@dxos/react-ui-feed 0.11.1

package/src/testing/debug/FeedStats.tsx

@@ -0,0 +1,182 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { IconButton, type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { useMessageList } from '../../components';
+import { type FrameMeter, type Stat, Stats, warnAbove } from '../../debug';
+
+/** What the feed currently holds, as opposed to how well it is holding it. */
+const FEED_STATS: Stat[] = [
+  {
+    id: 'range',
+    label: 'range',
+  },
+  {
+    id: 'index',
+    label: 'index',
+  },
+  {
+    id: 'rows',
+    label: 'rows',
+  },
+  {
+    id: 'widgets',
+    label: 'widgets',
+  },
+  {
+    id: 'selected',
+    label: 'selected',
+  },
+  {
+    id: 'hits',
+    label: 'hits',
+  },
+];
+
+/**
+ * The scroll-quality verdict: live rate, the rate at the pass's slowest fifth, the worst frame, and
+ * how many frames stuttered. Only meaningful at a real keyboard — an agent's browser throttles the
+ * frames this counts.
+ *
+ * `jumps` are rows moving against the scroll, sampled per frame; `shifts` are rows whose offset
+ * changed after they were laid out; `breaks` are shifts that broke the order. All three should be
+ * zero on a still feed, so each is coloured the moment it is not.
+ */
+const FRAME_STATS: Stat[] = [
+  {
+    id: 'fps',
+    label: 'render',
+    unit: 'fps',
+    classNames: (value) => Number(value) > 0 && Number(value) < 50 && 'text-warning-text',
+  },
+  {
+    id: 'p95',
+    label: 'p95',
+    unit: 'ms',
+  },
+  {
+    id: 'worst',
+    label: 'worst',
+    unit: 'ms',
+  },
+  {
+    id: 'hitches',
+    label: 'hitches',
+    classNames: warnAbove,
+  },
+  {
+    id: 'jumps',
+    label: 'jumps',
+    classNames: warnAbove,
+  },
+  {
+    id: 'shifts',
+    label: 'shifts',
+    classNames: warnAbove,
+  },
+  {
+    id: 'breaks',
+    label: 'breaks',
+    classNames: warnAbove,
+  },
+];
+
+export type FeedStatsProps = ThemedClassName<{
+  meter: FrameMeter;
+  streaming?: boolean;
+  selected?: number;
+  hits?: number;
+}>;
+
+/**
+ * Everything measured about a feed, floating over it.
+ *
+ * It sits above the viewport rather than in a statusbar because a statusbar is part of the layout
+ * being measured: a block of readouts that grows or wraps changes the height of the scroll
+ * container, and every number in it would then describe a viewport the readouts themselves resized.
+ */
+export const FeedStats = ({ classNames, meter, streaming, selected = 0, hits = 0 }: FeedStatsProps) => {
+  const { range, currentIndex, count, mountedRows, mountedWidgets, jumps, shifts, breaks, resetShifts } =
+    useMessageList('FeedStats');
+
+  // A pass is the interval between two presses, so the control is start/stop rather than a reset.
+  const [recording, setRecording] = useState(false);
+  const onRecord = useCallback(() => {
+    meter.record();
+    setRecording((value) => !value);
+  }, [meter]);
+
+  const values = useMemo(
+    () => ({
+      range: range ? `${range.startIndex} / ${range.endIndex}` : '—',
+      index: `${currentIndex} / ${count}`,
+      rows: mountedRows,
+      widgets: mountedWidgets,
+      selected,
+      hits,
+      fps: meter.fps,
+      p95: meter.p95,
+      worst: meter.worst,
+      hitches: meter.hitches,
+      jumps: jumps.count,
+      shifts,
+      breaks,
+    }),
+    [range, currentIndex, count, mountedRows, mountedWidgets, selected, hits, meter, jumps.count, shifts, breaks],
+  );
+
+  const label = `${meter.label} — p50 ${meter.p50} · ${meter.frames} frames · ${(meter.duration / 1000).toFixed(1)}s`;
+
+  return (
+    <div
+      // Fixed width, not fitted: the widest line is the pass summary, whose length changes with the
+      // elapsed time, so a panel sized to its content would resize once a second while being read.
+      className={mx(
+        'z-10 absolute bottom-3 right-3 w-[12rem] grid p-2 rounded-sm border border-separator bg-base-surface text-xs text-description',
+        classNames,
+      )}
+      data-testid='feed.stats'
+    >
+      <div className='flex items-center min-w-0'>
+        <span className='grow truncate' data-testid='feed.stream.state'>
+          {streaming ? 'streaming…' : 'idle'}
+        </span>
+        <IconButton
+          icon={recording ? 'ph--stop--regular' : 'ph--record--regular'}
+          iconOnly
+          label={recording ? 'End the pass' : 'Start a pass'}
+          variant='ghost'
+          size={3}
+          data-testid='feed.debug.record'
+          onClick={onRecord}
+        />
+        <IconButton
+          icon='ph--arrow-counter-clockwise--regular'
+          iconOnly
+          label='Reset counters'
+          variant='ghost'
+          size={3}
+          data-testid='feed.debug.reset'
+          onClick={resetShifts}
+        />
+      </div>
+
+      <Stats stats={FEED_STATS} values={values} />
+
+      {/* The pass's extent rides in the tooltip: it is context for the readings rather than one of
+          them, and its width changes with the elapsed time. */}
+      <Stats
+        stats={FRAME_STATS}
+        values={values}
+        classNames='border-t border-subdued-separator pt-1'
+        title={label}
+        data-testid='feed.frames'
+      />
+    </div>
+  );
+};

package/src/testing/debug/index.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Instrumentation, kept apart from the harness it measures.
+//
+// A story is about the feed; these are about how well the feed behaves. Separated because
+// instrumentation accumulates — a meter, a sweep, a jump detector, the controls that reset them —
+// and threaded through the story it slowly becomes the story.
+//
+
+export * from './FeedStats';
+
+export * from './sweep';
+export * from './use-feed-debug';

package/src/testing/debug/sweep.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Travel speed (px/s) of a measured pass: about what a hard trackpad fling reaches on a 120Hz
+ * display, and the speed at which a reader still expects to see content rather than a blur.
+ *
+ * Not "the whole document in N seconds", which was the first attempt: 2,000 rows in six seconds is
+ * 40,000 px/s — some 400 rows a second, each one a CodeMirror view to mount and measure — and it
+ * collapsed the frame rate to 3fps on hardware that idles at 120. That measured the sweep, not the
+ * list.
+ */
+const VELOCITY = 3_000;
+
+/** Time spent travelling in each direction (ms), so a pass covers the same distance in every story. */
+const LEG_DURATION = 5_000;
+
+export type SweepOptions = {
+  /** Travel speed in px/s. @default 3000 */
+  velocity?: number;
+  /** Time for one leg (ms). @default 5000 */
+  duration?: number;
+  /** Called once the return leg lands, or when cancelled. */
+  onDone?: () => void;
+};
+
+/**
+ * Scrolls an element down and back at a fixed speed.
+ *
+ * A measured pass has to be one repeatable gesture or the numbers cannot be compared between
+ * stories, and a 2,000-row feed is far too long to fling by hand. Fixed speed for a fixed time —
+ * rather than a fixed fraction of the document — so the two stories being compared travel the same
+ * distance even though they disagree about how tall the document is until their rows have measured.
+ */
+export const sweepScroll = (
+  element: HTMLElement,
+  { velocity = VELOCITY, duration = LEG_DURATION, onDone }: SweepOptions = {},
+) => {
+  let frame = 0;
+  let cancelled = false;
+  let start = performance.now();
+  let last = start;
+  let leg: 'down' | 'up' = 'down';
+
+  const finish = () => {
+    cancelAnimationFrame(frame);
+    onDone?.();
+  };
+
+  const tick = (now: number) => {
+    if (cancelled) {
+      return;
+    }
+
+    // Stepped by elapsed time rather than by frame, so a dropped frame costs smoothness but not
+    // distance — two passes over the same feed cover the same ground however each one rendered.
+    const step = (velocity * (now - last)) / 1000;
+    last = now;
+    const limit = element.scrollHeight - element.clientHeight;
+    element.scrollTop = Math.max(0, Math.min(element.scrollTop + (leg === 'down' ? step : -step), limit));
+
+    if (now - start < duration) {
+      frame = requestAnimationFrame(tick);
+      return;
+    }
+
+    if (leg === 'down') {
+      leg = 'up';
+      start = now;
+      last = now;
+      frame = requestAnimationFrame(tick);
+      return;
+    }
+
+    finish();
+  };
+
+  frame = requestAnimationFrame(tick);
+
+  return () => {
+    cancelled = true;
+    finish();
+  };
+};

package/src/testing/debug/use-feed-debug.ts

@@ -0,0 +1,91 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type RefObject, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { type FrameMeter, useFrameMeter } from '../../debug';
+import { sweepScroll } from './sweep';
+
+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 const useFeedDebug = ({
+  scenario,
+  count,
+  estimateSize,
+  streaming,
+  enabled = false,
+}: FeedDebugOptions): FeedDebug => {
+  const [debug, setDebug] = useState(enabled);
+  const toggleDebug = useCallback(() => setDebug((value) => !value), []);
+
+  const label = useMemo(
+    () =>
+      [scenario ?? 'mixed', `${count} msgs`, estimateSize ? `est ${estimateSize}` : undefined, streaming && 'streaming']
+        .filter(Boolean)
+        .join(' · '),
+    [scenario, count, estimateSize, streaming],
+  );
+
+  const meter = useFrameMeter({ label });
+  const viewportRef = useRef<HTMLDivElement>(null);
+  const [sweeping, setSweeping] = useState(false);
+  const cancelSweep = useRef<(() => void) | null>(null);
+
+  // A measured pass has to be one repeatable gesture. Flinging 2,000 rows by hand is neither, so the
+  // sweep runs the traversal and records what it cost: click, wait, read the clipboard.
+  const onSweep = useCallback(() => {
+    if (sweeping) {
+      cancelSweep.current?.();
+      return;
+    }
+
+    const viewport = viewportRef.current;
+    if (!viewport) {
+      return;
+    }
+
+    meter.record();
+    setSweeping(true);
+    cancelSweep.current = sweepScroll(viewport, {
+      onDone: () => {
+        cancelSweep.current = null;
+        setSweeping(false);
+        meter.record();
+      },
+    });
+  }, [sweeping, meter]);
+
+  useEffect(() => () => cancelSweep.current?.(), []);
+
+  return { debug, toggleDebug, meter, viewportRef, sweeping, onSweep };
+};

package/src/testing/generator.ts

@@ -0,0 +1,90 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { random } from '@dxos/random';
+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;
+};
+
+const SENDERS = ['user', 'assistant'] as const;
+
+/**
+ * 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 const createMessages = ({
+  count,
+  kinds = ['markdown', 'markdown', 'short', 'code', 'html'],
+  seed = 999,
+}: GeneratorOptions): Message.Message[] => {
+  random.seed(seed);
+  const start = Date.now() - count * 60_000;
+
+  return Array.from({ length: count }, (_, index) => {
+    const kind = kinds[index % kinds.length];
+    const role = SENDERS[index % SENDERS.length];
+    return Message.make({
+      created: new Date(start + index * 60_000).toISOString(),
+      sender: { role, name: role === 'user' ? 'Alice' : 'Assistant' },
+      blocks: [blockFor(kind, index)],
+      properties: { subject: `Message ${index}`, kind },
+    });
+  });
+};
+
+const blockFor = (kind: MessageKind, index: number) => {
+  switch (kind) {
+    case 'short':
+      return { _tag: 'text' as const, text: `**${index}.** ${random.lorem.sentence(6)}` };
+
+    case 'code':
+      return {
+        _tag: 'text' as const,
+        text: [
+          `**${index}.** ${random.lorem.sentence(8)}`,
+          '',
+          '```ts',
+          'const feed = useQuery(db, Query.from(feed));',
+          'const hits = searchFeed(messages, renderer, query);',
+          '```',
+          '',
+          random.lorem.sentence(12),
+        ].join('\n'),
+      };
+
+    case 'html':
+      return {
+        _tag: 'text' as const,
+        mimeType: 'text/html',
+        text: [
+          `<p><strong>${index}.</strong> ${random.lorem.sentence(10)}</p>`,
+          `<blockquote>${random.lorem.sentence(14)}</blockquote>`,
+          '<ul><li>attachment.pdf</li><li>invoice.csv</li></ul>',
+        ].join(''),
+      };
+
+    case 'markdown':
+    default:
+      return {
+        _tag: 'text' as const,
+        text: [
+          `**${index}.** ${random.lorem.sentence(10)}`,
+          '',
+          random.lorem.paragraph(),
+          '',
+          `- ${random.lorem.sentence(5)}`,
+          `- ${random.lorem.sentence(7)}`,
+        ].join('\n'),
+      };
+  }
+};

package/src/testing/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+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';