From 5b37ed1ef0fd3817d25906fa77311a4aa513a949 Mon Sep 17 00:00:00 2001
From: Muhammadjazuli <Muhammadjazuli@users.noreply.github.com>
Date: Fri, 25 Sep 2026 03:20:18 +0100
Subject: [PATCH] fix(auth): harden session and image resilience

Add WebP-aware image loading, activity-aware expiry warnings, transactional session-state consumption, and accurate bundle-boundary documentation.

Closes #1313
Closes #1314
Closes #1315
Closes #1316
---
 frontend/app/(protected)/map/page.tsx         |   8 +-
 frontend/app/[locale]/(protected)/layout.tsx  |   2 +
 .../(protected)/settings/data/page.tsx        |   9 +-
 .../(protected)/settings/security/page.tsx    |   6 +-
 frontend/app/[locale]/login/LoginForm.tsx     |  16 +-
 frontend/components/SessionExpiryGuard.tsx    |  17 +
 frontend/lib/__tests__/image-loader.test.ts   |  43 ++
 .../__tests__/session-expiry-warning.test.ts  | 153 +++++
 frontend/lib/__tests__/session-expiry.test.ts |   4 +-
 .../__tests__/session-state-preserver.test.ts | 282 ++++++++
 frontend/lib/api-client.ts                    | 241 ++++++-
 frontend/lib/auth-session.ts                  | 105 ++-
 frontend/lib/bundle-config.ts                 |  15 +-
 frontend/lib/image-loader.ts                  |  80 ++-
 frontend/lib/session-expiry-warning.ts        | 246 +++++--
 frontend/lib/session-state-preserver.ts       | 644 +++++++++++++++++-
 frontend/next.config.ts                       |   5 +
 frontend/test-utils/LoginForm.test.tsx        |  62 +-
 frontend/test-utils/api-client.test.ts        | 136 +++-
 frontend/test-utils/mocks/handlers.ts         |   4 +-
 20 files changed, 1900 insertions(+), 178 deletions(-)
 create mode 100644 frontend/components/SessionExpiryGuard.tsx
 create mode 100644 frontend/lib/__tests__/image-loader.test.ts
 create mode 100644 frontend/lib/__tests__/session-expiry-warning.test.ts
 create mode 100644 frontend/lib/__tests__/session-state-preserver.test.ts

diff --git a/frontend/app/(protected)/map/page.tsx b/frontend/app/(protected)/map/page.tsx
index ac2539d3..68d3ca7f 100644
--- a/frontend/app/(protected)/map/page.tsx
+++ b/frontend/app/(protected)/map/page.tsx
@@ -1,10 +1,12 @@
 "use client";
 
 import dynamic from "next/dynamic";
+import { clientOnlyBundleBoundary } from "@/lib/bundle-config";
 
-const MapPageContent = dynamic(() => import("./MapPageContent"), {
-  ssr: false,
-});
+const MapPageContent = dynamic(
+  () => import("./MapPageContent"),
+  clientOnlyBundleBoundary,
+);
 
 export default function MapPage() {
   return <MapPageContent />;
diff --git a/frontend/app/[locale]/(protected)/layout.tsx b/frontend/app/[locale]/(protected)/layout.tsx
index c9ad4c43..47df3f9f 100644
--- a/frontend/app/[locale]/(protected)/layout.tsx
+++ b/frontend/app/[locale]/(protected)/layout.tsx
@@ -2,6 +2,7 @@ import { getTranslations, setRequestLocale } from "next-intl/server";
 import { Link } from "@/i18n/navigation";
 import LanguageSwitcher from "@/components/LanguageSwitcher";
 import NotificationBell from "@/components/layout/NotificationBell";
+import { SessionExpiryGuard } from "@/components/SessionExpiryGuard";
 
 export const dynamic = "force-dynamic";
 
@@ -20,6 +21,7 @@ export default async function ProtectedLayout({
 
   return (
     <div className="min-h-screen bg-gray-50">
+      <SessionExpiryGuard />
       <nav className="sticky top-0 z-40 border-b border-gray-200 bg-white">
         <div className="mx-auto flex h-14 max-w-7xl items-center justify-between px-4 sm:px-6">
           <div className="flex items-center gap-6">
diff --git a/frontend/app/[locale]/(protected)/settings/data/page.tsx b/frontend/app/[locale]/(protected)/settings/data/page.tsx
index dc3c869d..455d1b2e 100644
--- a/frontend/app/[locale]/(protected)/settings/data/page.tsx
+++ b/frontend/app/[locale]/(protected)/settings/data/page.tsx
@@ -2,6 +2,7 @@
 
 import React, { useEffect, useRef, useState } from "react";
 import { useRouter } from "next/navigation";
+import { clearSession } from "@/lib/auth-session";
 
 const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
 
@@ -15,9 +16,11 @@ function getAuthHeaders(): HeadersInit {
   return token ? { Authorization: `Bearer ${token}` } : {};
 }
 
-function logout() {
-  localStorage.removeItem("auth-token");
-  document.cookie = "token=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;";
+function logout(): void {
+  const result = clearSession();
+  if (!result.ok) {
+    throw new Error("Unable to clear the session safely.");
+  }
 }
 
 const COOLDOWN_MS = 24 * 60 * 60 * 1000; // 24 hours
diff --git a/frontend/app/[locale]/(protected)/settings/security/page.tsx b/frontend/app/[locale]/(protected)/settings/security/page.tsx
index 8c85a477..08cbb07c 100644
--- a/frontend/app/[locale]/(protected)/settings/security/page.tsx
+++ b/frontend/app/[locale]/(protected)/settings/security/page.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import React, { useState } from "react";
+import { clearSession } from "@/lib/auth-session";
 
 // ─────────────────────────────────────────────
 // Types
@@ -268,7 +269,10 @@ function DangerZone() {
     try {
       // Replace with: await api.delete('/users/me')
       await new Promise((r) => setTimeout(r, 800));
-      // On success the auth layer should clear the session and redirect.
+      const cleared = clearSession();
+      if (!cleared.ok) {
+        throw new Error("Unable to clear the session safely.");
+      }
       window.location.href = "/login";
     } catch {
       setError("Failed to delete account. Please try again.");
diff --git a/frontend/app/[locale]/login/LoginForm.tsx b/frontend/app/[locale]/login/LoginForm.tsx
index 9e21ffc0..99752392 100644
--- a/frontend/app/[locale]/login/LoginForm.tsx
+++ b/frontend/app/[locale]/login/LoginForm.tsx
@@ -7,7 +7,7 @@ import { useTranslations } from "next-intl";
 import { useSearchParams } from "next/navigation";
 import { Link, useRouter } from "@/i18n/navigation";
 import { loginSchema, type LoginInput } from "@/lib/schemas/auth";
-import { ApiError, apiRequest } from "@/lib/api-client";
+import { API_V1_BASE, ApiError, apiRequest } from "@/lib/api-client";
 import {
   resolvePostLoginPath,
   storeSession,
@@ -24,8 +24,6 @@ import {
   Input,
 } from "@/components/ui";
 
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
-
 function ResetSuccessToast({ message }: { message: string }) {
   const [visible, setVisible] = useState(true);
 
@@ -90,26 +88,32 @@ export function LoginForm() {
   });
 
   const target = resolvePostLoginPath(searchParams.get("redirect"));
+  const resumeId = searchParams.get("resume");
 
   // OAuth is a full-page handoff to the backend, which redirects back with a
   // token — so these are plain anchors, not locale-aware client-side links.
   const oauthHref = (provider: "google" | "github") =>
-    `${API_BASE}/api/auth/${provider}`;
+    `${API_V1_BASE}/auth/${provider}`;
 
   async function onSubmit(values: LoginInput) {
     setSubmitError(null);
     try {
       const data = await apiRequest<LoginResponse>(
-        `${API_BASE}/api/auth/login`,
+        `${API_V1_BASE}/auth/login`,
         {
           method: "POST",
           body: values,
           // Lets the backend set a session cookie too, for when the token
           // stops living in localStorage.
           credentials: "include",
+          anonymous: true,
         },
       );
-      storeSession(data);
+      const stored = storeSession(data, resumeId ?? undefined);
+      if (!stored.ok) {
+        setSubmitError({ kind: "api", messageKey: "errors.status.unknown" });
+        return;
+      }
       // replace, so Back does not land the user on a login page they have
       // already passed through.
       router.replace(target);
diff --git a/frontend/components/SessionExpiryGuard.tsx b/frontend/components/SessionExpiryGuard.tsx
new file mode 100644
index 00000000..73f75939
--- /dev/null
+++ b/frontend/components/SessionExpiryGuard.tsx
@@ -0,0 +1,17 @@
+"use client";
+
+import { useCallback, useEffect } from "react";
+import { refreshSession } from "@/lib/api-client";
+import {
+  initCrossTabLogoutSync,
+  useSessionExpiryWarning,
+} from "@/lib/session-expiry-warning";
+
+export function SessionExpiryGuard() {
+  const onRefresh = useCallback(() => refreshSession(), []);
+
+  useSessionExpiryWarning({ onRefresh });
+  useEffect(() => initCrossTabLogoutSync(), []);
+
+  return null;
+}
diff --git a/frontend/lib/__tests__/image-loader.test.ts b/frontend/lib/__tests__/image-loader.test.ts
new file mode 100644
index 00000000..b83a9935
--- /dev/null
+++ b/frontend/lib/__tests__/image-loader.test.ts
@@ -0,0 +1,43 @@
+import imageLoader, { getOptimizedImageUrl } from "../image-loader";
+
+describe("Next image loader", () => {
+  it("uses the default-export ImageLoader contract", () => {
+    const result = imageLoader({
+      src: "/documents/photo.jpg?version=2#preview",
+      width: 640,
+      quality: 80,
+    });
+
+    expect(result).toBe(
+      "/_next/image?url=%2Fdocuments%2Fphoto.jpg%3Fversion%3D2&w=640&q=80#preview",
+    );
+  });
+
+  it("keeps the named URL helper compatible with the loader", () => {
+    expect(getOptimizedImageUrl("/photo.jpg", 320, 70)).toBe(
+      imageLoader({ src: "/photo.jpg", width: 320, quality: 70 }),
+    );
+  });
+
+  it("returns signed URLs unchanged rather than proxying them", () => {
+    const signedUrl =
+      "https://cdn.example.test/photo.jpg?X-Amz-Signature=abc&X-Amz-Expires=60";
+
+    expect(imageLoader({ src: signedUrl, width: 640 })).toBe(signedUrl);
+  });
+
+  it("leaves inline and object URLs unchanged", () => {
+    expect(imageLoader({ src: "data:image/png;base64,abc", width: 640 })).toBe(
+      "data:image/png;base64,abc",
+    );
+    expect(imageLoader({ src: "blob:https://example.test/image", width: 640 })).toBe(
+      "blob:https://example.test/image",
+    );
+  });
+
+  it("rejects protocol-relative URLs", () => {
+    expect(() => imageLoader({ src: "//cdn.example.test/photo.jpg", width: 640 })).toThrow(
+      "Protocol-relative image URLs are not supported",
+    );
+  });
+});
diff --git a/frontend/lib/__tests__/session-expiry-warning.test.ts b/frontend/lib/__tests__/session-expiry-warning.test.ts
new file mode 100644
index 00000000..c038dbdd
--- /dev/null
+++ b/frontend/lib/__tests__/session-expiry-warning.test.ts
@@ -0,0 +1,153 @@
+import { act, renderHook } from "@testing-library/react";
+import {
+  getTokenExpiryMs,
+  useSessionExpiryWarning,
+} from "../session-expiry-warning";
+
+const values: Record<string, string> = {};
+let storageBlocked = false;
+const localStorage = {
+  getItem: jest.fn((key: string) => {
+    if (storageBlocked) throw new DOMException("blocked", "SecurityError");
+    return values[key] ?? null;
+  }),
+};
+
+function makeToken(expiresInSeconds: number): string {
+  const payload = btoa(
+    JSON.stringify({ exp: Math.floor(Date.now() / 1000) + expiresInSeconds }),
+  )
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `header.${payload}.signature`;
+}
+
+beforeEach(() => {
+  jest.useFakeTimers();
+  jest.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+  Object.keys(values).forEach((key) => delete values[key]);
+  values["auth-token"] = makeToken(600);
+  storageBlocked = false;
+  Object.defineProperty(window, "localStorage", {
+    configurable: true,
+    value: localStorage,
+  });
+  localStorage.getItem.mockClear();
+  Object.defineProperty(window, "confirm", {
+    configurable: true,
+    value: jest.fn(() => false),
+  });
+});
+
+afterEach(() => {
+  jest.clearAllTimers();
+  jest.useRealTimers();
+  jest.restoreAllMocks();
+});
+
+describe("session expiry warning", () => {
+  it("parses base64url JWT payloads without requiring padding", () => {
+    const token =
+      "header.eyJleHAiOjE4OTM0NTYwMDAsIngiOiL_wiJ9.signature";
+
+    expect(getTokenExpiryMs(token)).toBe(
+      1893456000000 - new Date("2026-01-01T00:00:00.000Z").getTime(),
+    );
+  });
+
+  it("postpones the prompt until a continuous typing stream stops", () => {
+    values["auth-token"] = makeToken(360);
+    const onRefresh = jest.fn().mockResolvedValue(undefined);
+    const editor = document.createElement("textarea");
+    document.body.appendChild(editor);
+    const { unmount } = renderHook(() =>
+      useSessionExpiryWarning({ onRefresh }),
+    );
+
+    act(() => {
+      for (let index = 0; index < 400; index += 1) {
+        editor.dispatchEvent(new Event("input", { bubbles: true }));
+        jest.advanceTimersByTime(200);
+      }
+    });
+
+    expect(window.confirm).not.toHaveBeenCalled();
+
+    act(() => {
+      jest.advanceTimersByTime(250);
+      jest.advanceTimersByTime(60 * 1000);
+    });
+    expect(window.confirm).toHaveBeenCalledTimes(1);
+    unmount();
+    editor.remove();
+  });
+
+  it("handles blocked localStorage without throwing from activity", () => {
+    const onRefresh = jest.fn().mockResolvedValue(undefined);
+    const editor = document.createElement("input");
+    document.body.appendChild(editor);
+    const { unmount } = renderHook(() =>
+      useSessionExpiryWarning({ onRefresh }),
+    );
+    storageBlocked = true;
+
+    expect(() => {
+      act(() => {
+        editor.dispatchEvent(new Event("focusin", { bubbles: true }));
+        editor.dispatchEvent(new Event("input", { bubbles: true }));
+        jest.advanceTimersByTime(10 * 60 * 1000);
+      });
+    }).not.toThrow();
+    expect(window.confirm).not.toHaveBeenCalled();
+    unmount();
+    editor.remove();
+  });
+
+  it("uses the latest refresh callback without restarting on identity changes", async () => {
+    values["auth-token"] = makeToken(1200);
+    const firstRefresh = jest.fn().mockResolvedValue(undefined);
+    const secondRefresh = jest.fn().mockResolvedValue(undefined);
+    Object.defineProperty(window, "confirm", {
+      configurable: true,
+      value: jest.fn(() => true),
+    });
+    const { rerender, unmount } = renderHook(
+      ({ onRefresh }: { onRefresh: () => Promise<void> }) =>
+        useSessionExpiryWarning({ onRefresh }),
+      { initialProps: { onRefresh: firstRefresh } },
+    );
+
+    rerender({ onRefresh: secondRefresh });
+    await act(async () => {
+      jest.advanceTimersByTime(5 * 60 * 1000);
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(firstRefresh).not.toHaveBeenCalled();
+    expect(secondRefresh).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+
+  it("cleans the timer and listeners on unmount", () => {
+    const editor = document.createElement("textarea");
+    document.body.appendChild(editor);
+    const { unmount } = renderHook(() =>
+      useSessionExpiryWarning({ onRefresh: jest.fn().mockResolvedValue(undefined) }),
+    );
+
+    act(() => {
+      jest.advanceTimersByTime(4 * 60 * 1000);
+      editor.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+    unmount();
+
+    act(() => {
+      editor.dispatchEvent(new Event("input", { bubbles: true }));
+      jest.advanceTimersByTime(10 * 60 * 1000);
+    });
+    expect(window.confirm).not.toHaveBeenCalled();
+    editor.remove();
+  });
+});
diff --git a/frontend/lib/__tests__/session-expiry.test.ts b/frontend/lib/__tests__/session-expiry.test.ts
index 36742279..e1bb33df 100644
--- a/frontend/lib/__tests__/session-expiry.test.ts
+++ b/frontend/lib/__tests__/session-expiry.test.ts
@@ -59,7 +59,7 @@ describe("Concurrent 401 → single refresh (Issue #1024)", () => {
     // the refresh call returns 200 with a new token,
     // and retried calls return 200.
     (global as any).fetch = jest.fn((url: string) => {
-      if (url.includes("/auth/refresh")) {
+      if (url.includes("/api/v1/auth/refresh")) {
         refreshCallCount += 1;
         return Promise.resolve(
           new Response(
@@ -100,7 +100,7 @@ describe("Concurrent 401 → single refresh (Issue #1024)", () => {
     (window as any).location = { href: "" };
 
     (global as any).fetch = jest.fn((url: string) => {
-      if (url.includes("/auth/refresh")) {
+      if (url.includes("/api/v1/auth/refresh")) {
         return Promise.resolve(
           new Response(JSON.stringify({ error: "invalid_grant" }), {
             status: 401,
diff --git a/frontend/lib/__tests__/session-state-preserver.test.ts b/frontend/lib/__tests__/session-state-preserver.test.ts
new file mode 100644
index 00000000..fe2105a2
--- /dev/null
+++ b/frontend/lib/__tests__/session-state-preserver.test.ts
@@ -0,0 +1,282 @@
+import {
+  clearAllSessionState,
+  clearSessionState,
+  commitSessionResume,
+  commitSessionState,
+  consumeSessionResume,
+  consumeSessionState,
+  preserveSessionState,
+  readSessionState,
+  type SessionStateResult,
+} from "../session-state-preserver";
+
+const values: Record<string, string> = {};
+const accessTokens: Record<string, string> = {};
+let blockGet = false;
+let blockLocalGet = false;
+let blockSetKey: string | null = null;
+let blockRemove = false;
+
+const sessionStorage = {
+  getItem: jest.fn((key: string) => {
+    if (blockGet) throw new DOMException("blocked", "SecurityError");
+    return values[key] ?? null;
+  }),
+  setItem: jest.fn((key: string, value: string) => {
+    if (blockSetKey === key) throw new DOMException("blocked", "SecurityError");
+    values[key] = value;
+  }),
+  removeItem: jest.fn((key: string) => {
+    if (blockRemove) throw new DOMException("blocked", "SecurityError");
+    delete values[key];
+  }),
+  get length() {
+    return Object.keys(values).length;
+  },
+  key: jest.fn((index: number) => Object.keys(values)[index] ?? null),
+};
+
+const localStorage = {
+  getItem: jest.fn((key: string) => {
+    if (blockLocalGet) throw new DOMException("blocked", "SecurityError");
+    return accessTokens[key] ?? null;
+  }),
+  setItem: jest.fn((key: string, value: string) => {
+    accessTokens[key] = value;
+  }),
+  removeItem: jest.fn((key: string) => {
+    delete accessTokens[key];
+  }),
+};
+
+function makeToken(subject: string, nonce = ""): string {
+  const payload = btoa(JSON.stringify({ sub: subject, iat: nonce }))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `header.${payload}.signature`;
+}
+
+function unwrap<T>(result: SessionStateResult<T>): T {
+  if (!result.ok) throw new Error(result.error.code);
+  return result.value;
+}
+
+beforeEach(() => {
+  Object.keys(values).forEach((key) => delete values[key]);
+  Object.keys(accessTokens).forEach((key) => delete accessTokens[key]);
+  accessTokens["auth-token"] = makeToken("user-a", "old");
+  blockGet = false;
+  blockLocalGet = false;
+  blockSetKey = null;
+  blockRemove = false;
+  Object.defineProperty(window, "sessionStorage", {
+    configurable: true,
+    value: sessionStorage,
+  });
+  Object.defineProperty(window, "localStorage", {
+    configurable: true,
+    value: localStorage,
+  });
+  sessionStorage.getItem.mockClear();
+  sessionStorage.setItem.mockClear();
+  sessionStorage.removeItem.mockClear();
+  sessionStorage.key.mockClear();
+  localStorage.getItem.mockClear();
+  localStorage.setItem.mockClear();
+  localStorage.removeItem.mockClear();
+});
+
+describe("transactional session state", () => {
+  it("reads without removing and commits only after the caller is ready", () => {
+    const resumeId = unwrap(
+      preserveSessionState("upload-form", { fileName: "deed.pdf" }),
+    );
+    expect(resumeId).toEqual(expect.any(String));
+
+    const read = readSessionState<{ fileName: string }>("upload-form");
+    expect(unwrap(read)).toEqual({ fileName: "deed.pdf" });
+    expect(sessionStorage.removeItem).not.toHaveBeenCalled();
+
+    expect(commitSessionState("upload-form")).toEqual({ ok: true, value: undefined });
+    expect(sessionStorage.removeItem).toHaveBeenCalledTimes(2);
+    expect(readSessionState("upload-form")).toEqual({
+      ok: false,
+      error: { code: "not-found", key: "upload-form" },
+    });
+  });
+
+  it("consumes a matching session exactly once", () => {
+    unwrap(preserveSessionState("upload-form", { title: "Land deed" }));
+
+    expect(unwrap(consumeSessionState("upload-form"))).toEqual({
+      title: "Land deed",
+    });
+    expect(sessionStorage.removeItem).toHaveBeenCalledTimes(2);
+    expect(consumeSessionState("upload-form")).toEqual({
+      ok: false,
+      error: { code: "not-found", key: "upload-form" },
+    });
+    expect(sessionStorage.removeItem).toHaveBeenCalledTimes(2);
+  });
+
+  it("consumes pending state transactionally on an explicit resume", () => {
+    const resumeId = unwrap(
+      preserveSessionState("upload-form", { title: "Land deed" }),
+    );
+    const newToken = makeToken("user-a", "new");
+    accessTokens["auth-token"] = newToken;
+
+    expect(readSessionState("upload-form")).toEqual({
+      ok: false,
+      error: { code: "session-mismatch", key: "upload-form" },
+    });
+    expect(unwrap(consumeSessionResume(resumeId, newToken))).toEqual({
+      "upload-form": { title: "Land deed" },
+    });
+    expect(values["smalda-session-state:upload-form"]).toBeUndefined();
+    expect(values["smalda-session-state:__pending__"]).toBeUndefined();
+    expect(readSessionState("upload-form")).toEqual({
+      ok: false,
+      error: { code: "not-found", key: "upload-form" },
+    });
+  });
+
+  it("rejects a resume committed by a different JWT subject", () => {
+    accessTokens["auth-token"] = makeToken("user-a");
+    const resumeId = unwrap(
+      preserveSessionState("upload-form", { title: "Land deed" }),
+    );
+
+    accessTokens["auth-token"] = makeToken("user-b");
+    expect(commitSessionResume(resumeId, makeToken("user-b"))).toEqual({
+      ok: false,
+      error: { code: "session-mismatch", key: "upload-form" },
+    });
+    accessTokens["auth-token"] = makeToken("user-a");
+    expect(unwrap(commitSessionResume(resumeId, makeToken("user-a")))).toBe(1);
+    expect(values["smalda-session-state:upload-form"]).toBeUndefined();
+    expect(values["smalda-session-state:__pending__"]).toBeUndefined();
+  });
+
+  it("does not preserve state for an unverifiable token", () => {
+    accessTokens["auth-token"] = "opaque-old-token";
+
+    expect(
+      preserveSessionState("upload-form", { title: "Land deed" }),
+    ).toEqual({
+      ok: false,
+      error: { code: "unauthenticated", key: "upload-form" },
+    });
+  });
+
+  it("rejects a resume when the subject cannot be verified", () => {
+    const resumeId = unwrap(
+      preserveSessionState("upload-form", { title: "Land deed" }),
+    );
+    accessTokens["auth-token"] = "opaque-new-token";
+
+    expect(commitSessionResume(resumeId, "opaque-new-token")).toEqual({
+      ok: false,
+      error: { code: "session-mismatch", key: "upload-form" },
+    });
+  });
+
+  it("surfaces blocked reads and removal failures without losing state", () => {
+    unwrap(preserveSessionState("upload-form", { title: "Land deed" }));
+    blockGet = true;
+    expect(readSessionState("upload-form")).toEqual({
+      ok: false,
+      error: { code: "storage", key: "smalda-session-state:upload-form" },
+    });
+    blockGet = false;
+
+    blockLocalGet = true;
+    expect(readSessionState("upload-form")).toEqual({
+      ok: false,
+      error: { code: "storage", key: "auth-token" },
+    });
+    blockLocalGet = false;
+
+    blockRemove = true;
+    expect(consumeSessionState("upload-form")).toEqual({
+      ok: false,
+      error: { code: "removal", key: "smalda-session-state:upload-form" },
+    });
+    blockRemove = false;
+    expect(unwrap(readSessionState("upload-form"))).toEqual({
+      title: "Land deed",
+    });
+  });
+
+  it("does not claim resume success when state removal fails", () => {
+    const resumeId = unwrap(
+      preserveSessionState("upload-form", { title: "Land deed" }),
+    );
+    const newToken = makeToken("user-a", "new");
+    accessTokens["auth-token"] = newToken;
+    blockRemove = true;
+
+    expect(consumeSessionResume(resumeId, newToken)).toEqual({
+      ok: false,
+      error: { code: "removal", key: "smalda-session-state:upload-form" },
+    });
+
+    blockRemove = false;
+    expect(values["smalda-session-state:upload-form"]).toBeDefined();
+    expect(values["smalda-session-state:__pending__"]).toBeDefined();
+  });
+
+  it("rolls back a state write when the pending index cannot be written", () => {
+    blockSetKey = "smalda-session-state:__pending__";
+    expect(preserveSessionState("upload-form", { title: "Land deed" })).toEqual({
+      ok: false,
+      error: { code: "storage", key: "smalda-session-state:__pending__" },
+    });
+    blockSetKey = null;
+    expect(readSessionState("upload-form")).toEqual({
+      ok: false,
+      error: { code: "not-found", key: "upload-form" },
+    });
+  });
+
+  it("rejects File and Blob values instead of silently losing their bytes", () => {
+    expect(
+      preserveSessionState("upload", new File(["data"], "deed.pdf")),
+    ).toEqual({
+      ok: false,
+      error: { code: "serialization", key: "upload" },
+    });
+    expect(preserveSessionState("upload", new Blob(["data"]))).toEqual({
+      ok: false,
+      error: { code: "serialization", key: "upload" },
+    });
+  });
+
+  it("clears all preserved entries for an explicit logout", () => {
+    unwrap(preserveSessionState("first", { value: 1 }));
+    unwrap(preserveSessionState("second", { value: 2 }));
+
+    expect(clearAllSessionState()).toEqual({ ok: true, value: undefined });
+    expect(readSessionState("first")).toEqual({
+      ok: false,
+      error: { code: "not-found", key: "first" },
+    });
+    expect(readSessionState("second")).toEqual({
+      ok: false,
+      error: { code: "not-found", key: "second" },
+    });
+  });
+
+  it("can explicitly clear a single entry", () => {
+    unwrap(preserveSessionState("upload-form", { title: "Land deed" }));
+    expect(clearSessionState("upload-form")).toEqual({
+      ok: true,
+      value: undefined,
+    });
+    expect(readSessionState("upload-form")).toEqual({
+      ok: false,
+      error: { code: "not-found", key: "upload-form" },
+    });
+  });
+});
diff --git a/frontend/lib/api-client.ts b/frontend/lib/api-client.ts
index b83d5359..7dcc0e47 100644
--- a/frontend/lib/api-client.ts
+++ b/frontend/lib/api-client.ts
@@ -4,7 +4,7 @@
  * Exports a `request(path, options)` helper that:
  *   - reads NEXT_PUBLIC_API_URL as the base URL
  *   - attaches the JWT from localStorage as a Bearer header
- *   - on 401, attempts a silent refresh via POST /auth/refresh
+ *   - on 401, attempts a silent refresh via POST /api/v1/auth/refresh
  *   - if refresh also fails, clears the session and redirects to /login
  *   - parses JSON responses
  *   - throws typed ApiError for non-2xx responses
@@ -15,7 +15,25 @@
  * never surfaced.
  */
 
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
+import {
+  clearAllSessionState,
+  getPendingSessionResumeId,
+  type SessionStateError,
+  type SessionStateResult,
+} from "@/lib/session-state-preserver";
+
+function normalizeApiBase(value: string): string {
+  return value
+    .trim()
+    .replace(/\/+$/, "")
+    .replace(/(?:\/api)+(?:\/v1)?$/, "");
+}
+
+const API_BASE = normalizeApiBase(
+  process.env.NEXT_PUBLIC_API_URL?.trim() || "http://localhost:3001",
+);
+export const API_V1_BASE = `${API_BASE}/api/v1`;
+const REFRESH_ENDPOINT = `${API_V1_BASE}/auth/refresh`;
 
 const ACCESS_TOKEN_KEY = "auth-token";
 const REFRESH_TOKEN_KEY = "refresh-token";
@@ -36,12 +54,14 @@ export class ApiError extends Error {
   readonly kind: ApiErrorKind;
   readonly messageKey: string;
   readonly backendMessage?: string;
+  readonly stateError?: SessionStateError;
 
   constructor(opts: {
     status: number | null;
     kind: ApiErrorKind;
     messageKey: string;
     backendMessage?: string;
+    stateError?: SessionStateError;
   }) {
     super(opts.messageKey);
     this.name = "ApiError";
@@ -49,6 +69,7 @@ export class ApiError extends Error {
     this.kind = opts.kind;
     this.messageKey = opts.messageKey;
     this.backendMessage = opts.backendMessage;
+    this.stateError = opts.stateError;
   }
 }
 
@@ -79,12 +100,20 @@ export function classifyStatus(status: number): ApiErrorMapping {
 
 function getAccessToken(): string | null {
   if (typeof window === "undefined") return null;
-  return window.localStorage.getItem(ACCESS_TOKEN_KEY);
+  try {
+    return window.localStorage.getItem(ACCESS_TOKEN_KEY);
+  } catch {
+    return null;
+  }
 }
 
 function getRefreshToken(): string | null {
   if (typeof window === "undefined") return null;
-  return window.localStorage.getItem(REFRESH_TOKEN_KEY);
+  try {
+    return window.localStorage.getItem(REFRESH_TOKEN_KEY);
+  } catch {
+    return null;
+  }
 }
 
 function setAccessToken(token: string): void {
@@ -92,13 +121,29 @@ function setAccessToken(token: string): void {
   window.localStorage.setItem(ACCESS_TOKEN_KEY, token);
 }
 
-export function clearSession(): void {
-  if (typeof window === "undefined") return;
-  window.localStorage.removeItem(ACCESS_TOKEN_KEY);
-  window.localStorage.removeItem(REFRESH_TOKEN_KEY);
-  document.cookie = "token=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;";
-  // Signal other tabs to also redirect to login
-  window.localStorage.setItem("logout-event", Date.now().toString());
+export function clearSession(
+  options: { preserveSessionState?: boolean; notify?: boolean } = {},
+): SessionStateResult<void> {
+  invalidateRefresh();
+  if (typeof window === "undefined") {
+    return { ok: false, error: { code: "unavailable" } };
+  }
+
+  let result: SessionStateResult<void> = { ok: true, value: undefined };
+  try {
+    window.localStorage.removeItem(ACCESS_TOKEN_KEY);
+    window.localStorage.removeItem(REFRESH_TOKEN_KEY);
+    document.cookie = "token=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;";
+    if (options.notify !== false) {
+      window.localStorage.setItem("logout-event", Date.now().toString());
+    }
+  } catch {
+    result = { ok: false, error: { code: "storage" } };
+  }
+
+  if (options.preserveSessionState) return result;
+  const stateResult = clearAllSessionState();
+  return stateResult.ok ? result : stateResult;
 }
 
 /**
@@ -106,51 +151,162 @@ export function clearSession(): void {
  * then redirect to login. The login page's resolvePostLoginPath reads the
  * `?redirect=` param so the user lands back where they were after signing in.
  */
-function redirectToLogin(): void {
-  if (typeof window === "undefined") return;
+function redirectToLogin(): SessionStateResult<void> {
+  if (typeof window === "undefined") {
+    return { ok: false, error: { code: "unavailable" } };
+  }
   const currentPath = window.location.pathname + window.location.search;
   const params = new URLSearchParams();
   params.set("redirect", currentPath);
+  const resume = getPendingSessionResumeId();
+  if (resume.ok && resume.value) params.set("resume", resume.value);
   window.location.href = `/login?${params.toString()}`;
+  return resume.ok
+    ? { ok: true, value: undefined }
+    : propagateStateFailure(resume);
+}
+
+function propagateStateFailure(
+  result: { ok: false; error: SessionStateError },
+): SessionStateResult<void> {
+  return result;
 }
 
 // ── Refresh logic ───────────────────────────────────────────────────────────
 
-let refreshPromise: Promise<string> | null = null;
+interface RefreshResult {
+  accessToken: string;
+  refreshToken: string;
+  generation: number;
+}
+
+export class RefreshInvalidatedError extends Error {
+  constructor() {
+    super("Refresh invalidated");
+    this.name = "RefreshInvalidatedError";
+  }
+}
+
+let refreshPromise: Promise<RefreshResult> | null = null;
+let refreshAbortController: AbortController | null = null;
+let authGeneration = 0;
+
+function isRefreshInvalidatedError(error: unknown): boolean {
+  return error instanceof RefreshInvalidatedError;
+}
+
+export function invalidateRefresh(): void {
+  authGeneration += 1;
+  refreshPromise = null;
+  const controller = refreshAbortController;
+  refreshAbortController = null;
+  try {
+    controller?.abort();
+  } catch {
+    return;
+  }
+}
 
 /**
  * Attempt a silent token refresh. Deduplicates concurrent refresh calls
  * so that multiple 401s in-flight only trigger one refresh request.
  */
-async function refreshAccessToken(): Promise<string> {
+function refreshAccessToken(): Promise<RefreshResult> {
   if (refreshPromise) return refreshPromise;
 
-  refreshPromise = (async () => {
+  const generation = authGeneration;
+  const controller = new AbortController();
+  refreshAbortController = controller;
+  const promise = Promise.resolve().then(async () => {
     try {
+      if (generation !== authGeneration || controller.signal.aborted) {
+        throw new RefreshInvalidatedError();
+      }
       const refreshToken = getRefreshToken();
       if (!refreshToken) {
         throw new Error("No refresh token available");
       }
 
-      const res = await fetch(`${API_BASE}/auth/refresh`, {
+      const res = await fetch(REFRESH_ENDPOINT, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ refreshToken }),
+        signal: controller.signal,
       });
 
       if (!res.ok) {
         throw new Error("Refresh failed");
       }
 
-      const data = (await res.json()) as { access_token: string };
+      const data: unknown = await res.json();
+      if (
+        typeof data !== "object" ||
+        data === null ||
+        !("access_token" in data) ||
+        typeof data.access_token !== "string" ||
+        data.access_token.length === 0
+      ) {
+        throw new Error("Refresh response did not include an access token");
+      }
+      if (
+        generation !== authGeneration ||
+        controller.signal.aborted ||
+        getRefreshToken() !== refreshToken
+      ) {
+        throw new RefreshInvalidatedError();
+      }
       setAccessToken(data.access_token);
-      return data.access_token;
+      return {
+        accessToken: data.access_token,
+        refreshToken,
+        generation,
+      };
+    } catch (error) {
+      if (generation !== authGeneration || controller.signal.aborted) {
+        throw new RefreshInvalidatedError();
+      }
+      throw error;
     } finally {
-      refreshPromise = null;
+      if (refreshPromise === promise) refreshPromise = null;
+      if (refreshAbortController === controller) refreshAbortController = null;
     }
-  })();
+  });
+
+  refreshPromise = promise;
+  return promise;
+}
+
+export async function refreshSession(): Promise<void> {
+  await refreshAccessToken();
+}
 
-  return refreshPromise;
+function isRefreshResultCurrent(result: RefreshResult): boolean {
+  return (
+    result.generation === authGeneration &&
+    getRefreshToken() === result.refreshToken
+  );
+}
+
+function invalidatedRequestError(): ApiError {
+  return new ApiError({
+    status: null,
+    kind: "network",
+    messageKey: "errors.status.network",
+  });
+}
+
+function authRequiredError(): ApiError {
+  const cleared = clearSession({ preserveSessionState: true });
+  const redirected = redirectToLogin();
+  let stateError: SessionStateError | undefined;
+  if (!cleared.ok) stateError = cleared.error;
+  else if (!redirected.ok) stateError = redirected.error;
+  return new ApiError({
+    status: 401,
+    kind: "authRequired",
+    messageKey: "errors.status.unauthorized",
+    stateError,
+  });
 }
 
 // ── Request helper ──────────────────────────────────────────────────────────
@@ -191,7 +347,7 @@ async function extractBackendMessage(
  *   const data = await request<{ id: string }>("/documents", { method: "POST", body: { title: "..." } });
  *
  * On a 401 response the function will:
- *   1. Attempt a silent refresh via POST /auth/refresh
+ *   1. Attempt a silent refresh via POST /api/v1/auth/refresh
  *   2. If refresh succeeds, retry the original request with the new token
  *   3. If refresh also fails, clear the session and redirect to /login
  */
@@ -200,6 +356,7 @@ export async function request<T = unknown>(
   options: RequestOptions = {},
 ): Promise<T> {
   const { anonymous = false, ...fetchOpts } = options;
+  const requestGeneration = authGeneration;
 
   const url = path.startsWith("http") ? path : `${API_BASE}${path}`;
 
@@ -242,23 +399,45 @@ export async function request<T = unknown>(
     });
   }
 
+  if (requestGeneration !== authGeneration) {
+    throw invalidatedRequestError();
+  }
+
   // Handle 401 with refresh
   if (res.status === 401 && !anonymous) {
+    let refreshed: RefreshResult;
+    try {
+      refreshed = await refreshAccessToken();
+    } catch (error) {
+      if (isRefreshInvalidatedError(error)) {
+        throw invalidatedRequestError();
+      }
+      throw authRequiredError();
+    }
+    if (
+      requestGeneration !== authGeneration ||
+      !isRefreshResultCurrent(refreshed)
+    ) {
+      throw invalidatedRequestError();
+    }
     try {
-      const newToken = await refreshAccessToken();
-      res = await doFetch(newToken);
+      res = await doFetch(refreshed.accessToken);
     } catch {
-      // Refresh failed — clear session and redirect
-      clearSession();
-      redirectToLogin();
       throw new ApiError({
-        status: 401,
-        kind: "authRequired",
-        messageKey: "errors.status.unauthorized",
+        status: null,
+        kind: "network",
+        messageKey: "errors.status.network",
       });
     }
   }
 
+  if (requestGeneration !== authGeneration) {
+    throw invalidatedRequestError();
+  }
+  if (res.status === 401 && !anonymous) {
+    throw authRequiredError();
+  }
+
   // Handle non-2xx
   if (!res.ok) {
     const { kind, messageKey } = classifyStatus(res.status);
diff --git a/frontend/lib/auth-session.ts b/frontend/lib/auth-session.ts
index d6eda3f3..179162dc 100644
--- a/frontend/lib/auth-session.ts
+++ b/frontend/lib/auth-session.ts
@@ -1,35 +1,102 @@
-/**
- * Client-side session plumbing shared by the auth pages.
- *
- * FE-43's auth context is not in place yet, so the login page persists the
- * tokens it gets back from `POST /api/auth/login` through here. When the
- * context lands it should take ownership of these functions and the pages
- * should read the session off the context instead of touching storage.
- */
+import { invalidateRefresh } from "@/lib/api-client";
+import {
+  clearAllSessionState,
+  consumeSessionResume,
+  type SessionStateResult,
+} from "@/lib/session-state-preserver";
 
 const ACCESS_TOKEN_KEY = "auth-token";
-const REFRESH_TOKEN_KEY = "auth-refresh-token";
+const REFRESH_TOKEN_KEY = "refresh-token";
+const LOGOUT_EVENT_KEY = "logout-event";
 
-/** Shape of `POST /api/auth/login` — mirrors backend/src/auth/auth.service.ts. */
+/** Shape of `POST /api/v1/auth/login` — mirrors backend/src/auth/auth.service.ts. */
 export interface LoginResponse {
   access_token: string;
   refresh_token?: string;
 }
 
-export function storeSession(tokens: LoginResponse): void {
-  if (typeof window === "undefined") return;
-  if (tokens.access_token) {
+function unavailable<T>(): SessionStateResult<T> {
+  return { ok: false, error: { code: "unavailable" } };
+}
+
+function readLocalStorageItem(key: string): SessionStateResult<string | null> {
+  if (typeof window === "undefined") return unavailable<string | null>();
+  try {
+    return { ok: true, value: window.localStorage.getItem(key) };
+  } catch {
+    return { ok: false, error: { code: "storage", key } };
+  }
+}
+
+function restoreLocalStorageItem(
+  key: string,
+  value: string | null,
+): void {
+  try {
+    if (value === null) window.localStorage.removeItem(key);
+    else window.localStorage.setItem(key, value);
+  } catch {
+    return;
+  }
+}
+
+function invalidSession(): SessionStateResult<void> {
+  return { ok: false, error: { code: "unauthenticated" } };
+}
+
+export function storeSession(
+  tokens: LoginResponse,
+  resumeId?: string,
+): SessionStateResult<void> {
+  if (typeof window === "undefined") return unavailable<void>();
+  if (!tokens?.access_token) return invalidSession();
+
+  invalidateRefresh();
+  const previousAccess = readLocalStorageItem(ACCESS_TOKEN_KEY);
+  const previousRefresh = readLocalStorageItem(REFRESH_TOKEN_KEY);
+  if (!previousAccess.ok) return previousAccess;
+  if (!previousRefresh.ok) return previousRefresh;
+
+  try {
     window.localStorage.setItem(ACCESS_TOKEN_KEY, tokens.access_token);
+    if (tokens.refresh_token) {
+      window.localStorage.setItem(REFRESH_TOKEN_KEY, tokens.refresh_token);
+    } else {
+      window.localStorage.removeItem(REFRESH_TOKEN_KEY);
+    }
+  } catch {
+    restoreLocalStorageItem(ACCESS_TOKEN_KEY, previousAccess.value);
+    restoreLocalStorageItem(REFRESH_TOKEN_KEY, previousRefresh.value);
+    return { ok: false, error: { code: "storage" } };
   }
-  if (tokens.refresh_token) {
-    window.localStorage.setItem(REFRESH_TOKEN_KEY, tokens.refresh_token);
+
+  const stateResult = resumeId
+    ? consumeSessionResume(resumeId, tokens.access_token)
+    : clearAllSessionState();
+  if (!stateResult.ok) {
+    restoreLocalStorageItem(ACCESS_TOKEN_KEY, previousAccess.value);
+    restoreLocalStorageItem(REFRESH_TOKEN_KEY, previousRefresh.value);
+    return { ok: false, error: stateResult.error };
   }
+  return { ok: true, value: undefined };
 }
 
-export function clearSession(): void {
-  if (typeof window === "undefined") return;
-  window.localStorage.removeItem(ACCESS_TOKEN_KEY);
-  window.localStorage.removeItem(REFRESH_TOKEN_KEY);
+export function clearSession(): SessionStateResult<void> {
+  invalidateRefresh();
+  if (typeof window === "undefined") return unavailable<void>();
+
+  let result: SessionStateResult<void> = { ok: true, value: undefined };
+  try {
+    window.localStorage.removeItem(ACCESS_TOKEN_KEY);
+    window.localStorage.removeItem(REFRESH_TOKEN_KEY);
+    document.cookie = "token=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;";
+    window.localStorage.setItem(LOGOUT_EVENT_KEY, Date.now().toString());
+  } catch {
+    result = { ok: false, error: { code: "storage" } };
+  }
+
+  const stateResult = clearAllSessionState();
+  return stateResult.ok ? result : stateResult;
 }
 
 export const DEFAULT_POST_LOGIN_PATH = "/dashboard";
diff --git a/frontend/lib/bundle-config.ts b/frontend/lib/bundle-config.ts
index 91bea31b..b8c50867 100644
--- a/frontend/lib/bundle-config.ts
+++ b/frontend/lib/bundle-config.ts
@@ -1,7 +1,8 @@
-export interface BundleConfig {
-  dynamicImportHeavyDeps: boolean;
-}
-
-export const bundleConfig: BundleConfig = {
-  dynamicImportHeavyDeps: true,
-};
+/**
+ * The map route owns the application’s intentional client-only bundle split.
+ * Leaflet and the map content depend on browser APIs, so the boundary must
+ * remain `ssr: false`; the policy lives at the actual dynamic import site.
+ */
+export const clientOnlyBundleBoundary = {
+  ssr: false,
+} as const;
diff --git a/frontend/lib/image-loader.ts b/frontend/lib/image-loader.ts
index 8ad7bd65..acd0f91a 100644
--- a/frontend/lib/image-loader.ts
+++ b/frontend/lib/image-loader.ts
@@ -1,5 +1,77 @@
-export function getOptimizedImageUrl(src: string, width = 300, quality = 75): string {
-  if (!src) return '';
-  if (src.startsWith('data:') || src.startsWith('blob:')) return src;
-  return `${src}?w=${width}&q=${quality}`;
+import type { ImageLoader } from "next/image";
+
+const NEXT_IMAGE_PATH = "/_next/image";
+const DEFAULT_QUALITY = 75;
+const SIGNED_QUERY_KEYS = new Set([
+  "signature",
+  "sig",
+  "token",
+  "expires",
+  "policy",
+  "key-pair-id",
+  "x-amz-signature",
+  "x-amz-credential",
+  "x-amz-date",
+  "x-amz-security-token",
+]);
+
+/**
+ * Build URLs through Next's built-in image optimizer. That endpoint negotiates
+ * WebP (or another configured format) from the request's Accept header. A
+ * custom loader has a single-string contract, so it cannot expose a separate
+ * <picture> fallback itself; callers needing one must provide it explicitly.
+ *
+ * Signed image URLs are returned unchanged. Proxying or rewriting those URLs
+ * can invalidate provider signatures, and the original URL is the safe
+ * unoptimized source when its signature is opaque to this application; it is
+ * not a separate browser-format fallback. Non-local HTTP
+ * sources still need an explicit `images.remotePatterns` entry before Next's
+ * optimizer will fetch them.
+ */
+function buildNextImageUrl(
+  src: string,
+  width: number,
+  quality = DEFAULT_QUALITY,
+): string {
+  if (!src || src.startsWith("data:") || src.startsWith("blob:")) return src;
+  if (src.startsWith("//")) {
+    throw new Error("Protocol-relative image URLs are not supported");
+  }
+
+  const hashIndex = src.indexOf("#");
+  const source = hashIndex === -1 ? src : src.slice(0, hashIndex);
+  const fragment = hashIndex === -1 ? "" : src.slice(hashIndex);
+  const queryIndex = source.indexOf("?");
+  const query = queryIndex === -1 ? "" : source.slice(queryIndex + 1);
+  const isSigned = [...new URLSearchParams(query).keys()].some((key) => {
+    const normalizedKey = key.toLowerCase();
+    return (
+      SIGNED_QUERY_KEYS.has(normalizedKey) ||
+      normalizedKey.startsWith("x-amz-")
+    );
+  });
+
+  const isNextImageUrl =
+    source === NEXT_IMAGE_PATH || source.startsWith(`${NEXT_IMAGE_PATH}?`);
+  if (isSigned || isNextImageUrl) return src;
+
+  const params = new URLSearchParams();
+  params.set("url", source);
+  params.set("w", String(width));
+  params.set("q", String(quality));
+
+  return `${NEXT_IMAGE_PATH}?${params.toString()}${fragment}`;
 }
+
+export function getOptimizedImageUrl(
+  src: string,
+  width = 300,
+  quality = DEFAULT_QUALITY,
+): string {
+  return buildNextImageUrl(src, width, quality);
+}
+
+const imageLoader: ImageLoader = ({ src, width, quality }) =>
+  buildNextImageUrl(src, width, quality);
+
+export default imageLoader;
diff --git a/frontend/lib/session-expiry-warning.ts b/frontend/lib/session-expiry-warning.ts
index b62dc203..3f5f131b 100644
--- a/frontend/lib/session-expiry-warning.ts
+++ b/frontend/lib/session-expiry-warning.ts
@@ -1,33 +1,86 @@
 "use client";
 
-import { useEffect, useRef, useCallback } from "react";
+import { useCallback, useEffect, useRef } from "react";
+import { clearSession } from "@/lib/api-client";
 
 const ACCESS_TOKEN_KEY = "auth-token";
+const WARNING_BEFORE_MS = 5 * 60 * 1000;
+const ACTIVITY_GRACE_MS = 60 * 1000;
+const ACTIVITY_DEBOUNCE_MS = 250;
+const ACTIVITY_EVENTS = [
+  "keydown",
+  "beforeinput",
+  "input",
+  "focusin",
+  "pointerdown",
+  "mousedown",
+  "click",
+] as const;
+
+function decodeBase64Url(value: string): string | null {
+  try {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padding = (4 - (normalized.length % 4)) % 4;
+    const binary = atob(normalized + "=".repeat(padding));
+    if (typeof TextDecoder === "undefined") return binary;
+    const bytes = Uint8Array.from(binary, (character) =>
+      character.charCodeAt(0),
+    );
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return null;
+  }
+}
 
-// ── JWT expiry helper ───────────────────────────────────────────────────────
+export function getTokenExpiryMs(token: string): number | null {
+  const payloadPart = token.split(".")[1];
+  if (!payloadPart) return null;
+  const decoded = decodeBase64Url(payloadPart);
+  if (!decoded) return null;
 
-function getTokenExpiryMs(token: string): number | null {
   try {
-    const payload = JSON.parse(atob(token.split(".")[1]));
-    if (!payload.exp) return null;
-    // exp is in seconds; return ms until expiry
+    const payload: unknown = JSON.parse(decoded);
+    if (
+      typeof payload !== "object" ||
+      payload === null ||
+      !("exp" in payload) ||
+      typeof payload.exp !== "number" ||
+      !Number.isFinite(payload.exp)
+    ) {
+      return null;
+    }
     return payload.exp * 1000 - Date.now();
   } catch {
     return null;
   }
 }
 
-// ── Cross-tab logout sync ───────────────────────────────────────────────────
+function readAccessToken(): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.localStorage.getItem(ACCESS_TOKEN_KEY);
+  } catch {
+    return null;
+  }
+}
+
+function isEditingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  return (
+    target.isContentEditable ||
+    target instanceof HTMLInputElement ||
+    target instanceof HTMLTextAreaElement ||
+    target instanceof HTMLSelectElement ||
+    target.getAttribute("role") === "textbox"
+  );
+}
 
-/**
- * Listen for the `logout-event` localStorage key written by clearSession()
- * in other tabs and redirect to login. Call once on app bootstrap.
- */
 export function initCrossTabLogoutSync(): () => void {
   if (typeof window === "undefined") return () => {};
 
   function handler(event: StorageEvent) {
     if (event.key === "logout-event" && event.newValue) {
+      clearSession({ notify: false });
       window.location.href = "/login";
     }
   }
@@ -36,77 +89,162 @@ export function initCrossTabLogoutSync(): () => void {
   return () => window.removeEventListener("storage", handler);
 }
 
-// ── Session expiry warning hook ─────────────────────────────────────────────
-
-const WARNING_BEFORE_MS = 5 * 60 * 1000; // warn 5 minutes before expiry
-
-interface UseSessionExpiryWarningOptions {
-  /** Called when the user clicks "Stay signed in" — should trigger a refresh. */
-  onRefresh: () => Promise<void>;
-  /** Whether the user is currently authenticated (skip if false). */
+export interface UseSessionExpiryWarningOptions {
+  onRefresh?: () => Promise<void>;
   enabled?: boolean;
 }
 
-/**
- * Polls the access token's `exp` claim and prompts the user with a
- * "Stay signed in?" dialog a few minutes before the session expires.
- *
- * If the user confirms, calls `onRefresh`. If they dismiss or the token
- * expires, the consumer should handle the redirect (the api-client's 401
- * interceptor will do this automatically on the next request).
- */
 export function useSessionExpiryWarning({
   onRefresh,
   enabled = true,
 }: UseSessionExpiryWarningOptions) {
+  const onRefreshRef = useRef(onRefresh);
+  onRefreshRef.current = onRefresh;
+  const warningTokenRef = useRef<string | null>(null);
   const warningShownRef = useRef(false);
   const promptRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const activityDebounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastActivityAtRef = useRef<number | null>(null);
 
-  const clearTimer = useCallback(() => {
+  const clearTimers = useCallback(() => {
     if (promptRef.current !== null) {
       clearTimeout(promptRef.current);
       promptRef.current = null;
     }
+    if (activityDebounceRef.current !== null) {
+      clearTimeout(activityDebounceRef.current);
+      activityDebounceRef.current = null;
+    }
   }, []);
 
   useEffect(() => {
     if (!enabled || typeof window === "undefined") return;
 
-    function schedulePrompt() {
-      clearTimer();
-
-      const token = window.localStorage.getItem(ACCESS_TOKEN_KEY);
+    let disposed = false;
+    warningShownRef.current = false;
+    lastActivityAtRef.current = null;
+    const listenerOptions: AddEventListenerOptions = { capture: true };
+
+    function schedulePrompt(
+      afterActivity = false,
+      activityAt?: number,
+    ) {
+      if (promptRef.current !== null) {
+        clearTimeout(promptRef.current);
+        promptRef.current = null;
+      }
+      if (disposed) return;
+
+      const token = readAccessToken();
       if (!token) return;
-
-      const remainingMs = getTokenExpiryMs(token);
-      if (remainingMs === null || remainingMs <= 0) return;
-
-      const delayMs = Math.max(remainingMs - WARNING_BEFORE_MS, 0);
+      if (warningTokenRef.current !== token) {
+        warningTokenRef.current = token;
+        warningShownRef.current = false;
+      }
+      if (warningShownRef.current) return;
+
+      const now = Date.now();
+      const currentRemainingMs = getTokenExpiryMs(token);
+      if (currentRemainingMs === null || currentRemainingMs <= 0) return;
+      const remainingAtReference =
+        currentRemainingMs +
+        (afterActivity && activityAt !== undefined
+          ? Math.max(0, now - activityAt)
+          : 0);
+      if (remainingAtReference <= 0) return;
+      const warningDelayAtReference = Math.max(
+        remainingAtReference - WARNING_BEFORE_MS,
+        0,
+      );
+      const delayMs = afterActivity
+        ? Math.min(
+            remainingAtReference,
+            warningDelayAtReference + ACTIVITY_GRACE_MS,
+          )
+        : warningDelayAtReference;
 
       promptRef.current = setTimeout(() => {
+        promptRef.current = null;
+        if (disposed) return;
+
+        const currentToken = readAccessToken();
+        if (currentToken !== token) {
+          warningTokenRef.current = null;
+          warningShownRef.current = false;
+          lastActivityAtRef.current = null;
+          schedulePrompt();
+          return;
+        }
         if (warningShownRef.current) return;
+        warningTokenRef.current = token;
         warningShownRef.current = true;
 
-        // Simple confirm dialog — can be replaced with a custom UI later
-        const staySignedIn = window.confirm(
-          "Your session is about to expire. Stay signed in?",
-        );
-
-        if (staySignedIn) {
-          onRefresh()
-            .then(() => {
-              warningShownRef.current = false;
-              schedulePrompt();
-            })
-            .catch(() => {
-              // Refresh failed — api-client will redirect on next 401
-            });
+        let staySignedIn = false;
+        try {
+          staySignedIn = window.confirm(
+            "Your session is about to expire. Stay signed in?",
+          );
+        } catch {
+          return;
         }
+        if (!staySignedIn) return;
+
+        const refresh = onRefreshRef.current;
+        if (!refresh) return;
+        Promise.resolve()
+          .then(() => refresh())
+          .then(() => {
+            if (disposed) return;
+            warningTokenRef.current = null;
+            warningShownRef.current = false;
+            schedulePrompt();
+          })
+          .catch(() => {
+            if (disposed) return;
+            warningTokenRef.current = null;
+            warningShownRef.current = false;
+            schedulePrompt(true);
+          });
       }, delayMs);
     }
 
-    schedulePrompt();
+    function handleActivity(event: Event) {
+      const activeElement = document.activeElement;
+      const editingEvent =
+        isEditingTarget(event.target) ||
+        ((event.type === "click" ||
+          event.type === "pointerdown" ||
+          event.type === "mousedown") &&
+          isEditingTarget(activeElement));
+      if (!editingEvent) return;
+
+      const activityAt = Date.now();
+      lastActivityAtRef.current = activityAt;
+      if (promptRef.current !== null) {
+        clearTimeout(promptRef.current);
+        promptRef.current = null;
+      }
+      if (activityDebounceRef.current !== null) {
+        clearTimeout(activityDebounceRef.current);
+      }
+      activityDebounceRef.current = setTimeout(() => {
+        activityDebounceRef.current = null;
+        schedulePrompt(true, lastActivityAtRef.current ?? activityAt);
+      }, ACTIVITY_DEBOUNCE_MS);
+    }
 
-    return clearTimer;
-  }, [enabled, onRefresh, clearTimer]);
+    schedulePrompt();
+    ACTIVITY_EVENTS.forEach((eventName) => {
+      window.addEventListener(eventName, handleActivity, listenerOptions);
+    });
+
+    return () => {
+      disposed = true;
+      ACTIVITY_EVENTS.forEach((eventName) => {
+        window.removeEventListener(eventName, handleActivity, listenerOptions);
+      });
+      lastActivityAtRef.current = null;
+      clearTimers();
+    };
+  }, [enabled, clearTimers]);
 }
diff --git a/frontend/lib/session-state-preserver.ts b/frontend/lib/session-state-preserver.ts
index a5cbf70b..8a819c1a 100644
--- a/frontend/lib/session-state-preserver.ts
+++ b/frontend/lib/session-state-preserver.ts
@@ -1,55 +1,627 @@
 /**
- * Simple helper to preserve in-progress form and upload state across a
- * session-expiry redirect.
+ * Transactional storage for JSON-only form state across an authentication
+ * redirect. State is bound to the current access token and to a one-time
+ * resume group; a resume commit requires JWT `sub` claims and verifies that
+ * the replacement token belongs to the same subject. Use
+ * readSessionState followed by commitSessionState when a value can fail while
+ * it is being applied; consumeSessionResume returns restored values while
+ * removing the pending group transactionally. restoreSessionState is the
+ * one-shot consume variant.
  *
- * Usage:
- *   // Before the redirect (e.g. in a form component):
- *   preserveSessionState("upload-form", { file: fileData, annotations: [...] });
- *
- *   // After login, restore:
- *   const saved = restoreSessionState<UploadState>("upload-form");
- *   if (saved) { /* repopulate form */ }
- *
- * State is stored in sessionStorage so it survives a redirect but is
- * automatically cleared when the tab is closed.
+ * File and Blob instances are intentionally rejected because JSON does not
+ * preserve their bytes. Preserve metadata such as a file name and obtain the
+ * original file again through the upload flow.
  */
 
 const SESSION_STATE_PREFIX = "smalda-session-state:";
+const PENDING_RESUMES_KEY = `${SESSION_STATE_PREFIX}__pending__`;
+const ACCESS_TOKEN_KEY = "auth-token";
+const STORAGE_VERSION = 1;
 
-/**
- * Save in-progress state before a session-expiry redirect.
- * Serializes to JSON and stores in sessionStorage.
- */
-export function preserveSessionState<T = unknown>(
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type SessionStateErrorCode =
+  | "invalid-key"
+  | "unavailable"
+  | "unauthenticated"
+  | "not-found"
+  | "serialization"
+  | "storage"
+  | "parse"
+  | "session-mismatch"
+  | "resume-not-found"
+  | "removal";
+
+export interface SessionStateError {
+  code: SessionStateErrorCode;
+  key?: string;
+}
+
+export type SessionStateResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: SessionStateError };
+
+interface StoredSessionState {
+  version: typeof STORAGE_VERSION;
+  key: string;
+  resumeId: string;
+  sessionId: string;
+  subject: string | null;
+  state: JsonValue;
+}
+
+interface PendingResume {
+  resumeId: string;
+  keys: string[];
+}
+
+interface StorageWrite {
+  key: string;
+  value: string | null;
+}
+
+function failure<T>(
+  code: SessionStateErrorCode,
+  key?: string,
+): SessionStateResult<T> {
+  return { ok: false, error: key ? { code, key } : { code } };
+}
+
+function propagateFailure<T>(
+  result: { ok: false; error: SessionStateError },
+): SessionStateResult<T> {
+  return result;
+}
+
+function getStateKey(key: string): string {
+  return `${SESSION_STATE_PREFIX}${key}`;
+}
+
+function getStorage(): Storage | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+function readAccessToken(): SessionStateResult<string | null> {
+  if (typeof window === "undefined") return failure("unavailable");
+  try {
+    return { ok: true, value: window.localStorage.getItem(ACCESS_TOKEN_KEY) };
+  } catch {
+    return failure("storage", ACCESS_TOKEN_KEY);
+  }
+}
+
+function readItem(
+  storage: Storage,
   key: string,
-  state: T,
+): SessionStateResult<string | null> {
+  try {
+    return { ok: true, value: storage.getItem(key) };
+  } catch {
+    return failure("storage", key);
+  }
+}
+
+function writeItem(
+  storage: Storage,
+  key: string,
+  value: string,
+): SessionStateResult<void> {
+  try {
+    storage.setItem(key, value);
+    return { ok: true, value: undefined };
+  } catch {
+    return failure("storage", key);
+  }
+}
+
+function removeItem(
+  storage: Storage,
+  key: string,
+): SessionStateResult<void> {
+  try {
+    storage.removeItem(key);
+    return { ok: true, value: undefined };
+  } catch {
+    return failure("removal", key);
+  }
+}
+
+function restoreItem(
+  storage: Storage,
+  key: string,
+  previousValue: string | null,
 ): void {
-  if (typeof window === "undefined") return;
   try {
-    window.sessionStorage.setItem(
-      `${SESSION_STATE_PREFIX}${key}`,
-      JSON.stringify(state),
-    );
+    if (previousValue === null) storage.removeItem(key);
+    else storage.setItem(key, previousValue);
   } catch {
-    // sessionStorage full or unavailable — best-effort only
+    // Rollback is best effort; the original failure is returned to the caller.
   }
 }
 
-/**
- * Restore previously-saved state after login. Returns null if nothing was
- * saved under the given key. Clears the stored state after reading so it
- * isn't restored twice.
- */
-export function restoreSessionState<T = unknown>(
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isJsonValue(value: unknown, ancestors = new Set<object>()): boolean {
+  if (value === null) return true;
+  if (typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "object" || ancestors.has(value)) return false;
+
+  try {
+    const prototype = Object.getPrototypeOf(value);
+    if (
+      !Array.isArray(value) &&
+      prototype !== Object.prototype &&
+      prototype !== null
+    ) {
+      return false;
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+      return value.every((item) => isJsonValue(item, ancestors));
+    }
+    return Object.values(value).every((item) => isJsonValue(item, ancestors));
+  } catch {
+    return false;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function serializeJson(value: unknown): SessionStateResult<string> {
+  try {
+    if (!isJsonValue(value)) return failure("serialization");
+    const serialized = JSON.stringify(value);
+    return serialized === undefined
+      ? failure("serialization")
+      : { ok: true, value: serialized };
+  } catch {
+    return failure("serialization");
+  }
+}
+
+function parseStoredState(
+  raw: string,
   key: string,
-): T | null {
-  if (typeof window === "undefined") return null;
+): SessionStateResult<StoredSessionState> {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    const subject = isRecord(parsed) ? parsed.subject : undefined;
+    if (
+      !isRecord(parsed) ||
+      parsed.version !== STORAGE_VERSION ||
+      parsed.key !== key ||
+      typeof parsed.resumeId !== "string" ||
+      parsed.resumeId.length === 0 ||
+      typeof parsed.sessionId !== "string" ||
+      parsed.sessionId.length === 0 ||
+      (subject !== null && typeof subject !== "string") ||
+      !isJsonValue(parsed.state)
+    ) {
+      return failure("parse", getStateKey(key));
+    }
+    return {
+      ok: true,
+      value: {
+        version: STORAGE_VERSION,
+        key,
+        resumeId: parsed.resumeId,
+        sessionId: parsed.sessionId,
+        subject: subject as string | null,
+        state: parsed.state as JsonValue,
+      },
+    };
+  } catch {
+    return failure("parse", getStateKey(key));
+  }
+}
+
+function parsePendingResume(
+  raw: string | null,
+): SessionStateResult<PendingResume | null> {
+  if (raw === null) return { ok: true, value: null };
   try {
-    const raw = window.sessionStorage.getItem(`${SESSION_STATE_PREFIX}${key}`);
-    if (!raw) return null;
-    window.sessionStorage.removeItem(`${SESSION_STATE_PREFIX}${key}`);
-    return JSON.parse(raw) as T;
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      !isRecord(parsed) ||
+      typeof parsed.resumeId !== "string" ||
+      parsed.resumeId.length === 0 ||
+      !Array.isArray(parsed.keys) ||
+      !parsed.keys.every((key) => typeof key === "string" && key.length > 0)
+    ) {
+      return failure("parse", PENDING_RESUMES_KEY);
+    }
+    const keys = parsed.keys.filter(
+      (key: unknown): key is string =>
+        typeof key === "string" && key.length > 0,
+    );
+    return {
+      ok: true,
+      value: { resumeId: parsed.resumeId, keys: [...new Set(keys)] },
+    };
+  } catch {
+    return failure("parse", PENDING_RESUMES_KEY);
+  }
+}
+
+function readPendingResume(
+  storage: Storage,
+): SessionStateResult<PendingResume | null> {
+  const raw = readItem(storage, PENDING_RESUMES_KEY);
+  return raw.ok ? parsePendingResume(raw.value) : propagateFailure(raw);
+}
+
+function serializePendingResume(
+  pending: PendingResume | null,
+): SessionStateResult<string | null> {
+  if (pending === null) return { ok: true, value: null };
+  const serialized = serializeJson(pending);
+  return serialized.ok ? serialized : propagateFailure(serialized);
+}
+
+function applyWrites(
+  storage: Storage,
+  writes: StorageWrite[],
+): SessionStateResult<void> {
+  const previous: string | null[] = [];
+  for (const write of writes) {
+    const current = readItem(storage, write.key);
+    if (!current.ok) return propagateFailure(current);
+    previous.push(current.value);
+  }
+
+  for (let index = 0; index < writes.length; index += 1) {
+    const write = writes[index];
+    const result =
+      write.value === null
+        ? removeItem(storage, write.key)
+        : writeItem(storage, write.key, write.value);
+    if (!result.ok) {
+      for (
+        let rollbackIndex = 0;
+        rollbackIndex < writes.length;
+        rollbackIndex += 1
+      ) {
+        restoreItem(storage, writes[rollbackIndex].key, previous[rollbackIndex]);
+      }
+      return propagateFailure(result);
+    }
+  }
+  return { ok: true, value: undefined };
+}
+
+function createResumeId(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+export function getAccessTokenFingerprint(token: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < token.length; index += 1) {
+    hash ^= token.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `token-${(hash >>> 0).toString(16)}`;
+}
+
+function decodeBase64Url(value: string): string | null {
+  try {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padding = (4 - (normalized.length % 4)) % 4;
+    const binary = atob(normalized + "=".repeat(padding));
+    if (typeof TextDecoder === "undefined") return binary;
+    const bytes = Uint8Array.from(binary, (character) =>
+      character.charCodeAt(0),
+    );
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+function getTokenSubject(token: string): string | null {
+  const payloadPart = token.split(".")[1];
+  if (!payloadPart) return null;
+  const decoded = decodeBase64Url(payloadPart);
+  if (!decoded) return null;
+  try {
+    const payload: unknown = JSON.parse(decoded);
+    if (
+      typeof payload === "object" &&
+      payload !== null &&
+      "sub" in payload &&
+      typeof payload.sub === "string" &&
+      payload.sub.length > 0
+    ) {
+      return payload.sub;
+    }
   } catch {
     return null;
   }
+  return null;
+}
+
+function getCurrentSessionIdResult(): SessionStateResult<string | null> {
+  const token = readAccessToken();
+  if (!token.ok) return propagateFailure(token);
+  return {
+    ok: true,
+    value: token.value ? getAccessTokenFingerprint(token.value) : null,
+  };
+}
+
+export function getCurrentSessionId(): SessionStateResult<string | null> {
+  return getCurrentSessionIdResult();
+}
+
+function resolveSessionId(
+  sessionId: string | null | undefined,
+): SessionStateResult<string | null> {
+  return sessionId === undefined
+    ? getCurrentSessionId()
+    : { ok: true, value: sessionId };
+}
+
+export function getPendingSessionResumeId(): SessionStateResult<string | null> {
+  const storage = getStorage();
+  if (!storage) return failure("unavailable");
+  const pending = readPendingResume(storage);
+  return pending.ok
+    ? { ok: true, value: pending.value?.resumeId ?? null }
+    : propagateFailure(pending);
+}
+
+export function preserveSessionState<T>(
+  key: string,
+  state: T,
+): SessionStateResult<string> {
+  if (!key || key === "__pending__") return failure("invalid-key", key);
+  const storage = getStorage();
+  if (!storage) return failure("unavailable", key);
+  const tokenResult = readAccessToken();
+  if (!tokenResult.ok) return propagateFailure(tokenResult);
+  if (!tokenResult.value) return failure("unauthenticated", key);
+  const token = tokenResult.value;
+  const subject = getTokenSubject(token);
+  if (!subject) return failure("unauthenticated", key);
+
+  const serializedState = serializeJson(state);
+  if (!serializedState.ok) return failure("serialization", key);
+  let stateValue: JsonValue;
+  try {
+    stateValue = JSON.parse(serializedState.value) as JsonValue;
+  } catch {
+    return failure("serialization", key);
+  }
+
+  const pending = readPendingResume(storage);
+  if (!pending.ok) return propagateFailure(pending);
+  const resumeId = pending.value?.resumeId ?? createResumeId();
+  const keys = [...new Set([...(pending.value?.keys ?? []), key])];
+  const stored: StoredSessionState = {
+    version: STORAGE_VERSION,
+    key,
+    resumeId,
+    sessionId: getAccessTokenFingerprint(token),
+    subject,
+    state: stateValue,
+  };
+  const serializedStored = serializeJson(stored);
+  const serializedPending = serializePendingResume({
+    resumeId,
+    keys,
+  });
+  if (!serializedStored.ok) return failure("serialization", key);
+  if (!serializedPending.ok) return failure("serialization", PENDING_RESUMES_KEY);
+
+  const committed = applyWrites(storage, [
+    { key: getStateKey(key), value: serializedStored.value },
+    { key: PENDING_RESUMES_KEY, value: serializedPending.value },
+  ]);
+  return committed.ok
+    ? { ok: true, value: resumeId }
+    : propagateFailure(committed);
+}
+
+export type ResumedSessionState = Record<string, JsonValue>;
+
+export function consumeSessionResume(
+  resumeId: string,
+  accessToken: string,
+): SessionStateResult<ResumedSessionState> {
+  if (!resumeId || !accessToken) return failure("resume-not-found", resumeId);
+  const storage = getStorage();
+  if (!storage) return failure("unavailable", resumeId);
+  const pending = readPendingResume(storage);
+  if (!pending.ok) return propagateFailure(pending);
+  if (!pending.value || pending.value.resumeId !== resumeId) {
+    return failure("resume-not-found", resumeId);
+  }
+
+  const sessionId = getAccessTokenFingerprint(accessToken);
+  const currentSessionId = getCurrentSessionIdResult();
+  if (!currentSessionId.ok) return propagateFailure(currentSessionId);
+  if (currentSessionId.value !== sessionId) {
+    return failure("session-mismatch", resumeId);
+  }
+  const resumedState: ResumedSessionState = Object.create(null) as ResumedSessionState;
+  const writes: StorageWrite[] = [];
+  for (const key of pending.value.keys) {
+    const raw = readItem(storage, getStateKey(key));
+    if (!raw.ok) return propagateFailure(raw);
+    if (raw.value === null) return failure("not-found", key);
+    const parsed = parseStoredState(raw.value, key);
+    if (!parsed.ok) return propagateFailure(parsed);
+    if (parsed.value.resumeId !== resumeId) return failure("parse", key);
+    const nextSubject = getTokenSubject(accessToken);
+    if (parsed.value.subject === null || nextSubject === null) {
+      return failure("session-mismatch", key);
+    }
+    if (parsed.value.subject !== nextSubject) {
+      return failure("session-mismatch", key);
+    }
+    resumedState[key] = parsed.value.state;
+    writes.push({ key: getStateKey(key), value: null });
+  }
+  writes.push({ key: PENDING_RESUMES_KEY, value: null });
+  const committed = applyWrites(storage, writes);
+  return committed.ok
+    ? { ok: true, value: resumedState }
+    : propagateFailure(committed);
+}
+
+export function commitSessionResume(
+  resumeId: string,
+  accessToken: string,
+): SessionStateResult<number> {
+  const consumed = consumeSessionResume(resumeId, accessToken);
+  return consumed.ok
+    ? { ok: true, value: Object.keys(consumed.value).length }
+    : propagateFailure(consumed);
+}
+
+export function readSessionState<T>(
+  key: string,
+  sessionId?: string | null,
+): SessionStateResult<T> {
+  if (!key) return failure("invalid-key", key);
+  const resolvedSessionId = resolveSessionId(sessionId);
+  if (!resolvedSessionId.ok) return propagateFailure(resolvedSessionId);
+  if (!resolvedSessionId.value) return failure("unauthenticated", key);
+  const storage = getStorage();
+  if (!storage) return failure("unavailable", key);
+  const raw = readItem(storage, getStateKey(key));
+  if (!raw.ok) return propagateFailure(raw);
+  if (raw.value === null) return failure("not-found", key);
+  const parsed = parseStoredState(raw.value, key);
+  if (!parsed.ok) return propagateFailure(parsed);
+  if (parsed.value.sessionId !== resolvedSessionId.value) {
+    return failure("session-mismatch", key);
+  }
+  return { ok: true, value: parsed.value.state as T };
+}
+
+function pendingWithoutKey(
+  pending: PendingResume | null,
+  key: string,
+): PendingResume | null {
+  if (!pending || !pending.keys.includes(key)) return pending;
+  const keys = pending.keys.filter((pendingKey) => pendingKey !== key);
+  return keys.length === 0 ? null : { ...pending, keys };
+}
+
+export function commitSessionState(
+  key: string,
+  sessionId?: string | null,
+): SessionStateResult<void> {
+  const read = readSessionState<JsonValue>(key, sessionId);
+  if (!read.ok) return propagateFailure(read);
+  const storage = getStorage();
+  if (!storage) return failure("unavailable", key);
+  const raw = readItem(storage, getStateKey(key));
+  if (!raw.ok) return propagateFailure(raw);
+  if (raw.value === null) return failure("not-found", key);
+  const parsed = parseStoredState(raw.value, key);
+  if (!parsed.ok) return propagateFailure(parsed);
+  const pending = readPendingResume(storage);
+  if (!pending.ok) return propagateFailure(pending);
+  const nextPending = pendingWithoutKey(pending.value, key);
+  const serializedPending = serializePendingResume(nextPending);
+  if (!serializedPending.ok) return propagateFailure(serializedPending);
+  const writes: StorageWrite[] = [
+    { key: getStateKey(key), value: null },
+  ];
+  if (nextPending !== pending.value) {
+    writes.push({ key: PENDING_RESUMES_KEY, value: serializedPending.value });
+  }
+  const committed = applyWrites(storage, writes);
+  return committed.ok ? committed : propagateFailure(committed);
+}
+
+export function consumeSessionState<T>(
+  key: string,
+  sessionId?: string | null,
+): SessionStateResult<T> {
+  const read = readSessionState<T>(key, sessionId);
+  if (!read.ok) return read;
+  const committed = commitSessionState(key, sessionId);
+  return committed.ok
+    ? { ok: true, value: read.value }
+    : propagateFailure(committed);
+}
+
+export function restoreSessionState<T>(
+  key: string,
+  sessionId?: string | null,
+): SessionStateResult<T> {
+  return consumeSessionState<T>(key, sessionId);
+}
+
+export function clearSessionState(
+  key: string,
+  sessionId?: string | null,
+): SessionStateResult<void> {
+  if (!key) return failure("invalid-key", key);
+  const storage = getStorage();
+  if (!storage) return failure("unavailable", key);
+  const raw = readItem(storage, getStateKey(key));
+  if (!raw.ok) return propagateFailure(raw);
+  if (raw.value !== null && sessionId !== undefined) {
+    if (!sessionId) return failure("unauthenticated", key);
+    const parsed = parseStoredState(raw.value, key);
+    if (!parsed.ok) return propagateFailure(parsed);
+    if (parsed.value.sessionId !== sessionId) {
+      return failure("session-mismatch", key);
+    }
+  }
+
+  const pending = readPendingResume(storage);
+  if (!pending.ok) return propagateFailure(pending);
+  const nextPending = pendingWithoutKey(pending.value, key);
+  const serializedPending = serializePendingResume(nextPending);
+  if (!serializedPending.ok) return propagateFailure(serializedPending);
+  const writes: StorageWrite[] = [];
+  if (raw.value !== null) writes.push({ key: getStateKey(key), value: null });
+  if (nextPending !== pending.value) {
+    writes.push({ key: PENDING_RESUMES_KEY, value: serializedPending.value });
+  }
+  return writes.length === 0
+    ? { ok: true, value: undefined }
+    : applyWrites(storage, writes);
+}
+
+export function clearAllSessionState(): SessionStateResult<void> {
+  const storage = getStorage();
+  if (!storage) return failure("unavailable");
+  let length: number;
+  try {
+    length = storage.length;
+  } catch {
+    return failure("storage");
+  }
+  const keys = new Set<string>();
+  try {
+    for (let index = 0; index < length; index += 1) {
+      const key = storage.key(index);
+      if (key?.startsWith(SESSION_STATE_PREFIX)) keys.add(key);
+    }
+  } catch {
+    return failure("storage");
+  }
+  return applyWrites(
+    storage,
+    [...keys].map((key) => ({ key, value: null })),
+  );
 }
diff --git a/frontend/next.config.ts b/frontend/next.config.ts
index 27e2eaf5..682ad1a7 100644
--- a/frontend/next.config.ts
+++ b/frontend/next.config.ts
@@ -23,6 +23,11 @@ const securityHeaders = [
 ];
 
 const nextConfig: NextConfig = {
+  images: {
+    loader: "custom",
+    loaderFile: "./lib/image-loader.ts",
+    formats: ["image/avif", "image/webp"],
+  },
   async headers() {
     return [
       {
diff --git a/frontend/test-utils/LoginForm.test.tsx b/frontend/test-utils/LoginForm.test.tsx
index 23393f2b..86daf37a 100644
--- a/frontend/test-utils/LoginForm.test.tsx
+++ b/frontend/test-utils/LoginForm.test.tsx
@@ -22,6 +22,7 @@ jest.mock("next/navigation", () => ({
 }));
 
 jest.mock("@/lib/api-client", () => ({
+  API_V1_BASE: "http://localhost:3001/api/v1",
   ApiError: class ApiError extends Error {
     status: number | null;
     messageKey: string;
@@ -52,8 +53,10 @@ describe("LoginForm", () => {
   beforeEach(() => {
     mockReplace.mockClear();
     mockApiRequest.mockReset();
-    mockStoreSession.mockClear();
+    mockStoreSession.mockReset();
+    mockStoreSession.mockReturnValue({ ok: true, value: undefined });
     mockSearchParams.delete("redirect");
+    mockSearchParams.delete("resume");
     mockSearchParams.delete("reset");
   });
 
@@ -62,11 +65,11 @@ describe("LoginForm", () => {
 
     expect(screen.getByRole("link", { name: "Continue with Google" })).toHaveAttribute(
       "href",
-      "http://localhost:3001/api/auth/google",
+      "http://localhost:3001/api/v1/auth/google",
     );
     expect(screen.getByRole("link", { name: "Continue with GitHub" })).toHaveAttribute(
       "href",
-      "http://localhost:3001/api/auth/github",
+      "http://localhost:3001/api/v1/auth/github",
     );
   });
 
@@ -93,10 +96,17 @@ describe("LoginForm", () => {
 
     await waitFor(() => expect(mockApiRequest).toHaveBeenCalledTimes(1));
     expect(mockApiRequest).toHaveBeenCalledWith(
-      "http://localhost:3001/api/auth/login",
-      expect.objectContaining({ method: "POST", credentials: "include" }),
+      "http://localhost:3001/api/v1/auth/login",
+      expect.objectContaining({
+        method: "POST",
+        credentials: "include",
+        anonymous: true,
+      }),
+    );
+    expect(mockStoreSession).toHaveBeenCalledWith(
+      { access_token: "access-token" },
+      undefined,
     );
-    expect(mockStoreSession).toHaveBeenCalledWith({ access_token: "access-token" });
     expect(mockReplace).toHaveBeenCalledWith("/dashboard");
   });
 
@@ -118,6 +128,46 @@ describe("LoginForm", () => {
     await waitFor(() => expect(mockReplace).toHaveBeenCalledWith("/dashboard"));
   });
 
+  it("passes a resume token through the session commit", async () => {
+    mockSearchParams.set("resume", "resume-1");
+    mockApiRequest.mockResolvedValue({ access_token: "access-token" });
+    renderForm();
+
+    fireEvent.change(screen.getByLabelText("Email address"), {
+      target: { value: "person@example.com" },
+    });
+    fireEvent.change(screen.getByLabelText("Password"), {
+      target: { value: "correct-password" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Sign in" }));
+
+    await waitFor(() => expect(mockReplace).toHaveBeenCalledWith("/dashboard"));
+    expect(mockStoreSession).toHaveBeenCalledWith(
+      { access_token: "access-token" },
+      "resume-1",
+    );
+  });
+
+  it("does not redirect when session-state persistence fails", async () => {
+    mockApiRequest.mockResolvedValue({ access_token: "access-token" });
+    mockStoreSession.mockReturnValue({
+      ok: false,
+      error: { code: "storage" },
+    });
+    renderForm();
+
+    fireEvent.change(screen.getByLabelText("Email address"), {
+      target: { value: "person@example.com" },
+    });
+    fireEvent.change(screen.getByLabelText("Password"), {
+      target: { value: "correct-password" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Sign in" }));
+
+    expect(await screen.findByText("An unexpected error occurred.")).toBeInTheDocument();
+    expect(mockReplace).not.toHaveBeenCalled();
+  });
+
   it("renders an inline error when credentials are rejected", async () => {
     mockApiRequest.mockRejectedValue(
       new ApiError({ status: 401, messageKey: "errors.status.unauthorized" }),
diff --git a/frontend/test-utils/api-client.test.ts b/frontend/test-utils/api-client.test.ts
index a490dd64..c9690122 100644
--- a/frontend/test-utils/api-client.test.ts
+++ b/frontend/test-utils/api-client.test.ts
@@ -1,4 +1,12 @@
-import { ApiError, clearSession, request } from "@/lib/api-client";
+import {
+  ApiError,
+  clearSession,
+  invalidateRefresh,
+  refreshSession,
+  request,
+  RefreshInvalidatedError,
+} from "@/lib/api-client";
+import { preserveSessionState } from "@/lib/session-state-preserver";
 
 const API_BASE = "http://localhost:3001";
 
@@ -28,6 +36,21 @@ function createLocalStorageMock() {
 
 let lsMock: ReturnType<typeof createLocalStorageMock>;
 
+let sessionStore: Record<string, string>;
+const sessionStorageMock = {
+  getItem: jest.fn((key: string) => sessionStore[key] ?? null),
+  setItem: jest.fn((key: string, value: string) => {
+    sessionStore[key] = value;
+  }),
+  removeItem: jest.fn((key: string) => {
+    delete sessionStore[key];
+  }),
+  get length() {
+    return Object.keys(sessionStore).length;
+  },
+  key: jest.fn((index: number) => Object.keys(sessionStore)[index] ?? null),
+};
+
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
 function setTokens(access: string, refresh?: string) {
@@ -40,6 +63,14 @@ function clearTokens() {
   lsMock.removeItem("refresh-token");
 }
 
+function makeToken(subject: string): string {
+  const payload = btoa(JSON.stringify({ sub: subject }))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `header.${payload}.signature`;
+}
+
 /** Build a mock Response-like object */
 function mockResponse(
   body: unknown,
@@ -95,11 +126,21 @@ beforeEach(() => {
   }
 
   clearTokens();
+  sessionStore = {};
+  Object.defineProperty(window, "sessionStorage", {
+    value: sessionStorageMock,
+    writable: true,
+    configurable: true,
+  });
+  sessionStorageMock.getItem.mockClear();
+  sessionStorageMock.setItem.mockClear();
+  sessionStorageMock.removeItem.mockClear();
+  sessionStorageMock.key.mockClear();
 
   mockFetch = jest.fn();
   globalThis.fetch = mockFetch;
 
-  // Prevent actual navigation on redirect
+  invalidateRefresh();
   locationHref = "";
   Object.defineProperty(window, "location", {
     value: {
@@ -233,6 +274,29 @@ describe("request()", () => {
 
   // ── 401 → refresh failure → clear session + redirect ───────────────────
 
+  it("clears the session when a refreshed request is still unauthorized", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ message: "Unauthorized" }, { status: 401 }),
+    );
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ access_token: "new-jwt-token" }),
+    );
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ message: "Unauthorized" }, { status: 401 }),
+    );
+
+    setTokens("expired-jwt", "valid-refresh-token");
+    await expect(request("/api/secret")).rejects.toMatchObject({
+      name: "ApiError",
+      status: 401,
+      kind: "authRequired",
+    });
+
+    expect(lsMock.getItem("auth-token")).toBeNull();
+    expect(lsMock.getItem("refresh-token")).toBeNull();
+    expect(locationHref).toContain("/login?redirect=");
+  });
+
   it("clears session and redirects to /login when refresh fails", async () => {
     // First call: 401
     mockFetch.mockResolvedValueOnce(
@@ -243,7 +307,11 @@ describe("request()", () => {
       mockResponse({ message: "Invalid" }, { status: 401 }),
     );
 
-    setTokens("expired-token", "bad-refresh-token");
+    setTokens(makeToken("user-a"), "bad-refresh-token");
+    const preserved = preserveSessionState("upload-form", { title: "Land deed" });
+    expect(preserved.ok).toBe(true);
+    if (!preserved.ok) return;
+    const resumeId = preserved.value;
 
     await expect(request("/api/secret")).rejects.toMatchObject({
       name: "ApiError",
@@ -253,7 +321,8 @@ describe("request()", () => {
 
     expect(lsMock.getItem("auth-token")).toBeNull();
     expect(lsMock.getItem("refresh-token")).toBeNull();
-    expect(locationHref).toBe("/login");
+    expect(locationHref).toContain("resume=");
+    expect(locationHref).toContain(encodeURIComponent(resumeId));
   });
 
   it("clears session and redirects when no refresh token exists", async () => {
@@ -292,6 +361,65 @@ describe("request()", () => {
   });
 });
 
+describe("refreshSession()", () => {
+  it("uses the canonical refresh endpoint and stores the new access token", async () => {
+    setTokens("expired-jwt", "valid-refresh-token");
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ access_token: "refreshed-jwt" }),
+    );
+
+    await refreshSession();
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      `${API_BASE}/api/v1/auth/refresh`,
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(lsMock.getItem("auth-token")).toBe("refreshed-jwt");
+  });
+
+  it("rejects asynchronously when no refresh token exists", async () => {
+    setTokens("access-token");
+    const pending = refreshSession();
+
+    expect(pending).toBeInstanceOf(Promise);
+    await expect(pending).rejects.toThrow("No refresh token available");
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("deduplicates concurrent refreshes", async () => {
+    let resolveRefresh!: (value: Response) => void;
+    const response = new Promise<Response>((resolve) => {
+      resolveRefresh = resolve;
+    });
+    mockFetch.mockReturnValue(response);
+    setTokens("expired-jwt", "valid-refresh-token");
+
+    const first = refreshSession();
+    const second = refreshSession();
+    resolveRefresh(mockResponse({ access_token: "refreshed-jwt" }));
+
+    await Promise.all([first, second]);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not restore a token after refresh invalidation", async () => {
+    let resolveRefresh!: (value: Response) => void;
+    const response = new Promise<Response>((resolve) => {
+      resolveRefresh = resolve;
+    });
+    mockFetch.mockReturnValue(response);
+    setTokens("old-access-jwt", "valid-refresh-token");
+
+    const pending = refreshSession();
+    await Promise.resolve();
+    invalidateRefresh();
+    resolveRefresh(mockResponse({ access_token: "stale-jwt" }));
+
+    await expect(pending).rejects.toBeInstanceOf(RefreshInvalidatedError);
+    expect(lsMock.getItem("auth-token")).toBe("old-access-jwt");
+  });
+});
+
 // ── clearSession ────────────────────────────────────────────────────────────
 
 describe("clearSession()", () => {
diff --git a/frontend/test-utils/mocks/handlers.ts b/frontend/test-utils/mocks/handlers.ts
index 5cde6786..b606b8f9 100644
--- a/frontend/test-utils/mocks/handlers.ts
+++ b/frontend/test-utils/mocks/handlers.ts
@@ -4,7 +4,7 @@ const API_BASE = "http://localhost:3001";
 
 export const handlers = [
   // Auth — login
-  http.post(`${API_BASE}/api/auth/login`, async ({ request }) => {
+  http.post(`${API_BASE}/api/v1/auth/login`, async ({ request }) => {
     const body = (await request.json()) as { email: string; password: string };
     if (body.email === "bad@example.com") {
       return HttpResponse.json(
@@ -16,7 +16,7 @@ export const handlers = [
   }),
 
   // Auth — verify
-  http.get(`${API_BASE}/api/auth/verify`, ({ request }) => {
+  http.get(`${API_BASE}/api/v1/auth/verify`, ({ request }) => {
     const auth = request.headers.get("Authorization");
     if (!auth || !auth.startsWith("Bearer ")) {
       return HttpResponse.json({ message: "Unauthorized" }, { status: 401 });