From 7c4430d240f75b570f1f850daa05e7793b79b63e Mon Sep 17 00:00:00 2001
From: Denozordec <shatskiy.blog@gmail.com>
Date: Sun, 18 Oct 2026 01:58:31 +0700
Subject: [PATCH] =?UTF-8?q?chore(web):=20=D0=BE=D0=B1=D0=BD=D0=BE=D0=B2?=
 =?UTF-8?q?=D0=B8=D1=82=D1=8C=20=D0=BA=D0=BE=D0=BC=D0=BF=D0=BE=D0=BD=D0=B5?=
 =?UTF-8?q?=D0=BD=D1=82=D1=8B=20ReUI=20=D0=B8=20=D0=BF=D0=B5=D1=80=D0=B5?=
 =?UTF-8?q?=D0=B9=D1=82=D0=B8=20=D0=BD=D0=B0=20TanStack=20Table=20v9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Обновлены из реестра data-grid, filters, badge, frame, alert, icon-tile, icon-stack,
timeline и зависимые примитивы @authportal/ui. @tanstack/react-table 8.21 → 9.3,
добавлены dnd-kit, react-virtual, date-fns. Фильтры AdminUsersGrid переведены на
дерево FilterQuery, таблицы — на useTable + dataGridFeatures. Русские подписи вынесены
в lib/reui-ru.ts. Импорты cn из реестра заменены на @authportal/ui/lib/utils.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .gitignore                                    |    1 +
 apps/web/package.json                         |    8 +-
 .../components/reui-kit/admin-users-grid.tsx  |  292 +-
 .../reui/cascader/cascader-async.tsx          |  926 +++++
 .../reui/cascader/cascader-columns.tsx        |  274 ++
 .../reui/cascader/cascader-context.tsx        |  326 ++
 .../reui/cascader/cascader-footer.tsx         |  731 ++++
 .../reui/cascader/cascader-i18n.tsx           |   92 +
 .../reui/cascader/cascader-item.tsx           | 1082 ++++++
 .../components/reui/cascader/cascader-lib.tsx | 1012 ++++++
 .../components/reui/cascader/cascader-nav.tsx |  649 ++++
 .../reui/cascader/cascader-types.tsx          |  220 ++
 .../reui/cascader/cascader-virtual.tsx        |  470 +++
 .../src/components/reui/cascader/cascader.tsx | 3066 +++++++++++++++++
 .../data-grid/data-grid-cell-selection.tsx    | 2610 ++++++++++++++
 .../data-grid/data-grid-column-filter.tsx     |   21 +-
 .../data-grid/data-grid-column-header.tsx     |  262 +-
 .../data-grid/data-grid-column-visibility.tsx |   28 +-
 .../reui/data-grid/data-grid-i18n.tsx         |   99 +
 .../reui/data-grid/data-grid-pagination.tsx   |  266 +-
 .../reui/data-grid/data-grid-scroll-area.tsx  |  332 +-
 .../data-grid/data-grid-table-dnd-rows.tsx    |  823 +++++
 .../reui/data-grid/data-grid-table-dnd.tsx    |  551 +++
 .../data-grid/data-grid-table-virtual.tsx     | 1220 +++++++
 .../reui/data-grid/data-grid-table.tsx        | 2480 ++++++++++---
 .../components/reui/data-grid/data-grid.tsx   | 1206 ++++++-
 apps/web/src/components/reui/filters.tsx      | 1927 -----------
 .../reui/filters/filters-advanced.tsx         | 2081 +++++++++++
 .../reui/filters/filters-builder.tsx          |  303 ++
 .../components/reui/filters/filters-chip.tsx  | 1069 ++++++
 .../reui/filters/filters-context.tsx          |  662 ++++
 .../components/reui/filters/filters-date.tsx  |  213 ++
 .../components/reui/filters/filters-dnd.tsx   |  700 ++++
 .../components/reui/filters/filters-draft.tsx |  187 +
 .../reui/filters/filters-editors.tsx          | 1341 +++++++
 .../components/reui/filters/filters-i18n.tsx  |  151 +
 .../components/reui/filters/filters-lib.tsx   |  539 +++
 .../reui/filters/filters-operators.tsx        |  227 ++
 .../components/reui/filters/filters-query.tsx |  701 ++++
 .../components/reui/filters/filters-types.tsx |  566 +++
 .../src/components/reui/filters/filters.tsx   | 1228 +++++++
 apps/web/src/components/reui/frame.tsx        |   61 +-
 apps/web/src/components/reui/icon-tile.tsx    |   15 +-
 apps/web/src/design-preview/section-grid.tsx  |   24 +-
 apps/web/src/lib/reui-ru.ts                   |   79 +
 apps/web/src/routes/_auth.admin.logins.tsx    |   27 +-
 apps/web/tsconfig.app.json                    |    6 +-
 packages/ui/src/components/button-group.tsx   |    2 +-
 packages/ui/src/components/button.tsx         |    1 -
 packages/ui/src/components/checkbox.tsx       |    5 +-
 packages/ui/src/components/dropdown-menu.tsx  |    1 -
 packages/ui/src/components/input.tsx          |    1 -
 packages/ui/src/components/popover.tsx        |    1 -
 packages/ui/src/components/scroll-area.tsx    |    4 +-
 packages/ui/src/components/select.tsx         |    3 -
 packages/ui/src/components/separator.tsx      |    3 +-
 packages/ui/src/components/tooltip.tsx        |    3 +-
 pnpm-lock.yaml                                |  207 +-
 58 files changed, 28252 insertions(+), 3133 deletions(-)
 create mode 100644 apps/web/src/components/reui/cascader/cascader-async.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader-columns.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader-context.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader-footer.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader-i18n.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader-item.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader-lib.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader-nav.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader-types.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader-virtual.tsx
 create mode 100644 apps/web/src/components/reui/cascader/cascader.tsx
 create mode 100644 apps/web/src/components/reui/data-grid/data-grid-cell-selection.tsx
 create mode 100644 apps/web/src/components/reui/data-grid/data-grid-i18n.tsx
 create mode 100644 apps/web/src/components/reui/data-grid/data-grid-table-dnd-rows.tsx
 create mode 100644 apps/web/src/components/reui/data-grid/data-grid-table-dnd.tsx
 create mode 100644 apps/web/src/components/reui/data-grid/data-grid-table-virtual.tsx
 delete mode 100644 apps/web/src/components/reui/filters.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-advanced.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-builder.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-chip.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-context.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-date.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-dnd.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-draft.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-editors.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-i18n.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-lib.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-operators.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-query.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters-types.tsx
 create mode 100644 apps/web/src/components/reui/filters/filters.tsx
 create mode 100644 apps/web/src/lib/reui-ru.ts

diff --git a/.gitignore b/.gitignore
index 1bd84a8..b45eefc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,3 +35,4 @@ version.txt
 .codegraph/daemon.pid
 .release-version
 CHANGELOG.md
+.claude/settings.local.json
diff --git a/apps/web/package.json b/apps/web/package.json
index 3408846..764720c 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -16,6 +16,10 @@
     "@authportal/shared": "workspace:*",
     "@authportal/ui": "workspace:*",
     "@base-ui/react": "^1.5.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/modifiers": "^9.0.0",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@fontsource-variable/geist": "^5.3.0",
     "@fontsource-variable/geist-mono": "^5.3.0",
     "@hookform/resolvers": "^5.4.0",
@@ -23,9 +27,11 @@
     "@tailwindcss/vite": "^4.3.1",
     "@tanstack/react-query": "^5.101.0",
     "@tanstack/react-router": "^1.170.15",
-    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-table": "^9.3.1",
+    "@tanstack/react-virtual": "^3.14.21",
     "@tanstack/router-vite-plugin": "^1.167.18",
     "class-variance-authority": "^0.7.1",
+    "date-fns": "^4.4.0",
     "lucide-react": "catalog:",
     "next-themes": "^0.4.6",
     "react": "^19.2.6",
diff --git a/apps/web/src/components/reui-kit/admin-users-grid.tsx b/apps/web/src/components/reui-kit/admin-users-grid.tsx
index 72a3072..c127834 100644
--- a/apps/web/src/components/reui-kit/admin-users-grid.tsx
+++ b/apps/web/src/components/reui-kit/admin-users-grid.tsx
@@ -3,9 +3,8 @@
  * Preview: https://reui.io/preview/base/solution-users-1
  * Docs: https://reui.io/docs/components/base/filters · https://reui.io/docs/components/base/data-grid
  */
-import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { memo, useCallback, useMemo, useRef, useState } from 'react'
 import type { AdminUser, AppId } from '@authportal/shared'
-import { APPS } from '@authportal/shared'
 import {
   CircleDotIcon,
   FilterIcon,
@@ -25,20 +24,16 @@ import {
   UserPlusIcon,
 } from 'lucide-react'
 import {
-  getCoreRowModel,
-  getFilteredRowModel,
-  getPaginationRowModel,
-  getSortedRowModel,
   type ColumnDef,
   type PaginationState,
   type Row,
   type RowSelectionState,
   type SortingState,
-  type VisibilityState,
-  useReactTable,
+  type ColumnVisibilityState,
+  useTable,
 } from '@tanstack/react-table'
 import { Badge } from '@/components/reui/badge'
-import { DataGrid } from '@/components/reui/data-grid/data-grid'
+import { DataGrid, dataGridFeatures, type DataGridFeatures } from '@/components/reui/data-grid/data-grid'
 import { DataGridColumnHeader } from '@/components/reui/data-grid/data-grid-column-header'
 import { DataGridColumnVisibility } from '@/components/reui/data-grid/data-grid-column-visibility'
 import { DataGridPagination } from '@/components/reui/data-grid/data-grid-pagination'
@@ -48,12 +43,17 @@ import {
   DataGridTableRowSelect,
   DataGridTableRowSelectAll,
 } from '@/components/reui/data-grid/data-grid-table'
+import { DATA_GRID_RU, FILTERS_RU, FILTER_OPERATORS_RU } from '@/lib/reui-ru'
+import { Filters } from '@/components/reui/filters/filters'
 import {
-  createFilter,
-  Filters,
-  type Filter,
-  type FilterFieldConfig,
-} from '@/components/reui/filters'
+  createFilterQuery,
+  flattenFilterConditions,
+  type FilterCondition,
+} from '@/components/reui/filters/filters-query'
+import type {
+  FilterField,
+  FilterQuery,
+} from '@/components/reui/filters/filters-types'
 import {
   Frame,
   FrameDescription,
@@ -97,10 +97,6 @@ import { Separator } from '@authportal/ui/components/separator'
 import { Skeleton } from '@authportal/ui/components/skeleton'
 import { TooltipProvider } from '@authportal/ui/components/tooltip'
 
-const APP_TITLE: Record<AppId, string> = Object.fromEntries(
-  APPS.map((app) => [app.id, app.title]),
-) as Record<AppId, string>
-
 const BULK_ROLE_OPTIONS = [
   { value: 'admin', label: 'Админ' },
   { value: 'user', label: 'Пользователь' },
@@ -121,28 +117,13 @@ export interface AdminUsersGridProps {
   onBulkDeactivate: (userIds: string[]) => void
 }
 
-function getActiveFilters(filters: Filter[]) {
-  return filters.filter((filter) => {
-    const { values } = filter
-    if (!values || values.length === 0) return false
-    if (
-      values.every((value) => typeof value === 'string' && value.trim() === '')
-    )
-      return false
-    if (values.every((value) => value === null || value === undefined))
-      return false
-    if (values.every((value) => Array.isArray(value) && value.length === 0))
-      return false
-    return true
-  })
-}
-
-function serializeActiveFiltersKey(active: Filter[]) {
+function serializeConditionsKey(conditions: FilterCondition[]) {
   return JSON.stringify(
-    active.map((f) => ({
-      field: f.field,
-      operator: f.operator,
-      values: f.values,
+    conditions.map((c) => ({
+      field: c.field,
+      operator: c.operator,
+      values: c.values,
+      negated: c.negated,
     })),
   )
 }
@@ -156,84 +137,47 @@ function filterFieldValue(item: AdminUser, field: string): unknown {
   return undefined
 }
 
-function applyFiltersToUsers(data: AdminUser[], filters: Filter[]): AdminUser[] {
-  const active = getActiveFilters(filters)
-  let result = [...data]
-  for (const filter of active) {
-    const { field, operator, values } = filter
-    result = result.filter((item) => {
-      if (field === 'apps') {
-        const selected = values.map(String)
-        switch (operator) {
-          case 'is':
-            return (
-              selected.length > 0 && item.apps.includes(selected[0] as AppId)
-            )
-          case 'is_any_of':
-            return selected.some((v) => item.apps.includes(v as AppId))
-          case 'is_not_any_of':
-            return !selected.some((v) => item.apps.includes(v as AppId))
-          case 'contains': {
-            const tokens = values.map((v) => String(v).trim()).filter(Boolean)
-            if (tokens.length === 0) return true
-            return tokens.some((token) =>
-              item.apps.some((appId) =>
-                APP_TITLE[appId].toLowerCase().includes(token.toLowerCase()),
-              ),
-            )
-          }
-          default:
-            return true
-        }
-      }
+function matchesCondition(item: AdminUser, condition: FilterCondition): boolean {
+  const { field, operator, values } = condition
+  const raw = filterFieldValue(item, field)
+  const fieldValue = raw != null ? String(raw) : ''
+  const lower = fieldValue.toLowerCase()
+  const tokens = values.map((v) => String(v).trim()).filter(Boolean)
 
-      const raw = filterFieldValue(item, field)
-      const fieldValue = raw != null ? raw : ''
-
-      switch (operator) {
-        case 'is':
-          return values.includes(fieldValue)
-        case 'is_not':
-          return !values.includes(fieldValue)
-        case 'is_any_of':
-          return values.some((v) => fieldValue === v)
-        case 'is_not_any_of':
-          return !values.some((v) => fieldValue === v)
-        case 'contains': {
-          const tokens = values.map((v) => String(v).trim()).filter(Boolean)
-          if (tokens.length === 0) return true
-          return tokens.some((token) =>
-            String(fieldValue).toLowerCase().includes(token.toLowerCase()),
-          )
-        }
-        case 'not_contains':
-          return !values.some((v) =>
-            String(fieldValue).toLowerCase().includes(String(v).toLowerCase()),
-          )
-        case 'starts_with':
-          return values.some((v) =>
-            String(fieldValue)
-              .toLowerCase()
-              .startsWith(String(v).toLowerCase()),
-          )
-        case 'ends_with':
-          return values.some((v) =>
-            String(fieldValue).toLowerCase().endsWith(String(v).toLowerCase()),
-          )
-        case 'empty':
-          return fieldValue === '' || fieldValue == null
-        case 'not_empty':
-          return fieldValue !== '' && fieldValue != null
-        default:
-          return true
-      }
-    })
+  switch (operator) {
+    case 'is':
+      return values.map(String).includes(fieldValue)
+    case 'is_not':
+      return !values.map(String).includes(fieldValue)
+    case 'is_any_of':
+      return values.map(String).includes(fieldValue)
+    case 'is_none_of':
+      return !values.map(String).includes(fieldValue)
+    case 'contains':
+      return tokens.length === 0 || tokens.some((t) => lower.includes(t.toLowerCase()))
+    case 'not_contains':
+      return !tokens.some((t) => lower.includes(t.toLowerCase()))
+    case 'starts_with':
+      return tokens.some((t) => lower.startsWith(t.toLowerCase()))
+    case 'ends_with':
+      return tokens.some((t) => lower.endsWith(t.toLowerCase()))
+    case 'empty':
+      return fieldValue === ''
+    case 'not_empty':
+      return fieldValue !== ''
+    default:
+      return true
   }
-  return result
 }
 
-function createDefaultFilters(): Filter[] {
-  return [createFilter('name', 'contains', [''])]
+function applyConditionsToUsers(data: AdminUser[], conditions: FilterCondition[]): AdminUser[] {
+  if (conditions.length === 0) return data
+  return data.filter((item) =>
+    conditions.every((c) => {
+      const hit = matchesCondition(item, c)
+      return c.negated ? !hit : hit
+    }),
+  )
 }
 
 function userInitials(name: string, email: string) {
@@ -257,12 +201,6 @@ function formatLastActive(iso: string | null) {
   }).format(date)
 }
 
-function renderSelectedCount(values: unknown[]) {
-  if (values.length === 0) return 'Выберите…'
-  if (values.length > 1) return `${values.length} выбрано`
-  return null
-}
-
 function DotSeparator() {
   return (
     <span
@@ -309,7 +247,7 @@ const AppTags = memo(function AppTags({ apps }: { apps: AppId[] }) {
   )
 })
 
-const MemberCell = memo(function MemberCell({ row }: { row: Row<AdminUser> }) {
+const MemberCell = memo(function MemberCell({ row }: { row: Row<DataGridFeatures, AdminUser> }) {
   const user = row.original
   return (
     <div className="flex min-w-0 items-center gap-2">
@@ -407,7 +345,7 @@ function ActionsCell({
   onDelete,
   onResetPasskeys,
 }: {
-  row: Row<AdminUser>
+  row: Row<DataGridFeatures, AdminUser>
   onOpenAudit: (user: AdminUser) => void
   onOpenAccess: (user: AdminUser) => void
   onDeactivate: (user: AdminUser) => void
@@ -526,7 +464,7 @@ function createAdminUserColumns(handlers: {
   onDeactivate: (user: AdminUser) => void
   onDelete: (user: AdminUser) => void
   onResetPasskeys: (user: AdminUser) => void
-}): ColumnDef<AdminUser>[] {
+}): ColumnDef<DataGridFeatures, AdminUser>[] {
   return [
     {
       id: 'select',
@@ -766,15 +704,11 @@ export function AdminUsersGrid({
   const [sorting, setSorting] = useState<SortingState>([
     { id: 'name', desc: false },
   ])
-  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
+  const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>({})
   const [rowSelection, setRowSelection] = useState<RowSelectionState>({})
-  const [filters, setFilters] = useState<Filter[]>(createDefaultFilters)
+  const [query, setQuery] = useState<FilterQuery>(() => createFilterQuery())
   const [bulkRole, setBulkRole] = useState<BulkRole>('user')
-  const [filteredData, setFilteredData] = useState<AdminUser[]>(users)
-  const isInitialLoad = useRef(true)
-  const lastAppliedActiveKey = useRef<string>(
-    serializeActiveFiltersKey(getActiveFilters(createDefaultFilters())),
-  )
+  const lastAppliedKey = useRef<string>(serializeConditionsKey([]))
 
   const stats = useMemo(
     () => ({
@@ -785,95 +719,56 @@ export function AdminUsersGrid({
     [users],
   )
 
-  const filterFields: FilterFieldConfig[] = useMemo(
+  const filterFields: FilterField[] = useMemo(
     () => [
       {
-        key: 'name',
+        id: 'name',
         label: 'Участник',
         icon: <UserIcon className="size-3.5" aria-hidden />,
         type: 'text',
-        className: 'w-44',
         placeholder: 'Поиск…',
       },
       {
-        key: 'email',
+        id: 'email',
         label: 'Email',
         icon: <MailIcon className="size-3.5" aria-hidden />,
         type: 'text',
-        className: 'w-48',
         placeholder: 'Поиск…',
       },
       {
-        key: 'role',
+        id: 'role',
         label: 'Роль',
         icon: <ShieldCheckIcon className="size-3.5" aria-hidden />,
         type: 'select',
         searchable: false,
-        className: 'w-[160px]',
-        options: BULK_ROLE_OPTIONS.map((o) => ({
-          value: o.value,
-          label: o.label,
-        })),
-        customValueRenderer: (values) => {
-          const state = renderSelectedCount(values)
-          if (state) return state
-          return (
-            <RoleBadge isAdmin={(values[0] as BulkRole) === 'admin'} />
-          )
-        },
+        options: BULK_ROLE_OPTIONS.map((o) => ({ value: o.value, label: o.label })),
       },
       {
-        key: 'status',
+        id: 'status',
         label: 'Статус',
         icon: <CircleDotIcon className="size-3.5" aria-hidden />,
         type: 'select',
         searchable: false,
-        className: 'w-[150px]',
         options: [
           { value: 'active', label: 'Активен' },
           { value: 'disabled', label: 'Отключён' },
         ],
-        customValueRenderer: (values) => {
-          const state = renderSelectedCount(values)
-          if (state) return state
-          return (
-            <StatusBadge disabled={(values[0] as string) === 'disabled'} />
-          )
-        },
       },
     ],
     [],
   )
 
-  const applyFilters = useCallback(
-    (newFilters: Filter[]) => applyFiltersToUsers(users, newFilters),
-    [users],
-  )
+  const conditions = useMemo(() => flattenFilterConditions(query), [query])
+  const filteredData = useMemo(() => applyConditionsToUsers(users, conditions), [users, conditions])
 
-  const handleFiltersChange = useCallback(
-    (newFilters: Filter[]) => {
-      setFilters(newFilters)
-      const newActive = getActiveFilters(newFilters)
-      const nextKey = serializeActiveFiltersKey(newActive)
-      if (nextKey === lastAppliedActiveKey.current) return
-      lastAppliedActiveKey.current = nextKey
-      setPagination((prev) => ({ ...prev, pageIndex: 0 }))
-      setRowSelection({})
-    },
-    [],
-  )
-
-  useEffect(() => {
-    if (isInitialLoad.current) {
-      setFilteredData(applyFilters(filters))
-      isInitialLoad.current = false
-      return
-    }
-    setFilteredData(applyFilters(filters))
-    lastAppliedActiveKey.current = serializeActiveFiltersKey(
-      getActiveFilters(filters),
-    )
-  }, [users, filters, applyFilters])
+  const handleQueryChange = useCallback((next: FilterQuery) => {
+    setQuery(next)
+    const nextKey = serializeConditionsKey(flattenFilterConditions(next))
+    if (nextKey === lastAppliedKey.current) return
+    lastAppliedKey.current = nextKey
+    setPagination((prev) => ({ ...prev, pageIndex: 0 }))
+    setRowSelection({})
+  }, [])
 
   const columns = useMemo(
     () =>
@@ -891,7 +786,8 @@ export function AdminUsersGrid({
     () => columns.map((c) => c.id as string),
   )
 
-  const table = useReactTable({
+  const table = useTable({
+    features: dataGridFeatures,
     columns,
     data: filteredData,
     pageCount: Math.ceil(filteredData.length / pagination.pageSize),
@@ -910,17 +806,13 @@ export function AdminUsersGrid({
     onPaginationChange: setPagination,
     onSortingChange: setSorting,
     onRowSelectionChange: setRowSelection,
-    getCoreRowModel: getCoreRowModel(),
-    getFilteredRowModel: getFilteredRowModel(),
-    getPaginationRowModel: getPaginationRowModel(),
-    getSortedRowModel: getSortedRowModel(),
   })
 
   const selectedCount = table.getSelectedRowModel().rows.length
   const selectedIds = table
     .getSelectedRowModel()
     .rows.map((row) => row.original.id)
-  const showClearButton = filters.length > 0
+  const showClearButton = conditions.length > 0
   const gridLoading = isLoading
 
   const handleClearSelection = useCallback(() => setRowSelection({}), [])
@@ -938,11 +830,8 @@ export function AdminUsersGrid({
   }, [onBulkDeactivate, selectedCount, selectedIds])
 
   const handleClearFilters = useCallback(() => {
-    const next = createDefaultFilters()
-    lastAppliedActiveKey.current = serializeActiveFiltersKey(
-      getActiveFilters(next),
-    )
-    setFilters(next)
+    lastAppliedKey.current = serializeConditionsKey([])
+    setQuery(createFilterQuery())
     setRowSelection({})
   }, [])
 
@@ -950,6 +839,7 @@ export function AdminUsersGrid({
     <TooltipProvider delay={200}>
       <DataGrid
         table={table}
+        i18n={DATA_GRID_RU}
         isLoading={gridLoading}
         loadingMode="skeleton"
         recordCount={filteredData.length}
@@ -993,9 +883,11 @@ export function AdminUsersGrid({
           <FramePanel className="p-0 shadow-none">
             <div className="flex flex-wrap items-center justify-between gap-2 px-(--frame-panel-header-px) py-(--frame-panel-header-py)">
               <Filters
-                filters={filters}
+                query={query}
                 fields={filterFields}
-                onChange={handleFiltersChange}
+                onQueryChange={handleQueryChange}
+                labels={FILTERS_RU}
+                operatorLabels={FILTER_OPERATORS_RU}
                 size="default"
                 trigger={
                   <Button
@@ -1005,7 +897,7 @@ export function AdminUsersGrid({
                     aria-label="Фильтры"
                   >
                     <FilterIcon aria-hidden />
-                    Filters
+                    Фильтры
                   </Button>
                 }
               />
@@ -1020,7 +912,7 @@ export function AdminUsersGrid({
                     disabled={gridLoading}
                   >
                     <FunnelXIcon aria-hidden />
-                    Clear
+                    Сбросить
                   </Button>
                 ) : null}
                 <DataGridColumnVisibility
@@ -1033,7 +925,7 @@ export function AdminUsersGrid({
                       aria-label="Настройки таблицы"
                     >
                       <Settings2Icon aria-hidden="true" />
-                      View settings
+                      Колонки
                     </Button>
                   }
                 />
diff --git a/apps/web/src/components/reui/cascader/cascader-async.tsx b/apps/web/src/components/reui/cascader/cascader-async.tsx
new file mode 100644
index 0000000..47dcfba
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-async.tsx
@@ -0,0 +1,926 @@
+import * as React from "react"
+import { useCascaderState } from "@/components/reui/cascader/cascader-context"
+import {
+  CASCADER_ROOT_KEY,
+  isCascaderMoreNode,
+} from "@/components/reui/cascader/cascader-lib"
+import type {
+  CascaderIndex,
+  CascaderLoadContext,
+  CascaderLoadReason,
+  CascaderLoadResult,
+  CascaderLoadState,
+  CascaderNode,
+  CascaderSearchContext,
+} from "@/components/reui/cascader/cascader-types"
+
+/**
+ * Async data for the cascader. Loaded pages live in their own store and are
+ * MERGED onto the index built from `items`, never folded into that build:
+ * `items` changes identity on any parent re-render, and folding would discard
+ * every level the user drilled into. Map membership is the load discriminator:
+ * no `states` entry means never fetched, while an entry with no `loading`, no
+ * `error` and no children means empty for real.
+ */
+
+/* -------------------------------------------------------------------------- */
+/*                                    Types                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Fetches one level. `node` is `null` for the root level, and only
+ * `{ value, label: value }`, no `data`, for a level on screen whose node has
+ * not loaded: a deep link before the level above loads, or a page-loaded
+ * level after a `loadKey` change.
+ */
+export type CascaderGetChildren<T = unknown> = (
+  node: CascaderNode<T> | null,
+  context: CascaderLoadContext
+) =>
+  | CascaderNode<T>[]
+  | CascaderLoadResult<T>
+  | Promise<CascaderNode<T>[] | CascaderLoadResult<T>>
+
+/** Server-side search, replacing the local index scan while the query is set. */
+export type CascaderOnSearch<T = unknown> = (
+  query: string,
+  context: CascaderSearchContext
+) =>
+  | CascaderNode<T>[]
+  | CascaderLoadResult<T>
+  | Promise<CascaderNode<T>[] | CascaderLoadResult<T>>
+
+/** Resolves a selected value to its ancestor chain, root first, node last. */
+export type CascaderResolveValue<T = unknown> = (
+  value: string,
+  context: CascaderLoadContext
+) => CascaderNode<T>[] | Promise<CascaderNode<T>[]>
+
+export interface CascaderLoaderStore<T = unknown> {
+  /** Keyed by LEVEL: a parent's value, or `CASCADER_ROOT_KEY` for the root. */
+  pages: Map<string, CascaderNode<T>[]>
+  states: Map<string, CascaderLoadState>
+  /** Keyed by node value: search hits and resolved selections, level-less. */
+  detached: Map<string, CascaderNode<T>>
+  /**
+   * A resolved chain's parent links, node value to level key. Kept apart from
+   * `pages`: a level's first real page replaced a chain stub there, and a node
+   * that page left out lost its parent, and the trigger its path.
+   */
+  links: Map<string, string>
+}
+
+export interface UseCascaderLoaderOptions<T = unknown> {
+  /** The index built from `items`, before any pages are merged in. */
+  base: CascaderIndex<T>
+  getChildren?: CascaderGetChildren<T>
+  onSearch?: CascaderOnSearch<T>
+  resolveValue?: CascaderResolveValue<T>
+  /** Milliseconds of quiet before `onSearch` fires. */
+  searchDebounce?: number
+  /** Changing this drops every cached page, state and detached node. */
+  loadKey?: unknown
+  /** Speculatively fetch a branch's children when it is highlighted. */
+  prefetch?: boolean
+  /** Called when a request fails. Never for an aborted or superseded one. */
+  onLoadError?: (
+    error: unknown,
+    context: { parent: string | null; reason: string }
+  ) => void
+  /**
+   * Whether the panel is live: the popup is open, or the cascader is inline.
+   * Gates levels, paging and search. `resolveValue` runs regardless, and
+   * retries a failed value when this turns true.
+   */
+  enabled: boolean
+  query: string
+  /** Level keys that are currently on screen. Root is `CASCADER_ROOT_KEY`. */
+  levels: string[]
+  /** Handed to `onSearch` as its scope and read for nothing else: the
+   * navigation path, or `[]` when the search covers the whole tree. */
+  path: string[]
+  /** Current selection, for `resolveValue`. */
+  values: string[]
+}
+
+export interface CascaderLoader<T = unknown> {
+  /** Whether a `getChildren` loader is configured at all. */
+  active: boolean
+  store: CascaderLoaderStore<T>
+  states: ReadonlyMap<string, CascaderLoadState>
+  /**
+   * Async search hits, `null` when no `onSearch` is running. EMPTY while the
+   * first request is in flight, so the level behind is not shown as the answer.
+   */
+  searchResults: CascaderNode<T>[] | null
+  searchState: CascaderLoadState | null
+  /**
+   * Fetches a level's FIRST page. No-ops on a `states` entry (in flight,
+   * loaded or failed) or when `items` fills the level. The level effect fires
+   * only for on-screen levels, so a branch merely PRESSED is asked for by hand.
+   */
+  ensureLevel: (parentKey: string, reason: CascaderLoadReason) => void
+  /** Fetches the next page of a level. No-ops unless one is available. */
+  loadMore: (parentKey: string) => void
+  /** Refires a failed level. No-ops unless that level is in an error state. */
+  retryLevel: (parentKey: string) => void
+  /** Refires the server search for the current query. No-ops without one. */
+  retrySearch: () => void
+  /** Schedules a speculative fetch. Safe to call on every highlight move. */
+  prefetchNode: (node: CascaderNode<T> | null | undefined) => void
+  /**
+   * Evicts ONE level: aborts its request, drops its `states`/`pages` entries
+   * and paging latch, so the level effect refetches it. `null` = root level.
+   */
+  invalidateLevel: (value: string | null) => void
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Constants                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Highlight dwell before `prefetch` fetches: long enough that holding ArrowDown
+ * does not fire a request per row, short enough to beat the ArrowRight press.
+ */
+const PREFETCH_DELAY = 150
+
+/** Request keys for the two non-level requests. Never collide with a value. */
+const SEARCH_KEY = "\u0000search"
+const RESOLVE_PREFIX = "\u0000resolve:"
+
+const NO_STATE: CascaderLoadState = {
+  loading: false,
+  error: false,
+  hasMore: false,
+}
+
+/** Stable empty result, so an idle search never churns the state context. */
+const NO_RESULTS: CascaderNode<never>[] = []
+
+function createStore<T>(): CascaderLoaderStore<T> {
+  return {
+    pages: new Map(),
+    states: new Map(),
+    detached: new Map(),
+    links: new Map(),
+  }
+}
+
+function sameLoadState(a: CascaderLoadState, b: CascaderLoadState): boolean {
+  return (
+    a.loading === b.loading &&
+    a.error === b.error &&
+    a.hasMore === b.hasMore &&
+    a.cursor === b.cursor
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Store transitions                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Copy-on-write, and a NO-OP when nothing changed: the merged index is memoised
+ * on store identity, so a fresh object for an unchanged state would rebuild it.
+ */
+function withLoadState<T>(
+  store: CascaderLoaderStore<T>,
+  key: string,
+  update: (state: CascaderLoadState) => CascaderLoadState
+): CascaderLoaderStore<T> {
+  const current = store.states.get(key) ?? NO_STATE
+  const next = update(current)
+  if (store.states.has(key) && sameLoadState(current, next)) return store
+  const states = new Map(store.states)
+  states.set(key, next)
+  return { ...store, states }
+}
+
+function withPage<T>(
+  store: CascaderLoaderStore<T>,
+  key: string,
+  items: readonly CascaderNode<T>[],
+  options: { append: boolean; hasMore: boolean; cursor?: string }
+): CascaderLoaderStore<T> {
+  const previous = options.append ? (store.pages.get(key) ?? []) : []
+  const seen = new Set(previous.map((node) => node.value))
+  const merged = previous.slice()
+  for (const item of items) {
+    if (seen.has(item.value)) continue
+    seen.add(item.value)
+    merged.push(item)
+  }
+
+  const pages = new Map(store.pages)
+  pages.set(key, merged)
+  const states = new Map(store.states)
+  states.set(key, {
+    loading: false,
+    error: false,
+    hasMore: options.hasMore,
+    cursor: options.cursor,
+  })
+  return { ...store, pages, states }
+}
+
+function withDetached<T>(
+  store: CascaderLoaderStore<T>,
+  items: readonly CascaderNode<T>[]
+): CascaderLoaderStore<T> {
+  let detached: Map<string, CascaderNode<T>> | null = null
+  for (const item of items) {
+    if (store.detached.get(item.value) === item) continue
+    detached = detached ?? new Map(store.detached)
+    detached.set(item.value, item)
+  }
+  if (!detached) return store
+  return { ...store, detached }
+}
+
+/**
+ * Records a resolved ancestor chain, root first, as `detached` nodes plus
+ * `links`, never as rows in `pages`: a stub there made an unloaded level read
+ * as loaded. Writes no `states`, so every level on it still fetches for real.
+ */
+function withChain<T>(
+  store: CascaderLoaderStore<T>,
+  chain: readonly CascaderNode<T>[]
+): CascaderLoaderStore<T> {
+  if (chain.length === 0) return store
+  const detached = new Map(store.detached)
+  const links = new Map(store.links)
+  let parentKey = CASCADER_ROOT_KEY
+
+  for (const node of chain) {
+    detached.set(node.value, node)
+    links.set(node.value, parentKey)
+    parentKey = node.value
+  }
+
+  return { ...store, detached, links }
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Hook                                    */
+/* -------------------------------------------------------------------------- */
+
+interface CascaderLoaderLatest<T> {
+  base: CascaderIndex<T>
+  store: CascaderLoaderStore<T>
+  getChildren?: CascaderGetChildren<T>
+  onSearch?: CascaderOnSearch<T>
+  resolveValue?: CascaderResolveValue<T>
+  onLoadError?: (
+    error: unknown,
+    context: { parent: string | null; reason: string }
+  ) => void
+  prefetch: boolean
+  path: string[]
+  query: string
+}
+
+interface CascaderSearchSlice<T> {
+  query: string
+  results: CascaderNode<T>[]
+  loading: boolean
+  error: boolean
+}
+
+/**
+ * The loader. A SIBLING of the `buildCascaderIndex` memo, never inside it: the
+ * build stays pure in `items`, the merge pure in that build plus this store.
+ */
+export function useCascaderLoader<T = unknown>({
+  base,
+  getChildren,
+  onSearch,
+  resolveValue,
+  searchDebounce = 250,
+  loadKey,
+  prefetch = false,
+  onLoadError,
+  enabled,
+  query,
+  levels,
+  path,
+  values,
+}: UseCascaderLoaderOptions<T>): CascaderLoader<T> {
+  const [store, setStore] = React.useState<CascaderLoaderStore<T>>(createStore)
+  const [search, setSearch] = React.useState<CascaderSearchSlice<T> | null>(
+    null
+  )
+
+  /**
+   * Latest callbacks, WRITTEN IN AN EFFECT: `getChildren` is inline in most
+   * consumers, so closing over it would refire every in-flight request per
+   * re-render. The ref is what keeps the request machinery `[]`-dep. Declared
+   * FIRST, since effects run in declaration order, so the level effect below
+   * already sees the current commit.
+   */
+  const latest = React.useRef<CascaderLoaderLatest<T>>({
+    base,
+    store,
+    getChildren,
+    onSearch,
+    resolveValue,
+    onLoadError,
+    prefetch,
+    path,
+    query,
+  })
+
+  React.useEffect(() => {
+    latest.current = {
+      base,
+      store,
+      getChildren,
+      onSearch,
+      resolveValue,
+      onLoadError,
+      prefetch,
+      path,
+      query,
+    }
+  })
+
+  /** One AbortController PER KEY: columns mode runs several levels at once. */
+  const controllers = React.useRef(new Map<string, AbortController>())
+  /** Monotonic per key. The stale guard for out-of-order responses. */
+  const requestIds = React.useRef(new Map<string, number>())
+  /** In-flight `(level, cursor)` signatures, so a duplicate ask is free. */
+  const inflight = React.useRef(new Map<string, string>())
+  /**
+   * The `(child count, cursor)` signature at the last paging fire, per level.
+   * Guards what `hasMore` cannot: a page of zero new items while the server
+   * still says `hasMore`. Cursor is IN the signature because an all-duplicates
+   * page advances it while the count stands still - real progress, which a
+   * count-only latch would brick forever.
+   */
+  const moreLatch = React.useRef(new Map<string, string>())
+  /** Values `resolveValue` has already been asked about, so it asks once. */
+  const attempted = React.useRef(new Set<string>())
+  /**
+   * Values whose resolve failed. They stay `attempted` until the next open
+   * rather than the next values pass: with inline `items` every parent render
+   * is one, and an `onLoadError` that set parent state looped at network speed.
+   */
+  const failed = React.useRef(new Set<string>())
+  /** Every node the loader has seen, so a level key can name its own node. */
+  const known = React.useRef(new Map<string, CascaderNode<T>>())
+  const timers = React.useRef<{
+    prefetch: ReturnType<typeof setTimeout> | null
+  }>({ prefetch: null })
+  /** Bumped by a `loadKey` change, so responses from before it are dropped. */
+  const epoch = React.useRef(0)
+
+  const remember = React.useCallback((nodes: readonly CascaderNode<T>[]) => {
+    const map = known.current
+    const walk = (list: readonly CascaderNode<T>[]) => {
+      for (const node of list) {
+        map.set(node.value, node)
+        if (node.children?.length) walk(node.children)
+      }
+    }
+    walk(nodes)
+  }, [])
+
+  const abortKey = React.useCallback((key: string) => {
+    const controller = controllers.current.get(key)
+    if (!controller) return
+    controllers.current.delete(key)
+    inflight.current.delete(key)
+    controller.abort()
+  }, [])
+
+  /* ------------------------------- level load ------------------------------ */
+
+  const runLoad = React.useCallback(
+    (
+      key: string,
+      reason: CascaderLoadReason,
+      cursor: string | undefined,
+      append: boolean
+    ) => {
+      const { getChildren: loader, base: currentBase } = latest.current
+      if (!loader) return
+
+      const signature = `${append ? "1" : "0"}:${cursor ?? ""}`
+      if (inflight.current.get(key) === signature) return
+
+      abortKey(key)
+      const controller = new AbortController()
+      controllers.current.set(key, controller)
+      inflight.current.set(key, signature)
+
+      const requestId = (requestIds.current.get(key) ?? 0) + 1
+      requestIds.current.set(key, requestId)
+      const startEpoch = epoch.current
+
+      // A deep link (`path`, `expanded`) can put a level on screen before the
+      // level above it loads, and a `loadKey` reset forgets every node. `null`
+      // is the ROOT's argument, and a loader answered it with the root rows,
+      // so the level gets its value instead.
+      const node =
+        key === CASCADER_ROOT_KEY
+          ? null
+          : (currentBase.byValue.get(key) ??
+            known.current.get(key) ?? { value: key, label: key })
+
+      setStore((prev) =>
+        withLoadState(prev, key, (state) => ({
+          ...state,
+          loading: true,
+          error: false,
+        }))
+      )
+
+      const settle = () => {
+        if (inflight.current.get(key) === signature)
+          inflight.current.delete(key)
+        if (controllers.current.get(key) === controller) {
+          controllers.current.delete(key)
+        }
+      }
+
+      const stale = () =>
+        controller.signal.aborted ||
+        startEpoch !== epoch.current ||
+        requestId !== requestIds.current.get(key)
+
+      // `Promise.resolve().then(...)`, not a direct call: it normalises a
+      // SYNCHRONOUS throw into a rejection instead of taking the render down.
+      Promise.resolve()
+        .then(() => loader(node, { signal: controller.signal, cursor, reason }))
+        .then((result) => {
+          settle()
+          if (stale()) return
+          const items = Array.isArray(result) ? result : result.items
+          const nextCursor = Array.isArray(result)
+            ? undefined
+            : result.nextCursor
+          const hasMore = Array.isArray(result)
+            ? false
+            : (result.hasMore ?? nextCursor != null)
+
+          if (!append) moreLatch.current.delete(key)
+          remember(items)
+          setStore((prev) =>
+            withPage(prev, key, items, { append, hasMore, cursor: nextCursor })
+          )
+        })
+        .catch((error: unknown) => {
+          settle()
+          if (stale()) return
+          setStore((prev) =>
+            withLoadState(prev, key, (state) => ({
+              ...state,
+              loading: false,
+              error: true,
+            }))
+          )
+          // Behind the stale guard: an abort is navigation, not a failure.
+          latest.current.onLoadError?.(error, {
+            parent: key === CASCADER_ROOT_KEY ? null : key,
+            reason,
+          })
+        })
+    },
+    [abortKey, remember]
+  )
+
+  const ensureLevel = React.useCallback(
+    (key: string, reason: CascaderLoadReason) => {
+      const {
+        getChildren: loader,
+        store: current,
+        base: index,
+      } = latest.current
+      if (!loader) return
+      if (current.states.has(key)) return
+      // A level `items` already fills is not the loader's business: that is how
+      // a static root plus `getChildren` for the branches works with no flag.
+      if (index.childrenOf.has(key)) return
+      runLoad(key, reason, undefined, false)
+    },
+    [runLoad]
+  )
+
+  const loadMore = React.useCallback(
+    (key: string) => {
+      const { getChildren: loader, store: current } = latest.current
+      if (!loader) return
+      const state = current.states.get(key)
+      if (!state || state.loading || !state.hasMore) return
+
+      const loaded = current.pages.get(key)?.length ?? 0
+      const signature = `${loaded}:${state.cursor ?? ""}`
+      if (moreLatch.current.get(key) === signature) return
+      moreLatch.current.set(key, signature)
+
+      runLoad(key, "more", state.cursor, true)
+    },
+    [runLoad]
+  )
+
+  const retryLevel = React.useCallback(
+    (key: string) => {
+      const { getChildren: loader, store: current } = latest.current
+      if (!loader) return
+      const state = current.states.get(key)
+      if (!state?.error) return
+
+      const loaded = current.pages.get(key)?.length ?? 0
+      // A retry must be able to re-fire the page the latch just blocked.
+      moreLatch.current.delete(key)
+      runLoad(key, "retry", loaded > 0 ? state.cursor : undefined, loaded > 0)
+    },
+    [runLoad]
+  )
+
+  /**
+   * `detached` and `links` are deliberately untouched: chains and search hits
+   * belong to no level, and the trigger needs their path while the new page is
+   * in flight.
+   */
+  const invalidateLevel = React.useCallback(
+    (value: string | null) => {
+      const key = value ?? CASCADER_ROOT_KEY
+      abortKey(key)
+      // Bump the id too: a response past its signal check must still be stale.
+      requestIds.current.set(key, (requestIds.current.get(key) ?? 0) + 1)
+      moreLatch.current.delete(key)
+      setStore((prev) => {
+        if (!prev.states.has(key) && !prev.pages.has(key)) return prev
+        const states = new Map(prev.states)
+        states.delete(key)
+        const pages = new Map(prev.pages)
+        pages.delete(key)
+        return { ...prev, pages, states }
+      })
+    },
+    [abortKey]
+  )
+
+  const prefetchNode = React.useCallback(
+    (node: CascaderNode<T> | null | undefined) => {
+      const {
+        prefetch: on,
+        getChildren: loader,
+        store: current,
+      } = latest.current
+      if (!on || !loader || !node) return
+      if (isCascaderMoreNode(node)) return
+      if (!node.hasChildren) return
+      if (current.states.has(node.value)) return
+
+      const holder = timers.current
+      if (holder.prefetch) clearTimeout(holder.prefetch)
+      // A TIMEOUT, not a direct call: `onItemHighlighted` fires from a layout
+      // effect, where a synchronous setState is a render-phase cascade.
+      holder.prefetch = setTimeout(() => {
+        holder.prefetch = null
+        ensureLevel(node.value, "prefetch")
+      }, PREFETCH_DELAY)
+    },
+    [ensureLevel]
+  )
+
+  /* --------------------------------- search -------------------------------- */
+
+  const runSearch = React.useCallback(
+    (text: string) => {
+      const { onSearch: searcher, path: currentPath } = latest.current
+      if (!searcher) return
+
+      abortKey(SEARCH_KEY)
+      const controller = new AbortController()
+      controllers.current.set(SEARCH_KEY, controller)
+      const requestId = (requestIds.current.get(SEARCH_KEY) ?? 0) + 1
+      requestIds.current.set(SEARCH_KEY, requestId)
+      const startEpoch = epoch.current
+
+      setSearch((prev) => ({
+        query: text,
+        results: prev?.results ?? [],
+        loading: true,
+        error: false,
+      }))
+
+      const settle = () => {
+        if (controllers.current.get(SEARCH_KEY) === controller) {
+          controllers.current.delete(SEARCH_KEY)
+        }
+      }
+      const stale = () =>
+        controller.signal.aborted ||
+        startEpoch !== epoch.current ||
+        requestId !== requestIds.current.get(SEARCH_KEY)
+
+      Promise.resolve()
+        .then(() =>
+          searcher(text, { signal: controller.signal, path: currentPath })
+        )
+        .then((result) => {
+          settle()
+          if (stale()) return
+          const items = Array.isArray(result) ? result : result.items
+          remember(items)
+          // Search hits go to `detached`, never a level: a hit lives anywhere in
+          // the tree, and filing it under the open level would misplace it.
+          setStore((prev) => withDetached(prev, items))
+          setSearch({
+            query: text,
+            results: items,
+            loading: false,
+            error: false,
+          })
+        })
+        .catch((error: unknown) => {
+          settle()
+          if (stale()) return
+          setSearch((prev) => ({
+            query: text,
+            results: prev?.results ?? [],
+            loading: false,
+            error: true,
+          }))
+          latest.current.onLoadError?.(error, {
+            parent: null,
+            reason: "search",
+          })
+        })
+    },
+    [abortKey, remember]
+  )
+
+  const retrySearch = React.useCallback(() => {
+    const text = latest.current.query.trim()
+    if (text) runSearch(text)
+  }, [runSearch])
+
+  /* --------------------------------- resolve ------------------------------- */
+
+  const runResolve = React.useCallback(
+    (value: string) => {
+      const { resolveValue: resolver } = latest.current
+      if (!resolver) return
+
+      const key = `${RESOLVE_PREFIX}${value}`
+      abortKey(key)
+      const controller = new AbortController()
+      controllers.current.set(key, controller)
+      const startEpoch = epoch.current
+
+      const settle = () => {
+        if (controllers.current.get(key) === controller) {
+          controllers.current.delete(key)
+        }
+      }
+
+      Promise.resolve()
+        .then(() =>
+          resolver(value, { signal: controller.signal, reason: "resolve" })
+        )
+        .then((chain) => {
+          settle()
+          if (controller.signal.aborted || startEpoch !== epoch.current) return
+          if (!chain?.length) return
+          remember(chain)
+          setStore((prev) => withChain(prev, chain))
+        })
+        .catch((error: unknown) => {
+          // Read BEFORE `settle`. A newer ask or a reset that replaced this
+          // request owns the value's retry, so only a live failure is parked.
+          const live = controllers.current.get(key) === controller
+          settle()
+          if (live) failed.current.add(value)
+          if (controller.signal.aborted || startEpoch !== epoch.current) return
+          latest.current.onLoadError?.(error, {
+            parent: null,
+            reason: "resolve",
+          })
+        })
+    },
+    [abortKey, remember]
+  )
+
+  /* --------------------------------- resets -------------------------------- */
+
+  // Aborts what the PANEL asked for. A resolve keeps running: it feeds the
+  // trigger, which shows with the popup closed.
+  const cancelPanel = React.useCallback(() => {
+    const keys = Array.from(controllers.current.keys()).filter(
+      (key) => !key.startsWith(RESOLVE_PREFIX)
+    )
+    for (const key of keys) {
+      controllers.current.get(key)?.abort()
+      controllers.current.delete(key)
+    }
+    inflight.current.clear()
+
+    const holder = timers.current
+    if (holder.prefetch) {
+      clearTimeout(holder.prefetch)
+      holder.prefetch = null
+    }
+    if (keys.length === 0) return
+
+    setStore((prev) => {
+      let states: Map<string, CascaderLoadState> | null = null
+      for (const key of keys) {
+        const state = prev.states.get(key)
+        if (!state?.loading) continue
+        states = states ?? new Map(prev.states)
+        if ((prev.pages.get(key)?.length ?? 0) > 0) {
+          states.set(key, { ...state, loading: false })
+        } else {
+          // No entry AT ALL: membership is what says "loaded", so a stranded
+          // `loading: true` would read as loaded-and-empty forever.
+          states.delete(key)
+        }
+      }
+      return states ? { ...prev, states } : prev
+    })
+    setSearch((prev) => (prev?.loading ? { ...prev, loading: false } : prev))
+  }, [])
+
+  // A `loadKey` change drops everything. Declared BEFORE the level effect, so
+  // a reset always lands before the levels are asked for again.
+  const loadKeyRef = React.useRef<{ key: unknown } | null>(null)
+  React.useEffect(() => {
+    const previous = loadKeyRef.current
+    loadKeyRef.current = { key: loadKey }
+    if (!previous || Object.is(previous.key, loadKey)) return
+
+    epoch.current += 1
+    for (const controller of controllers.current.values()) controller.abort()
+    controllers.current.clear()
+    inflight.current.clear()
+    // `requestIds` is deliberately NOT cleared: the ids are stale-response
+    // guards, not cache. Reusing an aborted predecessor's id would leave only
+    // the epoch bump and the abort to reject the old response; monotonic per
+    // key keeps all three guards independent. The unmount cleanup clears them.
+    moreLatch.current.clear()
+    attempted.current.clear()
+    failed.current.clear()
+    known.current.clear()
+
+    const holder = timers.current
+    if (holder.prefetch) {
+      clearTimeout(holder.prefetch)
+      holder.prefetch = null
+    }
+
+    setStore(createStore)
+    setSearch(null)
+  }, [loadKey])
+
+  // Closing the popup aborts the panel's requests but does NOT drop the cache:
+  // reopening onto an already-loaded level is the point of keeping it.
+  React.useEffect(() => {
+    if (enabled) return
+    if (controllers.current.size === 0) return
+    cancelPanel()
+  }, [enabled, cancelPanel])
+
+  React.useEffect(() => {
+    const active = controllers.current
+    const holder = timers.current
+    const pending = inflight.current
+    const ids = requestIds.current
+    const tried = attempted.current
+    const parked = failed.current
+    return () => {
+      for (const controller of active.values()) controller.abort()
+      active.clear()
+      // Cleared WITH the controllers, for StrictMode's dev remount: a stale
+      // inflight signature would make `runLoad` skip the refetch forever, and
+      // a value still marked as asked would never be resolved again. The
+      // aborted promises are stale-guarded, so emptying the ids is safe.
+      pending.clear()
+      ids.clear()
+      tried.clear()
+      parked.clear()
+      if (holder.prefetch) clearTimeout(holder.prefetch)
+    }
+  }, [])
+
+  /* ------------------------------- the effects ----------------------------- */
+
+  const hasLoader = typeof getChildren === "function"
+  const hasSearch = typeof onSearch === "function"
+  const hasResolve = typeof resolveValue === "function"
+  const trimmed = query.trim()
+
+  // Serialised so the effects key on CONTENT, not on the array identity.
+  const levelsKey = JSON.stringify(levels)
+  const valuesKey = JSON.stringify(values)
+
+  // THE load trigger: one declarative effect on the levels on screen, not a
+  // call from `pushLevel`/`navigate`, which a controlled `path` never touches.
+  React.useEffect(() => {
+    if (!enabled || !hasLoader) return
+    for (const key of levels) ensureLevel(key, "level")
+    // `levels` enters through `levelsKey`; `store` re-runs after a load lands.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, hasLoader, levelsKey, store, ensureLevel])
+
+  React.useEffect(() => {
+    if (!hasSearch) return undefined
+    if (!enabled || !trimmed) {
+      abortKey(SEARCH_KEY)
+      setSearch((prev) => (prev === null ? prev : null))
+      return undefined
+    }
+    const timer = setTimeout(() => runSearch(trimmed), searchDebounce)
+    return () => {
+      clearTimeout(timer)
+      abortKey(SEARCH_KEY)
+    }
+  }, [hasSearch, enabled, trimmed, searchDebounce, abortKey, runSearch])
+
+  // Opening is the retry point for a failed resolve: un-ask it here, and the
+  // values pass below, which also re-runs on `enabled`, asks again.
+  React.useEffect(() => {
+    if (!enabled || failed.current.size === 0) return
+    for (const value of failed.current) attempted.current.delete(value)
+    failed.current.clear()
+  }, [enabled])
+
+  // NOT gated on `enabled`: the trigger shows the selection with the popup
+  // closed, so a saved value is pathed on load, not on the first open.
+  // `loadKey` re-runs it, because the reset dropped every resolved chain.
+  React.useEffect(() => {
+    if (!hasResolve) return
+    for (const value of values) {
+      if (!value) continue
+      if (attempted.current.has(value)) continue
+      if (base.byValue.has(value) || known.current.has(value)) continue
+      attempted.current.add(value)
+      runResolve(value)
+    }
+    // `values` is depended on through `valuesKey`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, hasResolve, valuesKey, base, runResolve, loadKey])
+
+  /* -------------------------------- the value ------------------------------ */
+
+  const searchResults = React.useMemo(() => {
+    if (!hasSearch || !trimmed) return null
+    if (!search || search.query !== trimmed) {
+      return NO_RESULTS as CascaderNode<T>[]
+    }
+    return search.results
+  }, [hasSearch, trimmed, search])
+
+  const searchState = React.useMemo<CascaderLoadState | null>(() => {
+    if (!hasSearch || !trimmed) return null
+    const settled = search?.query === trimmed
+    return {
+      loading: !settled || !!search?.loading,
+      error: settled && !!search?.error,
+      hasMore: false,
+    }
+  }, [hasSearch, trimmed, search])
+
+  return React.useMemo(
+    () => ({
+      active: hasLoader,
+      store,
+      states: store.states,
+      searchResults,
+      searchState,
+      ensureLevel,
+      loadMore,
+      retryLevel,
+      retrySearch,
+      invalidateLevel,
+      prefetchNode,
+    }),
+    [
+      hasLoader,
+      store,
+      searchResults,
+      searchState,
+      ensureLevel,
+      loadMore,
+      retryLevel,
+      retrySearch,
+      invalidateLevel,
+      prefetchNode,
+    ]
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Consumers                                 */
+/* -------------------------------------------------------------------------- */
+
+/** One level's load state, `null` when never fetched. Omit for the root. */
+export function useCascaderLoadState(
+  parent?: string | null
+): CascaderLoadState | null {
+  const { loadStates } = useCascaderState()
+  return loadStates.get(parent ?? CASCADER_ROOT_KEY) ?? null
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader-columns.tsx b/apps/web/src/components/reui/cascader/cascader-columns.tsx
new file mode 100644
index 0000000..08ae023
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-columns.tsx
@@ -0,0 +1,274 @@
+"use client"
+
+import * as React from "react"
+import {
+  useCascaderActions,
+  useCascaderState,
+} from "@/components/reui/cascader/cascader-context"
+import type { CascaderColumn } from "@/components/reui/cascader/cascader-context"
+import {
+  CascaderItem,
+  getCascaderMoreProps,
+} from "@/components/reui/cascader/cascader-item"
+import {
+  CASCADER_LIST_HEIGHT_CLASS,
+  CASCADER_LIST_PAD_CLASS,
+  CASCADER_ROOT_KEY,
+  CASCADER_ROWS_CLASS,
+  CASCADER_SCROLL_CLASS,
+  focusCascaderHome,
+  warnCascaderOnce,
+} from "@/components/reui/cascader/cascader-lib"
+import { Combobox as ComboboxPrimitive } from "@base-ui/react"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { ScrollArea } from "@authportal/ui/components/scroll-area"
+import { LoaderCircleIcon } from "lucide-react"
+
+export interface CascaderColumnsProps extends Omit<
+  React.ComponentProps<"div">,
+  "children"
+> {
+  /** Width of each column. */
+  columnWidth?: number | string
+  /** Height CAP per column. Falls back to the root `maxHeight`, then 24rem. */
+  maxHeight?: number | string
+  /** Replaces the default panel; the seam a windowed column plugs into. */
+  children?: (column: CascaderColumn) => React.ReactNode
+}
+
+/**
+ * Miller columns: the open trail side by side, one panel per level. Only the
+ * DEEPEST column is a real listbox (Base UI owns exactly one list); the trail
+ * behind is plain buttons, which keeps one state machine instead of a second,
+ * 2D one. `CascaderInput` moves between columns with ArrowLeft/ArrowRight.
+ */
+function CascaderColumns({
+  className,
+  columnWidth = 220,
+  maxHeight: maxHeightProp,
+  children,
+  ...props
+}: CascaderColumnsProps) {
+  const { maxHeight, mode, labels } = useCascaderActions()
+  const { columns } = useCascaderState()
+
+  // Before the early return, so the hook count is the same in both modes.
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production") return
+    if (mode === "columns") return
+    warnCascaderOnce(
+      `columns-outside-columns-mode:${mode}`,
+      `\`CascaderColumns\` renders nothing in \`mode="${mode}"\`, so \`columnWidth\` and everything else on it does nothing. Set \`mode="columns"\` on the root, or render \`CascaderList\` instead.`
+    )
+  }, [mode])
+
+  if (mode !== "columns") return null
+
+  const height = maxHeightProp ?? maxHeight
+  const toCss = (value: number | string) =>
+    typeof value === "number" ? `${value}px` : value
+
+  return (
+    <div
+      data-slot="cascader-columns"
+      role="group"
+      aria-label={labels.columnsLabel}
+      style={
+        {
+          "--cascader-column-width": toCss(columnWidth),
+          /* Set only from an EXPLICIT cap: unset means "24rem or what the
+             viewport leaves", via the `min()` fallback on the panel. A `?? 280`
+             default here ignored short viewports and wasted tall ones. */
+          ...(height != null
+            ? { "--cascader-max-height": toCss(height) }
+            : null),
+        } as React.CSSProperties
+      }
+      className={cn(
+        /* `max-h-full` with `min-h-0`: the trail is the panel's shrinking
+           child, and the columns inside it size against this box. */
+        "flex max-h-full min-h-0 items-stretch overflow-x-auto overscroll-x-contain",
+        CASCADER_LIST_PAD_CLASS,
+        className
+      )}
+      {...props}
+    >
+      {columns.map((column) =>
+        children ? (
+          <React.Fragment key={column.depth}>{children(column)}</React.Fragment>
+        ) : (
+          <CascaderColumnPanel key={column.depth} column={column} />
+        )
+      )}
+    </div>
+  )
+}
+
+/**
+ * One column's box. `columnWidth` is the width of the LIST, not the box: under
+ * `border-box` the 1px inline-start divider on every column but the first would
+ * come out of the rows, so bordered columns are widened by that pixel. The box
+ * is also the BOUND, the same `min(--available-height, cap)` the single list
+ * uses, and the `ScrollArea` inside scrolls, so every column shows a thumb.
+ */
+const PANEL_CLASS = `flex w-(--cascader-column-width) shrink-0 flex-col overscroll-contain not-first:w-[calc(var(--cascader-column-width)_+_1px)] not-first:border-border/60 not-first:border-s ${CASCADER_LIST_HEIGHT_CLASS}`
+
+export interface CascaderColumnPanelProps {
+  column: CascaderColumn
+  /** Replaces the panel's rows; the empty state still wins on an empty column. */
+  children?: React.ReactNode
+  /** Containing block for the windowed column's absolutely positioned rows. */
+  virtualized?: boolean
+}
+
+function CascaderColumnPanel({
+  column,
+  children,
+  virtualized,
+}: CascaderColumnPanelProps) {
+  const {
+    labels,
+    baseId,
+    isBranch,
+    isSelectable,
+    isSelected,
+    isIndeterminate,
+    retryLevel,
+    searchScope,
+  } = useCascaderActions()
+  const { loadStates, deepResults } = useCascaderState()
+
+  // Keyed per level, not one global flag: columns load and land independently.
+  const columnKey = column.parent?.value ?? CASCADER_ROOT_KEY
+  const loadState = loadStates.get(columnKey)
+
+  let emptyBody: React.ReactNode = labels.empty
+  if (loadState?.error) {
+    emptyBody = (
+      <>
+        {labels.error}{" "}
+        <button
+          type="button"
+          data-slot="cascader-retry"
+          onClick={(event) => {
+            // Same hand-off as the panel's Retry: a trail column, or an
+            // inline one, can hold focus, and the loading state unmounts this.
+            focusCascaderHome(event.currentTarget)
+            retryLevel(columnKey)
+          }}
+          className="text-foreground hover:bg-accent focus-visible:ring-ring/50 rounded-md px-1 font-medium outline-hidden transition-colors focus-visible:ring-2"
+        >
+          {labels.retry}
+        </button>
+      </>
+    )
+  } else if (loadState?.loading) {
+    emptyBody = (
+      <span className="flex items-center gap-1.5">
+        <LoaderCircleIcon className="size-3.5 animate-spin" aria-hidden />
+        {labels.loading}
+      </span>
+    )
+  }
+
+  const rows =
+    column.items.length === 0 ? (
+      <p
+        data-slot="cascader-column-empty"
+        data-state={
+          loadState?.error ? "error" : loadState?.loading ? "loading" : "empty"
+        }
+        className="text-muted-foreground px-2 py-1.5 text-sm"
+      >
+        {emptyBody}
+      </p>
+    ) : (
+      (children ??
+      column.items.map((node, i) => {
+        const open = node.value === column.activeValue
+        return (
+          <CascaderItem
+            key={node.value}
+            node={node}
+            /* A trail row must not compete for `aria-activedescendant`. */
+            as={column.active ? "option" : "button"}
+            depth={column.depth}
+            /* Answered here, not in the row: the trail rows are memoised too. */
+            branch={isBranch(node)}
+            selectable={isSelectable(node)}
+            selected={isSelected(node)}
+            indeterminate={isIndeterminate(node)}
+            {...getCascaderMoreProps(node, loadStates)}
+            data-open={open || undefined}
+            className={open ? "bg-accent/60 text-accent-foreground" : undefined}
+            /* Set metadata is option-only; a trail row is a `role="button"`. */
+            {...(column.active
+              ? {
+                  "aria-setsize": column.items.length,
+                  "aria-posinset": i + 1,
+                }
+              : null)}
+            {...(!column.active && open
+              ? {
+                  "aria-expanded": true,
+                  "aria-controls": `${baseId}-column-${column.depth + 1}`,
+                }
+              : null)}
+          />
+        )
+      }))
+    )
+
+  const shared = {
+    "data-slot": "cascader-column",
+    "data-active": column.active || undefined,
+    "data-depth": column.depth,
+    // Addressable so the opening trail row can point `aria-controls` here, and
+    // named even at the root, which has no parent label to borrow.
+    id: `${baseId}-column-${column.depth}`,
+    // Global hits come from the whole tree, so the parent would understate them.
+    "aria-label":
+      column.active && searchScope === "global" && deepResults
+        ? labels.rootLevel
+        : (column.parent?.label ?? labels.rootLevel),
+    // Conditional spread, never an explicit `undefined`: the active column is a
+    // Base UI element, and its `mergeProps` iterates own keys.
+    ...(virtualized ? { "data-virtualized": true } : null),
+  }
+
+  // A windowed row is absolutely positioned, so the ROWS' box is the containing
+  // block, not the scrollport: it carries the padding the geometry is measured
+  // against.
+  const rowsClass = cn(CASCADER_ROWS_CLASS, virtualized && "relative")
+
+  // The active column IS the Combobox list: only rows inside `Combobox.List`
+  // reach the CompositeList, arrow-key navigation and `aria-activedescendant`.
+  const body = column.active ? (
+    <ComboboxPrimitive.List {...shared} className={rowsClass}>
+      {rows}
+    </ComboboxPrimitive.List>
+  ) : (
+    // A named `group`, not a second listbox competing with the active column.
+    <div {...shared} role="group" className={rowsClass}>
+      {rows}
+    </div>
+  )
+
+  return (
+    <div
+      data-slot="cascader-column-bounds"
+      /* Repeated from `shared`: this box, not the semantic element, owns the
+         width, the divider and the height, so style hooks must reach it, and
+         `:first-child` on the semantic element no longer means "first column"
+         (it is its own scrollport's only child). */
+      data-active={column.active || undefined}
+      data-depth={column.depth}
+      className={PANEL_CLASS}
+    >
+      <ScrollArea className={CASCADER_SCROLL_CLASS}>{body}</ScrollArea>
+    </div>
+  )
+}
+
+export { CascaderColumnPanel, CascaderColumns }
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader-context.tsx b/apps/web/src/components/reui/cascader/cascader-context.tsx
new file mode 100644
index 0000000..d2a060e
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-context.tsx
@@ -0,0 +1,326 @@
+"use client"
+
+import * as React from "react"
+import type {
+  CascaderActionItem,
+  CascaderChangeReason,
+  CascaderFlatNode,
+  CascaderIndex,
+  CascaderLabels,
+  CascaderLoadState,
+  CascaderMode,
+  CascaderNode,
+  CascaderSearchScope,
+} from "@/components/reui/cascader/cascader-types"
+
+/**
+ * Four contexts, not one: actions (config and callbacks, near-stable), state
+ * (every keystroke), render (`renderItem` identity) and highlight (every arrow
+ * key and pointer move). One combined context re-rendered every row on every
+ * keystroke, which is what made `React.memo` on the row worth nothing.
+ */
+
+/* -------------------------------------------------------------------------- */
+/*                                Shared types                                */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderColumn<T = unknown> {
+  parent: CascaderNode<T> | null
+  items: CascaderNode<T>[]
+  depth: number
+  /** The node in this column that is drilled into, if any. */
+  activeValue: string | null
+  /** Whether this is the deepest column, the one Base UI owns. */
+  active: boolean
+}
+
+export interface CascaderItemState<T = unknown> {
+  branch: boolean
+  selected: boolean
+  /** The node's own flag or a disabled ancestor's, as `isCascaderDisabled`. */
+  disabled: boolean
+  depth: number
+  count: number
+  /** Ancestor chain, root first. Populated for deep and global search rows. */
+  path: CascaderNode<T>[]
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    State                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Everything derived from the query, the path and the selection. One keystroke
+ * rebuilds most of it, so never subscribe to it from a row.
+ */
+export interface CascaderStateContextValue<T = unknown> {
+  /** Same `useMemo` identity as the actions context's `index`. */
+  index: CascaderIndex<T>
+  path: string[]
+  expanded: ReadonlySet<string>
+  query: string
+  currentParent: CascaderNode<T> | null
+  /** Rows for the current level, already filtered. */
+  levelItems: CascaderNode<T>[]
+  deepResults: CascaderNode<T>[] | null
+  /** What `Combobox.Root` is currently rendering, in render order. */
+  renderedItems: CascaderNode<T>[]
+  columns: CascaderColumn<T>[]
+  treeRows: CascaderFlatNode<T>[]
+  selectedValues: string[]
+  /** Selected nodes below each value, at any depth. Absent means zero. */
+  selectedDescendants: ReadonlyMap<string, number>
+  /**
+   * Per level, keyed by parent value or `CASCADER_ROOT_KEY`. MEMBERSHIP is the
+   * discriminator: no entry means never fetched, an entry with no `loading`, no
+   * `error` and no children means fetched and genuinely empty.
+   */
+  loadStates: ReadonlyMap<string, CascaderLoadState>
+  /** Async search, `null` when idle. Separate: a search belongs to no level. */
+  searchState: CascaderLoadState | null
+  announcement: string
+}
+
+const CascaderStateContext = React.createContext<
+  CascaderStateContextValue | undefined
+>(undefined)
+
+/**
+ * One provider serves every `T`, so the context holds an erased `unknown` value
+ * and this cast restores it. The primitive never inspects the payload.
+ */
+export function useCascaderState<T = unknown>(): CascaderStateContextValue<T> {
+  const context = React.useContext(CascaderStateContext)
+  if (!context) {
+    throw new Error("useCascaderState must be used within a Cascader")
+  }
+  return context as unknown as CascaderStateContextValue<T>
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Actions                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Config and callbacks, slow enough that a memoised row can subscribe: the
+ * mutators are `[]`-dep callbacks over a latest-props ref. The predicates are
+ * the exception, read DURING RENDER where a ref written in an effect would
+ * return the previous commit's answer, so each is memoised on its own input.
+ */
+export interface CascaderActionsContextValue<T = unknown> {
+  index: CascaderIndex<T>
+  mode: CascaderMode
+  multiple: boolean
+  /** Multi-select only: a commit propagates over the LOADED subtree. */
+  cascade: boolean
+  /** Whether a BRANCH is committable. Per-LIST: the check gutter is a COLUMN. */
+  branchesSelectable: boolean
+  /** Draws the SINGLE-SELECT check and its gutter. Ignored in multi-select. */
+  indicator: boolean
+  expandTrigger?: "click" | "hover"
+  actions: CascaderActionItem[]
+  searchScope: CascaderSearchScope
+  maxHeight?: number | string
+  inline: boolean
+  invalid: boolean
+  /**
+   * Id prefix; columns are `${baseId}-column-${depth}`. The SCHEME is contract:
+   * the filters primitive's `FilterMenuPinKeeper` restores its highlight across
+   * a live re-pin through `${baseId}-column-0` and the `cascader-item` slot.
+   */
+  baseId: string
+  labels: CascaderLabels
+
+  /**
+   * Whether rows are WINDOWED. Also handed to `Combobox.Root`, which is what
+   * makes an explicit row `index` legal: forwarding one while this is false
+   * makes `aria-activedescendant` resolve to nothing. Latched per level.
+   */
+  virtualized: boolean
+  /** Mounts a windowing renderer, returns its unregister. LAYOUT effect only. */
+  registerVirtualRenderer: () => () => void
+  /** The root's `virtualize` prop. `undefined` means "decide by count". */
+  virtualize?: boolean
+  virtualizeThreshold: number
+  estimateRowSize: number
+  overscan: number
+
+  /** Tells "this level is empty" from "not fetched yet" before a load state. */
+  hasLoader: boolean
+  /** Next page of a level. Latched: a page with nothing new is not re-asked. */
+  loadMore: (parentKey: string) => void
+  retryLevel: (parentKey: string) => void
+  /** Re-runs a failed server search (`onSearch`) for the current query. */
+  retrySearch: () => void
+  /**
+   * Evicts one level's async cache, `null` for the root, so membership reads
+   * never-loaded. A level that is on screen when evicted refetches at once.
+   */
+  invalidateLevel: (value: string | null) => void
+
+  /** Index as of the last commit. Use in the stable callbacks, not `index`. */
+  getIndex: () => CascaderIndex<T>
+  getState: () => CascaderStateContextValue<T>
+  /** Highlighted row or null. A getter: the highlight moves per arrow key. */
+  getHighlighted: () => CascaderNode<T> | null
+
+  setPath: (next: string[] | ((prev: string[]) => string[])) => void
+  pushLevel: (value: string) => void
+  popLevel: () => void
+  goToDepth: (depth: number) => void
+  toggleExpanded: (value: string) => void
+  /**
+   * Registers a footer submenu as open or closed. `Combobox` has no
+   * `FloatingTree`, so one Escape would dismiss the flyout AND the cascader;
+   * the root's `onOpenChange` guard cancels the close while any is open, from a
+   * ref so it reads as of that event without re-rendering the root.
+   */
+  setFlyoutOpen: (key: string, open: boolean) => void
+  hasOpenFlyout: () => boolean
+  setQuery: (next: string) => void
+  /**
+   * Replaces the selection. `onValueChange` diffs it against the current one
+   * for its node and reason; pass `reason` only when the caller knows better.
+   */
+  setSelection: (values: string[], reason?: CascaderChangeReason) => void
+  /** Commits a node, for rows outside the listbox such as ancestor columns. */
+  commit: (node: CascaderNode<T>) => void
+  navigate: (node: CascaderNode<T>) => void
+  /** Into `node` as a child of `depth`, replacing anything deeper. */
+  navigateAt: (node: CascaderNode<T>, depth: number) => void
+  /** Never undefined: falls back to a remembered label, then a synthetic node. */
+  resolveNode: (value: string) => CascaderNode<T>
+  isBranch: (node: CascaderNode<T>) => boolean
+  isSelectable: (node: CascaderNode<T>) => boolean
+  /**
+   * The node or an ancestor is `disabled`. Rows render it disabled; row
+   * presses, keys, `commit`, `navigate`, `navigateAt` and a held navigation
+   * refuse it. `pushLevel`, `setPath`, `toggleExpanded` and `setSelection` are
+   * raw setters and do not ask.
+   */
+  isDisabled: (node: CascaderNode<T>) => boolean
+  isSelected: (node: CascaderNode<T>) => boolean
+  /** Always `false` without `cascade`: partial selection needs propagation. */
+  isIndeterminate: (node: CascaderNode<T>) => boolean
+  /**
+   * O(1) read of `selectedDescendants`; a memoised row may not subscribe.
+   * Unlike `isIndeterminate` this answers in every mode.
+   */
+  selectedDescendantCount: (node: CascaderNode<T>) => number
+}
+
+const CascaderActionsContext = React.createContext<
+  CascaderActionsContextValue | undefined
+>(undefined)
+
+export function useCascaderActions<
+  T = unknown,
+>(): CascaderActionsContextValue<T> {
+  const context = React.useContext(CascaderActionsContext)
+  if (!context) {
+    throw new Error("useCascaderActions must be used within a Cascader")
+  }
+  return context as unknown as CascaderActionsContextValue<T>
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                Render props                                */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Their own context, republished every render. They cannot ride on the actions
+ * context: an inline closure read off a memoised object is whichever closure
+ * that object captured, so the row would call a stale prop over stale state.
+ */
+export interface CascaderRenderContextValue<T = unknown> {
+  renderItem?: (
+    node: CascaderNode<T>,
+    state: CascaderItemState<T>
+  ) => React.ReactNode
+  renderLabel?: (
+    node: CascaderNode<T>,
+    state: CascaderItemState<T>
+  ) => React.ReactNode
+}
+
+const CascaderRenderContext = React.createContext<CascaderRenderContextValue>(
+  {}
+)
+
+export function useCascaderRender<
+  T = unknown,
+>(): CascaderRenderContextValue<T> {
+  return React.useContext(
+    CascaderRenderContext
+  ) as CascaderRenderContextValue<T>
+}
+
+/* -------------------------------------------------------------------------- */
+/*                               Highlight store                              */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderHighlight {
+  index: number
+  value: string | null
+}
+
+/**
+ * An external store, deliberately NOT React state: `onItemHighlighted` fires on
+ * every arrow key AND every pointer move over the list, so `setState` would
+ * re-render the whole root at mousemove rate. A store re-renders subscribers
+ * only, which inside the primitive is the virtualizer.
+ */
+export interface CascaderHighlightStore {
+  subscribe: (onStoreChange: () => void) => () => void
+  getSnapshot: () => CascaderHighlight
+  set: (next: CascaderHighlight) => void
+}
+
+const NO_HIGHLIGHT: CascaderHighlight = { index: -1, value: null }
+
+export function createCascaderHighlightStore(): CascaderHighlightStore {
+  let snapshot: CascaderHighlight = NO_HIGHLIGHT
+  const listeners = new Set<() => void>()
+
+  return {
+    subscribe(onStoreChange) {
+      listeners.add(onStoreChange)
+      return () => {
+        listeners.delete(onStoreChange)
+      }
+    },
+    // The SAME object until something changes; `useSyncExternalStore` needs it.
+    getSnapshot() {
+      return snapshot
+    },
+    set(next) {
+      if (next.index === snapshot.index && next.value === snapshot.value) return
+      snapshot = next
+      for (const listener of listeners) listener()
+    },
+  }
+}
+
+/** Shared and permanently empty, so the hook degrades outside a `Cascader`. */
+const FALLBACK_HIGHLIGHT_STORE = createCascaderHighlightStore()
+
+const CascaderHighlightContext = React.createContext<CascaderHighlightStore>(
+  FALLBACK_HIGHLIGHT_STORE
+)
+
+/** Subscribes to the highlight. Re-renders ONLY the calling component. */
+export function useCascaderHighlight(): CascaderHighlight {
+  const store = React.useContext(CascaderHighlightContext)
+  return React.useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot
+  )
+}
+
+export {
+  CascaderActionsContext,
+  CascaderHighlightContext,
+  CascaderRenderContext,
+  CascaderStateContext,
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader-footer.tsx b/apps/web/src/components/reui/cascader/cascader-footer.tsx
new file mode 100644
index 0000000..69010c2
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-footer.tsx
@@ -0,0 +1,731 @@
+import * as React from "react"
+import { useCascaderActions } from "@/components/reui/cascader/cascader-context"
+import {
+  CASCADER_ACTION_CLASS,
+  CascaderGroup,
+  CascaderLabel,
+} from "@/components/reui/cascader/cascader-item"
+import {
+  CASCADER_LIST_PAD_CLASS,
+  getCascaderFooterStops,
+  isCascaderRtl,
+} from "@/components/reui/cascader/cascader-lib"
+import type { CascaderActionItem } from "@/components/reui/cascader/cascader-types"
+import { Popover as PopoverPrimitive } from "@base-ui/react"
+import { useDirection } from "@base-ui/react/direction-provider"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { ChevronRightIcon } from "lucide-react"
+
+/**
+ * The pinned footer, and the side-anchored flyout a footer row can open. These
+ * are COMMANDS: nothing here joins the selection, the filter set or the
+ * highlight. The flyout is a Base UI `Popover` rendered as a REACT CHILD of
+ * `Combobox.Popup` with its OWN `Portal` and NO `container`: a nested portal
+ * resolves to the parent portal node, so it is a DOM sibling of the combobox
+ * popup (not clipped, not `aria-hidden`) but a React descendant, which is what
+ * the outside-press and focus-out whitelists read. `Combobox` builds no
+ * `FloatingTree`, so the flyout is not consulted first and one Escape would
+ * dismiss both; hence `CascaderSubmenu` registering with the root to turn one
+ * Escape into two. `Combobox.List` clicks its highlighted row on Enter, hence
+ * the footer sitting outside `CascaderList`. And a `Positioner` throws without
+ * its `Portal`, while `modal` stays `false` on the `Root` so the combobox
+ * keeps its own dismissal behaviour.
+ */
+
+/* -------------------------------------------------------------------------- */
+/*                                   Footer                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Keys the option list acts on, swallowed at the footer boundary. Escape and
+ * Tab are absent on purpose: Escape must reach the root, Tab must keep moving.
+ */
+const FOOTER_SWALLOWED_KEYS = new Set([
+  "Enter",
+  " ",
+  "ArrowUp",
+  "ArrowDown",
+  "Home",
+  "End",
+  "PageUp",
+  "PageDown",
+])
+
+export type CascaderFooterProps = React.ComponentProps<"div">
+
+/**
+ * Actions pinned below the list, a SIBLING of `CascaderList`. Children win
+ * over the root's `actions` prop; with neither it renders nothing.
+ */
+function CascaderFooter({
+  className,
+  children,
+  onKeyDown,
+  ...props
+}: CascaderFooterProps) {
+  const { actions, labels } = useCascaderActions()
+  const hasChildren = React.Children.count(children) > 0
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      onKeyDown?.(event)
+      if (event.defaultPrevented) return
+      if (!FOOTER_SWALLOWED_KEYS.has(event.key)) return
+      event.stopPropagation()
+
+      // The strip's own vertical movement, and the way back from the list's
+      // hand-off: either end returns focus to the search field, from which
+      // Base UI's empty highlight resumes the list. Down wraps to the FIELD,
+      // not a command (traps the arrows) or a row (no imperative highlight).
+      if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return
+      const footer = event.currentTarget
+      const stops = getCascaderFooterStops(footer)
+      const active = document.activeElement as HTMLElement | null
+      const index = active ? stops.indexOf(active) : -1
+      if (index === -1) return
+      event.preventDefault()
+      const next =
+        event.key === "ArrowDown" ? stops[index + 1] : stops[index - 1]
+      if (next) {
+        next.focus()
+        return
+      }
+      if (event.key === "ArrowUp" && index > 0) return
+      footer
+        .closest<HTMLElement>('[data-slot="cascader-panel"]')
+        ?.querySelector<HTMLElement>('[data-slot="cascader-input"]')
+        ?.focus()
+    },
+    [onKeyDown]
+  )
+
+  if (!hasChildren && actions.length === 0) return null
+
+  return (
+    <div
+      data-slot="cascader-footer"
+      /* Named, not a bare div: without it a screen reader reaches the actions
+         with nothing to say they are not more options. */
+      role="group"
+      aria-label={labels.actionsLabel}
+      onKeyDown={handleKeyDown}
+      className={cn(
+        "border-border/60 flex shrink-0 flex-col gap-0.5 border-t",
+        /* The LIST's padding, not a flat `p-1`: with a padding of its own the
+           two columns of text were 2px out in luma and sera and 4px out in
+           lyra. It also gives a separator in here a number to cancel. */
+        CASCADER_LIST_PAD_CLASS,
+        "p-(--cascader-list-pad,4px)",
+        className
+      )}
+      {...props}
+    >
+      {hasChildren ? children : <CascaderFooterActions actions={actions} />}
+    </div>
+  )
+}
+
+function CascaderFooterActions({ actions }: { actions: CascaderActionItem[] }) {
+  return (
+    <>
+      {actions.map((action, i) =>
+        action.items?.length ? (
+          <CascaderSubmenu key={actionKey(action, i)}>
+            <CascaderSubmenuTrigger
+              icon={action.icon}
+              disabled={action.disabled}
+            >
+              {action.label}
+            </CascaderSubmenuTrigger>
+            <CascaderSubmenuContent>
+              <CascaderActionList items={action.items} />
+            </CascaderSubmenuContent>
+          </CascaderSubmenu>
+        ) : (
+          <CascaderAction
+            key={actionKey(action, i)}
+            icon={action.icon}
+            disabled={action.disabled}
+            onSelect={action.onSelect}
+          >
+            {action.label}
+          </CascaderAction>
+        )
+      )}
+    </>
+  )
+}
+
+function actionKey(action: CascaderActionItem, index: number): string {
+  if (action.value != null) return action.value
+  if (typeof action.label === "string") return action.label
+  return String(index)
+}
+
+/**
+ * Consecutive entries sharing a `group`, as runs not buckets: two separated
+ * runs with the same name stay two, so the author's order survives.
+ */
+function groupActionRuns(
+  items: CascaderActionItem[]
+): { group?: string; items: CascaderActionItem[] }[] {
+  const runs: { group?: string; items: CascaderActionItem[] }[] = []
+  for (const item of items) {
+    const last = runs[runs.length - 1]
+    if (last && last.group === item.group) last.items.push(item)
+    else runs.push({ group: item.group, items: [item] })
+  }
+  return runs
+}
+
+/**
+ * Flyout body for a data-driven submenu. A named run becomes a real
+ * `CascaderGroup`; unnamed runs stay unwrapped, as an unnamed group is noise.
+ */
+function CascaderActionList({ items }: { items: CascaderActionItem[] }) {
+  const { close } = useCascaderSubmenu()
+  const runs = React.useMemo(() => groupActionRuns(items), [items])
+
+  const renderAction = (item: CascaderActionItem, i: number) => (
+    <CascaderAction
+      key={actionKey(item, i)}
+      icon={item.icon}
+      disabled={item.disabled}
+      onSelect={() => {
+        item.onSelect?.()
+        /* Closes behind the command, or the entries would read as toggles. */
+        close()
+      }}
+    >
+      {item.label}
+    </CascaderAction>
+  )
+
+  return (
+    <>
+      {runs.map((run, runIndex) =>
+        run.group ? (
+          <CascaderGroup key={`${run.group}-${runIndex}`} className="gap-0.5">
+            <CascaderLabel>{run.group}</CascaderLabel>
+            {run.items.map(renderAction)}
+          </CascaderGroup>
+        ) : (
+          <React.Fragment key={`run-${runIndex}`}>
+            {run.items.map(renderAction)}
+          </React.Fragment>
+        )
+      )}
+    </>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Action                                   */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderActionProps extends Omit<
+  React.ComponentProps<"button">,
+  "onSelect"
+> {
+  icon?: React.ReactNode
+  /** Fires on press, after `onClick`, and not at all when disabled. */
+  onSelect?: () => void
+}
+
+/**
+ * The cascader popup's panel per style, spelled with `style-<name>:` variants
+ * rather than ReUI theme CSS so an installed footer needs only Tailwind.
+ */
+const FLYOUT_SURFACE_CLASS =
+  "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 max-h-72 overflow-hidden ring-1 duration-100 ring-foreground/10 shadow-md rounded-lg"
+
+/**
+ * One footer command, shaped like a row and deliberately NOT one. A real
+ * `<button>`, never a `Combobox.Item`: an item would join the arrow-key ring,
+ * appear in `filteredItems`, and vanish the moment a query matched nothing -
+ * exactly when "Create new attribute" is most useful. Disabled is
+ * `aria-disabled`, never the native attribute: that one is not a tab stop and
+ * the panel's Tab order reads `button:not([disabled])`, so a footer whose ONLY
+ * row is a disabled command had no stop after the search field (measured on
+ * `c-cascader-8`). Staying focusable costs the guards below, plus the
+ * greyed-out look: `CASCADER_ACTION_CLASS` keys that off `aria-disabled`
+ * instead of `:disabled`.
+ */
+function CascaderAction({
+  className,
+  icon,
+  children,
+  onSelect,
+  onClick,
+  onKeyDown,
+  disabled,
+  ...props
+}: CascaderActionProps) {
+  // Set by `CascaderSubmenuContent`: a plain button in the footer's Tab ring,
+  // a roving-focus `menuitem` inside a flyout, never both.
+  const inMenu = React.useContext(CascaderMenuContext)
+
+  const handleClick = React.useCallback(
+    (event: React.MouseEvent<HTMLButtonElement>) => {
+      // Before the consumer's handler: a disabled command runs none of them.
+      if (disabled) {
+        event.preventDefault()
+        return
+      }
+      onClick?.(event)
+      if (event.defaultPrevented) return
+      onSelect?.()
+    },
+    [disabled, onClick, onSelect]
+  )
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLButtonElement>) => {
+      if (disabled) {
+        // The two keys a `<button>` activates on, and only those.
+        if (event.key === "Enter" || event.key === " ") event.preventDefault()
+        return
+      }
+      onKeyDown?.(event)
+    },
+    [disabled, onKeyDown]
+  )
+
+  return (
+    <button
+      type="button"
+      data-slot="cascader-action"
+      /* Conditional spread: `false` would publish `aria-disabled="false"`. */
+      {...(disabled ? { "aria-disabled": true, "data-disabled": "" } : null)}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      /* Conditional spread, so a consumer's own `role` or `tabIndex` wins. */
+      {...(inMenu ? { role: "menuitem" as const, tabIndex: -1 } : null)}
+      className={cn(CASCADER_ACTION_CLASS, className)}
+      {...props}
+    >
+      {icon ? (
+        <span
+          data-slot="cascader-action-icon"
+          className="text-muted-foreground flex shrink-0 items-center justify-center"
+        >
+          {icon}
+        </span>
+      ) : null}
+      <span className="min-w-0 flex-1 truncate text-start">{children}</span>
+    </button>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Submenu                                   */
+/* -------------------------------------------------------------------------- */
+
+interface CascaderSubmenuContextValue {
+  rowRef: React.RefObject<HTMLButtonElement | null>
+  open: boolean
+  setOpen: (open: boolean) => void
+  close: () => void
+  /** Names the flyout: a menu is labelled by the control that opens it. */
+  triggerId: string
+  /**
+   * Whether the pending open came from the KEYBOARD. Base UI's own `openType`
+   * calls the opening arrow a POINTER open, because the trigger intercepts it
+   * and calls `setOpen` (measured: focus landed on the popup, not the first
+   * entry). A ref, so reading it in the focus phase cannot render.
+   */
+  keyboardRef: React.RefObject<boolean>
+}
+
+/** Marks the subtree INSIDE a flyout. See `inMenu` in `CascaderAction`. */
+const CascaderMenuContext = React.createContext(false)
+
+/**
+ * Every entry a menu's roving focus may land on, in DOM order, read from the
+ * DOM because the entries are whatever the consumer composed. A disabled
+ * `CascaderAction` is INCLUDED: it carries `aria-disabled`, not the native
+ * attribute, so `:not([disabled])` excludes only a consumer's own natively
+ * disabled `menuitem`, which cannot take focus.
+ */
+function menuItems(popup: HTMLElement | null): HTMLElement[] {
+  if (!popup) return []
+  return Array.from(
+    popup.querySelectorAll<HTMLElement>('[role="menuitem"]:not([disabled])')
+  )
+}
+
+const CascaderSubmenuContext = React.createContext<
+  CascaderSubmenuContextValue | undefined
+>(undefined)
+
+/** The flyout's own state. `close()` is the one a custom entry usually wants. */
+export function useCascaderSubmenu(): CascaderSubmenuContextValue {
+  const context = React.useContext(CascaderSubmenuContext)
+  if (!context) {
+    throw new Error("useCascaderSubmenu must be used within a CascaderSubmenu")
+  }
+  return context
+}
+
+export interface CascaderSubmenuProps {
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  children?: React.ReactNode
+}
+
+/**
+ * A footer row plus the flyout it opens. Registers with the cascader root
+ * while open, which turns one Escape into two. Cleared in an EFFECT, so the
+ * flyout still reads as open during the event that closed it.
+ */
+function CascaderSubmenu({
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  children,
+}: CascaderSubmenuProps) {
+  const { setFlyoutOpen } = useCascaderActions()
+  const key = React.useId()
+  const triggerId = React.useId()
+  const rowRef = React.useRef<HTMLButtonElement | null>(null)
+  const keyboardRef = React.useRef(false)
+  const [uncontrolled, setUncontrolled] = React.useState(defaultOpen)
+  const open = openProp ?? uncontrolled
+
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (openProp == null) setUncontrolled(next)
+      onOpenChange?.(next)
+    },
+    [openProp, onOpenChange]
+  )
+
+  const close = React.useCallback(() => setOpen(false), [setOpen])
+
+  React.useEffect(() => {
+    setFlyoutOpen(key, open)
+    return () => setFlyoutOpen(key, false)
+  }, [setFlyoutOpen, key, open])
+
+  const context = React.useMemo<CascaderSubmenuContextValue>(
+    () => ({ rowRef, open, setOpen, close, triggerId, keyboardRef }),
+    [open, setOpen, close, triggerId]
+  )
+
+  return (
+    <CascaderSubmenuContext.Provider value={context}>
+      <PopoverPrimitive.Root
+        open={open}
+        onOpenChange={setOpen}
+        /* NEVER modal: it would disable the combobox that owns it. */
+        modal={false}
+      >
+        {children}
+      </PopoverPrimitive.Root>
+    </CascaderSubmenuContext.Provider>
+  )
+}
+
+export interface CascaderSubmenuTriggerProps extends Omit<
+  React.ComponentProps<"button">,
+  "onSelect"
+> {
+  icon?: React.ReactNode
+}
+
+/** Carries the handler-veto hook, derived so a Base UI bump cannot drift. */
+type CascaderSubmenuTriggerClickEvent = Parameters<
+  NonNullable<PopoverPrimitive.Trigger.Props["onClick"]>
+>[0]
+
+/**
+ * The footer row that opens the flyout, and its anchor. `aria-haspopup="menu"`
+ * rather than the `dialog` Base UI would announce: what opens is a list of
+ * commands with roving focus. `disabled` is intercepted, not forwarded:
+ * `Popover.Trigger` runs it through `useButton`, which writes the NATIVE
+ * attribute for a native `<button>` and takes the row out of the panel's Tab
+ * ring, the defect `CascaderAction` documents, and this component exposes no
+ * `focusableWhenDisabled` to opt out. Published as `aria-disabled`, with the
+ * arrow keys, Enter and Space, and the click closed by hand (`useClick`
+ * ignores `defaultPrevented`).
+ */
+function CascaderSubmenuTrigger({
+  className,
+  icon,
+  children,
+  onKeyDown,
+  onClick,
+  disabled,
+  ...props
+}: CascaderSubmenuTriggerProps) {
+  const { labels } = useCascaderActions()
+  const { rowRef, setOpen, triggerId, keyboardRef } = useCascaderSubmenu()
+  const direction = useDirection()
+
+  const handleClick = React.useCallback(
+    (event: CascaderSubmenuTriggerClickEvent) => {
+      if (disabled) {
+        // `mergeProps` runs right to left, so this drops Base UI's own handler.
+        event.preventDefault()
+        event.preventBaseUIHandler()
+        return
+      }
+      onClick?.(event)
+    },
+    [disabled, onClick]
+  )
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLButtonElement>) => {
+      if (disabled) {
+        if (event.key === "Enter" || event.key === " ") event.preventDefault()
+        return
+      }
+
+      onKeyDown?.(event)
+      if (event.defaultPrevented) return
+
+      // The opening key points AT the flyout, so it flips with the writing
+      // direction; ArrowDown stays "next command". Resolved per keydown, never
+      // `useDirection()` alone: with no provider that answers "ltr" in RTL.
+      const openKey = isCascaderRtl(event.currentTarget, direction)
+        ? "ArrowLeft"
+        : "ArrowRight"
+
+      // Enter and Space open through the button's own click, so only FLAGGED.
+      if (event.key === "Enter" || event.key === " ") {
+        keyboardRef.current = true
+        return
+      }
+
+      if (event.key !== openKey) return
+
+      event.preventDefault()
+      keyboardRef.current = true
+      setOpen(true)
+    },
+    [disabled, onKeyDown, direction, setOpen, keyboardRef]
+  )
+
+  return (
+    <PopoverPrimitive.Trigger
+      ref={rowRef}
+      id={triggerId}
+      data-slot="cascader-submenu-trigger"
+      aria-haspopup="menu"
+      /* NOT `disabled={disabled}`: Base UI writes the native attribute. */
+      {...(disabled ? { "aria-disabled": true, "data-disabled": "" } : null)}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      className={cn(
+        CASCADER_ACTION_CLASS,
+        /* Painted while the flyout is open, as shadcn paints a SubTrigger.
+           Keyed off `aria-expanded`, not shadcn's `data-[state=open]`: the
+           popover trigger carries `aria-expanded` in both states. */
+        "aria-expanded:bg-accent aria-expanded:text-accent-foreground",
+        className
+      )}
+      {...props}
+    >
+      {icon ? (
+        <span
+          data-slot="cascader-action-icon"
+          className="text-muted-foreground flex shrink-0 items-center justify-center"
+        >
+          {icon}
+        </span>
+      ) : null}
+      <span className="min-w-0 flex-1 truncate text-start">{children}</span>
+      {/* Nothing else says the row opens a MENU, not another tree level. */}
+      <span className="sr-only">, {labels.submenuAffordance}</span>
+      <ChevronRightIcon aria-hidden="true" className="text-muted-foreground -me-0.5 size-4 shrink-0 rtl:-scale-x-100" />
+    </PopoverPrimitive.Trigger>
+  )
+}
+
+export interface CascaderSubmenuContentProps
+  extends
+    PopoverPrimitive.Popup.Props,
+    Pick<
+      PopoverPrimitive.Positioner.Props,
+      "side" | "align" | "sideOffset" | "alignOffset"
+    > {}
+
+/** Carries Base UI's handler-veto hook, so a plain React event will not do. */
+type CascaderSubmenuKeyEvent = Parameters<
+  NonNullable<PopoverPrimitive.Popup.Props["onKeyDown"]>
+>[0]
+
+/**
+ * The flyout itself. `Portal` with NO `container`: a nested portal resolves to
+ * the parent portal node, the mechanism the file header describes.
+ */
+function CascaderSubmenuContent({
+  className,
+  children,
+  onKeyDown,
+  side = "inline-end",
+  align = "end",
+  sideOffset = 8,
+  alignOffset = 0,
+  ...props
+}: CascaderSubmenuContentProps) {
+  const { rowRef, close, triggerId, keyboardRef } = useCascaderSubmenu()
+  const direction = useDirection()
+  const popupRef = React.useRef<HTMLDivElement | null>(null)
+  const typeaheadRef = React.useRef({ buffer: "", at: 0 })
+
+  /**
+   * Keyboard opens land on the first entry; a pointer open falls through to
+   * Base UI's default, the popup, so a click paints no focus ring. Not an
+   * effect of our own: Base UI's focus manager runs on open and wins the race.
+   */
+  const initialFocus = React.useCallback(() => {
+    const byKeyboard = keyboardRef.current
+    keyboardRef.current = false
+    if (!byKeyboard) return true
+    return menuItems(popupRef.current)[0] ?? true
+  }, [keyboardRef])
+
+  const closeAndReturn = React.useCallback(() => {
+    close()
+    rowRef.current?.focus()
+  }, [close, rowRef])
+
+  const handleKeyDown = React.useCallback(
+    (event: CascaderSubmenuKeyEvent) => {
+      onKeyDown?.(event)
+      // A DOM sibling of the combobox popup but a REACT descendant, so keys in
+      // here reach its handlers unless stopped. Enter would commit a row.
+      event.stopPropagation()
+      if (event.defaultPrevented) return
+
+      const popup = popupRef.current
+      const items = menuItems(popup)
+      if (items.length === 0) return
+
+      const active = document.activeElement as HTMLElement | null
+      const index = active ? items.indexOf(active) : -1
+      const move = (next: number) => {
+        event.preventDefault()
+        items[(next + items.length) % items.length]?.focus()
+      }
+
+      // Mirrors the open key on the SAME per-keydown answer as the trigger.
+      const closeKey = isCascaderRtl(event.currentTarget, direction)
+        ? "ArrowRight"
+        : "ArrowLeft"
+
+      switch (event.key) {
+        case "ArrowDown":
+          return move(index + 1)
+        case "ArrowUp":
+          // From the popup itself (a pointer open) Up means the LAST entry.
+          return move(index === -1 ? items.length - 1 : index - 1)
+        case "Home":
+          return move(0)
+        case "End":
+          return move(items.length - 1)
+        case closeKey:
+          event.preventDefault()
+          return closeAndReturn()
+        case "Tab":
+          // A menu never holds Tab: it closes and focus carries on from its row.
+          close()
+          rowRef.current?.focus()
+          return
+        default:
+          break
+      }
+
+      // Typeahead, after the switch so it can never swallow a navigation key.
+      if (
+        event.key.length !== 1 ||
+        event.metaKey ||
+        event.ctrlKey ||
+        event.altKey
+      )
+        return
+      const now = event.timeStamp
+      const state = typeaheadRef.current
+      state.buffer = now - state.at > 500 ? event.key : state.buffer + event.key
+      state.at = now
+      const prefix = state.buffer.toLowerCase()
+      const from = index === -1 ? 0 : index
+      // Starts AFTER the current entry so one letter cycles rather than sticks.
+      const ordered = [
+        ...items.slice(state.buffer.length > 1 ? from : from + 1),
+        ...items.slice(0, state.buffer.length > 1 ? from : from + 1),
+      ]
+      const hit = ordered.find((item) =>
+        (item.textContent ?? "").trim().toLowerCase().startsWith(prefix)
+      )
+      if (hit) {
+        event.preventDefault()
+        hit.focus()
+      }
+    },
+    [onKeyDown, direction, close, closeAndReturn, rowRef]
+  )
+
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Positioner
+        /* The ROW, not whatever Base UI last treated as the trigger. */
+        anchor={rowRef}
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        alignOffset={alignOffset}
+        className="isolate z-50"
+      >
+        <PopoverPrimitive.Popup
+          ref={popupRef}
+          initialFocus={initialFocus}
+          data-slot="cascader-submenu-content"
+          /* Roving focus, named by the row that opens it. `tabIndex={-1}` lets
+             a pointer open park focus here without adding a Tab stop. */
+          role="menu"
+          aria-orientation="vertical"
+          aria-labelledby={triggerId}
+          tabIndex={-1}
+          onKeyDown={handleKeyDown}
+          /* Marks a menu surface for the docs design-system picker, which
+             repaints menus by walking the DOM. An attribute, not a class. */
+          data-menu-target=""
+          className={cn(
+            FLYOUT_SURFACE_CLASS,
+            "flex max-w-(--available-width) min-w-48 flex-col gap-0.5 outline-hidden",
+            CASCADER_LIST_PAD_CLASS,
+            "p-(--cascader-list-pad,4px)",
+            className
+          )}
+          {...props}
+        >
+          <CascaderMenuContext.Provider value={true}>
+            {children}
+          </CascaderMenuContext.Provider>
+        </PopoverPrimitive.Popup>
+      </PopoverPrimitive.Positioner>
+    </PopoverPrimitive.Portal>
+  )
+}
+
+/**
+ * Whether the footer would render anything, for a wrapper (a separator, a grid
+ * row) that has to make the same call `CascaderFooter` already makes.
+ */
+export function useCascaderHasActions(): boolean {
+  const { actions } = useCascaderActions()
+  return actions.length > 0
+}
+
+export {
+  CascaderAction,
+  CascaderFooter,
+  CascaderSubmenu,
+  CascaderSubmenuContent,
+  CascaderSubmenuTrigger,
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader-i18n.tsx b/apps/web/src/components/reui/cascader/cascader-i18n.tsx
new file mode 100644
index 0000000..30ea930
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-i18n.tsx
@@ -0,0 +1,92 @@
+import type {
+  CascaderLabels,
+  CascaderMode,
+} from "@/components/reui/cascader/cascader-types"
+
+/** Name of the root level. Hoisted so the root announcement can reuse it. */
+const ROOT_LEVEL = "Top level"
+
+/** Hoisted for the same reason: several defaults end in an item count. */
+const itemCount = (count: number) =>
+  `${count} ${count === 1 ? "item" : "items"}`
+
+/**
+ * English defaults. Every string the primitive can render lives here, so a
+ * consumer can translate the whole surface by passing `labels`.
+ */
+export const CASCADER_LABELS: CascaderLabels = {
+  // Deliberately NOT lowercased. `toLowerCase()` is locale-hostile - it maps
+  // Turkish "İ" to a two-code-point sequence and German "İstanbul" style
+  // proper nouns lose their casing - and a label is already written the way
+  // its author wants it read.
+  search: (parentLabel) =>
+    parentLabel ? `Search ${parentLabel}...` : "Search...",
+  back: "Back",
+  loading: "Loading...",
+  loadingMore: "Loading more...",
+  loadMore: "Load more",
+  error: "Could not load items.",
+  retry: "Retry",
+  empty: "No results found.",
+  selectedCount: (count) => `${count} selected`,
+  breadcrumbLabel: "Breadcrumb",
+  chipsLabel: "Selected items",
+  removeChip: (label) => `Remove ${label}`,
+  pathSeparator: "/",
+  rootLevel: ROOT_LEVEL,
+  itemCount,
+  branchAffordance: "submenu",
+  selectedState: "selected",
+  partiallySelectedState: "partially selected",
+  columnsLabel: "Levels",
+  actionsLabel: "Actions",
+  submenuAffordance: "opens a menu",
+  panelLabel: "Options",
+  keyboardHint: (mode: CascaderMode, dir: "ltr" | "rtl") => {
+    // "Deeper" is the direction the text runs, so the level keys mirror in
+    // RTL and the hint has to name the mirrored pair there - an LTR-worded
+    // hint would teach exactly the wrong keys.
+    const open = dir === "rtl" ? "Left" : "Right"
+    const back = dir === "rtl" ? "Right" : "Left"
+    if (mode === "tree") {
+      return `Use the ${open} Arrow key to expand and the ${back} Arrow key to collapse.`
+    }
+    if (mode === "columns") {
+      return `Use the ${open} Arrow key to open the next column and the ${back} Arrow key to go back.`
+    }
+    return `Use the ${open} Arrow key to open a branch and the ${back} Arrow key to go back.`
+  },
+  rootAnnouncement: (count) => `${ROOT_LEVEL}, ${itemCount(count)}`,
+  expandedAnnouncement: (label, count) =>
+    `${label} expanded, ${itemCount(count)}`,
+  collapsedAnnouncement: (label) => `${label} collapsed`,
+  levelAnnouncement: (parentLabel, depth, count) =>
+    `${parentLabel}, level ${depth}, ${itemCount(count)}`,
+  resultsAnnouncement: (count) =>
+    count === 1 ? "1 result" : `${count} results`,
+  maxReachedAnnouncement: (max) => `Selection limit of ${max} reached`,
+  cascadeAnnouncement: (label, count, selecting) =>
+    `${label} ${selecting ? "selected" : "deselected"}, ${itemCount(count)} followed`,
+  searchingAnnouncement: "Searching...",
+}
+
+/**
+ * Shallow-merges consumer overrides over the defaults, so `labels` can carry a
+ * single key without restating the rest.
+ */
+export function resolveCascaderLabels(
+  labels?: Partial<CascaderLabels>
+): CascaderLabels {
+  if (!labels) return CASCADER_LABELS
+  return { ...CASCADER_LABELS, ...labels }
+}
+
+/** Resolves the search placeholder, which may be a string or a function. */
+export function resolveCascaderSearchLabel(
+  labels: CascaderLabels,
+  parentLabel?: string
+): string {
+  return typeof labels.search === "function"
+    ? labels.search(parentLabel)
+    : labels.search
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader-item.tsx b/apps/web/src/components/reui/cascader/cascader-item.tsx
new file mode 100644
index 0000000..76701ca
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-item.tsx
@@ -0,0 +1,1082 @@
+"use client"
+
+import * as React from "react"
+import {
+  useCascaderActions,
+  useCascaderRender,
+  useCascaderState,
+} from "@/components/reui/cascader/cascader-context"
+import {
+  getCascaderCount,
+  getCascaderMoreParent,
+  getCascaderPath,
+  isCascaderMoreNode,
+} from "@/components/reui/cascader/cascader-lib"
+import type {
+  CascaderLoadState,
+  CascaderNode,
+} from "@/components/reui/cascader/cascader-types"
+import { Combobox as ComboboxPrimitive } from "@base-ui/react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { Spinner } from "@authportal/ui/components/spinner"
+import { LoaderCircleIcon, MinusIcon, CheckIcon, RotateCwIcon, ChevronRightIcon } from "lucide-react"
+
+// Base UI extends its synthetic events with a handler-veto escape hatch.
+type VetoableEvent = { preventBaseUIHandler?: () => void }
+
+/** A row press. The veto hook is optional: an `as="button"` row is outside Base
+ *  UI's listbox and gets a plain React event. */
+export type CascaderRowEvent = React.MouseEvent<HTMLElement> & VetoableEvent
+
+// Each style's inline inset, as a variable: a row and its absolutely positioned
+// check have to land on the same number, in LOGICAL properties. These eight
+// numbers MIRROR the shared style sheets; keep them in step with
+// `registry/styles/style-*.css`.
+const ROW_INSET_CLASS =
+  "[--cascader-row-inset:6px]"
+
+// Both insets equal, for a row with no check. `!` because a consumer may not
+// import the sheets into `layer(base)`, where the class would win on order.
+const ROW_FLUSH_CLASS =
+  "ps-[var(--cascader-row-inset,8px)]! pe-[var(--cascader-row-inset,8px)]!"
+
+// The same start inset plus room for the check. A flat `pr-8` is wrong in five
+// of the eight styles: 4px of slack in nova, 8px short in maia, luma and sera,
+// and no gutter at all in mira, whose check then overlaps its own label.
+const ROW_GUTTER_CLASS =
+  "ps-[var(--cascader-row-inset,8px)]! pe-[calc(var(--cascader-row-inset,8px)*2_+_16px)]!"
+
+// The check's box, inset to match the row's. A physical `right-2` neither
+// mirrors under RTL nor tracks the style's inset; `right-auto` comes with the
+// logical `end-*`, because width + `left` + `right` is over-constrained.
+const INDICATOR_CLASS =
+  "pointer-events-none absolute flex items-center justify-center size-4 end-[var(--cascader-row-inset,8px)]! rtl:right-auto!"
+
+// The row's type, gap, radius and icon size per style. No horizontal padding:
+// every row pairs this with `ROW_FLUSH_CLASS` or `ROW_GUTTER_CLASS`.
+const ROW_THEME_CLASS =
+  "data-highlighted:bg-accent data-highlighted:text-accent-foreground not-data-[variant=destructive]:data-highlighted:**:text-accent-foreground [&_svg:not([class*='size-'])]:size-4 rounded-md py-1"
+
+/**
+ * The row's gap and type, per style, held apart from the rest of the theme.
+ *
+ * A row that pins its own gap or text size takes `ROW_SHELL_CLASS` and leaves
+ * these out, because a `style-<name>:` utility is emitted AFTER the plain one
+ * it would have to lose to. Not receiving the token beats overriding it with
+ * `!`, which a consumer then has to fight in turn.
+ */
+const ROW_GAP_CLASS =
+  "gap-2"
+
+const ROW_TEXT_CLASS =
+  "text-sm"
+
+const ROW_SHELL_CLASS = `${ROW_THEME_CLASS} relative flex w-full cursor-default items-center outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 ${ROW_INSET_CLASS}`
+
+const ROW_CLASS = `${ROW_SHELL_CLASS} ${ROW_GAP_CLASS} ${ROW_TEXT_CLASS}`
+
+const CASCADER_ACTION_INSET_CLASS = `${ROW_INSET_CLASS} ${ROW_FLUSH_CLASS}`
+
+/** A footer COMMAND: the row theme, so it cannot drift from the list, plus the
+ *  hover and `focus-visible` fills a plain button never gets. Fills, never a
+ *  ring: a ring under rows that all paint with a fill read as a different
+ *  widget bolted on. `focus-visible`, not `focus`, so a pointer press does not
+ *  leave a command painted as if it were still hovered. Disabled keys off
+ *  `aria-disabled`, not `:disabled`, to keep it FOCUSABLE: a footer whose only
+ *  row is disabled has no tab stop. */
+export const CASCADER_ACTION_CLASS = `${ROW_SHELL_CLASS} ${ROW_TEXT_CLASS} ${ROW_FLUSH_CLASS} hover:bg-accent hover:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground cursor-pointer gap-2 transition-colors aria-disabled:pointer-events-none aria-disabled:opacity-50`
+
+// The box around the affordances that are not the row. 20px around a 16px icon,
+// the outer 2px cancelled at the call site; 24px would set the row height.
+const AFFORDANCE_BOX_CLASS =
+  "flex size-5 shrink-0 items-center justify-center rounded-sm"
+
+// What makes an affordance read as pressable on an already highlighted row. Not
+// `hover:bg-accent`: the row is `bg-accent` under the pointer, so the chip would
+// be invisible. `!` and `**:` for the `CHECKBOX_MARK_CLASS` reason.
+const AFFORDANCE_HOVER_CLASS =
+  "transition-[background-color,box-shadow,color] hover:bg-background hover:text-foreground! hover:**:text-foreground! hover:shadow-xs"
+
+// The selection MARK's colour, pinned so nothing can repaint it: every row
+// carries a DESCENDANT highlight rule, and a mark is STATE. Pinned TWICE
+// because icon sets draw with `fill`/`stroke="currentColor"`, which the
+// `<path>` inherits and resolves against the PATH's own `color`. Both halves
+// are asserted in `cascader-behavior.test.tsx`.
+const CHECKBOX_MARK_CLASS =
+  "text-primary-foreground! **:text-primary-foreground!"
+const INDICATOR_MARK_CLASS = "text-foreground! **:text-foreground!"
+
+// Milliseconds the pointer must rest on a branch row before
+// `expandTrigger="hover"` drills in: long enough that a pointer crossing the
+// column on its way elsewhere opens nothing, short enough to read as immediate.
+const CASCADER_HOVER_EXPAND_DELAY = 150
+
+export interface CascaderItemProps extends Omit<
+  ComboboxPrimitive.Item.Props,
+  "value" | "children" | "className" | "style" | "onClick" | "onMouseUp"
+> {
+  /** No state callback: the row merges `className` and `style` itself. */
+  className?: string
+  style?: React.CSSProperties
+  onClick?: (event: CascaderRowEvent) => void
+  onMouseUp?: (event: CascaderRowEvent) => void
+  node: CascaderNode
+  /** Explicit render index. Required while virtualized and DELIBERATELY IGNORED
+   *  otherwise: it self-registers the row and breaks `aria-activedescendant`. */
+  index?: number
+  /** Indentation depth. Drives `--cascader-indent` in tree mode. */
+  depth?: number
+  /** Renders the ancestor chain under the label, for deep and global search. */
+  showPath?: boolean
+  /** `option` renders a real `Combobox.Item`; `button` renders identical markup
+   *  outside the listbox, for the ancestor columns in columns mode. */
+  as?: "option" | "button"
+  /** Tree mode: this row is an expanded branch. */
+  expanded?: boolean
+  /** Indent each depth by this many pixels. Tree mode only. */
+  indent?: number
+  /** Whether the node has children. Defaults to the cascader's own answer, as do
+   *  the three below: callers pass them because they already hold the level,
+   *  which keeps a memoised row off the volatile context. */
+  branch?: boolean
+  /** Whether the node may be committed. Defaults to the cascader's own answer. */
+  selectable?: boolean
+  /** Whether the node is currently selected. Defaults to the cascader's answer. */
+  selected?: boolean
+  /** Some but not all of the loaded subtree selected. `cascade` only. */
+  indeterminate?: boolean
+  /** Selected nodes below this one, at any depth. Drives the trailing count. */
+  selectedCount?: number
+  /** Paging row only: a request for this level is in flight. */
+  loading?: boolean
+  /** Paging row only: this level's last request failed. */
+  error?: boolean
+  /** Branch row only: this node's OWN children are being fetched. The chevron
+   *  (or, in tree mode, the expander) becomes a spinner IN PLACE, in the same
+   *  16px box: no skeleton row appears below, nothing reflows. */
+  childrenLoading?: boolean
+  /** Branch row only: the last fetch of this node's children failed. The same
+   *  box becomes the retry. The press path is unchanged: it goes through
+   *  `navigate`, which refires the failed level rather than moving. */
+  childrenError?: boolean
+  children?: React.ReactNode
+}
+
+/** One row. Branch presses navigate instead of selecting, vetoed here with
+ *  `preventBaseUIHandler()` on `onClick` (Enter too) and on `onMouseUp`. */
+const CascaderItem = React.memo(function CascaderItem({
+  node,
+  index,
+  depth,
+  showPath = false,
+  as = "option",
+  expanded,
+  indent = 16,
+  branch: branchProp,
+  selectable: selectableProp,
+  selected: selectedProp,
+  indeterminate: indeterminateProp,
+  selectedCount: selectedCountProp,
+  loading,
+  error,
+  childrenLoading = false,
+  childrenError = false,
+  className,
+  children,
+  onClick,
+  onMouseUp,
+  style,
+  ...props
+}: CascaderItemProps) {
+  // The ACTIONS context only: the state context republishes on every keystroke.
+  const {
+    index: treeIndex,
+    mode,
+    labels,
+    isBranch,
+    isSelectable,
+    isDisabled,
+    isSelected,
+    isIndeterminate,
+    selectedDescendantCount,
+    multiple,
+    branchesSelectable,
+    indicator: indicatorEnabled,
+    expandTrigger = "click",
+    navigate,
+    navigateAt,
+    toggleExpanded,
+    commit,
+    getState,
+    virtualized,
+    loadMore,
+    retryLevel,
+  } = useCascaderActions()
+  // Render props come from an always-current context, or a closure goes stale.
+  const { renderItem, renderLabel } = useCascaderRender()
+
+  const branch = branchProp ?? isBranch(node)
+  const selectable = selectableProp ?? isSelectable(node)
+  // An ancestor's flag counts: a search hit or a revealed path can list a row
+  // inside a branch nobody may open. Asked here, off the near-stable context,
+  // so no new prop and only a row that re-renders pays the ancestor walk.
+  const disabled = isDisabled(node)
+  const selected = selectedProp ?? isSelected(node)
+  // A selected node is never also partially selected (a dash in a filled box).
+  const indeterminate =
+    !selected && (indeterminateProp ?? isIndeterminate(node))
+  const count = branch ? getCascaderCount(treeIndex, node) : 0
+  const nodeDepth = depth ?? treeIndex.depthOf.get(node.value) ?? 0
+
+  // O(1): the cascader publishes a map of selected-descendant counts, because a
+  // row walking its own subtree is `rows x descendants`, paid every keystroke.
+  const selectedDescendants = branch
+    ? (selectedCountProp ?? selectedDescendantCount(node))
+    : 0
+  // `multiple` only: with a single selection the trigger, the breadcrumb and
+  // the leaf's own check already say where it is, so swapping a branch's real
+  // child total ("24") for a permanent "1" would trade a useful number away.
+  const showsSelectedCount = multiple && selectedDescendants > 0
+  const trailingCount = showsSelectedCount ? selectedDescendants : count
+  // Shown selected or not: suppressing it under a checked branch read as data
+  // loss, and the row's TWO trailing columns mean the count never has to share
+  // a slot with the check.
+  const showCount = trailingCount > 0
+
+  // Where a multi-select tree puts its checkbox: at the HEAD of the row, since a
+  // trailing box does not follow the label stagger. Per-LIST, never per-row, or
+  // the labels below an unselectable row step back out.
+  const leadingCheckbox = mode === "tree" && multiple
+
+  // Whether this row draws a MARK, and so whether it reserves the gutter one
+  // needs. `|| multiple` is the scope of the opt-out: a checkbox is the
+  // selection CONTROL, so `indicator={false}` is a no-op in multi-select.
+  const showsIndicator = indicatorEnabled || multiple
+
+  const veto = React.useCallback((event: VetoableEvent) => {
+    event.preventBaseUIHandler?.()
+  }, [])
+
+  const handleClick = React.useCallback(
+    (event: CascaderRowEvent) => {
+      onClick?.(event)
+      if (disabled) return
+      if (branch && !selectable) {
+        veto(event)
+        navigate(node)
+      }
+    },
+    [onClick, node, disabled, branch, selectable, veto, navigate]
+  )
+
+  const handleMouseUp = React.useCallback(
+    (event: CascaderRowEvent) => {
+      onMouseUp?.(event)
+      if (disabled) return
+      if (branch && !selectable) veto(event)
+    },
+    [onMouseUp, disabled, branch, selectable, veto]
+  )
+
+  // The tree expander's own press. With `selectable="any"` the row press
+  // commits, and under `cascade` that selected a whole subtree while the row
+  // stayed collapsed, so expanding needs its own target. `stopPropagation`
+  // before the veto, so Base UI's handler never runs, and no role: nesting
+  // one in `role="option"` fails axe. `navigate` fetches BEFORE it opens.
+  // A disabled row may still CLOSE what `expanded` opened, never open: a row
+  // only a query holds open is not in `expanded`, and the toggle would add it.
+  const handleExpanderClick = React.useCallback(
+    (event: CascaderRowEvent) => {
+      event.stopPropagation()
+      veto(event)
+      if (expanded) {
+        if (!disabled || getState().expanded.has(node.value)) {
+          toggleExpanded(node.value)
+        }
+      } else if (!disabled) navigate(node)
+    },
+    [veto, node, disabled, expanded, getState, toggleExpanded, navigate]
+  )
+
+  const handleExpanderMouseUp = React.useCallback(
+    (event: CascaderRowEvent) => {
+      // Base UI treats a drag-select mouseup as a commit; this is not one.
+      event.stopPropagation()
+      veto(event)
+    },
+    [veto]
+  )
+
+  const handleChevronClick = React.useCallback(
+    (event: CascaderRowEvent) => {
+      event.stopPropagation()
+      veto(event)
+      if (disabled) return
+      // `navigate` falls through to `pushLevel`, which APPENDS: right in the
+      // deepest column, but from an ancestor column it duplicated the level and
+      // corrupted the path. `navigateAt` rebuilds the trail from this depth.
+      if (as === "button") navigateAt(node, depth ?? 0)
+      else navigate(node)
+    },
+    [veto, node, disabled, as, navigateAt, depth, navigate]
+  )
+
+  const handleChevronMouseUp = React.useCallback(
+    (event: CascaderRowEvent) => veto(event),
+    [veto]
+  )
+
+  // Keeps focus in the search field: Base UI prevents the mousedown default for
+  // option rows, and focusing a `tabindex="-1"` trail row kills every key.
+  const handleButtonMouseDown = React.useCallback(
+    (event: React.MouseEvent<HTMLElement>) => {
+      event.preventDefault()
+    },
+    []
+  )
+
+  const handleButtonClick = React.useCallback(
+    (event: CascaderRowEvent) => {
+      onClick?.(event)
+      if (disabled) return
+      if (branch && !selectable) {
+        // Button rows only exist in the columns trail, where `depth` is the
+        // column's own depth, so navigating replaces the trail from here.
+        navigateAt(node, depth ?? 0)
+        return
+      }
+      if (selectable) commit(node)
+    },
+    [onClick, node, disabled, branch, selectable, navigateAt, depth, commit]
+  )
+
+  // The paging row's press, never a selection, whatever `selectable` says.
+  const handleMoreClick = React.useCallback(
+    (event: CascaderRowEvent) => {
+      onClick?.(event)
+      veto(event)
+      const parent = getCascaderMoreParent(node)
+      if (parent == null) return
+      if (error) retryLevel(parent)
+      else if (!loading) loadMore(parent)
+    },
+    [onClick, veto, node, error, loading, retryLevel, loadMore]
+  )
+
+  // `expandTrigger="hover"`: resting on a BRANCH row in the ACTIVE column drills
+  // in after a delay. The deepest column of columns mode only, and it never
+  // commits, so a pointer crossing the panel cannot change the value.
+  const hoverNavigates =
+    expandTrigger === "hover" &&
+    mode === "columns" &&
+    as === "option" &&
+    branch &&
+    !disabled
+  const hoverTimerRef = React.useRef<number | null>(null)
+
+  const cancelHoverNavigate = React.useCallback(() => {
+    if (hoverTimerRef.current == null) return
+    window.clearTimeout(hoverTimerRef.current)
+    hoverTimerRef.current = null
+  }, [])
+
+  const handleHoverPointerEnter = React.useCallback(() => {
+    cancelHoverNavigate()
+    hoverTimerRef.current = window.setTimeout(() => {
+      hoverTimerRef.current = null
+      navigate(node)
+    }, CASCADER_HOVER_EXPAND_DELAY)
+  }, [cancelHoverNavigate, navigate, node])
+
+  // Drilling in demotes this column to the trail WITHOUT unmounting the row, so
+  // a pending timer has to die or it fires `navigate` from an inactive column.
+  React.useEffect(() => {
+    if (!hoverNavigates) cancelHoverNavigate()
+  }, [hoverNavigates, cancelHoverNavigate])
+  React.useEffect(() => cancelHoverNavigate, [cancelHoverNavigate])
+
+  /* ------------------------------- paging row ------------------------------ */
+
+  if (isCascaderMoreNode(node)) {
+    const text = error
+      ? labels.error
+      : loading
+        ? node.count
+          ? labels.loadingMore
+          : labels.loading
+        : labels.loadMore
+
+    const moreStyle =
+      mode === "tree" && nodeDepth > 0
+        ? ({
+            ...style,
+            "--cascader-indent": `${nodeDepth * indent}px`,
+          } as React.CSSProperties)
+        : style
+
+    const moreShared = {
+      "data-slot": "cascader-item",
+      "data-more": "",
+      "data-state": error ? "error" : loading ? "loading" : "idle",
+      "data-depth": nodeDepth,
+      style: moreStyle,
+      className: cn(
+        ROW_SHELL_CLASS,
+        ROW_FLUSH_CLASS,
+        "text-muted-foreground justify-center gap-1.5 text-xs",
+        !error && !loading && "hover:text-foreground",
+        mode === "tree" &&
+          "ps-[calc(var(--cascader-row-inset,8px)_+_var(--cascader-indent,0px))]!",
+        className
+      ),
+    }
+
+    const moreBody = children ?? (
+      <>
+        {loading ? (
+          <LoaderCircleIcon className="size-3.5 animate-spin" aria-hidden />
+        ) : null}
+        <span>{text}</span>
+        {/* TEXT, not a button: a focusable element inside a `role="option"`
+            row is a `nested-interactive` violation. */}
+        {error ? (
+          <span className="text-foreground font-medium">{labels.retry}</span>
+        ) : null}
+      </>
+    )
+
+    if (as === "button") {
+      const buttonProps = { ...(props as React.ComponentProps<"button">) }
+      delete buttonProps["aria-setsize"]
+      delete buttonProps["aria-posinset"]
+      delete buttonProps["aria-level"]
+
+      return (
+        <button
+          type="button"
+          {...moreShared}
+          tabIndex={-1}
+          onClick={handleMoreClick}
+          {...buttonProps}
+        >
+          {moreBody}
+        </button>
+      )
+    }
+
+    return (
+      <ComboboxPrimitive.Item
+        {...moreShared}
+        value={node}
+        {...(virtualized && index != null ? { index } : null)}
+        {...(mode === "tree"
+          ? { role: "treeitem" as const, "aria-level": nodeDepth + 1 }
+          : null)}
+        onClick={handleMoreClick}
+        onMouseUp={veto}
+        {...props}
+      >
+        {moreBody}
+      </ComboboxPrimitive.Item>
+    )
+  }
+
+  const itemState = {
+    branch,
+    selected,
+    disabled,
+    depth: nodeDepth,
+    count,
+    path: showPath ? getCascaderPath(treeIndex, node.value).slice(0, -1) : [],
+  }
+
+  const custom = renderItem?.(node, itemState)
+  const customLabel = renderLabel?.(node, itemState)
+
+  // What the markup cannot say: a branch would announce "Person 24", a naked
+  // number. Trail rows are outside the listbox, so they need words for state.
+  const srDetails = [
+    branch ? labels.itemCount(count) : null,
+    showsSelectedCount ? labels.selectedCount(selectedDescendants) : null,
+    branch && mode !== "tree" ? labels.branchAffordance : null,
+    as === "button" && selected ? labels.selectedState : null,
+    // Option rows say this with `aria-checked="mixed"`; `role="button"` allows
+    // neither that nor `aria-selected`, so a trail row says it in words.
+    as === "button" && indeterminate ? labels.partiallySelectedState : null,
+  ]
+    .filter(Boolean)
+    .map((detail) => `, ${detail}`)
+    .join("")
+
+  // Extracted because tree mode renders it INLINE at the head of the row. It
+  // reads `data-selected` off the ROW, so it also works on the trail rows.
+  const checkbox = (
+    <span
+      data-slot="cascader-item-checkbox"
+      className="border-input in-data-[selected]:bg-primary in-data-[selected]:border-primary in-data-[selected]:text-primary-foreground in-data-[indeterminate]:bg-primary in-data-[indeterminate]:border-primary in-data-[indeterminate]:text-primary-foreground flex size-4 shrink-0 items-center justify-center rounded-[4px] border transition-colors"
+    >
+      {/* Colour declared ON THE ICON with `!`; see `CHECKBOX_MARK_CLASS`. */}
+      {indeterminate ? (
+        <MinusIcon data-slot="cascader-item-dash" className={cn(CHECKBOX_MARK_CLASS, "size-3")} />
+      ) : (
+        <CheckIcon data-slot="cascader-item-tick" className={cn(
+                              CHECKBOX_MARK_CLASS,
+                              "size-3 opacity-0 in-data-[selected]:opacity-100"
+                            )} />
+      )}
+    </span>
+  )
+
+  const indicator = (
+    <>
+      {multiple ? (
+        checkbox
+      ) : (
+        <CheckIcon data-slot="cascader-item-check" className={cn("pointer-events-none", INDICATOR_MARK_CLASS)} />
+      )}
+    </>
+  )
+
+  const body = custom ?? children ?? (
+    <>
+      {/* Tree mode expands in place, so the branch marker leads the row. */}
+      {mode === "tree" && branch ? (
+        <span
+          data-slot="cascader-item-expander"
+          /* Pure affordance: the row itself carries `aria-expanded`. */
+          aria-hidden="true"
+          data-state={
+            childrenError ? "error" : childrenLoading ? "loading" : "idle"
+          }
+          onClick={handleExpanderClick}
+          onMouseUp={handleExpanderMouseUp}
+          className={cn(
+            "-ms-0.5",
+            childrenError ? "text-destructive" : "text-muted-foreground",
+            AFFORDANCE_BOX_CLASS,
+            AFFORDANCE_HOVER_CLASS,
+            /* A disabled row is `pointer-events-none`; only while open does its
+               expander take the pointer back, to close what `expanded` opened. */
+            disabled && expanded && "pointer-events-auto",
+            childrenLoading && "pointer-events-none"
+          )}
+        >
+          {childrenLoading ? (
+            <Spinner aria-hidden="true" className="size-4" />
+          ) : childrenError ? (
+            <RotateCwIcon className="size-4" />
+          ) : (
+            <ChevronRightIcon className={cn(
+                                              "size-4 transition-transform",
+                                              /* Collapsed it points INTO the level, so it mirrors; expanded
+                                                 it points DOWN, the same in both writing modes, so the mirror
+                                                 has to come off or `scaleX(-1)` composed with `rotate(90deg)`
+                                                 lands it pointing up. `rtl:rotate-90` beside `rotate-90` was
+                                                 a no-op that only looked like it handled this. */
+                                              expanded ? "rotate-90" : "rtl:-scale-x-100"
+                                            )} />
+          )}
+        </span>
+      ) : mode === "tree" ? (
+        // A LEAF's expander slot, reserved and empty: without it a leaf's label
+        // started 28px off its sibling branches' and read as one level up.
+        <span
+          data-slot="cascader-item-expander-spacer"
+          aria-hidden="true"
+          className={cn("-ms-0.5", AFFORDANCE_BOX_CLASS)}
+        />
+      ) : null}
+
+      {/* Tree + multi-select: the box leads the row, and an unselectable row
+          still reserves its width. */}
+      {leadingCheckbox ? (
+        selectable ? (
+          checkbox
+        ) : (
+          <span
+            data-slot="cascader-item-checkbox-spacer"
+            aria-hidden="true"
+            className="size-4 shrink-0"
+          />
+        )
+      ) : null}
+
+      {node.icon ? (
+        <span
+          data-slot="cascader-item-icon"
+          className="text-muted-foreground flex shrink-0 items-center justify-center"
+        >
+          {node.icon}
+        </span>
+      ) : null}
+
+      {/* The row box is sized for pieces side by side; this one stacks, so it
+          restates the gap: 8px reads as a paragraph break, not a subtitle. */}
+      <span className="flex min-w-0 flex-1 flex-col items-start gap-0.5">
+        {customLabel ?? (
+          <>
+            <span className="w-full truncate text-start">{node.label}</span>
+            {node.description ? (
+              <span
+                data-slot="cascader-item-description"
+                className="text-muted-foreground w-full truncate text-start text-xs"
+              >
+                {node.description}
+              </span>
+            ) : null}
+          </>
+        )}
+        {showPath ? <CascaderItemPath node={node} /> : null}
+      </span>
+
+      {/* The count is a bare number, and nothing else says a branch opens. */}
+      {srDetails ? (
+        <span data-slot="cascader-item-details" className="sr-only">
+          {srDetails}
+        </span>
+      ) : null}
+
+      {/* Tree mode expands in place, so it has no drill-in chevron. */}
+      {branch && mode !== "tree" ? (
+        <span
+          data-slot="cascader-item-trailing"
+          aria-hidden="true"
+          className="text-muted-foreground ms-auto flex shrink-0 items-center gap-1 text-xs tabular-nums"
+        >
+          {showCount ? (
+            <span
+              data-slot="cascader-item-count"
+              /* The marker a consumer (and a test) reads to tell the two
+                 numbers apart without matching on a colour class. */
+              {...(showsSelectedCount ? { "data-selected-count": "" } : null)}
+              className={cn(showsSelectedCount && "text-primary!")}
+            >
+              {trailingCount}
+            </span>
+          ) : null}
+          {/* ONLY the chevron is the drill target: sharing a hit area with
+              the count made a number pressable. */}
+          <span
+            data-slot="cascader-item-chevron"
+            data-state={
+              childrenError ? "error" : childrenLoading ? "loading" : "idle"
+            }
+            onClick={selectable ? handleChevronClick : undefined}
+            onMouseUp={selectable ? handleChevronMouseUp : undefined}
+            onMouseDown={as === "button" ? handleButtonMouseDown : undefined}
+            className={cn(
+              /* Cancels the box's outer slack, so the icon keeps its column. */
+              "-me-0.5",
+              AFFORDANCE_BOX_CLASS,
+              selectable && AFFORDANCE_HOVER_CLASS,
+              childrenError && "text-destructive",
+              childrenLoading && "pointer-events-none"
+            )}
+          >
+            {childrenLoading ? (
+              <Spinner aria-hidden="true" className="size-4" />
+            ) : childrenError ? (
+              <RotateCwIcon className="size-4" />
+            ) : (
+              <ChevronRightIcon className="size-4 rtl:-scale-x-100" />
+            )}
+          </span>
+        </span>
+      ) : null}
+
+      {branch && mode === "tree" && showCount ? (
+        <span
+          data-slot="cascader-item-count"
+          {...(showsSelectedCount ? { "data-selected-count": "" } : null)}
+          /* The count is spoken by the sr-only details span instead. */
+          aria-hidden="true"
+          className={cn(
+            "text-muted-foreground ms-auto shrink-0 text-xs tabular-nums",
+            showsSelectedCount && "text-primary!"
+          )}
+        >
+          {trailingCount}
+        </span>
+      ) : null}
+
+      {/* No trailing indicator when a tree's box led the row, or when
+          `indicator={false}` opted out. See `showsIndicator`. */}
+      {selectable && !leadingCheckbox && showsIndicator ? (
+        as === "button" ? (
+          // No ItemIndicator outside Base UI: `data-selected` drives it.
+          (multiple || selected) && (
+            <span
+              data-slot="cascader-item-indicator"
+              className={INDICATOR_CLASS}
+            >
+              {indicator}
+            </span>
+          )
+        ) : (
+          <ComboboxPrimitive.ItemIndicator
+            /* Kept mounted for a partial selection too: the row is not
+               selected, so Base UI would unmount the box the dash lives in. */
+            keepMounted={multiple || indeterminate}
+            render={
+              <span
+                data-slot="cascader-item-indicator"
+                className={INDICATOR_CLASS}
+              />
+            }
+          >
+            {indicator}
+          </ComboboxPrimitive.ItemIndicator>
+        )
+      ) : null}
+    </>
+  )
+
+  const rowStyle =
+    mode === "tree" && nodeDepth > 0
+      ? ({
+          ...style,
+          "--cascader-indent": `${nodeDepth * indent}px`,
+        } as React.CSSProperties)
+      : style
+
+  const shared = {
+    "data-slot": "cascader-item",
+    "data-branch": branch || undefined,
+    "data-selected": selected || undefined,
+    "data-indeterminate": indeterminate || undefined,
+    "data-depth": nodeDepth,
+    "data-expanded": expanded || undefined,
+    // No `aria-level`: `role="option"` allows only `aria-selected`,
+    // `aria-checked`, `aria-posinset` and `aria-setsize`, and a `role="button"`
+    // trail row allows none of the four. Only tree mode has a role that takes a
+    // level, and it adds one below.
+    style: rowStyle,
+    className: cn(
+      ROW_CLASS,
+      /* Three separate reasons to hand the check gutter back. A multi-select
+         tree's box leads the row, so the gutter would be 24px of dead space;
+         `indicator={false}` drops the check, and keeping the gutter would park
+         the count and the chevron one gutter in from an edge nothing sits on;
+         and for branches the question is per-LIST, not per-row, because the old
+         `branch && !selectable` put neighbouring chevrons on 24px and 6px in
+         nova. One `pe-*` is emitted either way, so nothing here depends on
+         class-merge order. */
+      leadingCheckbox || !showsIndicator || (branch && !branchesSelectable)
+        ? ROW_FLUSH_CLASS
+        : ROW_GUTTER_CLASS,
+      /* ADDED to the style's own inset, never substituted: replacing it put
+         depth 0 at 12px and depth 1 at 16px in maia, luma and sera, a 4px step.
+         `_+_` because Tailwind's parser splits on whitespace. */
+      mode === "tree" &&
+        "ps-[calc(var(--cascader-row-inset,8px)_+_var(--cascader-indent,0px))]!",
+      className
+    ),
+  }
+
+  if (as === "button") {
+    const buttonProps = { ...(props as React.ComponentProps<"button">) }
+    // `role="button"` allows none of these, so they are dropped, not passed.
+    delete buttonProps["aria-setsize"]
+    delete buttonProps["aria-posinset"]
+    delete buttonProps["aria-level"]
+
+    return (
+      <button
+        type="button"
+        {...shared}
+        /* Focus stays in the search input; the trail uses ArrowLeft. */
+        tabIndex={-1}
+        disabled={disabled}
+        aria-disabled={disabled || undefined}
+        onClick={handleButtonClick}
+        onMouseDown={handleButtonMouseDown}
+        {...buttonProps}
+      >
+        {body}
+      </button>
+    )
+  }
+
+  return (
+    <ComboboxPrimitive.Item
+      {...shared}
+      value={node}
+      /* THE one gate for the explicit index: supply one outside virtualized mode
+         and the first arrow key leaves `aria-activedescendant` pointing at
+         nothing. */
+      {...(virtualized && index != null ? { index } : null)}
+      disabled={disabled}
+      /* Conditional spread, never `role={... : undefined}`: `mergeProps`
+         iterates own keys, so `undefined` would delete `role="option"`. */
+      {...(mode === "tree"
+        ? {
+            role: "treeitem" as const,
+            "aria-level": nodeDepth + 1,
+            ...(branch ? { "aria-expanded": !!expanded } : null),
+          }
+        : branch
+          ? { "aria-haspopup": "listbox" as const }
+          : null)}
+      /* Only ever `mixed`: a selected row already says so with `aria-selected`,
+         and two selection attributes on one row is noise. */
+      {...(indeterminate ? { "aria-checked": "mixed" as const } : null)}
+      {...(hoverNavigates
+        ? {
+            onPointerEnter: handleHoverPointerEnter,
+            onPointerLeave: cancelHoverNavigate,
+          }
+        : null)}
+      onClick={handleClick}
+      onMouseUp={handleMouseUp}
+      {...props}
+    >
+      {body}
+    </ComboboxPrimitive.Item>
+  )
+})
+
+/** Ancestor chain under a deep or global hit: "Name" alone is ambiguous. */
+function CascaderItemPath({ node }: { node: CascaderNode }) {
+  const { index, labels } = useCascaderActions()
+  const ancestors = getCascaderPath(index, node.value).slice(0, -1)
+  if (!ancestors.length) return null
+
+  return (
+    <span
+      data-slot="cascader-item-path"
+      className="text-muted-foreground flex w-full items-center gap-0.5 truncate text-start text-xs"
+    >
+      {ancestors.map((ancestor, i) => (
+        <React.Fragment key={ancestor.value}>
+          {i > 0 ? (
+            <span aria-hidden="true">{labels.pathSeparator}</span>
+          ) : null}
+          <span className="truncate">{ancestor.label}</span>
+        </React.Fragment>
+      ))}
+    </span>
+  )
+}
+
+/** Every load-derived prop a row needs. A PAGING row reports the level it
+ *  belongs to, a BRANCH row the level it OWNS; mutually exclusive, so one call
+ *  answers both. Exported because a memoised row cannot read them itself. */
+export function getCascaderMoreProps(
+  node: CascaderNode,
+  loadStates: ReadonlyMap<string, CascaderLoadState>
+): {
+  loading: boolean
+  error: boolean
+  childrenLoading: boolean
+  childrenError: boolean
+} {
+  const parent = getCascaderMoreParent(node)
+  if (parent == null) {
+    const own = loadStates.get(node.value)
+    return {
+      loading: false,
+      error: false,
+      childrenLoading: !!own?.loading,
+      childrenError: !!own?.error,
+    }
+  }
+  const state = loadStates.get(parent)
+  return {
+    loading: !!state?.loading,
+    error: !!state?.error,
+    childrenLoading: false,
+    childrenError: false,
+  }
+}
+
+export interface CascaderItemsProps {
+  /** Replaces the default row for every item. */
+  children?: (node: CascaderNode, index: number) => React.ReactNode
+}
+
+/** Whatever the active view is: the current level, the deepest column, or the
+ *  flattened tree rows. Lives here so `cascader.tsx` never imports a row
+ *  component, which would cycle with the context. `index` is deliberately not
+ *  passed; see `CascaderItemProps`. */
+function CascaderItems({ children }: CascaderItemsProps) {
+  const { mode, isBranch, isSelectable, isSelected, isIndeterminate } =
+    useCascaderActions()
+  const { renderedItems, deepResults, treeRows, loadStates } =
+    useCascaderState()
+  const showPath = deepResults !== null
+
+  // Answered once here, as plain booleans, so `React.memo` can skip a row.
+  if (mode === "tree") {
+    return (
+      <>
+        {treeRows.map((row, i) =>
+          children ? (
+            <React.Fragment key={row.node.value}>
+              {children(row.node, i)}
+            </React.Fragment>
+          ) : (
+            <CascaderItem
+              key={row.node.value}
+              node={row.node}
+              depth={row.depth}
+              expanded={row.expanded}
+              branch={row.branch}
+              selectable={isSelectable(row.node)}
+              selected={isSelected(row.node)}
+              indeterminate={isIndeterminate(row.node)}
+              {...getCascaderMoreProps(row.node, loadStates)}
+              aria-setsize={row.setSize}
+              aria-posinset={row.posInSet}
+            />
+          )
+        )}
+      </>
+    )
+  }
+
+  return (
+    <>
+      {renderedItems.map((node, i) =>
+        children ? (
+          <React.Fragment key={node.value}>{children(node, i)}</React.Fragment>
+        ) : (
+          <CascaderItem
+            key={node.value}
+            node={node}
+            showPath={showPath}
+            branch={isBranch(node)}
+            selectable={isSelectable(node)}
+            selected={isSelected(node)}
+            indeterminate={isIndeterminate(node)}
+            {...getCascaderMoreProps(node, loadStates)}
+            aria-setsize={renderedItems.length}
+            aria-posinset={i + 1}
+          />
+        )
+      )}
+    </>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                          Group / Label / Separator                         */
+/* -------------------------------------------------------------------------- */
+
+// Whether a `CascaderLabel` has a group to name: Base UI's `Combobox.GroupLabel`
+// THROWS when there is none, and a heading is useful outside a group.
+const CascaderGroupContext = React.createContext(false)
+
+// A heading over a run of rows. All eight styles are spelled out because the
+// type is not uniform (sera is uppercase), and the inset is the row's own.
+const CASCADER_LABEL_CLASS = `text-muted-foreground text-xs py-1.5 ${CASCADER_ACTION_INSET_CLASS} block truncate`
+
+// A rule between two runs. The inline margin is not the combobox separator's:
+// that cancels the container's padding with a per-style number, wrong in a
+// footer and 4px too much in lyra. `--cascader-list-pad` reaches the edge.
+const CASCADER_SEPARATOR_CLASS =
+  "h-px bg-border my-1 mx-[calc(var(--cascader-list-pad,4px)*-1)]! shrink-0"
+
+export interface CascaderGroupProps extends Omit<
+  ComboboxPrimitive.Group.Props,
+  "className"
+> {
+  /** Base UI also accepts a state callback here; the group has no state. */
+  className?: string
+}
+
+/** A run of related rows, named by the `CascaderLabel` inside it: the group is
+ *  `role="group"` and Base UI points its `aria-labelledby` at the label, where a
+ *  heading alone inside a listbox is dropped from the accessibility tree.
+ *  Grouping is composition, not data: `CascaderItems` renders one flat run per
+ *  level, so its indices line up with `listRef`. */
+function CascaderGroup({ className, ...props }: CascaderGroupProps) {
+  return (
+    <CascaderGroupContext.Provider value={true}>
+      <ComboboxPrimitive.Group
+        data-slot="cascader-group"
+        className={cn("flex flex-col", className)}
+        {...props}
+      />
+    </CascaderGroupContext.Provider>
+  )
+}
+
+export interface CascaderLabelProps extends Omit<
+  ComboboxPrimitive.GroupLabel.Props,
+  "className" | "style"
+> {
+  /** No state callback; outside a group this is not a Base UI part at all. */
+  className?: string
+  style?: React.CSSProperties
+}
+
+/** Inside a group: the real thing, with the id association Base UI wires up. */
+function CascaderGroupLabel({ className, ...props }: CascaderLabelProps) {
+  return (
+    <ComboboxPrimitive.GroupLabel
+      data-slot="cascader-label"
+      className={cn(CASCADER_LABEL_CLASS, className)}
+      {...props}
+    />
+  )
+}
+
+// Outside a group: the same heading as a plain element. A separate component
+// rather than a branch, so the hook count cannot change when a label moves in.
+function CascaderPlainLabel({ className, ...props }: CascaderLabelProps) {
+  const defaultProps = {
+    "data-slot": "cascader-label",
+    className: cn(CASCADER_LABEL_CLASS, className),
+  }
+
+  return useRender({
+    defaultTagName: "div",
+    render: props.render,
+    props: mergeProps<"div">(defaultProps, props),
+  })
+}
+
+/** A heading. Inside `CascaderGroup` it is the group's accessible name; outside
+ *  one (the footer flyout is a menu, not a listbox) it is decoration only. */
+function CascaderLabel(props: CascaderLabelProps) {
+  const grouped = React.useContext(CascaderGroupContext)
+  return grouped ? (
+    <CascaderGroupLabel {...props} />
+  ) : (
+    <CascaderPlainLabel {...props} />
+  )
+}
+
+export interface CascaderSeparatorProps extends Omit<
+  ComboboxPrimitive.Separator.Props,
+  "className"
+> {
+  /** Base UI also accepts a state callback here; only the orientation varies. */
+  className?: string
+}
+
+/** Decorative on purpose: Base UI's separator is `role="separator"`, which a
+ *  `listbox` may not own, and a run that needs separating for a screen reader
+ *  needs a `CascaderGroup`, not a line. A consumer can pass the role back. */
+function CascaderSeparator({ className, ...props }: CascaderSeparatorProps) {
+  return (
+    <ComboboxPrimitive.Separator
+      data-slot="cascader-separator"
+      role="presentation"
+      aria-hidden="true"
+      className={cn(CASCADER_SEPARATOR_CLASS, className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  CascaderGroup,
+  CascaderItem,
+  CascaderItems,
+  CascaderLabel,
+  CascaderSeparator,
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader-lib.tsx b/apps/web/src/components/reui/cascader/cascader-lib.tsx
new file mode 100644
index 0000000..1cce4c4
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-lib.tsx
@@ -0,0 +1,1012 @@
+import type {
+  CascaderCollapse,
+  CascaderFlatNode,
+  CascaderIndex,
+  CascaderNode,
+  CascaderPathSegment,
+  CascaderSelectable,
+} from "@/components/reui/cascader/cascader-types"
+
+/** Root level key in `childrenOf`. NUL-prefixed so no real value collides. */
+export const CASCADER_ROOT_KEY = "\u0000root"
+
+/**
+ * Paging pseudo-node prefix. Written as an escape sequence, not a raw 0x00
+ * byte: a literal NUL makes this module read as binary and `grep -I` skips it.
+ */
+export const CASCADER_MORE_PREFIX = "\u0000more:"
+
+/* -------------------------------------------------------------------------- */
+/*                                Scroll layout                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The four scroll classes. In the lib because `cascader-columns.tsx` needs them
+ * too and must not import `cascader.tsx`. Shell > bound > scrollport > rows.
+ */
+
+/**
+ * The bound. `min()` over an undefined custom property is an INVALID
+ * declaration that drops the whole max-height, hence the `100vh` fallback: an
+ * inline panel has no positioner, so no `--available-height`. `24rem` is the
+ * default cap, so the common case sets no variable at all.
+ */
+export const CASCADER_LIST_HEIGHT_CLASS =
+  "max-h-[min(var(--available-height,100vh),var(--cascader-max-height,24rem))]"
+
+/**
+ * Each style's list padding: rows take it as `padding`, the scrollport as
+ * `scroll-padding` floored at 4px so lyra's `0` does not strand a row.
+ * Mirrored per style from `registry/styles/style-*.css`; keep them in step.
+ */
+export const CASCADER_LIST_PAD_CLASS =
+  "[--cascader-list-pad:4px]"
+
+/** The scrollport: a `max-h-*` on the ScrollArea ROOT bounds nothing. */
+export const CASCADER_SCROLL_CLASS =
+  "size-full min-h-0 **:data-[slot=scroll-area-viewport]:h-full **:data-[slot=scroll-area-viewport]:overscroll-contain **:data-[slot=scroll-area-viewport]:scroll-py-[max(var(--cascader-list-pad,4px),4px)]"
+
+/** The rows' box; `data-empty:p-0` keeps an empty state from double inset. */
+export const CASCADER_ROWS_CLASS = "p-(--cascader-list-pad,4px) data-empty:p-0"
+
+/* -------------------------------------------------------------------------- */
+/*                                  Tab order                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * What counts as a keyboard stop. Base UI's ScrollArea viewport makes ITSELF
+ * tabbable when content overflows (`hiddenState.x && hiddenState.y ? -1 : 0`),
+ * an unnamed stop per level that `ui/scroll-area.tsx` will not let us suppress.
+ */
+const CASCADER_TAB_STOP_SELECTOR =
+  'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])'
+
+/** The stop to step over: nothing here focuses the scrollport on purpose. */
+const CASCADER_TAB_SKIP_SELECTOR = '[data-slot="scroll-area-viewport"]'
+
+/** Out of the tab order whatever they contain; layout is never consulted. */
+const CASCADER_TAB_HIDDEN_SELECTOR = "[hidden],[inert],[aria-hidden='true']"
+
+/** The panel's real keyboard stops, in DOM order. */
+function getCascaderTabStops(panel: HTMLElement): HTMLElement[] {
+  const stops = Array.from(
+    panel.querySelectorAll<HTMLElement>(CASCADER_TAB_STOP_SELECTOR)
+  )
+  return stops.filter(
+    (stop) =>
+      // Option and trail rows are real `<button>`s with `tabindex="-1"`.
+      stop.getAttribute("tabindex") !== "-1" &&
+      !stop.matches(CASCADER_TAB_SKIP_SELECTOR) &&
+      !stop.closest(CASCADER_TAB_HIDDEN_SELECTOR)
+  )
+}
+
+/** The footer's own stops; an `aria-disabled` command still counts as one. */
+export function getCascaderFooterStops(scope: HTMLElement): HTMLElement[] {
+  const footer = scope.matches('[data-slot="cascader-footer"]')
+    ? scope
+    : scope.querySelector<HTMLElement>('[data-slot="cascader-footer"]')
+  if (!footer) return []
+  return getCascaderTabStops(footer)
+}
+
+/**
+ * Hands focus to the panel's search field, or the popup without one. A Retry
+ * button is replaced by the loading state as the retry starts, and a focused
+ * node that unmounts drops focus to the body.
+ */
+export function focusCascaderHome(from: HTMLElement): void {
+  const panel = from.closest<HTMLElement>('[data-slot="cascader-panel"]')
+  const home =
+    panel?.querySelector<HTMLElement>('[data-slot="cascader-input"]') ??
+    from.closest<HTMLElement>('[data-slot="cascader-content"]') ??
+    panel
+  // An inline panel with no search field is the last home left: make it
+  // focusable for this, never a tab stop.
+  if (home && home === panel && !home.hasAttribute("tabindex")) {
+    home.setAttribute("tabindex", "-1")
+  }
+  home?.focus()
+}
+
+/** Where Tab lands, or `null` to let the browser out: focus is never trapped. */
+export function getCascaderTabTarget(
+  panel: HTMLElement,
+  from: Element | null,
+  backwards: boolean
+): HTMLElement | null {
+  const stops = getCascaderTabStops(panel)
+  if (stops.length === 0 || !from) return null
+
+  const index = stops.indexOf(from as HTMLElement)
+  if (index !== -1) return stops[index + (backwards ? -1 : 1)] ?? null
+
+  if (backwards) {
+    for (let i = stops.length - 1; i >= 0; i -= 1) {
+      const position = from.compareDocumentPosition(stops[i])
+      if (position & Node.DOCUMENT_POSITION_PRECEDING) return stops[i]
+    }
+    return null
+  }
+
+  for (const stop of stops) {
+    const position = from.compareDocumentPosition(stop)
+    if (position & Node.DOCUMENT_POSITION_FOLLOWING) return stop
+  }
+  return null
+}
+
+/**
+ * The writing direction at `element`. `DirectionProvider` may only vote yes:
+ * unmounted it answers `"ltr"`, which would override a real `<html dir="rtl">`.
+ */
+export function isCascaderRtl(element: Element, provided: string): boolean {
+  if (provided === "rtl") return true
+  const explicit = element.closest("[dir]")?.getAttribute("dir")?.toLowerCase()
+  if (explicit === "rtl") return true
+  if (explicit === "ltr") return false
+  return (
+    element.ownerDocument?.defaultView?.getComputedStyle(element).direction ===
+    "rtl"
+  )
+}
+
+/**
+ * The paging row as a REAL node, not a DOM-only row after the list: every index
+ * Base UI hands out indexes the RENDERED array, so a DOM-only row shifts them.
+ */
+export function createCascaderMoreNode<T = unknown>(
+  parentKey: string,
+  loadedCount = 0
+): CascaderNode<T> {
+  return {
+    value: `${CASCADER_MORE_PREFIX}${parentKey}`,
+    // Empty on purpose: a typeahead letter must never reach the paging row.
+    label: "",
+    // Feeds the row's "Loading more..." wording, with no second prop to thread.
+    count: loadedCount,
+  }
+}
+
+export function isCascaderMoreNode<T>(node: CascaderNode<T>): boolean {
+  return node.value.startsWith(CASCADER_MORE_PREFIX)
+}
+
+/** The level key a paging pseudo-node belongs to, or `null` for a real node. */
+export function getCascaderMoreParent<T>(node: CascaderNode<T>): string | null {
+  if (!isCascaderMoreNode(node)) return null
+  return node.value.slice(CASCADER_MORE_PREFIX.length)
+}
+
+/** Either input shape into one index. Cycle-guarded depths; first wins. */
+export function buildCascaderIndex<T = unknown>(
+  items: readonly CascaderNode<T>[] | undefined,
+  getParent?: (node: CascaderNode<T>) => string | null | undefined
+): CascaderIndex<T> {
+  const byValue = new Map<string, CascaderNode<T>>()
+  const childrenOf = new Map<string, CascaderNode<T>[]>()
+  const parentOf = new Map<string, string | null>()
+  const depthOf = new Map<string, number>()
+  const all: CascaderNode<T>[] = []
+
+  const push = (parentKey: string, node: CascaderNode<T>) => {
+    const bucket = childrenOf.get(parentKey)
+    if (bucket) {
+      bucket.push(node)
+    } else {
+      childrenOf.set(parentKey, [node])
+    }
+  }
+
+  if (getParent) {
+    for (const node of items ?? []) {
+      // A nullish entry is a data bug: skip it like a duplicate, say so in dev.
+      if (node == null) {
+        if (process.env.NODE_ENV !== "production") {
+          warnCascaderOnce(
+            "nullish-entry",
+            "Ignored a null or undefined entry in `items` or `children`. Check the arrays you pass in."
+          )
+        }
+        continue
+      }
+      if (byValue.has(node.value)) continue
+      byValue.set(node.value, node)
+      all.push(node)
+    }
+
+    for (const node of all) {
+      const rawParent = getParent(node)
+      // An unknown parent makes the node a root rather than dropping the row.
+      const parent =
+        rawParent != null && byValue.has(rawParent) ? rawParent : null
+      parentOf.set(node.value, parent)
+      push(parent ?? CASCADER_ROOT_KEY, node)
+    }
+
+    for (const node of all) {
+      let depth = 0
+      let cursor = parentOf.get(node.value) ?? null
+      const seen = new Set<string>([node.value])
+      while (cursor != null && !seen.has(cursor)) {
+        seen.add(cursor)
+        depth += 1
+        cursor = parentOf.get(cursor) ?? null
+      }
+      depthOf.set(node.value, depth)
+    }
+  } else {
+    const walk = (
+      nodes: readonly CascaderNode<T>[] | undefined,
+      parent: string | null,
+      depth: number
+    ) => {
+      for (const node of nodes ?? []) {
+        // Same degradation as the flat path above.
+        if (node == null) {
+          if (process.env.NODE_ENV !== "production") {
+            warnCascaderOnce(
+              "nullish-entry",
+              "Ignored a null or undefined entry in `items` or `children`. Check the arrays you pass in."
+            )
+          }
+          continue
+        }
+        if (byValue.has(node.value)) continue
+        byValue.set(node.value, node)
+        parentOf.set(node.value, parent)
+        depthOf.set(node.value, depth)
+        all.push(node)
+        push(parent ?? CASCADER_ROOT_KEY, node)
+        if (node.children?.length) walk(node.children, node.value, depth + 1)
+      }
+    }
+    walk(items, null, 0)
+  }
+
+  return {
+    byValue,
+    childrenOf,
+    parentOf,
+    depthOf,
+    roots: childrenOf.get(CASCADER_ROOT_KEY) ?? [],
+    all,
+  }
+}
+
+/** One branch-flagged copy per node, so a re-merge keeps row identity. */
+const BRANCH_COPIES = new WeakMap<object, object>()
+
+function asCascaderBranch<T>(node: CascaderNode<T>): CascaderNode<T> {
+  if (node.hasChildren) return node
+  let copy = BRANCH_COPIES.get(node) as CascaderNode<T> | undefined
+  if (!copy) {
+    copy = { ...node, hasChildren: true }
+    BRANCH_COPIES.set(node, copy)
+  }
+  return copy
+}
+
+/**
+ * Folds loaded pages into an index built from `items`, so a re-render with a
+ * new `items` array keeps what the user drilled into. Static `items` wins;
+ * `detached` is `byValue` ONLY, or deep search doubles it and `childrenOf` lies.
+ *
+ * A resolved chain node in `links` that no page placed still gets its parent,
+ * so the trigger keeps its path. While its parent's level is unloaded it is
+ * searchable but no row; while that level has pages left (`paging`) it is
+ * LISTED, last, and in `pinned`; once the level loaded completely without it
+ * (moved, deleted) it is `hidden`: no row, hit or cascade child. A node some
+ * link names as a parent reads as a branch, whatever chain wrote it last.
+ */
+export function mergeCascaderIndex<T = unknown>(
+  base: CascaderIndex<T>,
+  pages: ReadonlyMap<string, readonly CascaderNode<T>[]>,
+  detached?: ReadonlyMap<string, CascaderNode<T>>,
+  links?: ReadonlyMap<string, string>,
+  paging?: ReadonlySet<string>
+): CascaderIndex<T> {
+  // Identity stability: every downstream `useMemo` is keyed on this index.
+  if (pages.size === 0 && !detached?.size) return base
+
+  const byValue = new Map(base.byValue)
+  const childrenOf = new Map(base.childrenOf)
+  const parentOf = new Map(base.parentOf)
+  const depthOf = new Map(base.depthOf)
+
+  // Copy-on-write per bucket: only levels that got a page pay for a new array.
+  const copied = new Set<string>()
+  const append = (parentKey: string, node: CascaderNode<T>) => {
+    let bucket = childrenOf.get(parentKey)
+    if (!copied.has(parentKey)) {
+      bucket = bucket ? bucket.slice() : []
+      childrenOf.set(parentKey, bucket)
+      copied.add(parentKey)
+    }
+    bucket!.push(node)
+  }
+
+  const insert = (parentKey: string, nodes: readonly CascaderNode<T>[]) => {
+    for (const node of nodes) {
+      if (byValue.has(node.value)) continue
+      byValue.set(node.value, node)
+      parentOf.set(
+        node.value,
+        parentKey === CASCADER_ROOT_KEY ? null : parentKey
+      )
+      append(parentKey, node)
+      if (node.children?.length) insert(node.value, node.children)
+    }
+  }
+
+  for (const [parentKey, nodes] of pages) insert(parentKey, nodes)
+
+  const pinned = new Set<string>()
+  const hidden = new Set<string>()
+  const linkParents = new Set(links?.values())
+  for (const [value, parentKey] of links ?? []) {
+    const linked = detached?.get(value)
+    if (!linked || byValue.has(value)) continue
+    const node = linkParents.has(value) ? asCascaderBranch(linked) : linked
+    byValue.set(value, node)
+    parentOf.set(value, parentKey === CASCADER_ROOT_KEY ? null : parentKey)
+    if (paging?.has(parentKey)) {
+      append(parentKey, node)
+      pinned.add(value)
+    } else if (pages.has(parentKey) || base.childrenOf.has(parentKey)) {
+      hidden.add(value)
+    }
+  }
+
+  for (const value of byValue.keys()) {
+    if (depthOf.has(value)) continue
+    let depth = 0
+    let cursor = parentOf.get(value) ?? null
+    const seen = new Set<string>([value])
+    while (cursor != null && !seen.has(cursor)) {
+      seen.add(cursor)
+      depth += 1
+      cursor = parentOf.get(cursor) ?? null
+    }
+    depthOf.set(value, depth)
+  }
+
+  const roots = childrenOf.get(CASCADER_ROOT_KEY) ?? []
+
+  // Depth first over the MERGED tree, so `all` keeps document order.
+  const all: CascaderNode<T>[] = []
+  const visited = new Set<string>()
+  const walk = (nodes: readonly CascaderNode<T>[]) => {
+    for (const node of nodes) {
+      if (visited.has(node.value)) continue
+      visited.add(node.value)
+      all.push(node)
+      const children = childrenOf.get(node.value)
+      if (children?.length) walk(children)
+    }
+  }
+  walk(roots)
+
+  // A page whose parent never arrived, or a linked node whose level has not
+  // loaded, stays searchable rather than vanishing.
+  for (const [value, node] of byValue) {
+    if (visited.has(value) || hidden.has(value)) continue
+    visited.add(value)
+    all.push(node)
+  }
+
+  if (detached) {
+    for (const [value, node] of detached) {
+      if (byValue.has(value)) continue
+      byValue.set(value, node)
+    }
+  }
+
+  return { byValue, childrenOf, parentOf, depthOf, roots, all, pinned, hidden }
+}
+
+/** Per index, so a query does not rebuild it. */
+const LISTED_VALUES = new WeakMap<object, ReadonlySet<string>>()
+
+/**
+ * Values reachable from the roots through `childrenOf`: the nodes a level can
+ * show. A tree query keeps only these, or a resolved node no level lists left
+ * its ancestors expanded over nothing.
+ */
+export function getCascaderListedValues<T>(
+  index: CascaderIndex<T>
+): ReadonlySet<string> {
+  let listed = LISTED_VALUES.get(index)
+  if (listed) return listed
+  const seen = new Set<string>()
+  const walk = (nodes: readonly CascaderNode<T>[]) => {
+    for (const node of nodes) {
+      if (seen.has(node.value)) continue
+      seen.add(node.value)
+      const children = index.childrenOf.get(node.value)
+      if (children?.length) walk(children)
+    }
+  }
+  walk(index.roots)
+  listed = seen
+  LISTED_VALUES.set(index, listed)
+  return listed
+}
+
+/**
+ * A level's rows plus its paging row, placed BEFORE the `pinned` rows, which
+ * sit last: the first row a page appends then takes the paging row's index,
+ * so the highlight Base UI keeps by index lands on it.
+ */
+export function withCascaderMoreRow<T>(
+  rows: readonly CascaderNode<T>[],
+  more: CascaderNode<T>,
+  pinned?: ReadonlySet<string>
+): CascaderNode<T>[] {
+  const at = pinned?.size ? rows.findIndex((row) => pinned.has(row.value)) : -1
+  if (at === -1) return [...rows, more]
+  return [...rows.slice(0, at), more, ...rows.slice(at)]
+}
+
+/** Children of `parent`, or the root level when `parent` is nullish. */
+export function getCascaderChildren<T>(
+  index: CascaderIndex<T>,
+  parent?: string | null
+): CascaderNode<T>[] {
+  return index.childrenOf.get(parent ?? CASCADER_ROOT_KEY) ?? []
+}
+
+/** A branch has known children, or `hasChildren` for an unfetched level. */
+export function isCascaderBranch<T>(
+  index: CascaderIndex<T>,
+  node: CascaderNode<T>
+): boolean {
+  if (node.hasChildren) return true
+  return (index.childrenOf.get(node.value)?.length ?? 0) > 0
+}
+
+/** Trailing count for the default row. Explicit `count` wins over the tree. */
+export function getCascaderCount<T>(
+  index: CascaderIndex<T>,
+  node: CascaderNode<T>
+): number {
+  if (typeof node.count === "number") return node.count
+  return index.childrenOf.get(node.value)?.length ?? 0
+}
+
+/**
+ * Whether a node is disabled: its own flag, or any ancestor's, since a disabled
+ * branch keeps its whole subtree shut. The index's copy counts as its own, so a
+ * server hit that omits the flag `items` sets is still caught. Ancestry is
+ * `parentOf`: a detached hit the index has never placed answers for itself.
+ */
+export function isCascaderDisabled<T>(
+  index: CascaderIndex<T>,
+  node: CascaderNode<T>
+): boolean {
+  if (node.disabled || index.byValue.get(node.value)?.disabled) return true
+  const seen = new Set<string>([node.value])
+  let cursor = index.parentOf.get(node.value) ?? null
+  while (cursor != null && !seen.has(cursor)) {
+    seen.add(cursor)
+    if (index.byValue.get(cursor)?.disabled) return true
+    cursor = index.parentOf.get(cursor) ?? null
+  }
+  return false
+}
+
+/** Whether a node may be committed as a selection. */
+export function isCascaderSelectable<T>(
+  index: CascaderIndex<T>,
+  node: CascaderNode<T>,
+  selectable: CascaderSelectable<T>
+): boolean {
+  // Before the branches a consumer controls: `selectable="any"` says yes to
+  // every node, and committing the paging row would select a level's name.
+  if (isCascaderMoreNode(node)) return false
+  // Rows render this answer and their presses, keys, `commit`, `navigate` and
+  // `navigateAt` check it, so a search lists a disabled subtree none of them
+  // opens. The raw setters (`pushLevel`, `setPath`, `toggleExpanded`,
+  // `setSelection`) do not ask.
+  if (isCascaderDisabled(index, node)) return false
+  if (typeof selectable === "function") return selectable(node)
+  if (selectable === "any") return true
+  return !isCascaderBranch(index, node)
+}
+
+/** Ancestor chain for `value`, root first. Empty while async data loads. */
+export function getCascaderPath<T>(
+  index: CascaderIndex<T>,
+  value: string | null | undefined
+): CascaderNode<T>[] {
+  if (value == null) return []
+  const chain: CascaderNode<T>[] = []
+  const seen = new Set<string>()
+  let cursor: string | null | undefined = value
+  while (cursor != null && !seen.has(cursor)) {
+    seen.add(cursor)
+    const node = index.byValue.get(cursor)
+    if (!node) break
+    chain.push(node)
+    cursor = index.parentOf.get(cursor) ?? null
+  }
+  return chain.reverse()
+}
+
+/**
+ * `toLocaleLowerCase`, not `toLowerCase`: the invariant mapping turns Turkish
+ * "I" into "i" not "ı", so "ışık" would never match "IŞIK". Both sides fold here.
+ */
+export function foldCascaderText(text: string): string {
+  return text.toLocaleLowerCase()
+}
+
+/** Folds once so callers can hoist the cost out of a per-node loop. */
+export function normalizeCascaderQuery(query: string): string {
+  return foldCascaderText(query.trim())
+}
+
+/** Case-insensitive substring over label and keywords; pre-fold the query. */
+export function matchesCascaderQuery<T>(
+  node: CascaderNode<T>,
+  normalized: string
+): boolean {
+  if (!normalized) return true
+  // Coerced, not trusted: a label-less node is malformed data, not a crash.
+  if (foldCascaderText(node.label ?? "").includes(normalized)) return true
+  if (node.keywords) {
+    for (const keyword of node.keywords) {
+      if (foldCascaderText(keyword).includes(normalized)) return true
+    }
+  }
+  return false
+}
+
+/** Filters one level in place-order. Returns the input when the query is empty. */
+export function filterCascaderLevel<T>(
+  nodes: readonly CascaderNode<T>[],
+  query: string,
+  matches: (
+    node: CascaderNode<T>,
+    normalized: string
+  ) => boolean = matchesCascaderQuery
+): CascaderNode<T>[] {
+  const normalized = normalizeCascaderQuery(query)
+  if (!normalized) return nodes as CascaderNode<T>[]
+  return nodes.filter((node) => matches(node, normalized))
+}
+
+/** Searches every node, optionally under `within`, in one pass over `all`. */
+export function searchCascaderDeep<T>(
+  index: CascaderIndex<T>,
+  query: string,
+  options: {
+    within?: string | null
+    limit?: number
+    matches?: (node: CascaderNode<T>, normalized: string) => boolean
+  } = {}
+): CascaderNode<T>[] {
+  const normalized = normalizeCascaderQuery(query)
+  if (!normalized) return []
+
+  const { within, limit = 200, matches = matchesCascaderQuery } = options
+  const results: CascaderNode<T>[] = []
+
+  // One memoised ancestry map per query. The provisional `false` written on the
+  // way up doubles as the cycle guard; the trail is promoted once `within` hits.
+  const ancestry = within == null ? null : new Map<string, boolean>()
+  const isWithin = (node: CascaderNode<T>) => {
+    if (within == null || !ancestry) return true
+    const trail: string[] = []
+    let answer = false
+    let cursor: string | null | undefined = index.parentOf.get(node.value)
+    while (cursor != null) {
+      if (cursor === within) {
+        answer = true
+        break
+      }
+      const cached = ancestry.get(cursor)
+      if (cached !== undefined) {
+        answer = cached
+        break
+      }
+      ancestry.set(cursor, false)
+      trail.push(cursor)
+      cursor = index.parentOf.get(cursor) ?? null
+    }
+    if (answer) for (const value of trail) ancestry.set(value, true)
+    return answer
+  }
+
+  for (const node of index.all) {
+    if (results.length >= limit) break
+    if (!matches(node, normalized)) continue
+    if (!isWithin(node)) continue
+    results.push(node)
+  }
+
+  return results
+}
+
+/**
+ * Flattens the tree into tree mode's visible rows. A `sentinels` paging row
+ * COUNTS as a sibling in `aria-setsize`: it holds an index of its own.
+ */
+export function flattenCascaderTree<T>(
+  index: CascaderIndex<T>,
+  expanded: ReadonlySet<string>,
+  sentinels?: ReadonlySet<string>
+): CascaderFlatNode<T>[] {
+  const rows: CascaderFlatNode<T>[] = []
+
+  const walk = (
+    nodes: readonly CascaderNode<T>[],
+    parentKey: string,
+    depth: number
+  ) => {
+    const items = sentinels?.has(parentKey)
+      ? withCascaderMoreRow(
+          nodes,
+          createCascaderMoreNode<T>(parentKey, nodes.length),
+          index.pinned
+        )
+      : nodes
+    const setSize = items.length
+    for (let i = 0; i < items.length; i += 1) {
+      const node = items[i]
+      if (isCascaderMoreNode(node)) {
+        rows.push({
+          node,
+          depth,
+          branch: false,
+          expanded: false,
+          setSize,
+          posInSet: i + 1,
+        })
+        continue
+      }
+      const branch = isCascaderBranch(index, node)
+      const isExpanded = branch && expanded.has(node.value)
+      rows.push({
+        node,
+        depth,
+        branch,
+        expanded: isExpanded,
+        setSize,
+        posInSet: i + 1,
+      })
+      if (isExpanded) {
+        walk(index.childrenOf.get(node.value) ?? [], node.value, depth + 1)
+      }
+    }
+  }
+
+  walk(index.roots, CASCADER_ROOT_KEY, 0)
+  return rows
+}
+
+/** Shortens a path; the ellipsis segment still carries the hidden nodes. */
+export function collapseCascaderPath<T>(
+  path: readonly CascaderNode<T>[],
+  options: { maxSegments?: number; collapse?: CascaderCollapse } = {}
+): CascaderPathSegment<T>[] {
+  const { maxSegments = 3, collapse = "middle" } = options
+
+  const asNodes = (
+    nodes: readonly CascaderNode<T>[]
+  ): CascaderPathSegment<T>[] =>
+    nodes.map((node) => ({ type: "node" as const, node }))
+
+  if (collapse === "none" || maxSegments <= 0 || path.length <= maxSegments) {
+    return asNodes(path)
+  }
+
+  if (collapse === "start") {
+    const tail = path.slice(path.length - maxSegments)
+    return [
+      { type: "ellipsis", hidden: path.slice(0, path.length - maxSegments) },
+      ...asNodes(tail),
+    ]
+  }
+
+  // "middle": keep the root for orientation and as much of the tail as fits.
+  const head = path.slice(0, 1)
+  const tailCount = maxSegments - 1
+  const tail = path.slice(path.length - tailCount)
+  const hidden = path.slice(1, path.length - tailCount)
+
+  if (hidden.length === 0) return asNodes(path)
+
+  return [...asNodes(head), { type: "ellipsis", hidden }, ...asNodes(tail)]
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Cascade selection                             */
+/* -------------------------------------------------------------------------- */
+
+/** Per index, so a press does not rebuild it. */
+const SELECTION_CHILDREN = new WeakMap<object, Map<string, unknown[]>>()
+
+/**
+ * Children by parent, built from `parentOf`. Unlike `childrenOf` it also holds
+ * a resolved chain node whose level has not loaded, which the selection walks
+ * must see: unchecking an ancestor has to take it along. A `hidden` one is left
+ * out, since its level loaded without it.
+ */
+function getSelectionChildren<T>(
+  index: CascaderIndex<T>
+): Map<string, CascaderNode<T>[]> {
+  let map = SELECTION_CHILDREN.get(index) as
+    | Map<string, CascaderNode<T>[]>
+    | undefined
+  if (map) return map
+  map = new Map()
+  for (const [value, parent] of index.parentOf) {
+    const node = index.byValue.get(value)
+    if (!node || index.hidden?.has(value)) continue
+    const key = parent ?? CASCADER_ROOT_KEY
+    const bucket = map.get(key)
+    if (bucket) bucket.push(node)
+    else map.set(key, [node])
+  }
+  SELECTION_CHILDREN.set(index, map)
+  return map
+}
+
+/**
+ * Every KNOWN node under `value`, root first: loaded, or on a resolved chain.
+ * Reaching an unfetched descendant would mean a network request per level of
+ * the subtree on every selection.
+ */
+export function collectCascaderSubtree<T>(
+  index: CascaderIndex<T>,
+  value: string
+): CascaderNode<T>[] {
+  const root = index.byValue.get(value)
+  if (!root) return []
+
+  const childrenOf = getSelectionChildren(index)
+  const out: CascaderNode<T>[] = []
+  const seen = new Set<string>()
+  const walk = (node: CascaderNode<T>) => {
+    if (seen.has(node.value)) return
+    seen.add(node.value)
+    out.push(node)
+    const children = childrenOf.get(node.value)
+    if (children) for (const child of children) walk(child)
+  }
+  walk(root)
+  return out
+}
+
+/**
+ * Toggles `value` with its known subtree (loaded, or on a resolved chain), then
+ * reconciles ancestors. One flat array, no hidden "checked" state: a branch is
+ * in the selection exactly when every selectable known child of it is, which
+ * keeps a row's checked state an O(1) lookup. Nodes `isSelectable` rejects are skipped down AND ignored up,
+ * the pressed node excepted.
+ */
+export function applyCascadeSelection<T>(
+  index: CascaderIndex<T>,
+  selected: readonly string[],
+  value: string,
+  select: boolean,
+  isSelectable: (node: CascaderNode<T>) => boolean = () => true
+): string[] {
+  const next = new Set(selected)
+  const subtree = collectCascaderSubtree(index, value)
+
+  // An unknown value still toggles itself, so an early async selection lands.
+  if (subtree.length === 0) {
+    if (select) next.add(value)
+    else next.delete(value)
+  }
+
+  for (const node of subtree) {
+    // The pressed node is exempt: it was committed, so it is selectable.
+    if (node.value !== value && !isSelectable(node)) continue
+    if (select) next.add(node.value)
+    else next.delete(node.value)
+  }
+
+  // Bottom up: a parent can only answer once its children have.
+  const seen = new Set<string>([value])
+  let cursor = index.parentOf.get(value) ?? null
+  while (cursor != null && !seen.has(cursor)) {
+    seen.add(cursor)
+    const parent = index.byValue.get(cursor)
+    const children = getSelectionChildren(index).get(cursor) ?? []
+    const selectable = children.filter((child) => isSelectable(child))
+    const full =
+      selectable.length > 0 &&
+      selectable.every((child) => next.has(child.value)) &&
+      // Never promote a node the consumer said may not be committed. Under
+      // `selectable="leaf"` no branch qualifies, hence the `cascade` warning.
+      !!parent &&
+      isSelectable(parent)
+    if (full) next.add(cursor)
+    else next.delete(cursor)
+    cursor = index.parentOf.get(cursor) ?? null
+  }
+
+  return Array.from(next)
+}
+
+/**
+ * How many selected nodes each value has BELOW it, itself excluded. Walks UP
+ * from each selection: a per-row subtree scan would be quadratic and re-paid.
+ */
+export function getCascaderSelectedDescendants<T>(
+  index: CascaderIndex<T>,
+  selected: readonly string[]
+): Map<string, number> {
+  const counts = new Map<string, number>()
+
+  for (const value of selected) {
+    const seen = new Set<string>([value])
+    let cursor = index.parentOf.get(value) ?? null
+    while (cursor != null && !seen.has(cursor)) {
+      seen.add(cursor)
+      counts.set(cursor, (counts.get(cursor) ?? 0) + 1)
+      cursor = index.parentOf.get(cursor) ?? null
+    }
+  }
+
+  return counts
+}
+
+/** The PARTIALLY selected values, read off counts the caller already holds. */
+export function getCascaderIndeterminateFrom(
+  counts: ReadonlyMap<string, number>,
+  selected: readonly string[]
+): Set<string> {
+  const selectedSet = new Set(selected)
+  const partial = new Set<string>()
+
+  for (const [value, count] of counts) {
+    if (count > 0 && !selectedSet.has(value)) partial.add(value)
+  }
+
+  return partial
+}
+
+/** The one-call form; the root uses the two halves above and its own counts. */
+export function getCascaderIndeterminate<T>(
+  index: CascaderIndex<T>,
+  selected: readonly string[]
+): Set<string> {
+  return getCascaderIndeterminateFrom(
+    getCascaderSelectedDescendants(index, selected),
+    selected
+  )
+}
+
+/** How `getCascaderCheckedValues` condenses a full-closure selection. */
+export type CascaderCheckedStrategy = "all" | "parent" | "child"
+
+/**
+ * The cascade selection under a reporting strategy. DERIVED OUTPUT ONLY: the
+ * STORED value stays the full closure, which keeps a checked state an O(1)
+ * lookup. `"all"` is the closure; `"parent"` drops a value whose parent is
+ * selected; `"child"` drops one with a selected child.
+ */
+export function getCascaderCheckedValues<T>(
+  index: CascaderIndex<T>,
+  selected: readonly string[],
+  strategy: CascaderCheckedStrategy
+): readonly string[] {
+  if (strategy === "all") return selected
+
+  const set = new Set(selected)
+  if (strategy === "parent") {
+    return selected.filter((value) => {
+      const parent = index.parentOf.get(value)
+      return parent == null || !set.has(parent)
+    })
+  }
+
+  // Parents of a selection, from `parentOf`: it holds the resolved chain
+  // nodes no loaded level lists, which `childrenOf` misses.
+  const withSelectedChild = new Set<string>()
+  for (const value of selected) {
+    if (index.hidden?.has(value)) continue
+    const parent = index.parentOf.get(value)
+    if (parent != null) withSelectedChild.add(parent)
+  }
+  return selected.filter((value) => !withSelectedChild.has(value))
+}
+
+/** Values in `nodes` whose label collides, so the chip must show its path. */
+export function findAmbiguousCascaderLabels<T>(
+  nodes: readonly CascaderNode<T>[]
+): Set<string> {
+  const firstByLabel = new Map<string, string>()
+  const ambiguous = new Set<string>()
+
+  for (const node of nodes) {
+    const first = firstByLabel.get(node.label)
+    if (first === undefined) {
+      firstByLabel.set(node.label, node.value)
+      continue
+    }
+    ambiguous.add(node.value)
+    ambiguous.add(first)
+  }
+
+  return ambiguous
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Development only                              */
+/* -------------------------------------------------------------------------- */
+
+/** Warnings already emitted. Module scoped, or they repeat once per render. */
+const CASCADER_WARNED = new Set<string>()
+
+/** Warns once per `key`, never in production, never by throwing. */
+export function warnCascaderOnce(key: string, message: string): void {
+  if (process.env.NODE_ENV === "production") return
+  if (CASCADER_WARNED.has(key)) return
+  CASCADER_WARNED.add(key)
+  console.warn(`[Cascader] ${message}`)
+}
+
+/** Empties the ledger. Tests only; a warning is meant to be seen once. */
+export function resetCascaderWarnings(): void {
+  CASCADER_WARNED.clear()
+}
+
+/** What a dev-time scan of the consumer's `items` found wrong with it. */
+export interface CascaderDataIssues {
+  /** Values appearing more than once. First wins, so a duplicate drops a row. */
+  duplicates: string[]
+  /** Values on a `getParent` cycle. Depth is clamped, so the tree reads wrong. */
+  cycles: string[]
+}
+
+/** Dev-time scan, kept out of `buildCascaderIndex` so the build stays hot. */
+export function findCascaderDataIssues<T>(
+  items: readonly CascaderNode<T>[] | undefined,
+  getParent?: (node: CascaderNode<T>) => string | null | undefined
+): CascaderDataIssues {
+  const seen = new Set<string>()
+  const duplicates = new Set<string>()
+  const flat: CascaderNode<T>[] = []
+
+  const visit = (nodes: readonly CascaderNode<T>[] | undefined) => {
+    for (const node of nodes ?? []) {
+      // The build skips a nullish entry, and this runs BEFORE its warning.
+      if (node == null) continue
+      if (seen.has(node.value)) duplicates.add(node.value)
+      else seen.add(node.value)
+      flat.push(node)
+      // Flat mode walks them too: BOTH `children` and `getParent` is a bug.
+      if (node.children?.length) visit(node.children)
+    }
+  }
+  visit(items)
+
+  const cycles: string[] = []
+  if (getParent) {
+    const parentOf = new Map<string, string | null>()
+    for (const node of flat) {
+      if (parentOf.has(node.value)) continue
+      const raw = getParent(node)
+      parentOf.set(node.value, raw != null && seen.has(raw) ? raw : null)
+    }
+    for (const node of flat) {
+      const walked = new Set<string>([node.value])
+      let cursor = parentOf.get(node.value) ?? null
+      while (cursor != null) {
+        if (walked.has(cursor)) {
+          cycles.push(node.value)
+          break
+        }
+        walked.add(cursor)
+        cursor = parentOf.get(cursor) ?? null
+      }
+    }
+  }
+
+  return { duplicates: Array.from(duplicates), cycles }
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader-nav.tsx b/apps/web/src/components/reui/cascader/cascader-nav.tsx
new file mode 100644
index 0000000..df590f2
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-nav.tsx
@@ -0,0 +1,649 @@
+import * as React from "react"
+import {
+  useCascaderActions,
+  useCascaderState,
+} from "@/components/reui/cascader/cascader-context"
+import { resolveCascaderSearchLabel } from "@/components/reui/cascader/cascader-i18n"
+import {
+  collapseCascaderPath,
+  getCascaderFooterStops,
+  getCascaderPath,
+  isCascaderRtl,
+} from "@/components/reui/cascader/cascader-lib"
+import type {
+  CascaderCollapse,
+  CascaderNode,
+  CascaderValueDisplay,
+} from "@/components/reui/cascader/cascader-types"
+import { Combobox as ComboboxPrimitive } from "@base-ui/react"
+import { useDirection } from "@base-ui/react/direction-provider"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { ChevronRightIcon, ChevronLeftIcon } from "lucide-react"
+
+/* -------------------------------------------------------------------------- */
+/*                                  Separator                                 */
+/* -------------------------------------------------------------------------- */
+
+function PathChevron() {
+  return (
+    <ChevronRightIcon className="size-3 shrink-0 opacity-50 rtl:-scale-x-100" />
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                     Nav                                    */
+/* -------------------------------------------------------------------------- */
+
+export type CascaderNavProps = useRender.ComponentProps<"div">
+
+/**
+ * Header: back control, search input, and the separator under them. The
+ * breadcrumb belongs with the list below: it describes the rows, not the field.
+ */
+function CascaderNav({ className, ...props }: CascaderNavProps) {
+  const defaultProps = {
+    "data-slot": "cascader-nav",
+    className: cn(
+      // `py-1`, not `py-1.5`: the row inside sets its own per-style height, so
+      // even padding read too tall. 6px beside the field, 4px above and below.
+      "border-border/60 flex shrink-0 flex-col gap-1 border-b px-1.5 py-1",
+      className
+    ),
+  }
+
+  return useRender({
+    defaultTagName: "div",
+    render: props.render,
+    props: mergeProps<"div">(defaultProps, props),
+  })
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Back                                    */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderBackProps extends Omit<
+  useRender.ComponentProps<"button">,
+  "children"
+> {
+  children?: React.ReactNode
+}
+
+/** Pops one level. Renders nothing at the root, so no dead header space. */
+function CascaderBack({ className, children, ...props }: CascaderBackProps) {
+  const { popLevel, labels, mode } = useCascaderActions()
+  const { path } = useCascaderState()
+
+  // Checked after `useRender`, never before it: an early return would change
+  // the hook count between the root level and any deeper one.
+  const hidden = mode !== "drill" || path.length === 0
+
+  const defaultProps = {
+    "data-slot": "cascader-back",
+    type: "button" as const,
+    "aria-label": labels.back,
+    onClick: () => popLevel(),
+    className: cn(
+      "text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:ring-ring/50 flex shrink-0 items-center justify-center rounded-md outline-hidden transition-colors focus-visible:ring-2",
+      // A notch under the row height: an affordance, not a second field.
+      "size-6",
+      className
+    ),
+    children: children ?? (
+      <ChevronLeftIcon className="size-4 rtl:-scale-x-100" />
+    ),
+  }
+
+  const element = useRender({
+    defaultTagName: "button",
+    render: props.render,
+    props: mergeProps<"button">(defaultProps, props),
+  })
+
+  return hidden ? null : element
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                 Breadcrumb                                 */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderBreadcrumbProps extends Omit<
+  useRender.ComponentProps<"nav">,
+  "children"
+> {
+  /** Maximum visible node segments before the middle collapses. */
+  maxSegments?: number
+  collapse?: CascaderCollapse
+  /** Clicking a segment navigates back to that level. Defaults to true. */
+  interactive?: boolean
+}
+
+/**
+ * Compact trail of the current level AND its ancestors, collapsed by the same
+ * helper as `CascaderValue` so panel and trigger cannot disagree. The current
+ * level IS the last crumb: dropping it read as a rendering bug, a trail naming
+ * only the places you are not.
+ */
+function CascaderBreadcrumb({
+  className,
+  maxSegments = 3,
+  collapse = "middle",
+  interactive = true,
+  ...props
+}: CascaderBreadcrumbProps) {
+  const { goToDepth, mode, labels } = useCascaderActions()
+  const { path, index } = useCascaderState()
+
+  // The WHOLE path, current level included; unresolvable entries drop out.
+  const nodes = path
+    .map((value) => index.byValue.get(value))
+    .filter(Boolean) as CascaderNode[]
+  const segments = collapseCascaderPath(nodes, { maxSegments, collapse })
+  // `collapseCascaderPath` never collapses the last node away, so this is
+  // always the final segment - derived rather than assumed, so a `collapse`
+  // mode that ever changes that cannot mark an ancestor as the current page.
+  const currentValue = nodes.length ? nodes[nodes.length - 1].value : null
+
+  // See `CascaderBack`: the hide check must not short-circuit past `useRender`.
+  const hidden = mode !== "drill" || nodes.length === 0
+
+  const goTo = (node: CascaderNode) => {
+    const depth = path.indexOf(node.value)
+    if (depth < 0) return
+    // `goToDepth`, not a bare `setPath`: it reports `reason: "breadcrumb"`,
+    // clears the query and drops any pending navigation.
+    goToDepth(depth + 1)
+  }
+
+  const defaultProps = {
+    "data-slot": "cascader-breadcrumb",
+    "aria-label": labels.breadcrumbLabel,
+    className: cn(
+      "text-muted-foreground flex min-w-0 shrink-0 items-center gap-0.5 pt-1.5 pb-0.5 text-xs",
+      // Lines up with the ROWS, not the header: each style's list padding plus
+      // its row inset. vega/mira/rhea `p-1`+`pl-2`, nova `p-1`+`pl-1.5`, maia
+      // `p-1`+`pl-3`, lyra `pl-2`, luma/sera `p-1.5`+`pl-3`, per style-*.css.
+      "px-2.5",
+      className
+    ),
+    children: segments.map((segment, i) => (
+      <React.Fragment
+        key={segment.type === "node" ? segment.node.value : `gap-${i}`}
+      >
+        {i > 0 ? <PathChevron /> : null}
+        {segment.type === "ellipsis" ? (
+          <span
+            data-slot="cascader-breadcrumb-ellipsis"
+            title={segment.hidden
+              .map((n) => n.label)
+              .join(` ${labels.pathSeparator} `)}
+            className="shrink-0"
+          >
+            &hellip;
+          </span>
+        ) : interactive && segment.node.value !== currentValue ? (
+          <button
+            type="button"
+            data-slot="cascader-breadcrumb-item"
+            onClick={() => goTo(segment.node)}
+            className="hover:text-foreground focus-visible:ring-ring/50 max-w-32 truncate rounded-sm outline-hidden transition-colors focus-visible:ring-2"
+          >
+            {segment.node.label}
+          </button>
+        ) : (
+          <span
+            data-slot="cascader-breadcrumb-item"
+            /* The level on screen: a span because it goes nowhere, plus
+               `aria-current="page"` so it is not read as one of a flat list. */
+            {...(segment.node.value === currentValue
+              ? { "aria-current": "page" as const }
+              : null)}
+            className={cn(
+              "max-w-32 truncate",
+              segment.node.value === currentValue &&
+                "text-foreground font-medium"
+            )}
+          >
+            {segment.node.label}
+          </span>
+        )}
+      </React.Fragment>
+    )),
+  }
+
+  const element = useRender({
+    defaultTagName: "nav",
+    render: props.render,
+    props: mergeProps<"nav">(defaultProps, props),
+  })
+
+  return hidden ? null : element
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Input                                   */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderInputProps extends ComboboxPrimitive.Input.Props {
+  /** Renders the back control inline, before the field. Defaults to true. */
+  showBack?: boolean
+}
+
+/** Base UI hands its input handlers an event carrying the veto hook. */
+type CascaderInputKeyEvent = Parameters<
+  NonNullable<ComboboxPrimitive.Input.Props["onKeyDown"]>
+>[0]
+
+/**
+ * Search field. MUST render inside the positioner: only there does Base UI skip
+ * the refill from the committed selection that would fight every level swap.
+ */
+function CascaderInput({
+  className,
+  showBack = true,
+  placeholder,
+  onKeyDown,
+  "aria-describedby": ariaDescribedBy,
+  ...props
+}: CascaderInputProps) {
+  const {
+    labels,
+    popLevel,
+    mode,
+    getHighlighted,
+    isBranch,
+    isDisabled,
+    navigate,
+    index,
+    toggleExpanded,
+    inline,
+    invalid,
+    baseId,
+    searchScope,
+  } = useCascaderActions()
+  const direction = useDirection()
+  const { currentParent, query, path, expanded, renderedItems, treeRows } =
+    useCascaderState()
+
+  // Root wording under a global search: naming the level on screen would
+  // promise a narrower search than the one that runs.
+  const resolvedPlaceholder =
+    placeholder ??
+    resolveCascaderSearchLabel(
+      labels,
+      searchScope === "global" ? undefined : currentParent?.label
+    )
+
+  // Not `showBack`: `CascaderBack` renders nothing at the root or outside
+  // drill mode, where the field's own leading `px-1.5` is wanted. Beside the
+  // button it stacks with the row's `gap-1` into a 10px hole, hence `ps-0`.
+  const backVisible = showBack && mode === "drill" && path.length > 0
+
+  const hintId = `${baseId}-hint`
+  // Base UI names no list while inline; columns mode moves the real listbox to
+  // the deepest panel, which is the `path.length` one.
+  const listId = `${baseId}-column-${mode === "columns" ? path.length : 0}`
+
+  // The direction the HINT is worded for. `handleKeyDown` re-reads
+  // `isCascaderRtl` per keystroke; this is text on screen before any key, so
+  // the same check runs once against the mounted DOM (on the hint span, so no
+  // second ref into Base UI's input). SSR renders the "ltr" default and
+  // corrects on hydration. `direction` is the only dep: a `dir` attribute and
+  // the stylesheet are declarations, not state, so nothing to resubscribe to.
+  const hintRef = React.useRef<HTMLSpanElement>(null)
+  const [hintDir, setHintDir] = React.useState<"ltr" | "rtl">("ltr")
+  React.useLayoutEffect(() => {
+    const hint = hintRef.current
+    if (!hint) return
+    setHintDir(isCascaderRtl(hint, direction) ? "rtl" : "ltr")
+  }, [direction])
+
+  /**
+   * Moves the highlight to `targetIndex` in `treeRows`. Base UI has no
+   * imperative setter (`actionsRef` is `{ unmount }`), so the move is arrow
+   * presses, sound only because `useListNavigation` fires `onItemHighlighted`
+   * SYNCHRONOUSLY per keydown. A press that fails to close the gap ends it.
+   */
+  const moveHighlightTo = (field: HTMLInputElement, targetIndex: number) => {
+    const rowIndex = () => {
+      const highlighted = getHighlighted()
+      if (!highlighted) return -1
+      return treeRows.findIndex((row) => row.node.value === highlighted.value)
+    }
+
+    let current = rowIndex()
+    for (let step = 0; step < treeRows.length; step += 1) {
+      if (current === -1 || current === targetIndex) return
+      const key = current > targetIndex ? "ArrowUp" : "ArrowDown"
+      field.dispatchEvent(
+        new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true })
+      )
+      const next = rowIndex()
+      const progressed =
+        key === "ArrowUp"
+          ? next < current && next >= targetIndex
+          : next > current && next <= targetIndex
+      if (next === -1 || !progressed) return
+      current = next
+    }
+  }
+
+  /**
+   * The tree pattern's two level keys; Base UI leaves both alone (list
+   * navigation is vertical-only, the chip handler no-ops without
+   * `Combobox.Chips`). Passed in rather than hardcoded because RTL swaps them:
+   * APG defines them as "toward the children", not as a physical arrow.
+   */
+  const handleTreeKeyDown = (
+    event: CascaderInputKeyEvent,
+    field: HTMLInputElement,
+    caretAtStart: boolean,
+    caretAtEnd: boolean,
+    forwardKey: "ArrowLeft" | "ArrowRight",
+    backKey: "ArrowLeft" | "ArrowRight"
+  ) => {
+    const forward = event.key === forwardKey
+    if (!forward && event.key !== backKey) return
+    if (forward ? !caretAtEnd : !caretAtStart) return
+
+    const highlighted = getHighlighted()
+    if (!highlighted) return
+    const rowIndex = treeRows.findIndex(
+      (row) => row.node.value === highlighted.value
+    )
+    if (rowIndex < 0) return
+    const row = treeRows[rowIndex]
+
+    if (forward) {
+      if (!row.branch) return
+      event.preventDefault()
+      if (!row.expanded) {
+        // `navigate`, not `toggleExpanded`: it waits for an unloaded branch's
+        // children, so the keyboard path in matches the expander.
+        navigate(row.node)
+        return
+      }
+      // `flattenCascaderTree` emits children right after their parent, so the
+      // first child is the next row. The depth check covers an empty branch.
+      const child = treeRows[rowIndex + 1]
+      if (child && child.depth === row.depth + 1) {
+        moveHighlightTo(field, rowIndex + 1)
+      }
+      return
+    }
+
+    // A query holds every hit's ancestors open without adding them to
+    // `expanded`, so the toggle would ADD such a row: it would open a disabled
+    // one for good. That row moves to its parent instead, as a closed one does.
+    const heldByQuery = isDisabled(row.node) && !expanded.has(row.node.value)
+    if (row.branch && row.expanded && !heldByQuery) {
+      event.preventDefault()
+      toggleExpanded(row.node.value)
+      return
+    }
+
+    const parentValue = index.parentOf.get(row.node.value)
+    if (!parentValue) return
+    const parentIndex = treeRows.findIndex(
+      (entry) => entry.node.value === parentValue
+    )
+    if (parentIndex < 0) return
+    event.preventDefault()
+    moveHighlightTo(field, parentIndex)
+  }
+
+  const handleKeyDown = (event: CascaderInputKeyEvent) => {
+    onKeyDown?.(event)
+    if (event.defaultPrevented) return
+
+    const field = event.currentTarget
+    const caretAtStart = field.selectionStart === 0 && field.selectionEnd === 0
+    const caretAtEnd =
+      field.selectionStart === query.length &&
+      field.selectionEnd === query.length
+
+    // ArrowDown at the END of the list hands real focus to the pinned footer,
+    // the key a combobox is actually navigated with; Tab still works and still
+    // skips the scroll area. An EMPTY list hands off at once, and the footer
+    // owns the way back. Counted from state, so a windowed list still answers.
+    if (event.key === "ArrowDown" && !event.altKey) {
+      const rowCount = mode === "tree" ? treeRows.length : renderedItems.length
+      const lastValue =
+        mode === "tree"
+          ? treeRows[rowCount - 1]?.node.value
+          : renderedItems[rowCount - 1]?.value
+      const highlighted = getHighlighted()
+      const atEnd =
+        rowCount === 0 ||
+        (highlighted != null && highlighted.value === lastValue)
+      if (atEnd) {
+        const panel = field.closest<HTMLElement>('[data-slot="cascader-panel"]')
+        const stop = panel ? getCascaderFooterStops(panel)[0] : undefined
+        if (stop) {
+          event.preventDefault()
+          // Base UI's handler is deliberately NOT vetoed: its wrap's first
+          // press CLEARS the highlight, so no stale row stays active behind the
+          // focused command, and the emptied highlight completes the ring.
+          stop.focus()
+          return
+        }
+      }
+    }
+
+    // The level keys are LOGICAL, not physical: in RTL, ArrowLeft opens a
+    // branch and ArrowRight goes back. They act only at the caret edge, and
+    // those guards do NOT mirror: `selectionStart === 0` is the logical start.
+    const rtl = isCascaderRtl(field, direction)
+    const forwardKey = rtl ? "ArrowLeft" : "ArrowRight"
+    const backKey = rtl ? "ArrowRight" : "ArrowLeft"
+
+    if (mode === "tree") {
+      handleTreeKeyDown(
+        event,
+        field,
+        caretAtStart,
+        caretAtEnd,
+        forwardKey,
+        backKey
+      )
+      return
+    }
+
+    if (event.key === forwardKey && caretAtEnd) {
+      const highlighted = getHighlighted()
+      if (highlighted && isBranch(highlighted)) {
+        event.preventDefault()
+        navigate(highlighted)
+        return
+      }
+    }
+
+    // Backspace on an empty query pops a level too, so the keyboard way out of
+    // a level is symmetric with typing into it.
+    if (
+      (event.key === backKey && caretAtStart) ||
+      (event.key === "Backspace" && query.length === 0)
+    ) {
+      if (path.length > 0) {
+        event.preventDefault()
+        popLevel()
+      }
+    }
+  }
+
+  return (
+    <div
+      data-slot="cascader-input-row"
+      className={cn(
+        "flex shrink-0 items-center gap-1",
+        /* Each style sizes a combobox search field only as a DIRECT child of
+           the popup; this row is nested, so the ladder is mirrored here rather
+           than hardcoding one height for all eight styles. */
+        "h-8"
+      )}
+    >
+      {showBack ? <CascaderBack /> : null}
+      <ComboboxPrimitive.Input
+        data-slot="cascader-input"
+        placeholder={resolvedPlaceholder}
+        onKeyDown={handleKeyDown}
+        /* Nothing on screen says the level keys exist. */
+        aria-describedby={[ariaDescribedBy, hintId].filter(Boolean).join(" ")}
+        /* Conditional: an explicit `undefined` deletes Base UI's own value. */
+        {...(mode === "tree" ? { "aria-haspopup": "tree" as const } : null)}
+        /* Base UI omits BOTH `aria-expanded` and `aria-controls` while inline,
+           and an embedded panel is permanently expanded, so supply both. */
+        {...(inline
+          ? { "aria-expanded": true, "aria-controls": listId }
+          : null)}
+        /* No trigger to carry the invalid state in the `inline` case. */
+        {...(invalid ? { "aria-invalid": true, "data-invalid": "" } : null)}
+        className={cn(
+          "placeholder:text-muted-foreground h-full w-full min-w-0 flex-1 bg-transparent px-1.5 text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
+          backVisible && "ps-0",
+          className
+        )}
+        {...props}
+      />
+      <span id={hintId} ref={hintRef} className="sr-only">
+        {/* `hintDir`, not `direction`: the context alone misses an RTL app that
+            uses a `dir` attribute instead of `DirectionProvider`. */}
+        {labels.keyboardHint(mode, hintDir)}
+      </span>
+    </div>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Value                                   */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderValueProps extends Omit<
+  useRender.ComponentProps<"span">,
+  "children"
+> {
+  /** `path` shows the full trail, `leaf` only the node, `count` only a total. */
+  display?: CascaderValueDisplay
+  maxSegments?: number
+  collapse?: CascaderCollapse
+  separator?: React.ReactNode
+  /** Renders the selected node's icon before the trail. */
+  showIcon?: boolean
+  placeholder?: React.ReactNode
+  /** Replaces the whole rendering. Receives the resolved selection and path. */
+  children?: (selected: CascaderNode[], path: CascaderNode[]) => React.ReactNode
+}
+
+/**
+ * Trigger display. Defaults to the collapsed selection path rather than a bare
+ * leaf label, which in a nested picker is frequently ambiguous.
+ */
+function CascaderValue({
+  className,
+  display = "path",
+  maxSegments = 3,
+  collapse = "middle",
+  separator,
+  showIcon = true,
+  placeholder,
+  children,
+  ...props
+}: CascaderValueProps) {
+  const { labels, multiple, resolveNode } = useCascaderActions()
+  const { index, selectedValues } = useCascaderState()
+
+  // `resolveNode`, not `index.byValue`: a selection missing from `items` (async
+  // children, a removed item) must still render a label, not an empty trigger.
+  const selected = selectedValues.map(resolveNode)
+
+  const resolvedPath =
+    selectedValues.length === 1 ? getCascaderPath(index, selectedValues[0]) : []
+  // No ancestor chain: fall back to the node so `display="path"` shows a leaf.
+  const path =
+    resolvedPath.length > 0
+      ? resolvedPath
+      : selected.length === 1
+        ? selected
+        : []
+
+  let content: React.ReactNode
+
+  if (children) {
+    content = children(selected, path)
+  } else if (selectedValues.length === 0) {
+    content = (
+      <span className="text-muted-foreground truncate">{placeholder}</span>
+    )
+  } else if (display === "count" || (multiple && selectedValues.length > 1)) {
+    content = labels.selectedCount(selectedValues.length)
+  } else {
+    const leaf = path[path.length - 1] ?? selected[0]
+    const segments =
+      display === "leaf"
+        ? [{ type: "node" as const, node: leaf }]
+        : collapseCascaderPath(path, { maxSegments, collapse })
+
+    content = (
+      <>
+        {showIcon && leaf?.icon ? (
+          <span
+            data-slot="cascader-value-icon"
+            className="text-muted-foreground flex shrink-0 items-center"
+          >
+            {leaf.icon}
+          </span>
+        ) : null}
+        {segments.map((segment, i) => (
+          <React.Fragment
+            key={segment.type === "node" ? segment.node.value : `gap-${i}`}
+          >
+            {i > 0 ? (separator ?? <PathChevron />) : null}
+            {segment.type === "ellipsis" ? (
+              <span
+                data-slot="cascader-value-ellipsis"
+                title={segment.hidden
+                  .map((n) => n.label)
+                  .join(` ${labels.pathSeparator} `)}
+                className="text-muted-foreground shrink-0"
+              >
+                &hellip;
+              </span>
+            ) : (
+              <span
+                className={cn(
+                  "truncate",
+                  i < segments.length - 1 && "text-muted-foreground"
+                )}
+              >
+                {segment.node?.label}
+              </span>
+            )}
+          </React.Fragment>
+        ))}
+      </>
+    )
+  }
+
+  const defaultProps = {
+    "data-slot": "cascader-value",
+    className: cn("flex min-w-0 items-center gap-1 truncate", className),
+    children: content,
+  }
+
+  return useRender({
+    defaultTagName: "span",
+    render: props.render,
+    props: mergeProps<"span">(defaultProps, props),
+  })
+}
+
+export {
+  CascaderNav,
+  CascaderBack,
+  CascaderBreadcrumb,
+  CascaderInput,
+  CascaderValue,
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader-types.tsx b/apps/web/src/components/reui/cascader/cascader-types.tsx
new file mode 100644
index 0000000..518efa9
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-types.tsx
@@ -0,0 +1,220 @@
+import type * as React from "react"
+
+/**
+ * A node in the cascader tree. Two input shapes normalize to one internal
+ * index: nested (nodes carry `children`), or flat adjacency plus the root's
+ * `getParent`, which skips the re-nesting step for large datasets.
+ */
+export interface CascaderNode<T = unknown> {
+  /** Stable id. Also the committed selection value. */
+  value: string
+  label: string
+  icon?: React.ReactNode
+  description?: string
+  children?: CascaderNode<T>[]
+  /** Declares a branch before load; async nodes read as leaves without it. */
+  hasChildren?: boolean
+  /** Trailing count. Defaults to known children; set it for async nodes. */
+  count?: number
+  /** Listed, never selected or opened; on a branch, its whole subtree too. */
+  disabled?: boolean
+  keywords?: string[]
+  /**
+   * Only read on a node nested inside a `getChildren` result. For the level a
+   * node OWNS the authoritative signal is that level's `CascaderLoadResult`.
+   */
+  hasMore?: boolean
+  data?: T
+}
+
+/**
+ * One footer ACTION. Deliberately not a `CascaderNode`, so a command can never
+ * be passed where an option is expected and join the ring, filter or selection.
+ */
+export interface CascaderActionItem {
+  /** Stable key. Falls back to the label when it is a string, then the index. */
+  value?: string
+  label: React.ReactNode
+  icon?: React.ReactNode
+  disabled?: boolean
+  /** Ignored when `items` is present - a flyout opens instead. */
+  onSelect?: () => void
+  /** Turns the row into a submenu trigger. One level deep on purpose. */
+  items?: CascaderActionItem[]
+  /** Consecutive entries sharing a heading are drawn under one. */
+  group?: string
+}
+
+/** Panel layout. See the docs for the keyboard map of each. */
+export type CascaderMode = "drill" | "columns" | "tree"
+
+export type CascaderSearchScope = "level" | "deep" | "global"
+
+/**
+ * Which nodes may be committed. The predicate arm is generic over the payload
+ * rather than quantified per call: a per-call `<T>` would force every predicate
+ * to accept EVERY payload, so `(node: CascaderNode<Member>) => boolean` could
+ * never satisfy it.
+ */
+export type CascaderSelectable<T = unknown> =
+  | "leaf"
+  | "any"
+  | ((node: CascaderNode<T>) => boolean)
+
+export type CascaderCollapse = "middle" | "start" | "none"
+
+export type CascaderValueDisplay = "path" | "leaf" | "count"
+
+export type CascaderChangeReason = "select" | "deselect" | "clear"
+
+/** Second argument to `onValueChange`: resolved nodes, so no re-lookup. */
+export interface CascaderChangeDetails<T = unknown> {
+  /** The node committed or toggled. Null when the selection was cleared. */
+  node: CascaderNode<T> | null
+  /** Ancestor chain of `node`, root first, node last. */
+  path: CascaderNode<T>[]
+  nodes: CascaderNode<T>[]
+  reason: CascaderChangeReason
+}
+
+/** Normalized tree, built once per `items` identity, shared by every mode. */
+export interface CascaderIndex<T = unknown> {
+  byValue: Map<string, CascaderNode<T>>
+  /** Children by parent value. Root children are keyed by `ROOT_KEY`. */
+  childrenOf: Map<string, CascaderNode<T>[]>
+  parentOf: Map<string, string | null>
+  /** Zero-based depth by node value. */
+  depthOf: Map<string, number>
+  /** Top level nodes, in input order. */
+  roots: CascaderNode<T>[]
+  /** Every node in a stable, depth-first order. Used by deep search. */
+  all: CascaderNode<T>[]
+  /** Resolved chain nodes listed last in a level that may still return them. */
+  pinned?: ReadonlySet<string>
+  /** Resolved chain nodes whose level loaded completely without them: they
+   * keep their path for the trigger, and are no row, hit or cascade child. */
+  hidden?: ReadonlySet<string>
+}
+
+export interface CascaderFlatNode<T = unknown> {
+  node: CascaderNode<T>
+  depth: number
+  /** Known children, or a declared `hasChildren`. */
+  branch: boolean
+  expanded: boolean
+  /** Sibling count, plus one when the level has a paging row. */
+  setSize: number
+  /** One-based index among siblings. */
+  posInSet: number
+}
+
+/** One segment of a rendered path, after collapsing. */
+export type CascaderPathSegment<T = unknown> =
+  | { type: "node"; node: CascaderNode<T> }
+  | { type: "ellipsis"; hidden: CascaderNode<T>[] }
+
+/**
+ * Async load state for one node's children. Deliberately WITHOUT a `status`
+ * field: "declared a branch, never fetched" and "fetched and genuinely empty"
+ * are told apart by MAP MEMBERSHIP, and a second source of that truth would
+ * eventually disagree with the first.
+ */
+export interface CascaderLoadState {
+  loading: boolean
+  error: boolean
+  hasMore: boolean
+  /** Opaque cursor handed back to `getChildren` for the next page. */
+  cursor?: string
+}
+
+/** Why a level was fetched. `resolve`: `resolveValue` hit an unloaded node. */
+export type CascaderLoadReason =
+  | "level"
+  | "more"
+  | "prefetch"
+  | "retry"
+  | "resolve"
+
+/** Argument handed to `getChildren` and `resolveValue`. */
+export interface CascaderLoadContext {
+  /**
+   * Aborted when the request is superseded, `loadKey` changes or the cascader
+   * unmounts, and for a `getChildren` load also when the popup closes.
+   */
+  signal: AbortSignal
+  cursor?: string
+  reason?: CascaderLoadReason
+}
+
+/** Value returned by `getChildren`. A bare array is also accepted. */
+export interface CascaderLoadResult<T = unknown> {
+  items: CascaderNode<T>[]
+  nextCursor?: string
+  /** Defaults to whether `nextCursor` was supplied. */
+  hasMore?: boolean
+}
+
+/** Argument handed to `onSearch`. */
+export interface CascaderSearchContext {
+  signal: AbortSignal
+  /** The path the user is searching within, deepest last. Empty under a
+   * global search, whose scope is the whole tree. */
+  path: string[]
+}
+
+/**
+ * Every user facing string, so the primitive ships no hardcoded copy. The
+ * callbacks take plain labels, not nodes: a `CascaderNode<T>` parameter would
+ * force this object to carry the item generic. `*Announcement` is live-region.
+ */
+export interface CascaderLabels {
+  /** `parentLabel` is absent at the root and under a global search. */
+  search: string | ((parentLabel?: string) => string)
+  back: string
+  /** A level's FIRST page. `loadingMore` is the next, `loadMore` its idle row. */
+  loading: string
+  loadingMore: string
+  loadMore: string
+  error: string
+  retry: string
+  empty: string
+  /** Rendered by `CascaderValue` when `display="count"`. */
+  selectedCount: (count: number) => string
+  breadcrumbLabel: string
+  chipsLabel: string
+  removeChip: (label: string) => string
+  /** Trail separator. Not every locale writes one with a slash. */
+  pathSeparator: string
+  /** Names the root level wherever there is no parent node to name it. */
+  rootLevel: string
+  itemCount: (count: number) => string
+  /** Appended to a branch row's name outside tree mode: it opens another list. */
+  branchAffordance: string
+  /** Columns-trail rows are plain buttons, so they carry no `aria-selected`. */
+  selectedState: string
+  /** Same for the mixed state, which a `role="button"` row may not carry. */
+  partiallySelectedState: string
+  columnsLabel: string
+  actionsLabel: string
+  submenuAffordance: string
+  panelLabel: string
+  /** Read per mode AND per direction: the level keys mirror in RTL. */
+  keyboardHint: (mode: CascaderMode, dir: "ltr" | "rtl") => string
+  rootAnnouncement: (count: number) => string
+  expandedAnnouncement: (label: string, count: number) => string
+  collapsedAnnouncement: (label: string) => string
+  levelAnnouncement: (
+    parentLabel: string,
+    depth: number,
+    count: number
+  ) => string
+  resultsAnnouncement: (count: number) => string
+  maxReachedAnnouncement: (max: number) => string
+  /** `count` is the descendants swept along; `selecting` is the direction. */
+  cascadeAnnouncement: (
+    label: string,
+    count: number,
+    selecting: boolean
+  ) => string
+  searchingAnnouncement: string
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader-virtual.tsx b/apps/web/src/components/reui/cascader/cascader-virtual.tsx
new file mode 100644
index 0000000..2939ec2
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader-virtual.tsx
@@ -0,0 +1,470 @@
+"use client"
+
+import * as React from "react"
+import { CascaderColumnPanel } from "@/components/reui/cascader/cascader-columns"
+import {
+  useCascaderActions,
+  useCascaderHighlight,
+  useCascaderState,
+} from "@/components/reui/cascader/cascader-context"
+import type { CascaderColumn } from "@/components/reui/cascader/cascader-context"
+import {
+  CascaderItem,
+  CascaderItems,
+  getCascaderMoreProps,
+} from "@/components/reui/cascader/cascader-item"
+import {
+  defaultRangeExtractor,
+  useVirtualizer,
+  type Range,
+  type Virtualizer,
+} from "@tanstack/react-virtual"
+
+/**
+ * Windowing for the cascader, in its own file so the primitive's own install
+ * never pulls `@tanstack/react-virtual` in. Base UI forces three rules:
+ *
+ * 1. A windowed row MUST carry an explicit `index`; the fallback
+ *    `findItemIndex` is O(n) per row and returns `-1` on the frame a level swap
+ *    renders empty, dangling `aria-activedescendant`.
+ * 2. That index is DESTRUCTIVE while unvirtualized (`useCompositeListItem`
+ *    skips registration, `CompositeList` truncates `elementsRef` to zero and
+ *    the first arrow key highlights nothing), so rows stay plain until the root
+ *    flips `virtualized`, gated inside `CascaderItem`.
+ * 3. No `Combobox.Collection` and no FUNCTION CHILD on `Combobox.List`, which
+ *    implicitly wraps one in a Collection: a Collection renders every filtered
+ *    item.
+ */
+
+/* -------------------------------------------------------------------------- */
+/*                                 Virtualizer                                */
+/* -------------------------------------------------------------------------- */
+
+export interface UseCascaderVirtualizerOptions {
+  count: number
+  getScrollElement: () => HTMLElement | null
+  estimateSize?: number
+  overscan?: number
+  /** Key rows by node value, never by index: a tree expand shifts every index. */
+  getItemKey: (index: number) => string | number
+  /** Render index of the highlighted row, or `-1`. Pinned into the window. */
+  activeIndex?: number
+}
+
+export type CascaderVirtualizer = Virtualizer<HTMLElement, HTMLElement>
+
+/**
+ * The cascader's virtualizer: TanStack plus the highlight pinning and
+ * scroll-into-view a combobox list needs. `activeIndex` is clamped here, not by
+ * the caller: emitted from a layout effect, it can be one commit ahead of a
+ * level that just shrank and would otherwise scroll to a row that is gone.
+ */
+export function useCascaderVirtualizer({
+  count,
+  getScrollElement,
+  estimateSize = 32,
+  overscan = 8,
+  getItemKey,
+  activeIndex = -1,
+}: UseCascaderVirtualizerOptions): CascaderVirtualizer {
+  const active = activeIndex >= 0 && activeIndex < count ? activeIndex : -1
+
+  // Keeps the highlighted row mounted so `aria-activedescendant` never dangles.
+  const rangeExtractor = React.useCallback(
+    (range: Range) => {
+      const indices = new Set(defaultRangeExtractor(range))
+      if (active !== -1) indices.add(active)
+      return Array.from(indices).sort((a, b) => a - b)
+    },
+    [active]
+  )
+
+  const measureEstimate = React.useCallback(() => estimateSize, [estimateSize])
+
+  // React Compiler bails on `useVirtualizer` HERE, and only here - the bail does not
+  // propagate to the components that call this hook. They opt out themselves.
+  // eslint-disable-next-line react-hooks/incompatible-library
+  const virtualizer = useVirtualizer<HTMLElement, HTMLElement>({
+    count,
+    getScrollElement,
+    estimateSize: measureEstimate,
+    overscan,
+    getItemKey,
+    rangeExtractor,
+  })
+
+  // Base UI's scroll-into-view no-ops on a windowed-out row (empty `listRef`).
+  React.useEffect(() => {
+    if (active === -1) return
+    virtualizer.scrollToIndex(active, { align: "auto" })
+  }, [active, count, virtualizer])
+
+  return virtualizer
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Geometry                                  */
+/* -------------------------------------------------------------------------- */
+
+interface CascaderVirtualGutter {
+  block: number
+  inline: number
+}
+
+const NO_GUTTER: CascaderVirtualGutter = { block: 0, inline: 0 }
+
+/**
+ * The ROWS' BOX's own padding, never the scrollport's (separate element, reads
+ * a flat zero). Measured because every style sets its own: a windowed row is
+ * positioned against this box's PADDING box while the scroll-height spacer is
+ * an in-flow child of its CONTENT box, so without it rows sit flush.
+ */
+function useCascaderVirtualGutter(
+  contentElement: HTMLElement | null
+): CascaderVirtualGutter {
+  const [gutter, setGutter] = React.useState<CascaderVirtualGutter>(NO_GUTTER)
+
+  React.useLayoutEffect(() => {
+    if (!contentElement) return
+    const styles = getComputedStyle(contentElement)
+    const block = Number.parseFloat(styles.paddingTop) || 0
+    const inline =
+      Number.parseFloat(styles.paddingInlineStart || styles.paddingLeft) || 0
+    setGutter((previous) =>
+      previous.block === block && previous.inline === inline
+        ? previous
+        : { block, inline }
+    )
+  }, [contentElement])
+
+  return gutter
+}
+
+/** Logical insets, not `left` / `width`, so RTL needs no second code path. */
+function cascaderVirtualRowStyle(
+  start: number,
+  gutter: CascaderVirtualGutter
+): React.CSSProperties {
+  return {
+    position: "absolute",
+    top: 0,
+    insetInlineStart: gutter.inline,
+    insetInlineEnd: gutter.inline,
+    transform: `translateY(${start + gutter.block}px)`,
+  }
+}
+
+/**
+ * The element that actually SCROLLS: the `ScrollArea` viewport above the rows'
+ * box, not the rows' box itself, which never overflows, so a virtualizer aimed
+ * at it would read a full `clientHeight` and render every row. `closest` rather
+ * than `parentElement`, plus a fallback to the content element, keeps a
+ * hand-written `overflow-y-auto` container working.
+ */
+function cascaderScrollElement(
+  content: HTMLElement | null
+): HTMLElement | null {
+  if (!content) return null
+  return (
+    content.closest<HTMLElement>('[data-slot="scroll-area-viewport"]') ??
+    content
+  )
+}
+
+/**
+ * `role="presentation"` keeps the listbox owning nothing but options, and this
+ * node's parent IS the rows' box, saving a ref threaded through `CascaderList`.
+ */
+function CascaderVirtualSpacer({
+  height,
+  onContentElement,
+}: {
+  height: number
+  onContentElement: (element: HTMLElement | null) => void
+}) {
+  return (
+    <div
+      ref={(node) => onContentElement(node?.parentElement ?? null)}
+      role="presentation"
+      data-slot="cascader-virtual-spacer"
+      style={{ height }}
+    />
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Rows                                    */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderVirtualItemsProps {
+  /** Row height before measurement. Defaults to the root `estimateRowSize`. */
+  estimateSize?: number
+  /** Rows rendered beyond each edge. Defaults to the root `overscan`. */
+  overscan?: number
+}
+
+/**
+ * Windowed replacement for `CascaderItems`, dropped inside `CascaderList`. The
+ * registration is a LAYOUT effect because the root derives `virtualized` from
+ * it and the flip has to land before the browser paints. Until the root has
+ * seen it, this renders exactly what `CascaderItems` does, so no frame carries
+ * indexed rows while Base UI still owns the composite list.
+ */
+function CascaderVirtualItems(props: CascaderVirtualItemsProps) {
+  const { virtualized, registerVirtualRenderer } = useCascaderActions()
+
+  React.useLayoutEffect(
+    () => registerVirtualRenderer(),
+    [registerVirtualRenderer]
+  )
+
+  if (!virtualized) return <CascaderItems />
+
+  return <CascaderVirtualRows {...props} />
+}
+
+function CascaderVirtualRows({
+  estimateSize,
+  overscan,
+}: CascaderVirtualItemsProps) {
+  /* The `useCascaderVirtualizer` bail does NOT reach here: the compiler caches
+     `getVirtualItems()` on the virtualizer, whose identity never changes, so the
+     window freezes on scroll. Inert where no compiler runs. */
+  "use no memo"
+
+  const {
+    estimateRowSize,
+    overscan: rootOverscan,
+    mode,
+    isBranch,
+    isSelectable,
+    isSelected,
+    isIndeterminate,
+  } = useCascaderActions()
+  const { renderedItems, treeRows, deepResults, loadStates } =
+    useCascaderState()
+  // Re-renders on every highlight change, and has to: the pinned row and the
+  // scroll target are both derived from it.
+  const highlight = useCascaderHighlight()
+
+  const [contentElement, setContentElement] =
+    React.useState<HTMLElement | null>(null)
+  const gutter = useCascaderVirtualGutter(contentElement)
+
+  const tree = mode === "tree"
+  const count = tree ? treeRows.length : renderedItems.length
+  const showPath = !tree && deepResults !== null
+
+  const getItemKey = React.useCallback(
+    (index: number) =>
+      (tree ? treeRows[index]?.node.value : renderedItems[index]?.value) ??
+      index,
+    [tree, treeRows, renderedItems]
+  )
+
+  const virtualizer = useCascaderVirtualizer({
+    count,
+    getScrollElement: () => cascaderScrollElement(contentElement),
+    estimateSize: estimateSize ?? estimateRowSize,
+    overscan: overscan ?? rootOverscan,
+    getItemKey,
+    activeIndex: highlight.index,
+  })
+
+  return (
+    <>
+      <CascaderVirtualSpacer
+        height={virtualizer.getTotalSize()}
+        onContentElement={setContentElement}
+      />
+      {virtualizer.getVirtualItems().map((row) => {
+        const flat = tree ? treeRows[row.index] : undefined
+        const node = tree ? flat?.node : renderedItems[row.index]
+        // For one commit after a query narrows the level, the window can name
+        // a row it no longer has; the count recomputes on the same tick.
+        if (!node) return null
+
+        return (
+          <CascaderItem
+            key={row.key}
+            /* Measured, not estimated: rows are two lines with a `description`
+               and three in deep or global search, and row height is per
+               style. An estimate alone would make `scrollToIndex` land on the
+               wrong row. */
+            ref={virtualizer.measureElement}
+            data-index={row.index}
+            style={cascaderVirtualRowStyle(row.start, gutter)}
+            node={node}
+            index={row.index}
+            depth={flat?.depth}
+            expanded={flat?.expanded}
+            branch={flat ? flat.branch : isBranch(node)}
+            selectable={isSelectable(node)}
+            selected={isSelected(node)}
+            indeterminate={isIndeterminate(node)}
+            {...getCascaderMoreProps(node, loadStates)}
+            showPath={showPath}
+            aria-setsize={flat ? flat.setSize : count}
+            aria-posinset={flat ? flat.posInSet : row.index + 1}
+          />
+        )
+      })}
+    </>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Column                                   */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderVirtualColumnProps extends CascaderVirtualItemsProps {
+  column: CascaderColumn
+}
+
+/**
+ * Windowed replacement for one Miller column, passed through the
+ * `CascaderColumns` render slot. One virtualizer PER COLUMN, since columns
+ * scroll independently, and only the deepest is Base UI's listbox: the trail
+ * behind is `as="button"` rows outside Base UI, so it windows on its own row
+ * count rather than waiting for the root to flip.
+ */
+function CascaderVirtualColumn({
+  column,
+  estimateSize,
+  overscan,
+}: CascaderVirtualColumnProps) {
+  const {
+    virtualized,
+    registerVirtualRenderer,
+    virtualize,
+    virtualizeThreshold,
+  } = useCascaderActions()
+
+  React.useLayoutEffect(
+    () => registerVirtualRenderer(),
+    [registerVirtualRenderer]
+  )
+
+  const windowed = column.active
+    ? virtualized
+    : (virtualize ?? column.items.length >= virtualizeThreshold)
+
+  if (!windowed) return <CascaderColumnPanel column={column} />
+
+  return (
+    <CascaderColumnPanel column={column} virtualized>
+      {column.active ? (
+        <CascaderVirtualActiveColumnRows
+          column={column}
+          estimateSize={estimateSize}
+          overscan={overscan}
+        />
+      ) : (
+        <CascaderVirtualColumnRows
+          column={column}
+          estimateSize={estimateSize}
+          overscan={overscan}
+          activeIndex={-1}
+        />
+      )}
+    </CascaderColumnPanel>
+  )
+}
+
+/** Only the active column subscribes to the highlight; a trail column must not. */
+function CascaderVirtualActiveColumnRows(props: CascaderVirtualColumnProps) {
+  const highlight = useCascaderHighlight()
+  return <CascaderVirtualColumnRows {...props} activeIndex={highlight.index} />
+}
+
+function CascaderVirtualColumnRows({
+  column,
+  estimateSize,
+  overscan,
+  activeIndex,
+}: CascaderVirtualColumnProps & { activeIndex: number }) {
+  /* The `useCascaderVirtualizer` bail does NOT reach here: the compiler caches
+     `getVirtualItems()` on the virtualizer, whose identity never changes, so the
+     window freezes on scroll. Inert where no compiler runs. */
+  "use no memo"
+
+  const {
+    estimateRowSize,
+    overscan: rootOverscan,
+    baseId,
+    isBranch,
+    isSelectable,
+    isSelected,
+    isIndeterminate,
+  } = useCascaderActions()
+  const { loadStates } = useCascaderState()
+
+  const [contentElement, setContentElement] =
+    React.useState<HTMLElement | null>(null)
+  const gutter = useCascaderVirtualGutter(contentElement)
+
+  const items = column.items
+  const getItemKey = React.useCallback(
+    (index: number) => items[index]?.value ?? index,
+    [items]
+  )
+
+  const virtualizer = useCascaderVirtualizer({
+    count: items.length,
+    getScrollElement: () => cascaderScrollElement(contentElement),
+    estimateSize: estimateSize ?? estimateRowSize,
+    overscan: overscan ?? rootOverscan,
+    getItemKey,
+    activeIndex,
+  })
+
+  return (
+    <>
+      <CascaderVirtualSpacer
+        height={virtualizer.getTotalSize()}
+        onContentElement={setContentElement}
+      />
+      {virtualizer.getVirtualItems().map((row) => {
+        const node = items[row.index]
+        if (!node) return null
+        const open = node.value === column.activeValue
+
+        return (
+          <CascaderItem
+            key={row.key}
+            ref={virtualizer.measureElement}
+            data-index={row.index}
+            style={cascaderVirtualRowStyle(row.start, gutter)}
+            node={node}
+            as={column.active ? "option" : "button"}
+            depth={column.depth}
+            branch={isBranch(node)}
+            selectable={isSelectable(node)}
+            selected={isSelected(node)}
+            indeterminate={isIndeterminate(node)}
+            {...getCascaderMoreProps(node, loadStates)}
+            data-open={open || undefined}
+            className={open ? "bg-accent/60 text-accent-foreground" : undefined}
+            /* Only the listbox column may carry an index or listbox metadata.
+               A trail row is a `role="button"`, which allows neither. */
+            {...(column.active
+              ? {
+                  index: row.index,
+                  "aria-setsize": items.length,
+                  "aria-posinset": row.index + 1,
+                }
+              : null)}
+            {...(!column.active && open
+              ? {
+                  "aria-expanded": true,
+                  "aria-controls": `${baseId}-column-${column.depth + 1}`,
+                }
+              : null)}
+          />
+        )
+      })}
+    </>
+  )
+}
+
+export { CascaderVirtualColumn, CascaderVirtualItems }
\ No newline at end of file
diff --git a/apps/web/src/components/reui/cascader/cascader.tsx b/apps/web/src/components/reui/cascader/cascader.tsx
new file mode 100644
index 0000000..bd8606b
--- /dev/null
+++ b/apps/web/src/components/reui/cascader/cascader.tsx
@@ -0,0 +1,3066 @@
+import * as React from "react"
+import {
+  useCascaderLoader,
+  useCascaderLoadState,
+} from "@/components/reui/cascader/cascader-async"
+import type {
+  CascaderGetChildren,
+  CascaderOnSearch,
+  CascaderResolveValue,
+} from "@/components/reui/cascader/cascader-async"
+import {
+  CascaderActionsContext,
+  CascaderHighlightContext,
+  CascaderRenderContext,
+  CascaderStateContext,
+  createCascaderHighlightStore,
+  useCascaderActions,
+  useCascaderHighlight,
+  useCascaderRender,
+  useCascaderState,
+} from "@/components/reui/cascader/cascader-context"
+import type {
+  CascaderActionsContextValue,
+  CascaderColumn,
+  CascaderHighlight,
+  CascaderHighlightStore,
+  CascaderItemState,
+  CascaderRenderContextValue,
+  CascaderStateContextValue,
+} from "@/components/reui/cascader/cascader-context"
+import { resolveCascaderLabels } from "@/components/reui/cascader/cascader-i18n"
+import {
+  applyCascadeSelection,
+  buildCascaderIndex,
+  CASCADER_LIST_HEIGHT_CLASS,
+  CASCADER_LIST_PAD_CLASS,
+  CASCADER_ROOT_KEY,
+  CASCADER_ROWS_CLASS,
+  CASCADER_SCROLL_CLASS,
+  collapseCascaderPath,
+  createCascaderMoreNode,
+  filterCascaderLevel,
+  findAmbiguousCascaderLabels,
+  findCascaderDataIssues,
+  flattenCascaderTree,
+  focusCascaderHome,
+  getCascaderCheckedValues,
+  getCascaderChildren,
+  getCascaderCount,
+  getCascaderIndeterminateFrom,
+  getCascaderListedValues,
+  getCascaderPath,
+  getCascaderSelectedDescendants,
+  getCascaderTabTarget,
+  isCascaderBranch,
+  isCascaderDisabled,
+  isCascaderMoreNode,
+  isCascaderSelectable,
+  matchesCascaderQuery,
+  mergeCascaderIndex,
+  normalizeCascaderQuery,
+  searchCascaderDeep,
+  warnCascaderOnce,
+  withCascaderMoreRow,
+} from "@/components/reui/cascader/cascader-lib"
+import type { CascaderCheckedStrategy } from "@/components/reui/cascader/cascader-lib"
+import type {
+  CascaderActionItem,
+  CascaderChangeDetails,
+  CascaderChangeReason,
+  CascaderFlatNode,
+  CascaderIndex,
+  CascaderLabels,
+  CascaderLoadState,
+  CascaderMode,
+  CascaderNode,
+  CascaderSearchScope,
+  CascaderSelectable,
+} from "@/components/reui/cascader/cascader-types"
+import { Combobox as ComboboxPrimitive } from "@base-ui/react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { ScrollArea } from "@authportal/ui/components/scroll-area"
+import { ChevronDownIcon, XIcon } from "lucide-react"
+
+/** Stable `filteredItems` for a level swap; a fixed identity cannot loop. */
+const EMPTY: CascaderNode<never>[] = []
+
+/** Stable empty array for the `actions` prop, so a cascader with no footer
+ * does not republish the actions context on every render. */
+const EMPTY_ACTIONS: CascaderActionItem[] = []
+
+/** The `onSearch` scope of a global search: no path, so the whole tree. */
+const GLOBAL_SEARCH_PATH: string[] = []
+
+// Word joiner. A polite region reads only MUTATIONS, so alternate it.
+const ANNOUNCE_MARKER = "\u2060"
+
+// Delay before a query result-count reaches the live region: polite
+// announcements queue, and re-announcing per keystroke plays back stale
+// counts. Only the count defers; every event-shaped one stays immediate.
+const ANNOUNCE_DEBOUNCE = 150
+
+/* -------------------------------------------------------------------------- */
+/*                                   State                                    */
+/* -------------------------------------------------------------------------- */
+
+// Minimal controlled/uncontrolled resolver, hand-rolled because the repo has
+// no shared `useControllableState`; the root needs it five times.
+function useControllable<V>(
+  controlled: V | undefined,
+  defaultValue: V,
+  onChange?: (value: V) => void,
+  /** Prop name, used only by the development-time switching warning. */
+  devName?: string
+): [V, (next: V | ((prev: V) => V)) => void] {
+  const [uncontrolled, setUncontrolled] = React.useState(defaultValue)
+  const isControlled = controlled !== undefined
+  const value = isControlled ? controlled : uncontrolled
+
+  // Switching controlled/uncontrolled mid-life strands half the state.
+  const wasControlled = React.useRef(isControlled)
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production") return
+    if (wasControlled.current === isControlled || !devName) return
+    const from = wasControlled.current ? "controlled" : "uncontrolled"
+    const to = isControlled ? "controlled" : "uncontrolled"
+    wasControlled.current = isControlled
+    warnCascaderOnce(
+      `controlled-switch:${devName}`,
+      `\`${devName}\` switched from ${from} to ${to}. Decide once: pass \`${devName}\` for the whole life of the component, or pass only the default and let the cascader own it.`
+    )
+  }, [isControlled, devName])
+
+  // Written in an EFFECT: a discarded render would still have mutated a ref.
+  const latest = React.useRef({ value, isControlled, onChange })
+  React.useEffect(() => {
+    latest.current = { value, isControlled, onChange }
+  })
+
+  // The last PROP seen: it differs from the optimistic advance exactly when a
+  // controlled parent declines a change and re-renders nothing.
+  const lastProp = React.useRef(controlled)
+  React.useEffect(() => {
+    lastProp.current = controlled
+  })
+
+  const set = React.useCallback((next: V | ((prev: V) => V)) => {
+    const current = latest.current.value
+    const resolved =
+      typeof next === "function" ? (next as (prev: V) => V)(current) : next
+    if (Object.is(resolved, current)) {
+      // Dedup against the last PROP, not the optimistic advance: a parent that
+      // declines re-renders nothing, so deduping on the advance left the popup
+      // un-dismissable from the second Escape on.
+      if (
+        !latest.current.isControlled ||
+        Object.is(resolved, lastProp.current)
+      ) {
+        return
+      }
+    }
+
+    // Advance now so two updates in ONE batch compose, rather than the second
+    // reading a stale value and its `Object.is` dedup dropping it.
+    latest.current = { ...latest.current, value: resolved }
+
+    if (!latest.current.isControlled) setUncontrolled(resolved)
+    latest.current.onChange?.(resolved)
+  }, [])
+
+  return [value, set]
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Shallow stability                             */
+/* -------------------------------------------------------------------------- */
+
+function shallowEqualRecords(a: object, b: object): boolean {
+  const left = a as Record<string, unknown>
+  const right = b as Record<string, unknown>
+  const keys = Object.keys(left)
+  if (keys.length !== Object.keys(right).length) return false
+  for (const key of keys) {
+    if (!Object.is(left[key], right[key])) return false
+  }
+  return true
+}
+
+function shallowEqualItemLists(
+  a: readonly object[],
+  b: readonly object[]
+): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i] && !shallowEqualRecords(a[i], b[i])) return false
+  }
+  return true
+}
+
+// Reuses the previous value while the next merely says the same thing: an
+// inline `labels`/`actions` otherwise republishes the actions context, and
+// with it every row. Adjust-state-during-render, not a ref.
+function useShallowStable<V>(
+  value: V,
+  equal: (a: V & object, b: V & object) => boolean
+): V {
+  const [stable, setStable] = React.useState(value)
+  if (Object.is(value, stable)) return stable
+  const comparable =
+    typeof value === "object" &&
+    value !== null &&
+    typeof stable === "object" &&
+    stable !== null
+  if (comparable && equal(value as V & object, stable as V & object)) {
+    return stable
+  }
+  setStable(value)
+  return value
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Context                                   */
+/* -------------------------------------------------------------------------- */
+
+/** The pre-split shape, merged, so `useCascader()` returns what it always did. */
+export interface CascaderContextValue<T = unknown>
+  extends CascaderActionsContextValue<T>, CascaderStateContextValue<T> {}
+
+/**
+ * The cascader's internals, typed for the caller's own item payload.
+ * @deprecated Reads BOTH halves, so a caller re-renders on every keystroke.
+ * Prefer `useCascaderActions()` or `useCascaderState()`. Kept for compat.
+ */
+export function useCascader<T = unknown>(): CascaderContextValue<T> {
+  const actions = useCascaderActions<T>()
+  const state = useCascaderState<T>()
+
+  return React.useMemo(() => ({ ...actions, ...state }), [actions, state])
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Headless selection                            */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderSelection<T = unknown> {
+  /** The selected nodes, resolved. Empty when nothing is selected. */
+  selected: CascaderNode<T>[]
+  /** Ancestor chain per selected node, root first, node last. */
+  paths: CascaderNode<T>[][]
+  /** The single selection, or the first one in `multiple` mode. */
+  first: CascaderNode<T> | null
+  /** Ancestor chain of `first`. */
+  firstPath: CascaderNode<T>[]
+  count: number
+  isEmpty: boolean
+  multiple: boolean
+  remove: (value: string) => void
+  clear: () => void
+}
+
+/** Headless access to the selection, for a trigger that is not
+ * `CascaderValue`. Pass the payload explicitly to get `node.data` typed. */
+export function useCascaderSelection<T = unknown>(): CascaderSelection<T> {
+  const { multiple, setSelection } = useCascaderActions<T>()
+  const { index, selectedValues } = useCascaderState<T>()
+
+  return React.useMemo(() => {
+    const selected = selectedValues
+      .map((value) => index.byValue.get(value))
+      .filter(Boolean) as CascaderNode<T>[]
+    const paths = selectedValues.map((value) => getCascaderPath(index, value))
+
+    return {
+      selected,
+      paths,
+      first: selected[0] ?? null,
+      firstPath: paths[0] ?? [],
+      count: selectedValues.length,
+      isEmpty: selectedValues.length === 0,
+      multiple,
+      remove: (value: string) =>
+        setSelection(selectedValues.filter((entry) => entry !== value)),
+      // Explicit reason: emptying on purpose is not "deselect the last node".
+      clear: () => setSelection([], "clear"),
+    }
+  }, [index, selectedValues, multiple, setSelection])
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Root                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Why the navigation path changed.
+ * - `"drill"`: a branch was entered (row press, level arrow, search hit).
+ * - `"back"`: one level up (back control, Backspace on an empty query).
+ * - `"breadcrumb"`: a jump to an exact depth in the trail.
+ * - `"reveal"`: the reopen navigated to the level holding the selection.
+ * - `"external"`: `setPath` called from outside the primitive's own flows.
+ */
+export type CascaderPathChangeReason =
+  | "drill"
+  | "back"
+  | "breadcrumb"
+  | "reveal"
+  | "external"
+
+/** Everything independent of the selection mode; the rest is on the two arms. */
+export interface CascaderBaseProps<T = unknown> {
+  /** Nested tree, or a flat list when `getParent` is supplied. */
+  items: CascaderNode<T>[]
+  /** Opt in to flat adjacency input by returning each node's parent value. */
+  getParent?: (node: CascaderNode<T>) => string | null | undefined
+
+  /**
+   * Fetches one level on demand; `node` is `null` for the root, and only
+   * `{ value, label: value }` for a level on screen whose node has not loaded
+   * (a deep link, or a page-loaded level after a `loadKey` change). Return an
+   * array, or a `CascaderLoadResult` when the level pages. Pages cache apart
+   * from `items`; mark unfetched branches `hasChildren` or they read as leaves.
+   */
+  getChildren?: CascaderGetChildren<T>
+  /**
+   * Server-side search, debounced by `searchDebounce`; replaces the local scan
+   * while the query is set. Results are detached: resolvable by value, in no
+   * level. Ignored in `mode="tree"`, where a hit belongs to no visible branch.
+   */
+  onSearch?: CascaderOnSearch<T>
+  /** Milliseconds of quiet before `onSearch` fires. */
+  searchDebounce?: number
+  /**
+   * Resolves a value the loader has never seen into its ancestor chain, root
+   * first, so the trigger can path a server-supplied selection. Runs with the
+   * popup closed too. Does NOT mark those levels loaded: opening one still
+   * fetches, and lists the node after its rows while it has pages left.
+   */
+  resolveValue?: CascaderResolveValue<T>
+  /** Cache key. Changing it drops every page and aborts anything in flight. */
+  loadKey?: unknown
+  /** Prefetch a highlighted branch's children after a pause. Off by default. */
+  prefetch?: boolean
+  /**
+   * Called when a load fails. `context.parent` is the level (`null` for root);
+   * `context.reason` is `"level"`, `"more"`, `"retry"`, `"prefetch"`,
+   * `"search"` or `"resolve"`. Never for an aborted or superseded request.
+   */
+  onLoadError?: (
+    error: unknown,
+    context: { parent: string | null; reason: string }
+  ) => void
+
+  /** Which nodes may be committed. Defaults to leaves only. */
+  selectable?: CascaderSelectable<T>
+
+  /**
+   * Whether the built-in SINGLE-SELECT check is drawn. Defaults to true.
+   * `false` also gives back the inline-end gutter every style reserves for it;
+   * `data-selected` and `aria-selected` stay. A no-op under `multiple`, where
+   * the checkbox is the selection CONTROL rather than a decoration.
+   */
+  indicator?: boolean
+
+  /**
+   * Footer ACTIONS: commands pinned below the list, never rows in it, and never
+   * touching the data tree. A childless `<CascaderFooter />` draws these; an
+   * action with `items` opens a side-anchored flyout rather than firing.
+   */
+  actions?: CascaderActionItem[]
+
+  /**
+   * Parent/child cascading. Multi-select only, off by default, and it needs
+   * committable branches (`selectable="any"` or a predicate). A commit selects
+   * or deselects every SELECTABLE node in the KNOWN subtree (loaded, or on a
+   * resolved chain) and reconciles ancestors. KNOWN is the semantic, not a
+   * hedge: a commit must not fan out into a request per level, so children
+   * arriving later arrive unchecked.
+   */
+  cascade?: boolean
+
+  mode?: CascaderMode
+
+  /** How a branch opens from the pointer in columns mode's ACTIVE column.
+   * `"click"` is the default, and neither value ever commits a selection. */
+  expandTrigger?: "click" | "hover"
+
+  path?: string[]
+  defaultPath?: string[]
+  /** The second argument says WHY. An existing `(path) => void` still works. */
+  onPathChange?: (
+    path: string[],
+    details: { reason: CascaderPathChangeReason }
+  ) => void
+
+  expanded?: string[]
+  defaultExpanded?: string[]
+  onExpandedChange?: (expanded: string[]) => void
+
+  open?: boolean
+  defaultOpen?: boolean
+  /** Forwards Base UI's reason; a leaf commit's close says `"item-press"`. */
+  onOpenChange?: (open: boolean, details: { reason: string }) => void
+
+  /**
+   * Whether a SINGLE-SELECT leaf commit closes the popup. Defaults to true.
+   * `false` is for a compare-and-repick flow; Escape, outside press and the
+   * trigger still close. Ignored under `multiple`, which never closes.
+   */
+  closeOnSelect?: boolean
+
+  inputValue?: string
+  defaultInputValue?: string
+  onInputValueChange?: (value: string) => void
+
+  /**
+   * `"level"` (default) filters the level on screen, `"deep"` also searches
+   * below it, `"global"` searches the whole tree from any level.
+   */
+  searchScope?: CascaderSearchScope
+  /** Custom matcher, replacing label + keywords substring matching. */
+  filter?: (node: CascaderNode<T>, normalizedQuery: string) => boolean
+
+  /** On open, navigate to the level holding the selection. Default true.
+   * Not in `mode="tree"`, which has no levels to navigate. */
+  revealSelected?: boolean
+
+  maxHeight?: number | string
+
+  /**
+   * Window the rendered rows. `undefined` decides per level from
+   * `virtualizeThreshold`; `true`/`false` force it. Also opt-in at the markup
+   * level, so the base install pulls in no virtualization library.
+   */
+  virtualize?: boolean
+  /** Row count at which windowing turns itself on. */
+  virtualizeThreshold?: number
+  /** Row height handed to the virtualizer before a row has been measured. */
+  estimateRowSize?: number
+  /** Rows rendered beyond each edge of the viewport. */
+  overscan?: number
+
+  labels?: Partial<CascaderLabels>
+  /** Replaces the entire row, affordances included. */
+  renderItem?: (
+    node: CascaderNode<T>,
+    state: CascaderItemState<T>
+  ) => React.ReactNode
+  /** Replaces only the label block; icon, count, chevron and check stay. */
+  renderLabel?: (
+    node: CascaderNode<T>,
+    state: CascaderItemState<T>
+  ) => React.ReactNode
+
+  disabled?: boolean
+  /** Native form field name. Submits the selected value(s). */
+  name?: string
+  /** Id of the owning form, for a cascader rendered outside it. */
+  form?: string
+  /** Id of the control. Pairs the field with a `<label htmlFor>`. */
+  id?: string
+  /** Marks the field required for native form validation. */
+  required?: boolean
+  /** The value can be read and submitted, but not changed. */
+  readOnly?: boolean
+  /** Marks the field invalid: `aria-invalid` and `data-invalid` on the trigger,
+   * the chips and the input, which every style's error treatment reads. */
+  invalid?: boolean
+  /** Ref to the hidden input Base UI submits with, for form-library focus. */
+  inputRef?: React.Ref<HTMLInputElement>
+  /** Renders without a floating popup, for an embedded `CascaderPanel`. */
+  inline?: boolean
+
+  children?: React.ReactNode
+}
+
+export interface CascaderSingleProps<T = unknown> extends CascaderBaseProps<T> {
+  multiple?: false
+  value?: string
+  defaultValue?: string
+  onValueChange?: (value: string, details: CascaderChangeDetails<T>) => void
+  /** `never` so passing it is a compile error, not a silent no-op. */
+  max?: never
+}
+
+/** Multi-select props. Enables checkbox rows and chip display. */
+export interface CascaderMultipleProps<
+  T = unknown,
+> extends CascaderBaseProps<T> {
+  multiple: true
+  value?: string[]
+  defaultValue?: string[]
+  onValueChange?: (value: string[], details: CascaderChangeDetails<T>) => void
+  /** Cap on selections. Further picks are refused, the existing ones survive. */
+  max?: number
+}
+
+/** `multiple` discriminates: `value`, `onValueChange` and `max` narrow with it. */
+export type CascaderProps<T = unknown> =
+  | CascaderSingleProps<T>
+  | CascaderMultipleProps<T>
+
+/** Normalizes to an array. `""` is "no selection", not a node: it is the
+ * uncontrolled default, and resolving it would render a blank chip. */
+function toArray(value: string | string[] | undefined): string[] {
+  if (value == null) return []
+  if (Array.isArray(value)) return value.filter((entry) => entry !== "")
+  return value === "" ? [] : [value]
+}
+
+/* -------------------------------------------------------------------------- */
+/*                            Development warnings                            */
+/* -------------------------------------------------------------------------- */
+
+interface CascaderDevOptions<T> {
+  items: CascaderNode<T>[]
+  getParent?: (node: CascaderNode<T>) => string | null | undefined
+  mode: CascaderMode
+  multiple: boolean
+  cascade: boolean
+  indicator: boolean
+  selectable: CascaderSelectable<T>
+  searchScope: CascaderSearchScope
+  max: number | undefined
+  value: string | string[] | undefined
+  defaultValue: string | string[] | undefined
+  hasExpanded: boolean
+  hasPath: boolean
+  hasOnSearch: boolean
+}
+
+/** Misconfigurations that are SILENT by design. Once each, never in prod. */
+function useCascaderDevWarnings<T>(options: CascaderDevOptions<T>) {
+  const {
+    items,
+    getParent,
+    mode,
+    multiple,
+    cascade,
+    indicator,
+    selectable,
+    searchScope,
+    max,
+    value,
+    defaultValue,
+    hasExpanded,
+    hasPath,
+    hasOnSearch,
+  } = options
+
+  // O(n) over the raw input, so the memo is skipped outright in production.
+  const issues = React.useMemo(
+    () =>
+      process.env.NODE_ENV === "production"
+        ? null
+        : findCascaderDataIssues(items, getParent),
+    [items, getParent]
+  )
+
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production") return
+
+    for (const duplicate of issues?.duplicates ?? []) {
+      warnCascaderOnce(
+        `duplicate-value:${duplicate}`,
+        `Duplicate node value ${JSON.stringify(duplicate)}. \`value\` is the selection key, so only the first occurrence is indexed and the rest never render.`
+      )
+    }
+
+    for (const cycle of issues?.cycles ?? []) {
+      warnCascaderOnce(
+        `cycle:${cycle}`,
+        `\`getParent\` puts ${JSON.stringify(cycle)} on a cycle. The depth walk is cycle-guarded so nothing hangs, but every depth on that chain is clamped rather than derived.`
+      )
+    }
+  }, [issues])
+
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production") return
+
+    for (const [prop, current] of [
+      ["value", value],
+      ["defaultValue", defaultValue],
+    ] as const) {
+      if (current == null) continue
+      if (multiple && !Array.isArray(current)) {
+        warnCascaderOnce(
+          `value-shape:multiple:${prop}`,
+          `\`multiple\` is set but \`${prop}\` is a string. Multi-select reads and writes a \`string[]\`; a string is treated as no selection at all.`
+        )
+      } else if (!multiple && Array.isArray(current)) {
+        warnCascaderOnce(
+          `value-shape:single:${prop}`,
+          `\`${prop}\` is an array but \`multiple\` is not set. Single-select reads and writes a \`string\`; only the first entry would survive a commit.`
+        )
+      }
+    }
+
+    if (cascade && !multiple) {
+      warnCascaderOnce(
+        "cascade-without-multiple",
+        "`cascade` does nothing without `multiple`: a single selection has no subtree to propagate over."
+      )
+    }
+
+    if (cascade && selectable === "leaf") {
+      warnCascaderOnce(
+        "cascade-with-leaf-selectable",
+        '`cascade` does nothing while `selectable="leaf"`: no branch can be committed, so no commit ever has a subtree under it. Pass `selectable="any"` or a predicate that accepts branches.'
+      )
+    }
+
+    if (!indicator && multiple) {
+      warnCascaderOnce(
+        "indicator-false-with-multiple",
+        "`indicator={false}` does nothing with `multiple`: the checkbox is the selection control rather than a decoration, so it and its gutter stay. Mark selection your own way from `data-selected` on the row, and drop the prop."
+      )
+    }
+
+    if (max != null && !multiple) {
+      warnCascaderOnce(
+        "max-without-multiple",
+        "`max` does nothing without `multiple`: there is only ever one selection to cap."
+      )
+    }
+
+    if (hasExpanded && mode !== "tree") {
+      warnCascaderOnce(
+        `expanded-outside-tree:${mode}`,
+        `\`expanded\` only does something in \`mode="tree"\`, and this cascader is in \`mode="${mode}"\`. Drill and columns navigate with \`path\`.`
+      )
+    }
+
+    if (hasPath && mode === "tree") {
+      warnCascaderOnce(
+        "path-in-tree",
+        '`path` does nothing in `mode="tree"`: branches expand in place rather than replacing the level. Use `expanded`.'
+      )
+    }
+
+    if (searchScope === "deep" && mode === "tree") {
+      warnCascaderOnce(
+        "deep-search-in-tree",
+        '`searchScope="deep"` does nothing in `mode="tree"`: a tree query already matches at any depth and auto-expands the ancestors of every hit.'
+      )
+    }
+
+    if (searchScope === "global" && mode === "tree") {
+      warnCascaderOnce(
+        "global-search-in-tree",
+        '`searchScope="global"` does nothing in `mode="tree"`: a tree query already searches the whole tree and auto-expands the ancestors of every hit.'
+      )
+    }
+
+    if (hasOnSearch && mode === "tree") {
+      warnCascaderOnce(
+        "onsearch-in-tree",
+        '`onSearch` does nothing in `mode="tree"`: a tree query filters the loaded tree in place, and a server hit belongs to no visible branch, so its results would never render. The request is not fired. Filter the tree locally, or use drill or columns for server search.'
+      )
+    }
+  }, [
+    mode,
+    multiple,
+    cascade,
+    indicator,
+    selectable,
+    searchScope,
+    max,
+    value,
+    defaultValue,
+    hasExpanded,
+    hasPath,
+    hasOnSearch,
+  ])
+}
+
+/** What the `[]`-dep callbacks would otherwise close over. One ref, one
+ * effect, so "the last committed render" is defined in exactly one place. */
+interface CascaderLatest<T> {
+  index: CascaderIndex<T>
+  state: CascaderStateContextValue<T>
+  mode: CascaderMode
+  multiple: boolean
+  cascade: boolean
+  max: number | undefined
+  labels: CascaderLabels
+  closeOnSelect: boolean
+  selectedValues: string[]
+  deepResults: CascaderNode<T>[] | null
+  onValueChange:
+    | ((value: string | string[], details: CascaderChangeDetails<T>) => void)
+    | undefined
+  resolveNode: (value: string) => CascaderNode<T>
+  isSelectable: (node: CascaderNode<T>) => boolean
+  needsChildren: (node: CascaderNode<T>) => boolean
+  expanded: ReadonlySet<string>
+}
+
+/** A navigation waiting on a fetch. The `kind`s differ: a drill appends, a
+ * columns press replaces the trail from `depth`, a search hit swaps in its own
+ * `trail`, a tree press expands. */
+type CascaderPendingNavigation =
+  | {
+      value: string
+      kind: "push" | "at" | "expand"
+      /** `kind: "at"` only. The depth the pressed row belongs to. */
+      depth: number
+    }
+  | {
+      value: string
+      kind: "trail"
+      /** The hit's ancestor chain, root first, the hit itself last. */
+      trail: string[]
+    }
+
+/** No default on `T`: inferred from `items`, so `node.data` arrives typed. */
+function Cascader<T>({
+  items,
+  getParent,
+  getChildren,
+  onSearch,
+  searchDebounce,
+  resolveValue,
+  loadKey,
+  prefetch,
+  onLoadError,
+  value: valueProp,
+  defaultValue,
+  onValueChange: onValueChangeProp,
+  multiple = false,
+  selectable = "leaf",
+  indicator = true,
+  actions,
+  cascade = false,
+  max,
+  mode = "drill",
+  expandTrigger,
+  path: pathProp,
+  defaultPath,
+  onPathChange,
+  expanded: expandedProp,
+  defaultExpanded,
+  onExpandedChange,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  closeOnSelect = true,
+  inputValue: inputValueProp,
+  defaultInputValue = "",
+  onInputValueChange,
+  searchScope = "level",
+  filter,
+  revealSelected = true,
+  maxHeight,
+  virtualize,
+  virtualizeThreshold = 100,
+  estimateRowSize = 32,
+  overscan = 8,
+  labels: labelsProp,
+  renderItem,
+  renderLabel,
+  disabled,
+  name,
+  form,
+  id,
+  required,
+  readOnly,
+  invalid,
+  inputRef,
+  inline,
+  children,
+}: CascaderProps<T>) {
+  const baseIndex = React.useMemo(
+    () => buildCascaderIndex(items, getParent),
+    // `getParent` is stable by design: an inline accessor must not rebuild a
+    // 50k-node index.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [items]
+  )
+
+  const baseId = React.useId()
+
+  // Shallow-stabilized first: an inline `labels` would republish the context.
+  const stableLabelsProp = useShallowStable(labelsProp, shallowEqualRecords)
+
+  const labels = React.useMemo(
+    () => resolveCascaderLabels(stableLabelsProp),
+    [stableLabelsProp]
+  )
+
+  useCascaderDevWarnings({
+    items,
+    getParent,
+    mode,
+    multiple,
+    cascade,
+    indicator,
+    selectable,
+    searchScope,
+    max,
+    value: valueProp,
+    defaultValue,
+    hasExpanded:
+      expandedProp !== undefined ||
+      defaultExpanded !== undefined ||
+      onExpandedChange !== undefined,
+    hasPath:
+      pathProp !== undefined ||
+      defaultPath !== undefined ||
+      onPathChange !== undefined,
+    hasOnSearch: onSearch !== undefined,
+  })
+
+  // Public props are discriminated, internals are not: one assertion.
+  const onValueChange = onValueChangeProp as
+    | ((value: string | string[], details: CascaderChangeDetails<T>) => void)
+    | undefined
+
+  // No `onChange`: `onValueChange` takes a second argument, so `emitSelection`
+  // invokes it rather than the state hook, which only knows the value.
+  const [value, setValue] = useControllable<string | string[]>(
+    valueProp,
+    defaultValue ?? (multiple ? [] : ""),
+    undefined,
+    "value"
+  )
+  // Why the current path (or open) change is happening. Refs, not arguments:
+  // `useControllable` only passes a value, and its onChange runs synchronously
+  // inside the setter, so a ref written just before is exact. The path ref
+  // resets to `"external"`, which is what the consumer's `setPath` reports.
+  const pathReasonRef = React.useRef<CascaderPathChangeReason>("external")
+  const openReasonRef = React.useRef<string>("none")
+
+  const [path, setPath] = useControllable<string[]>(
+    pathProp,
+    defaultPath ?? [],
+    (next) => onPathChange?.(next, { reason: pathReasonRef.current }),
+    "path"
+  )
+  const [expandedList, setExpandedList] = useControllable<string[]>(
+    expandedProp,
+    defaultExpanded ?? [],
+    onExpandedChange,
+    "expanded"
+  )
+  const [open, setOpen] = useControllable<boolean>(
+    openProp,
+    defaultOpen,
+    (next) => onOpenChange?.(next, { reason: openReasonRef.current }),
+    "open"
+  )
+
+  /** The internal `setPath`: names its reason, then hands back to "external". */
+  const setPathWithReason = React.useCallback(
+    (
+      next: string[] | ((prev: string[]) => string[]),
+      reason: CascaderPathChangeReason
+    ) => {
+      pathReasonRef.current = reason
+      try {
+        setPath(next)
+      } finally {
+        pathReasonRef.current = "external"
+      }
+    },
+    [setPath]
+  )
+  const [query, setQuery] = useControllable<string>(
+    inputValueProp,
+    defaultInputValue,
+    onInputValueChange,
+    "inputValue"
+  )
+
+  const expanded = React.useMemo(() => new Set(expandedList), [expandedList])
+  const selectedValues = React.useMemo(() => toArray(value), [value])
+
+  /* --------------------------------- async -------------------------------- */
+
+  // On-screen levels, so the ones worth fetching. Columns shows the whole
+  // trail at once, which is why the loader is per-level, not one flag.
+  const levels = React.useMemo(() => {
+    if (mode === "tree") return [CASCADER_ROOT_KEY, ...expandedList]
+    if (mode === "columns") return [CASCADER_ROOT_KEY, ...path]
+    return [path.length ? path[path.length - 1] : CASCADER_ROOT_KEY]
+  }, [mode, path, expandedList])
+
+  // A SIBLING of the index build, never a step inside it: the build stays pure
+  // in `items`, the loader owns the pages, the merge is pure in both, and that
+  // is what makes loaded data survive an `items` change.
+  const loader = useCascaderLoader<T>({
+    base: baseIndex,
+    getChildren,
+    // Gated, not merely unrendered: a tree hit belongs to no visible branch.
+    onSearch: mode === "tree" ? undefined : onSearch,
+    resolveValue,
+    searchDebounce,
+    loadKey,
+    prefetch,
+    onLoadError,
+    // An inline cascader is never "open", but its panel is live.
+    enabled: open || !!inline,
+    query,
+    levels,
+    path: searchScope === "global" ? GLOBAL_SEARCH_PATH : path,
+    values: selectedValues,
+  })
+
+  const loadStates = loader.states
+
+  // Destructured here, not at the actions memo, because `navigate` sits above
+  // it. All three are `[]`-dep inside the loader, so identity is stable.
+  const { ensureLevel, retryLevel: retryLoaderLevel, invalidateLevel } = loader
+
+  /**
+   * Whether pressing this branch has to FETCH first: in flight, failed, or
+   * never asked. `baseIndex`, as `ensureLevel` asks it: the two must agree or a
+   * press parks a navigation nothing will ever settle.
+   */
+  const needsChildren = React.useCallback(
+    (node: CascaderNode<T>) => {
+      if (!loader.active) return false
+      const state = loadStates.get(node.value)
+      if (state) return state.loading || state.error
+      return !baseIndex.childrenOf.has(node.value)
+    },
+    [loader.active, loadStates, baseIndex]
+  )
+
+  // Levels with pages left, the only ones a resolved chain node is listed in.
+  // A string first, so a loading flip that leaves `hasMore` alone keeps the
+  // set, and the index, as they were.
+  const pagingKey = JSON.stringify(
+    Array.from(loadStates)
+      .filter(([, state]) => state.hasMore)
+      .map(([key]) => key)
+  )
+  const paging = React.useMemo(
+    () => new Set<string>(JSON.parse(pagingKey) as string[]),
+    [pagingKey]
+  )
+
+  // Keyed on the maps the merge reads, NOT the store: `withLoadState`
+  // returns a fresh store over the SAME maps, so keying on it rebuilt the
+  // whole index on every loading flip that changed no data.
+  const { pages, detached, links } = loader.store
+  const index = React.useMemo(
+    () => mergeCascaderIndex(baseIndex, pages, detached, links, paging),
+    [baseIndex, pages, detached, links, paging]
+  )
+
+  /** Whether a level needs the paging pseudo-row. A never-fetched level gets
+   * nothing; that is the empty state's job. Tree has no per-level empty state,
+   * so there the row is also the branch's loading and error surface. */
+  const needsMoreRow = React.useCallback(
+    (key: string, childCount: number) => {
+      const state = loadStates.get(key)
+      if (!state) return false
+      if (childCount > 0) return state.hasMore || state.loading || state.error
+      return mode === "tree" && (state.loading || state.error)
+    },
+    [loadStates, mode]
+  )
+
+  // Remembers every selected node, so the trigger keeps a label after it
+  // leaves the loaded set (or was never in it).
+  const labelCacheRef = React.useRef(new Map<string, CascaderNode<T>>())
+
+  // Populated during render, since the trigger reads it while rendering.
+  // Idempotent and prop-derived, so a discarded render is harmless.
+  for (const selected of selectedValues) {
+    const node = index.byValue.get(selected)
+    if (node) labelCacheRef.current.set(selected, node)
+  }
+
+  const resolveNode = React.useCallback(
+    (nodeValue: string): CascaderNode<T> =>
+      index.byValue.get(nodeValue) ??
+      labelCacheRef.current.get(nodeValue) ?? {
+        value: nodeValue,
+        label: nodeValue,
+      },
+    [index]
+  )
+
+  /* ------------------------------ derived view ----------------------------- */
+
+  const currentParentValue = path.length ? path[path.length - 1] : null
+  const currentParent = currentParentValue
+    ? (index.byValue.get(currentParentValue) ?? null)
+    : null
+
+  const currentLevelKey = currentParentValue ?? CASCADER_ROOT_KEY
+
+  const isDeepSearching =
+    (searchScope === "deep" || searchScope === "global") &&
+    query.trim().length > 0 &&
+    mode !== "tree"
+  // Global is the same scan from the root, whatever level is on screen.
+  const deepSearchWithin = searchScope === "global" ? null : currentParentValue
+
+  const localDeepResults = React.useMemo(() => {
+    if (!isDeepSearching) return null
+    return searchCascaderDeep(index, query, {
+      within: deepSearchWithin,
+      matches: filter,
+    })
+  }, [isDeepSearching, index, query, deepSearchWithin, filter])
+
+  // Server search wins over the local scan, or each hit shows up twice.
+  const deepResults = loader.searchResults ?? localDeepResults
+
+  const levelItems = React.useMemo(() => {
+    const level = getCascaderChildren(index, currentParentValue)
+    return filterCascaderLevel(level, query, filter)
+  }, [index, currentParentValue, query, filter])
+
+  /** The active level's rows plus the paging pseudo-row, appended HERE because
+   * every index Base UI hands out indexes this array: a DOM row missing from
+   * it shifts the highlight and every windowed row by one. */
+  const levelRendered = React.useMemo(() => {
+    if (deepResults) return deepResults
+    if (!needsMoreRow(currentLevelKey, levelItems.length)) return levelItems
+    return withCascaderMoreRow(
+      levelItems,
+      createCascaderMoreNode<T>(currentLevelKey, levelItems.length),
+      index.pinned
+    )
+  }, [deepResults, levelItems, currentLevelKey, needsMoreRow, index.pinned])
+
+  // Columns renders the whole trail, but only the deepest column is
+  // interactive through Base UI, so `renderedItems` stays what drill uses.
+  const columns = React.useMemo<CascaderColumn<T>[]>(() => {
+    if (mode !== "columns") return []
+    const trail: CascaderColumn<T>[] = []
+    for (let depth = 0; depth <= path.length; depth += 1) {
+      const parentValue = depth === 0 ? null : path[depth - 1]
+      const parent = parentValue
+        ? (index.byValue.get(parentValue) ?? null)
+        : null
+      const isActive = depth === path.length
+      let columnItems: CascaderNode<T>[]
+      if (isActive) {
+        columnItems = levelRendered
+      } else {
+        // A trail column pages on its own, without losing the columns right of it.
+        const key = parentValue ?? CASCADER_ROOT_KEY
+        const children = getCascaderChildren(index, parentValue)
+        columnItems = needsMoreRow(key, children.length)
+          ? withCascaderMoreRow(
+              children,
+              createCascaderMoreNode<T>(key, children.length),
+              index.pinned
+            )
+          : children
+      }
+      trail.push({
+        parent,
+        depth,
+        activeValue: path[depth] ?? null,
+        active: isActive,
+        // Only the active column is filtered: a query narrows what you type
+        // into, never the trail behind it.
+        items: columnItems,
+      })
+    }
+    return trail
+  }, [mode, path, index, levelRendered, needsMoreRow])
+
+  // Tree level keys needing a paging pseudo-row. With no per-level empty
+  // state, this is also where a still-loading branch says so.
+  const treeSentinels = React.useMemo(() => {
+    if (mode !== "tree") return undefined
+    const keys = new Set<string>()
+    const consider = (key: string) => {
+      if (needsMoreRow(key, index.childrenOf.get(key)?.length ?? 0)) {
+        keys.add(key)
+      }
+    }
+    consider(CASCADER_ROOT_KEY)
+    for (const value of expanded) consider(value)
+    return keys.size ? keys : undefined
+  }, [mode, index, expanded, needsMoreRow])
+
+  const treeRows = React.useMemo<CascaderFlatNode<T>[]>(() => {
+    if (mode !== "tree") return []
+    const rows = flattenCascaderTree(index, expanded, treeSentinels)
+    // Same normalizer as the level filter, so the two cannot disagree.
+    const normalized = normalizeCascaderQuery(query)
+    if (!normalized) return rows
+    // Matches every node, not just visible rows, and keeps the ancestors, or a
+    // hit inside a collapsed branch disappears. Same matcher as every other
+    // path, so keyword-only hits do not vanish in tree mode alone.
+    const keep = new Set<string>()
+    // Only a hit some level shows: a resolved node no loaded level lists kept
+    // its ancestors expanded over nothing, while the status said no results.
+    const listed = getCascaderListedValues(index)
+    for (const node of index.all) {
+      if (!listed.has(node.value)) continue
+      if (
+        !(filter
+          ? filter(node, normalized)
+          : matchesCascaderQuery(node, normalized))
+      ) {
+        continue
+      }
+      for (const ancestor of getCascaderPath(index, node.value)) {
+        keep.add(ancestor.value)
+      }
+    }
+    // No sentinels while filtering: that page would not have the query applied.
+    return flattenCascaderTree(index, new Set([...expanded, ...keep])).filter(
+      (row) => keep.has(row.node.value)
+    )
+  }, [mode, index, expanded, treeSentinels, query, filter])
+
+  // What `Combobox.Root` receives. Tree flattens to the same linear list, so
+  // selection and highlighting need no per-mode case.
+  const renderedItems = React.useMemo(
+    () => (mode === "tree" ? treeRows.map((row) => row.node) : levelRendered),
+    [mode, treeRows, levelRendered]
+  )
+
+  /* ---------------------------- level swap reset --------------------------- */
+
+  /** Base UI never resets the highlighted index on an `items` change and has
+   * no imperative setter; its one automatic reset is an out-of-range clamp, so
+   * a single empty frame trips it. The frame rides `filteredItems`, so the
+   * `items` identity stays put. */
+  const levelKey = currentParentValue ?? ""
+
+  // STATE, not a ref: a replayed render would see a ref advanced and skip it.
+  const [swap, setSwap] = React.useState({ key: levelKey, active: false })
+
+  if (swap.key !== levelKey) {
+    setSwap({ key: levelKey, active: true })
+  }
+  const swapping = swap.active && swap.key === levelKey
+
+  React.useLayoutEffect(() => {
+    if (swap.active) setSwap((prev) => ({ ...prev, active: false }))
+  }, [swap.active])
+
+  // The same frame on demand, for a navigation that lands on the level already
+  // on screen: the key never moves, so the check above never fires.
+  const resetHighlight = React.useCallback(() => {
+    setSwap((prev) => (prev.active ? prev : { ...prev, active: true }))
+  }, [])
+
+  /* ----------------------------- virtualization ---------------------------- */
+
+  // A COUNT: columns mounts one per column, and StrictMode remounts effects.
+  const [virtualRenderers, setVirtualRenderers] = React.useState(0)
+
+  const registerVirtualRenderer = React.useCallback(() => {
+    setVirtualRenderers((count) => count + 1)
+    return () => setVirtualRenderers((count) => Math.max(0, count - 1))
+  }, [])
+
+  const hasVirtualRenderer = virtualRenderers > 0
+  const wantsVirtual = virtualize ?? renderedItems.length >= virtualizeThreshold
+
+  // LATCHED per level: otherwise a query narrowing a 5,000 row level past the
+  // threshold tears the virtualizer down and rebuilds it on backspace, losing
+  // every measurement. State, not a ref, like `swap`.
+  const [virtualLatch, setVirtualLatch] = React.useState({
+    key: levelKey,
+    on: false,
+  })
+
+  const virtualized =
+    hasVirtualRenderer &&
+    (virtualLatch.key === levelKey
+      ? virtualLatch.on || wantsVirtual
+      : wantsVirtual)
+
+  if (!hasVirtualRenderer) {
+    // Nothing is windowing, so nothing may stay latched.
+    if (virtualLatch.on || virtualLatch.key !== levelKey) {
+      setVirtualLatch({ key: levelKey, on: false })
+    }
+  } else if (virtualLatch.key !== levelKey) {
+    setVirtualLatch({ key: levelKey, on: virtualized })
+  } else if (virtualized && !virtualLatch.on) {
+    setVirtualLatch({ key: levelKey, on: true })
+  }
+
+  /**
+   * One forced re-render, one commit AFTER windowing turns on. Base UI sizes
+   * `listRef` from `filteredItems` in a layout effect keyed on that array's
+   * identity, but `virtualized` reaches the list a commit later and the
+   * `CompositeList` teardown REPLACES `listRef` with an empty array nothing
+   * re-sizes, so ArrowDown stops at the last WINDOWED row. A passive effect is
+   * late enough: the teardown is scheduled from a layout effect.
+   */
+  const [virtualSyncs, setVirtualSyncs] = React.useState(0)
+
+  React.useEffect(() => {
+    if (!virtualized) return
+    setVirtualSyncs((count) => count + 1)
+  }, [virtualized])
+
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production") return undefined
+    if (virtualize !== true || hasVirtualRenderer) return undefined
+    // Deferred a tick: the renderer registers from a layout effect, so a
+    // synchronous check would report every correctly wired cascader.
+    const timeout = setTimeout(() => {
+      console.error(
+        "[Cascader] `virtualize` is true but no windowing renderer is mounted. " +
+          "Render <CascaderVirtualItems /> inside <CascaderList>, or " +
+          "<CascaderVirtualColumn /> through the <CascaderColumns> slot."
+      )
+    }, 0)
+    return () => clearTimeout(timeout)
+  }, [virtualize, hasVirtualRenderer])
+
+  /* ------------------------------ navigation ------------------------------ */
+
+  /** One signal per navigation, feeding the live region, bumped EXACTLY once
+   * per action. `seq` alternates the invisible marker so two identical
+   * announcements are still two mutations; `toggled` names the tree branch. */
+  const [announceSignal, setAnnounceSignal] = React.useState<{
+    seq: number
+    toggled: string | null
+    /** A one-off verbatim message: a `max` refusal, a cascade fan-out. STATE,
+     * so an unrelated render cannot clear it mid-read. */
+    notice: string | null
+  }>({ seq: 0, toggled: null, notice: null })
+
+  const bumpAnnouncement = React.useCallback((toggled: string | null) => {
+    setAnnounceSignal((prev) => ({ seq: prev.seq + 1, toggled, notice: null }))
+  }, [])
+
+  /** Speaks for interactions that change nothing on screen: a refusal returns
+   * before any state moves, a cascade sweep is invisible from the row pressed.
+   * The seq bump keeps two identical refusals two mutations. */
+  const announceNotice = React.useCallback((notice: string) => {
+    setAnnounceSignal((prev) => ({ seq: prev.seq + 1, toggled: null, notice }))
+  }, [])
+
+  /**
+   * The navigation a press asked for and a fetch has not answered yet. Load
+   * BEFORE you move: drilling in first threw away the list the user was
+   * reading and, on failure, stranded them on an error screen for a level they
+   * had never seen. Holding here keeps the old rows and puts the progress on
+   * the pressed row, whose chevron `CascaderItem` swaps for a spinner.
+   */
+  const [pendingNavigation, setPendingNavigation] =
+    React.useState<CascaderPendingNavigation | null>(null)
+
+  /** Asks for a branch's children and parks the navigation until they land.
+   * BOTH entry points are called unconditionally: `retryLevel` no-ops unless
+   * the level errored, `ensureLevel` no-ops if it has state, so a repeat press
+   * is free and the readiness decision stays inside the loader. */
+  const requestChildren = React.useCallback(
+    (node: CascaderNode<T>, pending: CascaderPendingNavigation) => {
+      setPendingNavigation(pending)
+      retryLoaderLevel(node.value)
+      ensureLevel(node.value, "level")
+      // Otherwise the panel is silent from the press until the level swaps.
+      bumpAnnouncement(null)
+    },
+    [retryLoaderLevel, ensureLevel, bumpAnnouncement]
+  )
+
+  const pushLevel = React.useCallback(
+    (nodeValue: string) => {
+      setPathWithReason((prev) => [...prev, nodeValue], "drill")
+      setQuery("")
+      bumpAnnouncement(null)
+    },
+    [setPathWithReason, setQuery, bumpAnnouncement]
+  )
+
+  const popLevel = React.useCallback(() => {
+    setPathWithReason(
+      (prev) => (prev.length ? prev.slice(0, -1) : prev),
+      "back"
+    )
+    setQuery("")
+    // Going BACK abandons a held navigation, or an in-flight branch drills in
+    // the moment it lands, long after the user moved on.
+    setPendingNavigation(null)
+    bumpAnnouncement(null)
+  }, [setPathWithReason, setQuery, bumpAnnouncement])
+
+  const goToDepth = React.useCallback(
+    (depth: number) => {
+      setPathWithReason(
+        (prev) => prev.slice(0, Math.max(0, depth)),
+        "breadcrumb"
+      )
+      setQuery("")
+      setPendingNavigation(null)
+      bumpAnnouncement(null)
+    },
+    [setPathWithReason, setQuery, bumpAnnouncement]
+  )
+
+  const toggleExpanded = React.useCallback(
+    (nodeValue: string) => {
+      setExpandedList((prev) =>
+        prev.includes(nodeValue)
+          ? prev.filter((v) => v !== nodeValue)
+          : [...prev, nodeValue]
+      )
+      bumpAnnouncement(nodeValue)
+    },
+    [setExpandedList, bumpAnnouncement]
+  )
+
+  const isBranch = React.useCallback(
+    (node: CascaderNode<T>) => isCascaderBranch(index, node),
+    [index]
+  )
+
+  const isSelectable = React.useCallback(
+    (node: CascaderNode<T>) => isCascaderSelectable(index, node, selectable),
+    [index, selectable]
+  )
+
+  const isDisabled = React.useCallback(
+    (node: CascaderNode<T>) => isCascaderDisabled(index, node),
+    [index]
+  )
+
+  // Whether a branch can be committed AT ALL here. `"leaf"` is the only
+  // setting that answers no in advance; a predicate is opaque, so the check
+  // gutter is reserved uniformly rather than per row.
+  const branchesSelectable = selectable !== "leaf"
+
+  // Open flyouts, by key. A ref, not state: `handleOpenChange` needs the
+  // answer as of the Escape being handled, and opening a footer menu must not
+  // re-render the root.
+  const openFlyoutsRef = React.useRef<Set<string>>(new Set())
+
+  const setFlyoutOpen = React.useCallback((key: string, open: boolean) => {
+    if (open) openFlyoutsRef.current.add(key)
+    else openFlyoutsRef.current.delete(key)
+  }, [])
+
+  const hasOpenFlyout = React.useCallback(
+    () => openFlyoutsRef.current.size > 0,
+    []
+  )
+
+  // Shallow-stabilized like `labels`: an inline array republished the context.
+  const stableActions = useShallowStable(actions, shallowEqualItemLists)
+
+  const resolvedActions = React.useMemo<CascaderActionItem[]>(
+    () => stableActions ?? EMPTY_ACTIONS,
+    [stableActions]
+  )
+
+  // A Set, not an `includes` scan: `isSelected` runs once per rendered row.
+  const selectedSet = React.useMemo(
+    () => new Set(selectedValues),
+    [selectedValues]
+  )
+
+  const isSelected = React.useCallback(
+    (node: CascaderNode<T>) => selectedSet.has(node.value),
+    [selectedSet]
+  )
+
+  /** Selected-descendant counts, walked ONCE per selection change and never
+   * stored, so the flat value array stays the only source of truth. The walk
+   * is `selections x depth`, up from each selection rather than down from each
+   * row, which keeps the count and `isIndeterminate` O(1). */
+  const selectedDescendants = React.useMemo(
+    () => getCascaderSelectedDescendants(index, selectedValues),
+    [index, selectedValues]
+  )
+
+  const selectedDescendantCount = React.useCallback(
+    (node: CascaderNode<T>) => selectedDescendants.get(node.value) ?? 0,
+    [selectedDescendants]
+  )
+
+  // Partial selections read off the SAME map, so the dash and the number are
+  // two readings of one traversal and cannot drift apart.
+  const indeterminateSet = React.useMemo(() => {
+    if (!cascade || !multiple) return null
+    return getCascaderIndeterminateFrom(selectedDescendants, selectedValues)
+  }, [cascade, multiple, selectedDescendants, selectedValues])
+
+  const isIndeterminate = React.useCallback(
+    (node: CascaderNode<T>) => indeterminateSet?.has(node.value) ?? false,
+    [indeterminateSet]
+  )
+
+  // Base UI owns the highlight; mirrored so handlers can read it unsubscribed.
+  const highlightedRef = React.useRef<CascaderNode<T> | null>(null)
+  const getHighlighted = React.useCallback(() => highlightedRef.current, [])
+
+  // The same highlight as an external store, for the consumer that must
+  // RE-RENDER on it. `useState`, not `useMemo`: React may drop a memo, and a
+  // second store would silently orphan every subscriber.
+  const [highlightStore] = React.useState<CascaderHighlightStore>(
+    createCascaderHighlightStore
+  )
+
+  /* ------------------------------ announcement ---------------------------- */
+
+  const currentLoadState = React.useMemo<CascaderLoadState | null>(
+    () => loadStates.get(currentLevelKey) ?? null,
+    [loadStates, currentLevelKey]
+  )
+  const searchLoadState = loader.searchState
+
+  /** What the query announcement COUNTS: matches, not rows, since the list
+   * also carries a tree query's ancestor context and the Load-more row. Server
+   * hits count as-is; re-judging them locally would drop what it matched on
+   * data the client cannot see. */
+  const announcedMatches = React.useMemo(() => {
+    if (deepResults) return deepResults.length
+    const normalized = normalizeCascaderQuery(query)
+    if (!normalized) return 0
+    const matches = filter ?? matchesCascaderQuery
+    return renderedItems.filter(
+      (node) => !isCascaderMoreNode(node) && matches(node, normalized)
+    ).length
+  }, [deepResults, renderedItems, query, filter])
+
+  // Real rows only: a tree's first load renders its loading row, and counting
+  // that one called the first fetch "Loading more".
+  const hasRows = renderedItems.some((node) => !isCascaderMoreNode(node))
+
+  // The live-region text plus whether it may be DEFERRED; see
+  // `ANNOUNCE_DEBOUNCE`. The committed string is state, set below.
+  const announcementTarget = React.useMemo(() => {
+    // An INLINE cascader is never "open", so `open` alone silenced its tree.
+    if (!open && !inline) return { text: "", defer: false }
+
+    const total = renderedItems.length
+    const marker = ANNOUNCE_MARKER.repeat(announceSignal.seq % 2)
+
+    // A notice outranks everything below: it exists because nothing else on
+    // screen changed. It rides the signal, so the next navigation replaces it.
+    if (announceSignal.notice) {
+      return { text: `${announceSignal.notice}${marker}`, defer: false }
+    }
+
+    // A tree toggle changes neither level nor query, so it rides the signal.
+    const toggled =
+      mode === "tree" && announceSignal.toggled
+        ? (index.byValue.get(announceSignal.toggled) ?? null)
+        : null
+
+    // Async states outrank everything below, or a fetching level announces "0
+    // results" and contradicts itself. A HELD navigation outranks even those:
+    // nothing on screen has moved yet, so "loading" is the only truth.
+    const pendingState = pendingNavigation
+      ? (loadStates.get(pendingNavigation.value) ?? null)
+      : null
+    const levelState = query.trim() ? searchLoadState : currentLoadState
+    let text: string
+    let defer = false
+    if (pendingState?.error) {
+      text = labels.error
+    } else if (pendingNavigation) {
+      // Always the FIRST-page string: the rows on screen belong to the level
+      // being left behind, so their count says nothing about this request.
+      text = labels.loading
+    } else if (levelState?.error) {
+      text = labels.error
+    } else if (levelState?.loading) {
+      // With a query set the in-flight load IS the server search, and calling
+      // that "Loading more" misreads what is being waited on.
+      text = query.trim()
+        ? labels.searchingAnnouncement
+        : hasRows
+          ? labels.loadingMore
+          : labels.loading
+    } else if (query.trim()) {
+      // An empty result set is the more useful thing to say than "0 results".
+      text =
+        announcedMatches === 0
+          ? labels.empty
+          : labels.resultsAnnouncement(announcedMatches)
+      // The ONE deferred branch: only a stream of keystrokes needs coalescing.
+      defer = true
+    } else if (toggled) {
+      text = expanded.has(toggled.value)
+        ? labels.expandedAnnouncement(
+            toggled.label,
+            getCascaderCount(index, toggled)
+          )
+        : labels.collapsedAnnouncement(toggled.label)
+    } else if (currentParent) {
+      // `path.length + 1` matches tree mode's `aria-level`: the rows are
+      // `currentParent`'s CHILDREN, one level below it.
+      text = labels.levelAnnouncement(
+        currentParent.label,
+        path.length + 1,
+        total
+      )
+    } else {
+      // Returning to the root would otherwise announce nothing at all.
+      text = labels.rootAnnouncement(total)
+    }
+
+    return { text: `${text}${marker}`, defer }
+  }, [
+    open,
+    inline,
+    mode,
+    index,
+    expanded,
+    announceSignal,
+    query,
+    labels,
+    renderedItems.length,
+    hasRows,
+    announcedMatches,
+    currentParent,
+    path.length,
+    currentLoadState,
+    searchLoadState,
+    pendingNavigation,
+    loadStates,
+  ])
+
+  /** The COMMITTED announcement. Immediate texts commit during render (the
+   * pattern `swap` uses), so an async settle announces in the very commit that
+   * shows the rows. Only the deferred query count uses the timer below. */
+  const [announced, setAnnounced] = React.useState(announcementTarget)
+
+  if (!announcementTarget.defer && announced.text !== announcementTarget.text) {
+    // Terminates: after the set the condition is false on the re-render.
+    setAnnounced(announcementTarget)
+  }
+
+  React.useEffect(() => {
+    if (!announcementTarget.defer) return undefined
+    const timer = setTimeout(
+      () => setAnnounced(announcementTarget),
+      ANNOUNCE_DEBOUNCE
+    )
+    return () => clearTimeout(timer)
+  }, [announcementTarget])
+
+  const announcement = announced.text
+
+  /* --------------------------------- state -------------------------------- */
+
+  // The volatile half: rebuilt by a keystroke, hence split from the actions.
+  const stateValue = React.useMemo<CascaderStateContextValue<T>>(
+    () => ({
+      index,
+      path,
+      expanded,
+      query,
+      currentParent,
+      levelItems,
+      deepResults,
+      renderedItems,
+      columns,
+      treeRows,
+      selectedValues,
+      selectedDescendants,
+      loadStates,
+      searchState: searchLoadState,
+      announcement,
+    }),
+    [
+      index,
+      path,
+      expanded,
+      query,
+      currentParent,
+      levelItems,
+      deepResults,
+      renderedItems,
+      columns,
+      treeRows,
+      selectedValues,
+      selectedDescendants,
+      loadStates,
+      searchLoadState,
+      announcement,
+    ]
+  )
+
+  /* ------------------------------ latest props ---------------------------- */
+
+  /**
+   * Latest committed props and derived state, WRITTEN IN AN EFFECT. That is
+   * what keeps the callbacks below `[]`-dep and stable for the life of the
+   * cascader; writing during render is unsafe under concurrent rendering. The
+   * cost: a read sees the PREVIOUS commit until the effect runs, so ONLY event
+   * handlers may read it. Anything used during render is memoised instead.
+   */
+  const latest = React.useRef<CascaderLatest<T>>({
+    index,
+    state: stateValue,
+    mode,
+    multiple,
+    cascade,
+    max,
+    labels,
+    closeOnSelect,
+    selectedValues,
+    deepResults,
+    onValueChange,
+    resolveNode,
+    isSelectable,
+    needsChildren,
+    expanded,
+  })
+
+  React.useEffect(() => {
+    latest.current = {
+      index,
+      state: stateValue,
+      mode,
+      multiple,
+      cascade,
+      max,
+      labels,
+      closeOnSelect,
+      selectedValues,
+      deepResults,
+      onValueChange,
+      resolveNode,
+      isSelectable,
+      needsChildren,
+      expanded,
+    }
+  })
+
+  const getIndex = React.useCallback(() => latest.current.index, [])
+  const getState = React.useCallback(() => latest.current.state, [])
+
+  const goToLevelAt = React.useCallback(
+    (nodeValue: string, depth: number) => {
+      setPathWithReason(
+        (prev) => [...prev.slice(0, Math.max(0, depth)), nodeValue],
+        "drill"
+      )
+      setQuery("")
+      bumpAnnouncement(null)
+    },
+    [setPathWithReason, setQuery, bumpAnnouncement]
+  )
+
+  const goToTrail = React.useCallback(
+    (trail: string[]) => {
+      // A global hit can BE the level on screen. Then nothing moved, so no path
+      // change is reported, and no level swap clears the highlight the hit
+      // list left at its index, where Enter would commit some other row.
+      const { path: current } = latest.current.state
+      const stays =
+        trail.length === current.length &&
+        trail.every((entry, i) => entry === current[i])
+      if (stays) resetHighlight()
+      else setPathWithReason(trail, "drill")
+      setQuery("")
+      bumpAnnouncement(null)
+    },
+    [setPathWithReason, resetHighlight, setQuery, bumpAnnouncement]
+  )
+
+  const navigateAt = React.useCallback(
+    (node: CascaderNode<T>, depth: number) => {
+      if (isCascaderDisabled(latest.current.index, node)) return
+      if (latest.current.mode === "tree") {
+        toggleExpanded(node.value)
+        return
+      }
+      if (latest.current.needsChildren(node)) {
+        requestChildren(node, { value: node.value, kind: "at", depth })
+        return
+      }
+      goToLevelAt(node.value, depth)
+    },
+    [toggleExpanded, goToLevelAt, requestChildren]
+  )
+
+  const navigate = React.useCallback(
+    (node: CascaderNode<T>) => {
+      const {
+        mode: currentMode,
+        deepResults: currentDeepResults,
+        index: currentIndex,
+        expanded: currentExpanded,
+        needsChildren: pending,
+      } = latest.current
+
+      // Every drill and expand passes here, from a search hit, a key or a hover
+      // timer alike, so this is where a disabled subtree stays shut.
+      if (isCascaderDisabled(currentIndex, node)) return
+
+      if (currentMode === "tree") {
+        // Collapsing never needs data. Opening waits WITHOUT expanding, so
+        // the branch stays shut with a spinner rather than opening onto no rows.
+        if (!currentExpanded.has(node.value) && pending(node)) {
+          requestChildren(node, {
+            value: node.value,
+            kind: "expand",
+            depth: 0,
+          })
+          return
+        }
+        toggleExpanded(node.value)
+        return
+      }
+
+      // A search hit sits at any depth, and under a global search outside the
+      // current path, so drilling in swaps in the hit's own trail. A held drill
+      // carries it too: splicing the hit into the current path at its depth
+      // kept the wrong ancestors for anything below a direct child.
+      if (currentDeepResults) {
+        const trail = getCascaderPath(currentIndex, node.value).map(
+          (entry) => entry.value
+        )
+        if (pending(node)) {
+          requestChildren(node, { value: node.value, kind: "trail", trail })
+          return
+        }
+        goToTrail(trail)
+        return
+      }
+
+      if (pending(node)) {
+        requestChildren(node, { value: node.value, kind: "push", depth: 0 })
+        return
+      }
+      pushLevel(node.value)
+    },
+    [toggleExpanded, goToTrail, pushLevel, requestChildren]
+  )
+
+  /**
+   * The other half of `requestChildren`: the fetch settled, so the held
+   * navigation happens or is dropped. Reads the load STATE, not a promise:
+   * only the loader knows a request was superseded, aborted or retried, and no
+   * entry at all means it has not reached the store yet. On failure nothing
+   * moves and the intent is KEPT, which is what makes the row's retry
+   * affordance mean something; only `popLevel`, `goToDepth` and a close drop it.
+   */
+  React.useEffect(() => {
+    if (!pendingNavigation) return
+    const state = loadStates.get(pendingNavigation.value)
+    if (!state || state.loading || state.error) return
+
+    setPendingNavigation(null)
+
+    // Asked again against the index as it is NOW: a new `items` or a landed
+    // page can disable the target while its fetch was in flight.
+    const target = index.byValue.get(pendingNavigation.value)
+    if (target && isDisabled(target)) return
+
+    if (pendingNavigation.kind === "expand") {
+      toggleExpanded(pendingNavigation.value)
+      return
+    }
+    if (pendingNavigation.kind === "trail") {
+      goToTrail(pendingNavigation.trail)
+      return
+    }
+    if (pendingNavigation.kind === "at") {
+      goToLevelAt(pendingNavigation.value, pendingNavigation.depth)
+      return
+    }
+    pushLevel(pendingNavigation.value)
+  }, [
+    pendingNavigation,
+    loadStates,
+    index,
+    isDisabled,
+    toggleExpanded,
+    goToTrail,
+    goToLevelAt,
+    pushLevel,
+  ])
+
+  // A popup that closes mid-flight must not drill in when the answer arrives;
+  // the loader aborts the request, this drops the intent.
+  React.useEffect(() => {
+    if (!open && !inline) setPendingNavigation(null)
+  }, [open, inline])
+
+  /* ------------------------------- selection ------------------------------ */
+
+  // The one place the selection changes, so `onValueChange` reports the same
+  // shape whatever caused it: a row press, drag-select, or the headless hooks.
+  const emitSelection = React.useCallback(
+    (
+      nextValues: string[],
+      node: CascaderNode<T> | null,
+      reason: CascaderChangeReason
+    ) => {
+      const {
+        selectedValues: current,
+        multiple: currentMultiple,
+        onValueChange: emit,
+        index: currentIndex,
+        resolveNode: resolve,
+      } = latest.current
+
+      // Nothing changed. The dedup lives here now, not in `useControllable`.
+      const unchanged =
+        nextValues.length === current.length &&
+        nextValues.every((entry, i) => entry === current[i])
+      if (unchanged) return
+
+      const next = currentMultiple ? nextValues : (nextValues[0] ?? "")
+      setValue(next)
+
+      if (!emit) return
+
+      const chain = node ? getCascaderPath(currentIndex, node.value) : []
+      emit(next, {
+        node,
+        // A node absent from `items` has no chain, so fall back to the node
+        // rather than report an empty path for a change that had one.
+        path: node ? (chain.length ? chain : [node]) : [],
+        // `resolveNode`, not `index.byValue`: a selected value missing from
+        // `items` must still come back rather than be dropped.
+        nodes: nextValues.map(resolve),
+        reason,
+      })
+    },
+    [setValue]
+  )
+
+  const setSelection = React.useCallback(
+    (values: string[], reason?: CascaderChangeReason) => {
+      const { selectedValues: current, resolveNode: resolve } = latest.current
+      const before = new Set(current)
+      const after = new Set(values)
+      const added = values.find((entry) => !before.has(entry))
+      const removed = current.find((entry) => !after.has(entry))
+
+      if (reason === "clear") {
+        emitSelection(values, null, "clear")
+        return
+      }
+      if (added) {
+        emitSelection(values, resolve(added), reason ?? "select")
+        return
+      }
+      if (removed) {
+        emitSelection(values, resolve(removed), reason ?? "deselect")
+        return
+      }
+      // Same set: a no-op, but routed so an explicit `reason` still applies.
+      emitSelection(values, null, reason ?? "select")
+    },
+    [emitSelection]
+  )
+
+  const commit = React.useCallback(
+    (node: CascaderNode<T>) => {
+      const {
+        multiple: currentMultiple,
+        cascade: currentCascade,
+        selectedValues: current,
+        max: currentMax,
+        index: currentIndex,
+        isSelectable: currentIsSelectable,
+        labels: currentLabels,
+        closeOnSelect: currentCloseOnSelect,
+      } = latest.current
+
+      // Refuses a SELECT, never a removal: a disabled value set from outside
+      // must stay removable, and a cascade chip's removal arrives here.
+      const selecting = !currentMultiple || !current.includes(node.value)
+      if (selecting && isCascaderDisabled(currentIndex, node)) return
+
+      if (!currentMultiple) {
+        emitSelection([node.value], node, "select")
+        if (currentCloseOnSelect) {
+          openReasonRef.current = "item-press"
+          setOpen(false)
+        } else {
+          // The popup stays up, so clear the query the way a multiple commit
+          // does; the next pick then starts from the full level.
+          setQuery("")
+        }
+        return
+      }
+
+      if (currentCascade) {
+        const next = applyCascadeSelection(
+          currentIndex,
+          current,
+          node.value,
+          selecting,
+          currentIsSelectable
+        )
+        // `max` caps the whole gesture rather than truncating it: an arbitrary
+        // prefix of a subtree is a selection nobody asked for. The refusal
+        // changes nothing on screen, so the live region is its only witness.
+        if (
+          selecting &&
+          currentMax != null &&
+          next.length > currentMax &&
+          next.length > current.length
+        ) {
+          announceNotice(currentLabels.maxReachedAnnouncement(currentMax))
+          return
+        }
+        emitSelection(next, node, selecting ? "select" : "deselect")
+        // How many values the closure swept along is invisible from the one
+        // row pressed, so the sweep says its number out loud, itself excluded.
+        const before = new Set(current)
+        const after = new Set(next)
+        let swept = 0
+        for (const entry of selecting ? next : current) {
+          if (entry === node.value) continue
+          if (selecting ? !before.has(entry) : !after.has(entry)) swept += 1
+        }
+        if (swept > 0) {
+          announceNotice(
+            currentLabels.cascadeAnnouncement(
+              node.label ?? node.value,
+              swept,
+              selecting
+            )
+          )
+        }
+        setQuery("")
+        return
+      }
+
+      if (current.includes(node.value)) {
+        emitSelection(
+          current.filter((v) => v !== node.value),
+          node,
+          "deselect"
+        )
+      } else if (currentMax == null || current.length < currentMax) {
+        emitSelection([...current, node.value], node, "select")
+      } else {
+        // The plain-multiple twin of the cascade refusal above: just as silent.
+        announceNotice(currentLabels.maxReachedAnnouncement(currentMax))
+      }
+      setQuery("")
+    },
+    [emitSelection, setOpen, setQuery, announceNotice]
+  )
+
+  /** Safety net for paths that bypass the row-level veto (the drag-select
+   * mouseup). `details.cancel()` suppresses the commit and the close together:
+   * Base UI shares one event-details object between them. */
+  const handleComboboxValueChange = React.useCallback(
+    (
+      next: CascaderNode<T> | CascaderNode<T>[] | null,
+      details: ComboboxPrimitive.Root.ChangeEventDetails
+    ) => {
+      if (!multiple) {
+        const node = Array.isArray(next) ? (next[0] ?? null) : next
+        // The paging row is a real option, so Base UI reports it as a
+        // selection. Same safety net branches get, for paths a row cannot veto.
+        if (node && isCascaderMoreNode(node)) {
+          details.cancel()
+          return
+        }
+        // The row is Base UI `disabled` already, so only a path around it gets
+        // here, a custom row re-enabling it for one: refused, never navigated.
+        if (node && isDisabled(node)) {
+          details.cancel()
+          return
+        }
+        if (node && !isSelectable(node) && isBranch(node)) {
+          details.cancel()
+          navigate(node)
+          return
+        }
+        if (node) {
+          // `closeOnSelect={false}` must also stop Base UI's OWN close; one
+          // shared details object, so cancelling suppresses both, and our value
+          // is controlled, so Base UI's half had nothing to keep.
+          if (!closeOnSelect) details.cancel()
+          commit(node)
+        }
+        return
+      }
+
+      // Take Base UI's whole array as the answer and inspect only what was
+      // ADDED. Deriving the toggle from the tail works for an add but on a
+      // remove drops the wrong node, leaving the last selection unclearable.
+      const nextNodes = Array.isArray(next) ? next : []
+      const before = new Set(selectedValues)
+      const added = nextNodes.find((node) => !before.has(node.value))
+
+      if (added && (isCascaderMoreNode(added) || isDisabled(added))) {
+        details.cancel()
+        return
+      }
+
+      if (added && !isSelectable(added) && isBranch(added)) {
+        details.cancel()
+        navigate(added)
+        return
+      }
+
+      // Cascading reads Base UI's array only as the REPORT of which row was
+      // pressed: it differs by exactly one value either way, and the real
+      // commit covers a whole subtree.
+      if (cascade) {
+        const nextValues = new Set(nextNodes.map((node) => node.value))
+        const removed = selectedValues.find((entry) => !nextValues.has(entry))
+        const toggled = added ?? (removed != null ? resolveNode(removed) : null)
+        if (toggled) commit(toggled)
+        return
+      }
+
+      if (
+        max != null &&
+        nextNodes.length > selectedValues.length &&
+        nextNodes.length > max
+      ) {
+        details.cancel()
+        // The third silent refusal site: cancelling reverts the press with no
+        // state change, so the live region is the only witness.
+        announceNotice(labels.maxReachedAnnouncement(max))
+        return
+      }
+
+      setSelection(nextNodes.map((node) => node.value))
+      setQuery("")
+    },
+    [
+      multiple,
+      selectedValues,
+      max,
+      cascade,
+      closeOnSelect,
+      labels,
+      announceNotice,
+      isSelectable,
+      isDisabled,
+      isBranch,
+      navigate,
+      commit,
+      resolveNode,
+      setSelection,
+      setQuery,
+    ]
+  )
+
+  const handleOpenChange = React.useCallback(
+    (nextOpen: boolean, details: ComboboxPrimitive.Root.ChangeEventDetails) => {
+      if (details.isCanceled) return
+
+      // Escape closes ONE popup at a time. `Combobox` builds no `FloatingTree`,
+      // so one Escape reaches the flyout and the cascader; the flyout clears
+      // its registration in an effect, so the set holds for exactly this event.
+      if (!nextOpen && details.reason === "escape-key" && hasOpenFlyout()) {
+        details.cancel()
+        return
+      }
+
+      // Captured for the wrapped `onOpenChange`, which runs synchronously
+      // inside `setOpen`, so a ref written just before the call is exact.
+      openReasonRef.current = details.reason ?? "none"
+      setOpen(nextOpen)
+
+      if (!nextOpen) {
+        setQuery("")
+        return
+      }
+
+      // Opening onto the level holding the selection is the difference
+      // between "edit this" and "start over". Not in a tree, where `path`
+      // does nothing and the live region announced a level nobody could see.
+      if (revealSelected) {
+        setQuery("")
+        const first = toArray(value)[0]
+        if (mode !== "tree") {
+          setPathWithReason(
+            first
+              ? getCascaderPath(index, first)
+                  .slice(0, -1)
+                  .map((node) => node.value)
+              : [],
+            "reveal"
+          )
+        }
+      }
+    },
+    [
+      setOpen,
+      setQuery,
+      revealSelected,
+      value,
+      index,
+      mode,
+      setPathWithReason,
+      hasOpenFlyout,
+    ]
+  )
+
+  /* -------------------------------- context ------------------------------- */
+
+  // NOT memoised further: render props must be the current closure, and only
+  // rows consume this. See `CascaderRenderContextValue`.
+  const renderContext = React.useMemo(
+    () => ({ renderItem, renderLabel }),
+    [renderItem, renderLabel]
+  )
+
+  /** The stable half: nothing in these deps moves on a keystroke, a level
+   * change or a highlight, which is what makes `React.memo` on `CascaderItem`
+   * hold while the user types. Destructured off `loader` so the memo depends
+   * on its `[]`-dep callbacks, not the object it republishes per load. */
+  const {
+    active: hasLoader,
+    loadMore,
+    retryLevel,
+    retrySearch,
+    prefetchNode,
+  } = loader
+
+  const actionsValue = React.useMemo<CascaderActionsContextValue<T>>(
+    () => ({
+      index,
+      mode,
+      multiple,
+      cascade,
+      branchesSelectable,
+      indicator,
+      expandTrigger,
+      actions: resolvedActions,
+      searchScope,
+      maxHeight,
+      inline: !!inline,
+      invalid: !!invalid,
+      baseId,
+      labels,
+      virtualized,
+      registerVirtualRenderer,
+      virtualize,
+      virtualizeThreshold,
+      estimateRowSize,
+      overscan,
+      hasLoader,
+      loadMore,
+      retryLevel,
+      retrySearch,
+      invalidateLevel,
+      getIndex,
+      getState,
+      getHighlighted,
+      setPath,
+      pushLevel,
+      popLevel,
+      goToDepth,
+      toggleExpanded,
+      setFlyoutOpen,
+      hasOpenFlyout,
+      setQuery,
+      setSelection,
+      commit,
+      navigate,
+      navigateAt,
+      resolveNode,
+      isBranch,
+      isSelectable,
+      isDisabled,
+      isSelected,
+      isIndeterminate,
+      selectedDescendantCount,
+    }),
+    [
+      index,
+      mode,
+      multiple,
+      cascade,
+      branchesSelectable,
+      indicator,
+      expandTrigger,
+      resolvedActions,
+      searchScope,
+      maxHeight,
+      inline,
+      invalid,
+      baseId,
+      labels,
+      virtualized,
+      registerVirtualRenderer,
+      virtualize,
+      virtualizeThreshold,
+      estimateRowSize,
+      overscan,
+      hasLoader,
+      loadMore,
+      retryLevel,
+      retrySearch,
+      invalidateLevel,
+      getIndex,
+      getState,
+      getHighlighted,
+      setPath,
+      pushLevel,
+      popLevel,
+      goToDepth,
+      toggleExpanded,
+      setFlyoutOpen,
+      hasOpenFlyout,
+      setQuery,
+      setSelection,
+      commit,
+      navigate,
+      navigateAt,
+      resolveNode,
+      isBranch,
+      isSelectable,
+      isDisabled,
+      isSelected,
+      isIndeterminate,
+      selectedDescendantCount,
+    ]
+  )
+
+  // A fresh array identity each time windowing turns on, and once more after:
+  // that identity is the ONLY thing that re-runs Base UI's `listRef` sizing
+  // effect. See `virtualSyncs`.
+  const comboboxItems = React.useMemo(
+    () => (virtualized ? renderedItems.slice() : renderedItems),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [renderedItems, virtualized, virtualSyncs]
+  )
+
+  const comboboxValue = React.useMemo(() => {
+    if (multiple) return selectedValues.map(resolveNode)
+    return selectedValues.length ? resolveNode(selectedValues[0]) : null
+  }, [multiple, selectedValues, resolveNode])
+
+  return (
+    // Providers store values with the item generic erased; the hooks re-apply
+    // the caller's own `T` on the way back out.
+    <CascaderActionsContext.Provider
+      value={actionsValue as unknown as CascaderActionsContextValue}
+    >
+      <CascaderStateContext.Provider
+        value={stateValue as unknown as CascaderStateContextValue}
+      >
+        <CascaderHighlightContext.Provider value={highlightStore}>
+          <CascaderRenderContext.Provider
+            value={renderContext as unknown as CascaderRenderContextValue}
+          >
+            <ComboboxPrimitive.Root
+              items={renderedItems}
+              /* The empty frame that resets the highlight. See the comment above. */
+              filteredItems={swapping ? EMPTY : comboboxItems}
+              /* Filtering is ours: the level, deep and global scopes cannot
+                 be expressed through Base UI's single matcher. */
+              filter={null}
+              value={comboboxValue}
+              onValueChange={handleComboboxValueChange}
+              open={open}
+              onOpenChange={handleOpenChange}
+              inputValue={query}
+              onInputValueChange={(next: string) => setQuery(next)}
+              multiple={multiple}
+              disabled={disabled}
+              /* Form wiring, straight to Base UI's hidden input. Conditional
+                 spreads: an explicit `undefined` on a controlled prop reads as
+                 "deleted" rather than "not supplied". */
+              name={name}
+              {...(form != null ? { form } : null)}
+              {...(id != null ? { id } : null)}
+              {...(required != null ? { required } : null)}
+              {...(readOnly != null ? { readOnly } : null)}
+              {...(inputRef ? { inputRef } : null)}
+              inline={inline}
+              /* Stops Base UI rendering its composite list, which is what makes
+                 an explicit row `index` legal. `items`/`filteredItems` stay full:
+                 they size `listRef`, or ArrowDown stops at the last RENDERED row. */
+              virtualized={virtualized}
+              itemToStringValue={(item: CascaderNode<T>) => item?.value ?? ""}
+              itemToStringLabel={(item: CascaderNode<T>) => item?.label ?? ""}
+              isItemEqualToValue={(a: CascaderNode<T>, b: CascaderNode<T>) =>
+                a?.value === b?.value
+              }
+              // Fires on every arrow key AND every pointer move, so it must
+              // never call setState. The ref serves keyboard handlers, the
+              // de-duping store anything that has to re-render.
+              onItemHighlighted={(
+                item: CascaderNode<T> | undefined,
+                details: ComboboxPrimitive.Root.HighlightEventDetails
+              ) => {
+                highlightedRef.current = item ?? null
+                highlightStore.set({
+                  index: details.index,
+                  value: item?.value ?? null,
+                })
+                // Schedules a TIMEOUT and returns: inside a layout effect, a
+                // synchronous setState would cascade before paint.
+                prefetchNode(item)
+              }}
+            >
+              {children}
+            </ComboboxPrimitive.Root>
+          </CascaderRenderContext.Provider>
+        </CascaderHighlightContext.Provider>
+      </CascaderStateContext.Provider>
+    </CascaderActionsContext.Provider>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Trigger                                  */
+/* -------------------------------------------------------------------------- */
+
+/** `Trigger.Props` stops short of `ref`, so it is intersected in, as the
+ * shadcn combobox wrapper also does: a form library needs a ref here, and
+ * `onBlur`, the "touched" signal, lands here too. */
+export interface CascaderTriggerProps
+  extends
+    ComboboxPrimitive.Trigger.Props,
+    Pick<React.ComponentPropsWithRef<"button">, "ref"> {
+  /** Hides the trailing chevron, for a trigger that supplies its own. */
+  showIcon?: boolean
+}
+
+function CascaderTrigger({
+  className,
+  children,
+  showIcon = true,
+  ref,
+  ...props
+}: CascaderTriggerProps) {
+  const { invalid } = useCascaderActions()
+
+  // `ref` is the one prop `mergeProps` does not merge, so chain it by hand.
+  const triggerRef = React.useRef<HTMLButtonElement | null>(null)
+  const setTrigger = React.useCallback(
+    (node: HTMLButtonElement | null) => {
+      triggerRef.current = node
+      if (typeof ref === "function") ref(node)
+      else if (ref) ref.current = node
+    },
+    [ref]
+  )
+
+  /** 18 of 19 audited examples shipped an unnamed combobox: the trigger's
+   * contents are the field's VALUE, so a screen reader never hears its NAME.
+   * Checked in the DOM, since the name may arrive as a `<label for>`. */
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production") return
+    const element = triggerRef.current
+    if (!element) return
+    const named =
+      element.hasAttribute("aria-label") ||
+      element.hasAttribute("aria-labelledby") ||
+      element.closest("label") !== null ||
+      (element.id !== "" &&
+        element.ownerDocument.querySelector(
+          `label[for="${CSS.escape(element.id)}"]`
+        ) !== null)
+    if (named) return
+    warnCascaderOnce(
+      "trigger-unnamed",
+      "`CascaderTrigger` has no accessible name. Its contents are the field's VALUE - they change with the selection - so a screen reader hears what is picked but never what the field is for. Pass `aria-label` or `aria-labelledby`, or reference the trigger's `id` from a `<label>`."
+    )
+  })
+
+  return (
+    <ComboboxPrimitive.Trigger
+      ref={setTrigger}
+      data-slot="cascader-trigger"
+      /* Conditional spread: an explicit `undefined` would DELETE whatever a
+         `Field` wrapper had already put here. */
+      {...(invalid ? { "aria-invalid": true, "data-invalid": "" } : null)}
+      className={cn(TRIGGER_ICON_FALLBACK_CLASS, className)}
+      {...props}
+    >
+      {children}
+      {showIcon ? (
+        <ChevronDownIcon className={`${TRIGGER_ICON_CLASS} pointer-events-none shrink-0`} />
+      ) : null}
+    </ComboboxPrimitive.Trigger>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Resolved theme                                */
+/* -------------------------------------------------------------------------- */
+
+/* The eight registry styles each state a combobox surface differently, so the
+ * classes below spell every one out with `style-<name>:` variants. Nothing
+ * depends on ReUI's theme CSS; `build-registry` flattens one in on install. */
+
+/** Icon size for a combobox surface: 14px in mira and sera, 16px elsewhere. */
+const TRIGGER_ICON_CLASS =
+  "text-muted-foreground size-4"
+
+/** The same ladder, applied only to trigger children that carry no size. */
+const TRIGGER_ICON_FALLBACK_CLASS =
+  "[&_svg:not([class*='size-'])]:size-4"
+
+/** The chips field: a form-control surface, so it carries the invalid states. */
+const CHIPS_CLASS =
+  "flex flex-wrap items-center border bg-clip-padding dark:bg-input/30 border-input focus-within:border-ring focus-within:ring-ring/50 has-aria-invalid:ring-destructive/20 dark:has-aria-invalid:ring-destructive/40 has-aria-invalid:border-destructive dark:has-aria-invalid:border-destructive/50 bg-transparent px-2.5 text-sm focus-within:ring-3 has-aria-invalid:ring-3 min-h-8 gap-1 rounded-lg py-1 transition-colors has-data-[slot=combobox-chip]:px-1"
+
+const CHIP_CLASS =
+  "text-foreground flex w-fit items-center justify-center gap-1 font-medium whitespace-nowrap bg-muted rounded-sm px-1.5 text-xs has-data-[slot=combobox-chip-remove]:pr-0 h-[calc(--spacing(5.25))]"
+
+const CHIP_REMOVE_CLASS =
+  "opacity-50 hover:opacity-100 -ml-1"
+
+/** The floating panel's surface. The shared popup's `InputGroup` sizing is
+ * left out (mirrored in `cascader-nav.tsx`), as are its `max-h-72` and
+ * `min-w-*`: `CascaderContent` sets both from the positioner's variables. */
+const CONTENT_SURFACE_CLASS =
+  "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 overflow-hidden ring-1 duration-100 ring-foreground/10 shadow-md rounded-lg data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2"
+
+const EMPTY_CLASS =
+  "text-muted-foreground hidden w-full justify-center py-2 text-center group-data-empty/combobox-content:flex text-sm"
+
+/* -------------------------------------------------------------------------- */
+/*                                    Chips                                   */
+/* -------------------------------------------------------------------------- */
+
+/** Ref for the chips container: they replace the trigger, so the popup has to
+ * be anchored to them. Hand it to `CascaderContent`'s `anchor`. */
+export function useCascaderAnchor() {
+  return React.useRef<HTMLDivElement | null>(null)
+}
+
+export interface CascaderChipsProps
+  extends
+    Omit<ComboboxPrimitive.Chips.Props, "children">,
+    Pick<React.ComponentPropsWithRef<"div">, "ref"> {
+  /** Shown in place of the chips when nothing is selected. */
+  placeholder?: React.ReactNode
+  /**
+   * How a `cascade` selection is condensed into chips. DISPLAY ONLY: the
+   * stored value stays the full closure, which keeps a row's checked state an
+   * O(1) lookup. `"all"` (default) is one chip per value, `"parent"` collapses
+   * a fully selected branch, `"child"` chips only the deepest frontier.
+   * Removing a condensed chip removes its whole closure and reconciles.
+   */
+  strategy?: CascaderCheckedStrategy
+  /** Replaces the chip list, receiving the resolved selection IN SELECTION
+   * ORDER. Keep that order: Base UI removes a chip by sibling position. */
+  children?: React.ReactNode | ((nodes: CascaderNode[]) => React.ReactNode)
+}
+
+/**
+ * The multi-select trigger surface: one removable chip per selection, where
+ * `CascaderValue` would collapse to "3 selected". A component rather than a
+ * recipe because of three easy misses: the popup anchored to the chips, an
+ * accessible name on every remove button, and labels that disambiguate when
+ * two branches use the same one.
+ *
+ * ```tsx
+ * const anchor = useCascaderAnchor()
+ * <Cascader multiple items={items}>
+ *   <CascaderChips ref={anchor} placeholder="Select attributes" />
+ *   <CascaderContent anchor={anchor}>...</CascaderContent>
+ * </Cascader>
+ * ```
+ */
+function CascaderChips({
+  className,
+  children,
+  placeholder,
+  strategy = "all",
+  ...props
+}: CascaderChipsProps) {
+  const {
+    labels,
+    multiple,
+    invalid,
+    resolveNode,
+    index,
+    isSelectable,
+    setSelection,
+  } = useCascaderActions()
+  const { selectedValues } = useCascaderState()
+
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production") return
+    if (multiple) return
+    warnCascaderOnce(
+      "chips-without-multiple",
+      "`CascaderChips` renders one chip per selection and there is only ever one without `multiple`. Use `CascaderValue` for a single-select trigger."
+    )
+  }, [multiple])
+
+  // DERIVED display: the selection stays the full closure, the chips condense.
+  const displayedValues =
+    strategy === "all"
+      ? selectedValues
+      : getCascaderCheckedValues(index, selectedValues, strategy)
+
+  // Not memoised: one entry per SELECTION, not per row, so the pass is short.
+  const nodes = displayedValues.map(resolveNode)
+  const ambiguous = findAmbiguousCascaderLabels(nodes)
+
+  // Removal for a CONDENSED chip: Base UI's `ChipRemove` maps a press onto the
+  // STORED array, which is wrong once the chips are fewer, so this removes the
+  // chip's whole subtree closure instead.
+  const removeClosure = (node: CascaderNode) => {
+    setSelection(
+      applyCascadeSelection(
+        index,
+        selectedValues,
+        node.value,
+        false,
+        isSelectable
+      ),
+      "deselect"
+    )
+  }
+
+  const content = typeof children === "function" ? children(nodes) : children
+
+  return (
+    <ComboboxPrimitive.Chips
+      data-slot="cascader-chips"
+      /* An unnamed `role="toolbar"` announces as just "toolbar". */
+      aria-label={labels.chipsLabel}
+      /* Conditional spread: the error treatment is keyed on
+         `has-aria-invalid:`, so the attribute must be absent, not empty. */
+      {...(invalid ? { "aria-invalid": true, "data-invalid": "" } : null)}
+      className={cn(CHIPS_CLASS, className)}
+      {...props}
+    >
+      {content ??
+        (nodes.length === 0 ? (
+          <span
+            data-slot="cascader-chips-placeholder"
+            className="text-muted-foreground truncate"
+          >
+            {placeholder}
+          </span>
+        ) : (
+          nodes.map((node) => (
+            <CascaderChip
+              key={node.value}
+              node={node}
+              showPath={ambiguous.has(node.value)}
+              /* Only a condensed chip needs the remover; the default shape
+                 keeps Base UI's positional removal. */
+              {...(strategy !== "all"
+                ? { onRemove: () => removeClosure(node) }
+                : null)}
+            />
+          ))
+        ))}
+    </ComboboxPrimitive.Chips>
+  )
+}
+
+export interface CascaderChipProps extends Omit<
+  ComboboxPrimitive.Chip.Props,
+  "children"
+> {
+  node: CascaderNode
+  /** Prefix the label with its ancestor trail. */
+  showPath?: boolean
+  /** Trail segments to show, the node itself included. */
+  maxSegments?: number
+  /** Hides the remove button, for a read-only chip. */
+  showRemove?: boolean
+  /** Replaces Base UI's positional removal for this chip (remove button and
+   * Backspace/Delete). Supplied for a `strategy`-condensed chip, whose
+   * position no longer maps onto the stored array. */
+  onRemove?: () => void
+  /** Replaces the chip's label. The remove button is still rendered. */
+  children?: React.ReactNode
+}
+
+/** Base UI hands its chip handlers events carrying the veto hook. */
+type CascaderChipKeyEvent = Parameters<
+  NonNullable<ComboboxPrimitive.Chip.Props["onKeyDown"]>
+>[0]
+
+type CascaderChipRemoveClickEvent = Parameters<
+  NonNullable<ComboboxPrimitive.ChipRemove.Props["onClick"]>
+>[0]
+
+/** One chip. Removal goes through Base UI's `ChipRemove`, which reports the
+ * shortened selection to the root, so it lands in the same `setSelection` as
+ * every other deselection and `cascade` applies to it. */
+function CascaderChip({
+  className,
+  node,
+  showPath = false,
+  maxSegments = 2,
+  showRemove = true,
+  onRemove,
+  children,
+  ...props
+}: CascaderChipProps) {
+  const { labels, index } = useCascaderActions()
+
+  const chain = showPath ? getCascaderPath(index, node.value) : []
+  const segments = collapseCascaderPath(chain, {
+    maxSegments,
+    collapse: "start",
+  })
+
+  const label = segments.length
+    ? segments
+        .map((segment) => (segment.type === "node" ? segment.node.label : "…"))
+        .join(` ${labels.pathSeparator} `)
+    : node.label
+
+  return (
+    <ComboboxPrimitive.Chip
+      data-slot="cascader-chip"
+      /* Keyboard half of `onRemove`: Base UI's chip removes ITSELF by position
+         on Backspace/Delete, the arithmetic a condensed chip must not use. The
+         veto runs first, so the closure removal replaces it. */
+      {...(onRemove
+        ? {
+            onKeyDown: (event: CascaderChipKeyEvent) => {
+              if (event.key !== "Backspace" && event.key !== "Delete") return
+              event.preventBaseUIHandler()
+              onRemove()
+            },
+          }
+        : null)}
+      className={cn(
+        CHIP_CLASS,
+        "has-disabled:pointer-events-none has-disabled:cursor-not-allowed has-disabled:opacity-50",
+        className
+      )}
+      {...props}
+    >
+      {children ?? <span className="truncate">{label}</span>}
+      {showRemove ? (
+        <ComboboxPrimitive.ChipRemove
+          data-slot="cascader-chip-remove"
+          /* Named after what the chip DISPLAYS, not the bare node label, or
+             two disambiguated chips both announce "Remove Created at". */
+          aria-label={labels.removeChip(label)}
+          /* The pointer half of `onRemove`, same veto, same reason. */
+          {...(onRemove
+            ? {
+                onClick: (event: CascaderChipRemoveClickEvent) => {
+                  event.preventBaseUIHandler()
+                  onRemove()
+                },
+              }
+            : null)}
+          className={CHIP_REMOVE_CLASS}
+        >
+          <XIcon className="pointer-events-none" />
+        </ComboboxPrimitive.ChipRemove>
+      ) : null}
+    </ComboboxPrimitive.Chip>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Content                                  */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderContentProps
+  extends
+    ComboboxPrimitive.Popup.Props,
+    /** Positioner surface forwarded as-is, so an unusual anchor does not force
+     * a rebuild of the content stack. No `trackAnchor`: Base UI 1.5.0 has
+     * none. */
+    Pick<
+      ComboboxPrimitive.Positioner.Props,
+      | "side"
+      | "align"
+      | "sideOffset"
+      | "alignOffset"
+      | "anchor"
+      | "collisionBoundary"
+      | "collisionPadding"
+      | "sticky"
+      | "positionMethod"
+    >,
+    /** Where the portal mounts, for a shadow root or a scoped stacking context. */
+    Pick<ComboboxPrimitive.Portal.Props, "container"> {}
+
+/** Portal + Positioner + floating panel. Unlike shadcn's `ComboboxContent` it
+ * does NOT clamp the popup to the anchor width (a cascader panel is routinely
+ * wider), but it keeps `group/combobox-content`, which `CascaderEmpty` needs. */
+function CascaderContent({
+  className,
+  side = "bottom",
+  sideOffset = 6,
+  align = "start",
+  alignOffset = 0,
+  anchor,
+  collisionBoundary,
+  collisionPadding,
+  sticky,
+  positionMethod,
+  container,
+  ref,
+  ...props
+}: CascaderContentProps) {
+  const { labels } = useCascaderActions()
+  const popupRef = React.useRef<HTMLDivElement | null>(null)
+
+  // `initialFocus` needs the popup element, and `ref` is the one prop
+  // `mergeProps` does NOT merge, so it is chained by hand rather than spread.
+  const setPopup = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      popupRef.current = node
+      if (typeof ref === "function") ref(node)
+      else if (ref) ref.current = node
+    },
+    [ref]
+  )
+
+  /**
+   * Focus goes to the search field, where the level keys and
+   * `aria-activedescendant` live. Base UI's own default agrees but is COMPUTED
+   * FROM THE FIRST RENDER, when the field has not mounted, and collapses to
+   * "do not move focus": measured, a KEYBOARD open left focus on the trigger
+   * and cost two Tabs to reach the footer where a pointer open cost one.
+   *
+   * `initialFocus` rather than an effect, because anything scheduled alongside
+   * Base UI's focus manager is a race; the field is resolved INSIDE the
+   * callback, which runs after the layout effects. Touch is handed back to
+   * Base UI on purpose - focusing the popup keeps the Android keyboard shut.
+   */
+  const initialFocus = React.useCallback((openType: string) => {
+    const popup = popupRef.current
+    if (!popup) return true
+    if (openType === "touch") return popup
+    return (
+      popup.querySelector<HTMLElement>('[data-slot="cascader-input"]') ?? true
+    )
+  }, [])
+
+  return (
+    // Conditional spreads throughout: `mergeProps` iterates own keys, so an
+    // explicit `undefined` reads as "deleted" rather than "not supplied".
+    <ComboboxPrimitive.Portal
+      {...(container !== undefined ? { container } : null)}
+    >
+      <ComboboxPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        anchor={anchor}
+        {...(collisionBoundary !== undefined ? { collisionBoundary } : null)}
+        {...(collisionPadding !== undefined ? { collisionPadding } : null)}
+        {...(sticky !== undefined ? { sticky } : null)}
+        {...(positionMethod !== undefined ? { positionMethod } : null)}
+        className="isolate z-50"
+      >
+        <ComboboxPrimitive.Popup
+          ref={setPopup}
+          data-slot="cascader-content"
+          /* Marks a menu surface for the docs design-system picker. An
+             attribute, not a class, so the panel's look stays self-contained. */
+          data-menu-target=""
+          /* The input inside makes this a `role="dialog"`, unnamed by default. */
+          aria-label={labels.panelLabel}
+          initialFocus={initialFocus}
+          className={cn(
+            CONTENT_SURFACE_CLASS,
+            "group/combobox-content relative flex max-h-(--available-height) max-w-(--available-width) min-w-(--anchor-width) origin-(--transform-origin) flex-col",
+            className
+          )}
+          {...props}
+        />
+      </ComboboxPrimitive.Positioner>
+    </ComboboxPrimitive.Portal>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Panel                                   */
+/* -------------------------------------------------------------------------- */
+
+export type CascaderPanelProps = useRender.ComponentProps<"div">
+
+/**
+ * The nav + list(s) + footer container, with no positioning of its own: inside
+ * `CascaderContent` for the popup case, alone for the embedded one.
+ *
+ * `min-h-0` and `max-h-full` are load-bearing. A flex child without `min-h-0`
+ * refuses to shrink below its content, which is the usual reason a scroll area
+ * never scrolls - worst embedded, where no positioner publishes
+ * `--available-height`. It also owns the panel's TAB ORDER: the scroll area
+ * makes itself a tab stop whenever the level overflows, stranding the footer,
+ * and the panel is the only ancestor of both ends of that move in BOTH shapes.
+ */
+function CascaderPanel({ className, ...props }: CascaderPanelProps) {
+  const { mode } = useCascaderActions()
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key !== "Tab" || event.defaultPrevented) return
+      // A browser-level move (Ctrl+Tab switches tabs) is never ours.
+      if (event.altKey || event.ctrlKey || event.metaKey) return
+
+      const panel = event.currentTarget
+      const target = event.target as HTMLElement | null
+      if (!target || !panel.contains(target)) return
+
+      const next = getCascaderTabTarget(panel, target, event.shiftKey)
+      // Off either end: left to the browser, since focus is never trapped.
+      if (!next) return
+
+      event.preventDefault()
+      next.focus()
+    },
+    []
+  )
+
+  const defaultProps = {
+    "data-slot": "cascader-panel",
+    "data-mode": mode,
+    // In `defaultProps`, not around `props.onKeyDown`: `mergeProps` chains
+    // right to left, so a consumer's handler runs FIRST and can drop this one.
+    onKeyDown: handleKeyDown,
+    className: cn("flex max-h-full min-h-0 w-full flex-col", className),
+  }
+
+  return useRender({
+    defaultTagName: "div",
+    render: props.render,
+    props: mergeProps<"div">(defaultProps, props),
+  })
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    List                                    */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderListProps extends Omit<
+  ComboboxPrimitive.List.Props,
+  "style"
+> {
+  /** Applied to the OUTER shell, which owns the height, so an inline
+   * `--cascader-max-height` lands where the bound can read it. Narrowed from
+   * Base UI's `style`: the shell is a plain `<div>` with no list state. */
+  style?: React.CSSProperties
+  /** Caps this level's height; the panel still shrinks to fit. Default 24rem. */
+  maxHeight?: number | string
+}
+
+/**
+ * Scroll container for one level: pattern 3 of the house scroll reference,
+ * viewport-bounded popup scroll. The height is `min()` of `--available-height`
+ * (the positioner's space between anchor and viewport edge) and `maxHeight`,
+ * so neither can be ignored; a fixed pixel cap alone still reserved 288px for
+ * a panel opened 200px above the fold and spilled off screen, and wasted room
+ * in a tall window. The four classes are shared with `CascaderColumns` and
+ * live in `cascader-lib.tsx`.
+ */
+function CascaderList({
+  className,
+  style,
+  maxHeight: maxHeightProp,
+  ...props
+}: CascaderListProps) {
+  const { maxHeight, mode, labels, baseId, virtualized, searchScope } =
+    useCascaderActions()
+  const { currentParent, deepResults } = useCascaderState()
+  const resolved = maxHeightProp ?? maxHeight
+  // Global hits come from the whole tree, so the parent would understate them.
+  const listName =
+    searchScope === "global" && deepResults
+      ? labels.rootLevel
+      : (currentParent?.label ?? labels.rootLevel)
+
+  return (
+    <div
+      data-slot="cascader-list-shell"
+      style={
+        resolved != null
+          ? ({
+              ...style,
+              "--cascader-max-height":
+                typeof resolved === "number" ? `${resolved}px` : resolved,
+            } as React.CSSProperties)
+          : style
+      }
+      className={cn(
+        "relative flex max-h-full min-h-0",
+        CASCADER_LIST_PAD_CLASS
+      )}
+    >
+      <div
+        data-slot="cascader-list-bounds"
+        className={cn(
+          "flex w-full min-w-0 flex-col overscroll-contain",
+          CASCADER_LIST_HEIGHT_CLASS
+        )}
+      >
+        <ScrollArea className={CASCADER_SCROLL_CLASS}>
+          <ComboboxPrimitive.List
+            data-slot="cascader-list"
+            /* Base UI names the list nothing, so every mode shipped an unnamed
+               listbox. The level's parent is the name; the root borrows one. */
+            aria-label={listName}
+            /* Replaces Base UI's floating id. `aria-controls` reads the live
+               id, so the columns trail gets a predictable target. */
+            id={`${baseId}-column-0`}
+            /* NEVER a ternary ending in `undefined`: `mergeProps` iterates own
+               keys, so that DELETES Base UI's `role="listbox"`. */
+            {...(mode === "tree" ? { role: "tree" as const } : null)}
+            {...(virtualized ? { "data-virtualized": true } : null)}
+            className={cn(
+              CASCADER_ROWS_CLASS,
+              /* A windowed row is absolutely positioned, so the ROWS' box is
+                 the containing block, not the scrollport: it carries the
+                 padding the geometry is measured against. */
+              virtualized && "relative",
+              className
+            )}
+            {...props}
+          />
+        </ScrollArea>
+      </div>
+    </div>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Empty / Loading                               */
+/* -------------------------------------------------------------------------- */
+
+export interface CascaderEmptyProps extends ComboboxPrimitive.Empty.Props {
+  /** @deprecated Ignored: the loading surface no longer draws skeletons. They
+   * promised a shape the level might not have and cost a second layout; the
+   * progress lives on the branch row instead. Kept so call sites compile. */
+  skeletonRows?: number
+}
+
+/** The empty, loading and error surface, in ONE element that never unmounts.
+ * `Combobox.Empty` renders whenever `filteredItems.length === 0`, as true of a
+ * fetching level as of an empty one, so swapping siblings would announce "No
+ * results found." over every async level. Swap the CHILDREN. */
+function CascaderEmpty({
+  className,
+  children,
+  // Accepted and ignored; destructured so it is never spread onto the DOM.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  skeletonRows,
+  ...props
+}: CascaderEmptyProps) {
+  const { labels, retryLevel, retrySearch } = useCascaderActions()
+  const { query, path, searchState } = useCascaderState()
+  // The level whose emptiness is on screen; tree always shows the root.
+  const levelKey = path.length ? path[path.length - 1] : CASCADER_ROOT_KEY
+  const loadState = useCascaderLoadState(levelKey)
+  const state = query.trim() ? (searchState ?? loadState) : loadState
+
+  let body: React.ReactNode = children ?? labels.empty
+
+  if (state?.error) {
+    body = (
+      <span
+        data-slot="cascader-error"
+        className="flex flex-col items-center gap-1.5"
+      >
+        <span>{labels.error}</span>
+        <button
+          type="button"
+          data-slot="cascader-retry"
+          /* A real button because this lives OUTSIDE the listbox; a focusable
+             element inside a `role="option"` is `nested-interactive`. */
+          onClick={(event) => {
+            focusCascaderHome(event.currentTarget)
+            // With a query set the error shown is the SEARCH's, so that is
+            // what to ask again; the level behind it never failed.
+            if (query.trim() && searchState?.error) retrySearch()
+            else retryLevel(levelKey)
+          }}
+          className="text-foreground hover:bg-accent focus-visible:ring-ring/50 rounded-md px-2 py-0.5 font-medium outline-hidden transition-colors focus-visible:ring-2"
+        >
+          {labels.retry}
+        </button>
+      </span>
+    )
+  } else if (state?.loading) {
+    body = (
+      <span
+        data-slot="cascader-loading"
+        className="flex w-full items-center justify-center"
+      >
+        {labels.loading}
+      </span>
+    )
+  }
+
+  return (
+    <ComboboxPrimitive.Empty
+      data-slot="cascader-empty"
+      data-state={state?.error ? "error" : state?.loading ? "loading" : "empty"}
+      className={cn(EMPTY_CLASS, className)}
+      /* The ONE place an explicit `undefined` is right: it DELETES Base UI's
+         live region, which is wanted. `CascaderStatus` is the single one, and
+         leaving this one spoke "No results found." on every level swap, which
+         renders one deliberately empty frame to reset the highlight. */
+      role={undefined}
+      aria-live={undefined}
+      aria-atomic={undefined}
+      {...props}
+    >
+      {body}
+    </ComboboxPrimitive.Empty>
+  )
+}
+
+export type CascaderStatusProps = ComboboxPrimitive.Status.Props
+
+/**
+ * Polite live region for the current level and result count, which drill-down
+ * otherwise hides in a visual breadcrumb. Built on `Combobox.Status` for its
+ * initial-mutation marker: Safari and VoiceOver need a text change ~200ms
+ * after mount before reading a polite region at all.
+ */
+function CascaderStatus({
+  className,
+  children,
+  ...props
+}: CascaderStatusProps) {
+  const { announcement } = useCascaderState()
+
+  return (
+    <ComboboxPrimitive.Status
+      data-slot="cascader-status"
+      className={cn("sr-only", className)}
+      {...props}
+    >
+      {children ?? announcement}
+    </ComboboxPrimitive.Status>
+  )
+}
+
+export {
+  Cascader,
+  CascaderTrigger,
+  CascaderChip,
+  CascaderChips,
+  CascaderContent,
+  CascaderPanel,
+  CascaderList,
+  CascaderEmpty,
+  CascaderStatus,
+}
+
+/** Re-exported from `cascader-context.tsx`: existing import paths keep
+ * working, and the row component avoids an import cycle through this file. */
+export {
+  createCascaderHighlightStore,
+  useCascaderActions,
+  useCascaderHighlight,
+  useCascaderRender,
+  useCascaderState,
+}
+
+export type {
+  CascaderActionsContextValue,
+  CascaderColumn,
+  CascaderHighlight,
+  CascaderHighlightStore,
+  CascaderItemState,
+  CascaderRenderContextValue,
+  CascaderStateContextValue,
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/data-grid/data-grid-cell-selection.tsx b/apps/web/src/components/reui/data-grid/data-grid-cell-selection.tsx
new file mode 100644
index 0000000..78aecd3
--- /dev/null
+++ b/apps/web/src/components/reui/data-grid/data-grid-cell-selection.tsx
@@ -0,0 +1,2610 @@
+"use client"
+
+// Opted out of React Compiler with the rest of the grid (see data-grid.tsx).
+"use no memo"
+
+import { useEffect, useRef, useState } from "react"
+import type {
+  CSSProperties,
+  KeyboardEvent as ReactKeyboardEvent,
+  ReactNode,
+  RefObject,
+} from "react"
+import { createPortal } from "react-dom"
+import { useDataGrid } from "@/components/reui/data-grid/data-grid"
+import type {
+  DataGridCellChange,
+  DataGridCellRejection,
+  DataGridCellsChangeDetails,
+  DataGridColumnCellEdit,
+  DataGridTableInstance,
+} from "@/components/reui/data-grid/data-grid"
+import { Subscribe } from "@tanstack/react-table"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { Button } from "@authportal/ui/components/button"
+
+/** Where a finished edit sends the focused cell, or null to stay. */
+type DataGridEditorAdvance = "down" | "up" | "right" | "left" | null
+
+interface DataGridFocusCellOptions {
+  /** Also open the cell's editor, the way Enter would. */
+  edit?: boolean
+}
+
+/** Imperative surface of the cell-selection controller. */
+interface DataGridCellSelectionApi {
+  /**
+   * Moves the grid's cell focus AND the document focus together, retrying
+   * briefly while the row mounts, so a freshly created row is typeable
+   * without an extra click. `edit: true` also opens the cell's editor the
+   * way Enter would. Registered once the controller is wired; null while
+   * cell selection is off.
+   */
+  focusCell: (
+    rowId: string,
+    columnId: string,
+    options?: DataGridFocusCellOptions
+  ) => void
+  /** Clears every range and the focused cell. */
+  clearSelection: () => void
+  /** Scrolls a rendered cell into view without moving focus. */
+  scrollToCell: (rowId: string, columnId: string) => void
+}
+
+/** One open built-in editor: which cell, which control, and its text. */
+interface DataGridEditorSession {
+  rowId: string
+  columnId: string
+  control: "text" | "textarea"
+  /** What the editor opens with: the typed seed or the formatted value. */
+  initialValue: string
+  /** The formatted current value; an unchanged commit dispatches nothing. */
+  baseline: string
+  /** Accessible name for the overlay control, from the column's header. */
+  label: string
+}
+
+/* ------------------------------------------------------------------------- *
+ * Clipboard text: pure, node-testable.
+ * ------------------------------------------------------------------------- */
+
+function serializeDataGridClipboardField(field: string): string {
+  // Excel and Sheets quote a field containing a delimiter and double inner
+  // quotes; everything else ships bare.
+  return /[\t\n\r"]/.test(field)
+    ? '"' + field.replaceAll('"', '""') + '"'
+    : field
+}
+
+/** Row-major grid to TSV, CRLF rows, Excel-style quoting. */
+function serializeDataGridClipboardText(grid: string[][]): string {
+  return grid
+    .map((line) => line.map(serializeDataGridClipboardField).join("\t"))
+    .join("\r\n")
+}
+
+/**
+ * TSV to a row-major grid. A stateful scan, not a split: a quoted field may
+ * contain tabs, quotes and both newline flavors, which is exactly what Excel
+ * emits for a multi-line cell.
+ */
+function parseDataGridClipboardText(text: string): string[][] {
+  const rows: string[][] = []
+  let row: string[] = []
+  let field = ""
+  let quoted = false
+  let i = 0
+
+  while (i < text.length) {
+    const ch = text[i]!
+    if (quoted) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') {
+          field += '"'
+          i += 2
+          continue
+        }
+        quoted = false
+        i += 1
+        continue
+      }
+      field += ch
+      i += 1
+      continue
+    }
+    if (ch === '"' && field === "") {
+      quoted = true
+      i += 1
+      continue
+    }
+    if (ch === "\t") {
+      row.push(field)
+      field = ""
+      i += 1
+      continue
+    }
+    if (ch === "\r" || ch === "\n") {
+      if (ch === "\r" && text[i + 1] === "\n") i += 1
+      row.push(field)
+      rows.push(row)
+      row = []
+      field = ""
+      i += 1
+      continue
+    }
+    field += ch
+    i += 1
+  }
+  row.push(field)
+  rows.push(row)
+
+  // Excel terminates the payload with one newline; that final empty line is
+  // an artifact of the format, not a data row.
+  const last = rows[rows.length - 1]
+  if (rows.length > 1 && last?.length === 1 && last[0] === "") rows.pop()
+
+  return rows
+}
+
+/** Repeats a block cyclically to fill rowCount x columnCount. */
+function tileDataGridClipboardBlock(
+  block: string[][],
+  rowCount: number,
+  columnCount: number
+): string[][] {
+  const tiled: string[][] = []
+  for (let r = 0; r < rowCount; r++) {
+    const source = block[r % block.length] ?? []
+    const line: string[] = []
+    for (let c = 0; c < columnCount; c++) {
+      line.push(source[c % (source.length || 1)] ?? "")
+    }
+    tiled.push(line)
+  }
+  return tiled
+}
+
+function escapeDataGridClipboardHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+}
+
+// A minimal text/html flavor alongside the TSV keeps type fidelity when the
+// paste target is Excel or Sheets. Newlines inside a field become <br>, the
+// HTML representation of a multi-line cell; raw newlines would collapse to
+// spaces on paste.
+function renderDataGridClipboardHtml(grid: string[][]): string {
+  const body = grid
+    .map(
+      (line) =>
+        "<tr>" +
+        line
+          .map(
+            (field) =>
+              "<td>" +
+              escapeDataGridClipboardHtml(field).replace(
+                /\r\n|\r|\n/g,
+                "<br>"
+              ) +
+              "</td>"
+          )
+          .join("") +
+        "</tr>"
+    )
+    .join("")
+  return "<table><tbody>" + body + "</tbody></table>"
+}
+
+/* ------------------------------------------------------------------------- *
+ * Selection geometry: walks in the feature's own index space.
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Columns in render order, the same [start, center, end] space
+ * cellSelectionFeature resolves its bounds against.
+ */
+function getDataGridDisplayOrderedColumns<TData extends object>(
+  table: DataGridTableInstance<TData>
+) {
+  return [
+    ...table.getStartVisibleLeafColumns(),
+    ...table.getCenterVisibleLeafColumns(),
+    ...table.getEndVisibleLeafColumns(),
+  ]
+}
+
+function getDataGridWritableCellEdit<TData extends object>(
+  column: {
+    columnDef: { meta?: { cellEdit?: DataGridColumnCellEdit<TData> } }
+  },
+  /**
+   * The row a write targets. Function-form `editable` is evaluated against
+   * it; without a row the column counts as writable in principle, the
+   * coarse check the fill preview's column filter uses.
+   */
+  row?: TData
+): DataGridColumnCellEdit<TData> | null {
+  const cellEdit = column.columnDef.meta?.cellEdit
+  if (!cellEdit || cellEdit.editable === false) return null
+  if (
+    typeof cellEdit.editable === "function" &&
+    row !== undefined &&
+    !cellEdit.editable(row)
+  ) {
+    return null
+  }
+  return cellEdit
+}
+
+/**
+ * Ids of the rows the view can actually show: the page slice plus rows the
+ * DOM renders outside it (pinned rows under keepPinnedRows). Selection
+ * bounds live in pre-paginated display order, so a range whose corners are
+ * both visible can still span off-page rows in between - a page-boundary
+ * range to a bottom-pinned draft is the standing example. Every batch walk
+ * (copy, clear, paste, fill) filters rows through this set so the cells a
+ * batch touches are exactly the cells the selection paints.
+ */
+function getDataGridRenderedRowIds<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  viewport: HTMLElement | null | undefined
+): Set<string> | null {
+  if (!viewport) return null
+  // When the page slice covers the whole display order (manual pagination,
+  // virtualization, no pagination) no row can be off-page: skip the walk.
+  if (table.getRowModel().rows.length === table.getRowsInDisplayOrder().length) {
+    return null
+  }
+  const rendered = new Set<string>(
+    table.getRowModel().rows.map((row: { id: string }) => row.id)
+  )
+  for (const rowEl of Array.from(
+    viewport.querySelectorAll("tbody tr[data-row-id]")
+  )) {
+    const id = rowEl.getAttribute("data-row-id")
+    if (id) rendered.add(id)
+  }
+  return rendered
+}
+
+/**
+ * Cells of the current selection the view can actually show, under the
+ * same row filter the batch builders use, so a count shown next to the
+ * selection always matches what is painted and what a batch will touch.
+ * The feature's own getSelectedCellCount spans off-page rows instead.
+ */
+function getDataGridVisibleSelectedCellCount<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  /** The grid's body viewport; null falls back to the full-range count. */
+  viewport: HTMLElement | null
+): number {
+  const bounds = table.getCellSelectionBounds()
+  if (!bounds.length) return 0
+  const rows = table.getRowsInDisplayOrder()
+  const columns = getDataGridDisplayOrderedColumns(table)
+  const rendered = getDataGridRenderedRowIds(table, viewport)
+  let count = 0
+  for (const bound of bounds) {
+    let rowCount = 0
+    for (let r = bound.minRowIndex; r <= bound.maxRowIndex; r++) {
+      const row = rows[r]
+      if (row && (!rendered || rendered.has(row.id))) rowCount += 1
+    }
+    let columnCount = 0
+    for (let c = bound.minColumnIndex; c <= bound.maxColumnIndex; c++) {
+      const column = columns[c]
+      if (column && column.columnDef.enableCellSelection !== false) {
+        columnCount += 1
+      }
+    }
+    count += rowCount * columnCount
+  }
+  return count
+}
+
+/**
+ * The bound of the ACTIVE (most recent) region. getCellSelectionBounds()
+ * sorts geometrically, so its last entry is merely the bottom-right
+ * rectangle; the focused cell anchors the newest range, so the bound
+ * containing it is the active one. Falls back to the geometric last when
+ * the focused cell sits in no bound (the newest range was an exclude).
+ */
+function getDataGridActiveBound<TData extends object>(
+  table: DataGridTableInstance<TData>
+) {
+  const bounds = table.getCellSelectionBounds()
+  if (!bounds.length) return null
+  const focused = table.getFocusedCell()
+  if (focused) {
+    // O(1): v9 caches the display index on the row itself.
+    const rowIndex = focused.row.getDisplayIndex()
+    const columnIndex = getDataGridDisplayOrderedColumns(table).findIndex(
+      (column) => column.id === focused.column.id
+    )
+    const containing = bounds.find(
+      (bound) =>
+        rowIndex >= bound.minRowIndex &&
+        rowIndex <= bound.maxRowIndex &&
+        columnIndex >= bound.minColumnIndex &&
+        columnIndex <= bound.maxColumnIndex
+    )
+    if (containing) return containing
+  }
+  return bounds[bounds.length - 1] ?? null
+}
+
+/**
+ * Resolves the cell one visual step away from a given cell: selectable
+ * columns for horizontal, RENDERED row order for vertical. The feature's
+ * own move/extend resolve rows through the page slice and stall on pinned
+ * rows (a bottom-pinned draft), while id-addressed cells work everywhere.
+ * "edge" means the step is at the grid boundary; null means the position
+ * is not resolvable here and the caller should use the feature's move.
+ */
+function getDataGridStepTarget<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  viewport: HTMLElement,
+  from: { rowId: string; columnId: string },
+  direction: "up" | "down" | "left" | "right"
+): { rowId: string; columnId: string } | "edge" | null {
+  if (direction === "left" || direction === "right") {
+    const selectable = getDataGridDisplayOrderedColumns(table).filter(
+      (column) => column.columnDef.enableCellSelection !== false
+    )
+    const index = selectable.findIndex(
+      (column) => column.id === from.columnId
+    )
+    if (index === -1) return null
+    const next = selectable[index + (direction === "right" ? 1 : -1)]
+    return next ? { rowId: from.rowId, columnId: next.id } : "edge"
+  }
+  const renderedIds = Array.from(
+    viewport.querySelectorAll("tbody tr[data-row-id]")
+  ).map((row) => row.getAttribute("data-row-id"))
+  const index = renderedIds.indexOf(from.rowId)
+  if (index === -1) return null
+  const nextId = renderedIds[index + (direction === "down" ? 1 : -1)]
+  return nextId ? { rowId: nextId, columnId: from.columnId } : "edge"
+}
+
+/**
+ * Shift+Arrow: the feature keeps focus on the anchor and grows the range
+ * from its active corner. When its own extend cannot resolve the step
+ * (the active corner sits on a pinned row, or the next visual row is a
+ * pinned row outside the page slice), re-derive the active corner from
+ * the bounds and step it in visual space through selectCellRange.
+ */
+function extendDataGridSelection<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  viewport: HTMLElement,
+  direction: "up" | "down" | "left" | "right"
+): { rowId: string; columnId: string } | null {
+  // The range's active corner: focus stays the anchor, so the corner is
+  // the bound's opposite one. Returned to the caller so the view can
+  // follow the growing edge rather than the anchor.
+  const activeCorner = () => {
+    const focused = table.getFocusedCell()
+    if (!focused) return null
+    const bound = getDataGridActiveBound(table)
+    if (!bound) return null
+    const rows = table.getRowsInDisplayOrder()
+    const allColumns = getDataGridDisplayOrderedColumns(table)
+    const rowIndex = focused.row.getDisplayIndex()
+    const columnIndex = allColumns.findIndex(
+      (column) => column.id === focused.column.id
+    )
+    return {
+      rowId:
+        rows[
+          rowIndex === bound.minRowIndex
+            ? bound.maxRowIndex
+            : bound.minRowIndex
+        ]?.id ?? focused.row.id,
+      columnId:
+        allColumns[
+          columnIndex === bound.minColumnIndex
+            ? bound.maxColumnIndex
+            : bound.minColumnIndex
+        ]?.id ?? focused.column.id,
+    }
+  }
+  const boundKey = () => {
+    const bounds = table.getCellSelectionBounds()
+    const bound = bounds[bounds.length - 1]
+    return bound
+      ? `${bounds.length}:${bound.minRowIndex}-${bound.maxRowIndex}:${bound.minColumnIndex}-${bound.maxColumnIndex}`
+      : "none"
+  }
+  const before = boundKey()
+  table.extendCellSelection(direction)
+  if (boundKey() !== before) return activeCorner()
+  const focused = table.getFocusedCell()
+  if (!focused) return null
+  const active = activeCorner() ?? {
+    rowId: focused.row.id,
+    columnId: focused.column.id,
+  }
+  const target = getDataGridStepTarget(table, viewport, active, direction)
+  if (!target || target === "edge") return null
+  table.selectCellRange(
+    {
+      anchorRowId: focused.row.id,
+      anchorColumnId: focused.column.id,
+      focusRowId: target.rowId,
+      focusColumnId: target.columnId,
+    },
+    { mode: "replace" }
+  )
+  return target
+}
+
+/**
+ * The active region as formatted strings, row-major. Columns opted out of
+ * selection are compacted away, matching the feature's own ranges-data
+ * behavior, and rows the view cannot show are skipped when a viewport is
+ * given. Null when nothing is selected.
+ */
+function getDataGridActiveRegionGrid<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  viewport?: HTMLElement | null
+): string[][] | null {
+  const bound = getDataGridActiveBound(table)
+  if (!bound) return null
+
+  const rows = table.getRowsInDisplayOrder()
+  const columns = getDataGridDisplayOrderedColumns(table)
+  const rendered = getDataGridRenderedRowIds(table, viewport)
+  const grid: string[][] = []
+
+  for (let r = bound.minRowIndex; r <= bound.maxRowIndex; r++) {
+    const row = rows[r]
+    if (!row || (rendered && !rendered.has(row.id))) continue
+    const cells = row.getAllCellsByColumnId()
+    const line: string[] = []
+    for (let c = bound.minColumnIndex; c <= bound.maxColumnIndex; c++) {
+      const column = columns[c]
+      if (!column || column.columnDef.enableCellSelection === false) continue
+      const value = cells[column.id]?.getValue()
+      const format = column.columnDef.meta?.cellEdit?.format
+      line.push(
+        format ? format(value, row.original) : String(value ?? "")
+      )
+    }
+    grid.push(line)
+  }
+
+  return grid.length ? grid : null
+}
+
+/**
+ * A clear/cut batch over the selection's writable cells. Non-writable columns
+ * are skipped silently: clearing is an intent over what the grid owns, and a
+ * rejection per read-only cell would be noise. Null when nothing clears.
+ */
+function buildDataGridClearDetails<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  source: "clear" | "cut",
+  activeRegionOnly: boolean,
+  viewport?: HTMLElement | null
+): DataGridCellsChangeDetails<TData> | null {
+  const allBounds = table.getCellSelectionBounds()
+  const activeBound = getDataGridActiveBound(table)
+  const bounds = activeRegionOnly
+    ? activeBound
+      ? [activeBound]
+      : []
+    : allBounds
+  if (!bounds.length) return null
+
+  const rows = table.getRowsInDisplayOrder()
+  const columns = getDataGridDisplayOrderedColumns(table)
+  const rendered = getDataGridRenderedRowIds(table, viewport)
+  const changes: DataGridCellChange<TData>[] = []
+
+  for (const bound of bounds) {
+    for (let r = bound.minRowIndex; r <= bound.maxRowIndex; r++) {
+      const row = rows[r]
+      if (!row || (rendered && !rendered.has(row.id))) continue
+      const cells = row.getAllCellsByColumnId()
+      for (let c = bound.minColumnIndex; c <= bound.maxColumnIndex; c++) {
+        const column = columns[c]
+        if (!column || column.columnDef.enableCellSelection === false) continue
+        const cellEdit = getDataGridWritableCellEdit<TData>(column, row.original)
+        if (!cellEdit) continue
+        changes.push({
+          rowId: row.id,
+          columnId: column.id,
+          row: row.original,
+          previousValue: cells[column.id]?.getValue(),
+          value: cellEdit.clearValue ?? null,
+        })
+      }
+    }
+  }
+
+  return changes.length ? { source, changes, rejected: [] } : null
+}
+
+type DataGridPasteTarget = {
+  /** Display indexes of the pasted region's first and last row. */
+  startRowIndex: number
+  endRowIndex: number
+  /** How many rows a paste actually wrote (hidden rows are skipped). */
+  rowCount?: number
+  /** Display indexes of the pasted region's first and last column. */
+  startColumnIndex: number
+  endColumnIndex: number
+}
+
+/**
+ * Resolves a parsed clipboard block into a paste batch, Excel semantics:
+ * a 1x1 block fills the whole selected region; a block tiles when the region
+ * is an exact multiple of it; otherwise it pastes once from the region's
+ * top-left, clamped at the grid edges (rows are never grown).
+ */
+function buildDataGridPasteDetails<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  block: string[][],
+  viewport?: HTMLElement | null
+): {
+  details: DataGridCellsChangeDetails<TData>
+  target: DataGridPasteTarget
+} | null {
+  if (!block.length) return null
+  const bound = getDataGridActiveBound(table)
+  if (!bound) return null
+
+  const rows = table.getRowsInDisplayOrder()
+  const columns = getDataGridDisplayOrderedColumns(table)
+  const rendered = getDataGridRenderedRowIds(table, viewport)
+
+  // Copy COMPACTS opt-out columns away, so paste maps block columns over the
+  // same compacted space: selectable columns only, starting at the region's
+  // first selectable column and running past the region for a wider block,
+  // clamped at the grid edge. Walking raw display offsets instead would let
+  // an interior opt-out column swallow a block column silently.
+  const targetColumns: Array<{
+    column: (typeof columns)[number]
+    displayIndex: number
+  }> = []
+  let regionColumns = 0
+  for (let c = bound.minColumnIndex; c < columns.length; c++) {
+    const column = columns[c]
+    if (!column || column.columnDef.enableCellSelection === false) continue
+    targetColumns.push({ column, displayIndex: c })
+    if (c <= bound.maxColumnIndex) regionColumns += 1
+  }
+  if (!regionColumns) return null
+
+  const blockRows = block.length
+  const blockColumns = block.reduce((max, line) => Math.max(max, line.length), 1)
+  const regionRows = bound.maxRowIndex - bound.minRowIndex + 1
+
+  let rowCount: number
+  let columnCount: number
+  if (blockRows === 1 && blockColumns === 1) {
+    rowCount = regionRows
+    columnCount = regionColumns
+  } else if (
+    regionRows % blockRows === 0 &&
+    regionColumns % blockColumns === 0
+  ) {
+    rowCount = regionRows
+    columnCount = regionColumns
+  } else {
+    rowCount = blockRows
+    columnCount = blockColumns
+  }
+
+  const tiled = tileDataGridClipboardBlock(block, rowCount, columnCount)
+  const startRowIndex = bound.minRowIndex
+
+  // Rows the block maps onto: the next rowCount rows the view can show,
+  // starting at the region's top. Off-page rows between a page's tail and
+  // a pinned draft are skipped rather than silently written.
+  const targetRows: Array<{ row: (typeof rows)[number]; displayIndex: number }> =
+    []
+  for (let r = startRowIndex; r < rows.length; r++) {
+    if (targetRows.length === rowCount) break
+    const row = rows[r]
+    if (!row || (rendered && !rendered.has(row.id))) continue
+    targetRows.push({ row, displayIndex: r })
+  }
+
+  const changes: DataGridCellChange<TData>[] = []
+  const rejected: DataGridCellRejection[] = []
+
+  for (let r = 0; r < targetRows.length; r++) {
+    const row = targetRows[r]!.row
+    const cells = row.getAllCellsByColumnId()
+    for (let c = 0; c < columnCount; c++) {
+      const column = targetColumns[c]?.column
+      if (!column) continue
+      const raw = tiled[r]?.[c] ?? ""
+      const cellEdit = getDataGridWritableCellEdit<TData>(column, row.original)
+      if (!cellEdit) {
+        rejected.push({
+          rowId: row.id,
+          columnId: column.id,
+          raw,
+          reason: "readonly",
+        })
+        continue
+      }
+      const value = cellEdit.parse ? cellEdit.parse(raw, row.original) : raw
+      if (value === undefined) {
+        rejected.push({
+          rowId: row.id,
+          columnId: column.id,
+          raw,
+          reason: "invalid",
+        })
+        continue
+      }
+      changes.push({
+        rowId: row.id,
+        columnId: column.id,
+        row: row.original,
+        previousValue: cells[column.id]?.getValue(),
+        value,
+      })
+    }
+  }
+
+  if (!changes.length && !rejected.length) return null
+  const lastTarget =
+    targetColumns[Math.min(columnCount, targetColumns.length) - 1]
+  return {
+    details: { source: "paste", changes, rejected },
+    target: {
+      startRowIndex,
+      endRowIndex: targetRows[targetRows.length - 1]?.displayIndex ?? startRowIndex,
+      rowCount: targetRows.length,
+      startColumnIndex: targetColumns[0]!.displayIndex,
+      endColumnIndex: lastTarget!.displayIndex,
+    },
+  }
+}
+
+/**
+ * The inverse batch: every change's value and previousValue swapped and
+ * rejections dropped. Feed it through the same state update onCellsChange
+ * uses to implement undo; inverting the inverse is redo.
+ */
+function invertDataGridCellsChange<TData extends object>(
+  details: DataGridCellsChangeDetails<TData>
+): DataGridCellsChangeDetails<TData> {
+  return {
+    source: details.source,
+    changes: details.changes.map((change) => ({
+      ...change,
+      value: change.previousValue,
+      previousValue: change.value,
+    })),
+    rejected: [],
+  }
+}
+
+function selectDataGridRegion<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  target: DataGridPasteTarget
+) {
+  const rows = table.getRowsInDisplayOrder()
+  const columns = getDataGridDisplayOrderedColumns(table)
+  const anchorRow = rows[target.startRowIndex]
+  const anchorColumn = columns[target.startColumnIndex]
+  const focusRow = rows[Math.min(target.endRowIndex, rows.length - 1)]
+  const focusColumn = columns[target.endColumnIndex]
+  if (!anchorRow || !anchorColumn || !focusRow || !focusColumn) return
+  table.selectCellRange(
+    {
+      anchorRowId: anchorRow.id,
+      anchorColumnId: anchorColumn.id,
+      focusRowId: focusRow.id,
+      focusColumnId: focusColumn.id,
+    },
+    { mode: "replace" }
+  )
+}
+
+/* ------------------------------------------------------------------------- *
+ * Fill handle drag session.
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Imperative document-level session, the column-resize pattern: preview state
+ * is written as `data-cell-fill-target` attributes outside React, so the drag
+ * costs zero re-renders until release. v1 fills down or right (dominant axis)
+ * by repeating the source region's values; rows outside the rendered
+ * viewport of a virtualized body cannot be targeted mid-drag.
+ *
+ * Vertical distance is measured over the rows the view can show, so a drag
+ * onto a pinned draft fills exactly the rows the preview marked and never
+ * the off-page rows between. A cross-column fill round-trips through the
+ * source's format and the target's parse - the paste contract - because
+ * adjacent grid columns are heterogeneous; a parse rejection lands in the
+ * batch's rejected list, while cells that cannot be written are skipped
+ * and never tinted by the preview.
+ */
+// The fill drag's feedback: ONE dashed border (the Sheets fill marquee)
+// around the whole pending region - the source PLUS the extension - so the
+// drag reads as one growing region, never as a second box glued under the
+// source. While the session runs
+// the viewport carries data-cell-filling and the source cells' own
+// selection chrome rests, so this element is the only painter and nothing
+// can double at the junction. z-[35]: above the sticky pinned cells
+// (z 30) so the border survives crossing a pinned column; below the
+// sticky header (z-40).
+const dataGridGestureOutlineClasses =
+  "outline-primary pointer-events-none absolute z-[35] outline-1 outline-dashed -outline-offset-1"
+
+function startDataGridFillSession<TData extends object>(options: {
+  table: DataGridTableInstance<TData>
+  viewport: HTMLElement
+  onCellsChange: ((details: DataGridCellsChangeDetails<TData>) => void) | null
+}) {
+  const { table, viewport, onCellsChange } = options
+  // Fill over a multi-region selection is undefined territory; Excel refuses
+  // it too.
+  if (table.getCellSelectionBounds().length > 1) return
+  const bound = getDataGridActiveBound(table)
+  if (!bound) return
+
+  const rows = table.getRowsInDisplayOrder()
+  const columns = getDataGridDisplayOrderedColumns(table)
+  // The vertical walk space: rows the view can show, in display order. The
+  // DOM ids seed it (a drag can only target rendered rows), and one pass
+  // over the cached display array resolves them without building per-row
+  // wrappers for a 50k-row model.
+  const domRowIds = new Set<string>()
+  for (const rowEl of Array.from(
+    viewport.querySelectorAll("tbody tr[data-row-id]")
+  )) {
+    const id = rowEl.getAttribute("data-row-id")
+    if (id) domRowIds.add(id)
+  }
+  const visibleRows: Array<{ row: (typeof rows)[number]; displayIndex: number }> =
+    []
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i]!
+    if (domRowIds.has(row.id)) {
+      visibleRows.push({ row, displayIndex: i })
+    }
+  }
+  const visibleIndexById = new Map(
+    visibleRows.map((entry, index) => [entry.row.id, index])
+  )
+  // The source region and its last row, both in visible space.
+  const sourceRows = visibleRows.filter(
+    ({ displayIndex }) =>
+      displayIndex >= bound.minRowIndex && displayIndex <= bound.maxRowIndex
+  )
+  const sourceEndVisibleIndex = sourceRows.length
+    ? visibleIndexById.get(sourceRows[sourceRows.length - 1]!.row.id)!
+    : -1
+  if (sourceEndVisibleIndex === -1) return
+  const columnIndexById = new Map(
+    columns.map((column, index) => [column.id, index])
+  )
+  const isFillableColumn = (column: (typeof columns)[number]) =>
+    column.columnDef.enableCellSelection !== false &&
+    !!getDataGridWritableCellEdit<TData>(column)
+
+  let extension: { axis: "row" | "column"; count: number } | null = null
+  let previewCells: Element[] = []
+
+  const previewOutline = viewport.ownerDocument.createElement("div")
+  previewOutline.setAttribute("data-slot", "data-grid-cell-fill-preview")
+  previewOutline.className = dataGridGestureOutlineClasses
+  previewOutline.style.display = "none"
+  viewport.appendChild(previewOutline)
+  viewport.setAttribute("data-cell-filling", "")
+
+  // The region border wraps source plus extension: its corners are the
+  // source region's first cell and the farthest cell the drag reaches
+  // (the source's own last cell while nothing is extended).
+  const sourceCorner = (rowId: string, columnId: string | undefined) =>
+    columnId
+      ? viewport.querySelector(
+          `tr[data-row-id="${CSS.escape(rowId)}"] td[data-col-id="${CSS.escape(columnId)}"]`
+        )
+      : null
+  const positionPreviewOutline = () => {
+    const first = sourceRows.length
+      ? sourceCorner(sourceRows[0]!.row.id, columns[bound.minColumnIndex]?.id)
+      : null
+    const lastSource = sourceRows.length
+      ? sourceCorner(
+          sourceRows[sourceRows.length - 1]!.row.id,
+          columns[bound.maxColumnIndex]?.id
+        )
+      : null
+    const far = previewCells.length
+      ? previewCells[previewCells.length - 1]!
+      : lastSource
+    if (!first || !far) {
+      previewOutline.style.display = "none"
+      return
+    }
+    const firstRect = first.getBoundingClientRect()
+    const farRect = far.getBoundingClientRect()
+    const viewportRect = viewport.getBoundingClientRect()
+    const left = Math.min(firstRect.left, farRect.left)
+    const top = Math.min(firstRect.top, farRect.top)
+    previewOutline.style.display = "block"
+    previewOutline.style.left = `${left - viewportRect.left + viewport.scrollLeft}px`
+    previewOutline.style.top = `${top - viewportRect.top + viewport.scrollTop}px`
+    previewOutline.style.width = `${Math.max(firstRect.right, farRect.right) - left}px`
+    previewOutline.style.height = `${Math.max(firstRect.bottom, farRect.bottom) - top}px`
+  }
+
+  const clearPreview = () => {
+    for (const cell of previewCells) cell.removeAttribute("data-cell-fill-target")
+    previewCells = []
+    positionPreviewOutline()
+  }
+
+  // Target rows and columns for the current extension: rows in visible
+  // space, and only the columns the commit would actually write, so the
+  // preview never tints a cell the release will skip.
+  const getExtensionTargets = () => {
+    if (!extension) return null
+    const columnEntries = columns.map((column, displayIndex) => ({
+      column,
+      displayIndex,
+    }))
+    return extension.axis === "row"
+      ? {
+          rowEntries: visibleRows.slice(
+            sourceEndVisibleIndex + 1,
+            sourceEndVisibleIndex + 1 + extension.count
+          ),
+          columnEntries: columnEntries
+            .slice(bound.minColumnIndex, bound.maxColumnIndex + 1)
+            .filter(({ column }) => isFillableColumn(column)),
+        }
+      : {
+          rowEntries: sourceRows,
+          columnEntries: columnEntries
+            .slice(
+              bound.maxColumnIndex + 1,
+              bound.maxColumnIndex + 1 + extension.count
+            )
+            .filter(({ column }) => isFillableColumn(column)),
+        }
+  }
+
+  const applyPreview = () => {
+    clearPreview()
+    const targets = getExtensionTargets()
+    if (!targets) return
+    for (const { row } of targets.rowEntries) {
+      const rowElement = viewport.querySelector(
+        `tr[data-row-id="${CSS.escape(row.id)}"]`
+      )
+      if (!rowElement) continue
+      for (const { column } of targets.columnEntries) {
+        if (!getDataGridWritableCellEdit<TData>(column, row.original)) continue
+        const cellElement = rowElement.querySelector(
+          `td[data-col-id="${CSS.escape(column.id)}"]`
+        )
+        if (!cellElement) continue
+        cellElement.setAttribute("data-cell-fill-target", "true")
+        previewCells.push(cellElement)
+      }
+    }
+
+    positionPreviewOutline()
+  }
+
+  const handleMove = (event: MouseEvent) => {
+    const element = document.elementFromPoint(event.clientX, event.clientY)
+    const cellElement = element?.closest?.("td[data-col-id]")
+    const rowElement = cellElement?.closest?.("tr[data-row-id]")
+    if (!cellElement || !rowElement || !viewport.contains(cellElement)) return
+
+    const rowVisibleIndex = visibleIndexById.get(
+      rowElement.getAttribute("data-row-id") ?? ""
+    )
+    const columnIndex = columnIndexById.get(
+      cellElement.getAttribute("data-col-id") ?? ""
+    )
+    if (rowVisibleIndex === undefined || columnIndex === undefined) return
+
+    const rowsDelta = Math.max(0, rowVisibleIndex - sourceEndVisibleIndex)
+    const columnsDelta = Math.max(0, columnIndex - bound.maxColumnIndex)
+    const next: typeof extension =
+      rowsDelta === 0 && columnsDelta === 0
+        ? null
+        : rowsDelta >= columnsDelta
+          ? { axis: "row", count: rowsDelta }
+          : { axis: "column", count: columnsDelta }
+
+    if (next?.axis === extension?.axis && next?.count === extension?.count) {
+      return
+    }
+    extension = next
+    applyPreview()
+  }
+
+  const finish = (commit: boolean) => {
+    document.removeEventListener("mousemove", handleMove)
+    document.removeEventListener("mouseup", handleUp)
+    document.removeEventListener("keydown", handleKey, true)
+    clearPreview()
+    previewOutline.remove()
+    viewport.removeAttribute("data-cell-filling")
+    if (!commit || !extension || !onCellsChange) return
+    const targets = getExtensionTargets()
+    if (!targets || !targets.rowEntries.length) return
+
+    const changes: DataGridCellChange<TData>[] = []
+    const rejected: DataGridCellRejection[] = []
+
+    if (extension.axis === "row") {
+      for (let offset = 0; offset < targets.rowEntries.length; offset++) {
+        const targetRow = targets.rowEntries[offset]!.row
+        const sourceRow = sourceRows[offset % sourceRows.length]!.row
+        const targetCells = targetRow.getAllCellsByColumnId()
+        const sourceCells = sourceRow.getAllCellsByColumnId()
+        for (const { column } of targets.columnEntries) {
+          if (!getDataGridWritableCellEdit<TData>(column, targetRow.original)) {
+            continue
+          }
+          changes.push({
+            rowId: targetRow.id,
+            columnId: column.id,
+            row: targetRow.original,
+            previousValue: targetCells[column.id]?.getValue(),
+            value: sourceCells[column.id]?.getValue(),
+          })
+        }
+      }
+    } else {
+      const regionColumns = bound.maxColumnIndex - bound.minColumnIndex + 1
+      for (const { row } of targets.rowEntries) {
+        const cells = row.getAllCellsByColumnId()
+        for (const { column: targetColumn, displayIndex } of targets.columnEntries) {
+          const offset = displayIndex - (bound.maxColumnIndex + 1)
+          const sourceColumn =
+            columns[bound.minColumnIndex + (offset % regionColumns)]
+          if (!sourceColumn) continue
+          const targetEdit = getDataGridWritableCellEdit<TData>(
+            targetColumn,
+            row.original
+          )
+          if (!targetEdit) continue
+          const sourceValue = cells[sourceColumn.id]?.getValue()
+          let value: unknown = sourceValue
+          // Crossing columns is a type boundary: round-trip through the
+          // source's format and the target's parse, exactly what pasting
+          // the same cells would do. Same-column fills keep raw values.
+          if (targetColumn.id !== sourceColumn.id && targetEdit.parse) {
+            const sourceFormat =
+              sourceColumn.columnDef.meta?.cellEdit?.format
+            const raw = sourceFormat
+              ? sourceFormat(sourceValue, row.original)
+              : String(sourceValue ?? "")
+            const parsed = targetEdit.parse(raw, row.original)
+            if (parsed === undefined) {
+              rejected.push({
+                rowId: row.id,
+                columnId: targetColumn.id,
+                raw,
+                reason: "invalid",
+              })
+              continue
+            }
+            value = parsed
+          }
+          changes.push({
+            rowId: row.id,
+            columnId: targetColumn.id,
+            row: row.original,
+            previousValue: cells[targetColumn.id]?.getValue(),
+            value,
+          })
+        }
+      }
+    }
+
+    if (changes.length || rejected.length) {
+      onCellsChange({ source: "fill", changes, rejected })
+    }
+
+    // Grow the selection over source plus filled cells, Excel's post-fill
+    // shape.
+    selectDataGridRegion(table, {
+      startRowIndex: bound.minRowIndex,
+      endRowIndex:
+        extension.axis === "row"
+          ? targets.rowEntries[targets.rowEntries.length - 1]!.displayIndex
+          : bound.maxRowIndex,
+      startColumnIndex: bound.minColumnIndex,
+      endColumnIndex:
+        bound.maxColumnIndex +
+        (extension.axis === "column" ? extension.count : 0),
+    })
+  }
+
+  const handleUp = () => finish(true)
+  // Capture phase so a cancel cannot also reach the grid's own Escape
+  // handling and clear the selection underneath the drag.
+  const handleKey = (event: KeyboardEvent) => {
+    if (event.key !== "Escape") return
+    event.stopPropagation()
+    finish(false)
+  }
+
+  document.addEventListener("mousemove", handleMove)
+  document.addEventListener("mouseup", handleUp)
+  document.addEventListener("keydown", handleKey, true)
+}
+
+/* ------------------------------------------------------------------------- *
+ * Controller.
+ * ------------------------------------------------------------------------- */
+
+function isDataGridEditableTarget(target: EventTarget | null): boolean {
+  // data-cell-interactive is the same opt-out the mousedown guard honors, so
+  // a custom widget keeps its own keys and clipboard as well as its clicks.
+  return (
+    target instanceof Element &&
+    target.closest(
+      "input, textarea, select, [contenteditable], [data-cell-interactive]"
+    ) != null
+  )
+}
+
+// Keys belong to a focused in-cell control the same way clicks do: the
+// button, link and checkbox set the mousedown guard exempts must keep its
+// native Enter, Space and Tab, or an in-cell button is keyboard-dead.
+// Clipboard stays on the narrower guard: copying the grid selection while a
+// button happens to hold focus is what a spreadsheet user expects.
+function isDataGridInteractiveKeyTarget(target: EventTarget | null): boolean {
+  return (
+    isDataGridEditableTarget(target) ||
+    (target instanceof Element &&
+      target.closest('button, a, [role="checkbox"]') != null)
+  )
+}
+
+/**
+ * Headless spreadsheet controller: keyboard navigation, clipboard, clear and
+ * the fill-handle drag. Mount once inside `<DataGrid>`, next to the table.
+ * Renders only a hidden anchor; the real listeners attach to the grid's own
+ * body viewport, which also receives focus (container-focus model), so a
+ * virtualized row unmounting can never strand `document.activeElement`.
+ */
+function DataGridCellSelection<TData extends object>({
+  apiRef,
+  clipboard = true,
+  keyboard = true,
+}: {
+  /** Receives the controller's imperative API, e.g. for create-row flows. */
+  apiRef?: RefObject<DataGridCellSelectionApi | null>
+  /** Native copy, cut and paste handling. Defaults to true. */
+  clipboard?: boolean
+  /**
+   * Arrows (with Ctrl/Cmd edge jumps), Home/End, PageUp/PageDown, Enter,
+   * F2, type-to-edit, Tab, Ctrl/Cmd+A, Delete, Escape. Defaults to true.
+   */
+  keyboard?: boolean
+}) {
+  // The context value serves `table` and `props` through getters over the
+  // provider's own refs, so a context object captured at mount keeps handing
+  // out the CURRENT instances; no ref mirror is needed here.
+  const context = useDataGrid<TData>()
+
+  const anchorRef = useRef<HTMLSpanElement | null>(null)
+  // The body viewport, once the wiring effect resolves it; the built-in
+  // editor overlay portals into it so it scrolls with the cells.
+  const [viewportEl, setViewportEl] = useState<HTMLElement | null>(null)
+  const [editorSession, setEditorSession] =
+    useState<DataGridEditorSession | null>(null)
+  const { table } = context
+  const enabled =
+    !!context.props.tableLayout?.cellSelection &&
+    table.atoms.cellSelection != null
+
+  useEffect(() => {
+    if (!enabled) return
+    const anchor = anchorRef.current
+    if (!anchor) return
+
+    const root = (anchor.closest('[data-slot="data-grid"]') ??
+      anchor.parentElement) as HTMLElement | null
+    if (!root) return
+
+    // Split header/body grids render two viewports; the body one owns focus.
+    const viewports = Array.from(
+      root.querySelectorAll<HTMLElement>('[data-slot="data-grid-table-viewport"]')
+    )
+    const viewport =
+      viewports.find((node) =>
+        node.querySelector('[data-slot="data-grid-table-body"]')
+      ) ?? viewports[0]
+    if (!viewport) return
+
+    const getTable = () => context.table
+    const getOnCellsChange = () => context.props.onCellsChange ?? null
+    // "single" collapses every grow gesture to the focused cell.
+    const isRangeSelectionEnabled = () =>
+      context.props.tableLayout?.cellSelectionMode !== "single"
+
+    // The focusable element of the container-focus model. The table carries
+    // role="grid", so putting DOM focus (and aria-activedescendant) on it is
+    // what lets a screen reader follow the focused cell.
+    const focusTarget =
+      viewport.querySelector<HTMLElement>(
+        'table[data-slot="data-grid-table"]'
+      ) ?? viewport
+
+    const scrollTdIntoView = (cell: Element | null) =>
+      // Optional call: jsdom and some embedded contexts ship elements
+      // without scrollIntoView.
+      cell?.scrollIntoView?.({
+        block: "nearest",
+        inline: "nearest",
+        behavior: "instant",
+      })
+
+    // Points assistive tech at the virtually focused cell.
+    const syncActiveDescendant = () => {
+      const cell = viewport.querySelector<HTMLElement>("td[data-cell-focused]")
+      if (cell?.id) focusTarget.setAttribute("aria-activedescendant", cell.id)
+      else focusTarget.removeAttribute("aria-activedescendant")
+    }
+
+    const scrollFocusedIntoView = (
+      targetRowIndex?: number,
+      rowCount?: number,
+      // A Shift-extend grows away from the focused cell, which stays the
+      // anchor; the caller names the range's active corner so the view
+      // follows the growing edge instead of snapping back to the anchor.
+      explicitCell?: { rowId: string; columnId: string }
+    ) => {
+      const queryScrollCell = () =>
+        explicitCell
+          ? viewport.querySelector(
+              `tr[data-row-id="${CSS.escape(explicitCell.rowId)}"] td[data-col-id="${CSS.escape(explicitCell.columnId)}"]`
+            )
+          : viewport.querySelector("td[data-cell-focused]")
+      // After the atom write React still has to commit the data attributes;
+      // rAF lands after that commit. Instant, because the app-level
+      // scroll-smooth would otherwise animate every keystroke.
+      requestAnimationFrame(() => {
+        const cell = queryScrollCell()
+        syncActiveDescendant()
+        if (cell || targetRowIndex == null || !rowCount) {
+          scrollTdIntoView(cell)
+          return
+        }
+        // Virtualization: the jump target is not mounted, so there is no td
+        // to scroll to. The spacer rows keep scrollHeight proportional to
+        // the row count, so estimate the offset, let the virtualizer mount
+        // the region, then finish with a precise nearest-scroll.
+        let scroller: HTMLElement | null = viewport
+        while (scroller && scroller.scrollHeight <= scroller.clientHeight) {
+          scroller = scroller.parentElement
+        }
+        if (!scroller) return
+        scroller.scrollTop =
+          ((targetRowIndex + 0.5) / rowCount) * scroller.scrollHeight -
+          scroller.clientHeight / 2
+        requestAnimationFrame(() => {
+          scrollTdIntoView(queryScrollCell())
+          syncActiveDescendant()
+        })
+      })
+    }
+
+    // Opens an editor for the focused writable cell: the grid's own overlay
+    // for a column with a built-in `control`, the consumer's via
+    // `onCellEditRequest` otherwise, and as a last resort the cell's own
+    // interactive content (activated the way a mouse would). Returns false
+    // when nothing can open so the caller falls back to plain navigation.
+    const requestCellEdit = (initialText?: string): boolean => {
+      const table = getTable()
+      const cell = table.getFocusedCell()
+      if (!cell) return false
+      const cellEdit = getDataGridWritableCellEdit<TData>(
+        cell.column,
+        cell.row.original
+      )
+      if (cellEdit?.control) {
+        const baseline = cellEdit.format
+          ? cellEdit.format(cell.getValue(), cell.row.original)
+          : String(cell.getValue() ?? "")
+        const headerTitle = cell.column.columnDef.meta?.headerTitle
+        const header = cell.column.columnDef.header
+        setEditorSession({
+          rowId: cell.row.id,
+          columnId: cell.column.id,
+          control: cellEdit.control,
+          initialValue: initialText ?? baseline,
+          baseline,
+          label:
+            typeof headerTitle === "string"
+              ? headerTitle
+              : typeof header === "string"
+                ? header
+                : cell.column.id,
+        })
+        return true
+      }
+      const onCellEditRequest = context.props.onCellEditRequest
+      if (cellEdit && onCellEditRequest) {
+        onCellEditRequest({
+          rowId: cell.row.id,
+          columnId: cell.column.id,
+          row: cell.row.original,
+          previousValue: cell.getValue(),
+          initialText,
+        })
+        return true
+      }
+      // Generic activation: a custom control rendered in the cell (a
+      // select trigger, a combobox input, a button) toggles from the
+      // keyboard without any consumer wiring - focus it and click it,
+      // the same gesture the mouse performs. The lookup is ORDERED so an
+      // incidental button (a chip's remove button before a combobox
+      // input) never outranks the cell's primary control.
+      // Deliberate activation only (Enter, F2, double-click): typing a
+      // printable character must never toggle a control it cannot type
+      // into, and there is nowhere to put the character.
+      if (initialText !== undefined) return false
+      const focusedCell = viewport.querySelector("td[data-cell-focused]")
+      const control = focusedCell
+        ? [
+            '[role="combobox"]',
+            "select",
+            "input, textarea",
+            'button, a, [role="checkbox"], [tabindex]:not([tabindex="-1"])',
+          ]
+            .map((candidate) =>
+              focusedCell.querySelector<HTMLElement>(candidate)
+            )
+            .find(Boolean)
+        : null
+      if (!control) return false
+      control.focus()
+      control.click()
+      return true
+    }
+
+    // The imperative surface. A consumer that creates a row cannot focus
+    // its cell through state alone: setFocusedCell needs the row in the
+    // table model, DOM focus needs the focus target, and both race the
+    // commit that mounts the row. One bounded timer retry (timers, unlike
+    // animation frames, run in background tabs) settles all of it in order.
+    let focusRetryTimer: ReturnType<typeof setTimeout> | undefined
+    const focusCell: DataGridCellSelectionApi["focusCell"] = (
+      rowId,
+      columnId,
+      options
+    ) => {
+      // A newer call supersedes any chain still polling for an older row.
+      clearTimeout(focusRetryTimer)
+      let attempts = 12
+      const attempt = () => {
+        // The grid can unmount mid-retry; a stale timer must go quiet.
+        if (!viewport.isConnected) return
+        const cell = viewport.querySelector<HTMLElement>(
+          `tr[data-row-id="${CSS.escape(rowId)}"] td[data-col-id="${CSS.escape(columnId)}"]`
+        )
+        if (!cell) {
+          if (attempts-- > 0) focusRetryTimer = setTimeout(attempt, 32)
+          return
+        }
+        getTable().setFocusedCell(rowId, columnId)
+        focusTarget.focus()
+        // The cell's id is static, so assistive tech can point at it ahead
+        // of the data-cell-focused commit the rAF sync waits for.
+        if (cell.id) focusTarget.setAttribute("aria-activedescendant", cell.id)
+        scrollTdIntoView(cell)
+        if (!options?.edit) return
+        // The built-in overlay measures td[data-cell-focused], so the edit
+        // request waits for that attribute to land.
+        let editAttempts = 12
+        const attemptEdit = () => {
+          if (!cell.isConnected) return
+          if (cell.hasAttribute("data-cell-focused")) requestCellEdit()
+          else if (editAttempts-- > 0) {
+            focusRetryTimer = setTimeout(attemptEdit, 32)
+          }
+        }
+        attemptEdit()
+      }
+      attempt()
+    }
+    const clearSelection = () => {
+      getTable().resetCellSelection(true)
+      requestAnimationFrame(syncActiveDescendant)
+    }
+    const scrollToCell = (rowId: string, columnId: string) => {
+      scrollTdIntoView(
+        viewport.querySelector(
+          `tr[data-row-id="${CSS.escape(rowId)}"] td[data-col-id="${CSS.escape(columnId)}"]`
+        )
+      )
+    }
+    if (apiRef) apiRef.current = { focusCell, clearSelection, scrollToCell }
+
+    // Resolves jump targets (Home, End, Ctrl+Arrows, PageUp/PageDown) in the
+    // feature's display-index space and lands them through the range API:
+    // plain jumps collapse to the target cell, Shift jumps keep the active
+    // range's opposite corner as the anchor, the Excel model.
+    const jumpFocus = (
+      rowTarget: "first" | "last" | "same" | { delta: number },
+      columnTarget: "first" | "last" | "same",
+      extend: boolean
+    ): boolean => {
+      const table = getTable()
+      const focused = table.getFocusedCell()
+      if (!focused) return false
+      const rows = table.getRowsInDisplayOrder()
+      const allColumns = getDataGridDisplayOrderedColumns(table)
+      const selectable = allColumns.filter(
+        (column) => column.columnDef.enableCellSelection !== false
+      )
+      if (!rows.length || !selectable.length) return false
+      const rowIndex = focused.row.getDisplayIndex()
+      const targetRowIndex =
+        rowTarget === "first"
+          ? 0
+          : rowTarget === "last"
+            ? rows.length - 1
+            : rowTarget === "same"
+              ? rowIndex
+              : Math.min(
+                  rows.length - 1,
+                  Math.max(0, rowIndex + rowTarget.delta)
+                )
+      // Pagination renders a window of the display order; walk the target
+      // back toward the focus until it lands on a rendered row, so a jump
+      // can never focus an off-page row the view cannot show. DOM rows
+      // join the set so pinned rows outside the page slice stay reachable.
+      let clampedRowIndex = targetRowIndex
+      // With the whole display order in the page slice nothing is off-page
+      // and the clamp cannot move, so skip building the id set.
+      if (table.getRowModel().rows.length !== rows.length) {
+        const rendered = new Set<string | null>(
+          table.getRowModel().rows.map((row: { id: string }) => row.id)
+        )
+        for (const rowEl of Array.from(
+          viewport.querySelectorAll("tbody tr[data-row-id]")
+        )) {
+          rendered.add(rowEl.getAttribute("data-row-id"))
+        }
+        const step = clampedRowIndex >= rowIndex ? -1 : 1
+        while (
+          clampedRowIndex !== rowIndex &&
+          rows[clampedRowIndex] &&
+          !rendered.has(rows[clampedRowIndex].id)
+        ) {
+          clampedRowIndex += step
+        }
+      }
+      const targetRow = rows[clampedRowIndex]
+      const targetColumn =
+        columnTarget === "first"
+          ? selectable[0]
+          : columnTarget === "last"
+            ? selectable[selectable.length - 1]
+            : focused.column
+      if (!targetRow || !targetColumn) return false
+      if (extend) {
+        const bound = getDataGridActiveBound(table)
+        const columnIndex = allColumns.findIndex(
+          (column) => column.id === focused.column.id
+        )
+        let anchorRowId = focused.row.id
+        let anchorColumnId = focused.column.id
+        if (bound) {
+          anchorRowId =
+            rows[
+              rowIndex === bound.minRowIndex
+                ? bound.maxRowIndex
+                : bound.minRowIndex
+            ]?.id ?? anchorRowId
+          anchorColumnId =
+            allColumns[
+              columnIndex === bound.minColumnIndex
+                ? bound.maxColumnIndex
+                : bound.minColumnIndex
+            ]?.id ?? anchorColumnId
+        }
+        table.selectCellRange(
+          {
+            anchorRowId,
+            anchorColumnId,
+            focusRowId: targetRow.id,
+            focusColumnId: targetColumn.id,
+          },
+          { mode: "replace" }
+        )
+      } else {
+        table.setFocusedCell(targetRow.id, targetColumn.id)
+      }
+      scrollFocusedIntoView(
+        clampedRowIndex,
+        rows.length,
+        // The extend keeps focus on the anchor; follow the jump target.
+        extend
+          ? { rowId: targetRow.id, columnId: targetColumn.id }
+          : undefined
+      )
+      return true
+    }
+
+    // One visual-space focus step with the feature's move as the fallback
+    // for unresolvable positions; at an edge the focus stays put.
+    const moveFocusVisual = (
+      direction: "up" | "down" | "left" | "right"
+    ): void => {
+      const table = getTable()
+      const focused = table.getFocusedCell()
+      const target = focused
+        ? getDataGridStepTarget(
+            table,
+            viewport,
+            { rowId: focused.row.id, columnId: focused.column.id },
+            direction
+          )
+        : null
+      if (target === "edge") return
+      if (target) {
+        table.setFocusedCell(target.rowId, target.columnId)
+        return
+      }
+      table.moveCellSelection(direction)
+    }
+
+    // One viewport's worth of rows for PageUp/PageDown, measured from the
+    // live layout; 10 when nothing is measurable (jsdom). Data rows only:
+    // the virtual table's spacer rows carry the whole scroll offset as
+    // height and would collapse the page size to a single row.
+    const getPageJumpSize = (): number => {
+      const row = viewport.querySelector("tbody tr[data-row-id]")
+      // The nearest ancestor that actually scrolls; in the scroll-area
+      // layout the viewport's parent is a full-height content wrapper
+      // whose clientHeight would make the page span the whole table.
+      let scroller: HTMLElement | null = viewport
+      while (scroller && scroller.scrollHeight <= scroller.clientHeight) {
+        scroller = scroller.parentElement
+      }
+      const rowHeight = row?.getBoundingClientRect().height || 0
+      const viewHeight = scroller?.clientHeight || viewport.clientHeight
+      if (!rowHeight || !viewHeight) return 10
+      return Math.max(1, Math.floor(viewHeight / rowHeight) - 1)
+    }
+
+    // The rows appended after the data rows: the add-row affordance and a
+    // consumer appendRow draft. Positional, because an id-less tr is not
+    // enough - expanded-detail rows interleave BETWEEN data rows and the
+    // empty-state row stands alone, and neither belongs to this region.
+    // Virtual spacer rows are aria-hidden and never match.
+    const getAppendedRows = (): HTMLElement[] => {
+      const body = viewport.querySelector("tbody")
+      const appended: HTMLElement[] = []
+      // Backwards from the end, stopping at the first data row: O(appended)
+      // instead of an array of every rendered row per keystroke.
+      let rowEl = body?.lastElementChild
+      while (rowEl && !rowEl.hasAttribute("data-row-id")) {
+        if (
+          rowEl instanceof HTMLElement &&
+          !rowEl.hasAttribute("aria-hidden")
+        ) {
+          appended.unshift(rowEl)
+        }
+        rowEl = rowEl.previousElementSibling
+      }
+      return appended
+    }
+
+    const focusFirstIn = (row: HTMLElement | undefined): boolean => {
+      const focusable = row?.querySelector<HTMLElement>(
+        'button:not([disabled]), input:not([disabled]), [tabindex]:not([tabindex="-1"])'
+      )
+      if (!focusable) return false
+      focusable.focus()
+      // A control that refuses focus (hidden, inert) must not report
+      // success, or the arrow key that called this dead-ends.
+      return row!.ownerDocument.activeElement === focusable
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.defaultPrevented) return
+
+      // Unified keyboard for the appended region: ArrowDown/ArrowUp walk
+      // between its rows, and ArrowUp from its first row returns to the
+      // grid's cell navigation. Every other key stays native there.
+      const appendedRow =
+        event.target instanceof Element
+          ? (event.target.closest(
+              "tbody > tr:not([data-row-id])"
+            ) as HTMLElement | null)
+          : null
+      if (appendedRow && viewport.contains(appendedRow)) {
+        const appended = getAppendedRows()
+        const index = appended.indexOf(appendedRow)
+        // An id-less row that is NOT appended (expanded detail content,
+        // the empty-state row) keeps every key native.
+        if (index === -1) return
+        if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return
+        if (event.key === "ArrowDown") {
+          if (focusFirstIn(appended[index + 1])) event.preventDefault()
+          return
+        }
+        if (index > 0 && focusFirstIn(appended[index - 1])) {
+          event.preventDefault()
+          return
+        }
+        // Back into the grid, on whatever cell was focused last.
+        focusTarget.focus()
+        syncActiveDescendant()
+        event.preventDefault()
+        return
+      }
+
+      if (isDataGridInteractiveKeyTarget(event.target)) {
+        // The ARIA grid pattern's exit gesture: Escape on an in-cell
+        // control hands DOM focus back to the grid so navigation resumes.
+        // A control that consumed the key first (closing its own popup)
+        // never lets it reach here unprevented, and portal-rendered
+        // popups keep their Escape entirely outside the viewport.
+        if (event.key === "Escape") {
+          const cell = (event.target as Element).closest?.("td[data-col-id]")
+          if (cell && viewport.contains(cell)) {
+            event.preventDefault()
+            event.stopPropagation()
+            focusTarget.focus()
+            syncActiveDescendant()
+          }
+        }
+        return
+      }
+      const table = getTable()
+      const rtl = getComputedStyle(viewport).direction === "rtl"
+      const horizontal = (direction: "left" | "right") =>
+        rtl ? (direction === "left" ? "right" : "left") : direction
+
+      // Ahead of the switch so plain letters still reach the type-to-edit
+      // fall-through below. Matched by code as well as key, so non-Latin
+      // layouts (where the key is the layout's own character) still work.
+      if (
+        (event.key === "a" || event.key === "A" || event.code === "KeyA") &&
+        (event.metaKey || event.ctrlKey) &&
+        // AltGr arrives as Ctrl+Alt; that chord types a character on
+        // central-European layouts and is not a select-all.
+        !event.altKey
+      ) {
+        if (isRangeSelectionEnabled()) {
+          table.selectAllCells()
+          // Select-all moves the feature's focus to the range corner,
+          // which can sit off-page; keep assistive tech pointed right.
+          requestAnimationFrame(syncActiveDescendant)
+        }
+        event.preventDefault()
+        return
+      }
+
+      // Explicit copy and cut chords; see writeSelectionToClipboard for
+      // why the native copy event cannot carry these. Paste stays on the
+      // native event, which browsers do fire at the focused element.
+      if ((event.metaKey || event.ctrlKey) && !event.altKey && clipboard) {
+        const isCopy =
+          event.key === "c" || event.key === "C" || event.code === "KeyC"
+        const isCut =
+          event.key === "x" || event.key === "X" || event.code === "KeyX"
+        if (isCopy || isCut) {
+          event.preventDefault()
+          void writeSelectionToClipboard().then((written) => {
+            if (!written) return
+            context.props.onCellsCopy?.({ ...written, cut: isCut })
+            if (!isCut) return
+            const onCellsChange = getOnCellsChange()
+            if (!onCellsChange) return
+            const details = buildDataGridClearDetails<TData>(
+              getTable(),
+              "cut",
+              true,
+              viewport
+            )
+            if (details) onCellsChange(details)
+          })
+          return
+        }
+      }
+
+      switch (event.key) {
+        case "ArrowUp":
+        case "ArrowDown":
+        case "ArrowLeft":
+        case "ArrowRight": {
+          const direction =
+            event.key === "ArrowUp"
+              ? ("up" as const)
+              : event.key === "ArrowDown"
+                ? ("down" as const)
+                : horizontal(event.key === "ArrowLeft" ? "left" : "right")
+          if (event.metaKey || event.ctrlKey) {
+            // Ctrl/Cmd+Arrow jumps to the grid edge in that direction.
+            const jumped =
+              direction === "up"
+                ? jumpFocus("first", "same", event.shiftKey && isRangeSelectionEnabled())
+                : direction === "down"
+                  ? jumpFocus("last", "same", event.shiftKey && isRangeSelectionEnabled())
+                  : jumpFocus(
+                      "same",
+                      direction === "left" ? "first" : "last",
+                      event.shiftKey && isRangeSelectionEnabled()
+                    )
+            if (jumped) event.preventDefault()
+            return
+          }
+          // ArrowDown on the last rendered row steps into the appended
+          // region (a draft row, or the add-row affordance), keeping one
+          // keyboard model across the whole table.
+          if (direction === "down" && !event.shiftKey) {
+            const focused = table.getFocusedCell()
+            const renderedRows = viewport.querySelectorAll(
+              "tbody tr[data-row-id]"
+            )
+            const lastRenderedId = renderedRows[
+              renderedRows.length - 1
+            ]?.getAttribute("data-row-id")
+            if (
+              focused &&
+              lastRenderedId &&
+              focused.row.id === lastRenderedId &&
+              focusFirstIn(getAppendedRows()[0])
+            ) {
+              event.preventDefault()
+              return
+            }
+          }
+          if (event.shiftKey && isRangeSelectionEnabled()) {
+            const corner = extendDataGridSelection(table, viewport, direction)
+            event.preventDefault()
+            scrollFocusedIntoView(undefined, undefined, corner ?? undefined)
+            return
+          }
+          // Plain arrows step in visual space so navigation crosses
+          // pinned rows and pagination windows the feature's own move
+          // cannot resolve; at a visual edge the focus stays put.
+          const focused = table.getFocusedCell()
+          const target = focused
+            ? getDataGridStepTarget(
+                table,
+                viewport,
+                { rowId: focused.row.id, columnId: focused.column.id },
+                direction
+              )
+            : null
+          if (target === "edge") {
+            event.preventDefault()
+            return
+          }
+          if (target) {
+            table.setFocusedCell(target.rowId, target.columnId)
+            event.preventDefault()
+            scrollFocusedIntoView()
+            return
+          }
+          table.moveCellSelection(direction)
+          event.preventDefault()
+          scrollFocusedIntoView()
+          return
+        }
+        case "Home":
+        case "End": {
+          // Home/End: row start or end; with Ctrl/Cmd, the grid's corners.
+          const edge = event.key === "Home" ? ("first" as const) : ("last" as const)
+          const jumped =
+            event.metaKey || event.ctrlKey
+              ? jumpFocus(edge, edge, event.shiftKey && isRangeSelectionEnabled())
+              : jumpFocus("same", edge, event.shiftKey && isRangeSelectionEnabled())
+          if (jumped) event.preventDefault()
+          return
+        }
+        case "PageUp":
+        case "PageDown": {
+          const delta = (event.key === "PageUp" ? -1 : 1) * getPageJumpSize()
+          if (jumpFocus({ delta }, "same", event.shiftKey && isRangeSelectionEnabled())) {
+            event.preventDefault()
+          }
+          return
+        }
+        case "Enter": {
+          // The Notion/Airtable flow: Enter opens the editor when one is
+          // wired; the Excel move-down stays the fallback.
+          if (!event.shiftKey && requestCellEdit()) {
+            event.preventDefault()
+            return
+          }
+          moveFocusVisual(event.shiftKey ? "up" : "down")
+          event.preventDefault()
+          scrollFocusedIntoView()
+          return
+        }
+        case "F2": {
+          if (requestCellEdit()) event.preventDefault()
+          return
+        }
+        case "Tab": {
+          const before = table.getFocusedCell()
+          // Logical directions, no RTL swap: Tab means "next cell" in both
+          // reading directions, exactly like DOM tab order.
+          moveFocusVisual(event.shiftKey ? "left" : "right")
+          const after = table.getFocusedCell()
+          // Trap Tab only while it moved; at the edges focus leaves the grid,
+          // which keyboard users need to escape it at all.
+          if (after && after.id !== before?.id) {
+            event.preventDefault()
+            scrollFocusedIntoView()
+          }
+          return
+        }
+        case "Delete":
+        case "Backspace": {
+          const onCellsChange = getOnCellsChange()
+          if (!onCellsChange) return
+          const details = buildDataGridClearDetails<TData>(
+            table,
+            "clear",
+            false,
+            viewport
+          )
+          if (details) onCellsChange(details)
+          event.preventDefault()
+          return
+        }
+        case "Escape": {
+          // Consume the key only while it has a selection to clear, so a
+          // grid inside a dialog still lets Escape close the dialog.
+          if (table.getCellSelectionBounds().length) {
+            table.resetCellSelection(true)
+            // The focused-cell attribute is gone after the commit;
+            // aria-activedescendant must not keep naming it.
+            requestAnimationFrame(syncActiveDescendant)
+            event.preventDefault()
+            event.stopPropagation()
+          }
+          return
+        }
+      }
+
+      // Space on a cell whose content is a checkbox toggles it, the
+      // row-select idiom, so the selection column works by keyboard too.
+      if (event.key === " ") {
+        const checkbox = viewport
+          .querySelector("td[data-cell-focused]")
+          ?.querySelector<HTMLElement>(
+            '[role="checkbox"], input[type="checkbox"]'
+          )
+        if (checkbox) {
+          checkbox.click()
+          event.preventDefault()
+          return
+        }
+      }
+
+      // Type-to-edit: a printable character on the focused cell opens the
+      // editor seeded with it, replacing the value the way Notion and
+      // Airtable do. Plain Ctrl/Cmd chords stay shortcuts, but Ctrl+Alt is
+      // AltGr and bare Alt is the macOS Option layer - both type characters.
+      if (
+        event.key.length === 1 &&
+        !event.metaKey &&
+        !(event.ctrlKey && !event.altKey) &&
+        requestCellEdit(event.key)
+      ) {
+        event.preventDefault()
+        return
+      }
+
+      // Space that opened nothing (read-only cell) must not scroll the page
+      // out from under the focused cell.
+      if (event.key === " " && table.getFocusedCell()) {
+        event.preventDefault()
+      }
+    }
+
+    // Writes the active region to the system clipboard in both flavors.
+    // Needed because a native copy event only fires for a text selection
+    // or an editable target, and a focused grid is neither - Cmd/Ctrl+C
+    // would silently do nothing on macOS, Windows and Linux alike. The
+    // async API needs a secure context; the execCommand fallback covers
+    // the rest with the TSV flavor alone.
+    const writeSelectionToClipboard = async (): Promise<{
+      text: string
+      grid: string[][]
+    } | null> => {
+      const grid = getDataGridActiveRegionGrid(getTable(), viewport)
+      if (!grid) return null
+      const text = serializeDataGridClipboardText(grid)
+      try {
+        if (
+          typeof ClipboardItem !== "undefined" &&
+          navigator.clipboard?.write
+        ) {
+          await navigator.clipboard.write([
+            new ClipboardItem({
+              "text/plain": new Blob([text], { type: "text/plain" }),
+              "text/html": new Blob([renderDataGridClipboardHtml(grid)], {
+                type: "text/html",
+              }),
+            }),
+          ])
+          return { text, grid }
+        }
+        if (navigator.clipboard?.writeText) {
+          await navigator.clipboard.writeText(text)
+          return { text, grid }
+        }
+      } catch {
+        // Denied or unavailable; the legacy path below still applies.
+      }
+      const doc = viewport.ownerDocument
+      const scratch = doc.createElement("textarea")
+      scratch.value = text
+      scratch.style.position = "fixed"
+      scratch.style.opacity = "0"
+      doc.body.appendChild(scratch)
+      scratch.select()
+      let copied = false
+      try {
+        copied = doc.execCommand("copy")
+      } catch {
+        copied = false
+      }
+      scratch.remove()
+      focusTarget.focus()
+      return copied ? { text, grid } : null
+    }
+
+    const copySelection = (event: ClipboardEvent, cut: boolean): boolean => {
+      const grid = getDataGridActiveRegionGrid(getTable(), viewport)
+      if (!grid || !event.clipboardData) return false
+      event.preventDefault()
+      const text = serializeDataGridClipboardText(grid)
+      event.clipboardData.setData("text/plain", text)
+      event.clipboardData.setData("text/html", renderDataGridClipboardHtml(grid))
+      context.props.onCellsCopy?.({ text, grid, cut })
+      return true
+    }
+
+    const handleCopy = (event: ClipboardEvent) => {
+      if (isDataGridEditableTarget(event.target)) return
+      copySelection(event, false)
+    }
+
+    const handleCut = (event: ClipboardEvent) => {
+      if (isDataGridEditableTarget(event.target)) return
+      if (!copySelection(event, true)) return
+      const onCellsChange = getOnCellsChange()
+      if (!onCellsChange) return
+      const details = buildDataGridClearDetails<TData>(
+        getTable(),
+        "cut",
+        true,
+        viewport
+      )
+      if (details) onCellsChange(details)
+    }
+
+    const handlePaste = (event: ClipboardEvent) => {
+      if (isDataGridEditableTarget(event.target)) return
+      const onCellsChange = getOnCellsChange()
+      if (!onCellsChange) return
+      const text = event.clipboardData?.getData("text/plain")
+      if (!text) return
+      event.preventDefault()
+      const table = getTable()
+      const result = buildDataGridPasteDetails<TData>(
+        table,
+        parseDataGridClipboardText(text),
+        viewport
+      )
+      if (!result) return
+      onCellsChange(result.details)
+      // The pasted region becomes the selection, the documented contract;
+      // single mode keeps just the focused cell instead.
+      if (isRangeSelectionEnabled()) {
+        selectDataGridRegion(table, result.target)
+      }
+    }
+
+    // Custom-control cells follow the same two-step gesture as editor
+    // cells: the first click on an UNFOCUSED cell only focuses it, the
+    // second activates the control, so moving the focus around can never
+    // fire actions. Radix triggers open on pointerdown and Base UI ones
+    // on click, so the press is intercepted at both; checkboxes keep
+    // their one-click toggle (the row-select idiom), data-cell-interactive
+    // widgets own all their gestures, and single-click edit mode skips
+    // the interception outright.
+    let pressedUnfocusedControl = false
+    const getTwoStepControl = (target: EventTarget | null): Element | null => {
+      if (!(target instanceof Element)) return null
+      if (target.closest("[data-cell-interactive]")) return null
+      if (target.closest('[role="checkbox"], input[type="checkbox"]')) {
+        return null
+      }
+      // Opt-in for widgets whose ACTIVE surface is bigger than any generic
+      // selector can know - a combobox whose whole blank chips strip opens
+      // it, a canvas editor. Marking the wrapper data-cell-control makes a
+      // press anywhere on it two-step, exactly like a bare button.
+      const marked = target.closest("[data-cell-control]")
+      if (marked) return marked
+      return target.closest(
+        'button, a, select, input, textarea, [contenteditable], [role="combobox"]'
+      )
+    }
+    const handleControlPointerDown = (event: PointerEvent) => {
+      pressedUnfocusedControl = false
+      if (event.button !== 0) return
+      if (event.shiftKey || event.ctrlKey || event.metaKey) return
+      if (context.props.tableLayout?.cellEditMode === "click") return
+      const control = getTwoStepControl(event.target)
+      const cell = control?.closest("td[data-col-id]")
+      if (!control || !cell || !viewport.contains(cell)) return
+      if (cell.hasAttribute("data-cell-focused")) return
+      const column = getTable().getColumn(
+        cell.getAttribute("data-col-id") ?? ""
+      )
+      if (!column || column.columnDef.enableCellSelection === false) return
+      pressedUnfocusedControl = true
+      // Stops a Radix trigger's pointerdown open before React's root
+      // delegation sees it; the mouse events that focus the cell ride on.
+      event.stopPropagation()
+    }
+    const handleControlClick = (event: MouseEvent) => {
+      if (!pressedUnfocusedControl) return
+      pressedUnfocusedControl = false
+      // Swallows the activation click a Base UI trigger listens for.
+      event.preventDefault()
+      event.stopPropagation()
+    }
+    const handleControlMouseDown = (event: MouseEvent) => {
+      if (!pressedUnfocusedControl) return
+      // A Base UI trigger opens on the React-delegated mousedown, and all
+      // root-delegated handlers die together when the event stops here -
+      // including the td's own focus logic, so the selection start runs
+      // imperatively: same feature handler, same drag session.
+      event.stopPropagation()
+      event.preventDefault()
+      const cell = (event.target as Element | null)?.closest?.(
+        "td[data-col-id]"
+      )
+      const rowId = cell
+        ?.closest("tr[data-row-id]")
+        ?.getAttribute("data-row-id")
+      const columnId = cell?.getAttribute("data-col-id")
+      if (!rowId || !columnId) return
+      const tableNow = getTable()
+      const cellApi = tableNow
+        .getRowsInDisplayOrder()
+        .find((row) => row.id === rowId)
+        ?.getAllCellsByColumnId()[columnId]
+      if (!cellApi) return
+      if (isRangeSelectionEnabled()) {
+        cellApi.getSelectionStartHandler()(event)
+      } else {
+        tableNow.setFocusedCell(rowId, columnId)
+      }
+      focusTarget.focus()
+      requestAnimationFrame(syncActiveDescendant)
+    }
+
+    // Drag-to-select outranks in-cell controls: when a drag grew the
+    // range, the click that fires on release is swallowed in capture so a
+    // trigger under the pointer never opens. The selection key comparison
+    // is what distinguishes a drag from a motionless click made while a
+    // multi-cell selection already exists (a press on "+ Add row" or an
+    // in-cell control changes nothing, and its click must go through).
+    let dragStartedOnCell = false
+    let dragStartSelectionKey = ""
+    const getSelectionKey = () => {
+      const table = getTable()
+      const bounds = table.getCellSelectionBounds()
+      const bound = bounds[bounds.length - 1]
+      return `${table.getSelectedCellCount()}:${bounds.length}:${
+        bound
+          ? `${bound.minRowIndex},${bound.minColumnIndex},${bound.maxRowIndex},${bound.maxColumnIndex}`
+          : ""
+      }`
+    }
+    const handleDragMouseUp = () => {
+      const wasDrag =
+        dragStartedOnCell &&
+        getTable().getSelectedCellCount() > 1 &&
+        getSelectionKey() !== dragStartSelectionKey
+      dragStartedOnCell = false
+      viewport.removeAttribute("data-cell-selecting")
+      if (!wasDrag) return
+      const squelch = (clickEvent: MouseEvent) => {
+        clickEvent.stopPropagation()
+        clickEvent.preventDefault()
+      }
+      viewport.addEventListener("click", squelch, { capture: true })
+      setTimeout(
+        () => viewport.removeEventListener("click", squelch, true),
+        0
+      )
+    }
+
+    const handleMouseDown = (event: MouseEvent) => {
+      if (event.button !== 0) return
+      // The cell a click focuses reaches assistive tech once React commits.
+      requestAnimationFrame(syncActiveDescendant)
+      const target = event.target as Element | null
+      // A modifier press is a selection gesture all the way through, the
+      // Sheets contract: extending must not hand the keyboard to whatever
+      // control sits under the pointer, or the follow-up Shift+arrows land
+      // in a date button or a combobox input instead of growing the range.
+      // The extension itself runs through the cell's own React handlers, so
+      // the event must NOT be defaultPrevented - the delegated handlers
+      // treat that as consumed and the extension never happens. Only the
+      // browser's focus default is unwanted; it runs after the listeners,
+      // so the grid reclaims focus one task later.
+      if (
+        (event.shiftKey || event.metaKey || event.ctrlKey) &&
+        isRangeSelectionEnabled() &&
+        target?.closest?.("td[data-col-id]")
+      ) {
+        setTimeout(() => focusTarget.focus(), 0)
+      }
+      // Any td press can become a drag; the squelch only arms when the
+      // range actually grew by release time. The attribute hides the fill
+      // handle for the session, so its overhang never sits in the drag
+      // path or churns from cell to cell while the range grows.
+      dragStartedOnCell = !!target?.closest?.("td")
+      if (dragStartedOnCell) {
+        dragStartSelectionKey = getSelectionKey()
+        viewport.setAttribute("data-cell-selecting", "")
+      }
+      if (!target?.closest?.('[data-slot="data-grid-cell-fill-handle"]')) return
+      // Ahead of React's root delegation, so the td underneath never starts a
+      // plain range drag from the handle.
+      event.preventDefault()
+      event.stopPropagation()
+      startDataGridFillSession<TData>({
+        table: getTable(),
+        viewport,
+        onCellsChange: getOnCellsChange(),
+      })
+    }
+
+    // Single-click editing, the opt-in mode: a plain click that landed
+    // on the (now) focused cell opens its editor immediately. Drags were
+    // squelched in capture before this bubble listener, and modifier
+    // clicks are selection gestures.
+    const handleClickToEdit = (event: MouseEvent) => {
+      if (context.props.tableLayout?.cellEditMode !== "click") return
+      if (event.shiftKey || event.ctrlKey || event.metaKey) return
+      if (isDataGridInteractiveKeyTarget(event.target)) return
+      const cell = (event.target as HTMLElement | null)?.closest?.("td")
+      if (!cell?.hasAttribute("data-cell-focused")) return
+      requestCellEdit()
+    }
+
+    // Double-click opens the editor on the cell the first click focused,
+    // matching Sheets. Interactive content keeps its own double-clicks, and
+    // the clicked cell must BE the focused one, or a double-click on a
+    // non-selectable cell would edit whichever cell held focus before.
+    const handleDoubleClick = (event: MouseEvent) => {
+      if (isDataGridInteractiveKeyTarget(event.target)) return
+      const target = event.target as HTMLElement | null
+      const cell = target?.closest?.("td")
+      if (!cell?.hasAttribute("data-cell-focused")) return
+      requestCellEdit()
+    }
+
+    const previousTabIndex = focusTarget.getAttribute("tabindex")
+    const previousOutline = focusTarget.style.outline
+    if (keyboard) {
+      focusTarget.tabIndex = 0
+      // The focused CELL ring is the indicator; the browser's outline around
+      // the whole grid on focus() would double it.
+      focusTarget.style.outline = "none"
+      viewport.addEventListener("keydown", handleKeyDown)
+    }
+    if (clipboard) {
+      viewport.addEventListener("copy", handleCopy)
+      viewport.addEventListener("cut", handleCut)
+      viewport.addEventListener("paste", handlePaste)
+    }
+    viewport.addEventListener("pointerdown", handleControlPointerDown)
+    viewport.addEventListener("mousedown", handleControlMouseDown)
+    viewport.addEventListener("click", handleControlClick)
+    viewport.addEventListener("mousedown", handleMouseDown)
+    viewport.addEventListener("click", handleClickToEdit)
+    viewport.addEventListener("dblclick", handleDoubleClick)
+    viewport.ownerDocument.addEventListener("mouseup", handleDragMouseUp)
+    // Selection-change notifications, read through the context getter so
+    // the latest callback fires without re-running this effect. The
+    // snapshot is only built when a callback is actually wired.
+    const toBound = (bound: {
+      minRowIndex: number
+      maxRowIndex: number
+      minColumnIndex: number
+      maxColumnIndex: number
+    }) => ({
+      minRowIndex: bound.minRowIndex,
+      maxRowIndex: bound.maxRowIndex,
+      minColumnIndex: bound.minColumnIndex,
+      maxColumnIndex: bound.maxColumnIndex,
+    })
+    const selectionSubscription = table.atoms.cellSelection?.subscribe(() => {
+      const onCellSelectionChange = context.props.onCellSelectionChange
+      if (!onCellSelectionChange) return
+      const tableNow = getTable()
+      const focusedCell = tableNow.getFocusedCell()
+      const activeBound = getDataGridActiveBound(tableNow)
+      onCellSelectionChange({
+        focused: focusedCell
+          ? { rowId: focusedCell.row.id, columnId: focusedCell.column.id }
+          : null,
+        bounds: tableNow.getCellSelectionBounds().map(toBound),
+        activeBound: activeBound ? toBound(activeBound) : null,
+        visibleCellCount: getDataGridVisibleSelectedCellCount(
+          tableNow,
+          viewport
+        ),
+      })
+    })
+    setViewportEl(viewport)
+
+    return () => {
+      if (keyboard) {
+        if (previousTabIndex === null) focusTarget.removeAttribute("tabindex")
+        else focusTarget.setAttribute("tabindex", previousTabIndex)
+        focusTarget.style.outline = previousOutline
+        focusTarget.removeAttribute("aria-activedescendant")
+        viewport.removeEventListener("keydown", handleKeyDown)
+      }
+      if (clipboard) {
+        viewport.removeEventListener("copy", handleCopy)
+        viewport.removeEventListener("cut", handleCut)
+        viewport.removeEventListener("paste", handlePaste)
+      }
+      viewport.removeEventListener("pointerdown", handleControlPointerDown)
+      viewport.removeEventListener("mousedown", handleControlMouseDown)
+      viewport.removeEventListener("click", handleControlClick)
+      viewport.removeEventListener("mousedown", handleMouseDown)
+      viewport.removeEventListener("click", handleClickToEdit)
+      viewport.removeEventListener("dblclick", handleDoubleClick)
+      viewport.ownerDocument.removeEventListener("mouseup", handleDragMouseUp)
+      viewport.removeAttribute("data-cell-selecting")
+      selectionSubscription?.unsubscribe()
+      clearTimeout(focusRetryTimer)
+      if (apiRef) apiRef.current = null
+      setViewportEl(null)
+      setEditorSession(null)
+    }
+    // Context getters serve fresh table/props inside every handler, so the
+    // effect re-runs only when the table itself is replaced. apiRef is only
+    // read and written here: keeping it out of the deps means an inline ref
+    // object cannot tear the listeners down every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, keyboard, clipboard, table.store])
+
+  // The editor overlay covers the cell but not the fill handle's
+  // straddling half, which would poke out beneath it; the viewport flags
+  // the session so the handle hides, as it does during a drag.
+  useEffect(() => {
+    if (!viewportEl || !editorSession) return
+    viewportEl.setAttribute("data-cell-editing", "")
+    return () => viewportEl.removeAttribute("data-cell-editing")
+  }, [viewportEl, editorSession])
+
+  // Closing an editor the user finished with keys hands focus back to the
+  // viewport so navigation continues where the edit left off; a commit can
+  // advance first (Tab across, and Enter down or up when
+  // cellEditEnterAdvance opts into the Sheets flow). A blur-initiated close
+  // must NOT refocus: the browser already moved focus where the user
+  // clicked, and yanking it back would reroute their next keystrokes into
+  // the grid.
+  const closeEditorSession = (
+    advance: DataGridEditorAdvance,
+    refocus = true
+  ) => {
+    setEditorSession(null)
+    if (advance) {
+      // Same visual-space step as keyboard navigation, so a commit on a
+      // pinned row advances like any other row.
+      const tableNow = context.table
+      const focused = tableNow.getFocusedCell()
+      const target =
+        focused && viewportEl
+          ? getDataGridStepTarget(
+              tableNow,
+              viewportEl,
+              { rowId: focused.row.id, columnId: focused.column.id },
+              advance
+            )
+          : null
+      if (target && target !== "edge") {
+        tableNow.setFocusedCell(target.rowId, target.columnId)
+      } else if (!target) {
+        tableNow.moveCellSelection(advance)
+      }
+    }
+    if (!refocus) return
+    requestAnimationFrame(() => {
+      const focusEl =
+        viewportEl?.querySelector<HTMLElement>(
+          'table[data-slot="data-grid-table"]'
+        ) ?? viewportEl
+      focusEl?.focus()
+      const cell = viewportEl?.querySelector<HTMLElement>(
+        "td[data-cell-focused]"
+      )
+      if (cell?.id) focusEl?.setAttribute("aria-activedescendant", cell.id)
+      cell?.scrollIntoView?.({
+        block: "nearest",
+        inline: "nearest",
+        behavior: "instant",
+      })
+    })
+  }
+
+  // An unchanged commit dispatches nothing, the Excel model; a parse
+  // rejection reports through the batch's rejected list instead of writing.
+  const commitEditorSession = (
+    raw: string,
+    advance: DataGridEditorAdvance,
+    refocus = true
+  ) => {
+    const session = editorSession
+    closeEditorSession(advance, refocus)
+    const onCellsChange = context.props.onCellsChange
+    if (!session || !onCellsChange || raw === session.baseline) return
+    const tableNow = context.table
+    const row = tableNow
+      .getRowsInDisplayOrder()
+      .find((candidate) => candidate.id === session.rowId)
+    const column = tableNow.getColumn(session.columnId)
+    const cellEdit =
+      column && row
+        ? getDataGridWritableCellEdit<TData>(column, row.original)
+        : null
+    if (!row || !column || !cellEdit) return
+    const previousValue = row.getAllCellsByColumnId()[column.id]?.getValue()
+    let value: unknown = raw
+    if (cellEdit.parse) {
+      const parsed = cellEdit.parse(raw, row.original)
+      if (parsed === undefined) {
+        onCellsChange({
+          source: "edit",
+          changes: [],
+          rejected: [
+            {
+              rowId: session.rowId,
+              columnId: session.columnId,
+              raw,
+              reason: "invalid",
+            },
+          ],
+        })
+        return
+      }
+      value = parsed
+    }
+    onCellsChange({
+      source: "edit",
+      changes: [
+        {
+          rowId: session.rowId,
+          columnId: session.columnId,
+          row: row.original,
+          previousValue,
+          value,
+        },
+      ],
+      rejected: [],
+    })
+  }
+
+  return (
+    <>
+      <span ref={anchorRef} hidden data-slot="data-grid-cell-selection" />
+      {enabled && viewportEl && editorSession ? (
+        <DataGridCellEditorOverlay
+          key={`${editorSession.rowId}:${editorSession.columnId}`}
+          viewport={viewportEl}
+          session={editorSession}
+          enterAdvance={context.props.tableLayout?.cellEditEnterAdvance === true}
+          onCommit={commitEditorSession}
+          onCancel={() => closeEditorSession(null)}
+        />
+      ) : null}
+    </>
+  )
+}
+
+/**
+ * The built-in free-text editor: a portal into the body viewport, positioned
+ * flush over the focused cell with the cell's own font, alignment and
+ * padding, so the text keeps its exact place - the Sheets model. The
+ * `textarea` control grows downward over the rows below as the text wraps.
+ */
+function measureDataGridCellEditorStyle(
+  viewport: HTMLElement
+): CSSProperties | null {
+  const cell = viewport.querySelector<HTMLElement>("td[data-cell-focused]")
+  if (!cell) return null
+  const cellRect = cell.getBoundingClientRect()
+  const viewportRect = viewport.getBoundingClientRect()
+  const cellStyle = getComputedStyle(cell)
+  // The td centers its one line vertically (align-middle); the editor must
+  // put the text in exactly the same place or opening it shifts the value.
+  // Symmetric block padding sized to center one line does that for the
+  // textarea too, and keeps holding as it grows line by line.
+  const lineHeight =
+    Number.parseFloat(cellStyle.lineHeight) ||
+    Number.parseFloat(cellStyle.fontSize) * 1.5 ||
+    20
+  const centeredBlockPadding = Math.max(
+    Number.parseFloat(cellStyle.paddingTop) || 0,
+    (cellRect.height - lineHeight) / 2
+  )
+  return {
+    // Rect deltas are visual; when the viewport itself is the scroll
+    // container (the standalone virtual layout), absolute children live in
+    // content coordinates, so the scroll offset must be added back. The box
+    // matches the cell exactly - editing must not change the cell's
+    // geometry - and the cell's own overlay chrome hides for the session
+    // (data-cell-editing), so the editor's outline is the ONE border.
+    left: cellRect.left - viewportRect.left + viewport.scrollLeft,
+    top: cellRect.top - viewportRect.top + viewport.scrollTop,
+    width: cellRect.width,
+    minHeight: cellRect.height,
+    // The font shorthand can serialize empty (Firefox); the longhands after
+    // it win where set and cover that case.
+    font: cellStyle.font || undefined,
+    fontFamily: cellStyle.fontFamily,
+    fontSize: cellStyle.fontSize,
+    fontWeight: cellStyle.fontWeight,
+    fontStyle: cellStyle.fontStyle,
+    lineHeight: cellStyle.lineHeight,
+    letterSpacing: cellStyle.letterSpacing,
+    textAlign: cellStyle.textAlign as CSSProperties["textAlign"],
+    paddingLeft: cellStyle.paddingLeft,
+    paddingRight: cellStyle.paddingRight,
+    paddingTop: centeredBlockPadding,
+    paddingBottom: centeredBlockPadding,
+  }
+}
+
+function DataGridCellEditorOverlay({
+  viewport,
+  session,
+  enterAdvance,
+  onCommit,
+  onCancel,
+}: {
+  viewport: HTMLElement
+  session: DataGridEditorSession
+  enterAdvance: boolean
+  onCommit: (
+    raw: string,
+    advance: DataGridEditorAdvance,
+    refocus?: boolean
+  ) => void
+  onCancel: () => void
+}) {
+  // Measured lazily at first render: the focused td was committed before the
+  // session opened, and the overlay remounts per cell via its key, so one
+  // measurement holds for the editor's lifetime.
+  const [style] = useState<CSSProperties | null>(() =>
+    measureDataGridCellEditorStyle(viewport)
+  )
+  const finishedRef = useRef(false)
+
+  // The caret belongs at the END of the value (the Excel F2 convention);
+  // a textarea would otherwise open with it at position 0. Set on mount,
+  // before autoFocus lands, so the stored selection is already right.
+  const placeCaretAtEnd = (
+    element: HTMLInputElement | HTMLTextAreaElement | null
+  ) => {
+    if (!element) return
+    const end = element.value.length
+    element.setSelectionRange?.(end, end)
+  }
+
+  useEffect(() => {
+    if (!style) onCancel()
+  }, [style, onCancel])
+
+  // External row changes mid-edit (a live update, a re-sort) move or remove
+  // the cell underneath the overlay; the measured position is then a lie and
+  // a commit could land visually elsewhere. Cancel instead: predictable, and
+  // nothing is written that the user cannot see.
+  useEffect(() => {
+    const body = viewport.querySelector("tbody")
+    if (!body) return
+    const observer = new MutationObserver(() => {
+      if (!finishedRef.current) onCancel()
+    })
+    observer.observe(body, { childList: true, subtree: true })
+    return () => observer.disconnect()
+  }, [viewport, onCancel])
+
+  if (!style) return null
+
+  const finish = (
+    element: HTMLInputElement | HTMLTextAreaElement,
+    commit: boolean,
+    advance: DataGridEditorAdvance = null,
+    refocus = true
+  ) => {
+    // One finish per session: an Enter commit can be chased by the blur the
+    // unmount produces, and a doubled commit would write twice.
+    if (finishedRef.current) return
+    finishedRef.current = true
+    if (commit) onCommit(element.value, advance, refocus)
+    else onCancel()
+  }
+
+  const handleKeyDown = (
+    event: ReactKeyboardEvent<HTMLInputElement | HTMLTextAreaElement>
+  ) => {
+    const element = event.currentTarget
+    if (event.key === "Escape") {
+      event.preventDefault()
+      event.stopPropagation()
+      finish(element, false)
+      return
+    }
+    if (event.key === "Tab") {
+      event.preventDefault()
+      finish(element, true, event.shiftKey ? "left" : "right")
+      return
+    }
+    if (event.key !== "Enter") return
+    // A textarea keeps Shift/Alt+Enter as a newline, the Sheets convention.
+    if (session.control === "textarea" && (event.shiftKey || event.altKey)) {
+      return
+    }
+    event.preventDefault()
+    // The default keeps focus on the edited cell, so a corrected value can
+    // be reviewed in place; enterAdvance restores the Sheets move-down.
+    finish(
+      element,
+      true,
+      enterAdvance ? (event.shiftKey ? "up" : "down") : null
+    )
+  }
+
+  // z-[35]: above the sticky pinned cells (zIndex 30), or editing a pinned
+  // cell renders invisibly underneath them; below the sticky header (z-40).
+  // Primary outline at the same 1px weight as the focused cell's box: with
+  // the overlay covering that box, opening the editor reads as the same
+  // border becoming editable.
+  const sharedClassName =
+    "text-foreground bg-background outline-primary absolute z-[35] box-border resize-none outline-1 outline-solid -outline-offset-1"
+
+  return createPortal(
+    session.control === "textarea" ? (
+      <textarea
+        data-slot="data-grid-cell-editor"
+        ref={placeCaretAtEnd}
+        autoFocus
+        aria-label={session.label}
+        defaultValue={session.initialValue}
+        rows={1}
+        style={style}
+        className={cn(sharedClassName, "field-sizing-content overflow-hidden")}
+        onKeyDown={handleKeyDown}
+        onBlur={(event) => finish(event.currentTarget, true, null, false)}
+      />
+    ) : (
+      <input
+        data-slot="data-grid-cell-editor"
+        ref={placeCaretAtEnd}
+        autoFocus
+        aria-label={session.label}
+        defaultValue={session.initialValue}
+        style={style}
+        className={sharedClassName}
+        onKeyDown={handleKeyDown}
+        onBlur={(event) => finish(event.currentTarget, true, null, false)}
+      />
+    ),
+    viewport
+  )
+}
+
+/* ------------------------------------------------------------------------- *
+ * Bulk edit bar.
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Thin shell over row selection for bulk actions: selected count, a slot for
+ * the consumer's controls, and a clear action. Hidden while nothing is
+ * selected. What the controls do stays consumer-owned.
+ *
+ * Presented as a floating toolbar, the Google Sheets way: auto width,
+ * centered, elevated, and sticky to the viewport bottom with breathing room,
+ * so bulk actions stay reachable while the grid scrolls.
+ */
+function DataGridSelectionBar({
+  children,
+  className,
+  label,
+  clearLabel = "Clear",
+  onClear,
+}: {
+  children?: ReactNode
+  className?: string
+  label?: (count: number) => ReactNode
+  clearLabel?: ReactNode
+  onClear?: () => void
+}) {
+  const context = useDataGrid()
+  const rowSelectionAtom = context.table.atoms.rowSelection
+  if (rowSelectionAtom == null) return null
+
+  return (
+    <Subscribe source={rowSelectionAtom}>
+      {() => {
+        // Read through the context getter: this closure re-runs on atom
+        // writes without re-rendering the component, and a captured v9
+        // wrapper would keep reporting the state it was built with.
+        const table = context.table
+        const count = table.getSelectedRowModel().rows.length
+        if (count === 0) return null
+        return (
+          <div
+            data-slot="data-grid-selection-bar"
+            className={cn(
+              "bg-background rounded-lg sticky inset-x-0 bottom-4 z-40 mx-auto flex w-fit max-w-[calc(100%-2rem)] flex-wrap items-center gap-3 border px-4 py-2.5 shadow-lg",
+              className
+            )}
+          >
+            <span className="text-foreground text-sm font-medium">
+              {label ? label(count) : `${count} selected`}
+            </span>
+            <div className="flex flex-1 flex-wrap items-center justify-end gap-2.5">
+              {children}
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => {
+                  context.table.resetRowSelection()
+                  onClear?.()
+                }}
+              >
+                {clearLabel}
+              </Button>
+            </div>
+          </div>
+        )
+      }}
+    </Subscribe>
+  )
+}
+
+export {
+  DataGridCellSelection,
+  DataGridSelectionBar,
+  buildDataGridClearDetails,
+  buildDataGridPasteDetails,
+  getDataGridActiveRegionGrid,
+  getDataGridVisibleSelectedCellCount,
+  invertDataGridCellsChange,
+  parseDataGridClipboardText,
+  serializeDataGridClipboardText,
+  tileDataGridClipboardBlock,
+}
+export type {
+  DataGridCellSelectionApi,
+  DataGridFocusCellOptions,
+  DataGridPasteTarget,
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/data-grid/data-grid-column-filter.tsx b/apps/web/src/components/reui/data-grid/data-grid-column-filter.tsx
index 6a0201b..1e58b0e 100644
--- a/apps/web/src/components/reui/data-grid/data-grid-column-filter.tsx
+++ b/apps/web/src/components/reui/data-grid/data-grid-column-filter.tsx
@@ -1,8 +1,10 @@
-"use client"
+"use no memo"
 
 import { useMemo, useState } from "react"
 import { Badge } from "@/components/reui/badge"
-import { Column } from "@tanstack/react-table"
+import { useDataGrid } from "@/components/reui/data-grid/data-grid"
+import type { DataGridFeatures } from "@/components/reui/data-grid/data-grid"
+import type { Column } from "@tanstack/react-table"
 
 import { cn } from "@authportal/ui/lib/utils"
 import { Button } from "@authportal/ui/components/button"
@@ -15,8 +17,8 @@ import {
 import { Separator } from "@authportal/ui/components/separator"
 import { CirclePlusIcon, CheckIcon } from "lucide-react"
 
-interface DataGridColumnFilterProps<TData, TValue> {
-  column?: Column<TData, TValue>
+interface DataGridColumnFilterProps<TData extends object, TValue> {
+  column?: Column<DataGridFeatures, TData, TValue>
   title?: string
   options: {
     label: string
@@ -25,11 +27,12 @@ interface DataGridColumnFilterProps<TData, TValue> {
   }[]
 }
 
-function DataGridColumnFilter<TData, TValue>({
+function DataGridColumnFilter<TData extends object, TValue>({
   column,
   title,
   options,
 }: DataGridColumnFilterProps<TData, TValue>) {
+  const { i18n } = useDataGrid()
   const facets = column?.getFacetedUniqueValues()
   const filterValue = column?.getFilterValue()
   const selectedValues = new Set(
@@ -60,10 +63,10 @@ function DataGridColumnFilter<TData, TValue>({
                 >
                   {selectedValues.size}
                 </Badge>
-                <div className="hidden space-x-1 lg:flex">
+                <div className="hidden gap-x-1 lg:flex">
                   {selectedValues.size > 2 ? (
                     <Badge variant="secondary" className="px-1 font-normal">
-                      {selectedValues.size} selected
+                      {i18n.labels.filterSelectedCount(selectedValues.size)}
                     </Badge>
                   ) : (
                     options
@@ -96,7 +99,7 @@ function DataGridColumnFilter<TData, TValue>({
         <div className="max-h-[300px] overflow-y-auto">
           {filteredOptions.length === 0 ? (
             <div className="text-muted-foreground py-6 text-center text-sm">
-              No results found.
+              {i18n.labels.filterNoResults}
             </div>
           ) : (
             <div className="p-1">
@@ -172,7 +175,7 @@ function DataGridColumnFilter<TData, TValue>({
                   }}
                   className="hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground rounded-md relative flex cursor-pointer items-center justify-center px-2 py-1.5 text-sm outline-hidden select-none"
                 >
-                  Clear filters
+                  {i18n.labels.filterClear}
                 </div>
               </div>
             </>
diff --git a/apps/web/src/components/reui/data-grid/data-grid-column-header.tsx b/apps/web/src/components/reui/data-grid/data-grid-column-header.tsx
index 16d274d..43e7c00 100644
--- a/apps/web/src/components/reui/data-grid/data-grid-column-header.tsx
+++ b/apps/web/src/components/reui/data-grid/data-grid-column-header.tsx
@@ -1,9 +1,18 @@
-import { HTMLAttributes, memo, ReactNode, useMemo } from "react"
+"use client"
+
+// Opted out of React Compiler with the rest of the grid (see data-grid.tsx).
+"use no memo"
+
+import { memo, useLayoutEffect, useMemo, useRef } from "react"
+import type { HTMLAttributes, ReactNode } from "react"
 import {
   getColumnHeaderLabel,
+  getDataGridHeaderSpans,
   useDataGrid,
 } from "@/components/reui/data-grid/data-grid"
-import { Column } from "@tanstack/react-table"
+import type { DataGridFeatures } from "@/components/reui/data-grid/data-grid"
+import { Subscribe } from "@tanstack/react-table"
+import type { Column } from "@tanstack/react-table"
 
 import { cn } from "@authportal/ui/lib/utils"
 import { Button } from "@authportal/ui/components/button"
@@ -23,10 +32,10 @@ import {
 import { ArrowDownIcon, ArrowUpIcon, ChevronsUpDownIcon, CheckIcon, ArrowLeftToLineIcon, ArrowRightToLineIcon, ArrowLeftIcon, ArrowRightIcon, Settings2Icon, PinOffIcon } from "lucide-react"
 
 interface DataGridColumnHeaderProps<
-  TData,
+  TData extends object,
   TValue,
 > extends HTMLAttributes<HTMLDivElement> {
-  column: Column<TData, TValue>
+  column: Column<DataGridFeatures, TData, TValue>
   /** When omitted, uses `column.columnDef.meta.headerTitle`, then a string `columnDef.header`, then `column.id`. */
   title?: string
   icon?: ReactNode
@@ -36,7 +45,12 @@ interface DataGridColumnHeaderProps<
   visibility?: boolean
 }
 
-function DataGridColumnHeaderInner<TData, TValue>({
+// Unpinning moves a column into another header list (pinned, windowed center),
+// which remounts its header, so the focus request outlives the button: the next
+// header rendered for that column takes it. `column` is a stable reference.
+const pendingUnpinFocus = new WeakSet<object>()
+
+function DataGridColumnHeaderInner<TData extends object, TValue>({
   column,
   title,
   icon,
@@ -44,25 +58,106 @@ function DataGridColumnHeaderInner<TData, TValue>({
   filter,
   visibility = false,
 }: DataGridColumnHeaderProps<TData, TValue>) {
-  const { isLoading, table, props, recordCount } = useDataGrid()
+  const { i18n, isLoading, table, props } = useDataGrid()
   const resolvedTitle = title ?? getColumnHeaderLabel(column)
 
-  const columnOrder = table.getState().columnOrder
+  // The order a move rewrites: the consumer's columnOrder (TanStack defaults it
+  // to []), then every leaf it leaves out, in definition order - the same
+  // completion TanStack applies when rendering, so a rendered neighbour is
+  // always present to re-seat beside, even after columns are added later.
+  const columnOrderState = table.state.columnOrder
+  const definitionOrder = table
+    .getAllColumns()
+    .flatMap((topColumn) => topColumn.getLeafColumns())
+    .map((leafColumn) => leafColumn.id)
+  const columnOrder = [
+    ...columnOrderState,
+    ...definitionOrder.filter((id) => !columnOrderState.includes(id)),
+  ]
   const columnVisibilityKey =
     props.tableLayout?.columnsVisibility && visibility
-      ? JSON.stringify(table.getState().columnVisibility)
+      ? JSON.stringify(table.state.columnVisibility)
       : ""
   const isSorted = column.getIsSorted()
   const isPinned = column.getIsPinned()
+  const menuTriggerRef = useRef<HTMLButtonElement>(null)
+  useLayoutEffect(() => {
+    if (pendingUnpinFocus.delete(column)) menuTriggerRef.current?.focus()
+  })
   const canSort = column.getCanSort()
   const canPin = column.getCanPin()
   const canResize = column.getCanResize()
 
-  const columnIndex = columnOrder.indexOf(column.id)
-  const canMoveLeft = columnIndex > 0
-  const canMoveRight = columnIndex < columnOrder.length - 1
+  // Move neighbours come from what is RENDERED: the column's own pin bucket,
+  // visible columns only. Stepping through the raw columnOrder would trade
+  // places with a hidden or pinned column - an enabled click that moves nothing.
+  // With grouping in TanStack's default "reorder" mode, grouped columns render
+  // first whatever columnOrder says: they neither move nor serve as a target.
+  const groupedColumnMode = (
+    table.options as { groupedColumnMode?: false | "reorder" | "remove" }
+  ).groupedColumnMode
+  const isHoistedByGrouping = (target: object) =>
+    groupedColumnMode !== false &&
+    typeof (target as { getIsGrouped?: unknown }).getIsGrouped === "function" &&
+    (target as { getIsGrouped: () => boolean }).getIsGrouped()
+  const renderedLeaves = (
+    isPinned === "start"
+      ? table.getStartVisibleLeafColumns()
+      : isPinned === "end"
+        ? table.getEndVisibleLeafColumns()
+        : table.getCenterVisibleLeafColumns()
+  )
+    .filter((leafColumn) => !isHoistedByGrouping(leafColumn))
+    .map((leafColumn) => leafColumn.id)
+  const renderedOrder = new Map(renderedLeaves.map((id, index) => [id, index]))
+  const byRenderedOrder = (a: string, b: string) =>
+    renderedOrder.get(a)! - renderedOrder.get(b)!
+  // A peer is a sibling at this column's header level with its rendered
+  // leaves, so a group or a meta.headerColSpan span moves as one.
+  const headerSpans = getDataGridHeaderSpans(table)
+  const coveredIds = new Set(
+    [...headerSpans.values()].flat().map((leafColumn) => leafColumn.id)
+  )
+  // Siblings only: a leaf stepping out of its group would split its header.
+  const renderedPeers = (column.parent?.columns ?? table.getAllColumns())
+    .filter((sibling) => !coveredIds.has(sibling.id))
+    .map((sibling) =>
+      [...sibling.getLeafColumns(), ...(headerSpans.get(sibling.id) ?? [])]
+        .map((leafColumn) => leafColumn.id)
+        .filter((id) => renderedOrder.has(id))
+        .sort(byRenderedOrder)
+    )
+    .filter((leaves) => leaves.length > 0)
+    .sort((a, b) => byRenderedOrder(a[0]!, b[0]!))
+  const renderedIndex = column.columns.length
+    ? -1
+    : renderedPeers.findIndex((leaves) => leaves[0] === column.id)
+  const leftNeighbour =
+    renderedIndex > 0 ? renderedPeers[renderedIndex - 1] : undefined
+  const rightNeighbour =
+    renderedIndex !== -1 && renderedIndex < renderedPeers.length - 1
+      ? renderedPeers[renderedIndex + 1]
+      : undefined
+  const canMoveLeft = leftNeighbour !== undefined
+  const canMoveRight = rightNeighbour !== undefined
 
+  /** Re-seats this column, with the leaves its header spans, beside a rendered
+   * neighbour; every other column, hidden or pinned, keeps its place. */
+  const moveBeside = (neighbour: string[], side: "before" | "after") => {
+    const moving = renderedPeers[renderedIndex] ?? [column.id]
+    const newOrder = columnOrder.filter((id) => !moving.includes(id))
+    const anchor =
+      side === "before" ? neighbour[0] : neighbour[neighbour.length - 1]
+    const at = anchor === undefined ? -1 : newOrder.indexOf(anchor)
+    if (at === -1) return
+    newOrder.splice(side === "before" ? at : at + 1, 0, ...moving)
+    table.setColumnOrder(newOrder)
+  }
+
+  // column.toggleSorting has no getCanSort() guard of its own, and the
+  // direct button also renders for columns that are only resizable.
   const handleSort = () => {
+    if (!canSort) return
     if (isSorted === "asc") {
       column.toggleSorting(true)
     } else if (isSorted === "desc") {
@@ -92,6 +187,22 @@ function DataGridColumnHeaderInner<TData, TValue>({
       <ChevronsUpDownIcon className="mt-px size-3.25" aria-hidden="true" />
     ))
 
+  // A start-pinned column's resize handle covers the last 20px of its cell
+  // (the column that renders last already reserves it with pe-8, and a
+  // start-pinned one renders last only when nothing follows its group), so
+  // the unpin button steps in until it clears the handle in both densities.
+  // The step is padding on a wrapper that shrinks first: a column too narrow
+  // for label, button and clearance gives the clearance back, never the label.
+  const unpinClearsResizeHandle =
+    props.tableLayout?.columnsResizable &&
+    canResize &&
+    isPinned === "start" &&
+    !(
+      column.getIsLastColumn("start") &&
+      table.getCenterVisibleLeafColumns().length === 0 &&
+      table.getEndVisibleLeafColumns().length === 0
+    )
+
   const hasControls =
     props.tableLayout?.columnsMovable ||
     (props.tableLayout?.columnsVisibility && visibility) ||
@@ -130,7 +241,7 @@ function DataGridColumnHeaderInner<TData, TValue>({
           disabled={!canSort}
         >
           <ArrowUpIcon className="size-3.5!" />
-          <span className="grow">Asc</span>
+          <span className="grow">{i18n.labels.sortAscending}</span>
           {isSorted === "asc" && (
             <CheckIcon className="text-primary size-4 opacity-100!" />
           )}
@@ -147,7 +258,7 @@ function DataGridColumnHeaderInner<TData, TValue>({
           disabled={!canSort}
         >
           <ArrowDownIcon className="size-3.5!" />
-          <span className="grow">Desc</span>
+          <span className="grow">{i18n.labels.sortDescending}</span>
           {isSorted === "desc" && (
             <CheckIcon className="text-primary size-4 opacity-100!" />
           )}
@@ -164,21 +275,21 @@ function DataGridColumnHeaderInner<TData, TValue>({
       items.push(
         <DropdownMenuItem
           key="pin-left"
-          onClick={() => column.pin(isPinned === "left" ? false : "left")}
+          onClick={() => column.pin(isPinned === "start" ? false : "start")}
         >
           <ArrowLeftToLineIcon className="size-3.5!" aria-hidden="true" />
-          <span className="grow">Pin to left</span>
-          {isPinned === "left" && (
+          <span className="grow">{i18n.labels.pinColumnStart}</span>
+          {isPinned === "start" && (
             <CheckIcon className="text-primary size-4 opacity-100!" />
           )}
         </DropdownMenuItem>,
         <DropdownMenuItem
           key="pin-right"
-          onClick={() => column.pin(isPinned === "right" ? false : "right")}
+          onClick={() => column.pin(isPinned === "end" ? false : "end")}
         >
           <ArrowRightToLineIcon className="size-3.5!" aria-hidden="true" />
-          <span className="grow">Pin to right</span>
-          {isPinned === "right" && (
+          <span className="grow">{i18n.labels.pinColumnEnd}</span>
+          {isPinned === "end" && (
             <CheckIcon className="text-primary size-4 opacity-100!" />
           )}
         </DropdownMenuItem>
@@ -195,32 +306,22 @@ function DataGridColumnHeaderInner<TData, TValue>({
         <DropdownMenuItem
           key="move-left"
           onClick={() => {
-            if (columnIndex > 0) {
-              const newOrder = [...columnOrder]
-              const [movedColumn] = newOrder.splice(columnIndex, 1)
-              newOrder.splice(columnIndex - 1, 0, movedColumn)
-              table.setColumnOrder(newOrder)
-            }
+            if (leftNeighbour) moveBeside(leftNeighbour, "before")
           }}
           disabled={!canMoveLeft || isPinned !== false}
         >
           <ArrowLeftIcon className="size-3.5!" aria-hidden="true" />
-          <span>Move to Left</span>
+          <span>{i18n.labels.moveColumnStart}</span>
         </DropdownMenuItem>,
         <DropdownMenuItem
           key="move-right"
           onClick={() => {
-            if (columnIndex < columnOrder.length - 1) {
-              const newOrder = [...columnOrder]
-              const [movedColumn] = newOrder.splice(columnIndex, 1)
-              newOrder.splice(columnIndex + 1, 0, movedColumn)
-              table.setColumnOrder(newOrder)
-            }
+            if (rightNeighbour) moveBeside(rightNeighbour, "after")
           }}
           disabled={!canMoveRight || isPinned !== false}
         >
           <ArrowRightIcon className="size-3.5!" aria-hidden="true" />
-          <span>Move to Right</span>
+          <span>{i18n.labels.moveColumnEnd}</span>
         </DropdownMenuItem>
       )
       hasPreviousSection = true
@@ -235,7 +336,7 @@ function DataGridColumnHeaderInner<TData, TValue>({
         <DropdownMenuSub key="visibility">
           <DropdownMenuSubTrigger>
             <Settings2Icon className="size-3.5!" />
-            <span>Columns</span>
+            <span>{i18n.labels.columnsMenu}</span>
           </DropdownMenuSubTrigger>
           <DropdownMenuSubContent side="right">
             {table
@@ -247,7 +348,11 @@ function DataGridColumnHeaderInner<TData, TValue>({
                   checked={col.getIsVisible()}
                   onSelect={(event) => event.preventDefault()}
                   onCheckedChange={(value) => col.toggleVisibility(!!value)}
-                  className="capitalize"
+                  className={
+                    getColumnHeaderLabel(col) === col.id
+                      ? "capitalize"
+                      : undefined
+                  }
                 >
                   {getColumnHeaderLabel(col)}
                 </DropdownMenuCheckboxItem>
@@ -273,7 +378,8 @@ function DataGridColumnHeaderInner<TData, TValue>({
     canMoveRight,
     visibility,
     table,
-    columnIndex,
+    leftNeighbour,
+    rightNeighbour,
     columnOrder,
     columnVisibilityKey, // Needed to update checkbox states when visibility changes
   ])
@@ -283,11 +389,12 @@ function DataGridColumnHeaderInner<TData, TValue>({
       <div className="-ms-2 flex h-full items-center justify-between gap-1.5">
         <DropdownMenu>
           <DropdownMenuTrigger
+            ref={menuTriggerRef}
             render={
               <Button
                 variant="ghost"
                 className={headerButtonClassName}
-                disabled={isLoading || recordCount === 0}
+                disabled={isLoading}
               >
                 {icon && icon}
                 {resolvedTitle}
@@ -300,16 +407,34 @@ function DataGridColumnHeaderInner<TData, TValue>({
           </DropdownMenuContent>
         </DropdownMenu>
         {props.tableLayout?.columnsPinnable && canPin && isPinned && (
-          <Button
-            size="icon-sm"
-            variant="ghost"
-            className="rounded-lg -me-1 size-7"
-            onClick={() => column.pin(false)}
-            aria-label={`Unpin ${resolvedTitle} column`}
-            title={`Unpin ${resolvedTitle} column`}
+          <span
+            className={cn(
+              "-me-1 flex min-w-7 shrink-[999]",
+              unpinClearsResizeHandle && "pe-4"
+            )}
           >
-            <PinOffIcon className="size-3.5! opacity-50!" aria-hidden="true" />
-          </Button>
+            <Button
+              size="icon-sm"
+              variant="ghost"
+              className="rounded-lg size-7"
+              onClick={(event) => {
+                const scrollArea = event.currentTarget.closest<HTMLElement>(
+                  '[data-slot="scroll-area-viewport"]'
+                )
+                pendingUnpinFocus.add(column)
+                column.pin(false)
+                // A column the virtual window leaves unmounted claims nothing,
+                // so the grid's scroll area takes focus instead of the page.
+                requestAnimationFrame(() => {
+                  if (pendingUnpinFocus.delete(column)) scrollArea?.focus()
+                })
+              }}
+              aria-label={i18n.labels.unpinColumn(resolvedTitle)}
+              title={i18n.labels.unpinColumn(resolvedTitle)}
+            >
+              <PinOffIcon className="size-3.5! opacity-50!" aria-hidden="true" />
+            </Button>
+          </span>
         )}
       </div>
     )
@@ -321,7 +446,7 @@ function DataGridColumnHeaderInner<TData, TValue>({
         <Button
           variant="ghost"
           className={headerButtonClassName}
-          disabled={isLoading || recordCount === 0}
+          disabled={isLoading}
           onClick={handleSort}
         >
           {icon && icon}
@@ -340,8 +465,45 @@ function DataGridColumnHeaderInner<TData, TValue>({
   )
 }
 
-const DataGridColumnHeader = memo(
-  DataGridColumnHeaderInner
-) as typeof DataGridColumnHeaderInner
+const DataGridColumnHeaderMemo = memo(DataGridColumnHeaderInner) as <
+  TData extends object,
+  TValue,
+>(
+  props: DataGridColumnHeaderProps<TData, TValue> & {
+    /** Internal: the state slices the header re-renders on. Not part of the public API. */
+    subscribedState?: unknown
+  }
+) => ReactNode
+
+/**
+ * Sort and pin state reaches this header through builder calls on `column`
+ * (`getIsSorted()`, `getIsPinned()`), and `column` keeps its identity across
+ * renders, so anything memoized against it (the `memo` below, or a consumer's
+ * compiled header template) never re-runs those reads: frozen sort arrows and
+ * pin controls. The `Subscribe` below turns the slices this header actually
+ * reads into a real reactive dependency, and threading the selection through
+ * as a prop is what lets it past the `memo`.
+ */
+function DataGridColumnHeader<TData extends object, TValue>(
+  props: DataGridColumnHeaderProps<TData, TValue>
+) {
+  const { table } = useDataGrid()
+
+  return (
+    <Subscribe
+      source={table.store}
+      selector={(state) => ({
+        sorting: state.sorting,
+        columnPinning: state.columnPinning,
+        columnOrder: state.columnOrder,
+        columnVisibility: state.columnVisibility,
+      })}
+    >
+      {(subscribed) => (
+        <DataGridColumnHeaderMemo {...props} subscribedState={subscribed} />
+      )}
+    </Subscribe>
+  )
+}
 
 export { DataGridColumnHeader, type DataGridColumnHeaderProps }
\ No newline at end of file
diff --git a/apps/web/src/components/reui/data-grid/data-grid-column-visibility.tsx b/apps/web/src/components/reui/data-grid/data-grid-column-visibility.tsx
index b835d5c..5085c00 100644
--- a/apps/web/src/components/reui/data-grid/data-grid-column-visibility.tsx
+++ b/apps/web/src/components/reui/data-grid/data-grid-column-visibility.tsx
@@ -1,8 +1,12 @@
-"use client"
+"use no memo"
 
-import { ReactElement } from "react"
-import { getColumnHeaderLabel } from "@/components/reui/data-grid/data-grid"
-import { Table } from "@tanstack/react-table"
+import type { ReactElement } from "react"
+import {
+  getColumnHeaderLabel,
+  useDataGrid,
+} from "@/components/reui/data-grid/data-grid"
+import type { DataGridFeatures } from "@/components/reui/data-grid/data-grid"
+import type { Table } from "@tanstack/react-table"
 
 import {
   DropdownMenu,
@@ -13,20 +17,22 @@ import {
   DropdownMenuTrigger,
 } from "@authportal/ui/components/dropdown-menu"
 
-function DataGridColumnVisibility<TData>({
+function DataGridColumnVisibility<TData extends object>({
   table,
   trigger,
 }: {
-  table: Table<TData>
+  table: Table<DataGridFeatures, TData>
   trigger: ReactElement<Record<string, unknown>>
 }) {
+  const { i18n } = useDataGrid()
+
   return (
     <DropdownMenu>
       <DropdownMenuTrigger render={trigger} />
       <DropdownMenuContent align="end" className="min-w-[150px]">
         <DropdownMenuGroup>
           <DropdownMenuLabel className="font-medium">
-            Toggle Columns
+            {i18n.labels.toggleColumns}
           </DropdownMenuLabel>
           {table
             .getAllColumns()
@@ -35,7 +41,13 @@ function DataGridColumnVisibility<TData>({
               return (
                 <DropdownMenuCheckboxItem
                   key={column.id}
-                  className="capitalize"
+                  // Title-casing is for a raw column id only; an authored
+                  // label keeps its own casing.
+                  className={
+                    getColumnHeaderLabel(column) === column.id
+                      ? "capitalize"
+                      : undefined
+                  }
                   checked={column.getIsVisible()}
                   onSelect={(event) => event.preventDefault()}
                   onCheckedChange={(value) => column.toggleVisibility(!!value)}
diff --git a/apps/web/src/components/reui/data-grid/data-grid-i18n.tsx b/apps/web/src/components/reui/data-grid/data-grid-i18n.tsx
new file mode 100644
index 0000000..f7556e2
--- /dev/null
+++ b/apps/web/src/components/reui/data-grid/data-grid-i18n.tsx
@@ -0,0 +1,99 @@
+export interface DataGridI18nLabels {
+  /* The column header menu. */
+  sortAscending: string
+  sortDescending: string
+  pinColumnStart: string
+  pinColumnEnd: string
+  moveColumnStart: string
+  moveColumnEnd: string
+  columnsMenu: string
+  unpinColumn: (title: string) => string
+  toggleColumns: string
+  /* Row and cell affordances. */
+  rowCreate: string
+  pinRow: string
+  unpinRow: string
+  selectRow: string
+  selectAll: string
+  expandRow: string
+  collapseRow: string
+  dragToReorder: string
+  dragToReorderRow: string
+  reorderingUnavailable: string
+  /* Grid states. */
+  loading: string
+  empty: string
+  allRowsLoaded: string
+  /* Pagination. */
+  rowsPerPage: string
+  paginationInfo: (info: { from: number; to: number; count: number }) => string
+  previousPage: string
+  nextPage: string
+  goToPage: (page: number) => string
+  paginationEllipsis: string
+  /* The faceted column filter. */
+  filterSelectedCount: (count: number) => string
+  filterNoResults: string
+  filterClear: string
+}
+
+export interface DataGridI18nConfig {
+  labels: DataGridI18nLabels
+}
+
+export type DataGridI18nOverrides = {
+  labels?: Partial<DataGridI18nLabels>
+}
+
+const DEFAULT_DATA_GRID_LABELS: DataGridI18nLabels = {
+  sortAscending: "Asc",
+  sortDescending: "Desc",
+  pinColumnStart: "Pin to left",
+  pinColumnEnd: "Pin to right",
+  moveColumnStart: "Move to left",
+  moveColumnEnd: "Move to right",
+  columnsMenu: "Columns",
+  unpinColumn: (title) => `Unpin ${title} column`,
+  toggleColumns: "Toggle Columns",
+  rowCreate: "Add row",
+  pinRow: "Pin row",
+  unpinRow: "Unpin row",
+  selectRow: "Select row",
+  selectAll: "Select all",
+  expandRow: "Expand row",
+  collapseRow: "Collapse row",
+  dragToReorder: "Drag to reorder",
+  dragToReorderRow: "Drag to reorder row",
+  reorderingUnavailable: "Reordering unavailable",
+  loading: "Loading...",
+  empty: "No data available",
+  allRowsLoaded: "All records loaded",
+  rowsPerPage: "Rows per page",
+  paginationInfo: ({ from, to, count }) => `${from} - ${to} of ${count}`,
+  previousPage: "Go to previous page",
+  nextPage: "Go to next page",
+  goToPage: (page) => `Go to page ${page}`,
+  paginationEllipsis: "...",
+  filterSelectedCount: (count) => `${count} selected`,
+  filterNoResults: "No results found.",
+  filterClear: "Clear filters",
+}
+
+const DEFAULT_DATA_GRID_I18N: DataGridI18nConfig = Object.freeze({
+  labels: Object.freeze(DEFAULT_DATA_GRID_LABELS),
+})
+
+/**
+ * A shallow merge per section, deliberately: a deep merge would leak a
+ * default back into a function-valued label the consumer replaced. With no
+ * overrides the frozen default is returned as-is, so the merge is free to
+ * run on every render without producing a new identity.
+ */
+export function mergeDataGridI18n(
+  overrides?: DataGridI18nOverrides
+): DataGridI18nConfig {
+  if (!overrides?.labels) return DEFAULT_DATA_GRID_I18N
+  return {
+    labels: { ...DEFAULT_DATA_GRID_LABELS, ...overrides.labels },
+  }
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/data-grid/data-grid-pagination.tsx b/apps/web/src/components/reui/data-grid/data-grid-pagination.tsx
index e9082ab..98e9d6a 100644
--- a/apps/web/src/components/reui/data-grid/data-grid-pagination.tsx
+++ b/apps/web/src/components/reui/data-grid/data-grid-pagination.tsx
@@ -1,4 +1,9 @@
-import React, { ReactNode } from "react"
+"use client"
+
+// Opted out of React Compiler with the rest of the grid (see data-grid.tsx).
+"use no memo"
+
+import type { JSX, ReactNode } from "react"
 import { useDataGrid } from "@/components/reui/data-grid/data-grid"
 
 import { cn } from "@authportal/ui/lib/utils"
@@ -20,6 +25,8 @@ interface DataGridPaginationProps {
   sizesDescription?: string
   sizesSkeleton?: ReactNode
   more?: boolean
+  /** Page buttons the truncated middle shows; the row adds first, last and
+   *  an ellipsis for each hidden stretch. Clamped to a minimum of 3. */
   moreLimit?: number
   info?: string
   infoSkeleton?: ReactNode
@@ -30,109 +37,140 @@ interface DataGridPaginationProps {
   ellipsisText?: string
 }
 
-function DataGridPagination(props: DataGridPaginationProps): React.JSX.Element {
-  const { table, recordCount, isLoading } = useDataGrid()
+/**
+ * One slot in the page row: a page button, or an ellipsis that jumps over the
+ * pages it stands for.
+ */
+type DataGridPaginationItem =
+  | { type: "page"; index: number }
+  | { type: "ellipsis"; direction: "previous"; target: number }
+  | { type: "ellipsis"; direction: "next"; target: number }
+
+/**
+ * The adaptive window: first page, the run around the current one, last page,
+ * with an ellipsis standing in for each hidden stretch. It replaced fixed
+ * BLOCKS (1-5, then 6-10) because a block never shows the last page, so on a
+ * 50-page grid there was no way to reach the end - the primitive wires only
+ * `previousPage()` / `nextPage()`, so there is no last-page arrow either.
+ *
+ * `limit` is `moreLimit`: how many page buttons the truncated middle shows.
+ * At the default of 5 this emits exactly the same rows as the block version
+ * did at `moreLimit: 5`, so the prop keeps both its meaning and its default.
+ * An ellipsis never stands for a single page, because the early return covers
+ * every count a full row could hold.
+ */
+function getDataGridPaginationItems(
+  pageIndex: number,
+  pageCount: number,
+  limit: number
+): DataGridPaginationItem[] {
+  // Pages flanking the current one, per side. The run is rebuilt from it so
+  // the count is always odd: an even `limit` would make the head and tail
+  // rows one slot wider than the middle, and the footer would twitch as the
+  // user pages through.
+  const sibling = Math.max(0, Math.floor(((Math.floor(limit) || 3) - 3) / 2))
+  const pages = sibling * 2 + 3
+
+  // Two ellipses cost the width of two pages, so below this there is nothing
+  // to gain by hiding any.
+  if (pageCount <= pages + 2) {
+    return Array.from({ length: pageCount }, (_, index) => ({
+      type: "page" as const,
+      index,
+    }))
+  }
+
+  if (pageIndex <= sibling + 2) {
+    return [
+      ...Array.from({ length: pages }, (_, index) => ({
+        type: "page" as const,
+        index,
+      })),
+      { type: "ellipsis", direction: "next", target: pages },
+      { type: "page", index: pageCount - 1 },
+    ]
+  }
+
+  if (pageIndex >= pageCount - sibling - 3) {
+    return [
+      { type: "page", index: 0 },
+      {
+        type: "ellipsis",
+        direction: "previous",
+        target: pageCount - pages - 1,
+      },
+      ...Array.from({ length: pages }, (_, offset) => ({
+        type: "page" as const,
+        index: pageCount - pages + offset,
+      })),
+    ]
+  }
+
+  return [
+    { type: "page", index: 0 },
+    {
+      type: "ellipsis",
+      direction: "previous",
+      target: pageIndex - sibling - 1,
+    },
+    ...Array.from({ length: sibling * 2 + 1 }, (_, offset) => ({
+      type: "page" as const,
+      index: pageIndex - sibling + offset,
+    })),
+    { type: "ellipsis", direction: "next", target: pageIndex + sibling + 1 },
+    { type: "page", index: pageCount - 1 },
+  ]
+}
+
+/**
+ * A page button is square at one digit and grows from there, so the row does
+ * not reflow when the count crosses 10 or 100. The floor is each style's own
+ * `icon-sm` square, which is also its `sm` HEIGHT, so the numbers stay square
+ * and keep the arrows' height. Hardcoding one value would be right in three
+ * styles and wrong in five.
+ */
+const PAGE_BUTTON_WIDTH_CLASS =
+  "min-w-7"
+
+function DataGridPagination(props: DataGridPaginationProps): JSX.Element {
+  const { i18n, table, recordCount, isLoading } = useDataGrid()
 
   const defaultProps: Partial<DataGridPaginationProps> = {
     sizes: [5, 10, 25, 50, 100],
     sizesSkeleton: <Skeleton className="h-8 w-44" />,
     moreLimit: 5,
-    info: "{from} - {to} of {count}",
     infoSkeleton: <Skeleton className="h-8 w-60" />,
-    rowsPerPageLabel: "Rows per page",
-    previousPageLabel: "Go to previous page",
-    nextPageLabel: "Go to next page",
-    ellipsisText: "...",
+    rowsPerPageLabel: i18n.labels.rowsPerPage,
+    previousPageLabel: i18n.labels.previousPage,
+    nextPageLabel: i18n.labels.nextPage,
+    ellipsisText: i18n.labels.paginationEllipsis,
   }
 
   const mergedProps: DataGridPaginationProps = { ...defaultProps, ...props }
 
   const btnBaseClasses = "p-0 text-sm"
   const btnArrowClasses = btnBaseClasses + " rtl:transform rtl:rotate-180"
-  const pageIndex = table.getState().pagination.pageIndex
-  const pageSize = table.getState().pagination.pageSize
+  const pageIndex = table.state.pagination.pageIndex
+  const pageSize = table.state.pagination.pageSize
   const from = recordCount === 0 ? 0 : pageIndex * pageSize + 1
   const to = Math.min((pageIndex + 1) * pageSize, recordCount)
   const pageCount = table.getPageCount()
 
-  // Replace placeholders in paginationInfo
+  // A supplied `info` keeps its placeholder-template contract; the default
+  // routes through the i18n label function, where word order is free.
   const paginationInfo = mergedProps.info
     ? mergedProps.info
         .replaceAll("{from}", from.toString())
         .replaceAll("{to}", to.toString())
         .replaceAll("{count}", recordCount.toString())
-    : `${from} - ${to} of ${recordCount}`
+    : i18n.labels.paginationInfo({ from, to, count: recordCount })
 
-  // Pagination limit logic
-  const paginationMoreLimit = mergedProps.moreLimit || 5
-
-  // Determine the start and end of the pagination group
-  const currentGroupStart =
-    Math.floor(pageIndex / paginationMoreLimit) * paginationMoreLimit
-  const currentGroupEnd = Math.min(
-    currentGroupStart + paginationMoreLimit,
-    pageCount
+  const paginationItems = getDataGridPaginationItems(
+    pageIndex,
+    pageCount,
+    mergedProps.moreLimit ?? 5
   )
 
-  // Render page buttons based on the current group
-  const renderPageButtons = () => {
-    const buttons = []
-    for (let i = currentGroupStart; i < currentGroupEnd; i++) {
-      buttons.push(
-        <Button
-          key={i}
-          size="icon-sm"
-          variant="ghost"
-          className={cn(btnBaseClasses, "text-muted-foreground", {
-            "bg-accent text-accent-foreground": pageIndex === i,
-          })}
-          onClick={() => {
-            if (pageIndex !== i) {
-              table.setPageIndex(i)
-            }
-          }}
-        >
-          {i + 1}
-        </Button>
-      )
-    }
-    return buttons
-  }
-
-  // Render a "previous" ellipsis button if there are previous pages to show
-  const renderEllipsisPrevButton = () => {
-    if (currentGroupStart > 0) {
-      return (
-        <Button
-          size="icon-sm"
-          className={btnBaseClasses}
-          variant="ghost"
-          onClick={() => table.setPageIndex(currentGroupStart - 1)}
-        >
-          {mergedProps.ellipsisText}
-        </Button>
-      )
-    }
-    return null
-  }
-
-  // Render a "next" ellipsis button if there are more pages to show after the current group
-  const renderEllipsisNextButton = () => {
-    if (currentGroupEnd < pageCount) {
-      return (
-        <Button
-          className={btnBaseClasses}
-          variant="ghost"
-          size="icon-sm"
-          onClick={() => table.setPageIndex(currentGroupEnd)}
-        >
-          {mergedProps.ellipsisText}
-        </Button>
-      )
-    }
-    return null
-  }
-
   return (
     <div
       data-slot="data-grid-pagination"
@@ -141,7 +179,7 @@ function DataGridPagination(props: DataGridPaginationProps): React.JSX.Element {
         mergedProps.className
       )}
     >
-      <div className="order-2 flex flex-wrap items-center space-x-2.5 pb-2.5 sm:order-1 sm:pb-0">
+      <div className="order-2 flex flex-wrap items-center gap-x-2.5 pb-2.5 sm:order-1 sm:pb-0">
         {isLoading ? (
           mergedProps.sizesSkeleton
         ) : (
@@ -156,10 +194,22 @@ function DataGridPagination(props: DataGridPaginationProps): React.JSX.Element {
                 table.setPageSize(newPageSize)
               }}
             >
-              <SelectTrigger className="w-16" size="sm">
+              {/* w-fit with a min, never a fixed width: a fixed w-16 clipped
+                  the value "100" by 1px at nova's paddings, while fit-content
+                  grows the trigger for 3-digit sizes and the min keeps the
+                  1-2 digit ones from collapsing narrower than 64px. */}
+              <SelectTrigger
+                aria-label={mergedProps.rowsPerPageLabel}
+                className="w-fit min-w-16"
+                size="sm"
+              >
                 <SelectValue />
               </SelectTrigger>
-              <SelectContent side="top" className="min-w-18">
+              <SelectContent
+                align="start"
+                alignItemWithTrigger={false}
+                className="min-w-(--anchor-width)"
+              >
                 {mergedProps.sizes?.map((size: number) => (
                   <SelectItem key={size} value={`${size}`}>
                     {size}
@@ -179,7 +229,7 @@ function DataGridPagination(props: DataGridPaginationProps): React.JSX.Element {
               {paginationInfo}
             </div>
             {pageCount > 1 && (
-              <div className="order-1 flex items-center space-x-1">
+              <div className="order-1 flex flex-wrap items-center justify-center gap-1 sm:flex-nowrap">
                 <Button
                   size="icon-sm"
                   variant="ghost"
@@ -193,11 +243,49 @@ function DataGridPagination(props: DataGridPaginationProps): React.JSX.Element {
                   <ChevronLeftIcon className="size-4" />
                 </Button>
 
-                {renderEllipsisPrevButton()}
-
-                {renderPageButtons()}
-
-                {renderEllipsisNextButton()}
+                {paginationItems.map((item) =>
+                  item.type === "page" ? (
+                    <Button
+                      key={`page-${item.index}`}
+                      size="sm"
+                      variant="ghost"
+                      aria-label={i18n.labels.goToPage(item.index + 1)}
+                      aria-current={
+                        pageIndex === item.index ? "page" : undefined
+                      }
+                      className={cn(
+                        PAGE_BUTTON_WIDTH_CLASS,
+                        "px-1.5 text-sm",
+                        "text-muted-foreground",
+                        {
+                          "bg-accent text-accent-foreground":
+                            pageIndex === item.index,
+                        }
+                      )}
+                      onClick={() => {
+                        if (pageIndex !== item.index) {
+                          table.setPageIndex(item.index)
+                        }
+                      }}
+                    >
+                      {item.index + 1}
+                    </Button>
+                  ) : (
+                    /* Clickable, unlike the shadcn PaginationEllipsis, which is
+                       an aria-hidden span. This one MOVES the user, so it needs
+                       a name saying where. */
+                    <Button
+                      key={`ellipsis-${item.direction}`}
+                      size="icon-sm"
+                      className={btnBaseClasses}
+                      variant="ghost"
+                      aria-label={i18n.labels.goToPage(item.target + 1)}
+                      onClick={() => table.setPageIndex(item.target)}
+                    >
+                      {mergedProps.ellipsisText}
+                    </Button>
+                  )
+                )}
 
                 <Button
                   size="icon-sm"
diff --git a/apps/web/src/components/reui/data-grid/data-grid-scroll-area.tsx b/apps/web/src/components/reui/data-grid/data-grid-scroll-area.tsx
index f188b27..89e9309 100644
--- a/apps/web/src/components/reui/data-grid/data-grid-scroll-area.tsx
+++ b/apps/web/src/components/reui/data-grid/data-grid-scroll-area.tsx
@@ -1,20 +1,27 @@
-"use client"
+"use no memo"
 
 import {
-  PointerEvent,
-  ReactNode,
   useCallback,
   useEffect,
+  useLayoutEffect,
   useRef,
   useState,
 } from "react"
+import type { PointerEvent, ReactNode } from "react"
 import { useDataGrid } from "@/components/reui/data-grid/data-grid"
+import {
+  DirectionProvider,
+  useDirection,
+} from "@base-ui/react/direction-provider"
 import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area"
 
 import { cn } from "@authportal/ui/lib/utils"
 
 const MIN_THUMB_SIZE = 24
 const FALLBACK_SCROLLBAR_SIZE = 12
+// Gap between each track and the grid edge: the mb-px / me-px on the tracks and
+// the overlay's inset-e-px. The overlay's height math adds it below the bar.
+const SCROLLBAR_EDGE_GAP = 1
 
 const INITIAL_METRICS = {
   hasVerticalOverflow: false,
@@ -25,10 +32,18 @@ const INITIAL_METRICS = {
   trackHeight: 0,
 } as const
 
+// Track footprint: --data-grid-scrollbar-size (10px by default) in both
+// orientations, less 1px for the transparent border and 2px for p-px, so every
+// thumb lands at that size less 3px (7px), held 1px off the grid edge. Thinner
+// was hard to grab; the tracks overlay the last row and column, so the default
+// stays under 12px. The sticky-header overlay below follows the same variable.
 const SCROLLBAR_CLASSNAME =
-  "flex touch-none p-px transition-colors select-none data-[orientation=horizontal]:h-2.5 data-[orientation=horizontal]:flex-col data-[orientation=horizontal]:border-t data-[orientation=horizontal]:border-t-transparent data-[orientation=vertical]:h-full data-[orientation=vertical]:w-2 data-[orientation=vertical]:border-s data-[orientation=vertical]:border-s-transparent"
+  "flex touch-none p-px transition-colors select-none data-[orientation=horizontal]:mb-px data-[orientation=horizontal]:h-[var(--data-grid-scrollbar-size,0.625rem)] data-[orientation=horizontal]:flex-col data-[orientation=horizontal]:border-t data-[orientation=horizontal]:border-t-transparent data-[orientation=vertical]:me-px data-[orientation=vertical]:h-full data-[orientation=vertical]:w-[var(--data-grid-scrollbar-size,0.625rem)] data-[orientation=vertical]:border-s data-[orientation=vertical]:border-s-transparent"
 
-const SCROLLBAR_THUMB_CLASSNAME = "bg-border rounded-full relative flex-1"
+// The ::before reaches the track's outer edge, so the whole track thickness
+// grabs the thumb rather than only its painted 7px.
+const SCROLLBAR_THUMB_CLASSNAME =
+  "bg-border rounded-full relative flex-1 before:absolute before:-inset-0.5"
 
 type DataGridScrollAreaOrientation = "horizontal" | "vertical" | "both"
 
@@ -71,6 +86,19 @@ function areMetricsEqual(next: ScrollbarMetrics, prev: ScrollbarMetrics) {
   )
 }
 
+// A footer held at the bottom (its tfoot or its cells are sticky, however the
+// consumer made them so) takes the track's lower end the way the sticky header
+// takes its top, so the thumb never paints over the totals.
+function getStickyFooterHeight(table: HTMLElement | null) {
+  const footer = table instanceof HTMLTableElement ? table.tFoot : null
+  if (!footer) return 0
+
+  const isSticky = [footer, footer.rows[0]?.cells[0]].some(
+    (element) => element && getComputedStyle(element).position === "sticky"
+  )
+  return isSticky ? footer.getBoundingClientRect().height : 0
+}
+
 function applyMetrics(element: HTMLElement, metrics: ScrollbarMetrics) {
   element.style.setProperty(
     "--data-grid-scrollbar-header-height",
@@ -96,8 +124,9 @@ function DataGridScrollArea({
   orientation = "both",
   ...props
 }: DataGridScrollAreaProps) {
-  const { props: dataGridProps } = useDataGrid()
+  const { props: dataGridProps, table } = useDataGrid()
   const containerRef = useRef<HTMLDivElement>(null)
+  const overlayRef = useRef<HTMLDivElement | null>(null)
   const viewportRef = useRef<HTMLDivElement | null>(null)
   const dragRef = useRef<{
     pointerId: number
@@ -116,21 +145,63 @@ function DataGridScrollArea({
   const showVertical = orientation !== "horizontal"
   const usesCustomVerticalScrollbar =
     showVertical && !!dataGridProps.tableLayout?.headerSticky
+  // Pinned columns are sticky and never scroll, so the horizontal scrollbar
+  // track is inset to span only the scrollable center region between them.
+  const isColumnsPinnable = !!dataGridProps.tableLayout?.columnsPinnable
+  const scrollbarInsetStart = isColumnsPinnable ? table.getStartTotalSize() : 0
+  const scrollbarInsetEnd = isColumnsPinnable ? table.getEndTotalSize() : 0
   const [hasCustomVerticalOverflow, setHasCustomVerticalOverflow] =
     useState(false)
 
+  // Base UI's thumb math reads direction from its own context, which a Radix
+  // app or a bare dir="rtl" page never provides, so RTL scrolled with LTR math
+  // and the thumb froze. RTL is read off the layout instead, so no provider of
+  // any kind is needed. LTR passes the inherited value through untouched: no
+  // state change and no extra render, exactly as before this existed.
+  const inheritedDirection = useDirection()
+  const [isLayoutRtl, setIsLayoutRtl] = useState(false)
+
+  useLayoutEffect(() => {
+    const container = containerRef.current
+    if (!container) return
+
+    const readDirection = () => {
+      const next = getComputedStyle(container).direction === "rtl"
+      setIsLayoutRtl((prev) => (prev === next ? prev : next))
+    }
+
+    readDirection()
+    if (typeof MutationObserver === "undefined") return
+
+    // Only a dir attribute flips it at runtime (an RTL toggle on <html>).
+    const observer = new MutationObserver(readDirection)
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["dir"],
+      subtree: true,
+    })
+    return () => observer.disconnect()
+  }, [])
+
   const clearDragState = useCallback(() => {
     dragRef.current = null
     document.body.style.userSelect = ""
     document.body.style.webkitUserSelect = ""
   }, [])
 
-  const resetMetrics = useCallback(() => {
-    const container = containerRef.current
+  // The overlay is mounted one commit after the sync that detected overflow,
+  // so it misses that sync's write. Seeding it from the ref callback lands the
+  // geometry during commit, before the browser paints the track.
+  const setOverlayRef = useCallback((node: HTMLDivElement | null) => {
+    overlayRef.current = node
 
-    if (container && !areMetricsEqual(INITIAL_METRICS, metricsRef.current)) {
-      applyMetrics(container, INITIAL_METRICS)
+    if (node) applyMetrics(node, metricsRef.current)
+  }, [])
+
+  const resetMetrics = useCallback(() => {
+    if (!areMetricsEqual(INITIAL_METRICS, metricsRef.current)) {
       metricsRef.current = INITIAL_METRICS
+      if (overlayRef.current) applyMetrics(overlayRef.current, INITIAL_METRICS)
     }
 
     setHasCustomVerticalOverflow((prev) => (prev ? false : prev))
@@ -145,8 +216,9 @@ function DataGridScrollArea({
       return
     }
 
-    const { header, horizontalScrollbar } = observedElementsRef.current
+    const { header, horizontalScrollbar, table } = observedElementsRef.current
     const headerHeight = header?.getBoundingClientRect().height ?? 0
+    const footerHeight = getStickyFooterHeight(table)
     const viewportHeight = viewport.clientHeight
     const viewportWidth = viewport.clientWidth
     const scrollHeight = viewport.scrollHeight
@@ -154,11 +226,16 @@ function DataGridScrollArea({
     const hasHorizontalOverflow =
       showHorizontal && scrollWidth > viewportWidth + 0.5
     const horizontalScrollbarSize = hasHorizontalOverflow
-      ? horizontalScrollbar?.offsetHeight || FALLBACK_SCROLLBAR_SIZE
+      ? (horizontalScrollbar?.offsetHeight || FALLBACK_SCROLLBAR_SIZE) +
+        SCROLLBAR_EDGE_GAP
       : 0
+    // The horizontal bar overlays the bottom of the viewport, which a sticky
+    // footer already covers, so only the larger of the two is taken off.
     const trackHeight = Math.max(
       0,
-      viewportHeight - headerHeight - horizontalScrollbarSize
+      viewportHeight -
+        headerHeight -
+        Math.max(footerHeight, horizontalScrollbarSize)
     )
     const maxScroll = Math.max(0, scrollHeight - viewportHeight)
 
@@ -176,7 +253,7 @@ function DataGridScrollArea({
     } else {
       const bodyContentHeight = Math.max(
         trackHeight,
-        scrollHeight - headerHeight
+        scrollHeight - headerHeight - footerHeight
       )
       const thumbHeight = clamp(
         trackHeight * (trackHeight / bodyContentHeight),
@@ -198,8 +275,13 @@ function DataGridScrollArea({
     }
 
     if (!areMetricsEqual(nextMetrics, metricsRef.current)) {
-      applyMetrics(container, nextMetrics)
       metricsRef.current = nextMetrics
+      // Scoped to the overlay, never to the container. These four properties
+      // inherit, and thumbTop changes on essentially every scroll frame, so
+      // writing them on the element that wraps the whole grid invalidates
+      // computed style for every row and cell each frame. The overlay subtree
+      // is their only reader.
+      if (overlayRef.current) applyMetrics(overlayRef.current, nextMetrics)
     }
 
     setHasCustomVerticalOverflow((prev) =>
@@ -220,21 +302,6 @@ function DataGridScrollArea({
       return
     }
 
-    observedElementsRef.current = {
-      header: container.querySelector(
-        '[data-slot="data-grid-table"] thead'
-      ) as HTMLElement | null,
-      horizontalScrollbar: container.querySelector(
-        '[data-slot="data-grid-scrollbar"][data-orientation="horizontal"]'
-      ) as HTMLElement | null,
-      table: container.querySelector(
-        '[data-slot="data-grid-table"]'
-      ) as HTMLElement | null,
-      tableViewport: container.querySelector(
-        '[data-slot="data-grid-table-viewport"]'
-      ) as HTMLElement | null,
-    }
-
     let frame = 0
 
     const scheduleSync = () => {
@@ -242,25 +309,69 @@ function DataGridScrollArea({
       frame = window.requestAnimationFrame(syncCustomVerticalScrollbar)
     }
 
-    scheduleSync()
-    viewport.addEventListener("scroll", scheduleSync, { passive: true })
-
     const observer =
       typeof ResizeObserver === "undefined"
         ? null
         : new ResizeObserver(scheduleSync)
+    const observed = new Set<HTMLElement>()
 
-    observer?.observe(viewport)
-    observedElementsRef.current.header &&
-      observer?.observe(observedElementsRef.current.header)
-    observedElementsRef.current.table &&
-      observer?.observe(observedElementsRef.current.table)
-    observedElementsRef.current.tableViewport &&
-      observer?.observe(observedElementsRef.current.tableViewport)
+    const observeElement = (element: HTMLElement | null) => {
+      if (element && observer && !observed.has(element)) {
+        observer.observe(element)
+        observed.add(element)
+      }
+    }
+
+    const resolveObservedElements = () => {
+      observedElementsRef.current = {
+        header: container.querySelector(
+          '[data-slot="data-grid-table"] thead'
+        ) as HTMLElement | null,
+        horizontalScrollbar: container.querySelector(
+          '[data-slot="data-grid-scrollbar"][data-orientation="horizontal"]'
+        ) as HTMLElement | null,
+        table: container.querySelector(
+          '[data-slot="data-grid-table"]'
+        ) as HTMLElement | null,
+        tableViewport: container.querySelector(
+          '[data-slot="data-grid-table-viewport"]'
+        ) as HTMLElement | null,
+      }
+
+      observeElement(observedElementsRef.current.header)
+      observeElement(observedElementsRef.current.table)
+      observeElement(observedElementsRef.current.tableViewport)
+
+      return !!(
+        observedElementsRef.current.header && observedElementsRef.current.table
+      )
+    }
+
+    observeElement(viewport)
+    const resolvedOnMount = resolveObservedElements()
+
+    scheduleSync()
+    viewport.addEventListener("scroll", scheduleSync, { passive: true })
+
+    // A table that mounts after this effect (empty state swapped for data)
+    // would otherwise never be observed and the custom scrollbar would
+    // overlap the sticky header. One-shot: disconnects once resolved.
+    let mutationObserver: MutationObserver | null = null
+    if (!resolvedOnMount && typeof MutationObserver !== "undefined") {
+      mutationObserver = new MutationObserver(() => {
+        if (resolveObservedElements()) {
+          mutationObserver?.disconnect()
+          mutationObserver = null
+          scheduleSync()
+        }
+      })
+      mutationObserver.observe(container, { childList: true, subtree: true })
+    }
 
     return () => {
       cancelAnimationFrame(frame)
       observer?.disconnect()
+      mutationObserver?.disconnect()
       viewport.removeEventListener("scroll", scheduleSync)
       clearDragState()
     }
@@ -349,76 +460,93 @@ function DataGridScrollArea({
   }
 
   return (
-    <div ref={containerRef} className="relative">
-      <ScrollAreaPrimitive.Root
-        data-slot="data-grid-scroll-area"
-        className={cn("relative", className)}
-        {...props}
-      >
-        <ScrollAreaPrimitive.Viewport
-          ref={viewportRef}
-          data-slot="scroll-area-viewport"
-          className="size-full"
+    <DirectionProvider direction={isLayoutRtl ? "rtl" : inheritedDirection}>
+      <div ref={containerRef} className="relative">
+        <ScrollAreaPrimitive.Root
+          data-slot="data-grid-scroll-area"
+          // Styling hook: present while the sticky-header scroll mode detects
+          // vertical overflow, so consumers can style scrollable vs short
+          // grids with a plain ancestor attribute selector.
+          data-overflow-vertical={
+            hasCustomVerticalOverflow ? "true" : undefined
+          }
+          className={cn("relative", className)}
+          {...props}
         >
-          <ScrollAreaPrimitive.Content data-slot="scroll-area-content">
-            {children}
-          </ScrollAreaPrimitive.Content>
-        </ScrollAreaPrimitive.Viewport>
-
-        {showHorizontal && (
-          <ScrollAreaPrimitive.Scrollbar
-            data-slot="data-grid-scrollbar"
-            data-orientation="horizontal"
-            orientation="horizontal"
-            className={SCROLLBAR_CLASSNAME}
+          <ScrollAreaPrimitive.Viewport
+            ref={viewportRef}
+            data-slot="scroll-area-viewport"
+            className="size-full"
           >
-            <ScrollAreaPrimitive.Thumb
-              data-slot="data-grid-thumb"
-              className={SCROLLBAR_THUMB_CLASSNAME}
-            />
-          </ScrollAreaPrimitive.Scrollbar>
-        )}
+            <ScrollAreaPrimitive.Content data-slot="scroll-area-content">
+              {children}
+            </ScrollAreaPrimitive.Content>
+          </ScrollAreaPrimitive.Viewport>
 
-        {showVertical && !usesCustomVerticalScrollbar && (
-          <ScrollAreaPrimitive.Scrollbar
-            data-slot="data-grid-scrollbar"
-            data-orientation="vertical"
-            orientation="vertical"
-            className={SCROLLBAR_CLASSNAME}
-          >
-            <ScrollAreaPrimitive.Thumb
-              data-slot="data-grid-thumb"
-              className={SCROLLBAR_THUMB_CLASSNAME}
-            />
-          </ScrollAreaPrimitive.Scrollbar>
-        )}
-      </ScrollAreaPrimitive.Root>
+          {showHorizontal && (
+            <ScrollAreaPrimitive.Scrollbar
+              data-slot="data-grid-scrollbar"
+              data-orientation="horizontal"
+              orientation="horizontal"
+              className={SCROLLBAR_CLASSNAME}
+              style={
+                scrollbarInsetStart > 0 || scrollbarInsetEnd > 0
+                  ? {
+                      marginInlineStart: scrollbarInsetStart || undefined,
+                      marginInlineEnd: scrollbarInsetEnd || undefined,
+                    }
+                  : undefined
+              }
+            >
+              <ScrollAreaPrimitive.Thumb
+                data-slot="data-grid-thumb"
+                className={SCROLLBAR_THUMB_CLASSNAME}
+              />
+            </ScrollAreaPrimitive.Scrollbar>
+          )}
 
-      {usesCustomVerticalScrollbar && hasCustomVerticalOverflow && (
-        <div
-          aria-hidden="true"
-          className="pointer-events-none absolute inset-e-0 top-(--data-grid-scrollbar-header-height) z-20 h-(--data-grid-scrollbar-track-height)"
-        >
+          {showVertical && !usesCustomVerticalScrollbar && (
+            <ScrollAreaPrimitive.Scrollbar
+              data-slot="data-grid-scrollbar"
+              data-orientation="vertical"
+              orientation="vertical"
+              className={SCROLLBAR_CLASSNAME}
+            >
+              <ScrollAreaPrimitive.Thumb
+                data-slot="data-grid-thumb"
+                className={SCROLLBAR_THUMB_CLASSNAME}
+              />
+            </ScrollAreaPrimitive.Scrollbar>
+          )}
+        </ScrollAreaPrimitive.Root>
+
+        {usesCustomVerticalScrollbar && hasCustomVerticalOverflow && (
           <div
-            className="pointer-events-auto relative h-full w-2 touch-none p-px"
-            onPointerDown={handleTrackPointerDown}
+            ref={setOverlayRef}
+            aria-hidden="true"
+            className="pointer-events-none absolute inset-e-px top-(--data-grid-scrollbar-header-height) z-20 h-(--data-grid-scrollbar-track-height)"
           >
             <div
-              className={cn(
-                "bg-border absolute end-px w-2",
-                "top-(--data-grid-scrollbar-thumb-top) h-(--data-grid-scrollbar-thumb-height)",
-                "rounded-full"
-              )}
-              onLostPointerCapture={clearDragState}
-              onPointerCancel={handleThumbPointerUp}
-              onPointerDown={handleThumbPointerDown}
-              onPointerMove={handleThumbPointerMove}
-              onPointerUp={handleThumbPointerUp}
-            />
+              className="pointer-events-auto relative h-full w-[var(--data-grid-scrollbar-size,0.625rem)] touch-none p-px"
+              onPointerDown={handleTrackPointerDown}
+            >
+              <div
+                className={cn(
+                  "bg-border absolute end-px w-[calc(var(--data-grid-scrollbar-size,0.625rem)-0.1875rem)]",
+                  "top-(--data-grid-scrollbar-thumb-top) h-(--data-grid-scrollbar-thumb-height)",
+                  "rounded-full before:absolute before:-inset-0.5"
+                )}
+                onLostPointerCapture={clearDragState}
+                onPointerCancel={handleThumbPointerUp}
+                onPointerDown={handleThumbPointerDown}
+                onPointerMove={handleThumbPointerMove}
+                onPointerUp={handleThumbPointerUp}
+              />
+            </div>
           </div>
-        </div>
-      )}
-    </div>
+        )}
+      </div>
+    </DirectionProvider>
   )
 }
 
diff --git a/apps/web/src/components/reui/data-grid/data-grid-table-dnd-rows.tsx b/apps/web/src/components/reui/data-grid/data-grid-table-dnd-rows.tsx
new file mode 100644
index 0000000..71a286b
--- /dev/null
+++ b/apps/web/src/components/reui/data-grid/data-grid-table-dnd-rows.tsx
@@ -0,0 +1,823 @@
+"use client"
+
+// Opted out of React Compiler with the rest of the grid (see data-grid.tsx).
+"use no memo"
+
+import {
+  createContext,
+  memo,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+import type { CSSProperties, ReactNode } from "react"
+import { useDataGrid } from "@/components/reui/data-grid/data-grid"
+import type {
+  DataGridFeatures,
+  DataGridTableInstance,
+} from "@/components/reui/data-grid/data-grid"
+import {
+  DataGridTableBase,
+  DataGridTableBody,
+  DataGridTableBodyRow,
+  DataGridTableBodyRowCell,
+  DataGridTableBodyRowExpandded,
+  DataGridTableBodyRowSkeleton,
+  DataGridTableBodyRowSkeletonCell,
+  DataGridTableEmpty,
+  DataGridTableFillBodyCell,
+  DataGridTableFillHeadCell,
+  DataGridTableFoot,
+  DataGridTableHead,
+  DataGridTableHeadRow,
+  DataGridTableHeadRowCell,
+  DataGridTableHeadRowCellResize,
+  DataGridTableRowSpacer,
+  DataGridTableViewport,
+  getDataGridHeadCellResizeHeader,
+  getDataGridTableMergedHeaderGroups,
+  renderDataGridTableHeadCellContent,
+} from "@/components/reui/data-grid/data-grid-table"
+import {
+  closestCenter,
+  DndContext,
+  DragOverlay,
+  KeyboardSensor,
+  MouseSensor,
+  TouchSensor,
+  useSensor,
+  useSensors,
+  type CollisionDetection,
+  type DndContextProps,
+  type DragCancelEvent,
+  type DragEndEvent,
+  type DragMoveEvent,
+  type DragOverEvent,
+  type DragStartEvent,
+  type Modifier,
+  type UniqueIdentifier,
+} from "@dnd-kit/core"
+import { restrictToVerticalAxis } from "@dnd-kit/modifiers"
+import {
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  type SortingStrategy,
+} from "@dnd-kit/sortable"
+import { CSS } from "@dnd-kit/utilities"
+import { flexRender } from "@tanstack/react-table"
+import type { Cell, Header, Row } from "@tanstack/react-table"
+import { cn } from "@authportal/ui/lib/utils"
+import { createPortal } from "react-dom"
+
+import { Button } from "@authportal/ui/components/button"
+import { GripHorizontalIcon } from "lucide-react"
+
+// Context to share sortable listeners from row to handle
+type SortableContextValue = ReturnType<typeof useSortable>
+const SortableRowContext = createContext<Pick<
+  SortableContextValue,
+  "attributes" | "listeners"
+> | null>(null)
+
+/**
+ * Tree metadata attached to every sortable row, readable from
+ * `active.data.current` / `over.data.current` in any drag event. Cross-parent
+ * drops can be resolved from it without re-deriving the shape of the table.
+ */
+type DataGridTableDndRowData = {
+  type: "data-grid-row"
+  /** Tree depth, 0 for root rows. */
+  depth: number
+  /** Index within the parent's children, or within the root rows. */
+  index: number
+  /** Parent row id, or null for root rows. */
+  parentId: string | null
+}
+
+/**
+ * Per-row render slot for drop indicators and depth guides. The returned node
+ * is positioned over the row, so it never adds a column, shifts striping, or
+ * gets clipped by a truncating resizable cell.
+ */
+type DataGridTableDndRowDecoration<TData extends object> = (context: {
+  row: Row<DataGridFeatures, TData>
+  isDragging: boolean
+  isOver: boolean
+}) => ReactNode
+
+function DataGridTableDndRowHandle({
+  className,
+  disabled,
+  disabledLabel,
+}: {
+  className?: string
+  /**
+   * Renders the grip inert instead of withdrawing it. A grid that reorders on
+   * one truth (manual order) and sorts on another cannot honour both at once,
+   * but dropping the handle entirely collapses the gutter and reads as broken
+   * rather than as unavailable. Keep the column's shape, mute the control.
+   */
+  disabled?: boolean
+  /** Announced and shown on hover in place of the drag affordance. */
+  disabledLabel?: string
+}) {
+  const { i18n } = useDataGrid()
+  const context = useContext(SortableRowContext)
+  const resolvedDisabledLabel =
+    disabledLabel ?? i18n.labels.reorderingUnavailable
+
+  if (!context || disabled) {
+    return (
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        className={cn(
+          "size-7 cursor-grab opacity-70 hover:bg-transparent hover:opacity-100 active:cursor-grabbing",
+          // The Button's own disabled treatment supplies the muting; only the
+          // cursor needs saying, so the grip reads as unavailable rather than
+          // merely unresponsive.
+          disabled && "cursor-not-allowed",
+          className
+        )}
+        aria-label={
+          disabled ? resolvedDisabledLabel : i18n.labels.dragToReorderRow
+        }
+        title={disabled ? resolvedDisabledLabel : undefined}
+        disabled
+      >
+        <GripHorizontalIcon aria-hidden="true" />
+      </Button>
+    )
+  }
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon-sm"
+      className={cn(
+        "size-7 cursor-grab opacity-70 hover:bg-transparent hover:opacity-100 active:cursor-grabbing",
+        className
+      )}
+      aria-label={i18n.labels.dragToReorderRow}
+      {...context.attributes}
+      {...context.listeners}
+    >
+      <GripHorizontalIcon aria-hidden="true" />
+    </Button>
+  )
+}
+
+/**
+ * The rows do not move while one is being carried.
+ *
+ * Sliding the siblings apart opens a gap the carried row could go into, which
+ * reads well in a list of identical rows and badly in a table: the gap is the
+ * height of the row you are holding, so with rows of unequal height it never
+ * matches the slot it claims to be, and the row you picked up slides away from
+ * where it started - which is exactly the position you need to remember if you
+ * decide not to drop it.
+ *
+ * Holding everything still keeps the origin legible, and nothing is lost: the
+ * DragOverlay clone follows the pointer and the drop indicator names the seam.
+ * Pass `verticalListSortingStrategy` as `sortingStrategy` for the old feel.
+ */
+const holdRowsInPlaceStrategy: SortingStrategy = () => null
+
+function DataGridTableDndRow<TData extends object>({
+  row,
+  renderRowDecoration,
+  dropIndicator = true,
+}: {
+  row: Row<DataGridFeatures, TData>
+  renderRowDecoration?: DataGridTableDndRowDecoration<TData>
+  dropIndicator?: boolean
+}) {
+  const rowData: DataGridTableDndRowData = {
+    type: "data-grid-row",
+    depth: row.depth,
+    index: row.index,
+    parentId: row.getParentRow()?.id ?? null,
+  }
+
+  const {
+    transform,
+    setNodeRef,
+    isDragging,
+    isOver,
+    attributes,
+    listeners,
+    index,
+    activeIndex,
+    overIndex,
+  } = useSortable({
+    id: row.id,
+    data: rowData,
+  })
+
+  // Which edge of THIS row the carried row would land on, or null when it is
+  // not the drop target. Nothing slides apart any more, so the bar is the only
+  // thing that says where the drop goes: it marks the row at the destination
+  // index, on the side the carried row comes to rest.
+  //
+  // Dragging down it lands after the target, dragging up before it, so the
+  // edge follows the direction of travel.
+  const dropEdge =
+    dropIndicator && activeIndex !== -1 && index === overIndex && !isDragging
+      ? activeIndex < overIndex
+        ? "bottom"
+        : "top"
+      : null
+
+  const style: CSSProperties = {
+    transform: CSS.Transform.toString(transform),
+    // dnd-kit's transition is deliberately dropped. A transition on a transform
+    // property of a `tr` does not merely fail to animate in Chrome, it stops the
+    // transform applying at all: the element sits at the start value forever.
+    // The drag source escapes it because dnd-kit disables its own transition
+    // while it is being dragged, which is why the carried row used to be the
+    // ONLY one that moved and every other row silently refused to open a gap.
+    // Displacement therefore lands in one step, which is what a table wants.
+    zIndex: isDragging ? 1 : 0,
+    position: "relative",
+    cursor: isDragging ? "grabbing" : undefined,
+    // The row you are holding is drawn by the DragOverlay, so the one left
+    // behind is not a second copy of it - it is the slot you came from, and it
+    // stays exactly where it was. Fading alone read as "this row is busy";
+    // the outline says "this is the space you are moving out of", which is the
+    // thing you need if you change your mind mid-drag.
+    ...(isDragging && {
+      opacity: 0.4,
+      // Inset so the dashes sit inside the row box and cannot be clipped by
+      // the neighbouring row's border.
+      outline: "1px dashed var(--border)",
+      outlineOffset: "-1px",
+    }),
+  }
+
+  const decoration = renderRowDecoration?.({ row, isDragging, isOver })
+  const cells = row.getVisibleCells()
+  const lastCell = cells[cells.length - 1]
+
+  const renderCell = (cell: Cell<DataGridFeatures, TData, unknown>) => (
+    <DataGridTableBodyRowCell cell={cell} key={cell.id}>
+      {flexRender(cell.column.columnDef.cell, cell.getContext())}
+      {decoration && cell === lastCell ? (
+        // Rides inside the last cell rather than in a `td` of its own.
+        // An absolutely positioned `td` is still a cell as far as table
+        // layout is concerned, so it added a NINTH column with no width
+        // of its own, and under `table-layout: fixed` that new column
+        // swallowed the whole surplus the real columns had been sharing,
+        // so every column snapped back to its declared size and the row's
+        // content visibly narrowed the moment a drag began. A plain
+        // element adds no column. It anchors to the ROW, the nearest
+        // positioned ancestor, and spans the full width, unless the last
+        // cell is a sticky end-pinned one: that cell is positioned itself
+        // and confines the decoration to its own width.
+        <div
+          aria-hidden="true"
+          data-slot="data-grid-table-row-decoration"
+          className="pointer-events-none absolute inset-0"
+        >
+          {decoration}
+        </div>
+      ) : null}
+      {dropEdge && cell === lastCell ? (
+        // Same anchoring trick as the decoration above: a plain
+        // element inside the last cell, so it adds no column and
+        // cannot disturb `table-layout: fixed`. It spans the row, with
+        // the same sticky end-pinned exception.
+        <div
+          aria-hidden="true"
+          data-slot="data-grid-table-row-drop-indicator"
+          data-edge={dropEdge}
+          className="pointer-events-none absolute inset-0 z-20"
+        >
+          {/* Two solid pixels down the leading edge, the same marker
+              the tree drag uses for its drop target. A wash across
+              the row has to stay faint enough not to read as a
+              selected row, and in the achromatic styles primary
+              carries no chroma at all, so faint plus colourless is
+              just grey. The bar reads at any weight and leaves the
+              row's own background to hover and selection.
+
+              The bar is the whole indicator: the gap the rows have
+              already opened says which side, so a rule across the
+              seam as well only competes with the row borders it sits
+              between. `data-edge` still carries the direction for
+              anyone styling their own. */}
+          <span className="bg-primary absolute inset-y-0 start-0 w-0.5" />
+        </div>
+      ) : null}
+    </DataGridTableBodyRowCell>
+  )
+
+  return (
+    <SortableRowContext.Provider value={{ attributes, listeners }}>
+      <DataGridTableBodyRow
+        row={row}
+        dndRef={setNodeRef}
+        dndStyle={style}
+        dndDragging={isDragging}
+      >
+        {/* One keyed list with the fill in the middle, as in the head row. */}
+        {[
+          ...cells
+            .filter((cell) => cell.column.getIsPinned() !== "end")
+            .map(renderCell),
+          <DataGridTableFillBodyCell key="__data-grid-fill" />,
+          ...cells
+            .filter((cell) => cell.column.getIsPinned() === "end")
+            .map(renderCell),
+        ]}
+      </DataGridTableBodyRow>
+      {row.getIsExpanded() && <DataGridTableBodyRowExpandded row={row} />}
+    </SortableRowContext.Provider>
+  )
+}
+
+function DataGridTableDndRowsBody<TData extends object>({
+  table,
+  dataIds,
+  renderRowDecoration,
+  dropIndicator,
+  sortingStrategy,
+}: {
+  table: DataGridTableInstance<TData>
+  dataIds: UniqueIdentifier[]
+  renderRowDecoration?: DataGridTableDndRowDecoration<TData>
+  dropIndicator?: boolean
+  sortingStrategy: SortingStrategy
+}) {
+  const { isLoading, props } = useDataGrid()
+  const pagination = table.state.pagination
+
+  if (props.loadingMode === "skeleton" && isLoading && pagination?.pageSize) {
+    return (
+      <>
+        {Array.from({ length: pagination.pageSize }).map((_, rowIndex) => (
+          <DataGridTableBodyRowSkeleton key={rowIndex}>
+            {[
+              ...[
+                ...table.getStartVisibleLeafColumns(),
+                ...table.getCenterVisibleLeafColumns(),
+              ].map((column) => (
+                <DataGridTableBodyRowSkeletonCell
+                  column={column}
+                  key={column.id}
+                >
+                  {column.columnDef.meta?.skeleton}
+                </DataGridTableBodyRowSkeletonCell>
+              )),
+              <DataGridTableFillBodyCell key="__data-grid-fill" />,
+              ...table.getEndVisibleLeafColumns().map((column) => (
+                <DataGridTableBodyRowSkeletonCell
+                  column={column}
+                  key={column.id}
+                >
+                  {column.columnDef.meta?.skeleton}
+                </DataGridTableBodyRowSkeletonCell>
+              )),
+            ]}
+          </DataGridTableBodyRowSkeleton>
+        ))}
+      </>
+    )
+  }
+
+  if (!table.getRowModel().rows.length) return <DataGridTableEmpty />
+
+  return (
+    <SortableContext items={dataIds} strategy={sortingStrategy}>
+      {table.getRowModel().rows.map((row: Row<DataGridFeatures, TData>) => {
+        return (
+          <DataGridTableDndRow
+            row={row}
+            renderRowDecoration={renderRowDecoration}
+            dropIndicator={dropIndicator}
+            key={row.id}
+          />
+        )
+      })}
+    </SortableContext>
+  )
+}
+
+/**
+ * Memoized body rows: skip re-renders during active column resize.
+ * Column widths update via CSS variables on the <table> element,
+ * so the browser handles width changes without React re-renders.
+ */
+const MemoizedDataGridTableDndRowsBody = memo(
+  DataGridTableDndRowsBody,
+  (_prev, next) => !!next.table.state.columnResizing?.isResizingColumn
+) as typeof DataGridTableDndRowsBody
+
+function DataGridTableDndRows<TData extends object>({
+  handleDragEnd,
+  dataIds,
+  footerContent,
+  collisionDetection = closestCenter,
+  modifiers,
+  sortingStrategy = holdRowsInPlaceStrategy,
+  renderRowDecoration,
+  dropIndicator = true,
+  onDragStart,
+  onDragMove,
+  onDragOver,
+  onDragCancel,
+  accessibility,
+}: {
+  handleDragEnd: (event: DragEndEvent) => void
+  dataIds: UniqueIdentifier[]
+  footerContent?: ReactNode
+  /** Overrides the default `closestCenter` strategy. */
+  collisionDetection?: CollisionDetection
+  /**
+   * Replaces the default axis restriction, e.g. drop `restrictToVerticalAxis`
+   * to allow the horizontal gesture that tree re-parenting relies on. The
+   * table container clamp is always applied after these, so a dragged row
+   * cannot leave the grid.
+   */
+  modifiers?: Modifier[]
+  /**
+   * Replaces the default `verticalListSortingStrategy`. Return null from a
+   * strategy to leave every row exactly where it is. A tree needs that: its drop
+   * is either INTO the hovered row or BETWEEN two rows, and which one it is
+   * flips as the pointer crosses a single row, so a gap that opens for one and
+   * shuts for the other flickers the whole surface. Such a caller draws its own
+   * insertion line instead, and pairs this with a modifier that holds the
+   * carried row still, since a gap nothing moves into is just a hole.
+   */
+  sortingStrategy?: SortingStrategy
+  /** Per-row slot for drop indicators and depth guides. */
+  renderRowDecoration?: DataGridTableDndRowDecoration<TData>
+  /**
+   * Draws a line on the seam the carried row would land on. On by default;
+   * pass `false` when `renderRowDecoration` paints its own insertion affordance
+   * and the two would compete.
+   */
+  dropIndicator?: boolean
+  onDragStart?: (event: DragStartEvent) => void
+  onDragMove?: (event: DragMoveEvent) => void
+  onDragOver?: (event: DragOverEvent) => void
+  onDragCancel?: (event: DragCancelEvent) => void
+  /**
+   * Forwarded to dnd-kit's `DndContext`: its screen-reader instructions and
+   * live-region announcements, which default to dnd-kit's English strings.
+   */
+  accessibility?: DndContextProps["accessibility"]
+}) {
+  const { table, props } = useDataGrid<TData>()
+  const mergedHeaderGroups = getDataGridTableMergedHeaderGroups(table)
+  const tableContainerRef = useRef<HTMLDivElement>(null)
+  const [isDraggingRow, setIsDraggingRow] = useState(false)
+  // The overlay is portalled to the document body. dnd-kit renders DragOverlay
+  // in place, and it positions with `position: fixed` against viewport
+  // coordinates - so any ancestor that establishes a containing block for fixed
+  // descendants silently re-anchors it. `content-visibility`, `contain`,
+  // `transform`, `filter` and `will-change` all do that, and the first two are
+  // exactly what a card grid uses to defer off-screen work. The clone then
+  // lands offset by that ancestor's own top/left, and the container clamp
+  // below mis-clamps too, because its rects are measured in viewport space.
+  //
+  // Resolved in an effect rather than read at render so the server and the
+  // first client render agree. A drag cannot start before hydration, so the
+  // overlay being absent for one frame costs nothing.
+  const [portalTarget, setPortalTarget] = useState<HTMLElement | null>(null)
+
+  useEffect(() => {
+    setPortalTarget(document.body)
+  }, [])
+  // The row being carried, plus the column widths measured off the header the
+  // moment the drag starts. The clone lives outside the table, so it has no
+  // columns of its own and has to be told what they are.
+  const [carried, setCarried] = useState<{
+    id: UniqueIdentifier
+    width: number
+    height: number
+    columns: number[]
+    padding: { start: string; end: string }[]
+  } | null>(null)
+
+  const pickUpRow = useCallback((id: UniqueIdentifier) => {
+    const container = tableContainerRef.current
+    const head = container?.querySelector("thead tr")
+    if (!container || !head) {
+      setCarried(null)
+      return
+    }
+
+    // The clone has to be exactly as tall as the row it was lifted from.
+    // A fixed height reads as the grid growing under the pointer the moment
+    // you pick a row up, and it is wrong in both directions: rows whose
+    // content wraps are taller than any constant, and dense rows are shorter.
+    const source = Array.from(
+      container.querySelectorAll<HTMLElement>("tbody tr[data-row-id]")
+    ).find((candidate) => candidate.dataset.rowId === String(id))
+    const height = source?.getBoundingClientRect().height ?? 0
+
+    // The fill cell is a spacer that soaks up the surplus a column resize
+    // leaves behind, and the clone renders data cells only. Measuring it in
+    // would make the clone's table wider than the cells it actually holds,
+    // and `table-fixed` hands that orphaned width back out across every column
+    // -- the carried row comes out visibly wider than the row it was lifted
+    // from. So the width is the sum of what we render, never the header's own.
+    // Read off the source row, one cell per column: a head cell can span
+    // several (a group, a merged or a meta.headerColSpan cell).
+    const columns = Array.from(source?.children ?? head.children)
+      .filter(
+        (cell) =>
+          cell.getAttribute("data-slot") !== "data-grid-table-fill-body-cell" &&
+          cell.getAttribute("data-slot") !== "data-grid-table-fill-head-cell"
+      )
+      .map((cell) => cell.getBoundingClientRect().width)
+
+    // Inline padding is read off the source cells for the same reason. A fixed
+    // px-3 ignored edgeCell and cellClassName, so a 44px grip column holding a
+    // 28px handle overflowed by 8px and truncate painted an ellipsis beside it.
+    const padding = Array.from(source?.children ?? [])
+      .filter(
+        (cell) =>
+          cell.getAttribute("data-slot") !== "data-grid-table-fill-body-cell"
+      )
+      .map((cell) => {
+        const style = getComputedStyle(cell)
+        return { start: style.paddingInlineStart, end: style.paddingInlineEnd }
+      })
+
+    setCarried({
+      id,
+      width: columns.reduce((total, width) => total + width, 0),
+      height,
+      columns,
+      padding,
+    })
+  }, [])
+
+  const carriedRow = carried
+    ? table
+        .getRowModel()
+        .rows.find((row: Row<DataGridFeatures, TData>) => row.id === carried.id)
+    : undefined
+
+  const sensors = useSensors(
+    useSensor(MouseSensor, {}),
+    useSensor(TouchSensor, {}),
+    // Keyboard reordering moves one sortable position per keypress instead
+    // of the sensor's raw 25px default.
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    })
+  )
+
+  useEffect(() => {
+    if (!isDraggingRow) return
+
+    const { body, documentElement } = document
+    const previousBodyCursor = body.style.cursor
+    const previousDocumentCursor = documentElement.style.cursor
+
+    body.style.cursor = "grabbing"
+    documentElement.style.cursor = "grabbing"
+
+    return () => {
+      body.style.cursor = previousBodyCursor
+      documentElement.style.cursor = previousDocumentCursor
+    }
+  }, [isDraggingRow])
+
+  const resolvedModifiers = useMemo(() => {
+    const restrictToTableContainer: Modifier = ({
+      transform,
+      draggingNodeRect,
+    }) => {
+      if (!tableContainerRef.current || !draggingNodeRect) {
+        return transform
+      }
+
+      const containerRect = tableContainerRef.current.getBoundingClientRect()
+      const { x, y } = transform
+
+      const minX = containerRect.left - draggingNodeRect.left
+      const maxX = containerRect.right - draggingNodeRect.right
+      const minY = containerRect.top - draggingNodeRect.top
+      const maxY = containerRect.bottom - draggingNodeRect.bottom
+
+      return {
+        ...transform,
+        // The horizontal rail only engages while the default axis restriction
+        // is in force. A row is exactly as wide as the viewport, so minX and
+        // maxX both collapse to 0 and clamping x erases it entirely: harmless
+        // under restrictToVerticalAxis, which zeroes x anyway, but fatal for a
+        // caller that replaced the restriction precisely to READ x, as a tree
+        // does to resolve drop depth. Vertical is railed either way, which is
+        // what actually keeps a dragged row inside the grid.
+        x: modifiers ? x : Math.max(minX, Math.min(maxX, x)),
+        y: Math.max(minY, Math.min(maxY, y)),
+      }
+    }
+
+    // The container clamp is a safety rail rather than a policy, so it stays
+    // applied even when the caller replaces the axis restriction.
+    return [
+      ...(modifiers ?? [restrictToVerticalAxis]),
+      restrictToTableContainer,
+    ]
+  }, [modifiers])
+
+  return (
+    <DndContext
+      id={useId()}
+      accessibility={accessibility}
+      collisionDetection={collisionDetection}
+      modifiers={resolvedModifiers}
+      onDragCancel={(event) => {
+        setIsDraggingRow(false)
+        setCarried(null)
+        onDragCancel?.(event)
+      }}
+      onDragEnd={(event) => {
+        setIsDraggingRow(false)
+        setCarried(null)
+        handleDragEnd(event)
+      }}
+      onDragMove={onDragMove}
+      onDragOver={onDragOver}
+      onDragStart={(event) => {
+        setIsDraggingRow(true)
+        pickUpRow(event.active.id)
+        onDragStart?.(event)
+      }}
+      sensors={sensors}
+    >
+      <DataGridTableViewport
+        viewportRef={tableContainerRef}
+        className={
+          isDraggingRow
+            ? "relative cursor-grabbing [&_*]:cursor-grabbing!"
+            : "relative"
+        }
+      >
+        <DataGridTableBase>
+          <DataGridTableHead>
+            {mergedHeaderGroups.map((headerGroup, index) => {
+              const renderHeader = (
+                header: Header<DataGridFeatures, TData, unknown>
+              ) => {
+                const coveredHeaders = headerGroup.coveredHeaders.get(header.id)
+                const resizeHeader = getDataGridHeadCellResizeHeader(
+                  header,
+                  coveredHeaders
+                )
+
+                return (
+                  <DataGridTableHeadRowCell
+                    header={header}
+                    coveredHeaders={coveredHeaders}
+                    key={header.id}
+                  >
+                    {renderDataGridTableHeadCellContent(header)}
+                    {props.tableLayout?.columnsResizable &&
+                      resizeHeader.column.getCanResize() && (
+                        <DataGridTableHeadRowCellResize header={resizeHeader} />
+                      )}
+                  </DataGridTableHeadRowCell>
+                )
+              }
+
+              return (
+                <DataGridTableHeadRow key={index} rowId={headerGroup.id}>
+                  {/* Every row follows DataGridTableBase's colgroup, which
+                      puts the fill col between the center and end-pinned
+                      groups; a fill cell appended last hands its width to
+                      the end-pinned column. One keyed list, not three, so
+                      a column pinned into or out of the end group moves
+                      instead of remounting, which would drop keyboard
+                      focus. The fill spans every head row, so only the
+                      first renders it. */}
+                  {[
+                    ...[
+                      ...headerGroup.startHeaders,
+                      ...headerGroup.centerHeaders,
+                    ].map(renderHeader),
+                    ...(index === 0
+                      ? [
+                          <DataGridTableFillHeadCell
+                            key="__data-grid-fill"
+                            rowSpan={mergedHeaderGroups.length}
+                          />,
+                        ]
+                      : []),
+                    ...headerGroup.endHeaders.map(renderHeader),
+                  ]}
+                </DataGridTableHeadRow>
+              )
+            })}
+          </DataGridTableHead>
+
+          {(props.tableLayout?.stripped || !props.tableLayout?.rowBorder) && (
+            <DataGridTableRowSpacer />
+          )}
+
+          <DataGridTableBody>
+            <MemoizedDataGridTableDndRowsBody
+              table={table}
+              dataIds={dataIds}
+              renderRowDecoration={renderRowDecoration}
+              dropIndicator={dropIndicator}
+              sortingStrategy={sortingStrategy}
+            />
+          </DataGridTableBody>
+
+          {footerContent && (
+            <DataGridTableFoot>{footerContent}</DataGridTableFoot>
+          )}
+        </DataGridTableBase>
+      </DataGridTableViewport>
+
+      {/* The row you are actually holding. It is a real clone rendered outside
+          the table, which is the only way a dragged row can follow the pointer
+          without disturbing the grid: it adds no cell, so it cannot alter the
+          column widths, and it floats above the rows rather than through them.
+          Its presence also tells dnd-kit to stop translating the source row, so
+          the row left behind simply dims in place.
+
+          Portalled to the body so the fixed positioning resolves against the
+          viewport wherever the grid is mounted. React context crosses a portal,
+          so DndContext still reaches it. */}
+      {portalTarget
+        ? createPortal(
+            <DragOverlay dropAnimation={null}>
+              {carried && carriedRow ? (
+                <table
+                  aria-hidden="true"
+                  style={{ width: carried.width, tableLayout: "fixed" }}
+                  className="bg-background border-border pointer-events-none cursor-grabbing rounded-md border shadow-lg"
+                >
+                  <tbody>
+                    {/* Padding rides on the inner element, not the cell. A `td` can
+                  never render narrower than its own horizontal padding, so a
+                  column resized below that would silently widen here and the
+                  clone would stop matching the row it came from. Height comes
+                  from the measured source row for the same reason the widths
+                  do: the clone has no row of its own to inherit it from. */}
+                    <tr
+                      style={{ height: carried.height || undefined }}
+                      className="[&>td]:p-0 [&>td]:align-middle"
+                    >
+                      {carriedRow
+                        .getVisibleCells()
+                        .map(
+                          (
+                            cell: Cell<DataGridFeatures, TData, unknown>,
+                            index: number
+                          ) => (
+                            <td
+                              key={cell.id}
+                              // Falls back to the column's own size so an unforeseen
+                              // header/cell count mismatch degrades to a real width
+                              // rather than to `auto`.
+                              style={{
+                                width:
+                                  carried.columns[index] ??
+                                  cell.column.getSize(),
+                              }}
+                            >
+                              <div
+                                className={cn(
+                                  "truncate",
+                                  !carried.padding[index] && "px-3"
+                                )}
+                                style={{
+                                  paddingInlineStart:
+                                    carried.padding[index]?.start,
+                                  paddingInlineEnd: carried.padding[index]?.end,
+                                }}
+                              >
+                                {flexRender(
+                                  cell.column.columnDef.cell,
+                                  cell.getContext()
+                                )}
+                              </div>
+                            </td>
+                          )
+                        )}
+                    </tr>
+                  </tbody>
+                </table>
+              ) : null}
+            </DragOverlay>,
+            portalTarget
+          )
+        : null}
+    </DndContext>
+  )
+}
+
+export { DataGridTableDndRowHandle, DataGridTableDndRows }
+export type { DataGridTableDndRowData, DataGridTableDndRowDecoration }
\ No newline at end of file
diff --git a/apps/web/src/components/reui/data-grid/data-grid-table-dnd.tsx b/apps/web/src/components/reui/data-grid/data-grid-table-dnd.tsx
new file mode 100644
index 0000000..672e9da
--- /dev/null
+++ b/apps/web/src/components/reui/data-grid/data-grid-table-dnd.tsx
@@ -0,0 +1,551 @@
+"use no memo"
+
+import {
+  Fragment,
+  memo,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+import type { CSSProperties, ReactNode } from "react"
+import {
+  getDataGridHeaderSpans,
+  useDataGrid,
+} from "@/components/reui/data-grid/data-grid"
+import type {
+  DataGridFeatures,
+  DataGridTableInstance,
+} from "@/components/reui/data-grid/data-grid"
+import {
+  DataGridTableBase,
+  DataGridTableBody,
+  DataGridTableBodyRow,
+  DataGridTableBodyRowCell,
+  DataGridTableBodyRowExpandded,
+  DataGridTableBodyRowSkeleton,
+  DataGridTableBodyRowSkeletonCell,
+  DataGridTableEmpty,
+  DataGridTableFillBodyCell,
+  DataGridTableFillHeadCell,
+  DataGridTableFoot,
+  DataGridTableHead,
+  DataGridTableHeadRow,
+  DataGridTableHeadRowCell,
+  DataGridTableHeadRowCellResize,
+  DataGridTableRowSpacer,
+  DataGridTableViewport,
+  getDataGridHeadCellResizeHeader,
+  getDataGridHeadCellSizeVar,
+  getDataGridTableMergedHeaderGroups,
+  renderDataGridTableHeadCellContent,
+} from "@/components/reui/data-grid/data-grid-table"
+import {
+  closestCenter,
+  DndContext,
+  KeyboardSensor,
+  MouseSensor,
+  TouchSensor,
+  useSensor,
+  useSensors,
+  type DndContextProps,
+  type DragEndEvent,
+  type KeyboardSensorProps,
+  type Modifier,
+} from "@dnd-kit/core"
+import {
+  horizontalListSortingStrategy,
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+} from "@dnd-kit/sortable"
+import { CSS } from "@dnd-kit/utilities"
+import { flexRender } from "@tanstack/react-table"
+import type { Cell, Header, Row } from "@tanstack/react-table"
+
+import { Button } from "@authportal/ui/components/button"
+import { GripVerticalIcon } from "lucide-react"
+
+function DataGridTableDndHeader<TData extends object>({
+  header,
+  coveredHeaders = [],
+}: {
+  header: Header<DataGridFeatures, TData, unknown>
+  /** Headers this cell spans through meta.headerColSpan. */
+  coveredHeaders?: Header<DataGridFeatures, TData, unknown>[]
+}) {
+  const { i18n, props } = useDataGrid()
+  const { column } = header
+
+  // Pinning decides where a pinned column renders whatever columnOrder says,
+  // so dragging one could only rewrite hidden order. It gets no grip and is
+  // neither a drag source nor a drop target. Neither is a group cell: its
+  // id is not in columnOrder, which holds leaves only.
+  const isPinned = !!column.getIsPinned()
+  const isGroup = column.columns.length > 0
+  // A span is no drag source: a drop moves one leaf, never its covered ones.
+  const isSpan = coveredHeaders.length > 0
+  const canOrder =
+    (column.columnDef as { enableColumnOrdering?: boolean })
+      .enableColumnOrdering !== false &&
+    !isPinned &&
+    !isGroup &&
+    !isSpan
+
+  const {
+    attributes,
+    isDragging,
+    listeners,
+    setNodeRef,
+    transform,
+    transition,
+  } = useSortable({
+    id: header.column.id,
+    disabled: isPinned || isGroup || isSpan,
+  })
+  const resizeHeader = getDataGridHeadCellResizeHeader(header, coveredHeaders)
+
+  // This style spreads after getPinningStyles, so a sticky pinned cell must
+  // not take the drag keys: relative and z-index 0 would unstick it and sink
+  // it under the centre cells. Omitted, not undefined, which would still win.
+  const isSticky =
+    !!props.tableLayout?.columnsPinnable && column.getCanPin() && isPinned
+
+  const style: CSSProperties = {
+    opacity: isDragging ? 0.8 : 1,
+    ...(!isSticky && {
+      position: "relative",
+      transform: CSS.Translate.toString(transform),
+      zIndex: isDragging ? 1 : 0,
+    }),
+    transition,
+    cursor: isDragging ? "grabbing" : undefined,
+    whiteSpace: "nowrap",
+    width: props.tableLayout?.columnsResizable
+      ? getDataGridHeadCellSizeVar(header, coveredHeaders)
+      : coveredHeaders.reduce(
+          (sum, covered) => sum + covered.column.getSize(),
+          header.column.getSize()
+        ),
+  }
+
+  return (
+    <DataGridTableHeadRowCell
+      header={header}
+      coveredHeaders={coveredHeaders}
+      dndStyle={style}
+      dndRef={setNodeRef}
+    >
+      <div className="flex items-center justify-start gap-0.5">
+        {canOrder && (
+          <Button
+            size="icon-sm"
+            variant="ghost"
+            className={`-ms-2 size-6 ${isDragging ? "cursor-grabbing" : "cursor-grab active:cursor-grabbing"}`}
+            {...attributes}
+            {...listeners}
+            aria-label={i18n.labels.dragToReorder}
+          >
+            <GripVerticalIcon className="opacity-60 hover:opacity-100" aria-hidden="true" />
+          </Button>
+        )}
+        <div className="grow">{renderDataGridTableHeadCellContent(header)}</div>
+        {props.tableLayout?.columnsResizable &&
+          resizeHeader.column.getCanResize() && (
+            <DataGridTableHeadRowCellResize header={resizeHeader} />
+          )}
+      </div>
+    </DataGridTableHeadRowCell>
+  )
+}
+
+function DataGridTableDndCell<TData extends object>({
+  cell,
+}: {
+  cell: Cell<DataGridFeatures, TData, unknown>
+}) {
+  const { props } = useDataGrid()
+  const { isDragging, setNodeRef, transform, transition } = useSortable({
+    id: cell.column.id,
+    disabled: !!cell.column.getIsPinned(),
+  })
+
+  // Same rule as the header: a sticky pinned cell keeps its pinning styles.
+  const isSticky =
+    !!props.tableLayout?.columnsPinnable &&
+    cell.column.getCanPin() &&
+    !!cell.column.getIsPinned()
+
+  const style: CSSProperties = {
+    opacity: isDragging ? 0.8 : 1,
+    ...(!isSticky && {
+      position: "relative",
+      transform: CSS.Translate.toString(transform),
+      zIndex: isDragging ? 1 : 0,
+    }),
+    transition,
+    cursor: isDragging ? "grabbing" : undefined,
+    width: props.tableLayout?.columnsResizable
+      ? `calc(var(--col-${cell.column.id}-size) * 1px)`
+      : cell.column.getSize(),
+  }
+
+  return (
+    <DataGridTableBodyRowCell cell={cell} dndStyle={style} dndRef={setNodeRef}>
+      {flexRender(cell.column.columnDef.cell, cell.getContext())}
+    </DataGridTableBodyRowCell>
+  )
+}
+
+function DataGridTableDndBodyRows<TData extends object>({
+  table,
+}: {
+  table: DataGridTableInstance<TData>
+}) {
+  const { isLoading, props } = useDataGrid()
+  const pagination = table.state.pagination
+
+  if (props.loadingMode === "skeleton" && isLoading && pagination?.pageSize) {
+    return (
+      <>
+        {Array.from({ length: pagination.pageSize }).map((_, rowIndex) => (
+          <DataGridTableBodyRowSkeleton key={rowIndex}>
+            {[
+              ...[
+                ...table.getStartVisibleLeafColumns(),
+                ...table.getCenterVisibleLeafColumns(),
+              ].map((column) => (
+                <DataGridTableBodyRowSkeletonCell
+                  column={column}
+                  key={column.id}
+                >
+                  {column.columnDef.meta?.skeleton}
+                </DataGridTableBodyRowSkeletonCell>
+              )),
+              <DataGridTableFillBodyCell key="__data-grid-fill" />,
+              ...table.getEndVisibleLeafColumns().map((column) => (
+                <DataGridTableBodyRowSkeletonCell
+                  column={column}
+                  key={column.id}
+                >
+                  {column.columnDef.meta?.skeleton}
+                </DataGridTableBodyRowSkeletonCell>
+              )),
+            ]}
+          </DataGridTableBodyRowSkeleton>
+        ))}
+      </>
+    )
+  }
+
+  if (!table.getRowModel().rows.length) return <DataGridTableEmpty />
+
+  return (
+    <>
+      {table.getRowModel().rows.map((row: Row<DataGridFeatures, TData>) => {
+        return (
+          <Fragment key={row.id}>
+            <DataGridTableBodyRow row={row}>
+              <SortableContext
+                items={table.state.columnOrder}
+                strategy={horizontalListSortingStrategy}
+              >
+                {/* One keyed list with the fill in the middle, as in the
+                    head row below. */}
+                {[
+                  ...[
+                    ...row.getStartVisibleCells(),
+                    ...row.getCenterVisibleCells(),
+                  ].map((cell: Cell<DataGridFeatures, TData, unknown>) => (
+                    <DataGridTableDndCell cell={cell} key={cell.id} />
+                  )),
+                  <DataGridTableFillBodyCell key="__data-grid-fill" />,
+                  ...row
+                    .getEndVisibleCells()
+                    .map((cell: Cell<DataGridFeatures, TData, unknown>) => (
+                      <DataGridTableDndCell cell={cell} key={cell.id} />
+                    )),
+                ]}
+              </SortableContext>
+            </DataGridTableBodyRow>
+            {row.getIsExpanded() && <DataGridTableBodyRowExpandded row={row} />}
+          </Fragment>
+        )
+      })}
+    </>
+  )
+}
+
+/**
+ * Memoized body rows: skip re-renders during active column resize.
+ * Column widths update via CSS variables on the <table> element,
+ * so the browser handles width changes without React re-renders.
+ */
+const MemoizedDataGridTableDndBodyRows = memo(
+  DataGridTableDndBodyRows,
+  (_prev, next) => !!next.table.state.columnResizing?.isResizingColumn
+) as typeof DataGridTableDndBodyRows
+
+// dnd-kit's KeyboardSensor scrolls instead of moving when the target sits
+// past the middle of a scroller, and assumes scrollLeft runs 0 to max. RTL
+// runs -max to 0, so from the start edge ArrowRight became a scrollTo that
+// clamps to 0 and swallowed the keypress. The sensor gets an LTR-shaped view
+// of RTL scrollers, scrolled instantly: a smooth scroll drops a key pressed
+// before it settles. The document scroller and the coordinate getter's copy
+// stay real elements: both are matched by identity inside dnd-kit.
+function toLtrScrollView(element: Element): Element {
+  if (
+    element === element.ownerDocument.scrollingElement ||
+    getComputedStyle(element).direction !== "rtl"
+  ) {
+    return element
+  }
+  const offset = () => element.scrollWidth - element.clientWidth
+  return new Proxy(element, {
+    get(target, key) {
+      if (key === "scrollLeft") return target.scrollLeft + offset()
+      if (key === "scrollTo") {
+        return (options: ScrollToOptions) =>
+          target.scrollTo(
+            options.left === undefined
+              ? options
+              : {
+                  ...options,
+                  left: options.left - offset(),
+                  behavior: "instant",
+                }
+          )
+      }
+      const value = Reflect.get(target, key)
+      return typeof value === "function" ? value.bind(target) : value
+    },
+  })
+}
+
+/** A drop on a span's leaves targets its far edge, after its last leaf moving
+ *  forward and before its owner moving back, so no move lands inside it. */
+function getDataGridDropBesideSpans<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  event: DragEndEvent
+): DragEndEvent {
+  const { active, over } = event
+  if (!over || active.id === over.id) return event
+
+  const rendered = [
+    ...table.getStartVisibleLeafColumns(),
+    ...table.getCenterVisibleLeafColumns(),
+    ...table.getEndVisibleLeafColumns(),
+  ].map((column) => column.id)
+  const from = rendered.indexOf(String(active.id))
+  const to = rendered.indexOf(String(over.id))
+  if (from === -1 || to === -1) return event
+
+  for (const [ownerId, covered] of getDataGridHeaderSpans(table)) {
+    const leaves = [ownerId, ...covered.map((column) => column.id)]
+    if (!leaves.includes(String(over.id))) continue
+    if (leaves.includes(String(active.id))) return event
+    const edge = from < to ? leaves[leaves.length - 1]! : leaves[0]!
+    return edge === String(over.id)
+      ? event
+      : { ...event, over: { ...over, id: edge } }
+  }
+
+  return event
+}
+
+class DataGridKeyboardSensor extends KeyboardSensor {
+  constructor(props: KeyboardSensorProps) {
+    const { context, options } = props
+    const getCoordinates = options.coordinateGetter
+    super({
+      ...props,
+      context: {
+        get current() {
+          const current = context.current
+          return {
+            ...current,
+            scrollableAncestors:
+              current.scrollableAncestors.map(toLtrScrollView),
+          }
+        },
+      },
+      options: getCoordinates
+        ? {
+            ...options,
+            coordinateGetter: (event, args) =>
+              getCoordinates(event, { ...args, context: context.current }),
+          }
+        : options,
+    })
+  }
+}
+
+function DataGridTableDnd<TData extends object>({
+  handleDragEnd,
+  footerContent,
+  accessibility,
+}: {
+  handleDragEnd: (event: DragEndEvent) => void
+  footerContent?: ReactNode
+  /**
+   * Forwarded to dnd-kit's `DndContext`: its screen-reader instructions and
+   * live-region announcements, which default to dnd-kit's English strings.
+   */
+  accessibility?: DndContextProps["accessibility"]
+}) {
+  const { table, props } = useDataGrid()
+  const mergedHeaderGroups = getDataGridTableMergedHeaderGroups(table)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [isDraggingColumn, setIsDraggingColumn] = useState(false)
+
+  const sensors = useSensors(
+    useSensor(MouseSensor, {}),
+    useSensor(TouchSensor, {}),
+    // Keyboard reordering moves one sortable position per keypress instead
+    // of the sensor's raw 25px default.
+    useSensor(DataGridKeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    })
+  )
+
+  useEffect(() => {
+    if (!isDraggingColumn) return
+
+    const { body, documentElement } = document
+    const previousBodyCursor = body.style.cursor
+    const previousDocumentCursor = documentElement.style.cursor
+
+    body.style.cursor = "grabbing"
+    documentElement.style.cursor = "grabbing"
+
+    return () => {
+      body.style.cursor = previousBodyCursor
+      documentElement.style.cursor = previousDocumentCursor
+    }
+  }, [isDraggingColumn])
+
+  // Custom modifier to restrict dragging within table bounds with edge offset
+  const modifiers = useMemo(() => {
+    const restrictToTableBounds: Modifier = ({
+      draggingNodeRect,
+      transform,
+    }) => {
+      if (!draggingNodeRect || !containerRef.current) {
+        return { ...transform, y: 0 }
+      }
+
+      const containerRect = containerRef.current.getBoundingClientRect()
+      const edgeOffset = 0
+
+      const minX = containerRect.left - draggingNodeRect.left - edgeOffset
+      const maxX =
+        containerRect.right -
+        draggingNodeRect.left -
+        draggingNodeRect.width +
+        edgeOffset
+
+      return {
+        ...transform,
+        x: Math.min(Math.max(transform.x, minX), maxX),
+        y: 0, // Lock vertical movement
+      }
+    }
+
+    return [restrictToTableBounds]
+  }, [])
+
+  return (
+    <DndContext
+      accessibility={accessibility}
+      collisionDetection={closestCenter}
+      id={useId()}
+      modifiers={modifiers}
+      onDragCancel={() => setIsDraggingColumn(false)}
+      onDragEnd={(event) => {
+        setIsDraggingColumn(false)
+        handleDragEnd(getDataGridDropBesideSpans(table, event))
+      }}
+      onDragStart={() => setIsDraggingColumn(true)}
+      sensors={sensors}
+    >
+      <DataGridTableViewport
+        viewportRef={containerRef}
+        className={
+          isDraggingColumn
+            ? "relative cursor-grabbing [&_*]:cursor-grabbing!"
+            : "relative"
+        }
+      >
+        <DataGridTableBase>
+          <DataGridTableHead>
+            {mergedHeaderGroups.map((headerGroup, index) => {
+              return (
+                <DataGridTableHeadRow key={index} rowId={headerGroup.id}>
+                  <SortableContext
+                    items={table.state.columnOrder}
+                    strategy={horizontalListSortingStrategy}
+                  >
+                    {/* Every row follows DataGridTableBase's colgroup,
+                        which puts the fill col between the center and
+                        end-pinned groups; a fill cell appended last hands
+                        its width to the end-pinned column. One keyed
+                        list, not three, so a column pinned into or out of
+                        the end group moves instead of remounting, which
+                        would drop keyboard focus. The fill spans every
+                        head row, so only the first renders it. */}
+                    {[
+                      ...[
+                        ...headerGroup.startHeaders,
+                        ...headerGroup.centerHeaders,
+                      ].map((header) => (
+                        <DataGridTableDndHeader
+                          header={header}
+                          coveredHeaders={headerGroup.coveredHeaders.get(
+                            header.id
+                          )}
+                          key={header.id}
+                        />
+                      )),
+                      ...(index === 0
+                        ? [
+                            <DataGridTableFillHeadCell
+                              key="__data-grid-fill"
+                              rowSpan={mergedHeaderGroups.length}
+                            />,
+                          ]
+                        : []),
+                      ...headerGroup.endHeaders.map((header) => (
+                        <DataGridTableDndHeader
+                          header={header}
+                          coveredHeaders={headerGroup.coveredHeaders.get(
+                            header.id
+                          )}
+                          key={header.id}
+                        />
+                      )),
+                    ]}
+                  </SortableContext>
+                </DataGridTableHeadRow>
+              )
+            })}
+          </DataGridTableHead>
+
+          {(props.tableLayout?.stripped || !props.tableLayout?.rowBorder) && (
+            <DataGridTableRowSpacer />
+          )}
+
+          <DataGridTableBody>
+            <MemoizedDataGridTableDndBodyRows table={table} />
+          </DataGridTableBody>
+
+          {footerContent && (
+            <DataGridTableFoot>{footerContent}</DataGridTableFoot>
+          )}
+        </DataGridTableBase>
+      </DataGridTableViewport>
+    </DndContext>
+  )
+}
+
+export { DataGridTableDnd }
\ No newline at end of file
diff --git a/apps/web/src/components/reui/data-grid/data-grid-table-virtual.tsx b/apps/web/src/components/reui/data-grid/data-grid-table-virtual.tsx
new file mode 100644
index 0000000..18644a4
--- /dev/null
+++ b/apps/web/src/components/reui/data-grid/data-grid-table-virtual.tsx
@@ -0,0 +1,1220 @@
+"use client"
+
+// Opted out of React Compiler with the rest of the grid (see data-grid.tsx).
+"use no memo"
+
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react"
+import type { CSSProperties, ReactNode } from "react"
+import {
+  useDataGrid,
+  useDataGridAtom,
+} from "@/components/reui/data-grid/data-grid"
+import type {
+  DataGridFeatures,
+  DataGridTableInstance,
+} from "@/components/reui/data-grid/data-grid"
+import {
+  DataGridTableAddRow,
+  DataGridTableBase,
+  DataGridTableBody,
+  DataGridTableEmpty,
+  DataGridTableFillBodyCell,
+  DataGridTableFillHeadCell,
+  DataGridTableFoot,
+  DataGridTableHead,
+  DataGridTableHeadRow,
+  DataGridTableHeadRowCell,
+  DataGridTableHeadRowCellResize,
+  DataGridTableRenderedRow,
+  DataGridTableRowSpacer,
+  DataGridTableViewport,
+  getDataGridHeadCellResizeHeader,
+  getDataGridScrollAreaViewport,
+  getDataGridTableMergedHeaderGroups,
+  getDataGridTableRowSections,
+  getPinningStyles,
+  hasDataGridTableRightPinnedColumns,
+  renderDataGridTableHeadCellContent,
+} from "@/components/reui/data-grid/data-grid-table"
+import type { Column, Row } from "@tanstack/react-table"
+import { useVirtualizer } from "@tanstack/react-virtual"
+import type {
+  VirtualItem,
+  Virtualizer,
+  VirtualizerOptions,
+} from "@tanstack/react-virtual"
+import { cn } from "@authportal/ui/lib/utils"
+
+import { Spinner } from "@authportal/ui/components/spinner"
+
+type DataGridTableVirtualScrollElements = {
+  containerElement: HTMLDivElement | null
+  scrollElement: HTMLElement | null
+}
+
+type DataGridTableVirtualizerInstance = Virtualizer<
+  HTMLElement,
+  HTMLTableRowElement
+>
+
+type DataGridTableVirtualScrollAlignment = "auto" | "center" | "start" | "end"
+
+interface DataGridTableColumnVirtualizerOptions {
+  /** Off unless explicitly true; a column window is opt-in. */
+  enabled?: boolean
+  overscan?: number
+}
+
+type DataGridTableColumnScrollRequest = {
+  align: DataGridTableVirtualScrollAlignment
+  behavior: ScrollBehavior
+  columnId: string | undefined
+  columnIndex: number
+  scrollElement: HTMLElement
+}
+
+function isSameDataGridTableColumnScrollRequest(
+  previous: DataGridTableColumnScrollRequest | null,
+  next: DataGridTableColumnScrollRequest
+) {
+  return (
+    previous?.align === next.align &&
+    previous.behavior === next.behavior &&
+    previous.columnId === next.columnId &&
+    previous.columnIndex === next.columnIndex &&
+    previous.scrollElement === next.scrollElement
+  )
+}
+
+type DataGridTableVirtualScrollRequest = {
+  align: DataGridTableVirtualScrollAlignment
+  behavior: ScrollBehavior
+  containerElement: HTMLDivElement
+  headerSticky: boolean
+  isVirtualizationEnabled: boolean
+  rowId: string | undefined
+  rowIndex: number
+  scrollElement: HTMLElement
+}
+
+function isSameDataGridTableScrollRequest(
+  previous: DataGridTableVirtualScrollRequest | null,
+  next: DataGridTableVirtualScrollRequest
+) {
+  return (
+    previous?.align === next.align &&
+    previous.behavior === next.behavior &&
+    previous.containerElement === next.containerElement &&
+    previous.headerSticky === next.headerSticky &&
+    previous.isVirtualizationEnabled === next.isVirtualizationEnabled &&
+    previous.rowId === next.rowId &&
+    previous.rowIndex === next.rowIndex &&
+    previous.scrollElement === next.scrollElement
+  )
+}
+
+function getDataGridTableScrollTarget({
+  align,
+  clientHeight,
+  rowBottom,
+  rowHeight,
+  rowTop,
+  scrollHeight,
+  scrollTop,
+  viewportTopOffset = 0,
+}: {
+  align: DataGridTableVirtualScrollAlignment
+  clientHeight: number
+  rowBottom: number
+  rowHeight: number
+  rowTop: number
+  scrollHeight: number
+  scrollTop: number
+  viewportTopOffset?: number
+}) {
+  const visibleHeight = Math.max(0, clientHeight - viewportTopOffset)
+  const viewportTop = scrollTop + viewportTopOffset
+  const viewportBottom = scrollTop + clientHeight
+
+  const targetTop =
+    align === "auto"
+      ? rowTop < viewportTop
+        ? rowTop - viewportTopOffset
+        : rowBottom > viewportBottom
+          ? rowBottom - clientHeight
+          : null
+      : align === "start"
+        ? rowTop - viewportTopOffset
+        : align === "end"
+          ? rowBottom - clientHeight
+          : rowTop -
+            viewportTopOffset -
+            Math.max(0, (visibleHeight - rowHeight) / 2)
+
+  if (targetTop === null) return null
+
+  return Math.min(
+    Math.max(0, targetTop),
+    Math.max(0, scrollHeight - clientHeight)
+  )
+}
+
+function getDataGridTableHeaderOffset({
+  containerElement,
+  headerSticky,
+  scrollElement,
+}: {
+  containerElement: HTMLDivElement
+  headerSticky: boolean
+  scrollElement: HTMLElement
+}) {
+  if (!headerSticky) return 0
+
+  const headerElement = containerElement.querySelector<HTMLElement>(
+    ':scope > [data-slot="data-grid-table"] > thead'
+  )
+
+  if (!headerElement) return 0
+
+  const scrollRect = scrollElement.getBoundingClientRect()
+  const headerRect = headerElement.getBoundingClientRect()
+  const headerBottomOffset = headerRect.bottom - scrollRect.top
+  const overlapsViewportTop =
+    headerRect.top <= scrollRect.top + 0.5 && headerBottomOffset > 0
+
+  if (!overlapsViewportTop) return 0
+
+  return Math.min(scrollElement.clientHeight, Math.max(0, headerBottomOffset))
+}
+
+function scrollDataGridTableToOffset({
+  behavior,
+  scrollElement,
+  targetTop,
+  virtualizer,
+}: {
+  behavior: ScrollBehavior
+  scrollElement: HTMLElement
+  targetTop: number
+  virtualizer?: DataGridTableVirtualizerInstance
+}) {
+  if (virtualizer) {
+    virtualizer.scrollToOffset(targetTop, { align: "start", behavior })
+  } else if (typeof scrollElement.scrollTo === "function") {
+    scrollElement.scrollTo({ behavior, top: targetTop })
+  } else {
+    scrollElement.scrollTop = targetTop
+  }
+}
+
+function scrollDataGridTableRowIntoView({
+  align,
+  behavior,
+  cancelPendingScroll = false,
+  containerElement,
+  headerSticky,
+  rowIndex,
+  scrollElement,
+  virtualizer,
+}: {
+  align: DataGridTableVirtualScrollAlignment
+  behavior: ScrollBehavior
+  cancelPendingScroll?: boolean
+  containerElement: HTMLDivElement | null
+  headerSticky: boolean
+  rowIndex: number
+  scrollElement: HTMLElement | null
+  virtualizer?: DataGridTableVirtualizerInstance
+}) {
+  if (!containerElement || !scrollElement) return false
+
+  const rowElement = containerElement.querySelector<HTMLTableRowElement>(
+    `:scope > [data-slot="data-grid-table"] > tbody > tr[data-index="${rowIndex}"]`
+  )
+
+  if (!rowElement) return false
+
+  const scrollRect = scrollElement.getBoundingClientRect()
+  const rowRect = rowElement.getBoundingClientRect()
+  const viewportTopOffset = getDataGridTableHeaderOffset({
+    containerElement,
+    headerSticky,
+    scrollElement,
+  })
+  const rowTop = scrollElement.scrollTop + rowRect.top - scrollRect.top
+  const rowBottom = scrollElement.scrollTop + rowRect.bottom - scrollRect.top
+  const targetTop = getDataGridTableScrollTarget({
+    align,
+    clientHeight: scrollElement.clientHeight,
+    rowBottom,
+    rowHeight: rowRect.height || rowElement.offsetHeight,
+    rowTop,
+    scrollHeight: scrollElement.scrollHeight,
+    scrollTop: scrollElement.scrollTop,
+    viewportTopOffset,
+  })
+
+  if (
+    targetTop === null ||
+    Math.abs(targetTop - scrollElement.scrollTop) < 0.5
+  ) {
+    if (cancelPendingScroll) {
+      scrollDataGridTableToOffset({
+        behavior: "auto",
+        scrollElement,
+        targetTop: scrollElement.scrollTop,
+        virtualizer,
+      })
+    }
+
+    return true
+  }
+
+  scrollDataGridTableToOffset({
+    behavior,
+    scrollElement,
+    targetTop,
+    virtualizer,
+  })
+
+  return true
+}
+
+type DataGridTableVirtualizerOptions<TData extends object> = Omit<
+  VirtualizerOptions<HTMLElement, HTMLTableRowElement>,
+  "count" | "estimateSize" | "getItemKey" | "getScrollElement"
+> & {
+  estimateSize?: (index: number, row: Row<DataGridFeatures, TData>) => number
+  getItemKey?: (
+    index: number,
+    row: Row<DataGridFeatures, TData>
+  ) => string | number
+  getScrollElement?: (
+    elements: DataGridTableVirtualScrollElements
+  ) => HTMLElement | null
+}
+
+interface DataGridTableVirtualProps<TData extends object> {
+  height?: number | string
+  estimateSize?: number
+  overscan?: number
+  /** Scroll animation used when revealing a controlled target row. */
+  scrollBehavior?: ScrollBehavior
+  /** Alignment used when revealing a controlled target row. Defaults to auto. */
+  scrollToRowAlign?: DataGridTableVirtualScrollAlignment
+  /** Index within the center (non-pinned) row section to reveal. */
+  scrollToRowIndex?: number
+  /**
+   * Opt-in horizontal virtualization of the CENTER columns. Activates only
+   * under a fixed table layout with a single ungrouped header row; pinned
+   * columns stay mounted, and anything else falls back to full-column
+   * rendering. `scrollBehavior` is shared with controlled row scrolling.
+   */
+  columnVirtualizerOptions?: DataGridTableColumnVirtualizerOptions
+  /** Alignment used when revealing a controlled target column. */
+  scrollToColumnAlign?: DataGridTableVirtualScrollAlignment
+  /** Index within the center (non-pinned) visible leaf columns to reveal. */
+  scrollToColumnIndex?: number
+  footerContent?: ReactNode
+  renderHeader?: boolean
+  onFetchMore?: () => void
+  isFetchingMore?: boolean
+  hasMore?: boolean
+  fetchMoreOffset?: number
+  virtualizerOptions?: DataGridTableVirtualizerOptions<TData>
+}
+
+interface VirtualBodyProps<TData extends object> {
+  table: DataGridTableInstance<TData>
+  topRows: Row<DataGridFeatures, TData>[]
+  centerRows: Row<DataGridFeatures, TData>[]
+  bottomRows: Row<DataGridFeatures, TData>[]
+  virtualItems: VirtualItem[]
+  totalSize: number
+  isVirtualizationEnabled: boolean
+  isInfiniteMode: boolean
+  isFetchingMore: boolean
+  hasMore?: boolean
+  loadingMoreMessage: ReactNode
+  allRowsLoadedMessage: ReactNode
+  measureRowRef?: (element: HTMLTableRowElement | null) => void
+  centerColumnWindow?: { start: number; end: number }
+}
+
+function DataGridTableVirtualPinnedPlaceholderCell<TData extends object>({
+  column,
+}: {
+  column: Column<DataGridFeatures, TData, unknown>
+}) {
+  const { props } = useDataGrid()
+  const isPinned = column.getIsPinned()
+  const isLastStartPinned =
+    isPinned === "start" && column.getIsLastColumn("start")
+  const isFirstEndPinned = isPinned === "end" && column.getIsFirstColumn("end")
+
+  return (
+    <td
+      aria-hidden="true"
+      style={{
+        ...(props.tableLayout?.columnsPinnable &&
+          column.getCanPin() &&
+          getPinningStyles(column)),
+        ...(props.tableLayout?.columnsResizable && {
+          width: `calc(var(--col-${column.id}-size) * 1px)`,
+        }),
+      }}
+      data-pinned={isPinned || undefined}
+      data-last-col={
+        isLastStartPinned ? "start" : isFirstEndPinned ? "end" : undefined
+      }
+      className={cn(
+        "p-0",
+        props.tableLayout?.cellBorder && "border-e",
+        props.tableLayout?.columnsPinnable &&
+          column.getCanPin() &&
+          "data-pinned:isolate data-pinned:bg-[color:var(--data-grid-surface,var(--data-grid-card-surface,var(--background)))] [&[data-pinned=end][data-last-col=end]]:shadow-[inset_calc(1px*var(--data-grid-dir,1))_0_0_0_var(--border)] [&[data-pinned=start][data-last-col=start]]:shadow-[inset_calc(-1px*var(--data-grid-dir,1))_0_0_0_var(--border)]"
+      )}
+    />
+  )
+}
+
+function DataGridTableVirtualUtilityRow<TData extends object>({
+  table,
+  children,
+  centerCellClassName,
+  centerCellStyle,
+  rowClassName,
+  ariaHidden,
+}: {
+  table: DataGridTableInstance<TData>
+  children: ReactNode
+  centerCellClassName?: string
+  centerCellStyle?: CSSProperties
+  rowClassName?: string
+  ariaHidden?: boolean
+}) {
+  const { props } = useDataGrid()
+  const leftVisibleColumns = table.getStartVisibleLeafColumns()
+  const centerVisibleColumns = table.getCenterVisibleLeafColumns()
+  const rightVisibleColumns = table.getEndVisibleLeafColumns()
+  const hasRightPinnedColumns = hasDataGridTableRightPinnedColumns(table)
+
+  return (
+    <tr aria-hidden={ariaHidden || undefined} className={rowClassName}>
+      {leftVisibleColumns.map((column) => (
+        <DataGridTableVirtualPinnedPlaceholderCell
+          column={column}
+          key={column.id}
+        />
+      ))}
+      <td
+        colSpan={Math.max(centerVisibleColumns.length, 1)}
+        className={centerCellClassName}
+        style={centerCellStyle}
+      >
+        {children}
+      </td>
+      {props.tableLayout?.columnsResizable && hasRightPinnedColumns ? (
+        <DataGridTableFillBodyCell />
+      ) : null}
+      {rightVisibleColumns.map((column) => (
+        <DataGridTableVirtualPinnedPlaceholderCell
+          column={column}
+          key={column.id}
+        />
+      ))}
+      {props.tableLayout?.columnsResizable && !hasRightPinnedColumns ? (
+        <DataGridTableFillBodyCell />
+      ) : null}
+    </tr>
+  )
+}
+
+function DataGridTableVirtualSpacer<TData extends object>({
+  table,
+  height,
+}: {
+  table: DataGridTableInstance<TData>
+  height: number
+}) {
+  if (height <= 0) return null
+
+  return (
+    <DataGridTableVirtualUtilityRow
+      table={table}
+      ariaHidden
+      centerCellClassName="p-0"
+      centerCellStyle={{ height, padding: 0 }}
+    >
+      {null}
+    </DataGridTableVirtualUtilityRow>
+  )
+}
+
+function DataGridTableVirtualStatusRow<TData extends object>({
+  table,
+  children,
+  className,
+}: {
+  table: DataGridTableInstance<TData>
+  children: ReactNode
+  className?: string
+}) {
+  return (
+    <DataGridTableVirtualUtilityRow
+      table={table}
+      centerCellClassName={cn(
+        "text-muted-foreground py-4 text-center text-sm",
+        className
+      )}
+    >
+      {children}
+    </DataGridTableVirtualUtilityRow>
+  )
+}
+
+/**
+ * A scroll frame only shifts the window, so every surviving row's inputs are
+ * identical and its last render is reused; the per-frame cost is the rows
+ * entering the window, not all mounted rows. Cell-level state (selection,
+ * focus, row checks) repaints through each cell's own Subscribe, and any real
+ * data change rebuilds the row wrappers, so identity comparison is safe.
+ */
+const MemoizedRenderedRow = memo(
+  DataGridTableRenderedRow,
+  (prev, next) =>
+    prev.row === next.row &&
+    prev.rowIndex === next.rowIndex &&
+    prev.rowRef === next.rowRef &&
+    prev.pinnedBoundary === next.pinnedBoundary &&
+    prev.centerWindow?.start === next.centerWindow?.start &&
+    prev.centerWindow?.end === next.centerWindow?.end
+) as typeof DataGridTableRenderedRow
+
+function DataGridTableVirtualBody<TData extends object>({
+  table,
+  topRows,
+  centerRows,
+  bottomRows,
+  virtualItems,
+  totalSize,
+  isVirtualizationEnabled,
+  isInfiniteMode,
+  isFetchingMore,
+  hasMore,
+  loadingMoreMessage,
+  allRowsLoadedMessage,
+  measureRowRef,
+  centerColumnWindow,
+}: VirtualBodyProps<TData>) {
+  const { isLoading } = useDataGrid()
+  const totalRows = topRows.length + centerRows.length + bottomRows.length
+
+  if (!totalRows) {
+    // Initial load must not flash the empty state as if the query returned
+    // nothing.
+    if (isLoading) {
+      return (
+        <DataGridTableVirtualStatusRow table={table}>
+          <div className="flex items-center justify-center gap-2">
+            <Spinner className="size-4 opacity-60" />
+            {loadingMoreMessage}
+          </div>
+        </DataGridTableVirtualStatusRow>
+      )
+    }
+
+    return <DataGridTableEmpty />
+  }
+
+  const hasCenterRows = centerRows.length > 0
+  const showFetchingRow = isInfiniteMode && isFetchingMore
+  const showCompleteRow = isInfiniteMode && hasMore === false && totalRows > 0
+  const hasMiddleSection = hasCenterRows || showFetchingRow || showCompleteRow
+  const leadingSpacerHeight =
+    isVirtualizationEnabled && hasCenterRows && virtualItems.length > 0
+      ? (virtualItems[0]?.start ?? 0)
+      : 0
+  const trailingSpacerHeight =
+    isVirtualizationEnabled && hasCenterRows && virtualItems.length > 0
+      ? Math.max(
+          0,
+          totalSize - (virtualItems[virtualItems.length - 1]?.end ?? 0)
+        )
+      : 0
+
+  const renderedRows: ReactNode[] = []
+
+  topRows.forEach((row, index) => {
+    renderedRows.push(
+      <MemoizedRenderedRow
+        key={row.id}
+        row={row}
+        centerWindow={centerColumnWindow}
+        pinnedBoundary={
+          index === topRows.length - 1 && hasMiddleSection ? "top" : undefined
+        }
+      />
+    )
+  })
+
+  if (isVirtualizationEnabled) {
+    if (leadingSpacerHeight > 0) {
+      renderedRows.push(
+        <DataGridTableVirtualSpacer
+          key="virtual-spacer-start"
+          table={table}
+          height={leadingSpacerHeight}
+        />
+      )
+    }
+
+    virtualItems.forEach((virtualRow) => {
+      const row = centerRows[virtualRow.index]
+
+      if (!row) return
+
+      renderedRows.push(
+        <MemoizedRenderedRow
+          key={row.id}
+          row={row}
+          rowRef={measureRowRef}
+          rowIndex={virtualRow.index}
+          centerWindow={centerColumnWindow}
+        />
+      )
+    })
+
+    if (trailingSpacerHeight > 0) {
+      renderedRows.push(
+        <DataGridTableVirtualSpacer
+          key="virtual-spacer-end"
+          table={table}
+          height={trailingSpacerHeight}
+        />
+      )
+    }
+  } else {
+    centerRows.forEach((row, rowIndex) => {
+      renderedRows.push(
+        <MemoizedRenderedRow
+          key={row.id}
+          row={row}
+          rowIndex={rowIndex}
+          centerWindow={centerColumnWindow}
+        />
+      )
+    })
+  }
+
+  if (showFetchingRow) {
+    renderedRows.push(
+      <DataGridTableVirtualStatusRow key="virtual-status-loading" table={table}>
+        <div className="flex items-center justify-center gap-2">
+          <Spinner className="size-4 opacity-60" />
+          {loadingMoreMessage}
+        </div>
+      </DataGridTableVirtualStatusRow>
+    )
+  }
+
+  if (showCompleteRow) {
+    renderedRows.push(
+      <DataGridTableVirtualStatusRow
+        key="virtual-status-complete"
+        table={table}
+        className="py-3 text-xs"
+      >
+        {allRowsLoadedMessage}
+      </DataGridTableVirtualStatusRow>
+    )
+  }
+
+  bottomRows.forEach((row, index) => {
+    renderedRows.push(
+      <MemoizedRenderedRow
+        key={row.id}
+        row={row}
+        centerWindow={centerColumnWindow}
+        pinnedBoundary={
+          index === 0 && (topRows.length > 0 || hasMiddleSection)
+            ? "bottom"
+            : undefined
+        }
+      />
+    )
+  })
+
+  return <>{renderedRows}</>
+}
+
+/**
+ * Memoized virtual body: skip re-renders during active column resize.
+ * Column widths update via CSS variables on the <table> element,
+ * so the browser handles width changes without React re-renders.
+ * A cell-selection drag gets the same treatment: painting goes through each
+ * cell's own Subscribe, and the virtualizer re-renders itself from inside the
+ * memo boundary, so parent-driven reconciliation during the drag is waste.
+ */
+const MemoizedVirtualBody = memo(
+  DataGridTableVirtualBody,
+  (_prev, next) =>
+    !!next.table.state.columnResizing?.isResizingColumn ||
+    next.table._isSelectingCells === true
+) as typeof DataGridTableVirtualBody
+
+function DataGridTableVirtual<TData extends object>({
+  height,
+  estimateSize = 48,
+  overscan = 10,
+  scrollBehavior = "auto",
+  scrollToRowAlign = "auto",
+  scrollToRowIndex,
+  columnVirtualizerOptions,
+  scrollToColumnAlign = "auto",
+  scrollToColumnIndex,
+  footerContent,
+  renderHeader = true,
+  onFetchMore,
+  isFetchingMore = false,
+  hasMore,
+  fetchMoreOffset = 0,
+  virtualizerOptions,
+}: DataGridTableVirtualProps<TData>) {
+  const { i18n, table, props } = useDataGrid<TData>()
+  const columnSizing = useDataGridAtom(table.atoms.columnSizing)
+  const mergedHeaderGroups = getDataGridTableMergedHeaderGroups(table)
+  const hasRightPinnedColumns = hasDataGridTableRightPinnedColumns(table)
+  const centerVisibleColumns = table.getCenterVisibleLeafColumns()
+  // Column windows only where the geometry is provable: a fixed table
+  // layout (undefined defaults to fixed; the colgroup then owns every
+  // width, so colSpan spacers cannot drift) and a single ungrouped header
+  // row (a colSpan group or meta.headerColSpan cell cannot be windowed).
+  // Anything else falls back to full-column rendering silently, the same
+  // posture as row virtualization toward unsupported shapes.
+  const columnVirtualizationActive =
+    columnVirtualizerOptions?.enabled === true &&
+    props.tableLayout?.width !== "auto" &&
+    mergedHeaderGroups.length === 1 &&
+    (mergedHeaderGroups[0]?.headers.every((header) => header.colSpan <= 1) ??
+      false) &&
+    !mergedHeaderGroups[0]?.coveredHeaders.size
+  const { topRows, centerRows, bottomRows } = getDataGridTableRowSections(
+    table,
+    props.tableLayout?.rowsPinnable
+  )
+  const isInfiniteMode = typeof onFetchMore === "function"
+  const [viewportElements, setViewportElements] =
+    useState<DataGridTableVirtualScrollElements>({
+      containerElement: null,
+      scrollElement: null,
+    })
+
+  const {
+    estimateSize: customEstimateSize,
+    getItemKey: customGetItemKey,
+    getScrollElement: customGetScrollElement,
+    measureElement: customMeasureElement,
+    overscan: customOverscan,
+    ...virtualizerOptionsRest
+  } = virtualizerOptions ?? {}
+
+  const isVirtualizationEnabled = virtualizerOptions?.enabled !== false
+  const loadingMoreMessage =
+    props.fetchingMoreMessage || props.loadingMessage || i18n.labels.loading
+  const allRowsLoadedMessage =
+    props.allRowsLoadedMessage || i18n.labels.allRowsLoaded
+
+  const handleViewportRef = useCallback((node: HTMLDivElement | null) => {
+    setViewportElements({
+      containerElement: node,
+      scrollElement: node
+        ? (getDataGridScrollAreaViewport(node) ?? node)
+        : null,
+    })
+  }, [])
+
+  const usesExternalScrollArea =
+    viewportElements.scrollElement !== null &&
+    viewportElements.scrollElement !== viewportElements.containerElement
+
+  const resolveScrollElement = useCallback(() => {
+    if (customGetScrollElement) {
+      return customGetScrollElement(viewportElements)
+    }
+
+    return viewportElements.scrollElement
+  }, [customGetScrollElement, viewportElements])
+
+  const resolveItemKey = useCallback(
+    (index: number) => {
+      const row = centerRows[index]
+
+      if (!row) return index
+
+      return customGetItemKey?.(index, row) ?? row.id ?? index
+    },
+    [centerRows, customGetItemKey]
+  )
+
+  const resolveEstimateSize = useCallback(
+    (index: number) => {
+      const row = centerRows[index]
+
+      return row
+        ? (customEstimateSize?.(index, row) ?? estimateSize)
+        : estimateSize
+    },
+    [centerRows, customEstimateSize, estimateSize]
+  )
+
+  const virtualizer = useVirtualizer({
+    count: centerRows.length,
+    getScrollElement: resolveScrollElement,
+    getItemKey: resolveItemKey,
+    estimateSize: resolveEstimateSize,
+    overscan: customOverscan ?? overscan,
+    measureElement: customMeasureElement,
+    ...virtualizerOptionsRest,
+  }) as DataGridTableVirtualizerInstance
+
+  // Horizontal offsets invert in RTL; the virtualizer must be told.
+  const isRtl = useMemo(
+    () =>
+      viewportElements.containerElement
+        ? getComputedStyle(viewportElements.containerElement).direction ===
+          "rtl"
+        : false,
+    [viewportElements.containerElement]
+  )
+
+  const resolveColumnKey = useCallback(
+    (index: number) => centerVisibleColumns[index]?.id ?? index,
+    [centerVisibleColumns]
+  )
+
+  const resolveColumnEstimateSize = useCallback(
+    (index: number) => centerVisibleColumns[index]?.getSize() ?? 0,
+    [centerVisibleColumns]
+  )
+
+  const columnVirtualizer = useVirtualizer({
+    horizontal: true,
+    isRtl,
+    count: columnVirtualizationActive ? centerVisibleColumns.length : 0,
+    getScrollElement: resolveScrollElement,
+    getItemKey: resolveColumnKey,
+    estimateSize: resolveColumnEstimateSize,
+    overscan: columnVirtualizerOptions?.overscan ?? 3,
+  })
+
+  // Column sizes are exact reads of getSize(), never DOM-measured, so a
+  // resize commit or a visibility/order/pinning change must resync the
+  // virtualizer's cached sizes by hand.
+  useEffect(() => {
+    if (columnVirtualizationActive) columnVirtualizer.measure()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    columnVirtualizationActive,
+    columnVirtualizer,
+    columnSizing,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    table.state.columnVisibility,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    table.state.columnOrder,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    table.state.columnPinning,
+  ])
+
+  const virtualColumns = columnVirtualizationActive
+    ? columnVirtualizer.getVirtualItems()
+    : []
+  // The window is a contiguous inclusive [start, end] over the center
+  // columns; before the scroll element resolves the item list is empty and
+  // the grid renders full-width for that first frame.
+  const centerColumnWindow =
+    columnVirtualizationActive && virtualColumns.length > 0
+      ? {
+          start: virtualColumns[0]!.index,
+          end: virtualColumns[virtualColumns.length - 1]!.index,
+        }
+      : undefined
+
+  const virtualItems = isVirtualizationEnabled
+    ? virtualizer.getVirtualItems()
+    : []
+  const totalSize = isVirtualizationEnabled ? virtualizer.getTotalSize() : 0
+  const measureRowRef =
+    isVirtualizationEnabled && customMeasureElement
+      ? virtualizer.measureElement
+      : undefined
+  const resolvedFetchMoreOffset = Math.max(0, fetchMoreOffset)
+  const scrollToRowId =
+    scrollToRowIndex !== undefined
+      ? centerRows[scrollToRowIndex]?.id
+      : undefined
+  const scrollToRowVirtualItem =
+    isVirtualizationEnabled && scrollToRowIndex !== undefined
+      ? virtualItems.find((item) => item.index === scrollToRowIndex)
+      : undefined
+  const pendingScrollToRowIndexRef = useRef<number | null>(null)
+  const lastScrollRequestRef = useRef<DataGridTableVirtualScrollRequest | null>(
+    null
+  )
+  // Latch onFetchMore per row count: virtualItems gets a new identity every
+  // scroll frame, so without it the effect fires duplicate page requests
+  // before the consumer flips isFetchingMore, and loops at end-of-data when
+  // hasMore is never set.
+  const fetchMoreFiredAtCountRef = useRef<number | null>(null)
+  const lastColumnScrollRequestRef =
+    useRef<DataGridTableColumnScrollRequest | null>(null)
+
+  // Controlled column reveal: same dedupe posture as the row request - the
+  // signature keeps ordinary renders from re-scrolling, and exact column
+  // sizes mean no post-measure follow-up pass is needed.
+  useEffect(() => {
+    if (
+      !columnVirtualizationActive ||
+      scrollToColumnIndex === undefined ||
+      scrollToColumnIndex < 0 ||
+      scrollToColumnIndex >= centerVisibleColumns.length ||
+      !viewportElements.scrollElement
+    ) {
+      return
+    }
+    const request: DataGridTableColumnScrollRequest = {
+      align: scrollToColumnAlign,
+      behavior: scrollBehavior,
+      columnId: centerVisibleColumns[scrollToColumnIndex]?.id,
+      columnIndex: scrollToColumnIndex,
+      scrollElement: viewportElements.scrollElement,
+    }
+    if (
+      isSameDataGridTableColumnScrollRequest(
+        lastColumnScrollRequestRef.current,
+        request
+      )
+    ) {
+      return
+    }
+    lastColumnScrollRequestRef.current = request
+    columnVirtualizer.scrollToIndex(scrollToColumnIndex, {
+      align: scrollToColumnAlign,
+      behavior: scrollBehavior === "smooth" ? "smooth" : "auto",
+    })
+  }, [
+    columnVirtualizationActive,
+    columnVirtualizer,
+    centerVisibleColumns,
+    scrollToColumnAlign,
+    scrollToColumnIndex,
+    scrollBehavior,
+    viewportElements.scrollElement,
+  ])
+
+  // Resolve after every commit so a stable getter can expose a replaced ref;
+  // the request signature prevents duplicate scrolling on ordinary renders.
+  useEffect(() => {
+    const previousRequest = lastScrollRequestRef.current
+
+    if (
+      scrollToRowIndex === undefined ||
+      scrollToRowIndex < 0 ||
+      scrollToRowIndex >= centerRows.length
+    ) {
+      pendingScrollToRowIndexRef.current = null
+      lastScrollRequestRef.current = null
+
+      if (previousRequest) {
+        const scrollElement = resolveScrollElement()
+
+        if (scrollElement) {
+          scrollDataGridTableToOffset({
+            behavior: "auto",
+            scrollElement,
+            targetTop: scrollElement.scrollTop,
+            virtualizer: isVirtualizationEnabled ? virtualizer : undefined,
+          })
+        }
+      }
+
+      return
+    }
+
+    const scrollElement = resolveScrollElement()
+    const containerElement = viewportElements.containerElement
+    if (!containerElement || !scrollElement) return
+
+    const headerSticky = renderHeader && !!props.tableLayout?.headerSticky
+    const nextRequest: DataGridTableVirtualScrollRequest = {
+      align: scrollToRowAlign,
+      behavior: scrollBehavior,
+      containerElement,
+      headerSticky,
+      isVirtualizationEnabled,
+      rowId: scrollToRowId,
+      rowIndex: scrollToRowIndex,
+      scrollElement,
+    }
+
+    if (isSameDataGridTableScrollRequest(previousRequest, nextRequest)) return
+
+    pendingScrollToRowIndexRef.current = null
+
+    const rowWasHandled = scrollDataGridTableRowIntoView({
+      align: scrollToRowAlign,
+      behavior: scrollBehavior,
+      cancelPendingScroll: previousRequest !== null,
+      containerElement,
+      headerSticky,
+      rowIndex: scrollToRowIndex,
+      scrollElement,
+      virtualizer: isVirtualizationEnabled ? virtualizer : undefined,
+    })
+
+    if (rowWasHandled) {
+      lastScrollRequestRef.current = nextRequest
+      return
+    }
+
+    if (!isVirtualizationEnabled) return
+
+    pendingScrollToRowIndexRef.current = scrollToRowIndex
+    lastScrollRequestRef.current = nextRequest
+    virtualizer.scrollToIndex(scrollToRowIndex, {
+      align: scrollToRowAlign,
+      behavior: scrollBehavior,
+    })
+  })
+
+  useEffect(() => {
+    if (
+      !isVirtualizationEnabled ||
+      scrollToRowIndex === undefined ||
+      pendingScrollToRowIndexRef.current !== scrollToRowIndex ||
+      !scrollToRowVirtualItem
+    ) {
+      return
+    }
+
+    const rowWasHandled = scrollDataGridTableRowIntoView({
+      align: scrollToRowAlign,
+      behavior: "auto",
+      cancelPendingScroll: true,
+      containerElement: viewportElements.containerElement,
+      headerSticky: renderHeader && !!props.tableLayout?.headerSticky,
+      rowIndex: scrollToRowIndex,
+      scrollElement: resolveScrollElement(),
+      virtualizer,
+    })
+
+    if (rowWasHandled) {
+      pendingScrollToRowIndexRef.current = null
+    }
+  }, [
+    isVirtualizationEnabled,
+    props.tableLayout?.headerSticky,
+    renderHeader,
+    resolveScrollElement,
+    scrollToRowAlign,
+    scrollToRowIndex,
+    scrollToRowVirtualItem,
+    virtualizer,
+    viewportElements.containerElement,
+  ])
+
+  useEffect(() => {
+    if (
+      !isVirtualizationEnabled ||
+      !isInfiniteMode ||
+      hasMore === false ||
+      isFetchingMore
+    ) {
+      return
+    }
+
+    const lastItem = virtualItems[virtualItems.length - 1]
+    if (!lastItem) return
+
+    if (fetchMoreFiredAtCountRef.current === centerRows.length) return
+
+    if (lastItem.index >= centerRows.length - 1 - resolvedFetchMoreOffset) {
+      fetchMoreFiredAtCountRef.current = centerRows.length
+      onFetchMore?.()
+    }
+  }, [
+    centerRows.length,
+    hasMore,
+    isFetchingMore,
+    isInfiniteMode,
+    isVirtualizationEnabled,
+    onFetchMore,
+    resolvedFetchMoreOffset,
+    virtualItems,
+  ])
+
+  // The header re-renders only when its real inputs move: the table
+  // wrapper (any table state change recreates it), the layout props, and
+  // the column window. A scroll frame changes none of them, so the whole
+  // sortable-header subtree is reused instead of rebuilt per frame.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const headerNode = useMemo(
+    () =>
+      renderHeader && (
+        <DataGridTableHead>
+          {mergedHeaderGroups.map((headerGroup, rowIndex) => {
+            // The fill strip is one cell spanning every head row, so only
+            // the first row renders it.
+            const fillHeadCell =
+              props.tableLayout?.columnsResizable && rowIndex === 0 ? (
+                <DataGridTableFillHeadCell
+                  rowSpan={mergedHeaderGroups.length}
+                />
+              ) : null
+            const renderHeadCell = (
+              header: (typeof headerGroup.startHeaders)[number]
+            ) => {
+              const coveredHeaders = headerGroup.coveredHeaders.get(header.id)
+              const resizeHeader = getDataGridHeadCellResizeHeader(
+                header,
+                coveredHeaders
+              )
+
+              return (
+                <DataGridTableHeadRowCell
+                  header={header}
+                  coveredHeaders={coveredHeaders}
+                  key={header.id}
+                >
+                  {renderDataGridTableHeadCellContent(header)}
+                  {props.tableLayout?.columnsResizable &&
+                    resizeHeader.column.getCanResize() && (
+                      <DataGridTableHeadRowCellResize header={resizeHeader} />
+                    )}
+                </DataGridTableHeadRowCell>
+              )
+            }
+
+            return (
+              <DataGridTableHeadRow key={headerGroup.id} rowId={headerGroup.id}>
+                {/* Under an active column window the single ungrouped header
+                        row is bucketed start / windowed center / end, with each
+                        off-window flank one colSpan spacer sized by the intact
+                        colgroup - the same shape the body rows take. */}
+                {centerColumnWindow
+                  ? headerGroup.startHeaders.map(renderHeadCell)
+                  : null}
+                {centerColumnWindow && centerColumnWindow.start > 0 ? (
+                  <th
+                    aria-hidden="true"
+                    data-col-spacer="start"
+                    colSpan={centerColumnWindow.start}
+                    className="p-0"
+                  />
+                ) : null}
+                {centerColumnWindow
+                  ? headerGroup.centerHeaders
+                      .slice(
+                        centerColumnWindow.start,
+                        centerColumnWindow.end + 1
+                      )
+                      .map(renderHeadCell)
+                  : null}
+                {centerColumnWindow &&
+                centerVisibleColumns.length - 1 - centerColumnWindow.end > 0 ? (
+                  <th
+                    aria-hidden="true"
+                    data-col-spacer="end"
+                    colSpan={
+                      centerVisibleColumns.length - 1 - centerColumnWindow.end
+                    }
+                    className="p-0"
+                  />
+                ) : null}
+                {!centerColumnWindow &&
+                  [
+                    ...headerGroup.startHeaders,
+                    ...headerGroup.centerHeaders,
+                  ].map(renderHeadCell)}
+                {hasRightPinnedColumns ? fillHeadCell : null}
+                {headerGroup.endHeaders.map(renderHeadCell)}
+                {!hasRightPinnedColumns ? fillHeadCell : null}
+              </DataGridTableHeadRow>
+            )
+          })}
+        </DataGridTableHead>
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      renderHeader,
+      table,
+      props.tableLayout,
+      centerColumnWindow,
+      hasRightPinnedColumns,
+    ]
+  )
+
+  return (
+    <DataGridTableViewport
+      viewportRef={handleViewportRef}
+      className={!usesExternalScrollArea ? "block" : undefined}
+      style={
+        usesExternalScrollArea
+          ? undefined
+          : {
+              height,
+              overflow: "auto",
+              position: "relative",
+              // Standalone mode: this node IS the scroll container, so it
+              // must stay at its parent's width (not the resizable table
+              // width) or horizontal scrolling becomes impossible.
+              width: "auto",
+            }
+      }
+    >
+      <DataGridTableBase>
+        {headerNode}
+
+        {renderHeader &&
+          (props.tableLayout?.stripped || !props.tableLayout?.rowBorder) && (
+            <DataGridTableRowSpacer />
+          )}
+
+        <DataGridTableBody>
+          <MemoizedVirtualBody
+            table={table}
+            topRows={topRows}
+            centerRows={centerRows}
+            bottomRows={bottomRows}
+            virtualItems={virtualItems}
+            totalSize={totalSize}
+            isVirtualizationEnabled={isVirtualizationEnabled}
+            isInfiniteMode={isInfiniteMode}
+            isFetchingMore={isFetchingMore}
+            hasMore={hasMore}
+            loadingMoreMessage={loadingMoreMessage}
+            allRowsLoadedMessage={allRowsLoadedMessage}
+            measureRowRef={measureRowRef}
+            centerColumnWindow={centerColumnWindow}
+          />
+          {/* Same appended region as the standard body, so onRowCreate and
+              a consumer draft work in the virtual layout too. */}
+          {props.appendRow}
+          <DataGridTableAddRow />
+        </DataGridTableBody>
+
+        {footerContent && (
+          <DataGridTableFoot>{footerContent}</DataGridTableFoot>
+        )}
+      </DataGridTableBase>
+    </DataGridTableViewport>
+  )
+}
+
+export { DataGridTableVirtual }
+export type {
+  DataGridTableVirtualScrollAlignment,
+  DataGridTableVirtualProps,
+  DataGridTableVirtualScrollElements,
+  DataGridTableVirtualizerOptions,
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/data-grid/data-grid-table.tsx b/apps/web/src/components/reui/data-grid/data-grid-table.tsx
index d90bc4f..abb717f 100644
--- a/apps/web/src/components/reui/data-grid/data-grid-table.tsx
+++ b/apps/web/src/components/reui/data-grid/data-grid-table.tsx
@@ -1,76 +1,82 @@
-"use client"
+"use no memo"
 
 import {
-  CSSProperties,
   Fragment,
   memo,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from "react"
+import type {
+  CSSProperties,
   MouseEvent as ReactMouseEvent,
   ReactNode,
   TouchEvent as ReactTouchEvent,
   Ref,
-  useCallback,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useState,
+  RefObject,
 } from "react"
-import { useDataGrid } from "@/components/reui/data-grid/data-grid"
 import {
-  Cell,
-  Column,
-  flexRender,
-  Header,
-  Row,
-  Table,
-} from "@tanstack/react-table"
-import { cva } from "class-variance-authority"
-
+  dataGridCellSelectionCellClasses,
+  getDataGridCellSelectionCellAttrs,
+  getDataGridHeaderSpans,
+  toDataGridDomId,
+  useDataGrid,
+  useDataGridAtom,
+} from "@/components/reui/data-grid/data-grid"
+import type {
+  DataGridAutoSizeController,
+  DataGridFeatures,
+  DataGridLayoutProps,
+  DataGridTableInstance,
+} from "@/components/reui/data-grid/data-grid"
+import { flexRender, Subscribe } from "@tanstack/react-table"
+import type { Cell, Column, Header, Row } from "@tanstack/react-table"
 import { cn } from "@authportal/ui/lib/utils"
+
+import { Button } from "@authportal/ui/components/button"
 import { Checkbox } from "@authportal/ui/components/checkbox"
 import { Spinner } from "@authportal/ui/components/spinner"
+import { PlusIcon } from "lucide-react"
 
-const headerCellSpacingVariants = cva("", {
-  variants: {
-    size: {
-      dense: "px-2 h-8",
-      default: "px-3",
-    },
-  },
-  defaultVariants: {
-    size: "default",
-  },
-})
+// Static spacing lookups; called once per cell, so they stay plain string
+// picks instead of runtime variant machinery.
+const headerCellSpacingVariants = ({ size }: { size?: "dense" | "default" }) =>
+  size === "dense" ? "px-2 h-8" : "px-3"
 
-const bodyCellSpacingVariants = cva("", {
-  variants: {
-    size: {
-      dense: "px-2 py-1.5",
-      default: "px-3 py-2",
-    },
-  },
-  defaultVariants: {
-    size: "default",
-  },
-})
+const bodyCellSpacingVariants = ({ size }: { size?: "dense" | "default" }) =>
+  size === "dense" ? "px-2 py-1.5" : "px-3 py-2"
 
-const footerCellSpacingVariants = cva("", {
-  variants: {
-    size: {
-      dense: "px-2 py-1.5",
-      default: "px-3 py-2",
-    },
-  },
-  defaultVariants: {
-    size: "default",
-  },
-})
+// The truncation wrapper used when cell selection is on: it consumes the
+// td padding with negative margins and restores it as its own, so its
+// overflow clips at exactly the boundary the td's `truncate` used to clip
+// at - including custom cells that pull into the padding the same way.
+const bodyCellTruncateWrapVariants = ({
+  size,
+}: {
+  size?: "dense" | "default"
+}) =>
+  size === "dense"
+    ? "-mx-2 -my-1.5 truncate px-2 py-1.5"
+    : "-mx-3 -my-2 truncate px-3 py-2"
 
-function getPinningStyles<TData>(column: Column<TData>): CSSProperties {
+const footerCellSpacingVariants = ({ size }: { size?: "dense" | "default" }) =>
+  size === "dense" ? "px-2 py-1.5" : "px-3 py-2"
+
+function getPinningStyles<TData extends object>(
+  column: Column<DataGridFeatures, TData, unknown>
+): CSSProperties {
   const isPinned = column.getIsPinned()
 
   return {
-    left: isPinned === "left" ? `${column.getStart("left")}px` : undefined,
-    right: isPinned === "right" ? `${column.getAfter("right")}px` : undefined,
+    // Logical offsets: TanStack's "left"/"right" buckets are start/end
+    // semantics, so pinned columns stick to the correct edge in RTL too
+    // (identical to left/right in LTR).
+    insetInlineStart:
+      isPinned === "start" ? `${column.getStart("start")}px` : undefined,
+    insetInlineEnd:
+      isPinned === "end" ? `${column.getAfter("end")}px` : undefined,
     position: isPinned ? "sticky" : undefined,
     transform: isPinned ? "translateZ(0)" : undefined,
     contain: isPinned ? "paint" : undefined,
@@ -80,6 +86,18 @@ function getPinningStyles<TData>(column: Column<TData>): CSSProperties {
   }
 }
 
+// Shared indent contract for tree rows: DataGridTableRowExpand consumes it,
+// and fully custom cells can reuse it for depth alignment without the
+// built-in toggle.
+function getDataGridTreeIndentStyle<TData extends object>(
+  row: Row<DataGridFeatures, TData>,
+  indent: number = 20
+): CSSProperties {
+  return {
+    "--data-grid-tree-padding": `${row.depth * indent}px`,
+  } as CSSProperties
+}
+
 function assignRef<T>(ref: Ref<T> | undefined, value: T | null) {
   if (!ref) return
 
@@ -91,55 +109,166 @@ function assignRef<T>(ref: Ref<T> | undefined, value: T | null) {
   ;(ref as { current: T | null }).current = value
 }
 
+/**
+ * Nearest scroll-area viewport that belongs to THIS grid. A viewport outside
+ * the grid's own container (e.g. a page-level ScrollArea) would make the
+ * width measurement - and the virtualizer - bind the wrong box.
+ */
+function getDataGridScrollAreaViewport(node: HTMLElement): HTMLElement | null {
+  const scrollViewport = node.closest(
+    '[data-slot="scroll-area-viewport"]'
+  ) as HTMLElement | null
+
+  if (!scrollViewport) return null
+
+  const gridContainer = node.closest('[data-slot="data-grid"]')
+  if (gridContainer && !gridContainer.contains(scrollViewport)) return null
+
+  return scrollViewport
+}
+
+/**
+ * The box whose width the fill strip tops up to: the grid's own scroll
+ * viewport, else the table viewport's parent. The live resize session and
+ * the viewport's fill sync must measure the same box, or the fill jumps at
+ * release.
+ */
+function getDataGridTableFillMeasurementTarget(node: HTMLElement): HTMLElement {
+  return getDataGridScrollAreaViewport(node) ?? node.parentElement ?? node
+}
+
+/**
+ * True for an event that reached this element only through a React portal.
+ * React bubbles synthetic events along the React tree, so a pick in an
+ * in-cell Select, popover or combobox (its content portalled into <body>)
+ * still reaches the cell and the row. Those must not start or extend a cell
+ * selection or fire onRowClick: the selection session then swallowed the
+ * mouse pick, and the row kept its stale value.
+ */
+function isDataGridPortalEvent(event: {
+  currentTarget: Element
+  target: EventTarget | null
+}) {
+  // Duck-typed, not `instanceof Node`: a grid mounted into an iframe's
+  // document is another realm, where that check fails for every target.
+  const target = event.target as Node | null
+  return !(
+    typeof target?.nodeType === "number" && event.currentTarget.contains(target)
+  )
+}
+
 type DataGridResizeStartEvent =
-  | ReactMouseEvent<HTMLDivElement>
-  | ReactTouchEvent<HTMLDivElement>
+  ReactMouseEvent<HTMLElement> | ReactTouchEvent<HTMLElement>
 
 type DataGridResizeDocumentEvent = globalThis.MouseEvent | globalThis.TouchEvent
 
 function isDataGridTouchEvent(
   event: DataGridResizeStartEvent | DataGridResizeDocumentEvent
-): event is ReactTouchEvent<HTMLDivElement> | globalThis.TouchEvent {
+): event is ReactTouchEvent<HTMLElement> | globalThis.TouchEvent {
   return "touches" in event
 }
 
+type DataGridTouchListLike = {
+  length: number
+  item: (index: number) => { identifier: number; clientX: number } | null
+}
+
+function findTouchClientX(list: DataGridTouchListLike, identifier: number) {
+  for (let i = 0; i < list.length; i++) {
+    const touch = list.item(i)
+    if (touch && touch.identifier === identifier) return touch.clientX
+  }
+
+  return undefined
+}
+
 function getDataGridResizeEventClientX(
-  event: DataGridResizeStartEvent | DataGridResizeDocumentEvent
+  event: DataGridResizeStartEvent | DataGridResizeDocumentEvent,
+  touchIdentifier?: number
 ) {
   if (isDataGridTouchEvent(event)) {
+    if (typeof touchIdentifier === "number") {
+      return (
+        findTouchClientX(event.touches, touchIdentifier) ??
+        findTouchClientX(event.changedTouches, touchIdentifier)
+      )
+    }
+
     return event.touches[0]?.clientX ?? event.changedTouches[0]?.clientX
   }
 
   return event.clientX
 }
 
-function startDataGridColumnResizeOnEnd<TData>(
+function startDataGridColumnResizeOnEnd<TData extends object>(
   event: DataGridResizeStartEvent,
-  header: Header<TData, unknown>,
-  table: Table<TData>
-) {
+  header: Header<DataGridFeatures, TData, unknown>,
+  table: DataGridTableInstance<TData>,
+  /**
+   * Live mode: per-move width updates go straight to the table element's
+   * `--col/--header` variables, so cells track the pointer with ZERO React
+   * renders; state is written twice per drag (start marker, release commit)
+   * instead of per mousemove - which re-renders the consumer's whole tree.
+   */
+  live = false,
+  /** Live mode previews the meta.autoSize reflow with it, so nothing jumps. */
+  autoSize?: DataGridAutoSizeController
+): (() => void) | undefined {
   const column = table.getColumn(header.column.id)
 
   if (!column || !column.getCanResize()) return
-  if (isDataGridTouchEvent(event) && event.touches.length > 1) return
+  const isTouchSession = isDataGridTouchEvent(event)
+  if (isTouchSession && event.touches.length > 1) return
 
   event.persist?.()
 
   const ownerDocument = event.currentTarget.ownerDocument
+  const ownerWindow = ownerDocument.defaultView
   const previousBodyCursor = ownerDocument.body.style.cursor
   const previousDocumentCursor = ownerDocument.documentElement.style.cursor
   const startSize = header.getSize()
-  const dragStartClientX = getDataGridResizeEventClientX(event)
+  // Track the initiating finger so a second touch cannot move or commit the
+  // resize with the wrong clientX.
+  const touchIdentifier = isTouchSession
+    ? event.touches[0]?.identifier
+    : undefined
+  const dragStartClientX = getDataGridResizeEventClientX(event, touchIdentifier)
   const headerCell = event.currentTarget.closest("th")
   const headerRect = headerCell?.getBoundingClientRect()
+  const liveTableElement = live ? headerCell?.closest("table") : null
+  // Live mode moves only the resized columns' variables, so the table and
+  // viewport widths and the fill strip have to move with them, or
+  // table-layout: fixed spreads the difference across every column until
+  // the commit. Each is written in the exact form the commit render and
+  // syncFillWidth produce, so the handover at release is seamless. A
+  // standalone virtual viewport is the scroll container at width auto, and
+  // keeps it.
+  const liveViewportElement =
+    liveTableElement?.closest<HTMLElement>(
+      '[data-slot="data-grid-table-viewport"]'
+    ) ?? null
+  const liveViewportWidthIsComputed =
+    !!liveViewportElement?.style.width.startsWith("calc(")
+  const liveContainerWidth = liveViewportElement
+    ? getDataGridTableFillMeasurementTarget(liveViewportElement).clientWidth
+    : 0
+  const totalSizeStart = table.getTotalSize()
+  const fillColumnId = table
+    .getVisibleLeafColumns()
+    .find((visibleColumn) => visibleColumn.columnDef.meta?.fillWidth)?.id
+  const leafColumns = getDataGridHeaderLeafColumns(header)
+  // An end-pinned column is anchored at its end edge and grows from its
+  // START edge, so its whole resize geometry runs mirrored, exactly like
+  // RTL: the anchor is the opposite edge and the drag direction inverts.
+  // A group's own pin state reads "start" when ANY leaf is, so its leaves
+  // decide.
+  const resizeRtl =
+    (table.options.columnResizeDirection === "rtl") !==
+    (leafColumns[0]?.getIsPinned() === "end")
   const startOffset =
     headerRect &&
-    Number.isFinite(
-      table.options.columnResizeDirection === "rtl"
-        ? headerRect.left
-        : headerRect.right
-    )
-      ? table.options.columnResizeDirection === "rtl"
+    Number.isFinite(resizeRtl ? headerRect.left : headerRect.right)
+      ? resizeRtl
         ? headerRect.left
         : headerRect.right
       : dragStartClientX
@@ -151,21 +280,70 @@ function startDataGridColumnResizeOnEnd<TData>(
   ownerDocument.body.style.cursor = "col-resize"
   ownerDocument.documentElement.style.cursor = "col-resize"
 
-  const columnSizingStart = header
-    .getLeafHeaders()
-    .map(
-      (leafHeader) =>
-        [leafHeader.column.id, leafHeader.column.getSize()] as [string, number]
-    )
-  const directionMultiplier =
-    table.options.columnResizeDirection === "rtl" ? -1 : 1
+  const columnSizingStart = leafColumns.map(
+    (leafColumn) => [leafColumn.id, leafColumn.getSize()] as [string, number]
+  )
+  // Group and merged header cells size from their own variables, which
+  // must follow their leaves through a live drag too.
+  const liveSpanningHeaders = liveTableElement
+    ? getDataGridTableAllFlatHeaders(table)
+        .filter((flatHeader) => flatHeader.subHeaders.length > 0)
+        .map((flatHeader) => ({
+          id: flatHeader.id,
+          leaves: getDataGridHeaderLeafColumns(flatHeader).map(
+            (leafColumn) =>
+              [leafColumn.id, leafColumn.getSize()] as [string, number]
+          ),
+        }))
+    : []
+  const directionMultiplier = resizeRtl ? -1 : 1
+
+  // Clamp the drag to the leaf columns' min/max sizes so the preview
+  // indicator matches what the commit will produce (no overshoot followed by
+  // a snap-back on release). columnDef always carries resolved defaults.
+  let minDeltaPercentage = -0.999999
+  let maxDeltaPercentage = Number.POSITIVE_INFINITY
+  columnSizingStart.forEach(([columnId, headerSize]) => {
+    if (headerSize <= 0) return
+
+    const leafColumn = table.getColumn(columnId)
+    const minSize = leafColumn?.columnDef.minSize
+    const maxSize = leafColumn?.columnDef.maxSize
+
+    if (typeof minSize === "number") {
+      minDeltaPercentage = Math.max(
+        minDeltaPercentage,
+        minSize / headerSize - 1
+      )
+    }
+    if (typeof maxSize === "number" && Number.isFinite(maxSize)) {
+      maxDeltaPercentage = Math.min(
+        maxDeltaPercentage,
+        maxSize / headerSize - 1
+      )
+    }
+  })
+
+  let lastClientX = dragStartClientX
+  let ended = false
+  // The autoSize column's previewed width, committed with the drag at release.
+  let autoSizePreview: { columnId: string; size: number } | null = null
+  const stopListeners: Array<() => void> = []
 
   const updateOffset = (clientXPos?: number, commit = false) => {
     if (typeof clientXPos !== "number") return
 
+    lastClientX = clientXPos
+
     const nextColumnSizing: Record<string, number> = {}
-    const deltaOffset = (clientXPos - dragStartClientX) * directionMultiplier
-    const deltaPercentage = Math.max(deltaOffset / startSize, -0.999999)
+    const deltaPercentage = Math.min(
+      Math.max(
+        ((clientXPos - dragStartClientX) * directionMultiplier) / startSize,
+        minDeltaPercentage
+      ),
+      maxDeltaPercentage
+    )
+    const deltaOffset = deltaPercentage * startSize
 
     columnSizingStart.forEach(([columnId, headerSize]) => {
       nextColumnSizing[columnId] =
@@ -174,17 +352,86 @@ function startDataGridColumnResizeOnEnd<TData>(
         ) / 100
     })
 
-    table.setColumnSizingInfo((old) => ({
-      ...old,
-      startOffset,
-      startSize,
-      deltaOffset,
-      deltaPercentage,
-      columnSizingStart,
-      isResizingColumn: column.id,
-    }))
+    if (liveTableElement) {
+      let totalSize = totalSizeStart
+      columnSizingStart.forEach(([columnId, headerSize]) => {
+        const nextSize = nextColumnSizing[columnId]
+        if (typeof nextSize !== "number") return
+        totalSize += nextSize - headerSize
+        liveTableElement.style.setProperty(
+          `--col-${columnId}-size`,
+          columnId === fillColumnId
+            ? `calc(${nextSize} + var(--data-grid-fill, 0))`
+            : String(nextSize)
+        )
+        liveTableElement.style.setProperty(
+          `--header-${columnId}-size`,
+          String(nextSize)
+        )
+      })
+      // An armed meta.autoSize column would reflow after the commit and move
+      // every column past it, so its reflow is previewed here instead and
+      // committed with the drag. A dragged autoSize column is the user's.
+      const preview = autoSize?.preview(liveContainerWidth - totalSize)
+      autoSizePreview =
+        preview && !(preview.columnId in nextColumnSizing) ? preview : null
+      if (autoSizePreview && preview) {
+        totalSize += preview.size - preview.current
+        liveTableElement.style.setProperty(
+          `--col-${preview.columnId}-size`,
+          preview.columnId === fillColumnId
+            ? `calc(${preview.size} + var(--data-grid-fill, 0))`
+            : String(preview.size)
+        )
+        liveTableElement.style.setProperty(
+          `--header-${preview.columnId}-size`,
+          String(preview.size)
+        )
+      }
+      for (const spanningHeader of liveSpanningHeaders) {
+        let size = 0
+        for (const [columnId, startSize] of spanningHeader.leaves) {
+          size +=
+            nextColumnSizing[columnId] ??
+            (autoSizePreview?.columnId === columnId
+              ? autoSizePreview.size
+              : startSize)
+        }
+        liveTableElement.style.setProperty(
+          `--header-${spanningHeader.id}-size`,
+          String(size)
+        )
+      }
+      const width = `calc(${totalSize}px + var(--data-grid-fill-size, 0px))`
+      liveTableElement.style.width = width
+      if (liveViewportElement) {
+        if (liveViewportWidthIsComputed) {
+          liveViewportElement.style.width = width
+        }
+        const fill = Math.max(0, liveContainerWidth - totalSize)
+        liveViewportElement.style.setProperty(
+          "--data-grid-fill-size",
+          `${fill}px`
+        )
+        liveViewportElement.style.setProperty("--data-grid-fill", String(fill))
+      }
+    } else {
+      table.setColumnResizing((old) => ({
+        ...old,
+        startOffset,
+        startSize,
+        deltaOffset,
+        deltaPercentage,
+        columnSizingStart,
+        isResizingColumn: column.id,
+      }))
+    }
 
     if (commit) {
+      if (autoSizePreview) {
+        nextColumnSizing[autoSizePreview.columnId] = autoSizePreview.size
+        autoSize?.adopt(autoSizePreview.columnId, autoSizePreview.size)
+      }
       table.setColumnSizing((old) => ({
         ...old,
         ...nextColumnSizing,
@@ -192,9 +439,16 @@ function startDataGridColumnResizeOnEnd<TData>(
     }
   }
 
+  // Single teardown path: commits at the given position, removes every
+  // document/window listener, and restores cursors. Safe to call more than
+  // once (blur + mouseup + unmount can race).
   const endResize = (clientXPos?: number) => {
+    if (ended) return
+    ended = true
+
+    stopListeners.forEach((stop) => stop())
     updateOffset(clientXPos, true)
-    table.setColumnSizingInfo((old) => ({
+    table.setColumnResizing((old) => ({
       ...old,
       isResizingColumn: false,
       startOffset: null,
@@ -211,8 +465,6 @@ function startDataGridColumnResizeOnEnd<TData>(
     updateOffset(moveEvent.clientX)
   }
   const mouseUpHandler = (upEvent: globalThis.MouseEvent) => {
-    ownerDocument.removeEventListener("mousemove", mouseMoveHandler)
-    ownerDocument.removeEventListener("mouseup", mouseUpHandler)
     endResize(upEvent.clientX)
   }
   const touchMoveHandler = (moveEvent: globalThis.TouchEvent) => {
@@ -221,23 +473,36 @@ function startDataGridColumnResizeOnEnd<TData>(
       moveEvent.stopPropagation()
     }
 
-    updateOffset(getDataGridResizeEventClientX(moveEvent))
+    updateOffset(getDataGridResizeEventClientX(moveEvent, touchIdentifier))
   }
   const touchEndHandler = (endEvent: globalThis.TouchEvent) => {
-    ownerDocument.removeEventListener("touchmove", touchMoveHandler)
-    ownerDocument.removeEventListener("touchend", touchEndHandler)
+    // Ignore other fingers lifting; only the initiating touch ends the drag.
+    const clientXPos =
+      typeof touchIdentifier === "number"
+        ? findTouchClientX(endEvent.changedTouches, touchIdentifier)
+        : getDataGridResizeEventClientX(endEvent)
+
+    if (typeof clientXPos !== "number") return
 
     if (endEvent.cancelable) {
       endEvent.preventDefault()
       endEvent.stopPropagation()
     }
 
-    endResize(getDataGridResizeEventClientX(endEvent))
+    endResize(clientXPos)
+  }
+  // System-interrupted gestures and window focus loss would otherwise leave
+  // the session (and its document listeners) live with no pointer held.
+  const touchCancelHandler = () => {
+    endResize(lastClientX)
+  }
+  const windowBlurHandler = () => {
+    endResize(lastClientX)
   }
 
   const passiveIfSupported = { passive: false } as const
 
-  if (isDataGridTouchEvent(event)) {
+  if (isTouchSession) {
     ownerDocument.addEventListener(
       "touchmove",
       touchMoveHandler,
@@ -248,6 +513,12 @@ function startDataGridColumnResizeOnEnd<TData>(
       touchEndHandler,
       passiveIfSupported
     )
+    ownerDocument.addEventListener("touchcancel", touchCancelHandler)
+    stopListeners.push(() => {
+      ownerDocument.removeEventListener("touchmove", touchMoveHandler)
+      ownerDocument.removeEventListener("touchend", touchEndHandler)
+      ownerDocument.removeEventListener("touchcancel", touchCancelHandler)
+    })
   } else {
     ownerDocument.addEventListener(
       "mousemove",
@@ -259,9 +530,20 @@ function startDataGridColumnResizeOnEnd<TData>(
       mouseUpHandler,
       passiveIfSupported
     )
+    stopListeners.push(() => {
+      ownerDocument.removeEventListener("mousemove", mouseMoveHandler)
+      ownerDocument.removeEventListener("mouseup", mouseUpHandler)
+    })
   }
 
-  table.setColumnSizingInfo((old) => ({
+  if (ownerWindow) {
+    ownerWindow.addEventListener("blur", windowBlurHandler)
+    stopListeners.push(() =>
+      ownerWindow.removeEventListener("blur", windowBlurHandler)
+    )
+  }
+
+  table.setColumnResizing((old) => ({
     ...old,
     startOffset,
     startSize,
@@ -270,31 +552,33 @@ function startDataGridColumnResizeOnEnd<TData>(
     columnSizingStart,
     isResizingColumn: column.id,
   }))
+
+  return () => endResize(lastClientX)
 }
 
 type DataGridTablePinnedBoundary = "top" | "bottom"
 
-function getDataGridTableRowSections<TData>(
-  table: Table<TData>,
+function getDataGridTableRowSections<TData extends object>(
+  table: DataGridTableInstance<TData>,
   rowsPinnable?: boolean
 ) {
   if (!rowsPinnable) {
     return {
-      topRows: [] as Row<TData>[],
-      centerRows: table.getRowModel().rows as Row<TData>[],
-      bottomRows: [] as Row<TData>[],
+      topRows: [] as Row<DataGridFeatures, TData>[],
+      centerRows: table.getRowModel().rows as Row<DataGridFeatures, TData>[],
+      bottomRows: [] as Row<DataGridFeatures, TData>[],
     }
   }
 
   return {
-    topRows: table.getTopRows() as Row<TData>[],
-    centerRows: table.getCenterRows() as Row<TData>[],
-    bottomRows: table.getBottomRows() as Row<TData>[],
+    topRows: table.getTopRows() as Row<DataGridFeatures, TData>[],
+    centerRows: table.getCenterRows() as Row<DataGridFeatures, TData>[],
+    bottomRows: table.getBottomRows() as Row<DataGridFeatures, TData>[],
   }
 }
 
-function getDataGridTableResolvedRows<TData>(
-  table: Table<TData>,
+function getDataGridTableResolvedRows<TData extends object>(
+  table: DataGridTableInstance<TData>,
   rowsPinnable?: boolean
 ) {
   const { topRows, centerRows, bottomRows } = getDataGridTableRowSections(
@@ -302,7 +586,7 @@ function getDataGridTableResolvedRows<TData>(
     rowsPinnable
   )
   const resolvedRows: Array<{
-    row: Row<TData>
+    row: Row<DataGridFeatures, TData>
     pinnedBoundary?: DataGridTablePinnedBoundary
   }> = []
 
@@ -334,31 +618,106 @@ function getDataGridTableResolvedRows<TData>(
   return resolvedRows
 }
 
-function getDataGridTableOrderedVisibleColumns<TData>(table: Table<TData>) {
+function getDataGridTableOrderedVisibleColumns<TData extends object>(
+  table: DataGridTableInstance<TData>
+) {
   return [
-    ...table.getLeftVisibleLeafColumns(),
+    ...table.getStartVisibleLeafColumns(),
     ...table.getCenterVisibleLeafColumns(),
-    ...table.getRightVisibleLeafColumns(),
-  ] as Column<TData>[]
+    ...table.getEndVisibleLeafColumns(),
+  ] as Column<DataGridFeatures, TData, unknown>[]
 }
 
-function getDataGridTableOrderedVisibleCells<TData>(row: Row<TData>) {
+/**
+ * First or last column as the row renders it: start, center, then end.
+ * `column.getIndex()` follows column order and ignores pinning, so an edge
+ * check built on it picks the wrong cells once pinning moves a column away
+ * from its column-order slot.
+ */
+function getDataGridTableColumnEdges<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  columnId: string
+) {
+  const start = table.getStartVisibleLeafColumns()
+  const center = table.getCenterVisibleLeafColumns()
+  const end = table.getEndVisibleLeafColumns()
+  const first = start[0] ?? center[0] ?? end[0]
+  const last =
+    end[end.length - 1] ?? center[center.length - 1] ?? start[start.length - 1]
+
+  return { isFirst: first?.id === columnId, isLast: last?.id === columnId }
+}
+
+function getDataGridTableOrderedVisibleCells<TData extends object>(
+  row: Row<DataGridFeatures, TData>
+) {
   return [
-    ...row.getLeftVisibleCells(),
+    ...row.getStartVisibleCells(),
     ...row.getCenterVisibleCells(),
-    ...row.getRightVisibleCells(),
-  ] as Cell<TData, unknown>[]
+    ...row.getEndVisibleCells(),
+  ] as Cell<DataGridFeatures, TData, unknown>[]
 }
 
-function getDataGridTableMergedHeaderGroups<TData>(table: Table<TData>) {
-  const leftHeaderGroups = table.getLeftHeaderGroups()
+function getDataGridTableMergedHeaderGroups<TData extends object>(
+  table: DataGridTableInstance<TData>
+) {
+  const leftHeaderGroups = table.getStartHeaderGroups()
   const centerHeaderGroups = table.getCenterHeaderGroups()
-  const rightHeaderGroups = table.getRightHeaderGroups()
+  const rightHeaderGroups = table.getEndHeaderGroups()
   const headerGroupCount = Math.max(
     leftHeaderGroups.length,
     centerHeaderGroups.length,
     rightHeaderGroups.length
   )
+  const spans = getDataGridHeaderSpans(table)
+  // Headers a meta.headerColSpan cell covers, by that cell's header id.
+  const coveredHeaders = new Map<
+    string,
+    Header<DataGridFeatures, TData, unknown>[]
+  >()
+
+  // TanStack gives a merged run rowSpan N on its top cell and 0 on the cells
+  // it covers, so the covered ones are not rendered at all.
+  const getRenderedHeaders = (
+    headers: Header<DataGridFeatures, TData>[] = []
+  ) => {
+    const rendered = headers.filter((header) => header.rowSpan !== 0) as Header<
+      DataGridFeatures,
+      TData,
+      unknown
+    >[]
+    if (!spans.size) return rendered
+
+    const cells: Header<DataGridFeatures, TData, unknown>[] = []
+    for (let index = 0; index < rendered.length; index++) {
+      const header = rendered[index]!
+      cells.push(header)
+      const coveredColumns = header.column.columns.length
+        ? undefined
+        : spans.get(header.column.id)
+      if (!coveredColumns) continue
+
+      // Siblings share their header chain, so each covered cell sits right
+      // after the owner in this row with the same rowSpan.
+      const covered: Header<DataGridFeatures, TData, unknown>[] = []
+      for (const coveredColumn of coveredColumns) {
+        const next = rendered[index + 1 + covered.length]
+        if (
+          next?.column.id !== coveredColumn.id ||
+          next.rowSpan !== header.rowSpan
+        ) {
+          break
+        }
+        covered.push(next)
+      }
+      if (!covered.length) continue
+
+      coveredHeaders.set(header.id, covered)
+      index += covered.length
+    }
+
+    return cells
+  }
 
   return Array.from({ length: headerGroupCount }, (_, index) => {
     const leftGroup = leftHeaderGroups[index]
@@ -374,30 +733,154 @@ function getDataGridTableMergedHeaderGroups<TData>(table: Table<TData>) {
         ...(leftGroup?.headers ?? []),
         ...(centerGroup?.headers ?? []),
         ...(rightGroup?.headers ?? []),
-      ] as Header<TData, unknown>[],
+      ] as Header<DataGridFeatures, TData, unknown>[],
+      // The cells this row renders, per pinning family.
+      startHeaders: getRenderedHeaders(leftGroup?.headers),
+      centerHeaders: getRenderedHeaders(centerGroup?.headers),
+      endHeaders: getRenderedHeaders(rightGroup?.headers),
+      coveredHeaders,
     }
   })
 }
 
-function hasDataGridTableRightPinnedColumns<TData>(table: Table<TData>) {
-  return (table.getState().columnPinning.right?.length ?? 0) > 0
+/**
+ * Every header the head rows may render: the unpinned tree plus each
+ * pinning family's, whose ids carry a family prefix above the leaf row.
+ */
+function getDataGridTableAllFlatHeaders<TData extends object>(
+  table: DataGridTableInstance<TData>
+) {
+  return [
+    ...table.getFlatHeaders(),
+    ...table.getStartFlatHeaders(),
+    ...table.getCenterFlatHeaders(),
+    ...table.getEndFlatHeaders(),
+  ] as Header<DataGridFeatures, TData, unknown>[]
+}
+
+/**
+ * The leaf columns under a header, in render order: a group's leaves, or the
+ * column itself for a leaf or a merged cell. v9 `getLeafHeaders` also returns
+ * the header itself and every intermediate header, so those are dropped.
+ */
+function getDataGridHeaderLeafColumns<TData extends object>(
+  header: Header<DataGridFeatures, TData, unknown>
+) {
+  if (!header.subHeaders.length) return [header.column]
+
+  const leafColumns = header
+    .getLeafHeaders()
+    .filter((leafHeader) => !leafHeader.subHeaders.length)
+    .map((leafHeader) => leafHeader.column)
+
+  return leafColumns.length ? leafColumns : [header.column]
+}
+
+// A placeholder heading a merged run renders its column's header; one left
+// unmerged would repeat the header of the leaf below it.
+function renderDataGridTableHeadCellContent<TData extends object>(
+  header: Header<DataGridFeatures, TData, unknown>
+) {
+  return header.isPlaceholder && header.rowSpan <= 1
+    ? null
+    : flexRender(header.column.columnDef.header, header.getContext())
+}
+
+// A span's handle drives its last covered leaf; end-pinned, it sits on the
+// start edge and drives the owner, as an end-pinned group's handle does.
+function getDataGridHeadCellResizeHeader<TData extends object>(
+  header: Header<DataGridFeatures, TData, unknown>,
+  coveredHeaders?: Header<DataGridFeatures, TData, unknown>[]
+) {
+  return coveredHeaders?.length && header.column.getIsPinned() !== "end"
+    ? coveredHeaders[coveredHeaders.length - 1]!
+    : header
+}
+
+// A span sums its covered leaves' variables, so a live resize of any of them
+// moves its edge too.
+function getDataGridHeadCellSizeVar<TData extends object>(
+  header: Header<DataGridFeatures, TData, unknown>,
+  coveredHeaders: Header<DataGridFeatures, TData, unknown>[] = []
+) {
+  if (!coveredHeaders.length)
+    return `calc(var(--header-${header.id}-size) * 1px)`
+
+  const sizes = [header, ...coveredHeaders].map(
+    (spanned) => `var(--header-${spanned.id}-size)`
+  )
+  return `calc((${sizes.join(" + ")}) * 1px)`
+}
+
+/**
+ * Which edge of a leaf column's header draws a resting divider line, or null
+ * for none. Mirrors the branches of DataGridTableHeadRowCellResize, so a
+ * group cell above can continue exactly the lines its leaves draw.
+ */
+function getDataGridHeaderLineEdge<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  tableLayout: DataGridLayoutProps<TData>["tableLayout"],
+  column: Column<DataGridFeatures, TData, unknown>
+): "start" | "end" | null {
+  if (!tableLayout?.columnsResizable || !column.getCanResize()) return null
+
+  const isPinned = column.getIsPinned()
+
+  if (isPinned === "end") return tableLayout.columnsPinnable ? null : "start"
+  if (getDataGridTableColumnEdges(table, column.id).isLast) return null
+  if (isPinned) return tableLayout.columnsPinnable ? null : "end"
+  if (tableLayout.cellBorder) return null
+  if (
+    tableLayout.columnsPinnable &&
+    column.getIsLastColumn("center") &&
+    hasDataGridTableRightPinnedColumns(table)
+  ) {
+    return null
+  }
+
+  return "end"
+}
+
+function hasDataGridTableRightPinnedColumns<TData extends object>(
+  table: DataGridTableInstance<TData>
+) {
+  return (table.state.columnPinning.end?.length ?? 0) > 0
+}
+
+// A meta.fillWidth column absorbs the free space itself, so the fill cells
+// must collapse or the strip would be counted twice.
+function hasDataGridFillColumn<TData extends object>(
+  table: DataGridTableInstance<TData>
+) {
+  return table
+    .getVisibleLeafColumns()
+    .some((column) => column.columnDef.meta?.fillWidth)
 }
 
 function DataGridTableFillCol() {
-  const { props } = useDataGrid()
+  const { props, table } = useDataGrid()
 
   if (!props.tableLayout?.columnsResizable) return null
 
   return (
     <col
       data-slot="data-grid-table-fill-col"
-      style={{ width: "var(--data-grid-fill-size, 0px)" }}
+      style={{
+        width: hasDataGridFillColumn(table)
+          ? 0
+          : "var(--data-grid-fill-size, 0px)",
+      }}
     />
   )
 }
 
-function DataGridTableFillHeadCell() {
-  const { props } = useDataGrid()
+function DataGridTableFillHeadCell({
+  rowSpan,
+}: {
+  /** Multi-level headers render one fill cell spanning every head row. */
+  rowSpan?: number
+} = {}) {
+  const { props, table } = useDataGrid()
 
   if (!props.tableLayout?.columnsResizable) return null
 
@@ -405,14 +888,19 @@ function DataGridTableFillHeadCell() {
     <th
       aria-hidden="true"
       data-slot="data-grid-table-fill-head-cell"
-      style={{ width: "var(--data-grid-fill-size, 0px)" }}
-      className="p-0"
+      rowSpan={rowSpan && rowSpan > 1 ? rowSpan : undefined}
+      style={{
+        width: hasDataGridFillColumn(table)
+          ? 0
+          : "var(--data-grid-fill-size, 0px)",
+      }}
+      className={cn("p-0", props.tableLayout?.headerBackground && "bg-muted")}
     />
   )
 }
 
 function DataGridTableFillBodyCell() {
-  const { props } = useDataGrid()
+  const { props, table } = useDataGrid()
 
   if (!props.tableLayout?.columnsResizable) return null
 
@@ -420,14 +908,18 @@ function DataGridTableFillBodyCell() {
     <td
       aria-hidden="true"
       data-slot="data-grid-table-fill-body-cell"
-      style={{ width: "var(--data-grid-fill-size, 0px)" }}
+      style={{
+        width: hasDataGridFillColumn(table)
+          ? 0
+          : "var(--data-grid-fill-size, 0px)",
+      }}
       className="p-0"
     />
   )
 }
 
 function DataGridTableFillFootCell() {
-  const { props } = useDataGrid()
+  const { props, table } = useDataGrid()
 
   if (!props.tableLayout?.columnsResizable) return null
 
@@ -435,17 +927,93 @@ function DataGridTableFillFootCell() {
     <td
       aria-hidden="true"
       data-slot="data-grid-table-fill-foot-cell"
-      style={{ width: "var(--data-grid-fill-size, 0px)" }}
+      style={{
+        width: hasDataGridFillColumn(table)
+          ? 0
+          : "var(--data-grid-fill-size, 0px)",
+      }}
       className="p-0"
     />
   )
 }
 
+/**
+ * The quick-create affordance, rendered as the body's last row when
+ * `onRowCreate` is set: one full-width ghost button, the Notion/Airtable
+ * "+ New" idiom. What the click creates stays consumer-owned.
+ */
+function DataGridTableAddRow() {
+  const context = useDataGrid()
+  const { i18n, props, table } = context
+
+  if (!props.onRowCreate) return null
+
+  return (
+    <tr
+      data-slot="data-grid-table-add-row"
+      className={cn(
+        "hover:bg-muted/40 [thead+tbody_&:first-child]:border-t",
+        props.tableClassNames?.rowCreate
+      )}
+    >
+      <td
+        // The extra column is the filler strip, rendered only when columns
+        // are resizable.
+        colSpan={
+          table.getVisibleLeafColumns().length +
+          (props.tableLayout?.columnsResizable ? 1 : 0)
+        }
+        className="p-0"
+      >
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          // Block-level flex: inline-flex would sit on the cell's text
+          // baseline and push the icon and label off vertical center.
+          className={cn(
+            "text-muted-foreground flex w-full items-center justify-start rounded-none px-3",
+            props.tableLayout?.dense ? "h-8 px-2" : "h-9"
+          )}
+          onClick={(event) => {
+            // Creating often unmounts this affordance (a draft row takes
+            // its place); focus would fall to the body and strand the
+            // keyboard. Hand it to the grid's focus target instead - but
+            // only when it was actually lost, so a consumer that keeps
+            // the button mounted keeps repeated Enter presses working.
+            // A timer, not rAF: timers also run in background tabs.
+            const button = event.currentTarget
+            const grid = button.closest("table")
+            // Through the getter: this render's props can hold an older
+            // callback, since the context counts callbacks by presence.
+            context.props.onRowCreate?.()
+            setTimeout(() => {
+              if (
+                !button.isConnected &&
+                grid?.isConnected &&
+                grid.tabIndex >= 0 &&
+                (document.activeElement === document.body ||
+                  !document.activeElement)
+              ) {
+                grid.focus()
+              }
+            }, 0)
+          }}
+        >
+          <PlusIcon className="size-4" aria-hidden="true" />
+          {props.rowCreateLabel ?? i18n.labels.rowCreate}
+        </Button>
+      </td>
+    </tr>
+  )
+}
+
 function DataGridTableBase({ children }: { children: ReactNode }) {
-  const { props, table } = useDataGrid()
-  const leftVisibleColumns = table.getLeftVisibleLeafColumns()
+  const { props, table, recordCount } = useDataGrid()
+  const columnSizing = useDataGridAtom(table.atoms.columnSizing)
+  const leftVisibleColumns = table.getStartVisibleLeafColumns()
   const centerVisibleColumns = table.getCenterVisibleLeafColumns()
-  const rightVisibleColumns = table.getRightVisibleLeafColumns()
+  const rightVisibleColumns = table.getEndVisibleLeafColumns()
   const hasRightPinnedColumns = hasDataGridTableRightPinnedColumns(table)
 
   /**
@@ -456,26 +1024,81 @@ function DataGridTableBase({ children }: { children: ReactNode }) {
    */
   const columnSizeVars = useMemo(() => {
     if (!props.tableLayout?.columnsResizable) return undefined
-    const headers = table.getFlatHeaders()
-    const colSizes: Record<string, number> = {}
+    // Head rows render the pinning families' headers, whose group and
+    // merged-cell ids differ from the unpinned tree's; both sets get a size.
+    const headers = getDataGridTableAllFlatHeaders(table)
+    // A meta.fillWidth column absorbs the filler strip: its size variable
+    // carries the unitless fill amount, so every consumer of
+    // calc(var(--col-X-size) * 1px) stretches with the container while the
+    // fill cells collapse to zero.
+    const fillColumnId = table
+      .getVisibleLeafColumns()
+      .find((column) => column.columnDef.meta?.fillWidth)?.id
+    const colSizes: Record<string, number | string> = {}
     for (let i = 0; i < headers.length; i++) {
       const header = headers[i]!
       colSizes[`--header-${header.id}-size`] = header.getSize()
-      colSizes[`--col-${header.column.id}-size`] = header.column.getSize()
+      colSizes[`--col-${header.column.id}-size`] =
+        header.column.id === fillColumnId
+          ? `calc(${header.column.getSize()} + var(--data-grid-fill, 0))`
+          : header.column.getSize()
     }
     return colSizes
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     props.tableLayout?.columnsResizable,
+    columnSizing,
+    // Visibility/order/pinning change the flat header set, so a column shown
+    // after mount must get its size variable even though sizing is untouched.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    table.getState().columnSizing,
+    table.state.columnVisibility,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    table.state.columnOrder,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    table.state.columnPinning,
+    // A def swap can change a column's `size` without touching sizing
+    // STATE; without this dep the CSS variables keep the old widths. For a
+    // consumer defining columns inline the memo degrades to per-render
+    // recompute, which is the safe direction.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    table.options.columns,
   ])
 
+  // With cell selection on, the table announces as a grid so the tds compute
+  // as gridcells and aria-selected applies; existing grids keep their plain
+  // semantic table untouched.
+  const cellSelectionOn =
+    !!props.tableLayout?.cellSelection && table.atoms.cellSelection != null
+
   return (
     <table
       data-slot="data-grid-table"
+      role={cellSelectionOn ? "grid" : undefined}
+      aria-multiselectable={
+        cellSelectionOn && props.tableLayout?.cellSelectionMode !== "single"
+          ? true
+          : undefined
+      }
+      // recordCount can undercount the rows actually present (a pinned
+      // draft row a consumer keeps out of its totals), and aria-rowindex
+      // is computed from the full display order; the union keeps every
+      // announced index inside the announced count.
+      aria-rowcount={
+        cellSelectionOn
+          ? Math.max(recordCount, table.getRowsInDisplayOrder().length) + 1
+          : undefined
+      }
       className={cn(
         "text-foreground caption-bottom text-left align-middle text-sm font-normal rtl:text-right",
+        /* Opaque surfaces (pinned cells, the footer band, their premixed
+           tints) read --data-grid-surface and fall back to --background;
+           inside a Card that is the wrong token, so they follow --card. The
+           Card value is a fallback of its own, not --data-grid-surface: set
+           here on the table it would beat the consumer's ancestor value. */
+        "in-data-[slot=card]:[--data-grid-card-surface:var(--card)]",
+        /* Pinned-edge separators are inset box-shadows, which are physical;
+           this sign flips them under RTL so each stays on its inline seam. */
+        "rtl:[--data-grid-dir:-1]",
         props.tableLayout?.columnsResizable ? "min-w-0" : "w-full min-w-full",
         props.tableLayout?.width === "auto" ? "table-auto" : "table-fixed",
         !props.tableLayout?.columnsResizable && "",
@@ -536,85 +1159,92 @@ function DataGridTableViewport({
   viewportRef?: Ref<HTMLDivElement>
   style?: CSSProperties
 }) {
-  const { props, table } = useDataGrid()
-  const didApplyAutoSizeColumnRef = useRef<string | null>(null)
-  const [viewportElement, setViewportElement] = useState<HTMLDivElement | null>(
-    null
-  )
-  const [containerWidth, setContainerWidth] = useState(0)
+  const { props, table, autoSize } = useDataGrid()
+  // The width below and the fill re-sync follow every sizing write.
+  useDataGridAtom(table.atoms.columnSizing)
+  const isColumnsResizable = !!props.tableLayout?.columnsResizable
+  const viewportNodeRef = useRef<HTMLDivElement | null>(null)
+  const fillStateRef = useRef({ containerWidth: 0, appliedFill: -1 })
+  const stopContainerObserverRef = useRef<(() => void) | null>(null)
+  // v9 hands out a new table per state change. Closing over it gave the ref
+  // callback below a new identity every render, and React then detached and
+  // reattached it: a new ResizeObserver and a re-measure on every drag frame,
+  // and a null viewportNodeRef during every child layout effect in between.
+  // The latest values ride a ref instead, so the callback keeps one identity.
+  const latestRef = useRef({ table, autoSize })
+  useLayoutEffect(() => {
+    latestRef.current = { table, autoSize }
+  })
+
+  // Free space is written as a CSS variable directly on the viewport node
+  // instead of React state, so container resizes and column-size commits
+  // reach the fill column without re-rendering the grid.
+  const syncFillWidth = useCallback(() => {
+    const node = viewportNodeRef.current
+    if (!node) return
+
+    const latest = latestRef.current
+    const freeSpace =
+      fillStateRef.current.containerWidth - latest.table.getTotalSize()
+    const fillWidth = Math.max(0, freeSpace)
+
+    if (fillStateRef.current.appliedFill !== fillWidth) {
+      fillStateRef.current.appliedFill = fillWidth
+      node.style.setProperty("--data-grid-fill-size", `${fillWidth}px`)
+      // Unitless twin for the meta.fillWidth column, whose size variable
+      // participates in a calc that multiplies by 1px afterwards.
+      node.style.setProperty("--data-grid-fill", String(fillWidth))
+    }
+
+    // Signed on purpose: a shrinking container drives the free space
+    // NEGATIVE, which is exactly what tells a meta.autoSize column to hand
+    // its absorbed width back.
+    latest.autoSize?.apply(freeSpace)
+  }, [])
+
   const handleViewportRef = useCallback(
     (node: HTMLDivElement | null) => {
-      setViewportElement(node)
+      stopContainerObserverRef.current?.()
+      stopContainerObserverRef.current = null
+      viewportNodeRef.current = node
+      assignRef(viewportRef, node)
 
-      if (props.tableLayout?.columnsResizable && node) {
-        const scrollViewport =
-          (node.closest(
-            '[data-slot="scroll-area-viewport"]'
-          ) as HTMLElement | null) ?? node.parentElement
-        const measurementTarget = scrollViewport ?? node
+      if (!node) return
 
-        setContainerWidth(measurementTarget.clientWidth)
-      } else if (!node) {
-        setContainerWidth(0)
+      if (!isColumnsResizable) {
+        fillStateRef.current.appliedFill = -1
+        node.style.removeProperty("--data-grid-fill-size")
+        node.style.removeProperty("--data-grid-fill")
+        return
       }
 
-      assignRef(viewportRef, node)
+      const measurementTarget = getDataGridTableFillMeasurementTarget(node)
+
+      const measure = () => {
+        fillStateRef.current.containerWidth = measurementTarget.clientWidth
+        syncFillWidth()
+      }
+
+      // First measure runs inside the mount commit, before paint, so the fill
+      // column and any meta.autoSize growth land in the first painted frame.
+      measure()
+
+      if (typeof ResizeObserver !== "undefined") {
+        const observer = new ResizeObserver(measure)
+        observer.observe(measurementTarget)
+        stopContainerObserverRef.current = () => observer.disconnect()
+      }
     },
-    [props.tableLayout?.columnsResizable, viewportRef]
+    [isColumnsResizable, syncFillWidth, viewportRef]
   )
-  const fillWidth =
-    props.tableLayout?.columnsResizable && containerWidth > 0
-      ? Math.max(0, containerWidth - table.getTotalSize())
-      : 0
-  const autoSizeColumnId = table
-    .getVisibleLeafColumns()
-    .find(
-      (column) => column.columnDef.meta?.autoSize && column.getCanResize()
-    )?.id
 
+  // Column sizing commits and visibility changes alter the table's total size
+  // without moving the container, so the fill var must re-sync after renders
+  // the ResizeObserver never sees. No-ops when the value is unchanged.
   useLayoutEffect(() => {
-    if (!viewportElement || !props.tableLayout?.columnsResizable) {
-      setContainerWidth(0)
-      return
-    }
-
-    const scrollViewport =
-      (viewportElement.closest(
-        '[data-slot="scroll-area-viewport"]'
-      ) as HTMLElement | null) ?? viewportElement.parentElement
-    const measurementTarget = scrollViewport ?? viewportElement
-
-    const syncContainerWidth = () => {
-      setContainerWidth(measurementTarget.clientWidth)
-    }
-
-    syncContainerWidth()
-
-    if (typeof ResizeObserver === "undefined") return
-
-    const observer = new ResizeObserver(syncContainerWidth)
-    observer.observe(measurementTarget)
-
-    return () => {
-      observer.disconnect()
-    }
-  }, [props.tableLayout?.columnsResizable, viewportElement])
-
-  useLayoutEffect(() => {
-    if (!props.tableLayout?.columnsResizable) return
-    if (!autoSizeColumnId || fillWidth <= 0) return
-    if (didApplyAutoSizeColumnRef.current === autoSizeColumnId) return
-
-    const autoSizeColumn = table.getColumn(autoSizeColumnId)
-    if (!autoSizeColumn) return
-
-    didApplyAutoSizeColumnRef.current = autoSizeColumnId
-    table.setColumnSizing((old) => ({
-      ...old,
-      [autoSizeColumnId]:
-        (old[autoSizeColumnId] ?? autoSizeColumn.getSize()) + fillWidth,
-    }))
-  }, [autoSizeColumnId, fillWidth, props.tableLayout?.columnsResizable, table])
+    if (!isColumnsResizable) return
+    syncFillWidth()
+  })
 
   return (
     <div
@@ -622,17 +1252,16 @@ function DataGridTableViewport({
       ref={handleViewportRef}
       className={cn("relative min-w-full align-top", className)}
       style={{
-        ...(props.tableLayout?.columnsResizable
+        ...(isColumnsResizable
           ? {
               width: `calc(${table.getTotalSize()}px + var(--data-grid-fill-size, 0px))`,
-              ["--data-grid-fill-size" as string]: `${fillWidth}px`,
             }
           : undefined),
         ...style,
       }}
     >
       {children}
-      <DataGridTableResizeIndicator viewportElement={viewportElement} />
+      <DataGridTableResizeIndicator viewportNodeRef={viewportNodeRef} />
     </div>
   )
 }
@@ -654,18 +1283,22 @@ function DataGridTableHead({ children }: { children: ReactNode }) {
 
 function DataGridTableHeadRow({
   children,
-  rowId: _rowId,
+  rowId,
 }: {
   children: ReactNode
   rowId: string
 }) {
-  const { props } = useDataGrid()
+  const { props, table } = useDataGrid()
+  const isMultiLevel = table.getHeaderGroups().length > 1
 
   return (
     <tr
+      aria-rowindex={props.tableLayout?.cellSelection ? 1 : undefined}
       className={cn(
         props.tableLayout?.headerBorder && "[&>th]:border-b",
-        props.tableLayout?.cellBorder && "*:last:border-e-0",
+        // Under row-merged cells a row's last child is not the last column;
+        // multi-level cells drop their own end border instead.
+        props.tableLayout?.cellBorder && !isMultiLevel && "*:last:border-e-0",
         props.tableLayout?.stripped && "bg-transparent",
         props.tableLayout?.headerBackground === false && "bg-transparent",
         props.tableClassNames?.headerRow
@@ -676,147 +1309,417 @@ function DataGridTableHeadRow({
   )
 }
 
-function DataGridTableHeadRowCell<TData>({
+function DataGridTableHeadRowCell<TData extends object>({
   children,
   header,
+  coveredHeaders = [],
   dndRef,
   dndStyle,
 }: {
   children: ReactNode
-  header: Header<TData, unknown>
+  header: Header<DataGridFeatures, TData, unknown>
+  /** Headers this cell spans through meta.headerColSpan; they render none. */
+  coveredHeaders?: Header<DataGridFeatures, TData, unknown>[]
   dndRef?: React.Ref<HTMLTableCellElement>
   dndStyle?: CSSProperties
 }) {
-  const { props } = useDataGrid()
+  const { props, table } = useDataGrid<TData>()
+  // Pinned offsets and the span width below are read from sizing state.
+  useDataGridAtom(table.atoms.columnSizing)
 
   const { column } = header
-  const isPinned = column.getIsPinned()
-  const isFirstLeftPinned =
-    isPinned === "left" && column.getIsFirstColumn("left")
-  const isLastLeftPinned = isPinned === "left" && column.getIsLastColumn("left")
-  const isFirstRightPinned =
-    isPinned === "right" && column.getIsFirstColumn("right")
-  const isLastRightPinned =
-    isPinned === "right" && column.getIsLastColumn("right")
-  const isLastVisibleColumn =
-    column.getIndex() ===
-    header.getContext().table.getVisibleLeafColumns().length - 1
+  // A group cell spans several leaves, and its own column reads pinned when
+  // ANY leaf is and has no index or offsets: pin state, edges and offsets
+  // come from its first and last leaf instead. A leaf is both.
+  const isGroup = column.columns.length > 0
+  // A span runs from its own leaf to its last covered leaf.
+  const isSpan = coveredHeaders.length > 0
+  const leafColumns = isSpan
+    ? [column, ...coveredHeaders.map((covered) => covered.column)]
+    : getDataGridHeaderLeafColumns(header)
+  const colSpan = coveredHeaders.reduce(
+    (sum, covered) => sum + covered.colSpan,
+    header.colSpan
+  )
+  const size = coveredHeaders.reduce(
+    (sum, covered) => sum + covered.getSize(),
+    header.getSize()
+  )
+  const resizeColumn = getDataGridHeadCellResizeHeader(
+    header,
+    coveredHeaders
+  ).column
+  const firstLeaf = leafColumns[0] ?? column
+  const lastLeaf = leafColumns[leafColumns.length - 1] ?? column
+  const isPinned = firstLeaf.getIsPinned()
+  const isFirstStartPinned =
+    isPinned === "start" && firstLeaf.getIsFirstColumn("start")
+  const isLastStartPinned =
+    isPinned === "start" && lastLeaf.getIsLastColumn("start")
+  const isFirstEndPinned =
+    isPinned === "end" && firstLeaf.getIsFirstColumn("end")
+  const isLastEndPinned = isPinned === "end" && lastLeaf.getIsLastColumn("end")
+  const edges = {
+    isFirst: getDataGridTableColumnEdges(table, firstLeaf.id).isFirst,
+    isLast: getDataGridTableColumnEdges(table, lastLeaf.id).isLast,
+  }
+  const isMultiLevel = table.getHeaderGroups().length > 1
+  // Every cell that ends on the header's bottom edge - merged cells and the
+  // leaf row - holds its content in a leaf-row-high band at the bottom, so
+  // merged labels sit level with the leaf labels.
+  const isBanded =
+    header.rowSpan > 1 || (isMultiLevel && header.subHeaders.length === 0)
+  // A group with no resize handle of its own continues the line its edge
+  // leaf draws through the group row.
+  const groupLineEdge =
+    isGroup && !column.getCanResize()
+      ? getDataGridHeaderLineEdge(table, props.tableLayout, lastLeaf) === "end"
+        ? "end"
+        : getDataGridHeaderLineEdge(table, props.tableLayout, firstLeaf) ===
+            "start"
+          ? "start"
+          : null
+      : null
+  const hasColumnDividers =
+    !!props.tableLayout?.cellBorder || !!props.tableLayout?.columnsResizable
   const headerCellSpacing = headerCellSpacingVariants({
     size: props.tableLayout?.dense ? "dense" : "default",
   })
 
+  const sortDirection = column.getIsSorted()
+
   return (
     <th
       ref={dndRef}
+      // One colgroup holds every col, so a group or span is a col header
+      // whose colSpan carries its reach; colgroup would claim every column.
+      scope="col"
+      colSpan={colSpan > 1 ? colSpan : undefined}
+      rowSpan={header.rowSpan > 1 ? header.rowSpan : undefined}
+      aria-sort={
+        sortDirection === "asc"
+          ? "ascending"
+          : sortDirection === "desc"
+            ? "descending"
+            : column.getCanSort()
+              ? "none"
+              : undefined
+      }
+      aria-colindex={
+        props.tableLayout?.cellSelection ? firstLeaf.getIndex() + 1 : undefined
+      }
+      data-col-id={column.id}
+      data-header-id={header.id}
+      // TanStack's header.depth runs 1 to n; the row's depth is 0-based.
+      data-header-depth={header.headerGroup?.depth}
+      data-group={isGroup || undefined}
+      data-merged={header.rowSpan > 1 || undefined}
+      data-span={isSpan ? colSpan : undefined}
       style={{
         ...(props.tableLayout?.width === "fixed" &&
           !props.tableLayout?.columnsResizable && {
-            width: header.getSize(),
+            width: size,
           }),
         ...(props.tableLayout?.columnsPinnable &&
           column.getCanPin() &&
-          getPinningStyles(column)),
+          (isGroup || isSpan
+            ? {
+                // Sticky offset from the edge leaf on the pinned side; the
+                // width is this family's share of the group, or the span's.
+                ...getPinningStyles(isPinned === "end" ? lastLeaf : firstLeaf),
+                width: size,
+              }
+            : getPinningStyles(column))),
+        // A sticky child does not ride a sticky ancestor: under a sticky
+        // header the pinned cell's own position:sticky (horizontal) opts it
+        // out of the thead's vertical stickiness, and the corner scrolls
+        // away while its non-positioned siblings stick. Pin both axes on
+        // the cell itself.
+        ...(props.tableLayout?.headerSticky && isPinned && { top: 0 }),
         ...(props.tableLayout?.columnsResizable && {
-          width: `calc(var(--header-${header.id}-size) * 1px)`,
+          width: getDataGridHeadCellSizeVar(header, coveredHeaders),
         }),
         ...(dndStyle ? dndStyle : null),
       }}
       data-pinned={isPinned || undefined}
       data-outer-pinned-col={
-        isFirstLeftPinned ? "left" : isLastRightPinned ? "right" : undefined
+        isFirstStartPinned ? "start" : isLastEndPinned ? "end" : undefined
       }
       data-last-col={
-        isLastLeftPinned ? "left" : isFirstRightPinned ? "right" : undefined
+        isLastStartPinned ? "start" : isFirstEndPinned ? "end" : undefined
       }
       className={cn(
         "text-foreground relative h-10 text-left align-middle font-medium rtl:text-right [&:has([role=checkbox])]:pe-0",
         headerCellSpacing,
+        isBanded && "align-bottom",
         props.tableLayout?.headerBackground && "bg-muted",
         props.tableLayout?.cellBorder && "border-e",
+        // Multi-level rows end on different columns, so each cell checks
+        // its own last leaf instead of the row's last-child rule.
+        props.tableLayout?.cellBorder &&
+          isMultiLevel &&
+          edges.isLast &&
+          "border-e-0",
+        // The resize filler column follows the center group, and a border on
+        // the last center cell would float against that empty strip.
+        props.tableLayout?.cellBorder &&
+          props.tableLayout?.columnsResizable &&
+          // With end-pinned columns but no pin affordance, the pinned edge
+          // draws no separator of its own; keep the border then.
+          (props.tableLayout?.columnsPinnable ||
+            !hasDataGridTableRightPinnedColumns(table)) &&
+          !isPinned &&
+          lastLeaf.getIsLastColumn("center") &&
+          "border-e-0",
+        // A group's own bottom border is the rule spanning exactly its
+        // leaves, drawn whatever headerBorder says. With no column lines it
+        // would fuse with the next group's, so an inset rule replaces it.
+        isGroup && (hasColumnDividers ? "border-b" : "border-b-transparent"),
         props.tableLayout?.columnsResizable &&
-          column.getCanResize() &&
+          resizeColumn.getCanResize() &&
           (isPinned ? "overflow-hidden" : "overflow-visible"),
+        /* Clears the last column's end-edge resize handle. An end-pinned
+           column's handle sits at its start edge instead, and the padding
+           would only push a centred label off-centre and clip it. */
         props.tableLayout?.columnsResizable &&
-          column.getCanResize() &&
-          isLastVisibleColumn &&
+          resizeColumn.getCanResize() &&
+          edges.isLast &&
+          isPinned !== "end" &&
           "pe-8",
         props.tableLayout?.columnsPinnable &&
           column.getCanPin() &&
           cn(
             "data-pinned:bg-muted data-outer-pinned-col:bg-clip-padding data-pinned:isolate",
-            "[&[data-pinned=left][data-last-col=left]]:shadow-[inset_-1px_0_0_0_var(--border)] [&[data-pinned=right]:last-child_div.cursor-col-resize:last-child]:opacity-0 [&[data-pinned=right][data-last-col=right]]:shadow-[inset_1px_0_0_0_var(--border)]",
-            "[&:not([data-pinned]):has(+[data-pinned])_div.cursor-col-resize:last-child]:opacity-0 [&[data-last-col=left]_div.cursor-col-resize:last-child]:opacity-0"
+            /* No rule here may reach the resize handle: it sits outside the
+               handle's own cn(), so the onChange resize line could not undo
+               it. The handle decides its own line. */
+            "[&[data-pinned=end][data-last-col=end]]:shadow-[inset_calc(1px*var(--data-grid-dir,1))_0_0_0_var(--border)] [&[data-pinned=start][data-last-col=start]]:shadow-[inset_calc(-1px*var(--data-grid-dir,1))_0_0_0_var(--border)]"
           ),
         header.column.columnDef.meta?.headerClassName,
-        column.getIndex() === 0 ||
-          column.getIndex() === header.headerGroup.headers.length - 1
-          ? props.tableClassNames?.edgeCell
-          : ""
+        edges.isFirst || edges.isLast ? props.tableClassNames?.edgeCell : ""
       )}
     >
-      {children}
+      {isBanded ? (
+        // The band is the leaf cell's content box (its height less the
+        // header border). Fixed layout keeps nowrap content truncating; the
+        // band is not positioned, so the resize handle still spans the th.
+        <div
+          data-slot="data-grid-table-head-cell-band"
+          className={cn(
+            "table w-full table-fixed",
+            props.tableLayout?.dense
+              ? props.tableLayout?.headerBorder
+                ? "h-[calc(--spacing(8)-1px)]"
+                : "h-8"
+              : props.tableLayout?.headerBorder
+                ? "h-[calc(--spacing(10)-1px)]"
+                : "h-10"
+          )}
+        >
+          <div className="table-cell align-middle">{children}</div>
+        </div>
+      ) : (
+        children
+      )}
+      {isGroup && !hasColumnDividers ? (
+        <span
+          aria-hidden="true"
+          data-slot="data-grid-table-head-group-rule"
+          className={cn(
+            "bg-border pointer-events-none absolute h-px",
+            // On the cell's last pixel row: over the transparent header
+            // border when there is one, as the border-b rule paints.
+            props.tableLayout?.headerBorder ? "-bottom-px" : "bottom-0",
+            props.tableLayout?.dense ? "inset-x-2" : "inset-x-3"
+          )}
+        />
+      ) : null}
+      {groupLineEdge ? (
+        <span
+          aria-hidden="true"
+          data-slot="data-grid-table-head-divider"
+          className={cn(
+            "bg-border pointer-events-none absolute inset-y-0 w-px",
+            groupLineEdge === "end" ? "end-0" : "start-0"
+          )}
+        />
+      ) : null}
     </th>
   )
 }
 
-function DataGridTableHeadRowCellResize<TData>({
+/**
+ * TanStack's own default, restated here on purpose.
+ *
+ * v8 merged each feature's default table options into `table.options`, so
+ * reading `table.options.columnResizeMode` gave you `"onEnd"` even when the
+ * consumer never set it. v9 resolves feature defaults internally and leaves
+ * the option `undefined` on the instance, so the old `?? table.options...`
+ * fallback quietly produced `undefined` - and every grid that had not opted
+ * into a mode explicitly lost the onEnd drag session: no cursor lock, no
+ * vertical indicator, and an immediate commit instead of a deferred one.
+ */
+const DATA_GRID_DEFAULT_COLUMN_RESIZE_MODE = "onEnd" as const
+
+function getDataGridColumnResizeMode(
+  layoutMode: "onChange" | "onEnd" | undefined,
+  tableMode: "onChange" | "onEnd" | undefined
+) {
+  return layoutMode ?? tableMode ?? DATA_GRID_DEFAULT_COLUMN_RESIZE_MODE
+}
+
+function DataGridTableHeadRowCellResize<TData extends object>({
   header,
 }: {
-  header: Header<TData, unknown>
+  header: Header<DataGridFeatures, TData, unknown>
 }) {
-  const { props, table } = useDataGrid()
+  const { props, table, autoSize } = useDataGrid<TData>()
+  // Re-renders as a drag starts and ends, for column.getIsResizing() below.
+  useDataGridAtom(
+    table.atoms.columnResizing,
+    (resizing) => resizing?.isResizingColumn
+  )
   const { column } = header
-  const isPinned = column.getIsPinned()
-  const isLastVisibleColumn =
-    column.getIndex() ===
-    header.getContext().table.getVisibleLeafColumns().length - 1
+  // A group's handle sits on its edge leaf's boundary: the last leaf, or
+  // the first for an end-pinned group, which resizes from its start edge.
+  const leafColumns = getDataGridHeaderLeafColumns(header)
+  const isPinned = (leafColumns[0] ?? column).getIsPinned()
+  const edgeColumn =
+    (isPinned === "end"
+      ? leafColumns[0]
+      : leafColumns[leafColumns.length - 1]) ?? column
+  const isLastVisibleColumn = getDataGridTableColumnEdges(
+    table,
+    edgeColumn.id
+  ).isLast
+  // Under columnsPinnable the first end-pinned cell draws the seam's
+  // separator, so the last center column drops its own line, as the last
+  // visible column and cellBorder grids already do. Not a th selector: the
+  // cells between the groups vary by renderer, and a hide set outside this
+  // cn() would also kill the onChange resize line.
+  const hidesLastCenterLine =
+    props.tableLayout?.columnsPinnable &&
+    edgeColumn.getIsLastColumn("center") &&
+    hasDataGridTableRightPinnedColumns(table)
   const isResizeModeOnEnd =
-    (props.tableLayout?.columnsResizeMode ?? table.options.columnResizeMode) ===
-    "onEnd"
+    getDataGridColumnResizeMode(
+      props.tableLayout?.columnsResizeMode,
+      table.options.columnResizeMode
+    ) === "onEnd"
+  const stopResizeSessionRef = useRef<(() => void) | undefined>(undefined)
+
+  // End a live drag if the handle unmounts mid-resize so document listeners
+  // and the app-wide col-resize cursor don't outlive the grid.
+  useEffect(() => {
+    return () => {
+      stopResizeSessionRef.current?.()
+      stopResizeSessionRef.current = undefined
+    }
+  }, [])
+
+  const handleMouseDown = (event: ReactMouseEvent<HTMLElement>) => {
+    // Only the primary button starts a resize; guard before preventDefault so
+    // right-click still opens the context menu.
+    if (event.button !== 0) return
 
-  const handleMouseDown = (event: ReactMouseEvent<HTMLDivElement>) => {
     event.preventDefault()
     event.stopPropagation()
 
-    if (isResizeModeOnEnd) {
-      startDataGridColumnResizeOnEnd(event, header, table)
-      return
-    }
-
-    header.getResizeHandler()(event)
+    stopResizeSessionRef.current?.()
+    stopResizeSessionRef.current = startDataGridColumnResizeOnEnd(
+      event,
+      header,
+      table,
+      !isResizeModeOnEnd,
+      autoSize
+    )
   }
 
-  const handleTouchStart = (event: ReactTouchEvent<HTMLDivElement>) => {
+  const handleTouchStart = (event: ReactTouchEvent<HTMLElement>) => {
     event.preventDefault()
     event.stopPropagation()
 
-    if (isResizeModeOnEnd) {
-      startDataGridColumnResizeOnEnd(event, header, table)
-      return
-    }
-
-    header.getResizeHandler()(event)
+    stopResizeSessionRef.current?.()
+    stopResizeSessionRef.current = startDataGridColumnResizeOnEnd(
+      event,
+      header,
+      table,
+      !isResizeModeOnEnd,
+      autoSize
+    )
   }
 
   return (
-    <div
+    // A span, deliberately: consumers stretch end-aligned header CONTENT
+    // with `[&>div]:w-full` on headerClassName, and that compiled child
+    // selector (0,1,1) beats the handle's own w-5 (0,1,0) - a div handle
+    // then covers the whole cell and swallows the menu click. Hardening
+    // w-5 with ! was rejected: the tag change removes the fight instead
+    // of escalating it.
+    <span
+      data-slot="data-grid-table-resize-handle"
       {...{
         onDoubleClick: () => column.resetSize(),
         onMouseDown: handleMouseDown,
         onTouchStart: handleTouchStart,
         className: cn(
-          "absolute top-0 h-full cursor-col-resize user-select-none touch-none z-10 flex",
-          isLastVisibleColumn
-            ? "end-0 w-5 justify-end before:hidden"
-            : isPinned
+          "absolute top-0 h-full cursor-col-resize touch-none select-none z-10 flex",
+          isPinned === "end"
+            ? cn(
+                // An end-pinned column grows from its START edge (its end is
+                // anchored), so the handle lives there, inside the sticky
+                // cell.
+                "start-0 w-5 justify-start",
+                props.tableLayout?.columnsPinnable
+                  ? "before:hidden"
+                  : "before:absolute before:inset-y-0 before:start-0 before:w-px before:bg-border"
+              )
+            : isLastVisibleColumn
               ? "end-0 w-5 justify-end before:hidden"
-              : "-end-2 w-5 justify-center before:absolute before:inset-y-0 before:w-px before:-translate-x-px before:bg-border",
+              : isPinned
+                ? cn(
+                    // A pinned column is sticky, so the handle sits inside the
+                    // cell instead of straddling the boundary, where the next
+                    // sticky cell would paint over it.
+                    "end-0 w-5 justify-end",
+                    // With the pin affordance on, the pinned edge already draws
+                    // its own separator and a resize line would double it. But
+                    // pinning is also usable purely as an ordering lock, with no
+                    // affordance and no separator -- and there this line is the
+                    // only thing marking the edge, so hiding it left a resizable
+                    // column showing a resize cursor and no indicator at all.
+                    props.tableLayout?.columnsPinnable
+                      ? "before:hidden"
+                      : "before:absolute before:inset-y-0 before:end-0 before:w-px before:bg-border"
+                  )
+                : cn(
+                    "-end-2 w-5 justify-center",
+                    // With cell borders on, the th border-e already marks every
+                    // boundary and this always-on line would double it; the wide
+                    // hit area and resize cursor stay. end-2 cancels the
+                    // handle's -end-2 overhang, so the line paints on the
+                    // cell's last pixel column, where a th border-e paints.
+                    props.tableLayout?.cellBorder || hidesLastCenterLine
+                      ? "before:hidden"
+                      : "before:absolute before:inset-y-0 before:end-2 before:w-px before:bg-border"
+                  ),
           column.getIsResizing() &&
             (isResizeModeOnEnd
               ? "opacity-100"
-              : isLastVisibleColumn
+              : isLastVisibleColumn && isPinned !== "end"
                 ? "before:absolute before:end-0 before:block before:inset-y-0 before:w-0.5 before:bg-primary opacity-100"
-                : "before:block before:bg-primary before:w-0.5 opacity-100")
+                : isPinned
+                  ? "before:block before:bg-primary before:w-0.5 opacity-100"
+                  : cn(
+                      // Positioned explicitly: under cellBorder the resting
+                      // line is hidden and unpositioned.
+                      "before:absolute before:inset-y-0 before:block before:w-0.5 before:bg-primary opacity-100",
+                      // A th border-e ends the padding box 1px inside the
+                      // cell edge, so the line moves out by that pixel.
+                      props.tableLayout?.cellBorder && !hidesLastCenterLine
+                        ? "before:end-[calc(--spacing(2)-1px)]"
+                        : "before:end-2"
+                    ))
         ),
       }}
     />
@@ -824,60 +1727,136 @@ function DataGridTableHeadRowCellResize<TData>({
 }
 
 function DataGridTableResizeIndicator({
-  viewportElement,
+  viewportNodeRef,
 }: {
-  viewportElement: HTMLDivElement | null
+  viewportNodeRef: RefObject<HTMLDivElement | null>
 }) {
   const { props, table } = useDataGrid()
-  const columnSizingInfo = table.getState().columnSizingInfo
-  const resizingColumnId = columnSizingInfo.isResizingColumn
-  const resizeMode =
-    props.tableLayout?.columnsResizeMode ?? table.options.columnResizeMode
+  const indicatorRef = useRef<HTMLDivElement | null>(null)
+  const indicatorHeadRef = useRef<HTMLDivElement | null>(null)
+  // Header height is stable for the duration of a drag; caching it per
+  // session avoids a forced layout (querySelector + getBoundingClientRect)
+  // on every mousemove.
+  const headerHeightCacheRef = useRef<{
+    key: string | false
+    value: number
+  }>({ key: false, value: 0 })
+  const columnResizing =
+    useDataGridAtom(table.atoms.columnResizing) ?? table.state.columnResizing
+  // Absent with a bundle that leaves out columnResizingFeature.
+  const resizingColumnId = columnResizing?.isResizingColumn
+  const resizeMode = getDataGridColumnResizeMode(
+    props.tableLayout?.columnsResizeMode,
+    table.options.columnResizeMode
+  )
+  const isActive = !!(
+    props.tableLayout?.columnsResizable &&
+    resizeMode === "onEnd" &&
+    resizingColumnId
+  )
 
-  if (
-    !props.tableLayout?.columnsResizable ||
-    resizeMode !== "onEnd" ||
-    !resizingColumnId
-  ) {
-    return null
-  }
+  // Positioning happens imperatively after each drag-frame render: layout
+  // reads (viewport rect, thead height) and ref access belong outside render,
+  // and writing styles directly avoids holding the viewport node in React
+  // state, which would cost every grid a second render pass at mount.
+  useLayoutEffect(() => {
+    const indicator = indicatorRef.current
+    const indicatorHead = indicatorHeadRef.current
+    const viewportElement = viewportNodeRef.current
 
-  const resizingHeader = table
-    .getFlatHeaders()
-    .find(
-      (header) =>
-        header.column.id === resizingColumnId || header.id === resizingColumnId
+    if (!isActive || !indicator || !indicatorHead || !resizingColumnId) return
+
+    const resizingHeader = table
+      .getFlatHeaders()
+      .find(
+        (header) =>
+          header.column.id === resizingColumnId ||
+          header.id === resizingColumnId
+      )
+
+    if (!resizingHeader) return
+
+    // deltaOffset is a logical delta (already direction-adjusted); translate
+    // by the physical pointer movement so the indicator follows the cursor
+    // instead of mirroring it. End-pinned columns resize mirrored (see the
+    // session), so the multiplier matches theirs.
+    const directionMultiplier =
+      (table.options.columnResizeDirection === "rtl") !==
+      (resizingHeader.column.getIsPinned() === "end")
+        ? -1
+        : 1
+    const deltaOffset = (columnResizing?.deltaOffset ?? 0) * directionMultiplier
+
+    const viewportRoot =
+      viewportElement ??
+      indicator.closest<HTMLElement>('[data-slot="data-grid-table-viewport"]')
+
+    // A 0 is never cached: it means the thead was not measurable yet, and
+    // caching it pinned the head at its 6px floor for the whole drag.
+    if (
+      headerHeightCacheRef.current.key !== resizingColumnId ||
+      headerHeightCacheRef.current.value <= 0
+    ) {
+      headerHeightCacheRef.current = {
+        key: resizingColumnId,
+        value:
+          viewportRoot
+            ?.querySelector('[data-slot="data-grid-table"] thead')
+            ?.getBoundingClientRect().height ?? 0,
+      }
+    }
+
+    const headerHeight = headerHeightCacheRef.current.value
+    // Anchor on the live header cell: content math (getStart) cannot place a
+    // STICKY pinned column, while the DOM rect is right for every column at
+    // any scroll position. The state offset and content math stay as
+    // fallbacks for a header that is not in the DOM.
+    // A covered leaf has no th of its own; its span's th ends on its edge.
+    const spanOwnerId = [...getDataGridHeaderSpans(table)].find(([, covered]) =>
+      covered.some((leaf) => leaf.id === resizingHeader.column.id)
+    )?.[0]
+    const headerCellElement = viewportRoot?.querySelector<HTMLElement>(
+      `thead th[data-col-id="${CSS.escape(spanOwnerId ?? resizingHeader.column.id)}"]`
     )
-
-  if (!resizingHeader) return null
-
-  const deltaOffset = columnSizingInfo.deltaOffset ?? 0
-  const headerHeight =
-    viewportElement
-      ?.querySelector('[data-slot="data-grid-table"] thead')
-      ?.getBoundingClientRect().height ?? 0
-  const indicatorLeft =
-    typeof columnSizingInfo.startOffset === "number" && viewportElement
-      ? columnSizingInfo.startOffset -
+    let indicatorLeft: number
+    if (headerCellElement && viewportRoot) {
+      const anchorRect = headerCellElement.getBoundingClientRect()
+      const edgeClientX =
+        (table.options.columnResizeDirection === "rtl") !==
+        (resizingHeader.column.getIsPinned() === "end")
+          ? anchorRect.left
+          : anchorRect.right
+      indicatorLeft = edgeClientX - viewportRoot.getBoundingClientRect().left
+    } else if (
+      typeof columnResizing?.startOffset === "number" &&
+      viewportElement
+    ) {
+      indicatorLeft =
+        columnResizing.startOffset -
         viewportElement.getBoundingClientRect().left
-      : resizingHeader.getStart() + resizingHeader.getSize()
+    } else {
+      indicatorLeft = resizingHeader.getStart() + resizingHeader.getSize()
+    }
+
+    indicator.style.left = `${indicatorLeft}px`
+    indicator.style.transform = `translateX(${deltaOffset}px)`
+    indicatorHead.style.height = `${Math.max(headerHeight, 6)}px`
+  })
+
+  if (!isActive) return null
 
   return (
     <div
+      ref={indicatorRef}
       aria-hidden="true"
-      className="pointer-events-none absolute inset-y-0 z-20"
-      style={{
-        left: indicatorLeft,
-        transform: `translateX(${deltaOffset}px)`,
-      }}
+      data-slot="data-grid-table-resize-indicator"
+      className="pointer-events-none absolute inset-y-0 z-50"
     >
       <div className="bg-primary/85 absolute inset-y-0 left-0 w-px -translate-x-1/2" />
       <div
+        ref={indicatorHeadRef}
         className="bg-primary rounded-b-sm absolute top-0 left-0 -translate-x-1/2 shadow-xs"
-        style={{
-          width: 5,
-          height: Math.max(headerHeight, 6),
-        }}
+        style={{ width: 5 }}
       />
     </div>
   )
@@ -917,7 +1896,13 @@ function DataGridTableFoot({ children }: { children: ReactNode }) {
   return (
     <tfoot
       data-slot="data-grid-table-foot"
-      className={cn(props.tableClassNames?.footer)}
+      className={cn(
+        // The rule between the body and the footer. It used to be drawn by the
+        // last body row through an ancestor :has(), which made every style
+        // invalidation re-match the whole grid.
+        props.tableLayout?.rowBorder && "[&>tr:first-child>td]:border-t",
+        props.tableClassNames?.footer
+      )}
     >
       {children}
     </tfoot>
@@ -925,16 +1910,26 @@ function DataGridTableFoot({ children }: { children: ReactNode }) {
 }
 
 function DataGridTableFootRow({ children }: { children: ReactNode }) {
-  const { props } = useDataGrid()
+  const { props, table } = useDataGrid()
   const footRowBottomBorderClasses = "[&:not(:last-child)>td]:border-b"
 
   return (
     <tr
       data-slot="data-grid-table-foot-row"
       className={cn(
-        props.tableLayout?.footerBackground && "bg-muted/40 dark:bg-background",
+        props.tableLayout?.footerBackground &&
+          "bg-muted/40 dark:bg-[color:var(--data-grid-surface,var(--data-grid-card-surface,var(--background)))]",
         props.tableLayout?.rowBorder && footRowBottomBorderClasses,
-        props.tableLayout?.cellBorder && "*:last:border-e-0"
+        props.tableLayout?.cellBorder && "*:last:border-e-0",
+        // The fill foot cell is the :last child, so the rule above only
+        // strips the filler; the real last cell needs the same treatment or
+        // its border floats into the strip while thead and tbody suppress
+        // theirs. Same pin-affordance gate as the cell-level suppressors.
+        props.tableLayout?.cellBorder &&
+          props.tableLayout?.columnsResizable &&
+          (props.tableLayout?.columnsPinnable ||
+            !hasDataGridTableRightPinnedColumns(table)) &&
+          "[&>td:has(+td[data-slot=data-grid-table-fill-foot-cell])]:border-e-0"
       )}
     >
       {children}
@@ -962,7 +1957,8 @@ function DataGridTableFootRowCell({
       className={cn(
         "text-secondary-foreground/80 align-middle font-medium",
         spacing,
-        props.tableLayout?.footerBackground && "bg-muted/40 dark:bg-background",
+        props.tableLayout?.footerBackground &&
+          "bg-muted/40 dark:bg-[color:var(--data-grid-surface,var(--data-grid-card-surface,var(--background)))]",
         props.tableLayout?.cellBorder && "border-e",
         className
       )}
@@ -986,7 +1982,6 @@ function DataGridTableBodyRowSkeleton({ children }: { children: ReactNode }) {
         props.tableLayout?.cellBorder && "*:last:border-e-0",
         props.tableLayout?.stripped &&
           "odd:bg-muted/90 odd:hover:bg-muted hover:bg-transparent",
-        table.options.enableRowSelection && "*:first:relative",
         props.tableClassNames?.bodyRow
       )}
     >
@@ -995,40 +1990,58 @@ function DataGridTableBodyRowSkeleton({ children }: { children: ReactNode }) {
   )
 }
 
-function DataGridTableBodyRowSkeletonCell<TData>({
+function DataGridTableBodyRowSkeletonCell<TData extends object>({
   children,
   column,
 }: {
   children: ReactNode
-  column: Column<TData>
+  column: Column<DataGridFeatures, TData, unknown>
 }) {
   const { props, table } = useDataGrid()
+  const isPinned = column.getIsPinned()
+  const isLastStartPinned =
+    isPinned === "start" && column.getIsLastColumn("start")
+  const isFirstEndPinned = isPinned === "end" && column.getIsFirstColumn("end")
+  const edges = getDataGridTableColumnEdges(table, column.id)
   const bodyCellSpacing = bodyCellSpacingVariants({
     size: props.tableLayout?.dense ? "dense" : "default",
   })
 
   return (
     <td
-      style={
-        props.tableLayout?.columnsResizable
-          ? { width: `calc(var(--col-${column.id}-size) * 1px)` }
-          : undefined
+      style={{
+        ...(props.tableLayout?.columnsPinnable &&
+          column.getCanPin() &&
+          getPinningStyles(column)),
+        ...(props.tableLayout?.columnsResizable && {
+          width: `calc(var(--col-${column.id}-size) * 1px)`,
+        }),
+      }}
+      data-pinned={isPinned || undefined}
+      data-last-col={
+        isLastStartPinned ? "start" : isFirstEndPinned ? "end" : undefined
       }
       className={cn(
         "align-middle",
         bodyCellSpacing,
         props.tableLayout?.cellBorder && "border-e",
+        props.tableLayout?.cellBorder &&
+          props.tableLayout?.columnsResizable &&
+          // With end-pinned columns but no pin affordance, the pinned edge
+          // draws no separator of its own; keep the border then.
+          (props.tableLayout?.columnsPinnable ||
+            !hasDataGridTableRightPinnedColumns(table)) &&
+          !column.getIsPinned() &&
+          column.getIsLastColumn("center") &&
+          "border-e-0",
         props.tableLayout?.columnsResizable &&
           column.getCanResize() &&
           "truncate",
         column.columnDef.meta?.cellClassName,
         props.tableLayout?.columnsPinnable &&
           column.getCanPin() &&
-          "data-pinned:bg-background data-pinned:isolate [&[data-pinned=left][data-last-col=left]]:shadow-[inset_-1px_0_0_0_var(--border)] [&[data-pinned=right][data-last-col=right]]:shadow-[inset_1px_0_0_0_var(--border)]",
-        column.getIndex() === 0 ||
-          column.getIndex() === table.getVisibleFlatColumns().length - 1
-          ? props.tableClassNames?.edgeCell
-          : ""
+          "data-pinned:isolate data-pinned:bg-[color:var(--data-grid-surface,var(--data-grid-card-surface,var(--background)))] [&[data-pinned=end][data-last-col=end]]:shadow-[inset_calc(1px*var(--data-grid-dir,1))_0_0_0_var(--border)] [&[data-pinned=start][data-last-col=start]]:shadow-[inset_calc(-1px*var(--data-grid-dir,1))_0_0_0_var(--border)]",
+        edges.isFirst || edges.isLast ? props.tableClassNames?.edgeCell : ""
       )}
     >
       {children}
@@ -1036,26 +2049,31 @@ function DataGridTableBodyRowSkeletonCell<TData>({
   )
 }
 
-function DataGridTableBodyRow<TData>({
+function DataGridTableBodyRow<TData extends object>({
   children,
   row,
   pinnedBoundary,
   rowRef,
   dndRef,
   dndStyle,
+  dndDragging,
+  dataIndex,
 }: {
   children: ReactNode
-  row: Row<TData>
+  row: Row<DataGridFeatures, TData>
   pinnedBoundary?: DataGridTablePinnedBoundary
   rowRef?: React.Ref<HTMLTableRowElement>
   dndRef?: React.Ref<HTMLTableRowElement>
   dndStyle?: CSSProperties
+  dndDragging?: boolean
+  dataIndex?: number
 }) {
-  const { props, table } = useDataGrid()
+  const context = useDataGrid()
+  const { props, table } = context
   const isRowPinned = row.getIsPinned()
+  const rowStatus = props.getRowStatus?.(row.original)
 
-  const bodyRowBottomBorderClasses =
-    "[&:not(:last-child)>td]:border-b [tbody:has(+tfoot)_&:last-child>td]:border-b [*:has(>[data-slot=data-grid]+[data-slot=data-grid-pagination])_[data-slot=data-grid]_&:last-child>td]:border-b"
+  const bodyRowBottomBorderClasses = "[&:not(:last-child)>td]:border-b"
 
   return (
     <tr
@@ -1069,26 +2087,77 @@ function DataGridTableBodyRow<TData>({
           ? "selected"
           : undefined
       }
+      data-index={dataIndex}
+      data-row-id={row.id}
+      data-depth={row.depth || undefined}
       data-row-pinned={isRowPinned || undefined}
       data-row-pinned-boundary={pinnedBoundary}
-      onClick={() => props.onRowClick && props.onRowClick(row.original)}
+      data-row-status={rowStatus}
+      // Style the dragged row's slot through this, never its inline style: a
+      // rule matching td under an inline `cursor: grabbing` makes every inline
+      // style write (the scroll area rewrites its own each scroll) restyle all
+      // the cells below it, measured at 24 fps instead of 120 on 1,000 rows.
+      data-dragging={dndDragging || undefined}
+      // 1-based after the header row; row.index is the position in the data,
+      // so the announced index stays absolute across pagination.
+      aria-rowindex={
+        props.tableLayout?.cellSelection ? row.index + 2 : undefined
+      }
+      onClick={(event) => {
+        if (isDataGridPortalEvent(event)) return
+        // Through the getter, as in DataGridTableAddRow.
+        context.props.onRowClick?.(row.original)
+      }}
       className={cn(
         "hover:bg-muted/40 data-[state=selected]:bg-muted/50",
+        /* With the pin affordance on, pinned cells hide scrolled content
+           behind an OPAQUE background, which also hides the row's translucent
+           hover and selected tints; they get the same tints premixed over the
+           background instead, the row-status treatment. Pinning used only as
+           an ordering lock leaves cells transparent, so the premix would paint
+           a second, different hover colour: gate it on the same flag. */
+        props.tableLayout?.columnsPinnable &&
+          "hover:[&>td[data-pinned]]:bg-[color-mix(in_oklab,var(--muted)_40%,var(--data-grid-surface,var(--data-grid-card-surface,var(--background))))] data-[state=selected]:[&>td[data-pinned]]:bg-[color-mix(in_oklab,var(--muted)_50%,var(--data-grid-surface,var(--data-grid-card-surface,var(--background))))]",
         props.onRowClick && "cursor-pointer",
+        // Optional CRUD indications, active only when getRowStatus is
+        // wired; the warning-muted defaults yield to tableClassNames
+        // overrides per status. Pinned cells must stay OPAQUE (they hide
+        // scrolled content), so they get the same tint pre-mixed over the
+        // background instead of inheriting the translucent row fill.
+        props.getRowStatus &&
+          "data-[row-status=deleted]:bg-destructive/5 data-[row-status=deleted]:opacity-60 data-[row-status=dirty]:bg-amber-500/5 data-[row-status=new]:bg-green-500/5 data-[row-status=deleted]:[&_td]:line-through",
+        props.getRowStatus &&
+          props.tableLayout?.columnsPinnable &&
+          "data-[row-status=deleted]:[&>td[data-pinned]]:bg-[color-mix(in_oklab,var(--destructive)_5%,var(--data-grid-surface,var(--data-grid-card-surface,var(--background))))] data-[row-status=dirty]:[&>td[data-pinned]]:bg-[color-mix(in_oklab,var(--color-amber-500)_5%,var(--data-grid-surface,var(--data-grid-card-surface,var(--background))))] data-[row-status=new]:[&>td[data-pinned]]:bg-[color-mix(in_oklab,var(--color-green-500)_5%,var(--data-grid-surface,var(--data-grid-card-surface,var(--background))))]",
+        rowStatus === "new" && props.tableClassNames?.rowNew,
+        rowStatus === "dirty" && props.tableClassNames?.rowDirty,
+        rowStatus === "deleted" && props.tableClassNames?.rowDeleted,
         !props.tableLayout?.stripped &&
           props.tableLayout?.rowBorder &&
           bodyRowBottomBorderClasses,
         props.tableLayout?.cellBorder &&
           `*:last:border-e-0 ${bodyRowBottomBorderClasses}`,
+        // Virtualized rows stripe by absolute row index (CSS :nth-child
+        // parity flips as spacer rows resize while scrolling).
         props.tableLayout?.stripped &&
-          "odd:bg-muted/90 odd:hover:bg-muted hover:bg-transparent",
-        table.options.enableRowSelection && "*:first:relative",
+          (typeof dataIndex === "number"
+            ? cn(
+                "hover:bg-transparent",
+                dataIndex % 2 === 0 && "bg-muted/90 hover:bg-muted"
+              )
+            : "odd:bg-muted/90 odd:hover:bg-muted hover:bg-transparent"),
         props.tableLayout?.rowsPinnable &&
           isRowPinned &&
           "bg-muted/30 hover:bg-muted/50",
-        pinnedBoundary === "top" && "[&>td]:shadow-[0_2px_0_rgba(0,0,0,0.03)]",
+        pinnedBoundary === "top" &&
+          "[&>td]:shadow-[0_2px_0_rgba(0,0,0,0.03)] dark:[&>td]:shadow-[0_2px_0_rgba(255,255,255,0.06)]",
+        // A bottom-pinned row borders scrolled content along its TOP edge,
+        // so its separator shadow casts upward.
         pinnedBoundary === "bottom" &&
-          "[&>td]:shadow-[0_2px_0_rgba(0,0,0,0.03)]",
+          "[&>td]:shadow-[0_-2px_0_rgba(0,0,0,0.03)] dark:[&>td]:shadow-[0_-2px_0_rgba(255,255,255,0.06)]",
+        props.tableLayout?.rowsPinnable &&
+          isRowPinned &&
+          props.tableClassNames?.rowPinned,
         props.tableClassNames?.bodyRow
       )}
     >
@@ -1097,10 +2166,23 @@ function DataGridTableBodyRow<TData>({
   )
 }
 
-function DataGridTableBodyRowExpandded<TData>({ row }: { row: Row<TData> }) {
+function DataGridTableBodyRowExpandded<TData extends object>({
+  row,
+}: {
+  row: Row<DataGridFeatures, TData>
+}) {
   const { props, table } = useDataGrid()
-  const bodyRowBottomBorderClasses =
-    "[&:not(:last-child)>td]:border-b [tbody:has(+tfoot)_&:last-child>td]:border-b [*:has(>[data-slot=data-grid]+[data-slot=data-grid-pagination])_[data-slot=data-grid]_&:last-child>td]:border-b"
+  const expandedContent = table
+    .getAllColumns()
+    .find((column) => column.columnDef.meta?.expandedContent)?.columnDef
+    .meta?.expandedContent
+
+  // Tree and grouped rows share row.getIsExpanded() with detail expansion.
+  // Without a detail column there is nothing to render, and an empty <tr>
+  // would break striping parity, rowBorder, and virtual row measurement.
+  if (!expandedContent) return null
+
+  const bodyRowBottomBorderClasses = "[&:not(:last-child)>td]:border-b"
 
   return (
     <tr
@@ -1112,44 +2194,83 @@ function DataGridTableBodyRowExpandded<TData>({ row }: { row: Row<TData> }) {
           (props.tableLayout?.columnsResizable ? 1 : 0)
         }
       >
-        {table
-          .getAllColumns()
-          .find((column) => column.columnDef.meta?.expandedContent)
-          ?.columnDef.meta?.expandedContent?.(row.original)}
+        {expandedContent(row.original)}
       </td>
     </tr>
   )
 }
 
-function DataGridTableBodyRowCell<TData>({
+/**
+ * Interactive descendants keep their own mousedown semantics: a click on a
+ * button, link, editor or checkbox inside a cell must never start or replace
+ * a range. One selector also covers the row-dnd grip (a button), the expand
+ * toggle, and `data-cell-interactive` - the documented opt-out for custom
+ * widgets built from elements the tag list cannot know about.
+ */
+function isDataGridCellInteractiveTarget(target: EventTarget | null): boolean {
+  return (
+    target instanceof Element &&
+    target.closest(
+      'button, a, input, select, textarea, [contenteditable], [role="checkbox"], [data-cell-interactive], [data-slot="data-grid-table-row-expand"], [data-slot="data-grid-cell-fill-handle"]'
+    ) != null
+  )
+}
+
+function DataGridTableBodyRowCell<TData extends object>({
   children,
   cell,
   dndRef,
   dndStyle,
+  columnIndex,
 }: {
   children: ReactNode
-  cell: Cell<TData, unknown>
+  cell: Cell<DataGridFeatures, TData, unknown>
   dndRef?: React.Ref<HTMLTableCellElement>
   dndStyle?: CSSProperties
+  /** Center-column index under column virtualization; data-column-index. */
+  columnIndex?: number
 }) {
-  const { props } = useDataGrid()
+  const { props, table, gridId } = useDataGrid()
 
   const { column, row } = cell
   const isPinned = column.getIsPinned()
-  const isLastLeftPinned = isPinned === "left" && column.getIsLastColumn("left")
-  const isFirstRightPinned =
-    isPinned === "right" && column.getIsFirstColumn("right")
+  const isLastStartPinned =
+    isPinned === "start" && column.getIsLastColumn("start")
+  const isFirstEndPinned = isPinned === "end" && column.getIsFirstColumn("end")
+  const edges = getDataGridTableColumnEdges(table, column.id)
   const bodyCellSpacing = bodyCellSpacingVariants({
     size: props.tableLayout?.dense ? "dense" : "default",
   })
 
-  return (
+  // The atom check backs up the flag: consumers may hand the grid a leaner
+  // bundle without cellSelectionFeature, and the flag alone must not make the
+  // renderer call prototype APIs that were never assigned.
+  const cellSelectionOn =
+    !!props.tableLayout?.cellSelection && table.atoms.cellSelection != null
+  const rangeSelectionOn =
+    cellSelectionOn && props.tableLayout?.cellSelectionMode !== "single"
+
+  const renderTd = (
+    selection: ReturnType<typeof getDataGridCellSelectionCellAttrs> | null
+  ) => (
     <td
       ref={dndRef}
+      // The id is what the controller's aria-activedescendant points at, so
+      // a screen reader tracks the focused cell through the container-focus
+      // model.
+      id={
+        cellSelectionOn
+          ? `${gridId}c-${toDataGridDomId(row.id)}-${toDataGridDomId(column.id)}`
+          : undefined
+      }
+      aria-colindex={cellSelectionOn ? column.getIndex() + 1 : undefined}
       style={{
         ...(props.tableLayout?.columnsPinnable &&
           column.getCanPin() &&
           getPinningStyles(column)),
+        // Paint containment clips at the padding edge, which would erase
+        // the ::before selection chrome on pinned cells.
+        ...(cellSelectionOn ? { contain: undefined } : null),
         ...(props.tableLayout?.columnsResizable && {
           width: `calc(var(--col-${column.id}-size) * 1px)`,
         }),
@@ -1157,48 +2278,194 @@ function DataGridTableBodyRowCell<TData>({
       }}
       data-pinned={isPinned || undefined}
       data-last-col={
-        isLastLeftPinned ? "left" : isFirstRightPinned ? "right" : undefined
+        isLastStartPinned ? "start" : isFirstEndPinned ? "end" : undefined
+      }
+      data-cell-status={props.getCellStatus?.(row.original, column.id)}
+      data-column-index={columnIndex}
+      {...(selection ? selection : null)}
+      onMouseDown={
+        selection
+          ? (event) => {
+              if (event.button !== 0 || isDataGridPortalEvent(event)) return
+              if (isDataGridCellInteractiveTarget(event.target)) {
+                // A modifier click is a SELECTION gesture even on a control:
+                // Shift extends and Ctrl/Cmd adds, exactly as on a plain
+                // cell, so no column is unreachable for ranges.
+                if (
+                  rangeSelectionOn &&
+                  (event.shiftKey || event.metaKey || event.ctrlKey) &&
+                  cell.getCanSelect()
+                ) {
+                  event.preventDefault()
+                  cell.getSelectionStartHandler()(event)
+                  return
+                }
+                // The press starts the range session exactly like a plain
+                // cell: the cell focuses, a drag extends from it, and a
+                // motionless press still ends in the control's own click
+                // (this is why drag releases are squelched upstream, in the
+                // controller, once a drag actually grew the range).
+                if (cell.getCanSelect()) {
+                  if (rangeSelectionOn) {
+                    cell.getSelectionStartHandler()(event)
+                  } else {
+                    table.setFocusedCell(row.id, column.id)
+                  }
+                }
+                return
+              }
+              if (!rangeSelectionOn) {
+                // Single mode: every gesture collapses to the one cell.
+                if (cell.getCanSelect()) {
+                  table.setFocusedCell(row.id, column.id)
+                }
+                return
+              }
+              cell.getSelectionStartHandler()(event)
+            }
+          : undefined
+      }
+      onMouseEnter={
+        rangeSelectionOn
+          ? (event) => {
+              if (isDataGridPortalEvent(event)) return
+              cell.getSelectionExtendHandler()(event)
+            }
+          : undefined
       }
       className={cn(
         "align-middle",
         bodyCellSpacing,
+        // The classic edited-cell corner mark, active only when
+        // getCellStatus is wired: amber for "dirty", destructive for
+        // "invalid".
+        props.getCellStatus &&
+          "data-[cell-status=invalid]:after:border-t-destructive data-[cell-status]:relative data-[cell-status]:after:absolute data-[cell-status]:after:end-0 data-[cell-status]:after:top-0 data-[cell-status]:after:size-0 data-[cell-status]:after:border-s-[5px] data-[cell-status]:after:border-t-[5px] data-[cell-status]:after:border-s-transparent data-[cell-status]:after:content-[''] data-[cell-status=dirty]:after:border-t-amber-500",
         props.tableLayout?.cellBorder && "border-e",
+        // Mirror of the head cell rule: no floating border against the
+        // resize filler strip.
+        props.tableLayout?.cellBorder &&
+          props.tableLayout?.columnsResizable &&
+          // With end-pinned columns but no pin affordance, the pinned edge
+          // draws no separator of its own; keep the border then.
+          (props.tableLayout?.columnsPinnable ||
+            !hasDataGridTableRightPinnedColumns(table)) &&
+          !isPinned &&
+          column.getIsLastColumn("center") &&
+          "border-e-0",
         props.tableLayout?.columnsResizable &&
           column.getCanResize() &&
+          !cellSelectionOn &&
           "truncate",
         cell.column.columnDef.meta?.cellClassName,
         props.tableLayout?.columnsPinnable &&
           column.getCanPin() &&
           cn(
-            "data-pinned:bg-background data-pinned:isolate",
-            "[&[data-pinned=left][data-last-col=left]]:shadow-[inset_-1px_0_0_0_var(--border)]",
-            "[&[data-pinned=right][data-last-col=right]]:shadow-[inset_1px_0_0_0_var(--border)]"
+            "data-pinned:isolate data-pinned:bg-[color:var(--data-grid-surface,var(--data-grid-card-surface,var(--background)))]",
+            "[&[data-pinned=start][data-last-col=start]]:shadow-[inset_calc(-1px*var(--data-grid-dir,1))_0_0_0_var(--border)]",
+            "[&[data-pinned=end][data-last-col=end]]:shadow-[inset_calc(1px*var(--data-grid-dir,1))_0_0_0_var(--border)]"
           ),
-        column.getIndex() === 0 ||
-          column.getIndex() === row.getVisibleCells().length - 1
-          ? props.tableClassNames?.edgeCell
-          : ""
+        edges.isFirst || edges.isLast ? props.tableClassNames?.edgeCell : "",
+        selection && dataGridCellSelectionCellClasses
       )}
     >
-      {children}
+      {/* With cell selection on, the td must not clip (its ::before paints
+          the selection chrome 1px outside the cell), so the resize
+          truncation moves to an inner wrapper that clips at the same
+          boundary the td used to. */}
+      {cellSelectionOn &&
+      props.tableLayout?.columnsResizable &&
+      column.getCanResize() ? (
+        <div
+          className={bodyCellTruncateWrapVariants({
+            size: props.tableLayout?.dense ? "dense" : "default",
+          })}
+        >
+          {children}
+        </div>
+      ) : (
+        children
+      )}
+      {props.tableLayout?.cellFillHandle &&
+        selection?.["data-cell-edge-bottom"] &&
+        selection["data-cell-edge-right"] && (
+          <span
+            data-slot="data-grid-cell-fill-handle"
+            /* "dot" stays fully inside the cell corner; "ring" rides the
+               corner point the way Sheets draws it. Either way the handle
+               clamps where straddling would break: at the grid's own
+               boundary (last row, last cell, a last cell followed only by
+               the filler strip), where an overhang would extend the scroll
+               content and clip the selection chrome, and beside a PINNED
+               column, whose sticky layer (z 30) would otherwise paint over
+               the straddling half - raising the handle instead would float
+               it above the pinned column during horizontal scroll. */
+            className={cn(
+              "absolute z-10 cursor-crosshair in-data-[cell-editing]:hidden in-data-[cell-selecting]:hidden",
+              props.tableLayout?.cellFillHandleVariant === "ring"
+                ? "border-primary bg-background -end-[5px] -bottom-[5px] size-[11px] rounded-full border-2 in-[td:has(+[data-slot=data-grid-table-fill-body-cell]+td[data-pinned])]:end-0 in-[td:has(+[data-slot=data-grid-table-fill-body-cell]:last-child)]:end-0 in-[td:has(+td[data-pinned])]:end-0 in-[td:last-child]:end-0 in-[tr:last-child]:bottom-0"
+                : props.tableLayout?.cellFillHandleVariant === "square"
+                  ? /* Abutting the cell borders from inside: no gap and no
+                       overlap, so the square cannot merge with a gridline
+                       into a wider-than-tall blob, and it can never leave
+                       the grid, which is why it needs no boundary clamps. */
+                    "bg-primary end-0 bottom-0 size-[5px]"
+                  : "bg-primary border-background end-0 bottom-0 size-[9px] rounded-full border",
+              props.tableClassNames?.cellFillHandle
+            )}
+          />
+        )}
     </td>
   )
+
+  if (!cellSelectionOn) return renderTd(null)
+
+  // Per-cell subscription with a projecting selector: the atom writes once
+  // per cell crossed during a drag, and shallow-comparing this tuple limits
+  // the re-render to cells whose selection state actually changed.
+  return (
+    <Subscribe
+      source={table.atoms.cellSelection}
+      selector={() => getDataGridCellSelectionCellAttrs(cell)}
+    >
+      {(selection) => renderTd(selection)}
+    </Subscribe>
+  )
 }
 
-function DataGridTableRenderedRow<TData>({
+function DataGridTableRenderedRow<TData extends object>({
   row,
   pinnedBoundary,
   rowRef,
+  rowIndex,
+  centerWindow,
 }: {
-  row: Row<TData>
+  row: Row<DataGridFeatures, TData>
   pinnedBoundary?: DataGridTablePinnedBoundary
   rowRef?: React.Ref<HTMLTableRowElement>
+  /** Virtualized list index, rendered as data-index for measureElement. */
+  rowIndex?: number
+  /**
+   * Column-virtualization window over the CENTER cells: only the inclusive
+   * [start, end] slice renders, and each flank collapses into one colSpan
+   * spacer. The spacers carry no width of their own - the colgroup stays
+   * complete, so under table-fixed the browser sizes them from the col
+   * elements they span and the layout cannot drift.
+   */
+  centerWindow?: { start: number; end: number }
 }) {
   const { props, table } = useDataGrid()
-  const leftVisibleCells = row.getLeftVisibleCells()
+  const startVisibleCells = row.getStartVisibleCells()
   const centerVisibleCells = row.getCenterVisibleCells()
-  const rightVisibleCells = row.getRightVisibleCells()
+  const endVisibleCells = row.getEndVisibleCells()
   const hasRightPinnedColumns = hasDataGridTableRightPinnedColumns(table)
+  const windowedCenterCells = centerWindow
+    ? centerVisibleCells.slice(centerWindow.start, centerWindow.end + 1)
+    : centerVisibleCells
+  const leadingSpacerSpan = centerWindow ? centerWindow.start : 0
+  const trailingSpacerSpan = centerWindow
+    ? Math.max(0, centerVisibleCells.length - 1 - centerWindow.end)
+    : 0
 
   return (
     <Fragment>
@@ -1206,18 +2473,50 @@ function DataGridTableRenderedRow<TData>({
         row={row}
         pinnedBoundary={pinnedBoundary}
         rowRef={rowRef}
+        dataIndex={rowIndex}
       >
-        {[...leftVisibleCells, ...centerVisibleCells].map(
-          (cell: Cell<TData, unknown>) => (
+        {startVisibleCells.map(
+          (cell: Cell<DataGridFeatures, TData, unknown>) => (
             <DataGridTableBodyRowCell cell={cell} key={cell.id}>
               {flexRender(cell.column.columnDef.cell, cell.getContext())}
             </DataGridTableBodyRowCell>
           )
         )}
+        {/* The spacers are the only cells added and removed on every column
+            shift, so they carry no data-slot: a common `[data-slot] ~
+            [data-slot]` rule (button groups) would otherwise flag every row,
+            and each shift would restyle the whole grid. */}
+        {leadingSpacerSpan > 0 && (
+          <td
+            aria-hidden="true"
+            data-col-spacer="start"
+            colSpan={leadingSpacerSpan}
+          />
+        )}
+        {windowedCenterCells.map(
+          (cell: Cell<DataGridFeatures, TData, unknown>, cellIndex) => (
+            <DataGridTableBodyRowCell
+              cell={cell}
+              key={cell.id}
+              columnIndex={
+                centerWindow ? centerWindow.start + cellIndex : undefined
+              }
+            >
+              {flexRender(cell.column.columnDef.cell, cell.getContext())}
+            </DataGridTableBodyRowCell>
+          )
+        )}
+        {trailingSpacerSpan > 0 && (
+          <td
+            aria-hidden="true"
+            data-col-spacer="end"
+            colSpan={trailingSpacerSpan}
+          />
+        )}
         {props.tableLayout?.columnsResizable && hasRightPinnedColumns ? (
           <DataGridTableFillBodyCell />
         ) : null}
-        {rightVisibleCells.map((cell: Cell<TData, unknown>) => (
+        {endVisibleCells.map((cell: Cell<DataGridFeatures, TData, unknown>) => (
           <DataGridTableBodyRowCell cell={cell} key={cell.id}>
             {flexRender(cell.column.columnDef.cell, cell.getContext())}
           </DataGridTableBodyRowCell>
@@ -1232,44 +2531,87 @@ function DataGridTableRenderedRow<TData>({
 }
 
 function DataGridTableEmpty() {
-  const { table, props } = useDataGrid()
+  const { i18n, table, props } = useDataGrid()
+  const stopObserverRef = useRef<(() => void) | null>(null)
   const visibleColumnCount =
     getDataGridTableOrderedVisibleColumns(table).length +
     (props.tableLayout?.columnsResizable ? 1 : 0)
 
+  // The cell spans the whole table, so on a table wider than its scroll
+  // viewport text-center lands off-screen. A sticky box sized to the
+  // viewport centres the message on what is visible. It is sized only
+  // while the table overflows, so it can never widen the table itself.
+  const handleMessageRef = useCallback((node: HTMLDivElement | null) => {
+    stopObserverRef.current?.()
+    stopObserverRef.current = null
+    if (!node || typeof ResizeObserver === "undefined") return
+
+    const scrollViewport =
+      getDataGridScrollAreaViewport(node) ??
+      node.closest('[data-slot="data-grid-table-viewport"]')?.parentElement
+    if (!scrollViewport) return
+
+    const measure = () => {
+      const overflows =
+        scrollViewport.scrollWidth > scrollViewport.clientWidth + 0.5
+      node.style.width = overflows ? `${scrollViewport.clientWidth}px` : ""
+    }
+    measure()
+
+    const observer = new ResizeObserver(measure)
+    observer.observe(scrollViewport)
+    const tableNode = node.closest("table")
+    if (tableNode) observer.observe(tableNode)
+    stopObserverRef.current = () => observer.disconnect()
+  }, [])
+
   return (
     <tr>
       <td
         colSpan={Math.max(visibleColumnCount, 1)}
         className="text-muted-foreground py-6 text-center text-sm"
       >
-        {props.emptyMessage || "No data available"}
+        <div
+          ref={handleMessageRef}
+          data-slot="data-grid-table-empty"
+          className="sticky start-0"
+        >
+          {props.emptyMessage || i18n.labels.empty}
+        </div>
       </td>
     </tr>
   )
 }
 
 function DataGridTableLoader() {
-  const { props } = useDataGrid()
+  const { i18n, props } = useDataGrid()
 
   return (
     <div className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2">
       <div className="text-muted-foreground bg-card rounded-lg flex items-center gap-2 border px-4 py-2 text-sm leading-none font-medium">
         <Spinner className="size-5 opacity-60" />
-        {props.loadingMessage || "Loading..."}
+        {props.loadingMessage || i18n.labels.loading}
       </div>
     </div>
   )
 }
 
-function DataGridTableRowPin<TData>({ row }: { row: Row<TData> }) {
+function DataGridTableRowPin<TData extends object>({
+  row,
+}: {
+  row: Row<DataGridFeatures, TData>
+}) {
+  const { i18n } = useDataGrid()
   const isPinned = row.getIsPinned()
 
   return (
     <button
       type="button"
-      aria-label={isPinned ? "Unpin row" : "Pin row"}
-      onClick={() => {
+      aria-label={isPinned ? i18n.labels.unpinRow : i18n.labels.pinRow}
+      onClick={(event) => {
+        // Pinning must not bubble into the row's onRowClick handler.
+        event.stopPropagation()
+
         if (isPinned) {
           row.pin(false)
         } else {
@@ -1312,51 +2654,156 @@ function DataGridTableRowPin<TData>({ row }: { row: Row<TData> }) {
   )
 }
 
-function DataGridTableRowSelect<TData>({ row }: { row: Row<TData> }) {
+/**
+ * Selection cell.
+ *
+ * Selection is read through `row.getIsSelected()`, a builder call on a row
+ * that keeps its identity across renders. A consumer's compiled component
+ * around this checkbox caches it against that row and never renders it
+ * again, which shows up as checkboxes that do not respond to clicks.
+ * Subscribing to the row-selection atom makes selection a dependency of its
+ * own. Note the standalone `Subscribe` rather than `table.Subscribe`: inside a
+ * cell template the `table` handed to the column def is the core `Table`, which
+ * has no `Subscribe` attached.
+ */
+function DataGridTableRowSelect<TData extends object>({
+  row,
+}: {
+  row: Row<DataGridFeatures, TData>
+}) {
+  const { i18n } = useDataGrid()
   return (
-    <>
-      <div
-        className={cn(
-          "bg-primary absolute inset-s-0 top-0 bottom-0 hidden w-[2px]",
-          row.getIsSelected() && "block"
-        )}
-      ></div>
-      <Checkbox
-        checked={row.getIsSelected()}
-        onCheckedChange={(value) => row.toggleSelected(!!value)}
-        aria-label="Select row"
-        className="align-[inherit]"
-      />
-    </>
+    <Subscribe source={row.table.atoms.rowSelection}>
+      {() => (
+        <>
+          <Checkbox
+            checked={row.getIsSelected()}
+            indeterminate={row.getIsSomeSelected() && !row.getIsSelected()}
+            onCheckedChange={(value) => row.toggleSelected(!!value)}
+            onClick={(event) => {
+              // Selection must not bubble into the row's onRowClick handler.
+              event.stopPropagation()
+            }}
+            aria-label={i18n.labels.selectRow}
+            className="align-[inherit]"
+          />
+        </>
+      )}
+    </Subscribe>
   )
 }
 
 function DataGridTableRowSelectAll() {
-  const { table, recordCount, isLoading } = useDataGrid()
-
-  const isAllSelected = table.getIsAllPageRowsSelected()
-  const isSomeSelected = table.getIsSomePageRowsSelected()
+  const { i18n, table, recordCount, isLoading } = useDataGrid()
 
+  // `getIsSomePageRowsSelected()` means "at least one" in v9, where v8 meant
+  // "some but not all", so the all-selected case has to be excluded explicitly
+  // or the header checkbox stays indeterminate once every row is checked.
   return (
-    <Checkbox
-      checked={isAllSelected}
-      indeterminate={isSomeSelected && !isAllSelected}
-      disabled={isLoading || recordCount === 0}
-      onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
-      aria-label="Select all"
-      className="align-[inherit]"
-    />
+    <Subscribe source={table.atoms.rowSelection}>
+      {() => {
+        const isAllSelected = table.getIsAllPageRowsSelected()
+        const isSomeSelected = table.getIsSomePageRowsSelected()
+
+        return (
+          <Checkbox
+            checked={isAllSelected}
+            indeterminate={isSomeSelected && !isAllSelected}
+            disabled={isLoading || recordCount === 0}
+            onCheckedChange={(value) =>
+              table.toggleAllPageRowsSelected(!!value)
+            }
+            aria-label={i18n.labels.selectAll}
+            className="align-[inherit]"
+          />
+        )
+      }}
+    </Subscribe>
   )
 }
 
-function DataGridTableBodyRows<TData>({ table }: { table: Table<TData> }) {
-  const { isLoading, props } = useDataGrid()
-  const pagination = table.getState().pagination
+function DataGridTableRowExpand<TData extends object>({
+  row,
+  indent = 20,
+  className,
+  children,
+}: {
+  row: Row<DataGridFeatures, TData>
+  /** Horizontal offset in px applied per tree depth level. */
+  indent?: number
+  className?: string
+  /** Custom toggle icon; replaces the default chevron. */
+  children?: ReactNode
+}) {
+  const { i18n, props } = useDataGrid()
+  const isExpanded = row.getIsExpanded()
+  const controlSize = props.tableLayout?.dense ? "size-6" : "size-7"
+
+  return (
+    <span
+      data-slot="data-grid-table-row-expand"
+      style={getDataGridTreeIndentStyle(row, indent)}
+      className={cn(
+        "inline-flex shrink-0 items-center ps-(--data-grid-tree-padding) align-middle",
+        className
+      )}
+    >
+      {row.getCanExpand() ? (
+        <button
+          type="button"
+          aria-expanded={isExpanded}
+          aria-label={
+            isExpanded ? i18n.labels.collapseRow : i18n.labels.expandRow
+          }
+          onClick={(event) => {
+            // Expansion must not bubble into the row's onRowClick handler.
+            event.stopPropagation()
+            row.toggleExpanded()
+          }}
+          className={cn(
+            "text-muted-foreground hover:text-foreground rounded-lg inline-flex items-center justify-center transition-colors",
+            controlSize
+          )}
+        >
+          {children ?? (
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="16"
+              height="16"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden="true"
+              className="transition-transform duration-200 in-aria-[expanded=false]:-rotate-90 rtl:in-aria-[expanded=false]:rotate-90"
+            >
+              <path d="m6 9 6 6 6-6" />
+            </svg>
+          )}
+        </button>
+      ) : (
+        // Leaf spacer: compact by design so leaf content sits near the
+        // parent label instead of a full toggle width deeper.
+        <span aria-hidden="true" className="w-2 shrink-0" />
+      )}
+    </span>
+  )
+}
+
+function DataGridTableBodyRows<TData extends object>({
+  table,
+}: {
+  table: DataGridTableInstance<TData>
+}) {
+  const { i18n, isLoading, props } = useDataGrid()
+  const pagination = table.state.pagination
 
   if (isLoading && props.loadingMode === "skeleton" && pagination?.pageSize) {
-    const leftVisibleColumns = table.getLeftVisibleLeafColumns()
+    const leftVisibleColumns = table.getStartVisibleLeafColumns()
     const centerVisibleColumns = table.getCenterVisibleLeafColumns()
-    const rightVisibleColumns = table.getRightVisibleLeafColumns()
+    const rightVisibleColumns = table.getEndVisibleLeafColumns()
     const hasRightPinnedColumns = hasDataGridTableRightPinnedColumns(table)
 
     return (
@@ -1388,7 +2835,14 @@ function DataGridTableBodyRows<TData>({ table }: { table: Table<TData> }) {
   if (isLoading && props.loadingMode === "spinner") {
     return (
       <tr>
-        <td colSpan={table.getVisibleFlatColumns().length} className="p-8">
+        <td
+          // Leaves only: v9's visible flat columns include group columns.
+          colSpan={
+            getDataGridTableOrderedVisibleColumns(table).length +
+            (props.tableLayout?.columnsResizable ? 1 : 0)
+          }
+          className="p-8"
+        >
           <div className="flex items-center justify-center">
             <svg
               className="text-muted-foreground mr-3 -ml-1 h-5 w-5 animate-spin"
@@ -1410,7 +2864,7 @@ function DataGridTableBodyRows<TData>({ table }: { table: Table<TData> }) {
                 d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
               ></path>
             </svg>
-            {props.loadingMessage || "Loading..."}
+            {props.loadingMessage || i18n.labels.loading}
           </div>
         </td>
       </tr>
@@ -1441,13 +2895,18 @@ function DataGridTableBodyRows<TData>({ table }: { table: Table<TData> }) {
  * Memoized body rows: skip re-renders during active column resize.
  * Column widths update via CSS variables on the <table> element,
  * so the browser handles width changes without React re-renders.
+ * A cell-selection drag gets the same treatment: the root re-renders once per
+ * cell crossed, but painting goes through each cell's own Subscribe, so row
+ * reconciliation during the drag is pure waste.
  */
 const MemoizedDataGridTableBodyRows = memo(
   DataGridTableBodyRows,
-  (_prev, next) => !!next.table.getState().columnSizingInfo.isResizingColumn
+  (_prev, next) =>
+    !!next.table.state.columnResizing?.isResizingColumn ||
+    next.table._isSelectingCells === true
 ) as typeof DataGridTableBodyRows
 
-function DataGridTableHeader() {
+function DataGridTableHeader<TData extends object>() {
   const { table, props } = useDataGrid()
   const mergedHeaderGroups = getDataGridTableMergedHeaderGroups(table)
   const hasRightPinnedColumns = hasDataGridTableRightPinnedColumns(table)
@@ -1456,57 +2915,48 @@ function DataGridTableHeader() {
     <DataGridTableViewport>
       <DataGridTableBase>
         <DataGridTableHead>
-          {mergedHeaderGroups.map((headerGroup) => {
+          {mergedHeaderGroups.map((headerGroup, rowIndex) => {
+            // The fill strip is one cell spanning every head row, so only
+            // the first row renders it.
+            const fillHeadCell =
+              props.tableLayout?.columnsResizable && rowIndex === 0 ? (
+                <DataGridTableFillHeadCell
+                  rowSpan={mergedHeaderGroups.length}
+                />
+              ) : null
+            const renderHeadCell = (
+              header: (typeof headerGroup.startHeaders)[number]
+            ) => {
+              const coveredHeaders = headerGroup.coveredHeaders.get(header.id)
+              const resizeHeader = getDataGridHeadCellResizeHeader(
+                header,
+                coveredHeaders
+              )
+
+              return (
+                <DataGridTableHeadRowCell
+                  header={header}
+                  coveredHeaders={coveredHeaders}
+                  key={header.id}
+                >
+                  {renderDataGridTableHeadCellContent(header)}
+                  {props.tableLayout?.columnsResizable &&
+                    resizeHeader.column.getCanResize() && (
+                      <DataGridTableHeadRowCellResize header={resizeHeader} />
+                    )}
+                </DataGridTableHeadRowCell>
+              )
+            }
+
             return (
               <DataGridTableHeadRow key={headerGroup.id} rowId={headerGroup.id}>
-                {headerGroup.headers
-                  .filter((header) => header.column.getIsPinned() !== "right")
-                  .map((header) => {
-                    const { column } = header
-
-                    return (
-                      <DataGridTableHeadRowCell header={header} key={header.id}>
-                        {header.isPlaceholder
-                          ? null
-                          : flexRender(
-                              header.column.columnDef.header,
-                              header.getContext()
-                            )}
-                        {props.tableLayout?.columnsResizable &&
-                          column.getCanResize() && (
-                            <DataGridTableHeadRowCellResize header={header} />
-                          )}
-                      </DataGridTableHeadRowCell>
-                    )
-                  })}
-                {props.tableLayout?.columnsResizable &&
-                hasRightPinnedColumns ? (
-                  <DataGridTableFillHeadCell />
-                ) : null}
-                {headerGroup.headers
-                  .filter((header) => header.column.getIsPinned() === "right")
-                  .map((header) => {
-                    const { column } = header
-
-                    return (
-                      <DataGridTableHeadRowCell header={header} key={header.id}>
-                        {header.isPlaceholder
-                          ? null
-                          : flexRender(
-                              header.column.columnDef.header,
-                              header.getContext()
-                            )}
-                        {props.tableLayout?.columnsResizable &&
-                          column.getCanResize() && (
-                            <DataGridTableHeadRowCellResize header={header} />
-                          )}
-                      </DataGridTableHeadRowCell>
-                    )
-                  })}
-                {props.tableLayout?.columnsResizable &&
-                !hasRightPinnedColumns ? (
-                  <DataGridTableFillHeadCell />
-                ) : null}
+                {[
+                  ...headerGroup.startHeaders,
+                  ...headerGroup.centerHeaders,
+                ].map(renderHeadCell)}
+                {hasRightPinnedColumns ? fillHeadCell : null}
+                {headerGroup.endHeaders.map(renderHeadCell)}
+                {!hasRightPinnedColumns ? fillHeadCell : null}
               </DataGridTableHeadRow>
             )
           })}
@@ -1516,7 +2966,7 @@ function DataGridTableHeader() {
   )
 }
 
-function DataGridTable({
+function DataGridTable<TData extends object>({
   footerContent,
   renderHeader = true,
 }: {
@@ -1532,66 +2982,51 @@ function DataGridTable({
       <DataGridTableBase>
         {renderHeader && (
           <DataGridTableHead>
-            {mergedHeaderGroups.map((headerGroup) => {
+            {mergedHeaderGroups.map((headerGroup, rowIndex) => {
+              // The fill strip is one cell spanning every head row, so only
+              // the first row renders it.
+              const fillHeadCell =
+                props.tableLayout?.columnsResizable && rowIndex === 0 ? (
+                  <DataGridTableFillHeadCell
+                    rowSpan={mergedHeaderGroups.length}
+                  />
+                ) : null
+              const renderHeadCell = (
+                header: (typeof headerGroup.startHeaders)[number]
+              ) => {
+                const coveredHeaders = headerGroup.coveredHeaders.get(header.id)
+                const resizeHeader = getDataGridHeadCellResizeHeader(
+                  header,
+                  coveredHeaders
+                )
+
+                return (
+                  <DataGridTableHeadRowCell
+                    header={header}
+                    coveredHeaders={coveredHeaders}
+                    key={header.id}
+                  >
+                    {renderDataGridTableHeadCellContent(header)}
+                    {props.tableLayout?.columnsResizable &&
+                      resizeHeader.column.getCanResize() && (
+                        <DataGridTableHeadRowCellResize header={resizeHeader} />
+                      )}
+                  </DataGridTableHeadRowCell>
+                )
+              }
+
               return (
                 <DataGridTableHeadRow
                   key={headerGroup.id}
                   rowId={headerGroup.id}
                 >
-                  {headerGroup.headers
-                    .filter((header) => header.column.getIsPinned() !== "right")
-                    .map((header) => {
-                      const { column } = header
-
-                      return (
-                        <DataGridTableHeadRowCell
-                          header={header}
-                          key={header.id}
-                        >
-                          {header.isPlaceholder
-                            ? null
-                            : flexRender(
-                                header.column.columnDef.header,
-                                header.getContext()
-                              )}
-                          {props.tableLayout?.columnsResizable &&
-                            column.getCanResize() && (
-                              <DataGridTableHeadRowCellResize header={header} />
-                            )}
-                        </DataGridTableHeadRowCell>
-                      )
-                    })}
-                  {props.tableLayout?.columnsResizable &&
-                  hasRightPinnedColumns ? (
-                    <DataGridTableFillHeadCell />
-                  ) : null}
-                  {headerGroup.headers
-                    .filter((header) => header.column.getIsPinned() === "right")
-                    .map((header) => {
-                      const { column } = header
-
-                      return (
-                        <DataGridTableHeadRowCell
-                          header={header}
-                          key={header.id}
-                        >
-                          {header.isPlaceholder
-                            ? null
-                            : flexRender(
-                                header.column.columnDef.header,
-                                header.getContext()
-                              )}
-                          {props.tableLayout?.columnsResizable &&
-                            column.getCanResize() && (
-                              <DataGridTableHeadRowCellResize header={header} />
-                            )}
-                        </DataGridTableHeadRowCell>
-                      )
-                    })}
-                  {props.tableLayout?.columnsResizable &&
-                  !hasRightPinnedColumns ? (
-                    <DataGridTableFillHeadCell />
-                  ) : null}
+                  {[
+                    ...headerGroup.startHeaders,
+                    ...headerGroup.centerHeaders,
+                  ].map(renderHeadCell)}
+                  {hasRightPinnedColumns ? fillHeadCell : null}
+                  {headerGroup.endHeaders.map(renderHeadCell)}
+                  {!hasRightPinnedColumns ? fillHeadCell : null}
                 </DataGridTableHeadRow>
               )
             })}
@@ -1605,6 +3040,8 @@ function DataGridTable({
 
         <DataGridTableBody>
           <MemoizedDataGridTableBodyRows table={table} />
+          {props.appendRow}
+          <DataGridTableAddRow />
         </DataGridTableBody>
 
         {footerContent && (
@@ -1617,6 +3054,7 @@ function DataGridTable({
 
 export {
   DataGridTable,
+  DataGridTableAddRow,
   DataGridTableBase,
   DataGridTableBody,
   DataGridTableBodyRow,
@@ -1637,15 +3075,21 @@ export {
   DataGridTableHeadRowCell,
   DataGridTableHeadRowCellResize,
   DataGridTableLoader,
+  DataGridTableRowExpand,
   DataGridTableRowPin,
   DataGridTableRowSelect,
   DataGridTableRowSelectAll,
   DataGridTableRowSpacer,
   DataGridTableViewport,
+  getDataGridHeadCellResizeHeader,
+  getDataGridHeadCellSizeVar,
+  getDataGridScrollAreaViewport,
   getDataGridTableMergedHeaderGroups,
+  renderDataGridTableHeadCellContent,
   getPinningStyles,
   getDataGridTableResolvedRows,
   getDataGridTableRowSections,
+  getDataGridTreeIndentStyle,
   hasDataGridTableRightPinnedColumns,
 }
 
diff --git a/apps/web/src/components/reui/data-grid/data-grid.tsx b/apps/web/src/components/reui/data-grid/data-grid.tsx
index 9b04329..f7e7874 100644
--- a/apps/web/src/components/reui/data-grid/data-grid.tsx
+++ b/apps/web/src/components/reui/data-grid/data-grid.tsx
@@ -1,29 +1,227 @@
-import { createContext, ReactNode, useContext, useMemo } from "react"
+"use client"
+
+// Opts the grid out of React Compiler. Its parts read state through builder
+// calls on rows, columns and headers that keep their identity across renders
+// (row.getIsExpanded(), column.getIsResizing()); compiled, those reads are
+// cached against the unchanged object and never run again. The grid memoizes
+// by hand instead, and the component that renders it still compiles.
+"use no memo"
+
 import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from "react"
+import type { ReactNode } from "react"
+import {
+  mergeDataGridI18n,
+  type DataGridI18nConfig,
+  type DataGridI18nOverrides,
+} from "@/components/reui/data-grid/data-grid-i18n"
+import {
+  cellSelectionFeature,
+  columnFacetingFeature,
+  columnFilteringFeature,
+  columnOrderingFeature,
+  columnPinningFeature,
+  columnResizingFeature,
+  columnSizingFeature,
+  columnVisibilityFeature,
+  createExpandedRowModel,
+  createFacetedRowModel,
+  createFacetedUniqueValues,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  globalFilteringFeature,
+  metaHelper,
+  rowExpandingFeature,
+  rowPaginationFeature,
+  rowPinningFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  sortFn_alphanumericCaseSensitive,
+  sortFn_basic,
+  sortFn_datetime,
+  sortFn_text,
+  sortFn_textCaseSensitive,
+  tableFeatures,
+} from "@tanstack/react-table"
+import type {
+  Cell,
   Column,
   ColumnFiltersState,
+  ReactTable,
   RowData,
   SortingState,
   Table,
+  TableFeatures,
 } from "@tanstack/react-table"
 
 import { cn } from "@authportal/ui/lib/utils"
 
-declare module "@tanstack/react-table" {
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  interface ColumnMeta<TData extends RowData, TValue> {
-    headerTitle?: string
-    headerClassName?: string
-    cellClassName?: string
-    skeleton?: ReactNode
-    expandedContent?: (row: TData) => ReactNode
-    autoSize?: boolean
-  }
+/**
+ * Per-column extras the grid reads off `columnDef.meta`.
+ *
+ * TanStack v9 resolves this through the `columnMeta` slot on the feature
+ * bundle below instead of a global `declare module` augmentation, so
+ * installing the data grid no longer widens `ColumnMeta` for every other
+ * table in the consuming app.
+ */
+/**
+ * Per-column write contract for the spreadsheet operations (paste, fill,
+ * clear, cut). Presence marks the column writable; every write still flows
+ * through `onCellsChange`, so the consumer's state stays the only data owner.
+ */
+export interface DataGridColumnCellEdit<TData> {
+  /**
+   * Set false for a column that formats clipboard output but is never
+   * written; a function decides per row, so locked rows (archived, another
+   * user's, a totals row) reject like any read-only cell. Defaults to true.
+   */
+  editable?: boolean | ((row: TData) => boolean)
+  /**
+   * Clipboard or fill string to typed value. Return undefined to reject the
+   * cell into `rejected`. Without it the raw string passes through unchanged -
+   * a deliberate non-coercion, so a number column receives strings only when
+   * the consumer chose not to parse.
+   */
+  parse?: (raw: string, row: TData) => unknown
+  /** Typed value to clipboard string. Fallback: String(value ?? ""). */
+  format?: (value: unknown, row: TData) => string
+  /** Value dispatched by Delete/Backspace and cut. Defaults to null. */
+  clearValue?: unknown
+  /**
+   * Opt into the grid's built-in free-text editor: an overlay input (or
+   * auto-growing textarea) flush over the focused cell, opened by Enter, F2,
+   * typing, or double-click, committing through `onCellsChange` as source
+   * `"edit"` with `parse` applied. Columns without it stay consumer-edited
+   * via `onCellEditRequest` or their own cell renderers.
+   */
+  control?: "text" | "textarea"
 }
 
+export interface DataGridColumnMeta<TData> {
+  headerTitle?: string
+  headerClassName?: string
+  cellClassName?: string
+  skeleton?: ReactNode
+  expandedContent?: (row: TData) => ReactNode
+  autoSize?: boolean
+  /** Header spans this many leaves: this one and its next adjacent siblings. */
+  headerColSpan?: number
+  cellEdit?: DataGridColumnCellEdit<TData>
+  /**
+   * Under `columnsResizable`, this column absorbs the free space the filler
+   * strip would otherwise hold, so the grid always reads full-width and the
+   * built-in editor covers the whole cell. One column per grid; while free
+   * space remains, manual resizing of this column is visually a no-op (the
+   * absorbed space compensates), the flex-column trade-off.
+   */
+  fillWidth?: boolean
+}
+
+/**
+ * The batteries-included feature bundle every ReUI data-grid example builds
+ * on. v9 requires each table to declare its features up front, and the grid's
+ * render path needs the ones registered here: `columnVisibilityFeature` alone
+ * gates `row.getVisibleCells()`, so even a grid that never hides a column
+ * needs it to render at all.
+ *
+ * Pass it straight through for the full grid:
+ *
+ * ```tsx
+ * const table = useTable({ features: dataGridFeatures, columns, data })
+ * ```
+ *
+ * Extend it when a grid needs more, keeping each prerequisite feature ahead of
+ * the slot that depends on it:
+ *
+ * ```tsx
+ * const features = tableFeatures({
+ *   ...dataGridFeatures,
+ *   columnGroupingFeature,
+ *   groupedRowModel: createGroupedRowModel(),
+ * })
+ * ```
+ *
+ * Or drop it entirely and hand `<DataGrid>` a leaner table - the components
+ * accept any bundle, so you keep full ownership of the TanStack core.
+ */
+export const dataGridFeatures = tableFeatures({
+  columnVisibilityFeature,
+  columnOrderingFeature,
+  columnPinningFeature,
+  columnSizingFeature,
+  // columnResizingFeature requires columnSizingFeature, declared above.
+  columnResizingFeature,
+  columnFilteringFeature,
+  // Powers DataGridColumnFilter's column.getFacetedUniqueValues(). On v8 an
+  // unregistered facet silently returned an empty map; on v9 the method would
+  // not exist at all, so the faceted row models below are required, not
+  // optional.
+  columnFacetingFeature,
+  // globalFilteringFeature requires columnFilteringFeature, declared above.
+  globalFilteringFeature,
+  rowSortingFeature,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowExpandingFeature,
+  rowPinningFeature,
+  // Registration alone is inert: it seeds a `cellSelection: []` slice and
+  // prototype methods but binds no DOM handlers, so grids without
+  // `tableLayout.cellSelection` render and behave exactly as before.
+  cellSelectionFeature,
+  sortedRowModel: createSortedRowModel(),
+  filteredRowModel: createFilteredRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+  expandedRowModel: createExpandedRowModel(),
+  facetedRowModel: createFacetedRowModel(),
+  facetedUniqueValues: createFacetedUniqueValues(),
+  // Every built-in v9 ships. A string `sortFn` resolves against this map
+  // alone, and `sortFn: "auto"` infers a name ("alphanumeric", "text" or
+  // "datetime") from the first row's value - so a partial map makes auto
+  // sorting warn and silently fall back on ordinary string columns.
+  sortFns: {
+    alphanumeric: sortFn_alphanumeric,
+    alphanumericCaseSensitive: sortFn_alphanumericCaseSensitive,
+    basic: sortFn_basic,
+    datetime: sortFn_datetime,
+    text: sortFn_text,
+    textCaseSensitive: sortFn_textCaseSensitive,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  columnMeta: metaHelper<DataGridColumnMeta<any>>(),
+})
+
+/** The feature set `dataGridFeatures` registers. */
+export type DataGridFeatures = typeof dataGridFeatures
+
+/**
+ * The grid's internal view of the table.
+ *
+ * `TFeatures` is invariant in v9 and an unresolved generic one collapses to a
+ * union that includes the bare core arm, so no generic signature can call
+ * `getVisibleCells()`, `getStartVisibleLeafColumns()` and friends. The public
+ * components stay generic so consumers can pass any bundle they like; the
+ * table is widened to this concrete type exactly once, on the way into
+ * context, and every internal component reads it from there.
+ */
+export type DataGridTableInstance<TData extends object> = ReactTable<
+  DataGridFeatures,
+  TData
+>
+
 /** Label for headers / column visibility: `meta.headerTitle`, string `columnDef.header`, or `column.id`. */
-export function getColumnHeaderLabel<TData, TValue>(
-  column: Column<TData, TValue>
+export function getColumnHeaderLabel<TData extends RowData, TValue>(
+  column: Column<DataGridFeatures, TData, TValue>
 ): string {
   const meta = column.columnDef.meta as { headerTitle?: string } | undefined
   if (typeof meta?.headerTitle === "string") return meta.headerTitle
@@ -32,6 +230,179 @@ export function getColumnHeaderLabel<TData, TValue>(
   return String(column.id)
 }
 
+/**
+ * meta.headerColSpan: the sibling leaves each owning leaf's header covers,
+ * by owner id. Each must render right after the last in its pin family, or
+ * the span ends there; the header rows, the resize indicator and the move
+ * and drop targets all read spans from here.
+ */
+export function getDataGridHeaderSpans<TData extends object>(
+  table: DataGridTableInstance<TData>
+) {
+  const spans = new Map<string, Column<DataGridFeatures, TData, unknown>[]>()
+  const families = [
+    table.getStartVisibleLeafColumns(),
+    table.getCenterVisibleLeafColumns(),
+    table.getEndVisibleLeafColumns(),
+  ] as Column<DataGridFeatures, TData, unknown>[][]
+
+  for (const family of families) {
+    for (let index = 0; index < family.length; index++) {
+      const owner = family[index]!
+      const span = Math.floor(owner.columnDef.meta?.headerColSpan ?? 1)
+      if (span < 2) continue
+
+      // The next span - 1 siblings in definition order, so a span never
+      // leaves its parent group; a hidden one is skipped, not a gap.
+      const siblings = owner.parent?.columns ?? table.getAllColumns()
+      const at = siblings.findIndex((sibling) => sibling.id === owner.id)
+      const intended =
+        at < 0
+          ? []
+          : siblings
+              .slice(at + 1, at + span)
+              .filter((sibling) => sibling.getIsVisible())
+      const covered: Column<DataGridFeatures, TData, unknown>[] = []
+      for (const sibling of intended) {
+        const next = family[index + 1 + covered.length]
+        if (next?.id !== sibling.id) break
+        covered.push(next)
+      }
+      if (!covered.length) continue
+
+      spans.set(owner.id, covered)
+      index += covered.length
+    }
+  }
+
+  return spans
+}
+
+/**
+ * The td contract for spreadsheet selection. Call inside a
+ * `Subscribe source={table.atoms.cellSelection}` render only: the reads are
+ * builder calls whose state dependency React Compiler cannot see, exactly the
+ * trap the row-selection checkbox documents.
+ */
+export function getDataGridCellSelectionCellAttrs<TData extends object>(
+  cell: Cell<DataGridFeatures, TData, unknown>
+): {
+  "aria-selected": boolean
+  "data-col-id": string
+  "data-cell-selected": true | undefined
+  "data-cell-focused": true | undefined
+  "data-cell-edge-top": true | undefined
+  "data-cell-edge-right": true | undefined
+  "data-cell-edge-bottom": true | undefined
+  "data-cell-edge-left": true | undefined
+} {
+  const selected = cell.getIsSelected()
+  const edges = cell.getSelectionEdges()
+  return {
+    "aria-selected": selected,
+    "data-col-id": cell.column.id,
+    "data-cell-selected": selected || undefined,
+    "data-cell-focused": cell.getIsFocused() || undefined,
+    "data-cell-edge-top": edges.top || undefined,
+    "data-cell-edge-right": edges.right || undefined,
+    "data-cell-edge-bottom": edges.bottom || undefined,
+    "data-cell-edge-left": edges.left || undefined,
+  }
+}
+
+/**
+ * Selection chrome for a body td, activated by the data attributes above plus
+ * the imperatively toggled `data-cell-fill-target` (fill-drag preview, written
+ * outside React like the resize indicator). A ::before overlay, not outline
+ * or box-shadow: an outline ring hugs the cell box and cannot line up with
+ * the gridlines the perimeter paints on, and the pinned-column dividers
+ * already own the cell's shadow slot (tailwind-merge would collapse a second
+ * shadow-[...] into it).
+ */
+export const dataGridCellSelectionCellClasses = cn(
+  "relative select-none",
+  // A light tint: the selection must read as a range without drowning the
+  // gridlines under a heavy fill. The focused cell stays unfilled. Pinned
+  // cells must stay OPAQUE (they hide scrolled content), so they get the
+  // tint pre-mixed over the background, and the focused pinned cell keeps
+  // a solid background instead of turning transparent.
+  "data-[cell-selected]:bg-primary/4",
+  "data-[cell-selected]:data-pinned:bg-[color-mix(in_oklab,var(--primary)_4%,var(--data-grid-surface,var(--data-grid-card-surface,var(--background))))]",
+  "data-[cell-focused]:bg-transparent!",
+  "data-[cell-focused]:data-pinned:bg-[color:var(--data-grid-surface,var(--data-grid-card-surface,var(--background)))]!",
+  // Every selection line is one layout-free ::before overlay per cell. It
+  // reaches 1px BEYOND the cell so each line paints exactly ON the shared
+  // gridline it replaces: the range perimeter and the interior dividers
+  // share this geometry, so where they meet they coincide instead of
+  // stacking into a wider edge, every side stays exactly 1px, and
+  // selecting never adds real borders that shift layout. At the table's
+  // own boundary there is no shared gridline and the overshoot leaves the
+  // scrollable content box, where it is CLIPPED - the perimeter simply
+  // vanished on the first column, last column and last row. So every
+  // overshoot that can hit a boundary goes through a variable the
+  // boundary cells zero out. Longhand inset utilities only, logical
+  // start/end
+  // so RTL mirrors for free; a separate override rule cannot do this,
+  // equal-specificity variants leave shorthand-vs-longhand to sort order.
+  "data-[cell-selected]:before:pointer-events-none data-[cell-selected]:before:absolute data-[cell-selected]:before:top-[var(--data-grid-overlay-top,-1px)] data-[cell-selected]:before:start-[var(--data-grid-overlay-start,-1px)] data-[cell-selected]:before:end-[var(--data-grid-overlay-end,-1px)] data-[cell-selected]:before:bottom-[var(--data-grid-overlay-bottom,-1px)] data-[cell-selected]:before:border-primary data-[cell-selected]:before:content-['']",
+  "data-[cell-focused]:before:pointer-events-none data-[cell-focused]:before:absolute data-[cell-focused]:before:top-[var(--data-grid-overlay-top,-1px)] data-[cell-focused]:before:start-[var(--data-grid-overlay-start,-1px)] data-[cell-focused]:before:end-[var(--data-grid-overlay-end,-1px)] data-[cell-focused]:before:bottom-[var(--data-grid-overlay-bottom,-1px)] data-[cell-focused]:before:border-primary data-[cell-focused]:before:content-['']",
+  // Interior dividers: selected cells repaint their own end and bottom
+  // gridlines on the overlay, so gridline-less grids still divide a range.
+  // The gray color is guarded by not- variants (higher specificity), so a
+  // side that belongs to the range perimeter deterministically stays
+  // primary.
+  "data-[cell-selected]:before:border-e data-[cell-selected]:before:border-b",
+  "data-[cell-selected]:not-data-[cell-edge-right]:before:border-e-border",
+  "data-[cell-selected]:not-data-[cell-edge-bottom]:before:border-b-border",
+  // The Sheets model: a single selected cell IS its own range, so the four
+  // edge attributes below already draw its full primary box; inside a
+  // larger range the anchor reads by its unfilled background alone. The
+  // explicit ring only covers a focused cell with no selection at all.
+  // Edge sides are logical (border-e/border-s): the feature derives edges
+  // from display-order column indexes, which mirror in RTL.
+  "data-[cell-focused]:not-data-[cell-selected]:before:border",
+  "data-[cell-edge-top]:before:border-t data-[cell-edge-right]:before:border-e data-[cell-edge-bottom]:before:border-b data-[cell-edge-left]:before:border-s",
+  // While a fill drag is live the preview border is the ONE painter for
+  // the whole pending region, so the source cells' own chrome rests -
+  // otherwise its lines double against the region border at every shared
+  // edge. display is the no-cascade-fight switch (see below).
+  "in-data-[cell-filling]:data-[cell-selected]:before:hidden",
+  "in-data-[cell-filling]:data-[cell-focused]:before:hidden",
+  // While the built-in editor is open its outline is the one border; the
+  // edited cell's own overlay chrome hides so nothing peeks around the
+  // flush editor. display is the switch because no other before: rule
+  // sets it, so there is no cascade order to lose.
+  "in-data-[cell-editing]:data-[cell-focused]:before:hidden",
+  // Clamped to the cell edge at the grid's own boundary, the overlay's
+  // lines sit flush against the container border instead of being clipped
+  // away outside the scrollable content. A custom property has no cascade
+  // fight to lose. First/last-child cover the boundary columns: when a
+  // filler td follows the last data column, that cell's overshoot lands
+  // INSIDE the table and needs no clamp, and the td:first/last-child of a
+  // row are its logical start/end in RTL too.
+  "in-[tr:last-child]:[--data-grid-overlay-bottom:0px]",
+  // The top overshoot lands under a sticky header, which is positioned and
+  // paints over it - so the first row's perimeter lost its top line. Clamp
+  // inside the cell there, exactly like the other three boundaries.
+  "in-[tr:first-child]:[--data-grid-overlay-top:0px]",
+  "first:[--data-grid-overlay-start:0px]",
+  "last:[--data-grid-overlay-end:0px]",
+  // A pinned column is a boundary like the grid's own edges: the sticky
+  // neighbor would cover an on-gridline overlay line, and re-painting it
+  // from the pinned side doubles into a 2px blur whenever subpixel
+  // positions disagree (browser zoom, fractional fill widths). One
+  // painter instead: the overlay clamps inside its own cell there, the
+  // same custom-property clamp the first and last cells use.
+  "[&:has(+td[data-pinned])]:[--data-grid-overlay-end:0px]",
+  "[&:has(+[data-slot=data-grid-table-fill-body-cell]:last-child)]:[--data-grid-overlay-end:0px]",
+  "[&:has(+[data-slot=data-grid-table-fill-body-cell]+td[data-pinned])]:[--data-grid-overlay-end:0px]",
+  "[td[data-pinned]+&]:[--data-grid-overlay-start:0px]",
+  // Tint only: the dashed region outline is one overlay element drawn by
+  // the fill session, so neighboring target cells never double their edges.
+  "data-[cell-fill-target]:bg-primary/4",
+  "data-[cell-fill-target]:data-pinned:bg-[color-mix(in_oklab,var(--primary)_4%,var(--data-grid-surface,var(--data-grid-card-surface,var(--background))))]"
+)
+
 export type DataGridApiFetchParams = {
   pageIndex: number
   pageSize: number
@@ -49,11 +420,297 @@ export type DataGridApiResponse<T> = {
   }
 }
 
+/**
+ * Everything `<DataGrid>` accepts except the two props the provider consumes
+ * itself. Kept feature-agnostic: layout and messaging never depend on which
+ * TanStack features the consumer registered.
+ */
+export type DataGridLayoutProps<TData extends object> = Omit<
+  DataGridProps<TableFeatures, TData>,
+  "table" | "children"
+>
+
 export interface DataGridContextProps<TData extends object> {
-  props: DataGridProps<TData>
-  table: Table<TData>
+  props: DataGridLayoutProps<TData>
+  table: DataGridTableInstance<TData>
   recordCount: number
   isLoading: boolean
+  /** Stable per-grid prefix for the DOM ids ARIA relations point at. */
+  gridId: string
+  /** The merged label set; components read `i18n.labels.<key>`. */
+  i18n: DataGridI18nConfig
+  /**
+   * Internal coordinator for `meta.autoSize` columns. Lives at the core level
+   * so every table variant and viewport instance shares one application state.
+   */
+  autoSize?: DataGridAutoSizeController
+}
+
+/**
+ * Row and column ids are consumer strings; DOM ids cannot carry spaces or
+ * quotes. One shared sanitizer so `aria-activedescendant` writers and the id
+ * renderers always agree on the same encoding.
+ */
+export function toDataGridDomId(value: string): string {
+  return value.replace(/[^\w-]/g, "_")
+}
+
+export type DataGridAutoSizeController = {
+  /**
+   * Feeds the controller one viewport measurement: the SIGNED free space
+   * between the scroll container and the table, negative while the table
+   * overflows. The first sight of a `meta.autoSize` column absorbs the
+   * free space into its width; after that, every measurement REFLOWS the
+   * same growth - a wider window widens the column, a narrower one gives
+   * the space back down to the column's `minSize` (or its starting width
+   * when none is set) - so the grid tracks its container live. Commits
+   * are coalesced for performance: sub-pixel deltas are dropped, a
+   * streaming resize gets one leading commit plus one trailing commit at
+   * settle, and a width the user dragged is never touched. Safe to call
+   * from every viewport measurement; returns true when a sizing update
+   * was dispatched.
+   */
+  apply: (freeSpace: number) => boolean
+  /**
+   * The width the armed column would reflow to at this free space, and the
+   * width it holds now, without committing anything. Null when no column is
+   * armed. A live (onChange) resize previews with it on every move.
+   */
+  preview: (
+    freeSpace: number
+  ) => { columnId: string; current: number; size: number } | null
+  /**
+   * Records a width the caller commits for the armed column, so the next
+   * measurement reads it as this coordinator's own write and keeps
+   * reflowing, rather than as a user drag that stands it down.
+   */
+  adopt: (columnId: string, size: number) => void
+}
+
+type DataGridAutoSizeReflowState = {
+  applied: { columnId: string; base: number; grown: number } | null
+  settleTimer: ReturnType<typeof setTimeout> | null
+  pendingFreeSpace: number
+  lastCommitAt: number
+}
+
+/**
+ * Bookkeeping keyed on the TABLE STORE, never on a React instance: dev
+ * StrictMode double-mounts the tree, so two controller instances serve one
+ * page and only the first would remember what it absorbed - the second
+ * reads the grown width as a user drag and freezes the column. The store
+ * object is the one identity that provably survives that dance (the
+ * absorbed sizing rides inside it), and the WeakMap lets a discarded
+ * table take its bookkeeping with it.
+ */
+const dataGridAutoSizeStates = new WeakMap<
+  object,
+  DataGridAutoSizeReflowState
+>()
+
+function getDataGridAutoSizeState(store: object): DataGridAutoSizeReflowState {
+  let state = dataGridAutoSizeStates.get(store)
+  if (!state) {
+    state = {
+      applied: null,
+      settleTimer: null,
+      pendingFreeSpace: 0,
+      lastCommitAt: 0,
+    }
+    dataGridAutoSizeStates.set(store, state)
+  }
+  return state
+}
+
+function createDataGridAutoSizeController<TData extends object>(
+  /**
+   * A getter, not the table itself.
+   *
+   * v8 handed back one stable table whose state mutated in place, so a
+   * controller could close over it. v9 returns a NEW table wrapper on every
+   * state change, and a captured one keeps reporting the state it was built
+   * with - here that meant `columnSizing` looked permanently empty, the
+   * applied-once guard re-armed on every measurement, and the fill overwrote
+   * whatever width the user had just dragged the column to.
+   */
+  getTable: () => DataGridTableInstance<TData>
+): DataGridAutoSizeController {
+  // Reflow coalescing: a live window drag streams a measurement per frame,
+  // and every accepted commit re-renders the table. One leading commit
+  // keeps single snaps (a maximize) instant; the rest of the stream parks
+  // its latest value behind one trailing timer, so a continuous drag costs
+  // two commits instead of sixty a second. The trailing timer may fire
+  // after the grid unmounts; it re-reads the table then, and a sizing
+  // write to the consumer's store is inert once nothing renders it.
+  const SETTLE_MS = 150
+
+  // The armed column's reflow target at this free space. Shared by reflow,
+  // which commits it, and preview, which only reports it.
+  const resolveReflow = (freeSpace: number) => {
+    const table = getTable()
+    const state = getDataGridAutoSizeState(table.store)
+    // LIVE state, never the render snapshot: a measurement can run between
+    // our own sizing commit and React's re-render, and the stale snapshot
+    // would hide the width this controller just wrote.
+    const columnSizing =
+      table.atoms.columnSizing?.get() ?? table.state.columnSizing
+    if (!state.applied) return null
+    const autoSizeColumn = table
+      .getVisibleLeafColumns()
+      .find(
+        (column) => column.columnDef.meta?.autoSize && column.getCanResize()
+      )
+    if (!autoSizeColumn || autoSizeColumn.id !== state.applied.columnId)
+      return null
+    // A width this coordinator did not write belongs to the user's drag;
+    // reflow stands down until a reset re-arms the column.
+    const currentSize = columnSizing[state.applied.columnId]
+    if (currentSize !== undefined && currentSize !== state.applied.grown) {
+      return null
+    }
+    // The free space as it would measure with our growth removed; the
+    // target re-absorbs exactly that, floored at minSize so a narrow
+    // window hands space back without ever crushing the column (no
+    // explicit minSize floors at the starting width instead). The resolved
+    // columnDef always carries TanStack's built-in minSize (20), so only a
+    // value that differs from the defaults, or a defaultColumn.minSize,
+    // counts as one the consumer set.
+    const freeAtBase = freeSpace + (state.applied.grown - state.applied.base)
+    const resolvedMinSize = autoSizeColumn.columnDef.minSize
+    const hasConsumerMinSize =
+      table.options.defaultColumn?.minSize !== undefined ||
+      resolvedMinSize !== table.getDefaultColumnDef().minSize
+    const floor =
+      hasConsumerMinSize && resolvedMinSize !== undefined
+        ? resolvedMinSize
+        : state.applied.base
+    const target = Math.max(floor, state.applied.base + freeAtBase)
+    return {
+      table,
+      state,
+      applied: state.applied,
+      target,
+      // Always set on a resolved columnDef (MAX_SAFE_INTEGER by default).
+      maxSize: autoSizeColumn.columnDef.maxSize!,
+    }
+  }
+
+  const reflow = (freeSpace: number): boolean => {
+    const resolved = resolveReflow(freeSpace)
+    if (!resolved) return false
+    const { table, state, applied, target } = resolved
+    if (Math.abs(target - applied.grown) < 1) return false
+    state.applied = { ...applied, grown: target }
+    table.setColumnSizing((old) => ({
+      ...old,
+      [applied.columnId]: target,
+    }))
+    return true
+  }
+
+  return {
+    preview(freeSpace: number) {
+      const resolved = resolveReflow(freeSpace)
+      // In rendered pixels: getSize() clamps to maxSize, so an unclamped
+      // preview painted a capped column past its cap until the release.
+      return resolved
+        ? {
+            columnId: resolved.applied.columnId,
+            current: Math.min(resolved.applied.grown, resolved.maxSize),
+            size: Math.min(resolved.target, resolved.maxSize),
+          }
+        : null
+    },
+    adopt(columnId: string, size: number) {
+      const state = getDataGridAutoSizeState(getTable().store)
+      if (state.applied?.columnId === columnId) {
+        state.applied = { ...state.applied, grown: size }
+      }
+    },
+    apply(freeSpace: number) {
+      const table = getTable()
+      const state = getDataGridAutoSizeState(table.store)
+      // Same live read as `reflow`; the snapshot race is what made the
+      // re-arm check clear the bookkeeping right after the first absorb.
+      const columnSizing =
+        table.atoms.columnSizing?.get() ?? table.state.columnSizing
+
+      // Re-arm after reset flows (double-click resetSize, resetColumnSizing,
+      // controlled state replacement) so the column re-fills instead of
+      // leaving a dead blank strip.
+      if (state.applied && columnSizing[state.applied.columnId] === undefined) {
+        state.applied = null
+      }
+
+      const autoSizeColumn = table
+        .getVisibleLeafColumns()
+        .find(
+          (column) => column.columnDef.meta?.autoSize && column.getCanResize()
+        )
+
+      if (autoSizeColumn && state.applied?.columnId === autoSizeColumn.id) {
+        state.pendingFreeSpace = freeSpace
+        const now = Date.now()
+        if (now - state.lastCommitAt > SETTLE_MS) {
+          state.lastCommitAt = now
+          return reflow(freeSpace)
+        }
+        if (state.settleTimer !== null) clearTimeout(state.settleTimer)
+        state.settleTimer = setTimeout(() => {
+          state.settleTimer = null
+          state.lastCommitAt = Date.now()
+          reflow(state.pendingFreeSpace)
+        }, SETTLE_MS)
+        return false
+      }
+
+      const fillWidth = Math.max(0, freeSpace)
+      if (fillWidth <= 0) return false
+
+      if (!autoSizeColumn) {
+        return false
+      }
+
+      // A width this coordinator did not write belongs to someone else -
+      // almost always the user, who just dragged the column's resize handle.
+      // Filling over it is what made a `meta.autoSize` column look
+      // un-resizable: the drag committed, the next viewport measurement
+      // stamped the fill back on top, and the column snapped to its old width.
+      //
+      // Deliberately keyed on observed state rather than on `state.applied`, which
+      // is per-coordinator memory: anything that rebuilds the coordinator
+      // (a remount, a new table store) forgets what it did, and the guard has
+      // to survive that. An explicit reset clears the entry and re-arms the
+      // fill, which is what makes double-click-to-reset still work.
+      const currentSize = columnSizing[autoSizeColumn.id]
+      if (currentSize !== undefined && currentSize !== state.applied?.grown) {
+        return false
+      }
+
+      // Candidate switched (e.g. the grown column was hidden and another
+      // meta.autoSize column took over): revert the previous growth if the
+      // user hasn't manually resized that column since, so visibility
+      // toggles cannot ratchet the table wider than its container forever.
+      const revert =
+        state.applied &&
+        columnSizing[state.applied.columnId] === state.applied.grown
+          ? state.applied
+          : null
+      const base = columnSizing[autoSizeColumn.id] ?? autoSizeColumn.getSize()
+      const grown = base + fillWidth
+
+      state.applied = { columnId: autoSizeColumn.id, base, grown }
+      table.setColumnSizing((old) => {
+        const next = { ...old, [autoSizeColumn.id]: grown }
+        if (revert && next[revert.columnId] === revert.grown) {
+          next[revert.columnId] = revert.base
+        }
+        return next
+      })
+
+      return true
+    },
+  }
 }
 
 export type DataGridRequestParams = {
@@ -63,13 +720,169 @@ export type DataGridRequestParams = {
   columnFilters?: ColumnFiltersState
 }
 
-export interface DataGridProps<TData extends object> {
+/** Which spreadsheet operation produced a cell change batch. */
+export type DataGridCellsChangeSource =
+  | "paste"
+  | "cut"
+  | "clear"
+  | "fill"
+  | "edit"
+
+export interface DataGridCellChange<TData> {
+  rowId: string
+  columnId: string
+  /** The consumer's row object, so immutable write-back needs no second lookup. */
+  row: TData
+  /** Accessor value at dispatch time; enables consumer-side undo stacks. */
+  previousValue: unknown
+  /** Typed value produced by `meta.cellEdit.parse`, or `clearValue` for clear/cut. */
+  value: unknown
+}
+
+/** What onCellsCopy receives after the grid writes the clipboard. */
+export interface DataGridCopyDetails {
+  /** The TSV text that reached the clipboard. */
+  text: string
+  /** The same content as a row-major grid of formatted fields. */
+  grid: string[][]
+  /** True when the write came from a cut, which clears the region next. */
+  cut: boolean
+}
+
+/** One resolved positive region, in pre-paginated display indexes. */
+export interface DataGridCellSelectionBound {
+  minRowIndex: number
+  maxRowIndex: number
+  minColumnIndex: number
+  maxColumnIndex: number
+}
+
+/** What onCellSelectionChange receives, resolved from the live selection. */
+export interface DataGridCellSelectionSnapshot {
+  /** The virtually focused cell, the active range's anchor. Null when clear. */
+  focused: { rowId: string; columnId: string } | null
+  /** Every positive region, geometric order. */
+  bounds: DataGridCellSelectionBound[]
+  /** The most recent region, the one copy and paste act on. */
+  activeBound: DataGridCellSelectionBound | null
+  /**
+   * Cells of the selection the view can show - the count that matches the
+   * painted range and what a batch will touch.
+   */
+  visibleCellCount: number
+}
+
+export interface DataGridCellRejection {
+  rowId: string
+  columnId: string
+  raw: string
+  reason: "readonly" | "invalid"
+}
+
+/**
+ * Lifecycle of a row for the optional CRUD indications: "new" and "dirty"
+ * tint the row, "deleted" mutes and strikes it. Purely presentational - the
+ * consumer's state stays the only owner of what the statuses mean.
+ */
+export type DataGridRowStatus = "new" | "dirty" | "deleted"
+
+/**
+ * Lifecycle of a cell for the optional CRUD indications: a corner mark in
+ * the amber tone for "dirty", the destructive tone for "invalid".
+ */
+export type DataGridCellStatus = "dirty" | "invalid"
+
+/**
+ * Asks the consumer to open its editor for the focused cell: Enter or F2, or
+ * a typed printable character (then `initialText` carries it, the
+ * Notion/Airtable type-to-replace flow). Dispatched only for cells whose
+ * column is writable via `meta.cellEdit`.
+ */
+export interface DataGridCellEditRequest<TData> {
+  rowId: string
+  columnId: string
+  row: TData
+  previousValue: unknown
+  /** The typed character that started the edit; absent for Enter and F2. */
+  initialText?: string
+}
+
+/**
+ * One batch per operation, however many cells it spans: a 10k-cell paste is
+ * one callback, one consumer setState, one table rebuild. The grid never
+ * writes data itself.
+ */
+export interface DataGridCellsChangeDetails<TData> {
+  source: DataGridCellsChangeSource
+  changes: DataGridCellChange<TData>[]
+  rejected: DataGridCellRejection[]
+}
+
+export interface DataGridProps<
+  TFeatures extends TableFeatures,
+  TData extends object,
+> {
   className?: string
-  table?: Table<TData>
+  table?: Table<TFeatures, TData>
   recordCount: number
   children?: ReactNode
   onRowClick?: (row: TData) => void
+  /**
+   * Receives every spreadsheet write batch (paste, cut, clear, fill, edit).
+   * Served through the props getter like `onRowClick`, so an inline identity
+   * never republishes the context. Absent: copy still works, writes no-op.
+   */
+  onCellsChange?: (details: DataGridCellsChangeDetails<TData>) => void
+  /**
+   * Opens the consumer's editor from the keyboard: Enter, F2, or typing on
+   * the focused cell. Absent: Enter keeps moving down, typing does nothing.
+   */
+  onCellEditRequest?: (request: DataGridCellEditRequest<TData>) => void
+  /**
+   * Fires on every cell-selection change (focus moves, ranges grow or
+   * clear) with a resolved snapshot, so a selection count, formula bar or
+   * context panel needs no reach into TanStack internals.
+   */
+  onCellSelectionChange?: (snapshot: DataGridCellSelectionSnapshot) => void
+  /**
+   * Fires after the grid writes the clipboard (Cmd/Ctrl+C or X, or the
+   * native copy and cut events), e.g. to confirm with a toast.
+   */
+  onCellsCopy?: (details: DataGridCopyDetails) => void
+  /**
+   * Renders an "Add row" affordance as the table body's last row; clicking
+   * it is the consumer's cue to start creating a row. Absent: no row.
+   */
+  onRowCreate?: () => void
+  /** Label of the onRowCreate affordance. Defaults to "Add row". */
+  rowCreateLabel?: ReactNode
+  /**
+   * Rendered inside the table body after the data rows: the slot a DRAFT
+   * row lives in while it is being created, before it joins `data` and the
+   * pagination math. Supply a `<tr>` of cells; the colgroup sizes them.
+   */
+  appendRow?: ReactNode
+  /**
+   * Optional CRUD indication per row. Return undefined for no indication;
+   * omit the prop entirely to render none anywhere.
+   */
+  getRowStatus?: (row: TData) => DataGridRowStatus | undefined
+  /**
+   * Optional CRUD indication per cell: the classic corner mark on cells the
+   * consumer tracks as edited or invalid.
+   */
+  getCellStatus?: (
+    row: TData,
+    columnId: string
+  ) => DataGridCellStatus | undefined
   isLoading?: boolean
+  /**
+   * Overrides for every built-in string: menu items, aria labels,
+   * pagination copy, state messages. Merged over the defaults; a more
+   * specific component prop (`rowCreateLabel`, `loadingMessage`, the
+   * pagination label props) still wins over its `i18n` counterpart.
+   */
+  i18n?: DataGridI18nOverrides
   loadingMode?: "skeleton" | "spinner"
   loadingMessage?: ReactNode | string
   fetchingMoreMessage?: ReactNode | string
@@ -94,6 +907,36 @@ export interface DataGridProps<TData extends object> {
     columnsDraggable?: boolean
     rowsDraggable?: boolean
     rowsPinnable?: boolean
+    /** Spreadsheet cell range selection: mouse ranges, keyboard, clipboard chrome. */
+    cellSelection?: boolean
+    /**
+     * "range" (default): drag, Shift and Ctrl/Cmd gestures and Shift+keys
+     * grow multi-cell regions. "single": one focused cell only - every
+     * gesture collapses to it and Ctrl/Cmd+A is inert.
+     */
+    cellSelectionMode?: "single" | "range"
+    /** Drag-to-fill handle on the selection corner. Requires cellSelection. */
+    cellFillHandle?: boolean
+    /**
+     * How a cell opens its editor from the mouse: "dblclick" (default,
+     * the spreadsheet standard - first click focuses, second edits) or
+     * "click", opening the editor as soon as a plain click lands on the
+     * focused cell; modifier clicks and drags still select.
+     */
+    cellEditMode?: "dblclick" | "click"
+    /**
+     * When true, committing an edit with Enter moves focus down (Shift+Enter
+     * up), the Sheets and Excel convention. Off by default: the commit keeps
+     * focus on the edited cell. Tab always commits and moves across.
+     */
+    cellEditEnterAdvance?: boolean
+    /**
+     * The handle's look: "dot" is a solid primary dot kept inside the
+     * cell corner; "ring" is the Sheets-style hollow circle riding the
+     * corner point, clamped at the grid's own boundary; "square" is the
+     * Excel-style solid square inside the corner. Default "dot".
+     */
+    cellFillHandleVariant?: "dot" | "ring" | "square"
   }
   tableClassNames?: {
     base?: string
@@ -104,6 +947,20 @@ export interface DataGridProps<TData extends object> {
     bodyRow?: string
     footer?: string
     edgeCell?: string
+    /** Override the getRowStatus tints; defaults are the warning-muted set. */
+    rowNew?: string
+    rowDirty?: string
+    rowDeleted?: string
+    /**
+     * Override the pinned-row chrome (muted tint, boundary shadow). A grid
+     * that pins a draft row for quick-create wants it to read as an active
+     * row, not a muted one.
+     */
+    rowPinned?: string
+    /** The onRowCreate affordance row, e.g. to match the grid's row height. */
+    rowCreate?: string
+    /** The fill handle, e.g. to restyle or resize it beyond the built-in variants. */
+    cellFillHandle?: string
   }
 }
 
@@ -112,80 +969,260 @@ const DataGridContext = createContext<
   DataGridContextProps<any> | undefined
 >(undefined)
 
-function useDataGrid() {
-  const context = useContext(DataGridContext)
+/**
+ * Reads the grid context. Pass `TData` from the calling component when the
+ * table, a row or a cell is handed on to something typed against that row
+ * shape: v9 declares `TData` invariant, so the default `any` no longer
+ * unifies with a concrete row type the way it did on v8.
+ */
+function useDataGrid<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TData extends object = any,
+>(): DataGridContextProps<TData> {
+  const context = useContext(DataGridContext) as
+    | DataGridContextProps<TData>
+    | undefined
   if (!context) {
     throw new Error("useDataGrid must be used within a DataGridProvider")
   }
   return context
 }
 
+type DataGridStateAtom<TValue> = {
+  get: () => TValue
+  subscribe: (listener: () => void) => { unsubscribe: () => void }
+}
+
+const noopUnsubscribe = () => {}
+
+/**
+ * Re-renders the caller when one table state atom changes, without waiting
+ * for a render from above. The context holds still while a column resize is
+ * in flight (see DataGridProvider), and React Compiler caches a consumer's
+ * `<DataGridTable />` element, so whatever a drag must keep live (the width
+ * variables, the resize line and indicator) subscribes here. `select` must
+ * return the slice itself or a primitive, or every write re-renders.
+ */
+function useDataGridAtom<TValue, TSelected = TValue | undefined>(
+  atom: DataGridStateAtom<TValue> | undefined,
+  select: (value: TValue | undefined) => TSelected = (value) =>
+    value as TSelected
+): TSelected {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (!atom) return noopUnsubscribe
+      const subscription = atom.subscribe(onChange)
+      return () => subscription.unsubscribe()
+    },
+    [atom]
+  )
+  const getSnapshot = () => select(atom?.get())
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+// Slices kept out of the inputs: cells paint cell selection through their
+// own Subscribe, and a resize drag paints through useDataGridAtom.
+const DATA_GRID_UNPUBLISHED_STATE = new Set(["cellSelection", "columnResizing"])
+
+const isDataGridPropNode = (value: unknown) =>
+  value !== null &&
+  typeof value === "object" &&
+  !Array.isArray(value) &&
+  ("$$typeof" in value || Object.getPrototypeOf(value) !== Object.prototype)
+
+// Functions and React nodes count by presence here; their identity is a
+// callback input.
+function dataGridPropsSignatureReplacer(_key: string, value: unknown) {
+  if (typeof value === "function") return "fn"
+  if (isDataGridPropNode(value)) return "node"
+  return value
+}
+
+// Inputs that always publish: every state slice but the two above, `data`
+// and `columns` (TanStack needs both stable already), and props by value.
+function getDataGridStateInputs<TData extends object>(
+  table: DataGridTableInstance<TData>,
+  props: DataGridLayoutProps<TData>,
+  autoSize: DataGridAutoSizeController
+): unknown[] {
+  const inputs: unknown[] = [
+    autoSize,
+    table.options.data,
+    table.options.columns,
+    JSON.stringify(props, dataGridPropsSignatureReplacer),
+  ]
+  for (const [key, slice] of Object.entries(table.state)) {
+    if (!DATA_GRID_UNPUBLISHED_STATE.has(key)) inputs.push(key, slice)
+  }
+  return inputs
+}
+
+// Every callback and React node prop, compared by identity.
+function getDataGridCallbackInputs<TData extends object>(
+  props: DataGridLayoutProps<TData>
+): unknown[] {
+  return Object.values(props).filter(
+    (value) => typeof value === "function" || isDataGridPropNode(value)
+  )
+}
+
+const isSameDataGridInputs = (previous: unknown[], next: unknown[]) =>
+  previous.length === next.length &&
+  next.every((input, index) => Object.is(input, previous[index]))
+
 function DataGridProvider<TData extends object>({
   children,
   table,
   ...props
-}: DataGridProps<TData> & { table: Table<TData> }) {
-  const tableState = table.getState()
-  const resolvedColumnsResizeMode =
-    props.tableLayout?.columnsResizeMode ?? "onEnd"
+}: DataGridLayoutProps<TData> & {
+  table: DataGridTableInstance<TData>
+  children?: ReactNode
+}) {
+  // Stable for the grid's lifetime; ARIA ids and relations hang off it.
+  const gridId = useId()
+  // Latest-value refs behind the context getters: a reader always gets the
+  // current props, labels and table, while the published value changes only
+  // when its inputs do (below). v9 re-creates the table on every state
+  // change, including each resize tick.
+  const propsRef = useRef(props)
+  propsRef.current = props
+  const i18n = mergeDataGridI18n(props.i18n)
+  const i18nRef = useRef(i18n)
+  i18nRef.current = i18n
+  const tableRef = useRef(table)
+  tableRef.current = table
 
-  // Keep resize mode aligned with the DataGrid contract every render so
-  // consumer-level useReactTable options cannot flip it back between drags.
-  if (props.tableLayout?.columnsResizable) {
-    table.options.columnResizeMode = resolvedColumnsResizeMode
-  }
+  // Re-assert an explicit tableLayout resize mode so consumer-level useTable
+  // options cannot flip it back between drags. v9 makes `table.options`
+  // readonly, so this goes through setOptions in an effect rather than a
+  // render-phase mutation. Without an explicit mode, the consumer's own
+  // tanstack columnResizeMode (default "onEnd") is honored.
+  const resizeMode =
+    props.tableLayout?.columnsResizable && props.tableLayout.columnsResizeMode
+      ? props.tableLayout.columnsResizeMode
+      : undefined
 
-  // Memoize context value so consumers don't re-render during column resize.
-  // Column sizing state is intentionally excluded from deps -- CSS variables
-  // on the <table> element handle width updates without React re-renders.
-  const value = useMemo(
-    () => ({
-      props,
-      table,
-      recordCount: props.recordCount,
-      isLoading: props.isLoading || false,
-    }),
+  useEffect(() => {
+    if (!resizeMode) return
+    if (table.options.columnResizeMode === resizeMode) return
+    table.setOptions((old) => ({ ...old, columnResizeMode: resizeMode }))
+  }, [table, resizeMode])
+
+  // With the selection UI on, every paste/fill/clear batch replaces `data`,
+  // and the feature's default autoResetCellSelection would wipe the selection
+  // after each write. Ranges are row-id based and unresolvable ids drop out
+  // of the bounds safely, so keeping state across data edits is the correct
+  // default here.
+  const cellSelectionOn = !!props.tableLayout?.cellSelection
+  useEffect(() => {
+    if (!cellSelectionOn || table.atoms.cellSelection == null) return
+    if (table.options.autoResetCellSelection === false) return
+    table.setOptions((old) => ({ ...old, autoResetCellSelection: false }))
+  }, [table, cellSelectionOn])
+
+  // Rendered row indexes re-base per page, so a range kept across a page flip
+  // re-lights the same positions over different rows. A page change clears
+  // the selection instead - the rule Excel-family grids apply to paginated
+  // range selection.
+  const pageKey = `${table.state.pagination?.pageIndex}:${table.state.pagination?.pageSize}`
+  const previousPageKeyRef = useRef(pageKey)
+  useEffect(() => {
+    if (previousPageKeyRef.current === pageKey) return
+    previousPageKeyRef.current = pageKey
+    if (!cellSelectionOn || table.atoms.cellSelection == null) return
+    tableRef.current.resetCellSelection(true)
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [
-      table,
-      props.recordCount,
-      props.isLoading,
-      props.loadingMode,
-      props.loadingMessage,
-      props.fetchingMoreMessage,
-      props.allRowsLoadedMessage,
-      props.emptyMessage,
-      props.onRowClick,
-      props.className,
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-      JSON.stringify(props.tableLayout),
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-      JSON.stringify(props.tableClassNames),
-      tableState.sorting,
-      tableState.pagination,
-      tableState.columnFilters,
-      tableState.rowSelection,
-      tableState.expanded,
-      tableState.columnVisibility,
-      tableState.columnOrder,
-      tableState.columnPinning,
-      tableState.globalFilter,
-    ]
+  }, [pageKey, cellSelectionOn])
+
+  // One autoSize coordinator per table instance so split header/body viewports
+  // cannot apply the growth twice. Keyed on `table.store`, which v9 keeps
+  // stable for the life of the table, rather than on `table` itself: the
+  // wrapper is re-created on every state change, and re-creating the
+  // controller with it would reset its applied-once bookkeeping mid-drag.
+  const autoSize = useMemo(
+    () => createDataGridAutoSizeController(() => tableRef.current),
+    [table.store]
   )
 
+  // A new context value re-renders every useDataGrid reader, every cell
+  // included, past any memo, and it is the only update a part gets when React
+  // Compiler cached the element above it. The grid publishes one when a state
+  // input changes. Callback inputs publish only for a consumer that memoizes
+  // its useTable options, as the compiler does: its callbacks then change
+  // only when they really change. A consumer that is not compiled builds new
+  // options and new inline callbacks on every render, re-renders the grid
+  // from above anyway, and would otherwise re-render every memoized virtual
+  // row. Not the children's identity: the compiler caches the elements
+  // inside children separately, so fresh children can wrap a cached table.
+  // While a column resize is in flight the value holds still: the drag's own
+  // visuals subscribe through useDataGridAtom, and the render after it
+  // publishes what it changed.
+  const committedOptionsRef = useRef(table.options)
+  const hasMemoizedOptions = committedOptionsRef.current === table.options
+  useLayoutEffect(() => {
+    committedOptionsRef.current = table.options
+  })
+  const isResizing = !!table.state.columnResizing?.isResizingColumn
+  const publishedRef = useRef<{
+    stateInputs: unknown[]
+    callbackInputs: unknown[]
+    value: DataGridContextProps<TData>
+  } | null>(null)
+  let published = publishedRef.current
+  if (!published || !isResizing) {
+    const stateInputs = getDataGridStateInputs(table, props, autoSize)
+    const callbackInputs = getDataGridCallbackInputs(props)
+    const stateChanged =
+      !published || !isSameDataGridInputs(published.stateInputs, stateInputs)
+    const callbacksChanged =
+      !published ||
+      !isSameDataGridInputs(published.callbackInputs, callbackInputs)
+    if (published && !stateChanged && callbacksChanged && !hasMemoizedOptions) {
+      published.callbackInputs = callbackInputs
+    } else if (stateChanged || callbacksChanged) {
+      published = {
+        stateInputs,
+        callbackInputs,
+        value: {
+          get props() {
+            return propsRef.current
+          },
+          get table() {
+            return tableRef.current
+          },
+          get i18n() {
+            return i18nRef.current
+          },
+          recordCount: props.recordCount,
+          isLoading: props.isLoading || false,
+          gridId,
+          autoSize,
+        },
+      }
+      publishedRef.current = published
+    }
+  }
+  const value = published!.value
+
   return (
-    <DataGridContext.Provider value={value}>
+    // One React context serves every TData, but v9 declares both TFeatures and
+    // TData invariant, so a `DataGridContextProps<any>` context cannot accept a
+    // `DataGridContextProps<TData>` value structurally. The erasure happens
+    // here and is undone by the TData generic on each consumer component.
+    <DataGridContext.Provider
+      value={value as unknown as DataGridContextProps<TData>}
+    >
       {children}
     </DataGridContext.Provider>
   )
 }
 
-function DataGrid<TData extends object>({
+function DataGrid<TFeatures extends TableFeatures, TData extends object>({
   children,
   table,
   ...props
-}: DataGridProps<TData>) {
-  const defaultProps: Partial<DataGridProps<TData>> = {
+}: DataGridProps<TFeatures, TData>) {
+  const defaultProps: Partial<DataGridProps<TFeatures, TData>> = {
     loadingMode: "skeleton",
     tableLayout: {
       dense: false,
@@ -200,18 +1237,24 @@ function DataGrid<TData extends object>({
       width: "fixed",
       columnsVisibility: false,
       columnsResizable: false,
-      columnsResizeMode: "onEnd",
+      // columnsResizeMode has no default on purpose: when unset, the
+      // consumer's tanstack columnResizeMode (default "onEnd") is honored.
       columnsPinnable: false,
       columnsMovable: false,
       columnsDraggable: false,
       rowsDraggable: false,
       rowsPinnable: false,
+      cellSelection: false,
+      cellFillHandle: false,
     },
     tableClassNames: {
       base: "",
       header: "",
       headerRow: "",
-      headerSticky: "sticky top-0 z-15 bg-background/90 backdrop-blur-xs",
+      // z-40 keeps the sticky header above pinned body cells (zIndex 30 in
+      // getPinningStyles), which would otherwise paint over it while
+      // scrolling vertically with columnsPinnable enabled.
+      headerSticky: "sticky top-0 z-40 bg-background/90 backdrop-blur-xs",
       body: "",
       bodyRow: "",
       footer: "",
@@ -219,7 +1262,7 @@ function DataGrid<TData extends object>({
     },
   }
 
-  const mergedProps: DataGridProps<TData> = {
+  const mergedProps: DataGridProps<TFeatures, TData> = {
     ...defaultProps,
     ...props,
     tableLayout: {
@@ -237,8 +1280,15 @@ function DataGrid<TData extends object>({
     throw new Error('DataGrid requires a "table" prop')
   }
 
+  // The single widening point. Consumers own the TanStack core and may hand
+  // over any feature bundle; internals need a concrete one to resolve the
+  // feature-gated APIs they call, and v9's invariant TFeatures rules out
+  // expressing that with a generic constraint.
+  const internalTable = table as unknown as DataGridTableInstance<TData>
+  const internalProps = mergedProps as unknown as DataGridLayoutProps<TData>
+
   return (
-    <DataGridProvider table={table} {...mergedProps}>
+    <DataGridProvider table={internalTable} {...internalProps}>
       {children}
     </DataGridProvider>
   )
@@ -247,20 +1297,28 @@ function DataGrid<TData extends object>({
 function DataGridContainer({
   children,
   className,
-  border: _border = true,
 }: {
   children: ReactNode
   className?: string
+  /** Accepted for backwards compatibility; currently has no effect. */
   border?: boolean
 }) {
   return (
     <div
       data-slot="data-grid"
-      className={cn("w-full overflow-hidden", className)}
+      // relative: anchors floating chrome composed inside the container,
+      // like the fill-drag preview outline.
+      className={cn("relative w-full overflow-hidden", className)}
     >
       {children}
     </div>
   )
 }
 
-export { useDataGrid, DataGridProvider, DataGrid, DataGridContainer }
\ No newline at end of file
+export {
+  useDataGrid,
+  useDataGridAtom,
+  DataGridProvider,
+  DataGrid,
+  DataGridContainer,
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters.tsx b/apps/web/src/components/reui/filters.tsx
deleted file mode 100644
index 88ec851..0000000
--- a/apps/web/src/components/reui/filters.tsx
+++ /dev/null
@@ -1,1927 +0,0 @@
-"use client"
-
-import type React from "react"
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useId,
-  useMemo,
-  useRef,
-  useState,
-} from "react"
-import { useRender } from "@base-ui/react/use-render"
-import { cva } from "class-variance-authority"
-
-import { cn } from "@authportal/ui/lib/utils"
-import { Button } from "@authportal/ui/components/button"
-import {
-  ButtonGroup,
-  ButtonGroupText,
-} from "@authportal/ui/components/button-group"
-import {
-  DropdownMenu,
-  DropdownMenuCheckboxItem,
-  DropdownMenuContent,
-  DropdownMenuGroup,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-  DropdownMenuSub,
-  DropdownMenuSubContent,
-  DropdownMenuSubTrigger,
-  DropdownMenuTrigger,
-} from "@authportal/ui/components/dropdown-menu"
-import { Input } from "@authportal/ui/components/input"
-import {
-  InputGroup,
-  InputGroupAddon,
-  InputGroupButton,
-  InputGroupInput,
-  InputGroupText,
-} from "@authportal/ui/components/input-group"
-import { Kbd } from "@authportal/ui/components/kbd"
-import { ScrollArea } from "@authportal/ui/components/scroll-area"
-import {
-  Tooltip,
-  TooltipContent,
-  TooltipTrigger,
-} from "@authportal/ui/components/tooltip"
-import { AlertCircleIcon, XIcon, CheckIcon } from "lucide-react"
-
-// i18n Configuration Interface
-export interface FilterI18nConfig {
-  // UI Labels
-  addFilter: string
-  searchFields: string
-  noFieldsFound: string
-  noResultsFound: string
-  select: string
-  true: string
-  false: string
-  min: string
-  max: string
-  to: string
-  typeAndPressEnter: string
-  selected: string
-  selectedCount: string
-  percent: string
-  defaultCurrency: string
-  defaultColor: string
-  addFilterTitle: string
-
-  // Operators
-  operators: {
-    is: string
-    isNot: string
-    isAnyOf: string
-    isNotAnyOf: string
-    includesAll: string
-    excludesAll: string
-    before: string
-    after: string
-    between: string
-    notBetween: string
-    contains: string
-    notContains: string
-    startsWith: string
-    endsWith: string
-    isExactly: string
-    equals: string
-    notEquals: string
-    greaterThan: string
-    lessThan: string
-    overlaps: string
-    includes: string
-    excludes: string
-    includesAllOf: string
-    includesAnyOf: string
-    empty: string
-    notEmpty: string
-  }
-
-  // Placeholders
-  placeholders: {
-    enterField: (fieldType: string) => string
-    selectField: string
-    searchField: (fieldName: string) => string
-    enterKey: string
-    enterValue: string
-  }
-
-  // Helper functions
-  helpers: {
-    formatOperator: (operator: string) => string
-  }
-
-  // Validation
-  validation: {
-    invalidEmail: string
-    invalidUrl: string
-    invalidTel: string
-    invalid: string
-  }
-}
-
-// Default English i18n configuration
-export const DEFAULT_I18N: FilterI18nConfig = {
-  // UI Labels
-  addFilter: "Filter",
-  searchFields: "Filter...",
-  noFieldsFound: "No filters found.",
-  noResultsFound: "No results found.",
-  select: "Select...",
-  true: "True",
-  false: "False",
-  min: "Min",
-  max: "Max",
-  to: "to",
-  typeAndPressEnter: "Type and press Enter to add tag",
-  selected: "selected",
-  selectedCount: "selected",
-  percent: "%",
-  defaultCurrency: "$",
-  defaultColor: "#000000",
-  addFilterTitle: "Add filter",
-
-  // Operators
-  operators: {
-    is: "is",
-    isNot: "is not",
-    isAnyOf: "is any of",
-    isNotAnyOf: "is not any of",
-    includesAll: "includes all",
-    excludesAll: "excludes all",
-    before: "before",
-    after: "after",
-    between: "between",
-    notBetween: "not between",
-    contains: "contains",
-    notContains: "does not contain",
-    startsWith: "starts with",
-    endsWith: "ends with",
-    isExactly: "is exactly",
-    equals: "equals",
-    notEquals: "not equals",
-    greaterThan: "greater than",
-    lessThan: "less than",
-    overlaps: "overlaps",
-    includes: "includes",
-    excludes: "excludes",
-    includesAllOf: "includes all of",
-    includesAnyOf: "includes any of",
-    empty: "is empty",
-    notEmpty: "is not empty",
-  },
-
-  // Placeholders
-  placeholders: {
-    enterField: (fieldType: string) => `Enter ${fieldType}...`,
-    selectField: "Select...",
-    searchField: (fieldName: string) => `Search ${fieldName.toLowerCase()}...`,
-    enterKey: "Enter key...",
-    enterValue: "Enter value...",
-  },
-
-  // Helper functions
-  helpers: {
-    formatOperator: (operator: string) => operator.replace(/_/g, " "),
-  },
-
-  // Validation
-  validation: {
-    invalidEmail: "Invalid email format",
-    invalidUrl: "Invalid URL format",
-    invalidTel: "Invalid phone format",
-    invalid: "Invalid input format",
-  },
-}
-
-// Context for all Filter component props
-interface FilterContextValue {
-  variant: "solid" | "default"
-  size: "sm" | "default" | "lg"
-  radius: "default" | "full"
-  i18n: FilterI18nConfig
-  className?: string
-  showSearchInput?: boolean
-  trigger?: React.ReactNode
-  allowMultiple?: boolean
-}
-
-const FilterContext = createContext<FilterContextValue>({
-  variant: "default",
-  size: "default",
-  radius: "default",
-  i18n: DEFAULT_I18N,
-  className: undefined,
-  showSearchInput: true,
-  trigger: undefined,
-  allowMultiple: true,
-})
-
-const useFilterContext = () => useContext(FilterContext)
-
-// Container variant for filters wrapper
-const filtersContainerVariants = cva("flex flex-wrap items-center", {
-  variants: {
-    variant: {
-      solid: "gap-2",
-      default: "",
-    },
-    size: {
-      sm: "gap-1.5",
-      default: "gap-2.5",
-      lg: "gap-3.5",
-    },
-  },
-  defaultVariants: {
-    variant: "default",
-    size: "default",
-  },
-})
-
-function FilterInput<T = unknown>({
-  field,
-  onBlur,
-  onKeyDown,
-  className,
-  ...props
-}: React.InputHTMLAttributes<HTMLInputElement> & {
-  className?: string
-  field?: FilterFieldConfig<T>
-}) {
-  const context = useFilterContext()
-  const [isValid, setIsValid] = useState(true)
-  const [validationMessage, setValidationMessage] = useState("")
-  const inputRef = useRef<HTMLInputElement>(null)
-
-  useEffect(() => {
-    if (props.autoFocus) {
-      const timer = setTimeout(() => {
-        inputRef.current?.focus()
-      }, 300)
-      return () => clearTimeout(timer)
-    }
-  }, [props.autoFocus])
-
-  // Validation function to check if input matches pattern
-  const validateInput = (value: string, pattern?: string): boolean => {
-    if (!pattern || !value) return true
-    const regex = new RegExp(pattern)
-    return regex.test(value)
-  }
-
-  // Get validation message for field type
-  const getValidationMessage = (): string => {
-    return context.i18n.validation.invalid
-  }
-
-  // Handle blur event - validate when user leaves input
-  const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
-    const value = e.target.value
-    const pattern = field?.pattern || props.pattern
-
-    // Only validate if there's a value and (pattern or validation function)
-    if (value && (pattern || field?.validation)) {
-      let valid = true
-      let customMessage = ""
-
-      // If there's a custom validation function, use it
-      if (field?.validation) {
-        const result = field.validation(value)
-        // Handle both boolean and object return types
-        if (typeof result === "boolean") {
-          valid = result
-        } else {
-          valid = result.valid
-          customMessage = result.message || ""
-        }
-      } else if (pattern) {
-        // Use pattern validation
-        valid = validateInput(value, pattern)
-      }
-
-      setIsValid(valid)
-      setValidationMessage(valid ? "" : customMessage || getValidationMessage())
-    } else {
-      // Reset validation state for empty values or no validation
-      setIsValid(true)
-      setValidationMessage("")
-    }
-
-    // Call the original onBlur if provided
-    onBlur?.(e)
-  }
-
-  // Handle keydown event - hide validation error when user starts typing
-  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
-    // Hide validation error when user starts typing (any key except special keys)
-    if (
-      !isValid &&
-      ![
-        "Tab",
-        "Escape",
-        "Enter",
-        "ArrowUp",
-        "ArrowDown",
-        "ArrowLeft",
-        "ArrowRight",
-      ].includes(e.key)
-    ) {
-      setIsValid(true)
-      setValidationMessage("")
-    }
-
-    // Call the original onKeyDown if provided
-    onKeyDown?.(e)
-  }
-
-  return (
-    <InputGroup
-      className={cn(
-        "w-36",
-        context.size == "sm" &&
-          "h-7!",
-        context.size == "default" &&
-          "h-8!",
-        context.size == "lg" &&
-          "h-9!",
-        className
-      )}
-    >
-      {field?.prefix && (
-        <InputGroupAddon>
-          <InputGroupText>{field.prefix}</InputGroupText>
-        </InputGroupAddon>
-      )}
-      <InputGroupInput
-        ref={inputRef}
-        aria-invalid={!isValid}
-        aria-describedby={
-          !isValid && validationMessage
-            ? `${field?.key || "input"}-error`
-            : undefined
-        }
-        onBlur={handleBlur}
-        onKeyDown={handleKeyDown}
-        className={cn(
-          context.size == "sm" &&
-            "h-7! text-xs",
-          context.size == "default" &&
-            "h-8!",
-          context.size == "lg" &&
-            "h-9!"
-        )}
-        {...props}
-      />
-      {!isValid && validationMessage && (
-        <InputGroupAddon align="inline-end">
-          <Tooltip>
-            <TooltipTrigger render={<InputGroupButton size="icon-xs" />}>
-              <AlertCircleIcon className="text-destructive size-3.5" />
-            </TooltipTrigger>
-            <TooltipContent>
-              <p className="text-sm">{validationMessage}</p>
-            </TooltipContent>
-          </Tooltip>
-        </InputGroupAddon>
-      )}
-
-      {field?.suffix && (
-        <InputGroupAddon align="inline-end">
-          <InputGroupText>{field.suffix}</InputGroupText>
-        </InputGroupAddon>
-      )}
-    </InputGroup>
-  )
-}
-
-interface FilterRemoveButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  icon?: React.ReactNode
-}
-
-function FilterRemoveButton({
-  className,
-  icon = (
-    <XIcon
-    />
-  ),
-  ...props
-}: FilterRemoveButtonProps) {
-  const context = useFilterContext()
-
-  return (
-    <Button
-      variant="outline"
-      size={
-        context.size === "sm"
-          ? "icon-sm"
-          : context.size === "lg"
-            ? "icon-lg"
-            : "icon"
-      }
-      className={className}
-      {...props}
-    >
-      {icon}
-    </Button>
-  )
-}
-
-// Generic types for flexible filter system
-export interface FilterOption<T = unknown> {
-  value: T
-  label: string
-  icon?: React.ReactNode
-  metadata?: Record<string, unknown>
-  className?: string
-}
-
-export interface FilterOperator {
-  value: string
-  label: string
-  supportsMultiple?: boolean
-}
-
-// Custom renderer props interface
-export interface CustomRendererProps<T = unknown> {
-  field: FilterFieldConfig<T>
-  values: T[]
-  onChange: (values: T[]) => void
-  operator: string
-}
-
-// Grouped field configuration interface
-export interface FilterFieldGroup<T = unknown> {
-  group?: string
-  fields: FilterFieldConfig<T>[]
-}
-
-// Union type for both flat and grouped field configurations
-export type FilterFieldsConfig<T = unknown> =
-  | FilterFieldConfig<T>[]
-  | FilterFieldGroup<T>[]
-
-export interface FilterFieldConfig<T = unknown> {
-  key?: string
-  label?: string
-  icon?: React.ReactNode
-  type?: "select" | "multiselect" | "text" | "custom" | "separator"
-  // Group-level configuration
-  group?: string
-  fields?: FilterFieldConfig<T>[]
-  // Field-specific options
-  options?: FilterOption<T>[]
-  operators?: FilterOperator[]
-  customRenderer?: (props: CustomRendererProps<T>) => React.ReactNode
-  customValueRenderer?: (
-    values: T[],
-    options: FilterOption<T>[]
-  ) => React.ReactNode
-  placeholder?: string
-  searchable?: boolean
-  maxSelections?: number
-  min?: number
-  max?: number
-  step?: number
-  prefix?: string | React.ReactNode
-  suffix?: string | React.ReactNode
-  pattern?: string
-  validation?: (
-    value: unknown
-  ) => boolean | { valid: boolean; message?: string }
-  allowCustomValues?: boolean
-  className?: string
-  menuPopupClassName?: string
-  // Grouping options (legacy support)
-  groupLabel?: string
-  // Boolean field options
-  onLabel?: string
-  offLabel?: string
-  // Input event handlers
-  onInputChange?: (e: React.ChangeEvent<HTMLInputElement>) => void
-  // Default operator to use when creating a filter for this field
-  defaultOperator?: string
-  // Controlled values support for this field
-  value?: T[]
-  onValueChange?: (values: T[]) => void
-}
-
-// Helper functions to handle both flat and grouped field configurations
-const isFieldGroup = <T = unknown,>(
-  item: FilterFieldConfig<T> | FilterFieldGroup<T>
-): item is FilterFieldGroup<T> => {
-  return "fields" in item && Array.isArray(item.fields)
-}
-
-// Helper function to check if a FilterFieldConfig is a group-level configuration
-const isGroupLevelField = <T = unknown,>(
-  field: FilterFieldConfig<T>
-): boolean => {
-  return Boolean(field.group && field.fields)
-}
-
-const flattenFields = <T = unknown,>(
-  fields: FilterFieldsConfig<T>
-): FilterFieldConfig<T>[] => {
-  return fields.reduce<FilterFieldConfig<T>[]>((acc, item) => {
-    if (isFieldGroup(item)) {
-      return [...acc, ...item.fields]
-    }
-    // Handle group-level fields (new structure)
-    if (isGroupLevelField(item)) {
-      return [...acc, ...item.fields!]
-    }
-    return [...acc, item]
-  }, [])
-}
-
-const getFieldsMap = <T = unknown,>(
-  fields: FilterFieldsConfig<T>
-): Record<string, FilterFieldConfig<T>> => {
-  const flatFields = flattenFields(fields)
-  return flatFields.reduce(
-    (acc, field) => {
-      // Only add fields that have a key (skip group-level configurations)
-      if (field.key) {
-        acc[field.key] = field
-      }
-      return acc
-    },
-    {} as Record<string, FilterFieldConfig<T>>
-  )
-}
-
-// Helper function to create operators from i18n config
-const createOperatorsFromI18n = (
-  i18n: FilterI18nConfig
-): Record<string, FilterOperator[]> => ({
-  select: [
-    { value: "is", label: i18n.operators.is },
-    { value: "is_not", label: i18n.operators.isNot },
-    { value: "empty", label: i18n.operators.empty },
-    { value: "not_empty", label: i18n.operators.notEmpty },
-  ],
-  multiselect: [
-    { value: "is_any_of", label: i18n.operators.isAnyOf },
-    { value: "is_not_any_of", label: i18n.operators.isNotAnyOf },
-    { value: "includes_all", label: i18n.operators.includesAll },
-    { value: "excludes_all", label: i18n.operators.excludesAll },
-    { value: "empty", label: i18n.operators.empty },
-    { value: "not_empty", label: i18n.operators.notEmpty },
-  ],
-  text: [
-    { value: "contains", label: i18n.operators.contains },
-    { value: "not_contains", label: i18n.operators.notContains },
-    { value: "starts_with", label: i18n.operators.startsWith },
-    { value: "ends_with", label: i18n.operators.endsWith },
-    { value: "is", label: i18n.operators.isExactly },
-    { value: "empty", label: i18n.operators.empty },
-    { value: "not_empty", label: i18n.operators.notEmpty },
-  ],
-  custom: [
-    { value: "is", label: i18n.operators.is },
-    { value: "after", label: i18n.operators.after },
-    { value: "is", label: i18n.operators.is },
-    { value: "between", label: i18n.operators.between },
-    { value: "empty", label: i18n.operators.empty },
-    { value: "not_empty", label: i18n.operators.notEmpty },
-  ],
-})
-
-// Default operators for different field types (using default i18n)
-export const DEFAULT_OPERATORS: Record<string, FilterOperator[]> =
-  createOperatorsFromI18n(DEFAULT_I18N)
-
-// Helper function to get operators for a field
-const getOperatorsForField = <T = unknown,>(
-  field: FilterFieldConfig<T>,
-  values: T[],
-  i18n: FilterI18nConfig
-): FilterOperator[] => {
-  if (field.operators) return field.operators
-
-  const operators = createOperatorsFromI18n(i18n)
-
-  // Determine field type for operator selection
-  let fieldType = field.type || "select"
-
-  // If it's a select field but has multiple values, treat as multiselect
-  if (fieldType === "select" && values.length > 1) {
-    fieldType = "multiselect"
-  }
-
-  // If it's a multiselect field or has multiselect operators, use multiselect operators
-  if (fieldType === "multiselect" || field.type === "multiselect") {
-    return operators.multiselect
-  }
-
-  return operators[fieldType] || operators.select
-}
-
-interface FilterOperatorDropdownProps<T = unknown> {
-  field: FilterFieldConfig<T>
-  operator: string
-  values: T[]
-  onChange: (operator: string) => void
-}
-
-function FilterOperatorDropdown<T = unknown>({
-  field,
-  operator,
-  values,
-  onChange,
-}: FilterOperatorDropdownProps<T>) {
-  const context = useFilterContext()
-  const operators = getOperatorsForField(field, values, context.i18n)
-
-  // Find the operator label, with fallback to formatted operator name
-  const operatorLabel =
-    operators.find((op) => op.value === operator)?.label ||
-    context.i18n.helpers.formatOperator(operator)
-
-  return (
-    <DropdownMenu>
-      <DropdownMenuTrigger
-        render={
-          <Button
-            variant="outline"
-            size={context.size}
-            className="text-muted-foreground hover:text-foreground"
-          >
-            {operatorLabel}
-          </Button>
-        }
-      />
-      <DropdownMenuContent align="start" className="w-fit min-w-fit">
-        {operators.map((op) => (
-          <DropdownMenuItem
-            key={op.value}
-            onClick={() => onChange(op.value)}
-            className={cn(
-              "data-highlighted:bg-accent data-highlighted:text-accent-foreground flex items-center justify-between"
-            )}
-          >
-            <span>{op.label}</span>
-            <CheckIcon className={cn(
-                                "text-primary ms-auto",
-                                op.value === operator ? "opacity-100" : "opacity-0"
-                              )} />
-          </DropdownMenuItem>
-        ))}
-      </DropdownMenuContent>
-    </DropdownMenu>
-  )
-}
-
-interface FilterValueSelectorProps<T = unknown> {
-  field: FilterFieldConfig<T>
-  values: T[]
-  onChange: (values: T[]) => void
-  operator: string
-  autoFocus?: boolean
-}
-
-interface SelectOptionsPopoverProps<T = unknown> {
-  field: FilterFieldConfig<T>
-  values: T[]
-  onChange: (values: T[]) => void
-  onClose?: () => void
-  inline?: boolean
-}
-
-function SelectOptionsPopover<T = unknown>({
-  field,
-  values,
-  onChange,
-  onClose,
-  inline = false,
-}: SelectOptionsPopoverProps<T>) {
-  const [open, setOpen] = useState(false)
-  const [searchInput, setSearchInput] = useState("")
-  const [highlightedIndex, setHighlightedIndex] = useState(-1)
-  const inputRef = useRef<HTMLInputElement>(null)
-  const context = useFilterContext()
-  const baseId = useId()
-
-  useEffect(() => {
-    if (open) {
-      inputRef.current?.focus()
-    }
-  }, [open])
-
-  useEffect(() => {
-    setHighlightedIndex(-1)
-  }, [searchInput, open])
-
-  useEffect(() => {
-    if (highlightedIndex >= 0 && open) {
-      const element = document.getElementById(
-        `${baseId}-item-${highlightedIndex}`
-      )
-      element?.scrollIntoView({ block: "nearest" })
-    }
-  }, [highlightedIndex, open, baseId])
-
-  const isMultiSelect = field.type === "multiselect" || values.length > 1
-  const effectiveValues =
-    (field.value !== undefined ? (field.value as T[]) : values) || []
-
-  const selectedOptions =
-    field.options?.filter((opt) => effectiveValues.includes(opt.value)) || []
-  const unselectedOptions =
-    field.options?.filter((opt) => !effectiveValues.includes(opt.value)) || []
-
-  // Filter options based on search input
-  const filteredSelectedOptions = selectedOptions // Keep all selected visible
-  const filteredUnselectedOptions = unselectedOptions.filter((opt) =>
-    opt.label.toLowerCase().includes(searchInput.toLowerCase())
-  )
-
-  const allFilteredOptions = useMemo(
-    () => [...filteredSelectedOptions, ...filteredUnselectedOptions],
-    [filteredSelectedOptions, filteredUnselectedOptions]
-  )
-
-  const handleClose = () => {
-    setOpen(false)
-    onClose?.()
-  }
-
-  const renderMenuContent = () => (
-    <>
-      {field.searchable !== false && (
-        <>
-          <Input
-            ref={inputRef}
-            role="combobox"
-            aria-autocomplete="list"
-            aria-expanded={true}
-            aria-haspopup="listbox"
-            aria-controls={`${baseId}-listbox`}
-            aria-activedescendant={
-              highlightedIndex >= 0
-                ? `${baseId}-item-${highlightedIndex}`
-                : undefined
-            }
-            placeholder={context.i18n.placeholders.searchField(
-              field.label || ""
-            )}
-            className={cn(
-              "border-input h-8 rounded-none border-0 bg-transparent! px-2 text-sm shadow-none",
-              "focus-visible:border-border focus-visible:ring-0 focus-visible:ring-offset-0",
-              open && "placeholder:text-foreground"
-            )}
-            value={searchInput}
-            onChange={(e) => setSearchInput(e.target.value)}
-            onBlur={() => open && inputRef.current?.focus()}
-            onClick={(e) => e.stopPropagation()}
-            onKeyDown={(e) => {
-              if (e.key === "ArrowDown") {
-                e.preventDefault()
-                if (allFilteredOptions.length > 0) {
-                  setHighlightedIndex((prev) =>
-                    prev < allFilteredOptions.length - 1 ? prev + 1 : 0
-                  )
-                }
-              } else if (e.key === "ArrowUp") {
-                e.preventDefault()
-                if (allFilteredOptions.length > 0) {
-                  setHighlightedIndex((prev) =>
-                    prev > 0 ? prev - 1 : allFilteredOptions.length - 1
-                  )
-                }
-              } else if (e.key === "ArrowLeft") {
-                e.preventDefault()
-                setOpen(false)
-              } else if (e.key === "Enter" && highlightedIndex >= 0) {
-                e.preventDefault()
-                const option = allFilteredOptions[highlightedIndex]
-                if (option) {
-                  const isSelected = effectiveValues.includes(option.value as T)
-                  const next = isSelected
-                    ? (effectiveValues.filter((v) => v !== option.value) as T[])
-                    : isMultiSelect
-                      ? ([...effectiveValues, option.value] as T[])
-                      : ([option.value] as T[])
-
-                  if (
-                    !isSelected &&
-                    isMultiSelect &&
-                    field.maxSelections &&
-                    next.length > field.maxSelections
-                  ) {
-                    return
-                  }
-
-                  if (field.onValueChange) {
-                    field.onValueChange(next)
-                  } else {
-                    onChange(next)
-                  }
-                  if (!isMultiSelect) handleClose()
-                }
-              }
-              e.stopPropagation()
-            }}
-          />
-          <DropdownMenuSeparator />
-        </>
-      )}
-      <div className="relative flex max-h-full">
-        <div
-          className="flex max-h-[min(var(--available-height),24rem)] w-full scroll-pt-2 scroll-pb-2 flex-col overscroll-contain"
-          role="listbox"
-          id={`${baseId}-listbox`}
-        >
-          <ScrollArea className="size-full min-h-0 **:data-[slot=scroll-area-scrollbar]:m-0 [&_[data-slot=scroll-area-viewport]]:h-full [&_[data-slot=scroll-area-viewport]]:overscroll-contain">
-            {allFilteredOptions.length === 0 && (
-              <div className="text-muted-foreground py-2 text-center text-sm">
-                {context.i18n.noResultsFound}
-              </div>
-            )}
-
-            {/* Selected items */}
-            {filteredSelectedOptions.length > 0 && (
-              <DropdownMenuGroup className="px-1">
-                {filteredSelectedOptions.map((option, index) => {
-                  const isHighlighted = highlightedIndex === index
-                  const itemId = `${baseId}-item-${index}`
-
-                  return (
-                    <DropdownMenuCheckboxItem
-                      key={String(option.value)}
-                      id={itemId}
-                      role="option"
-                      aria-selected={isHighlighted}
-                      data-highlighted={isHighlighted || undefined}
-                      onMouseEnter={() => setHighlightedIndex(index)}
-                      checked={true}
-                      className={cn(
-                        "data-highlighted:bg-accent data-highlighted:text-accent-foreground",
-                        option.className
-                      )}
-                      onSelect={(e) => {
-                        if (isMultiSelect) e.preventDefault()
-                      }}
-                      onCheckedChange={() => {
-                        const next = effectiveValues.filter(
-                          (v) => v !== option.value
-                        ) as T[]
-                        if (field.onValueChange) {
-                          field.onValueChange(next)
-                        } else {
-                          onChange(next)
-                        }
-                        if (!isMultiSelect) handleClose()
-                      }}
-                    >
-                      {option.icon && option.icon}
-                      <span className="truncate">{option.label}</span>
-                    </DropdownMenuCheckboxItem>
-                  )
-                })}
-              </DropdownMenuGroup>
-            )}
-
-            {/* Separator */}
-            {filteredSelectedOptions.length > 0 &&
-              filteredUnselectedOptions.length > 0 && (
-                <DropdownMenuSeparator className="mx-0" />
-              )}
-
-            {/* Available items */}
-            {filteredUnselectedOptions.length > 0 && (
-              <DropdownMenuGroup className="px-1">
-                {filteredUnselectedOptions.map((option, index) => {
-                  const overallIndex = index + filteredSelectedOptions.length
-                  const isHighlighted = highlightedIndex === overallIndex
-                  const itemId = `${baseId}-item-${overallIndex}`
-
-                  return (
-                    <DropdownMenuCheckboxItem
-                      key={String(option.value)}
-                      id={itemId}
-                      role="option"
-                      aria-selected={isHighlighted}
-                      data-highlighted={isHighlighted || undefined}
-                      onMouseEnter={() => setHighlightedIndex(overallIndex)}
-                      checked={false}
-                      className={cn(
-                        "data-highlighted:bg-accent data-highlighted:text-accent-foreground",
-                        option.className
-                      )}
-                      onSelect={(e) => {
-                        if (isMultiSelect) e.preventDefault()
-                      }}
-                      onCheckedChange={() => {
-                        const next = isMultiSelect
-                          ? ([...effectiveValues, option.value] as T[])
-                          : ([option.value] as T[])
-
-                        if (
-                          isMultiSelect &&
-                          field.maxSelections &&
-                          next.length > field.maxSelections
-                        ) {
-                          return
-                        }
-
-                        if (field.onValueChange) {
-                          field.onValueChange(next)
-                        } else {
-                          onChange(next)
-                        }
-                        if (!isMultiSelect) handleClose()
-                      }}
-                    >
-                      {option.icon && option.icon}
-                      <span className="truncate">{option.label}</span>
-                    </DropdownMenuCheckboxItem>
-                  )
-                })}
-              </DropdownMenuGroup>
-            )}
-          </ScrollArea>
-        </div>
-      </div>
-    </>
-  )
-
-  if (inline) {
-    return <div className="w-full">{renderMenuContent()}</div>
-  }
-
-  return (
-    <DropdownMenu
-      open={open}
-      onOpenChange={(open) => {
-        setOpen(open)
-        if (!open) {
-          setTimeout(() => setSearchInput(""), 200)
-        }
-      }}
-    >
-      <DropdownMenuTrigger
-        render={
-          <Button variant="outline" size={context.size}>
-            <div className="flex items-center gap-1.5">
-              {field.customValueRenderer ? (
-                field.customValueRenderer(values, field.options || [])
-              ) : (
-                <>
-                  {selectedOptions.length > 0 && (
-                    <div className="flex items-center -space-x-1.5">
-                      {selectedOptions.slice(0, 3).map((option) => (
-                        <div key={String(option.value)}>{option.icon}</div>
-                      ))}
-                    </div>
-                  )}
-                  {selectedOptions.length === 1
-                    ? selectedOptions[0].label
-                    : selectedOptions.length > 1
-                      ? `${selectedOptions.length} ${context.i18n.selectedCount}`
-                      : context.i18n.select}
-                </>
-              )}
-            </div>
-          </Button>
-        }
-      />
-      <DropdownMenuContent
-        align="start"
-        className={cn("w-[200px] px-0", field.className)}
-      >
-        {renderMenuContent()}
-      </DropdownMenuContent>
-    </DropdownMenu>
-  )
-}
-
-function FilterValueSelector<T = unknown>({
-  field,
-  values,
-  onChange,
-  operator,
-  autoFocus,
-}: FilterValueSelectorProps<T>) {
-  if (operator === "empty" || operator === "not_empty") {
-    return null
-  }
-
-  if (field.customRenderer) {
-    return (
-      <ButtonGroupText className="hover:bg-accent aria-expanded:bg-accent bg-background dark:bg-input/30 text-start whitespace-nowrap outline-hidden">
-        {field.customRenderer({ field, values, onChange, operator })}
-      </ButtonGroupText>
-    )
-  }
-
-  if (field.type === "text") {
-    return (
-      <FilterInput
-        type="text"
-        value={(values[0] as string) || ""}
-        onChange={(e) => onChange([e.target.value] as T[])}
-        placeholder={field.placeholder}
-        pattern={field.pattern}
-        field={field}
-        className={cn("w-36", field.className)}
-        autoFocus={autoFocus}
-      />
-    )
-  }
-
-  if (field.type === "select" || field.type === "multiselect") {
-    return (
-      <SelectOptionsPopover field={field} values={values} onChange={onChange} />
-    )
-  }
-
-  return (
-    <SelectOptionsPopover field={field} values={values} onChange={onChange} />
-  )
-}
-export interface Filter<T = unknown> {
-  id: string
-  field: string
-  operator: string
-  values: T[]
-}
-
-export interface FilterGroup<T = unknown> {
-  id: string
-  label?: string
-  filters: Filter<T>[]
-  fields: FilterFieldConfig<T>[]
-}
-
-interface FiltersContentProps<T = unknown> {
-  filters: Filter<T>[]
-  fields: FilterFieldsConfig<T>
-  onChange: (filters: Filter<T>[]) => void
-}
-
-export const FiltersContent = <T = unknown,>({
-  filters,
-  fields,
-  onChange,
-}: FiltersContentProps<T>) => {
-  const context = useFilterContext()
-  const fieldsMap = useMemo(() => getFieldsMap(fields), [fields])
-
-  const updateFilter = useCallback(
-    (filterId: string, updates: Partial<Filter<T>>) => {
-      onChange(
-        filters.map((filter) => {
-          if (filter.id === filterId) {
-            const updatedFilter = { ...filter, ...updates }
-            if (
-              updates.operator === "empty" ||
-              updates.operator === "not_empty"
-            ) {
-              updatedFilter.values = [] as T[]
-            }
-            return updatedFilter
-          }
-          return filter
-        })
-      )
-    },
-    [filters, onChange]
-  )
-
-  const removeFilter = useCallback(
-    (filterId: string) => {
-      onChange(filters.filter((filter) => filter.id !== filterId))
-    },
-    [filters, onChange]
-  )
-
-  return (
-    <div
-      className={cn(
-        filtersContainerVariants({
-          variant: context.variant,
-          size: context.size,
-        }),
-        context.className
-      )}
-    >
-      {filters.map((filter) => {
-        const field = fieldsMap[filter.field]
-        if (!field) return null
-
-        return (
-          <ButtonGroup key={filter.id}>
-            <ButtonGroupText>
-              {field.icon && field.icon}
-              {field.label}
-            </ButtonGroupText>
-
-            <FilterOperatorDropdown<T>
-              field={field}
-              operator={filter.operator}
-              values={filter.values}
-              onChange={(operator) => updateFilter(filter.id, { operator })}
-            />
-
-            <FilterValueSelector<T>
-              field={field}
-              values={filter.values}
-              onChange={(values) => updateFilter(filter.id, { values })}
-              operator={filter.operator}
-              autoFocus={false}
-            />
-
-            <FilterRemoveButton onClick={() => removeFilter(filter.id)} />
-          </ButtonGroup>
-        )
-      })}
-    </div>
-  )
-}
-
-interface FiltersProps<T = unknown> {
-  filters: Filter<T>[]
-  fields: FilterFieldsConfig<T>
-  onChange: (filters: Filter<T>[]) => void
-  className?: string
-  variant?: "solid" | "default"
-  size?: "sm" | "default" | "lg"
-  radius?: "default" | "full"
-  i18n?: Partial<FilterI18nConfig>
-  showSearchInput?: boolean
-  trigger?: React.ReactNode
-  allowMultiple?: boolean
-  menuPopupClassName?: string
-  collapseAddButton?: boolean
-  enableShortcut?: boolean
-  shortcutKey?: string
-  shortcutLabel?: string
-}
-
-interface FilterSubmenuContentProps<T = unknown> {
-  field: FilterFieldConfig<T>
-  currentValues: T[]
-  isMultiSelect: boolean
-  onToggle: (value: T, isSelected: boolean) => void
-  i18n: FilterI18nConfig
-  isActive?: boolean
-  onActive?: () => void
-  onBack?: () => void
-  onClose?: () => void
-}
-
-function FilterSubmenuContent<T = unknown>({
-  field,
-  currentValues,
-  isMultiSelect,
-  onToggle,
-  i18n,
-  isActive,
-  onActive,
-  onBack,
-  onClose,
-}: FilterSubmenuContentProps<T>) {
-  const [searchInput, setSearchInput] = useState("")
-  const [highlightedIndex, setHighlightedIndex] = useState(-1)
-  const inputRef = useRef<HTMLInputElement>(null)
-  const baseId = useId()
-
-  useEffect(() => {
-    if (isActive) {
-      if (field.searchable !== false) {
-        inputRef.current?.focus()
-      } else {
-        const listbox = document.getElementById(`${baseId}-listbox`)
-        listbox?.focus()
-      }
-    }
-  }, [isActive, field.searchable, baseId])
-
-  useEffect(() => {
-    setHighlightedIndex(-1)
-  }, [searchInput])
-
-  useEffect(() => {
-    if (highlightedIndex >= 0 && isActive) {
-      const element = document.getElementById(
-        `${baseId}-item-${highlightedIndex}`
-      )
-      element?.scrollIntoView({ block: "nearest" })
-    }
-  }, [highlightedIndex, isActive, baseId])
-
-  const filteredOptions = useMemo(() => {
-    return (
-      field.options?.filter((option) => {
-        const isSelected = currentValues.includes(option.value)
-        if (isSelected) return true
-        if (!searchInput) return true
-        return option.label.toLowerCase().includes(searchInput.toLowerCase())
-      }) || []
-    )
-  }, [field.options, searchInput, currentValues])
-
-  useEffect(() => {
-    if (isActive && filteredOptions.length > 0) {
-      setHighlightedIndex(0)
-    }
-  }, [isActive, filteredOptions.length])
-
-  return (
-    <div className="flex flex-col" onMouseEnter={onActive}>
-      {field.searchable !== false && (
-        <>
-          <Input
-            ref={inputRef}
-            role="combobox"
-            aria-autocomplete="list"
-            aria-expanded={true}
-            aria-haspopup="listbox"
-            aria-controls={`${baseId}-listbox`}
-            aria-activedescendant={
-              highlightedIndex >= 0
-                ? `${baseId}-item-${highlightedIndex}`
-                : undefined
-            }
-            placeholder={i18n.placeholders.searchField(field.label || "")}
-            className={cn(
-              "h-8 rounded-none border-0 bg-transparent! px-2 text-sm shadow-none",
-              "focus-visible:border-border focus-visible:ring-0 focus-visible:ring-offset-0",
-              isActive && "placeholder:text-foreground"
-            )}
-            value={searchInput}
-            onBlur={() => isActive && inputRef.current?.focus()}
-            onChange={(e) => setSearchInput(e.target.value)}
-            onFocus={() => onActive?.()}
-            onMouseEnter={(e) => {
-              onActive?.()
-              e.stopPropagation()
-            }}
-            onClick={(e) => e.stopPropagation()}
-            onKeyDown={(e) => {
-              if (e.key === "ArrowDown") {
-                e.preventDefault()
-                if (filteredOptions.length > 0) {
-                  setHighlightedIndex((prev) =>
-                    prev < filteredOptions.length - 1 ? prev + 1 : 0
-                  )
-                }
-              } else if (e.key === "ArrowUp") {
-                e.preventDefault()
-                if (filteredOptions.length > 0) {
-                  setHighlightedIndex((prev) =>
-                    prev > 0 ? prev - 1 : filteredOptions.length - 1
-                  )
-                }
-              } else if (e.key === "ArrowLeft") {
-                e.preventDefault()
-                onBack?.()
-              } else if (e.key === "Enter" && highlightedIndex >= 0) {
-                e.preventDefault()
-                const option = filteredOptions[highlightedIndex]
-                if (option) {
-                  onToggle(
-                    option.value as T,
-                    currentValues.includes(option.value)
-                  )
-                  if (!isMultiSelect) {
-                    onBack?.()
-                  }
-                }
-              } else if (e.key === "Escape") {
-                e.preventDefault()
-                onClose?.()
-              }
-              e.stopPropagation()
-            }}
-          />
-          <DropdownMenuSeparator />
-        </>
-      )}
-      <div className="relative flex max-h-full">
-        <div
-          className="flex max-h-[min(var(--available-height),24rem)] w-full scroll-pt-2 scroll-pb-2 flex-col overscroll-contain outline-hidden"
-          role="listbox"
-          id={`${baseId}-listbox`}
-          tabIndex={field.searchable === false ? 0 : -1}
-          onKeyDown={(e) => {
-            if (field.searchable === false) {
-              if (e.key === "ArrowDown") {
-                e.preventDefault()
-                if (filteredOptions.length > 0) {
-                  setHighlightedIndex((prev) =>
-                    prev < filteredOptions.length - 1 ? prev + 1 : 0
-                  )
-                }
-              } else if (e.key === "ArrowUp") {
-                e.preventDefault()
-                if (filteredOptions.length > 0) {
-                  setHighlightedIndex((prev) =>
-                    prev > 0 ? prev - 1 : filteredOptions.length - 1
-                  )
-                }
-              } else if (e.key === "ArrowLeft") {
-                e.preventDefault()
-                onBack?.()
-              } else if (e.key === "Enter" && highlightedIndex >= 0) {
-                e.preventDefault()
-                const option = filteredOptions[highlightedIndex]
-                if (option) {
-                  onToggle(
-                    option.value as T,
-                    currentValues.includes(option.value)
-                  )
-                  if (!isMultiSelect) {
-                    onBack?.()
-                  }
-                }
-              } else if (e.key === "Escape") {
-                e.preventDefault()
-                onClose?.()
-              }
-              e.stopPropagation()
-            }
-          }}
-        >
-          <ScrollArea className="size-full min-h-0 **:data-[slot=scroll-area-scrollbar]:m-0 [&_[data-slot=scroll-area-viewport]]:h-full [&_[data-slot=scroll-area-viewport]]:overscroll-contain">
-            {filteredOptions.length === 0 ? (
-              <div className="text-muted-foreground py-2 text-center text-sm">
-                {i18n.noResultsFound}
-              </div>
-            ) : (
-              <DropdownMenuGroup>
-                {filteredOptions.map((option, index) => {
-                  const isSelected = currentValues.includes(option.value)
-                  const isHighlighted = highlightedIndex === index
-                  const itemId = `${baseId}-item-${index}`
-
-                  return (
-                    <DropdownMenuCheckboxItem
-                      key={String(option.value)}
-                      id={itemId}
-                      role="option"
-                      aria-selected={isHighlighted}
-                      data-highlighted={isHighlighted || undefined}
-                      onMouseEnter={() => setHighlightedIndex(index)}
-                      checked={isSelected}
-                      className={cn(
-                        "data-highlighted:bg-accent data-highlighted:text-accent-foreground",
-                        option.className
-                      )}
-                      onSelect={(e) => {
-                        if (isMultiSelect) e.preventDefault()
-                      }}
-                      onCheckedChange={() =>
-                        onToggle(option.value as T, isSelected)
-                      }
-                    >
-                      {option.icon && option.icon}
-                      <span className="truncate">{option.label}</span>
-                    </DropdownMenuCheckboxItem>
-                  )
-                })}
-              </DropdownMenuGroup>
-            )}
-          </ScrollArea>
-        </div>
-      </div>
-    </div>
-  )
-}
-
-export function Filters<T = unknown>({
-  filters,
-  fields,
-  onChange,
-  className,
-  variant = "default",
-  size = "default",
-  radius = "default",
-  i18n,
-  showSearchInput = true,
-  trigger,
-  allowMultiple = true,
-  menuPopupClassName,
-  enableShortcut = false,
-  shortcutKey = "f",
-  shortcutLabel = "F",
-}: FiltersProps<T>) {
-  const [addFilterOpen, setAddFilterOpen] = useState(false)
-  const [menuSearchInput, setMenuSearchInput] = useState("")
-  const [activeMenu, setActiveMenu] = useState<string>("root")
-  const [openSubMenu, setOpenSubMenu] = useState<string | null>(null)
-  const [highlightedIndex, setHighlightedIndex] = useState(-1)
-  const [lastAddedFilterId, setLastAddedFilterId] = useState<string | null>(
-    null
-  )
-  const rootInputRef = useRef<HTMLInputElement>(null)
-  const rootId = useId()
-
-  useEffect(() => {
-    if (!enableShortcut) return
-
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (
-        e.key.toLowerCase() === shortcutKey.toLowerCase() &&
-        !addFilterOpen &&
-        !(
-          document.activeElement instanceof HTMLInputElement ||
-          document.activeElement instanceof HTMLTextAreaElement
-        )
-      ) {
-        e.preventDefault()
-        setAddFilterOpen(true)
-      }
-    }
-
-    window.addEventListener("keydown", handleKeyDown)
-    return () => window.removeEventListener("keydown", handleKeyDown)
-  }, [enableShortcut, shortcutKey, addFilterOpen])
-
-  useEffect(() => {
-    if (addFilterOpen && activeMenu === "root") {
-      rootInputRef.current?.focus()
-    }
-  }, [addFilterOpen, activeMenu])
-
-  useEffect(() => {
-    setHighlightedIndex(-1)
-  }, [menuSearchInput])
-
-  useEffect(() => {
-    if (highlightedIndex >= 0 && addFilterOpen) {
-      const element = document.getElementById(
-        `${rootId}-item-${highlightedIndex}`
-      )
-      element?.scrollIntoView({ block: "nearest" })
-    }
-  }, [highlightedIndex, addFilterOpen, rootId])
-
-  useEffect(() => {
-    if (!addFilterOpen) {
-      setOpenSubMenu(null)
-    }
-  }, [addFilterOpen])
-
-  // Track which filter instance is being built in the current Add Filter menu session
-  // Maps fieldKey -> unique filterId created during this open session
-  const [sessionFilterIds, setSessionFilterIds] = useState<
-    Record<string, string>
-  >({})
-
-  useEffect(() => {
-    if (lastAddedFilterId) {
-      const timer = setTimeout(() => {
-        setLastAddedFilterId(null)
-      }, 1000)
-      return () => clearTimeout(timer)
-    }
-  }, [lastAddedFilterId])
-
-  const mergedI18n: FilterI18nConfig = {
-    ...DEFAULT_I18N,
-    ...i18n,
-    operators: { ...DEFAULT_I18N.operators, ...i18n?.operators },
-    placeholders: { ...DEFAULT_I18N.placeholders, ...i18n?.placeholders },
-    validation: { ...DEFAULT_I18N.validation, ...i18n?.validation },
-  }
-
-  const fieldsMap = useMemo(() => getFieldsMap(fields), [fields])
-
-  const updateFilter = useCallback(
-    (filterId: string, updates: Partial<Filter<T>>) => {
-      onChange(
-        filters.map((filter) => {
-          if (filter.id === filterId) {
-            const updatedFilter = { ...filter, ...updates }
-            if (
-              updates.operator === "empty" ||
-              updates.operator === "not_empty"
-            ) {
-              updatedFilter.values = [] as T[]
-            }
-            return updatedFilter
-          }
-          return filter
-        })
-      )
-    },
-    [filters, onChange]
-  )
-
-  const removeFilter = useCallback(
-    (filterId: string) => {
-      onChange(filters.filter((filter) => filter.id !== filterId))
-    },
-    [filters, onChange]
-  )
-
-  const addFilter = useCallback(
-    (fieldKey: string) => {
-      const field = fieldsMap[fieldKey]
-      if (field && field.key) {
-        const defaultOperator =
-          field.defaultOperator ||
-          (field.type === "multiselect" ? "is_any_of" : "is")
-        const defaultValues: unknown[] = field.type === "text" ? [""] : []
-        const newFilter = createFilter<T>(
-          fieldKey,
-          defaultOperator,
-          defaultValues as T[]
-        )
-        setLastAddedFilterId(newFilter.id)
-        onChange([...filters, newFilter])
-        setAddFilterOpen(false)
-        setMenuSearchInput("")
-      }
-    },
-    [fieldsMap, filters, onChange]
-  )
-
-  useEffect(() => {
-    if (addFilterOpen && activeMenu === "root") {
-      rootInputRef.current?.focus()
-    }
-  }, [addFilterOpen, activeMenu])
-
-  const selectableFields = useMemo(() => {
-    const flatFields = flattenFields(fields)
-    return flatFields.filter((field) => {
-      if (!field.key || field.type === "separator") return false
-      if (allowMultiple) return true
-      return !filters.some((filter) => filter.field === field.key)
-    })
-  }, [fields, filters, allowMultiple])
-
-  const filteredFields = useMemo(() => {
-    return selectableFields.filter(
-      (f) =>
-        !menuSearchInput ||
-        f.label?.toLowerCase().includes(menuSearchInput.toLowerCase())
-    )
-  }, [selectableFields, menuSearchInput])
-
-  useEffect(() => {
-    if (addFilterOpen && filteredFields.length > 0) {
-      setHighlightedIndex(0)
-    }
-  }, [addFilterOpen, filteredFields.length])
-
-  const triggerButton = useRender({
-    render: trigger as React.ReactElement,
-    defaultTagName: "button",
-  })
-
-  return (
-    <FilterContext.Provider
-      value={{
-        variant,
-        size,
-        radius,
-        i18n: mergedI18n,
-        className,
-        trigger,
-        allowMultiple,
-      }}
-    >
-      <div
-        className={cn(filtersContainerVariants({ variant, size }), className)}
-      >
-        {selectableFields.length > 0 && (
-          <DropdownMenu
-            open={addFilterOpen}
-            onOpenChange={(open) => {
-              setAddFilterOpen(open)
-              if (!open) {
-                setMenuSearchInput("")
-                setSessionFilterIds({})
-              } else {
-                setActiveMenu("root")
-              }
-            }}
-          >
-            <DropdownMenuTrigger render={triggerButton} />
-            <DropdownMenuContent
-              className={cn("w-[220px]", menuPopupClassName)}
-              align="start"
-            >
-              {showSearchInput && (
-                <>
-                  <div className="relative">
-                    <Input
-                      ref={rootInputRef}
-                      role="combobox"
-                      aria-controls={`${rootId}-listbox`}
-                      aria-activedescendant={
-                        highlightedIndex >= 0
-                          ? `${rootId}-item-${highlightedIndex}`
-                          : undefined
-                      }
-                      placeholder={mergedI18n.searchFields}
-                      className={cn(
-                        "h-8 rounded-none border-0 bg-transparent! px-2 text-sm shadow-none",
-                        "focus-visible:border-border focus-visible:ring-0 focus-visible:ring-offset-0",
-                        activeMenu === "root" && "placeholder:text-foreground"
-                      )}
-                      value={menuSearchInput}
-                      onFocus={() => setActiveMenu("root")}
-                      onMouseEnter={() => setActiveMenu("root")}
-                      onBlur={() =>
-                        activeMenu === "root" && rootInputRef.current?.focus()
-                      }
-                      onChange={(e) => setMenuSearchInput(e.target.value)}
-                      onClick={(e) => e.stopPropagation()}
-                      onKeyDown={(e) => {
-                        if (e.key === "ArrowDown") {
-                          e.preventDefault()
-                          if (filteredFields.length > 0) {
-                            setHighlightedIndex((prev) =>
-                              prev < filteredFields.length - 1 ? prev + 1 : 0
-                            )
-                          }
-                        } else if (e.key === "ArrowUp") {
-                          e.preventDefault()
-                          if (filteredFields.length > 0) {
-                            setHighlightedIndex((prev) =>
-                              prev > 0 ? prev - 1 : filteredFields.length - 1
-                            )
-                          }
-                        } else if (
-                          (e.key === "ArrowRight" || e.key === "ArrowLeft") &&
-                          highlightedIndex >= 0
-                        ) {
-                          const field = filteredFields[highlightedIndex]
-                          const hasSubMenu =
-                            field &&
-                            (field.type === "select" ||
-                              field.type === "multiselect") &&
-                            field.options?.length
-
-                          if (e.key === "ArrowRight" && hasSubMenu) {
-                            e.preventDefault()
-                            setOpenSubMenu(field.key || null)
-                            setActiveMenu(field.key || "root")
-                          } else if (e.key === "ArrowLeft") {
-                            e.preventDefault()
-                            if (openSubMenu) {
-                              setOpenSubMenu(null)
-                              setActiveMenu("root")
-                            }
-                          }
-                        } else if (e.key === "Enter" && highlightedIndex >= 0) {
-                          e.preventDefault()
-                          const field = filteredFields[highlightedIndex]
-                          if (field.key) {
-                            const hasSubMenu =
-                              (field.type === "select" ||
-                                field.type === "multiselect") &&
-                              field.options?.length
-                            if (!hasSubMenu) {
-                              addFilter(field.key)
-                            } else {
-                              if (openSubMenu === field.key) {
-                                setOpenSubMenu(null)
-                                setActiveMenu("root")
-                              } else {
-                                setOpenSubMenu(field.key)
-                                setActiveMenu(field.key)
-                              }
-                            }
-                          }
-                        } else if (e.key === "Escape") {
-                          setAddFilterOpen(false)
-                        }
-                        e.stopPropagation()
-                      }}
-                    />
-                    {enableShortcut && shortcutLabel && (
-                      <Kbd className="bg-background absolute top-1/2 right-2 -translate-y-1/2 border">
-                        {shortcutLabel}
-                      </Kbd>
-                    )}
-                  </div>
-                  <DropdownMenuSeparator />
-                </>
-              )}
-
-              <div className="relative flex max-h-full">
-                <div
-                  className="flex max-h-[min(var(--available-height),24rem)] w-full scroll-pt-2 scroll-pb-2 flex-col overscroll-contain"
-                  role="listbox"
-                  id={`${rootId}-listbox`}
-                  onMouseEnter={() => setActiveMenu("root")}
-                >
-                  <ScrollArea className="**:data-[slot=scroll-area-scrollbar]:m-0">
-                    {(() => {
-                      if (filteredFields.length === 0) {
-                        return (
-                          <div className="text-muted-foreground py-2 text-center text-sm">
-                            {mergedI18n.noFieldsFound}
-                          </div>
-                        )
-                      }
-
-                      return filteredFields.map((field, index) => {
-                        const isHighlighted = highlightedIndex === index
-                        const itemId = `${rootId}-item-${index}`
-                        const hasSubMenu =
-                          (field.type === "select" ||
-                            field.type === "multiselect") &&
-                          field.options?.length
-
-                        if (hasSubMenu) {
-                          const isMultiSelect = field.type === "multiselect"
-                          const fieldKey = field.key as string
-                          const sessionFilterId = sessionFilterIds[fieldKey]
-                          const sessionFilter = sessionFilterId
-                            ? filters.find((f) => f.id === sessionFilterId)
-                            : null
-                          const currentValues = sessionFilter?.values || []
-
-                          return (
-                            <DropdownMenuSub
-                              key={fieldKey}
-                              open={openSubMenu === fieldKey}
-                              onOpenChange={(open) => {
-                                if (open) {
-                                  setOpenSubMenu(fieldKey)
-                                } else {
-                                  if (openSubMenu === fieldKey) {
-                                    setOpenSubMenu(null)
-                                    setActiveMenu("root")
-                                  }
-                                }
-                              }}
-                            >
-                              <DropdownMenuSubTrigger
-                                id={itemId}
-                                role="option"
-                                aria-selected={isHighlighted}
-                                data-highlighted={isHighlighted || undefined}
-                                onMouseEnter={() => {
-                                  setHighlightedIndex(index)
-                                  setActiveMenu("root")
-                                }}
-                                className="data-popup-open:bg-accent data-popup-open:text-accent-foreground data-highlighted:bg-accent data-highlighted:text-accent-foreground"
-                              >
-                                {field.icon}
-                                <span>{field.label}</span>
-                              </DropdownMenuSubTrigger>
-                              <DropdownMenuSubContent
-                                className="w-[200px]"
-                                side="right"
-                              >
-                                <FilterSubmenuContent
-                                  field={field}
-                                  currentValues={currentValues}
-                                  isMultiSelect={isMultiSelect}
-                                  i18n={mergedI18n}
-                                  isActive={activeMenu === fieldKey}
-                                  onActive={() => {
-                                    if (field.searchable !== false) {
-                                      setActiveMenu(fieldKey)
-                                    }
-                                  }}
-                                  onBack={() => {
-                                    setOpenSubMenu(null)
-                                    setActiveMenu("root")
-                                  }}
-                                  onClose={() => setAddFilterOpen(false)}
-                                  onToggle={(value, isSelected) => {
-                                    if (isMultiSelect) {
-                                      const nextValues = isSelected
-                                        ? (currentValues.filter(
-                                            (v) => v !== value
-                                          ) as T[])
-                                        : ([...currentValues, value] as T[])
-
-                                      if (sessionFilter) {
-                                        if (nextValues.length === 0) {
-                                          onChange(
-                                            filters.filter(
-                                              (f) => f.id !== sessionFilter.id
-                                            )
-                                          )
-                                          setSessionFilterIds((prev) => ({
-                                            ...prev,
-                                            [fieldKey]: "",
-                                          }))
-                                        } else {
-                                          onChange(
-                                            filters.map((f) =>
-                                              f.id === sessionFilter.id
-                                                ? { ...f, values: nextValues }
-                                                : f
-                                            )
-                                          )
-                                        }
-                                      } else {
-                                        const newFilter = createFilter<T>(
-                                          fieldKey,
-                                          field.defaultOperator || "is_any_of",
-                                          nextValues
-                                        )
-                                        onChange([...filters, newFilter])
-                                        setSessionFilterIds((prev) => ({
-                                          ...prev,
-                                          [fieldKey]: newFilter.id,
-                                        }))
-                                      }
-                                    } else {
-                                      const newFilter = createFilter<T>(
-                                        fieldKey,
-                                        field.defaultOperator || "is",
-                                        [value] as T[]
-                                      )
-                                      setLastAddedFilterId(newFilter.id)
-                                      onChange([...filters, newFilter])
-                                      setAddFilterOpen(false)
-                                    }
-                                  }}
-                                />
-                              </DropdownMenuSubContent>
-                            </DropdownMenuSub>
-                          )
-                        }
-
-                        return (
-                          <DropdownMenuItem
-                            key={field.key}
-                            id={itemId}
-                            role="option"
-                            aria-selected={isHighlighted}
-                            data-highlighted={isHighlighted || undefined}
-                            onMouseEnter={() => setHighlightedIndex(index)}
-                            onClick={() => field.key && addFilter(field.key)}
-                            className="data-highlighted:bg-accent data-highlighted:text-accent-foreground"
-                          >
-                            {field.icon}
-                            <span>{field.label}</span>
-                          </DropdownMenuItem>
-                        )
-                      })
-                    })()}
-                  </ScrollArea>
-                </div>
-              </div>
-            </DropdownMenuContent>
-          </DropdownMenu>
-        )}
-
-        {filters.map((filter) => {
-          const field = fieldsMap[filter.field]
-          if (!field) return null
-          return (
-            <ButtonGroup key={filter.id}>
-              <ButtonGroupText className="bg-background dark:bg-input/30">
-                {field.icon && field.icon}
-                {field.label}
-              </ButtonGroupText>
-              <FilterOperatorDropdown<T>
-                field={field}
-                operator={filter.operator}
-                values={filter.values}
-                onChange={(operator) => updateFilter(filter.id, { operator })}
-              />
-              <FilterValueSelector<T>
-                field={field}
-                values={filter.values}
-                operator={filter.operator}
-                onChange={(values) => updateFilter(filter.id, { values })}
-                autoFocus={filter.id === lastAddedFilterId}
-              />
-              <FilterRemoveButton onClick={() => removeFilter(filter.id)} />
-            </ButtonGroup>
-          )
-        })}
-      </div>
-    </FilterContext.Provider>
-  )
-}
-
-export const createFilter = <T = unknown,>(
-  field: string,
-  operator?: string,
-  values: T[] = []
-): Filter<T> => ({
-  id: `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`,
-  field,
-  operator: operator || "is",
-  values,
-})
-
-export const createFilterGroup = <T = unknown,>(
-  id: string,
-  label: string,
-  fields: FilterFieldConfig<T>[],
-  initialFilters: Filter<T>[] = []
-): FilterGroup<T> => ({
-  id,
-  label,
-  filters: initialFilters,
-  fields,
-})
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-advanced.tsx b/apps/web/src/components/reui/filters/filters-advanced.tsx
new file mode 100644
index 0000000..8963813
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-advanced.tsx
@@ -0,0 +1,2081 @@
+"use client"
+
+import * as React from "react"
+import { FilterFieldPicker } from "@/components/reui/filters/filters-builder"
+import {
+  FilterMoveToMenuItems,
+  FilterOperatorPopover,
+  FilterRuleMenuItems,
+  FilterValuePopover,
+  useFilterRuleDisplay,
+} from "@/components/reui/filters/filters-chip"
+import {
+  filterControlSizes,
+  filterReadOnlyProps,
+  FilterReorderProvider,
+  isFilterLocked,
+  useFilterActions,
+  useFilterChipAutoOpen,
+  useFilterChipFocused,
+  useFilterFocusEmpty,
+  useFilterFocusStore,
+  useFilterRender,
+  useFilterReorderable,
+  useFilterRowPending,
+  useFilterRowStateStore,
+  useFilterSegmentFocus,
+  useFilterState,
+  type FilterActionsContextValue,
+} from "@/components/reui/filters/filters-context"
+import {
+  FILTER_ROW_SELECTOR,
+  useFilterRowDrag,
+} from "@/components/reui/filters/filters-dnd"
+import { filterIssueLabel } from "@/components/reui/filters/filters-i18n"
+import {
+  FILTER_FIELD_PICKER_CLASS,
+  FILTER_MENU_CLASS,
+  FILTER_MENU_LABEL_CLASS,
+  filterCombinatorSlot,
+  getFilterField,
+  isFilterFieldPickable,
+  joinFilterPath,
+} from "@/components/reui/filters/filters-lib"
+import {
+  getFilterArity,
+  getFilterOperator,
+  operatorTakesValue,
+} from "@/components/reui/filters/filters-operators"
+import {
+  collectFilterIssues,
+  createFilterRule,
+  isFilterRule,
+} from "@/components/reui/filters/filters-query"
+import type {
+  FilterCombinator,
+  FilterEmptyStateContext,
+  FilterField,
+  FilterGroupNode,
+  FilterIssue,
+  FilterNode,
+  FilterOperator,
+  FilterQuery,
+  FilterRule,
+} from "@/components/reui/filters/filters-types"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { Button } from "@authportal/ui/components/button"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@authportal/ui/components/dropdown-menu"
+import { Input } from "@authportal/ui/components/input"
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@authportal/ui/components/popover"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@authportal/ui/components/tooltip"
+import { RefreshCwIcon, CircleAlertIcon, GripVerticalIcon, ChevronDownIcon, EllipsisVerticalIcon, XIcon, PlusIcon, CopyIcon, UngroupIcon, Trash2Icon, ListFilterIcon, FolderPlusIcon } from "lucide-react"
+
+/* -------------------------------------------------------------------------- */
+/*                                  Columns                                   */
+/* -------------------------------------------------------------------------- */
+
+const CONTENT_COLUMNS = ["combinator", "field", "operator", "value"] as const
+
+const ACTION_COLUMNS = ["drag", "menu", "add", "remove"] as const
+
+/** Every column a row may draw, in two bands. Navigation is by COLUMN NAME and
+ * never position: the BANDS keep ArrowDown off a group's footer button. */
+type FilterColumn =
+  | (typeof CONTENT_COLUMNS)[number]
+  | (typeof ACTION_COLUMNS)[number]
+
+/** The nearest column in `band` that `available` has; backward wins a tie. */
+function nearestColumn(
+  band: readonly FilterColumn[],
+  from: FilterColumn,
+  available: Map<string | null, HTMLElement>
+): HTMLElement | undefined {
+  const at = band.indexOf(from)
+  if (at === -1) return undefined
+  for (let step = 0; step < band.length; step++) {
+    const before = step === 0 ? undefined : available.get(band[at - step] ?? "")
+    if (before) return before
+    const after = available.get(band[at + step] ?? "")
+    if (after) return after
+  }
+  return undefined
+}
+
+/** Marks a focusable cell control, read by the keyboard walker. Not
+ * `data-slot`: a cell control is handed to a Base UI trigger through `render`,
+ * which stamps its own, so a slot here would be two owners on one attribute. */
+const CELL_ATTRIBUTE = "data-filter-cell"
+
+/** Marks a cell the user TYPES into: the builder claims the arrows, Home, End
+ * and Delete, and each means something else in a text box. */
+const CELL_INPUT_ATTRIBUTE = "data-filter-cell-input"
+
+const ROW_SELECTOR = FILTER_ROW_SELECTOR
+
+/** Hands every row's handle its pointer wiring: only the panel, which owns the
+ * body element, can measure a drop. */
+
+const FilterDragContext = React.createContext<ReturnType<
+  typeof useFilterRowDrag
+> | null>(null)
+
+/** What each node is missing, by id. An empty map by default, so a row mounted
+ * outside the shipped panel gets "nothing is wrong" instead of a throw. */
+const FilterIssueContext = React.createContext<
+  ReadonlyMap<string, FilterIssue>
+>(new Map())
+
+function cellProps(column: FilterColumn, active: FilterColumn | null) {
+  return {
+    "data-filter-cell": column,
+    // ONE tab stop for the whole builder; the arrows move within it.
+    tabIndex: active === column ? 0 : -1,
+  }
+}
+
+/** What an INVALID cell wears: `aria-invalid` to announce it, `data-invalid`
+ * to style it, `aria-description` for the sentence. */
+function issueProps(
+  issue: FilterIssue | undefined,
+  column: FilterIssue["column"],
+  message: string
+) {
+  if (!issue || issue.column !== column) return null
+  return {
+    "aria-invalid": true,
+    "data-invalid": "",
+    "aria-description": message,
+    // NO `title`: the hint icon carries the sentence in a real tooltip, and a
+    // native one would clobber the truncation `title` beside it.
+  } as const
+}
+
+/** Sera's uppercase and wide tracking cost about a third of a cell, so where
+ * every other style drew "migration" sera drew "MIGRATI...". */
+const SERA_TEXT_CLASS = ""
+
+const CELL_CLASS = cn(
+  "w-full min-w-0 justify-between gap-1.5 font-normal",
+  // `>svg` is the caret and only the caret: a field's own type icon sits in a
+  // nested span, where it keeps full strength because it is content.
+  "[&>svg]:text-muted-foreground",
+  // WHAT A CELL GIVES UP FIRST: padding, icon and caret cost about 44px before
+  // a character is drawn, and the name is what nothing else can reconstruct.
+  // Container queries and not a viewport breakpoint: the question is how wide
+  // THIS cell is, and one panel holds a 300px cell and a 40px one.
+  "@max-[7rem]/cell:gap-0 @max-[7rem]/cell:[&>svg]:hidden",
+  "@max-[5rem]/cell:[&_span>svg]:hidden",
+  SERA_TEXT_CLASS
+)
+
+/** What an invalid cell looks like. A ring, not a border: a border changes the
+ * box, so a cell turning invalid would nudge every cell beside it. */
+const CELL_INVALID_CLASS =
+  "data-invalid:ring-destructive/40 data-invalid:ring-1"
+
+/** Width of the leading combinator column. The 58.72px pill put this track at
+ * 4rem and it does not shrink now the pill has: it is sized for the longest of
+ * the three things in it, "Where", 51.44px in every style. */
+const COMBINATOR_CLASS = cn(
+  "w-16 shrink-0 items-center justify-center",
+  // 6px of its own on TOP of the band's `gap-1.5`: this column is the
+  // sentence's connective, not a fourth control butted against the attribute.
+  "me-1.5"
+)
+
+/** The two static words in that column, CENTRED because the pill's own
+ * `justify-center` centres its word. `w-full`, or `truncate` has no box. */
+const COMBINATOR_TEXT_CLASS = cn(
+  "text-muted-foreground w-full truncate px-1 text-center text-sm",
+  SERA_TEXT_CLASS
+)
+
+/** A row is TWO BANDS. The trailing pair of every row at every depth shares one
+ * vertical axis - 0.00px of spread from 1104px to 240px, eight styles, depth
+ * three - and only because the content band may shrink to nothing. */
+const ROW_BAND_CLASS = "flex min-w-0 items-center gap-1.5"
+
+const CONTENT_BAND_CLASS = "flex min-w-0 flex-1 items-center gap-1.5"
+
+/** FLEX and not a block: a `Button` is `inline-flex`, so a block wrapper builds
+ * a line box as tall as its font's strut - 28px buttons in 28.141px wrappers. */
+const CELL_BOX_CLASS = "@container/cell flex min-w-0 shrink grow-0"
+
+/** THE DEFAULT WIDTH OF EACH CONTENT CELL. An INLINE FALLBACK and not a
+ * declaration on the panel: declared, the panel would beat anything an ANCESTOR
+ * set, which is where a consumer sets it in popover mode. So all four work:
+ *
+ *   <Filters variant="advanced" className="[--filter-field-width:14rem]" />
+ *   <FiltersAdvancedPanel className="[--filter-operator-width:7rem]" />
+ *   <Card className="[--filter-value-width:16rem]"><Filters … /></Card>
+ *   [data-slot="filters-advanced"] { --filter-field-width: 14rem } */
+const FIELD_CELL_CLASS = "basis-[var(--filter-field-width,11rem)]"
+const OPERATOR_CELL_CLASS = "basis-[var(--filter-operator-width,9rem)]"
+const VALUE_CELL_CLASS = "basis-[var(--filter-value-width,12rem)]"
+
+/** The trailing band. `pe-1` is on the BAND and not the gutter, since a group
+ * card is `pe-0`; the footer and `DROP_SLOT_INDICATOR` restate the same four. */
+const ACTION_BAND_CLASS = cn(
+  "text-muted-foreground flex shrink-0 items-center gap-0.5 pe-1"
+)
+
+/** What the grip and the kebab wear while open. TWO ATTRIBUTES, because Radix
+ * sets `data-state="open"` and Base UI `data-popup-open`, so one selector alone
+ * would be dead in one twin, silently, in a byte-locked file. */
+const ACTION_CONTROL_CLASS = cn(
+  "hover:inset-ring hover:inset-ring-border",
+  // Base UI.
+  "data-popup-open:inset-ring data-popup-open:inset-ring-border",
+  // Radix.
+  "data-[state=open]:inset-ring data-[state=open]:inset-ring-border"
+)
+
+/** The gap between sibling rows, one third of one measurement:
+ * `FILTER_ROW_SEAM_PX` is HALF of it and the footer's `-mt-*` cancels it. */
+const FILTER_ROW_GAP_CLASS = "gap-3"
+const FILTER_ROW_GAP_CANCEL_CLASS = "-mt-3"
+const FILTER_ROW_HALF_GAP_CLASS = {
+  // The slot names the BOUNDARY between two rows, which is the middle of the
+  // gap: 6px of it less HALF the rule's own 2px, so its CENTRE lands there.
+  before: "data-[drop-edge=before]:after:mb-[5px]",
+  after: "data-[drop-edge=after]:after:mt-[5px]",
+} as const
+
+/** POPOVER: the popover content is `p-0`, so this IS the popup's own inner
+ * padding. INLINE there is no popup, and a panel that pads itself as well is a
+ * second inset the page did not ask for. */
+const PANEL_PAD_VAR = "--filter-panel-pad"
+const PANEL_PAD_POPOVER = "0.75rem"
+const PANEL_PAD_INLINE = "0px"
+
+/** The panel's ONE horizontal rhythm: a row's trailing controls sit at the
+ * content edge, which IS this padding, so a footer that disagrees breaks it. */
+const PANEL_GUTTER_CLASS = "px-(--filter-panel-pad)"
+
+const PANEL_CLASS = "flex w-full min-w-0 flex-col gap-2 py-(--filter-panel-pad)"
+
+/** A RING and not a border, the whole answer to the staggered trailing
+ * controls: a border pushes the content edge inward a pixel per level. */
+const GROUP_CARD_CLASS = cn(
+  "bg-muted/40 min-w-0 flex-1 rounded-md",
+  "inset-ring inset-ring-border",
+  "ps-2 pe-0",
+  "data-invalid:inset-ring-destructive/50",
+  // The DESTINATION of a drop into this group, told apart from the insertion
+  // slot by STYLE and not size: dashed is not there yet, solid exists.
+  "data-drop-into:bg-muted/60",
+  "data-drop-into:outline-1 data-drop-into:outline-solid",
+  "data-drop-into:outline-border data-drop-into:-outline-offset-2"
+)
+
+/** THE CONTAINER a row measures its own room against, on the panel body and on
+ * every group's list, so a row asks how wide the list it is IN is. */
+const TRACK_CONTAINER_CLASS = "@container/track"
+
+/** When a group stops putting its combinator BESIDE the card. A DEPTH budget
+ * was wrong both ways: at 380px the depth-three row painted zero pixels of
+ * field, operator and value and fanned the kebab column out by up to 119px.
+ * 26rem is what a row MEASURES: 134px of fixed cost plus about 200px of cells. */
+const GROUP_COMBINATOR_WRAP_CLASS = "@max-[26rem]/track:w-full"
+
+/** The combinator itself, once its wrapper has a whole line. Pinned to the
+ * same 4rem the gutter track is, so it is the same control at every width. */
+const GROUP_COMBINATOR_WRAPPED_CLASS = "@max-[26rem]/track:w-16"
+
+/** How a row shows where a dragged node would land. `data-drop-edge` is an
+ * insertion BETWEEN rows, drawn here; `data-drop-into` is painted on the CARD,
+ * so "inside this group" and "after this group" are not one picture. */
+const DROP_SLOT_INDICATOR = cn(
+  // The SOURCE in flight, faded rather than hidden. THREE FIFTHS is a contrast
+  // measurement: at 35 under a `blur-[1px]` the text composited to #a9a9a9,
+  // 2.35:1 on the light panel, under even the 3:1 line for a non-text mark.
+  "relative rounded-md",
+  "data-dragging:opacity-60",
+  // THE INSERTION LINE lives in the gap rather than overlaying a real row.
+  // `end-1` and not `end-0`: four pixels of `pe-1` are the kebab column.
+  "data-drop-edge:after:absolute",
+  "data-drop-edge:after:start-0 data-drop-edge:after:end-1",
+  "data-drop-edge:after:h-0.5 data-drop-edge:after:rounded-full",
+  "data-drop-edge:after:bg-primary",
+  "data-drop-edge:after:z-10",
+  "data-[drop-edge=before]:after:bottom-full",
+  FILTER_ROW_HALF_GAP_CLASS.before,
+  "data-[drop-edge=after]:after:top-full",
+  FILTER_ROW_HALF_GAP_CLASS.after
+)
+
+/** What a CONDITION row draws, which is what a group's row draws: the slot and
+ * nothing else. It used to add a faint dashed outline of its own, a second
+ * dashed rectangle a few pixels from the first saying what it already said. */
+const DROP_INDICATOR = DROP_SLOT_INDICATOR
+
+/** How the footer says "append to the top level": the same RULE the rows draw.
+ * `data-drop-into` and not `data-drop-edge`, because an explicit zone is a
+ * DESTINATION. Both ends restate the padding VARIABLE, since `inset` resolves
+ * against the PADDING box and `inset-x-0` overran every rule above it. */
+const FOOTER_DROP_CLASS = cn(
+  "data-drop-into:after:absolute",
+  "data-drop-into:after:start-(--filter-panel-pad)",
+  "data-drop-into:after:end-[calc(var(--filter-panel-pad)+4px)]",
+  "data-drop-into:after:top-0 data-drop-into:after:h-0.5",
+  "data-drop-into:after:rounded-full data-drop-into:after:bg-primary"
+)
+
+/** The cells a row owns ITSELF: a group's row contains its children's rows, so
+ * a bare `querySelectorAll` would let ArrowRight walk into the first of them. */
+function ownCells(row: HTMLElement): HTMLElement[] {
+  return Array.from(
+    row.querySelectorAll<HTMLElement>(`[${CELL_ATTRIBUTE}]`)
+  ).filter((cell) => cell.closest<HTMLElement>(ROW_SELECTOR) === row)
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                Shared cells                                */
+/* -------------------------------------------------------------------------- */
+
+interface RowPosition {
+  index: number
+  parentId: string
+  combinator: FilterCombinator
+  depth: number
+}
+
+/** The leading and/or slot: one group is joined by ONE operator, and mixing is
+ * what a nested group is FOR. */
+function CombinatorCell({
+  index,
+  parentId,
+  combinator,
+  active,
+  onFocus,
+  className,
+}: {
+  index: number
+  parentId: string
+  combinator: FilterCombinator
+  active: FilterColumn | null
+  onFocus: (column: FilterColumn) => () => void
+  className?: string
+}) {
+  const actions = useFilterActions()
+  const sizes = filterControlSizes(actions)
+  const slot = filterCombinatorSlot(index)
+  const word = combinator === "and" ? actions.labels.and : actions.labels.or
+
+  if (slot === "where") {
+    return (
+      <span className={cn(COMBINATOR_TEXT_CLASS, className)}>
+        {actions.labels.where}
+      </span>
+    )
+  }
+
+  if (slot === "echo") {
+    return <span className={cn(COMBINATOR_TEXT_CLASS, className)}>{word}</span>
+  }
+
+  const name = actions.labels.combinatorLabel(word)
+
+  return (
+    <Button
+      variant="outline"
+      size={sizes.button}
+      /* The WORD is in the name: the track is fixed, so a locale whose
+         word overflows draws "a...". */
+      aria-label={name}
+      title={name}
+      disabled={actions.disabled}
+      {...filterReadOnlyProps(actions)}
+      className={cn(
+        "group/combinator relative w-full min-w-0 justify-center px-1.5 font-normal",
+        SERA_TEXT_CLASS,
+        className
+      )}
+      {...cellProps("combinator", active)}
+      onFocus={onFocus("combinator")}
+      onClick={() => actions.toggleCombinator(parentId)}
+    >
+      <span className="truncate">{word}</span>
+      {/* ABSOLUTELY POSITIONED, so the word still centres at 0.00px. */}
+      <span
+        aria-hidden="true"
+        className={cn(
+          "pointer-events-none absolute end-1 opacity-0 transition-opacity",
+          "group-hover/combinator:opacity-60",
+          "group-focus-visible/combinator:opacity-60",
+          "[&_svg]:size-3"
+        )}
+      >
+        <RefreshCwIcon
+        />
+      </span>
+    </Button>
+  )
+}
+
+/** Whether dragging this node could change the tree at all; the grip is drawn
+ * only when it could. Every destination outside the footer zone lives inside
+ * some row and the drop layer discards any inside the dragged one, so the sole
+ * child of the root is the one case with nowhere to go. A pure function of the
+ * QUERY, deliberately blind to `disabled` and `readOnly`: a locked bar keeps
+ * its grip, because "you may not move this" and "there is nowhere to move it"
+ * are different sentences. */
+function canFilterNodeMove(
+  query: FilterQuery<unknown>,
+  position: { parentId: string }
+) {
+  if (position.parentId !== query.id) return true
+  return query.rules.length > 1
+}
+
+/** The error, as a QUIET mark the pointer can ask about: ONE per ROW, and
+ * `aria-hidden`, since the cell carries it as `aria-description`. */
+function RowIssueHint({
+  message,
+  className,
+}: {
+  message: string
+  className?: string
+}) {
+  if (!message) return null
+  return (
+    <TooltipProvider delay={200}>
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <span
+              data-slot="filter-row-issue"
+              /* Focusable so a keyboard user can summon it, but OUT of the
+                 tab order: the sentence is already on the invalid cell. */
+              tabIndex={-1}
+              aria-hidden="true"
+              className={cn(
+                "text-destructive flex shrink-0 items-center justify-center [&_svg]:size-3.5",
+                className
+              )}
+            >
+              <CircleAlertIcon
+              />
+            </span>
+          }
+        />
+        <TooltipContent side="top">{message}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  )
+}
+
+/** The drag handle: what ARMS the gesture, since arming the row would turn
+ * every text selection into a drag, and the only thing a screen reader can be
+ * told about, which is why Alt+arrow hangs off it. */
+function RowHandle({
+  nodeId,
+  active,
+  onFocus,
+}: {
+  nodeId: string
+  active: FilterColumn | null
+  onFocus: (column: FilterColumn) => () => void
+}) {
+  const actions = useFilterActions()
+  const sizes = filterControlSizes(actions)
+  const dragProps = React.useContext(FilterDragContext)
+  const locked = isFilterLocked(actions)
+
+  return (
+    <Button
+      variant="ghost"
+      size={sizes.icon}
+      aria-label={actions.labels.reorder}
+      /* The activation is the DRAG, which no click performs, so without these
+         a screen reader finds a "Reorder" button that appears broken. */
+      aria-keyshortcuts="Alt+ArrowUp Alt+ArrowDown"
+      aria-description={actions.labels.reorderHint}
+      disabled={actions.disabled}
+      {...filterReadOnlyProps(actions)}
+      /* `touch-none`, or a finger on the handle becomes a page scroll the
+         gesture then fights. Muted at rest, never hidden. */
+      className={cn(
+        "focus-visible:text-foreground cursor-grab touch-none",
+        "active:cursor-grabbing",
+        ACTION_CONTROL_CLASS
+      )}
+      {...cellProps("drag", active)}
+      onFocus={onFocus("drag")}
+      /* Not armed at all while locked; the engine refuses it again. */
+      {...(locked ? null : dragProps?.(nodeId))}
+    >
+      <GripVerticalIcon
+      />
+    </Button>
+  )
+}
+
+/** Which cell of a row owns the builder's single tab stop. An operator change
+ * can take the value column out from under the focus pointing at it. */
+function useActiveColumn(
+  nodeId: string,
+  columns: FilterColumn[],
+  isFirstRow: boolean
+): FilterColumn | null {
+  const focused = useFilterChipFocused(nodeId)
+  const segment = useFilterSegmentFocus(nodeId)
+  const noFocus = useFilterFocusEmpty()
+
+  if (focused) {
+    return segment && columns.includes(segment as FilterColumn)
+      ? (segment as FilterColumn)
+      : columns[0]
+  }
+  return noFocus && isFirstRow ? columns[0] : null
+}
+
+function useFilterIssue(nodeId: string): FilterIssue | undefined {
+  return React.useContext(FilterIssueContext).get(nodeId)
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Inline free text                              */
+/* -------------------------------------------------------------------------- */
+
+/** Whether a value is FREE TEXT, and therefore typed in the row itself. The
+ * CHIP row keeps its popover for every value, deliberately, which is why this
+ * lives here and not in the shared display hook. NUMBER is in: empty clears,
+ * and anything unparseable snaps back to the last committed number. */
+function usesInlineTextEditor<V, O>(
+  field: FilterField<V, O>,
+  operator: FilterOperator | undefined,
+  hasCustomDisplay: boolean
+): boolean {
+  if (field.editor) return false
+  if (field.options || field.loadOptions) return false
+  if (field.renderValue || field.valueText || hasCustomDisplay) return false
+  const type = field.type ?? "text"
+  if (type !== "text" && type !== "number") return false
+  return getFilterArity(operator) === "one"
+}
+
+/** The value cell as a real text box. COMMIT IS BLUR AND ENTER: per keystroke
+ * makes the ROOT the source of truth for every character, and debouncing only
+ * adds a window where the cell and the query disagree with no event. */
+function FilterInlineValueCell<V, O>({
+  rule,
+  field,
+  issue,
+  issueText,
+  active,
+  onFocus,
+}: {
+  rule: FilterRule<V>
+  field: FilterField<V, O>
+  issue: FilterIssue | undefined
+  issueText: string
+  active: FilterColumn | null
+  onFocus: (column: FilterColumn) => () => void
+}) {
+  const actions = useFilterActions<V, O>()
+  const focusStore = useFilterFocusStore()
+  const locked = isFilterLocked(actions)
+  const numeric = (field.type ?? "text") === "number"
+  // The handoff the value POPOVER honours, answered by taking the caret.
+  const autoOpen = useFilterChipAutoOpen(rule.id) === "value"
+  const inputRef = React.useRef<HTMLInputElement>(null)
+
+  const committed =
+    rule.value === undefined || rule.value === null ? "" : String(rule.value)
+  const [draft, setDraft] = React.useState(committed)
+  // STATE and not a ref: the sync below runs during render.
+  const [seed, setSeed] = React.useState(committed)
+
+  // Adjusting state during render; an effect would paint the stale text.
+  if (seed !== committed) {
+    setSeed(committed)
+    setDraft(committed)
+  }
+
+  // CONSUMED as it is honoured: a flag left standing is spent by the next row.
+  React.useEffect(() => {
+    if (!autoOpen) return
+    if (!locked) {
+      const input = inputRef.current
+      input?.focus()
+      // SELECTED: the condition step may have coerced a value across.
+      input?.select()
+    }
+    focusStore.set({ id: rule.id, segment: "value", autoOpen: false })
+  }, [autoOpen, locked, focusStore, rule.id])
+
+  const commit = () => {
+    if (draft === seed) return
+
+    if (numeric) {
+      const text = draft.trim()
+      // Empty clears rather than writing 0, which silently matches rows.
+      if (text === "") {
+        actions.updateRule(rule.id, { value: undefined as V })
+        return
+      }
+      const parsed = Number(text)
+      // Revert, do not write: a NaN compares false against every row.
+      if (!Number.isFinite(parsed)) {
+        setDraft(seed)
+        return
+      }
+      actions.updateRule(rule.id, { value: parsed as V })
+      return
+    }
+
+    actions.updateRule(rule.id, { value: draft as V })
+  }
+
+  return (
+    /* A FRAGMENT, not a wrapper: the positioning context for the error mark
+       is the CELL itself, which already carries the column's basis. */
+    <>
+      <Input
+        ref={inputRef}
+        aria-label={field.label}
+        placeholder={field.placeholder ?? actions.labels.valuePlaceholder}
+        /* The RIGHT KEYPAD only: `type="number"` brings spinners. */
+        inputMode={numeric ? "decimal" : undefined}
+        value={draft}
+        /* `h-full` and no size class: `Input` has ONE height per style, so
+           at `size="sm"` it was a pixel taller in nova and two in sera. */
+        className={cn("h-full", issueText && "pe-7", CELL_INVALID_CLASS)}
+        /* Native `readOnly`, not `disabled`: it keeps its tab stop. */
+        readOnly={locked}
+        disabled={actions.disabled}
+        {...filterReadOnlyProps(actions)}
+        {...cellProps("value", active)}
+        {...{ [CELL_INPUT_ATTRIBUTE]: "" }}
+        {...issueProps(issue, "value", issueText)}
+        onFocus={onFocus("value")}
+        onChange={(event) => setDraft(event.target.value)}
+        onBlur={commit}
+        onKeyDown={(event) => {
+          if (event.key === "Enter" && !event.nativeEvent.isComposing) {
+            event.preventDefault()
+            commit()
+            return
+          }
+          if (event.key === "Escape") {
+            /* Only when there is something to revert; Escape belongs to the
+               surface the builder sits in. */
+            if (draft === seed) return
+            event.preventDefault()
+            event.stopPropagation()
+            setDraft(seed)
+          }
+        }}
+      />
+      <RowIssueHint
+        message={issueText}
+        /* `pointer-events-none`, so a click still lands in the input. */
+        className="pointer-events-none absolute end-2 top-1/2 -translate-y-1/2 [&>*]:pointer-events-auto"
+      />
+    </>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Rule row                                  */
+/* -------------------------------------------------------------------------- */
+
+export interface FilterAdvancedRowProps<V = unknown> {
+  rule: FilterRule<V>
+  position: RowPosition
+}
+
+function FilterAdvancedRowImpl<V, O>({
+  rule,
+  position,
+}: FilterAdvancedRowProps<V>) {
+  const actions = useFilterActions<V, O>()
+  const render = useFilterRender<V, O>()
+  const sizes = filterControlSizes(actions)
+  const focusStore = useFilterFocusStore()
+  const locked = isFilterLocked(actions)
+  const { query } = useFilterState<V>()
+
+  const field = getFilterField(actions.index, rule.path)
+  const operators = field ? actions.resolveOperators(field) : []
+  const operator = getFilterOperator(operators, rule.operator)
+  const takesValue = Boolean(rule.operator) && operatorTakesValue(operator)
+  const inlineValue =
+    takesValue && field
+      ? usesInlineTextEditor(field, operator, Boolean(render.renderValue))
+      : false
+
+  const issue = useFilterIssue(rule.id)
+  const issueText = issue ? filterIssueLabel(issue, actions.labels) : ""
+
+  const {
+    pathText,
+    pathLabel,
+    pathCollapsed,
+    operatorLabel,
+    valueLabel,
+    valueText,
+    valueFullText,
+    valueEmpty,
+  } = useFilterRuleDisplay<V, O>(rule, field, operator)
+
+  /* ------------------------------ field cell ------------------------------ */
+
+  const fieldAutoOpen = useFilterChipAutoOpen(rule.id) === "field"
+  const [pickerOpen, setPickerOpen] = React.useState(false)
+  // Controlled so both can REFUSE to open while locked.
+  const [menuOpen, setMenuOpen] = React.useState(false)
+  // Seeded from the rule's own level, so amending opens beside its siblings.
+  const [pickerPath, setPickerPath] = React.useState<string[]>(() =>
+    rule.path.slice(0, -1)
+  )
+  const [pickerQuery, setPickerQuery] = React.useState("")
+
+  // A new row arrives with a GUESS at its field, so the one choice not yet the
+  // user's own opens itself. CONSUMED as it is honoured: `pickerOpen` is a
+  // dependency, so a flag left standing reopened the picker in the frame it
+  // closed, a keyboard trap on the one row a user creates most.
+  React.useEffect(() => {
+    if (!fieldAutoOpen || pickerOpen) return
+    if (!locked) setPickerOpen(true)
+    focusStore.set({ id: rule.id, segment: "field", autoOpen: false })
+  }, [fieldAutoOpen, pickerOpen, locked, focusStore, rule.id])
+
+  // Re-seed on each open, so a browse that was abandoned last time does not
+  // decide where this one starts.
+  React.useEffect(() => {
+    if (!pickerOpen) return
+    setPickerPath(rule.path.slice(0, -1))
+    setPickerQuery("")
+  }, [pickerOpen, rule.path])
+
+  /* ------------------------------- tab stop ------------------------------- */
+
+  const slot = filterCombinatorSlot(position.index)
+  const reorderable = useFilterReorderable()
+  const canMove = reorderable && canFilterNodeMove(query, position)
+  const rowStateStore = useFilterRowStateStore()
+  // Still waiting for its attribute, so neither later cell is drawn.
+  const pending = useFilterRowPending(rule.id)
+
+  const columns = React.useMemo(() => {
+    const list: FilterColumn[] = []
+    if (slot === "toggle") list.push("combinator")
+    list.push("field")
+    if (!pending) {
+      list.push("operator")
+      if (takesValue) list.push("value")
+    }
+    // The grip is only a tab stop when it is drawn.
+    if (canMove) list.push("drag")
+    list.push("menu")
+    return list
+  }, [slot, takesValue, canMove, pending])
+
+  const active = useActiveColumn(
+    rule.id,
+    columns,
+    position.depth === 1 && position.index === 0
+  )
+
+  const onCellFocus = React.useCallback(
+    (column: FilterColumn) => () =>
+      focusStore.set({ id: rule.id, segment: column, autoOpen: false }),
+    [focusStore, rule.id]
+  )
+
+  /* -------------------------------- render -------------------------------- */
+
+  if (!field) return null
+
+  return (
+    <div
+      /* A GROUP, not a grid row: four depths of grid describes to no
+         assistive technology at all. */
+      role="group"
+      aria-label={actions.labels.rowLabel(
+        `${pathText} ${operatorLabel}`,
+        position.depth
+      )}
+      data-slot="filter-row"
+      data-node-id={rule.id}
+      data-parent-id={position.parentId}
+      data-index={position.index}
+      data-depth={position.depth}
+      className={cn("group/row", ROW_BAND_CLASS, DROP_INDICATOR)}
+    >
+      <div className={cn(COMBINATOR_CLASS, CELL_BOX_CLASS)}>
+        <CombinatorCell
+          index={position.index}
+          parentId={position.parentId}
+          combinator={position.combinator}
+          active={active}
+          onFocus={onCellFocus}
+        />
+      </div>
+
+      {/* THE CONTENT BAND: sized to itself, not to a share of the row. */}
+      <div className={CONTENT_BAND_CLASS}>
+        <div className={cn(CELL_BOX_CLASS, FIELD_CELL_CLASS)}>
+          <Popover
+            open={pickerOpen}
+            onOpenChange={(next) => {
+              if (next && locked) return
+              setPickerOpen(next)
+            }}
+          >
+            <PopoverTrigger
+              disabled={actions.disabled}
+              {...filterReadOnlyProps(actions)}
+              render={
+                <Button
+                  variant="outline"
+                  size={sizes.button}
+                  /* The path is truncated on screen, so the name carries all
+                     of it: "Primary loca... > State" identifies nothing. */
+                  aria-label={pathText}
+                  /* And as a `title` - unless the path is COLLAPSED, where the
+                     ellipsis inside already carries this exact sentence. */
+                  title={pathCollapsed ? undefined : pathText}
+                  className={CELL_CLASS}
+                  {...cellProps("field", active)}
+                  onFocus={onCellFocus("field")}
+                >
+                  <span className="flex min-w-0 items-center gap-1.5 truncate">
+                    {field.icon}
+                    <span className="truncate">{pathLabel}</span>
+                  </span>
+                  <ChevronDownIcon
+                  />
+                </Button>
+              }
+            />
+            <PopoverContent
+              align="start"
+              className={cn(
+                FILTER_FIELD_PICKER_CLASS,
+                actions.fieldPickerClassName
+              )}
+            >
+              <FilterFieldPicker<V, O>
+                path={pickerPath}
+                onPathChange={setPickerPath}
+                query={pickerQuery}
+                onQueryChange={setPickerQuery}
+                onSelect={(path, defaultOperator) => {
+                  setPickerOpen(false)
+                  // BUILDING versus AMENDING, the fork of the stepped
+                  // flow. Naming `operator` retires the field handoff.
+                  focusStore.set({
+                    id: rule.id,
+                    segment: pending ? "operator" : "field",
+                    autoOpen: pending,
+                  })
+                  // BEFORE the same-path early return, or a row minted
+                  // on a guessed field the user then picks stays pending.
+                  rowStateStore.resolvePending(rule.id)
+                  // Re-picking the field it has is a dismissal.
+                  if (joinFilterPath(path) === joinFilterPath(rule.path)) return
+                  // On the create path the condition stays UNSET, so the
+                  // menu opening next has nothing selected.
+                  actions.updateRule(rule.id, {
+                    path,
+                    operator: pending ? "" : (defaultOperator ?? ""),
+                    value: undefined,
+                  })
+                }}
+              />
+            </PopoverContent>
+          </Popover>
+        </div>
+
+        {pending ? null : (
+          <div className={cn(CELL_BOX_CLASS, OPERATOR_CELL_CLASS)}>
+            <FilterOperatorPopover
+              rule={rule}
+              field={field}
+              trigger={
+                <Button
+                  variant="outline"
+                  size={sizes.button}
+                  /* No `aria-label`: the label IS the name. */
+                  title={operatorLabel}
+                  className={cn(
+                    CELL_CLASS,
+                    CELL_INVALID_CLASS,
+                    "text-muted-foreground"
+                  )}
+                  {...cellProps("operator", active)}
+                  {...issueProps(issue, "operator", issueText)}
+                  onFocus={onCellFocus("operator")}
+                >
+                  <span className="truncate">{operatorLabel}</span>
+                  <ChevronDownIcon
+                  />
+                </Button>
+              }
+            />
+          </div>
+        )}
+
+        {/* The cell stays even with no value: dropping it would shift the
+            trailing buttons into the value column on that row alone. It goes
+            ENTIRELY while the row is PENDING, the one case that argument does
+            not cover: a row choosing its attribute has no column count yet. */}
+        {pending ? null : (
+          <div
+            className={cn(
+              CELL_BOX_CLASS,
+              VALUE_CELL_CLASS,
+              /* The positioning context for an inline editor's error mark. */
+              "relative",
+              /* What lets an inline box match the buttons beside it: as tall as
+                 the row, so `h-full` inside resolves to the button height. */
+              "self-stretch"
+            )}
+          >
+            {takesValue ? (
+              inlineValue ? (
+                <FilterInlineValueCell<V, O>
+                  rule={rule}
+                  field={field}
+                  issue={issue}
+                  issueText={issueText}
+                  active={active}
+                  onFocus={onCellFocus}
+                />
+              ) : (
+                <FilterValuePopover
+                  rule={rule}
+                  field={field}
+                  operator={operator}
+                  trigger={
+                    <Button
+                      variant="outline"
+                      size={sizes.button}
+                      /* The VALUE is the name, never the attribute.
+                         Locked, it grows to the whole list. */
+                      aria-label={locked ? valueFullText : valueText}
+                      title={valueFullText}
+                      className={cn(
+                        CELL_CLASS,
+                        CELL_INVALID_CLASS,
+                        "h-full",
+                        valueEmpty && "text-muted-foreground"
+                      )}
+                      {...cellProps("value", active)}
+                      {...issueProps(issue, "value", issueText)}
+                      onFocus={onCellFocus("value")}
+                    >
+                      {/* FREE OUTPUT: whatever the field draws. */}
+                      <span className="min-w-0 flex-1 truncate text-start">
+                        {valueLabel}
+                      </span>
+                      {/* The error, INSIDE the control that failed. */}
+                      <RowIssueHint message={issueText} />
+                    </Button>
+                  }
+                />
+              )
+            ) : null}
+          </div>
+        )}
+      </div>
+
+      {/* The WEIGHT is on the CLUSTER: a `ghost` button names no colour, so
+          the kebab took the full `--foreground`. */}
+      <div className={ACTION_BAND_CLASS}>
+        {canMove ? (
+          <RowHandle nodeId={rule.id} active={active} onFocus={onCellFocus} />
+        ) : null}
+        <DropdownMenu
+          open={menuOpen}
+          onOpenChange={(next) => {
+            if (next && locked) return
+            setMenuOpen(next)
+          }}
+        >
+          <DropdownMenuTrigger
+            disabled={actions.disabled}
+            {...filterReadOnlyProps(actions)}
+            render={
+              <Button
+                variant="ghost"
+                size={sizes.icon}
+                aria-label={actions.labels.chipMenu(field.label)}
+                className={ACTION_CONTROL_CLASS}
+                {...cellProps("menu", active)}
+                onFocus={onCellFocus("menu")}
+              />
+            }
+          >
+            <EllipsisVerticalIcon
+            />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            align="end"
+            className={cn(FILTER_MENU_CLASS, actions.menuClassName)}
+          >
+            {/* Grouping is HERE, not on a chip: the keyboard path to
+                `a AND (b OR c)`. */}
+            <FilterRuleMenuItems ruleId={rule.id} allowGrouping />
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+    </div>
+  )
+}
+
+/** One rule, as a row, memoized: the query tree shares structure, so editing
+ * one row of twenty re-renders one. */
+export const FilterAdvancedRow = React.memo(
+  FilterAdvancedRowImpl
+) as typeof FilterAdvancedRowImpl
+
+/** A rule whose field the schema no longer has: dropping it would lose a saved
+ * view's data, rendering nothing would leave it filtering invisibly. */
+function FilterUnknownRow<V>({
+  rule,
+  position,
+}: {
+  rule: FilterRule<V>
+  position: RowPosition
+}) {
+  const actions = useFilterActions()
+  const sizes = filterControlSizes(actions)
+  return (
+    <div
+      role="group"
+      aria-label={actions.labels.rowLabel(
+        rule.path.join(actions.labels.pathSeparator),
+        position.depth
+      )}
+      data-slot="filter-row"
+      data-node-id={rule.id}
+      data-parent-id={position.parentId}
+      data-index={position.index}
+      data-depth={position.depth}
+      data-unknown=""
+      /* The DROP language too: the hit test pushes every row carrying
+         `data-parent-id` into the surface, and this row carries one. */
+      className={cn(ROW_BAND_CLASS, DROP_INDICATOR)}
+    >
+      <span className="text-muted-foreground min-w-0 flex-1 truncate text-sm">
+        {rule.path.join(actions.labels.pathSeparator)}
+      </span>
+      {/* The same trailing band, so the broken row lands on the kebab column. */}
+      <div className={ACTION_BAND_CLASS}>
+        <Button
+          variant="ghost"
+          size={sizes.icon}
+          aria-label={actions.labels.remove}
+          className={ACTION_CONTROL_CLASS}
+          /* Outside the roving scheme: a real tab stop keeps it removable. */
+          data-filter-cell="remove"
+          /* It had no gate, so the one row whose purpose is to be removed
+             could be removed from a read-only bar. */
+          disabled={actions.disabled}
+          {...filterReadOnlyProps(actions)}
+          onClick={() => actions.removeNode(rule.id)}
+        >
+          <XIcon
+          />
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Group                                   */
+/* -------------------------------------------------------------------------- */
+
+/** A nested group: an indented card, its conditions, and one way to add
+ * another. The HEADLINE went; the pill outside already says "or". */
+function FilterAdvancedGroup<V, O>({
+  group,
+  position,
+}: {
+  group: FilterGroupNode<V>
+  position: RowPosition
+}) {
+  const actions = useFilterActions<V, O>()
+  const sizes = filterControlSizes(actions)
+  const focusStore = useFilterFocusStore()
+
+  const { query } = useFilterState<V>()
+
+  const issue = useFilterIssue(group.id)
+  const issueText = issue ? filterIssueLabel(issue, actions.labels) : ""
+
+  const reorderable = useFilterReorderable()
+  const canMove = reorderable && canFilterNodeMove(query, position)
+  const rowStateStore = useFilterRowStateStore()
+
+  const slot = filterCombinatorSlot(position.index)
+  const columns = React.useMemo(() => {
+    const list: FilterColumn[] = []
+    if (slot === "toggle") list.push("combinator")
+    // DOM order, which the arrow walker reads: a group's own controls are all
+    // in its footer now, add first and the trailing pair after it.
+    list.push("add")
+    if (canMove) list.push("drag")
+    list.push("menu")
+    return list
+  }, [slot, canMove])
+
+  const active = useActiveColumn(
+    group.id,
+    columns,
+    position.depth === 1 && position.index === 0
+  )
+
+  const onCellFocus = React.useCallback(
+    (column: FilterColumn) => () =>
+      focusStore.set({ id: group.id, segment: column, autoOpen: false }),
+    [focusStore, group.id]
+  )
+
+  const description =
+    group.combinator === "and"
+      ? actions.labels.groupAll
+      : actions.labels.groupAny
+
+  const addInto = () => {
+    const id = addFilterRow(actions, group.id)
+    if (!id) return
+    rowStateStore.markPending(id)
+    focusStore.set({ id, segment: "field", autoOpen: true })
+  }
+
+  return (
+    <div
+      role="group"
+      aria-label={actions.labels.groupLabel(description, position.depth)}
+      data-slot="filter-row"
+      data-node-id={group.id}
+      data-parent-id={position.parentId}
+      data-index={position.index}
+      data-depth={position.depth}
+      /* `flex-wrap` is the whole of the narrow-panel fix. `items-center`
+         measures the flex line, so the pill centres on the card. */
+      className={cn("flex flex-wrap items-center gap-1.5", DROP_SLOT_INDICATOR)}
+    >
+      <div
+        className={cn(
+          COMBINATOR_CLASS,
+          CELL_BOX_CLASS,
+          GROUP_COMBINATOR_WRAP_CLASS
+        )}
+      >
+        <CombinatorCell
+          index={position.index}
+          parentId={position.parentId}
+          combinator={position.combinator}
+          active={active}
+          onFocus={onCellFocus}
+          className={GROUP_COMBINATOR_WRAPPED_CLASS}
+        />
+      </div>
+
+      {/* The CARD lights up as the drop destination, not the header strip the
+          engine measured. This `data-invalid` only styles; the announcement
+          rides the footer's add button, which is the focusable control. */}
+      <div
+        data-slot="filter-group"
+        data-invalid={issue ? "" : undefined}
+        className={GROUP_CARD_CLASS}
+      >
+        {/* Eight pixels, because it is a DROP TARGET and a zone beats a row. */}
+        <div
+          data-slot="filter-group-header"
+          className="flex h-2 items-center"
+          /* The TOP of the card means the top of the list: index 0 PREPENDS.
+             It used to append, so the one place a pointer can aim to say "into
+             this group" put the row at the far other end of it. */
+          data-drop-parent={group.id}
+          data-drop-index={0}
+        />
+
+        {/* A CONTAINER: the box every child row divides up. */}
+        <div
+          className={cn(
+            TRACK_CONTAINER_CLASS,
+            "flex flex-col",
+            FILTER_ROW_GAP_CLASS
+          )}
+        >
+          {group.rules.length === 0 ? (
+            <p
+              className={cn(
+                /* 70% foreground, not the muted token: on the card's tint the
+                   muted foreground measured 4.35:1 in light, under 4.5:1 AA. */
+                "text-foreground/70 rounded-md border border-dashed px-2 py-3",
+                "text-center text-xs",
+                "data-drop-into:border-primary/60 data-drop-into:bg-primary/5",
+                "data-drop-into:text-primary"
+              )}
+              data-slot="filter-group-empty"
+              data-drop-parent={group.id}
+              data-drop-index={0}
+            >
+              {actions.labels.groupPlaceholder}
+            </p>
+          ) : (
+            group.rules.map((node, index) => (
+              <FilterAdvancedNode<V, O>
+                key={node.id}
+                node={node}
+                position={{
+                  index,
+                  parentId: group.id,
+                  combinator: group.combinator,
+                  depth: position.depth + 1,
+                }}
+              />
+            ))
+          )}
+        </div>
+
+        {/* `flex-nowrap`, or the group's kebab leaves the kebab column. */}
+        <div
+          data-slot="filter-group-footer"
+          className="text-muted-foreground flex flex-nowrap items-center gap-2 pt-2 pb-2"
+          data-drop-parent={group.id}
+          data-drop-index={group.rules.length}
+        >
+          <Button
+            variant="outline"
+            size={sizes.button}
+            aria-label={actions.labels.addToGroup}
+            className={cn(
+              /* `shrink` and not merely `min-w-0`: `shrink-0` is baked into
+                 the shadcn button's own base class. */
+              "min-w-0 shrink font-normal",
+              "overflow-hidden",
+              CELL_INVALID_CLASS
+            )}
+            disabled={actions.disabled}
+            {...filterReadOnlyProps(actions)}
+            {...cellProps("add", active)}
+            /* An EMPTY group is flagged on the control that fills it. */
+            {...issueProps(issue, "group", issueText)}
+            onFocus={onCellFocus("add")}
+            onClick={addInto}
+          >
+            <PlusIcon
+            />
+            {actions.labels.addCondition}
+          </Button>
+
+          <div className={cn("ms-auto", ACTION_BAND_CLASS)}>
+            {canMove ? (
+              <RowHandle
+                nodeId={group.id}
+                active={active}
+                onFocus={onCellFocus}
+              />
+            ) : null}
+            <FilterGroupMenu
+              group={group}
+              active={active}
+              onFocus={onCellFocus}
+            />
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/** A group's kebab. A menu row affords six words, where two icons said none. */
+function FilterGroupMenu<V>({
+  group,
+  active,
+  onFocus,
+}: {
+  group: FilterGroupNode<V>
+  active: FilterColumn | null
+  onFocus: (column: FilterColumn) => () => void
+}) {
+  const actions = useFilterActions()
+  const sizes = filterControlSizes(actions)
+  const locked = isFilterLocked(actions)
+  const [open, setOpen] = React.useState(false)
+
+  return (
+    <DropdownMenu
+      open={open}
+      onOpenChange={(next) => {
+        if (next && locked) return
+        setOpen(next)
+      }}
+    >
+      <DropdownMenuTrigger
+        disabled={actions.disabled}
+        {...filterReadOnlyProps(actions)}
+        render={
+          <Button
+            variant="ghost"
+            size={sizes.icon}
+            aria-label={actions.labels.groupMenu}
+            className={ACTION_CONTROL_CLASS}
+            {...cellProps("menu", active)}
+            onFocus={onFocus("menu")}
+          />
+        }
+      >
+        <EllipsisVerticalIcon
+        />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        align="end"
+        className={cn(FILTER_MENU_CLASS, actions.menuClassName)}
+      >
+        <DropdownMenuItem
+          disabled={locked}
+          onClick={() => actions.duplicateNode(group.id)}
+        >
+          <CopyIcon aria-hidden="true" />
+          <span className={FILTER_MENU_LABEL_CLASS}>
+            {actions.labels.duplicate}
+          </span>
+        </DropdownMenuItem>
+        <DropdownMenuItem
+          disabled={locked}
+          onClick={() => actions.unwrapGroup(group.id)}
+        >
+          {/* The inverse of the row menu's layers glyph. */}
+          <UngroupIcon aria-hidden="true" />
+          <span className={FILTER_MENU_LABEL_CLASS}>
+            {actions.labels.ungroup}
+          </span>
+        </DropdownMenuItem>
+        <FilterMoveToMenuItems nodeId={group.id} />
+        <DropdownMenuSeparator />
+        <DropdownMenuItem
+          variant="destructive"
+          disabled={locked}
+          onClick={() => actions.removeNode(group.id)}
+        >
+          {/* No colour: the destructive variant paints the row's svgs. */}
+          <Trash2Icon aria-hidden="true" />
+          <span className={FILTER_MENU_LABEL_CLASS}>
+            {actions.labels.removeGroup}
+          </span>
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+function FilterAdvancedNode<V, O>({
+  node,
+  position,
+}: {
+  node: FilterNode<V>
+  position: RowPosition
+}) {
+  const actions = useFilterActions<V, O>()
+
+  if (!isFilterRule(node)) {
+    return <FilterAdvancedGroup<V, O> group={node} position={position} />
+  }
+  if (!getFilterField(actions.index, node.path)) {
+    return <FilterUnknownRow<V> rule={node} position={position} />
+  }
+  return <FilterAdvancedRow<V, O> rule={node} position={position} />
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Adding                                   */
+/* -------------------------------------------------------------------------- */
+
+/** Appends a condition on the first attribute anyone may filter on, at any
+ * depth. `isFilterFieldPickable` is the picker's own rule. */
+function addFilterRow<V, O>(
+  actions: FilterActionsContextValue<V, O>,
+  parentId?: string
+): string | null {
+  // Before `nextId` and before `addRule`: while the store points at a row that
+  // was never created, the whole panel drops out of the tab order.
+  if (isFilterLocked(actions)) return null
+
+  const entry = actions.index.all.find((candidate) =>
+    isFilterFieldPickable(candidate.field)
+  )
+  if (!entry) return null
+
+  const id = actions.nextId()
+  actions.addRule(
+    createFilterRule<V>({
+      id,
+      path: entry.path,
+      // Deliberately empty: the row arrives PENDING, and a seeded default
+      // would open the next menu with its own answer highlighted.
+      operator: "",
+    }),
+    parentId
+  )
+  return id
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Panel                                   */
+/* -------------------------------------------------------------------------- */
+
+/** The panel draws NO border, NO background and NO radius, and takes no
+ * element to be drawn as: a surface is the page's decision. */
+export interface FiltersAdvancedPanelProps {
+  /** Which of the two boxes the panel sits in, the only thing deciding whether
+   * it pads itself: a popover's content is `p-0`, so this padding IS its
+   * inner padding, and `"inline"` is a page that owns its own. */
+  mode?: "popover" | "inline"
+  /** Replaces the empty state for this panel only. Wins over
+   * `Filters.renderEmpty`, the precedence a field has over the root's. */
+  renderEmpty?: (context: FilterEmptyStateContext) => React.ReactNode
+  /** Whether rows can be reordered. See `FiltersProps.reorderable`. */
+  reorderable?: boolean
+  className?: string
+}
+
+/** The builder itself: nested groups over the query tree the chips read. A
+ * group is a parenthesised list joined by ONE operator, so nesting is a real
+ * tree: a flat model cannot represent `a AND (b OR c)` without inventing
+ * precedence, and invented precedence returns the wrong rows. */
+export function FiltersAdvancedPanel<V, O>({
+  mode = "popover",
+  renderEmpty,
+  reorderable = false,
+  className,
+}: FiltersAdvancedPanelProps) {
+  const actions = useFilterActions<V, O>()
+  const panelRender = useFilterRender<V, O>()
+  const sizes = filterControlSizes(actions)
+  const { query, ruleCount, announcement, announcementSeq } =
+    useFilterState<V>()
+  const focusStore = useFilterFocusStore()
+  const rowStateStore = useFilterRowStateStore()
+  // A version counter, because the store is mutable and stable by identity.
+  const rowStateVersion = React.useSyncExternalStore(
+    rowStateStore.subscribe,
+    () => rowStateStore.version(),
+    () => 0
+  )
+  const bodyRef = React.useRef<HTMLDivElement>(null)
+  const locked = isFilterLocked(actions)
+
+  /* ------------------------------ validation ------------------------------ */
+
+  /** What is unfinished, computed ONCE: an empty group is a fact about a
+   * group, not about any row inside it. */
+  const issues = React.useMemo(
+    () =>
+      collectFilterIssues(
+        query,
+        (rule) => {
+          const field = getFilterField(actions.index, rule.path)
+          if (!field) return null
+          return getFilterArity(
+            getFilterOperator(actions.resolveOperators(field), rule.operator)
+          )
+        },
+        // The same normalisation the display callbacks get.
+        (rule) => {
+          const field = getFilterField(actions.index, rule.path)
+          if (!field?.validate) return null
+          const operator = getFilterOperator(
+            actions.resolveOperators(field),
+            rule.operator
+          )
+          if (!operator) return null
+          return field.validate({
+            value: rule.value,
+            values:
+              rule.value === undefined || rule.value === null
+                ? []
+                : Array.isArray(rule.value)
+                  ? (rule.value as unknown[])
+                  : [rule.value],
+            field,
+            operator,
+            arity: getFilterArity(operator) ?? "one",
+            rule,
+            labels: actions.labels,
+          })
+        }
+      ),
+    [query, actions]
+  )
+
+  /** Every issue, keyed by node: what the tree IS, drawn or not. */
+  const issueMap = React.useMemo(
+    () => new Map(issues.map((issue) => [issue.nodeId, issue])),
+    [issues]
+  )
+
+  /** The issues a row may DRAW: the ones on a value committed once. */
+  const visibleIssueMap = React.useMemo(() => {
+    const visible = new Map<string, FilterIssue>()
+    for (const issue of issues) {
+      // CUSTOM ONLY. The built-in reasons describe a row as HALF BUILT,
+      // so every Add filter produced a red row on the happy path.
+      if (issue.reason !== "custom") continue
+      if (rowStateStore.has(issue.nodeId)) visible.set(issue.nodeId, issue)
+    }
+    return visible
+  }, [issues, rowStateStore, rowStateVersion])
+
+  /** Says out loud that a VISIBLE error has appeared, which would
+   * otherwise happen in silence. The DRAWN issues, on a RISE only. */
+  const announcedIssues = React.useRef({
+    count: visibleIssueMap.size,
+    seq: announcementSeq,
+  })
+  React.useEffect(() => {
+    const before = announcedIssues.current
+    announcedIssues.current = {
+      count: visibleIssueMap.size,
+      seq: announcementSeq,
+    }
+    if (announcementSeq !== before.seq) return
+    if (visibleIssueMap.size <= before.count) return
+    actions.announce(actions.labels.issueSummary(visibleIssueMap.size))
+  }, [visibleIssueMap, announcementSeq, actions])
+
+  /** Sends focus to the first thing that needs it. Walked and not selected
+   * by id: a node id is consumer-supplied, and `CSS.escape` is not
+   * optional in a hand-built selector. */
+  const focusFirstIssue = React.useCallback(() => {
+    const first = issues[0]
+    const body = bodyRef.current
+    if (!first || !body) return
+    const row = Array.from(
+      body.querySelectorAll<HTMLElement>(ROW_SELECTOR)
+    ).find((candidate) => candidate.dataset.nodeId === first.nodeId)
+    if (!row) return
+    // A group's issue is drawn on the add button that resolves it.
+    const column = first.column === "group" ? "add" : first.column
+    const target = ownCells(row).find(
+      (cell) => cell.getAttribute(CELL_ATTRIBUTE) === column
+    )
+    target?.focus()
+  }, [issues])
+
+  /* ---------------------------- focus recovery ---------------------------- */
+
+  /** Whether the panel, or a menu of its own, held focus a moment ago. A
+   * blur WITH a `relatedTarget` is focus arriving somewhere real; a blur
+   * with none, or none at all when the element is simply removed, is what
+   * this exists to repair. */
+  const heldFocus = React.useRef(false)
+  const addRowRef = React.useRef<HTMLButtonElement>(null)
+
+  /** Puts focus back after a mutation that destroyed the thing holding it:
+   * measured at 50, 200, 600 and 1200ms after Convert to group, Remove,
+   * Ungroup and Move to group, `document.activeElement` was the BODY,
+   * because a menu restores focus to a trigger the action unmounted. */
+  const restoreFocus = React.useCallback(() => {
+    // A handoff is mid-air and owns focus: between one step being answered
+    // and the next opening `document.activeElement` IS the body.
+    if (focusStore.getSnapshot().autoOpen) return
+    if (!heldFocus.current) return
+    const active = document.activeElement
+    if (active && active !== document.body) return
+    const rows = Array.from(
+      bodyRef.current?.querySelectorAll<HTMLElement>(ROW_SELECTOR) ?? []
+    )
+    const { id, segment } = focusStore.getSnapshot()
+    const row = id
+      ? rows.find((candidate) => candidate.dataset.nodeId === id)
+      : undefined
+    const cells = row ? ownCells(row) : []
+    const target =
+      cells.find((entry) => entry.getAttribute(CELL_ATTRIBUTE) === segment) ??
+      cells[0] ??
+      (rows[0] ? ownCells(rows[0])[0] : undefined) ??
+      addRowRef.current ??
+      undefined
+    target?.focus()
+  }, [focusStore])
+
+  // In the passive effect, not a frame later: React removes the control in
+  // the mutation phase, so a menu's restore then aims at a detached node.
+  React.useEffect(() => {
+    restoreFocus()
+  }, [query, announcementSeq, restoreFocus])
+
+  /* -------------------------------- adding -------------------------------- */
+
+  const addRow = React.useCallback(() => {
+    const id = addFilterRow(actions)
+    if (!id) return
+    // PENDING until the attribute is chosen, the first of three questions.
+    rowStateStore.markPending(id)
+    focusStore.set({ id, segment: "field", autoOpen: true })
+  }, [actions, focusStore, rowStateStore])
+
+  const addGroup = React.useCallback(() => {
+    const id = actions.addGroup()
+    // An empty id means it refused, and focusing a group never created
+    // would strand the tab stop.
+    if (!id) return
+    // Onto the group's own chrome, not into it: it arrives empty.
+    focusStore.set({ id, segment: "add", autoOpen: false })
+  }, [actions, focusStore])
+
+  /* ------------------------------- keyboard ------------------------------- */
+
+  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    const cell = (event.target as HTMLElement).closest<HTMLElement>(
+      `[${CELL_ATTRIBUTE}]`
+    )
+    // A key pressed inside an open popover belongs to that popover; its
+    // content is portaled out, so this is belt and braces.
+    //
+    // ArrowDown never reaches here: Base UI stops it at the menu trigger.
+    if (!cell || event.target !== cell) return
+
+    const body = bodyRef.current
+    const row = cell.closest<HTMLElement>(ROW_SELECTOR)
+    if (!body || !row) return
+
+    /* A cell the user TYPES into keeps the keys that edit text; only the
+       VERTICAL keys stay. */
+    const editing = cell.hasAttribute(CELL_INPUT_ATTRIBUTE)
+
+    // DOM order for the two places that mean "the whole builder".
+    const rows = Array.from(body.querySelectorAll<HTMLElement>(ROW_SELECTOR))
+    const cells = ownCells(row)
+    const rowIndex = rows.indexOf(row)
+    const cellIndex = cells.indexOf(cell)
+
+    const rtl = getComputedStyle(cell).direction === "rtl"
+    const forward = rtl ? "ArrowLeft" : "ArrowRight"
+    const backward = rtl ? "ArrowRight" : "ArrowLeft"
+
+    const focus = (target: HTMLElement | undefined) => {
+      if (!target) return
+      event.preventDefault()
+      target.focus()
+    }
+
+    const from = cell.getAttribute(CELL_ATTRIBUTE) as FilterColumn
+    const band = (CONTENT_COLUMNS as readonly FilterColumn[]).includes(from)
+      ? CONTENT_COLUMNS
+      : ACTION_COLUMNS
+
+    /* The rows that draw a cell in this BAND, in cell order: by ROW it went
+       BACKWARDS at +212, -166, +122, -76, +38 pixels once a group's own
+       controls moved to its footer. */
+    const bandRows: HTMLElement[] = []
+    const seen = new Set<HTMLElement>()
+    for (const entry of body.querySelectorAll<HTMLElement>(
+      `[${CELL_ATTRIBUTE}]`
+    )) {
+      const column = entry.getAttribute(CELL_ATTRIBUTE) as FilterColumn
+      if (!(band as readonly FilterColumn[]).includes(column)) continue
+      const owner = entry.closest<HTMLElement>(ROW_SELECTOR)
+      if (!owner || seen.has(owner)) continue
+      seen.add(owner)
+      bandRows.push(owner)
+    }
+    const bandIndex = bandRows.indexOf(row)
+
+    const focusRow = (step: number) => {
+      const nextRow = bandRows[bandIndex + step]
+      if (!nextRow) return
+      const cellsThere = ownCells(nextRow)
+      const byColumn = new Map(
+        cellsThere.map((entry) => [entry.getAttribute(CELL_ATTRIBUTE), entry])
+      )
+      // The band, then anything at all, which keeps a consumer's cell
+      // reachable.
+      focus(nearestColumn(band, from, byColumn) ?? cellsThere[0])
+    }
+
+    const nodeId = row.dataset.nodeId
+    if (!nodeId) return
+
+    // Alt reorders rather than navigates, within the owning group only:
+    // changing depth with an arrow would make one gesture mean two things.
+    if (
+      event.altKey &&
+      (event.key === "ArrowUp" || event.key === "ArrowDown")
+    ) {
+      // Plain arrows, Home and End are deliberately NOT gated.
+      if (locked || !reorderable) return
+      event.preventDefault()
+      actions.moveNode(nodeId, event.key === "ArrowDown" ? 1 : -1)
+      return
+    }
+
+    if (event.key === "ArrowDown") return focusRow(1)
+    if (event.key === "ArrowUp") return focusRow(-1)
+    if (editing) return
+
+    if (event.key === forward) return focus(cells[cellIndex + 1])
+    if (event.key === backward) return focus(cells[cellIndex - 1])
+    if (event.key === "Home") {
+      return focus(event.ctrlKey ? ownCells(rows[0])[0] : cells[0])
+    }
+    if (event.key === "End") {
+      const scope = event.ctrlKey ? ownCells(rows[rows.length - 1]) : cells
+      return focus(scope[scope.length - 1])
+    }
+
+    if (event.key === "Backspace" || event.key === "Delete") {
+      if (locked) return
+      event.preventDefault()
+      actions.removeNode(nodeId)
+      // Focus the row that takes this one's place, so removing several
+      // does not throw focus to the body.
+      requestAnimationFrame(() => {
+        const remaining = Array.from(
+          bodyRef.current?.querySelectorAll<HTMLElement>(ROW_SELECTOR) ?? []
+        )
+        const target = remaining[Math.min(rowIndex, remaining.length - 1)]
+        if (target) ownCells(target)[0]?.focus()
+      })
+    }
+  }
+
+  /* --------------------------------- drag --------------------------------- */
+
+  /** Pointer drag, not HTML5 drag and drop: its drag image is a
+   * browser-owned snapshot no copy badge can be drawn on, and a nested
+   * drop would mean hit-testing on every `dragover`. */
+  const dragProps = useFilterRowDrag({
+    // THE PANEL, reached through the body, because the top level's append
+    // zone is in the FOOTER and the footer is the body's sibling.
+    root: () => bodyRef.current?.parentElement ?? null,
+    disabled: locked,
+    onDrop: (nodeId, drop) => {
+      if (drop.copy) actions.copyNodeTo(nodeId, drop.parentId, drop.index)
+      else actions.moveNodeTo(nodeId, drop.parentId, drop.index)
+    },
+  })
+
+  /* -------------------------------- render -------------------------------- */
+
+  const panelProps = {
+    // The panel's programmatic NAME. `group`, because the rows inside are
+    // groups too, so the tree reads as a query rather than as a landmark.
+    role: "group",
+    "aria-label": actions.labels.advancedFilter,
+    // WHAT IS IN IT, on entry, for a reader who did not press the trigger.
+    // The read-only half rides along: `aria-readonly` is illegal here.
+    "aria-description": actions.readOnly
+      ? `${actions.labels.countAnnouncement(ruleCount)} ${actions.labels.readOnly}`
+      : actions.labels.countAnnouncement(ruleCount),
+    "data-slot": "filters-advanced",
+    "data-readonly": actions.readOnly || undefined,
+    // Capture, and on the PANEL, so portaled menus report too.
+    onFocusCapture: () => {
+      heldFocus.current = true
+    },
+    onBlurCapture: (event: React.FocusEvent) => {
+      if (event.relatedTarget) heldFocus.current = false
+    },
+  } as const
+
+  /** The empty state, resolved once: the panel's own prop, else the root's.
+   * Assembled here so a replacement gets the SAME two actions the footer
+   * calls, focus handoff included. */
+  const renderEmptyState = renderEmpty ?? panelRender.renderEmpty
+  const emptyState = renderEmptyState
+    ? renderEmptyState({
+        labels: actions.labels,
+        readOnly: Boolean(actions.readOnly),
+        mode,
+        addFilter: addRow,
+        addGroup,
+      })
+    : null
+
+  const body = (
+    <>
+      {/* VISIBLE, not an ARIA attribute: `aria-readonly` is illegal on every
+          role here, and dimmed controls owe the reader a reason. */}
+      {actions.readOnly ? (
+        <p
+          data-slot="filters-readonly"
+          className={cn("text-muted-foreground text-xs", PANEL_GUTTER_CLASS)}
+        >
+          {actions.labels.readOnly}
+        </p>
+      ) : null}
+
+      {query.rules.length > 0 ? (
+        <div
+          ref={bodyRef}
+          data-slot="filters-advanced-body"
+          /* NO `overflow-x`: nothing here is ever wider than its box. */
+          className={cn(
+            TRACK_CONTAINER_CLASS,
+            "flex min-w-0 flex-col",
+            FILTER_ROW_GAP_CLASS,
+            PANEL_GUTTER_CLASS
+          )}
+          onKeyDown={onKeyDown}
+        >
+          <FilterReorderProvider value={reorderable}>
+            <FilterDragContext.Provider value={reorderable ? dragProps : null}>
+              <FilterIssueContext.Provider value={visibleIssueMap}>
+                {query.rules.map((node, index) => (
+                  <FilterAdvancedNode<V, O>
+                    key={node.id}
+                    node={node}
+                    position={{
+                      index,
+                      parentId: query.id,
+                      combinator: query.combinator,
+                      depth: 1,
+                    }}
+                  />
+                ))}
+              </FilterIssueContext.Provider>
+            </FilterDragContext.Provider>
+          </FilterReorderProvider>
+        </div>
+      ) : /*
+          THE EMPTY STATE, a real state and not a missing one: with no rules
+          the body renders nothing, so the panel used to open as a footer
+          floating in a blank popover. The HINT is withheld when the bar is
+          locked, since it points at two disabled buttons.
+        */
+      // The CALLBACK's presence decides, not its result: a consumer returning
+      // null wants a blank panel, and `??` would hand them the default back.
+      renderEmptyState ? (
+        emptyState
+      ) : (
+        <div
+          data-slot="filters-advanced-empty"
+          className={cn(
+            "flex flex-col items-center justify-center gap-1 py-8 text-center",
+            PANEL_GUTTER_CLASS
+          )}
+        >
+          <span
+            aria-hidden="true"
+            /* `rounded-full` is the one radius literal safe in every
+               style, square or round. */
+            className="bg-muted text-muted-foreground mb-1 flex size-9 items-center justify-center rounded-full [&_svg]:size-4"
+          >
+            <ListFilterIcon
+            />
+          </span>
+          <p className="text-sm font-medium">{actions.labels.builderEmpty}</p>
+          {actions.readOnly ? null : (
+            <p className="text-muted-foreground text-xs">
+              {actions.labels.builderEmptyHint}
+            </p>
+          )}
+        </div>
+      )}
+
+      {/* `shrink-0` on all three: a button clips its label rather than
+          reflowing it, so Clear all read as "ear all filters". */}
+      <div
+        data-slot="filters-advanced-footer"
+        /* THE APPEND TARGET FOR THE TOP LEVEL, which every group's footer had
+           and the root did not: at depth the strip under the last row is a 48px
+           "put it here", while at the root it was 47px of `no-drop`. */
+        data-drop-parent={query.id}
+        data-drop-index={query.rules.length}
+        className={cn(
+          "relative flex flex-wrap items-center gap-2",
+          PANEL_GUTTER_CLASS,
+          /* FOUR PIXELS MORE than the gutter, which is what a row's action
+             band spends after its kebab. */
+          "pe-[calc(var(--filter-panel-pad)+4px)]",
+          FOOTER_DROP_CLASS,
+          /* The strip's BOX reaches the body's bottom edge and pads its
+             content back down, so the append zone TILES with the last row.
+             `pt-5` and not `pt-2`: the row above already grows 4px into this
+             strip, so at `pt-2` the toolbar read as the last filter's tail. */
+          query.rules.length > 0 && cn(FILTER_ROW_GAP_CANCEL_CLASS, "pt-5")
+        )}
+      >
+        <Button
+          /* The last resort of `restoreFocus`: the only control that exists
+             at every query. */
+          ref={addRowRef}
+          /* OUTLINE, and the only pair in the panel with a box: they are
+             what the footer is FOR. */
+          variant="outline"
+          size={sizes.button}
+          className="shrink-0 font-normal"
+          disabled={actions.disabled}
+          {...filterReadOnlyProps(actions)}
+          onClick={addRow}
+        >
+          <PlusIcon
+          />
+          {actions.labels.addCondition}
+        </Button>
+
+        <Button
+          variant="outline"
+          size={sizes.button}
+          className="shrink-0 font-normal"
+          disabled={actions.disabled}
+          {...filterReadOnlyProps(actions)}
+          onClick={addGroup}
+        >
+          <FolderPlusIcon
+          />
+          {actions.labels.addConditionGroup}
+        </Button>
+
+        {/* NO PANEL-LEVEL SUMMARY: a validator's no belongs on the cell. */}
+        {ruleCount > 0 ? (
+          <Button
+            variant="ghost"
+            size={sizes.button}
+            className="text-muted-foreground hover:text-foreground ms-auto shrink-0"
+            disabled={actions.disabled}
+            {...filterReadOnlyProps(actions)}
+            onClick={() => actions.clearQuery()}
+          >
+            {actions.labels.clearAll}
+          </Button>
+        ) : null}
+      </div>
+
+      {/* The `key` is what makes a REPEATED sentence audible: `aria-live`
+          fires on a mutation and React writes nothing when the string is
+          unchanged, so three presses mutated the region once. */}
+      <div aria-live="polite" role="status" className="sr-only">
+        <span key={announcementSeq}>{announcement}</span>
+      </div>
+    </>
+  )
+
+  return (
+    <div
+      {...panelProps}
+      /* An inline style because it is a VALUE: one declaration to beat
+         rather than three classes in three places. */
+      style={
+        {
+          [PANEL_PAD_VAR]:
+            mode === "inline" ? PANEL_PAD_INLINE : PANEL_PAD_POPOVER,
+        } as React.CSSProperties
+      }
+      className={cn(PANEL_CLASS, className)}
+    >
+      {body}
+    </div>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Root                                    */
+/* -------------------------------------------------------------------------- */
+
+export interface FiltersAdvancedProps {
+  /** Where the builder lives. `"popover"` hangs it off a trigger; `"inline"`
+   * renders the same panel with no popup, for a sidebar or a settings page. */
+  mode?: "popover" | "inline"
+  /** Replaces the default trigger. Ignored inline. */
+  trigger?: React.ReactNode
+  /** Whether rows can be reordered. See `FiltersProps.reorderable`. */
+  reorderable?: boolean
+  /** Popover placement. */
+  align?: "start" | "center" | "end"
+  className?: string
+}
+
+export function FiltersAdvanced<V, O>({
+  mode = "popover",
+  trigger,
+  reorderable = false,
+  align = "start",
+  className,
+}: FiltersAdvancedProps) {
+  const actions = useFilterActions<V, O>()
+  const sizes = filterControlSizes(actions)
+  const { ruleCount } = useFilterState<V>()
+  const [open, setOpen] = React.useState(false)
+
+  if (mode === "inline") {
+    return (
+      <FiltersAdvancedPanel<V, O>
+        mode="inline"
+        reorderable={reorderable}
+        className={className}
+      />
+    )
+  }
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      {/* `actions.disabled` alone, and READ ONLY DELIBERATELY DOES NOT
+          GATE IT: opening this panel is reading, not writing. */}
+      <PopoverTrigger
+        /* On the TRIGGER rather than the button below it, so a consumer's own
+           trigger wears the same state. Still `actions.disabled` alone. */
+        disabled={actions.disabled}
+        render={
+          trigger ? (
+            (trigger as React.ReactElement)
+          ) : (
+            <Button
+              variant="outline"
+              size={sizes.button}
+              /* THE COUNT IN THE NAME, not only in the box: a consumer who
+                 replaces `trigger` never had the badge, which is hidden. */
+              aria-label={
+                ruleCount > 0
+                  ? `${actions.labels.advancedFilter}, ${actions.labels.countAnnouncement(ruleCount)}`
+                  : undefined
+              }
+            >
+              <ListFilterIcon
+              />
+              {actions.labels.advancedFilter}
+              {ruleCount > 0 ? (
+                <span
+                  aria-hidden="true"
+                  className="bg-muted text-muted-foreground rounded-sm px-1.5 text-xs tabular-nums"
+                >
+                  {ruleCount}
+                </span>
+              ) : null}
+            </Button>
+          )
+        }
+      />
+      {/* Wide enough for a nested group to keep real words at depth three;
+          the rows truncate rather than wrap. */}
+      <PopoverContent
+        align={align}
+        /* THE POPUP'S OWN NAME: it is a `role="dialog"`, and the panel's is
+           one level in, on its `role="group"`. */
+        aria-label={actions.labels.advancedFilter}
+        className={cn("w-[42rem] max-w-[95vw] p-0", className)}
+      >
+        {/* `mode` defaults to "popover", which keeps the panel's padding. */}
+        <FiltersAdvancedPanel<V, O> reorderable={reorderable} />
+      </PopoverContent>
+    </Popover>
+  )
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-builder.tsx b/apps/web/src/components/reui/filters/filters-builder.tsx
new file mode 100644
index 0000000..c538552
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-builder.tsx
@@ -0,0 +1,303 @@
+import * as React from "react"
+import {
+  Cascader,
+  CascaderEmpty,
+  CascaderList,
+  CascaderPanel,
+  CascaderStatus,
+} from "@/components/reui/cascader/cascader"
+import { CascaderFooter } from "@/components/reui/cascader/cascader-footer"
+import {
+  CascaderBreadcrumb,
+  CascaderInput,
+  CascaderNav,
+} from "@/components/reui/cascader/cascader-nav"
+import type {
+  CascaderActionItem,
+  CascaderLabels,
+  CascaderNode,
+} from "@/components/reui/cascader/cascader-types"
+import { CascaderVirtualItems } from "@/components/reui/cascader/cascader-virtual"
+import {
+  filterControlSizes,
+  filterReadOnlyProps,
+  useFilterActions,
+  useFilterState,
+} from "@/components/reui/filters/filters-context"
+import {
+  FILTER_FIELD_PICKER_CLASS,
+  getFilterField,
+  getFilterFieldCount,
+  joinFilterPath,
+  splitFilterPath,
+} from "@/components/reui/filters/filters-lib"
+import { getDefaultFilterOperator } from "@/components/reui/filters/filters-operators"
+import type { FilterField } from "@/components/reui/filters/filters-types"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { Button } from "@authportal/ui/components/button"
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@authportal/ui/components/popover"
+import { ListFilterPlusIcon } from "lucide-react"
+
+/**
+ * Projects ONLY the field tree: operators or values as nodes would force the
+ * wizard through a combobox that owns the arrows and `aria-activedescendant`.
+ */
+function toCascaderNodes<V, O>(
+  fields: readonly FilterField<V, O>[],
+  parentPath: string[] = []
+): CascaderNode<FilterField<V, O>>[] {
+  return fields.map((field) => {
+    const path = [...parentPath, field.id]
+    const node: CascaderNode<FilterField<V, O>> = {
+      value: joinFilterPath(path),
+      label: field.label,
+      icon: field.icon,
+      description: field.description,
+      keywords: field.keywords,
+      disabled: field.disabled,
+      data: field,
+    }
+    if (field.fields?.length) {
+      node.children = toCascaderNodes(field.fields, path)
+      node.count = getFilterFieldCount(field)
+    }
+    return node
+  })
+}
+
+export interface FilterFieldPickerProps {
+  /** The level being browsed. Not the chosen field. */
+  path: string[]
+  onPathChange: (path: string[]) => void
+  query: string
+  onQueryChange: (query: string) => void
+  /** A field was chosen, with its starting operator already resolved. */
+  onSelect: (path: string[], defaultOperator: string | null) => void
+  /** Viewport height before the list scrolls. */
+  maxHeight?: number
+  /** Cascader-only strings; the `FilterLabels` bridge below covers the rest. */
+  labels?: Partial<CascaderLabels>
+  /** Pinned footer rows, OUT of the option ring so arrows never land on one. */
+  actions?: CascaderActionItem[]
+}
+
+/**
+ * Fully controlled, not draft-driven, so ONE picker serves both the create
+ * popover (driven by the draft reducer) and an advanced row (its own state).
+ */
+export function FilterFieldPicker<V, O>({
+  path,
+  onPathChange,
+  query,
+  onQueryChange,
+  onSelect,
+  maxHeight = 260,
+  labels: labelsProp,
+  actions: actionItems,
+}: FilterFieldPickerProps) {
+  const actions = useFilterActions<V, O>()
+
+  const items = React.useMemo(
+    () => toCascaderNodes(actions.index.roots),
+    [actions.index]
+  )
+
+  // Bridges `FilterLabels` onto the cascader's own key names. `labelsProp` is
+  // spread LAST, so a consumer override always wins.
+  const cascaderLabels = React.useMemo<Partial<CascaderLabels>>(
+    () => ({
+      search: actions.labels.searchFields,
+      back: actions.labels.back,
+      empty: actions.labels.empty,
+      pathSeparator: actions.labels.pathSeparator.trim() || "/",
+      itemCount: actions.labels.itemCount,
+      branchAffordance: actions.labels.branchAffordance,
+      rootLevel: actions.labels.fieldsLabel,
+      panelLabel: actions.labels.fieldsLabel,
+      resultsAnnouncement: actions.labels.resultsAnnouncement,
+      actionsLabel: actions.labels.actionsLabel,
+      ...labelsProp,
+    }),
+    [actions.labels, labelsProp]
+  )
+
+  return (
+    <Cascader
+      inline
+      /* Pinned open: inline renders no popup and forces `open`, so the
+         single-select commit's `setOpen(false)` dismisses nothing. That avoids
+         the `multiple` plus `max` workaround and its `aria-multiselectable`. */
+      open
+      onOpenChange={() => {}}
+      items={items}
+      /* No `selectable` predicate: LEAVES commit, branches navigate. Honouring
+         a branch's opt-in made one click mean both drill and commit. */
+      searchScope="deep"
+      /* Nothing is ever selected, so the ~24px check gutter is dead space. */
+      indicator={false}
+      path={path}
+      onPathChange={onPathChange}
+      /* Controlled: the single-select arm of `commit()` never clears the query,
+         so an uncontrolled one would bleed into the next step. */
+      inputValue={query}
+      onInputValueChange={onQueryChange}
+      value=""
+      onValueChange={(value) => {
+        const nextPath = splitFilterPath(value)
+        const field = getFilterField(actions.index, nextPath)
+        if (!field) return
+        onSelect(
+          nextPath,
+          getDefaultFilterOperator(field, actions.resolveOperators(field))
+        )
+      }}
+      labels={cascaderLabels}
+      actions={actionItems}
+      /* Set here only: `CascaderList` takes its own `maxHeight` and that WINS,
+         so a second copy on the list is a divergence waiting to happen. */
+      maxHeight={maxHeight}
+    >
+      <CascaderPanel>
+        <CascaderNav>
+          <CascaderInput placeholder={actions.labels.searchFields} />
+        </CascaderNav>
+        <CascaderBreadcrumb />
+        <CascaderEmpty />
+        <CascaderList>
+          {/* WINDOWED: the picker is where scale lives and nothing here pins.
+            Below the threshold it renders what `CascaderItems` does. */}
+          <CascaderVirtualItems />
+        </CascaderList>
+        <CascaderFooter />
+        <CascaderStatus />
+      </CascaderPanel>
+    </Cascader>
+  )
+}
+
+function FieldStep<V, O>() {
+  const actions = useFilterActions<V, O>()
+  const { draft } = useFilterState<V>()
+
+  return (
+    <FilterFieldPicker<V, O>
+      path={draft?.cascaderPath ?? []}
+      onPathChange={(next) =>
+        actions.dispatchDraft({ type: "setCascaderPath", path: next })
+      }
+      query={draft?.query ?? ""}
+      onQueryChange={(query) =>
+        actions.dispatchDraft({ type: "setQuery", query })
+      }
+      onSelect={(path, defaultOperator) =>
+        actions.dispatchDraft({ type: "selectField", path, defaultOperator })
+      }
+    />
+  )
+}
+
+export interface FiltersBuilderProps {
+  /** Replaces the default Add filter button. */
+  trigger?: React.ReactNode
+  className?: string
+}
+
+/**
+ * The Add filter popover. ONE panel, the field step: picking a field commits
+ * the rule and opens the operator menu on the new chip. `open` derives from the
+ * draft and `openCreate` is gated, so read-only and disabled shut every route.
+ */
+export function FiltersBuilder<V, O>({
+  trigger,
+  className,
+}: FiltersBuilderProps) {
+  const actions = useFilterActions<V, O>()
+  const sizes = filterControlSizes(actions)
+  const { draft, ruleCount } = useFilterState<V>()
+  const open = draft !== null && draft.ruleId === null
+  // The HANDOFF close, the one that must not FADE: the panel is a 224px card
+  // dissolving over the very menu the user is now meant to read.
+  const committing =
+    draft !== null && draft.ruleId === null && draft.status === "ready"
+  // LATCHED, because `committing` is true for one render only, before the exit
+  // it suppresses begins. Adjusted during render; an effect is one frame late.
+  const [instantExit, setInstantExit] = React.useState(false)
+  if (committing && !instantExit) setInstantExit(true)
+  else if (open && !committing && instantExit) setInstantExit(false)
+  // Icon-only once chips sit beside it. Both states come off ONE size ladder,
+  // so they share height and radius in every style at every bar size. The
+  // hardcoded `icon`/`default` pair this replaced IS the `default` rung, so it
+  // drifted the moment the bar was `sm`.
+  const compact = ruleCount > 0
+
+  // Base UI's own microtask-then-rAF ordering hands focus to the new chip, NOT
+  // anything this file arranges. Suppressing the close restore with
+  // `finalFocus` only removes the fallback that keeps focus off the BODY.
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) actions.closeDraft()
+        else actions.openCreate()
+      }}
+    >
+      <PopoverTrigger
+        /* On the TRIGGER so a consumer's own `trigger` wears the state too. */
+        disabled={actions.disabled}
+        {...filterReadOnlyProps(actions)}
+        render={
+          trigger ? (
+            (trigger as React.ReactElement)
+          ) : (
+            <Button
+              variant="outline"
+              size={compact ? sizes.icon : sizes.button}
+              aria-label={compact ? actions.labels.addFilter : undefined}
+              /* THE RESET BOUNCE: the button's base class carries
+                 `transition-all`, so flipping the size class eased padding 0 to
+                 `px-6` in sera over 150ms. Naming a transition REPLACES it. */
+              className="transition-[color,background-color,border-color,box-shadow]"
+            >
+              {/* No filter-plus glyph in phosphor or remixicon. */}
+              <ListFilterPlusIcon
+              />
+              {compact ? null : actions.labels.addFilter}
+            </Button>
+          )
+        }
+      />
+      {/* The default, then the root override, then this `className` last, so
+        the specific wins. */}
+      <PopoverContent
+        align="start"
+        className={cn(
+          FILTER_FIELD_PICKER_CLASS,
+          /* See `instantExit`. Both PROPERTIES (an `exit` animation AND a
+             transition each paint over the successor) and both twins (Base UI
+             `data-ending-style`, Radix `data-[state=closed]`); only one can
+             match in a given build. The string stays identical on both sides
+             because listing only the Base UI half left the radix twin fading
+             a 224px card over its successor. */
+          instantExit &&
+            cn(
+              "data-ending-style:animate-none data-ending-style:transition-none",
+              "data-[state=closed]:animate-none data-[state=closed]:transition-none"
+            ),
+          actions.fieldPickerClassName,
+          className
+        )}
+      >
+        <FieldStep<V, O> />
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+/** Exported for custom field pickers. */
+export { toCascaderNodes }
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-chip.tsx b/apps/web/src/components/reui/filters/filters-chip.tsx
new file mode 100644
index 0000000..21395e6
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-chip.tsx
@@ -0,0 +1,1069 @@
+import * as React from "react"
+import {
+  filterControlSizes,
+  filterReadOnlyProps,
+  isFilterLocked,
+  useFilterActions,
+  useFilterChipAutoOpen,
+  useFilterChipFocused,
+  useFilterFocusEmpty,
+  useFilterFocusStore,
+  useFilterRender,
+  useFilterReorderable,
+} from "@/components/reui/filters/filters-context"
+import {
+  FilterMenu,
+  useFilterOptions,
+  useFilterValueResolution,
+} from "@/components/reui/filters/filters-editors"
+import {
+  collapseFilterPath,
+  FILTER_MENU_CLASS,
+  FILTER_MENU_LABEL_CLASS,
+  formatFilterPath,
+  getFilterField,
+  getFilterFieldChain,
+} from "@/components/reui/filters/filters-lib"
+import {
+  coerceFilterValue,
+  getFilterArity,
+  getFilterOperator,
+  operatorTakesValue,
+  visibleFilterOperators,
+} from "@/components/reui/filters/filters-operators"
+import {
+  findFilterNode,
+  isFilterGroup,
+} from "@/components/reui/filters/filters-query"
+import type {
+  FilterEditorProps,
+  FilterField,
+  FilterGroupNode,
+  FilterOperator,
+  FilterRule,
+} from "@/components/reui/filters/filters-types"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { Button } from "@authportal/ui/components/button"
+import {
+  ButtonGroup,
+  ButtonGroupText,
+} from "@authportal/ui/components/button-group"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@authportal/ui/components/dropdown-menu"
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@authportal/ui/components/popover"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@authportal/ui/components/tooltip"
+import { ChevronRightIcon, CornerDownRightIcon, CopyIcon, ArrowLeftRightIcon, LayersIcon, SlidersHorizontalIcon, Trash2Icon, XIcon, EllipsisVerticalIcon } from "lucide-react"
+
+/** Which part of the chip a pointer or key is aimed at. No `field`: the chip's
+ *  attribute segment is display only, and only the builder re-picks one. */
+type ChipSegment = "operator" | "value" | "menu"
+
+/** The ref half of `autoFocusProps`: a CALLBACK ref, the one shape an editor
+ *  can spread onto any element without a cast, and a no-op here. */
+const noopAutoFocusRef: React.RefCallback<HTMLElement> = () => {}
+
+function defaultValueDisplay<V>(
+  value: V | undefined,
+  operator: FilterOperator | undefined,
+  resolveOption: (value: string) => { label: string } | undefined,
+  labels: ReturnType<typeof useFilterActions>["labels"],
+  // The field's own word for "no value yet", which a generic label cannot beat.
+  fieldPlaceholder?: string,
+  /** Whether the value is PICKED rather than typed: a select's search prompt
+   *  and "enter text..." both give way to `labels.selectPlaceholder`. */
+  optionBacked?: boolean
+): string {
+  const emptyLabel = optionBacked
+    ? labels.selectPlaceholder
+    : (fieldPlaceholder ?? labels.valuePlaceholder)
+  if (value === undefined || value === null || value === "") {
+    return emptyLabel
+  }
+
+  if (getFilterArity(operator) === "range" && Array.isArray(value)) {
+    const [from, to] = value as unknown[]
+    return labels.valueRange(String(from ?? ""), String(to ?? ""))
+  }
+
+  if (Array.isArray(value)) {
+    const values = value as string[]
+    if (values.length === 0) return emptyLabel
+    if (values.length === 1) {
+      return resolveOption(values[0])?.label ?? String(values[0])
+    }
+    return labels.valueCount(values.length)
+  }
+
+  if (typeof value === "boolean") return value ? "True" : "False"
+
+  return resolveOption(String(value))?.label ?? String(value)
+}
+
+/** The same display with the option's own icon in front. A status filter reads
+ *  as its colour before its word, so dropping the swatch the picker showed
+ *  makes the chip harder to scan than the list it came from. */
+function valueWithIcon<V>(
+  value: V | undefined,
+  text: string,
+  resolveOption: (value: string) => { icon?: React.ReactNode } | undefined
+): React.ReactNode {
+  const single =
+    value === undefined || value === null || Array.isArray(value)
+      ? Array.isArray(value) && value.length === 1
+        ? String(value[0])
+        : null
+      : String(value)
+  const icon = single ? resolveOption(single)?.icon : null
+  if (!icon) return text
+  return (
+    <span className="flex items-center gap-1.5">
+      {icon}
+      {text}
+    </span>
+  )
+}
+
+/** The glyph between two ancestors in a nested attribute path, a chevron
+ *  because the `pathSeparator` string read as loud as the names it parts.
+ *  DECORATIVE: `aria-hidden`, and the plain string is still what
+ *  `formatFilterPath` joins for the chip's accessible name and `title`. */
+function FilterPathSeparator() {
+  return (
+    <ChevronRightIcon aria-hidden="true" data-slot="filter-path-separator" className="text-muted-foreground mx-[3px] inline-block size-3 shrink-0 self-center align-[calc(0.3635em_-_0.375rem)]" />
+  )
+}
+
+/** The elided run of a collapsed path, with the FULL path behind it. THE
+ *  TOOLTIP IS NOT THE ACCESSIBLE ROUTE: it is hover and focus, so the segment
+ *  is `aria-hidden` and the whole path stays in the control's NAME. The host's
+ *  own `title` is dropped while collapsed (`pathCollapsed`) or both fire. */
+function FilterPathEllipsis({ full }: { full: string }) {
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <span
+              aria-hidden="true"
+              data-slot="filter-path-ellipsis"
+              /* A path SEGMENT with no air of its own: the chevron's margin
+                 is all that parts a name from the next, and this used to STACK
+                 an `mx` on it. Plain inline, no `vertical-align`: `middle` sat
+                 the dots 1.7px low and inline-block grew the run to 21.17px. */
+              className="text-muted-foreground shrink-0 self-center"
+            >
+              ...
+            </span>
+          }
+        />
+        <TooltipContent>{full}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  )
+}
+
+/** Everything a rule needs in order to be READ, in either chrome. */
+export interface FilterRuleDisplay {
+  pathText: string
+  pathLabel: React.ReactNode
+  /** Whether `pathLabel` shows fewer names than the path has, so the cell's
+   *  own `title` can step aside for the ellipsis segment's tooltip. */
+  pathCollapsed: boolean
+  operatorLabel: string
+  valueLabel: React.ReactNode
+  /** The same value as PLAIN TEXT, for an accessible name. Never scraped from
+   *  the `renderValue` node: whatever text survives inside avatars and a count
+   *  badge announces "plus one" for two people. Kept separate from
+   *  `valueLabel`, not derived from it: a React node has no honest text to
+   *  read back. A field whose values do not stringify supplies `valueText`
+   *  itself, or the built-in fallback says "[object Object]" to exactly the
+   *  audience the visible display is hiding it from. */
+  valueText: string
+  /** The same value with any collapsed COUNT spelled out. "3 selected" cannot
+   *  be recovered from, which is fine while the editor opens and not once
+   *  locked, so the control carries this as `title` and, locked, as its name. */
+  valueFullText: string
+  valueEmpty: boolean
+}
+
+/** How one rule reads, resolved once and shared by both chromes, so a consumer
+ *  `renderValue`, the field's own and the built-in cannot disagree. */
+export function useFilterRuleDisplay<V, O>(
+  rule: FilterRule<V>,
+  field: FilterField<V, O> | undefined,
+  operator: FilterOperator | undefined
+): FilterRuleDisplay {
+  const actions = useFilterActions<V, O>()
+  const render = useFilterRender<V, O>()
+  // Lazily: a label needs no options until an editor actually opens.
+  const optionsState = useFilterOptions<V, O>(field, false)
+
+  const values =
+    rule.value === undefined || rule.value === null
+      ? []
+      : Array.isArray(rule.value)
+        ? (rule.value as unknown[])
+        : [rule.value]
+
+  // Saved views: values the loader has never returned are resolved through the
+  // field's own `resolveValues`, so a restored chip reads "John Doe", not an id.
+  useFilterValueResolution(field, values)
+
+  const pathText = formatFilterPath(
+    actions.index,
+    rule.path,
+    actions.labels.pathSeparator
+  )
+
+  const chain = getFilterFieldChain(actions.index, rule.path)
+  // The CASCADER's collapser, from the actions context rather than per host, so
+  // a deep path reads the same on a chip and in a builder row.
+  const segments = collapseFilterPath(chain, {
+    maxSegments: actions.maxPathSegments,
+    collapse: actions.pathCollapse,
+  })
+  const pathCollapsed = segments.some((segment) => segment.type === "ellipsis")
+  const pathLabel = chain.length
+    ? segments.map((segment, index) => (
+        <React.Fragment
+          /* Positional, because a field id is unique among its SIBLINGS only:
+             "Company > Team > Company" is a legal path and its two ids collide. */
+          key={
+            segment.type === "field"
+              ? `${index}:${segment.field.id}`
+              : `${index}:ellipsis`
+          }
+        >
+          {index > 0 ? <FilterPathSeparator /> : null}
+          {segment.type === "field" ? (
+            <span>{segment.field.label}</span>
+          ) : (
+            <FilterPathEllipsis full={pathText} />
+          )}
+        </React.Fragment>
+      ))
+    : pathText
+
+  const operatorLabel = operator
+    ? rule.negated
+      ? actions.labels.negated(operator.label)
+      : operator.label
+    : rule.operator || actions.labels.selectCondition
+
+  const valueEmpty =
+    rule.value === undefined ||
+    rule.value === null ||
+    rule.value === ("" as unknown as V) ||
+    values.length === 0
+
+  if (!field) {
+    return {
+      pathText,
+      pathLabel,
+      pathCollapsed,
+      operatorLabel,
+      valueLabel: "",
+      valueText: "",
+      valueFullText: "",
+      valueEmpty,
+    }
+  }
+
+  const valueContext = {
+    value: rule.value,
+    values,
+    field,
+    operator: operator ?? { value: rule.operator, label: rule.operator },
+    // Resolved, not empty: a custom display needs the option behind each value.
+    options: values
+      .map((entry) => optionsState.resolve(String(entry)))
+      .filter(Boolean) as NonNullable<
+      ReturnType<typeof optionsState.resolve>
+    >[],
+    labels: actions.labels,
+  }
+
+  // Computed even when a custom display replaces it: this is the string the
+  // accessible name is built from. `field.valueText` overrides it.
+  const valueText = field.valueText
+    ? field.valueText(valueContext)
+    : defaultValueDisplay(
+        rule.value,
+        operator,
+        optionsState.resolve,
+        actions.labels,
+        field.placeholder,
+        // Option-backed by the FIELD, not the operator: `is any of` is
+        // multi-value on a plain text field too, and that one is typed into.
+        field.type === "select" ||
+          field.type === "multiselect" ||
+          Boolean(field.options?.length) ||
+          Boolean(field.loadOptions)
+      )
+
+  const valueLabel = render.renderValue
+    ? render.renderValue(valueContext)
+    : field.renderValue
+      ? field.renderValue(valueContext)
+      : valueWithIcon(rule.value, valueText, optionsState.resolve)
+
+  // The list behind the count, or the same text again. Multi-value only: a
+  // RANGE also stores an array but already spells both ends out ("10 to 99").
+  const valueFullText =
+    field.valueText ||
+    !Array.isArray(rule.value) ||
+    getFilterArity(operator) === "range" ||
+    values.length < 2
+      ? valueText
+      : actions.labels.valueDetail(
+          valueText,
+          values.map(
+            (entry) =>
+              optionsState.resolve(String(entry))?.label ?? String(entry)
+          )
+        )
+
+  return {
+    pathText,
+    pathLabel,
+    pathCollapsed,
+    operatorLabel,
+    valueLabel,
+    valueText,
+    valueFullText,
+    valueEmpty,
+  }
+}
+
+interface FilterValueEditorProps<V = unknown, O = unknown> {
+  rule: FilterRule<V>
+  field: FilterField<V, O>
+  operator: FilterOperator
+  /** Whether the surface holding it is showing. Gates the option service. */
+  open: boolean
+  onClose: () => void
+}
+
+/** The value editor - draft, option service, commit - with NO surface of its
+ *  own, so surface and wiring can be replaced independently. The draft lives
+ *  here, so a text filter dispatches once on commit, not once per keystroke. */
+function FilterValueEditor<V, O>({
+  rule,
+  field,
+  operator,
+  open,
+  onClose,
+}: FilterValueEditorProps<V, O>) {
+  const actions = useFilterActions<V, O>()
+  const [draft, setDraft] = React.useState<V | undefined>(rule.value)
+
+  React.useEffect(() => {
+    if (open) setDraft(rule.value)
+  }, [open, rule.value])
+
+  const options = useFilterOptions<V, O>(field, open)
+  // A LOOKUP, not a definition: every result is a module-level built-in or the
+  // consumer's own component, so the editor is never remounted mid-edit.
+  const editor = React.useMemo(
+    () => actions.resolveEditor(field, operator),
+    [actions, field, operator]
+  )
+
+  if (!editor) return null
+
+  const editorProps: FilterEditorProps<V, O> = {
+    field,
+    operator,
+    value: draft,
+    onValueChange: (next) => setDraft(next as V),
+    host: "amend",
+    autoFocusProps: {
+      ref: noopAutoFocusRef,
+      autoFocus: true,
+    },
+    commit: (next, commitOptions) => {
+      actions.updateRule(rule.id, {
+        value: (next === undefined ? draft : next) as V,
+      })
+      // A multi-select commits per toggle and asks to stay put; others dismiss.
+      if (commitOptions?.close === false) return
+      onClose()
+    },
+    cancel: onClose,
+    // The same as cancel, honestly: `back` means something only to a `create`
+    // host.
+    back: onClose,
+    options,
+    labels: actions.labels,
+  }
+
+  // `createElement` rather than JSX: the component comes out of a lookup, so
+  // `<Editor />` trips `react-hooks/static-components`. The fragment keeps the
+  // props object, which carries a ref, from looking like a ref read in render.
+  return <>{React.createElement(editor, editorProps)}</>
+}
+
+/** One step of the flow, released when the panel that owes it has LEFT THE
+ *  DOM: both popovers keep portal content mounted through the exit transition,
+ *  so this unmount IS that moment and nothing is timed. `onRelease` is used AS
+ *  the cleanup, so an unmemoized callback fires its step early. */
+function FilterStepHandoff({ onRelease }: { onRelease: () => void }) {
+  React.useEffect(() => onRelease, [onRelease])
+  return null
+}
+
+/** The value host: the editor in a popover anchored to the value segment, and
+ *  BOTH routes end here. The operator popover used to draw the editor itself,
+ *  so a handed-off panel sat a segment's width left of a second press. */
+export interface FilterValuePopoverProps<V = unknown, O = unknown> {
+  rule: FilterRule<V>
+  field: FilterField<V, O>
+  operator: FilterOperator | undefined
+  /** The element that opens it, WITH its own children: a chip segment must be
+   *  a direct child of its `ButtonGroup` for the pill to fuse. */
+  trigger: React.ReactElement
+  className?: string
+}
+
+export function FilterValuePopover<V, O>({
+  rule,
+  field,
+  operator,
+  trigger,
+  className,
+}: FilterValuePopoverProps<V, O>) {
+  const actions = useFilterActions<V, O>()
+  const focusStore = useFilterFocusStore()
+  const autoOpen = useFilterChipAutoOpen(rule.id) === "value"
+  const [open, setOpen] = React.useState(false)
+  const locked = isFilterLocked(actions)
+
+  // The last step of the flow as well as the amend route; by now the condition
+  // menu has UNMOUNTED (see `FilterStepHandoff`). CONSUMED as it is honoured,
+  // or Escape closes the editor and this effect reopens it in the same frame.
+  // The `set` stays OUTSIDE the `locked` guard on purpose: a handoff nobody
+  // spends sits armed until some later chip spends it, and a chip that opened
+  // because a DIFFERENT chip was arrowed onto is worse than one that opened
+  // nothing.
+  React.useEffect(() => {
+    if (!autoOpen || open) return
+    if (!locked) setOpen(true)
+    focusStore.set({ id: rule.id, segment: "value", autoOpen: false })
+  }, [autoOpen, open, focusStore, rule.id, locked])
+
+  // Nothing to open, but the trigger still renders so the value keeps its
+  // place, and it wears the bar's state: that hangs on the TRIGGER below,
+  // which this path never reaches, so the segment used to look live.
+  if (!operator || !actions.resolveEditor(field, operator)) {
+    return React.cloneElement(
+      trigger as React.ReactElement<Record<string, unknown>>,
+      { disabled: actions.disabled, ...filterReadOnlyProps(actions) }
+    )
+  }
+
+  return (
+    // REFUSES to open while locked rather than leaving it to the trigger: an
+    // `aria-disabled` control that still opens an editor is one that lied.
+    <Popover
+      open={open}
+      onOpenChange={(next) => {
+        if (next && locked) return
+        setOpen(next)
+      }}
+    >
+      {/* The trigger IS the segment, never a wrapper. `ButtonGroup` fuses
+          DIRECT children only (`*:data-slot:rounded-r-none`,
+          `[&>[data-slot]~[data-slot]]:border-l-0`), so a nested one keeps its
+          own border and the chip reads as separate badges. */}
+      <PopoverTrigger
+        render={trigger}
+        disabled={actions.disabled}
+        {...filterReadOnlyProps(actions)}
+      />
+      <PopoverContent align="start" className={cn("w-auto p-0", className)}>
+        <FilterValueEditor<V, O>
+          rule={rule}
+          field={field}
+          operator={operator}
+          open={open}
+          onClose={() => {
+            setOpen(false)
+            focusStore.set({ id: rule.id, segment: "value", autoOpen: false })
+          }}
+        />
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+/* A chip's ATTRIBUTE is fixed once the chip exists: no field popover here. A
+   new field invalidates the operator and the value, so "amending" threw both
+   away. The builder keeps its picker, where a row reads as a form. */
+
+/** The condition menu, and the step after it. The list is the cascader run
+ *  flat: the old hand-rolled one marked the keyboard HIGHLIGHT with
+ *  `aria-selected` and had no Home, End or typeahead. It HANDS OFF to the
+ *  value popover once its own panel has left the DOM; advancing in place
+ *  anchored the editor to the CONDITION segment and doubled up in the row. */
+export interface FilterOperatorPopoverProps<V = unknown, O = unknown> {
+  rule: FilterRule<V>
+  field: FilterField<V, O>
+  trigger: React.ReactElement
+  className?: string
+}
+
+export function FilterOperatorPopover<V, O>({
+  rule,
+  field,
+  trigger,
+  className,
+}: FilterOperatorPopoverProps<V, O>) {
+  const actions = useFilterActions<V, O>()
+  const focusStore = useFilterFocusStore()
+  const autoOpen = useFilterChipAutoOpen(rule.id) === "operator"
+  const [open, setOpen] = React.useState(false)
+  const locked = isFilterLocked(actions)
+  /** Whether the close this panel is going through IS the step being handed
+   *  on. A ref, so it survives the render that closes the popover. Every OPEN
+   *  clears it, so an Escape or an outside press finds it already lowered and
+   *  spends nothing; `release` leaves it standing because one twin asks again
+   *  later: Radix reads it from `onCloseAutoFocus`, a macrotask after the
+   *  unmount. Clearing it in `release` would break that twin only. */
+  const handoff = React.useRef(false)
+  const operators = actions.resolveOperators(field)
+  const operator = getFilterOperator(operators, rule.operator)
+
+  // Memoized because the array IS the menu's identity: the cascader rebuilds
+  // its index per `items` identity, so a fresh array rebuilds it per keystroke.
+  const items = React.useMemo(
+    () =>
+      visibleFilterOperators(operators).map((entry) => ({
+        value: entry.value,
+        label: entry.label,
+      })),
+    [operators]
+  )
+
+  // Opened by the root the moment the chip is created. CONSUMED here, or the
+  // handoff re-opens the menu on the frame Escape closes it. Consumed even
+  // while locked, for the reason on the value popover's copy.
+  React.useEffect(() => {
+    if (!autoOpen || open) return
+    handoff.current = false
+    if (!locked) setOpen(true)
+    focusStore.set({ id: rule.id, segment: "operator", autoOpen: false })
+  }, [autoOpen, open, focusStore, rule.id, locked])
+
+  const close = () => {
+    handoff.current = false
+    setOpen(false)
+    focusStore.set({ id: rule.id, segment: "operator", autoOpen: false })
+  }
+
+  /** The parked step, spent on the frame this panel stops existing. Memoized
+   *  on nothing that changes, and load bearing: `FilterStepHandoff` uses this
+   *  AS its cleanup, so a new identity mid-flow fires the step too early. */
+  const release = React.useCallback(() => {
+    if (!handoff.current) return
+    focusStore.set({ id: rule.id, segment: "value", autoOpen: true })
+  }, [focusStore, rule.id])
+
+  // The chip going away takes its step with it: React destroys a deleted
+  // subtree top down, so this runs before the panel's own cleanup.
+  React.useEffect(
+    () => () => {
+      handoff.current = false
+    },
+    []
+  )
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(next) => {
+        if (next && locked) return
+        /* Escape, an outside press, a second press: none is the step being
+           taken, so none may spend it. RETIRED ON OPEN, not on close, and that
+           is a twin difference: in Radix an item choice dismisses through here
+           too, so retiring on close wiped the request before the unmount. */
+        if (next) handoff.current = false
+        setOpen(next)
+      }}
+    >
+      <PopoverTrigger
+        render={trigger}
+        disabled={actions.disabled}
+        {...filterReadOnlyProps(actions)}
+      />
+      <PopoverContent
+        align="start"
+        /* Base UI restores focus to the trigger as this panel closes, which
+           lands on the condition segment AFTER the value editor has opened and
+           focused its input, so a keyboard user is dropped back a step and
+           cannot reach the value at all. Suppressed only while the handoff is
+           up; a function because Base UI resolves it at close time, which is
+           when the ref is accurate. Radix runs the same guard through
+           `onCloseAutoFocus`. */
+        finalFocus={() => !handoff.current}
+        /* `w-auto` with a FLOOR: a catalog sizes to its longest label, and a
+           boolean field's "is" and "is not" would read as a scrap of paper. */
+        className={cn("w-auto min-w-40 p-0", className)}
+      >
+        {/* INSIDE the panel deliberately: only a child of the content is
+            unmounted by the exit transition rather than by the close. */}
+        <FilterStepHandoff onRelease={release} />
+        <FilterMenu
+          items={items}
+          selected={rule.operator ? [rule.operator] : []}
+          onSelectionChange={(values) => {
+            const value = values[0]
+            /* Deselecting the committed operator is a step back rather than a
+               choice, so pressing the current row simply closes. */
+            if (value === undefined) {
+              close()
+              return
+            }
+            const chosen = getFilterOperator(operators, value)
+            /* BUILDING versus AMENDING, the same fork the advanced row draws
+               at its field step. A rule reaches this menu with no operator
+               exactly once, while it is being added, and only then is the
+               value the step after this one. Re-picking the condition on a
+               rule that already has one is an edit of that one cell: it
+               commits and closes, and the user opens the value themselves. */
+            const building = !rule.operator
+            actions.updateRule(rule.id, {
+              operator: value,
+              /* The value moves with the operator: "is" to "is any of" would
+                 leave a bare string where every reader expects an array. */
+              value: coerceFilterValue(
+                rule.value,
+                getFilterOperator(operators, rule.operator),
+                chosen
+              ) as V,
+            })
+            if (building && operatorTakesValue(chosen)) {
+              /* PARKED, not opened: `release` hands the row to its value
+                 surface once this panel has unmounted. */
+              handoff.current = true
+              setOpen(false)
+              return
+            }
+            close()
+          }}
+          labels={actions.labels}
+          ariaLabel={field.label}
+          searchPlaceholder={actions.labels.searchOperators}
+          /* No visible search field: a CLOSED enum of six to ten labels, all
+             on screen. Still RENDERED, visually hidden, because it owns focus
+             and `aria-activedescendant`: arrows, Home, End and typeahead. */
+          searchable={false}
+          /* Taller than a value list on purpose: the operator set is CLOSED, so
+             all of it fits and the height buys the whole catalog. A value list
+             is open ended and would only push its own footer off the screen. */
+          maxHeight={320}
+          /* Deliberately unpinned: one selected operator in a short list, so
+             lifting it would lose the catalog's declared reading order. */
+        />
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+/** The keyboard path to a CROSS-GROUP move: Alt+Arrow reorders within the
+ *  owning group only and Wrap creates a NEW group, so the drag layer's
+ *  cross-group move had no keyboard parity. Numbered in document order. */
+export function FilterMoveToMenuItems({ nodeId }: { nodeId: string }) {
+  const actions = useFilterActions()
+  // A menu ITEM takes the native word: both twins already make `disabled`
+  // roving-focusable and `aria-disabled`.
+  const reorderable = useFilterReorderable()
+  const locked = isFilterLocked(actions)
+  // Read at render time: the menu's content mounts when the menu opens, so
+  // this is the tree the user is looking at.
+  const query = actions.getQuery()
+  const found = findFilterNode(query, nodeId)
+  if (!found || !found.parent) return null
+
+  const destinations: { id: string; label: string; size: number }[] = []
+  if (found.parent.id !== query.id) {
+    destinations.push({
+      id: query.id,
+      label: actions.labels.moveToTopLevel,
+      size: query.rules.length,
+    })
+  }
+
+  let position = 0
+  // `inside` suppresses the PUSH and not the walk, so the numbering stays
+  // document order rather than renumbering every group after this one. Counted
+  // before the exclusions for the same reason: the current parent is not
+  // offered but still holds its number, so the numbering is stable whichever
+  // row's menu is open.
+  const visit = (group: FilterGroupNode<unknown>, inside: boolean) => {
+    for (const child of group.rules) {
+      if (!isFilterGroup(child)) continue
+      position += 1
+      // Itself and everything under it: `moveFilterNodeTo` already refuses that
+      // move - it would detach the subtree and leave a cycle - so offering it
+      // would be a menu row that quietly does nothing.
+      const within = inside || child.id === nodeId
+      if (!within && child.id !== found.parent!.id) {
+        destinations.push({
+          id: child.id,
+          label: actions.labels.moveToGroup(position),
+          size: child.rules.length,
+        })
+      }
+      visit(child, within)
+    }
+  }
+  visit(query, false)
+
+  if (destinations.length === 0) return null
+
+  // The THIRD route into a move, gated on the same switch as the grip and
+  // Alt+Arrow: ungated, a builder that draws no handle still reordered here.
+  if (!reorderable) return null
+
+  return (
+    <>
+      {destinations.map((destination) => (
+        <DropdownMenuItem
+          key={destination.id}
+          disabled={locked}
+          onClick={() =>
+            actions.moveNodeTo(nodeId, destination.id, destination.size)
+          }
+        >
+          {/* A bend into the destination: movement, not duplication or nesting. */}
+          <CornerDownRightIcon aria-hidden="true" />
+          <span className={FILTER_MENU_LABEL_CLASS}>{destination.label}</span>
+        </DropdownMenuItem>
+      ))}
+    </>
+  )
+}
+
+/** The per-rule actions, without the trigger: the chip's kebab and a builder
+ *  row's kebab act on the same rule. `allowGrouping` is the CHROME's answer;
+ *  "Convert to advanced filter" is the CONSUMER's, and hides itself there. */
+export function FilterRuleMenuItems({
+  ruleId,
+  /** Offer "Wrap in condition group". Off for the chip row, which cannot draw
+   *  a group; on in the builder, the only way to nest without dragging. */
+  allowGrouping = false,
+}: {
+  ruleId: string
+  allowGrouping?: boolean
+}) {
+  const actions = useFilterActions()
+  // Gated here as well as at the trigger, because this is EXPORTED: a consumer
+  // composing their own menu gets rows that say they are unavailable.
+  const locked = isFilterLocked(actions)
+  return (
+    /* Every row leads with an icon. `IconPlaceholder` because the source ships
+       under five icon sets; no size class, because each style already sizes an
+       unsized svg in a menu row; `aria-hidden`, the label IS the name. */
+    <>
+      <DropdownMenuItem
+        disabled={locked}
+        onClick={() => actions.duplicateNode(ruleId)}
+      >
+        <CopyIcon aria-hidden="true" />
+        <span className={FILTER_MENU_LABEL_CLASS}>
+          {actions.labels.duplicate}
+        </span>
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        disabled={locked}
+        onClick={() => actions.negateRule(ruleId)}
+      >
+        {/* Two arrows swapping: negation flips to the declared inverse. */}
+        <ArrowLeftRightIcon aria-hidden="true" />
+        <span className={FILTER_MENU_LABEL_CLASS}>{actions.labels.negate}</span>
+      </DropdownMenuItem>
+      {allowGrouping ? (
+        <DropdownMenuItem
+          disabled={locked}
+          onClick={() => actions.wrapNodeInGroup(ruleId)}
+        >
+          {/* Layers: braces read as grouping in only three of the five sets. */}
+          <LayersIcon aria-hidden="true" />
+          <span className={FILTER_MENU_LABEL_CLASS}>
+            {actions.labels.wrapInGroup}
+          </span>
+        </DropdownMenuItem>
+      ) : null}
+      {allowGrouping ? <FilterMoveToMenuItems nodeId={ruleId} /> : null}
+      {/* OPTIONAL, and gated on both halves of "would this do anything": the
+          handler is the consumer's opt-in, and an already-advanced bar has
+          nothing to convert. NOT gated on `locked`: it changes no query, is
+          handed no mutator, and the shipped kebab will not open while locked. */}
+      {actions.convertToAdvanced && actions.variant !== "advanced" ? (
+        <DropdownMenuItem onClick={() => actions.convertToAdvanced?.()}>
+          {/* Sliders: the one "advanced settings" glyph in all five sets. */}
+          <SlidersHorizontalIcon aria-hidden="true" />
+          <span className={FILTER_MENU_LABEL_CLASS}>
+            {actions.labels.convertToAdvanced}
+          </span>
+        </DropdownMenuItem>
+      ) : null}
+      <DropdownMenuItem
+        variant="destructive"
+        disabled={locked}
+        onClick={() => actions.removeNode(ruleId)}
+      >
+        {/* No colour: the destructive variant already paints the row's svgs. */}
+        <Trash2Icon aria-hidden="true" />
+        <span className={FILTER_MENU_LABEL_CLASS}>{actions.labels.remove}</span>
+      </DropdownMenuItem>
+    </>
+  )
+}
+
+export interface FilterChipProps<V = unknown> {
+  rule: FilterRule<V>
+  index: number
+}
+
+/** One filter, as a chip. Memoization means something here: the actions
+ *  context is stable, the focus store is subscribed to a boolean and the query
+ *  shares structure, so editing one filter of forty re-renders one chip. */
+function FilterChipImpl<V, O>({ rule, index }: FilterChipProps<V>) {
+  const actions = useFilterActions<V, O>()
+  const render = useFilterRender<V, O>()
+  const focusStore = useFilterFocusStore()
+  const focused = useFilterChipFocused(rule.id)
+  const noFocus = useFilterFocusEmpty()
+  const locked = isFilterLocked(actions)
+  // THE CHIP'S HEIGHT, by way of the one button in it that has one:
+  // `ButtonGroup` is `items-stretch` and no style gives a text segment a
+  // height, so the kebab's rung is the pill's. The RADIUS survives because
+  // every style whose `icon-sm` rounds differently re-pins it in a group.
+  const sizes = filterControlSizes(actions)
+  // The kebab is CONTROLLED so it can refuse to open: every mutating row
+  // behind it is gated. That puts "Convert to advanced filter" out of reach
+  // while locked; a consumer-composed menu still draws it.
+  const [menuOpen, setMenuOpen] = React.useState(false)
+  // Exactly one chip is in the tab order at a time. Before anything has been
+  // focused that is the first chip, so Tab reaches the row in one press.
+  const isTabStop = focused || (noFocus && index === 0)
+
+  const field = getFilterField(actions.index, rule.path)
+  const operators = field ? actions.resolveOperators(field) : []
+  const operator = getFilterOperator(operators, rule.operator)
+
+  const {
+    pathText,
+    pathLabel,
+    pathCollapsed,
+    operatorLabel,
+    valueLabel,
+    valueText,
+    valueFullText,
+    valueEmpty,
+  } = useFilterRuleDisplay<V, O>(rule, field, operator)
+
+  if (!field) {
+    // A rule pointing at a field the schema no longer has. Dropping it loses a
+    // saved view's data; rendering nothing leaves an invisible condition still
+    // filtering. It carries the SAME roving wiring as a real chip: `data-slot`
+    // alone joined the arrow-key query with no `tabIndex` to land on.
+    return (
+      <ButtonGroup
+        data-slot="filter-chip"
+        data-unknown=""
+        role="group"
+        aria-label={actions.labels.filterLabel(
+          rule.path.join(actions.labels.pathSeparator)
+        )}
+        data-focused={focused || undefined}
+        data-rule-id={rule.id}
+        data-index={index}
+        tabIndex={isTabStop ? 0 : -1}
+        onFocusCapture={() => {
+          if (!focused)
+            focusStore.set({ id: rule.id, segment: null, autoOpen: false })
+        }}
+      >
+        <ButtonGroupText className="bg-background dark:bg-input/30 text-muted-foreground">
+          {rule.path.join(actions.labels.pathSeparator)}
+        </ButtonGroupText>
+        <Button
+          variant="outline"
+          size={sizes.icon}
+          className="bg-background dark:bg-input/30"
+          aria-label={actions.labels.remove}
+          /* It had no gate at all, so the one chip whose whole purpose is to be
+             removed could be removed from a bar that refuses every other edit. */
+          disabled={actions.disabled}
+          {...filterReadOnlyProps(actions)}
+          onClick={() => actions.removeNode(rule.id)}
+        >
+          <XIcon
+          />
+        </Button>
+      </ButtonGroup>
+    )
+  }
+
+  if (render.renderChip) return <>{render.renderChip(rule)}</>
+
+  const focusSegment = (segment: ChipSegment) =>
+    focusStore.set({ id: rule.id, segment, autoOpen: false })
+
+  // A rule with no condition yet, KEPT rather than removed (see
+  // `isFilterRuleComplete`), so it has to read as unfinished. Through WORDS:
+  // the dashed outline it replaces degraded to an underline under sera.
+  const incomplete = !rule.operator
+
+  // The same test the value segment renders under, so the name matches the
+  // chip: `valueText` alone appended a placeholder to valueless conditions.
+  const hasValue = Boolean(rule.operator) && operatorTakesValue(operator)
+
+  // The value's spoken form in the chip's NAME: a name is not a prompt, so
+  // "Description contains enter text..." becomes "no value".
+  const valueName =
+    valueEmpty && !field.valueText ? actions.labels.noValue : valueText
+
+  return (
+    <ButtonGroup
+      data-slot="filter-chip"
+      role="group"
+      aria-label={actions.labels.filterLabel(
+        `${pathText} ${operatorLabel}${hasValue ? ` ${valueName}` : ""}`.trim() +
+          (incomplete ? `, ${actions.labels.incomplete}` : "")
+      )}
+      data-focused={focused || undefined}
+      data-incomplete={incomplete || undefined}
+      data-rule-id={rule.id}
+      tabIndex={isTabStop ? 0 : -1}
+      className={cn(
+        /* Sera is an underline style, so the boxed segments are normalised to
+           its bottom-border-only look or the chip reads as a mix of both. */
+        ""
+      )}
+      onFocusCapture={() => {
+        if (!focused)
+          focusStore.set({ id: rule.id, segment: null, autoOpen: false })
+      }}
+      data-index={index}
+    >
+      {/* DISPLAY ONLY: a div, not a button, not a tab stop, no popover. The
+          attribute is fixed for the life of the chip. */}
+      <ButtonGroupText
+        /* Dropped while the path is collapsed: the ellipsis inside carries the
+           same sentence as a tooltip, and the two would stack. */
+        title={pathCollapsed ? undefined : pathText}
+        className="bg-background dark:bg-input/30 cursor-default gap-1.5"
+      >
+        {field.icon}
+        {/* Zero gap INSIDE the path, so the separator's own margin is the only
+            air around a chevron; `gap-1.5` used to stack 6px a side on it. */}
+        <span className="flex items-center">{pathLabel}</span>
+      </ButtonGroupText>
+
+      <FilterOperatorPopover
+        rule={rule}
+        field={field}
+        trigger={
+          <ButtonGroupText
+            render={<button type="button" />}
+            className={cn(
+              "hover:bg-accent bg-background dark:bg-input/30 cursor-default",
+              /* The operator is connective tissue between the field and the
+                 value, so it reads quieter than either - unless it is still
+                 the prompt "Select condition", the one thing to act on. */
+              incomplete ? "text-foreground" : "text-muted-foreground"
+            )}
+            onPointerDown={() => focusSegment("operator")}
+          >
+            {operatorLabel}
+          </ButtonGroupText>
+        }
+      />
+
+      {/* No condition, no value: `getFilterArity(undefined)` defaults to "one",
+          so testing the operator alone renders a stray value segment. */}
+      {hasValue ? (
+        <FilterValuePopover
+          rule={rule}
+          field={field}
+          operator={operator}
+          trigger={
+            <ButtonGroupText
+              render={<button type="button" />}
+              /* Named explicitly rather than by its contents: avatars or a
+                 "+2" badge, and "plus two" says nothing about two people. It
+                 grows to the whole list when the editor cannot be opened,
+                 since locked it must carry what a press no longer reveals. */
+              aria-label={locked ? valueFullText : valueText}
+              /* The pointer's route to the same thing, and only when there is
+                 more to say than the segment already says. */
+              title={valueFullText === valueText ? undefined : valueFullText}
+              className={cn(
+                "hover:bg-accent bg-background dark:bg-input/30 cursor-default",
+                valueEmpty && "text-muted-foreground"
+              )}
+              onPointerDown={() => focusSegment("value")}
+            >
+              {valueLabel}
+            </ButtonGroupText>
+          }
+        />
+      ) : null}
+
+      <DropdownMenu
+        open={menuOpen}
+        onOpenChange={(next) => {
+          if (next && locked) return
+          setMenuOpen(next)
+        }}
+      >
+        <DropdownMenuTrigger
+          disabled={actions.disabled}
+          {...filterReadOnlyProps(actions)}
+          render={
+            <Button
+              variant="outline"
+              size={sizes.icon}
+              /* The same surface the three text segments force. Styles whose
+                 outline button is transparent in dark (sera, luma, rhea) left
+                 the kebab as a notch in an otherwise filled pill. */
+              className="bg-background dark:bg-input/30"
+              aria-label={actions.labels.chipMenu(field.label)}
+              onPointerDown={() => focusSegment("menu")}
+            />
+          }
+        >
+          <EllipsisVerticalIcon
+          />
+        </DropdownMenuTrigger>
+        {/* The SAME sizing the builder's menus use, from one constant: a menu
+            that cuts "Convert to group" in one chrome is one defect twice. */}
+        <DropdownMenuContent
+          align="end"
+          className={cn(FILTER_MENU_CLASS, actions.menuClassName)}
+        >
+          <FilterRuleMenuItems ruleId={rule.id} />
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </ButtonGroup>
+  )
+}
+
+export const FilterChip = React.memo(FilterChipImpl) as typeof FilterChipImpl
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-context.tsx b/apps/web/src/components/reui/filters/filters-context.tsx
new file mode 100644
index 0000000..479a428
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-context.tsx
@@ -0,0 +1,662 @@
+"use client"
+
+import * as React from "react"
+import type { FilterDraftAction } from "@/components/reui/filters/filters-draft"
+import type { FilterPathCollapse } from "@/components/reui/filters/filters-lib"
+import type {
+  FilterCombinator,
+  FilterDraft,
+  FilterDraftStep,
+  FilterEditor,
+  FilterEditorRegistry,
+  FilterEmptyStateContext,
+  FilterField,
+  FilterIndex,
+  FilterLabels,
+  FilterOperator,
+  FilterOption,
+  FilterQuery,
+  FilterRule,
+  FilterValueDisplayContext,
+  FilterValueType,
+} from "@/components/reui/filters/filters-types"
+
+/** Four publishing channels, not one, so a chip never re-renders at the rate
+ *  of the fastest: `actions` republishes on a schema, labels or config change,
+ *  `state` on every query edit and keystroke, `render` on a `renderValue` /
+ *  `renderChip` identity change, `focus` on every arrow key. The reorder flag
+ *  and the row-state store further down are contexts too, but not channels the
+ *  query is published through. */
+
+/* -------------------------------------------------------------------------- */
+/*                                   Actions                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Stable for the life of the component, bar a config change. Every mutator
+ *  reads a latest-props ref rather than closing over the state it needs, so a
+ *  keystroke rebuilds no handler and no memoized chip re-renders. The two lock
+ *  flags are published rather than kept only in that ref: a refusal that lives
+ *  in a ref arrives one commit late. The two resolvers are the deliberate
+ *  exception: they are read DURING render, so they memoize on the values they
+ *  read instead of going through the ref. Every mutator is also the MUTATION
+ *  BOUNDARY - `disabled` and `readOnly` are enforced here, not at the call
+ *  sites that draw the buttons, so a route added next month is refused by
+ *  construction rather than by remembering. See `isFilterLocked`. */
+export interface FilterActionsContextValue<V = unknown, O = unknown> {
+  /** Normalized schema. Also on the state context, from the same memo. */
+  index: FilterIndex<V, O>
+  labels: FilterLabels
+  operatorCatalog: Record<FilterValueType, FilterOperator[]>
+  editors: FilterEditorRegistry
+  size: "sm" | "default"
+  /** The bar is off: nothing operable, and the controls leave the tab order. */
+  disabled: boolean
+  /** Readable and navigable, but not changeable. See `isFilterLocked`. */
+  readOnly: boolean
+
+  /** Which chrome is drawing, so a chip kebab can hide its convert row. */
+  variant: "basic" | "advanced"
+
+  /** Consumer classes for the menus and the field picker, merged AFTER the
+   *  primitive's own defaults so a consumer `w-*` wins through tailwind-merge
+   *  rather than on source order. On the context: four chromes mount the same
+   *  menu, and a per-chrome prop is set in four places and missed in a fifth. */
+  menuClassName: string | undefined
+  fieldPickerClassName: string | undefined
+
+  /** Turns on the chip kebab's "Convert to advanced filter" row: present means
+   *  offered. A callback with no boolean beside it, since only the consumer
+   *  can switch chromes. Changes no query, so it skips the mutation boundary,
+   *  which is safe only because it is handed no setter: a consumer's handler
+   *  has no route to the query at all. */
+  convertToAdvanced: (() => void) | undefined
+
+  /** Path shortening, published so BOTH chromes render the same path. */
+  pathCollapse: FilterPathCollapse
+  maxPathSegments: number
+
+  /** Operators for a field, memoized on the catalog and the schema. */
+  resolveOperators: (field: FilterField<V, O>) => FilterOperator[]
+  resolveEditor: (
+    field: FilterField<V, O>,
+    operator: FilterOperator | undefined
+  ) => FilterEditor<V, O> | undefined
+  /** Value-to-label store shared by every `useFilterOptions` under the root. */
+  resolution: FilterResolutionStore
+
+  /** Appends a rule. Defaults to the ROOT group. The parent is a parameter
+   *  rather than always the root because a nested group's add button is the
+   *  keyboard path into that group, and routing it through the root then
+   *  moving it would be two edits and two announcements for one action. */
+  addRule: (rule: FilterRule<V>, parentId?: string) => void
+  /** Appends an empty group and returns its id, so the caller can focus it.
+   *  Returns an EMPTY STRING when the bar is disabled or read only, the one
+   *  mutator that has to report its refusal: focusing a group that was never
+   *  created strands the tab stop. `""` rather than `string | null` keeps the
+   *  callers that already test the id honest without widening a published
+   *  signature. */
+  addGroup: (parentId?: string, combinator?: FilterCombinator) => string
+  updateRule: (
+    id: string,
+    updates: Partial<Omit<FilterRule<V>, "id" | "type">>
+  ) => void
+  /** Removes a rule OR a group, and prunes the groups that empties. Node-level
+   *  rather than rule-level because a chip only ever removes a rule, while a
+   *  builder row's trash and a group header's trash are the same button on two
+   *  kinds of node. */
+  removeNode: (id: string) => void
+  duplicateNode: (id: string) => void
+  negateRule: (id: string) => void
+  /** Reorders within the node's own parent. Out of range moves are no-ops. */
+  moveNode: (id: string, delta: number) => void
+  /** Moves a node into another group, at an index. The drag-and-drop half. */
+  moveNodeTo: (id: string, parentId: string, index: number) => void
+  /** Copies a node into another group, at an index. The Alt-drag half, apart
+   *  from `duplicateNode` (which copies BESIDE, with no destination): the two
+   *  composed would emit two queries for one gesture, and a controlled
+   *  consumer would persist a tree the user never asked for. */
+  copyNodeTo: (id: string, parentId: string, index: number) => void
+  /** Nests one node in a new group. The keyboard half of the same idea. */
+  wrapNodeInGroup: (id: string, combinator?: FilterCombinator) => void
+  /** Dissolves a group into its parent. The inverse of `wrapNodeInGroup`. */
+  unwrapGroup: (groupId: string) => void
+  setCombinator: (groupId: string, combinator: FilterCombinator) => void
+  toggleCombinator: (groupId: string) => void
+  clearQuery: () => void
+
+  openCreate: () => void
+  openAmend: (id: string, step: FilterDraftStep) => void
+  closeDraft: () => void
+  dispatchDraft: (action: FilterDraftAction<V>) => void
+
+  /** Writes the bar's live region, for a change no visible surface reports: an
+   *  editor's popover is the one place something destructive happens to rows
+   *  the user is not on, with focus, name and text unchanged afterwards. Not a
+   *  query write, so it skips `emit` and asks the lock nothing. */
+  announce: (message: string) => void
+
+  /** Getters for event handlers, so a handler never closes over stale state. */
+  getQuery: () => FilterQuery<V>
+  getDraft: () => FilterDraft<V> | null
+  /** Fresh id from the SSR-safe factory. */
+  nextId: () => string
+}
+
+/* -------------------------------------------------------------------------- */
+/*                             The mutation lock                              */
+/* -------------------------------------------------------------------------- */
+
+/** `disabled` and `readOnly` are NOT two words for one state. `disabled` is
+ *  the native attribute: not operable, out of the tab order. `readOnly` blocks
+ *  MUTATION and preserves NAVIGATION, because a read-only bar exists so a
+ *  keyboard or screen reader user can walk the chips and find out what the
+ *  view is filtered by. Collapsing the two once put the native attribute on
+ *  all thirteen advanced-builder cell controls while the roving tab stop sat
+ *  on a disabled element, so not one row could be reached from the keyboard.
+ *
+ *  So a mutating control keeps its tab stop and wears `aria-disabled` plus
+ *  `data-readonly` (`filterReadOnlyProps`), this repo's convention for
+ *  "present, focusable, not operable". `aria-readonly` is never used, being
+ *  disallowed on the button, group and toolbar roles, so the BAR says it in
+ *  prose through `labels.readOnly`. The refusal itself is enforced once, where
+ *  all fourteen query writes pass through `emit` in `filters.tsx`. */
+export function isFilterLocked(state: {
+  disabled: boolean
+  readOnly: boolean
+}): boolean {
+  return state.disabled || state.readOnly
+}
+
+/** What a MUTATING control wears while the bar is read only. `null` when the
+ *  bar is disabled, because the native attribute already says it. A
+ *  conditional spread, not explicit `undefined`s: `aria-disabled="false"` on
+ *  an enabled control is noise, and `data-readonly` is a presence hook. */
+export function filterReadOnlyProps(state: {
+  disabled: boolean
+  readOnly: boolean
+}) {
+  if (state.disabled || !state.readOnly) return null
+  return { "aria-disabled": true, "data-readonly": "" } as const
+}
+
+/* -------------------------------------------------------------------------- */
+/*                               The size ladder                              */
+/* -------------------------------------------------------------------------- */
+
+/** The two shadcn button sizes one filters size resolves to. Two rungs because
+ *  shadcn ships a separate ladder for labelled and for icon-only buttons, and
+ *  pairing them keeps a row's kebab as tall as the cell beside it. */
+export interface FilterControlSizes {
+  /** Labelled buttons: the row cells, both triggers, the panel footer. */
+  button: "sm" | "default"
+  /** Icon-only buttons, and also the CHIP's height: a chip is an
+   *  `items-stretch` `ButtonGroup` and no style gives its text segment a
+   *  height, so the segments stretch to the kebab, the one child that has one.
+   *  Sizing the kebab sizes the pill. */
+  icon: "icon-sm" | "icon"
+}
+
+/** ONE ladder, keyed off `size`, for every control the chrome renders, because
+ *  the alternative already happened: five advanced-builder cells took
+ *  `actions.size` while seven sites hardcoded `icon-sm` and three `sm`, giving
+ *  one row three heights. Nothing here is a pixel - each value is a shadcn
+ *  size NAME that `Button` resolves per style, since the control-height ladder
+ *  is per style (nova 7/8, sera 9/10, mira 6/7, and so on), and the glyph size
+ *  rides the same name, so pinning an icon size in here would fight the style
+ *  rather than match it. Two rungs only: `lg` would make the bar taller than
+ *  the style's own default control height (want taller, pick a taller STYLE),
+ *  and `icon-xs` is a 20-24px square in most styles, too small for a chip's
+ *  own label to clear. */
+const FILTER_CONTROL_SIZES: Record<"sm" | "default", FilterControlSizes> = {
+  sm: { button: "sm", icon: "icon-sm" },
+  default: { button: "default", icon: "icon" },
+}
+
+/** The pair for a bar's size, off anything with a `size`, so a
+ *  consumer-composed chrome uses the same ladder as the shipped one. The
+ *  fallback is for JavaScript callers: a `"lg"` TypeScript would have rejected
+ *  must still draw buttons rather than throw on `.button`. */
+export function filterControlSizes(state: {
+  size: "sm" | "default"
+}): FilterControlSizes {
+  return FILTER_CONTROL_SIZES[state.size] ?? FILTER_CONTROL_SIZES.default
+}
+
+const FilterActionsContext =
+  React.createContext<FilterActionsContextValue | null>(null)
+
+export function useFilterActions<
+  V = unknown,
+  O = unknown,
+>(): FilterActionsContextValue<V, O> {
+  const context = React.useContext(FilterActionsContext)
+  if (!context) {
+    throw new Error("useFilterActions must be used inside <Filters>")
+  }
+  return context as unknown as FilterActionsContextValue<V, O>
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    State                                   */
+/* -------------------------------------------------------------------------- */
+
+/** Volatile by construction: typing one character into a value editor
+ *  republishes it. Subscribe from the bar and the panel, never from a chip. */
+export interface FilterStateContextValue<V = unknown> {
+  query: FilterQuery<V>
+  draft: FilterDraft<V> | null
+  ruleCount: number
+  /** Live region text. Empty except immediately after an announced change. */
+  announcement: string
+  /** How many announcements have been made, so a REPEATED one is still heard:
+   *  `aria-live` reports a DOM mutation and React writes nothing when the
+   *  string is unchanged, so the chrome keys the region's contents on this. A
+   *  counter rather than a timestamp: it is compared for identity, never read
+   *  as a value, and is stable across a rerender that a clock is not. */
+  announcementSeq: number
+}
+
+const FilterStateContext = React.createContext<FilterStateContextValue | null>(
+  null
+)
+
+export function useFilterState<V = unknown>(): FilterStateContextValue<V> {
+  const context = React.useContext(FilterStateContext)
+  if (!context) {
+    throw new Error("useFilterState must be used inside <Filters>")
+  }
+  return context as unknown as FilterStateContextValue<V>
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Render                                   */
+/* -------------------------------------------------------------------------- */
+
+/** Consumer render overrides, on their own channel. They must be
+ *  always-current closures yet change identity on every parent render when
+ *  written inline, so isolating them re-renders only what calls them. */
+export interface FilterRenderContextValue<V = unknown, O = unknown> {
+  renderValue?: (context: FilterValueDisplayContext<V, O>) => React.ReactNode
+  renderChip?: (rule: FilterRule<V>) => React.ReactNode
+  renderEmpty?: (context: FilterEmptyStateContext) => React.ReactNode
+}
+
+const FilterRenderContext = React.createContext<FilterRenderContextValue>({})
+
+export function useFilterRender<
+  V = unknown,
+  O = unknown,
+>(): FilterRenderContextValue<V, O> {
+  return React.useContext(FilterRenderContext) as FilterRenderContextValue<V, O>
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                 Focus store                                */
+/* -------------------------------------------------------------------------- */
+
+/** Which chip currently owns the row's single tab stop. */
+export interface FilterFocus {
+  id: string | null
+  /** Which cell inside that row, for restoring focus after an edit. A chip
+   *  draws only `field`, `operator`, `value` and `menu`; the rest are advanced
+   *  builder cells, where a GROUP header is a row too (its `field` is the
+   *  combinator sentence). One union, because the chromes share the store. */
+  segment:
+    | "combinator"
+    | "field"
+    | "operator"
+    | "value"
+    | "add"
+    | "menu"
+    | "ungroup"
+    | "remove"
+    | "drag"
+    | null
+  /** Open that segment's popover, not merely focus it. Picking a field commits
+   *  the rule straight away and the chip appears with no condition yet, so the
+   *  operator menu has to open ON THE CHIP without a second click. */
+  autoOpen: boolean
+}
+
+/** An external store, deliberately NOT React state. A roving tabindex
+ *  republishes on every arrow key, and `setState` would re-render the whole
+ *  bar to move one outline. The SELECTOR hooks below each narrow to one value,
+ *  so arrowing across forty chips re-renders two components. `useFilterFocus`
+ *  is the exception: it returns the whole snapshot. */
+export interface FilterFocusStore {
+  subscribe: (onStoreChange: () => void) => () => void
+  getSnapshot: () => FilterFocus
+  /** No-ops when nothing changed. */
+  set: (next: FilterFocus) => void
+}
+
+const NO_FOCUS: FilterFocus = { id: null, segment: null, autoOpen: false }
+
+export function createFilterFocusStore(): FilterFocusStore {
+  let snapshot: FilterFocus = NO_FOCUS
+  const listeners = new Set<() => void>()
+
+  return {
+    subscribe(onStoreChange) {
+      listeners.add(onStoreChange)
+      return () => {
+        listeners.delete(onStoreChange)
+      }
+    },
+    // The SAME object until something actually changes, which is what
+    // `useSyncExternalStore` requires to avoid an infinite render loop.
+    getSnapshot() {
+      return snapshot
+    },
+    set(next) {
+      if (
+        next.id === snapshot.id &&
+        next.segment === snapshot.segment &&
+        next.autoOpen === snapshot.autoOpen
+      ) {
+        return
+      }
+      snapshot = next
+      for (const listener of listeners) listener()
+    },
+  }
+}
+
+/** A shared, permanently empty store, so the hook degrades to "nothing
+ *  focused" outside a `Filters`. Nothing ever writes to it: each root creates
+ *  and writes its own. */
+const FALLBACK_FOCUS_STORE = createFilterFocusStore()
+
+const FilterFocusContext =
+  React.createContext<FilterFocusStore>(FALLBACK_FOCUS_STORE)
+
+/* -------------------------------------------------------------------------- */
+/*                                 Reordering                                 */
+/* -------------------------------------------------------------------------- */
+
+/** Whether rows may be reordered at all, published once for the subtree. Two
+ *  files have to agree about it: the builder gates the grip and Alt+Arrow,
+ *  while the row and group menus commit the same mutator by a third route, so
+ *  gating only the builder left it off for a pointer and on from a menu. */
+const FilterReorderContext = React.createContext(false)
+
+export const FilterReorderProvider = FilterReorderContext.Provider
+
+export function useFilterReorderable(): boolean {
+  return React.useContext(FilterReorderContext)
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Touched                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Which rules the user has actually edited the VALUE of, which decides WHEN
+ *  an error may appear: "Add filter" mints a row with no value, so flagging
+ *  every invalid row turns the builder red before the user did anything wrong.
+ *  An issue is still COLLECTED for every rule - the footer count,
+ *  `onQueryChange` and tree validity do not change - and only DRAWN once the
+ *  user has committed a value. An external store for the focus store's reason,
+ *  keyed by rule id and never pruned: a stale id costs one Set entry, and
+ *  reconciling against the query on every commit is hot-path work. */
+export interface FilterRowStateStore {
+  subscribe: (listener: () => void) => () => void
+  /** Bumped on every write. What a memo depends on, since the Sets are mutable. */
+  version: () => number
+  /** Whether this rule has had a value committed to it by the user. */
+  has: (id: string) => boolean
+  mark: (id: string) => void
+  /** Starts this rule over. Changing a rule's ATTRIBUTE resets its operator
+   *  and its value, so it has to reset this too, or the row stays warned about
+   *  a value that no longer exists on a field the user navigated away from. */
+  unmark: (id: string) => void
+  /** Whether this rule is still being CREATED: minted by Add filter and not
+   *  yet given an attribute. The row enters the query with a guessed field to
+   *  keep the tree valid, so while pending the builder draws only that cell. */
+  isPending: (id: string) => boolean
+  markPending: (id: string) => void
+  /** The attribute was chosen. The rest of the row appears. */
+  resolvePending: (id: string) => void
+  /** Forgets everything. The bar's own Clear all, and a whole-tree replace. */
+  reset: () => void
+}
+
+export function createFilterRowStateStore(): FilterRowStateStore {
+  const touched = new Set<string>()
+  const pending = new Set<string>()
+  const listeners = new Set<() => void>()
+  let version = 0
+  const notify = () => {
+    version += 1
+    for (const listener of listeners) listener()
+  }
+  return {
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    version: () => version,
+    has: (id) => touched.has(id),
+    mark: (id) => {
+      if (touched.has(id)) return
+      touched.add(id)
+      notify()
+    },
+    unmark: (id) => {
+      if (!touched.delete(id)) return
+      notify()
+    },
+    isPending: (id) => pending.has(id),
+    markPending: (id) => {
+      if (pending.has(id)) return
+      pending.add(id)
+      notify()
+    },
+    resolvePending: (id) => {
+      if (!pending.delete(id)) return
+      notify()
+    },
+    reset: () => {
+      if (touched.size === 0 && pending.size === 0) return
+      touched.clear()
+      pending.clear()
+      notify()
+    },
+  }
+}
+
+const FALLBACK_ROW_STATE_STORE = createFilterRowStateStore()
+
+const FilterRowStateContext = React.createContext<FilterRowStateStore>(
+  FALLBACK_ROW_STATE_STORE
+)
+
+export const FilterRowStateProvider = FilterRowStateContext.Provider
+
+/** The store itself, for handlers that write without subscribing. */
+export function useFilterRowStateStore(): FilterRowStateStore {
+  return React.useContext(FilterRowStateContext)
+}
+
+/** Whether THIS rule is still waiting for its attribute. */
+export function useFilterRowPending(id: string): boolean {
+  const store = React.useContext(FilterRowStateContext)
+  return React.useSyncExternalStore(
+    store.subscribe,
+    () => store.isPending(id),
+    () => false
+  )
+}
+
+/** Whether THIS rule may show an error yet. */
+export function useFilterTouched(id: string): boolean {
+  const store = React.useContext(FilterRowStateContext)
+  return React.useSyncExternalStore(
+    store.subscribe,
+    () => store.has(id),
+    () => false
+  )
+}
+
+/** The whole focus snapshot, so the caller re-renders on EVERY move anywhere
+ *  in the row. A chip wants `useFilterChipFocused` or `useFilterSegmentFocus`
+ *  below instead. */
+export function useFilterFocus(): FilterFocus {
+  const store = React.useContext(FilterFocusContext)
+  return React.useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot
+  )
+}
+
+/** The store itself, for event handlers that write without subscribing. */
+export function useFilterFocusStore(): FilterFocusStore {
+  return React.useContext(FilterFocusContext)
+}
+
+/** The segment of THIS chip that should open itself, or null. */
+export function useFilterChipAutoOpen(
+  id: string
+): FilterFocus["segment"] | null {
+  const store = React.useContext(FilterFocusContext)
+  return React.useSyncExternalStore(
+    store.subscribe,
+    () => {
+      const snapshot = store.getSnapshot()
+      return snapshot.autoOpen && snapshot.id === id ? snapshot.segment : null
+    },
+    () => null
+  )
+}
+
+/** Whether the row holds no focus, so the first chip keeps the tab stop. */
+export function useFilterFocusEmpty(): boolean {
+  const store = React.useContext(FilterFocusContext)
+  return React.useSyncExternalStore(
+    store.subscribe,
+    () => store.getSnapshot().id === null,
+    () => true
+  )
+}
+
+/** Whether THIS chip owns the row's tab stop. */
+export function useFilterChipFocused(id: string): boolean {
+  const store = React.useContext(FilterFocusContext)
+  return React.useSyncExternalStore(
+    store.subscribe,
+    () => store.getSnapshot().id === id,
+    () => false
+  )
+}
+
+/** Which segment of THIS rule owns the tab stop, or null when another rule
+ *  does. A chip needs one boolean, but an advanced row is a grid ROW whose tab
+ *  stop is a (row, column) pair, and the column has to come from this store
+ *  too or the chromes disagree about where focus is after an edit. */
+export function useFilterSegmentFocus(id: string): FilterFocus["segment"] {
+  const store = React.useContext(FilterFocusContext)
+  return React.useSyncExternalStore(
+    store.subscribe,
+    () => {
+      const snapshot = store.getSnapshot()
+      return snapshot.id === id ? snapshot.segment : null
+    },
+    () => null
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Resolution store                              */
+/* -------------------------------------------------------------------------- */
+
+/** The instance-wide value-to-label store. `useFilterOptions` caches per HOOK
+ *  INSTANCE, and a chip's display and its editor are two instances, so a
+ *  `loadOptions`-only field rendered its raw id the moment the menu closed.
+ *  Every instance under one root writes here, and `resolveValues` results land
+ *  here too. External rather than React state because labels arrive from
+ *  effects and promises at their own pace, and the version bumps only when a
+ *  NEW label lands, so a subscriber re-renders once per page of results. */
+export interface FilterResolutionStore {
+  subscribe: (onStoreChange: () => void) => () => void
+  getVersion: () => number
+  /** The option behind a stored value, or undefined while unresolved. */
+  get: (fieldKey: string, value: string) => FilterOption | undefined
+  /** Records options under a field key. New values bump the version. */
+  set: (fieldKey: string, options: readonly FilterOption[]) => void
+  /** Marks values as resolving and returns the subset nobody has claimed yet,
+   *  so two chips holding the same id issue ONE request. Claims are permanent
+   *  for values a fulfilled resolve did not return, which stops an id the
+   *  server does not know from being re-asked forever. */
+  claim: (fieldKey: string, values: readonly string[]) => string[]
+  /** Releases claims after a FAILED resolve, so a later mount may retry. */
+  release: (fieldKey: string, values: readonly string[]) => void
+}
+
+export function createFilterResolutionStore(): FilterResolutionStore {
+  const resolved = new Map<string, Map<string, FilterOption>>()
+  const claimed = new Map<string, Set<string>>()
+  const listeners = new Set<() => void>()
+  let version = 0
+
+  const bucket = (fieldKey: string) => {
+    let map = resolved.get(fieldKey)
+    if (!map) {
+      map = new Map()
+      resolved.set(fieldKey, map)
+    }
+    return map
+  }
+
+  return {
+    subscribe(onStoreChange) {
+      listeners.add(onStoreChange)
+      return () => {
+        listeners.delete(onStoreChange)
+      }
+    },
+    getVersion() {
+      return version
+    },
+    get(fieldKey, value) {
+      return resolved.get(fieldKey)?.get(value)
+    },
+    set(fieldKey, options) {
+      const map = bucket(fieldKey)
+      let landed = false
+      for (const option of options) {
+        if (!map.has(option.value)) landed = true
+        map.set(option.value, option)
+      }
+      if (!landed) return
+      version += 1
+      for (const listener of listeners) listener()
+    },
+    claim(fieldKey, values) {
+      let set = claimed.get(fieldKey)
+      if (!set) {
+        set = new Set()
+        claimed.set(fieldKey, set)
+      }
+      const map = resolved.get(fieldKey)
+      const fresh: string[] = []
+      for (const value of values) {
+        if (set.has(value) || map?.has(value)) continue
+        set.add(value)
+        fresh.push(value)
+      }
+      return fresh
+    },
+    release(fieldKey, values) {
+      const set = claimed.get(fieldKey)
+      if (!set) return
+      for (const value of values) set.delete(value)
+    },
+  }
+}
+
+export {
+  FilterActionsContext,
+  FilterFocusContext,
+  FilterRenderContext,
+  FilterStateContext,
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-date.tsx b/apps/web/src/components/reui/filters/filters-date.tsx
new file mode 100644
index 0000000..64b7367
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-date.tsx
@@ -0,0 +1,213 @@
+import {
+  addDays,
+  addMonths,
+  addWeeks,
+  addYears,
+  format,
+  isValid,
+  parse,
+  startOfDay,
+} from "date-fns"
+
+/**
+ * A date filter value. NOT a `Date`: a filter gets persisted (saved views,
+ * shared URLs), and a resolved `Date` would freeze "created today" into one
+ * fixed day. An absolute pick still stores one day, because "on 14 August"
+ * does mean that day.
+ */
+export interface FilterDateValue {
+  /** An absolute day, `yyyy-MM-dd`. Mutually exclusive with `relative`. */
+  date?: string
+  /** A token re-resolved on every read. */
+  relative?: FilterRelativeDate
+  /** Optional time of day, `HH:mm`. */
+  time?: string
+}
+
+/** A calendar offset from now, resolved at read time. */
+export interface FilterRelativeDate {
+  unit: "day" | "week" | "month" | "year"
+  offset: number
+}
+
+export const FILTER_DATE_FORMAT = "yyyy-MM-dd"
+
+export const RELATIVE_TODAY: FilterRelativeDate = { unit: "day", offset: 0 }
+export const RELATIVE_TOMORROW: FilterRelativeDate = { unit: "day", offset: 1 }
+export const RELATIVE_YESTERDAY: FilterRelativeDate = {
+  unit: "day",
+  offset: -1,
+}
+export const RELATIVE_NEXT_WEEK: FilterRelativeDate = {
+  unit: "week",
+  offset: 1,
+}
+
+export function applyFilterRelative(
+  relative: FilterRelativeDate,
+  now: Date
+): Date {
+  const base = startOfDay(now)
+  if (relative.unit === "day") return addDays(base, relative.offset)
+  if (relative.unit === "week") return addWeeks(base, relative.offset)
+  if (relative.unit === "month") return addMonths(base, relative.offset)
+  return addYears(base, relative.offset)
+}
+
+export function resolveFilterDate(
+  value: FilterDateValue | undefined,
+  now: Date = new Date()
+): Date | null {
+  if (!value) return null
+  if (value.relative) return applyFilterRelative(value.relative, now)
+  if (value.date) {
+    const parsed = parse(value.date, FILTER_DATE_FORMAT, now)
+    return isValid(parsed) ? parsed : null
+  }
+  return null
+}
+
+export function toFilterDateValue(date: Date, time?: string): FilterDateValue {
+  const value: FilterDateValue = { date: format(date, FILTER_DATE_FORMAT) }
+  if (time) value.time = time
+  return value
+}
+
+// ----- natural language input -----
+
+const WEEKDAYS = [
+  "sunday",
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday",
+  "saturday",
+]
+
+/**
+ * Typed formats, most specific first. `date-selector.tsx` overlaps on a few
+ * of these, but its parser is a callback inside the component returning a
+ * `DateSelectorValue`, so there is nothing importable.
+ */
+const EXPLICIT_FORMATS = [
+  "yyyy-MM-dd",
+  "MM/dd/yyyy",
+  "M/d/yyyy",
+  "dd/MM/yyyy",
+  "MMMM d, yyyy",
+  "MMM d, yyyy",
+  "MMMM d",
+  "MMM d",
+  "d MMMM yyyy",
+  "d MMM yyyy",
+]
+
+/**
+ * Parses a typed phrase, or null when nothing matches. Relative phrasing gives
+ * a RELATIVE value and an explicit date an ABSOLUTE one; flattening the two is
+ * what freezes a saved view.
+ */
+export function parseFilterDate(
+  text: string,
+  now: Date = new Date()
+): FilterDateValue | null {
+  const input = text.trim().toLowerCase().replace(/\s+/g, " ")
+  if (!input) return null
+
+  if (input === "today" || input === "now") return { relative: RELATIVE_TODAY }
+  if (input === "tomorrow") return { relative: RELATIVE_TOMORROW }
+  if (input === "yesterday") return { relative: RELATIVE_YESTERDAY }
+
+  const nextLast = input.match(/^(next|last|this) (day|week|month|year)$/)
+  if (nextLast) {
+    const direction =
+      nextLast[1] === "next" ? 1 : nextLast[1] === "last" ? -1 : 0
+    return {
+      relative: {
+        unit: nextLast[2] as FilterRelativeDate["unit"],
+        offset: direction,
+      },
+    }
+  }
+
+  // "in 3 days" / "3 days ago" / "in 2 weeks"
+  const counted = input.match(
+    /^(?:in )?(\d+) (day|week|month|year)s?(?: ago)?$/
+  )
+  if (counted) {
+    const magnitude = Number.parseInt(counted[1], 10)
+    const past = input.endsWith("ago")
+    return {
+      relative: {
+        unit: counted[2] as FilterRelativeDate["unit"],
+        offset: past ? -magnitude : magnitude,
+      },
+    }
+  }
+
+  // "next tuesday" / "last friday" / bare "tuesday"
+  const weekday = input.match(/^(?:(next|last|this) )?([a-z]+)$/)
+  if (weekday) {
+    const index = WEEKDAYS.indexOf(weekday[2])
+    if (index !== -1) {
+      const today = startOfDay(now)
+      const current = today.getDay()
+      let delta = index - current
+      const qualifier = weekday[1]
+
+      if (qualifier === "last") {
+        // Always strictly in the past.
+        if (delta >= 0) delta -= 7
+      } else {
+        // "next"/"this" and a bare weekday all mean the NEXT one, not today.
+        if (delta <= 0) delta += 7
+      }
+
+      return { relative: { unit: "day", offset: delta } }
+    }
+  }
+
+  for (const pattern of EXPLICIT_FORMATS) {
+    const parsed = parse(input, pattern, now)
+    if (isValid(parsed)) {
+      // "Aug 14" has no year, so it takes the reference year.
+      return toFilterDateValue(parsed)
+    }
+  }
+
+  return null
+}
+
+/**
+ * Human wording for a value. Relative values render as their phrase, not the
+ * resolved day, so a chip reading "is today" does not go stale tomorrow.
+ */
+export function formatFilterDate(
+  value: FilterDateValue | undefined,
+  now: Date = new Date(),
+  pattern = "MMM d, yyyy"
+): string {
+  if (!value) return ""
+
+  if (value.relative) {
+    const { unit, offset } = value.relative
+    if (unit === "day" && offset === 0) return "today"
+    if (unit === "day" && offset === 1) return "tomorrow"
+    if (unit === "day" && offset === -1) return "yesterday"
+
+    const plural = Math.abs(offset) === 1 ? unit : `${unit}s`
+    if (offset > 0) return `in ${offset} ${plural}`
+    if (offset < 0) return `${Math.abs(offset)} ${plural} ago`
+    return `this ${unit}`
+  }
+
+  const resolved = resolveFilterDate(value, now)
+  if (!resolved) return ""
+  const day = format(resolved, pattern)
+  return value.time ? `${day} ${value.time}` : day
+}
+
+export function isFilterTime(time: string): boolean {
+  return /^([01]\d|2[0-3]):[0-5]\d$/.test(time)
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-dnd.tsx b/apps/web/src/components/reui/filters/filters-dnd.tsx
new file mode 100644
index 0000000..eab3742
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-dnd.tsx
@@ -0,0 +1,700 @@
+import * as React from "react"
+
+/**
+ * Gesture model copied from `event-calendar-dnd.tsx`, deliberately not
+ * imported: filters installs on its own and must not pull a whole calendar into
+ * `shadcn add filters`. Vanilla-DOM overlay, so a drag renders no React.
+ */
+export const FILTER_DND_ACTIVATION = {
+  /** Mouse travel before a press becomes a drag. Below this it stays a click. */
+  moveDistancePx: 5,
+  /** Touch long-press before a drag starts, so a swipe still scrolls. */
+  touchDelayMs: 250,
+  touchTolerancePx: 5,
+  autoScrollEdgePx: 40,
+  autoScrollMaxStepPx: 12,
+  /** A seed only: `createCarry` measures the real grab offset before paint. */
+  carryPointerOffsetPx: 12,
+} as const
+
+/** One rule row, or one group's header row. Both are drag sources and targets. */
+export const FILTER_ROW_SELECTOR = '[data-slot="filter-row"]'
+
+/** Explicit "drop INSIDE": a row hit test can only ever say "beside". */
+export const FILTER_DROP_ZONE_SELECTOR = "[data-drop-parent]"
+
+/** Marked alongside the zone, so lighting the group costs no `:has()`. */
+export const FILTER_GROUP_SELECTOR = '[data-slot="filter-group"]'
+
+/** Geometry only, so resolution is a pure function and a table test. */
+export interface FilterDropBox {
+  top: number
+  bottom: number
+  left: number
+  right: number
+  /** The group the drop writes into. */
+  parentId: string
+  /** Where in that group's children the node lands, not a slot in this list. */
+  index: number
+  /** How many rows enclose this box. Deeper wins. */
+  depth: number
+}
+
+export interface FilterDropResolution<T extends FilterDropBox> {
+  target: T
+  /** Null for a zone: INTO the group rather than beside anything. */
+  edge: "before" | "after" | null
+}
+
+function contains(box: FilterDropBox, x: number, y: number, grow = 0): boolean {
+  return (
+    x >= box.left &&
+    x <= box.right &&
+    y >= box.top - grow &&
+    y <= box.bottom + grow
+  )
+}
+
+/**
+ * How far a ROW reaches past its own rect when hit tested: HALF the sibling
+ * gap, which is `gap-3`, so six. `FILTER_ROW_GAP_CLASS` is the other half of
+ * one measurement; this moves whenever that does.
+ *
+ * The seam between adjacent rows is inside NEITHER rect, so a pointer aimed
+ * between two rows fell through to whatever did enclose it: at the top level
+ * nothing did, so the cursor said `no-drop`; one level in it was the group.
+ * Half the gap makes siblings tile, and the depth sort keeps the child ahead of
+ * that group. Rows only: zones are explicit strips.
+ */
+export const FILTER_ROW_SEAM_PX = 6
+
+/**
+ * Zones before rows, then the DEEPEST box: a group's rect encloses everything
+ * it holds, so a nested condition would otherwise resolve to its whole group.
+ * `seam` is a parameter, not the constant inlined, so the tiling rule itself is
+ * a table test.
+ */
+export function resolveFilterDrop<T extends FilterDropBox>(
+  zones: T[],
+  rows: T[],
+  x: number,
+  y: number,
+  seam: number = FILTER_ROW_SEAM_PX
+): FilterDropResolution<T> | null {
+  let zone: T | null = null
+  for (const candidate of zones) {
+    if (!contains(candidate, x, y)) continue
+    if (!zone || candidate.depth > zone.depth) zone = candidate
+  }
+  if (zone) return { target: zone, edge: null }
+
+  let row: T | null = null
+  for (const candidate of rows) {
+    if (!contains(candidate, x, y, seam)) continue
+    if (!row || candidate.depth > row.depth) row = candidate
+  }
+  if (!row) return null
+
+  // The midpoint, not the nearest edge: a row is the width of the panel, so a
+  // proximity test would leave the indicator undecided across most of one.
+  const after = y > row.top + (row.bottom - row.top) / 2
+  return {
+    target: { ...row, index: row.index + (after ? 1 : 0) },
+    edge: after ? "after" : "before",
+  }
+}
+
+/** Where a dragged node started, which is what makes a drop a no-op or not. */
+export interface FilterDropOrigin {
+  parentId: string
+  index: number
+}
+
+/**
+ * Both indices name the slot the node already occupies, because
+ * `moveFilterNodeTo` closes the gap the detach leaves. Copy is never a no-op.
+ */
+export function isFilterDropNoop(
+  resolution: FilterDropResolution<FilterDropBox> | null,
+  origin: FilterDropOrigin | null,
+  copy: boolean
+): boolean {
+  if (!resolution || !origin || copy) return false
+  if (resolution.target.parentId !== origin.parentId) return false
+  return (
+    resolution.target.index === origin.index ||
+    resolution.target.index === origin.index + 1
+  )
+}
+
+/** Rows unmount mid-gesture, so it is the PANEL leaving that aborts a drag. */
+const activeCancels = new Set<() => void>()
+
+/** Cancel and fully revert every in-flight filter row drag. */
+export function cancelActiveFilterDrags(): void {
+  for (const cancel of [...activeCancels]) cancel()
+}
+
+let lastDragEndedAt = 0
+
+/**
+ * Whether a drag ended within the last few frames. Exported: a consumer's own
+ * row click handler needs the same answer the suppressor below needs.
+ */
+export function wasRecentFilterDrag(): boolean {
+  return performance.now() - lastDragEndedAt < 250
+}
+
+/**
+ * NOT `{ once: true }` alone: a drag that ends over a different element fires
+ * no click at all, and a stale arming would eat the user's next click. The
+ * timestamp is what makes that stale arming harmless.
+ */
+function suppressTrailingClick(event: MouseEvent) {
+  window.removeEventListener("click", suppressTrailingClick, true)
+  if (!wasRecentFilterDrag()) return
+  event.stopPropagation()
+  event.preventDefault()
+}
+
+/** The carry is a compositing layer: a subpixel translate blurs its text. */
+function snapToPixel(value: number): number {
+  const dpr = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1
+  return Math.round(value * dpr) / dpr
+}
+
+/**
+ * `card` is a ZONE's group, resolved once rather than walked per frame. Null on
+ * a row, which stands for itself.
+ */
+type MeasuredBox = FilterDropBox & {
+  el: HTMLElement
+  card: HTMLElement | null
+}
+
+interface Surface {
+  zones: MeasuredBox[]
+  rows: MeasuredBox[]
+  /**
+   * Rects are captured ONCE, so one subtraction against this scrollTop corrects
+   * for scrolling instead of a per-move `getBoundingClientRect`. THE ELEMENT,
+   * NOT A MIRRORED NUMBER: a mirror tracks only this engine's own scrolling, so
+   * a wheel mid-gesture left the rects stale while the correction read zero,
+   * painting the indicator 60px off the pointer.
+   */
+  viewport: HTMLElement | null
+  viewportRect: DOMRect | null
+  /** The one number kept: where the rects were taken, which cannot change. */
+  startScrollTop: number
+}
+
+/**
+ * The nearest scroller, THIS ONE INCLUDED: the panel is exactly what a consumer
+ * caps with `overflow-y: auto`, and a walk from the parent answered null for it.
+ */
+function findScrollParent(el: HTMLElement | null): HTMLElement | null {
+  let node = el ?? null
+  while (node) {
+    const style = getComputedStyle(node)
+    const overflow = `${style.overflowY} ${style.overflow}`
+    if (
+      /(auto|scroll|overlay)/.test(overflow) &&
+      node.scrollHeight > node.clientHeight
+    ) {
+      return node
+    }
+    node = node.parentElement
+  }
+  return null
+}
+
+function rowDepth(el: HTMLElement, root: HTMLElement): number {
+  let depth = 0
+  let node = el.parentElement
+  while (node && node !== root) {
+    if (node.matches(FILTER_ROW_SELECTOR)) depth++
+    node = node.parentElement
+  }
+  return depth
+}
+
+/**
+ * Measured once. DESCENDANTS of the dragged node are excluded rather than
+ * refused later: an indicator the drop ignores is a broken promise. The dragged
+ * row ITSELF is kept, so its own slot reads as a no-op, not as a hole.
+ */
+function collectSurface(root: HTMLElement, dragged: HTMLElement): Surface {
+  const zones: MeasuredBox[] = []
+  const rows: MeasuredBox[] = []
+
+  for (const el of root.querySelectorAll<HTMLElement>(
+    FILTER_DROP_ZONE_SELECTOR
+  )) {
+    if (dragged.contains(el)) continue
+    const parentId = el.dataset.dropParent
+    if (!parentId) continue
+    const rect = el.getBoundingClientRect()
+    zones.push({
+      el,
+      card: el.closest<HTMLElement>(FILTER_GROUP_SELECTOR),
+      top: rect.top,
+      bottom: rect.bottom,
+      left: rect.left,
+      right: rect.right,
+      parentId,
+      index: Number(el.dataset.dropIndex ?? 0),
+      depth: rowDepth(el, root),
+    })
+  }
+
+  for (const el of root.querySelectorAll<HTMLElement>(FILTER_ROW_SELECTOR)) {
+    if (el !== dragged && dragged.contains(el)) continue
+    const parentId = el.dataset.parentId
+    if (!parentId) continue
+    const rect = el.getBoundingClientRect()
+    rows.push({
+      el,
+      card: null,
+      top: rect.top,
+      bottom: rect.bottom,
+      left: rect.left,
+      right: rect.right,
+      parentId,
+      index: Number(el.dataset.index ?? 0),
+      depth: rowDepth(el, root),
+    })
+  }
+
+  const viewport = findScrollParent(root)
+  return {
+    zones,
+    rows,
+    viewport,
+    viewportRect: viewport?.getBoundingClientRect() ?? null,
+    startScrollTop: viewport?.scrollTop ?? 0,
+  }
+}
+
+export interface FilterDropDetails {
+  parentId: string
+  index: number
+  /** Alt was held at release: copy the node rather than moving it. */
+  copy: boolean
+}
+
+export interface FilterRowDragOptions {
+  /** The PANEL, not its body: the top-level append zone is in the footer. */
+  root: () => HTMLElement | null
+  onDrop: (nodeId: string, details: FilterDropDetails) => void
+  disabled?: boolean
+}
+
+/**
+ * Straight to the DOM: a React state write per move is a tree render. A zone
+ * marks TWO elements, itself and its card, and both clear every frame.
+ */
+function paint(
+  surface: Surface,
+  hit: FilterDropResolution<MeasuredBox> | null
+) {
+  for (const box of surface.zones) {
+    delete box.el.dataset.dropInto
+    if (box.card) delete box.card.dataset.dropInto
+  }
+  for (const box of surface.rows) delete box.el.dataset.dropEdge
+  if (!hit) return
+  if (hit.edge) {
+    hit.target.el.dataset.dropEdge = hit.edge
+    return
+  }
+  hit.target.el.dataset.dropInto = ""
+  if (hit.target.card) hit.target.card.dataset.dropInto = ""
+}
+
+function startDrag(
+  event: React.PointerEvent<HTMLElement>,
+  nodeId: string,
+  options: FilterRowDragOptions
+) {
+  const handle = event.currentTarget
+  const root = options.root()
+  const source = handle.closest<HTMLElement>(FILTER_ROW_SELECTOR)
+  if (!root || !source) return
+
+  const pointerId = event.pointerId
+  const isTouch = event.pointerType === "touch"
+  const startX = event.clientX
+  const startY = event.clientY
+
+  // Off the row's own attributes, which it already publishes for the hit test.
+  // Asking the panel would mean threading a position through the drag context.
+  const origin: FilterDropOrigin | null = source.dataset.parentId
+    ? {
+        parentId: source.dataset.parentId,
+        index: Number(source.dataset.index ?? 0),
+      }
+    : null
+
+  let active = false
+  let finished = false
+  let surface: Surface | null = null
+  let hit: FilterDropResolution<MeasuredBox> | null = null
+  let copy = event.altKey
+  let lastEvent: PointerEvent | null = null
+  let touchTimer: ReturnType<typeof setTimeout> | null = null
+  let rafScroll = 0
+
+  // Three states, not a boolean: `"ok"` lands somewhere new, `"noop"` puts the
+  // node back where it came from, `"none"` is over nothing at all.
+  let dropState: "ok" | "noop" | "none" = "none"
+
+  let carryEl: HTMLDivElement | null = null
+  let badgeEl: HTMLSpanElement | null = null
+  // Where inside the row the pointer went down, so the copy holds that spot.
+  // Measured in `createCarry`, which runs before anything reads these.
+  let grabOffsetX = FILTER_DND_ACTIVATION.carryPointerOffsetPx
+  let grabOffsetY = FILTER_DND_ACTIVATION.carryPointerOffsetPx
+
+  const createCarry = () => {
+    const rect = source.getBoundingClientRect()
+    grabOffsetX = startX - rect.left
+    grabOffsetY = startY - rect.top
+
+    carryEl = document.createElement("div")
+    carryEl.setAttribute("data-slot", "filters-drag-carry")
+    carryEl.setAttribute("aria-hidden", "true")
+    // `data-drop-invalid` rather than a toggled class name, so the style stays
+    // one static string Tailwind can see at build time.
+    //
+    // Muted and translucent, no border or shadow: the clone carries the row's
+    // own controls, and a box around them read as a card leaving the page. Only
+    // the invalid state marks the clone, since nothing else says the drop is
+    // dead, and it RINGS rather than going dashed: dashed is this builder's
+    // word for "a row can land here", and the clone is not one.
+    carryEl.className =
+      "pointer-events-none fixed " +
+      "top-0 left-0 z-100 " +
+      "opacity-95 will-change-transform " +
+      "data-drop-invalid:ring-destructive/70 data-drop-invalid:ring-2 " +
+      "data-drop-invalid:opacity-60"
+    // A bare anchor: the clip box below owns the size, and no overflow lets the
+    // badge overhang.
+    carryEl.style.position = "fixed"
+
+    const clone = source.cloneNode(true) as HTMLElement
+    // The source is faded while in flight; its copy must not inherit that.
+    delete clone.dataset.dragging
+    delete clone.dataset.dropNoop
+    delete clone.dataset.dropEdge
+    if (rect.width > 0) clone.style.width = `${rect.width}px`
+
+    /*
+      SANITIZED, because the clone lives on `<body>`: two elements would claim
+      one node id, `aria-hidden` leaves real buttons in the tab order and must
+      never wrap a focused one, and cloned ids make a `for` resolve to a copy.
+    */
+    const strip = (el: HTMLElement) => {
+      el.removeAttribute("id")
+      el.removeAttribute("data-node-id")
+      el.removeAttribute("data-filter-cell")
+      if (el.dataset.slot === "filter-row") el.removeAttribute("data-slot")
+      // `-1` rather than removed: the attribute is also how the roving scheme
+      // marks its cells, and a row copied mid-gesture has one cell at `0`.
+      el.setAttribute("tabindex", "-1")
+    }
+    strip(clone)
+    for (const el of clone.querySelectorAll<HTMLElement>("*")) strip(el)
+
+    /*
+      The CLIPPING box is the inner one: the carry is the badge's containing
+      block, so `overflow-hidden` there clipped the badge that overhangs it.
+    */
+    const clip = document.createElement("div")
+    clip.className = "bg-background overflow-hidden rounded-md"
+    // Sized only when the rect is real: a document that is not being laid out
+    // measures zero, and a copy pinned to `0px` is invisible.
+    if (rect.width > 0) clip.style.width = `${rect.width}px`
+    if (rect.height > 0) clip.style.height = `${rect.height}px`
+    clip.appendChild(clone)
+    carryEl.appendChild(clip)
+
+    badgeEl = document.createElement("span")
+    badgeEl.setAttribute("data-slot", "filters-drag-copy")
+    badgeEl.className =
+      "bg-primary text-primary-foreground absolute -end-1.5 -top-1.5 flex " +
+      "size-4 items-center justify-center rounded-full text-[10px] leading-none"
+    badgeEl.textContent = "+"
+    // Legible BEFORE the release, or Alt is discoverable only by error.
+    badgeEl.hidden = !copy
+    carryEl.appendChild(badgeEl)
+
+    // <body>, not the panel: a transform or a `content-visibility` on a wrapper
+    // becomes the containing block for `position: fixed`, and the clone jumps.
+    document.body.appendChild(carryEl)
+    positionCarry(startX, startY)
+  }
+
+  const positionCarry = (x: number, y: number) => {
+    if (!carryEl) return
+    // THE GRAB OFFSET, not a fixed nudge: the grip sits at the row's trailing
+    // edge, so anchoring at the pointer hung the copy a row's width away.
+    carryEl.style.transform = `translate3d(${snapToPixel(x - grabOffsetX)}px, ${snapToPixel(y - grabOffsetY)}px, 0)`
+  }
+
+  // Two things decide the cursor and the RESOLUTION outranks Alt, which is why
+  // `none` is tested first: `copy` over nothing is still nothing.
+  const paintCursor = () => {
+    if (!active) return
+    document.body.style.cursor =
+      dropState === "none" ? "no-drop" : copy ? "copy" : "grabbing"
+  }
+
+  // Deliberately NOT guarded on `dropState === next`: the first resolution of a
+  // gesture is routinely `"none"`, which is also the initial value, so a guard
+  // left the first frame of a drag onto nothing wearing no mark at all.
+  const setDropState = (next: typeof dropState) => {
+    dropState = next
+    // On the SOURCE: "it stays here" is a statement about the row carried.
+    if (next === "noop") source.dataset.dropNoop = ""
+    else delete source.dataset.dropNoop
+    // And on the CARRY: over nothing there is no target left to mark.
+    if (carryEl) {
+      if (next === "none") carryEl.dataset.dropInvalid = ""
+      else delete carryEl.dataset.dropInvalid
+    }
+    paintCursor()
+  }
+
+  const setCopy = (next: boolean) => {
+    if (copy === next) return
+    copy = next
+    if (badgeEl) badgeEl.hidden = !next
+    paintCursor()
+    // Alt changes the ANSWER, not just the cursor: a release beside yourself is
+    // a no-op while moving and a duplicate in place while copying.
+    if (lastEvent) hitTest(lastEvent.clientX, lastEvent.clientY)
+  }
+
+  const hitTest = (x: number, y: number) => {
+    if (!surface) return
+    // One subtraction instead of a re-measure. Read off the ELEMENT every time:
+    // see `Surface.viewport`, a mirror misses the user's own scroll.
+    const scrolled = surface.viewport?.scrollTop ?? surface.startScrollTop
+    const drift = scrolled - surface.startScrollTop
+    const resolved = resolveFilterDrop(
+      surface.zones,
+      surface.rows,
+      x,
+      y + drift
+    )
+    const noop = isFilterDropNoop(resolved, origin, copy)
+    // A no-op commits as NOTHING, not as a move the tree would discard.
+    hit = noop ? null : resolved
+    paint(surface, hit)
+    setDropState(noop ? "noop" : hit ? "ok" : "none")
+  }
+
+  const autoScroll = (y: number) => {
+    if (rafScroll) cancelAnimationFrame(rafScroll)
+    rafScroll = 0
+    const viewport = surface?.viewport
+    const rect = surface?.viewportRect
+    if (!viewport || !rect) return
+
+    const edge = FILTER_DND_ACTIVATION.autoScrollEdgePx
+    const step = FILTER_DND_ACTIVATION.autoScrollMaxStepPx
+    let delta = 0
+    if (y >= rect.top && y < rect.top + edge) {
+      delta = -step * ((rect.top + edge - y) / edge)
+    } else if (y <= rect.bottom && y > rect.bottom - edge) {
+      delta = step * Math.min(1, (y - (rect.bottom - edge)) / edge)
+    }
+    if (delta === 0) return
+
+    const tick = () => {
+      // The read-back STOPS the loop: the browser clamps at the scroll extent,
+      // so a panel at its limit would keep asking for unusable frames.
+      const before = viewport.scrollTop
+      viewport.scrollTop = before + delta
+      if (viewport.scrollTop === before) return
+      if (lastEvent) hitTest(lastEvent.clientX, lastEvent.clientY)
+      rafScroll = requestAnimationFrame(tick)
+    }
+    rafScroll = requestAnimationFrame(tick)
+  }
+
+  /**
+   * A still pointer fires no `pointermove`, so a wheel mid-drag would leave the
+   * last answer painted while the rows slid out from under it. The overlap
+   * with the autoScroll tick is deliberate: this is arithmetic over boxes
+   * already measured, and one redundant pass per frame is cheaper than a rule
+   * about who owns the repaint.
+   */
+  const onViewportScroll = () => {
+    if (!active || !lastEvent) return
+    hitTest(lastEvent.clientX, lastEvent.clientY)
+  }
+
+  const activate = () => {
+    if (active) return
+    active = true
+    surface = collectSurface(root, source)
+
+    // Passive: nothing here calls `preventDefault`, and a non-passive listener
+    // on a scroller is a frame of jank per notch.
+    surface.viewport?.addEventListener("scroll", onViewportScroll, {
+      passive: true,
+    })
+    source.dataset.dragging = ""
+    document.body.style.cursor = copy ? "copy" : "grabbing"
+    document.body.style.userSelect = "none"
+    createCarry()
+    // Armed with the GESTURE, not the press: a press that never travels far
+    // enough strands no overlay, no body style and no listener.
+    window.addEventListener("blur", onWindowBlur)
+  }
+
+  // Idempotent. pointerup, pointercancel, Escape, window blur and the panel's
+  // own teardown can all race; whichever lands first wins and the rest no-op.
+  const cleanup = () => {
+    if (finished) return
+    finished = true
+    activeCancels.delete(cancel)
+    window.removeEventListener("pointermove", onPointerMove)
+    window.removeEventListener("pointerup", onPointerUp)
+    window.removeEventListener("pointercancel", onPointerCancel)
+    window.removeEventListener("keydown", onKeyDown, true)
+    window.removeEventListener("keyup", onKeyUp, true)
+    window.removeEventListener("blur", onWindowBlur)
+    surface?.viewport?.removeEventListener("scroll", onViewportScroll)
+    if (touchTimer) clearTimeout(touchTimer)
+    if (rafScroll) cancelAnimationFrame(rafScroll)
+    if (surface) paint(surface, null)
+    delete source.dataset.dragging
+    delete source.dataset.dropNoop
+    carryEl?.remove()
+    carryEl = null
+    badgeEl = null
+    document.body.style.cursor = ""
+    document.body.style.userSelect = ""
+  }
+
+  /** A bare teardown: nothing is committed until release, so no snapshot. */
+  const cancel = () => {
+    if (active) lastDragEndedAt = performance.now()
+    cleanup()
+  }
+
+  const onWindowBlur = () => cancel()
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === "Escape" && active) {
+      // Stopped, or the popover the builder may be living in closes underneath
+      // the gesture and takes the panel the drop was aimed at with it.
+      e.stopPropagation()
+      e.preventDefault()
+      cancel()
+      return
+    }
+    if (e.key === "Alt") setCopy(true)
+  }
+
+  // Alt tracked on its own keys too: reaching for the modifier without moving
+  // the mouse fires no pointermove, and the badge has to appear regardless.
+  const onKeyUp = (e: KeyboardEvent) => {
+    if (e.key === "Alt") setCopy(false)
+  }
+
+  const onPointerMove = (e: PointerEvent) => {
+    // A second finger must not drive or cancel the gesture this one started.
+    if (e.pointerId !== pointerId) return
+    lastEvent = e
+
+    if (!active) {
+      const distance = Math.hypot(e.clientX - startX, e.clientY - startY)
+      if (isTouch) {
+        // Past the tolerance the user is scrolling, so the press stays a scroll.
+        if (distance > FILTER_DND_ACTIVATION.touchTolerancePx) cancel()
+        return
+      }
+      if (distance < FILTER_DND_ACTIVATION.moveDistancePx) return
+      activate()
+    }
+
+    setCopy(e.altKey)
+    positionCarry(e.clientX, e.clientY)
+    hitTest(e.clientX, e.clientY)
+    autoScroll(e.clientY)
+  }
+
+  const onPointerUp = (e: PointerEvent) => {
+    if (e.pointerId !== pointerId) return
+    const landed = active ? hit : null
+    const wasCopy = copy
+    cleanup()
+    if (!active) return
+
+    lastDragEndedAt = performance.now()
+    // The trailing click belongs to the gesture, not to whatever it ended over.
+    window.addEventListener("click", suppressTrailingClick, true)
+
+    if (!landed) return
+    options.onDrop(nodeId, {
+      parentId: landed.target.parentId,
+      index: landed.target.index,
+      copy: wasCopy,
+    })
+  }
+
+  const onPointerCancel = (e: PointerEvent) => {
+    if (e.pointerId !== pointerId) return
+    cancel()
+  }
+
+  window.addEventListener("pointermove", onPointerMove)
+  window.addEventListener("pointerup", onPointerUp)
+  window.addEventListener("pointercancel", onPointerCancel)
+  window.addEventListener("keydown", onKeyDown, true)
+  window.addEventListener("keyup", onKeyUp, true)
+  activeCancels.add(cancel)
+
+  if (isTouch) {
+    touchTimer = setTimeout(() => {
+      activate()
+      if (lastEvent) {
+        positionCarry(lastEvent.clientX, lastEvent.clientY)
+        hitTest(lastEvent.clientX, lastEvent.clientY)
+      }
+    }, FILTER_DND_ACTIVATION.touchDelayMs)
+  }
+}
+
+/**
+ * Only `onPointerDown`: the handle is a real button that Tab reaches, so it must
+ * not also be `draggable` and race the browser's HTML5 drag, with its ghost, no
+ * copy affordance and no way to report a drop into a nested target.
+ */
+export function useFilterRowDrag(options: FilterRowDragOptions) {
+  // Read at gesture time, not captured at wiring time, so the handler identity
+  // is stable and a memoized row never re-renders on a re-created callback.
+  const latest = React.useRef(options)
+  React.useEffect(() => {
+    latest.current = options
+  })
+
+  // A gesture outlives its row by design, but never the panel: its listeners
+  // are on `window` and its carry on `document.body`.
+  React.useEffect(() => cancelActiveFilterDrags, [])
+
+  return React.useCallback(
+    (nodeId: string) => ({
+      onPointerDown: (event: React.PointerEvent<HTMLElement>) => {
+        if (latest.current.disabled) return
+        // Primary button only: a right press strands the drag under a menu.
+        if (event.button !== 0) return
+        startDrag(event, nodeId, latest.current)
+      },
+    }),
+    []
+  )
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-draft.tsx b/apps/web/src/components/reui/filters/filters-draft.tsx
new file mode 100644
index 0000000..fd73c7b
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-draft.tsx
@@ -0,0 +1,187 @@
+import type {
+  FilterDraft,
+  FilterDraftStep,
+  FilterOperatorArity,
+} from "@/components/reui/filters/filters-types"
+
+/**
+ * The filter builder's step machine. Pure: no React, Base UI or shadcn import,
+ * so the whole create and amend flow is a table test in node with no DOM.
+ *
+ * Arity arrives ON THE ACTION, which keeps the reducer free of the schema index
+ * while it still owns the branch that skips the value step. The shipped chrome
+ * drives `openCreate`, browse, query, `selectField` and `close`; `openAmend`,
+ * `selectOperator`, `setValue`, `commit`, `back` and `goto` are published
+ * surface for a consumer composing their own panel.
+ */
+export type FilterDraftAction<V = unknown> =
+  | { type: "openCreate"; cascaderPath?: string[] }
+  | {
+      type: "openAmend"
+      ruleId: string
+      step: FilterDraftStep
+      path: string[]
+      operator: string | null
+      value: V | undefined
+      cascaderPath?: string[]
+    }
+  | { type: "close" }
+  /** Where the user is BROWSING, not the selected field's path. */
+  | { type: "setCascaderPath"; path: string[] }
+  | { type: "setQuery"; query: string }
+  | {
+      type: "selectField"
+      path: string[]
+      defaultOperator: string | null
+    }
+  | {
+      type: "selectOperator"
+      operator: string
+      arity: FilterOperatorArity
+      /** Carried across the operator change, already coerced. */
+      value: V | undefined
+    }
+  | { type: "setValue"; value: V | undefined }
+  | { type: "commit"; value?: V }
+  | { type: "back" }
+  | { type: "goto"; step: FilterDraftStep }
+
+export function createFilterDraft<V = unknown>(
+  cascaderPath: string[] = []
+): FilterDraft<V> {
+  return {
+    step: "field",
+    status: "editing",
+    ruleId: null,
+    path: [],
+    cascaderPath,
+    operator: null,
+    value: undefined,
+    query: "",
+  }
+}
+
+/** null means Back closes the builder rather than stepping back. */
+function previousStep(step: FilterDraftStep): FilterDraftStep | null {
+  if (step === "value") return "operator"
+  if (step === "operator") return "field"
+  return null
+}
+
+/**
+ * `null` is the closed state, not a separate boolean: `{ open, draft }` would
+ * make "open with no draft" and "closed but still holding one" representable.
+ */
+export function filterDraftReducer<V = unknown>(
+  state: FilterDraft<V> | null,
+  action: FilterDraftAction<V>
+): FilterDraft<V> | null {
+  switch (action.type) {
+    case "openCreate":
+      return createFilterDraft<V>(action.cascaderPath ?? [])
+
+    case "openAmend":
+      return {
+        step: action.step,
+        status: "editing",
+        ruleId: action.ruleId,
+        path: action.path,
+        // Defaults the picker to the field's own level, so amend opens beside
+        // its siblings, not at the root. Callers may override.
+        cascaderPath: action.cascaderPath ?? action.path.slice(0, -1),
+        operator: action.operator,
+        value: action.value,
+        query: "",
+      }
+
+    case "close":
+      return null
+
+    case "setCascaderPath":
+      if (!state) return state
+      if (state.cascaderPath === action.path) return state
+      return { ...state, cascaderPath: action.path }
+
+    case "setQuery":
+      if (!state) return state
+      if (state.query === action.query) return state
+      return { ...state, query: action.query }
+
+    case "selectField": {
+      if (!state) return state
+      // Choosing a field COMMITS at once; the condition is picked on the chip,
+      // so the popover never holds a second and third step to walk.
+      return {
+        ...state,
+        path: action.path,
+        operator: action.defaultOperator,
+        status: "ready",
+        // A field change invalidates the value: "Active" means nothing once
+        // the field becomes "Created at".
+        value: undefined,
+        step: "operator",
+        query: "",
+      }
+    }
+
+    case "selectOperator": {
+      if (!state) return state
+      // arity "none" is the whole filter; a value step would be an empty panel.
+      if (action.arity === "none") {
+        return {
+          ...state,
+          operator: action.operator,
+          value: undefined,
+          status: "ready",
+          query: "",
+        }
+      }
+      return {
+        ...state,
+        operator: action.operator,
+        value: action.value,
+        step: "value",
+        status: "editing",
+        query: "",
+      }
+    }
+
+    case "setValue":
+      if (!state) return state
+      return { ...state, value: action.value }
+
+    case "commit":
+      if (!state) return state
+      return {
+        ...state,
+        value: action.value === undefined ? state.value : action.value,
+        status: "ready",
+      }
+
+    case "back": {
+      if (!state) return state
+      const step = previousStep(state.step)
+      if (!step) return null
+      return { ...state, step, status: "editing", query: "" }
+    }
+
+    case "goto":
+      if (!state) return state
+      if (state.step === action.step) return state
+      return { ...state, step: action.step, status: "editing", query: "" }
+
+    default:
+      return state
+  }
+}
+
+/**
+ * A path is enough. Not an operator: the flow commits when the field is picked,
+ * so `operator: ""` is a legitimate committed state. Not a value either, since
+ * `arity: "none"` has none and an editor may commit `undefined` to clear.
+ */
+export function isFilterDraftCommittable<V>(
+  draft: FilterDraft<V> | null
+): draft is FilterDraft<V> {
+  return Boolean(draft && draft.path.length > 0)
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-editors.tsx b/apps/web/src/components/reui/filters/filters-editors.tsx
new file mode 100644
index 0000000..59f698f
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-editors.tsx
@@ -0,0 +1,1341 @@
+"use client"
+
+import * as React from "react"
+import {
+  Cascader,
+  CascaderEmpty,
+  CascaderList,
+  CascaderPanel,
+  CascaderStatus,
+} from "@/components/reui/cascader/cascader"
+import type {
+  CascaderItemState,
+  CascaderProps,
+} from "@/components/reui/cascader/cascader"
+import {
+  useCascaderActions,
+  useCascaderHighlight,
+} from "@/components/reui/cascader/cascader-context"
+import { CascaderFooter } from "@/components/reui/cascader/cascader-footer"
+import { CascaderItems } from "@/components/reui/cascader/cascader-item"
+import {
+  CascaderInput,
+  CascaderNav,
+} from "@/components/reui/cascader/cascader-nav"
+import type {
+  CascaderActionItem,
+  CascaderNode,
+} from "@/components/reui/cascader/cascader-types"
+import {
+  FilterActionsContext,
+  filterControlSizes,
+  type FilterResolutionStore,
+} from "@/components/reui/filters/filters-context"
+import {
+  applyFilterExclusiveSelection,
+  filterFilterOptions,
+  joinFilterPath,
+  normalizeFilterQuery,
+  warnFilterOnce,
+} from "@/components/reui/filters/filters-lib"
+import type {
+  AnyFilterEditor,
+  FilterEditorProps,
+  FilterEditorRegistry,
+  FilterField,
+  FilterIndex,
+  FilterLabels,
+  FilterLoadResult,
+  FilterOperator,
+  FilterOption,
+  FilterOptionsState,
+} from "@/components/reui/filters/filters-types"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { Button } from "@authportal/ui/components/button"
+import { ButtonGroup } from "@authportal/ui/components/button-group"
+import { Input } from "@authportal/ui/components/input"
+import { CheckIcon, XIcon } from "lucide-react"
+
+/* -------------------------------------------------------------------------- */
+/*                              The options service                           */
+/* -------------------------------------------------------------------------- */
+
+interface OptionsInternalState<O> {
+  items: FilterOption<O>[]
+  loading: boolean
+  error: boolean
+  hasMore: boolean
+  cursor?: string
+}
+
+const IDLE: OptionsInternalState<never> = {
+  items: [],
+  loading: false,
+  error: false,
+  hasMore: false,
+}
+
+/** Stable no-op subscription, for a hook running outside a `Filters` root. */
+const emptySubscribe = () => () => {}
+const zeroVersion = () => 0
+
+/**
+ * The joined path of a field, from the schema index. Keyed by PATH, not field
+ * identity, so labels survive a schema rebuild; an unknown field uses its id.
+ */
+function filterFieldKey<V, O>(
+  field: FilterField<V, O> | undefined,
+  index: FilterIndex | undefined
+): string | null {
+  if (!field) return null
+  if (index) {
+    for (const entry of index.all) {
+      if ((entry.field as unknown) === (field as unknown)) {
+        return joinFilterPath(entry.path)
+      }
+    }
+  }
+  return `#${field.id}`
+}
+
+/**
+ * The shared option service every option-backed editor receives: debouncing,
+ * aborting, cursor paging and value-to-label resolution. A deliberate fork of
+ * the cascader's async machinery. Resolution is two-tier: a ref cache written
+ * in an EFFECT, plus the root's `FilterResolutionStore`, without which a
+ * `loadOptions`-only field showed its raw id once the menu closed.
+ */
+export function useFilterOptions<V, O>(
+  field: FilterField<V, O> | undefined,
+  enabled: boolean,
+  debounceMs = 250
+): FilterOptionsState<O> {
+  const [query, setQueryState] = React.useState("")
+  const [state, setState] = React.useState<OptionsInternalState<O>>(
+    IDLE as OptionsInternalState<O>
+  )
+
+  const cache = React.useRef(new Map<string, FilterOption<O>>())
+  const requestId = React.useRef(0)
+  const abortRef = React.useRef<AbortController | null>(null)
+
+  // Read directly, so this degrades outside a `Filters` root instead of throwing.
+  const actionsContext = React.useContext(FilterActionsContext)
+  const shared: FilterResolutionStore | null =
+    actionsContext?.resolution ?? null
+  const sharedKey = filterFieldKey(field, actionsContext?.index)
+
+  // Re-render when a label lands ANYWHERE under this root, not just here.
+  React.useSyncExternalStore(
+    shared ? shared.subscribe : emptySubscribe,
+    shared ? shared.getVersion : zeroVersion,
+    shared ? shared.getVersion : zeroVersion
+  )
+
+  const staticOptions = field?.options
+  const loadOptions = field?.loadOptions
+  const isAsync = Boolean(loadOptions)
+
+  // Seeded in an effect, not during render, so the render stays pure.
+  React.useEffect(() => {
+    if (!staticOptions) return
+    for (const option of staticOptions) cache.current.set(option.value, option)
+    if (shared && sharedKey) shared.set(sharedKey, staticOptions)
+  }, [staticOptions, shared, sharedKey])
+
+  React.useEffect(() => {
+    for (const option of state.items) cache.current.set(option.value, option)
+    if (shared && sharedKey && state.items.length) {
+      shared.set(sharedKey, state.items)
+    }
+  }, [state.items, shared, sharedKey])
+
+  const run = React.useCallback(
+    async (nextQuery: string, cursor: string | undefined, append: boolean) => {
+      if (!loadOptions) return
+
+      abortRef.current?.abort()
+      const controller = new AbortController()
+      abortRef.current = controller
+      const id = ++requestId.current
+
+      setState((previous) => ({
+        ...previous,
+        loading: true,
+        error: false,
+        items: append ? previous.items : [],
+      }))
+
+      try {
+        const result = await loadOptions(nextQuery, {
+          signal: controller.signal,
+          cursor,
+        })
+        // A superseded request must not write; the id, not the abort, decides.
+        if (id !== requestId.current) return
+
+        const normalized: FilterLoadResult<O> = Array.isArray(result)
+          ? { items: result }
+          : result
+
+        setState((previous) => ({
+          items: append
+            ? [...previous.items, ...normalized.items]
+            : normalized.items,
+          loading: false,
+          error: false,
+          hasMore: normalized.hasMore ?? Boolean(normalized.nextCursor),
+          cursor: normalized.nextCursor,
+        }))
+      } catch (error) {
+        if (id !== requestId.current) return
+        if ((error as Error)?.name === "AbortError") return
+        setState((previous) => ({
+          ...previous,
+          loading: false,
+          error: true,
+          hasMore: false,
+        }))
+      }
+    },
+    [loadOptions]
+  )
+
+  React.useEffect(() => {
+    if (!enabled || !isAsync) return
+    const timer = setTimeout(
+      () => void run(query, undefined, false),
+      debounceMs
+    )
+    return () => clearTimeout(timer)
+  }, [enabled, isAsync, query, debounceMs, run])
+
+  React.useEffect(() => {
+    return () => abortRef.current?.abort()
+  }, [])
+
+  const normalizedQuery = normalizeFilterQuery(query)
+
+  // Async results are server-filtered; re-filtering hides what the label omits.
+  const items = React.useMemo(() => {
+    if (isAsync) return state.items
+    return filterFilterOptions(staticOptions ?? [], normalizedQuery)
+  }, [isAsync, state.items, staticOptions, normalizedQuery])
+
+  const setQuery = React.useCallback((next: string) => setQueryState(next), [])
+
+  const loadMore = React.useCallback(() => {
+    if (!state.hasMore || state.loading) return
+    void run(query, state.cursor, true)
+  }, [state.hasMore, state.loading, state.cursor, query, run])
+
+  const retry = React.useCallback(() => {
+    void run(query, undefined, false)
+  }, [query, run])
+
+  const resolve = React.useCallback(
+    (value: string) => {
+      // The ref cache cannot be the only tier: a ref write triggers no render,
+      // so the chip would paint the raw value and never repaint. The shared
+      // store holds other instances' pages and re-renders this one on a gain.
+      const declared = staticOptions?.find((option) => option.value === value)
+      if (declared) return declared
+      const fromShared =
+        shared && sharedKey ? shared.get(sharedKey, value) : undefined
+      if (fromShared) return fromShared as FilterOption<O>
+      return cache.current.get(value)
+    },
+    [staticOptions, shared, sharedKey]
+  )
+
+  return {
+    items,
+    loading: state.loading,
+    error: state.error,
+    hasMore: state.hasMore,
+    query,
+    setQuery,
+    loadMore,
+    retry,
+    resolve,
+  }
+}
+
+/**
+ * Resolves committed values no loaded page covered, through `resolveValues`: a
+ * restored saved view holds ids the loader never returned. The claim set marks
+ * an omitted id asked, so only a REJECTED resolve lets a later mount retry.
+ */
+export function useFilterValueResolution<V, O>(
+  field: FilterField<V, O> | undefined,
+  values: readonly unknown[]
+): void {
+  const actionsContext = React.useContext(FilterActionsContext)
+  const shared: FilterResolutionStore | null =
+    actionsContext?.resolution ?? null
+  const sharedKey = filterFieldKey(field, actionsContext?.index)
+  const resolveValues = field?.resolveValues
+  const staticOptions = field?.options
+  // Keyed by CONTENT; NUL cannot occur inside a real stored value.
+  const valuesKey = values.map((entry) => String(entry)).join("\u0000")
+
+  React.useEffect(() => {
+    if (!resolveValues || !shared || !sharedKey || valuesKey === "") return
+    const missing = valuesKey.split("\u0000").filter((value) => {
+      if (staticOptions?.some((option) => option.value === value)) return false
+      return shared.get(sharedKey, value) === undefined
+    })
+    const wanted = shared.claim(sharedKey, missing)
+    if (wanted.length === 0) return
+
+    // No unmount guard: the store outlives the component.
+    void Promise.resolve(resolveValues(wanted)).then(
+      (options) => shared.set(sharedKey, options),
+      () => shared.release(sharedKey, wanted)
+    )
+  }, [resolveValues, shared, sharedKey, valuesKey, staticOptions])
+}
+
+/* -------------------------------------------------------------------------- */
+/*                               Shared chrome                                */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The panel every editor renders into. A plain flex column, NOT a combobox: an
+ * editor inside a Base UI composite would inherit its `aria-activedescendant`
+ * and arrow keys, which is hostile to a colour picker or a slider.
+ */
+function EditorPanel({
+  children,
+  className,
+}: {
+  children: React.ReactNode
+  className?: string
+}) {
+  return (
+    <div
+      data-slot="filter-editor"
+      className={cn(
+        "flex w-full flex-col gap-2 p-2",
+        /* The list height cap as a VARIABLE, not the `maxHeight` prop, which
+           becomes an inline style no consumer class can beat. 16rem is the
+           256px the menu has always used. */
+        "[--cascader-max-height:16rem]",
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+function EditorFooter({
+  onCancel,
+  onCommit,
+  labels,
+  host,
+}: Pick<FilterEditorProps, "labels" | "host"> & {
+  onCancel: () => void
+  onCommit: () => void
+}) {
+  // The ONE ladder, not a hardcoded rung: `size="sm"` here measured 4px short
+  // of the bar's own controls at `size="default"` in all eight styles.
+  const actions = React.useContext(FilterActionsContext)
+  const sizes = filterControlSizes({ size: actions?.size ?? "default" })
+
+  // The create host advances on commit and has Back; amend must offer discard.
+  if (host === "create") return null
+  return (
+    <div className="flex items-center justify-end gap-1.5 pt-1">
+      <Button variant="ghost" size={sizes.button} onClick={onCancel}>
+        {labels.discard}
+      </Button>
+      <Button size={sizes.button} onClick={onCommit}>
+        {labels.apply}
+      </Button>
+    </div>
+  )
+}
+
+/**
+ * `w-full` because `ButtonGroup` is `w-fit`, which collapses inside this
+ * fixed-width panel. Sera is an underline style, so its direct children flatten
+ * to one bottom-only edge - `border-b-input`, not transparent, since the
+ * buttons are the trailing edge and the rule would stop mid-panel.
+ */
+const EDITOR_FIELD_GROUP =
+  "w-full"
+
+/**
+ * Confirm and cancel, an OUTLINE pair FUSED onto the field's trailing edge.
+ * Returns a FRAGMENT: `ButtonGroup` fuses with selectors matching DIRECT
+ * children only, so a wrapper div renders three separate boxes. `size="icon"`
+ * because every style's icon button at that size is exactly its input's height.
+ */
+function EditorCommitButtons({
+  onCancel,
+  onCommit,
+  labels,
+}: Pick<FilterEditorProps, "labels"> & {
+  onCancel: () => void
+  onCommit: () => void
+}) {
+  return (
+    <>
+      <Button
+        type="button"
+        variant="outline"
+        size="icon"
+        aria-label={labels.apply}
+        onClick={onCommit}
+      >
+        <CheckIcon aria-hidden="true" />
+      </Button>
+      <Button
+        type="button"
+        variant="outline"
+        size="icon"
+        aria-label={labels.discard}
+        onClick={onCancel}
+      >
+        <XIcon aria-hidden="true" />
+      </Button>
+    </>
+  )
+}
+
+function useCommitKeys(commit: () => void, cancel: () => void) {
+  return React.useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.key === "Enter" && !event.nativeEvent.isComposing) {
+        event.preventDefault()
+        commit()
+        return
+      }
+      if (event.key === "Escape") {
+        event.preventDefault()
+        // Stop here so a surrounding dialog does not also close.
+        event.stopPropagation()
+        cancel()
+      }
+    },
+    [commit, cancel]
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                Text / number                               */
+/* -------------------------------------------------------------------------- */
+
+export function FilterTextEditor<V, O>({
+  value,
+  onValueChange,
+  commit,
+  cancel,
+  autoFocusProps,
+  labels,
+  host,
+  field,
+}: FilterEditorProps<V, O>) {
+  const onKeyDown = useCommitKeys(() => commit(), cancel)
+  return (
+    // A width, not shrink-to-fit: the popover is `w-auto`, so an unsized box
+    // changes width between the hosts. `w-72` is measured - it holds about 23
+    // characters in sera and 27 in nova; `w-64` held about eighteen, too short
+    // for an email, and `w-80` was the widest control in a bar of compact
+    // chips. Capped at the viewport because `w-80` is 320px and a 360px phone
+    // has 40px to spare. A `w-*` on the field wins.
+    <EditorPanel
+      className={cn("w-72 max-w-[calc(100vw-2rem)] min-w-0", field.className)}
+    >
+      <ButtonGroup className={EDITOR_FIELD_GROUP}>
+        <Input
+          {...autoFocusProps}
+          value={(value as string) ?? ""}
+          placeholder={field.placeholder ?? labels.valuePlaceholder}
+          aria-label={field.label}
+          onChange={(event) => onValueChange(event.target.value as V)}
+          onKeyDown={onKeyDown}
+        />
+        {/*
+          A lone input still belongs in the group: the per-style sheets re-round
+          the LAST child, so a group with nothing fused draws the bare field.
+        */}
+        {host === "create" ? null : (
+          <EditorCommitButtons
+            labels={labels}
+            onCancel={cancel}
+            onCommit={() => commit()}
+          />
+        )}
+      </ButtonGroup>
+    </EditorPanel>
+  )
+}
+
+export function FilterNumberEditor<V, O>({
+  value,
+  onValueChange,
+  commit,
+  cancel,
+  autoFocusProps,
+  labels,
+  host,
+  field,
+}: FilterEditorProps<V, O>) {
+  const onKeyDown = useCommitKeys(() => commit(), cancel)
+  return (
+    // Deliberately not the text editor's `w-72`: number values are short by
+    // construction, and a wide box around "42" is the opposite defect.
+    <EditorPanel className={cn("w-56 min-w-0", field.className)}>
+      <ButtonGroup className={EDITOR_FIELD_GROUP}>
+        <Input
+          {...autoFocusProps}
+          type="number"
+          value={value === undefined || value === null ? "" : String(value)}
+          placeholder={field.placeholder}
+          aria-label={field.label}
+          onChange={(event) => {
+            const raw = event.target.value
+            onValueChange((raw === "" ? undefined : Number(raw)) as V)
+          }}
+          onKeyDown={onKeyDown}
+        />
+        {host === "create" ? null : (
+          <EditorCommitButtons
+            labels={labels}
+            onCancel={cancel}
+            onCommit={() => commit()}
+          />
+        )}
+      </ButtonGroup>
+    </EditorPanel>
+  )
+}
+
+export function FilterRangeEditor<V, O>({
+  value,
+  onValueChange,
+  commit,
+  cancel,
+  autoFocusProps,
+  labels,
+  host,
+  field,
+}: FilterEditorProps<V, O>) {
+  const tuple = (Array.isArray(value) ? value : []) as unknown[]
+  const onKeyDown = useCommitKeys(() => commit(), cancel)
+
+  const update = (index: 0 | 1, raw: string) => {
+    const next = [tuple[0], tuple[1]]
+    next[index] = raw === "" ? undefined : Number(raw)
+    onValueChange(next as V)
+  }
+
+  return (
+    <EditorPanel>
+      <div className="flex items-center gap-1.5">
+        <Input
+          {...autoFocusProps}
+          type="number"
+          value={tuple[0] === undefined ? "" : String(tuple[0])}
+          aria-label={labels.rangeFrom(field.label)}
+          onChange={(event) => update(0, event.target.value)}
+          onKeyDown={onKeyDown}
+        />
+        <span className="text-muted-foreground text-xs">
+          {labels.rangeSeparator}
+        </span>
+        <Input
+          type="number"
+          value={tuple[1] === undefined ? "" : String(tuple[1])}
+          aria-label={labels.rangeTo(field.label)}
+          onChange={(event) => update(1, event.target.value)}
+          onKeyDown={onKeyDown}
+        />
+      </div>
+      <EditorFooter
+        host={host}
+        labels={labels}
+        onCancel={cancel}
+        onCommit={() => commit()}
+      />
+    </EditorPanel>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  The menu                                  */
+/* -------------------------------------------------------------------------- */
+
+/** One row. The shape both the operator menu and the option editors hand over. */
+export interface FilterListItem {
+  value: string
+  label: string
+  icon?: React.ReactNode
+  description?: string
+  keywords?: string[]
+  disabled?: boolean
+  /**
+   * A None row, from `FilterOption.exclusive`. LAYOUT only: what a pick DOES is
+   * `applyFilterExclusiveSelection`, in the option editor's handler. A consumer
+   * composing `FilterMenu` into an editor of their own owns the same call.
+   */
+  exclusive?: boolean
+}
+
+/**
+ * Beyond the cascader's own fields: one divider flag, on the first row of a
+ * group that is not the first, because grouping happens out here. A separator
+ * NODE would join the option ring, and `[data-selected] + :not([data-selected])`
+ * reads the LIVE selection, so unticking a pinned row drew a second line.
+ */
+interface FilterMenuMeta {
+  divider?: boolean
+  /**
+   * Carries `FilterListItem.exclusive` down to the row. The rule above it is
+   * `aria-hidden`, so the row's accessible name is the only channel arriving
+   * before the press, and `renderItem` receives the node and nothing else.
+   *
+   * `[data-slot=filter-menu-exclusive-hint]` is also the handle a consumer
+   * styles the row through: the cascader's row element takes no attribute of
+   * ours, so `:has([data-slot=filter-menu-exclusive-hint])` selects it.
+   */
+  exclusive?: boolean
+}
+
+/** Joins a selection into one comparable key; NUL cannot occur in a value. */
+const PIN_SEPARATOR = "\u0000"
+
+/** A bound on a race: each attempt costs one task and stops on success. */
+const MAX_PIN_RESTORE_ATTEMPTS = 4
+
+interface PendingPinRestore {
+  /** The row the user was on when the rows moved. Tracked by VALUE, never index. */
+  value: string
+  /** The index it sat at, which is the half of the signature Base UI keeps. */
+  index: number
+  /** The order the rows landed in, so the target's new position is known. */
+  order: string[]
+  attempts: number
+}
+
+/**
+ * Carries the HIGHLIGHT across a live re-pin. Base UI holds it as an INDEX and
+ * a keyed reorder MOVES the DOM node rather than remounting it, so the index
+ * map only rebuilds when the `MutationObserver` fires: until then, ticking a
+ * row moves the highlight down one. So this ARMS in the layout effect, where
+ * the map still reads the OLD order, and fires on the signature (SAME index,
+ * DIFFERENT row) from a TASK, re-trying because the store event and the re-sort
+ * are unordered. A synthetic `mousemove`, since Base UI exposes no setter.
+ */
+function FilterMenuPinKeeper({
+  order,
+  items,
+}: {
+  order: string[]
+  /** The data the order was derived from, by identity. */
+  items: FilterListItem[]
+}) {
+  const { baseId } = useCascaderActions()
+  const highlight = useCascaderHighlight()
+  const previousRef = React.useRef<{
+    order: string[]
+    items: FilterListItem[]
+  } | null>(null)
+  const pendingRef = React.useRef<PendingPinRestore | null>(null)
+  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  // From the render: on the reordering commit a ref still holds the OLD row.
+  const highlightedValue = highlight.value
+  const highlightedIndex = highlight.index
+
+  const stop = React.useCallback(() => {
+    pendingRef.current = null
+    if (timerRef.current === null) return
+    clearTimeout(timerRef.current)
+    timerRef.current = null
+  }, [])
+
+  const startRestore = React.useCallback(() => {
+    const attempt = () => {
+      timerRef.current = null
+      const pending = pendingRef.current
+      if (!pending) return
+
+      const target = pending.order.indexOf(pending.value)
+      const rows = document
+        .getElementById(`${baseId}-column-0`)
+        ?.querySelectorAll<HTMLElement>('[data-slot="cascader-item"]')
+      // A WINDOWED list renders a subset, so row N is not order[N]. Leave it.
+      if (target < 0 || !rows || rows.length !== pending.order.length) {
+        stop()
+        return
+      }
+
+      rows[target]?.dispatchEvent(
+        new MouseEvent("mousemove", { bubbles: true })
+      )
+
+      pending.attempts += 1
+      if (pending.attempts >= MAX_PIN_RESTORE_ATTEMPTS) {
+        stop()
+        return
+      }
+      timerRef.current = setTimeout(attempt, 0)
+    }
+
+    timerRef.current = setTimeout(attempt, 0)
+  }, [baseId, stop])
+
+  // No dependency list: the arm must run on the commit that reorders the rows.
+  React.useLayoutEffect(() => {
+    const previous = previousRef.current
+    previousRef.current = { order, items }
+
+    if (!previous || previous.order === order) return
+    // New DATA (a page, a query) is Base UI's to highlight; only a re-pin is ours.
+    if (previous.items !== items) return
+    if (!highlightedValue) return
+    // Content, not identity: a re-pin can leave the rows in the same order.
+    if (isSameOrder(previous.order, order)) return
+
+    pendingRef.current = {
+      value: highlightedValue,
+      index: highlightedIndex,
+      order,
+      attempts: 0,
+    }
+  })
+
+  React.useEffect(() => {
+    const pending = pendingRef.current
+    if (!pending) return
+
+    // Back where it belongs, or moved by the user: either way the arm is spent.
+    if (
+      highlightedValue === pending.value ||
+      highlightedIndex !== pending.index
+    ) {
+      stop()
+      return
+    }
+    // Already chasing this one; a second chain would double every dispatch.
+    if (pending.attempts > 0 || timerRef.current !== null) return
+    startRestore()
+  }, [highlightedValue, highlightedIndex, startRestore, stop])
+
+  React.useEffect(() => stop, [stop])
+
+  return null
+}
+
+/** Element-wise, because the arrays are rebuilt on every selection change. */
+function isSameOrder(a: string[], b: string[]) {
+  if (a.length !== b.length) return false
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] !== b[index]) return false
+  }
+  return true
+}
+
+export interface FilterMenuProps {
+  items: FilterListItem[]
+  /** Committed values. Drives the check mark and the pinned group. */
+  selected: string[]
+  multiple?: boolean
+  /** Receives the FULL next selection, so no caller re-derives it. */
+  onSelectionChange: (values: string[]) => void
+  labels: FilterLabels
+  ariaLabel: string
+  searchPlaceholder?: string
+  /** Whether the search field is VISIBLE. It is always rendered regardless. */
+  searchable?: boolean
+  /**
+   * Viewport height before the list scrolls, in pixels. Omitted on purpose by
+   * the option editors: it becomes an inline style a consumer's `className`
+   * cannot outrank, so the panel publishes `--cascader-max-height` instead.
+   */
+  maxHeight?: number
+  /**
+   * Pin selected rows above the rest, with a full-bleed rule between them. Off
+   * by default; the option editors read `FilterField.pinSelected` per field.
+   */
+  pinSelected?: boolean
+  /**
+   * Order INSIDE each group, plus WHEN the partition is taken. Declaration
+   * order by default, so the partition is stable rather than a re-sort.
+   */
+  sortSelected?: "none" | "label" | "snapshot"
+  /** The caller already filtered `items`, so the cascader must not re-filter. */
+  preFiltered?: boolean
+  autoFocusProps?: FilterEditorProps["autoFocusProps"]
+  /** Controlled query. Pair it with `onQueryChange` to filter outside. */
+  query?: string
+  onQueryChange?: (query: string) => void
+  state?: Pick<
+    FilterOptionsState<unknown>,
+    "loading" | "error" | "hasMore" | "loadMore" | "retry"
+  >
+}
+
+/**
+ * One accessible list, shared by the operator menu and every option editor. It
+ * is the CASCADER configured flat, not a list this file implements, which
+ * brings the typeahead, RTL handling and live region with it. Only the pinning
+ * and the paging affordance stay out here.
+ */
+export function FilterMenu({
+  items,
+  selected,
+  multiple = false,
+  onSelectionChange,
+  labels,
+  ariaLabel,
+  searchPlaceholder,
+  searchable = true,
+  maxHeight,
+  pinSelected = false,
+  sortSelected = "none",
+  preFiltered = false,
+  autoFocusProps,
+  query,
+  onQueryChange,
+  state,
+}: FilterMenuProps) {
+  /**
+   * The pin set as a KEY, not an array: `selected` is a fresh array on most
+   * renders, so a memo depending on it re-partitions every render.
+   */
+  const liveKey = pinSelected ? selected.join(PIN_SEPARATOR) : ""
+
+  /**
+   * The same set, frozen at OPEN, for `sortSelected: "snapshot"`. LIVE is the
+   * default: "your picks, then the rest" is about the CURRENT selection, and
+   * `FilterMenuPinKeeper` pays for rows moving under the pointer.
+   */
+  const [snapshotKey] = React.useState(() => liveKey)
+  // `pinSelected` re-checked here, not just through `liveKey`: `snapshotKey` is
+  // frozen at MOUNT, so a menu that lost the prop would keep partitioning.
+  const pinnedKey = !pinSelected
+    ? ""
+    : sortSelected === "snapshot"
+      ? snapshotKey
+      : liveKey
+
+  // Uncontrolled unless the caller owns the query, as an option service does.
+  const [ownQuery, setOwnQuery] = React.useState("")
+  const currentQuery = query ?? ownQuery
+  const setQuery = onQueryChange ?? setOwnQuery
+
+  /**
+   * Memoized on the SELECTION, not the query: folding the query in re-sorted
+   * 4,000 rows on every keystroke, for a one pixel rule.
+   */
+  const partitioned = React.useMemo(() => {
+    const pinned = new Set(pinnedKey ? pinnedKey.split(PIN_SEPARATOR) : [])
+
+    /*
+      Exclusive rows come out BEFORE the pin partition; their position is fixed.
+      Pinning is by SELECTION, so a ticked None row would lift itself above the
+      very rule drawn to set it apart and drop back on untick. Grouping by ROLE
+      means the pinned group counts ordinary picks only, which is also why
+      picking None draws no pin rule: it clears every other pick.
+    */
+    const exclusive = items.filter((item) => item.exclusive)
+    const values = exclusive.length
+      ? items.filter((item) => !item.exclusive)
+      : items
+
+    const chosen = pinned.size
+      ? values.filter((item) => pinned.has(item.value))
+      : []
+    const rest = pinned.size
+      ? values.filter((item) => !pinned.has(item.value))
+      : values
+
+    // The SCHEMA's order inside each group unless the field asks otherwise:
+    // option order is usually semantic.
+    const ordered =
+      sortSelected === "label"
+        ? [
+            [...chosen].sort((a, b) => a.label.localeCompare(b.label)),
+            [...rest].sort((a, b) => a.label.localeCompare(b.label)),
+            [...exclusive].sort((a, b) => a.label.localeCompare(b.label)),
+          ]
+        : [chosen, rest, exclusive]
+
+    const rows = [...ordered[0], ...ordered[1], ...ordered[2]]
+
+    return {
+      chosenCount: chosen.length,
+      /** Index of the first exclusive row, or -1 when the list has none. */
+      exclusiveAt: exclusive.length ? rows.length - exclusive.length : -1,
+      // The render order alone, so a REORDER is an identity compare.
+      order: rows.map((item) => item.value),
+      nodes: rows.map<CascaderNode<FilterMenuMeta>>((item) => ({
+        value: item.value,
+        label: item.label,
+        icon: item.icon,
+        description: item.description,
+        keywords: item.keywords,
+        disabled: item.disabled,
+        // Only exclusive rows carry `data`, so the ordinary 4,000 keep theirs.
+        data: item.exclusive ? { exclusive: true } : undefined,
+      })),
+    }
+  }, [items, pinnedKey, sortSelected])
+
+  // No rule under a query: "your picks, then the rest" is about the WHOLE list.
+  const dividerAt =
+    partitioned.chosenCount && !currentQuery.trim()
+      ? partitioned.chosenCount
+      : -1
+
+  // Survives a search, unlike the pin rule: it is a fact about the row.
+  const exclusiveDividerAt = partitioned.exclusiveAt
+
+  const nodes = React.useMemo<CascaderNode<FilterMenuMeta>[]>(() => {
+    const total = partitioned.nodes.length
+    // Only a boundary with rows on BOTH sides is one: a rule on row 0 would
+    // be a line above the top of the list.
+    const marks = [dividerAt, exclusiveDividerAt].filter(
+      (index) => index > 0 && index < total
+    )
+    if (marks.length === 0) return partitioned.nodes
+    // Rows rewritten, not rebuilt: copying 4,000 objects would undo the split.
+    const next = partitioned.nodes.slice()
+    for (const index of marks) {
+      // MERGED, never replaced: the two boundaries usually fall on one row, and
+      // overwriting `data` dropped the flag the accessible name is built from.
+      next[index] = {
+        ...next[index],
+        data: { ...next[index].data, divider: true },
+      }
+    }
+    return next
+  }, [partitioned, dividerAt, exclusiveDividerAt])
+
+  const renderItem = React.useCallback(
+    (
+      node: CascaderNode<FilterMenuMeta>,
+      itemState: CascaderItemState<FilterMenuMeta>
+    ) => (
+      <>
+        {node.data?.divider ? (
+          <span
+            data-slot="filter-menu-divider"
+            aria-hidden="true"
+            /* Full bleed, over the per-style `--cascader-list-pad` the shell
+               publishes: a rule stopping at the row's inset box reads as a gap.
+               Centred in the 8px the row gives back above itself, not `top-0`. */
+            className="bg-border absolute inset-x-[calc(var(--cascader-list-pad,4px)*-1)] -top-1 h-px"
+          />
+        ) : null}
+
+        {node.icon ? (
+          <span
+            data-slot="filter-menu-icon"
+            className="text-muted-foreground flex shrink-0 items-center justify-center"
+          >
+            {node.icon}
+          </span>
+        ) : null}
+
+        <span className="flex min-w-0 flex-1 flex-col items-start gap-0.5">
+          <span className="w-full truncate text-start">{node.label}</span>
+          {node.description ? (
+            <span className="text-muted-foreground w-full truncate text-start text-xs">
+              {node.description}
+            </span>
+          ) : null}
+        </span>
+
+        {/*
+          What the aria-hidden rule says, for the people it does not reach.
+          Inside the option element so it joins the row's accessible NAME, not
+          an `aria-describedby`: a description is announced late or not at all,
+          and this has to arrive before the press. The cascader's `srDetails`
+          cannot either: `renderItem` replaces the row body. Empty copy renders
+          nothing, so `labels.exclusiveHint` of "" silences it.
+        */}
+        {node.data?.exclusive && labels.exclusiveHint ? (
+          <span data-slot="filter-menu-exclusive-hint" className="sr-only">
+            {`, ${labels.exclusiveHint}`}
+          </span>
+        ) : null}
+
+        {/* A check mark in both modes, never the cascader's default box. */}
+        {itemState.selected ? (
+          <span
+            data-slot="filter-menu-check"
+            /* The gutter every style already reserves, on the cascader's own
+               logical inset. `end-*` rather than `right-2`, so RTL mirrors. */
+            className="size-4 pointer-events-none absolute end-[var(--cascader-row-inset,8px)]! flex items-center justify-center rtl:right-auto!"
+          >
+            <CheckIcon className="text-foreground! **:text-foreground!" />
+          </span>
+        ) : null}
+      </>
+    ),
+    [labels.exclusiveHint]
+  )
+
+  const cascaderLabels = React.useMemo(
+    () => ({
+      search: searchPlaceholder ?? labels.searchOptions,
+      empty: labels.empty,
+      loading: labels.loading,
+      loadingMore: labels.loadingMore,
+      loadMore: labels.loadMore,
+      error: labels.error,
+      retry: labels.retry,
+      // Named after the field, not the cascader's own "Top level" wording.
+      rootLevel: ariaLabel,
+      panelLabel: ariaLabel,
+      // Run FLAT, so the default hint would teach branch keys that do not exist.
+      keyboardHint: () => "",
+      // From `FilterLabels`, so the menu ships no English of its own.
+      resultsAnnouncement: labels.resultsAnnouncement,
+      actionsLabel: labels.actionsLabel,
+    }),
+    [labels, ariaLabel, searchPlaceholder]
+  )
+
+  /**
+   * Paging and retry in the pinned footer, never a row: a row would join the
+   * option ring, where arrows land on it and a query filters it away mid-page.
+   */
+  const actions = React.useMemo<CascaderActionItem[]>(() => {
+    if (state?.error) {
+      return [{ value: "retry", label: labels.retry, onSelect: state.retry }]
+    }
+    if (state?.hasMore) {
+      return [
+        {
+          value: "load-more",
+          label: state.loading ? labels.loadingMore : labels.loadMore,
+          disabled: state.loading,
+          onSelect: state.loadMore,
+        },
+      ]
+    }
+    return []
+  }, [state, labels])
+
+  const shared = {
+    // Inline and pinned open with a no-op handler, so the unconditional
+    // `setOpen(false)` of a single-select commit cannot dismiss the popover.
+    inline: true,
+    open: true,
+    onOpenChange: () => {},
+    items: nodes,
+    inputValue: currentQuery,
+    onInputValueChange: setQuery,
+    maxHeight,
+    renderItem,
+    labels: cascaderLabels,
+    actions,
+    // The option service is the ONE filter when it owns the query.
+    ...(preFiltered ? { filter: () => true } : null),
+  }
+
+  const cascaderProps: CascaderProps<FilterMenuMeta> = multiple
+    ? {
+        ...shared,
+        multiple: true,
+        value: selected,
+        onValueChange: (values: string[]) => onSelectionChange(values),
+      }
+    : {
+        ...shared,
+        value: selected[0] ?? "",
+        onValueChange: (value: string) =>
+          onSelectionChange(value ? [value] : []),
+      }
+
+  return (
+    <Cascader {...cascaderProps}>
+      <CascaderPanel>
+        {/*
+          `searchable: false` hides the FIELD, never removes it: the input owns
+          focus and `aria-activedescendant`, so a menu without one has no
+          keyboard. The class goes on the nav so the strip's border goes too.
+        */}
+        <CascaderNav
+          className={cn(
+            /* The nav's divider is `border-border/60` and the group separator
+               is a full-opacity `bg-border`; two strengths read as a mistake. */
+            "border-border",
+            !searchable && "sr-only"
+          )}
+        >
+          <CascaderInput
+            {...(autoFocusProps ?? {})}
+            placeholder={searchPlaceholder ?? labels.searchOptions}
+            aria-label={ariaLabel}
+          />
+        </CascaderNav>
+        <CascaderEmpty>
+          {state?.error
+            ? labels.error
+            : state?.loading
+              ? labels.loading
+              : labels.empty}
+        </CascaderEmpty>
+        {/*
+          Plain rows, DELIBERATELY not `CascaderVirtualItems`: windowing stands
+          `FilterMenuPinKeeper` down. The long lists are async and PAGE 25.
+        */}
+        <CascaderList
+          /**
+           * Real layout space around the group rule, which is absolutely
+           * positioned and adds no height. `renderItem` cannot reach the row's
+           * own box, and a spacer NODE would join the option ring.
+           *
+           * `:has()` is affordable here: scoped to this one list, a compound
+           * whose descendant exists on at most ONE row, and these menus render
+           * tens of rows rather than thousands.
+           */
+          className="[&>[data-slot=cascader-item]:has([data-slot=filter-menu-divider])]:mt-2"
+        >
+          <CascaderItems />
+        </CascaderList>
+        <CascaderFooter />
+        <CascaderStatus />
+        {/*
+          Last, so its layout effect reads the reordered DOM after every row has
+          registered. Not mounted at all for a menu that cannot reorder.
+        */}
+        {pinSelected && sortSelected !== "snapshot" ? (
+          <FilterMenuPinKeeper order={partitioned.order} items={items} />
+        ) : null}
+      </CascaderPanel>
+    </Cascader>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Option based editors                          */
+/* -------------------------------------------------------------------------- */
+
+function OptionEditor<V, O>(
+  props: FilterEditorProps<V, O> & { multiple: boolean }
+) {
+  const {
+    multiple,
+    options,
+    labels,
+    autoFocusProps,
+    commit,
+    cancel,
+    onValueChange,
+    value,
+    field,
+  } = props
+
+  const selected = React.useMemo(() => {
+    if (value === undefined || value === null) return []
+    return (Array.isArray(value) ? value : [value]) as string[]
+  }, [value])
+
+  const announce = React.useContext(FilterActionsContext)?.announce
+
+  return (
+    /*
+      A DELIBERATELY narrow default: 12rem holds around 22 characters at every
+      style's row size. `field.className` lands LAST, so a consumer's `w-*` wins.
+    */
+    <EditorPanel className={cn("w-48 min-w-0 gap-0 p-0", field.className)}>
+      <FilterMenu
+        items={options.items}
+        selected={selected}
+        multiple={multiple}
+        onSelectionChange={(raw) => {
+          /*
+            The ONE place the None rule is applied: every route into a selection
+            arrives here, so click and keyboard cannot disagree, and only the
+            editor can ANSWER it - `options.resolve` sees the schema and every
+            loaded page, where the menu holds only the rows on screen.
+          */
+          const values = applyFilterExclusiveSelection(raw, selected, (value) =>
+            Boolean(options.resolve(value)?.exclusive)
+          )
+
+          /*
+            Identity is the test: the rule hands back `raw` itself unless it
+            intervened. Announced because nothing else reports it: focus never
+            moved, and nobody is on the rows that lost their check marks.
+          */
+          if (values !== raw && announce) {
+            const arrived = values.find((entry) => !selected.includes(entry))
+            const cleared = raw.length - values.length
+            if (arrived !== undefined && cleared > 0) {
+              announce(
+                labels.exclusiveAnnouncement(
+                  options.resolve(arrived)?.label ?? arrived,
+                  cleared
+                )
+              )
+            }
+          } else if (values === raw && raw.length > 1) {
+            /*
+              The hole in the rule, made LOUD. An unresolvable value is treated
+              as ordinary and cannot be told from an id whose label has not
+              arrived, so this warns rather than acts. Needs a SEEN None row.
+            */
+            const hasNoneRow =
+              options.items.some((item) => item.exclusive) ||
+              Boolean(field.options?.some((option) => option.exclusive))
+            const unresolved = hasNoneRow
+              ? raw.find((entry) => options.resolve(entry) === undefined)
+              : undefined
+            if (unresolved !== undefined) {
+              warnFilterOnce(
+                `exclusive-unresolved:${field.id}`,
+                `field "${field.id}" has an exclusive option, but the value ` +
+                  `"${unresolved}" resolves to no option, so the None rule ` +
+                  `cannot tell whether it is the exclusive one and has left ` +
+                  `it in place. Declare the exclusive option in the field's ` +
+                  `\`options\` even when the rest of the list is async, or ` +
+                  `cover stored values with \`resolveValues\`.`
+              )
+            }
+          }
+
+          if (!multiple) {
+            const next = values[0]
+            // Base UI deselects the committed row; an empty filter is no gain.
+            if (next === undefined) {
+              cancel()
+              return
+            }
+            onValueChange(next as V)
+            commit(next as V)
+            return
+          }
+          onValueChange(values as V)
+          // Every toggle commits with the popover open: several picks, one gesture.
+          commit(values as V, { close: false })
+        }}
+        labels={labels}
+        ariaLabel={field.label}
+        searchable={field.searchable ?? true}
+        // Not a composed `Search ${label}...`: hardcoded English no `labels`
+        // override could reach, and lowercasing a label is locale-hostile.
+        searchPlaceholder={field.placeholder}
+        pinSelected={field.pinSelected ?? false}
+        sortSelected={field.sortSelected}
+        // `useFilterOptions` already applied the query, locally or server side.
+        preFiltered
+        query={options.query}
+        onQueryChange={options.setQuery}
+        state={options}
+        autoFocusProps={autoFocusProps}
+      />
+    </EditorPanel>
+  )
+}
+
+export function FilterSelectEditor<V, O>(props: FilterEditorProps<V, O>) {
+  return <OptionEditor {...props} multiple={false} />
+}
+
+export function FilterMultiSelectEditor<V, O>(props: FilterEditorProps<V, O>) {
+  return <OptionEditor {...props} multiple />
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Boolean                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Module level, so the menu's index is not rebuilt on every render. Not in
+ * `FilterLabels`: the chip's own display spells the same two words out.
+ */
+const BOOLEAN_ITEMS: FilterListItem[] = [
+  { value: "true", label: "True" },
+  { value: "false", label: "False" },
+]
+
+export function FilterBooleanEditor<V, O>({
+  value,
+  onValueChange,
+  commit,
+  labels,
+  autoFocusProps,
+  field,
+}: FilterEditorProps<V, O>) {
+  return (
+    // Two words, and `field.className` lands last so a consumer's `w-*` wins.
+    <EditorPanel className={cn("w-40 min-w-0 gap-0 p-0", field.className)}>
+      <FilterMenu
+        items={BOOLEAN_ITEMS}
+        selected={value === true ? ["true"] : value === false ? ["false"] : []}
+        onSelectionChange={(values) => {
+          /* Deselecting the committed row leaves nothing to filter on, so it is
+             a no-op rather than a commit of `false`. */
+          if (values.length === 0) return
+          const next = (values[0] === "true") as V
+          onValueChange(next)
+          commit(next)
+        }}
+        labels={labels}
+        ariaLabel={field.label}
+        /* Two rows: a search over them is more chrome than list, but the
+           field is still rendered, hidden, because it owns the keyboard. */
+        searchable={false}
+        autoFocusProps={autoFocusProps}
+      />
+    </EditorPanel>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Resolution                                */
+/* -------------------------------------------------------------------------- */
+
+export type {
+  AnyFilterEditor,
+  FilterEditorRegistry,
+} from "@/components/reui/filters/filters-types"
+
+export const DEFAULT_FILTER_EDITORS: FilterEditorRegistry = {
+  text: FilterTextEditor,
+  number: FilterNumberEditor,
+  range: FilterRangeEditor,
+  select: FilterSelectEditor,
+  multiselect: FilterMultiSelectEditor,
+  boolean: FilterBooleanEditor,
+}
+
+/**
+ * Picks the editor for a (field, operator) pair: the field's own `editor`, then
+ * the operator's ARITY, then the field's `type`. Arity outranks type because
+ * "between" wants two boxes whatever the field said.
+ */
+export function resolveFilterEditor<V, O>(
+  field: FilterField<V, O>,
+  operator: FilterOperator | undefined,
+  editors: FilterEditorRegistry
+): AnyFilterEditor | undefined {
+  if (typeof field.editor === "function") {
+    // The one place a consumer's typed editor meets the erased registry.
+    return field.editor as unknown as AnyFilterEditor
+  }
+  if (typeof field.editor === "string") {
+    const named = editors[field.editor]
+    if (named) return named
+  }
+
+  const arity = operator?.arity ?? "one"
+  if (arity === "none") return undefined
+  if (arity === "range") return editors.range
+  if (arity === "many") {
+    // An option-backed field gets checkboxes; anything else receives an array.
+    if (field.options || field.loadOptions) return editors.multiselect
+  }
+
+  return editors[field.type ?? "text"] ?? editors.text
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-i18n.tsx b/apps/web/src/components/reui/filters/filters-i18n.tsx
new file mode 100644
index 0000000..4398713
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-i18n.tsx
@@ -0,0 +1,151 @@
+import type {
+  FilterDraftStep,
+  FilterIssue,
+  FilterIssueReason,
+  FilterLabels,
+} from "@/components/reui/filters/filters-types"
+
+/**
+ * The shipped English copy. `stepAnnouncement` (consumer-composed create
+ * wizard) and `showRecords` (a consumer's own panel heading) are unread by the
+ * shipped chrome and kept on purpose; do not prune them as dead keys.
+ */
+export const DEFAULT_FILTER_LABELS: FilterLabels = {
+  addFilter: "Add filter",
+  advancedFilter: "Advanced filter",
+  showRecords: "In this view, show records",
+  builderEmpty: "No filters yet",
+  builderEmptyHint: "Add a filter to narrow down what you see.",
+  addCondition: "Add filter",
+  addConditionGroup: "Add group",
+  addToGroup: "Add filter to this group",
+  removeGroup: "Remove group",
+  wrapInGroup: "Wrap in group",
+  ungroup: "Ungroup",
+  moveToTopLevel: "Move to top",
+  moveToGroup: (position) => `Move to group ${position}`,
+  reorder: "Reorder",
+  reorderHint: "Press Alt with Arrow Up or Arrow Down to reorder",
+  groupAll: "All of the following are true...",
+  groupAny: "Any of the following are true...",
+  groupPlaceholder: "Drag filters here",
+  rowLabel: (condition, depth) => `${condition}, level ${depth}`,
+  groupLabel: (description, depth) => `${description} level ${depth}`,
+  groupAnnouncement: (added) => (added ? "Group added" : "Group removed"),
+  reorderAnnouncement: (label, position, total) =>
+    `${label} moved to position ${position} of ${total}`,
+  // Destination FIRST after the verb: it is the half a plain reorder cannot
+  // say and the half the user cannot see once the row has stopped moving.
+  // Position stays last, so this still ends on the "of N" a reorder ends on.
+  moveAnnouncement: (label, destination, position, total) =>
+    `${label} moved into ${destination}, position ${position} of ${total}`,
+  clearAll: "Clear all",
+  groupMenu: "Group options",
+  searchFields: "Search attributes...",
+  searchOperators: "Search operators...",
+  searchOptions: "Search...",
+  back: "Back",
+  clear: "Clear",
+  apply: "Apply",
+  discard: "Discard changes",
+  empty: "No results",
+  loading: "Loading...",
+  loadingMore: "Loading more...",
+  loadMore: "Load more",
+  error: "Could not load",
+  retry: "Retry",
+  where: "Where",
+  and: "And",
+  or: "Or",
+  combinator: "Change combinator",
+  // The word first: it is what the control SAYS and what a truncated pill
+  // stops showing. The action follows, so the name still names an action.
+  combinatorLabel: (word) => `${word}, change combinator`,
+  duplicate: "Duplicate",
+  negate: "Negate",
+  convertToAdvanced: "Advanced editor",
+  remove: "Remove",
+  chipMenu: (fieldLabel) => `${fieldLabel} filter options`,
+  filtersLabel: "Filters",
+  filterLabel: (condition) => condition,
+  readOnly: "Read only. These filters cannot be changed.",
+  pathSeparator: " > ",
+  valuePlaceholder: "enter text...",
+  selectPlaceholder: "Select...",
+  noValue: "no value",
+  selectCondition: "Select condition",
+  incomplete: "incomplete filter",
+  branchAffordance: "opens a list",
+  exclusiveHint: "cannot be combined with the other options",
+  exclusiveAnnouncement: (label, cleared) =>
+    cleared === 1
+      ? `${label} selected. 1 other selection cleared.`
+      : `${label} selected. ${cleared} other selections cleared.`,
+  itemCount: (count) => `${count} items`,
+  fieldsLabel: "Attributes",
+  resultsAnnouncement: (count) =>
+    count === 1 ? "1 result" : `${count} results`,
+  actionsLabel: "Actions",
+  stepAnnouncement: (step, label) => {
+    if (step === "field") return `Choose an attribute. ${label}`
+    if (step === "operator") return `Choose a condition for ${label}`
+    return `Enter a value for ${label}`
+  },
+  countAnnouncement: (count) =>
+    count === 1 ? "1 filter applied" : `${count} filters applied`,
+  valueCount: (count) => `${count} selected`,
+  valueDetail: (summary, values) => `${summary}: ${values.join(", ")}`,
+  valueRange: (from, to) => `${from} to ${to}`,
+  rangeFrom: (fieldLabel) => `${fieldLabel} from`,
+  rangeTo: (fieldLabel) => `${fieldLabel} to`,
+  rangeSeparator: "to",
+  negated: (operatorLabel) => `not ${operatorLabel}`,
+  issueOperator: "Choose a condition",
+  issueValue: "Enter a value",
+  issueRange: "Enter both ends of the range",
+  issueRangeOrder: "The end of the range comes before its start",
+  issueEmptyGroup: "This group has no conditions yet",
+  // "Row", not "condition": an empty GROUP is counted here too and a group is
+  // not a condition. Rule and group divs alike carry `data-slot="filter-row"`.
+  issueSummary: (count) =>
+    count === 1 ? "1 row needs attention" : `${count} rows need attention`,
+}
+
+/**
+ * Shallow merge over the defaults, like the cascader's. A deep merge would leak
+ * the default back into a replaced function-valued label for the arguments the
+ * consumer did not think about.
+ */
+export function resolveFilterLabels(
+  labels?: Partial<FilterLabels>
+): FilterLabels {
+  if (!labels) return DEFAULT_FILTER_LABELS
+  return { ...DEFAULT_FILTER_LABELS, ...labels }
+}
+
+/**
+ * The sentence for one issue. Takes the ISSUE, not just the reason: a field's
+ * `validate` supplies its own words, so `custom` has nothing to look up.
+ */
+export function filterIssueLabel(
+  issue: Pick<FilterIssue, "reason" | "message"> | FilterIssueReason,
+  labels: FilterLabels
+): string {
+  const reason = typeof issue === "string" ? issue : issue.reason
+  if (typeof issue !== "string" && issue.message) return issue.message
+  if (reason === "missing-operator") return labels.issueOperator
+  if (reason === "incomplete-range") return labels.issueRange
+  if (reason === "reversed-range") return labels.issueRangeOrder
+  if (reason === "empty-group") return labels.issueEmptyGroup
+  return labels.issueValue
+}
+
+/** The search placeholder for a step's panel. */
+export function stepPlaceholder(
+  step: FilterDraftStep,
+  labels: FilterLabels
+): string {
+  if (step === "field") return labels.searchFields
+  if (step === "operator") return labels.searchOperators
+  return labels.searchOptions
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-lib.tsx b/apps/web/src/components/reui/filters/filters-lib.tsx
new file mode 100644
index 0000000..b9c6058
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-lib.tsx
@@ -0,0 +1,539 @@
+import { collapseCascaderPath } from "@/components/reui/cascader/cascader-lib"
+import type { CascaderCollapse } from "@/components/reui/cascader/cascader-types"
+import type {
+  FilterField,
+  FilterIndex,
+  FilterOperator,
+  FilterOption,
+} from "@/components/reui/filters/filters-types"
+
+/* -------------------------------------------------------------------------- */
+/*                                    Menus                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * One menu size for the chip's kebab and the builder's three menus, which draw
+ * the same rows. `w-max` OVERRIDES the shadcn content width, which pins to the
+ * anchor and hides horizontal overflow, so a menu hung off a 28px icon button
+ * CUT every longer row. Floor 128px, down from 224px: the rows run about 130px,
+ * and five of the eight styles already floor a dropdown there (luma, maia and
+ * sera sit at 192px). The 24rem cap stops a pathological label pushing the menu
+ * off the side of a phone. Past it a row truncates rather than wraps, since a
+ * wrapped row changes HEIGHT and would slide the destructive row under the
+ * pointer: `min-w-0` lets a row shrink below its content at all (a flex child's
+ * floor is its content otherwise) and the label span carries `truncate`, see
+ * `FILTER_MENU_LABEL_CLASS`.
+ */
+export const FILTER_MENU_CLASS =
+  "w-max min-w-32 max-w-[min(24rem,calc(100vw-2rem))] [&_[data-slot=dropdown-menu-item]]:min-w-0"
+
+/**
+ * What a menu row's LABEL wears, and it has to be a real span: `text-overflow`
+ * needs a block container, not the anonymous flex item a bare text child is.
+ * `min-w-0` so the span can shrink below its own content.
+ */
+export const FILTER_MENU_LABEL_CLASS = "min-w-0 truncate"
+
+/**
+ * The FIELD PICKER's panel, shared by the Add filter popover and the advanced
+ * row's attribute cell so one schema is never drawn at two widths. `w-auto`
+ * grows to the longest row, so the 224px floor (down from 256px) only decides
+ * the reported case: a flat schema of short names in a mostly empty panel.
+ * Measured: 224px still clears the search input, the breadcrumb and a leaf
+ * row's icon-plus-label.
+ */
+export const FILTER_FIELD_PICKER_CLASS = "w-auto min-w-56 p-0"
+
+/* -------------------------------------------------------------------------- */
+/*                                    Paths                                   */
+/* -------------------------------------------------------------------------- */
+
+/** Root key for `childrenOf`; a control char cannot collide with a field id. */
+export const FILTER_ROOT_KEY = "\u0000root"
+
+/** Separator between path segments in the flat map keys. */
+const PATH_SEPARATOR = "\u0000"
+
+export function joinFilterPath(path: readonly string[]): string {
+  return path.join(PATH_SEPARATOR)
+}
+
+export function splitFilterPath(key: string): string[] {
+  return key === "" ? [] : key.split(PATH_SEPARATOR)
+}
+
+/** The joined key of a path's parent, or `FILTER_ROOT_KEY` at the top level. */
+export function parentFilterKey(path: readonly string[]): string {
+  return path.length <= 1 ? FILTER_ROOT_KEY : joinFilterPath(path.slice(0, -1))
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Signature                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * A content hash of the schema, used to skip a rebuild. Identity alone is
+ * useless: every block and example declares `fields` as an inline literal, so a
+ * memo keyed on the array misses on every parent render. Render props (`icon`,
+ * `renderValue`, a component-valued `editor`) are hashed by PRESENCE only,
+ * because inline JSX recreates them: swapping one's body keeps serving the
+ * previous field objects, so change a structural field or give `fields` a
+ * stable identity.
+ */
+export function computeFilterSchemaSignature<V, O>(
+  fields: readonly FilterField<V, O>[]
+): string {
+  const parts: string[] = []
+
+  const walk = (list: readonly FilterField<V, O>[], depth: number) => {
+    for (const field of list) {
+      parts.push(
+        depth +
+          ":" +
+          field.id +
+          "|" +
+          (field.label ?? "") +
+          "|" +
+          (field.type ?? "") +
+          "|" +
+          (field.defaultOperator ?? "") +
+          "|" +
+          (field.column ?? "") +
+          "|" +
+          (field.selectable ? "1" : "0") +
+          (field.disabled ? "1" : "0") +
+          (field.icon ? "1" : "0") +
+          (field.renderValue ? "1" : "0") +
+          (field.loadOptions ? "1" : "0") +
+          (field.resolveValues ? "1" : "0") +
+          "|" +
+          (typeof field.editor === "string"
+            ? field.editor
+            : field.editor
+              ? "fn"
+              : "") +
+          "|" +
+          (field.keywords?.join(",") ?? "") +
+          "|" +
+          (field.count ?? "") +
+          "|" +
+          // Options are part of the shape, and `exclusive` rides along: it
+          // decides what a pick DOES, so turning it on must force a rebuild.
+          (field.options
+            ? field.options
+                .map(
+                  (option) =>
+                    option.value +
+                    "~" +
+                    option.label +
+                    (option.exclusive ? "~x" : "")
+                )
+                .join(",")
+            : "") +
+          "|" +
+          (Array.isArray(field.operators)
+            ? field.operators.map((operator) => operator.value).join(",")
+            : field.operators
+              ? "fn"
+              : "")
+      )
+      if (field.fields?.length) walk(field.fields, depth + 1)
+    }
+  }
+
+  walk(fields, 0)
+  return parts.join("\n")
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Index                                   */
+/* -------------------------------------------------------------------------- */
+
+const EMPTY_INDEX: FilterIndex<never, never> = {
+  byPath: new Map(),
+  childrenOf: new Map(),
+  parentOf: new Map(),
+  all: [],
+  roots: [],
+  signature: "",
+}
+
+/**
+ * Normalizes a field schema into flat maps. When `previous`'s signature
+ * matches, the PREVIOUS OBJECT is returned: an equal-but-new one would leave
+ * every downstream memo missing exactly as often as before. Duplicate sibling
+ * ids are ignored after the first, as the cascader does for node values, and
+ * `findFilterSchemaIssues` reports them in development.
+ */
+export function buildFilterIndex<V = unknown, O = unknown>(
+  fields: readonly FilterField<V, O>[],
+  previous?: FilterIndex<V, O> | null,
+  /** A signature the caller already computed, to avoid walking twice. */
+  precomputedSignature?: string
+): FilterIndex<V, O> {
+  const signature = precomputedSignature ?? computeFilterSchemaSignature(fields)
+  if (previous && previous.signature === signature) return previous
+  if (fields.length === 0) {
+    return { ...(EMPTY_INDEX as unknown as FilterIndex<V, O>), signature }
+  }
+
+  const byPath = new Map<string, FilterField<V, O>>()
+  const childrenOf = new Map<string, FilterField<V, O>[]>()
+  const parentOf = new Map<string, string>()
+  const all: { field: FilterField<V, O>; path: string[] }[] = []
+  const roots: FilterField<V, O>[] = []
+
+  const walk = (
+    list: readonly FilterField<V, O>[],
+    parentPath: string[],
+    parentKey: string
+  ) => {
+    const accepted: FilterField<V, O>[] = []
+    const seen = new Set<string>()
+
+    for (const field of list) {
+      if (seen.has(field.id)) continue
+      seen.add(field.id)
+
+      const path = [...parentPath, field.id]
+      const key = joinFilterPath(path)
+      if (byPath.has(key)) continue
+
+      byPath.set(key, field)
+      parentOf.set(key, parentKey === FILTER_ROOT_KEY ? "" : parentKey)
+      all.push({ field, path })
+      accepted.push(field)
+
+      if (field.fields?.length) walk(field.fields, path, key)
+    }
+
+    childrenOf.set(parentKey, accepted)
+    if (parentKey === FILTER_ROOT_KEY) roots.push(...accepted)
+  }
+
+  walk(fields, [], FILTER_ROOT_KEY)
+
+  return { byPath, childrenOf, parentOf, all, roots, signature }
+}
+
+export function getFilterField<V, O>(
+  index: FilterIndex<V, O>,
+  path: readonly string[]
+): FilterField<V, O> | undefined {
+  return index.byPath.get(joinFilterPath(path))
+}
+
+/** The ancestor chain for a path, root first and the field itself last. */
+export function getFilterFieldChain<V, O>(
+  index: FilterIndex<V, O>,
+  path: readonly string[]
+): FilterField<V, O>[] {
+  const chain: FilterField<V, O>[] = []
+  for (let i = 1; i <= path.length; i++) {
+    const field = index.byPath.get(joinFilterPath(path.slice(0, i)))
+    if (!field) break
+    chain.push(field)
+  }
+  return chain
+}
+
+/** Child fields of a path. Pass an empty path for the root level. */
+export function getFilterChildren<V, O>(
+  index: FilterIndex<V, O>,
+  path: readonly string[]
+): FilterField<V, O>[] {
+  const key = path.length === 0 ? FILTER_ROOT_KEY : joinFilterPath(path)
+  return index.childrenOf.get(key) ?? []
+}
+
+export function isFilterBranch<V, O>(field: FilterField<V, O>): boolean {
+  return Boolean(field.fields?.length)
+}
+
+/**
+ * Whether a field DECLARES itself filterable on: leaves always, a branch only
+ * with `selectable`. The shipped pickers ignore it, see `isFilterFieldPickable`.
+ */
+export function isFilterFieldSelectable<V, O>(
+  field: FilterField<V, O>
+): boolean {
+  if (field.disabled) return false
+  return isFilterBranch(field) ? Boolean(field.selectable) : true
+}
+
+/**
+ * Whether the SHIPPED pickers may commit a field: leaves only. A row that both
+ * drills in and commits cannot disambiguate a click - its chevron and child
+ * count promise "opens a list", so the press that opened it also filtered on
+ * the parent and dismissed the picker. `selectable` stays honoured by
+ * `isFilterFieldSelectable` for a chrome that separates the two.
+ */
+export function isFilterFieldPickable<V, O>(field: FilterField<V, O>): boolean {
+  if (field.disabled) return false
+  return !isFilterBranch(field)
+}
+
+/** Trailing count for a branch row. */
+export function getFilterFieldCount<V, O>(field: FilterField<V, O>): number {
+  return field.count ?? field.fields?.length ?? 0
+}
+
+/** Renders a path as "Name > First" using the caller's separator. */
+export function formatFilterPath<V, O>(
+  index: FilterIndex<V, O>,
+  path: readonly string[],
+  separator: string
+): string {
+  const chain = getFilterFieldChain(index, path)
+  if (chain.length === 0) return path.join(separator)
+  return chain.map((field) => field.label).join(separator)
+}
+
+/** How a path is shortened; the cascader's own union, so the two cannot drift. */
+export type FilterPathCollapse = CascaderCollapse
+
+export type FilterPathSegment<V = unknown, O = unknown> =
+  | { type: "field"; field: FilterField<V, O> }
+  /** The run that was elided, kept so a host can surface it. */
+  | { type: "ellipsis"; hidden: FilterField<V, O>[] }
+
+/**
+ * Shortens an ancestor chain to at most `maxSegments` names, on the cascader's
+ * arithmetic so the chip's path and the builder's attribute cell cannot round
+ * differently. The adapter is POSITIONAL because a `FilterField`'s `id` is
+ * unique only among its siblings, so the index is the only key that survives a
+ * collapser keyed on `value`. Default `"none"`: no upgrade shortens a path.
+ */
+export function collapseFilterPath<V, O>(
+  chain: readonly FilterField<V, O>[],
+  options: { maxSegments?: number; collapse?: FilterPathCollapse } = {}
+): FilterPathSegment<V, O>[] {
+  const segments = collapseCascaderPath(
+    chain.map((field, index) => ({ value: String(index), label: field.label })),
+    { maxSegments: options.maxSegments, collapse: options.collapse ?? "none" }
+  )
+  return segments.map((segment) =>
+    segment.type === "node"
+      ? { type: "field" as const, field: chain[Number(segment.node.value)] }
+      : {
+          type: "ellipsis" as const,
+          hidden: segment.hidden.map((node) => chain[Number(node.value)]),
+        }
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                 Combinator                                 */
+/* -------------------------------------------------------------------------- */
+
+export type FilterCombinatorSlot = "where" | "toggle" | "echo"
+
+/**
+ * Which of the three forms the combinator slot before rule `index` takes. A
+ * group has exactly ONE combinator, so only one slot may be interactive: three
+ * editable "and"s down a column would imply three independent choices.
+ */
+export function filterCombinatorSlot(index: number): FilterCombinatorSlot {
+  if (index === 0) return "where"
+  return index === 1 ? "toggle" : "echo"
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Matching                                 */
+/* -------------------------------------------------------------------------- */
+
+/** `toLocaleLowerCase`, so Turkish dotted and dotless i fold as a reader expects. */
+export function foldFilterText(text: string): string {
+  return text.toLocaleLowerCase()
+}
+
+export function normalizeFilterQuery(query: string): string {
+  return foldFilterText(query.trim())
+}
+
+/** Whether a field matches a normalized query, by label or keywords. */
+export function matchesFilterQuery<V, O>(
+  field: FilterField<V, O>,
+  normalizedQuery: string
+): boolean {
+  if (normalizedQuery === "") return true
+  if (foldFilterText(field.label).includes(normalizedQuery)) return true
+  if (field.keywords) {
+    for (const keyword of field.keywords) {
+      if (foldFilterText(keyword).includes(normalizedQuery)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Filters one level, preserving input order. Unused here like
+ * `searchFilterDeep`: kept so a consumer's own picker need not re-implement the
+ * fold and the keyword matching.
+ */
+export function filterFilterLevel<V, O>(
+  fields: readonly FilterField<V, O>[],
+  normalizedQuery: string
+): FilterField<V, O>[] {
+  if (normalizedQuery === "") return fields as FilterField<V, O>[]
+  return fields.filter((field) => matchesFilterQuery(field, normalizedQuery))
+}
+
+/**
+ * Searches every SELECTABLE field at any depth, because a result the user
+ * cannot pick is a dead end. Unused here - the shipped picker is the cascader
+ * and delegates deep search to it - but it keeps a consumer's own picker from
+ * re-implementing the fold, the keyword matching and the selectable rule.
+ */
+export function searchFilterDeep<V, O>(
+  index: FilterIndex<V, O>,
+  normalizedQuery: string,
+  limit = 200
+): { field: FilterField<V, O>; path: string[] }[] {
+  if (normalizedQuery === "") return []
+  const results: { field: FilterField<V, O>; path: string[] }[] = []
+  for (const entry of index.all) {
+    if (results.length >= limit) break
+    if (!isFilterFieldSelectable(entry.field)) continue
+    if (matchesFilterQuery(entry.field, normalizedQuery)) results.push(entry)
+  }
+  return results
+}
+
+/** Filters an option list by a normalized query, by label or keywords. */
+export function filterFilterOptions<O>(
+  options: readonly FilterOption<O>[],
+  normalizedQuery: string
+): FilterOption<O>[] {
+  if (normalizedQuery === "") return options as FilterOption<O>[]
+  return options.filter((option) => {
+    if (foldFilterText(option.label).includes(normalizedQuery)) return true
+    if (option.keywords) {
+      for (const keyword of option.keywords) {
+        if (foldFilterText(keyword).includes(normalizedQuery)) return true
+      }
+    }
+    return false
+  })
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Exclusive options                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The None rule, as pure algebra over two selections: pick the `exclusive`
+ * option and it is the only pick, pick anything else and it goes. Written
+ * against the DELTA, not the result, which is what makes it total: an empty
+ * delta is a removal, including UNTICKING the exclusive row; an exclusive
+ * arrival is the whole answer; an ordinary arrival drops every exclusive value,
+ * restored ones included; both at once gives it to the LAST exclusive.
+ * `isExclusive` is a lookup, not an array, because a query hiding the None row
+ * while it stays SELECTED would answer "not exclusive" for the value the click
+ * must clear. Never applied on read - a saved view is the consumer's data - so
+ * it heals on the first ordinary pick, and only while `isExclusive` can ANSWER:
+ * a None row on a `loadOptions` field belongs in the static `options`.
+ */
+export function applyFilterExclusiveSelection(
+  next: readonly string[],
+  previous: readonly string[],
+  isExclusive: (value: string) => boolean
+): string[] {
+  const held = new Set(previous)
+  const added = next.filter((value) => !held.has(value))
+  if (added.length === 0) return next as string[]
+
+  let arrived: string | null = null
+  for (const value of added) {
+    if (isExclusive(value)) arrived = value
+  }
+  if (arrived !== null) return [arrived]
+
+  const kept = next.filter((value) => !isExclusive(value))
+  // The same array when nothing was exclusive, which is nearly every call: a
+  // fresh one would commit a new value on every toggle of an ordinary row.
+  return kept.length === next.length ? (next as string[]) : kept
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                     Ids                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Builds a deterministic id generator. `Date.now()` and `Math.random()`, as the
+ * old `createFilter` used, give the server and the client different ids for the
+ * same query, so any page shipping default filters hydrated mismatched.
+ */
+export function createFilterIdFactory(seed: string): () => string {
+  let counter = 0
+  return () => {
+    counter += 1
+    return `${seed}${counter}`
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              Development checks                            */
+/* -------------------------------------------------------------------------- */
+
+const warned = new Set<string>()
+
+/** Warns once per key. Never throws, and is a no-op in production. */
+export function warnFilterOnce(key: string, message: string): void {
+  if (process.env.NODE_ENV === "production") return
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(`[filters] ${message}`)
+}
+
+/** Clears the warn-once memory. For tests. */
+export function resetFilterWarnings(): void {
+  warned.clear()
+}
+
+export interface FilterSchemaIssues {
+  /** Ids that are empty, or that collide with a sibling. */
+  duplicatePaths: string[]
+  emptyIds: string[]
+  /** Branches that declare `selectable` but hold no children. */
+  emptyBranches: string[]
+  /** Fields whose `defaultOperator` is not in their operator list. */
+  unknownDefaultOperators: string[]
+}
+
+/** Reported, never thrown: a bad schema must degrade, not blank the page. */
+export function findFilterSchemaIssues<V, O>(
+  fields: readonly FilterField<V, O>[],
+  resolveOperators: (field: FilterField<V, O>) => FilterOperator[]
+): FilterSchemaIssues {
+  const duplicatePaths: string[] = []
+  const emptyIds: string[] = []
+  const emptyBranches: string[] = []
+  const unknownDefaultOperators: string[] = []
+
+  const walk = (list: readonly FilterField<V, O>[], parentPath: string[]) => {
+    const seen = new Set<string>()
+    for (const field of list) {
+      const label = [...parentPath, field.id].join(".")
+      if (!field.id) emptyIds.push(label)
+      else if (seen.has(field.id)) duplicatePaths.push(label)
+      seen.add(field.id)
+
+      if (field.selectable && field.fields && field.fields.length === 0) {
+        emptyBranches.push(label)
+      }
+
+      if (field.defaultOperator) {
+        const operators = resolveOperators(field)
+        if (!operators.some((op) => op.value === field.defaultOperator)) {
+          unknownDefaultOperators.push(`${label} -> ${field.defaultOperator}`)
+        }
+      }
+
+      if (field.fields?.length) walk(field.fields, [...parentPath, field.id])
+    }
+  }
+
+  walk(fields, [])
+  return { duplicatePaths, emptyIds, emptyBranches, unknownDefaultOperators }
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-operators.tsx b/apps/web/src/components/reui/filters/filters-operators.tsx
new file mode 100644
index 0000000..1c4ba1c
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-operators.tsx
@@ -0,0 +1,227 @@
+import type {
+  FilterField,
+  FilterOperator,
+  FilterValueType,
+} from "@/components/reui/filters/filters-types"
+
+/**
+ * Every operator label, keyed by value. Split from `FilterLabels`: operator
+ * wording is reworded per domain, chrome copy is translated once per app.
+ */
+export type FilterOperatorLabels = Record<string, string>
+
+export const DEFAULT_FILTER_OPERATOR_LABELS: FilterOperatorLabels = {
+  contains: "contains",
+  not_contains: "does not contain",
+  starts_with: "starts with",
+  ends_with: "ends with",
+  is: "is",
+  is_not: "is not",
+  is_any_of: "is any of",
+  is_none_of: "is none of",
+  has_any_of: "has any of",
+  has_all_of: "has all of",
+  has_none_of: "has none of",
+  eq: "equals",
+  neq: "does not equal",
+  gt: "is greater than",
+  gte: "is greater than or equal to",
+  lt: "is less than",
+  lte: "is less than or equal to",
+  between: "is between",
+  not_between: "is not between",
+  is_before: "is before",
+  is_after: "is after",
+  is_on_or_before: "is on or before",
+  is_on_or_after: "is on or after",
+  empty: "is empty",
+  not_empty: "is not empty",
+}
+
+/**
+ * Operator catalog per value type: value, arity, inverse, labels resolved at
+ * build time so translating one operator never restates the catalog. `arity`
+ * of "none" drops the chip's value segment and the wizard's value step, in a
+ * consumer's own `operators` array as much as in this catalog.
+ */
+const CATALOG: Record<
+  FilterValueType,
+  { value: string; arity?: FilterOperator["arity"]; inverse?: string }[]
+> = {
+  text: [
+    { value: "contains", inverse: "not_contains" },
+    { value: "not_contains", inverse: "contains" },
+    { value: "starts_with" },
+    { value: "ends_with" },
+    { value: "is", inverse: "is_not" },
+    { value: "is_not", inverse: "is" },
+    { value: "empty", arity: "none", inverse: "not_empty" },
+    { value: "not_empty", arity: "none", inverse: "empty" },
+  ],
+  number: [
+    { value: "eq", inverse: "neq" },
+    { value: "neq", inverse: "eq" },
+    { value: "gt", inverse: "lte" },
+    { value: "gte", inverse: "lt" },
+    { value: "lt", inverse: "gte" },
+    { value: "lte", inverse: "gt" },
+    { value: "between", arity: "range", inverse: "not_between" },
+    { value: "not_between", arity: "range", inverse: "between" },
+    { value: "empty", arity: "none", inverse: "not_empty" },
+    { value: "not_empty", arity: "none", inverse: "empty" },
+  ],
+  range: [
+    { value: "between", arity: "range", inverse: "not_between" },
+    { value: "not_between", arity: "range", inverse: "between" },
+    { value: "empty", arity: "none", inverse: "not_empty" },
+    { value: "not_empty", arity: "none", inverse: "empty" },
+  ],
+  select: [
+    { value: "is", inverse: "is_not" },
+    { value: "is_not", inverse: "is" },
+    { value: "is_any_of", arity: "many", inverse: "is_none_of" },
+    { value: "is_none_of", arity: "many", inverse: "is_any_of" },
+    { value: "empty", arity: "none", inverse: "not_empty" },
+    { value: "not_empty", arity: "none", inverse: "empty" },
+  ],
+  multiselect: [
+    { value: "has_any_of", arity: "many", inverse: "has_none_of" },
+    { value: "has_all_of", arity: "many" },
+    { value: "has_none_of", arity: "many", inverse: "has_any_of" },
+    { value: "empty", arity: "none", inverse: "not_empty" },
+    { value: "not_empty", arity: "none", inverse: "empty" },
+  ],
+  boolean: [
+    { value: "is", inverse: "is_not" },
+    { value: "is_not", inverse: "is" },
+    { value: "empty", arity: "none", inverse: "not_empty" },
+    { value: "not_empty", arity: "none", inverse: "empty" },
+  ],
+}
+
+export const DEFAULT_FILTER_VALUE_TYPE: FilterValueType = "text"
+
+/**
+ * Builds the operator catalog for one set of labels. Callers memoize on the
+ * label object: the old primitive built its equivalent inside
+ * `getOperatorsForField`, keyed on a `values` array that was fresh after every
+ * filter update, so every miss reallocated four arrays of 27 objects each.
+ */
+export function createFilterOperators(
+  labels: FilterOperatorLabels
+): Record<FilterValueType, FilterOperator[]> {
+  const built = {} as Record<FilterValueType, FilterOperator[]>
+  for (const type of Object.keys(CATALOG) as FilterValueType[]) {
+    built[type] = CATALOG[type].map((entry) => ({
+      value: entry.value,
+      label: labels[entry.value] ?? entry.value,
+      arity: entry.arity ?? "one",
+      inverse: entry.inverse,
+    }))
+  }
+  return built
+}
+
+export const DEFAULT_FILTER_OPERATORS: Record<
+  FilterValueType,
+  FilterOperator[]
+> = createFilterOperators(DEFAULT_FILTER_OPERATOR_LABELS)
+
+/**
+ * The operators for a field: its own `operators` wins, array or function,
+ * otherwise the catalog entry for its `type`. No implicit select to multiselect
+ * promotion by selection count: that changed the list as the user picked.
+ */
+export function resolveFilterOperators<V, O>(
+  field: FilterField<V, O>,
+  catalog: Record<FilterValueType, FilterOperator[]> = DEFAULT_FILTER_OPERATORS
+): FilterOperator[] {
+  if (typeof field.operators === "function") return field.operators(field)
+  if (field.operators) return field.operators
+  return catalog[field.type ?? DEFAULT_FILTER_VALUE_TYPE] ?? catalog.text
+}
+
+export function visibleFilterOperators(
+  operators: readonly FilterOperator[]
+): FilterOperator[] {
+  return operators.filter((operator) => !operator.hidden)
+}
+
+export function getFilterOperator(
+  operators: readonly FilterOperator[],
+  value: string | null | undefined
+): FilterOperator | undefined {
+  if (!value) return undefined
+  return operators.find((operator) => operator.value === value)
+}
+
+export function getFilterArity(
+  operator: FilterOperator | undefined
+): FilterOperator["arity"] {
+  return operator?.arity ?? "one"
+}
+
+export function operatorTakesValue(
+  operator: FilterOperator | undefined
+): boolean {
+  return getFilterArity(operator) !== "none"
+}
+
+/**
+ * The operator a field starts with: `defaultOperator` when it names one the
+ * field offers, otherwise the first visible operator. Falling back rather than
+ * trusting the schema keeps the rule out of a state its own list cannot show.
+ */
+export function getDefaultFilterOperator<V, O>(
+  field: FilterField<V, O>,
+  operators: readonly FilterOperator[]
+): string | null {
+  if (field.defaultOperator) {
+    const named = getFilterOperator(operators, field.defaultOperator)
+    if (named) return named.value
+  }
+  const visible = visibleFilterOperators(operators)
+  return visible[0]?.value ?? operators[0]?.value ?? null
+}
+
+/**
+ * Negating a rule: swap to the declared `inverse` so the chip reads "does not
+ * contain", else toggle `negated` so Negate still works without an inverse.
+ */
+export function negateFilterOperator(
+  operator: FilterOperator | undefined,
+  operators: readonly FilterOperator[],
+  negated: boolean | undefined
+): { operator: string | null; negated: boolean } {
+  if (operator?.inverse) {
+    const inverse = getFilterOperator(operators, operator.inverse)
+    if (inverse) return { operator: inverse.value, negated: Boolean(negated) }
+  }
+  return { operator: operator?.value ?? null, negated: !negated }
+}
+
+/**
+ * Reshapes a value when arity changes: widening "is" to "is any of" keeps what
+ * the user picked, narrowing keeps the first of them, `"none"` always drops it.
+ */
+export function coerceFilterValue(
+  value: unknown,
+  from: FilterOperator | undefined,
+  to: FilterOperator | undefined
+): unknown {
+  const nextArity = getFilterArity(to)
+  if (nextArity === "none") return undefined
+  if (value === undefined || value === null) return value
+
+  const previousArity = getFilterArity(from)
+  if (previousArity === nextArity) return value
+
+  const asArray = Array.isArray(value) ? value : [value]
+
+  if (nextArity === "many") return asArray
+  if (nextArity === "one") return asArray[0]
+  if (nextArity === "range") {
+    return [asArray[0], asArray[1]] as [unknown, unknown]
+  }
+  return value
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-query.tsx b/apps/web/src/components/reui/filters/filters-query.tsx
new file mode 100644
index 0000000..3cd8e4a
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-query.tsx
@@ -0,0 +1,701 @@
+import type {
+  FilterCombinator,
+  FilterGroupNode,
+  FilterIssue,
+  FilterNode,
+  FilterOperator,
+  FilterQuery,
+  FilterRule,
+} from "@/components/reui/filters/filters-types"
+
+export function isFilterRule<V>(node: FilterNode<V>): node is FilterRule<V> {
+  return node.type === "rule"
+}
+
+export function isFilterGroup<V>(
+  node: FilterNode<V>
+): node is FilterGroupNode<V> {
+  return node.type === "group"
+}
+
+/**
+ * A rule. `id` is passed in, never generated here: a non-deterministic value in
+ * a pure function broke hydration. Callers use `createFilterIdFactory`.
+ */
+export function createFilterRule<V = unknown>(input: {
+  id: string
+  path: string[]
+  operator: string
+  value?: V
+  negated?: boolean
+}): FilterRule<V> {
+  const rule: FilterRule<V> = {
+    id: input.id,
+    type: "rule",
+    path: input.path,
+    operator: input.operator,
+    value: input.value,
+  }
+  if (input.negated) rule.negated = true
+  return rule
+}
+
+export function createFilterGroup<V = unknown>(input: {
+  id: string
+  combinator?: FilterCombinator
+  rules?: FilterNode<V>[]
+}): FilterGroupNode<V> {
+  return {
+    id: input.id,
+    type: "group",
+    combinator: input.combinator ?? "and",
+    rules: input.rules ?? [],
+  }
+}
+
+/** An empty query. The root is always a group, never a bare array. */
+export function createFilterQuery<V = unknown>(
+  rules: FilterNode<V>[] = [],
+  combinator: FilterCombinator = "and",
+  id = "root"
+): FilterQuery<V> {
+  return { id, type: "group", combinator, rules }
+}
+
+/** Every rule in the tree, depth first. Groups are flattened away. */
+export function flattenFilterRules<V>(query: FilterQuery<V>): FilterRule<V>[] {
+  const out: FilterRule<V>[] = []
+  const walk = (node: FilterNode<V>) => {
+    if (isFilterRule(node)) {
+      out.push(node)
+      return
+    }
+    for (const child of node.rules) walk(child)
+  }
+  walk(query)
+  return out
+}
+
+/**
+ * One rule, flattened for a predicate. `values` is always an array even though
+ * `FilterRule.value` is singular, so no caller re-derives arity.
+ */
+export interface FilterCondition {
+  /** Full field path, `["name", "first"]`. */
+  path: string[]
+  /** First path segment, for the common flat-schema case. */
+  field: string
+  operator: string
+  /** `[]` for an operator that takes no value. */
+  values: unknown[]
+  negated: boolean
+}
+
+/**
+ * Whether a rule says anything yet. A rule exists as soon as an attribute is
+ * picked, so `operator: ""` is a real state: `flattenFilterConditions` leaves
+ * it out, `countFilterRules` still counts it, and `collectFilterIssues` reports
+ * it as `missing-operator`.
+ */
+export function isFilterRuleComplete<V>(rule: FilterRule<V>): boolean {
+  return rule.operator !== ""
+}
+
+/**
+ * Flattens a query to conditions. Lossy: safe only when the query is flat or
+ * every group shares the root's combinator. Read `query.combinator` and walk
+ * the tree yourself for anything else. Incomplete rules are left out.
+ */
+export function flattenFilterConditions<V>(
+  query: FilterQuery<V>
+): FilterCondition[] {
+  return flattenFilterRules(query)
+    .filter(isFilterRuleComplete)
+    .map((rule) => ({
+      path: rule.path,
+      field: rule.path[0],
+      operator: rule.operator,
+      values:
+        rule.value === undefined || rule.value === null
+          ? []
+          : Array.isArray(rule.value)
+            ? (rule.value as unknown[])
+            : [rule.value],
+      negated: Boolean(rule.negated),
+    }))
+}
+
+/** How many rules the query holds, at any depth. */
+export function countFilterRules<V>(query: FilterQuery<V>): number {
+  let count = 0
+  const walk = (node: FilterNode<V>) => {
+    if (isFilterRule(node)) {
+      count += 1
+      return
+    }
+    for (const child of node.rules) walk(child)
+  }
+  walk(query)
+  return count
+}
+
+/** Whether the query would match everything. */
+export function isFilterQueryEmpty<V>(query: FilterQuery<V>): boolean {
+  return countFilterRules(query) === 0
+}
+
+/**
+ * How an arity is answered for one rule. The caller resolves it, since arity
+ * lives on the FIELD's operator list. `null` is a rule it cannot judge.
+ */
+export type FilterArityResolver<V> = (
+  rule: FilterRule<V>
+) => FilterOperator["arity"] | null
+
+/** Runs a field's own `validate`. A resolver like `arityOf`: no schema here. */
+export type FilterValidateResolver<V> = (
+  rule: FilterRule<V>
+) => string | null | undefined | false
+
+/** A value slot the user has not filled in. `false` and `0` are values. */
+function isBlankFilterValue(value: unknown): boolean {
+  return value === undefined || value === null || value === ""
+}
+
+/**
+ * Compares two range bounds, or gives up. Numbers, dates and ISO strings only:
+ * inventing an order for a range of colour names would flag a correct filter as
+ * reversed. `Date.parse` must parse BOTH strings before they are compared.
+ */
+function compareFilterBounds(from: unknown, to: unknown): number | null {
+  if (typeof from === "number" && typeof to === "number") {
+    return Number.isNaN(from) || Number.isNaN(to) ? null : from - to
+  }
+  if (from instanceof Date && to instanceof Date) {
+    const a = from.getTime()
+    const b = to.getTime()
+    return Number.isNaN(a) || Number.isNaN(b) ? null : a - b
+  }
+  if (typeof from === "string" && typeof to === "string") {
+    const a = Date.parse(from)
+    const b = Date.parse(to)
+    return Number.isNaN(a) || Number.isNaN(b) ? null : a - b
+  }
+  return null
+}
+
+/**
+ * Every reason a query cannot be run as written, in document order: the five
+ * ways this builder can hold a condition that SILENTLY does the wrong thing.
+ * `missing-operator` and `empty-group` carry no predicate and are dropped by
+ * `flattenFilterConditions`; `missing-value` reaches the consumer with a
+ * `values` array that is empty or all blank, which most backends read as
+ * "match nothing"; `incomplete-range` is the same for a range and often
+ * arrives with one bound FILLED, so an emptiness check will not catch it;
+ * `reversed-range` is legal and matches nothing anywhere. A group of exactly
+ * ONE node is NOT an issue (it is what "Convert to group" produces), and the
+ * root is exempt from `empty-group`.
+ */
+export function collectFilterIssues<V>(
+  query: FilterQuery<V>,
+  arityOf: FilterArityResolver<V>,
+  validateOf?: FilterValidateResolver<V>
+): FilterIssue[] {
+  const issues: FilterIssue[] = []
+
+  const visit = (group: FilterGroupNode<V>, isRoot: boolean) => {
+    if (!isRoot && group.rules.length === 0) {
+      issues.push({
+        nodeId: group.id,
+        column: "group",
+        reason: "empty-group",
+      })
+    }
+
+    for (const child of group.rules) {
+      if (isFilterGroup(child)) {
+        visit(child, false)
+        continue
+      }
+      // Asked FIRST: `null` means the caller cannot judge this rule at all, so
+      // even `missing-operator` would point at a control that is not on screen.
+      const arity = arityOf(child)
+      if (arity === null) continue
+
+      if (!isFilterRuleComplete(child)) {
+        issues.push({
+          nodeId: child.id,
+          column: "operator",
+          reason: "missing-operator",
+        })
+        continue
+      }
+
+      if (arity === "none") continue
+
+      const values =
+        child.value === undefined || child.value === null
+          ? []
+          : Array.isArray(child.value)
+            ? (child.value as unknown[])
+            : [child.value]
+
+      if (arity === "range") {
+        if (
+          values.length < 2 ||
+          isBlankFilterValue(values[0]) ||
+          isBlankFilterValue(values[1])
+        ) {
+          issues.push({
+            nodeId: child.id,
+            column: "value",
+            reason: "incomplete-range",
+          })
+          continue
+        }
+        const order = compareFilterBounds(values[0], values[1])
+        if (order !== null && order > 0) {
+          issues.push({
+            nodeId: child.id,
+            column: "value",
+            reason: "reversed-range",
+          })
+        }
+        continue
+      }
+
+      // `many` and `one` collapse here: both are unsatisfied by an empty list,
+      // and `one` normalises to a single-element list above.
+      if (values.length === 0 || values.every(isBlankFilterValue)) {
+        issues.push({
+          nodeId: child.id,
+          column: "value",
+          reason: "missing-value",
+        })
+        continue
+      }
+
+      // LAST, and only on a rule the primitive is already happy with: stacking
+      // a second message on one cell breaks the one-issue-per-node shape.
+      const message = validateOf?.(child)
+      if (message) {
+        issues.push({
+          nodeId: child.id,
+          column: "value",
+          reason: "custom",
+          message,
+        })
+      }
+    }
+  }
+
+  visit(query, true)
+  return issues
+}
+
+/** Locates a node and its parent. Returns null when the id is unknown. */
+export function findFilterNode<V>(
+  query: FilterQuery<V>,
+  id: string
+): {
+  node: FilterNode<V>
+  parent: FilterGroupNode<V> | null
+  index: number
+} | null {
+  if (query.id === id) return { node: query, parent: null, index: -1 }
+
+  const walk = (
+    group: FilterGroupNode<V>
+  ): {
+    node: FilterNode<V>
+    parent: FilterGroupNode<V>
+    index: number
+  } | null => {
+    for (let i = 0; i < group.rules.length; i++) {
+      const child = group.rules[i]
+      if (child.id === id) return { node: child, parent: group, index: i }
+      if (isFilterGroup(child)) {
+        const found = walk(child)
+        if (found) return found
+      }
+    }
+    return null
+  }
+
+  return walk(query)
+}
+
+/** The rule with this id, or null when the id names a group or is unknown. */
+export function findFilterRule<V>(
+  query: FilterQuery<V>,
+  id: string
+): FilterRule<V> | null {
+  const found = findFilterNode(query, id)
+  if (!found || !isFilterRule(found.node)) return null
+  return found.node
+}
+
+/**
+ * Rebuilds the tree, applying `transform` to the group holding `id`. An
+ * unchanged subtree comes back BY IDENTITY, so `React.memo` holds for all but
+ * the moved chip. Tests assert it with `toBe`. `removeFilterNode` and
+ * `detachFilterNode` drop children rather than replace a group, so they
+ * hand-roll the same identity-preserving walk.
+ */
+function rewriteGroup<V>(
+  group: FilterGroupNode<V>,
+  shouldRewrite: (group: FilterGroupNode<V>) => boolean,
+  transform: (group: FilterGroupNode<V>) => FilterGroupNode<V>
+): FilterGroupNode<V> {
+  if (shouldRewrite(group)) return transform(group)
+
+  let changed = false
+  const rules = group.rules.map((child) => {
+    if (!isFilterGroup(child)) return child
+    const next = rewriteGroup(child, shouldRewrite, transform)
+    if (next !== child) changed = true
+    return next
+  })
+
+  return changed ? { ...group, rules } : group
+}
+
+/** Replaces a rule's fields. Unknown ids return the query unchanged. */
+export function updateFilterRule<V>(
+  query: FilterQuery<V>,
+  id: string,
+  updates: Partial<Omit<FilterRule<V>, "id" | "type">>
+): FilterQuery<V> {
+  return rewriteGroup(
+    query,
+    (group) =>
+      group.rules.some((child) => child.id === id && isFilterRule(child)),
+    (group) => ({
+      ...group,
+      rules: group.rules.map((child) =>
+        child.id === id && isFilterRule(child)
+          ? { ...child, ...updates }
+          : child
+      ),
+    })
+  ) as FilterQuery<V>
+}
+
+/**
+ * Removes a node, plus any group it empties, all the way up (not the root): an
+ * empty group is invisible in the flat UI yet still compiles to parentheses.
+ */
+export function removeFilterNode<V>(
+  query: FilterQuery<V>,
+  id: string
+): FilterQuery<V> {
+  const prune = (group: FilterGroupNode<V>): FilterGroupNode<V> => {
+    let changed = false
+    const rules: FilterNode<V>[] = []
+
+    for (const child of group.rules) {
+      if (child.id === id) {
+        changed = true
+        continue
+      }
+      if (isFilterGroup(child)) {
+        const next = prune(child)
+        if (next !== child) changed = true
+        if (next.rules.length === 0) continue
+        rules.push(next)
+        continue
+      }
+      rules.push(child)
+    }
+
+    return changed ? { ...group, rules } : group
+  }
+
+  return prune(query) as FilterQuery<V>
+}
+
+/** Appends a node to a group, defaulting to the root. */
+export function insertFilterNode<V>(
+  query: FilterQuery<V>,
+  node: FilterNode<V>,
+  parentId?: string,
+  index?: number
+): FilterQuery<V> {
+  const targetId = parentId ?? query.id
+  return rewriteGroup(
+    query,
+    (group) => group.id === targetId,
+    (group) => {
+      const rules = [...group.rules]
+      const at =
+        index === undefined
+          ? rules.length
+          : Math.max(0, Math.min(index, rules.length))
+      rules.splice(at, 0, node)
+      return { ...group, rules }
+    }
+  ) as FilterQuery<V>
+}
+
+/**
+ * A deep copy under fresh ids, the whole way down: children keeping their old
+ * ids would give two live nodes one id, and every lookup here is by id.
+ */
+function cloneFilterNode<V>(
+  node: FilterNode<V>,
+  nextId: () => string
+): FilterNode<V> {
+  return isFilterRule(node)
+    ? { ...node, id: nextId() }
+    : {
+        ...node,
+        id: nextId(),
+        rules: node.rules.map((child) => cloneFilterNode(child, nextId)),
+      }
+}
+
+/** Copies a node in beside the original. */
+export function duplicateFilterNode<V>(
+  query: FilterQuery<V>,
+  id: string,
+  nextId: () => string
+): FilterQuery<V> {
+  const found = findFilterNode(query, id)
+  if (!found || !found.parent) return query
+
+  return insertFilterNode(
+    query,
+    cloneFilterNode(found.node, nextId),
+    found.parent.id,
+    found.index + 1
+  )
+}
+
+export function setFilterCombinator<V>(
+  query: FilterQuery<V>,
+  groupId: string,
+  combinator: FilterCombinator
+): FilterQuery<V> {
+  return rewriteGroup(
+    query,
+    (group) => group.id === groupId,
+    (group) =>
+      group.combinator === combinator ? group : { ...group, combinator }
+  ) as FilterQuery<V>
+}
+
+export function toggleFilterCombinator<V>(
+  query: FilterQuery<V>,
+  groupId: string
+): FilterQuery<V> {
+  const found = findFilterNode(query, groupId)
+  if (!found || !isFilterGroup(found.node)) return query
+  return setFilterCombinator(
+    query,
+    groupId,
+    found.node.combinator === "and" ? "or" : "and"
+  )
+}
+
+/** Moves a node within its own group. Out of range moves are no-ops. */
+export function moveFilterNode<V>(
+  query: FilterQuery<V>,
+  id: string,
+  delta: number
+): FilterQuery<V> {
+  const found = findFilterNode(query, id)
+  if (!found || !found.parent) return query
+
+  const from = found.index
+  const to = from + delta
+  if (to < 0 || to >= found.parent.rules.length || delta === 0) return query
+
+  return rewriteGroup(
+    query,
+    (group) => group.id === found.parent!.id,
+    (group) => {
+      const rules = [...group.rules]
+      const [moved] = rules.splice(from, 1)
+      rules.splice(to, 0, moved)
+      return { ...group, rules }
+    }
+  ) as FilterQuery<V>
+}
+
+/** Whether `id` names `node` itself or anything beneath it. */
+function containsFilterNode<V>(node: FilterNode<V>, id: string): boolean {
+  if (node.id === id) return true
+  if (isFilterRule(node)) return false
+  return node.rules.some((child) => containsFilterNode(child, id))
+}
+
+/**
+ * Removes a node WITHOUT pruning what it empties. A move cannot reuse
+ * `removeFilterNode`: it would delete the group the drop is aimed at.
+ */
+function detachFilterNode<V>(
+  group: FilterGroupNode<V>,
+  id: string
+): FilterGroupNode<V> {
+  let changed = false
+  const rules: FilterNode<V>[] = []
+
+  for (const child of group.rules) {
+    if (child.id === id) {
+      changed = true
+      continue
+    }
+    if (isFilterGroup(child)) {
+      const next = detachFilterNode(child, id)
+      if (next !== child) changed = true
+      rules.push(next)
+      continue
+    }
+    rules.push(child)
+  }
+
+  return changed ? { ...group, rules } : group
+}
+
+/**
+ * Moves a node into another group, at an index: the cross-parent form of
+ * `moveFilterNode`, which only reorders within one parent. Refuses a group into
+ * itself or a descendant, which would leave a cycle, and refuses the root.
+ */
+export function moveFilterNodeTo<V>(
+  query: FilterQuery<V>,
+  id: string,
+  parentId: string,
+  index: number
+): FilterQuery<V> {
+  const found = findFilterNode(query, id)
+  if (!found || !found.parent) return query
+  if (containsFilterNode(found.node, parentId)) return query
+
+  const destination = findFilterNode(query, parentId)
+  if (!destination || !isFilterGroup(destination.node)) return query
+
+  // Within one parent the node's own slot disappears when it detaches, so
+  // indexes after it shift down by one: without this a drag down is a no-op.
+  const sameParent = found.parent.id === parentId
+  const target = sameParent && found.index < index ? index - 1 : index
+  if (sameParent && target === found.index) return query
+
+  return insertFilterNode(
+    detachFilterNode(query, id),
+    found.node,
+    parentId,
+    target
+  )
+}
+
+/**
+ * Copies a node into a group at a position: the Alt path of the drag layer. Not
+ * `duplicateFilterNode` then `moveFilterNodeTo`, which emits two queries for one
+ * gesture and needs the id the first step minted and never returned. The clone
+ * is taken BEFORE the insert, so copying a group into itself stays finite.
+ */
+export function copyFilterNodeTo<V>(
+  query: FilterQuery<V>,
+  id: string,
+  parentId: string,
+  index: number,
+  nextId: () => string
+): FilterQuery<V> {
+  const found = findFilterNode(query, id)
+  if (!found || !found.parent) return query
+
+  const destination = findFilterNode(query, parentId)
+  if (!destination || !isFilterGroup(destination.node)) return query
+
+  return insertFilterNode(
+    query,
+    cloneFilterNode(found.node, nextId),
+    parentId,
+    index
+  )
+}
+
+/**
+ * Wraps a node in a new group: the "Wrap in condition group" action, and the
+ * keyboard path to nesting for a user who cannot drag.
+ */
+export function wrapFilterNodeInGroup<V>(
+  query: FilterQuery<V>,
+  id: string,
+  groupId: string,
+  combinator: FilterCombinator = "or"
+): FilterQuery<V> {
+  const found = findFilterNode(query, id)
+  if (!found || !found.parent) return query
+
+  return rewriteGroup(
+    query,
+    (group) => group.id === found.parent!.id,
+    (group) => ({
+      ...group,
+      rules: group.rules.map((child) =>
+        child.id === id
+          ? createFilterGroup<V>({ id: groupId, combinator, rules: [child] })
+          : child
+      ),
+    })
+  ) as FilterQuery<V>
+}
+
+/**
+ * Dissolves a group into its parent, splicing its rules in at the position the
+ * group held so wrap and unwrap round-trip. The root, a rule id and an unknown
+ * id each return the query unchanged.
+ */
+export function unwrapFilterGroup<V>(
+  query: FilterQuery<V>,
+  groupId: string
+): FilterQuery<V> {
+  if (query.id === groupId) return query
+  const found = findFilterNode(query, groupId)
+  if (!found || !found.parent || !isFilterGroup(found.node)) return query
+
+  const dissolved = found.node
+  return rewriteGroup(
+    query,
+    (group) => group.id === found.parent!.id,
+    (group) => {
+      const rules = [...group.rules]
+      rules.splice(found.index, 1, ...dissolved.rules)
+      return { ...group, rules }
+    }
+  ) as FilterQuery<V>
+}
+
+/** Empties the query, keeping the root's identity fields. */
+export function clearFilterQuery<V>(query: FilterQuery<V>): FilterQuery<V> {
+  return query.rules.length === 0 ? query : { ...query, rules: [] }
+}
+
+/**
+ * Drops empty groups and collapses a group whose only child is a group. Not
+ * automatic: a user mid-edit may hold an almost-empty group. Call on persist.
+ */
+export function pruneFilterQuery<V>(query: FilterQuery<V>): FilterQuery<V> {
+  const prune = (node: FilterNode<V>): FilterNode<V> | null => {
+    if (isFilterRule(node)) return node
+
+    const rules: FilterNode<V>[] = []
+    for (const child of node.rules) {
+      const next = prune(child)
+      if (next) rules.push(next)
+    }
+
+    if (rules.length === 0) return null
+    if (rules.length === 1 && isFilterGroup(rules[0])) return rules[0]
+    return { ...node, rules }
+  }
+
+  const rules: FilterNode<V>[] = []
+  for (const child of query.rules) {
+    const next = prune(child)
+    if (next) rules.push(next)
+  }
+  return { ...query, rules }
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters-types.tsx b/apps/web/src/components/reui/filters/filters-types.tsx
new file mode 100644
index 0000000..2322ea6
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters-types.tsx
@@ -0,0 +1,566 @@
+import type * as React from "react"
+
+/* -------------------------------------------------------------------------- */
+/*                                 Query tree                                 */
+/* -------------------------------------------------------------------------- */
+
+export type FilterCombinator = "and" | "or"
+
+/**
+ * One condition. `path` maps one to one onto the cascader's `details.path`, so
+ * a field selection commits untranslated. `value` is SINGULAR and the
+ * operator's `arity` decides its shape: `"many"` holds an array, `"range"` a
+ * tuple, `"none"` undefined.
+ */
+export interface FilterRule<V = unknown> {
+  id: string
+  type: "rule"
+  /** Field path, root first. `["name", "first"]` for a nested attribute. */
+  path: string[]
+  operator: string
+  value: V | undefined
+  /** Flips the meaning in place. Set by Negate when there is no `inverse`. */
+  negated?: boolean
+}
+
+/** Rules under one combinator; nests, so nesting is never a later break. */
+export interface FilterGroupNode<V = unknown> {
+  id: string
+  type: "group"
+  combinator: FilterCombinator
+  rules: FilterNode<V>[]
+}
+
+export type FilterNode<V = unknown> = FilterRule<V> | FilterGroupNode<V>
+
+/** A whole query. Always a group, so flat and nested are one code path. */
+export type FilterQuery<V = unknown> = FilterGroupNode<V>
+
+export type FilterChangeReason =
+  | "add"
+  | "update"
+  | "remove"
+  | "duplicate"
+  | "negate"
+  | "reorder"
+  | "combinator"
+  | "clear"
+
+/** Second argument to `onQueryChange`, so nobody has to diff two trees. */
+export interface FilterChangeDetails<V = unknown, O = unknown> {
+  reason: FilterChangeReason
+  /** The rule that changed, or null for whole-query changes like `clear`. */
+  rule: FilterRule<V> | null
+  /** The field the rule points at, resolved. Null when the path is unknown. */
+  field: FilterField<V, O> | null
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Operators                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * How many values an operator takes. Answers "does this need a value editor"
+ * for every operator, a consumer's own included, in place of the hardcoded
+ * `operator === "empty"` checks it replaced.
+ */
+export type FilterOperatorArity = "none" | "one" | "many" | "range"
+
+export interface FilterOperator {
+  value: string
+  label: string
+  /** Defaults to `"one"`. */
+  arity?: FilterOperatorArity
+  /** The opposite operator. Negate flips to it, else sets `rule.negated`. */
+  inverse?: string
+  /** Hidden from the operator list but still valid in a restored query. */
+  hidden?: boolean
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Fields                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Which built-in editor a field uses by DEFAULT: `editor` overrides it, and an
+ * operator may override both. No date type on purpose - every product wants a
+ * different date control, and a built-in one would add a calendar dependency to
+ * every install, so a date ships as an `editor`.
+ */
+export type FilterValueType =
+  | "text"
+  | "number"
+  | "range"
+  | "select"
+  | "multiselect"
+  | "boolean"
+
+export interface FilterOption<O = unknown> {
+  value: string
+  label: string
+  icon?: React.ReactNode
+  description?: string
+  keywords?: string[]
+  disabled?: boolean
+  /**
+   * The row that means NONE OF THE ABOVE: Unassigned, No label, No due date.
+   * Picking it clears every other pick and picking anything else clears it, and
+   * it is drawn apart under a rule of its own, because a list that wipes a
+   * selection must not look like one that does not; hide that line with
+   * `"[&_[data-slot=filter-menu-divider]]:hidden"`. Applied under EVERY
+   * operator, negative ones included. The value must be RESOLVABLE, since the
+   * rule runs through the option service: an option that exists only in an
+   * unfetched `loadOptions` page is invisible to it.
+   */
+  exclusive?: boolean
+  /** Arbitrary payload, carried untouched through every render callback. */
+  data?: O
+}
+
+export interface FilterLoadContext {
+  /** Aborted when the query changes, the editor closes, or a load supersedes. */
+  signal: AbortSignal
+  cursor?: string
+}
+
+/** Result of `loadOptions`, or a bare array. Shape-locked to the cascader. */
+export interface FilterLoadResult<O = unknown> {
+  items: FilterOption<O>[]
+  nextCursor?: string
+  /** Defaults to whether `nextCursor` was supplied. */
+  hasMore?: boolean
+}
+
+/** A field, or a branch. A group is a field with `fields`, not `selectable`. */
+export interface FilterField<V = unknown, O = unknown> {
+  /** Stable id. Unique among its siblings; the full path must be unique. */
+  id: string
+  label: string
+  icon?: React.ReactNode
+  description?: string
+  keywords?: string[]
+  /** Trailing count. Defaults to known children; set it when they are lazy. */
+  count?: number
+  fields?: FilterField<V, O>[]
+  /** Whether a BRANCH is itself filterable. Leaves always are. */
+  selectable?: boolean
+  disabled?: boolean
+
+  type?: FilterValueType
+  options?: FilterOption<O>[]
+  /** Async options, paged via `cursor`. Any `options` also seed the cache. */
+  loadOptions?: (
+    query: string,
+    context: FilterLoadContext
+  ) => FilterOption<O>[] | Promise<FilterOption<O>[] | FilterLoadResult<O>>
+  /** Resolves stored values the loader never returned, for restored chips. */
+  resolveValues?: (
+    values: string[]
+  ) => FilterOption<O>[] | Promise<FilterOption<O>[]>
+
+  /** Operators for this field. Falls back to the catalog for its `type`. */
+  operators?:
+    | FilterOperator[]
+    | ((field: FilterField<V, O>) => FilterOperator[])
+  /**
+   * The operator this field FALLS BACK to, not a way to preselect one. Both
+   * create paths deliberately start a rule on `operator: ""` so the condition
+   * menu opens with nothing chosen, so this is read when an existing rule
+   * changes field, and it is the value `FilterFieldPicker` hands to `onSelect`.
+   * Ignored, with a dev warning, when it names an operator the field does not
+   * offer; the first visible operator wins instead.
+   */
+  defaultOperator?: string
+
+  /** Overrides the editor chosen from `type`. See `FilterEditorProps`. */
+  editor?: FilterEditorRef<V, O>
+  renderValue?: (context: FilterValueDisplayContext<V, O>) => React.ReactNode
+  /** The value as PLAIN TEXT for a11y; the default is `String(value)`. */
+  valueText?: (context: FilterValueDisplayContext<V, O>) => string
+
+  /** Placeholder for the value editor's input, or an option list's search. */
+  placeholder?: string
+  /** SHOWS the search box (default true). Off keeps it, hidden: it owns focus. */
+  searchable?: boolean
+  /**
+   * Whether an option-backed editor STACKS the picks at the top of its list.
+   * Off by default, because a short closed list is read as a whole and lifting
+   * a row out of a memorised order costs more than it buys. The partition is
+   * taken LIVE unless `sortSelected: "snapshot"`, so ticking a row moves the
+   * rows below it and the highlight is carried across by VALUE. Exclusive
+   * options never join the stack; they are grouped by ROLE.
+   */
+  pinSelected?: boolean
+  /**
+   * How an option list is ordered INSIDE each group, plus WHEN the partition is
+   * taken under `pinSelected`. With pinning off there is no partition, so
+   * `"snapshot"` is the same thing as `"none"`.
+   *
+   * - `"none"` (default) keeps declaration order. Not alphabetical, because
+   *   option order is usually semantic (To do, In progress, Done).
+   * - `"label"` sorts with `localeCompare`, so "Ålesund" files next to
+   *   "Alesund" rather than after "Zurich".
+   * - `"snapshot"` keeps declaration order too, and freezes the partition as
+   *   the menu opened it: a steady pointer target where the other two re-pin
+   *   live.
+   */
+  sortSelected?: "none" | "label" | "snapshot"
+  /**
+   * This field's own validity check. Return a MESSAGE to mark the value cell
+   * invalid, or `null` / `undefined` / `false` when the value is fine. A string
+   * rather than a schema object keeps the primitive library-agnostic.
+   *
+   * ORDER MATTERS: the built-in checks run first and this runs only when they
+   * pass, so a validator never re-answers "is there a value at all". Not called
+   * for a valueless operator, nor for a rule whose field the schema no longer
+   * has, and shown only once the user has committed a value to that rule.
+   */
+  validate?: (
+    context: FilterValidateContext<V, O>
+  ) => string | null | undefined | false
+  /**
+   * Reaches the value editor's PANEL. Merged last through tailwind-merge, so a
+   * `w-*` here beats the default rather than losing to it on source order.
+   *
+   * HEIGHT IS A VARIABLE, NOT A UTILITY: a `max-h-*` here bounds the PANEL and
+   * does nothing to the list inside it, which owns its own `max-height`. Write
+   * `--cascader-max-height: 28rem` as an arbitrary property instead; the cap is
+   * the SMALLER of that and the space the popup has.
+   */
+  className?: string
+
+  /** The storage column when it differs from the UI path. Never read here. */
+  column?: string
+  data?: unknown
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Editors                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Where an editor renders. The SAME component serves both: `"create"` is the
+ * wizard step, which has Back and advances on commit, `"amend"` the
+ * chip-anchored popover, which offers Discard instead.
+ */
+export type FilterEditorHost = "create" | "amend"
+
+export interface FilterOptionsState<O = unknown> {
+  items: FilterOption<O>[]
+  loading: boolean
+  error: boolean
+  hasMore: boolean
+  /** Current search text. Debounced before it reaches `loadOptions`. */
+  query: string
+  setQuery: (query: string) => void
+  loadMore: () => void
+  retry: () => void
+  /** Resolves a stored value to its option, from cache when possible. */
+  resolve: (value: string) => FilterOption<O> | undefined
+}
+
+export interface FilterCommitOptions {
+  /** Dismiss the host after writing. Defaults to true. */
+  close?: boolean
+}
+
+export interface FilterEditorProps<V = unknown, O = unknown> {
+  field: FilterField<V, O>
+  operator: FilterOperator
+  /** The DRAFT value. An editor edits a draft; the host commits it. */
+  value: V | undefined
+  onValueChange: (value: V | undefined) => void
+  host: FilterEditorHost
+  /**
+   * Spread onto whichever element should take focus, so no editor reaches for
+   * `setTimeout`. A CALLBACK ref at `HTMLElement` is the one shape assignable
+   * to every element's own ref prop, so it spreads onto an input, a slider or a
+   * button without a cast.
+   */
+  autoFocusProps: {
+    ref: React.RefCallback<HTMLElement>
+    autoFocus: boolean
+  }
+  /** Accept the draft. `{ close: false }` writes through without dismissing. */
+  commit: (value?: V, options?: FilterCommitOptions) => void
+  cancel: () => void
+  /** Step back. Only meaningful when `host === "create"`. */
+  back: () => void
+  options: FilterOptionsState<O>
+  labels: FilterLabels
+}
+
+export type FilterEditor<V = unknown, O = unknown> = React.ComponentType<
+  FilterEditorProps<V, O>
+>
+
+/**
+ * An editor with its generics erased, for the registry. `unknown` rather than
+ * `never`: props are contravariant, so a `FilterEditor<never, never>` registry
+ * accepts nothing at all. The single widening cast happens where it renders.
+ */
+export type AnyFilterEditor = React.ComponentType<
+  FilterEditorProps<unknown, unknown>
+>
+
+export type FilterEditorRegistry = Record<string, AnyFilterEditor>
+
+/**
+ * A registered editor's name, or a component. The `any` arm lets a CONCRETE
+ * editor sit on an unknown-typed field without a cast: props are contravariant,
+ * so `FilterEditor<DateValue>` is not a `FilterEditor<unknown>`. The widening
+ * happens once, inside `resolveFilterEditor`.
+ */
+export type FilterEditorRef<V = unknown, O = unknown> =
+  | string
+  | FilterEditor<V, O>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  | FilterEditor<any, any>
+
+/** Context for a custom builder empty state. Its actions ARE the footer's. */
+export interface FilterEmptyStateContext {
+  labels: FilterLabels
+  /** The bar is locked. A custom state should not offer an action here. */
+  readOnly: boolean
+  /** Which box the builder is in, for a state that wants to be denser inline. */
+  mode: "popover" | "inline"
+  /** Appends a condition and opens its attribute picker. */
+  addFilter: () => void
+  addGroup: () => void
+}
+
+export interface FilterValueDisplayContext<V = unknown, O = unknown> {
+  value: V | undefined
+  /** `value` normalised to an array, so callbacks never re-derive it. */
+  values: unknown[]
+  field: FilterField<V, O>
+  operator: FilterOperator
+  /** Options already resolved for `value`, when the field is option-backed. */
+  options: FilterOption<O>[]
+  labels: FilterLabels
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Index                                    */
+/* -------------------------------------------------------------------------- */
+
+/** Normalized schema, keyed by SIGNATURE: call sites inline the array. */
+export interface FilterIndex<V = unknown, O = unknown> {
+  /** Every field by its joined path, `"name.first"`. */
+  byPath: Map<string, FilterField<V, O>>
+  /** Child fields by parent path. Root fields are keyed by `FILTER_ROOT_KEY`. */
+  childrenOf: Map<string, FilterField<V, O>[]>
+  /** Parent path by path. Empty string for a root field. */
+  parentOf: Map<string, string>
+  /** Every field in stable, depth-first order. Deep search walks it, and the
+   * builder seeds a new row from the FIRST pickable entry, so order is load
+   * bearing, not incidental. */
+  all: { field: FilterField<V, O>; path: string[] }[]
+  /** Top level fields, in input order. */
+  roots: FilterField<V, O>[]
+  /** Content hash; equal schemas share one, so a rebuild reuses the index. */
+  signature: string
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Draft                                   */
+/* -------------------------------------------------------------------------- */
+
+export type FilterDraftStep = "field" | "operator" | "value"
+
+/**
+ * The in-flight filter. `cascaderPath` is kept SEPARATE from `path`: `path` is
+ * what the user chose, `cascaderPath` is where they were browsing when they
+ * chose it, and Back has to return there. Deriving it from `path` breaks the
+ * moment a deep search jumps across the tree.
+ */
+export interface FilterDraft<V = unknown> {
+  step: FilterDraftStep
+  /** `"ready"` = complete: the host writes it into the query and closes. The
+   * pure reducer decides that, not a click handler. */
+  status: "editing" | "ready"
+  /** Set when amending an existing rule, null when creating a new one. */
+  ruleId: string | null
+  /** The chosen field path. Empty until the field step commits. */
+  path: string[]
+  cascaderPath: string[]
+  operator: string | null
+  value: V | undefined
+  query: string
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Labels                                   */
+/* -------------------------------------------------------------------------- */
+
+/** Every user facing string. `stepAnnouncement` alone is headless-only. */
+export interface FilterLabels {
+  addFilter: string
+  advancedFilter: string
+  /** The line above the builder's rows, "In this view, show records". */
+  showRecords: string
+  /** Empty-state title. The HINT below is withheld from a read-only bar. */
+  builderEmpty: string
+  builderEmptyHint: string
+  /** Appends a condition to the root group, from the builder's footer. */
+  addCondition: string
+  addConditionGroup: string
+  /** A group's own add button: the only keyboard route into a nested group. It
+   * NAMES a button that shows `addCondition`, so a translation must contain
+   * that string, which is what WCAG Label in Name asks for. */
+  addToGroup: string
+  removeGroup: string
+  wrapInGroup: string
+  /** Dissolves a group into its parent. The inverse of `wrapInGroup`. */
+  ungroup: string
+  /** Moves a condition to the root group. The keyboard path to that drag. */
+  moveToTopLevel: string
+  /** Groups have no names, so they are numbered in document order, one-based. */
+  moveToGroup: (position: number) => string
+  /** Accessible name of a row's or a group's drag handle. */
+  reorder: string
+  /** Description on the drag handle, teaching the Alt+Arrow keyboard model. */
+  reorderHint: string
+  groupAll: string
+  groupAny: string
+  groupPlaceholder: string
+  /** Names a builder row. Depth is in it: indentation is invisible to AT. */
+  rowLabel: (condition: string, depth: number) => string
+  groupLabel: (description: string, depth: number) => string
+  groupAnnouncement: (added: boolean) => string
+  /** Alt+Arrow is otherwise silent. The total says whether this is the end. */
+  reorderAnnouncement: (
+    label: string,
+    position: number,
+    total: number
+  ) => string
+  /** A cross-PARENT move; a plain reorder announcement cannot be told apart.
+   * `destination` is the group's own headline, or the bar's label at the top
+   * level. */
+  moveAnnouncement: (
+    label: string,
+    destination: string,
+    position: number,
+    total: number
+  ) => string
+  clearAll: string
+  /** Names a group's menu; distinct from `chipMenu`, which is per-rule. */
+  groupMenu: string
+  searchFields: string
+  searchOperators: string
+  searchOptions: string
+  back: string
+  clear: string
+  apply: string
+  discard: string
+  empty: string
+  loading: string
+  loadingMore: string
+  loadMore: string
+  error: string
+  retry: string
+  /** Leading word before the first chip, where a combinator would otherwise go. */
+  where: string
+  and: string
+  or: string
+  /** Accessible name of the combinator toggle between two chips. */
+  combinator: string
+  /** Builder combinator toggle. English "and" wants 58.72px of a 64px track,
+   * so the name must CONTAIN the word: truncated, the pill shows "a...". */
+  combinatorLabel: (word: string) => string
+  duplicate: string
+  negate: string
+  /** Chip kebab's route into the builder. Needs `onConvertToAdvanced`. */
+  convertToAdvanced: string
+  remove: string
+  /** Names a chip's menu button. The builder's row menu reads the same key. */
+  chipMenu: (fieldLabel: string) => string
+  filtersLabel: string
+  filterLabel: (condition: string) => string
+  /** Prose, not ARIA: `aria-readonly` is invalid on toolbar, group and button. */
+  readOnly: string
+  /** Joins ancestors in a nested field path, "Name > First", for the names
+   * `formatFilterPath` builds. The chip draws a decorative chevron instead. */
+  pathSeparator: string
+  valuePlaceholder: string
+  /** Empty word for an OPTION value; `placeholder` is the search prompt. */
+  selectPlaceholder: string
+  /** Spoken for an empty value: "contains enter text..." is not a name. */
+  noValue: string
+  /** Shown in the operator segment before a condition has been chosen. */
+  selectCondition: string
+  /** Appended to a chip with no condition, matching the dashed outline. */
+  incomplete: string
+  /** Appended to a branch row's accessible name in the field picker. */
+  branchAffordance: string
+  /** A FRAGMENT, appended after a comma to an exclusive row's accessible name.
+   * Warns before the press; `exclusiveAnnouncement` is the receipt after. */
+  exclusiveHint: string
+  /** The clearing moves nothing on screen, so it is otherwise silent. */
+  exclusiveAnnouncement: (label: string, cleared: number) => string
+  itemCount: (count: number) => string
+  fieldsLabel: string
+  /** Live-region text after a query narrows an option list or the picker. */
+  resultsAnnouncement: (count: number) => string
+  /** Accessible name of an option menu's footer (Load more, Retry). */
+  actionsLabel: string
+  /** For a CONSUMER-composed wizard; the shipped flow announces counts. */
+  stepAnnouncement: (step: FilterDraftStep, label: string) => string
+  countAnnouncement: (count: number) => string
+  valueCount: (count: number) => string
+  /** Spells out the list behind the `valueCount` summary, and contains it. */
+  valueDetail: (summary: string, values: string[]) => string
+  valueRange: (from: string, to: string) => string
+  rangeFrom: (fieldLabel: string) => string
+  rangeTo: (fieldLabel: string) => string
+  rangeSeparator: string
+  /** Rendered for a `negated` rule, wrapping the operator label. */
+  negated: (operatorLabel: string) => string
+  /** Guidance ("Choose a condition"), not diagnosis: shown three ways over. */
+  issueOperator: string
+  issueValue: string
+  issueRange: string
+  issueRangeOrder: string
+  issueEmptyGroup: string
+  /** The roll-up, and the name of the button that jumps to the first issue. */
+  issueSummary: (count: number) => string
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                 Validation                                 */
+/* -------------------------------------------------------------------------- */
+
+/** Why a node cannot run as written. `collectFilterIssues` produces these. */
+export type FilterIssueReason =
+  | "missing-operator"
+  | "missing-value"
+  | "incomplete-range"
+  | "reversed-range"
+  | "empty-group"
+  /** The one reason whose message is the validator's, not `FilterLabels`. */
+  | "custom"
+
+export interface FilterIssue {
+  nodeId: string
+  /** WHICH cell to mark. Two reasons share the value cell; groups have none. */
+  column: "operator" | "value" | "group"
+  reason: FilterIssueReason
+  /** Set only for `reason: "custom"`; the rest look up `FilterLabels`. */
+  message?: string
+}
+
+/**
+ * What a field's `validate` is handed. Mirrors `FilterValueDisplayContext`.
+ * SYNCHRONOUS: issues are collected in a pure memo pass, so a check that has to
+ * hit a server belongs in the consumer's own submit path.
+ */
+export interface FilterValidateContext<V = unknown, O = unknown> {
+  value: V | undefined
+  values: unknown[]
+  field: FilterField<V, O>
+  operator: FilterOperator
+  /** How many values this operator takes, already resolved. */
+  arity: FilterOperatorArity
+  rule: FilterRule<V>
+  labels: FilterLabels
+}
\ No newline at end of file
diff --git a/apps/web/src/components/reui/filters/filters.tsx b/apps/web/src/components/reui/filters/filters.tsx
new file mode 100644
index 0000000..04df6a8
--- /dev/null
+++ b/apps/web/src/components/reui/filters/filters.tsx
@@ -0,0 +1,1228 @@
+import * as React from "react"
+import { FiltersAdvanced } from "@/components/reui/filters/filters-advanced"
+import { FiltersBuilder } from "@/components/reui/filters/filters-builder"
+import { FilterChip } from "@/components/reui/filters/filters-chip"
+import {
+  createFilterFocusStore,
+  createFilterResolutionStore,
+  createFilterRowStateStore,
+  FilterActionsContext,
+  filterControlSizes,
+  FilterFocusContext,
+  filterReadOnlyProps,
+  FilterRenderContext,
+  FilterRowStateProvider,
+  FilterStateContext,
+  isFilterLocked,
+  useFilterActions,
+  useFilterFocusStore,
+  useFilterState,
+  type FilterActionsContextValue,
+} from "@/components/reui/filters/filters-context"
+import {
+  filterDraftReducer,
+  isFilterDraftCommittable,
+  type FilterDraftAction,
+} from "@/components/reui/filters/filters-draft"
+import {
+  DEFAULT_FILTER_EDITORS,
+  resolveFilterEditor,
+  type FilterEditorRegistry,
+} from "@/components/reui/filters/filters-editors"
+import { resolveFilterLabels } from "@/components/reui/filters/filters-i18n"
+import {
+  buildFilterIndex,
+  computeFilterSchemaSignature,
+  createFilterIdFactory,
+  findFilterSchemaIssues,
+  formatFilterPath,
+  getFilterField,
+  warnFilterOnce,
+  type FilterPathCollapse,
+} from "@/components/reui/filters/filters-lib"
+import {
+  createFilterOperators,
+  DEFAULT_FILTER_OPERATOR_LABELS,
+  DEFAULT_FILTER_OPERATORS,
+  getFilterOperator,
+  negateFilterOperator,
+  operatorTakesValue,
+  resolveFilterOperators,
+  type FilterOperatorLabels,
+} from "@/components/reui/filters/filters-operators"
+import {
+  clearFilterQuery,
+  copyFilterNodeTo,
+  countFilterRules,
+  createFilterGroup,
+  createFilterQuery,
+  createFilterRule,
+  duplicateFilterNode,
+  findFilterNode,
+  findFilterRule,
+  flattenFilterRules,
+  insertFilterNode,
+  isFilterRule,
+  moveFilterNode,
+  moveFilterNodeTo,
+  removeFilterNode,
+  setFilterCombinator,
+  toggleFilterCombinator,
+  unwrapFilterGroup,
+  updateFilterRule,
+  wrapFilterNodeInGroup,
+} from "@/components/reui/filters/filters-query"
+import type {
+  FilterChangeDetails,
+  FilterCombinator,
+  FilterDraft,
+  FilterDraftStep,
+  FilterEditor,
+  FilterEmptyStateContext,
+  FilterField,
+  FilterLabels,
+  FilterQuery,
+  FilterRule,
+  FilterValueDisplayContext,
+} from "@/components/reui/filters/filters-types"
+import { cva } from "class-variance-authority"
+
+import { cn } from "@authportal/ui/lib/utils"
+import { Button } from "@authportal/ui/components/button"
+
+/* -------------------------------------------------------------------------- */
+/*                                  Variants                                  */
+/* -------------------------------------------------------------------------- */
+
+const filtersBarVariants = cva("flex flex-wrap items-center", {
+  variants: {
+    // The rungs `FILTER_CONTROL_SIZES` holds, fed the RESOLVED rung at both
+    // call sites, which is what keeps the two ladders in step: a cva default
+    // only applies to a value nobody passed, so a raw `"lg"` reaching here
+    // would leave the bar with no gap at all.
+    size: {
+      sm: "gap-1.5",
+      default: "gap-2",
+    },
+  },
+  defaultVariants: { size: "default" },
+})
+
+/* -------------------------------------------------------------------------- */
+/*                                 Controllable                               */
+/* -------------------------------------------------------------------------- */
+
+function useControllableQuery<V, O>(
+  controlled: FilterQuery<V> | undefined,
+  uncontrolledDefault: FilterQuery<V> | undefined,
+  onChange:
+    | ((query: FilterQuery<V>, details: FilterChangeDetails<V, O>) => void)
+    | undefined
+) {
+  const isControlled = controlled !== undefined
+  const [internal, setInternal] = React.useState<FilterQuery<V>>(
+    () => uncontrolledDefault ?? createFilterQuery<V>()
+  )
+
+  const query = isControlled ? controlled : internal
+  const queryRef = React.useRef(query)
+  React.useEffect(() => {
+    queryRef.current = query
+  })
+
+  const setQuery = React.useCallback(
+    (next: FilterQuery<V>, details: FilterChangeDetails<V, O>) => {
+      if (next === queryRef.current) return
+      queryRef.current = next
+      if (!isControlled) setInternal(next)
+      onChange?.(next, details)
+    },
+    [isControlled, onChange]
+  )
+
+  return { query, queryRef, setQuery }
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Root                                    */
+/* -------------------------------------------------------------------------- */
+
+export interface FiltersProps<V = unknown, O = unknown> {
+  /** The field schema. Nested via each field's own `fields`. */
+  fields: FilterField<V, O>[]
+
+  query?: FilterQuery<V>
+  defaultQuery?: FilterQuery<V>
+  onQueryChange?: (
+    query: FilterQuery<V>,
+    details: FilterChangeDetails<V, O>
+  ) => void
+
+  labels?: Partial<FilterLabels>
+  /** Operator wording, overridden independently of the chrome copy. */
+  operatorLabels?: FilterOperatorLabels
+  /** Extra or replacement value editors, resolved by a field's `editor` name. */
+  editors?: FilterEditorRegistry
+
+  /**
+   * Which chrome draws the query. `"basic"` is the flat chip row, joined by an
+   * implicit AND and drawing no combinator, because a chip row has nowhere to
+   * put a parenthesis, and it draws a nested rule at any depth as a flat chip.
+   */
+  variant?: "basic" | "advanced"
+  /** Where the advanced builder lives. `"inline"` renders the panel in place. */
+  advancedMode?: "popover" | "inline"
+  /**
+   * Where the panel sits against its trigger. Stating it settles a twin split:
+   * on overflow Base UI flips edges, Radix only shifts along the axis.
+   */
+  advancedAlign?: "start" | "center" | "end"
+  /**
+   * Whether the advanced builder's rows can be REORDERED. Off by default: a
+   * move changes nothing about what the query MEANS, and costs a grip on every
+   * row plus a gesture a touch screen starts by accident. On, drag and
+   * Alt+Arrow move any row but the lone root.
+   */
+  reorderable?: boolean
+
+  /**
+   * The density of the whole bar, chips included. TWO RUNGS and no `lg`,
+   * resolved through `filterControlSizes` to whatever the ACTIVE STYLE calls
+   * that rung (nova 7/8, sera 9/10, mira 6/7, maia and luma 8/9, lyra and rhea
+   * 7/8, vega 8/9). Chips need no `ButtonGroup` variant: `items-stretch` gives
+   * the pill the height of its one definite-height child, the kebab.
+   */
+  size?: "sm" | "default"
+  disabled?: boolean
+  readOnly?: boolean
+
+  /**
+   * ONE VETO POINT for every change the BAR makes to the query, and only those.
+   * Return `false` to refuse; anything else commits, and `details.reason` names
+   * the action. One hook and not fourteen because every write goes through
+   * `emit`: the Delete key, Alt+Arrow and a drag alike. It can only refuse, and
+   * it sits BEHIND the lock, so a locked bar never asks it. Returning a
+   * REPLACEMENT tree was rejected: the announcement is already computed from
+   * the proposed tree, so the bar would say one thing and commit another.
+   */
+  onBeforeQueryChange?: (
+    query: FilterQuery<V>,
+    details: FilterChangeDetails<V, O>
+  ) => boolean | void
+
+  /**
+   * Offers "Convert to advanced filter" in every chip's kebab; its presence IS
+   * the switch, since `variant` belongs to the consumer. Not drawn in advanced.
+   */
+  onConvertToAdvanced?: () => void
+
+  /**
+   * Classes for the dropdown MENUS and the field PICKER panel, one prop each
+   * rather than one per mount point. Merged after the default, so `w-*` wins.
+   */
+  menuClassName?: string
+  fieldPickerClassName?: string
+
+  /**
+   * How a NESTED attribute path is shortened when too deep to read. `"none"` is
+   * the default, so an upgrade changes nothing under a consumer; the collapser
+   * is the cascader's, and the full path survives as the accessible NAME.
+   */
+  pathCollapse?: FilterPathCollapse
+  /**
+   * How many names survive the collapse, the elided run not counted. Inert
+   * while `pathCollapse` is `"none"`. Three is the cascader's own default.
+   */
+  maxPathSegments?: number
+
+  /** Replaces the default Add filter button. */
+  trigger?: React.ReactNode
+  /** Renders a Clear button once the query holds anything. */
+  showClear?: boolean
+
+  renderValue?: (context: FilterValueDisplayContext<V, O>) => React.ReactNode
+  renderChip?: (rule: FilterRule<V>) => React.ReactNode
+  /**
+   * Replaces the advanced builder's empty state, which exists at all because a
+   * builder with no rows is a footer floating in blank space. `null` for none.
+   */
+  renderEmpty?: (context: FilterEmptyStateContext) => React.ReactNode
+
+  className?: string
+  children?: React.ReactNode
+}
+
+export function Filters<V = unknown, O = unknown>({
+  fields,
+  query: controlledQuery,
+  defaultQuery,
+  onQueryChange,
+  labels: labelsProp,
+  operatorLabels: operatorLabelsProp,
+  editors: editorsProp,
+  variant = "basic",
+  advancedMode = "popover",
+  advancedAlign = "start",
+  reorderable = false,
+  size = "default",
+  disabled = false,
+  readOnly = false,
+  onBeforeQueryChange,
+  onConvertToAdvanced,
+  menuClassName,
+  fieldPickerClassName,
+  pathCollapse = "none",
+  maxPathSegments = 3,
+  trigger,
+  showClear = false,
+  renderValue,
+  renderChip,
+  renderEmpty,
+  className,
+  children,
+}: FiltersProps<V, O>) {
+  const { query, queryRef, setQuery } = useControllableQuery<V, O>(
+    controlledQuery,
+    defaultQuery,
+    onQueryChange
+  )
+
+  const [draft, dispatchDraftRaw] = React.useReducer(
+    filterDraftReducer<V>,
+    null as FilterDraft<V> | null
+  )
+  // Text AND a counter: `aria-live` fires on a DOM mutation and React writes
+  // nothing when the string is already there, so a repeat was silent. Measured
+  // with a MutationObserver: "Group added" three times, one mutation.
+  const [announced, setAnnounced] = React.useState({ seq: 0, text: "" })
+  const announcement = announced.text
+  const setAnnouncement = React.useCallback((text: string) => {
+    setAnnounced((prev) => ({ seq: prev.seq + 1, text }))
+  }, [])
+
+  // Seeded from useId: ids from Date.now() plus Math.random() broke hydration.
+  const idSeed = React.useId()
+  const nextId = React.useMemo(
+    () => createFilterIdFactory(`${idSeed}f`),
+    [idSeed]
+  )
+
+  const focusStore = React.useMemo(() => createFilterFocusStore(), [])
+  const rowStateStore = React.useMemo(() => createFilterRowStateStore(), [])
+  // One per root: the value-to-label store every `useFilterOptions` shares.
+  const resolutionStore = React.useMemo(() => createFilterResolutionStore(), [])
+
+  /* -------------------------------- derived ------------------------------- */
+
+  // `fields` is an inline literal at every real call site, so the CHEAP walk
+  // runs every render and the EXPENSIVE index memoizes on its result. Not a
+  // ref caching the previous index: writing a ref during render is the
+  // impurity this rewrite removed, and it misbehaves under StrictMode.
+  const signature = computeFilterSchemaSignature(fields)
+  const index = React.useMemo(
+    () => buildFilterIndex<V, O>(fields, null, signature),
+    // Not `fields`: its identity changes every render at every real call site.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [signature]
+  )
+
+  const labels = React.useMemo(
+    () => resolveFilterLabels(labelsProp),
+    [labelsProp]
+  )
+
+  const operatorCatalog = React.useMemo(() => {
+    if (!operatorLabelsProp) return DEFAULT_FILTER_OPERATORS
+    return createFilterOperators({
+      ...DEFAULT_FILTER_OPERATOR_LABELS,
+      ...operatorLabelsProp,
+    })
+  }, [operatorLabelsProp])
+
+  const editors = React.useMemo(
+    () => ({ ...DEFAULT_FILTER_EDITORS, ...editorsProp }),
+    [editorsProp]
+  )
+
+  const resolveOperators = React.useCallback(
+    (field: FilterField<V, O>) =>
+      resolveFilterOperators(field, operatorCatalog),
+    [operatorCatalog]
+  )
+
+  const ruleCount = React.useMemo(() => countFilterRules(query), [query])
+
+  /* --------------------------- latest-props ref --------------------------- */
+
+  const latest = React.useRef({
+    index,
+    labels,
+    operatorCatalog,
+    resolveOperators,
+    draft,
+    nextId,
+    setQuery,
+    queryRef,
+    disabled,
+    readOnly,
+    onBeforeQueryChange,
+  })
+  React.useEffect(() => {
+    latest.current = {
+      index,
+      labels,
+      operatorCatalog,
+      resolveOperators,
+      draft,
+      nextId,
+      setQuery,
+      queryRef,
+      disabled,
+      readOnly,
+      onBeforeQueryChange,
+    }
+  })
+
+  /* -------------------------------- actions ------------------------------- */
+
+  // Every mutator below reads state through `latest`, so no keystroke rebuilds
+  // one. The lock flags are the ONE exception, for the reason on `locked`.
+
+  /**
+   * THE MUTATION BOUNDARY, asked here and not at the nine buttons, because the
+   * routes into a query are not only buttons. It needs BOTH the closure and
+   * the ref: `latest` is written in a passive effect and effects run
+   * child-first, so a consumer effect in the commit that turns `readOnly` on
+   * runs BEFORE the ref learns of it, while the ref is what a stale handler
+   * reads afterwards.
+   */
+  const locked = React.useCallback(
+    () => disabled || readOnly || isFilterLocked(latest.current),
+    [disabled, readOnly]
+  )
+
+  // Reports whether the write LANDED: `onBeforeQueryChange` is discoverable
+  // only here, and a vetoed remove that still announced a count would lie.
+  const emit = React.useCallback(
+    (
+      next: FilterQuery<V>,
+      reason: FilterChangeDetails<V, O>["reason"],
+      rule: FilterRule<V> | null
+    ): boolean => {
+      // The backstop, redundant with each mutator's own early return, and
+      // FIRST, so the consumer hook cannot approve what the lock refused.
+      if (locked()) return false
+      const field = rule
+        ? (getFilterField(latest.current.index, rule.path) ?? null)
+        : null
+      const details: FilterChangeDetails<V, O> = { reason, rule, field }
+      // Strictly `false`, so a handler that forgets to return is not a veto.
+      if (latest.current.onBeforeQueryChange?.(next, details) === false) {
+        return false
+      }
+      latest.current.setQuery(next, details)
+      return true
+    },
+    [locked]
+  )
+
+  /**
+   * Drops the roving tab stop when the node holding it no longer exists: a cell
+   * claims it when the store names it, and the "row one takes it" fallback
+   * fires only when the store is EMPTY, so a deleted id left twenty cells at
+   * `tabindex="-1"` with focus on the BODY. Keyed on the committed `query`, so
+   * a consumer's Reset or saved-view load is repaired too: add a condition,
+   * press Reset, and 25 cells stayed untabbable in both twins.
+   */
+  React.useEffect(() => {
+    const { id } = focusStore.getSnapshot()
+    if (!id || findFilterNode(query, id)) return
+    focusStore.set({ id: null, segment: null, autoOpen: false })
+  }, [query, focusStore])
+
+  const addRule = React.useCallback(
+    (rule: FilterRule<V>, parentId?: string) => {
+      if (locked()) return
+      const next = insertFilterNode(
+        latest.current.queryRef.current,
+        rule,
+        parentId
+      )
+      if (!emit(next, "add", rule)) return
+      setAnnouncement(
+        latest.current.labels.countAnnouncement(countFilterRules(next))
+      )
+    },
+    [emit, locked, setAnnouncement]
+  )
+
+  const addGroup = React.useCallback(
+    (parentId?: string, combinator: FilterCombinator = "or") => {
+      // Before `nextId`, so a LOCKED bar cannot drift the SSR-seeded sequence.
+      if (locked()) return ""
+      const id = latest.current.nextId()
+      // `or` by default: `a AND (b AND c)` is just `a AND b AND c`.
+      const next = insertFilterNode(
+        latest.current.queryRef.current,
+        createFilterGroup<V>({ id, combinator }),
+        parentId
+      )
+      // `""` on a veto: every caller moves focus onto the id it gets back, and
+      // focusing a group that was never created strands the tab stop. The id
+      // is already burnt, deliberately: a veto is a client-time decision the
+      // server never took part in.
+      if (!emit(next, "add", null)) return ""
+      setAnnouncement(latest.current.labels.groupAnnouncement(true))
+      return id
+    },
+    [emit, locked, setAnnouncement]
+  )
+
+  const updateRule = React.useCallback(
+    (id: string, updates: Partial<Omit<FilterRule<V>, "id" | "type">>) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const next = updateFilterRule(current, id, updates)
+      if (next === current) return
+      // THE VALUE, not the field or the operator: picking an attribute leaves
+      // the value empty, so arming there reddens the flow the primitive itself
+      // walks a user through. A field re-pick sends `value: undefined` in the
+      // SAME patch, so `path` and not the presence of `value` tells the two
+      // apart. Clearing a typed value still arms it: no `path` in that patch.
+      if ("path" in updates) rowStateStore.unmark(id)
+      else if ("value" in updates) rowStateStore.mark(id)
+      emit(next, "update", findFilterRule(next, id))
+    },
+    [emit, locked, rowStateStore]
+  )
+
+  const removeNode = React.useCallback(
+    (id: string) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const removed = findFilterRule(current, id)
+      const next = removeFilterNode(current, id)
+      if (next === current) return
+      if (!emit(next, "remove", removed)) return
+      // A rule removal reports the COUNT; a group has no rule to report and
+      // takes an unknown number of conditions with it, so it says so instead.
+      setAnnouncement(
+        removed
+          ? latest.current.labels.countAnnouncement(countFilterRules(next))
+          : latest.current.labels.groupAnnouncement(false)
+      )
+    },
+    [emit, locked, setAnnouncement]
+  )
+
+  const duplicateNode = React.useCallback(
+    (id: string) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const next = duplicateFilterNode(current, id, latest.current.nextId)
+      if (next === current) return
+      if (!emit(next, "duplicate", findFilterRule(current, id))) return
+      // The count, not "duplicated": a GROUP adds an unknown number of rows.
+      setAnnouncement(
+        latest.current.labels.countAnnouncement(countFilterRules(next))
+      )
+    },
+    [emit, locked, setAnnouncement]
+  )
+
+  const negateRule = React.useCallback(
+    (id: string) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const rule = findFilterRule(current, id)
+      if (!rule) return
+      const field = getFilterField(latest.current.index, rule.path)
+      if (!field) return
+      const operators = latest.current.resolveOperators(field)
+      const flipped = negateFilterOperator(
+        getFilterOperator(operators, rule.operator),
+        operators,
+        rule.negated
+      )
+      const next = updateFilterRule(current, id, {
+        operator: flipped.operator ?? rule.operator,
+        negated: flipped.negated || undefined,
+      })
+      emit(next, "negate", findFilterRule(next, id))
+    },
+    [emit, locked]
+  )
+
+  // Says where a node LANDED, the one mutator a screen reader hears nothing
+  // else about: focus stays on the handle and the name does not change. Reads
+  // the tree AFTER the move: the position and sibling count announced are the
+  // ones the user has just arrived at.
+  const announceReorder = React.useCallback(
+    (next: FilterQuery<V>, id: string, fromParentId: string | null) => {
+      const found = findFilterNode(next, id)
+      if (!found || !found.parent) return
+      const label = isFilterRule(found.node)
+        ? formatFilterPath(
+            latest.current.index,
+            found.node.path,
+            latest.current.labels.pathSeparator
+          )
+        : found.node.combinator === "and"
+          ? latest.current.labels.groupAll
+          : latest.current.labels.groupAny
+      const position = found.index + 1
+      const total = found.parent.rules.length
+
+      // A move that changed the node's CONTAINER is a different event, named by
+      // the group's own headline, or the bar's label at the top level.
+      if (fromParentId && fromParentId !== found.parent.id) {
+        const destination =
+          found.parent.id === next.id
+            ? latest.current.labels.filtersLabel
+            : found.parent.combinator === "and"
+              ? latest.current.labels.groupAll
+              : latest.current.labels.groupAny
+        setAnnouncement(
+          latest.current.labels.moveAnnouncement(
+            label,
+            destination,
+            position,
+            total
+          )
+        )
+        return
+      }
+
+      setAnnouncement(
+        latest.current.labels.reorderAnnouncement(label, position, total)
+      )
+    },
+    [setAnnouncement]
+  )
+
+  const moveNode = React.useCallback(
+    (id: string, delta: number) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const next = moveFilterNode(current, id, delta)
+      if (next === current) return
+      if (!emit(next, "reorder", findFilterRule(next, id))) return
+      // Within the owning group by construction, so there is no destination.
+      announceReorder(next, id, null)
+    },
+    [emit, announceReorder, locked]
+  )
+
+  // Also the drag layer's drop commit, so a drag and Alt+Arrow say the same.
+  const moveNodeTo = React.useCallback(
+    (id: string, parentId: string, index: number) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      // BEFORE the move: the only place the old parent still exists.
+      const fromParentId = findFilterNode(current, id)?.parent?.id ?? null
+      const next = moveFilterNodeTo(current, id, parentId, index)
+      if (next === current) return
+      if (!emit(next, "reorder", findFilterRule(next, id))) return
+      announceReorder(next, id, fromParentId)
+    },
+    [emit, announceReorder, locked]
+  )
+
+  const copyNodeTo = React.useCallback(
+    (id: string, parentId: string, index: number) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const next = copyFilterNodeTo(
+        current,
+        id,
+        parentId,
+        index,
+        latest.current.nextId
+      )
+      if (next === current) return
+      if (!emit(next, "duplicate", findFilterRule(current, id))) return
+      // The count again: an Alt-drag of a GROUP adds an unknown number of rows.
+      setAnnouncement(
+        latest.current.labels.countAnnouncement(countFilterRules(next))
+      )
+    },
+    [emit, locked, setAnnouncement]
+  )
+
+  const wrapNodeInGroup = React.useCallback(
+    (id: string, combinator: FilterCombinator = "or") => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const next = wrapFilterNodeInGroup(
+        current,
+        id,
+        latest.current.nextId(),
+        combinator
+      )
+      if (next === current) return
+      if (!emit(next, "add", findFilterRule(next, id))) return
+      setAnnouncement(latest.current.labels.groupAnnouncement(true))
+    },
+    [emit, locked, setAnnouncement]
+  )
+
+  const unwrapGroup = React.useCallback(
+    (groupId: string) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const next = unwrapFilterGroup(current, groupId)
+      if (next === current) return
+      // The conditions survive in place, so the count has not changed.
+      if (!emit(next, "remove", null)) return
+      setAnnouncement(latest.current.labels.groupAnnouncement(false))
+    },
+    [emit, locked, setAnnouncement]
+  )
+
+  // What a combinator change SOUNDS like: the pill's name changes with it, but
+  // a name change on the FOCUSED element is not re-announced by NVDA or JAWS.
+  // The group's own headline, not the bare word: it says what the query MEANS
+  // now, which is the thing that changed.
+  const announceCombinator = React.useCallback(
+    (combinator: FilterCombinator) => {
+      setAnnouncement(
+        combinator === "and"
+          ? latest.current.labels.groupAll
+          : latest.current.labels.groupAny
+      )
+    },
+    [setAnnouncement]
+  )
+
+  const setCombinatorAction = React.useCallback(
+    (groupId: string, combinator: FilterCombinator) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const next = setFilterCombinator(current, groupId, combinator)
+      if (next === current) return
+      if (!emit(next, "combinator", null)) return
+      announceCombinator(combinator)
+    },
+    [emit, locked, announceCombinator]
+  )
+
+  const toggleCombinatorAction = React.useCallback(
+    (groupId: string) => {
+      if (locked()) return
+      const current = latest.current.queryRef.current
+      const next = toggleFilterCombinator(current, groupId)
+      if (next === current) return
+      if (!emit(next, "combinator", null)) return
+      // Read off the COMMITTED tree, so the sentence cannot disagree with it.
+      const group = findFilterNode(next, groupId)?.node
+      if (group && !isFilterRule(group)) announceCombinator(group.combinator)
+    },
+    [emit, locked, announceCombinator]
+  )
+
+  const clearQueryAction = React.useCallback(() => {
+    if (locked()) return
+    const current = latest.current.queryRef.current
+    const next = clearFilterQuery(current)
+    if (next === current) return
+    if (!emit(next, "clear", null)) return
+    setAnnouncement(latest.current.labels.countAnnouncement(0))
+  }, [emit, locked, setAnnouncement])
+
+  // The live region, opened to the chrome inside the bar. The setter itself is
+  // not published: it is a channel anything could write anything to.
+  const announce = React.useCallback(
+    (message: string) => {
+      if (!message) return
+      setAnnouncement(message)
+    },
+    [setAnnouncement]
+  )
+
+  // A draft is a MUTATION in progress, so it locks with the rest, except
+  // `close`: a panel open when the bar turned read only must still dismiss.
+  const dispatchDraft = React.useCallback(
+    (action: FilterDraftAction<V>) => {
+      if (action.type !== "close" && locked()) return
+      dispatchDraftRaw(action)
+    },
+    [locked]
+  )
+
+  const openCreate = React.useCallback(() => {
+    if (locked()) return
+    dispatchDraftRaw({ type: "openCreate" })
+  }, [locked])
+
+  const openAmend = React.useCallback(
+    (id: string, step: FilterDraftStep) => {
+      if (locked()) return
+      const rule = findFilterRule(latest.current.queryRef.current, id)
+      if (!rule) return
+      dispatchDraftRaw({
+        type: "openAmend",
+        ruleId: id,
+        step,
+        path: rule.path,
+        operator: rule.operator,
+        value: rule.value,
+      })
+    },
+    [locked]
+  )
+
+  const closeDraft = React.useCallback(
+    () => dispatchDraftRaw({ type: "close" }),
+    []
+  )
+
+  const getQuery = React.useCallback(() => latest.current.queryRef.current, [])
+  const getDraft = React.useCallback(() => latest.current.draft, [])
+
+  /* ------------------------- draft -> query commit ------------------------ */
+
+  // The draft becomes a rule exactly once, when the reducer says it is ready.
+  // Here rather than in each click handler, which is what lets the "arity none
+  // skips the value step" branch live in the pure reducer.
+  React.useEffect(() => {
+    if (!draft || draft.status !== "ready") return
+    if (!isFilterDraftCommittable(draft)) return
+
+    if (draft.ruleId) {
+      updateRule(draft.ruleId, {
+        path: draft.path,
+        operator: draft.operator ?? "",
+        value: draft.value,
+      })
+    } else if (!locked()) {
+      // Asked here too: this branch burns an id and points the focus store at
+      // it, and a store naming a chip that never existed eats the tab stop.
+      const id = nextId()
+      addRule(
+        createFilterRule<V>({
+          id,
+          path: draft.path,
+          // Empty on purpose: the chip renders "Select condition" and opens.
+          operator: "",
+          value: undefined,
+        })
+      )
+      focusStore.set({ id, segment: "operator", autoOpen: true })
+    }
+    dispatchDraftRaw({ type: "close" })
+  }, [draft, addRule, updateRule, nextId, focusStore, locked])
+
+  /* ---------------------------- dev diagnostics --------------------------- */
+
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production") return
+    const issues = findFilterSchemaIssues(fields, (field) =>
+      resolveFilterOperators(field, operatorCatalog)
+    )
+    if (issues.duplicatePaths.length) {
+      warnFilterOnce(
+        `dup:${issues.duplicatePaths.join(",")}`,
+        `duplicate sibling field ids are ignored after the first: ${issues.duplicatePaths.join(", ")}`
+      )
+    }
+    if (issues.emptyIds.length) {
+      warnFilterOnce("empty-id", "every field needs a non-empty id")
+    }
+    if (issues.unknownDefaultOperators.length) {
+      warnFilterOnce(
+        `op:${issues.unknownDefaultOperators.join(",")}`,
+        `defaultOperator names an operator the field does not offer: ${issues.unknownDefaultOperators.join(", ")}`
+      )
+    }
+  }, [fields, operatorCatalog])
+
+  /* ------------------------------- contexts ------------------------------- */
+
+  const actions = React.useMemo<FilterActionsContextValue<V, O>>(
+    () => ({
+      index,
+      labels,
+      operatorCatalog,
+      editors,
+      size,
+      disabled,
+      readOnly,
+      variant,
+      menuClassName,
+      fieldPickerClassName,
+      convertToAdvanced: onConvertToAdvanced,
+      pathCollapse,
+      maxPathSegments,
+      resolveOperators,
+      // The same lookup the chrome uses, so a headless consumer can ask it too.
+      resolveEditor: (field, operator) =>
+        resolveFilterEditor(field, operator, editors) as
+          | FilterEditor<V, O>
+          | undefined,
+      resolution: resolutionStore,
+      addRule,
+      addGroup,
+      updateRule,
+      removeNode,
+      duplicateNode,
+      negateRule,
+      moveNode,
+      moveNodeTo,
+      copyNodeTo,
+      wrapNodeInGroup,
+      unwrapGroup,
+      setCombinator: setCombinatorAction,
+      toggleCombinator: toggleCombinatorAction,
+      clearQuery: clearQueryAction,
+      openCreate,
+      openAmend,
+      closeDraft,
+      dispatchDraft,
+      announce,
+      getQuery,
+      getDraft,
+      nextId,
+    }),
+    // Every input is memoized and every action `[]`-stable, so this
+    // republishes on a real schema or config change, never on a keystroke.
+    [
+      index,
+      labels,
+      operatorCatalog,
+      editors,
+      size,
+      disabled,
+      readOnly,
+      variant,
+      menuClassName,
+      fieldPickerClassName,
+      onConvertToAdvanced,
+      pathCollapse,
+      maxPathSegments,
+      resolveOperators,
+      resolutionStore,
+      addRule,
+      addGroup,
+      updateRule,
+      removeNode,
+      duplicateNode,
+      negateRule,
+      moveNode,
+      moveNodeTo,
+      copyNodeTo,
+      wrapNodeInGroup,
+      unwrapGroup,
+      setCombinatorAction,
+      toggleCombinatorAction,
+      clearQueryAction,
+      openCreate,
+      openAmend,
+      closeDraft,
+      dispatchDraft,
+      announce,
+      getQuery,
+      getDraft,
+      nextId,
+    ]
+  )
+
+  const state = React.useMemo(
+    () => ({
+      query,
+      draft,
+      ruleCount,
+      announcement,
+      announcementSeq: announced.seq,
+    }),
+    [query, draft, ruleCount, announcement, announced.seq]
+  )
+
+  const renderContext = React.useMemo(
+    () => ({ renderValue, renderChip, renderEmpty }),
+    [renderValue, renderChip, renderEmpty]
+  )
+
+  return (
+    <FilterActionsContext.Provider
+      value={actions as unknown as FilterActionsContextValue}
+    >
+      <FilterStateContext.Provider value={state as never}>
+        <FilterRenderContext.Provider value={renderContext as never}>
+          <FilterRowStateProvider value={rowStateStore}>
+            <FilterFocusContext.Provider value={focusStore}>
+              {children ??
+                (variant === "advanced" ? (
+                  <FiltersAdvanced<V, O>
+                    mode={advancedMode}
+                    align={advancedAlign}
+                    trigger={trigger}
+                    reorderable={reorderable}
+                    className={className}
+                  />
+                ) : (
+                  <FiltersRow
+                    trigger={trigger}
+                    showClear={showClear}
+                    className={className}
+                  />
+                ))}
+            </FilterFocusContext.Provider>
+          </FilterRowStateProvider>
+        </FilterRenderContext.Provider>
+      </FilterStateContext.Provider>
+    </FilterActionsContext.Provider>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                    Row                                     */
+/* -------------------------------------------------------------------------- */
+
+export interface FiltersRowProps {
+  trigger?: React.ReactNode
+  showClear?: boolean
+  className?: string
+}
+
+/**
+ * The chip row: a toolbar with a roving tabindex, where the predecessor made
+ * every segment of every chip its own tab stop. There is NO combinator here,
+ * because a chip row can draw a word between two pills but not a parenthesis.
+ */
+export function FiltersRow({ trigger, showClear, className }: FiltersRowProps) {
+  const actions = useFilterActions()
+  const sizes = filterControlSizes(actions)
+  const { query, ruleCount, announcement, announcementSeq } = useFilterState()
+  const focusStore = useFilterFocusStore()
+  const rootRef = React.useRef<HTMLDivElement>(null)
+  // The keys consult this even though the actions already refuse: an ungated
+  // Enter would ARM `autoOpen` for a popover that then refuses to open. Gated
+  // per branch, never at the top of `onKeyDown`: the arrows, Home and End are
+  // how a read-only bar is read.
+  const locked = isFilterLocked(actions)
+
+  // Flattened, not `query.rules.filter(isFilterRule)`: a query built in the
+  // advanced builder would otherwise hide nested conditions that still filter.
+  const rules = React.useMemo(() => flattenFilterRules(query), [query])
+
+  const chips = () =>
+    Array.from(
+      rootRef.current?.querySelectorAll<HTMLElement>(
+        '[data-slot="filter-chip"]'
+      ) ?? []
+    )
+
+  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    const target = (event.target as HTMLElement).closest<HTMLElement>(
+      '[data-slot="filter-chip"]'
+    )
+    if (!target) return
+    // A key pressed inside an open popover belongs to that popover.
+    if (event.target !== target) return
+
+    const all = chips()
+    const current = all.indexOf(target)
+    if (current === -1) return
+
+    const rtl = getComputedStyle(target).direction === "rtl"
+    const forward = rtl ? "ArrowLeft" : "ArrowRight"
+    const backward = rtl ? "ArrowRight" : "ArrowLeft"
+
+    const focusAt = (index: number) => {
+      const next = all[Math.max(0, Math.min(index, all.length - 1))]
+      if (!next) return
+      event.preventDefault()
+      next.focus()
+    }
+
+    const ruleId = target.dataset.ruleId
+    if (!ruleId) return
+
+    if (event.altKey && (event.key === forward || event.key === backward)) {
+      if (locked) return
+      event.preventDefault()
+      actions.moveNode(ruleId, event.key === forward ? 1 : -1)
+      return
+    }
+    if (event.key === forward) return focusAt(current + 1)
+    if (event.key === backward) return focusAt(current - 1)
+    if (event.key === "Home") return focusAt(0)
+    if (event.key === "End") return focusAt(all.length - 1)
+
+    if (event.key === "Backspace" || event.key === "Delete") {
+      if (locked) return
+      event.preventDefault()
+      actions.removeNode(ruleId)
+      // The neighbour taking this chip's place, so a run of deletes keeps focus.
+      requestAnimationFrame(() => {
+        const remaining = chips()
+        remaining[Math.min(current, remaining.length - 1)]?.focus()
+      })
+      return
+    }
+
+    if (event.key === "Enter" || event.key === " ") {
+      if (locked) return
+      event.preventDefault()
+      // Enter RESUMES the chip: the attribute segment is display only, so the
+      // target is whichever step the flow has not reached, never nothing.
+      const rule = findFilterRule(actions.getQuery(), ruleId)
+      if (!rule) return
+      const field = getFilterField(actions.index, rule.path)
+      // No popover to open, so autoOpen would sit armed until another chip
+      // spent it. The chip stays reachable and Delete still removes it.
+      if (!field) return
+      const operator = getFilterOperator(
+        actions.resolveOperators(field),
+        rule.operator
+      )
+      const segment =
+        rule.operator && operatorTakesValue(operator) ? "value" : "operator"
+      focusStore.set({ id: ruleId, segment, autoOpen: true })
+    }
+  }
+
+  return (
+    <div
+      ref={rootRef}
+      data-slot="filters"
+      data-empty={rules.length === 0 || undefined}
+      /* A presence hook, so a consumer can tint the whole read-only bar. */
+      data-readonly={actions.readOnly || undefined}
+      className={cn(
+        /* `sizes.button` and not `actions.size`: the gap ladder and the control
+           ladder must answer for the same rung, normalized in one place. */
+        filtersBarVariants({ size: sizes.button }),
+        /* An empty toolbar is still a flex child, so it took a gap with no
+           width. The gap goes, not the toolbar, which owns the row's name. */
+        rules.length === 0 && "gap-0",
+        className
+      )}
+    >
+      <div
+        role="toolbar"
+        aria-label={actions.labels.filtersLabel}
+        aria-orientation="horizontal"
+        /* `role=toolbar` disallows `aria-readonly`, and `aria-disabled` would
+           deny arrowing; a description is legal here and spoken on entry. */
+        {...(actions.readOnly
+          ? { "aria-description": actions.labels.readOnly }
+          : null)}
+        className={cn(filtersBarVariants({ size: sizes.button }))}
+        onKeyDown={onKeyDown}
+      >
+        {rules.map((rule, index) => (
+          <FilterChip key={rule.id} rule={rule} index={index} />
+        ))}
+      </div>
+
+      <FiltersBuilder trigger={trigger} />
+
+      {showClear && ruleCount > 0 ? (
+        // `ms-auto` and not `ml-auto`, so Clear stays on the trailing edge
+        // under RTL, where the whole bar mirrors.
+        <Button
+          variant="outline"
+          /* The same rung as the Add filter trigger beside it. */
+          size={sizes.button}
+          className="ms-auto"
+          /* `disabled` for the hard flag, `aria-disabled` for the soft one, so
+             a read-only Clear keeps its tab stop and can still be found. */
+          disabled={actions.disabled}
+          {...filterReadOnlyProps(actions)}
+          onClick={() => actions.clearQuery()}
+        >
+          {actions.labels.clear}
+        </Button>
+      ) : null}
+
+      {/* Keyed on the sequence, so the same sentence twice is two
+          announcements (see `announced` for the measurement). A replaced live
+          element stops being watched. */}
+      <div aria-live="polite" role="status" className="sr-only">
+        <span key={announcementSeq}>{announcement}</span>
+      </div>
+    </div>
+  )
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                   Exports                                  */
+/* -------------------------------------------------------------------------- */
+
+// The full pure READ surface, so one import reaches everything a predicate, a
+// saved view or a backend query needs. It stops at the query TREE and compiles
+// nothing: `flattenFilterConditions` is the hand-off a server compiles from.
+// No SQL emitter, because a server has to re-validate anything a browser sends
+// and should compile from the tree rather than parse a client's string. SQL is
+// one target of that hand-off beside Prisma, Drizzle, a REST query string and
+// Elasticsearch.
+export {
+  // The panel does not DRAW the built-in reasons, so this is the only way to
+  // surface "missing value", "empty group" and the rest.
+  collectFilterIssues,
+  copyFilterNodeTo,
+  createFilterGroup,
+  createFilterQuery,
+  createFilterRule,
+  countFilterRules,
+  flattenFilterConditions,
+  flattenFilterRules,
+  isFilterQueryEmpty,
+  isFilterRuleComplete,
+  moveFilterNodeTo,
+  pruneFilterQuery,
+  unwrapFilterGroup,
+  wrapFilterNodeInGroup,
+} from "@/components/reui/filters/filters-query"
+
+// The two resolver signatures `collectFilterIssues` takes.
+export type {
+  FilterArityResolver,
+  FilterValidateResolver,
+} from "@/components/reui/filters/filters-query"
+
+export {
+  // The read-only contract: the gate, and the props a mutating control wears.
+  filterReadOnlyProps,
+  isFilterLocked,
+  useFilterActions,
+  useFilterState,
+  useFilterFocus,
+  // What a custom chip needs to rebuild the roving scheme `renderChip` drops.
+  useFilterChipAutoOpen,
+  useFilterChipFocused,
+  useFilterFocusEmpty,
+  useFilterFocusStore,
+  useFilterRender,
+  useFilterSegmentFocus,
+} from "@/components/reui/filters/filters-context"
+
+export {
+  FilterChip,
+  FilterOperatorPopover,
+  FilterRuleMenuItems,
+  FilterValuePopover,
+  useFilterRuleDisplay,
+} from "@/components/reui/filters/filters-chip"
+export {
+  FiltersAdvanced,
+  FiltersAdvancedPanel,
+  FilterAdvancedRow,
+} from "@/components/reui/filters/filters-advanced"
+export {
+  FiltersBuilder,
+  FilterFieldPicker,
+} from "@/components/reui/filters/filters-builder"
+export { DEFAULT_FILTER_LABELS } from "@/components/reui/filters/filters-i18n"
+export {
+  DEFAULT_FILTER_OPERATORS,
+  DEFAULT_FILTER_OPERATOR_LABELS,
+} from "@/components/reui/filters/filters-operators"
+export {
+  DEFAULT_FILTER_EDITORS,
+  useFilterOptions,
+  useFilterValueResolution,
+} from "@/components/reui/filters/filters-editors"
+
+export type * from "@/components/reui/filters/filters-types"
\ No newline at end of file
diff --git a/apps/web/src/components/reui/frame.tsx b/apps/web/src/components/reui/frame.tsx
index 69e0246..b1a07ff 100644
--- a/apps/web/src/components/reui/frame.tsx
+++ b/apps/web/src/components/reui/frame.tsx
@@ -3,28 +3,30 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { cn } from "@authportal/ui/lib/utils"
 
 /**
- * CSS variable architecture for FramePanel theming:
- *
- * The Frame parent sets --frame-panel-bg and --frame-panel-border-color.
- * FramePanel consumes them directly via bg-(--frame-panel-bg) and
- * border-(--frame-panel-border-color). This means:
- *
- *   - variant="inverse" overrides those vars on Frame → all panels pick it up
- *   - <FramePanel className="bg-blue-50"> adds a direct utility on the element
- *     which wins over bg-(--frame-panel-bg) by Tailwind source order — no
- *     :not() or !important needed
+ * Frame sets --frame-panel-bg and --frame-panel-border-color; FramePanel reads
+ * them back as bg-(--frame-panel-bg) and border-(--frame-panel-border-color).
+ * So variant="inverse" re-points every panel from one place, and a consumer's
+ * own bg-* on a panel still wins on source order, with no :not() and no `!`.
  */
 const frameVariants = cva(
   [
     "relative flex flex-col bg-muted/50 gap-(--frame-gap) px-(--frame-px) py-(--frame-py) rounded-(--frame-radius)",
-    "(--radius-xl)] [--frame-radius:var(--radius-xl)]",
-    "(--radius-none)] (--radius-2xl)] (--radius-lg)] (--radius-none)]",
+    // Each rung is the radius that style's own shadcn Card resolves through, so
+    // a Frame and a Card side by side agree. lyra/sera are 0px, NOT
+    // var(--radius-none): no such token exists, and it only reached 0 by being
+    // invalid, which also left --frame-radius empty for anything reading it.
+    "[--frame-radius:var(--radius-xl)]",
     "[--frame-gap:--spacing(0.75)] [--frame-px:--spacing(0.75)] [--frame-py:--spacing(0.75)] [--frame-panel-header-gap:0rem] [--frame-panel-footer-gap:--spacing(1)]",
     "[--frame-panel-px-adjust:0px] [--frame-panel-py-adjust:0px] [--frame-panel-header-px-adjust:0px] [--frame-panel-header-py-adjust:0px] [--frame-panel-footer-px-adjust:0px] [--frame-panel-footer-py-adjust:0px]",
-    "[--frame-panel-px:calc(var(--frame-panel-px-base)_+_var(--frame-panel-px-adjust))] [--frame-panel-py:calc(var(--frame-panel-py-base)_+_var(--frame-panel-py-adjust))] [--frame-panel-header-px:calc(var(--frame-panel-header-px-base)_+_var(--frame-panel-header-px-adjust))] [--frame-panel-header-py:calc(var(--frame-panel-header-py-base)_+_var(--frame-panel-header-py-adjust))] [--frame-panel-footer-px:calc(var(--frame-panel-footer-px-base)_+_var(--frame-panel-footer-px-adjust))] [--frame-panel-footer-py:calc(var(--frame-panel-footer-py-base)_+_var(--frame-panel-footer-py-adjust))]",
-    "(1)] (1)] (1.25)] (1.5)] (1.5)] (0.5)] (1)] (1)]",
-    // Default panel token values — overridden per-variant below
+    "[--frame-panel-px:calc(var(--frame-panel-px-base)+var(--frame-panel-px-adjust))] [--frame-panel-py:calc(var(--frame-panel-py-base)+var(--frame-panel-py-adjust))] [--frame-panel-header-px:calc(var(--frame-panel-header-px-base)+var(--frame-panel-header-px-adjust))] [--frame-panel-header-py:calc(var(--frame-panel-header-py-base)+var(--frame-panel-header-py-adjust))] [--frame-panel-footer-px:calc(var(--frame-panel-footer-px-base)+var(--frame-panel-footer-px-adjust))] [--frame-panel-footer-py:calc(var(--frame-panel-footer-py-base)+var(--frame-panel-footer-py-adjust))]",
+    // Luma alone re-times the frame: wider gap and padding, roomier bars.
+    "",
     "[--frame-panel-bg:var(--color-card)] [--frame-panel-border-color:var(--color-border)] [--frame-border-color:var(--color-border)]",
+    // Concentric: the panel nests inside the frame's corner rather than copying
+    // it. It is inset by the 1px border plus --frame-px, so subtracting exactly
+    // that keeps the two arcs parallel. `ghost` drops the border term (no
+    // border), `dense` pins it to the frame radius (panels sit flush).
+    "[--frame-panel-radius:calc(var(--frame-radius)-var(--frame-px)-1px)]",
   ],
   {
     variants: {
@@ -32,14 +34,18 @@ const frameVariants = cva(
         default: "border border-[var(--frame-border-color)] bg-clip-padding",
         inverse:
           "[--frame-panel-bg:color-mix(in_oklch,var(--color-muted)_40%,transparent)] border border-[var(--frame-border-color)] bg-background bg-clip-padding",
-        ghost: "",
+        ghost: "[--frame-panel-radius:calc(var(--frame-radius)-var(--frame-px))]",
       },
+      // Bars read as chrome, not a second content block: py runs 0.5/1.5/2/2.5
+      // against a body py of 2/3.5/4/5, while px stays level with the body so
+      // header, content and footer left-align. xs floors at 0.5 (2px), below
+      // which it stops reading as padding. No style-*.css overrides these.
       spacing: {
-        xs: "[--frame-panel-px-base:--spacing(2)] [--frame-panel-py-base:--spacing(2)] [--frame-panel-header-px-base:--spacing(2)] [--frame-panel-header-py-base:--spacing(1)] [--frame-panel-footer-px-base:--spacing(2)] [--frame-panel-footer-py-base:--spacing(1)] (3)] (1)] (3)] (3)]",
-        sm: "[--frame-panel-px-base:--spacing(3)] [--frame-panel-py-base:--spacing(3.5)] [--frame-panel-header-px-base:--spacing(3)] [--frame-panel-header-py-base:--spacing(2.5)] [--frame-panel-footer-px-base:--spacing(3)] [--frame-panel-footer-py-base:--spacing(2.5)] (2)] (2)] (2)]",
+        xs: "[--frame-panel-px-base:--spacing(2)] [--frame-panel-py-base:--spacing(2)] [--frame-panel-header-px-base:--spacing(2)] [--frame-panel-header-py-base:--spacing(0.5)] [--frame-panel-footer-px-base:--spacing(2)] [--frame-panel-footer-py-base:--spacing(0.5)]",
+        sm: "[--frame-panel-px-base:--spacing(3)] [--frame-panel-py-base:--spacing(3.5)] [--frame-panel-header-px-base:--spacing(3)] [--frame-panel-header-py-base:--spacing(1.5)] [--frame-panel-footer-px-base:--spacing(3)] [--frame-panel-footer-py-base:--spacing(1.5)]",
         default:
-          "[--frame-panel-px-base:--spacing(4)] [--frame-panel-py-base:--spacing(4)] [--frame-panel-header-px-base:--spacing(4)] [--frame-panel-header-py-base:--spacing(3)] [--frame-panel-footer-px-base:--spacing(4)] [--frame-panel-footer-py-base:--spacing(3)] (2)] (2)] (2)]",
-        lg: "[--frame-panel-px-base:--spacing(5)] [--frame-panel-py-base:--spacing(5)] [--frame-panel-header-px-base:--spacing(5)] [--frame-panel-header-py-base:--spacing(4)] [--frame-panel-footer-px-base:--spacing(5)] [--frame-panel-footer-py-base:--spacing(4)] (2)] (2)] (2)]",
+          "[--frame-panel-px-base:--spacing(4)] [--frame-panel-py-base:--spacing(4)] [--frame-panel-header-px-base:--spacing(4)] [--frame-panel-header-py-base:--spacing(2)] [--frame-panel-footer-px-base:--spacing(4)] [--frame-panel-footer-py-base:--spacing(2)]",
+        lg: "[--frame-panel-px-base:--spacing(5)] [--frame-panel-py-base:--spacing(5)] [--frame-panel-header-px-base:--spacing(5)] [--frame-panel-header-py-base:--spacing(2.5)] [--frame-panel-footer-px-base:--spacing(5)] [--frame-panel-footer-py-base:--spacing(2.5)]",
       },
       stacked: {
         true: [
@@ -55,8 +61,9 @@ const frameVariants = cva(
         ],
       },
       dense: {
-        // Positional rules must stay as parent selectors — cannot be expressed via CSS vars
-        true: "p-0 gap-0 border-[var(--frame-border-color)] [&_[data-slot=frame-panel]]:-mx-px [&_[data-slot=frame-panel]]:before:hidden [&_[data-slot=frame-panel]:last-child]:-mb-px [&:not(:has([data-slot=frame-panel-header]))_[data-slot=frame-panel]:is(:first-child)]:-mt-px",
+        // Parent selectors, not CSS vars: these are positional. Panels are
+        // pulled flush (-mx-px), so corners align with the frame's own radius.
+        true: "p-0 gap-0 border-[var(--frame-border-color)] [--frame-panel-radius:var(--frame-radius)] [&_[data-slot=frame-panel]]:-mx-px [&_[data-slot=frame-panel]]:before:hidden [&_[data-slot=frame-panel]:last-child]:-mb-px [&:not(:has([data-slot=frame-panel-header]))_[data-slot=frame-panel]:is(:first-child)]:-mt-px",
         false: "",
       },
     },
@@ -98,13 +105,11 @@ function FramePanel({
   return (
     <div
       className={cn(
-        // bg-(--frame-panel-bg) and border-(--frame-panel-border-color) consume the
-        // CSS vars set by the Frame parent. Any explicit bg-* or border-* class passed
-        // via className overrides these by Tailwind source order - no ! needed.
-        "relative overflow-hidden rounded-(--frame-radius) border border-(--frame-panel-border-color) bg-(--frame-panel-bg) bg-clip-padding shadow-xs",
-        // `fit` sizes the panel to its content; otherwise it grows to fill the frame.
+        "relative overflow-hidden rounded-(--frame-panel-radius) border border-(--frame-panel-border-color) bg-(--frame-panel-bg) bg-clip-padding shadow-xs",
+        /* `fit` sizes the panel to its content; otherwise it grows to fill
+           the frame. */
         !fit && "grow",
-        "before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--frame-radius)-1px)] before:shadow-black/5",
+        "before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--frame-panel-radius)-1px)] before:shadow-black/5",
         "dark:bg-clip-border dark:before:shadow-white/5",
         "px-(--frame-panel-px) py-(--frame-panel-py)",
         className
diff --git a/apps/web/src/components/reui/icon-tile.tsx b/apps/web/src/components/reui/icon-tile.tsx
index 3989ac1..fc8c691 100644
--- a/apps/web/src/components/reui/icon-tile.tsx
+++ b/apps/web/src/components/reui/icon-tile.tsx
@@ -27,7 +27,7 @@ import { cn } from "@authportal/ui/lib/utils"
 const iconTileVariants = cva(
   [
     "relative inline-flex shrink-0 items-center justify-center align-middle",
-    "size-(--icon-tile-size) rounded-(--icon-tile-radius)",
+    "size-(--icon-tile-size) rounded-[var(--icon-tile-radius,min(var(--radius-md),calc(var(--icon-tile-size)/3)))]",
     "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-(--icon-tile-icon-size)",
   ],
   {
@@ -46,7 +46,7 @@ const iconTileVariants = cva(
         soft: [
           "isolate p-(--icon-tile-inset) text-primary bg-current/10",
           "after:absolute after:-z-10 after:inset-(--icon-tile-inset)",
-          "after:rounded-[calc(var(--icon-tile-radius)-var(--icon-tile-inset))]",
+          "after:rounded-[calc(var(--icon-tile-radius,min(var(--radius-md),calc(var(--icon-tile-size)/3)))-var(--icon-tile-inset))]",
           "after:border after:border-current/20 after:bg-current/5",
         ],
         /** Filled tone with a contrasting glyph. Retint with `bg-*` + a text color. */
@@ -55,7 +55,7 @@ const iconTileVariants = cva(
         frame: [
           "isolate border border-border bg-muted/50 p-(--icon-tile-inset)",
           "after:absolute after:-z-10 after:inset-(--icon-tile-inset)",
-          "after:rounded-[calc(var(--icon-tile-radius)-var(--icon-tile-inset))]",
+          "after:rounded-[calc(var(--icon-tile-radius,min(var(--radius-md),calc(var(--icon-tile-size)/3)))-var(--icon-tile-inset))]",
           "after:border after:border-border after:bg-card after:shadow-xs",
         ],
       },
@@ -69,9 +69,10 @@ const iconTileVariants = cva(
       },
       /**
        * `default`: active style radius. `full`: circular.
-       * The plain value is the fallback outside a style scope; the `style-*`
-       * tokens win by specificity inside one, and survive the registry
-       * transform as the single resolved value per generated style.
+       * No bare rung beside the ladder: the registry transform writes the
+       * installed style's rung bare, and a second bare rung would leave class
+       * order to pick the winner. The no-style fallback lives in the var()
+       * that reads the radius instead.
        *
        * Each style token is clamped to a fraction of the tile. A flat radius
        * is a circle once it reaches half the box, so the soft styles used to
@@ -82,7 +83,7 @@ const iconTileVariants = cva(
        */
       radius: {
         default:
-          "[--icon-tile-radius:min(var(--radius-md),calc(var(--icon-tile-size)/3))] [--icon-tile-radius:min(var(--radius-md),calc(var(--icon-tile-size)/3))]",
+          "[--icon-tile-radius:min(var(--radius-md),calc(var(--icon-tile-size)/3))]",
         full: "[--icon-tile-radius:calc(infinity*1px)]",
       },
     },
diff --git a/apps/web/src/design-preview/section-grid.tsx b/apps/web/src/design-preview/section-grid.tsx
index b485cbb..6e9bc71 100644
--- a/apps/web/src/design-preview/section-grid.tsx
+++ b/apps/web/src/design-preview/section-grid.tsx
@@ -1,15 +1,8 @@
 import { useMemo, useState, type ReactNode } from 'react'
 import { SearchIcon } from 'lucide-react'
-import {
-  getCoreRowModel,
-  getPaginationRowModel,
-  getSortedRowModel,
-  useReactTable,
-  type ColumnDef,
-  type RowSelectionState,
-  type SortingState,
-} from '@tanstack/react-table'
-import { DataGrid } from '@/components/reui/data-grid/data-grid'
+import { useTable, type ColumnDef, type RowSelectionState, type SortingState } from '@tanstack/react-table'
+import { DATA_GRID_RU } from '@/lib/reui-ru'
+import { DataGrid, dataGridFeatures, type DataGridFeatures } from '@/components/reui/data-grid/data-grid'
 import { DataGridColumnHeader } from '@/components/reui/data-grid/data-grid-column-header'
 import { DataGridPagination } from '@/components/reui/data-grid/data-grid-pagination'
 import { DataGridScrollArea } from '@/components/reui/data-grid/data-grid-scroll-area'
@@ -118,8 +111,8 @@ export function PreviewSectionGrid<T extends object>({
     })
   }, [rows, views, view, query, searchText])
 
-  const defs = useMemo<ColumnDef<T>[]>(() => {
-    const list: ColumnDef<T>[] = []
+  const defs = useMemo<ColumnDef<DataGridFeatures, T>[]>(() => {
+    const list: ColumnDef<DataGridFeatures, T>[] = []
     if (selectable) {
       list.push({
         id: 'select',
@@ -149,7 +142,8 @@ export function PreviewSectionGrid<T extends object>({
     return list
   }, [columns, selectable])
 
-  const table = useReactTable({
+  const table = useTable({
+    features: dataGridFeatures,
     columns: defs,
     data,
     getRowId,
@@ -158,9 +152,6 @@ export function PreviewSectionGrid<T extends object>({
     onSortingChange: setSorting,
     onRowSelectionChange: setRowSelection,
     onPaginationChange: setPagination,
-    getCoreRowModel: getCoreRowModel(),
-    getSortedRowModel: getSortedRowModel(),
-    getPaginationRowModel: getPaginationRowModel(),
   })
 
   const minWidth = columns.reduce((sum, c) => sum + c.size, selectable ? SELECT_COLUMN_SIZE : 0)
@@ -170,6 +161,7 @@ export function PreviewSectionGrid<T extends object>({
   return (
     <DataGrid
       table={table}
+      i18n={DATA_GRID_RU}
       recordCount={data.length}
       onRowClick={onRowClick}
       emptyMessage={emptyMessage}
diff --git a/apps/web/src/lib/reui-ru.ts b/apps/web/src/lib/reui-ru.ts
new file mode 100644
index 0000000..cde496c
--- /dev/null
+++ b/apps/web/src/lib/reui-ru.ts
@@ -0,0 +1,79 @@
+import type { DataGridI18nOverrides } from '@/components/reui/data-grid/data-grid-i18n'
+import type { FilterLabels } from '@/components/reui/filters/filters-types'
+
+/** Русские подписи DataGrid ReUI (передаются в проп `i18n`). */
+export const DATA_GRID_RU: DataGridI18nOverrides = {
+  labels: {
+    sortAscending: 'По возрастанию',
+    sortDescending: 'По убыванию',
+    pinColumnStart: 'Закрепить слева',
+    pinColumnEnd: 'Закрепить справа',
+    moveColumnStart: 'Сдвинуть влево',
+    moveColumnEnd: 'Сдвинуть вправо',
+    columnsMenu: 'Колонки',
+    unpinColumn: (title) => `Открепить колонку «${title}»`,
+    toggleColumns: 'Колонки',
+    rowCreate: 'Добавить строку',
+    pinRow: 'Закрепить строку',
+    unpinRow: 'Открепить строку',
+    selectRow: 'Выбрать строку',
+    selectAll: 'Выбрать все',
+    expandRow: 'Развернуть строку',
+    collapseRow: 'Свернуть строку',
+    dragToReorder: 'Перетащите, чтобы изменить порядок',
+    dragToReorderRow: 'Перетащите строку, чтобы изменить порядок',
+    reorderingUnavailable: 'Порядок менять нельзя',
+    loading: 'Загрузка…',
+    empty: 'Нет данных',
+    allRowsLoaded: 'Все записи загружены',
+    rowsPerPage: 'Строк на странице',
+    paginationInfo: ({ from, to, count }) => `${from} – ${to} из ${count}`,
+    previousPage: 'Предыдущая страница',
+    nextPage: 'Следующая страница',
+    goToPage: (page) => `Страница ${page}`,
+    filterSelectedCount: (count) => `Выбрано: ${count}`,
+    filterNoResults: 'Ничего не найдено.',
+    filterClear: 'Сбросить фильтры',
+  },
+}
+
+/** Русские подписи Filters ReUI (проп `labels`). */
+export const FILTERS_RU: Partial<FilterLabels> = {
+  addFilter: 'Фильтры',
+  advancedFilter: 'Расширенный фильтр',
+  clearAll: 'Сбросить все',
+  searchFields: 'Поиск полей…',
+  searchOperators: 'Поиск условий…',
+  searchOptions: 'Поиск…',
+  back: 'Назад',
+  clear: 'Сбросить',
+  apply: 'Применить',
+  empty: 'Ничего не найдено',
+  loading: 'Загрузка…',
+  where: 'Где',
+  and: 'И',
+  or: 'Или',
+  duplicate: 'Дублировать',
+  negate: 'Инвертировать',
+  remove: 'Удалить',
+  filtersLabel: 'Фильтры',
+  valuePlaceholder: 'введите текст…',
+  selectPlaceholder: 'Выберите…',
+  noValue: 'нет значения',
+  selectCondition: 'Выберите условие',
+  incomplete: 'фильтр не заполнен',
+}
+
+/** Русские названия условий (проп `operatorLabels`). */
+export const FILTER_OPERATORS_RU: Record<string, string> = {
+  contains: 'содержит',
+  not_contains: 'не содержит',
+  starts_with: 'начинается с',
+  ends_with: 'заканчивается на',
+  is: 'равно',
+  is_not: 'не равно',
+  is_any_of: 'одно из',
+  is_none_of: 'ни одно из',
+  empty: 'пусто',
+  not_empty: 'не пусто',
+}
diff --git a/apps/web/src/routes/_auth.admin.logins.tsx b/apps/web/src/routes/_auth.admin.logins.tsx
index 801316d..747c96b 100644
--- a/apps/web/src/routes/_auth.admin.logins.tsx
+++ b/apps/web/src/routes/_auth.admin.logins.tsx
@@ -7,14 +7,10 @@ import { useMemo, useState } from 'react'
 import { createFileRoute } from '@tanstack/react-router'
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
 import {
-  getCoreRowModel,
-  getFilteredRowModel,
-  getPaginationRowModel,
-  getSortedRowModel,
   type ColumnDef,
   type PaginationState,
   type SortingState,
-  useReactTable,
+  useTable,
 } from '@tanstack/react-table'
 import { toast } from 'sonner'
 import type { AdminSession, AuditLogEntry } from '@authportal/shared'
@@ -35,7 +31,8 @@ import {
   type AuditRange,
 } from '@/components/reui-kit/audit-log-helpers'
 import { Badge } from '@/components/reui/badge'
-import { DataGrid } from '@/components/reui/data-grid/data-grid'
+import { DATA_GRID_RU } from '@/lib/reui-ru'
+import { DataGrid, dataGridFeatures, type DataGridFeatures } from '@/components/reui/data-grid/data-grid'
 import { DataGridColumnHeader } from '@/components/reui/data-grid/data-grid-column-header'
 import { DataGridPagination } from '@/components/reui/data-grid/data-grid-pagination'
 import { DataGridScrollArea } from '@/components/reui/data-grid/data-grid-scroll-area'
@@ -141,7 +138,7 @@ function AdminLoginsPage() {
     return { ok, fail, ips: ips.size, sessions: sessions.length }
   }, [entries, sessions.length])
 
-  const historyColumns = useMemo<ColumnDef<AuditLogEntry>[]>(
+  const historyColumns = useMemo<ColumnDef<DataGridFeatures, AuditLogEntry>[]>(
     () => [
       {
         accessorKey: 'created_at',
@@ -244,19 +241,16 @@ function AdminLoginsPage() {
     [],
   )
 
-  const historyTable = useReactTable({
+  const historyTable = useTable({
+    features: dataGridFeatures,
     data: filtered,
     columns: historyColumns,
     state: { pagination, sorting },
     onPaginationChange: setPagination,
     onSortingChange: setSorting,
-    getCoreRowModel: getCoreRowModel(),
-    getFilteredRowModel: getFilteredRowModel(),
-    getPaginationRowModel: getPaginationRowModel(),
-    getSortedRowModel: getSortedRowModel(),
   })
 
-  const sessionColumns = useMemo<ColumnDef<AdminSession>[]>(
+  const sessionColumns = useMemo<ColumnDef<DataGridFeatures, AdminSession>[]>(
     () => [
       {
         accessorKey: 'email',
@@ -351,13 +345,12 @@ function AdminLoginsPage() {
     pageIndex: 0,
     pageSize: 20,
   })
-  const sessionsTable = useReactTable({
+  const sessionsTable = useTable({
+    features: dataGridFeatures,
     data: sessions,
     columns: sessionColumns,
     state: { pagination: sessionPagination },
     onPaginationChange: setSessionPagination,
-    getCoreRowModel: getCoreRowModel(),
-    getPaginationRowModel: getPaginationRowModel(),
   })
 
   return (
@@ -482,6 +475,7 @@ function AdminLoginsPage() {
               <Skeleton className="h-64 w-full" />
             ) : (
               <DataGrid
+                i18n={DATA_GRID_RU}
                 table={historyTable}
                 recordCount={filtered.length}
                 tableLayout={{ dense: true }}
@@ -522,6 +516,7 @@ function AdminLoginsPage() {
           <Skeleton className="h-64 w-full" />
         ) : (
           <DataGrid
+            i18n={DATA_GRID_RU}
             table={sessionsTable}
             recordCount={sessions.length}
             tableLayout={{ dense: true }}
diff --git a/apps/web/tsconfig.app.json b/apps/web/tsconfig.app.json
index b7790d3..4590f3a 100644
--- a/apps/web/tsconfig.app.json
+++ b/apps/web/tsconfig.app.json
@@ -4,7 +4,7 @@
     "target": "ES2022",
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "module": "ESNext",
-    "types": ["vite/client"],
+    "types": ["vite/client", "node"],
     "skipLibCheck": true,
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
@@ -13,8 +13,8 @@
     "noEmit": true,
     "jsx": "react-jsx",
     "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
     "noFallthroughCasesInSwitch": true,
     "paths": {
       "@/*": ["./src/*"],
diff --git a/packages/ui/src/components/button-group.tsx b/packages/ui/src/components/button-group.tsx
index 4af858f..56b1c38 100644
--- a/packages/ui/src/components/button-group.tsx
+++ b/packages/ui/src/components/button-group.tsx
@@ -1,8 +1,8 @@
 import { mergeProps } from "@base-ui/react/merge-props"
 import { useRender } from "@base-ui/react/use-render"
 import { cva, type VariantProps } from "class-variance-authority"
-
 import { cn } from "@authportal/ui/lib/utils"
+
 import { Separator } from "@authportal/ui/components/separator"
 
 const buttonGroupVariants = cva(
diff --git a/packages/ui/src/components/button.tsx b/packages/ui/src/components/button.tsx
index 4c02368..1b4ce67 100644
--- a/packages/ui/src/components/button.tsx
+++ b/packages/ui/src/components/button.tsx
@@ -1,6 +1,5 @@
 import { Button as ButtonPrimitive } from "@base-ui/react/button"
 import { cva, type VariantProps } from "class-variance-authority"
-
 import { cn } from "@authportal/ui/lib/utils"
 
 const buttonVariants = cva(
diff --git a/packages/ui/src/components/checkbox.tsx b/packages/ui/src/components/checkbox.tsx
index 642c789..aecb3ff 100644
--- a/packages/ui/src/components/checkbox.tsx
+++ b/packages/ui/src/components/checkbox.tsx
@@ -1,5 +1,6 @@
-import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox"
+"use client"
 
+import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox"
 import { cn } from "@authportal/ui/lib/utils"
 import { CheckIcon } from "lucide-react"
 
@@ -8,7 +9,7 @@ function Checkbox({ className, ...props }: CheckboxPrimitive.Root.Props) {
     <CheckboxPrimitive.Root
       data-slot="checkbox"
       className={cn(
-        "peer relative flex size-4 shrink-0 items-center justify-center rounded-[4px] border border-input transition-colors outline-none group-has-disabled/field:opacity-50 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground dark:data-checked:bg-primary",
+        "peer relative flex size-4 shrink-0 items-center justify-center rounded-[4px] border border-input transition-colors outline-none group-has-disabled/field:opacity-50 group-has-[:focus-visible]/field-label:ring-0 group-has-[:focus-visible]/field-label:not-data-checked:border-input after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground group-has-[:focus-visible]/field-label:data-checked:border-primary dark:data-checked:bg-primary",
         className
       )}
       {...props}
diff --git a/packages/ui/src/components/dropdown-menu.tsx b/packages/ui/src/components/dropdown-menu.tsx
index e6ebc7b..34c3f8b 100644
--- a/packages/ui/src/components/dropdown-menu.tsx
+++ b/packages/ui/src/components/dropdown-menu.tsx
@@ -2,7 +2,6 @@
 
 import * as React from "react"
 import { Menu as MenuPrimitive } from "@base-ui/react/menu"
-
 import { cn } from "@authportal/ui/lib/utils"
 import { ChevronRightIcon, CheckIcon } from "lucide-react"
 
diff --git a/packages/ui/src/components/input.tsx b/packages/ui/src/components/input.tsx
index 003954c..15bd00f 100644
--- a/packages/ui/src/components/input.tsx
+++ b/packages/ui/src/components/input.tsx
@@ -1,6 +1,5 @@
 import * as React from "react"
 import { Input as InputPrimitive } from "@base-ui/react/input"
-
 import { cn } from "@authportal/ui/lib/utils"
 
 function Input({ className, type, ...props }: React.ComponentProps<"input">) {
diff --git a/packages/ui/src/components/popover.tsx b/packages/ui/src/components/popover.tsx
index 3798f8b..cac3363 100644
--- a/packages/ui/src/components/popover.tsx
+++ b/packages/ui/src/components/popover.tsx
@@ -1,6 +1,5 @@
 import * as React from "react"
 import { Popover as PopoverPrimitive } from "@base-ui/react/popover"
-
 import { cn } from "@authportal/ui/lib/utils"
 
 function Popover({ ...props }: PopoverPrimitive.Root.Props) {
diff --git a/packages/ui/src/components/scroll-area.tsx b/packages/ui/src/components/scroll-area.tsx
index c306c71..6b6d202 100644
--- a/packages/ui/src/components/scroll-area.tsx
+++ b/packages/ui/src/components/scroll-area.tsx
@@ -1,7 +1,5 @@
-"use client"
-
+import * as React from "react"
 import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area"
-
 import { cn } from "@authportal/ui/lib/utils"
 
 function ScrollArea({
diff --git a/packages/ui/src/components/select.tsx b/packages/ui/src/components/select.tsx
index 6090d8a..9f00976 100644
--- a/packages/ui/src/components/select.tsx
+++ b/packages/ui/src/components/select.tsx
@@ -1,8 +1,5 @@
-"use client"
-
 import * as React from "react"
 import { Select as SelectPrimitive } from "@base-ui/react/select"
-
 import { cn } from "@authportal/ui/lib/utils"
 import { ChevronDownIcon, CheckIcon, ChevronUpIcon } from "lucide-react"
 
diff --git a/packages/ui/src/components/separator.tsx b/packages/ui/src/components/separator.tsx
index a1aedc1..5fe46fc 100644
--- a/packages/ui/src/components/separator.tsx
+++ b/packages/ui/src/components/separator.tsx
@@ -1,5 +1,6 @@
-import { Separator as SeparatorPrimitive } from "@base-ui/react/separator"
+"use client"
 
+import { Separator as SeparatorPrimitive } from "@base-ui/react/separator"
 import { cn } from "@authportal/ui/lib/utils"
 
 function Separator({
diff --git a/packages/ui/src/components/tooltip.tsx b/packages/ui/src/components/tooltip.tsx
index bf7e00f..1ceebea 100644
--- a/packages/ui/src/components/tooltip.tsx
+++ b/packages/ui/src/components/tooltip.tsx
@@ -1,5 +1,6 @@
-import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip"
+"use client"
 
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip"
 import { cn } from "@authportal/ui/lib/utils"
 
 function TooltipProvider({
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e3e1f43..913253e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -129,7 +129,7 @@ importers:
         version: 8.64.0(eslint@10.7.0(jiti@2.7.0))(typescript@6.0.3)
       vitest:
         specifier: 'catalog:'
-        version: 4.1.10(@types/node@22.20.1)(vite@8.1.5(@types/node@22.20.1)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1))
+        version: 4.1.10(@types/node@22.20.1)(vite@8.1.5(@types/node@22.20.1)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1))
 
   apps/web:
     dependencies:
@@ -142,6 +142,18 @@ importers:
       '@base-ui/react':
         specifier: ^1.5.0
         version: 1.6.0(@date-fns/tz@1.5.0)(@types/react@19.2.17)(date-fns@4.4.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/core':
+        specifier: ^6.3.1
+        version: 6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/modifiers':
+        specifier: ^9.0.0
+        version: 9.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/sortable':
+        specifier: ^10.0.0
+        version: 10.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/utilities':
+        specifier: ^3.2.2
+        version: 3.2.2(react@19.2.7)
       '@fontsource-variable/geist':
         specifier: ^5.3.0
         version: 5.3.0
@@ -164,14 +176,20 @@ importers:
         specifier: ^1.170.15
         version: 1.170.18(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@tanstack/react-table':
-        specifier: ^8.21.3
-        version: 8.21.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+        specifier: ^9.3.1
+        version: 9.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@tanstack/react-virtual':
+        specifier: ^3.14.21
+        version: 3.14.21(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@tanstack/router-vite-plugin':
         specifier: ^1.167.18
         version: 1.167.22(@tanstack/react-router@1.170.18(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(esbuild@0.28.1)(rolldown@1.1.5)(rollup@4.62.2)(vite@8.1.5(@types/node@24.13.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1))
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
+      date-fns:
+        specifier: ^4.4.0
+        version: 4.4.0
       lucide-react:
         specifier: 'catalog:'
         version: 1.25.0(react@19.2.7)
@@ -309,7 +327,7 @@ importers:
         version: 8.64.0(eslint@10.7.0(jiti@2.7.0))(typescript@6.0.3)
       vitest:
         specifier: 'catalog:'
-        version: 4.1.10(@types/node@24.13.3)(vite@8.1.5(@types/node@24.13.3)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1))
+        version: 4.1.10(@types/node@24.13.3)(vite@8.1.5(@types/node@24.13.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1))
 
   packages/ui:
     dependencies:
@@ -542,6 +560,34 @@ packages:
   '@date-fns/tz@1.5.0':
     resolution: {integrity: sha512-lwYN/vDPeNRULcepoE/LO2Pgx+7/RV+S9ARfbc9lr2DtGkOD7pAiruHvbR1RX3Qyf6ja47EWJDMsNK5vK08DJg==}
 
+  '@dnd-kit/accessibility@3.1.1':
+    resolution: {integrity: sha512-2P+YgaXF+gRsIihwwY1gCsQSYnu9Zyj2py8kY5fFvUM1qm2WA2u639R6YNVfU4GWr+ZM5mqEsfHZZLoRONbemw==}
+    peerDependencies:
+      react: '>=16.8.0'
+
+  '@dnd-kit/core@6.3.1':
+    resolution: {integrity: sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ==}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@dnd-kit/modifiers@9.0.0':
+    resolution: {integrity: sha512-ybiLc66qRGuZoC20wdSSG6pDXFikui/dCNGthxv4Ndy8ylErY0N3KVxY2bgo7AWwIbxDmXDg3ylAFmnrjcbVvw==}
+    peerDependencies:
+      '@dnd-kit/core': ^6.3.0
+      react: '>=16.8.0'
+
+  '@dnd-kit/sortable@10.0.0':
+    resolution: {integrity: sha512-+xqhmIIzvAYMGfBYYnbKuNicfSsk4RksY2XdmJhT+HAC01nix6fHCztU68jooFiMUB01Ky3F0FyOvhG/BZrWkg==}
+    peerDependencies:
+      '@dnd-kit/core': ^6.3.0
+      react: '>=16.8.0'
+
+  '@dnd-kit/utilities@3.2.2':
+    resolution: {integrity: sha512-+MKAJEOfaBe5SmV6t34p80MMKhjvUz0vRrvVJbPT0WElzaOJ/1xs+D+KDv+tD/NE5ujfrChEcshd4fLn0wpiqg==}
+    peerDependencies:
+      react: '>=16.8.0'
+
   '@drizzle-team/brocli@0.10.2':
     resolution: {integrity: sha512-z33Il7l5dKjUgGULTqBsQBQwckHh5AbIuxhdsIxDDiZAzBOrZO6q9ogcWC65kU382AfynTfgNumVcNIjuIua6w==}
 
@@ -1961,18 +2007,29 @@ packages:
       react: '>=18.0.0 || >=19.0.0'
       react-dom: '>=18.0.0 || >=19.0.0'
 
+  '@tanstack/react-store@0.11.2':
+    resolution: {integrity: sha512-oj5O5DmiMWE+ih+SioX2ayC1kbK7d3fpLx0B75fPJr9nY3zU+hoW010yr64qXsY/9fyiLVE2bn5mGNV3owm8RQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   '@tanstack/react-store@0.9.3':
     resolution: {integrity: sha512-y2iHd/N9OkoQbFJLUX1T9vbc2O9tjH0pQRgTcx1/Nz4IlwLvkgpuglXUx+mXt0g5ZDFrEeDnONPqkbfxXJKwRg==}
     peerDependencies:
       react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
-  '@tanstack/react-table@8.21.3':
-    resolution: {integrity: sha512-5nNMTSETP4ykGegmVkhjcS8tTLW6Vl4axfEGQN3v0zdHYbK4UfoqfPChclTrJ4EoK9QynqAu9oUf8VEmrpZ5Ww==}
-    engines: {node: '>=12'}
+  '@tanstack/react-table@9.3.1':
+    resolution: {integrity: sha512-E6Ya5TnY6EaGyZYIUqig/29Lr/gJSAubQkLJFqiWkUl5nRCr0Xr9hvJot+NiRTtG+TzGxHTiqUW3bnLtQxlHug==}
+    engines: {node: '>=20'}
     peerDependencies:
-      react: '>=16.8'
-      react-dom: '>=16.8'
+      react: '>=18'
+
+  '@tanstack/react-virtual@3.14.21':
+    resolution: {integrity: sha512-wWE/ZJDNNDp18JHWy7n5PQooqerHePVkEEu6Op0twKQ2InF9DPhYMQptQY0syDEviMd3/r8D0OUvKJibDGm9HQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   '@tanstack/router-cli@1.167.31':
     resolution: {integrity: sha512-/jjZzcwOdBpcLIXRYsmHzFlchbd3esBD6m9bmeoY8l9mVkv/NZOhfx1h/mEn6nETkpxBT4y3pTJ0Ave2EoYXnQ==}
@@ -2024,12 +2081,18 @@ packages:
     resolution: {integrity: sha512-+Yx7TGqFoE0uxVSedET6MIhxgKALQdSYfUgDTqA9Sj4aWBjoIiH7B3YQO2o8dbJ0c9sVdyEbBq1+E2HcjioMZA==}
     engines: {node: '>=20.19'}
 
+  '@tanstack/store@0.11.2':
+    resolution: {integrity: sha512-sJ4mjol8uQsHV0gOJzzjwXfh2Fwm+Sz0+8deqiTm4jGbMdjzNSW+xZCFm0kUa870uhd8yi+DpKnZb5Kc4apa0Q==}
+
   '@tanstack/store@0.9.3':
     resolution: {integrity: sha512-8reSzl/qGWGGVKhBoxXPMWzATSbZLZFWhwBAFO9NAyp0TxzfBP0mIrGb8CP8KrQTmvzXlR/vFPPUrHTLBGyFyw==}
 
-  '@tanstack/table-core@8.21.3':
-    resolution: {integrity: sha512-ldZXEhOBb8Is7xLs01fR3YEc3DERiz5silj8tnGkFZytt1abEvl/GhUmCE0PMLaMPTa3Jk4HbKmRlHmu+gCftg==}
-    engines: {node: '>=12'}
+  '@tanstack/table-core@9.3.1':
+    resolution: {integrity: sha512-zQvlxSNi2qGM3L4jh85Z6hqMfdIR5qOfD9KHOU32nuKFJGN0RlJ7UvV1lsPb1fPVhpFYI0VP3jJGxLdLDpTKjQ==}
+    engines: {node: '>=20'}
+
+  '@tanstack/virtual-core@3.19.6':
+    resolution: {integrity: sha512-CsTW892z23gy7IyxYTTorVu1uZWB+0N349rSMgKz4rFLPpLza7F7TpcCKeI5iUAwYQCt8QUlOU67J+KXCxtpGw==}
 
   '@tanstack/virtual-file-routes@1.162.0':
     resolution: {integrity: sha512-uhOeFyxLcU41HzvrxsGpiWdcMbScY1EDgbZ5K7DVRMYInbLYWAC0EA/kx9wXAoSM8q82bUG2hRl8+EAjE6XAbA==}
@@ -5246,6 +5309,38 @@ snapshots:
 
   '@date-fns/tz@1.5.0': {}
 
+  '@dnd-kit/accessibility@3.1.1(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+      tslib: 2.8.1
+
+  '@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@dnd-kit/accessibility': 3.1.1(react@19.2.7)
+      '@dnd-kit/utilities': 3.2.2(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      tslib: 2.8.1
+
+  '@dnd-kit/modifiers@9.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@dnd-kit/core': 6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/utilities': 3.2.2(react@19.2.7)
+      react: 19.2.7
+      tslib: 2.8.1
+
+  '@dnd-kit/sortable@10.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@dnd-kit/core': 6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/utilities': 3.2.2(react@19.2.7)
+      react: 19.2.7
+      tslib: 2.8.1
+
+  '@dnd-kit/utilities@3.2.2(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+      tslib: 2.8.1
+
   '@drizzle-team/brocli@0.10.2': {}
 
   '@emnapi/core@1.11.1':
@@ -6391,6 +6486,13 @@ snapshots:
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
 
+  '@tanstack/react-store@0.11.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@tanstack/store': 0.11.2
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      use-sync-external-store: 1.6.0(react@19.2.7)
+
   '@tanstack/react-store@0.9.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
       '@tanstack/store': 0.9.3
@@ -6398,9 +6500,17 @@ snapshots:
       react-dom: 19.2.7(react@19.2.7)
       use-sync-external-store: 1.6.0(react@19.2.7)
 
-  '@tanstack/react-table@8.21.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@tanstack/react-table@9.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
-      '@tanstack/table-core': 8.21.3
+      '@tanstack/react-store': 0.11.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@tanstack/table-core': 9.3.1
+      react: 19.2.7
+    transitivePeerDependencies:
+      - react-dom
+
+  '@tanstack/react-virtual@3.14.21(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@tanstack/virtual-core': 3.19.6
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
 
@@ -6507,9 +6617,15 @@ snapshots:
       - vite-plugin-solid
       - webpack
 
+  '@tanstack/store@0.11.2': {}
+
   '@tanstack/store@0.9.3': {}
 
-  '@tanstack/table-core@8.21.3': {}
+  '@tanstack/table-core@9.3.1':
+    dependencies:
+      '@tanstack/store': 0.11.2
+
+  '@tanstack/virtual-core@3.19.6': {}
 
   '@tanstack/virtual-file-routes@1.162.0': {}
 
@@ -6682,21 +6798,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
-  '@vitest/mocker@4.1.10(vite@8.1.5(@types/node@22.20.1)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1))':
+  '@vitest/mocker@4.1.10(vite@8.1.5(@types/node@22.20.1)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1))':
     dependencies:
       '@vitest/spy': 4.1.10
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 8.1.5(@types/node@22.20.1)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)
-
-  '@vitest/mocker@4.1.10(vite@8.1.5(@types/node@24.13.3)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1))':
-    dependencies:
-      '@vitest/spy': 4.1.10
-      estree-walker: 3.0.3
-      magic-string: 0.30.21
-    optionalDependencies:
-      vite: 8.1.5(@types/node@24.13.3)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1)
+      vite: 8.1.5(@types/node@22.20.1)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1)
 
   '@vitest/mocker@4.1.10(vite@8.1.5(@types/node@24.13.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1))':
     dependencies:
@@ -9145,7 +9253,7 @@ snapshots:
 
   vary@1.1.2: {}
 
-  vite@8.1.5(@types/node@22.20.1)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1):
+  vite@8.1.5(@types/node@22.20.1)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1):
     dependencies:
       lightningcss: 1.32.0
       picomatch: 4.0.5
@@ -9154,20 +9262,6 @@ snapshots:
       tinyglobby: 0.2.17
     optionalDependencies:
       '@types/node': 22.20.1
-      esbuild: 0.28.1
-      fsevents: 2.3.3
-      jiti: 2.7.0
-      tsx: 4.23.1
-
-  vite@8.1.5(@types/node@24.13.3)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1):
-    dependencies:
-      lightningcss: 1.32.0
-      picomatch: 4.0.5
-      postcss: 8.5.19
-      rolldown: 1.1.5
-      tinyglobby: 0.2.17
-    optionalDependencies:
-      '@types/node': 24.13.3
       esbuild: 0.27.7
       fsevents: 2.3.3
       jiti: 2.7.0
@@ -9187,10 +9281,10 @@ snapshots:
       jiti: 2.7.0
       tsx: 4.23.1
 
-  vitest@4.1.10(@types/node@22.20.1)(vite@8.1.5(@types/node@22.20.1)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)):
+  vitest@4.1.10(@types/node@22.20.1)(vite@8.1.5(@types/node@22.20.1)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1)):
     dependencies:
       '@vitest/expect': 4.1.10
-      '@vitest/mocker': 4.1.10(vite@8.1.5(@types/node@22.20.1)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1))
+      '@vitest/mocker': 4.1.10(vite@8.1.5(@types/node@22.20.1)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1))
       '@vitest/pretty-format': 4.1.10
       '@vitest/runner': 4.1.10
       '@vitest/snapshot': 4.1.10
@@ -9207,40 +9301,13 @@ snapshots:
       tinyexec: 1.2.4
       tinyglobby: 0.2.17
       tinyrainbow: 3.1.0
-      vite: 8.1.5(@types/node@22.20.1)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)
+      vite: 8.1.5(@types/node@22.20.1)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 22.20.1
     transitivePeerDependencies:
       - msw
 
-  vitest@4.1.10(@types/node@24.13.3)(vite@8.1.5(@types/node@24.13.3)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1)):
-    dependencies:
-      '@vitest/expect': 4.1.10
-      '@vitest/mocker': 4.1.10(vite@8.1.5(@types/node@24.13.3)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1))
-      '@vitest/pretty-format': 4.1.10
-      '@vitest/runner': 4.1.10
-      '@vitest/snapshot': 4.1.10
-      '@vitest/spy': 4.1.10
-      '@vitest/utils': 4.1.10
-      es-module-lexer: 2.3.1
-      expect-type: 1.4.0
-      magic-string: 0.30.21
-      obug: 2.1.4
-      pathe: 2.0.3
-      picomatch: 4.0.5
-      std-env: 4.2.0
-      tinybench: 2.9.0
-      tinyexec: 1.2.4
-      tinyglobby: 0.2.17
-      tinyrainbow: 3.1.0
-      vite: 8.1.5(@types/node@24.13.3)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.1)
-      why-is-node-running: 2.3.0
-    optionalDependencies:
-      '@types/node': 24.13.3
-    transitivePeerDependencies:
-      - msw
-
   vitest@4.1.10(@types/node@24.13.3)(vite@8.1.5(@types/node@24.13.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)):
     dependencies:
       '@vitest/expect': 4.1.10