.env.example

@@ -16,3 +16,13 @@ ALLOWED_ORIGINS=https://asuracomic.net,https://asurascans.com,https://demonicsca
 # Traefik HTTPS entrypoint + cert resolver names, if yours differ from these.
 # TRAEFIK_ENTRYPOINT=websecure
 # TRAEFIK_CERTRESOLVER=le
+
+# --- Web UI ---
+# Password for the browser UI at https://$MANGA_WEB_HOST. Leave unset to
+# disable the web UI entirely (the routes are not registered at all).
+# Generate one: openssl rand -base64 18
+WEB_PASSWORD=
+
+# Subdomain Traefik routes to the browser UI (prod override only). The same
+# container also answers on MANGA_API_HOST for the userscript's API.
+# MANGA_WEB_HOST=manga.example.com

CLAUDE.md

@@ -29,8 +29,17 @@ Bromite userscript (isolated world, per-site adapters, localStorage cache)
 - **Backend** (`backend/`): stdlib `net/http` (3 routes, no framework) + `modernc.org/sqlite` (pure Go, `CGO_ENABLED=0` -> static binary -> distroless/scratch image). The reverse proxy terminates TLS; the Go service listens plain `:8080`.
 - **Single-user store.** One `bookmarks` table keyed `<site>:<series_id>` (`asura`|`demonic`). Sync is **last-write-wins**. Schema and endpoint list are in the plan.
 - **Endpoints:** `GET /bookmarks`, `PUT /bookmarks/{key}` (upsert; see `updated_at` rule below), `DELETE /bookmarks/{key}`, `GET /healthz` (no auth).
+- **Web UI:** the same binary serves a password-gated browser UI on a second
+  hostname — `GET /` (list, or login page when there is no session),
+  `POST /login`, `POST /logout`, `GET /static/*`, and htmx fragment endpoints
+  under `/ui/*`. Templates and assets are `go:embed`-ed, so `backend/Dockerfile`
+  must copy `templates/` and `static/` as well as `*.go`. Sessions are stateless
+  HMAC cookies keyed off `API_TOKEN`; `WEB_PASSWORD` gates them and, when empty,
+  the web routes are not registered at all. UI mutations read-modify-write
+  through `Store.Get` + `Store.Upsert` so the `updated_at` rule stays in one
+  place. See `docs/superpowers/specs/2026-07-25-web-ui-design.md`.
 - **`updated_at` drives list order, so it moves only on real reading progress:** the server applies its timestamp when the row is new or `last_chapter_num` changes, and otherwise keeps the stored value — favouriting a series or recording a newly published chapter must not reorder the list. `PUT` therefore returns the row **as stored**, and clients must adopt that response rather than their own payload. See `plans/2026-07-25-bookmark-list-favorites-design.md` §4.
-- **Config via env:** `API_TOKEN`, `ALLOWED_ORIGINS` (comma list), `DB_PATH` (default `/data/bookmarks.db`), `PORT` (default `8080`).
+- **Config via env:** `API_TOKEN`, `ALLOWED_ORIGINS` (comma list), `DB_PATH` (default `/data/bookmarks.db`), `PORT` (default `8080`), `WEB_PASSWORD` (gates the browser UI; unset disables it).
 
 ### Userscript structure (single IIFE, `manga-bookmark.user.js`)
 

DEPLOY.md

@@ -60,6 +60,44 @@ grep -E '^API_TOKEN=' .env   # copy this — the userscript needs the same value
 
 ---
 
+## 1b. Web UI
+
+The browser UI is served by the same container on a second hostname.
+
+1. Add a DNS `A`/`AAAA` record for `manga.<yourdomain>` pointing at the server —
+   the same address as `manga-api.<yourdomain>`.
+
+2. Set both variables in `.env`:
+
+   ```ini
+   MANGA_WEB_HOST=manga.violetcrown.my.id
+   WEB_PASSWORD=<paste output of: openssl rand -base64 18>
+   ```
+
+   Generate and insert in one line:
+
+   ```bash
+   sed -i "s|^WEB_PASSWORD=.*|WEB_PASSWORD=$(openssl rand -base64 18)|" .env
+   grep -E '^WEB_PASSWORD=' .env   # this is what you type into the site
+   ```
+
+3. Redeploy and check:
+
+   ```bash
+   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+   curl -s -o /dev/null -w '%{http_code}\n' https://manga.violetcrown.my.id/
+   ```
+
+   Expected `200`, serving the login page.
+
+Leaving `WEB_PASSWORD` unset is safe: the web routes are not registered and `/`
+returns 404. The userscript's API on `MANGA_API_HOST` is unaffected either way.
+
+Sessions are signed with a key derived from `API_TOKEN`, so rotating the token
+logs every browser out. The session cookie lasts 60 days.
+
+---
+
 ## 2. Build + start
 
 ```bash

backend/.dockerignore

@@ -1,5 +1,10 @@
-# Only go source + module files are needed in the build context.
+# Only go source + module files, plus the go:embed'd templates/static
+# directories, are needed in the build context.
 *
 !go.mod
 !go.sum
 !*.go
+!templates/
+!templates/**
+!static/
+!static/**

backend/Dockerfile

@@ -9,7 +9,11 @@ COPY go.mod go.sum ./
 RUN go mod download
 
 # Then source (changes often).
+# Source plus the go:embed'd assets. Missing either directory turns the embed
+# directive into a build error, so both must be copied before `go build`.
 COPY *.go ./
+COPY templates/ ./templates/
+COPY static/ ./static/
 
 # Static binary: pure-Go sqlite means CGO_ENABLED=0 -> no libc dependency.
 # -trimpath + -ldflags strip paths and debug info for a smaller image.

docker-compose.prod.yml

@@ -5,6 +5,7 @@
 #
 # Set in .env:
 #   MANGA_API_HOST=manga-api.example.com   # your subdomain (required)
+#   MANGA_WEB_HOST=manga.example.com        # browser UI subdomain, same container
 #   PROXY_NETWORK=proxy                     # Traefik's network name, if not "proxy"
 #   TRAEFIK_ENTRYPOINT=websecure            # your HTTPS entrypoint name
 #   TRAEFIK_CERTRESOLVER=le                 # your ACME/cert resolver name
@@ -26,6 +27,14 @@ services:
       - "traefik.http.routers.mangabm.tls=true"
       - "traefik.http.routers.mangabm.tls.certresolver=${TRAEFIK_CERTRESOLVER:-le}"
       - "traefik.http.services.mangabm.loadbalancer.server.port=8080"
+      # Second hostname for the browser UI, same container. Traefik needs the
+      # service named explicitly once more than one router targets it.
+      - "traefik.http.routers.mangabm.service=mangabm"
+      - "traefik.http.routers.mangaweb.rule=Host(`${MANGA_WEB_HOST:-manga.example.com}`)"
+      - "traefik.http.routers.mangaweb.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
+      - "traefik.http.routers.mangaweb.tls=true"
+      - "traefik.http.routers.mangaweb.tls.certresolver=${TRAEFIK_CERTRESOLVER:-le}"
+      - "traefik.http.routers.mangaweb.service=mangabm"
 
 networks:
   proxy:

docker-compose.yml

@@ -18,6 +18,8 @@ services:
       ALLOWED_ORIGINS: ${ALLOWED_ORIGINS:-https://asuracomic.net,https://asurascans.com,https://demonicscans.org}
       DB_PATH: /data/bookmarks.db
       PORT: "8080"
+      # Gates the browser UI. Unset means the web routes are not served at all.
+      WEB_PASSWORD: ${WEB_PASSWORD:-}
     volumes:
       - bookmarks-data:/data
     # Bound to loopback only: the proxy (or curl during smoke test) reaches it,