no string for maintenance mode

* add bug to todo

* disabled import study button if no study ID is selected, but always show if logged in as not to break the layout

* basic import of lichess study link

* change interface import

* Minmax M3 solution to import study chapter/game functionality

* change button text

* fix toast to display on study and chapter load

* add lint and format fix scripts

* apply auto formatting

* update ignored directories

* fix specificity

* add rudimentary PDF count metrics

* allow docker build

* create maintenance mode banner, triggered by env variables

.env.example

@@ -1,4 +1,9 @@
+VITE_API_BASE_URL=
+VITE_MATOMO_URL=
+VITE_MATOMO_SITE_ID=
+VITE_MAINTENANCE_MODE=  # nothing = false, anything else = true
+VITE_MAINTENANCE_MODE_MESSAGE="ChessScribe is currently undergoing maintenance. Some features may be unavailable."
+
 DISCORD_CONTACT_WEBHOOK=
 DISCORD_ERROR_LOG_WEBHOOK=
 LICHESS_CLIENT_ID=
-VITE_API_BASE_URL=

.github/workflows/production.yml

@@ -0,0 +1,59 @@
+name: Production Deploy
+
+on:
+  push:
+    branches: [main]
+
+env:
+  REGISTRY: ghcr.io
+  GH_USER: therealowenrees
+  IMAGE_NAME: therealowenrees/chess-scribe:latest
+
+jobs:
+  publish:
+    name: publish image
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Login to Github Container Registry
+        run: echo "${{ secrets.GHCR_SECRET }}" | docker login ghcr.io -u ${{ env.GH_USER }} --password-stdin
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build image and publish with Cache
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            VITE_API_BASE_URL=https://api.chess-scribe.org/api/v1
+            VITE_MATOMO_URL=https://analytics.owenrees.eu
+            VITE_MATOMO_SITE_ID="3"
+            VITE_MAINTENANCE_MODE=
+            VITE_MAINTENANCE_MODE_MESSAGE="ChessScribe is currently undergoing maintenance. Some features may be unavailable."
+
+  deploy:
+    needs: publish
+    name: deploy image
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Connect and pull image from GHCR
+        uses: appleboy/ssh-action@v1.2.5
+        with:
+          host: ${{ secrets.HOST }}
+          username: ${{ secrets.USERNAME }}
+          key: ${{ secrets.SSH_KEY }}
+          port: ${{ secrets.PORT }}
+          script: |
+            cd /home/${{ secrets.USERNAME }}
+            echo "${{ secrets.GHCR_SECRET }}" | docker login ghcr.io -u ${{ env.GH_USER }} --password-stdin
+            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+            docker compose up -d

.gitignore

@@ -11,3 +11,4 @@ dist-ssr
 .vinxi
 __unconfig*
 todos.json
+data

Dockerfile

@@ -0,0 +1,38 @@
+# --- Stage 1: Build Stage ---
+FROM node:24-alpine AS builder
+WORKDIR /app
+
+# 1. Declare the build-time arguments Vite needs
+ARG VITE_API_BASE_URL
+ARG VITE_MATOMO_URL
+ARG VITE_MATOMO_SITE_ID
+ARG VITE_MAINTENANCE_MODE
+ARG VITE_MAINTENANCE_MODE_MESSAGE
+
+# 2. Assign them to environment variables so Vite detects them
+ENV VITE_API_BASE_URL=$VITE_API_BASE_URL
+ENV VITE_MATOMO_URL=$VITE_MATOMO_URL
+ENV VITE_MATOMO_SITE_ID=$VITE_MATOMO_SITE_ID
+ENV VITE_MAINTENANCE_MODE=$VITE_MAINTENANCE_MODE
+ENV VITE_MAINTENANCE_MODE_MESSAGE=$VITE_MAINTENANCE_MODE_MESSAGE
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+RUN corepack enable pnpm && pnpm i --frozen-lockfile
+COPY . .
+RUN pnpm run build
+
+# --- Stage 2: Production Stage ---
+FROM node:24-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOST=0.0.0.0
+
+# Nitro compiles everything needed into the .output directory
+COPY --from=builder /app/.output ./.output
+
+EXPOSE 3000
+
+# Run the compiled Nitro server
+CMD ["node", ".output/server/index.mjs"]

TODO

@@ -1,9 +1,13 @@
 - og / json-sd
-- Lichess login
 - logger
-- bring sections headers on all pages other than home page further up (reduce top margin / padding)
 - set game current position on game load to ply 0 and whatever the FEN is (starting position probably, but could be custom position)
 - privacy policy - have no access to anything you generate, only keep a count of success/failed pdf generations with timestamp and error message
-- a11y and lighthouse fixes
-- check wcag compliance
-- white background?
+- check wcag compliance - footer colour contrast
+- 429 lichess error handling - retry after 10 seconds
+- try/catch where needed in client code
+- generate state and check it against the state returned from lichess https://lichess.org/api#tag/oauth/GET/oauth
+- checkbox and toggle disabled states
+- react query on for study and chapter load, to allow caching
+- https://specification.website/checklist/
+
+- react query to cache the study and chapters

biome.json

@@ -13,7 +13,12 @@
 			"**/index.html",
 			"**/vite.config.ts",
 			"!**/src/routeTree.gen.ts",
-			"!**/src/styles.css"
+			"!**/src/styles.css",
+			"!**/.tanstack/*",
+			"!**/.output/*",
+			"!**/.nitro/*",
+			"!**/node_modules/*",
+			"!**/styles/vendor/*"
 		]
 	},
 	"formatter": {
@@ -33,4 +38,3 @@
 		}
 	}
 }
-

docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  chess-scribe-frontend:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+    env_file:
+      - .env
+    restart: unless-stopped

package.json

@@ -6,11 +6,14 @@
     "#/*": "./src/*"
   },
   "scripts": {
-    "dev": "vite dev --port 3000",
+    "dev": "vite dev --port 3000 --host",
     "build": "vite build",
     "preview": "vite preview",
+    "start": "node .output/server/index.mjs",
     "test": "vitest run",
+    "lint:fix": "biome lint --write",
     "format": "biome format",
+    "format:fix": "biome format --write",
     "lint": "biome lint",
     "check": "biome check"
   },
@@ -48,11 +51,5 @@
     "typescript": "^6.0.2",
     "vite": "^8.0.0",
     "vitest": "^4.1.5"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "lightningcss"
-    ]
   }
 }

pnpm-lock.yaml

@@ -315,6 +315,9 @@ packages:
   '@emnapi/runtime@1.10.0':
     resolution: {integrity: sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==}
 
+  '@emnapi/runtime@1.11.1':
+    resolution: {integrity: sha512-vgj7R3y3Wgx24IQaGPA/R6YFXLHVMOZ0uVEyIQPaWs+rd1AzfEMXlAC22FYwO1XkKR6NPsq7mUandH8oIRdZFw==}
+
   '@emnapi/wasi-threads@1.2.1':
     resolution: {integrity: sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==}
 
@@ -1903,8 +1906,8 @@ packages:
     resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
     hasBin: true
 
-  semver@7.8.1:
-    resolution: {integrity: sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg==}
+  semver@7.8.5:
+    resolution: {integrity: sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==}
     engines: {node: '>=10'}
     hasBin: true
 
@@ -2489,6 +2492,11 @@ snapshots:
       tslib: 2.8.1
     optional: true
 
+  '@emnapi/runtime@1.11.1':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
   '@emnapi/wasi-threads@1.2.1':
     dependencies:
       tslib: 2.8.1
@@ -2583,7 +2591,7 @@ snapshots:
 
   '@img/sharp-wasm32@0.34.5':
     dependencies:
-      '@emnapi/runtime': 1.10.0
+      '@emnapi/runtime': 1.11.1
     optional: true
 
   '@img/sharp-win32-arm64@0.34.5':
@@ -3912,7 +3920,7 @@ snapshots:
 
   semver@6.3.1: {}
 
-  semver@7.8.1:
+  semver@7.8.5:
     optional: true
 
   seroval-plugins@1.5.4(seroval@1.5.4):
@@ -3925,7 +3933,7 @@ snapshots:
     dependencies:
       '@img/colour': 1.1.0
       detect-libc: 2.1.2
-      semver: 7.8.1
+      semver: 7.8.5
     optionalDependencies:
       '@img/sharp-darwin-arm64': 0.34.5
       '@img/sharp-darwin-x64': 0.34.5

pnpm-workspace.yaml

@@ -0,0 +1,9 @@
+# pnpm v11 configuration file
+packages:
+  - "."
+
+# This replaces 'onlyBuiltDependencies'
+allowBuilds:
+  "sharp": true
+  "esbuild": true
+  "lightningcss": true

public/site.webmanifest

@@ -0,0 +1 @@
+{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}

src/components/AccordionItem.tsx

@@ -9,10 +9,7 @@ interface IProps {
 const AccordionItem = ({ title, id, children }: IProps) => (
 	<div className="hero__accordion-item">
 		<details className="hero__accordion-details" name="linked">
-			<summary
-				className="hero__accordion-item__summary"
-				aria-describedby={title}
-			>
+			<summary className="hero__accordion-item__summary" id={`${id}-summary`}>
 				<span className="hero__accordion-item__title-container">
 					<span className="hero__accordion-item__title">{title}</span>
 				</span>

src/components/CoffeeWidget.tsx

@@ -13,6 +13,7 @@ const CoffeeWidget = ({ height, width }: IProps) => {
 			target="_blank"
 			className="ml-auto flex items-center gap-2 text-sm"
 			rel="noopener"
+			aria-label="Buy Me A Coffee"
 		>
 			<Image
 				src={buyMeACoffeeLogo}

src/components/CustomHeaders.tsx

@@ -9,7 +9,7 @@ interface IProps {
 
 const CustomHeaders = ({ headers, updateHeaders }: IProps) => {
 	return (
-		<div className="mt-4 w-full max-w-175">
+		<div className="mt-4 w-full max-w-150">
 			<details className="bg-(--neutral-content)/20 p-4 rounded-lg">
 				<summary>
 					Custom Headers (PDF)

src/components/Feature.tsx

@@ -7,7 +7,7 @@ interface IProps {
 
 const Feature = ({ title, children }: IProps) => (
 	<div className="mb-auto">
-		<h6 className="text-(--neutral-content) text-2xl font-bold">{title}</h6>
+		<h5 className="text-(--neutral-content) text-2xl font-bold">{title}</h5>
 		<p className="text-(--neutral-content) font-medium" data-testid="text">
 			{children}
 		</p>

src/components/Footer.tsx

@@ -10,26 +10,26 @@ import footerLogo from "@/assets/images/footerLogo.svg?url";
 export default function Footer() {
 	return (
 		<footer className="text-white w-full grid-cols-2 items-center bg-(--accent) px-10 py-5">
-			<div className="flex w-full items-center">
-				<Link to="/">
+			<div className="flex w-full items-center gap-2">
+				<Link to="/" aria-label="Home">
 					<Image
 						src={footerLogo}
 						alt="ChessScribe Logo"
 						width={10}
 						height={10}
 						className="hidden h-10 w-10 sm:block"
+						aria-label="ChessScribe Logo"
 					/>
 				</Link>
 				<div>
-					<p data-testid="copyright">
-						Copyright © 2023 - {new Date().getFullYear()}
-					</p>
+					<p>© 2023 - {new Date().getFullYear()}</p>
 				</div>
 				<div className="ml-auto flex gap-2">
 					<a
 						href={GITHUB_URL}
 						target="_blank"
 						rel="noopener noreferrer"
+						aria-label="GitHub"
 						className="text-2xl hover:text-(--neutral-content) transition-colors duration-300 ease-in-out cursor-pointer"
 					>
 						<LuGithub />
@@ -38,6 +38,7 @@ export default function Footer() {
 					<Link
 						to="/contact"
 						rel="noopener noreferrer"
+						aria-label="Contact"
 						className="text-2xl hover:text-(--neutral-content) transition-colors duration-300 ease-in-out"
 					>
 						<LuMail />

src/components/GenericErrorView.tsx

@@ -0,0 +1,68 @@
+import { useNavigate, useRouter } from "@tanstack/react-router";
+
+interface GenericErrorViewProps {
+	error?: Error | unknown;
+	resetErrorBoundary?: () => void;
+}
+
+const GenericErrorView = ({
+	error,
+	resetErrorBoundary,
+}: GenericErrorViewProps) => {
+	const router = useRouter();
+	const navigate = useNavigate();
+
+	const errorMessage =
+		error instanceof Error
+			? error.message
+			: "An unexpected system error occurred.";
+
+	const handleTryAgain = async () => {
+		if (resetErrorBoundary) {
+			resetErrorBoundary();
+		}
+
+		await router.invalidate();
+		const currentSearch = router.state.location.search;
+		await navigate({ to: ".", search: currentSearch });
+	};
+
+	return (
+		<div className="flex min-h-[calc(100vh-194px)] flex-col items-center justify-center p-6">
+			<div className="relative flex max-w-md flex-col items-center text-center">
+				<h1 className="text-2xl font-bold tracking-tight mb-2 text-(--accent)">
+					Something went wrong
+				</h1>
+				<p className="text-sm text-(--neutral-content) mb-6 max-w-sm">
+					The application encountered an issue it couldn't recover from.
+				</p>
+
+				<div className="w-full mb-8 rounded-md bg-slate-300/60 border border-slate-800/80 p-4 text-left font-mono text-xs text-red-400 max-h-32 overflow-y-auto">
+					<span className="text-(--base-content) block mb-1">Error Logs:</span>
+					{errorMessage}
+				</div>
+
+				<div className="flex w-full gap-3 justify-center">
+					{resetErrorBoundary && (
+						<button
+							type="button"
+							onClick={handleTryAgain}
+							className="btn btn-secondary"
+						>
+							Try Again
+						</button>
+					)}
+					<button
+						type="button"
+						onClick={() => navigate({ to: "/" })}
+						className="btn btn-primary"
+					>
+						Go Home
+					</button>
+				</div>
+			</div>
+		</div>
+	);
+};
+
+export default GenericErrorView;

src/components/Header.tsx

@@ -1,11 +1,26 @@
 import { Link } from "@tanstack/react-router";
 import { Image } from "@unpic/react";
-
+import { z } from "zod";
+import MaintenanceModeBanner from "#/components/MaintenanceModeBanner.tsx";
+import { env } from "#/env.ts";
 import logo from "@/assets/images/logo.svg?url";
 
 export default function Header() {
+	const maintenanceModeMessage = env.VITE_MAINTENANCE_MODE
+		? z
+				.string()
+				.transform((value) => (value.trim() === "" ? null : value))
+				.parse(env.VITE_MAINTENANCE_MODE_MESSAGE)
+		: null;
+
 	return (
 		<header>
+			{maintenanceModeMessage ? (
+				<div className="absolute w-full">
+					<MaintenanceModeBanner message={maintenanceModeMessage} />
+				</div>
+			) : null}
+
 			<nav className="w-full max-w-screen-2xl place-self-center p-8">
 				<div className="container mx-auto flex items-center justify-between">
 					<div className="flex items-center">

src/components/HeaderFields.tsx

@@ -9,7 +9,7 @@ interface IProps {
 
 const HeaderFields = ({ headers, updateHeaders }: IProps) => {
 	return (
-		<div className="mt-4 w-full max-w-175">
+		<div className="mt-4 w-full max-w-150">
 			<details className="bg-(--neutral-content)/15 p-4 rounded-lg">
 				<summary>
 					Headers

src/components/LichessButton.tsx

@@ -6,12 +6,12 @@ const LichessButton = () => {
 	const { user } = useLichessUser();
 
 	const onClickHandler = () => {
-		return user?.isLoggedIn ? lichessLogout() : lichessLogin();
+		return user ? lichessLogout() : lichessLogin();
 	};
 
 	return (
 		<button
-			className="text-(--accent) border rounded-xl px-6 py-3 cursor-pointer flex items-center gap-2 p-2 hover:bg-(--accent) hover:text-(--header-bg) transition-colors duration-300 ease-in-out"
+			className="w-full text-(--accent) border rounded-xl px-6 py-3 cursor-pointer flex items-center justify-center gap-2 p-2 hover:bg-(--accent) hover:text-(--header-bg) transition-colors duration-300 ease-in-out"
 			onClick={onClickHandler}
 			type="button"
 		>
@@ -26,9 +26,7 @@ const LichessButton = () => {
 				</svg>
 			</div>
 
-			<p>
-				{user?.isLoggedIn ? `Logout ${user.username}` : "Log into Lichess.org"}
-			</p>
+			<p>{user ? `Logout ${user.username}` : "Log into Lichess.org"}</p>
 		</button>
 	);
 };

src/components/LichessStudyLinkInput.tsx

@@ -0,0 +1,61 @@
+import type { FormEvent } from "react";
+import { toast } from "react-toastify";
+import { useLichess } from "#/hooks/useLichess.ts";
+
+interface IProps {
+	setSelectedStudyId: (id: string) => void;
+}
+
+const LichessStudyLinkInput = ({ setSelectedStudyId }: IProps) => {
+	const { parseLichessStudyLink } = useLichess();
+
+	const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+		e.preventDefault();
+		const formData = new FormData(e.currentTarget);
+		const studyLink = formData.get("lichess-study-link");
+
+		if (!studyLink) return;
+
+		if (typeof studyLink !== "string") {
+			toast.error("Invalid study link");
+			return;
+		}
+
+		const result = parseLichessStudyLink(studyLink);
+
+		if (!result.ok) {
+			toast.error(result.error);
+			return;
+		}
+
+		console.log(result.data);
+
+		setSelectedStudyId(result.data);
+		toast.success("Study loaded — pick a chapter");
+	};
+
+	return (
+		<form className="flex items-end gap-2" onSubmit={handleSubmit}>
+			<div>
+				<label htmlFor="lichess-study-link" className="text-sm capitalize">
+					Lichess Study Link
+				</label>
+				<input
+					className="border rounded-md p-2 w-full"
+					type="text"
+					id="lichess-study-link"
+					name="lichess-study-link"
+					placeholder="https://lichess.org/study/..."
+				/>
+			</div>
+			<button
+				type="submit"
+				className="border py-2 px-3 rounded-md cursor-pointer bg-(--accent) text-white hover:bg-transparent hover:text-(--accent) transition-colors duration-300 ease-in-out"
+			>
+				Submit
+			</button>
+		</form>
+	);
+};
+
+export default LichessStudyLinkInput;

src/components/LichessStudyUrlInput.tsx

@@ -1,110 +0,0 @@
-import { useState } from "react";
-import { useLichess } from "#/hooks/useLichess.ts";
-
-const parseStudyId = (url: string): string | null => {
-	const match = url.match(
-		/(?:https?:\/\/)?(?:www\.)?lichess\.org\/study\/([a-zA-Z0-9]+)/,
-	);
-	return match?.[1] ?? null;
-};
-
-const LichessStudyUrlInput = () => {
-	const [url, setUrl] = useState("");
-	const [feedback, setFeedback] = useState<{
-		type: "success" | "error";
-		message: string;
-	} | null>(null);
-
-	const { setSelectedStudyId, selectedStudyId } = useLichess();
-
-	const handleSubmit = () => {
-		if (!url.trim()) {
-			setFeedback({ type: "error", message: "Please enter a study URL" });
-			return;
-		}
-
-		const studyId = parseStudyId(url.trim());
-
-		if (!studyId) {
-			setFeedback({
-				type: "error",
-				message: "Invalid Lichess study URL",
-			});
-			return;
-		}
-
-		if (studyId === selectedStudyId) {
-			setFeedback({
-				type: "success",
-				message: "Study already selected",
-			});
-			return;
-		}
-
-		setSelectedStudyId(studyId);
-		setFeedback({ type: "success", message: "Study loaded — pick a chapter" });
-	};
-
-	const handleKeyDown = (e: React.KeyboardEvent) => {
-		if (e.key === "Enter") handleSubmit();
-	};
-
-	return (
-		<div className="flex items-center gap-2 min-w-[500px]">
-			<div className="relative flex-1">
-				<span className="absolute left-3 top-1/2 -translate-y-1/2 text-(--neutral-content) pointer-events-none">
-					<svg
-						xmlns="http://www.w3.org/2000/svg"
-						width="16"
-						height="16"
-						viewBox="0 0 24 24"
-						fill="none"
-						stroke="currentColor"
-						strokeWidth="2"
-						strokeLinecap="round"
-						strokeLinejoin="round"
-						aria-hidden="true"
-					>
-						<path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" />
-						<path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" />
-					</svg>
-				</span>
-				<input
-					type="url"
-					placeholder="Lichess Study URL"
-					value={url}
-					onChange={(e) => {
-						setUrl(e.target.value);
-						if (feedback) setFeedback(null);
-					}}
-					onKeyDown={handleKeyDown}
-					className={`w-full h-12 pl-10 pr-4 rounded-lg border text-(--base-content) placeholder-(--neutral-content)/50 outline-hidden transition-all duration-200 focus:border-(--accent) focus:outline-3 focus:outline-offset-2 focus:outline-(--accent)/50 ${
-						feedback?.type === "error"
-							? "border-red-500"
-							: "border-(--neutral-content)"
-					}`}
-				/>
-			</div>
-
-			<button
-				type="button"
-				className="btn btn-secondary px-6 whitespace-nowrap"
-				onClick={handleSubmit}
-			>
-				Load Study
-			</button>
-
-			{feedback ? (
-				<span
-					className={`text-sm whitespace-nowrap ${
-						feedback.type === "error" ? "text-red-500" : "text-(--accent)"
-					}`}
-				>
-					{feedback.message}
-				</span>
-			) : null}
-		</div>
-	);
-};
-
-export default LichessStudyUrlInput;

src/components/LoadingView.tsx

@@ -0,0 +1,34 @@
+interface IProps {
+	title?: string;
+	description?: string;
+}
+
+const LoadingView = ({ title, description }: IProps) => {
+	return (
+		<div className="flex min-h-[calc(100vh-194px)] flex-col items-center justify-center p-6 bg-base-100">
+			<div className="relative flex max-w-sm flex-col items-center text-center">
+				{/* Animated Custom Loader */}
+				<div className="relative mb-6 flex h-16 w-16 items-center justify-center">
+					{/* Outer Pulsing Ring */}
+					<div className="absolute inset-0 animate-ping rounded-full bg-(--accent) opacity-20 [animation-duration:1.5s]"></div>
+
+					{/* Inner Spinning Ring */}
+					<div className="h-12 w-12 animate-spin rounded-full border-4 border-(--accent) border-t-transparent"></div>
+				</div>
+
+				{/* Loading Content */}
+				<h2 className="text-xl font-bold tracking-tight mb-2 text-(--base-content)">
+					{title || "Loading Data"}
+				</h2>
+				<p className="text-sm text-(--neutral-content) max-w-xs">
+					{description || "Please wait a moment while we load the data."}
+				</p>
+
+				{/* Decorative background glow matching your layout */}
+				<div className="absolute -inset-10 -z-10 bg-(--accent)/5 blur-2xl rounded-full pointer-events-none" />
+			</div>
+		</div>
+	);
+};
+
+export default LoadingView;

src/components/MaintenanceModeBanner.tsx

@@ -0,0 +1,13 @@
+interface IProps {
+	message?: string;
+}
+
+const DEFAULT_MESSAGE = "Maintenance Mode";
+
+const MaintenanceModeBanner = ({ message }: IProps) => (
+	<div className="bg-orange-400 text-white text-center py-1 w-full text-sm">
+		<p>{message || DEFAULT_MESSAGE}</p>
+	</div>
+);
+
+export default MaintenanceModeBanner;

src/components/MatomoAnalytics.tsx

@@ -1,9 +1,10 @@
 import { trackAppRouter } from "@socialgouv/matomo-next";
 import { useLocation, useSearch } from "@tanstack/react-router";
 import { useEffect } from "react";
+import { env } from "#/env.ts";
 
-const MATOMO_URL = import.meta.env.NEXT_PUBLIC_MATOMO_URL;
-const MATOMO_SITE_ID = import.meta.env.NEXT_PUBLIC_MATOMO_SITE_ID;
+const MATOMO_URL = env.VITE_MATOMO_URL;
+const MATOMO_SITE_ID = env.VITE_MATOMO_SITE_ID;
 
 export function MatomoAnalytics() {
 	const location = useLocation();

src/components/NotFoundView.tsx

@@ -0,0 +1,21 @@
+import { Link } from "@tanstack/react-router";
+
+const NotFoundView = () => {
+	return (
+		<div className="flex min-h-[calc(100vh-194px)] flex-col items-center justify-center p-6">
+			<div className="relative flex max-w-md flex-col items-center text-center">
+				<h1 className="text-2xl font-bold tracking-tight mb-4 text-(--accent)">
+					The page you are looking for does not exist.
+				</h1>
+
+				<div className="flex w-full gap-3 justify-center">
+					<Link to="/" className="btn btn-primary">
+						Go Home
+					</Link>
+				</div>
+			</div>
+		</div>
+	);
+};
+
+export default NotFoundView;

src/components/Section.tsx

@@ -14,7 +14,7 @@ const Section = ({ title, smallTitle, description, children }: IProps) => {
 
 	return (
 		<section className="mx-auto mt-8 grid max-w-5xl place-items-center gap-4 p-8 text-center md:grid-cols-3 md:text-left text-(--accent)">
-			<h3 className="col-span-full mb-4 text-center text-lg font-bold tracking-wider text-primary">
+			<h3 className="col-span-full mb-4 text-center text-2xl font-bold tracking-wider text-primary">
 				{smallTitle}
 			</h3>
 			<h4 className="col-span-full mb-4 text-center text-4xl font-extrabold text-(--neutral-content) md:text-5xl">

src/components/SelectLichessStudy.tsx

@@ -1,16 +1,16 @@
 import { useRef, useState } from "react";
+import { toast } from "react-toastify";
 import { useClickOutside } from "#/hooks/useClickOutside.ts";
-import { type IUserStudyChapter, useLichess } from "#/hooks/useLichess.ts";
+import { useLichess } from "#/hooks/useLichess.ts";
 
 interface IProps {
 	setSelectedStudyId: (studyId: string) => void;
-	setStudyChapters: (chapters: IUserStudyChapter[]) => void;
 }
 
 const SelectLichessStudy = ({ setSelectedStudyId }: IProps) => {
 	const [isOpen, setIsOpen] = useState(false);
 	const [search, setSearch] = useState("");
-	const { getLichessUserStudies, userStudies } = useLichess();
+	const { getLichessUserStudies, userStudies, setUserStudies } = useLichess();
 	const dropdownRef = useRef<HTMLDivElement>(null);
 
 	const filteredStudies = userStudies.filter((study) =>
@@ -20,15 +20,20 @@ const SelectLichessStudy = ({ setSelectedStudyId }: IProps) => {
 	const onClickHandler = async () => {
 		setIsOpen(!isOpen);
 
-		if (!userStudies.length) {
-			await getLichessUserStudies();
+		if (userStudies.length) return;
+
+		const result = await getLichessUserStudies();
+		if (result.ok) {
+			setUserStudies(result.data);
 		}
 	};
 
 	const handleStudyClick = async (studyId: string) => {
+		const study = userStudies.find((s) => s.id === studyId);
 		setSelectedStudyId(studyId);
 		setIsOpen(false);
 		setSearch("");
+		toast.success(`Loaded study "${study?.name ?? studyId}"`);
 	};
 
 	useClickOutside({ isOpen, setIsOpen, setSearch, ref: dropdownRef });

src/components/SelectStudyChapter.tsx

@@ -1,6 +1,14 @@
-import { type Dispatch, useRef, useState } from "react";
-import { useClickOutside } from "#/hooks/useClickOutside.ts";
-import { type IUserStudyChapter, useLichess } from "#/hooks/useLichess.ts";
+import {
+	type Dispatch,
+	useActionState,
+	useEffect,
+	// useRef,
+	useState,
+} from "react";
+import { toast } from "react-toastify";
+// import { useClickOutside } from "#/hooks/useClickOutside.ts";
+import { useLichess } from "#/hooks/useLichess.ts";
+import type { IUserStudyChapter } from "#/interfaces.ts";
 import type { GameAction } from "#/reducers/gameReducer.ts";
 
 interface IProps {
@@ -8,26 +16,68 @@ interface IProps {
 	gameDispatch: Dispatch<GameAction>;
 }
 
+type ChapterState = {
+	status: "idle" | "success" | "error";
+	chapters: IUserStudyChapter[];
+	error: string | null;
+};
+
+const initialChapterState: ChapterState = {
+	status: "idle",
+	chapters: [],
+	error: null,
+};
+
 const SelectStudyChapter = ({ selectedStudyId, gameDispatch }: IProps) => {
 	const [isOpen, setIsOpen] = useState(false);
-	const [studyChapters, setStudyChapters] = useState<IUserStudyChapter[]>([]);
 	const [search, setSearch] = useState("");
-	const dropdownRef = useRef<HTMLDivElement>(null);
+	// const dropdownRef = useRef<HTMLDivElement>(null);
 
 	const { getLichessStudyChapters, loadLichessStudyChapter } = useLichess();
 
-	const filteredChapters = studyChapters.filter((chapter) =>
+	const [chapterState, fetchChaptersAction, isPending] = useActionState(
+		async (_prev: ChapterState, _formData: FormData): Promise<ChapterState> => {
+			if (!selectedStudyId) {
+				return {
+					status: "error",
+					chapters: [],
+					error: "No study selected.",
+				} satisfies ChapterState;
+			}
+			const result = await getLichessStudyChapters({
+				studyId: selectedStudyId,
+			});
+
+			console.log(result);
+
+			if (result.ok) {
+				return {
+					status: "success",
+					chapters: result.data,
+					error: null,
+				} satisfies ChapterState;
+			}
+
+			return {
+				status: "error",
+				chapters: [],
+				error: result.error,
+			} satisfies ChapterState;
+		},
+		initialChapterState,
+	);
+
+	const filteredChapters = chapterState.chapters.filter((chapter) =>
 		chapter.name.toLowerCase().includes(search.toLowerCase()),
 	);
 
-	useClickOutside({ isOpen, setIsOpen, setSearch, ref: dropdownRef });
+	// useClickOutside({ isOpen, setIsOpen, setSearch, ref: dropdownRef });
 
-	const onClickHandler = async () => {
-		const studies = await getLichessStudyChapters({ studyId: selectedStudyId });
-		if (!studies) return;
-		setStudyChapters(studies);
-		setIsOpen(!isOpen);
-	};
+	useEffect(() => {
+		if (isPending || chapterState.status === "success") {
+			setIsOpen(true);
+		}
+	}, [isPending, chapterState.status]);
 
 	const handleChapterClick = async (chapter: IUserStudyChapter) => {
 		const { headers, pgn } = await loadLichessStudyChapter({ chapter });
@@ -36,16 +86,22 @@ const SelectStudyChapter = ({ selectedStudyId, gameDispatch }: IProps) => {
 
 		setIsOpen(false);
 		setSearch("");
+		toast.success(`Loaded chapter "${chapter.name}"`);
 	};
 
 	return (
-		<div ref={dropdownRef} className="relative">
-			<button
-				type="button"
-				className="btn btn-secondary"
-				onClick={onClickHandler}
+		<form
+			key={selectedStudyId}
+			action={fetchChaptersAction}
+			className="relative"
 		>
-				Import Study Chapter/Game
+			<input type="hidden" name="studyId" value={selectedStudyId} />
+			<button
+				type="submit"
+				className="btn btn-secondary"
+				disabled={!selectedStudyId || isPending}
+			>
+				{isPending ? "Loading chapters…" : "Import Chapter"}
 			</button>
 
 			{isOpen ? (
@@ -79,7 +135,11 @@ const SelectStudyChapter = ({ selectedStudyId, gameDispatch }: IProps) => {
 
 					<hr className="border-(--neutral-content)/15 my-2" />
 
-					{filteredChapters.length > 0 ? (
+					{isPending ? (
+						<p className="text-(--neutral-content) text-sm text-center py-4">
+							Loading chapters…
+						</p>
+					) : filteredChapters.length > 0 ? (
 						<ul>
 							{filteredChapters.map((chapter) => (
 								<li key={`${chapter.chapterId}${chapter.name}`}>
@@ -100,7 +160,7 @@ const SelectStudyChapter = ({ selectedStudyId, gameDispatch }: IProps) => {
 					)}
 				</div>
 			) : null}
-		</div>
+		</form>
 	);
 };
 

src/context/LichessUserContext.tsx

@@ -9,14 +9,10 @@ import {
 	useEffect,
 	useState,
 } from "react";
-
+import type { ISession } from "#/interfaces.ts";
 import { getSession } from "#/server/lichess.ts";
 
-interface ILichessUser {
-	username: string;
-	id: string;
-	isLoggedIn: boolean;
-}
+interface ILichessUser extends Omit<ISession, "token"> {}
 
 interface ILichessUserContextType {
 	user: ILichessUser | null;
@@ -38,7 +34,6 @@ export const LichessUserProvider = ({ children }: { children: ReactNode }) => {
 				setUser({
 					username: session.username,
 					id: session.id,
-					isLoggedIn: true,
 				});
 			}
 		})();

src/env.ts

@@ -1,7 +1,11 @@
 import { z } from "zod";
 
 const clientSchema = z.object({
-	VITE_API_BASE_URL: z.string("Invalid API Base URL format"),
+	VITE_API_BASE_URL: z.url("Invalid API Base URL format"),
+	VITE_MATOMO_URL: z.url("Invalid URL format"),
+	VITE_MATOMO_SITE_ID: z.string("Invalid Site ID"),
+	VITE_MAINTENANCE_MODE: z.string("Invalid Maintenance Mode"),
+	VITE_MAINTENANCE_MODE_MESSAGE: z.string().optional(),
 });
 
 const serverSchema = z.object({
@@ -23,6 +27,7 @@ const getEnv = () => {
 		const _env = fullSchema.safeParse(rawEnv);
 		if (!_env.success) {
 			console.error("❌ Invalid Server Environment Variables:");
+			console.error(JSON.stringify(_env.error.format(), null, 2));
 			throw new Error("Invalid environment variables");
 		}
 		return _env.data;
@@ -30,6 +35,7 @@ const getEnv = () => {
 		const _env = clientSchema.safeParse(rawEnv);
 		if (!_env.success) {
 			console.error("❌ Invalid Client Environment Variables:");
+			console.error(JSON.stringify(_env.error.format(), null, 2));
 			throw new Error("Invalid environment variables");
 		}
 		return _env.data as z.infer<typeof fullSchema>;

src/hooks/useChessGame.ts

@@ -1,3 +1,4 @@
+import { useServerFn } from "@tanstack/react-start";
 import {
 	type ChangeEvent,
 	useCallback,
@@ -9,6 +10,7 @@ import { toast } from "react-toastify";
 import { env } from "#/env.ts";
 import type { IHeader, IPosition } from "#/interfaces.ts";
 import { gameReducer, initialGameState } from "#/reducers/gameReducer.ts";
+import { recordPdfSuccess } from "#/server/pdfMetrics.ts";
 import { downloadPDF } from "#/utils/pdfUtils.ts";
 import { buildPgnString, getHeaders } from "#/utils/pgnUtils.ts";
 import { downloadString } from "#/utils/stringUtils.ts";
@@ -16,6 +18,8 @@ import { downloadString } from "#/utils/stringUtils.ts";
 export const useChessGame = () => {
 	const [gameState, gameDispatch] = useReducer(gameReducer, initialGameState);
 
+	const recordPdfSuccessFn = useServerFn(recordPdfSuccess);
+
 	const [currentPosition, setCurrentPosition] = useState<IPosition>({
 		ply: 0,
 		fen: "",
@@ -66,7 +70,7 @@ export const useChessGame = () => {
 			if (response.ok) {
 				downloadPDF(await response.blob());
 
-				// TODO add metrics logger - add success to analytics
+				await recordPdfSuccessFn();
 
 				toast.success("PDF successfully generated!", {
 					toastId: "pdf-success",

src/hooks/useLichess.ts

@@ -1,7 +1,11 @@
-import { useNavigate } from "@tanstack/react-router";
 import { useServerFn } from "@tanstack/react-start";
 import { useEffect, useState } from "react";
 import { useLichessUser } from "#/context/LichessUserContext.tsx";
+import type {
+	ITokenData,
+	IUserStudy,
+	IUserStudyChapter,
+} from "#/interfaces.ts";
 import {
 	getSession,
 	getStudyChapters,
@@ -14,32 +18,37 @@ import {
 } from "#/server/lichess.ts";
 import { getHeaders } from "#/utils/pgnUtils.ts";
 
-interface ITokenData {
-	access_token: string;
-	expires_in: number;
-	token_type: string;
-}
+type Status = "loading" | "success" | "error";
 
-export type IUserStudy = {
-	id: string;
-	name: string;
-	createdAt: number;
-	updatedAt: number;
+export type LichessResult<T> =
+	| { ok: true; data: T }
+	| { ok: false; error: string };
+
+const LICHESS_STUDY_LINK_RE =
+	/^https?:\/\/lichess\.org\/study\/([A-Za-z0-9]{8})(?:\.pgn)?(?:$|\/|\?|#)/i;
+
+const lichessFetch = async <T>(
+	fn: () => Promise<T | undefined>,
+	fallbackError: string,
+): Promise<LichessResult<T>> => {
+	try {
+		const data = await fn();
+		if (data === undefined || data === null) {
+			return { ok: false, error: fallbackError };
+		}
+		return { ok: true, data };
+	} catch (err) {
+		return {
+			ok: false,
+			error: err instanceof Error ? err.message : fallbackError,
 		};
-
-export interface IUserStudyChapter {
-	chapterId: string;
-	name: string;
-	pgn: string;
 	}
+};
 
 export const useLichess = () => {
 	const { user, setUser } = useLichessUser();
 	const [userStudies, setUserStudies] = useState<IUserStudy[]>([]);
 	const [selectedStudyId, setSelectedStudyId] = useState<string | null>(null);
-	const [studyChapters, setStudyChapters] = useState<
-		IUserStudyChapter[] | null
-	>(null);
 
 	const loginFn = useServerFn(login);
 	const logoutFn = useServerFn(logout);
@@ -64,7 +73,7 @@ export const useLichess = () => {
 		token: string;
 	}) => {
 		await setSessionFn({ data: { username, id, token } });
-		setUser({ username, id, isLoggedIn: true });
+		setUser({ username, id });
 	};
 
 	const getLichessUser = async ({ tokenData }: { tokenData: ITokenData }) => {
@@ -77,6 +86,7 @@ export const useLichess = () => {
 
 	const lichessLogout = async () => {
 		await logoutFn();
+		setSelectedStudyId(null);
 		setUser(null);
 	};
 
@@ -84,40 +94,59 @@ export const useLichess = () => {
 		return getSessionFn();
 	};
 
-	const useLichessCallback = async ({ code }: { code: string }) => {
-		const navigate = useNavigate();
+	const useLichessCallback = ({ code }: { code: string }) => {
+		const [status, setStatus] = useState<Status>("loading");
+		const [error, setError] = useState<string | null>(null);
 
 		useEffect(() => {
 			if (!code) return;
 
+			const isMounted = true;
+
+			try {
 				(async () => {
 					const tokenData = await lichessAccessToken({ code });
 					const userData = await getLichessUser({ tokenData });
 
+					if (!isMounted) return;
+
 					await setLichessUser({
 						username: userData.username,
 						id: userData.id,
 						token: tokenData.access_token,
 					});
-				await navigate({ to: "/chessboard" });
+
+					setStatus("success");
 				})();
-		}, [navigate, code]);
+			} catch (err: unknown) {
+				if (isMounted && err instanceof Error) {
+					console.error("Lichess Authentication Error:", err);
+					setError(err.message || "Failed to authenticate with Lichess");
+					setStatus("error");
+				}
+			}
+		}, [code]);
+
+		return { status, error };
 	};
 
-	const getLichessUserStudies = async () => {
-		if (!user) throw new Error("User not found");
-		const studies: IUserStudy[] | undefined = await getUserStudiesFn();
-		if (!studies) return;
-		setUserStudies(studies);
+	const getLichessUserStudies = async (): Promise<
+		LichessResult<IUserStudy[]>
+	> => {
+		if (!user) return { ok: false, error: "Not signed in to Lichess." };
+		return lichessFetch(() => getUserStudiesFn(), "Failed to load studies.");
 	};
 
-	const getLichessStudyChapters = async ({ studyId }: { studyId: string }) => {
-		if (!user) throw new Error("User not found");
-		const chapters: IUserStudyChapter[] | undefined = await getStudyChaptersFn({
-			data: { studyId },
-		});
-		if (!chapters) return;
-		return chapters;
+	const getLichessStudyChapters = async ({
+		studyId,
+	}: {
+		studyId: string;
+	}): Promise<LichessResult<IUserStudyChapter[]>> => {
+		if (!user) return { ok: false, error: "Not signed in to Lichess." };
+		return lichessFetch(
+			() => getStudyChaptersFn({ data: { studyId } }),
+			"Failed to load chapters.",
+		);
 	};
 
 	// return headers and pgn from the Lichess chapter
@@ -140,6 +169,23 @@ export const useLichess = () => {
 		return { headers, pgn };
 	};
 
+	// parse and process lichess study link
+	const parseLichessStudyLink = (studyLink: string): LichessResult<string> => {
+		const trimmed = studyLink.trim();
+
+		if (!trimmed) {
+			return { ok: false, error: "Please paste a Lichess study link." };
+		}
+
+		const match = trimmed.match(LICHESS_STUDY_LINK_RE);
+
+		if (!match) {
+			return { ok: false, error: "Invalid Lichess study link." };
+		}
+
+		return { ok: true, data: match[1] };
+	};
+
 	return {
 		lichessLogin,
 		lichessLogout,
@@ -154,8 +200,7 @@ export const useLichess = () => {
 		setSelectedStudyId,
 		selectedStudyId,
 		getLichessStudyChapters,
-		studyChapters,
-		setStudyChapters,
 		loadLichessStudyChapter,
+		parseLichessStudyLink,
 	};
 };

src/interfaces.ts

@@ -1,3 +1,22 @@
+import type { infer } from "zod";
+import type { SessionSchema, TokenResponseSchema } from "#/schemas.ts";
+
+export interface ISession extends infer<typeof SessionSchema> {}
+export interface ITokenData extends infer<typeof TokenResponseSchema> {}
+
+export interface IUserStudy {
+	id: string;
+	name: string;
+	createdAt: number;
+	updatedAt: number;
+}
+
+export interface IUserStudyChapter {
+	chapterId: string;
+	name: string;
+	pgn: string;
+}
+
 export interface IPosition {
 	ply: number;
 	fen: string;

src/pages/Callback.tsx

@@ -1,14 +1,23 @@
-import { getRouteApi } from "@tanstack/react-router";
+import { getRouteApi, useNavigate } from "@tanstack/react-router";
+import GenericErrorView from "#/components/GenericErrorView.tsx";
+import LoadingView from "#/components/LoadingView.tsx";
 import { useLichess } from "#/hooks/useLichess.ts";
 
 const routeApi = getRouteApi("/callback");
 
 const Callback = () => {
+	const navigate = useNavigate();
 	const { useLichessCallback } = useLichess();
 	const { code } = routeApi.useSearch();
-	useLichessCallback({ code }).then();
+	const { status, error } = useLichessCallback({ code });
 
-	return <div>Loading...</div>;
+	if (status === "success") navigate({ to: "/chessboard" });
+
+	if (status === "error") return <GenericErrorView error={error} />;
+
+	return (
+		<LoadingView title="Logging in..." description="Please wait a moment..." />
+	);
 };
 
 export default Callback;

src/pages/Chessboard.tsx

@@ -2,10 +2,11 @@ import { lazy, Suspense } from "react";
 import CustomHeaders from "#/components/CustomHeaders.tsx";
 import HeaderFields from "#/components/HeaderFields.tsx";
 import LichessButton from "#/components/LichessButton.tsx";
-import LichessStudyUrlInput from "#/components/LichessStudyUrlInput.tsx";
+import LichessStudyLinkInput from "#/components/LichessStudyLinkInput.tsx";
 import Section from "#/components/Section.tsx";
 import SelectLichessStudy from "#/components/SelectLichessStudy.tsx";
 import SelectStudyChapter from "#/components/SelectStudyChapter.tsx";
+import { useLichessUser } from "#/context/LichessUserContext.tsx";
 import { useChessGame } from "#/hooks/useChessGame.ts";
 import { useLichess } from "#/hooks/useLichess.ts";
 
@@ -38,8 +39,9 @@ const Chessboard = () => {
 		gameDispatch,
 	} = useChessGame();
 
-	const { selectedStudyId, setSelectedStudyId, setStudyChapters } =
-		useLichess();
+	const { selectedStudyId, setSelectedStudyId } = useLichess();
+
+	const { user } = useLichessUser();
 
 	return (
 		<main className="px-4 pb-8 place-self-center min-h-[calc(100vh-226px)]">
@@ -52,15 +54,22 @@ const Chessboard = () => {
 					className="file-input max-w-xs"
 					onChange={handleLoadPgn}
 				/>
-				<SelectLichessStudy
-					setSelectedStudyId={setSelectedStudyId}
-					setStudyChapters={setStudyChapters}
-				/>{" "}
-				or <LichessStudyUrlInput />
+				{user ? (
+					<SelectLichessStudy setSelectedStudyId={setSelectedStudyId} />
+				) : null}
+				<div />
+				{user ? (
 					<SelectStudyChapter
 						selectedStudyId={selectedStudyId || ""}
 						gameDispatch={gameDispatch}
 					/>
+				) : null}
+				{user ? (
+					<div className="flex flex-col">
+						<p className="text-center">or</p>
+						<LichessStudyLinkInput setSelectedStudyId={setSelectedStudyId} />
+					</div>
+				) : null}
 			</Section>
 
 			<div className="grid lg:grid-cols-2 gap-4">
@@ -103,6 +112,7 @@ const Chessboard = () => {
 									id="render-times"
 									name="render-times"
 									type="checkbox"
+									disabled={!gameState.pgn}
 									checked={gameState.diagramClock}
 									onChange={handleToggleClock}
 								/>

src/pages/index.tsx

@@ -10,7 +10,7 @@ const Home = () => (
 	<main className="px-4 pb-8 pt-14">
 		<section
 			id="hero"
-			className="grid max-w-screen-2xl items-center gap-8 p-8 text-center md:grid-cols-2 md:text-left mx-auto"
+			className="relative grid max-w-screen-2xl items-center gap-8 p-8 text-center md:grid-cols-2 md:text-left mx-auto md:min-h-[calc(100vh-226px)]"
 		>
 			<div>
 				<h1 className="text-3xl font-bold text-base-content md:text-4xl">
@@ -37,6 +37,22 @@ const Home = () => (
 					priority
 				/>
 			</div>
+			<div className="absolute bottom-4 left-1/2 hidden -translate-x-1/2 md:block animate-bounce text-base-content/50">
+				<svg
+					xmlns="http://www.w3.org/2000/svg"
+					width="32"
+					height="32"
+					viewBox="0 0 24 24"
+					fill="none"
+					stroke="currentColor"
+					strokeWidth="2"
+					strokeLinecap="round"
+					strokeLinejoin="round"
+				>
+					<title>scroll down</title>
+					<path d="m6 9 6 6 6-6" />
+				</svg>
+			</div>
 		</section>
 		<Section
 			title="A Unique Chess Publication Service"

src/router.tsx

@@ -1,19 +1,19 @@
-import { createRouter as createTanStackRouter } from '@tanstack/react-router'
-import { routeTree } from './routeTree.gen'
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
 
 export function getRouter() {
 	const router = createTanStackRouter({
 		routeTree,
 		scrollRestoration: true,
-    defaultPreload: 'intent',
+		defaultPreload: "intent",
 		defaultPreloadStaleTime: 0,
-  })
+	});
 
-  return router
+	return router;
 }
 
-declare module '@tanstack/react-router' {
+declare module "@tanstack/react-router" {
 	interface Register {
-    router: ReturnType<typeof getRouter>
+		router: ReturnType<typeof getRouter>;
 	}
 }

src/routes/__root.tsx

@@ -3,7 +3,10 @@ import { createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";
 import { TanStackRouterDevtoolsPanel } from "@tanstack/react-router-devtools";
 import { type ReactNode, Suspense } from "react";
 import { ToastContainer } from "react-toastify";
+import GenericErrorView from "#/components/GenericErrorView.tsx";
+import LoadingView from "#/components/LoadingView.tsx";
 import { MatomoAnalytics } from "#/components/MatomoAnalytics.tsx";
+import NotFoundView from "#/components/NotFoundView.tsx";
 import { LichessUserProvider } from "#/context/LichessUserContext.tsx";
 import Footer from "../components/Footer";
 import Header from "../components/Header";
@@ -39,10 +42,27 @@ export const Route = createRootRoute({
 			{
 				rel: "icon",
 				href: "/favicon.svg",
+				type: "image/svg+xml",
+			},
+			{
+				rel: "icon",
+				href: "/favicon.ico",
+				sizes: "32x32",
+			},
+			{
+				rel: "apple-touch-icon",
+				href: "/apple-touch-icon.png",
+			},
+			{
+				rel: "manifest",
+				href: "/site.webmanifest",
 			},
 		],
 	}),
 	shellComponent: RootDocument,
+	errorComponent: ({ error }) => <GenericErrorView error={error} />,
+	pendingComponent: () => <LoadingView />,
+	notFoundComponent: () => <NotFoundView />,
 });
 
 function RootDocument({ children }: { children: ReactNode }) {

src/routes/callback.tsx

@@ -1,16 +1,27 @@
-import { createFileRoute } from "@tanstack/react-router";
+import { createFileRoute, notFound } from "@tanstack/react-router";
 import { z } from "zod";
+import GenericErrorView from "#/components/GenericErrorView.tsx";
 import Callback from "#/pages/Callback.tsx";
 
 const callbackSchema = z.object({
 	code: z.string(),
 });
 
-// type CallbackProps = z.infer<typeof callbackSchema>;
-
 export const Route = createFileRoute("/callback")({
+	head: () => ({
+		meta: [{ name: "robots", content: "noindex, nofollow" }],
+	}),
+
 	validateSearch: (search) => callbackSchema.parse(search),
+
+	beforeLoad: ({ search }) => {
+		if (!search.code) {
+			throw notFound();
+		}
+	},
+
 	component: RouteComponent,
+	errorComponent: ({ error }) => <GenericErrorView error={error} />,
 });
 
 function RouteComponent() {

src/schemas.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+export const SessionSchema = z.object({
+	username: z.string(),
+	id: z.string(),
+	token: z.string(),
+});
+
+export const TokenResponseSchema = z.object({
+	access_token: z.string(),
+	expires_in: z.number(),
+	scope: z.string().optional(),
+	token_type: z.string(),
+});
+
+export const LichessAccountSchema = z.object({
+	id: z.string(),
+	username: z.string(),
+});

src/server/lichess.ts

@@ -6,8 +6,14 @@ import {
 	getCookie,
 	setCookie,
 } from "@tanstack/react-start/server";
+import { z } from "zod";
 import { env } from "#/env.ts";
 import { base64UrlEncode, sha256 } from "#/lib/encodeDecode.ts";
+import {
+	LichessAccountSchema,
+	SessionSchema,
+	TokenResponseSchema,
+} from "#/schemas.ts";
 
 const createVerifier = () => base64UrlEncode(randomBytes(32));
 const createChallenge = (verifier: string) => base64UrlEncode(sha256(verifier));
@@ -22,11 +28,8 @@ export const getSession = createServerFn({ method: "GET" }).handler(
 		const session = getCookie("lichess-session");
 		if (!session) return null;
 		try {
-			return JSON.parse(session) as {
-				username: string;
-				id: string;
-				token: string;
-			};
+			const parsed = SessionSchema.safeParse(JSON.parse(session));
+			return parsed.success ? parsed.data : null;
 		} catch {
 			return null;
 		}
@@ -34,25 +37,15 @@ export const getSession = createServerFn({ method: "GET" }).handler(
 );
 
 export const setSession = createServerFn({ method: "POST" })
-	.inputValidator(
-		(data: { username: string; id: string; token: string }) => data,
-	)
+	.inputValidator(SessionSchema)
 	.handler(async ({ data }) => {
-		setCookie(
-			"lichess-session",
-			JSON.stringify({
-				username: data.username,
-				id: data.id,
-				token: data.token,
-			}),
-			{
+		setCookie("lichess-session", JSON.stringify(data), {
 			path: "/",
 			httpOnly: true,
 			secure: process.env.NODE_ENV === "production",
 			sameSite: "lax",
 			maxAge: 60 * 60 * 24 * 7,
-			},
-		);
+		});
 
 		setCookie("lichess-oauth-verifier", "", {
 			path: "/",
@@ -66,12 +59,13 @@ export const setSession = createServerFn({ method: "POST" })
 	});
 
 export const getToken = createServerFn({ method: "POST" })
-	.inputValidator((data: { code: string }) => data)
+	.inputValidator(z.object({ code: z.string() }))
 	.handler(async ({ data }) => {
 		const verifier = getCookie("lichess-oauth-verifier");
 
-		if (!verifier)
+		if (!verifier) {
 			throw new Error("OAuth session expired. Please login again.");
+		}
 
 		const response = await fetch("https://lichess.org/api/token", {
 			method: "POST",
@@ -87,14 +81,16 @@ export const getToken = createServerFn({ method: "POST" })
 			}),
 		});
 
-		if (!response.ok)
+		if (!response.ok) {
 			throw new Error(`Token exchange failed: ${await response.text()}`);
+		}
 
-		return response.json();
+		const json = await response.json();
+		return TokenResponseSchema.parse(json);
 	});
 
-export const getUser = createServerFn({ method: "GET" })
-	.inputValidator((data: { access_token: string }) => data)
+export const getUser = createServerFn({ method: "POST" })
+	.inputValidator(z.object({ access_token: z.string() }))
 	.handler(async ({ data }) => {
 		const response = await fetch("https://lichess.org/api/account", {
 			headers: {
@@ -102,7 +98,10 @@ export const getUser = createServerFn({ method: "GET" })
 			},
 		});
 
-		return response.json();
+		if (!response.ok) throw new Error("Failed to fetch Lichess account");
+
+		const json = await response.json();
+		return LichessAccountSchema.parse(json);
 	});
 
 const deleteAccessToken = createServerFn().handler(async () => {
@@ -117,8 +116,14 @@ const deleteAccessToken = createServerFn().handler(async () => {
 			},
 		});
 
-		return await response.json();
+		if (!response.ok) {
+			throw new Error(`Failed to delete access token: ${response.statusText}`);
 		}
+
+		return { success: true };
+	}
+
+	return { success: false, message: "No token found to delete." };
 });
 
 export const logout = createServerFn().handler(async () => {

src/server/pdfMetrics.ts

@@ -0,0 +1,41 @@
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { createServerFn } from "@tanstack/react-start";
+
+const METRICS_DIR = join(process.cwd(), "data");
+const LOG_FILE = join(METRICS_DIR, "pdf-events.log");
+const COUNT_FILE = join(METRICS_DIR, "pdf-count.txt");
+
+const readCount = async (): Promise<number> => {
+	try {
+		const n = Number.parseInt(
+			(await fs.readFile(COUNT_FILE, "utf-8")).trim(),
+			10,
+		);
+		return Number.isFinite(n) ? n : 0;
+	} catch {
+		return 0;
+	}
+};
+
+const writeCountAtomic = async (count: number) => {
+	const tmp = `${COUNT_FILE}.tmp`;
+	await fs.writeFile(tmp, String(count), "utf-8");
+	await fs.rename(tmp, COUNT_FILE);
+};
+
+export const recordPdfSuccess = createServerFn({ method: "POST" }).handler(
+	async () => {
+		try {
+			await fs.mkdir(METRICS_DIR, { recursive: true });
+			const next = (await readCount()) + 1;
+			await Promise.all([
+				fs.appendFile(LOG_FILE, `${new Date().toISOString()}\n`, "utf-8"),
+				writeCountAtomic(next),
+			]);
+			return { count: next };
+		} catch (err) {
+			console.error("Failed to record PDF success:", err);
+		}
+	},
+);

src/styles/_accordion.css

@@ -17,6 +17,19 @@
 	border-bottom: 1px solid var(--neutral-content);
 }
 
+.hero__accordion-item__content {
+	padding: 0 10px;
+	display: grid;
+	grid-template-rows: 0fr;
+	transition:
+		grid-template-rows 0.3s ease,
+		padding 0.3s ease;
+
+	@media (prefers-reduced-motion) {
+		transition: none;
+	}
+}
+
 .hero__accordion-details[open] + .hero__accordion-item__content {
 	grid-template-rows: 1fr;
 	padding: 10px;
@@ -53,19 +66,6 @@
 	font-weight: 600;
 }
 
-.hero__accordion-item__content {
-	padding: 0 10px;
-	display: grid;
-	grid-template-rows: 0fr;
-	transition:
-		grid-template-rows 0.3s ease,
-		padding 0.3s ease;
-
-	@media (prefers-reduced-motion) {
-		transition: none;
-	}
-}
-
 .hero__accordion-item__content__inner {
 	color: var(--neutral-content);
 	overflow: hidden;

vite.config.ts

@@ -19,6 +19,17 @@ const config = defineConfig({
 				enabled: true,
 				crawlLinks: true,
 			},
+			pages: [
+				{
+					path: "/callback",
+					prerender: {
+						enabled: false,
+					},
+					sitemap: {
+						exclude: true,
+					},
+				},
+			],
 			sitemap: {
 				enabled: true,
 				host: HOST_URL,