Merge pull request 'feature/pretext' (#34) from feature/pretext into main

Reviewed-on: #34

package.json

@@ -66,6 +66,7 @@
     "vitest-browser-svelte": "^2.0.1"
   },
   "dependencies": {
+    "@chenglou/pretext": "^0.0.5",
     "@tanstack/svelte-query": "^6.0.14"
   }
 }

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,13 +34,9 @@ export {
     MOCK_STORES,
     type MockFilterOptions,
     type MockFilters,
-    mockFontshareFont,
-    type MockFontshareFontOptions,
     type MockFontStoreState,
     // Font mocks
-    mockGoogleFont,
     // Types
-    type MockGoogleFontOptions,
     type MockQueryObserverResult,
     type MockQueryState,
     mockUnifiedFont,
@@ -61,3 +48,6 @@ export {
     FontNetworkError,
     FontResponseError,
 } from './errors/errors';
+
+export { createFontRowSizeResolver } from './sizeResolver/createFontRowSizeResolver';
+export type { FontRowSizeResolverOptions } from './sizeResolver/createFontRowSizeResolver';

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

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
 
 /**

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,

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,
-                },
-            },
-        ],
-    };
-}

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';

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

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

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

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

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

@@ -1,15 +1,7 @@
-/**
- * ============================================================================
- * UNIFIED FONT STORE EXPORTS
- * ============================================================================
- *
- * Single export point for the unified font store infrastructure.
- */
-
-// Applied fonts manager (CSS loading - unchanged)
+// Applied fonts manager
 export { appliedFontsManager } from './appliedFontsStore/appliedFontsStore.svelte';
 
-// Single FontStore (new implementation)
+// Single FontStore
 export {
     createFontStore,
     FontStore,

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';

src/entities/Font/model/types/font.ts

@@ -1,25 +1,85 @@
 /**
- * ============================================================================
- * NORMALIZATION TYPES
- * ============================================================================
+ * Font domain types
+ *
+ * Shared types for font entities across providers (Google, Fontshare).
+ * Includes categories, subsets, weights, and the unified font model.
  */
 
-import type {
-    FontCategory,
-    FontProvider,
-    FontSubset,
-    FontVariant,
-} from './common';
+/**
+ * Unified font category across all providers
+ */
+export type FontCategory =
+    | 'sans-serif'
+    | '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;
-}
-
-export interface FontStyleUrls extends LegacyFontStyleUrls {
+    /** Additional variant mapping */
     variants?: Partial<Record<UnifiedFontVariant, string>>;
 }
 

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;
-}

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>>;

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 {

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

@@ -8,8 +8,8 @@ import type {
     FontCategory,
     FontProvider,
     FontSubset,
-} from './common';
-import type { UnifiedFont } from './normalize';
+    UnifiedFont,
+} from './font';
 
 /**
  * Font collection state

src/entities/Font/ui/FontVirtualList/FontVirtualList.svelte

@@ -18,8 +18,8 @@ import {
     type FontLoadRequestConfig,
     type UnifiedFont,
     appliedFontsManager,
-    fontStore,
 } from '../../model';
+import { fontStore } from '../../model/store';
 
 interface Props extends
     Omit<

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;
+    }
+}

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);
+    });
+});

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,
+        };
+    }
+}

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);
+    });
+});

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),
+    });
+}

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>;

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);
-        });
-    });
-});

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

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

src/shared/lib/helpers/index.ts

@@ -52,10 +52,16 @@ export {
 } from './createEntityStore/createEntityStore.svelte';
 
 export {
-    type CharacterComparison,
-    createCharacterComparison,
-    type LineData,
-} from './createCharacterComparison/createCharacterComparison.svelte';
+    CharacterComparisonEngine,
+    type ComparisonLine,
+    type ComparisonResult,
+} from './CharacterComparisonEngine/CharacterComparisonEngine.svelte';
+
+export {
+    type LayoutLine as TextLayoutLine,
+    type LayoutResult as TextLayoutResult,
+    TextLayoutEngine,
+} from './TextLayoutEngine/TextLayoutEngine.svelte';
 
 export {
     createPersistentStore,

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,

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;
-    /**
-     * DOM element reference
-     */
-    element?: HTMLElement;
+    chars: LineChar[];
     /**
      * Character render snippet
      */
@@ -22,18 +28,15 @@ interface Props {
 }
 const typography = $derived(comparisonStore.typography);
 
-let { text, element = $bindable<HTMLElement>(), character }: Props = $props();
-
-const characters = $derived(text.split(''));
+let { chars, character }: Props = $props();
 </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}
-        {@render character?.({ char, index })}
+    {#each chars as c, index}
+        {@render character?.({ char: c.char, index })}
     {/each}
 </div>

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(
-    () => comparisonStore.text,
-    () => fontA,
-    () => fontB,
-    () => typography.weight,
-    () => typography.renderedSize,
-);
+// New high-performance layout engine
+const comparisonEngine = new CharacterComparisonEngine();
 
-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(() => {
-            charComparison.breakIntoLines(container, measureCanvas);
-        });
+
+    if (container && fontA && fontB) {
+        // 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) {
-            charComparison.breakIntoLines(container, measureCanvas);
+        if (container && fontA && fontB) {
+            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}
-                            <Line bind:element={lineElements[lineIndex]} text={line.text}>
+                        {#each layoutResult.lines as line, lineIndex}
+                            <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>

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}

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"