react-a11y-auto-caption 1.0.1 → 1.0.4

package/README.md

@@ -1,53 +1,66 @@
 # react-a11y-auto-caption
 
 > A smart React & Next.js component <br/>
-that automatically generates highly accurate `alt` text for images using AI.<br/>
-**Generate captions effortlessly during local development, <br/>
-save them to your database, and serve 100% accessible images in production<br/>
-with zero API costs and zero latency.**
+> that automatically generates highly accurate `alt` text for images using AI.<br/>
+> **Generate captions effortlessly during local development, <br/>
+> save them to your database, and serve 100% accessible images in production<br/>
+> with zero API costs and zero latency.**
 
 [![npm version](https://img.shields.io/npm/v/react-a11y-auto-caption.svg)](https://www.npmjs.com/package/react-a11y-auto-caption)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Accessibility](https://img.shields.io/badge/Accessibility-100%25-brightgreen.svg)]()
 
+---
+
 ## Why use this library?
 
-- **Generate Once, Serve Forever (Best Practice):** Automatically generate captions during local development, easily save them to your database using the `onCaptionGenerated` callback, and completely bypass AI requests in production. 
+- **Generate Once, Serve Forever (Best Practice):** Automatically generate captions during local development, easily save them to your database using the `onCaptionGenerated` callback, and completely bypass AI requests in production.
 - **Cost-Free Local AI Server:** Comes with a ready-to-use, lightweight FastAPI Python server. It runs perfectly on your local machine, meaning you don't need to pay for expensive cloud GPUs or third-party API subscriptions (like OpenAI).
 - **Zero-Config Accessibility:** Automatically describes images for screen readers without manual data entry.
-- **First-Class Next.js Support:** Provides a dedicated `<SmartNextImage>` component optimized for Next.js.
-- **Smart Request Caching:** Built-in memory caching prevents duplicate API calls for the same image, saving your server costs.
+- **First-Class Next.js Support:** Provides a dedicated `<SmartNextImage>` component optimized for Next.js, supporting both static imports and URL strings.
+- **Smart LRU Caching:** Built-in LRU memory cache (max 500 entries) prevents duplicate API calls and unbounded memory growth.
 - **Concurrent Request Defense:** Safely handles simultaneous renders of the same image across multiple components.
+- **Reliable Error Handling:** Exposes errors via both `onCaptionError` callback and returned `error` state for full control over failure UX.
 - **Global Provider Pattern:** Set your API endpoint once at the root level and forget about it.
 - **Developer Experience (DX):** Built-in test mode (`disableAI`) and intelligent console warnings for smooth debugging.
 
 ---
 
+## What's New in v1.1.0
+
+- **LRU Cache:** Replaced unbounded `Map` cache with an LRU implementation to prevent memory leaks in long-running apps.
+- **`onCaptionError` callback:** New prop to handle caption generation failures externally (e.g. logging, toast notifications).
+- **`error` state:** `useAICaptions` hook now returns an `error` field so you can branch your UI on failure.
+- **Unmount safety:** Caption generation is now safely cancelled when a component unmounts, preventing stale state updates.
+- **Next.js static import support:** `<SmartNextImage>` now correctly resolves both `StaticImageData` and `StaticRequire` import types.
+- **Subpath exports:** Added `react-a11y-auto-caption/next` entry point for cleaner Next.js-specific imports.
+
+---
+
 ## Installation
 
-npm
 ```bash
+# npm
 npm install react-a11y-auto-caption
-```
-yarn berry
-```bash
+
+# yarn
 yarn add react-a11y-auto-caption
-```
-pnpm
-```bash
+
+# pnpm
 pnpm add react-a11y-auto-caption
 ```
 
 ---
+
 ## Quick Start
 
-### 1. Wrap your app with the Provider (Optional but Recommended) <br/>
-Set your backend API endpoint once globally. <br/>
-Otherwise, you can simply pass apiEndpoint as a prop when using `<SmartImage>` <br/>
+### 1. Wrap your app with the Provider (Optional but Recommended)
 
-```ts
+Set your backend API endpoint once globally. Otherwise, pass `apiEndpoint` directly as a prop.
+
+```tsx
 // App.tsx or layout.tsx
-import { SmartImageProvider } from 'react-a11y-auto-caption';
+import { SmartImageProvider } from "react-a11y-auto-caption";
 
 export default function App({ children }) {
   return (
@@ -57,96 +70,99 @@ export default function App({ children }) {
   );
 }
 ```
+
 ### 2. Use it in your components
-For Vanilla React (Vite, CRA):<br/>
-```ts
-import { SmartImage } from 'react-a11y-auto-caption';
+
+**Vanilla React (Vite, CRA):**
+
+```tsx
+import { SmartImage } from "react-a11y-auto-caption";
 
 function Gallery() {
-  return (
-    <SmartImage 
-      src="[https://example.com/beautiful-landscape.jpg](https://example.com/beautiful-landscape.jpg)" 
-      announceLive={true} 
-    />
-  );
+  return <SmartImage src="https://example.com/beautiful-landscape.jpg" announceLive={true} />;
 }
 ```
 
-For Next.js: <br/>
-```ts
-import { SmartNextImage } from 'react-a11y-auto-caption';
-import dogPic from '../public/dog.jpg';
+**Next.js:**
+
+```tsx
+import { SmartNextImage } from "react-a11y-auto-caption/next";
+import dogPic from "../public/dog.jpg";
 
 function NextGallery() {
-  return (
-    <SmartNextImage 
-      src={dogPic} 
-      width={500} 
-      height={300}
-      // You can override global settings per component
-      disableAI={process.env.NODE_ENV === 'development'} 
-    />
-  );
+  return <SmartNextImage src={dogPic} width={500} height={300} disableAI={process.env.NODE_ENV === "production"} />;
 }
 ```
----
 
-## API Reference 
-Both `SmartImage` and `SmartNextImage` inherit all standard `<img>` / `next/image` props, plus the following: <br/>
-## API Reference (Props)
+---
 
-Both `<SmartImage>` and `<SmartNextImage>` inherit all standard HTML `<img>` (or `next/image`) attributes. The following custom props are available:
+## API Reference
 
-| Prop | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `apiEndpoint` | `string` | `undefined` | The URL of your AI backend API. Overrides the `SmartImageProvider`'s endpoint if provided. |
-| `alt` | `string` | `undefined` | Manual alt text. If provided, the AI generation is completely bypassed. |
-| `fallbackAlt` | `string` | `"Image loading or caption unavailable"` | The text displayed if the AI API request fails or times out. |
-| `disableAI` | `boolean` | `false` | Disables AI generation and uses a mock caption. Highly recommended for local development and testing. |
-| `announceLive` | `boolean` | `false` | Enables `aria-live` regions to dynamically announce the generation status to screen readers. |
-| `onCaptionGenerated`| `function` | `undefined` | Callback fired when a caption is successfully generated. `(caption: string) => void` |
+Both `<SmartImage>` and `<SmartNextImage>` inherit all standard HTML `<img>` (or `next/image`) attributes, plus the following:
 
-> **Note:** If you are using `<SmartNextImage>`, you must also provide standard required Next.js image props such as `width` and `height` (unless using `fill`).
----
-## Security & Backend Integration
+| Prop                 | Type                        | Default                                  | Description                                                                              |
+| :------------------- | :-------------------------- | :--------------------------------------- | :--------------------------------------------------------------------------------------- |
+| `apiEndpoint`        | `string`                    | `undefined`                              | The URL of your AI backend API. Overrides the `SmartImageProvider` endpoint if provided. |
+| `alt`                | `string`                    | `undefined`                              | Manual alt text. If provided, AI generation is completely bypassed.                      |
+| `fallbackAlt`        | `string`                    | `"Image loading or caption unavailable"` | Text used when the AI request fails or times out.                                        |
+| `disableAI`          | `boolean`                   | `false`                                  | Disables AI generation and uses a mock caption. Recommended for testing.                 |
+| `announceLive`       | `boolean`                   | `false`                                  | Enables `aria-live` region to announce generation status to screen readers.              |
+| `onCaptionGenerated` | `(caption: string) => void` | `undefined`                              | Callback fired when a caption is successfully generated.                                 |
+| `onCaptionError`     | `(error: Error) => void`    | `undefined`                              | Callback fired when caption generation fails. Use for logging or toast notifications.    |
 
-This package requires a backend to process the images through an AI model (like ViT-GPT2). <br/>
-We provide a ready-to-use FastAPI reference server in [this repository.](https://github.com/kong33/SmartImage)<br/>
+> **Note:** `<SmartNextImage>` requires standard Next.js image props such as `width` and `height` (unless using `fill`).
 
-Depending on your architecture, choose one of the following integration methods:<br/>
 ---
-### First step: Deploying our Standalone AI Microservice
-For security reasons, all cross-origin requests are blocked by default. <br/>
-You MUST set the ALLOWED_ORIGINS environment variable in your server's .env file<br/>
-to allow your frontend to communicate with it. <br/>
 
+## Error Handling
+
+You can handle errors in two ways depending on your use case.
 
-```python
-# For production
+**Via callback** — for external handling like logging or toasts:
 
-# .env file on your Python server
-ALLOWED_ORIGINS=https://your-frontend-domain.com,https://your-frontend-domain2.com
+```tsx
+<SmartImage src={imageUrl} onCaptionError={(err) => toast.error(err.message)} />
 ```
-```python
-# For local development
 
-# .env file on your Python server
-ALLOWED_ORIGINS=http://localhost:3000
+**Via `useAICaptions` hook** — for UI branching:
+
+```tsx
+const { generatedAlt, isGenerating, error } = useAICaptions({ src });
+
+if (error) return <p>Failed to generate caption.</p>;
 ```
-> **Note:** Change the port if you are using Vite 5173 or another local server. You can allow multiple environments simultaneously by separating them with a comma (no spaces).
 
 ---
 
 ## Best Practice: Generate Once, Save, Reuse
-Generating captions on-the-fly for every user is slow. <br/>
-The industry standard is to generate the caption once and save it to your database:
+
+Generating captions on-the-fly for every user is slow. The recommended pattern is to generate once and persist to your database:
 
 ```tsx
-<SmartImage 
+<SmartImage
   src={image.url}
-  alt={image.savedAlt} // If provided, the AI sleeps!
+  alt={image.savedAlt} // If provided, AI is skipped entirely
   apiEndpoint="http://localhost:8000/api/generate-caption"
   onCaptionGenerated={(text) => {
-    saveToDatabase(image.id, text); // Save permanently (You create your own database saving function based on your code.) 
+    saveToDatabase(image.id, text);
   }}
 />
+```
+
+---
+
+## Security & Backend Integration
+
+This package requires a backend to process images through an AI model (e.g. ViT-GPT2). We provide a ready-to-use FastAPI reference server in [this repository](https://github.com/kong33/SmartImage).
+
+For security, all cross-origin requests are blocked by default. Set the `ALLOWED_ORIGINS` environment variable in your server's `.env` file:
+
+```bash
+# Production
+ALLOWED_ORIGINS=https://your-frontend-domain.com
+
+# Local development
+ALLOWED_ORIGINS=http://localhost:3000
+```
+
+> **Note:** Separate multiple origins with a comma and no spaces. Adjust the port if using Vite (`5173`) or another local server.

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import React, { ImgHTMLAttributes } from "react";
+export declare const SmartImageProvider: React.FC<{
+    value: {
+        apiEndpoint?: string;
+        disableAI?: boolean;
+    };
+    children: React.ReactNode;
+}>;
+export interface SmartImageProps extends ImgHTMLAttributes<HTMLImageElement> {
+    src?: string;
+    apiEndpoint?: string;
+    fallbackAlt?: string;
+    onCaptionGenerated?: (caption: string) => void;
+    disableAI?: boolean;
+    announceLive?: boolean;
+    onCaptionError?: (error: Error) => void;
+}
+export declare const SmartImage: ({ src, alt, apiEndpoint: propsEndpoint, fallbackAlt, onCaptionGenerated, disableAI: propsDisableAI, announceLive, onCaptionError, ...props }: SmartImageProps) => import("react/jsx-runtime").JSX.Element;

package/dist/index.js

@@ -0,0 +1,213 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  SmartImage: () => SmartImage,
+  SmartImageProvider: () => SmartImageProvider
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useAICaption.ts
+var import_react = require("react");
+var SmartImageContext = (0, import_react.createContext)(void 0);
+var MAX_SIZE = 500;
+var LRUCaptionCache = class {
+  constructor() {
+    this.cache = /* @__PURE__ */ new Map();
+  }
+  get(key) {
+    return this.cache.get(key);
+  }
+  set(key, value) {
+    if (this.cache.size >= MAX_SIZE) {
+      this.cache.delete(this.cache.keys().next().value);
+    }
+    this.cache.set(key, value);
+  }
+  has(key) {
+    return this.cache.has(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+};
+var captionCache = new LRUCaptionCache();
+var pendingRequestCache = /* @__PURE__ */ new Map();
+function isStaticImageData(src) {
+  return typeof src === "object" && src !== null && "src" in src;
+}
+function resolveImageUrl(src) {
+  if (typeof src === "string") return src;
+  if (isStaticImageData(src)) return src.src;
+  return src.default.src;
+}
+var log = process.env.NODE_ENV === "development" ? console.log : () => {
+};
+var useAICaptions = ({
+  src,
+  alt,
+  apiEndpoint: propsEndpoint,
+  fallbackAlt = "Image loading or caption unavailable",
+  onCaptionGenerated,
+  disableAI: propsDisableAI,
+  onCaptionError
+}) => {
+  const context = (0, import_react.useContext)(SmartImageContext);
+  const apiEndpoint = propsEndpoint || context?.apiEndpoint;
+  const disableAI = propsDisableAI ?? context?.disableAI ?? false;
+  const [generatedAlt, setGeneratedAlt] = (0, import_react.useState)("");
+  const [isGenerating, setIsGenerating] = (0, import_react.useState)(false);
+  const [error, setError] = (0, import_react.useState)(null);
+  const onCaptionGeneratedRef = (0, import_react.useRef)(onCaptionGenerated);
+  const onCaptionErrorRef = (0, import_react.useRef)(onCaptionError);
+  (0, import_react.useEffect)(() => {
+    onCaptionGeneratedRef.current = onCaptionGenerated;
+    onCaptionErrorRef.current = onCaptionError;
+  });
+  (0, import_react.useEffect)(() => {
+    setError(null);
+    if (alt) {
+      setGeneratedAlt(alt);
+      return;
+    }
+    if (!src) return;
+    if (disableAI) {
+      setGeneratedAlt("[Testing mode: AI caption generation disabled]");
+      return;
+    }
+    if (!apiEndpoint) {
+      console.warn(
+        "[SmartImage] Missing 'apiEndpoint' prop. Please provide a backend API URL via props or SmartImageProvider to enable AI caption generation."
+      );
+      setGeneratedAlt(fallbackAlt);
+      return;
+    }
+    const imageUrl = resolveImageUrl(src);
+    if (captionCache.has(imageUrl)) {
+      log("[SmartImage] Cache hit: Reusing existing caption.");
+      const cachedCaption = captionCache.get(imageUrl);
+      setGeneratedAlt(cachedCaption);
+      if (onCaptionGeneratedRef.current) onCaptionGeneratedRef.current(cachedCaption);
+      return;
+    }
+    let cancelled = false;
+    const generateCaption = async () => {
+      setIsGenerating(true);
+      try {
+        if (pendingRequestCache.has(imageUrl)) {
+          log("[SmartImage] Pending request detected. Waiting for the existing API call to complete.");
+          const caption = await pendingRequestCache.get(imageUrl);
+          if (cancelled) return;
+          setGeneratedAlt(caption);
+          if (onCaptionGeneratedRef.current) onCaptionGeneratedRef.current(caption);
+          return;
+        }
+        const fetchPromise = (async () => {
+          const imageResponse = await fetch(imageUrl);
+          const imageBlob = await imageResponse.blob();
+          const imageFile = new File([imageBlob], "image.jpg", {
+            type: imageBlob.type || "image/jpeg"
+          });
+          const formData = new FormData();
+          formData.append("file", imageFile);
+          const response = await fetch(apiEndpoint, {
+            method: "POST",
+            body: formData
+          });
+          if (!response.ok) throw new Error("AI API request failed");
+          const data = await response.json();
+          if (data.caption) return data.caption;
+          throw new Error("No caption returned from the API.");
+        })();
+        pendingRequestCache.set(imageUrl, fetchPromise);
+        const newCaption = await fetchPromise;
+        pendingRequestCache.delete(imageUrl);
+        captionCache.set(imageUrl, newCaption);
+        if (cancelled) return;
+        setGeneratedAlt(newCaption);
+        if (onCaptionGeneratedRef.current) onCaptionGeneratedRef.current(newCaption);
+      } catch (err) {
+        const normalizedError = err instanceof Error ? err : new Error("Unknown error");
+        pendingRequestCache.delete(imageUrl);
+        if (cancelled) return;
+        setError(normalizedError);
+        setGeneratedAlt(fallbackAlt);
+        if (onCaptionErrorRef.current) onCaptionErrorRef.current(normalizedError);
+      } finally {
+        if (!cancelled) setIsGenerating(false);
+      }
+    };
+    generateCaption();
+    return () => {
+      cancelled = true;
+    };
+  }, [src, alt, apiEndpoint, fallbackAlt, disableAI]);
+  return { generatedAlt, isGenerating, error };
+};
+
+// src/index.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var SmartImageProvider = ({ value, children }) => {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SmartImageContext.Provider, { value, children });
+};
+var SR_ONLY_STYLE = {
+  position: "absolute",
+  width: "1px",
+  height: "1px",
+  padding: 0,
+  margin: "-1px",
+  overflow: "hidden",
+  clip: "rect(0, 0, 0, 0)",
+  whiteSpace: "nowrap",
+  borderWidth: 0
+};
+var SmartImage = ({
+  src,
+  alt,
+  apiEndpoint: propsEndpoint,
+  fallbackAlt = "Image loading or caption unavailable",
+  onCaptionGenerated,
+  disableAI: propsDisableAI,
+  announceLive = false,
+  onCaptionError,
+  ...props
+}) => {
+  const { isGenerating, generatedAlt } = useAICaptions({
+    src,
+    alt,
+    apiEndpoint: propsEndpoint,
+    fallbackAlt,
+    onCaptionGenerated,
+    disableAI: propsDisableAI,
+    announceLive,
+    onCaptionError
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+    announceLive && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: SR_ONLY_STYLE, "aria-live": "polite", "aria-atomic": "true", children: isGenerating ? "Generating image description. Please wait..." : generatedAlt ? `Image description generated: ${generatedAlt}` : "" }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("img", { src, alt: generatedAlt, "aria-busy": isGenerating, ...props })
+  ] });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SmartImage,
+  SmartImageProvider
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx","../src/useAICaption.ts"],"sourcesContent":["import React, { ImgHTMLAttributes } from \"react\";\r\nimport { SmartImageContext, useAICaptions } from \"./useAICaption\";\r\n\r\nexport const SmartImageProvider: React.FC<{\r\n  value: { apiEndpoint?: string; disableAI?: boolean };\r\n  children: React.ReactNode;\r\n}> = ({ value, children }) => {\r\n  return <SmartImageContext.Provider value={value}>{children}</SmartImageContext.Provider>;\r\n};\r\n\r\nexport interface SmartImageProps extends ImgHTMLAttributes<HTMLImageElement> {\r\n  src?: string;\r\n  apiEndpoint?: string;\r\n  fallbackAlt?: string;\r\n  onCaptionGenerated?: (caption: string) => void;\r\n  disableAI?: boolean;\r\n  announceLive?: boolean;\r\n  onCaptionError?: (error: Error) => void;\r\n}\r\n\r\nconst SR_ONLY_STYLE: React.CSSProperties = {\r\n  position: \"absolute\",\r\n  width: \"1px\",\r\n  height: \"1px\",\r\n  padding: 0,\r\n  margin: \"-1px\",\r\n  overflow: \"hidden\",\r\n  clip: \"rect(0, 0, 0, 0)\",\r\n  whiteSpace: \"nowrap\",\r\n  borderWidth: 0,\r\n};\r\n\r\nexport const SmartImage = ({\r\n  src,\r\n  alt,\r\n  apiEndpoint: propsEndpoint,\r\n  fallbackAlt = \"Image loading or caption unavailable\",\r\n  onCaptionGenerated,\r\n  disableAI: propsDisableAI,\r\n  announceLive = false,\r\n  onCaptionError,\r\n  ...props\r\n}: SmartImageProps) => {\r\n  const { isGenerating, generatedAlt } = useAICaptions({\r\n    src,\r\n    alt,\r\n    apiEndpoint: propsEndpoint,\r\n    fallbackAlt,\r\n    onCaptionGenerated,\r\n    disableAI: propsDisableAI,\r\n    announceLive,\r\n    onCaptionError,\r\n  });\r\n\r\n  return (\r\n    <>\r\n      {announceLive && (\r\n        <span style={SR_ONLY_STYLE} aria-live=\"polite\" aria-atomic=\"true\">\r\n          {isGenerating\r\n            ? \"Generating image description. Please wait...\"\r\n            : generatedAlt\r\n              ? `Image description generated: ${generatedAlt}`\r\n              : \"\"}\r\n        </span>\r\n      )}\r\n      <img src={src} alt={generatedAlt} aria-busy={isGenerating} {...props} />\r\n    </>\r\n  );\r\n};\r\n","import { StaticImport } from \"next/dist/shared/lib/get-img-props\";\r\nimport { StaticImageData } from \"next/image\";\r\nimport { createContext, ImgHTMLAttributes, useContext, useEffect, useRef, useState } from \"react\";\r\n\r\nexport interface UseAICaptionOptions {\r\n  src?: string | StaticImport;\r\n  alt?: string;\r\n  apiEndpoint?: string;\r\n  fallbackAlt?: string;\r\n  onCaptionGenerated?: (caption: string) => void;\r\n  disableAI?: boolean;\r\n  announceLive?: boolean;\r\n  onCaptionError?: (error: Error) => void;\r\n}\r\n\r\ninterface SmartImageContextProps {\r\n  apiEndpoint?: string;\r\n  disableAI?: boolean;\r\n}\r\n\r\nexport const SmartImageContext = createContext<SmartImageContextProps | undefined>(undefined);\r\n\r\nconst MAX_SIZE = 500;\r\n\r\nclass LRUCaptionCache {\r\n  private cache = new Map<string, string>();\r\n\r\n  get(key: string): string | undefined {\r\n    return this.cache.get(key);\r\n  }\r\n  set(key: string, value: string) {\r\n    if (this.cache.size >= MAX_SIZE) {\r\n      this.cache.delete(this.cache.keys().next().value!);\r\n    }\r\n    this.cache.set(key, value);\r\n  }\r\n  has(key: string) {\r\n    return this.cache.has(key);\r\n  }\r\n  clear() {\r\n    this.cache.clear();\r\n  }\r\n}\r\n\r\nconst captionCache = new LRUCaptionCache();\r\nconst pendingRequestCache = new Map<string, Promise<string>>();\r\n\r\nexport interface SmartImageProps extends ImgHTMLAttributes<HTMLImageElement> {\r\n  apiEndpoint?: string;\r\n  fallbackAlt?: string;\r\n  onCaptionGenerated?: (caption: string) => void;\r\n  disableAI?: boolean;\r\n  announceLive?: boolean;\r\n}\r\n\r\nfunction isStaticImageData(src: string | StaticImport): src is StaticImageData {\r\n  return typeof src === \"object\" && src !== null && \"src\" in src;\r\n}\r\n\r\nfunction resolveImageUrl(src: string | StaticImport): string {\r\n  if (typeof src === \"string\") return src;\r\n  if (isStaticImageData(src)) return src.src;\r\n  return src.default.src;\r\n}\r\n\r\nconst log = process.env.NODE_ENV === \"development\" ? console.log : () => {};\r\n\r\nexport const useAICaptions = ({\r\n  src,\r\n  alt,\r\n  apiEndpoint: propsEndpoint,\r\n  fallbackAlt = \"Image loading or caption unavailable\",\r\n  onCaptionGenerated,\r\n  disableAI: propsDisableAI,\r\n  onCaptionError,\r\n}: UseAICaptionOptions) => {\r\n  const context = useContext(SmartImageContext);\r\n\r\n  const apiEndpoint = propsEndpoint || context?.apiEndpoint;\r\n  const disableAI = propsDisableAI ?? context?.disableAI ?? false;\r\n\r\n  const [generatedAlt, setGeneratedAlt] = useState(\"\");\r\n  const [isGenerating, setIsGenerating] = useState(false);\r\n  const [error, setError] = useState<Error | null>(null);\r\n\r\n  const onCaptionGeneratedRef = useRef(onCaptionGenerated);\r\n  const onCaptionErrorRef = useRef(onCaptionError);\r\n\r\n  useEffect(() => {\r\n    onCaptionGeneratedRef.current = onCaptionGenerated;\r\n    onCaptionErrorRef.current = onCaptionError;\r\n  });\r\n\r\n  useEffect(() => {\r\n    setError(null);\r\n\r\n    if (alt) {\r\n      setGeneratedAlt(alt);\r\n      return;\r\n    }\r\n\r\n    if (!src) return;\r\n\r\n    if (disableAI) {\r\n      setGeneratedAlt(\"[Testing mode: AI caption generation disabled]\");\r\n      return;\r\n    }\r\n\r\n    if (!apiEndpoint) {\r\n      console.warn(\r\n        \"[SmartImage] Missing 'apiEndpoint' prop. Please provide a backend API URL via props or SmartImageProvider to enable AI caption generation.\",\r\n      );\r\n      setGeneratedAlt(fallbackAlt);\r\n      return;\r\n    }\r\n\r\n    const imageUrl = resolveImageUrl(src);\r\n\r\n    if (captionCache.has(imageUrl)) {\r\n      log(\"[SmartImage] Cache hit: Reusing existing caption.\");\r\n      const cachedCaption = captionCache.get(imageUrl)!;\r\n      setGeneratedAlt(cachedCaption);\r\n      if (onCaptionGeneratedRef.current) onCaptionGeneratedRef.current(cachedCaption);\r\n      return;\r\n    }\r\n\r\n    let cancelled = false;\r\n\r\n    const generateCaption = async () => {\r\n      setIsGenerating(true);\r\n      try {\r\n        if (pendingRequestCache.has(imageUrl)) {\r\n          log(\"[SmartImage] Pending request detected. Waiting for the existing API call to complete.\");\r\n          const caption = await pendingRequestCache.get(imageUrl)!;\r\n          if (cancelled) return;\r\n          setGeneratedAlt(caption);\r\n          if (onCaptionGeneratedRef.current) onCaptionGeneratedRef.current(caption);\r\n          return;\r\n        }\r\n\r\n        const fetchPromise = (async () => {\r\n          const imageResponse = await fetch(imageUrl);\r\n          const imageBlob = await imageResponse.blob();\r\n          const imageFile = new File([imageBlob], \"image.jpg\", {\r\n            type: imageBlob.type || \"image/jpeg\",\r\n          });\r\n          const formData = new FormData();\r\n          formData.append(\"file\", imageFile);\r\n\r\n          const response = await fetch(apiEndpoint, {\r\n            method: \"POST\",\r\n            body: formData,\r\n          });\r\n\r\n          if (!response.ok) throw new Error(\"AI API request failed\");\r\n          const data = await response.json();\r\n          if (data.caption) return data.caption;\r\n          throw new Error(\"No caption returned from the API.\");\r\n        })();\r\n\r\n        pendingRequestCache.set(imageUrl, fetchPromise);\r\n\r\n        const newCaption = await fetchPromise;\r\n        pendingRequestCache.delete(imageUrl);\r\n        captionCache.set(imageUrl, newCaption);\r\n\r\n        if (cancelled) return;\r\n        setGeneratedAlt(newCaption);\r\n        if (onCaptionGeneratedRef.current) onCaptionGeneratedRef.current(newCaption);\r\n      } catch (err) {\r\n        const normalizedError = err instanceof Error ? err : new Error(\"Unknown error\");\r\n        pendingRequestCache.delete(imageUrl);\r\n        if (cancelled) return;\r\n        setError(normalizedError);\r\n        setGeneratedAlt(fallbackAlt);\r\n        if (onCaptionErrorRef.current) onCaptionErrorRef.current(normalizedError);\r\n      } finally {\r\n        if (!cancelled) setIsGenerating(false);\r\n      }\r\n    };\r\n\r\n    generateCaption();\r\n\r\n    return () => {\r\n      cancelled = true;\r\n    };\r\n  }, [src, alt, apiEndpoint, fallbackAlt, disableAI]);\r\n\r\n  return { generatedAlt, isGenerating, error };\r\n};\r\n"],"mappings":"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","names":[]}