@dxos/react-ui-attention 0.8.4-staging.60fe92afc8 → 0.9.1-main.c7dcc2e112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-attention",
-  "version": "0.8.4-staging.60fe92afc8",
+  "version": "0.9.1-main.c7dcc2e112",
   "description": "Signifier components and providers for attention system.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -47,30 +47,32 @@
     "@radix-ui/react-slot": "1.1.2",
     "@radix-ui/react-use-controllable-state": "1.1.0",
     "effect": "3.21.3",
-    "@dxos/echo": "0.8.4-staging.60fe92afc8",
-    "@dxos/keyboard": "0.8.4-staging.60fe92afc8",
-    "@dxos/invariant": "0.8.4-staging.60fe92afc8",
-    "@dxos/log": "0.8.4-staging.60fe92afc8",
-    "@dxos/react-hooks": "0.8.4-staging.60fe92afc8",
-    "@dxos/util": "0.8.4-staging.60fe92afc8"
+    "@dxos/echo": "0.9.1-main.c7dcc2e112",
+    "@dxos/util": "0.9.1-main.c7dcc2e112",
+    "@dxos/log": "0.9.1-main.c7dcc2e112",
+    "@dxos/keyboard": "0.9.1-main.c7dcc2e112",
+    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
+    "@dxos/react-hooks": "0.9.1-main.c7dcc2e112"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "~19.2.7",
     "@types/react-dom": "~19.2.3",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
     "vite": "^8.0.16",
-    "@dxos/react-ui": "0.8.4-staging.60fe92afc8",
-    "@dxos/random": "0.8.4-staging.60fe92afc8",
-    "@dxos/storybook-utils": "0.8.4-staging.60fe92afc8",
-    "@dxos/ui-theme": "0.8.4-staging.60fe92afc8"
+    "@dxos/random": "0.9.1-main.c7dcc2e112",
+    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
+    "@dxos/storybook-utils": "0.9.1-main.c7dcc2e112",
+    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112"
   },
   "peerDependencies": {
     "effect": "3.21.3",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/react-ui": "0.8.4-staging.60fe92afc8",
-    "@dxos/ui-theme": "0.8.4-staging.60fe92afc8"
+    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112",
+    "@dxos/react-ui": "0.9.1-main.c7dcc2e112"
   },
   "publishConfig": {
     "access": "public"

package/src/components/ViewStateProvider/ViewStateProvider.test.tsx

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry, RegistryContext } from '@effect-atom/atom-react';
+import { act, renderHook } from '@testing-library/react';
+import React, { type PropsWithChildren } from 'react';
+import { describe, test } from 'vitest';
+
+import { ViewStateManager, createDefaultBackends } from '../../view-state';
+import { ViewStateProvider, useSelection, useSelectionActions } from './ViewStateProvider';
+
+describe('useSelection / useSelectionActions', () => {
+  test('single select updates the resolved value', ({ expect }) => {
+    const registry = Registry.make();
+    const manager = new ViewStateManager({ registry, backends: createDefaultBackends(registry) });
+    const Wrapper = wrapper(manager, registry);
+    const { result: value } = renderHook(() => useSelection('ctx', 'single'), { wrapper: Wrapper });
+    const { result: actions } = renderHook(() => useSelectionActions('ctx'), { wrapper: Wrapper });
+    expect(value.current).toBeUndefined();
+    act(() => actions.current.single('item-1'));
+    expect(value.current).toEqual('item-1');
+  });
+
+  test('toggle within multi selection', ({ expect }) => {
+    const registry = Registry.make();
+    const manager = new ViewStateManager({ registry, backends: createDefaultBackends(registry) });
+    const Wrapper = wrapper(manager, registry);
+    const { result: value } = renderHook(() => useSelection('ctx', 'multi'), { wrapper: Wrapper });
+    const { result: actions } = renderHook(() => useSelectionActions('ctx'), { wrapper: Wrapper });
+    act(() => actions.current.toggle('a'));
+    act(() => actions.current.toggle('b'));
+    expect(value.current).toEqual(['a', 'b']);
+    act(() => actions.current.toggle('a'));
+    expect(value.current).toEqual(['b']);
+  });
+});
+
+const wrapper =
+  (manager: ViewStateManager, registry: Registry.Registry) =>
+  ({ children }: PropsWithChildren) => (
+    <RegistryContext.Provider value={registry}>
+      <ViewStateProvider manager={manager}>{children}</ViewStateProvider>
+    </RegistryContext.Provider>
+  );

package/src/components/ViewStateProvider/ViewStateProvider.tsx

@@ -0,0 +1,123 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import { createContext } from '@radix-ui/react-context';
+import React, { type PropsWithChildren, useContext, useEffect, useMemo, useState } from 'react';
+
+import { invariant } from '@dxos/invariant';
+import { useDefaultValue } from '@dxos/react-hooks';
+
+import {
+  type SelectionMode,
+  type SelectionResult,
+  resolveSelection,
+  selectionAspect,
+  toggleSelection,
+} from '../../selection';
+import { type AspectDef, ViewStateManager, createDefaultBackends } from '../../view-state';
+
+const VIEW_STATE_NAME = 'ViewState';
+
+type ViewStateContextValue = { manager?: ViewStateManager };
+
+// Default value lets consumers render outside a provider (isolated stories/tests) without throwing;
+// `manager` reads as `undefined` and hooks fall back to aspect defaults / no-op actions.
+const [ViewStateContextProvider, useViewStateContext] = createContext<ViewStateContextValue>(VIEW_STATE_NAME, {
+  manager: undefined,
+});
+
+/** Provides the per-context UI state manager. Replaces the former `SelectionProvider`. */
+export const ViewStateProvider = ({
+  children,
+  manager: managerProp,
+}: PropsWithChildren<{ manager?: ViewStateManager }>) => {
+  const registry = useContext(RegistryContext);
+  const manager = useDefaultValue(
+    managerProp,
+    () => new ViewStateManager({ registry, backends: createDefaultBackends(registry) }),
+  );
+  return <ViewStateContextProvider manager={manager}>{children}</ViewStateContextProvider>;
+};
+
+/** Access the underlying ViewStateManager from context. Throws when used outside a `ViewStateProvider`. */
+export const useViewStateManager = (): ViewStateManager => {
+  const { manager } = useViewStateContext(VIEW_STATE_NAME);
+  invariant(manager, 'useViewStateManager() requires a ViewStateProvider ancestor.');
+  return manager;
+};
+
+/** Reactive read of an aspect value for a context; yields the aspect default when unset or unprovided. */
+export const useViewState = <T,>(aspect: AspectDef<T>, contextId?: string): T => {
+  const { manager } = useViewStateContext(VIEW_STATE_NAME);
+  const [value, setValue] = useState<T>(() =>
+    contextId && manager ? manager.get(aspect, contextId) : aspect.defaultValue(),
+  );
+  useEffect(() => {
+    if (!contextId || !manager) {
+      setValue(aspect.defaultValue());
+      return;
+    }
+    setValue(manager.get(aspect, contextId));
+    return manager.subscribe(aspect, contextId, setValue);
+  }, [manager, aspect, contextId]);
+  return value;
+};
+
+export type UseViewStateActions<T> = {
+  set: (value: T) => void;
+  update: (fn: (prev: T) => T) => void;
+  clear: () => void;
+};
+
+export const useViewStateActions = <T,>(aspect: AspectDef<T>, contextId?: string): UseViewStateActions<T> => {
+  const { manager } = useViewStateContext(VIEW_STATE_NAME);
+  return useMemo<UseViewStateActions<T>>(
+    () => ({
+      set: (value) => {
+        if (contextId) {
+          manager?.set(aspect, contextId, value);
+        }
+      },
+      update: (fn) => {
+        if (contextId) {
+          manager?.update(aspect, contextId, fn);
+        }
+      },
+      clear: () => {
+        if (contextId) {
+          manager?.set(aspect, contextId, aspect.defaultValue());
+        }
+      },
+    }),
+    [manager, aspect, contextId],
+  );
+};
+
+/** Resolved selection value for `contextId` in the requested `mode` (default `multi`). */
+export const useSelection = <T extends SelectionMode>(contextId?: string, mode: T = 'multi' as T): SelectionResult<T> =>
+  resolveSelection(useViewState(selectionAspect, contextId), mode);
+
+export type UseSelectionActions = {
+  single: (id: string) => void;
+  multi: (ids: string[]) => void;
+  range: (from: string, to: string) => void;
+  toggle: (id: string) => void;
+  clear: () => void;
+};
+
+/** Selection mutators for a single context, built on the generic ViewState actions. */
+export const useSelectionActions = (contextId?: string): UseSelectionActions => {
+  const { update, clear } = useViewStateActions(selectionAspect, contextId);
+  return useMemo<UseSelectionActions>(
+    () => ({
+      single: (id) => update(() => ({ mode: 'single', id })),
+      multi: (ids) => update(() => ({ mode: 'multi', ids: [...ids] })),
+      range: (from, to) => update(() => ({ mode: 'range', from, to })),
+      toggle: (id) => update((prev) => toggleSelection(prev, id)),
+      clear,
+    }),
+    [update, clear],
+  );
+};

package/src/components/ViewStateProvider/index.ts

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

package/src/components/index.ts

@@ -4,4 +4,4 @@
 
 export * from './AttentionGlyph';
 export * from './AttentionProvider';
-export * from './SelectionProvider';
+export * from './ViewStateProvider';

package/src/index.ts

@@ -6,3 +6,4 @@ export * from './attention';
 export * from './components';
 export * from './selection';
 export * from './useArticleKeyboardNavigation';
+export * from './view-state';

package/src/selection.test.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom-react';
+import { describe, test } from 'vitest';
+
+import { getSelectionSet, resolveSelection, selectionAspect, toggleSelection } from './selection';
+import { ViewStateManager, createDefaultBackends } from './view-state';
+
+describe('selection helpers', () => {
+  test('selectionAspect declares a memory-backed aspect', ({ expect }) => {
+    expect(selectionAspect.key).toEqual('selection');
+    expect(selectionAspect.backend).toEqual('memory');
+    expect(selectionAspect.defaultValue()).toEqual({ mode: 'multi', ids: [] });
+  });
+
+  test('resolveSelection extracts the value for the requested mode', ({ expect }) => {
+    expect(resolveSelection({ mode: 'single', id: 'x' }, 'single')).toEqual('x');
+    expect(resolveSelection({ mode: 'multi', ids: ['a', 'b'] }, 'multi')).toEqual(['a', 'b']);
+    expect(resolveSelection({ mode: 'range', from: 'a', to: 'b' }, 'range')).toEqual({ from: 'a', to: 'b' });
+    expect(resolveSelection({ 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(resolveSelection(undefined, 'single')).toBeUndefined();
+    expect(resolveSelection(undefined, 'multi')).toEqual([]);
+    // Stored value is the default multi but a single reader asks — yields the single default.
+    expect(resolveSelection({ mode: 'multi', ids: [] }, 'single')).toBeUndefined();
+    expect(resolveSelection({ mode: 'range' }, 'range')).toBeUndefined();
+  });
+
+  test('toggleSelection adds/removes within a multi selection', ({ expect }) => {
+    expect(toggleSelection({ mode: 'multi', ids: ['a'] }, 'b')).toEqual({ mode: 'multi', ids: ['a', 'b'] });
+    expect(toggleSelection({ mode: 'multi', ids: ['a', 'b'] }, 'b')).toEqual({ mode: 'multi', ids: ['a'] });
+    // Tolerate a non-multi current value by starting fresh.
+    expect(toggleSelection({ mode: 'single', id: 'x' }, 'b')).toEqual({ mode: 'multi', ids: ['b'] });
+  });
+});
+
+describe('getSelectionSet', () => {
+  const makeManager = () => {
+    const registry = Registry.make();
+    return new ViewStateManager({ registry, backends: createDefaultBackends(registry) });
+  };
+
+  test('unions multi-selected ids across every context', ({ expect }) => {
+    const manager = makeManager();
+    manager.set(selectionAspect, 'ctx-a', { mode: 'multi', ids: ['a1', 'a2'] });
+    manager.set(selectionAspect, 'ctx-b', { mode: 'multi', ids: ['a2', 'b1'] });
+    // Single-mode contexts contribute nothing to the set.
+    manager.set(selectionAspect, 'ctx-c', { mode: 'single', id: 'c1' });
+    expect(getSelectionSet(manager)).toEqual(new Set(['a1', 'a2', 'b1']));
+  });
+
+  test('seeds the set with the optional explicit contextId', ({ expect }) => {
+    const manager = makeManager();
+    manager.set(selectionAspect, 'ctx-a', { mode: 'multi', ids: ['a1'] });
+    expect(getSelectionSet(manager, 'explicit')).toEqual(new Set(['explicit', 'a1']));
+  });
+
+  test('returns an empty set when nothing is selected', ({ expect }) => {
+    expect(getSelectionSet(makeManager())).toEqual(new Set());
+  });
+});

package/src/selection.ts

@@ -2,11 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Atom, type Registry } from '@effect-atom/atom-react';
 import * as Match from 'effect/Match';
 import * as Schema from 'effect/Schema';
 
-import { invariant } from '@dxos/invariant';
+import { type AspectDef, type ViewStateManager, defineViewState } from './view-state';
 
 export type SelectionMode = 'single' | 'multi' | 'range' | 'multi-range';
 
@@ -51,178 +50,49 @@ export type SelectionResult<T extends SelectionMode> = T extends 'single'
         ? { from: string; to: string }[]
         : never;
 
-export const getSelectionSet = (selectionManager: SelectionManager, contextId?: string) => {
+/** Selection state for a context, stored in memory (ephemeral, per-device session). */
+export const selectionAspect: AspectDef<Selection> = defineViewState<Selection>({
+  key: 'selection',
+  backend: 'memory',
+  schema: SelectionSchema,
+  defaultValue: () => ({ mode: 'multi', ids: [] }),
+});
+
+/**
+ * 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);
+  // 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),
+    Match.when({ mode: 'multi' }, (s) => s.ids),
+    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>;
+};
+
+/** 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 => {
+  const ids = selection?.mode === 'multi' ? selection.ids : [];
+  return { mode: 'multi', ids: ids.includes(id) ? ids.filter((existing) => existing !== id) : [...ids, id] };
+};
+
+/** Union of all multi-selected ids across every selection context, plus an optional explicit id. */
+export const getSelectionSet = (manager: ViewStateManager, contextId?: string): Set<string> => {
   const ids = new Set<string>(contextId ? [contextId] : []);
-  for (const context of selectionManager.getSelectionContexts()) {
-    const selection = selectionManager.getSelection(context);
-    if (selection?.mode === 'multi') {
+  for (const context of manager.contexts(selectionAspect)) {
+    const selection = manager.get(selectionAspect, context);
+    if (selection.mode === 'multi') {
       for (const id of selection.ids) {
         ids.add(id);
       }
     }
   }
-
   return ids;
 };
-
-/**
- * Manages selection state for different contexts.
- * Each context maintains its own selection mode and state.
- */
-export class SelectionManager {
-  private readonly _state: Atom.Writable<{ selections: Record<string, Selection> }>;
-
-  constructor(
-    private readonly _registry: Registry.Registry,
-    initial: Record<string, Selection> = {},
-  ) {
-    this._state = Atom.make<{ selections: Record<string, Selection> }>({
-      selections: { ...initial },
-    });
-  }
-
-  /**
-   * Get the state atom for reactive access in the graph system.
-   */
-  get state(): Atom.Atom<{ selections: Record<string, Selection> }> {
-    return this._state;
-  }
-
-  /**
-   * Gets the current state.
-   */
-  getState(): { selections: Record<string, Selection> } {
-    return this._registry.get(this._state);
-  }
-
-  /**
-   * Subscribe to changes in the selection state.
-   */
-  subscribe(cb: (state: { selections: Record<string, Selection> }) => void): () => void {
-    this._registry.get(this._state);
-    return this._registry.subscribe(this._state, () => {
-      cb(this._registry.get(this._state));
-    });
-  }
-
-  getSelectionContexts(): string[] {
-    return Object.keys(this._registry.get(this._state).selections);
-  }
-
-  getSelection(contextId: string): Selection | undefined;
-  getSelection<T extends SelectionMode>(contextId: string, mode: T): Selection;
-  getSelection<T extends SelectionMode | undefined>(
-    contextId: string,
-    mode: T = undefined as T,
-  ): Selection | undefined {
-    const state = this._registry.get(this._state);
-    const selection = state.selections[contextId];
-    if (!mode || selection) {
-      return selection;
-    }
-
-    // Create new selection for the context.
-    const newSelection = defaultSelection(mode);
-    this._registry.update(this._state, (state) => ({
-      selections: { ...state.selections, [contextId]: newSelection },
-    }));
-
-    return newSelection;
-  }
-
-  getSelected<T extends SelectionMode>(contextId: string, mode: T = 'multi' as T): SelectionResult<T> {
-    const selection = this.getSelection(contextId, mode);
-    invariant(selection?.mode === mode, 'Selection mode mismatch');
-
-    // Cast required because TypeScript can't infer the relationship between T and the matched result.
-    return Match.type<Selection>().pipe(
-      Match.when({ mode: 'single' }, (s) => s.id),
-      Match.when({ mode: 'multi' }, (s) => s.ids),
-      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,
-    )(selection) as SelectionResult<T>;
-  }
-
-  updateSingle(contextId: string, id: string): void {
-    const selection = this.getSelection(contextId, 'single');
-    invariant(selection?.mode === 'single', 'Selection mode is not single');
-    this._registry.update(this._state, (state) => ({
-      selections: {
-        ...state.selections,
-        [contextId]: { ...selection, id },
-      },
-    }));
-  }
-
-  updateMulti(contextId: string, ids: string[]) {
-    const selection = this.getSelection(contextId, 'multi');
-    invariant(selection?.mode === 'multi', 'Selection mode is not multi');
-    this._registry.update(this._state, (state) => ({
-      selections: {
-        ...state.selections,
-        [contextId]: { ...selection, ids: [...ids] },
-      },
-    }));
-  }
-
-  updateRange(contextId: string, from: string, to: string) {
-    const selection = this.getSelection(contextId, 'range');
-    invariant(selection?.mode === 'range', 'Selection mode is not range');
-    this._registry.update(this._state, (state) => ({
-      selections: {
-        ...state.selections,
-        [contextId]: { ...selection, from, to },
-      },
-    }));
-  }
-
-  updateMultiRange(contextId: string, ranges: { from: string; to: string }[]) {
-    const selection = this.getSelection(contextId, 'multi-range');
-    invariant(selection?.mode === 'multi-range', 'Selection mode is not multi-range');
-    this._registry.update(this._state, (state) => ({
-      selections: {
-        ...state.selections,
-        [contextId]: { ...selection, ranges: [...ranges] },
-      },
-    }));
-  }
-
-  clearSelection(contextId: string): void {
-    const selection = this.getSelection(contextId);
-    if (!selection) {
-      return;
-    }
-
-    const clearedSelection = Match.type<Selection>().pipe(
-      Match.when({ mode: 'single' }, (s) => ({ ...s, id: undefined })),
-      Match.when({ mode: 'multi' }, (s) => ({ ...s, ids: [] })),
-      Match.when({ mode: 'range' }, (s) => ({ ...s, from: undefined, to: undefined })),
-      Match.when({ mode: 'multi-range' }, (s) => ({ ...s, ranges: [] })),
-      Match.exhaustive,
-    )(selection);
-
-    this._registry.update(this._state, (state) => ({
-      selections: {
-        ...state.selections,
-        [contextId]: clearedSelection,
-      },
-    }));
-  }
-
-  toggleSelection(contextId: string, id: string): void {
-    const selection = this.getSelection(contextId, 'multi');
-    invariant(selection?.mode === 'multi', 'Selection mode is not multi');
-
-    const newIds = selection.ids.includes(id)
-      ? selection.ids.filter((existingId) => existingId !== id)
-      : [...selection.ids, id];
-
-    this._registry.update(this._state, (state) => ({
-      selections: {
-        ...state.selections,
-        [contextId]: { ...selection, ids: newIds },
-      },
-    }));
-  }
-}

package/src/testing/decorators/withAttention.ts

@@ -7,7 +7,7 @@ import { type Decorator } from '@storybook/react';
 import { createElement, useMemo } from 'react';
 
 import { AttentionManager } from '../../attention';
-import { RootAttentionProvider, SelectionProvider } from '../../components';
+import { RootAttentionProvider, ViewStateProvider } from '../../components';
 
 /**
  * Storybook decorator that provides attention context.
@@ -24,7 +24,7 @@ export const withAttention = (initialAttendedId?: string): Decorator => {
     return createElement(
       RegistryContext.Provider,
       { value: registry },
-      createElement(RootAttentionProvider, { attention }, createElement(SelectionProvider, {}, createElement(Story))),
+      createElement(RootAttentionProvider, { attention }, createElement(ViewStateProvider, {}, createElement(Story))),
     );
   };
 };

package/src/types/index.ts

@@ -7,3 +7,4 @@
 // other non-DOM code that only needs the data model and pure helpers.
 export * from '../attention';
 export * from '../selection';
+export * from '../view-state';

package/src/view-state/backends.test.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom-react';
+import * as Schema from 'effect/Schema';
+import { afterEach, describe, test } from 'vitest';
+
+import { LocalBackend } from './backends';
+import { ViewStateManager, defineViewState } from './view-state';
+
+const Editor = defineViewState({
+  key: 'editor',
+  backend: 'local',
+  schema: Schema.Struct({ scrollTo: Schema.optional(Schema.Number) }).pipe(Schema.mutable),
+  defaultValue: () => ({}),
+});
+
+// Minimal in-memory Storage stand-in (no real localStorage in the test runner).
+const fakeStorage = (): Storage => {
+  const map = new Map<string, string>();
+  return {
+    get length() {
+      return map.size;
+    },
+    clear: () => map.clear(),
+    getItem: (key) => (map.has(key) ? map.get(key)! : null),
+    key: (index) => [...map.keys()][index] ?? null,
+    removeItem: (key) => void map.delete(key),
+    setItem: (key, value) => void map.set(key, value),
+  };
+};
+
+describe('LocalBackend', () => {
+  // Dispose every backend after each test so its global `storage` listener does not leak across the suite.
+  const disposables: LocalBackend[] = [];
+  afterEach(() => {
+    disposables.splice(0).forEach((backend) => backend.dispose());
+  });
+
+  const make = () => {
+    const registry = Registry.make();
+    const storage = fakeStorage();
+    const local = new LocalBackend({ registry, storage });
+    disposables.push(local);
+    const manager = new ViewStateManager({ registry, backends: { memory: local, local } });
+    return { manager, storage };
+  };
+
+  test('default until written', ({ expect }) => {
+    const { manager } = make();
+    expect(manager.get(Editor, 'doc-1')).toEqual({});
+  });
+
+  test('set persists encoded JSON under the namespaced key', ({ expect }) => {
+    const { manager, storage } = make();
+    manager.set(Editor, 'doc-1', { scrollTo: 42 });
+    expect(JSON.parse(storage.getItem('dxos:view-state:editor:doc-1')!)).toEqual({ scrollTo: 42 });
+  });
+
+  test('reading does not write defaults to storage', ({ expect }) => {
+    const { manager, storage } = make();
+    manager.get(Editor, 'doc-1');
+    expect(storage.getItem('dxos:view-state:editor:doc-1')).toBeNull();
+  });
+
+  test('seeds atom from pre-existing storage value', ({ expect }) => {
+    const { manager, storage } = make();
+    storage.setItem('dxos:view-state:editor:doc-2', JSON.stringify({ scrollTo: 7 }));
+    expect(manager.get(Editor, 'doc-2')).toEqual({ scrollTo: 7 });
+  });
+
+  test('falls back to default on unparseable storage value', ({ expect }) => {
+    const { manager, storage } = make();
+    storage.setItem('dxos:view-state:editor:doc-3', '{not json');
+    expect(manager.get(Editor, 'doc-3')).toEqual({});
+  });
+
+  test('contexts enumerates persisted contexts', ({ expect }) => {
+    const { manager } = make();
+    manager.set(Editor, 'doc-1', { scrollTo: 1 });
+    manager.set(Editor, 'doc-2', { scrollTo: 2 });
+    expect(new Set(manager.contexts(Editor))).toEqual(new Set(['doc-1', 'doc-2']));
+  });
+
+  test('a cross-tab storage event re-reads the atom from storage', ({ expect }) => {
+    const registry = Registry.make();
+    const storage = fakeStorage();
+    const local = new LocalBackend({ registry, storage });
+    const manager = new ViewStateManager({ registry, backends: { memory: local, local } });
+
+    // Touch the context so its atom is registered and observed by the storage listener.
+    const key = 'dxos:view-state:editor:doc-4';
+    expect(manager.get(Editor, 'doc-4')).toEqual({});
+
+    // Simulate another tab's write: update storage, then fire the `storage` event (the listener
+    // re-reads from storage rather than trusting the event payload).
+    storage.setItem(key, JSON.stringify({ scrollTo: 99 }));
+    globalThis.dispatchEvent(new StorageEvent('storage', { key, newValue: storage.getItem(key) }));
+
+    expect(manager.get(Editor, 'doc-4')).toEqual({ scrollTo: 99 });
+    local.dispose();
+  });
+});