add agents and readme

Reviewed-on: http://gitea.lan/gpatti/MediaLore-Web-App/pulls/3

AGENTS.md

@@ -0,0 +1,226 @@
+# AGENTS.md
+
+## Project Overview
+
+MediaLore is a **self-hosted media library browser** for images and videos. It provides a web UI for browsing, searching, tagging, and viewing media with thumbnail previews and doom-scroll/TikTok-style consumption.
+
+**Monorepo** with two independent apps:
+- `backend/` — Python FastAPI server
+- `frontend/` — React SPA (TypeScript, Vite)
+
+## Tech Stack
+
+| Layer       | Technology                                              |
+|-------------|---------------------------------------------------------|
+| Backend     | Python 3.12+, FastAPI, Uvicorn                         |
+| Database    | SQLite via SQLAlchemy (async aiosqlite), WAL mode       |
+| Migrations  | Alembic                                                 |
+| Thumbnails  | Pillow (images), ffmpeg (videos) — generated on-demand  |
+| File Watch  | watchdog — live filesystem monitoring                   |
+| Frontend    | React 19, TypeScript 6, Vite 8, React Router 7, TanStack Query v5 |
+| Infra       | Docker Compose (backend: Python 3.12-slim, frontend: Nginx Alpine) |
+
+## Directory Structure
+
+```
+medialore-web-app/
+├── docker-compose.yml        # Orchestration (backend, frontend, volumes)
+├── .env.example              # MEDIA_ROOT env var template
+├── backend/
+│   ├── Dockerfile
+│   ├── pyproject.toml        # Python package config (hatchling build)
+│   ├── alembic.ini
+│   ├── alembic/              # DB migrations
+│   │   ├── env.py
+│   │   └── versions/
+│   └── app/
+│       ├── main.py           # FastAPI app, CORS, lifespan, router registration
+│       ├── config.py         # Pydantic Settings (DATABASE_URL, MEDIA_ROOT, THUMBNAIL_DIR)
+│       ├── database.py       # SQLAlchemy async engine, session, WAL pragma
+│       ├── models.py         # ORM models: Library, MediaItem, Tag, media_item_tags
+│       ├── schemas.py        # Pydantic request/response schemas
+│       ├── routers/
+│       │   ├── libraries.py  # Library CRUD, browse, doom-scroll, scan-status, rescan
+│       │   ├── media.py      # Media item get, file serve, thumbnail, tag assignment
+│       │   ├── tags.py       # Tag CRUD, grouped by category
+│       │   └── search.py     # Fuzzy filename + tag search
+│       └── services/
+│           ├── scanner.py    # Dir walk, SHA-256 hashing, moved file detection
+│           ├── watcher.py    # watchdog event handler (create/move/delete)
+│           └── thumbnails.py # Pillow + ffmpeg thumbnail generation
+└── frontend/
+    ├── Dockerfile            # Multi-stage: Node build + Nginx serve
+    ├── nginx.conf            # SPA fallback, /api proxy to backend
+    ├── package.json
+    ├── tsconfig.json         # Root references
+    ├── tsconfig.app.json     # App TS config
+    ├── tsconfig.node.json    # Vite config TS config
+    ├── vite.config.ts        # Vite + React plugin, dev proxy /api -> localhost:8000
+    ├── eslint.config.js      # Flat config: JS + TS + React hooks + refresh
+    ├── index.html
+    ├── public/
+    │   ├── favicon.svg
+    │   └── icons.svg
+    └── src/
+        ├── main.tsx          # React entry point
+        ├── App.tsx           # Router, QueryClient, sidebar, theme, responsive layout
+        ├── index.css         # CSS custom properties for light/dark themes
+        ├── api/
+        │   └── client.ts     # Typed fetch wrapper; all endpoint functions
+        ├── pages/
+        │   ├── SearchPage.tsx
+        │   ├── BrowserPage.tsx
+        │   ├── SettingsPage.tsx
+        ├── components/
+        │   ├── FileBrowser/FileBrowser.tsx
+        │   ├── MediaViewer/MediaViewer.tsx
+        │   ├── DoomScrollViewer/DoomScrollViewer.tsx
+        │   └── TagPanel/TagPanel.tsx
+        └── assets/
+            ├── hero.png
+            └── vite.svg
+```
+
+## Common Commands
+
+### Backend
+
+```bash
+# Install (from backend/)
+pip install -e .
+
+# Run dev server
+cd backend && uvicorn app.main:app --reload --port 8000
+
+# Generate a new Alembic migration
+cd backend && alembic revision --autogenerate -m "description"
+
+# Apply migrations
+cd backend && alembic upgrade head
+```
+
+### Frontend
+
+```bash
+# Install dependencies (from frontend/)
+npm install
+
+# Dev server (proxies /api to localhost:8000)
+npm run dev
+
+# Production build
+npm run build
+
+# Lint
+npm run lint
+
+# Preview production build
+npm run preview
+```
+
+### Docker
+
+```bash
+docker compose up -d
+```
+
+## Environment Variables
+
+| Variable         | Default                             | Purpose                      |
+|------------------|-------------------------------------|------------------------------|
+| `DATABASE_URL`   | `sqlite+aiosqlite:////data/medialore.db` | SQLite connection string     |
+| `MEDIA_ROOT`     | `/media`                            | Root path for media libraries |
+| `THUMBNAIL_DIR`  | `/data/thumbnails`                  | Cached thumbnail storage     |
+
+Pydantic Settings reads from `.env` at startup (via `model_config = {"env_file": ".env"}`). For Docker, these are set in `docker-compose.yml`.
+
+## Database
+
+SQLite with **WAL mode** and a 10-second busy timeout (see `app/database.py:14-18`). Tables are auto-created at startup via `Base.metadata.create_all` in the FastAPI lifespan.
+
+### Schema
+
+- **libraries**: `id`, `name`, `path` (unique)
+- **media_items**: `id`, `library_id` (FK), `rel_path`, `filename`, `file_hash` (SHA-256), `media_type` ("image" or "video"), `size_bytes`, `missing`, `created_at`, `updated_at` — unique on `(library_id, rel_path)`
+- **tags**: `id`, `name`, `category` — unique on `(name, category)`
+- **media_item_tags**: `media_item_id` (FK), `tag_id` (FK), composite PK
+
+**Migrations**: Use Alembic. The initial migration is at `backend/alembic/versions/0001_initial_schema.py`.
+
+## API Conventions
+
+All endpoints are prefixed with `/api`. All responses are JSON except `/api/media/:id/file` (binary stream) and `/api/media/:id/thumbnail` (JPEG).
+
+### Async Database Access
+
+Routers use FastAPI's `Depends` injection with the `get_db` async generator from `database.py`:
+
+```python
+from app.database import get_db
+
+@router.get("/...")
+async def endpoint(db: AsyncSession = Depends(get_db)):
+    ...
+```
+
+### Frontend API Client
+
+All API calls go through the typed `api` object in `frontend/src/api/client.ts`. Use `useQuery` / `useMutation` from TanStack Query. Never call `fetch` directly from components.
+
+```ts
+import { api } from "../api/client";
+import { useQuery } from "@tanstack/react-query";
+
+const { data } = useQuery({
+  queryKey: ["libraries", id, "browse", path],
+  queryFn: () => api.libraries.browse(id, path),
+});
+```
+
+## Code Patterns & Conventions
+
+### Backend (Python)
+- **No linter configured** — follow the existing style (4-space indent, snake_case)
+- Models use SQLAlchemy 2.0-style `mapped_column` (not `Column()`)
+- Schemas use Pydantic `BaseModel`
+- Service modules handle business logic; routers handle HTTP concerns
+- Background scanning runs via `asyncio.create_task`; watchers run in separate threads via `watchdog.Observer`
+- Logging: use `logging.getLogger(__name__)` — the `app` namespace has a StreamHandler configured in `main.py`
+
+### Frontend (TypeScript/React)
+- **ESLint flat config** with strict TypeScript-ESLint rules
+- Inline `style={{ ... }}` objects for CSS (no CSS modules, no Tailwind)
+- TypeScript interfaces for all API types live in `client.ts`
+- Components use `useState`/`useEffect`/`useQuery` hooks, not class components
+- Theme state persisted in `localStorage` key `"theme"`, applied as `data-theme` attribute
+- Responsive via `window.matchMedia("(max-width: 767px)")` listener
+- File/thumbnail URLs constructed with `api.media.fileUrl(id)` and `api.media.thumbnailUrl(id)` (not fetched)
+
+### TypeScript Configuration
+- `tsconfig.app.json`: strict mode, `noUnusedLocals`, `noUnusedParameters`, `erasableSyntaxOnly`
+- `tsconfig.node.json`: for `vite.config.ts` only
+- Build command: `tsc -b && vite build` (type-check via project references)
+
+## Testing
+
+**There are no test files in this project.** No test framework is configured. When adding tests:
+- Frontend: consider Vitest (pairs with Vite) + React Testing Library
+- Backend: consider pytest + pytest-asyncio + httpx (for FastAPI TestClient)
+- No existing test commands in CI, so add them and consider a GitHub Action or similar
+
+## Docker / Deployment
+
+- `docker compose up -d` starts both services
+- Backend runs on port 8000 (internal), frontend Nginx on port 80 (mapped to 8085 on host)
+- Nginx proxies `/api/` to `http://backend:8000`
+- Media paths from the host are volume-mounted into the container at `/media`
+- Persistent data (DB, thumbnails) stored in Docker volume `medialore-data`
+
+## Important Notes
+
+- **No auth/authentication** — CORS allows all origins, no login system
+- Thumbnails are generated on first request and cached to disk (`THUMBNAIL_DIR`)
+- The scanner computes SHA-256 hashes to detect moved/renamed files and avoid re-processing
+- File watcher uses watchdog with per-library `PollingObserver` (necessary for Docker volumes)
+- `media_items.missing` flag is set when a scanned file no longer exists on disk
+- The frontend `build` command runs `tsc -b` first, which checks types across project references — type errors will block the build

README.md

@@ -0,0 +1,193 @@
+# MediaLore
+
+A self-hosted media library browser for images and videos. Organize your local media collections with tagged browsing, a file-system explorer, and a full-screen "doom scroll" viewer — all via a clean, responsive web UI.
+
+## Features
+
+- **Media Libraries** — Add local directories as named libraries; files are indexed by relative path within each library
+- **File Browser** — Navigate your library's directory structure with a thumbnail grid, breadcrumbs, and lazy-loaded previews
+- **Tagging System** — Organize media with named tags grouped into categories; create tags inline while viewing items
+- **Search** — Filter by filename (fuzzy match), tag, and/or library
+- **Doom Scroll** — Full-screen, swipe/scroll-driven media viewer for an immersive, social-media-like experience
+- **Live File Watching** — Automatically detects new, moved, and deleted files via `watchdog` (no manual rescans needed)
+- **Auto-Generated Thumbnails** — JPEG thumbnails for images (via Pillow) and videos (via ffmpeg)
+- **Dark / Light Theme** — Toggle with persistence via `localStorage`
+- **Responsive** — Mobile-friendly with a collapsible sidebar and touch gestures
+
+## Architecture
+
+```
+┌─────────────┐       ┌──────────────┐       ┌─────────────┐
+│   Frontend   │──────▶│   Backend    │──────▶│   SQLite DB  │
+│  React +     │  HTTP │  FastAPI +   │  ORM  │  (SQLite +   │
+│  TypeScript  │       │  Uvicorn     │       │   WAL mode)  │
+│  Vite        │       │              │       │              │
+└─────────────┘       └──────┬───────┘       └─────────────┘
+                             │
+                     ┌───────▼────────┐
+                     │  File System    │
+                     │  (media root)   │
+                     └─────────────────┘
+```
+
+**Backend** — Python 3.12+, FastAPI, SQLAlchemy (async), aiosqlite, Alembic for migrations, `watchdog` for file-system events, Pillow for image thumbnails, ffmpeg for video thumbnails.
+
+**Frontend** — React 19, TypeScript, Vite 8, React Router 7, TanStack Query, Nginx (static serving + API proxy).
+
+## Quick Start (Docker Compose)
+
+### Prerequisites
+
+- Docker & Docker Compose
+- ffmpeg (bundled in the backend container)
+- Your media files accessible on the host (e.g. mounted from a NAS)
+
+### 1. Clone & configure
+
+```bash
+git clone <repo-url>
+cd MediaLore-Web-App
+cp .env.example .env
+```
+
+Edit `.env` to point `MEDIA_ROOT` to your host media directory:
+
+```env
+MEDIA_ROOT=/mnt/nas
+```
+
+> **Note:** Inside the container, `$MEDIA_ROOT` maps to `/media`. Library paths you add in the UI must be subdirectories of this mount.
+
+### 2. Start the stack
+
+```bash
+docker compose up --build -d
+```
+
+The frontend is available at `http://localhost:8085`.
+
+### 3. Add a library
+
+1. Open **Settings** → **Libraries**
+2. Enter a name and a path (e.g. `/media/Images/Photos`)
+3. Click **Add Library** — scanning begins in the background
+
+The scanner walks the directory tree, computes SHA-256 hashes, detects moved files by hash, and starts a file watcher for live updates.
+
+## Docker Compose Configuration
+
+```yaml
+services:
+  backend:
+    build: ./backend
+    volumes:
+      - medialore-data:/data          # DB + thumbnails
+      - /data/smb/adult/Images:/media/Images
+      - /data/smb/adult/Video Clips:/media/Video Clips
+    environment:
+      - DATABASE_URL=sqlite+aiosqlite:////data/medialore.db
+      - THUMBNAIL_DIR=/data/thumbnails
+
+  frontend:
+    build: ./frontend
+    ports:
+      - "8085:80"
+```
+
+Adjust the volume mounts to match your media layout. The `medialore-data` named volume persists the SQLite database and generated thumbnails across restarts.
+
+## API Endpoints
+
+All endpoints are under `/api` and return JSON (except file/thumbnail responses).
+
+### Libraries
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/libraries` | List all libraries |
+| `POST` | `/libraries` | Create a library (`{ name, path }`) |
+| `GET` | `/libraries/:id/scan-status` | Check if a library is currently scanning |
+| `POST` | `/libraries/:id/rescan` | Trigger a manual rescan |
+| `GET` | `/libraries/:id/browse` | Browse directory entries (`?path=/sub/dir`) |
+| `GET` | `/libraries/:id/doom-scroll` | Get all media items in a library (optionally under a path) |
+| `DELETE` | `/libraries/:id` | Remove a library (stops watcher, deletes records) |
+
+### Media
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/media/:id` | Get media item details (with tags) |
+| `GET` | `/media/:id/file` | Stream the original media file |
+| `GET` | `/media/:id/thumbnail` | Get or generate a thumbnail (JPEG) |
+| `PUT` | `/media/:id/tags` | Set tags on an item (`{ tag_ids: [1, 2] }`) |
+
+### Tags
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/tags` | List all tags grouped by category |
+| `POST` | `/tags` | Create a tag (`{ name, category }`) |
+| `DELETE` | `/tags/:id` | Delete a tag |
+
+### Search
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/search?q=foo&tags=1,2&library_id=3` | Search media by filename, tags, and/or library |
+
+## Development
+
+### Backend (local)
+
+```bash
+cd backend
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"   # or: pip install fastapi uvicorn[standard] sqlalchemy aiosqlite alembic pydantic-settings watchdog Pillow python-multipart
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Frontend (local)
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+The Vite dev server runs at `http://localhost:5173`. Configure your proxy or set `VITE_API_BASE` to point to the backend.
+
+## Data Model
+
+```
+┌──────────┐       1..*       ┌────────────┐       *..*       ┌─────┐
+│ Library   │─────────────────▶│ MediaItem  │─────────────────▶│ Tag  │
+└──────────┘                  └────────────┘                  └─────┘
+  • id                          • id
+  • name                        • library_id
+  • path                        • rel_path
+                                • filename
+                                • file_hash   (SHA-256)
+                                • media_type  (image | video)
+                                • size_bytes
+                                • missing     (file deleted from disk)
+                                • created_at
+                                • updated_at
+                                • tags[]
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Frontend | React 19, TypeScript, Vite, React Router, TanStack Query |
+| Backend | Python 3.12+, FastAPI, Uvicorn |
+| Database | SQLite (async via aiosqlite, WAL mode) |
+| Migrations | Alembic |
+| Thumbnails | Pillow (images), ffmpeg (videos) |
+| File Watching | watchdog |
+| Containerization | Docker (Python 3.12-slim, Node 20-alpine, Nginx Alpine) |
+
+## License
+
+[Add your license here]

docker-compose.yml

@@ -3,7 +3,7 @@ services:
     build: ./backend
     restart: unless-stopped
     volumes:
-      - ./data:/data
+      - medialore-data:/data
       - /data/smb/adult/Images:/media/Images
       - /data/smb/adult/Video Clips:/media/Video Clips
     environment:
@@ -16,3 +16,6 @@ services:
       - "8080:80"
     depends_on:
       - backend
+
+volumes:
+  medialore-data:

frontend/src/App.tsx

@@ -21,7 +21,7 @@ function useTheme() {
   return { dark, toggle: () => setDark((d) => !d) };
 }
 
-function Sidebar({ onToggleTheme, dark }: { onToggleTheme: () => void; dark: boolean }) {
+function Sidebar({ onToggleTheme, dark, onClose }: { onToggleTheme: () => void; dark: boolean; onClose?: () => void }) {
   const { data: libraries = [] } = useQuery<Library[]>({
     queryKey: ["libraries"],
     queryFn: api.libraries.list,
@@ -52,7 +52,7 @@ function Sidebar({ onToggleTheme, dark }: { onToggleTheme: () => void; dark: boo
         MediaLore
       </div>
 
-      <NavLink to="/search" style={linkStyle}>Search</NavLink>
+      <NavLink to="/search" style={linkStyle} onClick={onClose}>Search</NavLink>
 
       {libraries.length > 0 && (
         <>
@@ -60,7 +60,7 @@ function Sidebar({ onToggleTheme, dark }: { onToggleTheme: () => void; dark: boo
             Libraries
           </div>
           {libraries.map((lib) => (
-            <NavLink key={lib.id} to={`/library/${lib.id}`} style={linkStyle}>
+            <NavLink key={lib.id} to={`/library/${lib.id}`} style={linkStyle} onClick={onClose}>
               {lib.name}
             </NavLink>
           ))}
@@ -68,7 +68,7 @@ function Sidebar({ onToggleTheme, dark }: { onToggleTheme: () => void; dark: boo
       )}
 
       <div style={{ marginTop: "auto", display: "flex", flexDirection: "column", gap: 4 }}>
-        <NavLink to="/settings" style={linkStyle}>Settings</NavLink>
+        <NavLink to="/settings" style={linkStyle} onClick={onClose}>Settings</NavLink>
         <button
           onClick={onToggleTheme}
           title={dark ? "Switch to light mode" : "Switch to dark mode"}
@@ -83,11 +83,51 @@ function Sidebar({ onToggleTheme, dark }: { onToggleTheme: () => void; dark: boo
 
 function AppShell() {
   const { dark, toggle } = useTheme();
+  const [isMobile, setIsMobile] = useState(() => window.innerWidth < 768);
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+
+  useEffect(() => {
+    const mq = window.matchMedia("(max-width: 767px)");
+    setIsMobile(mq.matches);
+    const handler = (e: MediaQueryListEvent) => {
+      setIsMobile(e.matches);
+      if (!e.matches) setSidebarOpen(false);
+    };
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+  }, []);
 
   return (
     <div style={{ display: "flex", height: "100vh", background: "var(--bg)", color: "var(--text)" }}>
-      <Sidebar onToggleTheme={toggle} dark={dark} />
+      {/* Mobile hamburger button */}
-      <main style={{ flex: 1, overflow: "auto", background: "var(--bg)" }}>
+      {isMobile && (
+        <button
+          onClick={() => setSidebarOpen((v) => !v)}
+          style={{ position: "fixed", top: 12, left: 12, zIndex: 301, background: "var(--bg)", border: "1px solid var(--border)", borderRadius: 6, padding: "6px 10px", color: "var(--text)", fontSize: 18, cursor: "pointer" }}
+          aria-label="Toggle menu"
+        >
+          ☰
+        </button>
+      )}
+
+      {/* Mobile backdrop */}
+      {isMobile && sidebarOpen && (
+        <div
+          onClick={() => setSidebarOpen(false)}
+          style={{ position: "fixed", inset: 0, background: "rgba(0,0,0,0.4)", zIndex: 299 }}
+        />
+      )}
+
+      {/* Sidebar */}
+      <div style={isMobile ? {
+        position: "fixed", top: 0, left: 0, bottom: 0, zIndex: 300,
+        transform: sidebarOpen ? "translateX(0)" : "translateX(-100%)",
+        transition: "transform 0.2s ease",
+      } : {}}>
+        <Sidebar onToggleTheme={toggle} dark={dark} onClose={isMobile ? () => setSidebarOpen(false) : undefined} />
+      </div>
+
+      <main style={{ flex: 1, overflow: "auto", background: "var(--bg)", paddingTop: isMobile ? 48 : 0 }}>
         <Routes>
           <Route path="/" element={<SearchPage />} />
           <Route path="/search" element={<SearchPage />} />

frontend/src/components/DoomScrollViewer/DoomScrollViewer.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { api, type MediaItem } from "../../api/client";
 
 interface Props {
@@ -11,10 +11,12 @@ export default function DoomScrollViewer({ items, onClose, onViewInLibrary }: Pr
   const [index, setIndex] = useState(0);
   const [fading, setFading] = useState(false);
   const wheelLock = useRef(false);
+  const touchStartY = useRef<number | null>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
 
   const item = items[index];
 
-  function go(delta: 1 | -1) {
+  const go = useCallback((delta: 1 | -1) => {
     if (wheelLock.current) return;
     const next = index + delta;
     if (next < 0 || next >= items.length) return;
@@ -25,7 +27,7 @@ export default function DoomScrollViewer({ items, onClose, onViewInLibrary }: Pr
       setFading(false);
       wheelLock.current = false;
     }, 200);
-  }
+  }, [index, items.length]);
 
   useEffect(() => {
     const onWheel = (e: WheelEvent) => { e.deltaY > 0 ? go(1) : go(-1); };
@@ -40,7 +42,62 @@ export default function DoomScrollViewer({ items, onClose, onViewInLibrary }: Pr
       window.removeEventListener("wheel", onWheel);
       window.removeEventListener("keydown", onKey);
     };
-  }, [index, fading]);
+  }, [go, onClose]);
+
+  useEffect(() => {
+    const onTouchStart = (e: TouchEvent) => {
+      touchStartY.current = e.touches[0].clientY;
+      if (contentRef.current) contentRef.current.style.transition = "none";
+    };
+
+    const onTouchMove = (e: TouchEvent) => {
+      e.preventDefault();
+      if (touchStartY.current === null || !contentRef.current) return;
+      const offset = e.touches[0].clientY - touchStartY.current;
+      contentRef.current.style.transform = `translateY(${offset}px)`;
+      contentRef.current.style.opacity = String(Math.max(0.3, 1 - Math.abs(offset) / 300));
+    };
+
+    const onTouchEnd = (e: TouchEvent) => {
+      if (touchStartY.current === null) return;
+      const delta = touchStartY.current - e.changedTouches[0].clientY;
+      touchStartY.current = null;
+
+      if (Math.abs(delta) > 80) {
+        // Hand off to the fading animation
+        if (contentRef.current) {
+          contentRef.current.style.transition = "";
+          contentRef.current.style.transform = "";
+          contentRef.current.style.opacity = "";
+        }
+        go(delta > 0 ? 1 : -1);
+      } else {
+        // Snap back to center
+        if (contentRef.current) {
+          const el = contentRef.current;
+          el.style.transition = "opacity 0.25s ease, transform 0.25s ease";
+          el.style.transform = "translateY(0)";
+          el.style.opacity = "1";
+          setTimeout(() => {
+            if (contentRef.current) {
+              contentRef.current.style.transition = "";
+              contentRef.current.style.transform = "";
+              contentRef.current.style.opacity = "";
+            }
+          }, 260);
+        }
+      }
+    };
+
+    window.addEventListener("touchstart", onTouchStart);
+    window.addEventListener("touchmove", onTouchMove, { passive: false });
+    window.addEventListener("touchend", onTouchEnd);
+    return () => {
+      window.removeEventListener("touchstart", onTouchStart);
+      window.removeEventListener("touchmove", onTouchMove);
+      window.removeEventListener("touchend", onTouchEnd);
+    };
+  }, [go]);
 
   return (
     <>
@@ -49,6 +106,7 @@ export default function DoomScrollViewer({ items, onClose, onViewInLibrary }: Pr
 
       {/* Media area */}
       <div
+        ref={contentRef}
         style={{
           position: "fixed", inset: 0, zIndex: 201,
           display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center",
@@ -58,7 +116,6 @@ export default function DoomScrollViewer({ items, onClose, onViewInLibrary }: Pr
           transform: fading ? "translateY(-12px)" : "translateY(0)",
         }}
       >
-        <div style={{ color: "#ccc", fontSize: 13 }}>{item?.filename}</div>
         {item?.media_type === "image" && (
           <img
             key={item.id}
@@ -71,8 +128,11 @@ export default function DoomScrollViewer({ items, onClose, onViewInLibrary }: Pr
           <video
             key={item.id}
             src={api.media.fileUrl(item.id)}
-            controls
             autoPlay
+            muted
+            playsInline
+            controls
+            loop
             style={{ maxWidth: "90vw", maxHeight: "82vh" }}
           />
         )}

frontend/src/components/MediaViewer/MediaViewer.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { api, type BrowseEntry, type MediaItem } from "../../api/client";
 import TagPanel from "../TagPanel/TagPanel";
@@ -11,7 +11,14 @@ interface Props {
 }
 
 export default function MediaViewer({ mediaId, siblings, onClose, onNavigate }: Props) {
-  const [showTags, setShowTags] = useState(true);
+  const TAG_PANEL_WIDTH = 260;
+  const EDGE_GAP = 16;
+  const BASE_CARD_TRANSFORM = "translate(-50%, -50%)";
+  const [showTags, setShowTags] = useState(() => window.innerWidth >= 768);
+  const touchStartX = useRef<number | null>(null);
+  const touchStartY = useRef<number | null>(null);
+  const swipeAxis = useRef<"horizontal" | "vertical" | null>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
 
   const { data: item } = useQuery<MediaItem>({
     queryKey: ["media", mediaId],
@@ -22,6 +29,16 @@ export default function MediaViewer({ mediaId, siblings, onClose, onNavigate }:
   const currentIndex = mediaSiblings.findIndex((e) => e.media_item_id === mediaId);
   const prevId = currentIndex > 0 ? mediaSiblings[currentIndex - 1].media_item_id : null;
   const nextId = currentIndex < mediaSiblings.length - 1 ? mediaSiblings[currentIndex + 1].media_item_id : null;
+  const cardCenterX = showTags ? `calc((100vw - ${TAG_PANEL_WIDTH}px) / 2)` : "50%";
+
+  // Clear inline styles when a new item loads so the card appears cleanly
+  useEffect(() => {
+    if (contentRef.current) {
+      contentRef.current.style.transition = "";
+      contentRef.current.style.transform = BASE_CARD_TRANSFORM;
+      contentRef.current.style.opacity = "1";
+    }
+  }, [mediaId, BASE_CARD_TRANSFORM]);
 
   useEffect(() => {
     function onKey(e: KeyboardEvent) {
@@ -29,9 +46,93 @@ export default function MediaViewer({ mediaId, siblings, onClose, onNavigate }:
       if (e.key === "ArrowLeft" && prevId) onNavigate(prevId);
       if (e.key === "ArrowRight" && nextId) onNavigate(nextId);
     }
+
+    const onTouchStart = (e: TouchEvent) => {
+      touchStartX.current = e.touches[0].clientX;
+      touchStartY.current = e.touches[0].clientY;
+      swipeAxis.current = null;
+      if (contentRef.current) contentRef.current.style.transition = "none";
+    };
+
+    const onTouchMove = (e: TouchEvent) => {
+      if (touchStartX.current === null || touchStartY.current === null) return;
+      const dx = e.touches[0].clientX - touchStartX.current;
+      const dy = e.touches[0].clientY - touchStartY.current;
+
+      // Commit to an axis on the first significant movement
+      if (swipeAxis.current === null && (Math.abs(dx) > 8 || Math.abs(dy) > 8)) {
+        swipeAxis.current = Math.abs(dx) >= Math.abs(dy) ? "horizontal" : "vertical";
+      }
+
+      // Vertical gestures (tag panel scroll, etc.) pass through untouched
+      if (swipeAxis.current !== "horizontal") return;
+
+      e.preventDefault();
+      if (!contentRef.current) return;
+      contentRef.current.style.transform = `translate(calc(-50% + ${dx}px), -50%)`;
+      contentRef.current.style.opacity = String(Math.max(0.4, 1 - Math.abs(dx) / 400));
+    };
+
+    const onTouchEnd = (e: TouchEvent) => {
+      if (touchStartX.current === null) return;
+      const delta = touchStartX.current - e.changedTouches[0].clientX;
+      touchStartX.current = null;
+      touchStartY.current = null;
+
+      // Non-horizontal gesture: just reset the transition we disabled on touchstart
+      if (swipeAxis.current !== "horizontal") {
+        swipeAxis.current = null;
+        if (contentRef.current) {
+          contentRef.current.style.transition = "";
+          contentRef.current.style.transform = BASE_CARD_TRANSFORM;
+          contentRef.current.style.opacity = "1";
+        }
+        return;
+      }
+      swipeAxis.current = null;
+
+      const targetId = delta > 0 ? nextId : prevId;
+
+      if (Math.abs(delta) > 80 && targetId) {
+        const el = contentRef.current;
+        if (el) {
+          const slideX = delta > 0 ? -120 : 120;
+          el.style.transition = "opacity 0.2s ease, transform 0.2s ease";
+          el.style.transform = `translate(calc(-50% + ${slideX}px), -50%)`;
+          el.style.opacity = "0";
+          setTimeout(() => onNavigate(targetId), 200);
+        } else {
+          onNavigate(targetId);
+        }
+      } else {
+        // Snap back to center
+        const el = contentRef.current;
+        if (el) {
+          el.style.transition = "opacity 0.25s ease, transform 0.25s ease";
+          el.style.transform = "translate(-50%, -50%)";
+          el.style.opacity = "1";
+          setTimeout(() => {
+            if (contentRef.current) {
+              contentRef.current.style.transition = "";
+              contentRef.current.style.transform = BASE_CARD_TRANSFORM;
+              contentRef.current.style.opacity = "1";
+            }
+          }, 260);
+        }
+      }
+    };
+
     window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
+    window.addEventListener("touchstart", onTouchStart);
-  }, [prevId, nextId, onClose, onNavigate]);
+    window.addEventListener("touchmove", onTouchMove, { passive: false });
+    window.addEventListener("touchend", onTouchEnd);
+    return () => {
+      window.removeEventListener("keydown", onKey);
+      window.removeEventListener("touchstart", onTouchStart);
+      window.removeEventListener("touchmove", onTouchMove);
+      window.removeEventListener("touchend", onTouchEnd);
+    };
+  }, [prevId, nextId, onClose, onNavigate, BASE_CARD_TRANSFORM]);
 
   return (
     <>
@@ -54,15 +155,16 @@ export default function MediaViewer({ mediaId, siblings, onClose, onNavigate }:
       <button
         onClick={() => nextId && onNavigate(nextId)}
         disabled={!nextId}
-        style={{ position: "fixed", right: showTags ? 276 : 16, top: "50%", transform: "translateY(-50%)", zIndex: 102, fontSize: 36, background: "none", border: "none", color: nextId ? "#fff" : "#444", cursor: nextId ? "pointer" : "default" }}
+        style={{ position: "fixed", right: showTags ? TAG_PANEL_WIDTH + EDGE_GAP : EDGE_GAP, top: "50%", transform: "translateY(-50%)", zIndex: 102, fontSize: 36, background: "none", border: "none", color: nextId ? "#fff" : "#444", cursor: nextId ? "pointer" : "default" }}
       >
         ›
       </button>
 
       {/* Media card */}
       <div
+        ref={contentRef}
         onClick={(e) => e.stopPropagation()}
-        style={{ position: "fixed", top: "50%", left: "50%", transform: "translate(-50%, -50%)", zIndex: 101, background: "#1a1a1a", borderRadius: 8, padding: 16, display: "flex", flexDirection: "column", alignItems: "center", gap: 12, maxWidth: "80vw", maxHeight: "90vh", overflow: "auto" }}
+        style={{ position: "fixed", top: "50%", left: cardCenterX, transform: BASE_CARD_TRANSFORM, zIndex: 101, background: "#1a1a1a", borderRadius: 8, padding: 16, display: "flex", flexDirection: "column", alignItems: "center", gap: 12, maxWidth: "80vw", maxHeight: "90vh", overflow: "auto" }}
       >
         {item?.filename && (
           <div style={{ color: "#ccc", fontSize: 13 }}>{item.filename}</div>
@@ -103,7 +205,7 @@ export default function MediaViewer({ mediaId, siblings, onClose, onNavigate }:
       {showTags && item && (
         <div
           onClick={(e) => e.stopPropagation()}
-          style={{ position: "fixed", top: 0, right: 0, height: "100%", width: 260, background: "#1a1a1a", borderLeft: "1px solid #333", padding: "48px 16px 16px", zIndex: 101, overflowY: "auto" }}
+          style={{ position: "fixed", top: 0, right: 0, height: "100%", width: TAG_PANEL_WIDTH, background: "#1a1a1a", borderLeft: "1px solid #333", padding: "48px 16px 16px", zIndex: 101, overflowY: "auto" }}
         >
           <TagPanel item={item} />
         </div>