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