feat(v3): add v3 stack — backend rewrite, renamed env vars, docs

- New Go backend binary (backend + runner) replacing old scraper/
- Rename SCRAPER_API_URL → BACKEND_API_URL in UI env and docker-compose
- Rename scraperFetch → backendFetch across all 19 UI server files
- Remove SCRAPER_PROXY env var and proxy transport from browser.Config
- Add Meilisearch, Valkey, Caddy to docker-compose
- Add docs/: api-endpoints.md, request-flow.mermaid.md, data-flow.mermaid.md

v3/ui/src/routes/api/auth/change-password/+server.ts

@@ -0,0 +1,47 @@
+import { json, error } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { changePassword } from '$lib/server/pocketbase';
+import { log } from '$lib/server/logger';
+
+/**
+ * POST /api/auth/change-password
+ * Body: { currentPassword: string, newPassword: string }
+ * Requires authentication.
+ */
+export const POST: RequestHandler = async ({ request, locals }) => {
+	if (!locals.user) {
+		error(401, 'Not authenticated');
+	}
+
+	let body: { currentPassword?: string; newPassword?: string };
+	try {
+		body = await request.json();
+	} catch {
+		error(400, 'Invalid JSON body');
+	}
+
+	const currentPassword = body.currentPassword ?? '';
+	const newPassword = body.newPassword ?? '';
+
+	if (!currentPassword || !newPassword) {
+		error(400, 'currentPassword and newPassword are required');
+	}
+
+	if (newPassword.length < 4) {
+		error(400, 'New password must be at least 4 characters');
+	}
+
+	try {
+		const ok = await changePassword(locals.user.id, currentPassword, newPassword);
+		if (!ok) {
+			error(401, 'Current password is incorrect');
+		}
+	} catch (e: unknown) {
+		// Re-throw SvelteKit errors as-is
+		if (e && typeof e === 'object' && 'status' in e) throw e;
+		log.error('api/auth/change-password', 'unexpected error', { err: String(e) });
+		error(500, 'An error occurred. Please try again.');
+	}
+
+	return json({ ok: true });
+};

v3/ui/src/routes/api/auth/login/+server.ts

@@ -0,0 +1,75 @@
+import { json, error } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { loginUser, mergeSessionProgress, createUserSession } from '$lib/server/pocketbase';
+import { createAuthToken } from '../../../../hooks.server';
+import { log } from '$lib/server/logger';
+import { randomBytes } from 'node:crypto';
+
+const AUTH_COOKIE = 'libnovel_auth';
+const ONE_YEAR = 60 * 60 * 24 * 365;
+
+/**
+ * POST /api/auth/login
+ * Body: { username: string, password: string }
+ * Returns: { token: string, user: { id, username, role } }
+ *
+ * Sets the libnovel_auth cookie and returns the raw token value so the
+ * iOS app can persist it for subsequent requests.
+ */
+export const POST: RequestHandler = async ({ request, cookies, locals }) => {
+	let body: { username?: string; password?: string };
+	try {
+		body = await request.json();
+	} catch {
+		error(400, 'Invalid JSON body');
+	}
+
+	const username = (body.username ?? '').trim();
+	const password = body.password ?? '';
+
+	if (!username || !password) {
+		error(400, 'Username and password are required');
+	}
+
+	let user;
+	try {
+		user = await loginUser(username, password);
+	} catch (e) {
+		log.error('api/auth/login', 'unexpected error', { username, err: String(e) });
+		error(500, 'An error occurred. Please try again.');
+	}
+
+	if (!user) {
+		error(401, 'Invalid username or password');
+	}
+
+	// Merge anonymous session progress (non-fatal)
+	mergeSessionProgress(locals.sessionId, user.id).catch((e) =>
+		log.warn('api/auth/login', 'mergeSessionProgress failed (non-fatal)', { err: String(e) })
+	);
+
+	const authSessionId = randomBytes(16).toString('hex');
+
+	const userAgent = request.headers.get('user-agent') ?? '';
+	const ip =
+		request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
+		request.headers.get('x-real-ip') ??
+		'';
+	createUserSession(user.id, authSessionId, userAgent, ip).catch((e) =>
+		log.warn('api/auth/login', 'createUserSession failed (non-fatal)', { err: String(e) })
+	);
+
+	const token = createAuthToken(user.id, user.username, user.role ?? 'user', authSessionId);
+
+	cookies.set(AUTH_COOKIE, token, {
+		path: '/',
+		httpOnly: true,
+		sameSite: 'lax',
+		maxAge: ONE_YEAR
+	});
+
+	return json({
+		token,
+		user: { id: user.id, username: user.username, role: user.role ?? 'user' }
+	});
+};

v3/ui/src/routes/api/auth/logout/+server.ts

@@ -0,0 +1,15 @@
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+
+const AUTH_COOKIE = 'libnovel_auth';
+
+/**
+ * POST /api/auth/logout
+ * Clears the auth cookie and returns { ok: true }.
+ * Does not revoke the session record from PocketBase —
+ * for full revocation use DELETE /api/sessions/[id] first.
+ */
+export const POST: RequestHandler = async ({ cookies }) => {
+	cookies.delete(AUTH_COOKIE, { path: '/' });
+	return json({ ok: true });
+};

v3/ui/src/routes/api/auth/me/+server.ts

@@ -0,0 +1,22 @@
+import { json, error } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { getUserByUsername } from '$lib/server/pocketbase';
+
+/**
+ * GET /api/auth/me
+ * Returns the currently authenticated user from the request's auth cookie.
+ * Returns 401 if not authenticated.
+ */
+export const GET: RequestHandler = async ({ locals }) => {
+	if (!locals.user) {
+		error(401, 'Not authenticated');
+	}
+	// Fetch full record from PocketBase to get avatar_url
+	const record = await getUserByUsername(locals.user.username).catch(() => null);
+	return json({
+		id: locals.user.id,
+		username: locals.user.username,
+		role: locals.user.role,
+		avatar_url: record?.avatar_url ?? null
+	});
+};

v3/ui/src/routes/api/auth/register/+server.ts

@@ -0,0 +1,84 @@
+import { json, error } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { createUser, mergeSessionProgress, createUserSession } from '$lib/server/pocketbase';
+import { createAuthToken } from '../../../../hooks.server';
+import { log } from '$lib/server/logger';
+import { randomBytes } from 'node:crypto';
+
+const AUTH_COOKIE = 'libnovel_auth';
+const ONE_YEAR = 60 * 60 * 24 * 365;
+
+/**
+ * POST /api/auth/register
+ * Body: { username: string, password: string }
+ * Returns: { token: string, user: { id, username, role } }
+ *
+ * Sets the libnovel_auth cookie and returns the raw token value so the
+ * iOS app can persist it for subsequent requests.
+ */
+export const POST: RequestHandler = async ({ request, cookies, locals }) => {
+	let body: { username?: string; password?: string };
+	try {
+		body = await request.json();
+	} catch {
+		error(400, 'Invalid JSON body');
+	}
+
+	const username = (body.username ?? '').trim();
+	const password = body.password ?? '';
+
+	if (!username || !password) {
+		error(400, 'Username and password are required');
+	}
+	if (username.length < 3 || username.length > 32) {
+		error(400, 'Username must be between 3 and 32 characters');
+	}
+	if (!/^[a-zA-Z0-9_-]+$/.test(username)) {
+		error(400, 'Username may only contain letters, numbers, underscores and hyphens');
+	}
+	if (password.length < 8) {
+		error(400, 'Password must be at least 8 characters');
+	}
+
+	let user;
+	try {
+		user = await createUser(username, password);
+	} catch (e: unknown) {
+		const msg = e instanceof Error ? e.message : 'Registration failed.';
+		if (msg.includes('Username already taken')) {
+			error(409, 'That username is already taken');
+		}
+		log.error('api/auth/register', 'unexpected error', { username, err: String(e) });
+		error(500, 'An error occurred. Please try again.');
+	}
+
+	// Merge anonymous session progress (non-fatal)
+	mergeSessionProgress(locals.sessionId, user.id).catch((e) =>
+		log.warn('api/auth/register', 'mergeSessionProgress failed (non-fatal)', { err: String(e) })
+	);
+
+	const authSessionId = randomBytes(16).toString('hex');
+
+	const userAgent = request.headers.get('user-agent') ?? '';
+	const ip =
+		request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
+		request.headers.get('x-real-ip') ??
+		'';
+	createUserSession(user.id, authSessionId, userAgent, ip).catch((e) =>
+		log.warn('api/auth/register', 'createUserSession failed (non-fatal)', { err: String(e) })
+	);
+
+	const token = createAuthToken(user.id, user.username, user.role ?? 'user', authSessionId);
+
+	cookies.set(AUTH_COOKIE, token, {
+		path: '/',
+		httpOnly: true,
+		sameSite: 'lax',
+		maxAge: ONE_YEAR
+	});
+
+	return json({
+		token,
+		user: { id: user.id, username: user.username, role: user.role ?? 'user' }
+	});
+};