From 431dcded7f1beab110c8b01388e8ce28aab0daac Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 4 Oct 2026 09:01:33 +0000
Subject: [PATCH 1/4] feat: add MiniFlatList, a minimal FlatList-like list

Builds on NaiveList with the core ideas of React Native's FlatList:

- keyExtractor (default key, then id, then index) keys items and their
  cached sizes, so sizes survive inserts and reorders. Unmeasured items
  count as the average measured size.
- initialNumToRender items are rendered before the viewport is measured.
- windowSize sets the rendered area in viewports.
- Batched rendering: the scroll offset lives in a ref, so scrolling does
  not re-render while the visible items are rendered. The off-screen area
  fills maxToRenderPerBatch items every updateCellsBatchingPeriod ms; a
  blank visible area renders right away.
- Cells are memoized and re-render only when their props or extraData
  change.
- Offsets are looked up with binary search.

The example app can switch between NaiveList and MiniFlatList.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EZxDtj1CphSjr2V67rdmFP
---
 README.md                                     |  30 +++
 example/src/App.tsx                           |  46 +++-
 src/MiniFlatList/MiniFlatList.tsx             | 241 ++++++++++++++++++
 .../__tests__/MiniFlatList.test.tsx           | 196 ++++++++++++++
 .../__tests__/item-offsets.test.ts            |  60 +++++
 .../__tests__/render-window.test.ts           |  91 +++++++
 src/MiniFlatList/index.ts                     |   6 +
 src/MiniFlatList/item-offsets.ts              |  99 +++++++
 src/MiniFlatList/render-window.ts             | 120 +++++++++
 src/index.tsx                                 |   5 +
 10 files changed, 883 insertions(+), 11 deletions(-)
 create mode 100644 src/MiniFlatList/MiniFlatList.tsx
 create mode 100644 src/MiniFlatList/__tests__/MiniFlatList.test.tsx
 create mode 100644 src/MiniFlatList/__tests__/item-offsets.test.ts
 create mode 100644 src/MiniFlatList/__tests__/render-window.test.ts
 create mode 100644 src/MiniFlatList/index.ts
 create mode 100644 src/MiniFlatList/item-offsets.ts
 create mode 100644 src/MiniFlatList/render-window.ts

diff --git a/README.md b/README.md
index 4226be5..1ac1aef 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,36 @@ area and replaces the rest with spacer views. Item heights are measured with
 `onLayout` and cached by index; unmeasured items are assumed to be 50 px tall.
 Expect blank areas and content jumps while scrolling fast.
 
+```tsx
+import { MiniFlatList } from 'react-native-tiny-list';
+
+<MiniFlatList
+  data={items}
+  renderItem={renderRow} // keep it stable, not an inline function
+  keyExtractor={(item) => item.id}
+  initialNumToRender={10}
+  windowSize={21}
+  maxToRenderPerBatch={10}
+  updateCellsBatchingPeriod={50}
+/>
+```
+
+`MiniFlatList` adds the core ideas of React Native's `FlatList` on top of
+`TinyList`:
+
+- **Keys.** `keyExtractor` (default: `item.key`, then `item.id`, then the
+  index) keys both the items and the cached sizes, so sizes survive inserts and
+  reorders. Unmeasured items count as the average measured size.
+- **`initialNumToRender`.** Items rendered before the viewport is measured.
+- **`windowSize`.** The area kept rendered, in viewports, centered on the
+  visible one.
+- **Batched rendering.** Scrolling does not re-render the list while the
+  visible items are already rendered. The area off screen is filled
+  `maxToRenderPerBatch` items at a time, every `updateCellsBatchingPeriod` ms.
+  When the visible area is blank, the list renders right away.
+- **Memoized items.** Each item re-renders only when its props or `extraData`
+  change.
+
 
 ## Contributing
 
diff --git a/example/src/App.tsx b/example/src/App.tsx
index 9a3da52..6bc583b 100644
--- a/example/src/App.tsx
+++ b/example/src/App.tsx
@@ -1,5 +1,10 @@
-import { StyleSheet, Text, View } from 'react-native';
-import { TinyList } from 'react-native-tiny-list';
+import { useState } from 'react';
+import { Button, StyleSheet, Text, View } from 'react-native';
+import {
+  MiniFlatList,
+  TinyList,
+  type MiniFlatListRenderItemInfo,
+} from 'react-native-tiny-list';
 
 type Item = { id: number; title: string };
 
@@ -8,18 +13,31 @@ const DATA: Item[] = Array.from({ length: 10_000 }, (_, i) => ({
   title: `Item ${i}`,
 }));
 
+// Defined outside the component so it stays stable and MiniFlatList can skip
+// re-rendering unchanged items.
+function renderItem({ item, index }: MiniFlatListRenderItemInfo<Item>) {
+  return (
+    // Vary heights to exercise measurement.
+    <View style={[styles.item, { height: 40 + (index % 5) * 15 }]}>
+      <Text>{item.title}</Text>
+    </View>
+  );
+}
+
 export default function App() {
+  const [list, setList] = useState<'tiny' | 'mini'>('mini');
+
   return (
     <View style={styles.container}>
-      <TinyList
-        data={DATA}
-        renderItem={({ item, index }) => (
-          // Vary heights to exercise measurement.
-          <View style={[styles.item, { height: 40 + (index % 5) * 15 }]}>
-            <Text>{item.title}</Text>
-          </View>
-        )}
-      />
+      <View style={styles.toolbar}>
+        <Button title="TinyList" onPress={() => setList('tiny')} />
+        <Button title="MiniFlatList" onPress={() => setList('mini')} />
+      </View>
+      {list === 'tiny' ? (
+        <TinyList data={DATA} renderItem={renderItem} />
+      ) : (
+        <MiniFlatList data={DATA} renderItem={renderItem} />
+      )}
     </View>
   );
 }
@@ -28,6 +46,12 @@ const styles = StyleSheet.create({
   container: {
     flex: 1,
   },
+  toolbar: {
+    flexDirection: 'row',
+    justifyContent: 'space-around',
+    paddingTop: 48,
+    paddingBottom: 8,
+  },
   item: {
     justifyContent: 'center',
     paddingHorizontal: 16,
diff --git a/src/MiniFlatList/MiniFlatList.tsx b/src/MiniFlatList/MiniFlatList.tsx
new file mode 100644
index 0000000..e9e8d35
--- /dev/null
+++ b/src/MiniFlatList/MiniFlatList.tsx
@@ -0,0 +1,241 @@
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useReducer,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import {
+  ScrollView,
+  View,
+  type LayoutChangeEvent,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+} from 'react-native';
+import {
+  computeItemOffsets,
+  findItemsInArea,
+  type ItemRange,
+} from './item-offsets';
+import {
+  computeRenderWindow,
+  isRangeInside,
+  isSameRange,
+} from './render-window';
+
+export interface MiniFlatListRenderItemInfo<T> {
+  item: T;
+  index: number;
+}
+
+export interface MiniFlatListProps<T> {
+  data: ReadonlyArray<T>;
+  /** Keep it stable (not an inline function) so unchanged items skip re-rendering. */
+  renderItem: (info: MiniFlatListRenderItemInfo<T>) => ReactNode;
+  /** Unique key per item. Defaults to `item.key`, then `item.id`, then the index. */
+  keyExtractor?: (item: T, index: number) => string;
+  /** Change it to re-render all items, e.g. when `renderItem` reads outside state. */
+  extraData?: unknown;
+  /** Items rendered before the viewport is measured. */
+  initialNumToRender?: number;
+  /** Area to keep rendered, in viewports, centered on the visible one. */
+  windowSize?: number;
+  /** Most items to add in one update. */
+  maxToRenderPerBatch?: number;
+  /** Delay between updates that only fill the area off screen, in ms. */
+  updateCellsBatchingPeriod?: number;
+}
+
+/**
+ * A minimal FlatList. Like TinyList it renders items near the viewport
+ * between two spacers, but it also:
+ *
+ * - caches item sizes by key, so they survive inserts and reorders;
+ * - skips re-rendering on scroll unless the visible area is not rendered yet;
+ * - fills the area off screen in small batches instead of all at once;
+ * - memoizes items, so a batch renders only the new ones.
+ */
+export function MiniFlatList<T>({
+  data,
+  renderItem,
+  keyExtractor = defaultKeyExtractor,
+  extraData,
+  initialNumToRender = 10,
+  windowSize = 21,
+  maxToRenderPerBatch = 10,
+  updateCellsBatchingPeriod = 50,
+}: MiniFlatListProps<T>) {
+  const [viewportSize, setViewportSize] = useState(0);
+
+  // Read on demand instead of being state, so scrolling does not re-render.
+  const scrollOffsetRef = useRef(0);
+
+  // Measured item sizes by key. A change re-renders the list.
+  const sizesRef = useRef(new Map<string, number>());
+  const [, forceRender] = useReducer((count: number) => count + 1, 0);
+
+  // Items that are rendered. Grows in batches toward the target window.
+  const [renderWindow, setRenderWindow] = useState<ItemRange>(() => ({
+    start: 0,
+    end: Math.min(initialNumToRender, data.length),
+  }));
+
+  // Recomputed on every render. Cheap, as scrolling alone does not re-render.
+  const keys = data.map((item, index) => keyExtractor(item, index));
+  const offsets = computeItemOffsets(keys, sizesRef.current);
+
+  // Compute and render the next batch now.
+  const updateRenderWindow = () => {
+    cancelNextBatch();
+    const next = computeRenderWindow({
+      offsets,
+      scrollOffset: scrollOffsetRef.current,
+      viewportSize,
+      windowSize,
+      maxToRenderPerBatch,
+      initialNumToRender,
+      previous: renderWindow,
+    });
+    if (!isSameRange(next, renderWindow)) {
+      setRenderWindow(next);
+    }
+  };
+
+  // Only one batch is pending at a time.
+  const batchTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const scheduleNextBatch = () => {
+    if (batchTimerRef.current == null) {
+      batchTimerRef.current = setTimeout(
+        updateRenderWindow,
+        updateCellsBatchingPeriod
+      );
+    }
+  };
+  const cancelNextBatch = () => {
+    if (batchTimerRef.current != null) {
+      clearTimeout(batchTimerRef.current);
+      batchTimerRef.current = null;
+    }
+  };
+
+  // After each render, schedule the next batch. The chain stops once a batch
+  // leaves the window unchanged. The cleanup cancels a timer scheduled by an
+  // earlier render, so a batch never runs with stale offsets.
+  useEffect(() => {
+    scheduleNextBatch();
+    return cancelNextBatch;
+  });
+
+  // Needed to establish viewport height
+  const handleLayout = (event: LayoutChangeEvent) => {
+    setViewportSize(event.nativeEvent.layout.height);
+  };
+
+  // Needed to get actual item size. Stable, so memoized cells stay memoized.
+  const handleCellLayout = useCallback(
+    (key: string, event: LayoutChangeEvent) => {
+      const size = event.nativeEvent.layout.height;
+      if (sizesRef.current.get(key) !== size) {
+        sizesRef.current.set(key, size);
+        forceRender();
+      }
+    },
+    []
+  );
+
+  // Blank area on screen: render right away. Otherwise fill off screen later.
+  // The final drag offset arrives only in `onScrollEndDrag`, so listen to it too.
+  const handleScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    scrollOffsetRef.current = event.nativeEvent.contentOffset.y;
+    const visible = findItemsInArea(
+      offsets,
+      scrollOffsetRef.current,
+      scrollOffsetRef.current + viewportSize
+    );
+    if (isRangeInside(visible, renderWindow)) {
+      scheduleNextBatch();
+    } else {
+      updateRenderWindow();
+    }
+  };
+
+  // `data` may have shrunk since the window was computed.
+  const start = Math.min(renderWindow.start, data.length);
+  const end = Math.min(renderWindow.end, data.length);
+
+  const cells: ReactNode[] = [];
+  for (let index = start; index < end; index++) {
+    const key = keys[index]!;
+    cells.push(
+      <Cell
+        key={key}
+        cellKey={key}
+        item={data[index] as T}
+        index={index}
+        renderItem={renderItem}
+        extraData={extraData}
+        onCellLayout={handleCellLayout}
+      />
+    );
+  }
+
+  return (
+    <ScrollView
+      onScroll={handleScroll}
+      onScrollEndDrag={handleScroll}
+      onMomentumScrollEnd={handleScroll}
+      onLayout={handleLayout}
+      scrollEventThrottle={16}
+    >
+      <View style={{ height: offsets[start] }} />
+      {cells}
+      <View style={{ height: offsets[data.length]! - offsets[end]! }} />
+    </ScrollView>
+  );
+}
+
+/** Same default as FlatList: `item.key`, then `item.id`, then the index. */
+export function defaultKeyExtractor(item: unknown, index: number): string {
+  if (typeof item === 'object' && item != null) {
+    if ('key' in item && item.key != null) {
+      return String(item.key);
+    }
+    if ('id' in item && item.id != null) {
+      return String(item.id);
+    }
+  }
+  return String(index);
+}
+
+interface CellProps<T> {
+  cellKey: string;
+  item: T;
+  index: number;
+  renderItem: (info: MiniFlatListRenderItemInfo<T>) => ReactNode;
+  /** Unused here; a new value only makes `memo` re-render the cell. */
+  extraData: unknown;
+  onCellLayout: (key: string, event: LayoutChangeEvent) => void;
+}
+
+/**
+ * Wraps one item to measure it. Memoized below, so a new batch or a size
+ * change re-renders only cells whose props changed.
+ */
+function CellView<T>({
+  cellKey,
+  item,
+  index,
+  renderItem,
+  onCellLayout,
+}: CellProps<T>) {
+  return (
+    <View onLayout={(event) => onCellLayout(cellKey, event)}>
+      {renderItem({ item, index })}
+    </View>
+  );
+}
+
+// `memo` loses the generic type parameter, so restore it with a cast.
+const Cell = memo(CellView) as typeof CellView;
diff --git a/src/MiniFlatList/__tests__/MiniFlatList.test.tsx b/src/MiniFlatList/__tests__/MiniFlatList.test.tsx
new file mode 100644
index 0000000..7d56c91
--- /dev/null
+++ b/src/MiniFlatList/__tests__/MiniFlatList.test.tsx
@@ -0,0 +1,196 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest,
+} from '@jest/globals';
+import { act, fireEvent, render, screen } from '@testing-library/react-native';
+import { Text } from 'react-native';
+import { MiniFlatList, type MiniFlatListProps } from '../MiniFlatList';
+import { defaultKeyExtractor } from '../MiniFlatList';
+
+type Item = { id: string; title: string };
+
+const DATA: Item[] = Array.from({ length: 100 }, (_, i) => ({
+  id: `id-${i}`,
+  title: `Item ${i}`,
+}));
+
+const renderItem = ({ item }: { item: Item }) => <Text>{item.title}</Text>;
+
+function layoutEvent(height: number) {
+  return { nativeEvent: { layout: { x: 0, y: 0, width: 300, height } } };
+}
+
+function scrollEvent(y: number) {
+  return { nativeEvent: { contentOffset: { x: 0, y } } };
+}
+
+async function renderList(props: Partial<MiniFlatListProps<Item>> = {}) {
+  const result = await render(
+    <MiniFlatList
+      data={DATA}
+      renderItem={renderItem}
+      windowSize={3}
+      {...props}
+    />
+  );
+  return result.root!;
+}
+
+/** Runs one pending batch timer and renders its result. */
+async function runNextBatch() {
+  await act(async () => {
+    jest.advanceTimersByTime(50);
+  });
+}
+
+function renderedItems(): string[] {
+  return screen.queryAllByText(/^Item \d+$/).map((node) => {
+    return String(node.props.children);
+  });
+}
+
+describe('MiniFlatList', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('renders initialNumToRender items before the viewport is measured', async () => {
+    await renderList({ initialNumToRender: 3 });
+    expect(renderedItems()).toEqual(['Item 0', 'Item 1', 'Item 2']);
+  });
+
+  it('fills the window in batches of maxToRenderPerBatch', async () => {
+    const scrollView = await renderList({
+      initialNumToRender: 3,
+      maxToRenderPerBatch: 5,
+    });
+
+    // Viewport is 500 px, items are estimated at 50 px: 10 visible items.
+    await fireEvent(scrollView, 'layout', layoutEvent(500));
+
+    // The 10 visible items render even though the budget is 5.
+    await runNextBatch();
+    expect(renderedItems()).toHaveLength(10);
+
+    // Then up to 5 new items per batch, until one viewport below is filled.
+    await runNextBatch();
+    expect(renderedItems()).toHaveLength(15);
+    await runNextBatch();
+    expect(renderedItems()).toHaveLength(20);
+    await runNextBatch();
+    expect(renderedItems()).toHaveLength(20);
+  });
+
+  it('renders right away when scrolled past the rendered items', async () => {
+    const scrollView = await renderList();
+    await fireEvent(scrollView, 'layout', layoutEvent(500));
+    await runNextBatch();
+
+    // No timer advanced: the visible area was blank, so it renders now.
+    await fireEvent(scrollView, 'scroll', scrollEvent(3000));
+    expect(screen.getByText('Item 60')).toBeOnTheScreen();
+    expect(screen.queryByText('Item 0')).not.toBeOnTheScreen();
+  });
+
+  it('waits for the next batch when the visible items are rendered', async () => {
+    const scrollView = await renderList({ maxToRenderPerBatch: 100 });
+    await fireEvent(scrollView, 'layout', layoutEvent(500));
+    await runNextBatch();
+    expect(renderedItems()).toHaveLength(20);
+
+    // Items 5..14 are visible and rendered, so nothing changes yet.
+    await fireEvent(scrollView, 'scroll', scrollEvent(250));
+    expect(renderedItems()).toHaveLength(20);
+
+    // The next batch extends the window below: items 0..24.
+    await runNextBatch();
+    expect(renderedItems()).toHaveLength(25);
+  });
+
+  it('keeps measured sizes with their item when data is reordered', async () => {
+    const scrollView = await renderList({ maxToRenderPerBatch: 100 });
+    await fireEvent(scrollView, 'layout', layoutEvent(500));
+    await runNextBatch();
+
+    // Item 0 is 1050 px and alone fills the window. Items 1..19 are 50 px,
+    // so unmeasured items are estimated at the average, 100 px.
+    await fireEvent(screen.getByText('Item 0'), 'layout', layoutEvent(1050));
+    for (let index = 1; index < 20; index += 1) {
+      await fireEvent(
+        screen.getByText(`Item ${index}`),
+        'layout',
+        layoutEvent(50)
+      );
+    }
+    await runNextBatch();
+    expect(renderedItems()).toEqual(['Item 0']);
+
+    // Move item 0 to the end. Its size moves with it, so items 1..20 fit.
+    const reordered = [...DATA.slice(1), DATA[0]!];
+    await screen.rerender(
+      <MiniFlatList
+        data={reordered}
+        renderItem={renderItem}
+        windowSize={3}
+        maxToRenderPerBatch={100}
+      />
+    );
+    await runNextBatch();
+    expect(renderedItems()).toHaveLength(20);
+    expect(screen.getByText('Item 20')).toBeOnTheScreen();
+    expect(screen.queryByText('Item 0')).not.toBeOnTheScreen();
+  });
+
+  it('re-renders items only when their props or extraData change', async () => {
+    const calls: number[] = [];
+    const countingRenderItem = ({
+      item,
+      index,
+    }: {
+      item: Item;
+      index: number;
+    }) => {
+      calls.push(index);
+      return <Text>{item.title}</Text>;
+    };
+    const props = {
+      data: DATA,
+      renderItem: countingRenderItem,
+      initialNumToRender: 2,
+    };
+
+    await render(<MiniFlatList {...props} extraData={1} />);
+    expect(calls).toEqual([0, 1]);
+
+    calls.length = 0;
+    await screen.rerender(<MiniFlatList {...props} extraData={1} />);
+    expect(calls).toEqual([]);
+
+    await screen.rerender(<MiniFlatList {...props} extraData={2} />);
+    expect(calls).toEqual([0, 1]);
+  });
+
+  it('renders nothing for empty data', async () => {
+    const scrollView = await renderList({ data: [] });
+    await fireEvent(scrollView, 'layout', layoutEvent(500));
+    await runNextBatch();
+    expect(renderedItems()).toEqual([]);
+  });
+});
+
+describe('defaultKeyExtractor', () => {
+  it('uses key, then id, then the index', () => {
+    expect(defaultKeyExtractor({ key: 'k', id: 'i' }, 3)).toBe('k');
+    expect(defaultKeyExtractor({ id: 7 }, 3)).toBe('7');
+    expect(defaultKeyExtractor({ title: 'x' }, 3)).toBe('3');
+    expect(defaultKeyExtractor('text', 3)).toBe('3');
+  });
+});
diff --git a/src/MiniFlatList/__tests__/item-offsets.test.ts b/src/MiniFlatList/__tests__/item-offsets.test.ts
new file mode 100644
index 0000000..f0b8fec
--- /dev/null
+++ b/src/MiniFlatList/__tests__/item-offsets.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from '@jest/globals';
+import {
+  computeItemOffsets,
+  DEFAULT_ITEM_SIZE,
+  findFirstItemEndingAfter,
+  findFirstItemStartingAtOrAfter,
+  findItemsInArea,
+} from '../item-offsets';
+
+describe('computeItemOffsets', () => {
+  it('returns only the total for empty data', () => {
+    expect(computeItemOffsets([], new Map())).toEqual([0]);
+  });
+
+  it('uses DEFAULT_ITEM_SIZE when nothing is measured', () => {
+    expect(computeItemOffsets(['a', 'b'], new Map())).toEqual([
+      0,
+      DEFAULT_ITEM_SIZE,
+      2 * DEFAULT_ITEM_SIZE,
+    ]);
+  });
+
+  it('looks sizes up by key and estimates the rest with the average', () => {
+    const sizes = new Map([
+      ['a', 100],
+      ['c', 300],
+    ]);
+    // 'b' is unmeasured and counts as the average, 200.
+    expect(computeItemOffsets(['c', 'b', 'a'], sizes)).toEqual([
+      0, 300, 500, 600,
+    ]);
+  });
+});
+
+describe('binary search', () => {
+  // Items: 0 = [0, 100), 1 = [100, 300), 2 = [300, 350)
+  const offsets = [0, 100, 300, 350];
+
+  it('finds the item at an offset', () => {
+    expect(findFirstItemEndingAfter(offsets, -10)).toBe(0);
+    expect(findFirstItemEndingAfter(offsets, 0)).toBe(0);
+    expect(findFirstItemEndingAfter(offsets, 99)).toBe(0);
+    expect(findFirstItemEndingAfter(offsets, 100)).toBe(1);
+    expect(findFirstItemEndingAfter(offsets, 349)).toBe(2);
+    expect(findFirstItemEndingAfter(offsets, 350)).toBe(3);
+  });
+
+  it('finds the first item starting at or after an offset', () => {
+    expect(findFirstItemStartingAtOrAfter(offsets, 0)).toBe(0);
+    expect(findFirstItemStartingAtOrAfter(offsets, 1)).toBe(1);
+    expect(findFirstItemStartingAtOrAfter(offsets, 300)).toBe(2);
+    expect(findFirstItemStartingAtOrAfter(offsets, 301)).toBe(3);
+  });
+
+  it('finds the items overlapping an area', () => {
+    expect(findItemsInArea(offsets, 0, 100)).toEqual({ start: 0, end: 1 });
+    expect(findItemsInArea(offsets, 50, 301)).toEqual({ start: 0, end: 3 });
+    expect(findItemsInArea(offsets, 400, 500)).toEqual({ start: 3, end: 3 });
+  });
+});
diff --git a/src/MiniFlatList/__tests__/render-window.test.ts b/src/MiniFlatList/__tests__/render-window.test.ts
new file mode 100644
index 0000000..7a97111
--- /dev/null
+++ b/src/MiniFlatList/__tests__/render-window.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it } from '@jest/globals';
+import { computeRenderWindow, growTowardTarget } from '../render-window';
+
+// 100 items of 100 px each.
+const OFFSETS = Array.from({ length: 101 }, (_, i) => i * 100);
+
+const DEFAULTS = {
+  offsets: OFFSETS,
+  scrollOffset: 0,
+  viewportSize: 500,
+  windowSize: 3,
+  maxToRenderPerBatch: 1000,
+  initialNumToRender: 10,
+  previous: { start: 0, end: 0 },
+};
+
+describe('computeRenderWindow', () => {
+  it('renders initialNumToRender items before the viewport is measured', () => {
+    expect(computeRenderWindow({ ...DEFAULTS, viewportSize: 0 })).toEqual({
+      start: 0,
+      end: 10,
+    });
+  });
+
+  it('renders nothing for empty data', () => {
+    expect(computeRenderWindow({ ...DEFAULTS, offsets: [0] })).toEqual({
+      start: 0,
+      end: 0,
+    });
+  });
+
+  it('renders windowSize viewports centered on the visible one', () => {
+    // windowSize 3: one viewport above and below. Area is [1500, 3000).
+    expect(computeRenderWindow({ ...DEFAULTS, scrollOffset: 2000 })).toEqual({
+      start: 15,
+      end: 30,
+    });
+
+    // windowSize 5: two viewports above and below. Area is [1000, 3500).
+    expect(
+      computeRenderWindow({ ...DEFAULTS, scrollOffset: 2000, windowSize: 5 })
+    ).toEqual({ start: 10, end: 35 });
+  });
+
+  it('adds at most maxToRenderPerBatch new items per call', () => {
+    const params = { ...DEFAULTS, scrollOffset: 2000, maxToRenderPerBatch: 2 };
+
+    // Visible items 20..24 are always rendered, even beyond the budget.
+    const first = computeRenderWindow(params);
+    expect(first).toEqual({ start: 20, end: 25 });
+
+    // Next batches grow by 2 items, one on each side.
+    const second = computeRenderWindow({ ...params, previous: first });
+    expect(second).toEqual({ start: 19, end: 26 });
+
+    const third = computeRenderWindow({ ...params, previous: second });
+    expect(third).toEqual({ start: 18, end: 27 });
+  });
+
+  it('reaches the target window after enough batches', () => {
+    const params = { ...DEFAULTS, scrollOffset: 2000, maxToRenderPerBatch: 4 };
+    let window = params.previous;
+    for (let batch = 0; batch < 10; batch += 1) {
+      window = computeRenderWindow({ ...params, previous: window });
+    }
+    expect(window).toEqual({ start: 15, end: 30 });
+  });
+});
+
+describe('growTowardTarget', () => {
+  const target = { start: 0, end: 20 };
+
+  it('keeps already rendered items without counting them as new', () => {
+    expect(
+      growTowardTarget({ start: 8, end: 12 }, target, { start: 5, end: 15 }, 0)
+    ).toEqual({ start: 5, end: 15 });
+  });
+
+  it('drops rendered items outside the target', () => {
+    expect(
+      growTowardTarget({ start: 8, end: 12 }, target, { start: 0, end: 50 }, 0)
+    ).toEqual({ start: 0, end: 20 });
+  });
+
+  it('counts new visible items against the budget', () => {
+    // The 4 visible items are new, so only 1 more fits in a budget of 5.
+    expect(
+      growTowardTarget({ start: 8, end: 12 }, target, { start: 0, end: 0 }, 5)
+    ).toEqual({ start: 7, end: 12 });
+  });
+});
diff --git a/src/MiniFlatList/index.ts b/src/MiniFlatList/index.ts
new file mode 100644
index 0000000..2e04ce5
--- /dev/null
+++ b/src/MiniFlatList/index.ts
@@ -0,0 +1,6 @@
+export {
+  MiniFlatList,
+  defaultKeyExtractor,
+  type MiniFlatListProps,
+  type MiniFlatListRenderItemInfo,
+} from './MiniFlatList';
diff --git a/src/MiniFlatList/item-offsets.ts b/src/MiniFlatList/item-offsets.ts
new file mode 100644
index 0000000..d8493d0
--- /dev/null
+++ b/src/MiniFlatList/item-offsets.ts
@@ -0,0 +1,99 @@
+/** Size used for unmeasured items until at least one item has been measured. */
+export const DEFAULT_ITEM_SIZE = 50;
+
+/** A run of items from `start` (inclusive) to `end` (exclusive). */
+export interface ItemRange {
+  start: number;
+  end: number;
+}
+
+/**
+ * Computes where each item starts. `offsets[i]` is the start of item `i` and
+ * `offsets[itemCount]` is the total content size.
+ *
+ * Unmeasured items count as the average measured size, like in FlatList.
+ */
+export function computeItemOffsets(
+  keys: ReadonlyArray<string>,
+  sizes: ReadonlyMap<string, number>
+): number[] {
+  const estimatedSize = averageSize(sizes) ?? DEFAULT_ITEM_SIZE;
+
+  const offsets = [0];
+  for (let index = 0; index < keys.length; index += 1) {
+    const size = sizes.get(keys[index]!) ?? estimatedSize;
+    offsets.push(offsets[index]! + size);
+  }
+  return offsets;
+}
+
+function averageSize(sizes: ReadonlyMap<string, number>): number | undefined {
+  if (sizes.size === 0) {
+    return undefined;
+  }
+
+  let total = 0;
+  for (const size of sizes.values()) {
+    total += size;
+  }
+  return total / sizes.size;
+}
+
+/** Items that overlap the `[startOffset, endOffset)` area. */
+export function findItemsInArea(
+  offsets: ReadonlyArray<number>,
+  startOffset: number,
+  endOffset: number
+): ItemRange {
+  return {
+    start: findFirstItemEndingAfter(offsets, startOffset),
+    end: findFirstItemStartingAtOrAfter(offsets, endOffset),
+  };
+}
+
+/** The first item that ends after `offset`, i.e. the item at `offset`. */
+export function findFirstItemEndingAfter(
+  offsets: ReadonlyArray<number>,
+  offset: number
+): number {
+  return findFirstItem(offsets.length - 1, (index) => {
+    return offsets[index + 1]! > offset;
+  });
+}
+
+/** The first item that starts at or after `offset`. */
+export function findFirstItemStartingAtOrAfter(
+  offsets: ReadonlyArray<number>,
+  offset: number
+): number {
+  return findFirstItem(offsets.length - 1, (index) => {
+    return offsets[index]! >= offset;
+  });
+}
+
+/**
+ * Binary search for the first index in `[0, itemCount)` that matches
+ * `predicate`, or `itemCount` when none does. `predicate` must be false for
+ * every index before the first match and true for every index after it.
+ */
+function findFirstItem(
+  itemCount: number,
+  predicate: (index: number) => boolean
+): number {
+  let low = 0;
+  let high = itemCount;
+
+  // The answer is always in [low, high]. Halve that range until it is a single index.
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (predicate(middle)) {
+      // Match: the first match is `middle` or earlier.
+      high = middle;
+    } else {
+      // No match: the first match is after `middle`.
+      low = middle + 1;
+    }
+  }
+
+  return low;
+}
diff --git a/src/MiniFlatList/render-window.ts b/src/MiniFlatList/render-window.ts
new file mode 100644
index 0000000..7d6e29f
--- /dev/null
+++ b/src/MiniFlatList/render-window.ts
@@ -0,0 +1,120 @@
+import { findItemsInArea, type ItemRange } from './item-offsets';
+
+export interface ComputeRenderWindowParams {
+  /** Item start offsets from `computeItemOffsets`. */
+  offsets: ReadonlyArray<number>;
+  scrollOffset: number;
+  viewportSize: number;
+  /** Area to render, in viewports, centered on the visible one. */
+  windowSize: number;
+  /** Most items to add in one update. */
+  maxToRenderPerBatch: number;
+  /** Items to render before the viewport has been measured. */
+  initialNumToRender: number;
+  /** Currently rendered items. */
+  previous: ItemRange;
+}
+
+/**
+ * Picks the items to render next. It always renders every visible item, then
+ * grows toward `windowSize` viewports of items, adding at most
+ * `maxToRenderPerBatch` items that are not rendered yet. Calling it again with
+ * the result as `previous` renders the next batch, until the result stops
+ * changing.
+ */
+export function computeRenderWindow({
+  offsets,
+  scrollOffset,
+  viewportSize,
+  windowSize,
+  maxToRenderPerBatch,
+  initialNumToRender,
+  previous,
+}: ComputeRenderWindowParams): ItemRange {
+  const itemCount = offsets.length - 1;
+
+  // Viewport not measured yet: render the first few items.
+  if (viewportSize === 0) {
+    return { start: 0, end: Math.min(initialNumToRender, itemCount) };
+  }
+
+  // 1. Items on screen right now. They are always rendered.
+  const visible = findItemsInArea(
+    offsets,
+    scrollOffset,
+    scrollOffset + viewportSize
+  );
+
+  // 2. Items we would like to render: `windowSize` viewports in total.
+  const overscan = ((Math.max(windowSize, 1) - 1) / 2) * viewportSize;
+  const target = findItemsInArea(
+    offsets,
+    scrollOffset - overscan,
+    scrollOffset + viewportSize + overscan
+  );
+
+  // 3. Grow from the visible items toward the target, one batch at a time.
+  return growTowardTarget(visible, target, previous, maxToRenderPerBatch);
+}
+
+/**
+ * Grows `visible` one item at a time on each side until it covers `target`
+ * or `maxNewItems` new items have been added. Items already in `previous` are
+ * free: keeping them mounted costs no rendering.
+ */
+export function growTowardTarget(
+  visible: ItemRange,
+  target: ItemRange,
+  previous: ItemRange,
+  maxNewItems: number
+): ItemRange {
+  const isRendered = (index: number) =>
+    index >= previous.start && index < previous.end;
+
+  let { start, end } = visible;
+  let newItems = countNewItems(visible, previous);
+
+  let grew = true;
+  while (grew) {
+    grew = false;
+
+    // Add the item before the window, if it is free or within budget.
+    if (start > target.start) {
+      const isNew = !isRendered(start - 1);
+      if (!isNew || newItems < maxNewItems) {
+        start -= 1;
+        newItems += isNew ? 1 : 0;
+        grew = true;
+      }
+    }
+
+    // Same for the item after the window.
+    if (end < target.end) {
+      const isNew = !isRendered(end);
+      if (!isNew || newItems < maxNewItems) {
+        end += 1;
+        newItems += isNew ? 1 : 0;
+        grew = true;
+      }
+    }
+  }
+
+  return { start, end };
+}
+
+/** Number of items in `range` that are not in `previous`. */
+function countNewItems(range: ItemRange, previous: ItemRange): number {
+  const overlap = Math.max(
+    0,
+    Math.min(range.end, previous.end) - Math.max(range.start, previous.start)
+  );
+  return range.end - range.start - overlap;
+}
+
+export function isRangeInside(inner: ItemRange, outer: ItemRange): boolean {
+  return inner.start >= outer.start && inner.end <= outer.end;
+}
+
+export function isSameRange(a: ItemRange, b: ItemRange): boolean {
+  return a.start === b.start && a.end === b.end;
+}
diff --git a/src/index.tsx b/src/index.tsx
index 380f70c..c1ea753 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -3,3 +3,8 @@ export {
   type TinyListProps,
   type TinyListRenderItemInfo,
 } from './TinyList';
+export {
+  MiniFlatList,
+  type MiniFlatListProps,
+  type MiniFlatListRenderItemInfo,
+} from './MiniFlatList';

From 2319d1095f6dbdf0de9e8d346443ada94c2c8ad8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 4 Oct 2026 09:20:03 +0000
Subject: [PATCH 2/4] feat(MiniFlatList): keep the initialNumToRender items
 rendered

Like FlatList, the first initialNumToRender items stay mounted after the
window moves away, so scrolling back to the top shows them instantly. A
spacer stands in for the items between them and the window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EZxDtj1CphSjr2V67rdmFP
---
 README.md                                     |  1 +
 src/MiniFlatList/MiniFlatList.tsx             | 65 ++++++++++++-------
 .../__tests__/MiniFlatList.test.tsx           | 28 +++++++-
 .../__tests__/render-window.test.ts           | 33 +++++++++-
 src/MiniFlatList/render-window.ts             | 29 +++++++++
 5 files changed, 130 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 1ac1aef..b0c4d77 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,7 @@ import { MiniFlatList } from 'react-native-tiny-list';
   index) keys both the items and the cached sizes, so sizes survive inserts and
   reorders. Unmeasured items count as the average measured size.
 - **`initialNumToRender`.** Items rendered before the viewport is measured.
+  They stay rendered, so scrolling back to the top shows them instantly.
 - **`windowSize`.** The area kept rendered, in viewports, centered on the
   visible one.
 - **Batched rendering.** Scrolling does not re-render the list while the
diff --git a/src/MiniFlatList/MiniFlatList.tsx b/src/MiniFlatList/MiniFlatList.tsx
index e9e8d35..0006054 100644
--- a/src/MiniFlatList/MiniFlatList.tsx
+++ b/src/MiniFlatList/MiniFlatList.tsx
@@ -20,6 +20,7 @@ import {
   type ItemRange,
 } from './item-offsets';
 import {
+  addInitialItems,
   computeRenderWindow,
   isRangeInside,
   isSameRange,
@@ -38,7 +39,7 @@ export interface MiniFlatListProps<T> {
   keyExtractor?: (item: T, index: number) => string;
   /** Change it to re-render all items, e.g. when `renderItem` reads outside state. */
   extraData?: unknown;
-  /** Items rendered before the viewport is measured. */
+  /** Items rendered before the viewport is measured, and kept rendered after. */
   initialNumToRender?: number;
   /** Area to keep rendered, in viewports, centered on the visible one. */
   windowSize?: number;
@@ -55,6 +56,7 @@ export interface MiniFlatListProps<T> {
  * - caches item sizes by key, so they survive inserts and reorders;
  * - skips re-rendering on scroll unless the visible area is not rendered yet;
  * - fills the area off screen in small batches instead of all at once;
+ * - keeps the first `initialNumToRender` items rendered, for a fast scroll to top;
  * - memoizes items, so a batch renders only the new ones.
  */
 export function MiniFlatList<T>({
@@ -161,25 +163,30 @@ export function MiniFlatList<T>({
     }
   };
 
-  // `data` may have shrunk since the window was computed.
-  const start = Math.min(renderWindow.start, data.length);
-  const end = Math.min(renderWindow.end, data.length);
-
-  const cells: ReactNode[] = [];
-  for (let index = start; index < end; index++) {
-    const key = keys[index]!;
-    cells.push(
-      <Cell
-        key={key}
-        cellKey={key}
-        item={data[index] as T}
-        index={index}
-        renderItem={renderItem}
-        extraData={extraData}
-        onCellLayout={handleCellLayout}
-      />
-    );
-  }
+  const rendered = addInitialItems(
+    renderWindow,
+    initialNumToRender,
+    data.length
+  );
+
+  const renderCells = ({ start, end }: ItemRange) => {
+    const cells: ReactNode[] = [];
+    for (let index = start; index < end; index++) {
+      const key = keys[index]!;
+      cells.push(
+        <Cell
+          key={key}
+          cellKey={key}
+          item={data[index] as T}
+          index={index}
+          renderItem={renderItem}
+          extraData={extraData}
+          onCellLayout={handleCellLayout}
+        />
+      );
+    }
+    return cells;
+  };
 
   return (
     <ScrollView
@@ -189,9 +196,21 @@ export function MiniFlatList<T>({
       onLayout={handleLayout}
       scrollEventThrottle={16}
     >
-      <View style={{ height: offsets[start] }} />
-      {cells}
-      <View style={{ height: offsets[data.length]! - offsets[end]! }} />
+      {renderCells(rendered.initial)}
+      {/* Stands in for the items between the initial items and the window. */}
+      <View
+        style={{
+          height:
+            offsets[rendered.window.start]! - offsets[rendered.initial.end]!,
+        }}
+      />
+      {renderCells(rendered.window)}
+      {/* Stands in for the items after the window. */}
+      <View
+        style={{
+          height: offsets[data.length]! - offsets[rendered.window.end]!,
+        }}
+      />
     </ScrollView>
   );
 }
diff --git a/src/MiniFlatList/__tests__/MiniFlatList.test.tsx b/src/MiniFlatList/__tests__/MiniFlatList.test.tsx
index 7d56c91..82cc46f 100644
--- a/src/MiniFlatList/__tests__/MiniFlatList.test.tsx
+++ b/src/MiniFlatList/__tests__/MiniFlatList.test.tsx
@@ -97,7 +97,27 @@ describe('MiniFlatList', () => {
     // No timer advanced: the visible area was blank, so it renders now.
     await fireEvent(scrollView, 'scroll', scrollEvent(3000));
     expect(screen.getByText('Item 60')).toBeOnTheScreen();
-    expect(screen.queryByText('Item 0')).not.toBeOnTheScreen();
+    expect(screen.queryByText('Item 20')).not.toBeOnTheScreen();
+  });
+
+  it('keeps the first initialNumToRender items rendered', async () => {
+    const scrollView = await renderList({ initialNumToRender: 3 });
+    await fireEvent(scrollView, 'layout', layoutEvent(500));
+    await runNextBatch();
+
+    // Window is [2500, 4000) px: items 50..79, plus items 0..2.
+    await fireEvent(scrollView, 'scroll', scrollEvent(3000));
+    await runNextBatch();
+    await runNextBatch();
+    const items = renderedItems();
+    expect(items.slice(0, 4)).toEqual([
+      'Item 0',
+      'Item 1',
+      'Item 2',
+      'Item 50',
+    ]);
+    expect(items.at(-1)).toBe('Item 79');
+    expect(items).toHaveLength(33);
   });
 
   it('waits for the next batch when the visible items are rendered', async () => {
@@ -116,7 +136,10 @@ describe('MiniFlatList', () => {
   });
 
   it('keeps measured sizes with their item when data is reordered', async () => {
-    const scrollView = await renderList({ maxToRenderPerBatch: 100 });
+    const scrollView = await renderList({
+      initialNumToRender: 1,
+      maxToRenderPerBatch: 100,
+    });
     await fireEvent(scrollView, 'layout', layoutEvent(500));
     await runNextBatch();
 
@@ -140,6 +163,7 @@ describe('MiniFlatList', () => {
         data={reordered}
         renderItem={renderItem}
         windowSize={3}
+        initialNumToRender={1}
         maxToRenderPerBatch={100}
       />
     );
diff --git a/src/MiniFlatList/__tests__/render-window.test.ts b/src/MiniFlatList/__tests__/render-window.test.ts
index 7a97111..f002c5e 100644
--- a/src/MiniFlatList/__tests__/render-window.test.ts
+++ b/src/MiniFlatList/__tests__/render-window.test.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from '@jest/globals';
-import { computeRenderWindow, growTowardTarget } from '../render-window';
+import {
+  addInitialItems,
+  computeRenderWindow,
+  growTowardTarget,
+} from '../render-window';
 
 // 100 items of 100 px each.
 const OFFSETS = Array.from({ length: 101 }, (_, i) => i * 100);
@@ -89,3 +93,30 @@ describe('growTowardTarget', () => {
     ).toEqual({ start: 7, end: 12 });
   });
 });
+
+describe('addInitialItems', () => {
+  it('adds the initial items before a window further down', () => {
+    expect(addInitialItems({ start: 50, end: 80 }, 10, 100)).toEqual({
+      initial: { start: 0, end: 10 },
+      window: { start: 50, end: 80 },
+    });
+  });
+
+  it('removes initial items from a window that overlaps them', () => {
+    expect(addInitialItems({ start: 0, end: 30 }, 10, 100)).toEqual({
+      initial: { start: 0, end: 10 },
+      window: { start: 10, end: 30 },
+    });
+    expect(addInitialItems({ start: 0, end: 5 }, 10, 100)).toEqual({
+      initial: { start: 0, end: 10 },
+      window: { start: 10, end: 10 },
+    });
+  });
+
+  it('clamps both to the item count', () => {
+    expect(addInitialItems({ start: 50, end: 80 }, 10, 5)).toEqual({
+      initial: { start: 0, end: 5 },
+      window: { start: 5, end: 5 },
+    });
+  });
+});
diff --git a/src/MiniFlatList/render-window.ts b/src/MiniFlatList/render-window.ts
index 7d6e29f..b5c381d 100644
--- a/src/MiniFlatList/render-window.ts
+++ b/src/MiniFlatList/render-window.ts
@@ -102,6 +102,35 @@ export function growTowardTarget(
   return { start, end };
 }
 
+export interface RenderedItems {
+  /** The first `initialNumToRender` items. Always rendered. */
+  initial: ItemRange;
+  /** The render window, minus any items already in `initial`. */
+  window: ItemRange;
+}
+
+/**
+ * Like FlatList, keeps the first `initialNumToRender` items rendered so that
+ * scrolling back to the top shows them instantly. A spacer goes between them
+ * and the window when the two do not touch.
+ */
+export function addInitialItems(
+  window: ItemRange,
+  initialNumToRender: number,
+  itemCount: number
+): RenderedItems {
+  const initialEnd = Math.min(initialNumToRender, itemCount);
+
+  // `data` may have shrunk since the window was computed, so clamp it too.
+  const start = Math.min(Math.max(window.start, initialEnd), itemCount);
+  const end = Math.min(Math.max(window.end, start), itemCount);
+
+  return {
+    initial: { start: 0, end: initialEnd },
+    window: { start, end },
+  };
+}
+
 /** Number of items in `range` that are not in `previous`. */
 function countNewItems(range: ItemRange, previous: ItemRange): number {
   const overlap = Math.max(

From 9896ecad43650580eb8bb4f9dfd79b089cab8f52 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Tue, 6 Oct 2026 11:44:18 +0200
Subject: [PATCH 3/4] rename to tiny list

---
 README.md                                      |  8 ++++----
 example/src/App.tsx                            | 18 +++++++++---------
 package.json                                   |  2 +-
 src/MiniFlatList/index.ts                      |  6 ------
 .../TinyFlatList.tsx}                          | 12 ++++++------
 .../__tests__/TinyFlatList.test.tsx}           | 18 +++++++++---------
 .../__tests__/item-offsets.test.ts             |  0
 .../__tests__/render-window.test.ts            |  0
 src/TinyFlatList/index.ts                      |  6 ++++++
 .../item-offsets.ts                            |  0
 .../render-window.ts                           |  0
 src/index.tsx                                  |  8 ++++----
 12 files changed, 39 insertions(+), 39 deletions(-)
 delete mode 100644 src/MiniFlatList/index.ts
 rename src/{MiniFlatList/MiniFlatList.tsx => TinyFlatList/TinyFlatList.tsx} (96%)
 rename src/{MiniFlatList/__tests__/MiniFlatList.test.tsx => TinyFlatList/__tests__/TinyFlatList.test.tsx} (93%)
 rename src/{MiniFlatList => TinyFlatList}/__tests__/item-offsets.test.ts (100%)
 rename src/{MiniFlatList => TinyFlatList}/__tests__/render-window.test.ts (100%)
 create mode 100644 src/TinyFlatList/index.ts
 rename src/{MiniFlatList => TinyFlatList}/item-offsets.ts (100%)
 rename src/{MiniFlatList => TinyFlatList}/render-window.ts (100%)

diff --git a/README.md b/README.md
index b0c4d77..454246f 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # react-native-tiny-list
 
-Simple flat list component
+Tiny, readable virtualized lists for React Native
 
 ## Installation
 
@@ -29,9 +29,9 @@ area and replaces the rest with spacer views. Item heights are measured with
 Expect blank areas and content jumps while scrolling fast.
 
 ```tsx
-import { MiniFlatList } from 'react-native-tiny-list';
+import { TinyFlatList } from 'react-native-tiny-list';
 
-<MiniFlatList
+<TinyFlatList
   data={items}
   renderItem={renderRow} // keep it stable, not an inline function
   keyExtractor={(item) => item.id}
@@ -42,7 +42,7 @@ import { MiniFlatList } from 'react-native-tiny-list';
 />
 ```
 
-`MiniFlatList` adds the core ideas of React Native's `FlatList` on top of
+`TinyFlatList` adds the core ideas of React Native's `FlatList` on top of
 `TinyList`:
 
 - **Keys.** `keyExtractor` (default: `item.key`, then `item.id`, then the
diff --git a/example/src/App.tsx b/example/src/App.tsx
index 6bc583b..7c10e62 100644
--- a/example/src/App.tsx
+++ b/example/src/App.tsx
@@ -1,9 +1,9 @@
 import { useState } from 'react';
 import { Button, StyleSheet, Text, View } from 'react-native';
 import {
-  MiniFlatList,
+  TinyFlatList,
   TinyList,
-  type MiniFlatListRenderItemInfo,
+  type TinyFlatListRenderItemInfo,
 } from 'react-native-tiny-list';
 
 type Item = { id: number; title: string };
@@ -13,9 +13,9 @@ const DATA: Item[] = Array.from({ length: 10_000 }, (_, i) => ({
   title: `Item ${i}`,
 }));
 
-// Defined outside the component so it stays stable and MiniFlatList can skip
+// Defined outside the component so it stays stable and TinyFlatList can skip
 // re-rendering unchanged items.
-function renderItem({ item, index }: MiniFlatListRenderItemInfo<Item>) {
+function renderItem({ item, index }: TinyFlatListRenderItemInfo<Item>) {
   return (
     // Vary heights to exercise measurement.
     <View style={[styles.item, { height: 40 + (index % 5) * 15 }]}>
@@ -25,18 +25,18 @@ function renderItem({ item, index }: MiniFlatListRenderItemInfo<Item>) {
 }
 
 export default function App() {
-  const [list, setList] = useState<'tiny' | 'mini'>('mini');
+  const [list, setList] = useState<'list' | 'flatList'>('flatList');
 
   return (
     <View style={styles.container}>
       <View style={styles.toolbar}>
-        <Button title="TinyList" onPress={() => setList('tiny')} />
-        <Button title="MiniFlatList" onPress={() => setList('mini')} />
+        <Button title="TinyList" onPress={() => setList('list')} />
+        <Button title="TinyFlatList" onPress={() => setList('flatList')} />
       </View>
-      {list === 'tiny' ? (
+      {list === 'list' ? (
         <TinyList data={DATA} renderItem={renderItem} />
       ) : (
-        <MiniFlatList data={DATA} renderItem={renderItem} />
+        <TinyFlatList data={DATA} renderItem={renderItem} />
       )}
     </View>
   );
diff --git a/package.json b/package.json
index 141f761..5e15643 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "react-native-tiny-list",
   "version": "0.1.0",
-  "description": "Simple flat list component",
+  "description": "Tiny educational rebuilds of FlatList, FlashList and LegendList for React Native",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
   "exports": {
diff --git a/src/MiniFlatList/index.ts b/src/MiniFlatList/index.ts
deleted file mode 100644
index 2e04ce5..0000000
--- a/src/MiniFlatList/index.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-export {
-  MiniFlatList,
-  defaultKeyExtractor,
-  type MiniFlatListProps,
-  type MiniFlatListRenderItemInfo,
-} from './MiniFlatList';
diff --git a/src/MiniFlatList/MiniFlatList.tsx b/src/TinyFlatList/TinyFlatList.tsx
similarity index 96%
rename from src/MiniFlatList/MiniFlatList.tsx
rename to src/TinyFlatList/TinyFlatList.tsx
index 0006054..098837b 100644
--- a/src/MiniFlatList/MiniFlatList.tsx
+++ b/src/TinyFlatList/TinyFlatList.tsx
@@ -26,15 +26,15 @@ import {
   isSameRange,
 } from './render-window';
 
-export interface MiniFlatListRenderItemInfo<T> {
+export interface TinyFlatListRenderItemInfo<T> {
   item: T;
   index: number;
 }
 
-export interface MiniFlatListProps<T> {
+export interface TinyFlatListProps<T> {
   data: ReadonlyArray<T>;
   /** Keep it stable (not an inline function) so unchanged items skip re-rendering. */
-  renderItem: (info: MiniFlatListRenderItemInfo<T>) => ReactNode;
+  renderItem: (info: TinyFlatListRenderItemInfo<T>) => ReactNode;
   /** Unique key per item. Defaults to `item.key`, then `item.id`, then the index. */
   keyExtractor?: (item: T, index: number) => string;
   /** Change it to re-render all items, e.g. when `renderItem` reads outside state. */
@@ -59,7 +59,7 @@ export interface MiniFlatListProps<T> {
  * - keeps the first `initialNumToRender` items rendered, for a fast scroll to top;
  * - memoizes items, so a batch renders only the new ones.
  */
-export function MiniFlatList<T>({
+export function TinyFlatList<T>({
   data,
   renderItem,
   keyExtractor = defaultKeyExtractor,
@@ -68,7 +68,7 @@ export function MiniFlatList<T>({
   windowSize = 21,
   maxToRenderPerBatch = 10,
   updateCellsBatchingPeriod = 50,
-}: MiniFlatListProps<T>) {
+}: TinyFlatListProps<T>) {
   const [viewportSize, setViewportSize] = useState(0);
 
   // Read on demand instead of being state, so scrolling does not re-render.
@@ -232,7 +232,7 @@ interface CellProps<T> {
   cellKey: string;
   item: T;
   index: number;
-  renderItem: (info: MiniFlatListRenderItemInfo<T>) => ReactNode;
+  renderItem: (info: TinyFlatListRenderItemInfo<T>) => ReactNode;
   /** Unused here; a new value only makes `memo` re-render the cell. */
   extraData: unknown;
   onCellLayout: (key: string, event: LayoutChangeEvent) => void;
diff --git a/src/MiniFlatList/__tests__/MiniFlatList.test.tsx b/src/TinyFlatList/__tests__/TinyFlatList.test.tsx
similarity index 93%
rename from src/MiniFlatList/__tests__/MiniFlatList.test.tsx
rename to src/TinyFlatList/__tests__/TinyFlatList.test.tsx
index 82cc46f..9cd3c21 100644
--- a/src/MiniFlatList/__tests__/MiniFlatList.test.tsx
+++ b/src/TinyFlatList/__tests__/TinyFlatList.test.tsx
@@ -8,8 +8,8 @@ import {
 } from '@jest/globals';
 import { act, fireEvent, render, screen } from '@testing-library/react-native';
 import { Text } from 'react-native';
-import { MiniFlatList, type MiniFlatListProps } from '../MiniFlatList';
-import { defaultKeyExtractor } from '../MiniFlatList';
+import { TinyFlatList, type TinyFlatListProps } from '../TinyFlatList';
+import { defaultKeyExtractor } from '../TinyFlatList';
 
 type Item = { id: string; title: string };
 
@@ -28,9 +28,9 @@ function scrollEvent(y: number) {
   return { nativeEvent: { contentOffset: { x: 0, y } } };
 }
 
-async function renderList(props: Partial<MiniFlatListProps<Item>> = {}) {
+async function renderList(props: Partial<TinyFlatListProps<Item>> = {}) {
   const result = await render(
-    <MiniFlatList
+    <TinyFlatList
       data={DATA}
       renderItem={renderItem}
       windowSize={3}
@@ -53,7 +53,7 @@ function renderedItems(): string[] {
   });
 }
 
-describe('MiniFlatList', () => {
+describe('TinyFlatList', () => {
   beforeEach(() => {
     jest.useFakeTimers();
   });
@@ -159,7 +159,7 @@ describe('MiniFlatList', () => {
     // Move item 0 to the end. Its size moves with it, so items 1..20 fit.
     const reordered = [...DATA.slice(1), DATA[0]!];
     await screen.rerender(
-      <MiniFlatList
+      <TinyFlatList
         data={reordered}
         renderItem={renderItem}
         windowSize={3}
@@ -191,14 +191,14 @@ describe('MiniFlatList', () => {
       initialNumToRender: 2,
     };
 
-    await render(<MiniFlatList {...props} extraData={1} />);
+    await render(<TinyFlatList {...props} extraData={1} />);
     expect(calls).toEqual([0, 1]);
 
     calls.length = 0;
-    await screen.rerender(<MiniFlatList {...props} extraData={1} />);
+    await screen.rerender(<TinyFlatList {...props} extraData={1} />);
     expect(calls).toEqual([]);
 
-    await screen.rerender(<MiniFlatList {...props} extraData={2} />);
+    await screen.rerender(<TinyFlatList {...props} extraData={2} />);
     expect(calls).toEqual([0, 1]);
   });
 
diff --git a/src/MiniFlatList/__tests__/item-offsets.test.ts b/src/TinyFlatList/__tests__/item-offsets.test.ts
similarity index 100%
rename from src/MiniFlatList/__tests__/item-offsets.test.ts
rename to src/TinyFlatList/__tests__/item-offsets.test.ts
diff --git a/src/MiniFlatList/__tests__/render-window.test.ts b/src/TinyFlatList/__tests__/render-window.test.ts
similarity index 100%
rename from src/MiniFlatList/__tests__/render-window.test.ts
rename to src/TinyFlatList/__tests__/render-window.test.ts
diff --git a/src/TinyFlatList/index.ts b/src/TinyFlatList/index.ts
new file mode 100644
index 0000000..9ce03cd
--- /dev/null
+++ b/src/TinyFlatList/index.ts
@@ -0,0 +1,6 @@
+export {
+  TinyFlatList,
+  defaultKeyExtractor,
+  type TinyFlatListProps,
+  type TinyFlatListRenderItemInfo,
+} from './TinyFlatList';
diff --git a/src/MiniFlatList/item-offsets.ts b/src/TinyFlatList/item-offsets.ts
similarity index 100%
rename from src/MiniFlatList/item-offsets.ts
rename to src/TinyFlatList/item-offsets.ts
diff --git a/src/MiniFlatList/render-window.ts b/src/TinyFlatList/render-window.ts
similarity index 100%
rename from src/MiniFlatList/render-window.ts
rename to src/TinyFlatList/render-window.ts
diff --git a/src/index.tsx b/src/index.tsx
index c1ea753..526eff7 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -4,7 +4,7 @@ export {
   type TinyListRenderItemInfo,
 } from './TinyList';
 export {
-  MiniFlatList,
-  type MiniFlatListProps,
-  type MiniFlatListRenderItemInfo,
-} from './MiniFlatList';
+  TinyFlatList,
+  type TinyFlatListProps,
+  type TinyFlatListRenderItemInfo,
+} from './TinyFlatList';

From 95b893048f2e5634b220dcb57f11e694e4401b8d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Tue, 6 Oct 2026 13:02:59 +0200
Subject: [PATCH 4/4] readable

---
 .../__tests__/render-window.test.ts           |  7 ++
 src/TinyFlatList/render-window.ts             | 64 ++++++++++---------
 2 files changed, 42 insertions(+), 29 deletions(-)

diff --git a/src/TinyFlatList/__tests__/render-window.test.ts b/src/TinyFlatList/__tests__/render-window.test.ts
index f002c5e..16b828b 100644
--- a/src/TinyFlatList/__tests__/render-window.test.ts
+++ b/src/TinyFlatList/__tests__/render-window.test.ts
@@ -86,6 +86,13 @@ describe('growTowardTarget', () => {
     ).toEqual({ start: 0, end: 20 });
   });
 
+  it('drops rendered items that do not touch the visible ones', () => {
+    // Keeping 0..5 would also render the gap 5..8, which is not in the budget.
+    expect(
+      growTowardTarget({ start: 8, end: 12 }, target, { start: 0, end: 5 }, 0)
+    ).toEqual({ start: 8, end: 12 });
+  });
+
   it('counts new visible items against the budget', () => {
     // The 4 visible items are new, so only 1 more fits in a budget of 5.
     expect(
diff --git a/src/TinyFlatList/render-window.ts b/src/TinyFlatList/render-window.ts
index b5c381d..0d2238c 100644
--- a/src/TinyFlatList/render-window.ts
+++ b/src/TinyFlatList/render-window.ts
@@ -58,9 +58,9 @@ export function computeRenderWindow({
 }
 
 /**
- * Grows `visible` one item at a time on each side until it covers `target`
- * or `maxNewItems` new items have been added. Items already in `previous` are
- * free: keeping them mounted costs no rendering.
+ * Grows `visible` toward `target`, adding at most `maxNewItems` items that are
+ * not in `previous`. Items already in `previous` are free: keeping them
+ * mounted costs no rendering.
  */
 export function growTowardTarget(
   visible: ItemRange,
@@ -68,34 +68,25 @@ export function growTowardTarget(
   previous: ItemRange,
   maxNewItems: number
 ): ItemRange {
-  const isRendered = (index: number) =>
-    index >= previous.start && index < previous.end;
-
-  let { start, end } = visible;
-  let newItems = countNewItems(visible, previous);
-
-  let grew = true;
-  while (grew) {
-    grew = false;
-
-    // Add the item before the window, if it is free or within budget.
+  // 1. Keep the rendered items that are still in the target, if they touch
+  //    the visible ones. Every item outside this range is new.
+  const kept = intersectRanges(previous, target);
+  let { start, end } = rangesTouch(kept, visible)
+    ? joinRanges(kept, visible)
+    : visible;
+
+  // 2. New visible items use up the budget first.
+  let budget = maxNewItems - countNewItems(visible, previous);
+
+  // 3. Spend the rest on new items, one on each side in turn.
+  while (budget > 0 && (start > target.start || end < target.end)) {
     if (start > target.start) {
-      const isNew = !isRendered(start - 1);
-      if (!isNew || newItems < maxNewItems) {
-        start -= 1;
-        newItems += isNew ? 1 : 0;
-        grew = true;
-      }
+      start -= 1;
+      budget -= 1;
     }
-
-    // Same for the item after the window.
-    if (end < target.end) {
-      const isNew = !isRendered(end);
-      if (!isNew || newItems < maxNewItems) {
-        end += 1;
-        newItems += isNew ? 1 : 0;
-        grew = true;
-      }
+    if (budget > 0 && end < target.end) {
+      end += 1;
+      budget -= 1;
     }
   }
 
@@ -140,6 +131,21 @@ function countNewItems(range: ItemRange, previous: ItemRange): number {
   return range.end - range.start - overlap;
 }
 
+function intersectRanges(a: ItemRange, b: ItemRange): ItemRange {
+  const start = Math.max(a.start, b.start);
+  return { start, end: Math.max(start, Math.min(a.end, b.end)) };
+}
+
+/** True when `a` is not empty and overlaps or sits right next to `b`. */
+function rangesTouch(a: ItemRange, b: ItemRange): boolean {
+  return a.start < a.end && a.start <= b.end && a.end >= b.start;
+}
+
+/** The smallest range covering both `a` and `b`. */
+function joinRanges(a: ItemRange, b: ItemRange): ItemRange {
+  return { start: Math.min(a.start, b.start), end: Math.max(a.end, b.end) };
+}
+
 export function isRangeInside(inner: ItemRange, outer: ItemRange): boolean {
   return inner.start >= outer.start && inner.end <= outer.end;
 }