@moldable-ai/ui 0.2.20 → 0.2.21

package/dist/components/ui/message-scroller-controller.d.ts

@@ -0,0 +1,162 @@
+import { MessageScrollerPolicy } from './message-scroller-policy';
+export type MessageScrollerDefaultScrollPosition = 'start' | 'end' | 'last-anchor';
+export type MessageScrollerScrollAlign = 'start' | 'center' | 'end' | 'nearest';
+export type MessageScrollerScrollOptions = {
+    align?: MessageScrollerScrollAlign;
+    behavior?: ScrollBehavior;
+    scrollMargin?: number;
+};
+export type MessageScrollerScrollable = {
+    start: boolean;
+    end: boolean;
+};
+export type MessageScrollerVisibilityState = {
+    currentAnchorId: string | null;
+    visibleMessageIds: string[];
+};
+export interface MessageScrollerControllerOptions {
+    autoScroll: boolean;
+    defaultScrollPosition: MessageScrollerDefaultScrollPosition;
+    scrollEdgeThreshold: number;
+    scrollPreviousItemPeek: number;
+    scrollMargin: number;
+}
+export interface ExternalStore<T> {
+    getSnapshot: () => T;
+    hasListeners: () => boolean;
+    setSnapshot: (next: T) => void;
+    subscribe: (listener: () => void, onFirst?: () => void, onLast?: () => void) => () => void;
+}
+export declare function createExternalStore<T>(initial: T, isEqual: (a: T, b: T) => boolean): ExternalStore<T>;
+export type ReadingLeaf = {
+    element: HTMLElement;
+    top: number;
+    bottom: number;
+};
+export declare function isMessageScrollerAtEnd(viewport: HTMLElement, threshold: number): boolean;
+/**
+ * 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 declare function captureReadingLeaves(viewport: HTMLElement, content: HTMLElement, items: HTMLElement[]): ReadingLeaf[];
+/**
+ * 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 declare function restoreReadingLeaves(viewport: HTMLElement, leaves: readonly ReadingLeaf[]): boolean;
+/**
+ * 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 declare class MessageScrollerController {
+    readonly scrollableStore: ExternalStore<MessageScrollerScrollable>;
+    readonly visibilityStore: ExternalStore<MessageScrollerVisibilityState>;
+    policy: MessageScrollerPolicy;
+    options: MessageScrollerControllerOptions;
+    preserveScrollOnPrepend: boolean;
+    private root;
+    private viewport;
+    private content;
+    private spacer;
+    private readonly messageElements;
+    private readonly handledTurnAnchors;
+    private readonly visibleMessageIds;
+    private readonly warmedItems;
+    private lastScrollTop;
+    private previousFirstItem;
+    private previousItemCount;
+    private anchoredElement;
+    private trackedFirstVisible;
+    private readingLeaves;
+    private pendingScrollToMessage;
+    private defaultPositionApplied;
+    private spacerHeight;
+    private spacerGap;
+    private programmaticDeadline;
+    private stateFrame;
+    private visibilityFrame;
+    private warmupHandle;
+    private warmupUsesIdleCallback;
+    private intersectionObserver;
+    constructor(options: MessageScrollerControllerOptions);
+    get viewportElement(): HTMLElement | null;
+    setRoot(element: HTMLElement | null): void;
+    setViewport(element: HTMLElement | null): void;
+    setContent(element: HTMLElement | null): void;
+    setSpacer(element: HTMLElement | null): void;
+    registerMessage(messageId: string, element: HTMLElement | null, previous: HTMLElement | null): void;
+    scrollToEnd: (options?: MessageScrollerScrollOptions) => boolean;
+    scrollToStart: (options?: MessageScrollerScrollOptions) => boolean;
+    scrollToMessage: (messageId: string, options?: MessageScrollerScrollOptions) => boolean;
+    scrollToElement(element: HTMLElement, options?: MessageScrollerScrollOptions, { keepPreviousPeek }?: {
+        keepPreviousPeek?: boolean;
+    }): boolean;
+    handleScroll(): void;
+    handleWheel(deltaY: number): void;
+    handleTouchMove(): void;
+    handleScrollKey(): void;
+    /**
+     * 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(): void;
+    /** Children of the content element changed. Runs before the next paint. */
+    handleContentMutation(): void;
+    observeVisibility(): void;
+    unobserveVisibility(): void;
+    resetDefaultPosition(): void;
+    updateOptions(options: MessageScrollerControllerOptions): void;
+    destroy(): void;
+    private applyDefaultPosition;
+    private anchorTurn;
+    private markTurnAnchorsHandled;
+    /**
+     * 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.
+     */
+    private preservePrependPosition;
+    private performScroll;
+    /**
+     * 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.
+     */
+    private snapshotReadingLeaves;
+    private restoreReadingPosition;
+    private trackFirstVisibleItem;
+    private scheduleStateCommit;
+    /**
+     * 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.
+     */
+    private commitFrameState;
+    private applyStateAttributes;
+    private scheduleVisibilitySync;
+    private computeVisibility;
+    /**
+     * 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.
+     */
+    private scheduleWarmup;
+    private warmupBatch;
+    private cancelWarmup;
+    private flushPendingScrollToMessage;
+    private setSpacerHeight;
+    private itemChildren;
+    private isAtEnd;
+}
+//# sourceMappingURL=message-scroller-controller.d.ts.map

package/dist/components/ui/message-scroller-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller-controller.d.ts","sourceRoot":"","sources":["../../../src/components/ui/message-scroller-controller.ts"],"names":[],"mappings":"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"}