@dxos/react-ui-attention 0.9.1-staging.ee54ba693a → 0.11.0

package/src/{view-state → core}/backends.ts

@@ -2,30 +2,33 @@
 // Copyright 2026 DXOS.org
 //
 
-import { Atom, type Registry } from '@effect-atom/atom-react';
+import { Atom, type Registry } from '@effect-atom/atom';
 import * as Schema from 'effect/Schema';
 
-import { type AspectDef, type BackendName, type ViewStateBackend } from './view-state';
+import { ViewState } from '../types';
 
-// Only the stable `key` string is needed to form the map key; avoids variance issues with AspectDef<T>.
+// Only the stable `key` string is needed to form the map key; avoids variance issues with Aspect<T>.
 const cacheKey = (aspect: { key: string }, contextId: string) => `${aspect.key}:${contextId}`;
 
 /** In-memory backend: state is ephemeral and scoped to the session (never persisted). */
-export class MemoryBackend implements ViewStateBackend {
+export class MemoryBackend implements ViewState.Backend {
   readonly #atoms = new Map<string, Atom.Writable<unknown>>();
 
-  atom<T>(aspect: AspectDef<T>, contextId: string): Atom.Writable<T> {
+  atom<T, Encoded>(aspect: ViewState.Aspect<T, Encoded>, contextId: string): Atom.Writable<T> {
     const key = cacheKey(aspect, contextId);
     let atom = this.#atoms.get(key);
     if (!atom) {
-      atom = Atom.make<unknown>(aspect.defaultValue());
+      // `keepAlive` pins the node so a written value survives for the session; without it the registry
+      // sweeps the unsubscribed atom back to its default, dropping state that no UI happens to observe
+      // (e.g. a selection read on-demand by an agent tool rather than a live subscriber).
+      atom = Atom.make<unknown>(aspect.defaultValue()).pipe(Atom.keepAlive);
       this.#atoms.set(key, atom);
     }
     // Cast bridges the per-aspect value type erased by the shared atom map; safe by construction.
     return atom as Atom.Writable<T>;
   }
 
-  contexts<T>(aspect: AspectDef<T>): string[] {
+  contexts<T, Encoded>(aspect: ViewState.Aspect<T, Encoded>): string[] {
     const prefix = `${aspect.key}:`;
     return [...this.#atoms.keys()].filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
   }
@@ -52,14 +55,14 @@ export interface LocalBackendOptions {
 }
 
 /** localStorage-backed backend: seeds atoms from storage, persists on set, syncs across tabs. */
-export class LocalBackend implements ViewStateBackend {
+export class LocalBackend implements ViewState.Backend {
   readonly #registry: Registry.Registry;
   // Absent in non-browser contexts (SSR/tests without injection); the backend then degrades to
   // ephemeral, in-memory behaviour rather than crashing on a missing `localStorage`.
   readonly #storage: Storage | undefined;
   readonly #atoms = new Map<string, Atom.Writable<unknown>>();
   // Reverse map: storage key -> (aspect, contextId) so `storage` events can target the right atom.
-  readonly #byStorageKey = new Map<string, { aspect: AspectDef<unknown>; contextId: string }>();
+  readonly #byStorageKey = new Map<string, { aspect: ViewState.Aspect<unknown, unknown>; contextId: string }>();
   #storageListener?: (event: StorageEvent) => void;
 
   constructor({ registry, storage }: LocalBackendOptions) {
@@ -80,26 +83,28 @@ export class LocalBackend implements ViewStateBackend {
     }
   }
 
-  atom<T>(aspect: AspectDef<T>, contextId: string): Atom.Writable<T> {
+  atom<T, Encoded>(aspect: ViewState.Aspect<T, Encoded>, contextId: string): Atom.Writable<T> {
     const key = cacheKey(aspect, contextId);
     let atom = this.#atoms.get(key);
     if (!atom) {
       const storageKey = storageKeyFor(aspect, contextId);
-      atom = Atom.make<unknown>(this.#read(aspect, storageKey));
+      // `keepAlive` pins the node so the in-memory value stays consistent with storage without a live
+      // subscriber; otherwise the registry sweeps the unsubscribed atom back to its creation-time seed.
+      atom = Atom.make<unknown>(this.#read(aspect, storageKey)).pipe(Atom.keepAlive);
       this.#atoms.set(key, atom);
       // Cast erases the per-aspect value type so the reverse map can hold aspects of any `T`; the
       // stored aspect is only used to re-read/decode its own value, so the erasure is safe.
-      this.#byStorageKey.set(storageKey, { aspect: aspect as AspectDef<unknown>, contextId });
+      this.#byStorageKey.set(storageKey, { aspect: aspect as ViewState.Aspect<unknown, unknown>, contextId });
     }
     // Cast bridges the per-aspect value type erased by the shared atom map; safe by construction.
     return atom as Atom.Writable<T>;
   }
 
-  persist<T>(aspect: AspectDef<T>, contextId: string, value: T): void {
+  persist<T, Encoded>(aspect: ViewState.Aspect<T, Encoded>, contextId: string, value: T): void {
     this.#storage?.setItem(storageKeyFor(aspect, contextId), JSON.stringify(Schema.encodeSync(aspect.schema)(value)));
   }
 
-  contexts<T>(aspect: AspectDef<T>): string[] {
+  contexts<T, Encoded>(aspect: ViewState.Aspect<T, Encoded>): string[] {
     if (!this.#storage) {
       // No persistent storage: fall back to the in-memory atoms (mirrors `atom()`'s ephemeral path).
       const prefix = `${aspect.key}:`;
@@ -125,7 +130,7 @@ export class LocalBackend implements ViewStateBackend {
     this.#byStorageKey.clear();
   }
 
-  #read<T>(aspect: AspectDef<T>, storageKey: string): T {
+  #read<T, Encoded>(aspect: ViewState.Aspect<T, Encoded>, storageKey: string): T {
     const raw = this.#storage?.getItem(storageKey);
     if (raw == null) {
       return aspect.defaultValue();
@@ -133,13 +138,15 @@ export class LocalBackend implements ViewStateBackend {
     try {
       return Schema.decodeUnknownSync(aspect.schema)(JSON.parse(raw));
     } catch {
-      // Tolerate stale/corrupt entries (e.g. a prior schema shape) by falling back to the default.
+      // Tolerate stale/corrupt entries (e.g., a prior schema shape) by falling back to the default.
       return aspect.defaultValue();
     }
   }
 }
 
-export const createDefaultBackends = (registry: Registry.Registry): Record<BackendName, ViewStateBackend> => ({
+export const createDefaultBackends = (
+  registry: Registry.Registry,
+): Record<ViewState.BackendName, ViewState.Backend> => ({
   memory: new MemoryBackend(),
   local: new LocalBackend({ registry }),
 });

package/src/{view-state → core}/index.ts

@@ -2,5 +2,4 @@
 // Copyright 2026 DXOS.org
 //
 
-export * from './view-state';
 export * from './backends';

package/src/hooks/index.ts

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

package/src/{useArticleKeyboardNavigation.ts → hooks/useArticleKeyboardNavigation.ts}

@@ -6,7 +6,7 @@ import { useEffect, useMemo } from 'react';
 
 import { Keyboard, nestKeyboardContext } from '@dxos/keyboard';
 
-import { useAttention } from './components';
+import { useAttention } from '../components';
 
 /**
  * Compute the id to select after pressing 'j' (delta = 1) or 'k' (delta = -1).

package/src/index.ts

@@ -2,8 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './attention';
 export * from './components';
-export * from './selection';
-export * from './useArticleKeyboardNavigation';
-export * from './view-state';
+export * from './core';
+export * from './hooks';
+export * from './types';

package/src/testing/decorators/withAttention.ts

@@ -6,8 +6,8 @@ import { Registry, RegistryContext } from '@effect-atom/atom-react';
 import { type Decorator } from '@storybook/react';
 import { createElement, useMemo } from 'react';
 
-import { AttentionManager } from '../../attention';
 import { RootAttentionProvider, ViewStateProvider } from '../../components';
+import { Attention } from '../../types';
 
 /**
  * Storybook decorator that provides attention context.
@@ -17,7 +17,7 @@ export const withAttention = (initialAttendedId?: string): Decorator => {
   return (Story) => {
     const registry = useMemo(() => Registry.make(), []);
     const attention = useMemo(
-      () => (initialAttendedId ? new AttentionManager(registry, [initialAttendedId]) : undefined),
+      () => (initialAttendedId ? new Attention.AttentionManager(registry, [initialAttendedId]) : undefined),
       [registry],
     );
 

package/src/{attention.test.ts → types/Attention.test.ts}

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Registry } from '@effect-atom/atom-react';
+import { Registry } from '@effect-atom/atom';
 import { describe, test } from 'vitest';
 
 import {
@@ -13,7 +13,7 @@ import {
   getSegmentId,
   isLinkedSegment,
   linkedSegment,
-} from './attention';
+} from './Attention';
 
 describe('AttentionManager', () => {
   test('takes an initial attended id', ({ expect }) => {

package/src/{attention.ts → types/Attention.ts}

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Atom, type Registry } from '@effect-atom/atom-react';
+import { Atom, type Registry } from '@effect-atom/atom';
 
 export type Attention = {
   hasAttention: boolean;
@@ -159,6 +159,12 @@ export class AttentionManager {
   }
 }
 
+/** The attribute marking an element as attendable, carrying its qualified id. */
+export const ATTENDABLE_ATTRIBUTE = 'data-attendable-id';
+
+/** Selector matching any attendable element. */
+export const ATTENDABLE_SELECTOR = `[${ATTENDABLE_ATTRIBUTE}]`;
+
 /**
  * Accumulates all attendable IDs between the element provided and the root, inclusive.
  * Each `data-attendable-id` value is treated as a single qualified ID (no splitting).
@@ -167,7 +173,7 @@ export const getAttendables = (selector: string, cursor: Element, acc: string[]
   // Find the closest element with `data-attendable-id`, if any; start from cursor and move up the DOM tree.
   const closestAttendable = cursor.closest(selector);
   if (closestAttendable) {
-    const attendableId = closestAttendable.getAttribute('data-attendable-id');
+    const attendableId = closestAttendable.getAttribute(ATTENDABLE_ATTRIBUTE);
     if (!attendableId) {
       // This has an id of an aria-controls elsewhere on the page, move cursor to that trigger.
       const trigger = document.querySelector(`[aria-controls="${closestAttendable.getAttribute('id')}"]`);
@@ -185,6 +191,15 @@ export const getAttendables = (selector: string, cursor: Element, acc: string[]
   return [...new Set(acc)];
 };
 
+/**
+ * The outermost attendable ancestor of `element` — the root of any nested attendables (e.g. a section
+ * within a stack). Structural (real DOM ancestry), so it is independent of what currently has attention.
+ * Resolve it from an in-DOM element: a portaled subtree (a menu, a popover) is not under its own
+ * attendable, so walk from the trigger or anchor instead.
+ */
+export const getRootAttendableId = (element: Element): string | undefined =>
+  getAttendables(ATTENDABLE_SELECTOR, element).at(-1);
+
 export type AttendableId = { attendableId?: string };
 
 export type Related = { related?: boolean };

package/src/types/Selection.test.ts

@@ -0,0 +1,100 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom';
+import { describe, test } from 'vitest';
+
+import { createDefaultBackends } from '../core';
+import * as Selection from './Selection';
+import { Manager } from './ViewState';
+
+describe('selection helpers', () => {
+  test('aspect declares a memory-backed aspect', ({ expect }) => {
+    expect(Selection.aspect.key).toEqual('selection');
+    expect(Selection.aspect.backend).toEqual('memory');
+    expect(Selection.aspect.defaultValue()).toEqual({ mode: 'multi', ids: [] });
+  });
+
+  test('resolveSelection extracts the value for the requested mode', ({ expect }) => {
+    expect(Selection.resolve({ mode: 'single', id: 'x' }, 'single')).toEqual('x');
+    expect(Selection.resolve({ mode: 'multi', ids: ['a', 'b'] }, 'multi')).toEqual(['a', 'b']);
+    expect(Selection.resolve({ mode: 'range', from: 'a', to: 'b' }, 'range')).toEqual({ from: 'a', to: 'b' });
+    expect(Selection.resolve({ mode: 'multi-range', ranges: [{ from: 'a', to: 'b' }] }, 'multi-range')).toEqual([
+      { from: 'a', to: 'b' },
+    ]);
+  });
+
+  test('resolveSelection returns the requested-mode default on mismatch or undefined', ({ expect }) => {
+    expect(Selection.resolve(undefined, 'single')).toBeUndefined();
+    expect(Selection.resolve(undefined, 'multi')).toEqual([]);
+    // Stored value is the default multi but a single reader asks — yields the single default.
+    expect(Selection.resolve({ mode: 'multi', ids: [] }, 'single')).toBeUndefined();
+    expect(Selection.resolve({ mode: 'range' }, 'range')).toBeUndefined();
+  });
+
+  test('toggleSelection adds/removes within a multi selection', ({ expect }) => {
+    expect(Selection.toggle({ mode: 'multi', ids: ['a'] }, 'b')).toEqual({ mode: 'multi', ids: ['a', 'b'] });
+    expect(Selection.toggle({ mode: 'multi', ids: ['a', 'b'] }, 'b')).toEqual({ mode: 'multi', ids: ['a'] });
+    // Tolerate a non-multi current value by starting fresh.
+    expect(Selection.toggle({ mode: 'single', id: 'x' }, 'b')).toEqual({ mode: 'multi', ids: ['b'] });
+  });
+});
+
+describe('toAnchors', () => {
+  test('undefined selection yields no anchors', ({ expect }) => {
+    expect(Selection.toAnchors(undefined)).toEqual([]);
+  });
+
+  test('single mode yields the id when set', ({ expect }) => {
+    expect(Selection.toAnchors({ mode: 'single', id: 'a' })).toEqual(['a']);
+    expect(Selection.toAnchors({ mode: 'single' })).toEqual([]);
+  });
+
+  test('multi mode yields all ids', ({ expect }) => {
+    expect(Selection.toAnchors({ mode: 'multi', ids: ['a', 'b'] })).toEqual(['a', 'b']);
+  });
+
+  test('range mode yields a cursor-pair anchor when complete', ({ expect }) => {
+    expect(Selection.toAnchors({ mode: 'range', from: 'x', to: 'y' })).toEqual(['x:y']);
+    expect(Selection.toAnchors({ mode: 'range', from: 'x' })).toEqual([]);
+  });
+
+  test('multi-range mode yields one anchor per range', ({ expect }) => {
+    expect(
+      Selection.toAnchors({
+        mode: 'multi-range',
+        ranges: [
+          { from: 'a', to: 'b' },
+          { from: 'c', to: 'd' },
+        ],
+      }),
+    ).toEqual(['a:b', 'c:d']);
+  });
+});
+
+describe('getValue', () => {
+  const makeManager = () => {
+    const registry = Registry.make();
+    return new Manager({ registry, backends: createDefaultBackends(registry) });
+  };
+
+  test('unions multi-selected ids across every context', ({ expect }) => {
+    const manager = makeManager();
+    manager.set(Selection.aspect, 'ctx-a', { mode: 'multi', ids: ['a1', 'a2'] });
+    manager.set(Selection.aspect, 'ctx-b', { mode: 'multi', ids: ['a2', 'b1'] });
+    // Single-mode contexts contribute nothing to the set.
+    manager.set(Selection.aspect, 'ctx-c', { mode: 'single', id: 'c1' });
+    expect(Selection.getValue(manager)).toEqual(new Set(['a1', 'a2', 'b1']));
+  });
+
+  test('seeds the set with the optional explicit contextId', ({ expect }) => {
+    const manager = makeManager();
+    manager.set(Selection.aspect, 'ctx-a', { mode: 'multi', ids: ['a1'] });
+    expect(Selection.getValue(manager, 'explicit')).toEqual(new Set(['explicit', 'a1']));
+  });
+
+  test('returns an empty set when nothing is selected', ({ expect }) => {
+    expect(Selection.getValue(makeManager())).toEqual(new Set());
+  });
+});

package/src/{selection.ts → types/Selection.ts}

@@ -5,11 +5,11 @@
 import * as Match from 'effect/Match';
 import * as Schema from 'effect/Schema';
 
-import { type AspectDef, type ViewStateManager, defineViewState } from './view-state';
+import { type Aspect, type Manager, define } from './ViewState';
 
 export type SelectionMode = 'single' | 'multi' | 'range' | 'multi-range';
 
-export const SelectionSchema = Schema.Union(
+export const Selection = Schema.Union(
   Schema.Struct({
     mode: Schema.Literal('single'),
     id: Schema.optional(Schema.String),
@@ -29,9 +29,9 @@ export const SelectionSchema = Schema.Union(
   }).pipe(Schema.mutable),
 ).pipe(Schema.mutable);
 
-export type Selection = Schema.Schema.Type<typeof SelectionSchema>;
+export type Selection = Schema.Schema.Type<typeof Selection>;
 
-export const defaultSelection = Match.type<SelectionMode>().pipe(
+export const defaultValue = Match.type<SelectionMode>().pipe(
   Match.withReturnType<Selection>(),
   Match.when('single', () => ({ mode: 'single' })),
   Match.when('multi', () => ({ mode: 'multi', ids: [] })),
@@ -40,7 +40,7 @@ export const defaultSelection = Match.type<SelectionMode>().pipe(
   Match.exhaustive,
 );
 
-export type SelectionResult<T extends SelectionMode> = T extends 'single'
+export type Result<T extends SelectionMode> = T extends 'single'
   ? string | undefined
   : T extends 'multi'
     ? string[]
@@ -51,10 +51,10 @@ export type SelectionResult<T extends SelectionMode> = T extends 'single'
         : never;
 
 /** Selection state for a context, stored in memory (ephemeral, per-device session). */
-export const selectionAspect: AspectDef<Selection> = defineViewState<Selection>({
+export const aspect: Aspect<Selection> = define<Selection>({
   key: 'selection',
   backend: 'memory',
-  schema: SelectionSchema,
+  schema: Selection,
   defaultValue: () => ({ mode: 'multi', ids: [] }),
 });
 
@@ -62,11 +62,8 @@ export const selectionAspect: AspectDef<Selection> = defineViewState<Selection>(
  * Extract the typed result for `mode` from a stored selection value, returning the requested
  * mode's default when the stored value is absent or holds a different mode.
  */
-export const resolveSelection = <T extends SelectionMode>(
-  selection: Selection | undefined,
-  mode: T,
-): SelectionResult<T> => {
-  const value = selection?.mode === mode ? selection : defaultSelection(mode);
+export const resolve = <T extends SelectionMode>(selection: Selection | undefined, mode: T): Result<T> => {
+  const value = selection?.mode === mode ? selection : defaultValue(mode);
   // Cast required because TypeScript cannot relate the `Match` result to the generic `T`.
   return Match.type<Selection>().pipe(
     Match.when({ mode: 'single' }, (s) => s.id),
@@ -74,25 +71,38 @@ export const resolveSelection = <T extends SelectionMode>(
     Match.when({ mode: 'range' }, (s) => (s.from && s.to ? { from: s.from, to: s.to } : undefined)),
     Match.when({ mode: 'multi-range' }, (s) => s.ranges),
     Match.exhaustive,
-  )(value) as SelectionResult<T>;
+  )(value) as Result<T>;
 };
 
 /** Toggle `id` within a multi selection; resets to a multi selection if the current value differs. */
-export const toggleSelection = (selection: Selection | undefined, id: string): Selection => {
+export const toggle = (selection: Selection | undefined, id: string): Selection => {
   const ids = selection?.mode === 'multi' ? selection.ids : [];
   return { mode: 'multi', ids: ids.includes(id) ? ids.filter((existing) => existing !== id) : [...ids, id] };
 };
 
+/** Anchor strings for a selection: ids for single/multi modes, `"${from}:${to}"` cursor pairs for range modes. */
+export const toAnchors = (selection: Selection | undefined): string[] =>
+  selection == null
+    ? []
+    : Match.type<Selection>().pipe(
+        Match.when({ mode: 'single' }, (value) => (value.id ? [value.id] : [])),
+        Match.when({ mode: 'multi' }, (value) => [...value.ids]),
+        Match.when({ mode: 'range' }, (value) => (value.from && value.to ? [`${value.from}:${value.to}`] : [])),
+        Match.when({ mode: 'multi-range' }, (value) => value.ranges.map((range) => `${range.from}:${range.to}`)),
+        Match.exhaustive,
+      )(selection);
+
 /** Union of all multi-selected ids across every selection context, plus an optional explicit id. */
-export const getSelectionSet = (manager: ViewStateManager, contextId?: string): Set<string> => {
+export const getValue = (manager: Manager, contextId?: string): Set<string> => {
   const ids = new Set<string>(contextId ? [contextId] : []);
-  for (const context of manager.contexts(selectionAspect)) {
-    const selection = manager.get(selectionAspect, context);
+  for (const context of manager.contexts(aspect)) {
+    const selection = manager.get(aspect, context);
     if (selection.mode === 'multi') {
       for (const id of selection.ids) {
         ids.add(id);
       }
     }
   }
+
   return ids;
 };

package/src/{view-state/view-state.test.ts → types/ViewState.test.ts}

@@ -2,24 +2,24 @@
 // Copyright 2026 DXOS.org
 //
 
-import { Registry } from '@effect-atom/atom-react';
+import { Registry } from '@effect-atom/atom';
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { createDefaultBackends } from './backends';
-import { ViewStateManager, defineViewState } from './view-state';
+import { createDefaultBackends } from '../core';
+import { Manager, define } from './ViewState';
 
-const Counter = defineViewState({
+const Counter = define({
   key: 'counter',
   backend: 'memory',
   schema: Schema.Struct({ value: Schema.Number }).pipe(Schema.mutable),
   defaultValue: () => ({ value: 0 }),
 });
 
-describe('ViewStateManager', () => {
+describe('Manager', () => {
   const make = () => {
     const registry = Registry.make();
-    return new ViewStateManager({ registry, backends: createDefaultBackends(registry) });
+    return new Manager({ registry, backends: createDefaultBackends(registry) });
   };
 
   test('returns the aspect default for an unwritten context', ({ expect }) => {

package/src/types/ViewState.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Atom, type Registry } from '@effect-atom/atom';
+import type * as Schema from 'effect/Schema';
+
+/**
+ * Persistence backend identifier. `personal` (ECHO/personal-space) is reserved for a future backend.
+ */
+export type BackendName = 'memory' | 'local';
+
+/**
+ * Declares a kind of per-context UI state. The value type `T` and its persisted wire type `Encoded`
+ * are inferred from the schema; `Encoded` defaults to `T` for the common no-transform case.
+ */
+export interface Aspect<T, Encoded = T> {
+  readonly key: string;
+  readonly backend: BackendName;
+  readonly schema: Schema.Schema<T, Encoded>;
+  readonly defaultValue: () => T;
+}
+
+/**
+ * Identity helper that pins the value type from the schema while keeping the literal `key`/`backend`.
+ * Declares an aspect of per-context UI state (selection, scroll, view mode, split) read/written via
+ * {@link Manager} — through `useViewState`/`useViewStateActions` in React or the
+ * `AttentionCapabilities.ViewState` capability in operations. Durability is the `backend`'s: `local`
+ * survives reloads (best-effort — degrades to in-memory when storage is blocked), `memory` is
+ * session-only.
+ *
+ * @idiom org.dxos.react-ui-attention.viewState
+ *   applies: Holding per-context UI state (selection, view mode, scroll, split) that survives navigation (and reloads with the `local` backend)
+ *   instead-of: ad-hoc `useState` that resets on remount, or stuffing per-context state into the plugin Settings store
+ *   uses: {@link define}, {@link Manager}
+ *   related: org.dxos.effect.kvsStore
+ */
+export const define = <T, Encoded = T>(def: Aspect<T, Encoded>): Aspect<T, Encoded> => def;
+
+/**
+ * A backend produces a reactive, writable atom for each `(aspect, contextId)` pair. Backends may
+ * hydrate asynchronously (an ECHO backend would), yielding `aspect.defaultValue()` until loaded;
+ * the memory and local backends resolve synchronously.
+ */
+export interface Backend {
+  /** Stable atom for the pair; created (and seeded) on first access, cached thereafter. */
+  atom: <T, Encoded>(aspect: Aspect<T, Encoded>, contextId: string) => Atom.Writable<T>;
+  /** Persist a value after the atom is updated. No-op for in-memory backends. */
+  persist?: <T, Encoded>(aspect: Aspect<T, Encoded>, contextId: string, value: T) => void;
+  /** Context ids that currently hold a value for the aspect. */
+  contexts: <T, Encoded>(aspect: Aspect<T, Encoded>) => string[];
+  /** Release listeners/timers (used by tests; app-lifetime managers do not call this). */
+  dispose?: () => void;
+}
+
+export interface ManagerOptions {
+  readonly registry: Registry.Registry;
+  readonly backends: Record<BackendName, Backend>;
+}
+
+/**
+ * Routes per-context UI state to the backend declared by each aspect. Reads/writes go through the
+ * effect-atom registry so React hooks and graph atoms observe changes uniformly.
+ */
+export class Manager {
+  readonly #registry: Registry.Registry;
+  readonly #backends: Record<BackendName, Backend>;
+
+  constructor({ registry, backends }: ManagerOptions) {
+    this.#registry = registry;
+    this.#backends = backends;
+  }
+
+  /** Reactive atom for `(aspect, contextId)`; pass to `registry.get` inside derived atoms/hooks. */
+  atom<T, Encoded>(aspect: Aspect<T, Encoded>, contextId: string): Atom.Writable<T> {
+    return this.#backends[aspect.backend].atom(aspect, contextId);
+  }
+
+  get<T, Encoded>(aspect: Aspect<T, Encoded>, contextId: string): T {
+    return this.#registry.get(this.atom(aspect, contextId));
+  }
+
+  set<T, Encoded>(aspect: Aspect<T, Encoded>, contextId: string, value: T): void {
+    const backend = this.#backends[aspect.backend];
+    this.#registry.set(backend.atom(aspect, contextId), value);
+    backend.persist?.(aspect, contextId, value);
+  }
+
+  update<T, Encoded>(aspect: Aspect<T, Encoded>, contextId: string, fn: (prev: T) => T): void {
+    this.set(aspect, contextId, fn(this.get(aspect, contextId)));
+  }
+
+  subscribe<T, Encoded>(aspect: Aspect<T, Encoded>, contextId: string, cb: (value: T) => void): () => void {
+    const atom = this.atom(aspect, contextId);
+    return this.#registry.subscribe(atom, () => cb(this.#registry.get(atom)));
+  }
+
+  contexts<T, Encoded>(aspect: Aspect<T, Encoded>): string[] {
+    return this.#backends[aspect.backend].contexts(aspect);
+  }
+}

package/src/types/index.ts

@@ -1,10 +1,11 @@
 //
-// Copyright 2024 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
-// UI-free re-exports of @dxos/react-ui-attention. Importing from here does not
-// pull in React components, so it is safe to use from operations, schemas, and
-// other non-DOM code that only needs the data model and pure helpers.
-export * from '../attention';
-export * from '../selection';
-export * from '../view-state';
+// A UI-free entrypoint: the attention/selection/view state definitions with no React attached, so
+// operation handlers and app-graph builders running under node or bun can use them without pulling
+// the components.
+
+export * as Attention from './Attention';
+export * as Selection from './Selection';
+export * as ViewState from './ViewState';