@dxos/react-ui-feed 0.11.1

package/src/components/MessageList/position-log.ts

@@ -0,0 +1,167 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** Movement below this is sub-pixel rounding, not a row changing place. */
+const EPSILON = 1;
+
+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 };
+
+/** Recent shifts kept for inspection — enough to see whether one row type moves or all of them. */
+const TRACE_LIMIT = 40;
+
+/** `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 };
+
+const EMPTY: PositionStats = { shifts: 0, breaks: 0 };
+
+/**
+ * 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 const useJumpDetector = (viewport: HTMLElement | null, enabled = true) => {
+  const [jumps, setJumps] = useState({ count: 0, worst: 0 });
+
+  useEffect(() => {
+    if (!viewport || !enabled) {
+      return;
+    }
+
+    let handle = 0;
+    let previous = new Map<string, number>();
+    let previousScroll = viewport.scrollTop;
+    let count = 0;
+    let worst = 0;
+
+    const tick = () => {
+      const scroll = viewport.scrollTop;
+      const travelled = previousScroll - scroll;
+      const current = new Map<string, number>();
+      for (const row of viewport.querySelectorAll<HTMLElement>('[data-index]')) {
+        const top = row.getBoundingClientRect().top;
+        const index = row.dataset.index!;
+        current.set(index, top);
+        const before = previous.get(index);
+        if (before !== undefined) {
+          const residual = Math.abs(top - (before + travelled));
+          if (residual > EPSILON) {
+            count++;
+            worst = Math.max(worst, Math.round(residual));
+          }
+        }
+      }
+
+      previous = current;
+      previousScroll = scroll;
+      handle = requestAnimationFrame(tick);
+    };
+
+    handle = requestAnimationFrame(tick);
+    const timer = setInterval(() => setJumps({ count, worst }), 250);
+    return () => {
+      cancelAnimationFrame(handle);
+      clearInterval(timer);
+    };
+  }, [viewport, enabled]);
+
+  return jumps;
+};
+
+export const usePositionLog = () => {
+  const positions = useRef(new Map<PositionKey, number>());
+  const trace = useRef<PositionShift[]>([]);
+  const [stats, setStats] = useState<PositionStats>(EMPTY);
+  const pending = useRef<PositionStats>(EMPTY);
+
+  const reset = useCallback(() => {
+    positions.current.clear();
+    trace.current = [];
+    pending.current = EMPTY;
+    setStats(EMPTY);
+  }, []);
+
+  const record = useCallback((entries: readonly PositionEntry[], { scrollOffset }: PositionFrame) => {
+    let { shifts, breaks, last } = pending.current;
+
+    let previousStart = -Infinity;
+    for (const { key, index, start: absolute } of entries) {
+      const start = absolute - scrollOffset;
+      const recorded = positions.current.get(key);
+      if (recorded !== undefined && Math.abs(recorded - start) > EPSILON) {
+        shifts++;
+        last = { index, from: Math.round(recorded), to: Math.round(start), delta: Math.round(start - recorded) };
+        trace.current.push(last);
+        if (trace.current.length > TRACE_LIMIT) {
+          trace.current.shift();
+        }
+      }
+
+      positions.current.set(key, start);
+      if (start < previousStart) {
+        breaks++;
+      }
+      previousStart = start;
+    }
+
+    // Rows that are no longer mounted are forgotten: their next measurement is a fresh layout, and
+    // holding the old offset would report every remount as a shift.
+    const mounted = new Set(entries.map(({ key }) => key));
+    for (const key of positions.current.keys()) {
+      if (!mounted.has(key)) {
+        positions.current.delete(key);
+      }
+    }
+
+    const next = { shifts, breaks, last };
+    pending.current = next;
+    setStats((previous) =>
+      previous.shifts === next.shifts && previous.breaks === next.breaks ? previous : { ...next },
+    );
+  }, []);
+
+  return { ...stats, trace, record, reset };
+};

package/src/components/Minimap/Minimap.stories.tsx

@@ -0,0 +1,129 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo, useRef, useState } from 'react';
+import { expect } from 'storybook/test';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { ListModel } from '../../model';
+import { Window, type WindowController, type WindowState } from '../../virtualizer';
+import { Minimap } from './Minimap';
+
+/**
+ * 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;
+};
+
+const EXTENT = (index: number) => 40 + (index % 8) * 30;
+
+const DefaultStory = ({ count = 500, width }: StoryArgs) => {
+  const model = useMemo(
+    () =>
+      new ListModel({
+        items: Array.from({ length: count }, (_, index) => ({ id: `row-${index}` })),
+        getId: (item) => item.id,
+      }),
+    [count],
+  );
+  const [state, setState] = useState<WindowState>();
+  const controller = useRef<WindowController>(null);
+
+  return (
+    <div className='flex h-full gap-2 p-2'>
+      <Window
+        classNames='grow min-h-0'
+        model={model}
+        extents={{ of: EXTENT, exact: true }}
+        onChange={setState}
+        controllerRef={controller}
+      >
+        {(index) => (
+          <div
+            className='flex items-center justify-center border border-separator text-xs tabular-nums'
+            style={{ height: EXTENT(index) }}
+          >
+            {index}
+          </div>
+        )}
+      </Window>
+      <Minimap
+        state={state}
+        width={width}
+        onSelect={(fraction) => controller.current?.scrollToIndex(Math.round(fraction * (model.count - 1)))}
+      />
+    </div>
+  );
+};
+
+const meta: Meta<StoryArgs> = {
+  title: 'ui/react-ui-feed/components/Minimap',
+  render: DefaultStory,
+  decorators: [withLayout({ layout: 'column', classNames: 'w-[40rem]' }), withTheme()],
+  parameters: { layout: 'fullscreen' },
+  args: { count: 500 },
+};
+
+export default meta;
+
+type Story = StoryObj<StoryArgs>;
+
+/** Scroll the list, watch the bands; click the rail, the list jumps. No play. */
+export const Default: Story = {};
+
+const nextFrame = () => new Promise<number>((resolve) => requestAnimationFrame(resolve));
+
+const settle = async (frames = 20) => {
+  for (let frame = 0; frame < frames; frame++) {
+    await nextFrame();
+  }
+};
+
+/**
+ * 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 const Tracks: Story = {
+  play: async ({ canvasElement }) => {
+    await settle();
+    const scroller = canvasElement.querySelector<HTMLElement>('[data-testid="window.scroller"]')!;
+    const rail = canvasElement.querySelector<HTMLElement>('[data-testid="minimap"]')!;
+    const band = (testid: string) => {
+      const element = rail.querySelector<HTMLElement>(`[data-testid="${testid}"]`)!;
+      const box = element.getBoundingClientRect();
+      return { top: box.top, bottom: box.bottom };
+    };
+
+    const inside = () => {
+      const mounted = band('minimap.mounted');
+      const viewport = band('minimap.viewport');
+      return viewport.top >= mounted.top - 1 && viewport.bottom <= mounted.bottom + 1;
+    };
+
+    // At rest, mid-scroll, and settled again.
+    const readings = [inside()];
+    scroller.scrollTop = 20_000;
+    await settle(5);
+    readings.push(inside());
+    await settle(20);
+    readings.push(inside());
+
+    // A click near the middle of the rail lands the list near the middle of the document.
+    const box = rail.getBoundingClientRect();
+    rail.dispatchEvent(
+      new MouseEvent('click', { bubbles: true, clientX: box.left + 4, clientY: box.top + box.height / 2 }),
+    );
+    await settle();
+    const total = scroller.scrollHeight - scroller.clientHeight;
+    const nearMiddle = Math.abs(scroller.scrollTop / total - 0.5) < 0.1;
+
+    await expect({ readings, nearMiddle }).toEqual({ readings: [true, true, true], nearMiddle: true });
+  },
+};

package/src/components/Minimap/Minimap.tsx

@@ -0,0 +1,84 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { type WindowState } from '../../virtualizer';
+
+/** 2rem, matching the outline rail it usually sits opposite. */
+const DEFAULT_WIDTH = 32;
+
+/**
+ * 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 const Minimap = ({ classNames, state, width = DEFAULT_WIDTH, onSelect }: MinimapProps) => {
+  const total = state?.geometry.total ?? 0;
+  const scale = (value: number) => (total > 0 ? `${Math.max(0, Math.min(100, (value / total) * 100))}%` : '0%');
+
+  return (
+    <div
+      className={mx('relative h-full bg-input-surface overflow-hidden', onSelect && 'cursor-pointer', classNames)}
+      style={{ width }}
+      title={total ? `${Math.round(total)}px over ${state?.count} rows` : 'empty'}
+      data-testid='minimap'
+      onClick={
+        onSelect &&
+        ((event) => {
+          const box = event.currentTarget.getBoundingClientRect();
+          onSelect(Math.max(0, Math.min(1, (event.clientY - box.top) / box.height)));
+        })
+      }
+    >
+      {state && total > 0 && (
+        <>
+          {/* Mounted rows: where content actually exists. Should always contain the viewport — if it
+              does not, the reader is looking at rows nobody has rendered. */}
+          <div
+            className='absolute inset-x-0 bg-accent-fill/30'
+            style={{ top: scale(state.geometry.window.start), height: scale(state.geometry.window.extent) }}
+            data-testid='minimap.mounted'
+          />
+          {/* Tenths, so a glance says roughly where in the list a bar sits without reading a number. */}
+          {Array.from({ length: 9 }, (_, step) => (
+            <div
+              key={step}
+              className='absolute inset-x-0 border-t border-separator/40'
+              style={{ top: `${((step + 1) / 10) * 100}%` }}
+            />
+          ))}
+          {/* The viewport, which is the reader. */}
+          <div
+            className='absolute inset-x-0 border-y border-accent-bg bg-accent-fill/70'
+            style={{ top: scale(state.geometry.scroll), height: scale(state.geometry.viewport) }}
+            data-testid='minimap.viewport'
+          />
+        </>
+      )}
+    </div>
+  );
+};

package/src/components/Minimap/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Minimap';

package/src/components/Outline/Outline.stories.tsx

@@ -0,0 +1,196 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo, useState } from 'react';
+import { expect } from 'storybook/test';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { Outline, type OutlineMarker, type OutlineProps } from './Outline';
+
+const DOC_LENGTH = 2000;
+const WINDOW = 320;
+
+// Synthetic prompt/response markers spread across a document of length `DOC_LENGTH`.
+const createMarkers = (count: number): OutlineMarker[] =>
+  Array.from({ length: count }, (_, index) => {
+    const from = Math.round((index / count) * DOC_LENGTH);
+    const to = Math.round(((index + 1) / count) * DOC_LENGTH) - 8;
+    return {
+      id: `marker-${index}`,
+      title: `Prompt ${index + 1}`,
+      description: `Response snippet for prompt ${index + 1}. This is the first few lines of the assistant reply, shown in the popover on hover.`,
+      range: { from, to },
+    };
+  });
+
+const defaultMarkers = createMarkers(14);
+
+const DefaultStory = ({ markers, ...props }: OutlineProps) => {
+  const [start, setStart] = useState(0);
+  const [selected, setSelected] = useState<OutlineMarker | null>(null);
+  const visibleRange = useMemo(() => ({ from: start, to: start + WINDOW }), [start]);
+
+  return (
+    <div className='relative grid grid-cols-[3rem_1fr] gap-6 p-4'>
+      <div>
+        <div className='absolute left-4 top-4'>
+          <Outline
+            {...props}
+            markers={markers}
+            visibleRange={visibleRange}
+            // The wiring a host actually uses: arrows step the *document*, not the rail's ticks,
+            // because the rail thins its markers and the two are not one-to-one.
+            onNavigate={(delta) =>
+              setStart((current) => Math.max(0, Math.min(current + delta * (DOC_LENGTH / 14), DOC_LENGTH - WINDOW)))
+            }
+            onSelect={(marker) => {
+              setSelected(marker);
+              // Clicking a tick moves the visible range to that marker.
+              setStart(Math.max(0, Math.min(marker.range.from, DOC_LENGTH - WINDOW)));
+            }}
+          />
+        </div>
+      </div>
+      <div className='flex flex-col gap-3'>
+        <label className='flex flex-col gap-1 text-sm'>
+          <span className='text-description'>
+            Visible range: {visibleRange.from}–{visibleRange.to} (drag to scroll)
+          </span>
+          <input
+            type='range'
+            min={0}
+            max={DOC_LENGTH - WINDOW}
+            value={start}
+            onChange={(event) => setStart(Number(event.target.value))}
+          />
+        </label>
+        <p className='text-sm text-description'>
+          Hover the rail to see the wave + popover. Ticks intersecting the visible range are brighter.
+        </p>
+        <p className='text-sm'>Selected: {selected ? selected.title : '(none)'}</p>
+      </div>
+    </div>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-feed/components/Outline',
+  component: Outline,
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+} satisfies Meta<typeof Outline>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    markers: defaultMarkers,
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    markers: [],
+  },
+};
+
+/**
+ * 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 const Dismissal: Story = {
+  args: { markers: defaultMarkers },
+  play: async ({ canvasElement }) => {
+    const rail = canvasElement.querySelector<HTMLElement>('[role="navigation"]')!;
+    const tick = rail.querySelectorAll('button')[3] as HTMLElement;
+    const settle = async () => {
+      for (let frame = 0; frame < 20; frame++) {
+        await new Promise((resolve) => requestAnimationFrame(resolve));
+      }
+    };
+
+    // Focused explicitly as well as clicked: a dispatched `click()` does not move focus, and focus
+    // is the thing whose side effect this is about.
+    tick.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+    tick.focus();
+    tick.click();
+    await settle();
+
+    await expect({
+      focused: canvasElement.ownerDocument.activeElement === tick,
+      navigated: rail.dataset.navigated,
+    }).toEqual({ focused: true, navigated: '' });
+  },
+};
+
+/**
+ * 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 const KeyboardTakeover: Story = {
+  args: { markers: defaultMarkers },
+  play: async ({ canvasElement }) => {
+    const rail = canvasElement.querySelector<HTMLElement>('[role="navigation"]')!;
+    const tick = rail.querySelectorAll('button')[3] as HTMLElement;
+    // Polled to the condition rather than settled by frame count: the transitions run through
+    // effects whose commit timing differs between a laptop and CI, and a fixed wait encodes
+    // whichever machine wrote it.
+    const until = async (condition: () => boolean, frames = 300) => {
+      for (let frame = 0; frame < frames && !condition(); frame++) {
+        await new Promise((resolve) => requestAnimationFrame(resolve));
+      }
+      return condition();
+    };
+
+    // `pointerover`, not `pointerenter`: React synthesises enter from over/out pairs, so over is the
+    // event a handler actually hears.
+    tick.dispatchEvent(new PointerEvent('pointerover', { bubbles: true }));
+    const hovered = await until(() => rail.dataset.pointer === '3' && rail.dataset.shown === '3');
+
+    tick.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+    tick.focus();
+    tick.click();
+
+    // Three presses, with the pointer never moving off the tick that was clicked; the card must
+    // move with the keyboard even though the pointer has not moved at all.
+    let moved = false;
+    for (let press = 0; press < 3; press++) {
+      tick.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+      moved = (await until(() => rail.dataset.shown !== '3', 60)) || moved;
+    }
+
+    // Deliberately NOT asserted: that `data-pointer` still reads '3'. Chrome re-hit-tests a
+    // stationary cursor when layout shifts under it and fires real pointerover at wherever the
+    // runner last left the mouse — so on CI the backstop clears the pointer through no fault of the
+    // component's. What the product owes the reader is that the card moved with the keyboard and
+    // that pointing again takes over, and both are asserted.
+
+    // Pointing again hands it back: the pointer is the more direct statement while it is being made.
+    tick.dispatchEvent(new PointerEvent('pointerover', { bubbles: true }));
+    const returned = await until(() => rail.dataset.shown === rail.dataset.pointer && rail.dataset.pointer === '3');
+
+    await expect({ hovered, moved, returned }).toEqual({
+      hovered: true,
+      moved: true,
+      returned: true,
+    });
+  },
+};