From 0b88ca251f47fb39dac301fd74a858717e71a546 Mon Sep 17 00:00:00 2001
From: chodeus <190988615+chodeus@users.noreply.github.com>
Date: Sat, 22 Aug 2026 08:10:01 +0800
Subject: [PATCH] feat(cl2k): mirror the artwork horizontally
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A Mirror toggle on the poster, square-art and background-art makers
flips the artwork left-to-right — for backdrops whose subject faces out
of frame.

The flip lands at the END of framing, not on the source bytes, and that
placement is the whole design. The AI text-removal mask and the extend
outpaint are built in source space, so flipping the source first would
put every brush stroke on the wrong side of the picture; the logo and
label are composited after the artwork, so flipping the finished poster
would render the season band backwards. _framed_inset_base and
render_framed_art are the two points where framing is finished and
nothing else is drawn yet, so both flop there.

Applying it last also means no coordinate is re-mapped: the framer keeps
showing the source as it is, and toggling Mirror leaves the crop box and
focal point exactly where they were.

The .psd export follows the poster (both go through frame_backdrop) and
the season batch carries the flag, so a bulk run matches its preview.
---
 backend/api/cl2k_maker.py                   |  14 +
 backend/modules/cl2k_maker.py               |  12 +
 backend/util/cl2k/renderer.py               |  26 +-
 frontend/src/pages/poster/Cl2kMakerPage.jsx | 105 +++++-
 tests/test_cl2k_mirror.py                   | 336 ++++++++++++++++++++
 5 files changed, 485 insertions(+), 8 deletions(-)
 create mode 100644 tests/test_cl2k_mirror.py

diff --git a/backend/api/cl2k_maker.py b/backend/api/cl2k_maker.py
index 80a24f3e..f81ffbe7 100644
--- a/backend/api/cl2k_maker.py
+++ b/backend/api/cl2k_maker.py
@@ -142,6 +142,9 @@ class GenerateRequest(BaseModel):
     # fit (sides crop) so a wide backdrop isn't shrunk to a tiny strip; in cover
     # ("Fill"), <1 shrinks the art below the fill onto black. 1.0 = plain fit/cover.
     zoom: float = Field(1.0, ge=geo.ZOOM_MIN, le=geo.ZOOM_MAX)
+    # Mirror: flip the artwork horizontally. Applied at the END of framing, so
+    # the crop/focal point, the AI mask and the logo/label are unaffected.
+    mirror: bool = False
     # Explicit bottom banner (e.g. "COMPLETE LIMITED SERIES"); overrides the auto
     # COLLECTION / season label when set.
     band_label: str = ""
@@ -661,6 +664,7 @@ def preview(
             crop=_crop_tuple(req),
             v_pos=req.v_pos,
             zoom=req.zoom,
+            mirror=req.mirror,
             band_label=req.band_label,
             logo_scale=req.logo_scale,
             logo_y_offset=req.logo_y_offset,
@@ -723,6 +727,7 @@ def generate(
             crop=_crop_tuple(req),
             v_pos=req.v_pos,
             zoom=req.zoom,
+            mirror=req.mirror,
             band_label=req.band_label,
             logo_scale=req.logo_scale,
             logo_y_offset=req.logo_y_offset,
@@ -779,6 +784,7 @@ class SquareArtRequest(BaseModel):
     v_pos: float = Field(0.0, ge=geo.V_POS_MIN, le=geo.V_POS_MAX)
     fit_mode: str = "cover"  # cover (focal crop) | fit (contain on black)
     zoom: float = Field(1.0, ge=geo.ZOOM_MIN, le=geo.ZOOM_MAX)
+    mirror: bool = False  # flip the artwork horizontally
     save_local: bool = True
     upload_gdrive: Optional[bool] = None
 
@@ -867,6 +873,7 @@ def square_preview(
             fit_mode=req.fit_mode,
             v_pos=req.v_pos,
             zoom=req.zoom,
+            mirror=req.mirror,
         ),
     )
 
@@ -902,6 +909,7 @@ def square_generate(
             fit_mode=req.fit_mode,
             v_pos=req.v_pos,
             zoom=req.zoom,
+            mirror=req.mirror,
             season_number=req.season_number,
             save_local=req.save_local,
             upload_gdrive=req.upload_gdrive,
@@ -927,6 +935,7 @@ class BackgroundArtRequest(BaseModel):
     v_pos: float = Field(0.0, ge=geo.V_POS_MIN, le=geo.V_POS_MAX)
     fit_mode: str = "cover"  # cover (focal crop) | fit (contain on black)
     zoom: float = Field(1.0, ge=geo.ZOOM_MIN, le=geo.ZOOM_MAX)
+    mirror: bool = False  # flip the artwork horizontally
     resolution: str = "1080p"  # 1080p (1920x1080) | 4k (3840x2160), per Plex dims
     save_local: bool = True
     upload_gdrive: Optional[bool] = None
@@ -954,6 +963,7 @@ def background_preview(
             fit_mode=req.fit_mode,
             v_pos=req.v_pos,
             zoom=req.zoom,
+            mirror=req.mirror,
         ),
     )
 
@@ -989,6 +999,7 @@ def background_generate(
             fit_mode=req.fit_mode,
             v_pos=req.v_pos,
             zoom=req.zoom,
+            mirror=req.mirror,
             resolution=req.resolution,
             season_number=req.season_number,
             save_local=req.save_local,
@@ -1176,6 +1187,7 @@ def psd_export(
             crop=_crop_tuple(req),
             v_pos=req.v_pos,
             zoom=req.zoom,
+            mirror=req.mirror,
             whiten=req.whiten,
             flat_white=req.flat_white,
             logo_3d=req.logo_3d,
@@ -1219,6 +1231,7 @@ class SeasonsRequest(BaseModel):
     crop_h: Optional[float] = None
     v_pos: float = Field(0.0, ge=geo.V_POS_MIN, le=geo.V_POS_MAX)
     zoom: float = Field(1.0, ge=geo.ZOOM_MIN, le=geo.ZOOM_MAX)
+    mirror: bool = False  # flip the artwork horizontally
     logo_scale: float = Field(1.0, ge=geo.LOGO_SCALE_MIN, le=geo.LOGO_SCALE_MAX)
     logo_y_offset: int = Field(0, ge=geo.LOGO_Y_OFFSET_MIN, le=geo.LOGO_Y_OFFSET_MAX)
     whiten: Optional[bool] = None  # None = module config (whiten_logo)
@@ -1374,6 +1387,7 @@ def _progress(entry: Dict[str, Any]) -> None:
                 crop=_crop_tuple(req),
                 v_pos=req.v_pos,
                 zoom=req.zoom,
+                mirror=req.mirror,
                 logo_scale=req.logo_scale,
                 logo_y_offset=req.logo_y_offset,
                 whiten=req.whiten,
diff --git a/backend/modules/cl2k_maker.py b/backend/modules/cl2k_maker.py
index 4a44bbe6..613e0d82 100644
--- a/backend/modules/cl2k_maker.py
+++ b/backend/modules/cl2k_maker.py
@@ -202,6 +202,7 @@ def _resolve_and_render(
     crop: Optional[Tuple[float, float, float, float]] = None,
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
     band_label: str = "",
     logo_scale: float = 1.0,
     logo_y_offset: int = 0,
@@ -392,6 +393,7 @@ def _resolve_and_render(
         crop=crop,
         v_pos=v_pos,
         zoom=zoom,
+        mirror=mirror,
         band_label=band_label,
         place_logo=place_logo,
         text_logo_stroke=cfg.text_logo_stroke,
@@ -435,6 +437,7 @@ def generate_for_item(
     crop: Optional[Tuple[float, float, float, float]] = None,
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
     band_label: str = "",
     logo_scale: float = 1.0,
     logo_y_offset: int = 0,
@@ -507,6 +510,7 @@ def generate_for_item(
         crop=crop,
         v_pos=v_pos,
         zoom=zoom,
+        mirror=mirror,
         band_label=band_label,
         logo_scale=logo_scale,
         logo_y_offset=logo_y_offset,
@@ -560,6 +564,7 @@ def generate_square_art(
     fit_mode: str = "cover",
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
     season_number: Optional[int] = None,
     save_local: bool = True,
     upload_gdrive: Optional[bool] = None,
@@ -600,6 +605,7 @@ def generate_square_art(
         fit_mode=fit_mode,
         v_pos=v_pos,
         zoom=zoom,
+        mirror=mirror,
     )
     return _persist_poster(
         db,
@@ -643,6 +649,7 @@ def generate_background_art(
     fit_mode: str = "cover",
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
     resolution: str = "1080p",
     season_number: Optional[int] = None,
     save_local: bool = True,
@@ -689,6 +696,7 @@ def generate_background_art(
         fit_mode=fit_mode,
         v_pos=v_pos,
         zoom=zoom,
+        mirror=mirror,
     )
     return _persist_poster(
         db,
@@ -1444,6 +1452,7 @@ def generate_seasons(
     crop: Optional[Tuple[float, float, float, float]] = None,
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
     logo_scale: float = 1.0,
     logo_y_offset: int = 0,
     whiten: Optional[bool] = None,  # None = module config (whiten_logo)
@@ -1499,6 +1508,7 @@ def generate_seasons(
                 crop=crop,
                 v_pos=v_pos,
                 zoom=zoom,
+                mirror=mirror,
                 logo_scale=logo_scale,
                 logo_y_offset=logo_y_offset,
                 whiten=whiten,
@@ -1552,6 +1562,7 @@ def psd_for_item(
     crop: Optional[Tuple[float, float, float, float]] = None,
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
     whiten: Optional[bool] = None,  # None = module config (whiten_logo)
     flat_white: bool = False,  # paint the logo a flat pure-white silhouette
     logo_3d: bool = False,  # extruded art -> flat-white lit face; wins over flat_white
@@ -1599,6 +1610,7 @@ def psd_for_item(
         crop=crop,
         v_pos=v_pos,
         zoom=zoom,
+        mirror=mirror,
     )
     logo_bytes = custom_logo_bytes
     if logo_bytes is None and logo_path:
diff --git a/backend/util/cl2k/renderer.py b/backend/util/cl2k/renderer.py
index 2e57c558..374c1bc8 100644
--- a/backend/util/cl2k/renderer.py
+++ b/backend/util/cl2k/renderer.py
@@ -947,6 +947,7 @@ def render_framed_art(
     fit_mode: str = "cover",
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
 ) -> bytes:
     """Render plain framed artwork at ``width``×``height`` — no gradient/logo/label.
 
@@ -957,7 +958,7 @@ def render_framed_art(
     horizontally and ``v_pos`` (-1..1, 0 = centred) vertically, where the image
     overflows the canvas; plain black letterbox where it doesn't. There is no
     gradient here to hide an extended band, so ``v_pos`` is source-bounded both
-    ways. Encoded at CL2K quality.
+    ways. ``mirror`` flips the finished frame horizontally. Encoded at CL2K quality.
     """
     zoom = max(geo.ZOOM_MIN, min(float(zoom or 1.0), geo.ZOOM_MAX))
     with Image(blob=backdrop_bytes) as img:
@@ -977,6 +978,8 @@ def render_framed_art(
         oy = -_v_pos_top(nh, height, v_pos) if nh >= height else (height - nh) // 2
         with Image(width=width, height=height, background=Color("black")) as canvas:
             canvas.composite(img, left=ox, top=oy)
+            if mirror:
+                canvas.flop()
             return _encode_jpeg(canvas)
 
 
@@ -988,6 +991,7 @@ def render_square_art(
     fit_mode: str = "cover",
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
 ) -> bytes:
     """Render square (1:1) art from a backdrop/poster — just the framed artwork."""
     return render_framed_art(
@@ -998,6 +1002,7 @@ def render_square_art(
         fit_mode=fit_mode,
         v_pos=v_pos,
         zoom=zoom,
+        mirror=mirror,
     )
 
 
@@ -1009,6 +1014,7 @@ def _framed_inset_base(
     crop: Optional[Tuple[float, float, float, float]],
     v_pos: float,
     zoom: float,
+    mirror: bool,
 ) -> Image:
     """Frame the backdrop FULL-BLEED and return a full CANVAS image.
 
@@ -1025,6 +1031,11 @@ def _framed_inset_base(
 
     render_cl2k and frame_backdrop both go through here, so they stay
     pixel-identical (the PSD POSTER-layer parity the exporter relies on).
+
+    ``mirror`` flips the framed artwork horizontally. It lands HERE, at the end
+    of framing, rather than on the source bytes: the AI text-removal mask and the
+    extend outpaint (modules.cl2k_maker) are brushed/built in source space, and
+    the logo/label the caller composites next must never come out backwards.
     """
     base = Image(
         width=geo.CANVAS_W, height=geo.CANVAS_H, background=Color(geo.BORDER_COLOR)
@@ -1035,6 +1046,8 @@ def _framed_inset_base(
         else:
             _cover_resize(art, geo.CANVAS_W, geo.CANVAS_H, focus_x, v_pos, zoom)
         base.composite(art, left=0, top=0)
+    if mirror:
+        base.flop()
     return base
 
 
@@ -1046,6 +1059,7 @@ def frame_backdrop(
     crop: Optional[Tuple[float, float, float, float]] = None,
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
 ) -> bytes:
     """Frame a backdrop to the 2:3 canvas exactly as :func:`render_cl2k` would
     and return PNG bytes.
@@ -1062,6 +1076,7 @@ def frame_backdrop(
         crop=crop,
         v_pos=v_pos,
         zoom=zoom,
+        mirror=mirror,
     ) as base:
         base.format = "png"
         return base.make_blob()
@@ -1089,6 +1104,7 @@ def render_cl2k(
     crop: Optional[Tuple[float, float, float, float]] = None,
     v_pos: float = 0.0,
     zoom: float = 1.0,
+    mirror: bool = False,
     band_label: str = "",
     place_logo: bool = True,
     text_logo_stroke: int = 0,
@@ -1114,6 +1130,9 @@ def render_cl2k(
       optionally isolates the subject region first; the black bottom band is the
       gradient/logo zone. ``v_pos`` applies here too, but on :func:`_fit_resize`'s
       0..1 top-anchored scale (0 = top), not cover's -1..1.
+
+    ``mirror`` flips the ARTWORK horizontally; the logo and label are composited
+    afterwards and stay the right way round.
     """
     kind = kind.lower()
     baseline = geo.logo_baseline(kind)
@@ -1127,6 +1146,7 @@ def render_cl2k(
         crop=crop,
         v_pos=v_pos,
         zoom=zoom,
+        mirror=mirror,
     ) as base:
         with Image(filename=str(geo.GRADIENT_PNG)) as grad:
             base.composite(grad, left=0, top=0)
@@ -1341,6 +1361,9 @@ def main() -> None:
     ap.add_argument(
         "--no-whiten", action="store_true", help="keep the logo's original colours"
     )
+    ap.add_argument(
+        "--mirror", action="store_true", help="flip the artwork horizontally"
+    )
     ap.add_argument("--font", help="font file for text")
     ap.add_argument("--out", required=True, help="output .jpg path")
     args = ap.parse_args()
@@ -1360,6 +1383,7 @@ def main() -> None:
         season_text=args.season_text,
         logo_max_width=args.width,
         whiten=not args.no_whiten,
+        mirror=args.mirror,
         font_path=args.font,
     )
     with open(args.out, "wb") as fh:
diff --git a/frontend/src/pages/poster/Cl2kMakerPage.jsx b/frontend/src/pages/poster/Cl2kMakerPage.jsx
index 7e2e9a80..9467f033 100644
--- a/frontend/src/pages/poster/Cl2kMakerPage.jsx
+++ b/frontend/src/pages/poster/Cl2kMakerPage.jsx
@@ -1294,6 +1294,10 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
     // wide backdrop isn't shrunk to a tiny strip.
     const [zoom, setZoom] = useState(saved.zoom ?? 1);
     const [focusX, setFocusX] = useState(saved.focusX ?? 0.5);
+    // Mirror flips the ARTWORK only, at the end of the backend's framing — the
+    // crop box, focal point and AI mask all stay in unmirrored source space, so
+    // nothing here re-maps and the framer keeps showing the source as it is.
+    const [mirror, setMirror] = useState(saved.mirror ?? false);
     // Measured by CropFramer's <img onLoad>; owned here because the Vertical
     // position slider's real range depends on it. null until measured.
     const [backdropRatio, setBackdropRatio] = useState(null);
@@ -1340,6 +1344,7 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
         setVPos(0);
         setZoom(1);
         setFocusX(0.5);
+        setMirror(false); // which way a subject faces is a property of THAT image
         setBackdropRatio(null); // re-measured by the new image's onLoad
     }, []);
     // fitMode is deliberately NOT reset — it's a per-user way of working
@@ -1419,6 +1424,7 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
             vPos,
             zoom,
             focusX,
+            mirror,
             logoScale,
             logoYOffset,
             whitenLogo,
@@ -1441,6 +1447,7 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
         vPos,
         zoom,
         focusX,
+        mirror,
         logoScale,
         logoYOffset,
         whitenLogo,
@@ -1681,6 +1688,7 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
             // v_pos applies to every mode now (Fill pans up; fit/extend position).
             v_pos: vPos,
             zoom: zoom,
+            mirror,
             // Banner overrides the auto COLLECTION / SEASON label — e.g. a season
             // poster drawing COMPLETE LIMITED SERIES in place of SEASON N.
             band_label: bandLabel,
@@ -1710,6 +1718,7 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
             vPos,
             zoom,
             focusX,
+            mirror,
             bandLabel,
             saveTargets.saveLocal,
             saveTargets.uploadGdrive,
@@ -1749,6 +1758,7 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
                 vp: vPos,
                 zm: zoom,
                 fx: focusX,
+                mi: mirror,
                 bl: bandLabel,
                 pl: !hasLogo,
                 ti: hasLogo ? null : item.title,
@@ -1769,6 +1779,7 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
             vPos,
             zoom,
             focusX,
+            mirror,
             bandLabel,
             hasLogo,
             logoScale,
@@ -1918,6 +1929,7 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
                 crop_h: (fitMode === 'fit' || fitMode === 'extend') && crop ? crop.h : null,
                 v_pos: vPos,
                 zoom: zoom,
+                mirror,
                 logo_scale: logoScale,
                 logo_y_offset: logoYOffset,
                 save_local: saveTargets.saveLocal,
@@ -1958,6 +1970,7 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
         crop,
         vPos,
         zoom,
+        mirror,
         logoScale,
         logoYOffset,
         toast,
@@ -2089,6 +2102,8 @@ const Builder = ({ item, config, uploadStatus, onReset, onItemChange, toast }) =
                     setVPos={setVPos}
                     zoom={zoom}
                     setZoom={setZoomClamped}
+                    mirror={mirror}
+                    setMirror={setMirror}
                     vPosLimits={vPosLimits}
                     backdropRatio={backdropRatio}
                     onBackdropRatio={onBackdropRatio}
@@ -2259,6 +2274,8 @@ const RenderPanel = ({
     setVPos,
     zoom,
     setZoom,
+    mirror,
+    setMirror,
     vPosLimits,
     backdropRatio,
     onBackdropRatio,
@@ -3208,6 +3225,8 @@ const RenderPanel = ({
                                     focusX={focusX}
                                     vPos={vPos}
                                     zoom={zoom}
+                                    mirror={mirror}
+                                    setMirror={setMirror}
                                     ratio={backdropRatio}
                                     onRatio={onBackdropRatio}
                                     onChange={onFocusChange}
@@ -4270,6 +4289,8 @@ const CropFramer = ({
     focusX,
     vPos,
     zoom,
+    mirror,
+    setMirror,
     onChange,
     // Natural aspect ratio (h/w) of the backdrop, owned by the parent: the
     // Vertical position slider's real travel depends on it, and it must not be
@@ -4424,6 +4445,18 @@ const CropFramer = ({
                     >
                         Extend (AI)
                     </Button>
+                    {/* The photo below stays unmirrored on purpose: the crop box and
+                        the AI mask are both in source space. Only the render flips. */}
+                    <Button
+                        onClick={() => setMirror(!mirror)}
+                        variant={mirror ? 'primary' : 'secondary'}
+                        icon="flip"
+                        size="small"
+                        aria-pressed={mirror}
+                        title="Flip the artwork horizontally (the logo and label stay as they are)"
+                    >
+                        Mirror
+                    </Button>
                     {/* Span wrapper carries the tooltip: a disabled <button>
                         doesn't reliably fire native title tooltips cross-browser. */}
                     <span title={resetTip} className="inline-flex">
@@ -5472,6 +5505,8 @@ const FramingSliders = ({
 // every setter that can shrink the range re-clamps here rather than in an effect.
 const useAssetFraming = aspect => {
     const [vPos, setVPos] = useState(0);
+    // Flips the rendered art only — the framer below keeps showing the source.
+    const [mirror, setMirror] = useState(false);
     const [fitMode, setFitModeRaw] = useState('cover'); // cover (fill) | fit (contain)
     const [zoom, setZoomRaw] = useState(1);
     const [srcRatio, setSrcRatio] = useState(null); // measured from the source image
@@ -5507,7 +5542,19 @@ const useAssetFraming = aspect => {
         },
         [boundsFor, fitMode, zoom]
     );
-    return { vPos, setVPos, fitMode, setFitMode, zoom, setZoom, srcRatio, onSrcRatio, vPosLimits };
+    return {
+        vPos,
+        setVPos,
+        fitMode,
+        setFitMode,
+        zoom,
+        setZoom,
+        mirror,
+        setMirror,
+        srcRatio,
+        onSrcRatio,
+        vPosLimits,
+    };
 };
 
 const SquareFramer = ({
@@ -5519,6 +5566,8 @@ const SquareFramer = ({
     setFitMode,
     zoom,
     setZoom,
+    mirror,
+    setMirror,
     aspect = 1, // target frame h/w: 1 = square, 9/16 = background art
     title = 'Crop to square',
     frameName = '1:1 square',
@@ -5600,6 +5649,18 @@ const SquareFramer = ({
                     >
                         Fit
                     </button>
+                    {/* The photo below stays unmirrored: the drag picks a region of
+                        the SOURCE, and only the rendered art is flipped. */}
+                    <Button
+                        onClick={() => setMirror(!mirror)}
+                        variant={mirror ? 'primary' : 'secondary'}
+                        icon="flip"
+                        size="small"
+                        aria-pressed={mirror}
+                        title="Flip the artwork horizontally"
+                    >
+                        Mirror
+                    </Button>
                     <Button
                         onClick={() => {
                             onChange(0.5, 0);
@@ -5721,8 +5782,19 @@ const SquareArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast }) =
         onSrcRatio(null); // the old ratio must not outlive the old image
     };
     const [focusX, setFocusX] = useState(0.5);
-    const { vPos, setVPos, fitMode, setFitMode, zoom, setZoom, srcRatio, onSrcRatio, vPosLimits } =
-        useAssetFraming(1);
+    const {
+        vPos,
+        setVPos,
+        fitMode,
+        setFitMode,
+        zoom,
+        setZoom,
+        mirror,
+        setMirror,
+        srcRatio,
+        onSrcRatio,
+        vPosLimits,
+    } = useAssetFraming(1);
     const [seasonNumber, setSeasonNumber] = useState(''); // '' = show-level asset
     const [previewUrl, setPreviewUrl] = useState(null);
     const [previewing, setPreviewing] = useState(false);
@@ -5747,6 +5819,7 @@ const SquareArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast }) =
             fit_mode: fitMode,
             v_pos: vPos,
             zoom,
+            mirror,
             save_local: saveTargets.saveLocal,
             upload_gdrive: saveTargets.uploadGdrive,
         }),
@@ -5758,6 +5831,7 @@ const SquareArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast }) =
             fitMode,
             vPos,
             zoom,
+            mirror,
             seasonNum,
             saveTargets.saveLocal,
             saveTargets.uploadGdrive,
@@ -5768,7 +5842,7 @@ const SquareArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast }) =
         reqRef.current = req;
     }, [req]);
 
-    const sig = `${customSig(customBg) || backdrop}|${focusX}|${vPos}|${fitMode}|${zoom}`;
+    const sig = `${customSig(customBg) || backdrop}|${focusX}|${vPos}|${fitMode}|${zoom}|${mirror}`;
     useEffect(() => {
         if (!hasSrc) return undefined;
         let cancelled = false;
@@ -5910,6 +5984,8 @@ const SquareArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast }) =
                             setFitMode={setFitMode}
                             zoom={zoom}
                             setZoom={setZoom}
+                            mirror={mirror}
+                            setMirror={setMirror}
                             ratio={srcRatio}
                             onRatio={onSrcRatio}
                         />
@@ -5985,8 +6061,19 @@ const BackgroundArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast
         onSrcRatio(null); // the old ratio must not outlive the old image
     };
     const [focusX, setFocusX] = useState(0.5);
-    const { vPos, setVPos, fitMode, setFitMode, zoom, setZoom, srcRatio, onSrcRatio, vPosLimits } =
-        useAssetFraming(9 / 16);
+    const {
+        vPos,
+        setVPos,
+        fitMode,
+        setFitMode,
+        zoom,
+        setZoom,
+        mirror,
+        setMirror,
+        srcRatio,
+        onSrcRatio,
+        vPosLimits,
+    } = useAssetFraming(9 / 16);
     const [resolution, setResolution] = useState('1080p'); // 1080p | 4k (Plex dims)
     const [seasonNumber, setSeasonNumber] = useState(''); // '' = show-level asset
     const [previewUrl, setPreviewUrl] = useState(null);
@@ -6012,6 +6099,7 @@ const BackgroundArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast
             fit_mode: fitMode,
             v_pos: vPos,
             zoom,
+            mirror,
             resolution,
             save_local: saveTargets.saveLocal,
             upload_gdrive: saveTargets.uploadGdrive,
@@ -6024,6 +6112,7 @@ const BackgroundArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast
             fitMode,
             vPos,
             zoom,
+            mirror,
             resolution,
             seasonNum,
             saveTargets.saveLocal,
@@ -6036,7 +6125,7 @@ const BackgroundArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast
     }, [req]);
 
     // Preview renders at 1080p regardless of resolution — same 16:9 frame.
-    const sig = `${customSig(customBg) || backdrop}|${focusX}|${vPos}|${fitMode}|${zoom}`;
+    const sig = `${customSig(customBg) || backdrop}|${focusX}|${vPos}|${fitMode}|${zoom}|${mirror}`;
     useEffect(() => {
         if (!hasSrc) return undefined;
         let cancelled = false;
@@ -6178,6 +6267,8 @@ const BackgroundArtPanel = ({ item, artBySource, loadingArt, saveTargets, toast
                             setFitMode={setFitMode}
                             zoom={zoom}
                             setZoom={setZoom}
+                            mirror={mirror}
+                            setMirror={setMirror}
                             ratio={srcRatio}
                             onRatio={onSrcRatio}
                             aspect={9 / 16}
diff --git a/tests/test_cl2k_mirror.py b/tests/test_cl2k_mirror.py
new file mode 100644
index 00000000..183f546e
--- /dev/null
+++ b/tests/test_cl2k_mirror.py
@@ -0,0 +1,336 @@
+"""Tests for mirror, the horizontal artwork flip.
+
+Where the flip lands IS the design. It is applied at the END of framing rather
+than to the source bytes, because the AI text-removal mask and the extend
+outpaint are both built in source space, and because the logo and label are
+composited after the artwork. So mirror has to do exactly two things: flip the
+artwork on every render path, and touch nothing else — a mirrored poster whose
+season band reads backwards is the failure this file exists to catch.
+
+It also has to survive the trip: the flag crosses four layers (request model ->
+api endpoint -> module maker -> renderer), and a forward dropped anywhere shows
+up only as "the toggle does nothing", so each hop is asserted.
+"""
+
+import base64
+import types
+
+import pytest
+
+pytest.importorskip("httpx")
+pytest.importorskip("wand.image")  # Wand + ImageMagick required (cl2k extra)
+
+from fastapi import BackgroundTasks  # noqa: E402
+from wand.color import Color  # noqa: E402
+from wand.image import Image  # noqa: E402
+
+import backend.api.cl2k_maker as api  # noqa: E402
+import backend.modules.cl2k_maker as maker  # noqa: E402
+from backend.util.cl2k import geometry as geo  # noqa: E402
+from backend.util.cl2k.renderer import (  # noqa: E402
+    frame_backdrop,
+    render_cl2k,
+    render_framed_art,
+    render_square_art,
+)
+
+
+def _two_tone(w=1920, h=1080):
+    """Left half red, right half blue — the flip has to swap the halves."""
+    with Image(width=w, height=h, background=Color("red")) as bg:
+        with Image(width=w // 2, height=h, background=Color("blue")) as right:
+            bg.composite(right, left=w // 2, top=0)
+        bg.format = "jpeg"
+        return bg.make_blob()
+
+
+def _sides(blob):
+    """Sample colours 10% in from each edge, on the middle row."""
+    with Image(blob=blob) as img:
+        y = img.height // 2
+        return img[int(img.width * 0.1), y], img[int(img.width * 0.9), y]
+
+
+def _sig(blob, flop=False):
+    """Pixel signature (not encoded bytes — ImageMagick stamps a PNG tIME chunk)."""
+    with Image(blob=blob) as img:
+        if flop:
+            img.flop()
+        return img.signature
+
+
+def _strip(blob, top, height):
+    """Raw RGB of one horizontal strip, for an exact same-pixels comparison."""
+    with Image(blob=blob) as img:
+        img.crop(0, top, width=img.width, height=height)
+        return img.make_blob("RGB")
+
+
+def _logger():
+    return types.SimpleNamespace(
+        info=lambda *a, **k: None,
+        debug=lambda *a, **k: None,
+        warning=lambda *a, **k: None,
+        error=lambda *a, **k: None,
+    )
+
+
+# --------------------------------------------------------------------------
+# the flip itself
+# --------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("size", [(1920, 1080), (1000, 1000)], ids=["16:9", "1:1"])
+def test_framed_art_mirror_swaps_the_sides(size):
+    width, height = size
+    kw = dict(backdrop_bytes=_two_tone(), width=width, height=height)
+    plain_l, plain_r = _sides(render_framed_art(**kw))
+    mirror_l, mirror_r = _sides(render_framed_art(**kw, mirror=True))
+
+    assert plain_l.red > 0.9 and plain_r.blue > 0.9
+    assert mirror_l.blue > 0.9 and mirror_r.red > 0.9
+
+
+def test_square_art_forwards_mirror():
+    left, right = _sides(render_square_art(backdrop_bytes=_two_tone(), mirror=True))
+    assert left.blue > 0.9 and right.red > 0.9
+
+
+def test_frame_backdrop_mirrors_the_poster_frame():
+    # The .psd POSTER layer is this function's output, so an unmirrored frame here
+    # would export a document that disagrees with the poster beside it.
+    left, right = _sides(frame_backdrop(backdrop_bytes=_two_tone(), mirror=True))
+    assert left.blue > 0.9 and right.red > 0.9
+
+
+@pytest.mark.parametrize("fit_mode", ["cover", "fit"])
+def test_mirror_composes_with_the_framing_it_does_not_replace_it(fit_mode):
+    # Off-centre framing, so a flip applied to the SOURCE instead of the framed
+    # result would land the crop window on the other side and fail this.
+    # frame_backdrop returns PNG, so the comparison is lossless and exact.
+    kw = dict(
+        backdrop_bytes=_two_tone(),
+        fit_mode=fit_mode,
+        focus_x=0.2,
+        v_pos=0.3,
+        zoom=1.6,
+    )
+    assert _sig(frame_backdrop(**kw, mirror=True)) == _sig(frame_backdrop(**kw), flop=True)
+
+
+def test_render_cl2k_mirrors_the_artwork_and_never_the_label():
+    """The whole point of flipping at the end of framing: text stays readable."""
+    kw = dict(
+        backdrop_bytes=_two_tone(),
+        kind="season",
+        title="Mirror Test",
+        season_text="Season one",
+    )
+    plain, mirrored = render_cl2k(**kw), render_cl2k(**kw, mirror=True)
+
+    left, right = _sides(mirrored)
+    assert left.blue > 0.9 and right.red > 0.9  # artwork flipped
+
+    # Below the gradient's full-black row there is no artwork left, so every lit
+    # pixel in this strip is typeset label. Identical pixels = the text did not flip.
+    top = geo.GRADIENT_FULL_BLACK_Y + 20
+    height = geo.CANVAS_H - geo.BORDER_WIDTH - 5 - top
+    assert _strip(mirrored, top, height) == _strip(plain, top, height)
+    # ...and the strip is genuinely asymmetric, or the line above proves nothing.
+    with Image(blob=plain) as img:
+        img.crop(0, top, width=img.width, height=height)
+        with img.clone() as flipped:
+            flipped.flop()
+            assert flipped.signature != img.signature
+
+
+# --------------------------------------------------------------------------
+# the flag's trip through the layers
+# --------------------------------------------------------------------------
+
+
+_ENDPOINTS = [
+    # (endpoint, the module function it must forward to, request model, takes BackgroundTasks)
+    ("preview", "render_preview", api.GenerateRequest, False),
+    ("generate", "generate_for_item", api.GenerateRequest, True),
+    ("square_generate", "generate_square_art", api.SquareArtRequest, True),
+    ("background_generate", "generate_background_art", api.BackgroundArtRequest, True),
+    ("psd_export", "psd_for_item", api.GenerateRequest, False),
+]
+
+
+@pytest.mark.parametrize("route,target,model,tasks", _ENDPOINTS, ids=[e[0] for e in _ENDPOINTS])
+def test_an_endpoint_forwards_mirror_to_its_maker(route, target, model, tasks, monkeypatch):
+    seen = {}
+    monkeypatch.setattr(api, "load_config", object)
+    # The save routes shape a result dict; the render routes return bytes.
+    # *a: render_preview takes db/config/logger positionally.
+    out = {"status": "generated"} if tasks else b"blob"
+    monkeypatch.setattr(api, target, lambda *a, **kw: (seen.update(kw), out)[1])
+    req = model(kind="movie", title="T", tmdb_id=7, mirror=True)
+    extra = {"background_tasks": BackgroundTasks()} if tasks else {}
+
+    getattr(api, route)(req, db=object(), logger=_logger(), **extra)
+
+    # Split, because these endpoints answer a raising stub with a clean 4xx —
+    # "never called" would otherwise read as "called without mirror".
+    assert seen, f"{route} never reached {target}"
+    assert seen.get("mirror") is True, f"{route} dropped mirror on the way to {target}"
+
+
+@pytest.mark.parametrize("route,model", [("square_preview", api.SquareArtRequest),
+                                         ("background_preview", api.BackgroundArtRequest)])
+def test_an_art_preview_forwards_mirror_to_the_renderer(route, model, monkeypatch):
+    seen = {}
+    target = "render_square_art" if route == "square_preview" else "render_framed_art"
+    monkeypatch.setattr(api, target, lambda **kw: (seen.update(kw), b"jpeg")[1])
+    req = model(kind="movie", title="T", tmdb_id=7, backdrop_b64="", mirror=True)
+    monkeypatch.setattr(api, "_source_art_bytes", lambda _req: b"ART")
+
+    getattr(api, route)(req, db=object(), logger=_logger())
+
+    assert seen.get("mirror") is True
+
+
+def test_the_seasons_job_carries_mirror_into_every_season(monkeypatch):
+    seen = {}
+    monkeypatch.setattr(api, "load_config", object)
+    monkeypatch.setattr(
+        api, "generate_seasons", lambda **kw: (seen.update(kw), {"status": "ok"})[1]
+    )
+    req = api.SeasonsRequest(title="T", tmdb_id=7, seasons=[1], mirror=True)
+
+    api._run_seasons_job(api._new_season_job(1, "T"), object(), _logger(), req)
+
+    assert seen.get("mirror") is True
+
+
+@pytest.mark.parametrize(
+    "maker_fn,renderer_fn",
+    [
+        ("generate_square_art", "render_square_art"),
+        ("generate_background_art", "render_framed_art"),
+    ],
+)
+def test_an_asset_maker_forwards_mirror_to_the_renderer(maker_fn, renderer_fn, monkeypatch):
+    seen = {}
+    monkeypatch.setattr(maker, "_backfill_title_year", lambda *a, **kw: ("T", 2024))
+    monkeypatch.setattr(maker, "_persist_poster", lambda *a, **kw: {"status": "ok"})
+    monkeypatch.setattr(
+        maker.renderer, renderer_fn, lambda **kw: (seen.update(kw), b"jpeg")[1]
+    )
+
+    getattr(maker, maker_fn)(
+        db=object(),
+        full_config=types.SimpleNamespace(cl2k_maker=object(), sync_gdrive=None),
+        logger=_logger(),
+        kind="movie",
+        title="T",
+        tmdb_id=7,
+        backdrop_bytes=b"ART",
+        mirror=True,
+    )
+
+    assert seen.get("mirror") is True
+
+
+def test_resolve_and_render_forwards_mirror_to_the_poster_renderer(monkeypatch):
+    seen = {}
+    monkeypatch.setattr(maker, "TMDBClient", lambda *a, **k: object())
+    monkeypatch.setattr(maker, "_resolve_default_art", lambda *a, **kw: (None, None))
+    monkeypatch.setattr(maker, "render_cl2k", lambda **kw: (seen.update(kw), b"jpeg")[1])
+
+    maker._resolve_and_render(
+        object(),
+        types.SimpleNamespace(
+            cl2k_maker=types.SimpleNamespace(
+                language="en",
+                whiten_logo=True,
+                text_logo_fallback=True,
+                text_logo_stroke=0,
+            ),
+            tmdb=None,
+        ),
+        _logger(),
+        kind="movie",
+        title="T",
+        tmdb_id=7,
+        backdrop_bytes=b"ART",
+        custom_logo_bytes=b"LOGO",
+        mirror=True,
+    )
+
+    assert seen.get("mirror") is True
+
+
+def test_generate_seasons_carries_mirror_into_each_poster(monkeypatch):
+    seen = {}
+    monkeypatch.setattr(
+        maker, "generate_for_item", lambda **kw: (seen.update(kw), {"status": "ok"})[1]
+    )
+
+    maker.generate_seasons(
+        db=object(),
+        full_config=object(),
+        logger=_logger(),
+        title="T",
+        tmdb_id=7,
+        seasons=[1],
+        mirror=True,
+    )
+
+    assert seen.get("mirror") is True
+
+
+@pytest.mark.parametrize(
+    "model",
+    [api.GenerateRequest, api.SquareArtRequest, api.BackgroundArtRequest, api.SeasonsRequest],
+)
+def test_mirror_is_off_unless_asked_for(model):
+    # Every poster ever made was rendered without this flag; a truthy default
+    # would silently flip the lot on the next re-render.
+    extra = {"seasons": [1]} if model is api.SeasonsRequest else {"kind": "movie"}
+    assert model(title="T", tmdb_id=7, **extra).mirror is False
+
+
+def test_a_mirror_request_returns_mirrored_art_over_http(monkeypatch):
+    """The whole stack in one shot: JSON on the wire -> pydantic -> endpoint ->
+    maker -> renderer -> flipped pixels. The unit tests above each cover one hop;
+    this is the one that would catch a model that quietly drops the field."""
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+
+    cfg = types.SimpleNamespace(
+        cl2k_maker=types.SimpleNamespace(
+            language="en",
+            whiten_logo=True,
+            text_logo_fallback=False,
+            text_logo_stroke=0,
+        ),
+        tmdb=None,
+    )
+    monkeypatch.setattr(api, "load_config", lambda: cfg)
+    monkeypatch.setattr(maker, "TMDBClient", lambda *a, **k: object())
+    monkeypatch.setattr(maker, "_resolve_default_art", lambda *a, **kw: (None, None))
+    monkeypatch.setattr(maker, "_fanart_logo", lambda *a, **kw: None)  # no network
+
+    app = FastAPI()
+    app.include_router(api.router)
+    app.dependency_overrides[api.get_cl2k_logger] = _logger
+    app.dependency_overrides[api.get_database] = object
+    client = TestClient(app)
+
+    body = {
+        "kind": "movie",
+        "title": "T",
+        "tmdb_id": 7,
+        "backdrop_b64": base64.b64encode(_two_tone()).decode(),
+        "place_logo": False,
+    }
+    plain = client.post("/api/cl2k-maker/preview", json=body)
+    mirrored = client.post("/api/cl2k-maker/preview", json={**body, "mirror": True})
+
+    assert (plain.status_code, mirrored.status_code) == (200, 200)
+    assert _sides(plain.content)[0].red > 0.9  # unmirrored: red on the left
+    left, right = _sides(mirrored.content)
+    assert left.blue > 0.9 and right.red > 0.9