@danxbot/ui 20.10.0 → 20.12.0

package/dist/types/components/Board.d.ts

@@ -138,19 +138,6 @@ export interface BoardColumnProps<T> {
      * never colour or glyph alone (WCAG 1.4.1).
      */
     icon?: ReactNode;
-    /**
-     * DX-4540: the lane's real length when `column.items` holds only the cards
-     * loaded so far (a windowed lane, see the file header). The count badge, the
-     * empty-state decision and the WIP limit all read it instead of the loaded
-     * count, so a lane of 500 shows 500 while rendering 40. Omitted, they read
-     * `column.count` exactly as before.
-     *
-     * `null` is "the length is still being read" (a lane opening, or starting a
-     * new sort): the count shows a dash, and the lane is NOT empty — its cards
-     * are on their way, so the empty state stays away and the children (a
-     * `PagedWindowList` holding a loading placeholder) stay mounted.
-     */
-    total?: number | null;
     /**
      * DX-4540: controls drawn at the header's end, after the count — a
      * `SortMenu`, say. A slot of content, not a boolean: supplying it is what
@@ -163,7 +150,7 @@ export interface BoardColumnProps<T> {
      *  lane puts a `PagedWindowList` here — see the file header. */
     children?: ReactNode;
 }
-export declare function BoardColumn<T>({ column, emptyState, className, listClassName, accent, icon, total, actions, children, }: BoardColumnProps<T>): import("react").JSX.Element;
+export declare function BoardColumn<T>({ column, emptyState, className, listClassName, accent, icon, actions, children, }: BoardColumnProps<T>): import("react").JSX.Element;
 export interface BoardCardProps {
     id: BoardItemId;
     /** Position within its OWN column right now — same contract as

package/dist/types/components/DragDrop.d.ts

@@ -37,10 +37,19 @@ export interface DragDropContainerProps {
      * @default "y"
      */
     axis?: DragAxis;
+    /**
+     * DX-4540: for a container that renders only a window of a longer list — the
+     * position in the whole list of its first item. Every announcement then
+     * speaks the real place ("position 221 of 500"), not the place among what
+     * happens to be rendered. Give both or neither.
+     */
+    offset?: number;
+    /** The whole list's length, counting the carried item when it lives here. See `offset`. */
+    total?: number;
     className?: string;
     children?: ReactNode;
 }
-export declare function DragDropContainer({ id, label, axis, className, children, }: DragDropContainerProps): import("react").JSX.Element;
+export declare function DragDropContainer({ id, label, axis, offset, total, className, children, }: DragDropContainerProps): import("react").JSX.Element;
 export interface DragDropItemProps {
     id: DragId;
     /**

package/dist/types/components/PagedWindowList.d.ts

@@ -7,14 +7,14 @@ export interface PagedWindowStrings {
     retry: string;
 }
 export interface PagedWindowItemPosition {
-    /** Position among the items currently held, across every held page. */
+    /** Position among the items currently shown, across every shown page. */
     local: number;
-    /** Position in the whole list: `page * pageSize + index on the page`. */
+    /** Position in the whole list: `source.offset + local`. */
     global: number;
 }
 export interface PagedWindowListProps<T> {
     /** The window to render — what `usePagedWindow` returned. */
-    window: PagedWindow<T>;
+    source: PagedWindow<T>;
     /** Stable across renders and pages. Never an array index. */
     getKey: (item: T) => string | number;
     renderItem: (item: T, position: PagedWindowItemPosition) => ReactNode;
@@ -28,4 +28,4 @@ export interface PagedWindowListProps<T> {
     strings?: Partial<PagedWindowStrings>;
     className?: string;
 }
-export declare function PagedWindowList<T>({ window: win, getKey, renderItem, estimatedItemHeight, strings, className, }: PagedWindowListProps<T>): import("react").JSX.Element;
+export declare function PagedWindowList<T>({ source, getKey, renderItem, estimatedItemHeight, strings, className, }: PagedWindowListProps<T>): import("react").JSX.Element;

package/dist/types/components/paged-window/PageBlock.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode, Ref } from "react";
+import type { BlockStatus } from "../../lib/paged-window/layout";
+export interface PageBlockProps {
+    page: number;
+    status: BlockStatus;
+    /** The cards of a `ready` page. Ignored for every other status: they have none to show. */
+    children?: ReactNode;
+    /** How many cards a `ready` page shows (`data-count`, which the pitch measurement reads). */
+    count: number;
+    /** The height the page holds when it has no cards: items on it x the measured item height. */
+    height: number;
+    /** One item's height, for the loading rows. */
+    pitch: number;
+    /** Ref callback that returns its cleanup: how the list's observers find this block. */
+    blockRef: Ref<HTMLDivElement>;
+    errorText: string;
+    retryText: string;
+    onRetry: () => void;
+}
+/**
+ * THE ONE ELEMENT A PAGE IS, in every state. A page turns from placeholder to
+ * cards (a load), to placeholder again (a drop) and to an error row and back
+ * without this element being replaced: it is the same component type at the same
+ * key, so React keeps the same DOM node. That is what keeps the browser's scroll
+ * anchoring on the element under the viewport and keeps the observers attached
+ * (visibility and pitch) instead of detaching and re-attaching on every change.
+ * What changes is only what it holds and how it is drawn: the cards of a ready
+ * page, otherwise the page's height (and, while loading, faint rows; on failure,
+ * a Retry row).
+ */
+export declare function PageBlock({ page, status, children, count, height, pitch, blockRef, errorText, retryText, onRetry, }: PageBlockProps): import("react").JSX.Element;

package/dist/types/index.d.ts

@@ -113,10 +113,10 @@ export { DragDrop, DragDropContainer, DragDropItem, DragDropHandle, DragDropSurf
 export { KanbanBoard, type KanbanBoardProps, type KanbanLane, type KanbanMove, type KanbanRefusal, } from "./components/kanban/KanbanBoard";
 export { DEFAULT_DRAG_STRINGS, DRAG_INSTRUCTIONS_ID, DragInstructions, DragLiveRegion, DragSession, DragSessionProvider, applyMove, attachAutoScroll, attachKeyboardSensor, attachPointerSensor, attachSessionWindowListeners, isNoOp, resolveTarget, sameTarget, scrollVelocity, useCreateDragSession, useDragAnnouncements, useDragSession, useDragState, useDragLive, useDraggable, useDropContainer, type ContainerId, type DragAxis, type DragCancelEvent, type DragEndEvent, type DragId, type DragMode, type DragPhase, type DragSessionCallbacks, type DragStartEvent, type DragState, type AutoScrollOptions, type DragAnnouncementContext, type DragAnnouncementOptions, type DragAnnouncements, type DragInstructionsProps, type DragLiveRegionProps, type DragStrings, type DropTarget, type KeyboardSensorOptions, type PointerActivation, } from "./lib/dnd";
 export { Board, BoardColumn, BoardCard, BoardCardSurface, type BoardProps, type BoardColumnProps, type BoardCardProps, type BoardCardSurfaceProps, } from "./components/Board";
-export { buildBoardModel, resolveMove, applyBoardMoves, useBoard, type BoardModel, type UseBoardResult, } from "./lib/board";
-export type { BoardAccessors, BoardColumnDef, BoardColumnId, BoardColumnModel, BoardItemId, BoardMove, BoardMoveRequest, BoardMoveSource, BoardMoveVerdict, UseBoardOptions, } from "./lib/board";
+export { buildBoardModel, resolveMove, applyBoardMoves, useBoard, moveAnchor, columnLength, positionInColumn, type BoardModel, type MoveAnchor, type UseBoardResult, } from "./lib/board";
+export type { BoardAccessors, BoardColumnDef, BoardEdge, BoardColumnId, BoardColumnModel, BoardItemId, BoardMove, BoardMoveRequest, BoardMoveSource, BoardMoveVerdict, UseBoardOptions, } from "./lib/board";
 export { PagedWindowList, type PagedWindowItemPosition, type PagedWindowListProps, type PagedWindowStrings, } from "./components/PagedWindowList";
-export { PagedWindowStore, usePagedWindow, windowPageNumbers, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindow, type PagedWindowOptions, type PagedWindowSnapshot, type UsePagedWindowOptions, } from "./lib/paged-window";
+export { PagedWindowStore, usePagedWindow, windowPageNumbers, type LoadCount, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindow, type PagedWindowMode, type PagedWindowOptions, type PagedWindowSnapshot, type UsePagedWindowOptions, } from "./lib/paged-window";
 export type { MessageRole, MessagePart, TextPart, CodePart, ReasoningPart, ToolPart, ToolStatus, FilePart, ComponentPart, ChatFile, ChatMessage, RenderContext, PartRenderer, PartRenderers, ChatComponentRenderer, ChatComponents, } from "./components/chat/types";
 export { Chat, ChatPopover, type ChatProps, type ChatPopoverProps, type ChatSurface, } from "./components/chat/Chat";
 export { Message, MessagePartView, ToolCall, type MessageProps, type MessageAction, type MessagePartViewProps, type ToolCallProps, } from "./components/chat/Message";

package/dist/types/lib/board/anchor.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ==== MOVE ANCHOR ====
+ *
+ * What a server needs to place a card the board moved, when the board holds
+ * only a window of the column (DX-4540). A drop knows exactly one thing about
+ * where it landed: which LOADED neighbours it is between. It never knows the
+ * card's position in the whole column, and a client that tries to compute one
+ * from `to.index` is wrong the moment the window does not start at the top.
+ * So the request names the neighbours, and the server finds the place.
+ *
+ * `to.index` counts the destination's LOADED cards with the moved card already
+ * removed (the board's one index rule), so the card lands before
+ * `rest[to.index]`, where `rest` is the destination's loaded cards without the
+ * moved one. ONE neighbour is named, because a server places a card relative to
+ * one: the card it lands directly above (`beforeId`) whenever there is one, and
+ * only at the end of the loaded run, where nothing is below, the card it lands
+ * directly below (`afterId`). An empty destination names nothing.
+ *
+ * AN EDGE INTENT TRUMPS THE NEIGHBOURS. "Move to top" in a window that starts
+ * at card 221 means the top of the column, which no loaded neighbour can say,
+ * so the anchor carries the edge and no ids.
+ */
+import type { BoardEdge, BoardItemId, BoardMove } from "./types";
+/**
+ * EXACTLY ONE placement field is set — a server's lane-move takes one — or none
+ * for an empty destination:
+ *   beforeId  the moved card lands directly above this loaded card
+ *   afterId   it lands directly below this one: only when it lands after the last
+ *             loaded card, where nothing is below to name
+ *   edge      it goes to the very top or bottom of the whole column
+ */
+export type MoveAnchor = {
+    beforeId: BoardItemId;
+    afterId?: never;
+    edge?: never;
+} | {
+    afterId: BoardItemId;
+    beforeId?: never;
+    edge?: never;
+} | {
+    edge: BoardEdge;
+    beforeId?: never;
+    afterId?: never;
+} | {
+    beforeId?: never;
+    afterId?: never;
+    edge?: never;
+};
+/**
+ * @param destinationItems the destination column's LOADED cards (the moved card
+ *   may be among them, for a same-column move).
+ */
+export declare function moveAnchor<T>(destinationItems: readonly T[], move: BoardMove, getId: (item: T) => BoardItemId): MoveAnchor;

package/dist/types/lib/board/index.d.ts

@@ -8,7 +8,9 @@
  * NOT wired into the package's top-level `src/index.ts` — that barrel is
  * owned by the contract's author, not this agent (see this round's brief).
  */
-export type { BoardAccessors, BoardColumnDef, BoardColumnId, BoardColumnModel, BoardItemId, BoardMove, BoardMoveRequest, BoardMoveSource, BoardMoveVerdict, UseBoardOptions, } from "./types";
+export type { BoardAccessors, BoardColumnDef, BoardEdge, BoardColumnId, BoardColumnModel, BoardItemId, BoardMove, BoardMoveRequest, BoardMoveSource, BoardMoveVerdict, UseBoardOptions, } from "./types";
 export { buildBoardModel, type BoardModel } from "./model";
+export { moveAnchor, type MoveAnchor } from "./anchor";
+export { columnLength, positionInColumn } from "./position";
 export { applyBoardMoves, resolveMove, type ResolveMoveContext, type ResolvedMove, } from "./move";
 export { useBoard, type UseBoardResult } from "./use-board";

package/dist/types/lib/board/move.d.ts

@@ -146,6 +146,15 @@ export declare function resolveMove<T>(context: ResolveMoveContext<T>, request:
  * column membership on every subsequent `buildBoardModel` call, and
  * `buildBoardModel` only ever reads WITHIN-column order.
  *
+ * `to.edge` IS NOT APPLIED HERE. This arranges the cards it was given, and in a
+ * windowed column an edge move lands OUTSIDE the cards that are loaded — at the
+ * top or bottom of a list this function cannot see — so the index it would
+ * splice at is only the nearest loaded position, not the place the card is
+ * going. A consumer of a windowed column sends the move to its server (see
+ * `moveAnchor`) and re-reads the affected pages (`invalidateAll`); it does not
+ * apply an edge move locally. In a column with every card loaded the edge IS
+ * the index, and this function is exactly right.
+ *
  * NEVER WRITES A FIELD ON ANY ITEM — ONLY REPOSITIONS. `BoardAccessors` has
  * no setter, on purpose (the file header on `types.ts` — items are opaque),
  * so this function CANNOT change what `getColumnId` reports for a moved

package/dist/types/lib/board/position.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ==== COLUMN POSITION ====
+ *
+ * Two facts about a column that three callers each need and must not each work
+ * out for themselves (DX-4540): how long the column really is, and where in the
+ * whole column a loaded card sits. A windowed column holds only a few pages of
+ * a longer list, so the cards loaded are not the column.
+ *
+ * `buildBoardModel` decides the length once (the model's `count`); `resolveMove`
+ * works from the column DEFINITIONS before any model exists and must decide
+ * "is this card already at that edge" with the same rule; and the move menu
+ * decides what to offer from a card's place in the column. All three read these.
+ */
+import type { BoardColumnDef } from "./types";
+/**
+ * The column's length: its `total` when the definition gave a number, otherwise
+ * the cards loaded (`total` absent means every card is loaded; `null` means the
+ * length is still being read, so the loaded cards are all that is known).
+ */
+export declare function columnLength(def: Pick<BoardColumnDef, "total"> | undefined, loaded: number): number;
+/** The place in the whole column of the loaded card at `index`: the window's offset plus the index. */
+export declare function positionInColumn(def: Pick<BoardColumnDef, "offset"> | undefined, index: number): number;

package/dist/types/lib/board/types.d.ts

@@ -74,11 +74,42 @@ export interface BoardColumnDef {
      * Soft cap on item count. Exceeding it is a VISUAL event, not a blocked move
      * — a WIP limit exists to interrupt a human, and a board that refuses the
      * drop instead just teaches people to work around the board. The core reports
-     * `overWip`; the view layer is responsible for making it loud.
+     * `overWip`; the view layer is responsible for making it loud. The limit is
+     * judged against the column's real length (`total`), not what is loaded.
      */
     wipLimit?: number;
+    /**
+     * DX-4540: the column's real length when `items` holds only the cards loaded so
+     * far (a windowed lane). The model's `count` is this number, and `overWip`,
+     * the move menu's "is there anything above/below" and the drag announcements
+     * all read it. `null` means the length is still being read: the column is
+     * neither empty nor over its limit, and `count` falls back to the loaded
+     * cards. Omitted, every card of the column is loaded and the count is theirs.
+     */
+    total?: number | null;
+    /**
+     * DX-4540: the position in the whole column of the first loaded card, so a
+     * card at index 0 of `items` is spoken as "position 221", not "position 1".
+     * Only meaningful with `total`; the loaded cards must be one contiguous run
+     * of the column. @default 0
+     */
+    offset?: number;
 }
-/** One item's move. `to.index` counts the destination list without this item. */
+/**
+ * Where a move lands beyond what is loaded. In a windowed column `to.index` can
+ * only name a position among the LOADED cards, so a move to "the very top" or
+ * "the very bottom" of the column says so here and the consumer sends that
+ * intent to its server (see `moveAnchor`). In a column with every card loaded
+ * the edge is the same place as `index` 0 / the end, so a consumer that ignores
+ * it is still right.
+ */
+export type BoardEdge = "top" | "bottom";
+/**
+ * One item's move. `to.index` counts the destination list without this item —
+ * the LOADED list, in a windowed column. `to.edge`, when present, is the
+ * intent the index cannot carry; the index is then the nearest loaded position
+ * (0 for `"top"`, one past the last loaded card for `"bottom"`).
+ */
 export interface BoardMove {
     itemId: BoardItemId;
     from: {
@@ -88,6 +119,7 @@ export interface BoardMove {
     to: {
         columnId: BoardColumnId;
         index: number;
+        edge?: BoardEdge;
     };
 }
 /**
@@ -125,11 +157,22 @@ export type BoardMoveVerdict = {
 export interface BoardColumnModel<T> {
     id: BoardColumnId;
     label: string;
+    /** The cards loaded. All of the column's cards unless the column is windowed. */
     items: readonly T[];
-    /** Count is on the model because the view needs it before it renders rows. */
+    /**
+     * The column's length: its `total` when the definition gave one, else the
+     * loaded cards. Count is on the model because the view needs it before it
+     * renders rows — and because it is computed ONCE here: the badge, the empty
+     * state, the WIP verdict, the move menu and the announcements all read this
+     * number, never their own.
+     */
     count: number;
+    /** `true` while a windowed column's length is still being read (`total: null`). `count` is then the loaded cards. */
+    counting: boolean;
+    /** Position in the whole column of `items[0]`; 0 unless the column is windowed. */
+    offset: number;
     wipLimit: number | undefined;
-    /** `true` when `count` exceeds `wipLimit`. Always false with no limit set. */
+    /** `true` when `count` exceeds `wipLimit`. Always false with no limit set, and while `counting`. */
     overWip: boolean;
 }
 export interface UseBoardOptions<T> {

package/dist/types/lib/dnd/announce.d.ts

@@ -7,7 +7,7 @@ export interface DragAnnouncementContext {
     label: string;
     container: ContainerId;
     containerLabel: string;
-    /** 1-based, as spoken. */
+    /** 1-based, as spoken, in the WHOLE container — a windowed container reports its real offset and length (DX-4540). */
     position: number;
     /**
      * The list length WITH the carried item counted in it, so `position` is never

package/dist/types/lib/dnd/session.d.ts

@@ -94,6 +94,18 @@ export declare class DragSession {
     cancel(): void;
     /** The container the pointer is over right now, or null. */
     containerAtPoint(point: Point): string | null;
+    /**
+     * Where a drop target sits, as a person is told it: 1-based, in the WHOLE
+     * container, with the whole container's length counted with the carried item
+     * in it. A container that renders every item is its own whole (the items
+     * registered under it); a windowed one says so at registration (`offset`,
+     * `total`) and the answer follows. `index` counts the container with the
+     * carried item already removed — the engine's one index rule.
+     */
+    spokenPosition(container: string, index: number, carried: DragId): {
+        position: number;
+        total: number;
+    };
     /** How many items a container holds once the carried one is taken out. */
     slotCount(container: string): number;
 }

package/dist/types/lib/dnd/types.d.ts

@@ -95,6 +95,15 @@ export interface ContainerRegistration {
     id: ContainerId;
     element: HTMLElement;
     axis: DragAxis;
+    /**
+     * DX-4540: for a container that renders only a window of a longer list. The
+     * position in the whole list of its first registered item, so a drop spoken
+     * as "position 221 of 500" is true. Absent for a container that holds every
+     * item.
+     */
+    offset?: number;
+    /** The whole list's length, the carried item counted in it when it lives here. See `offset`. */
+    total?: number;
 }
 /** One item's measured box, taken at snapshot time. */
 export interface ItemRect {

package/dist/types/lib/dnd/use-drag.d.ts

@@ -55,6 +55,10 @@ export declare function useDraggable(session: DragSession, options: UseDraggable
 export interface UseDropContainerOptions {
     id: ContainerId;
     axis?: DragAxis;
+    /** See `ContainerRegistration.offset` — a windowed container's first item's place in the whole list. */
+    offset?: number;
+    /** See `ContainerRegistration.total` — a windowed container's whole length. */
+    total?: number;
 }
 export interface UseDropContainerResult {
     setContainerRef: (el: HTMLElement | null) => void;

package/dist/types/lib/dom/scroll-ancestor.d.ts

@@ -0,0 +1,15 @@
+export type ScrollAxis = "x" | "y";
+export interface ScrollBoxOptions {
+    /** The axes that count; a box scrolling along any of them qualifies. @default ["y"] */
+    axes?: readonly ScrollAxis[];
+    /** Also require the content to overflow the box on that axis, not merely allow scrolling. @default false */
+    mustOverflow?: boolean;
+}
+export interface ScrollAncestorOptions extends ScrollBoxOptions {
+    /** Whether `from` itself may be the answer. Required: it is a statement about the caller. */
+    includeSelf: boolean;
+}
+/** Does `el` scroll along any of the given axes? */
+export declare function isScrollBox(el: HTMLElement, { axes, mustOverflow }?: ScrollBoxOptions): boolean;
+/** The nearest box that scrolls, walking up from `from`; null when none does. */
+export declare function nearestScrollAncestor(from: Element | null, { includeSelf, ...box }: ScrollAncestorOptions): HTMLElement | null;

package/dist/types/lib/paged-window/index.d.ts

@@ -1,2 +1,2 @@
-export { PagedWindowStore, windowPageNumbers, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindowOptions, type PagedWindowSnapshot, } from "./store";
+export { PagedWindowStore, windowPageNumbers, type LoadCount, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindowMode, type PagedWindowOptions, type PagedWindowSnapshot, } from "./store";
 export { usePagedWindow, type PagedWindow, type UsePagedWindowOptions } from "./use-paged-window";

package/dist/types/lib/paged-window/layout.d.ts

@@ -0,0 +1,21 @@
+import type { PageSnapshot } from "./store";
+/**
+ * What a page's block is showing. One name for every case, so the list renders
+ * ONE kind of block and only this changes:
+ *   ready    the page's cards are shown
+ *   loading  held, its request is in flight
+ *   error    held, its request failed
+ *   waiting  held and ready, but past a hole in the loaded run — not shown until
+ *            the page that closes the hole arrives (see the store header)
+ *   unheld   outside the window: empty space of the right height
+ */
+export type BlockStatus = "ready" | "loading" | "error" | "waiting" | "unheld";
+export declare function blockStatus<T>(held: PageSnapshot<T> | undefined): BlockStatus;
+/**
+ * How many page blocks to render. One per page of the list; before the first
+ * response the length is unknown but page 0 is being asked for, and one block
+ * stands in for it, so a new query does not flash an empty list.
+ */
+export declare function blockCountFor(pageCount: number, heldPageCount: number): number;
+/** The height of a page's placeholder: the items it holds (the last page is short) times one item's height. */
+export declare function placeholderHeight(page: number, pageSize: number, total: number, pitch: number): number;

package/dist/types/lib/paged-window/store.d.ts

@@ -9,6 +9,9 @@ export interface LoadPageContext {
     signal: AbortSignal;
 }
 export type LoadPage<T> = (page: number, context: LoadPageContext) => Promise<PageResponse<T>>;
+/** Answers the list's length alone — no items. What a hidden (`count` mode) lane asks. */
+export type LoadCount = (context: LoadPageContext) => Promise<number>;
+export type PagedWindowMode = "pages" | "count";
 export type PageStatus = "loading" | "ready" | "error";
 export interface PageSnapshot<T> {
     page: number;
@@ -19,8 +22,11 @@ export interface PageSnapshot<T> {
     refreshing: boolean;
     /** What the load rejected with. Only on `error`. */
     error: unknown;
+    /** Part of the loaded run — its items are in `items`. A ready page past a hole is not, until the hole closes. */
+    shown: boolean;
 }
 export interface PagedWindowSnapshot<T> {
+    mode: PagedWindowMode;
     /** The list's length as the latest response reported it; null before the first. */
     total: number | null;
     pageSize: number;
@@ -32,14 +38,22 @@ export interface PagedWindowSnapshot<T> {
     epoch: number;
     /** The held pages, ascending. At most `windowPages` of them. */
     pages: readonly PageSnapshot<T>[];
-    /** Every item of every `ready` held page, in list order. At most `windowPages * pageSize`. */
+    /** The loaded run: the items of the shown pages, in list order. At most `windowPages * pageSize`. */
     items: readonly T[];
+    /** The position in the whole list of `items[0]`; 0 when nothing is loaded. */
+    offset: number;
+    /** What the last `loadCount` rejected with; undefined otherwise. */
+    countError: unknown;
 }
 export interface PagedWindowOptions<T> {
     pageSize: number;
     /** How many pages are held at once. @default 3 */
     windowPages?: number;
     loadPage: LoadPage<T>;
+    /** Required to use `count` mode. */
+    loadCount?: LoadCount;
+    /** @default "pages" */
+    mode?: PagedWindowMode;
 }
 /**
  * The pages to hold for an anchor: `windowPages` of them centred on it (the
@@ -51,61 +65,84 @@ export declare class PagedWindowStore<T> {
     private readonly pageSize;
     private readonly windowPages;
     private loadPage;
+    private loadCount;
     private held;
     private total;
     private anchor;
     /** The anchor the held pages were last synced to; differs from `anchor` only while frozen. */
     private appliedAnchor;
-    private enabled;
+    private mode;
     private frozen;
     private epoch;
     private nextToken;
+    private countRequest;
+    /** Answers that arrived while frozen, applied in arrival order on thaw. */
+    private heldAnswers;
+    /** Pages whose refresh was asked for while frozen. */
+    private queuedPages;
+    /** The length's refresh (count mode) was asked for while frozen. */
+    private queuedCount;
+    private countError;
     private snapshot;
     private listeners;
-    constructor({ pageSize, windowPages, loadPage }: PagedWindowOptions<T>);
+    constructor({ pageSize, windowPages, loadPage, loadCount, mode }: PagedWindowOptions<T>);
     /**
-     * Replaced on every render by the React binding, so a consumer's loader can
-     * close over fresh state without the store being rebuilt (rebuilding drops
-     * every held page). A change in WHAT is loaded is a `reset`, never this.
+     * Replace the loaders. The React binding calls this after every commit so a
+     * consumer's loaders can close over fresh state without the store being
+     * rebuilt (rebuilding drops every held page). A change in WHAT is loaded is a
+     * `reset`, never this.
      */
-    setLoader(loadPage: LoadPage<T>): void;
+    setLoaders(loadPage: LoadPage<T>, loadCount: LoadCount | undefined): void;
     getSnapshot: () => PagedWindowSnapshot<T>;
     subscribe: (listener: () => void) => (() => void);
     /** The viewer moved to another page. Ignored while frozen, applied on thaw. */
     setAnchorPage(page: number): void;
     /**
-     * While true the window neither loads nor drops pages, whatever the anchor
-     * does. A drag needs it: the carried card is mounted in its page, and
-     * dropping that page mid-drag would unmount the card and cancel the drag.
+     * While true the window neither loads nor drops pages, whatever the anchor or
+     * the total does. A drag needs it: the carried card is mounted in its page,
+     * and dropping that page mid-drag would unmount the card and cancel the drag.
      */
     setFrozen(frozen: boolean): void;
-    /** Off, nothing is held or requested. Back on, the window loads again. */
-    setEnabled(enabled: boolean): void;
+    /** `count` holds and requests no cards, only the length (see the file header). */
+    setMode(mode: PagedWindowMode): void;
     /** The query changed: forget everything, return to the first page. */
     reset(): void;
     /** Re-read one held page in place. A page that is not held loads fresh when it is next wanted. */
     invalidatePage(page: number): void;
-    /** Re-read every held page in place. */
+    /** Re-read every held page in place; in `count` mode, re-ask the length. */
     invalidateAll(): void;
-    /** Load the first window. The binding calls it on mount, and again after a `stop`. */
+    /** Load the first window (or the length). The binding calls it on mount, and again after a `stop`. */
     start(): void;
-    /** Abort every request and release every held page. The binding calls it on unmount. */
+    /** Abort every request and release every page. The binding calls it on unmount. */
     stop(): void;
+    private requireCountLoader;
     private pageCount;
     /**
-     * Pages to hold now. Page 0 alone before the first response (the count is
-     * unknown) and for an empty list: an empty page is still held, because it is
-     * what `invalidateAll` re-reads when the list gets its first item — an empty
-     * lane that holds nothing could never find out it was no longer empty.
+     * Pages to hold now. None in `count` mode. Page 0 alone before the first
+     * response (the count is unknown) and for an empty list: an empty page is
+     * still held, because it is what `invalidateAll` re-reads when the list gets
+     * its first item — an empty lane that holds nothing could never find out it
+     * was no longer empty.
      */
     private wanted;
+    /** Bring the held pages to the wanted ones — unless frozen, when that waits for the thaw. */
     private sync;
+    private reconcile;
+    /** Everything the frozen window put off, in the order the header promises. */
+    private thaw;
     /** Start (or restart) a page's request; whatever was in flight is abandoned. */
     private request;
     private settle;
-    /** The list shrank: a held page past its end has nothing to show. */
-    private dropBeyondCount;
+    private requestCount;
+    private settleCount;
+    private abortCount;
     private dropAll;
+    /**
+     * The longest unbroken stretch of ready pages inside the list, lowest on a
+     * tie. Pages past the list's end (it shrank while the window was frozen) are
+     * not part of any run.
+     */
+    private loadedRun;
     private build;
     private publish;
 }

package/dist/types/lib/paged-window/use-measured-pitch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * How tall one item really is — measured, not guessed. DX-4540.
+ *
+ * A page that is not held is drawn as a placeholder of `items x pitch`, so the
+ * scrollbar is only as true as the pitch. `estimated` stands in until pages
+ * have been seen; after that the pitch is the MEAN over every item measured,
+ * which is a ResizeObserver over the page blocks.
+ *
+ * EVERY block is observed, because a block turns from placeholder to cards (and
+ * back) without its element being replaced: only a block that currently holds
+ * cards (`data-count`) is a measurement of what a card costs; a placeholder's
+ * own size is the estimate drawn back at us. A block that stops holding cards,
+ * or is removed, leaves its LAST reading in the mean (`departed`), so dropping
+ * a page does not make the estimate lurch and every placeholder above the
+ * viewer resize with it.
+ *
+ * A change under half a pixel is not published: re-laying-out every placeholder
+ * in a long list for sub-pixel drift is cost with no picture.
+ *
+ * NOTHING IS EVER RESET, AND THAT IS DELIBERATE. A new query (another sort, a
+ * different time range) lists the same kind of card, so what was learned about
+ * its height still holds; clearing it would snap every placeholder back to the
+ * estimate and make the first screen of the new query jump. The measurement is
+ * only a sizing aid for space no card occupies, and the mean keeps correcting
+ * itself from every page that is shown.
+ *
+ * A block whose size does not change when it turns from placeholder to cards
+ * (or back) fires no resize, so its reading is picked up at the next size change;
+ * a placeholder is sized from the estimate in the first place.
+ */
+export declare function useMeasuredPitch(estimated: number): {
+    pitch: number;
+    observe: (el: HTMLElement) => () => void;
+};

package/dist/types/lib/paged-window/use-page-visibility.d.ts

@@ -0,0 +1,20 @@
+import type { ScrollRoot } from "./use-scroll-root";
+/**
+ * The page the window should centre on: the middle one (lower middle when
+ * even) of the pages whose blocks intersect the root. A viewport shorter than
+ * a page sees one or two; the window of three covers either. Null when nothing
+ * is in view (a hidden scroller), so the window keeps where it was.
+ */
+export declare function centrePage(visible: ReadonlySet<Element>): number | null;
+/**
+ * Which pages are in view, from one IntersectionObserver over every page block,
+ * rooted at the scroller — no scroll listener, no polling. DX-4540.
+ *
+ * `observe(el)` is what a block's ref calls; it returns the cleanup. It is
+ * stable, and blocks that mount before the observer exists (it needs the
+ * resolved scroller) are picked up when it does. Whenever the set in view
+ * changes, `onCentre` is told the page to centre on.
+ */
+export declare function usePageVisibility(scroller: ScrollRoot | null, onCentre: (page: number) => void): {
+    observe: (el: HTMLElement) => () => void;
+};