@foldkit/ui 0.166.0-canary.fe2701c2fa4b → 0.167.0

package/dist/virtualList/index.js

@@ -1,28 +1,87 @@
 import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
-import { Array, Effect, Number, Option, Queue, Schema, Stream, pipe, } from 'effect';
+import { Array, Effect, HashSet, Match, Number, Option, Queue, Record, Schema, Stream, pipe, } from 'effect';
+import { Update } from 'foldkit';
 import * as Command from 'foldkit/command';
 import { childAttributes, } from 'foldkit/html';
 import { defineMessageUnion } from 'foldkit/message';
+import * as Mount from 'foldkit/mount';
+import * as Render from 'foldkit/render';
 import { defineTaggedUnion } from 'foldkit/schema';
 import { modifyFields } from 'foldkit/struct';
 import { defineView } from 'foldkit/submodel';
-import * as Subscription from 'foldkit/subscription';
 // MODEL
 /** Measurement state of the virtual list's scrollable container.
  *
- * Before the container's `ResizeObserver` fires for the first time we don't
- * know its height and cannot compute a visible slice. The view must handle
- * `Unmeasured` explicitly, typically by rendering a placeholder until the
- * first measurement arrives.
+ * Before the Mount reports the container's dimensions we cannot compute a
+ * visible slice. The view handles `Unmeasured` by rendering an empty
+ * container until the first measurement arrives.
  */
 const Measurement = defineTaggedUnion({
     Unmeasured: {},
-    Measured: { containerHeight: Schema.Number },
+    Measured: {
+        containerWidth: Schema.Number,
+        containerHeight: Schema.Number,
+    },
+});
+/** Alignment of a row within the viewport after a programmatic scroll. */
+export const ScrollAlignment = Schema.Literals([
+    'Start',
+    'Center',
+    'End',
+    'Nearest',
+]);
+/** Logical destination for initial and programmatic scrolling. */
+export const ScrollTarget = defineTaggedUnion({
+    Index: { index: Schema.Number },
+    Key: { key: Schema.String },
+    Offset: { offset: Schema.Number },
+    End: {},
+});
+const ViewportAnchor = defineTaggedUnion({
+    Offset: { scrollTop: Schema.Number },
+    Row: {
+        key: Schema.String,
+        index: Schema.Number,
+        viewportOffset: Schema.Number,
+    },
+    End: {},
+});
+const ObservedAnchor = defineTaggedUnion({
+    None: {},
+    Row: {
+        key: Schema.String,
+        index: Schema.Number,
+        viewportOffset: Schema.Number,
+    },
+});
+/** Outcome of applying a logical scroll request after the view commits. */
+export const ApplyScrollOutcome = defineTaggedUnion({
+    Applied: {
+        scrollTop: Schema.Number,
+        scrollHeight: Schema.Number,
+        containerHeight: Schema.Number,
+        anchor: ObservedAnchor,
+    },
+    Skipped: {},
+});
+const ScrollRequest = defineTaggedUnion({
+    Target: {
+        target: ScrollTarget,
+        alignment: ScrollAlignment,
+    },
+    Anchor: { anchor: ViewportAnchor },
 });
-/** State of a programmatic scroll initiated by `scrollToIndex`. */
 const PendingScroll = defineTaggedUnion({
     Idle: {},
-    ScrollingToIndex: { index: Schema.Number, version: Schema.Number },
+    Pending: { request: ScrollRequest, version: Schema.Number },
+});
+const InitialScroll = defineTaggedUnion({
+    Applied: {},
+    Pending: { target: ScrollTarget, alignment: ScrollAlignment },
+});
+const EndBehavior = defineTaggedUnion({
+    PreserveAnchor: {},
+    Follow: { thresholdPx: Schema.Number },
 });
 /** Schema for the virtual list's state. Tracks scroll position, container
  *  measurement, and any in-flight programmatic scroll. */
@@ -31,316 +90,636 @@ export const Model = Schema.Struct({
     rowHeightPx: Schema.Number,
     scrollTop: Schema.Number,
     measurement: Measurement,
+    viewportAnchor: ViewportAnchor,
+    measuredRowHeights: Schema.Record(Schema.String, Schema.Number),
+    layoutVersion: Schema.Number,
+    initialScroll: InitialScroll,
+    endBehavior: EndBehavior,
     pendingScroll: PendingScroll,
     pendingScrollVersion: Schema.Number,
 });
 // MESSAGE
 /** Union of all messages the virtual list component can produce. */
 export const Message = defineMessageUnion({
-    ScrolledContainer: { scrollTop: Schema.Number },
-    MeasuredContainer: { containerHeight: Schema.Number },
-    CompletedApplyScroll: { version: Schema.Number },
+    ObservedContainerScroll: {
+        scrollTop: Schema.Number,
+        scrollHeight: Schema.Number,
+        containerHeight: Schema.Number,
+        anchor: ObservedAnchor,
+    },
+    ResizedContainer: {
+        containerWidth: Schema.Number,
+        containerHeight: Schema.Number,
+    },
+    MeasuredRows: {
+        measurements: Schema.Array(Schema.Struct({
+            key: Schema.String,
+            height: Schema.Number,
+            layoutVersion: Schema.Number,
+        })),
+    },
+    CompletedApplyScroll: {
+        version: Schema.Number,
+        outcome: ApplyScrollOutcome,
+    },
 });
+const initialScrollFromConfig = (config) => {
+    if (config.initialScroll !== undefined) {
+        return __foldkitBrandViewResult((InitialScroll.Pending({
+            target: config.initialScroll.target,
+            alignment: config.initialScroll.alignment ?? 'Start',
+        })), "@foldkit/ui/virtualList/index.js#initialScrollFromConfig");
+    }
+    if (config.initialScrollTop !== undefined) {
+        return __foldkitBrandViewResult((InitialScroll.Pending({
+            target: ScrollTarget.Offset({ offset: config.initialScrollTop }),
+            alignment: 'Start',
+        })), "@foldkit/ui/virtualList/index.js#initialScrollFromConfig");
+    }
+    return __foldkitBrandViewResult((InitialScroll.Applied()), "@foldkit/ui/virtualList/index.js#initialScrollFromConfig");
+};
 /** Creates an initial virtual list model from a config. The container starts
- *  in `Unmeasured` state. The first `ResizeObserver` entry transitions it to
- *  `Measured`. */
-export const init = (config) => (__foldkitBrandViewResult(({
-    id: config.id,
-    rowHeightPx: config.rowHeightPx,
-    scrollTop: config.initialScrollTop ?? 0,
-    measurement: Measurement.Unmeasured(),
-    pendingScroll: PendingScroll.Idle(),
-    pendingScrollVersion: 0,
-}), "@foldkit/ui/virtualList/index.js#init"));
+ *  in `Unmeasured` state until its Mount reports the first measurement. */
+export const init = (config) => {
+    const initialScroll = initialScrollFromConfig(config);
+    return __foldkitBrandViewResult(({
+        id: config.id,
+        rowHeightPx: config.rowHeightPx,
+        scrollTop: config.initialScrollTop ?? 0,
+        measurement: Measurement.Unmeasured(),
+        viewportAnchor: ViewportAnchor.Offset({
+            scrollTop: config.initialScrollTop ?? 0,
+        }),
+        measuredRowHeights: Record.empty(),
+        layoutVersion: 0,
+        initialScroll,
+        endBehavior: config.followEnd === undefined
+            ? EndBehavior.PreserveAnchor()
+            : EndBehavior.Follow({
+                thresholdPx: config.followEnd.thresholdPx ?? 1,
+            }),
+        pendingScroll: PendingScroll.Idle(),
+        pendingScrollVersion: 0,
+    }), "@foldkit/ui/virtualList/index.js#init");
+};
 // UPDATE
+const scrollTopForNearestAlignment = (currentScrollTop, containerHeight, startOffset, endOffset) => {
+    const viewportEnd = currentScrollTop + containerHeight;
+    const rowSpansViewport = startOffset < currentScrollTop && endOffset > viewportEnd;
+    if (rowSpansViewport) {
+        return __foldkitBrandViewResult((currentScrollTop), "@foldkit/ui/virtualList/index.js#scrollTopForNearestAlignment");
+    }
+    if (startOffset < currentScrollTop) {
+        return __foldkitBrandViewResult((startOffset), "@foldkit/ui/virtualList/index.js#scrollTopForNearestAlignment");
+    }
+    if (endOffset > viewportEnd) {
+        return __foldkitBrandViewResult((endOffset - containerHeight), "@foldkit/ui/virtualList/index.js#scrollTopForNearestAlignment");
+    }
+    return __foldkitBrandViewResult((currentScrollTop), "@foldkit/ui/virtualList/index.js#scrollTopForNearestAlignment");
+};
+const scrollTopForRow = (currentScrollTop, containerHeight, startOffset, endOffset, alignment) => {
+    const targetScrollTop = Match.value(alignment).pipe(Match.withReturnType(), Match.when('Start', () => __foldkitBrandViewResult((startOffset), "@foldkit/ui/virtualList/index.js#anonymous")), Match.when('Center', () => __foldkitBrandViewResult((startOffset + (endOffset - startOffset - containerHeight) / 2), "@foldkit/ui/virtualList/index.js#anonymous~2")), Match.when('End', () => __foldkitBrandViewResult((endOffset - containerHeight), "@foldkit/ui/virtualList/index.js#anonymous~3")), Match.when('Nearest', () => __foldkitBrandViewResult((scrollTopForNearestAlignment(currentScrollTop, containerHeight, startOffset, endOffset)), "@foldkit/ui/virtualList/index.js#anonymous~4")), Match.exhaustive);
+    return __foldkitBrandViewResult((Math.max(0, targetScrollTop)), "@foldkit/ui/virtualList/index.js#scrollTopForRow");
+};
+const renderedRows = (element) => __foldkitBrandViewResult((pipe(element.children, Array.fromIterable, Array.filter((row) => __foldkitBrandViewResult((row instanceof HTMLElement &&
+    row.hasAttribute('data-virtual-list-item-key')), "@foldkit/ui/virtualList/index.js#anonymous~5")))), "@foldkit/ui/virtualList/index.js#renderedRows");
+const rowIndex = (element) => __foldkitBrandViewResult((pipe(element.getAttribute('data-virtual-list-item-index'), Option.fromNullishOr, Option.flatMap(Number.parse))), "@foldkit/ui/virtualList/index.js#rowIndex");
+const observedAnchor = (element) => {
+    const containerRect = element.getBoundingClientRect();
+    const viewportTop = containerRect.top + element.clientTop;
+    const viewportBottom = viewportTop + element.clientHeight;
+    const maybeRow = Array.findFirst(renderedRows(element), row => {
+        const rowRect = row.getBoundingClientRect();
+        return __foldkitBrandViewResult((rowRect.bottom > viewportTop && rowRect.top < viewportBottom), "@foldkit/ui/virtualList/index.js#anonymous~6");
+    });
+    if (Option.isNone(maybeRow)) {
+        return __foldkitBrandViewResult((ObservedAnchor.None()), "@foldkit/ui/virtualList/index.js#observedAnchor");
+    }
+    const key = maybeRow.value.getAttribute('data-virtual-list-item-key');
+    const maybeIndex = rowIndex(maybeRow.value);
+    if (key === null || Option.isNone(maybeIndex)) {
+        return __foldkitBrandViewResult((ObservedAnchor.None()), "@foldkit/ui/virtualList/index.js#observedAnchor");
+    }
+    return __foldkitBrandViewResult((ObservedAnchor.Row({
+        key,
+        index: maybeIndex.value,
+        viewportOffset: maybeRow.value.getBoundingClientRect().top - viewportTop,
+    })), "@foldkit/ui/virtualList/index.js#observedAnchor");
+};
+const maxScrollTop = (element) => __foldkitBrandViewResult((Math.max(0, element.scrollHeight - element.clientHeight)), "@foldkit/ui/virtualList/index.js#maxScrollTop");
+const clampScrollTop = (element, scrollTop) => __foldkitBrandViewResult((Math.max(0, Math.min(scrollTop, maxScrollTop(element)))), "@foldkit/ui/virtualList/index.js#clampScrollTop");
+const rowForIndex = (element, index) => {
+    const rows = renderedRows(element);
+    const maybeExact = Array.findFirst(rows, row => __foldkitBrandViewResult((Option.exists(rowIndex(row), rowIndex => __foldkitBrandViewResult((rowIndex === index), "@foldkit/ui/virtualList/index.js#anonymous~8"))), "@foldkit/ui/virtualList/index.js#anonymous~7"));
+    if (Option.isSome(maybeExact)) {
+        return __foldkitBrandViewResult((maybeExact), "@foldkit/ui/virtualList/index.js#rowForIndex");
+    }
+    const maybeFirst = Array.head(rows);
+    const maybeLast = Array.last(rows);
+    if (Option.isSome(maybeFirst)) {
+        const maybeFirstIndex = rowIndex(maybeFirst.value);
+        if (Option.isSome(maybeFirstIndex) && index < maybeFirstIndex.value) {
+            return __foldkitBrandViewResult((maybeFirst), "@foldkit/ui/virtualList/index.js#rowForIndex");
+        }
+    }
+    if (Option.isSome(maybeLast)) {
+        const maybeLastIndex = rowIndex(maybeLast.value);
+        if (Option.isSome(maybeLastIndex) && index > maybeLastIndex.value) {
+            return __foldkitBrandViewResult((maybeLast), "@foldkit/ui/virtualList/index.js#rowForIndex");
+        }
+    }
+    return __foldkitBrandViewResult((Option.none()), "@foldkit/ui/virtualList/index.js#rowForIndex");
+};
+const rowForKey = (element, key) => __foldkitBrandViewResult((Array.findFirst(renderedRows(element), row => __foldkitBrandViewResult((row.getAttribute('data-virtual-list-item-key') === key), "@foldkit/ui/virtualList/index.js#anonymous~9"))), "@foldkit/ui/virtualList/index.js#rowForKey");
+const rowOffsets = (container, row) => {
+    const viewportTop = container.getBoundingClientRect().top + container.clientTop;
+    const rowRect = row.getBoundingClientRect();
+    const startOffset = container.scrollTop + rowRect.top - viewportTop;
+    return __foldkitBrandViewResult(({ startOffset, endOffset: startOffset + rowRect.height }), "@foldkit/ui/virtualList/index.js#rowOffsets");
+};
+const rowForTarget = (element, target) => __foldkitBrandViewResult((ScrollTarget.matchOrElse(target, {
+    Index: ({ index }) => __foldkitBrandViewResult((rowForIndex(element, index)), "@foldkit/ui/virtualList/index.js#Index"),
+    Key: ({ key }) => __foldkitBrandViewResult((rowForKey(element, key)), "@foldkit/ui/virtualList/index.js#Key"),
+}, () => __foldkitBrandViewResult((Option.none()), "@foldkit/ui/virtualList/index.js#anonymous~10"))), "@foldkit/ui/virtualList/index.js#rowForTarget");
+const scrollTopForRowTarget = (element, target, alignment) => __foldkitBrandViewResult((Option.map(rowForTarget(element, target), row => {
+    const offsets = rowOffsets(element, row);
+    return __foldkitBrandViewResult((scrollTopForRow(element.scrollTop, element.clientHeight, offsets.startOffset, offsets.endOffset, alignment)), "@foldkit/ui/virtualList/index.js#anonymous~11");
+})), "@foldkit/ui/virtualList/index.js#scrollTopForRowTarget");
+const scrollTopForTarget = (element, target, alignment) => __foldkitBrandViewResult((ScrollTarget.match(target, {
+    Index: indexTarget => __foldkitBrandViewResult((scrollTopForRowTarget(element, indexTarget, alignment)), "@foldkit/ui/virtualList/index.js#Index~2"),
+    Key: keyTarget => __foldkitBrandViewResult((scrollTopForRowTarget(element, keyTarget, alignment)), "@foldkit/ui/virtualList/index.js#Key~2"),
+    Offset: ({ offset }) => __foldkitBrandViewResult((Option.some(offset)), "@foldkit/ui/virtualList/index.js#Offset"),
+    End: () => __foldkitBrandViewResult((Option.some(maxScrollTop(element))), "@foldkit/ui/virtualList/index.js#End"),
+})), "@foldkit/ui/virtualList/index.js#scrollTopForTarget");
+const rowForAnchor = (element, anchor) => __foldkitBrandViewResult((Option.orElse(rowForKey(element, anchor.key), () => __foldkitBrandViewResult((rowForIndex(element, anchor.index)), "@foldkit/ui/virtualList/index.js#anonymous~12"))), "@foldkit/ui/virtualList/index.js#rowForAnchor");
+const scrollTopForAnchor = (element, anchor) => __foldkitBrandViewResult((ViewportAnchor.match(anchor, {
+    Offset: ({ scrollTop }) => __foldkitBrandViewResult((Option.some(scrollTop)), "@foldkit/ui/virtualList/index.js#Offset~2"),
+    Row: rowAnchor => __foldkitBrandViewResult((Option.map(rowForAnchor(element, rowAnchor), row => __foldkitBrandViewResult((Math.max(0, rowOffsets(element, row).startOffset - rowAnchor.viewportOffset)), "@foldkit/ui/virtualList/index.js#anonymous~13"))), "@foldkit/ui/virtualList/index.js#Row"),
+    End: () => __foldkitBrandViewResult((Option.some(maxScrollTop(element))), "@foldkit/ui/virtualList/index.js#End~2"),
+})), "@foldkit/ui/virtualList/index.js#scrollTopForAnchor");
+const scrollTopForRequest = (element, request) => __foldkitBrandViewResult((ScrollRequest.match(request, {
+    Target: ({ target, alignment }) => __foldkitBrandViewResult((scrollTopForTarget(element, target, alignment)), "@foldkit/ui/virtualList/index.js#Target"),
+    Anchor: ({ anchor }) => __foldkitBrandViewResult((scrollTopForAnchor(element, anchor)), "@foldkit/ui/virtualList/index.js#Anchor"),
+})), "@foldkit/ui/virtualList/index.js#scrollTopForRequest");
+const mountedContainers = new Map();
 export const ApplyScroll = Command.define('ApplyScroll', {
-    args: { id: Schema.String, scrollTop: Schema.Number, version: Schema.Number },
+    args: {
+        id: Schema.String,
+        request: ScrollRequest,
+        version: Schema.Number,
+    },
     messages: [Message.CompletedApplyScroll],
-    execute: ({ id, scrollTop, version }) => __foldkitBrandViewResult((Effect.sync(() => {
-        const element = document.getElementById(id);
-        if (element !== null) {
-            element.scrollTop = scrollTop;
+    execute: ({ id, request, version }) => __foldkitBrandViewResult((Effect.gen(function* () {
+        yield* Render.afterCommit;
+        const containers = mountedContainers.get(id);
+        if (containers === undefined || containers.size !== 1) {
+            return __foldkitBrandViewResult((Message.CompletedApplyScroll({
+                version,
+                outcome: ApplyScrollOutcome.Skipped(),
+            })), "@foldkit/ui/virtualList/index.js#anonymous~14");
         }
-        return __foldkitBrandViewResult((Message.CompletedApplyScroll({ version })), "@foldkit/ui/virtualList/index.js#anonymous");
-    })), "@foldkit/ui/virtualList/index.js#execute"),
-});
-/** Processes a VirtualList Message and returns the next Model and optional Commands. */
-export const update = (model, message) => __foldkitBrandViewResult((Message.match(message, {
-    ScrolledContainer: ({ scrollTop }) => (__foldkitBrandViewResult(({
-        model: modifyFields(model, { scrollTop: () => __foldkitBrandViewResult((scrollTop), "@foldkit/ui/virtualList/index.js#scrollTop") }),
-    }), "@foldkit/ui/virtualList/index.js#ScrolledContainer")),
-    MeasuredContainer: ({ containerHeight }) => {
-        const wasUnmeasured = model.measurement._tag === 'Unmeasured';
-        const needsInitialApply = wasUnmeasured && model.scrollTop !== 0;
-        if (needsInitialApply) {
-            const nextVersion = Number.increment(model.pendingScrollVersion);
-            return __foldkitBrandViewResult(({
-                model: modifyFields(model, {
-                    measurement: () => __foldkitBrandViewResult((Measurement.Measured({ containerHeight })), "@foldkit/ui/virtualList/index.js#measurement"),
-                    pendingScrollVersion: () => __foldkitBrandViewResult((nextVersion), "@foldkit/ui/virtualList/index.js#pendingScrollVersion"),
-                    pendingScroll: () => __foldkitBrandViewResult((PendingScroll.ScrollingToIndex({
-                        index: Math.floor(model.scrollTop / model.rowHeightPx),
-                        version: nextVersion,
-                    })), "@foldkit/ui/virtualList/index.js#pendingScroll"),
-                }),
-                commands: [
-                    ApplyScroll({
-                        id: model.id,
-                        scrollTop: model.scrollTop,
-                        version: nextVersion,
-                    }),
-                ],
-            }), "@foldkit/ui/virtualList/index.js#MeasuredContainer");
+        const maybeElement = pipe(containers, Array.fromIterable, Array.head);
+        if (Option.isNone(maybeElement)) {
+            return __foldkitBrandViewResult((Message.CompletedApplyScroll({
+                version,
+                outcome: ApplyScrollOutcome.Skipped(),
+            })), "@foldkit/ui/virtualList/index.js#anonymous~14");
         }
-        else {
-            return __foldkitBrandViewResult(({
-                model: modifyFields(model, {
-                    measurement: () => __foldkitBrandViewResult((Measurement.Measured({ containerHeight })), "@foldkit/ui/virtualList/index.js#measurement~2"),
-                }),
-            }), "@foldkit/ui/virtualList/index.js#MeasuredContainer");
+        const element = maybeElement.value;
+        const maybeActiveVersion = pipe(element.getAttribute('data-virtual-list-scroll-version'), Option.fromNullishOr, Option.flatMap(Number.parse));
+        if (Option.isNone(maybeActiveVersion) ||
+            maybeActiveVersion.value !== version) {
+            return __foldkitBrandViewResult((Message.CompletedApplyScroll({
+                version,
+                outcome: ApplyScrollOutcome.Skipped(),
+            })), "@foldkit/ui/virtualList/index.js#anonymous~14");
         }
-    },
-    CompletedApplyScroll: ({ version }) => {
-        if (version !== model.pendingScrollVersion) {
-            return __foldkitBrandViewResult(({ model }), "@foldkit/ui/virtualList/index.js#CompletedApplyScroll");
-        }
-        else {
-            return __foldkitBrandViewResult(({
-                model: modifyFields(model, {
-                    pendingScroll: () => __foldkitBrandViewResult((PendingScroll.Idle()), "@foldkit/ui/virtualList/index.js#pendingScroll~2"),
-                }),
-            }), "@foldkit/ui/virtualList/index.js#CompletedApplyScroll");
+        const maybeScrollTop = scrollTopForRequest(element, request);
+        if (Option.isNone(maybeScrollTop)) {
+            return __foldkitBrandViewResult((Message.CompletedApplyScroll({
+                version,
+                outcome: ApplyScrollOutcome.Skipped(),
+            })), "@foldkit/ui/virtualList/index.js#anonymous~14");
         }
-    },
-})), "@foldkit/ui/virtualList/index.js#update");
-const buildScrollToIndex = (model, index, targetScrollTop) => {
+        element.scrollTop = clampScrollTop(element, maybeScrollTop.value);
+        return __foldkitBrandViewResult((Message.CompletedApplyScroll({
+            version,
+            outcome: ApplyScrollOutcome.Applied({
+                scrollTop: element.scrollTop,
+                scrollHeight: element.scrollHeight,
+                containerHeight: element.clientHeight,
+                anchor: observedAnchor(element),
+            }),
+        })), "@foldkit/ui/virtualList/index.js#anonymous~14");
+    })), "@foldkit/ui/virtualList/index.js#execute"),
+});
+const buildScrollRequest = (model, request) => {
     const nextVersion = Number.increment(model.pendingScrollVersion);
     return __foldkitBrandViewResult(({
         model: modifyFields(model, {
-            pendingScrollVersion: () => __foldkitBrandViewResult((nextVersion), "@foldkit/ui/virtualList/index.js#pendingScrollVersion~2"),
-            pendingScroll: () => __foldkitBrandViewResult((PendingScroll.ScrollingToIndex({ index, version: nextVersion })), "@foldkit/ui/virtualList/index.js#pendingScroll~3"),
+            pendingScrollVersion: () => __foldkitBrandViewResult((nextVersion), "@foldkit/ui/virtualList/index.js#pendingScrollVersion"),
+            pendingScroll: () => __foldkitBrandViewResult((PendingScroll.Pending({ request, version: nextVersion })), "@foldkit/ui/virtualList/index.js#pendingScroll"),
         }),
         commands: [
             ApplyScroll({
                 id: model.id,
-                scrollTop: targetScrollTop,
+                request,
                 version: nextVersion,
             }),
         ],
-    }), "@foldkit/ui/virtualList/index.js#buildScrollToIndex");
+    }), "@foldkit/ui/virtualList/index.js#buildScrollRequest");
+};
+const currentScrollRequest = (model) => __foldkitBrandViewResult((PendingScroll.match(model.pendingScroll, {
+    Idle: () => __foldkitBrandViewResult((InitialScroll.match(model.initialScroll, {
+        Applied: () => __foldkitBrandViewResult((ScrollRequest.Anchor({ anchor: model.viewportAnchor })), "@foldkit/ui/virtualList/index.js#Applied"),
+        Pending: ({ target, alignment }) => __foldkitBrandViewResult((ScrollRequest.Target({ target, alignment })), "@foldkit/ui/virtualList/index.js#Pending"),
+    })), "@foldkit/ui/virtualList/index.js#Idle"),
+    Pending: ({ request }) => __foldkitBrandViewResult((request), "@foldkit/ui/virtualList/index.js#Pending~2"),
+})), "@foldkit/ui/virtualList/index.js#currentScrollRequest");
+const reconcileLayout = (model) => __foldkitBrandViewResult((buildScrollRequest(model, currentScrollRequest(model))), "@foldkit/ui/virtualList/index.js#reconcileLayout");
+const anchorFromSnapshot = (model, scrollTop, scrollHeight, containerHeight, anchor) => {
+    const distanceFromEnd = Math.max(0, scrollHeight - containerHeight - scrollTop);
+    const isFollowingEnd = EndBehavior.match(model.endBehavior, {
+        PreserveAnchor: () => __foldkitBrandViewResult((false), "@foldkit/ui/virtualList/index.js#PreserveAnchor"),
+        Follow: ({ thresholdPx }) => __foldkitBrandViewResult((distanceFromEnd <= thresholdPx), "@foldkit/ui/virtualList/index.js#Follow"),
+    });
+    if (isFollowingEnd) {
+        return __foldkitBrandViewResult((ViewportAnchor.End()), "@foldkit/ui/virtualList/index.js#anchorFromSnapshot");
+    }
+    return __foldkitBrandViewResult((ObservedAnchor.match(anchor, {
+        None: () => __foldkitBrandViewResult((ViewportAnchor.Offset({ scrollTop })), "@foldkit/ui/virtualList/index.js#None"),
+        Row: ({ key, index, viewportOffset }) => __foldkitBrandViewResult((ViewportAnchor.Row({ key, index, viewportOffset })), "@foldkit/ui/virtualList/index.js#Row~2"),
+    })), "@foldkit/ui/virtualList/index.js#anchorFromSnapshot");
+};
+const applyScrollSnapshot = (model, snapshot) => __foldkitBrandViewResult((modifyFields(model, {
+    scrollTop: () => __foldkitBrandViewResult((snapshot.scrollTop), "@foldkit/ui/virtualList/index.js#scrollTop"),
+    viewportAnchor: () => __foldkitBrandViewResult((anchorFromSnapshot(model, snapshot.scrollTop, snapshot.scrollHeight, snapshot.containerHeight, snapshot.anchor)), "@foldkit/ui/virtualList/index.js#viewportAnchor"),
+})), "@foldkit/ui/virtualList/index.js#applyScrollSnapshot");
+const measureContainer = (model, containerWidth, containerHeight) => {
+    const wasUnmeasured = model.measurement._tag === 'Unmeasured';
+    const didWidthChange = Measurement.match(model.measurement, {
+        Unmeasured: () => __foldkitBrandViewResult((false), "@foldkit/ui/virtualList/index.js#Unmeasured"),
+        Measured: measurement => __foldkitBrandViewResult((measurement.containerWidth !== containerWidth), "@foldkit/ui/virtualList/index.js#Measured"),
+    });
+    const recordContainerMeasurement = stepModel => (__foldkitBrandViewResult(({
+        model: modifyFields(stepModel, {
+            measurement: () => __foldkitBrandViewResult((Measurement.Measured({ containerWidth, containerHeight })), "@foldkit/ui/virtualList/index.js#measurement"),
+            measuredRowHeights: measuredRowHeights => __foldkitBrandViewResult((didWidthChange ? Record.empty() : measuredRowHeights), "@foldkit/ui/virtualList/index.js#measuredRowHeights"),
+            layoutVersion: layoutVersion => __foldkitBrandViewResult((didWidthChange ? Number.increment(layoutVersion) : layoutVersion), "@foldkit/ui/virtualList/index.js#layoutVersion"),
+        }),
+    }), "@foldkit/ui/virtualList/index.js#recordContainerMeasurement"));
+    const { initialScroll } = model;
+    if (initialScroll._tag === 'Pending') {
+        return __foldkitBrandViewResult((Update.combine(model, [
+            recordContainerMeasurement,
+            stepModel => __foldkitBrandViewResult((buildScrollRequest(stepModel, ScrollRequest.Target({
+                target: initialScroll.target,
+                alignment: initialScroll.alignment,
+            }))), "@foldkit/ui/virtualList/index.js#anonymous~15"),
+        ])), "@foldkit/ui/virtualList/index.js#measureContainer");
+    }
+    if (wasUnmeasured) {
+        return __foldkitBrandViewResult((recordContainerMeasurement(model)), "@foldkit/ui/virtualList/index.js#measureContainer");
+    }
+    return __foldkitBrandViewResult((Update.combine(model, [recordContainerMeasurement, reconcileLayout])), "@foldkit/ui/virtualList/index.js#measureContainer");
+};
+const hasChangedMeasurement = (model, measurement) => {
+    if (measurement.layoutVersion !== model.layoutVersion) {
+        return __foldkitBrandViewResult((false), "@foldkit/ui/virtualList/index.js#hasChangedMeasurement");
+    }
+    return __foldkitBrandViewResult((pipe(model.measuredRowHeights, Record.get(measurement.key), Option.match({
+        onNone: () => __foldkitBrandViewResult((true), "@foldkit/ui/virtualList/index.js#onNone"),
+        onSome: height => __foldkitBrandViewResult((height !== measurement.height), "@foldkit/ui/virtualList/index.js#onSome"),
+    }))), "@foldkit/ui/virtualList/index.js#hasChangedMeasurement");
+};
+const applyRowMeasurements = (model, measurements) => {
+    const changedMeasurements = Array.filter(measurements, measurement => __foldkitBrandViewResult((hasChangedMeasurement(model, measurement)), "@foldkit/ui/virtualList/index.js#anonymous~16"));
+    if (Array.isArrayEmpty(changedMeasurements)) {
+        return __foldkitBrandViewResult(({ model }), "@foldkit/ui/virtualList/index.js#applyRowMeasurements");
+    }
+    const measuredRowHeights = Array.reduce(changedMeasurements, model.measuredRowHeights, (heights, measurement) => __foldkitBrandViewResult((Record.set(heights, measurement.key, measurement.height)), "@foldkit/ui/virtualList/index.js#anonymous~17"));
+    return __foldkitBrandViewResult((Update.combine(model, [
+        stepModel => (__foldkitBrandViewResult(({
+            model: modifyFields(stepModel, {
+                measuredRowHeights: () => __foldkitBrandViewResult((measuredRowHeights), "@foldkit/ui/virtualList/index.js#measuredRowHeights~2"),
+            }),
+        }), "@foldkit/ui/virtualList/index.js#anonymous~18")),
+        reconcileLayout,
+    ])), "@foldkit/ui/virtualList/index.js#applyRowMeasurements");
 };
+/** Processes a VirtualList Message and returns the next Model and optional Commands. */
+export const update = (model, message) => __foldkitBrandViewResult((Message.match(message, {
+    ObservedContainerScroll: snapshot => {
+        const nextPendingScrollVersion = PendingScroll.match(model.pendingScroll, {
+            Idle: () => __foldkitBrandViewResult((model.pendingScrollVersion), "@foldkit/ui/virtualList/index.js#Idle~2"),
+            Pending: () => __foldkitBrandViewResult((Number.increment(model.pendingScrollVersion)), "@foldkit/ui/virtualList/index.js#Pending~3"),
+        });
+        return __foldkitBrandViewResult(({
+            model: modifyFields(applyScrollSnapshot(model, snapshot), {
+                initialScroll: () => __foldkitBrandViewResult((InitialScroll.Applied()), "@foldkit/ui/virtualList/index.js#initialScroll"),
+                pendingScroll: () => __foldkitBrandViewResult((PendingScroll.Idle()), "@foldkit/ui/virtualList/index.js#pendingScroll~2"),
+                pendingScrollVersion: () => __foldkitBrandViewResult((nextPendingScrollVersion), "@foldkit/ui/virtualList/index.js#pendingScrollVersion~2"),
+            }),
+        }), "@foldkit/ui/virtualList/index.js#ObservedContainerScroll");
+    },
+    ResizedContainer: ({ containerWidth, containerHeight }) => __foldkitBrandViewResult((measureContainer(model, containerWidth, containerHeight)), "@foldkit/ui/virtualList/index.js#ResizedContainer"),
+    MeasuredRows: ({ measurements }) => __foldkitBrandViewResult((applyRowMeasurements(model, measurements)), "@foldkit/ui/virtualList/index.js#MeasuredRows"),
+    CompletedApplyScroll: ({ version, outcome }) => {
+        if (version !== model.pendingScrollVersion) {
+            return __foldkitBrandViewResult(({ model }), "@foldkit/ui/virtualList/index.js#CompletedApplyScroll");
+        }
+        return __foldkitBrandViewResult((ApplyScrollOutcome.match(outcome, {
+            Applied: snapshot => {
+                const scrolledModel = applyScrollSnapshot(model, snapshot);
+                return __foldkitBrandViewResult(({
+                    model: modifyFields(scrolledModel, {
+                        initialScroll: () => __foldkitBrandViewResult((snapshot.anchor._tag === 'Row'
+                            ? InitialScroll.Applied()
+                            : model.initialScroll), "@foldkit/ui/virtualList/index.js#initialScroll~2"),
+                        pendingScroll: () => __foldkitBrandViewResult((PendingScroll.Idle()), "@foldkit/ui/virtualList/index.js#pendingScroll~3"),
+                    }),
+                }), "@foldkit/ui/virtualList/index.js#Applied~2");
+            },
+            Skipped: () => (__foldkitBrandViewResult(({
+                model: modifyFields(model, {
+                    pendingScroll: () => __foldkitBrandViewResult((PendingScroll.Idle()), "@foldkit/ui/virtualList/index.js#pendingScroll~4"),
+                }),
+            }), "@foldkit/ui/virtualList/index.js#Skipped")),
+        })), "@foldkit/ui/virtualList/index.js#CompletedApplyScroll");
+    },
+})), "@foldkit/ui/virtualList/index.js#update");
+/** Programmatically scrolls to a logical target. */
+export const scrollTo = (model, target, options = {}) => __foldkitBrandViewResult((Update.combine(model, [
+    stepModel => (__foldkitBrandViewResult(({
+        model: modifyFields(stepModel, {
+            initialScroll: () => __foldkitBrandViewResult((InitialScroll.Applied()), "@foldkit/ui/virtualList/index.js#initialScroll~3"),
+        }),
+    }), "@foldkit/ui/virtualList/index.js#anonymous~19")),
+    stepModel => __foldkitBrandViewResult((buildScrollRequest(stepModel, ScrollRequest.Target({
+        target,
+        alignment: options.alignment ?? 'Start',
+    }))), "@foldkit/ui/virtualList/index.js#anonymous~20"),
+])), "@foldkit/ui/virtualList/index.js#scrollTo");
 /** Programmatically scrolls the container so the row at `index` is visible.
- *  Returns the next Model and a Command that mutates `element.scrollTop`. The
- *  natural scroll event then flows back through `ScrolledContainer` and the
- *  component re-renders the new visible slice.
- *
- *  Uses version-based cancellation: each call increments
- *  `pendingScrollVersion` so a stale `CompletedApplyScroll` (e.g. from a
- *  previous in-flight scroll) is ignored when its version no longer matches.
- *
- *  Should be called after the container has rendered. If the container is not
- *  yet in the DOM the Command silently no-ops (the Model still transitions
- *  through `ScrollingToIndex` → `Idle` via the version-matched completion).
- *
- *  Assumes uniform row heights: target scroll position is computed as
- *  `index * model.rowHeightPx`. For variable-height rows, use
- *  `scrollToIndexVariable`. */
-export const scrollToIndex = (model, index) => __foldkitBrandViewResult((buildScrollToIndex(model, index, index * model.rowHeightPx)), "@foldkit/ui/virtualList/index.js#scrollToIndex");
-/** Variable-height counterpart of `scrollToIndex`. Walks the heights of items
- *  before `index` to compute the target `scrollTop`. Use this when rendering
- *  the list with `itemToRowHeightPx`; use `scrollToIndex` for uniform heights.
- *
- *  Out-of-range indices clamp to the corresponding edge: negative or zero
- *  scrolls to the top, indices past the end scroll past the last row.
- *
- *  Note: when restoring `initialScrollTop` on the first measurement of a
- *  variable-height list, the runtime falls back to uniform-height math (using
- *  `model.rowHeightPx`) because items aren't reachable from the `update`
- *  function. Consumers who need an accurate initial scroll on a
- *  variable-height list should call `scrollToIndexVariable` after the first
- *  `MeasuredContainer` arrives. */
-export const scrollToIndexVariable = (model, items, itemToRowHeightPx, index) => {
-    const cumulativeOffsets = prefixSum(items, itemToRowHeightPx);
-    const targetScrollTop = pipe(cumulativeOffsets, Array.get(Math.max(0, index)), Option.getOrElse(() => __foldkitBrandViewResult((lastOrZero(cumulativeOffsets)), "@foldkit/ui/virtualList/index.js#anonymous~2")));
-    return __foldkitBrandViewResult((buildScrollToIndex(model, index, targetScrollTop)), "@foldkit/ui/virtualList/index.js#scrollToIndexVariable");
+ *  The next view resolves the logical index with its current sizing mode, and
+ *  the Command aligns the live rendered row. */
+export const scrollToIndex = (model, index, options = {}) => __foldkitBrandViewResult((scrollTo(model, ScrollTarget.Index({ index }), options)), "@foldkit/ui/virtualList/index.js#scrollToIndex");
+/** Programmatically scrolls to the row whose `itemToKey` result matches
+ *  `key`. The next view resolves the key against its current items. */
+export const scrollToKey = (model, key, options = {}) => __foldkitBrandViewResult((scrollTo(model, ScrollTarget.Key({ key }), options)), "@foldkit/ui/virtualList/index.js#scrollToKey");
+/** Programmatically scrolls to an exact pixel offset from the start of the
+ *  list. Negative offsets clamp to zero. */
+export const scrollToOffset = (model, offset) => __foldkitBrandViewResult((scrollTo(model, ScrollTarget.Offset({ offset }))), "@foldkit/ui/virtualList/index.js#scrollToOffset");
+/** Programmatically scrolls to the end of the list. */
+export const scrollToEnd = (model) => __foldkitBrandViewResult((scrollTo(model, ScrollTarget.End())), "@foldkit/ui/virtualList/index.js#scrollToEnd");
+/** Notifies VirtualList that its parent-owned items changed. The next view
+ *  resolves the stored stable-key anchor against the new items, and the
+ *  Command restores that anchor after the DOM patch. */
+export const informItemsChanged = (model, itemKeys) => {
+    const currentKeys = HashSet.fromIterable(itemKeys);
+    return __foldkitBrandViewResult((Update.combine(model, [
+        stepModel => (__foldkitBrandViewResult(({
+            model: modifyFields(stepModel, {
+                measuredRowHeights: Record.filter((_, key) => __foldkitBrandViewResult((HashSet.has(currentKeys, key)), "@foldkit/ui/virtualList/index.js#anonymous~22")),
+                layoutVersion: Number.increment,
+            }),
+        }), "@foldkit/ui/virtualList/index.js#anonymous~21")),
+        reconcileLayout,
+    ])), "@foldkit/ui/virtualList/index.js#informItemsChanged");
 };
 const clampIndex = (index, itemCount) => __foldkitBrandViewResult((Math.max(0, Math.min(index, itemCount))), "@foldkit/ui/virtualList/index.js#clampIndex");
 const prefixSum = (items, itemToRowHeightPx) => {
     const heights = Array.map(items, itemToRowHeightPx);
-    return __foldkitBrandViewResult((Array.scan(heights, 0, (cumulative, height) => __foldkitBrandViewResult((cumulative + height), "@foldkit/ui/virtualList/index.js#anonymous~3"))), "@foldkit/ui/virtualList/index.js#prefixSum");
+    return __foldkitBrandViewResult((Array.scan(heights, 0, (cumulative, height) => __foldkitBrandViewResult((cumulative + height), "@foldkit/ui/virtualList/index.js#anonymous~23"))), "@foldkit/ui/virtualList/index.js#prefixSum");
 };
-const lastOrZero = (values) => __foldkitBrandViewResult((pipe(values, Array.last, Option.getOrElse(() => __foldkitBrandViewResult((0), "@foldkit/ui/virtualList/index.js#anonymous~4")))), "@foldkit/ui/virtualList/index.js#lastOrZero");
-/** Computes the visible slice of a data array given the current scroll
- *  position, container height, row height, and an overscan buffer.
- *
- *  Assumes uniform row heights via `model.rowHeightPx`. For variable-height
- *  rows, use `visibleWindowVariable`.
- *
- *  Returns `Option.none()` when the container has not yet been measured;
- *  callers should render a placeholder (or `Html.empty`) and wait for the
- *  first `MeasuredContainer` message. */
-export const visibleWindow = (model, itemCount, overscan) => __foldkitBrandViewResult((Measurement.match(model.measurement, {
-    Unmeasured: () => __foldkitBrandViewResult((Option.none()), "@foldkit/ui/virtualList/index.js#Unmeasured"),
-    Measured: ({ containerHeight }) => {
-        const firstVisibleIndex = Math.floor(model.scrollTop / model.rowHeightPx);
-        const lastVisibleIndex = Math.ceil((model.scrollTop + containerHeight) / model.rowHeightPx);
-        const startIndex = clampIndex(firstVisibleIndex - overscan, itemCount);
-        const endIndex = clampIndex(lastVisibleIndex + overscan, itemCount);
-        const topSpacerHeight = startIndex * model.rowHeightPx;
-        const bottomSpacerHeight = (itemCount - endIndex) * model.rowHeightPx;
-        return __foldkitBrandViewResult((Option.some({
-            startIndex,
-            endIndex,
-            topSpacerHeight,
-            bottomSpacerHeight,
-        })), "@foldkit/ui/virtualList/index.js#Measured");
-    },
-})), "@foldkit/ui/virtualList/index.js#visibleWindow");
-/** Variable-height counterpart of `visibleWindow`. Walks the heights of every
- *  item to build a prefix-sum array, then locates the visible slice with two
- *  linear searches.
- *
- *  Cost is O(N) per call, walking the whole `items` array once to build the
- *  prefix sums. For lists in the 10k-item range, this comfortably fits inside
- *  a 60Hz scroll budget. Larger lists or hotter scroll paths can layer a
- *  prefix-sum cache invalidated when items change; that lives behind the same
- *  return shape so consumers don't have to know.
- *
- *  Returns `Option.none()` when the container has not yet been measured. */
-export const visibleWindowVariable = (model, items, itemToRowHeightPx, overscan) => __foldkitBrandViewResult((Measurement.match(model.measurement, {
-    Unmeasured: () => __foldkitBrandViewResult((Option.none()), "@foldkit/ui/virtualList/index.js#Unmeasured~2"),
-    Measured: ({ containerHeight }) => {
-        const itemCount = items.length;
-        const cumulativeOffsets = prefixSum(items, itemToRowHeightPx);
-        const totalHeight = lastOrZero(cumulativeOffsets);
-        const firstVisibleIndex = pipe(cumulativeOffsets, Array.findFirstIndex(Number.isGreaterThan(model.scrollTop)), Option.match({
-            onNone: () => __foldkitBrandViewResult((itemCount), "@foldkit/ui/virtualList/index.js#onNone"),
-            onSome: index => __foldkitBrandViewResult((Math.max(0, index - 1)), "@foldkit/ui/virtualList/index.js#onSome"),
-        }));
-        const lastVisibleIndex = pipe(cumulativeOffsets, Array.findFirstIndex(Number.isGreaterThanOrEqualTo(model.scrollTop + containerHeight)), Option.getOrElse(() => __foldkitBrandViewResult((itemCount), "@foldkit/ui/virtualList/index.js#anonymous~5")));
-        const startIndex = clampIndex(firstVisibleIndex - overscan, itemCount);
-        const endIndex = clampIndex(lastVisibleIndex + overscan, itemCount);
-        const topSpacerHeight = pipe(cumulativeOffsets, Array.get(startIndex), Option.getOrElse(() => __foldkitBrandViewResult((0), "@foldkit/ui/virtualList/index.js#anonymous~6")));
-        const offsetAtEnd = pipe(cumulativeOffsets, Array.get(endIndex), Option.getOrElse(() => __foldkitBrandViewResult((totalHeight), "@foldkit/ui/virtualList/index.js#anonymous~7")));
-        const bottomSpacerHeight = totalHeight - offsetAtEnd;
-        return __foldkitBrandViewResult((Option.some({
-            startIndex,
-            endIndex,
-            topSpacerHeight,
-            bottomSpacerHeight,
-        })), "@foldkit/ui/virtualList/index.js#Measured~2");
+const lastOrZero = (values) => __foldkitBrandViewResult((pipe(values, Array.last, Option.getOrElse(() => __foldkitBrandViewResult((0), "@foldkit/ui/virtualList/index.js#anonymous~24")))), "@foldkit/ui/virtualList/index.js#lastOrZero");
+/** Alignment of content when its total height is shorter than the viewport. */
+export const ContentAlignment = Schema.Literals(['Start', 'End']);
+const measuredRowHeight = (model, key) => __foldkitBrandViewResult((Record.get(model.measuredRowHeights, key)), "@foldkit/ui/virtualList/index.js#measuredRowHeight");
+const listLayout = (model, items, itemToKey, itemToRowHeightPx, dynamicRowHeights, itemToEstimatedRowHeightPx, contentAlignment) => {
+    const rowHeightFor = (item, index) => {
+        if (dynamicRowHeights !== undefined) {
+            const key = itemToKey(item, index);
+            return __foldkitBrandViewResult((Option.getOrElse(measuredRowHeight(model, key), () => __foldkitBrandViewResult((itemToEstimatedRowHeightPx?.(item, index) ?? model.rowHeightPx), "@foldkit/ui/virtualList/index.js#anonymous~25"))), "@foldkit/ui/virtualList/index.js#rowHeightFor");
+        }
+        if (itemToRowHeightPx !== undefined) {
+            return __foldkitBrandViewResult((itemToRowHeightPx(item, index)), "@foldkit/ui/virtualList/index.js#rowHeightFor");
+        }
+        return __foldkitBrandViewResult((model.rowHeightPx), "@foldkit/ui/virtualList/index.js#rowHeightFor");
+    };
+    const maybeCumulativeOffsets = dynamicRowHeights === undefined && itemToRowHeightPx === undefined
+        ? Option.none()
+        : Option.some(prefixSum(items, rowHeightFor));
+    const totalHeight = Option.match(maybeCumulativeOffsets, {
+        onNone: () => __foldkitBrandViewResult((items.length * model.rowHeightPx), "@foldkit/ui/virtualList/index.js#onNone~2"),
+        onSome: lastOrZero,
+    });
+    const containerHeight = Measurement.match(model.measurement, {
+        Unmeasured: () => __foldkitBrandViewResult((0), "@foldkit/ui/virtualList/index.js#Unmeasured~2"),
+        Measured: ({ containerHeight }) => __foldkitBrandViewResult((containerHeight), "@foldkit/ui/virtualList/index.js#Measured~2"),
+    });
+    const leadingInset = contentAlignment === 'End' ? Math.max(0, containerHeight - totalHeight) : 0;
+    return __foldkitBrandViewResult(({
+        maybeCumulativeOffsets,
+        rowHeightPx: model.rowHeightPx,
+        totalHeight,
+        leadingInset,
+        containerHeight,
+        maxScrollTop: Math.max(0, leadingInset + totalHeight - containerHeight),
+    }), "@foldkit/ui/virtualList/index.js#listLayout");
+};
+const offsetAt = (layout, index) => __foldkitBrandViewResult((Option.match(layout.maybeCumulativeOffsets, {
+    onNone: () => __foldkitBrandViewResult((index * layout.rowHeightPx), "@foldkit/ui/virtualList/index.js#onNone~3"),
+    onSome: cumulativeOffsets => __foldkitBrandViewResult((pipe(cumulativeOffsets, Array.get(index), Option.getOrElse(() => __foldkitBrandViewResult((layout.totalHeight), "@foldkit/ui/virtualList/index.js#anonymous~26")))), "@foldkit/ui/virtualList/index.js#onSome~2"),
+})), "@foldkit/ui/virtualList/index.js#offsetAt");
+const rowOffsetsForIndex = (layout, itemCount, index) => {
+    if (itemCount === 0) {
+        return __foldkitBrandViewResult((Option.none()), "@foldkit/ui/virtualList/index.js#rowOffsetsForIndex");
+    }
+    const clampedIndex = Math.max(0, Math.min(index, itemCount - 1));
+    return __foldkitBrandViewResult((Option.some({
+        startOffset: layout.leadingInset + offsetAt(layout, clampedIndex),
+        endOffset: layout.leadingInset + offsetAt(layout, clampedIndex + 1),
+    })), "@foldkit/ui/virtualList/index.js#rowOffsetsForIndex");
+};
+const indexForKey = (items, itemToKey, key) => __foldkitBrandViewResult((Array.findFirstIndex(items, (item, index) => __foldkitBrandViewResult((itemToKey(item, index) === key), "@foldkit/ui/virtualList/index.js#anonymous~27"))), "@foldkit/ui/virtualList/index.js#indexForKey");
+const clampLayoutScrollTop = (layout, scrollTop) => __foldkitBrandViewResult((Math.max(0, Math.min(scrollTop, layout.maxScrollTop))), "@foldkit/ui/virtualList/index.js#clampLayoutScrollTop");
+const alignedLayoutScrollTop = (model, layout, offsets, alignment) => __foldkitBrandViewResult((clampLayoutScrollTop(layout, scrollTopForRow(model.scrollTop, layout.containerHeight, offsets.startOffset, offsets.endOffset, alignment))), "@foldkit/ui/virtualList/index.js#alignedLayoutScrollTop");
+const scrollTopForLayoutTarget = (model, layout, items, itemToKey, target, alignment) => __foldkitBrandViewResult((ScrollTarget.match(target, {
+    Index: ({ index }) => __foldkitBrandViewResult((Option.map(rowOffsetsForIndex(layout, items.length, index), offsets => __foldkitBrandViewResult((alignedLayoutScrollTop(model, layout, offsets, alignment)), "@foldkit/ui/virtualList/index.js#anonymous~28"))), "@foldkit/ui/virtualList/index.js#Index~3"),
+    Key: ({ key }) => __foldkitBrandViewResult((pipe(indexForKey(items, itemToKey, key), Option.flatMap(index => __foldkitBrandViewResult((rowOffsetsForIndex(layout, items.length, index)), "@foldkit/ui/virtualList/index.js#anonymous~29")), Option.map(offsets => __foldkitBrandViewResult((alignedLayoutScrollTop(model, layout, offsets, alignment)), "@foldkit/ui/virtualList/index.js#anonymous~30")))), "@foldkit/ui/virtualList/index.js#Key~3"),
+    Offset: ({ offset }) => __foldkitBrandViewResult((Option.some(clampLayoutScrollTop(layout, offset))), "@foldkit/ui/virtualList/index.js#Offset~3"),
+    End: () => __foldkitBrandViewResult((Option.some(layout.maxScrollTop)), "@foldkit/ui/virtualList/index.js#End~3"),
+})), "@foldkit/ui/virtualList/index.js#scrollTopForLayoutTarget");
+const scrollTopForLayoutAnchor = (layout, items, itemToKey, anchor) => __foldkitBrandViewResult((ViewportAnchor.match(anchor, {
+    Offset: ({ scrollTop }) => __foldkitBrandViewResult((clampLayoutScrollTop(layout, scrollTop)), "@foldkit/ui/virtualList/index.js#Offset~4"),
+    Row: ({ key, index, viewportOffset }) => {
+        const anchorIndex = Option.getOrElse(indexForKey(items, itemToKey, key), () => __foldkitBrandViewResult((index), "@foldkit/ui/virtualList/index.js#anonymous~31"));
+        const maybeOffsets = rowOffsetsForIndex(layout, items.length, anchorIndex);
+        return __foldkitBrandViewResult((Option.match(maybeOffsets, {
+            onNone: () => __foldkitBrandViewResult((0), "@foldkit/ui/virtualList/index.js#onNone~4"),
+            onSome: offsets => __foldkitBrandViewResult((clampLayoutScrollTop(layout, offsets.startOffset - viewportOffset)), "@foldkit/ui/virtualList/index.js#onSome~3"),
+        })), "@foldkit/ui/virtualList/index.js#Row~3");
     },
-})), "@foldkit/ui/virtualList/index.js#visibleWindowVariable");
-// SUBSCRIPTION
-const containerElement = (id) => __foldkitBrandViewResult((Option.fromNullishOr(document.getElementById(id))), "@foldkit/ui/virtualList/index.js#containerElement");
-/** Subscriptions that track the container's scroll position and size.
- *
- *  - **scroll**: listens for `scroll` events on the container element and
- *    emits `ScrolledContainer` with the new `scrollTop`.
- *  - **resize**: observes the container with `ResizeObserver` and emits
- *    `MeasuredContainer` with the new height.
- *
- *  A `MutationObserver` watches the document for the container element
- *  appearing and disappearing, so the listeners attach the moment the
- *  element is inserted into the DOM and clean up when it is removed. This
- *  makes the subscription robust across SPA route changes: navigating to a
- *  page that mounts the list, away, and back all reattach correctly without
- *  the consumer having to teach the framework about navigation. */
-export const subscriptions = Subscription.make()(entry => (__foldkitBrandViewResult(({
-    containerEvents: entry({ id: Schema.String }, {
-        modelToDependencies: model => (__foldkitBrandViewResult(({ id: model.id }), "@foldkit/ui/virtualList/index.js#modelToDependencies")),
-        dependenciesToStream: ({ id }) => __foldkitBrandViewResult((Stream.callback(queue => __foldkitBrandViewResult((Effect.acquireRelease(Effect.sync(() => {
-            const state = {
-                scrollListener: null,
-                resizeObserver: null,
-                observedElement: null,
-                pendingFrame: null,
-            };
-            const detach = () => {
-                if (state.resizeObserver !== null) {
-                    state.resizeObserver.disconnect();
-                    state.resizeObserver = null;
-                }
-                if (state.observedElement !== null &&
-                    state.scrollListener !== null) {
-                    state.observedElement.removeEventListener('scroll', state.scrollListener);
-                }
-                state.observedElement = null;
-                state.scrollListener = null;
-            };
-            const attach = (element) => {
-                const listener = () => __foldkitBrandViewResult((Queue.offerUnsafe(queue, Message.ScrolledContainer({ scrollTop: element.scrollTop }))), "@foldkit/ui/virtualList/index.js#listener");
-                element.addEventListener('scroll', listener, { passive: true });
-                state.scrollListener = listener;
-                state.observedElement = element;
-                state.resizeObserver = new ResizeObserver(entries => {
-                    const lastEntry = Array.last(entries);
-                    if (Option.isSome(lastEntry)) {
-                        Queue.offerUnsafe(queue, Message.MeasuredContainer({
-                            containerHeight: lastEntry.value.contentRect.height,
-                        }));
-                    }
-                });
-                state.resizeObserver.observe(element);
-            };
-            const reconcile = () => {
-                const maybeElement = containerElement(id);
-                if (Option.isNone(maybeElement)) {
-                    if (state.observedElement !== null) {
-                        detach();
-                    }
-                    return;
-                }
-                if (state.observedElement === maybeElement.value) {
-                    return;
-                }
-                detach();
-                attach(maybeElement.value);
-            };
-            reconcile();
-            // NOTE: observes the entire document subtree because the container
-            // can be inserted/removed by any parent the consumer chooses (route
-            // changes, conditional renders, modal mounts), and the framework
-            // has no way to know that hierarchy in advance. Reconcile is gated
-            // by rAF and short-circuits when the cached observedElement is
-            // still in the DOM, so per-mutation cost stays low even with
-            // subtree: true.
-            const mutationObserver = new MutationObserver(() => {
-                if (state.pendingFrame !== null) {
-                    return;
-                }
-                state.pendingFrame = requestAnimationFrame(() => {
-                    state.pendingFrame = null;
-                    reconcile();
-                });
-            });
-            mutationObserver.observe(document.body, {
-                childList: true,
-                subtree: true,
-            });
-            return __foldkitBrandViewResult(({ state, detach, mutationObserver }), "@foldkit/ui/virtualList/index.js#anonymous~10");
-        }), ({ state, detach, mutationObserver }) => __foldkitBrandViewResult((Effect.sync(() => {
-            mutationObserver.disconnect();
-            if (state.pendingFrame !== null) {
-                cancelAnimationFrame(state.pendingFrame);
+    End: () => __foldkitBrandViewResult((layout.maxScrollTop), "@foldkit/ui/virtualList/index.js#End~4"),
+})), "@foldkit/ui/virtualList/index.js#scrollTopForLayoutAnchor");
+const scrollTopForView = (model, layout, items, itemToKey) => __foldkitBrandViewResult((PendingScroll.match(model.pendingScroll, {
+    Idle: () => __foldkitBrandViewResult((clampLayoutScrollTop(layout, model.scrollTop)), "@foldkit/ui/virtualList/index.js#Idle~3"),
+    Pending: ({ request }) => __foldkitBrandViewResult((ScrollRequest.match(request, {
+        Target: ({ target, alignment }) => __foldkitBrandViewResult((Option.getOrElse(scrollTopForLayoutTarget(model, layout, items, itemToKey, target, alignment), () => __foldkitBrandViewResult((clampLayoutScrollTop(layout, model.scrollTop)), "@foldkit/ui/virtualList/index.js#anonymous~32"))), "@foldkit/ui/virtualList/index.js#Target~2"),
+        Anchor: ({ anchor }) => __foldkitBrandViewResult((scrollTopForLayoutAnchor(layout, items, itemToKey, anchor)), "@foldkit/ui/virtualList/index.js#Anchor~2"),
+    })), "@foldkit/ui/virtualList/index.js#Pending~4"),
+})), "@foldkit/ui/virtualList/index.js#scrollTopForView");
+const visibleWindowForLayout = (layout, scrollTop, itemCount, overscan) => {
+    const contentScrollTop = Math.max(0, scrollTop - layout.leadingInset);
+    const contentViewportEnd = Math.max(0, scrollTop + layout.containerHeight - layout.leadingInset);
+    const firstVisibleIndex = Option.match(layout.maybeCumulativeOffsets, {
+        onNone: () => __foldkitBrandViewResult((Math.floor(contentScrollTop / layout.rowHeightPx)), "@foldkit/ui/virtualList/index.js#onNone~5"),
+        onSome: cumulativeOffsets => __foldkitBrandViewResult((pipe(cumulativeOffsets, Array.findFirstIndex(Number.isGreaterThan(contentScrollTop)), Option.match({
+            onNone: () => __foldkitBrandViewResult((itemCount), "@foldkit/ui/virtualList/index.js#onNone~6"),
+            onSome: index => __foldkitBrandViewResult((Math.max(0, index - 1)), "@foldkit/ui/virtualList/index.js#onSome~5"),
+        }))), "@foldkit/ui/virtualList/index.js#onSome~4"),
+    });
+    const lastVisibleIndex = Option.match(layout.maybeCumulativeOffsets, {
+        onNone: () => __foldkitBrandViewResult((Math.ceil(contentViewportEnd / layout.rowHeightPx)), "@foldkit/ui/virtualList/index.js#onNone~7"),
+        onSome: cumulativeOffsets => __foldkitBrandViewResult((pipe(cumulativeOffsets, Array.findFirstIndex(Number.isGreaterThanOrEqualTo(contentViewportEnd)), Option.getOrElse(() => __foldkitBrandViewResult((itemCount), "@foldkit/ui/virtualList/index.js#anonymous~33")))), "@foldkit/ui/virtualList/index.js#onSome~6"),
+    });
+    const startIndex = clampIndex(firstVisibleIndex - overscan, itemCount);
+    const endIndex = clampIndex(lastVisibleIndex + overscan, itemCount);
+    return __foldkitBrandViewResult(({
+        startIndex,
+        endIndex,
+        topSpacerHeight: layout.leadingInset + offsetAt(layout, startIndex),
+        bottomSpacerHeight: layout.totalHeight - offsetAt(layout, endIndex),
+    }), "@foldkit/ui/virtualList/index.js#visibleWindowForLayout");
+};
+// ELEMENT LIFECYCLE
+const rowMeasurement = (entry) => {
+    if (!(entry.target instanceof HTMLElement)) {
+        return __foldkitBrandViewResult((Option.none()), "@foldkit/ui/virtualList/index.js#rowMeasurement");
+    }
+    const key = entry.target.getAttribute('data-virtual-list-item-key');
+    const layoutVersion = pipe(entry.target.getAttribute('data-virtual-list-layout-version'), Option.fromNullishOr, Option.flatMap(Number.parse));
+    if (key === null || Option.isNone(layoutVersion)) {
+        return __foldkitBrandViewResult((Option.none()), "@foldkit/ui/virtualList/index.js#rowMeasurement");
+    }
+    return __foldkitBrandViewResult((Option.some({
+        key,
+        height: entry.target.getBoundingClientRect().height,
+        layoutVersion: layoutVersion.value,
+    })), "@foldkit/ui/virtualList/index.js#rowMeasurement");
+};
+const observeVirtualList = (element, id) => __foldkitBrandViewResult((Stream.callback(queue => __foldkitBrandViewResult((Effect.acquireRelease(Effect.sync(() => {
+    if (!(element instanceof HTMLElement)) {
+        return __foldkitBrandViewResult((() => __foldkitBrandViewResult((undefined), "@foldkit/ui/virtualList/index.js#anonymous~36")), "@foldkit/ui/virtualList/index.js#anonymous~35");
+    }
+    const emitContainerMeasurement = () => __foldkitBrandViewResult((Queue.offerUnsafe(queue, Message.ResizedContainer({
+        containerWidth: element.clientWidth,
+        containerHeight: element.clientHeight,
+    }))), "@foldkit/ui/virtualList/index.js#emitContainerMeasurement");
+    emitContainerMeasurement();
+    const scrollListener = () => __foldkitBrandViewResult((Queue.offerUnsafe(queue, Message.ObservedContainerScroll({
+        scrollTop: element.scrollTop,
+        scrollHeight: element.scrollHeight,
+        containerHeight: element.clientHeight,
+        anchor: observedAnchor(element),
+    }))), "@foldkit/ui/virtualList/index.js#scrollListener");
+    element.addEventListener('scroll', scrollListener, { passive: true });
+    const containerResizeObserver = new ResizeObserver(entries => {
+        const lastEntry = Array.last(entries);
+        if (Option.isSome(lastEntry)) {
+            Queue.offerUnsafe(queue, Message.ResizedContainer({
+                containerWidth: lastEntry.value.contentRect.width,
+                containerHeight: lastEntry.value.contentRect.height,
+            }));
+        }
+    });
+    containerResizeObserver.observe(element);
+    const observedRows = new Map();
+    const rowResizeObserver = new ResizeObserver(entries => {
+        const measurements = Array.flatMap(entries, entry => __foldkitBrandViewResult((Option.match(rowMeasurement(entry), {
+            onNone: () => __foldkitBrandViewResult(([]), "@foldkit/ui/virtualList/index.js#onNone~8"),
+            onSome: measurement => __foldkitBrandViewResult(([measurement]), "@foldkit/ui/virtualList/index.js#onSome~7"),
+        })), "@foldkit/ui/virtualList/index.js#anonymous~39"));
+        if (Array.isArrayNonEmpty(measurements)) {
+            Queue.offerUnsafe(queue, Message.MeasuredRows({ measurements }));
+        }
+    });
+    const reconcileRows = () => {
+        if (element.childElementCount === 0) {
+            emitContainerMeasurement();
+        }
+        const rows = Array.filter(renderedRows(element), row => __foldkitBrandViewResult((row.getAttribute('data-virtual-list-measure') === 'true'), "@foldkit/ui/virtualList/index.js#anonymous~40"));
+        const measurableRows = new Set(rows);
+        for (const row of observedRows.keys()) {
+            if (!measurableRows.has(row)) {
+                rowResizeObserver.unobserve(row);
+                observedRows.delete(row);
+            }
+        }
+        for (const row of rows) {
+            const layoutVersion = row.getAttribute('data-virtual-list-layout-version') ?? '';
+            if (observedRows.get(row) !== layoutVersion) {
+                rowResizeObserver.unobserve(row);
+                observedRows.set(row, layoutVersion);
+                rowResizeObserver.observe(row);
             }
-            detach();
-        })), "@foldkit/ui/virtualList/index.js#anonymous~14")).pipe(Effect.flatMap(() => __foldkitBrandViewResult((Effect.never), "@foldkit/ui/virtualList/index.js#anonymous~16")))), "@foldkit/ui/virtualList/index.js#anonymous~9"))), "@foldkit/ui/virtualList/index.js#dependenciesToStream"),
-    }),
-}), "@foldkit/ui/virtualList/index.js#anonymous~8")));
+        }
+    };
+    const mutationObserver = new MutationObserver(reconcileRows);
+    mutationObserver.observe(element, {
+        attributes: true,
+        attributeFilter: [
+            'data-virtual-list-layout-version',
+            'data-virtual-list-measure',
+        ],
+        childList: true,
+        subtree: true,
+    });
+    reconcileRows();
+    const containers = mountedContainers.get(id) ?? new Set();
+    containers.add(element);
+    mountedContainers.set(id, containers);
+    return __foldkitBrandViewResult((() => {
+        const containers = mountedContainers.get(id);
+        if (containers !== undefined) {
+            containers.delete(element);
+            if (containers.size === 0) {
+                mountedContainers.delete(id);
+            }
+        }
+        mutationObserver.disconnect();
+        rowResizeObserver.disconnect();
+        containerResizeObserver.disconnect();
+        element.removeEventListener('scroll', scrollListener);
+    }), "@foldkit/ui/virtualList/index.js#anonymous~35");
+}), cleanup => __foldkitBrandViewResult((Effect.sync(cleanup)), "@foldkit/ui/virtualList/index.js#anonymous~42")).pipe(Effect.flatMap(() => __foldkitBrandViewResult((Effect.never), "@foldkit/ui/virtualList/index.js#anonymous~43")))), "@foldkit/ui/virtualList/index.js#anonymous~34"))), "@foldkit/ui/virtualList/index.js#observeVirtualList");
+/** Container-owned Mount that tracks scrolling, container resizing, and
+ *  rendered row measurements for dynamic-height lists. */
+export const ObserveVirtualList = Mount.defineStream('ObserveVirtualList', {
+    args: { id: Schema.String },
+    messages: [
+        Message.ObservedContainerScroll,
+        Message.ResizedContainer,
+        Message.MeasuredRows,
+    ],
+    execute: ({ element, id, viewStateChanges }) => __foldkitBrandViewResult((viewStateChanges.pipe(Stream.switchMap(viewState => __foldkitBrandViewResult((viewState === 'Live' ? observeVirtualList(element, id) : Stream.never), "@foldkit/ui/virtualList/index.js#anonymous~44")))), "@foldkit/ui/virtualList/index.js#execute~2"),
+});
 // VIEW
 const DEFAULT_OVERSCAN = 5;
 export const view = () => 
 /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
 __foldkitBrandViewResult((viewImpl), "@foldkit/ui/virtualList/index.js#view");
 const viewImpl = defineView((model, viewInputs, h) => {
-    const { items, itemToKey, itemToView, itemToRowHeightPx, overscan = DEFAULT_OVERSCAN, rowElement = 'li', containerClassName, containerAttributes = [], } = viewInputs;
+    const { items, itemToKey, itemToView, itemToRowHeightPx, dynamicRowHeights, itemToEstimatedRowHeightPx, overscan = DEFAULT_OVERSCAN, rowElement = 'li', containerClassName, containerAttributes = [], contentAlignment = 'Start', } = viewInputs;
     const baseContainerAttributes = [
         h.Id(model.id),
         h.Role('list'),
-        h.DataAttribute('virtual-list-id', model.id),
+        h.DataAttribute('virtual-list-scroll-version', String(model.pendingScrollVersion)),
+        h.OnMount(ObserveVirtualList({ id: model.id })),
         h.Style({
             overflow: 'auto',
+            'overflow-anchor': 'none',
             'list-style': 'none',
             margin: '0',
             padding: '0',
@@ -354,14 +733,13 @@ const viewImpl = defineView((model, viewInputs, h) => {
         ...containerAttributes,
     ];
     const renderContainer = (children) => __foldkitBrandViewResult((h.keyed('ul')(model.id, allContainerAttributes, children)), "@foldkit/ui/virtualList/index.js#renderContainer");
-    const maybeWindow = itemToRowHeightPx !== undefined
-        ? visibleWindowVariable(model, items, itemToRowHeightPx, overscan)
-        : visibleWindow(model, items.length, overscan);
-    const rowHeightFor = (item, dataIndex) => __foldkitBrandViewResult((itemToRowHeightPx !== undefined
-        ? itemToRowHeightPx(item, dataIndex)
-        : model.rowHeightPx), "@foldkit/ui/virtualList/index.js#rowHeightFor");
+    const layout = listLayout(model, items, itemToKey, itemToRowHeightPx, dynamicRowHeights, itemToEstimatedRowHeightPx, contentAlignment);
+    const maybeWindow = Measurement.match(model.measurement, {
+        Unmeasured: () => __foldkitBrandViewResult((Option.none()), "@foldkit/ui/virtualList/index.js#Unmeasured~3"),
+        Measured: () => __foldkitBrandViewResult((Option.some(visibleWindowForLayout(layout, scrollTopForView(model, layout, items, itemToKey), items.length, overscan))), "@foldkit/ui/virtualList/index.js#Measured~3"),
+    });
     return __foldkitBrandViewResult((Option.match(maybeWindow, {
-        onNone: () => __foldkitBrandViewResult((renderContainer([])), "@foldkit/ui/virtualList/index.js#onNone~2"),
+        onNone: () => __foldkitBrandViewResult((renderContainer([])), "@foldkit/ui/virtualList/index.js#onNone~9"),
         onSome: ({ startIndex, endIndex, topSpacerHeight, bottomSpacerHeight, }) => {
             const visibleItems = items.slice(startIndex, endIndex);
             const topSpacer = h.keyed('li')(`${model.id}-top-spacer`, [
@@ -374,18 +752,30 @@ const viewImpl = defineView((model, viewInputs, h) => {
             ]);
             const renderedRows = Array.map(visibleItems, (item, sliceIndex) => {
                 const dataIndex = startIndex + sliceIndex;
-                return __foldkitBrandViewResult((h.keyed(rowElement)(itemToKey(item, dataIndex), [
+                const key = itemToKey(item, dataIndex);
+                const rowHeight = offsetAt(layout, dataIndex + 1) - offsetAt(layout, dataIndex);
+                const rowSizingAttributes = dynamicRowHeights === undefined
+                    ? [
+                        h.Style({
+                            height: `${rowHeight}px`,
+                            display: 'grid',
+                        }),
+                    ]
+                    : [
+                        h.DataAttribute('virtual-list-measure', 'true'),
+                        h.DataAttribute('virtual-list-layout-version', String(model.layoutVersion)),
+                        h.Style({ display: 'grid' }),
+                    ];
+                return __foldkitBrandViewResult((h.keyed(rowElement)(key, [
                     h.Role('listitem'),
+                    h.DataAttribute('virtual-list-item-key', key),
                     h.DataAttribute('virtual-list-item-index', String(dataIndex)),
                     h.AriaSetsize(items.length),
                     h.AriaPosinset(dataIndex + 1),
-                    h.Style({
-                        height: `${rowHeightFor(item, dataIndex)}px`,
-                        display: 'grid',
-                    }),
-                ], [itemToView(item, dataIndex)])), "@foldkit/ui/virtualList/index.js#anonymous~18");
+                    ...rowSizingAttributes,
+                ], [itemToView(item, dataIndex)])), "@foldkit/ui/virtualList/index.js#anonymous~46");
             });
-            return __foldkitBrandViewResult((renderContainer([topSpacer, ...renderedRows, bottomSpacer])), "@foldkit/ui/virtualList/index.js#onSome~2");
+            return __foldkitBrandViewResult((renderContainer([topSpacer, ...renderedRows, bottomSpacer])), "@foldkit/ui/virtualList/index.js#onSome~8");
         },
-    })), "@foldkit/ui/virtualList/index.js#anonymous~17");
+    })), "@foldkit/ui/virtualList/index.js#anonymous~45");
 });