refactor(core)!: autoSizes owns resize tracking; vue/nuxt onCleanup

- autoSizes accepts { updateOnResize: true } and returns a disposer; an <img> argument walks to <source data-sizes="auto"> siblings in the same call.
- triggerLoad is one-shot again - TriggerLoadOptions.updateSizesOnResize removed.
- lazyLoad keeps updateSizesOnResize as a thin wrapper that delegates to autoSizes.
- Drop resizeObserverCache; one disposer per call.
- Vue/Nuxt switch to watchEffect((onCleanup) => …) per Vue 3.5+ idiom.
- Fix stale picture-callback note in usage.md and stale triggerLoad reference in migration.md.

Author: johannschopplich

docs/api/auto-sizes.md

@@ -1,13 +1,34 @@
 # `autoSizes`
 
-The `autoSizes` function calculates and sets the `sizes` attribute based on the current display width of image or source elements when `data-sizes="auto"` is present.
+The `autoSizes` function resolves `data-sizes="auto"` to a numeric pixel width based on the rendered display size. It works on standalone `<img>` elements, on `<source>` siblings inside a `<picture>`, or both.
 
-The calculation uses the element's rendered width (`element.offsetWidth`) to determine the appropriate value for the `sizes` attribute, enabling browsers to select the optimal image from a `srcset`.
+When called with an `<img>` inside a `<picture>`, `autoSizes` walks to every `<source data-sizes="auto">` sibling and resolves them in the same call. `<source>` elements have no layout box of their own, so the rendered `<img>` width is used instead.
 
 To lazy load images, refer to the [`lazyLoad`](/api/lazy-load) method.
 
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `updateOnResize` | `boolean` | `false` | Install a debounced `ResizeObserver` that re-resolves `data-sizes="auto"` on viewport changes. The returned disposer disconnects it. |
+
+## Return Value
+
+`autoSizes` returns a disposer. When called with `updateOnResize: false` (or no options), the disposer is a no-op. With `updateOnResize: true`, calling it disconnects every `ResizeObserver` created by that call:
+
+```ts
+import { autoSizes } from 'unlazy'
+
+const dispose = autoSizes('img[data-sizes="auto"]', { updateOnResize: true })
+
+// Later, when cleaning up
+dispose()
+```
+
 ## Type Declarations
 
+<<< @/../packages/core/src/types.ts#AutoSizesOptions{ts}
+
 <<< @/../packages/core/src/lazyLoad.ts#autoSizes{ts}
 
 ## Example
@@ -18,3 +39,17 @@ To lazy load images, refer to the [`lazyLoad`](/api/lazy-load) method.
   data-sizes="auto"
 >
 ```
+
+```ts
+import { autoSizes } from 'unlazy'
+
+// One-shot resolve
+autoSizes()
+
+// Or: resolve and keep tracking on resize
+const dispose = autoSizes(undefined, { updateOnResize: true })
+```
+
+::: tip
+For most users, calling [`lazyLoad`](/api/lazy-load) with `updateSizesOnResize: true` is the simpler path – it delegates to `autoSizes` internally and bundles the disposer into the same cleanup callback.
+:::

docs/api/lazy-load.md

@@ -30,7 +30,7 @@ Options can be passed to the function to customize its behavior:
 | `hash` | `boolean \| string` | `true` | Whether to use a hash for generating a blurry placeholder. Can be `true` (auto-detect from `data-blurhash`/`data-thumbhash`), `false` (disabled), or a hash string. |
 | `hashType` | `'blurhash' \| 'thumbhash'` | `'blurhash'` | The type of hash to use. Ignored when `hash` is boolean (auto-detected from data attributes). |
 | `placeholderSize` | `number` | `32` | The size of the longer edge for BlurHash decoding. Ignored for ThumbHash. |
-| `updateSizesOnResize` | `boolean` | `false` | Whether to update the `sizes` attribute on resize events using a debounced ResizeObserver. Useful for responsive layouts where image display size changes. |
+| `updateSizesOnResize` | `boolean` | `false` | Re-resolve `data-sizes="auto"` on viewport resize – applies to both `<img>` and `<source>` siblings inside a `<picture>`. Internally delegates to [`autoSizes`](/api/auto-sizes); the returned cleanup disconnects every observer. |
 | `onImageLoad` | `(image: HTMLImageElement) => void` | - | Callback invoked when an image loads successfully. |
 | `onImageError` | `(image: HTMLImageElement, error: Event) => void` | - | Callback invoked when an image fails to load. |
 

docs/api/trigger-load.md

@@ -1,17 +1,30 @@
 # `triggerLoad`
 
-The `triggerLoad` function programmatically loads an image by updating its attributes from data attributes. It handles both standalone `<img>` elements and images within `<picture>` elements.
+The `triggerLoad` function programmatically loads an image by swapping its data attributes to standard ones. It handles both standalone `<img>` elements and images inside `<picture>` elements.
 
 The function performs the following operations:
 
-1. If the image is inside a `<picture>` element, updates all `<source>` elements by converting their `data-srcset` and `data-sizes` attributes to standard attributes synchronously. Callbacks fire after the browser resolves a source on the visible `<img>`.
+1. If the image is inside a `<picture>` element, swaps `data-srcset` to `srcset` on every `<source>` and resolves `data-sizes="auto"` to a numeric pixel width before the swap so the browser sees a final value at source-selection time. Callbacks fire after the browser resolves a source on the visible `<img>`.
 2. For standalone `<img>` elements, preloads the image in a temporary element to ensure proper loading.
-3. Calculates the `sizes` attribute if `data-sizes="auto"` is set.
+3. Calculates the `sizes` attribute on the temporary element if `data-sizes="auto"` is set on the visible `<img>`.
 4. Swaps `data-src` and `data-srcset` to their standard counterparts.
 5. Invokes the optional `onImageLoad` callback when loading completes, or `onImageError` if loading fails. On failure, a synthetic `error` event also fires on the visible `<img>`.
 
 `triggerLoad` returns a disposer that detaches its listeners and, for standalone images, aborts the in-flight network fetch. Calling it after the load has already completed is a no-op.
 
+::: tip
+`triggerLoad` is one-shot – it does not install any `ResizeObserver`. For ongoing source-size tracking on responsive `<picture>` layouts, pair it with [`autoSizes`](/api/auto-sizes) and `{ updateOnResize: true }`:
+
+```ts
+const disposeSizes = autoSizes(image, { updateOnResize: true })
+const disposeLoad = triggerLoad(image)
+
+// Later
+disposeSizes()
+disposeLoad()
+```
+:::
+
 ## Type Declarations
 
 <<< @/../packages/core/src/lazyLoad.ts#triggerLoad{ts}

docs/guide/migration.md

@@ -25,6 +25,21 @@ The deprecated `loadImage` alias is gone. Replace every call site with `triggerL
 + // Optional: dispose() to cancel before the load completes
 ```
 
+### `autoSizes` Owns Ongoing Size Tracking
+
+`triggerLoad` is one-shot again – it no longer accepts `updateSizesOnResize`. Ongoing re-resolution of `data-sizes="auto"` lives on [`autoSizes`](/api/auto-sizes), which now accepts `{ updateOnResize: true }` and returns a disposer:
+
+```diff
+- triggerLoad(image, { updateSizesOnResize: true })
++ const disposeSizes = autoSizes(image, { updateOnResize: true })
++ const disposeLoad = triggerLoad(image)
++ // Later: disposeSizes(); disposeLoad()
+```
+
+For the common case, [`lazyLoad`](/api/lazy-load) keeps `updateSizesOnResize` and delegates to `autoSizes` internally – no caller change needed.
+
+`autoSizes` itself now always returns a function. With no options, the returned disposer is a no-op; with `updateOnResize: true`, it disconnects every `ResizeObserver` created by the call. Passing an `<img>` inside a `<picture>` walks to every `<source data-sizes="auto">` sibling in the same call, replacing the previous need to invoke `autoSizes` separately on each source.
+
 ### `isLazyLoadingSupported` Removal
 
 Native `loading="lazy"` is Baseline Widely Available; the feature-detect was used internally to fall back to immediate swap, and that branch is gone. If you imported the helper directly, replace it with:
@@ -93,6 +108,21 @@ Result: you can safely re-invoke `lazyLoad()` after inserting images into the DO
 
 unlazy now warns in development when the LCP element is still configured for lazy loading. See the [Core Web Vitals guide](/guide/core-web-vitals#dev-mode-lcp-warning).
 
+### `sources` Prop Across Adapters
+
+The `sources` prop is no longer Nuxt-only. Every adapter now renders a `<picture>` when you pass an array of `UnLazySource` objects:
+
+```ts
+import type { UnLazySource } from 'unlazy'
+
+const sources: UnLazySource[] = [
+  { type: 'image/avif', srcSet: 'hero.avif 1x, hero@2x.avif 2x' },
+  { media: '(max-width: 600px)', srcSet: 'hero-mobile.jpg', width: 480, height: 640 },
+]
+```
+
+Each entry becomes a `<source>` child with `type`, `media`, `width`, `height`, and `data-sizes="auto"` support. Pass `updateSizesOnResize: true` to [`lazyLoad`](/api/lazy-load) (or `{ updateOnResize: true }` directly to [`autoSizes`](/api/auto-sizes)) to re-resolve `<source data-sizes="auto">` siblings on viewport resize.
+
 ### Vue / Nuxt: `@image-load` and `@image-error` Emits
 
 The Vue and Nuxt adapters now expose a symmetric pair of emits aligned with the core option names:

docs/guide/usage.md

@@ -95,17 +95,26 @@ The automatic sizes calculation uses the display width of the image.
 
 When calling [`lazyLoad`](/api/lazy-load), the library automatically calculates the `sizes` attribute for all images with `data-sizes="auto"`.
 
-Alternatively, use the [`autoSizes`](/api/auto-sizes) function to calculate the `sizes` attribute without lazy loading.
-
-To do so, import the [`autoSizes`](/api/auto-sizes) function from the library and call it:
+Alternatively, use the [`autoSizes`](/api/auto-sizes) function to calculate the `sizes` attribute without lazy loading. Call it with an `<img>` inside a `<picture>` and it walks to every `<source data-sizes="auto">` sibling in the same call:
 
 ```ts
 import { autoSizes } from 'unlazy'
 
-// Automatically calculate the sizes attribute for all `img[data-sizes="auto"], source[data-sizes="auto"]` images, without lazy loading them
+// One-shot resolve for every matching element in the document
 autoSizes()
 ```
 
+For responsive layouts where the display width changes – fluid containers, breakpoint switches, orientation changes – pass `{ updateOnResize: true }` to keep `sizes` synced. `autoSizes` returns a disposer – call it when you no longer need the observer:
+
+```ts
+const dispose = autoSizes(undefined, { updateOnResize: true })
+
+// Later, when unmounting
+dispose()
+```
+
+The same behavior is available on [`lazyLoad`](/api/lazy-load) via `updateSizesOnResize: true`, which delegates to `autoSizes` internally and bundles the disposer into the same cleanup callback.
+
 ## Custom Selectors
 
 You can customize the CSS selectors to target specific images by passing a CSS selector, a DOM element, a list of DOM elements, or an array of DOM elements to [`lazyLoad`](/api/lazy-load) and [`autoSizes`](/api/auto-sizes).
@@ -170,8 +179,4 @@ unlazy fully supports the `<picture>` element for art direction and format selec
 </picture>
 ```
 
-When the image loads, unlazy automatically swaps `data-srcset` to `srcset` on all `<source>` elements within the `<picture>`.
-
-::: info
-For `<picture>` elements, the `onImageLoad` and `onImageError` callbacks passed to `lazyLoad` aren't invoked, as the browser handles source selection internally.
-:::
+When the image loads, unlazy automatically swaps `data-srcset` to `srcset` on all `<source>` elements within the `<picture>`. The `onImageLoad` and `onImageError` callbacks fire once the browser resolves a source on the visible `<img>`.