Anchored Live Feed

A live feed that preserves the reading position, with configurable items, labels, palette, and fonts. New content waits in a notice band until the reader requests it.

Why this one

Reading stability is the effect. Prepending a batch does not intentionally move the current record, steal focus, or reorder existing records. The component deduplicates IDs, excludes updates to existing IDs from the unread count, restores by identity, and chooses a surviving neighbor when an anchor disappears. The host owns data and subscription behavior.

How it works

1. Keep descending chronological order in the host. Each ID identifies a persistent record; duplicate IDs keep their first position and last payload.
2. Capture the first visible ID and its signed top offset relative to the list viewport. A negative offset means that the row starts above the viewport.
3. On iOS and Android, use FlatList's native maintainVisibleContentPosition for prepends. Web disables browser scroll anchoring and compensates the measured row delta before paint when the anchor is mounted. Virtualized targets are sought and corrected after measurement.
4. Count unseen prepended IDs while the reader is more than 32 points from the start. Updates to existing IDs and appended earlier pages do not increment the badge. Visiting records consumes their unread IDs.
5. Reserve the notice band even when the capsule is invisible. A voluntary jump runs for 280 ms; dragging cancels an active jump. A request received during a drag waits for scrolling to finish, and another drag cancels the queued request.
6. Remeasure variable-height rows after layout changes. Native explicit restores and anchor-removal recovery measure the target against the viewport; no fictional fixed-height getItemLayout is supplied.

Install

Copy this folder, excluding demo/, into your app. Dependencies are already compatible with Expo SDK 58:

npx expo install react-native-reanimated react-native-worklets @shopify/react-native-skia

Use the Reanimated/worklets setup appropriate to your host project. On web, initialize Skia's CanvasKit before mounting the component, following your host's Skia setup. No network images, external services, or additional native modules are required. Icons: Lucide (ISC); exact paths are included in icons.ts.

Usage

import { useRef, useState } from 'react';
import { View } from 'react-native';
import {
  AnchoredLiveFeed,
  PAPER,
  type AnchoredLiveFeedRef,
  type FeedItem,
} from './anchored-live-feed';

const labels = {
  empty: 'No notes yet.',
  showLatest: 'Show latest',
  pause: 'Pause updates',
  resume: 'Resume updates',
  readingHere: 'Reading here',
  loading: 'Loading earlier notes',
  anchorRemoved: 'That note was removed. Continuing at the next available note.',
};

export function Notes({ items }: { items: FeedItem[] }) {
  const feed = useRef<AnchoredLiveFeedRef>(null);
  const [live, setLive] = useState(true);

  return (
    <View style={{ width: '100%', height: 400 }}>
      <AnchoredLiveFeed
        ref={feed}
        items={items}
        labels={labels}
        live={live}
        onLiveChange={setLive}
        palette={PAPER}
        motionScale={0.8}
        formatNewCount={(count) => `${count} new notes`}
        accessibilityLabel="Notes, newest first"
        testID="notes"
      />
    </View>
  );
}

The host subscribes or unsubscribes when its controlled live value changes. A pause request does not mutate or reject items. Filter stale network responses by ID and request generation before updating props. Do not reorder existing records during a prepend.

For custom content, pass renderItem={({ item, index }) => <YourRow item={item} />}. Supply complete row content and accessibility semantics. Height is measured from the rendered result. onAnchorChange can save { id, offset } for a later feed.current?.restoreAnchor(saved) call.

Props

Labels

Empty row titles, bodies, time labels, marker labels, and loading text are omitted. The notice band remains reserved by design. No demo brand or editorial copy is embedded in the reusable component.

Ref methods

live and loadingEarlier are always controlled. There is no uncontrolled subscription mode and no ref method that simulates arrivals. A host replacement of the data remains authoritative.

States and transitions

Demo and simulated content

The Lumen demo uses 100 locally generated editorial records with variable heights. It opens at note-4 with offset −18; receives one note at 600 ms and two more at 850 ms; shows the accumulated capsule before 1.4 seconds; jumps at 2.1 seconds; and restores the original fixture at 4.2 seconds. autoplay repeats every five seconds. Replay runs one cycle. Touch/pointer input cancels pending demo timers; theme and subscription actions also cancel them. The demo owns every fixture reset.

Paper/Night palettes are complete. Ambient gradients are static. The bottom control band places a radius-20 BlurView over its own gradient, with an opaque readable surface as Android fallback. No photographs or generated artwork are used.

Compatibility

Target versions: Expo 58, React Native 0.88.0, Reanimated 4.7.1, worklets 0.13.0, Skia 2.14.0. Expo Go includes these modules. The demo also uses existing expo-blur and expo-linear-gradient; neither is required by the reusable component.

Platform limits: native prepend behavior depends on RN's visible-content implementation; do not reorder existing data during prepend. Web can compensate a mounted anchor synchronously; a virtualized offscreen restore requires a seek and subsequent measurement. The host should expose an explicit detail view if a row's complete content cannot be conveniently read in its chosen slot at very large text sizes. Custom rows must remain measurable and must not apply independent layout translations to the outer row container.

Implementation notes

• Text remains in flow; compact mode omits the decorative headline and brand. No exterior scroll or top-right control is present.
• The count lives in a permanently reserved band. The reading marker reserves identical geometry in every default row, avoiding marker-induced row reflow.
• The demo shows the three-note arrival while the marked row stays still, before three seconds.
• State labels have one active text layer. Digit columns reserve their width with an invisible in-flow numeral; progress resets in a layout effect.
• Every BlurView and intermediate wrapper has its own radius and overflow clipping. No business action waits for an animation completion.

Accessibility

Only the FlatList scrolls. There is no exterior ScrollView, fixed screen-height calculation, or component safe-area inset. The host supplies safe areas. The demo measures its own slot, limits width to 480 pt, and removes decorative context below 540 pt of height or at large font scale. Compact layouts reserve the top 56 points for the host close control. Rows retain complete text and can grow; they are not clamped to two lines when that would hide data. Small slots trade visible row count for usable controls.

Controls have at least 48-point targets, immediate 0.97 press feedback, labels, and disabled states. The invisible notice is excluded from touch and accessibility. New data never requests focus. Native readers receive a discrete announcement after 400 ms of count stability; web uses one polite live region. Individual count columns are hidden from accessibility. Reduced motion removes row travel, capsule scaling, rolling travel, and animated scrolling; content changes retain a short fade and all actions. Subscription labels replace each other without overlapping text layers.