@dxos/react-ui-feed 0.11.1

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@dxos/react-ui-feed",
+  "version": "0.11.1",
+  "description": "Virtualized feed of message items.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "DXOS.org",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/lib/index.mjs"
+    },
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./dist/types/src/testing/index.d.ts",
+      "import": "./dist/lib/testing.mjs"
+    },
+    "./virtualizer": {
+      "source": "./src/virtualizer/index.ts",
+      "types": "./dist/types/src/virtualizer/index.d.ts",
+      "import": "./dist/lib/virtualizer.mjs"
+    },
+    "./debug": {
+      "source": "./src/debug/index.ts",
+      "types": "./dist/types/src/debug/index.d.ts",
+      "import": "./dist/lib/debug.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.8",
+    "@radix-ui/react-context": "1.1.1",
+    "dompurify": "^3.3.1",
+    "@dxos/types": "0.11.1",
+    "@dxos/react-ui": "0.11.1",
+    "@dxos/ui-editor": "0.11.1",
+    "@dxos/ui-theme": "0.11.1",
+    "@dxos/util": "0.11.1"
+  },
+  "devDependencies": {
+    "@storybook/react-vite": "^10.5.8",
+    "@types/react": "~19.2.17",
+    "@types/react-dom": "~19.2.3",
+    "effect": "4.0.0-rc.108",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "vite": "^8.2.1",
+    "@dxos/react-ui-components": "0.11.1",
+    "@dxos/random": "0.11.1"
+  },
+  "peerDependencies": {
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/react-ui": "^0.11.1",
+    "@dxos/ui-theme": "^0.11.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components/Block/HtmlBlock.tsx

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import DOMPurify from 'dompurify';
+import React, { memo, useMemo } from 'react';
+
+export type HtmlBlockProps = {
+  html: string;
+};
+
+/**
+ * A message rendered as sanitized HTML — the email case, which is not markdown and cannot be a
+ * CodeMirror document.
+ *
+ * Its presence is the reason the item renderer is generalized rather than markdown-only: the
+ * engine owns virtualization, chrome and selection anchors, not what a message looks like inside.
+ * As plain (non-contenteditable) DOM it is also the control case for cross-item selection.
+ */
+export const HtmlBlock = memo(({ html }: HtmlBlockProps) => {
+  const sanitized = useMemo(() => DOMPurify.sanitize(html, { USE_PROFILES: { html: true } }), [html]);
+
+  return <div className='dx-feed-html' dangerouslySetInnerHTML={{ __html: sanitized }} />;
+});
+
+HtmlBlock.displayName = 'HtmlBlock';

package/src/components/Block/MarkdownBlock.tsx

@@ -0,0 +1,157 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EditorState, type Extension } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import React, { memo, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import { useThemeContext } from '@dxos/react-ui';
+import { type XmlWidgetRegistry, type XmlWidgetState } from '@dxos/ui-editor';
+
+import { createBlockExtensions } from './extensions';
+import { type HighlightRange, setHighlights } from './highlight';
+import { useSelectionGroup } from './selection-group';
+
+export type MarkdownBlockProps = {
+  text: string;
+  /**
+   * When false the view mounts with `EditorView.editable.of(false)`, which drops `contenteditable`
+   * from the DOM. Browsers refuse to extend one selection across two contenteditable hosts, so this
+   * is what decides whether a drag can span adjacent items.
+   */
+  editable?: boolean;
+  registry?: XmlWidgetRegistry;
+  hits?: readonly HighlightRange[];
+  /** Number of block widgets this item currently has mounted; 0 once it unmounts. */
+  onWidgetsChange?: (count: number) => void;
+};
+
+/**
+ * One message as its own markdown document.
+ *
+ * Each item owns a document, so streaming appends and per-message editing stay local — where a
+ * single thread-wide document needs a cursor and a range table to know which message it is touching.
+ */
+export const MarkdownBlock = memo(({ text, editable = false, registry, hits, onWidgetsChange }: MarkdownBlockProps) => {
+  const { themeMode } = useThemeContext();
+  const [view, setView] = useState<EditorView | null>(null);
+  // React widgets render in portals into hosts the extension places in the document, so the item has
+  // to own them: a widget's tree belongs to the React root that rendered the item, not to CodeMirror.
+  const [widgets, setWidgets] = useState<XmlWidgetState[]>([]);
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  // Read through a ref so the group never lands in the extension deps: rebuilding extensions
+  // reconstructs the view, which would discard the selection the reader just made.
+  const selectionGroup = useSelectionGroup();
+  const selectionGroupRef = useRef(selectionGroup);
+  selectionGroupRef.current = selectionGroup;
+
+  const extensions = useMemo<Extension[]>(
+    () => [
+      ...createBlockExtensions({ registry, editable, themeMode, setWidgets }),
+      EditorView.updateListener.of((update) => {
+        if (update.selectionSet && !update.state.selection.main.empty) {
+          selectionGroupRef.current.claim(update.view);
+        }
+      }),
+    ],
+    [editable, themeMode, registry],
+  );
+
+  // Deliberately NOT `useTextEditor`, which builds the view in a passive effect — i.e. after paint.
+  // The virtualizer measures each row as it mounts, so a row whose document does not exist yet
+  // measures at chrome height and then grows, shifting every row below it. Constructing the view in
+  // the layout phase gives the row its real height before the first paint, so it is measured once.
+  const initialTextRef = useRef(text);
+  useLayoutEffect(() => {
+    const parent = rootRef.current;
+    if (!parent) {
+      return;
+    }
+
+    const instance = new EditorView({
+      parent,
+      state: EditorState.create({ doc: initialTextRef.current, extensions }),
+    });
+    const unregister = selectionGroupRef.current.register(instance);
+    setView(instance);
+
+    return () => {
+      unregister();
+      instance.destroy();
+      setView(null);
+    };
+  }, [extensions]);
+
+  // The document belongs to the model, not the view: a message whose text changes is reconciled
+  // rather than remounted, so the virtualizer's measurement for this row survives the update.
+  const currentRef = useRef(text);
+  useEffect(() => {
+    if (!view || currentRef.current === text) {
+      return;
+    }
+
+    const previous = currentRef.current;
+    currentRef.current = text;
+    initialTextRef.current = text;
+    // A streaming tail only ever extends: dispatch the delta so CodeMirror keeps scroll position and
+    // decorations instead of rebuilding the document on every frame.
+    view.dispatch(
+      text.startsWith(previous)
+        ? { changes: { from: previous.length, insert: text.slice(previous.length) } }
+        : { changes: { from: 0, to: view.state.doc.length, insert: text } },
+    );
+  }, [view, text]);
+
+  // Nothing is dispatched to clear highlights that were never set: a transaction makes CodeMirror
+  // re-measure the document, and a viewport of rows mounting is a viewport of forced layouts for a
+  // search that is not running.
+  const highlighted = useRef(false);
+  useEffect(() => {
+    if (!view || (!hits?.length && !highlighted.current)) {
+      return;
+    }
+
+    highlighted.current = Boolean(hits?.length);
+    view.dispatch({ effects: setHighlights.of(hits ?? []) });
+  }, [view, hits]);
+
+  // Reported rather than derived: the widgets are portals into the item's own document, so nothing
+  // above the item can count them without reaching into the DOM.
+  useEffect(() => {
+    onWidgetsChange?.(widgets.length);
+    return () => onWidgetsChange?.(0);
+  }, [widgets.length, onWidgetsChange]);
+
+  // A block widget is measured once, when CodeMirror mounts it. Its content is React rendered into a
+  // portal, so anything that changes height afterwards — a disclosure opening, an image loading —
+  // leaves the editor holding a stale height and drawing the lines below it over the widget.
+  //
+  // Observing the portal roots and asking for a re-measure is what keeps the document's geometry
+  // honest; the row's own height then follows through the virtualizer's observer.
+  useEffect(() => {
+    if (!view || !widgets.length) {
+      return;
+    }
+
+    const observer = new ResizeObserver(() => view.requestMeasure());
+    for (const { root } of widgets) {
+      observer.observe(root);
+    }
+
+    return () => observer.disconnect();
+  }, [view, widgets]);
+
+  return (
+    <>
+      <div ref={rootRef} />
+      {widgets.map(({ Component, root, id, props }) => (
+        <div key={id}>{createPortal(<Component view={view ?? undefined} {...props} />, root)}</div>
+      ))}
+    </>
+  );
+});
+
+MarkdownBlock.displayName = 'MarkdownBlock';

package/src/components/Block/block.stories.tsx

@@ -0,0 +1,140 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+import { expect } from 'storybook/test';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { trim } from '@dxos/util';
+
+import { chatRegistry } from '../../testing';
+import { HtmlBlock } from './HtmlBlock';
+import { MarkdownBlock } from './MarkdownBlock';
+import { WidgetStateProvider, createWidgetStateStore } from './widget-state';
+
+/**
+ * One story per item kind, outside any list: the item is the unit the feed mounts per message, and
+ * this is where its rendering is judged on its own — a defect here is the item's, never the
+ * placement's. Kinds mirror `ItemContent`: markdown (a read-only CodeMirror document), markdown
+ * with block widgets (the assistant turn's shape), markdown with highlights (what decorations
+ * paint), and html (sanitized prose, the email case).
+ */
+type StoryArgs = {
+  kind: 'markdown' | 'widgets' | 'highlighted' | 'html';
+};
+
+const MARKDOWN = trim`
+  ### A markdown item
+
+  One read-only CodeMirror document per message: **bold**, *emphasis*, [a link](https://dxos.org),
+  \`inline code\`, and a fence —
+
+  \`\`\`ts
+  const answer = 42;
+  \`\`\`
+
+  1. Ordered
+  2. Lists
+`;
+
+const WIDGETS = trim`
+  <prompt>What does a turn look like?</prompt>
+
+  <reasoning>Considering the block kinds a model emits, in order.</reasoning>
+
+  <toolCall name="search" input="{}"></toolCall>
+
+  The answer's prose follows the widgets, as ordinary markdown.
+`;
+
+const HIGHLIGHTED = 'The needle sits in the middle of this sentence, and the ranges paint it.';
+
+const HTML = trim`
+  <h3>An HTML item</h3>
+  <p>Sanitized prose for content that arrives as markup — the email case. <b>Tags</b> render,
+  <i>scripts</i> do not.</p>
+  <ul><li>One</li><li>Two</li></ul>
+`;
+
+const store = createWidgetStateStore();
+
+const DefaultStory = ({ kind }: StoryArgs) => {
+  switch (kind) {
+    case 'markdown':
+      return <MarkdownBlock text={MARKDOWN} />;
+    case 'widgets':
+      return (
+        <WidgetStateProvider store={store}>
+          <MarkdownBlock text={WIDGETS} registry={chatRegistry} />
+        </WidgetStateProvider>
+      );
+    case 'highlighted': {
+      const offset = HIGHLIGHTED.indexOf('needle');
+      return <MarkdownBlock text={HIGHLIGHTED} hits={[[offset, offset + 'needle'.length]]} />;
+    }
+    case 'html':
+      return <HtmlBlock html={HTML} />;
+  }
+};
+
+const meta: Meta<StoryArgs> = {
+  title: 'ui/react-ui-feed/components/Block',
+  render: DefaultStory,
+  decorators: [withLayout({ layout: 'column', classNames: 'w-[40rem] p-4' }), withTheme()],
+  args: { kind: 'markdown' },
+  argTypes: {
+    kind: { control: 'select', options: ['markdown', 'widgets', 'highlighted', 'html'] },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<StoryArgs>;
+
+/** Passive: flip `kind` in the controls. */
+export const Default: Story = {};
+
+export const Markdown: Story = {
+  args: { kind: 'markdown' },
+  play: async ({ canvasElement }) => {
+    // The document rendered as markdown, not as its source: decoration replaced the heading marks.
+    await expect(canvasElement.querySelector('.cm-content')).toBeTruthy();
+    await expect(canvasElement.textContent).toContain('A markdown item');
+  },
+};
+
+export const Widgets: Story = {
+  args: { kind: 'widgets' },
+  play: async ({ canvasElement }) => {
+    // The tags became widgets: the reasoning panel mounts as a React component inside the editor,
+    // and the raw angle brackets are gone from what the reader sees.
+    for (let frame = 0; frame < 60 && !canvasElement.querySelector('[data-testid="feed.widget"]'); frame++) {
+      await new Promise((resolve) => requestAnimationFrame(resolve));
+    }
+
+    await expect(canvasElement.querySelector('[data-testid="feed.widget"]')).toBeTruthy();
+    await expect(canvasElement.textContent).not.toContain('<reasoning>');
+  },
+};
+
+export const Highlighted: Story = {
+  args: { kind: 'highlighted' },
+  play: async ({ canvasElement }) => {
+    // What `useDecorations` paints, at the item level: the range carries a highlight mark.
+    for (let frame = 0; frame < 60 && !canvasElement.querySelector('.dx-feed-hit'); frame++) {
+      await new Promise((resolve) => requestAnimationFrame(resolve));
+    }
+
+    await expect(canvasElement.querySelector('.dx-feed-hit')).toBeTruthy();
+  },
+};
+
+export const Html: Story = {
+  args: { kind: 'html' },
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement.querySelector('h3')).toBeTruthy();
+    await expect(canvasElement.textContent).toContain('An HTML item');
+  },
+};

package/src/components/Block/construction.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EditorState, type Extension } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+
+/**
+ * What one item costs to build.
+ *
+ * The list's first fill mounts a viewport's worth of rows at once, so the wall-clock cost of that
+ * fill is the per-item construction cost times the number of rows on screen — which is why this is
+ * measured per extension set rather than per story: the answer has to say *what* to drop.
+ *
+ * Only meaningful in a real browser. Construction is dominated by style resolution and the forced
+ * layout that follows it, neither of which a DOM shim performs.
+ */
+export type ConstructionCase = {
+  name: string;
+  extensions: Extension[];
+};
+
+export type ConstructionResult = {
+  name: string;
+  /** Mean milliseconds to construct one view and force its layout. */
+  mean: number;
+  /** Slowest single construction in the run, which is what a dropped frame is made of. */
+  worst: number;
+};
+
+export type ConstructionProfileOptions = {
+  parent: HTMLElement;
+  cases: ConstructionCase[];
+  doc: string;
+  runs?: number;
+};
+
+/**
+ * Times construction of `runs` views per case, including the layout each one forces.
+ *
+ * Views are destroyed after each case rather than at the end: a hundred live editors in one parent
+ * make every subsequent layout progressively more expensive, which would report the harness.
+ */
+export const profileConstruction = ({
+  parent,
+  cases,
+  doc,
+  runs = 20,
+}: ConstructionProfileOptions): ConstructionResult[] =>
+  cases.map(({ name, extensions }) => {
+    // Discarded: the first view of a run pays for style sheets the rest reuse.
+    construct(parent, extensions, doc).destroy();
+
+    const views: EditorView[] = [];
+    let worst = 0;
+    const start = performance.now();
+    for (let index = 0; index < runs; index++) {
+      const before = performance.now();
+      views.push(construct(parent, extensions, doc));
+      worst = Math.max(worst, performance.now() - before);
+    }
+    const mean = (performance.now() - start) / runs;
+
+    for (const view of views) {
+      view.destroy();
+    }
+
+    return { name, mean, worst };
+  });
+
+// Reading `offsetHeight` is not incidental: the row is measured the instant it mounts, so the
+// layout the editor forces is part of what the item costs.
+const construct = (parent: HTMLElement, extensions: Extension[], doc: string): EditorView => {
+  const view = new EditorView({ parent, state: EditorState.create({ doc, extensions }) });
+  void view.dom.offsetHeight;
+  return view;
+};

package/src/components/Block/extensions.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Extension } from '@codemirror/state';
+
+import {
+  type XmlWidgetRegistry,
+  type XmlWidgetState,
+  createBasicExtensions,
+  createMarkdownExtensions,
+  createThemeExtensions,
+  decorateMarkdown,
+  extendedMarkdown,
+  xmlBlockDecoration,
+  xmlFormatting,
+  xmlTags,
+} from '@dxos/ui-editor';
+
+import { highlights, highlightTheme } from './highlight';
+
+export type ItemExtensionOptions = {
+  registry?: XmlWidgetRegistry;
+  editable?: boolean;
+  themeMode?: 'light' | 'dark';
+  setWidgets?: (widgets: XmlWidgetState[]) => void;
+};
+
+/**
+ * The extension set one item's document is built from.
+ *
+ * Everything that does not depend on the item is **built once and shared**, and that is the point of
+ * this module rather than a tidiness. `EditorView.theme()` mints a new `StyleModule` and a new
+ * generated class on every call, so a set built per item injects one stylesheet per row and
+ * invalidates the whole document's style each time it does. Measured at ~14ms per row against ~2ms
+ * for the identical set shared (`baseline/mount`) — six times the cost of the first fill, for
+ * stylesheets that are all the same.
+ *
+ * Extensions are descriptors, not instances: a `StateField` or `ViewPlugin` in a shared array is
+ * still instantiated per view, so sharing changes nothing but the identity CodeMirror dedupes on.
+ */
+export const createBlockExtensions = ({
+  registry,
+  editable = false,
+  themeMode = 'light',
+  setWidgets,
+}: ItemExtensionOptions = {}): Extension[] => [
+  ...sharedExtensions(registry, editable, themeMode),
+  // The one part that cannot be shared: the callback that hands this item's widgets back to it.
+  ...(registry ? [xmlTags({ registry, setWidgets: setWidgets ?? (() => {}), bookmarks: ['prompt'] })] : []),
+];
+
+/** Registries are compared by identity, so a feed's single registry is a single cache scope. */
+const NO_REGISTRY = {};
+
+const cache = new WeakMap<object, Map<string, Extension[]>>();
+
+const sharedExtensions = (
+  registry: XmlWidgetRegistry | undefined,
+  editable: boolean,
+  themeMode: 'light' | 'dark',
+): Extension[] => {
+  const scope = registry ?? NO_REGISTRY;
+  let byVariant = cache.get(scope);
+  if (!byVariant) {
+    byVariant = new Map();
+    cache.set(scope, byVariant);
+  }
+
+  const key = `${editable}:${themeMode}`;
+  let extensions = byVariant.get(key);
+  if (!extensions) {
+    extensions = build(registry, editable, themeMode);
+    byVariant.set(key, extensions);
+  }
+
+  return extensions;
+};
+
+const build = (registry: XmlWidgetRegistry | undefined, editable: boolean, themeMode: 'light' | 'dark'): Extension[] =>
+  [
+    createBasicExtensions({ readOnly: !editable, editable, lineWrapping: true }),
+    createThemeExtensions({ themeMode }),
+    // A registry changes how the document is *parsed*, not only how it is decorated: registered
+    // tags have to survive as single blocks through the markdown parser before `xmlTags` can
+    // replace them, and without that they render as the literal angle brackets they are.
+    registry ? extendedMarkdown({ registry }) : createMarkdownExtensions(),
+    registry && xmlFormatting({ skip: ['prompt'] }),
+    decorateMarkdown(),
+    // The tags are hidden but the prompt is NOT framed here: the frame is chrome's, which also
+    // owns the rewind toolbar under it. Styling it in both places drew the border twice.
+    registry?.prompt && xmlBlockDecoration({ tag: 'prompt', hideTags: true }),
+    highlights,
+    highlightTheme,
+  ].filter(Boolean) as Extension[];

package/src/components/Block/highlight.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { StateEffect, StateField } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView } from '@codemirror/view';
+
+/** Ranges to highlight, as [from, to) offsets into the item's document. */
+export type HighlightRange = readonly [number, number];
+
+export const setHighlights = StateEffect.define<readonly HighlightRange[]>();
+
+const mark = Decoration.mark({ class: 'dx-feed-hit' });
+
+const clamp = (offset: number, length: number) => Math.max(0, Math.min(offset, length));
+
+/**
+ * Highlights pushed in from the model.
+ *
+ * Search runs over the feed's projection rather than per-view (most messages are never mounted), so
+ * the item receives ranges instead of owning search state.
+ */
+export const highlights = StateField.define<DecorationSet>({
+  create: () => Decoration.none,
+  update: (value, tr) => {
+    for (const effect of tr.effects) {
+      if (effect.is(setHighlights)) {
+        const length = tr.state.doc.length;
+        return Decoration.set(
+          effect.value
+            // Clamp against the current document at both ends: a hit computed on the model can
+            // outrun a view whose streaming tail has not arrived yet, and a decoration outside
+            // `[0, length]` throws rather than being ignored.
+            .map(([from, to]) => [clamp(from, length), clamp(to, length)] as const)
+            .filter(([from, to]) => from < to)
+            .map(([from, to]) => mark.range(from, to)),
+          true,
+        );
+      }
+    }
+
+    return tr.docChanged ? value.map(tr.changes) : value;
+  },
+  provide: (field) => EditorView.decorations.from(field),
+});
+
+export const highlightTheme = EditorView.baseTheme({
+  '.dx-feed-hit': {
+    backgroundColor: 'var(--dx-accentFill)',
+    color: 'var(--dx-accentFillText)',
+    borderRadius: '2px',
+  },
+});

package/src/components/Block/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './selection-group';
+export * from './highlight';
+export * from './widget-state';
+
+export * from './HtmlBlock';
+export * from './MarkdownBlock';

package/src/components/Block/selection-group.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type EditorView } from '@codemirror/view';
+import { createContext, useContext, useMemo } from 'react';
+
+/**
+ * Coordinates selection across the items of one feed.
+ *
+ * Each item is its own editor with its own selection state, and `drawSelection` paints that state
+ * whether or not the view has focus — so without a coordinator every message the reader has ever
+ * selected in stays highlighted at once. The feed has one selection, so claiming it in one item
+ * collapses it everywhere else.
+ */
+export type SelectionGroup = {
+  /** Adds a view to the group; returns the disposer. */
+  register: (view: EditorView) => () => void;
+  /** Makes `view` the sole owner of the feed's selection. */
+  claim: (view: EditorView) => void;
+};
+
+/** Creates a group; one per feed, provided to its items by `MessageList.Root`. */
+export const createSelectionGroup = (): SelectionGroup => {
+  const views = new Set<EditorView>();
+
+  return {
+    register: (view) => {
+      views.add(view);
+      return () => views.delete(view);
+    },
+
+    claim: (view) => {
+      for (const other of views) {
+        if (other === view || other.state.selection.main.empty) {
+          continue;
+        }
+        // Collapsing re-enters this listener for `other`, but with an empty selection, which claims
+        // nothing — so the cascade terminates after one pass.
+        other.dispatch({ selection: { anchor: 0 } });
+      }
+    },
+  };
+};
+
+export const SelectionGroupContext = createContext<SelectionGroup | undefined>(undefined);
+
+/** The enclosing feed's selection group, or a private one when an item is used standalone. */
+export const useSelectionGroup = (): SelectionGroup => {
+  const provided = useContext(SelectionGroupContext);
+  const fallback = useMemo(createSelectionGroup, []);
+  return provided ?? fallback;
+};