@dxos/react-ui-feed 0.11.1

package/src/debug/frame-meter.test.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { rateAtQuantile } from './frame-meter';
+
+/** A pass as a list of frame durations (ms), in the histogram the meter keeps. */
+const histogram = (durations: number[]): { buckets: Uint32Array; frames: number } => {
+  const buckets = new Uint32Array(512);
+  for (const duration of durations) {
+    buckets[Math.min(Math.round(duration), 511)]++;
+  }
+  return { buckets, frames: durations.length };
+};
+
+const rate = (durations: number[], quantile: number) => {
+  const { buckets, frames } = histogram(durations);
+  return rateAtQuantile(buckets, frames, quantile);
+};
+
+describe('rateAtQuantile', () => {
+  test('reports the display rate for a pass that never missed a frame', () => {
+    const smooth = Array.from({ length: 600 }, () => 16);
+    expect(rate(smooth, 0.5)).toEqual(63);
+    expect(rate(smooth, 0.95)).toEqual(63);
+  });
+
+  test('separates a single stall from the pass that contains it', () => {
+    // The case the whole meter exists for: 60fps throughout, one 200ms stall. A mean would call
+    // this smooth; the reader would not.
+    const stalled = [...Array.from({ length: 599 }, () => 16), 200];
+    expect(rate(stalled, 0.5)).toEqual(63);
+    expect(rate(stalled, 0.95)).toEqual(63);
+    expect(rate(stalled, 1)).toEqual(5);
+  });
+
+  test('the slow tail drags the 95th percentile down once a twentieth of the pass is bad', () => {
+    const janky = [...Array.from({ length: 90 }, () => 16), ...Array.from({ length: 10 }, () => 50)];
+    expect(rate(janky, 0.5)).toEqual(63);
+    expect(rate(janky, 0.95)).toEqual(20);
+  });
+
+  test('an empty pass reports nothing rather than dividing by zero', () => {
+    expect(rate([], 0.5)).toEqual(0);
+    expect(rateAtQuantile(new Uint32Array(512), 0, 0.95)).toEqual(0);
+  });
+});

package/src/debug/frame-meter.ts

@@ -0,0 +1,188 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** How often the live readout is published. Per-frame state would itself be the thing dropping frames. */
+const REPORT_INTERVAL = 250;
+
+/**
+ * A frame longer than this counts as a hitch: two intervals of a 60Hz display, the point at which a
+ * pause stops reading as motion and starts reading as a stutter. Deliberately absolute rather than
+ * derived from the display's rate — the question is whether a reader notices, not whether the
+ * hardware's budget was met.
+ */
+const HITCH_MS = 32;
+
+/** Frame durations are bucketed by the millisecond; anything slower than this lands in the last bucket. */
+const MAX_BUCKET = 512;
+
+/** Hitches traced per pass. A pass that produces more than this has already failed. */
+const MAX_TRACE = 100;
+
+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;
+};
+
+const EMPTY: FrameStats = { fps: 0, p50: 0, p95: 0, worst: 0, hitches: 0, frames: 0, duration: 0 };
+
+/**
+ * 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 const rateAtQuantile = (buckets: Uint32Array, frames: number, quantile: number): number => {
+  if (!frames) {
+    return 0;
+  }
+
+  const target = frames * quantile;
+  let seen = 0;
+  for (let ms = 0; ms < buckets.length; ++ms) {
+    seen += buckets[ms];
+    if (seen >= target) {
+      return ms > 0 ? Math.round(1000 / ms) : 0;
+    }
+  }
+
+  return 0;
+};
+
+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 const useFrameMeter = ({ label }: FrameMeterOptions = {}): FrameMeter => {
+  const [stats, setStats] = useState<FrameStats>(EMPTY);
+
+  const buckets = useRef(new Uint32Array(MAX_BUCKET));
+  const worst = useRef(0);
+  const hitches = useRef(0);
+  const frames = useRef(0);
+  const started = useRef(performance.now());
+  const labelRef = useRef(label);
+  labelRef.current = label;
+
+  const clear = useCallback(() => {
+    buckets.current.fill(0);
+    worst.current = 0;
+    hitches.current = 0;
+    frames.current = 0;
+    started.current = performance.now();
+    setStats(EMPTY);
+  }, []);
+
+  const rateAt = useCallback((quantile: number) => rateAtQuantile(buckets.current, frames.current, quantile), []);
+
+  /**
+   * Ends the pass: returns its one-line summary, copies it to the clipboard, logs it, and starts a
+   * fresh pass. One control, because a pass is exactly the interval between two of these — start a
+   * clean one by clicking, run the gesture, click again to record it.
+   */
+  const record = useCallback((): string => {
+    const seconds = (performance.now() - started.current) / 1000;
+    const summary = [
+      labelRef.current ?? 'pass',
+      `p50 ${rateAt(0.5)}`,
+      `p95 ${rateAt(0.95)}`,
+      `worst ${Math.round(worst.current)}ms`,
+      `${hitches.current} hitches`,
+      `${frames.current} frames`,
+      `${seconds.toFixed(1)}s`,
+    ].join(' · ');
+
+    // eslint-disable-next-line no-console
+    console.log('[feed] pass', summary);
+    void navigator.clipboard?.writeText(summary).catch(() => {
+      // Clipboard access is denied in some embedding contexts; the log above is the fallback.
+    });
+
+    clear();
+    return summary;
+  }, [rateAt, clear]);
+
+  useEffect(() => {
+    let handle = 0;
+    let last = performance.now();
+    let windowStart = last;
+    let windowFrames = 0;
+    let traced = 0;
+
+    const tick = (now: number) => {
+      const delta = now - last;
+      last = now;
+      frames.current++;
+      windowFrames++;
+      buckets.current[Math.min(Math.round(delta), MAX_BUCKET - 1)]++;
+      if (delta > worst.current) {
+        worst.current = delta;
+      }
+      if (delta > HITCH_MS) {
+        hitches.current++;
+        if (traced++ < MAX_TRACE) {
+          // eslint-disable-next-line no-console
+          console.debug('[feed] hitch', {
+            ms: Math.round(delta),
+            at: Math.round(now - started.current),
+            label: labelRef.current,
+          });
+        }
+      }
+
+      const elapsed = now - windowStart;
+      if (elapsed >= REPORT_INTERVAL) {
+        setStats({
+          fps: Math.round((windowFrames * 1000) / elapsed),
+          p50: rateAt(0.5),
+          p95: rateAt(0.95),
+          worst: Math.round(worst.current),
+          hitches: hitches.current,
+          frames: frames.current,
+          duration: Math.round(now - started.current),
+        });
+        windowStart = now;
+        windowFrames = 0;
+      }
+
+      handle = requestAnimationFrame(tick);
+    };
+
+    handle = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(handle);
+  }, [rateAt]);
+
+  return { ...stats, label, record };
+};

package/src/debug/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Debug';
+export * from './debug-model';
+export * from './frame-meter';
+export * from './Stats';
+export * from './use-debug';

package/src/debug/use-debug.tsx

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type PropsWithChildren, createContext, useContext, useEffect, useMemo } from 'react';
+
+import { DebugModel, type DebugProbe } from './debug-model';
+
+const DebugContext = createContext<DebugModel | undefined>(undefined);
+
+export type DebugProviderProps = PropsWithChildren<{ model?: DebugModel }>;
+
+/**
+ * Scope for probes. Anything under it may instrument itself; a `Debug` table under the same
+ * provider renders whatever registered. No provider, no cost: the hooks below no-op.
+ */
+export const DebugProvider = ({ model: provided, children }: DebugProviderProps) => {
+  const model = useMemo(() => provided ?? new DebugModel(), [provided]);
+  return <DebugContext.Provider value={model}>{children}</DebugContext.Provider>;
+};
+
+export const useDebugModel = (): DebugModel | undefined => useContext(DebugContext);
+
+/**
+ * Register live readouts for as long as the component is mounted.
+ *
+ * The probe reads state through a closure, so the component never re-renders for the table's sake;
+ * `deps` re-registers when the closure would go stale (a rebuilt model, a new element).
+ */
+export const useDebugProbes = (probes: () => DebugProbe[], deps: unknown[] = []): void => {
+  const model = useDebugModel();
+  useEffect(() => {
+    if (!model) {
+      return;
+    }
+
+    const unregister = probes().map((probe) => model.register(probe));
+    return () => unregister.forEach((remove) => remove());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [model, ...deps]);
+};

package/src/hooks/follow.stories.tsx

@@ -0,0 +1,200 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { IconButton, Panel, ScrollArea, Toolbar } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { mx } from '@dxos/ui-theme';
+
+import { ScrollFollower } from './follow';
+
+/** Fixed so the readout in rows/s is directly checkable against the pixels travelled. */
+const ROW_HEIGHT = 48;
+
+type StoryProps = {
+  count?: number;
+  /** rows/s */
+  maxSpeed?: number;
+  /** rows/s² */
+  acceleration?: number;
+  /** rows/s²; defaults to `acceleration` */
+  deceleration?: number;
+  /** Append an item every `growInterval` ms while following, to test a moving target. */
+  grow?: boolean;
+  growInterval?: number;
+};
+
+/**
+ * The scroll mechanism on its own.
+ *
+ * Deliberately free of messages, items and virtualization: plain rows in a `ScrollArea`, so what is
+ * on screen is only the follow — its ramp up, its cruise, and its landing. When the feed's scrolling
+ * feels wrong, this is where to tell a follow problem apart from a measurement one.
+ */
+const DefaultStory = ({
+  count = 100,
+  maxSpeed,
+  acceleration,
+  deceleration,
+  grow = false,
+  growInterval = 300,
+}: StoryProps) => {
+  const [viewport, setViewport] = useState<HTMLDivElement | null>(null);
+  const [extra, setExtra] = useState(0);
+  const [running, setRunning] = useState(false);
+  const [readout, setReadout] = useState({ top: 0, target: 0, velocity: 0, peak: 0 });
+
+  const items = useMemo(() => Array.from({ length: count + extra }, (_, index) => ({ index })), [count, extra]);
+
+  // Rows are a fixed size here, which is the point: the mechanism is measured against a known
+  // geometry so a speed in rows/s means exactly what it says.
+  const follower = useMemo(
+    () =>
+      viewport
+        ? new ScrollFollower(viewport, { maxSpeed, acceleration, deceleration, rowHeight: () => ROW_HEIGHT })
+        : undefined,
+    [viewport, maxSpeed, acceleration, deceleration],
+  );
+  useEffect(() => () => follower?.cancel(), [follower]);
+
+  const handleToggle = useCallback(() => {
+    if (follower?.running) {
+      // `running` stays true through the coast; the sampler below clears it once the follow has
+      // actually come to rest, so the control reflects the motion rather than the intent.
+      follower.stop();
+    } else {
+      follower?.start();
+      setRunning(true);
+    }
+  }, [follower]);
+
+  const handleTop = useCallback(() => {
+    follower?.cancel();
+    setRunning(false);
+    setExtra(0);
+    if (viewport) {
+      viewport.scrollTop = 0;
+    }
+  }, [follower, viewport]);
+
+  // A moving target: content arriving while the follow is under way is the case a single smooth
+  // scroll cannot serve, since each arrival would restart its easing.
+  useEffect(() => {
+    if (!grow || !running) {
+      return;
+    }
+
+    const interval = setInterval(() => setExtra((value) => value + 1), growInterval);
+    return () => clearInterval(interval);
+  }, [grow, running, growInterval]);
+
+  // Sampled rather than pushed: the follower writes `scrollTop` every frame, and re-rendering the
+  // list at that rate would measure React instead of the scroll.
+  useEffect(() => {
+    if (!viewport || !follower) {
+      return;
+    }
+
+    const timer = setInterval(() => {
+      const velocity = Math.round(follower.velocity * 10) / 10;
+      setReadout((prev) => ({
+        top: Math.round(viewport.scrollTop),
+        target: Math.round(viewport.scrollHeight - viewport.clientHeight),
+        velocity,
+        // Peak is what says whether the ceiling was ever reached; a travel that never cruises reads
+        // as abrupt for a reason that has nothing to do with the landing.
+        peak: follower.running ? Math.max(prev.peak, velocity) : prev.peak,
+      }));
+      setRunning(follower.running);
+    }, 50);
+    return () => clearInterval(timer);
+  }, [viewport, follower]);
+
+  return (
+    <Panel.Root>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root>
+          <IconButton
+            icon={running ? 'ph--stop--regular' : 'ph--play--regular'}
+            iconOnly
+            label={running ? 'Stop' : 'Start'}
+            data-testid='follow.toggle'
+            onClick={handleToggle}
+          />
+          <IconButton
+            icon='ph--arrow-line-up--regular'
+            iconOnly
+            label='Top'
+            data-testid='follow.top'
+            onClick={handleTop}
+          />
+        </Toolbar.Root>
+      </Panel.Toolbar>
+
+      <Panel.Content asChild>
+        <ScrollArea.Root orientation='vertical'>
+          <ScrollArea.Viewport data-testid='follow.viewport' ref={setViewport}>
+            {items.map(({ index }) => (
+              <div
+                key={index}
+                style={{ height: ROW_HEIGHT }}
+                className={mx('flex items-center px-3', index % 2 === 0 && 'bg-input-surface')}
+              >
+                <span className='text-sm text-description'>{index}</span>
+              </div>
+            ))}
+          </ScrollArea.Viewport>
+        </ScrollArea.Root>
+      </Panel.Content>
+
+      <Panel.Statusbar>
+        <div className='h-6 grid grid-cols-5 items-center gap-4 px-2 text-xs text-description tabular-nums'>
+          <span data-testid='follow.items'>{items.length} items</span>
+          <span data-testid='follow.position'>
+            {readout.top} / {readout.target}
+          </span>
+          <span data-testid='follow.remaining'>
+            {((readout.target - readout.top) / ROW_HEIGHT).toFixed(1)} rows left
+          </span>
+          <span data-testid='follow.velocity'>
+            {readout.velocity} rows/s (peak {readout.peak})
+          </span>
+          <span className='text-right'>{running ? 'following' : 'idle'}</span>
+        </div>
+      </Panel.Statusbar>
+    </Panel.Root>
+  );
+};
+
+const meta: Meta<StoryProps> = {
+  title: 'ui/react-ui-feed/hooks/follow',
+  render: DefaultStory,
+  decorators: [withLayout({ layout: 'column' }), withTheme()],
+  parameters: { layout: 'fullscreen' },
+  args: { count: 100 },
+};
+
+export default meta;
+
+type Story = StoryObj<StoryProps>;
+
+/** Fixed target: press play and watch it ramp up, cruise, then brake onto the last row. */
+export const Default: Story = {};
+
+/** Moving target: rows keep arriving, so the follow should hold its cruise speed rather than stutter. */
+export const Growing: Story = {
+  args: { grow: true },
+};
+
+/** Slower and gentler — the dials, for comparing feel. */
+export const Gentle: Story = {
+  args: { maxSpeed: 4, acceleration: 8 },
+};
+
+/** Brakes harder than it accelerates: a quick pick-up with a long, soft landing. */
+export const LateBraking: Story = {
+  args: { maxSpeed: 16, acceleration: 40, deceleration: 8 },
+};

package/src/hooks/follow.test.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { stepVelocity } from './follow';
+
+const maxSpeed = 1_600;
+const acceleration = 3_200;
+const frame = 1 / 60;
+
+const step = (velocity: number, distance: number) =>
+  stepVelocity({ velocity, distance, dt: frame, maxSpeed, acceleration });
+
+describe('stepVelocity', () => {
+  test('ramps up from rest rather than jumping to full speed', () => {
+    const first = step(0, 10_000);
+    expect(first).toBeGreaterThan(0);
+    expect(first).toBeLessThan(maxSpeed / 2);
+  });
+
+  test('reaches the ceiling and stays there while the target is far', () => {
+    let velocity = 0;
+    for (let index = 0; index < 120; index++) {
+      velocity = step(velocity, 10_000);
+    }
+    expect(velocity).toEqual(maxSpeed);
+  });
+
+  test('decelerates as the target approaches', () => {
+    const near = step(maxSpeed, 20);
+    expect(near).toBeLessThan(maxSpeed);
+    expect(step(near, 5)).toBeLessThan(near);
+  });
+
+  test('brakes onto the curve rather than easing towards it', () => {
+    // Rate-limiting the slow-down would leave the speed above what the remaining distance can shed,
+    // and the follow would reach the target still moving — an abrupt stop instead of a landing.
+    for (const distance of [1, 10, 100, 400]) {
+      const velocity = step(maxSpeed, distance);
+      expect((velocity * velocity) / (2 * acceleration)).toBeLessThanOrEqual(distance + 1e-6);
+    }
+  });
+
+  test('arrives at rest', () => {
+    expect(step(0, 0)).toEqual(0);
+  });
+
+  test('a whole travel accelerates, cruises and lands gently', () => {
+    // Simulated rather than asserted step-by-step: deceleration is rate-limited like acceleration,
+    // so a single step from an arbitrary speed can exceed its own braking distance. What matters is
+    // the shape of the complete journey.
+    let velocity = 0;
+    let position = 0;
+    const target = 4_000;
+    const speeds: number[] = [];
+    const steps: number[] = [];
+    for (let index = 0; index < 600 && target - position > 0.5; index++) {
+      velocity = step(velocity, target - position);
+      const next = Math.min(target, position + velocity * frame);
+      steps.push(next - position);
+      position = next;
+      speeds.push(velocity);
+    }
+
+    expect(position).toBeCloseTo(target, 0);
+    expect(Math.max(...speeds)).toBeLessThanOrEqual(maxSpeed);
+    expect(Math.max(...speeds)).toBeGreaterThan(maxSpeed * 0.9);
+    // Landing measured in pixels travelled, not as a fraction of the ceiling: the last frame before
+    // arrival is what the eye reads as a glide or a stop, and a couple of pixels is a glide.
+    expect(steps[steps.length - 1]).toBeLessThan(4);
+    expect(steps[0]).toBeLessThan(steps[Math.floor(steps.length / 2)]);
+  });
+
+  test('a moving target keeps it at cruise speed', () => {
+    // Content arriving faster than the follow travels: the distance never shrinks.
+    let velocity = 0;
+    for (let index = 0; index < 120; index++) {
+      velocity = step(velocity, 5_000);
+    }
+    expect(velocity).toEqual(maxSpeed);
+  });
+});
+
+describe('deceleration', () => {
+  const at = (distance: number, deceleration: number) =>
+    stepVelocity({ velocity: maxSpeed, distance, dt: frame, maxSpeed, acceleration, deceleration });
+
+  test('a gentler rate starts braking further out', () => {
+    // Braking distance is v²/2d: at a third of the rate the follow is already slowing where the
+    // matched rate is still at full speed, which is what makes the landing visible.
+    // 800px is inside the gentler rate's runway (v²/2d = 1200px) and outside the matched one's
+    // (400px), so the two disagree exactly where it matters.
+    const distance = 800;
+    expect(at(distance, acceleration)).toEqual(maxSpeed);
+    expect(at(distance, acceleration / 3)).toBeLessThan(maxSpeed);
+  });
+
+  test('defaults to the acceleration when unset', () => {
+    expect(stepVelocity({ velocity: maxSpeed, distance: 100, dt: frame, maxSpeed, acceleration })).toEqual(
+      at(100, acceleration),
+    );
+  });
+});