react-a11y-auto-caption 1.1.6 → 1.1.7

package/README.md

@@ -1,6 +1,6 @@
 # react-a11y-auto-caption
 
-> AI-powered alt text generation component for React and Next.js images.
+> AI-powered alt text generation component for React and Next.js images.  
 > Generate captions during development, save them once, and reuse them in production for fast, accessible images.
 
 [![npm version](https://img.shields.io/npm/v/react-a11y-auto-caption.svg)](https://www.npmjs.com/package/react-a11y-auto-caption)
@@ -8,38 +8,83 @@
 [![Accessibility](https://img.shields.io/badge/Accessibility-100%25-brightgreen.svg)]()
 
 ---
+
 ## Why use react-a11y-auto-caption?
 
 - **Generate once, reuse forever** — create captions during development, save them, and skip AI calls in production.
 - **Built for accessibility** — automatically provide meaningful alt text for screen readers.
 - **Works with React and Next.js** — includes both `<SmartImage>` and `<SmartNextImage>`.
-- **Bring your own backend** — use your own FastAPI, Flask, or Node caption API.
-- **Production-friendly** — caching, duplicate-request protection, and error handling are built in.
+- **Local-first by default** — run the official caption server with `npx`.
+- **Production-friendly** — caching, duplicate-request protection, lazy generation, and error handling are built in.
+
+---
+
+## Installation
+
+```bash
+npm install react-a11y-auto-caption
+```
+
+or:
+
+```bash
+yarn add react-a11y-auto-caption
+```
+
+or:
+
+```bash
+pnpm add react-a11y-auto-caption
+```
 
 ---
 
 ## Quick Start
 
-### React
+### 1. Start the local caption server
+
+```bash
+npx react-a11y-auto-caption-server
+```
+
+Default endpoint:
+
+```txt
+http://127.0.0.1:8000/api/generate-caption
+```
+
+If port `8000` is unavailable, use another port:
+
+```bash
+npx react-a11y-auto-caption-server --port 5000
+```
+
+Then use:
+
+```txt
+http://127.0.0.1:5000/api/generate-caption
+```
+
+### 2. Use `SmartImage`
 
 ```tsx
-import { SmartImage } from 'react-a11y-auto-caption';
+import { SmartImage } from "react-a11y-auto-caption";
 
 export default function Demo() {
   return (
     <SmartImage
-      src="https://example.com/image.jpg"
-      apiEndpoint="http://localhost:8000/api/generate-caption"
+      src="/example.jpg"
+      apiEndpoint="http://127.0.0.1:8000/api/generate-caption"
     />
   );
 }
 ```
 
-### Next.js
+### 3. Use `SmartNextImage`
 
 ```tsx
-import { SmartNextImage } from 'react-a11y-auto-caption/next';
-import sampleImage from '../public/sample.jpg';
+import { SmartNextImage } from "react-a11y-auto-caption/next";
+import sampleImage from "../public/sample.jpg";
 
 export default function Demo() {
   return (
@@ -47,159 +92,261 @@ export default function Demo() {
       src={sampleImage}
       width={500}
       height={300}
-      apiEndpoint="http://localhost:8000/api/generate-caption"
+      apiEndpoint="http://127.0.0.1:8000/api/generate-caption"
     />
   );
 }
 ```
-> **Optional**: set the API endpoint once with a Provider
 
-### Wrap your app with the Provider (Optional but Recommended)
+---
+
+## Provider Setup
 
-Set your backend API endpoint once globally. Otherwise, pass `apiEndpoint` directly as a prop.
+You can set the backend API endpoint once globally instead of passing `apiEndpoint` to every image.
 
 ```tsx
-// App.tsx or layout.tsx
 import { SmartImageProvider } from "react-a11y-auto-caption";
 
 export default function App({ children }) {
   return (
-    <SmartImageProvider value={{ apiEndpoint: "https://your-api.com/api/generate-caption" }}>
+    <SmartImageProvider
+      value={{
+        apiEndpoint: "http://127.0.0.1:8000/api/generate-caption",
+      }}
+    >
       {children}
     </SmartImageProvider>
   );
 }
 ```
 
+Then use `SmartImage` without repeating the endpoint:
+
+```tsx
+<SmartImage src="/example.jpg" />
+```
+
 ---
 
-## Installation
+## Recommended Workflow
 
-```bash
-# npm
-npm install react-a11y-auto-caption
+1. Run the local caption server with `npx react-a11y-auto-caption-server`
+2. Generate captions during development
+3. Save generated captions to your database with `onCaptionGenerated`
+4. Pass the saved `alt` text in production
+5. Skip AI requests entirely for faster production pages
 
-# yarn
-yarn add react-a11y-auto-caption
+Example:
 
-# pnpm
-pnpm add react-a11y-auto-caption
+```tsx
+<SmartImage
+  src="/example.jpg"
+  alt={savedAlt || undefined}
+  apiEndpoint="http://127.0.0.1:8000/api/generate-caption"
+  onCaptionGenerated={(caption) => {
+    saveAltTextToDatabase(caption);
+  }}
+/>
 ```
 
+> If `alt` is provided, AI generation is bypassed. This is intentional so saved captions can be reused in production.
+
 ---
-## Recommended workflow
 
-1. Generate captions during local development with light [python server](https://github.com/kong33/SmartImage)
-2. Save them to your database with `onCaptionGenerated`
-3. Pass the saved `alt` text in production
-4. Skip AI requests entirely for zero extra latency
+## Public Demo Server
+
+You can test the package with the public demo server:
+
+```txt
+https://kong3333-react-a11y-auto-caption-server.hf.space/api/generate-caption
+```
+
+Example:
+
+```tsx
+<SmartImage
+  src="/example.jpg"
+  apiEndpoint="https://kong3333-react-a11y-auto-caption-server.hf.space/api/generate-caption"
+/>
+```
+
+> The public demo server is for testing only. It may be slow, paused, or unavailable depending on free-tier limits.  
+> For production, run your own caption server.
+
+---
+
+## Backend Integration
+
+This package needs a caption API endpoint that accepts an image file and returns a caption.
+
+The official local server is the easiest option:
+
+```bash
+npx react-a11y-auto-caption-server
+```
+
+Default endpoint:
+
+```txt
+http://127.0.0.1:8000/api/generate-caption
+```
+
+Custom port:
+
+```bash
+npx react-a11y-auto-caption-server --port 5000
+```
+
+Custom endpoint:
+
+```txt
+http://127.0.0.1:5000/api/generate-caption
+```
+
+The caption server automatically allows local development origins such as:
+
+```txt
+http://localhost:<any-port>
+http://127.0.0.1:<any-port>
+```
+
+For production or internal company servers, configure `ALLOWED_ORIGINS` on the server side.
+
+Example:
+
+```env
+ALLOWED_ORIGINS=https://your-frontend-domain.com,http://localhost:3000
+```
+
+If your frontend runs locally but the caption server runs on another machine, your frontend endpoint should point to that machine:
+
+```tsx
+<SmartImage
+  src="/example.jpg"
+  apiEndpoint="http://192.168.0.20:8000/api/generate-caption"
+/>
+```
 
 ---
 
 ## API Reference
 
-Both `<SmartImage>` and `<SmartNextImage>` inherit all standard HTML `<img>` (or `next/image`) attributes, plus the following:
+Both `<SmartImage>` and `<SmartNextImage>` inherit standard HTML `<img>` or `next/image` props, plus the following:
 
 | 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. |
-| `lazyGenerate` | `boolean` | `true` | Delays AI API calls until the image enters the viewport using `IntersectionObserver`.|
-| `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. |
+| `fallbackAlt` | `string` | `"Image loading or caption unavailable"` | Text used when the AI request fails. |
+| `lazyGenerate` | `boolean` | `true` | Delays AI API calls until the image enters the viewport using `IntersectionObserver`. |
+| `disableAI` | `boolean` | `false` | Disables AI generation and uses a mock caption. Useful for tests. |
+| `announceLive` | `boolean` | `false` | Enables an `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. |
+| `onCaptionError` | `(error: Error) => void` | `undefined` | Callback fired when caption generation fails. Useful for logging or toast notifications. |
 
-> **Note:** `<SmartNextImage>` requires standard Next.js image props such as `width` and `height` (unless using `fill`).
+> `<SmartNextImage>` requires standard Next.js image props such as `width` and `height`, unless using `fill`.
 
 ---
 
 ## Error Handling
 
-You can handle errors in two ways depending on your use case.
-
-**Via callback** — for external handling like logging or toasts:
+Use `onCaptionError` for logging, toast messages, or debugging.
 
 ```tsx
 <SmartImage
-  src={imageUrl}
-  onCaptionError={(err) => toast.error(err.message)}
+  src="/example.jpg"
+  apiEndpoint="http://127.0.0.1:8000/api/generate-caption"
+  onCaptionError={(error) => {
+    console.error("Caption generation failed:", error);
+  }}
 />
 ```
 
-**Via `useAICaptions` hook** — for UI branching:
+You can also use the hook directly:
 
 ```tsx
-const { generatedAlt, isGenerating, error } = useAICaptions({ src });
+const { generatedAlt, isGenerating, error } = useAICaptions({
+  src: "/example.jpg",
+  apiEndpoint: "http://127.0.0.1:8000/api/generate-caption",
+});
 
 if (error) return <p>Failed to generate caption.</p>;
 ```
 
 ---
 
-## Backend Integration
+## Troubleshooting
 
-This package needs a caption API endpoint to generate alt text.
+### API request does not run
 
-We offer a public demo server for testing. Set API endpoint as:
+Check that:
 
-```bash
-https://kong3333-react-a11y-auto-caption-server.hf.space/api/generate-caption
-```
+- `apiEndpoint` points to `/api/generate-caption`
+- the caption server is running
+- the frontend endpoint uses the same port as the server
+- `alt` is not already provided if you expect AI generation
+- `lazyGenerate={false}` is used while debugging viewport-related issues
+- the latest package version is installed
 
-> This public demo server is for testing only and may be slow or unavailable depending on free-tier limits.
-> For production, please run your own caption server.
+Debug example:
 
-The easiest way is to run the official local server:
-
-```bash
-npx react-a11y-auto-caption-server
+```tsx
+<SmartImage
+  src="/example.jpg"
+  apiEndpoint="http://127.0.0.1:8000/api/generate-caption"
+  lazyGenerate={false}
+  onCaptionGenerated={(caption) => console.log("Generated:", caption)}
+  onCaptionError={(error) => console.error("Caption error:", error)}
+/>
 ```
 
-By default, the server runs at:
+### Port 8000 is unavailable
 
-```txt
-http://127.0.0.1:8000/api/generate-caption
+Run the server on another port:
+
+```bash
+npx react-a11y-auto-caption-server --port 8001
 ```
 
-Use it with `SmartImage` or `SmartNextImage`:
+Then update your frontend:
 
 ```tsx
 <SmartImage
   src="/example.jpg"
-  apiEndpoint="http://127.0.0.1:8000/api/generate-caption"
+  apiEndpoint="http://127.0.0.1:8001/api/generate-caption"
 />
 ```
 
-You can also change the port:
-
-```bash
-npx react-a11y-auto-caption-server --port 5000
-```
+### External image URLs
 
-Then update the endpoint:
+If an external image URL fails before reaching the caption server, try a local image first:
 
 ```tsx
 <SmartImage
-  src="/example.jpg"
-  apiEndpoint="http://127.0.0.1:5000/api/generate-caption"
+  src="/sample.jpg"
+  apiEndpoint="http://127.0.0.1:8000/api/generate-caption"
 />
 ```
 
-> First run may take a few minutes because the server creates a Python environment and installs AI dependencies.
+Some external image hosts block browser-side `fetch()` access even if the image displays correctly in an `<img>` tag.
+
+---
+
+## What's New
 
-For production, we recommend running your own caption server and applying CORS restrictions, file size limits, and rate limiting.
+- Fixed lazy generation so captions are triggered correctly after images enter the viewport.
+- Added official `npx react-a11y-auto-caption-server` workflow.
+- Added custom backend server port support.
+- Added public demo server option for quick testing.
 
 ---
 
-## What's New in v1.0.4
+## Related
+
+- [`react-a11y-auto-caption-server`](https://www.npmjs.com/package/react-a11y-auto-caption-server)
+
+---
 
-- **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.
+## License
 
-  
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-a11y-auto-caption",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Smart React component that automatically generates alt text for images using AI.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",