@ixfx/components 0.13.2 → 0.13.3

package/docs-user/data-grid.md

@@ -112,6 +112,13 @@ grid.getRowKey = (row, i) => row.key ?? row.id ?? String(i);
 
 Reassign `rows` to update. Sorting is derived from `sortState`.
 
+The sorted / filtered / grouped row model is only re-derived when one of its
+inputs is **reassigned** — `rows`, `sortState`, `columns`, `filterPredicate`,
+`groupBy`, `groupLabel`, `getRowKey` (or a group is collapsed). Scroll, hover,
+selection and edit updates skip it, so they cost O(visible rows), not O(rows).
+Mutating a row object in place and calling `requestUpdate()` re-renders the
+cell but does not re-filter, re-group or re-sort — reassign `rows` for that.
+
 When the row set changes without a wholesale replace — rows spliced in, rows
 filtered out — the new rows fade in and, for ~0.3s afterwards, every row slides
 to its new position instead of snapping (so an inserted row's neighbours make
@@ -136,6 +143,63 @@ over the appended slice only. When a sort is active the new rows show unsorted
 for one frame, then a single coalesced re-sort runs. Scroll position, selection
 and cursor are preserved across the append.
 
+### Performance
+
+**Any change to `data-grid.ts` that touches `willUpdate`, `render`, the row
+model (`_rebuildFlat`, sorting, grouping, filtering), scrolling or
+`appendRows` should be checked with both tools below.** The per-frame paths are
+easy to make O(rows) by accident: before these guards existed, one stray
+rebuild-per-update made scrolling 50k grouped rows cost ~146 ms a frame.
+
+There are two layers:
+
+| | `data-grid.perf.test.ts` | `pnpm bench:data-grid` |
+|---|---|---|
+| Runs | with `pnpm test` (happy-dom) | against the dev server, in headless Chrome |
+| Measures | grid JS work: call counts and 2k → 20k scaling | real main-thread ms per frame: script + style/layout/paint |
+| Catches | O(n) / O(n²) creeping into scroll, hover, add/remove | real-browser slowdowns, including rendering cost |
+| Use it | always (it's part of CI) | before / after any perf-sensitive change |
+
+**Unit-level guards** — `data-grid.perf.test.ts` asserts that a scroll frame /
+hover does work proportional to the visible window (flat from 2k to 20k rows,
+including sorted / grouped / filtered), that a sub-row scroll doesn't
+re-render, and that adding / removing rows scales at most linearly. They use
+call counts and size ratios rather than absolute times, so they don't flake on
+slow machines. `pnpm test:perf` prints the per-scenario timings.
+
+**Real-browser benchmark** — `scripts/bench/data-grid.ts` drives
+`demo/data-grid.html` in an isolated headless Chrome (its own temp profile; set
+`CHROME_PATH` if Chrome isn't in a standard location). It needs the dev server
+running (`pnpm start`). For 1k / 50k rows, plain and grouped by `status`, it
+reports:
+
+- `scroll script` / `scroll render` — main-thread ms per frame at 40 px/frame
+  (wheel / trackpad), from a timeline trace.
+- `jump script` / `jump render` — the same at 1200 px/frame (scrollbar drag /
+  fling: every row in the window is replaced each frame).
+- `insert3Ms`, `removeOneMs`, `appendRows500Ms`, `selectMs` — median time from
+  the call until Lit has rendered and style + layout are flushed.
+
+Workflow — record a baseline on the unchanged code, make the change, compare:
+
+```sh
+pnpm bench:data-grid --out /tmp/grid-base.json      # before
+pnpm bench:data-grid --compare /tmp/grid-base.json  # after
+```
+
+`--compare` prints each metric's % change and lists anything over
+`--threshold` (default 50%, and never changes under 1 ms — run-to-run noise is
+~±25%). Add `--fail-on-regression` to exit non-zero. Other options: `--rows
+1000,50000`, `--group-by status` (empty to skip grouped runs), `--url`.
+Baselines are machine-specific, so keep them local rather than committing
+them. The dev server runs Lit in dev mode, so absolute numbers are higher than
+a production build — compare runs against each other, not against a budget.
+
+Reference numbers (M-series Mac, dev mode, 50k rows): a smooth-scroll frame is
+~1.5 ms script + ~2 ms render; a jump frame ~6 ms + ~4.5 ms; add / remove one
+row ~7 ms; select ~1 ms. All flat across row count and grouping, except
+add / remove, which is linear in rows.
+
 ---
 
 ## Selection & interaction
@@ -395,9 +459,9 @@ Demo: `Score` is random float `0–100` with 0–3 decimals, `align:'right'`, `f
 
 Gear menu (`ixfx-menu-trigger` placement `bottom-end`, `inset-area: block-end span-inline-end`) lists `Columns` (check-items) and `Group by` (radio). Toggle visibility via `col.visible=false` or menu. Event: `datagrid-column-visibility` `{key, visible}`.
 
-`column-menu` attribute: `auto` (default) renders the gear menu; `none`
-suppresses it entirely. `col.visible` + `datagrid-column-visibility` still give
-full external control, so `none` lets a host own the column-visibility UI.
+`column-menu` attribute: `none` (default) hides the gear menu; `auto` opts in to
+rendering it. `col.visible` + `datagrid-column-visibility` give full external
+control, so a host can own the column-visibility UI.
 
 Other events: `datagrid-column-reorder` `{from,to,columns}`, `datagrid-column-resize` `{key,width}`, `datagrid-cell-click` `{rowKey,colKey,rowIndex,colIndex}`, `datagrid-cell-edit` `{rowKey,colKey,oldValue,newValue}`.
 
@@ -410,12 +474,18 @@ Grid is focusable (`tabindex=0`). When not editing:
 | Key | Action |
 |---|---|
 | `ArrowDown/Up` | Move tickled cursor, scroll into view; with `Shift` + `vscode`/`standard` extends range |
-| `Home/End` | First/last |
+| `Home/End` | First/last data row |
 | `Enter` | If `editability=user` and row has editable cell, open editor (prefers `lastClickedCell`); else select row |
 | `Space` | Toggle selection |
 | `Escape` | Clear selection (or cancel edit) |
 | `Ctrl/Cmd+A` | Select all (clamped to anchor group if `!crossGroupSelection`) |
 
+The cursor skips group header rows. Moving it scrolls synchronously, so the target row is rendered in the same update, and moving up onto the first row of a group reveals its header.
+
+**Accessibility:** the grid is `role="grid"` with `aria-rowcount` / `aria-colcount`; header cells are `columnheader` (with `aria-sort`), rows carry `aria-rowindex` (absolute, so it stays correct while windowed) and `aria-selected`, and group rows have a `rowheader` with `aria-expanded`.
+
+**Editing while scrolling:** the row being edited is pinned in the DOM even if scrolled out of the window, so its input keeps focus and the edit isn't lost. It is not listed in `renderedKeys()`.
+
 ---
 
 ## Incremental search

package/docs-user/detail-list.md

@@ -40,6 +40,7 @@ Selection semantics match `ixfx-vertical-list` — same modes, same `list-*` eve
     - [Streaming provider](#streaming-provider)
   - [CSS variables](#css-variables)
   - [CSS parts](#css-parts)
+  - [Performance](#performance)
 
 ---
 
@@ -168,6 +169,13 @@ list.formatter = (item, index) => {
 };
 ```
 
+Reassigning `items` keeps the row of every object that is still in the new
+array (matched by identity), so `list.items = [...list.items, next]` creates
+one `<li>` rather than rebuilding the list — selection, cursor and scroll stay
+put, and the new row animates in like `addItem()`. Pass new objects (or change
+`displayProperty`, `formatter`, …) to rebuild rows. With a `formatter`, a row
+is only kept at the same index, since the formatter receives the index.
+
 Retrieve the original data for an element:
 
 ```typescript
@@ -625,3 +633,60 @@ ixfx-detail-list::part(search-overlay) {
   background: rgba(0, 0, 0, 0.8);
 }
 ```
+
+---
+
+## Performance
+
+Every item is a real `<li>` in the light DOM — there is no virtual window —
+so the per-frame and per-hover paths must never scale with the item count.
+They don't: scrolling binary-searches the column flow (`visibleKeys()` reads
+O(log n) rects), the column grid used for keyboard navigation is measured
+lazily and re-validated with a few probe reads, hover and selection update
+only the rows that changed, and each row has `contain: paint` so restyling
+one row doesn't repaint the list.
+
+`contain: paint` means row content that overflows the row box is clipped to
+it (and each row is its own stacking context). Rows are fixed-size, so this
+only matters if a badge or custom node is wider than the column. It costs
+~0.6 ms more compositor work per scroll frame at 10k rows and saves ~30 ms of
+paint per hover / selection change.
+
+**Any change to `detail-list.ts` that touches item caching, geometry,
+`_syncItemStates`, scrolling or the add / remove paths should be checked with
+both tools below.** At 10k items these paths used to cost ~30 ms of script per
+scroll frame and 180 ms per arrow-key press.
+
+| | `detail-list.perf.test.ts` (+ `detail-list-geometry.test.ts`) | `pnpm bench:detail-list` |
+|---|---|---|
+| Runs | with `pnpm test` (happy-dom, stubbed layout) | against the dev server, in headless Chrome |
+| Measures | work counters: layout reads per scroll / keypress, rows created per append, attribute writes per hover; 1k → 10k scaling | real main-thread ms: script + style / layout / paint |
+| Catches | O(n) creeping into scroll, hover, navigation, add / remove; stale caches | real-browser slowdowns, including paint |
+| Use it | always (part of CI) | before / after any perf-sensitive change |
+
+**Real-browser benchmark** — `scripts/bench/detail-list.ts` drives
+`#list-objects` in `demo/detail-list.html` with 1k / 10k generated items,
+plain and grouped by `kind`, and reports:
+
+- `scroll` / `jump` `script` + `render` — main-thread ms per frame scrolling
+  the columns at 40 px / 1200 px per frame, from a timeline trace.
+- `hover`, `keyNav`, `select`, `addItem`, `removeItem`, `itemsAppend`
+  (`items = [...items, x]`) — main-thread ms per operation (script + render),
+  run with `prefers-reduced-motion: reduce` so row animations don't count.
+
+Record a baseline on the unchanged code, make the change, compare:
+
+```sh
+pnpm start                                           # dev server, separate terminal
+pnpm bench:detail-list --out /tmp/list-base.json     # before
+pnpm bench:detail-list --compare /tmp/list-base.json # after
+```
+
+`--compare` lists metrics over `--threshold` (default 50%, ignoring changes
+under 1 ms); add `--fail-on-regression` to exit non-zero. Other options:
+`--items 1000,10000`, `--group-by kind` (empty to skip grouped runs), `--url`.
+Baselines are machine-specific and the dev server runs Lit in dev mode, so
+compare runs against each other rather than against fixed budgets. The data
+grid has the same tooling (`pnpm bench:data-grid`); shared harness code is in
+`scripts/bench/`.
+

package/docs-user/grid-list.md

@@ -21,8 +21,9 @@ single vertical column, or a horizontally-scrolling strip.
 10. [Keyboard](#keyboard)
 11. [Grouping](#grouping)
 12. [Virtualisation](#virtualisation)
-13. [CSS parts](#css-parts)
-14. [Choosing a list component](#choosing-a-list-component)
+13. [Performance](#performance)
+14. [CSS parts](#css-parts)
+15. [Choosing a list component](#choosing-a-list-component)
 
 ---
 
@@ -46,8 +47,10 @@ single vertical column, or a horizontally-scrolling strip.
 ```
 
 Items are **light-DOM children**. Each is projected into its own virtualised
-cell via a named `<slot>`. Add or remove children at any time — a
-`MutationObserver` picks the change up and re-renders.
+cell via a named `<slot>`: the list sets each rendered item's `slot` attribute
+(and removes it from items outside the window), so don't set `slot` on items
+yourself. Add or remove children at any time — a `MutationObserver` picks the
+change up and re-renders.
 
 ```typescript
 import type { GridListElement } from '@ixfx/components/grid-list';
@@ -463,6 +466,13 @@ grid.visibleKeys();     // keys strictly intersecting the viewport (no overscan)
 keyless light-DOM items (auto-assigned internally) are omitted from
 `renderedKeys()` / `visibleKeys()` / `selectedKeys`.
 
+### Accessibility
+
+Cells are `role="option"` with `aria-setsize` (the filtered, non-collapsed count)
+and `aria-posinset`, so assistive technology sees the true list size even though
+only a window of cells is in the DOM. Group headers are `role="presentation"`.
+A container resize that changes the column count keeps the centre item in view.
+
 ### Hidden containers
 
 `refreshLayout()` re-reads the viewport after an ancestor's visibility or size
@@ -491,6 +501,73 @@ it's suppressed under `prefers-reduced-motion: reduce`. Duration:
 
 ---
 
+## Performance
+
+**Any change to `grid-list.ts`, `grid-list-source.ts` or `grid-list-layout.ts`
+that touches `render`, the per-cell template, the item source, scrolling,
+cursor movement or item insertion should be checked with `pnpm bench:grid-list`.**
+A per-frame path that quietly becomes O(items) is easy to introduce — see the
+list at the end of this section for the ones that have bitten before.
+
+`scripts/bench/grid-list.ts` drives `demo/grid-list.html` in an isolated
+headless Chrome (its own temp profile; set `CHROME_PATH` if Chrome isn't in a
+standard location). It needs the dev server running (`pnpm start`). It mounts
+its own full-window list in **data mode** (adapter + `items`, default 5k and 50k
+items) and **element mode** (light-DOM children, default 2k and 10k), and
+reports main-thread ms from a timeline trace:
+
+- `scroll` — script + render per frame at 40 px/frame (wheel / trackpad).
+- `jump` — the same at 1200 px/frame (scrollbar drag / fling: the whole window
+  is replaced every frame).
+- `key arrow` / `key page` / `key jump` — script + render per key press for
+  Arrow keys, PageUp/PageDown, and End/Home (cursor crosses the whole list).
+- `append1`, `append100`, `insertMid`, `removeMid` — script + render per dynamic
+  change (data mode: `appendItems` / `items` / `removeItems`; element mode:
+  light-DOM `append` / `insertBefore` / `remove`). Run with
+  `prefers-reduced-motion` so the 200 ms slide animation isn't measured.
+
+Workflow — record a baseline on the unchanged code, make the change, compare:
+
+```sh
+pnpm bench:grid-list --out /tmp/grid-list-base.json      # before
+pnpm bench:grid-list --compare /tmp/grid-list-base.json  # after
+```
+
+`--compare` prints each metric's % change and lists anything over
+`--threshold` (default 50%, and never changes under 1 ms — run-to-run noise is
+a few %). Add `--fail-on-regression` to exit non-zero. `--data-items 5000,100000`
+and `--element-items 2000,20000` change the sizes. Baselines are
+machine-specific, so keep them local rather than committing them. The dev
+server runs Lit in dev mode, so absolute numbers are higher than a production
+build — compare runs against each other, not against a budget.
+
+Reference numbers (M-series Mac, dev mode; all flat in item count except
+inserts): a smooth-scroll frame ~2–3 ms script + ~2.5 ms render; a jump-scroll
+frame ~5 ms script (data) / ~9–16 ms (element) + ~7 ms render; an Arrow / Page
+key ~2–3 ms + ~3 ms; End / Home ~6 ms (data) / ~9–13 ms (element) + ~7 ms.
+Inserting is O(items): one `appendItems` costs ~5 ms at 5k items and ~21 ms at
+50k (the source and search index are rebuilt, and `items` is copied); the
+element-mode equivalents are ~8 ms at 2k and ~16 ms at 10k.
+
+Things that keep the per-frame paths flat, and that the benchmark guards:
+
+- **Cell recycling.** Cells are keyed by a stable cell id, not the item key, so
+  a cell scrolled out of the window is handed to an item scrolling in rather
+  than destroyed and recreated. (Item-keyed `repeat` gets steadily slower in
+  Chrome when every key in the window is new — a scrollbar drag or fling.) A
+  recycled cell carries the `recycled` class for one render, which disables its
+  transitions so it never animates from the previous item's state or position.
+- **Per-cell slots (element mode).** Each cell has a fixed
+  `<slot name="gl-cell-<id>">`; the item it shows gets a matching `slot`
+  attribute, and items outside the window have none. Renaming slots instead
+  makes the browser re-match every light-DOM child.
+- **The light DOM is only re-read when it changes** (child list, or an item's
+  `hidden` / `data-key` / `data-value`), not on every scroll / hover / cursor
+  update; `data-tickled` / `data-selected` are updated only on the items whose
+  state changed.
+
+---
+
 ## CSS parts
 
 | Part | Element |

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "version": "0.13.2",
-  "generated": "2026-10-01T21:51:41.922Z",
+  "generated": "2026-10-03T23:39:03.024Z",
   "components": [
     {
       "name": "ac-text",

package/docs-user/miller.md

@@ -104,7 +104,9 @@ Explicit multi-select similar to a file manager:
 | Shift+Click | Contiguous range from anchor to item (within same depth) |
 | Cmd/Ctrl+Click | Toggle item without expanding (no anchor change) |
 | Arrow Up/Down | Move focus; re-seats anchor |
-| Shift+Arrow | Extend range from anchor (bootstraps anchor from current position if unset) |
+| Home / End | Move focus to the first / last item in the column |
+| Page Up / Page Down | Move focus up / down by one visible page (clamped to the column) |
+| Shift+Arrow / Home / End / Page keys | Extend range from anchor (bootstraps anchor from current position if unset) |
 | Enter | Select focused item (sets anchor) |
 | Shift+Enter | Extend range to focused item |
 
@@ -118,7 +120,8 @@ Extends `standard` with persistent multi-selection across cursor movement:
 | Shift+Click | Contiguous range from anchor — same as `standard` |
 | Cmd/Ctrl+Click | Toggle item without expanding — same as `standard` |
 | Arrow Up/Down | Move cursor **only** — selection is preserved, anchor is not re-seated |
-| Shift+Arrow | Extend range from anchor — same as `standard` |
+| Home / End / Page Up / Page Down | Move cursor only, as Arrow Up/Down |
+| Shift+Arrow / Home / End / Page keys | Extend range from anchor — same as `standard` |
 | Arrow Right | Expand/navigate into branch — selection is preserved (does not clear) |
 | Enter | Add focused item to selection (sets anchor) |
 | Shift+Enter | Extend range to focused item |
@@ -426,13 +429,66 @@ Miller columns support full keyboard navigation when the component has focus:
 | `Arrow Down` | Move focus to next item in column |
 | `Arrow Right` | Select focused item and open its children (if any) |
 | `Arrow Left` | Go back to previous column |
+| `Home` / `End` | Move focus to the first / last item in the column |
+| `Page Up` / `Page Down` | Move focus up / down by one visible page |
 | `Enter` | Fire `select` event on focused item; in `standard` mode also selects and sets anchor |
-| `Shift+Arrow` | In `standard` mode: extend selection range from anchor |
+| `Shift+Arrow` / `Home` / `End` / `Page` keys | In `standard` mode: extend selection range from anchor |
 | `Shift+Enter` | In `standard` mode: extend selection range to focused item |
 | `Escape` | Cancel pending lazy load / go back one column |
 
 ---
 
+## Performance
+
+**Any change to `miller-base.ts` or `miller-list.ts` that touches `render`,
+the per-item template, selection handling, cursor movement, column opening or
+lazy loading should be checked with `pnpm bench:miller`.** Every update
+re-renders every item in every open column, so an accidental O(items) (or
+O(descendants), in `checked` mode) per-keystroke cost is easy to introduce and
+shows up directly as key-repeat lag.
+
+`scripts/bench/miller.ts` drives `demo/miller.html` in an isolated headless
+Chrome (its own temp profile; set `CHROME_PATH` if Chrome isn't in a standard
+location). It needs the dev server running (`pnpm start`). It mounts its own
+list and runs two scenarios per item count (default 500 and 2000 rows per
+column): `standard`, and `checked` with a loaded 20 × 10 subtree under most
+rows (which the checkbox state scan must walk). It reports:
+
+- `arrow` / `page` / `hover` — main-thread `script` and `render` ms per
+  Arrow Down, Page Up/Down, or hover (from a timeline trace).
+- `resize` — the same, per frame of a column-resize drag.
+- `openMs` — median ms to click a branch whose children are already loaded and
+  render the new column.
+- `lazyOpenMs` — the same for an unloaded branch resolved by an instant
+  `loadChildren`. This exposes any artificial delay in the lazy-load path
+  (clicks must start loading immediately; only keyboard navigation is
+  debounced).
+- `checkToggleMs` — median ms to toggle a branch checkbox (`checked` only).
+
+Workflow — record a baseline on the unchanged code, make the change, compare:
+
+```sh
+pnpm bench:miller --out /tmp/miller-base.json      # before
+pnpm bench:miller --compare /tmp/miller-base.json  # after
+```
+
+`--compare` prints each metric's % change and lists anything over
+`--threshold` (default 50%, and never changes under 1 ms — run-to-run noise is
+a few %). Add `--fail-on-regression` to exit non-zero. `--items 500,5000`
+changes the column sizes. Baselines are machine-specific, so keep them local
+rather than committing them. The dev server runs Lit in dev mode, so absolute
+numbers are higher than a production build — compare runs against each other,
+not against a budget.
+
+Reference numbers (M-series Mac, dev mode, 2000 rows per column, `standard`):
+an Arrow / Page / hover update is ~4 ms script + ~1 ms render; a resize frame
+~9.5 ms render; opening a loaded column ~20 ms, a lazy one ~7 ms. In `checked`
+mode with the 20 × 10 subtrees, key and hover updates are ~11-12 ms and a
+checkbox toggle ~27 ms, because each render scans every visible row's loaded
+subtree.
+
+---
+
 ## Subclassing MillerBaseElement
 
 Create custom column renderers by subclassing `MillerBaseElement`. Override

package/docs-user/tree.md

@@ -11,6 +11,7 @@ Three components share a common `TreeComponent` interface: **`ixfx-tree-list`**,
 1. [Data model](#data-model)
 2. [Properties](#properties)
    - [Custom checkbox (`checkboxRenderer`)](#custom-checkbox-ixfx-tree-list-only--checkboxrenderer)
+   - [Virtualisation](#virtualisation-ixfx-tree-list)
 3. [Selection](#selection)
 4. [Events](#events)
 5. [Keyboard navigation](#keyboard-navigation)
@@ -45,6 +46,8 @@ type TreeNode = {
 
 `TreeNode` is **immutable** — structural changes always produce a new root. Never mutate a node in place; use `TreeDataModel` convenience methods or replace `root` directly.
 
+**Escape hatch for in-place edits.** The component itself fills in `node.children` when lazy-loading, and `TreeController` does the same. If you must edit `node.children` or `node.item` (e.g. an icon) in place, call `el.invalidateStructure()` afterwards. It drops the cached whole-tree indexes (parent map, icon depths, filter matches, checkbox states) and re-renders. Visible rows are re-derived on every update, so ordinary expand / collapse never needs it.
+
 ---
 
 ### Static trees
@@ -140,9 +143,11 @@ These properties are present on all three components (`ixfx-tree-list`, `ixfx-mi
 | `selectedNodes` | `ReadonlySet<TreeNode>` | `{}` | Full selection set (read-only) |
 | `interactionMode` | `TreeInteractionMode` | `'standard'` | How gestures map to selection changes (`ixfx-tree-list` / `ixfx-miller-list` only) |
 | `selectionFilter` | `'none' \| 'leaf' \| 'branch'` | `'leaf'` | Which node kinds can be selected (reflected attribute) |
-| `filterPredicate` | `TreeFilterPredicate \| undefined` | `undefined` | Filter; only nodes returning `true` are shown |
+| `filterPredicate` | `TreeFilterPredicate \| undefined` | `undefined` | Filter; only matching nodes and their ancestors are rendered (non-matching rows are not in the DOM, keyboard navigation, `selectAll` and Shift-range skip them) |
 | `exclusivity` | `'none' \| 'depth' \| 'global'` | `'none'` | Expansion exclusivity (reflected attribute) |
 | `stickyHeaders` (`sticky-headers`) | `boolean` | `true` | VS Code-style sticky headers; set `sticky-headers="false"` to opt out (`ixfx-tree-list` only) |
+| `virtualize` | `'auto' \| 'on' \| 'off'` | `'auto'` | Render only the rows near the viewport; `auto` switches on above `virtualizeThreshold` visible rows (`ixfx-tree-list` only). See [Virtualisation](#virtualisation-ixfx-tree-list) |
+| `virtualizeThreshold` (`virtualize-threshold`) | `number` | `200` | Visible-row count above which `virtualize="auto"` windows the list |
 
 ### `interactionMode` (`ixfx-tree-list` / `ixfx-miller-list`)
 
@@ -220,6 +225,51 @@ On by default: while scrolling vertically, the ancestors of the top-visible row
 - An ancestor that is itself still visible is never duplicated in the header.
 - Style via `--tree-sticky-bg`, `--tree-sticky-border`, `--tree-sticky-shadow`, and the `sticky-headers` / `sticky-header` parts.
 
+### Virtualisation (`ixfx-tree-list`)
+
+A node with 10,000 children needs only about 25 `<li>` elements in the DOM. When
+the number of visible rows (expanded rows, after any filter) exceeds
+`virtualize-threshold` (default 200), `ixfx-tree-list` renders only the rows
+near the viewport, plus 5 rows of overscan either side. Two spacer `<li>`s
+hold the scroll height for the rest. Force it with `virtualize="on"` or disable
+it with `virtualize="off"`; `data-virtual` is set on the host while the list is
+windowed.
+
+```html
+<ixfx-tree-list virtualize="on" style="--tree-item-height: 28px"></ixfx-tree-list>
+```
+
+Everything is keyed by node, not by DOM element, so these behave exactly as
+they do without windowing and cover rows that are not rendered:
+
+- **Cursor, selection, `selectAll`, Shift-range** and **checkbox states**.
+- **Keyboard**: arrows move across the whole list, and Home / End / PageUp / PageDown
+  jump by index. The cursor row is scrolled into view in the same frame, so it
+  is never missing.
+- **Incremental search**: `navigate`, `select` and `filter` modes search the whole tree.
+  Match highlights are repainted as the window moves.
+- **`navigateTo` / `revealKey`**: expand ancestors and scroll to the row.
+- **Drag and drop**: drop targets are computed from the layout, so auto-scroll while dragging works.
+- **Sticky headers**: found by arithmetic, with no per-row measuring.
+
+Constraints while windowed:
+
+- Every row must render at the same height. The list measures a rendered row's
+  box (which includes its padding and border, so it is taller than
+  `--tree-item-height` alone) and its top margin, and places rows by that stride.
+  Keep labels single-line (they truncate with an ellipsis) and custom row content within the row.
+- **Expand / collapse and insert / remove rows do not animate.** The
+  fading "ghost" rows need variable heights. Below the threshold, or with
+  `virtualize="off"`, animation works as before.
+- The sticky-header overlay is taken out of the layout flow so it cannot shift row positions.
+- Rows outside the window do not exist in the DOM. Use the component's API
+  (`getNodes()`, `selectedNodes`, `revealKey()`) rather than `querySelector` to find a node.
+
+Every row gets `aria-level`, `aria-setsize` and `aria-posinset`, counted over
+**all** siblings (those matching the filter), so assistive technology
+reports "5,000 of 10,000" even though most siblings are not in the DOM. The list
+also exposes `aria-rowcount`.
+
 ---
 
 ## Selection
@@ -250,6 +300,8 @@ el.deselectAll();
 | `checked` | Checks the checkbox of each visible node (recursively toggles descendants) | Unchecks each visible node |
 | All other modes | Adds every visible selectable node to the selection | Clears the selection |
 
+While a `filterPredicate` is active, `selectAll()` / `deselectAll()` and Shift-range selection cover only the rows that are shown (as in `ixfx-vertical-list`).
+
 Both methods dispatch a single `select` event with the full old and new selection sets. `selectAll` respects `selectionFilter` — only nodes that pass the filter are selected.
 
 ### Reading the selection
@@ -423,9 +475,12 @@ The element must be focused (click it or tab to it) before keyboard navigation w
 | `Arrow Right` (on leaf) | No-op |
 | `Arrow Left` (on expanded branch) | Collapse branch |
 | `Arrow Left` (on leaf or collapsed branch) | Move to parent |
+| `Home` / `End` | Move cursor to the first / last visible item |
+| `Page Up` / `Page Down` | Move cursor up / down by about one viewport |
 | `Enter` | Select and activate focused item |
 | `Escape` | Cancel in-flight lazy load |
 
+Holding `Shift` with any movement key extends the range selection (in `standard` / `vscode` modes).
 Moving the cursor fires a `tickle` event. Pressing Enter fires `select` then `activate`.
 
 ### `ixfx-miller-list`
@@ -540,6 +595,8 @@ Each tree-like component must implement the following. These are enforced by the
 - [ ] `role="tree"` on the outermost interactive container
 - [ ] `aria-label` or `aria-labelledby` to name the tree
 
+`ixfx-tree-list` sets all of the item attributes below, including `aria-setsize` / `aria-posinset` (see [Virtualisation](#virtualisation-ixfx-tree-list)); the checklist is still outstanding for the other tree components.
+
 **Each item element**
 
 - [ ] `role="treeitem"`
@@ -573,6 +630,9 @@ at once the animation is skipped, as it is entirely under
 `prefers-reduced-motion: reduce`. Duration: `--ixfx-list-item-move-duration`
 (default `200ms`).
 
+Typing in a filter search does not animate, and neither does a windowed
+(virtualised) list: see [Virtualisation](#virtualisation-ixfx-tree-list).
+
 ---
 
 ## CSS variables
@@ -603,7 +663,8 @@ These are set by the global theme and inherited by all tree components.
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `--tree-indent` | `20px` | Indentation per depth level |
-| `--tree-item-height` | `30px` | Height of each row |
+| `--tree-item-height` | `30px` | Content height of each row (padding and border add to the rendered box) |
+| `--tree-item-gap` | `1px` | Margin above each row |
 | `--tree-caret-size` | `30px` | Expand/collapse caret size |
 | `--ixfx-list-item-move-duration` | `200ms` | Row enter / leave animation duration |
 | `--tree-drop-line` | `var(--accent)` | Colour of the before/after insertion line + nub |

package/docs-user/vertical-list.md

@@ -588,6 +588,8 @@ The element must be focused (click it or tab to it) before keyboard navigation w
 |---|---|
 | `Arrow Down` | Move cursor to next visible item |
 | `Arrow Up` | Move cursor to previous visible item |
+| `Home` / `End` | Move cursor to the first / last item (across the whole list, including pooled rows when virtualized) |
+| `Page Down` / `Page Up` | Move cursor by one viewport of rows |
 | `Enter` | Activate the cursor item — fires `list-item-click` then `list-activate`; selects the item (except in `manual` mode) |
 | `Space` | Toggle selection on the cursor item |
 | `Shift+Arrow Down/Up` | Extend range from anchor (`vscode` mode only) |
@@ -756,7 +758,13 @@ dispatch. Mirrors `ixfx-grid-list`'s `grid-list-viewport-change`.
 
 - **Drag-select is disabled** — the window shifts under a drag, so the marquee band can't be tracked reliably.
 - **Incremental-search `filter` mode is excluded** — it collapses rows via `hidden`, corrupting the fixed-stride geometry. `navigate` and `select` modes still work.
-- **Keyboard navigation stays within the rendered window** — scroll first.
+
+### Search, keyboard and accessibility while virtualized
+
+- **Incremental search covers every row**, rendered or pooled. Matches in `navigate` / `select` mode don't change as you scroll, and highlights repaint as the window moves.
+- **Keyboard navigation spans the whole list** (arrows, Home/End, Page Up/Down, `item-wrap="wrap"`). The cursor is scrolled to the nearest edge only when it would otherwise leave the viewport.
+- **Native multi-row drag** includes selected rows that are currently pooled; `ListDragEntry.index` is the row's position in the full list.
+- **Accessibility:** attached rows get `aria-setsize` / `aria-posinset` for the whole list. Rows without a `role` get `role="option"` and `aria-selected`; a role you set yourself is preserved. The inner list is `role="listbox"` unless the host has its own `role`.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",
@@ -216,6 +216,11 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "bench:grid-list": "node --experimental-strip-types ./scripts/bench/grid-list.ts",
+    "bench:miller": "node --experimental-strip-types ./scripts/bench/miller.ts",
+    "bench:data-grid": "node --experimental-strip-types ./scripts/bench/data-grid.ts",
+    "bench:detail-list": "node --experimental-strip-types ./scripts/bench/detail-list.ts",
+    "test:perf": "PERF_REPORT=1 vitest run --reporter=verbose .perf.test",
     "start": "vite serve",
     "dev": "vite serve",
     "lint": "eslint",