react-fastload 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,562 @@
+import React from 'react';
+
+/**
+ * Shared type definitions for the ReactFastLoad scheduling engine.
+ *
+ * These types are the contract between the registry, priority engine,
+ * observers, and scheduler. Keep this file dependency-free so it can be
+ * imported from anywhere without pulling in React or DOM-heavy code.
+ */
+type Priority = "CRITICAL" | "HIGH" | "NORMAL" | "LOW" | "IDLE";
+type ResourceType = "image" | "video" | "audio" | "component" | "other";
+type ResourceState = "idle" | "eligible" | "loading" | "loaded" | "error";
+type LoadingStrategy = "eager" | "lazy" | "auto";
+interface ResourceTimestamps {
+    /** When the resource was registered with the registry. */
+    registeredAt: number;
+    /** When the resource became eligible to load (left "idle"). */
+    eligibleAt?: number;
+    /** When the scheduler handed the resource to its loader. */
+    loadStartedAt?: number;
+    /** When loading finished (success or error). */
+    loadEndedAt?: number;
+}
+interface ResourceRecord {
+    id: string;
+    type: ResourceType;
+    priority: Priority;
+    state: ResourceState;
+    /** Estimated byte size, if known (e.g. from a srcset hint, or measured via Resource Timing after load). */
+    estimatedSize?: number;
+    /** Distance from the viewport in pixels at last measurement. <= 0 means intersecting. */
+    viewportDistance?: number;
+    strategy: LoadingStrategy;
+    timestamps: ResourceTimestamps;
+    /** True if the scheduler intentionally delayed this resource past its natural request time. */
+    deferred: boolean;
+    /** True if this resource was proactively prefetched ahead of viewport entry. */
+    prefetched: boolean;
+    /** Arbitrary metadata a resource loader may attach (e.g. natural width/height, video duration). */
+    meta?: Record<string, unknown>;
+    /**
+     * Created once per registry entry (not per mounted component — see
+     * LoadManager's reference counting). A loader may read
+     * `resource.abortController?.signal` to cancel in-flight work; the
+     * registry calls `.abort()` when the LAST consumer of this id
+     * unmounts. `undefined` in environments without AbortController.
+     */
+    abortController?: AbortController;
+}
+type RegisterResourceInput = Pick<ResourceRecord, "id" | "type" | "priority" | "strategy"> & Partial<Pick<ResourceRecord, "estimatedSize" | "meta">>;
+interface SchedulerDecision {
+    resourceId: string;
+    action: "load" | "defer" | "prefetch";
+    reason: string;
+    timestamp: number;
+}
+interface ConnectionInfo {
+    /** Effective connection type, e.g. "4g", "3g", "2g", "slow-2g". Null if unsupported. */
+    effectiveType: string | null;
+    /** Estimated downlink in Mbps. Null if unsupported. */
+    downlink: number | null;
+    /** Estimated round-trip time in ms. Null if unsupported. */
+    rtt: number | null;
+    /** User has requested reduced data usage. */
+    saveData: boolean;
+    /** Whether the Network Information API is supported in this environment. */
+    supported: boolean;
+}
+interface SchedulerOptions {
+    /** Maximum number of resources the scheduler will actively load at once. Default 4. */
+    concurrency?: number;
+    /** Called whenever the scheduler makes a decision about a resource. Used by debug mode. */
+    onDecision?: (decision: SchedulerDecision) => void;
+}
+interface FastLoadDebugSnapshot {
+    resources: ResourceRecord[];
+    decisions: SchedulerDecision[];
+    connection: ConnectionInfo;
+}
+
+interface PriorityContext {
+    connection: ConnectionInfo;
+    /** Preload distance in pixels, as configured on the provider. */
+    preloadDistance: number;
+}
+/**
+ * PriorityEngine turns a resource's declared priority plus live signals
+ * (viewport distance, network conditions) into an *effective* priority
+ * score used purely for ordering within the scheduler. It never mutates
+ * the resource's declared priority — that stays whatever the developer set.
+ */
+declare class PriorityEngine {
+    /**
+     * Lower score = loaded sooner. CRITICAL always sorts first regardless
+     * of other signals, per the "never delay explicitly critical resources"
+     * requirement.
+     */
+    score(resource: ResourceRecord, ctx: PriorityContext): number;
+    compare(a: ResourceRecord, b: ResourceRecord, ctx: PriorityContext): number;
+    isConstrainedConnection(connection: ConnectionInfo): boolean;
+    /** Whether a resource sitting at `distance` px from the viewport should become eligible. */
+    isWithinPreloadZone(distance: number | undefined, preloadDistance: number): boolean;
+}
+
+type Listener = (resources: ResourceRecord[]) => void;
+/**
+ * ResourceRegistry is the single source of truth for every resource
+ * ReactFastLoad knows about. It does not make loading decisions itself —
+ * that's the PriorityEngine and Scheduler's job — it only stores state
+ * and notifies subscribers when that state changes.
+ */
+declare class ResourceRegistry {
+    private resources;
+    private listeners;
+    register(input: RegisterResourceInput): ResourceRecord;
+    unregister(id: string): void;
+    get(id: string): ResourceRecord | undefined;
+    has(id: string): boolean;
+    all(): ResourceRecord[];
+    byState(state: ResourceState): ResourceRecord[];
+    update(id: string, patch: Partial<ResourceRecord>): ResourceRecord | undefined;
+    /**
+     * Returns the CURRENT record after the transition — not the stale
+     * pre-call reference. This matters: a caller that does
+     * `const r = registry.setState(id, "eligible")` must see `r.state ===
+     * "eligible"`, not whatever `r` looked like before this call, since
+     * `update()` replaces the Map entry with a new object rather than
+     * mutating the old one in place. (This exact mismatch was a real bug
+     * in LoadManager.register(), caught by a clean-install runtime smoke
+     * test — see CHANGELOG.) Returns `undefined` only if `id` isn't
+     * registered at all.
+     */
+    setState(id: string, state: ResourceState): ResourceRecord | undefined;
+    setViewportDistance(id: string, distance: number): void;
+    markDeferred(id: string): void;
+    markPrefetched(id: string): void;
+    subscribe(listener: Listener): () => void;
+    clear(): void;
+    /** Aggregate counters used by the metrics layer. Pure derived data, no side effects. */
+    summary(): {
+        totalRequests: number;
+        initialRequests: number;
+        deferredRequests: number;
+        deferredResources: number;
+        bytesDeferred: number;
+        imagesDeferred: number;
+        videosDeferred: number;
+        audiosDeferred: number;
+        componentsDeferred: number;
+    };
+    private emit;
+}
+
+type LoaderFn = (resource: ResourceRecord) => Promise<void>;
+interface RunOptions {
+    ctx: PriorityContext;
+}
+/**
+ * Scheduler is the central coordinator described in the architecture:
+ *
+ *   Registry -> PriorityEngine -> signals -> Scheduler -> loading decision
+ *
+ * It owns no DOM logic and knows nothing about images/video/components —
+ * it only decides, given the current registry state and priority scores,
+ * which *eligible* resources get a loader slot right now, respecting a
+ * concurrency cap so competing requests don't starve visible content.
+ *
+ * Loaders are registered per resource type by the resources/* modules and
+ * invoked by the scheduler when it decides to load a resource.
+ */
+declare class Scheduler {
+    private registry;
+    private priorityEngine;
+    private concurrency;
+    private onDecision?;
+    private activeCount;
+    private loaders;
+    private decisions;
+    private readonly maxDecisionLog;
+    private scheduled;
+    constructor(registry: ResourceRegistry, priorityEngine: PriorityEngine, options?: SchedulerOptions);
+    /** Register the function used to actually load a given resource id (called once per resource). */
+    registerLoader(resourceId: string, loader: LoaderFn): void;
+    unregisterLoader(resourceId: string): void;
+    /**
+     * Request a scheduling pass. Coalesced into a microtask so multiple
+     * rapid registry updates (e.g. many IntersectionObserver callbacks in
+     * one frame) only trigger a single pass.
+     */
+    requestPass(ctx: PriorityContext): void;
+    /** Synchronous scheduling pass, exposed directly for tests and advanced use. */
+    runPass({ ctx }: RunOptions): void;
+    private dispatch;
+    /** Explicitly defer a resource (used by observers when it leaves the preload zone again, or on slow connections). */
+    defer(resourceId: string, reason: string): void;
+    prefetch(resourceId: string, reason: string): void;
+    getDecisionLog(): SchedulerDecision[];
+    private record;
+}
+
+type ViewportCallback = (distance: number, isIntersecting: boolean) => void;
+/**
+ * Thin, testable wrapper around IntersectionObserver.
+ *
+ * Rather than only exposing a boolean "is it visible", this computes an
+ * approximate pixel distance from the viewport so the PriorityEngine can
+ * rank near-viewport resources ahead of far-off ones, and so `rootMargin`
+ * (the preload distance) can be configured per observer instance.
+ *
+ * Falls back to reporting elements as immediately eligible when
+ * IntersectionObserver isn't supported (very old browsers, some SSR/test
+ * environments) — a graceful degrade rather than a crash, per the
+ * "progressive enhancement" requirement.
+ */
+declare class ViewportObserver {
+    private observer?;
+    private callbacks;
+    private preloadDistance;
+    constructor(preloadDistance?: number);
+    observe(element: Element, callback: ViewportCallback): void;
+    unobserve(element: Element): void;
+    disconnect(): void;
+    private handleEntries;
+}
+
+interface LoadManagerOptions {
+    preloadDistance?: number;
+    concurrency?: number;
+    debug?: boolean;
+}
+/**
+ * LoadManager wires together the registry, priority engine, and scheduler
+ * into the single object that FastLoadProvider creates and shares via
+ * context. This is the "central intellectual component" the architecture
+ * calls for — resource wrappers (SmartImage, SmartVideo, LazyComponent)
+ * only ever talk to a LoadManager instance, never to the DOM-observation
+ * or scheduling internals directly.
+ *
+ * Two behaviors worth calling out because they're easy to get wrong:
+ *
+ * 1. Request deduplication: `register()` is reference-counted. Two
+ *    mounted components that resolve to the SAME resource id (by default,
+ *    `${type}:${src}` — see SmartImage/SmartVideo/SmartAudio) share ONE
+ *    registry entry, one loader call, and one AbortController. The entry
+ *    is only actually removed — and its AbortController only actually
+ *    aborted — once every consumer has unregistered. Without this, an
+ *    id reused by two instances would let the first unmount delete a
+ *    resource the second instance still depends on.
+ * 2. Viewport observation is centralized here as ONE shared
+ *    IntersectionObserver for the whole provider, not one per resource.
+ *    An earlier version had each `useLazyLoad` call create its own
+ *    ViewportObserver — harmless correctness-wise, but wasteful: a page
+ *    with 50 resources was creating 50 separate native
+ *    IntersectionObserver instances all doing the same kind of work.
+ */
+declare class LoadManager {
+    readonly registry: ResourceRegistry;
+    readonly priorityEngine: PriorityEngine;
+    readonly scheduler: Scheduler;
+    readonly viewportObserver: ViewportObserver;
+    readonly preloadDistance: number;
+    readonly debug: boolean;
+    private connection;
+    private unsubscribeConnection?;
+    private refCounts;
+    constructor(options?: LoadManagerOptions);
+    register(input: RegisterResourceInput): ResourceRecord;
+    /**
+     * Decrements the id's reference count. Only when it reaches zero — i.e.
+     * the last mounted consumer of this resource has unmounted — does this
+     * actually abort any in-flight load, remove the scheduler's loader, and
+     * delete the registry entry. See the class doc for why.
+     */
+    unregister(id: string): void;
+    setLoader(id: string, loader: LoaderFn): void;
+    /**
+     * Attaches the shared ViewportObserver to an element for a given
+     * resource id. Returns an unobserve function. A no-op (returning a
+     * no-op cleanup) for resources that skip viewport gating — callers
+     * don't need to branch on that themselves.
+     */
+    observeViewport(id: string, element: Element): () => void;
+    /** Called whenever a resource's distance-from-viewport changes. */
+    reportViewportDistance(id: string, distance: number): void;
+    requestPass(): void;
+    getConnection(): ConnectionInfo;
+    getDebugSnapshot(): FastLoadDebugSnapshot;
+    setPriority(id: string, priority: Priority): void;
+    destroy(): void;
+    private logDecision;
+}
+
+interface WebVitalsSnapshot {
+    /** First Contentful Paint, in ms. null until observed or if unsupported. */
+    fcp: number | null;
+    /** Largest Contentful Paint, in ms. Updates as later, larger candidates appear. */
+    lcp: number | null;
+    /** Cumulative Layout Shift score (unitless). Accumulates for the page's lifetime. */
+    cls: number | null;
+}
+
+/**
+ * The metrics object returned by useFastLoadMetrics().
+ *
+ * Every field is documented with where its value actually comes from.
+ * Nothing here is fabricated: browser-observed fields are `null` until
+ * the browser has actually reported them, and internal counters are
+ * derived directly from the registry's bookkeeping (never guessed).
+ */
+interface FastLoadMetrics {
+    /** First Contentful Paint in ms. Browser-observed. */
+    fcp: number | null;
+    /** Largest Contentful Paint in ms. Browser-observed; may update as the page loads. */
+    lcp: number | null;
+    /** Cumulative Layout Shift score. Browser-observed. */
+    cls: number | null;
+    /** Time to first byte in ms, from Navigation Timing. Browser-observed. */
+    ttfb: number | null;
+    /** Total resources loaded for the page per the Resource Timing API. Browser-observed. */
+    totalResourcesObserved: number;
+    /** Total bytes transferred per Resource Timing (0 when transferSize is unavailable, e.g. opaque cross-origin responses). Browser-observed. */
+    totalTransferBytesObserved: number;
+    /** Resources registered with ReactFastLoad that were NOT deferred (loaded on initial pass). Internal. */
+    initialRequests: number;
+    /** Resources registered with ReactFastLoad that the scheduler deferred past their natural load time. Internal. */
+    deferredRequests: number;
+    /** Same as deferredRequests; kept for API clarity per the requested shape. Internal. */
+    deferredResources: number;
+    /** Sum of estimatedSize across deferred resources. This is an ESTIMATE — see estimatedSize on each resource. Estimated. */
+    bytesDeferred: number;
+    imagesDeferred: number;
+    videosDeferred: number;
+    audiosDeferred: number;
+    componentsDeferred: number;
+}
+/**
+ * MetricsCollector composes browser-observed Web Vitals / Resource Timing
+ * with the LoadManager's internal registry counters into one snapshot.
+ * It never blends the two categories into a single "score" — the
+ * distinction is preserved field-by-field, per the module's core
+ * requirement not to present estimates as measurements.
+ */
+declare class MetricsCollector {
+    private loadManager;
+    private webVitals;
+    private started;
+    constructor(loadManager: LoadManager);
+    start(): void;
+    stop(): void;
+    subscribeWebVitals(listener: (snapshot: WebVitalsSnapshot) => void): () => void;
+    snapshot(): FastLoadMetrics;
+}
+
+interface FastLoadContextValue {
+    loadManager: LoadManager;
+    metricsCollector: MetricsCollector;
+    debug: boolean;
+}
+interface FastLoadProviderProps {
+    children: React.ReactNode;
+    /**
+     * "adaptive" (default) lets the scheduler weigh viewport distance,
+     * connection quality, and priority together. "eager" raises the
+     * effective floor so more resources load sooner (useful for
+     * low-resource-count pages where deferral has little benefit).
+     * "conservative" is the inverse — favors deferring anything not
+     * CRITICAL/HIGH, useful for resource-heavy pages on constrained devices.
+     */
+    strategy?: "adaptive" | "eager" | "conservative";
+    preloadDistance?: number;
+    concurrency?: number;
+    /** Enables the developer debug overlay/console reporting described in the docs. */
+    debug?: boolean;
+}
+/**
+ * FastLoadProvider initializes the resource registry, scheduler, and
+ * metrics collector for the subtree, and makes them available to
+ * SmartImage/SmartVideo/LazyComponent/hooks via context. There is exactly
+ * one LoadManager per provider instance — nesting providers creates
+ * independent scheduling domains, which is intentional (e.g. for
+ * micro-frontends) but not required for typical use.
+ */
+declare function FastLoadProvider({ children, strategy, preloadDistance, concurrency, debug, }: FastLoadProviderProps): React.JSX.Element;
+declare function useFastLoadContext(): FastLoadContextValue;
+
+type PriorityProp = Priority | "auto";
+interface SmartImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "placeholder" | "onLoad" | "onError"> {
+    src: string;
+    /** "auto" (default) resolves to NORMAL; pass an explicit Priority to override the scheduler's ranking. */
+    priority?: PriorityProp;
+    /** Shown while `src` is loading/deferred. Rendered as a background-image so layout doesn't depend on it loading. */
+    placeholder?: string;
+    /** Explicit id for scheduler bookkeeping/debugging. Defaults to `src`. */
+    resourceId?: string;
+    /** "eager" skips viewport gating entirely (use for above-the-fold images). "lazy" (default) waits for the preload zone. "auto" behaves like "lazy" but lets CRITICAL priority still force eager. */
+    strategy?: LoadingStrategy;
+    /** Estimated byte size, used only for the bytesDeferred metric — never affects loading behavior. */
+    estimatedSize?: number;
+    onLoad?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+    onError?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+}
+/**
+ * A drop-in <img> replacement that registers with the ReactFastLoad
+ * scheduler instead of relying solely on the browser's native
+ * `loading="lazy"`. This adds real value over native lazy loading in two
+ * ways: (1) a configurable preload distance shared across every resource
+ * type via one scheduler, and (2) priority-aware concurrency — so, e.g.,
+ * five LOW-priority images entering view at once don't compete with a
+ * HIGH-priority one for the same network queue.
+ *
+ * For CRITICAL/HIGH priority images with strategy="eager", this renders a
+ * plain <img> immediately — it deliberately does NOT duplicate
+ * `loading="lazy"` for resources that shouldn't be lazy at all.
+ */
+declare function SmartImage({ src, priority, placeholder, resourceId, strategy, estimatedSize, alt, decoding, style, onLoad, onError, ...rest }: SmartImageProps): React.JSX.Element;
+
+interface SmartVideoProps extends Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "src" | "poster" | "preload"> {
+    src: string;
+    poster?: string;
+    priority?: PriorityProp;
+    resourceId?: string;
+    strategy?: LoadingStrategy;
+    /** Estimated byte size (the full video, not just the poster), used only for the bytesDeferred metric — never affects loading behavior. */
+    estimatedSize?: number;
+    /**
+     * CSS `aspect-ratio` (e.g. `"16/9"`) reserved for BOTH the pre-eligible
+     * placeholder and the real `<video>` element, so swapping between them
+     * doesn't change the element's box size — that mismatch is a real
+     * layout-shift (CLS) source if left to each render its own default
+     * height. Omit only if you're already reserving space yourself via a
+     * wrapping container.
+     */
+    aspectRatio?: string;
+    /**
+     * Explicit autoplay request. Unlike the native `autoPlay` attribute,
+     * this is only honored once the resource has actually become eligible
+     * (in view / eager), so a below-the-fold "autoplay" video never
+     * silently starts downloading and playing off-screen.
+     */
+    autoplay?: boolean;
+}
+/**
+ * A <video> wrapper that avoids downloading video data before it's
+ * needed. Below the preload zone, it renders only the poster (if given)
+ * with `preload="none"`; once eligible, it mounts a real <video> with
+ * `preload="metadata"` (or "auto" for CRITICAL/HIGH priority) and, if
+ * `autoplay` was requested, attempts to play once mounted.
+ *
+ * We never fetch the video bytes ourselves — the browser's own
+ * range-request/streaming behavior handles that once the element mounts,
+ * per the "work with browser-native mechanisms" requirement.
+ */
+declare function SmartVideo({ src, poster, priority, resourceId, strategy, estimatedSize, aspectRatio, autoplay, muted, controls, style, ...rest }: SmartVideoProps): React.JSX.Element;
+
+interface SmartAudioProps extends Omit<React.AudioHTMLAttributes<HTMLAudioElement>, "src" | "preload"> {
+    src: string;
+    priority?: PriorityProp;
+    resourceId?: string;
+    strategy?: LoadingStrategy;
+    /** Estimated byte size, used only for the bytesDeferred metric — never affects loading behavior. */
+    estimatedSize?: number;
+    /** Track title, shown on the pre-eligible placeholder's play affordance. Optional. */
+    label?: string;
+    /**
+     * Same semantics as SmartVideo's `autoplay`: only honored once the
+     * resource is actually eligible, and implies `muted` — most browsers
+     * block unmuted audio autoplay outright, so this exists mainly for
+     * background/ambient-track use cases where that's acceptable.
+     */
+    autoplay?: boolean;
+}
+/**
+ * An <audio> wrapper for songs/podcasts/sound effects — the audio
+ * equivalent of SmartVideo. Below the preload zone it renders a small
+ * click/keyboard-activatable placeholder instead of a real <audio>
+ * element, so nothing downloads early. Once eligible, it mounts a real
+ * <audio> with `preload="auto"` for CRITICAL/HIGH priority or
+ * `preload="metadata"` otherwise, and lets the browser's own streaming
+ * behavior handle the actual byte transfer — this library never fetches
+ * audio data itself.
+ */
+declare function SmartAudio({ src, priority, resourceId, strategy, estimatedSize, label, autoplay, muted, controls, ...rest }: SmartAudioProps): React.JSX.Element;
+
+type DynamicImport<T> = () => Promise<{
+    default: T;
+}>;
+
+interface LazyComponentOptions {
+    priority?: Priority;
+    /** Overrides the provider's preloadDistance for this component only. Currently informational — actual gating uses the provider's shared observer distance; a per-instance override is planned for a future minor version. */
+    preloadDistance?: number;
+    strategy?: LoadingStrategy;
+    /** Rendered while the component hasn't become eligible to load yet. Defaults to null (renders nothing). */
+    placeholder?: React.ReactNode;
+    /** Rendered by Suspense while the dynamic import is in flight. Defaults to `placeholder`. */
+    fallback?: React.ReactNode;
+    resourceId?: string;
+    /** Estimated byte size of the chunk this component imports, used only for the bytesDeferred metric — never affects loading behavior. */
+    estimatedSize?: number;
+}
+/**
+ * Wraps React.lazy + Suspense so that the dynamic import() itself is not
+ * triggered until the scheduler decides this component is eligible
+ * (in the preload zone, or eager/CRITICAL). Plain React.lazy has no
+ * concept of "not yet" — it fetches as soon as it's first rendered. This
+ * is the actual gap LazyComponent closes over ordinary code splitting.
+ */
+declare function lazyComponent<P extends object>(importFn: DynamicImport<React.ComponentType<P>>, options?: LazyComponentOptions): React.ComponentType<P>;
+
+interface UseLazyLoadOptions {
+    id: string;
+    type: ResourceType;
+    priority: Priority;
+    strategy: LoadingStrategy;
+    estimatedSize?: number;
+    meta?: Record<string, unknown>;
+    /** The actual load function (e.g. loadImage, loadVideo, dynamic import wrapper). */
+    loader: LoaderFn;
+}
+interface UseLazyLoadResult {
+    /** Attach to the DOM node whose viewport position should be observed. */
+    ref: (node: Element | null) => void;
+    state: ResourceState;
+    record: ResourceRecord | undefined;
+}
+/**
+ * Shared internal hook: registers a resource with the LoadManager, wires
+ * viewport observation up to the provider's single shared
+ * ViewportObserver (unless the strategy is "eager", which skips
+ * observation entirely and loads immediately), and tracks the resource's
+ * state for re-rendering. SmartImage, SmartVideo, and SmartAudio are thin
+ * wrappers around this hook plus their own rendering concerns.
+ *
+ * Request deduplication: `id` defaults to `${type}:${src}` in the Smart*
+ * components, so two mounted instances with the same `src` resolve to the
+ * SAME resource id here — LoadManager.register()/unregister() are
+ * reference-counted specifically so that works correctly (the resource
+ * isn't torn down until the LAST consumer unmounts). Pass an explicit
+ * `resourceId` to opt out when two elements with the same src genuinely
+ * need independent scheduling.
+ */
+declare function useLazyLoad(options: UseLazyLoadOptions): UseLazyLoadResult;
+
+/**
+ * Lets a component update a registered resource's priority after the
+ * fact — e.g. bumping an image from LOW to HIGH once the user hovers
+ * over a card, or once a carousel slide becomes the active one.
+ */
+declare function usePriority(resourceId: string, priority: Priority): void;
+
+/**
+ * Returns a live-updating FastLoadMetrics snapshot. Re-renders when:
+ * - a browser Web Vitals entry arrives (FCP/LCP/CLS), or
+ * - the resource registry changes (a resource loads, defers, etc.)
+ *
+ * The returned object always reflects real state at the time of the
+ * render that produced it — see FastLoadMetrics' field-level docs for
+ * which values are browser-observed vs. internal bookkeeping.
+ */
+declare function useFastLoadMetrics(): FastLoadMetrics;
+
+export { type ConnectionInfo, type FastLoadContextValue, type FastLoadDebugSnapshot, type FastLoadMetrics, FastLoadProvider, type FastLoadProviderProps, type LazyComponentOptions, LoadManager, type LoadingStrategy, type Priority, PriorityEngine, type PriorityProp, type ResourceRecord, ResourceRegistry, type ResourceState, type ResourceType, Scheduler, type SchedulerDecision, SmartAudio, type SmartAudioProps, SmartImage, type SmartImageProps, SmartVideo, type SmartVideoProps, type UseLazyLoadOptions, type UseLazyLoadResult, type WebVitalsSnapshot, lazyComponent, useFastLoadContext, useFastLoadMetrics, useLazyLoad, usePriority };