gloomberb 0.10.0 → 0.10.2

package/src/plugins/builtin/portfolio-list/quick-add/resolution.ts

@@ -19,8 +19,10 @@ interface ResolvedQuickAdd {
 export type QuickAddValidation =
   | { status: "idle"; query: "" }
   | { status: "checking"; query: string }
-  | (ResolvedQuickAdd & { status: "ready" | "duplicate" })
-  | { status: "missing" | "error"; query: string; message: string };
+  | (ResolvedQuickAdd & { status: "ready" })
+  | (ResolvedQuickAdd & { status: "duplicate" })
+  | { status: "missing"; query: string; message: string }
+  | { status: "error"; query: string; message: string };
 
 export const IDLE_VALIDATION: QuickAddValidation = { status: "idle", query: "" };
 

package/src/plugins/builtin/research/corporate-actions-pane.tsx

@@ -19,8 +19,7 @@ import { blendHex, colors } from "../../../theme/colors";
 import { formatCompact, formatCurrency, formatNumber, formatPercent, formatPercentRaw } from "../../../utils/format";
 import { isPlainKey } from "../../../utils/keyboard";
 import { wrapTextLines } from "../../../utils/text-wrap";
-import { useResolvedEntryValue, useSecFilingContent, useSecFilingDocuments, useSecFilingsQuery } from "../../../market-data/hooks";
-import { getSharedMarketDataCoordinator } from "../../../market-data/coordinator";
+import { useResolvedEntryValue, useSecFilingDocuments, useSecFilingsQuery } from "../../../market-data/hooks";
 import { instrumentFromTicker } from "../../../market-data/request-types";
 import { isUsEquityTicker } from "../../../utils/sec";
 import { useAssetData } from "../../runtime";
@@ -28,12 +27,15 @@ import { handleRefreshKey, loadingErrorFooterInfo, refreshFooterHint } from "../
 import { useBoundTicker as useSymbolBinding, useTickerRequest } from "../shared/ticker-request";
 import {
   documentContentKey,
-  documentContentTarget,
   documentHeading,
   formatCompactDocumentLabel,
   isDefaultVisibleFilingDocument,
   isInlineExhibitDocument,
 } from "../sec/filing-documents";
+import {
+  buildInlineFilingContentTargets,
+  useSecFilingContentCache,
+} from "../sec/filing-content";
 
 type EventStatus = "Earnings" | "Q Est" | "FY Est" | "TTM" | "Dividend" | "Split";
 
@@ -523,9 +525,6 @@ export function CorporateActionsView({
   const [selectedIdx, setSelectedIdx] = useState(0);
   const [openRowId, setOpenRowId] = useState<string | null>(null);
   const detailScrollRef = useRef<ScrollBoxRenderable>(null);
-  const [inlineContent, setInlineContent] = useState<Map<string, string | null>>(new Map());
-  const documentFetchStartedRef = useRef(new Set<string>());
-  const documentFetchGenRef = useRef(0);
   const todayKey = todayDateKey();
   const futureRowBackground = blendHex(colors.bg, colors.positive, 0.16);
   const loading = actionsLoading || analystLoading || financialsLoading;
@@ -561,16 +560,26 @@ export function CorporateActionsView({
     || documentsEntry?.phase === "loading"
     || documentsEntry?.phase === "refreshing"
   );
-  const hasInlineExhibits = documents.some(isInlineExhibitDocument);
-  const filingContentEntry = useSecFilingContent(
-    matchedFiling && !documentsLoading && !hasInlineExhibits ? matchedFiling : null,
-  );
-  const primaryContent = useResolvedEntryValue(filingContentEntry);
-  const primaryContentLoading = !!matchedFiling && (
-    filingContentEntry?.phase === "idle"
-    || filingContentEntry?.phase === "loading"
-    || filingContentEntry?.phase === "refreshing"
+  const inlineTargets = useMemo(
+    () => buildInlineFilingContentTargets(matchedFiling, documents),
+    [documents, matchedFiling],
   );
+  const filingContentTargets = useMemo(() => {
+    if (!matchedFiling || documentsLoading) return [];
+    return inlineTargets.length > 0 ? inlineTargets : [matchedFiling];
+  }, [documentsLoading, inlineTargets, matchedFiling]);
+  const { contentCache: inlineContent } = useSecFilingContentCache({
+    scopeKey: `${symbol}:${exchange}`,
+    targets: filingContentTargets,
+  });
+  const hasInlineExhibits = inlineTargets.length > 0;
+  const primaryContent = matchedFiling
+    ? inlineContent.get(matchedFiling.accessionNumber) ?? null
+    : null;
+  const primaryContentLoading = !!matchedFiling
+    && !documentsLoading
+    && !hasInlineExhibits
+    && !inlineContent.has(matchedFiling.accessionNumber);
 
   useEffect(() => {
     if (rows.length > 0 && selectedIdx >= rows.length) {
@@ -590,43 +599,6 @@ export function CorporateActionsView({
     if (scrollBox) scrollBox.scrollTop = 0;
   }, [openRowId]);
 
-  useEffect(() => {
-    setInlineContent(new Map());
-    documentFetchStartedRef.current.clear();
-    documentFetchGenRef.current += 1;
-  }, [exchange, symbol]);
-
-  useEffect(() => {
-    if (!matchedFiling || documents.length === 0) return;
-    const coordinator = getSharedMarketDataCoordinator();
-    if (!coordinator) return;
-    const gen = documentFetchGenRef.current;
-    const documentsToFetch = documents.filter((document) => {
-      if (!isInlineExhibitDocument(document)) return false;
-      const key = documentContentKey(matchedFiling, document);
-      return !inlineContent.has(key) && !documentFetchStartedRef.current.has(key);
-    });
-    if (documentsToFetch.length === 0) return;
-
-    for (const document of documentsToFetch) {
-      documentFetchStartedRef.current.add(documentContentKey(matchedFiling, document));
-    }
-
-    (async () => {
-      for (const document of documentsToFetch) {
-        if (documentFetchGenRef.current !== gen) return;
-        const key = documentContentKey(matchedFiling, document);
-        try {
-          const entry = await coordinator.loadSecFilingContent(documentContentTarget(matchedFiling, document));
-          if (documentFetchGenRef.current !== gen) return;
-          setInlineContent((prev) => new Map(prev).set(key, entry.data ?? entry.lastGoodData ?? null));
-        } catch {
-          if (documentFetchGenRef.current !== gen) return;
-          setInlineContent((prev) => new Map(prev).set(key, null));
-        }
-      }
-    })();
-  }, [documents, inlineContent, matchedFiling]);
   const detailBody = openRow
     ? buildEventDetailBody({
         row: openRow,

package/src/plugins/builtin/sec/filing-content.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import type { SecFilingDocument, SecFilingItem } from "../../../types/data-provider";
+import {
+  buildInlineFilingContentTargets,
+  nextUncachedFilingContentTarget,
+} from "./filing-content";
+
+function filing(accessionNumber: string): SecFilingItem {
+  return {
+    accessionNumber,
+    filingDate: "2026-01-01",
+    filingUrl: `https://example.com/${accessionNumber}`,
+    form: "8-K",
+    primaryDocument: "filing.htm",
+  };
+}
+
+describe("SEC filing content cache", () => {
+  test("loads unique content targets sequentially in caller priority order", () => {
+    const selected = filing("selected");
+    const background = filing("background");
+    const targets = [selected, selected, background];
+
+    expect(nextUncachedFilingContentTarget(targets, new Map())?.accessionNumber).toBe("selected");
+    expect(nextUncachedFilingContentTarget(
+      targets,
+      new Map([["selected", null]]),
+    )?.accessionNumber).toBe("background");
+  });
+
+  test("builds content targets only for readable inline exhibits", () => {
+    const selected = filing("selected");
+    const documents: SecFilingDocument[] = [
+      { document: "exhibit.htm", description: "Press release", type: "EX-99.1", url: "https://example.com/exhibit.htm", isPrimary: false },
+      { document: "schema.xsd", description: "Schema", type: "EX-101", url: "https://example.com/schema.xsd", isPrimary: false },
+    ];
+
+    expect(buildInlineFilingContentTargets(selected, documents).map((target) => target.accessionNumber))
+      .toEqual(["selected:exhibit.htm"]);
+  });
+});

package/src/plugins/builtin/sec/filing-content.ts

@@ -0,0 +1,94 @@
+import { useEffect, useMemo, useState } from "react";
+import { useResolvedEntryValue, useSecFilingContent } from "../../../market-data/hooks";
+import type { SecFilingDocument, SecFilingItem } from "../../../types/data-provider";
+import { documentContentTarget, isInlineExhibitDocument } from "./filing-documents";
+
+interface ScopedFilingContentCache {
+  scopeKey: string;
+  values: Map<string, string | null>;
+}
+
+const EMPTY_CONTENT_CACHE = new Map<string, string | null>();
+
+export function buildInlineFilingContentTargets(
+  filing: SecFilingItem | null | undefined,
+  documents: readonly SecFilingDocument[],
+): SecFilingItem[] {
+  if (!filing) return [];
+  return documents
+    .filter(isInlineExhibitDocument)
+    .map((document) => documentContentTarget(filing, document));
+}
+
+export function nextUncachedFilingContentTarget(
+  targets: readonly SecFilingItem[],
+  cache: ReadonlyMap<string, string | null>,
+): SecFilingItem | null {
+  const seen = new Set<string>();
+  for (const target of targets) {
+    const key = target.accessionNumber;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (!cache.has(key)) return target;
+  }
+  return null;
+}
+
+export function useSecFilingContentCache({
+  scopeKey,
+  targets,
+}: {
+  scopeKey: string;
+  targets: readonly SecFilingItem[];
+}) {
+  const [state, setState] = useState<ScopedFilingContentCache>(() => ({
+    scopeKey,
+    values: new Map(),
+  }));
+  const contentCache = state.scopeKey === scopeKey ? state.values : EMPTY_CONTENT_CACHE;
+
+  useEffect(() => {
+    setState((current) => current.scopeKey === scopeKey
+      ? current
+      : { scopeKey, values: new Map() });
+  }, [scopeKey]);
+
+  const nextTarget = useMemo(
+    () => nextUncachedFilingContentTarget(targets, contentCache),
+    [contentCache, targets],
+  );
+  const contentEntry = useSecFilingContent(nextTarget);
+  const resolvedContent = useResolvedEntryValue(contentEntry);
+
+  useEffect(() => {
+    if (!nextTarget) return;
+    const phase = contentEntry?.phase;
+    const settled = phase === "ready"
+      || phase === "error"
+      || (phase === "refreshing" && resolvedContent !== null);
+    if (!settled) return;
+    const key = nextTarget.accessionNumber;
+    const content = phase === "error" ? null : resolvedContent;
+    setState((current) => {
+      if (current.scopeKey !== scopeKey || current.values.has(key)) return current;
+      return {
+        scopeKey,
+        values: new Map(current.values).set(key, content),
+      };
+    });
+  }, [contentEntry?.phase, nextTarget, resolvedContent, scopeKey]);
+
+  const pendingCount = useMemo(() => {
+    const pending = new Set<string>();
+    for (const target of targets) {
+      if (!contentCache.has(target.accessionNumber)) pending.add(target.accessionNumber);
+    }
+    return pending.size;
+  }, [contentCache, targets]);
+
+  return {
+    contentCache,
+    loadingKey: nextTarget?.accessionNumber ?? null,
+    pendingCount,
+  };
+}

package/src/plugins/builtin/sec/index.tsx

@@ -1,15 +1,14 @@
 import { Text } from "../../../ui";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import type { PluginModule } from "../plugin-module";
 import type { SecFilingDocument, SecFilingItem } from "../../../types/data-provider";
-import { useResolvedEntryValue, useSecFilingContent, useSecFilingDocuments, useSecFilingsQuery } from "../../../market-data/hooks";
+import { useResolvedEntryValue, useSecFilingDocuments, useSecFilingsQuery } from "../../../market-data/hooks";
 import { instrumentFromTicker } from "../../../market-data/request-types";
 import { useDebouncedPluginPaneState } from "../../runtime";
 import { usePaneTicker } from "../../../state/app/context";
 import { colors } from "../../../theme/colors";
-import { FeedDataTableStackView, Spinner, useExternalLinkFooter, type FeedDataTableItem } from "../../../components";
+import { FeedDataTableStackView, Spinner, type FeedDataTableItem } from "../../../components";
 import { isUsEquityTicker } from "../../../utils/sec";
-import { getSharedMarketDataCoordinator } from "../../../market-data/coordinator";
 import { parseForm4Xml, transactionTypeLabel } from "../insider/insider-data";
 import { formatCompact, formatCurrency } from "../../../utils/format";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
@@ -19,12 +18,16 @@ import {
 } from "./filing-display";
 import {
   documentContentKey,
-  documentContentTarget,
   documentHeading,
   formatCompactDocumentLabel,
   isDefaultVisibleFilingDocument,
   isInlineExhibitDocument,
 } from "./filing-documents";
+import {
+  buildInlineFilingContentTargets,
+  useSecFilingContentCache,
+} from "./filing-content";
+import { usePaneStatusLinkFooter } from "../shared/pane-footer";
 
 const SEC_FILING_LIMIT = 50;
 const OWNERSHIP_FORMS = new Set(["3", "4", "5"]);
@@ -244,9 +247,7 @@ function SecView({ width, height, focused }: { width: number; height: number; fo
   const { ticker } = usePaneTicker();
   const selectionKey = `selectedIdx:${ticker?.metadata.ticker ?? "none"}`;
   const [selectedIdx, setSelectedIdx] = useDebouncedPluginPaneState<number>(selectionKey, 0);
-  const [contentCache, setContentCache] = useState<Map<string, string | null>>(new Map());
   const [openItemId, setOpenItemId] = useState<string | null>(null);
-  const contentFetchRef = useRef(0);
   const eligibleTicker = isUsEquityTicker(ticker);
   const instrument = instrumentFromTicker(ticker, ticker?.metadata.ticker ?? null);
   const filingsEntry = useSecFilingsQuery(
@@ -258,20 +259,9 @@ function SecView({ width, height, focused }: { width: number; height: number; fo
   const loading = filingsEntry?.phase === "loading" || (filingsEntry?.phase === "refreshing" && filings.length === 0);
   const error = filingsEntry?.phase === "error" ? filingsEntry.error?.message ?? "Failed to load SEC filings" : null;
 
-  useEffect(() => {
-    setContentCache(new Map());
-    contentFetchRef.current += 1;
-  }, [eligibleTicker, ticker?.metadata.exchange, ticker?.metadata.ticker]);
-
   const openFiling = openItemId
     ? filings.find((filing) => filing.accessionNumber === openItemId) ?? null
     : null;
-  const cachedOpenContent = openFiling ? contentCache.get(openFiling.accessionNumber) : undefined;
-  const filingContentEntry = useSecFilingContent(
-    openFiling && cachedOpenContent === undefined ? openFiling : null,
-  );
-  const filingContent = useResolvedEntryValue(filingContentEntry);
-  const loadingContent = filingContentEntry?.phase === "loading" || filingContentEntry?.phase === "refreshing";
   const documentsEntry = useSecFilingDocuments(openFiling ?? null);
   const openDocuments = useResolvedEntryValue(documentsEntry) ?? [];
   const loadingDocuments = !!openFiling && (
@@ -280,50 +270,16 @@ function SecView({ width, height, focused }: { width: number; height: number; fo
     || documentsEntry?.phase === "refreshing"
   );
 
-  useEffect(() => {
-    if (!openFiling) return;
-    if (cachedOpenContent !== undefined) return;
-    if (filingContentEntry?.phase === "error") {
-      setContentCache((prev) => new Map(prev).set(openFiling.accessionNumber, null));
-      return;
-    }
-    if (filingContent !== null) {
-      setContentCache((prev) => new Map(prev).set(openFiling.accessionNumber, filingContent));
-    }
-  }, [cachedOpenContent, filingContent, filingContentEntry?.phase, openFiling]);
-
-  const documentFetchStartedRef = useRef(new Set<string>());
-  useEffect(() => {
-    if (!openFiling || openDocuments.length === 0) return;
-    const coordinator = getSharedMarketDataCoordinator();
-    if (!coordinator) return;
-    const gen = contentFetchRef.current;
-    const documentsToFetch = openDocuments.filter((document) => {
-      if (!isInlineExhibitDocument(document)) return false;
-      const key = documentContentKey(openFiling, document);
-      return !contentCache.has(key) && !documentFetchStartedRef.current.has(key);
-    });
-    if (documentsToFetch.length === 0) return;
-
-    for (const document of documentsToFetch) {
-      documentFetchStartedRef.current.add(documentContentKey(openFiling, document));
-    }
-
-    (async () => {
-      for (const document of documentsToFetch) {
-        if (contentFetchRef.current !== gen) return;
-        const key = documentContentKey(openFiling, document);
-        try {
-          const entry = await coordinator.loadSecFilingContent(documentContentTarget(openFiling, document));
-          if (contentFetchRef.current !== gen) return;
-          setContentCache((prev) => new Map(prev).set(key, entry.data ?? entry.lastGoodData ?? null));
-        } catch {
-          if (contentFetchRef.current !== gen) return;
-          setContentCache((prev) => new Map(prev).set(key, null));
-        }
-      }
-    })();
-  }, [contentCache, openFiling, openDocuments]);
+  const contentTargets = useMemo(() => [
+    ...(openFiling ? [openFiling] : []),
+    ...buildInlineFilingContentTargets(openFiling, openDocuments),
+    ...filings.filter((filing) => OWNERSHIP_FORMS.has(filing.form.trim())),
+  ], [filings, openDocuments, openFiling]);
+  const { contentCache } = useSecFilingContentCache({
+    scopeKey: `${ticker?.metadata.ticker ?? "none"}:${ticker?.metadata.exchange ?? ""}:${eligibleTicker}`,
+    targets: contentTargets,
+  });
+  const loadingContent = !!openFiling && !contentCache.has(openFiling.accessionNumber);
 
   useEffect(() => {
     if (filings.length > 0 && selectedIdx >= filings.length) {
@@ -331,53 +287,14 @@ function SecView({ width, height, focused }: { width: number; height: number; fo
     }
   }, [filings.length, selectedIdx, setSelectedIdx]);
 
-  // Background prefetch Form 4 content for enriched previews
-  const prefetchStartedRef = useRef(new Set<string>());
-  useEffect(() => {
-    prefetchStartedRef.current.clear();
-    documentFetchStartedRef.current.clear();
-  }, [eligibleTicker, ticker?.metadata.exchange, ticker?.metadata.ticker]);
-
-  useEffect(() => {
-    if (filings.length === 0) return;
-    const coordinator = getSharedMarketDataCoordinator();
-    if (!coordinator) return;
-    const gen = contentFetchRef.current;
-    const form4s = filings.filter((f) =>
-      OWNERSHIP_FORMS.has(f.form.trim())
-      && !contentCache.has(f.accessionNumber)
-      && !prefetchStartedRef.current.has(f.accessionNumber),
-    );
-    if (form4s.length === 0) return;
-
-    for (const filing of form4s) {
-      prefetchStartedRef.current.add(filing.accessionNumber);
-    }
-
-    (async () => {
-      for (const filing of form4s) {
-        if (contentFetchRef.current !== gen) return;
-        try {
-          const entry = await coordinator.loadSecFilingContent(filing);
-          if (contentFetchRef.current !== gen) return;
-          const content = entry?.data ?? null;
-          setContentCache((prev) => new Map(prev).set(filing.accessionNumber, content));
-        } catch { /* skip */ }
-      }
-    })();
-  }, [filings]);
-
-  const footerInfo = useMemo(() => [
-    ...(loading ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
-    ...(error ? [{ id: "error", parts: [{ text: "error", tone: "warning" as const }] }] : []),
-  ], [error, loading]);
-  useExternalLinkFooter({
+  usePaneStatusLinkFooter({
     registrationId: "sec",
     focused,
     url: error ? null : openFiling?.filingUrl,
     source: openFiling?.form,
-    info: footerInfo,
     label: "filing",
+    loading,
+    error,
   });
 
   if (!ticker) return <Text fg={colors.textDim}>Select a ticker to view SEC filings.</Text>;

package/src/plugins/builtin/sectors/sector-model.ts

@@ -1,6 +1,7 @@
 import type { DataTableColumn } from "../../../components";
 import type { PricePoint } from "../../../types/financials";
 import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
+import { getPricePointTimestamp } from "../../../utils/price-history";
 import {
   getSectorCollection,
   type SectorCollectionId,
@@ -101,13 +102,6 @@ export function updateRowsForCollection(
   };
 }
 
-function getPricePointTimestamp(point: PricePoint): number {
-  const value = point.date as Date | string | number | null | undefined;
-  if (value instanceof Date) return value.getTime();
-  if (value == null) return Number.NaN;
-  return new Date(value).getTime();
-}
-
 function getSortedHistory(history: readonly PricePoint[]): Array<{ point: PricePoint; timestamp: number }> {
   return history
     .map((point) => ({ point, timestamp: getPricePointTimestamp(point) }))

package/src/plugins/builtin/shared/cloud-upgrade.ts

@@ -0,0 +1 @@
+export const CLOUD_UPGRADE_URL = "https://gloom.sh/cloud?upgrade=pro";

package/src/plugins/builtin/shared/pane-footer.ts

@@ -0,0 +1,82 @@
+import { useMemo } from "react";
+import {
+  useExternalLinkFooter,
+  usePaneFooter,
+  type PaneFooterSegment,
+} from "../../../components";
+
+const EMPTY_STATUS_INFO: PaneFooterSegment[] = [];
+
+function buildPaneStatusInfo({
+  loading = false,
+  error,
+  info = EMPTY_STATUS_INFO,
+}: {
+  loading?: boolean;
+  error?: string | null;
+  info?: readonly PaneFooterSegment[];
+}): PaneFooterSegment[] {
+  return [
+    ...info,
+    ...(loading ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
+    ...(error ? [{ id: "error", parts: [{ text: error, tone: "warning" as const }] }] : []),
+  ];
+}
+
+export function usePaneStatusFooter({
+  registrationId,
+  loading = false,
+  error,
+  info = EMPTY_STATUS_INFO,
+  enabled = true,
+}: {
+  registrationId: string;
+  loading?: boolean;
+  error?: string | null;
+  info?: readonly PaneFooterSegment[];
+  enabled?: boolean;
+}) {
+  const statusInfo = useMemo(
+    () => buildPaneStatusInfo({ loading, error, info }),
+    [error, info, loading],
+  );
+  usePaneFooter(
+    registrationId,
+    () => enabled && statusInfo.length > 0 ? { info: statusInfo } : null,
+    [enabled, registrationId, statusInfo],
+  );
+}
+
+export function usePaneStatusLinkFooter({
+  registrationId,
+  focused,
+  url,
+  source,
+  label,
+  loading = false,
+  error,
+  info = EMPTY_STATUS_INFO,
+}: {
+  registrationId: string;
+  focused: boolean;
+  url: string | null | undefined;
+  source?: string | null;
+  label?: string;
+  loading?: boolean;
+  error?: string | null;
+  info?: readonly PaneFooterSegment[];
+}) {
+  const statusInfo = useMemo(
+    () => buildPaneStatusInfo({ loading, error, info }),
+    [error, info, loading],
+  );
+  return useExternalLinkFooter({
+    registrationId,
+    focused,
+    url,
+    source,
+    label,
+    info: statusInfo,
+    showHint: false,
+  });
+}

package/src/plugins/builtin/shared/read-state.ts

@@ -1,15 +1,31 @@
+import { useCallback, useMemo } from "react";
+import { usePluginState } from "../../runtime";
+
 export const DEFAULT_MAX_READ_IDS = 2_000;
 
+export interface PersistedReadIdAdapter<TState> {
+  getIds(state: TState): readonly unknown[] | undefined;
+  withIds(state: TState, ids: string[]): TState;
+  maxIds?: number;
+}
+
+interface UsePersistedReadIdsOptions<TState> {
+  key: string;
+  fallback: TState;
+  schemaVersion: number;
+  adapter: PersistedReadIdAdapter<TState>;
+}
+
 function normalizeReadId(readId: unknown): string {
   return typeof readId === "string" ? readId.trim() : "";
 }
 
-export function sameStringArray(left: readonly string[], right: readonly string[]): boolean {
+function sameStringArray(left: readonly string[], right: readonly unknown[]): boolean {
   if (left.length !== right.length) return false;
   return left.every((value, index) => value === right[index]);
 }
 
-export function normalizeReadIds(
+function normalizeReadIds(
   readIds: readonly unknown[] | undefined,
   maxIds = DEFAULT_MAX_READ_IDS,
 ): string[] {
@@ -27,7 +43,7 @@ export function normalizeReadIds(
   return normalizedIds;
 }
 
-export function markReadId(
+function markReadId(
   readIds: readonly unknown[] | undefined,
   readId: string,
   maxIds = DEFAULT_MAX_READ_IDS,
@@ -41,3 +57,48 @@ export function markReadId(
     ...current.filter((currentId) => currentId !== normalizedId),
   ].slice(0, maxIds);
 }
+
+export function normalizePersistedReadIdState<TState>(
+  state: TState,
+  adapter: PersistedReadIdAdapter<TState>,
+): TState {
+  const current = adapter.getIds(state);
+  const ids = normalizeReadIds(current, adapter.maxIds);
+  return Array.isArray(current) && sameStringArray(ids, current)
+    ? state
+    : adapter.withIds(state, ids);
+}
+
+export function markPersistedReadId<TState>(
+  state: TState,
+  readId: string,
+  adapter: PersistedReadIdAdapter<TState>,
+): TState {
+  const current = adapter.getIds(state);
+  const ids = markReadId(current, readId, adapter.maxIds);
+  return Array.isArray(current) && sameStringArray(ids, current)
+    ? state
+    : adapter.withIds(state, ids);
+}
+
+export function usePersistedReadIds<TState>({
+  key,
+  fallback,
+  schemaVersion,
+  adapter,
+}: UsePersistedReadIdsOptions<TState>) {
+  const [state, setState] = usePluginState<TState>(key, fallback, { schemaVersion });
+  const normalizedState = useMemo(
+    () => normalizePersistedReadIdState(state, adapter),
+    [adapter, state],
+  );
+  const readIds = useMemo(
+    () => new Set(normalizeReadIds(adapter.getIds(normalizedState), adapter.maxIds)),
+    [adapter, normalizedState],
+  );
+  const markRead = useCallback((readId: string) => {
+    setState((current) => markPersistedReadId(current, readId, adapter));
+  }, [adapter, setState]);
+
+  return { readIds, markRead };
+}