react-fastload 0.1.0

package/dist/index.js

@@ -0,0 +1,1330 @@
+import React5, { createContext, useRef, useEffect, useMemo, useContext, useState, useId, Suspense } from 'react';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+// src/components/FastLoadProvider.tsx
+
+// src/core/PriorityEngine.ts
+var PRIORITY_ORDER = {
+  CRITICAL: 0,
+  HIGH: 1,
+  NORMAL: 2,
+  LOW: 3,
+  IDLE: 4
+};
+var PriorityEngine = class {
+  /**
+   * Lower score = loaded sooner. CRITICAL always sorts first regardless
+   * of other signals, per the "never delay explicitly critical resources"
+   * requirement.
+   */
+  score(resource, ctx) {
+    if (resource.priority === "CRITICAL") return -Infinity;
+    let score = PRIORITY_ORDER[resource.priority] * 1e3;
+    const distance = resource.viewportDistance;
+    if (typeof distance === "number") {
+      score += Math.max(distance, 0) / 10;
+    } else {
+      score += 500;
+    }
+    if (this.isConstrainedConnection(ctx.connection)) {
+      if (resource.priority === "LOW" || resource.priority === "IDLE") {
+        score += 2e3;
+      }
+    }
+    return score;
+  }
+  compare(a, b, ctx) {
+    return this.score(a, ctx) - this.score(b, ctx);
+  }
+  isConstrainedConnection(connection) {
+    if (connection.saveData) return true;
+    if (!connection.supported) return false;
+    if (connection.effectiveType === "slow-2g" || connection.effectiveType === "2g") {
+      return true;
+    }
+    if (typeof connection.downlink === "number" && connection.downlink > 0 && connection.downlink < 1.5) {
+      return true;
+    }
+    return false;
+  }
+  /** Whether a resource sitting at `distance` px from the viewport should become eligible. */
+  isWithinPreloadZone(distance, preloadDistance) {
+    if (typeof distance !== "number") return false;
+    return distance <= preloadDistance;
+  }
+};
+
+// src/core/ResourceRegistry.ts
+var ResourceRegistry = class {
+  constructor() {
+    this.resources = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  register(input) {
+    const existing = this.resources.get(input.id);
+    if (existing) {
+      return existing;
+    }
+    const record = {
+      id: input.id,
+      type: input.type,
+      priority: input.priority,
+      strategy: input.strategy,
+      state: "idle",
+      estimatedSize: input.estimatedSize,
+      meta: input.meta,
+      deferred: false,
+      prefetched: false,
+      abortController: typeof AbortController !== "undefined" ? new AbortController() : void 0,
+      timestamps: {
+        registeredAt: now()
+      }
+    };
+    this.resources.set(input.id, record);
+    this.emit();
+    return record;
+  }
+  unregister(id) {
+    if (this.resources.delete(id)) {
+      this.emit();
+    }
+  }
+  get(id) {
+    return this.resources.get(id);
+  }
+  has(id) {
+    return this.resources.has(id);
+  }
+  all() {
+    return Array.from(this.resources.values());
+  }
+  byState(state) {
+    return this.all().filter((r) => r.state === state);
+  }
+  update(id, patch) {
+    const record = this.resources.get(id);
+    if (!record) return void 0;
+    const updated = {
+      ...record,
+      ...patch,
+      timestamps: { ...record.timestamps, ...patch.timestamps }
+    };
+    this.resources.set(id, updated);
+    this.emit();
+    return updated;
+  }
+  /**
+   * 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, state) {
+    const record = this.resources.get(id);
+    if (!record) return void 0;
+    if (record.state === state) return record;
+    const timestamps = { ...record.timestamps };
+    const t = now();
+    if (state === "eligible" && !timestamps.eligibleAt) timestamps.eligibleAt = t;
+    if (state === "loading" && !timestamps.loadStartedAt) timestamps.loadStartedAt = t;
+    if ((state === "loaded" || state === "error") && !timestamps.loadEndedAt) {
+      timestamps.loadEndedAt = t;
+    }
+    return this.update(id, { state, timestamps });
+  }
+  setViewportDistance(id, distance) {
+    this.update(id, { viewportDistance: distance });
+  }
+  markDeferred(id) {
+    this.update(id, { deferred: true });
+  }
+  markPrefetched(id) {
+    this.update(id, { prefetched: true });
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  clear() {
+    this.resources.clear();
+    this.emit();
+  }
+  /** Aggregate counters used by the metrics layer. Pure derived data, no side effects. */
+  summary() {
+    var _a;
+    const all = this.all();
+    let deferredRequests = 0;
+    let bytesDeferred = 0;
+    let imagesDeferred = 0;
+    let videosDeferred = 0;
+    let audiosDeferred = 0;
+    let componentsDeferred = 0;
+    for (const r of all) {
+      if (r.deferred) {
+        deferredRequests += 1;
+        bytesDeferred += (_a = r.estimatedSize) != null ? _a : 0;
+        if (r.type === "image") imagesDeferred += 1;
+        if (r.type === "video") videosDeferred += 1;
+        if (r.type === "audio") audiosDeferred += 1;
+        if (r.type === "component") componentsDeferred += 1;
+      }
+    }
+    return {
+      totalRequests: all.length,
+      initialRequests: all.filter((r) => !r.deferred).length,
+      deferredRequests,
+      deferredResources: deferredRequests,
+      bytesDeferred,
+      imagesDeferred,
+      videosDeferred,
+      audiosDeferred,
+      componentsDeferred
+    };
+  }
+  emit() {
+    const snapshot = this.all();
+    for (const listener of this.listeners) listener(snapshot);
+  }
+};
+function now() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+
+// src/core/Scheduler.ts
+var Scheduler = class {
+  constructor(registry, priorityEngine, options = {}) {
+    this.registry = registry;
+    this.priorityEngine = priorityEngine;
+    this.activeCount = 0;
+    this.loaders = /* @__PURE__ */ new Map();
+    this.decisions = [];
+    this.maxDecisionLog = 200;
+    this.scheduled = false;
+    var _a;
+    this.concurrency = (_a = options.concurrency) != null ? _a : 4;
+    this.onDecision = options.onDecision;
+  }
+  /** Register the function used to actually load a given resource id (called once per resource). */
+  registerLoader(resourceId, loader) {
+    this.loaders.set(resourceId, loader);
+  }
+  unregisterLoader(resourceId) {
+    this.loaders.delete(resourceId);
+  }
+  /**
+   * 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) {
+    if (this.scheduled) return;
+    this.scheduled = true;
+    queueMicrotask(() => {
+      this.scheduled = false;
+      this.runPass({ ctx });
+    });
+  }
+  /** Synchronous scheduling pass, exposed directly for tests and advanced use. */
+  runPass({ ctx }) {
+    const eligible = this.registry.byState("eligible").slice().sort((a, b) => this.priorityEngine.compare(a, b, ctx));
+    let freeSlots = this.concurrency - this.activeCount;
+    if (freeSlots <= 0) return;
+    for (const resource of eligible) {
+      if (freeSlots <= 0) break;
+      const loader = this.loaders.get(resource.id);
+      if (!loader) continue;
+      freeSlots -= 1;
+      this.dispatch(resource, loader);
+    }
+  }
+  dispatch(resource, loader) {
+    var _a;
+    this.activeCount += 1;
+    this.registry.setState(resource.id, "loading");
+    this.record({
+      resourceId: resource.id,
+      action: "load",
+      reason: `priority=${resource.priority} distance=${(_a = resource.viewportDistance) != null ? _a : "unknown"}`,
+      timestamp: nowMs()
+    });
+    loader(resource).then(() => {
+      this.registry.setState(resource.id, "loaded");
+    }).catch(() => {
+      this.registry.setState(resource.id, "error");
+    }).finally(() => {
+      this.activeCount -= 1;
+      this.unregisterLoader(resource.id);
+    });
+  }
+  /** Explicitly defer a resource (used by observers when it leaves the preload zone again, or on slow connections). */
+  defer(resourceId, reason) {
+    this.registry.markDeferred(resourceId);
+    this.record({ resourceId, action: "defer", reason, timestamp: nowMs() });
+  }
+  prefetch(resourceId, reason) {
+    this.registry.markPrefetched(resourceId);
+    this.record({ resourceId, action: "prefetch", reason, timestamp: nowMs() });
+  }
+  getDecisionLog() {
+    return this.decisions.slice();
+  }
+  record(decision) {
+    var _a;
+    this.decisions.push(decision);
+    if (this.decisions.length > this.maxDecisionLog) {
+      this.decisions.shift();
+    }
+    (_a = this.onDecision) == null ? void 0 : _a.call(this, decision);
+  }
+};
+function nowMs() {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+
+// src/utils/browserSupport.ts
+var isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+function supportsIntersectionObserver() {
+  return isBrowser && typeof window.IntersectionObserver === "function";
+}
+function supportsPerformanceObserver() {
+  return isBrowser && typeof PerformanceObserver !== "undefined";
+}
+function supportsNavigationTiming() {
+  return isBrowser && typeof performance !== "undefined" && typeof performance.getEntriesByType === "function";
+}
+function supportsNetworkInformation() {
+  return isBrowser && "connection" in navigator;
+}
+function supportsFetchPriority() {
+  if (!isBrowser) return false;
+  const img = document.createElement("img");
+  return "fetchPriority" in img;
+}
+
+// src/observers/ViewportObserver.ts
+var ViewportObserver = class {
+  constructor(preloadDistance = 1e3) {
+    this.callbacks = /* @__PURE__ */ new Map();
+    this.preloadDistance = preloadDistance;
+    if (supportsIntersectionObserver()) {
+      this.observer = new IntersectionObserver(
+        (entries) => this.handleEntries(entries),
+        {
+          root: null,
+          rootMargin: `${preloadDistance}px`,
+          threshold: [0, 0.01, 0.5, 1]
+        }
+      );
+    }
+  }
+  observe(element, callback) {
+    this.callbacks.set(element, callback);
+    if (!this.observer) {
+      callback(0, true);
+      return;
+    }
+    this.observer.observe(element);
+  }
+  unobserve(element) {
+    var _a;
+    this.callbacks.delete(element);
+    (_a = this.observer) == null ? void 0 : _a.unobserve(element);
+  }
+  disconnect() {
+    var _a;
+    (_a = this.observer) == null ? void 0 : _a.disconnect();
+    this.callbacks.clear();
+  }
+  handleEntries(entries) {
+    for (const entry of entries) {
+      const callback = this.callbacks.get(entry.target);
+      if (!callback) continue;
+      const distance = estimateDistance(entry);
+      callback(distance, entry.isIntersecting);
+    }
+  }
+};
+function estimateDistance(entry) {
+  if (entry.isIntersecting) return 0;
+  const target = entry.boundingClientRect;
+  const root = entry.rootBounds;
+  if (!root) {
+    return Number.POSITIVE_INFINITY;
+  }
+  if (target.bottom < root.top) return root.top - target.bottom;
+  if (target.top > root.bottom) return target.top - root.bottom;
+  if (target.right < root.left) return root.left - target.right;
+  if (target.left > root.right) return target.left - root.right;
+  return 0;
+}
+
+// src/utils/connection.ts
+function getConnectionApi() {
+  var _a, _b;
+  if (!isBrowser) return void 0;
+  const nav = navigator;
+  return (_b = (_a = nav.connection) != null ? _a : nav.mozConnection) != null ? _b : nav.webkitConnection;
+}
+function getConnectionInfo() {
+  var _a, _b;
+  const conn = getConnectionApi();
+  const supported = supportsNetworkInformation() && !!conn;
+  if (!supported || !conn) {
+    return {
+      effectiveType: null,
+      downlink: null,
+      rtt: null,
+      saveData: false,
+      supported: false
+    };
+  }
+  return {
+    effectiveType: (_a = conn.effectiveType) != null ? _a : null,
+    downlink: typeof conn.downlink === "number" ? conn.downlink : null,
+    rtt: typeof conn.rtt === "number" ? conn.rtt : null,
+    saveData: (_b = conn.saveData) != null ? _b : false,
+    supported: true
+  };
+}
+function subscribeToConnectionChange(onChange) {
+  const conn = getConnectionApi();
+  if (!conn || typeof conn.addEventListener !== "function") {
+    return () => {
+    };
+  }
+  const handler = () => onChange(getConnectionInfo());
+  conn.addEventListener("change", handler);
+  return () => {
+    var _a;
+    return (_a = conn.removeEventListener) == null ? void 0 : _a.call(conn, "change", handler);
+  };
+}
+
+// src/core/LoadManager.ts
+var LoadManager = class {
+  constructor(options = {}) {
+    this.refCounts = /* @__PURE__ */ new Map();
+    var _a, _b, _c;
+    this.preloadDistance = (_a = options.preloadDistance) != null ? _a : 1e3;
+    this.debug = (_b = options.debug) != null ? _b : false;
+    this.registry = new ResourceRegistry();
+    this.priorityEngine = new PriorityEngine();
+    this.viewportObserver = new ViewportObserver(this.preloadDistance);
+    this.connection = getConnectionInfo();
+    this.scheduler = new Scheduler(this.registry, this.priorityEngine, {
+      concurrency: (_c = options.concurrency) != null ? _c : 4,
+      onDecision: this.debug ? (d) => this.logDecision(d) : void 0
+    });
+    this.unsubscribeConnection = subscribeToConnectionChange((info) => {
+      this.connection = info;
+      this.requestPass();
+    });
+  }
+  register(input) {
+    var _a, _b;
+    const refCount = ((_a = this.refCounts.get(input.id)) != null ? _a : 0) + 1;
+    this.refCounts.set(input.id, refCount);
+    let record = this.registry.register(input);
+    if (input.strategy === "eager" || input.priority === "CRITICAL") {
+      record = (_b = this.registry.setState(record.id, "eligible")) != null ? _b : record;
+      this.requestPass();
+    }
+    return record;
+  }
+  /**
+   * 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) {
+    var _a, _b;
+    const remaining = ((_a = this.refCounts.get(id)) != null ? _a : 1) - 1;
+    if (remaining > 0) {
+      this.refCounts.set(id, remaining);
+      return;
+    }
+    this.refCounts.delete(id);
+    const record = this.registry.get(id);
+    if (record && record.state !== "loaded" && record.state !== "error") {
+      (_b = record.abortController) == null ? void 0 : _b.abort();
+    }
+    this.scheduler.unregisterLoader(id);
+    this.registry.unregister(id);
+  }
+  setLoader(id, loader) {
+    this.scheduler.registerLoader(id, loader);
+    this.requestPass();
+  }
+  /**
+   * 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, element) {
+    const callback = (distance) => this.reportViewportDistance(id, distance);
+    this.viewportObserver.observe(element, callback);
+    return () => this.viewportObserver.unobserve(element);
+  }
+  /** Called whenever a resource's distance-from-viewport changes. */
+  reportViewportDistance(id, distance) {
+    const record = this.registry.get(id);
+    if (!record) return;
+    this.registry.setViewportDistance(id, distance);
+    if (record.state === "idle") {
+      const withinZone = this.priorityEngine.isWithinPreloadZone(distance, this.preloadDistance);
+      if (withinZone) {
+        this.registry.setState(id, "eligible");
+        if (distance > 0) {
+          this.scheduler.prefetch(id, `entered preload zone at ${Math.round(distance)}px`);
+        }
+      } else {
+        this.scheduler.defer(id, `outside preload zone (${Math.round(distance)}px > ${this.preloadDistance}px)`);
+      }
+    }
+    this.requestPass();
+  }
+  requestPass() {
+    this.scheduler.requestPass({
+      connection: this.connection,
+      preloadDistance: this.preloadDistance
+    });
+  }
+  getConnection() {
+    return this.connection;
+  }
+  getDebugSnapshot() {
+    return {
+      resources: this.registry.all(),
+      decisions: this.scheduler.getDecisionLog(),
+      connection: this.connection
+    };
+  }
+  setPriority(id, priority) {
+    this.registry.update(id, { priority });
+    this.requestPass();
+  }
+  destroy() {
+    var _a;
+    (_a = this.unsubscribeConnection) == null ? void 0 : _a.call(this);
+    this.viewportObserver.disconnect();
+    this.refCounts.clear();
+    this.registry.clear();
+  }
+  logDecision(decision) {
+    if (typeof console === "undefined") return;
+    console.debug(
+      `[react-fastload] ${decision.action} "${decision.resourceId}" \u2014 ${decision.reason}`
+    );
+  }
+};
+
+// src/observers/PerformanceObserver.ts
+var BrowserPerformanceObserver = class {
+  constructor() {
+    this.observers = [];
+  }
+  observe(entryTypes, callback, options) {
+    var _a;
+    if (!supportsPerformanceObserver()) return;
+    for (const type of entryTypes) {
+      try {
+        const observer = new PerformanceObserver((list) => {
+          callback(list.getEntries());
+        });
+        observer.observe({ type, buffered: (_a = options == null ? void 0 : options.buffered) != null ? _a : true });
+        this.observers.push(observer);
+      } catch {
+      }
+    }
+  }
+  disconnect() {
+    for (const observer of this.observers) observer.disconnect();
+    this.observers = [];
+  }
+};
+
+// src/metrics/WebVitals.ts
+var WebVitals = class {
+  constructor() {
+    this.snapshot = { fcp: null, lcp: null, cls: null };
+    this.listeners = /* @__PURE__ */ new Set();
+    this.perfObserver = new BrowserPerformanceObserver();
+    this.clsAccumulator = 0;
+  }
+  start() {
+    if (!supportsNavigationTiming()) return;
+    this.perfObserver.observe(["paint"], (entries) => {
+      for (const entry of entries) {
+        if (entry.name === "first-contentful-paint") {
+          this.update({ fcp: entry.startTime });
+        }
+      }
+    });
+    this.perfObserver.observe(["largest-contentful-paint"], (entries) => {
+      const last = entries[entries.length - 1];
+      if (last) {
+        const value = last.renderTime || last.loadTime || last.startTime;
+        this.update({ lcp: value });
+      }
+    });
+    this.perfObserver.observe(["layout-shift"], (entries) => {
+      for (const entry of entries) {
+        if (!entry.hadRecentInput) {
+          this.clsAccumulator += entry.value;
+        }
+      }
+      this.update({ cls: this.clsAccumulator });
+    });
+  }
+  getSnapshot() {
+    return { ...this.snapshot };
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  stop() {
+    this.perfObserver.disconnect();
+    this.listeners.clear();
+  }
+  update(patch) {
+    this.snapshot = { ...this.snapshot, ...patch };
+    for (const listener of this.listeners) listener(this.snapshot);
+  }
+};
+
+// src/metrics/ResourceMetrics.ts
+function getNavigationMetrics() {
+  if (!supportsNavigationTiming()) {
+    return { ttfb: null, domContentLoaded: null, loadEvent: null };
+  }
+  const [nav] = performance.getEntriesByType("navigation");
+  if (!nav) {
+    return { ttfb: null, domContentLoaded: null, loadEvent: null };
+  }
+  return {
+    ttfb: round(nav.responseStart - nav.startTime),
+    domContentLoaded: round(nav.domContentLoadedEventEnd - nav.startTime),
+    loadEvent: nav.loadEventEnd > 0 ? round(nav.loadEventEnd - nav.startTime) : null
+  };
+}
+function getResourceTimingSummary() {
+  if (!supportsNavigationTiming()) {
+    return { totalResources: 0, totalTransferBytes: 0, slowestResourceMs: null };
+  }
+  const entries = performance.getEntriesByType("resource");
+  let totalTransferBytes = 0;
+  let slowest = null;
+  for (const entry of entries) {
+    totalTransferBytes += entry.transferSize || 0;
+    const duration = entry.duration;
+    if (slowest === null || duration > slowest) slowest = duration;
+  }
+  return {
+    totalResources: entries.length,
+    totalTransferBytes,
+    slowestResourceMs: slowest !== null ? round(slowest) : null
+  };
+}
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+
+// src/metrics/MetricsCollector.ts
+var MetricsCollector = class {
+  constructor(loadManager) {
+    this.loadManager = loadManager;
+    this.webVitals = new WebVitals();
+    this.started = false;
+  }
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.webVitals.start();
+  }
+  stop() {
+    this.webVitals.stop();
+    this.started = false;
+  }
+  subscribeWebVitals(listener) {
+    return this.webVitals.subscribe(listener);
+  }
+  snapshot() {
+    const vitals = this.webVitals.getSnapshot();
+    const nav = getNavigationMetrics();
+    const resourceTiming = getResourceTimingSummary();
+    const registrySummary = this.loadManager.registry.summary();
+    return {
+      fcp: vitals.fcp,
+      lcp: vitals.lcp,
+      cls: vitals.cls,
+      ttfb: nav.ttfb,
+      totalResourcesObserved: resourceTiming.totalResources,
+      totalTransferBytesObserved: resourceTiming.totalTransferBytes,
+      initialRequests: registrySummary.initialRequests,
+      deferredRequests: registrySummary.deferredRequests,
+      deferredResources: registrySummary.deferredResources,
+      bytesDeferred: registrySummary.bytesDeferred,
+      imagesDeferred: registrySummary.imagesDeferred,
+      videosDeferred: registrySummary.videosDeferred,
+      audiosDeferred: registrySummary.audiosDeferred,
+      componentsDeferred: registrySummary.componentsDeferred
+    };
+  }
+};
+var FastLoadContext = createContext(null);
+var STRATEGY_CONCURRENCY = {
+  adaptive: 4,
+  eager: 8,
+  conservative: 2
+};
+function FastLoadProvider({
+  children,
+  strategy = "adaptive",
+  preloadDistance = 1e3,
+  concurrency,
+  debug = false
+}) {
+  const loadManagerRef = useRef();
+  if (!loadManagerRef.current) {
+    loadManagerRef.current = new LoadManager({
+      preloadDistance,
+      concurrency: concurrency != null ? concurrency : STRATEGY_CONCURRENCY[strategy],
+      debug
+    });
+  }
+  const metricsCollectorRef = useRef();
+  if (!metricsCollectorRef.current) {
+    metricsCollectorRef.current = new MetricsCollector(loadManagerRef.current);
+  }
+  useEffect(() => {
+    const manager = loadManagerRef.current;
+    const collector = metricsCollectorRef.current;
+    collector.start();
+    return () => {
+      collector.stop();
+      manager.destroy();
+    };
+  }, []);
+  const value = useMemo(
+    () => ({
+      loadManager: loadManagerRef.current,
+      metricsCollector: metricsCollectorRef.current,
+      debug
+    }),
+    [debug]
+  );
+  return /* @__PURE__ */ jsxs(FastLoadContext.Provider, { value, children: [
+    children,
+    debug && /* @__PURE__ */ jsx(FastLoadDebugPanel, {})
+  ] });
+}
+function useFastLoadContext() {
+  const ctx = useContext(FastLoadContext);
+  if (!ctx) {
+    throw new Error(
+      "react-fastload: this hook/component must be used inside a <FastLoadProvider>."
+    );
+  }
+  return ctx;
+}
+function FastLoadDebugPanel() {
+  var _a, _b;
+  const { loadManager } = useFastLoadContext();
+  const [snapshot, setSnapshot] = useState(() => loadManager.getDebugSnapshot());
+  useEffect(() => {
+    const unsubscribe = loadManager.registry.subscribe(() => {
+      setSnapshot(loadManager.getDebugSnapshot());
+    });
+    const interval = setInterval(() => setSnapshot(loadManager.getDebugSnapshot()), 1e3);
+    return () => {
+      unsubscribe();
+      clearInterval(interval);
+    };
+  }, [loadManager]);
+  const isProduction = typeof process !== "undefined" && ((_a = process.env) == null ? void 0 : _a.NODE_ENV) === "production";
+  if (isProduction) return null;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: {
+        position: "fixed",
+        bottom: 8,
+        right: 8,
+        zIndex: 999999,
+        maxWidth: 360,
+        maxHeight: 320,
+        overflow: "auto",
+        background: "rgba(17, 17, 17, 0.92)",
+        color: "#e6e6e6",
+        fontFamily: "monospace",
+        fontSize: 11,
+        borderRadius: 8,
+        padding: 10,
+        lineHeight: 1.4
+      },
+      "data-testid": "fastload-debug-panel",
+      children: [
+        /* @__PURE__ */ jsx("div", { style: { fontWeight: 700, marginBottom: 6 }, children: "react-fastload debug" }),
+        /* @__PURE__ */ jsxs("div", { children: [
+          "connection: ",
+          (_b = snapshot.connection.effectiveType) != null ? _b : "unknown",
+          " (saveData: ",
+          String(snapshot.connection.saveData),
+          ")"
+        ] }),
+        /* @__PURE__ */ jsxs("div", { style: { marginTop: 6 }, children: [
+          "resources (",
+          snapshot.resources.length,
+          ")"
+        ] }),
+        snapshot.resources.map((r) => /* @__PURE__ */ jsxs("div", { style: { opacity: r.state === "loaded" ? 0.6 : 1 }, children: [
+          "[",
+          r.priority,
+          "] ",
+          r.id,
+          " \u2014 ",
+          r.state,
+          r.deferred ? " (deferred)" : "",
+          r.prefetched ? " (prefetched)" : ""
+        ] }, r.id)),
+        /* @__PURE__ */ jsx("div", { style: { marginTop: 6 }, children: "recent decisions" }),
+        snapshot.decisions.slice(-8).map((d, i) => /* @__PURE__ */ jsxs("div", { children: [
+          d.action,
+          " ",
+          d.resourceId,
+          ": ",
+          d.reason
+        ] }, i))
+      ]
+    }
+  );
+}
+function useLazyLoad(options) {
+  const { loadManager } = useFastLoadContext();
+  const { id, type, priority, strategy, estimatedSize, meta, loader } = options;
+  const unobserveRef = useRef(void 0);
+  const elementRef = useRef(null);
+  const shouldObserveRef = useRef(strategy !== "eager" && priority !== "CRITICAL");
+  shouldObserveRef.current = strategy !== "eager" && priority !== "CRITICAL";
+  const [state, setState] = useState("idle");
+  const [record, setRecord] = useState(void 0);
+  useEffect(() => {
+    const initial = loadManager.register({ id, type, priority, strategy, estimatedSize, meta });
+    setRecord(initial);
+    setState(initial.state);
+    loadManager.setLoader(id, loader);
+    const unsubscribe = loadManager.registry.subscribe((all) => {
+      const found = all.find((r) => r.id === id);
+      if (found) {
+        setRecord(found);
+        setState(found.state);
+      }
+    });
+    if (shouldObserveRef.current && elementRef.current) {
+      unobserveRef.current = loadManager.observeViewport(id, elementRef.current);
+    }
+    return () => {
+      var _a;
+      unsubscribe();
+      (_a = unobserveRef.current) == null ? void 0 : _a.call(unobserveRef);
+      unobserveRef.current = void 0;
+      loadManager.unregister(id);
+    };
+  }, [id]);
+  const ref = (node) => {
+    var _a;
+    if (elementRef.current === node) return;
+    (_a = unobserveRef.current) == null ? void 0 : _a.call(unobserveRef);
+    unobserveRef.current = void 0;
+    elementRef.current = node;
+    if (node && shouldObserveRef.current) {
+      unobserveRef.current = loadManager.observeViewport(id, node);
+    }
+  };
+  return { ref, state, record };
+}
+
+// src/resources/ImageLoader.ts
+var PRIORITY_TO_FETCH_PRIORITY = {
+  CRITICAL: "high",
+  HIGH: "high",
+  NORMAL: "auto",
+  LOW: "low",
+  IDLE: "low"
+};
+function loadImage(options) {
+  return new Promise((resolve, reject) => {
+    var _a, _b, _c;
+    if (typeof Image === "undefined") {
+      resolve({});
+      return;
+    }
+    if ((_a = options.signal) == null ? void 0 : _a.aborted) {
+      reject(new DOMException("Image load aborted before it started", "AbortError"));
+      return;
+    }
+    const img = new Image();
+    if (supportsFetchPriority()) {
+      img.fetchPriority = PRIORITY_TO_FETCH_PRIORITY[options.priority];
+    }
+    img.decoding = (_b = options.decoding) != null ? _b : "async";
+    const cleanup = () => {
+      var _a2;
+      img.onload = null;
+      img.onerror = null;
+      (_a2 = options.signal) == null ? void 0 : _a2.removeEventListener("abort", onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      img.src = "";
+      reject(new DOMException("Image load aborted", "AbortError"));
+    };
+    img.onload = () => {
+      cleanup();
+      resolve(img);
+    };
+    img.onerror = (event) => {
+      cleanup();
+      reject(event instanceof Event ? new Error("Image failed to load") : event);
+    };
+    (_c = options.signal) == null ? void 0 : _c.addEventListener("abort", onAbort, { once: true });
+    img.src = options.src;
+  });
+}
+function resolvePriority(priority) {
+  if (!priority || priority === "auto") return "NORMAL";
+  return priority;
+}
+function SmartImage({
+  src,
+  priority = "auto",
+  placeholder,
+  resourceId,
+  strategy = "auto",
+  estimatedSize,
+  alt,
+  decoding = "async",
+  style,
+  onLoad,
+  onError,
+  ...rest
+}) {
+  const id = resourceId != null ? resourceId : `image:${src}`;
+  const resolvedPriority = resolvePriority(priority);
+  const effectiveStrategy = strategy === "auto" ? resolvedPriority === "CRITICAL" ? "eager" : "lazy" : strategy;
+  const loader = useMemo(
+    () => (resource) => {
+      var _a;
+      return loadImage({ src, priority: resolvedPriority, decoding, signal: (_a = resource.abortController) == null ? void 0 : _a.signal }).then(
+        () => void 0
+      );
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [src, resolvedPriority, decoding]
+  );
+  const { ref, state } = useLazyLoad({
+    id,
+    type: "image",
+    priority: resolvedPriority,
+    strategy: effectiveStrategy,
+    estimatedSize,
+    // Stored so tooling (e.g. a benchmark or devtools panel) can
+    // cross-reference a deferred registry entry against its real
+    // Resource Timing entry once it eventually loads. Never read by the
+    // scheduler itself.
+    meta: { src },
+    loader
+  });
+  const shouldRenderRealImage = effectiveStrategy === "eager" || state === "loading" || state === "loaded";
+  const containerStyle = {
+    ...style,
+    ...placeholder && !shouldRenderRealImage ? {
+      backgroundImage: `url(${placeholder})`,
+      backgroundSize: "cover",
+      backgroundPosition: "center"
+    } : {}
+  };
+  if (!shouldRenderRealImage) {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref,
+        role: "img",
+        "aria-label": alt,
+        "aria-busy": state === "eligible",
+        "data-fastload-state": state,
+        style: { display: "inline-block", ...containerStyle }
+      }
+    );
+  }
+  const imgProps = {
+    src,
+    alt,
+    decoding,
+    loading: effectiveStrategy === "eager" ? "eager" : "lazy",
+    style: containerStyle,
+    onLoad,
+    onError,
+    ...supportsFetchPriority() ? { fetchPriority: fetchPriorityFor(resolvedPriority) } : {},
+    ...rest
+  };
+  return /* @__PURE__ */ jsx(
+    "img",
+    {
+      ref,
+      "data-fastload-state": state,
+      ...imgProps
+    }
+  );
+}
+function fetchPriorityFor(priority) {
+  if (priority === "CRITICAL" || priority === "HIGH") return "high";
+  if (priority === "LOW" || priority === "IDLE") return "low";
+  return "auto";
+}
+
+// src/resources/VideoLoader.ts
+function loadVideo(options) {
+  return new Promise((resolve) => {
+    var _a, _b;
+    if ((_a = options.signal) == null ? void 0 : _a.aborted) {
+      resolve();
+      return;
+    }
+    if (options.poster && (options.priority === "CRITICAL" || options.priority === "HIGH")) {
+      if (typeof Image === "undefined") {
+        resolve();
+        return;
+      }
+      const img = new Image();
+      const cleanup = () => {
+        var _a2;
+        img.onload = null;
+        img.onerror = null;
+        (_a2 = options.signal) == null ? void 0 : _a2.removeEventListener("abort", onAbort);
+      };
+      const onAbort = () => {
+        cleanup();
+        img.src = "";
+        resolve();
+      };
+      img.onload = () => {
+        cleanup();
+        resolve();
+      };
+      img.onerror = () => {
+        cleanup();
+        resolve();
+      };
+      (_b = options.signal) == null ? void 0 : _b.addEventListener("abort", onAbort, { once: true });
+      img.src = options.poster;
+      return;
+    }
+    resolve();
+  });
+}
+function resolvePriority2(priority) {
+  if (!priority || priority === "auto") return "NORMAL";
+  return priority;
+}
+function SmartVideo({
+  src,
+  poster,
+  priority = "auto",
+  resourceId,
+  strategy = "auto",
+  estimatedSize,
+  aspectRatio,
+  autoplay = false,
+  muted,
+  controls = true,
+  style,
+  ...rest
+}) {
+  const id = resourceId != null ? resourceId : `video:${src}`;
+  const resolvedPriority = resolvePriority2(priority);
+  const effectiveStrategy = strategy === "auto" ? resolvedPriority === "CRITICAL" ? "eager" : "lazy" : strategy;
+  const [userInteracted, setUserInteracted] = useState(false);
+  const loader = useMemo(
+    () => (resource) => {
+      var _a;
+      return loadVideo({ poster, priority: resolvedPriority, signal: (_a = resource.abortController) == null ? void 0 : _a.signal });
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [src, poster, resolvedPriority]
+  );
+  const { ref, state } = useLazyLoad({
+    id,
+    type: "video",
+    priority: resolvedPriority,
+    strategy: effectiveStrategy,
+    estimatedSize,
+    // Stored so tooling (e.g. a benchmark or devtools panel) can
+    // cross-reference a deferred registry entry against its real
+    // Resource Timing entry once it eventually loads. Never read by the
+    // scheduler itself.
+    meta: { src },
+    loader
+  });
+  const isEligible = effectiveStrategy === "eager" || state === "loading" || state === "loaded";
+  const shouldMountVideo = isEligible || userInteracted;
+  if (!shouldMountVideo) {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref,
+        role: "button",
+        tabIndex: 0,
+        "aria-label": "Load video",
+        "data-fastload-state": state,
+        onClick: () => setUserInteracted(true),
+        onKeyDown: (e) => {
+          if (e.key === "Enter" || e.key === " ") setUserInteracted(true);
+        },
+        style: {
+          position: "relative",
+          cursor: "pointer",
+          backgroundImage: poster ? `url(${poster})` : void 0,
+          backgroundSize: "cover",
+          backgroundPosition: "center",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          minHeight: aspectRatio ? void 0 : 120,
+          aspectRatio,
+          ...style
+        },
+        children: /* @__PURE__ */ jsx(PlayGlyph, {})
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "video",
+    {
+      ref,
+      src,
+      poster,
+      preload: resolvedPriority === "CRITICAL" || resolvedPriority === "HIGH" ? "auto" : "metadata",
+      autoPlay: autoplay && isEligible,
+      muted: autoplay ? true : muted,
+      controls,
+      "data-fastload-state": state,
+      style: { aspectRatio, ...style },
+      ...rest
+    }
+  );
+}
+function PlayGlyph() {
+  return /* @__PURE__ */ jsxs("svg", { width: "48", height: "48", viewBox: "0 0 48 48", "aria-hidden": "true", children: [
+    /* @__PURE__ */ jsx("circle", { cx: "24", cy: "24", r: "23", fill: "rgba(0,0,0,0.55)", stroke: "white", strokeWidth: "1" }),
+    /* @__PURE__ */ jsx("polygon", { points: "19,14 19,34 35,24", fill: "white" })
+  ] });
+}
+
+// src/resources/AudioLoader.ts
+function loadAudio(options) {
+  return new Promise((resolve) => {
+    var _a, _b;
+    if ((_a = options.signal) == null ? void 0 : _a.aborted) {
+      resolve();
+      return;
+    }
+    if (options.priority !== "CRITICAL" && options.priority !== "HIGH") {
+      resolve();
+      return;
+    }
+    if (typeof Audio === "undefined") {
+      resolve();
+      return;
+    }
+    const audio = new Audio();
+    audio.preload = "metadata";
+    const cleanup = () => {
+      var _a2;
+      audio.removeEventListener("loadedmetadata", finish);
+      audio.removeEventListener("error", finish);
+      (_a2 = options.signal) == null ? void 0 : _a2.removeEventListener("abort", onAbort);
+    };
+    const finish = () => {
+      cleanup();
+      resolve();
+    };
+    const onAbort = () => {
+      cleanup();
+      audio.src = "";
+      resolve();
+    };
+    audio.addEventListener("loadedmetadata", finish, { once: true });
+    audio.addEventListener("error", finish, { once: true });
+    (_b = options.signal) == null ? void 0 : _b.addEventListener("abort", onAbort, { once: true });
+    audio.src = options.src;
+  });
+}
+function resolvePriority3(priority) {
+  if (!priority || priority === "auto") return "NORMAL";
+  return priority;
+}
+function SmartAudio({
+  src,
+  priority = "auto",
+  resourceId,
+  strategy = "auto",
+  estimatedSize,
+  label,
+  autoplay = false,
+  muted,
+  controls = true,
+  ...rest
+}) {
+  const id = resourceId != null ? resourceId : `audio:${src}`;
+  const resolvedPriority = resolvePriority3(priority);
+  const effectiveStrategy = strategy === "auto" ? resolvedPriority === "CRITICAL" ? "eager" : "lazy" : strategy;
+  const [userInteracted, setUserInteracted] = useState(false);
+  const loader = useMemo(
+    () => (resource) => {
+      var _a;
+      return loadAudio({ src, priority: resolvedPriority, signal: (_a = resource.abortController) == null ? void 0 : _a.signal });
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [src, resolvedPriority]
+  );
+  const { ref, state } = useLazyLoad({
+    id,
+    type: "audio",
+    priority: resolvedPriority,
+    strategy: effectiveStrategy,
+    estimatedSize,
+    // Stored so tooling (e.g. a benchmark or devtools panel) can
+    // cross-reference a deferred registry entry against its real
+    // Resource Timing entry once it eventually loads. Never read by the
+    // scheduler itself.
+    meta: { src },
+    loader
+  });
+  const isEligible = effectiveStrategy === "eager" || state === "loading" || state === "loaded";
+  const shouldMountAudio = isEligible || userInteracted;
+  if (!shouldMountAudio) {
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref,
+        role: "button",
+        tabIndex: 0,
+        "aria-label": label ? `Load audio: ${label}` : "Load audio",
+        "data-fastload-state": state,
+        onClick: () => setUserInteracted(true),
+        onKeyDown: (e) => {
+          if (e.key === "Enter" || e.key === " ") setUserInteracted(true);
+        },
+        style: {
+          display: "inline-flex",
+          alignItems: "center",
+          gap: 8,
+          padding: "8px 12px",
+          borderRadius: 999,
+          border: "1px solid rgba(0,0,0,0.15)",
+          cursor: "pointer",
+          userSelect: "none"
+        },
+        children: [
+          /* @__PURE__ */ jsx(PlayGlyph2, {}),
+          label != null ? label : "Load audio"
+        ]
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "audio",
+    {
+      ref,
+      src,
+      preload: resolvedPriority === "CRITICAL" || resolvedPriority === "HIGH" ? "auto" : "metadata",
+      autoPlay: autoplay && isEligible,
+      muted: autoplay ? true : muted,
+      controls,
+      "data-fastload-state": state,
+      ...rest
+    }
+  );
+}
+function PlayGlyph2() {
+  return /* @__PURE__ */ jsx("svg", { width: "14", height: "14", viewBox: "0 0 24 24", "aria-hidden": "true", children: /* @__PURE__ */ jsx("polygon", { points: "6,4 6,20 20,12", fill: "currentColor" }) });
+}
+
+// src/resources/ComponentLoader.ts
+function createComponentLoader(importFn) {
+  let cached;
+  return () => {
+    if (!cached) {
+      cached = importFn();
+    }
+    return cached;
+  };
+}
+function lazyComponent(importFn, options = {}) {
+  var _a, _b, _c;
+  const cachedImport = createComponentLoader(importFn);
+  const priority = (_a = options.priority) != null ? _a : "NORMAL";
+  const strategy = (_b = options.strategy) != null ? _b : priority === "CRITICAL" ? "eager" : "lazy";
+  function LazyComponentWrapper(props) {
+    var _a2, _b2, _c2, _d;
+    const generatedId = useId();
+    const id = (_a2 = options.resourceId) != null ? _a2 : `component:${generatedId}`;
+    const LazyReal = useMemo(() => React5.lazy(cachedImport), []);
+    const loader = useMemo(
+      () => () => cachedImport().then(() => void 0),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      []
+    );
+    const { ref, state } = useLazyLoad({
+      id,
+      type: "component",
+      priority,
+      strategy,
+      estimatedSize: options.estimatedSize,
+      loader
+    });
+    const isEligible = strategy === "eager" || state === "eligible" || state === "loading" || state === "loaded";
+    if (!isEligible) {
+      return /* @__PURE__ */ jsx("div", { ref, "data-fastload-state": state, children: (_b2 = options.placeholder) != null ? _b2 : null });
+    }
+    const Rendered = LazyReal;
+    return /* @__PURE__ */ jsx(Suspense, { fallback: (_d = (_c2 = options.fallback) != null ? _c2 : options.placeholder) != null ? _d : null, children: /* @__PURE__ */ jsx(Rendered, { ...props }) });
+  }
+  LazyComponentWrapper.displayName = `LazyComponent(${(_c = options.resourceId) != null ? _c : "anonymous"})`;
+  return LazyComponentWrapper;
+}
+function usePriority(resourceId, priority) {
+  const { loadManager } = useFastLoadContext();
+  useEffect(() => {
+    if (!loadManager.registry.has(resourceId)) return;
+    loadManager.setPriority(resourceId, priority);
+  }, [loadManager, resourceId, priority]);
+}
+function useFastLoadMetrics() {
+  const { loadManager, metricsCollector } = useFastLoadContext();
+  const [metrics, setMetrics] = useState(() => metricsCollector.snapshot());
+  useEffect(() => {
+    const refresh = () => setMetrics(metricsCollector.snapshot());
+    const unsubVitals = metricsCollector.subscribeWebVitals(refresh);
+    const unsubRegistry = loadManager.registry.subscribe(refresh);
+    refresh();
+    return () => {
+      unsubVitals();
+      unsubRegistry();
+    };
+  }, [loadManager, metricsCollector]);
+  return metrics;
+}
+
+export { FastLoadProvider, LoadManager, PriorityEngine, ResourceRegistry, Scheduler, SmartAudio, SmartImage, SmartVideo, lazyComponent, useFastLoadContext, useFastLoadMetrics, useLazyLoad, usePriority };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map