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

Reviewed-on: #36
fix(BaseQueryStore): use QueryObserverOptions instead of QueryOptions
2026-04-16 04:53:28 +00:00 · 2026-04-15 22:37:30 +03:00 · 2026-04-15 22:32:45 +03:00 · 2026-04-15 22:25:34 +03:00 · 2026-04-15 15:59:01 +03:00 · 2026-04-15 12:29:16 +03:00
71 changed files with 4121 additions and 4343 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,9 @@ node_modules
 /build
 /dist
 # Git worktrees (isolated development branches)
 .worktrees
 # OS
 .DS_Store
 Thumbs.db
--- a/index.html
+++ b/index.html
@@ -4,6 +4,7 @@
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>glyphdiff</title>
        <script src="https://mcp.figma.com/mcp/html-to-design/capture.js" async></script>
    </head>
    <body>
        <div id="app"></div>
--- a/package.json
+++ b/package.json
@@ -66,6 +66,7 @@
    "vitest-browser-svelte": "^2.0.1"
  },
  "dependencies": {
    "@chenglou/pretext": "^0.0.5",
    "@tanstack/svelte-query": "^6.0.14"
  }
 }
--- a/src/entities/Font/api/proxy/proxyFonts.test.ts
+++ b/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();
        });
    });
 });
--- a/src/entities/Font/api/proxy/proxyFonts.ts
+++ b/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,
+ * Normalizes cache by seeding individual font entries from collection responses.
-} from '../../model/types';
+ * 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
--- a/src/entities/Font/index.ts
+++ b/src/entities/Font/index.ts
@@ -1,110 +1,4 @@
-// Proxy API (primary)
+export * from './api';
-export {
+export * from './lib';
-    fetchFontsByIds,
+export * from './model';
-    fetchProxyFontById,
+export * from './ui';
    fetchProxyFonts,
 } from './api/proxy/proxyFonts';
 export type {
    ProxyFontsParams,
    ProxyFontsResponse,
 } from './api/proxy/proxyFonts';
 export {
    normalizeFontshareFont,
    normalizeFontshareFonts,
 } from './lib/normalize/normalize';
 export type {
    // Domain types
    FontCategory,
    FontCollectionFilters,
    FontCollectionSort,
    // Store types
    FontCollectionState,
    FontFeatures,
    FontFiles,
    FontItem,
    FontMetadata,
    FontProvider,
    // Fontshare API types
    FontshareApiModel,
    FontshareAxis,
    FontshareDesigner,
    FontshareFeature,
    FontshareFont,
    FontshareLink,
    FontsharePublisher,
    FontshareStyle,
    FontshareStyleProperties,
    FontshareTag,
    FontshareWeight,
    FontStyleUrls,
    FontSubset,
    FontVariant,
    FontWeight,
    FontWeightItalic,
    // Normalization types
    UnifiedFont,
    UnifiedFontVariant,
 } from './model';
 export {
    appliedFontsManager,
    createUnifiedFontStore,
    unifiedFontStore,
 } from './model';
 // Mock data helpers for Storybook and testing
 export {
    createCategoriesFilter,
    createErrorState,
    createGenericFilter,
    createLoadingState,
    createMockComparisonStore,
    // Filter mocks
    createMockFilter,
    createMockFontApiResponse,
    createMockFontStoreState,
    // Store mocks
    createMockQueryState,
    createMockReactiveState,
    createMockStore,
    createProvidersFilter,
    createSubsetsFilter,
    createSuccessState,
    FONTHARE_FONTS,
    generateMixedCategoryFonts,
    generateMockFonts,
    generatePaginatedFonts,
    generateSequentialFilter,
    GENERIC_FILTERS,
    getAllMockFonts,
    getFontsByCategory,
    getFontsByProvider,
    GOOGLE_FONTS,
    MOCK_FILTERS,
    MOCK_FILTERS_ALL_SELECTED,
    MOCK_FILTERS_EMPTY,
    MOCK_FILTERS_SELECTED,
    MOCK_FONT_STORE_STATES,
    MOCK_STORES,
    type MockFilterOptions,
    type MockFilters,
    mockFontshareFont,
    type MockFontshareFontOptions,
    type MockFontStoreState,
    // Font mocks
    mockGoogleFont,
    // Types
    type MockGoogleFontOptions,
    type MockQueryObserverResult,
    type MockQueryState,
    mockUnifiedFont,
    type MockUnifiedFontOptions,
    UNIFIED_FONTS,
 } from './lib/mocks';
 // UI elements
 export {
    FontApplicator,
    FontVirtualList,
 } from './ui';
--- a/src/entities/Font/lib/errors/errors.test.ts
+++ b/src/entities/Font/lib/errors/errors.test.ts
@@ -0,0 +1,51 @@
 import {
    FontNetworkError,
    FontResponseError,
 } from './errors';
 describe('FontNetworkError', () => {
    it('has correct name', () => {
        const err = new FontNetworkError();
        expect(err.name).toBe('FontNetworkError');
    });
    it('is instance of Error', () => {
        expect(new FontNetworkError()).toBeInstanceOf(Error);
    });
    it('stores cause', () => {
        const cause = new Error('network down');
        const err = new FontNetworkError(cause);
        expect(err.cause).toBe(cause);
    });
    it('has default message', () => {
        expect(new FontNetworkError().message).toBe('Failed to fetch fonts from proxy API');
    });
 });
 describe('FontResponseError', () => {
    it('has correct name', () => {
        const err = new FontResponseError('response', undefined);
        expect(err.name).toBe('FontResponseError');
    });
    it('is instance of Error', () => {
        expect(new FontResponseError('response.fonts', null)).toBeInstanceOf(Error);
    });
    it('stores field', () => {
        const err = new FontResponseError('response.fonts', 42);
        expect(err.field).toBe('response.fonts');
    });
    it('stores received value', () => {
        const err = new FontResponseError('response.fonts', 42);
        expect(err.received).toBe(42);
    });
    it('message includes field name', () => {
        const err = new FontResponseError('response.fonts', null);
        expect(err.message).toContain('response.fonts');
    });
 });
--- a/src/entities/Font/lib/errors/errors.ts
+++ b/src/entities/Font/lib/errors/errors.ts
@@ -0,0 +1,28 @@
 /**
 * Thrown when the network request to the proxy API fails.
 * Wraps the underlying fetch error (timeout, DNS failure, connection refused, etc.).
 */
 export class FontNetworkError extends Error {
    readonly name = 'FontNetworkError';
    constructor(public readonly cause?: unknown) {
        super('Failed to fetch fonts from proxy API');
    }
 }
 /**
 * Thrown when the proxy API returns a response with an unexpected shape.
 *
 * @property field - The name of the field that failed validation (e.g. `'response'`, `'response.fonts'`).
 * @property received - The actual value received at that field, for debugging.
 */
 export class FontResponseError extends Error {
    readonly name = 'FontResponseError';
    constructor(
        public readonly field: string,
        public readonly received: unknown,
    ) {
        super(`Invalid proxy API response: ${field}`);
    }
 }
--- a/src/entities/Font/lib/index.ts
+++ b/src/entities/Font/lib/index.ts
@@ -1,10 +1,3 @@
 export {
    normalizeFontshareFont,
    normalizeFontshareFonts,
    normalizeGoogleFont,
    normalizeGoogleFonts,
 } from './normalize/normalize';
 export { getFontUrl } from './getFontUrl/getFontUrl';
 // Mock data helpers for Storybook and testing
@@ -25,7 +18,6 @@ export {
    createProvidersFilter,
    createSubsetsFilter,
    createSuccessState,
    FONTHARE_FONTS,
    generateMixedCategoryFonts,
    generateMockFonts,
    generatePaginatedFonts,
@@ -34,7 +26,6 @@ export {
    getAllMockFonts,
    getFontsByCategory,
    getFontsByProvider,
    GOOGLE_FONTS,
    MOCK_FILTERS,
    MOCK_FILTERS_ALL_SELECTED,
    MOCK_FILTERS_EMPTY,
@@ -43,16 +34,20 @@ export {
    MOCK_STORES,
    type MockFilterOptions,
    type MockFilters,
    mockFontshareFont,
    type MockFontshareFontOptions,
    type MockFontStoreState,
    // Font mocks
    mockGoogleFont,
    // Types
    type MockGoogleFontOptions,
    type MockQueryObserverResult,
    type MockQueryState,
    mockUnifiedFont,
    type MockUnifiedFontOptions,
    UNIFIED_FONTS,
 } from './mocks';
 export {
    FontNetworkError,
    FontResponseError,
 } from './errors/errors';
 export { createFontRowSizeResolver } from './sizeResolver/createFontRowSizeResolver';
 export type { FontRowSizeResolverOptions } from './sizeResolver/createFontRowSizeResolver';
--- a/src/entities/Font/lib/mocks/filters.mock.ts
+++ b/src/entities/Font/lib/mocks/filters.mock.ts
@@ -58,29 +58,6 @@ export interface MockFilters {
 // FONT CATEGORIES
 /**
 * Google Fonts categories
 */
 export const GOOGLE_CATEGORIES: Property<'sans-serif' | 'serif' | 'display' | 'handwriting' | 'monospace'>[] = [
    { id: 'sans-serif', name: 'Sans Serif', value: 'sans-serif' },
    { id: 'serif', name: 'Serif', value: 'serif' },
    { id: 'display', name: 'Display', value: 'display' },
    { id: 'handwriting', name: 'Handwriting', value: 'handwriting' },
    { id: 'monospace', name: 'Monospace', value: 'monospace' },
 ];
 /**
 * Fontshare categories (mapped to common naming)
 */
 export const FONTHARE_CATEGORIES: Property<'sans' | 'serif' | 'slab' | 'display' | 'handwritten' | 'script'>[] = [
    { id: 'sans', name: 'Sans', value: 'sans' },
    { id: 'serif', name: 'Serif', value: 'serif' },
    { id: 'slab', name: 'Slab', value: 'slab' },
    { id: 'display', name: 'Display', value: 'display' },
    { id: 'handwritten', name: 'Handwritten', value: 'handwritten' },
    { id: 'script', name: 'Script', value: 'script' },
 ];
 /**
 * Unified categories (combines both providers)
 */
@@ -90,6 +67,8 @@ export const UNIFIED_CATEGORIES: Property<FontCategory>[] = [
    { id: 'display', name: 'Display', value: 'display' },
    { id: 'handwriting', name: 'Handwriting', value: 'handwriting' },
    { id: 'monospace', name: 'Monospace', value: 'monospace' },
    { id: 'slab', name: 'Slab', value: 'slab' },
    { id: 'script', name: 'Script', value: 'script' },
 ];
 // FONT SUBSETS
--- a/src/entities/Font/lib/mocks/fonts.mock.ts
+++ b/src/entities/Font/lib/mocks/fonts.mock.ts
@@ -38,11 +38,6 @@ import type {
    FontSubset,
    FontVariant,
 } from '$entities/Font/model/types';
 import type {
    FontItem,
    FontshareFont,
    GoogleFontItem,
 } from '$entities/Font/model/types';
 import type {
    FontFeatures,
    FontMetadata,
@@ -50,351 +45,6 @@ import type {
    UnifiedFont,
 } from '$entities/Font/model/types';
 // GOOGLE FONTS MOCKS
 /**
 * Options for creating a mock Google Font
 */
 export interface MockGoogleFontOptions {
    /** Font family name (default: 'Mock Font') */
    family?: string;
    /** Font category (default: 'sans-serif') */
    category?: 'sans-serif' | 'serif' | 'display' | 'handwriting' | 'monospace';
    /** Font variants (default: ['regular', '700', 'italic', '700italic']) */
    variants?: FontVariant[];
    /** Font subsets (default: ['latin']) */
    subsets?: string[];
    /** Font version (default: 'v30') */
    version?: string;
    /** Last modified date (default: current ISO date) */
    lastModified?: string;
    /** Custom file URLs (if not provided, mock URLs are generated) */
    files?: Partial<Record<FontVariant, string>>;
    /** Popularity rank (1 = most popular) */
    popularity?: number;
 }
 /**
 * Default mock Google Font
 */
 export function mockGoogleFont(options: MockGoogleFontOptions = {}): GoogleFontItem {
    const {
        family = 'Mock Font',
        category = 'sans-serif',
        variants = ['regular', '700', 'italic', '700italic'],
        subsets = ['latin'],
        version = 'v30',
        lastModified = new Date().toISOString().split('T')[0],
        files,
        popularity = 1,
    } = options;
    const baseUrl = `https://fonts.gstatic.com/s/${family.toLowerCase().replace(/\s+/g, '')}/${version}`;
    return {
        family,
        category,
        variants: variants as FontVariant[],
        subsets,
        version,
        lastModified,
        files: files ?? {
            regular: `${baseUrl}/KFOmCnqEu92Fr1Me4W.woff2`,
            '700': `${baseUrl}/KFOlCnqEu92Fr1MmWUlfBBc9.woff2`,
            italic: `${baseUrl}/KFOkCnqEu92Fr1Mu51xIIzI.woff2`,
            '700italic': `${baseUrl}/KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2`,
        },
        menu: `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family)}`,
    };
 }
 /**
 * Preset Google Font mocks
 */
 export const GOOGLE_FONTS: Record<string, GoogleFontItem> = {
    roboto: mockGoogleFont({
        family: 'Roboto',
        category: 'sans-serif',
        variants: ['100', '300', '400', '500', '700', '900', 'italic', '700italic'],
        subsets: ['latin', 'latin-ext', 'cyrillic', 'greek'],
        popularity: 1,
    }),
    openSans: mockGoogleFont({
        family: 'Open Sans',
        category: 'sans-serif',
        variants: ['300', '400', '500', '600', '700', '800', 'italic', '700italic'],
        subsets: ['latin', 'latin-ext', 'cyrillic', 'greek'],
        popularity: 2,
    }),
    lato: mockGoogleFont({
        family: 'Lato',
        category: 'sans-serif',
        variants: ['100', '300', '400', '700', '900', 'italic', '700italic'],
        subsets: ['latin', 'latin-ext'],
        popularity: 3,
    }),
    playfairDisplay: mockGoogleFont({
        family: 'Playfair Display',
        category: 'serif',
        variants: ['400', '500', '600', '700', '800', '900', 'italic', '700italic'],
        subsets: ['latin', 'latin-ext', 'cyrillic'],
        popularity: 10,
    }),
    montserrat: mockGoogleFont({
        family: 'Montserrat',
        category: 'sans-serif',
        variants: ['100', '200', '300', '400', '500', '600', '700', '800', '900', 'italic', '700italic'],
        subsets: ['latin', 'latin-ext', 'cyrillic', 'vietnamese'],
        popularity: 4,
    }),
    sourceSansPro: mockGoogleFont({
        family: 'Source Sans Pro',
        category: 'sans-serif',
        variants: ['200', '300', '400', '600', '700', '900', 'italic', '700italic'],
        subsets: ['latin', 'latin-ext', 'cyrillic', 'greek', 'vietnamese'],
        popularity: 5,
    }),
    merriweather: mockGoogleFont({
        family: 'Merriweather',
        category: 'serif',
        variants: ['300', '400', '700', '900', 'italic', '700italic'],
        subsets: ['latin', 'latin-ext', 'cyrillic', 'vietnamese'],
        popularity: 15,
    }),
    robotoSlab: mockGoogleFont({
        family: 'Roboto Slab',
        category: 'serif',
        variants: ['100', '300', '400', '500', '700', '900'],
        subsets: ['latin', 'latin-ext', 'cyrillic', 'greek', 'vietnamese'],
        popularity: 8,
    }),
    oswald: mockGoogleFont({
        family: 'Oswald',
        category: 'sans-serif',
        variants: ['200', '300', '400', '500', '600', '700'],
        subsets: ['latin', 'latin-ext', 'vietnamese'],
        popularity: 6,
    }),
    raleway: mockGoogleFont({
        family: 'Raleway',
        category: 'sans-serif',
        variants: ['100', '200', '300', '400', '500', '600', '700', '800', '900', 'italic'],
        subsets: ['latin', 'latin-ext', 'cyrillic', 'vietnamese'],
        popularity: 7,
    }),
 };
 // FONTHARE MOCKS
 /**
 * Options for creating a mock Fontshare font
 */
 export interface MockFontshareFontOptions {
    /** Font name (default: 'Mock Font') */
    name?: string;
    /** URL-friendly slug (default: derived from name) */
    slug?: string;
    /** Font category (default: 'sans') */
    category?: 'sans' | 'serif' | 'slab' | 'display' | 'handwritten' | 'script' | 'mono';
    /** Script (default: 'latin') */
    script?: string;
    /** Whether this is a variable font (default: false) */
    isVariable?: boolean;
    /** Font version (default: '1.0') */
    version?: string;
    /** Popularity/views count (default: 1000) */
    views?: number;
    /** Usage tags */
    tags?: string[];
    /** Font weights available */
    weights?: number[];
    /** Publisher name */
    publisher?: string;
    /** Designer name */
    designer?: string;
 }
 /**
 * Create a mock Fontshare style
 */
 function mockFontshareStyle(
    weight: number,
    isItalic: boolean,
    isVariable: boolean,
    slug: string,
 ): FontshareFont['styles'][number] {
    const weightLabel = weight === 400 ? 'Regular' : weight === 700 ? 'Bold' : weight.toString();
    const suffix = isItalic ? 'italic' : '';
    const variablePrefix = isVariable ? 'variable-' : '';
    return {
        id: `style-${weight}${isItalic ? '-italic' : ''}`,
        default: weight === 400 && !isItalic,
        file: `//cdn.fontshare.com/wf/${slug}-${variablePrefix}${weight}${suffix}.woff2`,
        is_italic: isItalic,
        is_variable: isVariable,
        properties: {},
        weight: {
            label: isVariable ? 'Variable' + (isItalic ? ' Italic' : '') : weightLabel,
            name: isVariable ? 'Variable' + (isItalic ? 'Italic' : '') : weightLabel,
            native_name: null,
            number: isVariable ? 0 : weight,
            weight: isVariable ? 0 : weight,
        },
    };
 }
 /**
 * Default mock Fontshare font
 */
 export function mockFontshareFont(options: MockFontshareFontOptions = {}): FontshareFont {
    const {
        name = 'Mock Font',
        slug = name.toLowerCase().replace(/\s+/g, '-'),
        category = 'sans',
        script = 'latin',
        isVariable = false,
        version = '1.0',
        views = 1000,
        tags = [],
        weights = [400, 700],
        publisher = 'Mock Foundry',
        designer = 'Mock Designer',
    } = options;
    // Generate styles based on weights and variable setting
    const styles: FontshareFont['styles'] = isVariable
        ? [
            mockFontshareStyle(0, false, true, slug),
            mockFontshareStyle(0, true, true, slug),
        ]
        : weights.flatMap(weight => [
            mockFontshareStyle(weight, false, false, slug),
            mockFontshareStyle(weight, true, false, slug),
        ]);
    return {
        id: `mock-${slug}`,
        name,
        native_name: null,
        slug,
        category,
        script,
        publisher: {
            bio: `Mock publisher bio for ${publisher}`,
            email: null,
            id: `pub-${slug}`,
            links: [],
            name: publisher,
        },
        designers: [
            {
                bio: `Mock designer bio for ${designer}`,
                links: [],
                name: designer,
            },
        ],
        related_families: null,
        display_publisher_as_designer: false,
        trials_enabled: true,
        show_latin_metrics: false,
        license_type: 'ofl',
        languages: 'English, Spanish, French, German',
        inserted_at: '2021-03-12T20:49:05Z',
        story: `<p>A mock font story for ${name}.</p>`,
        version,
        views,
        views_recent: Math.floor(views * 0.1),
        is_hot: views > 5000,
        is_new: views < 500,
        is_shortlisted: null,
        is_top: views > 10000,
        axes: isVariable
            ? [
                {
                    name: 'Weight',
                    property: 'wght',
                    range_default: 400,
                    range_left: 300,
                    range_right: 700,
                },
            ]
            : [],
        font_tags: tags.map(name => ({ name })),
        features: [],
        styles,
    };
 }
 /**
 * Preset Fontshare font mocks
 */
 export const FONTHARE_FONTS: Record<string, FontshareFont> = {
    satoshi: mockFontshareFont({
        name: 'Satoshi',
        slug: 'satoshi',
        category: 'sans',
        isVariable: true,
        views: 15000,
        tags: ['Branding', 'Logos', 'Editorial'],
        publisher: 'Indian Type Foundry',
        designer: 'Denis Shelabovets',
    }),
    generalSans: mockFontshareFont({
        name: 'General Sans',
        slug: 'general-sans',
        category: 'sans',
        isVariable: true,
        views: 12000,
        tags: ['UI', 'Branding', 'Display'],
        publisher: 'Indestructible Type',
        designer: 'Eugene Tantsur',
    }),
    clashDisplay: mockFontshareFont({
        name: 'Clash Display',
        slug: 'clash-display',
        category: 'display',
        isVariable: false,
        views: 8000,
        tags: ['Headlines', 'Posters', 'Branding'],
        weights: [400, 500, 600, 700],
        publisher: 'Letterogika',
        designer: 'Matěj Trnka',
    }),
    fonta: mockFontshareFont({
        name: 'Fonta',
        slug: 'fonta',
        category: 'serif',
        isVariable: false,
        views: 5000,
        tags: ['Editorial', 'Books', 'Magazines'],
        weights: [300, 400, 500, 600, 700],
        publisher: 'Fonta',
        designer: 'Alexei Vanyashin',
    }),
    aileron: mockFontshareFont({
        name: 'Aileron',
        slug: 'aileron',
        category: 'sans',
        isVariable: false,
        views: 3000,
        tags: ['Display', 'Headlines'],
        weights: [100, 200, 300, 400, 500, 600, 700, 800, 900],
        publisher: 'Sorkin Type',
        designer: 'Sorkin Type',
    }),
    beVietnamPro: mockFontshareFont({
        name: 'Be Vietnam Pro',
        slug: 'be-vietnam-pro',
        category: 'sans',
        isVariable: true,
        views: 20000,
        tags: ['UI', 'App', 'Web'],
        publisher: 'ildefox',
        designer: 'Manh Nguyen',
    }),
 };
 // UNIFIED FONT MOCKS
 /**
--- a/src/entities/Font/lib/mocks/index.ts
+++ b/src/entities/Font/lib/mocks/index.ts
@@ -26,17 +26,11 @@
 // Font mocks
 export {
    FONTHARE_FONTS,
    generateMixedCategoryFonts,
    generateMockFonts,
    getAllMockFonts,
    getFontsByCategory,
    getFontsByProvider,
    GOOGLE_FONTS,
    mockFontshareFont,
    type MockFontshareFontOptions,
    mockGoogleFont,
    type MockGoogleFontOptions,
    mockUnifiedFont,
    type MockUnifiedFontOptions,
    UNIFIED_FONTS,
@@ -51,10 +45,8 @@ export {
    createSubsetsFilter,
    FONT_PROVIDERS,
    FONT_SUBSETS,
    FONTHARE_CATEGORIES,
    generateSequentialFilter,
    GENERIC_FILTERS,
    GOOGLE_CATEGORIES,
    MOCK_FILTERS,
    MOCK_FILTERS_ALL_SELECTED,
    MOCK_FILTERS_EMPTY,
--- a/src/entities/Font/lib/mocks/stores.mock.ts
+++ b/src/entities/Font/lib/mocks/stores.mock.ts
@@ -20,7 +20,7 @@
 * const successState = createMockQueryState({ status: 'success', data: mockFonts });
 *
 * // Use preset stores
- * const mockFontStore = MOCK_STORES.unifiedFontStore();
+ * const mockFontStore = createMockFontStore();
 * ```
 */
@@ -459,6 +459,117 @@ export const MOCK_STORES = {
            resetFilters: () => {},
        };
    },
    /**
     * Create a mock FontStore object
     * Matches FontStore's public API for Storybook use
     */
    fontStore: (config: {
        fonts?: UnifiedFont[];
        total?: number;
        limit?: number;
        offset?: number;
        isLoading?: boolean;
        isFetching?: boolean;
        isError?: boolean;
        error?: Error | null;
        hasMore?: boolean;
        page?: number;
    } = {}) => {
        const {
            fonts: mockFonts = Object.values(UNIFIED_FONTS).slice(0, 5),
            total: mockTotal = mockFonts.length,
            limit = 50,
            offset = 0,
            isLoading = false,
            isFetching = false,
            isError = false,
            error = null,
            hasMore = false,
            page = 1,
        } = config;
        const totalPages = Math.ceil(mockTotal / limit);
        const state = {
            params: { limit },
        };
        return {
            // State getters
            get params() {
                return state.params;
            },
            get fonts() {
                return mockFonts;
            },
            get isLoading() {
                return isLoading;
            },
            get isFetching() {
                return isFetching;
            },
            get isError() {
                return isError;
            },
            get error() {
                return error;
            },
            get isEmpty() {
                return !isLoading && !isFetching && mockFonts.length === 0;
            },
            get pagination() {
                return {
                    total: mockTotal,
                    limit,
                    offset,
                    hasMore,
                    page,
                    totalPages,
                };
            },
            // Category getters
            get sansSerifFonts() {
                return mockFonts.filter(f => f.category === 'sans-serif');
            },
            get serifFonts() {
                return mockFonts.filter(f => f.category === 'serif');
            },
            get displayFonts() {
                return mockFonts.filter(f => f.category === 'display');
            },
            get handwritingFonts() {
                return mockFonts.filter(f => f.category === 'handwriting');
            },
            get monospaceFonts() {
                return mockFonts.filter(f => f.category === 'monospace');
            },
            // Lifecycle
            destroy() {},
            // Param management
            setParams(_updates: Record<string, unknown>) {},
            invalidate() {},
            // Async operations (no-op for Storybook)
            refetch() {},
            prefetch() {},
            cancel() {},
            getCachedData() {
                return mockFonts.length > 0 ? mockFonts : undefined;
            },
            setQueryData() {},
            // Filter shortcuts
            setProviders() {},
            setCategories() {},
            setSubsets() {},
            setSearch() {},
            setSort() {},
            // Pagination navigation
            nextPage() {},
            prevPage() {},
            goToPage() {},
            setLimit(_limit: number) {
                state.params.limit = _limit;
            },
        };
    },
 };
 // REACTIVE STATE MOCKS
--- a/src/entities/Font/lib/normalize/normalize.test.ts
+++ b/src/entities/Font/lib/normalize/normalize.test.ts
@@ -1,582 +0,0 @@
 import {
    describe,
    expect,
    it,
 } from 'vitest';
 import type {
    FontItem,
    FontshareFont,
    GoogleFontItem,
 } from '../../model/types';
 import {
    normalizeFontshareFont,
    normalizeFontshareFonts,
    normalizeGoogleFont,
    normalizeGoogleFonts,
 } from './normalize';
 describe('Font Normalization', () => {
    describe('normalizeGoogleFont', () => {
        const mockGoogleFont: GoogleFontItem = {
            family: 'Roboto',
            category: 'sans-serif',
            variants: ['regular', '700', 'italic', '700italic'],
            subsets: ['latin', 'latin-ext'],
            files: {
                regular: 'https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                '700': 'https://fonts.gstatic.com/s/roboto/v30/KFOlCnqEu92Fr1Mu72xWUlvAx05IsDqlA.woff2',
                italic: 'https://fonts.gstatic.com/s/roboto/v30/KFOkCnqEu92Fr1Mu51xIIzI.woff2',
                '700italic': 'https://fonts.gstatic.com/s/roboto/v30/KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2',
            },
            version: 'v30',
            lastModified: '2022-01-01',
            menu: 'https://fonts.googleapis.com/css2?family=Roboto',
        };
        it('normalizes Google Font to unified model', () => {
            const result = normalizeGoogleFont(mockGoogleFont);
            expect(result.id).toBe('Roboto');
            expect(result.name).toBe('Roboto');
            expect(result.provider).toBe('google');
            expect(result.category).toBe('sans-serif');
        });
        it('maps font variants correctly', () => {
            const result = normalizeGoogleFont(mockGoogleFont);
            expect(result.variants).toEqual(['regular', '700', 'italic', '700italic']);
        });
        it('maps subsets correctly', () => {
            const result = normalizeGoogleFont(mockGoogleFont);
            expect(result.subsets).toContain('latin');
            expect(result.subsets).toContain('latin-ext');
            expect(result.subsets).toHaveLength(2);
        });
        it('maps style URLs correctly', () => {
            const result = normalizeGoogleFont(mockGoogleFont);
            expect(result.styles.regular).toBeDefined();
            expect(result.styles.bold).toBeDefined();
            expect(result.styles.italic).toBeDefined();
            expect(result.styles.boldItalic).toBeDefined();
        });
        it('includes metadata', () => {
            const result = normalizeGoogleFont(mockGoogleFont);
            expect(result.metadata.cachedAt).toBeDefined();
            expect(result.metadata.version).toBe('v30');
            expect(result.metadata.lastModified).toBe('2022-01-01');
        });
        it('marks Google Fonts as non-variable', () => {
            const result = normalizeGoogleFont(mockGoogleFont);
            expect(result.features.isVariable).toBe(false);
            expect(result.features.tags).toEqual([]);
        });
        it('handles sans-serif category', () => {
            const font: FontItem = { ...mockGoogleFont, category: 'sans-serif' };
            const result = normalizeGoogleFont(font);
            expect(result.category).toBe('sans-serif');
        });
        it('handles serif category', () => {
            const font: FontItem = { ...mockGoogleFont, category: 'serif' };
            const result = normalizeGoogleFont(font);
            expect(result.category).toBe('serif');
        });
        it('handles display category', () => {
            const font: FontItem = { ...mockGoogleFont, category: 'display' };
            const result = normalizeGoogleFont(font);
            expect(result.category).toBe('display');
        });
        it('handles handwriting category', () => {
            const font: FontItem = { ...mockGoogleFont, category: 'handwriting' };
            const result = normalizeGoogleFont(font);
            expect(result.category).toBe('handwriting');
        });
        it('handles cursive category (maps to handwriting)', () => {
            const font: FontItem = { ...mockGoogleFont, category: 'cursive' as any };
            const result = normalizeGoogleFont(font);
            expect(result.category).toBe('handwriting');
        });
        it('handles monospace category', () => {
            const font: FontItem = { ...mockGoogleFont, category: 'monospace' };
            const result = normalizeGoogleFont(font);
            expect(result.category).toBe('monospace');
        });
        it('filters invalid subsets', () => {
            const font = {
                ...mockGoogleFont,
                subsets: ['latin', 'latin-ext', 'invalid-subset'],
            };
            const result = normalizeGoogleFont(font);
            expect(result.subsets).not.toContain('invalid-subset');
            expect(result.subsets).toHaveLength(2);
        });
        it('maps variant weights correctly', () => {
            const font: GoogleFontItem = {
                ...mockGoogleFont,
                variants: ['regular', '100', '400', '700', '900'] as any,
            };
            const result = normalizeGoogleFont(font);
            expect(result.variants).toContain('regular');
            expect(result.variants).toContain('100');
            expect(result.variants).toContain('400');
            expect(result.variants).toContain('700');
            expect(result.variants).toContain('900');
        });
    });
    describe('normalizeFontshareFont', () => {
        const mockFontshareFont: FontshareFont = {
            id: '20e9fcdc-1e41-4559-a43d-1ede0adc8896',
            name: 'Satoshi',
            native_name: null,
            slug: 'satoshi',
            category: 'Sans',
            script: 'latin',
            publisher: {
                bio: 'Indian Type Foundry',
                email: null,
                id: 'test-id',
                links: [],
                name: 'Indian Type Foundry',
            },
            designers: [
                {
                    bio: 'Designer bio',
                    links: [],
                    name: 'Designer Name',
                },
            ],
            related_families: null,
            display_publisher_as_designer: false,
            trials_enabled: true,
            show_latin_metrics: false,
            license_type: 'itf_ffl',
            languages: 'Afar, Afrikaans',
            inserted_at: '2021-03-12T20:49:05Z',
            story: '<p>Font story</p>',
            version: '1.0',
            views: 10000,
            views_recent: 500,
            is_hot: true,
            is_new: false,
            is_shortlisted: false,
            is_top: true,
            axes: [],
            font_tags: [
                { name: 'Branding' },
                { name: 'Logos' },
            ],
            features: [
                {
                    name: 'Alternate t',
                    on_by_default: false,
                    tag: 'ss01',
                },
            ],
            styles: [
                {
                    id: 'style-id-1',
                    default: true,
                    file: '//cdn.fontshare.com/wf/satoshi.woff2',
                    is_italic: false,
                    is_variable: false,
                    properties: {},
                    weight: {
                        label: 'Regular',
                        name: 'Regular',
                        native_name: null,
                        number: 400,
                        weight: 400,
                    },
                },
                {
                    id: 'style-id-2',
                    default: false,
                    file: '//cdn.fontshare.com/wf/satoshi-bold.woff2',
                    is_italic: false,
                    is_variable: false,
                    properties: {},
                    weight: {
                        label: 'Bold',
                        name: 'Bold',
                        native_name: null,
                        number: 700,
                        weight: 700,
                    },
                },
                {
                    id: 'style-id-3',
                    default: false,
                    file: '//cdn.fontshare.com/wf/satoshi-italic.woff2',
                    is_italic: true,
                    is_variable: false,
                    properties: {},
                    weight: {
                        label: 'Regular',
                        name: 'Regular',
                        native_name: null,
                        number: 400,
                        weight: 400,
                    },
                },
                {
                    id: 'style-id-4',
                    default: false,
                    file: '//cdn.fontshare.com/wf/satoshi-bolditalic.woff2',
                    is_italic: true,
                    is_variable: false,
                    properties: {},
                    weight: {
                        label: 'Bold',
                        name: 'Bold',
                        native_name: null,
                        number: 700,
                        weight: 700,
                    },
                },
            ],
        };
        it('normalizes Fontshare font to unified model', () => {
            const result = normalizeFontshareFont(mockFontshareFont);
            expect(result.id).toBe('satoshi');
            expect(result.name).toBe('Satoshi');
            expect(result.provider).toBe('fontshare');
            expect(result.category).toBe('sans-serif');
        });
        it('uses slug as unique identifier', () => {
            const result = normalizeFontshareFont(mockFontshareFont);
            expect(result.id).toBe('satoshi');
        });
        it('extracts variant names from styles', () => {
            const result = normalizeFontshareFont(mockFontshareFont);
            expect(result.variants).toContain('Regular');
            expect(result.variants).toContain('Bold');
            expect(result.variants).toContain('Regularitalic');
            expect(result.variants).toContain('Bolditalic');
        });
        it('maps Fontshare Sans to sans-serif category', () => {
            const font = { ...mockFontshareFont, category: 'Sans' };
            const result = normalizeFontshareFont(font);
            expect(result.category).toBe('sans-serif');
        });
        it('maps Fontshare Serif to serif category', () => {
            const font = { ...mockFontshareFont, category: 'Serif' };
            const result = normalizeFontshareFont(font);
            expect(result.category).toBe('serif');
        });
        it('maps Fontshare Display to display category', () => {
            const font = { ...mockFontshareFont, category: 'Display' };
            const result = normalizeFontshareFont(font);
            expect(result.category).toBe('display');
        });
        it('maps Fontshare Script to handwriting category', () => {
            const font = { ...mockFontshareFont, category: 'Script' };
            const result = normalizeFontshareFont(font);
            expect(result.category).toBe('handwriting');
        });
        it('maps Fontshare Mono to monospace category', () => {
            const font = { ...mockFontshareFont, category: 'Mono' };
            const result = normalizeFontshareFont(font);
            expect(result.category).toBe('monospace');
        });
        it('maps style URLs correctly', () => {
            const result = normalizeFontshareFont(mockFontshareFont);
            expect(result.styles.regular).toBe('//cdn.fontshare.com/wf/satoshi.woff2');
            expect(result.styles.bold).toBe('//cdn.fontshare.com/wf/satoshi-bold.woff2');
            expect(result.styles.italic).toBe('//cdn.fontshare.com/wf/satoshi-italic.woff2');
            expect(result.styles.boldItalic).toBe(
                '//cdn.fontshare.com/wf/satoshi-bolditalic.woff2',
            );
        });
        it('handles variable fonts', () => {
            const variableFont: FontshareFont = {
                ...mockFontshareFont,
                axes: [
                    {
                        name: 'wght',
                        property: 'wght',
                        range_default: 400,
                        range_left: 300,
                        range_right: 900,
                    },
                ],
                styles: [
                    {
                        id: 'var-style',
                        default: true,
                        file: '//cdn.fontshare.com/wf/satoshi-variable.woff2',
                        is_italic: false,
                        is_variable: true,
                        properties: {},
                        weight: {
                            label: 'Variable',
                            name: 'Variable',
                            native_name: null,
                            number: 0,
                            weight: 0,
                        },
                    },
                ],
            };
            const result = normalizeFontshareFont(variableFont);
            expect(result.features.isVariable).toBe(true);
            expect(result.features.axes).toHaveLength(1);
            expect(result.features.axes?.[0].name).toBe('wght');
        });
        it('extracts font tags', () => {
            const result = normalizeFontshareFont(mockFontshareFont);
            expect(result.features.tags).toContain('Branding');
            expect(result.features.tags).toContain('Logos');
            expect(result.features.tags).toHaveLength(2);
        });
        it('includes popularity from views', () => {
            const result = normalizeFontshareFont(mockFontshareFont);
            expect(result.metadata.popularity).toBe(10000);
        });
        it('includes metadata', () => {
            const result = normalizeFontshareFont(mockFontshareFont);
            expect(result.metadata.cachedAt).toBeDefined();
            expect(result.metadata.version).toBe('1.0');
            expect(result.metadata.lastModified).toBe('2021-03-12T20:49:05Z');
        });
        it('handles missing subsets gracefully', () => {
            const font = {
                ...mockFontshareFont,
                script: 'invalid-script',
            };
            const result = normalizeFontshareFont(font);
            expect(result.subsets).toEqual([]);
        });
        it('handles empty tags', () => {
            const font = {
                ...mockFontshareFont,
                font_tags: [],
            };
            const result = normalizeFontshareFont(font);
            expect(result.features.tags).toBeUndefined();
        });
        it('handles empty axes', () => {
            const font = {
                ...mockFontshareFont,
                axes: [],
            };
            const result = normalizeFontshareFont(font);
            expect(result.features.isVariable).toBe(false);
            expect(result.features.axes).toBeUndefined();
        });
    });
    describe('normalizeGoogleFonts', () => {
        it('normalizes array of Google Fonts', () => {
            const fonts: GoogleFontItem[] = [
                {
                    family: 'Roboto',
                    category: 'sans-serif',
                    variants: ['regular'],
                    subsets: ['latin'],
                    files: { regular: 'url' },
                    version: 'v1',
                    lastModified: '2022-01-01',
                    menu: 'https://fonts.googleapis.com/css2?family=Roboto',
                },
                {
                    family: 'Open Sans',
                    category: 'sans-serif',
                    variants: ['regular'],
                    subsets: ['latin'],
                    files: { regular: 'url' },
                    version: 'v1',
                    lastModified: '2022-01-01',
                    menu: 'https://fonts.googleapis.com/css2?family=Open+Sans',
                },
            ];
            const result = normalizeGoogleFonts(fonts);
            expect(result).toHaveLength(2);
            expect(result[0].name).toBe('Roboto');
            expect(result[1].name).toBe('Open Sans');
        });
        it('returns empty array for empty input', () => {
            const result = normalizeGoogleFonts([]);
            expect(result).toEqual([]);
        });
    });
    describe('normalizeFontshareFonts', () => {
        it('normalizes array of Fontshare fonts', () => {
            const fonts: FontshareFont[] = [
                {
                    ...mockMinimalFontshareFont('font1', 'Font 1'),
                },
                {
                    ...mockMinimalFontshareFont('font2', 'Font 2'),
                },
            ];
            const result = normalizeFontshareFonts(fonts);
            expect(result).toHaveLength(2);
            expect(result[0].name).toBe('Font 1');
            expect(result[1].name).toBe('Font 2');
        });
        it('returns empty array for empty input', () => {
            const result = normalizeFontshareFonts([]);
            expect(result).toEqual([]);
        });
    });
    describe('edge cases', () => {
        it('handles Google Font with missing optional fields', () => {
            const font: Partial<GoogleFontItem> = {
                family: 'Test Font',
                category: 'sans-serif',
                variants: ['regular'],
                subsets: ['latin'],
                files: { regular: 'url' },
            };
            const result = normalizeGoogleFont(font as GoogleFontItem);
            expect(result.id).toBe('Test Font');
            expect(result.metadata.version).toBeUndefined();
            expect(result.metadata.lastModified).toBeUndefined();
        });
        it('handles Fontshare font with minimal data', () => {
            const result = normalizeFontshareFont(mockMinimalFontshareFont('slug', 'Name'));
            expect(result.id).toBe('slug');
            expect(result.name).toBe('Name');
            expect(result.provider).toBe('fontshare');
        });
        it('handles unknown Fontshare category', () => {
            const font = {
                ...mockMinimalFontshareFont('slug', 'Name'),
                category: 'Unknown Category',
            };
            const result = normalizeFontshareFont(font);
            expect(result.category).toBe('sans-serif'); // fallback
        });
    });
 });
 /**
 * Helper function to create minimal Fontshare font mock
 */
 function mockMinimalFontshareFont(slug: string, name: string): FontshareFont {
    return {
        id: 'test-id',
        name,
        native_name: null,
        slug,
        category: 'Sans',
        script: 'latin',
        publisher: {
            bio: '',
            email: null,
            id: '',
            links: [],
            name: '',
        },
        designers: [],
        related_families: null,
        display_publisher_as_designer: false,
        trials_enabled: false,
        show_latin_metrics: false,
        license_type: '',
        languages: '',
        inserted_at: '',
        story: '',
        version: '1.0',
        views: 0,
        views_recent: 0,
        is_hot: false,
        is_new: false,
        is_shortlisted: null,
        is_top: false,
        axes: [],
        font_tags: [],
        features: [],
        styles: [
            {
                id: 'style-id',
                default: true,
                file: '//cdn.fontshare.com/wf/test.woff2',
                is_italic: false,
                is_variable: false,
                properties: {},
                weight: {
                    label: 'Regular',
                    name: 'Regular',
                    native_name: null,
                    number: 400,
                    weight: 400,
                },
            },
        ],
    };
 }
--- a/src/entities/Font/lib/normalize/normalize.ts
+++ b/src/entities/Font/lib/normalize/normalize.ts
@@ -1,275 +0,0 @@
 /**
 * Normalize fonts from Google Fonts and Fontshare to unified model
 *
 * Transforms provider-specific font data into a common interface
 * for consistent handling across the application.
 */
 import type {
    FontCategory,
    FontStyleUrls,
    FontSubset,
    FontshareFont,
    GoogleFontItem,
    UnifiedFont,
    UnifiedFontVariant,
 } from '../../model/types';
 /**
 * Map Google Fonts category to unified FontCategory
 */
 function mapGoogleCategory(category: string): FontCategory {
    const normalized = category.toLowerCase();
    if (normalized.includes('sans-serif')) {
        return 'sans-serif';
    }
    if (normalized.includes('serif')) {
        return 'serif';
    }
    if (normalized.includes('display')) {
        return 'display';
    }
    if (normalized.includes('handwriting') || normalized.includes('cursive')) {
        return 'handwriting';
    }
    if (normalized.includes('monospace')) {
        return 'monospace';
    }
    // Default fallback
    return 'sans-serif';
 }
 /**
 * Map Fontshare category to unified FontCategory
 */
 function mapFontshareCategory(category: string): FontCategory {
    const normalized = category.toLowerCase();
    if (normalized === 'sans' || normalized === 'sans-serif') {
        return 'sans-serif';
    }
    if (normalized === 'serif') {
        return 'serif';
    }
    if (normalized === 'display') {
        return 'display';
    }
    if (normalized === 'script') {
        return 'handwriting';
    }
    if (normalized === 'mono' || normalized === 'monospace') {
        return 'monospace';
    }
    // Default fallback
    return 'sans-serif';
 }
 /**
 * Map Google subset to unified FontSubset
 */
 function mapGoogleSubset(subset: string): FontSubset | null {
    const validSubsets: FontSubset[] = [
        'latin',
        'latin-ext',
        'cyrillic',
        'greek',
        'arabic',
        'devanagari',
    ];
    return validSubsets.includes(subset as FontSubset)
        ? (subset as FontSubset)
        : null;
 }
 /**
 * Map Fontshare script to unified FontSubset
 */
 function mapFontshareScript(script: string): FontSubset | null {
    const normalized = script.toLowerCase();
    const mapping: Record<string, FontSubset | null> = {
        latin: 'latin',
        'latin-ext': 'latin-ext',
        cyrillic: 'cyrillic',
        greek: 'greek',
        arabic: 'arabic',
        devanagari: 'devanagari',
    };
    return mapping[normalized] ?? null;
 }
 /**
 * Normalize Google Font to unified model
 *
 * @param apiFont - Font item from Google Fonts API
 * @returns Unified font model
 *
 * @example
 * ```ts
 * const roboto = normalizeGoogleFont({
 *     family: 'Roboto',
 *     category: 'sans-serif',
 *     variants: ['regular', '700'],
 *     subsets: ['latin', 'latin-ext'],
 *     files: { regular: '...', '700': '...' }
 * });
 *
 * console.log(roboto.id); // 'Roboto'
 * console.log(roboto.provider); // 'google'
 * ```
 */
 export function normalizeGoogleFont(apiFont: GoogleFontItem): UnifiedFont {
    const category = mapGoogleCategory(apiFont.category);
    const subsets = apiFont.subsets
        .map(mapGoogleSubset)
        .filter((subset): subset is FontSubset => subset !== null);
    // Map variant files to style URLs
    const styles: FontStyleUrls = {};
    for (const [variant, url] of Object.entries(apiFont.files)) {
        const urlString = url as string; // Type assertion for Record<string, string>
        if (variant === 'regular' || variant === '400') {
            styles.regular = urlString;
        } else if (variant === 'italic' || variant === '400italic') {
            styles.italic = urlString;
        } else if (variant === 'bold' || variant === '700') {
            styles.bold = urlString;
        } else if (variant === 'bolditalic' || variant === '700italic') {
            styles.boldItalic = urlString;
        }
    }
    return {
        id: apiFont.family,
        name: apiFont.family,
        provider: 'google',
        category,
        subsets,
        variants: apiFont.variants,
        styles,
        metadata: {
            cachedAt: Date.now(),
            version: apiFont.version,
            lastModified: apiFont.lastModified,
        },
        features: {
            isVariable: false, // Google Fonts doesn't expose variable font info
            tags: [],
        },
    };
 }
 /**
 * Normalize Fontshare font to unified model
 *
 * @param apiFont - Font item from Fontshare API
 * @returns Unified font model
 *
 * @example
 * ```ts
 * const satoshi = normalizeFontshareFont({
 *     id: 'uuid',
 *     name: 'Satoshi',
 *     slug: 'satoshi',
 *     category: 'Sans',
 *     script: 'latin',
 *     styles: [ ... ]
 * });
 *
 * console.log(satoshi.id); // 'satoshi'
 * console.log(satoshi.provider); // 'fontshare'
 * ```
 */
 export function normalizeFontshareFont(apiFont: FontshareFont): UnifiedFont {
    const category = mapFontshareCategory(apiFont.category);
    const subset = mapFontshareScript(apiFont.script);
    const subsets = subset ? [subset] : [];
    // Extract variant names from styles
    const variants = apiFont.styles.map(style => {
        const weightLabel = style.weight.label;
        const isItalic = style.is_italic;
        return (isItalic ? `${weightLabel}italic` : weightLabel) as UnifiedFontVariant;
    });
    // Map styles to URLs
    const styles: FontStyleUrls = {};
    for (const style of apiFont.styles) {
        if (style.is_variable) {
            // Variable font - store as primary variant
            styles.regular = style.file;
            break;
        }
        const weight = style.weight.number;
        const isItalic = style.is_italic;
        if (weight === 400 && !isItalic) {
            styles.regular = style.file;
        } else if (weight === 400 && isItalic) {
            styles.italic = style.file;
        } else if (weight >= 700 && !isItalic) {
            styles.bold = style.file;
        } else if (weight >= 700 && isItalic) {
            styles.boldItalic = style.file;
        }
    }
    // Extract variable font axes
    const axes = apiFont.axes.map(axis => ({
        name: axis.name,
        property: axis.property,
        default: axis.range_default,
        min: axis.range_left,
        max: axis.range_right,
    }));
    // Extract tags
    const tags = apiFont.font_tags.map(tag => tag.name);
    return {
        id: apiFont.slug,
        name: apiFont.name,
        provider: 'fontshare',
        category,
        subsets,
        variants,
        styles,
        metadata: {
            cachedAt: Date.now(),
            version: apiFont.version,
            lastModified: apiFont.inserted_at,
            popularity: apiFont.views,
        },
        features: {
            isVariable: apiFont.axes.length > 0,
            axes: axes.length > 0 ? axes : undefined,
            tags: tags.length > 0 ? tags : undefined,
        },
    };
 }
 /**
 * Normalize multiple Google Fonts to unified model
 *
 * @param apiFonts - Array of Google Font items
 * @returns Array of unified fonts
 */
 export function normalizeGoogleFonts(
    apiFonts: GoogleFontItem[],
 ): UnifiedFont[] {
    return apiFonts.map(normalizeGoogleFont);
 }
 /**
 * Normalize multiple Fontshare fonts to unified model
 *
 * @param apiFonts - Array of Fontshare font items
 * @returns Array of unified fonts
 */
 export function normalizeFontshareFonts(
    apiFonts: FontshareFont[],
 ): UnifiedFont[] {
    return apiFonts.map(normalizeFontshareFont);
 }
 // Re-export UnifiedFont for backward compatibility
 export type { UnifiedFont } from '../../model/types/normalize';
--- a/src/entities/Font/lib/sizeResolver/createFontRowSizeResolver.test.ts
+++ b/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);
    });
 });
--- a/src/entities/Font/lib/sizeResolver/createFontRowSizeResolver.ts
+++ b/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;
    };
 }
--- a/src/entities/Font/model/index.ts
+++ b/src/entities/Font/model/index.ts
@@ -1,43 +1,2 @@
-export type {
+export * from './store';
-    // Domain types
+export * from './types';
    FontCategory,
    FontCollectionFilters,
    FontCollectionSort,
    // Store types
    FontCollectionState,
    FontFeatures,
    FontFiles,
    FontItem,
    FontMetadata,
    FontProvider,
    // Fontshare API types
    FontshareApiModel,
    FontshareAxis,
    FontshareDesigner,
    FontshareFeature,
    FontshareFont,
    FontshareLink,
    FontsharePublisher,
    FontshareStyle,
    FontshareStyleProperties,
    FontshareTag,
    FontshareWeight,
    FontStyleUrls,
    FontSubset,
    FontVariant,
    FontWeight,
    FontWeightItalic,
    // Google Fonts API types
    GoogleFontsApiModel,
    // Normalization types
    UnifiedFont,
    UnifiedFontVariant,
 } from './types';
 export {
    appliedFontsManager,
    createUnifiedFontStore,
    type FontConfigRequest,
    type UnifiedFontStore,
    unifiedFontStore,
 } from './store';
--- a/src/entities/Font/model/store/appliedFontsStore/appliedFontStore.test.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/appliedFontStore.test.ts
@@ -1,73 +1,63 @@
 /** @vitest-environment jsdom */
 import {
    afterEach,
    beforeEach,
    describe,
    expect,
    it,
    vi,
 } from 'vitest';
 import { AppliedFontsManager } from './appliedFontsStore.svelte';
 import { FontFetchError } from './errors';
 import { FontEvictionPolicy } from './utils/fontEvictionPolicy/FontEvictionPolicy';
 // ── Fake collaborators ────────────────────────────────────────────────────────
 class FakeBufferCache {
    async get(_url: string): Promise<ArrayBuffer> {
        return new ArrayBuffer(8);
    }
    evict(_url: string): void {}
    clear(): void {}
 }
 /** Throws {@link FontFetchError} on every `get()` — simulates network/HTTP failure. */
 class FailingBufferCache {
    async get(url: string): Promise<never> {
        throw new FontFetchError(url, new Error('network error'), 500);
    }
    evict(_url: string): void {}
    clear(): void {}
 }
 // ── Helpers ───────────────────────────────────────────────────────────────────
 const makeConfig = (id: string, overrides: Partial<{ weight: number; isVariable: boolean }> = {}) => ({
    id,
    name: id,
    url: `https://example.com/${id}.woff2`,
    weight: 400,
    ...overrides,
 });
 // ── Suite ─────────────────────────────────────────────────────────────────────
 describe('AppliedFontsManager', () => {
    let manager: AppliedFontsManager;
-    let mockFontFaceSet: any;
+    let eviction: FontEvictionPolicy;
-    let mockFetch: any;
+    let mockFontFaceSet: { add: ReturnType<typeof vi.fn>; delete: ReturnType<typeof vi.fn> };
    let failUrls: Set<string>;
    beforeEach(() => {
        vi.useFakeTimers();
-        failUrls = new Set();
+        eviction = new FontEvictionPolicy({ ttl: 60000 });
        mockFontFaceSet = { add: vi.fn(), delete: vi.fn() };
        mockFontFaceSet = {
            add: vi.fn(),
            delete: vi.fn(),
        };
        // 1. Properly mock FontFace as a constructor function
        // The actual implementation passes buffer (ArrayBuffer) as second arg, not URL string
        const MockFontFace = vi.fn(function(this: any, name: string, bufferOrUrl: ArrayBuffer | string) {
            this.name = name;
            this.bufferOrUrl = bufferOrUrl;
            this.load = vi.fn().mockImplementation(() => {
                // For error tests, we track which URLs should fail via failUrls
                // The fetch mock will have already rejected for those URLs
                return Promise.resolve(this);
            });
        });
        vi.stubGlobal('FontFace', MockFontFace);
        // 2. Mock document.fonts safely
        Object.defineProperty(document, 'fonts', {
            value: mockFontFaceSet,
            configurable: true,
            writable: true,
        });
-        vi.stubGlobal('crypto', {
+        const MockFontFace = vi.fn(function(this: any, name: string, buffer: BufferSource) {
-            randomUUID: () => '11111111-1111-1111-1111-111111111111' as any,
+            this.name = name;
            this.buffer = buffer;
            this.load = vi.fn().mockResolvedValue(this);
        });
        vi.stubGlobal('FontFace', MockFontFace);
-        // 3. Mock fetch to return fake ArrayBuffer data
+        manager = new AppliedFontsManager({ cache: new FakeBufferCache() as any, eviction });
        mockFetch = vi.fn((url: string) => {
            if (failUrls.has(url)) {
                return Promise.reject(new Error('Network error'));
            }
            return Promise.resolve({
                ok: true,
                status: 200,
                arrayBuffer: () => Promise.resolve(new ArrayBuffer(8)),
                clone: () => ({
                    ok: true,
                    status: 200,
                    arrayBuffer: () => Promise.resolve(new ArrayBuffer(8)),
                }),
            } as Response);
        });
        vi.stubGlobal('fetch', mockFetch);
        manager = new AppliedFontsManager();
    });
    afterEach(() => {
@@ -76,138 +66,267 @@ describe('AppliedFontsManager', () => {
        vi.unstubAllGlobals();
    });
-    it('should batch multiple font requests into a single process', async () => {
+    // ── touch() ───────────────────────────────────────────────────────────────
        const configs = [
            { id: 'lato-400', name: 'Lato', url: 'https://example.com/lato.ttf', weight: 400 },
            { id: 'lato-700', name: 'Lato', url: 'https://example.com/lato-bold.ttf', weight: 700 },
        ];
-        manager.touch(configs);
+    describe('touch()', () => {
        it('queues and loads a new font', async () => {
            manager.touch([makeConfig('roboto')]);
            await vi.advanceTimersByTimeAsync(50);
-        // Advance to trigger the 16ms debounced #processQueue
+            expect(manager.getFontStatus('roboto', 400)).toBe('loaded');
-        await vi.advanceTimersByTimeAsync(50);
+        });
-        expect(manager.getFontStatus('lato-400', 400)).toBe('loaded');
+        it('batches multiple fonts into a single queue flush', async () => {
-        expect(mockFontFaceSet.add).toHaveBeenCalledTimes(2);
+            manager.touch([makeConfig('lato'), makeConfig('inter')]);
            await vi.advanceTimersByTimeAsync(50);
            expect(mockFontFaceSet.add).toHaveBeenCalledTimes(2);
        });
        it('skips fonts that are already loaded', async () => {
            manager.touch([makeConfig('lato')]);
            await vi.advanceTimersByTimeAsync(50);
            manager.touch([makeConfig('lato')]);
            await vi.advanceTimersByTimeAsync(50);
            expect(mockFontFaceSet.add).toHaveBeenCalledTimes(1);
        });
        it('skips fonts that are currently loading', async () => {
            manager.touch([makeConfig('lato')]);
            // simulate loading state before queue drains
            manager.statuses.set('lato@400', 'loading');
            manager.touch([makeConfig('lato')]);
            await vi.advanceTimersByTimeAsync(50);
            expect(mockFontFaceSet.add).toHaveBeenCalledTimes(1);
        });
        it('skips fonts that have exhausted retries', async () => {
            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
            const failManager = new AppliedFontsManager({ cache: new FailingBufferCache() as any, eviction });
            // exhaust all 3 retries
            for (let i = 0; i < 3; i++) {
                failManager.statuses.delete('broken@400');
                failManager.touch([makeConfig('broken')]);
                await vi.advanceTimersByTimeAsync(50);
            }
            failManager.touch([makeConfig('broken')]);
            await vi.advanceTimersByTimeAsync(50);
            expect(failManager.getFontStatus('broken', 400)).toBe('error');
            expect(mockFontFaceSet.add).not.toHaveBeenCalled();
            consoleSpy.mockRestore();
        });
        it('does nothing after manager is destroyed', async () => {
            manager.destroy();
            manager.touch([makeConfig('roboto')]);
            await vi.advanceTimersByTimeAsync(50);
            expect(manager.statuses.size).toBe(0);
        });
    });
-    it('should handle font loading errors gracefully', async () => {
+    // ── queue processing ──────────────────────────────────────────────────────
        // Suppress expected console error for clean test logs
        const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
-        const failUrl = 'https://example.com/fail.ttf';
+    describe('queue processing', () => {
-        failUrls.add(failUrl);
+        it('filters non-critical weights in data-saver mode', async () => {
            (navigator as any).connection = { saveData: true };
-        const config = { id: 'broken', name: 'Broken', url: failUrl, weight: 400 };
+            manager.touch([
                makeConfig('light', { weight: 300 }),
                makeConfig('regular', { weight: 400 }),
                makeConfig('bold', { weight: 700 }),
            ]);
            await vi.advanceTimersByTimeAsync(50);
-        manager.touch([config]);
+            expect(manager.getFontStatus('light', 300)).toBeUndefined();
-        await vi.advanceTimersByTimeAsync(50);
+            expect(manager.getFontStatus('regular', 400)).toBe('loaded');
            expect(manager.getFontStatus('bold', 700)).toBe('loaded');
-        expect(manager.getFontStatus('broken', 400)).toBe('error');
+            delete (navigator as any).connection;
-        spy.mockRestore();
+        });
        it('loads variable fonts in data-saver mode regardless of weight', async () => {
            (navigator as any).connection = { saveData: true };
            manager.touch([makeConfig('vf', { weight: 300, isVariable: true })]);
            await vi.advanceTimersByTimeAsync(50);
            expect(manager.getFontStatus('vf', 300, true)).toBe('loaded');
            delete (navigator as any).connection;
        });
    });
-    it('should purge fonts after TTL expires', async () => {
+    // ── Phase 1: fetch ────────────────────────────────────────────────────────
        const config = { id: 'ephemeral', name: 'Temp', url: 'https://example.com/temp.ttf', weight: 400 };
-        manager.touch([config]);
+    describe('Phase 1 — fetch', () => {
-        await vi.advanceTimersByTimeAsync(50);
+        it('sets status to error on fetch failure', async () => {
-        expect(manager.getFontStatus('ephemeral', 400)).toBe('loaded');
+            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
            const failManager = new AppliedFontsManager({ cache: new FailingBufferCache() as any, eviction });
-        // Move clock forward past TTL (5m) and Purge Interval (1m)
+            failManager.touch([makeConfig('broken')]);
-        // advanceTimersByTimeAsync is key here; it handles the promises inside the interval
+            await vi.advanceTimersByTimeAsync(50);
        await vi.advanceTimersByTimeAsync(6 * 60 * 1000);
-        expect(manager.getFontStatus('ephemeral', 400)).toBeUndefined();
+            expect(failManager.getFontStatus('broken', 400)).toBe('error');
-        expect(mockFontFaceSet.delete).toHaveBeenCalled();
+            consoleSpy.mockRestore();
        });
        it('logs a console error on fetch failure', async () => {
            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
            const failManager = new AppliedFontsManager({ cache: new FailingBufferCache() as any, eviction });
            failManager.touch([makeConfig('broken')]);
            await vi.advanceTimersByTimeAsync(50);
            expect(consoleSpy).toHaveBeenCalled();
            consoleSpy.mockRestore();
        });
        it('does not set error status or log for aborted fetches', async () => {
            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
            const abortingCache = {
                async get(url: string): Promise<never> {
                    throw new FontFetchError(url, Object.assign(new Error('Aborted'), { name: 'AbortError' }));
                },
                evict() {},
                clear() {},
            };
            const abortManager = new AppliedFontsManager({ cache: abortingCache as any, eviction });
            abortManager.touch([makeConfig('aborted')]);
            await vi.advanceTimersByTimeAsync(50);
            // status is left as 'loading' (not 'error') — abort is not a retriable failure
            expect(abortManager.getFontStatus('aborted', 400)).not.toBe('error');
            expect(consoleSpy).not.toHaveBeenCalled();
            consoleSpy.mockRestore();
        });
    });
-    it('should NOT purge fonts that are still being "touched"', async () => {
+    // ── Phase 2: parse ────────────────────────────────────────────────────────
        const config = { id: 'active', name: 'Active', url: 'https://example.com/active.ttf', weight: 400 };
-        manager.touch([config]);
+    describe('Phase 2 — parse', () => {
-        await vi.advanceTimersByTimeAsync(50);
+        it('sets status to error on parse failure', async () => {
            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
            const FailingFontFace = vi.fn(function(this: any) {
                this.load = vi.fn().mockRejectedValue(new Error('parse failed'));
            });
            vi.stubGlobal('FontFace', FailingFontFace);
-        // Advance 4 minutes
+            manager.touch([makeConfig('broken')]);
-        await vi.advanceTimersByTimeAsync(4 * 60 * 1000);
+            await vi.advanceTimersByTimeAsync(50);
-        // Refresh touch
+            expect(manager.getFontStatus('broken', 400)).toBe('error');
-        manager.touch([config]);
+            consoleSpy.mockRestore();
        });
-        // Advance another 2 minutes (Total 6 since start)
+        it('logs a console error on parse failure', async () => {
-        await vi.advanceTimersByTimeAsync(2 * 60 * 1000);
+            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
            const FailingFontFace = vi.fn(function(this: any) {
                this.load = vi.fn().mockRejectedValue(new Error('parse failed'));
            });
            vi.stubGlobal('FontFace', FailingFontFace);
-        expect(manager.getFontStatus('active', 400)).toBe('loaded');
+            manager.touch([makeConfig('broken')]);
            await vi.advanceTimersByTimeAsync(50);
            expect(consoleSpy).toHaveBeenCalled();
            consoleSpy.mockRestore();
        });
    });
-    it('should serve buffer from memory without calling fetch again', async () => {
+    // ── #purgeUnused ──────────────────────────────────────────────────────────
        const config = { id: 'cached', name: 'Cached', url: 'https://example.com/cached.ttf', weight: 400 };
-        // First load — populates in-memory buffer
+    describe('#purgeUnused', () => {
-        manager.touch([config]);
+        it('evicts fonts after TTL expires', async () => {
-        await vi.advanceTimersByTimeAsync(50);
+            manager.touch([makeConfig('ephemeral')]);
-        expect(manager.getFontStatus('cached', 400)).toBe('loaded');
+            await vi.advanceTimersByTimeAsync(50);
        expect(mockFetch).toHaveBeenCalledTimes(1);
-        // Simulate eviction by deleting the status entry directly
+            await vi.advanceTimersByTimeAsync(61000);
        manager.statuses.delete('cached@400');
-        // Second load — should hit in-memory buffer, not network
+            expect(manager.getFontStatus('ephemeral', 400)).toBeUndefined();
-        manager.touch([config]);
+            expect(mockFontFaceSet.delete).toHaveBeenCalled();
-        await vi.advanceTimersByTimeAsync(50);
+        });
-        expect(manager.getFontStatus('cached', 400)).toBe('loaded');
+        it('removes the evicted key from the eviction policy', async () => {
-        // fetch should still only have been called once (buffer was reused)
+            manager.touch([makeConfig('ephemeral')]);
-        expect(mockFetch).toHaveBeenCalledTimes(1);
+            await vi.advanceTimersByTimeAsync(50);
            await vi.advanceTimersByTimeAsync(61000);
            expect(Array.from(eviction.keys())).not.toContain('ephemeral@400');
        });
        it('refreshes TTL when font is re-touched before expiry', async () => {
            const config = makeConfig('active');
            manager.touch([config]);
            await vi.advanceTimersByTimeAsync(50);
            await vi.advanceTimersByTimeAsync(40000);
            manager.touch([config]); // refresh at t≈40s
            await vi.advanceTimersByTimeAsync(25000); // purge at t≈60s sees only ~20s elapsed → not evicted
            expect(manager.getFontStatus('active', 400)).toBe('loaded');
        });
        it('does not evict pinned fonts', async () => {
            manager.touch([makeConfig('pinned')]);
            await vi.advanceTimersByTimeAsync(50);
            manager.pin('pinned', 400);
            await vi.advanceTimersByTimeAsync(61000);
            expect(manager.getFontStatus('pinned', 400)).toBe('loaded');
            expect(mockFontFaceSet.delete).not.toHaveBeenCalled();
        });
        it('evicts font after it is unpinned and TTL expires', async () => {
            manager.touch([makeConfig('toggled')]);
            await vi.advanceTimersByTimeAsync(50);
            manager.pin('toggled', 400);
            manager.unpin('toggled', 400);
            await vi.advanceTimersByTimeAsync(61000);
            expect(manager.getFontStatus('toggled', 400)).toBeUndefined();
            expect(mockFontFaceSet.delete).toHaveBeenCalled();
        });
    });
-    it('should NOT purge a pinned font after TTL expires', async () => {
+    // ── destroy() ─────────────────────────────────────────────────────────────
        const config = { id: 'pinned', name: 'Pinned', url: 'https://example.com/pinned.ttf', weight: 400 };
-        manager.touch([config]);
+    describe('destroy()', () => {
-        await vi.advanceTimersByTimeAsync(50);
+        it('clears all statuses', async () => {
-        expect(manager.getFontStatus('pinned', 400)).toBe('loaded');
+            manager.touch([makeConfig('roboto')]);
            await vi.advanceTimersByTimeAsync(50);
-        manager.pin('pinned', 400);
+            manager.destroy();
-        // Advance past TTL + purge interval
+            expect(manager.statuses.size).toBe(0);
-        await vi.advanceTimersByTimeAsync(6 * 60 * 1000);
+        });
-        expect(manager.getFontStatus('pinned', 400)).toBe('loaded');
+        it('removes all loaded fonts from document.fonts', async () => {
-        expect(mockFontFaceSet.delete).not.toHaveBeenCalled();
+            manager.touch([makeConfig('roboto'), makeConfig('inter')]);
-    });
+            await vi.advanceTimersByTimeAsync(50);
-    it('should evict a font after it is unpinned and TTL expires', async () => {
+            manager.destroy();
        const config = { id: 'unpinned', name: 'Unpinned', url: 'https://example.com/unpinned.ttf', weight: 400 };
-        manager.touch([config]);
+            expect(mockFontFaceSet.delete).toHaveBeenCalledTimes(2);
-        await vi.advanceTimersByTimeAsync(50);
+        });
        expect(manager.getFontStatus('unpinned', 400)).toBe('loaded');
-        manager.pin('unpinned', 400);
+        it('prevents further loading after destroy', async () => {
-        manager.unpin('unpinned', 400);
+            manager.destroy();
            manager.touch([makeConfig('roboto')]);
            await vi.advanceTimersByTimeAsync(50);
-        // Advance past TTL + purge interval
+            expect(manager.statuses.size).toBe(0);
-        await vi.advanceTimersByTimeAsync(6 * 60 * 1000);
+        });
        expect(manager.getFontStatus('unpinned', 400)).toBeUndefined();
        expect(mockFontFaceSet.delete).toHaveBeenCalled();
    });
    it('should clear pinned set on destroy without errors', async () => {
        const config = {
            id: 'destroy-pin',
            name: 'DestroyPin',
            url: 'https://example.com/destroypin.ttf',
            weight: 400,
        };
        manager.touch([config]);
        await vi.advanceTimersByTimeAsync(50);
        manager.pin('destroy-pin', 400);
        manager.destroy();
        expect(manager.statuses.size).toBe(0);
    });
 });
--- a/src/entities/Font/model/store/appliedFontsStore/appliedFontsStore.svelte.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/appliedFontsStore.svelte.ts
@@ -1,34 +1,26 @@
 import { SvelteMap } from 'svelte/reactivity';
 import {
    type FontLoadRequestConfig,
    type FontLoadStatus,
 } from '../../types';
 import {
    FontFetchError,
    FontParseError,
 } from './errors';
 import {
    generateFontKey,
    getEffectiveConcurrency,
    loadFont,
    yieldToMainThread,
 } from './utils';
 import { FontBufferCache } from './utils/fontBufferCache/FontBufferCache';
 import { FontEvictionPolicy } from './utils/fontEvictionPolicy/FontEvictionPolicy';
 import { FontLoadQueue } from './utils/fontLoadQueue/FontLoadQueue';
-/** Loading state of a font. Failed loads may be retried up to MAX_RETRIES. */
+interface AppliedFontsManagerDeps {
-export type FontStatus = 'loading' | 'loaded' | 'error';
+    cache?: FontBufferCache;
-
+    eviction?: FontEvictionPolicy;
-/** Configuration for a font load request. */
+    queue?: FontLoadQueue;
 export interface FontConfigRequest {
    /**
     * Unique identifier for the font (e.g., "lato", "roboto").
     */
    id: string;
    /**
     * Actual font family name recognized by the browser (e.g., "Lato", "Roboto").
     */
    name: string;
    /**
     * URL pointing to the font file (typically .ttf or .woff2).
     */
    url: string;
    /**
     * Numeric weight (100-900). Variable fonts load once per ID regardless of weight.
     */
    weight: number;
    /**
     * Variable fonts load once per ID; static fonts load per weight.
     */
    isVariable?: boolean;
 }
 /**
@@ -55,14 +47,16 @@ export interface FontConfigRequest {
 * **Browser APIs Used:** `scheduler.yield()`, `isInputPending()`, `requestIdleCallback`, Cache API, Network Information API
 */
 export class AppliedFontsManager {
    // Injected collaborators - each handles one concern for better testability
    readonly #cache: FontBufferCache;
    readonly #eviction: FontEvictionPolicy;
    readonly #queue: FontLoadQueue;
    // Loaded FontFace instances registered with document.fonts. Key: `{id}@{weight}` or `{id}@vf`
    #loadedFonts = new Map<string, FontFace>();
-    // Last-used timestamps for LRU cleanup. Key: `{id}@{weight}` or `{id}@vf`, Value: unix timestamp (ms)
+    // Maps font key → URL so #purgeUnused() can evict from cache
-    #usageTracker = new Map<string, number>();
+    #urlByKey = new Map<string, string>();
    // Fonts queued for loading by `touch()`, processed by `#processQueue()`
    #queue = new Map<string, FontConfigRequest>();
    // Handle for scheduled queue processing (requestIdleCallback or setTimeout)
    #timeoutId: ReturnType<typeof setTimeout> | null = null;
@@ -76,82 +70,95 @@ export class AppliedFontsManager {
    // Tracks which callback type is pending ('idle' | 'timeout' | null) for proper cancellation
    #pendingType: 'idle' | 'timeout' | null = null;
-    // Retry counts for failed loads; fonts exceeding MAX_RETRIES are permanently skipped
+    readonly #PURGE_INTERVAL = 60000;
    #retryCounts = new Map<string, number>();
    // In-memory buffer cache keyed by URL — fastest tier, checked before Cache API and network
    #buffersByUrl = new Map<string, ArrayBuffer>();
    // Maps font key → URL so #purgeUnused() can evict from #buffersByUrl
    #urlByKey = new Map<string, string>();
    // Fonts currently visible/in-use; purge skips these regardless of TTL
    #pinnedFonts = new Set<string>();
    readonly #MAX_RETRIES = 3;
    readonly #PURGE_INTERVAL = 60000; // 60 seconds
    readonly #TTL = 5 * 60 * 1000; // 5 minutes
    readonly #CACHE_NAME = 'font-cache-v1'; // Versioned for future invalidation
    // Reactive status map for Svelte components to track font states
-    statuses = new SvelteMap<string, FontStatus>();
+    statuses = new SvelteMap<string, FontLoadStatus>();
    // Starts periodic cleanup timer (browser-only).
-    constructor() {
+    constructor(
        { cache = new FontBufferCache(), eviction = new FontEvictionPolicy(), queue = new FontLoadQueue() }:
            AppliedFontsManagerDeps = {},
    ) {
        // Inject collaborators - defaults provided for production, fakes for testing
        this.#cache = cache;
        this.#eviction = eviction;
        this.#queue = queue;
        if (typeof window !== 'undefined') {
            this.#intervalId = setInterval(() => this.#purgeUnused(), this.#PURGE_INTERVAL);
        }
    }
    // Generates font key: `{id}@vf` for variable, `{id}@{weight}` for static.
    #getFontKey(id: string, weight: number, isVariable: boolean): string {
        return isVariable ? `${id.toLowerCase()}@vf` : `${id.toLowerCase()}@${weight}`;
    }
    /**
     * Requests fonts to be loaded. Updates usage tracking and queues new fonts.
     *
     * Retry behavior: 'loaded' and 'loading' fonts are skipped; 'error' fonts retry if count < MAX_RETRIES.
     * Scheduling: Prefers requestIdleCallback (150ms timeout), falls back to setTimeout(16ms).
     */
-    touch(configs: FontConfigRequest[]) {
+    touch(configs: FontLoadRequestConfig[]) {
-        if (this.#abortController.signal.aborted) return;
+        if (this.#abortController.signal.aborted) {
-
+            return;
        const now = Date.now();
        let hasNewItems = false;
        for (const config of configs) {
            const key = this.#getFontKey(config.id, config.weight, !!config.isVariable);
            this.#usageTracker.set(key, now);
            const status = this.statuses.get(key);
            if (status === 'loaded' || status === 'loading' || this.#queue.has(key)) continue;
            if (status === 'error' && (this.#retryCounts.get(key) ?? 0) >= this.#MAX_RETRIES) continue;
            this.#queue.set(key, config);
            hasNewItems = true;
        }
        try {
            const now = Date.now();
            let hasNewItems = false;
-        if (hasNewItems && !this.#timeoutId) {
+            for (const config of configs) {
-            if (typeof requestIdleCallback !== 'undefined') {
+                const key = generateFontKey(config);
-                this.#timeoutId = requestIdleCallback(
+
-                    () => this.#processQueue(),
+                // Update last-used timestamp for LRU eviction policy
-                    { timeout: 150 },
+                this.#eviction.touch(key, now);
-                ) as unknown as ReturnType<typeof setTimeout>;
+
-                this.#pendingType = 'idle';
+                const status = this.statuses.get(key);
-            } else {
+
-                this.#timeoutId = setTimeout(() => this.#processQueue(), 16);
+                // Skip fonts that are already loaded or currently loading
-                this.#pendingType = 'timeout';
+                if (status === 'loaded' || status === 'loading') {
                    continue;
                }
                // Skip fonts already in the queue (avoid duplicates)
                if (this.#queue.has(key)) {
                    continue;
                }
                // Skip error fonts that have exceeded max retry count
                if (status === 'error' && this.#queue.isMaxRetriesReached(key)) {
                    continue;
                }
                // Queue this font for loading
                this.#queue.enqueue(key, config);
                hasNewItems = true;
            }
            if (hasNewItems && !this.#timeoutId) {
                this.#scheduleProcessing();
            }
        } catch (error) {
            console.error(error);
        }
    }
-    /** Returns optimal concurrent fetches based on Network Information API: 1 for 2G, 2 for 3G, 4 for 4G/default. */
+    /**
     * Schedules `#processQueue()` via `requestIdleCallback` (150ms timeout) when available,
     * falling back to `setTimeout(16ms)` for ~60fps timing.
     */
    #scheduleProcessing(): void {
        if (typeof requestIdleCallback !== 'undefined') {
            this.#timeoutId = requestIdleCallback(
                () => this.#processQueue(),
                { timeout: 150 },
            ) as unknown as ReturnType<typeof setTimeout>;
            this.#pendingType = 'idle';
        } else {
            this.#timeoutId = setTimeout(() => this.#processQueue(), 16);
            this.#pendingType = 'timeout';
        }
    }
    /** Returns true if data-saver mode is enabled (defers non-critical weights). */
    #shouldDeferNonCritical(): boolean {
-        const nav = navigator as any;
+        return (navigator as any).connection?.saveData === true;
        return nav.connection?.saveData === true;
    }
    /**
@@ -162,76 +169,52 @@ export class AppliedFontsManager {
     * Yielding: Chromium uses `isInputPending()` for optimal responsiveness; others yield every 8ms.
     */
    async #processQueue() {
        // Clear timer flags since we're now processing
        this.#timeoutId = null;
        this.#pendingType = null;
-        let entries = Array.from(this.#queue.entries());
+        // Get all queued entries and clear the queue atomically
-        if (!entries.length) return;
+        let entries = this.#queue.flush();
-        this.#queue.clear();
+        if (!entries.length) {
            return;
        }
        // In data-saver mode, only load variable fonts and common weights (400, 700)
        if (this.#shouldDeferNonCritical()) {
            entries = entries.filter(([, c]) => c.isVariable || [400, 700].includes(c.weight));
        }
-        // Phase 1: Concurrent fetching (I/O bound, non-blocking)
+        // Determine optimal concurrent fetches based on network speed (1-4)
        const concurrency = getEffectiveConcurrency();
        const buffers = new Map<string, ArrayBuffer>();
        // ==================== PHASE 1: Concurrent Fetching ====================
        // Fetch multiple font files in parallel since network I/O is non-blocking
        for (let i = 0; i < entries.length; i += concurrency) {
-            const chunk = entries.slice(i, i + concurrency);
+            await this.#fetchChunk(entries.slice(i, i + concurrency), buffers);
            const results = await Promise.allSettled(
                chunk.map(async ([key, config]) => {
                    this.statuses.set(key, 'loading');
                    const buffer = await this.#fetchFontBuffer(
                        config.url,
                        this.#abortController.signal,
                    );
                    buffers.set(key, buffer);
                }),
            );
            for (let j = 0; j < results.length; j++) {
                if (results[j].status === 'rejected') {
                    const [key, config] = chunk[j];
                    console.error(`Font fetch failed: ${config.name}`, (results[j] as PromiseRejectedResult).reason);
                    this.statuses.set(key, 'error');
                    this.#retryCounts.set(key, (this.#retryCounts.get(key) ?? 0) + 1);
                }
            }
        }
-        // Phase 2: Sequential parsing (CPU-intensive, yields periodically)
+        // ==================== PHASE 2: Sequential Parsing ====================
        // Parse buffers one at a time with periodic yields to avoid blocking UI
        const hasInputPending = !!(navigator as any).scheduling?.isInputPending;
        let lastYield = performance.now();
-        const YIELD_INTERVAL = 8; // ms
+        const YIELD_INTERVAL = 8;
        for (const [key, config] of entries) {
            const buffer = buffers.get(key);
-            if (!buffer) continue;
+            // Skip fonts that failed to fetch in phase 1
-
+            if (!buffer) {
-            try {
+                continue;
                const weightRange = config.isVariable ? '100 900' : `${config.weight}`;
                const font = new FontFace(config.name, buffer, {
                    weight: weightRange,
                    style: 'normal',
                    display: 'swap',
                });
                await font.load();
                document.fonts.add(font);
                this.#loadedFonts.set(key, font);
                this.#buffersByUrl.set(config.url, buffer);
                this.#urlByKey.set(key, config.url);
                this.statuses.set(key, 'loaded');
            } catch (e) {
                if (e instanceof Error && e.name === 'AbortError') continue;
                console.error(`Font parse failed: ${config.name}`, e);
                this.statuses.set(key, 'error');
                this.#retryCounts.set(key, (this.#retryCounts.get(key) ?? 0) + 1);
            }
            await this.#processFont(key, config, buffer);
            // Yield to main thread if needed (prevents UI blocking)
            // Chromium: use isInputPending() for optimal responsiveness
            // Others: yield every 8ms as fallback
            const shouldYield = hasInputPending
                ? (navigator as any).scheduling.isInputPending({ includeContinuous: true })
-                : (performance.now() - lastYield > YIELD_INTERVAL);
+                : performance.now() - lastYield > YIELD_INTERVAL;
            if (shouldYield) {
                await yieldToMainThread();
@@ -241,94 +224,124 @@ export class AppliedFontsManager {
    }
    /**
-     * Fetches font with three-tier lookup: in-memory buffer → Cache API → network.
+     * Fetches a chunk of fonts concurrently and populates `buffers` with successful results.
-     * Cache failures (private browsing, quota limits) are silently ignored.
+     * Each promise carries its own key and config so results need no index correlation.
     * Aborted fetches are silently skipped; other errors set status to `'error'` and increment retry.
     */
-    async #fetchFontBuffer(url: string, signal?: AbortSignal): Promise<ArrayBuffer> {
+    async #fetchChunk(
-        // Tier 1: in-memory buffer (fastest, no I/O)
+        chunk: Array<[string, FontLoadRequestConfig]>,
-        const inMemory = this.#buffersByUrl.get(url);
+        buffers: Map<string, ArrayBuffer>,
-        if (inMemory) return inMemory;
+    ): Promise<void> {
        const results = await Promise.all(
            chunk.map(async ([key, config]) => {
                this.statuses.set(key, 'loading');
                try {
                    const buffer = await this.#cache.get(config.url, this.#abortController.signal);
                    buffers.set(key, buffer);
                    return { ok: true as const, key };
                } catch (reason) {
                    return { ok: false as const, key, config, reason };
                }
            }),
        );
-        // Tier 2: Cache API
+        for (const result of results) {
-        try {
+            if (result.ok) continue;
-            if (typeof caches !== 'undefined') {
+            const { key, config, reason } = result;
-                const cache = await caches.open(this.#CACHE_NAME);
+            const isAbort = reason instanceof FontFetchError
-                const cached = await cache.match(url);
+                && reason.cause instanceof Error
-                if (cached) return cached.arrayBuffer();
+                && reason.cause.name === 'AbortError';
            if (isAbort) continue;
            if (reason instanceof FontFetchError) {
                console.error(`Font fetch failed: ${config.name}`, reason);
            }
-        } catch {
+            this.statuses.set(key, 'error');
-            // Cache unavailable (private browsing, security restrictions) — fall through to network
+            this.#queue.incrementRetry(key);
        }
    }
-        // Tier 3: network
+    /**
-        const response = await fetch(url, { signal });
+     * Parses a fetched buffer into a {@link FontFace}, registers it with `document.fonts`,
-        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+     * and updates reactive status. On failure, sets status to `'error'` and increments the retry count.
-
+     */
    async #processFont(key: string, config: FontLoadRequestConfig, buffer: ArrayBuffer): Promise<void> {
        try {
-            if (typeof caches !== 'undefined') {
+            const font = await loadFont(config, buffer);
-                const cache = await caches.open(this.#CACHE_NAME);
+            this.#loadedFonts.set(key, font);
-                await cache.put(url, response.clone());
+            this.#urlByKey.set(key, config.url);
            this.statuses.set(key, 'loaded');
        } catch (e) {
            if (e instanceof FontParseError) {
                console.error(`Font parse failed: ${config.name}`, e);
                this.statuses.set(key, 'error');
                this.#queue.incrementRetry(key);
            }
        } catch {
            // Cache write failed (quota, storage pressure) — return font anyway
        }
        return response.arrayBuffer();
    }
    /** Removes fonts unused within TTL (LRU-style cleanup). Runs every PURGE_INTERVAL. Pinned fonts are never evicted. */
    #purgeUnused() {
        const now = Date.now();
-        for (const [key, lastUsed] of this.#usageTracker) {
+        // Iterate through all tracked font keys
-            if (now - lastUsed < this.#TTL) continue;
+        for (const key of this.#eviction.keys()) {
-            if (this.#pinnedFonts.has(key)) continue;
+            // Skip fonts that are still within TTL or are pinned
            if (!this.#eviction.shouldEvict(key, now)) {
                continue;
            }
            // Remove FontFace from document to free memory
            const font = this.#loadedFonts.get(key);
            if (font) document.fonts.delete(font);
            // Evict from cache and cleanup URL mapping
            const url = this.#urlByKey.get(key);
            if (url) {
-                this.#buffersByUrl.delete(url);
+                this.#cache.evict(url);
                this.#urlByKey.delete(key);
            }
            // Clean up remaining state
            this.#loadedFonts.delete(key);
            this.#usageTracker.delete(key);
            this.statuses.delete(key);
-            this.#retryCounts.delete(key);
+            this.#eviction.remove(key);
        }
    }
    /** Returns current loading status for a font, or undefined if never requested. */
    getFontStatus(id: string, weight: number, isVariable = false) {
-        return this.statuses.get(this.#getFontKey(id, weight, isVariable));
+        try {
            return this.statuses.get(generateFontKey({ id, weight, isVariable }));
        } catch (error) {
            console.error(error);
        }
    }
    /** Pins a font so it is never evicted by #purgeUnused(), regardless of TTL. */
-    pin(id: string, weight: number, isVariable?: boolean): void {
+    pin(id: string, weight: number, isVariable = false): void {
-        this.#pinnedFonts.add(this.#getFontKey(id, weight, !!isVariable));
+        this.#eviction.pin(generateFontKey({ id, weight, isVariable }));
    }
    /** Unpins a font, allowing it to be evicted by #purgeUnused() once its TTL expires. */
-    unpin(id: string, weight: number, isVariable?: boolean): void {
+    unpin(id: string, weight: number, isVariable = false): void {
-        this.#pinnedFonts.delete(this.#getFontKey(id, weight, !!isVariable));
+        this.#eviction.unpin(generateFontKey({ id, weight, isVariable }));
    }
    /** Waits for all fonts to finish loading using document.fonts.ready. */
    async ready(): Promise<void> {
-        if (typeof document === 'undefined') return;
+        if (typeof document === 'undefined') {
            return;
        }
        try {
            await document.fonts.ready;
-        } catch {
+        } catch { /* document unloaded */ }
            // document.fonts.ready can reject in some edge cases
            // (e.g., document unloaded). Silently resolve.
        }
    }
    /** Aborts all operations, removes fonts from document, and clears state. Manager cannot be reused after. */
    destroy() {
        // Abort all in-flight network requests
        this.#abortController.abort();
        // Cancel pending queue processing (idle callback or timeout)
        if (this.#timeoutId !== null) {
            if (this.#pendingType === 'idle' && typeof cancelIdleCallback !== 'undefined') {
                cancelIdleCallback(this.#timeoutId as unknown as number);
@@ -339,25 +352,26 @@ export class AppliedFontsManager {
            this.#pendingType = null;
        }
        // Stop periodic cleanup timer
        if (this.#intervalId) {
            clearInterval(this.#intervalId);
            this.#intervalId = null;
        }
        // Remove all loaded fonts from document
        if (typeof document !== 'undefined') {
            for (const font of this.#loadedFonts.values()) {
                document.fonts.delete(font);
            }
        }
        // Clear all state and collaborators
        this.#loadedFonts.clear();
        this.#usageTracker.clear();
        this.#retryCounts.clear();
        this.#buffersByUrl.clear();
        this.#urlByKey.clear();
-        this.#pinnedFonts.clear();
+        this.#cache.clear();
-        this.statuses.clear();
+        this.#eviction.clear();
        this.#queue.clear();
        this.statuses.clear();
    }
 }
--- a/src/entities/Font/model/store/appliedFontsStore/errors.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/errors.ts
@@ -0,0 +1,35 @@
 /**
 * Thrown by {@link FontBufferCache} when a font file cannot be retrieved from the network or cache.
 *
 * @property url - The URL that was requested.
 * @property cause - The underlying error, if any.
 * @property status - HTTP status code. Present on HTTP errors, absent on network failures.
 */
 export class FontFetchError extends Error {
    readonly name = 'FontFetchError';
    constructor(
        public readonly url: string,
        public readonly cause?: unknown,
        public readonly status?: number,
    ) {
        super(status ? `HTTP ${status} fetching font: ${url}` : `Network error fetching font: ${url}`);
    }
 }
 /**
 * Thrown by {@link loadFont} when a font buffer cannot be parsed into a {@link FontFace}.
 *
 * @property fontName - The display name of the font that failed to parse.
 * @property cause - The underlying error from the FontFace API.
 */
 export class FontParseError extends Error {
    readonly name = 'FontParseError';
    constructor(
        public readonly fontName: string,
        public readonly cause?: unknown,
    ) {
        super(`Failed to parse font: ${fontName}`);
    }
 }
--- a/src/entities/Font/model/store/appliedFontsStore/utils/fontBufferCache/FontBufferCache.test.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/fontBufferCache/FontBufferCache.test.ts
@@ -0,0 +1,66 @@
 /** @vitest-environment jsdom */
 import { FontFetchError } from '../../errors';
 import { FontBufferCache } from './FontBufferCache';
 const makeBuffer = () => new ArrayBuffer(8);
 const makeFetcher = (overrides: Partial<Response> = {}) =>
    vi.fn().mockResolvedValue({
        ok: true,
        status: 200,
        arrayBuffer: () => Promise.resolve(makeBuffer()),
        clone: () => ({ ok: true, status: 200, arrayBuffer: () => Promise.resolve(makeBuffer()) }),
        ...overrides,
    } as Response);
 describe('FontBufferCache', () => {
    let cache: FontBufferCache;
    let fetcher: ReturnType<typeof makeFetcher>;
    beforeEach(() => {
        fetcher = makeFetcher();
        cache = new FontBufferCache({ fetcher });
    });
    it('returns buffer from memory on second call without fetching', async () => {
        await cache.get('https://example.com/font.woff2');
        await cache.get('https://example.com/font.woff2');
        expect(fetcher).toHaveBeenCalledOnce();
    });
    it('throws FontFetchError on HTTP error with correct status', async () => {
        const errorFetcher = makeFetcher({ ok: false, status: 404 });
        const errorCache = new FontBufferCache({ fetcher: errorFetcher });
        const err = await errorCache.get('https://example.com/font.woff2').catch(e => e);
        expect(err).toBeInstanceOf(FontFetchError);
        expect(err.status).toBe(404);
    });
    it('throws FontFetchError on network failure without status', async () => {
        const networkFetcher = vi.fn().mockRejectedValue(new Error('network down'));
        const networkCache = new FontBufferCache({ fetcher: networkFetcher });
        const err = await networkCache.get('https://example.com/font.woff2').catch(e => e);
        expect(err).toBeInstanceOf(FontFetchError);
        expect(err.status).toBeUndefined();
    });
    it('evict removes url from memory so next call fetches again', async () => {
        await cache.get('https://example.com/font.woff2');
        cache.evict('https://example.com/font.woff2');
        await cache.get('https://example.com/font.woff2');
        expect(fetcher).toHaveBeenCalledTimes(2);
    });
    it('clear wipes all memory cache entries', async () => {
        await cache.get('https://example.com/a.woff2');
        await cache.get('https://example.com/b.woff2');
        cache.clear();
        await cache.get('https://example.com/a.woff2');
        expect(fetcher).toHaveBeenCalledTimes(3);
    });
 });
--- a/src/entities/Font/model/store/appliedFontsStore/utils/fontBufferCache/FontBufferCache.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/fontBufferCache/FontBufferCache.ts
@@ -0,0 +1,97 @@
 import { FontFetchError } from '../../errors';
 type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
 interface FontBufferCacheOptions {
    /** Custom fetch implementation. Defaults to `globalThis.fetch`. Inject in tests for isolation. */
    fetcher?: Fetcher;
    /** Cache API cache name. Defaults to `'font-cache-v1'`. */
    cacheName?: string;
 }
 /**
 * Three-tier font buffer cache: in-memory → Cache API → network.
 *
 * - **Tier 1 (memory):** Fastest — no I/O. Populated after first successful fetch.
 * - **Tier 2 (Cache API):** Persists across page loads. Silently skipped in private browsing.
 * - **Tier 3 (network):** Raw fetch. Throws {@link FontFetchError} on failure.
 *
 * The `fetcher` option is injectable for testing — pass a `vi.fn()` to avoid real network calls.
 */
 export class FontBufferCache {
    #buffersByUrl = new Map<string, ArrayBuffer>();
    readonly #fetcher: Fetcher;
    readonly #cacheName: string;
    constructor(
        { fetcher = globalThis.fetch.bind(globalThis), cacheName = 'font-cache-v1' }: FontBufferCacheOptions = {},
    ) {
        this.#fetcher = fetcher;
        this.#cacheName = cacheName;
    }
    /**
     * Retrieves the font buffer for the given URL using the three-tier strategy.
     * Stores the result in memory on success.
     *
     * @throws {@link FontFetchError} if the network request fails or returns a non-OK response.
     */
    async get(url: string, signal?: AbortSignal): Promise<ArrayBuffer> {
        // Tier 1: in-memory (fastest, no I/O)
        const inMemory = this.#buffersByUrl.get(url);
        if (inMemory) {
            return inMemory;
        }
        // Tier 2: Cache API
        try {
            if (typeof caches !== 'undefined') {
                const cache = await caches.open(this.#cacheName);
                const cached = await cache.match(url);
                if (cached) {
                    const buffer = await cached.arrayBuffer();
                    this.#buffersByUrl.set(url, buffer);
                    return buffer;
                }
            }
        } catch {
            // Cache unavailable (private browsing, security restrictions) — fall through to network
        }
        // Tier 3: network
        let response: Response;
        try {
            response = await this.#fetcher(url, { signal });
        } catch (cause) {
            throw new FontFetchError(url, cause);
        }
        if (!response.ok) {
            throw new FontFetchError(url, undefined, response.status);
        }
        try {
            if (typeof caches !== 'undefined') {
                const cache = await caches.open(this.#cacheName);
                await cache.put(url, response.clone());
            }
        } catch {
            // Cache write failed (quota, storage pressure) — return font anyway
        }
        const buffer = await response.arrayBuffer();
        this.#buffersByUrl.set(url, buffer);
        return buffer;
    }
    /** Removes a URL from the in-memory cache. Next call to `get()` will re-fetch. */
    evict(url: string): void {
        this.#buffersByUrl.delete(url);
    }
    /** Clears all in-memory cached buffers. */
    clear(): void {
        this.#buffersByUrl.clear();
    }
 }
--- a/src/entities/Font/model/store/appliedFontsStore/utils/fontEvictionPolicy/FontEvictionPolicy.test.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/fontEvictionPolicy/FontEvictionPolicy.test.ts
@@ -0,0 +1,69 @@
 import { FontEvictionPolicy } from './FontEvictionPolicy';
 describe('FontEvictionPolicy', () => {
    let policy: FontEvictionPolicy;
    const TTL = 1000;
    const t0 = 100000;
    beforeEach(() => {
        policy = new FontEvictionPolicy({ ttl: TTL });
    });
    it('shouldEvict returns false within TTL', () => {
        policy.touch('a@400', t0);
        expect(policy.shouldEvict('a@400', t0 + TTL - 1)).toBe(false);
    });
    it('shouldEvict returns true at TTL boundary', () => {
        policy.touch('a@400', t0);
        expect(policy.shouldEvict('a@400', t0 + TTL)).toBe(true);
    });
    it('shouldEvict returns false for pinned key regardless of TTL', () => {
        policy.touch('a@400', t0);
        policy.pin('a@400');
        expect(policy.shouldEvict('a@400', t0 + TTL * 10)).toBe(false);
    });
    it('shouldEvict returns true again after unpin past TTL', () => {
        policy.touch('a@400', t0);
        policy.pin('a@400');
        policy.unpin('a@400');
        expect(policy.shouldEvict('a@400', t0 + TTL)).toBe(true);
    });
    it('shouldEvict returns false for untracked key', () => {
        expect(policy.shouldEvict('never@touched', t0 + TTL * 100)).toBe(false);
    });
    it('keys returns all tracked keys', () => {
        policy.touch('a@400', t0);
        policy.touch('b@vf', t0);
        expect(Array.from(policy.keys())).toEqual(expect.arrayContaining(['a@400', 'b@vf']));
    });
    it('remove deletes key from tracking so it no longer appears in keys()', () => {
        policy.touch('a@400', t0);
        policy.touch('b@vf', t0);
        policy.remove('a@400');
        expect(Array.from(policy.keys())).not.toContain('a@400');
        expect(Array.from(policy.keys())).toContain('b@vf');
    });
    it('remove unpins the key so a subsequent touch + TTL would evict it', () => {
        policy.touch('a@400', t0);
        policy.pin('a@400');
        policy.remove('a@400');
        // re-touch and check it can be evicted again
        policy.touch('a@400', t0);
        expect(policy.shouldEvict('a@400', t0 + TTL)).toBe(true);
    });
    it('clear resets all state', () => {
        policy.touch('a@400', t0);
        policy.pin('a@400');
        policy.clear();
        expect(Array.from(policy.keys())).toHaveLength(0);
        expect(policy.shouldEvict('a@400', t0 + TTL * 10)).toBe(false);
    });
 });
--- a/src/entities/Font/model/store/appliedFontsStore/utils/fontEvictionPolicy/FontEvictionPolicy.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/fontEvictionPolicy/FontEvictionPolicy.ts
@@ -0,0 +1,76 @@
 interface FontEvictionPolicyOptions {
    /** TTL in milliseconds. Defaults to 5 minutes. */
    ttl?: number;
 }
 /**
 * Tracks font usage timestamps and pinned keys to determine when a font should be evicted.
 *
 * Pure data — no browser APIs. Accepts explicit `now` timestamps so tests
 * never need fake timers.
 */
 export class FontEvictionPolicy {
    #usageTracker = new Map<string, number>();
    #pinnedFonts = new Set<string>();
    readonly #TTL: number;
    constructor({ ttl = 5 * 60 * 1000 }: FontEvictionPolicyOptions = {}) {
        this.#TTL = ttl;
    }
    /**
     * Records the last-used time for a font key.
     * @param key - Font key in `{id}@{weight}` or `{id}@vf` format.
     * @param now - Current timestamp in ms. Defaults to `Date.now()`.
     */
    touch(key: string, now: number = Date.now()): void {
        this.#usageTracker.set(key, now);
    }
    /** Pins a font key so it is never evicted regardless of TTL. */
    pin(key: string): void {
        this.#pinnedFonts.add(key);
    }
    /** Unpins a font key, allowing it to be evicted once its TTL expires. */
    unpin(key: string): void {
        this.#pinnedFonts.delete(key);
    }
    /**
     * Returns `true` if the font should be evicted.
     * A font is evicted when its TTL has elapsed and it is not pinned.
     * Returns `false` for untracked keys.
     *
     * @param key - Font key to check.
     * @param now - Current timestamp in ms (pass explicitly for deterministic tests).
     */
    shouldEvict(key: string, now: number): boolean {
        const lastUsed = this.#usageTracker.get(key);
        if (lastUsed === undefined) {
            return false;
        }
        if (this.#pinnedFonts.has(key)) {
            return false;
        }
        return now - lastUsed >= this.#TTL;
    }
    /** Returns an iterator over all tracked font keys. */
    keys(): IterableIterator<string> {
        return this.#usageTracker.keys();
    }
    /** Removes a font key from tracking. Called by the orchestrator after eviction. */
    remove(key: string): void {
        this.#usageTracker.delete(key);
        this.#pinnedFonts.delete(key);
    }
    /** Clears all usage timestamps and pinned keys. */
    clear(): void {
        this.#usageTracker.clear();
        this.#pinnedFonts.clear();
    }
 }
--- a/src/entities/Font/model/store/appliedFontsStore/utils/fontLoadQueue/FontLoadQueue.test.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/fontLoadQueue/FontLoadQueue.test.ts
@@ -0,0 +1,65 @@
 import type { FontLoadRequestConfig } from '../../../../types';
 import { FontLoadQueue } from './FontLoadQueue';
 const config = (id: string): FontLoadRequestConfig => ({
    id,
    name: id,
    url: `https://example.com/${id}.woff2`,
    weight: 400,
 });
 describe('FontLoadQueue', () => {
    let queue: FontLoadQueue;
    beforeEach(() => {
        queue = new FontLoadQueue();
    });
    it('enqueue returns true for a new key', () => {
        expect(queue.enqueue('a@400', config('a'))).toBe(true);
    });
    it('enqueue returns false for an already-queued key', () => {
        queue.enqueue('a@400', config('a'));
        expect(queue.enqueue('a@400', config('a'))).toBe(false);
    });
    it('has returns true after enqueue, false after flush', () => {
        queue.enqueue('a@400', config('a'));
        expect(queue.has('a@400')).toBe(true);
        queue.flush();
        expect(queue.has('a@400')).toBe(false);
    });
    it('flush returns all entries and atomically clears the queue', () => {
        queue.enqueue('a@400', config('a'));
        queue.enqueue('b@700', config('b'));
        const entries = queue.flush();
        expect(entries).toHaveLength(2);
        expect(queue.has('a@400')).toBe(false);
        expect(queue.has('b@700')).toBe(false);
    });
    it('isMaxRetriesReached returns false below MAX_RETRIES', () => {
        queue.incrementRetry('a@400');
        queue.incrementRetry('a@400');
        expect(queue.isMaxRetriesReached('a@400')).toBe(false);
    });
    it('isMaxRetriesReached returns true at MAX_RETRIES (3)', () => {
        queue.incrementRetry('a@400');
        queue.incrementRetry('a@400');
        queue.incrementRetry('a@400');
        expect(queue.isMaxRetriesReached('a@400')).toBe(true);
    });
    it('clear resets queue and retry counts', () => {
        queue.enqueue('a@400', config('a'));
        queue.incrementRetry('a@400');
        queue.incrementRetry('a@400');
        queue.incrementRetry('a@400');
        queue.clear();
        expect(queue.has('a@400')).toBe(false);
        expect(queue.isMaxRetriesReached('a@400')).toBe(false);
    });
 });
--- a/src/entities/Font/model/store/appliedFontsStore/utils/fontLoadQueue/FontLoadQueue.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/fontLoadQueue/FontLoadQueue.ts
@@ -0,0 +1,57 @@
 import type { FontLoadRequestConfig } from '../../../../types';
 /**
 * Manages the font load queue and per-font retry counts.
 *
 * Scheduling (when to drain the queue) is handled by the orchestrator —
 * this class is purely concerned with what is queued and whether retries are exhausted.
 */
 export class FontLoadQueue {
    #queue = new Map<string, FontLoadRequestConfig>();
    #retryCounts = new Map<string, number>();
    readonly #MAX_RETRIES = 3;
    /**
     * Adds a font to the queue.
     * @returns `true` if the key was newly enqueued, `false` if it was already present.
     */
    enqueue(key: string, config: FontLoadRequestConfig): boolean {
        if (this.#queue.has(key)) {
            return false;
        }
        this.#queue.set(key, config);
        return true;
    }
    /**
     * Atomically snapshots and clears the queue.
     * @returns All queued entries at the time of the call.
     */
    flush(): Array<[string, FontLoadRequestConfig]> {
        const entries = Array.from(this.#queue.entries());
        this.#queue.clear();
        return entries;
    }
    /** Returns `true` if the key is currently in the queue. */
    has(key: string): boolean {
        return this.#queue.has(key);
    }
    /** Increments the retry count for a font key. */
    incrementRetry(key: string): void {
        this.#retryCounts.set(key, (this.#retryCounts.get(key) ?? 0) + 1);
    }
    /** Returns `true` if the font has reached or exceeded the maximum retry limit. */
    isMaxRetriesReached(key: string): boolean {
        return (this.#retryCounts.get(key) ?? 0) >= this.#MAX_RETRIES;
    }
    /** Clears all queued fonts and resets all retry counts. */
    clear(): void {
        this.#queue.clear();
        this.#retryCounts.clear();
    }
 }
--- a/src/entities/Font/model/store/appliedFontsStore/utils/generateFontKey/generateFontKey.test.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/generateFontKey/generateFontKey.test.ts
@@ -0,0 +1,25 @@
 import { generateFontKey } from './generateFontKey';
 describe('generateFontKey', () => {
    it('should throw an error if font id is not provided', () => {
        const config = { weight: 400, isVariable: false };
        // @ts-expect-error
        expect(() => generateFontKey(config)).toThrow('Font id is required');
    });
    it('should generate a font key for a variable font', () => {
        const config = { id: 'Roboto', weight: 400, isVariable: true };
        expect(generateFontKey(config)).toBe('roboto@vf');
    });
    it('should throw an error if font weight is not provided and is not a variable font', () => {
        const config = { id: 'Roboto', isVariable: false };
        // @ts-expect-error
        expect(() => generateFontKey(config)).toThrow('Font weight is required');
    });
    it('should generate a font key for a non-variable font', () => {
        const config = { id: 'Roboto', weight: 400, isVariable: false };
        expect(generateFontKey(config)).toBe('roboto@400');
    });
 });
--- a/src/entities/Font/model/store/appliedFontsStore/utils/generateFontKey/generateFontKey.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/generateFontKey/generateFontKey.ts
@@ -0,0 +1,22 @@
 import type { FontLoadRequestConfig } from '../../../../types';
 export type PartialConfig = Pick<FontLoadRequestConfig, 'id' | 'weight' | 'isVariable'>;
 /**
 * Generates a font key for a given font load request configuration.
 * @param config - The font load request configuration.
 * @returns The generated font key.
 */
 export function generateFontKey(config: PartialConfig): string {
    if (!config.id) {
        throw new Error('Font id is required');
    }
    if (config.isVariable) {
        return `${config.id.toLowerCase()}@vf`;
    }
    if (!config.weight) {
        throw new Error('Font weight is required');
    }
    return `${config.id.toLowerCase()}@${config.weight}`;
 }
--- a/src/entities/Font/model/store/appliedFontsStore/utils/index.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/index.ts
@@ -1,2 +1,4 @@
 export { generateFontKey } from './generateFontKey/generateFontKey';
 export { getEffectiveConcurrency } from './getEffectiveConcurrency/getEffectiveConcurrency';
 export { loadFont } from './loadFont/loadFont';
 export { yieldToMainThread } from './yieldToMainThread/yieldToMainThread';
--- a/src/entities/Font/model/store/appliedFontsStore/utils/loadFont/loadFont.test.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/loadFont/loadFont.test.ts
@@ -0,0 +1,93 @@
 /** @vitest-environment jsdom */
 import { FontParseError } from '../../errors';
 import { loadFont } from './loadFont';
 describe('loadFont', () => {
    let mockFontInstance: any;
    let mockFontFaceSet: { add: ReturnType<typeof vi.fn>; delete: ReturnType<typeof vi.fn> };
    beforeEach(() => {
        mockFontFaceSet = { add: vi.fn(), delete: vi.fn() };
        Object.defineProperty(document, 'fonts', { value: mockFontFaceSet, configurable: true, writable: true });
        const MockFontFace = vi.fn(
            function(this: any, name: string, buffer: BufferSource, options: FontFaceDescriptors) {
                this.name = name;
                this.buffer = buffer;
                this.options = options;
                this.load = vi.fn().mockResolvedValue(this);
                mockFontInstance = this;
            },
        );
        vi.stubGlobal('FontFace', MockFontFace);
    });
    afterEach(() => {
        vi.unstubAllGlobals();
    });
    it('constructs FontFace with exact weight for static fonts', async () => {
        const buffer = new ArrayBuffer(8);
        await loadFont({ name: 'Roboto', weight: 400 }, buffer);
        expect(FontFace).toHaveBeenCalledWith('Roboto', buffer, expect.objectContaining({ weight: '400' }));
    });
    it('constructs FontFace with weight range for variable fonts', async () => {
        const buffer = new ArrayBuffer(8);
        await loadFont({ name: 'Roboto', weight: 400, isVariable: true }, buffer);
        expect(FontFace).toHaveBeenCalledWith('Roboto', buffer, expect.objectContaining({ weight: '100 900' }));
    });
    it('sets style: normal and display: swap on FontFace options', async () => {
        await loadFont({ name: 'Lato', weight: 700 }, new ArrayBuffer(8));
        expect(FontFace).toHaveBeenCalledWith(
            'Lato',
            expect.anything(),
            expect.objectContaining({ style: 'normal', display: 'swap' }),
        );
    });
    it('passes the buffer as the second argument to FontFace', async () => {
        const buffer = new ArrayBuffer(16);
        await loadFont({ name: 'Inter', weight: 400 }, buffer);
        expect(FontFace).toHaveBeenCalledWith('Inter', buffer, expect.anything());
    });
    it('calls font.load() and adds the font to document.fonts', async () => {
        const buffer = new ArrayBuffer(8);
        const result = await loadFont({ name: 'Inter', weight: 400 }, buffer);
        expect(mockFontInstance.load).toHaveBeenCalledOnce();
        expect(mockFontFaceSet.add).toHaveBeenCalledWith(mockFontInstance);
        expect(result).toBe(mockFontInstance);
    });
    it('throws FontParseError when font.load() rejects', async () => {
        const loadError = new Error('parse failed');
        const MockFontFace = vi.fn(
            function(this: any, name: string, buffer: BufferSource, options: FontFaceDescriptors) {
                this.load = vi.fn().mockRejectedValue(loadError);
            },
        );
        vi.stubGlobal('FontFace', MockFontFace);
        await expect(loadFont({ name: 'Broken', weight: 400 }, new ArrayBuffer(8))).rejects.toBeInstanceOf(
            FontParseError,
        );
    });
    it('throws FontParseError when document.fonts.add throws', async () => {
        const addError = new Error('add failed');
        mockFontFaceSet.add.mockImplementation(() => {
            throw addError;
        });
        await expect(loadFont({ name: 'Broken', weight: 400 }, new ArrayBuffer(8))).rejects.toBeInstanceOf(
            FontParseError,
        );
    });
 });
--- a/src/entities/Font/model/store/appliedFontsStore/utils/loadFont/loadFont.ts
+++ b/src/entities/Font/model/store/appliedFontsStore/utils/loadFont/loadFont.ts
@@ -0,0 +1,27 @@
 import type { FontLoadRequestConfig } from '../../../../types';
 import { FontParseError } from '../../errors';
 export type PartialConfig = Pick<FontLoadRequestConfig, 'weight' | 'name' | 'isVariable'>;
 /**
 * Loads a font from a buffer and adds it to the document's font collection.
 * @param config - The font load request configuration.
 * @param buffer - The buffer containing the font data.
 * @returns A promise that resolves to the loaded `FontFace`.
 * @throws {@link FontParseError} When the font buffer cannot be parsed or added to the document font set.
 */
 export async function loadFont(config: PartialConfig, buffer: BufferSource): Promise<FontFace> {
    try {
        const weightRange = config.isVariable ? '100 900' : `${config.weight}`;
        const font = new FontFace(config.name, buffer, {
            weight: weightRange,
            style: 'normal',
            display: 'swap',
        });
        await font.load();
        document.fonts.add(font);
        return font;
    } catch (error) {
        throw new FontParseError(config.name, error);
    }
 }
--- a/src/entities/Font/model/store/baseFontStore.svelte.ts
+++ b/src/entities/Font/model/store/baseFontStore.svelte.ts
@@ -1,210 +0,0 @@
 import { queryClient } from '$shared/api/queryClient';
 import {
    type QueryKey,
    QueryObserver,
    type QueryObserverOptions,
    type QueryObserverResult,
 } from '@tanstack/query-core';
 import type { UnifiedFont } from '../types';
 /**
 * Base class for font stores using TanStack Query
 *
 * Provides reactive font data fetching with caching, automatic refetching,
 * and parameter binding. Extended by UnifiedFontStore for provider-agnostic
 * font fetching.
 *
 * @template TParams - Type of query parameters
 */
 export abstract class BaseFontStore<TParams extends Record<string, any>> {
    /**
     * Cleanup function for effects
     * Call destroy() to remove effects and prevent memory leaks
     */
    cleanup: () => void;
    /** Reactive parameter bindings from external sources */
    #bindings = $state<(() => Partial<TParams>)[]>([]);
    /** Internal parameter state */
    #internalParams = $state<TParams>({} as TParams);
    /**
     * Merged params from internal state and all bindings
     * Automatically updates when bindings or internal params change
     */
    params = $derived.by(() => {
        let merged = { ...this.#internalParams };
        // Merge all binding results into params
        for (const getter of this.#bindings) {
            const bindingResult = getter();
            merged = { ...merged, ...bindingResult };
        }
        return merged as TParams;
    });
    /** TanStack Query result state */
    protected result = $state<QueryObserverResult<UnifiedFont[], Error>>({} as any);
    /** TanStack Query observer instance */
    protected observer: QueryObserver<UnifiedFont[], Error>;
    /** Shared query client */
    protected qc = queryClient;
    /**
     * Creates a new base font store
     * @param initialParams - Initial query parameters
     */
    constructor(initialParams: TParams) {
        this.#internalParams = initialParams;
        this.observer = new QueryObserver(this.qc, this.getOptions());
        // Sync TanStack Query state -> Svelte state
        this.observer.subscribe(r => {
            this.result = r;
        });
        // Sync Svelte state changes -> TanStack Query options
        this.cleanup = $effect.root(() => {
            $effect(() => {
                this.observer.setOptions(this.getOptions());
            });
        });
    }
    /**
     * Must be implemented by child class
     * Returns the query key for TanStack Query caching
     */
    protected abstract getQueryKey(params: TParams): QueryKey;
    /**
     * Must be implemented by child class
     * Fetches font data from API
     */
    protected abstract fetchFn(params: TParams): Promise<UnifiedFont[]>;
    /**
     * Gets TanStack Query options
     * @param params - Query parameters (defaults to current params)
     */
    protected getOptions(params = this.params): QueryObserverOptions<UnifiedFont[], Error> {
        return {
            queryKey: this.getQueryKey(params),
            queryFn: () => this.fetchFn(params),
            staleTime: 5 * 60 * 1000,
            gcTime: 10 * 60 * 1000,
        };
    }
    /** Array of fonts (empty array if loading/error) */
    get fonts() {
        return this.result.data ?? [];
    }
    /** Whether currently fetching initial data */
    get isLoading() {
        return this.result.isLoading;
    }
    /** Whether any fetch is in progress (including refetches) */
    get isFetching() {
        return this.result.isFetching;
    }
    /** Whether last fetch resulted in an error */
    get isError() {
        return this.result.isError;
    }
    /** Whether no fonts are loaded (not loading and empty array) */
    get isEmpty() {
        return !this.isLoading && this.fonts.length === 0;
    }
    /**
     * Add a reactive parameter binding
     * @param getter - Function that returns partial params to merge
     * @returns Unbind function to remove the binding
     */
    addBinding(getter: () => Partial<TParams>) {
        this.#bindings.push(getter);
        return () => {
            this.#bindings = this.#bindings.filter(b => b !== getter);
        };
    }
    /**
     * Update query parameters
     * @param newParams - Partial params to merge with existing
     */
    setParams(newParams: Partial<TParams>) {
        this.#internalParams = { ...this.params, ...newParams };
    }
    /**
     * Invalidate cache and refetch
     */
    invalidate() {
        this.qc.invalidateQueries({ queryKey: this.getQueryKey(this.params) });
    }
    /**
     * Clean up effects and observers
     */
    destroy() {
        this.cleanup();
    }
    /**
     * Manually trigger a refetch
     */
    async refetch() {
        await this.observer.refetch();
    }
    /**
     * Prefetch data with different parameters
     */
    async prefetch(params: TParams) {
        await this.qc.prefetchQuery(this.getOptions(params));
    }
    /**
     * Cancel ongoing queries
     */
    cancel() {
        this.qc.cancelQueries({
            queryKey: this.getQueryKey(this.params),
        });
    }
    /**
     * Clear cache for current params
     */
    clearCache() {
        this.qc.removeQueries({
            queryKey: this.getQueryKey(this.params),
        });
    }
    /**
     * Get cached data without triggering fetch
     */
    getCachedData() {
        return this.qc.getQueryData<UnifiedFont[]>(
            this.getQueryKey(this.params),
        );
    }
    /**
     * Set data manually (optimistic updates)
     */
    setQueryData(updater: (old: UnifiedFont[] | undefined) => UnifiedFont[]) {
        this.qc.setQueryData(
            this.getQueryKey(this.params),
            updater,
        );
    }
 }
--- a/src/entities/Font/model/store/batchFontStore.svelte.ts
+++ b/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;
    }
 }
--- a/src/entities/Font/model/store/batchFontStore.test.ts
+++ b/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 });
        });
    });
 });
--- a/src/entities/Font/model/store/fontStore/fontStore.svelte.spec.ts
+++ b/src/entities/Font/model/store/fontStore/fontStore.svelte.spec.ts
@@ -0,0 +1,583 @@
 import { QueryClient } from '@tanstack/query-core';
 import { flushSync } from 'svelte';
 import {
    afterEach,
    beforeEach,
    describe,
    expect,
    it,
    vi,
 } from 'vitest';
 import {
    FontNetworkError,
    FontResponseError,
 } from '../../../lib/errors/errors';
 import {
    generateMixedCategoryFonts,
    generateMockFonts,
 } from '../../../lib/mocks/fonts.mock';
 import type { UnifiedFont } from '../../types';
 import { FontStore } from './fontStore.svelte';
 vi.mock('$shared/api/queryClient', () => ({
    queryClient: new QueryClient({
        defaultOptions: { queries: { retry: 0, gcTime: 0 } },
    }),
 }));
 vi.mock('../../../api', () => ({ fetchProxyFonts: vi.fn() }));
 import { queryClient } from '$shared/api/queryClient';
 import { fetchProxyFonts } from '../../../api';
 const fetch = fetchProxyFonts as ReturnType<typeof vi.fn>;
 type FontPage = { fonts: UnifiedFont[]; total: number; limit: number; offset: number };
 const makeResponse = (
    fonts: UnifiedFont[],
    meta: { total?: number; limit?: number; offset?: number } = {},
 ): FontPage => ({
    fonts,
    total: meta.total ?? fonts.length,
    limit: meta.limit ?? 10,
    offset: meta.offset ?? 0,
 });
 function makeStore(params = {}) {
    return new FontStore({ limit: 10, ...params });
 }
 async function fetchedStore(params = {}, fonts = generateMockFonts(5), meta: Parameters<typeof makeResponse>[1] = {}) {
    fetch.mockResolvedValue(makeResponse(fonts, meta));
    const store = makeStore(params);
    await store.refetch();
    flushSync();
    return store;
 }
 describe('FontStore', () => {
    afterEach(() => {
        queryClient.clear();
        vi.resetAllMocks();
    });
    // -----------------------------------------------------------------------
    describe('construction', () => {
        it('stores initial params', () => {
            const store = makeStore({ limit: 20 });
            expect(store.params.limit).toBe(20);
            store.destroy();
        });
        it('defaults limit to 50 when not provided', () => {
            const store = new FontStore();
            expect(store.params.limit).toBe(50);
            store.destroy();
        });
        it('starts with empty fonts', () => {
            const store = makeStore();
            expect(store.fonts).toEqual([]);
            store.destroy();
        });
        it('starts with isEmpty false — initial fetch is in progress', () => {
            // The observer starts fetching immediately on construction.
            // isEmpty must be false so the UI shows a loader, not "no results".
            const store = makeStore();
            expect(store.isEmpty).toBe(false);
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('state after fetch', () => {
        it('exposes loaded fonts', async () => {
            const store = await fetchedStore({}, generateMockFonts(7));
            expect(store.fonts).toHaveLength(7);
            store.destroy();
        });
        it('isEmpty is false when fonts are present', async () => {
            const store = await fetchedStore();
            expect(store.isEmpty).toBe(false);
            store.destroy();
        });
        it('isLoading is false after fetch', async () => {
            const store = await fetchedStore();
            expect(store.isLoading).toBe(false);
            store.destroy();
        });
        it('isFetching is false after fetch', async () => {
            const store = await fetchedStore();
            expect(store.isFetching).toBe(false);
            store.destroy();
        });
        it('isError is false on success', async () => {
            const store = await fetchedStore();
            expect(store.isError).toBe(false);
            store.destroy();
        });
        it('error is null on success', async () => {
            const store = await fetchedStore();
            expect(store.error).toBeNull();
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('error states', () => {
        it('isError is false before any fetch', () => {
            const store = makeStore();
            expect(store.isError).toBe(false);
            store.destroy();
        });
        it('wraps network failures in FontNetworkError', async () => {
            fetch.mockRejectedValue(new Error('network down'));
            const store = makeStore();
            await store.refetch().catch(() => {});
            flushSync();
            expect(store.error).toBeInstanceOf(FontNetworkError);
            expect(store.isError).toBe(true);
            store.destroy();
        });
        it('exposes FontResponseError for falsy response', async () => {
            const store = makeStore();
            fetch.mockResolvedValue(null);
            await store.refetch().catch(() => {});
            flushSync();
            expect(store.error).toBeInstanceOf(FontResponseError);
            expect((store.error as FontResponseError).field).toBe('response');
            store.destroy();
        });
        it('exposes FontResponseError for missing fonts field', async () => {
            fetch.mockResolvedValue({ total: 0, limit: 10, offset: 0 });
            const store = makeStore();
            await store.refetch().catch(() => {});
            flushSync();
            expect(store.error).toBeInstanceOf(FontResponseError);
            expect((store.error as FontResponseError).field).toBe('response.fonts');
            store.destroy();
        });
        it('exposes FontResponseError for non-array fonts', async () => {
            fetch.mockResolvedValue({ fonts: 'bad', total: 0, limit: 10, offset: 0 });
            const store = makeStore();
            await store.refetch().catch(() => {});
            flushSync();
            expect(store.error).toBeInstanceOf(FontResponseError);
            expect((store.error as FontResponseError).received).toBe('bad');
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('font accumulation', () => {
        it('replaces fonts when refetching the first page', async () => {
            const store = makeStore();
            fetch.mockResolvedValue(makeResponse(generateMockFonts(3)));
            await store.refetch();
            flushSync();
            const second = generateMockFonts(2);
            fetch.mockResolvedValue(makeResponse(second));
            await store.refetch();
            flushSync();
            // refetch at offset=0 re-fetches all pages; only one page loaded → new data replaces old
            expect(store.fonts).toHaveLength(2);
            expect(store.fonts[0].id).toBe(second[0].id);
            store.destroy();
        });
        it('appends fonts after nextPage', async () => {
            const page1 = generateMockFonts(3);
            const store = await fetchedStore({ limit: 3 }, page1, { total: 6, limit: 3, offset: 0 });
            const page2 = generateMockFonts(3).map((f, i) => ({ ...f, id: `p2-${i}` }));
            fetch.mockResolvedValue(makeResponse(page2, { total: 6, limit: 3, offset: 3 }));
            await store.nextPage();
            flushSync();
            expect(store.fonts).toHaveLength(6);
            expect(store.fonts.slice(0, 3).map(f => f.id)).toEqual(page1.map(f => f.id));
            expect(store.fonts.slice(3).map(f => f.id)).toEqual(page2.map(f => f.id));
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('pagination state', () => {
        it('returns zero-value defaults before any fetch', () => {
            const store = makeStore();
            expect(store.pagination).toMatchObject({ total: 0, hasMore: false, page: 1, totalPages: 0 });
            store.destroy();
        });
        it('reflects response metadata after fetch', async () => {
            const store = await fetchedStore({}, generateMockFonts(10), { total: 30, limit: 10, offset: 0 });
            expect(store.pagination.total).toBe(30);
            expect(store.pagination.hasMore).toBe(true);
            expect(store.pagination.page).toBe(1);
            expect(store.pagination.totalPages).toBe(3);
            store.destroy();
        });
        it('hasMore is false on the last page', async () => {
            const store = await fetchedStore({}, generateMockFonts(10), { total: 10, limit: 10, offset: 0 });
            expect(store.pagination.hasMore).toBe(false);
            store.destroy();
        });
        it('page count increments after nextPage', async () => {
            const store = await fetchedStore({ limit: 10 }, generateMockFonts(10), { total: 30, limit: 10, offset: 0 });
            expect(store.pagination.page).toBe(1);
            fetch.mockResolvedValue(makeResponse(generateMockFonts(10), { total: 30, limit: 10, offset: 10 }));
            await store.nextPage();
            flushSync();
            expect(store.pagination.page).toBe(2);
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('setParams', () => {
        it('merges updates into existing params', () => {
            const store = makeStore({ limit: 10 });
            store.setParams({ limit: 20 });
            expect(store.params.limit).toBe(20);
            store.destroy();
        });
        it('retains unmodified params', () => {
            const store = makeStore({ limit: 10 });
            store.setCategories(['serif']);
            store.setParams({ limit: 25 });
            expect(store.params.categories).toEqual(['serif']);
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('filter change resets', () => {
        it('clears accumulated fonts when a filter changes', async () => {
            const store = await fetchedStore({}, generateMockFonts(5));
            store.setSearch('roboto');
            flushSync();
            // TQ switches to a new queryKey → data.pages reset → fonts = []
            expect(store.fonts).toHaveLength(0);
            store.destroy();
        });
        it('isEmpty is false immediately after filter change — fetch is in progress', async () => {
            const store = await fetchedStore({}, generateMockFonts(5));
            // Hang the next fetch so we can observe the transitioning state
            fetch.mockReturnValue(new Promise(() => {}));
            store.setSearch('roboto');
            flushSync();
            // fonts = [] AND isFetching = true → isEmpty must be false (no "no results" flash)
            expect(store.isEmpty).toBe(false);
            store.destroy();
        });
        it('does NOT reset fonts when the same filter value is set again', async () => {
            const store = await fetchedStore({}, generateMockFonts(5));
            store.setCategories(['serif']);
            flushSync();
            // First change: clears fonts (expected)
            store.setCategories(['serif']); // same value — same queryKey — TQ keeps data.pages
            flushSync();
            // Because queryKey hasn't changed, TQ returns cached data — fonts restored from cache
            // (actual font count depends on cache; key assertion is no extra reset)
            expect(store.isError).toBe(false);
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('staleTime in buildOptions', () => {
        it('is 5 minutes with no active filters', () => {
            const store = makeStore();
            expect((store as any).buildOptions().staleTime).toBe(5 * 60 * 1000);
            store.destroy();
        });
        it('is 0 when a search query is active', () => {
            const store = makeStore();
            store.setSearch('roboto');
            expect((store as any).buildOptions().staleTime).toBe(0);
            store.destroy();
        });
        it('is 0 when a category filter is active', () => {
            const store = makeStore();
            store.setCategories(['serif']);
            expect((store as any).buildOptions().staleTime).toBe(0);
            store.destroy();
        });
        it('gcTime is 10 minutes always', () => {
            const store = makeStore();
            expect((store as any).buildOptions().gcTime).toBe(10 * 60 * 1000);
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('buildQueryKey', () => {
        it('omits empty-string params', () => {
            const store = makeStore();
            store.setSearch('');
            const [root, normalized] = (store as any).buildQueryKey(store.params);
            expect(root).toBe('fonts');
            expect(normalized).not.toHaveProperty('q');
            store.destroy();
        });
        it('omits empty-array params', () => {
            const store = makeStore();
            store.setProviders([]);
            const [, normalized] = (store as any).buildQueryKey(store.params);
            expect(normalized).not.toHaveProperty('providers');
            store.destroy();
        });
        it('includes non-empty filter values', () => {
            const store = makeStore();
            store.setCategories(['serif']);
            const [, normalized] = (store as any).buildQueryKey(store.params);
            expect(normalized).toHaveProperty('categories', ['serif']);
            store.destroy();
        });
        it('does not include offset (offset is the TQ page param, not a query key component)', () => {
            const store = makeStore();
            const [, normalized] = (store as any).buildQueryKey(store.params);
            expect(normalized).not.toHaveProperty('offset');
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('destroy', () => {
        it('does not throw', () => {
            const store = makeStore();
            expect(() => store.destroy()).not.toThrow();
        });
        it('is idempotent', () => {
            const store = makeStore();
            store.destroy();
            expect(() => store.destroy()).not.toThrow();
        });
    });
    // -----------------------------------------------------------------------
    describe('refetch', () => {
        it('triggers a fetch', async () => {
            const store = makeStore();
            fetch.mockResolvedValue(makeResponse(generateMockFonts(3)));
            await store.refetch();
            expect(fetch).toHaveBeenCalled();
            store.destroy();
        });
        it('uses params current at call time', async () => {
            const store = makeStore({ limit: 10 });
            store.setParams({ limit: 20 });
            fetch.mockResolvedValue(makeResponse(generateMockFonts(20)));
            await store.refetch();
            expect(fetch).toHaveBeenCalledWith(expect.objectContaining({ limit: 20 }));
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('nextPage', () => {
        let store: FontStore;
        beforeEach(async () => {
            fetch.mockResolvedValue(makeResponse(generateMockFonts(10), { total: 30, limit: 10, offset: 0 }));
            store = new FontStore({ limit: 10 });
            await store.refetch();
            flushSync();
        });
        afterEach(() => {
            store.destroy();
        });
        it('fetches the next page and appends fonts', async () => {
            fetch.mockResolvedValue(makeResponse(generateMockFonts(10), { total: 30, limit: 10, offset: 10 }));
            await store.nextPage();
            flushSync();
            expect(store.fonts).toHaveLength(20);
            expect(store.pagination.offset).toBe(10);
        });
        it('is a no-op when hasMore is false', async () => {
            // Set up a store where all fonts fit in one page (hasMore = false)
            queryClient.clear();
            fetch.mockResolvedValue(makeResponse(generateMockFonts(10), { total: 10, limit: 10, offset: 0 }));
            store = new FontStore({ limit: 10 });
            await store.refetch();
            flushSync();
            expect(store.pagination.hasMore).toBe(false);
            await store.nextPage(); // should not trigger another fetch
            expect(store.fonts).toHaveLength(10);
        });
    });
    // -----------------------------------------------------------------------
    describe('prevPage and goToPage', () => {
        it('prevPage is a no-op — infinite scroll does not support backward navigation', async () => {
            const store = await fetchedStore({}, generateMockFonts(5));
            store.prevPage();
            expect(store.fonts).toHaveLength(5); // unchanged
            store.destroy();
        });
        it('goToPage is a no-op — infinite scroll does not support arbitrary page jumps', async () => {
            const store = await fetchedStore({}, generateMockFonts(5));
            store.goToPage(3);
            expect(store.fonts).toHaveLength(5); // unchanged
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('prefetch', () => {
        it('triggers a fetch for the provided params', async () => {
            const store = makeStore();
            fetch.mockResolvedValue(makeResponse(generateMockFonts(5)));
            await store.prefetch({ limit: 5 });
            expect(fetch).toHaveBeenCalledWith(expect.objectContaining({ limit: 5, offset: 0 }));
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('getCachedData / setQueryData', () => {
        it('getCachedData returns undefined before any fetch', () => {
            queryClient.clear();
            const store = new FontStore({ limit: 10 });
            expect(store.getCachedData()).toBeUndefined();
            store.destroy();
        });
        it('getCachedData returns flattened fonts after fetch', async () => {
            const store = await fetchedStore();
            expect(store.getCachedData()).toHaveLength(5);
            store.destroy();
        });
        it('setQueryData writes to cache', () => {
            const store = makeStore();
            const font = generateMockFonts(1)[0];
            store.setQueryData(() => [font]);
            expect(store.getCachedData()).toHaveLength(1);
            store.destroy();
        });
        it('setQueryData updater receives existing flattened fonts', async () => {
            const store = await fetchedStore();
            const updater = vi.fn((old: UnifiedFont[] | undefined) => old ?? []);
            store.setQueryData(updater);
            expect(updater).toHaveBeenCalledWith(expect.any(Array));
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('invalidate', () => {
        it('calls invalidateQueries', async () => {
            const store = await fetchedStore();
            const spy = vi.spyOn(queryClient, 'invalidateQueries');
            store.invalidate();
            expect(spy).toHaveBeenCalledOnce();
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('setLimit', () => {
        it('updates the limit param', () => {
            const store = makeStore({ limit: 10 });
            store.setLimit(25);
            expect(store.params.limit).toBe(25);
            store.destroy();
        });
    });
    // -----------------------------------------------------------------------
    describe('filter shortcut methods', () => {
        let store: FontStore;
        beforeEach(() => {
            store = makeStore();
        });
        afterEach(() => {
            store.destroy();
        });
        it('setProviders updates providers param', () => {
            store.setProviders(['google']);
            expect(store.params.providers).toEqual(['google']);
        });
        it('setCategories updates categories param', () => {
            store.setCategories(['serif']);
            expect(store.params.categories).toEqual(['serif']);
        });
        it('setSubsets updates subsets param', () => {
            store.setSubsets(['cyrillic']);
            expect(store.params.subsets).toEqual(['cyrillic']);
        });
        it('setSearch sets q param', () => {
            store.setSearch('roboto');
            expect(store.params.q).toBe('roboto');
        });
        it('setSearch with empty string clears q', () => {
            store.setSearch('roboto');
            store.setSearch('');
            expect(store.params.q).toBeUndefined();
        });
        it('setSort updates sort param', () => {
            store.setSort('popularity');
            expect(store.params.sort).toBe('popularity');
        });
    });
    // -----------------------------------------------------------------------
    describe('category getters', () => {
        it('each getter returns only fonts of that category', async () => {
            const fonts = generateMixedCategoryFonts(2); // 2 of each category = 10 total
            fetch.mockResolvedValue(makeResponse(fonts, { total: fonts.length, limit: fonts.length }));
            const store = makeStore({ limit: 50 });
            await store.refetch();
            flushSync();
            expect(store.sansSerifFonts.every(f => f.category === 'sans-serif')).toBe(true);
            expect(store.serifFonts.every(f => f.category === 'serif')).toBe(true);
            expect(store.displayFonts.every(f => f.category === 'display')).toBe(true);
            expect(store.handwritingFonts.every(f => f.category === 'handwriting')).toBe(true);
            expect(store.monospaceFonts.every(f => f.category === 'monospace')).toBe(true);
            expect(store.sansSerifFonts).toHaveLength(2);
            store.destroy();
        });
    });
 });
--- a/src/entities/Font/model/store/fontStore/fontStore.svelte.ts
+++ b/src/entities/Font/model/store/fontStore/fontStore.svelte.ts
@@ -0,0 +1,283 @@
 import { queryClient } from '$shared/api/queryClient';
 import {
    type InfiniteData,
    InfiniteQueryObserver,
    type InfiniteQueryObserverResult,
    type QueryFunctionContext,
 } from '@tanstack/query-core';
 import {
    type ProxyFontsParams,
    type ProxyFontsResponse,
    fetchProxyFonts,
 } from '../../../api';
 import {
    FontNetworkError,
    FontResponseError,
 } from '../../../lib/errors/errors';
 import type { UnifiedFont } from '../../types';
 type PageParam = { offset: number };
 /** Filter params + limit — offset is managed by TQ as a page param, not a user param. */
 type FontStoreParams = Omit<ProxyFontsParams, 'offset'>;
 type FontStoreResult = InfiniteQueryObserverResult<InfiniteData<ProxyFontsResponse, PageParam>, Error>;
 export class FontStore {
    #params = $state<FontStoreParams>({ limit: 50 });
    #result = $state<FontStoreResult>({} as FontStoreResult);
    #observer: InfiniteQueryObserver<
        ProxyFontsResponse,
        Error,
        InfiniteData<ProxyFontsResponse, PageParam>,
        readonly unknown[],
        PageParam
    >;
    #qc = queryClient;
    #unsubscribe: () => void;
    constructor(params: FontStoreParams = {}) {
        this.#params = { limit: 50, ...params };
        this.#observer = new InfiniteQueryObserver(this.#qc, this.buildOptions());
        this.#unsubscribe = this.#observer.subscribe(r => {
            this.#result = r;
        });
    }
    // -- Public state --
    get params(): FontStoreParams {
        return this.#params;
    }
    get fonts(): UnifiedFont[] {
        return this.#result.data?.pages.flatMap((p: ProxyFontsResponse) => p.fonts) ?? [];
    }
    get isLoading(): boolean {
        return this.#result.isLoading;
    }
    get isFetching(): boolean {
        return this.#result.isFetching;
    }
    get isError(): boolean {
        return this.#result.isError;
    }
    get error(): Error | null {
        return this.#result.error ?? null;
    }
    // isEmpty is false during loading/fetching so the UI never flashes "no results"
    // while a fetch is in progress. The !isFetching guard is specifically for the filter-change
    // transition: fonts clear synchronously → isFetching becomes true → isEmpty stays false.
    get isEmpty(): boolean {
        return !this.isLoading && !this.isFetching && this.fonts.length === 0;
    }
    get pagination() {
        const pages = this.#result.data?.pages;
        const last = pages?.at(-1);
        if (!last) {
            return {
                total: 0,
                limit: this.#params.limit ?? 50,
                offset: 0,
                hasMore: false,
                page: 1,
                totalPages: 0,
            };
        }
        return {
            total: last.total,
            limit: last.limit,
            offset: last.offset,
            hasMore: this.#result.hasNextPage,
            page: pages!.length,
            totalPages: Math.ceil(last.total / last.limit),
        };
    }
    // -- Lifecycle --
    destroy() {
        this.#unsubscribe();
        this.#observer.destroy();
    }
    // -- Param management --
    setParams(updates: Partial<FontStoreParams>) {
        this.#params = { ...this.#params, ...updates };
        this.#observer.setOptions(this.buildOptions());
    }
    invalidate() {
        this.#qc.invalidateQueries({ queryKey: this.buildQueryKey(this.#params) });
    }
    // -- Async operations --
    async refetch() {
        await this.#observer.refetch();
    }
    async prefetch(params: FontStoreParams) {
        await this.#qc.prefetchInfiniteQuery(this.buildOptions(params));
    }
    cancel() {
        this.#qc.cancelQueries({ queryKey: this.buildQueryKey(this.#params) });
    }
    getCachedData(): UnifiedFont[] | undefined {
        const data = this.#qc.getQueryData<InfiniteData<ProxyFontsResponse, PageParam>>(
            this.buildQueryKey(this.#params),
        );
        if (!data) return undefined;
        return data.pages.flatMap(p => p.fonts);
    }
    setQueryData(updater: (old: UnifiedFont[] | undefined) => UnifiedFont[]) {
        const key = this.buildQueryKey(this.#params);
        this.#qc.setQueryData<InfiniteData<ProxyFontsResponse, PageParam>>(
            key,
            old => {
                const flatFonts = old?.pages.flatMap(p => p.fonts);
                const newFonts = updater(flatFonts);
                // Re-distribute the updated fonts back into the existing page structure
                // Define the first page. If old data exists, we merge into the first page template.
                const limit = typeof this.#params.limit === 'number' ? this.#params.limit : 50;
                const template = old?.pages[0] ?? {
                    total: newFonts.length,
                    limit,
                    offset: 0,
                };
                const updatedPage: ProxyFontsResponse = {
                    ...template,
                    fonts: newFonts,
                    total: newFonts.length, // Synchronize total with the new font count
                };
                return {
                    pages: [updatedPage],
                    pageParams: [{ offset: 0 }],
                };
            },
        );
    }
    // -- Filter shortcuts --
    setProviders(v: ProxyFontsParams['providers']) {
        this.setParams({ providers: v });
    }
    setCategories(v: ProxyFontsParams['categories']) {
        this.setParams({ categories: v });
    }
    setSubsets(v: ProxyFontsParams['subsets']) {
        this.setParams({ subsets: v });
    }
    setSearch(v: string) {
        this.setParams({ q: v || undefined });
    }
    setSort(v: ProxyFontsParams['sort']) {
        this.setParams({ sort: v });
    }
    // -- Pagination navigation --
    async nextPage(): Promise<void> {
        await this.#observer.fetchNextPage();
    }
    prevPage(): void {} // no-op: infinite scroll accumulates forward only; method kept for API compatibility
    goToPage(_page: number): void {} // no-op
    setLimit(limit: number) {
        this.setParams({ limit });
    }
    // -- Category views --
    get sansSerifFonts() {
        return this.fonts.filter(f => f.category === 'sans-serif');
    }
    get serifFonts() {
        return this.fonts.filter(f => f.category === 'serif');
    }
    get displayFonts() {
        return this.fonts.filter(f => f.category === 'display');
    }
    get handwritingFonts() {
        return this.fonts.filter(f => f.category === 'handwriting');
    }
    get monospaceFonts() {
        return this.fonts.filter(f => f.category === 'monospace');
    }
    // -- Private helpers (TypeScript-private so tests can spy via `as any`) --
    private buildQueryKey(params: FontStoreParams): readonly unknown[] {
        const filtered: Record<string, any> = {};
        for (const [key, value] of Object.entries(params)) {
            // Ensure we DO NOT 'continue' or skip the limit key here.
            // The limit is a fundamental part of the data identity.
            if (
                value !== undefined
                && value !== null
                && value !== ''
                && !(Array.isArray(value) && value.length === 0)
            ) {
                filtered[key] = value;
            }
        }
        return ['fonts', filtered];
    }
    private buildOptions(params = this.#params) {
        const activeParams = { ...params };
        const hasFilters = !!(
            activeParams.q
            || (Array.isArray(activeParams.providers) && activeParams.providers.length > 0)
            || (Array.isArray(activeParams.categories) && activeParams.categories.length > 0)
            || (Array.isArray(activeParams.subsets) && activeParams.subsets.length > 0)
        );
        return {
            queryKey: this.buildQueryKey(activeParams),
            queryFn: ({ pageParam }: QueryFunctionContext<readonly unknown[], PageParam>) =>
                this.fetchPage({ ...activeParams, ...pageParam }),
            initialPageParam: { offset: 0 } as PageParam,
            getNextPageParam: (lastPage: ProxyFontsResponse): PageParam | undefined => {
                const next = lastPage.offset + lastPage.limit;
                return next < lastPage.total ? { offset: next } : undefined;
            },
            staleTime: hasFilters ? 0 : 5 * 60 * 1000,
            gcTime: 10 * 60 * 1000,
        };
    }
    private async fetchPage(params: ProxyFontsParams): Promise<ProxyFontsResponse> {
        let response: ProxyFontsResponse;
        try {
            response = await fetchProxyFonts(params);
        } catch (cause) {
            throw new FontNetworkError(cause);
        }
        if (!response) throw new FontResponseError('response', response);
        if (!response.fonts) throw new FontResponseError('response.fonts', response.fonts);
        if (!Array.isArray(response.fonts)) throw new FontResponseError('response.fonts', response.fonts);
        return {
            fonts: response.fonts,
            total: response.total ?? 0,
            limit: response.limit ?? params.limit ?? 50,
            offset: response.offset ?? params.offset ?? 0,
        };
    }
 }
 export function createFontStore(params: FontStoreParams = {}): FontStore {
    return new FontStore(params);
 }
 export const fontStore = new FontStore({ limit: 50 });
--- a/src/entities/Font/model/store/index.ts
+++ b/src/entities/Font/model/store/index.ts
@@ -1,20 +1,12 @@
-/**
+// Applied fonts manager
- * ============================================================================
+export { appliedFontsManager } from './appliedFontsStore/appliedFontsStore.svelte';
 * UNIFIED FONT STORE EXPORTS
 * ============================================================================
 *
 * Single export point for the unified font store infrastructure.
 */
-// Primary store (unified)
+// Batch font store
-export {
+export { BatchFontStore } from './batchFontStore.svelte';
    createUnifiedFontStore,
    type UnifiedFontStore,
    unifiedFontStore,
 } from './unifiedFontStore.svelte';
-// Applied fonts manager (CSS loading - unchanged)
+// Single FontStore
 export {
-    appliedFontsManager,
+    createFontStore,
-    type FontConfigRequest,
+    FontStore,
-} from './appliedFontsStore/appliedFontsStore.svelte';
+    fontStore,
 } from './fontStore/fontStore.svelte';
--- a/src/entities/Font/model/store/unifiedFontStore.svelte.ts
+++ b/src/entities/Font/model/store/unifiedFontStore.svelte.ts
@@ -1,373 +0,0 @@
 /**
 * Unified font store
 *
 * Single source of truth for font data, powered by the proxy API.
 * Extends BaseFontStore for TanStack Query integration and reactivity.
 *
 * Key features:
 * - Provider-agnostic (proxy API handles provider logic)
 * - Reactive to filter changes
 * - Optimistic updates via TanStack Query
 * - Pagination support
 * - Provider-specific shortcuts for common operations
 */
 import type { QueryObserverOptions } from '@tanstack/query-core';
 import type { ProxyFontsParams } from '../../api';
 import { fetchProxyFonts } from '../../api';
 import type { UnifiedFont } from '../types';
 import { BaseFontStore } from './baseFontStore.svelte';
 /**
 * Unified font store wrapping TanStack Query with Svelte 5 runes
 *
 * Extends BaseFontStore to provide:
 * - Reactive state management
 * - TanStack Query integration for caching
 * - Dynamic parameter binding for filters
 * - Pagination support
 *
 * @example
 * ```ts
 * const store = new UnifiedFontStore({
 *     provider: 'google',
 *     category: 'sans-serif',
 *     limit: 50
 * });
 *
 * // Access reactive state
 * $effect(() => {
 *     console.log(store.fonts);
 *     console.log(store.isLoading);
 *     console.log(store.pagination);
 * });
 *
 * // Update parameters
 * store.setCategories(['serif']);
 * store.nextPage();
 * ```
 */
 export class UnifiedFontStore extends BaseFontStore<ProxyFontsParams> {
    /**
     * Store pagination metadata separately from fonts
     * This is a workaround for TanStack Query's type system
     */
    #paginationMetadata = $state<
        {
            total: number;
            limit: number;
            offset: number;
        } | null
    >(null);
    /**
     * Accumulated fonts from all pages (for infinite scroll)
     */
    #accumulatedFonts = $state<UnifiedFont[]>([]);
    /**
     * Pagination metadata (derived from proxy API response)
     */
    readonly pagination = $derived.by(() => {
        if (this.#paginationMetadata) {
            const { total, limit, offset } = this.#paginationMetadata;
            return {
                total,
                limit,
                offset,
                hasMore: offset + limit < total,
                page: Math.floor(offset / limit) + 1,
                totalPages: Math.ceil(total / limit),
            };
        }
        return {
            total: 0,
            limit: this.params.limit || 50,
            offset: this.params.offset || 0,
            hasMore: false,
            page: 1,
            totalPages: 0,
        };
    });
    /**
     * Track previous filter params to detect changes and reset pagination
     */
    #previousFilterParams = $state<string>('');
    /**
     * Cleanup function for the filter tracking effect
     */
    #filterCleanup: (() => void) | null = null;
    constructor(initialParams: ProxyFontsParams = {}) {
        super(initialParams);
        // Track filter params (excluding pagination params)
        // Wrapped in $effect.root() to prevent effect_orphan error
        this.#filterCleanup = $effect.root(() => {
            $effect(() => {
                const filterParams = JSON.stringify({
                    providers: this.params.providers,
                    categories: this.params.categories,
                    subsets: this.params.subsets,
                    q: this.params.q,
                });
                // If filters changed, reset offset and invalidate cache
                if (filterParams !== this.#previousFilterParams) {
                    if (this.#previousFilterParams) {
                        if (this.params.offset !== 0) {
                            this.setParams({ offset: 0 });
                        }
                        this.#accumulatedFonts = [];
                        this.invalidate();
                    }
                    this.#previousFilterParams = filterParams;
                }
            });
            // Effect: Sync state from Query result (Handles Cache Hits)
            $effect(() => {
                const data = this.result.data;
                const offset = this.params.offset || 0;
                // When we have data and we are at the start (offset 0),
                // we must ensure accumulatedFonts matches the fresh (or cached) data.
                // This fixes the issue where cache hits skip fetchFn side-effects.
                if (offset === 0 && data && data.length > 0) {
                    this.#accumulatedFonts = data;
                }
            });
        });
    }
    /**
     * Clean up both parent and child effects
     */
    destroy() {
        // Call parent cleanup (TanStack observer effect)
        super.destroy();
        // Call filter tracking effect cleanup
        if (this.#filterCleanup) {
            this.#filterCleanup();
            this.#filterCleanup = null;
        }
    }
    /**
     * Query key for TanStack Query caching
     * Normalizes params to treat empty arrays/strings as undefined
     */
    protected getQueryKey(params: ProxyFontsParams) {
        // Normalize params to treat empty arrays/strings as undefined
        const normalized = Object.entries(params).reduce((acc, [key, value]) => {
            if (value === '' || value === undefined || (Array.isArray(value) && value.length === 0)) {
                return acc;
            }
            return { ...acc, [key]: value };
        }, {});
        // Return a consistent key
        return ['unifiedFonts', normalized] as const;
    }
    protected getOptions(params = this.params): QueryObserverOptions<UnifiedFont[], Error> {
        const hasFilters = !!(params.q || params.providers || params.categories || params.subsets);
        return {
            queryKey: this.getQueryKey(params),
            queryFn: () => this.fetchFn(params),
            staleTime: hasFilters ? 0 : 5 * 60 * 1000,
            gcTime: 10 * 60 * 1000,
        };
    }
    /**
     * Fetch function that calls the proxy API
     * Returns the full response including pagination metadata
     */
    protected async fetchFn(params: ProxyFontsParams): Promise<UnifiedFont[]> {
        const response = await fetchProxyFonts(params);
        // Validate response structure
        if (!response) {
            console.error('[UnifiedFontStore] fetchProxyFonts returned undefined', { params });
            throw new Error('Proxy API returned undefined response');
        }
        if (!response.fonts) {
            console.error('[UnifiedFontStore] response.fonts is undefined', { response });
            throw new Error('Proxy API response missing fonts array');
        }
        if (!Array.isArray(response.fonts)) {
            console.error('[UnifiedFontStore] response.fonts is not an array', {
                fonts: response.fonts,
            });
            throw new Error('Proxy API fonts is not an array');
        }
        // Store pagination metadata separately for derived values
        this.#paginationMetadata = {
            total: response.total ?? 0,
            limit: response.limit ?? this.params.limit ?? 50,
            offset: response.offset ?? this.params.offset ?? 0,
        };
        // Accumulate fonts for infinite scroll
        // Note: For offset === 0, we rely on the $effect above to handle the reset/init
        // This prevents race conditions and double-setting.
        if (params.offset !== 0) {
            this.#accumulatedFonts = [...this.#accumulatedFonts, ...response.fonts];
        }
        return response.fonts;
    }
    /**
     * Get all accumulated fonts (for infinite scroll)
     */
    get fonts(): UnifiedFont[] {
        return this.#accumulatedFonts;
    }
    /**
     * Check if loading initial data
     */
    get isLoading(): boolean {
        return this.result.isLoading;
    }
    /**
     * Check if fetching (including background refetches)
     */
    get isFetching(): boolean {
        return this.result.isFetching;
    }
    /**
     * Check if error occurred
     */
    get isError(): boolean {
        return this.result.isError;
    }
    /**
     * Check if result is empty (not loading and no fonts)
     */
    get isEmpty(): boolean {
        return !this.isLoading && this.fonts.length === 0;
    }
    /**
     * Set providers filter
     */
    setProviders(providers: ProxyFontsParams['providers']) {
        this.setParams({ providers });
    }
    /**
     * Set categories filter
     */
    setCategories(categories: ProxyFontsParams['categories']) {
        this.setParams({ categories });
    }
    /**
     * Set subsets filter
     */
    setSubsets(subsets: ProxyFontsParams['subsets']) {
        this.setParams({ subsets });
    }
    /**
     * Set search query
     */
    setSearch(search: string) {
        this.setParams({ q: search || undefined });
    }
    /**
     * Set sort order
     */
    setSort(sort: ProxyFontsParams['sort']) {
        this.setParams({ sort });
    }
    /**
     * Go to next page
     */
    nextPage() {
        if (this.pagination.hasMore) {
            this.setParams({
                offset: this.pagination.offset + this.pagination.limit,
            });
        }
    }
    /**
     * Go to previous page
     */
    prevPage() {
        if (this.pagination.page > 1) {
            this.setParams({
                offset: this.pagination.offset - this.pagination.limit,
            });
        }
    }
    /**
     * Go to specific page
     */
    goToPage(page: number) {
        if (page >= 1 && page <= this.pagination.totalPages) {
            this.setParams({
                offset: (page - 1) * this.pagination.limit,
            });
        }
    }
    /**
     * Set limit (items per page)
     */
    setLimit(limit: number) {
        this.setParams({ limit });
    }
    get sansSerifFonts() {
        return this.fonts.filter(f => f.category === 'sans-serif');
    }
    get serifFonts() {
        return this.fonts.filter(f => f.category === 'serif');
    }
    get displayFonts() {
        return this.fonts.filter(f => f.category === 'display');
    }
    get handwritingFonts() {
        return this.fonts.filter(f => f.category === 'handwriting');
    }
    get monospaceFonts() {
        return this.fonts.filter(f => f.category === 'monospace');
    }
 }
 /**
 * Factory function to create unified font store
 */
 export function createUnifiedFontStore(params: ProxyFontsParams = {}) {
    return new UnifiedFontStore(params);
 }
 /**
 * Singleton instance for global use
 * Initialized with a default limit to prevent fetching all fonts at once
 */
 export const unifiedFontStore = new UnifiedFontStore({
    limit: 50,
    offset: 0,
 });
--- a/src/entities/Font/model/types/common.ts
+++ b/src/entities/Font/model/types/common.ts
@@ -1,68 +0,0 @@
 /**
 * Common font domain types
 *
 * Shared types for font entities across providers (Google, Fontshare).
 * Includes categories, subsets, weights, and filter types.
 */
 import type { FontCategory as FontshareFontCategory } from './fontshare';
 import type { FontCategory as GoogleFontCategory } from './google';
 /**
 * Unified font category across all providers
 */
 export type FontCategory = GoogleFontCategory | FontshareFontCategory;
 /**
 * Font provider identifier
 */
 export type FontProvider = 'google' | 'fontshare';
 /**
 * Character subset support
 */
 export type FontSubset = 'latin' | 'latin-ext' | 'cyrillic' | 'greek' | 'arabic' | 'devanagari';
 /**
 * Combined filter state for font queries
 */
 export interface FontFilters {
    /** Selected font providers */
    providers: FontProvider[];
    /** Selected font categories */
    categories: FontCategory[];
    /** Selected character subsets */
    subsets: FontSubset[];
 }
 /** Filter group identifier */
 export type FilterGroup = 'providers' | 'categories' | 'subsets';
 /** Filter type including search query */
 export type FilterType = FilterGroup | 'searchQuery';
 /**
 * Numeric font weights (100-900)
 */
 export type FontWeight = '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
 /**
 * Italic variant with weight: "100italic", "400italic", "700italic", etc.
 */
 export type FontWeightItalic = `${FontWeight}italic`;
 /**
 * All possible font variant identifiers
 *
 * Includes:
 * - Numeric weights: "400", "700", etc.
 * - Italic variants: "400italic", "700italic", etc.
 * - Legacy names: "regular", "italic", "bold", "bolditalic"
 */
 export type FontVariant =
    | FontWeight
    | FontWeightItalic
    | 'regular'
    | 'italic'
    | 'bold'
    | 'bolditalic';
--- a/src/entities/Font/model/types/normalize.ts
+++ b/src/entities/Font/model/types/normalize.ts
@@ -1,25 +1,85 @@
 /**
- * ============================================================================
+ * Font domain types
- * NORMALIZATION TYPES
+ *
- * ============================================================================
+ * Shared types for font entities across providers (Google, Fontshare).
 * Includes categories, subsets, weights, and the unified font model.
 */
-import type {
+/**
-    FontCategory,
+ * Unified font category across all providers
-    FontProvider,
+ */
-    FontSubset,
+export type FontCategory =
-    FontVariant,
+    | 'sans-serif'
-} from './common';
+    | 'serif'
    | 'display'
    | 'handwriting'
    | 'monospace'
    | 'slab'
    | 'script';
 /**
- * Font variant types (standardized)
+ * Font provider identifier
 */
 export type FontProvider = 'google' | 'fontshare';
 /**
 * Character subset support
 */
 export type FontSubset = 'latin' | 'latin-ext' | 'cyrillic' | 'greek' | 'arabic' | 'devanagari';
 /**
 * Combined filter state for font queries
 */
 export interface FontFilters {
    /** Selected font providers */
    providers: FontProvider[];
    /** Selected font categories */
    categories: FontCategory[];
    /** Selected character subsets */
    subsets: FontSubset[];
 }
 /** Filter group identifier */
 export type FilterGroup = 'providers' | 'categories' | 'subsets';
 /** Filter type including search query */
 export type FilterType = FilterGroup | 'searchQuery';
 /**
 * Numeric font weights (100-900)
 */
 export type FontWeight = '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
 /**
 * Italic variant with weight: "100italic", "400italic", "700italic", etc.
 */
 export type FontWeightItalic = `${FontWeight}italic`;
 /**
 * All possible font variant identifiers
 *
 * Includes:
 * - Numeric weights: "400", "700", etc.
 * - Italic variants: "400italic", "700italic", etc.
 * - Legacy names: "regular", "italic", "bold", "bolditalic"
 */
 export type FontVariant =
    | FontWeight
    | FontWeightItalic
    | 'regular'
    | 'italic'
    | 'bold'
    | 'bolditalic';
 /**
 * Standardized font variant alias
 */
 export type UnifiedFontVariant = FontVariant;
 /**
 * Font style URLs
 */
-export interface LegacyFontStyleUrls {
+export interface FontStyleUrls {
    /** Regular weight URL */
    regular?: string;
    /** Italic URL */
@@ -28,9 +88,7 @@ export interface LegacyFontStyleUrls {
    bold?: string;
    /** Bold italic URL */
    boldItalic?: string;
-}
+    /** Additional variant mapping */
 export interface FontStyleUrls extends LegacyFontStyleUrls {
    variants?: Partial<Record<UnifiedFontVariant, string>>;
 }
--- a/src/entities/Font/model/types/fontshare.ts
+++ b/src/entities/Font/model/types/fontshare.ts
@@ -1,468 +0,0 @@
 /**
 * ============================================================================
 * FONTHARE API TYPES
 * ============================================================================
 */
 export const FONTSHARE_API_URL = 'https://api.fontshare.com/v2/fonts' as const;
 export type FontCategory = 'sans' | 'serif' | 'slab' | 'display' | 'handwritten' | 'script';
 /**
 * Model of Fontshare API response
 * @see https://fontshare.com
 *
 * Fontshare API uses 'fonts' key instead of 'items' for the array
 */
 export interface FontshareApiModel {
    /**
     * Number of items returned in current page/response
     */
    count: number;
    /**
     * Total number of items available across all pages
     */
    count_total: number;
    /**
     * Indicates if there are more items available beyond this page
     */
    has_more: boolean;
    /**
     * Array of fonts (Fontshare uses 'fonts' key, not 'items')
     */
    fonts: FontshareFont[];
 }
 /**
 * Individual font metadata from Fontshare API
 */
 export interface FontshareFont {
    /**
     * Unique identifier for the font
     * UUID v4 format (e.g., "20e9fcdc-1e41-4559-a43d-1ede0adc8896")
     */
    id: string;
    /**
     * Display name of the font family
     * Examples: "Satoshi", "General Sans", "Clash Display"
     */
    name: string;
    /**
     * Native/localized name of the font (if available)
     * Often null for Latin-script fonts
     */
    native_name: string | null;
    /**
     * URL-friendly identifier for the font
     * Used in URLs: e.g., "satoshi", "general-sans", "clash-display"
     */
    slug: string;
    /**
     * Font category classification
     * Examples: "Sans", "Serif", "Display", "Script"
     */
    category: string;
    /**
     * Script/writing system supported by the font
     * Examples: "latin", "arabic", "devanagari"
     */
    script: string;
    /**
     * Font publisher/foundry information
     */
    publisher: FontsharePublisher;
    /**
     * Array of designers who created this font
     * Multiple designers may have collaborated on a single font
     */
    designers: FontshareDesigner[];
    /**
     * Related font families (if any)
     * Often null, as fonts are typically independent
     */
    related_families: string | null;
    /**
     * Whether to display publisher as the designer instead of individual designers
     */
    display_publisher_as_designer: boolean;
    /**
     * Whether trial downloads are enabled for this font
     */
    trials_enabled: boolean;
    /**
     * Whether to show Latin-specific metrics
     */
    show_latin_metrics: boolean;
    /**
     * Type of license for this font
     * Examples: "itf_ffl" (ITF Free Font License)
     */
    license_type: string;
    /**
     * Comma-separated list of languages supported by this font
     * Example: "Afar, Afrikaans, Albanian, Aranese, Aromanian, Aymara, ..."
     */
    languages: string;
    /**
     * ISO 8601 timestamp when the font was added to Fontshare
     * Format: "2021-03-12T20:49:05Z"
     */
    inserted_at: string;
    /**
     * HTML-formatted story/description about the font
     * Contains marketing text, design philosophy, and usage recommendations
     */
    story: string;
    /**
     * Version of the font family
     * Format: "1.0", "1.2", etc.
     */
    version: string;
    /**
     * Total number of times this font has been viewed
     */
    views: number;
    /**
     * Number of views in the recent time period
     */
    views_recent: number;
    /**
     * Whether this font is marked as "hot"/trending
     */
    is_hot: boolean;
    /**
     * Whether this font is marked as new
     */
    is_new: boolean;
    /**
     * Whether this font is in the shortlisted collection
     */
    is_shortlisted: boolean | null;
    /**
     * Whether this font is marked as top/popular
     */
    is_top: boolean;
    /**
     * Variable font axes (for variable fonts)
     * Empty array [] for static fonts
     */
    axes: FontshareAxis[];
    /**
     * Tags/categories for this font
     * Examples: ["Magazines", "Branding", "Logos", "Posters"]
     */
    font_tags: FontshareTag[];
    /**
     * OpenType features available in this font
     */
    features: FontshareFeature[];
    /**
     * Array of available font styles/variants
     * Each style represents a different font file (weight, italic, variable)
     */
    styles: FontshareStyle[];
 }
 /**
 * Publisher/foundry information
 */
 export interface FontsharePublisher {
    /**
     * Description/bio of the publisher
     * Example: "Indian Type Foundry (ITF) creates retail and custom multilingual fonts..."
     */
    bio: string;
    /**
     * Publisher email (if available)
     */
    email: string | null;
    /**
     * Unique publisher identifier
     * UUID format
     */
    id: string;
    /**
     * Publisher links (social media, website, etc.)
     */
    links: FontshareLink[];
    /**
     * Publisher name
     * Example: "Indian Type Foundry"
     */
    name: string;
 }
 /**
 * Designer information
 */
 export interface FontshareDesigner {
    /**
     * Designer bio/description
     */
    bio: string;
    /**
     * Designer links (Twitter, website, etc.)
     */
    links: FontshareLink[];
    /**
     * Designer name
     */
    name: string;
 }
 /**
 * Link information
 */
 export interface FontshareLink {
    /**
     * Name of the link platform/site
     * Examples: "Twitter", "GitHub", "Website"
     */
    name: string;
    /**
     * URL of the link (may be null)
     */
    url: string | null;
 }
 /**
 * Font tag/category
 */
 export interface FontshareTag {
    /**
     * Tag name
     * Examples: "Magazines", "Branding", "Logos", "Posters"
     */
    name: string;
 }
 /**
 * OpenType feature
 */
 export interface FontshareFeature {
    /**
     * Feature name (descriptive name or null)
     * Examples: "Alternate t", "All Alternates", or null
     */
    name: string | null;
    /**
     * Whether this feature is on by default
     */
    on_by_default: boolean;
    /**
     * OpenType feature tag (4-character code)
     * Examples: "ss01", "frac", "liga", "aalt", "case"
     */
    tag: string;
 }
 /**
 * Variable font axis (for variable fonts)
 * Defines the range and properties of a variable font axis (e.g., weight)
 */
 export interface FontshareAxis {
    /**
     * Name of the axis
     * Example: "wght" (weight axis)
     */
    name: string;
    /**
     * CSS property name for the axis
     * Example: "wght"
     */
    property: string;
    /**
     * Default value for the axis
     * Example: 420.0, 650.0, 700.0
     */
    range_default: number;
    /**
     * Minimum value for the axis
     * Example: 300.0, 100.0, 200.0
     */
    range_left: number;
    /**
     * Maximum value for the axis
     * Example: 900.0, 700.0, 800.0
     */
    range_right: number;
 }
 /**
 * Individual font style/variant
 * Each style represents a single downloadable font file
 */
 export interface FontshareStyle {
    /**
     * Unique identifier for this style
     * UUID format
     */
    id: string;
    /**
     * Whether this is the default style for the font family
     * Typically, one style per font is marked as default
     */
    default: boolean;
    /**
     * CDN URL to the font file
     * Protocol-relative URL: "//cdn.fontshare.com/wf/..."
     * Note: URL starts with "//" (protocol-relative), may need protocol prepended
     */
    file: string;
    /**
     * Whether this style is italic
     * false for upright, true for italic styles
     */
    is_italic: boolean;
    /**
     * Whether this is a variable font
     * Variable fonts have adjustable axes (weight, slant, etc.)
     */
    is_variable: boolean;
    /**
     * Typography properties for this style
     * Contains measurements like cap height, x-height, ascenders/descenders
     * May be empty object {} for some styles
     */
    properties: FontshareStyleProperties | Record<string, never>;
    /**
     * Weight information for this style
     */
    weight: FontshareWeight;
 }
 /**
 * Typography/measurement properties for a font style
 */
 export interface FontshareStyleProperties {
    /**
     * Distance from baseline to the top of ascenders
     * Example: 1010, 990, 1000
     */
    ascending_leading: number | null;
    /**
     * Height of uppercase letters (cap height)
     * Example: 710, 680, 750
     */
    cap_height: number | null;
    /**
     * Distance from baseline to the bottom of descenders (negative value)
     * Example: -203, -186, -220
     */
    descending_leading: number | null;
    /**
     * Body height of the font
     * Often null in Fontshare data
     */
    body_height: number | null;
    /**
     * Maximum character width in the font
     * Example: 1739, 1739, 1739
     */
    max_char_width: number | null;
    /**
     * Height of lowercase x-height
     * Example: 480, 494, 523
     */
    x_height: number | null;
    /**
     * Maximum Y coordinate (top of ascenders)
     * Example: 1010, 990, 1026
     */
    y_max: number | null;
    /**
     * Minimum Y coordinate (bottom of descenders)
     * Example: -240, -250, -280
     */
    y_min: number | null;
 }
 /**
 * Weight information for a font style
 */
 export interface FontshareWeight {
    /**
     * Display label for the weight
     * Examples: "Light", "Regular", "Bold", "Variable", "Variable Italic"
     */
    label: string;
    /**
     * Internal name for the weight
     * Examples: "Light", "Regular", "Bold", "Variable", "VariableItalic"
     */
    name: string;
    /**
     * Native/localized name for the weight (if available)
     * Often null for Latin-script fonts
     */
    native_name: string | null;
    /**
     * Numeric weight value
     * Examples: 300, 400, 700, 0 (for variable fonts), 1, 2
     * Note: This matches the `weight` property
     */
    number: number;
    /**
     * Numeric weight value (duplicate of `number`)
     * Appears to be redundant with `number` field
     */
    weight: number;
 }
--- a/src/entities/Font/model/types/google.ts
+++ b/src/entities/Font/model/types/google.ts
@@ -1,99 +0,0 @@
 /**
 * ============================================================================
 * GOOGLE FONTS API TYPES
 * ============================================================================
 */
 import type { FontVariant } from './common';
 export type FontCategory = 'sans-serif' | 'serif' | 'display' | 'handwriting' | 'monospace';
 /**
 * Model of google fonts api response
 */
 export interface GoogleFontsApiModel {
    /**
     * Array of font items returned by the Google Fonts API
     * Contains all font families matching the requested query parameters
     */
    items: FontItem[];
 }
 /**
 * Individual font from Google Fonts API
 */
 export interface FontItem {
    /**
     * Font family name (e.g., "Roboto", "Open Sans", "Lato")
     * This is the name used in CSS font-family declarations
     */
    family: string;
    /**
     * Font category classification (e.g., "sans-serif", "serif", "display", "handwriting", "monospace")
     * Useful for grouping and filtering fonts by style
     */
    category: FontCategory;
    /**
     * Available font variants for this font family
     * Array of strings representing available weights and styles
     * Examples: ["regular", "italic", "100", "200", "300", "400", "500", "600", "700", "800", "900", "100italic", "900italic"]
     * The keys in the `files` object correspond to these variant values
     */
    variants: FontVariant[];
    /**
     * Supported character subsets for this font
     * Examples: ["latin", "latin-ext", "cyrillic", "greek", "arabic", "devanagari", "vietnamese", "hebrew", "thai", etc.]
     * Determines which character sets are included in the font files
     */
    subsets: string[];
    /**
     * Font version identifier
     * Format: "v" followed by version number (e.g., "v31", "v20", "v1")
     * Used to track font updates and cache busting
     */
    version: string;
    /**
     * Last modification date of the font
     * Format: ISO 8601 date string (e.g., "2024-01-15", "2023-12-01")
     * Indicates when the font was last updated by the font foundry
     */
    lastModified: string;
    /**
     * Mapping of font variants to their downloadable URLs
     * Keys correspond to values in the `variants` array
     * Examples:
     * - "regular" → "https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Me4W..."
     * - "700" → "https://fonts.gstatic.com/s/roboto/v30/KFOlCnqEu92Fr1MmWUlf..."
     * - "700italic" → "https://fonts.gstatic.com/s/roboto/v30/KFOjCnqEu92Fr1Mu51TzA..."
     */
    files: FontFiles;
    /**
     * URL to the font menu preview image
     * Typically a PNG showing the font family name in the font
     * Example: "https://fonts.gstatic.com/l/font?kit=KFOmCnqEu92Fr1Me4W...&s=i2"
     */
    menu: string;
 }
 /**
 * Type alias for backward compatibility
 * Google Fonts API font item
 */
 export type GoogleFontItem = FontItem;
 /**
 * Google Fonts API file mapping
 * Dynamic keys that match the variants array
 *
 * Examples:
 * - { "regular": "...", "italic": "...", "700": "...", "700italic": "..." }
 * - { "400": "...", "400italic": "...", "900": "..." }
 */
 export type FontFiles = Partial<Record<FontVariant, string>>;
--- a/src/entities/Font/model/types/index.ts
+++ b/src/entities/Font/model/types/index.ts
@@ -7,48 +7,23 @@
 * All imports should use: `import { X } from '$entities/Font/model/types'`
 */
-// Domain types
+// Font domain and model types
 export type {
    FilterGroup,
    FilterType,
    FontCategory,
    FontFeatures,
    FontFilters,
    FontMetadata,
    FontProvider,
    FontStyleUrls,
    FontSubset,
    FontVariant,
    FontWeight,
    FontWeightItalic,
 } from './common';
 // Google Fonts API types
 export type {
    FontFiles,
    FontItem,
    GoogleFontItem,
    GoogleFontsApiModel,
 } from './google';
 // Fontshare API types
 export type {
    FontshareApiModel,
    FontshareAxis,
    FontshareDesigner,
    FontshareFeature,
    FontshareFont,
    FontshareLink,
    FontsharePublisher,
    FontshareStyle,
    FontshareStyleProperties,
    FontshareTag,
    FontshareWeight,
 } from './fontshare';
 export { FONTSHARE_API_URL } from './fontshare';
 // Normalization types
 export type {
    FontFeatures,
    FontMetadata,
    FontStyleUrls,
    UnifiedFont,
    UnifiedFontVariant,
-} from './normalize';
+} from './font';
 // Store types
 export type {
@@ -56,3 +31,5 @@ export type {
    FontCollectionSort,
    FontCollectionState,
 } from './store';
 export * from './store/appliedFonts';
--- a/src/entities/Font/model/types/store.ts
+++ b/src/entities/Font/model/types/store.ts
@@ -8,8 +8,8 @@ import type {
    FontCategory,
    FontProvider,
    FontSubset,
-} from './common';
+    UnifiedFont,
-import type { UnifiedFont } from './normalize';
+} from './font';
 /**
 * Font collection state
--- a/src/entities/Font/model/types/store/appliedFonts.ts
+++ b/src/entities/Font/model/types/store/appliedFonts.ts
@@ -0,0 +1,30 @@
 /**
 * Configuration for a font load request.
 */
 export interface FontLoadRequestConfig {
    /**
     * Unique identifier for the font (e.g., "lato", "roboto").
     */
    id: string;
    /**
     * Actual font family name recognized by the browser (e.g., "Lato", "Roboto").
     */
    name: string;
    /**
     * URL pointing to the font file (typically .ttf or .woff2).
     */
    url: string;
    /**
     * Numeric weight (100-900). Variable fonts load once per ID regardless of weight.
     */
    weight: number;
    /**
     * Variable fonts load once per ID; static fonts load per weight.
     */
    isVariable?: boolean;
 }
 /**
 * Loading state of a font.
 */
 export type FontLoadStatus = 'loading' | 'loaded' | 'error';
--- a/src/entities/Font/ui/FontVirtualList/FontVirtualList.svelte
+++ b/src/entities/Font/ui/FontVirtualList/FontVirtualList.svelte
@@ -15,11 +15,11 @@ import type {
 import { fade } from 'svelte/transition';
 import { getFontUrl } from '../../lib';
 import {
-    type FontConfigRequest,
+    type FontLoadRequestConfig,
    type UnifiedFont,
    appliedFontsManager,
    unifiedFontStore,
 } from '../../model';
 import { fontStore } from '../../model/store';
 interface Props extends
    Omit<
@@ -50,11 +50,11 @@ let {
 }: Props = $props();
 const isLoading = $derived(
-    unifiedFontStore.isFetching || unifiedFontStore.isLoading,
+    fontStore.isFetching || fontStore.isLoading,
 );
 function handleInternalVisibleChange(visibleItems: UnifiedFont[]) {
-    const configs: FontConfigRequest[] = [];
+    const configs: FontLoadRequestConfig[] = [];
    visibleItems.forEach(item => {
        const url = getFontUrl(item, weight);
@@ -82,12 +82,12 @@ function handleInternalVisibleChange(visibleItems: UnifiedFont[]) {
 */
 function loadMore() {
    if (
-        !unifiedFontStore.pagination.hasMore
+        !fontStore.pagination.hasMore
-        || unifiedFontStore.isFetching
+        || fontStore.isFetching
    ) {
        return;
    }
-    unifiedFontStore.nextPage();
+    fontStore.nextPage();
 }
 /**
@@ -97,17 +97,17 @@ function loadMore() {
 * of the loaded items. Only fetches if there are more pages available.
 */
 function handleNearBottom(_lastVisibleIndex: number) {
-    const { hasMore } = unifiedFontStore.pagination;
+    const { hasMore } = fontStore.pagination;
    // VirtualList already checks if we're near the bottom of loaded items
-    if (hasMore && !unifiedFontStore.isFetching) {
+    if (hasMore && !fontStore.isFetching) {
        loadMore();
    }
 }
 </script>
 <div class="relative w-full h-full">
-    {#if skeleton && isLoading && unifiedFontStore.fonts.length === 0}
+    {#if skeleton && isLoading && fontStore.fonts.length === 0}
        <!-- Show skeleton only on initial load when no fonts are loaded yet -->
        <div transition:fade={{ duration: 300 }}>
            {@render skeleton()}
@@ -115,8 +115,8 @@ function handleNearBottom(_lastVisibleIndex: number) {
    {:else}
        <!-- VirtualList persists during pagination - no destruction/recreation -->
        <VirtualList
-            items={unifiedFontStore.fonts}
+            items={fontStore.fonts}
-            total={unifiedFontStore.pagination.total}
+            total={fontStore.pagination.total}
            isLoading={isLoading}
            onVisibleItemsChange={handleInternalVisibleChange}
            onNearBottom={handleNearBottom}
--- a/src/features/GetFonts/ui/FiltersControl/FilterControls.svelte
+++ b/src/features/GetFonts/ui/FiltersControl/FilterControls.svelte
@@ -4,7 +4,7 @@
    Sits below the filter list, separated by a top border.
 -->
 <script lang="ts">
-import { unifiedFontStore } from '$entities/Font';
+import { fontStore } from '$entities/Font';
 import type { ResponsiveManager } from '$shared/lib';
 import { cn } from '$shared/shadcn/utils/shadcn-utils';
 import { Button } from '$shared/ui';
@@ -33,7 +33,7 @@ const {
 $effect(() => {
    const apiSort = sortStore.apiValue;
-    untrack(() => unifiedFontStore.setSort(apiSort));
+    untrack(() => fontStore.setSort(apiSort));
 });
 const responsive = getContext<ResponsiveManager>('responsive');
--- a/src/shared/api/queryKeys.test.ts
+++ b/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());
        });
    });
 });
--- a/src/shared/api/queryKeys.ts
+++ b/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;
--- a/src/shared/lib/helpers/BaseQueryStore.svelte.ts
+++ b/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();
    }
 }
--- a/src/shared/lib/helpers/BaseQueryStore.test.ts
+++ b/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();
        });
    });
 });
--- a/src/shared/lib/helpers/CharacterComparisonEngine/CharacterComparisonEngine.svelte.ts
+++ b/src/shared/lib/helpers/CharacterComparisonEngine/CharacterComparisonEngine.svelte.ts
@@ -0,0 +1,270 @@
 import {
    type PreparedTextWithSegments,
    layoutWithLines,
    prepareWithSegments,
 } from '@chenglou/pretext';
 /**
 * 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;
    /** 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;
        /** 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;
        /** 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;
    // Cached prepared data
    #preparedA: PreparedTextWithSegments | null = null;
    #preparedB: PreparedTextWithSegments | null = null;
    #unifiedPrepared: PreparedTextWithSegments | null = null;
    #lastText = '';
    #lastFontA = '';
    #lastFontB = '';
    // Cached layout results
    #lastWidth = -1;
    #lastLineHeight = -1;
    #lastResult: ComparisonResult | null = null;
    constructor(locale?: string) {
        this.#segmenter = new Intl.Segmenter(locale, { granularity: 'grapheme' });
    }
    /**
     * 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,
        fontA: string,
        fontB: string,
        width: number,
        lineHeight: number,
    ): ComparisonResult {
        if (!text) {
            return { lines: [], totalHeight: 0 };
        }
        const isFontChange = text !== this.#lastText || fontA !== this.#lastFontA || fontB !== this.#lastFontB;
        const isLayoutChange = width !== this.#lastWidth || lineHeight !== this.#lastLineHeight;
        if (!isFontChange && !isLayoutChange && this.#lastResult) {
            return this.#lastResult;
        }
        // 1. Prepare (or use cache)
        if (isFontChange) {
            this.#preparedA = prepareWithSegments(text, fontA);
            this.#preparedB = prepareWithSegments(text, fontB);
            this.#unifiedPrepared = this.#createUnifiedPrepared(this.#preparedA, this.#preparedB);
            this.#lastText = text;
            this.#lastFontA = fontA;
            this.#lastFontB = fontB;
        }
        if (!this.#unifiedPrepared || !this.#preparedA || !this.#preparedB) {
            return { lines: [], totalHeight: 0 };
        }
        // 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
        const resultLines: ComparisonLine[] = lines.map(line => {
            const chars: ComparisonLine['chars'] = [];
            let currentXA = 0;
            let currentXB = 0;
            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;
            for (let sIdx = start.segmentIndex; sIdx <= end.segmentIndex; sIdx++) {
                const segmentText = this.#preparedA!.segments[sIdx];
                if (segmentText === undefined) continue;
                // PERFORMANCE: Reuse segmenter results if possible, but for now just optimize the loop
                const graphemes = Array.from(this.#segmenter.segment(segmentText), s => s.segment);
                const advA = intA.breakableFitAdvances[sIdx];
                const advB = intB.breakableFitAdvances[sIdx];
                const gStart = sIdx === start.segmentIndex ? start.graphemeIndex : 0;
                const gEnd = sIdx === end.segmentIndex ? end.graphemeIndex : graphemes.length;
                for (let gIdx = gStart; gIdx < gEnd; gIdx++) {
                    const char = graphemes[gIdx];
                    const wA = advA != null ? advA[gIdx]! : intA.widths[sIdx]!;
                    const wB = advB != null ? advB[gIdx]! : intB.widths[sIdx]!;
                    chars.push({
                        char,
                        xA: currentXA,
                        widthA: wA,
                        xB: currentXB,
                        widthB: wB,
                    });
                    currentXA += wA;
                    currentXB += wB;
                }
            }
            return {
                text: line.text,
                width: line.width,
                chars,
            };
        });
        this.#lastWidth = width;
        this.#lastLineHeight = lineHeight;
        this.#lastResult = {
            lines: resultLines,
            totalHeight: height,
        };
        return this.#lastResult;
    }
    /**
     * 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,
        containerWidth: number,
    ): { proximity: number; isPast: boolean } {
        if (!this.#lastResult || !this.#lastResult.lines[lineIndex]) {
            return { proximity: 0, isPast: false };
        }
        const line = this.#lastResult.lines[lineIndex];
        const char = line.chars[charIndex];
        if (!char) return { proximity: 0, isPast: false };
        // Center the comparison on the unified width
        // In the UI, lines are centered. So we need to calculate the global X.
        const lineXOffset = (containerWidth - line.width) / 2;
        const charCenterX = lineXOffset + char.xA + (char.widthA / 2);
        const charGlobalPercent = (charCenterX / containerWidth) * 100;
        const distance = Math.abs(sliderPos - charGlobalPercent);
        const range = 5;
        const proximity = Math.max(0, 1 - distance / range);
        const isPast = sliderPos > charGlobalPercent;
        return { proximity, isPast };
    }
    /**
     * 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;
        const unified = { ...intA };
        unified.widths = intA.widths.map((w: number, i: number) => Math.max(w, intB.widths[i]));
        unified.lineEndFitAdvances = intA.lineEndFitAdvances.map((w: number, i: number) =>
            Math.max(w, intB.lineEndFitAdvances[i])
        );
        unified.lineEndPaintAdvances = intA.lineEndPaintAdvances.map((w: number, i: number) =>
            Math.max(w, intB.lineEndPaintAdvances[i])
        );
        unified.breakableFitAdvances = intA.breakableFitAdvances.map((advA: number[] | null, i: number) => {
            const advB = intB.breakableFitAdvances[i];
            if (!advA && !advB) return null;
            if (!advA) return advB;
            if (!advB) return advA;
            return advA.map((w: number, j: number) => Math.max(w, advB[j]));
        });
        return unified;
    }
 }
--- a/src/shared/lib/helpers/CharacterComparisonEngine/CharacterComparisonEngine.test.ts
+++ b/src/shared/lib/helpers/CharacterComparisonEngine/CharacterComparisonEngine.test.ts
@@ -0,0 +1,168 @@
 // @vitest-environment jsdom
 import { clearCache } from '@chenglou/pretext';
 import {
    beforeEach,
    describe,
    expect,
    it,
 } from 'vitest';
 import { installCanvasMock } from '../__mocks__/canvas';
 import { CharacterComparisonEngine } from './CharacterComparisonEngine.svelte';
 // FontA: 10px per character. FontB: 15px per character.
 // The mock dispatches on whether the font string contains 'FontA' or 'FontB'.
 const FONT_A_WIDTH = 10;
 const FONT_B_WIDTH = 15;
 function fontWidthFactory(font: string, text: string): number {
    const perChar = font.includes('FontA') ? FONT_A_WIDTH : FONT_B_WIDTH;
    return text.length * perChar;
 }
 describe('CharacterComparisonEngine', () => {
    let engine: CharacterComparisonEngine;
    beforeEach(() => {
        installCanvasMock(fontWidthFactory);
        clearCache();
        engine = new CharacterComparisonEngine();
    });
    // --- layout() ---
    it('returns empty result for empty string', () => {
        const result = engine.layout('', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        expect(result.lines).toHaveLength(0);
        expect(result.totalHeight).toBe(0);
    });
    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 '.
        // Unified must use FontB widths — so it must wrap at the same place FontB wraps.
        const result = engine.layout('AB CD', '400 16px "FontA"', '400 16px "FontB"', 35, 20);
        expect(result.lines.length).toBeGreaterThan(1);
        // First line text must not include both words.
        expect(result.lines[0].text).not.toContain('CD');
    });
    it('provides xA and xB offsets for both fonts on a single line', () => {
        // 'ABC' fits in 500px for both fonts.
        // FontA: A@0(w=10), B@10(w=10), C@20(w=10)
        // FontB: A@0(w=15), B@15(w=15), C@30(w=15)
        const result = engine.layout('ABC', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const chars = result.lines[0].chars;
        expect(chars).toHaveLength(3);
        expect(chars[0].xA).toBe(0);
        expect(chars[0].widthA).toBe(FONT_A_WIDTH);
        expect(chars[0].xB).toBe(0);
        expect(chars[0].widthB).toBe(FONT_B_WIDTH);
        expect(chars[1].xA).toBe(FONT_A_WIDTH); // 10
        expect(chars[1].widthA).toBe(FONT_A_WIDTH);
        expect(chars[1].xB).toBe(FONT_B_WIDTH); // 15
        expect(chars[1].widthB).toBe(FONT_B_WIDTH);
        expect(chars[2].xA).toBe(FONT_A_WIDTH * 2); // 20
        expect(chars[2].xB).toBe(FONT_B_WIDTH * 2); // 30
    });
    it('xA positions are monotonically increasing', () => {
        const result = engine.layout('ABCDE', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const chars = result.lines[0].chars;
        for (let i = 1; i < chars.length; i++) {
            expect(chars[i].xA).toBeGreaterThan(chars[i - 1].xA);
        }
    });
    it('xB positions are monotonically increasing', () => {
        const result = engine.layout('ABCDE', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const chars = result.lines[0].chars;
        for (let i = 1; i < chars.length; i++) {
            expect(chars[i].xB).toBeGreaterThan(chars[i - 1].xB);
        }
    });
    it('returns cached result when called again with same arguments', () => {
        const r1 = engine.layout('ABC', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const r2 = engine.layout('ABC', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        expect(r2).toBe(r1); // strict reference equality — same object
    });
    it('re-computes when text changes', () => {
        const r1 = engine.layout('ABC', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const r2 = engine.layout('DEF', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        expect(r2).not.toBe(r1);
        expect(r2.lines[0].text).not.toBe(r1.lines[0].text);
    });
    it('re-computes when width changes', () => {
        const r1 = engine.layout('Hello World', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const r2 = engine.layout('Hello World', '400 16px "FontA"', '400 16px "FontB"', 60, 20);
        expect(r2).not.toBe(r1);
    });
    it('re-computes when fontA changes', () => {
        const r1 = engine.layout('ABC', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const r2 = engine.layout('ABC', '400 24px "FontA"', '400 16px "FontB"', 500, 20);
        expect(r2).not.toBe(r1);
    });
    // --- getCharState() ---
    it('getCharState returns proximity 1 when slider is exactly over char center', () => {
        // 'A' only: FontA width=10. Container=500px. Line centered.
        // lineXOffset = (500 - maxWidth) / 2. maxWidth = max(10, 15) = 15 (FontB is wider).
        // charCenterX = lineXOffset + xA + widthA/2.
        // Using xA=0, widthA=10: charCenterX = (500-15)/2 + 0 + 5 = 247.5 + 5 = 252.5
        // charGlobalPercent = (252.5 / 500) * 100 = 50.5
        // distance = |50.5 - 50.5| = 0 => proximity = 1
        const containerWidth = 500;
        engine.layout('A', '400 16px "FontA"', '400 16px "FontB"', containerWidth, 20);
        // Recalculate expected percent manually:
        const lineWidth = Math.max(FONT_A_WIDTH, FONT_B_WIDTH); // 15 (unified worst-case)
        const lineXOffset = (containerWidth - lineWidth) / 2;
        const charCenterX = lineXOffset + 0 + FONT_A_WIDTH / 2;
        const charPercent = (charCenterX / containerWidth) * 100;
        const state = engine.getCharState(0, 0, charPercent, containerWidth);
        expect(state.proximity).toBe(1);
        expect(state.isPast).toBe(false);
    });
    it('getCharState returns proximity 0 when slider is far from char', () => {
        engine.layout('A', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        // Slider at 0%, char is near 50% — distance > 5 range => proximity = 0
        const state = engine.getCharState(0, 0, 0, 500);
        expect(state.proximity).toBe(0);
    });
    it('getCharState isPast is true when slider has passed char center', () => {
        engine.layout('A', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const state = engine.getCharState(0, 0, 100, 500);
        expect(state.isPast).toBe(true);
    });
    it('getCharState returns safe default for out-of-range lineIndex', () => {
        engine.layout('A', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const state = engine.getCharState(99, 0, 50, 500);
        expect(state.proximity).toBe(0);
        expect(state.isPast).toBe(false);
    });
    it('getCharState returns safe default for out-of-range charIndex', () => {
        engine.layout('A', '400 16px "FontA"', '400 16px "FontB"', 500, 20);
        const state = engine.getCharState(0, 99, 50, 500);
        expect(state.proximity).toBe(0);
        expect(state.isPast).toBe(false);
    });
    it('getCharState returns safe default before layout() has been called', () => {
        const state = engine.getCharState(0, 0, 50, 500);
        expect(state.proximity).toBe(0);
        expect(state.isPast).toBe(false);
    });
 });
--- a/src/shared/lib/helpers/TextLayoutEngine/TextLayoutEngine.svelte.ts
+++ b/src/shared/lib/helpers/TextLayoutEngine/TextLayoutEngine.svelte.ts
@@ -0,0 +1,154 @@
 import {
    layoutWithLines,
    prepareWithSegments,
 } from '@chenglou/pretext';
 /**
 * A single laid-out line of text, with per-grapheme x offsets and widths.
 *
 * `chars` is indexed by grapheme cluster (not UTF-16 code unit), so emoji
 * sequences and combining characters each produce exactly one entry.
 */
 export interface LayoutLine {
    /** Full text of this line as returned by pretext. */
    text: string;
    /** Rendered width of this line in pixels. */
    width: number;
    chars: Array<{
        /** The grapheme cluster string (may be >1 code unit for emoji, etc.). */
        char: string;
        /** X offset from the start of the line, in pixels. */
        x: number;
        /** Advance width of this grapheme, in pixels. */
        width: number;
    }>;
 }
 /**
 * 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;
 }
 /**
 * Single-font text layout engine backed by `@chenglou/pretext`.
 *
 * Replaces the canvas-DOM hybrid `createCharacterComparison` for cases where
 * only one font is needed. For dual-font comparison use `CharacterComparisonEngine`.
 *
 * **Usage**
 * ```ts
 * const engine = new TextLayoutEngine();
 * const result = engine.layout('Hello World', '400 16px "Inter"', 320, 24);
 * // result.lines[0].chars → [{ char: 'H', x: 0, width: 9 }, ...]
 * ```
 *
 * **Font string format:** `"${weight} ${size}px \"${family}\""` — e.g. `'400 16px "Inter"'`.
 * This matches what SliderArea constructs from `typography.weight` and `typography.renderedSize`.
 *
 * **Canvas requirement:** pretext calls `document.createElement('canvas').getContext('2d')` on
 * first use and caches the context for the process lifetime. Tests must install a canvas mock
 * (see `__mocks__/canvas.ts`) before the first `layout()` call.
 */
 export class TextLayoutEngine {
    /**
     * Grapheme segmenter used to split segment text into individual clusters.
     *
     * Pretext maintains its own internal segmenter for line-breaking decisions.
     * We keep a separate one here so we can iterate graphemes in `layout()`
     * without depending on pretext internals — the two segmenters produce
     * identical boundaries because both use `{ granularity: 'grapheme' }`.
     */
    #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' });
    }
    /**
     * Lay out `text` in the given `font` within `width` pixels.
     *
     * @param text       Raw text to lay out.
     * @param font       CSS font string: `"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. Empty `lines` when `text` is empty.
     */
    layout(text: string, font: string, width: number, lineHeight: number): LayoutResult {
        if (!text) {
            return { lines: [], totalHeight: 0 };
        }
        // prepareWithSegments measures the text and builds the segment data structure
        // (widths, breakableFitAdvances, etc.) that the line-walker consumes.
        const prepared = prepareWithSegments(text, font);
        const { lines, height } = layoutWithLines(prepared, width, lineHeight);
        // `PreparedTextWithSegments` has these fields in its public type definition
        // but the TypeScript signature only exposes `segments`. We cast to `any` to
        // access the parallel numeric arrays — they are documented in the plan and
        // verified against the pretext source at node_modules/@chenglou/pretext/src/layout.ts.
        const internal = prepared as any;
        const breakableFitAdvances = internal.breakableFitAdvances as (number[] | null)[];
        const widths = internal.widths as number[];
        const resultLines: LayoutLine[] = lines.map(line => {
            const chars: LayoutLine['chars'] = [];
            let currentX = 0;
            const start = line.start;
            const end = line.end;
            // Walk every segment that falls within this line's [start, end] cursors.
            // Both cursors are grapheme-level: start is inclusive, end is exclusive.
            for (let sIdx = start.segmentIndex; sIdx <= end.segmentIndex; sIdx++) {
                const segmentText = prepared.segments[sIdx];
                if (segmentText === undefined) continue;
                const graphemes = Array.from(this.#segmenter.segment(segmentText), s => s.segment);
                const advances = breakableFitAdvances[sIdx];
                // For the first and last segments of the line the cursor may point
                // into the middle of the segment — respect those boundaries.
                // All intermediate segments are walked in full (gStart=0, gEnd=length).
                const gStart = sIdx === start.segmentIndex ? start.graphemeIndex : 0;
                const gEnd = sIdx === end.segmentIndex ? end.graphemeIndex : graphemes.length;
                for (let gIdx = gStart; gIdx < gEnd; gIdx++) {
                    const char = graphemes[gIdx];
                    // `breakableFitAdvances[sIdx]` is an array of per-grapheme advance
                    // widths when the segment has >1 grapheme (multi-character words).
                    // It is `null` for single-grapheme segments (spaces, punctuation,
                    // emoji, etc.) — in that case the entire segment width is attributed
                    // to this single grapheme.
                    const charWidth = advances != null ? advances[gIdx]! : widths[sIdx]!;
                    chars.push({
                        char,
                        x: currentX,
                        width: charWidth,
                    });
                    currentX += charWidth;
                }
            }
            return {
                text: line.text,
                width: line.width,
                chars,
            };
        });
        return {
            lines: resultLines,
            // pretext guarantees height === lineCount * lineHeight (see layout.ts source).
            totalHeight: height,
        };
    }
 }
--- a/src/shared/lib/helpers/TextLayoutEngine/TextLayoutEngine.test.ts
+++ b/src/shared/lib/helpers/TextLayoutEngine/TextLayoutEngine.test.ts
@@ -0,0 +1,89 @@
 // @vitest-environment jsdom
 import { clearCache } from '@chenglou/pretext';
 import {
    beforeEach,
    describe,
    expect,
    it,
 } from 'vitest';
 import { installCanvasMock } from '../__mocks__/canvas';
 import { TextLayoutEngine } from './TextLayoutEngine.svelte';
 // Fixed-width mock: every segment is measured as (text.length * 10) px.
 // This is font-independent so we can reason about wrapping precisely.
 const CHAR_WIDTH = 10;
 describe('TextLayoutEngine', () => {
    let engine: TextLayoutEngine;
    beforeEach(() => {
        // Install mock BEFORE any prepareWithSegments call.
        // clearMeasurementCaches resets pretext's cached canvas context
        // and segment metric caches so each test gets a clean slate.
        installCanvasMock((_font, text) => text.length * CHAR_WIDTH);
        clearCache();
        engine = new TextLayoutEngine();
    });
    it('returns empty result for empty string', () => {
        const result = engine.layout('', '400 16px "Inter"', 500, 20);
        expect(result.lines).toHaveLength(0);
        expect(result.totalHeight).toBe(0);
    });
    it('returns a single line when text fits within width', () => {
        // 'ABC' = 3 chars × 10px = 30px, fits in 500px
        const result = engine.layout('ABC', '400 16px "Inter"', 500, 20);
        expect(result.lines).toHaveLength(1);
        expect(result.lines[0].text).toBe('ABC');
    });
    it('breaks text into multiple lines when it exceeds width', () => {
        // 'Hello World' — pretext will split at the space.
        // 'Hello' = 50px, ' ' hangs, 'World' = 50px. Width = 60px forces wrap after 'Hello '.
        const result = engine.layout('Hello World', '400 16px "Inter"', 60, 20);
        expect(result.lines.length).toBeGreaterThan(1);
        // First line must not exceed the container width.
        expect(result.lines[0].width).toBeLessThanOrEqual(60);
    });
    it('assigns correct x positions to characters on a single line', () => {
        // 'ABC': A=10px, B=10px, C=10px; all on one line in 500px container.
        const result = engine.layout('ABC', '400 16px "Inter"', 500, 20);
        const chars = result.lines[0].chars;
        expect(chars).toHaveLength(3);
        expect(chars[0].char).toBe('A');
        expect(chars[0].x).toBe(0);
        expect(chars[0].width).toBe(CHAR_WIDTH);
        expect(chars[1].char).toBe('B');
        expect(chars[1].x).toBe(CHAR_WIDTH);
        expect(chars[1].width).toBe(CHAR_WIDTH);
        expect(chars[2].char).toBe('C');
        expect(chars[2].x).toBe(CHAR_WIDTH * 2);
        expect(chars[2].width).toBe(CHAR_WIDTH);
    });
    it('x positions are monotonically increasing across a line', () => {
        const result = engine.layout('ABCDE', '400 16px "Inter"', 500, 20);
        const chars = result.lines[0].chars;
        for (let i = 1; i < chars.length; i++) {
            expect(chars[i].x).toBeGreaterThan(chars[i - 1].x);
        }
    });
    it('each line has at least one char', () => {
        const result = engine.layout('Hello World', '400 16px "Inter"', 60, 20);
        for (const line of result.lines) {
            expect(line.chars.length).toBeGreaterThan(0);
        }
    });
    it('totalHeight equals lineCount * lineHeight', () => {
        const lineHeight = 24;
        const result = engine.layout('Hello World', '400 16px "Inter"', 60, lineHeight);
        expect(result.totalHeight).toBe(result.lines.length * lineHeight);
    });
 });
--- a/src/shared/lib/helpers/mocks/canvas.ts
+++ b/src/shared/lib/helpers/mocks/canvas.ts
@@ -0,0 +1,29 @@
 // src/shared/lib/helpers/__mocks__/canvas.ts
 //
 // Call installCanvasMock(fn) before any pretext import to control measureText.
 // The factory receives the current ctx.font string and the text to measure.
 import { vi } from 'vitest';
 export type MeasureFactory = (font: string, text: string) => number;
 export function installCanvasMock(factory: MeasureFactory): void {
    let currentFont = '';
    const mockCtx = {
        get font() {
            return currentFont;
        },
        set font(f: string) {
            currentFont = f;
        },
        measureText: vi.fn((text: string) => ({ width: factory(currentFont, text) })),
    };
    // HTMLCanvasElement.prototype.getContext is the entry point pretext uses in DOM environments.
    // OffscreenCanvas takes priority in pretext; jsdom does not define it so DOM path is used.
    Object.defineProperty(HTMLCanvasElement.prototype, 'getContext', {
        configurable: true,
        writable: true,
        value: vi.fn(() => mockCtx),
    });
 }
--- a/src/shared/lib/helpers/createCharacterComparison/createCharacterComparison.svelte.ts
+++ b/src/shared/lib/helpers/createCharacterComparison/createCharacterComparison.svelte.ts
@@ -1,374 +0,0 @@
 /**
 * Character-by-character font comparison helper
 *
 * Creates utilities for comparing two fonts character by character.
 * Used by the ComparisonView widget to render morphing text effects
 * where characters transition between font A and font B based on
 * slider position.
 *
 * Features:
 * - Responsive text measurement using canvas
 * - Binary search for optimal line breaking
 * - Character proximity calculation for morphing effects
 * - Handles CSS transforms correctly (uses offsetWidth)
 *
 * @example
 * ```svelte
 * <script lang="ts">
 *   import { createCharacterComparison } from '$shared/lib/helpers';
 *
 *   const comparison = createCharacterComparison(
 *       () => text,
 *       () => fontA,
 *       () => fontB,
 *       () => weight,
 *       () => size
 *   );
 *
 *   $: lines = comparison.lines;
 * </script>
 *
 * <canvas bind:this={measureCanvas} hidden></canvas>
 * <div bind:this={container}>
 *   {#each lines as line}
 *     <span>{line.text}</span>
 *   {/each}
 * </div>
 * ```
 */
 /**
 * Represents a single line of text with its measured width
 */
 export interface LineData {
    /** The text content of the line */
    text: string;
    /** Maximum width between both fonts in pixels */
    width: number;
 }
 /**
 * Creates a character comparison helper for morphing text effects
 *
 * Measures text in both fonts to determine line breaks and calculates
 * character-level proximity for morphing animations.
 *
 * @param text - Getter for the text to compare
 * @param fontA - Getter for the first font (left/top side)
 * @param fontB - Getter for the second font (right/bottom side)
 * @param weight - Getter for the current font weight
 * @param size - Getter for the controlled font size
 * @returns Character comparison instance with lines and proximity calculations
 *
 * @example
 * ```ts
 * const comparison = createCharacterComparison(
 *     () => $sampleText,
 *     () => $selectedFontA,
 *     () => $selectedFontB,
 *     () => $fontWeight,
 *     () => $fontSize
 * );
 *
 * // Call when DOM is ready
 * comparison.breakIntoLines(container, canvas);
 *
 * // Get character state for morphing
 * const state = comparison.getCharState(5, sliderPosition, lineEl, container);
 * // state.proximity: 0-1 value for opacity/interpolation
 * // state.isPast: true if slider is past this character
 * ```
 */
 export function createCharacterComparison<
    T extends { name: string; id: string } | undefined = undefined,
 >(
    text: () => string,
    fontA: () => T,
    fontB: () => T,
    weight: () => number,
    size: () => number,
 ) {
    let lines = $state<LineData[]>([]);
    let containerWidth = $state(0);
    /**
     * Type guard to check if a font is defined
     */
    function fontDefined<T extends { name: string; id: string }>(font: T | undefined): font is T {
        return font !== undefined;
    }
    /**
     * Measures text width using canvas 2D context
     *
     * @param ctx - Canvas rendering context
     * @param text - Text string to measure
     * @param fontSize - Font size in pixels
     * @param fontWeight - Font weight (100-900)
     * @param fontFamily - Font family name (optional, returns 0 if missing)
     * @returns Width of text in pixels
     */
    function measureText(
        ctx: CanvasRenderingContext2D,
        text: string,
        fontSize: number,
        fontWeight: number,
        fontFamily?: string,
    ): number {
        if (!fontFamily) return 0;
        ctx.font = `${fontWeight} ${fontSize}px ${fontFamily}`;
        return ctx.measureText(text).width;
    }
    /**
     * Gets responsive font size based on viewport width
     *
     * Matches Tailwind breakpoints used in the component:
     * - < 640px: 64px
     * - 640-767px: 80px
     * - 768-1023px: 96px
     * - >= 1024px: 112px
     */
    function getFontSize() {
        if (typeof window === 'undefined') {
            return 64;
        }
        return window.innerWidth >= 1024
            ? 112
            : window.innerWidth >= 768
            ? 96
            : window.innerWidth >= 640
            ? 80
            : 64;
    }
    /**
     * Breaks text into lines based on container width
     *
     * Measures text in BOTH fonts and uses the wider width to prevent
     * layout shifts. Uses binary search for efficient word breaking.
     *
     * @param container - Container element to measure width from
     * @param measureCanvas - Hidden canvas element for text measurement
     */
    function breakIntoLines(
        container: HTMLElement | undefined,
        measureCanvas: HTMLCanvasElement | undefined,
    ) {
        if (!container || !measureCanvas || !fontA() || !fontB()) {
            return;
        }
        // Use offsetWidth to avoid CSS transform scaling issues
        // getBoundingClientRect() includes transform scale which breaks calculations
        const width = container.offsetWidth;
        containerWidth = width;
        const padding = window.innerWidth < 640 ? 48 : 96;
        const availableWidth = width - padding;
        const ctx = measureCanvas.getContext('2d');
        if (!ctx) {
            return;
        }
        const controlledFontSize = size();
        const fontSize = getFontSize();
        const currentWeight = weight();
        const words = text().split(' ');
        const newLines: LineData[] = [];
        let currentLineWords: string[] = [];
        /**
         * Adds a line to the output using the wider font's width
         */
        function pushLine(words: string[]) {
            if (words.length === 0 || !fontDefined(fontA()) || !fontDefined(fontB())) {
                return;
            }
            const lineText = words.join(' ');
            const widthA = measureText(
                ctx!,
                lineText,
                Math.min(fontSize, controlledFontSize),
                currentWeight,
                fontA()?.name,
            );
            const widthB = measureText(
                ctx!,
                lineText,
                Math.min(fontSize, controlledFontSize),
                currentWeight,
                fontB()?.name,
            );
            const maxWidth = Math.max(widthA, widthB);
            newLines.push({ text: lineText, width: maxWidth });
        }
        for (const word of words) {
            const testLine = currentLineWords.length > 0
                ? currentLineWords.join(' ') + ' ' + word
                : word;
            // Measure with both fonts - use wider to prevent shifts
            const widthA = measureText(
                ctx,
                testLine,
                Math.min(fontSize, controlledFontSize),
                currentWeight,
                fontA()?.name,
            );
            const widthB = measureText(
                ctx,
                testLine,
                Math.min(fontSize, controlledFontSize),
                currentWeight,
                fontB()?.name,
            );
            const maxWidth = Math.max(widthA, widthB);
            const isContainerOverflown = maxWidth > availableWidth;
            if (isContainerOverflown) {
                if (currentLineWords.length > 0) {
                    pushLine(currentLineWords);
                    currentLineWords = [];
                }
                // Check if word alone fits
                const wordWidthA = measureText(
                    ctx,
                    word,
                    Math.min(fontSize, controlledFontSize),
                    currentWeight,
                    fontA()?.name,
                );
                const wordWidthB = measureText(
                    ctx,
                    word,
                    Math.min(fontSize, controlledFontSize),
                    currentWeight,
                    fontB()?.name,
                );
                const wordAloneWidth = Math.max(wordWidthA, wordWidthB);
                if (wordAloneWidth <= availableWidth) {
                    currentLineWords = [word];
                } else {
                    // Word doesn't fit - binary search to find break point
                    let remainingWord = word;
                    while (remainingWord.length > 0) {
                        let low = 1;
                        let high = remainingWord.length;
                        let bestBreak = 1;
                        // Binary search for maximum characters that fit
                        while (low <= high) {
                            const mid = Math.floor((low + high) / 2);
                            const testFragment = remainingWord.slice(0, mid);
                            const wA = measureText(
                                ctx,
                                testFragment,
                                fontSize,
                                currentWeight,
                                fontA()?.name,
                            );
                            const wB = measureText(
                                ctx,
                                testFragment,
                                fontSize,
                                currentWeight,
                                fontB()?.name,
                            );
                            if (Math.max(wA, wB) <= availableWidth) {
                                bestBreak = mid;
                                low = mid + 1;
                            } else {
                                high = mid - 1;
                            }
                        }
                        pushLine([remainingWord.slice(0, bestBreak)]);
                        remainingWord = remainingWord.slice(bestBreak);
                    }
                }
            } else if (maxWidth > availableWidth && currentLineWords.length > 0) {
                pushLine(currentLineWords);
                currentLineWords = [word];
            } else {
                currentLineWords.push(word);
            }
        }
        if (currentLineWords.length > 0) {
            pushLine(currentLineWords);
        }
        lines = newLines;
    }
    /**
     * Calculates character proximity to slider position
     *
     * Used for morphing effects - returns how close a character is to
     * the slider and whether it's on the "past" side.
     *
     * @param charIndex - Index of character within its line
     * @param sliderPos - Slider position (0-100, percent across container)
     * @param lineElement - The line element containing the character
     * @param container - The container element for position calculations
     * @returns Proximity (0-1, 1 = at slider) and isPast (true = right of slider)
     */
    function getCharState(
        charIndex: number,
        sliderPos: number,
        lineElement?: HTMLElement,
        container?: HTMLElement,
    ) {
        if (!containerWidth || !container) {
            return {
                proximity: 0,
                isPast: false,
            };
        }
        const charElement = lineElement?.children[charIndex] as HTMLElement;
        if (!charElement) {
            return { proximity: 0, isPast: false };
        }
        // Get character bounding box relative to container
        const charRect = charElement.getBoundingClientRect();
        const containerRect = container.getBoundingClientRect();
        // Calculate character center as percentage of container width
        const charCenter = charRect.left + (charRect.width / 2) - containerRect.left;
        const charGlobalPercent = (charCenter / containerWidth) * 100;
        // Calculate proximity (1.0 = at slider, 0.0 = 5% away)
        const distance = Math.abs(sliderPos - charGlobalPercent);
        const range = 5;
        const proximity = Math.max(0, 1 - distance / range);
        const isPast = sliderPos > charGlobalPercent;
        return { proximity, isPast };
    }
    return {
        /** Reactive array of broken lines */
        get lines() {
            return lines;
        },
        /** Container width in pixels */
        get containerWidth() {
            return containerWidth;
        },
        /** Break text into lines based on current container and fonts */
        breakIntoLines,
        /** Get character state for morphing calculations */
        getCharState,
    };
 }
 /**
 * Type representing a character comparison instance
 */
 export type CharacterComparison = ReturnType<typeof createCharacterComparison>;
--- a/src/shared/lib/helpers/createCharacterComparison/createCharacterComparison.test.ts
+++ b/src/shared/lib/helpers/createCharacterComparison/createCharacterComparison.test.ts
@@ -1,312 +0,0 @@
 import {
    beforeEach,
    describe,
    expect,
    it,
    vi,
 } from 'vitest';
 import { createCharacterComparison } from './createCharacterComparison.svelte';
 type Font = { name: string; id: string };
 const fontA: Font = { name: 'Roboto', id: 'roboto' };
 const fontB: Font = { name: 'Open Sans', id: 'open-sans' };
 function createMockCanvas(charWidth = 10): HTMLCanvasElement {
    return {
        getContext: () => ({
            font: '',
            measureText: (text: string) => ({ width: text.length * charWidth }),
        }),
    } as unknown as HTMLCanvasElement;
 }
 function createMockContainer(offsetWidth = 500): HTMLElement {
    return {
        offsetWidth,
        getBoundingClientRect: () => ({
            left: 0,
            width: offsetWidth,
            top: 0,
            right: offsetWidth,
            bottom: 0,
            height: 0,
        }),
    } as unknown as HTMLElement;
 }
 describe('createCharacterComparison', () => {
    beforeEach(() => {
        // Mock window.innerWidth for getFontSize and padding calculations
        Object.defineProperty(globalThis, 'window', {
            value: { innerWidth: 1024 },
            writable: true,
            configurable: true,
        });
    });
    describe('Initial State', () => {
        it('should initialize with empty lines and zero container width', () => {
            const comparison = createCharacterComparison(
                () => 'test',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            expect(comparison.lines).toEqual([]);
            expect(comparison.containerWidth).toBe(0);
        });
    });
    describe('breakIntoLines', () => {
        it('should not break lines when container or canvas is undefined', () => {
            const comparison = createCharacterComparison(
                () => 'Hello world',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(undefined, undefined);
            expect(comparison.lines).toEqual([]);
            comparison.breakIntoLines(createMockContainer(), undefined);
            expect(comparison.lines).toEqual([]);
        });
        it('should not break lines when fonts are undefined', () => {
            const comparison = createCharacterComparison(
                () => 'Hello world',
                () => undefined,
                () => undefined,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(), createMockCanvas());
            expect(comparison.lines).toEqual([]);
        });
        it('should produce a single line when text fits within container', () => {
            // charWidth=10, padding=96 (innerWidth>=640), availableWidth=500-96=404
            // "Hello" = 5 chars * 10 = 50px, fits easily
            const comparison = createCharacterComparison(
                () => 'Hello',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(500), createMockCanvas(10));
            expect(comparison.lines).toHaveLength(1);
            expect(comparison.lines[0].text).toBe('Hello');
        });
        it('should break text into multiple lines when it overflows', () => {
            // charWidth=10, container=200, padding=96, availableWidth=104
            // "Hello world test" => "Hello" (50px), "Hello world" (110px > 104)
            // So "Hello" goes on line 1, "world" (50px) fits, "world test" (100px) fits
            const comparison = createCharacterComparison(
                () => 'Hello world test',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(200), createMockCanvas(10));
            expect(comparison.lines.length).toBeGreaterThan(1);
            // All original text should be preserved across lines
            const reconstructed = comparison.lines.map(l => l.text).join(' ');
            expect(reconstructed).toBe('Hello world test');
        });
        it('should update containerWidth after breaking lines', () => {
            const comparison = createCharacterComparison(
                () => 'Hi',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(750), createMockCanvas(10));
            expect(comparison.containerWidth).toBe(750);
        });
        it('should use smaller padding on narrow viewports', () => {
            Object.defineProperty(globalThis, 'window', {
                value: { innerWidth: 500 },
                writable: true,
                configurable: true,
            });
            // container=150, padding=48 (innerWidth<640), availableWidth=102
            // "ABCDEFGHIJ" = 10 chars * 10 = 100px, fits in 102
            const comparison = createCharacterComparison(
                () => 'ABCDEFGHIJ',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(150), createMockCanvas(10));
            expect(comparison.lines).toHaveLength(1);
            expect(comparison.lines[0].text).toBe('ABCDEFGHIJ');
        });
        it('should break a single long word using binary search', () => {
            // container=150, padding=96, availableWidth=54
            // "ABCDEFGHIJ" = 10 chars * 10 = 100px, doesn't fit as single word
            // Binary search should split it
            const comparison = createCharacterComparison(
                () => 'ABCDEFGHIJ',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(150), createMockCanvas(10));
            expect(comparison.lines.length).toBeGreaterThan(1);
            const reconstructed = comparison.lines.map(l => l.text).join('');
            expect(reconstructed).toBe('ABCDEFGHIJ');
        });
        it('should store max width between both fonts for each line', () => {
            // Use a canvas where measureText returns text.length * charWidth
            // Both fonts measure the same, so width = text.length * charWidth
            const comparison = createCharacterComparison(
                () => 'Hi',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(500), createMockCanvas(10));
            expect(comparison.lines[0].width).toBe(20); // "Hi" = 2 chars * 10
        });
    });
    describe('getCharState', () => {
        it('should return zero proximity and isPast=false when containerWidth is 0', () => {
            const comparison = createCharacterComparison(
                () => 'test',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            const state = comparison.getCharState(0, 50, undefined, undefined);
            expect(state.proximity).toBe(0);
            expect(state.isPast).toBe(false);
        });
        it('should return zero proximity when charElement is not found', () => {
            const comparison = createCharacterComparison(
                () => 'test',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            // First break lines to set containerWidth
            comparison.breakIntoLines(createMockContainer(500), createMockCanvas(10));
            const lineEl = { children: [] } as unknown as HTMLElement;
            const container = createMockContainer(500);
            const state = comparison.getCharState(0, 50, lineEl, container);
            expect(state.proximity).toBe(0);
            expect(state.isPast).toBe(false);
        });
        it('should calculate proximity based on distance from slider', () => {
            const comparison = createCharacterComparison(
                () => 'test',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(500), createMockCanvas(10));
            // Character centered at 250px in a 500px container = 50%
            const charEl = {
                getBoundingClientRect: () => ({ left: 240, width: 20 }),
            };
            const lineEl = { children: [charEl] } as unknown as HTMLElement;
            const container = createMockContainer(500);
            // Slider at 50% => charCenter at 250px => charGlobalPercent = 50%
            // distance = |50 - 50| = 0, proximity = max(0, 1 - 0/5) = 1
            const state = comparison.getCharState(0, 50, lineEl, container);
            expect(state.proximity).toBe(1);
            expect(state.isPast).toBe(false);
        });
        it('should return isPast=true when slider is past the character', () => {
            const comparison = createCharacterComparison(
                () => 'test',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(500), createMockCanvas(10));
            // Character centered at 100px => 20% of 500px
            const charEl = {
                getBoundingClientRect: () => ({ left: 90, width: 20 }),
            };
            const lineEl = { children: [charEl] } as unknown as HTMLElement;
            const container = createMockContainer(500);
            // Slider at 80% => past the character at 20%
            const state = comparison.getCharState(0, 80, lineEl, container);
            expect(state.isPast).toBe(true);
        });
        it('should return zero proximity when character is far from slider', () => {
            const comparison = createCharacterComparison(
                () => 'test',
                () => fontA,
                () => fontB,
                () => 400,
                () => 48,
            );
            comparison.breakIntoLines(createMockContainer(500), createMockCanvas(10));
            // Character at 10% of container, slider at 90% => distance = 80%, range = 5%
            const charEl = {
                getBoundingClientRect: () => ({ left: 45, width: 10 }),
            };
            const lineEl = { children: [charEl] } as unknown as HTMLElement;
            const container = createMockContainer(500);
            const state = comparison.getCharState(0, 90, lineEl, container);
            expect(state.proximity).toBe(0);
        });
    });
 });
--- a/src/shared/lib/helpers/createVirtualizer/createVirtualizer.svelte.ts
+++ b/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.
 *
--- a/src/shared/lib/helpers/index.ts
+++ b/src/shared/lib/helpers/index.ts
@@ -52,10 +52,16 @@ export {
 } from './createEntityStore/createEntityStore.svelte';
 export {
-    type CharacterComparison,
+    CharacterComparisonEngine,
-    createCharacterComparison,
+    type ComparisonLine,
-    type LineData,
+    type ComparisonResult,
-} from './createCharacterComparison/createCharacterComparison.svelte';
+} from './CharacterComparisonEngine/CharacterComparisonEngine.svelte';
 export {
    type LayoutLine as TextLayoutLine,
    type LayoutResult as TextLayoutResult,
    TextLayoutEngine,
 } from './TextLayoutEngine/TextLayoutEngine.svelte';
 export {
    createPersistentStore,
--- a/src/shared/lib/index.ts
+++ b/src/shared/lib/index.ts
@@ -5,10 +5,11 @@
 */
 export {
-    type CharacterComparison,
+    CharacterComparisonEngine,
    type ComparisonLine,
    type ComparisonResult,
    type ControlDataModel,
    type ControlModel,
    createCharacterComparison,
    createDebouncedState,
    createEntityStore,
    createFilter,
@@ -21,12 +22,14 @@ export {
    type EntityStore,
    type Filter,
    type FilterModel,
    type LineData,
    type PersistentStore,
    type PerspectiveManager,
    type Property,
    type ResponsiveManager,
    responsiveManager,
    TextLayoutEngine,
    type TextLayoutLine,
    type TextLayoutResult,
    type TypographyControl,
    type VirtualItem,
    type Virtualizer,
--- a/src/shared/lib/utils/buildQueryString/buildQueryString.ts
+++ b/src/shared/lib/utils/buildQueryString/buildQueryString.ts
@@ -7,7 +7,7 @@
 * @example
 * ```ts
 * buildQueryString({ category: 'serif', subsets: ['latin', 'latin-ext'] })
- * // Returns: "?category=serif&subsets=latin%2Clatin-ext"
+ * // Returns: "?category=serif&subsets=latin&subsets=latin-ext"
 *
 * buildQueryString({ limit: 50, page: 1 })
 * // Returns: "?limit=50&page=1"
@@ -16,7 +16,7 @@
 * // Returns: ""
 *
 * buildQueryString({ search: 'hello world', active: true })
- * // Returns: "?search=hello%20world&active=true"
+ * // Returns: "?search=hello+world&active=true"
 * ```
 */
@@ -35,7 +35,7 @@ export type QueryParams = Record<string, QueryParamValue | undefined | null>;
 *
 * Handles:
 * - Primitive values (string, number, boolean) - converted to strings
- * - Arrays - comma-separated values
+ * - Arrays - multiple parameters with same key (e.g., ?key=1&key=2&key=3)
 * - null/undefined - omitted from output
 * - Special characters - URL encoded
 *
@@ -51,14 +51,12 @@ export function buildQueryString(params: QueryParams): string {
            continue;
        }
-        // Handle arrays (comma-separated values)
+        // Handle arrays - append each item as separate parameter with same key
        if (Array.isArray(value)) {
-            const joined = value
+            for (const item of value) {
-                .filter(item => item !== undefined && item !== null)
+                if (item !== undefined && item !== null) {
-                .map(String)
+                    searchParams.append(key, String(item));
-                .join(',');
+                }
            if (joined) {
                searchParams.append(key, joined);
            }
        } else {
            // Handle primitives
--- a/src/widgets/ComparisonView/model/stores/comparisonStore.svelte.ts
+++ b/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,
-    unifiedFontStore,
+    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 BatchFontStore (TanStack Query) to fetch fonts by ID, replacing
- * Uses the CSS Font Loading API to ensure fonts are loaded before
+ * the previous hand-rolled async fetch approach. Three reactive effects
- * showing the comparison interface.
+ * 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
+                const fonts = this.#batchStore.fonts;
-                if (this.#isRestoring) {
+                if (fonts.length === 0) return;
                    return;
                }
-                // If we already have a selection, do nothing
+                const { fontAId: aId, fontBId: bId } = storage.value;
-                if (this.#fontA && this.#fontB) {
+                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;
                }
            });
-                // Check if fonts are available to set as defaults
+            // Effect 3: Set default fonts when storage is empty
-                const fonts = unifiedFontStore.fonts;
+            $effect(() => {
                if (this.#fontA && this.#fontB) return;
                const fonts = fontStore.fonts;
                if (fonts.length >= 2) {
-                    // Only set if we really have nothing (fallback)
+                    untrack(() => {
-                    if (!this.#fontA) this.#fontA = fonts[0];
+                        const id1 = fonts[0].id;
-                    if (!this.#fontB) this.#fontB = fonts[fonts.length - 1];
+                        const id2 = fonts[fonts.length - 1].id;
-
+                        storage.value = { fontAId: id1, fontBId: id2 };
-                    // Sync defaults to storage so they persist if the user leaves
+                        this.#batchStore.setIds([id1, id2]);
-                    this.updateStorage();
+                    });
                }
            });
        });
    }
    /**
-     * 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
+     * Updates persistent storage with the current font selection.
     *
     * 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
     */
    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;
    }
-    /**
+    /** Whether both fonts are selected and loaded */
     * Check if 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)
+     * Resets all state, clears storage, and disables the batch query.
     */
    initialize() {
        if (!this.#isRestoring && !this.#fontA && !this.#fontB) {
            this.restoreFromStorage();
        }
    }
    /**
     * Reset all state and clear storage
     */
    resetAll() {
        this.#fontA = undefined;
        this.#fontB = undefined;
        this.#batchStore.setIds([]);
        storage.clear();
        this.#typography.reset();
    }
--- a/src/widgets/ComparisonView/model/stores/comparisonStore.test.ts
+++ b/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:
+ * Uses the real BatchFontStore so Svelte $state reactivity works correctly.
- * - Font loading via CSS Font Loading API
+ * Controls network behaviour via vi.spyOn on the proxyFonts API layer.
 * - Storage synchronization when fonts change
 * - Default values from unifiedFontStore
 * - Reset functionality
 * - isReady computed state
 */
 /** @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
+// ── Persistent-store mock ─────────────────────────────────────────────────────
 vi.mock('$entities/Font', () => ({
    fetchFontsByIds: vi.fn(),
    unifiedFontStore: { fonts: [] },
 }));
 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 = {
+    storage._value = { fontAId: null, fontBId: null };
        fontAId: null as string | null,
        fontBId: null as string | null,
    };
    storage._clear = vi.fn(() => {
-        storage._value = {
+        storage._value = { fontAId: null, fontBId: null };
            fontAId: null,
            fontBId: null,
        };
    });
    Object.defineProperty(storage, 'value', {
@@ -116,471 +51,162 @@ vi.mock('$shared/lib/helpers/createPersistentStore/createPersistentStore.svelte'
    createPersistentStore: vi.fn(() => mockStorage),
 }));
-// Import after mocks
+// ── $entities/Font mock — keep real BatchFontStore, stub singletons ───────────
-import {
+
-    fetchFontsByIds,
+vi.mock('$entities/Font', async () => {
-    unifiedFontStore,
+    const { BatchFontStore } = await import(
-} from '$entities/Font';
+        '$entities/Font/model/store/batchFontStore.svelte'
-import { createTypographyControlManager } from '$features/SetupFont';
+    );
    return {
        BatchFontStore,
        fontStore: { fonts: [] },
        appliedFontsManager: {
            touch: vi.fn(),
            getFontStatus: vi.fn(),
            ready: vi.fn(() => Promise.resolve()),
        },
        getFontUrl: vi.fn(() => 'https://example.com/font.woff2'),
    };
 });
 // ── $features/SetupFont mock ──────────────────────────────────────────────────
 vi.mock('$features/SetupFont', () => ({
    DEFAULT_TYPOGRAPHY_CONTROLS_DATA: [],
    createTypographyControlManager: vi.fn(() => ({
        weight: 400,
        renderedSize: 48,
        reset: vi.fn(),
    })),
 }));
 // ── Imports (after mocks) ─────────────────────────────────────────────────────
 import { fontStore } from '$entities/Font';
 import * as proxyFonts from '$entities/Font/api/proxy/proxyFonts';
 import { ComparisonStore } from './comparisonStore.svelte';
-describe('ComparisonStore', () => {
+// ── Tests ─────────────────────────────────────────────────────────────────────
    // Mock fonts
    const mockFontA: UnifiedFont = UNIFIED_FONTS.roboto;
    const mockFontB: UnifiedFont = UNIFIED_FONTS.openSans;
-    // Mock document.fonts
+describe('ComparisonStore', () => {
-    let mockFontFaceSet: {
+    const mockFontA: UnifiedFont = UNIFIED_FONTS.roboto; // id: 'roboto'
-        check: ReturnType<typeof vi.fn>;
+    const mockFontB: UnifiedFont = UNIFIED_FONTS.openSans; // id: 'open-sans'
        load: ReturnType<typeof vi.fn>;
        ready: Promise<FontFaceSet>;
    };
    beforeEach(() => {
-        // Clear all mocks
+        queryClient.clear();
        vi.clearAllMocks();
-
+        mockStorage._value = { fontAId: null, fontBId: null };
        // Clear localStorage
        localStorage.clear();
        // Reset mock storage value via the helper
        mockStorage._value = {
            fontAId: null,
            fontBId: null,
        };
        mockStorage._clear.mockClear();
        (fontStore as any).fonts = [];
-        // Setup mock unifiedFontStore
+        // Default: fetchFontsByIds returns empty so tests that don't care don't hang
-        (unifiedFontStore as any).fonts = [];
+        vi.spyOn(proxyFonts, 'fetchFontsByIds').mockResolvedValue([]);
        // Setup mock fetchFontsByIds
        vi.mocked(fetchFontsByIds).mockResolvedValue([]);
        // Setup mock createTypographyControlManager
        vi.mocked(createTypographyControlManager).mockReturnValue({
            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),
        };
        // document.fonts: check returns true so #checkFontsLoaded resolves immediately
        Object.defineProperty(document, 'fonts', {
-            value: mockFontFaceSet,
+            value: {
                check: vi.fn(() => true),
                load: vi.fn(() => Promise.resolve()),
                ready: Promise.resolve({} as FontFaceSet),
            },
            writable: true,
            configurable: true,
        });
    });
-    afterEach(() => {
+    // ── Initialization ────────────────────────────────────────────────────────
        // 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') {
            Object.defineProperty(document, 'fonts', {
                value: {
                    check: vi.fn(() => true),
                    load: vi.fn(() => Promise.resolve()),
                    ready: Promise.resolve({} as FontFaceSet),
                },
                writable: true,
                configurable: true,
            });
        }
    });
    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.spyOn(proxyFonts, 'fetchFontsByIds').mockResolvedValue([mockFontA, mockFontB]);
            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();
+            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();
            consoleSpy.mockRestore();
        });
    });
-        it('should handle partial restoration when only one font is found', async () => {
+    // ── Default Fallbacks ─────────────────────────────────────────────────────
            // Ensure unifiedFontStore is empty so $effect doesn't interfere
            (unifiedFontStore as any).fonts = [];
    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(
-            // Only return fontA (simulating partial data from API)
+                () => new Promise(r => setTimeout(() => r([mockFontA, mockFontB]), 50)),
-            vi.mocked(fetchFontsByIds).mockResolvedValue([mockFontA]);
+            );
            const store = new ComparisonStore();
-            // Wait for async restoration from constructor
+            expect(store.isLoading).toBe(true);
            await new Promise(resolve => setTimeout(resolve, 10));
-            // The store should call fetchFontsByIds with both IDs
+            await vi.waitFor(() => expect(store.isLoading).toBe(false), { timeout: 2000 });
            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', () => {
+    // ── Reset ─────────────────────────────────────────────────────────────────
        it('should construct correct font strings for checking', async () => {
            mockFontFaceSet.check.mockReturnValue(false);
            (unifiedFontStore 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'));
            (unifiedFontStore 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 unifiedFontStore', () => {
        it('should set default fonts from unifiedFontStore 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.
            (unifiedFontStore as any).fonts = [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 unifiedFontStore as defaults', () => {
            const mockFontC = UNIFIED_FONTS.lato;
            (unifiedFontStore as any).fonts = [mockFontA, mockFontC, mockFontB];
            const store = new ComparisonStore();
            // Manually set the first font to test the logic
            store.fontA = mockFontA;
            expect(store.fontA?.id).toBe(mockFontA.id);
        });
    });
    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', () => {
+        it('should clear fontA and fontB on reset', async () => {
            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 () => {
            mockStorage._value.fontAId = mockFontA.id;
            mockStorage._value.fontBId = mockFontB.id;
-
+            vi.spyOn(proxyFonts, 'fetchFontsByIds').mockResolvedValue([mockFontA, mockFontB]);
            // Make fetch take some time
            vi.mocked(fetchFontsByIds).mockImplementation(
                () => new Promise(resolve => setTimeout(() => resolve([mockFontA, mockFontB]), 10)),
            );
            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
+            store.resetAll();
-            expect(store.isLoading).toBe(true);
+            expect(store.fontA).toBeUndefined();
-
+            expect(store.fontB).toBeUndefined();
            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');
        });
    });
 });
--- a/src/widgets/ComparisonView/ui/Line/Line.svelte
+++ b/src/widgets/ComparisonView/ui/Line/Line.svelte
@@ -6,15 +6,21 @@
 import type { Snippet } from 'svelte';
 import { comparisonStore } from '../../model';
 interface LineChar {
    char: string;
    xA: number;
    widthA: number;
    xB: number;
    widthB: number;
 }
 interface Props {
    /**
-     * Line text
+     * Pre-computed grapheme array from CharacterComparisonEngine.
     * Using the engine's chars array (rather than splitting line.text) ensures
     * correct grapheme-cluster boundaries for emoji and multi-codepoint characters.
     */
-    text: string;
+    chars: LineChar[];
    /**
     * DOM element reference
     */
    element?: HTMLElement;
    /**
     * Character render snippet
     */
@@ -22,18 +28,15 @@ interface Props {
 }
 const typography = $derived(comparisonStore.typography);
-let { text, element = $bindable<HTMLElement>(), character }: Props = $props();
+let { chars, character }: Props = $props();
 const characters = $derived(text.split(''));
 </script>
 <div
    bind:this={element}
    class="relative flex w-full justify-center items-center whitespace-nowrap"
    style:height="{typography.height}em"
    style:line-height="{typography.height}em"
 >
-    {#each characters as char, index}
+    {#each chars as c, index}
-        {@render character?.({ char, index })}
+        {@render character?.({ char: c.char, index })}
    {/each}
 </div>
--- a/src/widgets/ComparisonView/ui/SliderArea/SliderArea.svelte
+++ b/src/widgets/ComparisonView/ui/SliderArea/SliderArea.svelte
@@ -9,11 +9,12 @@
 -->
 <script lang="ts">
 import {
    type CharacterComparison,
    type ResponsiveManager,
    createCharacterComparison,
    debounce,
 } from '$shared/lib';
 import {
    CharacterComparisonEngine,
 } from '$shared/lib/helpers/CharacterComparisonEngine/CharacterComparisonEngine.svelte';
 import { cn } from '$shared/shadcn/utils/shadcn-utils';
 import { Loader } from '$shared/ui';
 import { getContext } from 'svelte';
@@ -44,22 +45,16 @@ const isLoading = $derived(comparisonStore.isLoading || !comparisonStore.isReady
 const typography = $derived(comparisonStore.typography);
 let container = $state<HTMLElement>();
 let measureCanvas = $state<HTMLCanvasElement>();
 const responsive = getContext<ResponsiveManager>('responsive');
 const isMobile = $derived(responsive?.isMobile ?? false);
 let isDragging = $state(false);
-const charComparison: CharacterComparison = createCharacterComparison(
+// New high-performance layout engine
-    () => comparisonStore.text,
+const comparisonEngine = new CharacterComparisonEngine();
    () => fontA,
    () => fontB,
    () => typography.weight,
    () => typography.renderedSize,
 );
-let lineElements = $state<(HTMLElement | undefined)[]>([]);
+let layoutResult = $state<ReturnType<typeof comparisonEngine.layout>>({ lines: [], totalHeight: 0 });
 const sliderSpring = new Spring(50, {
    stiffness: 0.2,
@@ -123,18 +118,41 @@ $effect(() => {
    const _weight = typography.weight;
    const _size = typography.renderedSize;
    const _height = typography.height;
-    if (container && measureCanvas && fontA && fontB) {
+
-        requestAnimationFrame(() => {
+    if (container && fontA && fontB) {
-            charComparison.breakIntoLines(container, measureCanvas);
+        // PRETEXT API strings: "weight sizepx family"
-        });
+        const fontAStr = `${_weight} ${_size}px "${fontA.name}"`;
        const fontBStr = `${_weight} ${_size}px "${fontB.name}"`;
        // Use offsetWidth to avoid transform scaling issues
        const width = container.offsetWidth;
        const padding = isMobile ? 48 : 96;
        const availableWidth = width - padding;
        const lineHeight = _size * 1.2; // Approximate
        layoutResult = comparisonEngine.layout(
            _text,
            fontAStr,
            fontBStr,
            availableWidth,
            lineHeight,
        );
    }
 });
 $effect(() => {
    if (typeof window === 'undefined') return;
    const handleResize = () => {
-        if (container && measureCanvas) {
+        if (container && fontA && fontB) {
-            charComparison.breakIntoLines(container, measureCanvas);
+            const width = container.offsetWidth;
            const padding = isMobile ? 48 : 96;
            layoutResult = comparisonEngine.layout(
                comparisonStore.text,
                `${typography.weight} ${typography.renderedSize}px "${fontA.name}"`,
                `${typography.weight} ${typography.renderedSize}px "${fontB.name}"`,
                width - padding,
                typography.renderedSize * 1.2,
            );
        }
    };
    window.addEventListener('resize', handleResize);
@@ -156,9 +174,6 @@ const scaleClass = $derived(
 );
 </script>
 <!-- Hidden measurement canvas -->
 <canvas bind:this={measureCanvas} class="hidden" width="1" height="1"></canvas>
 <!--
    Outer flex container — fills parent.
    The paper div inside scales down when the sidebar opens on desktop.
@@ -218,10 +233,10 @@ const scaleClass = $derived(
                            my-auto
                        "
                    >
-                        {#each charComparison.lines as line, lineIndex}
+                        {#each layoutResult.lines as line, lineIndex}
-                            <Line bind:element={lineElements[lineIndex]} text={line.text}>
+                            <Line chars={line.chars}>
                                {#snippet character({ char, index })}
-                                    {@const { proximity, isPast } = charComparison.getCharState(index, sliderPos, lineElements[lineIndex], container)}
+                                    {@const { proximity, isPast } = comparisonEngine.getCharState(lineIndex, index, sliderPos, container?.offsetWidth ?? 0)}
                                    <Character {char} {proximity} {isPast} />
                                {/snippet}
                            </Line>
--- a/src/widgets/FontSearch/ui/FontSearch/FontSearch.svelte
+++ b/src/widgets/FontSearch/ui/FontSearch/FontSearch.svelte
@@ -3,7 +3,7 @@
    Provides a search input and filtration for fonts
 -->
 <script lang="ts">
-import { unifiedFontStore } from '$entities/Font';
+import { fontStore } from '$entities/Font';
 import {
    FilterControls,
    Filters,
@@ -36,7 +36,7 @@ let { showFilters = $bindable(true) }: Props = $props();
 $effect(() => {
    const params = mapManagerToParams(filterManager);
-    untrack(() => unifiedFontStore.setParams(params));
+    untrack(() => fontStore.setParams(params));
 });
 const transform = new Tween(
--- a/src/widgets/SampleList/ui/SampleList/SampleList.svelte
+++ b/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}
--- a/src/widgets/SampleList/ui/SampleListSection/SampleListSection.svelte
+++ b/src/widgets/SampleList/ui/SampleListSection/SampleListSection.svelte
@@ -4,7 +4,7 @@
 -->
 <script lang="ts">
 import { NavigationWrapper } from '$entities/Breadcrumb';
-import { unifiedFontStore } from '$entities/Font';
+import { fontStore } from '$entities/Font';
 import type { ResponsiveManager } from '$shared/lib';
 import { cn } from '$shared/shadcn/utils/shadcn-utils';
 import {
@@ -36,7 +36,7 @@ const responsive = getContext<ResponsiveManager>('responsive');
            id="sample_set"
            title="Sample Set"
            headerTitle="visual_output"
-            headerSubtitle="items_total: {unifiedFontStore.pagination.total ?? 0}"
+            headerSubtitle="items_total: {fontStore.pagination.total ?? 0}"
            headerAction={registerAction}
        >
            {#snippet headerContent()}
--- a/yarn.lock
+++ b/yarn.lock
@@ -122,6 +122,13 @@ __metadata:
  languageName: node
  linkType: hard
 "@chenglou/pretext@npm:^0.0.5":
  version: 0.0.5
  resolution: "@chenglou/pretext@npm:0.0.5"
  checksum: 10c0/5139b39a166fbe7d1e0cf31c95f83125cc0658d8951b19dff3ac14b94d08c2bb53e954801c0325dac79c5b2b21157fa7763e0c561d46773baa37253f1a526242
  languageName: node
  linkType: hard
 "@chromatic-com/storybook@npm:^4.1.3":
  version: 4.1.3
  resolution: "@chromatic-com/storybook@npm:4.1.3"
@@ -2436,6 +2443,7 @@ __metadata:
  version: 0.0.0-use.local
  resolution: "glyphdiff@workspace:."
  dependencies:
    "@chenglou/pretext": "npm:^0.0.5"
    "@chromatic-com/storybook": "npm:^4.1.3"
    "@internationalized/date": "npm:^3.10.0"
    "@lucide/svelte": "npm:^0.561.0"
Author	SHA1	Message	Date
ilia	46d0d887b1	Merge pull request 'feature/unified-tanstack-query' (#36 ) from feature/unified-tanstack-query into main All checks were successful Workflow / build (push) Successful in 45s Details Workflow / publish (push) Successful in 47s Details Reviewed-on: #36	2026-04-16 04:53:28 +00:00
Ilia Mashkov	0a489a8adc	fix(BaseQueryStore): use QueryObserverOptions instead of QueryOptions All checks were successful Workflow / build (pull_request) Successful in 58s Details Workflow / publish (pull_request) Has been skipped Details QueryOptions has queryKey as optional; QueryObserverOptions requires it, matching what QueryObserver.constructor and setOptions actually expect.	2026-04-15 22:37:30 +03:00
Ilia Mashkov	cd349aec92	fix: imports	2026-04-15 22:32:45 +03:00
Ilia Mashkov	adaa6d7648	feat: refactor ComparisonStore to use BatchFontStore Replace hand-rolled async fetching (fetchFontsByIds + isRestoring flag) with BatchFontStore backed by TanStack Query. Three reactive effects handle batch sync, CSS font loading, and default-font fallback. isLoading now derives from batchStore.isLoading + fontsReady.	2026-04-15 22:25:34 +03:00
Ilia Mashkov	10f4781a67	test: enrich coverage for queryKeys, BaseQueryStore, and BatchFontStore - queryKeys: add mutation-safety test for batch(), key hierarchy tests (list/batch/detail keys rooted in their parent base keys), and unique-key test for different detail IDs - BaseQueryStore: add initial-state test (data undefined, isError false before any fetch resolves) - BatchFontStore: add FontResponseError type assertion on malformed response, null error assertion on success, and setIds([]) disables query and returns empty fonts without triggering a fetch	2026-04-15 15:59:01 +03:00
Ilia Mashkov	f4a568832a	feat: implement reactive BatchFontStore	2026-04-15 12:29:16 +03:00
Ilia Mashkov	4e9670118a	feat: add seedFontCache utility	2026-04-15 12:21:04 +03:00
Ilia Mashkov	8e88d1b7cf	feat: add BaseQueryStore for reactive query observers	2026-04-15 12:19:25 +03:00
Ilia Mashkov	1cbc262af7	feat: add stable query key factory	2026-04-15 12:06:32 +03:00
ilia	f072c5b270	Merge pull request 'fix/initial-fonts-loading' (#35 ) from fix/initial-fonts-loading into main All checks were successful Workflow / build (push) Successful in 46s Details Workflow / publish (push) Successful in 45s Details Reviewed-on: #35	2026-04-15 08:37:40 +00:00
Ilia Mashkov	bfa99cde20	fix(comparisonStore): add missing batch request and effect for initial font loading All checks were successful Workflow / build (pull_request) Successful in 3m8s Details Workflow / publish (pull_request) Has been skipped Details	2026-04-15 11:35:37 +03:00
Ilia Mashkov	75b62265be	fix: add missing export	2026-04-15 09:13:22 +03:00
ilia	5b81be6614	Merge pull request 'feature/pretext' (#34 ) from feature/pretext into main Some checks failed Workflow / build (push) Failing after 36s Details Workflow / publish (push) Has been skipped Details Reviewed-on: #34	2026-04-14 07:12:41 +00:00
Ilia Mashkov	a74abbb0b3	feat: wire createFontRowSizeResolver into SampleList for pretext-backed row heights Some checks failed Workflow / build (pull_request) Failing after 49s Details Workflow / publish (pull_request) Has been skipped Details	2026-04-13 13:23:03 +03:00
Ilia Mashkov	20accb9c93	feat: implement createFontRowSizeResolver with canvas-measured heights and reactive status check	2026-04-13 08:54:19 +03:00
Ilia Mashkov	46b9db1db3	feat: export ItemSizeResolver type and document reactive estimateSize contract	2026-04-12 19:43:44 +03:00
Ilia Mashkov	4b017a83bb	fix: add missing JSDoc, return types, and as-any comments to layout engines	2026-04-12 09:51:36 +03:00
Ilia Mashkov	49822f8af7	feat: install pretext library	2026-04-12 09:08:01 +03:00
Ilia Mashkov	338ca9b4fd	feat: export TextLayoutEngine and CharacterComparisonEngine from shared helpers index Remove deleted createCharacterComparison exports and benchmark.	2026-04-11 16:44:49 +03:00
Ilia Mashkov	99f662e2d5	fix: iterate pre-computed chars array in Line.svelte to fix unicode grapheme splitting bug	2026-04-11 16:26:41 +03:00
Ilia Mashkov	5977e0a0dc	fix: correct advances null-check in CharacterComparisonEngine and remove unused TextLayoutEngine dep	2026-04-11 16:14:28 +03:00
Ilia Mashkov	2b0d8470e5	test: fix CharacterComparisonEngine tests — correct env directive, canvas mock, and full spec coverage	2026-04-11 16:14:24 +03:00
Ilia Mashkov	351ee9fd52	docs: add inline documentation to TextLayoutEngine	2026-04-11 16:10:01 +03:00
Ilia Mashkov	a526a51af8	test: fix TextLayoutEngine tests — correct jsdom directive placement and canvas mock setup fix: correct grapheme-width fallback in TextLayoutEngine for null breakableFitAdvances	2026-04-11 15:48:52 +03:00
Ilia Mashkov	fcde78abad	test: add canvas mock helper for pretext-based engine tests	2026-04-11 15:48:47 +03:00
ilia	26737f2f11	Merge pull request 'chore/purge-unused' (#33 ) from chore/purge-unused into main All checks were successful Workflow / build (push) Successful in 45s Details Workflow / publish (push) Successful in 23s Details Reviewed-on: #33	2026-04-10 14:31:27 +00:00
Ilia Mashkov	d9fa2bc501	refactor: consolidate font domain and model types into font.ts All checks were successful Workflow / build (pull_request) Successful in 59s Details Workflow / publish (pull_request) Has been skipped Details	2026-04-10 17:29:15 +03:00
Ilia Mashkov	5f38996665	chore: purge legacy font provider types and normalization logic	2026-04-10 16:05:57 +03:00
ilia	d70fc9f918	Merge pull request 'feat/font-store-merge' (#32 ) from feat/font-store-merge into main All checks were successful Workflow / build (push) Successful in 43s Details Workflow / publish (push) Successful in 21s Details Reviewed-on: #32	2026-04-10 05:13:39 +00:00
Ilia Mashkov	14dbd374ec	refactor: replace unifiedFontStore with fontStore in comparisonStore tests All checks were successful Workflow / build (pull_request) Successful in 1m1s Details Workflow / publish (pull_request) Has been skipped Details	2026-04-10 08:06:51 +03:00
Ilia Mashkov	dc6e15492a	test: mock fontStore and update FontStore type signatures	2026-04-09 19:40:31 +03:00
Ilia Mashkov	45eac0c396	refactor: delete BaseFontStore and UnifiedFontStore — FontStore is the single implementation	2026-04-08 10:07:36 +03:00
Ilia Mashkov	ed7d31bf5c	refactor: migrate all callers from unifiedFontStore to fontStore	2026-04-08 10:00:30 +03:00
Ilia Mashkov	468d2e7f8c	feat(FontStore): export through entity barrel files	2026-04-08 09:55:40 +03:00
Ilia Mashkov	2a761b9d47	feat(FontStore): implement lifecycle, param management, async methods, shortcuts, pagination, category getters, singleton — all tests green	2026-04-08 09:54:27 +03:00
Ilia Mashkov	a9e4633b64	feat(FontStore): implement fetchPage with error wrapping	2026-04-08 09:50:16 +03:00
Ilia Mashkov	778988977f	feat(FontStore): implement state getters, pagination, buildQueryKey, buildOptions	2026-04-08 09:47:25 +03:00
Ilia Mashkov	9a9ff95bf3	test(FontStore): write full TDD spec and empty shell (InfiniteQueryObserver)	2026-04-08 09:43:29 +03:00
Ilia Mashkov	7517678e87	chore: add .worktrees to .gitignore for isolated development	2026-04-08 09:37:47 +03:00
ilia	4281d94d66	Merge pull request 'refactor/code-splitting' (#31 ) from refactor/code-splitting into main All checks were successful Workflow / build (push) Successful in 44s Details Workflow / publish (push) Successful in 42s Details Reviewed-on: #31	2026-04-08 06:34:19 +00:00
Ilia Mashkov	752e38adf9	test: full test coverage of baseFontStore and unifiedFontStore All checks were successful Workflow / build (pull_request) Successful in 55s Details Workflow / publish (pull_request) Has been skipped Details	2026-04-08 09:33:04 +03:00
Ilia Mashkov	9c538069e4	test(UnifiedFontStore): add isEmpty and destroy tests	2026-04-06 12:26:08 +03:00
Ilia Mashkov	71fed58af9	test(UnifiedFontStore): add category getter tests	2026-04-06 12:24:23 +03:00
Ilia Mashkov	fee3355a65	test(UnifiedFontStore): add filter change reset tests	2026-04-06 12:19:49 +03:00
Ilia Mashkov	2ff7f1a13d	test(UnifiedFontStore): add filter setter tests	2026-04-06 11:35:56 +03:00
Ilia Mashkov	6bf1b1ea87	test(UnifiedFontStore): add pagination navigation tests	2026-04-06 11:34:53 +03:00
Ilia Mashkov	3ef012eb43	test(UnifiedFontStore): add pagination state tests	2026-04-06 11:34:03 +03:00
Ilia Mashkov	5df60b236c	test(UnifiedFontStore): cover fetchFn typed error paths and error getter	2026-04-05 15:20:15 +03:00
Ilia Mashkov	df3c694909	feat(UnifiedFontStore): throw FontNetworkError and FontResponseError in fetchFn	2026-04-05 14:07:26 +03:00
Ilia Mashkov	a1a1fcf39d	feat(BaseFontStore): expose error getter	2026-04-05 11:03:00 +03:00
Ilia Mashkov	b40e651be4	refactor(Font/model): move baseFontStore and unifiedFontStore to subdirectories, rename errors/index to errors/errors	2026-04-05 11:02:42 +03:00
Ilia Mashkov	9427f4e50f	feat(Font): re-export FontNetworkError and FontResponseError from entity barrel	2026-04-05 09:33:58 +03:00
Ilia Mashkov	ed9791c176	feat(Font/lib): add FontNetworkError and FontResponseError	2026-04-05 09:04:47 +03:00
Ilia Mashkov	c6dabafd93	chore(appliedFontsStore): move FontBufferCache, FontEvicionPolicy and FontLoadQueue to appliedFontsStore/utils	2026-04-05 08:25:05 +03:00
Ilia Mashkov	e88cca9289	test(FontBufferCache): change mock fetcher type	2026-04-04 16:43:54 +03:00
Ilia Mashkov	d4cf6764b4	test(appliedFontsStore): rewrite tests with describe grouping and full coverage	2026-04-04 10:38:20 +03:00
Ilia Mashkov	5a065ae5a1	refactor: extract #fetchChunk, replace Promise.allSettled with self-describing results	2026-04-04 09:58:41 +03:00
Ilia Mashkov	20110168f2	refactor: extract #processFont and #scheduleProcessing from touch and #processQueue	2026-04-04 09:52:45 +03:00
Ilia Mashkov	f88729cc77	fix: guard AbortError from retry counting; eviction policy removes stale keys	2026-04-04 09:40:21 +03:00
Ilia Mashkov	d21de1bf78	chore(appliedFontsStore): use created collaborators classes	2026-04-03 16:09:10 +03:00
Ilia Mashkov	bc4ab58644	fix(buildQueryString): change the way the searchParams built	2026-04-03 16:08:15 +03:00
Ilia Mashkov	37e0c29788	refactor: loadFont throws FontParseError instead of re-throwing raw error	2026-04-03 15:42:08 +03:00
Ilia Mashkov	46ce0f7aab	feat: extract FontBufferCache with injectable fetcher	2026-04-03 15:24:14 +03:00
Ilia Mashkov	128f341399	feat: extract FontEvictionPolicy with TTL and pin/unpin	2026-04-03 15:06:01 +03:00
Ilia Mashkov	64b97794a6	feat: extract FontLoadQueue with retry tracking	2026-04-03 15:01:36 +03:00
Ilia Mashkov	d6eb02bb28	feat: add FontFetchError and FontParseError typed errors	2026-04-03 14:44:06 +03:00
Ilia Mashkov	a711e4e12a	chore(appliedFontsStore): move generateFontKey into separate function and cover it with tests	2026-04-03 12:50:50 +03:00
Ilia Mashkov	05e4c082ed	feat(appliedFontsStore): move font loading logic into loadFont function and cover it with tests	2026-04-03 12:29:48 +03:00
Ilia Mashkov	b602b5022b	chore(appliedFontsStore): move the FontLoadRequestConfig type and other types from appliedFontsStore into types directory	2026-04-03 12:25:38 +03:00