@moldable-ai/ui 0.2.19 → 0.2.21

package/dist/components/ui/message-scroller-controller.js

@@ -0,0 +1,888 @@
+import { MessageScrollerPolicy } from './message-scroller-policy';
+const READING_LEAF_SELECTOR = '[data-message-scroll-anchor]';
+const POSITION_EPSILON_PX = 0.5;
+const WARMUP_BATCH_SIZE = 3;
+const PROGRAMMATIC_SCROLL_TIMEOUT_MS = 800;
+function now() {
+    return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+const EMPTY_SCROLLABLE = { start: false, end: false };
+const EMPTY_VISIBILITY = {
+    currentAnchorId: null,
+    visibleMessageIds: [],
+};
+export function createExternalStore(initial, isEqual) {
+    let snapshot = initial;
+    const listeners = new Set();
+    return {
+        getSnapshot: () => snapshot,
+        hasListeners: () => listeners.size > 0,
+        setSnapshot: (next) => {
+            if (isEqual(snapshot, next))
+                return;
+            snapshot = next;
+            listeners.forEach((listener) => listener());
+        },
+        subscribe: (listener, onFirst, onLast) => {
+            const wasEmpty = listeners.size === 0;
+            listeners.add(listener);
+            if (wasEmpty)
+                onFirst?.();
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0)
+                    onLast?.();
+            };
+        },
+    };
+}
+function scrollableEquals(a, b) {
+    return a.start === b.start && a.end === b.end;
+}
+function visibilityEquals(a, b) {
+    return (a.currentAnchorId === b.currentAnchorId &&
+        a.visibleMessageIds.length === b.visibleMessageIds.length &&
+        a.visibleMessageIds.every((id, index) => id === b.visibleMessageIds[index]));
+}
+export function isMessageScrollerAtEnd(viewport, threshold) {
+    return maxScrollTop(viewport) - viewport.scrollTop <= threshold;
+}
+/**
+ * Snapshot of the stable leaves the reader can currently see, preferring
+ * fine-grained `[data-message-scroll-anchor]` leaves (their tops do not move
+ * when a disclosure collapses inside the same message) over whole items.
+ */
+export function captureReadingLeaves(viewport, content, items) {
+    const leaves = [
+        ...Array.from(content.querySelectorAll(READING_LEAF_SELECTOR)),
+        ...items,
+    ];
+    const viewportRect = viewport.getBoundingClientRect();
+    return leaves.map((element) => {
+        const rect = element.getBoundingClientRect();
+        return {
+            element,
+            top: rect.top - viewportRect.top,
+            bottom: rect.bottom - viewportRect.top,
+        };
+    });
+}
+/**
+ * Re-pins the first still-visible captured leaf after content above it
+ * changed size. Native scroll anchoring may already have compensated; the
+ * measured delta is zero then and this is deliberately a no-op.
+ */
+export function restoreReadingLeaves(viewport, leaves) {
+    const visible = leaves.find(({ element, top, bottom }) => {
+        if (!element.isConnected)
+            return false;
+        const rect = element.getBoundingClientRect();
+        return rect.height > 0 && bottom > 0 && top < viewport.clientHeight;
+    });
+    if (!visible)
+        return false;
+    const delta = elementViewportTop(visible.element, viewport) - visible.top;
+    if (Math.abs(delta) <= POSITION_EPSILON_PX)
+        return false;
+    viewport.scrollTop += delta;
+    return true;
+}
+/**
+ * The single DOM-side owner of transcript scrolling. Every behavior that can
+ * move the viewport — follow-the-end, turn anchoring, prepend preservation,
+ * reading-position stability while rows above collapse — routes through this
+ * controller and its {@link MessageScrollerPolicy}, so nothing here can fight
+ * the reader (or another controller) for the scroll position.
+ */
+export class MessageScrollerController {
+    scrollableStore = createExternalStore(EMPTY_SCROLLABLE, scrollableEquals);
+    visibilityStore = createExternalStore(EMPTY_VISIBILITY, visibilityEquals);
+    policy;
+    options;
+    preserveScrollOnPrepend = true;
+    root = null;
+    viewport = null;
+    content = null;
+    spacer = null;
+    messageElements = new Map();
+    handledTurnAnchors = new WeakSet();
+    visibleMessageIds = new Set();
+    warmedItems = new WeakSet();
+    lastScrollTop = 0;
+    previousFirstItem = null;
+    previousItemCount = 0;
+    anchoredElement = null;
+    trackedFirstVisible = null;
+    readingLeaves = [];
+    pendingScrollToMessage = null;
+    defaultPositionApplied = false;
+    spacerHeight = 0;
+    spacerGap = 0;
+    programmaticDeadline = 0;
+    stateFrame = null;
+    visibilityFrame = null;
+    warmupHandle = null;
+    warmupUsesIdleCallback = false;
+    intersectionObserver = null;
+    constructor(options) {
+        this.options = options;
+        this.policy = new MessageScrollerPolicy(options.autoScroll);
+    }
+    get viewportElement() {
+        return this.viewport;
+    }
+    // MARK: - Element wiring
+    setRoot(element) {
+        this.root = element;
+        if (element)
+            this.applyStateAttributes();
+    }
+    setViewport(element) {
+        this.viewport = element;
+        if (element) {
+            this.lastScrollTop = element.scrollTop;
+            this.applyStateAttributes();
+        }
+    }
+    setContent(element) {
+        this.content = element;
+    }
+    setSpacer(element) {
+        this.spacer = element;
+        this.spacerGap = element ? readRowGap(element.parentElement) : 0;
+    }
+    registerMessage(messageId, element, previous) {
+        if (element) {
+            this.messageElements.set(messageId, element);
+            this.intersectionObserver?.observe(element);
+            this.scheduleVisibilitySync();
+            if (this.pendingScrollToMessage?.messageId === messageId) {
+                this.flushPendingScrollToMessage();
+            }
+            return;
+        }
+        if (previous && this.messageElements.get(messageId) === previous) {
+            this.messageElements.delete(messageId);
+            this.visibleMessageIds.delete(messageId);
+            this.intersectionObserver?.unobserve(previous);
+            this.scheduleVisibilitySync();
+        }
+    }
+    // MARK: - Public scroll commands
+    scrollToEnd = (options = {}) => {
+        const viewport = this.viewport;
+        if (!viewport)
+            return false;
+        this.setSpacerHeight(0);
+        this.anchoredElement = null;
+        this.readingLeaves = [];
+        this.policy.jumpToEnd();
+        this.performScroll(maxScrollTop(viewport), options.behavior ?? 'auto');
+        this.scheduleVisibilitySync();
+        return true;
+    };
+    scrollToStart = (options = {}) => {
+        const viewport = this.viewport;
+        if (!viewport)
+            return false;
+        this.setSpacerHeight(0);
+        this.anchoredElement = null;
+        this.readingLeaves = [];
+        this.policy.jumpToStart();
+        this.performScroll(0, options.behavior ?? 'auto');
+        this.scheduleVisibilitySync();
+        return true;
+    };
+    scrollToMessage = (messageId, options) => {
+        const element = this.messageElements.get(messageId);
+        if (element) {
+            if (this.scrollToElement(element, options)) {
+                this.pendingScrollToMessage = null;
+                return true;
+            }
+            this.pendingScrollToMessage = { messageId, options };
+            return true;
+        }
+        if (this.previousItemCount === 0) {
+            this.pendingScrollToMessage = { messageId, options };
+            this.defaultPositionApplied = true;
+            return true;
+        }
+        return false;
+    };
+    scrollToElement(element, options = {}, { keepPreviousPeek = false } = {}) {
+        const viewport = this.viewport;
+        const content = this.content;
+        if (!viewport || !content || !content.contains(element))
+            return false;
+        const margin = (options.scrollMargin ?? this.options.scrollMargin) +
+            (keepPreviousPeek ? this.options.scrollPreviousItemPeek : 0);
+        const padding = readBlockPadding(content);
+        const target = alignedScrollTarget({
+            align: options.align ?? 'start',
+            element,
+            margin,
+            padding,
+            viewport,
+        });
+        // Growing the spacer first lets a late-transcript anchor actually reach
+        // the requested position even when little content follows it. The
+        // measurement must exclude the spacer itself: measuring through the
+        // content box would yield `required − current` instead of the absolute
+        // requirement, and the resulting resize feedback oscillated the spacer
+        // between the two values on every ResizeObserver tick.
+        const shortfall = target +
+            viewport.clientHeight -
+            contentBottomWithoutSpacer(viewport, content, this.itemChildren());
+        this.setSpacerHeight(Math.max(0, Math.ceil(shortfall)));
+        this.readingLeaves = [];
+        if (keepPreviousPeek) {
+            this.anchoredElement = element;
+            this.policy.anchorToTurn();
+        }
+        else {
+            this.anchoredElement = null;
+            this.policy.beginJump();
+        }
+        this.performScroll(target, options.behavior ?? 'auto');
+        this.scheduleVisibilitySync();
+        return true;
+    }
+    // MARK: - DOM events
+    handleScroll() {
+        const viewport = this.viewport;
+        if (!viewport)
+            return;
+        if (this.policy.programmaticTarget !== null &&
+            now() > this.programmaticDeadline) {
+            this.policy.cancelProgrammaticScroll();
+        }
+        const scrollTop = viewport.scrollTop;
+        const userScrolled = this.policy.handleScrollEvent({
+            scrollTop,
+            lastScrollTop: this.lastScrollTop,
+            atEnd: this.isAtEnd(),
+        });
+        this.lastScrollTop = scrollTop;
+        if (userScrolled) {
+            if (this.policy.mode !== 'anchored')
+                this.anchoredElement = null;
+            // A snapshot captured before this ownership change describes a layout
+            // the reader has scrolled away from; restoring against it would
+            // teleport the viewport. A fresh capture lands next frame.
+            this.readingLeaves = [];
+        }
+        this.scheduleStateCommit();
+        this.scheduleVisibilitySync();
+    }
+    handleWheel(deltaY) {
+        this.policy.handleUserIntent(deltaY < 0 ? 'up' : 'down');
+        if (this.policy.mode !== 'anchored')
+            this.anchoredElement = null;
+        this.readingLeaves = [];
+        this.scheduleStateCommit();
+    }
+    handleTouchMove() {
+        this.policy.handleUserIntent('unknown');
+        this.anchoredElement = null;
+        this.readingLeaves = [];
+        this.scheduleStateCommit();
+    }
+    handleScrollKey() {
+        this.policy.handleUserIntent('unknown');
+        this.anchoredElement = null;
+        this.readingLeaves = [];
+        this.scheduleStateCommit();
+    }
+    /**
+     * Content box resized (streaming growth, images decoding, disclosures
+     * collapsing, `content-visibility` reveals). Which way the viewport moves
+     * — if at all — is entirely the policy's call.
+     */
+    handleResize() {
+        const viewport = this.viewport;
+        if (!viewport) {
+            return;
+        }
+        switch (this.policy.resizeAction()) {
+            case 'stick-to-end': {
+                const target = maxScrollTop(viewport);
+                if (Math.abs(viewport.scrollTop - target) > POSITION_EPSILON_PX) {
+                    this.performScroll(target, 'auto');
+                }
+                break;
+            }
+            case 'reanchor': {
+                const anchored = this.anchoredElement;
+                if (anchored?.isConnected) {
+                    this.scrollToElement(anchored, { align: 'start' }, { keepPreviousPeek: true });
+                }
+                else {
+                    this.anchoredElement = null;
+                    this.policy.release();
+                }
+                break;
+            }
+            case 'preserve-reading-position':
+                this.restoreReadingPosition();
+                break;
+            case 'none':
+                break;
+        }
+        this.scheduleStateCommit();
+        this.scheduleVisibilitySync();
+    }
+    /** Children of the content element changed. Runs before the next paint. */
+    handleContentMutation() {
+        const children = this.itemChildren();
+        const previousFirst = this.previousFirstItem;
+        const previousCount = this.previousItemCount;
+        this.previousFirstItem = children[0] ?? null;
+        this.previousItemCount = children.length;
+        this.scheduleWarmup();
+        if (this.flushPendingScrollToMessage())
+            return;
+        if (previousCount === 0) {
+            // Everything present at mount is history; only anchors appended after
+            // this point can represent a new turn. Without this seeding, a later
+            // equal-count row replacement would treat the conversation's oldest
+            // prompt as "unhandled" and yank the viewport to the top.
+            this.markTurnAnchorsHandled(children, 0);
+            if (children.length > 0)
+                this.applyDefaultPosition(children);
+            this.scheduleStateCommit();
+            this.scheduleVisibilitySync();
+            return;
+        }
+        const previousFirstIndex = previousFirst
+            ? children.indexOf(previousFirst)
+            : -1;
+        if (this.preserveScrollOnPrepend && previousFirstIndex > 0) {
+            this.markTurnAnchorsHandled(children, 0);
+            this.preservePrependPosition();
+            return;
+        }
+        if (children.length > previousCount) {
+            const appendedAnchor = firstTurnAnchorAt(children, previousCount);
+            if (appendedAnchor) {
+                this.markTurnAnchorsHandled(children, previousCount);
+                if (this.policy.followsEnd &&
+                    countTurnAnchorsAt(children, previousCount) > 1) {
+                    // Several anchors at once is a history restore, not a new turn.
+                    this.scrollToEnd();
+                    return;
+                }
+                this.anchorTurn(appendedAnchor);
+                return;
+            }
+        }
+        if (children.length === previousCount && this.policy.mode === 'anchored') {
+            // A terminal snapshot can replace the live turn's rows one-for-one
+            // with their persisted forms; keep that turn anchored. The live turn
+            // is the newest anchor, so scan from the end.
+            let replacement = null;
+            for (let index = children.length - 1; index >= 0; index -= 1) {
+                const child = children[index];
+                if (child?.dataset.scrollAnchor === 'true' &&
+                    !this.handledTurnAnchors.has(child)) {
+                    replacement = child;
+                    break;
+                }
+            }
+            if (replacement) {
+                this.markTurnAnchorsHandled(children, 0);
+                this.anchorTurn(replacement);
+                return;
+            }
+        }
+        if (this.policy.followsEnd) {
+            this.scrollToEnd();
+            return;
+        }
+        this.scheduleStateCommit();
+        this.scheduleVisibilitySync();
+    }
+    observeVisibility() {
+        const viewport = this.viewport;
+        if (!viewport || !this.visibilityStore.hasListeners())
+            return;
+        if (typeof IntersectionObserver === 'undefined') {
+            this.scheduleVisibilitySync();
+            return;
+        }
+        if (!this.intersectionObserver) {
+            this.intersectionObserver = new IntersectionObserver((entries) => {
+                for (const entry of entries) {
+                    const messageId = entry.target.dataset.messageId;
+                    if (!messageId)
+                        continue;
+                    if (entry.isIntersecting)
+                        this.visibleMessageIds.add(messageId);
+                    else
+                        this.visibleMessageIds.delete(messageId);
+                }
+                this.scheduleVisibilitySync();
+            }, {
+                root: viewport,
+                rootMargin: `${-(this.options.scrollMargin + this.options.scrollPreviousItemPeek)}px 0px 0px 0px`,
+                threshold: [0, 0.01, 0.5, 1],
+            });
+            this.messageElements.forEach((element) => {
+                this.intersectionObserver?.observe(element);
+            });
+        }
+        this.scheduleVisibilitySync();
+    }
+    unobserveVisibility() {
+        if (this.visibilityFrame !== null) {
+            cancelAnimationFrame(this.visibilityFrame);
+            this.visibilityFrame = null;
+        }
+        this.intersectionObserver?.disconnect();
+        this.intersectionObserver = null;
+        this.visibleMessageIds.clear();
+        this.visibilityStore.setSnapshot(EMPTY_VISIBILITY);
+    }
+    resetDefaultPosition() {
+        this.defaultPositionApplied = false;
+    }
+    updateOptions(options) {
+        const autoScrollChanged = options.autoScroll !== this.options.autoScroll;
+        this.options = options;
+        this.policy.autoScroll = options.autoScroll;
+        if (autoScrollChanged && options.autoScroll && this.isAtEnd()) {
+            this.policy.jumpToEnd();
+        }
+    }
+    destroy() {
+        // Nulling the frame handles matters as much as cancelling them: the
+        // controller outlives a StrictMode unmount/remount cycle, and a stale
+        // non-null handle would block every future scheduled commit.
+        if (this.stateFrame !== null) {
+            cancelAnimationFrame(this.stateFrame);
+            this.stateFrame = null;
+        }
+        if (this.visibilityFrame !== null) {
+            cancelAnimationFrame(this.visibilityFrame);
+            this.visibilityFrame = null;
+        }
+        this.cancelWarmup();
+        this.unobserveVisibility();
+    }
+    // MARK: - Positioning
+    applyDefaultPosition(children) {
+        if (this.defaultPositionApplied)
+            return;
+        this.defaultPositionApplied = true;
+        const position = this.options.defaultScrollPosition;
+        if (position === 'start') {
+            this.scrollToStart();
+            return;
+        }
+        if (position === 'last-anchor') {
+            const viewport = this.viewport;
+            const content = this.content;
+            const lastAnchor = [...children]
+                .reverse()
+                .find((child) => child.dataset.scrollAnchor === 'true');
+            if (viewport && content && lastAnchor) {
+                const remaining = contentBottomWithoutSpacer(viewport, content, children) -
+                    elementTopInContent(lastAnchor, viewport);
+                if (remaining > viewport.clientHeight) {
+                    this.scrollToElement(lastAnchor, { align: 'start' }, { keepPreviousPeek: true });
+                    return;
+                }
+            }
+        }
+        this.scrollToEnd();
+    }
+    anchorTurn(anchor) {
+        this.handledTurnAnchors.add(anchor);
+        this.scrollToElement(anchor, { align: 'start' }, { keepPreviousPeek: true });
+    }
+    markTurnAnchorsHandled(children, fromIndex) {
+        for (let index = fromIndex; index < children.length; index += 1) {
+            const child = children[index];
+            if (child?.dataset.scrollAnchor === 'true') {
+                this.handledTurnAnchors.add(child);
+            }
+        }
+    }
+    /**
+     * Older rows were inserted above the reader. Compensate the scroll offset
+     * by the tracked first-visible row's displacement in the same mutation
+     * pass, before the shifted layout can paint.
+     */
+    preservePrependPosition() {
+        const viewport = this.viewport;
+        const tracked = this.trackedFirstVisible;
+        if (viewport && tracked?.element.isConnected) {
+            if (this.policy.followsEnd) {
+                this.scrollToEnd();
+                return;
+            }
+            const delta = elementViewportTop(tracked.element, viewport) - tracked.top;
+            if (Math.abs(delta) > POSITION_EPSILON_PX) {
+                viewport.scrollTop += delta;
+                this.lastScrollTop = viewport.scrollTop;
+            }
+            this.trackFirstVisibleItem();
+        }
+        this.scheduleStateCommit();
+        this.scheduleVisibilitySync();
+    }
+    performScroll(target, behavior) {
+        const viewport = this.viewport;
+        if (!viewport)
+            return;
+        // Clamp to what the viewport can actually reach: an unreachable target
+        // would never register arrival and would park the policy in a state
+        // where the next reader scroll is misread as programmatic motion.
+        const clamped = Math.min(Math.max(0, target), maxScrollTop(viewport));
+        this.policy.beginProgrammaticScroll(clamped);
+        const resolveInPlace = behavior === 'auto' ||
+            typeof viewport.scrollTo !== 'function' ||
+            Math.abs(viewport.scrollTop - clamped) <= POSITION_EPSILON_PX;
+        if (resolveInPlace) {
+            viewport.scrollTop = clamped;
+            this.lastScrollTop = viewport.scrollTop;
+            this.policy.handleScrollEvent({
+                scrollTop: viewport.scrollTop,
+                lastScrollTop: this.lastScrollTop,
+                atEnd: this.isAtEnd(),
+            });
+            this.scheduleStateCommit();
+            return;
+        }
+        // A smooth scroll that gets interrupted (content shrank, animation
+        // dropped) may never emit an arriving event; past the deadline the
+        // policy stops treating movement as its own.
+        this.programmaticDeadline = now() + PROGRAMMATIC_SCROLL_TIMEOUT_MS;
+        viewport.scrollTo({ top: clamped, behavior });
+        this.scheduleStateCommit();
+    }
+    // MARK: - Reading-position stability
+    /**
+     * Snapshot of stable leaves the reader can see. When a disclosure above
+     * them collapses (or a hidden row re-measures), the first still-visible
+     * leaf is re-pinned so the text under the reader's eyes never shifts.
+     */
+    snapshotReadingLeaves() {
+        const viewport = this.viewport;
+        const content = this.content;
+        if (!viewport || !content)
+            return;
+        this.readingLeaves = captureReadingLeaves(viewport, content, this.itemChildren());
+    }
+    restoreReadingPosition() {
+        const viewport = this.viewport;
+        if (!viewport)
+            return;
+        if (restoreReadingLeaves(viewport, this.readingLeaves)) {
+            this.lastScrollTop = viewport.scrollTop;
+            this.snapshotReadingLeaves();
+        }
+    }
+    trackFirstVisibleItem() {
+        const viewport = this.viewport;
+        if (!viewport) {
+            this.trackedFirstVisible = null;
+            return;
+        }
+        const viewportRect = viewport.getBoundingClientRect();
+        for (const child of this.itemChildren()) {
+            const rect = child.getBoundingClientRect();
+            if (rect.bottom > viewportRect.top && rect.top < viewportRect.bottom) {
+                this.trackedFirstVisible = {
+                    element: child,
+                    top: rect.top - viewportRect.top,
+                };
+                return;
+            }
+        }
+        this.trackedFirstVisible = null;
+    }
+    // MARK: - State stores
+    scheduleStateCommit() {
+        if (this.stateFrame !== null)
+            return;
+        this.stateFrame = requestAnimationFrame(() => {
+            this.stateFrame = null;
+            this.commitFrameState();
+        });
+    }
+    /**
+     * Once per frame: publish the scrollable edges and refresh the geometry
+     * snapshots (tracked first-visible row, reading leaves) that prepend
+     * preservation and reading-position restores compare against. Capturing
+     * here — instead of on every scroll event — bounds rect reads to one pass
+     * per frame.
+     */
+    commitFrameState() {
+        const viewport = this.viewport;
+        if (!viewport)
+            return;
+        const threshold = this.options.scrollEdgeThreshold;
+        const scrollable = {
+            start: viewport.scrollTop > threshold,
+            // While following, transient off-end moments (content grew; the
+            // follow-up scroll lands next tick) must not flash the jump button.
+            end: !this.policy.followsEnd &&
+                maxScrollTop(viewport) - viewport.scrollTop > threshold,
+        };
+        this.scrollableStore.setSnapshot(scrollable);
+        this.applyStateAttributes();
+        if (!this.policy.followsEnd) {
+            this.trackFirstVisibleItem();
+            if (this.policy.mode === 'free')
+                this.snapshotReadingLeaves();
+        }
+    }
+    applyStateAttributes() {
+        const scrollable = this.scrollableStore.getSnapshot();
+        const label = [
+            scrollable.start ? 'start' : null,
+            scrollable.end ? 'end' : null,
+        ]
+            .filter(Boolean)
+            .join(' ');
+        for (const element of [this.root, this.viewport]) {
+            if (!element)
+                continue;
+            if (label)
+                element.setAttribute('data-scrollable', label);
+            else
+                element.removeAttribute('data-scrollable');
+            element.toggleAttribute('data-autoscrolling', this.policy.programmaticTarget !== null);
+        }
+    }
+    scheduleVisibilitySync() {
+        if (!this.visibilityStore.hasListeners())
+            return;
+        if (this.visibilityFrame !== null)
+            return;
+        this.visibilityFrame = requestAnimationFrame(() => {
+            this.visibilityFrame = null;
+            if (!this.visibilityStore.hasListeners())
+                return;
+            this.visibilityStore.setSnapshot(this.computeVisibility());
+        });
+    }
+    computeVisibility() {
+        const viewport = this.viewport;
+        const content = this.content;
+        if (!viewport || !content)
+            return EMPTY_VISIBILITY;
+        const viewportRect = viewport.getBoundingClientRect();
+        const anchorLine = viewportRect.top +
+            this.options.scrollMargin +
+            this.options.scrollPreviousItemPeek;
+        const useRectFallback = typeof IntersectionObserver === 'undefined';
+        const visibleIds = [];
+        let currentAnchorId = null;
+        for (const child of this.itemChildren()) {
+            const messageId = child.dataset.messageId;
+            if (!messageId)
+                continue;
+            const isAnchor = child.dataset.scrollAnchor === 'true';
+            const rect = isAnchor || useRectFallback ? child.getBoundingClientRect() : null;
+            const isVisible = useRectFallback && rect
+                ? rect.bottom > anchorLine && rect.top < viewportRect.bottom
+                : this.visibleMessageIds.has(messageId);
+            if (isVisible)
+                visibleIds.push(messageId);
+            if (isAnchor && rect && rect.top <= anchorLine + POSITION_EPSILON_PX) {
+                currentAnchorId = messageId;
+            }
+        }
+        if (visibleIds.length === 0 && currentAnchorId === null) {
+            return EMPTY_VISIBILITY;
+        }
+        return { currentAnchorId, visibleMessageIds: visibleIds };
+    }
+    // MARK: - Content-visibility warm-up
+    /**
+     * Rows outside the viewport skip rendering via `content-visibility: auto`
+     * and a placeholder intrinsic size. Their first reveal during an upward
+     * scroll pays first-time layout of complex markdown — felt as hitches on
+     * the first pass through history. Rendering each row once at idle records
+     * its real size (the `auto` keyword keeps last-remembered sizes), so the
+     * first real scroll finds everything measured and warm.
+     */
+    scheduleWarmup() {
+        if (this.warmupHandle !== null)
+            return;
+        const run = () => {
+            this.warmupHandle = null;
+            this.warmupBatch();
+        };
+        if (typeof requestIdleCallback === 'function') {
+            this.warmupUsesIdleCallback = true;
+            this.warmupHandle = requestIdleCallback(run, { timeout: 1_000 });
+        }
+        else {
+            this.warmupUsesIdleCallback = false;
+            this.warmupHandle = window.setTimeout(run, 150);
+        }
+    }
+    warmupBatch() {
+        if (typeof getComputedStyle !== 'function')
+            return;
+        const batch = [];
+        for (const child of this.itemChildren()) {
+            if (this.warmedItems.has(child))
+                continue;
+            this.warmedItems.add(child);
+            const style = getComputedStyle(child);
+            const contentVisibility = style.getPropertyValue('content-visibility').trim() || 'visible';
+            if (contentVisibility === 'auto')
+                batch.push(child);
+            if (batch.length >= WARMUP_BATCH_SIZE)
+                break;
+        }
+        if (batch.length === 0)
+            return;
+        for (const element of batch) {
+            element.style.contentVisibility = 'visible';
+        }
+        requestAnimationFrame(() => {
+            // Back to the stylesheet's `auto`; the rendered pass left a
+            // remembered intrinsic size behind.
+            for (const element of batch) {
+                element.style.contentVisibility = '';
+            }
+            this.scheduleWarmup();
+        });
+    }
+    cancelWarmup() {
+        if (this.warmupHandle === null)
+            return;
+        if (this.warmupUsesIdleCallback &&
+            typeof cancelIdleCallback === 'function') {
+            cancelIdleCallback(this.warmupHandle);
+        }
+        else {
+            clearTimeout(this.warmupHandle);
+        }
+        this.warmupHandle = null;
+    }
+    // MARK: - Helpers
+    flushPendingScrollToMessage() {
+        const pending = this.pendingScrollToMessage;
+        if (!pending)
+            return false;
+        const element = this.messageElements.get(pending.messageId);
+        if (!element || !this.scrollToElement(element, pending.options)) {
+            return false;
+        }
+        this.pendingScrollToMessage = null;
+        this.defaultPositionApplied = true;
+        return true;
+    }
+    setSpacerHeight(height) {
+        const spacer = this.spacer;
+        const next = Math.max(0, Math.ceil(height));
+        if (!spacer || this.spacerHeight === next)
+            return;
+        this.spacerHeight = next;
+        spacer.hidden = next === 0;
+        spacer.style.height = `${next}px`;
+        spacer.style.marginTop = next > 0 ? `${-this.spacerGap}px` : '';
+    }
+    itemChildren() {
+        const content = this.content;
+        if (!content)
+            return [];
+        return Array.from(content.children).filter((child) => child instanceof HTMLElement && child !== this.spacer);
+    }
+    isAtEnd() {
+        const viewport = this.viewport;
+        if (!viewport)
+            return true;
+        return isMessageScrollerAtEnd(viewport, this.options.scrollEdgeThreshold);
+    }
+}
+function maxScrollTop(viewport) {
+    return Math.max(0, viewport.scrollHeight - viewport.clientHeight);
+}
+function elementViewportTop(element, viewport) {
+    return (element.getBoundingClientRect().top - viewport.getBoundingClientRect().top);
+}
+function elementTopInContent(element, viewport) {
+    return elementViewportTop(element, viewport) + viewport.scrollTop;
+}
+function readBlockPadding(element) {
+    if (!element || typeof getComputedStyle !== 'function') {
+        return { start: 0, end: 0 };
+    }
+    const style = getComputedStyle(element);
+    return {
+        start: parsePx(style.paddingBlockStart || style.paddingTop),
+        end: parsePx(style.paddingBlockEnd || style.paddingBottom),
+    };
+}
+function parsePx(value) {
+    const parsed = Number.parseFloat(value || '0');
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/**
+ * The content-space bottom of the real transcript: the lowest item edge plus
+ * the content's own padding. Measured from items instead of the content box
+ * so the anchoring spacer never feeds back into its own requirement.
+ */
+function contentBottomWithoutSpacer(viewport, content, items) {
+    const viewportRect = viewport.getBoundingClientRect();
+    const padding = readBlockPadding(content);
+    let bottom = padding.start + padding.end;
+    for (const item of items) {
+        const rect = item.getBoundingClientRect();
+        bottom = Math.max(bottom, rect.bottom - viewportRect.top + viewport.scrollTop + padding.end);
+    }
+    return bottom;
+}
+function alignedScrollTarget({ align, element, margin, padding, viewport, }) {
+    const top = elementTopInContent(element, viewport);
+    const height = element.getBoundingClientRect().height;
+    if (align === 'center') {
+        const available = Math.max(0, viewport.clientHeight - padding.start - padding.end);
+        return top - padding.start - (available - height) / 2 - margin;
+    }
+    if (align === 'end') {
+        return top - viewport.clientHeight + height + padding.end + margin;
+    }
+    if (align === 'nearest') {
+        const bottom = top + height;
+        const visibleTop = viewport.scrollTop + padding.start;
+        const visibleBottom = viewport.scrollTop + viewport.clientHeight - padding.end;
+        if (top >= visibleTop && bottom <= visibleBottom)
+            return viewport.scrollTop;
+        return top < visibleTop
+            ? top - padding.start - margin
+            : bottom - viewport.clientHeight + padding.end + margin;
+    }
+    return top - padding.start - margin;
+}
+function firstTurnAnchorAt(children, startIndex) {
+    for (let index = startIndex; index < children.length; index += 1) {
+        if (children[index]?.dataset.scrollAnchor === 'true') {
+            return children[index] ?? null;
+        }
+    }
+    return null;
+}
+function countTurnAnchorsAt(children, startIndex) {
+    let count = 0;
+    for (let index = startIndex; index < children.length; index += 1) {
+        if (children[index]?.dataset.scrollAnchor === 'true')
+            count += 1;
+    }
+    return count;
+}
+function readRowGap(element) {
+    if (!element || typeof getComputedStyle !== 'function')
+        return 0;
+    const style = getComputedStyle(element);
+    const gap = style.rowGap === 'normal' ? style.gap : style.rowGap;
+    const parsed = Number.parseFloat(gap || '0');
+    return Number.isFinite(parsed) ? parsed : 0;
+}