create-cloudinary-react 1.0.0-beta.13 → 1.0.0-beta.14

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.0.0-beta.14](https://github.com/cloudinary-devs/create-cloudinary-react/compare/v1.0.0-beta.13...v1.0.0-beta.14) (2026-02-04)
+
+
+### Bug Fixes
+
+* improve upload widget reliability and add video player poster options ([ac51e42](https://github.com/cloudinary-devs/create-cloudinary-react/commit/ac51e420f1b81f2a055bb3fb7e0331841e86b37a))
+
 # [1.0.0-beta.13](https://github.com/cloudinary-devs/create-cloudinary-react/compare/v1.0.0-beta.12...v1.0.0-beta.13) (2026-02-03)
 
 

package/README.md

@@ -22,7 +22,7 @@ npx create-cloudinary-react
 The CLI will prompt you for:
 - Project name
 - **Cloudinary cloud name** (found in your [dashboard](https://console.cloudinary.com/app/home/dashboard))
-- Unsigned Upload preset (optional - required for uploads, but transformations work without it)
+- Unsigned upload preset (optional - required for uploads, but transformations work without it)
 - AI coding assistant(s) you're using (Cursor, GitHub Copilot, Claude, etc.)
 - Whether to install dependencies
 - Whether to start dev server
@@ -44,7 +44,7 @@ During setup, you'll be asked which AI coding assistant(s) you're using. The CLI
 
 - ✅ **Cursor** → `.cursorrules` + `.cursor/mcp.json` (if selected)
 - ✅ **GitHub Copilot** → `.github/copilot-instructions.md`
-- ✅ **Claude Code / Claude Desktop** → `.claude`, `claude.md` + `.cursor/mcp.json` (if selected)
+- ✅ **Claude Code (VS Code extension)** → `.claude`, `claude.md` + `.cursor/mcp.json` (if selected)
 - ✅ **Generic AI tools** → `AI_INSTRUCTIONS.md`, `PROMPT.md`
 
 **MCP Configuration**: The `.cursor/mcp.json` file is automatically generated if you select Cursor or Claude, as it works with both tools.

package/cli.js

@@ -139,7 +139,7 @@ async function main() {
         choices: [
           { name: 'Cursor', value: 'cursor' },
           { name: 'GitHub Copilot', value: 'copilot' },
-          { name: 'Claude Code / Claude Desktop', value: 'claude' },
+          { name: 'Claude Code (VS Code extension)', value: 'claude' },
           { name: 'Other / Generic AI tools', value: 'generic' },
         ],
         default: ['cursor'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cloudinary-react",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.14",
   "description": "Scaffold a Cloudinary React + Vite + TypeScript project with interactive setup",
   "type": "module",
   "bin": {

package/templates/.cursorrules.template

@@ -4,15 +4,15 @@
 
 ## Official Documentation
 - **Transformation Rules**: https://cloudinary.com/documentation/cloudinary_transformation_rules.md
-- **Transformation Reference**: https://cloudinary.com/documentation/transformation_reference
-- **React Image Transformations & Plugins**: https://cloudinary.com/documentation/react_image_transformations#plugins
-- **React Video Transformations**: https://cloudinary.com/documentation/react_video_transformations
-- **Cloudinary Video Player** (standalone player): https://cloudinary.com/documentation/cloudinary_video_player
-- **Video Player React Tutorial**: https://cloudinary.com/documentation/video_player_react_tutorial#banner
-- **Upload Widget (signed uploads)**: https://cloudinary.com/documentation/upload_widget#signed_uploads
-- **Upload assets in Next.js (backend signature)**: https://cloudinary.com/documentation/upload_assets_in_nextjs_tutorial
-- **Cloudinary Node.js SDK (server-side signing)** — use **v2**: `import { v2 as cloudinary } from 'cloudinary'`; do not use v1 (e.g. 1.47.0). https://cloudinary.com/documentation/node_integration
-- **React Native image and video upload (signed)**: https://cloudinary.com/documentation/react_native_image_and_video_upload#signed_upload
+- **Transformation Reference**: https://cloudinary.com/documentation/transformation_reference.md
+- **React Image Transformations & Plugins**: https://cloudinary.com/documentation/react_image_transformations.md#plugins
+- **React Video Transformations**: https://cloudinary.com/documentation/react_video_transformations.md
+- **Cloudinary Video Player** (standalone player): https://cloudinary.com/documentation/cloudinary_video_player.md
+- **Video Player React Tutorial**: https://cloudinary.com/documentation/video_player_react_tutorial.md
+- **Upload Widget (signed uploads)**: https://cloudinary.com/documentation/upload_widget.md#signed_uploads
+- **Upload assets in Next.js (backend signature)**: https://cloudinary.com/documentation/upload_assets_in_nextjs_tutorial.md
+- **Cloudinary Node.js SDK (server-side signing)** — use **v2**: `import { v2 as cloudinary } from 'cloudinary'`; do not use v1 (e.g. 1.47.0). https://cloudinary.com/documentation/node_integration.md
+- **React Native image and video upload (signed)**: https://cloudinary.com/documentation/react_native_image_and_video_upload.md#signed_upload
 - Always consult the official transformation rules when creating transformations
 - Use only officially supported parameters from the transformation reference
 
@@ -48,10 +48,15 @@ export const uploadPreset = import.meta.env.VITE_CLOUDINARY_UPLOAD_PRESET || '';
 - Use **this** pattern for the reusable instance. Everywhere else: `import { cld } from './cloudinary/config'` (or the path the user chose) and call `cld.image(publicId)` / `cld.video(publicId)`.
 
 **3. Upload Widget (unsigned, from scratch)**  
-- **Script**: Add to `index.html`: `<script src="https://upload-widget.cloudinary.com/global/all.js" async></script>`. Because the script loads **async**, React's useEffect can run before it's ready — **do not** call `createUploadWidget` until the script is loaded.
-- **Wait for script**: Before calling `window.cloudinary.createUploadWidget(...)`, ensure `typeof window.cloudinary?.createUploadWidget === 'function'`. If not ready, poll (e.g. setInterval) or wait for the script's `onload` (if you inject the script in code). Otherwise you get "createUploadWidget is not a function".
-- **Create widget in useEffect**, not in render. Store the widget in a **ref**. Pass options: `{ cloudName: import.meta.env.VITE_CLOUDINARY_CLOUD_NAME, uploadPreset: uploadPreset || undefined, sources: ['local', 'camera', 'url'], multiple: false }`. Use `uploadPreset` from config or env.
-- **Open on click**: Attach a click listener to a button that calls `widgetRef.current?.open()`. Remove the listener in useEffect cleanup. Handle script load failures (e.g. show error state if script never loads).
+
+**Strict pattern (always follow this exactly):**
+1. **Script in `index.html`** (required): Add `<script src="https://upload-widget.cloudinary.com/global/all.js" async></script>` to `index.html`. Do **not** rely only on dynamic script injection from React — it's fragile.
+2. **Poll in useEffect** (required): In `useEffect`, poll with `setInterval` (e.g. every 100ms) until `typeof window.cloudinary?.createUploadWidget === 'function'`. Only then create the widget. A single check (even in `onload`) is **not** reliable because `window.cloudinary` can exist before `createUploadWidget` is attached.
+3. **Add a timeout**: Set a timeout (e.g. 10 seconds) to stop polling and show an error if the script never loads. Clear both interval and timeout in cleanup.
+4. **Create widget once**: When `createUploadWidget` is available, create the widget and store it in a **ref**. Clear the interval and timeout. Pass options: `{ cloudName, uploadPreset, sources: ['local', 'camera', 'url'], multiple: false }`.
+5. **Open on click**: Attach a click listener to a button that calls `widgetRef.current?.open()`. Remove the listener in useEffect cleanup.
+
+❌ **Do NOT**: Check only `window.cloudinary` (not enough); do a single check in `onload` (unreliable); skip the script in `index.html`; poll forever without a timeout.
 - **Signed uploads**: Do not use only `uploadPreset`; use the pattern under "Secure (Signed) Uploads" (uploadSignature as function, fetch api_key, server includes upload_preset in signature).
 
 **4. Video player**  
@@ -60,7 +65,7 @@ export const uploadPreset = import.meta.env.VITE_CLOUDINARY_UPLOAD_PRESET || '';
 **5. Summary for rules-only users**  
 - **Env**: Use your bundler's client env prefix and access (Vite: `VITE_` + `import.meta.env.VITE_*`; see "Other bundlers" if not Vite).
 - **Reusable instance**: One config file that creates and exports `cld` (and optionally `uploadPreset`) from `@cloudinary/url-gen`; use it everywhere.
-- **Upload widget**: Script in index.html (or equivalent); create widget once in useEffect with ref; unsigned = cloudName + uploadPreset; signed = use uploadSignature function and backend.
+- **Upload widget**: Script in index.html (required); in useEffect, **poll** until `createUploadWidget` is a function, then create widget once and store in ref; unsigned = cloudName + uploadPreset; signed = use uploadSignature function and backend.
 - **Video player**: Imperative video element (createElement, append to container ref, pass to videoPlayer); dispose + removeChild in cleanup; fall back to AdvancedVideo if init fails.
 
 **If the user is not using Vite:** Use their bundler's client env prefix and access in the config file and everywhere you read env. Examples: Create React App → `REACT_APP_CLOUDINARY_CLOUD_NAME`, `process.env.REACT_APP_CLOUDINARY_CLOUD_NAME`; Next.js (client) → `NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`, `process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`. The rest (cld instance, widget options, video player) is the same.
@@ -141,7 +146,7 @@ cld.image('id').overlay(
 
 // Image overlay (logo/image with resize)
 cld.image('id').overlay(
-  source(image('logo').transformation(new Transformation().resize(scale().width(100).height(100))))
+  source(image('logo').transformation(new Transformation().resize(scale().width(100))))
     .position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20))
 );
 ```
@@ -192,7 +197,7 @@ cld.image('id').overlay(
 
 ### Transformation Best Practices
 - ✅ Format and quality must use separate `.delivery()` calls
-- ✅ Always end with auto format/quality: `.delivery(format(auto())).delivery(quality(autoQuality()))`
+- ✅ Always end with auto format/quality: `.delivery(format(auto())).delivery(quality(autoQuality()))` unless user specifies a particular format or quality
 - ✅ Use `gravity(auto())` unless user specifies a focal point
 - ✅ Same transformation syntax works for both images and videos
 
@@ -201,16 +206,16 @@ cld.image('id').overlay(
 - ✅ Import plugins from `@cloudinary/react`
 - ✅ Pass plugins as array: `plugins={[responsive(), lazyload(), placeholder()]}`
 - ✅ Recommended plugin order:
-  1. `responsive()` - First
-  2. `lazyload()` - Second
-  3. `accessibility()` - Third
-  4. `placeholder()` - Last
+  1. `responsive()` - First (handles breakpoints)
+  2. `placeholder()` - Second (shows placeholder while loading)
+  3. `lazyload()` - Third (delays loading until in viewport)
+  4. `accessibility()` - Last (if needed)
 - ✅ Always add `width` and `height` attributes to prevent layout shift
 - ✅ Example:
   ```tsx
   <AdvancedImage
     cldImg={img}
-    plugins={[responsive(), lazyload(), placeholder({ mode: 'blur' })]}
+    plugins={[responsive(), placeholder({ mode: 'blur' }), lazyload()]}
     width={800}
     height={600}
   />
@@ -241,20 +246,27 @@ cld.image('id').overlay(
 - ✅ **When the user asks for image overlays with text or logos**: Use `@cloudinary/url-gen` overlay APIs. Copy imports and patterns from the **"Import reference"** table and **"Canonical overlay block"** in these rules. Do not import `text` or `image` from `actions/overlay` — they are from **`qualifiers/source`**; only `source` is from `actions/overlay`.
 - ✅ **Import** `source` from `actions/overlay`; **`text` and `image` from `qualifiers/source`**. Also: `Position` from `qualifiers/position`, `TextStyle` from `qualifiers/textStyle`, `compass` from `qualifiers/gravity`, `Transformation` from `transformation/Transformation`, `scale` from `actions/resize`.
 - ✅ **compass()** takes **string** values, with **underscores**: `compass('center')`, `compass('south_east')`, `compass('north_west')`. ❌ WRONG: `compass(southEast)` or `'southEast'` (no camelCase).
-- ✅ **Overlay image**: Use `new Transformation()` **inside** `.transformation()`: `image('logo').transformation(new Transformation().resize(scale().width(100).height(100)))`. ❌ WRONG: `image('logo').transformation().resize(...)` (`.transformation()` does not return a chainable object).
+- ✅ **Overlay image**: Use `new Transformation()` **inside** `.transformation()`: `image('logo').transformation(new Transformation().resize(scale().width(100)))`. ❌ WRONG: `image('logo').transformation().resize(...)` (`.transformation()` does not return a chainable object).
 - ✅ **Text overlay**: `fontWeight` goes on **TextStyle**: `new TextStyle('Arial', 60).fontWeight('bold')`. `textColor` goes on the **text source** (chained after `text(...)`): `text('Hello', new TextStyle('Arial', 60)).textColor('white')`.
 - ✅ **Position** is chained **after** `source(...)`, not inside: `source(image('logo').transformation(...)).position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20))`.
-- ✅ **Image overlay pattern**: `baseImage.overlay(source(image('id').transformation(new Transformation().resize(scale().width(100).height(100)))).position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20)))`. (Import `scale` from `@cloudinary/url-gen/actions/resize` if needed.)
+- ✅ **Image overlay pattern**: `baseImage.overlay(source(image('id').transformation(new Transformation().resize(scale().width(100)))).position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20)))`. (Import `scale` from `@cloudinary/url-gen/actions/resize` if needed.)
 - ✅ **Text overlay pattern**: `baseImage.overlay(source(text('Your Text', new TextStyle('Arial', 60).fontWeight('bold')).textColor('white')).position(new Position().gravity(compass('center'))))`.
 - ✅ Docs: React Image Transformations and transformation reference for overlay syntax.
 
 ## Upload Widget Pattern
 - ✅ Use component: `import { UploadWidget } from './cloudinary/UploadWidget'`
-- ✅ Load script in `index.html`:
+
+**Strict initialization pattern (always follow this exactly):**
+1. ✅ **Script in `index.html`** (required):
   ```html
   <script src="https://upload-widget.cloudinary.com/global/all.js" async></script>
   ```
-- ✅ **Race condition**: The script loads **async**, so React's useEffect may run before `createUploadWidget` exists. **Wait until** `typeof window.cloudinary?.createUploadWidget === 'function'` before calling it (e.g. poll with setInterval or wait for script onload). Checking only `window.cloudinary` is not enough — `createUploadWidget` might not be attached yet. Otherwise: "createUploadWidget is not a function".
+2. ✅ **Poll in useEffect until `createUploadWidget` is available** (required): Use `setInterval` (e.g. every 100ms) to check `typeof window.cloudinary?.createUploadWidget === 'function'`. Only create the widget when this returns `true`. Clear the interval once ready.
+3. ✅ **Add a timeout** (e.g. 10 seconds) to stop polling and show an error state if the script never loads. Clear both interval and timeout in cleanup and when ready.
+4. ✅ **Create widget once**, store in a ref. Cleanup: clear interval, clear timeout, remove click listener.
+
+❌ **Do NOT**: Check only `window.cloudinary` (the function may not be attached yet); do a single check in `onload` (unreliable timing); skip `index.html` and rely only on dynamic injection; poll forever without a timeout.
+
 - ✅ Create unsigned upload preset in dashboard at `settings/upload/presets`
 - ✅ Add to `.env`: `VITE_CLOUDINARY_UPLOAD_PRESET=your_preset_name`
 - ✅ Handle callbacks:
@@ -343,7 +355,7 @@ res.json({ signature, timestamp: paramsToSign.timestamp, api_key: process.env.CL
 ```
 
 - ❌ **Avoid `signatureEndpoint`** — it may not be called reliably by all widget versions. Prefer the `uploadSignature` function.
-- ✅ Docs: [Upload widget — signed uploads](https://cloudinary.com/documentation/upload_widget#signed_uploads), [Upload assets in Next.js](https://cloudinary.com/documentation/upload_assets_in_nextjs_tutorial).
+- ✅ Docs: [Upload widget — signed uploads](https://cloudinary.com/documentation/upload_widget.md#signed_uploads), [Upload assets in Next.js](https://cloudinary.com/documentation/upload_assets_in_nextjs_tutorial.md).
 
 ### Rules for secure uploads
 - ✅ Use a **signed** upload preset (dashboard → Upload presets → Signed). Do not use an unsigned preset when the user wants secure uploads. **Default:** Accounts have a built-in signed preset `ml_default` — use it if the user hasn't created their own (they can delete `ml_default`, in which case they must create a signed preset in the dashboard).
@@ -400,7 +412,7 @@ res.json({ signature, timestamp: paramsToSign.timestamp, api_key: process.env.CL
     muted
   />
   ```
-- ✅ **Documentation**: https://cloudinary.com/documentation/react_video_transformations
+- ✅ **Documentation**: https://cloudinary.com/documentation/react_video_transformations.md
 
 ### Cloudinary Video Player (The Player)
 Use when the user asks for a **video player** (styled UI, controls, playlists). For just **displaying** a video, use AdvancedVideo instead.
@@ -413,6 +425,11 @@ Use when the user asks for a **video player** (styled UI, controls, playlists).
 - **Cleanup**: Call `player.dispose()`, then **only if** `el.parentNode` exists call `el.parentNode.removeChild(el)` (avoids NotFoundError).
 - **If init fails** (CSP, extensions, timing): render **AdvancedVideo** with the same publicId. Do not relax CSP in index.html or ask the user to disable extensions.
 
+**Poster options**: Always include `posterOptions` for a predictable poster image with a fallback color:
+- `transformation: { startOffset: '0' }` — use the first frame of the video as the poster (consistent and loads reliably)
+- `posterColor: '#0f0f0f'` — if the poster image fails to load, shows a dark background instead of blank/broken
+- These can be overridden via props (e.g. `posterOptions={{ transformation: { startOffset: '5' } }}` for a different frame)
+
 **Example (copy this pattern):**
 ```tsx
 const containerRef = useRef<HTMLDivElement>(null);
@@ -423,7 +440,16 @@ useLayoutEffect(() => {
   el.className = 'cld-video-player cld-fluid';
   containerRef.current.appendChild(el);
   try {
-    const player = videoPlayer(el, { cloudName, secure: true, controls: true, fluid: true });
+    const player = videoPlayer(el, {
+      cloudName,
+      secure: true,
+      controls: true,
+      fluid: true,
+      posterOptions: {
+        transformation: { startOffset: '0' },
+        posterColor: '#0f0f0f',
+      },
+    });
     player.source({ publicId: 'samples/elephants' });
     playerRef.current = player;
   } catch (err) { console.error(err); }
@@ -437,7 +463,7 @@ useLayoutEffect(() => {
 }, [cloudName]);
 return <div ref={containerRef} />;
 ```
-Docs: https://cloudinary.com/documentation/cloudinary_video_player
+Docs: https://cloudinary.com/documentation/cloudinary_video_player.md
 
 ### When to Use Which?
 - ✅ **Use AdvancedVideo** when: User wants to **display** or **show** a video (no full player). It just displays a video with transformations.
@@ -494,18 +520,28 @@ Docs: https://cloudinary.com/documentation/cloudinary_video_player
 - ✅ Access with type safety: `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME`
 
 ### Type Guards and Safety
-- ✅ Type guard for window.cloudinary:
+- ✅ Type guard for window.cloudinary (check `createUploadWidget`, not just `cloudinary`):
   ```tsx
-  function isCloudinaryLoaded(): boolean {
+  function isUploadWidgetReady(): boolean {
     return typeof window !== 'undefined' && 
-           typeof window.cloudinary !== 'undefined';
+           typeof window.cloudinary?.createUploadWidget === 'function';
   }
   ```
-- ✅ Use type guards before accessing:
+- ✅ Use type guards before accessing (but **always poll with timeout** in useEffect — don't rely on a single check):
   ```tsx
-  if (isCloudinaryLoaded()) {
-    window.cloudinary.createUploadWidget(...);
-  }
+  // In useEffect, poll until ready with timeout:
+  const interval = setInterval(() => {
+    if (isUploadWidgetReady()) {
+      clearInterval(interval);
+      clearTimeout(timeout);
+      window.cloudinary.createUploadWidget(...);
+    }
+  }, 100);
+  const timeout = setTimeout(() => {
+    clearInterval(interval);
+    console.error('Upload widget script failed to load');
+  }, 10000);
+  // Cleanup: clearInterval(interval); clearTimeout(timeout);
   ```
 
 ### Ref Typing Patterns
@@ -548,12 +584,12 @@ Docs: https://cloudinary.com/documentation/cloudinary_video_player
   ```
 
 ## Best Practices
-- ✅ Always use `fill()` resize for responsive images
-- ✅ Always end transformations with `.delivery(format(auto())).delivery(quality(autoQuality()))`
+- ✅ Always use `fill()` resize with automatic gravity for responsive images
+- ✅ Always end transformations with `.delivery(format(auto())).delivery(quality(autoQuality()))` unless the user specifies a format or quality
 - ✅ Use `placeholder()` and `lazyload()` plugins together
 - ✅ Always add `width` and `height` attributes to `AdvancedImage`
 - ✅ Store `public_id` from upload success, not full URL
-- ✅ Video player: use imperative element only; dispose in useLayoutEffect cleanup and remove element with `if (el.parentNode) el.parentNode.removeChild(el)`
+- ✅ Video player: use imperative element only; dispose in useLayoutEffect cleanup and remove element with `if (el.parentNode) el.parentNode.removeChild(el)`; always include `posterOptions` with `transformation: { startOffset: '0' }` and `posterColor: '#0f0f0f'` for reliable poster display
 - ✅ Use TypeScript for better autocomplete and error catching
 - ✅ Prefer `unknown` over `any` when types aren't available
 - ✅ Use type guards for runtime type checking
@@ -656,16 +692,17 @@ Docs: https://cloudinary.com/documentation/cloudinary_video_player
   4. Consider using server-side upload for very large files
 
 ### Widget not opening
-- ❌ Problem: Script not loaded or initialization issue
+- ❌ Problem: Script not loaded, or widget created before `createUploadWidget` was available
 - ✅ Solution:
   1. Ensure script is in `index.html`: `<script src="https://upload-widget.cloudinary.com/global/all.js" async></script>`
-  2. Check widget initializes in `useEffect` after `window.cloudinary` is available
+  2. In `useEffect`, **poll** with `setInterval` until `typeof window.cloudinary?.createUploadWidget === 'function'` — only then create the widget. Do **not** check only `window.cloudinary`.
   3. Verify upload preset is set correctly
 
 ### "createUploadWidget is not a function"
-- ❌ Problem: **Race condition** — the script in index.html loads **async**, so React's useEffect can run before the script has finished loading. `window.cloudinary` might exist but `createUploadWidget` isn't attached yet.
-- ✅ **Wait for script**: Before calling `window.cloudinary.createUploadWidget(...)`, ensure `typeof window.cloudinary?.createUploadWidget === 'function'`. If not ready, poll (e.g. setInterval until it exists) or inject the script in code and call createUploadWidget in the script's `onload`. Don't assume `window.cloudinary` means the API is ready.
-- ✅ See PATTERNS → Upload Widget Pattern ("Race condition") and Project setup → Upload Widget ("Wait for script").
+- ❌ Problem: **Race condition** — the script loads **async**, so `window.cloudinary` can exist before `createUploadWidget` is attached. A single check (even in `onload`) is **not** reliable.
+- ✅ **Always poll**: In `useEffect`, use `setInterval` to check `typeof window.cloudinary?.createUploadWidget === 'function'`. Only create the widget when this returns `true`. Clear the interval once ready.
+- ❌ **Do NOT**: Check only `window.cloudinary`; do a single check in `onload`; skip the script in `index.html`.
+- ✅ See PATTERNS → Upload Widget Pattern and Project setup → Upload Widget for the strict pattern.
 
 ### Video player: "Invalid target for null#on" or React removeChild or NotFoundError
 - ❌ Problem: Passing a React-managed `<video ref={...} />` to the player causes removeChild errors (the player mutates the DOM). Or container/ref not in DOM yet when init runs.
@@ -718,7 +755,7 @@ Docs: https://cloudinary.com/documentation/cloudinary_video_player
 
 ### Cloudinary package install fails or "version doesn't exist"
 - ❌ Problem: Agent pinned a Cloudinary package to a specific version (e.g. `cloudinary-video-player@1.2.3`) that doesn't exist on npm, or used a wrong package name.
-- ✅ **Install latest**: Use `npm install <package>` with **no version** so npm gets the latest compatible. In package.json use a **caret** (e.g. `"cloudinary-video-player": "^1.0.0"`). Use only correct package names: `@cloudinary/react`, `@cloudinary/tps://console.cloudinary.com/app/settings/upload/presets\n\n'-gen`, `cloudinary-video-player`, `cloudinary`. See PATTERNS → "Installing Cloudinary packages".
+- ✅ **Install latest**: Use `npm install <package>` with **no version** so npm gets the latest compatible. In package.json use a **caret** (e.g. `"cloudinary-video-player": "^1.0.0"`). Use only correct package names: `@cloudinary/react`, `@cloudinary/url-gen`, `cloudinary-video-player`, `cloudinary`. See PATTERNS → "Installing Cloudinary packages".
 
 ### Confusion between AdvancedVideo and Video Player
 - **AdvancedVideo** = for **displaying** a video (not a full player). **Cloudinary Video Player** = the **player** (styled UI, controls, playlists, etc.).
@@ -742,6 +779,11 @@ Docs: https://cloudinary.com/documentation/cloudinary_video_player
 ### Video player: "source is not a function" or video not playing
 - **player.source()** takes an **object**: `player.source({ publicId: 'samples/elephants' })`, not a string. Use named import: `import { videoPlayer } from 'cloudinary-video-player'`. See PATTERNS → Cloudinary Video Player (The Player).
 
+### Video player: poster image missing, wrong frame, or broken
+- ❌ Problem: Video player shows no poster, wrong poster frame, or blank area before video loads.
+- ✅ **Always include `posterOptions`** in the player config: `posterOptions: { transformation: { startOffset: '0' }, posterColor: '#0f0f0f' }`. This uses the first frame as the poster (reliable) and provides a dark fallback color if the poster fails to load.
+- ✅ **Override if needed**: Pass different values via props, e.g. `startOffset: '5'` for a frame 5 seconds in, or a different `posterColor` for your design.
+
 ### Overlay: "Cannot read properties of undefined" or overlay not showing
 - ❌ Problem: Wrong overlay API usage (Overlay.source, compass constants, .transformation().resize, fontWeight on wrong object).
 - ✅ Import `source` directly from `@cloudinary/url-gen/actions/overlay` (not `Overlay.source`). Use **string** values for compass: `compass('south_east')` (underscores, not camelCase). Use `new Transformation()` inside `.transformation()`. Put `fontWeight` on **TextStyle**; put `textColor` on the **text source**. See PATTERNS → Image Overlays (text or logos).
@@ -815,8 +857,8 @@ When something isn't working, check:
 - [ ] Format/quality use separate `.delivery()` calls
 - [ ] Plugins are in array format
 - [ ] Upload widget script is loaded in `index.html`
-- [ ] **"createUploadWidget is not a function"?** → Wait until `typeof window.cloudinary?.createUploadWidget === 'function'` before calling it (script loads async; poll or use script onload)
-- [ ] **Video player?** → **Imperative element only**: createElement('video'), append to container ref, pass to videoPlayer(el, ...); player.source({ publicId }); cleanup: dispose then if (el.parentNode) el.parentNode.removeChild(el). CSS: cloudinary-video-player/cld-video-player.min.css. If init fails, fall back to AdvancedVideo (do not relax CSP).
+- [ ] **"createUploadWidget is not a function"?** → In useEffect, **poll** with setInterval until `typeof window.cloudinary?.createUploadWidget === 'function'`. Do NOT check only `window.cloudinary`; do NOT rely on a single onload check
+- [ ] **Video player?** → **Imperative element only**: createElement('video'), append to container ref, pass to videoPlayer(el, ...); include `posterOptions: { transformation: { startOffset: '0' }, posterColor: '#0f0f0f' }` for reliable poster; player.source({ publicId }); cleanup: dispose then if (el.parentNode) el.parentNode.removeChild(el). CSS: cloudinary-video-player/cld-video-player.min.css. If init fails, fall back to AdvancedVideo (do not relax CSP).
 - [ ] **Upload fails (unsigned)?** → Is `VITE_CLOUDINARY_UPLOAD_PRESET` set? Preset exists and is Unsigned in dashboard?
 - [ ] **Upload default?** → Default to **unsigned** uploads (cloudName + uploadPreset); use signed only when the user explicitly asks for secure/signed uploads (signed requires a running backend)
 - [ ] **Secure uploads?** → Use `uploadSignature` as function (not `signatureEndpoint`); fetch `api_key` from server first; include `uploadPreset` in widget config; server includes `upload_preset` in signed params; use Cloudinary Node SDK v2 on server; never expose or commit API secret

package/templates/index.html.template

@@ -8,6 +8,8 @@
   </head>
   <body>
     <div id="root"></div>
+    <!-- Cloudinary upload widget - load early so it's ready before React; avoids races with other components -->
+    <script src="https://upload-widget.cloudinary.com/global/all.js" async></script>
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

package/templates/src/App.tsx.template

@@ -4,14 +4,16 @@ import { fill } from '@cloudinary/url-gen/actions/resize';
 import { format, quality } from '@cloudinary/url-gen/actions/delivery';
 import { auto } from '@cloudinary/url-gen/qualifiers/format';
 import { auto as autoQuality } from '@cloudinary/url-gen/qualifiers/quality';
+import { autoGravity } from '@cloudinary/url-gen/qualifiers/gravity';
 import { cld } from './cloudinary/config';
 import { UploadWidget } from './cloudinary/UploadWidget';
+import type { CloudinaryUploadResult } from './cloudinary/UploadWidget';
 import './App.css';
 
 function App() {
   const [uploadedImageId, setUploadedImageId] = useState<string | null>(null);
 
-  const handleUploadSuccess = (result: any) => {
+  const handleUploadSuccess = (result: CloudinaryUploadResult) => {
     console.log('Upload successful:', result);
     setUploadedImageId(result.public_id);
   };
@@ -26,7 +28,7 @@ function App() {
   
   const displayImage = cld
     .image(imageId)
-    .resize(fill().width(600).height(400))
+    .resize(fill().width(600).height(400).gravity(autoGravity()))
     .delivery(format(auto()))
     .delivery(quality(autoQuality()));
 

package/templates/src/cloudinary/UploadWidget.tsx.template

@@ -1,16 +1,42 @@
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { uploadPreset } from './config';
 
+export interface CloudinaryUploadResult {
+  public_id: string;
+  secure_url: string;
+  url: string;
+  width: number;
+  height: number;
+  format: string;
+  resource_type: string;
+  bytes: number;
+  created_at: string;
+}
+
 interface UploadWidgetProps {
-  onUploadSuccess?: (result: any) => void;
+  onUploadSuccess?: (result: CloudinaryUploadResult) => void;
   onUploadError?: (error: Error) => void;
   buttonText?: string;
   className?: string;
 }
 
+interface CloudinaryWidgetResult {
+  event: string;
+  info: CloudinaryUploadResult;
+}
+
+interface CloudinaryWidgetError {
+  message?: string;
+}
+
 declare global {
   interface Window {
-    cloudinary: any;
+    cloudinary?: {
+      createUploadWidget: (
+        config: Record<string, unknown>,
+        callback: (error: CloudinaryWidgetError | null, result: CloudinaryWidgetResult | null) => void
+      ) => { open: () => void };
+    };
   }
 }
 
@@ -20,13 +46,17 @@ export function UploadWidget({
   buttonText = 'Upload Image',
   className = '',
 }: UploadWidgetProps) {
-  const widgetRef = useRef<any>(null);
-  const buttonRef = useRef<HTMLButtonElement>(null);
-  const clickHandlerRef = useRef<(() => void) | null>(null);
+  const widgetRef = useRef<{ open: () => void } | null>(null);
+  const [isReady, setIsReady] = useState(false);
+  const [scriptError, setScriptError] = useState(false);
 
   useEffect(() => {
+    let poll: ReturnType<typeof setInterval> | null = null;
+    let timeout: ReturnType<typeof setTimeout> | null = null;
+    let mounted = true;
+
     function initializeWidget() {
-      if (typeof window.cloudinary?.createUploadWidget !== 'function' || !buttonRef.current) return;
+      if (!mounted || typeof window.cloudinary?.createUploadWidget !== 'function') return;
 
       if (!uploadPreset) {
         console.warn(
@@ -42,7 +72,7 @@ export function UploadWidget({
           sources: ['local', 'camera', 'url'],
           multiple: false,
         },
-        (error: any, result: any) => {
+        (error: CloudinaryWidgetError | null, result: CloudinaryWidgetResult | null) => {
           if (error) {
             console.error('Upload error:', error);
             onUploadError?.(new Error(error.message || 'Upload failed'));
@@ -56,73 +86,88 @@ export function UploadWidget({
         }
       );
 
-      const handler = () => widgetRef.current?.open();
-      clickHandlerRef.current = handler;
-      buttonRef.current.addEventListener('click', handler);
+      setIsReady(true);
+    }
+
+    function isWidgetReady(): boolean {
+      return typeof window.cloudinary?.createUploadWidget === 'function';
     }
 
-    function waitThenInit() {
-      if (typeof window.cloudinary?.createUploadWidget === 'function') {
+    // Poll until createUploadWidget is available
+    // Script should be in index.html, but poll handles any load timing
+    poll = setInterval(() => {
+      if (isWidgetReady()) {
+        if (poll) clearInterval(poll);
+        if (timeout) clearTimeout(timeout);
         initializeWidget();
-        return true;
       }
-      return false;
-    }
+    }, 100);
 
-    if (!window.cloudinary) {
-      const script = document.createElement('script');
-      script.src = 'https://upload-widget.cloudinary.com/global/all.js';
-      script.async = true;
-      document.body.appendChild(script);
-      script.onload = () => waitThenInit();
-    } else if (!waitThenInit()) {
-      const poll = setInterval(() => {
-        if (waitThenInit()) {
-          clearInterval(poll);
-          clearTimeout(timeout);
-        }
-      }, 100);
-      const timeout = setTimeout(() => clearInterval(poll), 10000);
-      return () => {
-        clearInterval(poll);
-        clearTimeout(timeout);
-        if (buttonRef.current && clickHandlerRef.current) {
-          buttonRef.current.removeEventListener('click', clickHandlerRef.current);
-        }
-      };
+    // Timeout after 10 seconds
+    timeout = setTimeout(() => {
+      if (poll) clearInterval(poll);
+      if (mounted && !isWidgetReady()) {
+        console.error('Upload widget script failed to load within 10 seconds');
+        setScriptError(true);
+      }
+    }, 10000);
+
+    // Check immediately in case script is already loaded
+    if (isWidgetReady()) {
+      if (poll) clearInterval(poll);
+      if (timeout) clearTimeout(timeout);
+      initializeWidget();
     }
 
     return () => {
-      if (buttonRef.current && clickHandlerRef.current) {
-        buttonRef.current.removeEventListener('click', clickHandlerRef.current);
-      }
+      mounted = false;
+      if (poll) clearInterval(poll);
+      if (timeout) clearTimeout(timeout);
     };
   }, [onUploadSuccess, onUploadError]);
 
+  const handleClick = () => {
+    if (widgetRef.current) {
+      widgetRef.current.open();
+    } else if (!scriptError) {
+      console.warn('Upload widget is still loading, please try again.');
+    }
+  };
+
+  if (scriptError) {
+    return (
+      <div style={{ color: '#dc2626', fontSize: '0.875rem' }}>
+        Upload widget failed to load. Please refresh the page or check your network connection.
+      </div>
+    );
+  }
+
   return (
     <button
-      ref={buttonRef}
       type="button"
+      onClick={handleClick}
+      disabled={!isReady}
       className={className}
       style={{
         padding: '0.75rem 1.5rem',
         fontSize: '1rem',
         fontWeight: 500,
         color: 'white',
-        backgroundColor: '#6366f1',
+        backgroundColor: isReady ? '#6366f1' : '#9ca3af',
         border: 'none',
         borderRadius: '0.5rem',
-        cursor: 'pointer',
+        cursor: isReady ? 'pointer' : 'wait',
         transition: 'background-color 0.2s',
+        opacity: isReady ? 1 : 0.7,
       }}
       onMouseEnter={(e) => {
-        e.currentTarget.style.backgroundColor = '#4f46e5';
+        if (isReady) e.currentTarget.style.backgroundColor = '#4f46e5';
       }}
       onMouseLeave={(e) => {
-        e.currentTarget.style.backgroundColor = '#6366f1';
+        if (isReady) e.currentTarget.style.backgroundColor = '#6366f1';
       }}
     >
-      {buttonText}
+      {isReady ? buttonText : 'Loading...'}
     </button>
   );
 }