kryten-webqueue 0.26.0__tar.gz → 0.27.0__tar.gz

{kryten_webqueue-0.26.0 → kryten_webqueue-0.27.0}/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.27.0] — 2026-06-23
+
+### Added
+
+- **Viewer feedback + "Suggest a Title".** A new **Feedback** page (login required, linked in the nav) lets viewers contribute to Channel-Z in two tabs. *Feedback* is a simple text box — submit and get an instant thank-you. *Suggest a Title* resolves what you type against our movie databases (TMDB + OMDB) and shows the candidate matches so you can confirm the right one; pick a match and it's recorded for the team. A title we can't match is still accepted (stored as **unresolved**), and if we already have it you're told right away with a link to watch it now.
+- **Admin triage queues for feedback & suggestions.** Both feeds land in the admin dashboard with the same lightweight workflow: mark entries **read/unread** and **delete** stale ones, with a per-tab unread badge and an "unread only" filter. Suggestion rows show the resolved match (title/year/source), whether we **already have it in the catalog** (with a direct link to the item), or that it's unresolved.
+
+### Changed
+
+- **Admin dashboard is now tabbed**, mirroring the user profile page. The at-a-glance sections (Overview, Jobs, Sync Logs) plus the new Feedback and Suggestions queues are organized into tabs; the Playlists / Schedules / Queue Management / Promos pages remain linked as before.
+- **Race odds column is now a fixed width.** The odds/bet-total column on the `/race` view no longer auto-sizes to each entry's bet total, so the lanes (and the track rails) line up cleanly instead of staggering as bets come in.
+- **Race view now supports 8 cars.** Added Brown and White lane colours to match the economy's expanded 8-car grid.
+
+[0.27.0]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.27.0
+
 ## [0.26.0] — 2026-06-22
 
 ### Changed

{kryten_webqueue-0.26.0 → kryten_webqueue-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kryten-webqueue
-Version: 0.26.0
+Version: 0.27.0
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT

{kryten_webqueue-0.26.0 → kryten_webqueue-0.27.0}/kryten_webqueue/app.py

@@ -33,6 +33,8 @@ from .routes.admin_queue import router as admin_queue_router
 from .routes.admin_jobs import router as admin_jobs_router
 from .routes.admin_catalog import router as admin_catalog_router
 from .routes.admin_promos import router as admin_promos_router
+from .routes.feedback import router as feedback_router
+from .routes.admin_feedback import router as admin_feedback_router
 from .routes.pages import router as pages_router
 from .ws.handler import router as ws_router
 
@@ -147,8 +149,10 @@ async def lifespan(app: FastAPI):
     await poller.start()
     app.state.poller = poller
 
-    # Rate limiter
+    # Rate limiter (OTP requests) plus a more lenient limiter shared by the
+    # feedback/suggestion endpoints (per-user, namespaced keys).
     app.state.rate_limiter = RateLimiter()
+    app.state.feedback_rate_limiter = RateLimiter(max_requests=12, window_seconds=300)
 
     # Playlist scheduler
     scheduler = PlaylistScheduler(
@@ -256,6 +260,8 @@ def create_app(config: Config) -> FastAPI:
     app.include_router(admin_jobs_router)
     app.include_router(admin_catalog_router)
     app.include_router(admin_promos_router)
+    app.include_router(feedback_router)
+    app.include_router(admin_feedback_router)
     app.include_router(ws_router)
 
     # Health check

{kryten_webqueue-0.26.0 → kryten_webqueue-0.27.0}/kryten_webqueue/catalog/db.py

@@ -12,6 +12,20 @@ def _slugify(text: str) -> str:
     return s.strip("-") or "untitled"
 
 
+def _normalize_title(title: str) -> str:
+    """Normalize a media title for equality comparison.
+
+    Lowercases, drops parenthetical/bracketed chunks and any 4-digit year, and
+    collapses remaining non-alphanumerics to single spaces. Lets a clean
+    database title ("The Matrix") match a catalog title ("The Matrix (1999)").
+    """
+    s = (title or "").lower()
+    s = re.sub(r"[\(\[][^\)\]]*[\)\]]", " ", s)
+    s = re.sub(r"\b(?:19|20)\d{2}\b", " ", s)
+    s = re.sub(r"[^a-z0-9]+", " ", s)
+    return " ".join(s.split())
+
+
 # Categories and tags whose items are hidden from the public catalog (dropdowns
 # and search results). Admins can opt to reveal them. Matched by exact name.
 HIDDEN_CATEGORY_NAMES = [
@@ -337,6 +351,36 @@ MIGRATIONS = [
     ALTER TABLE queue_shadow ADD COLUMN promo_type TEXT;
     ALTER TABLE queue_shadow ADD COLUMN lead_in_for_uid INTEGER;
     """,
+    # v12: Viewer feedback + movie-title suggestions, each with a simple
+    # admin-triage queue (status new|read). Title suggestions record the
+    # resolved match against TMDB/OMDB (NULL when unresolved) and whether we
+    # already have the title in the catalog (resolution + catalog_token).
+    """
+    CREATE TABLE IF NOT EXISTS feedback (
+        id          INTEGER PRIMARY KEY AUTOINCREMENT,
+        username    TEXT NOT NULL,
+        body        TEXT NOT NULL,
+        status      TEXT NOT NULL DEFAULT 'new',
+        created_at  TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE INDEX IF NOT EXISTS idx_feedback_status ON feedback(status, created_at);
+
+    CREATE TABLE IF NOT EXISTS title_suggestions (
+        id              INTEGER PRIMARY KEY AUTOINCREMENT,
+        username        TEXT NOT NULL,
+        query           TEXT NOT NULL,
+        resolved_title  TEXT,
+        resolved_year   TEXT,
+        resolved_source TEXT,
+        resolved_id     TEXT,
+        poster_url      TEXT,
+        resolution      TEXT NOT NULL DEFAULT 'unresolved',
+        catalog_token   TEXT,
+        status          TEXT NOT NULL DEFAULT 'new',
+        created_at      TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE INDEX IF NOT EXISTS idx_title_suggestions_status ON title_suggestions(status, created_at);
+    """,
 ]
 
 
@@ -946,6 +990,130 @@ class Database:
         )
         return int(row["c"]) if row else 0
 
+    # --- Feedback ---
+
+    async def add_feedback(self, *, username: str, body: str) -> int:
+        cursor = await self._db.execute(
+            "INSERT INTO feedback (username, body) VALUES (?, ?)",
+            [username, body],
+        )
+        await self._db.commit()
+        return cursor.lastrowid
+
+    async def list_feedback(self, *, status: str | None = None,
+                            limit: int = 100, offset: int = 0) -> list[dict]:
+        sql = "SELECT * FROM feedback"
+        params: list = []
+        if status:
+            sql += " WHERE status = ?"
+            params.append(status)
+        sql += " ORDER BY id DESC LIMIT ? OFFSET ?"
+        params.extend([limit, offset])
+        return await self._fetch_all(sql, params)
+
+    async def count_feedback(self, *, status: str | None = None) -> int:
+        sql = "SELECT COUNT(*) AS c FROM feedback"
+        params: list = []
+        if status:
+            sql += " WHERE status = ?"
+            params.append(status)
+        row = await self._fetch_one(sql, params)
+        return int(row["c"]) if row else 0
+
+    async def set_feedback_status(self, feedback_id: int, status: str) -> bool:
+        cursor = await self._db.execute(
+            "UPDATE feedback SET status = ? WHERE id = ?", [status, feedback_id]
+        )
+        await self._db.commit()
+        return (cursor.rowcount or 0) > 0
+
+    async def delete_feedback(self, feedback_id: int) -> bool:
+        cursor = await self._db.execute("DELETE FROM feedback WHERE id = ?", [feedback_id])
+        await self._db.commit()
+        return (cursor.rowcount or 0) > 0
+
+    # --- Title suggestions ---
+
+    async def add_title_suggestion(self, *, username: str, query: str,
+                                   resolved_title: str | None = None,
+                                   resolved_year: str | None = None,
+                                   resolved_source: str | None = None,
+                                   resolved_id: str | None = None,
+                                   poster_url: str | None = None,
+                                   resolution: str = "unresolved",
+                                   catalog_token: str | None = None) -> int:
+        cursor = await self._db.execute(
+            "INSERT INTO title_suggestions "
+            "(username, query, resolved_title, resolved_year, resolved_source, "
+            " resolved_id, poster_url, resolution, catalog_token) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            [username, query, resolved_title, resolved_year, resolved_source,
+             resolved_id, poster_url, resolution, catalog_token],
+        )
+        await self._db.commit()
+        return cursor.lastrowid
+
+    async def list_title_suggestions(self, *, status: str | None = None,
+                                     limit: int = 100, offset: int = 0) -> list[dict]:
+        sql = "SELECT * FROM title_suggestions"
+        params: list = []
+        if status:
+            sql += " WHERE status = ?"
+            params.append(status)
+        sql += " ORDER BY id DESC LIMIT ? OFFSET ?"
+        params.extend([limit, offset])
+        return await self._fetch_all(sql, params)
+
+    async def count_title_suggestions(self, *, status: str | None = None) -> int:
+        sql = "SELECT COUNT(*) AS c FROM title_suggestions"
+        params: list = []
+        if status:
+            sql += " WHERE status = ?"
+            params.append(status)
+        row = await self._fetch_one(sql, params)
+        return int(row["c"]) if row else 0
+
+    async def set_title_suggestion_status(self, suggestion_id: int, status: str) -> bool:
+        cursor = await self._db.execute(
+            "UPDATE title_suggestions SET status = ? WHERE id = ?", [status, suggestion_id]
+        )
+        await self._db.commit()
+        return (cursor.rowcount or 0) > 0
+
+    async def delete_title_suggestion(self, suggestion_id: int) -> bool:
+        cursor = await self._db.execute(
+            "DELETE FROM title_suggestions WHERE id = ?", [suggestion_id]
+        )
+        await self._db.commit()
+        return (cursor.rowcount or 0) > 0
+
+    async def find_catalog_by_title(self, title: str) -> dict | None:
+        """Best-effort lookup of a catalog item whose title matches ``title``.
+
+        Used to tell a user we already have a suggested movie. Runs an FTS
+        phrase match to gather candidates, then confirms with a normalized
+        (year/punctuation-stripped, case-insensitive) equality check so loose
+        token overlaps don't produce false "already have" hits. Returns
+        ``{friendly_token, title}`` of the best match, or None.
+        """
+        norm_target = _normalize_title(title)
+        if not norm_target:
+            return None
+        phrase = '"' + (title or "").replace('"', '""') + '"'
+        try:
+            rows = await self._fetch_all(
+                "SELECT c.friendly_token, c.title FROM catalog_fts fts "
+                "JOIN catalog c ON c.rowid = fts.rowid "
+                "WHERE catalog_fts MATCH ? LIMIT 25",
+                [phrase],
+            )
+        except aiosqlite.Error:
+            rows = []
+        for row in rows:
+            if _normalize_title(row["title"]) == norm_target:
+                return {"friendly_token": row["friendly_token"], "title": row["title"]}
+        return None
+
     # --- Saved playlists ---
 
     async def get_saved_playlists(self) -> list[dict]:

{kryten_webqueue-0.26.0 → kryten_webqueue-0.27.0}/kryten_webqueue/catalog/images.py

@@ -201,6 +201,109 @@ class CoverArtResolver:
                 logger.warning(f"OMDB search error for {t!r}: {e}")
         return None
 
+    # --- Title suggestion resolution ---------------------------------------
+    # These return *candidate matches* (title/year/poster/id) rather than a
+    # single poster URL, so the "Suggest a Title" UI can let the user confirm
+    # which match they meant. An empty list = unresolved (no keys, or no hits).
+
+    async def search_titles(self, query: str, *, limit: int = 8) -> list[dict]:
+        """Search TMDB + OMDB for title candidates matching ``query``.
+
+        Returns up to ``limit`` candidate dicts, most-relevant first:
+        ``{source, id, title, year, media_type, poster_url}``. TMDB (movie + TV)
+        is primary and ranked by popularity; OMDB supplements when configured.
+        An empty list means "unresolved" — no API keys, or no matches.
+        """
+        query = (query or "").strip()
+        if not query:
+            return []
+
+        candidates: list[dict] = []
+        if self._tmdb_key:
+            candidates.extend(await self._tmdb_candidates(query))
+        if self._omdb_key:
+            candidates.extend(await self._omdb_candidates(query))
+
+        # Dedupe by (lowercased title, year), keeping the most popular instance.
+        seen: dict[tuple, dict] = {}
+        for c in candidates:
+            key = (c["title"].strip().lower(), c["year"] or "")
+            prev = seen.get(key)
+            if prev is None or c["_popularity"] > prev["_popularity"]:
+                seen[key] = c
+        # Stable sort preserves provider order (TMDB before OMDB) within ties.
+        merged = sorted(seen.values(), key=lambda c: c["_popularity"], reverse=True)
+        for c in merged:
+            c.pop("_popularity", None)
+        return merged[:limit]
+
+    async def _tmdb_candidates(self, query: str) -> list[dict]:
+        movie_task = asyncio.create_task(self._tmdb_search_candidates("movie", query))
+        tv_task = asyncio.create_task(self._tmdb_search_candidates("tv", query))
+        movie_hits, tv_hits = await asyncio.gather(movie_task, tv_task)
+        return [*movie_hits, *tv_hits]
+
+    async def _tmdb_search_candidates(self, media_type: str, query: str) -> list[dict]:
+        params = {"api_key": self._tmdb_key, "query": query, "include_adult": "false"}
+        try:
+            resp = await self._client.get(
+                f"https://api.themoviedb.org/3/search/{media_type}", params=params
+            )
+            if resp.status_code != 200:
+                logger.warning(f"TMDB {media_type} suggest search returned {resp.status_code} for {query!r}")
+                return []
+            results = resp.json().get("results", [])
+        except (httpx.HTTPError, ValueError) as e:
+            logger.warning(f"TMDB {media_type} suggest search error for {query!r}: {e}")
+            return []
+        out: list[dict] = []
+        for r in results[:8]:
+            title = (r.get("title") or r.get("name") or "").strip()
+            if not title:
+                continue
+            date = r.get("release_date") or r.get("first_air_date") or ""
+            poster = r.get("poster_path")
+            out.append({
+                "source": "tmdb",
+                "id": str(r.get("id") or ""),
+                "title": title,
+                "year": (date[:4] or None),
+                "media_type": "tv" if media_type == "tv" else "movie",
+                "poster_url": (f"https://image.tmdb.org/t/p/w185{poster}" if poster else None),
+                "_popularity": float(r.get("popularity") or 0.0),
+            })
+        return out
+
+    async def _omdb_candidates(self, query: str) -> list[dict]:
+        cleaned, year = _clean_title(query)
+        params: dict = {"apikey": self._omdb_key, "s": query}
+        if year:
+            params["y"] = year
+        try:
+            resp = await self._client.get("https://www.omdbapi.com/", params=params)
+            if resp.status_code != 200:
+                return []
+            data = resp.json()
+        except (httpx.HTTPError, ValueError) as e:
+            logger.warning(f"OMDB suggest search error for {query!r}: {e}")
+            return []
+        out: list[dict] = []
+        for r in (data.get("Search") or [])[:8]:
+            title = (r.get("Title") or "").strip()
+            if not title:
+                continue
+            poster = r.get("Poster")
+            out.append({
+                "source": "omdb",
+                "id": str(r.get("imdbID") or ""),
+                "title": title,
+                "year": ((r.get("Year") or "")[:4] or None),
+                "media_type": (r.get("Type") or "movie"),
+                "poster_url": (poster if poster and poster != "N/A" else None),
+                "_popularity": 0.0,
+            })
+        return out
+
     async def _save_responsive(self, friendly_token: str, data: bytes, source: str, db) -> str:
         """Save image in multiple responsive widths."""
         token_hash = hashlib.md5(friendly_token.encode()).hexdigest()[:8]

kryten_webqueue-0.27.0/kryten_webqueue/routes/admin_feedback.py

@@ -0,0 +1,111 @@
+"""Admin triage endpoints for viewer feedback + movie-title suggestions.
+
+These back the "Feedback" and "Suggestions" tabs on the admin dashboard. Both
+queues support the same lightweight triage: list (optionally filtered by
+status), mark read/unread, and delete stale entries. Suggestion rows also carry
+the resolved match + a catalog token when we already own the title, which the UI
+turns into a direct link to the catalog item.
+"""
+
+from fastapi import APIRouter, Request, Depends, HTTPException
+from pydantic import BaseModel
+
+from ..auth.session import require_admin
+
+router = APIRouter(prefix="/admin", tags=["admin"])
+
+_VALID_STATUSES = {"new", "read"}
+
+
+class StatusUpdate(BaseModel):
+    status: str
+
+
+# --- Feedback ---------------------------------------------------------------
+
+@router.get("/feedback")
+async def list_feedback(
+    request: Request, status: str | None = None, user: dict = Depends(require_admin)
+):
+    """List feedback submissions, newest first, optionally filtered by status."""
+    db = request.app.state.db
+    if status not in _VALID_STATUSES:
+        status = None
+    items = await db.list_feedback(status=status)
+    return {
+        "items": items,
+        "counts": {
+            "new": await db.count_feedback(status="new"),
+            "total": await db.count_feedback(),
+        },
+    }
+
+
+@router.post("/feedback/{feedback_id}/status")
+async def set_feedback_status(
+    feedback_id: int, payload: StatusUpdate, request: Request,
+    user: dict = Depends(require_admin),
+):
+    """Mark a feedback entry read/unread."""
+    if payload.status not in _VALID_STATUSES:
+        raise HTTPException(status_code=400, detail="Invalid status")
+    db = request.app.state.db
+    if not await db.set_feedback_status(feedback_id, payload.status):
+        raise HTTPException(status_code=404, detail="Feedback not found")
+    return {"success": True}
+
+
+@router.delete("/feedback/{feedback_id}")
+async def delete_feedback(
+    feedback_id: int, request: Request, user: dict = Depends(require_admin)
+):
+    """Delete a stale feedback entry."""
+    db = request.app.state.db
+    if not await db.delete_feedback(feedback_id):
+        raise HTTPException(status_code=404, detail="Feedback not found")
+    return {"success": True}
+
+
+# --- Title suggestions ------------------------------------------------------
+
+@router.get("/suggestions")
+async def list_suggestions(
+    request: Request, status: str | None = None, user: dict = Depends(require_admin)
+):
+    """List movie suggestions, newest first, optionally filtered by status."""
+    db = request.app.state.db
+    if status not in _VALID_STATUSES:
+        status = None
+    items = await db.list_title_suggestions(status=status)
+    return {
+        "items": items,
+        "counts": {
+            "new": await db.count_title_suggestions(status="new"),
+            "total": await db.count_title_suggestions(),
+        },
+    }
+
+
+@router.post("/suggestions/{suggestion_id}/status")
+async def set_suggestion_status(
+    suggestion_id: int, payload: StatusUpdate, request: Request,
+    user: dict = Depends(require_admin),
+):
+    """Mark a suggestion read/unread."""
+    if payload.status not in _VALID_STATUSES:
+        raise HTTPException(status_code=400, detail="Invalid status")
+    db = request.app.state.db
+    if not await db.set_title_suggestion_status(suggestion_id, payload.status):
+        raise HTTPException(status_code=404, detail="Suggestion not found")
+    return {"success": True}
+
+
+@router.delete("/suggestions/{suggestion_id}")
+async def delete_suggestion(
+    suggestion_id: int, request: Request, user: dict = Depends(require_admin)
+):
+    """Delete a stale suggestion."""
+    db = request.app.state.db
+    if not await db.delete_title_suggestion(suggestion_id):
+        raise HTTPException(status_code=404, detail="Suggestion not found")
+    return {"success": True}

kryten_webqueue-0.27.0/kryten_webqueue/routes/feedback.py

@@ -0,0 +1,197 @@
+"""User-facing feedback + movie-title suggestion endpoints.
+
+Backs the public "Feedback" page (templates/feedback/index.html). Both features
+require a logged-in user so submissions carry a canonical username for
+attribution and light spam control.
+
+Movie suggestions are resolved against TMDB/OMDB (reusing the cover-art
+resolver). The flow is two-step: ``/suggest/resolve`` returns candidate matches
+the user confirms, then ``/suggest/submit`` records the chosen match. A title we
+can't match is still accepted and stored as ``unresolved``; a title we already
+have is stored as ``already_have`` and the user is told it's available.
+"""
+
+from fastapi import APIRouter, Request, Depends, HTTPException
+from pydantic import BaseModel
+
+from ..auth.session import get_current_user
+
+router = APIRouter(tags=["feedback"])
+
+FEEDBACK_MAX_LEN = 2000
+SUGGEST_QUERY_MAX_LEN = 200
+_THANKS = "Thanks for helping make Channel-Z better!"
+_VALID_SOURCES = {"tmdb", "omdb"}
+
+
+class FeedbackSubmit(BaseModel):
+    body: str
+
+
+class SuggestResolve(BaseModel):
+    query: str
+
+
+class SuggestChoice(BaseModel):
+    source: str | None = None
+    id: str | None = None
+    title: str | None = None
+    year: str | None = None
+    media_type: str | None = None
+    poster_url: str | None = None
+
+
+class SuggestSubmit(BaseModel):
+    query: str
+    choice: SuggestChoice | None = None
+    unresolved: bool = False
+
+
+def _rate_limit(request: Request, key: str, message: str) -> None:
+    """Raise 429 when the per-user sliding window for ``key`` is exhausted."""
+    limiter = request.app.state.feedback_rate_limiter
+    if not limiter.is_allowed(key):
+        raise HTTPException(status_code=429, detail=message)
+
+
+@router.post("/feedback/submit")
+async def submit_feedback(
+    payload: FeedbackSubmit, request: Request, user: dict = Depends(get_current_user)
+):
+    """Record a free-text feedback submission and thank the user."""
+    body = (payload.body or "").strip()
+    if not body:
+        raise HTTPException(status_code=400, detail="Please enter some feedback before submitting.")
+    if len(body) > FEEDBACK_MAX_LEN:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Feedback is too long (max {FEEDBACK_MAX_LEN} characters).",
+        )
+    _rate_limit(
+        request, f"feedback:{user['username']}",
+        "You're sending feedback very quickly. Please wait a moment and try again.",
+    )
+    db = request.app.state.db
+    await db.add_feedback(username=user["username"], body=body)
+    return {
+        "success": True,
+        "message": (
+            f"Thanks, {user['username']}! {_THANKS} Your feedback has been "
+            "sent to the Channel-Z team."
+        ),
+    }
+
+
+@router.post("/feedback/suggest/resolve")
+async def resolve_suggestion(
+    payload: SuggestResolve, request: Request, user: dict = Depends(get_current_user)
+):
+    """Search the movie databases for candidate matches to a title query.
+
+    Each candidate is annotated with ``catalog_token``/``catalog_title`` when we
+    already have that title, so the UI can flag it before the user submits.
+    """
+    query = (payload.query or "").strip()
+    if not query:
+        raise HTTPException(status_code=400, detail="Enter a movie or show title to search.")
+    if len(query) > SUGGEST_QUERY_MAX_LEN:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Title is too long (max {SUGGEST_QUERY_MAX_LEN} characters).",
+        )
+    _rate_limit(
+        request, f"suggest-resolve:{user['username']}",
+        "Too many searches in a short time. Please wait a moment and try again.",
+    )
+    cover_art = request.app.state.cover_art
+    db = request.app.state.db
+    candidates = await cover_art.search_titles(query)
+    for c in candidates:
+        match = await db.find_catalog_by_title(c.get("title") or "")
+        if match:
+            c["catalog_token"] = match["friendly_token"]
+            c["catalog_title"] = match["title"]
+    return {"query": query, "candidates": candidates}
+
+
+@router.post("/feedback/suggest/submit")
+async def submit_suggestion(
+    payload: SuggestSubmit, request: Request, user: dict = Depends(get_current_user)
+):
+    """Record a movie suggestion, resolving 'already have' server-side.
+
+    A missing/empty choice (or ``unresolved=true``) is stored as an unresolved
+    suggestion — still surfaced to admins. The chosen candidate fields are
+    user-supplied and so are sanitized and length-capped; the catalog match is
+    always re-derived from the DB rather than trusted from the client.
+    """
+    query = (payload.query or "").strip()
+    if not query:
+        raise HTTPException(status_code=400, detail="Enter a movie or show title.")
+    if len(query) > SUGGEST_QUERY_MAX_LEN:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Title is too long (max {SUGGEST_QUERY_MAX_LEN} characters).",
+        )
+    _rate_limit(
+        request, f"suggest:{user['username']}",
+        "You're sending suggestions very quickly. Please wait a moment and try again.",
+    )
+    db = request.app.state.db
+    username = user["username"]
+    choice = payload.choice
+
+    # Unresolved path: no match chosen (or explicitly flagged). Still recorded.
+    if payload.unresolved or not choice or not (choice.title or "").strip():
+        await db.add_title_suggestion(username=username, query=query, resolution="unresolved")
+        return {
+            "success": True,
+            "resolution": "unresolved",
+            "message": (
+                f"Thanks, {username}! {_THANKS} We couldn't match that to a "
+                "database entry, but we've passed your suggestion to the "
+                "Channel-Z team."
+            ),
+        }
+
+    # Sanitize the client-provided candidate before storing.
+    title = (choice.title or "").strip()[:300]
+    year = ((choice.year or "").strip()[:8]) or None
+    source = ((choice.source or "").strip().lower()[:16]) or None
+    if source not in _VALID_SOURCES:
+        source = None
+    resolved_id = ((choice.id or "").strip()[:64]) or None
+    poster = ((choice.poster_url or "").strip()[:500]) or None
+
+    # Authoritatively re-check whether we already have this title.
+    match = await db.find_catalog_by_title(title)
+    if match:
+        await db.add_title_suggestion(
+            username=username, query=query, resolved_title=title, resolved_year=year,
+            resolved_source=source, resolved_id=resolved_id, poster_url=poster,
+            resolution="already_have", catalog_token=match["friendly_token"],
+        )
+        return {
+            "success": True,
+            "resolution": "already_have",
+            "catalog_token": match["friendly_token"],
+            "catalog_title": match["title"],
+            "message": (
+                f"Good news, {username} — we already have \u201c{match['title']}\u201d "
+                "in the catalog! Thanks for the suggestion."
+            ),
+        }
+
+    await db.add_title_suggestion(
+        username=username, query=query, resolved_title=title, resolved_year=year,
+        resolved_source=source, resolved_id=resolved_id, poster_url=poster,
+        resolution="resolved",
+    )
+    return {
+        "success": True,
+        "resolution": "resolved",
+        "message": (
+            f"Thanks, {username}! {_THANKS} We've added \u201c{title}\u201d to the "
+            "suggestions list for the Channel-Z team to review."
+        ),
+    }