Add textless poster art for mobile featured heroes

[blurbery]

What I changed

I added a safe, authenticated way for the mobile apps to request clean textless poster art for featured hero cards. This keeps the phone design consistent without using an admin image route or trying to scrape artwork client-side.

The endpoint:

• uses the same catalogue access checks as the rest of the viewer API
• supports movies and series only
• selects the best portrait artwork explicitly marked as textless, with a conservative language fallback when the provider does not include that flag
• returns an empty successful response when no suitable artwork exists, so clients can fall back cleanly
• uses bounded positive and negative caching plus singleflight request sharing to avoid repeated provider work
• is advertised through the images capability response

I also exposed the existing media tagline in Home section items so the phone hero can show a short quote instead of truncating a long overview.

Linked mobile PRs

• Apple hero: Add a server-driven featured hero on iOS silo-apple#197
• Android hero: Add a server-driven featured hero on Android silo-android#248

These three PRs are designed to land together. The clients retain their normal poster/title fallbacks if the new endpoint is unavailable.

Testing

• go test ./internal/api/handlers
• go test ./internal/api
• Added coverage for authentication, catalogue access, supported content types, textless selection, fallbacks, caching, cancellation, capability advertisement, and Home taglines.

AI disclosure

I designed the mobile hero experience and its clean-art behaviour, directed the implementation, and tested the result in the iPhone and Android emulators. I used OpenAI Codex (GPT-5) to help implement and refine the code.

Summary by CodeRabbit

• New Features
  • Added optional textless portrait posters for movies and series, with secure access checks and provider-based image selection.
  • Added capability metadata describing textless poster availability and supported media types.
  • Added optional tagline information to section item responses.
• Documentation
  • Updated image API documentation with textless poster configuration, response details, and supported options.
• Bug Fixes
  • Improved poster selection with fallback handling when explicit text metadata is unavailable.
  • Improved image retrieval reliability through caching and request handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c195f5b6-8f87-40e9-a584-46492ced4706

📥 Commits

Reviewing files that changed from the base of the PR and between 02ef482 and 463f93d.

📒 Files selected for processing (2)

• internal/api/handlers/images_capability.go
• internal/api/handlers/textless_poster.go

🚧 Files skipped from review as they are similar to previous changes (1)

• internal/api/handlers/textless_poster.go

Included review availability: Your plan provides up to 2 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The API now supports authenticated textless portrait posters for movies and series. Capability metadata reports route availability. Section item responses now include optional media taglines.

Changes

Textless poster delivery

Layer / File(s)	Summary
Poster handler and selection internal/api/handlers/textless_poster.go, internal/api/handlers/textless_poster_test.go	Adds access validation, provider image retrieval, request coalescing, bounded caching, URL resolution, and textless portrait poster selection. Tests cover selection precedence, neutral fallback, and unauthorized access.
Capability and route wiring internal/api/handlers/images_capability.go, internal/api/handlers/images_capability_test.go, internal/api/router.go, docs/images-api.md	Wires the handler when dependencies are available, registers the authenticated route, advertises supported media types, and documents the endpoint and response behavior.

Section tagline output

Layer / File(s)	Summary
Section item tagline propagation internal/api/handlers/sections.go, internal/api/handlers/sections_test.go	Adds optional tagline output and verifies episode tagline propagation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 463f9

The change is merge-ready after normal checks and review; no actionable merge-blocking risk remains in the supplied evidence.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Router
  participant TextlessPosterHandler
  participant Catalog
  participant MetadataProvider
  participant ImageURLResolver
  Client->>Router: GET /catalog/items/{id}/images/textless-poster
  Router->>TextlessPosterHandler: dispatch authenticated request
  TextlessPosterHandler->>Catalog: validate access and load item
  TextlessPosterHandler->>MetadataProvider: fetch provider images
  MetadataProvider-->>TextlessPosterHandler: return poster candidates
  TextlessPosterHandler->>ImageURLResolver: resolve featured URL
  ImageURLResolver-->>TextlessPosterHandler: return poster URL
  TextlessPosterHandler-->>Client: return poster response

Loading

Suggested reviewers: quick104

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 29.41% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 7 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding textless poster art for mobile featured heroes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}