@dxos/react-ui-feed 0.11.1

package/dist/types/src/components/MessageList/MessageList.d.ts

@@ -0,0 +1,129 @@
+import React, { type ComponentType, type PropsWithChildren } from 'react';
+import { type ScrollAreaRootProps } from '@dxos/react-ui';
+import { type Message } from '@dxos/types';
+import { type XmlWidgetRegistry } from '@dxos/ui-editor';
+import { type FeedNavigation } from '../../hooks';
+import { type FeedModel, type ItemContent, type MessageRenderer } from '../../model';
+/** Per-message chrome (avatar, timestamp, fork/rewind/reply controls), supplied by the host. */
+export type MessageChromeProps = PropsWithChildren<{
+    message: Message.Message;
+    index: number;
+    selected: boolean;
+    onSelect: (id: string, additive: boolean) => void;
+}>;
+export type MessageRange = {
+    startIndex: number;
+    endIndex: number;
+};
+export type ScrollToOptions = {
+    align?: 'start' | 'center' | 'end';
+    behavior?: 'auto' | 'smooth';
+};
+/**
+ * The list's state and scroll controls, for parts that live outside the viewport — a toolbar's
+ * find-next, a statusbar's range readout.
+ */
+export declare const useMessageList: (consumerName?: string) => {
+    range: MessageRange | undefined;
+    currentIndex: number;
+    navigation: FeedNavigation;
+    mountedRows: number;
+    mountedWidgets: number;
+    jumps: {
+        count: number;
+        worst: number;
+    };
+    shifts: number;
+    breaks: number;
+    resetShifts: () => void;
+    model: FeedModel;
+    count: number;
+    scrollToIndex: (index: number, options?: ScrollToOptions) => void;
+    scrollToBottom: (options?: ScrollToOptions) => void;
+};
+export type MessageListRootProps = PropsWithChildren<{
+    /**
+     * The feed's model (SPEC F-7): messages and identity, the stops policy, the streaming tail, and
+     * iteration (`loadBefore`/`loadAfter`, consumed when the window reaches an edge). `fromMessages`
+     * adapts a plain array; ECHO/queue bindings adapt outside this package.
+     *
+     * What is NOT here, deliberately: search hits (decorations — `DecorationsProvider` + an item's
+     * `useDecorations`), selection (`ItemSelectionProvider` + `useItemSelection`), `streamingId` and
+     * `isAnchor` (model concerns). The list neither knows nor routes cross-cutting per-item data.
+     */
+    model: FeedModel;
+    renderer?: MessageRenderer;
+    registry?: XmlWidgetRegistry;
+    /**
+     * Chrome wrapper; receives the item as `children`. Defaults to a bare frame.
+     * Chrome must be layout-stable: a control that changes a row's height on hover or focus
+     * re-triggers measurement, and a pointer travelling down the list mid-scroll then shifts every
+     * row below it. Toggle such affordances with opacity, or take them out of flow.
+     */
+    Chrome?: ComponentType<MessageChromeProps>;
+    /**
+     * Renders a `custom` item. The engine's own kinds are documents — markdown in CodeMirror, HTML —
+     * and both build their content asynchronously enough to be measured wrong once. A host component
+     * whose height is settled at first paint is the control case: if a feed of those still moves, the
+     * fault is the list; if it does not, the fault is in what the item is building.
+     */
+    Custom?: ComponentType<{
+        content: ItemContent & {
+            kind: 'custom';
+        };
+        message: Message.Message;
+    }>;
+    /**
+     * Outline each item and the blocks inside it, so what the layout is measuring is visible.
+     */
+    debug?: boolean;
+    /**
+     * Estimated row height before measurement. A function is worth supplying whenever the feed's
+     * rows differ widely — a one-line prompt beside a long answer — because a single number is wrong
+     * for both.
+     */
+    estimateSize?: number | ((message: Message.Message, index: number) => number);
+    /**
+     * Pin to the bottom as messages arrive, and as a streaming message grows (chat behaviour).
+     */
+    stickyBottom?: boolean;
+    /**
+     * Reserve empty space below the last row, so that any message — including the last — can be
+     * brought to the top of the viewport. A number in the sizer, not a mode the list has (§7).
+     */
+    scrollPastEnd?: boolean;
+    overscan?: number;
+    onRangeChange?: (range: MessageRange) => void;
+}>;
+declare function MessageListRoot({ children, model, renderer, registry, Chrome, Custom, debug, estimateSize, stickyBottom, scrollPastEnd, overscan, onRangeChange }: MessageListRootProps): React.JSX.Element;
+declare namespace MessageListRoot {
+    var displayName: string;
+}
+type MessageListViewportExtra = Pick<ScrollAreaRootProps, 'autoHide' | 'centered' | 'native' | 'padding' | 'scrollbars' | 'thin'> & {
+    /**
+     * Gutter size for the three-track layout each row is laid out on (`gutter | content | gutter`).
+     *
+     * The tracks live inside the row rather than on the container, because the rows are laid out by
+     * the browser inside one placed parent and cannot be items of an outer grid. Chrome that wants the
+     * gutters — a fork control, an avatar, a resolve toggle — opts in with `Column.Row`; everything
+     * else sits in the centre track.
+     */
+    gutter?: 'sm' | 'md' | 'lg';
+};
+type MessageListItemExtra = {
+    message: Message.Message;
+};
+export declare const MessageList: {
+    Root: {
+        ({ children, model, renderer, registry, Chrome, Custom, debug, estimateSize, stickyBottom, scrollPastEnd, overscan, onRangeChange, }: MessageListRootProps): React.JSX.Element;
+        displayName: string;
+    };
+    Viewport: React.ForwardRefExoticComponent<Omit<MessageListViewportExtra, "className"> & {
+        classNames?: import("@dxos/ui-types").ClassNameValue;
+    } & Pick<React.HTMLAttributes<Element>, "children" | "role" | "style"> & React.RefAttributes<HTMLDivElement>>;
+    Item: React.ForwardRefExoticComponent<Omit<MessageListItemExtra, "className"> & {
+        classNames?: import("@dxos/ui-types").ClassNameValue;
+    } & Pick<React.HTMLAttributes<Element>, "children" | "role" | "style"> & React.RefAttributes<HTMLDivElement>>;
+};
+export type { MessageListItemExtra as MessageListItemProps, MessageListViewportExtra as MessageListViewportProps };
+//# sourceMappingURL=MessageList.d.ts.map

package/dist/types/src/components/MessageList/MessageList.d.ts.map

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

package/dist/types/src/components/MessageList/MessageList.stories.d.ts

@@ -0,0 +1,47 @@
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { type FeedStoryProps } from '../../testing';
+declare const meta: Meta<FeedStoryProps>;
+export default meta;
+type Story = StoryObj<FeedStoryProps>;
+/** Passive: the assistant-shaped feed under the shared harness. */
+export declare const Default: Story;
+export declare const Small: Story;
+export declare const Medium: Story;
+/**
+ * Scroll-quality case: the deciding criterion is smoothness here, not at 200.
+ *
+ * The statusbar's right-hand readout is `fps · worst frame · hitches`, sampled from animation
+ * frames and reset by clicking it. It has to be read at a real keyboard — an agent's browser
+ * throttles `requestAnimationFrame`, so any number collected there describes the harness.
+ *
+ * Test:
+ * 1. Click the frame readout to reset it, then fling-scroll the list from top to bottom twice.
+ * 2. Read `fps` while the scroll is running: it should hold near the display's rate.
+ * 3. Read `worst` and `hitches` after it settles — one 200ms stall reads as smooth in an average
+ *    and as broken to a reader, which is why they are reported separately.
+ * 4. Watch the scrollbar thumb during the fling: it should not jump backwards as rows measure.
+ */
+export declare const Large: Story;
+/**
+ * A bad height estimate is what scrollbar drift looks like; compare against `Large`.
+ *
+ * Test:
+ * 1. Reset the frame readout and fling-scroll to the middle of the list.
+ * 2. Compare `worst` and `hitches` against `Large` — the cost of measurement correction is the
+ *    difference between the two stories, since nothing else changes.
+ * 3. Hold at one position for a second: the rows must not creep once measurement catches up.
+ */
+export declare const BadEstimate: Story;
+/**
+ * A model answering into the tail, from nothing, until stopped. The answer arrives in word chunks
+ * and re-parses as markdown (heading, list, code fence) while the row it lives in grows.
+ *
+ * Test:
+ * 1. Reset the frame readout and let three or four turns arrive.
+ * 2. Read `fps` while the tail grows — the follow runs on animation frames, so it competes with
+ *    the item re-parsing its markdown, and this is where they collide.
+ * 3. Scroll away mid-answer: the follow must stop and stay stopped.
+ * 4. Scroll back to the tail: it must resume following without a jump.
+ */
+export declare const Streaming: Story;
+//# sourceMappingURL=MessageList.stories.d.ts.map

package/dist/types/src/components/MessageList/MessageList.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageList.stories.d.ts","sourceRoot":"","sources":["../../../../../src/components/MessageList/MessageList.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAIjE,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/D,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,cAAc,CAa9B,CAAC;eAEa,IAAI;AAEnB,KAAK,KAAK,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;AAStC,mEAAmE;AACnE,eAAO,MAAM,OAAO,EAAE,KAErB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAKnB,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,KAKpB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,EAAE,KAKnB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE,KAMzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,EAAE,KAMvB,CAAC"}

package/dist/types/src/components/MessageList/index.d.ts

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

package/dist/types/src/components/MessageList/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/MessageList/index.ts"],"names":[],"mappings":"AAIA,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

package/dist/types/src/components/MessageList/position-log.d.ts

@@ -0,0 +1,73 @@
+export type PositionStats = {
+    /** Rows whose offset changed after they were laid out — every one of these is a visible flicker. */
+    shifts: number;
+    /** Windows where offsets did not increase with index; a row was placed over its neighbour. */
+    breaks: number;
+    /** The most recent shift, for reading in the console while scrolling. */
+    last?: PositionShift;
+};
+export type PositionShift = {
+    index: number;
+    from: number;
+    to: number;
+    delta: number;
+};
+/** `key` is the virtualizer's item key — the message id, via `getItemKey`. */
+export type PositionKey = number | string | bigint;
+export type PositionEntry = {
+    key: PositionKey;
+    index: number;
+    start: number;
+};
+/** Movement of the viewport itself between samples, which every row is expected to follow. */
+export type PositionFrame = {
+    scrollOffset: number;
+};
+/**
+ * Records where each row was placed, and reports when a row moves.
+ *
+ * A virtualized list is only still if a row's offset, once laid out, does not change: rows above the
+ * reader are measured as they mount, and any correction there pushes everything below it. Scrolling
+ * **up** is where this shows, because that is the direction in which unmeasured rows enter — going
+ * down, the rows above have already been measured.
+ *
+ * Positions are recorded **relative to the viewport** (`start - scrollOffset`), not as absolute
+ * document offsets, because those two answer different questions. Measuring a row for the first time
+ * re-lays every row below it, and the virtualizer compensates by moving `scrollTop` the same
+ * distance — the offsets all change and the reader sees nothing. What a reader sees is a row landing
+ * somewhere else on screen, which is what this counts.
+ *
+ * Two invariants:
+ *
+ * 1. a row keyed by message id holds its place on screen for as long as it stays mounted;
+ * 2. positions within the mounted window increase strictly with index.
+ *
+ * The count is what a reader means by "flicker". Deliberately kept as a count rather than a log:
+ * a scroll produces thousands of samples, and the number is the signal.
+ */
+/**
+ * Watches for jumps in what was actually painted, once per animation frame.
+ *
+ * The counting above is done per React render, which cannot separate a row moving from the sampling
+ * happening at a different moment than the layout. This reads the scroll and every row's box in the
+ * **same** frame and compares each row's travel against the scroll's: a row that keeps its place in
+ * the document travels exactly as far as the scroll did, so anything else is the reader seeing a
+ * jump. It is the in-page form of measuring a screen recording frame by frame, and it is what a
+ * developer should have running while working on the list.
+ */
+export declare const useJumpDetector: (viewport: HTMLElement | null, enabled?: boolean) => {
+    count: number;
+    worst: number;
+};
+export declare const usePositionLog: () => {
+    /** Rows whose offset changed after they were laid out — every one of these is a visible flicker. */
+    shifts: number;
+    /** Windows where offsets did not increase with index; a row was placed over its neighbour. */
+    breaks: number;
+    /** The most recent shift, for reading in the console while scrolling. */
+    last?: PositionShift;
+    trace: import("react").RefObject<PositionShift[]>;
+    record: (entries: readonly PositionEntry[], { scrollOffset }: PositionFrame) => void;
+    reset: () => void;
+};
+//# sourceMappingURL=position-log.d.ts.map

package/dist/types/src/components/MessageList/position-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position-log.d.ts","sourceRoot":"","sources":["../../../../../src/components/MessageList/position-log.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,aAAa,GAAG;IAC1B,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAKvF,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD,MAAM,MAAM,aAAa,GAAG;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,8FAA8F;AAC9F,MAAM,MAAM,aAAa,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,aAAc,WAAW,GAAG,IAAI;;;CA8C3D,CAAC;AAEF,eAAO,MAAM,cAAc;IAvGzB,oGAAoG;YAC5F,MAAM;IACd,8FAA8F;YACtF,MAAM;IACd,yEAAyE;WAClE,aAAa;;sBA+GiB,SAAS,aAAa,EAAE,oBAAoB,aAAa;;CAwC/F,CAAC"}

package/dist/types/src/components/Minimap/Minimap.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { type WindowState } from '../../virtualizer';
+/**
+ * The whole list at a glance: what exists, what is mounted, and what the reader can see.
+ *
+ * Drawn in **content space**, not in indices. The three quantities a virtualized list can get wrong
+ * are where the mounted rows are, how big the reader's slice of them is, and whether the total the
+ * thumb is scaled against is honest — and none of those are visible from a row count. Here they are
+ * three bars on one track, so a mounted range that has drifted away from the viewport, or a total
+ * that jumps while nothing scrolls, is a picture rather than a number to be noticed.
+ *
+ * Debug only. It reads the state the window publishes and draws it (§2); it does not participate.
+ */
+export type MinimapProps = ThemedClassName<{
+    state?: WindowState;
+    /** Width of the rail, in px. @default 32 (2rem) */
+    width?: number;
+    /**
+     * Jump to where the reader pointed, as a fraction of the whole list.
+     *
+     * A fraction and not an index: the map is drawn in content space, so what a click names is a
+     * position, and turning that into a row is the host's business — it has the count.
+     */
+    onSelect?: (fraction: number) => void;
+}>;
+export declare const Minimap: ({ classNames, state, width, onSelect }: MinimapProps) => React.JSX.Element;
+//# sourceMappingURL=Minimap.d.ts.map

package/dist/types/src/components/Minimap/Minimap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Minimap.d.ts","sourceRoot":"","sources":["../../../../../src/components/Minimap/Minimap.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGtD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKrD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,CAAC;IACzC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC,CAAC,CAAC;AAEH,eAAO,MAAM,OAAO,2CAA4D,YAAY,sBA6C3F,CAAC"}

package/dist/types/src/components/Minimap/Minimap.stories.d.ts

@@ -0,0 +1,21 @@
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+/**
+ * The minimap against a live window, because its whole job is to draw what the window publishes:
+ * the track is the document, the faint band the mounted rows, the solid band the viewport. Scroll
+ * the list and the bands move; click the rail and the list jumps to that fraction.
+ */
+type StoryArgs = {
+    count?: number;
+    width?: number;
+};
+declare const meta: Meta<StoryArgs>;
+export default meta;
+type Story = StoryObj<StoryArgs>;
+/** Scroll the list, watch the bands; click the rail, the list jumps. No play. */
+export declare const Default: Story;
+/**
+ * The viewport band stays inside the mounted band — a viewport showing rows that are not mounted
+ * would mean the reader is looking at nothing — and a click moves the list to that fraction.
+ */
+export declare const Tracks: Story;
+//# sourceMappingURL=Minimap.stories.d.ts.map

package/dist/types/src/components/Minimap/Minimap.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Minimap.stories.d.ts","sourceRoot":"","sources":["../../../../../src/components/Minimap/Minimap.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAUjE;;;;GAIG;AACH,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA2CF,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,SAAS,CAMzB,CAAC;eAEa,IAAI;AAEnB,KAAK,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAEjC,iFAAiF;AACjF,eAAO,MAAM,OAAO,EAAE,KAAU,CAAC;AAUjC;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,KAoCpB,CAAC"}

package/dist/types/src/components/Minimap/index.d.ts

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

package/dist/types/src/components/Minimap/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/Minimap/index.ts"],"names":[],"mappings":"AAIA,cAAc,WAAW,CAAC"}

package/dist/types/src/components/Outline/Outline.d.ts

@@ -0,0 +1,46 @@
+import React from 'react';
+import { type ThemedClassName } from '@dxos/react-ui';
+/**
+ * A single anchor marker within the mapped document.
+ * `range` is expressed in the document's own position space (e.g. CodeMirror offsets).
+ */
+export type OutlineMarker = {
+    id: string;
+    title: string;
+    description?: string;
+    range: {
+        from: number;
+        to: number;
+    };
+};
+export type OutlineProps = ThemedClassName<{
+    markers: OutlineMarker[];
+    /** Currently-visible document range; markers intersecting it render brighter ("active"). */
+    visibleRange?: {
+        from: number;
+        to: number;
+    };
+    /**
+     * Height of one tick, in px.
+     *
+     * Fixed rather than shared out over the rail's height: ticks that stretch to fill make a short
+     * document's markers enormous and a long one's hairline, so the same rail reads as a different
+     * control depending on what is in it. A fixed pitch means the rail thins to what fits and every
+     * tick looks the same. @default 8
+     */
+    tickSize?: number;
+    /** Width of the rail, in px, which is also how far a tick extends at the peak of the wave. @default 32 (2rem) */
+    width?: number;
+    onSelect?: (marker: OutlineMarker, index: number) => void;
+    /**
+     * Step one item, in whatever the host counts items in.
+     *
+     * Not one tick: the rail thins its markers to what fits, so the next tick can be ten items away,
+     * and a reader pressing an arrow means "the next one" rather than "the next thing I can see". The
+     * host steps it with the same mechanism its toolbar uses, which is why this is a callback rather
+     * than something the rail decides.
+     */
+    onNavigate?: (delta: number) => void;
+}>;
+export declare const Outline: ({ classNames, markers, visibleRange, tickSize, width, onSelect, onNavigate, }: OutlineProps) => React.JSX.Element;
+//# sourceMappingURL=Outline.d.ts.map

package/dist/types/src/components/Outline/Outline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Outline.d.ts","sourceRoot":"","sources":["../../../../../src/components/Outline/Outline.tsx"],"names":[],"mappings":"AAIA,OAAO,KAQN,MAAM,OAAO,CAAC;AAEf,OAAO,EAAW,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAgB/D;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,eAAe,CAAC;IACzC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,4FAA4F;IAC5F,YAAY,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iHAAiH;IACjH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,CAAC,CAAC;AAkCH,eAAO,MAAM,OAAO,kFAQjB,YAAY,sBAkRd,CAAC"}

package/dist/types/src/components/Outline/Outline.stories.d.ts

@@ -0,0 +1,37 @@
+import { type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+import { type OutlineProps } from './Outline';
+declare const meta: {
+    title: string;
+    component: ({ classNames, markers, visibleRange, tickSize, width, onSelect, onNavigate, }: OutlineProps) => React.JSX.Element;
+    render: ({ markers, ...props }: OutlineProps) => React.JSX.Element;
+    decorators: import("@storybook/react").Decorator[];
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Default: Story;
+export declare const Empty: Story;
+/**
+ * A click does not leave a position asserted behind it.
+ *
+ * Clicking a tick focuses it, and the card was gated on focus — so the reader clicked, moved away,
+ * and a keyboard position they never asked for kept it up. What may assert a position is the pointer
+ * being over a tick, or the keyboard having *navigated* to one; focus is neither, and a click
+ * confers focus as a side effect.
+ *
+ * What this does **not** cover is the pointer actually leaving, because React synthesises enter and
+ * leave from over/out pairs and three attempts to drive that from dispatched events did not reach
+ * the handler — the state was still set afterwards whether or not the component was right. Asserting
+ * it here would be asserting the probe. It needs a real pointer; see `chat-ui/TASKS.md`.
+ */
+export declare const Dismissal: Story;
+/**
+ * The arrows take the card over from the pointer, and pointing takes it back.
+ *
+ * A reader clicks a tick and then presses an arrow without moving the mouse — which is the whole
+ * point of clicking one. The pointer is still resting on the tick they clicked, so a rule of
+ * "the pointer always wins" pins the card to a place they have already left, and the feed scrolls
+ * under a card describing somewhere else. Reported from a real session as "card does not move".
+ */
+export declare const KeyboardTakeover: Story;
+//# sourceMappingURL=Outline.stories.d.ts.map

package/dist/types/src/components/Outline/Outline.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Outline.stories.d.ts","sourceRoot":"","sources":["../../../../../src/components/Outline/Outline.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAA4B,MAAM,OAAO,CAAC;AAKjD,OAAO,EAA+B,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAoE3E,QAAA,MAAM,IAAI;;;oCAhDmC,YAAY;;CAqDzB,CAAC;eAElB,IAAI;AAEnB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KAIrB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAInB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,EAAE,KAuBvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAgD9B,CAAC"}

package/dist/types/src/components/Outline/index.d.ts

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

package/dist/types/src/components/Outline/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/Outline/index.ts"],"names":[],"mappings":"AAIA,cAAc,WAAW,CAAC"}

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

@@ -0,0 +1,5 @@
+export * from './Block';
+export * from './MessageList';
+export * from './Minimap';
+export * from './Outline';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/index.ts"],"names":[],"mappings":"AAIA,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC"}

package/dist/types/src/debug/Debug.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { type ThemedClassName } from '@dxos/react-ui';
+export type DebugProps = ThemedClassName<{
+    /** Readouts side by side. @default 1 */
+    columns?: number;
+    title?: string;
+}>;
+/**
+ * The table over whatever probes are registered (SPEC follow-up: generic debug mechanism, built
+ * once and reused by future react-ui components rather than re-invented per surface).
+ *
+ * Values are sampled once per animation frame while mounted — the model is not reactive over
+ * values by design, so the table is the only thing paying for sixty reads a second. Grouped by the
+ * probe's `group`, in fixed tracks so a changing digit moves nothing beside it.
+ */
+export declare const Debug: ({ columns, title, classNames }: DebugProps) => React.JSX.Element | null;
+//# sourceMappingURL=Debug.d.ts.map

package/dist/types/src/debug/Debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Debug.d.ts","sourceRoot":"","sources":["../../../../src/debug/Debug.tsx"],"names":[],"mappings":"AAIA,OAAO,KAA2D,MAAM,OAAO,CAAC;AAEhF,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAOtD,MAAM,MAAM,UAAU,GAAG,eAAe,CAAC;IACvC,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,mCAAwC,UAAU,6BA8DnE,CAAC"}

package/dist/types/src/debug/Stats.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+import { type ThemedClassName } from '@dxos/react-ui';
+/** Readouts are mostly counts, but a range (`463–499`) is one reading and reads as one cell. */
+export type StatValue = number | string;
+export type Stat = {
+    id: string;
+    label?: string;
+    unit?: string;
+    /** Emphasis for a value that means something is wrong; called with the current value. */
+    classNames?: (value: StatValue) => string | false | undefined;
+};
+export type StatsProps = ThemedClassName<{
+    'stats': Stat[];
+    'values': Record<string, StatValue>;
+    /** Readouts side by side, for a panel that is wider than it is tall. @default 1 */
+    'columns'?: number;
+    'title'?: string;
+    'data-testid'?: string;
+}>;
+/**
+ * A block of readouts, in fixed tracks.
+ *
+ * Every number here changes while the feed scrolls, so the value and unit columns are given widths
+ * rather than sized to their contents: a column that fits itself to `4` and then to `1054` moves
+ * every digit beside it, and an instrument that moves cannot be read at a glance.
+ */
+export declare const Stats: ({ stats, values, columns, classNames, title, ...props }: StatsProps) => React.JSX.Element;
+/** Anything above zero is a defect, not a reading. */
+export declare const warnAbove: (value: StatValue) => "text-warning-text" | false;
+//# sourceMappingURL=Stats.d.ts.map

package/dist/types/src/debug/Stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stats.d.ts","sourceRoot":"","sources":["../../../../src/debug/Stats.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAmB,MAAM,OAAO,CAAC;AAExC,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGtD,gGAAgG;AAChG,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,MAAM,MAAM,IAAI,GAAG;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;CAC/D,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,eAAe,CAAC;IACvC,OAAO,EAAE,IAAI,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACpC,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,4DAAiE,UAAU,sBAiB5F,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,SAAS,UAAW,SAAS,gCAA6C,CAAC"}

package/dist/types/src/debug/debug-model.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One live readout: a name and how to read it. Reading must be cheap — the table reads every probe
+ * once per animation frame while it is shown.
+ */
+export type DebugProbe = {
+    id: string;
+    /** Probes render grouped; a group is a component's or an aspect's set. */
+    group?: string;
+    label?: string;
+    unit?: string;
+    read: () => number | string;
+    /** Emphasis when the value means something is wrong. */
+    alarm?: (value: number | string) => boolean;
+};
+/**
+ * A registry of live readouts, so a debug table can render *whatever is currently instrumented*
+ * rather than a hard-coded panel per surface (SPEC follow-up: the generic debug mechanism).
+ *
+ * Deliberately not reactive state: probes are read by whoever renders them, per frame, and a value
+ * that changed sixty times a second is not worth sixty renders of anything but the table itself.
+ * Registration is the only event.
+ */
+export declare class DebugModel {
+    #private;
+    register(probe: DebugProbe): () => void;
+    probes(): DebugProbe[];
+    /** Every probe's current value, in one pass. */
+    read(): Record<string, number | string>;
+    /** Fires on registration changes only, never on values. */
+    subscribe(listener: () => void): () => void;
+}
+//# sourceMappingURL=debug-model.d.ts.map

package/dist/types/src/debug/debug-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-model.d.ts","sourceRoot":"","sources":["../../../../src/debug/debug-model.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,MAAM,GAAG,MAAM,CAAC;IAC5B,wDAAwD;IACxD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC;CAC7C,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,UAAU;;IAIrB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,IAAI,CAOtC;IAED,MAAM,IAAI,UAAU,EAAE,CAErB;IAED,gDAAgD;IAChD,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAOtC;IAED,2DAA2D;IAC3D,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1C;CAOF"}

package/dist/types/src/debug/debug-model.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=debug-model.test.d.ts.map

package/dist/types/src/debug/debug-model.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-model.test.d.ts","sourceRoot":"","sources":["../../../../src/debug/debug-model.test.ts"],"names":[],"mappings":""}

package/dist/types/src/debug/frame-meter.d.ts

@@ -0,0 +1,48 @@
+export type FrameStats = {
+    /** Frames per second over the last reporting window — what the eye checks while a gesture runs. */
+    fps: number;
+    /** Rate at the median frame: the pass's typical smoothness. */
+    p50: number;
+    /** Rate at the 95th-percentile (slowest) frame: what the pass felt like at its worst fifth. */
+    p95: number;
+    /** Longest frame (ms) since the pass began. */
+    worst: number;
+    /** Frames over {@link HITCH_MS} since the pass began. */
+    hitches: number;
+    /** Frames sampled, so a reading of zero hitches can be weighed against how long it was measured. */
+    frames: number;
+    /** Length of the pass so far (ms). */
+    duration: number;
+};
+/**
+ * Rate (fps) at the frame standing at `quantile` of a pass, counting from the fast end — so 0.95 is
+ * the slow tail, the fifth of the pass a reader would call the stutter.
+ *
+ * `buckets` counts frames by their duration in whole milliseconds. Exported for its test: this is
+ * the number the engine's verdict rests on, and an off-by-one in the walk would flatter it.
+ */
+export declare const rateAtQuantile: (buckets: Uint32Array, frames: number, quantile: number) => number;
+export type FrameMeterOptions = {
+    /** Names the pass in the recorded line — the story's arguments, since they are what varies. */
+    label?: string;
+};
+/** Live statistics plus the control that ends one pass and begins the next. */
+export type FrameMeter = FrameStats & {
+    label?: string;
+    record: () => string;
+};
+/**
+ * Samples animation-frame intervals and records a pass on demand.
+ *
+ * This exists because scroll smoothness is the deciding criterion for the feed engine and no
+ * automated harness can report it: an agent's browser throttles `requestAnimationFrame`, so any
+ * number collected there describes the harness. Averages hide the defect — a scroll that holds
+ * 60fps and stalls once for 200ms reads as smooth in a mean and as broken to a reader — so the
+ * percentiles, the worst frame and the hitch count are reported together, and each hitch is traced
+ * to the console as it happens so a bad number can be turned into a cause.
+ *
+ * Durations are bucketed by the millisecond rather than kept, so a pass costs the same however long
+ * it runs; percentiles come out of the histogram.
+ */
+export declare const useFrameMeter: ({ label }?: FrameMeterOptions) => FrameMeter;
+//# sourceMappingURL=frame-meter.d.ts.map

package/dist/types/src/debug/frame-meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-meter.d.ts","sourceRoot":"","sources":["../../../../src/debug/frame-meter.ts"],"names":[],"mappings":"AAuBA,MAAM,MAAM,UAAU,GAAG;IACvB,mGAAmG;IACnG,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,+FAA+F;IAC/F,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,YAAa,WAAW,UAAU,MAAM,YAAY,MAAM,KAAG,MAevF,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,MAAM,CAAA;CAAE,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,eAAe,iBAAiB,KAAQ,UAoGjE,CAAC"}

package/dist/types/src/debug/frame-meter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=frame-meter.test.d.ts.map

package/dist/types/src/debug/frame-meter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-meter.test.d.ts","sourceRoot":"","sources":["../../../../src/debug/frame-meter.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,6 @@
+export * from './Debug';
+export * from './debug-model';
+export * from './frame-meter';
+export * from './Stats';
+export * from './use-debug';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/debug/index.ts"],"names":[],"mappings":"AAIA,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC"}