Sync from kink_cli (Docker Space)

.gitignore

@@ -13,6 +13,7 @@ data/store.db-shm
 data/store_slim.db
 data/store_slim.db-wal
 data/store_slim.db-shm
+data/cached_assets*.tar
 data/recsys/
 
 # Python

api.py

@@ -11,12 +11,13 @@ from typing import Any
 
 from fastapi import FastAPI, Header, HTTPException, Query, Request
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.responses import FileResponse, HTMLResponse, RedirectResponse
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
 from sse_starlette.sse import EventSourceResponse
 
 from backend import Backend, VALID_RATINGS
-from backend.hf_bootstrap import ensure_store_db
+from backend.hf_bootstrap import ensure_media_cache, ensure_store_db
+from backend.media_remote import remote_media_health_payload, remote_media_url
 
 _app_dir = Path(__file__).resolve().parent
 _data_dir = _app_dir / "data"
@@ -54,18 +55,18 @@ def _require_frontend_build() -> None:
 def _hf_space_published_image() -> bool:
     """True in the Hugging Face Space Docker image (``Dockerfile`` sets ``KINK_HF_SPACE_IMAGE=1``).
 
-    Space repository variables can override ``KINK_MEDIA_STRICT`` / ``KINK_MEDIA_FALLBACK_PATH``; the
-    published image still serves bundled JPEG fallbacks for missing catalog tiles so Discover cards
-    are never blank JSON 404s.
+    Seed deployments can serve bundled JPEG fallbacks for missing catalog tiles. Full-catalog
+    deployments must expose missing bytes as 404s so the UI can use a neutral placeholder instead of
+    repeating an unrelated demo image.
     """
     return _env_truthy("KINK_HF_SPACE_IMAGE")
 
 
 def _media_strict_missing() -> bool:
     """If true, missing ``/media/...`` bytes return 404 instead of a same-origin placeholder image."""
-    if _hf_space_published_image():
-        return False
-    return _env_truthy("KINK_MEDIA_STRICT")
+    if _env_is_set("KINK_MEDIA_STRICT"):
+        return _env_truthy("KINK_MEDIA_STRICT")
+    return _env_truthy("KINK_HF_REQUIRE_FULL_CATALOG")
 
 
 def _media_fallback_path() -> Path | None:
@@ -85,13 +86,15 @@ def _media_fallback_path() -> Path | None:
 
 def _media_health_payload() -> dict[str, Any]:
     fb = _media_fallback_path()
-    return {
+    payload = {
         "hf_space_image": _hf_space_published_image(),
         "strict_env": _env_truthy("KINK_MEDIA_STRICT"),
         "strict_missing_assets": _media_strict_missing(),
         "fallback_ready": fb is not None,
         "fallback_path": str(fb) if fb is not None else None,
     }
+    payload.update(remote_media_health_payload())
+    return payload
 
 _backend_impl: Backend | None = None
 _backend_lock = threading.Lock()
@@ -101,6 +104,10 @@ def _env_truthy(name: str) -> bool:
     return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
 
 
+def _env_is_set(name: str) -> bool:
+    return os.environ.get(name, "").strip() != ""
+
+
 def _store_path_is_ephemeral(path: Path) -> bool:
     resolved = path.resolve()
     prefixes = ("/tmp", "/var/tmp", "/dev/shm")
@@ -134,6 +141,7 @@ def _get_backend() -> Backend:
     with _backend_lock:
         if _backend_impl is not None:
             return _backend_impl
+        ensure_media_cache(MEDIA_ROOT)
         path = ensure_store_db(_default_store)
         _warn_or_fail_ephemeral_store(path)
         b = Backend(path)
@@ -399,13 +407,20 @@ def favicon() -> FileResponse:
     raise HTTPException(status_code=404, detail="Not found")
 
 
-@app.get("/media/{bucket}/{filename:path}")
-def media(bucket: str, filename: str) -> FileResponse:
+@app.get("/media/{bucket}/{filename:path}", response_model=None)
+def media(bucket: str, filename: str) -> Any:
     target = (MEDIA_ROOT / bucket / filename).resolve()
     if MEDIA_ROOT.resolve() not in target.parents:
         raise HTTPException(status_code=404, detail="Unknown asset")
     if target.is_file():
         return FileResponse(target, headers={"Cache-Control": _MEDIA_CACHE})
+    remote_url = remote_media_url(f"{bucket}/{filename}")
+    if remote_url:
+        return RedirectResponse(
+            remote_url,
+            status_code=307,
+            headers={"Cache-Control": "private, max-age=300"},
+        )
     if not _media_strict_missing():
         fb = _media_fallback_path()
         if fb is not None:

backend/hf_bootstrap.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 import os
 import shutil
+import tarfile
 from pathlib import Path
 
 # Default dataset when KINK_HF_REQUIRE_FULL_CATALOG=1 but Space UI cleared KINK_HF_DATASET_REPO (empty overrides Dockerfile).
@@ -97,6 +98,50 @@ def _download_store_from_http(url: str, dest: Path) -> None:
         raise
 
 
+def ensure_media_cache(target_root: Path) -> Path:
+    """Hydrate ``data/cached_assets`` from a Hub dataset archive when configured."""
+    archive_name = os.environ.get("KINK_HF_MEDIA_ARCHIVE", "").strip()
+    if not archive_name:
+        return target_root
+
+    target_root = target_root.resolve()
+    marker = target_root / f".{archive_name.replace('/', '_')}.ready"
+    if marker.is_file():
+        return target_root
+
+    repo = (
+        os.environ.get("KINK_HF_MEDIA_DATASET_REPO", "").strip()
+        or os.environ.get("KINK_HF_DATASET_REPO", "").strip()
+        or DEFAULT_KINK_HF_DATASET_REPO
+    )
+    revision = os.environ.get("KINK_HF_MEDIA_DATASET_REVISION", "").strip() or None
+    token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+    if not repo:
+        raise RuntimeError("KINK_HF_MEDIA_ARCHIVE is set but no Hub dataset repo is configured")
+
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError as exc:
+        raise ImportError(
+            "huggingface_hub is required when KINK_HF_MEDIA_ARCHIVE is set. "
+            "Install with: pip install huggingface_hub"
+        ) from exc
+
+    target_root.mkdir(parents=True, exist_ok=True)
+    downloaded = hf_hub_download(
+        repo_id=repo,
+        repo_type="dataset",
+        filename=archive_name,
+        revision=revision,
+        token=token,
+        local_dir=str(target_root.parent),
+    )
+    with tarfile.open(downloaded, "r:*") as tar:
+        tar.extractall(target_root, filter="data")
+    marker.write_text("ok\n", encoding="utf-8")
+    return target_root
+
+
 def ensure_store_db(target: Path) -> Path:
     """Return ``target`` if it exists; otherwise download from Hub, or copy bundled seed when allowed."""
     target = target.resolve()

backend/media_remote.py

@@ -0,0 +1,141 @@
+"""Remote media URL resolution for catalog assets."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+from urllib.parse import quote
+
+
+@dataclass(frozen=True)
+class RemoteMediaConfig:
+    public_base_url: str
+    s3_bucket: str
+    s3_prefix: str
+    s3_endpoint_url: str
+    s3_region: str
+    s3_access_key_id: str
+    s3_secret_access_key: str
+    s3_expires_s: int
+
+    @property
+    def mode(self) -> str:
+        if self.public_base_url:
+            return "public_base"
+        if self.s3_bucket and self.s3_endpoint_url and self.s3_access_key_id and self.s3_secret_access_key:
+            return "s3_presign"
+        return "none"
+
+
+def _env(name: str) -> str:
+    return (os.environ.get(name) or "").strip()
+
+
+def _env_int(name: str, default: int, *, low: int, high: int) -> int:
+    raw = _env(name)
+    if not raw:
+        return default
+    value = int(raw)
+    return min(max(value, low), high)
+
+
+def _clean_prefix(prefix: str) -> str:
+    return prefix.strip().strip("/")
+
+
+def _object_key(prefix: str, relative_path: str) -> str:
+    rel = relative_path.strip().lstrip("/")
+    pref = _clean_prefix(prefix)
+    return f"{pref}/{rel}" if pref else rel
+
+
+def _quote_path(path: str) -> str:
+    return "/".join(quote(part, safe="") for part in path.split("/"))
+
+
+def remote_media_config_from_env() -> RemoteMediaConfig:
+    public_base_url = _env("KINK_MEDIA_PUBLIC_BASE_URL").rstrip("/")
+
+    s3_prefix = _env("KINK_MEDIA_S3_PREFIX") or _env("KINK_B2_MEDIA_PREFIX")
+    explicit_s3 = bool(_env("KINK_MEDIA_S3_BUCKET"))
+    explicit_b2 = bool(_env("KINK_B2_MEDIA_BUCKET") or _env("KINK_B2_MEDIA_PREFIX"))
+
+    s3_bucket = _env("KINK_MEDIA_S3_BUCKET")
+    if not s3_bucket and explicit_b2:
+        s3_bucket = _env("KINK_B2_MEDIA_BUCKET") or _env("B2_BUCKET") or _env("KINK_B2_BUCKET")
+
+    s3_region = _env("KINK_MEDIA_S3_REGION")
+    if not s3_region and (explicit_b2 or s3_bucket):
+        s3_region = _env("KINK_B2_MEDIA_REGION") or _env("B2_REGION") or _env("KINK_B2_REGION")
+
+    s3_endpoint_url = _env("KINK_MEDIA_S3_ENDPOINT_URL")
+    if not s3_endpoint_url and explicit_b2 and s3_region:
+        s3_endpoint_url = f"https://s3.{s3_region}.backblazeb2.com"
+
+    s3_access_key_id = _env("KINK_MEDIA_S3_ACCESS_KEY_ID")
+    s3_secret_access_key = _env("KINK_MEDIA_S3_SECRET_ACCESS_KEY")
+    if explicit_b2:
+        s3_access_key_id = s3_access_key_id or _env("B2_KEY_ID") or _env("KINK_B2_KEY_ID")
+        s3_secret_access_key = (
+            s3_secret_access_key or _env("B2_APPLICATION_KEY") or _env("KINK_B2_APPLICATION_KEY")
+        )
+
+    if explicit_s3 and not s3_endpoint_url:
+        s3_endpoint_url = f"https://s3.{s3_region}.amazonaws.com" if s3_region else ""
+
+    return RemoteMediaConfig(
+        public_base_url=public_base_url,
+        s3_bucket=s3_bucket,
+        s3_prefix=s3_prefix,
+        s3_endpoint_url=s3_endpoint_url.rstrip("/"),
+        s3_region=s3_region,
+        s3_access_key_id=s3_access_key_id,
+        s3_secret_access_key=s3_secret_access_key,
+        s3_expires_s=_env_int("KINK_MEDIA_S3_EXPIRES_S", 3600, low=60, high=604800),
+    )
+
+
+@lru_cache(maxsize=8)
+def _s3_client(endpoint_url: str, region: str, access_key_id: str, secret_access_key: str):
+    import boto3
+
+    return boto3.client(
+        "s3",
+        endpoint_url=endpoint_url,
+        aws_access_key_id=access_key_id,
+        aws_secret_access_key=secret_access_key,
+        region_name=region or None,
+    )
+
+
+def remote_media_url(relative_path: str) -> str | None:
+    cfg = remote_media_config_from_env()
+    if cfg.mode == "public_base":
+        key = _quote_path(_object_key("", relative_path))
+        return f"{cfg.public_base_url}/{key}"
+    if cfg.mode == "s3_presign":
+        key = _object_key(cfg.s3_prefix, relative_path)
+        client = _s3_client(
+            cfg.s3_endpoint_url,
+            cfg.s3_region,
+            cfg.s3_access_key_id,
+            cfg.s3_secret_access_key,
+        )
+        return str(
+            client.generate_presigned_url(
+                "get_object",
+                Params={"Bucket": cfg.s3_bucket, "Key": key},
+                ExpiresIn=cfg.s3_expires_s,
+            )
+        )
+    return None
+
+
+def remote_media_health_payload() -> dict[str, object]:
+    cfg = remote_media_config_from_env()
+    return {
+        "remote_mode": cfg.mode,
+        "remote_configured": cfg.mode != "none",
+        "remote_prefix": _clean_prefix(cfg.s3_prefix),
+        "remote_expires_s": cfg.s3_expires_s if cfg.mode == "s3_presign" else None,
+    }

frontend/components.js

@@ -3,7 +3,7 @@ import { html, UI_REACTIONS, DIRECTION_PILLS } from "./constants.js";
 import { kinkCategoryLabel } from "./ui-labels.js";
 
 /** One photo at a time; tap left/right edges to change. */
-function KinkMediaScroll({ assets, imageRevealed, kinkName, onReveal, resetKey }) {
+function KinkMediaScroll({ assets, imageRevealed, kinkName, onReveal, onAssetError, resetKey }) {
   const [idx, setIdx] = useState(0);
   const list = (Array.isArray(assets) ? assets : []).filter((a) => a && typeof a.asset_url === "string" && a.asset_url);
   const n = list.length;
@@ -59,6 +59,7 @@ function KinkMediaScroll({ assets, imageRevealed, kinkName, onReveal, resetKey }
             src=${cur.asset_url}
             alt=""
             draggable=${false}
+            onError=${() => onAssetError?.(cur.asset_url)}
           />
         </div>
         ${n > 1
@@ -161,7 +162,21 @@ export function KinkCard({
   onToggleInfo,
 }) {
   const assets = (kink.assets || []).filter((a) => a && typeof a.asset_url === "string" && a.asset_url);
-  const hasImage = photosEnabled && assets.length > 0;
+  const [failedAssetUrls, setFailedAssetUrls] = useState(() => new Set());
+  useEffect(() => {
+    setFailedAssetUrls(new Set());
+  }, [kink.id]);
+  const markAssetFailed = useCallback((assetUrl) => {
+    if (!assetUrl) return;
+    setFailedAssetUrls((prev) => {
+      if (prev.has(assetUrl)) return prev;
+      const next = new Set(prev);
+      next.add(assetUrl);
+      return next;
+    });
+  }, []);
+  const visibleAssets = assets.filter((a) => !failedAssetUrls.has(a.asset_url));
+  const hasImage = photosEnabled && visibleAssets.length > 0;
   const category = kinkCategoryLabel(kink);
   const def = definitionText(kink);
   const safety = html`
@@ -206,10 +221,11 @@ export function KinkCard({
           <div className=${`tinder-card__media ${imageRevealed ? "revealed" : ""}`}>
             <${KinkMediaScroll}
               resetKey=${kink.id}
-              assets=${assets}
+              assets=${visibleAssets}
               imageRevealed=${imageRevealed}
               kinkName=${kink.name}
               onReveal=${onRevealImage}
+              onAssetError=${markAssetFailed}
             />
           </div>
         `
@@ -269,10 +285,15 @@ export function KinkCard({
         ? imageRevealed
           ? html`
               <div className="card-image-scroll">
-                ${assets.map(
+                ${visibleAssets.map(
                   (asset, i) => html`
                     <div key=${asset.asset_url || `c-${i}`} className="card-image-slide">
-                      <img loading=${i < 2 ? "eager" : "lazy"} src=${asset.asset_url} alt="" />
+                      <img
+                        loading=${i < 2 ? "eager" : "lazy"}
+                        src=${asset.asset_url}
+                        alt=""
+                        onError=${() => markAssetFailed(asset.asset_url)}
+                      />
                     </div>
                   `,
                 )}
@@ -280,7 +301,13 @@ export function KinkCard({
             `
           : html`
               <div className="card-image-area card-image-area--preview" onClick=${onRevealImage}>
-                <img className="card-image-blur" src=${assets[0].asset_url} alt="" draggable=${false} />
+                <img
+                  className="card-image-blur"
+                  src=${visibleAssets[0].asset_url}
+                  alt=""
+                  draggable=${false}
+                  onError=${() => markAssetFailed(visibleAssets[0].asset_url)}
+                />
                 <span className="card-image-cta">Show</span>
               </div>
             `

frontend/dist/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Play List</title>
     <link rel="icon" href="/favicon.ico" type="image/jpeg" />
-    <script type="module" crossorigin src="/frontend/assets/index-CselhGyO.js"></script>
+    <script type="module" crossorigin src="/frontend/assets/index-DoKOnBon.js"></script>
     <link rel="stylesheet" crossorigin href="/frontend/assets/index-B1No5j6D.css">
   </head>
   <body>

frontend/my-plays.js

@@ -262,11 +262,14 @@ function CollapsibleSection(props) {
 function ImageGrid({ assets }) {
   const [revealed, setRevealed] = useState(false);
   const [idx, setIdx] = useState(0);
-  const n = assets.length;
-  const cur = assets[idx];
+  const [failedAssetUrls, setFailedAssetUrls] = useState(() => new Set());
+  const visibleAssets = assets.filter((asset) => !failedAssetUrls.has(asset.asset_url));
+  const n = visibleAssets.length;
+  const cur = visibleAssets[idx];
 
   useEffect(() => {
     setIdx(0);
+    setFailedAssetUrls(new Set());
   }, [assets?.length, assets?.[0]?.asset_url]);
 
   const go = useCallback((delta, e) => {
@@ -275,6 +278,22 @@ function ImageGrid({ assets }) {
     setIdx((i) => (i + delta + n) % n);
   }, [n]);
 
+  const markAssetFailed = useCallback((assetUrl) => {
+    if (!assetUrl) return;
+    setFailedAssetUrls((prev) => {
+      if (prev.has(assetUrl)) return prev;
+      const next = new Set(prev);
+      next.add(assetUrl);
+      return next;
+    });
+  }, []);
+
+  useEffect(() => {
+    setIdx((i) => (n ? Math.min(Math.max(0, i), n - 1) : 0));
+  }, [n]);
+
+  if (!n) return null;
+
   return html`
     <div className="play-assets">
       ${!revealed
@@ -294,12 +313,19 @@ function ImageGrid({ assets }) {
                   `
                 : null}
               <div className="play-assets-slide">
-                <img loading="eager" decoding="async" src=${cur.asset_url} alt="" draggable=${false} />
+                <img
+                  loading="eager"
+                  decoding="async"
+                  src=${cur.asset_url}
+                  alt=""
+                  draggable=${false}
+                  onError=${() => markAssetFailed(cur.asset_url)}
+                />
               </div>
               ${n > 1
                 ? html`
                     <div className="play-assets-dots" aria-hidden="true">
-                      ${assets.map((_, i) => html`<span key=${`pd-${i}`} className=${i === idx ? "on" : ""} />`)}
+                      ${visibleAssets.map((_, i) => html`<span key=${`pd-${i}`} className=${i === idx ? "on" : ""} />`)}
                     </div>
                     <div className="play-assets-badge">${idx + 1} / ${n}</div>
                   `

scripts/sync_hf_space_b2_media.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Upload cached catalog media to B2 and point the Hugging Face Space at it.
+
+The app keeps stable same-origin ``/media/...`` URLs in the catalog. In production, when a
+file is not present in the Space container, ``api.py`` can redirect that URL to a private
+S3/B2 pre-signed URL. This script uploads ``data/cached_assets`` under one B2 prefix and
+sets the Space variables/secrets required for that redirect path.
+"""
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import mimetypes
+import os
+import sys
+import tomllib
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from backend.b2_toml import load_b2_section, resolve_b2_config_path
+from backend.repo_dotenv import load_repo_dotenv
+
+DEFAULT_SECRETS = Path(
+    os.environ.get("KINK_PARSER_SECRETS_TOML", Path.home() / "PycharmProjects/parser/secrets.toml")
+)
+
+
+def _load_hf_token(path: Path) -> str:
+    token = (os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN") or "").strip()
+    if token:
+        return token
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    token = str((data.get("huggingface") or {}).get("token") or "").strip()
+    if not token:
+        raise SystemExit(f"Missing [huggingface].token in {path}")
+    return token
+
+
+def _iter_media_files(root: Path) -> list[Path]:
+    files = [p for p in root.rglob("*") if p.is_file()]
+    files.sort(key=lambda p: p.relative_to(root).as_posix())
+    return files
+
+
+def _object_key(prefix: str, rel: str) -> str:
+    clean = prefix.strip().strip("/")
+    return f"{clean}/{rel}" if clean else rel
+
+
+def _content_type(path: Path) -> str:
+    return mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+
+
+def main() -> int:
+    load_repo_dotenv()
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--secrets-toml", type=Path, default=DEFAULT_SECRETS)
+    ap.add_argument("--b2-secrets-toml", type=Path, default=None)
+    ap.add_argument("--local-root", type=Path, default=ROOT / "data" / "cached_assets")
+    ap.add_argument("--bucket", default=None, help="Bucket override; defaults to [b2].bucket_name")
+    ap.add_argument("--prefix", default="kink/media", help="Object prefix for media files")
+    ap.add_argument("--workers", type=int, default=16)
+    ap.add_argument("--limit", type=int, default=0, help="Upload at most N files (test/dev)")
+    ap.add_argument("--skip-existing", action="store_true", help="HEAD each object and skip existing keys")
+    ap.add_argument("--skip-upload", action="store_true", help="Only push HF Space variables/secrets")
+    ap.add_argument("--no-space-update", action="store_true", help="Upload only; do not update HF Space")
+    ap.add_argument("--progress-every", type=int, default=1000)
+    args = ap.parse_args()
+
+    local_root = args.local_root.resolve()
+    if not local_root.is_dir():
+        print(f"sync_hf_space_b2_media: media root not found: {local_root}", file=sys.stderr)
+        return 1
+    if not args.secrets_toml.is_file():
+        print(f"sync_hf_space_b2_media: secrets not found: {args.secrets_toml}", file=sys.stderr)
+        return 1
+    b2_path = resolve_b2_config_path(cli_b2=args.b2_secrets_toml, cli_fallback=args.secrets_toml)
+    if not b2_path.is_file():
+        print(f"sync_hf_space_b2_media: B2 secrets TOML not found: {b2_path}", file=sys.stderr)
+        return 1
+    try:
+        b2 = load_b2_section(b2_path)
+    except SystemExit as exc:
+        print(f"sync_hf_space_b2_media: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        import boto3
+        from boto3.s3.transfer import TransferConfig
+    except ImportError:
+        print("sync_hf_space_b2_media: boto3 is required", file=sys.stderr)
+        return 1
+
+    region = b2["region"]
+    bucket = (args.bucket or os.environ.get("KINK_B2_MEDIA_BUCKET") or b2["bucket_name"]).strip()
+    endpoint = f"https://s3.{region}.backblazeb2.com"
+    client = boto3.client(
+        "s3",
+        endpoint_url=endpoint,
+        aws_access_key_id=b2["key_id"],
+        aws_secret_access_key=b2["application_key"],
+        region_name=region,
+    )
+
+    files = _iter_media_files(local_root)
+    if args.limit:
+        files = files[: args.limit]
+    total_bytes = sum(p.stat().st_size for p in files)
+    print(
+        f"sync_hf_space_b2_media: {len(files)} files, {total_bytes / 1e9:.2f} GB → s3://{bucket}/{args.prefix.strip().strip('/')}/",
+        file=sys.stderr,
+    )
+
+    if not args.skip_upload:
+        transfer_cfg = TransferConfig(use_threads=False)
+
+        def upload_one(path: Path) -> tuple[str, str]:
+            rel = path.relative_to(local_root).as_posix()
+            key = _object_key(args.prefix, rel)
+            if args.skip_existing:
+                try:
+                    client.head_object(Bucket=bucket, Key=key)
+                    return ("skipped", rel)
+                except Exception:
+                    pass
+            client.upload_file(
+                str(path),
+                bucket,
+                key,
+                ExtraArgs={
+                    "ContentType": _content_type(path),
+                    "CacheControl": "public, max-age=31536000, immutable",
+                },
+                Config=transfer_cfg,
+            )
+            return ("uploaded", rel)
+
+        uploaded = 0
+        skipped = 0
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, args.workers)) as pool:
+            futures = [pool.submit(upload_one, path) for path in files]
+            for i, fut in enumerate(concurrent.futures.as_completed(futures), start=1):
+                status, rel = fut.result()
+                if status == "skipped":
+                    skipped += 1
+                else:
+                    uploaded += 1
+                if args.progress_every and (i % args.progress_every == 0 or i == len(futures)):
+                    print(
+                        f"sync_hf_space_b2_media: {i}/{len(futures)} done ({uploaded} uploaded, {skipped} skipped), last={rel}",
+                        file=sys.stderr,
+                    )
+
+    if args.no_space_update:
+        return 0
+
+    repo_id = (os.environ.get("HF_SPACE_REPO") or "").strip()
+    if not repo_id:
+        print("sync_hf_space_b2_media: set HF_SPACE_REPO=owner/slug or pass --no-space-update", file=sys.stderr)
+        return 1
+    try:
+        hf_token = _load_hf_token(args.secrets_toml)
+    except SystemExit as exc:
+        print(f"sync_hf_space_b2_media: {exc}", file=sys.stderr)
+        return 1
+
+    from huggingface_hub import HfApi
+
+    api = HfApi(token=hf_token)
+
+    def sec(name: str, value: str, desc: str) -> None:
+        api.add_space_secret(repo_id, name, value, description=desc, token=hf_token)
+
+    sec("B2_KEY_ID", b2["key_id"], "Backblaze B2 application key id (S3)")
+    sec("B2_APPLICATION_KEY", b2["application_key"], "Backblaze B2 application key secret")
+    sec("B2_BUCKET", bucket, "Backblaze B2 bucket for catalog/media objects")
+    sec("B2_REGION", region, "Backblaze B2 region")
+    api.add_space_variable(
+        repo_id,
+        "KINK_B2_MEDIA_PREFIX",
+        args.prefix.strip().strip("/"),
+        description="B2/S3 prefix for catalog media files",
+        token=hf_token,
+    )
+    api.add_space_variable(
+        repo_id,
+        "KINK_MEDIA_S3_EXPIRES_S",
+        "21600",
+        description="Signed media URL lifetime in seconds",
+        token=hf_token,
+    )
+    api.add_space_variable(
+        repo_id,
+        "KINK_MEDIA_STRICT",
+        "1",
+        description="Do not serve demo placeholders for missing catalog media",
+        token=hf_token,
+    )
+    print("sync_hf_space_b2_media: Space media secrets/variables updated.", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/verify_hf_stack.py

@@ -291,10 +291,16 @@ def _assert_catalog_https_image_fetchable(root: str) -> None:
         print("verify_hf_stack: bundled fetlife_fetishes placeholder image ok", file=sys.stderr)
 
     health = _get(f"{base}/health")
-    n_assets = int((health.get("stats") or {}).get("assets") or 0)
+    stats = health.get("stats") or {}
+    media = health.get("media") or {}
+    n_assets = int(stats.get("assets") or 0)
     if n_assets < 1:
         print("verify_hf_stack: skipping live catalog row probe (stats.assets is 0)", file=sys.stderr)
         return
+    require_catalog_image = (
+        os.environ.get("HF_VERIFY_REQUIRE_CATALOG_IMAGE", "").strip().lower() in ("1", "true", "yes", "on")
+        or (bool(media.get("strict_missing_assets")) and int(stats.get("kinks") or 0) >= 1000)
+    )
 
     lst = _get(f"{base}/kinks?limit=500")
     items = lst.get("items") or []
@@ -316,6 +322,10 @@ def _assert_catalog_https_image_fetchable(root: str) -> None:
         assert_catalog_image_url_works(url, timeout_s=t_img)
     except HTTPError as e:
         if e.code == 404:
+            if require_catalog_image:
+                raise RuntimeError(
+                    f"catalog image GET 404 for {kid!r}; full-catalog media is required but bytes are missing"
+                ) from e
             print(
                 f"verify_hf_stack: catalog image GET 404 for {kid!r} (missing on-disk bytes for that path; "
                 "bundled seed images above still prove /media is wired).",

tests/test_api_media_fallback.py

@@ -55,6 +55,30 @@ def test_missing_media_strict_returns_404(tmp_path, monkeypatch) -> None:
     assert r.status_code == 404
 
 
+def test_missing_media_redirects_to_public_media_base(tmp_path, monkeypatch) -> None:
+    assert _SEED.is_file(), f"Missing seed DB: {_SEED}"
+    dest = tmp_path / "remote_media_store.db"
+    shutil.copyfile(_SEED, dest)
+    monkeypatch.setenv("KINK_STORE_PATH", str(dest))
+    monkeypatch.setenv("KINK_SKIP_HEAVY_WARM", "1")
+    monkeypatch.setenv("KINK_HF_REQUIRE_FULL_CATALOG", "1")
+    monkeypatch.setenv("KINK_HF_STALE_MAX_BYTES", "0")
+    monkeypatch.setenv("KINK_MEDIA_PUBLIC_BASE_URL", "https://cdn.example.test/kink-media")
+    monkeypatch.delenv("KINK_MEDIA_STRICT", raising=False)
+    sys.modules.pop("api", None)
+    import api as api_mod
+
+    api_mod._backend_impl = None
+    api_mod._get_backend()
+    client = TestClient(api_mod.app)
+    r = client.get("/media/fetlife_fetishes/999999/0000000000001.jpg", follow_redirects=False)
+    assert r.status_code == 307
+    assert r.headers["location"] == "https://cdn.example.test/kink-media/fetlife_fetishes/999999/0000000000001.jpg"
+    h = client.get("/health").json()
+    assert h.get("media", {}).get("remote_mode") == "public_base"
+    assert h.get("media", {}).get("remote_configured") is True
+
+
 def test_favicon_serves_placeholder(media_fallback_app) -> None:
     client = TestClient(media_fallback_app.app)
     r = client.get("/favicon.ico")
@@ -62,8 +86,8 @@ def test_favicon_serves_placeholder(media_fallback_app) -> None:
     assert r.headers.get("content-type", "").startswith("image/")
 
 
-def test_hf_space_image_ignores_media_strict_for_missing_tiles(tmp_path, monkeypatch) -> None:
-    """Published HF image marker: placeholders win over a Space secret ``KINK_MEDIA_STRICT=1``."""
+def test_hf_space_image_honors_media_strict_for_missing_tiles(tmp_path, monkeypatch) -> None:
+    """Published HF image marker must not override an explicit Space ``KINK_MEDIA_STRICT=1``."""
     assert _SEED.is_file(), f"Missing seed DB: {_SEED}"
     dest = tmp_path / "media_hf_strict.db"
     shutil.copyfile(_SEED, dest)
@@ -79,12 +103,33 @@ def test_hf_space_image_ignores_media_strict_for_missing_tiles(tmp_path, monkeyp
     api_mod._get_backend()
     client = TestClient(api_mod.app)
     r = client.get("/media/fetlife_fetishes/999999/0000000000001.jpg")
-    assert r.status_code == 200
-    assert r.headers.get("x-kink-media-fallback") == "1"
+    assert r.status_code == 404
     h = client.get("/health").json()
     assert h.get("media", {}).get("hf_space_image") is True
     assert h.get("media", {}).get("strict_env") is True
-    assert h.get("media", {}).get("strict_missing_assets") is False
+    assert h.get("media", {}).get("strict_missing_assets") is True
+
+
+def test_full_catalog_mode_defaults_to_strict_missing_media(tmp_path, monkeypatch) -> None:
+    assert _SEED.is_file(), f"Missing seed DB: {_SEED}"
+    dest = tmp_path / "media_full_catalog.db"
+    shutil.copyfile(_SEED, dest)
+    monkeypatch.setenv("KINK_STORE_PATH", str(dest))
+    monkeypatch.setenv("KINK_SKIP_HEAVY_WARM", "1")
+    monkeypatch.setenv("KINK_HF_REQUIRE_FULL_CATALOG", "1")
+    monkeypatch.setenv("KINK_HF_STALE_MAX_BYTES", "0")
+    monkeypatch.delenv("KINK_MEDIA_STRICT", raising=False)
+    sys.modules.pop("api", None)
+    import api as api_mod
+
+    api_mod._backend_impl = None
+    api_mod._get_backend()
+    client = TestClient(api_mod.app)
+    r = client.get("/media/fetlife_fetishes/999999/0000000000001.jpg")
+    assert r.status_code == 404
+    h = client.get("/health").json()
+    assert h.get("media", {}).get("strict_env") is False
+    assert h.get("media", {}).get("strict_missing_assets") is True
 
 
 def test_invalid_kink_media_fallback_override_still_serves_bundled_demo(tmp_path, monkeypatch) -> None:

tests/test_hf_bootstrap.py

@@ -1,6 +1,7 @@
 """Persistence and optional Hub bootstrap behavior."""
 from __future__ import annotations
 
+import tarfile
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
@@ -30,6 +31,40 @@ def test_ensure_store_db_uses_existing_file(tmp_path: Path):
     assert ensure_store_db(p) == p.resolve()
 
 
+def test_ensure_media_cache_downloads_and_extracts_archive(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    from backend import hf_bootstrap
+
+    remote_dir = tmp_path / "remote"
+    source_dir = tmp_path / "source"
+    source_dir.mkdir()
+    (source_dir / "fetlife_fetishes").mkdir()
+    (source_dir / "fetlife_fetishes" / "1.jpg").write_bytes(b"jpeg")
+    archive = remote_dir / "cached_assets.tar"
+    remote_dir.mkdir()
+    with tarfile.open(archive, "w") as tar:
+        tar.add(source_dir / "fetlife_fetishes" / "1.jpg", arcname="fetlife_fetishes/1.jpg")
+
+    seen: dict[str, str] = {}
+
+    def fake_download(*, repo_id, filename, revision, token, local_dir, repo_type, **kwargs):
+        seen["repo_id"] = repo_id
+        seen["filename"] = filename
+        dest = Path(local_dir) / filename
+        dest.write_bytes(archive.read_bytes())
+        return str(dest)
+
+    target = tmp_path / "cached_assets"
+    monkeypatch.setenv("KINK_HF_MEDIA_ARCHIVE", "cached_assets.tar")
+    monkeypatch.setenv("KINK_HF_MEDIA_DATASET_REPO", "dummy/media")
+    with patch("huggingface_hub.hf_hub_download", side_effect=fake_download):
+        out = hf_bootstrap.ensure_media_cache(target)
+
+    assert out == target.resolve()
+    assert seen == {"repo_id": "dummy/media", "filename": "cached_assets.tar"}
+    assert (target / "fetlife_fetishes" / "1.jpg").read_bytes() == b"jpeg"
+    assert (target / ".cached_assets.tar.ready").is_file()
+
+
 def test_ensure_store_db_require_full_replaces_tiny_existing_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
     """Stale bundled seed on disk must not block Hub download when full catalog is required."""
     from backend import hf_bootstrap