# Performance handoff: background images, `<x-media.img>`, video, preloads

Owner: Performance and SEO. For: Site and Products. Generated by `php artisan site:images`
(variants live in `public/media/_v/`, manifest `public/media/_v/manifest.json`). All paths below exist now.

## 1. `<x-media.img>` is live

Props unchanged (`src alt width height sizes eager` + pass-through attributes). When the manifest has
variants it renders:

```html
<picture><source type="image/avif" srcset="... 480w, ... 800w, ... 1200w" sizes="auto, 100vw">
<source type="image/webp" srcset="..." sizes="auto, 100vw"><img src="/media/..." alt=".." width=".." height=".." loading="lazy" decoding="async" sizes="auto, 100vw" class=".."></picture>
```

otherwise a plain `<img>`. Things to know:

- `class`, `id`, `data-*`, `style` go on the `<img>`, not on `<picture>`. No CSS in the project uses
  `parent > img`, so selectors keep matching. If an image is a flex/grid item, `<picture>` becomes the
  item instead. **Site: please add `picture { display: contents; }` to the base CSS** so layouts stay
  exactly as with a bare `<img>`.
- width/height come from the manifest when you do not pass them; pass `sizes` when you know the
  rendered width (e.g. `sizes="(max-width: 767px) 100vw, 560px"`). Without `sizes`, lazy images use
  `sizes="auto, 100vw"` (Chrome picks the variant from the laid-out width).
- `eager` on the one hero `<img>` of a page: no lazy loading, `fetchpriority="high"`. It needs no
  preload.

## 2. CSS backgrounds: switch to `image-set()`

Write the original first as the fallback, then the `image-set()` (browsers without `type()` support
ignore the second declaration):

```css
.hero {
    background-image: url("/media/2023/12/studiobkhero.webp");
    background-image: image-set(url("/media/_v/2023/12/studiobkhero-webp.avif") type("image/avif"),
                                url("/media/_v/2023/12/studiobkhero-webp.webp") type("image/webp"),
                                url("/media/2023/12/studiobkhero.webp"));
}
```

Leave out a format marked "none" below (the variant was not smaller than the source, so the source
itself is the best file for that format). Rows with no variant at all need no change.

For backgrounds that come from content through inline custom properties (home page), use the new
helper `media_set($path)`, which returns the `image-set(...)` value (or `url(...)` when there are no
variants, so it is always safe), and keep the plain `url()` as fallback:

```blade
<section class="hero" style="--hero-bg: url('{{ media($c('hero.background')) }}'); --hero-bg-set: {{ media_set($c('hero.background')) }}">
```
```css
.hero { background-image: var(--hero-bg); }
@supports (background-image: image-set(url("x.avif") type("image/avif"))) {
    .hero { background-image: var(--hero-bg-set, var(--hero-bg)); }
}
```
(A custom property holding an unsupported `image-set()` would not fall back to the previous
declaration, hence the `@supports`.) The same helper works for the device screens in
`components/product/device.blade.php` (`style="background-image: {{ media_set($screen) }}"` behind the
same `@supports` pattern, or two declarations in a class if you prefer).

Full-size variants (what `image-set()` should reference). KB = file size on disk.

### CSS files (Products: resources/css/products/pages/*.css)

| Source | Used by | Source KB | AVIF (full size) | KB | WebP (full size) | KB |
|---|---|---:|---|---:|---|---:|
| `/media/2022/12/crmbk.webp` | crm-system.css | 9.7 | `/media/_v/2022/12/crmbk-webp.avif` | 9.3 | none (not smaller) | - |
| `/media/2023/12/studiobkhero.webp` | design-studio-tool.css | 81.6 | `/media/_v/2023/12/studiobkhero-webp.avif` | 36.9 | `/media/_v/2023/12/studiobkhero-webp.webp` | 34.3 |
| `/media/2023/12/blankplaceholder.png` | design-studio-tool.css | 1.9 | none (small) | - | none (small) | - |
| `/media/2022/12/DMSBK.webp` | idms-idealers-management-system.css | 5.9 | none (not smaller) | - | none (not smaller) | - |
| `/media/2022/12/inventoryBK.webp` | inventory-management.css | 9.7 | `/media/_v/2022/12/inventoryBK-webp.avif` | 9.0 | none (not smaller) | - |
| `/media/2022/12/leadsbk.webp` | leads-center.css | 9.7 | `/media/_v/2022/12/leadsbk-webp.avif` | 9.2 | none (not smaller) | - |
| `/media/2022/12/marketingbk.webp` | marketing-tools.css | 9.2 | `/media/_v/2022/12/marketingbk-webp.avif` | 8.6 | none (not smaller) | - |
| `/media/2022/12/pricebk-scaled.webp` | pricing.css | 16.0 | `/media/_v/2022/12/pricebk-scaled-webp.avif` | 12.4 | `/media/_v/2022/12/pricebk-scaled-webp.webp` | 15.1 |
| `/media/2022/12/websitebk.webp` | website.css | 9.4 | `/media/_v/2022/12/websitebk-webp.avif` | 8.8 | none (not smaller) | - |

### CSS files (Site: resources/css/site/layout.css)

| Source | Used by | Source KB | AVIF (full size) | KB | WebP (full size) | KB |
|---|---|---:|---|---:|---|---:|
| `/media/2022/12/footerbk.webp` | layout.css footer | 33.3 | `/media/_v/2022/12/footerbk-webp.avif` | 7.2 | `/media/_v/2022/12/footerbk-webp.webp` | 27.8 |
| `/media/2022/12/hdcolor.webp` | layout.css header stripe | 0.1 | none (small) | - | none (small) | - |

### Inline styles from content (Site: pages/home.blade.php)

| Source | Used by | Source KB | AVIF (full size) | KB | WebP (full size) | KB |
|---|---|---:|---|---:|---|---:|
| `/media/2023/11/bkhero.webp` | home hero.background (LCP) | 158.0 | `/media/_v/2023/11/bkhero-webp.avif` | 103.5 | `/media/_v/2023/11/bkhero-webp.webp` | 140.9 |
| `/media/2022/12/screenmac3-scaled.webp` | home intro.background | 95.6 | `/media/_v/2022/12/screenmac3-scaled-webp.avif` | 57.3 | `/media/_v/2022/12/screenmac3-scaled-webp.webp` | 82.1 |
| `/media/2022/12/abanner.png` | home leads.background | 28.3 | `/media/_v/2022/12/abanner-png.avif` | 11.4 | `/media/_v/2022/12/abanner-png.webp` | 12.5 |
| `/media/2022/12/creditscreen.webp` | home leads.credit_screen | 61.3 | `/media/_v/2022/12/creditscreen-webp.avif` | 38.8 | `/media/_v/2022/12/creditscreen-webp.webp` | 55.5 |
| `/media/2022/12/testdrivescreen.webp` | home leads.calendar_screen | 23.6 | `/media/_v/2022/12/testdrivescreen-webp.avif` | 12.2 | `/media/_v/2022/12/testdrivescreen-webp.webp` | 14.4 |
| `/media/2022/12/bk2.webp` | home sales.background | 14.5 | `/media/_v/2022/12/bk2-webp.avif` | 13.3 | `/media/_v/2022/12/bk2-webp.webp` | 13.8 |
| `/media/2022/12/bodybk.webp` | home clients.background | 71.8 | `/media/_v/2022/12/bodybk-webp.avif` | 60.6 | none (not smaller) | - |

### Device screens (Products: components/product/device.blade.php, background-image)

| Source | Used by | Source KB | AVIF (full size) | KB | WebP (full size) | KB |
|---|---|---:|---|---:|---|---:|
| `/media/2022/12/crmScreen-1.webp` | crm-system hero.device_screen | 29.2 | `/media/_v/2022/12/crmScreen-1-webp.avif` | 21.3 | `/media/_v/2022/12/crmScreen-1-webp.webp` | 24.3 |
| `/media/2022/12/dealcrmscreen-1.webp` | crm-system quick_deals.device_screen | 26.1 | `/media/_v/2022/12/dealcrmscreen-1-webp.avif` | 18.0 | `/media/_v/2022/12/dealcrmscreen-1-webp.webp` | 22.4 |
| `/media/2022/12/inventorylistbk.webp` | inventory-management hero.device_screen | 75.5 | `/media/_v/2022/12/inventorylistbk-webp.avif` | 56.0 | `/media/_v/2022/12/inventorylistbk-webp.webp` | 69.3 |
| `/media/2022/12/vehicleDetailsbk-1.webp` | inventory-management details.device_screen | 40.4 | `/media/_v/2022/12/vehicleDetailsbk-1-webp.avif` | 23.7 | `/media/_v/2022/12/vehicleDetailsbk-1-webp.webp` | 32.0 |
| `/media/2022/12/testdrivescreen.webp` | leads-center test_drive.device_screen | 23.6 | `/media/_v/2022/12/testdrivescreen-webp.avif` | 12.2 | `/media/_v/2022/12/testdrivescreen-webp.webp` | 14.4 |
| `/media/2022/12/creditscreen.webp` | leads-center credit_leads.device_screen | 61.3 | `/media/_v/2022/12/creditscreen-webp.avif` | 38.8 | `/media/_v/2022/12/creditscreen-webp.webp` | 55.5 |
| `/media/2022/12/marketingscreen-1.webp` | marketing-tools interface.device_screen | 33.8 | `/media/_v/2022/12/marketingscreen-1-webp.avif` | 21.7 | `/media/_v/2022/12/marketingscreen-1-webp.webp` | 26.5 |
| `/media/2022/12/websiteipadscreen.webp` | website hero.device_screen | 59.7 | `/media/_v/2022/12/websiteipadscreen-webp.avif` | 47.0 | none (not smaller) | - |
| `/media/2022/12/displaypagescreen.webp` | website display_page.device_screen | 103.4 | `/media/_v/2022/12/displaypagescreen-webp.avif` | 79.6 | none (not smaller) | - |

Biggest wins: home hero `bkhero` 158 -> 103.5 KB, footer `footerbk` 33.3 -> 7.2 KB (every page),
design-studio hero 81.6 -> 36.9 KB, `screenmac3-scaled` 95.6 -> 57.3 KB, `creditscreen` 61.3 -> 38.8 KB.
The small product hero backgrounds (5-10 KB) gain little.

## 3. Preloads

`<x-seo.preload :image="...">` now preloads the full-size AVIF (`type="image/avif"`) when one exists,
which is the file `image-set()` picks. **Site: until the home hero uses `image-set()`, that preload
fetches a file the CSS does not use**; please switch the home hero in the same change (or pass
`:image-srcset` explicitly). Fonts passed to `:fonts` that do not exist in `public/fonts/` are now
skipped automatically, but please update the call in `pages/home.blade.php`, which still names
`raleway-900.woff2` and `saira-semi-condensed-400.woff2`, to the Poppins/Rubik file actually used above
the fold (e.g. `/fonts/poppins-600.woff2` or `poppins-700.woff2` for the hero heading).

## 4. Video

Checked with headless Chrome (`php scripts/qa/video.php`, cache disabled, page scrolled to the end):
home, about, contact, request-demo, talk-to-sales and IDMS request **0 bytes** of
`iDealers-Intro-Promo.mp4` before play (`<video preload="none">`, popup `<video>` without `src` until
click); pressing play loads it (9,383.7 KB). **No change is required for the "no bytes before play" rule.**

Optional, for the poster (Site, `components/ui/video.blade.php`): the thumbnail is
`/media/2022/06/login-bk1.webp` (1920x1080, 59.9 KB) shown in a small box. Two small changes would cut it to
about 6-15 KB:
1. render the thumbnail with `<x-media.img :src="$poster" :alt="$posterAlt" class="video__thumb" sizes="(max-width: 767px) 100vw, 560px" />`
   (variants exist: `/media/_v/2022/06/login-bk1-webp-480w.avif`, `-800w`, `-1200w`, full `login-bk1-webp.avif` 14.6 KB);
2. drop the `poster` attribute from the `<video>` while the thumbnail button is rendered (the button
   covers the video until play, so the poster is never seen, but its URL would be fetched as a second
   file once the thumbnail comes from `<picture>`). A lightweight poster for when no thumbnail is set:
   `/media/_v/2022/06/login-bk1-webp-800w.webp`.
