updates

AGENT.MD

@@ -10,6 +10,9 @@ It currently supports:
 - Generating a wide `Thumb` image
 - Optionally generating a matching tall `Primary` poster
 - Using Emby-known logos and backdrops already attached to the item
+- Reframing any Emby or imported image in a premium artwork editor
+- Exporting editor output as `Primary`, `Thumb`, or `Backdrop`
+- Searching provider-backed external image sources and importing remote images into cache
 - Applying generated artwork back to Emby
 - Adding optional studio badges and a red `NEW EPISODES` series tag
 
@@ -154,6 +157,41 @@ Important:
 - `Apply` must remain tolerant of cache misses
 - Do not reintroduce a hard dependency on a pre-existing cache file only
 
+### 5. Artwork editor flow
+
+Browser:
+
+- The editor appears after an Emby item is selected
+- Editor state is kept separate from the existing thumb-generator `state` object
+- The editor has three panels:
+  - source image panel
+  - fixed-ratio editor canvas
+  - export panel
+- Users can choose Emby `Primary`, selected Emby `Backdrop`, Emby `Thumb`, or an imported remote image
+- Users can target `poster`, `thumb`, or `backdrop`
+- Users can drag, zoom, reset, and switch `cover` / `contain`
+- Landscape-to-portrait conversion supports blurred, mirrored, or solid background fill
+- `POST /api/artwork/export` generates a live preview and returns cache headers
+- `POST /api/artwork/apply` uploads the cached or regenerated export to the matching Emby image type
+
+Server:
+
+- Editor rendering is separate from `generate_thumbnail(...)`
+- `render_artwork_editor_image(...)` handles fixed-frame reframing and high-quality JPEG output
+- `fit_image_positioned(...)` is the shared crop/contain positioning helper
+- `build_editor_fill(...)` handles blurred, mirrored, and solid background fill
+- `resolve_editor_source_bytes(...)` loads either Emby source bytes or cached remote imports
+- Editor exports are cached as `<cache_key>.editor.jpg`
+- Remote imports are cached under `cache/imports/`
+
+Remote image search:
+
+- Provider lookup is intentionally abstracted behind `ImageSearchProvider`
+- `GET /api/artwork/providers` exposes available providers to the UI
+- `GET /api/artwork/search` calls the selected provider
+- `POST /api/artwork/import` downloads, validates, size-limits, and caches a selected remote image
+- The first provider is Wikimedia Commons; add future providers by implementing `ImageSearchProvider` and registering it in `IMAGE_SEARCH_PROVIDERS`
+
 ## Rendering Pipeline
 
 The central renderer is `generate_thumbnail(...)`.
@@ -196,6 +234,8 @@ Current cache helpers:
 
 - Thumb cache: `<cache_key>.png`
 - Primary cache: `<cache_key>.primary.png`
+- Artwork editor export cache: `<cache_key>.editor.jpg`
+- Imported remote image cache: `cache/imports/<sha256>.img`
 
 The cache key is derived from rendering inputs such as:
 
@@ -279,6 +319,22 @@ When adding a new visual option:
 
 If any of those steps are skipped, behavior will drift.
 
+Artwork editor state is intentionally separate:
+
+- `editorState.sourceKind`
+- `editorState.sourceType`
+- `editorState.sourceIndex`
+- `editorState.importId`
+- `editorState.cacheKey`
+- transform controls from the editor sliders
+
+Keep editor payloads aligned across:
+
+- `/api/artwork/export`
+- `/api/artwork/apply`
+- `build_editor_cache_key(...)`
+- `render_artwork_editor_image(...)`
+
 ## Laptop UX Constraints
 
 The app has custom responsive rules for laptop-sized screens.
@@ -378,8 +434,7 @@ python -m py_compile app.py
 
 Likely next improvements:
 
-- Separate primary preview in the UI
-- Remote/provider image search from Emby metadata sources
+- Additional image search providers from Emby metadata sources
 - Better poster-specific typography/layout rules
 - Better user-visible error reporting for partial apply failures
 - Cache cleanup strategy