chat-layout 1.2.0-5 → 1.2.0-6

package/example/chat.ts

@@ -513,6 +513,8 @@ function drawFrame(): void {
     maxIdx: Number.NaN,
     min: Number.NaN,
     max: Number.NaN,
+    canAutoFollowTop: false,
+    canAutoFollowBottom: false,
   };
   renderer.render(feedback);
 
@@ -644,7 +646,7 @@ button("unshift", () => {
     ],
     {
       duration: INSERT_ANIMATION_DURATION,
-      followIfAtBoundary: true,
+      autoFollow: true,
     },
   );
 });
@@ -661,7 +663,7 @@ button("push", () => {
     ],
     {
       distance: 24,
-      followIfAtBoundary: true,
+      autoFollow: true,
     },
   );
 });

package/index.d.mts

@@ -19,6 +19,10 @@ interface RenderFeedback {
   min: number;
   /** Largest visible continuous item position, expressed in item coordinates rather than pixels. */
   max: number;
+  /** Whether the current viewport may auto-follow inserts at the visual top edge. */
+  canAutoFollowTop: boolean;
+  /** Whether the current viewport may auto-follow inserts at the visual bottom edge. */
+  canAutoFollowBottom: boolean;
 }
 /**
  * The main axis direction used by flex containers.
@@ -523,7 +527,7 @@ interface InsertListItemsAnimationOptions {
   /** Enter offset in pixels measured from the final resting position. */
   distance?: number;
   /** Auto-follow the insertion edge when the viewport was already pinned there. */
-  followIfAtBoundary?: boolean;
+  autoFollow?: boolean;
 }
 type PushListItemsAnimationOptions = InsertListItemsAnimationOptions;
 type UnshiftListItemsAnimationOptions = InsertListItemsAnimationOptions;
@@ -593,6 +597,10 @@ declare function memoRenderItemBy<C extends CanvasRenderingContext2D, T, K>(keyO
 };
 //#endregion
 //#region src/renderer/virtualized/base-types.d.ts
+type AutoFollowCapabilities = {
+  top: boolean;
+  bottom: boolean;
+};
 /** Per-item draw/hittest callbacks produced by the resolver. */
 type VirtualizedResolvedItem = {
   draw: (y: number) => boolean;
@@ -690,10 +698,19 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
    * Scrolls the viewport to the requested item index.
    */
   jumpTo(index: number, options?: JumpToOptions): void;
+  /**
+   * Scrolls the viewport to the visual top edge and arms top auto-follow immediately.
+   */
+  jumpToTop(options?: JumpToOptions): void;
+  /**
+   * Scrolls the viewport to the visual bottom edge and arms bottom auto-follow immediately.
+   */
+  jumpToBottom(options?: JumpToOptions): void;
   protected _resetRenderFeedback(feedback?: RenderFeedback): void;
   protected _accumulateRenderFeedback(feedback: RenderFeedback, idx: number, top: number, height: number): void;
   protected _renderDrawList(list: VisibleWindow<VirtualizedResolvedItem>["drawList"], shift: number, feedback?: RenderFeedback): boolean;
   protected _renderVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem>, feedback?: RenderFeedback, extraShift?: number): boolean;
+  protected _readAutoFollowCapabilities(window: VisibleWindow<VirtualizedResolvedItem>, extraShift?: number): AutoFollowCapabilities;
   protected _readVisibleRange(top: number, height: number): {
     top: number;
     bottom: number;

package/index.mjs

@@ -3661,7 +3661,7 @@ function normalizeInsertAnimation(animation) {
 	if (duration == null) return;
 	const normalizedAnimation = { duration };
 	if (typeof animation?.distance === "number" && Number.isFinite(animation.distance)) normalizedAnimation.distance = Math.max(0, animation.distance);
-	if (animation?.followIfAtBoundary === true) normalizedAnimation.followIfAtBoundary = true;
+	if (animation?.autoFollow === true) normalizedAnimation.autoFollow = true;
 	return normalizedAnimation;
 }
 var ListState = class {
@@ -3981,18 +3981,21 @@ function prepareFrameSession(params) {
 //#endregion
 //#region src/renderer/virtualized/jump-controller.ts
 var JumpController = class {
-	#autoFollowLatch;
+	#confirmedAutoFollowTop = false;
+	#confirmedAutoFollowBottom = false;
 	#controlledState;
 	#jumpAnimation;
 	#lastCommittedState;
 	#hasPendingListChange = false;
+	#pendingBoundaryJumpTop = false;
+	#pendingBoundaryJumpBottom = false;
 	#options;
 	constructor(options) {
 		this.#options = options;
 	}
 	beforeFrame() {
 		const currentState = this.#options.readListState();
-		if (!this.#hasPendingListChange && this.#jumpAnimation == null && this.#lastCommittedState != null && !sameState(this.#lastCommittedState, currentState.position, currentState.offset)) this.#clearAutoFollowLatch();
+		if (!this.#hasPendingListChange && this.#jumpAnimation == null && this.#lastCommittedState != null && !sameState(this.#lastCommittedState, currentState.position, currentState.offset)) this.#clearPendingBoundaryJumps();
 		this.#hasPendingListChange = false;
 	}
 	prepare(now) {
@@ -4003,7 +4006,7 @@ var JumpController = class {
 			return false;
 		}
 		if (this.#controlledState != null && !sameState(this.#controlledState, this.#options.readListState().position, this.#options.readListState().offset)) {
-			this.#clearAutoFollowLatch();
+			this.#clearPendingBoundaryJumps();
 			this.#cancelJumpAnimation();
 			return false;
 		}
@@ -4033,28 +4036,53 @@ var JumpController = class {
 		};
 	}
 	jumpTo(index, options = {}) {
-		this.#clearAutoFollowLatch();
+		this.#clearPendingBoundaryJumps();
 		if (this.#options.getItemCount() === 0) {
 			this.#cancelJumpAnimation();
 			return;
 		}
 		this.#startJumpToIndex(index, options, { kind: "manual" });
 	}
+	jumpToBoundary(boundary, options = {}) {
+		this.#clearPendingBoundaryJumps();
+		if (this.#options.getItemCount() === 0) {
+			this.#cancelJumpAnimation();
+			return;
+		}
+		this.#armBoundaryJump(boundary);
+		this.#startJumpToIndex(boundary === "bottom" ? this.#options.getItemCount() - 1 : 0, {
+			...options,
+			block: boundary === "bottom" ? "end" : "start"
+		}, {
+			kind: "boundary-jump",
+			boundary
+		});
+	}
+	syncAutoFollowCapabilities(capabilities) {
+		this.#confirmedAutoFollowTop = capabilities.top;
+		this.#confirmedAutoFollowBottom = capabilities.bottom;
+		this.#clearPendingBoundaryJumps();
+		return this.getEffectiveAutoFollowCapabilities();
+	}
+	getEffectiveAutoFollowCapabilities() {
+		return {
+			top: this.#hasEffectiveAutoFollowCapability("top"),
+			bottom: this.#hasEffectiveAutoFollowCapability("bottom")
+		};
+	}
 	handleListStateChange(change) {
 		this.#hasPendingListChange = true;
 		const followChange = this.#resolveAutoFollowChange(change);
-		const canChainAutoFollow = followChange != null ? this.#shouldChainAutoFollow(followChange.direction, followChange.animation) : false;
-		const canLatchAutoFollow = followChange != null ? this.#shouldLatchAutoFollow(followChange.direction, followChange.count, followChange.animation) : false;
-		const canSnapshotAutoFollow = followChange != null ? this.#shouldAutoFollowFromSnapshot(followChange.direction, followChange.count, followChange.animation) : false;
-		if (followChange != null && (canSnapshotAutoFollow || canChainAutoFollow || canLatchAutoFollow)) {
+		const canChainAutoFollow = followChange != null ? this.#shouldChainAutoFollow(followChange.boundary) : false;
+		const canCapabilityAutoFollow = followChange != null ? this.#shouldAutoFollowFromCapability(followChange.boundary, followChange.direction, followChange.count) : false;
+		if (followChange != null && (canChainAutoFollow || canCapabilityAutoFollow)) {
 			if (canChainAutoFollow) this.#rebaseJumpAnchorForBoundaryInsert(followChange.direction, followChange.count, getNow());
-			this.#autoFollowLatch = followChange.direction;
-			this.#startJumpToIndex(followChange.direction === "push" ? this.#options.getItemCount() - 1 : 0, {
-				block: followChange.direction === "push" ? "end" : "start",
+			this.#startJumpToIndex(followChange.boundary === "bottom" ? this.#options.getItemCount() - 1 : 0, {
+				block: followChange.boundary === "bottom" ? "end" : "start",
 				duration: followChange.animation?.duration
 			}, {
 				kind: "auto-follow",
-				direction: followChange.direction
+				boundary: followChange.boundary
 			});
 			return {
 				...followChange.change,
@@ -4106,8 +4134,9 @@ var JumpController = class {
 	#resolveAutoFollowChange(change) {
 		switch (change.type) {
 			case "push":
-			case "unshift": return change.animation?.followIfAtBoundary === true ? {
+			case "unshift": return change.animation?.autoFollow === true ? {
 				change,
+				boundary: change.type === "push" ? "bottom" : "top",
 				direction: change.type,
 				count: change.count,
 				animation: change.animation
@@ -4115,21 +4144,11 @@ var JumpController = class {
 			default: return;
 		}
 	}
-	#shouldAutoFollowFromSnapshot(direction, count, animation) {
-		if (animation?.followIfAtBoundary !== true) return false;
-		return this.#options.canAutoFollowBoundaryInsert(direction, count, this.#options.readListState().position, this.#options.readListState().offset);
-	}
-	#shouldLatchAutoFollow(direction, count, animation) {
-		if (animation?.followIfAtBoundary !== true) return false;
-		if (!this.#matchesLastCommittedStateAfterBoundaryInsert(direction, count)) {
-			this.#clearAutoFollowLatch();
-			return false;
-		}
-		return this.#autoFollowLatch === direction;
+	#shouldAutoFollowFromCapability(boundary, direction, count) {
+		return this.#hasEffectiveAutoFollowCapability(boundary) && this.#matchesLastCommittedStateAfterBoundaryInsert(direction, count);
 	}
-	#shouldChainAutoFollow(direction, animation) {
-		if (animation?.followIfAtBoundary !== true) return false;
-		return this.#jumpAnimation?.source.kind === "auto-follow" ? this.#jumpAnimation.source.direction === direction : false;
+	#shouldChainAutoFollow(boundary) {
+		return this.#readJumpBoundary() === boundary;
 	}
 	#rebaseJumpAnchorForBoundaryInsert(direction, count, now) {
 		const animation = this.#jumpAnimation;
@@ -4148,8 +4167,22 @@ var JumpController = class {
 			offset: state.offset
 		}, this.#options.readListState().position, this.#options.readListState().offset);
 	}
-	#clearAutoFollowLatch() {
-		this.#autoFollowLatch = void 0;
+	#hasEffectiveAutoFollowCapability(boundary) {
+		const animationBoundary = this.#readJumpBoundary();
+		return boundary === "top" ? this.#confirmedAutoFollowTop || this.#pendingBoundaryJumpTop || animationBoundary === "top" : this.#confirmedAutoFollowBottom || this.#pendingBoundaryJumpBottom || animationBoundary === "bottom";
+	}
+	#readJumpBoundary() {
+		const source = this.#jumpAnimation?.source;
+		if (source == null || source.kind === "manual") return;
+		return source.boundary;
+	}
+	#armBoundaryJump(boundary) {
+		this.#pendingBoundaryJumpTop = boundary === "top";
+		this.#pendingBoundaryJumpBottom = boundary === "bottom";
+	}
+	#clearPendingBoundaryJumps() {
+		this.#pendingBoundaryJumpTop = false;
+		this.#pendingBoundaryJumpBottom = false;
 	}
 };
 //#endregion
@@ -4157,14 +4190,21 @@ var JumpController = class {
 var VisibilitySnapshot = class {
 	#drawnItems = /* @__PURE__ */ new Set();
 	#visibleItems = /* @__PURE__ */ new Set();
+	#previousVisibleItems = /* @__PURE__ */ new Set();
 	#hasSnapshot = false;
 	#snapshotState;
+	#previousSnapshotState;
 	#emptyState;
 	#coversShortList = false;
 	#topGap = 0;
 	#bottomGap = 0;
 	#atStartBoundary = false;
 	#atEndBoundary = false;
+	#currentExtraShift = 0;
+	#minDrawnIndex = Number.POSITIVE_INFINITY;
+	#maxDrawnIndex = Number.NEGATIVE_INFINITY;
+	#topBoundaryItem;
+	#bottomBoundaryItem;
 	get coversShortList() {
 		return this.#hasSnapshot && this.#snapshotState != null && this.#coversShortList;
 	}
@@ -4174,22 +4214,58 @@ var VisibilitySnapshot = class {
 	get bottomGap() {
 		return this.#bottomGap;
 	}
+	get previousState() {
+		return this.#previousSnapshotState;
+	}
+	get currentExtraShift() {
+		return this.#currentExtraShift;
+	}
+	readDrawnIndexRange() {
+		if (!Number.isFinite(this.#minDrawnIndex) || !Number.isFinite(this.#maxDrawnIndex)) return;
+		return {
+			minIndex: this.#minDrawnIndex,
+			maxIndex: this.#maxDrawnIndex
+		};
+	}
+	readBoundaryItem(boundary) {
+		return boundary === "top" ? this.#topBoundaryItem : this.#bottomBoundaryItem;
+	}
 	capture(window, _resolutionPath, items, viewportHeight, snapshotState, extraShift, readVisibleRange) {
+		this.#previousVisibleItems = this.#visibleItems;
+		this.#previousSnapshotState = this.#snapshotState;
 		const nextDrawnItems = /* @__PURE__ */ new Set();
 		const nextVisibleItems = /* @__PURE__ */ new Set();
 		let minVisibleIndex = Number.POSITIVE_INFINITY;
 		let maxVisibleIndex = Number.NEGATIVE_INFINITY;
 		let topMostY = Number.POSITIVE_INFINITY;
 		let bottomMostY = Number.NEGATIVE_INFINITY;
+		let nextMinDrawnIndex = Number.POSITIVE_INFINITY;
+		let nextMaxDrawnIndex = Number.NEGATIVE_INFINITY;
+		let nextTopBoundaryItem;
+		let nextBottomBoundaryItem;
+		let nextTopBoundaryY = Number.POSITIVE_INFINITY;
+		let nextBottomBoundaryY = Number.NEGATIVE_INFINITY;
 		const effectiveShift = window.shift + extraShift;
 		for (const { idx, offset, height } of window.drawList) {
 			minVisibleIndex = Math.min(minVisibleIndex, idx);
 			maxVisibleIndex = Math.max(maxVisibleIndex, idx);
+			nextMinDrawnIndex = Math.min(nextMinDrawnIndex, idx);
+			nextMaxDrawnIndex = Math.max(nextMaxDrawnIndex, idx);
 			const y = offset + effectiveShift;
 			topMostY = Math.min(topMostY, y);
 			bottomMostY = Math.max(bottomMostY, y + height);
 			const item = items[idx];
-			if (item != null) nextDrawnItems.add(item);
+			if (item != null) {
+				nextDrawnItems.add(item);
+				if (y < nextTopBoundaryY) {
+					nextTopBoundaryY = y;
+					nextTopBoundaryItem = item;
+				}
+				if (y + height > nextBottomBoundaryY) {
+					nextBottomBoundaryY = y + height;
+					nextBottomBoundaryItem = item;
+				}
+			}
 			if (item == null || readVisibleRange(y, height) == null) continue;
 			nextVisibleItems.add(item);
 		}
@@ -4197,6 +4273,11 @@ var VisibilitySnapshot = class {
 		this.#visibleItems = nextVisibleItems;
 		this.#hasSnapshot = true;
 		this.#snapshotState = snapshotState;
+		this.#currentExtraShift = extraShift;
+		this.#minDrawnIndex = nextMinDrawnIndex;
+		this.#maxDrawnIndex = nextMaxDrawnIndex;
+		this.#topBoundaryItem = nextTopBoundaryItem;
+		this.#bottomBoundaryItem = nextBottomBoundaryItem;
 		this.#emptyState = items.length === 0 && window.drawList.length === 0 ? snapshotState : void 0;
 		const contentHeight = bottomMostY - topMostY;
 		this.#coversShortList = window.drawList.length > 0 && items.length > 0 && window.drawList.length === items.length && minVisibleIndex === 0 && maxVisibleIndex === items.length - 1 && topMostY >= -Number.EPSILON && bottomMostY <= viewportHeight + Number.EPSILON && contentHeight < viewportHeight - Number.EPSILON;
@@ -4228,20 +4309,30 @@ var VisibilitySnapshot = class {
 	isVisible(item) {
 		return this.#visibleItems.has(item);
 	}
+	wasVisible(item) {
+		return this.#previousVisibleItems.has(item);
+	}
 	tracks(item, retention) {
 		return retention === "drawn" ? this.#drawnItems.has(item) : this.#visibleItems.has(item);
 	}
 	reset() {
 		this.#drawnItems.clear();
 		this.#visibleItems.clear();
+		this.#previousVisibleItems.clear();
 		this.#hasSnapshot = false;
 		this.#snapshotState = void 0;
+		this.#previousSnapshotState = void 0;
 		this.#emptyState = void 0;
 		this.#coversShortList = false;
 		this.#topGap = 0;
 		this.#bottomGap = 0;
 		this.#atStartBoundary = false;
 		this.#atEndBoundary = false;
+		this.#currentExtraShift = 0;
+		this.#minDrawnIndex = Number.POSITIVE_INFINITY;
+		this.#maxDrawnIndex = Number.NEGATIVE_INFINITY;
+		this.#topBoundaryItem = void 0;
+		this.#bottomBoundaryItem = void 0;
 	}
 	#matchesStateAfterBoundaryInsert(direction, count, position, offset) {
 		const snapshotState = this.#snapshotState;
@@ -4629,6 +4720,19 @@ function handleTransitionStateChange(store, snapshot, currentViewportTranslateY,
 }
 //#endregion
 //#region src/renderer/virtualized/base-transition.ts
+function remapAnchorAfterDeletes(anchor, deletedIndices) {
+	if (!Number.isFinite(anchor) || deletedIndices.length === 0) return anchor;
+	const sortedIndices = [...deletedIndices].filter((index) => Number.isFinite(index) && index >= 0).sort((a, b) => a - b);
+	let removedBeforeAnchor = 0;
+	for (const index of sortedIndices) {
+		if (anchor > index + 1) {
+			removedBeforeAnchor += 1;
+			continue;
+		}
+		if (anchor >= index) return index - removedBeforeAnchor;
+	}
+	return anchor - removedBeforeAnchor;
+}
 var TransitionController = class {
 	#store = new TransitionStore();
 	#snapshot = new VisibilitySnapshot();
@@ -4636,8 +4740,8 @@ var TransitionController = class {
 	captureVisibilitySnapshot(window, resolutionPath, items, viewportHeight, snapshotState, extraShift, readVisibleRange) {
 		this.#snapshot.capture(window, resolutionPath, items, viewportHeight, snapshotState, extraShift, readVisibleRange);
 	}
-	pruneInvisible(lifecycle) {
-		return this.pruneInvisibleAt(getNow(), lifecycle);
+	pruneInvisible(ctx, lifecycle) {
+		return this.pruneInvisibleAt(getNow(), ctx, lifecycle);
 	}
 	prepare(now, lifecycle) {
 		this.settle(now, lifecycle);
@@ -4673,8 +4777,9 @@ var TransitionController = class {
 		this.#cleanupViewportTranslateAnimation(now);
 		return changed;
 	}
-	pruneInvisibleAt(now, lifecycle) {
-		return this.#settleTransitions(this.#store.findInvisible(this.#snapshot), now, lifecycle);
+	pruneInvisibleAt(now, ctx, lifecycle) {
+		const removals = this.#store.findInvisible(this.#snapshot);
+		return this.#settleTransitions(removals, now, lifecycle, this.#resolveNaturalBoundarySnap(removals, now, ctx, lifecycle));
 	}
 	reset() {
 		this.#store.reset();
@@ -4686,16 +4791,58 @@ var TransitionController = class {
 		if (animation == null) return;
 		if (getProgress(animation.startTime, animation.duration, now) >= 1) this.#viewportTranslateAnimation = void 0;
 	}
-	#settleTransitions(removals, now, lifecycle) {
+	#settleTransitions(removals, now, lifecycle, boundarySnap) {
 		if (removals.length === 0) return false;
 		const anchor = lifecycle.captureVisualAnchor(now);
+		const completedDeleteIndices = [];
 		for (const { item, transition } of removals) {
+			if (transition.kind === "delete") {
+				const index = lifecycle.readItemIndex(item);
+				if (index >= 0) completedDeleteIndices.push(index);
+			}
 			this.#store.delete(item);
 			if (transition.kind === "delete") lifecycle.onDeleteComplete(item);
 		}
-		if (anchor != null && Number.isFinite(anchor)) lifecycle.restoreVisualAnchor(anchor);
+		if (anchor != null && Number.isFinite(anchor)) lifecycle.restoreVisualAnchor(remapAnchorAfterDeletes(anchor, completedDeleteIndices));
+		if (boundarySnap != null) lifecycle.snapItemToViewportBoundary(boundarySnap.item, boundarySnap.boundary);
 		return true;
 	}
+	#resolveNaturalBoundarySnap(removals, now, ctx, lifecycle) {
+		const previousState = this.#snapshot.previousState;
+		const drawnRange = this.#snapshot.readDrawnIndexRange();
+		if (previousState == null || drawnRange == null) return;
+		const naturalIndices = [];
+		for (const { item, transition } of removals) {
+			if (transition.kind !== "update" && transition.kind !== "delete") continue;
+			const index = lifecycle.readItemIndex(item);
+			if (index < 0 || !this.#snapshot.wasVisible(item)) return;
+			if (this.#isTransitionVisibleInState(index, previousState, now, this.#snapshot.currentExtraShift, ctx)) return;
+			naturalIndices.push(index);
+		}
+		if (naturalIndices.length === 0) return;
+		if (naturalIndices.every((index) => index < drawnRange.minIndex)) {
+			const item = this.#snapshot.readBoundaryItem("top");
+			return item == null ? void 0 : {
+				item,
+				boundary: "top"
+			};
+		}
+		if (naturalIndices.every((index) => index > drawnRange.maxIndex)) {
+			const item = this.#snapshot.readBoundaryItem("bottom");
+			return item == null ? void 0 : {
+				item,
+				boundary: "bottom"
+			};
+		}
+	}
+	#isTransitionVisibleInState(index, state, now, extraShift, ctx) {
+		const solution = ctx.resolveVisibleWindowForState(state, now);
+		for (const entry of solution.window.drawList) {
+			if (entry.idx !== index) continue;
+			return ctx.readVisibleRange(entry.offset + solution.window.shift + extraShift, entry.height) != null;
+		}
+		return false;
+	}
 };
 //#endregion
 //#region src/renderer/virtualized/base.ts
@@ -4722,8 +4869,7 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 			getDefaultJumpBlock: this._getDefaultJumpBlock.bind(this),
 			getTargetAnchor: this._getTargetAnchor.bind(this),
 			clampItemIndex: this._clampItemIndex.bind(this),
-			getItemHeight: this._getItemHeight.bind(this),
-			canAutoFollowBoundaryInsert: (direction, count, position, offset) => this.#transitionController.canAutoFollowBoundaryInsert(direction, count, position, offset)
+			getItemHeight: this._getItemHeight.bind(this)
 		});
 		subscribeListState(options.list, this, (owner, change) => {
 			owner.#handleListStateChange(change);
@@ -4767,7 +4913,12 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 			captureVisibleItemSnapshot: (solution, extraShift) => this._captureVisibleItemSnapshot(solution, extraShift),
 			pruneTransitionAnimations: (window, frameNow) => this._pruneTransitionAnimations(window, frameNow)
 		});
+		const autoFollowCapabilities = this.#jumpController.syncAutoFollowCapabilities(this._readAutoFollowCapabilities(frame.solution.window, frame.viewportTranslateY));
 		const requestRedraw = this._renderVisibleWindow(frame.solution.window, feedback, frame.viewportTranslateY);
+		if (feedback != null) {
+			feedback.canAutoFollowTop = autoFollowCapabilities.top;
+			feedback.canAutoFollowBottom = autoFollowCapabilities.bottom;
+		}
 		this._commitListState(frame.solution.normalizedState);
 		return this._finishRender(keepAnimating || requestRedraw || frame.requestSettleRedraw);
 	}
@@ -4783,6 +4934,7 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 			captureVisibleItemSnapshot: (solution, extraShift) => this._captureVisibleItemSnapshot(solution, extraShift),
 			pruneTransitionAnimations: (window, frameNow) => this._pruneTransitionAnimations(window, frameNow)
 		});
+		this.#jumpController.syncAutoFollowCapabilities(this._readAutoFollowCapabilities(frame.solution.window, frame.viewportTranslateY));
 		return this._hittestVisibleWindow(frame.solution.window, test, frame.viewportTranslateY);
 	}
 	_readListState() {
@@ -4805,12 +4957,26 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 	jumpTo(index, options = {}) {
 		this.#jumpController.jumpTo(index, options);
 	}
+	/**
+	* Scrolls the viewport to the visual top edge and arms top auto-follow immediately.
+	*/
+	jumpToTop(options = {}) {
+		this.#jumpController.jumpToBoundary("top", options);
+	}
+	/**
+	* Scrolls the viewport to the visual bottom edge and arms bottom auto-follow immediately.
+	*/
+	jumpToBottom(options = {}) {
+		this.#jumpController.jumpToBoundary("bottom", options);
+	}
 	_resetRenderFeedback(feedback) {
 		if (feedback == null) return;
 		feedback.minIdx = NaN;
 		feedback.maxIdx = NaN;
 		feedback.min = NaN;
 		feedback.max = NaN;
+		feedback.canAutoFollowTop = false;
+		feedback.canAutoFollowBottom = false;
 	}
 	_accumulateRenderFeedback(feedback, idx, top, height) {
 		const visibleRange = this._readVisibleRange(top, height);
@@ -4837,6 +5003,29 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 		this._resetRenderFeedback(feedback);
 		return this._renderDrawList(window.drawList, window.shift + extraShift, feedback);
 	}
+	_readAutoFollowCapabilities(window, extraShift = 0) {
+		if (window.drawList.length === 0 || this.items.length === 0) return {
+			top: false,
+			bottom: false
+		};
+		let minIndex = Number.POSITIVE_INFINITY;
+		let maxIndex = Number.NEGATIVE_INFINITY;
+		let topMostY = Number.POSITIVE_INFINITY;
+		let bottomMostY = Number.NEGATIVE_INFINITY;
+		const effectiveShift = window.shift + extraShift;
+		for (const { idx, offset, height } of window.drawList) {
+			minIndex = Math.min(minIndex, idx);
+			maxIndex = Math.max(maxIndex, idx);
+			const y = offset + effectiveShift;
+			topMostY = Math.min(topMostY, y);
+			bottomMostY = Math.max(bottomMostY, y + height);
+		}
+		const viewportHeight = this.graphics.canvas.clientHeight;
+		return {
+			top: minIndex === 0 && topMostY >= -Number.EPSILON,
+			bottom: maxIndex === this.items.length - 1 && bottomMostY <= viewportHeight + Number.EPSILON
+		};
+	}
 	_readVisibleRange(top, height) {
 		if (!Number.isFinite(top) || !Number.isFinite(height) || height <= 0) return;
 		const viewportHeight = this.graphics.canvas.clientHeight;
@@ -4849,7 +5038,7 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 		};
 	}
 	_pruneTransitionAnimations(_window, now) {
-		return this.#transitionController.pruneInvisibleAt(now, this.#getTransitionLifecycleAdapter());
+		return this.#transitionController.pruneInvisibleAt(now, this.#getTransitionPlanningAdapter(), this.#getTransitionLifecycleAdapter());
 	}
 	_hittestVisibleWindow(window, test, extraShift = 0) {
 		for (const { value: item, offset, height } of window.drawList) {
@@ -4893,6 +5082,11 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 		if (!Number.isFinite(anchor) || this.items.length <= 0) return;
 		this._applyAnchor(anchor);
 	}
+	#snapItemToViewportBoundary(item, boundary) {
+		const index = this.items.indexOf(item);
+		if (index < 0) return;
+		this._applyAnchor(this._getTargetAnchor(index, boundary === "top" ? "start" : "end"));
+	}
 	_resolveItem(item, _index, now) {
 		return this.#transitionController.resolveItem(item, now, this.#getTransitionRenderAdapter(), this.#getTransitionLifecycleAdapter());
 	}
@@ -4903,7 +5097,9 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 		return {
 			onDeleteComplete: this.#handleDeleteComplete.bind(this),
 			captureVisualAnchor: this._readAnchorAt.bind(this),
-			restoreVisualAnchor: this._restoreAnchor.bind(this)
+			restoreVisualAnchor: this._restoreAnchor.bind(this),
+			readItemIndex: (item) => this.items.indexOf(item),
+			snapItemToViewportBoundary: this.#snapItemToViewportBoundary.bind(this)
 		};
 	}
 	#getVirtualizedRuntime() {
@@ -4914,7 +5110,8 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 			renderItem: this.options.renderItem,
 			measureNode: this.measureRootNode.bind(this),
 			readVisibleRange: this._readVisibleRange.bind(this),
-			resolveVisibleWindow: () => this._resolveVisibleWindow(getNow())
+			resolveVisibleWindow: () => this._resolveVisibleWindow(getNow()),
+			resolveVisibleWindowForState: (state, now) => this._resolveVisibleWindowForState(state, now)
 		};
 	}
 	#getTransitionRenderAdapter() {