@page-speed/img 0.4.5 → 0.4.7

package/dist/core/Img.cjs

@@ -1,7 +1,8 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { forwardRef, memo, useCallback, useMemo, useRef } from "react";
 import { useOptimizedImage } from "@page-speed/hooks/media";
+import { useImgDebugLog } from "./useImgDebugLog.js";
 import { useMediaSelectionEffect } from "./useMediaSelectionEffect.js";
 import { useResponsiveReset } from "./useResponsiveReset.js";
 const TRANSPARENT_PIXEL = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==";
@@ -20,7 +21,6 @@ const resolveOptixFlowConfig = (config) => {
 export const setDefaultOptixFlowConfig = (config) => {
     defaultOptixFlowConfig = config ?? undefined;
 };
-const isUrlString = (value) => typeof value === "string" && value.trim().length > 0;
 const parseDimension = (value) => {
     if (value === "" || value === null || typeof value === "undefined")
         return undefined;
@@ -44,18 +44,19 @@ const composeRefs = (hookRef, forwardedRef, localRef) => useCallback((node) => {
         forwardedRef.current = node;
     }
 }, [hookRef, forwardedRef, localRef]);
-const ModernImg = ({ sizes, loading, decoding, alt, title, src: directSrc, eager, intersectionMargin, intersectionThreshold, optixFlowConfig, forwardedRef, ...rest }) => {
+const ModernImg = ({ sizes, loading, decoding, alt, title, src: directSrc, eager, width, height, fetchPriority, intersectionMargin, intersectionThreshold, optixFlowConfig, useDebugMode, forwardedRef, ...restProps }) => {
     const imgRef = useRef(null);
     const pictureRef = useRef(null);
-    const logKeyRef = useRef(null);
     useResponsiveReset(pictureRef);
     useMediaSelectionEffect();
     const normalizedSrc = useMemo(() => (typeof directSrc === "string" ? directSrc.trim() : ""), [directSrc]);
-    const numericWidth = useMemo(() => parseDimension(rest.width), [rest]);
-    const numericHeight = useMemo(() => parseDimension(rest.height), [rest]);
+    const numericWidth = useMemo(() => parseDimension(width), [width]);
+    const numericHeight = useMemo(() => parseDimension(height), [height]);
     const resolvedOptixConfig = useMemo(() => resolveOptixFlowConfig(optixFlowConfig), [optixFlowConfig]);
-    const eagerLoad = eager ?? loading === "eager";
-    const { ref: hookRef, src, srcset, sizes: computedSizes, loading: hookLoading, isInView, size, } = useOptimizedImage({
+    const eagerLoad = useMemo(() => {
+        return eager ?? loading === "eager";
+    }, [eager, loading]);
+    const hookOptions = useMemo(() => ({
         src: normalizedSrc,
         eager: eagerLoad,
         width: numericWidth,
@@ -63,57 +64,57 @@ const ModernImg = ({ sizes, loading, decoding, alt, title, src: directSrc, eager
         rootMargin: intersectionMargin ?? "200px",
         threshold: intersectionThreshold ?? 0.1,
         optixFlowConfig: resolvedOptixConfig,
-    });
+    }), [
+        normalizedSrc,
+        eagerLoad,
+        numericWidth,
+        numericHeight,
+        intersectionMargin,
+        intersectionThreshold,
+        resolvedOptixConfig,
+    ]);
+    const { ref: hookRef, src, srcset, sizes: computedSizes, loading: hookLoading, isInView, size, } = useOptimizedImage(hookOptions);
     const mergedRef = composeRefs(hookRef, forwardedRef, imgRef);
-    const { width, height, ...restProps } = rest;
-    const sizesAttr = sizes ?? (computedSizes || undefined);
-    const loadingAttr = loading ?? hookLoading ?? "lazy";
-    const decodingAttr = decoding ?? "async";
-    const hasSrcSet = Boolean(srcset.avif || srcset.webp || srcset.jpeg);
-    const imgSrc = src || normalizedSrc || TRANSPARENT_PIXEL;
-    const inlineSrcSet = hasSrcSet && !srcset.avif && !srcset.webp ? srcset.jpeg : "";
-    const parsedWidth = parseDimension(width);
-    const parsedHeight = parseDimension(height);
-    const widthAttr = parsedWidth ?? (size.width || numericWidth || undefined);
-    const heightAttr = parsedHeight ?? (size.height || numericHeight || undefined);
-    // Temporary logging to detect repeated transform requests and URL churn.
-    useEffect(() => {
-        if (typeof window === "undefined")
-            return;
-        if (!eagerLoad && !isInView)
-            return;
-        if (!imgSrc || imgSrc === TRANSPARENT_PIXEL)
-            return;
-        const logKey = [
-            imgSrc,
-            srcset.avif,
-            srcset.webp,
-            srcset.jpeg,
-            sizesAttr ?? "",
-        ].join("|");
-        if (logKeyRef.current === logKey)
-            return;
-        logKeyRef.current = logKey;
-        if (typeof console !== "undefined" && console.info) {
-            console.info("[PageSpeedImg] image request", {
-                src: imgSrc,
-                srcset,
-                sizes: sizesAttr,
-            });
-        }
-    }, [
+    const sizesAttr = useMemo(() => {
+        return sizes ?? (computedSizes || undefined);
+    }, [sizes, computedSizes]);
+    const loadingAttr = useMemo(() => {
+        return loading ?? hookLoading ?? "lazy";
+    }, [loading, hookLoading]);
+    const decodingAttr = useMemo(() => {
+        return decoding ?? "async";
+    }, [decoding]);
+    const fetchPriorityAttr = useMemo(() => {
+        return fetchPriority ?? (eagerLoad ? "high" : undefined);
+    }, [fetchPriority, eagerLoad]);
+    const hasSrcSet = useMemo(() => {
+        return Boolean(srcset.avif || srcset.webp || srcset.jpeg);
+    }, [srcset.avif, srcset.webp, srcset.jpeg]);
+    const imgSrc = useMemo(() => {
+        return src || normalizedSrc || TRANSPARENT_PIXEL;
+    }, [src, normalizedSrc]);
+    const inlineSrcSet = useMemo(() => {
+        return hasSrcSet && !srcset.avif && !srcset.webp ? srcset.jpeg : "";
+    }, [hasSrcSet, srcset.avif, srcset.webp, srcset.jpeg]);
+    const widthAttr = useMemo(() => {
+        return numericWidth ?? (size.width || undefined);
+    }, [numericWidth, size?.width]);
+    const heightAttr = useMemo(() => {
+        return numericHeight ?? (size.height || undefined);
+    }, [numericHeight, size?.height]);
+    useImgDebugLog({
+        enabled: useDebugMode ?? false,
         eagerLoad,
-        imgSrc,
         isInView,
+        imgSrc,
+        transparentPixel: TRANSPARENT_PIXEL,
+        srcset,
         sizesAttr,
-        srcset.avif,
-        srcset.webp,
-        srcset.jpeg,
-    ]);
+    });
     if (!hasSrcSet) {
-        return (_jsx("img", { ref: mergedRef, src: imgSrc, loading: loadingAttr, decoding: decodingAttr, alt: alt, title: title, width: widthAttr, height: heightAttr, ...restProps }));
+        return (_jsx("img", { ref: mergedRef, src: imgSrc, loading: loadingAttr, decoding: decodingAttr, fetchPriority: fetchPriorityAttr, alt: alt, title: title, width: widthAttr, height: heightAttr, ...restProps }));
     }
-    return (_jsxs("picture", { ref: pictureRef, children: [srcset.avif ? (_jsx("source", { type: "image/avif", srcSet: srcset.avif, sizes: sizesAttr })) : null, srcset.webp ? (_jsx("source", { type: "image/webp", srcSet: srcset.webp, sizes: sizesAttr })) : null, _jsx("img", { ref: mergedRef, src: imgSrc, srcSet: inlineSrcSet || undefined, sizes: inlineSrcSet ? sizesAttr : undefined, loading: loadingAttr, decoding: decodingAttr, alt: alt, title: title, width: widthAttr, height: heightAttr, ...restProps })] }));
+    return (_jsxs("picture", { ref: pictureRef, children: [srcset.avif ? (_jsx("source", { type: "image/avif", srcSet: srcset.avif, sizes: sizesAttr })) : null, srcset.webp ? (_jsx("source", { type: "image/webp", srcSet: srcset.webp, sizes: sizesAttr })) : null, _jsx("img", { ref: mergedRef, src: imgSrc, srcSet: inlineSrcSet || undefined, sizes: inlineSrcSet ? sizesAttr : undefined, loading: loadingAttr, decoding: decodingAttr, fetchPriority: fetchPriorityAttr, alt: alt, title: title, width: widthAttr, height: heightAttr, ...restProps })] }));
 };
 const ImgBase = forwardRef(function Img(props, ref) {
     const hasSrc = typeof props.src === "string" && props.src.trim().length > 0;

package/dist/core/Img.d.ts

@@ -14,6 +14,8 @@ export type ImgProps = NativeImgProps & {
     intersectionMargin?: string;
     /** OptixFlow integration options */
     optixFlowConfig?: UseOptimizedImageOptions["optixFlowConfig"];
+    /** Enable debug logging for image requests */
+    useDebugMode?: boolean;
 };
 export declare const setDefaultOptixFlowConfig: (config?: UseOptimizedImageOptions["optixFlowConfig"] | null) => void;
 export declare const Img: React.MemoExoticComponent<React.ForwardRefExoticComponent<Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet" | "sizes"> & {
@@ -29,5 +31,7 @@ export declare const Img: React.MemoExoticComponent<React.ForwardRefExoticCompon
     intersectionMargin?: string;
     /** OptixFlow integration options */
     optixFlowConfig?: UseOptimizedImageOptions["optixFlowConfig"];
+    /** Enable debug logging for image requests */
+    useDebugMode?: boolean;
 } & React.RefAttributes<HTMLImageElement>>>;
 export {};

package/dist/core/Img.js

@@ -1,7 +1,8 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { forwardRef, memo, useCallback, useMemo, useRef } from "react";
 import { useOptimizedImage } from "@page-speed/hooks/media";
+import { useImgDebugLog } from "./useImgDebugLog.js";
 import { useMediaSelectionEffect } from "./useMediaSelectionEffect.js";
 import { useResponsiveReset } from "./useResponsiveReset.js";
 const TRANSPARENT_PIXEL = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==";
@@ -20,7 +21,6 @@ const resolveOptixFlowConfig = (config) => {
 export const setDefaultOptixFlowConfig = (config) => {
     defaultOptixFlowConfig = config ?? undefined;
 };
-const isUrlString = (value) => typeof value === "string" && value.trim().length > 0;
 const parseDimension = (value) => {
     if (value === "" || value === null || typeof value === "undefined")
         return undefined;
@@ -44,18 +44,19 @@ const composeRefs = (hookRef, forwardedRef, localRef) => useCallback((node) => {
         forwardedRef.current = node;
     }
 }, [hookRef, forwardedRef, localRef]);
-const ModernImg = ({ sizes, loading, decoding, alt, title, src: directSrc, eager, intersectionMargin, intersectionThreshold, optixFlowConfig, forwardedRef, ...rest }) => {
+const ModernImg = ({ sizes, loading, decoding, alt, title, src: directSrc, eager, width, height, fetchPriority, intersectionMargin, intersectionThreshold, optixFlowConfig, useDebugMode, forwardedRef, ...restProps }) => {
     const imgRef = useRef(null);
     const pictureRef = useRef(null);
-    const logKeyRef = useRef(null);
     useResponsiveReset(pictureRef);
     useMediaSelectionEffect();
     const normalizedSrc = useMemo(() => (typeof directSrc === "string" ? directSrc.trim() : ""), [directSrc]);
-    const numericWidth = useMemo(() => parseDimension(rest.width), [rest]);
-    const numericHeight = useMemo(() => parseDimension(rest.height), [rest]);
+    const numericWidth = useMemo(() => parseDimension(width), [width]);
+    const numericHeight = useMemo(() => parseDimension(height), [height]);
     const resolvedOptixConfig = useMemo(() => resolveOptixFlowConfig(optixFlowConfig), [optixFlowConfig]);
-    const eagerLoad = eager ?? loading === "eager";
-    const { ref: hookRef, src, srcset, sizes: computedSizes, loading: hookLoading, isInView, size, } = useOptimizedImage({
+    const eagerLoad = useMemo(() => {
+        return eager ?? loading === "eager";
+    }, [eager, loading]);
+    const hookOptions = useMemo(() => ({
         src: normalizedSrc,
         eager: eagerLoad,
         width: numericWidth,
@@ -63,57 +64,57 @@ const ModernImg = ({ sizes, loading, decoding, alt, title, src: directSrc, eager
         rootMargin: intersectionMargin ?? "200px",
         threshold: intersectionThreshold ?? 0.1,
         optixFlowConfig: resolvedOptixConfig,
-    });
+    }), [
+        normalizedSrc,
+        eagerLoad,
+        numericWidth,
+        numericHeight,
+        intersectionMargin,
+        intersectionThreshold,
+        resolvedOptixConfig,
+    ]);
+    const { ref: hookRef, src, srcset, sizes: computedSizes, loading: hookLoading, isInView, size, } = useOptimizedImage(hookOptions);
     const mergedRef = composeRefs(hookRef, forwardedRef, imgRef);
-    const { width, height, ...restProps } = rest;
-    const sizesAttr = sizes ?? (computedSizes || undefined);
-    const loadingAttr = loading ?? hookLoading ?? "lazy";
-    const decodingAttr = decoding ?? "async";
-    const hasSrcSet = Boolean(srcset.avif || srcset.webp || srcset.jpeg);
-    const imgSrc = src || normalizedSrc || TRANSPARENT_PIXEL;
-    const inlineSrcSet = hasSrcSet && !srcset.avif && !srcset.webp ? srcset.jpeg : "";
-    const parsedWidth = parseDimension(width);
-    const parsedHeight = parseDimension(height);
-    const widthAttr = parsedWidth ?? (size.width || numericWidth || undefined);
-    const heightAttr = parsedHeight ?? (size.height || numericHeight || undefined);
-    // Temporary logging to detect repeated transform requests and URL churn.
-    useEffect(() => {
-        if (typeof window === "undefined")
-            return;
-        if (!eagerLoad && !isInView)
-            return;
-        if (!imgSrc || imgSrc === TRANSPARENT_PIXEL)
-            return;
-        const logKey = [
-            imgSrc,
-            srcset.avif,
-            srcset.webp,
-            srcset.jpeg,
-            sizesAttr ?? "",
-        ].join("|");
-        if (logKeyRef.current === logKey)
-            return;
-        logKeyRef.current = logKey;
-        if (typeof console !== "undefined" && console.info) {
-            console.info("[PageSpeedImg] image request", {
-                src: imgSrc,
-                srcset,
-                sizes: sizesAttr,
-            });
-        }
-    }, [
+    const sizesAttr = useMemo(() => {
+        return sizes ?? (computedSizes || undefined);
+    }, [sizes, computedSizes]);
+    const loadingAttr = useMemo(() => {
+        return loading ?? hookLoading ?? "lazy";
+    }, [loading, hookLoading]);
+    const decodingAttr = useMemo(() => {
+        return decoding ?? "async";
+    }, [decoding]);
+    const fetchPriorityAttr = useMemo(() => {
+        return fetchPriority ?? (eagerLoad ? "high" : undefined);
+    }, [fetchPriority, eagerLoad]);
+    const hasSrcSet = useMemo(() => {
+        return Boolean(srcset.avif || srcset.webp || srcset.jpeg);
+    }, [srcset.avif, srcset.webp, srcset.jpeg]);
+    const imgSrc = useMemo(() => {
+        return src || normalizedSrc || TRANSPARENT_PIXEL;
+    }, [src, normalizedSrc]);
+    const inlineSrcSet = useMemo(() => {
+        return hasSrcSet && !srcset.avif && !srcset.webp ? srcset.jpeg : "";
+    }, [hasSrcSet, srcset.avif, srcset.webp, srcset.jpeg]);
+    const widthAttr = useMemo(() => {
+        return numericWidth ?? (size.width || undefined);
+    }, [numericWidth, size?.width]);
+    const heightAttr = useMemo(() => {
+        return numericHeight ?? (size.height || undefined);
+    }, [numericHeight, size?.height]);
+    useImgDebugLog({
+        enabled: useDebugMode ?? false,
         eagerLoad,
-        imgSrc,
         isInView,
+        imgSrc,
+        transparentPixel: TRANSPARENT_PIXEL,
+        srcset,
         sizesAttr,
-        srcset.avif,
-        srcset.webp,
-        srcset.jpeg,
-    ]);
+    });
     if (!hasSrcSet) {
-        return (_jsx("img", { ref: mergedRef, src: imgSrc, loading: loadingAttr, decoding: decodingAttr, alt: alt, title: title, width: widthAttr, height: heightAttr, ...restProps }));
+        return (_jsx("img", { ref: mergedRef, src: imgSrc, loading: loadingAttr, decoding: decodingAttr, fetchPriority: fetchPriorityAttr, alt: alt, title: title, width: widthAttr, height: heightAttr, ...restProps }));
     }
-    return (_jsxs("picture", { ref: pictureRef, children: [srcset.avif ? (_jsx("source", { type: "image/avif", srcSet: srcset.avif, sizes: sizesAttr })) : null, srcset.webp ? (_jsx("source", { type: "image/webp", srcSet: srcset.webp, sizes: sizesAttr })) : null, _jsx("img", { ref: mergedRef, src: imgSrc, srcSet: inlineSrcSet || undefined, sizes: inlineSrcSet ? sizesAttr : undefined, loading: loadingAttr, decoding: decodingAttr, alt: alt, title: title, width: widthAttr, height: heightAttr, ...restProps })] }));
+    return (_jsxs("picture", { ref: pictureRef, children: [srcset.avif ? (_jsx("source", { type: "image/avif", srcSet: srcset.avif, sizes: sizesAttr })) : null, srcset.webp ? (_jsx("source", { type: "image/webp", srcSet: srcset.webp, sizes: sizesAttr })) : null, _jsx("img", { ref: mergedRef, src: imgSrc, srcSet: inlineSrcSet || undefined, sizes: inlineSrcSet ? sizesAttr : undefined, loading: loadingAttr, decoding: decodingAttr, fetchPriority: fetchPriorityAttr, alt: alt, title: title, width: widthAttr, height: heightAttr, ...restProps })] }));
 };
 const ImgBase = forwardRef(function Img(props, ref) {
     const hasSrc = typeof props.src === "string" && props.src.trim().length > 0;

package/dist/core/OptixFlowConfig.cjs

@@ -0,0 +1,30 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { setDefaultOptixFlowConfig } from "./Img.js";
+/**
+ * A component that sets the default OptixFlow configuration for all Img components
+ * in an SSR-safe way. This component should be rendered once at the app root level.
+ *
+ * The config is applied inside a useEffect, which means it only runs on the client
+ * and is never executed during server-side rendering.
+ *
+ * @example
+ * ```tsx
+ * // In your app root
+ * <OptixFlowConfig config={{ apiKey: 'your-api-key' }}>
+ *   <App />
+ * </OptixFlowConfig>
+ * ```
+ *
+ * Or without children:
+ * ```tsx
+ * <OptixFlowConfig config={{ apiKey: 'your-api-key' }} />
+ * ```
+ */
+export function OptixFlowConfig({ config, children, }) {
+    React.useEffect(() => {
+        setDefaultOptixFlowConfig(config ?? null);
+    }, [config]);
+    return children ? _jsx(_Fragment, { children: children }) : null;
+}

package/dist/core/OptixFlowConfig.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+import type { UseOptimizedImageOptions } from "@page-speed/hooks/media";
+/**
+ * Props for the OptixFlowConfig component
+ */
+export interface OptixFlowConfigProps {
+    /**
+     * OptixFlow configuration to set as default for all images
+     * @example { apiKey: 'your-api-key', compressionLevel: 80 }
+     */
+    config: UseOptimizedImageOptions["optixFlowConfig"];
+    /**
+     * Optional children (component returns null regardless)
+     */
+    children?: React.ReactNode;
+}
+/**
+ * A component that sets the default OptixFlow configuration for all Img components
+ * in an SSR-safe way. This component should be rendered once at the app root level.
+ *
+ * The config is applied inside a useEffect, which means it only runs on the client
+ * and is never executed during server-side rendering.
+ *
+ * @example
+ * ```tsx
+ * // In your app root
+ * <OptixFlowConfig config={{ apiKey: 'your-api-key' }}>
+ *   <App />
+ * </OptixFlowConfig>
+ * ```
+ *
+ * Or without children:
+ * ```tsx
+ * <OptixFlowConfig config={{ apiKey: 'your-api-key' }} />
+ * ```
+ */
+export declare function OptixFlowConfig({ config, children, }: OptixFlowConfigProps): React.ReactElement | null;

package/dist/core/OptixFlowConfig.js

@@ -0,0 +1,30 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { setDefaultOptixFlowConfig } from "./Img.js";
+/**
+ * A component that sets the default OptixFlow configuration for all Img components
+ * in an SSR-safe way. This component should be rendered once at the app root level.
+ *
+ * The config is applied inside a useEffect, which means it only runs on the client
+ * and is never executed during server-side rendering.
+ *
+ * @example
+ * ```tsx
+ * // In your app root
+ * <OptixFlowConfig config={{ apiKey: 'your-api-key' }}>
+ *   <App />
+ * </OptixFlowConfig>
+ * ```
+ *
+ * Or without children:
+ * ```tsx
+ * <OptixFlowConfig config={{ apiKey: 'your-api-key' }} />
+ * ```
+ */
+export function OptixFlowConfig({ config, children, }) {
+    React.useEffect(() => {
+        setDefaultOptixFlowConfig(config ?? null);
+    }, [config]);
+    return children ? _jsx(_Fragment, { children: children }) : null;
+}

package/dist/core/index.cjs

@@ -1 +1,2 @@
-export { Img, setDefaultOptixFlowConfig } from './Img.js';
+export { Img, setDefaultOptixFlowConfig } from "./Img.js";
+export { OptixFlowConfig } from "./OptixFlowConfig.js";

package/dist/core/index.d.ts

@@ -1 +1,4 @@
-export { Img, setDefaultOptixFlowConfig } from './Img.js';
+export { Img, setDefaultOptixFlowConfig } from "./Img.js";
+export type { ImgProps } from "./Img.js";
+export { OptixFlowConfig } from "./OptixFlowConfig.js";
+export type { OptixFlowConfigProps } from "./OptixFlowConfig.js";

package/dist/core/index.js

@@ -1 +1,2 @@
-export { Img, setDefaultOptixFlowConfig } from './Img.js';
+export { Img, setDefaultOptixFlowConfig } from "./Img.js";
+export { OptixFlowConfig } from "./OptixFlowConfig.js";

package/dist/core/useImgDebugLog.cjs

@@ -0,0 +1,46 @@
+import { useEffect, useRef } from "react";
+/**
+ * Logs image-request details to the console when `enabled` is true.
+ * When disabled (the default), the hook short-circuits on the very first
+ * line so there is no meaningful runtime cost.
+ */
+export function useImgDebugLog({ enabled, eagerLoad, isInView, imgSrc, transparentPixel, srcset, sizesAttr, }) {
+    const logKeyRef = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (typeof window === "undefined")
+            return;
+        if (!eagerLoad && !isInView)
+            return;
+        if (!imgSrc || imgSrc === transparentPixel)
+            return;
+        const logKey = [
+            imgSrc,
+            srcset.avif,
+            srcset.webp,
+            srcset.jpeg,
+            sizesAttr ?? "",
+        ].join("|");
+        if (logKeyRef.current === logKey)
+            return;
+        logKeyRef.current = logKey;
+        if (typeof console !== "undefined" && console.info) {
+            console.info("[PageSpeedImg] image request", {
+                src: imgSrc,
+                srcset,
+                sizes: sizesAttr,
+            });
+        }
+    }, [
+        enabled,
+        eagerLoad,
+        imgSrc,
+        isInView,
+        sizesAttr,
+        srcset.avif,
+        srcset.webp,
+        srcset.jpeg,
+        transparentPixel,
+    ]);
+}

package/dist/core/useImgDebugLog.d.ts

@@ -0,0 +1,20 @@
+interface ImgDebugLogParams {
+    enabled: boolean;
+    eagerLoad: boolean;
+    isInView: boolean;
+    imgSrc: string;
+    transparentPixel: string;
+    srcset: {
+        avif: string;
+        webp: string;
+        jpeg: string;
+    };
+    sizesAttr: string | undefined;
+}
+/**
+ * Logs image-request details to the console when `enabled` is true.
+ * When disabled (the default), the hook short-circuits on the very first
+ * line so there is no meaningful runtime cost.
+ */
+export declare function useImgDebugLog({ enabled, eagerLoad, isInView, imgSrc, transparentPixel, srcset, sizesAttr, }: ImgDebugLogParams): void;
+export {};

package/dist/core/useImgDebugLog.js

@@ -0,0 +1,46 @@
+import { useEffect, useRef } from "react";
+/**
+ * Logs image-request details to the console when `enabled` is true.
+ * When disabled (the default), the hook short-circuits on the very first
+ * line so there is no meaningful runtime cost.
+ */
+export function useImgDebugLog({ enabled, eagerLoad, isInView, imgSrc, transparentPixel, srcset, sizesAttr, }) {
+    const logKeyRef = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (typeof window === "undefined")
+            return;
+        if (!eagerLoad && !isInView)
+            return;
+        if (!imgSrc || imgSrc === transparentPixel)
+            return;
+        const logKey = [
+            imgSrc,
+            srcset.avif,
+            srcset.webp,
+            srcset.jpeg,
+            sizesAttr ?? "",
+        ].join("|");
+        if (logKeyRef.current === logKey)
+            return;
+        logKeyRef.current = logKey;
+        if (typeof console !== "undefined" && console.info) {
+            console.info("[PageSpeedImg] image request", {
+                src: imgSrc,
+                srcset,
+                sizes: sizesAttr,
+            });
+        }
+    }, [
+        enabled,
+        eagerLoad,
+        imgSrc,
+        isInView,
+        sizesAttr,
+        srcset.avif,
+        srcset.webp,
+        srcset.jpeg,
+        transparentPixel,
+    ]);
+}

package/dist/index.cjs

@@ -13,3 +13,5 @@ if (globalObject) {
     }
 }
 export * from './core/index.js';
+// Re-export specific items for clarity and CDN usage
+export { Img, setDefaultOptixFlowConfig, OptixFlowConfig } from './core/index.js';

package/dist/index.d.ts

@@ -2,3 +2,5 @@ import type { UseOptimizedImageOptions } from '@page-speed/hooks/media';
 export * from './core/index.js';
 export type { ImageFormat, SrcsetByFormat, UseOptimizedImageOptions, UseOptimizedImageState, } from '@page-speed/hooks/media';
 export type OptixFlowConfig = UseOptimizedImageOptions['optixFlowConfig'];
+export { Img, setDefaultOptixFlowConfig, OptixFlowConfig } from './core/index.js';
+export type { ImgProps, OptixFlowConfigProps } from './core/index.js';

package/dist/index.js

@@ -13,3 +13,5 @@ if (globalObject) {
     }
 }
 export * from './core/index.js';
+// Re-export specific items for clarity and CDN usage
+export { Img, setDefaultOptixFlowConfig, OptixFlowConfig } from './core/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@page-speed/img",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Performance-optimized React Image component. Drop-in image implementation of web.dev best practices with zero configuration.",
   "keywords": [
     "react",
@@ -25,7 +25,7 @@
     "url": "https://github.com/opensite-ai/page-speed-img/issues"
   },
   "author": "OpenSite AI (https://opensite.ai)",
-  "license": "BSD 3",
+  "license": "BSD-3-Clause",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",
@@ -66,7 +66,7 @@
     "bundle-analysis": "node scripts/analyze-bundle.js || true",
     "prepare": "husky",
     "prepack": "pnpm run build",
-    "prepublishOnly": "pnpm run build"
+    "prepublishOnly": "pnpm run build && pnpm run test"
   },
   "peerDependencies": {
     "react": ">=17.0.0",
@@ -75,6 +75,7 @@
   "devDependencies": {
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^20.17.6",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
@@ -90,7 +91,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@opensite/hooks": "2.0.3",
+    "@opensite/hooks": "2.1.0",
     "@page-speed/hooks": "0.4.5"
   },
   "packageManager": "pnpm@10.24.0",

package/dist/browser/opensite-img.umd.cjs

@@ -1,2 +0,0 @@
-!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?e(exports,require("react")):"function"==typeof define&&define.amd?define(["exports","react"],e):e((t="undefined"!=typeof globalThis?globalThis:t||self).OpensiteImg={},t.React)}(this,function(t,e){"use strict";const n=new Map;function i(t,e){n.set(t,e)}const r="https://cdn.ing";function l(t){return(t??r).replace(/\/$/,"")}function o(t,e){return`${l(e)}/assets/images/${t}`}function s(t,e){return`${l(e)}/i/r/${t}`}function a(t){return!!t&&["AVIF","WEBP","JPEG"].some(e=>{const n=null==t?void 0:t[e];return!!(i=n)&&[i.sm,i.md,i.lg,i.full].some(t=>"string"==typeof t&&t.trim().length>0);var i})}function u(t){return"string"==typeof t&&t.trim().length>0}function d(t){var e;if(!t)return!1;if(a((null==(e=t.variants_data)?void 0:e.variants)??null))return!0;const n=t;return[n.img_url,n.file_data_url,n.file_data_thumbnail_url,n.img_src,n.med_src,n.thumb_src,n.low_res_thumb].some(u)}async function c(t,e){const n=await fetch(t,{signal:e});if(!n.ok){const e=new Error(`Failed to fetch image data (status ${n.status}) from ${t}`);throw e.status=n.status,e}return await n.json()}async function f(t,e={}){if(!Number.isFinite(t))throw new Error("Invalid mediaId provided to fetchImageData");const r=l(e.cdnHost),a=`image:${r}:${t}`;if(!e.bypassCache){const t=(u=a,n.get(u));if(t)return t}var u;const f=[o(t,r),s(t,r)];let m;for(const n of f)try{const t=await c(n,e.signal);return d(t)&&i(a,t),t}catch(v){if("AbortError"===(null==v?void 0:v.name))throw v;m=v}if(m instanceof Error)throw m;throw new Error(`Failed to fetch image data for mediaId ${t}`)}const m="dt:media-selected";function v(t){t&&t.querySelectorAll("source").forEach(t=>{const e=t.getAttribute("srcset");e&&(t.setAttribute("data-srcset",e),t.removeAttribute("srcset"),requestAnimationFrame(()=>{t.setAttribute("srcset",e)}))})}const g={sm:640,md:1024,lg:1536,full:2560},h=t=>"string"==typeof t&&t.trim().length>0;function p(t){const e=null==t?void 0:t.widths;return e?{sm:e.small??e.sm??g.sm,md:e.medium??e.md??g.md,lg:e.large??e.lg??g.lg,full:e.full_size??e.full??g.full}:null}function w(t){if(t)return t.md||t.lg||t.sm||t.full||Object.values(t).find(Boolean)}const _=e.forwardRef(function({mediaId:t,cdnHost:n,sizes:i,onImageData:o,loading:s,decoding:u,alt:d,title:c,src:_,...E},b){const y=e.useRef(null);e.useImperativeHandle(b,()=>y.current);!function(t){e.useEffect(()=>{const e=t.current;e&&(e instanceof HTMLPictureElement?v(e):e.parentElement instanceof HTMLPictureElement&&v(e.parentElement))},[t])}(e.useRef(null)),e.useEffect(()=>{if("undefined"==typeof window)return;const t=()=>{};return window.addEventListener(m,t),()=>window.removeEventListener(m,t)},[]);const[$,I]=e.useState(null),[S,M]=e.useState(0),x=Number.isFinite(t),z=s??"lazy",A=u??"async",[O,N]=e.useState(()=>!x||"lazy"!==z),P=e.useMemo(()=>(n??r).replace(/\/$/,""),[n]);e.useEffect(()=>{if(!x)return I(null),void M(0);I(null),M(0)},[x,t,n]),e.useEffect(()=>{if(!x)return;const e=new AbortController;return f(t,{cdnHost:n,signal:e.signal,bypassCache:S>0}).then(t=>{I(t),null==o||o(t)}).catch(t=>{"AbortError"!==(null==t?void 0:t.name)&&console.warn("Image data fetch failed:",t)}),()=>e.abort()},[x,t,n,o,S]),e.useEffect(()=>{N(!x||"lazy"!==z)},[x,t,z]),e.useEffect(()=>{if(!x||"lazy"!==z||O)return;if("undefined"==typeof window||void 0===window.IntersectionObserver)return void N(!0);const t=y.current;if(!t)return;const e=new IntersectionObserver(t=>{t.some(t=>t.isIntersecting)&&(N(!0),e.disconnect())},{rootMargin:"200px"});return e.observe(t),()=>e.disconnect()},[x,z,O]);const T=e.useMemo(()=>{var t,e,n;if(!$)return null;const i=(null==(t=$.variants_data)?void 0:t.variants)??{},r=i.WEBP,l=i.AVIF,o=i.JPEG,s=p(null==(e=i.WEBP)?void 0:e.metadata)||p(null==(n=i.JPEG)?void 0:n.metadata)||{...g},a=t=>(t=>{if(h(t))return/^https?:\/\//i.test(t)||t.startsWith("data:")?t:t.startsWith("//")?`https:${t}`:t.startsWith("/")?`${P}${t}`:`${P}/${t}`})("string"==typeof t?t:void 0),u=[w(r),w(o),w(l),null==r?void 0:r.sm,null==r?void 0:r.md,null==r?void 0:r.lg,null==r?void 0:r.full,null==o?void 0:o.sm,null==o?void 0:o.md,null==o?void 0:o.lg,null==o?void 0:o.full,null==l?void 0:l.sm,null==l?void 0:l.md,null==l?void 0:l.lg,null==l?void 0:l.full].map(t=>a(t??void 0)).filter(h),d=$,c=[d.img_url,d.file_data_url,d.file_data_thumbnail_url,d.img_src,d.med_src,d.thumb_src,d.low_res_thumb].map(t=>h(t)?a(t):void 0).filter(h),f=d.fallback_url?[a(d.fallback_url)].filter(h):[],m=[...u,...c,...f][0];if(!m)return null;return{webp:r,avif:l,jpeg:o,toSrcSet:t=>{if(!t)return;const e=[],n=(t,n)=>{const i=a(t);i&&n&&e.push(`${i} ${n}w`)};return n(t.sm,s.sm),n(t.md,s.md),n(t.lg,s.lg),n(t.full,s.full),e.length?e.join(", "):void 0},fallback:m,widths:s,hasVariantSource:u.length>0}},[$,P]),j=e.useMemo(()=>{var t;return a((null==(t=null==$?void 0:$.variants_data)?void 0:t.variants)??null)},[$]),F=e.useMemo(()=>{var t;const e=(null==(t=null==$?void 0:$.variants_data)?void 0:t.status)??(null==$?void 0:$.variants_status)??"";return"string"==typeof e?e.toLowerCase():""},[$]),k="failed"===F||"error"===F,H=x&&Boolean($)&&!k&&!j&&S<5;e.useEffect(()=>{if(!H)return;if("undefined"==typeof window)return;const t=window.setTimeout(()=>{M(t=>t+1)},3e3);return()=>window.clearTimeout(t)},[H]);const L=e.useMemo(()=>{var t,e;return"string"==typeof d?d:(null==(e=null==(t=null==$?void 0:$.meta)?void 0:t.content_manifest)?void 0:e.summary)??void 0},[d,$]),V=e.useMemo(()=>{var t,e;return"string"==typeof c?c:(null==(e=null==(t=null==$?void 0:$.meta)?void 0:t.content_manifest)?void 0:e.title)??void 0},[c,$]),W=e.useMemo(()=>{var t,e,n,i;return(null==(e=null==(t=null==$?void 0:$.meta)?void 0:t.sizing)?void 0:e.width)??(null==(i=null==(n=null==$?void 0:$.variants_data)?void 0:n.metadata)?void 0:i.width)??void 0},[$]),B=e.useMemo(()=>{var t,e,n,i;return(null==(e=null==(t=null==$?void 0:$.meta)?void 0:t.sizing)?void 0:e.height)??(null==(i=null==(n=null==$?void 0:$.variants_data)?void 0:n.metadata)?void 0:i.height)??void 0},[$]),C=e.useMemo(()=>{var t,e;const n=null==(e=null==(t=null==$?void 0:$.meta)?void 0:t.content_manifest)?void 0:e.optimized_filename;if(!n)return;const i=null==T?void 0:T.fallback;if(!i)return;const r=i.lastIndexOf(".");return`${n}.${r>-1?i.slice(r+1).toLowerCase():"jpg"}`},[$,T]);if(!x){const t={...E};return e.createElement("img",{ref:y,src:_,loading:z,decoding:A,alt:L,title:V,width:t.width,height:t.height,...t})}const D=function(t,e){return`${l(e)}/assets/low_res_thumb/${t}`}(t,n);if(!$||!T||!O){const t={...E};return e.createElement("img",{ref:y,src:D,loading:z,decoding:A,alt:L,title:V,width:t.width??W,height:t.height??B,...t})}const R=i??"(max-width:640px) 640px, (max-width:1024px) 1024px, 1536px",{webp:q,avif:G,jpeg:J,toSrcSet:K,fallback:Q}=T,U=K(q),X=K(G),Y=K(J);return U||X||Y?e.createElement("picture",null,X?e.createElement("source",{type:"image/avif",srcSet:X,sizes:R}):null,U?e.createElement("source",{type:"image/webp",srcSet:U,sizes:R}):null,e.createElement("img",{ref:y,src:Q,srcSet:!Y||U||X?void 0:Y,sizes:!Y||U||X?void 0:R,loading:z,decoding:A,alt:L,title:V,width:W,height:B,"data-filename":C,...E})):e.createElement("img",{ref:y,src:Q,loading:z,decoding:A,alt:L,title:V,width:W,height:B,"data-filename":C,...E})}),E=e.memo(_);E.displayName="OpenSiteImg";const b="undefined"!=typeof globalThis?globalThis:void 0;if(b)if(b.process){const t=b.process.env??(b.process.env={});void 0===t.NODE_ENV&&(t.NODE_ENV="production")}else b.process={env:{NODE_ENV:"production"}};t.Img=E,Object.defineProperty(t,Symbol.toStringTag,{value:"Module"})});
-//# sourceMappingURL=opensite-img.umd.js.map