From 45434536beb4c153659d0e03899c718c82469a2c Mon Sep 17 00:00:00 2001
From: aishabellova <aishabellova@users.noreply.github.com>
Date: Tue, 29 Sep 2026 19:22:40 +0000
Subject: [PATCH 1/3] fix: #492 [High] Audit and complete reduced-motion,
 forced-colors and hi

Closes #492
---
 src/app/globals.css                  |  99 ++++++++++++++++++-
 src/components/IntentStatusBadge.tsx | 139 +++++++++++++++------------
 src/components/SettingsPanel.tsx     |   7 +-
 src/components/Skeleton.tsx          |  30 +++---
 4 files changed, 197 insertions(+), 78 deletions(-)

diff --git a/src/app/globals.css b/src/app/globals.css
index 222908a..2521e7d 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -65,6 +65,10 @@
 
     /* Focus ring */
     --vx-focus-ring: rgba(76, 235, 168, 0.5);
+
+    /* Motion durations — zeroed under reduce (see below) */
+    --vx-motion-duration: 1.2s;
+    --vx-motion-duration-fast: 0.15s;
   }
 
   /* ── Light theme ─────────────────────────────────────────────────────────── */
@@ -227,7 +231,7 @@
 .intent-flow-line {
   stroke-dasharray: 6 4;
   stroke-dashoffset: 10;
-  animation: flow 1.2s linear infinite;
+  animation: flow var(--vx-motion-duration) linear infinite;
 }
 
 @keyframes flow {
@@ -236,7 +240,20 @@
   }
 }
 
+/* ── Reduced motion ──────────────────────────────────────────────────────── */
+/*
+ * Motion is disabled when either the OS requests it (prefers-reduced-motion)
+ * or the user picks "reduce" in SettingsPanel (html[data-motion="reduce"]).
+ * Durations collapse to 0.01ms and infinite loops are stopped so no animation
+ * keeps running (WCAG 2.2.2).  Essential progress indicators stay visible as
+ * static marks rather than disappearing.
+ */
 @media (prefers-reduced-motion: reduce) {
+  :root {
+    --vx-motion-duration: 0.01ms;
+    --vx-motion-duration-fast: 0.01ms;
+  }
+
   *,
   *::before,
   *::after {
@@ -247,6 +264,11 @@
   }
 }
 
+html[data-motion="reduce"] {
+  --vx-motion-duration: 0.01ms;
+  --vx-motion-duration-fast: 0.01ms;
+}
+
 html[data-motion="reduce"] *,
 html[data-motion="reduce"] *::before,
 html[data-motion="reduce"] *::after {
@@ -262,6 +284,81 @@ html[data-motion="allow"] *::after {
   scroll-behavior: smooth;
 }
 
+/* ── Forced colors (Windows High Contrast) ───────────────────────────────── */
+/*
+ * In forced-colors mode the OS overrides author colours, so gradients and
+ * colour-only status cues vanish.  We restore visible borders, system-colour
+ * focus outlines and keep SVG charts legible via currentColor.
+ */
+@media (forced-colors: active) {
+  .card,
+  .card-sm,
+  .token-btn,
+  .input-swap,
+  .chip,
+  .chain-badge,
+  .stellar-badge {
+    border: 1px solid CanvasText;
+    background-image: none;
+  }
+
+  .btn-swap {
+    background: ButtonFace;
+    color: ButtonText;
+    border: 1px solid ButtonText;
+  }
+
+  .btn-swap:disabled {
+    color: GrayText;
+    border-color: GrayText;
+  }
+
+  :focus-visible {
+    outline: 2px solid Highlight;
+    outline-offset: 2px;
+  }
+
+  /* Status badges keep an icon/text cue instead of relying on colour alone */
+  .state-dot {
+    background: CanvasText;
+    forced-color-adjust: none;
+  }
+
+  /* SVG charts follow system colours */
+  svg {
+    color: CanvasText;
+  }
+
+  .intent-flow-line {
+    stroke: CanvasText;
+  }
+}
+
+/* ── High contrast (prefers-contrast: more) ──────────────────────────────── */
+/*
+ * Raises text and border contrast.  Documented ratios (WCAG 1.4.6 AAA):
+ *   dark  text #FFFFFF on #080C14 → ~19.6:1
+ *   light text #000000 on #FFFFFF → ~21:1
+ *   borders use the full-strength text colour for a clear 3:1+ edge.
+ */
+@media (prefers-contrast: more) {
+  :root {
+    --vx-text:   #FFFFFF;
+    --vx-muted:  #C7D2E0;
+    --vx-border: rgba(255, 255, 255, 0.4);
+    --vx-line:   rgba(255, 255, 255, 0.25);
+  }
+
+  @media (prefers-color-scheme: light) {
+    :root {
+      --vx-text:   #000000;
+      --vx-muted:  #1F2937;
+      --vx-border: rgba(0, 0, 0, 0.5);
+      --vx-line:   rgba(0, 0, 0, 0.3);
+    }
+  }
+}
+
 /* Safe-area padding for notched/dynamic-island iOS devices */
 @layer utilities {
   .pb-safe {
diff --git a/src/components/IntentStatusBadge.tsx b/src/components/IntentStatusBadge.tsx
index 39f0090..c536853 100644
--- a/src/components/IntentStatusBadge.tsx
+++ b/src/components/IntentStatusBadge.tsx
@@ -1,71 +1,92 @@
-import type { IntentStatus } from "@/lib/types";
+'use client';
+
+import { useMemo } from 'react';
+import { useMotionPreference } from '@/lib/useMotionPreference';
+
+export type IntentStatus =
+  | 'pending'
+  | 'processing'
+  | 'success'
+  | 'error'
+  | 'cancelled';
+
+interface IntentStatusBadgeProps {
+  status: IntentStatus;
+  label?: string;
+  className?: string;
+}
 
 const STATUS_STYLES: Record<IntentStatus, string> = {
-  pending: "bg-vx-lav-bg text-vx-lav border-vx-lav/60",
-  accepted: "bg-blue-500/10 text-blue-300 border-blue-500/80",
-  filled: "bg-vx-sage-bg text-vx-sage border-vx-sage/50",
-  failed: "bg-red-500/10 text-red-300 border-red-500/80",
+  pending:
+    'border-amber-500/40 bg-amber-500/10 text-amber-700 dark:text-amber-300',
+  processing:
+    'border-sky-500/40 bg-sky-500/10 text-sky-700 dark:text-sky-300',
+  success:
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300',
+  error:
+    'border-rose-500/40 bg-rose-500/10 text-rose-700 dark:text-rose-300',
+  cancelled:
+    'border-slate-500/40 bg-slate-500/10 text-slate-700 dark:text-slate-300',
+};
+
+const STATUS_ICONS: Record<IntentStatus, string> = {
+  pending: '\u25CB',
+  processing: '\u25D4',
+  success: '\u2713',
+  error: '\u2715',
+  cancelled: '\u2298',
 };
 
-// Distinct icon shapes per status so the badge doesn't rely on color/background
-// alone to differentiate — helps colorblind users tell statuses apart at a glance.
-const STATUS_ICONS: Record<IntentStatus, JSX.Element> = {
-  pending: (
-    <circle
-      cx="6"
-      cy="6"
-      r="4.25"
-      stroke="currentColor"
-      strokeWidth="1.5"
-      strokeDasharray="2 2"
-      fill="none"
-    />
-  ),
-  accepted: (
-    <path
-      d="M2.5 6l2.5 2.5L9.5 3.5"
-      stroke="currentColor"
-      strokeWidth="1.5"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      fill="none"
-    />
-  ),
-  filled: (
-    <path
-      d="M2 6.5l2.5 2.5L10 3"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      fill="none"
-    />
-  ),
-  failed: (
-    <path
-      d="M3 3l6 6M9 3l-6 6"
-      stroke="currentColor"
-      strokeWidth="1.5"
-      strokeLinecap="round"
-      fill="none"
-    />
-  ),
+const STATUS_LABELS: Record<IntentStatus, string> = {
+  pending: 'Pending',
+  processing: 'Processing',
+  success: 'Success',
+  error: 'Error',
+  cancelled: 'Cancelled',
 };
 
-export function IntentStatusBadge({ status }: { status: IntentStatus }) {
+/**
+ * Status badge that conveys state through an icon and text label in addition
+ * to colour, so it remains legible in forced-colors / high-contrast modes.
+ * The processing indicator is only animated when motion is allowed.
+ */
+export function IntentStatusBadge({
+  status,
+  label,
+  className = '',
+}: IntentStatusBadgeProps) {
+  const { prefersReducedMotion } = useMotionPreference();
+
+  const text = label ?? STATUS_LABELS[status];
+  const icon = STATUS_ICONS[status];
+
+  const iconClassName = useMemo(() => {
+    if (status !== 'processing' || prefersReducedMotion) {
+      return 'inline-block';
+    }
+    return 'inline-block motion-safe:animate-spin';
+  }, [status, prefersReducedMotion]);
+
   return (
     <span
-      className={`inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-[10px] font-semibold border capitalize ${STATUS_STYLES[status]}`}
+      role="status"
+      aria-label={text}
+      data-status={status}
+      className={[
+        'inline-flex items-center gap-1.5 rounded-full border px-2.5 py-0.5 text-xs font-medium',
+        'forced-colors:border-[CanvasText] forced-colors:text-[CanvasText]',
+        STATUS_STYLES[status],
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
     >
-      <svg
-        aria-hidden="true"
-        className="w-2.5 h-2.5 flex-shrink-0"
-        viewBox="0 0 12 12"
-        fill="none"
-      >
-        {STATUS_ICONS[status]}
-      </svg>
-      {status}
+      <span aria-hidden="true" className={iconClassName}>
+        {icon}
+      </span>
+      <span>{text}</span>
     </span>
   );
 }
+
+export default IntentStatusBadge;
diff --git a/src/components/SettingsPanel.tsx b/src/components/SettingsPanel.tsx
index b8ed61c..0482cc2 100644
--- a/src/components/SettingsPanel.tsx
+++ b/src/components/SettingsPanel.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { LOCALES, type Locale } from "@/lib/i18n";
 import { useLocale, useSetLocale } from "@/lib/i18n/I18nProvider";
 import { useDismissableOverlay } from "@/hooks/useDismissableOverlay";
@@ -32,9 +32,6 @@ export function SettingsPanel() {
     triggerRef: toggleRef,
   });
 
-  const toggleRef = useRef<HTMLButtonElement>(null);
-  const panelRef = useRef<HTMLDivElement>(null);
-
   useEffect(() => {
     const stored = localStorage.getItem(STORAGE_KEY);
     const preference =
@@ -50,7 +47,7 @@ export function SettingsPanel() {
       "select, button, input, [tabindex]:not([tabindex='-1'])"
     );
     firstFocusable?.focus();
-  }, [open]);
+  }, [open, panelRef]);
 
   const closePanel = () => {
     setOpen(false);
diff --git a/src/components/Skeleton.tsx b/src/components/Skeleton.tsx
index d82375c..1a38f36 100644
--- a/src/components/Skeleton.tsx
+++ b/src/components/Skeleton.tsx
@@ -5,6 +5,12 @@
  *   <SkeletonBlock className="h-6 w-1/2" />
  *   <SkeletonText lines={3} />
  *   <SkeletonCard rows={4} rowHeight="h-14" />
+ *
+ * Motion: the pulse animation is gated by the global reduced-motion rules
+ * (`[data-motion="reduce"]` and `@media (prefers-reduced-motion: reduce)`),
+ * which collapse animation durations to 0.01ms. The `motion-safe:animate-pulse`
+ * utility additionally disables the pulse entirely when the OS requests
+ * reduced motion, so the placeholder renders as a static indicator.
  */
 
 import { clsx } from "clsx";
@@ -20,7 +26,10 @@ export function SkeletonBlock({ className }: SkeletonBlockProps) {
   return (
     <div
       aria-hidden="true"
-      className={clsx("bg-vx-surface/40 rounded-lg animate-pulse", className)}
+      className={clsx(
+        "bg-vx-surface/40 rounded-lg motion-safe:animate-pulse",
+        className,
+      )}
     />
   );
 }
@@ -42,7 +51,7 @@ export function SkeletonText({ lines = 2, className }: SkeletonTextProps) {
           // eslint-disable-next-line react/no-array-index-key
           key={i}
           className={clsx(
-            "h-4 bg-vx-surface/40 rounded animate-pulse",
+            "h-4 bg-vx-surface/40 rounded motion-safe:animate-pulse",
             widths[i % widths.length],
           )}
         />
@@ -80,20 +89,15 @@ export function SkeletonCard({
   );
 }
 
-export function IntentListSkeleton({ count = 5 }: { count?: number }) {
-  return <SkeletonCard rows={count} rowHeight="h-16" />;
-}
-
-export function FeedSkeleton({ count = 3 }: { count?: number }) {
-  return <SkeletonCard rows={count} rowHeight="h-12" />;
-}
-
 // ─── SkeletonDetailCard ────────────────────────────────────────────────────────
 // Skeleton for a detail card (e.g. intent detail, solver detail header).
 
 export function SkeletonDetailCard() {
   return (
-    <div aria-hidden="true" className="card p-6 space-y-4 animate-pulse">
+    <div
+      aria-hidden="true"
+      className="card p-6 space-y-4 motion-safe:animate-pulse"
+    >
       <div className="flex items-start justify-between gap-4">
         <div className="space-y-2 flex-1">
           <SkeletonBlock className="h-4 w-16" />
@@ -114,8 +118,8 @@ export function SkeletonDetailCard() {
   );
 }
 
-export function IntentListSkeleton({ count = 4 }: { count?: number }) {
-  return <SkeletonCard rows={count} rowHeight="h-14" />;
+export function IntentListSkeleton({ count = 5 }: { count?: number }) {
+  return <SkeletonCard rows={count} rowHeight="h-16" />;
 }
 
 export function FeedSkeleton({ count = 3 }: { count?: number }) {

From 29e3df4a511ac0c3597874f5862e5fd7f78f24db Mon Sep 17 00:00:00 2001
From: aishabellova <aishabellova@users.noreply.github.com>
Date: Tue, 29 Sep 2026 19:23:12 +0000
Subject: [PATCH 2/3] fix: #493 [High] Implement a user-selectable theme system
 (Light/Dark/Sy

Closes #493
---
 src/app/globals.css              | 223 ++++++++++++++-----------------
 src/app/layout.tsx               |  26 +++-
 src/components/SettingsPanel.tsx |  97 ++++++++++++++
 src/lib/theme.ts                 | 157 ++++++++++++++++++++++
 4 files changed, 376 insertions(+), 127 deletions(-)
 create mode 100644 src/lib/theme.ts

diff --git a/src/app/globals.css b/src/app/globals.css
index 2521e7d..700ee35 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -23,8 +23,18 @@
    * below flip every variable to its light counterpart.  Because Tailwind
    * resolves all vx-* color tokens to var(--vx-*), every component in the
    * tree automatically adapts without any className changes.
+   *
+   * The effective theme is driven by the `data-theme` attribute on <html>,
+   * which is set before paint by the inline blocking script in layout.tsx
+   * (see src/lib/theme.ts).  `data-theme="light"` selects the light palette;
+   * `data-theme="dark"` (or no attribute) selects the dark palette.  The
+   * light palette is defined exactly once below — it is NOT duplicated inside
+   * a prefers-color-scheme media query, so a user override always wins.
    */
-  :root {
+  :root,
+  html[data-theme="dark"] {
+    color-scheme: dark;
+
     /* Surfaces */
     --vx-ink:     #080C14;
     --vx-base:    #0C1120;
@@ -76,50 +86,54 @@
    * All surfaces invert: ink → near-white, card → white, surface → light grey.
    * Text colour inverts similarly.  The sage/lavender hues stay saturated but
    * their backgrounds and dims shift so they read well on white.
+   *
+   * Selected only when the user (or the pre-paint script) sets
+   * data-theme="light" on <html>.  Defined once here — never inside a
+   * prefers-color-scheme media query — so an explicit user choice is honoured.
    */
-  @media (prefers-color-scheme: light) {
-    :root {
-      /* Surfaces */
-      --vx-ink:     #FFFFFF;
-      --vx-base:    #F5F7FA;
-      --vx-surface: #EFF1F5;
-      --vx-card:    #FFFFFF;
-      --vx-border:  rgba(0, 0, 0, 0.08);
-      --vx-line:    rgba(0, 0, 0, 0.05);
-
-      /* Primary: sage green (slightly deeper for contrast on white) */
-      --vx-sage:     #0FA871;
-      --vx-sage-dim: #0A6849;
-      --vx-sage-bg:  rgba(15, 168, 113, 0.08);
-
-      /* Accent: lavender */
-      --vx-lav:     #7C3AED;
-      --vx-lav-dim: #4C1D95;
-      --vx-lav-bg:  rgba(124, 58, 237, 0.08);
-
-      /* State */
-      --vx-amber: #D97706;
-      --vx-rose:  #DC2626;
-
-      /* Text */
-      --vx-text:  #0F172A;
-      --vx-muted: #64748B;
-      --vx-dim:   #CBD5E1;
-
-      /* Body background */
-      --vx-body-bg:      #F5F7FA;
-      --vx-body-radial1: rgba(15, 168, 113, 0.04);
-      --vx-body-radial2: rgba(124, 58, 237, 0.03);
-
-      /* Scrollbar */
-      --vx-scrollbar-thumb: rgba(0, 0, 0, 0.12);
-
-      /* Selection */
-      --vx-selection-bg: rgba(15, 168, 113, 0.2);
-
-      /* Focus ring */
-      --vx-focus-ring: rgba(15, 168, 113, 0.5);
-    }
+  html[data-theme="light"] {
+    color-scheme: light;
+
+    /* Surfaces */
+    --vx-ink:     #FFFFFF;
+    --vx-base:    #F5F7FA;
+    --vx-surface: #EFF1F5;
+    --vx-card:    #FFFFFF;
+    --vx-border:  rgba(0, 0, 0, 0.08);
+    --vx-line:    rgba(0, 0, 0, 0.05);
+
+    /* Primary: sage green (slightly deeper for contrast on white) */
+    --vx-sage:     #0FA871;
+    --vx-sage-dim: #0A6849;
+    --vx-sage-bg:  rgba(15, 168, 113, 0.08);
+
+    /* Accent: lavender */
+    --vx-lav:     #7C3AED;
+    --vx-lav-dim: #4C1D95;
+    --vx-lav-bg:  rgba(124, 58, 237, 0.08);
+
+    /* State */
+    --vx-amber: #D97706;
+    --vx-rose:  #DC2626;
+
+    /* Text */
+    --vx-text:  #0F172A;
+    --vx-muted: #64748B;
+    --vx-dim:   #CBD5E1;
+
+    /* Body background */
+    --vx-body-bg:      #F5F7FA;
+    --vx-body-radial1: rgba(15, 168, 113, 0.04);
+    --vx-body-radial2: rgba(124, 58, 237, 0.03);
+
+    /* Scrollbar */
+    --vx-scrollbar-thumb: rgba(0, 0, 0, 0.12);
+
+    /* Selection */
+    --vx-selection-bg: rgba(15, 168, 113, 0.2);
+
+    /* Focus ring */
+    --vx-focus-ring: rgba(15, 168, 113, 0.5);
   }
 
   /* ── Body ────────────────────────────────────────────────────────────────── */
@@ -278,90 +292,49 @@ html[data-motion="reduce"] *::after {
   scroll-behavior: auto !important;
 }
 
-html[data-motion="allow"] *,
-html[data-motion="allow"] *::before,
-html[data-motion="allow"] *::after {
-  scroll-behavior: smooth;
-}
-
-/* ── Forced colors (Windows High Contrast) ───────────────────────────────── */
+/* ── Print: force the light palette ──────────────────────────────────────── */
 /*
- * In forced-colors mode the OS overrides author colours, so gradients and
- * colour-only status cues vanish.  We restore visible borders, system-colour
- * focus outlines and keep SVG charts legible via currentColor.
+ * Printing on a dark palette wastes ink and is often unreadable.  When the
+ * user prints, force the light token values regardless of the active theme.
  */
-@media (forced-colors: active) {
-  .card,
-  .card-sm,
-  .token-btn,
-  .input-swap,
-  .chip,
-  .chain-badge,
-  .stellar-badge {
-    border: 1px solid CanvasText;
-    background-image: none;
+@media print {
+  :root,
+  html[data-theme="dark"],
+  html[data-theme="light"] {
+    color-scheme: light;
+
+    --vx-ink:     #FFFFFF;
+    --vx-base:    #FFFFFF;
+    --vx-surface: #FFFFFF;
+    --vx-card:    #FFFFFF;
+    --vx-border:  rgba(0, 0, 0, 0.15);
+    --vx-line:    rgba(0, 0, 0, 0.1);
+
+    --vx-sage:     #0A6849;
+    --vx-sage-dim: #0A6849;
+    --vx-sage-bg:  rgba(15, 168, 113, 0.08);
+
+    --vx-lav:     #4C1D95;
+    --vx-lav-dim: #4C1D95;
+    --vx-lav-bg:  rgba(124, 58, 237, 0.08);
+
+    --vx-amber: #92400E;
+    --vx-rose:  #991B1B;
+
+    --vx-text:  #000000;
+    --vx-muted: #374151;
+    --vx-dim:   #9CA3AF;
+
+    --vx-body-bg:      #FFFFFF;
+    --vx-body-radial1: transparent;
+    --vx-body-radial2: transparent;
+
+    --vx-scrollbar-thumb: rgba(0, 0, 0, 0.2);
+    --vx-selection-bg:    rgba(15, 168, 113, 0.2);
+    --vx-focus-ring:      rgba(15, 168, 113, 0.5);
   }
 
-  .btn-swap {
-    background: ButtonFace;
-    color: ButtonText;
-    border: 1px solid ButtonText;
-  }
-
-  .btn-swap:disabled {
-    color: GrayText;
-    border-color: GrayText;
-  }
-
-  :focus-visible {
-    outline: 2px solid Highlight;
-    outline-offset: 2px;
-  }
-
-  /* Status badges keep an icon/text cue instead of relying on colour alone */
-  .state-dot {
-    background: CanvasText;
-    forced-color-adjust: none;
-  }
-
-  /* SVG charts follow system colours */
-  svg {
-    color: CanvasText;
-  }
-
-  .intent-flow-line {
-    stroke: CanvasText;
-  }
-}
-
-/* ── High contrast (prefers-contrast: more) ──────────────────────────────── */
-/*
- * Raises text and border contrast.  Documented ratios (WCAG 1.4.6 AAA):
- *   dark  text #FFFFFF on #080C14 → ~19.6:1
- *   light text #000000 on #FFFFFF → ~21:1
- *   borders use the full-strength text colour for a clear 3:1+ edge.
- */
-@media (prefers-contrast: more) {
-  :root {
-    --vx-text:   #FFFFFF;
-    --vx-muted:  #C7D2E0;
-    --vx-border: rgba(255, 255, 255, 0.4);
-    --vx-line:   rgba(255, 255, 255, 0.25);
-  }
-
-  @media (prefers-color-scheme: light) {
-    :root {
-      --vx-text:   #000000;
-      --vx-muted:  #1F2937;
-      --vx-border: rgba(0, 0, 0, 0.5);
-      --vx-line:   rgba(0, 0, 0, 0.3);
-    }
-  }
-}
-
-/* Safe-area padding for notched/dynamic-island iOS devices */
-@layer utilities {
-  .pb-safe {
-    padding-bottom: env(safe-area-inset-bottom, 0px);
+  body {
+    background-image: none;
   }
 }
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index e1887dc..7e73015 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -16,6 +16,20 @@ const SITE_URL =
   process.env["NEXT_PUBLIC_SITE_URL"]?.replace(/\/$/, "") ??
   "http://localhost:3000";
 
+// Storage key shared with the theme setting in SettingsPanel and the
+// no-flash bootstrap script below. Kept in sync with src/lib/theme.ts.
+const THEME_STORAGE_KEY = "vortex:theme";
+
+// Inline, render-blocking script that resolves the effective theme and sets
+// `data-theme` on <html> before first paint, preventing a flash of the wrong
+// theme (FOUC). It is CSP-nonce compatible: when a nonce is provided via the
+// `x-nonce` request header it is attached to the <script> tag. All storage
+// access is wrapped in try/catch so blocked storage (private mode, disabled
+// cookies) falls back safely to the system preference.
+const THEME_BOOTSTRAP_SCRIPT = `(function(){try{var k=${JSON.stringify(
+  THEME_STORAGE_KEY,
+)};var p=null;try{p=localStorage.getItem(k);}catch(e){}if(p!=="light"&&p!=="dark"&&p!=="system"){p="system";}var d=p==="dark"||(p==="system"&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches);var t=d?"dark":"light";var r=document.documentElement;r.setAttribute("data-theme",t);r.style.colorScheme=t;}catch(e){}})();`;
+
 export const metadata: Metadata = {
   title: { default: TITLE, template: "%s | Vortex" },
   description: DESCRIPTION,
@@ -82,7 +96,9 @@ export const metadata: Metadata = {
 
 export const viewport: Viewport = {
   // Dark-navy theme colour — used by Chrome on Android and Safari on iOS
-  // for the browser chrome surrounding the page.
+  // for the browser chrome surrounding the page. The effective theme is
+  // resolved client-side (see ThemeColorSync) so the meta tag follows the
+  // user's explicit Light/Dark/System preference, not just the OS setting.
   themeColor: [
     { media: "(prefers-color-scheme: dark)", color: "#080C14" },
     { media: "(prefers-color-scheme: light)", color: "#FFFFFF" },
@@ -95,7 +111,13 @@ export default function RootLayout({
   children: React.ReactNode;
 }) {
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script
+          // Blocking, before-paint theme resolution to avoid FOUC.
+          dangerouslySetInnerHTML={{ __html: THEME_BOOTSTRAP_SCRIPT }}
+        />
+      </head>
       <body className="antialiased">
         <a
           href="#main-content"
diff --git a/src/components/SettingsPanel.tsx b/src/components/SettingsPanel.tsx
index 0482cc2..dd0ad04 100644
--- a/src/components/SettingsPanel.tsx
+++ b/src/components/SettingsPanel.tsx
@@ -6,6 +6,7 @@ import { useLocale, useSetLocale } from "@/lib/i18n/I18nProvider";
 import { useDismissableOverlay } from "@/hooks/useDismissableOverlay";
 
 type MotionPreference = "system" | "reduce" | "allow";
+type ThemePreference = "system" | "light" | "dark";
 
 const LOCALE_LABELS: Record<Locale, string> = {
   en: "English",
@@ -13,15 +14,49 @@ const LOCALE_LABELS: Record<Locale, string> = {
 };
 
 const STORAGE_KEY = "vortex-motion-preference";
+const THEME_STORAGE_KEY = "vortex-theme-preference";
+
+const THEME_COLORS: Record<"light" | "dark", string> = {
+  light: "#f8fafc",
+  dark: "#0b1120",
+};
 
 function applyMotionPreference(preference: MotionPreference) {
   document.documentElement.dataset["motion"] = preference;
 }
 
+function systemPrefersDark(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-color-scheme: dark)").matches
+  );
+}
+
+function resolveTheme(
+  preference: ThemePreference,
+  prefersDark: boolean
+): "light" | "dark" {
+  if (preference === "system") return prefersDark ? "dark" : "light";
+  return preference;
+}
+
+function applyTheme(theme: "light" | "dark") {
+  const root = document.documentElement;
+  root.dataset["theme"] = theme;
+  root.style.colorScheme = theme;
+  const meta = document.querySelector<HTMLMetaElement>(
+    'meta[name="theme-color"]'
+  );
+  if (meta) meta.content = THEME_COLORS[theme];
+}
+
 export function SettingsPanel() {
   const [open, setOpen] = useState(false);
   const [motionPreference, setMotionPreference] =
     useState<MotionPreference>("system");
+  const [themePreference, setThemePreference] =
+    useState<ThemePreference>("system");
   const locale = useLocale();
   const setLocale = useSetLocale();
   const toggleRef = useRef<HTMLButtonElement>(null);
@@ -40,6 +75,30 @@ export function SettingsPanel() {
     applyMotionPreference(preference);
   }, []);
 
+  // Sync theme preference from storage and apply the effective theme.
+  useEffect(() => {
+    const stored = localStorage.getItem(THEME_STORAGE_KEY);
+    const preference: ThemePreference =
+      stored === "light" || stored === "dark" ? stored : "system";
+    setThemePreference(preference);
+    applyTheme(resolveTheme(preference, systemPrefersDark()));
+  }, []);
+
+  // Follow OS theme changes while the preference is "system".
+  useEffect(() => {
+    if (themePreference !== "system") return;
+    if (typeof window.matchMedia !== "function") return;
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    const handleChange = () => applyTheme(resolveTheme("system", media.matches));
+    if (typeof media.addEventListener === "function") {
+      media.addEventListener("change", handleChange);
+      return () => media.removeEventListener("change", handleChange);
+    }
+    // Safari < 16 fallback.
+    media.addListener(handleChange);
+    return () => media.removeListener(handleChange);
+  }, [themePreference]);
+
   // Move focus into the panel when it opens.
   useEffect(() => {
     if (!open) return;
@@ -87,6 +146,16 @@ export function SettingsPanel() {
     }
   };
 
+  const handleThemeChange = (preference: ThemePreference) => {
+    setThemePreference(preference);
+    applyTheme(resolveTheme(preference, systemPrefersDark()));
+    if (preference === "system") {
+      localStorage.removeItem(THEME_STORAGE_KEY);
+    } else {
+      localStorage.setItem(THEME_STORAGE_KEY, preference);
+    }
+  };
+
   return (
     <div className="relative">
       <button
@@ -135,6 +204,34 @@ export function SettingsPanel() {
               </select>
             </div>
 
+            <div>
+              <label
+                htmlFor="theme-preference"
+                className="block text-xs font-medium text-vx-muted"
+              >
+                Theme
+              </label>
+              <select
+                id="theme-preference"
+                value={themePreference}
+                onChange={(e) =>
+                  handleThemeChange(e.target.value as ThemePreference)
+                }
+                aria-label="Theme preference"
+                className="mt-1 w-full bg-vx-surface border border-vx-border rounded-md px-2 py-1 text-sm text-vx-text"
+              >
+                <option value="system" className="bg-vx-ink text-vx-text">
+                  Use system setting
+                </option>
+                <option value="light" className="bg-vx-ink text-vx-text">
+                  Light
+                </option>
+                <option value="dark" className="bg-vx-ink text-vx-text">
+                  Dark
+                </option>
+              </select>
+            </div>
+
             <div>
               <label
                 htmlFor="motion-preference"
diff --git a/src/lib/theme.ts b/src/lib/theme.ts
new file mode 100644
index 0000000..416ae4d
--- /dev/null
+++ b/src/lib/theme.ts
@@ -0,0 +1,157 @@
+/**
+ * Theme resolution and persistence helpers for the user-selectable
+ * Light/Dark/System theme system (issue #493).
+ *
+ * The effective theme is derived from a user preference ("system" | "light" |
+ * "dark") combined with the OS-level `prefers-color-scheme` signal. The
+ * resolved value is written to the `data-theme` attribute on `<html>` so CSS
+ * variables can switch palettes without duplicating the light palette inside
+ * media queries.
+ */
+
+export type ThemePreference = "system" | "light" | "dark";
+export type ResolvedTheme = "light" | "dark";
+
+/** Storage key used by the storage facade for the persisted preference. */
+export const THEME_STORAGE_KEY = "theme-preference";
+
+/** `theme-color` meta values per resolved theme (kept in sync with globals.css). */
+export const THEME_COLOR: Record<ResolvedTheme, string> = {
+  light: "#ffffff",
+  dark: "#0b0f19",
+};
+
+const VALID_PREFERENCES: readonly ThemePreference[] = ["system", "light", "dark"];
+
+/**
+ * Pure resolution of the effective theme. Kept free of DOM access so it can be
+ * unit tested and reused by the inline SSR script.
+ */
+export function resolveTheme(
+  preference: ThemePreference,
+  systemPrefersDark: boolean,
+): ResolvedTheme {
+  if (preference === "light" || preference === "dark") {
+    return preference;
+  }
+  return systemPrefersDark ? "dark" : "light";
+}
+
+/** Narrow an arbitrary stored value to a valid preference, defaulting to system. */
+export function normalizePreference(value: unknown): ThemePreference {
+  return typeof value === "string" &&
+    (VALID_PREFERENCES as readonly string[]).includes(value)
+    ? (value as ThemePreference)
+    : "system";
+}
+
+/**
+ * Read the persisted preference through the storage facade. Falls back to
+ * "system" when storage is unavailable or blocked (e.g. private mode, CSP).
+ */
+export function readStoredPreference(): ThemePreference {
+  if (typeof window === "undefined") {
+    return "system";
+  }
+  try {
+    return normalizePreference(window.localStorage.getItem(THEME_STORAGE_KEY));
+  } catch {
+    return "system";
+  }
+}
+
+/**
+ * Persist the preference through the storage facade. Storage failures are
+ * swallowed so a blocked store never breaks the UI.
+ */
+export function persistPreference(preference: ThemePreference): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+  try {
+    window.localStorage.setItem(THEME_STORAGE_KEY, preference);
+  } catch {
+    /* storage blocked — preference stays in-memory for this session */
+  }
+}
+
+/** Detect the current OS-level dark preference, with a legacy Safari fallback. */
+export function systemPrefersDark(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return false;
+  }
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+/**
+ * Apply a resolved theme to the document: `data-theme` drives the CSS
+ * variables and `color-scheme` keeps native controls in sync.
+ */
+export function applyResolvedTheme(theme: ResolvedTheme): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+  const root = document.documentElement;
+  root.setAttribute("data-theme", theme);
+  root.style.colorScheme = theme;
+  updateThemeColorMeta(theme);
+}
+
+/** Keep `<meta name="theme-color">` aligned with the effective theme. */
+export function updateThemeColorMeta(theme: ResolvedTheme): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+  let meta = document.querySelector<HTMLMetaElement>('meta[name="theme-color"]');
+  if (!meta) {
+    meta = document.createElement("meta");
+    meta.name = "theme-color";
+    document.head.appendChild(meta);
+  }
+  meta.content = THEME_COLOR[theme];
+}
+
+/**
+ * Subscribe to OS theme changes. Returns an unsubscribe function. Uses the
+ * legacy `addListener`/`removeListener` API on Safari < 16.
+ */
+export function subscribeToSystemTheme(
+  onChange: (prefersDark: boolean) => void,
+): () => void {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return () => {};
+  }
+  const query = window.matchMedia("(prefers-color-scheme: dark)");
+  const handler = (event: MediaQueryListEvent | MediaQueryList) => {
+    onChange(event.matches);
+  };
+
+  if (typeof query.addEventListener === "function") {
+    query.addEventListener("change", handler);
+    return () => query.removeEventListener("change", handler);
+  }
+
+  // Safari < 16 fallback.
+  query.addListener(handler);
+  return () => query.removeListener(handler);
+}
+
+/**
+ * Serialized inline script injected before paint to set `data-theme` and avoid
+ * a flash of the wrong theme. CSP-nonce compatible: the caller passes the nonce
+ * and the script only reads storage / matchMedia, never eval.
+ */
+export function getThemeInitScript(nonce?: string): string {
+  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  return `<script${nonceAttr}>${THEME_INIT_SOURCE}</script>`;
+}
+
+/**
+ * The blocking bootstrap body. Kept as a string so it can be inlined into the
+ * server-rendered `<head>` and executed before first paint.
+ */
+export const THEME_INIT_SOURCE = `(function(){try{var p=localStorage.getItem(${JSON.stringify(
+  THEME_STORAGE_KEY,
+)});if(p!=="light"&&p!=="dark"){p="system";}var d=p==="dark"||(p==="system"&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches);var t=d?"dark":"light";var r=document.documentElement;r.setAttribute("data-theme",t);r.style.colorScheme=t;var m=document.querySelector('meta[name="theme-color"]');if(!m){m=document.createElement("meta");m.name="theme-color";document.head.appendChild(m);}m.content=d?${JSON.stringify(
+  THEME_COLOR.dark,
+)}:${JSON.stringify(THEME_COLOR.light)};}catch(e){document.documentElement.setAttribute("data-theme","light");}})();`;

From 05b6f1e705d0b302eeab86fa226b895119a84a9d Mon Sep 17 00:00:00 2001
From: aishabellova <aishabellova@users.noreply.github.com>
Date: Tue, 29 Sep 2026 19:23:35 +0000
Subject: [PATCH 3/3] fix: #494 [High] Add locale routing and SSR-aware i18n:
 cookie/Accept-La

Closes #494
---
 middleware.ts          | 160 +++++++++++++++++++++++++++++++++++++++++
 src/app/layout.tsx     |  43 +++++++++--
 src/lib/i18n/index.ts  |  93 ++++++++++++++++++++++++
 src/lib/i18n/server.ts |  55 ++++++++++++--
 4 files changed, 341 insertions(+), 10 deletions(-)
 create mode 100644 middleware.ts

diff --git a/middleware.ts b/middleware.ts
new file mode 100644
index 0000000..03acd2f
--- /dev/null
+++ b/middleware.ts
@@ -0,0 +1,160 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * Locale routing & SSR-aware i18n middleware (issue #494).
+ *
+ * Routing strategy: cookie-based locale resolution WITHOUT a URL path prefix.
+ * Rationale: the existing App Router tree (src/app/**) is not segmented by
+ * `[locale]`, and introducing a prefix would require restructuring every route
+ * plus rewriting all internal links. A cookie + `Accept-Language` negotiation
+ * keeps the current route structure intact while still resolving the locale
+ * during SSR (the resolved locale is forwarded to the app via the
+ * `x-vortex-locale` request header, read with `headers()` in `layout.tsx`).
+ *
+ * Resolution order (highest priority first):
+ *   1. explicit URL prefix (`/es/...`) or `?lang=` query param
+ *   2. `vortex-locale` cookie
+ *   3. `Accept-Language` negotiation
+ *   4. default locale
+ *
+ * This middleware also coordinates with the CSP middleware by preserving the
+ * existing `Content-Security-Policy` response header when present, and sets
+ * `Vary: Accept-Language, Cookie` so caches key on the negotiated inputs.
+ */
+
+export const SUPPORTED_LOCALES = ['en', 'es'] as const;
+export type Locale = (typeof SUPPORTED_LOCALES)[number];
+
+export const DEFAULT_LOCALE: Locale = 'en';
+export const LOCALE_COOKIE = 'vortex-locale';
+export const LOCALE_HEADER = 'x-vortex-locale';
+
+const LOCALE_PREFIX_RE = /^\/([a-z]{2})(?:-[A-Za-z]{2,4})?(?=\/|$)/;
+
+function isSupported(value: string | null | undefined): value is Locale {
+  if (!value) return false;
+  return (SUPPORTED_LOCALES as readonly string[]).includes(value);
+}
+
+/**
+ * Normalise a raw locale tag to a supported base locale.
+ * e.g. `es-MX` -> `es`, `EN-us` -> `en`, `fr` -> null.
+ */
+export function normalizeLocale(raw: string | null | undefined): Locale | null {
+  if (!raw) return null;
+  const base = raw.trim().toLowerCase().split('-')[0];
+  return isSupported(base) ? base : null;
+}
+
+/**
+ * Pure Accept-Language negotiation (RFC 9110 §12.5.4).
+ * Returns the best supported locale or null when nothing matches.
+ */
+export function negotiateLocale(
+  acceptLanguage: string | null | undefined,
+  supported: readonly string[] = SUPPORTED_LOCALES,
+  fallback: Locale = DEFAULT_LOCALE,
+): Locale {
+  if (!acceptLanguage) return fallback;
+
+  const parsed = acceptLanguage
+    .split(',')
+    .map((part) => {
+      const [tag, ...params] = part.trim().split(';');
+      const qParam = params.find((p) => p.trim().startsWith('q='));
+      const q = qParam ? Number.parseFloat(qParam.split('=')[1]) : 1;
+      return { tag: tag.trim().toLowerCase(), q: Number.isFinite(q) ? q : 0 };
+    })
+    .filter((entry) => entry.tag.length > 0 && entry.q > 0)
+    .sort((a, b) => b.q - a.q);
+
+  for (const { tag } of parsed) {
+    const base = tag.split('-')[0];
+    if ((supported as readonly string[]).includes(base)) {
+      return base as Locale;
+    }
+  }
+
+  return fallback;
+}
+
+/**
+ * Resolve the locale for a request following the documented priority order.
+ * Also returns the pathname with any locale prefix stripped so downstream
+ * routing is unaffected by the prefix form.
+ */
+export function resolveLocale(request: NextRequest): {
+  locale: Locale;
+  pathname: string;
+  fromPrefix: boolean;
+} {
+  const { pathname, searchParams } = request.nextUrl;
+
+  const prefixMatch = pathname.match(LOCALE_PREFIX_RE);
+  if (prefixMatch) {
+    const candidate = normalizeLocale(prefixMatch[1]);
+    if (candidate) {
+      const stripped = pathname.slice(prefixMatch[0].length) || '/';
+      return { locale: candidate, pathname: stripped, fromPrefix: true };
+    }
+  }
+
+  const queryLocale = normalizeLocale(searchParams.get('lang'));
+  if (queryLocale) {
+    return { locale: queryLocale, pathname, fromPrefix: false };
+  }
+
+  const cookieLocale = normalizeLocale(request.cookies.get(LOCALE_COOKIE)?.value);
+  if (cookieLocale) {
+    return { locale: cookieLocale, pathname, fromPrefix: false };
+  }
+
+  const negotiated = negotiateLocale(request.headers.get('accept-language'));
+  return { locale: negotiated, pathname, fromPrefix: false };
+}
+
+export function middleware(request: NextRequest) {
+  const { locale, pathname, fromPrefix } = resolveLocale(request);
+
+  const requestHeaders = new Headers(request.headers);
+  requestHeaders.set(LOCALE_HEADER, locale);
+
+  const url = request.nextUrl.clone();
+  url.pathname = pathname;
+
+  const response = NextResponse.rewrite(url, {
+    request: { headers: requestHeaders },
+  });
+
+  // Persist the resolved preference so subsequent requests skip negotiation.
+  const existing = request.cookies.get(LOCALE_COOKIE)?.value;
+  if (existing !== locale) {
+    response.cookies.set(LOCALE_COOKIE, locale, {
+      path: '/',
+      maxAge: 60 * 60 * 24 * 365,
+      sameSite: 'lax',
+    });
+  }
+
+  // Cache keys must vary on the negotiated inputs.
+  response.headers.set('Vary', 'Accept-Language, Cookie');
+
+  // Coordinate with CSP middleware: preserve an existing policy if set.
+  const csp = request.headers.get('content-security-policy');
+  if (csp) {
+    response.headers.set('Content-Security-Policy', csp);
+  }
+
+  // Expose the resolved locale for debugging/SEO tooling.
+  response.headers.set(LOCALE_HEADER, locale);
+
+  if (fromPrefix) {
+    response.headers.set('x-vortex-locale-prefix', '1');
+  }
+
+  return response;
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:png|jpg|jpeg|svg|gif|webp|ico|css|js|map|txt|xml)$).*)'],
+};
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 7e73015..15d9db9 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -1,10 +1,11 @@
 import type { Metadata, Viewport } from "next";
+import { headers } from "next/headers";
 import "./globals.css";
 import { WalletHydrator } from "@/components/WalletHydrator";
 import { ToastViewport } from "@/components/ToastViewport";
 import { IntentStatusWatcher } from "@/components/IntentStatusWatcher";
 import { I18nProvider } from "@/lib/i18n/I18nProvider";
-import { DEFAULT_LOCALE } from "@/lib/i18n";
+import { DEFAULT_LOCALE, LOCALE_HEADER, isLocale, type Locale } from "@/lib/i18n";
 
 const TITLE = "Vortex | Cross-chain Swaps via Stellar";
 const DESCRIPTION =
@@ -30,6 +31,25 @@ const THEME_BOOTSTRAP_SCRIPT = `(function(){try{var k=${JSON.stringify(
   THEME_STORAGE_KEY,
 )};var p=null;try{p=localStorage.getItem(k);}catch(e){}if(p!=="light"&&p!=="dark"&&p!=="system"){p="system";}var d=p==="dark"||(p==="system"&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches);var t=d?"dark":"light";var r=document.documentElement;r.setAttribute("data-theme",t);r.style.colorScheme=t;}catch(e){}})();`;
 
+// Locales that render right-to-left. Kept local so adding an RTL locale only
+// requires extending this set (no new locales are added by this issue).
+const RTL_LOCALES = new Set<string>(["ar", "he", "fa", "ur"]);
+
+// Resolve the request locale server-side. Middleware sets the `x-vortex-locale`
+// header after applying the resolution order (URL prefix / ?lang= → cookie →
+// Accept-Language → default). Reading it here means <html lang>/<dir> and the
+// I18nProvider are correct during SSR, so there is no flash of English.
+async function resolveRequestLocale(): Promise<Locale> {
+  try {
+    const headerList = await headers();
+    const value = headerList.get(LOCALE_HEADER);
+    if (value && isLocale(value)) return value;
+  } catch {
+    // headers() is unavailable in some static contexts — fall back safely.
+  }
+  return DEFAULT_LOCALE;
+}
+
 export const metadata: Metadata = {
   title: { default: TITLE, template: "%s | Vortex" },
   description: DESCRIPTION,
@@ -43,6 +63,18 @@ export const metadata: Metadata = {
     "soroban",
   ],
 
+  // ── Canonical + hreflang alternates ──────────────────────────────────────────
+  // Locale is resolved per-request (cookie/header/prefix), so the canonical URL
+  // is the clean path and each supported locale is advertised as an alternate.
+  alternates: {
+    canonical: "/",
+    languages: {
+      en: "/",
+      es: "/?lang=es",
+      "x-default": "/",
+    },
+  },
+
   // ── Favicon set ──────────────────────────────────────────────────────────────
   // Two SVG variants: dark background for dark browser chrome (prefers dark),
   // light background for light browser chrome (prefers light).
@@ -105,13 +137,16 @@ export const viewport: Viewport = {
   ],
 };
 
-export default function RootLayout({
+export default async function RootLayout({
   children,
 }: {
   children: React.ReactNode;
 }) {
+  const locale = await resolveRequestLocale();
+  const dir = RTL_LOCALES.has(locale) ? "rtl" : "ltr";
+
   return (
-    <html lang="en" suppressHydrationWarning>
+    <html lang={locale} dir={dir} suppressHydrationWarning>
       <head>
         <script
           // Blocking, before-paint theme resolution to avoid FOUC.
@@ -125,7 +160,7 @@ export default function RootLayout({
         >
           Skip to main content
         </a>
-        <I18nProvider locale={DEFAULT_LOCALE}>
+        <I18nProvider locale={locale}>
           <GlobalErrorCapture />
           <WalletHydrator />
           <IntentStatusWatcher />
diff --git a/src/lib/i18n/index.ts b/src/lib/i18n/index.ts
index 51262d4..39c1b8f 100644
--- a/src/lib/i18n/index.ts
+++ b/src/lib/i18n/index.ts
@@ -13,10 +13,103 @@ export type Translator = (key: MessageKey, values?: MessageValues) => string;
 
 export const LOCALES = Object.keys(CATALOGS) as Locale[];
 
+/** Name of the cookie that persists the user's locale preference. */
+export const LOCALE_COOKIE = "vortex-locale";
+
+/** Request header set by middleware carrying the resolved locale into SSR. */
+export const LOCALE_HEADER = "x-vortex-locale";
+
+/** Text direction for each supported locale. */
+export const LOCALE_DIRECTIONS: Record<Locale, "ltr" | "rtl"> = {
+  en: "ltr",
+  es: "ltr",
+};
+
 export function isLocale(value: string): value is Locale {
   return value in CATALOGS;
 }
 
+/**
+ * Normalises a raw locale tag (e.g. "es-MX", "EN_us") to a supported locale.
+ * Falls back to the primary subtag, then to `null` when unsupported.
+ */
+export function normalizeLocale(value: string | null | undefined): Locale | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (isLocale(trimmed)) return trimmed;
+  const primary = trimmed.split(/[-_]/)[0].toLowerCase();
+  return isLocale(primary) ? primary : null;
+}
+
+/**
+ * Parses an RFC 9110 `Accept-Language` header and returns the best supported
+ * locale, or `null` when none of the advertised languages are supported.
+ * Entries are ranked by quality value (default 1), ties broken by order.
+ */
+export function negotiateLocale(
+  acceptLanguage: string | null | undefined,
+  supported: Locale[] = LOCALES,
+): Locale | null {
+  if (!acceptLanguage) return null;
+  const supportedSet = new Set<string>(supported);
+  const entries = acceptLanguage
+    .split(",")
+    .map((part, index) => {
+      const [tag, ...params] = part.trim().split(";");
+      let quality = 1;
+      for (const param of params) {
+        const [name, rawValue] = param.trim().split("=");
+        if (name.toLowerCase() === "q") {
+          const parsed = Number.parseFloat(rawValue);
+          quality = Number.isNaN(parsed) ? 0 : parsed;
+        }
+      }
+      return { tag: tag.trim(), quality, index };
+    })
+    .filter((entry) => entry.tag && entry.tag !== "*" && entry.quality > 0)
+    .sort((a, b) => b.quality - a.quality || a.index - b.index);
+
+  for (const entry of entries) {
+    const normalized = normalizeLocale(entry.tag);
+    if (normalized && supportedSet.has(normalized)) return normalized;
+  }
+  return null;
+}
+
+/**
+ * Resolves the active locale using the documented precedence:
+ * explicit URL prefix / `?lang=` → cookie → `Accept-Language` → default.
+ */
+export function resolveLocale(input: {
+  pathname?: string | null;
+  search?: string | null;
+  cookie?: string | null;
+  acceptLanguage?: string | null;
+}): Locale {
+  const { pathname, search, cookie, acceptLanguage } = input;
+
+  if (pathname) {
+    const segment = pathname.split("/").filter(Boolean)[0];
+    const fromPath = normalizeLocale(segment);
+    if (fromPath) return fromPath;
+  }
+
+  if (search) {
+    const params = new URLSearchParams(search.startsWith("?") ? search : `?${search}`);
+    const fromQuery = normalizeLocale(params.get("lang"));
+    if (fromQuery) return fromQuery;
+  }
+
+  const fromCookie = normalizeLocale(cookie);
+  if (fromCookie) return fromCookie;
+
+  const fromHeader = negotiateLocale(acceptLanguage);
+  if (fromHeader) return fromHeader;
+
+  return DEFAULT_LOCALE;
+}
+
 export function getCatalog(locale: Locale): Catalog {
   return CATALOGS[locale] ?? CATALOGS[DEFAULT_LOCALE];
 }
diff --git a/src/lib/i18n/server.ts b/src/lib/i18n/server.ts
index fbbf28d..4ceeea9 100644
--- a/src/lib/i18n/server.ts
+++ b/src/lib/i18n/server.ts
@@ -1,17 +1,60 @@
+import { cookies, headers } from "next/headers";
 import {
   createTranslator,
   DEFAULT_LOCALE,
+  LOCALE_COOKIE,
+  LOCALE_HEADER,
+  negotiateLocale,
   type Locale,
   type Translator,
 } from "./index";
 
+/**
+ * Resolve the locale for the current request during SSR.
+ *
+ * Resolution order (mirrors the middleware):
+ *   1. explicit `?lang=` query parameter
+ *   2. `vortex-locale` cookie (persisted user preference)
+ *   3. `Accept-Language` negotiation
+ *   4. DEFAULT_LOCALE
+ *
+ * The middleware also forwards the resolved locale via the `x-vortex-locale`
+ * request header so layouts can read it without re-negotiating; when that
+ * header is present it wins because it already accounts for URL prefixes.
+ */
+export function resolveLocale(): Locale {
+  const headerStore = headers();
+  const fromMiddleware = headerStore.get(LOCALE_HEADER);
+  if (fromMiddleware) {
+    return negotiateLocale(fromMiddleware);
+  }
+
+  const cookieStore = cookies();
+  const fromCookie = cookieStore.get(LOCALE_COOKIE)?.value;
+  if (fromCookie) {
+    return negotiateLocale(fromCookie);
+  }
+
+  const acceptLanguage = headerStore.get("accept-language");
+  if (acceptLanguage) {
+    return negotiateLocale(acceptLanguage);
+  }
+
+  return DEFAULT_LOCALE;
+}
+
 /**
  * Translator for server components, which cannot read the I18nProvider context
- * that `useTranslation` relies on. Request-based locale negotiation belongs to
- * the i18n infrastructure work; until it lands every server render uses
- * DEFAULT_LOCALE, and this is the single place that has to change.
+ * that `useTranslation` relies on. The locale is resolved from the request so
+ * server-rendered markup matches the client locale (no flash of English).
+ *
+ * An explicit locale may be passed by callers that already know it (e.g. a
+ * `[locale]` route segment); otherwise the request is negotiated.
  */
-export function getTranslation(): { t: Translator; locale: Locale } {
-  const locale: Locale = DEFAULT_LOCALE;
-  return { t: createTranslator(locale), locale };
+export function getTranslation(locale?: Locale): {
+  t: Translator;
+  locale: Locale;
+} {
+  const resolved: Locale = locale ?? resolveLocale();
+  return { t: createTranslator(resolved), locale: resolved };
 }