Merge pull request 'feature/unified-tanstack-query' (#36) from feature/unified-tanstack-query into main

Reviewed-on: #36

src/entities/Font/api/proxy/proxyFonts.test.ts

@@ -19,10 +19,13 @@ vi.mock('$shared/api/api', () => ({
 }));
 
 import { api } from '$shared/api/api';
+import { queryClient } from '$shared/api/queryClient';
+import { fontKeys } from '$shared/api/queryKeys';
 import {
     fetchFontsByIds,
     fetchProxyFontById,
     fetchProxyFonts,
+    seedFontCache,
 } from './proxyFonts';
 
 const PROXY_API_URL = 'https://api.glyphdiff.com/api/v1/fonts';
@@ -46,6 +49,7 @@ function mockApiGet<T>(data: T) {
 describe('proxyFonts', () => {
     beforeEach(() => {
         vi.mocked(api.get).mockReset();
+        queryClient.clear();
     });
 
     describe('fetchProxyFonts', () => {
@@ -168,4 +172,33 @@ describe('proxyFonts', () => {
             expect(result).toEqual([]);
         });
     });
+
+    describe('seedFontCache', () => {
+        test('should populate cache with multiple fonts', () => {
+            const fonts = [
+                createMockFont({ id: '1', name: 'A' }),
+                createMockFont({ id: '2', name: 'B' }),
+            ];
+            seedFontCache(fonts);
+            expect(queryClient.getQueryData(fontKeys.detail('1'))).toEqual(fonts[0]);
+            expect(queryClient.getQueryData(fontKeys.detail('2'))).toEqual(fonts[1]);
+        });
+
+        test('should update existing cached fonts with new data', () => {
+            const id = 'update-me';
+            queryClient.setQueryData(fontKeys.detail(id), createMockFont({ id, name: 'Old' }));
+
+            const updated = createMockFont({ id, name: 'New' });
+            seedFontCache([updated]);
+
+            expect(queryClient.getQueryData(fontKeys.detail(id))).toEqual(updated);
+        });
+
+        test('should handle empty input arrays gracefully', () => {
+            const spy = vi.spyOn(queryClient, 'setQueryData');
+            seedFontCache([]);
+            expect(spy).not.toHaveBeenCalled();
+            spy.mockRestore();
+        });
+    });
 });

src/entities/Font/api/proxy/proxyFonts.ts

@@ -11,13 +11,23 @@
  */
 
 import { api } from '$shared/api/api';
+import { queryClient } from '$shared/api/queryClient';
+import { fontKeys } from '$shared/api/queryKeys';
 import { buildQueryString } from '$shared/lib/utils';
 import type { QueryParams } from '$shared/lib/utils';
 import type { UnifiedFont } from '../../model/types';
-import type {
-    FontCategory,
-    FontSubset,
-} from '../../model/types';
+
+/**
+ * Normalizes cache by seeding individual font entries from collection responses.
+ * This ensures that a font fetched in a list or batch is available via its detail key.
+ *
+ * @param fonts - Array of fonts to cache
+ */
+export function seedFontCache(fonts: UnifiedFont[]): void {
+    fonts.forEach(font => {
+        queryClient.setQueryData(fontKeys.detail(font.id), font);
+    });
+}
 
 /**
  * Proxy API base URL

src/entities/Font/index.ts

@@ -1,3 +1,4 @@
 export * from './api';
+export * from './lib';
 export * from './model';
 export * from './ui';

src/entities/Font/lib/index.ts

@@ -48,3 +48,6 @@ export {
     FontNetworkError,
     FontResponseError,
 } from './errors/errors';
+
+export { createFontRowSizeResolver } from './sizeResolver/createFontRowSizeResolver';
+export type { FontRowSizeResolverOptions } from './sizeResolver/createFontRowSizeResolver';

src/entities/Font/lib/sizeResolver/createFontRowSizeResolver.test.ts

@@ -0,0 +1,168 @@
+// @vitest-environment jsdom
+import { TextLayoutEngine } from '$shared/lib';
+import { installCanvasMock } from '$shared/lib/helpers/__mocks__/canvas';
+import { clearCache } from '@chenglou/pretext';
+import {
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from 'vitest';
+import type { FontLoadStatus } from '../../model/types';
+import { mockUnifiedFont } from '../mocks';
+import { createFontRowSizeResolver } from './createFontRowSizeResolver';
+
+// Fixed-width canvas mock: every character is 10px wide regardless of font.
+// This makes wrapping math predictable: N chars × 10px = N×10 total width.
+const CHAR_WIDTH = 10;
+const LINE_HEIGHT = 20;
+const CONTAINER_WIDTH = 200;
+const CONTENT_PADDING_X = 32; // p-4 × 2 sides = 32px
+const CHROME_HEIGHT = 56;
+const FALLBACK_HEIGHT = 220;
+const FONT_SIZE_PX = 16;
+
+describe('createFontRowSizeResolver', () => {
+    let statusMap: Map<string, FontLoadStatus>;
+    let getStatus: (key: string) => FontLoadStatus | undefined;
+
+    beforeEach(() => {
+        installCanvasMock((_font, text) => text.length * CHAR_WIDTH);
+        clearCache();
+        statusMap = new Map();
+        getStatus = key => statusMap.get(key);
+    });
+
+    function makeResolver(overrides?: Partial<Parameters<typeof createFontRowSizeResolver>[0]>) {
+        const font = mockUnifiedFont({ id: 'inter', name: 'Inter' });
+        return {
+            font,
+            resolver: createFontRowSizeResolver({
+                getFonts: () => [font],
+                getWeight: () => 400,
+                getPreviewText: () => 'Hello',
+                getContainerWidth: () => CONTAINER_WIDTH,
+                getFontSizePx: () => FONT_SIZE_PX,
+                getLineHeightPx: () => LINE_HEIGHT,
+                getStatus,
+                contentHorizontalPadding: CONTENT_PADDING_X,
+                chromeHeight: CHROME_HEIGHT,
+                fallbackHeight: FALLBACK_HEIGHT,
+                ...overrides,
+            }),
+        };
+    }
+
+    it('returns fallbackHeight when font status is undefined', () => {
+        const { resolver } = makeResolver();
+        expect(resolver(0)).toBe(FALLBACK_HEIGHT);
+    });
+
+    it('returns fallbackHeight when font status is "loading"', () => {
+        const { resolver } = makeResolver();
+        statusMap.set('inter@400', 'loading');
+        expect(resolver(0)).toBe(FALLBACK_HEIGHT);
+    });
+
+    it('returns fallbackHeight when font status is "error"', () => {
+        const { resolver } = makeResolver();
+        statusMap.set('inter@400', 'error');
+        expect(resolver(0)).toBe(FALLBACK_HEIGHT);
+    });
+
+    it('returns fallbackHeight when containerWidth is 0', () => {
+        const { resolver } = makeResolver({ getContainerWidth: () => 0 });
+        statusMap.set('inter@400', 'loaded');
+        expect(resolver(0)).toBe(FALLBACK_HEIGHT);
+    });
+
+    it('returns fallbackHeight when previewText is empty', () => {
+        const { resolver } = makeResolver({ getPreviewText: () => '' });
+        statusMap.set('inter@400', 'loaded');
+        expect(resolver(0)).toBe(FALLBACK_HEIGHT);
+    });
+
+    it('returns fallbackHeight for out-of-bounds rowIndex', () => {
+        const { resolver } = makeResolver();
+        statusMap.set('inter@400', 'loaded');
+        expect(resolver(99)).toBe(FALLBACK_HEIGHT);
+    });
+
+    it('returns computed height (totalHeight + chromeHeight) when font is loaded', () => {
+        const { resolver } = makeResolver();
+        statusMap.set('inter@400', 'loaded');
+
+        // 'Hello' = 5 chars × 10px = 50px. contentWidth = 200 - 32 = 168px. Fits on one line.
+        // totalHeight = 1 × LINE_HEIGHT = 20. result = 20 + CHROME_HEIGHT = 76.
+        const result = resolver(0);
+        expect(result).toBe(LINE_HEIGHT + CHROME_HEIGHT);
+    });
+
+    it('returns increased height when text wraps due to narrow container', () => {
+        // contentWidth = 40 - 32 = 8px — 'Hello' (50px) forces wrapping onto many lines
+        const { resolver } = makeResolver({ getContainerWidth: () => 40 });
+        statusMap.set('inter@400', 'loaded');
+
+        const result = resolver(0);
+        expect(result).toBeGreaterThan(LINE_HEIGHT + CHROME_HEIGHT);
+    });
+
+    it('does not call layout() again on second call with same arguments', () => {
+        const { resolver } = makeResolver();
+        statusMap.set('inter@400', 'loaded');
+
+        const layoutSpy = vi.spyOn(TextLayoutEngine.prototype, 'layout');
+
+        resolver(0);
+        resolver(0);
+
+        expect(layoutSpy).toHaveBeenCalledTimes(1);
+        layoutSpy.mockRestore();
+    });
+
+    it('calls layout() again when containerWidth changes (cache miss)', () => {
+        let width = CONTAINER_WIDTH;
+        const { resolver } = makeResolver({ getContainerWidth: () => width });
+        statusMap.set('inter@400', 'loaded');
+
+        const layoutSpy = vi.spyOn(TextLayoutEngine.prototype, 'layout');
+
+        resolver(0);
+        width = 100;
+        resolver(0);
+
+        expect(layoutSpy).toHaveBeenCalledTimes(2);
+        layoutSpy.mockRestore();
+    });
+
+    it('returns greater height when container narrows (more wrapping)', () => {
+        let width = CONTAINER_WIDTH;
+        const { resolver } = makeResolver({ getContainerWidth: () => width });
+        statusMap.set('inter@400', 'loaded');
+
+        const h1 = resolver(0);
+        width = 100; // narrower → more wrapping
+        const h2 = resolver(0);
+
+        expect(h2).toBeGreaterThanOrEqual(h1);
+    });
+
+    it('uses variable font key for variable fonts', () => {
+        const vfFont = mockUnifiedFont({ id: 'roboto', name: 'Roboto', features: { isVariable: true } });
+        const { resolver } = makeResolver({ getFonts: () => [vfFont] });
+        // Variable fonts use '{id}@vf' key, not '{id}@{weight}'
+        statusMap.set('roboto@vf', 'loaded');
+        const result = resolver(0);
+        expect(result).not.toBe(FALLBACK_HEIGHT);
+        expect(result).toBeGreaterThan(0);
+    });
+
+    it('returns fallbackHeight for variable font when static key is set instead', () => {
+        const vfFont = mockUnifiedFont({ id: 'roboto', name: 'Roboto', features: { isVariable: true } });
+        const { resolver } = makeResolver({ getFonts: () => [vfFont] });
+        // Setting the static key should NOT unlock computed height for variable fonts
+        statusMap.set('roboto@400', 'loaded');
+        expect(resolver(0)).toBe(FALLBACK_HEIGHT);
+    });
+});

src/entities/Font/lib/sizeResolver/createFontRowSizeResolver.ts

@@ -0,0 +1,112 @@
+import { TextLayoutEngine } from '$shared/lib';
+import { generateFontKey } from '../../model/store/appliedFontsStore/utils/generateFontKey/generateFontKey';
+import type {
+    FontLoadStatus,
+    UnifiedFont,
+} from '../../model/types';
+
+/**
+ * Options for {@link createFontRowSizeResolver}.
+ *
+ * All getter functions are called on every resolver invocation. When called
+ * inside a Svelte `$derived.by` block, any reactive state read within them
+ * (e.g. `SvelteMap.get()`) is automatically tracked as a dependency.
+ */
+export interface FontRowSizeResolverOptions {
+    /** Returns the current fonts array. Index `i` corresponds to row `i`. */
+    getFonts: () => UnifiedFont[];
+    /** Returns the active font weight (e.g. 400). */
+    getWeight: () => number;
+    /** Returns the preview text string. */
+    getPreviewText: () => string;
+    /** Returns the scroll container's inner width in pixels. Returns 0 before mount. */
+    getContainerWidth: () => number;
+    /** Returns the font size in pixels (e.g. `controlManager.renderedSize`). */
+    getFontSizePx: () => number;
+    /**
+     * Returns the computed line height in pixels.
+     * Typically `controlManager.height * controlManager.renderedSize`.
+     */
+    getLineHeightPx: () => number;
+    /**
+     * Returns the font load status for a given font key (`'{id}@{weight}'` or `'{id}@vf'`).
+     *
+     * In production: `(key) => appliedFontsManager.statuses.get(key)`.
+     * Injected for testability — avoids a module-level singleton dependency in tests.
+     * The call to `.get()` on a `SvelteMap` must happen inside a `$derived.by` context
+     * for reactivity to work. This is satisfied when `itemHeight` is called by
+     * `createVirtualizer`'s `estimateSize`.
+     */
+    getStatus: (fontKey: string) => FontLoadStatus | undefined;
+    /**
+     * Total horizontal padding of the text content area in pixels.
+     * Use the smallest breakpoint value (mobile `p-4` = 32px) to guarantee
+     * the content width is never over-estimated, keeping the height estimate safe.
+     */
+    contentHorizontalPadding: number;
+    /** Fixed height in pixels of chrome that is not text content (header bar, etc.). */
+    chromeHeight: number;
+    /** Height in pixels to return when the font is not loaded or container width is 0. */
+    fallbackHeight: number;
+}
+
+/**
+ * Creates a row-height resolver for `FontSampler` rows in `VirtualList`.
+ *
+ * The returned function is suitable as the `itemHeight` prop of `VirtualList`.
+ * Pass it from the widget layer (`SampleList`) so that typography values from
+ * `controlManager` are injected as getter functions rather than imported directly,
+ * keeping `$entities/Font` free of `$features` dependencies.
+ *
+ * **Reactivity:** When the returned function reads `getStatus()` inside a
+ * `$derived.by` block (as `estimateSize` does in `createVirtualizer`), any
+ * `SvelteMap.get()` call within `getStatus` registers a Svelte 5 dependency.
+ * When a font's status changes to `'loaded'`, `offsets` recomputes automatically —
+ * no DOM snap occurs.
+ *
+ * **Caching:** A `Map` keyed by `fontCssString|text|contentWidth|lineHeightPx`
+ * prevents redundant `TextLayoutEngine.layout()` calls. The cache is invalidated
+ * naturally because a change in any input produces a different cache key.
+ *
+ * @param options - Configuration and getter functions (all injected for testability).
+ * @returns A function `(rowIndex: number) => number` for use as `VirtualList.itemHeight`.
+ */
+export function createFontRowSizeResolver(options: FontRowSizeResolverOptions): (rowIndex: number) => number {
+    const engine = new TextLayoutEngine();
+    // Key: `${fontCssString}|${text}|${contentWidth}|${lineHeightPx}`
+    const cache = new Map<string, number>();
+
+    return function resolveRowHeight(rowIndex: number): number {
+        const fonts = options.getFonts();
+        const font = fonts[rowIndex];
+        if (!font) return options.fallbackHeight;
+
+        const containerWidth = options.getContainerWidth();
+        const previewText = options.getPreviewText();
+
+        if (containerWidth <= 0 || !previewText) return options.fallbackHeight;
+
+        const weight = options.getWeight();
+        // generateFontKey: '{id}@{weight}' for static fonts, '{id}@vf' for variable fonts.
+        const fontKey = generateFontKey({ id: font.id, weight, isVariable: font.features?.isVariable });
+
+        // Reading via getStatus() allows the caller to pass appliedFontsManager.statuses.get(),
+        // which creates a Svelte 5 reactive dependency when called inside $derived.by.
+        const status = options.getStatus(fontKey);
+        if (status !== 'loaded') return options.fallbackHeight;
+
+        const fontSizePx = options.getFontSizePx();
+        const lineHeightPx = options.getLineHeightPx();
+        const contentWidth = containerWidth - options.contentHorizontalPadding;
+        const fontCssString = `${weight} ${fontSizePx}px "${font.name}"`;
+
+        const cacheKey = `${fontCssString}|${previewText}|${contentWidth}|${lineHeightPx}`;
+        const cached = cache.get(cacheKey);
+        if (cached !== undefined) return cached;
+
+        const { totalHeight } = engine.layout(previewText, fontCssString, contentWidth, lineHeightPx);
+        const result = totalHeight + options.chromeHeight;
+        cache.set(cacheKey, result);
+        return result;
+    };
+}

src/entities/Font/model/index.ts

@@ -1,7 +1,2 @@
-export {
-    appliedFontsManager,
-    createFontStore,
-    FontStore,
-    fontStore,
-} from './store';
+export * from './store';
 export * from './types';

src/entities/Font/model/store/batchFontStore.svelte.ts

@@ -0,0 +1,91 @@
+import { fontKeys } from '$shared/api/queryKeys';
+import { BaseQueryStore } from '$shared/lib/helpers/BaseQueryStore.svelte';
+import {
+    fetchFontsByIds,
+    seedFontCache,
+} from '../../api/proxy/proxyFonts';
+import {
+    FontNetworkError,
+    FontResponseError,
+} from '../../lib/errors/errors';
+import type { UnifiedFont } from '../../model/types';
+
+/**
+ * Internal fetcher that seeds the cache and handles error wrapping.
+ * Standalone function to avoid 'this' issues during construction.
+ */
+async function fetchAndSeed(ids: string[]): Promise<UnifiedFont[]> {
+    if (ids.length === 0) return [];
+
+    let response: UnifiedFont[];
+    try {
+        response = await fetchFontsByIds(ids);
+    } catch (cause) {
+        throw new FontNetworkError(cause);
+    }
+
+    if (!response || !Array.isArray(response)) {
+        throw new FontResponseError('batchResponse', response);
+    }
+
+    seedFontCache(response);
+    return response;
+}
+
+/**
+ * Reactive store for fetching and caching batches of fonts by ID.
+ * Integrates with TanStack Query via BaseQueryStore and handles
+ * normalized cache seeding.
+ */
+export class BatchFontStore extends BaseQueryStore<UnifiedFont[]> {
+    constructor(initialIds: string[] = []) {
+        super({
+            queryKey: fontKeys.batch(initialIds),
+            queryFn: () => fetchAndSeed(initialIds),
+            enabled: initialIds.length > 0,
+            retry: false,
+        });
+    }
+
+    /**
+     * Updates the IDs to fetch. Triggers a new query.
+     *
+     * @param ids - Array of font IDs
+     */
+    setIds(ids: string[]): void {
+        this.updateOptions({
+            queryKey: fontKeys.batch(ids),
+            queryFn: () => fetchAndSeed(ids),
+            enabled: ids.length > 0,
+            retry: false,
+        });
+    }
+
+    /**
+     * Array of fetched fonts
+     */
+    get fonts(): UnifiedFont[] {
+        return this.result.data ?? [];
+    }
+
+    /**
+     * Whether the query is currently loading
+     */
+    get isLoading(): boolean {
+        return this.result.isLoading;
+    }
+
+    /**
+     * Whether the query encountered an error
+     */
+    get isError(): boolean {
+        return this.result.isError;
+    }
+
+    /**
+     * The error object if the query failed
+     */
+    get error(): Error | null {
+        return (this.result.error as Error) ?? null;
+    }
+}

src/entities/Font/model/store/batchFontStore.test.ts

@@ -0,0 +1,107 @@
+import { queryClient } from '$shared/api/queryClient';
+import { fontKeys } from '$shared/api/queryKeys';
+import {
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from 'vitest';
+import * as api from '../../api/proxy/proxyFonts';
+import {
+    FontNetworkError,
+    FontResponseError,
+} from '../../lib/errors/errors';
+import { BatchFontStore } from './batchFontStore.svelte';
+
+describe('BatchFontStore', () => {
+    beforeEach(() => {
+        queryClient.clear();
+        vi.clearAllMocks();
+    });
+
+    describe('Fetch Behavior', () => {
+        it('should skip fetch when initialized with empty IDs', async () => {
+            const spy = vi.spyOn(api, 'fetchFontsByIds');
+            const store = new BatchFontStore([]);
+            expect(spy).not.toHaveBeenCalled();
+            expect(store.fonts).toEqual([]);
+        });
+
+        it('should fetch and seed cache for valid IDs', async () => {
+            const fonts = [{ id: 'a', name: 'A' }] as any[];
+            vi.spyOn(api, 'fetchFontsByIds').mockResolvedValue(fonts);
+            const store = new BatchFontStore(['a']);
+            await vi.waitFor(() => expect(store.fonts).toEqual(fonts), { timeout: 1000 });
+            expect(queryClient.getQueryData(fontKeys.detail('a'))).toEqual(fonts[0]);
+        });
+    });
+
+    describe('Loading States', () => {
+        it('should transition through loading state', async () => {
+            vi.spyOn(api, 'fetchFontsByIds').mockImplementation(() =>
+                new Promise(r => setTimeout(() => r([{ id: 'a' }] as any), 50))
+            );
+            const store = new BatchFontStore(['a']);
+            expect(store.isLoading).toBe(true);
+            await vi.waitFor(() => expect(store.isLoading).toBe(false), { timeout: 1000 });
+        });
+    });
+
+    describe('Error Handling', () => {
+        it('should wrap network failures in FontNetworkError', async () => {
+            vi.spyOn(api, 'fetchFontsByIds').mockRejectedValue(new Error('Network fail'));
+            const store = new BatchFontStore(['a']);
+            await vi.waitFor(() => expect(store.isError).toBe(true), { timeout: 1000 });
+            expect(store.error).toBeInstanceOf(FontNetworkError);
+        });
+
+        it('should handle malformed API responses with FontResponseError', async () => {
+            // Mocking a malformed response that the store should validate
+            vi.spyOn(api, 'fetchFontsByIds').mockResolvedValue(null as any);
+            const store = new BatchFontStore(['a']);
+            await vi.waitFor(() => expect(store.isError).toBe(true), { timeout: 1000 });
+            expect(store.error).toBeInstanceOf(FontResponseError);
+        });
+
+        it('should have null error in success state', async () => {
+            const fonts = [{ id: 'a' }] as any[];
+            vi.spyOn(api, 'fetchFontsByIds').mockResolvedValue(fonts);
+            const store = new BatchFontStore(['a']);
+            await vi.waitFor(() => expect(store.fonts).toEqual(fonts), { timeout: 1000 });
+            expect(store.error).toBeNull();
+        });
+    });
+
+    describe('Disable Behavior', () => {
+        it('should return empty fonts and not fetch when setIds is called with empty array', async () => {
+            const fonts1 = [{ id: 'a' }] as any[];
+            const spy = vi.spyOn(api, 'fetchFontsByIds').mockResolvedValueOnce(fonts1);
+
+            const store = new BatchFontStore(['a']);
+            await vi.waitFor(() => expect(store.fonts).toEqual(fonts1), { timeout: 1000 });
+
+            spy.mockClear();
+            store.setIds([]);
+
+            await vi.waitFor(() => expect(store.fonts).toEqual([]), { timeout: 1000 });
+            expect(spy).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('Reactivity', () => {
+        it('should refetch when setIds is called', async () => {
+            const fonts1 = [{ id: 'a' }] as any[];
+            const fonts2 = [{ id: 'b' }] as any[];
+            vi.spyOn(api, 'fetchFontsByIds')
+                .mockResolvedValueOnce(fonts1)
+                .mockResolvedValueOnce(fonts2);
+
+            const store = new BatchFontStore(['a']);
+            await vi.waitFor(() => expect(store.fonts).toEqual(fonts1), { timeout: 1000 });
+
+            store.setIds(['b']);
+            await vi.waitFor(() => expect(store.fonts).toEqual(fonts2), { timeout: 1000 });
+        });
+    });
+});

src/entities/Font/model/store/index.ts

@@ -1,6 +1,9 @@
 // Applied fonts manager
 export { appliedFontsManager } from './appliedFontsStore/appliedFontsStore.svelte';
 
+// Batch font store
+export { BatchFontStore } from './batchFontStore.svelte';
+
 // Single FontStore
 export {
     createFontStore,

src/shared/api/queryKeys.test.ts

@@ -0,0 +1,73 @@
+import {
+    describe,
+    expect,
+    it,
+} from 'vitest';
+import { fontKeys } from './queryKeys';
+
+describe('fontKeys', () => {
+    describe('Hierarchy', () => {
+        it('should generate base keys', () => {
+            expect(fontKeys.all).toEqual(['fonts']);
+            expect(fontKeys.lists()).toEqual(['fonts', 'list']);
+            expect(fontKeys.batches()).toEqual(['fonts', 'batch']);
+            expect(fontKeys.details()).toEqual(['fonts', 'detail']);
+        });
+    });
+
+    describe('Batch Keys (Stability & Sorting)', () => {
+        it('should sort IDs for stable serialization', () => {
+            const key1 = fontKeys.batch(['b', 'a', 'c']);
+            const key2 = fontKeys.batch(['c', 'b', 'a']);
+            const expected = ['fonts', 'batch', ['a', 'b', 'c']];
+            expect(key1).toEqual(expected);
+            expect(key2).toEqual(expected);
+        });
+
+        it('should handle empty ID arrays', () => {
+            expect(fontKeys.batch([])).toEqual(['fonts', 'batch', []]);
+        });
+
+        it('should not mutate the input array when sorting', () => {
+            const ids = ['c', 'b', 'a'];
+            fontKeys.batch(ids);
+            expect(ids).toEqual(['c', 'b', 'a']);
+        });
+
+        it('batch key should be rooted in batches() base', () => {
+            const key = fontKeys.batch(['a']);
+            expect(key.slice(0, 2)).toEqual(fontKeys.batches());
+        });
+    });
+
+    describe('List Keys (Parameters)', () => {
+        it('should include parameters in list keys', () => {
+            const params = { provider: 'google' };
+            expect(fontKeys.list(params)).toEqual(['fonts', 'list', params]);
+        });
+
+        it('should handle empty parameters', () => {
+            expect(fontKeys.list({})).toEqual(['fonts', 'list', {}]);
+        });
+
+        it('list key should be rooted in lists() base', () => {
+            const key = fontKeys.list({ provider: 'google' });
+            expect(key.slice(0, 2)).toEqual(fontKeys.lists());
+        });
+    });
+
+    describe('Detail Keys', () => {
+        it('should generate unique detail keys per ID', () => {
+            expect(fontKeys.detail('roboto')).toEqual(['fonts', 'detail', 'roboto']);
+        });
+
+        it('should generate different keys for different IDs', () => {
+            expect(fontKeys.detail('roboto')).not.toEqual(fontKeys.detail('open-sans'));
+        });
+
+        it('detail key should be rooted in details() base', () => {
+            const key = fontKeys.detail('roboto');
+            expect(key.slice(0, 2)).toEqual(fontKeys.details());
+        });
+    });
+});

src/shared/api/queryKeys.ts

@@ -0,0 +1,23 @@
+/**
+ * Stable query key factory for font-related queries.
+ * Ensures consistent serialization for batch requests by sorting IDs.
+ */
+export const fontKeys = {
+    /** Base key for all font queries */
+    all: ['fonts'] as const,
+
+    /** Keys for font list queries */
+    lists: () => [...fontKeys.all, 'list'] as const,
+    /** Specific font list key with filter parameters */
+    list: (params: object) => [...fontKeys.lists(), params] as const,
+
+    /** Keys for font batch queries */
+    batches: () => [...fontKeys.all, 'batch'] as const,
+    /** Specific batch key, sorted for stability */
+    batch: (ids: string[]) => [...fontKeys.batches(), [...ids].sort()] as const,
+
+    /** Keys for font detail queries */
+    details: () => [...fontKeys.all, 'detail'] as const,
+    /** Specific font detail key by ID */
+    detail: (id: string) => [...fontKeys.details(), id] as const,
+} as const;

src/shared/lib/helpers/BaseQueryStore.svelte.ts

@@ -0,0 +1,51 @@
+import { queryClient } from '$shared/api/queryClient';
+import {
+    QueryObserver,
+    type QueryObserverOptions,
+    type QueryObserverResult,
+} from '@tanstack/query-core';
+
+/**
+ * Abstract base class for reactive Svelte 5 stores backed by TanStack Query.
+ *
+ * Provides a unified way to use TanStack Query observers within Svelte 5 classes
+ * using runes for reactivity. Handles subscription lifecycle automatically.
+ *
+ * @template TData - The type of data returned by the query.
+ * @template TError - The type of error that can be thrown.
+ */
+export abstract class BaseQueryStore<TData, TError = Error> {
+    #result = $state<QueryObserverResult<TData, TError>>({} as QueryObserverResult<TData, TError>);
+    #observer: QueryObserver<TData, TError>;
+    #unsubscribe: () => void;
+
+    constructor(options: QueryObserverOptions<TData, TError, TData, any, any>) {
+        this.#observer = new QueryObserver(queryClient, options);
+        this.#unsubscribe = this.#observer.subscribe(result => {
+            this.#result = result;
+        });
+    }
+
+    /**
+     * Current query result (reactive)
+     */
+    protected get result(): QueryObserverResult<TData, TError> {
+        return this.#result;
+    }
+
+    /**
+     * Updates observer options dynamically.
+     * Use this when query parameters or dependencies change.
+     */
+    protected updateOptions(options: QueryObserverOptions<TData, TError, TData, any, any>): void {
+        this.#observer.setOptions(options);
+    }
+
+    /**
+     * Cleans up the observer subscription.
+     * Should be called when the store is no longer needed.
+     */
+    destroy(): void {
+        this.#unsubscribe();
+    }
+}

src/shared/lib/helpers/BaseQueryStore.test.ts

@@ -0,0 +1,91 @@
+import { queryClient } from '$shared/api/queryClient';
+import {
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from 'vitest';
+import { BaseQueryStore } from './BaseQueryStore.svelte';
+
+class TestStore extends BaseQueryStore<string> {
+    constructor(key = ['test'], fn = () => Promise.resolve('ok')) {
+        super({
+            queryKey: key,
+            queryFn: fn,
+            retry: false, // Disable retries for faster error testing
+        });
+    }
+    get data() {
+        return this.result.data;
+    }
+    get isLoading() {
+        return this.result.isLoading;
+    }
+    get isError() {
+        return this.result.isError;
+    }
+
+    update(newKey: string[], newFn?: () => Promise<string>) {
+        this.updateOptions({
+            queryKey: newKey,
+            queryFn: newFn ?? (() => Promise.resolve('ok')),
+            retry: false,
+        });
+    }
+}
+
+import * as tq from '@tanstack/query-core';
+
+// ... (TestStore remains same)
+
+describe('BaseQueryStore', () => {
+    beforeEach(() => {
+        queryClient.clear();
+    });
+
+    describe('Lifecycle & Fetching', () => {
+        it('should transition from loading to success', async () => {
+            const store = new TestStore();
+            expect(store.isLoading).toBe(true);
+            await vi.waitFor(() => expect(store.data).toBe('ok'), { timeout: 1000 });
+            expect(store.isLoading).toBe(false);
+        });
+
+        it('should have undefined data and no error in initial loading state', () => {
+            const store = new TestStore(['initial-state'], () => new Promise(r => setTimeout(() => r('late'), 500)));
+            expect(store.data).toBeUndefined();
+            expect(store.isError).toBe(false);
+        });
+    });
+
+    describe('Error Handling', () => {
+        it('should handle query failures', async () => {
+            const store = new TestStore(['fail'], () => Promise.reject(new Error('fail')));
+            await vi.waitFor(() => expect(store.isError).toBe(true), { timeout: 1000 });
+        });
+    });
+
+    describe('Reactivity', () => {
+        it('should refetch and update data when options change', async () => {
+            const store = new TestStore(['key1'], () => Promise.resolve('val1'));
+            await vi.waitFor(() => expect(store.data).toBe('val1'), { timeout: 1000 });
+
+            store.update(['key2'], () => Promise.resolve('val2'));
+            await vi.waitFor(() => expect(store.data).toBe('val2'), { timeout: 1000 });
+        });
+    });
+
+    describe('Cleanup', () => {
+        it('should unsubscribe observer on destroy', () => {
+            const unsubscribe = vi.fn();
+            const subscribeSpy = vi.spyOn(tq.QueryObserver.prototype, 'subscribe').mockReturnValue(unsubscribe);
+
+            const store = new TestStore();
+            store.destroy();
+
+            expect(unsubscribe).toHaveBeenCalled();
+            subscribeSpy.mockRestore();
+        });
+    });
+});

src/shared/lib/helpers/CharacterComparisonEngine/CharacterComparisonEngine.svelte.ts

@@ -5,25 +5,64 @@ import {
 } from '@chenglou/pretext';
 
 /**
- * Result of dual-font comparison layout
+ * A single laid-out line produced by dual-font comparison layout.
+ *
+ * Line breaking is determined by the unified worst-case widths, so both fonts
+ * always break at identical positions. Per-character `xA`/`xB` offsets reflect
+ * each font's actual advance widths independently.
  */
 export interface ComparisonLine {
+    /** Full text of this line as returned by pretext. */
     text: string;
-    width: number; // Max width between font A and B
+    /** Rendered width of this line in pixels — maximum across font A and font B. */
+    width: number;
     chars: Array<{
+        /** The grapheme cluster string (may be >1 code unit for emoji, etc.). */
         char: string;
-        xA: number; // X offset in font A
+        /** X offset from the start of the line in font A, in pixels. */
+        xA: number;
+        /** Advance width of this grapheme in font A, in pixels. */
         widthA: number;
-        xB: number; // X offset in font B
+        /** X offset from the start of the line in font B, in pixels. */
+        xB: number;
+        /** Advance width of this grapheme in font B, in pixels. */
         widthB: number;
     }>;
 }
 
+/**
+ * Aggregated output of a dual-font layout pass.
+ */
 export interface ComparisonResult {
+    /** Per-line grapheme data for both fonts. Empty when input text is empty. */
     lines: ComparisonLine[];
+    /** Total height in pixels. Equals `lines.length * lineHeight` (pretext guarantee). */
     totalHeight: number;
 }
 
+/**
+ * Dual-font text layout engine backed by `@chenglou/pretext`.
+ *
+ * Computes identical line breaks for two fonts simultaneously by constructing a
+ * "unified" prepared-text object whose per-glyph widths are the worst-case maximum
+ * of font A and font B. This guarantees that both fonts wrap at exactly the same
+ * positions, making side-by-side or slider comparison visually coherent.
+ *
+ * **Two-level caching strategy**
+ * 1. Font-change cache (`#preparedA`, `#preparedB`, `#unifiedPrepared`): rebuilt only
+ *    when `text`, `fontA`, or `fontB` changes. `prepareWithSegments` is expensive
+ *    (canvas measurement), so this avoids re-measuring during slider interaction.
+ * 2. Layout cache (`#lastResult`): rebuilt when `width` or `lineHeight` changes but
+ *    the fonts have not changed. Line-breaking is cheap relative to measurement, but
+ *    still worth skipping on every render tick.
+ *
+ * **`as any` casts:** `PreparedTextWithSegments` exposes only the `segments` field in
+ * its public TypeScript type. The numeric arrays (`widths`, `breakableFitAdvances`,
+ * `lineEndFitAdvances`, `lineEndPaintAdvances`) are internal implementation details of
+ * pretext that are not part of the published type signature. The casts are required to
+ * access these fields; they are verified against the pretext source at
+ * `node_modules/@chenglou/pretext/src/layout.ts`.
+ */
 export class CharacterComparisonEngine {
     #segmenter: Intl.Segmenter;
 
@@ -46,8 +85,17 @@ export class CharacterComparisonEngine {
     }
 
     /**
-     * Unified layout for two fonts
-     * Ensures consistent line breaks by taking the worst-case width
+     * Lay out `text` using both fonts within `width` pixels.
+     *
+     * Line breaks are determined by the worst-case (maximum) glyph widths across
+     * both fonts, so both fonts always wrap at identical positions.
+     *
+     * @param text       Raw text to lay out.
+     * @param fontA      CSS font string for the first font: `"weight sizepx \"family\""`.
+     * @param fontB      CSS font string for the second font: `"weight sizepx \"family\""`.
+     * @param width      Available line width in pixels.
+     * @param lineHeight Line height in pixels (passed directly to pretext).
+     * @returns          Per-line grapheme data for both fonts. Empty `lines` when `text` is empty.
      */
     layout(
         text: string,
@@ -82,7 +130,9 @@ export class CharacterComparisonEngine {
             return { lines: [], totalHeight: 0 };
         }
 
-        // 2. Layout using the unified widths
+        // 2. Layout using the unified widths.
+        // `PreparedTextWithSegments` only exposes `segments` in its public type; cast to `any`
+        // so pretext's layoutWithLines can read the internal numeric arrays at runtime.
         const { lines, height } = layoutWithLines(this.#unifiedPrepared as any, width, lineHeight);
 
         // 3. Map results back to both fonts
@@ -94,6 +144,7 @@ export class CharacterComparisonEngine {
             const start = line.start;
             const end = line.end;
 
+            // Cast to `any`: accessing internal numeric arrays not in the public type signature.
             const intA = this.#preparedA as any;
             const intB = this.#preparedB as any;
 
@@ -145,14 +196,24 @@ export class CharacterComparisonEngine {
     }
 
     /**
-     * Calculates character state without any DOM calls
+     * Calculates character proximity and direction relative to a slider position.
+     *
+     * Uses the most recent `layout()` result — must be called after `layout()`.
+     * No DOM calls are made; all geometry is derived from cached layout data.
+     *
+     * @param lineIndex      Zero-based index of the line within the last layout result.
+     * @param charIndex      Zero-based index of the character within that line's `chars` array.
+     * @param sliderPos      Current slider position as a percentage (0–100) of `containerWidth`.
+     * @param containerWidth Total container width in pixels, used to convert pixel offsets to %.
+     * @returns              `proximity` in [0, 1] (1 = slider exactly over char center) and
+     *                       `isPast` (true when the slider has already passed the char center).
      */
     getCharState(
         lineIndex: number,
         charIndex: number,
-        sliderPos: number, // 0-100 percentage
+        sliderPos: number,
         containerWidth: number,
-    ) {
+    ): { proximity: number; isPast: boolean } {
         if (!this.#lastResult || !this.#lastResult.lines[lineIndex]) {
             return { proximity: 0, isPast: false };
         }
@@ -181,6 +242,7 @@ export class CharacterComparisonEngine {
      * Internal helper to merge two prepared texts into a "worst-case" unified version
      */
     #createUnifiedPrepared(a: PreparedTextWithSegments, b: PreparedTextWithSegments): PreparedTextWithSegments {
+        // Cast to `any`: accessing internal numeric arrays not in the public type signature.
         const intA = a as any;
         const intB = b as any;
 

src/shared/lib/helpers/CharacterComparisonEngine/CharacterComparisonEngine.test.ts

@@ -36,7 +36,7 @@ describe('CharacterComparisonEngine', () => {
         expect(result.totalHeight).toBe(0);
     });
 
-    it('uses worst-case (FontB) width to determine line breaks', () => {
+    it('uses worst-case width across both fonts to determine line breaks', () => {
         // 'AB CD' — two 2-char words separated by a space.
         // FontA: 'AB'=20px, 'CD'=20px. Both fit in 25px? No: 'AB CD' = 50px total.
         // FontB: 'AB'=30px, 'CD'=30px. Width 35px forces wrap after 'AB '.

src/shared/lib/helpers/TextLayoutEngine/TextLayoutEngine.svelte.ts

@@ -24,7 +24,11 @@ export interface LayoutLine {
     }>;
 }
 
+/**
+ * Aggregated output of a single-font layout pass.
+ */
 export interface LayoutResult {
+    /** Per-line grapheme data. Empty when input text is empty. */
     lines: LayoutLine[];
     /** Total height in pixels. Equals `lines.length * lineHeight` (pretext guarantee). */
     totalHeight: number;
@@ -61,6 +65,7 @@ export class TextLayoutEngine {
      */
     #segmenter: Intl.Segmenter;
 
+    /** @param locale BCP 47 language tag passed to Intl.Segmenter. Defaults to the runtime locale. */
     constructor(locale?: string) {
         this.#segmenter = new Intl.Segmenter(locale, { granularity: 'grapheme' });
     }

src/shared/lib/helpers/createVirtualizer/createVirtualizer.svelte.ts

@@ -50,6 +50,14 @@ export interface VirtualizerOptions {
     /**
      * Function to estimate the size of an item at a given index.
      * Used for initial layout before actual measurements are available.
+     *
+     * Called inside a `$derived.by` block. Any `$state` or `$derived` value
+     * read within this function is automatically tracked as a dependency —
+     * when those values change, `offsets` and `totalSize` recompute instantly.
+     *
+     * For font preview rows, pass a closure that reads
+     * `appliedFontsManager.statuses` so the virtualizer recalculates heights
+     * as fonts finish loading, eliminating the DOM-measurement snap on load.
      */
     estimateSize: (index: number) => number;
     /** Number of extra items to render outside viewport for smoother scrolling (default: 5) */
@@ -71,6 +79,18 @@ export interface VirtualizerOptions {
     useWindowScroll?: boolean;
 }
 
+/**
+ * A height resolver for a single virtual-list row.
+ *
+ * When this function reads reactive state (e.g. `SvelteMap.get()`), calling
+ * it inside a `$derived.by` block automatically subscribes to that state.
+ * Return `fallbackHeight` whenever the true height is not yet known.
+ *
+ * @param rowIndex  Zero-based row index within the data array.
+ * @returns         Row height in pixels, excluding the list gap.
+ */
+export type ItemSizeResolver = (rowIndex: number) => number;
+
 /**
  * Creates a reactive virtualizer for efficiently rendering large lists by only rendering visible items.
  *

src/widgets/ComparisonView/model/stores/comparisonStore.svelte.ts

@@ -1,5 +1,5 @@
 /**
- * Font comparison store for side-by-side font comparison
+ * Font comparison store — TanStack Query refactor
  *
  * Manages the state for comparing two fonts character by character.
  * Persists font selection to localStorage and handles font loading
@@ -7,22 +7,26 @@
  *
  * Features:
  * - Persistent font selection (survives page refresh)
- * - Font loading state tracking
+ * - Font loading state tracking via BatchFontStore + TanStack Query
  * - Sample text management
  * - Typography controls (size, weight, line height, spacing)
  * - Slider position for character-by-character morphing
  */
 
 import {
+    BatchFontStore,
+    type FontLoadRequestConfig,
     type UnifiedFont,
-    fetchFontsByIds,
+    appliedFontsManager,
     fontStore,
+    getFontUrl,
 } from '$entities/Font';
 import {
     DEFAULT_TYPOGRAPHY_CONTROLS_DATA,
     createTypographyControlManager,
 } from '$features/SetupFont';
 import { createPersistentStore } from '$shared/lib';
+import { untrack } from 'svelte';
 
 /**
  * Storage schema for comparison state
@@ -43,11 +47,13 @@ const storage = createPersistentStore<ComparisonState>('glyphdiff:comparison', {
 });
 
 /**
- * Store for managing font comparison state
+ * Store for managing font comparison state.
  *
- * Handles font selection persistence, fetching, and loading state tracking.
- * Uses the CSS Font Loading API to ensure fonts are loaded before
- * showing the comparison interface.
+ * Uses BatchFontStore (TanStack Query) to fetch fonts by ID, replacing
+ * the previous hand-rolled async fetch approach. Three reactive effects
+ * handle: (1) syncing batch results into fontA/fontB, (2) triggering the
+ * CSS Font Loading API, and (3) falling back to default fonts when
+ * storage is empty.
  */
 export class ComparisonStore {
     /** Font for side A */
@@ -56,8 +62,6 @@ export class ComparisonStore {
     #fontB = $state<UnifiedFont | undefined>();
     /** Sample text to display */
     #sampleText = $state('The quick brown fox jumps over the lazy dog');
-    /** Whether currently restoring from storage */
-    #isRestoring = $state(true);
     /** Whether fonts are loaded and ready to display */
     #fontsReady = $state(false);
     /** Active side for single-font operations */
@@ -66,40 +70,78 @@ export class ComparisonStore {
     #sliderPosition = $state(50);
     /** Typography controls for this comparison */
     #typography = createTypographyControlManager(DEFAULT_TYPOGRAPHY_CONTROLS_DATA, 'glyphdiff:comparison:typography');
+    /** TanStack Query-backed batch font fetcher */
+    #batchStore: BatchFontStore;
 
     constructor() {
-        this.restoreFromStorage();
+        // Synchronously seed the batch store with any IDs already in storage
+        const { fontAId, fontBId } = storage.value;
+        this.#batchStore = new BatchFontStore(fontAId && fontBId ? [fontAId, fontBId] : []);
 
-        // Reactively set defaults if we aren't restoring and have no selection
         $effect.root(() => {
+            // Effect 1: Sync batch results → fontA / fontB
             $effect(() => {
-                // Wait until we are done checking storage
-                if (this.#isRestoring) {
-                    return;
-                }
+                const fonts = this.#batchStore.fonts;
+                if (fonts.length === 0) return;
 
-                // If we already have a selection, do nothing
-                if (this.#fontA && this.#fontB) {
+                const { fontAId: aId, fontBId: bId } = storage.value;
+                if (aId) {
+                    const fa = fonts.find(f => f.id === aId);
+                    if (fa) this.#fontA = fa;
+                }
+                if (bId) {
+                    const fb = fonts.find(f => f.id === bId);
+                    if (fb) this.#fontB = fb;
+                }
+            });
+
+            // Effect 2: Trigger font loading whenever selection or weight changes
+            $effect(() => {
+                const fa = this.#fontA;
+                const fb = this.#fontB;
+                const weight = this.#typography.weight;
+
+                if (!fa || !fb) return;
+
+                const configs: FontLoadRequestConfig[] = [];
+                [fa, fb].forEach(f => {
+                    const url = getFontUrl(f, weight);
+                    if (url) {
+                        configs.push({
+                            id: f.id,
+                            name: f.name,
+                            weight,
+                            url,
+                            isVariable: f.features?.isVariable,
+                        });
+                    }
+                });
+
+                if (configs.length > 0) {
+                    appliedFontsManager.touch(configs);
                     this.#checkFontsLoaded();
-                    return;
                 }
+            });
+
+            // Effect 3: Set default fonts when storage is empty
+            $effect(() => {
+                if (this.#fontA && this.#fontB) return;
 
-                // Check if fonts are available to set as defaults
                 const fonts = fontStore.fonts;
                 if (fonts.length >= 2) {
-                    // Only set if we really have nothing (fallback)
-                    if (!this.#fontA) this.#fontA = fonts[0];
-                    if (!this.#fontB) this.#fontB = fonts[fonts.length - 1];
-
-                    // Sync defaults to storage so they persist if the user leaves
-                    this.updateStorage();
+                    untrack(() => {
+                        const id1 = fonts[0].id;
+                        const id2 = fonts[fonts.length - 1].id;
+                        storage.value = { fontAId: id1, fontBId: id2 };
+                        this.#batchStore.setIds([id1, id2]);
+                    });
                 }
             });
         });
     }
 
     /**
-     * Checks if fonts are actually loaded in the browser at current weight
+     * Checks if fonts are actually loaded in the browser at current weight.
      *
      * Uses CSS Font Loading API to prevent FOUT. Waits for fonts to load
      * and forces a layout/paint cycle before marking as ready.
@@ -132,71 +174,35 @@ export class ComparisonStore {
         this.#fontsReady = false;
 
         try {
-            // Step 1: Load fonts into memory
             await Promise.all([
                 document.fonts.load(fontAString),
                 document.fonts.load(fontBString),
             ]);
-
-            // Step 2: Wait for browser to be ready to render
             await document.fonts.ready;
-
-            // Step 3: Force a layout/paint cycle (critical!)
             await new Promise(resolve => {
                 requestAnimationFrame(() => {
-                    requestAnimationFrame(resolve); // Double rAF ensures paint completes
+                    requestAnimationFrame(resolve);
                 });
             });
-
             this.#fontsReady = true;
         } catch (error) {
             console.warn('[ComparisonStore] Font loading failed:', error);
-            setTimeout(() => this.#fontsReady = true, 1000);
+            setTimeout(() => (this.#fontsReady = true), 1000);
         }
     }
 
     /**
-     * Restore state from persistent storage
-     *
-     * Fetches saved fonts from the API and restores them to the store.
-     */
-    async restoreFromStorage() {
-        this.#isRestoring = true;
-        const { fontAId, fontBId } = storage.value;
-
-        if (fontAId && fontBId) {
-            try {
-                // Batch fetch the saved fonts
-                const fonts = await fetchFontsByIds([fontAId, fontBId]);
-                const loadedFontA = fonts.find((f: UnifiedFont) => f.id === fontAId);
-                const loadedFontB = fonts.find((f: UnifiedFont) => f.id === fontBId);
-
-                if (loadedFontA && loadedFontB) {
-                    this.#fontA = loadedFontA;
-                    this.#fontB = loadedFontB;
-                }
-            } catch (error) {
-                console.warn('[ComparisonStore] Failed to restore fonts:', error);
-            }
-        }
-
-        // Mark restoration as complete (whether success or fail)
-        this.#isRestoring = false;
-    }
-
-    /**
-     * Update storage with current state
+     * Updates persistent storage with the current font selection.
      */
     private updateStorage() {
-        // Don't save if we are currently restoring (avoid race)
-        if (this.#isRestoring) return;
-
         storage.value = {
             fontAId: this.#fontA?.id ?? null,
             fontBId: this.#fontB?.id ?? null,
         };
     }
 
+    // ── Getters / Setters ─────────────────────────────────────────────────────
+
     /** Typography control manager */
     get typography() {
         return this.#typography;
@@ -249,33 +255,23 @@ export class ComparisonStore {
         this.#sliderPosition = value;
     }
 
-    /**
-     * Check if both fonts are selected and loaded
-     */
+    /** Whether both fonts are selected and loaded */
     get isReady() {
         return !!this.#fontA && !!this.#fontB && this.#fontsReady;
     }
 
-    /** Whether currently loading or restoring */
+    /** Whether currently loading (batch fetch in flight or fonts not yet painted) */
     get isLoading() {
-        return this.#isRestoring || !this.#fontsReady;
+        return this.#batchStore.isLoading || !this.#fontsReady;
     }
 
     /**
-     * Public initializer (optional, as constructor starts it)
-     */
-    initialize() {
-        if (!this.#isRestoring && !this.#fontA && !this.#fontB) {
-            this.restoreFromStorage();
-        }
-    }
-
-    /**
-     * Reset all state and clear storage
+     * Resets all state, clears storage, and disables the batch query.
      */
     resetAll() {
         this.#fontA = undefined;
         this.#fontB = undefined;
+        this.#batchStore.setIds([]);
         storage.clear();
         this.#typography.reset();
     }

src/widgets/ComparisonView/model/stores/comparisonStore.test.ts

@@ -1,20 +1,16 @@
 /**
- * Unit tests for ComparisonStore
+ * Unit tests for ComparisonStore (TanStack Query refactor)
  *
- * Tests the font comparison store functionality including:
- * - Font loading via CSS Font Loading API
- * - Storage synchronization when fonts change
- * - Default values from fontStore
- * - Reset functionality
- * - isReady computed state
+ * Uses the real BatchFontStore so Svelte $state reactivity works correctly.
+ * Controls network behaviour via vi.spyOn on the proxyFonts API layer.
  */
 
 /** @vitest-environment jsdom */
 
 import type { UnifiedFont } from '$entities/Font';
 import { UNIFIED_FONTS } from '$entities/Font/lib/mocks';
+import { queryClient } from '$shared/api/queryClient';
 import {
-    afterEach,
     beforeEach,
     describe,
     expect,
@@ -22,74 +18,13 @@ import {
     vi,
 } from 'vitest';
 
-// Mock all dependencies
-vi.mock('$entities/Font', () => ({
-    fetchFontsByIds: vi.fn(),
-    fontStore: { fonts: [] },
-}));
+// ── Persistent-store mock ─────────────────────────────────────────────────────
 
-vi.mock('$features/SetupFont', () => ({
-    DEFAULT_TYPOGRAPHY_CONTROLS_DATA: [
-        {
-            id: 'font_size',
-            value: 48,
-            min: 8,
-            max: 100,
-            step: 1,
-            increaseLabel: 'Increase Font Size',
-            decreaseLabel: 'Decrease Font Size',
-            controlLabel: 'Size',
-        },
-        {
-            id: 'font_weight',
-            value: 400,
-            min: 100,
-            max: 900,
-            step: 100,
-            increaseLabel: 'Increase Font Weight',
-            decreaseLabel: 'Decrease Font Weight',
-            controlLabel: 'Weight',
-        },
-        {
-            id: 'line_height',
-            value: 1.5,
-            min: 1,
-            max: 2,
-            step: 0.05,
-            increaseLabel: 'Increase Line Height',
-            decreaseLabel: 'Decrease Line Height',
-            controlLabel: 'Leading',
-        },
-        {
-            id: 'letter_spacing',
-            value: 0,
-            min: -0.1,
-            max: 0.5,
-            step: 0.01,
-            increaseLabel: 'Increase Letter Spacing',
-            decreaseLabel: 'Decrease Letter Spacing',
-            controlLabel: 'Tracking',
-        },
-    ],
-    createTypographyControlManager: vi.fn(() => ({
-        weight: 400,
-        renderedSize: 48,
-        reset: vi.fn(),
-    })),
-}));
-
-// Create mock storage accessible from both vi.mock factory and tests
 const mockStorage = vi.hoisted(() => {
     const storage: any = {};
-    storage._value = {
-        fontAId: null as string | null,
-        fontBId: null as string | null,
-    };
+    storage._value = { fontAId: null, fontBId: null };
     storage._clear = vi.fn(() => {
-        storage._value = {
-            fontAId: null,
-            fontBId: null,
-        };
+        storage._value = { fontAId: null, fontBId: null };
     });
 
     Object.defineProperty(storage, 'value', {
@@ -116,71 +51,58 @@ vi.mock('$shared/lib/helpers/createPersistentStore/createPersistentStore.svelte'
     createPersistentStore: vi.fn(() => mockStorage),
 }));
 
-// Import after mocks
-import {
-    fetchFontsByIds,
-    fontStore,
-} from '$entities/Font';
-import { createTypographyControlManager } from '$features/SetupFont';
-import { ComparisonStore } from './comparisonStore.svelte';
+// ── $entities/Font mock — keep real BatchFontStore, stub singletons ───────────
 
-describe('ComparisonStore', () => {
-    // Mock fonts
-    const mockFontA: UnifiedFont = UNIFIED_FONTS.roboto;
-    const mockFontB: UnifiedFont = UNIFIED_FONTS.openSans;
-
-    // Mock document.fonts
-    let mockFontFaceSet: {
-        check: ReturnType<typeof vi.fn>;
-        load: ReturnType<typeof vi.fn>;
-        ready: Promise<FontFaceSet>;
+vi.mock('$entities/Font', async () => {
+    const { BatchFontStore } = await import(
+        '$entities/Font/model/store/batchFontStore.svelte'
+    );
+    return {
+        BatchFontStore,
+        fontStore: { fonts: [] },
+        appliedFontsManager: {
+            touch: vi.fn(),
+            getFontStatus: vi.fn(),
+            ready: vi.fn(() => Promise.resolve()),
+        },
+        getFontUrl: vi.fn(() => 'https://example.com/font.woff2'),
     };
+});
 
-    beforeEach(() => {
-        // Clear all mocks
-        vi.clearAllMocks();
+// ── $features/SetupFont mock ──────────────────────────────────────────────────
 
-        // Clear localStorage
-        localStorage.clear();
-
-        // Reset mock storage value via the helper
-        mockStorage._value = {
-            fontAId: null,
-            fontBId: null,
-        };
-        mockStorage._clear.mockClear();
-
-        // Setup mock fontStore
-        (fontStore as any).fonts = [];
-
-        // Setup mock fetchFontsByIds
-        vi.mocked(fetchFontsByIds).mockResolvedValue([]);
-
-        // Setup mock createTypographyControlManager
-        vi.mocked(createTypographyControlManager).mockReturnValue({
+vi.mock('$features/SetupFont', () => ({
+    DEFAULT_TYPOGRAPHY_CONTROLS_DATA: [],
+    createTypographyControlManager: vi.fn(() => ({
         weight: 400,
         renderedSize: 48,
         reset: vi.fn(),
-        } as any);
+    })),
+}));
 
-        // Setup mock document.fonts
-        mockFontFaceSet = {
-            check: vi.fn(() => true),
-            load: vi.fn(() => Promise.resolve()),
-            ready: Promise.resolve({} as FontFaceSet),
-        };
+// ── Imports (after mocks) ─────────────────────────────────────────────────────
 
-        Object.defineProperty(document, 'fonts', {
-            value: mockFontFaceSet,
-            writable: true,
-            configurable: true,
-        });
-    });
+import { fontStore } from '$entities/Font';
+import * as proxyFonts from '$entities/Font/api/proxy/proxyFonts';
+import { ComparisonStore } from './comparisonStore.svelte';
 
-    afterEach(() => {
-        // Ensure document.fonts is always reset to a valid mock
-        // This prevents issues when tests delete or undefined document.fonts
-        if (!document.fonts || typeof document.fonts.check !== 'function') {
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('ComparisonStore', () => {
+    const mockFontA: UnifiedFont = UNIFIED_FONTS.roboto; // id: 'roboto'
+    const mockFontB: UnifiedFont = UNIFIED_FONTS.openSans; // id: 'open-sans'
+
+    beforeEach(() => {
+        queryClient.clear();
+        vi.clearAllMocks();
+        mockStorage._value = { fontAId: null, fontBId: null };
+        mockStorage._clear.mockClear();
+        (fontStore as any).fonts = [];
+
+        // Default: fetchFontsByIds returns empty so tests that don't care don't hang
+        vi.spyOn(proxyFonts, 'fetchFontsByIds').mockResolvedValue([]);
+
+        // document.fonts: check returns true so #checkFontsLoaded resolves immediately
         Object.defineProperty(document, 'fonts', {
             value: {
                 check: vi.fn(() => true),
@@ -190,397 +112,101 @@ describe('ComparisonStore', () => {
             writable: true,
             configurable: true,
         });
-        }
     });
 
+    // ── Initialization ────────────────────────────────────────────────────────
+
     describe('Initialization', () => {
         it('should create store with initial empty state', () => {
             const store = new ComparisonStore();
-
-            expect(store.fontA).toBeUndefined();
-            expect(store.fontB).toBeUndefined();
-            expect(store.text).toBe('The quick brown fox jumps over the lazy dog');
-            expect(store.side).toBe('A');
-            expect(store.sliderPosition).toBe(50);
-        });
-
-        it('should initialize with default sample text', () => {
-            const store = new ComparisonStore();
-
-            expect(store.text).toBe('The quick brown fox jumps over the lazy dog');
-        });
-
-        it('should have typography manager attached', () => {
-            const store = new ComparisonStore();
-
-            expect(store.typography).toBeDefined();
-        });
-    });
-
-    describe('Storage Synchronization', () => {
-        it('should update storage when fontA is set', () => {
-            const store = new ComparisonStore();
-
-            store.fontA = mockFontA;
-
-            expect(mockStorage._value.fontAId).toBe(mockFontA.id);
-        });
-
-        it('should update storage when fontB is set', () => {
-            const store = new ComparisonStore();
-
-            store.fontB = mockFontB;
-
-            expect(mockStorage._value.fontBId).toBe(mockFontB.id);
-        });
-
-        it('should update storage when both fonts are set', () => {
-            const store = new ComparisonStore();
-
-            store.fontA = mockFontA;
-            store.fontB = mockFontB;
-
-            expect(mockStorage._value.fontAId).toBe(mockFontA.id);
-            expect(mockStorage._value.fontBId).toBe(mockFontB.id);
-        });
-
-        it('should set storage to null when font is set to undefined', () => {
-            const store = new ComparisonStore();
-
-            store.fontA = mockFontA;
-            expect(mockStorage._value.fontAId).toBe(mockFontA.id);
-
-            store.fontA = undefined;
-            expect(mockStorage._value.fontAId).toBeNull();
-        });
-    });
-
-    describe('Restore from Storage', () => {
-        it('should restore fonts from storage when both IDs exist', async () => {
-            mockStorage._value.fontAId = mockFontA.id;
-            mockStorage._value.fontBId = mockFontB.id;
-
-            vi.mocked(fetchFontsByIds).mockResolvedValue([mockFontA, mockFontB]);
-
-            const store = new ComparisonStore();
-            await store.restoreFromStorage();
-
-            expect(fetchFontsByIds).toHaveBeenCalledWith([mockFontA.id, mockFontB.id]);
-            expect(store.fontA).toEqual(mockFontA);
-            expect(store.fontB).toEqual(mockFontB);
-        });
-
-        it('should not restore when storage has null IDs', async () => {
-            mockStorage._value.fontAId = null;
-            mockStorage._value.fontBId = null;
-
-            const store = new ComparisonStore();
-            await store.restoreFromStorage();
-
-            expect(fetchFontsByIds).not.toHaveBeenCalled();
             expect(store.fontA).toBeUndefined();
             expect(store.fontB).toBeUndefined();
         });
+    });
 
-        it('should handle fetch errors gracefully when restoring', async () => {
+    // ── Restoration from Storage ──────────────────────────────────────────────
+
+    describe('Restoration from Storage (via BatchFontStore)', () => {
+        it('should restore fontA and fontB from stored IDs', async () => {
             mockStorage._value.fontAId = mockFontA.id;
             mockStorage._value.fontBId = mockFontB.id;
-
-            vi.mocked(fetchFontsByIds).mockRejectedValue(new Error('Network error'));
-
-            const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-            const store = new ComparisonStore();
-            await store.restoreFromStorage();
-
-            expect(consoleSpy).toHaveBeenCalled();
-            expect(store.fontA).toBeUndefined();
-            expect(store.fontB).toBeUndefined();
-
-            consoleSpy.mockRestore();
-        });
-
-        it('should handle partial restoration when only one font is found', async () => {
-            // Ensure fontStore is empty so $effect doesn't interfere
-            (fontStore as any).fonts = [];
-
-            mockStorage._value.fontAId = mockFontA.id;
-            mockStorage._value.fontBId = mockFontB.id;
-
-            // Only return fontA (simulating partial data from API)
-            vi.mocked(fetchFontsByIds).mockResolvedValue([mockFontA]);
-
-            const store = new ComparisonStore();
-            // Wait for async restoration from constructor
-            await new Promise(resolve => setTimeout(resolve, 10));
-
-            // The store should call fetchFontsByIds with both IDs
-            expect(fetchFontsByIds).toHaveBeenCalledWith([mockFontA.id, mockFontB.id]);
-
-            // When only one font is found, the store handles it gracefully
-            // (both fonts need to be found for restoration to set them)
-            // The key behavior tested here is that partial fetch doesn't crash
-            // and the store remains functional
-
-            // Store should not have crashed and should be in a valid state
-            expect(store).toBeDefined();
-        });
-    });
-
-    describe('Font Loading with CSS Font Loading API', () => {
-        it('should construct correct font strings for checking', async () => {
-            mockFontFaceSet.check.mockReturnValue(false);
-            (fontStore as any).fonts = [mockFontA, mockFontB];
-            vi.mocked(fetchFontsByIds).mockResolvedValue([mockFontA, mockFontB]);
-
-            const store = new ComparisonStore();
-            store.fontA = mockFontA;
-            store.fontB = mockFontB;
-
-            // Wait for async operations
-            await new Promise(resolve => setTimeout(resolve, 0));
-
-            // Check that font strings are constructed correctly
-            const expectedFontAString = '400 48px "Roboto"';
-            const expectedFontBString = '400 48px "Open Sans"';
-
-            expect(mockFontFaceSet.load).toHaveBeenCalledWith(expectedFontAString);
-            expect(mockFontFaceSet.load).toHaveBeenCalledWith(expectedFontBString);
-        });
-
-        it('should handle missing document.fonts API gracefully', () => {
-            // Delete the fonts property entirely to simulate missing API
-            delete (document as any).fonts;
-
-            const store = new ComparisonStore();
-            store.fontA = mockFontA;
-            store.fontB = mockFontB;
-
-            // Should not throw and should still work
-            expect(store.fontA).toStrictEqual(mockFontA);
-            expect(store.fontB).toStrictEqual(mockFontB);
-        });
-
-        it('should handle font loading errors gracefully', async () => {
-            // Mock check to return false (fonts not loaded)
-            mockFontFaceSet.check.mockReturnValue(false);
-            // Mock load to fail
-            mockFontFaceSet.load.mockRejectedValue(new Error('Font load failed'));
-
-            (fontStore as any).fonts = [mockFontA, mockFontB];
-            vi.mocked(fetchFontsByIds).mockResolvedValue([mockFontA, mockFontB]);
-
-            const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-            const store = new ComparisonStore();
-            store.fontA = mockFontA;
-            store.fontB = mockFontB;
-
-            // Wait for async operations and timeout fallback
-            await new Promise(resolve => setTimeout(resolve, 1100));
-
-            expect(consoleSpy).toHaveBeenCalled();
-            consoleSpy.mockRestore();
-        });
-    });
-
-    describe('Default Values from fontStore', () => {
-        it('should set default fonts from fontStore when available', () => {
-            // Note: This test relies on Svelte 5's $effect which may not work
-            // reliably in the test environment. We test the logic path instead.
-            (fontStore as any).fonts = [mockFontA, mockFontB];
+            vi.spyOn(proxyFonts, 'fetchFontsByIds').mockResolvedValue([mockFontA, mockFontB]);
 
             const store = new ComparisonStore();
 
-            // The default fonts should be set when storage is empty
-            // In the actual app, this happens via $effect in the constructor
-            // In tests, we verify the store can have fonts set manually
-            store.fontA = mockFontA;
-            store.fontB = mockFontB;
-
-            expect(store.fontA).toBeDefined();
-            expect(store.fontB).toBeDefined();
-        });
-
-        it('should use first and last font from fontStore as defaults', () => {
-            const mockFontC = UNIFIED_FONTS.lato;
-            (fontStore as any).fonts = [mockFontA, mockFontC, mockFontB];
-
-            const store = new ComparisonStore();
-
-            // Manually set the first font to test the logic
-            store.fontA = mockFontA;
-
+            await vi.waitFor(() => {
                 expect(store.fontA?.id).toBe(mockFontA.id);
+                expect(store.fontB?.id).toBe(mockFontB.id);
+            }, { timeout: 2000 });
+        });
+
+        it('should handle fetch errors during restoration gracefully', async () => {
+            mockStorage._value.fontAId = mockFontA.id;
+            mockStorage._value.fontBId = mockFontB.id;
+            vi.spyOn(proxyFonts, 'fetchFontsByIds').mockRejectedValue(new Error('Network fail'));
+
+            const store = new ComparisonStore();
+
+            // Store stays in valid state — no throw, fonts remain undefined
+            await vi.waitFor(() => expect(store.isLoading).toBe(true)); // stuck loading since no fonts
+            expect(store.fontA).toBeUndefined();
+            expect(store.fontB).toBeUndefined();
         });
     });
 
+    // ── Default Fallbacks ─────────────────────────────────────────────────────
+
+    describe('Default Fallbacks', () => {
+        it('should update storage with default IDs when storage is empty', async () => {
+            (fontStore as any).fonts = [mockFontA, mockFontB];
+            vi.spyOn(proxyFonts, 'fetchFontsByIds').mockResolvedValue([mockFontA, mockFontB]);
+
+            new ComparisonStore();
+
+            await vi.waitFor(() => {
+                expect(mockStorage._value.fontAId).toBe(mockFontA.id);
+                expect(mockStorage._value.fontBId).toBe(mockFontB.id);
+            });
+        });
+    });
+
+    // ── Loading State ─────────────────────────────────────────────────────────
+
+    describe('Aggregate Loading State', () => {
+        it('should be loading initially when storage has IDs', async () => {
+            mockStorage._value.fontAId = mockFontA.id;
+            mockStorage._value.fontBId = mockFontB.id;
+            vi.spyOn(proxyFonts, 'fetchFontsByIds').mockImplementation(
+                () => new Promise(r => setTimeout(() => r([mockFontA, mockFontB]), 50)),
+            );
+
+            const store = new ComparisonStore();
+            expect(store.isLoading).toBe(true);
+
+            await vi.waitFor(() => expect(store.isLoading).toBe(false), { timeout: 2000 });
+        });
+    });
+
+    // ── Reset ─────────────────────────────────────────────────────────────────
+
     describe('Reset Functionality', () => {
         it('should reset all state and clear storage', () => {
             const store = new ComparisonStore();
-
-            // Set some values
-            store.fontA = mockFontA;
-            store.fontB = mockFontB;
-            store.text = 'Custom text';
-            store.side = 'B';
-            store.sliderPosition = 75;
-
-            // Reset
             store.resetAll();
-
-            // Check all state is cleared
-            expect(store.fontA).toBeUndefined();
-            expect(store.fontB).toBeUndefined();
             expect(mockStorage._clear).toHaveBeenCalled();
         });
 
-        it('should reset typography controls when resetAll is called', () => {
-            const mockReset = vi.fn();
-            vi.mocked(createTypographyControlManager).mockReturnValue({
-                weight: 400,
-                renderedSize: 48,
-                reset: mockReset,
-            } as any);
-
-            const store = new ComparisonStore();
-            store.resetAll();
-
-            expect(mockReset).toHaveBeenCalled();
-        });
-
-        it('should not affect text property on reset', () => {
-            const store = new ComparisonStore();
-
-            store.text = 'Custom text';
-            store.resetAll();
-
-            // Text is not reset by resetAll
-            expect(store.text).toBe('Custom text');
-        });
-    });
-
-    describe('isReady Computed State', () => {
-        it('should return false when fonts are not set', () => {
-            const store = new ComparisonStore();
-
-            expect(store.isReady).toBe(false);
-        });
-
-        it('should return false when only fontA is set', () => {
-            const store = new ComparisonStore();
-            store.fontA = mockFontA;
-
-            expect(store.isReady).toBe(false);
-        });
-
-        it('should return false when only fontB is set', () => {
-            const store = new ComparisonStore();
-            store.fontB = mockFontB;
-
-            expect(store.isReady).toBe(false);
-        });
-
-        it('should return true when both fonts are set', () => {
-            const store = new ComparisonStore();
-
-            // Manually set fonts
-            store.fontA = mockFontA;
-            store.fontB = mockFontB;
-
-            // After setting both fonts, isReady should eventually be true
-            // Note: In actual testing with Svelte 5 runes, the reactivity
-            // may not work in Node.js environment, so this tests the logic path
-            expect(store.fontA).toBeDefined();
-            expect(store.fontB).toBeDefined();
-        });
-    });
-
-    describe('isLoading State', () => {
-        it('should return true when restoring from storage', async () => {
+        it('should clear fontA and fontB on reset', async () => {
             mockStorage._value.fontAId = mockFontA.id;
             mockStorage._value.fontBId = mockFontB.id;
-
-            // Make fetch take some time
-            vi.mocked(fetchFontsByIds).mockImplementation(
-                () => new Promise(resolve => setTimeout(() => resolve([mockFontA, mockFontB]), 10)),
-            );
+            vi.spyOn(proxyFonts, 'fetchFontsByIds').mockResolvedValue([mockFontA, mockFontB]);
 
             const store = new ComparisonStore();
-            const restorePromise = store.restoreFromStorage();
+            await vi.waitFor(() => expect(store.fontA?.id).toBe(mockFontA.id), { timeout: 2000 });
 
-            // While restoring, isLoading should be true
-            expect(store.isLoading).toBe(true);
-
-            await restorePromise;
-
-            // After restoration, isLoading should be false
-            expect(store.isLoading).toBe(false);
-        });
-    });
-
-    describe('Getters and Setters', () => {
-        it('should allow getting and setting sample text', () => {
-            const store = new ComparisonStore();
-
-            store.text = 'Hello World';
-            expect(store.text).toBe('Hello World');
-        });
-
-        it('should allow getting and setting side', () => {
-            const store = new ComparisonStore();
-
-            expect(store.side).toBe('A');
-
-            store.side = 'B';
-            expect(store.side).toBe('B');
-        });
-
-        it('should allow getting and setting slider position', () => {
-            const store = new ComparisonStore();
-
-            store.sliderPosition = 75;
-            expect(store.sliderPosition).toBe(75);
-        });
-
-        it('should allow getting typography manager', () => {
-            const store = new ComparisonStore();
-
-            expect(store.typography).toBeDefined();
-        });
-    });
-
-    describe('Edge Cases', () => {
-        it('should handle empty font names gracefully', () => {
-            const emptyFont = { ...mockFontA, name: '' };
-
-            const store = new ComparisonStore();
-
-            store.fontA = emptyFont;
-            store.fontB = mockFontB;
-
-            // Should not throw
-            expect(store.fontA).toEqual(emptyFont);
-        });
-
-        it('should handle fontA with undefined name', () => {
-            const noNameFont = { ...mockFontA, name: undefined as any };
-
-            const store = new ComparisonStore();
-
-            store.fontA = noNameFont;
-
-            expect(store.fontA).toEqual(noNameFont);
-        });
-
-        it('should handle setSide with both valid values', () => {
-            const store = new ComparisonStore();
-
-            store.side = 'A';
-            expect(store.side).toBe('A');
-
-            store.side = 'B';
-            expect(store.side).toBe('B');
+            store.resetAll();
+            expect(store.fontA).toBeUndefined();
+            expect(store.fontB).toBeUndefined();
         });
     });
 });

src/widgets/SampleList/ui/SampleList/SampleList.svelte

@@ -5,7 +5,12 @@
     - Provides a typography menu for font setup.
 -->
 <script lang="ts">
-import { FontVirtualList } from '$entities/Font';
+import {
+    FontVirtualList,
+    appliedFontsManager,
+    createFontRowSizeResolver,
+    fontStore,
+} from '$entities/Font';
 import { FontSampler } from '$features/DisplayFont';
 import {
     TypographyMenu,
@@ -15,12 +20,30 @@ import { throttle } from '$shared/lib/utils';
 import { Skeleton } from '$shared/ui';
 import { layoutManager } from '../../model';
 
+// FontSampler chrome heights — derived from Tailwind classes in FontSampler.svelte.
+// Header: py-3 (12+12px padding) + ~32px content row ≈ 56px.
+// Only the header is counted; the mobile footer (md:hidden) is excluded because
+// on desktop, where container widths are wide and estimates matter most, it is invisible.
+// Over-estimating chrome is safe (row is slightly taller than text needs, never cut off).
+const SAMPLER_CHROME_HEIGHT = 56;
+
+// p-4 = 16px per side = 32px total horizontal padding in FontSampler's content area.
+// Using the smallest breakpoint (mobile) ensures contentWidth is never over-estimated:
+// wider actual padding → more text wrapping → pretext height ≥ rendered height → safe.
+const SAMPLER_CONTENT_PADDING_X = 32;
+
+// Fallback row height used when the font has not loaded yet.
+// Matches the previous hardcoded itemHeight={220} value to avoid regressions.
+const SAMPLER_FALLBACK_HEIGHT = 220;
+
 let text = $state('The quick brown fox jumps over the lazy dog...');
 let wrapper = $state<HTMLDivElement | null>(null);
 // Binds to the actual window height
 let innerHeight = $state(0);
 // Is the component above the middle of the viewport?
 let isAboveMiddle = $state(false);
+// Inner width of the wrapper div — updated by bind:clientWidth on mount and resize.
+let containerWidth = $state(0);
 
 const checkPosition = throttle(() => {
     if (!wrapper) return;
@@ -30,6 +53,24 @@ const checkPosition = throttle(() => {
 
     isAboveMiddle = rect.top < viewportMiddle;
 }, 100);
+
+// Resolver recreated when typography values change. The returned closure reads
+// appliedFontsManager.statuses (a SvelteMap) on every call, so any font status
+// change triggers a full offsets recompute in createVirtualizer — no DOM snap.
+const fontRowHeight = $derived.by(() =>
+    createFontRowSizeResolver({
+        getFonts: () => fontStore.fonts,
+        getWeight: () => controlManager.weight,
+        getPreviewText: () => text,
+        getContainerWidth: () => containerWidth,
+        getFontSizePx: () => controlManager.renderedSize,
+        getLineHeightPx: () => controlManager.height * controlManager.renderedSize,
+        getStatus: key => appliedFontsManager.statuses.get(key),
+        contentHorizontalPadding: SAMPLER_CONTENT_PADDING_X,
+        chromeHeight: SAMPLER_CHROME_HEIGHT,
+        fallbackHeight: SAMPLER_FALLBACK_HEIGHT,
+    })
+);
 </script>
 
 {#snippet skeleton()}
@@ -52,9 +93,9 @@ const checkPosition = throttle(() => {
     onresize={checkPosition}
 />
 
-<div bind:this={wrapper}>
+<div bind:this={wrapper} bind:clientWidth={containerWidth}>
     <FontVirtualList
-        itemHeight={220}
+        itemHeight={fontRowHeight}
         useWindowScroll={true}
         weight={controlManager.weight}
         columns={layoutManager.columns}