@dxos/react-ui-feed 0.11.1

package/dist/types/src/testing/debug/use-feed-debug.d.ts

@@ -0,0 +1,33 @@
+import { type RefObject } from 'react';
+import { type FrameMeter } from '../../debug';
+export type FeedDebugOptions = {
+    /** What the pass ran under; the recorded line carries these rather than a story name. */
+    scenario?: string;
+    count: number;
+    estimateSize?: number;
+    streaming: boolean;
+    /** Whether the outlines start on. Off: they are for a question, not for every reading. */
+    enabled?: boolean;
+};
+export type FeedDebug = {
+    /** Whether the item and block outlines are drawn. */
+    debug: boolean;
+    toggleDebug: () => void;
+    /** Frame statistics and the control that records a pass. */
+    meter: FrameMeter;
+    /** Attach to the viewport: the sweep needs the element it is going to scroll. */
+    viewportRef: RefObject<HTMLDivElement | null>;
+    sweeping: boolean;
+    /** Start a measured pass, or cancel the one running. */
+    onSweep: () => void;
+};
+/**
+ * Everything the harness measures itself with, in one place.
+ *
+ * Kept apart from the story deliberately: instrumentation accumulates — a meter, a sweep, a toggle,
+ * a label, the refs and teardown each needs — and threaded through a component it slowly becomes
+ * the component. As an aspect the story stays about the feed, and what is being measured can be
+ * read, changed or dropped in one file.
+ */
+export declare const useFeedDebug: ({ scenario, count, estimateSize, streaming, enabled, }: FeedDebugOptions) => FeedDebug;
+//# sourceMappingURL=use-feed-debug.d.ts.map

package/dist/types/src/testing/debug/use-feed-debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-feed-debug.d.ts","sourceRoot":"","sources":["../../../../../src/testing/debug/use-feed-debug.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,SAAS,EAAqD,MAAM,OAAO,CAAC;AAE1F,OAAO,EAAE,KAAK,UAAU,EAAiB,MAAM,aAAa,CAAC;AAG7D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,4DAA4D;IAC5D,KAAK,EAAE,UAAU,CAAC;IAClB,iFAAiF;IACjF,WAAW,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC9C,QAAQ,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,2DAMtB,gBAAgB,KAAG,SA4CrB,CAAC"}

package/dist/types/src/testing/generator.d.ts

@@ -0,0 +1,16 @@
+import { Message } from '@dxos/types';
+export type MessageKind = 'markdown' | 'html' | 'code' | 'short';
+export type GeneratorOptions = {
+    count: number;
+    /** Relative weights per kind; a mixed feed is the realistic case (email threads, AI chats). */
+    kinds?: MessageKind[];
+    seed?: number;
+};
+/**
+ * Synthetic feed for measuring the engine.
+ *
+ * Heights are deliberately uneven — a uniform-height feed would hide exactly the measurement
+ * problem the spike exists to answer.
+ */
+export declare const createMessages: ({ count, kinds, seed, }: GeneratorOptions) => Message.Message[];
+//# sourceMappingURL=generator.d.ts.map

package/dist/types/src/testing/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../src/testing/generator.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAIF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,4BAIxB,gBAAgB,KAAG,OAAO,CAAC,OAAO,EAcpC,CAAC"}

package/dist/types/src/testing/index.d.ts

@@ -0,0 +1,10 @@
+export * from './FeedStory';
+export * from './MessageWindow';
+export * from './controls';
+export * from './debug';
+export * from './generator';
+export * from './scenarios';
+export * from './stream';
+export * from './turn';
+export * from './widgets';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC"}

package/dist/types/src/testing/scenarios.d.ts

@@ -0,0 +1,58 @@
+import { type ComponentType } from 'react';
+import { Message } from '@dxos/types';
+import { type XmlWidgetRegistry } from '@dxos/ui-editor';
+import { type MessageChromeProps, type MessageRenderer } from '../';
+/**
+ * The five places in the repo that render a thread of messages, approximated against one engine.
+ *
+ * The point is not the fixtures — it is that all five differ only in the renderer, the chrome and a
+ * couple of options, while the list, the virtualization, the selection and the search are the same
+ * code. Where a scenario needs something the engine does not have, that is the finding.
+ */
+export type FeedScenario = 
+/** No editor at all: fixed-height divs, so the list is measured against content that cannot move. */
+'plain'
+/** One editor per row, every row identical — the same document, so every height is the same. */
+ | 'uniform'
+/** The `uniform` rows with their text as a paragraph: the same feed without a document at all. */
+ | 'uniform-text'
+/** The `uniform` rows with an editor carrying nothing but line wrapping. */
+ | 'uniform-bare'
+/** The `uniform` rows with wrapping and the theme, but no markdown and no decoration. */
+ | 'uniform-themed'
+/** The `uniform` rows with the markdown language, but nothing drawn from what it parses. */
+ | 'uniform-markdown'
+/** The `uniform` rows with markdown drawn as itself: headings, lists, links. */
+ | 'uniform-decorated'
+/** The `uniform` rows rendered by the real item, reached through `Custom` like the probes. */
+ | 'uniform-item' | 'assistant' | 'email' | 'thread' | 'comments' | 'transcript';
+export type ScenarioDefinition = {
+    messages: Message.Message[];
+    renderer: MessageRenderer;
+    /** Widgets for the tags the renderer emits; only the assistant turn has non-prose blocks. */
+    registry?: XmlWidgetRegistry;
+    Chrome: ComponentType<MessageChromeProps>;
+    /** Renders a `custom` item, for the scenarios that deliberately avoid an editor. */
+    Custom?: ComponentType<{
+        content: any;
+        message: Message.Message;
+    }>;
+    /** Whether the feed follows its tail: true where messages arrive, false where they are read. */
+    stickyBottom: boolean;
+    /**
+     * Height a row is assumed to have before it is measured. A function where rows differ widely: a
+     * one-line prompt and a long answer share no useful average, and a row measured for the first time
+     * re-lays everything below it — which the reader sees as flicker when scrolling up, into rows that
+     * have never been measured.
+     */
+    estimateSize: number | ((message: Message.Message, index: number) => number);
+    /** Which messages the arrows and the navigation buttons stop on. */
+    isAnchor?: (message: Message.Message, index: number) => boolean;
+};
+export type ScenarioOptions = {
+    scenario: FeedScenario;
+    count: number;
+    seed?: number;
+};
+export declare const createScenario: ({ scenario, count, seed }: ScenarioOptions) => ScenarioDefinition;
+//# sourceMappingURL=scenarios.d.ts.map

package/dist/types/src/testing/scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios.d.ts","sourceRoot":"","sources":["../../../../src/testing/scenarios.tsx"],"names":[],"mappings":"AAIA,OAAc,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAIlD,OAAO,EAAqB,OAAO,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAiC,MAAM,KAAK,CAAC;AAoBnG;;;;;;GAMG;AACH,MAAM,MAAM,YAAY;AACtB,qGAAqG;AACnG,OAAO;AACT,gGAAgG;GAC9F,SAAS;AACX,kGAAkG;GAChG,cAAc;AAChB,4EAA4E;GAC1E,cAAc;AAChB,yFAAyF;GACvF,gBAAgB;AAClB,4FAA4F;GAC1F,kBAAkB;AACpB,gFAAgF;GAC9E,mBAAmB;AACrB,8FAA8F;GAC5F,cAAc,GACd,WAAW,GACX,OAAO,GACP,QAAQ,GACR,UAAU,GACV,YAAY,CAAC;AAEjB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,MAAM,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC1C,oFAAoF;IACpF,MAAM,CAAC,EAAE,aAAa,CAAC;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAA;KAAE,CAAC,CAAC;IACnE,gGAAgG;IAChG,YAAY,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAC7E,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CACjE,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,cAAc,8BAAqC,eAAe,KAAG,kBA6FjF,CAAC"}

package/dist/types/src/testing/stream.d.ts

@@ -0,0 +1,22 @@
+export type TextStreamOptions = {
+    /** Delay between chunks in ms. */
+    chunkDelay?: number;
+    /** Variance in timing (0-1). */
+    variance?: number;
+    /** Words per chunk. */
+    wordsPerChunk?: number;
+};
+/**
+ * Word-by-word stream, the shape a model emits: chunks of a few words at an uneven cadence.
+ *
+ * Whitespace is preserved as its own token so a chunk boundary never fuses two words, which would
+ * corrupt the markdown the item is parsing mid-stream.
+ */
+export declare function textStream(text: string, options?: TextStreamOptions): AsyncGenerator<string, void>;
+/**
+ * A plausible assistant answer: prose, a list, a code block and a closing paragraph — enough
+ * structure that the item re-parses markdown as the text arrives, rather than growing one flat
+ * paragraph.
+ */
+export declare const createAnswer: () => string;
+//# sourceMappingURL=stream.d.ts.map

package/dist/types/src/testing/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../../src/testing/stream.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,wBAAuB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAuB7G;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAO,MAkBlB,CAAC"}

package/dist/types/src/testing/turn.d.ts

@@ -0,0 +1,21 @@
+import { type ContentBlock } from '@dxos/types';
+export type TurnOptions = {
+    chunkDelay?: number;
+    wordsPerChunk?: number;
+};
+/**
+ * One assistant turn as the blocks a model actually emits, arriving in order.
+ *
+ * The text-only stream exercises the easy half of reconciliation: a tail that only ever grows, which
+ * the item appends. A real turn is harder in three ways, and each is a separate way for an item to
+ * be rebuilt instead of extended —
+ *
+ * 1. a **status** block appears first and is removed once work begins, so the document shrinks;
+ * 2. **reasoning** streams inside an unclosed tag and is closed when it completes, which rewrites
+ *    the end of the document rather than appending to it;
+ * 3. a **tool call** lands whole, then its **result** arrives as a second block after it.
+ *
+ * Yields the complete block array at each step; the caller replaces the message's blocks with it.
+ */
+export declare function streamTurn({ chunkDelay, wordsPerChunk }?: TurnOptions): AsyncGenerator<ContentBlock.Any[], void>;
+//# sourceMappingURL=turn.d.ts.map

package/dist/types/src/testing/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../../../src/testing/turn.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,MAAM,WAAW,GAAG;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAuB,UAAU,CAAC,EAAE,UAAgB,EAAE,aAAiB,EAAE,GAAE,WAAgB,GAAG,cAAc,CAC1G,YAAY,CAAC,GAAG,EAAE,EAClB,IAAI,CACL,CA2DA"}

package/dist/types/src/testing/widgets.d.ts

@@ -0,0 +1,3 @@
+import { type XmlWidgetRegistry } from '@dxos/ui-editor';
+export declare const chatRegistry: XmlWidgetRegistry;
+//# sourceMappingURL=widgets.d.ts.map

package/dist/types/src/testing/widgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widgets.d.ts","sourceRoot":"","sources":["../../../../src/testing/widgets.tsx"],"names":[],"mappings":"AAQA,OAAO,EAAuB,KAAK,iBAAiB,EAAmB,MAAM,iBAAiB,CAAC;AAsJ/F,eAAO,MAAM,YAAY,EAAE,iBAwB1B,CAAC"}

package/dist/types/src/virtualizer/Window.d.ts

@@ -0,0 +1,137 @@
+import React, { type ReactNode, type Ref } from 'react';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { type EdgeDrift, type Extents, type Layout, Placement } from './placement';
+/**
+ * What the window needs from a model, structurally — `ListModel`/`FeedModel` satisfy it, and the
+ * virtualizer stays importable without the model layer. The contract is SPEC F-7.1: a change says
+ * what it was (`prepended`), so the anchor is told rather than left to infer it from identities.
+ */
+export type WindowModel = {
+    readonly count: number;
+    getId: (index: number) => string;
+    subscribe: (listener: (change: {
+        prepended?: number;
+        appended?: number;
+        updated?: readonly string[];
+    }) => void) => () => void;
+};
+/**
+ * The DOM shape, and nothing else.
+ *
+ * Three elements: a **sizer** that holds no rows and exists only to give the thumb something to
+ * measure, a **window** holding the mounted rows in normal flow, and the scroller around them. The
+ * window is absolutely positioned and moved by a transform, so a correction changes one number and
+ * never touches `scrollTop` — which is what stops corrections and the reader sharing a channel (§7).
+ *
+ * Rows are unpositioned. A row that changes extent reflows the ones after it, in the browser, in the
+ * same frame; the alternative was re-placing every row below it ourselves on every frame of the
+ * change — measured at 177 re-placements for one disclosure opening (§6).
+ *
+ * Knows nothing about messages, markdown or CodeMirror. What it renders is whatever `children`
+ * returns, which is what lets `placement/*` drive it with content that cannot lie about its size.
+ */
+export type WindowAxis = 'block' | 'inline';
+/**
+ * What a toolbar or a readout needs, and nothing more.
+ *
+ * Published rather than rendered: chrome belongs to the host (§2), so the window says where it is
+ * and the host decides what to draw about it.
+ */
+export type WindowState = {
+    /** The row at the top of the viewport — what "where am I" means to a reader. */
+    index: number;
+    visible: {
+        first: number;
+        last: number;
+    };
+    /** The mounted range, which includes the overscan the reader cannot see. */
+    mounted: {
+        first: number;
+        last: number;
+    };
+    count: number;
+    /**
+     * The same thing in pixels, which is what a map of the list has to draw.
+     *
+     * `window` is the mounted parent's span in content space — where the rows that exist actually are —
+     * and `total` is what the thumb is scaled against. A map drawn from indices instead would be a map
+     * of the model rather than of the layout, and it is the layout that goes wrong.
+     */
+    geometry: {
+        scroll: number;
+        viewport: number;
+        total: number;
+        window: {
+            start: number;
+            extent: number;
+        };
+    };
+};
+export type WindowController = {
+    /**
+     * `behavior: 'smooth'` glides, and only over content that is mounted — a glide across rows that do
+     * not exist is a journey over a blank screen, so a far target is taken instantly (§7).
+     */
+    scrollToIndex: (index: number, align?: 'start' | 'end', behavior?: ScrollBehavior) => void;
+};
+export type WindowProps = ThemedClassName<{
+    model: WindowModel;
+    extents: Extents;
+    /** Which way the list runs. The principles hold either way; only this mapping differs (§9). */
+    axis?: WindowAxis;
+    overscan?: number;
+    /** Empty extent after the last row, so it can be scrolled to the top of the viewport (§7). */
+    reserve?: number;
+    /**
+     * Keep the last row against the end of the viewport as content arrives.
+     *
+     * Consumed by the trivial `Window` binding, which composes `useFollow`; `useWindow` itself knows
+     * nothing about following — the intent, the withdrawal and the glide are the aspect's (SPEC §Aspects).
+     */
+    sticky?: boolean;
+    /** What an edge revealed about the estimates, if it revealed anything. */
+    onEdge?: (drift: EdgeDrift) => void;
+    /** A row whose declared extent was not the extent it rendered at. `exact` means do not correct — not do not check (§8). */
+    onMismatch?: (mismatch: {
+        index: number;
+        id: string;
+        declared: number;
+        actual: number;
+    }) => void;
+    onChange?: (state: WindowState) => void;
+    controllerRef?: Ref<WindowController>;
+    children: (index: number, id: string) => ReactNode;
+}>;
+/**
+ * Everything the shape needs, with no opinion about who owns the scroll element.
+ *
+ * Split out because the DOM below is only the *simplest* binding of it. A host that already has a
+ * scroll container — `MessageList` scrolls inside `ScrollArea`, which owns the overlay thumbs and
+ * the padding tokens — cannot nest a second one, and would otherwise have to reimplement the
+ * placement to keep its own chrome. It hands its element over instead.
+ */
+export type UseWindowOptions = Omit<WindowProps, 'classNames' | 'children'> & {
+    /** The element being scrolled, when the host owns it. `Window` passes its own. */
+    scrollerRef: React.RefObject<HTMLElement | null>;
+};
+export type UseWindowResult = {
+    placement: Placement;
+    layout: Layout;
+    /** Ref for the element holding the mounted rows, which is what gets measured. */
+    windowRef: React.RefObject<HTMLDivElement | null>;
+    /** Extent of the whole document along the axis, reserve included: what the thumb is scaled to. */
+    sizerExtent: number;
+    /** Absolute position of the first mounted row, which the parent is translated by. */
+    offset: number;
+    first: number;
+    last: number;
+};
+export declare const useWindow: ({ scrollerRef, model, extents, axis, overscan, reserve, onEdge, onMismatch, onChange, controllerRef, }: UseWindowOptions) => UseWindowResult;
+/**
+ * The DOM shape, and nothing else.
+ *
+ * Three elements: a **sizer** that holds no rows and exists only to give the thumb something to
+ * measure, a **window** holding the mounted rows in normal flow, and the scroller around them.
+ */
+export declare const Window: ({ classNames, children, controllerRef, ...options }: WindowProps) => React.JSX.Element;
+//# sourceMappingURL=Window.d.ts.map

package/dist/types/src/virtualizer/Window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Window.d.ts","sourceRoot":"","sources":["../../../../src/virtualizer/Window.tsx"],"names":[],"mappings":"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"}

package/dist/types/src/virtualizer/Window.stories.d.ts

@@ -0,0 +1,112 @@
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { type WindowAxis } from './Window';
+/**
+ * The DOM shape, driven by content that cannot lie about its size.
+ *
+ * Between `placement.test.ts` (arithmetic, no DOM) and `baseline/*` (a real feed, real editors) sits
+ * this: plain boxes of declared extent, so anything that moves here is the shape and not the item.
+ * The layer exists because the two things fail differently and a single suite cannot say which.
+ */
+type StoryArgs = {
+    /** Rows the model is seeded with; the append/prepend buttons then drive the model directly. */
+    count?: number;
+    axis?: WindowAxis;
+    exact?: boolean;
+    /** Extent the row actually renders at — the story controls it, so the story knows the truth. */
+    extent?: (index: number) => number;
+    /** Outline every row and label its extent, so what is being measured is visible. */
+    debug?: boolean;
+    /**
+     * Controls a story needs to drive the list, rendered in the toolbar when supplied.
+     *
+     * Buttons rather than a global the play function calls: a story is rendered more than once, so a
+     * `window.__grow` captured in an effect goes stale and the press lands on a previous mount's
+     * state — which presented as `Prepend` and `Grow` passing or failing depending on what else ran.
+     * A button is the same thing the reader has, and there is only ever one of it.
+     */
+    /** Render the append button; 'few' appends 5 rows per press instead of 20 (the sticky story). */
+    append?: boolean | 'few';
+    /** Keep the last row against the bottom of the viewport as content arrives. */
+    sticky?: boolean;
+    prepend?: boolean;
+    grow?: boolean;
+    /**
+     * Reserve a viewport's worth of space after the last row, so it can be read at the top.
+     *
+     * Computed **here**, from what the window publishes, and handed back as a number — which is the
+     * claim §7 makes: with the window placed rather than the rows, this is not a mode the list has.
+     */
+    scrollPastEnd?: boolean;
+    /**
+     * Extent the host *claims*, when that differs from what renders.
+     *
+     * Two callbacks, not one, because a story that reports the same number it renders cannot express a
+     * host being wrong — which is the only thing `Drift` is about.
+     */
+    declared?: (index: number) => number;
+};
+declare const meta: Meta<StoryArgs>;
+export default meta;
+type Story = StoryObj<StoryArgs>;
+/** The harness at rest, for the eye and the controls panel. No play. */
+export declare const Default: Story;
+/**
+ * The window is placed where the arithmetic says, and the edges agree with the model.
+ *
+ * `offset === 0` at the start and `offset + window === sizer` at the end are where estimate meets
+ * ground truth — with `exact` extents they must hold to the pixel, which is what makes this the
+ * control the other stories are read against.
+ */
+export declare const Static: Story;
+/** Rows arriving at the end move nothing that is already on screen, and do not move the window. */
+export declare const Append: Story;
+/**
+ * The hard case: rows inserted *before* the reader.
+ *
+ * Everything at or after the anchor has to stay exactly where it is, in the frame the insert lands —
+ * which is the whole reason placement is anchor-relative rather than summed from index 0.
+ */
+export declare const Prepend: Story;
+/**
+ * A row changing extent moves the rows after it and none before it — and costs us nothing.
+ *
+ * This is §6 in one assertion: the browser reflows the siblings. With rows placed by transform it
+ * was 177 re-placements written by us for one disclosure.
+ */
+export declare const Grow: Story;
+/** A jump lands, and both edge invariants still hold once it has. */
+export declare const Jump: Story;
+/** The same shape on the other axis, where the layout constrains the extent and nothing is measured. */
+export declare const Horizontal: Story;
+/**
+ * A declared extent that is wrong is **reported**, not silently absorbed.
+ *
+ * `exact` is a promise the host makes, and a promise nobody checks is how a 1px separator costs a day
+ * of bisection (§8). The row renders at a size the callback did not claim; the mismatch names it.
+ */
+export declare const Drift: Story;
+/**
+ * The chrome, which is outside the window and reads what it publishes.
+ *
+ * Tested because untested chrome is how a story ended up pinned to half the screen height without
+ * anything failing: the assertions were all about the rows, and nothing asked whether what surrounds
+ * them was right (§12).
+ */
+export declare const Chrome: Story;
+/**
+ * With space reserved, the last row can be brought to the top of the viewport.
+ *
+ * On the old design this was a flag that special-cased the tail wherever it was consulted, and it
+ * could never be stabilised. Here the host computes a number and the list adds it to the sizer;
+ * nothing else in the engine knows it happened (§7).
+ */
+export declare const PastEnd: Story;
+/**
+ * A feed pinned to its tail stays there as content arrives.
+ *
+ * The one thing the old engine spent the most machinery on — a follow, a sticky flag, a re-base and
+ * a scroll listener that had to tell the reader apart from itself. Here it is a standing intent: at
+ * the end, appending keeps you at the end; away from it, appending does not move you.
+ */
+export declare const Sticky: Story;
+//# sourceMappingURL=Window.stories.d.ts.map

package/dist/types/src/virtualizer/Window.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Window.stories.d.ts","sourceRoot":"","sources":["../../../../src/virtualizer/Window.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAWjE,OAAO,EAAU,KAAK,UAAU,EAA2C,MAAM,UAAU,CAAC;AAU5F;;;;;;GAMG;AACH,KAAK,SAAS,GAAG;IACf,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gGAAgG;IAChG,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,iGAAiG;IACjG,MAAM,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IACzB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,CAAC;AAwOF,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,SAAS,CAgBzB,CAAC;eAEa,IAAI;AAEnB,KAAK,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AA8CjC,wEAAwE;AACxE,eAAO,MAAM,OAAO,EAAE,KAErB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAE,KAgBpB,CAAC;AAEF,mGAAmG;AACnG,eAAO,MAAM,MAAM,EAAE,KAepB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,KAqBrB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,IAAI,EAAE,KAuBlB,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,IAAI,EAAE,KAclB,CAAC;AAEF,wGAAwG;AACxG,eAAO,MAAM,UAAU,EAAE,KAaxB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,KAcnB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAE,KA4DpB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAE,KA2BrB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAE,KAwCpB,CAAC"}

package/dist/types/src/virtualizer/index.d.ts

@@ -0,0 +1,3 @@
+export * from './placement';
+export * from './Window';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/virtualizer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/virtualizer/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC"}