# Otimizador de Imagens (ImageOptimizer) V2

O `ImageOptimizer` é um serviço de alto desempenho projetado para automatizar a geração de variantes responsivas e a conversão de imagens para formato **WebP** no ecossistema V2.

## Arquitetura e Performance

O serviço utiliza a extensão nativa **PHP Imagick** (v3.4+) para processamento de imagem. O ambiente Docker do projeto tem suporte a WebP habilitado.

### Geração de Variantes

- **Larguras padrão**: 360px, 720px, 1200px, 1920px
- **Qualidade**: 75 (fixa, balanced entre qualidade e compressão)
- **Formato**: WebP (strip de metadados para menor peso)
- **Fallback p/ imagens < 360px**: Gera automaticamente 1 variante WebP na largura original com chave `original` — garante que toda imagem tenha ao menos 1 WebP

### Tratamento de SVGs

SVGs (`image/svg+xml`) são **excluídos** da otimização WebP no `MediaInputer`. São armazenados e servidos como SVG original, sem tentativa de conversão.

### Propagação de Erros

Diferente da implementação anterior (que silenciava exceções e retornava `[]`), o `ImageOptimizer` agora **propaga exceções** para o chamador. Isso garante que seeders, controllers e serviços tomem ciência de falhas no processamento.

```
generateVariants() → se falhar → throw \Exception → MediaInputer catch → log + seed catch → warning visível
```

## Fluxo Completo de Otimização

```
Upload / Seed
  → MediaInputer::processUpload()
    → storeFileResiliently()    → salva original (S3 → local fallback)
    → verifica MIME
      ├─ image/svg+xml → variants = [] (ignora otimização)
      ├─ image/*       → ImageOptimizer::generateVariants()
      │                  ├─ largura ≥ 360px → [360, 720, 1200, 1920]w.webp
      │                  └─ largura < 360px → [original → nome.webp]
      ├─ application/pdf → PdfVisualOptimizer
      ├─ audio/*         → AudioOptimizer
      └─ spreadsheet     → SpreadsheetOptimizer
  → DB::insert com variants em JSON
  → return DB row
```

## Componente Picture

O componente `v2-service-media::components.picture` renderiza a tag `<picture>` com:

- **Múltiplos `<source>` WebP**: ordenados do maior para o menor, com `media="(min-width: Npx)"`
- **`<img>` fallback**: sempre presente para navegadores sem suporte a WebP
- **Prevenção de double-download**: quando há variantes, o `<img>` recebe `loading="lazy"` mesmo se o parâmetro `lazy=false` for passado. Isso impede o Chrome preload scanner de baixar o PNG/JPG original desnecessariamente.
- **`fetchpriority="high"`**: aplicado ao primeiro `<source>` WebP quando `lazy=false`, garantindo carregamento prioritário da versão otimizada.

### Parâmetros

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `originalPath` | string | obrigatório | Caminho relativo da imagem original |
| `variants` | array | `[]` | Array `[largura => caminho_relativo]` das WebP |
| `alt` | string | `''` | Texto alternativo (WCAG) |
| `class` | string | `'img-responsive rounded'` | Classes CSS |
| `style` | string | `''` | Estilos inline |
| `lazy` | bool | `true` | Se `true`, aplica `loading="lazy"` no `<img>`. Se `false` MAS há variantes, ainda aplica lazy no `<img>` (anti-double-download) e `fetchpriority="high"` no 1º `<source>` |
| `disk` | string | `'public'` | Disco de storage (resolvido via `v2_storage_url()`) |

## Integração com o GalleryService

```php
use V2\Services\Gallery\Services\GalleryService;
use V2\Services\Gallery\DTOs\GalleryConfig;

$gallery = app(GalleryService::class);
$config = new GalleryConfig('meu-modulo', ['image/*'], 10240, false);

$result = $gallery->seedFromPath($localPath, $config, $filename, $altText);
// $result['file_path']  → caminho do original
// $result['variants']   → string JSON das variantes
```

## Seeder: Verificação de Variantes

Ao processar imagens em seeders, SEMPRE verifique se variantes foram geradas:

```php
$media = $gallery->seedFromPath($fullPath, $galleryConfig, $key, $info['alt']);

$variants = isset($media['variants']) ? json_decode($media['variants'], true) : [];
if (empty($variants)) {
    $this->command->warn("  ⚠ Nenhuma variante WebP gerada para {$path}");
} else {
    $this->command->info("  ✓ WebP: " . implode(', ', array_keys($variants)) . "px");
}
```

## Localização do Código

- **ImageOptimizer**: `V2/Services/Media/Services/Midia/ImageOptimizer.php`
- **MediaInputer**: `V2/Services/Media/Services/MediaInputer.php`
- **Picture Component**: `V2/Services/Media/Views/components/picture.blade.php`
- **GalleryService**: `V2/Services/Gallery/Services/GalleryService.php`
- **Wiki**: `wiki/v2/servicos/image-optimizer.md`
- **Guia CMS**: `V2/Services/Media/CMS_INTEGRATION.md`

---

*Atualizado em Julho de 2026.*