build(project): install vips-tools for image thumbnailing

Add vips-tools (vipsthumbnail) to the runtime image alongside ffmpeg and
exiftool, and document THUMB_MAX_PIXELS as the pure-Go fallback guard.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,33 @@
+# Keep the build context small and reproducible: never ship local state,
+# dependencies, or build outputs — they are rebuilt inside the image.
+
+# VCS / tooling
+.git
+.gitignore
+**/.DS_Store
+
+# Compose file — used to build/run, not needed inside the image context
+docker-compose.yml
+docker-compose.*.yml
+
+# Secrets and local env
+.env
+.env.*
+!.env.example
+
+# Node
+frontend/node_modules
+frontend/.svelte-kit
+frontend/build
+frontend/.vite
+
+# Go
+backend/server
+backend/**/*.test
+
+# Docs / reference (not needed to build the image)
+docs/reference
+
+# Editor / OS
+.vscode
+.idea

.env.example

@@ -1,27 +1,90 @@
 # =============================================================================
 # Tanabata File Manager — environment variables
-# Copy to .env and fill in the values.
+#
+# Copy to .env and fill in the secrets:
+#   cp .env.example .env
+#   docker compose up -d --build
 # =============================================================================
 
+# ---------------------------------------------------------------------------
+# Docker Compose  (read by the compose CLI, ignored by the app)
+# ---------------------------------------------------------------------------
+# Profiles to enable. "with-db" runs the bundled Postgres container. Leave
+# EMPTY to skip it and use a Postgres running on the host instead — then point
+# DATABASE_URL at host.docker.internal (see the Database section below).
+COMPOSE_PROFILES=with-db
+
+# Host port the app is published on. The container always listens on 42776.
+APP_PORT=42776
+
+# ---------------------------------------------------------------------------
+# Volume mounts  (Docker Compose; ignored by the app)
+# ---------------------------------------------------------------------------
+# By default the app's data and the database live in named Docker volumes
+# (app_files, app_thumbs, app_import, db_data). To keep them in specific folders
+# on the host instead, point any of these at a host path — absolute, or relative
+# to this file (e.g. ./data/files). Unset = named volume.
+# FILES_DIR=/var/lib/tanabata/files
+# THUMBS_DIR=/var/lib/tanabata/thumbs
+# IMPORT_DIR=/var/lib/tanabata/import
+# DB_DIR=/var/lib/tanabata/db
+
+# When bind-mounting the app folders above, the container must be able to write
+# to them. Set PUID/PGID to the owner of those folders and create them with
+# matching ownership first, e.g.:
+#   sudo mkdir -p /var/lib/tanabata/{files,thumbs,import}
+#   sudo chown -R 1000:1000 /var/lib/tanabata
+#   PUID=1000
+#   PGID=1000
+# Defaults match the image's tanabata user (42776), which owns the named volumes. The
+# DB folder is handled by Postgres itself and needs no PUID/PGID.
+# PUID=42776
+# PGID=42776
+
 # ---------------------------------------------------------------------------
 # Server
 # ---------------------------------------------------------------------------
-LISTEN_ADDR=:8080
+# 42776 is the project's default port: the sum of the Unicode code points of
+# 七夕 (七 U+4E03 = 19971, 夕 U+5915 = 22805).
+LISTEN_ADDR=:42776
 JWT_SECRET=change-me-to-a-random-32-byte-secret
 JWT_ACCESS_TTL=15m
 JWT_REFRESH_TTL=720h
 
+# Initial administrator, created on first startup if it does not yet exist.
+# Changing the password later (via the API) is preserved across restarts.
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=change-me-before-first-run
+
 # ---------------------------------------------------------------------------
 # Database
 # ---------------------------------------------------------------------------
-DATABASE_URL=postgres://tanabata:password@localhost:5432/tanabata?sslmode=disable
+# Credentials for the bundled Postgres container (the "with-db" profile).
+# Keep these in sync with DATABASE_URL below.
+POSTGRES_DB=tanabata
+POSTGRES_USER=tanabata
+POSTGRES_PASSWORD=password
+
+# Connection string the app uses. Pick ONE to match your database mode:
+#
+#   • Bundled container DB (COMPOSE_PROFILES=with-db) — host is the "db" service:
+DATABASE_URL=postgres://tanabata:password@db:5432/tanabata?sslmode=disable
+#
+#   • Postgres on the host (COMPOSE_PROFILES empty):
+# DATABASE_URL=postgres://tanabata:password@host.docker.internal:5432/tanabata?sslmode=disable
+#
+#   • Bare-metal `go run` (no Docker):
+# DATABASE_URL=postgres://tanabata:password@localhost:5432/tanabata?sslmode=disable
 
 # ---------------------------------------------------------------------------
-# Storage
+# Storage  (paths inside the container; backed by named volumes in compose)
 # ---------------------------------------------------------------------------
 FILES_PATH=/data/files
 THUMBS_CACHE_PATH=/data/thumbs
 
+# Maximum accepted upload size in bytes (default 500 MiB).
+MAX_UPLOAD_BYTES=524288000
+
 # ---------------------------------------------------------------------------
 # Thumbnails
 # ---------------------------------------------------------------------------
@@ -29,8 +92,27 @@ THUMB_WIDTH=160
 THUMB_HEIGHT=160
 PREVIEW_WIDTH=1920
 PREVIEW_HEIGHT=1080
+# Pixel cap (width×height) for the pure-Go fallback decoder, used only when
+# vipsthumbnail is NOT installed; larger images then get a placeholder. With vips
+# present (the default image) thumbnails shrink on load, so this limit — and its
+# RAM cost — don't apply. Also bounds a decompression bomb. Default ~300 Mpx.
+THUMB_MAX_PIXELS=300000000
+# How many thumbnails/previews may be generated at once. Each resize already uses
+# every core, so a burst of large images otherwise pegs the CPU and RAM. 0 = auto
+# (half the available CPUs).
+THUMB_CONCURRENCY=0
 
 # ---------------------------------------------------------------------------
 # Import
 # ---------------------------------------------------------------------------
 IMPORT_PATH=/data/import
+
+# ---------------------------------------------------------------------------
+# Static SPA
+# ---------------------------------------------------------------------------
+# Leave UNSET here. The Docker image already serves the built SPA from
+# /app/static and compose pins STATIC_DIR for the container — an empty value in
+# .env would be injected into the container and disable SPA serving. Set this
+# only for a bare-metal deploy where the Go server serves a built SPA; leave it
+# unset in local dev, where the Vite dev server serves the UI.
+# STATIC_DIR=/path/to/frontend/build

.gitea/workflows/deploy.yml

@@ -0,0 +1,44 @@
+name: deploy
+
+# Build the image and (re)start the compose stack on the production host
+# whenever master moves. Also runnable manually from the Gitea Actions tab.
+on:
+  push:
+    branches: [master]
+  workflow_dispatch: {}
+
+# One deploy at a time; queue rather than cancel an in-flight run.
+concurrency:
+  group: deploy-prod
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    # Self-hosted act_runner registered on the prod host with the "host" label
+    # (shell executor), so the job uses the host's git + Docker daemon and the
+    # existing clone in /opt/tanabata. See docs/DEPLOY.md for runner setup.
+    #
+    # Only shell steps here (no `uses:` actions), so the host needs git + docker
+    # and nothing else — no node, no rsync.
+    runs-on: host
+
+    env:
+      DEPLOY_DIR: /opt/tanabata
+
+    steps:
+      - name: Pull latest master
+        # DEPLOY_DIR is a git clone set up once at deploy time. reset --hard
+        # makes it match origin exactly; .env is untracked (.gitignore) so it
+        # is never touched.
+        run: |
+          cd "$DEPLOY_DIR"
+          git fetch --prune origin
+          git reset --hard origin/master
+
+      - name: Build image and start the stack
+        working-directory: /opt/tanabata
+        # .env must already exist in DEPLOY_DIR on the host (secrets + DB mode).
+        run: docker compose up -d --build --remove-orphans
+
+      - name: Prune dangling build layers
+        run: docker image prune -f

CLAUDE.md

@@ -52,4 +52,7 @@ npm run generate:types       # regenerate API types from openapi.yaml
 - TypeScript: strict mode, named exports
 - SQL: snake_case, all migrations via goose
 - API errors: { code, message, details? }
-- Git: conventional commits (feat:, fix:, docs:, refactor:)
+- Git: conventional commits with scope — `type(scope): message`
+  - `(backend)` for Go backend code
+  - `(frontend)` for SvelteKit/TypeScript code
+  - `(project)` for root-level files (.gitignore, docs/reference, structure)

Dockerfile

@@ -0,0 +1,93 @@
+# syntax=docker/dockerfile:1
+
+# =============================================================================
+# Tanabata File Manager — single-image build
+#
+# Produces one container that serves the SvelteKit SPA (built to static files)
+# and the Go API on the same port. There is no Node runtime in the final image:
+# the frontend uses adapter-static, so stage 1 emits plain HTML/CSS/JS that the
+# Go binary serves directly (see STATIC_DIR).
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Stage 1 — build the frontend (static SPA)
+# -----------------------------------------------------------------------------
+FROM node:22-alpine AS frontend
+
+WORKDIR /src/frontend
+
+# Install dependencies first so this layer is cached unless the lockfile changes.
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+
+# `npm run build` runs `generate:types`, which reads ../openapi.yaml relative to
+# the frontend directory — place the spec one level up to match the repo layout.
+COPY openapi.yaml /src/openapi.yaml
+COPY frontend/ ./
+
+RUN npm run build
+# Output: /src/frontend/build (index.html, _app/, fonts, service-worker.js, …)
+
+# -----------------------------------------------------------------------------
+# Stage 2 — build the Go server (static binary)
+# -----------------------------------------------------------------------------
+FROM golang:1.26-alpine AS backend
+
+WORKDIR /src/backend
+
+# Download modules first so this layer is cached unless go.mod/go.sum changes.
+COPY backend/go.mod backend/go.sum ./
+RUN go mod download
+
+COPY backend/ ./
+
+# CGO is disabled: the binary shells out to external tools at runtime
+# (vipsthumbnail for image thumbnails, ffmpeg for video frames, exiftool for
+# metadata) and falls back to pure-Go image processing (disintegration/imaging)
+# when vips is absent, so it stays fully static and portable across base images.
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/server ./cmd/server
+
+# -----------------------------------------------------------------------------
+# Stage 3 — minimal runtime
+#
+# Alpine (not distroless/scratch) because thumbnailing and metadata extraction
+# invoke external processes (vipsthumbnail, ffmpeg, exiftool) that must be present
+# on the runtime image.
+# -----------------------------------------------------------------------------
+FROM alpine:3.21 AS runtime
+
+# vips-tools: fast, low-memory image thumbnails (shrink-on-load, so multi-hundred-
+# Mpx photos cost little). ffmpeg: video frame extraction. exiftool: rich metadata.
+# ca-certificates/tzdata: TLS + time zones.
+RUN apk add --no-cache vips-tools ffmpeg exiftool ca-certificates tzdata
+
+# Run as an unprivileged user.
+RUN addgroup -S -g 42776 tanabata && adduser -S -G tanabata -u 42776 tanabata
+
+WORKDIR /app
+
+# The built SPA, served by the Go binary (matches STATIC_DIR below).
+COPY --from=frontend --chown=tanabata:tanabata /src/frontend/build /app/static
+# The server binary.
+COPY --from=backend --chown=tanabata:tanabata /out/server /app/server
+
+# Data directories (overridable via FILES_PATH/THUMBS_CACHE_PATH/IMPORT_PATH).
+# Created and owned by the tanabata user so a fresh named volume inherits write access.
+RUN mkdir -p /data/files /data/thumbs /data/import && chown -R tanabata:tanabata /data
+
+# Non-secret defaults mirroring .env.example. Secrets (JWT_SECRET, ADMIN_PASSWORD,
+# DATABASE_URL) are intentionally NOT baked in — pass them at `docker run`.
+ENV LISTEN_ADDR=:42776 \
+    STATIC_DIR=/app/static \
+    FILES_PATH=/data/files \
+    THUMBS_CACHE_PATH=/data/thumbs \
+    IMPORT_PATH=/data/import
+
+EXPOSE 42776
+VOLUME ["/data"]
+USER tanabata
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD wget -qO- http://127.0.0.1:42776/health >/dev/null 2>&1 || exit 1
+
+ENTRYPOINT ["/app/server"]

backend/cmd/server/main.go

@@ -3,7 +3,9 @@ package main
 import (
 	"context"
 	"log/slog"
+	"net/http"
 	"os"
+	"time"
 
 	"github.com/jackc/pgx/v5/stdlib"
 	"github.com/pressly/goose/v3"
@@ -50,6 +52,7 @@ func main() {
 		cfg.ThumbsCachePath,
 		cfg.ThumbWidth, cfg.ThumbHeight,
 		cfg.PreviewWidth, cfg.PreviewHeight,
+		cfg.ThumbMaxPixels, cfg.ThumbConcurrency,
 	)
 	if err != nil {
 		slog.Error("failed to initialise storage", "err", err)
@@ -63,6 +66,10 @@ func main() {
 	mimeRepo := postgres.NewMimeRepo(pool)
 	aclRepo := postgres.NewACLRepo(pool)
 	auditRepo := postgres.NewAuditRepo(pool)
+	tagRepo := postgres.NewTagRepo(pool)
+	tagRuleRepo := postgres.NewTagRuleRepo(pool)
+	categoryRepo := postgres.NewCategoryRepo(pool)
+	poolRepo := postgres.NewPoolRepo(pool)
 	transactor := postgres.NewTransactor(pool)
 
 	// Services
@@ -73,27 +80,58 @@ func main() {
 		cfg.JWTAccessTTL,
 		cfg.JWTRefreshTTL,
 	)
-	aclSvc   := service.NewACLService(aclRepo)
+	aclSvc := service.NewACLService(aclRepo, fileRepo, tagRepo, categoryRepo, poolRepo, transactor)
 	auditSvc := service.NewAuditService(auditRepo)
+	tagSvc := service.NewTagService(tagRepo, tagRuleRepo, aclSvc, auditSvc, transactor)
+	categorySvc := service.NewCategoryService(categoryRepo, tagRepo, aclSvc, auditSvc)
+	poolSvc := service.NewPoolService(poolRepo, aclSvc, auditSvc)
 	fileSvc := service.NewFileService(
 		fileRepo,
 		mimeRepo,
 		diskStorage,
 		aclSvc,
 		auditSvc,
+		tagSvc,
 		transactor,
 		cfg.ImportPath,
 	)
+	userSvc := service.NewUserService(userRepo, sessionRepo, auditSvc)
+
+	// Bootstrap the initial administrator (idempotent).
+	if err := userSvc.EnsureAdmin(context.Background(), cfg.AdminUsername, cfg.AdminPassword); err != nil {
+		slog.Error("failed to bootstrap admin user", "err", err)
+		os.Exit(1)
+	}
 
 	// Handlers
 	authMiddleware := handler.NewAuthMiddleware(authSvc)
 	authHandler := handler.NewAuthHandler(authSvc)
-	fileHandler    := handler.NewFileHandler(fileSvc)
+	fileHandler := handler.NewFileHandler(fileSvc, tagSvc, cfg.MaxUploadBytes)
+	tagHandler := handler.NewTagHandler(tagSvc, fileSvc)
+	categoryHandler := handler.NewCategoryHandler(categorySvc)
+	poolHandler := handler.NewPoolHandler(poolSvc)
+	userHandler := handler.NewUserHandler(userSvc)
+	aclHandler := handler.NewACLHandler(aclSvc)
+	auditHandler := handler.NewAuditHandler(auditSvc)
 
-	r := handler.NewRouter(authMiddleware, authHandler, fileHandler)
+	r := handler.NewRouter(
+		authMiddleware, authHandler,
+		fileHandler, tagHandler, categoryHandler, poolHandler,
+		userHandler, aclHandler, auditHandler,
+		cfg.StaticDir,
+	)
+
+	// ReadHeaderTimeout bounds slow-header (Slowloris) attacks; body read/write
+	// are left unbounded so large file uploads and downloads can stream.
+	srv := &http.Server{
+		Addr:              cfg.ListenAddr,
+		Handler:           r,
+		ReadHeaderTimeout: 10 * time.Second,
+		IdleTimeout:       120 * time.Second,
+	}
 
 	slog.Info("starting server", "addr", cfg.ListenAddr)
-	if err := r.Run(cfg.ListenAddr); err != nil {
+	if err := srv.ListenAndServe(); err != nil {
 		slog.Error("server error", "err", err)
 		os.Exit(1)
 	}

backend/go.mod

@@ -5,51 +5,100 @@ go 1.26
 toolchain go1.26.1
 
 require (
+	github.com/disintegration/imaging v1.6.2
+	github.com/gabriel-vasile/mimetype v1.4.12
 	github.com/gin-gonic/gin v1.9.1
+	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/google/uuid v1.6.0
 	github.com/jackc/pgx/v5 v5.5.5
 	github.com/joho/godotenv v1.5.1
 	github.com/pressly/goose/v3 v3.21.1
+	github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd
+	github.com/stretchr/testify v1.11.1
+	github.com/testcontainers/testcontainers-go v0.41.0
+	github.com/testcontainers/testcontainers-go/modules/postgres v0.41.0
+	golang.org/x/crypto v0.48.0
+	golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8
 )
 
 require (
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/bytedance/gopkg v0.1.3 // indirect
 	github.com/bytedance/sonic v1.15.0 // indirect
 	github.com/bytedance/sonic/loader v0.5.0 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/cloudwego/base64x v0.1.6 // indirect
-	github.com/disintegration/imaging v1.6.2 // indirect
+	github.com/containerd/errdefs v1.0.0 // indirect
-	github.com/gabriel-vasile/mimetype v1.4.12 // indirect
+	github.com/containerd/errdefs/pkg v0.3.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/containerd/platforms v0.2.1 // indirect
+	github.com/cpuguy83/dockercfg v0.3.2 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/docker v28.5.2+incompatible // indirect
+	github.com/docker/go-connections v0.6.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/ebitengine/purego v0.10.0 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.22.0 // indirect
 	github.com/goccy/go-json v0.10.5 // indirect
-	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.1 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/compress v1.18.2 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.9 // indirect
-	github.com/kr/text v0.2.0 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mfridman/interpolate v0.0.2 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/go-archive v0.2.0 // indirect
+	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/user v0.4.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/moby/term v0.5.2 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.1 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
-	github.com/rogpeppe/go-internal v1.14.1 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
-	github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
 	github.com/sethvargo/go-retry v0.3.0 // indirect
+	github.com/shirou/gopsutil/v4 v4.26.2 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
+	github.com/tklauser/go-sysconf v0.3.16 // indirect
+	github.com/tklauser/numcpus v0.11.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.3.1 // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 // indirect
+	go.opentelemetry.io/otel v1.41.0 // indirect
+	go.opentelemetry.io/otel/metric v1.41.0 // indirect
+	go.opentelemetry.io/otel/trace v1.41.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	golang.org/x/arch v0.22.0 // indirect
-	golang.org/x/crypto v0.39.0 // indirect
+	golang.org/x/net v0.49.0 // indirect
-	golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8 // indirect
-	golang.org/x/net v0.33.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
 	golang.org/x/sys v0.41.0 // indirect
 	golang.org/x/text v0.34.0 // indirect
+	google.golang.org/grpc v1.79.1 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

backend/go.sum

@@ -1,25 +1,69 @@
+dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
+dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8afgbRMd7mFxO99hRNu+6tazq8nFF9lIwo9JFroBk=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6/go.mod h1:8o94RPi1/7XTJvwPpRSzSUedZrtlirdB3r9Z20bi2f8=
+github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c h1:udKWzYgxTojEKWjV8V+WSxDXJ4NFATAsZjh8iIbsQIg=
+github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
 github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
 github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
 github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
 github.com/bytedance/sonic v1.15.0/go.mod h1:tFkWrPz0/CUCLEF4ri4UkHekCIcdnkqXw9VduqpJh0k=
 github.com/bytedance/sonic/loader v0.5.0 h1:gXH3KVnatgY7loH5/TkeVyXPfESoqSBSBEiDd5VjlgE=
 github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM=
+github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
 github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
-github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
+github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
+github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
+github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk=
+github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
+github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
+github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
+github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
+github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
+github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
+github.com/creack/pty v1.1.18 h1:n56/Zwd5o6whRC5PMGretI4IdRLlmBXYNjScPaBgsbY=
+github.com/creack/pty v1.1.18/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/disintegration/imaging v1.6.2 h1:w1LecBlG2Lnp8B3jk5zSuNqd7b4DXhcjwek1ei82L+c=
 github.com/disintegration/imaging v1.6.2/go.mod h1:44/5580QXChDfwIclfc/PCwrr44amcmDAg8hxG0Ewe4=
+github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
+github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/docker v28.5.2+incompatible h1:DBX0Y0zAjZbSrm1uzOkdr1onVghKaftjlSWt4AFexzM=
+github.com/docker/docker v28.5.2+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
+github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
+github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
+github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/ISU=
+github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
 github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
 github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
 github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
 github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
 github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
 github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YrpYKXt5YId3A/Tnip5kqbEAP+KLuI3SUcPTeU=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
+github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
 github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
@@ -32,11 +76,14 @@ github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
 github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
 github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 h1:HWRh5R2+9EifMyIHV7ZV+MIZqgz+PMpZ14Jynv3O2Zs=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0/go.mod h1:JfhWUomR1baixubs02l85lZYYOm7LV6om4ceouMv45c=
 github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
@@ -51,29 +98,65 @@ github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/compress v1.18.2 h1:iiPHWW0YrcFgpBYhsA6D1+fqHssJscY/Tm/y2Uqnapk=
+github.com/klauspost/compress v1.18.2/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
 github.com/klauspost/cpuid/v2 v2.2.9 h1:66ze0taIn2H33fBvCkXuv9BmCwDfafmiIVpKV9kKGuY=
 github.com/klauspost/cpuid/v2 v2.2.9/go.mod h1:rqkxqrZ1EhYM9G+hXH7YdowN5R5RGN6NK4QwQ3WMXF8=
-github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
-github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
+github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
+github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
+github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mdelapenya/tlscert v0.2.0 h1:7H81W6Z/4weDvZBNOfQte5GpIMo0lGYEeWbkGp5LJHI=
+github.com/mdelapenya/tlscert v0.2.0/go.mod h1:O4njj3ELLnJjGdkN7M/vIVCpZ+Cf0L6muqOG4tLSl8o=
 github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY=
 github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg=
+github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
+github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
+github.com/moby/go-archive v0.2.0 h1:zg5QDUM2mi0JIM9fdQZWC7U8+2ZfixfTYoHL7rWUcP8=
+github.com/moby/go-archive v0.2.0/go.mod h1:mNeivT14o8xU+5q1YnNrkQVpK+dnNe/K6fHqnTg4qPU=
+github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk=
+github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
+github.com/moby/sys/atomicwriter v0.1.0 h1:kw5D/EqkBwsBFi0ss9v1VG3wIkVhzGvLklJ+w3A14Sw=
+github.com/moby/sys/atomicwriter v0.1.0/go.mod h1:Ul8oqv2ZMNHOceF643P6FKPXeCmYtlQMvpizfsSoaWs=
+github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
+github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko=
+github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs=
+github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
+github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
+github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
+github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ=
+github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A=
+github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
 github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4=
 github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
+github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU=
+github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/pressly/goose/v3 v3.21.1 h1:5SSAKKWej8LVVzNLuT6KIvP1eFDuPvxa+B6H0w78buQ=
 github.com/pressly/goose/v3 v3.21.1/go.mod h1:sqthmzV8PitchEkjecFJII//l43dLOCzfWh8pHEe+vE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
@@ -84,39 +167,88 @@ github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd h1:CmH9+J6ZSsIjUK
 github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd/go.mod h1:hPqNNc0+uJM6H+SuU8sEs5K5IQeKccPqeSjfgcKGgPk=
 github.com/sethvargo/go-retry v0.3.0 h1:EEt31A35QhrcRZtrYFDTBg91cqZVnFL2navjDrah2SE=
 github.com/sethvargo/go-retry v0.3.0/go.mod h1:mNX17F0C/HguQMyMyJxcnU471gOZGxCLyYaFyAZraas=
+github.com/shirou/gopsutil/v4 v4.26.2 h1:X8i6sicvUFih4BmYIGT1m2wwgw2VG9YgrDTi7cIRGUI=
+github.com/shirou/gopsutil/v4 v4.26.2/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ=
+github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
+github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/testcontainers/testcontainers-go v0.41.0 h1:mfpsD0D36YgkxGj2LrIyxuwQ9i2wCKAD+ESsYM1wais=
+github.com/testcontainers/testcontainers-go v0.41.0/go.mod h1:pdFrEIfaPl24zmBjerWTTYaY0M6UHsqA1YSvsoU40MI=
+github.com/testcontainers/testcontainers-go/modules/postgres v0.41.0 h1:AOtFXssrDlLm84A2sTTR/AhvJiYbrIuCO59d+Ro9Tb0=
+github.com/testcontainers/testcontainers-go/modules/postgres v0.41.0/go.mod h1:k2a09UKhgSp6vNpliIY0QSgm4Hi7GXVTzWvWgUemu/8=
+github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYICU0nA=
+github.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI=
+github.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw=
+github.com/tklauser/numcpus v0.11.0/go.mod h1:z+LwcLq54uWZTX0u/bGobaV34u6V7KNlTZejzM6/3MQ=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
 github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
+github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
+github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 h1:jq9TW8u3so/bN+JPT166wjOI6/vQPF6Xe7nMNIltagk=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0/go.mod h1:p8pYQP+m5XfbZm9fxtSKAbM6oIllS7s2AfxrChvc7iw=
+go.opentelemetry.io/otel v1.41.0 h1:YlEwVsGAlCvczDILpUXpIpPSL/VPugt7zHThEMLce1c=
+go.opentelemetry.io/otel v1.41.0/go.mod h1:Yt4UwgEKeT05QbLwbyHXEwhnjxNO6D8L5PQP51/46dE=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.19.0 h1:Mne5On7VWdx7omSrSSZvM4Kw7cS7NQkOOmLcgscI51U=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.19.0/go.mod h1:IPtUMKL4O3tH5y+iXVyAXqpAwMuzC1IrxVS81rummfE=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.41.0 h1:inYW9ZhgqiDqh6BioM7DVHHzEGVq76Db5897WLGZ5Go=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.41.0/go.mod h1:Izur+Wt8gClgMJqO/cZ8wdeeMryJ/xxiOVgFSSfpDTY=
+go.opentelemetry.io/otel/metric v1.41.0 h1:rFnDcs4gRzBcsO9tS8LCpgR0dxg4aaxWlJxCno7JlTQ=
+go.opentelemetry.io/otel/metric v1.41.0/go.mod h1:xPvCwd9pU0VN8tPZYzDZV/BMj9CM9vs00GuBjeKhJps=
+go.opentelemetry.io/otel/sdk v1.41.0 h1:YPIEXKmiAwkGl3Gu1huk1aYWwtpRLeskpV+wPisxBp8=
+go.opentelemetry.io/otel/sdk v1.41.0/go.mod h1:ahFdU0G5y8IxglBf0QBJXgSe7agzjE4GiTJ6HT9ud90=
+go.opentelemetry.io/otel/trace v1.41.0 h1:Vbk2co6bhj8L59ZJ6/xFTskY+tGAbOnCtQGVVa9TIN0=
+go.opentelemetry.io/otel/trace v1.41.0/go.mod h1:U1NU4ULCoxeDKc09yCWdWe+3QoyweJcISEVa1RBzOis=
+go.opentelemetry.io/proto/otlp v1.0.0 h1:T0TX0tmXU8a3CbNXzEKGeU5mIVOdf0oykP+u2lIVU/I=
+go.opentelemetry.io/proto/otlp v1.0.0/go.mod h1:Sy6pihPLfYHkr3NkUbEhGHFhINUSI/v80hjKIs5JXpM=
 go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
 go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
 golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
 golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
-golang.org/x/crypto v0.39.0 h1:SHs+kF4LP+f+p14esP5jAoDpHU8Gu/v9lFRK6IT5imM=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
-golang.org/x/crypto v0.39.0/go.mod h1:L+Xg3Wf6HoL4Bn4238Z6ft6KfEpN0tJGo53AAPC632U=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
 golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8 h1:hVwzHzIUGRjiF7EcUjqNxk3NCfkPxbDKRdnNE1Rpg0U=
 golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8/go.mod h1:FeLwcggjj3mMvU+oOTbSwawSJRM1uh48EjtB4UJZlP0=
-golang.org/x/net v0.33.0 h1:74SYHlV8BIgHIFC/LrYkOGIwL19eTYXQ5wc6TBuO36I=
+golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
-golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
+golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
 golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
 golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
 golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/term v0.40.0 h1:36e4zGLqU4yhjlmxEaagx2KuYbJq3EwY8K943ZsHcvg=
+golang.org/x/term v0.40.0/go.mod h1:w2P8uVp06p2iyKKuvXIm7N/y0UCRt3UfJTfZ7oOpglM=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
 golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+golang.org/x/time v0.0.0-20220210224613-90d013bbcef8 h1:vVKdlvoWBphwdxWKrFZEuM0kGgGLxUOYcY4U/2Vjg44=
+golang.org/x/time v0.0.0-20220210224613-90d013bbcef8/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/genproto/googleapis/api v0.0.0-20260209200024-4cfbd4190f57 h1:JLQynH/LBHfCTSbDWl+py8C+Rg/k1OVH3xfcaiANuF0=
+google.golang.org/genproto/googleapis/api v0.0.0-20260209200024-4cfbd4190f57/go.mod h1:kSJwQxqmFXeo79zOmbrALdflXQeAYcUbgS7PbpMknCY=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260209200024-4cfbd4190f57 h1:mWPCjDEyshlQYzBpMNHaEof6UX1PmHcaUODUywQ0uac=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260209200024-4cfbd4190f57/go.mod h1:j9x/tPzZkyxcgEFkiKEEGxfvyumM01BEtsW8xzOahRQ=
+google.golang.org/grpc v1.79.1 h1:zGhSi45ODB9/p3VAawt9a+O/MULLl9dpizzNNpq7flY=
+google.golang.org/grpc v1.79.1/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
@@ -125,6 +257,8 @@ gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EV
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
+gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
 modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6 h1:5D53IMaUuA5InSeMu9eJtlQXS2NxAhyWQvkKEgXZhHI=
 modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6/go.mod h1:Qz0X07sNOR1jWYCrJMEnbW/X55x206Q7Vt4mz6/wHp4=
 modernc.org/libc v1.41.0 h1:g9YAc6BkKlgORsUWj+JwqoB1wU3o4DE3bM3yvA3k+Gk=

backend/internal/config/config.go

@@ -18,21 +18,40 @@ type Config struct {
 	JWTAccessTTL  time.Duration
 	JWTRefreshTTL time.Duration
 
+	// Initial admin bootstrap (applied on startup if the user does not exist)
+	AdminUsername string
+	AdminPassword string
+
 	// Database
 	DatabaseURL string
 
 	// Storage
 	FilesPath       string
 	ThumbsCachePath string
+	MaxUploadBytes  int64 // reject uploads larger than this (bytes)
 
 	// Thumbnails
 	ThumbWidth    int
 	ThumbHeight   int
 	PreviewWidth  int
 	PreviewHeight int
+	// ThumbMaxPixels caps the pixel count of a source image decoded in-process by
+	// the pure-Go fallback (a decompression-bomb guard and memory bound); larger
+	// images then get a placeholder. It does not apply when vipsthumbnail is
+	// installed, which shrinks on load regardless of source size.
+	ThumbMaxPixels int
+	// ThumbConcurrency bounds how many thumbnails/previews are generated at once,
+	// so a burst of large images can't saturate every core or exhaust RAM. 0 =
+	// auto (half the available CPUs).
+	ThumbConcurrency int
 
 	// Import
 	ImportPath string
+
+	// Static SPA. When set, the server serves the built frontend (and falls
+	// back to index.html for client routes) on the same port as the API. Empty
+	// in local development, where the Vite dev server serves the UI separately.
+	StaticDir string
 }
 
 // Load reads a .env file (if present) then loads all configuration from
@@ -81,23 +100,44 @@ func Load() (*Config, error) {
 		return n
 	}
 
+	parseInt64 := func(key string, def int64) int64 {
+		raw := os.Getenv(key)
+		if raw == "" {
+			return def
+		}
+		n, err := strconv.ParseInt(raw, 10, 64)
+		if err != nil {
+			errs = append(errs, fmt.Errorf("%s: invalid integer %q: %w", key, raw, err))
+			return def
+		}
+		return n
+	}
+
 	cfg := &Config{
-		ListenAddr:    defaultStr("LISTEN_ADDR", ":8080"),
+		ListenAddr:    defaultStr("LISTEN_ADDR", ":42776"),
 		JWTSecret:     requireStr("JWT_SECRET"),
 		JWTAccessTTL:  parseDuration("JWT_ACCESS_TTL", "15m"),
 		JWTRefreshTTL: parseDuration("JWT_REFRESH_TTL", "720h"),
 
+		AdminUsername: defaultStr("ADMIN_USERNAME", "admin"),
+		AdminPassword: requireStr("ADMIN_PASSWORD"),
+
 		DatabaseURL: requireStr("DATABASE_URL"),
 
 		FilesPath:       requireStr("FILES_PATH"),
 		ThumbsCachePath: requireStr("THUMBS_CACHE_PATH"),
+		MaxUploadBytes:  parseInt64("MAX_UPLOAD_BYTES", 500<<20), // 500 MiB
 
 		ThumbWidth:       parseInt("THUMB_WIDTH", 160),
 		ThumbHeight:      parseInt("THUMB_HEIGHT", 160),
 		PreviewWidth:     parseInt("PREVIEW_WIDTH", 1920),
 		PreviewHeight:    parseInt("PREVIEW_HEIGHT", 1080),
+		ThumbMaxPixels:   parseInt("THUMB_MAX_PIXELS", 300_000_000), // ~300 Mpx (e.g. 13000×17000)
+		ThumbConcurrency: parseInt("THUMB_CONCURRENCY", 0),          // 0 = auto
 
 		ImportPath: requireStr("IMPORT_PATH"),
+
+		StaticDir: defaultStr("STATIC_DIR", ""),
 	}
 
 	if len(errs) > 0 {

backend/internal/db/postgres/category_repo.go

@@ -0,0 +1,303 @@
+package postgres
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+)
+
+// ---------------------------------------------------------------------------
+// Row struct
+// ---------------------------------------------------------------------------
+
+type categoryRow struct {
+	ID          uuid.UUID `db:"id"`
+	Name        string    `db:"name"`
+	Notes       *string   `db:"notes"`
+	Color       *string   `db:"color"`
+	Metadata    []byte    `db:"metadata"`
+	CreatorID   int16     `db:"creator_id"`
+	CreatorName string    `db:"creator_name"`
+	IsPublic    bool      `db:"is_public"`
+}
+
+type categoryRowWithTotal struct {
+	categoryRow
+	Total int `db:"total"`
+}
+
+// ---------------------------------------------------------------------------
+// Converter
+// ---------------------------------------------------------------------------
+
+func toCategory(r categoryRow) domain.Category {
+	c := domain.Category{
+		ID:          r.ID,
+		Name:        r.Name,
+		Notes:       r.Notes,
+		Color:       r.Color,
+		CreatorID:   r.CreatorID,
+		CreatorName: r.CreatorName,
+		IsPublic:    r.IsPublic,
+		CreatedAt:   domain.UUIDCreatedAt(r.ID),
+	}
+	if len(r.Metadata) > 0 && string(r.Metadata) != "null" {
+		c.Metadata = json.RawMessage(r.Metadata)
+	}
+	return c
+}
+
+// ---------------------------------------------------------------------------
+// Shared SQL
+// ---------------------------------------------------------------------------
+
+const categorySelectFrom = `
+SELECT
+    c.id,
+    c.name,
+    c.notes,
+    c.color,
+    c.metadata,
+    c.creator_id,
+    u.name AS creator_name,
+    c.is_public
+FROM data.categories c
+JOIN core.users u ON u.id = c.creator_id`
+
+func categorySortColumn(s string) string {
+	if s == "name" {
+		return "c.name"
+	}
+	return "c.id" // "created"
+}
+
+// ---------------------------------------------------------------------------
+// CategoryRepo — implements port.CategoryRepo
+// ---------------------------------------------------------------------------
+
+// CategoryRepo handles category CRUD using PostgreSQL.
+type CategoryRepo struct {
+	pool *pgxpool.Pool
+}
+
+var _ port.CategoryRepo = (*CategoryRepo)(nil)
+
+// NewCategoryRepo creates a CategoryRepo backed by pool.
+func NewCategoryRepo(pool *pgxpool.Pool) *CategoryRepo {
+	return &CategoryRepo{pool: pool}
+}
+
+// ---------------------------------------------------------------------------
+// List
+// ---------------------------------------------------------------------------
+
+func (r *CategoryRepo) List(ctx context.Context, params port.OffsetParams) (*domain.CategoryOffsetPage, error) {
+	order := "ASC"
+	if strings.ToLower(params.Order) == "desc" {
+		order = "DESC"
+	}
+	sortCol := categorySortColumn(params.Sort)
+
+	args := []any{}
+	n := 1
+	var conditions []string
+
+	if params.Search != "" {
+		conditions = append(conditions, fmt.Sprintf("lower(c.name) LIKE lower($%d)", n))
+		args = append(args, "%"+params.Search+"%")
+		n++
+	}
+	// Restrict to categories the viewer may see (private-by-default), unless admin.
+	if !params.ViewerIsAdmin {
+		var aclCond string
+		aclCond, n, args = aclVisibilityCond("c", objTypeCategory, params.ViewerID, n, args)
+		conditions = append(conditions, aclCond)
+	}
+
+	where := ""
+	if len(conditions) > 0 {
+		where = "WHERE " + strings.Join(conditions, " AND ")
+	}
+
+	limit := params.Limit
+	if limit <= 0 {
+		limit = 50
+	}
+	offset := params.Offset
+	if offset < 0 {
+		offset = 0
+	}
+
+	query := fmt.Sprintf(`
+SELECT
+    c.id, c.name, c.notes, c.color, c.metadata,
+    c.creator_id, u.name AS creator_name, c.is_public,
+    COUNT(*) OVER() AS total
+FROM data.categories c
+JOIN core.users u ON u.id = c.creator_id
+%s
+ORDER BY %s %s NULLS LAST, c.id ASC
+LIMIT $%d OFFSET $%d`, where, sortCol, order, n, n+1)
+
+	args = append(args, limit, offset)
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, args...)
+	if err != nil {
+		return nil, fmt.Errorf("CategoryRepo.List query: %w", err)
+	}
+	collected, err := pgx.CollectRows(rows, pgx.RowToStructByName[categoryRowWithTotal])
+	if err != nil {
+		return nil, fmt.Errorf("CategoryRepo.List scan: %w", err)
+	}
+
+	items := make([]domain.Category, len(collected))
+	total := 0
+	for i, row := range collected {
+		items[i] = toCategory(row.categoryRow)
+		total = row.Total
+	}
+	return &domain.CategoryOffsetPage{
+		Items:  items,
+		Total:  total,
+		Offset: offset,
+		Limit:  limit,
+	}, nil
+}
+
+// ---------------------------------------------------------------------------
+// GetByID
+// ---------------------------------------------------------------------------
+
+func (r *CategoryRepo) GetByID(ctx context.Context, id uuid.UUID) (*domain.Category, error) {
+	const query = categorySelectFrom + `
+WHERE c.id = $1`
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, id)
+	if err != nil {
+		return nil, fmt.Errorf("CategoryRepo.GetByID: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[categoryRow])
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, domain.ErrNotFound
+		}
+		return nil, fmt.Errorf("CategoryRepo.GetByID scan: %w", err)
+	}
+	c := toCategory(row)
+	return &c, nil
+}
+
+// ---------------------------------------------------------------------------
+// Create
+// ---------------------------------------------------------------------------
+
+func (r *CategoryRepo) Create(ctx context.Context, c *domain.Category) (*domain.Category, error) {
+	const query = `
+WITH ins AS (
+    INSERT INTO data.categories (name, notes, color, metadata, creator_id, is_public)
+    VALUES ($1, $2, $3, $4, $5, $6)
+    RETURNING *
+)
+SELECT ins.id, ins.name, ins.notes, ins.color, ins.metadata,
+       ins.creator_id, u.name AS creator_name, ins.is_public
+FROM ins
+JOIN core.users u ON u.id = ins.creator_id`
+
+	var meta any
+	if len(c.Metadata) > 0 {
+		meta = c.Metadata
+	}
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query,
+		c.Name, c.Notes, c.Color, meta, c.CreatorID, c.IsPublic)
+	if err != nil {
+		return nil, fmt.Errorf("CategoryRepo.Create: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[categoryRow])
+	if err != nil {
+		if isPgUniqueViolation(err) {
+			return nil, domain.ErrConflict
+		}
+		return nil, fmt.Errorf("CategoryRepo.Create scan: %w", err)
+	}
+	created := toCategory(row)
+	return &created, nil
+}
+
+// ---------------------------------------------------------------------------
+// Update
+// ---------------------------------------------------------------------------
+
+// Update replaces all mutable fields. The caller must merge current values
+// with the patch before calling (read-then-write semantics).
+func (r *CategoryRepo) Update(ctx context.Context, id uuid.UUID, c *domain.Category) (*domain.Category, error) {
+	const query = `
+WITH upd AS (
+    UPDATE data.categories SET
+        name      = $2,
+        notes     = $3,
+        color     = $4,
+        metadata  = COALESCE($5, metadata),
+        is_public = $6
+    WHERE id = $1
+    RETURNING *
+)
+SELECT upd.id, upd.name, upd.notes, upd.color, upd.metadata,
+       upd.creator_id, u.name AS creator_name, upd.is_public
+FROM upd
+JOIN core.users u ON u.id = upd.creator_id`
+
+	var meta any
+	if len(c.Metadata) > 0 {
+		meta = c.Metadata
+	}
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query,
+		id, c.Name, c.Notes, c.Color, meta, c.IsPublic)
+	if err != nil {
+		return nil, fmt.Errorf("CategoryRepo.Update: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[categoryRow])
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, domain.ErrNotFound
+		}
+		if isPgUniqueViolation(err) {
+			return nil, domain.ErrConflict
+		}
+		return nil, fmt.Errorf("CategoryRepo.Update scan: %w", err)
+	}
+	updated := toCategory(row)
+	return &updated, nil
+}
+
+// ---------------------------------------------------------------------------
+// Delete
+// ---------------------------------------------------------------------------
+
+func (r *CategoryRepo) Delete(ctx context.Context, id uuid.UUID) error {
+	const query = `DELETE FROM data.categories WHERE id = $1`
+
+	q := connOrTx(ctx, r.pool)
+	ct, err := q.Exec(ctx, query, id)
+	if err != nil {
+		return fmt.Errorf("CategoryRepo.Delete: %w", err)
+	}
+	if ct.RowsAffected() == 0 {
+		return domain.ErrNotFound
+	}
+	return nil
+}

backend/internal/db/postgres/file_repo.go

@@ -302,17 +302,18 @@ const fileSelectCTE = `
 // Create
 // ---------------------------------------------------------------------------
 
-// Create inserts a new file record. The MIME type is resolved from
+// Create inserts a new file record using the ID already set on f.
-// f.MIMEType (name string) via a subquery; the DB generates the UUID v7 id.
+// The MIME type is resolved from f.MIMEType (name string) via a subquery.
 func (r *FileRepo) Create(ctx context.Context, f *domain.File) (*domain.File, error) {
 	const sqlStr = `
         WITH r AS (
             INSERT INTO data.files
-                (original_name, mime_id, content_datetime, notes, metadata, exif, phash, creator_id, is_public)
+                (id, original_name, mime_id, content_datetime, notes, metadata, exif, phash, creator_id, is_public)
             VALUES (
                 $1,
-                (SELECT id FROM core.mime_types WHERE name = $2),
+                $2,
-                $3, $4, $5, $6, $7, $8, $9
+                (SELECT id FROM core.mime_types WHERE name = $3),
+                $4, $5, $6, $7, $8, $9, $10
             )
             RETURNING id, original_name, mime_id, content_datetime, notes,
                       metadata, exif, phash, creator_id, is_public, is_deleted
@@ -320,7 +321,7 @@ func (r *FileRepo) Create(ctx context.Context, f *domain.File) (*domain.File, er
 
 	q := connOrTx(ctx, r.pool)
 	rows, err := q.Query(ctx, sqlStr,
-		f.OriginalName, f.MIMEType, f.ContentDatetime,
+		f.ID, f.OriginalName, f.MIMEType, f.ContentDatetime,
 		f.Notes, f.Metadata, f.EXIF, f.PHash,
 		f.CreatorID, f.IsPublic,
 	)
@@ -606,6 +607,13 @@ func (r *FileRepo) List(ctx context.Context, params domain.FileListParams) (*dom
 		}
 	}
 
+	// Restrict to files the viewer may see (private-by-default), unless admin.
+	if !params.ViewerIsAdmin {
+		var aclCond string
+		aclCond, n, args = aclVisibilityCond("f", objTypeFile, params.ViewerID, n, args)
+		conds = append(conds, aclCond)
+	}
+
 	var orderBy string
 	if hasCursor {
 		ksWhere, ksOrder, nextN, ksArgs := buildKeysetCond(
@@ -793,3 +801,43 @@ func (r *FileRepo) loadTagsBatch(ctx context.Context, fileIDs []uuid.UUID) (map[
 	}
 	return result, nil
 }
+
+// RecordView appends a row to activity.file_views. viewed_at defaults to
+// statement_timestamp(), so each call records a distinct view in the history.
+func (r *FileRepo) RecordView(ctx context.Context, fileID uuid.UUID, userID int16) error {
+	const query = `INSERT INTO activity.file_views (file_id, user_id) VALUES ($1, $2)`
+	if _, err := connOrTx(ctx, r.pool).Exec(ctx, query, fileID, userID); err != nil {
+		return fmt.Errorf("FileRepo.RecordView: %w", err)
+	}
+	return nil
+}
+
+// RecordTagUses appends a row to activity.tag_uses for each tag referenced in a
+// filter DSL, flagging it included (positive) or excluded (negated). Tags are
+// deduplicated per call, so one statement_timestamp() never collides on the
+// (tag_id, used_at, user_id) PK; ON CONFLICT DO NOTHING guards the rest. A
+// filter with no tag terms is a no-op.
+func (r *FileRepo) RecordTagUses(ctx context.Context, userID int16, filterDSL string) error {
+	uses := filterTagUses(filterDSL)
+	if len(uses) == 0 {
+		return nil
+	}
+
+	var sb strings.Builder
+	sb.WriteString("INSERT INTO activity.tag_uses (tag_id, user_id, is_included) VALUES ")
+	args := make([]any, 0, len(uses)*3)
+	for i, u := range uses {
+		if i > 0 {
+			sb.WriteString(", ")
+		}
+		base := i * 3
+		fmt.Fprintf(&sb, "($%d, $%d, $%d)", base+1, base+2, base+3)
+		args = append(args, u.tagID, userID, u.included)
+	}
+	sb.WriteString(" ON CONFLICT DO NOTHING")
+
+	if _, err := connOrTx(ctx, r.pool).Exec(ctx, sb.String(), args...); err != nil {
+		return fmt.Errorf("FileRepo.RecordTagUses: %w", err)
+	}
+	return nil
+}

backend/internal/db/postgres/filter_parser.go

@@ -253,6 +253,31 @@ func (p *filterParser) parseAtom() (filterNode, error) {
 // Public entry point
 // ---------------------------------------------------------------------------
 
+// parseFilterAST lexes and parses a filter DSL into an AST. Returns (nil, nil)
+// for an empty or trivial DSL.
+func parseFilterAST(dsl string) (filterNode, error) {
+	dsl = strings.TrimSpace(dsl)
+	if dsl == "" || dsl == "{}" {
+		return nil, nil
+	}
+	toks, err := lexFilter(dsl)
+	if err != nil {
+		return nil, err
+	}
+	if len(toks) == 0 {
+		return nil, nil
+	}
+	p := &filterParser{tokens: toks}
+	node, err := p.parseExpr()
+	if err != nil {
+		return nil, err
+	}
+	if p.pos != len(p.tokens) {
+		return nil, fmt.Errorf("filter: trailing tokens at position %d", p.pos)
+	}
+	return node, nil
+}
+
 // ParseFilter parses a filter DSL string into a parameterized SQL fragment.
 //
 // argStart is the 1-based index for the first $N placeholder; this lets the
@@ -262,25 +287,62 @@ func (p *filterParser) parseAtom() (filterNode, error) {
 // SQL injection is structurally impossible: every user-supplied value is
 // bound as a query parameter ($N), never interpolated into the SQL string.
 func ParseFilter(dsl string, argStart int) (sql string, nextN int, args []any, err error) {
-	dsl = strings.TrimSpace(dsl)
+	node, err := parseFilterAST(dsl)
-	if dsl == "" || dsl == "{}" {
-		return "", argStart, nil, nil
-	}
-	toks, err := lexFilter(dsl)
 	if err != nil {
 		return "", argStart, nil, err
 	}
-	if len(toks) == 0 {
+	if node == nil {
 		return "", argStart, nil, nil
 	}
-	p := &filterParser{tokens: toks}
-	node, err := p.parseExpr()
-	if err != nil {
-		return "", argStart, nil, err
-	}
-	if p.pos != len(p.tokens) {
-		return "", argStart, nil, fmt.Errorf("filter: trailing tokens at position %d", p.pos)
-	}
 	sql, nextN, args = node.toSQL(argStart, nil)
 	return sql, nextN, args, nil
 }
+
+// tagUse is a tag referenced by a filter, with whether it was included
+// (positive) or excluded (negated under an odd number of NOTs).
+type tagUse struct {
+	tagID    uuid.UUID
+	included bool
+}
+
+// filterTagUses extracts the distinct tag references in a filter DSL, marking
+// each as included or excluded. The "untagged" pseudo-token (zero UUID) is
+// skipped. Returns nil for a filter with no tag terms; an unparseable filter
+// also yields nil (extraction is best-effort analytics, not validation).
+func filterTagUses(dsl string) []tagUse {
+	node, err := parseFilterAST(dsl)
+	if err != nil || node == nil {
+		return nil
+	}
+	seen := make(map[uuid.UUID]bool)
+	collectTagUses(node, true, seen)
+	if len(seen) == 0 {
+		return nil
+	}
+	uses := make([]tagUse, 0, len(seen))
+	for id, inc := range seen {
+		uses = append(uses, tagUse{tagID: id, included: inc})
+	}
+	return uses
+}
+
+// collectTagUses walks the AST, recording each real tag leaf into out keyed by
+// id. included flips under every NOT, so a tag is "excluded" only when nested
+// under an odd number of NOTs. A tag appearing under both polarities keeps the
+// last seen — pathological, but it avoids a duplicate-key insert.
+func collectTagUses(node filterNode, included bool, out map[uuid.UUID]bool) {
+	switch nd := node.(type) {
+	case *andNode:
+		collectTagUses(nd.left, included, out)
+		collectTagUses(nd.right, included, out)
+	case *orNode:
+		collectTagUses(nd.left, included, out)
+		collectTagUses(nd.right, included, out)
+	case *notNode:
+		collectTagUses(nd.child, !included, out)
+	case *leafNode:
+		if nd.tok.kind == ftkTag && !nd.tok.untagged {
+			out[nd.tok.tagID] = included
+		}
+	}
+}

backend/internal/db/postgres/filter_parser_test.go

@@ -0,0 +1,53 @@
+package postgres
+
+import (
+	"testing"
+
+	"github.com/google/uuid"
+)
+
+func TestFilterTagUses(t *testing.T) {
+	a := uuid.MustParse("11111111-1111-1111-1111-111111111111")
+	b := uuid.MustParse("22222222-2222-2222-2222-222222222222")
+
+	tests := []struct {
+		name string
+		dsl  string
+		want map[uuid.UUID]bool // tag → included; absence means "not recorded"
+	}{
+		{"single included", "{t=" + a.String() + "}", map[uuid.UUID]bool{a: true}},
+		{"single excluded", "{!,t=" + a.String() + "}", map[uuid.UUID]bool{a: false}},
+		{"double negation is included", "{!,!,t=" + a.String() + "}", map[uuid.UUID]bool{a: true}},
+		{
+			"and of two included",
+			"{t=" + a.String() + ",&,t=" + b.String() + "}",
+			map[uuid.UUID]bool{a: true, b: true},
+		},
+		{
+			"not over a group excludes both",
+			"{!,(,t=" + a.String() + ",|,t=" + b.String() + ",)}",
+			map[uuid.UUID]bool{a: false, b: false},
+		},
+		{"untagged pseudo-token skipped", "{t=" + uuid.Nil.String() + "}", map[uuid.UUID]bool{}},
+		{"mime-only filter records nothing", "{m=3}", map[uuid.UUID]bool{}},
+		{"empty filter", "{}", map[uuid.UUID]bool{}},
+		{"unparseable filter is best-effort nil", "{t=not-a-uuid}", map[uuid.UUID]bool{}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := make(map[uuid.UUID]bool)
+			for _, u := range filterTagUses(tc.dsl) {
+				got[u.tagID] = u.included
+			}
+			if len(got) != len(tc.want) {
+				t.Fatalf("got %d uses %v, want %d %v", len(got), got, len(tc.want), tc.want)
+			}
+			for id, inc := range tc.want {
+				if g, ok := got[id]; !ok || g != inc {
+					t.Errorf("tag %s: got (included=%v, present=%v), want included=%v", id, g, ok, inc)
+				}
+			}
+		})
+	}
+}

backend/internal/db/postgres/pool_repo.go

@@ -0,0 +1,725 @@
+package postgres
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"tanabata/backend/internal/db"
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+)
+
+// ---------------------------------------------------------------------------
+// Row structs
+// ---------------------------------------------------------------------------
+
+type poolRow struct {
+	ID          uuid.UUID `db:"id"`
+	Name        string    `db:"name"`
+	Notes       *string   `db:"notes"`
+	Metadata    []byte    `db:"metadata"`
+	CreatorID   int16     `db:"creator_id"`
+	CreatorName string    `db:"creator_name"`
+	IsPublic    bool      `db:"is_public"`
+	FileCount   int       `db:"file_count"`
+}
+
+type poolRowWithTotal struct {
+	poolRow
+	Total int `db:"total"`
+}
+
+// poolFileRow is a flat struct combining all file columns plus pool position.
+type poolFileRow struct {
+	ID              uuid.UUID       `db:"id"`
+	OriginalName    *string         `db:"original_name"`
+	MIMEType        string          `db:"mime_type"`
+	MIMEExtension   string          `db:"mime_extension"`
+	ContentDatetime time.Time       `db:"content_datetime"`
+	Notes           *string         `db:"notes"`
+	Metadata        json.RawMessage `db:"metadata"`
+	EXIF            json.RawMessage `db:"exif"`
+	PHash           *int64          `db:"phash"`
+	CreatorID       int16           `db:"creator_id"`
+	CreatorName     string          `db:"creator_name"`
+	IsPublic        bool            `db:"is_public"`
+	IsDeleted       bool            `db:"is_deleted"`
+	Position        int             `db:"position"`
+}
+
+// ---------------------------------------------------------------------------
+// Converters
+// ---------------------------------------------------------------------------
+
+func toPool(r poolRow) domain.Pool {
+	p := domain.Pool{
+		ID:          r.ID,
+		Name:        r.Name,
+		Notes:       r.Notes,
+		CreatorID:   r.CreatorID,
+		CreatorName: r.CreatorName,
+		IsPublic:    r.IsPublic,
+		FileCount:   r.FileCount,
+		CreatedAt:   domain.UUIDCreatedAt(r.ID),
+	}
+	if len(r.Metadata) > 0 && string(r.Metadata) != "null" {
+		p.Metadata = json.RawMessage(r.Metadata)
+	}
+	return p
+}
+
+func toPoolFile(r poolFileRow) domain.PoolFile {
+	return domain.PoolFile{
+		File: domain.File{
+			ID:              r.ID,
+			OriginalName:    r.OriginalName,
+			MIMEType:        r.MIMEType,
+			MIMEExtension:   r.MIMEExtension,
+			ContentDatetime: r.ContentDatetime,
+			Notes:           r.Notes,
+			Metadata:        r.Metadata,
+			EXIF:            r.EXIF,
+			PHash:           r.PHash,
+			CreatorID:       r.CreatorID,
+			CreatorName:     r.CreatorName,
+			IsPublic:        r.IsPublic,
+			IsDeleted:       r.IsDeleted,
+			CreatedAt:       domain.UUIDCreatedAt(r.ID),
+		},
+		Position: r.Position,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Cursor
+// ---------------------------------------------------------------------------
+
+type poolFileCursor struct {
+	Position int    `json:"p"`
+	FileID   string `json:"id"`
+}
+
+func encodePoolCursor(c poolFileCursor) string {
+	b, _ := json.Marshal(c)
+	return base64.RawURLEncoding.EncodeToString(b)
+}
+
+func decodePoolCursor(s string) (poolFileCursor, error) {
+	b, err := base64.RawURLEncoding.DecodeString(s)
+	if err != nil {
+		return poolFileCursor{}, fmt.Errorf("cursor: invalid encoding")
+	}
+	var c poolFileCursor
+	if err := json.Unmarshal(b, &c); err != nil {
+		return poolFileCursor{}, fmt.Errorf("cursor: invalid format")
+	}
+	return c, nil
+}
+
+// ---------------------------------------------------------------------------
+// Shared SQL
+// ---------------------------------------------------------------------------
+
+// poolCountSubquery computes per-pool file counts.
+const poolCountSubquery = `(SELECT pool_id, COUNT(*) AS cnt FROM data.file_pool GROUP BY pool_id)`
+
+const poolSelectFrom = `
+SELECT p.id, p.name, p.notes, p.metadata,
+       p.creator_id, u.name AS creator_name, p.is_public,
+       COALESCE(fc.cnt, 0) AS file_count
+FROM data.pools p
+JOIN core.users u ON u.id = p.creator_id
+LEFT JOIN ` + poolCountSubquery + ` fc ON fc.pool_id = p.id`
+
+func poolSortColumn(s string) string {
+	if s == "name" {
+		return "p.name"
+	}
+	return "p.id" // "created"
+}
+
+// ---------------------------------------------------------------------------
+// PoolRepo
+// ---------------------------------------------------------------------------
+
+// PoolRepo implements port.PoolRepo using PostgreSQL.
+type PoolRepo struct {
+	pool *pgxpool.Pool
+}
+
+var _ port.PoolRepo = (*PoolRepo)(nil)
+
+// NewPoolRepo creates a PoolRepo backed by pool.
+func NewPoolRepo(pool *pgxpool.Pool) *PoolRepo {
+	return &PoolRepo{pool: pool}
+}
+
+// ---------------------------------------------------------------------------
+// List
+// ---------------------------------------------------------------------------
+
+func (r *PoolRepo) List(ctx context.Context, params port.OffsetParams) (*domain.PoolOffsetPage, error) {
+	order := "ASC"
+	if strings.ToLower(params.Order) == "desc" {
+		order = "DESC"
+	}
+	sortCol := poolSortColumn(params.Sort)
+
+	args := []any{}
+	n := 1
+	var conditions []string
+
+	if params.Search != "" {
+		conditions = append(conditions, fmt.Sprintf("lower(p.name) LIKE lower($%d)", n))
+		args = append(args, "%"+params.Search+"%")
+		n++
+	}
+	// Restrict to pools the viewer may see (private-by-default), unless admin.
+	if !params.ViewerIsAdmin {
+		var aclCond string
+		aclCond, n, args = aclVisibilityCond("p", objTypePool, params.ViewerID, n, args)
+		conditions = append(conditions, aclCond)
+	}
+
+	where := ""
+	if len(conditions) > 0 {
+		where = "WHERE " + strings.Join(conditions, " AND ")
+	}
+
+	limit := params.Limit
+	if limit <= 0 {
+		limit = 50
+	}
+	offset := params.Offset
+	if offset < 0 {
+		offset = 0
+	}
+
+	query := fmt.Sprintf(`
+SELECT p.id, p.name, p.notes, p.metadata,
+       p.creator_id, u.name AS creator_name, p.is_public,
+       COALESCE(fc.cnt, 0) AS file_count,
+       COUNT(*) OVER() AS total
+FROM data.pools p
+JOIN core.users u ON u.id = p.creator_id
+LEFT JOIN %s fc ON fc.pool_id = p.id
+%s
+ORDER BY %s %s NULLS LAST, p.id ASC
+LIMIT $%d OFFSET $%d`, poolCountSubquery, where, sortCol, order, n, n+1)
+
+	args = append(args, limit, offset)
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, args...)
+	if err != nil {
+		return nil, fmt.Errorf("PoolRepo.List query: %w", err)
+	}
+	collected, err := pgx.CollectRows(rows, pgx.RowToStructByName[poolRowWithTotal])
+	if err != nil {
+		return nil, fmt.Errorf("PoolRepo.List scan: %w", err)
+	}
+
+	items := make([]domain.Pool, len(collected))
+	total := 0
+	for i, row := range collected {
+		items[i] = toPool(row.poolRow)
+		total = row.Total
+	}
+	return &domain.PoolOffsetPage{
+		Items:  items,
+		Total:  total,
+		Offset: offset,
+		Limit:  limit,
+	}, nil
+}
+
+// ---------------------------------------------------------------------------
+// GetByID
+// ---------------------------------------------------------------------------
+
+func (r *PoolRepo) GetByID(ctx context.Context, id uuid.UUID) (*domain.Pool, error) {
+	query := poolSelectFrom + `
+WHERE p.id = $1`
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, id)
+	if err != nil {
+		return nil, fmt.Errorf("PoolRepo.GetByID: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[poolRow])
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, domain.ErrNotFound
+		}
+		return nil, fmt.Errorf("PoolRepo.GetByID scan: %w", err)
+	}
+	p := toPool(row)
+	return &p, nil
+}
+
+// RecordView appends a row to activity.pool_views. viewed_at defaults to
+// statement_timestamp(), so each call records a distinct view in the history.
+func (r *PoolRepo) RecordView(ctx context.Context, poolID uuid.UUID, userID int16) error {
+	const query = `INSERT INTO activity.pool_views (pool_id, user_id) VALUES ($1, $2)`
+	if _, err := connOrTx(ctx, r.pool).Exec(ctx, query, poolID, userID); err != nil {
+		return fmt.Errorf("PoolRepo.RecordView: %w", err)
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Create
+// ---------------------------------------------------------------------------
+
+func (r *PoolRepo) Create(ctx context.Context, p *domain.Pool) (*domain.Pool, error) {
+	const query = `
+WITH ins AS (
+    INSERT INTO data.pools (name, notes, metadata, creator_id, is_public)
+    VALUES ($1, $2, $3, $4, $5)
+    RETURNING *
+)
+SELECT ins.id, ins.name, ins.notes, ins.metadata,
+       ins.creator_id, u.name AS creator_name, ins.is_public,
+       0 AS file_count
+FROM ins
+JOIN core.users u ON u.id = ins.creator_id`
+
+	var meta any
+	if len(p.Metadata) > 0 {
+		meta = p.Metadata
+	}
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, p.Name, p.Notes, meta, p.CreatorID, p.IsPublic)
+	if err != nil {
+		return nil, fmt.Errorf("PoolRepo.Create: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[poolRow])
+	if err != nil {
+		if isPgUniqueViolation(err) {
+			return nil, domain.ErrConflict
+		}
+		return nil, fmt.Errorf("PoolRepo.Create scan: %w", err)
+	}
+	created := toPool(row)
+	return &created, nil
+}
+
+// ---------------------------------------------------------------------------
+// Update
+// ---------------------------------------------------------------------------
+
+func (r *PoolRepo) Update(ctx context.Context, id uuid.UUID, p *domain.Pool) (*domain.Pool, error) {
+	const query = `
+WITH upd AS (
+    UPDATE data.pools SET
+        name      = $2,
+        notes     = $3,
+        metadata  = COALESCE($4, metadata),
+        is_public = $5
+    WHERE id = $1
+    RETURNING *
+)
+SELECT upd.id, upd.name, upd.notes, upd.metadata,
+       upd.creator_id, u.name AS creator_name, upd.is_public,
+       COALESCE(fc.cnt, 0) AS file_count
+FROM upd
+JOIN core.users u ON u.id = upd.creator_id
+LEFT JOIN (SELECT pool_id, COUNT(*) AS cnt FROM data.file_pool WHERE pool_id = $1 GROUP BY pool_id) fc
+    ON fc.pool_id = upd.id`
+
+	var meta any
+	if len(p.Metadata) > 0 {
+		meta = p.Metadata
+	}
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, id, p.Name, p.Notes, meta, p.IsPublic)
+	if err != nil {
+		return nil, fmt.Errorf("PoolRepo.Update: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[poolRow])
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, domain.ErrNotFound
+		}
+		if isPgUniqueViolation(err) {
+			return nil, domain.ErrConflict
+		}
+		return nil, fmt.Errorf("PoolRepo.Update scan: %w", err)
+	}
+	updated := toPool(row)
+	return &updated, nil
+}
+
+// ---------------------------------------------------------------------------
+// Delete
+// ---------------------------------------------------------------------------
+
+func (r *PoolRepo) Delete(ctx context.Context, id uuid.UUID) error {
+	const query = `DELETE FROM data.pools WHERE id = $1`
+	q := connOrTx(ctx, r.pool)
+	ct, err := q.Exec(ctx, query, id)
+	if err != nil {
+		return fmt.Errorf("PoolRepo.Delete: %w", err)
+	}
+	if ct.RowsAffected() == 0 {
+		return domain.ErrNotFound
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// ListFiles
+// ---------------------------------------------------------------------------
+
+// fileSelectForPool is the column list for pool file queries (without position).
+const fileSelectForPool = `
+    f.id, f.original_name,
+    mt.name AS mime_type, mt.extension AS mime_extension,
+    f.content_datetime, f.notes, f.metadata, f.exif, f.phash,
+    f.creator_id, u.name AS creator_name,
+    f.is_public, f.is_deleted`
+
+func (r *PoolRepo) ListFiles(ctx context.Context, poolID uuid.UUID, params port.PoolFileListParams) (*domain.PoolFilePage, error) {
+	limit := db.ClampLimit(params.Limit, 50, 200)
+
+	args := []any{poolID}
+	n := 2
+	var conds []string
+
+	conds = append(conds, "fp.pool_id = $1")
+	conds = append(conds, "f.is_deleted = false")
+
+	if params.Filter != "" {
+		filterSQL, nextN, filterArgs, err := ParseFilter(params.Filter, n)
+		if err != nil {
+			return nil, fmt.Errorf("%w: %v", domain.ErrValidation, err)
+		}
+		if filterSQL != "" {
+			conds = append(conds, filterSQL)
+			n = nextN
+			args = append(args, filterArgs...)
+		}
+	}
+
+	// Cursor condition.
+	var orderBy string
+	if params.Cursor != "" {
+		cur, err := decodePoolCursor(params.Cursor)
+		if err != nil {
+			return nil, fmt.Errorf("%w: %v", domain.ErrValidation, err)
+		}
+		fileID, err := uuid.Parse(cur.FileID)
+		if err != nil {
+			return nil, domain.ErrValidation
+		}
+		conds = append(conds, fmt.Sprintf(
+			"(fp.position > $%d OR (fp.position = $%d AND fp.file_id > $%d))",
+			n, n, n+1))
+		args = append(args, cur.Position, fileID)
+		n += 2
+	}
+	orderBy = "fp.position ASC, fp.file_id ASC"
+
+	where := "WHERE " + strings.Join(conds, " AND ")
+	args = append(args, limit+1)
+
+	sqlStr := fmt.Sprintf(`
+SELECT %s, fp.position
+FROM data.file_pool fp
+JOIN data.files f       ON f.id  = fp.file_id
+JOIN core.mime_types mt ON mt.id = f.mime_id
+JOIN core.users u       ON u.id  = f.creator_id
+%s
+ORDER BY %s
+LIMIT $%d`, fileSelectForPool, where, orderBy, n)
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, sqlStr, args...)
+	if err != nil {
+		return nil, fmt.Errorf("PoolRepo.ListFiles query: %w", err)
+	}
+	collected, err := pgx.CollectRows(rows, pgx.RowToStructByName[poolFileRow])
+	if err != nil {
+		return nil, fmt.Errorf("PoolRepo.ListFiles scan: %w", err)
+	}
+
+	hasMore := len(collected) > limit
+	if hasMore {
+		collected = collected[:limit]
+	}
+
+	items := make([]domain.PoolFile, len(collected))
+	for i, row := range collected {
+		items[i] = toPoolFile(row)
+	}
+
+	page := &domain.PoolFilePage{Items: items}
+
+	if hasMore && len(collected) > 0 {
+		last := collected[len(collected)-1]
+		cur := encodePoolCursor(poolFileCursor{
+			Position: last.Position,
+			FileID:   last.ID.String(),
+		})
+		page.NextCursor = &cur
+	}
+
+	// Batch-load tags.
+	if len(items) > 0 {
+		fileIDs := make([]uuid.UUID, len(items))
+		for i, pf := range items {
+			fileIDs[i] = pf.File.ID
+		}
+		tagMap, err := r.loadPoolTagsBatch(ctx, fileIDs)
+		if err != nil {
+			return nil, err
+		}
+		for i, pf := range items {
+			page.Items[i].File.Tags = tagMap[pf.File.ID]
+		}
+	}
+
+	return page, nil
+}
+
+// loadPoolTagsBatch re-uses the same pattern as FileRepo.loadTagsBatch.
+func (r *PoolRepo) loadPoolTagsBatch(ctx context.Context, fileIDs []uuid.UUID) (map[uuid.UUID][]domain.Tag, error) {
+	if len(fileIDs) == 0 {
+		return nil, nil
+	}
+	placeholders := make([]string, len(fileIDs))
+	args := make([]any, len(fileIDs))
+	for i, id := range fileIDs {
+		placeholders[i] = fmt.Sprintf("$%d", i+1)
+		args[i] = id
+	}
+	sqlStr := fmt.Sprintf(`
+SELECT ft.file_id,
+       t.id, t.name, t.notes, t.color,
+       t.category_id,
+       c.name  AS category_name,
+       c.color AS category_color,
+       t.metadata, t.creator_id, u.name AS creator_name, t.is_public
+FROM data.file_tag ft
+JOIN  data.tags t           ON t.id = ft.tag_id
+JOIN  core.users u          ON u.id = t.creator_id
+LEFT JOIN data.categories c ON c.id = t.category_id
+WHERE ft.file_id IN (%s)
+ORDER BY ft.file_id, t.name`, strings.Join(placeholders, ","))
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, sqlStr, args...)
+	if err != nil {
+		return nil, fmt.Errorf("PoolRepo.loadPoolTagsBatch: %w", err)
+	}
+	collected, err := pgx.CollectRows(rows, pgx.RowToStructByName[fileTagRow])
+	if err != nil {
+		return nil, fmt.Errorf("PoolRepo.loadPoolTagsBatch scan: %w", err)
+	}
+	result := make(map[uuid.UUID][]domain.Tag, len(fileIDs))
+	for _, fid := range fileIDs {
+		result[fid] = []domain.Tag{}
+	}
+	for _, row := range collected {
+		result[row.FileID] = append(result[row.FileID], toTagFromFileTag(row))
+	}
+	return result, nil
+}
+
+// ---------------------------------------------------------------------------
+// AddFiles
+// ---------------------------------------------------------------------------
+
+// AddFiles inserts files into the pool. When position is nil, files are
+// appended after the last existing file (MAX(position) + 1000 * i).
+// When position is provided (0-indexed), files are inserted at that index
+// and all pool positions are reassigned in one shot.
+func (r *PoolRepo) AddFiles(ctx context.Context, poolID uuid.UUID, fileIDs []uuid.UUID, position *int) error {
+	if len(fileIDs) == 0 {
+		return nil
+	}
+	q := connOrTx(ctx, r.pool)
+
+	if position == nil {
+		// Append: get current max position, then bulk-insert.
+		var maxPos int
+		row := q.QueryRow(ctx, `SELECT COALESCE(MAX(position), 0) FROM data.file_pool WHERE pool_id = $1`, poolID)
+		if err := row.Scan(&maxPos); err != nil {
+			return fmt.Errorf("PoolRepo.AddFiles maxPos: %w", err)
+		}
+		const ins = `INSERT INTO data.file_pool (file_id, pool_id, position) VALUES ($1, $2, $3) ON CONFLICT DO NOTHING`
+		for i, fid := range fileIDs {
+			if _, err := q.Exec(ctx, ins, fid, poolID, maxPos+1000*(i+1)); err != nil {
+				return fmt.Errorf("PoolRepo.AddFiles insert: %w", err)
+			}
+		}
+		return nil
+	}
+
+	// Positional insert: rebuild the full ordered list and reassign.
+	return r.insertAtPosition(ctx, q, poolID, fileIDs, *position)
+}
+
+// insertAtPosition fetches the current ordered file list, splices in the new
+// IDs at index pos (0-indexed, clamped), then does a full position reassign.
+func (r *PoolRepo) insertAtPosition(ctx context.Context, q db.Querier, poolID uuid.UUID, newIDs []uuid.UUID, pos int) error {
+	// 1. Fetch current order.
+	rows, err := q.Query(ctx, `SELECT file_id FROM data.file_pool WHERE pool_id = $1 ORDER BY position ASC, file_id ASC`, poolID)
+	if err != nil {
+		return fmt.Errorf("PoolRepo.insertAtPosition fetch: %w", err)
+	}
+	var current []uuid.UUID
+	for rows.Next() {
+		var fid uuid.UUID
+		if err := rows.Scan(&fid); err != nil {
+			rows.Close()
+			return fmt.Errorf("PoolRepo.insertAtPosition scan: %w", err)
+		}
+		current = append(current, fid)
+	}
+	rows.Close()
+	if err := rows.Err(); err != nil {
+		return fmt.Errorf("PoolRepo.insertAtPosition rows: %w", err)
+	}
+
+	// 2. Build new ordered list, skipping already-present IDs from newIDs.
+	present := make(map[uuid.UUID]bool, len(current))
+	for _, fid := range current {
+		present[fid] = true
+	}
+	toAdd := make([]uuid.UUID, 0, len(newIDs))
+	for _, fid := range newIDs {
+		if !present[fid] {
+			toAdd = append(toAdd, fid)
+		}
+	}
+	if len(toAdd) == 0 {
+		return nil // all already present
+	}
+
+	if pos < 0 {
+		pos = 0
+	}
+	if pos > len(current) {
+		pos = len(current)
+	}
+
+	ordered := make([]uuid.UUID, 0, len(current)+len(toAdd))
+	ordered = append(ordered, current[:pos]...)
+	ordered = append(ordered, toAdd...)
+	ordered = append(ordered, current[pos:]...)
+
+	// 3. Full replace.
+	return r.reassignPositions(ctx, q, poolID, ordered)
+}
+
+// reassignPositions does a DELETE + bulk INSERT for the pool with positions
+// 1000, 2000, 3000, ...
+func (r *PoolRepo) reassignPositions(ctx context.Context, q db.Querier, poolID uuid.UUID, ordered []uuid.UUID) error {
+	if _, err := q.Exec(ctx, `DELETE FROM data.file_pool WHERE pool_id = $1`, poolID); err != nil {
+		return fmt.Errorf("PoolRepo.reassignPositions delete: %w", err)
+	}
+	if len(ordered) == 0 {
+		return nil
+	}
+	const ins = `INSERT INTO data.file_pool (file_id, pool_id, position) VALUES ($1, $2, $3)`
+	for i, fid := range ordered {
+		if _, err := q.Exec(ctx, ins, fid, poolID, 1000*(i+1)); err != nil {
+			return fmt.Errorf("PoolRepo.reassignPositions insert: %w", err)
+		}
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// RemoveFiles
+// ---------------------------------------------------------------------------
+
+func (r *PoolRepo) RemoveFiles(ctx context.Context, poolID uuid.UUID, fileIDs []uuid.UUID) error {
+	if len(fileIDs) == 0 {
+		return nil
+	}
+	placeholders := make([]string, len(fileIDs))
+	args := make([]any, len(fileIDs)+1)
+	args[0] = poolID
+	for i, fid := range fileIDs {
+		placeholders[i] = fmt.Sprintf("$%d", i+2)
+		args[i+1] = fid
+	}
+	query := fmt.Sprintf(
+		`DELETE FROM data.file_pool WHERE pool_id = $1 AND file_id IN (%s)`,
+		strings.Join(placeholders, ","))
+
+	q := connOrTx(ctx, r.pool)
+	if _, err := q.Exec(ctx, query, args...); err != nil {
+		return fmt.Errorf("PoolRepo.RemoveFiles: %w", err)
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Reorder
+// ---------------------------------------------------------------------------
+
+// Reorder applies the requested order to the pool. Files actually in the pool
+// are placed in the given order; any pool members the request omitted are kept
+// and appended in their current order. This makes a partial request (e.g. a
+// paginated client that only loaded the first pages) reorder the visible prefix
+// without deleting the rest. Unknown IDs are ignored.
+func (r *PoolRepo) Reorder(ctx context.Context, poolID uuid.UUID, fileIDs []uuid.UUID) error {
+	q := connOrTx(ctx, r.pool)
+
+	// Current membership, in position order.
+	rows, err := q.Query(ctx,
+		`SELECT file_id FROM data.file_pool WHERE pool_id = $1 ORDER BY position ASC, file_id ASC`, poolID)
+	if err != nil {
+		return fmt.Errorf("PoolRepo.Reorder fetch: %w", err)
+	}
+	var current []uuid.UUID
+	for rows.Next() {
+		var fid uuid.UUID
+		if err := rows.Scan(&fid); err != nil {
+			rows.Close()
+			return fmt.Errorf("PoolRepo.Reorder scan: %w", err)
+		}
+		current = append(current, fid)
+	}
+	rows.Close()
+	if err := rows.Err(); err != nil {
+		return fmt.Errorf("PoolRepo.Reorder rows: %w", err)
+	}
+
+	inPool := make(map[uuid.UUID]bool, len(current))
+	for _, fid := range current {
+		inPool[fid] = true
+	}
+
+	ordered := make([]uuid.UUID, 0, len(current))
+	placed := make(map[uuid.UUID]bool, len(current))
+	for _, fid := range fileIDs {
+		if inPool[fid] && !placed[fid] {
+			ordered = append(ordered, fid)
+			placed[fid] = true
+		}
+	}
+	// Preserve any members the request did not mention.
+	for _, fid := range current {
+		if !placed[fid] {
+			ordered = append(ordered, fid)
+			placed[fid] = true
+		}
+	}
+
+	return r.reassignPositions(ctx, q, poolID, ordered)
+}

backend/internal/db/postgres/postgres.go

@@ -65,3 +65,29 @@ func connOrTx(ctx context.Context, pool *pgxpool.Pool) db.Querier {
 	}
 	return pool
 }
+
+// Object type IDs as seeded in core.object_types (007_seed_data.sql).
+const (
+	objTypeFile     int16 = 1
+	objTypeTag      int16 = 2
+	objTypeCategory int16 = 3
+	objTypePool     int16 = 4
+)
+
+// aclVisibilityCond returns a SQL boolean fragment that is true when the viewer
+// may see the row at <alias>.id of the given object type under the
+// private-by-default model: the row is public, the viewer created it, or the
+// viewer holds an explicit can_view grant. objectTypeID is a trusted constant
+// and is inlined; viewerID is bound as $n (referenced twice). Returns the
+// fragment, the next free parameter index, and the extended args.
+//
+// Callers skip this entirely for admins (who bypass ACL).
+func aclVisibilityCond(alias string, objectTypeID int16, viewerID int16, n int, args []any) (string, int, []any) {
+	cond := fmt.Sprintf(
+		"(%[1]s.is_public OR %[1]s.creator_id = $%[2]d OR EXISTS ("+
+			"SELECT 1 FROM acl.permissions p "+
+			"WHERE p.object_type_id = %[3]d AND p.object_id = %[1]s.id "+
+			"AND p.user_id = $%[2]d AND p.can_view))",
+		alias, n, objectTypeID)
+	return cond, n + 1, append(args, viewerID)
+}

backend/internal/db/postgres/session_repo.go

@@ -74,6 +74,28 @@ func (r *SessionRepo) Create(ctx context.Context, s *domain.Session) (*domain.Se
 	return &created, nil
 }
 
+func (r *SessionRepo) GetByID(ctx context.Context, id int) (*domain.Session, error) {
+	const sql = `
+		SELECT id, token_hash, user_id, user_agent, started_at, expires_at, last_activity
+		FROM activity.sessions
+		WHERE id = $1 AND is_active = true`
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, sql, id)
+	if err != nil {
+		return nil, fmt.Errorf("SessionRepo.GetByID: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[sessionRow])
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, domain.ErrNotFound
+		}
+		return nil, fmt.Errorf("SessionRepo.GetByID scan: %w", err)
+	}
+	s := toSession(row)
+	return &s, nil
+}
+
 func (r *SessionRepo) GetByTokenHash(ctx context.Context, hash string) (*domain.Session, error) {
 	const sql = `
 		SELECT id, token_hash, user_id, user_agent, started_at, expires_at, last_activity

backend/internal/db/postgres/tag_repo.go

@@ -0,0 +1,647 @@
+package postgres
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/google/uuid"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+)
+
+// ---------------------------------------------------------------------------
+// Row structs — use pgx-scannable types
+// ---------------------------------------------------------------------------
+
+type tagRow struct {
+	ID            uuid.UUID  `db:"id"`
+	Name          string     `db:"name"`
+	Notes         *string    `db:"notes"`
+	Color         *string    `db:"color"`
+	CategoryID    *uuid.UUID `db:"category_id"`
+	CategoryName  *string    `db:"category_name"`
+	CategoryColor *string    `db:"category_color"`
+	Metadata      []byte     `db:"metadata"`
+	CreatorID     int16      `db:"creator_id"`
+	CreatorName   string     `db:"creator_name"`
+	IsPublic      bool       `db:"is_public"`
+}
+
+type tagRowWithTotal struct {
+	tagRow
+	Total int `db:"total"`
+}
+
+type tagRuleRow struct {
+	WhenTagID   uuid.UUID `db:"when_tag_id"`
+	ThenTagID   uuid.UUID `db:"then_tag_id"`
+	ThenTagName string    `db:"then_tag_name"`
+	IsActive    bool      `db:"is_active"`
+}
+
+// ---------------------------------------------------------------------------
+// Converters
+// ---------------------------------------------------------------------------
+
+func toTag(r tagRow) domain.Tag {
+	t := domain.Tag{
+		ID:            r.ID,
+		Name:          r.Name,
+		Notes:         r.Notes,
+		Color:         r.Color,
+		CategoryID:    r.CategoryID,
+		CategoryName:  r.CategoryName,
+		CategoryColor: r.CategoryColor,
+		CreatorID:     r.CreatorID,
+		CreatorName:   r.CreatorName,
+		IsPublic:      r.IsPublic,
+		CreatedAt:     domain.UUIDCreatedAt(r.ID),
+	}
+	if len(r.Metadata) > 0 && string(r.Metadata) != "null" {
+		t.Metadata = json.RawMessage(r.Metadata)
+	}
+	return t
+}
+
+func toTagRule(r tagRuleRow) domain.TagRule {
+	return domain.TagRule{
+		WhenTagID:   r.WhenTagID,
+		ThenTagID:   r.ThenTagID,
+		ThenTagName: r.ThenTagName,
+		IsActive:    r.IsActive,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Shared SQL fragments
+// ---------------------------------------------------------------------------
+
+const tagSelectFrom = `
+SELECT
+    t.id,
+    t.name,
+    t.notes,
+    t.color,
+    t.category_id,
+    c.name  AS category_name,
+    c.color AS category_color,
+    t.metadata,
+    t.creator_id,
+    u.name  AS creator_name,
+    t.is_public
+FROM data.tags t
+LEFT JOIN data.categories c ON c.id = t.category_id
+JOIN      core.users u ON u.id = t.creator_id`
+
+func tagSortColumn(s string) string {
+	switch s {
+	case "name":
+		return "t.name"
+	case "color":
+		return "t.color"
+	case "category_name":
+		return "c.name"
+	default: // "created"
+		return "t.id"
+	}
+}
+
+// isPgUniqueViolation reports whether err is a PostgreSQL unique-constraint error.
+func isPgUniqueViolation(err error) bool {
+	var pgErr *pgconn.PgError
+	return errors.As(err, &pgErr) && pgErr.Code == "23505"
+}
+
+// ---------------------------------------------------------------------------
+// TagRepo — implements port.TagRepo
+// ---------------------------------------------------------------------------
+
+// TagRepo handles tag CRUD and file–tag relations.
+type TagRepo struct {
+	pool *pgxpool.Pool
+}
+
+var _ port.TagRepo = (*TagRepo)(nil)
+
+// NewTagRepo creates a TagRepo backed by pool.
+func NewTagRepo(pool *pgxpool.Pool) *TagRepo {
+	return &TagRepo{pool: pool}
+}
+
+// ---------------------------------------------------------------------------
+// List / ListByCategory
+// ---------------------------------------------------------------------------
+
+func (r *TagRepo) List(ctx context.Context, params port.OffsetParams) (*domain.TagOffsetPage, error) {
+	return r.listTags(ctx, params, nil)
+}
+
+func (r *TagRepo) ListByCategory(ctx context.Context, categoryID uuid.UUID, params port.OffsetParams) (*domain.TagOffsetPage, error) {
+	return r.listTags(ctx, params, &categoryID)
+}
+
+func (r *TagRepo) listTags(ctx context.Context, params port.OffsetParams, categoryID *uuid.UUID) (*domain.TagOffsetPage, error) {
+	order := "ASC"
+	if strings.ToLower(params.Order) == "desc" {
+		order = "DESC"
+	}
+	sortCol := tagSortColumn(params.Sort)
+
+	// When sorting by category, break ties within a category by the tag's own
+	// name (same direction), so tags are grouped by category then alphabetical.
+	secondarySort := ""
+	if params.Sort == "category_name" {
+		secondarySort = fmt.Sprintf("t.name %s, ", order)
+	}
+
+	args := []any{}
+	n := 1
+	var conditions []string
+
+	if params.Search != "" {
+		conditions = append(conditions, fmt.Sprintf("lower(t.name) LIKE lower($%d)", n))
+		args = append(args, "%"+params.Search+"%")
+		n++
+	}
+	if categoryID != nil {
+		conditions = append(conditions, fmt.Sprintf("t.category_id = $%d", n))
+		args = append(args, *categoryID)
+		n++
+	}
+	// Restrict to tags the viewer may see (private-by-default), unless admin.
+	if !params.ViewerIsAdmin {
+		var aclCond string
+		aclCond, n, args = aclVisibilityCond("t", objTypeTag, params.ViewerID, n, args)
+		conditions = append(conditions, aclCond)
+	}
+
+	where := ""
+	if len(conditions) > 0 {
+		where = "WHERE " + strings.Join(conditions, " AND ")
+	}
+
+	limit := params.Limit
+	if limit <= 0 {
+		limit = 50
+	}
+	offset := params.Offset
+	if offset < 0 {
+		offset = 0
+	}
+
+	query := fmt.Sprintf(`
+SELECT
+    t.id, t.name, t.notes, t.color,
+    t.category_id,
+    c.name  AS category_name,
+    c.color AS category_color,
+    t.metadata, t.creator_id,
+    u.name  AS creator_name,
+    t.is_public,
+    COUNT(*) OVER() AS total
+FROM data.tags t
+LEFT JOIN data.categories c ON c.id = t.category_id
+JOIN      core.users u ON u.id = t.creator_id
+%s
+ORDER BY %s %s NULLS LAST, %st.id ASC
+LIMIT $%d OFFSET $%d`, where, sortCol, order, secondarySort, n, n+1)
+
+	args = append(args, limit, offset)
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, args...)
+	if err != nil {
+		return nil, fmt.Errorf("TagRepo.List query: %w", err)
+	}
+	collected, err := pgx.CollectRows(rows, pgx.RowToStructByName[tagRowWithTotal])
+	if err != nil {
+		return nil, fmt.Errorf("TagRepo.List scan: %w", err)
+	}
+
+	items := make([]domain.Tag, len(collected))
+	total := 0
+	for i, row := range collected {
+		items[i] = toTag(row.tagRow)
+		total = row.Total
+	}
+	return &domain.TagOffsetPage{
+		Items:  items,
+		Total:  total,
+		Offset: offset,
+		Limit:  limit,
+	}, nil
+}
+
+// ---------------------------------------------------------------------------
+// GetByID
+// ---------------------------------------------------------------------------
+
+func (r *TagRepo) GetByID(ctx context.Context, id uuid.UUID) (*domain.Tag, error) {
+	const query = tagSelectFrom + `
+WHERE t.id = $1`
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, id)
+	if err != nil {
+		return nil, fmt.Errorf("TagRepo.GetByID: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[tagRow])
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, domain.ErrNotFound
+		}
+		return nil, fmt.Errorf("TagRepo.GetByID scan: %w", err)
+	}
+	t := toTag(row)
+	return &t, nil
+}
+
+// ---------------------------------------------------------------------------
+// Create
+// ---------------------------------------------------------------------------
+
+func (r *TagRepo) Create(ctx context.Context, t *domain.Tag) (*domain.Tag, error) {
+	const query = `
+WITH ins AS (
+    INSERT INTO data.tags (name, notes, color, category_id, metadata, creator_id, is_public)
+    VALUES ($1, $2, NULLIF($3, ''), $4, $5, $6, $7)
+    RETURNING *
+)
+SELECT
+    ins.id, ins.name, ins.notes, ins.color,
+    ins.category_id,
+    c.name  AS category_name,
+    c.color AS category_color,
+    ins.metadata, ins.creator_id,
+    u.name  AS creator_name,
+    ins.is_public
+FROM ins
+LEFT JOIN data.categories c ON c.id = ins.category_id
+JOIN      core.users u ON u.id = ins.creator_id`
+
+	var meta any
+	if len(t.Metadata) > 0 {
+		meta = t.Metadata
+	}
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query,
+		t.Name, t.Notes, t.Color, t.CategoryID, meta, t.CreatorID, t.IsPublic)
+	if err != nil {
+		return nil, fmt.Errorf("TagRepo.Create: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[tagRow])
+	if err != nil {
+		if isPgUniqueViolation(err) {
+			return nil, domain.ErrConflict
+		}
+		return nil, fmt.Errorf("TagRepo.Create scan: %w", err)
+	}
+	created := toTag(row)
+	return &created, nil
+}
+
+// ---------------------------------------------------------------------------
+// Update
+// ---------------------------------------------------------------------------
+
+// Update replaces all mutable fields. The caller must merge current values with
+// the patch (read-then-write) before calling this.
+func (r *TagRepo) Update(ctx context.Context, id uuid.UUID, t *domain.Tag) (*domain.Tag, error) {
+	const query = `
+WITH upd AS (
+    UPDATE data.tags SET
+        name        = $2,
+        notes       = $3,
+        color       = NULLIF($4, ''),
+        category_id = $5,
+        metadata    = COALESCE($6, metadata),
+        is_public   = $7
+    WHERE id = $1
+    RETURNING *
+)
+SELECT
+    upd.id, upd.name, upd.notes, upd.color,
+    upd.category_id,
+    c.name  AS category_name,
+    c.color AS category_color,
+    upd.metadata, upd.creator_id,
+    u.name  AS creator_name,
+    upd.is_public
+FROM upd
+LEFT JOIN data.categories c ON c.id = upd.category_id
+JOIN      core.users u ON u.id = upd.creator_id`
+
+	var meta any
+	if len(t.Metadata) > 0 {
+		meta = t.Metadata
+	}
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query,
+		id, t.Name, t.Notes, t.Color, t.CategoryID, meta, t.IsPublic)
+	if err != nil {
+		return nil, fmt.Errorf("TagRepo.Update: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[tagRow])
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, domain.ErrNotFound
+		}
+		if isPgUniqueViolation(err) {
+			return nil, domain.ErrConflict
+		}
+		return nil, fmt.Errorf("TagRepo.Update scan: %w", err)
+	}
+	updated := toTag(row)
+	return &updated, nil
+}
+
+// ---------------------------------------------------------------------------
+// Delete
+// ---------------------------------------------------------------------------
+
+func (r *TagRepo) Delete(ctx context.Context, id uuid.UUID) error {
+	const query = `DELETE FROM data.tags WHERE id = $1`
+
+	q := connOrTx(ctx, r.pool)
+	ct, err := q.Exec(ctx, query, id)
+	if err != nil {
+		return fmt.Errorf("TagRepo.Delete: %w", err)
+	}
+	if ct.RowsAffected() == 0 {
+		return domain.ErrNotFound
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// File–tag operations
+// ---------------------------------------------------------------------------
+
+func (r *TagRepo) ListByFile(ctx context.Context, fileID uuid.UUID) ([]domain.Tag, error) {
+	const query = tagSelectFrom + `
+JOIN data.file_tag ft ON ft.tag_id = t.id
+WHERE ft.file_id = $1
+ORDER BY t.name`
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, fileID)
+	if err != nil {
+		return nil, fmt.Errorf("TagRepo.ListByFile: %w", err)
+	}
+	collected, err := pgx.CollectRows(rows, pgx.RowToStructByName[tagRow])
+	if err != nil {
+		return nil, fmt.Errorf("TagRepo.ListByFile scan: %w", err)
+	}
+	tags := make([]domain.Tag, len(collected))
+	for i, row := range collected {
+		tags[i] = toTag(row)
+	}
+	return tags, nil
+}
+
+func (r *TagRepo) AddFileTag(ctx context.Context, fileID, tagID uuid.UUID) error {
+	const query = `
+INSERT INTO data.file_tag (file_id, tag_id) VALUES ($1, $2)
+ON CONFLICT DO NOTHING`
+
+	q := connOrTx(ctx, r.pool)
+	if _, err := q.Exec(ctx, query, fileID, tagID); err != nil {
+		return fmt.Errorf("TagRepo.AddFileTag: %w", err)
+	}
+	return nil
+}
+
+func (r *TagRepo) RemoveFileTag(ctx context.Context, fileID, tagID uuid.UUID) error {
+	const query = `DELETE FROM data.file_tag WHERE file_id = $1 AND tag_id = $2`
+
+	q := connOrTx(ctx, r.pool)
+	if _, err := q.Exec(ctx, query, fileID, tagID); err != nil {
+		return fmt.Errorf("TagRepo.RemoveFileTag: %w", err)
+	}
+	return nil
+}
+
+func (r *TagRepo) SetFileTags(ctx context.Context, fileID uuid.UUID, tagIDs []uuid.UUID) error {
+	q := connOrTx(ctx, r.pool)
+
+	if _, err := q.Exec(ctx,
+		`DELETE FROM data.file_tag WHERE file_id = $1`, fileID); err != nil {
+		return fmt.Errorf("TagRepo.SetFileTags delete: %w", err)
+	}
+	if len(tagIDs) == 0 {
+		return nil
+	}
+
+	placeholders := make([]string, len(tagIDs))
+	args := []any{fileID}
+	for i, tagID := range tagIDs {
+		placeholders[i] = fmt.Sprintf("($1, $%d)", i+2)
+		args = append(args, tagID)
+	}
+	ins := `INSERT INTO data.file_tag (file_id, tag_id) VALUES ` +
+		strings.Join(placeholders, ", ") + ` ON CONFLICT DO NOTHING`
+
+	if _, err := q.Exec(ctx, ins, args...); err != nil {
+		return fmt.Errorf("TagRepo.SetFileTags insert: %w", err)
+	}
+	return nil
+}
+
+func (r *TagRepo) CommonTagsForFiles(ctx context.Context, fileIDs []uuid.UUID) ([]domain.Tag, error) {
+	if len(fileIDs) == 0 {
+		return []domain.Tag{}, nil
+	}
+	return r.queryTagsByPresence(ctx, fileIDs, "=")
+}
+
+func (r *TagRepo) PartialTagsForFiles(ctx context.Context, fileIDs []uuid.UUID) ([]domain.Tag, error) {
+	if len(fileIDs) == 0 {
+		return []domain.Tag{}, nil
+	}
+	return r.queryTagsByPresence(ctx, fileIDs, "<")
+}
+
+func (r *TagRepo) queryTagsByPresence(ctx context.Context, fileIDs []uuid.UUID, op string) ([]domain.Tag, error) {
+	placeholders := make([]string, len(fileIDs))
+	args := make([]any, len(fileIDs)+1)
+	for i, id := range fileIDs {
+		placeholders[i] = fmt.Sprintf("$%d", i+1)
+		args[i] = id
+	}
+	args[len(fileIDs)] = len(fileIDs)
+	n := len(fileIDs) + 1
+
+	query := fmt.Sprintf(`
+SELECT
+    t.id, t.name, t.notes, t.color,
+    t.category_id,
+    c.name  AS category_name,
+    c.color AS category_color,
+    t.metadata, t.creator_id,
+    u.name  AS creator_name,
+    t.is_public
+FROM data.tags t
+JOIN data.file_tag ft ON ft.tag_id = t.id
+LEFT JOIN data.categories c ON c.id = t.category_id
+JOIN      core.users u ON u.id = t.creator_id
+WHERE ft.file_id IN (%s)
+GROUP BY t.id, c.id, u.id
+HAVING COUNT(DISTINCT ft.file_id) %s $%d
+ORDER BY t.name`,
+		strings.Join(placeholders, ", "), op, n)
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, args...)
+	if err != nil {
+		return nil, fmt.Errorf("TagRepo.queryTagsByPresence: %w", err)
+	}
+	collected, err := pgx.CollectRows(rows, pgx.RowToStructByName[tagRow])
+	if err != nil {
+		return nil, fmt.Errorf("TagRepo.queryTagsByPresence scan: %w", err)
+	}
+	tags := make([]domain.Tag, len(collected))
+	for i, row := range collected {
+		tags[i] = toTag(row)
+	}
+	return tags, nil
+}
+
+// ---------------------------------------------------------------------------
+// TagRuleRepo — implements port.TagRuleRepo (separate type to avoid method collision)
+// ---------------------------------------------------------------------------
+
+// TagRuleRepo handles tag-rule CRUD.
+type TagRuleRepo struct {
+	pool *pgxpool.Pool
+}
+
+var _ port.TagRuleRepo = (*TagRuleRepo)(nil)
+
+// NewTagRuleRepo creates a TagRuleRepo backed by pool.
+func NewTagRuleRepo(pool *pgxpool.Pool) *TagRuleRepo {
+	return &TagRuleRepo{pool: pool}
+}
+
+func (r *TagRuleRepo) ListByTag(ctx context.Context, tagID uuid.UUID) ([]domain.TagRule, error) {
+	const query = `
+SELECT
+    tr.when_tag_id,
+    tr.then_tag_id,
+    t.name AS then_tag_name,
+    tr.is_active
+FROM data.tag_rules tr
+JOIN data.tags t ON t.id = tr.then_tag_id
+WHERE tr.when_tag_id = $1
+ORDER BY t.name`
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, tagID)
+	if err != nil {
+		return nil, fmt.Errorf("TagRuleRepo.ListByTag: %w", err)
+	}
+	collected, err := pgx.CollectRows(rows, pgx.RowToStructByName[tagRuleRow])
+	if err != nil {
+		return nil, fmt.Errorf("TagRuleRepo.ListByTag scan: %w", err)
+	}
+	rules := make([]domain.TagRule, len(collected))
+	for i, row := range collected {
+		rules[i] = toTagRule(row)
+	}
+	return rules, nil
+}
+
+func (r *TagRuleRepo) Create(ctx context.Context, rule domain.TagRule) (*domain.TagRule, error) {
+	const query = `
+WITH ins AS (
+    INSERT INTO data.tag_rules (when_tag_id, then_tag_id, is_active)
+    VALUES ($1, $2, $3)
+    RETURNING *
+)
+SELECT ins.when_tag_id, ins.then_tag_id, t.name AS then_tag_name, ins.is_active
+FROM ins
+JOIN data.tags t ON t.id = ins.then_tag_id`
+
+	q := connOrTx(ctx, r.pool)
+	rows, err := q.Query(ctx, query, rule.WhenTagID, rule.ThenTagID, rule.IsActive)
+	if err != nil {
+		return nil, fmt.Errorf("TagRuleRepo.Create: %w", err)
+	}
+	row, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[tagRuleRow])
+	if err != nil {
+		if isPgUniqueViolation(err) {
+			return nil, domain.ErrConflict
+		}
+		return nil, fmt.Errorf("TagRuleRepo.Create scan: %w", err)
+	}
+	result := toTagRule(row)
+	return &result, nil
+}
+
+func (r *TagRuleRepo) SetActive(ctx context.Context, whenTagID, thenTagID uuid.UUID, active, applyToExisting bool) error {
+	const updateQuery = `
+UPDATE data.tag_rules SET is_active = $3
+WHERE when_tag_id = $1 AND then_tag_id = $2`
+
+	q := connOrTx(ctx, r.pool)
+	ct, err := q.Exec(ctx, updateQuery, whenTagID, thenTagID, active)
+	if err != nil {
+		return fmt.Errorf("TagRuleRepo.SetActive: %w", err)
+	}
+	if ct.RowsAffected() == 0 {
+		return domain.ErrNotFound
+	}
+
+	if !active || !applyToExisting {
+		return nil
+	}
+
+	// Retroactively apply the full transitive expansion of thenTagID to all
+	// files that already carry whenTagID. The recursive CTE walks active rules
+	// starting from thenTagID (mirrors the Go expandTagSet BFS).
+	const retroQuery = `
+WITH RECURSIVE expansion(tag_id) AS (
+    SELECT $2::uuid
+    UNION
+    SELECT r.then_tag_id
+    FROM data.tag_rules r
+    JOIN expansion e ON r.when_tag_id = e.tag_id
+    WHERE r.is_active = true
+)
+INSERT INTO data.file_tag (file_id, tag_id)
+SELECT ft.file_id, e.tag_id
+FROM data.file_tag ft
+CROSS JOIN expansion e
+WHERE ft.tag_id = $1
+ON CONFLICT DO NOTHING`
+
+	if _, err := q.Exec(ctx, retroQuery, whenTagID, thenTagID); err != nil {
+		return fmt.Errorf("TagRuleRepo.SetActive retroactive apply: %w", err)
+	}
+	return nil
+}
+
+func (r *TagRuleRepo) Delete(ctx context.Context, whenTagID, thenTagID uuid.UUID) error {
+	const query = `
+DELETE FROM data.tag_rules
+WHERE when_tag_id = $1 AND then_tag_id = $2`
+
+	q := connOrTx(ctx, r.pool)
+	ct, err := q.Exec(ctx, query, whenTagID, thenTagID)
+	if err != nil {
+		return fmt.Errorf("TagRuleRepo.Delete: %w", err)
+	}
+	if ct.RowsAffected() == 0 {
+		return domain.ErrNotFound
+	}
+	return nil
+}

backend/internal/db/postgres/user_repo.go

@@ -162,12 +162,12 @@ func (r *UserRepo) Create(ctx context.Context, u *domain.User) (*domain.User, er
 func (r *UserRepo) Update(ctx context.Context, id int16, u *domain.User) (*domain.User, error) {
 	const sql = `
 		UPDATE core.users
-		SET name = $2, password = $3, is_admin = $4, can_create = $5
+		SET name = $2, password = $3, is_admin = $4, can_create = $5, is_blocked = $6
 		WHERE id = $1
 		RETURNING id, name, password, is_admin, can_create, is_blocked`
 
 	q := connOrTx(ctx, r.pool)
-	rows, err := q.Query(ctx, sql, id, u.Name, u.Password, u.IsAdmin, u.CanCreate)
+	rows, err := q.Query(ctx, sql, id, u.Name, u.Password, u.IsAdmin, u.CanCreate, u.IsBlocked)
 	if err != nil {
 		return nil, fmt.Errorf("UserRepo.Update: %w", err)
 	}

backend/internal/domain/file.go

@@ -49,6 +49,12 @@ type FileListParams struct {
 	Filter string // filter DSL expression
 	Search string // substring match on original_name
 	Trash  bool   // if true, return only soft-deleted files
+
+	// Visibility — populated by the service from the request context. When
+	// ViewerIsAdmin is false the repository restricts results to files the
+	// viewer may see (public, owned, or explicitly granted).
+	ViewerID      int16
+	ViewerIsAdmin bool
 }
 
 // FilePage is the result of a cursor-based file listing.

backend/internal/handler/acl_handler.go

@@ -0,0 +1,146 @@
+package handler
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/service"
+)
+
+// objectTypeIDs maps the URL segment to the object_type PK in core.object_types.
+// Row order matches 007_seed_data.sql: file=1, tag=2, category=3, pool=4.
+var objectTypeIDs = map[string]int16{
+	"file":     1,
+	"tag":      2,
+	"category": 3,
+	"pool":     4,
+}
+
+// ACLHandler handles GET/PUT /acl/:object_type/:object_id.
+type ACLHandler struct {
+	aclSvc *service.ACLService
+}
+
+// NewACLHandler creates an ACLHandler.
+func NewACLHandler(aclSvc *service.ACLService) *ACLHandler {
+	return &ACLHandler{aclSvc: aclSvc}
+}
+
+// ---------------------------------------------------------------------------
+// Response type
+// ---------------------------------------------------------------------------
+
+type permissionJSON struct {
+	UserID   int16  `json:"user_id"`
+	UserName string `json:"user_name"`
+	CanView  bool   `json:"can_view"`
+	CanEdit  bool   `json:"can_edit"`
+}
+
+func toPermissionJSON(p domain.Permission) permissionJSON {
+	return permissionJSON{
+		UserID:   p.UserID,
+		UserName: p.UserName,
+		CanView:  p.CanView,
+		CanEdit:  p.CanEdit,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func parseACLPath(c *gin.Context) (objectTypeID int16, objectID uuid.UUID, ok bool) {
+	typeStr := c.Param("object_type")
+	id, exists := objectTypeIDs[typeStr]
+	if !exists {
+		respondError(c, domain.ErrValidation)
+		return 0, uuid.UUID{}, false
+	}
+
+	objectID, err := uuid.Parse(c.Param("object_id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return 0, uuid.UUID{}, false
+	}
+
+	return id, objectID, true
+}
+
+// ---------------------------------------------------------------------------
+// GET /acl/:object_type/:object_id
+// ---------------------------------------------------------------------------
+
+func (h *ACLHandler) GetPermissions(c *gin.Context) {
+	objectTypeID, objectID, ok := parseACLPath(c)
+	if !ok {
+		return
+	}
+
+	userID, isAdmin, _ := domain.UserFromContext(c.Request.Context())
+	perms, err := h.aclSvc.GetPermissions(c.Request.Context(), userID, isAdmin, objectTypeID, objectID)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	out := make([]permissionJSON, len(perms))
+	for i, p := range perms {
+		out[i] = toPermissionJSON(p)
+	}
+	respondJSON(c, http.StatusOK, out)
+}
+
+// ---------------------------------------------------------------------------
+// PUT /acl/:object_type/:object_id
+// ---------------------------------------------------------------------------
+
+func (h *ACLHandler) SetPermissions(c *gin.Context) {
+	objectTypeID, objectID, ok := parseACLPath(c)
+	if !ok {
+		return
+	}
+
+	var body struct {
+		Permissions []struct {
+			UserID  int16 `json:"user_id"  binding:"required"`
+			CanView bool  `json:"can_view"`
+			CanEdit bool  `json:"can_edit"`
+		} `json:"permissions" binding:"required"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	perms := make([]domain.Permission, len(body.Permissions))
+	for i, p := range body.Permissions {
+		perms[i] = domain.Permission{
+			UserID:  p.UserID,
+			CanView: p.CanView,
+			CanEdit: p.CanEdit,
+		}
+	}
+
+	userID, isAdmin, _ := domain.UserFromContext(c.Request.Context())
+	if err := h.aclSvc.SetPermissions(c.Request.Context(), userID, isAdmin, objectTypeID, objectID, perms); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	// Re-read to return the stored permissions (with UserName denormalized).
+	stored, err := h.aclSvc.GetPermissions(c.Request.Context(), userID, isAdmin, objectTypeID, objectID)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	out := make([]permissionJSON, len(stored))
+	for i, p := range stored {
+		out[i] = toPermissionJSON(p)
+	}
+	respondJSON(c, http.StatusOK, out)
+}

backend/internal/handler/audit_handler.go

@@ -0,0 +1,120 @@
+package handler
+
+import (
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/service"
+)
+
+// AuditHandler handles GET /audit.
+type AuditHandler struct {
+	auditSvc *service.AuditService
+}
+
+// NewAuditHandler creates an AuditHandler.
+func NewAuditHandler(auditSvc *service.AuditService) *AuditHandler {
+	return &AuditHandler{auditSvc: auditSvc}
+}
+
+// ---------------------------------------------------------------------------
+// Response type
+// ---------------------------------------------------------------------------
+
+type auditEntryJSON struct {
+	ID          int64   `json:"id"`
+	UserID      int16   `json:"user_id"`
+	UserName    string  `json:"user_name"`
+	Action      string  `json:"action"`
+	ObjectType  *string `json:"object_type"`
+	ObjectID    *string `json:"object_id"`
+	PerformedAt string  `json:"performed_at"`
+}
+
+func toAuditEntryJSON(e domain.AuditEntry) auditEntryJSON {
+	j := auditEntryJSON{
+		ID:          e.ID,
+		UserID:      e.UserID,
+		UserName:    e.UserName,
+		Action:      e.Action,
+		ObjectType:  e.ObjectType,
+		PerformedAt: e.PerformedAt.UTC().Format(time.RFC3339),
+	}
+	if e.ObjectID != nil {
+		s := e.ObjectID.String()
+		j.ObjectID = &s
+	}
+	return j
+}
+
+// ---------------------------------------------------------------------------
+// GET /audit  (admin)
+// ---------------------------------------------------------------------------
+
+func (h *AuditHandler) List(c *gin.Context) {
+	if !requireAdmin(c) {
+		return
+	}
+
+	filter := domain.AuditFilter{}
+
+	if s := c.Query("limit"); s != "" {
+		if n, err := strconv.Atoi(s); err == nil {
+			filter.Limit = n
+		}
+	}
+	if s := c.Query("offset"); s != "" {
+		if n, err := strconv.Atoi(s); err == nil {
+			filter.Offset = n
+		}
+	}
+	if s := c.Query("user_id"); s != "" {
+		if n, err := strconv.ParseInt(s, 10, 16); err == nil {
+			id := int16(n)
+			filter.UserID = &id
+		}
+	}
+	if s := c.Query("action"); s != "" {
+		filter.Action = s
+	}
+	if s := c.Query("object_type"); s != "" {
+		filter.ObjectType = s
+	}
+	if s := c.Query("object_id"); s != "" {
+		if id, err := uuid.Parse(s); err == nil {
+			filter.ObjectID = &id
+		}
+	}
+	if s := c.Query("from"); s != "" {
+		if t, err := time.Parse(time.RFC3339, s); err == nil {
+			filter.From = &t
+		}
+	}
+	if s := c.Query("to"); s != "" {
+		if t, err := time.Parse(time.RFC3339, s); err == nil {
+			filter.To = &t
+		}
+	}
+
+	page, err := h.auditSvc.Query(c.Request.Context(), filter)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]auditEntryJSON, len(page.Items))
+	for i, e := range page.Items {
+		items[i] = toAuditEntryJSON(e)
+	}
+	respondJSON(c, http.StatusOK, gin.H{
+		"items":  items,
+		"total":  page.Total,
+		"offset": page.Offset,
+		"limit":  page.Limit,
+	})
+}

backend/internal/handler/category_handler.go

@@ -0,0 +1,235 @@
+package handler
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/service"
+)
+
+// CategoryHandler handles all /categories endpoints.
+type CategoryHandler struct {
+	categorySvc *service.CategoryService
+}
+
+// NewCategoryHandler creates a CategoryHandler.
+func NewCategoryHandler(categorySvc *service.CategoryService) *CategoryHandler {
+	return &CategoryHandler{categorySvc: categorySvc}
+}
+
+// ---------------------------------------------------------------------------
+// Response types
+// ---------------------------------------------------------------------------
+
+type categoryJSON struct {
+	ID          string  `json:"id"`
+	Name        string  `json:"name"`
+	Notes       *string `json:"notes"`
+	Color       *string `json:"color"`
+	CreatorID   int16   `json:"creator_id"`
+	CreatorName string  `json:"creator_name"`
+	IsPublic    bool    `json:"is_public"`
+	CreatedAt   string  `json:"created_at"`
+}
+
+func toCategoryJSON(c domain.Category) categoryJSON {
+	return categoryJSON{
+		ID:          c.ID.String(),
+		Name:        c.Name,
+		Notes:       c.Notes,
+		Color:       c.Color,
+		CreatorID:   c.CreatorID,
+		CreatorName: c.CreatorName,
+		IsPublic:    c.IsPublic,
+		CreatedAt:   c.CreatedAt.UTC().Format("2006-01-02T15:04:05Z"),
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func parseCategoryID(c *gin.Context) (uuid.UUID, bool) {
+	id, err := uuid.Parse(c.Param("category_id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return uuid.UUID{}, false
+	}
+	return id, true
+}
+
+// ---------------------------------------------------------------------------
+// GET /categories
+// ---------------------------------------------------------------------------
+
+func (h *CategoryHandler) List(c *gin.Context) {
+	params := parseOffsetParams(c, "created")
+
+	page, err := h.categorySvc.List(c.Request.Context(), params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]categoryJSON, len(page.Items))
+	for i, cat := range page.Items {
+		items[i] = toCategoryJSON(cat)
+	}
+	respondJSON(c, http.StatusOK, gin.H{
+		"items":  items,
+		"total":  page.Total,
+		"offset": page.Offset,
+		"limit":  page.Limit,
+	})
+}
+
+// ---------------------------------------------------------------------------
+// POST /categories
+// ---------------------------------------------------------------------------
+
+func (h *CategoryHandler) Create(c *gin.Context) {
+	var body struct {
+		Name     string  `json:"name"      binding:"required"`
+		Notes    *string `json:"notes"`
+		Color    *string `json:"color"`
+		IsPublic *bool   `json:"is_public"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	created, err := h.categorySvc.Create(c.Request.Context(), service.CategoryParams{
+		Name:     body.Name,
+		Notes:    body.Notes,
+		Color:    body.Color,
+		IsPublic: body.IsPublic,
+	})
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusCreated, toCategoryJSON(*created))
+}
+
+// ---------------------------------------------------------------------------
+// GET /categories/:category_id
+// ---------------------------------------------------------------------------
+
+func (h *CategoryHandler) Get(c *gin.Context) {
+	id, ok := parseCategoryID(c)
+	if !ok {
+		return
+	}
+
+	cat, err := h.categorySvc.Get(c.Request.Context(), id)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusOK, toCategoryJSON(*cat))
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /categories/:category_id
+// ---------------------------------------------------------------------------
+
+func (h *CategoryHandler) Update(c *gin.Context) {
+	id, ok := parseCategoryID(c)
+	if !ok {
+		return
+	}
+
+	// Use a raw map to detect explicitly-null fields.
+	var raw map[string]any
+	if err := c.ShouldBindJSON(&raw); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	params := service.CategoryParams{}
+
+	if v, ok := raw["name"]; ok {
+		if s, ok := v.(string); ok {
+			params.Name = s
+		}
+	}
+	if _, ok := raw["notes"]; ok {
+		if raw["notes"] == nil {
+			empty := ""
+			params.Notes = &empty
+		} else if s, ok := raw["notes"].(string); ok {
+			params.Notes = &s
+		}
+	}
+	if _, ok := raw["color"]; ok {
+		if raw["color"] == nil {
+			empty := ""
+			params.Color = &empty
+		} else if s, ok := raw["color"].(string); ok {
+			params.Color = &s
+		}
+	}
+	if v, ok := raw["is_public"]; ok {
+		if b, ok := v.(bool); ok {
+			params.IsPublic = &b
+		}
+	}
+
+	updated, err := h.categorySvc.Update(c.Request.Context(), id, params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusOK, toCategoryJSON(*updated))
+}
+
+// ---------------------------------------------------------------------------
+// DELETE /categories/:category_id
+// ---------------------------------------------------------------------------
+
+func (h *CategoryHandler) Delete(c *gin.Context) {
+	id, ok := parseCategoryID(c)
+	if !ok {
+		return
+	}
+
+	if err := h.categorySvc.Delete(c.Request.Context(), id); err != nil {
+		respondError(c, err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// ---------------------------------------------------------------------------
+// GET /categories/:category_id/tags
+// ---------------------------------------------------------------------------
+
+func (h *CategoryHandler) ListTags(c *gin.Context) {
+	id, ok := parseCategoryID(c)
+	if !ok {
+		return
+	}
+
+	params := parseOffsetParams(c, "created")
+
+	page, err := h.categorySvc.ListTags(c.Request.Context(), id, params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]tagJSON, len(page.Items))
+	for i, t := range page.Items {
+		items[i] = toTagJSON(t)
+	}
+	respondJSON(c, http.StatusOK, gin.H{
+		"items":  items,
+		"total":  page.Total,
+		"offset": page.Offset,
+		"limit":  page.Limit,
+	})
+}

backend/internal/handler/file_handler.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"mime/multipart"
 	"net/http"
 	"strconv"
 	"strings"
@@ -20,11 +21,34 @@ import (
 // FileHandler handles all /files endpoints.
 type FileHandler struct {
 	fileSvc        *service.FileService
+	tagSvc         *service.TagService
+	maxUploadBytes int64
 }
 
-// NewFileHandler creates a FileHandler.
+// NewFileHandler creates a FileHandler. maxUploadBytes caps the size of an
-func NewFileHandler(fileSvc *service.FileService) *FileHandler {
+// uploaded or replacement file.
-	return &FileHandler{fileSvc: fileSvc}
+func NewFileHandler(fileSvc *service.FileService, tagSvc *service.TagService, maxUploadBytes int64) *FileHandler {
+	return &FileHandler{fileSvc: fileSvc, tagSvc: tagSvc, maxUploadBytes: maxUploadBytes}
+}
+
+// formFileLimited reads the "file" multipart field while bounding how many bytes
+// are read from the request body, then rejects files larger than the configured
+// cap. The body limit guards against a dishonest Content-Length; the Size check
+// gives a clear rejection for an honestly-declared oversized file.
+func (h *FileHandler) formFileLimited(c *gin.Context) (*multipart.FileHeader, bool) {
+	// Allow a little slack above the file cap for multipart framing overhead.
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, h.maxUploadBytes+(1<<20))
+
+	fh, err := c.FormFile("file")
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return nil, false
+	}
+	if fh.Size > h.maxUploadBytes {
+		respondError(c, domain.ErrValidation)
+		return nil, false
+	}
+	return fh, true
 }
 
 // ---------------------------------------------------------------------------
@@ -185,9 +209,8 @@ func (h *FileHandler) List(c *gin.Context) {
 // ---------------------------------------------------------------------------
 
 func (h *FileHandler) Upload(c *gin.Context) {
-	fh, err := c.FormFile("file")
+	fh, ok := h.formFileLimited(c)
-	if err != nil {
+	if !ok {
-		respondError(c, domain.ErrValidation)
 		return
 	}
 
@@ -277,6 +300,25 @@ func (h *FileHandler) GetMeta(c *gin.Context) {
 	respondJSON(c, http.StatusOK, toFileJSON(*f))
 }
 
+// ---------------------------------------------------------------------------
+// POST /files/:id/views
+// ---------------------------------------------------------------------------
+
+// RecordView logs that the current user viewed the file (activity.file_views).
+func (h *FileHandler) RecordView(c *gin.Context) {
+	id, ok := parseFileID(c)
+	if !ok {
+		return
+	}
+
+	if err := h.fileSvc.RecordView(c.Request.Context(), id); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	c.Status(http.StatusNoContent)
+}
+
 // ---------------------------------------------------------------------------
 // PATCH /files/:id
 // ---------------------------------------------------------------------------
@@ -359,9 +401,26 @@ func (h *FileHandler) GetContent(c *gin.Context) {
 	defer res.Body.Close()
 
 	c.Header("Content-Type", res.MIMEType)
+	c.Header("Cache-Control", "private, max-age=3600")
+	// Default to attachment (download); ?inline=1 serves it for in-tab viewing.
+	disposition := "attachment"
+	if c.Query("inline") == "1" {
+		disposition = "inline"
+	}
+	name := ""
 	if res.OriginalName != nil {
+		name = *res.OriginalName
 		c.Header("Content-Disposition",
-			fmt.Sprintf("attachment; filename=%q", *res.OriginalName))
+			fmt.Sprintf("%s; filename=%q", disposition, name))
+	}
+
+	// Serve with byte-range support when the body is seekable (it is for the
+	// disk store): http.ServeContent advertises Accept-Ranges and answers Range
+	// requests with 206 Partial Content, which is what lets the browser scrub and
+	// seek within audio/video. Fall back to a plain stream otherwise.
+	if seeker, ok := res.Body.(io.ReadSeeker); ok {
+		http.ServeContent(c.Writer, c.Request, name, time.Time{}, seeker)
+		return
 	}
 	c.Status(http.StatusOK)
 	io.Copy(c.Writer, res.Body) //nolint:errcheck
@@ -377,9 +436,8 @@ func (h *FileHandler) ReplaceContent(c *gin.Context) {
 		return
 	}
 
-	fh, err := c.FormFile("file")
+	fh, ok := h.formFileLimited(c)
-	if err != nil {
+	if !ok {
-		respondError(c, domain.ErrValidation)
 		return
 	}
 
@@ -435,6 +493,7 @@ func (h *FileHandler) GetThumbnail(c *gin.Context) {
 	defer rc.Close()
 
 	c.Header("Content-Type", "image/jpeg")
+	c.Header("Cache-Control", "private, max-age=3600")
 	c.Status(http.StatusOK)
 	io.Copy(c.Writer, rc) //nolint:errcheck
 }
@@ -457,6 +516,7 @@ func (h *FileHandler) GetPreview(c *gin.Context) {
 	defer rc.Close()
 
 	c.Header("Content-Type", "image/jpeg")
+	c.Header("Cache-Control", "private, max-age=3600")
 	c.Status(http.StatusOK)
 	io.Copy(c.Writer, rc) //nolint:errcheck
 }
@@ -498,117 +558,6 @@ func (h *FileHandler) PermanentDelete(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }
 
-// ---------------------------------------------------------------------------
-// GET /files/:id/tags
-// ---------------------------------------------------------------------------
-
-func (h *FileHandler) ListTags(c *gin.Context) {
-	id, ok := parseFileID(c)
-	if !ok {
-		return
-	}
-
-	tags, err := h.fileSvc.ListFileTags(c.Request.Context(), id)
-	if err != nil {
-		respondError(c, err)
-		return
-	}
-
-	items := make([]tagJSON, len(tags))
-	for i, t := range tags {
-		items[i] = toTagJSON(t)
-	}
-	respondJSON(c, http.StatusOK, items)
-}
-
-// ---------------------------------------------------------------------------
-// PUT /files/:id/tags  (replace all)
-// ---------------------------------------------------------------------------
-
-func (h *FileHandler) SetTags(c *gin.Context) {
-	id, ok := parseFileID(c)
-	if !ok {
-		return
-	}
-
-	var body struct {
-		TagIDs []string `json:"tag_ids" binding:"required"`
-	}
-	if err := c.ShouldBindJSON(&body); err != nil {
-		respondError(c, domain.ErrValidation)
-		return
-	}
-
-	tagIDs, err := parseUUIDs(body.TagIDs)
-	if err != nil {
-		respondError(c, domain.ErrValidation)
-		return
-	}
-
-	tags, err := h.fileSvc.SetFileTags(c.Request.Context(), id, tagIDs)
-	if err != nil {
-		respondError(c, err)
-		return
-	}
-
-	items := make([]tagJSON, len(tags))
-	for i, t := range tags {
-		items[i] = toTagJSON(t)
-	}
-	respondJSON(c, http.StatusOK, items)
-}
-
-// ---------------------------------------------------------------------------
-// PUT /files/:id/tags/:tag_id
-// ---------------------------------------------------------------------------
-
-func (h *FileHandler) AddTag(c *gin.Context) {
-	fileID, ok := parseFileID(c)
-	if !ok {
-		return
-	}
-	tagID, err := uuid.Parse(c.Param("tag_id"))
-	if err != nil {
-		respondError(c, domain.ErrValidation)
-		return
-	}
-
-	tags, err := h.fileSvc.AddTag(c.Request.Context(), fileID, tagID)
-	if err != nil {
-		respondError(c, err)
-		return
-	}
-
-	items := make([]tagJSON, len(tags))
-	for i, t := range tags {
-		items[i] = toTagJSON(t)
-	}
-	respondJSON(c, http.StatusOK, items)
-}
-
-// ---------------------------------------------------------------------------
-// DELETE /files/:id/tags/:tag_id
-// ---------------------------------------------------------------------------
-
-func (h *FileHandler) RemoveTag(c *gin.Context) {
-	fileID, ok := parseFileID(c)
-	if !ok {
-		return
-	}
-	tagID, err := uuid.Parse(c.Param("tag_id"))
-	if err != nil {
-		respondError(c, domain.ErrValidation)
-		return
-	}
-
-	if err := h.fileSvc.RemoveTag(c.Request.Context(), fileID, tagID); err != nil {
-		respondError(c, err)
-		return
-	}
-
-	c.Status(http.StatusNoContent)
-}
-
 // ---------------------------------------------------------------------------
 // POST /files/bulk/tags
 // ---------------------------------------------------------------------------
@@ -639,7 +588,7 @@ func (h *FileHandler) BulkSetTags(c *gin.Context) {
 		return
 	}
 
-	applied, err := h.fileSvc.BulkSetTags(c.Request.Context(), fileIDs, body.Action, tagIDs)
+	applied, err := h.tagSvc.BulkSetTags(c.Request.Context(), fileIDs, body.Action, tagIDs)
 	if err != nil {
 		respondError(c, err)
 		return
@@ -698,16 +647,16 @@ func (h *FileHandler) CommonTags(c *gin.Context) {
 		return
 	}
 
-	common, partial, err := h.fileSvc.CommonTags(c.Request.Context(), fileIDs)
+	common, partial, err := h.tagSvc.CommonTags(c.Request.Context(), fileIDs)
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 
-	toStrs := func(ids []uuid.UUID) []string {
+	toStrs := func(tags []domain.Tag) []string {
-		s := make([]string, len(ids))
+		s := make([]string, len(tags))
-		for i, id := range ids {
+		for i, t := range tags {
-			s[i] = id.String()
+			s[i] = t.ID.String()
 		}
 		return s
 	}
@@ -723,19 +672,48 @@ func (h *FileHandler) CommonTags(c *gin.Context) {
 // ---------------------------------------------------------------------------
 
 func (h *FileHandler) Import(c *gin.Context) {
+	// Server-side directory import reads arbitrary paths on the host; restrict
+	// it to administrators.
+	if !requireAdmin(c) {
+		return
+	}
+
 	var body struct {
 		Path string `json:"path"`
 	}
 	// Body is optional; ignore bind errors.
 	_ = c.ShouldBindJSON(&body)
 
-	result, err := h.fileSvc.Import(c.Request.Context(), body.Path)
+	// Stream progress as newline-delimited JSON so the client can render a live
-	if err != nil {
+	// progress bar and per-file status. Headers are deferred until the first
+	// event, so a validation error (bad path, import disabled) raised before any
+	// file is touched can still be returned as a normal JSON error response.
+	flusher, canFlush := c.Writer.(http.Flusher)
+	started := false
+	enc := json.NewEncoder(c.Writer)
+
+	emit := func(ev service.ImportEvent) {
+		if !started {
+			c.Header("Content-Type", "application/x-ndjson")
+			c.Header("Cache-Control", "no-cache")
+			c.Header("X-Accel-Buffering", "no") // don't let a proxy buffer the stream
+			c.Writer.WriteHeader(http.StatusOK)
+			started = true
+		}
+		_ = enc.Encode(ev) // appends a newline
+		if canFlush {
+			flusher.Flush()
+		}
+	}
+
+	if _, err := h.fileSvc.Import(c.Request.Context(), body.Path, emit); err != nil {
+		if !started {
 			respondError(c, err)
 			return
 		}
-
+		// Headers already sent; surface the failure as a terminal stream event.
-	respondJSON(c, http.StatusOK, result)
+		emit(service.ImportEvent{Type: "error", Reason: err.Error()})
+	}
 }
 
 // ---------------------------------------------------------------------------

backend/internal/handler/middleware.go

@@ -24,8 +24,8 @@ func NewAuthMiddleware(authSvc *service.AuthService) *AuthMiddleware {
 // On success it calls c.Next(); on failure it aborts with 401 JSON.
 func (m *AuthMiddleware) Handle() gin.HandlerFunc {
 	return func(c *gin.Context) {
-		raw := c.GetHeader("Authorization")
+		token := bearerToken(c)
-		if !strings.HasPrefix(raw, "Bearer ") {
+		if token == "" {
 			c.JSON(http.StatusUnauthorized, errorBody{
 				Code:    domain.ErrUnauthorized.Code(),
 				Message: "authorization header missing or malformed",
@@ -33,9 +33,8 @@ func (m *AuthMiddleware) Handle() gin.HandlerFunc {
 			c.Abort()
 			return
 		}
-		token := strings.TrimPrefix(raw, "Bearer ")
 
-		claims, err := m.authSvc.ParseAccessToken(token)
+		claims, err := m.authSvc.ValidateAccessToken(c.Request.Context(), token)
 		if err != nil {
 			c.JSON(http.StatusUnauthorized, errorBody{
 				Code:    domain.ErrUnauthorized.Code(),
@@ -50,3 +49,18 @@ func (m *AuthMiddleware) Handle() gin.HandlerFunc {
 		c.Next()
 	}
 }
+
+// bearerToken extracts the access token from the Authorization header. As a
+// fallback it accepts an ?access_token= query parameter, but only for GET
+// requests — this lets the browser open media (e.g. /files/{id}/content) via a
+// plain link/new tab, where it can't send the header, without allowing a crafted
+// link to drive a state-changing request.
+func bearerToken(c *gin.Context) string {
+	if raw := c.GetHeader("Authorization"); strings.HasPrefix(raw, "Bearer ") {
+		return strings.TrimPrefix(raw, "Bearer ")
+	}
+	if c.Request.Method == http.MethodGet {
+		return c.Query("access_token")
+	}
+	return ""
+}

backend/internal/handler/pool_handler.go

@@ -0,0 +1,375 @@
+package handler
+
+import (
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+	"tanabata/backend/internal/service"
+)
+
+// PoolHandler handles all /pools endpoints.
+type PoolHandler struct {
+	poolSvc *service.PoolService
+}
+
+// NewPoolHandler creates a PoolHandler.
+func NewPoolHandler(poolSvc *service.PoolService) *PoolHandler {
+	return &PoolHandler{poolSvc: poolSvc}
+}
+
+// ---------------------------------------------------------------------------
+// Response types
+// ---------------------------------------------------------------------------
+
+type poolJSON struct {
+	ID          string  `json:"id"`
+	Name        string  `json:"name"`
+	Notes       *string `json:"notes"`
+	CreatorID   int16   `json:"creator_id"`
+	CreatorName string  `json:"creator_name"`
+	IsPublic    bool    `json:"is_public"`
+	FileCount   int     `json:"file_count"`
+	CreatedAt   string  `json:"created_at"`
+}
+
+type poolFileJSON struct {
+	fileJSON
+	Position int `json:"position"`
+}
+
+func toPoolJSON(p domain.Pool) poolJSON {
+	return poolJSON{
+		ID:          p.ID.String(),
+		Name:        p.Name,
+		Notes:       p.Notes,
+		CreatorID:   p.CreatorID,
+		CreatorName: p.CreatorName,
+		IsPublic:    p.IsPublic,
+		FileCount:   p.FileCount,
+		CreatedAt:   p.CreatedAt.UTC().Format(time.RFC3339),
+	}
+}
+
+func toPoolFileJSON(pf domain.PoolFile) poolFileJSON {
+	return poolFileJSON{
+		fileJSON: toFileJSON(pf.File),
+		Position: pf.Position,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func parsePoolID(c *gin.Context) (uuid.UUID, bool) {
+	id, err := uuid.Parse(c.Param("pool_id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return uuid.UUID{}, false
+	}
+	return id, true
+}
+
+func parsePoolFileParams(c *gin.Context) port.PoolFileListParams {
+	limit := 50
+	if s := c.Query("limit"); s != "" {
+		if n, err := strconv.Atoi(s); err == nil && n > 0 && n <= 200 {
+			limit = n
+		}
+	}
+	return port.PoolFileListParams{
+		Cursor: c.Query("cursor"),
+		Limit:  limit,
+		Filter: c.Query("filter"),
+	}
+}
+
+// ---------------------------------------------------------------------------
+// GET /pools
+// ---------------------------------------------------------------------------
+
+func (h *PoolHandler) List(c *gin.Context) {
+	params := parseOffsetParams(c, "created")
+
+	page, err := h.poolSvc.List(c.Request.Context(), params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]poolJSON, len(page.Items))
+	for i, p := range page.Items {
+		items[i] = toPoolJSON(p)
+	}
+	respondJSON(c, http.StatusOK, gin.H{
+		"items":  items,
+		"total":  page.Total,
+		"offset": page.Offset,
+		"limit":  page.Limit,
+	})
+}
+
+// ---------------------------------------------------------------------------
+// POST /pools
+// ---------------------------------------------------------------------------
+
+func (h *PoolHandler) Create(c *gin.Context) {
+	var body struct {
+		Name     string  `json:"name"      binding:"required"`
+		Notes    *string `json:"notes"`
+		IsPublic *bool   `json:"is_public"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	created, err := h.poolSvc.Create(c.Request.Context(), service.PoolParams{
+		Name:     body.Name,
+		Notes:    body.Notes,
+		IsPublic: body.IsPublic,
+	})
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusCreated, toPoolJSON(*created))
+}
+
+// ---------------------------------------------------------------------------
+// GET /pools/:pool_id
+// ---------------------------------------------------------------------------
+
+func (h *PoolHandler) Get(c *gin.Context) {
+	id, ok := parsePoolID(c)
+	if !ok {
+		return
+	}
+
+	p, err := h.poolSvc.Get(c.Request.Context(), id)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusOK, toPoolJSON(*p))
+}
+
+// ---------------------------------------------------------------------------
+// POST /pools/:pool_id/views
+// ---------------------------------------------------------------------------
+
+// RecordView logs that the current user viewed the pool (activity.pool_views).
+func (h *PoolHandler) RecordView(c *gin.Context) {
+	id, ok := parsePoolID(c)
+	if !ok {
+		return
+	}
+
+	if err := h.poolSvc.RecordView(c.Request.Context(), id); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	c.Status(http.StatusNoContent)
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /pools/:pool_id
+// ---------------------------------------------------------------------------
+
+func (h *PoolHandler) Update(c *gin.Context) {
+	id, ok := parsePoolID(c)
+	if !ok {
+		return
+	}
+
+	var raw map[string]any
+	if err := c.ShouldBindJSON(&raw); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	params := service.PoolParams{}
+	if v, ok := raw["name"]; ok {
+		if s, ok := v.(string); ok {
+			params.Name = s
+		}
+	}
+	if _, ok := raw["notes"]; ok {
+		if raw["notes"] == nil {
+			empty := ""
+			params.Notes = &empty
+		} else if s, ok := raw["notes"].(string); ok {
+			params.Notes = &s
+		}
+	}
+	if v, ok := raw["is_public"]; ok {
+		if b, ok := v.(bool); ok {
+			params.IsPublic = &b
+		}
+	}
+
+	updated, err := h.poolSvc.Update(c.Request.Context(), id, params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusOK, toPoolJSON(*updated))
+}
+
+// ---------------------------------------------------------------------------
+// DELETE /pools/:pool_id
+// ---------------------------------------------------------------------------
+
+func (h *PoolHandler) Delete(c *gin.Context) {
+	id, ok := parsePoolID(c)
+	if !ok {
+		return
+	}
+
+	if err := h.poolSvc.Delete(c.Request.Context(), id); err != nil {
+		respondError(c, err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// ---------------------------------------------------------------------------
+// GET /pools/:pool_id/files
+// ---------------------------------------------------------------------------
+
+func (h *PoolHandler) ListFiles(c *gin.Context) {
+	poolID, ok := parsePoolID(c)
+	if !ok {
+		return
+	}
+
+	params := parsePoolFileParams(c)
+
+	page, err := h.poolSvc.ListFiles(c.Request.Context(), poolID, params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]poolFileJSON, len(page.Items))
+	for i, pf := range page.Items {
+		items[i] = toPoolFileJSON(pf)
+	}
+	respondJSON(c, http.StatusOK, gin.H{
+		"items":       items,
+		"next_cursor": page.NextCursor,
+	})
+}
+
+// ---------------------------------------------------------------------------
+// POST /pools/:pool_id/files
+// ---------------------------------------------------------------------------
+
+func (h *PoolHandler) AddFiles(c *gin.Context) {
+	poolID, ok := parsePoolID(c)
+	if !ok {
+		return
+	}
+
+	var body struct {
+		FileIDs  []string `json:"file_ids" binding:"required"`
+		Position *int     `json:"position"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	fileIDs := make([]uuid.UUID, 0, len(body.FileIDs))
+	for _, s := range body.FileIDs {
+		id, err := uuid.Parse(s)
+		if err != nil {
+			respondError(c, domain.ErrValidation)
+			return
+		}
+		fileIDs = append(fileIDs, id)
+	}
+
+	if err := h.poolSvc.AddFiles(c.Request.Context(), poolID, fileIDs, body.Position); err != nil {
+		respondError(c, err)
+		return
+	}
+	c.Status(http.StatusCreated)
+}
+
+// ---------------------------------------------------------------------------
+// POST /pools/:pool_id/files/remove
+// ---------------------------------------------------------------------------
+
+func (h *PoolHandler) RemoveFiles(c *gin.Context) {
+	poolID, ok := parsePoolID(c)
+	if !ok {
+		return
+	}
+
+	var body struct {
+		FileIDs []string `json:"file_ids" binding:"required"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	fileIDs := make([]uuid.UUID, 0, len(body.FileIDs))
+	for _, s := range body.FileIDs {
+		id, err := uuid.Parse(s)
+		if err != nil {
+			respondError(c, domain.ErrValidation)
+			return
+		}
+		fileIDs = append(fileIDs, id)
+	}
+
+	if err := h.poolSvc.RemoveFiles(c.Request.Context(), poolID, fileIDs); err != nil {
+		respondError(c, err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// ---------------------------------------------------------------------------
+// PUT /pools/:pool_id/files/reorder
+// ---------------------------------------------------------------------------
+
+func (h *PoolHandler) Reorder(c *gin.Context) {
+	poolID, ok := parsePoolID(c)
+	if !ok {
+		return
+	}
+
+	var body struct {
+		FileIDs []string `json:"file_ids" binding:"required"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	fileIDs := make([]uuid.UUID, 0, len(body.FileIDs))
+	for _, s := range body.FileIDs {
+		id, err := uuid.Parse(s)
+		if err != nil {
+			respondError(c, domain.ErrValidation)
+			return
+		}
+		fileIDs = append(fileIDs, id)
+	}
+
+	if err := h.poolSvc.Reorder(c.Request.Context(), poolID, fileIDs); err != nil {
+		respondError(c, err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}

backend/internal/handler/ratelimit.go

@@ -0,0 +1,77 @@
+package handler
+
+import (
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// rateLimiter is a process-local, fixed-window per-key request limiter used to
+// throttle unauthenticated endpoints (login, refresh) against brute force. It
+// is best-effort: counts live in memory and reset on restart.
+type rateLimiter struct {
+	mu     sync.Mutex
+	counts map[string]*rateWindow
+	limit  int
+	window time.Duration
+}
+
+type rateWindow struct {
+	count int
+	reset time.Time
+}
+
+// newRateLimiter allows up to limit requests per key within each window.
+func newRateLimiter(limit int, window time.Duration) *rateLimiter {
+	return &rateLimiter{
+		counts: make(map[string]*rateWindow),
+		limit:  limit,
+		window: window,
+	}
+}
+
+// allow records a request for key and reports whether it is within the limit.
+func (rl *rateLimiter) allow(key string) bool {
+	now := time.Now()
+
+	rl.mu.Lock()
+	defer rl.mu.Unlock()
+
+	// Opportunistically prune expired entries so the map cannot grow without
+	// bound under a flood of distinct client IPs.
+	if len(rl.counts) > 10000 {
+		for k, w := range rl.counts {
+			if now.After(w.reset) {
+				delete(rl.counts, k)
+			}
+		}
+	}
+
+	w, ok := rl.counts[key]
+	if !ok || now.After(w.reset) {
+		rl.counts[key] = &rateWindow{count: 1, reset: now.Add(rl.window)}
+		return true
+	}
+	if w.count >= rl.limit {
+		return false
+	}
+	w.count++
+	return true
+}
+
+// Middleware throttles requests by client IP, returning 429 when over the limit.
+func (rl *rateLimiter) Middleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if !rl.allow(c.ClientIP()) {
+			c.JSON(http.StatusTooManyRequests, errorBody{
+				Code:    "rate_limited",
+				Message: "too many requests, please try again later",
+			})
+			c.Abort()
+			return
+		}
+		c.Next()
+	}
+}

backend/internal/handler/router.go

@@ -2,14 +2,39 @@ package handler
 
 import (
 	"net/http"
+	"time"
 
 	"github.com/gin-gonic/gin"
 )
 
+// securityHeaders sets conservative response headers on every response: prevent
+// MIME sniffing of served file content, forbid framing, and suppress the
+// Referer header on outbound navigations.
+func securityHeaders() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		h := c.Writer.Header()
+		h.Set("X-Content-Type-Options", "nosniff")
+		h.Set("X-Frame-Options", "DENY")
+		h.Set("Referrer-Policy", "no-referrer")
+		c.Next()
+	}
+}
+
 // NewRouter builds and returns a configured Gin engine.
-func NewRouter(auth *AuthMiddleware, authHandler *AuthHandler, fileHandler *FileHandler) *gin.Engine {
+func NewRouter(
+	auth *AuthMiddleware,
+	authHandler *AuthHandler,
+	fileHandler *FileHandler,
+	tagHandler *TagHandler,
+	categoryHandler *CategoryHandler,
+	poolHandler *PoolHandler,
+	userHandler *UserHandler,
+	aclHandler *ACLHandler,
+	auditHandler *AuditHandler,
+	staticDir string,
+) *gin.Engine {
 	r := gin.New()
-	r.Use(gin.Logger(), gin.Recovery())
+	r.Use(gin.Logger(), gin.Recovery(), securityHeaders())
 
 	// Health check — no auth required.
 	r.GET("/health", func(c *gin.Context) {
@@ -18,11 +43,15 @@ func NewRouter(auth *AuthMiddleware, authHandler *AuthHandler, fileHandler *File
 
 	v1 := r.Group("/api/v1")
 
-	// Auth endpoints — login and refresh are public; others require a valid token.
+	// -------------------------------------------------------------------------
+	// Auth
+	// -------------------------------------------------------------------------
 	authGroup := v1.Group("/auth")
 	{
-		authGroup.POST("/login", authHandler.Login)
+		// Throttle credential endpoints per client IP to slow brute force.
-		authGroup.POST("/refresh", authHandler.Refresh)
+		authLimiter := newRateLimiter(10, time.Minute).Middleware()
+		authGroup.POST("/login", authLimiter, authHandler.Login)
+		authGroup.POST("/refresh", authLimiter, authHandler.Refresh)
 
 		protected := authGroup.Group("", auth.Handle())
 		{
@@ -32,13 +61,15 @@ func NewRouter(auth *AuthMiddleware, authHandler *AuthHandler, fileHandler *File
 		}
 	}
 
-	// File endpoints — all require authentication.
+	// -------------------------------------------------------------------------
+	// Files (all require auth)
+	// -------------------------------------------------------------------------
 	files := v1.Group("/files", auth.Handle())
 	{
 		files.GET("", fileHandler.List)
 		files.POST("", fileHandler.Upload)
 
-		// Bulk routes must be registered before /:id to avoid ambiguity.
+		// Bulk + import routes registered before /:id to prevent param collision.
 		files.POST("/bulk/tags", fileHandler.BulkSetTags)
 		files.POST("/bulk/delete", fileHandler.BulkDelete)
 		files.POST("/bulk/common-tags", fileHandler.CommonTags)
@@ -53,13 +84,109 @@ func NewRouter(auth *AuthMiddleware, authHandler *AuthHandler, fileHandler *File
 		files.PUT("/:id/content", fileHandler.ReplaceContent)
 		files.GET("/:id/thumbnail", fileHandler.GetThumbnail)
 		files.GET("/:id/preview", fileHandler.GetPreview)
+		files.POST("/:id/views", fileHandler.RecordView)
 		files.POST("/:id/restore", fileHandler.Restore)
 		files.DELETE("/:id/permanent", fileHandler.PermanentDelete)
 
-		files.GET("/:id/tags", fileHandler.ListTags)
+		// File–tag relations — served by TagHandler for auto-rule support.
-		files.PUT("/:id/tags", fileHandler.SetTags)
+		files.GET("/:id/tags", tagHandler.FileListTags)
-		files.PUT("/:id/tags/:tag_id", fileHandler.AddTag)
+		files.PUT("/:id/tags", tagHandler.FileSetTags)
-		files.DELETE("/:id/tags/:tag_id", fileHandler.RemoveTag)
+		files.PUT("/:id/tags/:tag_id", tagHandler.FileAddTag)
+		files.DELETE("/:id/tags/:tag_id", tagHandler.FileRemoveTag)
+	}
+
+	// -------------------------------------------------------------------------
+	// Tags (all require auth)
+	// -------------------------------------------------------------------------
+	tags := v1.Group("/tags", auth.Handle())
+	{
+		tags.GET("", tagHandler.List)
+		tags.POST("", tagHandler.Create)
+
+		tags.GET("/:tag_id", tagHandler.Get)
+		tags.PATCH("/:tag_id", tagHandler.Update)
+		tags.DELETE("/:tag_id", tagHandler.Delete)
+
+		tags.GET("/:tag_id/files", tagHandler.ListFiles)
+
+		tags.GET("/:tag_id/rules", tagHandler.ListRules)
+		tags.POST("/:tag_id/rules", tagHandler.CreateRule)
+		tags.PATCH("/:tag_id/rules/:then_tag_id", tagHandler.PatchRule)
+		tags.DELETE("/:tag_id/rules/:then_tag_id", tagHandler.DeleteRule)
+	}
+
+	// -------------------------------------------------------------------------
+	// Categories (all require auth)
+	// -------------------------------------------------------------------------
+	categories := v1.Group("/categories", auth.Handle())
+	{
+		categories.GET("", categoryHandler.List)
+		categories.POST("", categoryHandler.Create)
+
+		categories.GET("/:category_id", categoryHandler.Get)
+		categories.PATCH("/:category_id", categoryHandler.Update)
+		categories.DELETE("/:category_id", categoryHandler.Delete)
+
+		categories.GET("/:category_id/tags", categoryHandler.ListTags)
+	}
+
+	// -------------------------------------------------------------------------
+	// Pools (all require auth)
+	// -------------------------------------------------------------------------
+	pools := v1.Group("/pools", auth.Handle())
+	{
+		pools.GET("", poolHandler.List)
+		pools.POST("", poolHandler.Create)
+
+		pools.GET("/:pool_id", poolHandler.Get)
+		pools.PATCH("/:pool_id", poolHandler.Update)
+		pools.DELETE("/:pool_id", poolHandler.Delete)
+		pools.POST("/:pool_id/views", poolHandler.RecordView)
+
+		// Sub-routes registered before /:pool_id/files to avoid param conflicts.
+		pools.POST("/:pool_id/files/remove", poolHandler.RemoveFiles)
+		pools.PUT("/:pool_id/files/reorder", poolHandler.Reorder)
+
+		pools.GET("/:pool_id/files", poolHandler.ListFiles)
+		pools.POST("/:pool_id/files", poolHandler.AddFiles)
+	}
+
+	// -------------------------------------------------------------------------
+	// Users (auth required; admin checks enforced in handler)
+	// -------------------------------------------------------------------------
+	users := v1.Group("/users", auth.Handle())
+	{
+		// /users/me must be registered before /:user_id to avoid param capture.
+		users.GET("/me", userHandler.GetMe)
+		users.PATCH("/me", userHandler.UpdateMe)
+
+		users.GET("", userHandler.List)
+		users.POST("", userHandler.Create)
+
+		users.GET("/:user_id", userHandler.Get)
+		users.PATCH("/:user_id", userHandler.UpdateAdmin)
+		users.DELETE("/:user_id", userHandler.Delete)
+	}
+
+	// -------------------------------------------------------------------------
+	// ACL (auth required)
+	// -------------------------------------------------------------------------
+	acl := v1.Group("/acl", auth.Handle())
+	{
+		acl.GET("/:object_type/:object_id", aclHandler.GetPermissions)
+		acl.PUT("/:object_type/:object_id", aclHandler.SetPermissions)
+	}
+
+	// -------------------------------------------------------------------------
+	// Audit (auth required; admin check enforced in handler)
+	// -------------------------------------------------------------------------
+	v1.GET("/audit", auth.Handle(), auditHandler.List)
+
+	// Serve the built single-page app on the same port as the API. When
+	// staticDir is empty (local development) the Vite dev server serves the UI
+	// instead, so the API runs standalone and unknown routes 404 normally.
+	if staticDir != "" {
+		r.NoRoute(spaHandler(staticDir))
 	}
 
 	return r

backend/internal/handler/static.go

@@ -0,0 +1,74 @@
+package handler
+
+import (
+	"mime"
+	"net/http"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+func init() {
+	// Go's mime table doesn't know .webmanifest; register it so the PWA manifest
+	// is served as JSON and isn't rejected by the X-Content-Type-Options header.
+	_ = mime.AddExtensionType(".webmanifest", "application/manifest+json")
+}
+
+// spaHandler serves the built single-page app from dir. It is wired as the
+// router's NoRoute handler, so it only sees requests that matched no API route.
+//
+// A request whose path maps to a real file on disk is served directly (with
+// cache headers tuned to SvelteKit's adapter-static output). Anything else
+// falls back to index.html so the client-side router can resolve deep links
+// like /pools/123. Unknown /api/ paths return a JSON 404 instead of the HTML
+// shell, keeping API error responses machine-readable.
+func spaHandler(dir string) gin.HandlerFunc {
+	indexPath := filepath.Join(dir, "index.html")
+
+	return func(c *gin.Context) {
+		reqPath := c.Request.URL.Path
+
+		if strings.HasPrefix(reqPath, "/api/") {
+			c.JSON(http.StatusNotFound, errorBody{
+				Code:    "not_found",
+				Message: "resource not found",
+			})
+			return
+		}
+
+		// Resolve the request to a path inside dir. Cleaning an absolute path
+		// collapses any "../" segments before the join, so the result can never
+		// escape dir — this is the traversal guard.
+		clean := path.Clean("/" + reqPath)
+		target := filepath.Join(dir, filepath.FromSlash(clean))
+
+		if info, err := os.Stat(target); err == nil && !info.IsDir() {
+			c.Header("Cache-Control", cacheControl(clean))
+			c.File(target)
+			return
+		}
+
+		// SPA fallback: serve the shell, never cached so a new deploy is picked
+		// up immediately on the next navigation.
+		c.Header("Cache-Control", "no-cache")
+		c.File(indexPath)
+	}
+}
+
+// cacheControl returns the Cache-Control value for a served static asset.
+// SvelteKit emits content-hashed files under /_app/immutable — those are safe
+// to cache forever. The service worker must never be cached, or clients pin to
+// a stale shell. Everything else gets a short, revalidated TTL.
+func cacheControl(p string) string {
+	switch {
+	case strings.HasPrefix(p, "/_app/immutable/"):
+		return "public, max-age=31536000, immutable"
+	case p == "/service-worker.js":
+		return "no-cache"
+	default:
+		return "public, max-age=3600"
+	}
+}

backend/internal/handler/tag_handler.go

@@ -0,0 +1,552 @@
+package handler
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+	"tanabata/backend/internal/service"
+)
+
+// TagHandler handles all /tags endpoints.
+type TagHandler struct {
+	tagSvc  *service.TagService
+	fileSvc *service.FileService
+}
+
+// NewTagHandler creates a TagHandler.
+func NewTagHandler(tagSvc *service.TagService, fileSvc *service.FileService) *TagHandler {
+	return &TagHandler{tagSvc: tagSvc, fileSvc: fileSvc}
+}
+
+// ---------------------------------------------------------------------------
+// Response types
+// ---------------------------------------------------------------------------
+
+type tagRuleJSON struct {
+	WhenTagID   string `json:"when_tag_id"`
+	ThenTagID   string `json:"then_tag_id"`
+	ThenTagName string `json:"then_tag_name"`
+	IsActive    bool   `json:"is_active"`
+}
+
+func toTagRuleJSON(r domain.TagRule) tagRuleJSON {
+	return tagRuleJSON{
+		WhenTagID:   r.WhenTagID.String(),
+		ThenTagID:   r.ThenTagID.String(),
+		ThenTagName: r.ThenTagName,
+		IsActive:    r.IsActive,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func parseTagID(c *gin.Context) (uuid.UUID, bool) {
+	id, err := uuid.Parse(c.Param("tag_id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return uuid.UUID{}, false
+	}
+	return id, true
+}
+
+func parseOffsetParams(c *gin.Context, defaultSort string) port.OffsetParams {
+	limit := 50
+	if s := c.Query("limit"); s != "" {
+		if n, err := strconv.Atoi(s); err == nil && n > 0 && n <= 200 {
+			limit = n
+		}
+	}
+	offset := 0
+	if s := c.Query("offset"); s != "" {
+		if n, err := strconv.Atoi(s); err == nil && n >= 0 {
+			offset = n
+		}
+	}
+	sort := c.DefaultQuery("sort", defaultSort)
+	order := c.DefaultQuery("order", "desc")
+	search := c.Query("search")
+	return port.OffsetParams{Sort: sort, Order: order, Search: search, Limit: limit, Offset: offset}
+}
+
+// ---------------------------------------------------------------------------
+// GET /tags
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) List(c *gin.Context) {
+	params := parseOffsetParams(c, "created")
+
+	page, err := h.tagSvc.List(c.Request.Context(), params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]tagJSON, len(page.Items))
+	for i, t := range page.Items {
+		items[i] = toTagJSON(t)
+	}
+	respondJSON(c, http.StatusOK, gin.H{
+		"items":  items,
+		"total":  page.Total,
+		"offset": page.Offset,
+		"limit":  page.Limit,
+	})
+}
+
+// ---------------------------------------------------------------------------
+// POST /tags
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) Create(c *gin.Context) {
+	var body struct {
+		Name       string  `json:"name"       binding:"required"`
+		Notes      *string `json:"notes"`
+		Color      *string `json:"color"`
+		CategoryID *string `json:"category_id"`
+		IsPublic   *bool   `json:"is_public"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	params := service.TagParams{
+		Name:     body.Name,
+		Notes:    body.Notes,
+		Color:    body.Color,
+		IsPublic: body.IsPublic,
+	}
+	if body.CategoryID != nil {
+		id, err := uuid.Parse(*body.CategoryID)
+		if err != nil {
+			respondError(c, domain.ErrValidation)
+			return
+		}
+		params.CategoryID = &id
+	}
+
+	t, err := h.tagSvc.Create(c.Request.Context(), params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	respondJSON(c, http.StatusCreated, toTagJSON(*t))
+}
+
+// ---------------------------------------------------------------------------
+// GET /tags/:tag_id
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) Get(c *gin.Context) {
+	id, ok := parseTagID(c)
+	if !ok {
+		return
+	}
+
+	t, err := h.tagSvc.Get(c.Request.Context(), id)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	respondJSON(c, http.StatusOK, toTagJSON(*t))
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /tags/:tag_id
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) Update(c *gin.Context) {
+	id, ok := parseTagID(c)
+	if !ok {
+		return
+	}
+
+	// Use a raw map to distinguish "field absent" from "field = null".
+	var raw map[string]any
+	if err := c.ShouldBindJSON(&raw); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	params := service.TagParams{}
+
+	if v, ok := raw["name"]; ok {
+		if s, ok := v.(string); ok {
+			params.Name = s
+		}
+	}
+	if _, ok := raw["notes"]; ok {
+		if raw["notes"] == nil {
+			params.Notes = ptr("")
+		} else if s, ok := raw["notes"].(string); ok {
+			params.Notes = &s
+		}
+	}
+	if _, ok := raw["color"]; ok {
+		if raw["color"] == nil {
+			nilStr := ""
+			params.Color = &nilStr
+		} else if s, ok := raw["color"].(string); ok {
+			params.Color = &s
+		}
+	}
+	if _, ok := raw["category_id"]; ok {
+		if raw["category_id"] == nil {
+			nilID := uuid.Nil
+			params.CategoryID = &nilID // signals "unassign"
+		} else if s, ok := raw["category_id"].(string); ok {
+			cid, err := uuid.Parse(s)
+			if err != nil {
+				respondError(c, domain.ErrValidation)
+				return
+			}
+			params.CategoryID = &cid
+		}
+	}
+	if v, ok := raw["is_public"]; ok {
+		if b, ok := v.(bool); ok {
+			params.IsPublic = &b
+		}
+	}
+
+	t, err := h.tagSvc.Update(c.Request.Context(), id, params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	respondJSON(c, http.StatusOK, toTagJSON(*t))
+}
+
+// ---------------------------------------------------------------------------
+// DELETE /tags/:tag_id
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) Delete(c *gin.Context) {
+	id, ok := parseTagID(c)
+	if !ok {
+		return
+	}
+
+	if err := h.tagSvc.Delete(c.Request.Context(), id); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	c.Status(http.StatusNoContent)
+}
+
+// ---------------------------------------------------------------------------
+// GET /tags/:tag_id/files
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) ListFiles(c *gin.Context) {
+	id, ok := parseTagID(c)
+	if !ok {
+		return
+	}
+
+	limit := 50
+	if s := c.Query("limit"); s != "" {
+		if n, err := strconv.Atoi(s); err == nil && n > 0 && n <= 200 {
+			limit = n
+		}
+	}
+
+	// Delegate to file service with a tag filter.
+	page, err := h.fileSvc.List(c.Request.Context(), domain.FileListParams{
+		Cursor:    c.Query("cursor"),
+		Direction: "forward",
+		Limit:     limit,
+		Sort:      "created",
+		Order:     "desc",
+		Filter:    "{t=" + id.String() + "}",
+	})
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]fileJSON, len(page.Items))
+	for i, f := range page.Items {
+		items[i] = toFileJSON(f)
+	}
+	respondJSON(c, http.StatusOK, gin.H{
+		"items":       items,
+		"next_cursor": page.NextCursor,
+		"prev_cursor": page.PrevCursor,
+	})
+}
+
+// ---------------------------------------------------------------------------
+// GET /tags/:tag_id/rules
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) ListRules(c *gin.Context) {
+	id, ok := parseTagID(c)
+	if !ok {
+		return
+	}
+
+	rules, err := h.tagSvc.ListRules(c.Request.Context(), id)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]tagRuleJSON, len(rules))
+	for i, r := range rules {
+		items[i] = toTagRuleJSON(r)
+	}
+	respondJSON(c, http.StatusOK, items)
+}
+
+// ---------------------------------------------------------------------------
+// POST /tags/:tag_id/rules
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) CreateRule(c *gin.Context) {
+	whenTagID, ok := parseTagID(c)
+	if !ok {
+		return
+	}
+
+	var body struct {
+		ThenTagID       string `json:"then_tag_id" binding:"required"`
+		IsActive        *bool  `json:"is_active"`
+		ApplyToExisting *bool  `json:"apply_to_existing"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	thenTagID, err := uuid.Parse(body.ThenTagID)
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	isActive := true
+	if body.IsActive != nil {
+		isActive = *body.IsActive
+	}
+	applyToExisting := true
+	if body.ApplyToExisting != nil {
+		applyToExisting = *body.ApplyToExisting
+	}
+
+	rule, err := h.tagSvc.CreateRule(c.Request.Context(), whenTagID, thenTagID, isActive, applyToExisting)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	respondJSON(c, http.StatusCreated, toTagRuleJSON(*rule))
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /tags/:tag_id/rules/:then_tag_id
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) PatchRule(c *gin.Context) {
+	whenTagID, ok := parseTagID(c)
+	if !ok {
+		return
+	}
+
+	thenTagID, err := uuid.Parse(c.Param("then_tag_id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	var body struct {
+		IsActive        *bool `json:"is_active"`
+		ApplyToExisting *bool `json:"apply_to_existing"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.IsActive == nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	applyToExisting := false
+	if body.ApplyToExisting != nil {
+		applyToExisting = *body.ApplyToExisting
+	}
+
+	rule, err := h.tagSvc.SetRuleActive(c.Request.Context(), whenTagID, thenTagID, *body.IsActive, applyToExisting)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	respondJSON(c, http.StatusOK, toTagRuleJSON(*rule))
+}
+
+// ---------------------------------------------------------------------------
+// DELETE /tags/:tag_id/rules/:then_tag_id
+// ---------------------------------------------------------------------------
+
+func (h *TagHandler) DeleteRule(c *gin.Context) {
+	whenTagID, ok := parseTagID(c)
+	if !ok {
+		return
+	}
+
+	thenTagID, err := uuid.Parse(c.Param("then_tag_id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	if err := h.tagSvc.DeleteRule(c.Request.Context(), whenTagID, thenTagID); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	c.Status(http.StatusNoContent)
+}
+
+// ---------------------------------------------------------------------------
+// File-tag endpoints wired through TagService
+// (called from file routes, shared handler logic lives here)
+// ---------------------------------------------------------------------------
+
+// FileListTags handles GET /files/:id/tags.
+func (h *TagHandler) FileListTags(c *gin.Context) {
+	fileID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	if err := h.fileSvc.AuthorizeView(c.Request.Context(), fileID); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	tags, err := h.tagSvc.ListFileTags(c.Request.Context(), fileID)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]tagJSON, len(tags))
+	for i, t := range tags {
+		items[i] = toTagJSON(t)
+	}
+	respondJSON(c, http.StatusOK, items)
+}
+
+// FileSetTags handles PUT /files/:id/tags.
+func (h *TagHandler) FileSetTags(c *gin.Context) {
+	fileID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	var body struct {
+		TagIDs []string `json:"tag_ids" binding:"required"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	tagIDs, err := parseUUIDs(body.TagIDs)
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	if err := h.fileSvc.AuthorizeEdit(c.Request.Context(), fileID); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	tags, err := h.tagSvc.SetFileTags(c.Request.Context(), fileID, tagIDs)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]tagJSON, len(tags))
+	for i, t := range tags {
+		items[i] = toTagJSON(t)
+	}
+	respondJSON(c, http.StatusOK, items)
+}
+
+// FileAddTag handles PUT /files/:id/tags/:tag_id.
+func (h *TagHandler) FileAddTag(c *gin.Context) {
+	fileID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+	tagID, err := uuid.Parse(c.Param("tag_id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	if err := h.fileSvc.AuthorizeEdit(c.Request.Context(), fileID); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	tags, err := h.tagSvc.AddFileTag(c.Request.Context(), fileID, tagID)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]tagJSON, len(tags))
+	for i, t := range tags {
+		items[i] = toTagJSON(t)
+	}
+	respondJSON(c, http.StatusOK, items)
+}
+
+// FileRemoveTag handles DELETE /files/:id/tags/:tag_id.
+func (h *TagHandler) FileRemoveTag(c *gin.Context) {
+	fileID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+	tagID, err := uuid.Parse(c.Param("tag_id"))
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	if err := h.fileSvc.AuthorizeEdit(c.Request.Context(), fileID); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	if err := h.tagSvc.RemoveFileTag(c.Request.Context(), fileID, tagID); err != nil {
+		respondError(c, err)
+		return
+	}
+
+	c.Status(http.StatusNoContent)
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func ptr(s string) *string { return &s }

backend/internal/handler/user_handler.go

@@ -0,0 +1,258 @@
+package handler
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+	"tanabata/backend/internal/service"
+)
+
+// UserHandler handles all /users endpoints.
+type UserHandler struct {
+	userSvc *service.UserService
+}
+
+// NewUserHandler creates a UserHandler.
+func NewUserHandler(userSvc *service.UserService) *UserHandler {
+	return &UserHandler{userSvc: userSvc}
+}
+
+// ---------------------------------------------------------------------------
+// Response types
+// ---------------------------------------------------------------------------
+
+type userJSON struct {
+	ID        int16  `json:"id"`
+	Name      string `json:"name"`
+	IsAdmin   bool   `json:"is_admin"`
+	CanCreate bool   `json:"can_create"`
+	IsBlocked bool   `json:"is_blocked"`
+}
+
+func toUserJSON(u domain.User) userJSON {
+	return userJSON{
+		ID:        u.ID,
+		Name:      u.Name,
+		IsAdmin:   u.IsAdmin,
+		CanCreate: u.CanCreate,
+		IsBlocked: u.IsBlocked,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func requireAdmin(c *gin.Context) bool {
+	_, isAdmin, _ := domain.UserFromContext(c.Request.Context())
+	if !isAdmin {
+		respondError(c, domain.ErrForbidden)
+		return false
+	}
+	return true
+}
+
+func parseUserID(c *gin.Context) (int16, bool) {
+	n, err := strconv.ParseInt(c.Param("user_id"), 10, 16)
+	if err != nil {
+		respondError(c, domain.ErrValidation)
+		return 0, false
+	}
+	return int16(n), true
+}
+
+// ---------------------------------------------------------------------------
+// GET /users/me
+// ---------------------------------------------------------------------------
+
+func (h *UserHandler) GetMe(c *gin.Context) {
+	u, err := h.userSvc.GetMe(c.Request.Context())
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusOK, toUserJSON(*u))
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /users/me
+// ---------------------------------------------------------------------------
+
+func (h *UserHandler) UpdateMe(c *gin.Context) {
+	var body struct {
+		Name     string  `json:"name"`
+		Password *string `json:"password"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	updated, err := h.userSvc.UpdateMe(c.Request.Context(), service.UpdateMeParams{
+		Name:     body.Name,
+		Password: body.Password,
+	})
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusOK, toUserJSON(*updated))
+}
+
+// ---------------------------------------------------------------------------
+// GET /users  (admin)
+// ---------------------------------------------------------------------------
+
+func (h *UserHandler) List(c *gin.Context) {
+	if !requireAdmin(c) {
+		return
+	}
+
+	params := port.OffsetParams{
+		Sort:  c.DefaultQuery("sort", "id"),
+		Order: c.DefaultQuery("order", "asc"),
+	}
+	if s := c.Query("limit"); s != "" {
+		if n, err := strconv.Atoi(s); err == nil {
+			params.Limit = n
+		}
+	}
+	if s := c.Query("offset"); s != "" {
+		if n, err := strconv.Atoi(s); err == nil {
+			params.Offset = n
+		}
+	}
+
+	page, err := h.userSvc.List(c.Request.Context(), params)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+
+	items := make([]userJSON, len(page.Items))
+	for i, u := range page.Items {
+		items[i] = toUserJSON(u)
+	}
+	respondJSON(c, http.StatusOK, gin.H{
+		"items":  items,
+		"total":  page.Total,
+		"offset": page.Offset,
+		"limit":  page.Limit,
+	})
+}
+
+// ---------------------------------------------------------------------------
+// POST /users  (admin)
+// ---------------------------------------------------------------------------
+
+func (h *UserHandler) Create(c *gin.Context) {
+	if !requireAdmin(c) {
+		return
+	}
+
+	var body struct {
+		Name      string `json:"name"     binding:"required"`
+		Password  string `json:"password" binding:"required"`
+		IsAdmin   bool   `json:"is_admin"`
+		CanCreate bool   `json:"can_create"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	created, err := h.userSvc.Create(c.Request.Context(), service.CreateUserParams{
+		Name:      body.Name,
+		Password:  body.Password,
+		IsAdmin:   body.IsAdmin,
+		CanCreate: body.CanCreate,
+	})
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusCreated, toUserJSON(*created))
+}
+
+// ---------------------------------------------------------------------------
+// GET /users/:user_id  (admin)
+// ---------------------------------------------------------------------------
+
+func (h *UserHandler) Get(c *gin.Context) {
+	if !requireAdmin(c) {
+		return
+	}
+
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	u, err := h.userSvc.Get(c.Request.Context(), id)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusOK, toUserJSON(*u))
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /users/:user_id  (admin)
+// ---------------------------------------------------------------------------
+
+func (h *UserHandler) UpdateAdmin(c *gin.Context) {
+	if !requireAdmin(c) {
+		return
+	}
+
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	var body struct {
+		IsAdmin   *bool `json:"is_admin"`
+		CanCreate *bool `json:"can_create"`
+		IsBlocked *bool `json:"is_blocked"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		respondError(c, domain.ErrValidation)
+		return
+	}
+
+	updated, err := h.userSvc.UpdateAdmin(c.Request.Context(), id, service.UpdateAdminParams{
+		IsAdmin:   body.IsAdmin,
+		CanCreate: body.CanCreate,
+		IsBlocked: body.IsBlocked,
+	})
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	respondJSON(c, http.StatusOK, toUserJSON(*updated))
+}
+
+// ---------------------------------------------------------------------------
+// DELETE /users/:user_id  (admin)
+// ---------------------------------------------------------------------------
+
+func (h *UserHandler) Delete(c *gin.Context) {
+	if !requireAdmin(c) {
+		return
+	}
+
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	if err := h.userSvc.Delete(c.Request.Context(), id); err != nil {
+		respondError(c, err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}

backend/internal/port/repository.go

@@ -22,6 +22,13 @@ type OffsetParams struct {
 	Search string
 	Offset int
 	Limit  int
+
+	// Visibility — populated by the service from the request context. When
+	// ViewerIsAdmin is false the repository restricts results to rows the viewer
+	// may see (public, owned, or explicitly granted). Ignored by user listing,
+	// which is admin-only.
+	ViewerID      int16
+	ViewerIsAdmin bool
 }
 
 // PoolFileListParams holds parameters for listing files inside a pool.
@@ -52,6 +59,13 @@ type FileRepo interface {
 	ListTags(ctx context.Context, fileID uuid.UUID) ([]domain.Tag, error)
 	// SetTags replaces all tags on a file (full replace semantics).
 	SetTags(ctx context.Context, fileID uuid.UUID, tagIDs []uuid.UUID) error
+
+	// RecordView appends a view-history row (activity.file_views) for the user.
+	RecordView(ctx context.Context, fileID uuid.UUID, userID int16) error
+	// RecordTagUses logs the tags referenced in a filter DSL to
+	// activity.tag_uses, flagging each included or excluded. Best-effort
+	// analytics — callers may ignore the error.
+	RecordTagUses(ctx context.Context, userID int16, filterDSL string) error
 }
 
 // TagRepo is the persistence interface for tags.
@@ -63,6 +77,19 @@ type TagRepo interface {
 	Create(ctx context.Context, t *domain.Tag) (*domain.Tag, error)
 	Update(ctx context.Context, id uuid.UUID, t *domain.Tag) (*domain.Tag, error)
 	Delete(ctx context.Context, id uuid.UUID) error
+
+	// ListByFile returns all tags assigned to a specific file, ordered by name.
+	ListByFile(ctx context.Context, fileID uuid.UUID) ([]domain.Tag, error)
+	// AddFileTag inserts a single file→tag relation. No-op if already present.
+	AddFileTag(ctx context.Context, fileID, tagID uuid.UUID) error
+	// RemoveFileTag deletes a single file→tag relation.
+	RemoveFileTag(ctx context.Context, fileID, tagID uuid.UUID) error
+	// SetFileTags replaces all tags on a file (full replace semantics).
+	SetFileTags(ctx context.Context, fileID uuid.UUID, tagIDs []uuid.UUID) error
+	// CommonTagsForFiles returns tags present on every one of the given files.
+	CommonTagsForFiles(ctx context.Context, fileIDs []uuid.UUID) ([]domain.Tag, error)
+	// PartialTagsForFiles returns tags present on some but not all of the given files.
+	PartialTagsForFiles(ctx context.Context, fileIDs []uuid.UUID) ([]domain.Tag, error)
 }
 
 // TagRuleRepo is the persistence interface for auto-tag rules.
@@ -70,8 +97,10 @@ type TagRuleRepo interface {
 	// ListByTag returns all rules where WhenTagID == tagID.
 	ListByTag(ctx context.Context, tagID uuid.UUID) ([]domain.TagRule, error)
 	Create(ctx context.Context, r domain.TagRule) (*domain.TagRule, error)
-	// SetActive toggles a rule's is_active flag.
+	// SetActive toggles a rule's is_active flag. When active and applyToExisting
-	SetActive(ctx context.Context, whenTagID, thenTagID uuid.UUID, active bool) error
+	// are both true, the full transitive expansion of thenTagID is retroactively
+	// applied to all files that already carry whenTagID.
+	SetActive(ctx context.Context, whenTagID, thenTagID uuid.UUID, active, applyToExisting bool) error
 	Delete(ctx context.Context, whenTagID, thenTagID uuid.UUID) error
 }
 
@@ -100,6 +129,9 @@ type PoolRepo interface {
 	RemoveFiles(ctx context.Context, poolID uuid.UUID, fileIDs []uuid.UUID) error
 	// Reorder sets the full ordered sequence of file IDs in the pool.
 	Reorder(ctx context.Context, poolID uuid.UUID, fileIDs []uuid.UUID) error
+
+	// RecordView appends a view-history row (activity.pool_views) for the user.
+	RecordView(ctx context.Context, poolID uuid.UUID, userID int16) error
 }
 
 // UserRepo is the persistence interface for users.
@@ -117,6 +149,9 @@ type UserRepo interface {
 type SessionRepo interface {
 	// ListByUser returns all active sessions for a user.
 	ListByUser(ctx context.Context, userID int16) (*domain.SessionList, error)
+	// GetByID returns an active session by its ID, or ErrNotFound if it does not
+	// exist or has been deactivated.
+	GetByID(ctx context.Context, id int) (*domain.Session, error)
 	// GetByTokenHash looks up a session by the hashed refresh token.
 	GetByTokenHash(ctx context.Context, hash string) (*domain.Session, error)
 	Create(ctx context.Context, s *domain.Session) (*domain.Session, error)

backend/internal/port/storage.go

@@ -21,6 +21,10 @@ type FileStorage interface {
 	// Delete removes the file content from storage.
 	Delete(ctx context.Context, id uuid.UUID) error
 
+	// InvalidateCache removes any cached thumbnail/preview for the file so they
+	// are regenerated from the current content on next request.
+	InvalidateCache(ctx context.Context, id uuid.UUID) error
+
 	// Thumbnail opens the pre-generated thumbnail (JPEG). Returns ErrNotFound
 	// if the thumbnail has not been generated yet.
 	Thumbnail(ctx context.Context, id uuid.UUID) (io.ReadCloser, error)

backend/internal/service/acl_service.go

@@ -13,10 +13,31 @@ import (
 // ACLService handles access control checks and permission management.
 type ACLService struct {
 	aclRepo    port.ACLRepo
+	files      port.FileRepo
+	tags       port.TagRepo
+	categories port.CategoryRepo
+	pools      port.PoolRepo
+	tx         port.Transactor
 }
 
-func NewACLService(aclRepo port.ACLRepo) *ACLService {
+// NewACLService creates an ACLService. The object repositories are used to
-	return &ACLService{aclRepo: aclRepo}
+// resolve an object's owner when authorizing permission management.
+func NewACLService(
+	aclRepo port.ACLRepo,
+	files port.FileRepo,
+	tags port.TagRepo,
+	categories port.CategoryRepo,
+	pools port.PoolRepo,
+	tx port.Transactor,
+) *ACLService {
+	return &ACLService{
+		aclRepo:    aclRepo,
+		files:      files,
+		tags:       tags,
+		categories: categories,
+		pools:      pools,
+		tx:         tx,
+	}
 }
 
 // CanView returns true if the user may view the object.
@@ -70,12 +91,86 @@ func (s *ACLService) CanEdit(
 	return perm.CanEdit, nil
 }
 
-// GetPermissions returns all explicit ACL entries for an object.
+// GetPermissions returns all explicit ACL entries for an object. Only the
-func (s *ACLService) GetPermissions(ctx context.Context, objectTypeID int16, objectID uuid.UUID) ([]domain.Permission, error) {
+// object's owner or an admin may inspect its permission list.
+func (s *ACLService) GetPermissions(
+	ctx context.Context,
+	userID int16, isAdmin bool,
+	objectTypeID int16, objectID uuid.UUID,
+) ([]domain.Permission, error) {
+	if err := s.authorizeManage(ctx, userID, isAdmin, objectTypeID, objectID); err != nil {
+		return nil, err
+	}
 	return s.aclRepo.List(ctx, objectTypeID, objectID)
 }
 
 // SetPermissions replaces all ACL entries for an object (full replace semantics).
-func (s *ACLService) SetPermissions(ctx context.Context, objectTypeID int16, objectID uuid.UUID, perms []domain.Permission) error {
+// Only the object's owner or an admin may change its permissions. The replace is
+// performed atomically inside a single transaction.
+func (s *ACLService) SetPermissions(
+	ctx context.Context,
+	userID int16, isAdmin bool,
+	objectTypeID int16, objectID uuid.UUID,
+	perms []domain.Permission,
+) error {
+	if err := s.authorizeManage(ctx, userID, isAdmin, objectTypeID, objectID); err != nil {
+		return err
+	}
+	return s.tx.WithTx(ctx, func(ctx context.Context) error {
 		return s.aclRepo.Set(ctx, objectTypeID, objectID, perms)
+	})
+}
+
+// authorizeManage returns nil if the user may manage the object's ACL
+// (admin or owner), ErrForbidden otherwise, or a propagated lookup error
+// (including ErrNotFound when the object does not exist).
+func (s *ACLService) authorizeManage(
+	ctx context.Context,
+	userID int16, isAdmin bool,
+	objectTypeID int16, objectID uuid.UUID,
+) error {
+	if isAdmin {
+		return nil
+	}
+	owner, err := s.objectOwner(ctx, objectTypeID, objectID)
+	if err != nil {
+		return err
+	}
+	if owner != userID {
+		return domain.ErrForbidden
+	}
+	return nil
+}
+
+// objectOwner resolves the creator ID of the object identified by
+// (objectTypeID, objectID). Returns ErrNotFound if the object does not exist.
+func (s *ACLService) objectOwner(ctx context.Context, objectTypeID int16, objectID uuid.UUID) (int16, error) {
+	switch objectTypeID {
+	case fileObjectTypeID:
+		obj, err := s.files.GetByID(ctx, objectID)
+		if err != nil {
+			return 0, err
+		}
+		return obj.CreatorID, nil
+	case tagObjectTypeID:
+		obj, err := s.tags.GetByID(ctx, objectID)
+		if err != nil {
+			return 0, err
+		}
+		return obj.CreatorID, nil
+	case categoryObjectTypeID:
+		obj, err := s.categories.GetByID(ctx, objectID)
+		if err != nil {
+			return 0, err
+		}
+		return obj.CreatorID, nil
+	case poolObjectTypeID:
+		obj, err := s.pools.GetByID(ctx, objectID)
+		if err != nil {
+			return 0, err
+		}
+		return obj.CreatorID, nil
+	default:
+		return 0, domain.ErrValidation
+	}
 }

backend/internal/service/auth_service.go

@@ -2,6 +2,7 @@ package service
 
 import (
 	"context"
+	"crypto/rand"
 	"crypto/sha256"
 	"encoding/hex"
 	"fmt"
@@ -14,12 +15,25 @@ import (
 	"tanabata/backend/internal/port"
 )
 
+// Token types distinguish short-lived access tokens from long-lived refresh
+// tokens so the two cannot be substituted for one another.
+const (
+	tokenTypeAccess  = "access"
+	tokenTypeRefresh = "refresh"
+)
+
+// dummyPasswordHash is a valid bcrypt hash used to equalise the cost of a login
+// attempt against a non-existent user, preventing username enumeration via
+// response timing. It is the hash of a random string no one knows.
+const dummyPasswordHash = "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy"
+
 // Claims is the JWT payload for both access and refresh tokens.
 type Claims struct {
 	jwt.RegisteredClaims
 	UserID    int16  `json:"uid"`
 	IsAdmin   bool   `json:"adm"`
 	SessionID int    `json:"sid"`
+	TokenType string `json:"typ"`
 }
 
 // TokenPair holds an issued access/refresh token pair with the access TTL.
@@ -59,8 +73,16 @@ func NewAuthService(
 func (s *AuthService) Login(ctx context.Context, name, password, userAgent string) (*TokenPair, error) {
 	user, err := s.users.GetByName(ctx, name)
 	if err != nil {
-		// Return ErrUnauthorized regardless of whether the user exists,
+		// Compare against a dummy hash so a missing user costs the same as a
-		// to avoid username enumeration.
+		// wrong password, and return ErrUnauthorized either way to avoid
+		// username enumeration.
+		_ = bcrypt.CompareHashAndPassword([]byte(dummyPasswordHash), []byte(password))
+		return nil, domain.ErrUnauthorized
+	}
+
+	// Verify the password before disclosing anything about account state, so a
+	// caller cannot distinguish "blocked" from "wrong password".
+	if err := bcrypt.CompareHashAndPassword([]byte(user.Password), []byte(password)); err != nil {
 		return nil, domain.ErrUnauthorized
 	}
 
@@ -68,48 +90,7 @@ func (s *AuthService) Login(ctx context.Context, name, password, userAgent strin
 		return nil, domain.ErrForbidden
 	}
 
-	if err := bcrypt.CompareHashAndPassword([]byte(user.Password), []byte(password)); err != nil {
+	return s.issuePair(ctx, user, userAgent)
-		return nil, domain.ErrUnauthorized
-	}
-
-	var expiresAt *time.Time
-	if s.refreshTTL > 0 {
-		t := time.Now().Add(s.refreshTTL)
-		expiresAt = &t
-	}
-
-	// Issue the refresh token first so we can store its hash.
-	refreshToken, err := s.issueToken(user.ID, user.IsAdmin, 0, s.refreshTTL)
-	if err != nil {
-		return nil, fmt.Errorf("issue refresh token: %w", err)
-	}
-
-	session, err := s.sessions.Create(ctx, &domain.Session{
-		TokenHash: hashToken(refreshToken),
-		UserID:    user.ID,
-		UserAgent: userAgent,
-		ExpiresAt: expiresAt,
-	})
-	if err != nil {
-		return nil, fmt.Errorf("create session: %w", err)
-	}
-
-	accessToken, err := s.issueToken(user.ID, user.IsAdmin, session.ID, s.accessTTL)
-	if err != nil {
-		return nil, fmt.Errorf("issue access token: %w", err)
-	}
-
-	// Re-issue the refresh token with the real session ID now that we have it.
-	refreshToken, err = s.issueToken(user.ID, user.IsAdmin, session.ID, s.refreshTTL)
-	if err != nil {
-		return nil, fmt.Errorf("issue refresh token: %w", err)
-	}
-
-	return &TokenPair{
-		AccessToken:  accessToken,
-		RefreshToken: refreshToken,
-		ExpiresIn:    int(s.accessTTL.Seconds()),
-	}, nil
 }
 
 // Logout deactivates the session identified by sessionID.
@@ -124,7 +105,7 @@ func (s *AuthService) Logout(ctx context.Context, sessionID int) error {
 // the old session.
 func (s *AuthService) Refresh(ctx context.Context, refreshToken, userAgent string) (*TokenPair, error) {
 	claims, err := s.parseToken(refreshToken)
-	if err != nil {
+	if err != nil || claims.TokenType != tokenTypeRefresh {
 		return nil, domain.ErrUnauthorized
 	}
 
@@ -152,19 +133,30 @@ func (s *AuthService) Refresh(ctx context.Context, refreshToken, userAgent strin
 		return nil, domain.ErrForbidden
 	}
 
+	return s.issuePair(ctx, user, userAgent)
+}
+
+// issuePair creates a session and the access/refresh token pair for user.
+//
+// The refresh token is issued first and its hash is stored as the session's
+// identity; the refresh token is located on /refresh purely by that hash, so it
+// carries no session ID. The access token then embeds the real session ID so it
+// can be revoked on logout. Because the stored hash is the hash of the token
+// actually returned, /refresh works (unlike the previous re-issue approach).
+func (s *AuthService) issuePair(ctx context.Context, user *domain.User, userAgent string) (*TokenPair, error) {
 	var expiresAt *time.Time
 	if s.refreshTTL > 0 {
 		t := time.Now().Add(s.refreshTTL)
 		expiresAt = &t
 	}
 
-	newRefresh, err := s.issueToken(user.ID, user.IsAdmin, 0, s.refreshTTL)
+	refreshToken, err := s.issueToken(user.ID, user.IsAdmin, 0, s.refreshTTL, tokenTypeRefresh)
 	if err != nil {
 		return nil, fmt.Errorf("issue refresh token: %w", err)
 	}
 
-	newSession, err := s.sessions.Create(ctx, &domain.Session{
+	session, err := s.sessions.Create(ctx, &domain.Session{
-		TokenHash: hashToken(newRefresh),
+		TokenHash: hashToken(refreshToken),
 		UserID:    user.ID,
 		UserAgent: userAgent,
 		ExpiresAt: expiresAt,
@@ -173,19 +165,14 @@ func (s *AuthService) Refresh(ctx context.Context, refreshToken, userAgent strin
 		return nil, fmt.Errorf("create session: %w", err)
 	}
 
-	accessToken, err := s.issueToken(user.ID, user.IsAdmin, newSession.ID, s.accessTTL)
+	accessToken, err := s.issueToken(user.ID, user.IsAdmin, session.ID, s.accessTTL, tokenTypeAccess)
 	if err != nil {
 		return nil, fmt.Errorf("issue access token: %w", err)
 	}
 
-	newRefresh, err = s.issueToken(user.ID, user.IsAdmin, newSession.ID, s.refreshTTL)
-	if err != nil {
-		return nil, fmt.Errorf("issue refresh token: %w", err)
-	}
-
 	return &TokenPair{
 		AccessToken:  accessToken,
-		RefreshToken: newRefresh,
+		RefreshToken: refreshToken,
 		ExpiresIn:    int(s.accessTTL.Seconds()),
 	}, nil
 }
@@ -227,26 +214,43 @@ func (s *AuthService) TerminateSession(ctx context.Context, callerID int16, isAd
 	return nil
 }
 
-// ParseAccessToken parses and validates an access token, returning its claims.
+// ValidateAccessToken parses and validates an access token, returning its
-func (s *AuthService) ParseAccessToken(tokenStr string) (*Claims, error) {
+// claims. A refresh token is rejected (wrong type), and the token's session
+// must still be active — so logout, session termination, an admin block, or a
+// refresh rotation revoke any outstanding access tokens immediately rather than
+// only at expiry.
+func (s *AuthService) ValidateAccessToken(ctx context.Context, tokenStr string) (*Claims, error) {
 	claims, err := s.parseToken(tokenStr)
 	if err != nil {
 		return nil, domain.ErrUnauthorized
 	}
+	if claims.TokenType != tokenTypeAccess {
+		return nil, domain.ErrUnauthorized
+	}
+	if _, err := s.sessions.GetByID(ctx, claims.SessionID); err != nil {
+		return nil, domain.ErrUnauthorized
+	}
 	return claims, nil
 }
 
-// issueToken signs a JWT with the given parameters.
+// issueToken signs a JWT with the given parameters. A random JWT ID guarantees
-func (s *AuthService) issueToken(userID int16, isAdmin bool, sessionID int, ttl time.Duration) (string, error) {
+// uniqueness even for tokens minted within the same second.
+func (s *AuthService) issueToken(userID int16, isAdmin bool, sessionID int, ttl time.Duration, tokenType string) (string, error) {
+	jti, err := randomJTI()
+	if err != nil {
+		return "", err
+	}
 	now := time.Now()
 	claims := Claims{
 		RegisteredClaims: jwt.RegisteredClaims{
+			ID:        jti,
 			IssuedAt:  jwt.NewNumericDate(now),
 			ExpiresAt: jwt.NewNumericDate(now.Add(ttl)),
 		},
 		UserID:    userID,
 		IsAdmin:   isAdmin,
 		SessionID: sessionID,
+		TokenType: tokenType,
 	}
 	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
 	signed, err := token.SignedString(s.secret)
@@ -280,3 +284,12 @@ func hashToken(token string) string {
 	sum := sha256.Sum256([]byte(token))
 	return hex.EncodeToString(sum[:])
 }
+
+// randomJTI returns a 128-bit random hex string for use as a JWT ID.
+func randomJTI() (string, error) {
+	b := make([]byte, 16)
+	if _, err := rand.Read(b); err != nil {
+		return "", fmt.Errorf("generate jti: %w", err)
+	}
+	return hex.EncodeToString(b), nil
+}

backend/internal/service/category_service.go

@@ -0,0 +1,179 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/google/uuid"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+)
+
+const categoryObjectType = "category"
+const categoryObjectTypeID int16 = 3 // third row in 007_seed_data.sql object_types
+
+// CategoryParams holds the fields for creating or patching a category.
+type CategoryParams struct {
+	Name     string
+	Notes    *string
+	Color    *string // nil = no change; pointer to empty string = clear
+	Metadata json.RawMessage
+	IsPublic *bool
+}
+
+// CategoryService handles category CRUD with ACL enforcement and audit logging.
+type CategoryService struct {
+	categories port.CategoryRepo
+	tags       port.TagRepo
+	acl        *ACLService
+	audit      *AuditService
+}
+
+// NewCategoryService creates a CategoryService.
+func NewCategoryService(
+	categories port.CategoryRepo,
+	tags port.TagRepo,
+	acl *ACLService,
+	audit *AuditService,
+) *CategoryService {
+	return &CategoryService{
+		categories: categories,
+		tags:       tags,
+		acl:        acl,
+		audit:      audit,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// CRUD
+// ---------------------------------------------------------------------------
+
+// List returns a paginated list of categories the caller may see.
+func (s *CategoryService) List(ctx context.Context, params port.OffsetParams) (*domain.CategoryOffsetPage, error) {
+	params.ViewerID, params.ViewerIsAdmin, _ = domain.UserFromContext(ctx)
+	return s.categories.List(ctx, params)
+}
+
+// Get returns a category by ID, enforcing view ACL.
+func (s *CategoryService) Get(ctx context.Context, id uuid.UUID) (*domain.Category, error) {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+	c, err := s.categories.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	ok, err := s.acl.CanView(ctx, userID, isAdmin, c.CreatorID, c.IsPublic, categoryObjectTypeID, id)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		return nil, domain.ErrForbidden
+	}
+	return c, nil
+}
+
+// Create inserts a new category record.
+func (s *CategoryService) Create(ctx context.Context, p CategoryParams) (*domain.Category, error) {
+	userID, _, _ := domain.UserFromContext(ctx)
+
+	c := &domain.Category{
+		Name:      p.Name,
+		Notes:     p.Notes,
+		Color:     p.Color,
+		Metadata:  p.Metadata,
+		CreatorID: userID,
+	}
+	if p.IsPublic != nil {
+		c.IsPublic = *p.IsPublic
+	}
+
+	created, err := s.categories.Create(ctx, c)
+	if err != nil {
+		return nil, err
+	}
+
+	objType := categoryObjectType
+	_ = s.audit.Log(ctx, "category_create", &objType, &created.ID, nil)
+	return created, nil
+}
+
+// Update applies a partial patch to a category.
+func (s *CategoryService) Update(ctx context.Context, id uuid.UUID, p CategoryParams) (*domain.Category, error) {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+
+	current, err := s.categories.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, current.CreatorID, categoryObjectTypeID, id)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		return nil, domain.ErrForbidden
+	}
+
+	patch := *current
+	if p.Name != "" {
+		patch.Name = p.Name
+	}
+	if p.Notes != nil {
+		patch.Notes = p.Notes
+	}
+	if p.Color != nil {
+		patch.Color = p.Color
+	}
+	if len(p.Metadata) > 0 {
+		patch.Metadata = p.Metadata
+	}
+	if p.IsPublic != nil {
+		patch.IsPublic = *p.IsPublic
+	}
+
+	updated, err := s.categories.Update(ctx, id, &patch)
+	if err != nil {
+		return nil, err
+	}
+
+	objType := categoryObjectType
+	_ = s.audit.Log(ctx, "category_edit", &objType, &id, nil)
+	return updated, nil
+}
+
+// Delete removes a category by ID, enforcing edit ACL.
+func (s *CategoryService) Delete(ctx context.Context, id uuid.UUID) error {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+
+	c, err := s.categories.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, c.CreatorID, categoryObjectTypeID, id)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return domain.ErrForbidden
+	}
+
+	if err := s.categories.Delete(ctx, id); err != nil {
+		return err
+	}
+
+	objType := categoryObjectType
+	_ = s.audit.Log(ctx, "category_delete", &objType, &id, nil)
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Tags in category
+// ---------------------------------------------------------------------------
+
+// ListTags returns a paginated list of tags in this category that the caller
+// may see.
+func (s *CategoryService) ListTags(ctx context.Context, categoryID uuid.UUID, params port.OffsetParams) (*domain.TagOffsetPage, error) {
+	params.ViewerID, params.ViewerIsAdmin, _ = domain.UserFromContext(ctx)
+	return s.tags.ListByCategory(ctx, categoryID, params)
+}

backend/internal/service/file_service.go

@@ -8,11 +8,11 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"strings"
 	"time"
 
 	"github.com/gabriel-vasile/mimetype"
 	"github.com/google/uuid"
-	"github.com/rwcarlsen/goexif/exif"
 
 	"tanabata/backend/internal/domain"
 	"tanabata/backend/internal/port"
@@ -32,6 +32,10 @@ type UploadParams struct {
 	Notes           *string
 	Metadata        json.RawMessage
 	ContentDatetime *time.Time
+	// ContentDatetimeFallback is used for content_datetime only when neither an
+	// explicit ContentDatetime nor an EXIF date is available (e.g. the source
+	// file's mtime on a server-side import).
+	ContentDatetimeFallback *time.Time
 	IsPublic                bool
 	TagIDs                  []uuid.UUID
 }
@@ -66,6 +70,24 @@ type ImportResult struct {
 	Errors   []ImportFileError `json:"errors"`
 }
 
+// ImportEvent is one progress message streamed during an import, letting the UI
+// show a live progress bar and a per-file status list. Type is the discriminator:
+//
+//	"start" — total is the number of entries about to be processed.
+//	"file"  — one entry finished: index (1-based), filename, status, optional reason.
+//	"done"  — final tallies (imported/skipped/errors).
+type ImportEvent struct {
+	Type     string `json:"type"`
+	Total    int    `json:"total,omitempty"`
+	Index    int    `json:"index,omitempty"`
+	Filename string `json:"filename,omitempty"`
+	Status   string `json:"status,omitempty"` // "imported" | "skipped" | "error"
+	Reason   string `json:"reason,omitempty"`
+	Imported int    `json:"imported,omitempty"`
+	Skipped  int    `json:"skipped,omitempty"`
+	Errors   int    `json:"errors,omitempty"`
+}
+
 // FileService handles business logic for file records.
 type FileService struct {
 	files      port.FileRepo
@@ -73,6 +95,7 @@ type FileService struct {
 	storage    port.FileStorage
 	acl        *ACLService
 	audit      *AuditService
+	tags       *TagService
 	tx         port.Transactor
 	importPath string // default server-side import directory
 }
@@ -84,6 +107,7 @@ func NewFileService(
 	storage port.FileStorage,
 	acl *ACLService,
 	audit *AuditService,
+	tags *TagService,
 	tx port.Transactor,
 	importPath string,
 ) *FileService {
@@ -93,6 +117,7 @@ func NewFileService(
 		storage:    storage,
 		acl:        acl,
 		audit:      audit,
+		tags:       tags,
 		tx:         tx,
 		importPath: importPath,
 	}
@@ -104,7 +129,7 @@ func NewFileService(
 
 // Upload validates the MIME type, saves the file to storage, creates the DB
 // record, and applies any initial tags — all within a single transaction.
-// If ContentDatetime is nil and EXIF DateTimeOriginal is present, it is used.
+// If ContentDatetime is nil and the metadata carries a capture date, it is used.
 func (s *FileService) Upload(ctx context.Context, p UploadParams) (*domain.File, error) {
 	userID, _, _ := domain.UserFromContext(ctx)
 
@@ -121,15 +146,21 @@ func (s *FileService) Upload(ctx context.Context, p UploadParams) (*domain.File,
 	}
 	data := buf.Bytes()
 
-	// Extract EXIF metadata (best-effort; non-image files will error silently).
+	// Extract rich metadata (best-effort; covers images, video and audio).
-	exifData, exifDatetime := extractEXIFWithDatetime(data)
+	var origName string
+	if p.OriginalName != nil {
+		origName = *p.OriginalName
+	}
+	exifData, exifDatetime := extractMetadata(data, origName, p.ContentDatetimeFallback)
 
-	// Resolve content datetime: explicit > EXIF > zero value.
+	// Resolve content datetime: explicit > metadata date > fallback (e.g. import mtime) > zero.
 	var contentDatetime time.Time
 	if p.ContentDatetime != nil {
 		contentDatetime = *p.ContentDatetime
 	} else if exifDatetime != nil {
 		contentDatetime = *exifDatetime
+	} else if p.ContentDatetimeFallback != nil {
+		contentDatetime = *p.ContentDatetimeFallback
 	}
 
 	// Assign UUID v7 so CreatedAt can be derived from it later.
@@ -166,10 +197,7 @@ func (s *FileService) Upload(ctx context.Context, p UploadParams) (*domain.File,
 		}
 
 		if len(p.TagIDs) > 0 {
-			if err := s.files.SetTags(ctx, created.ID, p.TagIDs); err != nil {
+			tags, err := s.tags.SetFileTags(ctx, created.ID, p.TagIDs)
-				return err
-			}
-			tags, err := s.files.ListTags(ctx, created.ID)
 			if err != nil {
 				return err
 			}
@@ -207,6 +235,26 @@ func (s *FileService) Get(ctx context.Context, id uuid.UUID) (*domain.File, erro
 	return f, nil
 }
 
+// RecordView appends a view-history entry for the current user, enforcing view
+// ACL (you can only record a view of a file you may see).
+func (s *FileService) RecordView(ctx context.Context, id uuid.UUID) error {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+
+	f, err := s.files.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	ok, err := s.acl.CanView(ctx, userID, isAdmin, f.CreatorID, f.IsPublic, fileObjectTypeID, id)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return domain.ErrForbidden
+	}
+	return s.files.RecordView(ctx, id, userID)
+}
+
 // Update applies metadata changes to a file, enforcing edit ACL.
 func (s *FileService) Update(ctx context.Context, id uuid.UUID, p UpdateParams) (*domain.File, error) {
 	userID, isAdmin, _ := domain.UserFromContext(ctx)
@@ -249,10 +297,7 @@ func (s *FileService) Update(ctx context.Context, id uuid.UUID, p UpdateParams)
 			return updateErr
 		}
 		if p.TagIDs != nil {
-			if err := s.files.SetTags(ctx, id, *p.TagIDs); err != nil {
+			tags, err := s.tags.SetFileTags(ctx, id, *p.TagIDs)
-				return err
-			}
-			tags, err := s.files.ListTags(ctx, id)
 			if err != nil {
 				return err
 			}
@@ -347,6 +392,7 @@ func (s *FileService) PermanentDelete(ctx context.Context, id uuid.UUID) error {
 		return err
 	}
 	_ = s.storage.Delete(ctx, id)
+	_ = s.storage.InvalidateCache(ctx, id)
 
 	objType := fileObjectType
 	_ = s.audit.Log(ctx, "file_permanent_delete", &objType, &id, nil)
@@ -380,11 +426,17 @@ func (s *FileService) Replace(ctx context.Context, id uuid.UUID, p UploadParams)
 		return nil, fmt.Errorf("FileService.Replace: read body: %w", err)
 	}
 	data := buf.Bytes()
-	exifData, _ := extractEXIFWithDatetime(data)
+	var origName string
+	if p.OriginalName != nil {
+		origName = *p.OriginalName
+	}
+	exifData, _ := extractMetadata(data, origName, nil)
 
 	if _, err := s.storage.Save(ctx, id, bytes.NewReader(data)); err != nil {
 		return nil, fmt.Errorf("FileService.Replace: save to storage: %w", err)
 	}
+	// Drop stale thumbnail/preview so they regenerate from the new content.
+	_ = s.storage.InvalidateCache(ctx, id)
 
 	patch := &domain.File{
 		MIMEType:      mime.Name,
@@ -405,9 +457,50 @@ func (s *FileService) Replace(ctx context.Context, id uuid.UUID, p UploadParams)
 	return updated, nil
 }
 
-// List delegates to FileRepo with the given params.
+// List delegates to FileRepo with the given params, restricting results to
+// files the caller may see (unless they are an admin).
 func (s *FileService) List(ctx context.Context, params domain.FileListParams) (*domain.FilePage, error) {
-	return s.files.List(ctx, params)
+	params.ViewerID, params.ViewerIsAdmin, _ = domain.UserFromContext(ctx)
+
+	page, err := s.files.List(ctx, params)
+	if err != nil {
+		return nil, err
+	}
+
+	// Log tag usage when a filter is first applied — not on pagination (cursor)
+	// or an anchored return, so a single browse counts once. Best-effort
+	// analytics; a failed write never breaks the listing.
+	if params.Filter != "" && params.Cursor == "" && params.Anchor == nil && params.ViewerID != 0 {
+		_ = s.files.RecordTagUses(ctx, params.ViewerID, params.Filter)
+	}
+
+	return page, nil
+}
+
+// AuthorizeView ensures the caller may view the file. Returns ErrNotFound if the
+// file does not exist or ErrForbidden if the caller lacks view access.
+func (s *FileService) AuthorizeView(ctx context.Context, id uuid.UUID) error {
+	_, err := s.Get(ctx, id)
+	return err
+}
+
+// AuthorizeEdit ensures the caller may edit the file. Returns ErrNotFound if the
+// file does not exist or ErrForbidden if the caller lacks edit access.
+func (s *FileService) AuthorizeEdit(ctx context.Context, id uuid.UUID) error {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+
+	f, err := s.files.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, f.CreatorID, fileObjectTypeID, id)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return domain.ErrForbidden
+	}
+	return nil
 }
 
 // ---------------------------------------------------------------------------
@@ -447,120 +540,6 @@ func (s *FileService) GetPreview(ctx context.Context, id uuid.UUID) (io.ReadClos
 	return s.storage.Preview(ctx, id)
 }
 
-// ---------------------------------------------------------------------------
-// Tag operations
-// ---------------------------------------------------------------------------
-
-// ListFileTags returns the tags on a file, enforcing view ACL.
-func (s *FileService) ListFileTags(ctx context.Context, fileID uuid.UUID) ([]domain.Tag, error) {
-	if _, err := s.Get(ctx, fileID); err != nil {
-		return nil, err
-	}
-	return s.files.ListTags(ctx, fileID)
-}
-
-// SetFileTags replaces all tags on a file (full replace semantics), enforcing edit ACL.
-func (s *FileService) SetFileTags(ctx context.Context, fileID uuid.UUID, tagIDs []uuid.UUID) ([]domain.Tag, error) {
-	userID, isAdmin, _ := domain.UserFromContext(ctx)
-
-	f, err := s.files.GetByID(ctx, fileID)
-	if err != nil {
-		return nil, err
-	}
-	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, f.CreatorID, fileObjectTypeID, fileID)
-	if err != nil {
-		return nil, err
-	}
-	if !ok {
-		return nil, domain.ErrForbidden
-	}
-
-	if err := s.files.SetTags(ctx, fileID, tagIDs); err != nil {
-		return nil, err
-	}
-
-	objType := fileObjectType
-	_ = s.audit.Log(ctx, "file_tag_add", &objType, &fileID, nil)
-	return s.files.ListTags(ctx, fileID)
-}
-
-// AddTag adds a single tag to a file, enforcing edit ACL.
-func (s *FileService) AddTag(ctx context.Context, fileID, tagID uuid.UUID) ([]domain.Tag, error) {
-	userID, isAdmin, _ := domain.UserFromContext(ctx)
-
-	f, err := s.files.GetByID(ctx, fileID)
-	if err != nil {
-		return nil, err
-	}
-	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, f.CreatorID, fileObjectTypeID, fileID)
-	if err != nil {
-		return nil, err
-	}
-	if !ok {
-		return nil, domain.ErrForbidden
-	}
-
-	current, err := s.files.ListTags(ctx, fileID)
-	if err != nil {
-		return nil, err
-	}
-	// Only add if not already present.
-	for _, t := range current {
-		if t.ID == tagID {
-			return current, nil
-		}
-	}
-	ids := make([]uuid.UUID, 0, len(current)+1)
-	for _, t := range current {
-		ids = append(ids, t.ID)
-	}
-	ids = append(ids, tagID)
-
-	if err := s.files.SetTags(ctx, fileID, ids); err != nil {
-		return nil, err
-	}
-
-	objType := fileObjectType
-	_ = s.audit.Log(ctx, "file_tag_add", &objType, &fileID, map[string]any{"tag_id": tagID})
-	return s.files.ListTags(ctx, fileID)
-}
-
-// RemoveTag removes a single tag from a file, enforcing edit ACL.
-func (s *FileService) RemoveTag(ctx context.Context, fileID, tagID uuid.UUID) error {
-	userID, isAdmin, _ := domain.UserFromContext(ctx)
-
-	f, err := s.files.GetByID(ctx, fileID)
-	if err != nil {
-		return err
-	}
-	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, f.CreatorID, fileObjectTypeID, fileID)
-	if err != nil {
-		return err
-	}
-	if !ok {
-		return domain.ErrForbidden
-	}
-
-	current, err := s.files.ListTags(ctx, fileID)
-	if err != nil {
-		return err
-	}
-	ids := make([]uuid.UUID, 0, len(current))
-	for _, t := range current {
-		if t.ID != tagID {
-			ids = append(ids, t.ID)
-		}
-	}
-
-	if err := s.files.SetTags(ctx, fileID, ids); err != nil {
-		return err
-	}
-
-	objType := fileObjectType
-	_ = s.audit.Log(ctx, "file_tag_remove", &objType, &fileID, map[string]any{"tag_id": tagID})
-	return nil
-}
-
 // ---------------------------------------------------------------------------
 // Bulk operations
 // ---------------------------------------------------------------------------
@@ -569,7 +548,6 @@ func (s *FileService) RemoveTag(ctx context.Context, fileID, tagID uuid.UUID) er
 func (s *FileService) BulkDelete(ctx context.Context, fileIDs []uuid.UUID) error {
 	for _, id := range fileIDs {
 		if err := s.Delete(ctx, id); err != nil {
-			// Skip files not found or forbidden; surface real errors.
 			if err == domain.ErrNotFound || err == domain.ErrForbidden {
 				continue
 			}
@@ -579,159 +557,132 @@ func (s *FileService) BulkDelete(ctx context.Context, fileIDs []uuid.UUID) error
 	return nil
 }
 
-// BulkSetTags adds or removes the given tags on multiple files.
-// For "add": tags are appended to each file's existing set.
-// For "remove": tags are removed from each file's existing set.
-// Returns the tag IDs that were applied (the input tagIDs, for add).
-func (s *FileService) BulkSetTags(ctx context.Context, fileIDs []uuid.UUID, action string, tagIDs []uuid.UUID) ([]uuid.UUID, error) {
-	for _, fileID := range fileIDs {
-		switch action {
-		case "add":
-			for _, tagID := range tagIDs {
-				if _, err := s.AddTag(ctx, fileID, tagID); err != nil {
-					if err == domain.ErrNotFound || err == domain.ErrForbidden {
-						continue
-					}
-					return nil, err
-				}
-			}
-		case "remove":
-			for _, tagID := range tagIDs {
-				if err := s.RemoveTag(ctx, fileID, tagID); err != nil {
-					if err == domain.ErrNotFound || err == domain.ErrForbidden {
-						continue
-					}
-					return nil, err
-				}
-			}
-		default:
-			return nil, domain.ErrValidation
-		}
-	}
-	if action == "add" {
-		return tagIDs, nil
-	}
-	return []uuid.UUID{}, nil
-}
-
-// CommonTags loads the tag sets for all given files and splits them into:
-//   - common: tag IDs present on every file
-//   - partial: tag IDs present on some but not all files
-func (s *FileService) CommonTags(ctx context.Context, fileIDs []uuid.UUID) (common, partial []uuid.UUID, err error) {
-	if len(fileIDs) == 0 {
-		return nil, nil, nil
-	}
-
-	// Count how many files each tag appears on.
-	counts := map[uuid.UUID]int{}
-	for _, fid := range fileIDs {
-		tags, err := s.files.ListTags(ctx, fid)
-		if err != nil {
-			return nil, nil, err
-		}
-		for _, t := range tags {
-			counts[t.ID]++
-		}
-	}
-
-	n := len(fileIDs)
-	for id, cnt := range counts {
-		if cnt == n {
-			common = append(common, id)
-		} else {
-			partial = append(partial, id)
-		}
-	}
-	if common == nil {
-		common = []uuid.UUID{}
-	}
-	if partial == nil {
-		partial = []uuid.UUID{}
-	}
-	return common, partial, nil
-}
-
 // ---------------------------------------------------------------------------
 // Import
 // ---------------------------------------------------------------------------
 
 // Import scans a server-side directory and uploads all supported files.
 // If path is empty, the configured default import path is used.
-func (s *FileService) Import(ctx context.Context, path string) (*ImportResult, error) {
+//
-	dir := path
+// onProgress, when non-nil, receives a "start" event, one "file" event per
-	if dir == "" {
+// directory entry as it is processed, and a final "done" event — letting a
-		dir = s.importPath
+// caller stream live progress. It is always called from this goroutine (never
-	}
+// concurrently). The aggregate result is also returned for non-streaming callers.
-	if dir == "" {
+func (s *FileService) Import(ctx context.Context, path string, onProgress func(ImportEvent)) (*ImportResult, error) {
+	if s.importPath == "" {
 		return nil, domain.ErrValidation
 	}
 
+	dir := s.importPath
+	if path != "" {
+		// Confine caller-supplied paths to the configured import directory so a
+		// directory-traversal value cannot read arbitrary host files.
+		confined, err := confineToBase(s.importPath, path)
+		if err != nil {
+			return nil, err
+		}
+		dir = confined
+	}
+
 	entries, err := os.ReadDir(dir)
 	if err != nil {
 		return nil, fmt.Errorf("FileService.Import: read dir %q: %w", dir, err)
 	}
 
-	result := &ImportResult{Errors: []ImportFileError{}}
+	emit := func(ev ImportEvent) {
+		if onProgress != nil {
+			onProgress(ev)
+		}
+	}
+
+	result := &ImportResult{Errors: []ImportFileError{}}
+	total := len(entries)
+	emit(ImportEvent{Type: "start", Total: total})
+
+	for i, entry := range entries {
+		name := entry.Name()
+		file := func(status, reason string) {
+			emit(ImportEvent{
+				Type: "file", Index: i + 1, Total: total,
+				Filename: name, Status: status, Reason: reason,
+			})
+		}
+		fail := func(reason string) {
+			result.Errors = append(result.Errors, ImportFileError{Filename: name, Reason: reason})
+			file("error", reason)
+		}
 
-	for _, entry := range entries {
 		if entry.IsDir() {
 			result.Skipped++
+			file("skipped", "directory")
 			continue
 		}
 
-		fullPath := filepath.Join(dir, entry.Name())
+		fullPath := filepath.Join(dir, name)
 
 		mt, err := mimetype.DetectFile(fullPath)
 		if err != nil {
-			result.Errors = append(result.Errors, ImportFileError{
+			fail(fmt.Sprintf("MIME detection failed: %s", err))
-				Filename: entry.Name(),
-				Reason:   fmt.Sprintf("MIME detection failed: %s", err),
-			})
 			continue
 		}
 
 		mimeStr := mt.String()
 		// Strip parameters (e.g. "text/plain; charset=utf-8" → "text/plain").
-		if idx := len(mimeStr); idx > 0 {
+		if j := strings.IndexByte(mimeStr, ';'); j >= 0 {
-			for i, c := range mimeStr {
+			mimeStr = mimeStr[:j]
-				if c == ';' {
-					mimeStr = mimeStr[:i]
-					break
-				}
-			}
 		}
 
 		if _, err := s.mimes.GetByName(ctx, mimeStr); err != nil {
 			result.Skipped++
+			file("skipped", "unsupported type: "+mimeStr)
 			continue
 		}
 
 		f, err := os.Open(fullPath)
 		if err != nil {
-			result.Errors = append(result.Errors, ImportFileError{
+			fail(fmt.Sprintf("open failed: %s", err))
-				Filename: entry.Name(),
-				Reason:   fmt.Sprintf("open failed: %s", err),
-			})
 			continue
 		}
 
-		name := entry.Name()
+		// Preserve the file's mtime as a content_datetime fallback (used only when
+		// the file has no EXIF date) — once the source is removed below it's the
+		// only date left for non-photo files.
+		var mtime *time.Time
+		if info, statErr := entry.Info(); statErr == nil {
+			t := info.ModTime()
+			mtime = &t
+		}
+
 		_, uploadErr := s.Upload(ctx, UploadParams{
 			Reader:                  f,
 			MIMEType:                mimeStr,
 			OriginalName:            &name,
+			ContentDatetimeFallback: mtime,
 		})
 		f.Close()
 
 		if uploadErr != nil {
-			result.Errors = append(result.Errors, ImportFileError{
+			fail(uploadErr.Error())
-				Filename: entry.Name(),
-				Reason:   uploadErr.Error(),
-			})
 			continue
 		}
 		result.Imported++
+
+		// Remove the source on success so the import folder drains and re-running
+		// doesn't duplicate. The file is already safely copied into storage; a
+		// removal failure is reported but doesn't undo the import.
+		if rmErr := os.Remove(fullPath); rmErr != nil {
+			reason := fmt.Sprintf("imported, but failed to remove source: %s", rmErr)
+			result.Errors = append(result.Errors, ImportFileError{Filename: name, Reason: reason})
+			file("imported", reason) // imported, with a warning
+			continue
 		}
+		file("imported", "")
+	}
+
+	emit(ImportEvent{
+		Type: "done", Total: total,
+		Imported: result.Imported, Skipped: result.Skipped, Errors: len(result.Errors),
+	})
 
 	return result, nil
 }
@@ -740,20 +691,24 @@ func (s *FileService) Import(ctx context.Context, path string) (*ImportResult, e
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-// extractEXIFWithDatetime parses EXIF from raw bytes, returning both the JSON
+// confineToBase resolves target and verifies it does not escape base (after
-// representation and the DateTimeOriginal (if present). Both may be nil.
+// cleaning and resolving "..") so a caller cannot read files outside the
-func extractEXIFWithDatetime(data []byte) (json.RawMessage, *time.Time) {
+// configured import directory. Returns the cleaned absolute path on success.
-	x, err := exif.Decode(bytes.NewReader(data))
+func confineToBase(base, target string) (string, error) {
+	absBase, err := filepath.Abs(base)
 	if err != nil {
-		return nil, nil
+		return "", domain.ErrValidation
 	}
-	b, err := x.MarshalJSON()
+	absTarget, err := filepath.Abs(target)
 	if err != nil {
-		return nil, nil
+		return "", domain.ErrValidation
 	}
-	var dt *time.Time
+	rel, err := filepath.Rel(absBase, absTarget)
-	if t, err := x.DateTime(); err == nil {
+	if err != nil {
-		dt = &t
+		return "", domain.ErrValidation
 	}
-	return json.RawMessage(b), dt
+	if rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
+		return "", domain.ErrForbidden
+	}
+	return absTarget, nil
 }

backend/internal/service/metadata.go

@@ -0,0 +1,183 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/rwcarlsen/goexif/exif"
+)
+
+// exiftoolPath is resolved once at startup. When exiftool isn't installed we
+// skip the subprocess and fall back to the pure-Go EXIF reader, so the server
+// still runs (with thinner metadata) on hosts without it.
+var exiftoolPath, _ = exec.LookPath("exiftool")
+
+// metadataTimeout bounds a single exiftool invocation so a pathological file
+// can't wedge an upload.
+const metadataTimeout = 30 * time.Second
+
+// metaTempFileKeys are exiftool fields that describe the temporary file we feed
+// it rather than the content. Dropping them avoids leaking internal paths and
+// recording the temp file's permissions/inode timestamps.
+var metaTempFileKeys = []string{
+	"SourceFile",
+	"Directory",
+	"FileAccessDate",
+	"FileInodeChangeDate",
+	"FilePermissions",
+}
+
+// metaDateKeys are the metadata fields, in priority order, holding the moment
+// the content was actually captured/created — photos first, then video atoms.
+var metaDateKeys = []string{
+	"DateTimeOriginal",
+	"CreateDate",
+	"MediaCreateDate",
+	"TrackCreateDate",
+	"ModifyDate",
+}
+
+// extractMetadata returns rich metadata as JSON plus the best content datetime
+// it can find. It prefers exiftool, which understands video, audio and every
+// image format and emits machine-readable numeric values (the basis for later
+// analytics); when exiftool is unavailable it falls back to the pure-Go EXIF
+// reader, which only handles JPEG/TIFF.
+//
+// originalName supplies the extension exiftool uses for format detection and the
+// FileName reported back. mtime, when set (e.g. a server-side import), is stamped
+// onto the temp file so FileModifyDate reflects the real source.
+func extractMetadata(data []byte, originalName string, mtime *time.Time) (json.RawMessage, *time.Time) {
+	if exiftoolPath != "" {
+		if raw, dt, ok := exiftoolExtract(data, originalName, mtime); ok {
+			return raw, dt
+		}
+	}
+	return extractEXIFWithDatetime(data)
+}
+
+// exiftoolExtract stages the bytes in a temp file and shells out to exiftool.
+// It returns ok=false on any failure so the caller can fall back.
+func exiftoolExtract(data []byte, originalName string, mtime *time.Time) (json.RawMessage, *time.Time, bool) {
+	// exiftool reads a real file far more reliably than a pipe (it seeks freely,
+	// e.g. to a trailing MP4 moov atom), so stage the bytes in a temp file whose
+	// extension matches the original for accurate format detection.
+	tmp, err := os.CreateTemp("", "tfm-meta-*"+filepath.Ext(originalName))
+	if err != nil {
+		return nil, nil, false
+	}
+	tmpName := tmp.Name()
+	defer os.Remove(tmpName)
+
+	if _, err := tmp.Write(data); err != nil {
+		tmp.Close()
+		return nil, nil, false
+	}
+	if err := tmp.Close(); err != nil {
+		return nil, nil, false
+	}
+	if mtime != nil {
+		_ = os.Chtimes(tmpName, *mtime, *mtime)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), metadataTimeout)
+	defer cancel()
+	// -n forces raw numeric/machine values for every tag (no "3.53 Mbps" strings)
+	// so the metadata is analytics-ready. -all extracts every tag. largefilesupport
+	// handles multi-GB videos. Output is a one-element JSON array.
+	out, err := exec.CommandContext(ctx, exiftoolPath,
+		"-n", "-all", "-json", "-api", "largefilesupport=1", tmpName,
+	).Output()
+	if err != nil {
+		return nil, nil, false
+	}
+
+	var arr []map[string]json.RawMessage
+	if err := json.Unmarshal(out, &arr); err != nil || len(arr) == 0 {
+		return nil, nil, false
+	}
+	m := arr[0]
+
+	dt := pickMetaDatetime(m)
+
+	// Strip temp-file artifacts and substitute the real name.
+	for _, k := range metaTempFileKeys {
+		delete(m, k)
+	}
+	if mtime == nil {
+		// Without a real source mtime this is just the temp file's write time.
+		delete(m, "FileModifyDate")
+	}
+	if originalName != "" {
+		if nb, err := json.Marshal(originalName); err == nil {
+			m["FileName"] = nb
+		}
+	} else {
+		delete(m, "FileName")
+	}
+
+	raw, err := json.Marshal(m)
+	if err != nil {
+		return nil, nil, false
+	}
+	return raw, dt, true
+}
+
+// pickMetaDatetime returns the first parseable content date among metaDateKeys.
+func pickMetaDatetime(m map[string]json.RawMessage) *time.Time {
+	for _, key := range metaDateKeys {
+		raw, ok := m[key]
+		if !ok {
+			continue
+		}
+		var s string
+		if err := json.Unmarshal(raw, &s); err != nil {
+			continue
+		}
+		if t, ok := parseExifDate(s); ok {
+			return &t
+		}
+	}
+	return nil
+}
+
+// parseExifDate parses exiftool's "YYYY:MM:DD HH:MM:SS" timestamps, with or
+// without a trailing timezone offset. Zeroed placeholders ("0000:00:00 ...")
+// fail to parse and are skipped by the caller.
+func parseExifDate(s string) (time.Time, bool) {
+	s = strings.TrimSpace(s)
+	for _, layout := range []string{
+		"2006:01:02 15:04:05-07:00",
+		"2006:01:02 15:04:05Z07:00",
+		"2006:01:02 15:04:05",
+	} {
+		if t, err := time.Parse(layout, s); err == nil {
+			return t, true
+		}
+	}
+	return time.Time{}, false
+}
+
+// extractEXIFWithDatetime is the pure-Go fallback used when exiftool is absent.
+// It parses EXIF from raw bytes (JPEG/TIFF only), returning both the JSON
+// representation and the DateTimeOriginal (if present). Both may be nil.
+func extractEXIFWithDatetime(data []byte) (json.RawMessage, *time.Time) {
+	x, err := exif.Decode(bytes.NewReader(data))
+	if err != nil {
+		return nil, nil
+	}
+	b, err := x.MarshalJSON()
+	if err != nil {
+		return nil, nil
+	}
+	var dt *time.Time
+	if t, err := x.DateTime(); err == nil {
+		dt = &t
+	}
+	return json.RawMessage(b), dt
+}

backend/internal/service/metadata_test.go

@@ -0,0 +1,110 @@
+package service
+
+import (
+	"bytes"
+	"encoding/json"
+	"image"
+	"image/color"
+	"image/png"
+	"testing"
+	"time"
+)
+
+func TestParseExifDate(t *testing.T) {
+	cases := []struct {
+		in   string
+		ok   bool
+		want time.Time
+	}{
+		{"2026:03:24 16:57:58", true, time.Date(2026, 3, 24, 16, 57, 58, 0, time.UTC)},
+		{"2026:05:08 23:07:55+03:00", true, time.Date(2026, 5, 8, 23, 7, 55, 0, time.FixedZone("", 3*3600))},
+		{"  2026:01:02 03:04:05  ", true, time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)},
+		{"0000:00:00 00:00:00", false, time.Time{}},
+		{"not a date", false, time.Time{}},
+		{"", false, time.Time{}},
+	}
+	for _, c := range cases {
+		got, ok := parseExifDate(c.in)
+		if ok != c.ok {
+			t.Errorf("parseExifDate(%q) ok=%v, want %v", c.in, ok, c.ok)
+			continue
+		}
+		if ok && !got.Equal(c.want) {
+			t.Errorf("parseExifDate(%q) = %v, want %v", c.in, got, c.want)
+		}
+	}
+}
+
+// tinyPNG returns a valid 2x3 PNG with no embedded EXIF/date.
+func tinyPNG(t *testing.T) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, 2, 3))
+	img.Set(0, 0, color.RGBA{R: 10, G: 20, B: 30, A: 255})
+	var buf bytes.Buffer
+	if err := png.Encode(&buf, img); err != nil {
+		t.Fatalf("encode png: %v", err)
+	}
+	return buf.Bytes()
+}
+
+func TestExtractMetadataExiftool(t *testing.T) {
+	if exiftoolPath == "" {
+		t.Skip("exiftool not installed; metadata extraction falls back to goexif")
+	}
+
+	raw, dt := extractMetadata(tinyPNG(t), "snapshot.png", nil)
+	if raw == nil {
+		t.Fatal("expected non-nil metadata JSON")
+	}
+	if dt != nil {
+		t.Errorf("a PNG without a capture date should yield no content datetime, got %v", dt)
+	}
+
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatalf("metadata is not valid JSON: %v", err)
+	}
+
+	// exiftool understood the format (goexif never would for PNG).
+	if v := jsonString(t, m, "FileType"); v != "PNG" {
+		t.Errorf("FileType = %q, want PNG", v)
+	}
+
+	// Dimensions are numeric, not human-readable strings.
+	for _, key := range []string{"ImageWidth", "ImageHeight"} {
+		raw, ok := m[key]
+		if !ok {
+			t.Errorf("missing %s", key)
+			continue
+		}
+		var n float64
+		if err := json.Unmarshal(raw, &n); err != nil {
+			t.Errorf("%s is not numeric: %s", key, raw)
+		}
+	}
+
+	// FileName is the original, not the temp file; temp-file artifacts are gone.
+	if v := jsonString(t, m, "FileName"); v != "snapshot.png" {
+		t.Errorf("FileName = %q, want snapshot.png", v)
+	}
+	for _, leaked := range []string{"SourceFile", "Directory", "FilePermissions", "FileModifyDate"} {
+		if _, ok := m[leaked]; ok {
+			t.Errorf("temp-file field %q should have been stripped", leaked)
+		}
+	}
+}
+
+func jsonString(t *testing.T, m map[string]json.RawMessage, key string) string {
+	t.Helper()
+	raw, ok := m[key]
+	if !ok {
+		t.Errorf("missing key %q", key)
+		return ""
+	}
+	var s string
+	if err := json.Unmarshal(raw, &s); err != nil {
+		t.Errorf("key %q is not a string: %s", key, raw)
+		return ""
+	}
+	return s
+}

backend/internal/service/pool_service.go

@@ -0,0 +1,251 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/google/uuid"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+)
+
+const poolObjectType = "pool"
+const poolObjectTypeID int16 = 4 // fourth row in 007_seed_data.sql object_types
+
+// PoolParams holds the fields for creating or patching a pool.
+type PoolParams struct {
+	Name     string
+	Notes    *string
+	Metadata json.RawMessage
+	IsPublic *bool
+}
+
+// PoolService handles pool CRUD and pool–file management with ACL + audit.
+type PoolService struct {
+	pools port.PoolRepo
+	acl   *ACLService
+	audit *AuditService
+}
+
+// NewPoolService creates a PoolService.
+func NewPoolService(
+	pools port.PoolRepo,
+	acl *ACLService,
+	audit *AuditService,
+) *PoolService {
+	return &PoolService{pools: pools, acl: acl, audit: audit}
+}
+
+// ---------------------------------------------------------------------------
+// CRUD
+// ---------------------------------------------------------------------------
+
+// List returns a paginated list of pools the caller may see.
+func (s *PoolService) List(ctx context.Context, params port.OffsetParams) (*domain.PoolOffsetPage, error) {
+	params.ViewerID, params.ViewerIsAdmin, _ = domain.UserFromContext(ctx)
+	return s.pools.List(ctx, params)
+}
+
+// Get returns a pool by ID, enforcing view ACL.
+func (s *PoolService) Get(ctx context.Context, id uuid.UUID) (*domain.Pool, error) {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+	p, err := s.pools.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	ok, err := s.acl.CanView(ctx, userID, isAdmin, p.CreatorID, p.IsPublic, poolObjectTypeID, id)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		return nil, domain.ErrForbidden
+	}
+	return p, nil
+}
+
+// authorizeView returns nil if the caller may view the pool, else ErrForbidden
+// (or ErrNotFound if the pool does not exist).
+func (s *PoolService) authorizeView(ctx context.Context, poolID uuid.UUID) error {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+	p, err := s.pools.GetByID(ctx, poolID)
+	if err != nil {
+		return err
+	}
+	ok, err := s.acl.CanView(ctx, userID, isAdmin, p.CreatorID, p.IsPublic, poolObjectTypeID, poolID)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return domain.ErrForbidden
+	}
+	return nil
+}
+
+// RecordView appends a view-history entry for the current user, enforcing view
+// ACL (you can only record a view of a pool you may see).
+func (s *PoolService) RecordView(ctx context.Context, id uuid.UUID) error {
+	userID, _, _ := domain.UserFromContext(ctx)
+	if err := s.authorizeView(ctx, id); err != nil {
+		return err
+	}
+	return s.pools.RecordView(ctx, id, userID)
+}
+
+// authorizeEdit returns nil if the caller may edit the pool, else ErrForbidden
+// (or ErrNotFound if the pool does not exist).
+func (s *PoolService) authorizeEdit(ctx context.Context, poolID uuid.UUID) error {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+	p, err := s.pools.GetByID(ctx, poolID)
+	if err != nil {
+		return err
+	}
+	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, p.CreatorID, poolObjectTypeID, poolID)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return domain.ErrForbidden
+	}
+	return nil
+}
+
+// Create inserts a new pool.
+func (s *PoolService) Create(ctx context.Context, p PoolParams) (*domain.Pool, error) {
+	userID, _, _ := domain.UserFromContext(ctx)
+
+	pool := &domain.Pool{
+		Name:      p.Name,
+		Notes:     p.Notes,
+		Metadata:  p.Metadata,
+		CreatorID: userID,
+	}
+	if p.IsPublic != nil {
+		pool.IsPublic = *p.IsPublic
+	}
+
+	created, err := s.pools.Create(ctx, pool)
+	if err != nil {
+		return nil, err
+	}
+
+	objType := poolObjectType
+	_ = s.audit.Log(ctx, "pool_create", &objType, &created.ID, nil)
+	return created, nil
+}
+
+// Update applies a partial patch to a pool.
+func (s *PoolService) Update(ctx context.Context, id uuid.UUID, p PoolParams) (*domain.Pool, error) {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+
+	current, err := s.pools.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, current.CreatorID, poolObjectTypeID, id)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		return nil, domain.ErrForbidden
+	}
+
+	patch := *current
+	if p.Name != "" {
+		patch.Name = p.Name
+	}
+	if p.Notes != nil {
+		patch.Notes = p.Notes
+	}
+	if len(p.Metadata) > 0 {
+		patch.Metadata = p.Metadata
+	}
+	if p.IsPublic != nil {
+		patch.IsPublic = *p.IsPublic
+	}
+
+	updated, err := s.pools.Update(ctx, id, &patch)
+	if err != nil {
+		return nil, err
+	}
+
+	objType := poolObjectType
+	_ = s.audit.Log(ctx, "pool_edit", &objType, &id, nil)
+	return updated, nil
+}
+
+// Delete removes a pool by ID, enforcing edit ACL.
+func (s *PoolService) Delete(ctx context.Context, id uuid.UUID) error {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+
+	pool, err := s.pools.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, pool.CreatorID, poolObjectTypeID, id)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return domain.ErrForbidden
+	}
+
+	if err := s.pools.Delete(ctx, id); err != nil {
+		return err
+	}
+
+	objType := poolObjectType
+	_ = s.audit.Log(ctx, "pool_delete", &objType, &id, nil)
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Pool–file operations
+// ---------------------------------------------------------------------------
+
+// ListFiles returns cursor-paginated files within a pool ordered by position,
+// enforcing view ACL on the pool.
+func (s *PoolService) ListFiles(ctx context.Context, poolID uuid.UUID, params port.PoolFileListParams) (*domain.PoolFilePage, error) {
+	if err := s.authorizeView(ctx, poolID); err != nil {
+		return nil, err
+	}
+	return s.pools.ListFiles(ctx, poolID, params)
+}
+
+// AddFiles adds files to a pool at the given position (nil = append), enforcing
+// edit ACL on the pool.
+func (s *PoolService) AddFiles(ctx context.Context, poolID uuid.UUID, fileIDs []uuid.UUID, position *int) error {
+	if err := s.authorizeEdit(ctx, poolID); err != nil {
+		return err
+	}
+	if err := s.pools.AddFiles(ctx, poolID, fileIDs, position); err != nil {
+		return err
+	}
+	objType := poolObjectType
+	_ = s.audit.Log(ctx, "file_pool_add", &objType, &poolID, map[string]any{"count": len(fileIDs)})
+	return nil
+}
+
+// RemoveFiles removes files from a pool, enforcing edit ACL on the pool.
+func (s *PoolService) RemoveFiles(ctx context.Context, poolID uuid.UUID, fileIDs []uuid.UUID) error {
+	if err := s.authorizeEdit(ctx, poolID); err != nil {
+		return err
+	}
+	if err := s.pools.RemoveFiles(ctx, poolID, fileIDs); err != nil {
+		return err
+	}
+	objType := poolObjectType
+	_ = s.audit.Log(ctx, "file_pool_remove", &objType, &poolID, map[string]any{"count": len(fileIDs)})
+	return nil
+}
+
+// Reorder sets the ordered sequence of file IDs within a pool, enforcing edit
+// ACL on the pool.
+func (s *PoolService) Reorder(ctx context.Context, poolID uuid.UUID, fileIDs []uuid.UUID) error {
+	if err := s.authorizeEdit(ctx, poolID); err != nil {
+		return err
+	}
+	return s.pools.Reorder(ctx, poolID, fileIDs)
+}

backend/internal/service/tag_service.go

@@ -0,0 +1,425 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/google/uuid"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+)
+
+const tagObjectType = "tag"
+const tagObjectTypeID int16 = 2 // second row in 007_seed_data.sql object_types
+
+// TagParams holds the fields for creating or patching a tag.
+type TagParams struct {
+	Name       string
+	Notes      *string
+	Color      *string    // nil = no change; pointer to empty string = clear
+	CategoryID *uuid.UUID // nil = no change; Nil UUID = unassign
+	Metadata   json.RawMessage
+	IsPublic   *bool
+}
+
+// TagService handles tag CRUD, tag-rule management, and file–tag operations
+// including automatic recursive rule application.
+type TagService struct {
+	tags  port.TagRepo
+	rules port.TagRuleRepo
+	acl   *ACLService
+	audit *AuditService
+	tx    port.Transactor
+}
+
+// NewTagService creates a TagService.
+func NewTagService(
+	tags port.TagRepo,
+	rules port.TagRuleRepo,
+	acl *ACLService,
+	audit *AuditService,
+	tx port.Transactor,
+) *TagService {
+	return &TagService{
+		tags:  tags,
+		rules: rules,
+		acl:   acl,
+		audit: audit,
+		tx:    tx,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Tag CRUD
+// ---------------------------------------------------------------------------
+
+// List returns a paginated, optionally filtered list of tags the caller may see.
+func (s *TagService) List(ctx context.Context, params port.OffsetParams) (*domain.TagOffsetPage, error) {
+	params.ViewerID, params.ViewerIsAdmin, _ = domain.UserFromContext(ctx)
+	return s.tags.List(ctx, params)
+}
+
+// Get returns a tag by ID, enforcing view ACL.
+func (s *TagService) Get(ctx context.Context, id uuid.UUID) (*domain.Tag, error) {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+	t, err := s.tags.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	ok, err := s.acl.CanView(ctx, userID, isAdmin, t.CreatorID, t.IsPublic, tagObjectTypeID, id)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		return nil, domain.ErrForbidden
+	}
+	return t, nil
+}
+
+// Create inserts a new tag record.
+func (s *TagService) Create(ctx context.Context, p TagParams) (*domain.Tag, error) {
+	userID, _, _ := domain.UserFromContext(ctx)
+
+	t := &domain.Tag{
+		Name:       p.Name,
+		Notes:      p.Notes,
+		Color:      p.Color,
+		CategoryID: p.CategoryID,
+		Metadata:   p.Metadata,
+		CreatorID:  userID,
+	}
+	if p.IsPublic != nil {
+		t.IsPublic = *p.IsPublic
+	}
+
+	created, err := s.tags.Create(ctx, t)
+	if err != nil {
+		return nil, err
+	}
+
+	objType := tagObjectType
+	_ = s.audit.Log(ctx, "tag_create", &objType, &created.ID, nil)
+	return created, nil
+}
+
+// Update applies a partial patch to a tag.
+// The service reads the current tag first so the caller only needs to supply
+// the fields that should change.
+func (s *TagService) Update(ctx context.Context, id uuid.UUID, p TagParams) (*domain.Tag, error) {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+
+	current, err := s.tags.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, current.CreatorID, tagObjectTypeID, id)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		return nil, domain.ErrForbidden
+	}
+
+	// Merge patch into current.
+	patch := *current // copy
+	if p.Name != "" {
+		patch.Name = p.Name
+	}
+	if p.Notes != nil {
+		patch.Notes = p.Notes
+	}
+	if p.Color != nil {
+		patch.Color = p.Color
+	}
+	if p.CategoryID != nil {
+		if *p.CategoryID == uuid.Nil {
+			patch.CategoryID = nil // explicit unassign
+		} else {
+			patch.CategoryID = p.CategoryID
+		}
+	}
+	if len(p.Metadata) > 0 {
+		patch.Metadata = p.Metadata
+	}
+	if p.IsPublic != nil {
+		patch.IsPublic = *p.IsPublic
+	}
+
+	updated, err := s.tags.Update(ctx, id, &patch)
+	if err != nil {
+		return nil, err
+	}
+
+	objType := tagObjectType
+	_ = s.audit.Log(ctx, "tag_edit", &objType, &id, nil)
+	return updated, nil
+}
+
+// Delete removes a tag by ID, enforcing edit ACL.
+func (s *TagService) Delete(ctx context.Context, id uuid.UUID) error {
+	userID, isAdmin, _ := domain.UserFromContext(ctx)
+
+	t, err := s.tags.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	ok, err := s.acl.CanEdit(ctx, userID, isAdmin, t.CreatorID, tagObjectTypeID, id)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return domain.ErrForbidden
+	}
+
+	if err := s.tags.Delete(ctx, id); err != nil {
+		return err
+	}
+
+	objType := tagObjectType
+	_ = s.audit.Log(ctx, "tag_delete", &objType, &id, nil)
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Tag rules
+// ---------------------------------------------------------------------------
+
+// ListRules returns all rules for a tag (when this tag is applied, these follow).
+func (s *TagService) ListRules(ctx context.Context, tagID uuid.UUID) ([]domain.TagRule, error) {
+	return s.rules.ListByTag(ctx, tagID)
+}
+
+// CreateRule adds a tag rule. If applyToExisting is true, the then_tag is
+// retroactively applied to all files that already carry the when_tag.
+// Retroactive application requires a FileRepo; it is deferred until wired
+// in a future iteration (see port.FileRepo.ListByTag).
+func (s *TagService) CreateRule(ctx context.Context, whenTagID, thenTagID uuid.UUID, isActive, _ bool) (*domain.TagRule, error) {
+	return s.rules.Create(ctx, domain.TagRule{
+		WhenTagID: whenTagID,
+		ThenTagID: thenTagID,
+		IsActive:  isActive,
+	})
+}
+
+// SetRuleActive toggles a rule's is_active flag and returns the updated rule.
+// When active and applyToExisting are both true, the full transitive expansion
+// of thenTagID is retroactively applied to files already carrying whenTagID.
+func (s *TagService) SetRuleActive(ctx context.Context, whenTagID, thenTagID uuid.UUID, active, applyToExisting bool) (*domain.TagRule, error) {
+	if err := s.rules.SetActive(ctx, whenTagID, thenTagID, active, applyToExisting); err != nil {
+		return nil, err
+	}
+	rules, err := s.rules.ListByTag(ctx, whenTagID)
+	if err != nil {
+		return nil, err
+	}
+	for _, r := range rules {
+		if r.ThenTagID == thenTagID {
+			return &r, nil
+		}
+	}
+	return nil, domain.ErrNotFound
+}
+
+// DeleteRule removes a tag rule.
+func (s *TagService) DeleteRule(ctx context.Context, whenTagID, thenTagID uuid.UUID) error {
+	return s.rules.Delete(ctx, whenTagID, thenTagID)
+}
+
+// ---------------------------------------------------------------------------
+// File–tag operations (with auto-rule expansion)
+// ---------------------------------------------------------------------------
+
+// ListFileTags returns the tags on a file.
+func (s *TagService) ListFileTags(ctx context.Context, fileID uuid.UUID) ([]domain.Tag, error) {
+	return s.tags.ListByFile(ctx, fileID)
+}
+
+// SetFileTags replaces all tags on a file, then applies active rules for all
+// newly set tags (BFS expansion). Returns the full resulting tag set.
+func (s *TagService) SetFileTags(ctx context.Context, fileID uuid.UUID, tagIDs []uuid.UUID) ([]domain.Tag, error) {
+	expanded, err := s.expandTagSet(ctx, tagIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := s.tags.SetFileTags(ctx, fileID, expanded); err != nil {
+		return nil, err
+	}
+
+	objType := fileObjectType
+	_ = s.audit.Log(ctx, "file_tag_add", &objType, &fileID, nil)
+	return s.tags.ListByFile(ctx, fileID)
+}
+
+// AddFileTag adds a single tag to a file, then recursively applies active rules.
+// Returns the full resulting tag set.
+func (s *TagService) AddFileTag(ctx context.Context, fileID, tagID uuid.UUID) ([]domain.Tag, error) {
+	// Compute the full set including rule-expansion from tagID.
+	extra, err := s.expandTagSet(ctx, []uuid.UUID{tagID})
+	if err != nil {
+		return nil, err
+	}
+
+	// Fetch current tags so we don't lose them.
+	current, err := s.tags.ListByFile(ctx, fileID)
+	if err != nil {
+		return nil, err
+	}
+
+	// Union: existing + expanded new tags.
+	seen := make(map[uuid.UUID]bool, len(current)+len(extra))
+	for _, t := range current {
+		seen[t.ID] = true
+	}
+	merged := make([]uuid.UUID, len(current))
+	for i, t := range current {
+		merged[i] = t.ID
+	}
+	for _, id := range extra {
+		if !seen[id] {
+			seen[id] = true
+			merged = append(merged, id)
+		}
+	}
+
+	if err := s.tags.SetFileTags(ctx, fileID, merged); err != nil {
+		return nil, err
+	}
+
+	objType := fileObjectType
+	_ = s.audit.Log(ctx, "file_tag_add", &objType, &fileID, map[string]any{"tag_id": tagID})
+	return s.tags.ListByFile(ctx, fileID)
+}
+
+// RemoveFileTag removes a single tag from a file.
+func (s *TagService) RemoveFileTag(ctx context.Context, fileID, tagID uuid.UUID) error {
+	if err := s.tags.RemoveFileTag(ctx, fileID, tagID); err != nil {
+		return err
+	}
+
+	objType := fileObjectType
+	_ = s.audit.Log(ctx, "file_tag_remove", &objType, &fileID, map[string]any{"tag_id": tagID})
+	return nil
+}
+
+// BulkSetTags adds or removes tags on multiple files (with rule expansion for add).
+// Returns the tagIDs that were applied (the expanded input set for add; empty for remove).
+func (s *TagService) BulkSetTags(ctx context.Context, fileIDs []uuid.UUID, action string, tagIDs []uuid.UUID) ([]uuid.UUID, error) {
+	if action != "add" && action != "remove" {
+		return nil, domain.ErrValidation
+	}
+
+	// Pre-expand tag set once; all files get the same expansion.
+	var expanded []uuid.UUID
+	if action == "add" {
+		var err error
+		expanded, err = s.expandTagSet(ctx, tagIDs)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	for _, fileID := range fileIDs {
+		switch action {
+		case "add":
+			current, err := s.tags.ListByFile(ctx, fileID)
+			if err != nil {
+				if err == domain.ErrNotFound {
+					continue
+				}
+				return nil, err
+			}
+			seen := make(map[uuid.UUID]bool, len(current))
+			merged := make([]uuid.UUID, len(current))
+			for i, t := range current {
+				seen[t.ID] = true
+				merged[i] = t.ID
+			}
+			for _, id := range expanded {
+				if !seen[id] {
+					seen[id] = true
+					merged = append(merged, id)
+				}
+			}
+			if err := s.tags.SetFileTags(ctx, fileID, merged); err != nil {
+				return nil, err
+			}
+		case "remove":
+			current, err := s.tags.ListByFile(ctx, fileID)
+			if err != nil {
+				if err == domain.ErrNotFound {
+					continue
+				}
+				return nil, err
+			}
+			remove := make(map[uuid.UUID]bool, len(tagIDs))
+			for _, id := range tagIDs {
+				remove[id] = true
+			}
+			kept := make([]uuid.UUID, 0, len(current))
+			for _, t := range current {
+				if !remove[t.ID] {
+					kept = append(kept, t.ID)
+				}
+			}
+			if err := s.tags.SetFileTags(ctx, fileID, kept); err != nil {
+				return nil, err
+			}
+		}
+	}
+
+	if action == "add" {
+		return expanded, nil
+	}
+	return []uuid.UUID{}, nil
+}
+
+// CommonTags returns tags present on ALL given files and tags present on SOME.
+func (s *TagService) CommonTags(ctx context.Context, fileIDs []uuid.UUID) (common, partial []domain.Tag, err error) {
+	common, err = s.tags.CommonTagsForFiles(ctx, fileIDs)
+	if err != nil {
+		return nil, nil, err
+	}
+	partial, err = s.tags.PartialTagsForFiles(ctx, fileIDs)
+	if err != nil {
+		return nil, nil, err
+	}
+	return common, partial, nil
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+// expandTagSet runs a BFS from the given seed tags, following active tag rules,
+// and returns the full set of tag IDs that should be applied (seeds + auto-applied).
+func (s *TagService) expandTagSet(ctx context.Context, seeds []uuid.UUID) ([]uuid.UUID, error) {
+	visited := make(map[uuid.UUID]bool, len(seeds))
+	queue := make([]uuid.UUID, 0, len(seeds))
+
+	for _, id := range seeds {
+		if !visited[id] {
+			visited[id] = true
+			queue = append(queue, id)
+		}
+	}
+
+	for i := 0; i < len(queue); i++ {
+		tagID := queue[i]
+		rules, err := s.rules.ListByTag(ctx, tagID)
+		if err != nil {
+			return nil, err
+		}
+		for _, r := range rules {
+			if r.IsActive && !visited[r.ThenTagID] {
+				visited[r.ThenTagID] = true
+				queue = append(queue, r.ThenTagID)
+			}
+		}
+	}
+
+	return queue, nil
+}

backend/internal/service/user_service.go

@@ -0,0 +1,192 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"golang.org/x/crypto/bcrypt"
+
+	"tanabata/backend/internal/domain"
+	"tanabata/backend/internal/port"
+)
+
+// UserService handles user CRUD and profile management.
+type UserService struct {
+	users    port.UserRepo
+	sessions port.SessionRepo
+	audit    *AuditService
+}
+
+// NewUserService creates a UserService.
+func NewUserService(users port.UserRepo, sessions port.SessionRepo, audit *AuditService) *UserService {
+	return &UserService{users: users, sessions: sessions, audit: audit}
+}
+
+// EnsureAdmin creates the initial administrator account if it does not already
+// exist. It is idempotent and never overwrites an existing user's password, so
+// an operator who has changed the admin password keeps it across restarts.
+func (s *UserService) EnsureAdmin(ctx context.Context, username, password string) error {
+	if username == "" || password == "" {
+		return fmt.Errorf("EnsureAdmin: username and password must be set")
+	}
+
+	if _, err := s.users.GetByName(ctx, username); err == nil {
+		return nil // already exists
+	} else if !errors.Is(err, domain.ErrNotFound) {
+		return fmt.Errorf("EnsureAdmin: lookup: %w", err)
+	}
+
+	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+	if err != nil {
+		return fmt.Errorf("EnsureAdmin: hash: %w", err)
+	}
+	_, err = s.users.Create(ctx, &domain.User{
+		Name:      username,
+		Password:  string(hash),
+		IsAdmin:   true,
+		CanCreate: true,
+	})
+	if err != nil {
+		return fmt.Errorf("EnsureAdmin: create: %w", err)
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Self-service
+// ---------------------------------------------------------------------------
+
+// GetMe returns the profile of the currently authenticated user.
+func (s *UserService) GetMe(ctx context.Context) (*domain.User, error) {
+	userID, _, _ := domain.UserFromContext(ctx)
+	return s.users.GetByID(ctx, userID)
+}
+
+// UpdateMeParams holds fields a user may change on their own profile.
+type UpdateMeParams struct {
+	Name     string  // empty = no change
+	Password *string // nil = no change
+}
+
+// UpdateMe allows a user to change their own name and/or password.
+func (s *UserService) UpdateMe(ctx context.Context, p UpdateMeParams) (*domain.User, error) {
+	userID, _, _ := domain.UserFromContext(ctx)
+
+	current, err := s.users.GetByID(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+
+	patch := *current
+	if p.Name != "" {
+		patch.Name = p.Name
+	}
+	if p.Password != nil {
+		hash, err := bcrypt.GenerateFromPassword([]byte(*p.Password), bcrypt.DefaultCost)
+		if err != nil {
+			return nil, fmt.Errorf("UserService.UpdateMe hash: %w", err)
+		}
+		patch.Password = string(hash)
+	}
+
+	return s.users.Update(ctx, userID, &patch)
+}
+
+// ---------------------------------------------------------------------------
+// Admin CRUD
+// ---------------------------------------------------------------------------
+
+// List returns a paginated list of users (admin only — caller must enforce).
+func (s *UserService) List(ctx context.Context, params port.OffsetParams) (*domain.UserPage, error) {
+	return s.users.List(ctx, params)
+}
+
+// Get returns a user by ID (admin only).
+func (s *UserService) Get(ctx context.Context, id int16) (*domain.User, error) {
+	return s.users.GetByID(ctx, id)
+}
+
+// CreateParams holds fields for creating a new user.
+type CreateUserParams struct {
+	Name      string
+	Password  string
+	IsAdmin   bool
+	CanCreate bool
+}
+
+// Create inserts a new user with a bcrypt-hashed password (admin only).
+func (s *UserService) Create(ctx context.Context, p CreateUserParams) (*domain.User, error) {
+	hash, err := bcrypt.GenerateFromPassword([]byte(p.Password), bcrypt.DefaultCost)
+	if err != nil {
+		return nil, fmt.Errorf("UserService.Create hash: %w", err)
+	}
+
+	u := &domain.User{
+		Name:      p.Name,
+		Password:  string(hash),
+		IsAdmin:   p.IsAdmin,
+		CanCreate: p.CanCreate,
+	}
+	created, err := s.users.Create(ctx, u)
+	if err != nil {
+		return nil, err
+	}
+
+	_ = s.audit.Log(ctx, "user_create", nil, nil, map[string]any{"target_user_id": created.ID})
+	return created, nil
+}
+
+// UpdateAdminParams holds fields an admin may change on any user.
+type UpdateAdminParams struct {
+	IsAdmin   *bool
+	CanCreate *bool
+	IsBlocked *bool
+}
+
+// UpdateAdmin applies an admin-level patch to a user.
+func (s *UserService) UpdateAdmin(ctx context.Context, id int16, p UpdateAdminParams) (*domain.User, error) {
+	current, err := s.users.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	patch := *current
+	if p.IsAdmin != nil {
+		patch.IsAdmin = *p.IsAdmin
+	}
+	if p.CanCreate != nil {
+		patch.CanCreate = *p.CanCreate
+	}
+	if p.IsBlocked != nil {
+		patch.IsBlocked = *p.IsBlocked
+	}
+
+	updated, err := s.users.Update(ctx, id, &patch)
+	if err != nil {
+		return nil, err
+	}
+
+	// Log block/unblock specifically, and revoke all sessions on block so the
+	// user's outstanding access tokens stop working immediately.
+	if p.IsBlocked != nil {
+		action := "user_unblock"
+		if *p.IsBlocked {
+			action = "user_block"
+			if err := s.sessions.DeleteByUserID(ctx, id); err != nil {
+				return nil, fmt.Errorf("UserService.UpdateAdmin revoke sessions: %w", err)
+			}
+		}
+		_ = s.audit.Log(ctx, action, nil, nil, map[string]any{"target_user_id": id})
+	}
+	return updated, nil
+}
+
+// Delete removes a user by ID (admin only).
+func (s *UserService) Delete(ctx context.Context, id int16) error {
+	if err := s.users.Delete(ctx, id); err != nil {
+		return err
+	}
+	_ = s.audit.Log(ctx, "user_delete", nil, nil, map[string]any{"target_user_id": id})
+	return nil
+}

backend/internal/storage/disk.go

@@ -5,16 +5,18 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	_ "golang.org/x/image/webp" // register WebP decoder
 	"image"
 	"image/color"
-	"image/jpeg"
 	_ "image/gif" // register GIF decoder
+	"image/jpeg"
 	_ "image/png" // register PNG decoder
-	_ "golang.org/x/image/webp"      // register WebP decoder
 	"io"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
+	"time"
 
 	"github.com/disintegration/imaging"
 	"github.com/google/uuid"
@@ -37,20 +39,36 @@ type DiskStorage struct {
 	thumbHeight   int
 	previewWidth  int
 	previewHeight int
+	maxPixels     int
+	// genSem bounds concurrent thumbnail/preview generation. Each resize already
+	// fans out across every core (imaging uses GOMAXPROCS), and large sources cost
+	// hundreds of MB to decode, so unbounded parallelism on a burst of big images
+	// pegs the CPU and can exhaust RAM. A buffered channel caps how many run at once.
+	genSem chan struct{}
 }
 
 var _ port.FileStorage = (*DiskStorage)(nil)
 
 // NewDiskStorage creates a DiskStorage and ensures both directories exist.
+//
+// maxPixels caps the source pixel count we will decode in-process (0 → a sane
+// default). concurrency bounds simultaneous generation (≤0 → half the CPUs).
 func NewDiskStorage(
 	filesPath, thumbsPath string,
 	thumbW, thumbH, prevW, prevH int,
+	maxPixels, concurrency int,
 ) (*DiskStorage, error) {
 	for _, p := range []string{filesPath, thumbsPath} {
 		if err := os.MkdirAll(p, 0o755); err != nil {
 			return nil, fmt.Errorf("storage: create directory %q: %w", p, err)
 		}
 	}
+	if maxPixels <= 0 {
+		maxPixels = defaultMaxDecodePixels
+	}
+	if concurrency <= 0 {
+		concurrency = max(1, runtime.GOMAXPROCS(0)/2)
+	}
 	return &DiskStorage{
 		filesPath:     filesPath,
 		thumbsPath:    thumbsPath,
@@ -58,6 +76,8 @@ func NewDiskStorage(
 		thumbHeight:   thumbH,
 		previewWidth:  prevW,
 		previewHeight: prevH,
+		maxPixels:     maxPixels,
+		genSem:        make(chan struct{}, concurrency),
 	}, nil
 }
 
@@ -108,16 +128,29 @@ func (s *DiskStorage) Delete(_ context.Context, id uuid.UUID) error {
 	return nil
 }
 
-// Thumbnail returns a JPEG that fits within the configured max width×height
+// InvalidateCache removes the cached thumbnail and preview for id, if present,
-// (never upscaled, never cropped). Generated on first call and cached.
+// so they are regenerated from the current file content on the next request.
-// Video files are thumbnailed via ffmpeg; other non-image files get a placeholder.
+func (s *DiskStorage) InvalidateCache(_ context.Context, id uuid.UUID) error {
+	for _, p := range []string{s.thumbCachePath(id), s.previewCachePath(id)} {
+		if err := os.Remove(p); err != nil && !os.IsNotExist(err) {
+			return fmt.Errorf("storage.InvalidateCache remove %q: %w", p, err)
+		}
+	}
+	return nil
+}
+
+// Thumbnail returns a JPEG scaled to fit within the configured max width×height,
+// preserving the original aspect ratio (never upscaled, never cropped); the grid
+// cell letterboxes it as needed. Generated on first call and cached. Video files
+// are thumbnailed via ffmpeg; other non-image files get a placeholder.
 func (s *DiskStorage) Thumbnail(ctx context.Context, id uuid.UUID) (io.ReadCloser, error) {
 	return s.serveGenerated(ctx, id, s.thumbCachePath(id), s.thumbWidth, s.thumbHeight)
 }
 
-// Preview returns a JPEG that fits within the configured max width×height
+// Preview returns a JPEG scaled to fit within the configured max width×height,
-// (never upscaled, never cropped). Generated on first call and cached.
+// preserving the original aspect ratio (never upscaled, never cropped) so the
-// Video files are thumbnailed via ffmpeg; other non-image files get a placeholder.
+// viewer shows the whole image. Generated on first call and cached. Video files
+// are thumbnailed via ffmpeg; other non-image files get a placeholder.
 func (s *DiskStorage) Preview(ctx context.Context, id uuid.UUID) (io.ReadCloser, error) {
 	return s.serveGenerated(ctx, id, s.previewCachePath(id), s.previewWidth, s.previewHeight)
 }
@@ -126,14 +159,16 @@ func (s *DiskStorage) Preview(ctx context.Context, id uuid.UUID) (io.ReadCloser,
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-// serveGenerated is the shared implementation for Thumbnail and Preview.
+// serveGenerated is the shared implementation for Thumbnail and Preview. Both
-// imaging.Thumbnail fits the source within maxW×maxH without upscaling or cropping.
+// fit the source within maxW×maxH preserving the aspect ratio (no crop, no
+// upscale); they differ only in the configured dimensions.
 //
 // Resolution order:
 //  1. Return cached JPEG if present.
-//  2. Decode as still image (JPEG/PNG/GIF via imaging).
+//  2. vipsthumbnail (shrink-on-load; the primary still-image path).
-//  3. Extract a frame with ffmpeg (video files).
+//  3. Pure-Go decode + imaging.Fit (fallback when vips is absent).
-//  4. Solid-colour placeholder (archives, unrecognised formats, etc.).
+//  4. Extract a frame with ffmpeg (video files).
+//  5. Solid-colour placeholder (archives, unrecognised formats, etc.).
 func (s *DiskStorage) serveGenerated(ctx context.Context, id uuid.UUID, cachePath string, maxW, maxH int) (io.ReadCloser, error) {
 	// Fast path: cache hit.
 	if f, err := os.Open(cachePath); err == nil {
@@ -149,14 +184,40 @@ func (s *DiskStorage) serveGenerated(ctx context.Context, id uuid.UUID, cachePat
 		return nil, fmt.Errorf("storage: stat %q: %w", srcPath, err)
 	}
 
-	// 1. Try still-image decode (JPEG/PNG/GIF).
+	// Bound concurrent generation so a burst of large images can't peg every core
-	// 2. Try video frame extraction via ffmpeg.
+	// or exhaust RAM. Queue here (respecting cancellation) rather than starting
-	// 3. Fall back to placeholder.
+	// the heavy decode immediately.
+	select {
+	case s.genSem <- struct{}{}:
+		defer func() { <-s.genSem }()
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	}
+
+	// Another request may have generated this while we waited on the semaphore.
+	if f, err := os.Open(cachePath); err == nil {
+		return f, nil
+	}
+
+	// Primary path: vipsthumbnail. It shrinks on load (e.g. JPEG DCT scaling), so
+	// even a 200+ Mpx photo is thumbnailed in a fraction of the memory and CPU of a
+	// full in-process decode, writing the final JPEG straight to the cache. Falls
+	// through when vips is absent or can't read the source (e.g. a video).
+	if vipsThumbnailPath != "" {
+		if rc, err := s.vipsThumbnail(ctx, srcPath, cachePath, maxW, maxH); err == nil {
+			return rc, nil
+		}
+	}
+
+	// Fallback pipeline (pure Go):
+	//  1. Still-image decode (JPEG/PNG/GIF), rejecting oversized rasters.
+	//  2. Video frame extraction via ffmpeg.
+	//  3. Solid-colour placeholder.
 	var img image.Image
-	if decoded, err := imaging.Open(srcPath, imaging.AutoOrientation(true)); err == nil {
+	if decoded, err := decodeImageLimited(srcPath, s.maxPixels); err == nil {
-		img = imaging.Thumbnail(decoded, maxW, maxH, imaging.Lanczos)
+		img = imaging.Fit(decoded, maxW, maxH, imaging.Lanczos)
 	} else if frame, err := extractVideoFrame(ctx, srcPath); err == nil {
-		img = imaging.Thumbnail(frame, maxW, maxH, imaging.Lanczos)
+		img = imaging.Fit(frame, maxW, maxH, imaging.Lanczos)
 	} else {
 		img = placeholder(maxW, maxH)
 	}
@@ -206,12 +267,91 @@ func writeCache(cachePath string, img image.Image) (io.ReadCloser, error) {
 	return f, nil
 }
 
+// defaultMaxDecodePixels is the fallback cap when none is configured. It bounds
+// the cost of a decompression bomb (a tiny file that expands to an enormous
+// raster) and the per-image memory; ~300 Mpx covers e.g. a 13000×17000 photo.
+const defaultMaxDecodePixels = 300_000_000
+
+// decodeImageLimited decodes the image at path after first inspecting its header
+// dimensions via image.DecodeConfig (which does not allocate the raster), and
+// refuses images whose pixel count exceeds maxPixels.
+func decodeImageLimited(path string, maxPixels int) (image.Image, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	cfg, _, err := image.DecodeConfig(f)
+	if err != nil {
+		return nil, err
+	}
+	if int64(cfg.Width)*int64(cfg.Height) > int64(maxPixels) {
+		return nil, fmt.Errorf("image too large to decode: %dx%d", cfg.Width, cfg.Height)
+	}
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		return nil, err
+	}
+	return imaging.Decode(f, imaging.AutoOrientation(true))
+}
+
+// vipsThumbnailPath is the resolved path to the vipsthumbnail CLI, or "" when it
+// isn't installed — in which case generation falls back to the pure-Go pipeline.
+var vipsThumbnailPath, _ = exec.LookPath("vipsthumbnail")
+
+// vipsThumbnail generates a JPEG thumbnail with the vipsthumbnail CLI, writing it
+// straight to cachePath via an atomic temp→rename. vips decodes large images at a
+// reduced scale (shrink-on-load), so this costs a fraction of the memory and CPU
+// of a full in-process decode. The result is fit within maxW×maxH and never
+// upscaled (the ">" size modifier). Returns an error for inputs vips can't read
+// (e.g. videos) so the caller can fall back.
+func (s *DiskStorage) vipsThumbnail(ctx context.Context, srcPath, cachePath string, maxW, maxH int) (io.ReadCloser, error) {
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+
+	tmp, err := os.CreateTemp(filepath.Dir(cachePath), ".vips-*.jpg")
+	if err != nil {
+		return nil, fmt.Errorf("storage: create temp file: %w", err)
+	}
+	tmpName := tmp.Name()
+	_ = tmp.Close()
+
+	cmd := exec.CommandContext(ctx, vipsThumbnailPath,
+		srcPath,
+		"--size", fmt.Sprintf("%dx%d>", maxW, maxH),
+		"--output", tmpName+"[Q=85]",
+	)
+	cmd.Stderr = io.Discard
+
+	if err := cmd.Run(); err != nil {
+		os.Remove(tmpName)
+		return nil, fmt.Errorf("vipsthumbnail: %w", err)
+	}
+	if fi, err := os.Stat(tmpName); err != nil || fi.Size() == 0 {
+		os.Remove(tmpName)
+		return nil, fmt.Errorf("vipsthumbnail: no output produced")
+	}
+	if err := os.Rename(tmpName, cachePath); err != nil {
+		os.Remove(tmpName)
+		return nil, fmt.Errorf("storage: rename cache file: %w", err)
+	}
+	f, err := os.Open(cachePath)
+	if err != nil {
+		return nil, fmt.Errorf("storage: open cache file: %w", err)
+	}
+	return f, nil
+}
+
 // extractVideoFrame uses ffmpeg to extract a single frame from a video file.
 // It seeks 1 second in (keyframe-accurate fast seek) and pipes the frame out
 // as PNG. If the video is shorter than 1 s the seek is silently ignored by
 // ffmpeg and the first available frame is returned instead.
-// Returns an error if ffmpeg is not installed or produces no output.
+// Returns an error if ffmpeg is not installed or produces no output. The run is
+// bounded by a timeout so a malformed file cannot hang the request indefinitely.
 func extractVideoFrame(ctx context.Context, srcPath string) (image.Image, error) {
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+
 	var out bytes.Buffer
 	cmd := exec.CommandContext(ctx, "ffmpeg",
 		"-ss", "1", // fast input seek; ignored gracefully on short files

backend/internal/storage/disk_test.go

@@ -0,0 +1,181 @@
+package storage
+
+import (
+	"bytes"
+	"context"
+	"image"
+	"image/color"
+	"image/png"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/disintegration/imaging"
+	"github.com/google/uuid"
+)
+
+// writeTestImage writes a w×h PNG filled with a distinct (non-placeholder)
+// colour so a generated thumbnail can be told apart from the grey placeholder.
+func writeTestImage(t *testing.T, path string, w, h int) {
+	t.Helper()
+	img := image.NewNRGBA(image.Rect(0, 0, w, h))
+	for y := 0; y < h; y++ {
+		for x := 0; x < w; x++ {
+			img.Set(x, y, color.NRGBA{R: 0xC0, G: 0x10, B: 0x20, A: 0xFF})
+		}
+	}
+	f, err := os.Create(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	if err := png.Encode(f, img); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestDecodeImageLimited(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "img.png")
+	writeTestImage(t, p, 100, 80) // 8000 px
+
+	if _, err := decodeImageLimited(p, 4000); err == nil {
+		t.Fatal("expected rejection for an image over the pixel cap")
+	}
+
+	img, err := decodeImageLimited(p, 100000)
+	if err != nil {
+		t.Fatalf("expected decode within the cap, got %v", err)
+	}
+	if b := img.Bounds(); b.Dx() != 100 || b.Dy() != 80 {
+		t.Fatalf("unexpected decoded size %v", b.Size())
+	}
+}
+
+// TestThumbnailGeneratesAndCaches exercises the full generation path (semaphore
+// acquire → decode → fit → encode → cache) and the cache fast path on re-request.
+func TestThumbnailGeneratesAndCaches(t *testing.T) {
+	files := t.TempDir()
+	thumbs := t.TempDir()
+	id := uuid.New()
+	writeTestImage(t, filepath.Join(files, id.String()), 100, 80)
+
+	s, err := NewDiskStorage(files, thumbs, 160, 160, 1920, 1080, 0, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	rc, err := s.Thumbnail(context.Background(), id)
+	if err != nil {
+		t.Fatalf("Thumbnail: %v", err)
+	}
+	data, _ := io.ReadAll(rc)
+	rc.Close()
+
+	out, err := imaging.Decode(bytes.NewReader(data))
+	if err != nil {
+		t.Fatalf("decode thumbnail: %v", err)
+	}
+	// The source fits within 160×160, so it is not upscaled.
+	if b := out.Bounds(); b.Dx() != 100 || b.Dy() != 80 {
+		t.Fatalf("unexpected thumbnail size %v", b.Size())
+	}
+	// Centre pixel should be the source's red, not the grey placeholder.
+	r, g, b, _ := out.At(50, 40).RGBA()
+	if !(r>>8 > g>>8+40 && r>>8 > b>>8+40) {
+		t.Fatalf("thumbnail is not the source image (got r=%d g=%d b=%d) — fell back to placeholder?", r>>8, g>>8, b>>8)
+	}
+
+	// The cache file must now exist, and a second request must serve it.
+	if _, err := os.Stat(s.thumbCachePath(id)); err != nil {
+		t.Fatalf("cache file not written: %v", err)
+	}
+	rc2, err := s.Thumbnail(context.Background(), id)
+	if err != nil {
+		t.Fatalf("Thumbnail (cached): %v", err)
+	}
+	rc2.Close()
+}
+
+// TestThumbnailFallbackWithoutVips forces the pure-Go pipeline (as if vips were
+// not installed) and verifies generation still produces the source image.
+func TestThumbnailFallbackWithoutVips(t *testing.T) {
+	orig := vipsThumbnailPath
+	vipsThumbnailPath = ""
+	t.Cleanup(func() { vipsThumbnailPath = orig })
+
+	files := t.TempDir()
+	thumbs := t.TempDir()
+	id := uuid.New()
+	writeTestImage(t, filepath.Join(files, id.String()), 100, 80)
+
+	s, err := NewDiskStorage(files, thumbs, 160, 160, 1920, 1080, 0, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	rc, err := s.Thumbnail(context.Background(), id)
+	if err != nil {
+		t.Fatalf("Thumbnail: %v", err)
+	}
+	data, _ := io.ReadAll(rc)
+	rc.Close()
+
+	out, err := imaging.Decode(bytes.NewReader(data))
+	if err != nil {
+		t.Fatalf("decode thumbnail: %v", err)
+	}
+	if b := out.Bounds(); b.Dx() != 100 || b.Dy() != 80 {
+		t.Fatalf("unexpected thumbnail size %v", b.Size())
+	}
+	r, g, b, _ := out.At(50, 40).RGBA()
+	if !(r>>8 > g>>8+40 && r>>8 > b>>8+40) {
+		t.Fatalf("fallback produced a placeholder, not the source (r=%d g=%d b=%d)", r>>8, g>>8, b>>8)
+	}
+}
+
+// TestPreviewGeneratesAndCaches verifies Preview runs through the same pipeline
+// with the preview dimensions and its own cache file (not the thumbnail's).
+func TestPreviewGeneratesAndCaches(t *testing.T) {
+	files := t.TempDir()
+	thumbs := t.TempDir()
+	id := uuid.New()
+	// Larger than the thumbnail box but within the preview box, so the preview
+	// keeps full resolution where a thumbnail would shrink it.
+	writeTestImage(t, filepath.Join(files, id.String()), 400, 300)
+
+	s, err := NewDiskStorage(files, thumbs, 160, 160, 1920, 1080, 0, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	rc, err := s.Preview(context.Background(), id)
+	if err != nil {
+		t.Fatalf("Preview: %v", err)
+	}
+	data, _ := io.ReadAll(rc)
+	rc.Close()
+
+	out, err := imaging.Decode(bytes.NewReader(data))
+	if err != nil {
+		t.Fatalf("decode preview: %v", err)
+	}
+	// 400×300 fits within 1920×1080, so the preview is not downscaled.
+	if b := out.Bounds(); b.Dx() != 400 || b.Dy() != 300 {
+		t.Fatalf("unexpected preview size %v", b.Size())
+	}
+	r, g, b, _ := out.At(200, 150).RGBA()
+	if !(r>>8 > g>>8+40 && r>>8 > b>>8+40) {
+		t.Fatalf("preview is not the source image (r=%d g=%d b=%d)", r>>8, g>>8, b>>8)
+	}
+
+	// The preview cache must be written, and the thumbnail cache must not — they
+	// are separate files served by the same code with different dimensions.
+	if _, err := os.Stat(s.previewCachePath(id)); err != nil {
+		t.Fatalf("preview cache not written: %v", err)
+	}
+	if _, err := os.Stat(s.thumbCachePath(id)); err == nil {
+		t.Fatal("thumbnail cache should not exist after a preview-only request")
+	}
+}

backend/migrations/003_data_tables.sql

@@ -50,7 +50,7 @@ CREATE TABLE data.files (
     content_datetime timestamptz  NOT NULL DEFAULT clock_timestamp(),  -- content datetime (e.g. photo taken)
     notes            text,
     metadata         jsonb,                 -- user-editable key-value data
-    exif             jsonb        NOT NULL DEFAULT '{}'::jsonb,  -- EXIF data extracted at upload (immutable)
+    exif             jsonb,                 -- EXIF data extracted at upload (immutable)
     phash            bigint,                -- perceptual hash for duplicate detection (future)
     creator_id       smallint     NOT NULL REFERENCES core.users(id)
                                   ON UPDATE CASCADE ON DELETE RESTRICT,

backend/migrations/007_seed_data.sql

@@ -38,12 +38,12 @@ INSERT INTO activity.action_types (name) VALUES
     -- Sessions
     ('session_terminate');
 
-INSERT INTO core.users (name, password, is_admin, can_create) VALUES
+-- The initial administrator is created at application startup from the
-    ('admin', '$2a$10$zk.VTFjRRxbkTE7cKfc7KOWeZfByk1VEkbkgZMJggI1fFf.yDEHZy', true, true);
+-- ADMIN_USERNAME / ADMIN_PASSWORD environment variables (see UserService.
+-- EnsureAdmin), so no default credentials are seeded here.
 
 -- +goose Down
 
-DELETE FROM core.users WHERE name = 'admin';
 DELETE FROM activity.action_types;
 DELETE FROM core.object_types;
 DELETE FROM core.mime_types;

docker-compose.yml

@@ -0,0 +1,104 @@
+# =============================================================================
+# Tanabata File Manager — Docker Compose
+#
+# Quick start:
+#   cp .env.example .env        # then edit the secrets
+#   docker compose up -d --build
+#
+# Database — two supported modes, selected in .env:
+#
+#   1. Bundled Postgres container (default).
+#        COMPOSE_PROFILES=with-db
+#        DATABASE_URL=postgres://tanabata:password@db:5432/tanabata?sslmode=disable
+#
+#   2. Postgres already running on the host.
+#        COMPOSE_PROFILES=          # empty → the db container is not started
+#        DATABASE_URL=postgres://tanabata:password@host.docker.internal:5432/tanabata?sslmode=disable
+#
+# Requires Docker Compose v2.20+ (for depends_on.required).
+# =============================================================================
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: tfm
+    restart: unless-stopped
+
+    # All application config (secrets, DATABASE_URL, tunables) comes from .env.
+    env_file: .env
+
+    # Pin STATIC_DIR to the path baked into the image. .env intentionally leaves
+    # it unset; pinning here guarantees in-container SPA serving can't be
+    # disabled by an empty value leaking in through env_file.
+    environment:
+      STATIC_DIR: /app/static
+
+    # The container always listens on 42776 (Dockerfile default); APP_PORT only
+    # changes the host-published port.
+    ports:
+      - "${APP_PORT:-42776}:42776"
+
+    # Wait for the bundled DB when the with-db profile is active. When using a
+    # host Postgres the db service is disabled, and required:false keeps this
+    # dependency from erroring or auto-starting it.
+    depends_on:
+      db:
+        condition: service_healthy
+        required: false
+
+    # Lets DATABASE_URL reach a Postgres on the host via host.docker.internal
+    # (needed on Linux; harmless elsewhere).
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+    # Run as this uid:gid. Relevant when the mounts below are bind-mounted to
+    # host folders: set PUID/PGID (in .env) to the owner of those folders so the
+    # container can write to them. Defaults to the image's tanabata user
+    # (42776), which owns the named volumes.
+    user: "${PUID:-42776}:${PGID:-42776}"
+
+    # Storage for originals, the thumbnail cache, and the import drop folder.
+    # Each source defaults to a named volume but can be pointed at a specific
+    # host folder via FILES_DIR / THUMBS_DIR / IMPORT_DIR in .env (a path turns
+    # the mount into a host bind mount; a bare name stays a named volume).
+    volumes:
+      - "${FILES_DIR:-app_files}:/data/files"
+      - "${THUMBS_DIR:-app_thumbs}:/data/thumbs"
+      - "${IMPORT_DIR:-app_import}:/data/import"
+
+  db:
+    image: postgres:14-alpine
+    restart: unless-stopped
+
+    # Only started when COMPOSE_PROFILES includes "with-db". Disable it to point
+    # the app at a Postgres running on the host instead.
+    profiles: ["with-db"]
+
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-tanabata}
+      POSTGRES_USER: ${POSTGRES_USER:-tanabata}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-password}
+
+    # Defaults to a named volume; set DB_DIR in .env to a host folder to bind
+    # mount it instead. Postgres fixes the folder's ownership itself, so DB_DIR
+    # needs no PUID/PGID.
+    volumes:
+      - "${DB_DIR:-db_data}:/var/lib/postgresql/data"
+
+    # Uncomment to reach the DB from the host (e.g. with psql) for debugging.
+    # ports:
+    #   - "5432:5432"
+
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-tanabata} -d ${POSTGRES_DB:-tanabata}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  app_files:
+  app_thumbs:
+  app_import:
+  db_data:

docs/DEPLOY.md

@@ -0,0 +1,182 @@
+# Deployment (Gitea Actions → host)
+
+Tanabata is deployed by a [Gitea Actions](https://docs.gitea.com/usage/actions/overview)
+workflow ([`.gitea/workflows/deploy.yml`](../.gitea/workflows/deploy.yml)) that
+runs on the **production host itself**. On every push to `master` it updates the
+git clone in `/opt/tanabata` and runs `docker compose up -d --build` there, so the
+image is built from the freshly-pushed code and the stack is restarted.
+
+```
+push master ──> Gitea (container) ──> act_runner (host, "host" label)
+                                          │ git fetch + reset --hard   (in /opt/tanabata)
+                                          └ docker compose up -d --build
+```
+
+The Gitea server runs in a container, but the **runner runs directly on the host**
+(shell executor) so it can use the host's git, the host Docker daemon, and the
+clone in `/opt/tanabata`. Nothing needs a registry — the host builds the image
+locally. The workflow uses only shell steps, so the host needs just **git** and
+**docker** (no node, no rsync).
+
+## What is a runner?
+
+Gitea (like GitHub) only *coordinates* CI: it stores the workflow, queues jobs,
+and shows logs. It does **not** execute anything itself. A **runner** is a
+separate agent program that polls Gitea for queued jobs, runs the steps on a
+machine you control, and reports results back.
+
+Gitea's official runner is **act_runner** (a single Go binary; it uses the
+`act` engine to interpret workflow YAML). One act_runner process can serve many
+repos. Each runner advertises one or more **labels**, and a job's `runs-on:`
+picks a runner by label. A label also decides *how* a job runs — the **executor**:
+
+- **docker executor** — each job runs in a fresh container from an image (e.g.
+  `node:20-bookworm`). Isolated and reproducible; the usual default. Label form
+  at registration: `ubuntu:docker://node:20-bookworm`.
+- **host / shell executor** — the job runs directly on the host as the runner's
+  user, using host-installed tools. Label form: `host:host`. This is what we use,
+  because the deploy needs the host's Docker daemon and `/opt/tanabata`.
+
+So `runs-on: host` in the workflow ⇒ "run this job on a runner that registered a
+`host` label" ⇒ our shell executor on the prod box.
+
+## One-time setup
+
+### 1. Enable Actions in Gitea
+
+Gitea 1.21+ has Actions on by default. Otherwise add to `app.ini` and restart:
+
+```ini
+[actions]
+ENABLED = true
+```
+
+### 2. A runner user on the host
+
+Pick (or create) the Linux user the runner runs as. It must be able to use Docker
+and own the deploy dir — so the workflow needs no `sudo`:
+
+```bash
+sudo useradd -r -m -d /home/gitea-runner gitea-runner   # or reuse an existing user
+sudo usermod -aG docker gitea-runner                     # host Docker access
+```
+
+The host needs `git` and a Docker engine with the Compose plugin:
+
+```bash
+sudo apt install -y git docker.io docker-compose-plugin   # Debian/Ubuntu
+```
+
+### 3. Clone the repo to /opt/tanabata once
+
+The workflow only does `git fetch` + `reset --hard`, so the clone (and its auth)
+is established here, once. Use a **read-only deploy key** so the host never holds
+write credentials:
+
+```bash
+# As the runner user, create a key and add the PUBLIC half to the repo in Gitea:
+#   Repo → Settings → Deploy Keys → Add (read-only)
+sudo -u gitea-runner ssh-keygen -t ed25519 -f /home/gitea-runner/.ssh/tanabata_deploy -N ''
+
+# Clone with that key (SSH URL of your Gitea repo):
+sudo -u gitea-runner GIT_SSH_COMMAND='ssh -i /home/gitea-runner/.ssh/tanabata_deploy' \
+  git clone git@gitea.example.com:you/tanabata.git /opt/tanabata
+sudo chown -R gitea-runner:gitea-runner /opt/tanabata
+```
+
+> HTTPS works too — clone with a URL that carries a read-only token. SSH deploy
+> keys are the cleaner, per-repo, read-only option.
+
+After cloning, recurring `git fetch` reuses the remote + key stored in
+`/opt/tanabata/.git/config`, so the runner itself needs no standing credentials.
+
+### 4. Register and run act_runner on the host
+
+Get a registration token in Gitea. **Where you create it sets the runner's
+scope** (and `--name` is only a display label, unrelated to scope):
+
+- **Repository** (Tanabata repo → Settings → Actions → Runners) → serves only
+  this repo. **Use this.**
+- Organization → all repos in the org; Site (admin) → all repos on the instance.
+
+> Security: this runner is a host/shell executor with access to the Docker
+> socket — effectively root on the host. Register it at the **repository** level
+> so only Tanabata's workflows can run on your prod server; a site-wide runner
+> would let any repo's workflow execute arbitrary commands here.
+
+Then, as the runner user:
+
+```bash
+# Download act_runner: https://gitea.com/gitea/act_runner/releases
+act_runner register --no-interactive \
+  --instance https://gitea.example.com \
+  --token   <REGISTRATION_TOKEN> \
+  --name    prod-host \
+  --labels  host:host          # <-- maps `runs-on: host` to the shell executor
+
+# Run it (use a systemd unit in production so it survives reboots):
+act_runner daemon
+```
+
+`--labels host:host` is what makes jobs run **on the host** instead of in a
+container. The instance URL must be reachable from the host (Gitea's published
+port / domain — not the in-container address). Registration writes a `.runner`
+file (the runner's credentials) in the working directory.
+
+Minimal systemd unit (`/etc/systemd/system/act_runner.service`):
+
+```ini
+[Unit]
+Description=Gitea act_runner
+After=docker.service
+Requires=docker.service
+
+[Service]
+User=gitea-runner
+WorkingDirectory=/home/gitea-runner
+ExecStart=/usr/local/bin/act_runner daemon
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable --now act_runner
+```
+
+### 5. Create /opt/tanabata/.env (secrets)
+
+The workflow **never** writes `.env` — it lives on the host and holds the real
+secrets and the chosen DB mode. `.env` is git-ignored, so `git reset --hard`
+leaves it untouched. Create it once:
+
+```bash
+cd /opt/tanabata
+sudo -u gitea-runner cp .env.example .env
+sudo -u gitea-runner $EDITOR .env    # set JWT_SECRET, ADMIN_PASSWORD, DATABASE_URL, etc.
+```
+
+See [`.env.example`](../.env.example) for every variable. For the bundled
+Postgres keep `COMPOSE_PROFILES=with-db`; to use a Postgres already on the host,
+set it empty and point `DATABASE_URL` at `host.docker.internal`.
+
+> Data lives in named Docker volumes by default (or the `*_DIR` host paths you
+> set in `.env`, e.g. `/var/lib/tanabata/...`) — **not** in `/opt/tanabata`. So
+> `git reset --hard` on the code dir never touches your data.
+
+## Deploying
+
+Push to `master` (or hit **Run workflow** on the Actions tab). Watch progress
+under the repo's **Actions** tab. The first build pulls the Node/Go base images
+and takes a few minutes; later builds reuse the host's layer cache.
+
+## Notes / alternatives
+
+- **Docker-executor runner instead of host.** If you'd rather the runner itself
+  run in a container, register with a Docker label and bind-mount
+  `/var/run/docker.sock` and `/opt/tanabata` into the job (act_runner
+  `config.yaml` → `container.valid_volumes`), then change `runs-on` accordingly.
+  The host executor above is simpler for host deploys.
+- **Zero-downtime** isn't attempted: `compose up` recreates changed containers.
+  For a single-node setup the brief restart is usually fine.

docs/FRONTEND_STRUCTURE.md

@@ -10,6 +10,46 @@
 - **Font**: Epilogue (variable weight)
 - **Package manager**: npm
 
+## SPA mode — why SvelteKit without the server
+
+This frontend runs as a **pure client-side SPA**: `adapter-static` with
+`fallback: 'index.html'` and `ssr = false` globally (see
+`src/routes/+layout.ts`). There is no Node server in production — the build is
+static assets, and the only backend is the Go API. SvelteKit is used here
+purely as an SPA framework: file-based routing, the client router, and build
+tooling.
+
+**SvelteKit features we *do* use:**
+
+- File-based routing with nested layouts (`admin/` has its own guard) and
+  dynamic segments (`[id]`).
+- The client router: `goto`, the `page` store/state, `afterNavigate`,
+  `navigating`.
+- **Shallow routing** — `pushState`/`replaceState` + `page.state`. The
+  Immich-style file viewer in `files/` and `pools/[id]/` opens as an overlay
+  over the still-mounted list via shallow routing, so the browser back button
+  dismisses it without reloading the grid. This is the single biggest reason we
+  stay on SvelteKit rather than a plain router.
+- `load` functions, used *only* as client-side route guards (auth redirect,
+  admin redirect, `/` → `/files`).
+- `$lib` alias, generated `./$types`, Vite/HMR integration.
+
+**SvelteKit features we deliberately do *not* use** (the "server half"):
+
+- SSR / hydration.
+- `+page.server.ts`, `+server.ts` endpoints, form actions — all data goes
+  through the Go API via the `$lib/api` client.
+- `hooks.*`, prerendering, server-only modules — no `hooks.server.ts` /
+  `hooks.client.ts` files exist.
+
+**Decision: stay on SvelteKit, do not migrate to a bare Svelte + router SPA.**
+The project already *is* an SPA, so there is no runtime gain from switching
+(adapter-static tree-shakes the unused server bits; the client-runtime size
+difference is negligible). A migration would mean re-implementing nested
+layouts, guards, dynamic params, and — most painfully — shallow routing /
+history-state overlays by hand, for zero benefit. New contributors should not
+expect SSR, endpoints, or hooks to do anything here; that is intentional.
+
 ## Monorepo Layout
 
 ```
@@ -49,8 +89,7 @@ frontend/
 ├── src/
 │   ├── app.html                    # Shell HTML (PWA meta, font preload)
 │   ├── app.css                     # Tailwind directives + CSS custom properties
-│   ├── hooks.server.ts             # Server hooks (not used in SPA mode)
+│   │                               # (no hooks.* — see "SPA mode" above)
-│   ├── hooks.client.ts             # Client hooks (global error handling)
 │   │
 │   ├── lib/                        # Shared code ($lib/ alias)
 │   │   │

docs/GO_PROJECT_STRUCTURE.md

@@ -297,7 +297,7 @@ stored as hash in `activity.sessions.token_hash`.
 
 ```env
 # Server
-LISTEN_ADDR=:8080
+LISTEN_ADDR=:42776
 JWT_SECRET=<random-32-bytes>
 JWT_ACCESS_TTL=15m
 JWT_REFRESH_TTL=720h

frontend/.prettierignore

@@ -0,0 +1,11 @@
+# Build output and dependencies
+.svelte-kit
+build
+node_modules
+package-lock.json
+
+# Generated from openapi.yaml — formatting would be overwritten on regen
+src/lib/api/schema.ts
+
+# Static assets (fonts, icons, manifest, robots)
+static

frontend/.prettierrc

@@ -0,0 +1,15 @@
+{
+	"useTabs": true,
+	"singleQuote": true,
+	"trailingComma": "none",
+	"printWidth": 100,
+	"plugins": ["prettier-plugin-svelte"],
+	"overrides": [
+		{
+			"files": "*.svelte",
+			"options": {
+				"parser": "svelte"
+			}
+		}
+	]
+}

frontend/package-lock.json

@@ -13,7 +13,10 @@
 				"@sveltejs/kit": "^2.50.2",
 				"@sveltejs/vite-plugin-svelte": "^6.2.4",
 				"@tailwindcss/vite": "^4.2.2",
+				"@types/node": "^25.5.2",
 				"openapi-typescript": "^7.13.0",
+				"prettier": "^3.8.4",
+				"prettier-plugin-svelte": "^4.1.0",
 				"svelte": "^5.54.0",
 				"svelte-check": "^4.4.2",
 				"tailwindcss": "^4.2.2",
@@ -1345,6 +1348,16 @@
 			"dev": true,
 			"license": "MIT"
 		},
+		"node_modules/@types/node": {
+			"version": "25.5.2",
+			"resolved": "https://registry.npmjs.org/@types/node/-/node-25.5.2.tgz",
+			"integrity": "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"undici-types": "~7.18.0"
+			}
+		},
 		"node_modules/@types/trusted-types": {
 			"version": "2.0.7",
 			"resolved": "https://registry.npmjs.org/@types/trusted-types/-/trusted-types-2.0.7.tgz",
@@ -2199,6 +2212,36 @@
 				"node": "^10 || ^12 || >=14"
 			}
 		},
+		"node_modules/prettier": {
+			"version": "3.8.4",
+			"resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.4.tgz",
+			"integrity": "sha512-N2MylSdi48+5N/6S5j+maeHbUSIzzZ5uOcX5Hm4QpV8Dkb1HFjfAKTKX6yNPJQD9AhcT3ifHNB66tWTTJDi11Q==",
+			"dev": true,
+			"license": "MIT",
+			"bin": {
+				"prettier": "bin/prettier.cjs"
+			},
+			"engines": {
+				"node": ">=14"
+			},
+			"funding": {
+				"url": "https://github.com/prettier/prettier?sponsor=1"
+			}
+		},
+		"node_modules/prettier-plugin-svelte": {
+			"version": "4.1.0",
+			"resolved": "https://registry.npmjs.org/prettier-plugin-svelte/-/prettier-plugin-svelte-4.1.0.tgz",
+			"integrity": "sha512-YZkhA2Q9oOerFFG9tq+2f98WYT7Z2JgrybJrAyrB78jpsH9i/DdgplXemehuFPgsldetFNCcR/yCcYlDjPy94Q==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=20"
+			},
+			"peerDependencies": {
+				"prettier": "^3.0.0",
+				"svelte": "^5.0.0"
+			}
+		},
 		"node_modules/readdirp": {
 			"version": "4.1.2",
 			"resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
@@ -2453,6 +2496,13 @@
 				"node": ">=14.17"
 			}
 		},
+		"node_modules/undici-types": {
+			"version": "7.18.2",
+			"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
+			"integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+			"dev": true,
+			"license": "MIT"
+		},
 		"node_modules/uri-js-replace": {
 			"version": "1.0.1",
 			"resolved": "https://registry.npmjs.org/uri-js-replace/-/uri-js-replace-1.0.1.tgz",

frontend/package.json

@@ -10,7 +10,9 @@
 		"preview": "vite preview",
 		"prepare": "svelte-kit sync || echo ''",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
-		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"format": "prettier --write .",
+		"format:check": "prettier --check ."
 	},
 	"devDependencies": {
 		"@sveltejs/adapter-auto": "^7.0.0",
@@ -18,7 +20,10 @@
 		"@sveltejs/kit": "^2.50.2",
 		"@sveltejs/vite-plugin-svelte": "^6.2.4",
 		"@tailwindcss/vite": "^4.2.2",
+		"@types/node": "^25.5.2",
 		"openapi-typescript": "^7.13.0",
+		"prettier": "^3.8.4",
+		"prettier-plugin-svelte": "^4.1.0",
 		"svelte": "^5.54.0",
 		"svelte-check": "^4.4.2",
 		"tailwindcss": "^4.2.2",

frontend/src/app.css

@@ -1,30 +1,37 @@
 @import 'tailwindcss';
 
 @theme {
-  --color-bg-primary: #312F45;
+	--color-bg-primary: #312f45;
 	--color-bg-secondary: #181721;
 	--color-bg-elevated: #111118;
-  --color-accent: #9592B5;
+	--color-accent: #9592b5;
-  --color-accent-hover: #7D7AA4;
+	--color-accent-hover: #7d7aa4;
 	--color-text-primary: #f0f0f0;
-  --color-text-muted: #9999AD;
+	--color-text-muted: #9999ad;
-  --color-danger: #DB6060;
+	--color-danger: #db6060;
-  --color-info: #4DC7ED;
+	--color-info: #4dc7ed;
-  --color-warning: #F5E872;
+	--color-warning: #f5e872;
 	--color-tag-default: #444455;
+	--color-nav-bg: rgba(0, 0, 0, 0.45);
+	--color-nav-active: rgba(52, 50, 73, 0.72);
 
 	--font-sans: 'Epilogue', sans-serif;
 }
 
-:root[data-theme="light"] {
+:root[data-theme='light'] {
-  --color-bg-primary: #f5f5f5;
+	/* Muted, faintly lavender-tinted surfaces — not a glaring near-white, the same
-  --color-bg-secondary: #ffffff;
+     way the dark theme's background isn't pure black. Page sits on the dimmest
-  --color-bg-elevated: #e8e8ec;
+     surface; sheets are brighter to pop, chips a touch darker for definition. */
-  --color-accent: #6B68A0;
+	--color-bg-primary: #e4e2ec;
-  --color-accent-hover: #5A578F;
+	--color-bg-secondary: #f2f1f6;
+	--color-bg-elevated: #d8d6e2;
+	--color-accent: #6b68a0;
+	--color-accent-hover: #5a578f;
 	--color-text-primary: #111118;
 	--color-text-muted: #555566;
-  --color-tag-default: #ccccdd;
+	--color-tag-default: #cbcad9;
+	--color-nav-bg: rgba(228, 226, 236, 0.85);
+	--color-nav-active: rgba(90, 87, 143, 0.22);
 }
 
 @font-face {

frontend/src/app.d.ts

@@ -5,7 +5,11 @@ declare global {
 		// interface Error {}
 		// interface Locals {}
 		// interface PageData {}
-		// interface PageState {}
+		interface PageState {
+			/** Set via shallow routing when the file viewer is open as an overlay
+			 *  on top of the files list. */
+			fileId?: string;
+		}
 		// interface Platform {}
 	}
 }

frontend/src/app.html

@@ -3,7 +3,35 @@
 	<head>
 		<meta charset="utf-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1" />
-		<link rel="preload" href="/fonts/Epilogue-VariableFont_wght.ttf" as="font" type="font/ttf" crossorigin="anonymous" />
+		<meta name="theme-color" content="#312F45" />
+		<meta name="mobile-web-app-capable" content="yes" />
+		<meta name="apple-mobile-web-app-capable" content="yes" />
+		<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+		<meta name="apple-mobile-web-app-title" content="Tanabata" />
+		<meta name="msapplication-TileColor" content="#312F45" />
+		<meta name="msapplication-TileImage" content="/images/ms-icon-144x144.png" />
+		<meta name="msapplication-config" content="/browserconfig.xml" />
+		<link rel="manifest" href="/manifest.webmanifest" />
+		<link rel="icon" type="image/x-icon" href="/favicon.ico" />
+		<link rel="icon" type="image/png" sizes="96x96" href="/images/favicon-96x96.png" />
+		<link rel="icon" type="image/png" sizes="32x32" href="/images/favicon-32x32.png" />
+		<link rel="icon" type="image/png" sizes="16x16" href="/images/favicon-16x16.png" />
+		<link rel="apple-touch-icon" sizes="57x57" href="/images/apple-icon-57x57.png" />
+		<link rel="apple-touch-icon" sizes="60x60" href="/images/apple-icon-60x60.png" />
+		<link rel="apple-touch-icon" sizes="72x72" href="/images/apple-icon-72x72.png" />
+		<link rel="apple-touch-icon" sizes="76x76" href="/images/apple-icon-76x76.png" />
+		<link rel="apple-touch-icon" sizes="114x114" href="/images/apple-icon-114x114.png" />
+		<link rel="apple-touch-icon" sizes="120x120" href="/images/apple-icon-120x120.png" />
+		<link rel="apple-touch-icon" sizes="144x144" href="/images/apple-icon-144x144.png" />
+		<link rel="apple-touch-icon" sizes="152x152" href="/images/apple-icon-152x152.png" />
+		<link rel="apple-touch-icon" sizes="180x180" href="/images/apple-icon-180x180.png" />
+		<link
+			rel="preload"
+			href="/fonts/Epilogue-VariableFont_wght.ttf"
+			as="font"
+			type="font/ttf"
+			crossorigin="anonymous"
+		/>
 		%sveltekit.head%
 	</head>
 	<body data-sveltekit-preload-data="hover">

frontend/src/lib/api/auth.ts

@@ -0,0 +1,45 @@
+import { get } from 'svelte/store';
+import { authStore } from '$lib/stores/auth';
+import { api } from './client';
+import type { TokenPair, SessionList } from './types';
+
+export async function login(name: string, password: string): Promise<void> {
+	const tokens = await api.post<TokenPair>('/auth/login', { name, password });
+	authStore.update((s) => ({
+		...s,
+		accessToken: tokens.access_token ?? null,
+		refreshToken: tokens.refresh_token ?? null
+	}));
+}
+
+export async function logout(): Promise<void> {
+	try {
+		await api.post('/auth/logout');
+	} finally {
+		authStore.set({ accessToken: null, refreshToken: null, user: null });
+	}
+}
+
+export async function refresh(): Promise<void> {
+	const { refreshToken } = get(authStore);
+	if (!refreshToken) throw new Error('No refresh token');
+
+	const tokens = await api.post<TokenPair>('/auth/refresh', { refresh_token: refreshToken });
+	authStore.update((s) => ({
+		...s,
+		accessToken: tokens.access_token ?? null,
+		refreshToken: tokens.refresh_token ?? null
+	}));
+}
+
+export function listSessions(params?: { offset?: number; limit?: number }): Promise<SessionList> {
+	const entries = Object.entries(params ?? {})
+		.filter(([, v]) => v !== undefined)
+		.map(([k, v]) => [k, String(v)]);
+	const qs = entries.length ? '?' + new URLSearchParams(entries).toString() : '';
+	return api.get<SessionList>(`/auth/sessions${qs}`);
+}
+
+export function terminateSession(sessionId: number): Promise<void> {
+	return api.delete<void>(`/auth/sessions/${sessionId}`);
+}

frontend/src/lib/api/categories.ts

@@ -0,0 +1,28 @@
+import { get } from 'svelte/store';
+import { api } from '$lib/api/client';
+import type { Category, CategoryOffsetPage } from '$lib/api/types';
+import { categorySorting } from '$lib/stores/sorting';
+
+// The /categories endpoint caps limit at 200 per request. Category dropdowns
+// show the whole list, so page through to get them all — otherwise categories
+// past the first 200 are missing from the picker.
+const PAGE = 200;
+
+/**
+ * Fetches every category, paging past the server's per-request cap. Ordered by
+ * the sort the user picked on the categories page (categorySorting).
+ */
+export async function fetchAllCategories(): Promise<Category[]> {
+	const { sort, order } = get(categorySorting);
+	const all: Category[] = [];
+	for (let offset = 0; ; offset += PAGE) {
+		const page = await api.get<CategoryOffsetPage>(
+			`/categories?limit=${PAGE}&offset=${offset}&sort=${sort}&order=${order}`
+		);
+		const items = page.items ?? [];
+		all.push(...items);
+		const total = page.total ?? all.length;
+		if (items.length < PAGE || all.length >= total) break;
+	}
+	return all;
+}

frontend/src/lib/api/client.ts

@@ -0,0 +1,245 @@
+import { get } from 'svelte/store';
+import { goto } from '$app/navigation';
+import { browser } from '$app/environment';
+import { authStore } from '$lib/stores/auth';
+import { clearSection, type SectionKey } from '$lib/stores/sectionCache';
+
+const BASE = '/api/v1';
+
+// The tags/categories/pools lists are edited on their own detail/new pages, so a
+// cached list snapshot goes stale after a write there. Drop the matching
+// section's snapshot on any successful mutation so the list refetches on return.
+// (Files isn't included — its grid keeps itself consistent via optimistic
+// updates, and over-invalidating would needlessly lose the scroll position.)
+function invalidateSectionCache(path: string, method: string): void {
+	if (method === 'GET') return;
+	const sections: SectionKey[] = ['tags', 'categories', 'pools'];
+	for (const s of sections) {
+		if (path === `/${s}` || path.startsWith(`/${s}/`) || path.startsWith(`/${s}?`)) {
+			clearSection(s);
+			return;
+		}
+	}
+}
+
+/** Clear the session and bounce to the login screen. Called when the refresh
+ *  token is missing or rejected, so an expired session doesn't strand the user
+ *  on a page that only shows errors. */
+function endSession(): void {
+	authStore.set({ accessToken: null, refreshToken: null, user: null });
+	if (browser) void goto('/login');
+}
+
+export class ApiError extends Error {
+	constructor(
+		public readonly status: number,
+		public readonly code: string,
+		message: string,
+		public readonly details?: Array<{ field?: string; message?: string }>
+	) {
+		super(message);
+		this.name = 'ApiError';
+	}
+}
+
+// Deduplicates concurrent 401 refresh attempts into a single in-flight request.
+let refreshPromise: Promise<void> | null = null;
+
+async function refreshTokens(): Promise<void> {
+	const attempted = get(authStore).refreshToken;
+	if (!attempted) {
+		endSession();
+		throw new ApiError(401, 'unauthorized', 'Session expired');
+	}
+
+	const res = await fetch(`${BASE}/auth/refresh`, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify({ refresh_token: attempted })
+	});
+
+	if (!res.ok) {
+		// Refresh tokens rotate, so another tab may have already refreshed and
+		// rotated ours out. If a newer token has since synced in from that tab (via
+		// the auth store's storage listener), adopt it and let the caller retry
+		// rather than ending a session that's actually still alive.
+		if (get(authStore).refreshToken !== attempted) return;
+		endSession();
+		throw new ApiError(401, 'unauthorized', 'Session expired');
+	}
+
+	const data = await res.json();
+	authStore.update((s) => ({
+		...s,
+		accessToken: data.access_token ?? null,
+		refreshToken: data.refresh_token ?? null
+	}));
+}
+
+function buildHeaders(init: RequestInit | undefined, accessToken: string | null): HeadersInit {
+	const isFormData = init?.body instanceof FormData;
+	const base: Record<string, string> = isFormData ? {} : { 'Content-Type': 'application/json' };
+	if (accessToken) base['Authorization'] = `Bearer ${accessToken}`;
+	return { ...base, ...(init?.headers as Record<string, string> | undefined) };
+}
+
+async function request<T>(path: string, init?: RequestInit): Promise<T> {
+	let res = await fetch(BASE + path, {
+		...init,
+		headers: buildHeaders(init, get(authStore).accessToken)
+	});
+
+	if (res.status === 401) {
+		if (!refreshPromise) {
+			refreshPromise = refreshTokens().finally(() => {
+				refreshPromise = null;
+			});
+		}
+		try {
+			await refreshPromise;
+		} catch {
+			throw new ApiError(401, 'unauthorized', 'Session expired');
+		}
+
+		res = await fetch(BASE + path, {
+			...init,
+			headers: buildHeaders(init, get(authStore).accessToken)
+		});
+	}
+
+	if (!res.ok) {
+		let body: {
+			code?: string;
+			message?: string;
+			details?: Array<{ field?: string; message?: string }>;
+		} = {};
+		try {
+			body = await res.json();
+		} catch {
+			// ignore parse failure
+		}
+		throw new ApiError(
+			res.status,
+			body.code ?? 'error',
+			body.message ?? res.statusText,
+			body.details
+		);
+	}
+
+	invalidateSectionCache(path, (init?.method ?? 'GET').toUpperCase());
+
+	if (res.status === 204) return undefined as T;
+	return res.json();
+}
+
+/** Upload with XHR so we can track progress via onProgress(0–100). */
+export function uploadWithProgress<T>(
+	path: string,
+	formData: FormData,
+	onProgress: (pct: number) => void
+): Promise<T> {
+	return new Promise((resolve, reject) => {
+		const token = get(authStore).accessToken;
+		const xhr = new XMLHttpRequest();
+		xhr.open('POST', BASE + path);
+		if (token) xhr.setRequestHeader('Authorization', `Bearer ${token}`);
+
+		xhr.upload.onprogress = (e) => {
+			if (e.lengthComputable) onProgress(Math.round((e.loaded / e.total) * 100));
+		};
+
+		xhr.onload = () => {
+			if (xhr.status >= 200 && xhr.status < 300) {
+				try {
+					resolve(JSON.parse(xhr.responseText) as T);
+				} catch {
+					resolve(undefined as T);
+				}
+			} else {
+				let body: { code?: string; message?: string } = {};
+				try {
+					body = JSON.parse(xhr.responseText);
+				} catch {
+					/* ignore */
+				}
+				reject(new ApiError(xhr.status, body.code ?? 'error', body.message ?? xhr.statusText));
+			}
+		};
+
+		xhr.onerror = () => reject(new ApiError(0, 'network_error', 'Network error'));
+		xhr.send(formData);
+	});
+}
+
+/** POST that consumes a streamed newline-delimited JSON (NDJSON) response,
+ *  invoking onEvent once per parsed line. Used by the server-side import so the
+ *  UI can render live per-file progress. Reuses the bearer token and a single
+ *  401 refresh+retry, but (unlike request()) keeps the body as a stream. */
+export async function postStream(
+	path: string,
+	body: unknown,
+	onEvent: (ev: Record<string, unknown>) => void
+): Promise<void> {
+	const init: RequestInit = { method: 'POST', body: JSON.stringify(body) };
+	const send = () =>
+		fetch(BASE + path, { ...init, headers: buildHeaders(init, get(authStore).accessToken) });
+
+	let res = await send();
+	if (res.status === 401) {
+		if (!refreshPromise) {
+			refreshPromise = refreshTokens().finally(() => {
+				refreshPromise = null;
+			});
+		}
+		try {
+			await refreshPromise;
+		} catch {
+			throw new ApiError(401, 'unauthorized', 'Session expired');
+		}
+		res = await send();
+	}
+
+	if (!res.ok || !res.body) {
+		let b: { code?: string; message?: string } = {};
+		try {
+			b = await res.json();
+		} catch {
+			// ignore parse failure
+		}
+		throw new ApiError(res.status, b.code ?? 'error', b.message ?? res.statusText);
+	}
+
+	const reader = res.body.getReader();
+	const decoder = new TextDecoder();
+	let buf = '';
+	const flushLine = (line: string) => {
+		const trimmed = line.trim();
+		if (trimmed) onEvent(JSON.parse(trimmed));
+	};
+
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buf += decoder.decode(value, { stream: true });
+		let nl: number;
+		while ((nl = buf.indexOf('\n')) >= 0) {
+			flushLine(buf.slice(0, nl));
+			buf = buf.slice(nl + 1);
+		}
+	}
+	buf += decoder.decode();
+	flushLine(buf);
+}
+
+export const api = {
+	get: <T>(path: string) => request<T>(path),
+	post: <T>(path: string, body?: unknown) =>
+		request<T>(path, { method: 'POST', body: JSON.stringify(body) }),
+	patch: <T>(path: string, body?: unknown) =>
+		request<T>(path, { method: 'PATCH', body: JSON.stringify(body) }),
+	put: <T>(path: string, body?: unknown) =>
+		request<T>(path, { method: 'PUT', body: JSON.stringify(body) }),
+	delete: <T>(path: string) => request<T>(path, { method: 'DELETE' }),
+	upload: <T>(path: string, formData: FormData) =>
+		request<T>(path, { method: 'POST', body: formData })
+};

frontend/src/lib/api/tags.ts

@@ -0,0 +1,64 @@
+import { get } from 'svelte/store';
+import { api } from '$lib/api/client';
+import type { Tag, TagOffsetPage } from '$lib/api/types';
+import { tagSorting, type SortState, type TagSortField } from '$lib/stores/sorting';
+
+// The /tags endpoint caps limit at 200 per request. Pickers and the filter bar
+// filter the tag list client-side, so they need the *whole* list — otherwise
+// tags past the first 200 are invisible and unsearchable. Page through until we
+// have them all.
+const PAGE = 200;
+
+/**
+ * Fetches every tag, paging past the server's per-request cap. Ordered by the
+ * sort the user picked on the tags page (tagSorting), so the pickers and filter
+ * bar show tags in the same order as that page.
+ */
+export async function fetchAllTags(): Promise<Tag[]> {
+	const { sort, order } = get(tagSorting);
+	const all: Tag[] = [];
+	for (let offset = 0; ; offset += PAGE) {
+		const page = await api.get<TagOffsetPage>(
+			`/tags?limit=${PAGE}&offset=${offset}&sort=${sort}&order=${order}`
+		);
+		const items = page.items ?? [];
+		all.push(...items);
+		const total = page.total ?? all.length;
+		if (items.length < PAGE || all.length >= total) break;
+	}
+	return all;
+}
+
+// Field a tag is keyed on for a given sort choice. created_at is an ISO string,
+// so lexical comparison matches chronological order.
+function tagSortKey(t: Tag, field: TagSortField): string {
+	switch (field) {
+		case 'name':
+			return t.name ?? '';
+		case 'color':
+			return t.color ?? '';
+		case 'category_name':
+			return t.category_name ?? '';
+		case 'created':
+			return t.created_at ?? '';
+		default:
+			return '';
+	}
+}
+
+/**
+ * Returns a copy of `tags` sorted by the given tag sort state — used to order a
+ * file's already-assigned tags the same way as the tags page and the pickers'
+ * available list (which the server sorts). Client-side so it reacts instantly
+ * when the user changes the sort.
+ */
+export function sortTags(tags: Tag[], { sort, order }: SortState<TagSortField>): Tag[] {
+	const dir = order === 'asc' ? 1 : -1;
+	return [...tags].sort((a, b) => {
+		const primary = dir * tagSortKey(a, sort).localeCompare(tagSortKey(b, sort));
+		if (primary !== 0 || sort !== 'category_name') return primary;
+		// Same category: break the tie by the tag's own name (same direction), so
+		// tags are grouped by category then alphabetical — matching the server.
+		return dir * (a.name ?? '').localeCompare(b.name ?? '');
+	});
+}

frontend/src/lib/api/types.ts

@@ -7,6 +7,7 @@ export type Pool = components['schemas']['Pool'];
 export type PoolFile = components['schemas']['PoolFile'];
 export type User = components['schemas']['User'];
 export type Session = components['schemas']['Session'];
+export type TokenPair = components['schemas']['TokenPair'];
 export type Permission = components['schemas']['Permission'];
 export type AuditEntry = components['schemas']['AuditLogEntry'];
 export type TagRule = components['schemas']['TagRule'];

frontend/src/lib/components/common/ConfirmDialog.svelte

@@ -0,0 +1,123 @@
+<script lang="ts">
+	interface Props {
+		message: string;
+		confirmLabel?: string;
+		danger?: boolean;
+		onConfirm: () => void;
+		onCancel: () => void;
+	}
+
+	let { message, confirmLabel = 'Confirm', danger = false, onConfirm, onCancel }: Props = $props();
+
+	let dialog = $state<HTMLDialogElement | undefined>();
+
+	$effect(() => {
+		dialog?.showModal();
+		return () => dialog?.close();
+	});
+
+	function handleKeydown(e: KeyboardEvent) {
+		if (e.key === 'Escape') onCancel();
+	}
+
+	function handleBackdropClick(e: MouseEvent) {
+		if (e.target === dialog) onCancel();
+	}
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<dialog
+	bind:this={dialog}
+	onkeydown={handleKeydown}
+	onclick={handleBackdropClick}
+	aria-modal="true"
+>
+	<div class="body">
+		<p class="message">{message}</p>
+		<div class="actions">
+			<button class="btn cancel" onclick={onCancel}>Cancel</button>
+			<button class="btn confirm" class:danger onclick={onConfirm}>{confirmLabel}</button>
+		</div>
+	</div>
+</dialog>
+
+<style>
+	dialog {
+		padding: 0;
+		border: none;
+		border-radius: 12px;
+		background-color: var(--color-bg-secondary);
+		color: var(--color-text-primary);
+		box-shadow: 0 8px 32px rgba(0, 0, 0, 0.6);
+		max-width: min(340px, calc(100vw - 32px));
+		width: 100%;
+		position: fixed;
+		top: 50%;
+		left: 50%;
+		transform: translate(-50%, -50%);
+		margin: 0;
+	}
+
+	dialog::backdrop {
+		background-color: rgba(0, 0, 0, 0.55);
+		backdrop-filter: blur(2px);
+	}
+
+	.body {
+		padding: 20px 20px 16px;
+		display: flex;
+		flex-direction: column;
+		gap: 18px;
+	}
+
+	.message {
+		margin: 0;
+		font-size: 0.9rem;
+		line-height: 1.5;
+		color: var(--color-text-primary);
+	}
+
+	.actions {
+		display: flex;
+		gap: 8px;
+		justify-content: flex-end;
+	}
+
+	.btn {
+		height: 36px;
+		padding: 0 16px;
+		border-radius: 8px;
+		font-size: 0.875rem;
+		font-weight: 600;
+		font-family: inherit;
+		cursor: pointer;
+	}
+
+	.btn.cancel {
+		border: 1px solid color-mix(in srgb, var(--color-accent) 35%, transparent);
+		background: none;
+		color: var(--color-text-primary);
+	}
+
+	.btn.cancel:hover {
+		background-color: color-mix(in srgb, var(--color-accent) 12%, transparent);
+	}
+
+	.btn.confirm {
+		border: none;
+		background-color: var(--color-accent);
+		color: var(--color-bg-primary);
+	}
+
+	.btn.confirm:hover {
+		background-color: var(--color-accent-hover);
+	}
+
+	.btn.confirm.danger {
+		background-color: var(--color-danger);
+	}
+
+	.btn.confirm.danger:hover {
+		background-color: color-mix(in srgb, var(--color-danger) 80%, #fff);
+	}
+</style>

frontend/src/lib/components/common/InfiniteScroll.svelte

@@ -0,0 +1,105 @@
+<script lang="ts">
+	interface Props {
+		loading?: boolean;
+		hasMore?: boolean;
+		onLoadMore: () => void;
+		/** Which edge to watch: 'bottom' loads on scroll down, 'top' on scroll up. */
+		edge?: 'top' | 'bottom';
+	}
+
+	let { loading = false, hasMore = true, onLoadMore, edge = 'bottom' }: Props = $props();
+
+	// Lookahead distance past the viewport edge at which we start loading.
+	const MARGIN = 300;
+
+	let sentinel = $state<HTMLDivElement | undefined>();
+
+	// True while the sentinel is within MARGIN px of the watched viewport edge.
+	// Measuring the sentinel's viewport rect (rather than a scroll container's
+	// scrollHeight/clientHeight) makes this correct whether the page scrolls on
+	// <main> or on the window, and loads only enough to reach past the viewport.
+	function nearViewport(): boolean {
+		if (!sentinel) return false;
+		const rect = sentinel.getBoundingClientRect();
+		return edge === 'bottom' ? rect.top <= window.innerHeight + MARGIN : rect.bottom >= -MARGIN;
+	}
+
+	function maybeLoad() {
+		if (loading || !hasMore || !sentinel) return;
+		if (nearViewport()) onLoadMore();
+	}
+
+	// Load on scroll. We watch the actual scroll position rather than relying on an
+	// IntersectionObserver, which fires only on enter/leave transitions: a scroll
+	// that *ends* with the sentinel already in range (e.g. scrolling straight to the
+	// bottom) produces no new observer callback, so nothing loads until the user
+	// scrolls back up and down to force a fresh transition. Re-checking the sentinel
+	// on every scroll is what reliably keeps the list growing.
+	//
+	// `capture: true` is required because scroll events don't bubble — capturing lets
+	// a single window listener catch scrolls from any nested scroll container (here
+	// the grid's <main>) as well as the document itself. rAF-throttled so it stays
+	// cheap (one getBoundingClientRect per frame at most).
+	$effect(() => {
+		let scheduled = false;
+		const onScroll = () => {
+			if (scheduled) return;
+			scheduled = true;
+			requestAnimationFrame(() => {
+				scheduled = false;
+				maybeLoad();
+			});
+		};
+		window.addEventListener('scroll', onScroll, { passive: true, capture: true });
+		window.addEventListener('resize', onScroll, { passive: true });
+		return () => {
+			window.removeEventListener('scroll', onScroll, { capture: true });
+			window.removeEventListener('resize', onScroll);
+		};
+	});
+
+	// Re-check after mount and after each load settles (loading → false): if the
+	// freshly added content still didn't push the sentinel past the viewport, load
+	// again. This fills short pages and covers the sentinel already being in range on
+	// first render, without waiting for a scroll.
+	$effect(() => {
+		if (!loading) maybeLoad();
+	});
+</script>
+
+<div bind:this={sentinel} class="sentinel" aria-hidden="true"></div>
+
+{#if loading}
+	<div class="loading-row">
+		<span class="spinner" role="status" aria-label="Loading"></span>
+	</div>
+{/if}
+
+<style>
+	.sentinel {
+		height: 1px;
+	}
+
+	.loading-row {
+		display: flex;
+		justify-content: center;
+		align-items: center;
+		padding: 24px 0;
+	}
+
+	.spinner {
+		display: block;
+		width: 32px;
+		height: 32px;
+		border: 3px solid color-mix(in srgb, var(--color-accent) 25%, transparent);
+		border-top-color: var(--color-accent);
+		border-radius: 50%;
+		animation: spin 0.7s linear infinite;
+	}
+
+	@keyframes spin {
+		to {
+			transform: rotate(360deg);
+		}
+	}
+</style>

frontend/src/lib/components/file/BulkTagEditor.svelte

@@ -0,0 +1,436 @@
+<script lang="ts">
+	import { api } from '$lib/api/client';
+	import type { Tag } from '$lib/api/types';
+	import { fetchAllTags } from '$lib/api/tags';
+
+	interface Props {
+		fileIds: string[];
+		onDone: () => void;
+	}
+
+	let { fileIds, onDone }: Props = $props();
+
+	// Tags present on ALL selected files
+	let commonIds = $state(new Set<string>());
+	// Tags present on SOME but not all selected files
+	let partialIds = $state(new Set<string>());
+	// All available tags from /tags
+	let allTags = $state<Tag[]>([]);
+
+	let search = $state('');
+	let busy = $state(false);
+	let loading = $state(true);
+	let error = $state('');
+
+	$effect(() => {
+		load();
+	});
+
+	async function load() {
+		loading = true;
+		error = '';
+		try {
+			const [tagsRes, commonRes] = await Promise.all([
+				fetchAllTags(),
+				api.post<{ common_tag_ids: string[]; partial_tag_ids: string[] }>(
+					'/files/bulk/common-tags',
+					{ file_ids: fileIds }
+				)
+			]);
+			allTags = tagsRes;
+			commonIds = new Set(commonRes.common_tag_ids ?? []);
+			partialIds = new Set(commonRes.partial_tag_ids ?? []);
+		} catch {
+			error = 'Failed to load tags';
+		} finally {
+			loading = false;
+		}
+	}
+
+	// Assigned = common + partial (shown in assigned section)
+	let assignedIds = $derived(new Set([...commonIds, ...partialIds]));
+
+	let assignedTags = $derived(
+		allTags.filter(
+			(t) =>
+				assignedIds.has(t.id ?? '') &&
+				(!search.trim() || t.name?.toLowerCase().includes(search.toLowerCase()))
+		)
+	);
+
+	let availableTags = $derived(
+		allTags.filter(
+			(t) =>
+				!assignedIds.has(t.id ?? '') &&
+				(!search.trim() || t.name?.toLowerCase().includes(search.toLowerCase()))
+		)
+	);
+
+	function tagStyle(tag: Tag) {
+		const color = tag.color ?? tag.category_color;
+		return color ? `background-color: #${color}` : '';
+	}
+
+	// Refetch which tags are common/partial across the selection. Run after any
+	// bulk change so rule-applied tags (and partial→common shifts) show up — the
+	// server applies auto-tag rules, so we can't infer the result locally.
+	async function refreshCommon() {
+		const res = await api.post<{ common_tag_ids: string[]; partial_tag_ids: string[] }>(
+			'/files/bulk/common-tags',
+			{ file_ids: fileIds }
+		);
+		commonIds = new Set(res.common_tag_ids ?? []);
+		partialIds = new Set(res.partial_tag_ids ?? []);
+	}
+
+	async function add(tagId: string) {
+		if (busy) return;
+		busy = true;
+		try {
+			await api.post('/files/bulk/tags', { file_ids: fileIds, action: 'add', tag_ids: [tagId] });
+			await refreshCommon();
+		} finally {
+			busy = false;
+		}
+	}
+
+	// Clicking a partial tag promotes it to common (adds to all files that don't have it)
+	async function promotePartial(tagId: string) {
+		if (busy) return;
+		busy = true;
+		try {
+			await api.post('/files/bulk/tags', { file_ids: fileIds, action: 'add', tag_ids: [tagId] });
+			await refreshCommon();
+		} finally {
+			busy = false;
+		}
+	}
+
+	async function remove(tagId: string) {
+		if (busy) return;
+		busy = true;
+		try {
+			await api.post('/files/bulk/tags', { file_ids: fileIds, action: 'remove', tag_ids: [tagId] });
+			await refreshCommon();
+		} finally {
+			busy = false;
+		}
+	}
+
+	// ---- Keyboard navigation (from the search input) ----
+	// ↓/↑ highlight a suggestion, Enter adds it (focus stays); with the input empty
+	// ←/→ walk the assigned tags and Del removes the focused one from all files.
+	let highlightIdx = $state(0);
+	let assignedFocusIdx = $state(-1);
+
+	$effect(() => {
+		if (highlightIdx > availableTags.length - 1) {
+			highlightIdx = Math.max(0, availableTags.length - 1);
+		}
+	});
+
+	function onSearchKeydown(e: KeyboardEvent) {
+		if (e.key === 'ArrowDown') {
+			e.preventDefault();
+			assignedFocusIdx = -1;
+			if (availableTags.length) highlightIdx = Math.min(highlightIdx + 1, availableTags.length - 1);
+		} else if (e.key === 'ArrowUp') {
+			e.preventDefault();
+			assignedFocusIdx = -1;
+			highlightIdx = Math.max(highlightIdx - 1, 0);
+		} else if (e.key === 'Enter') {
+			const tag = availableTags[highlightIdx];
+			if (tag?.id) {
+				e.preventDefault();
+				void add(tag.id);
+			}
+		} else if (e.key === 'ArrowRight' && search === '') {
+			e.preventDefault();
+			const n = assignedTags.length;
+			if (n) assignedFocusIdx = assignedFocusIdx < 0 ? 0 : Math.min(assignedFocusIdx + 1, n - 1);
+		} else if (e.key === 'ArrowLeft' && search === '') {
+			e.preventDefault();
+			const n = assignedTags.length;
+			if (n) assignedFocusIdx = assignedFocusIdx < 0 ? n - 1 : Math.max(assignedFocusIdx - 1, 0);
+		} else if (e.key === 'Delete' && assignedFocusIdx >= 0) {
+			const tag = assignedTags[assignedFocusIdx];
+			if (tag?.id) {
+				e.preventDefault();
+				void remove(tag.id);
+				assignedFocusIdx = Math.min(assignedFocusIdx, assignedTags.length - 2);
+			}
+		} else if (e.key === 'Escape') {
+			// Staged exit: a non-empty filter clears first; once empty, Escape
+			// releases focus. Stop propagation so neither step reaches the page's
+			// window handler — only the *next* Escape (with focus already gone) does,
+			// and that one closes the popup.
+			e.preventDefault();
+			e.stopPropagation();
+			if (search) {
+				search = '';
+				assignedFocusIdx = -1;
+			} else {
+				assignedFocusIdx = -1;
+				(e.currentTarget as HTMLInputElement).blur();
+			}
+		}
+	}
+</script>
+
+<div class="editor" class:busy>
+	{#if loading}
+		<p class="status">Loading…</p>
+	{:else if error}
+		<p class="status err">{error}</p>
+	{:else}
+		<!-- Assigned tags -->
+		{#if assignedTags.length > 0}
+			<div class="section-label">
+				Assigned
+				<span class="hint">— partial tags shown with dashed border, click to apply to all</span>
+			</div>
+			<div class="tag-row">
+				{#each assignedTags as tag, i (tag.id)}
+					{@const isPartial = partialIds.has(tag.id ?? '')}
+					<div class="tag-wrap">
+						<button
+							class="tag assigned"
+							class:partial={isPartial}
+							class:kbfocus={assignedFocusIdx === i}
+							style={tagStyle(tag)}
+							onclick={() => (isPartial ? promotePartial(tag.id!) : remove(tag.id!))}
+							title={isPartial
+								? 'Partial — click to add to all files'
+								: 'Click to remove from all files'}
+						>
+							{tag.name}
+							{#if isPartial}
+								<span class="partial-icon" aria-label="partial">~</span>
+							{:else}
+								<span class="remove" aria-label="remove">×</span>
+							{/if}
+						</button>
+					</div>
+				{/each}
+			</div>
+		{/if}
+
+		<!-- Search -->
+		<div class="search-wrap">
+			<input
+				class="search"
+				type="search"
+				placeholder="Search tags…"
+				bind:value={search}
+				onkeydown={onSearchKeydown}
+				autocomplete="off"
+			/>
+			{#if search}
+				<button class="search-clear" onclick={() => (search = '')} aria-label="Clear search">
+					<svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+						<path
+							d="M2 2l10 10M12 2L2 12"
+							stroke="currentColor"
+							stroke-width="1.8"
+							stroke-linecap="round"
+						/>
+					</svg>
+				</button>
+			{/if}
+		</div>
+
+		<!-- Available tags -->
+		{#if availableTags.length > 0}
+			<div class="section-label">Add tag</div>
+			<div class="tag-row available-row">
+				{#each availableTags as tag, i (tag.id)}
+					<button
+						class="tag available"
+						class:hl={highlightIdx === i}
+						style={tagStyle(tag)}
+						onclick={() => add(tag.id!)}
+						title="Add to all selected files"
+					>
+						{tag.name}
+					</button>
+				{/each}
+			</div>
+		{:else if search.trim() && availableTags.length === 0 && assignedTags.length === 0}
+			<p class="empty">No matching tags</p>
+		{/if}
+	{/if}
+</div>
+
+<style>
+	.editor {
+		display: flex;
+		flex-direction: column;
+		gap: 8px;
+	}
+
+	.editor.busy {
+		opacity: 0.6;
+		pointer-events: none;
+	}
+
+	.status {
+		font-size: 0.85rem;
+		color: var(--color-text-muted);
+		margin: 0;
+		padding: 8px 0;
+	}
+
+	.status.err {
+		color: var(--color-danger);
+	}
+
+	.section-label {
+		font-size: 0.75rem;
+		color: var(--color-text-muted);
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+	}
+
+	.hint {
+		font-weight: 400;
+		text-transform: none;
+		letter-spacing: 0;
+		font-size: 0.72rem;
+	}
+
+	.tag-row {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 5px;
+	}
+
+	.available-row {
+		max-height: 140px;
+		overflow-y: auto;
+	}
+
+	.tag-wrap {
+		display: contents;
+	}
+
+	.tag {
+		display: inline-flex;
+		align-items: center;
+		gap: 4px;
+		height: 26px;
+		padding: 0 9px;
+		border-radius: 5px;
+		font-size: 0.8rem;
+		font-family: inherit;
+		cursor: pointer;
+		border: 2px solid transparent;
+		background-color: var(--color-tag-default);
+		color: rgba(255, 255, 255, 0.9);
+		user-select: none;
+	}
+
+	/* Common tag — solid, slightly faded ×, full opacity */
+	.tag.assigned {
+		opacity: 0.95;
+	}
+
+	.tag.assigned:hover {
+		filter: brightness(1.15);
+	}
+
+	/* Partial tag — dashed border, reduced opacity */
+	.tag.assigned.partial {
+		opacity: 0.65;
+		border-style: dashed;
+		border-color: rgba(255, 255, 255, 0.55);
+	}
+
+	.tag.assigned.partial:hover {
+		opacity: 1;
+		filter: brightness(1.1);
+	}
+
+	.remove {
+		font-size: 1rem;
+		line-height: 1;
+		opacity: 0.7;
+	}
+
+	.partial-icon {
+		font-size: 0.9rem;
+		line-height: 1;
+		opacity: 0.85;
+	}
+
+	.tag.available {
+		opacity: 0.7;
+	}
+
+	.tag.available:hover {
+		opacity: 1;
+		filter: brightness(1.1);
+	}
+
+	.tag.available.hl {
+		opacity: 1;
+		outline: 2px solid var(--color-accent);
+		outline-offset: 1px;
+	}
+
+	.tag.assigned.kbfocus {
+		outline: 2px solid var(--color-danger);
+		outline-offset: 1px;
+	}
+
+	.search-wrap {
+		position: relative;
+		display: flex;
+		align-items: center;
+	}
+
+	.search {
+		width: 100%;
+		box-sizing: border-box;
+		height: 32px;
+		padding: 0 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-primary);
+		color: var(--color-text-primary);
+		font-size: 0.85rem;
+		font-family: inherit;
+		outline: none;
+	}
+
+	.search:focus {
+		border-color: var(--color-accent);
+	}
+
+	.search-clear {
+		position: absolute;
+		right: 6px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		border: none;
+		background: none;
+		color: var(--color-text-muted);
+		cursor: pointer;
+		padding: 0;
+	}
+
+	.search-clear:hover {
+		color: var(--color-text-primary);
+		background-color: color-mix(in srgb, var(--color-accent) 20%, transparent);
+	}
+
+	.empty {
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+		margin: 0;
+	}
+</style>

frontend/src/lib/components/file/FileCard.svelte

@@ -0,0 +1,247 @@
+<script lang="ts">
+	import { get } from 'svelte/store';
+	import { authStore } from '$lib/stores/auth';
+	import type { File } from '$lib/api/types';
+
+	const LONG_PRESS_MS = 400;
+	const DRAG_THRESHOLD = 8; // px — cancel long-press if pointer moves more than this
+
+	interface Props {
+		file: File;
+		index: number;
+		selected?: boolean;
+		selectionMode?: boolean;
+		/** Roving keyboard-focus ring (shown only during keyboard navigation). */
+		focused?: boolean;
+		onTap?: (e: MouseEvent) => void;
+		/** Called when long-press fires; receives the pointerType of the gesture. */
+		onLongPress?: (pointerType: string) => void;
+	}
+
+	let {
+		file,
+		index,
+		selected = false,
+		selectionMode = false,
+		focused = false,
+		onTap,
+		onLongPress
+	}: Props = $props();
+
+	let imgSrc = $state<string | null>(null);
+	let failed = $state(false);
+
+	$effect(() => {
+		const token = get(authStore).accessToken;
+		let objectUrl: string | null = null;
+		let cancelled = false;
+
+		fetch(`/api/v1/files/${file.id}/thumbnail`, {
+			headers: token ? { Authorization: `Bearer ${token}` } : {}
+		})
+			.then((res) => (res.ok ? res.blob() : null))
+			.then((blob) => {
+				if (cancelled || !blob) {
+					if (!cancelled) failed = true;
+					return;
+				}
+				objectUrl = URL.createObjectURL(blob);
+				imgSrc = objectUrl;
+			})
+			.catch(() => {
+				if (!cancelled) failed = true;
+			});
+
+		return () => {
+			cancelled = true;
+			if (objectUrl) URL.revokeObjectURL(objectUrl);
+		};
+	});
+
+	// --- Long press + drag detection ---
+	let pressTimer: ReturnType<typeof setTimeout> | null = null;
+	let didLongPress = false;
+	let pressStartX = 0;
+	let pressStartY = 0;
+	let currentPointerType = '';
+
+	function onPointerDown(e: PointerEvent) {
+		if (e.button !== 0 && e.pointerType === 'mouse') return;
+		didLongPress = false;
+		pressStartX = e.clientX;
+		pressStartY = e.clientY;
+		currentPointerType = e.pointerType;
+		pressTimer = setTimeout(() => {
+			didLongPress = true;
+			onLongPress?.(currentPointerType);
+		}, LONG_PRESS_MS);
+	}
+
+	function onPointerMoveInternal(e: PointerEvent) {
+		// Cancel long-press if pointer has moved significantly (user is scrolling)
+		if (pressTimer !== null) {
+			const dx = e.clientX - pressStartX;
+			const dy = e.clientY - pressStartY;
+			if (Math.hypot(dx, dy) > DRAG_THRESHOLD) {
+				clearTimeout(pressTimer);
+				pressTimer = null;
+			}
+		}
+	}
+
+	function cancelPress() {
+		if (pressTimer !== null) {
+			clearTimeout(pressTimer);
+			pressTimer = null;
+		}
+	}
+
+	function onClick(e: MouseEvent) {
+		if (didLongPress) {
+			didLongPress = false;
+			return;
+		}
+		cancelPress();
+		onTap?.(e);
+	}
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
+<div
+	class="card"
+	class:loaded={!!imgSrc}
+	class:selected
+	class:focused
+	data-file-index={index}
+	onpointerdown={onPointerDown}
+	onpointermove={onPointerMoveInternal}
+	onpointerup={() => {
+		cancelPress();
+		didLongPress = false;
+	}}
+	onpointerleave={cancelPress}
+	oncontextmenu={(e) => e.preventDefault()}
+	onclick={onClick}
+	title={file.original_name ?? undefined}
+>
+	{#if imgSrc}
+		<img src={imgSrc} alt={file.original_name ?? ''} class="thumb" draggable="false" />
+	{:else if failed}
+		<div class="placeholder failed" aria-label="Failed to load"></div>
+	{:else}
+		<div class="placeholder loading" aria-label="Loading"></div>
+	{/if}
+	<div class="overlay"></div>
+	{#if selected}
+		<div class="check" aria-hidden="true">
+			<svg width="18" height="18" viewBox="0 0 18 18" fill="none">
+				<circle cx="9" cy="9" r="8.5" fill="rgba(0,0,0,0.55)" stroke="white" stroke-width="1" />
+				<path
+					d="M5 9l3 3 5-5"
+					stroke="white"
+					stroke-width="1.8"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+				/>
+			</svg>
+		</div>
+	{:else if selectionMode}
+		<div class="check" aria-hidden="true">
+			<svg width="18" height="18" viewBox="0 0 18 18" fill="none">
+				<circle
+					cx="9"
+					cy="9"
+					r="8.5"
+					fill="rgba(0,0,0,0.35)"
+					stroke="rgba(255,255,255,0.5)"
+					stroke-width="1"
+				/>
+			</svg>
+		</div>
+	{/if}
+</div>
+
+<style>
+	.card {
+		position: relative;
+		width: 160px;
+		height: 160px;
+		max-width: calc(33vw - 7px);
+		max-height: calc(33vw - 7px);
+		overflow: hidden;
+		cursor: pointer;
+		background-color: var(--color-bg-elevated);
+		flex-shrink: 0;
+		user-select: none;
+		-webkit-user-select: none;
+		/* Keyboard scrollIntoView leaves room for the sticky header above and the
+		   fixed bottom navbar below, so the focused card never hides under them. */
+		scroll-margin-top: 52px;
+		scroll-margin-bottom: calc(72px + env(safe-area-inset-bottom, 0px));
+	}
+
+	.thumb {
+		width: 100%;
+		height: 100%;
+		object-fit: contain;
+		object-position: center;
+		display: block;
+	}
+
+	.placeholder {
+		width: 100%;
+		height: 100%;
+	}
+
+	.placeholder.loading {
+		background: linear-gradient(
+			90deg,
+			var(--color-bg-elevated) 25%,
+			color-mix(in srgb, var(--color-accent) 12%, var(--color-bg-elevated)) 50%,
+			var(--color-bg-elevated) 75%
+		);
+		background-size: 200% 100%;
+		animation: shimmer 1.4s infinite;
+	}
+
+	.placeholder.failed {
+		background-color: color-mix(in srgb, var(--color-danger) 15%, var(--color-bg-elevated));
+	}
+
+	.overlay {
+		position: absolute;
+		inset: 0;
+		background-color: rgba(0, 0, 0, 0.1);
+		transition: background-color 0.15s;
+	}
+
+	.card:hover .overlay {
+		background-color: rgba(0, 0, 0, 0.3);
+	}
+
+	.card.selected .overlay {
+		background-color: color-mix(in srgb, var(--color-accent) 35%, transparent);
+	}
+
+	.card.focused {
+		outline: 3px solid var(--color-accent);
+		outline-offset: -3px;
+		z-index: 1;
+	}
+
+	.check {
+		position: absolute;
+		top: 6px;
+		right: 6px;
+		pointer-events: none;
+	}
+
+	@keyframes shimmer {
+		0% {
+			background-position: 200% 0;
+		}
+		100% {
+			background-position: -200% 0;
+		}
+	}
+</style>

frontend/src/lib/components/file/FileUpload.svelte

@@ -0,0 +1,376 @@
+<script lang="ts">
+	import { uploadWithProgress, ApiError } from '$lib/api/client';
+	import type { File as ApiFile } from '$lib/api/types';
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		onUploaded: (file: ApiFile) => void;
+		children: Snippet;
+	}
+
+	let { onUploaded, children }: Props = $props();
+
+	// ---- Upload queue ----
+	type UploadStatus = 'uploading' | 'done' | 'error';
+
+	interface QueueItem {
+		id: string;
+		name: string;
+		progress: number;
+		status: UploadStatus;
+		error?: string;
+	}
+
+	let queue = $state<QueueItem[]>([]);
+	let fileInput = $state<HTMLInputElement | undefined>();
+
+	let allSettled = $derived(queue.length > 0 && queue.every((i) => i.status !== 'uploading'));
+
+	// ---- File input ----
+	export function open() {
+		fileInput?.click();
+	}
+
+	function onInputChange(e: Event) {
+		const files = (e.currentTarget as HTMLInputElement).files;
+		if (files?.length) {
+			void enqueue(Array.from(files));
+			// Reset so the same file can be re-selected
+			(e.currentTarget as HTMLInputElement).value = '';
+		}
+	}
+
+	// ---- Upload logic ----
+	function uid() {
+		return `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+	}
+
+	async function enqueue(files: globalThis.File[]) {
+		const items: QueueItem[] = files.map((f) => ({
+			id: uid(),
+			name: f.name,
+			progress: 0,
+			status: 'uploading'
+		}));
+		queue = [...queue, ...items];
+
+		await Promise.all(files.map((file, i) => uploadOne(file, items[i].id)));
+	}
+
+	async function uploadOne(file: globalThis.File, itemId: string) {
+		const fd = new FormData();
+		fd.append('file', file);
+
+		try {
+			const result = await uploadWithProgress<ApiFile>('/files', fd, (pct) =>
+				updateItem(itemId, { progress: pct })
+			);
+			updateItem(itemId, { status: 'done', progress: 100 });
+			onUploaded(result);
+		} catch (e) {
+			const msg =
+				e instanceof ApiError
+					? e.status === 415
+						? `Unsupported file type`
+						: e.message
+					: 'Upload failed';
+			updateItem(itemId, { status: 'error', error: msg });
+		}
+	}
+
+	function updateItem(id: string, patch: Partial<QueueItem>) {
+		queue = queue.map((item) => (item.id === id ? { ...item, ...patch } : item));
+	}
+
+	function clearQueue() {
+		queue = [];
+	}
+
+	// ---- Drag and drop ----
+	let dragCounter = $state(0);
+	let dragOver = $derived(dragCounter > 0);
+
+	function onDragEnter(e: DragEvent) {
+		if (!e.dataTransfer?.types.includes('Files')) return;
+		e.preventDefault();
+		dragCounter++;
+	}
+
+	function onDragLeave() {
+		dragCounter = Math.max(0, dragCounter - 1);
+	}
+
+	function onDragOver(e: DragEvent) {
+		if (!e.dataTransfer?.types.includes('Files')) return;
+		e.preventDefault();
+		e.dataTransfer.dropEffect = 'copy';
+	}
+
+	function onDrop(e: DragEvent) {
+		e.preventDefault();
+		dragCounter = 0;
+		const files = Array.from(e.dataTransfer?.files ?? []);
+		if (files.length) void enqueue(files);
+	}
+</script>
+
+<!-- Hidden file input -->
+<input
+	bind:this={fileInput}
+	type="file"
+	multiple
+	accept="image/*,video/*"
+	style="display:none"
+	onchange={onInputChange}
+/>
+
+<!-- Drop zone wrapper -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div
+	class="drop-zone"
+	class:drag-over={dragOver}
+	ondragenter={onDragEnter}
+	ondragleave={onDragLeave}
+	ondragover={onDragOver}
+	ondrop={onDrop}
+>
+	{@render children()}
+
+	{#if dragOver}
+		<div class="drop-overlay" aria-hidden="true">
+			<div class="drop-label">
+				<svg width="36" height="36" viewBox="0 0 36 36" fill="none" aria-hidden="true">
+					<path
+						d="M18 4v20M10 14l8-10 8 10"
+						stroke="currentColor"
+						stroke-width="2.5"
+						stroke-linecap="round"
+						stroke-linejoin="round"
+					/>
+					<path d="M6 28h24" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" />
+				</svg>
+				Drop files to upload
+			</div>
+		</div>
+	{/if}
+</div>
+
+<!-- Upload progress panel -->
+{#if queue.length > 0}
+	<div class="upload-panel" role="status">
+		<div class="panel-header">
+			<span class="panel-title">
+				{#if allSettled}
+					Uploads complete
+				{:else}
+					Uploading {queue.filter((i) => i.status === 'uploading').length} file(s)…
+				{/if}
+			</span>
+			{#if allSettled}
+				<button class="clear-btn" onclick={clearQueue}>Dismiss</button>
+			{/if}
+		</div>
+
+		<ul class="upload-list">
+			{#each queue as item (item.id)}
+				<li
+					class="upload-item"
+					class:done={item.status === 'done'}
+					class:error={item.status === 'error'}
+				>
+					<span class="item-name" title={item.name}>{item.name}</span>
+					<div class="item-right">
+						{#if item.status === 'uploading'}
+							<div class="progress-track">
+								<div class="progress-fill" style="width: {item.progress}%"></div>
+							</div>
+							<span class="pct">{item.progress}%</span>
+						{:else if item.status === 'done'}
+							<svg
+								class="icon-ok"
+								width="16"
+								height="16"
+								viewBox="0 0 16 16"
+								fill="none"
+								aria-label="Done"
+							>
+								<path
+									d="M3 8l4 4 6-6"
+									stroke="currentColor"
+									stroke-width="2"
+									stroke-linecap="round"
+									stroke-linejoin="round"
+								/>
+							</svg>
+						{:else}
+							<span class="err-msg" title={item.error}>{item.error}</span>
+						{/if}
+					</div>
+				</li>
+			{/each}
+		</ul>
+	</div>
+{/if}
+
+<style>
+	/* ---- Drop zone ---- */
+	.drop-zone {
+		position: relative;
+		flex: 1;
+		display: flex;
+		flex-direction: column;
+		min-height: 0;
+	}
+
+	.drop-overlay {
+		position: absolute;
+		inset: 0;
+		z-index: 50;
+		background-color: color-mix(in srgb, var(--color-accent) 18%, rgba(0, 0, 0, 0.7));
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		border: 2px dashed var(--color-accent);
+		border-radius: 4px;
+		pointer-events: none;
+	}
+
+	.drop-label {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: 10px;
+		color: #fff;
+		font-size: 1.1rem;
+		font-weight: 600;
+	}
+
+	/* ---- Upload panel ---- */
+	.upload-panel {
+		position: fixed;
+		left: 10px;
+		right: 10px;
+		bottom: 65px;
+		z-index: 110;
+		background-color: var(--color-bg-secondary);
+		border-radius: 10px;
+		box-shadow: 0 0 16px rgba(0, 0, 0, 0.6);
+		padding: 10px 12px;
+		animation: slide-up 0.18s ease-out;
+		max-height: 50vh;
+		overflow-y: auto;
+	}
+
+	@keyframes slide-up {
+		from {
+			transform: translateY(10px);
+			opacity: 0;
+		}
+		to {
+			transform: translateY(0);
+			opacity: 1;
+		}
+	}
+
+	.panel-header {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		margin-bottom: 8px;
+	}
+
+	.panel-title {
+		font-size: 0.85rem;
+		font-weight: 600;
+		color: var(--color-text-muted);
+	}
+
+	.clear-btn {
+		background: none;
+		border: none;
+		color: var(--color-accent);
+		font-size: 0.82rem;
+		font-family: inherit;
+		cursor: pointer;
+		padding: 2px 6px;
+	}
+
+	.clear-btn:hover {
+		text-decoration: underline;
+	}
+
+	.upload-list {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 6px;
+	}
+
+	.upload-item {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		min-height: 28px;
+	}
+
+	.item-name {
+		flex: 1;
+		font-size: 0.82rem;
+		color: var(--color-text-primary);
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.upload-item.done .item-name {
+		color: var(--color-text-muted);
+	}
+
+	.upload-item.error .item-name {
+		color: var(--color-text-muted);
+	}
+
+	.item-right {
+		display: flex;
+		align-items: center;
+		gap: 6px;
+		flex-shrink: 0;
+	}
+
+	.progress-track {
+		width: 80px;
+		height: 4px;
+		background-color: color-mix(in srgb, var(--color-accent) 20%, var(--color-bg-elevated));
+		border-radius: 2px;
+		overflow: hidden;
+	}
+
+	.progress-fill {
+		height: 100%;
+		background-color: var(--color-accent);
+		border-radius: 2px;
+		transition: width 0.1s linear;
+	}
+
+	.pct {
+		font-size: 0.75rem;
+		color: var(--color-text-muted);
+		min-width: 30px;
+		text-align: right;
+	}
+
+	.icon-ok {
+		color: var(--color-accent);
+	}
+
+	.err-msg {
+		font-size: 0.75rem;
+		color: var(--color-danger);
+		max-width: 140px;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+</style>

frontend/src/lib/components/file/FileViewer.svelte

@@ -0,0 +1,792 @@
+<script lang="ts">
+	import { get } from 'svelte/store';
+	import { untrack, onDestroy } from 'svelte';
+	import { api, ApiError } from '$lib/api/client';
+	import { authStore } from '$lib/stores/auth';
+	import TagPicker from '$lib/components/file/TagPicker.svelte';
+	import PoolPicker from '$lib/components/file/PoolPicker.svelte';
+	import type { File, Tag } from '$lib/api/types';
+
+	interface Props {
+		/** File currently shown. Changing it (paging) reloads in place. */
+		fileId: string;
+		/** Neighbour ids resolved by the parent; null hides the arrow. */
+		prevId?: string | null;
+		nextId?: string | null;
+		/** Page to a neighbour. */
+		onNavigate: (id: string) => void;
+		/** Close the viewer. */
+		onClose: () => void;
+	}
+
+	let { fileId, prevId = null, nextId = null, onNavigate, onClose }: Props = $props();
+
+	let file = $state<File | null>(null);
+	let fileTags = $state<Tag[]>([]);
+	let previewSrc = $state<string | null>(null);
+	let loading = $state(true);
+	let saving = $state(false);
+	let error = $state('');
+	let poolPickerOpen = $state(false);
+
+	// Tags are loaded lazily — the Tags section sits below a full-viewport
+	// preview, so fetching them on open just hammers the DB for data the user
+	// usually never scrolls to. We fetch only once the section comes into view.
+	let tagsVisible = $state(false);
+	let tagsLoading = $state(false);
+	let tagsLoadedFor = $state<string | null>(null);
+	let tagsLoaded = $derived(tagsLoadedFor === fileId);
+
+	// Editable fields (initialised on load)
+	let notes = $state('');
+	let contentDatetime = $state('');
+	let isPublic = $state(false);
+	let dirty = $state(false);
+
+	let exifEntries = $derived(
+		file?.exif ? Object.entries(file.exif as Record<string, unknown>) : []
+	);
+
+	// ---- Load (re-runs whenever the file changes, i.e. paging) ----
+	$effect(() => {
+		if (!fileId) return;
+		const id = fileId; // snapshot — don't re-run if other state changes
+		// Revoke old blob URL without tracking previewSrc as a dependency.
+		untrack(() => {
+			if (previewSrc) URL.revokeObjectURL(previewSrc);
+			previewSrc = null;
+		});
+		void loadFile(id);
+	});
+
+	onDestroy(() => {
+		if (previewSrc) URL.revokeObjectURL(previewSrc);
+	});
+
+	async function loadFile(id: string) {
+		loading = true;
+		error = '';
+		// Drop the previous file's tags; they reload lazily when scrolled to.
+		fileTags = [];
+		try {
+			const fileData = await api.get<File>(`/files/${id}`);
+			if (fileId !== id) return; // paged on; ignore
+			file = fileData;
+			notes = fileData.notes ?? '';
+			contentDatetime = fileData.content_datetime
+				? fileData.content_datetime.slice(0, 16) // YYYY-MM-DDTHH:mm
+				: '';
+			isPublic = fileData.is_public ?? false;
+			dirty = false;
+			void fetchPreview(id);
+			// Log the view (activity.file_views). Fire-and-forget — never block or
+			// fail the viewer over view tracking.
+			void api.post(`/files/${id}/views`).catch(() => {});
+		} catch (e) {
+			error = e instanceof ApiError ? e.message : 'Failed to load file';
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function fetchPreview(id: string) {
+		const token = get(authStore).accessToken;
+		try {
+			const res = await fetch(`/api/v1/files/${id}/preview`, {
+				headers: token ? { Authorization: `Bearer ${token}` } : {}
+			});
+			if (res.ok && fileId === id) {
+				previewSrc = URL.createObjectURL(await res.blob());
+			}
+		} catch {
+			// non-critical — thumbnail stays as fallback
+		}
+	}
+
+	// Direct link to the full-resolution original, opened in a new tab. A
+	// navigation can't send the auth header, so the token rides in the query —
+	// the server accepts ?access_token= for GET media. Reactive on the token so a
+	// silent refresh keeps the link valid.
+	let originalUrl = $derived(
+		fileId
+			? `/api/v1/files/${fileId}/content?inline=1&access_token=${encodeURIComponent($authStore.accessToken ?? '')}`
+			: '#'
+	);
+
+	// ---- Tags (lazy) ----
+	// Fetch the current file's tags the first time the Tags section is visible.
+	// Re-runs when fileId changes while the section is still on-screen.
+	$effect(() => {
+		const id = fileId;
+		if (id && tagsVisible && tagsLoadedFor !== id && !tagsLoading) {
+			void loadTags(id);
+		}
+	});
+
+	async function loadTags(id: string) {
+		tagsLoading = true;
+		try {
+			const tags = await api.get<Tag[]>(`/files/${id}/tags`);
+			if (fileId !== id) return; // paged on; ignore
+			fileTags = tags;
+			tagsLoadedFor = id;
+		} catch {
+			// non-critical — a later scroll into view retries
+		} finally {
+			tagsLoading = false;
+		}
+	}
+
+	// Svelte action: flips tagsVisible while the Tags section is in (or near) the
+	// viewport. rootMargin pre-loads just before it scrolls fully into view.
+	function tagsSentinel(node: HTMLElement) {
+		const observer = new IntersectionObserver(
+			(entries) => {
+				tagsVisible = entries[0]?.isIntersecting ?? false;
+			},
+			{ rootMargin: '200px' }
+		);
+		observer.observe(node);
+		return {
+			destroy() {
+				observer.disconnect();
+			}
+		};
+	}
+
+	async function addTag(tagId: string) {
+		const updated = await api.put<Tag[]>(`/files/${fileId}/tags/${tagId}`);
+		fileTags = updated;
+		tagsLoadedFor = fileId;
+	}
+
+	async function removeTag(tagId: string) {
+		await api.delete(`/files/${fileId}/tags/${tagId}`);
+		fileTags = fileTags.filter((t) => t.id !== tagId);
+	}
+
+	// ---- Save ----
+	async function save() {
+		if (!file || saving) return;
+		saving = true;
+		error = '';
+		try {
+			const updated = await api.patch<File>(`/files/${file.id}`, {
+				notes: notes.trim() || null,
+				content_datetime: contentDatetime ? new Date(contentDatetime).toISOString() : undefined,
+				is_public: isPublic
+			});
+			file = updated;
+			dirty = false;
+		} catch (e) {
+			error = e instanceof ApiError ? e.message : 'Failed to save';
+		} finally {
+			saving = false;
+		}
+	}
+
+	// ---- Keyboard ----
+	let viewerPage = $state<HTMLElement>();
+	let tagsSection = $state<HTMLElement>();
+	let pendingTagFocus = false;
+
+	// Bring the preview back to the top of the scroll container (the overlay, or
+	// the page in the standalone route). scrollIntoView resolves the right
+	// scroller in either case. Called when Escape leaves the tag filter.
+	function revealPreview() {
+		viewerPage?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+	}
+
+	function handleKeydown(e: KeyboardEvent) {
+		// While the pool picker is open it owns the keyboard: Escape closes it
+		// (even from its search field), and every other key is swallowed so the
+		// viewer's shortcuts don't fire behind the modal. Typing still works —
+		// non-Escape keys aren't prevented, only ignored here.
+		if (poolPickerOpen) {
+			if (e.key === 'Escape') {
+				e.preventDefault();
+				poolPickerOpen = false;
+			}
+			return;
+		}
+		if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return;
+		if (e.ctrlKey || e.metaKey || e.altKey) return;
+		// Letter keys are matched by physical position (e.code) so j/k/e work on any
+		// keyboard layout; arrows and Escape are layout-independent already.
+		if (e.key === 'ArrowLeft' || e.code === 'KeyK') {
+			if (prevId) onNavigate(prevId);
+		} else if (e.key === 'ArrowRight' || e.code === 'KeyJ') {
+			if (nextId) onNavigate(nextId);
+		} else if (e.code === 'KeyE') {
+			e.preventDefault();
+			jumpToTags();
+		} else if (e.key === 'Escape') {
+			onClose();
+		}
+	}
+
+	// Scroll the (lazily loaded) Tags section into view and drop the cursor into
+	// its filter. Forces the load so the focus lands even before the user reaches
+	// the section by scrolling.
+	function jumpToTags() {
+		tagsVisible = true;
+		tagsSection?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+		pendingTagFocus = true;
+		focusTagInput();
+	}
+
+	function focusTagInput() {
+		requestAnimationFrame(() => tagsSection?.querySelector<HTMLInputElement>('input')?.focus());
+	}
+
+	$effect(() => {
+		if (tagsLoaded && pendingTagFocus) {
+			pendingTagFocus = false;
+			focusTagInput();
+		}
+	});
+
+	// ---- Helpers ----
+	function formatDatetime(iso: string | null | undefined): string {
+		if (!iso) return '—';
+		return new Date(iso).toLocaleString();
+	}
+
+	// EXIF values may be nested arrays/objects (e.g. rationals, GPS); render those
+	// as JSON instead of the useless "[object Object]".
+	function formatExifValue(val: unknown): string {
+		if (val === null || val === undefined) return '—';
+		if (typeof val === 'object') return JSON.stringify(val);
+		return String(val);
+	}
+</script>
+
+<svelte:window onkeydown={handleKeydown} />
+
+<div class="viewer-page" bind:this={viewerPage}>
+	<!-- Top bar -->
+	<div class="top-bar">
+		<button class="back-btn" onclick={onClose} aria-label="Back to files">
+			<svg width="20" height="20" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+				<path
+					d="M12 4L6 10L12 16"
+					stroke="currentColor"
+					stroke-width="2"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+				/>
+			</svg>
+		</button>
+		<span class="filename">{file?.original_name ?? ''}</span>
+		{#if file}
+			<button
+				class="pool-btn"
+				onclick={() => (poolPickerOpen = true)}
+				aria-label="Add to pool"
+				title="Add to pool"
+			>
+				<svg width="20" height="20" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+					<rect
+						x="3"
+						y="5"
+						width="14"
+						height="11"
+						rx="2"
+						stroke="currentColor"
+						stroke-width="1.6"
+					/>
+					<path
+						d="M10 8.5v4M8 10.5h4"
+						stroke="currentColor"
+						stroke-width="1.6"
+						stroke-linecap="round"
+					/>
+				</svg>
+			</button>
+		{/if}
+	</div>
+
+	<!-- Preview -->
+	<div class="preview-wrap">
+		{#if previewSrc}
+			<a
+				class="preview-link"
+				href={originalUrl}
+				target="_blank"
+				rel="noopener"
+				title="Open original in a new tab"
+			>
+				<img src={previewSrc} alt={file?.original_name ?? ''} class="preview-img" />
+			</a>
+		{:else if loading}
+			<div class="preview-placeholder shimmer"></div>
+		{:else}
+			<div class="preview-placeholder failed"></div>
+		{/if}
+
+		<!-- Prev / Next -->
+		{#if prevId}
+			<button
+				class="nav-btn nav-prev"
+				onclick={() => prevId && onNavigate(prevId)}
+				aria-label="Previous file"
+			>
+				<svg width="18" height="18" viewBox="0 0 18 18" fill="none" aria-hidden="true">
+					<path
+						d="M11 3L5 9L11 15"
+						stroke="currentColor"
+						stroke-width="2"
+						stroke-linecap="round"
+						stroke-linejoin="round"
+					/>
+				</svg>
+			</button>
+		{/if}
+		{#if nextId}
+			<button
+				class="nav-btn nav-next"
+				onclick={() => nextId && onNavigate(nextId)}
+				aria-label="Next file"
+			>
+				<svg width="18" height="18" viewBox="0 0 18 18" fill="none" aria-hidden="true">
+					<path
+						d="M7 3L13 9L7 15"
+						stroke="currentColor"
+						stroke-width="2"
+						stroke-linecap="round"
+						stroke-linejoin="round"
+					/>
+				</svg>
+			</button>
+		{/if}
+	</div>
+
+	<!-- Metadata panel -->
+	<div class="meta-panel">
+		{#if error}
+			<p class="error" role="alert">{error}</p>
+		{/if}
+
+		{#if file}
+			<!-- File info -->
+			<div class="info-row">
+				<span class="mime">{file.mime_type}</span>
+				<span class="sep">·</span>
+				<span class="created">Added {formatDatetime(file.created_at)}</span>
+			</div>
+
+			<!-- Edit form -->
+			<section class="section">
+				<label class="field-label" for="notes">Notes</label>
+				<textarea
+					id="notes"
+					class="textarea"
+					rows="3"
+					bind:value={notes}
+					oninput={() => (dirty = true)}
+					placeholder="Add notes…"
+				></textarea>
+			</section>
+
+			<section class="section">
+				<label class="field-label" for="datetime">Date taken</label>
+				<input
+					id="datetime"
+					type="datetime-local"
+					class="input"
+					bind:value={contentDatetime}
+					oninput={() => (dirty = true)}
+				/>
+			</section>
+
+			<section class="section toggle-row">
+				<span class="field-label">Public</span>
+				<button
+					class="toggle"
+					class:on={isPublic}
+					onclick={() => {
+						isPublic = !isPublic;
+						dirty = true;
+					}}
+					role="switch"
+					aria-checked={isPublic}
+					aria-label="Public"
+				>
+					<span class="thumb"></span>
+				</button>
+			</section>
+
+			<button class="save-btn" onclick={save} disabled={!dirty || saving}>
+				{saving ? 'Saving…' : 'Save changes'}
+			</button>
+
+			<!-- Tags (loaded lazily on scroll) -->
+			<section class="section" use:tagsSentinel bind:this={tagsSection}>
+				<div class="field-label">Tags</div>
+				{#if tagsLoaded}
+					<TagPicker {fileTags} onAdd={addTag} onRemove={removeTag} onExit={revealPreview} />
+				{:else}
+					<p class="tags-loading">Loading tags…</p>
+				{/if}
+			</section>
+
+			<!-- EXIF -->
+			{#if exifEntries.length > 0}
+				<section class="section">
+					<div class="field-label">EXIF</div>
+					<dl class="exif">
+						{#each exifEntries as [key, val]}
+							<dt>{key}</dt>
+							<dd>{formatExifValue(val)}</dd>
+						{/each}
+					</dl>
+				</section>
+			{/if}
+		{:else if !loading}
+			<p class="empty">File not found.</p>
+		{/if}
+	</div>
+</div>
+
+{#if poolPickerOpen && file}
+	<PoolPicker fileIds={[file.id!]} onClose={() => (poolPickerOpen = false)} />
+{/if}
+
+<style>
+	.viewer-page {
+		display: flex;
+		flex-direction: column;
+		min-height: 0;
+		padding-bottom: 70px; /* clear the bottom navbar in the standalone route */
+	}
+
+	/* ---- Top bar ---- */
+	.top-bar {
+		position: sticky;
+		top: 0;
+		z-index: 20;
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		padding: 6px 10px;
+		background-color: var(--color-bg-primary);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 15%, transparent);
+		min-height: 44px;
+	}
+
+	.back-btn {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 36px;
+		height: 36px;
+		border-radius: 8px;
+		border: none;
+		background: none;
+		color: var(--color-text-primary);
+		cursor: pointer;
+		flex-shrink: 0;
+	}
+
+	.back-btn:hover {
+		background-color: color-mix(in srgb, var(--color-accent) 15%, transparent);
+	}
+
+	.filename {
+		font-size: 0.9rem;
+		color: var(--color-text-muted);
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.pool-btn {
+		margin-left: auto;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 36px;
+		height: 36px;
+		border-radius: 8px;
+		border: none;
+		background: none;
+		color: var(--color-text-primary);
+		cursor: pointer;
+		flex-shrink: 0;
+	}
+
+	.pool-btn:hover {
+		background-color: color-mix(in srgb, var(--color-accent) 15%, transparent);
+	}
+
+	/* ---- Preview ---- */
+	.preview-wrap {
+		position: relative;
+		background-color: #000;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		/* Fill viewport below the top bar (44px) */
+		height: calc(100dvh - 44px);
+		flex-shrink: 0;
+		overflow: hidden;
+	}
+
+	/* Whole preview area is a link: click opens the original in a new tab. */
+	.preview-link {
+		width: 100%;
+		height: 100%;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		cursor: zoom-in;
+		text-decoration: none;
+	}
+
+	.preview-img {
+		max-width: 100%;
+		max-height: 100%;
+		object-fit: contain;
+		display: block;
+	}
+
+	.preview-placeholder {
+		width: 100%;
+		height: 100%;
+	}
+
+	.preview-placeholder.shimmer {
+		background: linear-gradient(90deg, #111 25%, #222 50%, #111 75%);
+		background-size: 200% 100%;
+		animation: shimmer 1.4s infinite;
+	}
+
+	.preview-placeholder.failed {
+		background-color: #1a1010;
+	}
+
+	/* ---- Nav buttons ---- */
+	.nav-btn {
+		position: absolute;
+		top: 50%;
+		transform: translateY(-50%);
+		width: 40px;
+		height: 40px;
+		border-radius: 50%;
+		border: none;
+		background-color: rgba(0, 0, 0, 0.55);
+		color: #fff;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		cursor: pointer;
+		transition: background-color 0.15s;
+	}
+
+	.nav-btn:hover {
+		background-color: rgba(0, 0, 0, 0.8);
+	}
+
+	.nav-prev {
+		left: 10px;
+	}
+	.nav-next {
+		right: 10px;
+	}
+
+	/* ---- Metadata panel ---- */
+	.meta-panel {
+		padding: 14px 14px 0;
+		display: flex;
+		flex-direction: column;
+		gap: 2px;
+	}
+
+	.info-row {
+		display: flex;
+		align-items: center;
+		gap: 6px;
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+		padding-bottom: 10px;
+	}
+
+	.sep {
+		opacity: 0.4;
+	}
+
+	.section {
+		padding: 10px 0;
+		border-top: 1px solid color-mix(in srgb, var(--color-accent) 12%, transparent);
+	}
+
+	.field-label {
+		font-size: 0.75rem;
+		font-weight: 600;
+		color: var(--color-text-muted);
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		margin-bottom: 6px;
+	}
+
+	.textarea {
+		width: 100%;
+		box-sizing: border-box;
+		padding: 8px 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.875rem;
+		font-family: inherit;
+		resize: vertical;
+		outline: none;
+		min-height: 70px;
+	}
+
+	.textarea:focus {
+		border-color: var(--color-accent);
+	}
+
+	.input {
+		width: 100%;
+		box-sizing: border-box;
+		height: 36px;
+		padding: 0 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.875rem;
+		font-family: inherit;
+		outline: none;
+		color-scheme: dark;
+	}
+
+	.input:focus {
+		border-color: var(--color-accent);
+	}
+
+	/* ---- Toggle ---- */
+	.toggle-row {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		padding-top: 12px;
+		padding-bottom: 12px;
+	}
+
+	.toggle-row .field-label {
+		margin-bottom: 0;
+	}
+
+	.toggle {
+		position: relative;
+		width: 44px;
+		height: 26px;
+		border-radius: 13px;
+		border: none;
+		background-color: color-mix(in srgb, var(--color-accent) 25%, var(--color-bg-elevated));
+		cursor: pointer;
+		transition: background-color 0.2s;
+		flex-shrink: 0;
+	}
+
+	.toggle.on {
+		background-color: var(--color-accent);
+	}
+
+	.thumb {
+		position: absolute;
+		top: 3px;
+		left: 3px;
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		background-color: #fff;
+		transition: transform 0.2s;
+	}
+
+	.toggle.on .thumb {
+		transform: translateX(18px);
+	}
+
+	/* ---- Save button ---- */
+	.save-btn {
+		width: 100%;
+		height: 40px;
+		border-radius: 8px;
+		border: none;
+		background-color: var(--color-accent);
+		color: var(--color-bg-primary);
+		font-size: 0.9rem;
+		font-weight: 600;
+		font-family: inherit;
+		cursor: pointer;
+		margin-top: 4px;
+		margin-bottom: 4px;
+		transition:
+			background-color 0.15s,
+			opacity 0.15s;
+	}
+
+	.save-btn:hover:not(:disabled) {
+		background-color: var(--color-accent-hover);
+	}
+
+	.save-btn:disabled {
+		opacity: 0.4;
+		cursor: default;
+	}
+
+	/* ---- Tags ---- */
+	.tags-loading {
+		margin: 0;
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+		opacity: 0.7;
+	}
+
+	/* ---- EXIF ---- */
+	.exif {
+		display: grid;
+		grid-template-columns: auto 1fr;
+		gap: 3px 12px;
+		font-size: 0.78rem;
+		margin: 0;
+	}
+
+	dt {
+		color: var(--color-text-muted);
+		font-weight: 500;
+	}
+
+	dd {
+		margin: 0;
+		color: var(--color-text-primary);
+		word-break: break-word;
+	}
+
+	/* ---- Misc ---- */
+	.error {
+		color: var(--color-danger);
+		font-size: 0.875rem;
+		padding: 8px 0;
+	}
+
+	.empty {
+		color: var(--color-text-muted);
+		font-size: 0.95rem;
+		text-align: center;
+		padding: 40px 0;
+	}
+
+	@keyframes shimmer {
+		0% {
+			background-position: 200% 0;
+		}
+		100% {
+			background-position: -200% 0;
+		}
+	}
+</style>

frontend/src/lib/components/file/FilterBar.svelte

@@ -0,0 +1,407 @@
+<script lang="ts">
+	import type { Tag } from '$lib/api/types';
+	import { fetchAllTags } from '$lib/api/tags';
+	import { buildDslFilter, parseDslFilter, tokenLabel } from '$lib/utils/dsl';
+
+	interface Props {
+		/** Current DSL filter string (e.g. "{t=uuid1,&,t=uuid2}"). */
+		value?: string | null;
+		onApply: (filter: string | null) => void;
+		onClose: () => void;
+	}
+
+	let { value = null, onApply, onClose }: Props = $props();
+
+	const OPERATORS = ['(', ')', '&', '|', '!'] as const;
+
+	let tags = $state<Tag[]>([]);
+	let search = $state('');
+	let tokens = $state<string[]>(parseDslFilter(value));
+	let tagNames = $derived(
+		new Map(tags.filter((t) => t.id && t.name).map((t) => [t.id as string, t.name as string]))
+	);
+
+	$effect(() => {
+		tokens = parseDslFilter(value ?? null);
+	});
+
+	$effect(() => {
+		fetchAllTags().then((all) => {
+			tags = all;
+		});
+	});
+
+	let filteredTags = $derived(
+		search.trim() ? tags.filter((t) => t.name?.toLowerCase().includes(search.toLowerCase())) : tags
+	);
+
+	function addToken(t: string) {
+		tokens = [...tokens, t];
+	}
+
+	function removeToken(i: number) {
+		tokens = tokens.filter((_, idx) => idx !== i);
+	}
+
+	function apply() {
+		onApply(buildDslFilter(tokens));
+	}
+
+	function reset() {
+		tokens = [];
+		search = '';
+		onApply(null);
+	}
+
+	// ---- Keyboard navigation (from the search input) ----
+	// ↓/↑ highlight a tag, Enter adds it as a token; the operator chars insert an
+	// operator token; with the input empty ←/→ walk the active tokens and Del
+	// removes the focused one. Mod+Enter applies, Mod+Backspace resets, Esc closes.
+	let highlightIdx = $state(0);
+	let tokenFocusIdx = $state(-1);
+	const OP_KEYS = ['&', '|', '!', '(', ')'];
+
+	$effect(() => {
+		if (highlightIdx > filteredTags.length - 1) {
+			highlightIdx = Math.max(0, filteredTags.length - 1);
+		}
+	});
+
+	function onSearchKeydown(e: KeyboardEvent) {
+		if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') {
+			e.preventDefault();
+			apply();
+			return;
+		}
+		if ((e.ctrlKey || e.metaKey) && e.key === 'Backspace') {
+			e.preventDefault();
+			reset();
+			return;
+		}
+		if (e.ctrlKey || e.metaKey || e.altKey) return;
+
+		if (OP_KEYS.includes(e.key)) {
+			e.preventDefault();
+			addToken(e.key);
+			return;
+		}
+
+		if (e.key === 'ArrowDown') {
+			e.preventDefault();
+			tokenFocusIdx = -1;
+			if (filteredTags.length) highlightIdx = Math.min(highlightIdx + 1, filteredTags.length - 1);
+		} else if (e.key === 'ArrowUp') {
+			e.preventDefault();
+			tokenFocusIdx = -1;
+			highlightIdx = Math.max(highlightIdx - 1, 0);
+		} else if (e.key === 'Enter') {
+			const tag = filteredTags[highlightIdx];
+			if (tag?.id) {
+				e.preventDefault();
+				addToken(`t=${tag.id}`);
+			}
+		} else if (e.key === 'ArrowRight' && search === '') {
+			e.preventDefault();
+			const n = tokens.length;
+			if (n) tokenFocusIdx = tokenFocusIdx < 0 ? 0 : Math.min(tokenFocusIdx + 1, n - 1);
+		} else if (e.key === 'ArrowLeft' && search === '') {
+			e.preventDefault();
+			const n = tokens.length;
+			if (n) tokenFocusIdx = tokenFocusIdx < 0 ? n - 1 : Math.max(tokenFocusIdx - 1, 0);
+		} else if (e.key === 'Delete' && tokenFocusIdx >= 0) {
+			e.preventDefault();
+			removeToken(tokenFocusIdx);
+			tokenFocusIdx = Math.min(tokenFocusIdx, tokens.length - 2);
+		} else if (e.key === 'Escape') {
+			e.preventDefault();
+			onClose();
+		}
+	}
+
+	// --- Drag-and-drop reordering ---
+	let dragIndex = $state<number | null>(null);
+	let dropIndex = $state<number | null>(null);
+
+	function onDragStart(i: number, e: DragEvent) {
+		dragIndex = i;
+		e.dataTransfer!.effectAllowed = 'move';
+		// Set minimal drag image so the token itself acts as the ghost
+		e.dataTransfer!.setData('text/plain', String(i));
+	}
+
+	function onDragOver(i: number, e: DragEvent) {
+		e.preventDefault();
+		e.dataTransfer!.dropEffect = 'move';
+		dropIndex = i;
+	}
+
+	function onDrop(i: number, e: DragEvent) {
+		e.preventDefault();
+		if (dragIndex === null || dragIndex === i) return;
+		const next = [...tokens];
+		const [moved] = next.splice(dragIndex, 1);
+		next.splice(i, 0, moved);
+		tokens = next;
+		dragIndex = null;
+		dropIndex = null;
+	}
+
+	function onDragEnd() {
+		dragIndex = null;
+		dropIndex = null;
+	}
+</script>
+
+<div class="bar">
+	<!-- Active tokens -->
+	<div class="active" class:empty={tokens.length === 0}>
+		{#if tokens.length === 0}
+			<span class="hint">No filter — tap a tag or operator below to build one</span>
+		{:else}
+			{#each tokens as token, i (i)}
+				<!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
+				<div
+					class="token active-token"
+					class:dragging={dragIndex === i}
+					class:drop-before={dropIndex === i && dragIndex !== null && dragIndex !== i}
+					class:kbfocus={tokenFocusIdx === i}
+					draggable="true"
+					role="button"
+					tabindex="0"
+					title="Drag to reorder · Click to remove"
+					ondragstart={(e) => onDragStart(i, e)}
+					ondragover={(e) => onDragOver(i, e)}
+					ondrop={(e) => onDrop(i, e)}
+					ondragend={onDragEnd}
+					onclick={() => removeToken(i)}
+					onkeydown={(e) => e.key === 'Delete' && removeToken(i)}
+				>
+					{tokenLabel(token, tagNames)}
+				</div>
+			{/each}
+		{/if}
+	</div>
+
+	<!-- Operator buttons -->
+	<div class="ops">
+		{#each OPERATORS as op}
+			<button class="token op-token" onclick={() => addToken(op)}>{op}</button>
+		{/each}
+	</div>
+
+	<!-- Tag search -->
+	<input
+		class="search"
+		type="search"
+		placeholder="Search tags…"
+		bind:value={search}
+		onkeydown={onSearchKeydown}
+		autocomplete="off"
+	/>
+
+	<!-- Tag list -->
+	<div class="tag-list">
+		{#each filteredTags as tag, i (tag.id)}
+			<button
+				class="token tag-token"
+				class:hl={highlightIdx === i}
+				style="background-color: {tag.color
+					? '#' + tag.color
+					: tag.category_color
+						? '#' + tag.category_color
+						: 'var(--color-tag-default)'}"
+				onclick={() => addToken(`t=${tag.id}`)}
+			>
+				{tag.name}
+			</button>
+		{:else}
+			<span class="no-tags">{search ? 'No matching tags' : 'No tags yet'}</span>
+		{/each}
+	</div>
+
+	<!-- Actions -->
+	<div class="actions">
+		<button class="btn btn-reset" onclick={reset}>Reset</button>
+		<button class="btn btn-apply" onclick={apply}>Apply</button>
+		<button class="btn btn-close" onclick={onClose}>Close</button>
+	</div>
+</div>
+
+<style>
+	.bar {
+		background-color: var(--color-bg-elevated);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 20%, transparent);
+		padding: 8px 10px;
+		display: flex;
+		flex-direction: column;
+		gap: 8px;
+		position: sticky;
+		top: 43px; /* header height */
+		z-index: 9;
+	}
+
+	.active {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 4px;
+		min-height: 32px;
+		align-items: center;
+	}
+
+	.active.empty {
+		opacity: 0.5;
+	}
+
+	.hint {
+		font-size: 0.75rem;
+		color: var(--color-text-muted);
+	}
+
+	.ops {
+		display: flex;
+		gap: 4px;
+	}
+
+	.token {
+		display: inline-flex;
+		align-items: center;
+		height: 26px;
+		padding: 0 8px;
+		border-radius: 5px;
+		font-size: 0.8rem;
+		cursor: pointer;
+		border: none;
+		font-family: inherit;
+	}
+
+	.active-token {
+		background-color: var(--color-accent);
+		color: var(--color-bg-primary);
+		font-weight: 600;
+		cursor: grab;
+		user-select: none;
+		transition:
+			opacity 0.15s,
+			outline 0.1s;
+		outline: 2px solid transparent;
+	}
+
+	.active-token:hover {
+		background-color: var(--color-accent-hover);
+	}
+
+	.active-token.dragging {
+		opacity: 0.4;
+		cursor: grabbing;
+	}
+
+	.active-token.drop-before {
+		outline: 2px solid var(--color-accent);
+		outline-offset: 2px;
+	}
+
+	.active-token.kbfocus {
+		outline: 2px solid var(--color-danger);
+		outline-offset: 2px;
+	}
+
+	.op-token {
+		background-color: color-mix(in srgb, var(--color-accent) 18%, var(--color-bg-elevated));
+		color: var(--color-text-primary);
+		font-weight: 700;
+		min-width: 30px;
+		justify-content: center;
+	}
+
+	.op-token:hover {
+		background-color: color-mix(in srgb, var(--color-accent) 35%, var(--color-bg-elevated));
+	}
+
+	.search {
+		width: 100%;
+		box-sizing: border-box;
+		height: 30px;
+		padding: 0 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-primary);
+		color: var(--color-text-primary);
+		font-size: 0.85rem;
+		font-family: inherit;
+		outline: none;
+	}
+
+	.search:focus {
+		border-color: var(--color-accent);
+	}
+
+	.tag-list {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 4px;
+		max-height: 120px;
+		overflow-y: auto;
+	}
+
+	.tag-token {
+		color: rgba(255, 255, 255, 0.9);
+	}
+
+	.tag-token:hover {
+		filter: brightness(1.15);
+	}
+
+	.tag-token.hl {
+		outline: 2px solid var(--color-text-primary);
+		outline-offset: 1px;
+	}
+
+	.no-tags {
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+	}
+
+	.actions {
+		display: flex;
+		gap: 6px;
+		justify-content: flex-end;
+	}
+
+	.btn {
+		height: 30px;
+		padding: 0 14px;
+		border-radius: 6px;
+		border: none;
+		font-size: 0.85rem;
+		font-family: inherit;
+		cursor: pointer;
+	}
+
+	.btn-apply {
+		background-color: var(--color-accent);
+		color: var(--color-bg-primary);
+		font-weight: 600;
+	}
+
+	.btn-apply:hover {
+		background-color: var(--color-accent-hover);
+	}
+
+	.btn-reset {
+		background-color: color-mix(in srgb, var(--color-danger) 20%, var(--color-bg-elevated));
+		color: var(--color-text-primary);
+	}
+
+	.btn-reset:hover {
+		background-color: color-mix(in srgb, var(--color-danger) 35%, var(--color-bg-elevated));
+	}
+
+	.btn-close {
+		background-color: color-mix(in srgb, var(--color-accent) 15%, var(--color-bg-elevated));
+		color: var(--color-text-muted);
+	}
+
+	.btn-close:hover {
+		color: var(--color-text-primary);
+	}
+</style>

frontend/src/lib/components/file/PoolPicker.svelte

@@ -0,0 +1,251 @@
+<script lang="ts">
+	import { api } from '$lib/api/client';
+	import type { Pool, PoolOffsetPage } from '$lib/api/types';
+
+	interface Props {
+		/** Files to add to the chosen pool. */
+		fileIds: string[];
+		/** Called after a successful add (before close) — e.g. to clear a selection. */
+		onAdded?: (poolId: string) => void;
+		/** Close the picker without adding. */
+		onClose: () => void;
+	}
+
+	let { fileIds, onAdded, onClose }: Props = $props();
+
+	let pools = $state<Pool[]>([]);
+	let loading = $state(true);
+	let loadError = $state('');
+	let addError = $state('');
+	let search = $state('');
+	let busy = $state(false);
+
+	$effect(() => {
+		void load();
+	});
+
+	async function load() {
+		loading = true;
+		loadError = '';
+		try {
+			const res = await api.get<PoolOffsetPage>('/pools?limit=200&sort=name&order=asc');
+			pools = res.items ?? [];
+		} catch {
+			loadError = 'Failed to load pools';
+		} finally {
+			loading = false;
+		}
+	}
+
+	let filtered = $derived(
+		search.trim()
+			? pools.filter((p) => p.name?.toLowerCase().includes(search.toLowerCase()))
+			: pools
+	);
+
+	async function add(poolId: string) {
+		if (busy) return;
+		busy = true;
+		addError = '';
+		try {
+			await api.post(`/pools/${poolId}/files`, { file_ids: fileIds });
+			onAdded?.(poolId);
+			onClose();
+		} catch {
+			addError = 'Failed to add to pool';
+			busy = false;
+		}
+	}
+
+	let count = $derived(fileIds.length);
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<div class="picker-backdrop" role="presentation" onclick={onClose}></div>
+<div class="picker-sheet" class:busy role="dialog" aria-label="Add to pool">
+	<div class="picker-header">
+		<span class="picker-title">Add {count} file{count !== 1 ? 's' : ''} to pool</span>
+		<button class="picker-close" onclick={onClose} aria-label="Close">
+			<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+				<path
+					d="M3 3l10 10M13 3L3 13"
+					stroke="currentColor"
+					stroke-width="1.8"
+					stroke-linecap="round"
+				/>
+			</svg>
+		</button>
+	</div>
+
+	<div class="picker-search-wrap">
+		<input
+			class="picker-search"
+			type="search"
+			placeholder="Search pools…"
+			bind:value={search}
+			autocomplete="off"
+		/>
+	</div>
+
+	{#if loading}
+		<p class="picker-empty">Loading…</p>
+	{:else if loadError}
+		<p class="picker-error">{loadError}</p>
+	{:else}
+		{#if addError}
+			<p class="picker-error">{addError}</p>
+		{/if}
+		{#if filtered.length === 0}
+			<p class="picker-empty">No pools found.</p>
+		{:else}
+			<ul class="picker-list">
+				{#each filtered as pool (pool.id)}
+					<li>
+						<button class="picker-item" onclick={() => pool.id && add(pool.id)}>
+							<span class="picker-item-name">{pool.name}</span>
+							<span class="picker-item-count">{pool.file_count ?? 0} files</span>
+						</button>
+					</li>
+				{/each}
+			</ul>
+		{/if}
+	{/if}
+</div>
+
+<style>
+	.picker-backdrop {
+		position: fixed;
+		inset: 0;
+		z-index: 110;
+		background: rgba(0, 0, 0, 0.5);
+	}
+
+	.picker-sheet {
+		position: fixed;
+		left: 0;
+		right: 0;
+		bottom: 0;
+		z-index: 111;
+		background-color: var(--color-bg-secondary);
+		border-radius: 14px 14px 0 0;
+		padding-bottom: env(safe-area-inset-bottom, 0px);
+		max-height: 70dvh;
+		display: flex;
+		flex-direction: column;
+		animation: slide-up 0.18s ease-out;
+	}
+
+	.picker-sheet.busy {
+		opacity: 0.6;
+		pointer-events: none;
+	}
+
+	@keyframes slide-up {
+		from {
+			transform: translateY(20px);
+			opacity: 0;
+		}
+		to {
+			transform: translateY(0);
+			opacity: 1;
+		}
+	}
+
+	.picker-header {
+		display: flex;
+		align-items: center;
+		padding: 14px 16px 10px;
+		gap: 8px;
+	}
+
+	.picker-title {
+		flex: 1;
+		font-size: 0.95rem;
+		font-weight: 600;
+	}
+
+	.picker-close {
+		background: none;
+		border: none;
+		cursor: pointer;
+		color: var(--color-text-muted);
+		padding: 4px;
+		display: flex;
+		align-items: center;
+	}
+
+	.picker-close:hover {
+		color: var(--color-text-primary);
+	}
+
+	.picker-search-wrap {
+		padding: 0 14px 10px;
+	}
+
+	.picker-search {
+		width: 100%;
+		box-sizing: border-box;
+		height: 34px;
+		padding: 0 10px;
+		border-radius: 8px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.9rem;
+		font-family: inherit;
+		outline: none;
+	}
+
+	.picker-search:focus {
+		border-color: var(--color-accent);
+	}
+
+	.picker-list {
+		list-style: none;
+		margin: 0;
+		padding: 0 8px 12px;
+		overflow-y: auto;
+		flex: 1;
+	}
+
+	.picker-item {
+		display: flex;
+		align-items: center;
+		width: 100%;
+		text-align: left;
+		padding: 11px 10px;
+		border-radius: 8px;
+		background: none;
+		border: none;
+		cursor: pointer;
+		font-family: inherit;
+		gap: 8px;
+	}
+
+	.picker-item:hover {
+		background-color: color-mix(in srgb, var(--color-accent) 12%, transparent);
+	}
+
+	.picker-item-name {
+		flex: 1;
+		font-size: 0.95rem;
+		color: var(--color-text-primary);
+	}
+
+	.picker-item-count {
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+	}
+
+	.picker-empty,
+	.picker-error {
+		text-align: center;
+		padding: 20px;
+		font-size: 0.9rem;
+		color: var(--color-text-muted);
+	}
+
+	.picker-error {
+		color: var(--color-danger);
+	}
+</style>

frontend/src/lib/components/file/TagPicker.svelte

@@ -0,0 +1,328 @@
+<script lang="ts">
+	import type { Tag } from '$lib/api/types';
+	import { fetchAllTags, sortTags } from '$lib/api/tags';
+	import { tagSorting } from '$lib/stores/sorting';
+
+	interface Props {
+		fileTags: Tag[];
+		onAdd: (tagId: string) => Promise<void>;
+		onRemove: (tagId: string) => Promise<void>;
+		/** Called when Escape leaves an already-empty filter, so the viewer can
+		 *  scroll the preview back into view. */
+		onExit?: () => void;
+	}
+
+	let { fileTags, onAdd, onRemove, onExit }: Props = $props();
+
+	let allTags = $state<Tag[]>([]);
+	let search = $state('');
+	let busy = $state(false);
+
+	$effect(() => {
+		fetchAllTags().then((all) => {
+			allTags = all;
+		});
+	});
+
+	let assignedIds = $derived(new Set(fileTags.map((t) => t.id)));
+
+	let filteredAvailable = $derived(
+		allTags.filter(
+			(t) =>
+				!assignedIds.has(t.id) &&
+				(!search.trim() || t.name?.toLowerCase().includes(search.toLowerCase()))
+		)
+	);
+
+	// Show a file's already-assigned tags in the user's chosen tag order too.
+	let sortedAssigned = $derived(sortTags(fileTags, $tagSorting));
+
+	let filteredAssigned = $derived(
+		search.trim()
+			? sortedAssigned.filter((t) => t.name?.toLowerCase().includes(search.toLowerCase()))
+			: sortedAssigned
+	);
+
+	async function handleAdd(tagId: string) {
+		if (busy) return;
+		busy = true;
+		try {
+			await onAdd(tagId);
+		} finally {
+			busy = false;
+		}
+	}
+
+	async function handleRemove(tagId: string) {
+		if (busy) return;
+		busy = true;
+		try {
+			await onRemove(tagId);
+		} finally {
+			busy = false;
+		}
+	}
+
+	function tagStyle(tag: Tag) {
+		const color = tag.color ?? tag.category_color;
+		return color ? `background-color: #${color}` : '';
+	}
+
+	// ---- Keyboard navigation (from the search input) ----
+	// ↓/↑ highlight a suggestion, Enter adds it (focus stays for chaining); with the
+	// input empty, ←/→ walk the assigned pills and Del removes the focused one.
+	let highlightIdx = $state(0);
+	let assignedFocusIdx = $state(-1);
+
+	$effect(() => {
+		if (highlightIdx > filteredAvailable.length - 1) {
+			highlightIdx = Math.max(0, filteredAvailable.length - 1);
+		}
+	});
+
+	function onSearchKeydown(e: KeyboardEvent) {
+		if (e.key === 'ArrowDown') {
+			e.preventDefault();
+			assignedFocusIdx = -1;
+			if (filteredAvailable.length) {
+				highlightIdx = Math.min(highlightIdx + 1, filteredAvailable.length - 1);
+			}
+		} else if (e.key === 'ArrowUp') {
+			e.preventDefault();
+			assignedFocusIdx = -1;
+			highlightIdx = Math.max(highlightIdx - 1, 0);
+		} else if (e.key === 'Enter') {
+			const tag = filteredAvailable[highlightIdx];
+			if (tag?.id) {
+				e.preventDefault();
+				void handleAdd(tag.id);
+			}
+		} else if (e.key === 'ArrowRight' && search === '') {
+			e.preventDefault();
+			const n = filteredAssigned.length;
+			if (n) assignedFocusIdx = assignedFocusIdx < 0 ? 0 : Math.min(assignedFocusIdx + 1, n - 1);
+		} else if (e.key === 'ArrowLeft' && search === '') {
+			e.preventDefault();
+			const n = filteredAssigned.length;
+			if (n) assignedFocusIdx = assignedFocusIdx < 0 ? n - 1 : Math.max(assignedFocusIdx - 1, 0);
+		} else if (e.key === 'Delete' && assignedFocusIdx >= 0) {
+			const tag = filteredAssigned[assignedFocusIdx];
+			if (tag?.id) {
+				e.preventDefault();
+				void handleRemove(tag.id);
+				assignedFocusIdx = Math.min(assignedFocusIdx, filteredAssigned.length - 2);
+			}
+		} else if (e.key === 'Escape') {
+			e.preventDefault();
+			if (search) {
+				// Non-empty filter: just clear it, keeping focus for more editing.
+				search = '';
+				assignedFocusIdx = -1;
+				return;
+			}
+			// Empty: blur back to the page (so arrow keys and a further Escape reach
+			// the viewer) and let it scroll the preview back into view.
+			assignedFocusIdx = -1;
+			(e.currentTarget as HTMLInputElement).blur();
+			onExit?.();
+		}
+	}
+</script>
+
+<div class="picker" class:busy>
+	<!-- Assigned tags -->
+	{#if fileTags.length > 0}
+		<div class="section-label">Assigned</div>
+		<div class="tag-row">
+			{#each filteredAssigned as tag, i (tag.id)}
+				<button
+					class="tag assigned"
+					class:kbfocus={assignedFocusIdx === i}
+					style={tagStyle(tag)}
+					onclick={() => handleRemove(tag.id!)}
+					title="Remove tag"
+				>
+					{tag.name}
+					<span class="remove">×</span>
+				</button>
+			{/each}
+		</div>
+	{/if}
+
+	<!-- Search -->
+	<div class="search-wrap">
+		<input
+			class="search"
+			type="search"
+			placeholder="Search tags…"
+			bind:value={search}
+			onkeydown={onSearchKeydown}
+			autocomplete="off"
+		/>
+		{#if search}
+			<button class="search-clear" onclick={() => (search = '')} aria-label="Clear search">
+				<svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+					<path
+						d="M2 2l10 10M12 2L2 12"
+						stroke="currentColor"
+						stroke-width="1.8"
+						stroke-linecap="round"
+					/>
+				</svg>
+			</button>
+		{/if}
+	</div>
+
+	<!-- Available tags -->
+	{#if filteredAvailable.length > 0}
+		<div class="section-label">Add tag</div>
+		<div class="tag-row available-row">
+			{#each filteredAvailable as tag, i (tag.id)}
+				<button
+					class="tag available"
+					class:hl={highlightIdx === i}
+					style={tagStyle(tag)}
+					onclick={() => handleAdd(tag.id!)}
+					title="Add tag"
+				>
+					{tag.name}
+				</button>
+			{/each}
+		</div>
+	{:else if search.trim()}
+		<p class="empty">No matching tags</p>
+	{/if}
+</div>
+
+<style>
+	.picker {
+		display: flex;
+		flex-direction: column;
+		gap: 6px;
+	}
+
+	.picker.busy {
+		opacity: 0.6;
+		pointer-events: none;
+	}
+
+	.section-label {
+		font-size: 0.75rem;
+		color: var(--color-text-muted);
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+	}
+
+	.tag-row {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 5px;
+	}
+
+	.available-row {
+		max-height: 140px;
+		overflow-y: auto;
+	}
+
+	.tag {
+		display: inline-flex;
+		align-items: center;
+		gap: 4px;
+		height: 26px;
+		padding: 0 9px;
+		border-radius: 5px;
+		font-size: 0.8rem;
+		font-family: inherit;
+		cursor: pointer;
+		border: none;
+		background-color: var(--color-tag-default);
+		color: rgba(255, 255, 255, 0.9);
+		user-select: none;
+	}
+
+	.tag.assigned {
+		opacity: 0.95;
+	}
+
+	.tag.assigned:hover {
+		filter: brightness(1.1);
+	}
+
+	.remove {
+		font-size: 1rem;
+		line-height: 1;
+		opacity: 0.7;
+	}
+
+	.tag.available {
+		opacity: 0.75;
+	}
+
+	.tag.available:hover {
+		opacity: 1;
+		filter: brightness(1.1);
+	}
+
+	.tag.available.hl {
+		opacity: 1;
+		outline: 2px solid var(--color-accent);
+		outline-offset: 1px;
+	}
+
+	.tag.assigned.kbfocus {
+		outline: 2px solid var(--color-danger);
+		outline-offset: 1px;
+	}
+
+	.search-wrap {
+		position: relative;
+		display: flex;
+		align-items: center;
+	}
+
+	.search {
+		width: 100%;
+		box-sizing: border-box;
+		height: 32px;
+		padding: 0 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-primary);
+		color: var(--color-text-primary);
+		font-size: 0.85rem;
+		font-family: inherit;
+		outline: none;
+	}
+
+	.search:focus {
+		border-color: var(--color-accent);
+	}
+
+	.search-clear {
+		position: absolute;
+		right: 6px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		border: none;
+		background: none;
+		color: var(--color-text-muted);
+		cursor: pointer;
+		padding: 0;
+	}
+
+	.search-clear:hover {
+		color: var(--color-text-primary);
+		background-color: color-mix(in srgb, var(--color-accent) 20%, transparent);
+	}
+
+	.empty {
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+		margin: 0;
+	}
+</style>

frontend/src/lib/components/layout/Header.svelte

@@ -0,0 +1,209 @@
+<script lang="ts">
+	import type { SortOrder } from '$lib/stores/sorting';
+	import { selectionStore, selectionActive } from '$lib/stores/selection';
+
+	interface Props {
+		sortOptions: { value: string; label: string }[];
+		sort: string;
+		order: SortOrder;
+		filterActive?: boolean;
+		onSortChange: (sort: string) => void;
+		onOrderToggle: () => void;
+		onFilterToggle: () => void;
+		onUpload?: () => void;
+		onTrash?: () => void;
+	}
+
+	let {
+		sortOptions,
+		sort,
+		order,
+		filterActive = false,
+		onSortChange,
+		onOrderToggle,
+		onFilterToggle,
+		onUpload,
+		onTrash
+	}: Props = $props();
+</script>
+
+<header>
+	<button
+		class="select-btn"
+		class:active={$selectionActive}
+		onclick={() => ($selectionActive ? selectionStore.exit() : selectionStore.enter())}
+	>
+		{$selectionActive ? 'Cancel' : 'Select'}
+	</button>
+
+	{#if onUpload}
+		<button class="upload-btn icon-btn" onclick={onUpload} title="Upload files">
+			<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+				<path
+					d="M8 2v9M4 6l4-4 4 4"
+					stroke="currentColor"
+					stroke-width="1.8"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+				/>
+				<path d="M2 13h12" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" />
+			</svg>
+		</button>
+	{/if}
+
+	{#if onTrash}
+		<button class="icon-btn trash-btn" onclick={onTrash} title="Trash">
+			<svg width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true">
+				<path
+					d="M2 4h11M5 4V2.5h5V4M5.5 7v4.5M9.5 7v4.5M3 4l.8 9h7.4l.8-9"
+					stroke="currentColor"
+					stroke-width="1.6"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+				/>
+			</svg>
+		</button>
+	{/if}
+
+	<div class="controls">
+		<select
+			class="sort-select"
+			value={sort}
+			onchange={(e) => onSortChange((e.currentTarget as HTMLSelectElement).value)}
+		>
+			{#each sortOptions as opt}
+				<option value={opt.value}>{opt.label}</option>
+			{/each}
+		</select>
+
+		<button
+			class="icon-btn order-btn"
+			onclick={onOrderToggle}
+			title={order === 'asc' ? 'Ascending' : 'Descending'}
+		>
+			{#if order === 'asc'}
+				<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+					<path
+						d="M4 10L8 6L12 10"
+						stroke="currentColor"
+						stroke-width="1.8"
+						stroke-linecap="round"
+						stroke-linejoin="round"
+					/>
+				</svg>
+			{:else}
+				<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+					<path
+						d="M4 6L8 10L12 6"
+						stroke="currentColor"
+						stroke-width="1.8"
+						stroke-linecap="round"
+						stroke-linejoin="round"
+					/>
+				</svg>
+			{/if}
+		</button>
+
+		<button
+			class="icon-btn filter-btn"
+			class:active={filterActive}
+			onclick={onFilterToggle}
+			title="Filter"
+		>
+			<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+				<path
+					d="M2 4h12M4 8h8M6 12h4"
+					stroke="currentColor"
+					stroke-width="1.8"
+					stroke-linecap="round"
+				/>
+			</svg>
+		</button>
+	</div>
+</header>
+
+<style>
+	header {
+		display: flex;
+		align-items: center;
+		padding: 6px 10px;
+		background-color: var(--color-bg-primary);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 15%, transparent);
+		gap: 6px;
+		flex-shrink: 0;
+		position: sticky;
+		top: 0;
+		z-index: 10;
+	}
+
+	.select-btn {
+		height: 30px;
+		padding: 0 12px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-muted);
+		font-size: 0.85rem;
+		font-family: inherit;
+		cursor: pointer;
+	}
+
+	.select-btn:hover {
+		color: var(--color-text-primary);
+		border-color: var(--color-accent);
+	}
+
+	.select-btn.active {
+		background-color: color-mix(in srgb, var(--color-accent) 25%, var(--color-bg-elevated));
+		color: var(--color-accent);
+		border-color: var(--color-accent);
+	}
+
+	.controls {
+		display: flex;
+		align-items: center;
+		gap: 4px;
+		margin-left: auto;
+	}
+
+	.sort-select {
+		height: 30px;
+		padding: 0 8px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.85rem;
+		font-family: inherit;
+		cursor: pointer;
+		outline: none;
+	}
+
+	.sort-select:focus {
+		border-color: var(--color-accent);
+	}
+
+	.icon-btn {
+		width: 30px;
+		height: 30px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-muted);
+		cursor: pointer;
+	}
+
+	.icon-btn:hover {
+		color: var(--color-text-primary);
+		border-color: var(--color-accent);
+	}
+
+	.icon-btn.active {
+		background-color: color-mix(in srgb, var(--color-accent) 25%, var(--color-bg-elevated));
+		color: var(--color-accent);
+		border-color: var(--color-accent);
+	}
+</style>

frontend/src/lib/components/layout/KeyboardHelp.svelte

@@ -0,0 +1,193 @@
+<script lang="ts">
+	interface Props {
+		onClose: () => void;
+	}
+
+	let { onClose }: Props = $props();
+
+	// Static cheat-sheet of the app's shortcuts, grouped by context. Kept in sync
+	// by hand with the per-context handlers (global nav here, the rest on the
+	// Files page / viewer / tag pickers).
+	const groups: { title: string; rows: [string, string][] }[] = [
+		{
+			title: 'Anywhere',
+			rows: [
+				['g then c / t / f / p / s', 'Go to Categories / Tags / Files / Pools / Settings'],
+				['1 – 5', 'Jump to a section'],
+				['?', 'Toggle this help'],
+				['/', 'Focus the filter / search']
+			]
+		},
+		{
+			title: 'File grid',
+			rows: [
+				['↑ ↓ ← →', 'Move focus between files'],
+				['Enter', 'Open the focused file'],
+				['Space / x', 'Select / deselect'],
+				['Shift+Space / Shift+x', 'Select a range from the anchor'],
+				['e', 'Edit tags (focus the tag filter)'],
+				['p', 'Add to pool'],
+				['Del', 'Move to trash'],
+				['Esc', 'Clear selection']
+			]
+		},
+		{
+			title: 'Viewer',
+			rows: [
+				['← / → or j / k', 'Previous / next file'],
+				['e', 'Jump to tags & focus the filter'],
+				['Esc', 'Close']
+			]
+		},
+		{
+			title: 'Tag editor / filter',
+			rows: [
+				['↓ ↑', 'Highlight a suggestion'],
+				['Enter', 'Add the highlighted tag'],
+				['← →', 'Move across added tags / tokens (empty input)'],
+				['Del', 'Remove the focused tag / token'],
+				['& | ! ( )', 'Insert an operator (filter only)'],
+				['Ctrl+Enter', 'Apply the filter'],
+				['Ctrl+Backspace', 'Reset the filter'],
+				['Esc', 'Leave the field / close']
+			]
+		}
+	];
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
+<div class="backdrop" role="presentation" onclick={onClose}></div>
+<div class="sheet" role="dialog" aria-label="Keyboard shortcuts" aria-modal="true">
+	<div class="head">
+		<span class="title">Keyboard shortcuts</span>
+		<button class="close" onclick={onClose} aria-label="Close">
+			<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+				<path
+					d="M3 3l10 10M13 3L3 13"
+					stroke="currentColor"
+					stroke-width="1.8"
+					stroke-linecap="round"
+				/>
+			</svg>
+		</button>
+	</div>
+	<div class="body">
+		{#each groups as group}
+			<section class="group">
+				<h3 class="group-title">{group.title}</h3>
+				{#each group.rows as [keys, desc]}
+					<div class="row">
+						<kbd class="keys">{keys}</kbd>
+						<span class="desc">{desc}</span>
+					</div>
+				{/each}
+			</section>
+		{/each}
+	</div>
+</div>
+
+<style>
+	.backdrop {
+		position: fixed;
+		inset: 0;
+		z-index: 300;
+		background: rgba(0, 0, 0, 0.5);
+	}
+
+	.sheet {
+		position: fixed;
+		left: 50%;
+		top: 50%;
+		transform: translate(-50%, -50%);
+		z-index: 301;
+		width: min(560px, calc(100vw - 24px));
+		max-height: min(80dvh, 640px);
+		display: flex;
+		flex-direction: column;
+		background-color: var(--color-bg-secondary);
+		border-radius: 14px;
+		box-shadow: 0 8px 40px rgba(0, 0, 0, 0.5);
+		animation: pop 0.16s ease-out;
+	}
+
+	@keyframes pop {
+		from {
+			transform: translate(-50%, -48%) scale(0.98);
+			opacity: 0;
+		}
+		to {
+			transform: translate(-50%, -50%) scale(1);
+			opacity: 1;
+		}
+	}
+
+	.head {
+		display: flex;
+		align-items: center;
+		padding: 14px 16px 10px;
+	}
+
+	.title {
+		flex: 1;
+		font-size: 1rem;
+		font-weight: 600;
+	}
+
+	.close {
+		background: none;
+		border: none;
+		cursor: pointer;
+		color: var(--color-text-muted);
+		padding: 4px;
+		display: flex;
+	}
+
+	.close:hover {
+		color: var(--color-text-primary);
+	}
+
+	.body {
+		padding: 0 16px 18px;
+		overflow-y: auto;
+		display: grid;
+		grid-template-columns: repeat(auto-fit, minmax(230px, 1fr));
+		gap: 6px 20px;
+	}
+
+	.group {
+		break-inside: avoid;
+		padding-top: 8px;
+	}
+
+	.group-title {
+		font-size: 0.72rem;
+		text-transform: uppercase;
+		letter-spacing: 0.06em;
+		color: var(--color-accent);
+		margin: 0 0 6px;
+	}
+
+	.row {
+		display: flex;
+		align-items: baseline;
+		gap: 10px;
+		padding: 3px 0;
+	}
+
+	.keys {
+		flex-shrink: 0;
+		font-family: var(--font-sans);
+		font-size: 0.72rem;
+		color: var(--color-text-primary);
+		background-color: var(--color-bg-elevated);
+		border: 1px solid color-mix(in srgb, var(--color-accent) 25%, transparent);
+		border-radius: 5px;
+		padding: 2px 6px;
+		white-space: nowrap;
+	}
+
+	.desc {
+		font-size: 0.82rem;
+		color: var(--color-text-muted);
+	}
+</style>

frontend/src/lib/components/layout/SelectionBar.svelte

@@ -0,0 +1,150 @@
+<script lang="ts">
+	import { selectionStore, selectionCount } from '$lib/stores/selection';
+
+	interface Props {
+		onEditTags: () => void;
+		onAddToPool: () => void;
+		onDelete: () => void;
+	}
+
+	let { onEditTags, onAddToPool, onDelete }: Props = $props();
+</script>
+
+<div class="bar" role="toolbar" aria-label="Selection actions">
+	<div class="row">
+		<!-- Count / deselect all -->
+		<button class="count" onclick={() => selectionStore.exit()} title="Clear selection">
+			<span class="num">{$selectionCount}</span>
+			<span class="label">selected</span>
+			<svg
+				class="close-icon"
+				width="14"
+				height="14"
+				viewBox="0 0 14 14"
+				fill="none"
+				aria-hidden="true"
+			>
+				<path
+					d="M2 2l10 10M12 2L2 12"
+					stroke="currentColor"
+					stroke-width="1.8"
+					stroke-linecap="round"
+				/>
+			</svg>
+		</button>
+
+		<div class="spacer"></div>
+
+		<button class="action edit-tags" onclick={onEditTags}>Edit tags</button>
+		<button class="action add-pool" onclick={onAddToPool}>Add to pool</button>
+		<button class="action delete" onclick={onDelete}>Delete</button>
+	</div>
+</div>
+
+<style>
+	.bar {
+		position: fixed;
+		left: 10px;
+		right: 10px;
+		bottom: 65px;
+		box-sizing: border-box;
+		background-color: var(--color-bg-secondary);
+		border-radius: 10px;
+		box-shadow: 0 0 12px rgba(0, 0, 0, 0.5);
+		padding: 12px 14px;
+		z-index: 100;
+		animation: slide-up 0.18s ease-out;
+	}
+
+	@keyframes slide-up {
+		from {
+			transform: translateY(12px);
+			opacity: 0;
+		}
+		to {
+			transform: translateY(0);
+			opacity: 1;
+		}
+	}
+
+	.row {
+		display: flex;
+		align-items: center;
+		gap: 4px;
+	}
+
+	.spacer {
+		flex: 1;
+	}
+
+	.count {
+		display: flex;
+		align-items: center;
+		gap: 5px;
+		background: none;
+		border: none;
+		cursor: pointer;
+		padding: 4px 6px;
+		border-radius: 6px;
+		color: var(--color-text-muted);
+		font-family: inherit;
+	}
+
+	.count:hover {
+		background-color: color-mix(in srgb, var(--color-accent) 12%, transparent);
+		color: var(--color-text-primary);
+	}
+
+	.num {
+		font-size: 1.1rem;
+		font-weight: 700;
+		color: var(--color-text-primary);
+	}
+
+	.label {
+		font-size: 0.85rem;
+	}
+
+	.close-icon {
+		opacity: 0.5;
+	}
+
+	.count:hover .close-icon {
+		opacity: 1;
+	}
+
+	.action {
+		background: none;
+		border: none;
+		cursor: pointer;
+		padding: 6px 10px;
+		border-radius: 6px;
+		font-size: 0.85rem;
+		font-family: inherit;
+		font-weight: 600;
+	}
+
+	.edit-tags {
+		color: var(--color-info);
+	}
+
+	.edit-tags:hover {
+		background-color: color-mix(in srgb, var(--color-info) 15%, transparent);
+	}
+
+	.add-pool {
+		color: var(--color-warning);
+	}
+
+	.add-pool:hover {
+		background-color: color-mix(in srgb, var(--color-warning) 15%, transparent);
+	}
+
+	.delete {
+		color: var(--color-danger);
+	}
+
+	.delete:hover {
+		background-color: color-mix(in srgb, var(--color-danger) 15%, transparent);
+	}
+</style>

frontend/src/lib/components/tag/TagBadge.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+	import type { Tag } from '$lib/api/types';
+
+	interface Props {
+		tag: Tag;
+		onclick?: () => void;
+		size?: 'sm' | 'md';
+	}
+
+	let { tag, onclick, size = 'md' }: Props = $props();
+
+	const color = tag.color ?? tag.category_color;
+	const style = color ? `background-color: #${color}` : '';
+</script>
+
+{#if onclick}
+	<button class="badge {size}" {style} {onclick} type="button">
+		{tag.name}
+	</button>
+{:else}
+	<span class="badge {size}" {style}>{tag.name}</span>
+{/if}
+
+<style>
+	.badge {
+		display: inline-flex;
+		align-items: center;
+		border-radius: 5px;
+		font-family: inherit;
+		background-color: var(--color-tag-default);
+		color: rgba(255, 255, 255, 0.9);
+		white-space: nowrap;
+		border: none;
+		cursor: default;
+	}
+
+	.badge.md {
+		height: 28px;
+		padding: 0 10px;
+		font-size: 0.85rem;
+	}
+
+	.badge.sm {
+		height: 22px;
+		padding: 0 7px;
+		font-size: 0.75rem;
+	}
+
+	button.badge {
+		cursor: pointer;
+	}
+
+	button.badge:hover {
+		filter: brightness(1.15);
+	}
+</style>

frontend/src/lib/components/tag/TagRuleEditor.svelte

@@ -0,0 +1,333 @@
+<script lang="ts">
+	import { api, ApiError } from '$lib/api/client';
+	import type { Tag, TagRule } from '$lib/api/types';
+	import { fetchAllTags } from '$lib/api/tags';
+	import TagBadge from './TagBadge.svelte';
+	import { appSettings } from '$lib/stores/appSettings';
+
+	interface Props {
+		tagId: string;
+		rules: TagRule[];
+		onRulesChange: (rules: TagRule[]) => void;
+	}
+
+	let { tagId, rules, onRulesChange }: Props = $props();
+
+	let allTags = $state<Tag[]>([]);
+	let search = $state('');
+	let busy = $state(false);
+	let error = $state('');
+
+	$effect(() => {
+		fetchAllTags().then((all) => {
+			allTags = all;
+		});
+	});
+
+	// IDs already used in rules
+	let usedIds = $derived(new Set(rules.map((r) => r.then_tag_id)));
+
+	let filteredTags = $derived(
+		allTags.filter(
+			(t) =>
+				t.id !== tagId &&
+				!usedIds.has(t.id) &&
+				(!search.trim() || t.name?.toLowerCase().includes(search.toLowerCase()))
+		)
+	);
+
+	function tagForId(id: string | undefined) {
+		return allTags.find((t) => t.id === id);
+	}
+
+	async function addRule(thenTagId: string) {
+		if (busy) return;
+		busy = true;
+		error = '';
+		try {
+			const rule = await api.post<TagRule>(`/tags/${tagId}/rules`, {
+				then_tag_id: thenTagId,
+				is_active: true,
+				apply_to_existing: $appSettings.tagRuleApplyToExisting
+			});
+			onRulesChange([...rules, rule]);
+			search = '';
+		} catch (e) {
+			error = e instanceof ApiError ? e.message : 'Failed to add rule';
+		} finally {
+			busy = false;
+		}
+	}
+
+	async function toggleRule(rule: TagRule) {
+		if (busy) return;
+		busy = true;
+		error = '';
+		const thenTagId = rule.then_tag_id!;
+		const activating = !rule.is_active;
+		try {
+			const body: Record<string, unknown> = { is_active: activating };
+			if (activating) body.apply_to_existing = $appSettings.tagRuleApplyToExisting;
+			const updated = await api.patch<TagRule>(`/tags/${tagId}/rules/${thenTagId}`, body);
+			onRulesChange(rules.map((r) => (r.then_tag_id === thenTagId ? updated : r)));
+		} catch (e) {
+			error = e instanceof ApiError ? e.message : 'Failed to update rule';
+		} finally {
+			busy = false;
+		}
+	}
+
+	async function removeRule(thenTagId: string) {
+		if (busy) return;
+		busy = true;
+		error = '';
+		try {
+			await api.delete(`/tags/${tagId}/rules/${thenTagId}`);
+			onRulesChange(rules.filter((r) => r.then_tag_id !== thenTagId));
+		} catch (e) {
+			error = e instanceof ApiError ? e.message : 'Failed to remove rule';
+		} finally {
+			busy = false;
+		}
+	}
+</script>
+
+<div class="editor" class:busy>
+	<p class="desc">When this tag is applied, also apply:</p>
+
+	{#if error}
+		<p class="error" role="alert">{error}</p>
+	{/if}
+
+	<!-- Current rules -->
+	{#if rules.length > 0}
+		<div class="rule-list">
+			{#each rules as rule (rule.then_tag_id)}
+				{@const t = tagForId(rule.then_tag_id)}
+				<div class="rule-row" class:inactive={!rule.is_active}>
+					{#if t}
+						<TagBadge tag={t} size="sm" />
+					{:else}
+						<span class="unknown">{rule.then_tag_name ?? rule.then_tag_id}</span>
+					{/if}
+					<button
+						class="toggle-btn"
+						class:active={rule.is_active}
+						onclick={() => toggleRule(rule)}
+						title={rule.is_active ? 'Deactivate rule' : 'Activate rule'}
+						aria-label={rule.is_active ? 'Deactivate rule' : 'Activate rule'}
+					>
+						{#if rule.is_active}
+							<svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+								<circle cx="6" cy="6" r="5" stroke="currentColor" stroke-width="1.5" />
+								<circle cx="6" cy="6" r="2.5" fill="currentColor" />
+							</svg>
+						{:else}
+							<svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+								<circle cx="6" cy="6" r="5" stroke="currentColor" stroke-width="1.5" />
+							</svg>
+						{/if}
+					</button>
+					<button
+						class="remove-btn"
+						onclick={() => removeRule(rule.then_tag_id!)}
+						aria-label="Remove rule">×</button
+					>
+				</div>
+			{/each}
+		</div>
+	{:else}
+		<p class="empty">No rules — when this tag is applied, nothing extra happens.</p>
+	{/if}
+
+	<!-- Add rule -->
+	<div class="add-section">
+		<div class="section-label">Add rule</div>
+		<div class="search-wrap">
+			<input
+				class="search"
+				type="search"
+				placeholder="Search tags to add…"
+				bind:value={search}
+				autocomplete="off"
+			/>
+			{#if search}
+				<button class="search-clear" onclick={() => (search = '')} aria-label="Clear search">
+					<svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+						<path
+							d="M2 2l10 10M12 2L2 12"
+							stroke="currentColor"
+							stroke-width="1.8"
+							stroke-linecap="round"
+						/>
+					</svg>
+				</button>
+			{/if}
+		</div>
+		<div class="tag-pick">
+			{#each filteredTags as t (t.id)}
+				<TagBadge tag={t} size="sm" onclick={() => addRule(t.id!)} />
+			{:else}
+				<span class="empty">{search.trim() ? 'No matching tags' : 'All tags already added'}</span>
+			{/each}
+		</div>
+	</div>
+</div>
+
+<style>
+	.editor {
+		display: flex;
+		flex-direction: column;
+		gap: 8px;
+	}
+
+	.editor.busy {
+		opacity: 0.6;
+		pointer-events: none;
+	}
+
+	.desc {
+		font-size: 0.82rem;
+		color: var(--color-text-muted);
+		margin: 0;
+	}
+
+	.rule-list {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 6px;
+		align-items: center;
+	}
+
+	.rule-row {
+		display: inline-flex;
+		align-items: center;
+		gap: 2px;
+	}
+
+	.rule-row.inactive {
+		opacity: 0.45;
+	}
+
+	.toggle-btn {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		background: none;
+		border: none;
+		color: var(--color-text-muted);
+		cursor: pointer;
+		padding: 2px 3px;
+		border-radius: 3px;
+		line-height: 1;
+	}
+
+	.toggle-btn.active {
+		color: var(--color-accent);
+	}
+
+	.toggle-btn:hover {
+		color: var(--color-text-primary);
+	}
+
+	.remove-btn {
+		background: none;
+		border: none;
+		color: var(--color-text-muted);
+		font-size: 1rem;
+		line-height: 1;
+		cursor: pointer;
+		padding: 1px 3px;
+		border-radius: 3px;
+	}
+
+	.remove-btn:hover {
+		color: var(--color-danger);
+	}
+
+	.unknown {
+		font-size: 0.75rem;
+		color: var(--color-text-muted);
+		font-family: monospace;
+	}
+
+	.section-label {
+		font-size: 0.75rem;
+		font-weight: 600;
+		color: var(--color-text-muted);
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		margin-bottom: 4px;
+	}
+
+	.add-section {
+		display: flex;
+		flex-direction: column;
+		gap: 6px;
+	}
+
+	.search-wrap {
+		position: relative;
+		display: flex;
+		align-items: center;
+	}
+
+	.search {
+		width: 100%;
+		box-sizing: border-box;
+		height: 32px;
+		padding: 0 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-primary);
+		color: var(--color-text-primary);
+		font-size: 0.85rem;
+		font-family: inherit;
+		outline: none;
+	}
+
+	.search:focus {
+		border-color: var(--color-accent);
+	}
+
+	.search-clear {
+		position: absolute;
+		right: 6px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		border: none;
+		background: none;
+		color: var(--color-text-muted);
+		cursor: pointer;
+		padding: 0;
+	}
+
+	.search-clear:hover {
+		color: var(--color-text-primary);
+		background-color: color-mix(in srgb, var(--color-accent) 20%, transparent);
+	}
+
+	.tag-pick {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 5px;
+		max-height: 100px;
+		overflow-y: auto;
+	}
+
+	.empty {
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+		margin: 0;
+	}
+
+	.error {
+		font-size: 0.8rem;
+		color: var(--color-danger);
+		margin: 0;
+	}
+</style>

frontend/src/lib/stores/appSettings.ts

@@ -0,0 +1,28 @@
+import { writable } from 'svelte/store';
+import { browser } from '$app/environment';
+
+export interface AppSettings {
+	fileLoadLimit: number;
+	tagRuleApplyToExisting: boolean;
+}
+
+const DEFAULTS: AppSettings = {
+	fileLoadLimit: 100,
+	tagRuleApplyToExisting: true
+};
+
+function load(): AppSettings {
+	if (!browser) return { ...DEFAULTS };
+	try {
+		const stored = JSON.parse(localStorage.getItem('app-settings') ?? 'null');
+		return stored ? { ...DEFAULTS, ...stored } : { ...DEFAULTS };
+	} catch {
+		return { ...DEFAULTS };
+	}
+}
+
+export const appSettings = writable<AppSettings>(load());
+
+appSettings.subscribe((v) => {
+	if (browser) localStorage.setItem('app-settings', JSON.stringify(v));
+});

frontend/src/lib/stores/auth.ts

@@ -0,0 +1,59 @@
+import { writable, derived } from 'svelte/store';
+
+export interface AuthUser {
+	id: number;
+	name: string;
+	isAdmin: boolean;
+}
+
+export interface AuthState {
+	accessToken: string | null;
+	refreshToken: string | null;
+	user: AuthUser | null;
+}
+
+const initial: AuthState = { accessToken: null, refreshToken: null, user: null };
+
+function loadStored(): AuthState {
+	if (typeof localStorage === 'undefined') return initial;
+	try {
+		return JSON.parse(localStorage.getItem('auth') ?? 'null') ?? initial;
+	} catch {
+		return initial;
+	}
+}
+
+export const authStore = writable<AuthState>(loadStored());
+
+// Persist on change. Compare first so a value that just arrived from another tab
+// (applied by the storage listener below) isn't written straight back, which
+// would risk a storage-event echo between tabs.
+authStore.subscribe((state) => {
+	if (typeof localStorage === 'undefined') return;
+	const serialized = JSON.stringify(state);
+	if (localStorage.getItem('auth') !== serialized) {
+		localStorage.setItem('auth', serialized);
+	}
+});
+
+// Keep tabs in sync. Refresh tokens rotate on every use (each refresh deletes the
+// old session server-side), so when one tab logs in, refreshes, or logs out, the
+// others must pick up the new tokens — or the cleared session — immediately.
+// Otherwise a second tab would later refresh with a token that's already been
+// rotated away and get bounced to the login screen.
+if (typeof window !== 'undefined') {
+	window.addEventListener('storage', (e) => {
+		if (e.key !== 'auth') return;
+		let next: AuthState = initial;
+		if (e.newValue) {
+			try {
+				next = (JSON.parse(e.newValue) as AuthState) ?? initial;
+			} catch {
+				next = initial;
+			}
+		}
+		authStore.set(next);
+	});
+}
+
+export const isAuthenticated = derived(authStore, ($auth) => !!$auth.accessToken);

frontend/src/lib/stores/listScroll.ts

@@ -0,0 +1,19 @@
+// Reapply a restored scroll offset to a list's scroller, retrying across frames
+// because the list may not be laid out yet right after a cache rehydrate (and
+// SvelteKit resets scroll to the top on navigation, so this has to win after).
+export function restoreListScroll(getEl: () => HTMLElement | undefined, top: number): void {
+	let tries = 12;
+	const apply = () => {
+		const el = getEl();
+		if (!el) {
+			if (tries-- > 0) requestAnimationFrame(apply);
+			return;
+		}
+		if (el.scrollHeight > top + el.clientHeight || tries-- <= 0) {
+			el.scrollTop = top;
+			return;
+		}
+		requestAnimationFrame(apply);
+	};
+	requestAnimationFrame(apply);
+}

frontend/src/lib/stores/sectionCache.ts

@@ -0,0 +1,47 @@
+// In-memory, per-section view cache. When you leave a list (Files, Tags, …) for
+// another section and come back, the page restores its loaded items, pagination
+// cursors and scroll position from here instead of refetching from scratch.
+//
+// Kept deliberately simple: a plain module-level Map that lives for the session.
+// No TTL — a snapshot is taken from the page's current state on the way out, so
+// it already reflects local mutations (deletes, uploads, tag edits). It is
+// dropped on a full reload, and each page validates the snapshot's `resetKey`
+// (sort/filter/search) before trusting it, so a stale query never restores.
+
+export type SectionKey = 'files' | 'tags' | 'categories' | 'pools';
+
+/** Snapshot shape shared by the offset-paginated lists (tags/categories/pools). */
+export interface OffsetListSnapshot<T> {
+	/** sort|order|search at capture — guards against restoring a different query. */
+	resetKey: string;
+	search: string;
+	items: T[];
+	total: number;
+	offset: number;
+}
+
+interface Snapshot<T> {
+	/** Scroll offset of the list's scroller at capture time. */
+	scrollTop: number;
+	/** Page-specific state blob; opaque to this module. */
+	data: T;
+	savedAt: number;
+}
+
+const cache = new Map<SectionKey, Snapshot<unknown>>();
+
+export function saveSection<T>(key: SectionKey, scrollTop: number, data: T): void {
+	cache.set(key, { scrollTop, data, savedAt: Date.now() });
+}
+
+/** Read and remove a section's snapshot (restore consumes it). */
+export function takeSection<T>(key: SectionKey): { scrollTop: number; data: T } | null {
+	const snap = cache.get(key) as Snapshot<T> | undefined;
+	if (!snap) return null;
+	cache.delete(key);
+	return { scrollTop: snap.scrollTop, data: snap.data };
+}
+
+export function clearSection(key: SectionKey): void {
+	cache.delete(key);
+}

frontend/src/lib/stores/selection.ts

@@ -0,0 +1,65 @@
+import { writable, derived } from 'svelte/store';
+
+interface SelectionState {
+	active: boolean;
+	ids: Set<string>;
+}
+
+function createSelectionStore() {
+	const { subscribe, update, set } = writable<SelectionState>({
+		active: false,
+		ids: new Set()
+	});
+
+	return {
+		subscribe,
+
+		enter() {
+			update((s) => ({ ...s, active: true }));
+		},
+
+		exit() {
+			set({ active: false, ids: new Set() });
+		},
+
+		toggle(id: string) {
+			update((s) => {
+				const ids = new Set(s.ids);
+				if (ids.has(id)) {
+					ids.delete(id);
+				} else {
+					ids.add(id);
+				}
+				// Exit selection mode automatically when last item is deselected
+				const active = ids.size > 0;
+				return { active, ids };
+			});
+		},
+
+		select(id: string) {
+			update((s) => {
+				const ids = new Set(s.ids);
+				ids.add(id);
+				return { active: true, ids };
+			});
+		},
+
+		deselect(id: string) {
+			update((s) => {
+				const ids = new Set(s.ids);
+				ids.delete(id);
+				const active = ids.size > 0;
+				return { active, ids };
+			});
+		},
+
+		clear() {
+			set({ active: false, ids: new Set() });
+		}
+	};
+}
+
+export const selectionStore = createSelectionStore();
+
+export const selectionCount = derived(selectionStore, ($s) => $s.ids.size);
+export const selectionActive = derived(selectionStore, ($s) => $s.active);

frontend/src/lib/stores/sorting.ts

@@ -0,0 +1,58 @@
+import { writable } from 'svelte/store';
+import { browser } from '$app/environment';
+
+export type FileSortField = 'content_datetime' | 'created' | 'original_name' | 'mime';
+export type TagSortField = 'name' | 'color' | 'category_name' | 'created';
+export type SortOrder = 'asc' | 'desc';
+
+export interface SortState<F extends string> {
+	sort: F;
+	order: SortOrder;
+}
+
+function makeSortStore<F extends string>(key: string, defaults: SortState<F>) {
+	const stored = browser ? localStorage.getItem(key) : null;
+	const initial: SortState<F> = stored ? (JSON.parse(stored) as SortState<F>) : defaults;
+	const store = writable<SortState<F>>(initial);
+
+	store.subscribe((v) => {
+		if (browser) localStorage.setItem(key, JSON.stringify(v));
+	});
+
+	return {
+		subscribe: store.subscribe,
+		setSort(sort: F) {
+			store.update((s) => ({ ...s, sort }));
+		},
+		setOrder(order: SortOrder) {
+			store.update((s) => ({ ...s, order }));
+		},
+		toggleOrder() {
+			store.update((s) => ({ ...s, order: s.order === 'asc' ? 'desc' : 'asc' }));
+		}
+	};
+}
+
+export const fileSorting = makeSortStore<FileSortField>('sort:files', {
+	sort: 'created',
+	order: 'desc'
+});
+
+export const tagSorting = makeSortStore<TagSortField>('sort:tags', {
+	sort: 'created',
+	order: 'desc'
+});
+
+export type CategorySortField = 'name' | 'color' | 'created';
+
+export const categorySorting = makeSortStore<CategorySortField>('sort:categories', {
+	sort: 'name',
+	order: 'asc'
+});
+
+export type PoolSortField = 'name' | 'created';
+
+export const poolSorting = makeSortStore<PoolSortField>('sort:pools', {
+	sort: 'created',
+	order: 'desc'
+});

frontend/src/lib/stores/theme.ts

@@ -0,0 +1,29 @@
+import { writable } from 'svelte/store';
+import { browser } from '$app/environment';
+
+type Theme = 'dark' | 'light';
+
+function loadTheme(): Theme {
+	if (!browser) return 'dark';
+	return (localStorage.getItem('theme') as Theme) ?? 'dark';
+}
+
+function applyTheme(theme: Theme) {
+	if (!browser) return;
+	if (theme === 'light') {
+		document.documentElement.setAttribute('data-theme', 'light');
+	} else {
+		document.documentElement.removeAttribute('data-theme');
+	}
+}
+
+export const themeStore = writable<Theme>(loadTheme());
+
+themeStore.subscribe((theme) => {
+	applyTheme(theme);
+	if (browser) localStorage.setItem('theme', theme);
+});
+
+export function toggleTheme() {
+	themeStore.update((t) => (t === 'dark' ? 'light' : 'dark'));
+}

frontend/src/lib/utils/dsl.ts

@@ -0,0 +1,39 @@
+/**
+ * Filter DSL utilities.
+ *
+ * Token format (comma-separated inside braces):
+ *   t=<uuid>        — has tag
+ *   m=<mime>        — exact MIME
+ *   m~<pattern>     — MIME LIKE pattern
+ *   (  )  &  |  !  — grouping / boolean operators
+ *
+ * Example: {t=uuid1,&,!,t=uuid2}  → has tag1 AND NOT tag2
+ */
+
+/** Build the filter query string value from an ordered token list. */
+export function buildDslFilter(tokens: string[]): string | null {
+	if (tokens.length === 0) return null;
+	return '{' + tokens.join(',') + '}';
+}
+
+/** Parse the filter query string value back into a token list. */
+export function parseDslFilter(value: string | null): string[] {
+	if (!value) return [];
+	const inner = value.replace(/^\{/, '').replace(/\}$/, '').trim();
+	if (!inner) return [];
+	return inner.split(',');
+}
+
+/** Return a human-readable label for a single DSL token (for display). */
+export function tokenLabel(token: string, tagNames: Map<string, string>): string {
+	if (token === '&') return 'AND';
+	if (token === '|') return 'OR';
+	if (token === '!') return 'NOT';
+	if (token === '(') return '(';
+	if (token === ')') return ')';
+	if (token.startsWith('t=')) {
+		const id = token.slice(2);
+		return tagNames.get(id) ?? token;
+	}
+	return token;
+}

frontend/src/lib/utils/pwa.ts

@@ -0,0 +1,17 @@
+/**
+ * Unregisters all service workers and clears all caches, then reloads.
+ * Use this when the app feels stale or to force a clean re-fetch of all assets.
+ */
+export async function resetPwa(): Promise<void> {
+	if ('serviceWorker' in navigator) {
+		const registrations = await navigator.serviceWorker.getRegistrations();
+		await Promise.all(registrations.map((r) => r.unregister()));
+	}
+	if ('caches' in window) {
+		const keys = await caches.keys();
+		await Promise.all(keys.map((k) => caches.delete(k)));
+	}
+	// Hard reload so the page (and a fresh service worker, if still installed)
+	// re-fetches everything from the network instead of the now-cleared cache.
+	location.reload();
+}

frontend/src/routes/+layout.svelte

@@ -1,11 +1,326 @@
 <script lang="ts">
-	import favicon from '$lib/assets/favicon.svg';
+	import '../app.css';
+	import { page } from '$app/stores';
+	import { afterNavigate, goto } from '$app/navigation';
+	import { themeStore, toggleTheme } from '$lib/stores/theme';
+	import KeyboardHelp from '$lib/components/layout/KeyboardHelp.svelte';
 
 	let { children } = $props();
+
+	const navItems = [
+		{
+			href: '/categories',
+			label: 'Categories',
+			match: '/categories'
+		},
+		{
+			href: '/tags',
+			label: 'Tags',
+			match: '/tags'
+		},
+		{
+			href: '/files',
+			label: 'Files',
+			match: '/files'
+		},
+		{
+			href: '/pools',
+			label: 'Pools',
+			match: '/pools'
+		},
+		{
+			href: '/settings',
+			label: 'Settings',
+			match: '/settings'
+		}
+	];
+
+	const isLogin = $derived($page.url.pathname === '/login');
+	const isAdmin = $derived($page.url.pathname.startsWith('/admin'));
+
+	// Remember the last list URL (with its query — filter/sort) per section, so
+	// tapping a nav item returns you to where you left off rather than the bare
+	// root. The root layout never unmounts, so this map persists across the whole
+	// session. Only the section's list root is recorded (e.g. /files, not
+	// /files/<id> or /files/trash) — the tab should reopen the list, not a
+	// sub-screen or the viewer.
+	let lastUrl = $state<Record<string, string>>({});
+
+	afterNavigate((nav) => {
+		const url = nav.to?.url;
+		if (!url) return;
+		const item = navItems.find((it) => it.match === url.pathname);
+		if (item) lastUrl[item.match] = url.pathname + url.search;
+	});
+
+	// ---- Global keyboard navigation -----------------------------------------
+	let helpOpen = $state(false);
+
+	// g-then-letter and 1–5 jump between sections; both honour the remembered
+	// per-section URL so you land back on the same filter/scroll. Keyed by
+	// KeyboardEvent.code (physical key) so the shortcuts work the same on any
+	// layout — on a Russian layout the `f` key still triggers Files, etc.
+	const G_MAP: Record<string, string> = {
+		KeyC: '/categories',
+		KeyT: '/tags',
+		KeyF: '/files',
+		KeyP: '/pools',
+		KeyS: '/settings'
+	};
+	const NUM_MAP = navItems.map((it) => it.match); // 1→categories … 5→settings
+
+	let pendingG = false;
+	let gTimer: ReturnType<typeof setTimeout> | undefined;
+
+	function go(match: string) {
+		goto(lastUrl[match] ?? match);
+	}
+
+	function isEditable(t: EventTarget | null): boolean {
+		return (
+			t instanceof HTMLElement &&
+			(t.isContentEditable || ['INPUT', 'TEXTAREA', 'SELECT'].includes(t.tagName))
+		);
+	}
+
+	function onGlobalKey(e: KeyboardEvent) {
+		if (helpOpen && e.key === 'Escape') {
+			helpOpen = false;
+			return;
+		}
+		// Stay out of the way while typing or when a browser/OS combo is held.
+		if (isEditable(e.target) || e.metaKey || e.ctrlKey || e.altKey) return;
+		if (isLogin) return;
+
+		// Help: `?` by character, or Shift+/ by position (covers non-US layouts).
+		if (e.key === '?' || (e.code === 'Slash' && e.shiftKey)) {
+			helpOpen = !helpOpen;
+			e.preventDefault();
+			return;
+		}
+
+		// Focus the page's search box. Pages with a persistent one (Tags/Categories/
+		// Pools) are handled here; Files has no always-on input, so its own handler
+		// opens the filter instead. Match `/` by character or by Slash position.
+		if (!e.shiftKey && (e.key === '/' || e.code === 'Slash')) {
+			const input = document.querySelector<HTMLInputElement>('input[type="search"]');
+			if (input) {
+				e.preventDefault();
+				input.focus();
+			}
+			return;
+		}
+
+		// The remaining shortcuts are unshifted letters/digits, matched by physical
+		// position so the layout (Latin or not) doesn't matter.
+		if (e.shiftKey) return;
+
+		if (pendingG) {
+			pendingG = false;
+			clearTimeout(gTimer);
+			const dest = G_MAP[e.code];
+			if (dest) {
+				e.preventDefault();
+				go(dest);
+			}
+			return;
+		}
+		if (e.code === 'KeyG') {
+			pendingG = true;
+			clearTimeout(gTimer);
+			gTimer = setTimeout(() => (pendingG = false), 1000);
+			return;
+		}
+		const digit = /^(?:Digit|Numpad)([1-5])$/.exec(e.code);
+		if (digit) {
+			e.preventDefault();
+			go(NUM_MAP[Number(digit[1]) - 1]);
+		}
+	}
 </script>
 
-<svelte:head>
+<svelte:window onkeydown={onGlobalKey} />
-	<link rel="icon" href={favicon} />
-</svelte:head>
 
 {@render children()}
+
+{#if helpOpen}
+	<KeyboardHelp onClose={() => (helpOpen = false)} />
+{/if}
+
+{#if !isLogin && !isAdmin}
+	<footer>
+		{#each navItems as item}
+			{@const active = $page.url.pathname.startsWith(item.match)}
+			<a
+				href={lastUrl[item.match] ?? item.href}
+				class="nav"
+				class:curr={active}
+				aria-label={item.label}
+			>
+				{#if item.label === 'Categories'}
+					<svg
+						width="24"
+						height="24"
+						viewBox="0 0 24 24"
+						fill="none"
+						xmlns="http://www.w3.org/2000/svg"
+						aria-hidden="true"
+					>
+						<path
+							d="M18.875 9.25C21.1532 9.25 23 7.40317 23 5.125C23 2.84683 21.1532 1 18.875 1C16.5968 1 14.75 2.84683 14.75 5.125C14.75 7.40317 16.5968 9.25 18.875 9.25Z"
+							stroke="currentColor"
+							stroke-width="1.5"
+							stroke-linecap="round"
+							stroke-linejoin="round"
+						/>
+						<path
+							d="M5.125 23C7.40317 23 9.25 21.1532 9.25 18.875C9.25 16.5968 7.40317 14.75 5.125 14.75C2.84683 14.75 1 16.5968 1 18.875C1 21.1532 2.84683 23 5.125 23Z"
+							stroke="currentColor"
+							stroke-width="1.5"
+							stroke-linecap="round"
+							stroke-linejoin="round"
+						/>
+						<path
+							d="M14.75 14.75H23V21.625C23 21.9897 22.8551 22.3394 22.5973 22.5973C22.3394 22.8551 21.9897 23 21.625 23H16.125C15.7603 23 15.4106 22.8551 15.1527 22.5973C14.8949 22.3394 14.75 21.9897 14.75 21.625V14.75ZM1 1H9.25V7.875C9.25 8.23967 9.10513 8.58941 8.84727 8.84727C8.58941 9.10513 8.23967 9.25 7.875 9.25H2.375C2.01033 9.25 1.66059 9.10513 1.40273 8.84727C1.14487 8.58941 1 8.23967 1 7.875V1Z"
+							stroke="currentColor"
+							stroke-width="1.5"
+							stroke-linecap="round"
+							stroke-linejoin="round"
+						/>
+					</svg>
+				{:else if item.label === 'Tags'}
+					<svg
+						width="24"
+						height="24"
+						viewBox="0 0 24 24"
+						fill="none"
+						xmlns="http://www.w3.org/2000/svg"
+						aria-hidden="true"
+					>
+						<path
+							d="M4.00067 16.5511C2.30116 14.8505 1.45086 14.0013 1.13515 12.8979C0.818352 11.7946 1.08895 10.6231 1.63016 8.28122L1.94146 6.93041C2.39576 4.9592 2.62346 3.97359 3.29777 3.29819C3.97317 2.62388 4.95878 2.39618 6.92999 1.94188L8.2808 1.62947C10.6238 1.08937 11.7942 0.818769 12.8975 1.13447C14.0008 1.45127 14.85 2.30158 16.5496 4.00109L18.5626 6.0141C21.5227 8.97312 23 10.4515 23 12.2885C23 14.1267 21.5216 15.6051 18.5637 18.563C15.6046 21.522 14.1262 23.0004 12.2881 23.0004C10.4511 23.0004 8.97161 21.522 6.01369 18.5641L4.00067 16.5511Z"
+							stroke="currentColor"
+							stroke-width="1.5"
+						/>
+						<path
+							d="M9.82325 10.1229C10.6824 9.26375 10.6824 7.87077 9.82325 7.01161C8.96409 6.15246 7.57112 6.15246 6.71196 7.01162C5.8528 7.87077 5.8528 9.26375 6.71196 10.1229C7.57112 10.9821 8.96409 10.9821 9.82325 10.1229Z"
+							stroke="currentColor"
+							stroke-width="1.5"
+						/>
+						<path
+							d="M11.4962 19.1504L19.1731 11.4724"
+							stroke="currentColor"
+							stroke-width="1.5"
+							stroke-linecap="round"
+						/>
+					</svg>
+				{:else if item.label === 'Files'}
+					<svg
+						width="22"
+						height="22"
+						viewBox="0 0 22 22"
+						fill="none"
+						xmlns="http://www.w3.org/2000/svg"
+						aria-hidden="true"
+					>
+						<path
+							d="M13.0465 20.4651H8.95346V22H13.0465V20.4651ZM1.53488 13.0465V8.95352H1.29521e-06V13.0465H1.53488ZM20.4651 12.5994V13.0465H21.9999V12.5994H20.4651ZM13.9582 3.43921L18.0092 7.08506L19.0356 5.94311L14.9855 2.29726L13.9582 3.43921ZM21.9999 12.5994C21.9999 10.8711 22.0153 9.77621 21.5804 8.79798L20.1775 9.42319C20.4497 10.0351 20.4651 10.736 20.4651 12.5994H21.9999ZM18.0092 7.08506C19.3937 8.33138 19.9053 8.81231 20.1775 9.42319L21.5804 8.79798C21.1445 7.81873 20.3208 7.09938 19.0356 5.94311L18.0092 7.08506ZM8.98416 1.53494C10.6029 1.53494 11.2138 1.54722 11.7572 1.75596L12.3077 0.323405C11.4359 -0.012222 10.4863 5.70826e-05 8.98416 5.70826e-05V1.53494ZM14.9855 2.29828C13.8743 1.29856 13.1795 0.656985 12.3077 0.323405L11.7582 1.75596C12.3026 1.9647 12.761 2.36172 13.9582 3.43921L14.9855 2.29828ZM8.95346 20.4651C7.00212 20.4651 5.61664 20.4631 4.56371 20.3219C3.53534 20.1837 2.94185 19.9238 2.50902 19.491L1.42437 20.5756C2.18976 21.3431 3.16083 21.6818 4.36008 21.8434C5.53682 22.002 7.04612 22 8.95346 22V20.4651ZM1.29521e-06 13.0465C1.29521e-06 14.9539 -0.00204521 16.4621 0.156559 17.6399C0.318233 18.8392 0.657953 19.8102 1.42335 20.5766L2.50799 19.492C2.07618 19.0581 1.81627 18.4646 1.67814 17.4353C1.53693 16.3844 1.53488 14.9979 1.53488 13.0465H1.29521e-06ZM13.0465 22C14.9538 22 16.4621 22.002 17.6399 21.8434C18.8391 21.6818 19.8102 21.342 20.5766 20.5766L19.4919 19.492C19.0581 19.9238 18.4646 20.1837 17.4352 20.3219C16.3843 20.4631 14.9978 20.4651 13.0465 20.4651V22ZM20.4651 13.0465C20.4651 14.9979 20.463 16.3844 20.3218 17.4363C20.1837 18.4647 19.9238 19.0581 19.4909 19.491L20.5756 20.5756C21.343 19.8102 21.6817 18.8392 21.8434 17.6399C22.002 16.4632 21.9999 14.9539 21.9999 13.0465H20.4651ZM1.53488 8.95352C1.53488 7.00217 1.53693 5.61669 1.67814 4.56376C1.81627 3.53539 2.07618 2.94191 2.50902 2.50907L1.42437 1.42442C0.656929 2.18982 0.318233 3.16088 0.156559 4.36014C-0.00204521 5.53688 1.29521e-06 7.04617 1.29521e-06 8.95352H1.53488ZM8.98416 5.70826e-05C7.06556 5.70826e-05 5.55012 -0.00198942 4.36827 0.156615C3.1639 0.318289 2.18976 0.658009 1.42335 1.4234L2.50799 2.50805C2.94185 2.07624 3.53636 1.81633 4.57189 1.67819C5.62891 1.53698 7.02258 1.53494 8.98416 1.53494V5.70826e-05Z"
+							fill="currentColor"
+						/>
+						<path
+							d="M12.0232 1.27905V3.83718C12.0232 6.24899 12.0232 7.45541 12.7722 8.20443C13.5212 8.95345 14.7276 8.95345 17.1395 8.95345H21.2325"
+							stroke="currentColor"
+							stroke-width="1.5"
+						/>
+					</svg>
+				{:else if item.label === 'Pools'}
+					<svg
+						width="22"
+						height="22"
+						viewBox="0 0 22 22"
+						fill="none"
+						xmlns="http://www.w3.org/2000/svg"
+						aria-hidden="true"
+					>
+						<path
+							d="M6.07102 2.7508H4.64702C4.80588 1.9743 5.22797 1.27646 5.84196 0.775241C6.45595 0.274027 7.22417 0.000183205 8.01676 0H16.7276C18.1259 0 19.467 0.55548 20.4558 1.54424C21.4445 2.533 22 3.87405 22 5.27237V13.9832C22 14.7743 21.7273 15.5411 21.2279 16.1546C20.7285 16.7681 20.033 17.1907 19.2584 17.3511V15.9253C19.6583 15.7816 20.0042 15.518 20.2487 15.1704C20.4932 14.8228 20.6245 14.4082 20.6246 13.9832V5.27237C20.6246 4.23883 20.214 3.24762 19.4832 2.5168C18.7524 1.78597 17.7612 1.3754 16.7276 1.3754H8.01676C7.59001 1.37527 7.17373 1.50748 6.82525 1.75381C6.47678 2.00014 6.21327 2.34846 6.07102 2.7508ZM3.4385 3.66774C2.52656 3.66774 1.65196 4.03001 1.00711 4.67485C0.36227 5.3197 0 6.19429 0 7.10624V18.5679C0 19.4799 0.36227 20.3545 1.00711 20.9993C1.65196 21.6442 2.52656 22.0064 3.4385 22.0064H14.9002C15.8121 22.0064 16.6867 21.6442 17.3316 20.9993C17.9764 20.3545 18.3387 19.4799 18.3387 18.5679V7.10624C18.3387 6.19429 17.9764 5.3197 17.3316 4.67485C16.6867 4.03001 15.8121 3.66774 14.9002 3.66774H3.4385ZM1.3754 7.10624C1.3754 6.55907 1.59276 6.03431 1.97967 5.64741C2.36658 5.2605 2.89133 5.04314 3.4385 5.04314H14.9002C15.4473 5.04314 15.9721 5.2605 16.359 5.64741C16.7459 6.03431 16.9633 6.55907 16.9633 7.10624V18.5679C16.9633 19.1151 16.7459 19.6398 16.359 20.0268C15.9721 20.4137 15.4473 20.631 14.9002 20.631H3.4385C2.89133 20.631 2.36658 20.4137 1.97967 20.0268C1.59276 19.6398 1.3754 19.1151 1.3754 18.5679V7.10624Z"
+							fill="currentColor"
+						/>
+					</svg>
+				{:else if item.label === 'Settings'}
+					<svg
+						width="23"
+						height="24"
+						viewBox="0 0 23 24"
+						fill="none"
+						xmlns="http://www.w3.org/2000/svg"
+						aria-hidden="true"
+					>
+						<path
+							d="M11.371 15.3C13.1935 15.3 14.671 13.8226 14.671 12C14.671 10.1775 13.1935 8.70001 11.371 8.70001C9.54844 8.70001 8.07098 10.1775 8.07098 12C8.07098 13.8226 9.54844 15.3 11.371 15.3Z"
+							stroke="currentColor"
+							stroke-width="1.5"
+						/>
+						<path
+							d="M13.3125 1.1672C12.9088 1 12.3962 1 11.371 1C10.3458 1 9.8332 1 9.4295 1.1672C9.1624 1.27776 8.91971 1.43989 8.7153 1.6443C8.51089 1.84871 8.34877 2.0914 8.2382 2.3585C8.137 2.6038 8.0963 2.8909 8.0809 3.3078C8.07405 3.60919 7.9907 3.90389 7.8387 4.16423C7.68669 4.42456 7.47101 4.642 7.2119 4.7961C6.94889 4.94355 6.65271 5.02171 6.35119 5.02325C6.04967 5.02479 5.75271 4.94965 5.4882 4.8049C5.1186 4.6091 4.8513 4.5013 4.5862 4.4661C4.00795 4.39006 3.42317 4.54674 2.9604 4.9017C2.615 5.169 2.3576 5.6123 1.845 6.5C1.3324 7.3877 1.075 7.831 1.0189 8.2655C0.981102 8.552 1.00012 8.84314 1.07486 9.12228C1.1496 9.40143 1.2786 9.66312 1.4545 9.8924C1.6173 10.1036 1.845 10.2807 2.1981 10.5029C2.7184 10.8296 3.0528 11.3862 3.0528 12C3.0528 12.6138 2.7184 13.1704 2.1981 13.496C1.845 13.7193 1.6162 13.8964 1.4545 14.1076C1.2786 14.3369 1.1496 14.5986 1.07486 14.8777C1.00012 15.1569 0.981102 15.448 1.0189 15.7345C1.0761 16.1679 1.3324 16.6123 1.8439 17.5C2.3576 18.3877 2.6139 18.831 2.9604 19.0983C3.18968 19.2742 3.45137 19.4032 3.73052 19.4779C4.00967 19.5527 4.30081 19.5717 4.5873 19.5339C4.8513 19.4987 5.1186 19.3909 5.4882 19.1951C5.75271 19.0503 6.04967 18.9752 6.35119 18.9767C6.65271 18.9783 6.94889 19.0565 7.2119 19.2039C7.7432 19.5119 8.0589 20.0784 8.0809 20.6922C8.0963 21.1102 8.1359 21.3962 8.2382 21.6415C8.34877 21.9086 8.51089 22.1513 8.7153 22.3557C8.91971 22.5601 9.1624 22.7222 9.4295 22.8328C9.8332 23 10.3458 23 11.371 23C12.3962 23 12.9088 23 13.3125 22.8328C13.5796 22.7222 13.8223 22.5601 14.0267 22.3557C14.2311 22.1513 14.3932 21.9086 14.5038 21.6415C14.605 21.3962 14.6457 21.1102 14.6611 20.6922C14.6831 20.0784 14.9988 19.5108 15.5301 19.2039C15.7931 19.0565 16.0893 18.9783 16.3908 18.9767C16.6923 18.9752 16.9893 19.0503 17.2538 19.1951C17.6234 19.3909 17.8907 19.4987 18.1547 19.5339C18.4412 19.5717 18.7323 19.5527 19.0115 19.4779C19.2906 19.4032 19.5523 19.2742 19.7816 19.0983C20.1281 18.8321 20.3844 18.3877 20.897 17.5C21.4096 16.6123 21.667 16.169 21.7231 15.7345C21.7609 15.448 21.7419 15.1569 21.6672 14.8777C21.5924 14.5986 21.4634 14.3369 21.2875 14.1076C21.1247 13.8964 20.897 13.7193 20.5439 13.4971C20.2862 13.3405 20.0726 13.1209 19.9231 12.859C19.7736 12.5971 19.6931 12.3015 19.6892 12C19.6892 11.3862 20.0236 10.8296 20.5439 10.504C20.897 10.2807 21.1258 10.1036 21.2875 9.8924C21.4634 9.66312 21.5924 9.40143 21.6672 9.12228C21.7419 8.84314 21.7609 8.552 21.7231 8.2655C21.6659 7.8321 21.4096 7.3877 20.8981 6.5C20.3844 5.6123 20.1281 5.169 19.7816 4.9017C19.5523 4.7258 19.2906 4.59679 19.0115 4.52205C18.7323 4.44731 18.4412 4.4283 18.1547 4.4661C17.8907 4.5013 17.6234 4.6091 17.2527 4.8049C16.9883 4.94946 16.6916 5.02449 16.3903 5.02295C16.089 5.02141 15.793 4.94335 15.5301 4.7961C15.271 4.642 15.0553 4.42456 14.9033 4.16423C14.7513 3.90389 14.668 3.60919 14.6611 3.3078C14.6457 2.8898 14.6061 2.6038 14.5038 2.3585C14.3932 2.0914 14.2311 1.84871 14.0267 1.6443C13.8223 1.43989 13.5796 1.27776 13.3125 1.1672Z"
+							stroke="currentColor"
+							stroke-width="1.5"
+						/>
+					</svg>
+				{/if}
+			</a>
+		{/each}
+	</footer>
+{/if}
+
+<style>
+	:global(body) {
+		background-color: var(--color-bg-primary);
+		color: var(--color-text-primary);
+		font-family: var(--font-sans);
+		min-height: 100dvh;
+		display: flex;
+		flex-direction: column;
+	}
+
+	footer {
+		position: fixed;
+		bottom: 0;
+		left: 0;
+		right: 0;
+		display: flex;
+		justify-content: space-between;
+		align-items: center;
+		padding: 10px;
+		background-color: var(--color-nav-bg);
+		backdrop-filter: blur(8px);
+		-webkit-backdrop-filter: blur(8px);
+		z-index: 100;
+	}
+
+	.nav {
+		display: flex;
+		justify-content: center;
+		align-items: center;
+		height: 40px;
+		width: 18vw;
+		border-radius: 10px;
+		color: var(--color-text-muted);
+		text-decoration: none;
+		transition:
+			background-color 0.15s,
+			color 0.15s;
+	}
+
+	.nav:hover,
+	.nav.curr {
+		background-color: var(--color-nav-active);
+		color: var(--color-text-primary);
+	}
+
+	.nav :global(svg) {
+		display: block;
+		height: 28px;
+		width: auto;
+	}
+</style>

frontend/src/routes/+layout.ts

@@ -0,0 +1,16 @@
+import { get } from 'svelte/store';
+import { redirect } from '@sveltejs/kit';
+import { browser } from '$app/environment';
+import { authStore } from '$lib/stores/auth';
+
+export const ssr = false;
+
+export const load = ({ url }: { url: URL }) => {
+	if (!browser) return;
+	if (url.pathname === '/login') return;
+
+	const { accessToken } = get(authStore);
+	if (!accessToken) {
+		redirect(307, '/login');
+	}
+};

frontend/src/routes/+page.svelte

@@ -1,2 +1 @@
-<h1>Welcome to SvelteKit</h1>
+<!-- Root route redirects to /files in +page.ts; nothing is rendered here. -->
-<p>Visit <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> to read the documentation</p>

frontend/src/routes/+page.ts

@@ -0,0 +1,7 @@
+import { redirect } from '@sveltejs/kit';
+
+// The app has no content at the root; send users to the files view (the layout
+// guard redirects to /login first when unauthenticated).
+export const load = () => {
+	redirect(307, '/files');
+};

frontend/src/routes/admin/+layout.svelte

@@ -0,0 +1,119 @@
+<script lang="ts">
+	import { page } from '$app/stores';
+	import { goto } from '$app/navigation';
+
+	let { children } = $props();
+
+	const tabs = [
+		{ href: '/admin/users', label: 'Users' },
+		{ href: '/admin/audit', label: 'Audit log' }
+	];
+</script>
+
+<div class="admin-shell">
+	<nav class="admin-nav">
+		<button class="back-btn" onclick={() => goto('/files')} aria-label="Back to files">
+			<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+				<path
+					d="M10 3L5 8L10 13"
+					stroke="currentColor"
+					stroke-width="1.8"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+				/>
+			</svg>
+		</button>
+		<span class="admin-title">Admin</span>
+		<div class="tabs">
+			{#each tabs as tab}
+				<a href={tab.href} class="tab" class:active={$page.url.pathname.startsWith(tab.href)}
+					>{tab.label}</a
+				>
+			{/each}
+		</div>
+	</nav>
+	<div class="admin-content">
+		{@render children()}
+	</div>
+</div>
+
+<style>
+	.admin-shell {
+		flex: 1;
+		display: flex;
+		flex-direction: column;
+		min-height: 0;
+	}
+
+	.admin-nav {
+		display: flex;
+		align-items: center;
+		gap: 10px;
+		padding: 8px 14px;
+		background-color: var(--color-bg-elevated);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 20%, transparent);
+		flex-shrink: 0;
+	}
+
+	.back-btn {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 28px;
+		height: 28px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 25%, transparent);
+		background: none;
+		color: var(--color-text-muted);
+		cursor: pointer;
+		flex-shrink: 0;
+	}
+
+	.back-btn:hover {
+		color: var(--color-text-primary);
+		border-color: var(--color-accent);
+	}
+
+	.admin-title {
+		font-size: 0.8rem;
+		font-weight: 700;
+		text-transform: uppercase;
+		letter-spacing: 0.08em;
+		color: var(--color-text-muted);
+		flex-shrink: 0;
+	}
+
+	.tabs {
+		display: flex;
+		gap: 2px;
+		margin-left: 8px;
+	}
+
+	.tab {
+		height: 28px;
+		padding: 0 12px;
+		border-radius: 6px;
+		font-size: 0.85rem;
+		font-weight: 500;
+		color: var(--color-text-muted);
+		text-decoration: none;
+		display: flex;
+		align-items: center;
+	}
+
+	.tab:hover {
+		background-color: color-mix(in srgb, var(--color-accent) 12%, transparent);
+		color: var(--color-text-primary);
+	}
+
+	.tab.active {
+		background-color: color-mix(in srgb, var(--color-accent) 20%, transparent);
+		color: var(--color-accent);
+	}
+
+	.admin-content {
+		flex: 1;
+		min-height: 0;
+		overflow-y: auto;
+	}
+</style>

frontend/src/routes/admin/+layout.ts

@@ -0,0 +1,12 @@
+import { get } from 'svelte/store';
+import { redirect } from '@sveltejs/kit';
+import { browser } from '$app/environment';
+import { authStore } from '$lib/stores/auth';
+
+export const load = () => {
+	if (!browser) return;
+	const { user } = get(authStore);
+	if (!user?.isAdmin) {
+		redirect(307, '/files');
+	}
+};

frontend/src/routes/admin/audit/+page.svelte

@@ -0,0 +1,556 @@
+<script lang="ts">
+	import { api, ApiError } from '$lib/api/client';
+	import type { AuditEntry, AuditOffsetPage, User, UserOffsetPage } from '$lib/api/types';
+
+	const LIMIT = 50;
+	const OBJECT_TYPES = ['file', 'tag', 'category', 'pool'];
+	const ACTION_LABELS: Record<string, string> = {
+		// Auth
+		user_login: 'User logged in',
+		user_logout: 'User logged out',
+		// Files
+		file_create: 'File uploaded',
+		file_edit: 'File edited',
+		file_delete: 'File deleted',
+		file_restore: 'File restored',
+		file_permanent_delete: 'File permanently deleted',
+		file_replace: 'File replaced',
+		// Tags
+		tag_create: 'Tag created',
+		tag_edit: 'Tag edited',
+		tag_delete: 'Tag deleted',
+		// Categories
+		category_create: 'Category created',
+		category_edit: 'Category edited',
+		category_delete: 'Category deleted',
+		// Pools
+		pool_create: 'Pool created',
+		pool_edit: 'Pool edited',
+		pool_delete: 'Pool deleted',
+		// Relations
+		file_tag_add: 'Tag added to file',
+		file_tag_remove: 'Tag removed from file',
+		file_pool_add: 'File added to pool',
+		file_pool_remove: 'File removed from pool',
+		// ACL
+		acl_change: 'ACL changed',
+		// Admin
+		user_create: 'User created',
+		user_delete: 'User deleted',
+		user_block: 'User blocked',
+		user_unblock: 'User unblocked',
+		user_role_change: 'User role changed',
+		// Sessions
+		session_terminate: 'Session terminated'
+	};
+
+	// ---- Filters ----
+	let filterUserId = $state('');
+	let filterAction = $state('');
+	let filterObjectType = $state('');
+	let filterObjectId = $state('');
+	let filterFrom = $state('');
+	let filterTo = $state('');
+
+	// ---- Data ----
+	let entries = $state<AuditEntry[]>([]);
+	let total = $state(0);
+	let page = $state(0); // 0-based
+	let loading = $state(false);
+	let error = $state('');
+	let initialLoaded = $state(false);
+
+	let totalPages = $derived(Math.max(1, Math.ceil(total / LIMIT)));
+
+	// ---- Users for filter dropdown ----
+	let allUsers = $state<User[]>([]);
+	$effect(() => {
+		api
+			.get<UserOffsetPage>('/users?limit=200')
+			.then((r) => {
+				allUsers = r.items ?? [];
+			})
+			.catch(() => {});
+	});
+
+	// Unknown action types not in ACTION_LABELS (server may add new ones)
+	let knownActions = $derived(
+		[...new Set(entries.map((e) => e.action).filter(Boolean))].sort() as string[]
+	);
+
+	// ---- Reset on filter change ----
+	let filterKey = $derived(
+		`${filterUserId}|${filterAction}|${filterObjectType}|${filterObjectId}|${filterFrom}|${filterTo}`
+	);
+	let prevFilterKey = $state('');
+
+	$effect(() => {
+		if (filterKey !== prevFilterKey) {
+			prevFilterKey = filterKey;
+			page = 0;
+			initialLoaded = false;
+			error = '';
+		}
+	});
+
+	$effect(() => {
+		if (!initialLoaded && !loading) void load();
+	});
+
+	async function load() {
+		if (loading) return;
+		loading = true;
+		error = '';
+		try {
+			const params = new URLSearchParams({ limit: String(LIMIT), offset: String(page * LIMIT) });
+			if (filterUserId) params.set('user_id', filterUserId);
+			if (filterAction) params.set('action', filterAction);
+			if (filterObjectType) params.set('object_type', filterObjectType);
+			if (filterObjectId.trim()) params.set('object_id', filterObjectId.trim());
+			if (filterFrom) params.set('from', new Date(filterFrom).toISOString());
+			if (filterTo) params.set('to', new Date(filterTo).toISOString());
+
+			const res = await api.get<AuditOffsetPage>(`/audit?${params}`);
+			entries = res.items ?? [];
+			total = res.total ?? entries.length;
+		} catch (e) {
+			error = e instanceof ApiError ? e.message : 'Failed to load audit log';
+		} finally {
+			loading = false;
+			initialLoaded = true;
+		}
+	}
+
+	async function goToPage(p: number) {
+		if (p < 0 || p >= totalPages || p === page) return;
+		page = p;
+		initialLoaded = false;
+	}
+
+	function formatTs(iso: string | undefined | null): string {
+		if (!iso) return '—';
+		const d = new Date(iso);
+		return d.toLocaleString(undefined, {
+			year: 'numeric',
+			month: 'short',
+			day: 'numeric',
+			hour: '2-digit',
+			minute: '2-digit',
+			second: '2-digit'
+		});
+	}
+
+	function actionLabel(action: string | undefined | null): string {
+		if (!action) return '—';
+		return ACTION_LABELS[action] ?? action.replace(/_/g, ' ');
+	}
+
+	function shortId(id: string | undefined | null): string {
+		if (!id) return '—';
+		return id.slice(-8);
+	}
+
+	function clearFilters() {
+		filterUserId = '';
+		filterAction = '';
+		filterObjectType = '';
+		filterObjectId = '';
+		filterFrom = '';
+		filterTo = '';
+	}
+
+	let filtersActive = $derived(
+		!!(filterUserId || filterAction || filterObjectType || filterObjectId || filterFrom || filterTo)
+	);
+</script>
+
+<svelte:head><title>Audit Log — Admin | Tanabata</title></svelte:head>
+
+<div class="page">
+	<!-- Filters -->
+	<div class="filters">
+		<div class="filters-row">
+			<select class="filter-select" bind:value={filterUserId} title="Filter by user">
+				<option value="">All users</option>
+				{#each allUsers as u (u.id)}
+					<option value={String(u.id)}>{u.name}</option>
+				{/each}
+			</select>
+
+			<select class="filter-select" bind:value={filterAction} title="Filter by action">
+				<option value="">All actions</option>
+				{#each Object.keys(ACTION_LABELS) as a}
+					<option value={a}>{ACTION_LABELS[a]}</option>
+				{/each}
+				{#each knownActions.filter((a) => !(a in ACTION_LABELS)) as a}
+					<option value={a}>{a}</option>
+				{/each}
+			</select>
+
+			<select class="filter-select" bind:value={filterObjectType} title="Filter by object type">
+				<option value="">All objects</option>
+				{#each OBJECT_TYPES as t}
+					<option value={t}>{t}</option>
+				{/each}
+			</select>
+
+			<input
+				class="filter-input"
+				type="text"
+				placeholder="Object ID…"
+				bind:value={filterObjectId}
+				autocomplete="off"
+			/>
+		</div>
+
+		<div class="filters-row">
+			<label class="date-label">
+				From
+				<input class="filter-input date" type="datetime-local" bind:value={filterFrom} />
+			</label>
+			<label class="date-label">
+				To
+				<input class="filter-input date" type="datetime-local" bind:value={filterTo} />
+			</label>
+			{#if filtersActive}
+				<button class="clear-btn" onclick={clearFilters}>Clear filters</button>
+			{/if}
+			<span class="total-hint">{total} entr{total !== 1 ? 'ies' : 'y'}</span>
+		</div>
+	</div>
+
+	<!-- Table -->
+	{#if error}
+		<p class="msg error" role="alert">{error}</p>
+	{:else}
+		<div class="content-area">
+			<div class="table-wrap">
+				<table class="table">
+					<thead>
+						<tr>
+							<th>Time</th>
+							<th>User</th>
+							<th>Action</th>
+							<th>Object</th>
+							<th>ID</th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each entries as e (e.id)}
+							<tr>
+								<td class="ts-cell">{formatTs(e.performed_at)}</td>
+								<td class="user-cell">{e.user_name ?? '—'}</td>
+								<td class="action-cell">
+									<span
+										class="action-tag"
+										class:file={e.object_type === 'file'}
+										class:tag={e.object_type === 'tag'}
+										class:pool={e.object_type === 'pool'}
+										class:cat={e.object_type === 'category'}
+									>
+										{actionLabel(e.action)}
+									</span>
+								</td>
+								<td class="obj-type-cell">{e.object_type ?? '—'}</td>
+								<td class="obj-id-cell" title={e.object_id ?? ''}>{shortId(e.object_id)}</td>
+							</tr>
+						{/each}
+
+						{#if loading}
+							<tr class="loading-row">
+								<td colspan="5">
+									<span class="spinner" role="status" aria-label="Loading"></span>
+								</td>
+							</tr>
+						{/if}
+
+						{#if !loading && initialLoaded && entries.length === 0}
+							<tr>
+								<td colspan="5" class="empty-cell">No entries match the current filters.</td>
+							</tr>
+						{/if}
+					</tbody>
+				</table>
+			</div>
+
+			{#if totalPages > 1}
+				<div class="pagination">
+					<button
+						class="page-btn"
+						onclick={() => goToPage(page - 1)}
+						disabled={page === 0 || loading}
+					>
+						← Prev
+					</button>
+					<span class="page-info">Page {page + 1} of {totalPages}</span>
+					<button
+						class="page-btn"
+						onclick={() => goToPage(page + 1)}
+						disabled={page >= totalPages - 1 || loading}
+					>
+						Next →
+					</button>
+				</div>
+			{/if}
+		</div>
+	{/if}
+</div>
+
+<style>
+	.page {
+		padding: 14px 16px;
+		display: flex;
+		flex-direction: column;
+		gap: 12px;
+		height: 100%;
+		box-sizing: border-box;
+	}
+
+	/* ---- Filters ---- */
+	.filters {
+		display: flex;
+		flex-direction: column;
+		gap: 8px;
+		flex-shrink: 0;
+	}
+
+	.filters-row {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 6px;
+		align-items: center;
+	}
+
+	.filter-select,
+	.filter-input {
+		height: 32px;
+		padding: 0 8px;
+		border-radius: 7px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.82rem;
+		font-family: inherit;
+		outline: none;
+	}
+
+	.filter-select:focus,
+	.filter-input:focus {
+		border-color: var(--color-accent);
+	}
+
+	.filter-input {
+		min-width: 140px;
+	}
+
+	.filter-input.date {
+		min-width: 180px;
+	}
+
+	.date-label {
+		display: flex;
+		align-items: center;
+		gap: 5px;
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+	}
+
+	.clear-btn {
+		height: 30px;
+		padding: 0 12px;
+		border-radius: 7px;
+		border: 1px solid color-mix(in srgb, var(--color-danger) 45%, transparent);
+		background: none;
+		color: var(--color-danger);
+		font-size: 0.8rem;
+		font-family: inherit;
+		cursor: pointer;
+	}
+
+	.clear-btn:hover {
+		background-color: color-mix(in srgb, var(--color-danger) 10%, transparent);
+	}
+
+	.total-hint {
+		font-size: 0.78rem;
+		color: var(--color-text-muted);
+		margin-left: auto;
+	}
+
+	/* ---- Table ---- */
+	.content-area {
+		flex: 1;
+		min-height: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 8px;
+	}
+
+	.table-wrap {
+		flex: 1;
+		min-height: 0;
+		overflow-y: auto;
+		border-radius: 10px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 15%, transparent);
+	}
+
+	.table {
+		width: 100%;
+		border-collapse: collapse;
+		font-size: 0.82rem;
+	}
+
+	.table thead {
+		position: sticky;
+		top: 0;
+		z-index: 1;
+		background-color: var(--color-bg-elevated);
+	}
+
+	.table th {
+		text-align: left;
+		padding: 8px 10px;
+		font-size: 0.72rem;
+		font-weight: 700;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		color: var(--color-text-muted);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 20%, transparent);
+		white-space: nowrap;
+	}
+
+	.table td {
+		padding: 7px 10px;
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 8%, transparent);
+		vertical-align: middle;
+	}
+
+	.table tbody tr:last-child td {
+		border-bottom: none;
+	}
+
+	.table tbody tr:hover td {
+		background-color: color-mix(in srgb, var(--color-accent) 5%, transparent);
+	}
+
+	.ts-cell {
+		white-space: nowrap;
+		color: var(--color-text-muted);
+		font-size: 0.78rem;
+	}
+
+	.user-cell {
+		white-space: nowrap;
+		font-weight: 500;
+	}
+
+	.action-tag {
+		display: inline-block;
+		padding: 2px 7px;
+		border-radius: 4px;
+		font-size: 0.75rem;
+		font-weight: 600;
+		background-color: color-mix(in srgb, var(--color-accent) 12%, transparent);
+		color: var(--color-accent);
+		white-space: nowrap;
+	}
+
+	.action-tag.file {
+		background-color: color-mix(in srgb, var(--color-info) 12%, transparent);
+		color: var(--color-info);
+	}
+	.action-tag.tag {
+		background-color: color-mix(in srgb, #7ecba1 12%, transparent);
+		color: #7ecba1;
+	}
+	.action-tag.pool {
+		background-color: color-mix(in srgb, var(--color-warning) 12%, transparent);
+		color: var(--color-warning);
+	}
+	.action-tag.cat {
+		background-color: color-mix(in srgb, var(--color-danger) 12%, transparent);
+		color: var(--color-danger);
+	}
+
+	.obj-type-cell {
+		color: var(--color-text-muted);
+		text-transform: capitalize;
+		font-size: 0.78rem;
+	}
+
+	.obj-id-cell {
+		color: var(--color-text-muted);
+		font-family: monospace;
+		font-size: 0.78rem;
+	}
+
+	.loading-row td {
+		text-align: center;
+		padding: 16px;
+	}
+
+	.empty-cell {
+		text-align: center;
+		color: var(--color-text-muted);
+		padding: 40px 0;
+	}
+
+	.spinner {
+		display: inline-block;
+		width: 22px;
+		height: 22px;
+		border: 2px solid color-mix(in srgb, var(--color-accent) 25%, transparent);
+		border-top-color: var(--color-accent);
+		border-radius: 50%;
+		animation: spin 0.7s linear infinite;
+	}
+
+	@keyframes spin {
+		to {
+			transform: rotate(360deg);
+		}
+	}
+
+	.pagination {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		gap: 12px;
+		flex-shrink: 0;
+	}
+
+	.page-btn {
+		height: 32px;
+		padding: 0 14px;
+		border-radius: 7px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 35%, transparent);
+		background: none;
+		color: var(--color-text-muted);
+		font-size: 0.82rem;
+		font-family: inherit;
+		cursor: pointer;
+	}
+
+	.page-btn:hover:not(:disabled) {
+		border-color: var(--color-accent);
+		color: var(--color-accent);
+	}
+
+	.page-btn:disabled {
+		opacity: 0.35;
+		cursor: default;
+	}
+
+	.page-info {
+		font-size: 0.82rem;
+		color: var(--color-text-muted);
+		min-width: 100px;
+		text-align: center;
+	}
+
+	.msg.error {
+		font-size: 0.85rem;
+		color: var(--color-danger);
+		margin: 0;
+	}
+</style>

frontend/src/routes/admin/users/+page.svelte

@@ -0,0 +1,458 @@
+<script lang="ts">
+	import { goto } from '$app/navigation';
+	import { api, ApiError } from '$lib/api/client';
+	import ConfirmDialog from '$lib/components/common/ConfirmDialog.svelte';
+	import type { User, UserOffsetPage } from '$lib/api/types';
+
+	const LIMIT = 100;
+
+	let users = $state<User[]>([]);
+	let total = $state(0);
+	let loading = $state(true);
+	let error = $state('');
+
+	// Create form
+	let showCreate = $state(false);
+	let newName = $state('');
+	let newPassword = $state('');
+	let newCanCreate = $state(false);
+	let newIsAdmin = $state(false);
+	let creating = $state(false);
+	let createError = $state('');
+
+	// Delete confirm
+	let confirmDeleteUser = $state<User | null>(null);
+
+	async function load() {
+		loading = true;
+		error = '';
+		try {
+			const res = await api.get<UserOffsetPage>(`/users?limit=${LIMIT}&offset=0`);
+			users = res.items ?? [];
+			total = res.total ?? users.length;
+		} catch (e) {
+			error = e instanceof ApiError ? e.message : 'Failed to load users';
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function createUser() {
+		if (!newName.trim() || !newPassword.trim()) return;
+		creating = true;
+		createError = '';
+		try {
+			const u = await api.post<User>('/users', {
+				name: newName.trim(),
+				password: newPassword.trim(),
+				can_create: newCanCreate,
+				is_admin: newIsAdmin
+			});
+			users = [u, ...users];
+			total++;
+			showCreate = false;
+			newName = '';
+			newPassword = '';
+			newCanCreate = false;
+			newIsAdmin = false;
+		} catch (e) {
+			createError = e instanceof ApiError ? e.message : 'Failed to create user';
+		} finally {
+			creating = false;
+		}
+	}
+
+	async function deleteUser(u: User) {
+		confirmDeleteUser = null;
+		try {
+			await api.delete(`/users/${u.id}`);
+			users = users.filter((x) => x.id !== u.id);
+			total--;
+		} catch {
+			// silently ignore
+		}
+	}
+
+	$effect(() => {
+		void load();
+	});
+</script>
+
+<svelte:head><title>Users — Admin | Tanabata</title></svelte:head>
+
+<div class="page">
+	<div class="toolbar">
+		<span class="count">{total} user{total !== 1 ? 's' : ''}</span>
+		<button class="btn primary" onclick={() => (showCreate = !showCreate)}>
+			{showCreate ? 'Cancel' : '+ New user'}
+		</button>
+	</div>
+
+	{#if showCreate}
+		<div class="create-form">
+			{#if createError}<p class="form-error" role="alert">{createError}</p>{/if}
+			<div class="form-row">
+				<input
+					class="input"
+					type="text"
+					placeholder="Username"
+					bind:value={newName}
+					autocomplete="off"
+				/>
+				<input
+					class="input"
+					type="password"
+					placeholder="Password"
+					bind:value={newPassword}
+					autocomplete="new-password"
+				/>
+			</div>
+			<div class="form-row checks">
+				<label class="check-label">
+					<input type="checkbox" bind:checked={newCanCreate} />
+					Can create
+				</label>
+				<label class="check-label">
+					<input type="checkbox" bind:checked={newIsAdmin} />
+					Admin
+				</label>
+				<button
+					class="btn primary"
+					onclick={createUser}
+					disabled={creating || !newName.trim() || !newPassword.trim()}
+				>
+					{creating ? 'Creating…' : 'Create'}
+				</button>
+			</div>
+		</div>
+	{/if}
+
+	{#if error}
+		<p class="error" role="alert">{error}</p>
+	{:else if loading}
+		<div class="loading"><span class="spinner" role="status" aria-label="Loading"></span></div>
+	{:else if users.length === 0}
+		<p class="empty">No users found.</p>
+	{:else}
+		<table class="table">
+			<thead>
+				<tr>
+					<th>ID</th>
+					<th>Name</th>
+					<th>Role</th>
+					<th>Status</th>
+					<th></th>
+				</tr>
+			</thead>
+			<tbody>
+				{#each users as u (u.id)}
+					<tr class="user-row" class:blocked={u.is_blocked}>
+						<td class="id-cell">{u.id}</td>
+						<td class="name-cell">
+							<button class="name-btn" onclick={() => goto(`/admin/users/${u.id}`)}>
+								{u.name}
+							</button>
+						</td>
+						<td>
+							<span
+								class="badge"
+								class:admin={u.is_admin}
+								class:creator={!u.is_admin && u.can_create}
+							>
+								{u.is_admin ? 'Admin' : u.can_create ? 'Creator' : 'Viewer'}
+							</span>
+						</td>
+						<td>
+							{#if u.is_blocked}
+								<span class="badge blocked">Blocked</span>
+							{:else}
+								<span class="badge active">Active</span>
+							{/if}
+						</td>
+						<td class="actions-cell">
+							<button class="icon-btn" onclick={() => goto(`/admin/users/${u.id}`)} title="Edit">
+								<svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+									<path
+										d="M9.5 2.5l2 2-7 7H2.5v-2l7-7z"
+										stroke="currentColor"
+										stroke-width="1.4"
+										stroke-linejoin="round"
+									/>
+								</svg>
+							</button>
+							<button
+								class="icon-btn danger"
+								onclick={() => (confirmDeleteUser = u)}
+								title="Delete"
+							>
+								<svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+									<path
+										d="M2 4h10M5 4V2.5h4V4M5.5 6.5v4M8.5 6.5v4M3 4l.8 7.5h6.4L11 4"
+										stroke="currentColor"
+										stroke-width="1.4"
+										stroke-linecap="round"
+										stroke-linejoin="round"
+									/>
+								</svg>
+							</button>
+						</td>
+					</tr>
+				{/each}
+			</tbody>
+		</table>
+	{/if}
+</div>
+
+{#if confirmDeleteUser}
+	<ConfirmDialog
+		message="Delete user &ldquo;{confirmDeleteUser.name}&rdquo;? This cannot be undone."
+		confirmLabel="Delete"
+		danger
+		onConfirm={() => deleteUser(confirmDeleteUser!)}
+		onCancel={() => (confirmDeleteUser = null)}
+	/>
+{/if}
+
+<style>
+	.page {
+		padding: 16px;
+		max-width: 760px;
+		margin: 0 auto;
+		display: flex;
+		flex-direction: column;
+		gap: 14px;
+	}
+
+	.toolbar {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+	}
+
+	.count {
+		font-size: 0.85rem;
+		color: var(--color-text-muted);
+	}
+
+	.create-form {
+		background-color: var(--color-bg-elevated);
+		border-radius: 10px;
+		padding: 14px;
+		display: flex;
+		flex-direction: column;
+		gap: 10px;
+	}
+
+	.form-row {
+		display: flex;
+		gap: 8px;
+		flex-wrap: wrap;
+	}
+
+	.form-row.checks {
+		align-items: center;
+	}
+
+	.input {
+		flex: 1;
+		min-width: 140px;
+		height: 34px;
+		padding: 0 10px;
+		border-radius: 7px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-primary);
+		color: var(--color-text-primary);
+		font-size: 0.875rem;
+		font-family: inherit;
+		outline: none;
+	}
+
+	.input:focus {
+		border-color: var(--color-accent);
+	}
+
+	.check-label {
+		display: flex;
+		align-items: center;
+		gap: 5px;
+		font-size: 0.85rem;
+		cursor: pointer;
+		user-select: none;
+	}
+
+	.form-error {
+		font-size: 0.82rem;
+		color: var(--color-danger);
+		margin: 0;
+	}
+
+	.btn {
+		height: 32px;
+		padding: 0 14px;
+		border-radius: 7px;
+		border: none;
+		font-size: 0.85rem;
+		font-family: inherit;
+		font-weight: 600;
+		cursor: pointer;
+		white-space: nowrap;
+	}
+
+	.btn:disabled {
+		opacity: 0.5;
+		cursor: default;
+	}
+
+	.btn.primary {
+		background-color: var(--color-accent);
+		color: #fff;
+	}
+
+	.btn.primary:hover:not(:disabled) {
+		background-color: var(--color-accent-hover);
+	}
+
+	.table {
+		width: 100%;
+		border-collapse: collapse;
+		font-size: 0.875rem;
+	}
+
+	.table th {
+		text-align: left;
+		padding: 6px 10px;
+		font-size: 0.75rem;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		color: var(--color-text-muted);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 20%, transparent);
+	}
+
+	.table td {
+		padding: 9px 10px;
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 10%, transparent);
+		vertical-align: middle;
+	}
+
+	.user-row.blocked td {
+		opacity: 0.55;
+	}
+
+	.id-cell {
+		color: var(--color-text-muted);
+		font-size: 0.8rem;
+		width: 40px;
+	}
+
+	.name-btn {
+		background: none;
+		border: none;
+		color: var(--color-text-primary);
+		font-size: inherit;
+		font-family: inherit;
+		cursor: pointer;
+		padding: 0;
+		font-weight: 500;
+	}
+
+	.name-btn:hover {
+		color: var(--color-accent);
+		text-decoration: underline;
+	}
+
+	.badge {
+		display: inline-block;
+		font-size: 0.72rem;
+		font-weight: 700;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+		padding: 2px 7px;
+		border-radius: 4px;
+		background-color: color-mix(in srgb, var(--color-accent) 15%, transparent);
+		color: var(--color-text-muted);
+	}
+
+	.badge.admin {
+		background-color: color-mix(in srgb, var(--color-warning) 20%, transparent);
+		color: var(--color-warning);
+	}
+
+	.badge.creator {
+		background-color: color-mix(in srgb, var(--color-info) 15%, transparent);
+		color: var(--color-info);
+	}
+
+	.badge.active {
+		background-color: color-mix(in srgb, #7ecba1 15%, transparent);
+		color: #7ecba1;
+	}
+
+	.badge.blocked {
+		background-color: color-mix(in srgb, var(--color-danger) 15%, transparent);
+		color: var(--color-danger);
+	}
+
+	.actions-cell {
+		display: flex;
+		gap: 4px;
+		justify-content: flex-end;
+	}
+
+	.icon-btn {
+		width: 28px;
+		height: 28px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 25%, transparent);
+		background: none;
+		color: var(--color-text-muted);
+		cursor: pointer;
+	}
+
+	.icon-btn:hover {
+		color: var(--color-text-primary);
+		border-color: var(--color-accent);
+	}
+
+	.icon-btn.danger:hover {
+		color: var(--color-danger);
+		border-color: var(--color-danger);
+	}
+
+	.loading {
+		display: flex;
+		justify-content: center;
+		padding: 40px;
+	}
+
+	.spinner {
+		display: block;
+		width: 28px;
+		height: 28px;
+		border: 3px solid color-mix(in srgb, var(--color-accent) 25%, transparent);
+		border-top-color: var(--color-accent);
+		border-radius: 50%;
+		animation: spin 0.7s linear infinite;
+	}
+
+	@keyframes spin {
+		to {
+			transform: rotate(360deg);
+		}
+	}
+
+	.error,
+	.empty {
+		font-size: 0.875rem;
+		color: var(--color-text-muted);
+		text-align: center;
+		padding: 40px 0;
+	}
+
+	.error {
+		color: var(--color-danger);
+	}
+</style>

frontend/src/routes/admin/users/[id]/+page.svelte

@@ -0,0 +1,371 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { goto } from '$app/navigation';
+	import { api, ApiError } from '$lib/api/client';
+	import ConfirmDialog from '$lib/components/common/ConfirmDialog.svelte';
+	import type { User } from '$lib/api/types';
+
+	let userId = $derived(page.params.id);
+
+	let user = $state<User | null>(null);
+	let loading = $state(true);
+	let error = $state('');
+	let saving = $state(false);
+	let saveError = $state('');
+	let saveSuccess = $state(false);
+	let confirmDelete = $state(false);
+	let deleting = $state(false);
+
+	// editable fields
+	let isAdmin = $state(false);
+	let canCreate = $state(false);
+	let isBlocked = $state(false);
+
+	$effect(() => {
+		const id = userId;
+		loading = true;
+		error = '';
+		void api
+			.get<User>(`/users/${id}`)
+			.then((u) => {
+				user = u;
+				isAdmin = u.is_admin ?? false;
+				canCreate = u.can_create ?? false;
+				isBlocked = u.is_blocked ?? false;
+			})
+			.catch((e) => {
+				error = e instanceof ApiError ? e.message : 'Failed to load user';
+			})
+			.finally(() => {
+				loading = false;
+			});
+	});
+
+	async function save() {
+		if (saving || !user) return;
+		saving = true;
+		saveError = '';
+		saveSuccess = false;
+		try {
+			const updated = await api.patch<User>(`/users/${user.id}`, {
+				is_admin: isAdmin,
+				can_create: canCreate,
+				is_blocked: isBlocked
+			});
+			user = updated;
+			saveSuccess = true;
+			setTimeout(() => (saveSuccess = false), 2500);
+		} catch (e) {
+			saveError = e instanceof ApiError ? e.message : 'Failed to save';
+		} finally {
+			saving = false;
+		}
+	}
+
+	async function doDelete() {
+		confirmDelete = false;
+		deleting = true;
+		try {
+			await api.delete(`/users/${user!.id}`);
+			goto('/admin/users');
+		} catch (e) {
+			saveError = e instanceof ApiError ? e.message : 'Failed to delete';
+			deleting = false;
+		}
+	}
+</script>
+
+<svelte:head><title>{user?.name ?? 'User'} — Admin | Tanabata</title></svelte:head>
+
+<div class="page">
+	<button class="back-link" onclick={() => goto('/admin/users')}> ← All users </button>
+
+	{#if error}
+		<p class="msg error" role="alert">{error}</p>
+	{:else if loading}
+		<div class="loading"><span class="spinner" role="status" aria-label="Loading"></span></div>
+	{:else if user}
+		<div class="card">
+			<div class="user-header">
+				<span class="user-name">{user.name}</span>
+				<span class="user-id">#{user.id}</span>
+			</div>
+
+			{#if saveError}<p class="msg error" role="alert">{saveError}</p>{/if}
+			{#if saveSuccess}<p class="msg success" role="status">Saved.</p>{/if}
+
+			<div class="section-label">Role & permissions</div>
+
+			<div class="toggle-group">
+				<div class="toggle-row">
+					<div>
+						<span class="toggle-label">Admin</span>
+						<p class="toggle-hint">Full access to all data and admin panel.</p>
+					</div>
+					<button
+						class="toggle"
+						class:on={isAdmin}
+						role="switch"
+						aria-checked={isAdmin}
+						onclick={() => (isAdmin = !isAdmin)}><span class="thumb"></span></button
+					>
+				</div>
+
+				<div class="toggle-row">
+					<div>
+						<span class="toggle-label">Can create</span>
+						<p class="toggle-hint">Can upload files and create tags, pools, categories.</p>
+					</div>
+					<button
+						class="toggle"
+						class:on={canCreate}
+						role="switch"
+						aria-checked={canCreate}
+						onclick={() => (canCreate = !canCreate)}><span class="thumb"></span></button
+					>
+				</div>
+			</div>
+
+			<div class="section-label">Account status</div>
+
+			<div class="toggle-group">
+				<div class="toggle-row">
+					<div>
+						<span class="toggle-label" class:danger-label={isBlocked}>Blocked</span>
+						<p class="toggle-hint">Blocked users cannot log in.</p>
+					</div>
+					<button
+						class="toggle"
+						class:on={isBlocked}
+						class:danger={isBlocked}
+						role="switch"
+						aria-checked={isBlocked}
+						onclick={() => (isBlocked = !isBlocked)}><span class="thumb"></span></button
+					>
+				</div>
+			</div>
+
+			<div class="action-row">
+				<button class="btn primary" onclick={save} disabled={saving}>
+					{saving ? 'Saving…' : 'Save changes'}
+				</button>
+				<button
+					class="btn danger-outline"
+					onclick={() => (confirmDelete = true)}
+					disabled={deleting}
+				>
+					{deleting ? 'Deleting…' : 'Delete user'}
+				</button>
+			</div>
+		</div>
+	{/if}
+</div>
+
+{#if confirmDelete && user}
+	<ConfirmDialog
+		message="Delete user &ldquo;{user.name}&rdquo;? This cannot be undone."
+		confirmLabel="Delete"
+		danger
+		onConfirm={doDelete}
+		onCancel={() => (confirmDelete = false)}
+	/>
+{/if}
+
+<style>
+	.page {
+		padding: 16px;
+		max-width: 520px;
+		margin: 0 auto;
+		display: flex;
+		flex-direction: column;
+		gap: 14px;
+	}
+
+	.back-link {
+		background: none;
+		border: none;
+		color: var(--color-text-muted);
+		font-size: 0.85rem;
+		cursor: pointer;
+		padding: 0;
+		text-align: left;
+		font-family: inherit;
+	}
+
+	.back-link:hover {
+		color: var(--color-accent);
+	}
+
+	.card {
+		background-color: var(--color-bg-elevated);
+		border-radius: 12px;
+		padding: 18px;
+		display: flex;
+		flex-direction: column;
+		gap: 14px;
+	}
+
+	.user-header {
+		display: flex;
+		align-items: baseline;
+		gap: 8px;
+	}
+
+	.user-name {
+		font-size: 1.15rem;
+		font-weight: 700;
+	}
+
+	.user-id {
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+	}
+
+	.section-label {
+		font-size: 0.72rem;
+		font-weight: 700;
+		text-transform: uppercase;
+		letter-spacing: 0.07em;
+		color: var(--color-text-muted);
+		margin-bottom: -6px;
+	}
+
+	.toggle-group {
+		display: flex;
+		flex-direction: column;
+		gap: 10px;
+	}
+
+	.toggle-row {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 12px;
+	}
+
+	.toggle-label {
+		font-size: 0.9rem;
+		font-weight: 500;
+	}
+
+	.toggle-label.danger-label {
+		color: var(--color-danger);
+	}
+
+	.toggle-hint {
+		font-size: 0.78rem;
+		color: var(--color-text-muted);
+		margin: 2px 0 0;
+	}
+
+	/* toggle switch */
+	.toggle {
+		flex-shrink: 0;
+		position: relative;
+		width: 40px;
+		height: 22px;
+		border-radius: 11px;
+		border: none;
+		background-color: color-mix(in srgb, var(--color-accent) 22%, var(--color-bg-primary));
+		cursor: pointer;
+		padding: 0;
+		transition: background-color 0.15s;
+	}
+
+	.toggle.on {
+		background-color: var(--color-accent);
+	}
+	.toggle.on.danger {
+		background-color: var(--color-danger);
+	}
+
+	.toggle .thumb {
+		position: absolute;
+		top: 3px;
+		left: 3px;
+		width: 16px;
+		height: 16px;
+		border-radius: 50%;
+		background-color: #fff;
+		transition: transform 0.15s;
+	}
+
+	.toggle.on .thumb {
+		transform: translateX(18px);
+	}
+
+	.action-row {
+		display: flex;
+		gap: 8px;
+		margin-top: 4px;
+	}
+
+	.btn {
+		height: 34px;
+		padding: 0 16px;
+		border-radius: 7px;
+		font-size: 0.875rem;
+		font-family: inherit;
+		font-weight: 600;
+		cursor: pointer;
+		border: none;
+	}
+
+	.btn:disabled {
+		opacity: 0.5;
+		cursor: default;
+	}
+
+	.btn.primary {
+		background-color: var(--color-accent);
+		color: #fff;
+	}
+
+	.btn.primary:hover:not(:disabled) {
+		background-color: var(--color-accent-hover);
+	}
+
+	.btn.danger-outline {
+		background: none;
+		border: 1px solid var(--color-danger);
+		color: var(--color-danger);
+	}
+
+	.btn.danger-outline:hover:not(:disabled) {
+		background-color: color-mix(in srgb, var(--color-danger) 12%, transparent);
+	}
+
+	.msg {
+		font-size: 0.85rem;
+		margin: 0;
+	}
+
+	.msg.error {
+		color: var(--color-danger);
+	}
+	.msg.success {
+		color: #7ecba1;
+	}
+
+	.loading {
+		display: flex;
+		justify-content: center;
+		padding: 40px;
+	}
+
+	.spinner {
+		display: block;
+		width: 28px;
+		height: 28px;
+		border: 3px solid color-mix(in srgb, var(--color-accent) 25%, transparent);
+		border-top-color: var(--color-accent);
+		border-radius: 50%;
+		animation: spin 0.7s linear infinite;
+	}
+
+	@keyframes spin {
+		to {
+			transform: rotate(360deg);
+		}
+	}
+</style>

frontend/src/routes/categories/+page.svelte

@@ -0,0 +1,408 @@
+<script lang="ts">
+	import { goto, beforeNavigate, afterNavigate } from '$app/navigation';
+	import { get } from 'svelte/store';
+	import { api, ApiError } from '$lib/api/client';
+	import { categorySorting, type CategorySortField } from '$lib/stores/sorting';
+	import InfiniteScroll from '$lib/components/common/InfiniteScroll.svelte';
+	import { saveSection, takeSection, type OffsetListSnapshot } from '$lib/stores/sectionCache';
+	import { restoreListScroll } from '$lib/stores/listScroll';
+	import type { Category, CategoryOffsetPage } from '$lib/api/types';
+
+	const LIMIT = 100;
+
+	const SORT_OPTIONS: { value: CategorySortField; label: string }[] = [
+		{ value: 'name', label: 'Name' },
+		{ value: 'color', label: 'Color' },
+		{ value: 'created', label: 'Created' }
+	];
+
+	let categories = $state<Category[]>([]);
+	let total = $state(0);
+	let offset = $state(0);
+	let loading = $state(false);
+	let initialLoaded = $state(false);
+	let error = $state('');
+	let search = $state('');
+
+	let sortState = $derived($categorySorting);
+
+	let resetKey = $derived(`${sortState.sort}|${sortState.order}|${search}`);
+	let prevKey = $state('');
+
+	let scrollEl = $state<HTMLElement>();
+	let pendingScroll: number | null = null;
+
+	// Rehydrate the loaded list, search and scroll from the cache on return (same
+	// sort/order/search), during init so the matching prevKey/initialLoaded
+	// suppress the reset + initial load below.
+	const cached = takeSection<OffsetListSnapshot<Category>>('categories');
+	if (cached) {
+		const s0 = get(categorySorting);
+		const wouldKey = `${s0.sort}|${s0.order}|${cached.data.search}`;
+		if (wouldKey === cached.data.resetKey && cached.data.items.length > 0) {
+			search = cached.data.search;
+			categories = cached.data.items;
+			total = cached.data.total;
+			offset = cached.data.offset;
+			initialLoaded = true;
+			prevKey = wouldKey;
+			pendingScroll = cached.scrollTop;
+		}
+	}
+
+	beforeNavigate(() => {
+		if (categories.length === 0) return;
+		saveSection<OffsetListSnapshot<Category>>('categories', scrollEl?.scrollTop ?? 0, {
+			resetKey,
+			search,
+			items: categories,
+			total,
+			offset
+		});
+	});
+
+	afterNavigate(() => {
+		if (pendingScroll == null) return;
+		restoreListScroll(() => scrollEl, pendingScroll);
+		pendingScroll = null;
+	});
+
+	$effect(() => {
+		if (resetKey !== prevKey) {
+			prevKey = resetKey;
+			categories = [];
+			offset = 0;
+			total = 0;
+			initialLoaded = false;
+		}
+	});
+
+	$effect(() => {
+		if (!initialLoaded && !loading) void load();
+	});
+
+	async function load() {
+		if (loading) return;
+		loading = true;
+		error = '';
+		try {
+			const params = new URLSearchParams({
+				limit: String(LIMIT),
+				offset: String(offset),
+				sort: sortState.sort,
+				order: sortState.order
+			});
+			if (search.trim()) params.set('search', search.trim());
+			const page = await api.get<CategoryOffsetPage>(`/categories?${params}`);
+			categories = offset === 0 ? (page.items ?? []) : [...categories, ...(page.items ?? [])];
+			total = page.total ?? 0;
+			offset = categories.length;
+		} catch (e) {
+			error = e instanceof ApiError ? e.message : 'Failed to load categories';
+		} finally {
+			loading = false;
+			initialLoaded = true;
+		}
+	}
+
+	let hasMore = $derived(categories.length < total);
+</script>
+
+<svelte:head>
+	<title>Categories | Tanabata</title>
+</svelte:head>
+
+<div class="page">
+	<header class="top-bar">
+		<h1 class="page-title">Categories</h1>
+
+		<div class="controls">
+			<select
+				class="sort-select"
+				value={sortState.sort}
+				onchange={(e) =>
+					categorySorting.setSort(
+						(e.currentTarget as HTMLSelectElement).value as CategorySortField
+					)}
+			>
+				{#each SORT_OPTIONS as opt}
+					<option value={opt.value}>{opt.label}</option>
+				{/each}
+			</select>
+
+			<button
+				class="icon-btn"
+				onclick={() => categorySorting.toggleOrder()}
+				title={sortState.order === 'asc' ? 'Ascending' : 'Descending'}
+			>
+				{#if sortState.order === 'asc'}
+					<svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+						<path
+							d="M3 9L7 5L11 9"
+							stroke="currentColor"
+							stroke-width="1.8"
+							stroke-linecap="round"
+							stroke-linejoin="round"
+						/>
+					</svg>
+				{:else}
+					<svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+						<path
+							d="M3 5L7 9L11 5"
+							stroke="currentColor"
+							stroke-width="1.8"
+							stroke-linecap="round"
+							stroke-linejoin="round"
+						/>
+					</svg>
+				{/if}
+			</button>
+
+			<button class="new-btn" onclick={() => goto('/categories/new')}>+ New</button>
+		</div>
+	</header>
+
+	<div class="search-bar">
+		<div class="search-wrap">
+			<input
+				class="search-input"
+				type="search"
+				placeholder="Search categories…"
+				value={search}
+				oninput={(e) => (search = (e.currentTarget as HTMLInputElement).value)}
+				autocomplete="off"
+			/>
+			{#if search}
+				<button class="search-clear" onclick={() => (search = '')} aria-label="Clear search">
+					<svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+						<path
+							d="M2 2l10 10M12 2L2 12"
+							stroke="currentColor"
+							stroke-width="1.8"
+							stroke-linecap="round"
+						/>
+					</svg>
+				</button>
+			{/if}
+		</div>
+	</div>
+
+	<main bind:this={scrollEl}>
+		{#if error}
+			<p class="error" role="alert">{error}</p>
+		{/if}
+
+		<div class="category-grid">
+			{#each categories as cat (cat.id)}
+				<button
+					class="category-pill"
+					style={cat.color ? `background-color: #${cat.color}` : ''}
+					onclick={() => goto(`/categories/${cat.id}`)}
+				>
+					{cat.name}
+				</button>
+			{/each}
+		</div>
+
+		<InfiniteScroll {loading} {hasMore} onLoadMore={load} />
+
+		{#if !loading && categories.length === 0}
+			<div class="empty">
+				{search ? 'No categories match your search.' : 'No categories yet.'}
+				{#if !search}
+					<a href="/categories/new">Create one</a>
+				{/if}
+			</div>
+		{/if}
+	</main>
+</div>
+
+<style>
+	.page {
+		flex: 1;
+		min-height: 0;
+		display: flex;
+		flex-direction: column;
+	}
+
+	.top-bar {
+		position: sticky;
+		top: 0;
+		z-index: 10;
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		padding: 6px 12px;
+		background-color: var(--color-bg-primary);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 15%, transparent);
+		flex-shrink: 0;
+	}
+
+	.page-title {
+		font-size: 1rem;
+		font-weight: 600;
+		color: var(--color-text-primary);
+		margin: 0;
+		flex: 1;
+	}
+
+	.controls {
+		display: flex;
+		align-items: center;
+		gap: 4px;
+	}
+
+	.sort-select {
+		height: 28px;
+		padding: 0 8px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.82rem;
+		font-family: inherit;
+		cursor: pointer;
+		outline: none;
+	}
+
+	.icon-btn {
+		width: 28px;
+		height: 28px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-muted);
+		cursor: pointer;
+	}
+
+	.icon-btn:hover {
+		color: var(--color-text-primary);
+		border-color: var(--color-accent);
+	}
+
+	.new-btn {
+		height: 28px;
+		padding: 0 12px;
+		border-radius: 6px;
+		border: none;
+		background-color: var(--color-accent);
+		color: var(--color-bg-primary);
+		font-size: 0.82rem;
+		font-weight: 600;
+		font-family: inherit;
+		cursor: pointer;
+	}
+
+	.new-btn:hover {
+		background-color: var(--color-accent-hover);
+	}
+
+	.search-bar {
+		padding: 8px 12px;
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 10%, transparent);
+		flex-shrink: 0;
+	}
+
+	.search-wrap {
+		position: relative;
+		display: flex;
+		align-items: center;
+	}
+
+	.search-input {
+		width: 100%;
+		box-sizing: border-box;
+		height: 34px;
+		padding: 0 12px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.875rem;
+		font-family: inherit;
+		outline: none;
+	}
+
+	.search-input:focus {
+		border-color: var(--color-accent);
+	}
+
+	.search-clear {
+		position: absolute;
+		right: 8px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		border: none;
+		background: none;
+		color: var(--color-text-muted);
+		cursor: pointer;
+		padding: 0;
+	}
+
+	.search-clear:hover {
+		color: var(--color-text-primary);
+		background-color: color-mix(in srgb, var(--color-accent) 20%, transparent);
+	}
+
+	main {
+		flex: 1;
+		overflow-y: auto;
+		padding: 12px 12px calc(60px + 12px);
+	}
+
+	.category-grid {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 8px;
+		align-content: flex-start;
+	}
+
+	.category-pill {
+		display: inline-flex;
+		align-items: center;
+		height: 32px;
+		padding: 0 14px;
+		border-radius: 6px;
+		border: none;
+		background-color: var(--color-tag-default);
+		color: rgba(255, 255, 255, 0.9);
+		font-size: 0.875rem;
+		font-family: inherit;
+		font-weight: 500;
+		white-space: nowrap;
+		cursor: pointer;
+	}
+
+	.category-pill:hover {
+		filter: brightness(1.15);
+	}
+
+	.error {
+		color: var(--color-danger);
+		font-size: 0.875rem;
+		padding: 8px 0;
+	}
+
+	.empty {
+		text-align: center;
+		color: var(--color-text-muted);
+		padding: 60px 20px;
+		font-size: 0.95rem;
+		display: flex;
+		flex-direction: column;
+		gap: 8px;
+		align-items: center;
+	}
+
+	.empty a {
+		color: var(--color-accent);
+		text-decoration: none;
+	}
+</style>

frontend/src/routes/categories/[id]/+page.svelte

@@ -0,0 +1,553 @@
+<script lang="ts">
+	import { goto } from '$app/navigation';
+	import { page } from '$app/state';
+	import { api, ApiError } from '$lib/api/client';
+	import type { Category, Tag, TagOffsetPage } from '$lib/api/types';
+	import TagBadge from '$lib/components/tag/TagBadge.svelte';
+	import ConfirmDialog from '$lib/components/common/ConfirmDialog.svelte';
+
+	let categoryId = $derived(page.params.id);
+
+	let category = $state<Category | null>(null);
+	let tags = $state<Tag[]>([]);
+	let tagsTotal = $state(0);
+	let tagsOffset = $state(0);
+	let tagsLoading = $state(false);
+
+	let name = $state('');
+	let notes = $state('');
+	let color = $state('#9592B5');
+	let isPublic = $state(false);
+
+	let saving = $state(false);
+	let deleting = $state(false);
+	let loadError = $state('');
+	let saveError = $state('');
+	let loaded = $state(false);
+	let confirmDelete = $state(false);
+
+	const TAGS_LIMIT = 100;
+
+	$effect(() => {
+		const id = categoryId;
+		loaded = false;
+		loadError = '';
+		tags = [];
+		tagsOffset = 0;
+		tagsTotal = 0;
+		void api
+			.get<Category>(`/categories/${id}`)
+			.then((cat) => {
+				category = cat;
+				name = cat.name ?? '';
+				notes = cat.notes ?? '';
+				color = cat.color ? `#${cat.color}` : '#9592B5';
+				isPublic = cat.is_public ?? false;
+				loaded = true;
+			})
+			.catch((e) => {
+				loadError = e instanceof ApiError ? e.message : 'Failed to load category';
+			});
+		void loadTags(id, 0);
+	});
+
+	async function loadTags(id: string | undefined, startOffset: number) {
+		if (!id) return;
+		tagsLoading = true;
+		try {
+			const params = new URLSearchParams({
+				limit: String(TAGS_LIMIT),
+				offset: String(startOffset),
+				sort: 'name',
+				order: 'asc'
+			});
+			const p = await api.get<TagOffsetPage>(`/categories/${id}/tags?${params}`);
+			tags = startOffset === 0 ? (p.items ?? []) : [...tags, ...(p.items ?? [])];
+			tagsTotal = p.total ?? 0;
+			tagsOffset = tags.length;
+		} catch {
+			// non-fatal — tags section just stays empty
+		} finally {
+			tagsLoading = false;
+		}
+	}
+
+	let tagsHasMore = $derived(tags.length < tagsTotal);
+
+	async function save() {
+		if (!name.trim() || saving) return;
+		saving = true;
+		saveError = '';
+		try {
+			await api.patch(`/categories/${categoryId}`, {
+				name: name.trim(),
+				notes: notes.trim() || null,
+				color: color.slice(1),
+				is_public: isPublic
+			});
+			goto('/categories');
+		} catch (e) {
+			saveError = e instanceof ApiError ? e.message : 'Failed to save category';
+		} finally {
+			saving = false;
+		}
+	}
+
+	async function doDeleteCategory() {
+		confirmDelete = false;
+		deleting = true;
+		try {
+			await api.delete(`/categories/${categoryId}`);
+			goto('/categories');
+		} catch (e) {
+			saveError = e instanceof ApiError ? e.message : 'Failed to delete category';
+			deleting = false;
+		}
+	}
+</script>
+
+<svelte:head>
+	<title>{category?.name ?? 'Category'} | Tanabata</title>
+</svelte:head>
+
+<div class="page">
+	<header class="top-bar">
+		<button class="back-btn" onclick={() => goto('/categories')} aria-label="Back">
+			<svg width="20" height="20" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+				<path
+					d="M12 4L6 10L12 16"
+					stroke="currentColor"
+					stroke-width="2"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+				/>
+			</svg>
+		</button>
+		<h1 class="page-title">{category?.name ?? 'Category'}</h1>
+	</header>
+
+	<main>
+		{#if loadError}
+			<p class="error" role="alert">{loadError}</p>
+		{:else if !loaded}
+			<div class="loading-row">
+				<span class="spinner" role="status" aria-label="Loading"></span>
+			</div>
+		{:else}
+			{#if saveError}
+				<p class="error" role="alert">{saveError}</p>
+			{/if}
+
+			<form
+				class="form"
+				onsubmit={(e) => {
+					e.preventDefault();
+					void save();
+				}}
+			>
+				<div class="row-fields">
+					<div class="field" style="flex: 1">
+						<label class="label" for="name">Name <span class="required">*</span></label>
+						<input
+							id="name"
+							class="input"
+							type="text"
+							bind:value={name}
+							required
+							placeholder="Category name"
+							autocomplete="off"
+						/>
+					</div>
+					<div class="field color-field">
+						<label class="label" for="color">Color</label>
+						<input id="color" class="color-input" type="color" bind:value={color} />
+					</div>
+				</div>
+
+				<div class="field">
+					<label class="label" for="notes">Notes</label>
+					<textarea
+						id="notes"
+						class="textarea"
+						rows="3"
+						bind:value={notes}
+						placeholder="Optional notes…"
+					></textarea>
+				</div>
+
+				<div class="toggle-row">
+					<span class="label">Public</span>
+					<button
+						type="button"
+						class="toggle"
+						class:on={isPublic}
+						onclick={() => (isPublic = !isPublic)}
+						role="switch"
+						aria-checked={isPublic}
+						aria-label="Public"
+					>
+						<span class="thumb"></span>
+					</button>
+				</div>
+
+				<div class="action-row">
+					<button type="submit" class="submit-btn" disabled={!name.trim() || saving}>
+						{saving ? 'Saving…' : 'Save changes'}
+					</button>
+					<button
+						type="button"
+						class="delete-btn"
+						onclick={() => (confirmDelete = true)}
+						disabled={deleting}
+					>
+						{deleting ? 'Deleting…' : 'Delete'}
+					</button>
+				</div>
+			</form>
+
+			<!-- Tags in this category -->
+			<section class="section">
+				<h2 class="section-title">
+					Tags
+					{#if tagsTotal > 0}<span class="count">({tagsTotal})</span>{/if}
+				</h2>
+
+				{#if tagsLoading && tags.length === 0}
+					<div class="loading-row">
+						<span class="spinner" role="status" aria-label="Loading"></span>
+					</div>
+				{:else if tags.length === 0}
+					<p class="empty-tags">No tags in this category.</p>
+				{:else}
+					<div class="tag-grid">
+						{#each tags as tag (tag.id)}
+							<TagBadge {tag} onclick={() => goto(`/tags/${tag.id}`)} size="sm" />
+						{/each}
+					</div>
+
+					{#if tagsHasMore}
+						<button
+							class="load-more"
+							onclick={() => loadTags(categoryId, tagsOffset)}
+							disabled={tagsLoading}
+						>
+							{tagsLoading ? 'Loading…' : 'Load more'}
+						</button>
+					{/if}
+				{/if}
+			</section>
+		{/if}
+	</main>
+</div>
+
+{#if confirmDelete}
+	<ConfirmDialog
+		message={`Delete category "${name}"? Tags in this category will be unassigned.`}
+		confirmLabel="Delete"
+		danger
+		onConfirm={doDeleteCategory}
+		onCancel={() => (confirmDelete = false)}
+	/>
+{/if}
+
+<style>
+	.page {
+		flex: 1;
+		min-height: 0;
+		display: flex;
+		flex-direction: column;
+	}
+
+	.top-bar {
+		position: sticky;
+		top: 0;
+		z-index: 10;
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		padding: 6px 10px;
+		min-height: 44px;
+		background-color: var(--color-bg-primary);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 15%, transparent);
+		flex-shrink: 0;
+	}
+
+	.back-btn {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 36px;
+		height: 36px;
+		border-radius: 8px;
+		border: none;
+		background: none;
+		color: var(--color-text-primary);
+		cursor: pointer;
+	}
+	.back-btn:hover {
+		background-color: color-mix(in srgb, var(--color-accent) 15%, transparent);
+	}
+
+	.page-title {
+		font-size: 1rem;
+		font-weight: 600;
+		margin: 0;
+	}
+
+	main {
+		flex: 1;
+		overflow-y: auto;
+		padding: 16px 14px calc(60px + 16px);
+		display: flex;
+		flex-direction: column;
+		gap: 24px;
+	}
+
+	.loading-row {
+		display: flex;
+		justify-content: center;
+		padding: 40px;
+	}
+
+	.spinner {
+		display: block;
+		width: 28px;
+		height: 28px;
+		border: 3px solid color-mix(in srgb, var(--color-accent) 25%, transparent);
+		border-top-color: var(--color-accent);
+		border-radius: 50%;
+		animation: spin 0.7s linear infinite;
+	}
+	@keyframes spin {
+		to {
+			transform: rotate(360deg);
+		}
+	}
+
+	.form {
+		display: flex;
+		flex-direction: column;
+		gap: 14px;
+	}
+
+	.row-fields {
+		display: flex;
+		gap: 10px;
+		align-items: flex-end;
+	}
+
+	.field {
+		display: flex;
+		flex-direction: column;
+		gap: 5px;
+	}
+
+	.color-field {
+		flex-shrink: 0;
+	}
+
+	.label {
+		font-size: 0.75rem;
+		font-weight: 600;
+		color: var(--color-text-muted);
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+	}
+
+	.required {
+		color: var(--color-danger);
+	}
+
+	.input {
+		width: 100%;
+		box-sizing: border-box;
+		height: 36px;
+		padding: 0 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.875rem;
+		font-family: inherit;
+		outline: none;
+	}
+	.input:focus {
+		border-color: var(--color-accent);
+	}
+
+	.color-input {
+		width: 50px;
+		height: 36px;
+		padding: 2px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		cursor: pointer;
+	}
+
+	.textarea {
+		width: 100%;
+		box-sizing: border-box;
+		padding: 8px 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.875rem;
+		font-family: inherit;
+		resize: vertical;
+		outline: none;
+		min-height: 70px;
+	}
+	.textarea:focus {
+		border-color: var(--color-accent);
+	}
+
+	.toggle-row {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		padding: 4px 0;
+	}
+	.toggle-row .label {
+		margin: 0;
+	}
+
+	.toggle {
+		position: relative;
+		width: 44px;
+		height: 26px;
+		border-radius: 13px;
+		border: none;
+		background-color: color-mix(in srgb, var(--color-accent) 25%, var(--color-bg-elevated));
+		cursor: pointer;
+		transition: background-color 0.2s;
+		flex-shrink: 0;
+	}
+	.toggle.on {
+		background-color: var(--color-accent);
+	}
+	.thumb {
+		position: absolute;
+		top: 3px;
+		left: 3px;
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		background-color: #fff;
+		transition: transform 0.2s;
+	}
+	.toggle.on .thumb {
+		transform: translateX(18px);
+	}
+
+	.action-row {
+		display: flex;
+		gap: 8px;
+	}
+
+	.submit-btn {
+		flex: 1;
+		height: 42px;
+		border-radius: 8px;
+		border: none;
+		background-color: var(--color-accent);
+		color: var(--color-bg-primary);
+		font-size: 0.9rem;
+		font-weight: 600;
+		font-family: inherit;
+		cursor: pointer;
+	}
+	.submit-btn:hover:not(:disabled) {
+		background-color: var(--color-accent-hover);
+	}
+	.submit-btn:disabled {
+		opacity: 0.4;
+		cursor: default;
+	}
+
+	.delete-btn {
+		height: 42px;
+		padding: 0 18px;
+		border-radius: 8px;
+		border: 1px solid color-mix(in srgb, var(--color-danger) 50%, transparent);
+		background: none;
+		color: var(--color-danger);
+		font-size: 0.9rem;
+		font-weight: 600;
+		font-family: inherit;
+		cursor: pointer;
+	}
+	.delete-btn:hover:not(:disabled) {
+		background-color: color-mix(in srgb, var(--color-danger) 12%, transparent);
+	}
+	.delete-btn:disabled {
+		opacity: 0.4;
+		cursor: default;
+	}
+
+	.section {
+		display: flex;
+		flex-direction: column;
+		gap: 10px;
+	}
+
+	.section-title {
+		font-size: 0.75rem;
+		font-weight: 600;
+		color: var(--color-text-muted);
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		margin: 0;
+		padding-bottom: 6px;
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 15%, transparent);
+		display: flex;
+		gap: 6px;
+		align-items: baseline;
+	}
+
+	.count {
+		font-weight: 400;
+		color: var(--color-text-muted);
+	}
+
+	.tag-grid {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 6px;
+	}
+
+	.empty-tags {
+		font-size: 0.85rem;
+		color: var(--color-text-muted);
+		margin: 0;
+	}
+
+	.load-more {
+		display: block;
+		margin-top: 8px;
+		padding: 6px 20px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 40%, transparent);
+		background: none;
+		color: var(--color-accent);
+		font-family: inherit;
+		font-size: 0.82rem;
+		cursor: pointer;
+	}
+
+	.load-more:hover:not(:disabled) {
+		background-color: color-mix(in srgb, var(--color-accent) 10%, transparent);
+	}
+
+	.load-more:disabled {
+		opacity: 0.5;
+		cursor: default;
+	}
+
+	.error {
+		color: var(--color-danger);
+		font-size: 0.875rem;
+		margin: 0;
+	}
+</style>

frontend/src/routes/categories/new/+page.svelte

@@ -0,0 +1,307 @@
+<script lang="ts">
+	import { goto } from '$app/navigation';
+	import { api, ApiError } from '$lib/api/client';
+
+	let name = $state('');
+	let notes = $state('');
+	let color = $state('#9592B5');
+	let isPublic = $state(false);
+	let saving = $state(false);
+	let error = $state('');
+
+	async function submit() {
+		if (!name.trim() || saving) return;
+		saving = true;
+		error = '';
+		try {
+			await api.post('/categories', {
+				name: name.trim(),
+				notes: notes.trim() || null,
+				color: color.slice(1),
+				is_public: isPublic
+			});
+			goto('/categories');
+		} catch (e) {
+			error = e instanceof ApiError ? e.message : 'Failed to create category';
+		} finally {
+			saving = false;
+		}
+	}
+</script>
+
+<svelte:head>
+	<title>New Category | Tanabata</title>
+</svelte:head>
+
+<div class="page">
+	<header class="top-bar">
+		<button class="back-btn" onclick={() => goto('/categories')} aria-label="Back">
+			<svg width="20" height="20" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+				<path
+					d="M12 4L6 10L12 16"
+					stroke="currentColor"
+					stroke-width="2"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+				/>
+			</svg>
+		</button>
+		<h1 class="page-title">New Category</h1>
+	</header>
+
+	<main>
+		{#if error}
+			<p class="error" role="alert">{error}</p>
+		{/if}
+
+		<form
+			class="form"
+			onsubmit={(e) => {
+				e.preventDefault();
+				void submit();
+			}}
+		>
+			<div class="row-fields">
+				<div class="field" style="flex: 1">
+					<label class="label" for="name">Name <span class="required">*</span></label>
+					<input
+						id="name"
+						class="input"
+						type="text"
+						bind:value={name}
+						required
+						placeholder="Category name"
+						autocomplete="off"
+					/>
+				</div>
+				<div class="field color-field">
+					<label class="label" for="color">Color</label>
+					<input id="color" class="color-input" type="color" bind:value={color} />
+				</div>
+			</div>
+
+			<div class="field">
+				<label class="label" for="notes">Notes</label>
+				<textarea
+					id="notes"
+					class="textarea"
+					rows="3"
+					bind:value={notes}
+					placeholder="Optional notes…"
+				></textarea>
+			</div>
+
+			<div class="toggle-row">
+				<span class="label">Public</span>
+				<button
+					type="button"
+					class="toggle"
+					class:on={isPublic}
+					onclick={() => (isPublic = !isPublic)}
+					role="switch"
+					aria-checked={isPublic}
+					aria-label="Public"
+				>
+					<span class="thumb"></span>
+				</button>
+			</div>
+
+			<button type="submit" class="submit-btn" disabled={!name.trim() || saving}>
+				{saving ? 'Creating…' : 'Create category'}
+			</button>
+		</form>
+	</main>
+</div>
+
+<style>
+	.page {
+		flex: 1;
+		min-height: 0;
+		display: flex;
+		flex-direction: column;
+	}
+
+	.top-bar {
+		position: sticky;
+		top: 0;
+		z-index: 10;
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		padding: 6px 10px;
+		min-height: 44px;
+		background-color: var(--color-bg-primary);
+		border-bottom: 1px solid color-mix(in srgb, var(--color-accent) 15%, transparent);
+		flex-shrink: 0;
+	}
+
+	.back-btn {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 36px;
+		height: 36px;
+		border-radius: 8px;
+		border: none;
+		background: none;
+		color: var(--color-text-primary);
+		cursor: pointer;
+	}
+	.back-btn:hover {
+		background-color: color-mix(in srgb, var(--color-accent) 15%, transparent);
+	}
+
+	.page-title {
+		font-size: 1rem;
+		font-weight: 600;
+		margin: 0;
+	}
+
+	main {
+		flex: 1;
+		overflow-y: auto;
+		padding: 16px 14px calc(60px + 16px);
+	}
+
+	.form {
+		display: flex;
+		flex-direction: column;
+		gap: 14px;
+	}
+
+	.row-fields {
+		display: flex;
+		gap: 10px;
+		align-items: flex-end;
+	}
+
+	.field {
+		display: flex;
+		flex-direction: column;
+		gap: 5px;
+	}
+
+	.color-field {
+		flex-shrink: 0;
+	}
+
+	.label {
+		font-size: 0.75rem;
+		font-weight: 600;
+		color: var(--color-text-muted);
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+	}
+
+	.required {
+		color: var(--color-danger);
+	}
+
+	.input {
+		width: 100%;
+		box-sizing: border-box;
+		height: 36px;
+		padding: 0 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.875rem;
+		font-family: inherit;
+		outline: none;
+	}
+	.input:focus {
+		border-color: var(--color-accent);
+	}
+
+	.color-input {
+		width: 50px;
+		height: 36px;
+		padding: 2px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		cursor: pointer;
+	}
+
+	.textarea {
+		width: 100%;
+		box-sizing: border-box;
+		padding: 8px 10px;
+		border-radius: 6px;
+		border: 1px solid color-mix(in srgb, var(--color-accent) 30%, transparent);
+		background-color: var(--color-bg-elevated);
+		color: var(--color-text-primary);
+		font-size: 0.875rem;
+		font-family: inherit;
+		resize: vertical;
+		outline: none;
+		min-height: 70px;
+	}
+	.textarea:focus {
+		border-color: var(--color-accent);
+	}
+
+	.toggle-row {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		padding: 4px 0;
+	}
+	.toggle-row .label {
+		margin: 0;
+	}
+
+	.toggle {
+		position: relative;
+		width: 44px;
+		height: 26px;
+		border-radius: 13px;
+		border: none;
+		background-color: color-mix(in srgb, var(--color-accent) 25%, var(--color-bg-elevated));
+		cursor: pointer;
+		transition: background-color 0.2s;
+		flex-shrink: 0;
+	}
+	.toggle.on {
+		background-color: var(--color-accent);
+	}
+	.thumb {
+		position: absolute;
+		top: 3px;
+		left: 3px;
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		background-color: #fff;
+		transition: transform 0.2s;
+	}
+	.toggle.on .thumb {
+		transform: translateX(18px);
+	}
+
+	.submit-btn {
+		width: 100%;
+		height: 42px;
+		border-radius: 8px;
+		border: none;
+		background-color: var(--color-accent);
+		color: var(--color-bg-primary);
+		font-size: 0.9rem;
+		font-weight: 600;
+		font-family: inherit;
+		cursor: pointer;
+	}
+	.submit-btn:hover:not(:disabled) {
+		background-color: var(--color-accent-hover);
+	}
+	.submit-btn:disabled {
+		opacity: 0.4;
+		cursor: default;
+	}
+
+	.error {
+		color: var(--color-danger);
+		font-size: 0.875rem;
+	}
+</style>

frontend/src/routes/files/[id]/+page.svelte

@@ -0,0 +1,64 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { goto } from '$app/navigation';
+	import { get } from 'svelte/store';
+	import { api } from '$lib/api/client';
+	import { fileSorting } from '$lib/stores/sorting';
+	import FileViewer from '$lib/components/file/FileViewer.svelte';
+	import type { FileCursorPage } from '$lib/api/types';
+
+	// This standalone route is the fallback for a deep link / hard reload to a
+	// file. The normal path (opening from the grid) renders FileViewer as an
+	// overlay on the still-mounted list via shallow routing — see files/+page.
+	let fileId = $derived(page.params.id);
+
+	let prevId = $state<string | null>(null);
+	let nextId = $state<string | null>(null);
+
+	$effect(() => {
+		const id = fileId;
+		if (id) void resolveNeighbors(id);
+	});
+
+	// No cached grid here, so derive neighbours from an anchored window. The
+	// backend anchor window is forward-inclusive, so prev is only available once
+	// we're past the first item of that window.
+	async function resolveNeighbors(id: string) {
+		const sort = get(fileSorting);
+		const params = new URLSearchParams({
+			anchor: id,
+			limit: '3',
+			sort: sort.sort,
+			order: sort.order
+		});
+		try {
+			const result = await api.get<FileCursorPage>(`/files?${params}`);
+			if (fileId !== id) return;
+			const items = result.items ?? [];
+			const idx = items.findIndex((f) => f.id === id);
+			prevId = idx > 0 ? (items[idx - 1].id ?? null) : null;
+			nextId = idx >= 0 && idx < items.length - 1 ? (items[idx + 1].id ?? null) : null;
+		} catch {
+			// non-critical
+		}
+	}
+
+	function pageTo(id: string) {
+		goto(`/files/${id}`);
+	}
+
+	function closeViewer() {
+		// No list mounted underneath — go to the grid, carrying the file as an
+		// anchor so it scrolls into view there.
+		const id = fileId;
+		goto('/files' + (id ? `?anchor=${id}` : ''), { noScroll: true });
+	}
+</script>
+
+<svelte:head>
+	<title>{fileId} | Tanabata</title>
+</svelte:head>
+
+{#if fileId}
+	<FileViewer {fileId} {prevId} {nextId} onNavigate={pageTo} onClose={closeViewer} />
+{/if}