From e0ef1dee77b4f52fcda991678f55adc677403028 Mon Sep 17 00:00:00 2001
From: Anthony GAEREMYNCK <1@anthony.sh>
Date: Tue, 11 Aug 2026 15:12:51 +0200
Subject: [PATCH] docs: add design spec for 4K quality support

---
 .../specs/2026-08-11-4k-support-design.md     | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-11-4k-support-design.md

diff --git a/docs/superpowers/specs/2026-08-11-4k-support-design.md b/docs/superpowers/specs/2026-08-11-4k-support-design.md
new file mode 100644
index 0000000..747379b
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-11-4k-support-design.md
@@ -0,0 +1,53 @@
+# 4K support in video downloads
+
+## Purpose
+
+Add 4K (2160p) and 2K (1440p) as selectable download quality tiers, and update marketing
+copy that currently caps the advertised resolution at 1080p.
+
+## Context
+
+The download pipeline already resolves quality generically:
+
+- `src/lib/ytdlp-options.ts` exports `QUALITIES`, a fixed list consumed by the probe
+  (`src/lib/ytdlp-probe.ts`) to compute which qualities are actually available for a given
+  source video (filtered against the max height yt-dlp reports), and by the UI
+  (`src/components/SubmitForm.tsx`, via `capabilities.availableQualities`) to render the
+  quality `<select>`.
+- `src/lib/ytdlp.ts` (`buildYtdlpArgs`) turns the selected quality string into a yt-dlp
+  format selector via `height<=?${quality.replace('p', '')}`, with no hardcoded ceiling.
+
+Because both the filtering and the format-selector logic are already generic over the
+quality string, no logic changes are required — only the `QUALITIES` list itself, its
+tests, and marketing copy need to change.
+
+## Changes
+
+### 1. Quality list — `src/lib/ytdlp-options.ts`
+
+```ts
+export const QUALITIES = ['best', '2160p', '1440p', '1080p', '720p', '480p', '360p'] as const
+```
+
+### 2. Tests
+
+- `src/lib/__tests__/ytdlp-probe.test.ts`: add a case with a 4K-height fixture
+  (`height: 2160`) asserting `availableQualities` includes `'2160p'` and `'1440p'`. The
+  existing 1080p-source case is unaffected (2160p/1440p correctly excluded since
+  `maxHeight` there is 1080).
+- `src/lib/__tests__/ytdlp.test.ts`: add a case for `quality: '2160p'` asserting the built
+  args contain `height<=?2160`, mirroring the existing `1080p` case.
+
+### 3. Marketing copy — `messages/{en,fr,es,it}.json`
+
+Replace the "up to 1080p" claim (and localized equivalents) with "up to 4K" in the 5
+affected keys, in each of the 4 locale files: `formatsDesc`, `step2Desc`, `a4`, and the two
+`faqA2` occurrences (home FAQ + platform-page FAQ). Only the resolution figure changes;
+surrounding wording stays identical.
+
+## Out of scope
+
+- No change to the download pipeline, worker, or database schema — the format selector and
+  probe filtering are already resolution-agnostic.
+- No change to per-platform SEO page copy (`src/lib/downloader-platforms.ts`) — it does not
+  mention a specific resolution ceiling.