Persistence: share entity write-through helper; normalize quota at db.put

src/app/infrastructure/db.ts

@@ -21,6 +21,19 @@ export const DATASETS_STORE = 'datasets';
 export const THEMES_STORE = 'themes';
 export const FONTS_STORE = 'fonts';
 
+/**
+ * Raised when a write fails because the origin's storage budget is exhausted.
+ * Normalized from the raw `QuotaExceededError` DOMException in `put` (the one
+ * write path), so every typed adapter fails loud on quota uniformly and the UI
+ * can map it to an actionable "storage full" message rather than losing work.
+ */
+export class StorageQuotaError extends Error {
+  constructor(message = 'Storage is full. Export and remove items to free space.') {
+    super(message);
+    this.name = 'StorageQuotaError';
+  }
+}
+
 /** Every object store the app expects — the open-time verification checklist. */
 const EXPECTED_STORES = [SNIPPETS_STORE, DATASETS_STORE, THEMES_STORE, FONTS_STORE] as const;
 
@@ -105,7 +118,14 @@ export const getAll = <T>(store: string): Promise<T[]> =>
   tx<T[]>(store, 'readonly', (s) => s.getAll() as IDBRequest<T[]>);
 
 export const put = <T>(store: string, value: T): Promise<IDBValidKey> =>
-  tx<IDBValidKey>(store, 'readwrite', (s) => s.put(value));
+  tx<IDBValidKey>(store, 'readwrite', (s) => s.put(value)).catch((err: unknown) => {
+    // Quota is whole-origin and surfaces as a QuotaExceededError DOMException;
+    // normalize it here so every adapter throws a typed StorageQuotaError.
+    if (err instanceof DOMException && err.name === 'QuotaExceededError') {
+      throw new StorageQuotaError();
+    }
+    throw err;
+  });
 
 export const del = (store: string, key: IDBValidKey): Promise<undefined> =>
   tx<undefined>(store, 'readwrite', (s) => s.delete(key));

src/app/infrastructure/snippet-store.ts

@@ -2,22 +2,15 @@
  * Snippet persistence adapter (docs/architecture/02).
  *
  * The typed seam between the snippet store and IndexedDB. Exposes plain async
- * functions returning domain `Snippet` objects; migrates every record on read;
- * fails loudly on quota so the UI can warn rather than silently lose work.
+ * functions returning domain `Snippet` objects; migrates every record on read.
+ * Quota failures fail loud as a `StorageQuotaError` — normalized once in `db.put`
+ * (see db.ts) — so the UI can warn rather than silently lose work.
  */
 
 import { CURRENT_SNIPPET_VERSION, type Snippet } from '@core/snippet';
 import { del, getAll, put, SNIPPETS_STORE } from './db';
 import { migrateSnippet } from './snippet-migrations';
 
-/** Raised when a write fails because the snippet storage budget is exhausted. */
-export class StorageQuotaError extends Error {
-  constructor(message = 'Snippet storage is full. Export and remove snippets to free space.') {
-    super(message);
-    this.name = 'StorageQuotaError';
-  }
-}
-
 /** Load every snippet, upgrading each record to the current shape. */
 export async function loadSnippets(): Promise<Snippet[]> {
   const records = await getAll<unknown>(SNIPPETS_STORE);
@@ -26,14 +19,7 @@ export async function loadSnippets(): Promise<Snippet[]> {
 
 /** Persist a snippet at the current schema version. Propagates quota failures. */
 export async function saveSnippet(snippet: Snippet): Promise<void> {
-  try {
-    await put(SNIPPETS_STORE, { ...snippet, version: CURRENT_SNIPPET_VERSION });
-  } catch (err) {
-    if (err instanceof DOMException && err.name === 'QuotaExceededError') {
-      throw new StorageQuotaError();
-    }
-    throw err;
-  }
+  await put(SNIPPETS_STORE, { ...snippet, version: CURRENT_SNIPPET_VERSION });
 }
 
 /** Permanently remove a snippet by id. */

src/app/orchestration/dataset-persistence.ts

@@ -1,54 +1,26 @@
 /**
  * Dataset persistence wiring (docs/architecture/01 §5, spec §09E).
  *
- * The dataset sibling of `persistence.ts`: a startup subscriber that diffs the
- * `datasets` array against the previous snapshot and writes upserts/deletes
- * through to the IndexedDB adapter. The store stays browser-free; failures
- * surface as a toast rather than silent loss (spec §10). There is no debounced
- * auto-save here — datasets change on explicit create/edit/delete, not per
- * keystroke, so every change is a structural array edit.
+ * A startup subscriber that write-throughs the `datasets` array to the IndexedDB
+ * adapter via the shared `wireEntityWriteThrough` diff loop. The store stays
+ * browser-free; failures surface as a toast rather than silent loss (spec §10).
+ * There is no debounced auto-save here — datasets change on explicit create/edit/
+ * delete, not per keystroke, so every change is a structural array edit.
  */
 
 import { deleteDataset, saveDataset } from '../infrastructure/dataset-store';
+import { entityStorageErrorNotification } from '../services/storage-errors';
 import { notify } from '../stores/NotificationStore';
 import { useDatasetStore } from '../stores/DatasetStore';
+import { wireEntityWriteThrough } from './entity-persistence';
 
 type Unsubscribe = () => void;
 
-function datasetError(op: 'save' | 'delete', err: unknown) {
-  notify({
-    kind: 'error',
-    title: op === 'delete' ? "Couldn't delete the dataset" : "Couldn't save the dataset",
-    message:
-      'A storage error stopped Astrolabe from completing the last dataset change, so it may not ' +
-      'survive a reload. If this keeps happening, your browser may be blocking local storage.',
-    detail:
-      err instanceof Error ? `Dataset ${op} failed: ${err.name}: ${err.message}` : String(err),
-  });
-}
-
 /** Persist dataset upserts and deletions whenever the array changes. */
-function wireDatasetWriteThrough(): Unsubscribe {
-  let prevDatasets = useDatasetStore.getState().datasets;
-  return useDatasetStore.subscribe((s) => {
-    const next = s.datasets;
-    if (next === prevDatasets) return;
-    const prev = prevDatasets;
-    prevDatasets = next;
-
-    for (const old of prev) {
-      if (!next.some((n) => n.id === old.id)) {
-        deleteDataset(old.id).catch((err) => datasetError('delete', err));
-      }
-    }
-    for (const n of next) {
-      const old = prev.find((p) => p.id === n.id);
-      if (old !== n) saveDataset(n).catch((err) => datasetError('save', err));
-    }
+export function wireDatasetPersistence(): Unsubscribe {
+  return wireEntityWriteThrough(useDatasetStore, (s) => s.datasets, {
+    save: saveDataset,
+    remove: deleteDataset,
+    onError: (op, err) => notify(entityStorageErrorNotification('dataset', op, err)),
   });
 }
-
-/** Wire dataset persistence subscribers. Returns a teardown that detaches them. */
-export function wireDatasetPersistence(): Unsubscribe {
-  return wireDatasetWriteThrough();
-}

src/app/orchestration/entity-persistence.test.ts

@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { wireEntityWriteThrough } from './entity-persistence';
+
+/**
+ * Direct contract test for the shared write-through engine. The four
+ * `*-persistence.ts` wrappers exercise it transitively (see
+ * snippet-persistence.test.ts), but this is the engine four tiers depend on, so
+ * its diff/save/delete/error behavior is pinned here against a minimal store —
+ * including the number-id path the (string-id) snippet test never hits.
+ */
+
+interface Item {
+  id: number;
+  v: number;
+}
+interface State {
+  items: Item[];
+  other?: number;
+}
+
+/** Minimal `StoreLike` the helper accepts, plus a `setState` for the test to drive. */
+function makeStore(initial: State) {
+  let state = initial;
+  const listeners = new Set<(s: State) => void>();
+  return {
+    getState: () => state,
+    setState: (next: State) => {
+      state = next;
+      listeners.forEach((l) => l(state));
+    },
+    subscribe: (l: (s: State) => void) => {
+      listeners.add(l);
+      return () => listeners.delete(l);
+    },
+  };
+}
+
+/** Flush microtasks so a `.catch` on a rejected io promise runs. */
+const flush = () => Promise.resolve().then(() => Promise.resolve());
+
+let store: ReturnType<typeof makeStore>;
+let save: ReturnType<typeof vi.fn>;
+let remove: ReturnType<typeof vi.fn>;
+let onError: ReturnType<typeof vi.fn>;
+let teardown: () => void;
+
+beforeEach(() => {
+  store = makeStore({ items: [{ id: 1, v: 1 }] });
+  save = vi.fn().mockResolvedValue(undefined);
+  remove = vi.fn().mockResolvedValue(undefined);
+  onError = vi.fn();
+  teardown = wireEntityWriteThrough(store, (s) => s.items, { save, remove, onError });
+});
+
+afterEach(() => teardown());
+
+describe('wireEntityWriteThrough', () => {
+  it('saves a newly added record (number id) and leaves untouched refs alone', () => {
+    const kept = store.getState().items[0];
+    store.setState({ items: [kept, { id: 2, v: 1 }] });
+
+    expect(save).toHaveBeenCalledTimes(1);
+    expect(save).toHaveBeenCalledWith({ id: 2, v: 1 });
+    expect(remove).not.toHaveBeenCalled();
+  });
+
+  it('saves only the record whose reference changed', () => {
+    store.setState({ items: [{ id: 1, v: 2 }] });
+
+    expect(save).toHaveBeenCalledTimes(1);
+    expect(save).toHaveBeenCalledWith({ id: 1, v: 2 });
+  });
+
+  it('removes a dropped record by id without re-saving the survivors', () => {
+    const one = store.getState().items[0];
+    const two = { id: 2, v: 1 };
+    store.setState({ items: [one, two] });
+    save.mockClear();
+
+    store.setState({ items: [two] }); // drop 1, keep 2's reference
+
+    expect(remove).toHaveBeenCalledTimes(1);
+    expect(remove).toHaveBeenCalledWith(1);
+    expect(save).not.toHaveBeenCalled();
+  });
+
+  it('ignores state changes that do not touch the selected array', () => {
+    store.setState({ ...store.getState(), other: 5 });
+
+    expect(save).not.toHaveBeenCalled();
+    expect(remove).not.toHaveBeenCalled();
+  });
+
+  it('routes a rejected save to onError instead of losing it', async () => {
+    save.mockRejectedValueOnce(new Error('boom'));
+    const kept = store.getState().items[0];
+    store.setState({ items: [kept, { id: 2, v: 1 }] });
+    await flush();
+
+    expect(onError).toHaveBeenCalledWith('save', expect.any(Error));
+  });
+
+  it('routes a rejected delete to onError', async () => {
+    remove.mockRejectedValueOnce(new Error('boom'));
+    const two = { id: 2, v: 1 };
+    store.setState({ items: [store.getState().items[0], two] });
+    store.setState({ items: [two] });
+    await flush();
+
+    expect(onError).toHaveBeenCalledWith('delete', expect.any(Error));
+  });
+
+  it('detaches on teardown', () => {
+    teardown();
+    store.setState({ items: [...store.getState().items, { id: 9, v: 1 }] });
+
+    expect(save).not.toHaveBeenCalled();
+  });
+});

src/app/orchestration/entity-persistence.ts

@@ -0,0 +1,64 @@
+/**
+ * Generic entity write-through (docs/architecture/01 §5).
+ *
+ * Every per-record store (snippets, datasets, custom themes, user fonts) persists
+ * the same way: watch its entity array, and on each change diff it against the
+ * previous snapshot by id reference — save what's new or changed, delete what's
+ * gone. Because store actions produce fresh object references for what they touch,
+ * a reference diff catches exactly the changed records (spec §09E one-record-per-
+ * entity tiers; a whole-store serializer like Zustand's `persist` middleware would
+ * rewrite every record on any change, so it doesn't fit).
+ *
+ * The per-entity `wire*Persistence` modules supply the store, the array selector,
+ * and the IndexedDB adapter + error toast; this owns the diff loop they shared.
+ */
+
+type Unsubscribe = () => void;
+
+/** Minimal store surface this needs — satisfied by any Zustand store. */
+interface StoreLike<S> {
+  getState: () => S;
+  subscribe: (listener: (state: S) => void) => Unsubscribe;
+}
+
+export interface EntityWriteThrough<T extends { id: string | number }> {
+  /** Persist a new or changed record. */
+  save: (entity: T) => Promise<void>;
+  /** Remove a record that's no longer in the array. Id type follows the entity's. */
+  remove: (id: T['id']) => Promise<void>;
+  /**
+   * Surface a failed write — these promises are otherwise fire-and-forget, so a
+   * rejection becomes a toast rather than silent data loss (spec §10 → "told when
+   * a save fails rather than losing data silently").
+   */
+  onError: (op: 'save' | 'delete', err: unknown) => void;
+}
+
+/**
+ * Persist upserts and deletions whenever a store's entity array changes. Returns
+ * a teardown that detaches the subscriber. Wire it AFTER the store is hydrated so
+ * the baseline is the loaded set — otherwise the first diff re-saves everything.
+ */
+export function wireEntityWriteThrough<S, T extends { id: string | number }>(
+  store: StoreLike<S>,
+  select: (state: S) => readonly T[],
+  io: EntityWriteThrough<T>,
+): Unsubscribe {
+  let prev = select(store.getState());
+  return store.subscribe((state) => {
+    const next = select(state);
+    if (next === prev) return;
+    const before = prev;
+    prev = next;
+
+    for (const old of before) {
+      if (!next.some((n) => n.id === old.id)) {
+        io.remove(old.id).catch((err) => io.onError('delete', err));
+      }
+    }
+    for (const n of next) {
+      const old = before.find((p) => p.id === n.id);
+      if (old !== n) io.save(n).catch((err) => io.onError('save', err)); // new or changed ref
+    }
+  });
+}

src/app/orchestration/font-persistence.ts

@@ -1,47 +1,25 @@
 /**
  * User font persistence wiring (docs/architecture/01 §5; scope doc §4 → fonts).
  *
- * The font sibling of `theme-persistence.ts`: a startup subscriber that diffs the
- * `fonts` array against the previous snapshot and writes upserts/deletes through
- * to the IndexedDB adapter. The store stays browser-free; failures surface as a
- * toast rather than silent loss. Fonts change on explicit add/delete, so there is
- * no debounce.
+ * A startup subscriber that write-throughs the `fonts` array to the IndexedDB
+ * adapter via the shared `wireEntityWriteThrough` diff loop. The store stays
+ * browser-free; failures surface as a toast rather than silent loss. Fonts change
+ * on explicit add/delete, so there is no debounce.
  */
 
 import { deleteFont, saveFont } from '../infrastructure/font-store';
+import { entityStorageErrorNotification } from '../services/storage-errors';
 import { notify } from '../stores/NotificationStore';
 import { useFontStore } from '../stores/FontStore';
+import { wireEntityWriteThrough } from './entity-persistence';
 
 type Unsubscribe = () => void;
 
-function fontError(op: 'save' | 'delete', err: unknown) {
-  notify({
-    kind: 'error',
-    title: op === 'delete' ? "Couldn't delete the font" : "Couldn't save the font",
-    message:
-      'A storage error stopped Astrolabe from completing the last font change, so it may not ' +
-      'survive a reload. If this keeps happening, your browser may be blocking local storage.',
-    detail: err instanceof Error ? `Font ${op} failed: ${err.name}: ${err.message}` : String(err),
-  });
-}
-
 /** Persist font upserts and deletions whenever the array changes. */
 export function wireFontPersistence(): Unsubscribe {
-  let prevFonts = useFontStore.getState().fonts;
-  return useFontStore.subscribe((s) => {
-    const next = s.fonts;
-    if (next === prevFonts) return;
-    const prev = prevFonts;
-    prevFonts = next;
-
-    for (const old of prev) {
-      if (!next.some((n) => n.id === old.id)) {
-        deleteFont(old.id).catch((err) => fontError('delete', err));
-      }
-    }
-    for (const n of next) {
-      const old = prev.find((p) => p.id === n.id);
-      if (old !== n) saveFont(n).catch((err) => fontError('save', err));
-    }
+  return wireEntityWriteThrough(useFontStore, (s) => s.fonts, {
+    save: saveFont,
+    remove: deleteFont,
+    onError: (op, err) => notify(entityStorageErrorNotification('font', op, err)),
   });
 }

src/app/orchestration/snippet-persistence.test.ts

@@ -9,14 +9,15 @@ import { createSnippet, type Snippet } from '@core/snippet';
  * no real database.
  */
 
-// Mock the adapter, but keep the real StorageQuotaError so the error-mapping
-// path (instanceof check) behaves exactly as in production.
+// Mock the adapter's writes. StorageQuotaError comes from the (unmocked) db
+// module, so the error-mapping path (instanceof check) behaves as in production.
 vi.mock('../infrastructure/snippet-store', async (importOriginal) => {
   const actual = await importOriginal<typeof import('../infrastructure/snippet-store')>();
   return { ...actual, saveSnippet: vi.fn(), deleteSnippet: vi.fn() };
 });
 
-import { saveSnippet, deleteSnippet, StorageQuotaError } from '../infrastructure/snippet-store';
+import { saveSnippet, deleteSnippet } from '../infrastructure/snippet-store';
+import { StorageQuotaError } from '../infrastructure/db';
 import { useNotificationStore } from '../stores/NotificationStore';
 import { useSnippetStore } from '../stores/SnippetStore';
 import { AUTOSAVE_DEBOUNCE_MS, wireSnippetPersistence } from './snippet-persistence';

src/app/orchestration/snippet-persistence.ts

@@ -6,17 +6,19 @@
  * through `infrastructure/`. Two subscribers:
  *
  *   1. Debounced auto-save: editor keystrokes (`draftText`) settle into a
- *      `commitDraft()` after a pause (spec §03B).
- *   2. Write-through: any change to the `snippets` array is diffed against the
- *      previous snapshot and persisted/deleted. Because commits and structural
- *      edits produce fresh object references, a reference diff catches exactly
- *      what changed.
+ *      `commitDraft()` after a pause (spec §03B). Snippet-specific — the other
+ *      entity tiers change on explicit actions, not per keystroke.
+ *   2. Write-through: the shared `wireEntityWriteThrough` diff loop persists any
+ *      change to the `snippets` array. Snippets use the richer
+ *      `storageErrorNotification` (quota + load aware) rather than the generic
+ *      entity toast.
  */
 
 import { deleteSnippet, saveSnippet } from '../infrastructure/snippet-store';
 import { storageErrorNotification } from '../services/storage-errors';
 import { notify } from '../stores/NotificationStore';
 import { useSnippetStore } from '../stores/SnippetStore';
+import { wireEntityWriteThrough } from './entity-persistence';
 
 /** Delay before a settled edit is committed to the stored draft (spec §03B). */
 export const AUTOSAVE_DEBOUNCE_MS = 400;
@@ -35,28 +37,10 @@ function wireDraftAutoSave(): Unsubscribe {
 
 /** Persist snippet upserts and deletions whenever the array changes. */
 function wireWriteThrough(): Unsubscribe {
-  let prevSnippets = useSnippetStore.getState().snippets;
-  return useSnippetStore.subscribe((s) => {
-    const next = s.snippets;
-    if (next === prevSnippets) return;
-    const prev = prevSnippets;
-    prevSnippets = next;
-
-    // A failed write must surface, not vanish — these promises are otherwise
-    // fire-and-forget, so a rejection becomes a toast rather than silent loss
-    // (spec §10 → "told when a save fails rather than losing data silently").
-    for (const old of prev) {
-      if (!next.some((n) => n.id === old.id)) {
-        deleteSnippet(old.id).catch((err) => notify(storageErrorNotification('delete', err)));
-      }
-    }
-    for (const n of next) {
-      const old = prev.find((p) => p.id === n.id);
-      if (old !== n) {
-        // new, or a changed reference
-        saveSnippet(n).catch((err) => notify(storageErrorNotification('save', err)));
-      }
-    }
+  return wireEntityWriteThrough(useSnippetStore, (s) => s.snippets, {
+    save: saveSnippet,
+    remove: deleteSnippet,
+    onError: (op, err) => notify(storageErrorNotification(op, err)),
   });
 }
 

src/app/orchestration/startup.ts

@@ -17,7 +17,10 @@ import { loadDatasets } from '../infrastructure/dataset-store';
 import { loadCustomThemes } from '../infrastructure/theme-store';
 import { loadFonts } from '../infrastructure/font-store';
 import { registerFontAssets } from '../infrastructure/font-faces';
-import { storageErrorNotification } from '../services/storage-errors';
+import {
+  entityStorageErrorNotification,
+  storageErrorNotification,
+} from '../services/storage-errors';
 import { notify } from '../stores/NotificationStore';
 import { useSnippetStore } from '../stores/SnippetStore';
 import { useDatasetStore } from '../stores/DatasetStore';
@@ -53,7 +56,7 @@ export async function initApp(): Promise<void> {
   try {
     datasets = await loadDatasets();
   } catch (err) {
-    notify(storageErrorNotification('load', err));
+    notify(entityStorageErrorNotification('dataset', 'load', err));
   }
 
   // Custom chart themes (spec §04 → Chart theme). Same failure posture: the
@@ -63,7 +66,7 @@ export async function initApp(): Promise<void> {
   try {
     themes = await loadCustomThemes();
   } catch (err) {
-    notify(storageErrorNotification('load', err));
+    notify(entityStorageErrorNotification('theme', 'load', err));
   }
 
   // User-uploaded font faces (scope doc §4). Same failure posture: a font that
@@ -73,7 +76,7 @@ export async function initApp(): Promise<void> {
   try {
     fonts = await loadFonts();
   } catch (err) {
-    notify(storageErrorNotification('load', err));
+    notify(entityStorageErrorNotification('font', 'load', err));
   }
 
   useSnippetStore.getState().hydrate(snippets);

src/app/orchestration/theme-persistence.ts

@@ -1,47 +1,25 @@
 /**
  * Custom theme persistence wiring (docs/architecture/01 §5; scope doc §4.4).
  *
- * The theme sibling of `dataset-persistence.ts`: a startup subscriber that
- * diffs the `themes` array against the previous snapshot and writes
- * upserts/deletes through to the IndexedDB adapter. The store stays
+ * A startup subscriber that write-throughs the `themes` array to the IndexedDB
+ * adapter via the shared `wireEntityWriteThrough` diff loop. The store stays
  * browser-free; failures surface as a toast rather than silent loss. Themes
  * change on explicit save/delete, so there is no debounce.
  */
 
 import { deleteCustomTheme, saveCustomTheme } from '../infrastructure/theme-store';
+import { entityStorageErrorNotification } from '../services/storage-errors';
 import { notify } from '../stores/NotificationStore';
 import { useCustomThemeStore } from '../stores/CustomThemeStore';
+import { wireEntityWriteThrough } from './entity-persistence';
 
 type Unsubscribe = () => void;
 
-function themeError(op: 'save' | 'delete', err: unknown) {
-  notify({
-    kind: 'error',
-    title: op === 'delete' ? "Couldn't delete the theme" : "Couldn't save the theme",
-    message:
-      'A storage error stopped Astrolabe from completing the last theme change, so it may not ' +
-      'survive a reload. If this keeps happening, your browser may be blocking local storage.',
-    detail: err instanceof Error ? `Theme ${op} failed: ${err.name}: ${err.message}` : String(err),
-  });
-}
-
 /** Persist theme upserts and deletions whenever the array changes. */
 export function wireThemePersistence(): Unsubscribe {
-  let prevThemes = useCustomThemeStore.getState().themes;
-  return useCustomThemeStore.subscribe((s) => {
-    const next = s.themes;
-    if (next === prevThemes) return;
-    const prev = prevThemes;
-    prevThemes = next;
-
-    for (const old of prev) {
-      if (!next.some((n) => n.id === old.id)) {
-        deleteCustomTheme(old.id).catch((err) => themeError('delete', err));
-      }
-    }
-    for (const n of next) {
-      const old = prev.find((p) => p.id === n.id);
-      if (old !== n) saveCustomTheme(n).catch((err) => themeError('save', err));
-    }
+  return wireEntityWriteThrough(useCustomThemeStore, (s) => s.themes, {
+    save: saveCustomTheme,
+    remove: deleteCustomTheme,
+    onError: (op, err) => notify(entityStorageErrorNotification('theme', op, err)),
   });
 }

src/app/services/storage-errors.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { StorageQuotaError } from '../infrastructure/snippet-store';
-import { storageErrorNotification } from './storage-errors';
+import { StorageQuotaError } from '../infrastructure/db';
+import { entityStorageErrorNotification, storageErrorNotification } from './storage-errors';
 
 describe('storageErrorNotification', () => {
   describe('a failure the user can fix (storage full)', () => {
@@ -43,3 +43,43 @@ describe('storageErrorNotification', () => {
     });
   });
 });
+
+describe('entityStorageErrorNotification', () => {
+  it('names the entity in the title, message, and diagnostic', () => {
+    const save = entityStorageErrorNotification('dataset', 'save', new Error('boom'));
+    expect(save.kind).toBe('error');
+    expect(save.title).toBe("Couldn't save the dataset");
+    expect(save.message).toContain('dataset change');
+    expect(save.detail).toBe('Dataset save failed: Error: boom'); // capitalized noun in trace
+
+    const del = entityStorageErrorNotification('font', 'delete', new Error('boom'));
+    expect(del.title).toBe("Couldn't delete the font");
+    expect(del.detail).toContain('Font delete failed');
+  });
+
+  it('detects a quota failure for any entity tier (not just snippets)', () => {
+    const n = entityStorageErrorNotification('dataset', 'save', new StorageQuotaError());
+    expect(n.title).toBe('Storage full');
+    expect(n.message.toLowerCase()).toContain('dataset');
+    expect(n.message.toLowerCase()).toContain('delete');
+    expect(n.detail).toBeUndefined(); // nothing to report — the fix is in the message
+  });
+
+  it('frames a load failure with the entity noun, not "snippets"', () => {
+    const n = entityStorageErrorNotification(
+      'dataset',
+      'load',
+      new DOMException('blocked', 'SecurityError'),
+    );
+    expect(n.title).toBe("Couldn't open your datasets");
+    expect(n.message).toContain('datasets');
+    expect(n.message).not.toContain('snippet');
+    expect(n.detail).toContain('load');
+    expect(n.detail).toContain('SecurityError');
+  });
+
+  it('describes a non-Error throw without crashing', () => {
+    const n = entityStorageErrorNotification('theme', 'save', 'weird string');
+    expect(n.detail).toBe('weird string');
+  });
+});

src/app/services/storage-errors.ts

@@ -13,7 +13,7 @@
  *     that failed + the underlying error) so it can be reported and traced.
  */
 
-import { StorageQuotaError } from '../infrastructure/snippet-store';
+import { StorageQuotaError } from '../infrastructure/db';
 import type { NotifyOptions } from '../stores/NotificationStore';
 
 /** Which persistence operation failed — shapes both the wording and the trace. */
@@ -73,3 +73,58 @@ export function storageErrorNotification(op: StorageOp, err: unknown): NotifyOpt
     detail: diagnostic(op, err),
   };
 }
+
+/**
+ * The storage-failure notification for the per-record entity tiers other than
+ * snippets (datasets, themes, fonts), parameterized by entity noun. Mirrors the
+ * snippet-flavored `storageErrorNotification` above — quota detection, the startup
+ * `load` failure, and the generic save/delete failure — but with the entity's own
+ * noun so a dataset error never reads "snippet". Snippets keep the bespoke function
+ * above (its "your library" / "your changes" framing is tuned to the silent
+ * save-on-edit model). `noun` is the lowercase singular ("dataset").
+ */
+export function entityStorageErrorNotification(
+  noun: string,
+  op: StorageOp,
+  err: unknown,
+): NotifyOptions {
+  const Noun = noun.charAt(0).toUpperCase() + noun.slice(1);
+  const plural = `${noun}s`;
+  const detail =
+    err instanceof Error ? `${Noun} ${op} failed: ${err.name}: ${err.message}` : String(err);
+
+  // Storage full — the one failure the user can act on. No detail: the next step
+  // is in the message. (Quota is whole-origin; per-tier framing is a parked UX
+  // nuance — see docs/ux-second-pass.md.)
+  if (err instanceof StorageQuotaError) {
+    return {
+      kind: 'error',
+      title: 'Storage full',
+      message:
+        `This ${noun} couldn't be saved because ${noun} storage is full. ` +
+        `Delete ${plural} you no longer need to free space, then try again.`,
+    };
+  }
+
+  // Couldn't read this tier on startup — almost always blocked storage.
+  if (op === 'load') {
+    return {
+      kind: 'error',
+      title: `Couldn't open your ${plural}`,
+      message:
+        `Astrolabe couldn't open local storage, so your saved ${plural} aren't available yet. ` +
+        'This usually means the browser is blocking storage — for example, private-browsing mode. ' +
+        'Reload to try again.',
+      detail,
+    };
+  }
+
+  return {
+    kind: 'error',
+    title: op === 'delete' ? `Couldn't delete the ${noun}` : `Couldn't save the ${noun}`,
+    message:
+      `A storage error stopped Astrolabe from completing the last ${noun} change, so it may not ` +
+      'survive a reload. If this keeps happening, your browser may be blocking local storage.',
+    detail,
+  };
+}

src/app/services/transfer.test.ts

@@ -24,7 +24,8 @@ import { createCustomTheme } from '@core/custom-theme';
 import { createDataset } from '@core/dataset';
 import { createSnippet } from '@core/snippet';
 import { downloadJson, readTextFile } from '../infrastructure/file-transfer';
-import { deleteSnippet, saveSnippet, StorageQuotaError } from '../infrastructure/snippet-store';
+import { deleteSnippet, saveSnippet } from '../infrastructure/snippet-store';
+import { StorageQuotaError } from '../infrastructure/db';
 import { useCustomThemeStore } from '../stores/CustomThemeStore';
 import { useDatasetStore } from '../stores/DatasetStore';
 import { useNotificationStore } from '../stores/NotificationStore';

src/app/services/transfer.ts

@@ -29,7 +29,8 @@ import {
 import { snippetSizeBytes } from '@core/snippet';
 import { humanizeBytes } from '@core/storage-estimate';
 import { downloadJson, readTextFile } from '../infrastructure/file-transfer';
-import { deleteSnippet, saveSnippet, StorageQuotaError } from '../infrastructure/snippet-store';
+import { deleteSnippet, saveSnippet } from '../infrastructure/snippet-store';
+import { StorageQuotaError } from '../infrastructure/db';
 import { notify } from '../stores/NotificationStore';
 import { useCustomThemeStore } from '../stores/CustomThemeStore';
 import { useDatasetStore } from '../stores/DatasetStore';