@svgrid/grid 3.0.8 → 3.0.9

package/src/virtualization/column-virtualizer.ts

@@ -7,6 +7,10 @@ export function createColumnVirtualizer(input: {
   viewportWidth: number
   scrollOffset?: number
   overscan?: number
+  /** Columns kept behind the scroll direction; defaults to `overscan`. */
+  overscanBehind?: number
+  /** Fewest columns left ahead of a scroll before the window moves. */
+  overscanMin?: number
   /** Either a uniform size (number) or a per-column size function. */
   estimateSize?: number | ColumnSizeEstimator
 }) {
@@ -16,6 +20,8 @@ export function createColumnVirtualizer(input: {
     viewportHeight: input.viewportWidth,
     scrollOffset: input.scrollOffset ?? 0,
     overscan: input.overscan ?? 4,
+    overscanBehind: input.overscanBehind,
+    overscanMin: input.overscanMin,
   })
 
   return {

package/src/virtualization/types.ts

@@ -16,8 +16,28 @@ export type VirtualizerOptions = {
    */
   estimateSize: number | ((index: number) => number)
   overscan?: number
+  /**
+   * Items kept on the side the scroll is moving away from (`overscan` is kept
+   * ahead of it). Defaults to `overscan`, a symmetric window. Before the
+   * first scroll there is no direction and both sides get `overscan`.
+   */
+  overscanBehind?: number
+  /**
+   * Keep the rendered window while a scroll leaves at least this many items
+   * rendered ahead of it, and move the window only when the scroll runs past
+   * that: the window is then rebuilt with the full `overscan` ahead, so it
+   * moves `overscan - overscanMin + 1` items at a time instead of one. Each
+   * move costs about the same whether one item enters or several, so fewer,
+   * larger moves are less work, and the scroll frames in between change
+   * nothing. A window built at rest, or after a jump to items outside the
+   * rendered window, carries `overscanMin` instead of `overscan`. Undefined
+   * moves the window on every item boundary, always with `overscan`.
+   */
+  overscanMin?: number
   viewportHeight: number
   scrollOffset?: number
+  /** Internal: the sign of the last scroll movement (-1, 0, 1). */
+  scrollDirection?: number
 }
 
 export type VirtualizerState = {

package/src/virtualization/virtualizer.test.ts

@@ -89,3 +89,155 @@ describe('virtualizer', () => {
     expect(calls).toBe(afterBuild)
   })
 })
+
+describe('virtualizer: overscanBehind', () => {
+  // 1,000 items of 10px in a 100px viewport: items 0-9 visible at offset 0.
+  const make = () =>
+    createVirtualizer({ count: 1000, estimateSize: 10, viewportHeight: 100, overscan: 3, overscanBehind: 1 })
+
+  it('keeps the full overscan on both sides before any scroll', () => {
+    // Created at offset 500: no movement yet, so no direction.
+    const fresh = createVirtualizer({ count: 1000, estimateSize: 10, viewportHeight: 100, overscan: 3, overscanBehind: 1, scrollOffset: 500 })
+    const items = fresh.getVirtualItems()
+    expect(items[0]!.index).toBe(47)
+    expect(items.at(-1)!.index).toBe(50 + 10 + 3)
+  })
+
+  it('puts the overscan ahead of a forward scroll and one item behind it', () => {
+    const v = make()
+    v.setScrollOffset(500)
+    const items = v.getVirtualItems()
+    expect(items[0]!.index).toBe(50 - 1)
+    expect(items.at(-1)!.index).toBe(60 + 3)
+  })
+
+  it('flips when the scroll turns around', () => {
+    const v = make()
+    v.setScrollOffset(500)
+    v.setScrollOffset(400)
+    const items = v.getVirtualItems()
+    expect(items[0]!.index).toBe(40 - 3)
+    expect(items.at(-1)!.index).toBe(50 + 1)
+  })
+
+  it('defaults to a symmetric window', () => {
+    const v = createVirtualizer({ count: 1000, estimateSize: 10, viewportHeight: 100, overscan: 3 })
+    v.setScrollOffset(500)
+    const items = v.getVirtualItems()
+    expect(items[0]!.index).toBe(47)
+    expect(items.at(-1)!.index).toBe(63)
+  })
+})
+
+describe('virtualizer: overscanMin', () => {
+  // 1,000 items of 10px in a 100px viewport; at offset o the visible items
+  // are o/10 .. o/10 + 10.
+  const make = (estimateSize: number | ((i: number) => number) = 10) =>
+    createVirtualizer({ count: 1000, estimateSize, viewportHeight: 100, overscan: 3, overscanBehind: 1, overscanMin: 1 })
+
+  const range = (v: ReturnType<typeof make>) => {
+    const items = v.getVirtualItems()
+    return [items[0]!.index, items.at(-1)!.index]
+  }
+
+  it('renders overscanMin around the visible items at rest and after a jump', () => {
+    // At rest: one item on each side of visible 0..10.
+    const v = make()
+    expect(range(v)).toEqual([0, 11])
+    // Visible 50..60 shares nothing with the window: a jump, so one item
+    // ahead and one behind, as a thumb drag lands.
+    v.setScrollOffset(500)
+    expect(range(v)).toEqual([49, 61])
+    const fresh = createVirtualizer({ count: 1000, estimateSize: 10, viewportHeight: 100, overscan: 3, overscanBehind: 1, overscanMin: 1, scrollOffset: 500 })
+    expect(range(fresh)).toEqual([49, 61])
+  })
+
+  it('keeps the window while one item is left ahead, then moves it three at a time', () => {
+    const v = make()
+    let emits = 0
+    v.subscribe(() => (emits += 1))
+    // Visible end 11 leaves nothing ahead of [0, 11]: the window moves on
+    // with the full overscan ahead.
+    v.setScrollOffset(10)
+    const moved = v.getVirtualItems()
+    expect(range(v)).toEqual([0, 14])
+    expect(emits).toBe(1)
+
+    // Visible ends 12 and 13: item 14 is still rendered ahead of them.
+    v.setScrollOffset(20)
+    v.setScrollOffset(30)
+    expect(v.getVirtualItems()).toBe(moved)
+    expect(emits).toBe(1)
+
+    // Visible end 14 leaves nothing ahead: the window moves by three.
+    v.setScrollOffset(40)
+    expect(range(v)).toEqual([3, 17])
+    expect(emits).toBe(2)
+    v.setScrollOffset(50)
+    v.setScrollOffset(60)
+    expect(emits).toBe(2)
+    v.setScrollOffset(70)
+    expect(range(v)).toEqual([6, 20])
+    expect(emits).toBe(3)
+  })
+
+  it('works the same with per-item sizes', () => {
+    // The per-item path counts visible 0..9 at offset 0, not 0..10: an item
+    // starting exactly at the viewport's end is not in it.
+    const v = make(() => 10)
+    expect(range(v)).toEqual([0, 10])
+    v.setScrollOffset(10)
+    const moved = v.getVirtualItems()
+    expect(range(v)).toEqual([0, 13])
+    v.setScrollOffset(30)
+    expect(v.getVirtualItems()).toBe(moved)
+    v.setScrollOffset(40)
+    expect(range(v)).toEqual([3, 16])
+  })
+
+  it('keeps the window through a turn while it still covers the way back', () => {
+    const v = make()
+    v.setScrollOffset(500)
+    v.setScrollOffset(510)
+    const moved = v.getVirtualItems()
+    expect(range(v)).toEqual([50, 64])
+    v.setScrollOffset(530)
+    // Back up to visible 52..62 and 51..61: items 51 and 50 are one ahead.
+    v.setScrollOffset(520)
+    v.setScrollOffset(510)
+    expect(v.getVirtualItems()).toBe(moved)
+    // Visible start 50 with item 49 missing: the window moves with the full
+    // overscan before it and one item after.
+    v.setScrollOffset(500)
+    expect(range(v)).toEqual([47, 61])
+  })
+
+  it('always renders every visible item', () => {
+    const v = make((i) => 5 + (i % 7) * 3)
+    let seed = 7
+    const random = () => ((seed = (seed * 16807) % 2147483647) / 2147483647)
+    let offset = 0
+    for (let step = 0; step < 2000; step += 1) {
+      // Mostly small steps either way, now and then a jump.
+      offset = random() < 0.05 ? Math.floor(random() * 12_000) : Math.max(0, offset + Math.floor((random() - 0.4) * 60))
+      v.setScrollOffset(offset)
+      const state = v.getState()
+      const items = v.getVirtualItems()
+      const top = Math.min(offset, Math.max(state.totalSize - 100, 0))
+      const visible = items.filter((it) => it.end > top && it.start < top + 100)
+      expect(visible.length).toBeGreaterThan(0)
+      expect(items[0]!.start).toBeLessThanOrEqual(top)
+      expect(items.at(-1)!.end).toBeGreaterThanOrEqual(Math.min(top + 100, state.totalSize))
+    }
+  })
+
+  it('re-windows at once when the viewport or the sizes change', () => {
+    const v = make()
+    v.setScrollOffset(500)
+    v.setScrollOffset(510)
+    v.setViewportHeight(200)
+    expect(range(v)).toEqual([50, 51 + 20 + 1])
+    v.setOptions({ estimateSize: 20 })
+    expect(v.getVirtualItems()[0]!.start).toBe(v.getVirtualItems()[0]!.index * 20)
+  })
+})

package/src/virtualization/virtualizer.ts

@@ -11,6 +11,8 @@ function sameOptions(a: VirtualizerOptions, b: VirtualizerOptions) {
     a.count === b.count &&
     a.estimateSize === b.estimateSize &&
     (a.overscan ?? 6) === (b.overscan ?? 6) &&
+    a.overscanBehind === b.overscanBehind &&
+    a.overscanMin === b.overscanMin &&
     a.viewportHeight === b.viewportHeight &&
     (a.scrollOffset ?? 0) === (b.scrollOffset ?? 0)
   )
@@ -133,13 +135,14 @@ function buildVariableItems(
   return items
 }
 
-function createState(
+/** The items under the viewport at the current scroll offset, before any
+ *  overscan. */
+function visibleRange(
   options: VirtualizerOptions,
   /** Pre-built cumulative offsets for the variable-size path. */
   offsets: Array<number> | null,
-): VirtualizerState {
+) {
   const count = Math.max(options.count, 0)
-  const overscan = Math.max(options.overscan ?? 6, 0)
   const viewportHeight = Math.max(options.viewportHeight, 0)
 
   if (typeof options.estimateSize === 'function' && offsets) {
@@ -167,38 +170,59 @@ function createState(
       else hi = mid
     }
     const visibleEnd = Math.max(lo - 1, visibleStart)
-
-    const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1)
-    const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1)
-
-    return {
-      items: endIndex >= startIndex ? buildVariableItems(startIndex, endIndex, offsets) : [],
-      totalSize,
-      startIndex,
-      endIndex,
-      scrollOffset,
-      viewportHeight,
-    }
+    return { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize: 0 }
   }
 
   // Uniform-size fast path (original behavior).
-  const estimateSize = Math.max(
+  const uniformSize = Math.max(
     typeof options.estimateSize === 'number' ? options.estimateSize : 1,
     1,
   )
-  const totalSize = count * estimateSize
+  const totalSize = count * uniformSize
   const maxOffset = Math.max(totalSize - viewportHeight, 0)
   const scrollOffset = clamp(options.scrollOffset ?? 0, 0, maxOffset)
 
-  const visibleStart = Math.floor(scrollOffset / estimateSize)
-  const visibleCount = Math.ceil(viewportHeight / estimateSize)
+  const visibleStart = Math.floor(scrollOffset / uniformSize)
+  const visibleCount = Math.ceil(viewportHeight / uniformSize)
   const visibleEnd = Math.min(visibleStart + visibleCount, Math.max(count - 1, 0))
+  return { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize }
+}
 
-  const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1)
-  const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1)
+function createState(
+  options: VirtualizerOptions,
+  /** Pre-built cumulative offsets for the variable-size path. */
+  offsets: Array<number> | null,
+  /** The scroll moved on from the window already rendered. With
+   *  `overscanMin`, only then does the full `overscan` go ahead; a window
+   *  built at rest or after a jump carries `overscanMin`, so a thumb drag
+   *  that jumps every frame renders no more than it needs. */
+  scrolling = false,
+): VirtualizerState {
+  const full = Math.max(options.overscan ?? 6, 0)
+  const overscan =
+    options.overscanMin === undefined || scrolling ? full : clamp(options.overscanMin, 0, full)
+  // The overscan goes ahead of the scroll and `overscanBehind` behind it:
+  // items behind the movement were just scrolled past, and a horizontal
+  // scroll that kept three columns on each side drew ~40% more cells than it
+  // needed to (350 vs 275 in the wide benchmark).
+  const behind = Math.min(Math.max(options.overscanBehind ?? full, 0), overscan)
+  const direction = options.scrollDirection ?? 0
+  const overscanBefore = direction > 0 ? behind : overscan
+  const overscanAfter = direction < 0 ? behind : overscan
+  const { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize } =
+    visibleRange(options, offsets)
+
+  const startIndex = count === 0 ? 0 : clamp(visibleStart - overscanBefore, 0, count - 1)
+  const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscanAfter, 0, count - 1)
 
+  let items: Array<VirtualItem> = []
+  if (endIndex >= startIndex) {
+    items = uniformSize > 0
+      ? buildUniformItems(startIndex, endIndex, uniformSize)
+      : buildVariableItems(startIndex, endIndex, offsets!)
+  }
   return {
-    items: endIndex >= startIndex ? buildUniformItems(startIndex, endIndex, estimateSize) : [],
+    items,
     totalSize,
     startIndex,
     endIndex,
@@ -251,13 +275,52 @@ export function createVirtualizer(initial: VirtualizerOptions) {
     listeners.forEach((listener) => listener())
   }
 
-  function recalc() {
-    const next = createState(options, getOffsets())
+  function recalc(scrolling = false) {
+    const next = createState(options, getOffsets(), scrolling)
     if (sameState(state, next)) return
+    // Hand back the previous item object for a row whose index, offset, size
+    // and slot did not change. The grid's row {#each} is keyed by slot, so a
+    // row that stays in the window keeps its <tr>, but a new item object
+    // still invalidated everything that row and its cells derive from it:
+    // every scroll frame re-checked ~300 cells to render the two that came
+    // into view, and Svelte's dependency marking was most of the frame's
+    // script time (measured 4.8 of 8.3 ms on a 100k-row grid).
+    if (state.items.length > 0 && next.items.length > 0) {
+      const first = state.items[0]!.index
+      const items = next.items
+      for (let i = 0; i < items.length; i += 1) {
+        const item = items[i]!
+        const prev = state.items[item.index - first]
+        if (prev && prev.index === item.index && prev.start === item.start && prev.size === item.size && prev.key === item.key) {
+          items[i] = prev
+        }
+      }
+    }
     state = next
     emit()
   }
 
+  /**
+   * What a scroll does to the window already rendered, with `overscanMin`:
+   * 'hold' while that window still covers the visible items plus
+   * `overscanMin` ahead of the scroll, 'move' once the scroll runs past that
+   * (the window moves on with the full overscan ahead), and 'jump' when the
+   * visible items are nowhere in it. Without `overscanMin` every scroll moves
+   * the window.
+   */
+  function scrollStep(): 'hold' | 'move' | 'jump' {
+    const min = options.overscanMin
+    if (min === undefined || state.items.length === 0) return 'move'
+    const ahead = clamp(min, 0, Math.max(options.overscan ?? 6, 0))
+    const { count, viewportHeight, totalSize, visibleStart, visibleEnd } = visibleRange(options, getOffsets())
+    if (count === 0 || viewportHeight !== state.viewportHeight || totalSize !== state.totalSize) return 'jump'
+    if (visibleStart > state.endIndex || visibleEnd < state.startIndex) return 'jump'
+    const direction = options.scrollDirection ?? 0
+    const needStart = Math.max(visibleStart - (direction < 0 ? ahead : 0), 0)
+    const needEnd = Math.min(visibleEnd + (direction > 0 ? ahead : 0), count - 1)
+    return state.startIndex <= needStart && state.endIndex >= needEnd ? 'hold' : 'move'
+  }
+
   return {
     setOptions(next: Partial<VirtualizerOptions>) {
       const merged = { ...options, ...next }
@@ -278,9 +341,12 @@ export function createVirtualizer(initial: VirtualizerOptions) {
       recalc()
     },
     setScrollOffset(scrollOffset: number) {
-      if ((options.scrollOffset ?? 0) === scrollOffset) return
-      options = { ...options, scrollOffset }
-      recalc()
+      const previous = options.scrollOffset ?? 0
+      if (previous === scrollOffset) return
+      options = { ...options, scrollOffset, scrollDirection: scrollOffset > previous ? 1 : -1 }
+      const step = scrollStep()
+      if (step === 'hold') return
+      recalc(step === 'move')
     },
     setViewportHeight(viewportHeight: number) {
       if (options.viewportHeight === viewportHeight) return

package/src/windowed-brand.ts

@@ -0,0 +1,67 @@
+/**
+ * What marks an array as windowed data, and how to tell (windowed-data.ts has
+ * the full story). Kept apart from createWindowedData so code that only asks
+ * "is this windowed?" - the controller, the core's per-update paths - does not
+ * pull in the windowed row model that createWindowedData installs.
+ */
+
+const WINDOWED = Symbol.for('svgrid.windowedData')
+
+export type WindowedSource<T> = {
+  /** The number of rows, loaded or not. */
+  readonly length: number
+  /** The entry at `index`: a loaded row, a placeholder, or undefined. */
+  at(index: number): T | undefined
+}
+
+const isIndexKey = (key: string | symbol): key is string =>
+  typeof key === 'string' && key.length > 0 && key.length < 16 && /^(0|[1-9]\d*)$/.test(key)
+
+/**
+ * An array of `length` entries read through `at(i)`: a real `Array` (a Proxy
+ * over an empty one) carrying the windowed mark. Each call returns a new
+ * array identity, which is how a source tells the grid its rows changed.
+ */
+export function makeWindowedArray<T>(length: number, at: (index: number) => T | undefined): T[] {
+  const source: WindowedSource<T> = { length, at }
+  const target: T[] = []
+  return new Proxy(target, {
+    get(t, key, receiver) {
+      if (key === WINDOWED) return source
+      if (key === 'length') return length
+      if (isIndexKey(key)) {
+        const i = Number(key)
+        return i < length ? at(i) : undefined
+      }
+      return Reflect.get(t, key, receiver)
+    },
+    has(t, key) {
+      if (key === WINDOWED) return true
+      if (isIndexKey(key)) return Number(key) < length
+      return Reflect.has(t, key)
+    },
+    set() {
+      // Read-only: a write would land in the empty target and never be seen.
+      return false
+    },
+    getOwnPropertyDescriptor(t, key) {
+      if (isIndexKey(key) && Number(key) < length) {
+        return { value: at(Number(key)), writable: false, enumerable: true, configurable: true }
+      }
+      if (key === 'length') return { value: length, writable: true, enumerable: false, configurable: false }
+      return Reflect.getOwnPropertyDescriptor(t, key)
+    },
+  })
+}
+
+/** The source behind windowed data, or null for an ordinary array. */
+export function windowedSourceOf<T>(data: unknown): WindowedSource<T> | null {
+  if (data === null || typeof data !== 'object') return null
+  const source = (data as Record<symbol, unknown>)[WINDOWED]
+  return (source as WindowedSource<T> | undefined) ?? null
+}
+
+/** True for windowed data. */
+export function isWindowedData(data: unknown): boolean {
+  return windowedSourceOf(data) !== null
+}

package/src/windowed-data.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Windowed data: an array whose entries are read on demand, so a server row
+ * model can hand the grid 100M rows without building 100M of anything.
+ */
+import { describe, expect, it } from 'vitest'
+import { createWindowedData, isWindowedData, windowedSourceOf } from './windowed-data'
+import { createSvGridCore } from './core'
+import { createCoreRowModel, tableFeatures } from './index'
+import { createBlockCache } from './server-block-cache'
+
+describe('createWindowedData', () => {
+  it('reports the length and reads entries through at()', () => {
+    const reads: number[] = []
+    const data = createWindowedData(100_000_000, (i) => {
+      reads.push(i)
+      return { id: i }
+    })
+    expect(Array.isArray(data)).toBe(true)
+    expect(data.length).toBe(100_000_000)
+    expect(data[99_999_999]).toEqual({ id: 99_999_999 })
+    expect(data[100_000_000]).toBeUndefined()
+    expect(reads).toEqual([99_999_999])
+  })
+
+  it('is recognised, and ordinary arrays are not', () => {
+    const data = createWindowedData(3, (i) => i)
+    expect(isWindowedData(data)).toBe(true)
+    expect(windowedSourceOf(data)?.length).toBe(3)
+    expect(isWindowedData([1, 2, 3])).toBe(false)
+    expect(isWindowedData(null)).toBe(false)
+  })
+
+  it('still iterates like an array', () => {
+    const data = createWindowedData(4, (i) => i * 10)
+    expect([...data]).toEqual([0, 10, 20, 30])
+    expect(data.slice(1, 3)).toEqual([10, 20])
+    expect(2 in data).toBe(true)
+    expect(9 in data).toBe(false)
+  })
+
+  it('refuses writes', () => {
+    const data = createWindowedData(2, (i) => i) as number[]
+    expect(() => {
+      'use strict'
+      data[0] = 5
+    }).toThrow()
+  })
+})
+
+describe('core row model over windowed data', () => {
+  function grid(data: unknown) {
+    return createSvGridCore({
+      _features: tableFeatures({}),
+      _rowModels: { coreRowModel: createCoreRowModel() },
+      columns: [{ field: 'v', header: 'V' }],
+      data: data as any[],
+      getRowId: (r: any) => String(r.id),
+      state: {},
+    } as any)
+  }
+
+  it('builds a row only for the indices that are read', () => {
+    let reads = 0
+    const data = createWindowedData(50_000_000, (i) => {
+      reads += 1
+      return { id: i, v: i * 2 }
+    })
+    const rows = grid(data).getRowModel().rows
+    expect(rows.length).toBe(50_000_000)
+    expect(reads).toBe(0)
+    const row = rows[25_000_000]!
+    expect(row.id).toBe('25000000')
+    expect(row.index).toBe(25_000_000)
+    expect(row.getCellValueByColumnId('v')).toBe(50_000_000)
+    expect(reads).toBe(1)
+  })
+
+  it('keeps a row object while its data object is the same', () => {
+    const objects = [{ id: 0, v: 1 }, { id: 1, v: 2 }]
+    const g = grid(createWindowedData(2, (i) => objects[i]))
+    const first = g.getRowModel().rows[1]
+    expect(g.getRowModel().rows[1]).toBe(first)
+  })
+})
+
+describe('block cache windowedRows', () => {
+  it('spans the row count without materialising it', async () => {
+    const cache = createBlockCache<{ id: number }>({
+      blockSize: 100,
+      initialRowCount: 1,
+      fetch: async (start, end) => ({
+        rows: Array.from({ length: end - start }, (_, k) => ({ id: start + k })),
+        rowCount: 100_000_000,
+      }),
+      onChange: () => {},
+    })
+    cache.setViewport(0, 10)
+    for (let i = 0; i < 10; i += 1) await Promise.resolve()
+    const rows = cache.windowedRows()
+    expect(rows.length).toBe(100_000_000)
+    expect(rows[5]).toEqual({ id: 5 })
+    expect(cache.windowedRows()).toBe(rows) // memoised until the next change
+    cache.dispose()
+  })
+})

package/src/windowed-data.ts

@@ -0,0 +1,36 @@
+/**
+ * Windowed data: an array the grid can index without anyone having built it.
+ *
+ * A server row model knows how many rows there are and holds a few blocks of
+ * them. Handing the grid a dense array of `rowCount` entries (placeholders
+ * for everything not loaded) made every block landing cost O(rowCount): the
+ * array itself, a copy in the controller, and a row object per entry in the
+ * core. At 10M rows that was ~1 GB of heap and ~1 s per block; at 100M the
+ * grid never painted.
+ *
+ * `createWindowedData(length, at)` returns a real `Array` (a Proxy over one)
+ * whose `length` is the row count and whose entries are read through `at(i)`
+ * on demand. The grid recognises it (`windowedSourceOf`) and builds row
+ * objects only for the indices it actually reads - the rows on screen, plus
+ * whatever a user action touches. Iterating one still works (it is an array),
+ * but costs O(length), so the grid's per-update paths check for it first.
+ *
+ * Windowed data is final: the source has already sorted, filtered and grouped
+ * it, so the grid's own sort / filter / group stages do not run over it.
+ *
+ * The row model that reads it (windowed-row-model.ts) is installed by the
+ * first call here, so a grid never handed windowed data does not bundle it.
+ */
+import { makeWindowedArray } from './windowed-brand'
+import { enableWindowedRowModel } from './windowed-row-model'
+
+export { windowedSourceOf, isWindowedData, type WindowedSource } from './windowed-brand'
+
+/**
+ * An array of `length` entries read through `at(i)`. Each call returns a new
+ * array identity, which is how a source tells the grid its rows changed.
+ */
+export function createWindowedData<T>(length: number, at: (index: number) => T | undefined): T[] {
+  enableWindowedRowModel()
+  return makeWindowedArray(length, at)
+}