Module list 

The WINDOWED List: the core lays out only the visible range plus overscan, reports the content extent, and memoizes item extents per key so a scroll step is constant work.

Round 2 (docs/round-2-contract.md §4–5, src/list.ts): the LIST numbers every renderer shares — template item keys and instance suffixes (duplicates and empty keys → #<index>, suffixes ACCUMULATE through nested templates), Table row keys, the one-axis virtual window (vertical OR horizontal), scrollToIndex offsets, sections and the sticky header. fixtures/template-items.json and fixtures/virtual-list.json lock them.

Structs

ListSection

Consecutive items sharing a sectionBy value.

ListWindow

StickyHeader

The pinned header at a scroll offset: row (a flat row index) drawn at offset on the list’s axis.

TemplateInstance

One item a template renders.

VisibleRange

WindowRange

The window over a list: items start..end render, before/after = the spacers, total = the content length.

Enums

ScrollAlign

How scrollToIndex aligns the item.

SectionRow

A flat row of a sectioned list: a section header or a data item.

Constants

DEFAULT_ESTIMATED_ITEM_HEIGHT

The extent an unmeasured item takes when no theme says $control.row.

DEFAULT_OVERSCAN

Items rendered beyond each viewport edge (layout.json windowOverscan).

WINDOW_THRESHOLD

Lists and Tables with more items than this window (layout.json windowThreshold).

Functions

instance_segment

A key as one instance-suffix segment: ~ → ~0, . → ~1 (as JSON pointer escapes /), so dotted keys never collide across nesting levels (a.b + c vs a + b.c). The reference’s instanceSegment.

item_extents

Every item’s extent on the list’s axis: a measured item (Some) keeps its extent; an unmeasured one takes the MEAN measured extent once any item is measured (the content length stays stable while rows measure in), else row (the theme’s $control.row). ListWindow applies the same rule. Mirrors itemExtents (round 2 §5, virtual-list.json).

item_offsets

Start offsets of items laid end to end with gap between them (a divided list adds $control.hairline to the gap): offsets[i] = where item i starts, offsets[count] = the content length.

list_sections

Consecutive items with the same section_by value (a pointer relative to each item) form a section; the data order is kept.

scroll_offset_at

scroll_offset_for_index for an item at top with extent size in content of length total (O(1) over cached offsets).

scroll_offset_for_index

The scroll offset that brings item index into a viewport at scroll (scrollToIndex): start = its start at the viewport start after inset (the pinned header), end, center, nearest = the smallest move (none when visible). Clamped to [0, max(0, total - viewport)].

scroll_offset_for_item

scrollToIndex on a SECTIONED list: the DATA index → its flat row (section_rows; absent → scroll, no move), then scroll_offset_for_index over the rows’ extents with inset = the extent of the item’s own section header when headers are sticky (it pins over the item), else 0. The reference’s scrollOffsetForItem.

section_rows

The flat ROW list a sectioned list windows: a header before each section’s items.

sticky_header

The LAST header row starting at or before scroll pins at the viewport start, pushed back by the next header (min(scroll, nextStart − extent)). row_offsets = item_offsets of the flat rows, header_rows ascending. None before the first header.

sticky_header_by

sticky_header over accessors: only the header rows are read (binary search; O(log headers)).

table_row_keys

Table row keys: the row_key FIELD (default id) under the same rules.

template_instances

The items a template renders in a data scope: one per array item at template.path (relative to scope), keyed by template.key; instance = the suffix of the item the template sits in (`` at the top). The key is escaped by instance_segment.

template_item_keys

The instance key of every item: the value at key_pointer (relative to the item; objects as their JSON) — #<index> when that value is missing, null, `` or a DUPLICATE of an earlier item’s key (more #s until unique); without a pointer, the index. templateItemKeys.

virtual_window

The items to render for a viewport [scroll, scroll + viewport) on the list’s axis (relative to its content start): every item intersecting it (an item ending exactly at scroll counts) plus overscan on each side. virtualWindow.