refactor: fix whitespace indents in copy

![image.png](/attachments/182d430f-7b29-48f7-aad6-0aa3ed1708c4)

---------

Co-authored-by: me <ramvignesh-b@github.com>
Reviewed-on: #6

.env.e2e.example

@@ -2,8 +2,8 @@
 DB_NAME=piku_test_db
 DB_USER=test
 DB_PASSWORD=password123
-DB_HOST=localhost
-DB_PORT=5433
+DB_HOST=127.0.0.1
+DB_PORT=5443
 
 # SSL
 SSL_ENABLED=true
@@ -12,17 +12,17 @@ SSL_ENABLED=true
 DEBUG=True
 SECRET_KEY=django-insecure-initial-key
 BACKEND_DOMAIN=127.0.0.1
-BACKEND_PORT=8001
+BACKEND_PORT=8101
 
 # EMAIL
 EMAIL_HOST=127.0.0.1
 EMAIL_PORT=1026
-EMAIL_HOST_USER=test
-EMAIL_HOST_PASSWORD=password123
+EMAIL_HOST_USER=
+EMAIL_HOST_PASSWORD=
 FROM_EMAIL="Test <test@pi-ku.app>"
 EMAIL_API_PORT=8026
 
 # FRONTEND
 FRONTEND_PORT=5199
 FRONTEND_DOMAIN=127.0.0.1
-VITE_API_URL=https://127.0.0.1:8001
+VITE_API_URL=https://127.0.0.1:8101

.env.example

@@ -2,26 +2,33 @@
 DB_NAME=piku
 DB_USER=user
 DB_PASSWORD=password123
-DB_HOST=localhost
-DB_PORT=5432
+DB_HOST=127.0.0.1
+DB_PORT=5442
 
 # SSL
 SSL_ENABLED=true
+S3_ENABLED=false
 
 # DJANGO
 DEBUG=True
 SECRET_KEY=django-secret-key
 BACKEND_DOMAIN=127.0.0.1
-BACKEND_PORT=8000
+BACKEND_PORT=8100
+# S3
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_REGION_NAME=
+R2_ENDPOINT_URL=
+R2_PUBLIC_URL=
 
 # EMAIL
 EMAIL_HOST=127.0.0.1
 EMAIL_PORT=1025
-EMAIL_HOST_USER=test
-EMAIL_HOST_PASSWORD=password123
+EMAIL_HOST_USER=
+EMAIL_HOST_PASSWORD=
 FROM_EMAIL="Pi Ku <no-reply@test.com>"
 
 # FRONTEND
 FRONTEND_PORT=5173
 FRONTEND_DOMAIN=127.0.0.1
-VITE_API_URL=https://127.0.0.1:8000
+VITE_API_URL=https://127.0.0.1:8100

.github/workflows/ci.yml

@@ -19,11 +19,12 @@ jobs:
           mkcert -install
           mkcert -cert-file certs/localhost.pem -key-file certs/localhost-key.pem localhost 127.0.0.1 ::1
 
-      - name: Cache certificates
-        uses: actions/cache/save@v4
+      - name: Upload certificates
+        uses: christopherHX/gitea-upload-artifact@v4
         with:
-          path: certs
-          key: certs-${{ runner.os }}-${{ github.sha }}
+          name: ssl-certs
+          path: certs/
+          retention-days: 1
 
   frontend:
     name: Frontend CI
@@ -37,10 +38,10 @@ jobs:
       - uses: oven-sh/setup-bun@v2
 
       - name: Restore certificates
-        uses: actions/cache/restore@v4
+        uses: christopherHX/gitea-download-artifact@v4
         with:
-          path: certs
-          key: certs-${{ runner.os }}-${{ github.sha }}
+          name: ssl-certs
+          path: certs/
 
       - name: Install dependencies
         run: bun install --frozen-lockfile
@@ -61,15 +62,15 @@ jobs:
     runs-on: ubuntu-latest
     needs: setup-environment
     services:
-      postgres:
+      db:
         image: postgres:16-alpine
         env:
-          POSTGRES_DB: piku
-          POSTGRES_USER: user
+          POSTGRES_DB: piku__test
+          POSTGRES_USER: test
           POSTGRES_PASSWORD: password123
         ports:
-          - 5432:5432
-        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+          - 5442:5432
+        options: --tmpfs /var/lib/postgresql/data --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
     defaults:
       run:
         working-directory: ./backend
@@ -82,18 +83,28 @@ jobs:
           cache-dependency-glob: "backend/uv.lock"
 
       - name: Restore certificates
-        uses: actions/cache/restore@v4
+        uses: christopherHX/gitea-download-artifact@v4
         with:
-          path: certs
-          key: certs-${{ runner.os }}-${{ github.sha }}
+          name: ssl-certs
+          path: certs/
 
-      - name: Setup Environment
+      - name: Setup & Test
         run: |
           cp ../.env.example ../.env
           uv sync
 
-      - name: Lint & Test
-        run: |
+          export DB_NAME="piku__test"
+          export DB_USER="test"
+          export DB_PASSWORD="password123"
+
+          if [ "$GITEA_ACTIONS" = "true" ]; then
+            export DB_HOST="db"
+            export DB_PORT="5432"
+          else
+            export DB_HOST="127.0.0.1"
+            export DB_PORT="5442"
+          fi
+
           uv run ruff check
           uv run python manage.py test
 
@@ -101,23 +112,27 @@ jobs:
     name: E2E Tests
     runs-on: ubuntu-latest
     needs: setup-environment
+    # Skipping on Gitea pushes until cache server is configured
+    if: github.server_url == 'https://github.com' || github.event_name == 'pull_request'
     steps:
       - uses: actions/checkout@v4
 
       - name: Restore Certificates
-        uses: actions/cache/restore@v4
+        uses: christopherHX/gitea-download-artifact@v4
         with:
-          path: certs
-          key: certs-${{ runner.os }}-${{ github.sha }}
+          name: ssl-certs
+          path: certs/
 
       - name: Setup Tools
         uses: astral-sh/setup-uv@v5
 
       - uses: oven-sh/setup-bun@v2
 
-
       - name: Cache Playwright
         id: playwright-cache
+        # Disable cache when not using GitHub Actions because the runner spends ~3mins trying to upload the cache and failing
+        # TODO: setup cache server in Gitea
+        if: github.server_url == 'https://github.com'
         uses: actions/cache@v4
         with:
           path: ~/.cache/ms-playwright
@@ -140,8 +155,12 @@ jobs:
 
       - name: Upload Playwright Report
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: christopherHX/gitea-upload-artifact@v4
         with:
           name: playwright-report
           path: frontend/playwright-report/
           retention-days: 10
+
+      - name: Print Backend Logs on Failure
+        if: failure()
+        run: cat tmp/logs/backend.log || true

backend/.gitignore

@@ -10,3 +10,4 @@ __pycache__/
 
 docs/
 encrypted-images/
+logs/

backend/Dockerfile

@@ -10,9 +10,7 @@ RUN uv sync --frozen --no-dev
 
 COPY . .
 
-# Make the temp log dir writable since server is running rootless
-RUN mkdir -p /app/logs && chmod -R 777 /app/logs
-
 EXPOSE 8000
 
-CMD ["sh", "-c", "uv run manage.py migrate && uv run gunicorn --bind 0.0.0.0:8000 --access-logfile - --error-logfile - --capture-output --log-level debug config.wsgi:application"]
+# NOTE: Exporting env var 'UVICORN_MAIN=true' is required for the scheduler to run on app start.
+CMD ["sh", "-c", "uv run manage.py migrate && UVICORN_MAIN=true uv run gunicorn --bind 0.0.0.0:8000 --access-logfile - --error-logfile - --capture-output --log-level debug config.wsgi:application"]

backend/config/logging.py

@@ -1,5 +1,12 @@
+from pathlib import Path
+
 import structlog
 
+BASE_DIR = Path(__file__).resolve().parent.parent
+LOGS_DIR = BASE_DIR / "logs"
+
+LOGS_DIR.mkdir(parents=True, exist_ok=True)
+
 structlog.configure(
     processors=[
         structlog.contextvars.merge_contextvars,
@@ -41,22 +48,22 @@ LOGGING = {
         },
         "json_file": {
             "class": "logging.handlers.WatchedFileHandler",
-            "filename": "logs/json.log",
+            "filename": LOGS_DIR / "json.log",
             "formatter": "json_formatter",
         },
         "flat_line_file": {
             "class": "logging.handlers.WatchedFileHandler",
-            "filename": "logs/flat_line.log",
+            "filename": LOGS_DIR / "flat_line.log",
             "formatter": "key_value",
         },
         "letters_log": {
             "class": "logging.handlers.WatchedFileHandler",
-            "filename": "logs/letters.log",
+            "filename": LOGS_DIR / "letters.log",
             "formatter": "key_value",
         },
         "scheduler_log": {
             "class": "logging.handlers.WatchedFileHandler",
-            "filename": "logs/scheduler.log",
+            "filename": LOGS_DIR / "scheduler.log",
             "formatter": "key_value",
         },
     },
@@ -71,18 +78,18 @@ LOGGING = {
             "level": "DEBUG",
             "propagate": False,
         },
+        "letters.tasks": {
+            "handlers": ["console", "scheduler_log"],
+            "level": "INFO",
+            "propagate": False,
+        },
         "letters": {
             "handlers": ["console", "flat_line_file", "json_file", "letters_log"],
             "level": "INFO",
             "propagate": False,
         },
-        "scheduler": {
-            "handlers": ["console", "scheduler_log"],
-            "level": "INFO",
-            "propagate": False,
-        },
         "": {
-            "handlers": ["console", "flat_line_file", "json_file"],
+            "handlers": ["console"],
             "level": "INFO",
         },
     },

backend/config/settings.py

@@ -16,6 +16,8 @@ from pathlib import Path
 
 import environ
 
+from .logging import LOGGING
+
 # Build paths inside the project like this: BASE_DIR / 'subdir'.
 BASE_DIR = Path(__file__).resolve().parent.parent
 
@@ -25,8 +27,14 @@ env_file = os.environ.get("PIKU_ENV_FILE", os.path.join(BASE_DIR.parent, ".env")
 if os.path.exists(env_file):
     environ.Env.read_env(env_file, overwrite=False)
 
-ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", default=[])
-ALLOWED_HOSTS.append(env("FRONTEND_DOMAIN"))
+# Security Settings
+ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", default=["127.0.0.1"])
+ALLOWED_HOSTS.append(env("FRONTEND_DOMAIN", default="127.0.0.1"))
+ALLOWED_HOSTS.append(env("BACKEND_DOMAIN", default="127.0.0.1"))
+# NOTE: Set to forward https when using reverse proxy
+SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
+
+CSRF_TRUSTED_ORIGINS = env.list("CSRF_TRUSTED_ORIGINS", default=[])
 
 SSL_ENABLED = env.bool("SSL_ENABLED", default=False)
 URI_SCHEME = "https://" if SSL_ENABLED else "http://"
@@ -48,6 +56,7 @@ SECRET_KEY = env("SECRET_KEY")
 # SECURITY WARNING: don't run with debug turned on in production!
 DEBUG = env.bool("DEBUG", default=False)
 
+LOGGING = LOGGING
 
 # Application definition
 
@@ -78,6 +87,21 @@ MIDDLEWARE = [
     "django_structlog.middlewares.RequestMiddleware",
 ]
 
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [os.path.join(BASE_DIR, "templates")],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.debug",
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
+            ],
+        },
+    },
+]
 
 ROOT_URLCONF = "config.urls"
 
@@ -98,6 +122,7 @@ DATABASES = {
 }
 
 CORS_ALLOWED_ORIGINS = FRONTEND_URLS
+CSRF_TRUSTED_ORIGINS += FRONTEND_URLS
 CORS_ALLOW_CREDENTIALS = True
 
 AUTH_USER_MODEL = "users.User"
@@ -172,4 +197,31 @@ USE_TZ = True
 
 STATIC_URL = "static/"
 MEDIA_URL = "/media/"
+
+if env.bool("S3_ENABLED", default=False):
+    MEDIA_URL = f"{env('R2_PUBLIC_URL')}/media/"
+    # HACK: S3 auto pre-pends the url scheme forcefully and this prevents double https
+    R2_HOST = env("R2_PUBLIC_URL").replace("https://", "")
+    STORAGES = {
+        "default": {
+            "BACKEND": "storages.backends.s3.S3Storage",
+            "OPTIONS": {
+                "access_key": env("R2_ACCESS_KEY_ID"),
+                "secret_key": env("R2_SECRET_ACCESS_KEY"),
+                "bucket_name": env("R2_STORAGE_BUCKET_NAME"),
+                "region_name": env("R2_REGION_NAME"),
+                "endpoint_url": env("R2_ENDPOINT_URL"),
+                "location": "media",
+                "signature_version": "s3v4",
+                "file_overwrite": False,
+                "custom_domain": R2_HOST,
+                "querystring_auth": False,
+            },
+        },
+        "staticfiles": {
+            "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
+        },
+    }
+    DEFAULT_FILE_STORAGE = "storages.backends.s3.S3Storage"
+
 MEDIA_ROOT = BASE_DIR / "media"

backend/letters/apps.py

@@ -10,9 +10,13 @@ class LettersConfig(AppConfig):
         """
         Start the scheduler only when the server is starting.
         NOTE: If we don't check for RUN_MAIN, the scheduler triggers for all django operations (migration, test etc.)
+        NOTE++: For uvicorn, we make sure to set the env var `UVICORN_MAIN` to `true` in the docker command.
         """
-
-        if not (os.environ.get("RUN_MAIN") == "true" or os.environ.get("WERKZEUG_RUN_MAIN") == "true"):
+        if not (
+            os.environ.get("RUN_MAIN") == "true"
+            or os.environ.get("WERKZEUG_RUN_MAIN") == "true"
+            or os.environ.get("UVICORN_MAIN") == "true"
+        ):
             return
         from .tasks import start_scheduler
 

backend/letters/tasks.py

@@ -3,8 +3,10 @@ from datetime import UTC, datetime
 import structlog
 from apscheduler.schedulers.background import BackgroundScheduler
 from django.core.mail import send_mail
+from django.template.loader import render_to_string
 
 from config import settings
+from config.settings import FRONTEND_URLS
 from letters.models import Letter
 
 logger = structlog.get_logger(__name__)
@@ -23,9 +25,26 @@ def notify_unlocked_letter(letter):
     """
     author = letter.user.get_username()
     try:
-        send_mail(subject="", message="", from_email=settings.FROM_EMAIL, recipient_list=[author], fail_silently=False)
+        letter_link = f"{FRONTEND_URLS[0]}/read/{letter.public_id}"
+        subject = "A letter. Written for this exact moment."
+        context = {
+            "pen_name": letter.user.first_name,
+            "cta": {"title": "View what you wrote", "link": letter_link},
+            "footnote": True,
+        }
+        plaint_content = render_to_string("email/vault_unlock.txt", context=context)
+        html_content = render_to_string("email/vault_unlock.html", context=context)
+        send_mail(
+            subject=subject,
+            message=plaint_content,
+            from_email=settings.FROM_EMAIL,
+            recipient_list=[author],
+            fail_silently=False,
+            html_message=html_content,
+        )
         letter.notified_at = datetime.now(UTC)
         letter.save()
+        logger.info(f"Successfully notified {author} of unlocked letter")
     except Exception:
         logger.exception(f"Failed to notify {author} of unlocked letter")
 

backend/letters/tests.py

@@ -396,6 +396,7 @@ class LetterTaskTest(TestCase):
                 from_email=settings.FROM_EMAIL,
                 recipient_list=[self.user.email],
                 fail_silently=False,
+                html_message=ANY,
             )
             self.assertIsNotNone(letter_to_notify1.notified_at)
 

backend/pyproject.toml

@@ -6,11 +6,13 @@ readme = "README.md"
 requires-python = ">=3.14"
 dependencies = [
     "apscheduler>=3.11.2",
+    "boto3>=1.42.96",
     "django>=6.0.4",
     "django-apscheduler>=0.7.0",
     "django-cors-headers>=4.9.0",
     "django-environ>=0.13.0",
     "django-extensions>=4.1",
+    "django-storages>=1.14.6",
     "django-structlog>=10.0.0",
     "djangorestframework>=3.17.1",
     "djangorestframework-simplejwt>=5.5.1",

backend/templates/email/activation.html

@@ -0,0 +1,22 @@
+{% extends 'email/base.html' %}
+
+{% block content %}
+    <div style="padding: 15px; font-style: italic">
+        <p>{{ pen_name }},</p>
+        <p>
+            Your destination is one train away.
+        </p>
+        <p>I've been keeping a place for your words.<br/>
+            Come when you're ready.</p>
+    </div>
+{% endblock %}
+
+{% block footnote %}
+    This link expires in 24 hours.<br/>
+    I'm patient, but not endlessly so.
+{% endblock %}
+
+{% block footer %}
+    Didn't write to me? Then someone else did.<br/>
+    Ignore this. I'll forget you were ever here.
+{% endblock %}

backend/templates/email/activation.txt

@@ -0,0 +1,21 @@
+pi. ku.
+-------------------------------------------
+
+{{pen_name}},
+
+Your destination is one train away.
+
+I've been keeping a place for your words.
+Come when you're ready.
+
+{{ cta.title }} -> {{ cta.link }}
+
+-------------------------------------------
+
+This link expires in 24 hours.
+I'm patient, but not endlessly so.
+
+-------------------------------------------
+
+Didn't write to me? Then someone else did.
+Ignore this. I'll forget you were ever here.

backend/templates/email/base.html

@@ -0,0 +1,103 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <title>pi. ku.</title>
+</head>
+
+<body style="margin:0; padding:0; background-color:#1a1712;">
+
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"
+        style="background-color:#1a1712; font-family: 'Trebuchet MS', 'Lucida Grande', 'Lucida Sans Unicode', 'Lucida Sans', Tahoma, sans-serif;">
+        <tr>
+            <td align="center" style="padding: 48px 16px;">
+                <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"
+                    style="max-width:480px; width:100%;">
+
+                    {# Logo #}
+                    <tr>
+                        <td align="left" style="padding-bottom: 24px;">
+                            <img src="https://cdn.jsdelivr.net/gh/ramvignesh-b/cdn@main/pi-ku_logo.png" width="80"
+                                alt="Pi.Ku" style="display:block; border:0;">
+                        </td>
+                    </tr>
+
+                    {# Body #}
+                    <tr>
+                        <td style="font-family: 'Trebuchet MS', 'Lucida Sans Unicode', Arial, sans-serif;
+                                   font-size: 13px;
+                                   line-height: 1.9;
+                                   color: #cdccca;
+                                   font-style: italic;
+                                   padding-bottom: 24px;">
+                            {% block content %}
+                            {% endblock %}
+                        </td>
+                    </tr>
+
+                    {# CTA #}
+                    {% if cta %}
+                    <tr>
+                        <td align="left" style="padding-bottom: 24px;">
+                            <table role="presentation" cellpadding="0" cellspacing="0" border="0">
+                                <tr>
+                                    <td style="background-color: #301e19; border-radius: 3px;">
+                                        <a href='{{ cta.link }}' style="display: inline-block;
+                                  padding: 12px 24px;
+                                  font-family: 'Trebuchet MS', Arial, sans-serif;
+                                  font-size: 13px;
+                                  color: #f5e6c8;
+                                  text-decoration: none;
+                                  letter-spacing: 0.04em;
+                                  font-weight: bold;">
+                                            {{ cta.title }}
+                                        </a>
+                                    </td>
+                                </tr>
+                            </table>
+                        </td>
+                    </tr>
+                    {% endif %}
+
+                    {% if footnote %}
+                    <tr>
+                        <td style="font-family: Georgia, 'Times New Roman', Times, serif;
+                                   font-size: 12px;
+                                   font-style: italic;
+                                   color: #7a7974;
+                                   padding-bottom: 40px;
+                                   line-height: 1.8;">
+                            {% block footnote %}
+                            {% endblock %}
+                        </td>
+                    </tr>
+                    {% endif %}
+
+                    {# Footer #}
+                    <tr>
+                        <td style="border-top: 1px solid #2e2c29; padding-bottom: 24px; font-size: 0; line-height: 0;">
+                            &nbsp;</td>
+                    </tr>
+                    <tr>
+                        <td style="font-family: Georgia, 'Times New Roman', Times, serif;
+                                   font-size: 12px;
+                                   font-style: italic;
+                                   color: #5a5957;
+                                   line-height: 1.8;">
+                            {% block footer %}
+                            {% endblock %}
+                        </td>
+                    </tr>
+
+                </table>
+            </td>
+        </tr>
+    </table>
+
+</body>
+
+</html>

backend/templates/email/vault_unlock.html

@@ -0,0 +1,20 @@
+{% extends 'email/base.html' %}
+
+{% block content %}
+    <p>
+        Time has a way of making things clearer.<br/>
+        Or heavier. Sometimes both.
+    </p>
+    <p>
+        You had something to say at this exact moment.<br/>
+        I kept it exactly as you left it. <br/>
+        Not a word changed. Not a word read.
+    </p>
+{% endblock %}
+
+{% block footnote %}
+    <p>
+        You're ready now. Or maybe you're still not.<br/>
+        Open it anyway. You won't regret it.
+    </p>
+{% endblock %}

backend/templates/email/vault_unlock.txt

@@ -0,0 +1,17 @@
+pi. ku.
+-------------------------------------------
+
+{{pen_name}},
+
+Time has a way of making things clearer.
+Or heavier. Sometimes both.
+
+You had something to say at this exact moment.
+I kept it exactly as you left it.
+Not a word changed. Not a word read.
+
+{{ cta.title }} -> {{ cta.link }}
+
+-------------------------------------------
+You're ready now. Or maybe you're still not.
+Open it anyway. You won't regret it.

backend/users/utils.py

@@ -1,6 +1,7 @@
 from django.conf import settings
 from django.contrib.auth.tokens import default_token_generator
 from django.core.mail import send_mail
+from django.template.loader import render_to_string
 from django.utils.encoding import force_bytes
 from django.utils.http import urlsafe_base64_encode
 
@@ -9,16 +10,25 @@ def send_activation_email(user):
     token = default_token_generator.make_token(user)
     uid = urlsafe_base64_encode(force_bytes(user.public_id))
     activation_url = f"{settings.FRONTEND_URLS[0]}/activate/{uid}/{token}"
-    subject = "Activate Your Piku Account"
-    message = f"""Hi {user.full_name},
-
-        Welcome to Pi Ku.
-
-        Please click the link below to activate your account:
-        >> {activation_url}
-
-        If you did not create this account, please ignore this email."""
-    send_mail(subject, message, settings.FROM_EMAIL, [user.email], fail_silently=False)
+    subject = "Activate your pi. ku. account"
+    context = {
+        "pen_name": user.full_name,
+        "footnote": True,
+        "cta": {
+            "title": "Onboard",
+            "link": activation_url,
+        },
+    }
+    html_content = render_to_string("email/activation.html", context)
+    plain_content = render_to_string("email/activation.txt", context)
+    send_mail(
+        subject=subject,
+        message=plain_content,
+        from_email=settings.FROM_EMAIL,
+        recipient_list=[user.email],
+        fail_silently=False,
+        html_message=html_content,
+    )
     return True
 
 

backend/uv.lock

@@ -23,6 +23,34 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/5c/0a/a72d10ed65068e115044937873362e6e32fab1b7dce0046aeb224682c989/asgiref-3.11.1-py3-none-any.whl", hash = "sha256:e8667a091e69529631969fd45dc268fa79b99c92c5fcdda727757e52146ec133", size = 24345, upload-time = "2026-02-03T13:30:13.039Z" },
 ]
 
+[[package]]
+name = "boto3"
+version = "1.42.96"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "botocore" },
+    { name = "jmespath" },
+    { name = "s3transfer" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a6/2d/69fb3acd50bab83fb295c167d33c4b653faeb5fb0f42bfca4d9b69d6fb68/boto3-1.42.96.tar.gz", hash = "sha256:b38a9e4a3fbbee9017252576f1379780d0a5814768676c08df2f539d31fcdd68", size = 113203, upload-time = "2026-04-24T19:47:18.677Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2b/9d/b3f617d011c42eb804d993103b8fa9acdce153e181a3042f58bfe33d7cb4/boto3-1.42.96-py3-none-any.whl", hash = "sha256:2f4566da2c209a98bdbfc874d813ef231c84ad24e4f815e9bc91de5f63351a24", size = 140557, upload-time = "2026-04-24T19:47:15.824Z" },
+]
+
+[[package]]
+name = "botocore"
+version = "1.42.96"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "jmespath" },
+    { name = "python-dateutil" },
+    { name = "urllib3" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/61/77/2c333622a1d47cf5bf73cdcab0cb6c92addafbef2ec05f81b9f75687d9e5/botocore-1.42.96.tar.gz", hash = "sha256:75b3b841ffacaa944f645196655a21ca777591dd8911e732bfb6614545af0250", size = 15263344, upload-time = "2026-04-24T19:47:05.283Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/45/56/152c3a859ca1b9d77ed16deac3cf81682013677c68cf5715698781fc81bd/botocore-1.42.96-py3-none-any.whl", hash = "sha256:db2c3e2006628be6fde81a24124a6563c363d6982fb92728837cf174bad9d98a", size = 14945920, upload-time = "2026-04-24T19:47:00.323Z" },
+]
+
 [[package]]
 name = "cffi"
 version = "2.0.0"
@@ -182,6 +210,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/11/33/bf539925b102d68200da5b1d3eacb8aa5d5d9a065972e8b8724d0d53bb0d/django_ipware-7.0.1-py2.py3-none-any.whl", hash = "sha256:db16bbee920f661ae7f678e4270460c85850f03c6761a4eaeb489bdc91f64709", size = 6425, upload-time = "2024-04-19T20:02:47.469Z" },
 ]
 
+[[package]]
+name = "django-storages"
+version = "1.14.6"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "django" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ff/d6/2e50e378fff0408d558f36c4acffc090f9a641fd6e084af9e54d45307efa/django_storages-1.14.6.tar.gz", hash = "sha256:7a25ce8f4214f69ac9c7ce87e2603887f7ae99326c316bc8d2d75375e09341c9", size = 87587, upload-time = "2025-04-02T02:34:55.103Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1f/21/3cedee63417bc5553eed0c204be478071c9ab208e5e259e97287590194f1/django_storages-1.14.6-py3-none-any.whl", hash = "sha256:11b7b6200e1cb5ffcd9962bd3673a39c7d6a6109e8096f0e03d46fab3d3aabd9", size = 33095, upload-time = "2025-04-02T02:34:53.291Z" },
+]
+
 [[package]]
 name = "django-structlog"
 version = "10.0.0"
@@ -289,6 +329,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/43/c8/8aaf447698c4d59aa853fd318eed300b5c9e44459f242ab8ead6c9c09792/gunicorn-25.3.0-py3-none-any.whl", hash = "sha256:cacea387dab08cd6776501621c295a904fe8e3b7aae9a1a3cbb26f4e7ed54660", size = 208403, upload-time = "2026-03-27T00:00:27.386Z" },
 ]
 
+[[package]]
+name = "jmespath"
+version = "1.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d3/59/322338183ecda247fb5d1763a6cbe46eff7222eaeebafd9fa65d4bf5cb11/jmespath-1.1.0.tar.gz", hash = "sha256:472c87d80f36026ae83c6ddd0f1d05d4e510134ed462851fd5f754c8c3cbb88d", size = 27377, upload-time = "2026-01-22T16:35:26.279Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/14/2f/967ba146e6d58cf6a652da73885f52fc68001525b4197effc174321d70b4/jmespath-1.1.0-py3-none-any.whl", hash = "sha256:a5663118de4908c91729bea0acadca56526eb2698e83de10cd116ae0f4e97c64", size = 20419, upload-time = "2026-01-22T16:35:24.919Z" },
+]
+
 [[package]]
 name = "markdown-it-py"
 version = "4.0.0"
@@ -355,11 +404,13 @@ version = "0.1.0"
 source = { virtual = "." }
 dependencies = [
     { name = "apscheduler" },
+    { name = "boto3" },
     { name = "django" },
     { name = "django-apscheduler" },
     { name = "django-cors-headers" },
     { name = "django-environ" },
     { name = "django-extensions" },
+    { name = "django-storages" },
     { name = "django-structlog" },
     { name = "djangorestframework" },
     { name = "djangorestframework-simplejwt" },
@@ -377,11 +428,13 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "apscheduler", specifier = ">=3.11.2" },
+    { name = "boto3", specifier = ">=1.42.96" },
     { name = "django", specifier = ">=6.0.4" },
     { name = "django-apscheduler", specifier = ">=0.7.0" },
     { name = "django-cors-headers", specifier = ">=4.9.0" },
     { name = "django-environ", specifier = ">=0.13.0" },
     { name = "django-extensions", specifier = ">=4.1" },
+    { name = "django-storages", specifier = ">=1.14.6" },
     { name = "django-structlog", specifier = ">=10.0.0" },
     { name = "djangorestframework", specifier = ">=3.17.1" },
     { name = "djangorestframework-simplejwt", specifier = ">=5.5.1" },
@@ -513,6 +566,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/03/36/76704c4f312257d6dbaae3c959add2a622f63fcca9d864659ce6d8d97d3d/ruff-0.15.9-py3-none-win_arm64.whl", hash = "sha256:0694e601c028fd97dc5c6ee244675bc241aeefced7ef80cd9c6935a871078f53", size = 11005870, upload-time = "2026-04-02T18:17:15.773Z" },
 ]
 
+[[package]]
+name = "s3transfer"
+version = "0.16.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "botocore" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/46/29/af14f4ef3c11a50435308660e2cc68761c9a7742475e0585cd4396b91777/s3transfer-0.16.1.tar.gz", hash = "sha256:8e424355754b9ccb32467bdc568edf55be82692ef2002d934b1311dbb3b9e524", size = 154801, upload-time = "2026-04-22T20:36:06.475Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/03/19/90d7d4ed51932c022d53f1d02d564b62d10e272692a1f9b76425c1ad2a02/s3transfer-0.16.1-py3-none-any.whl", hash = "sha256:61bcd00ccb83b21a0fe7e91a553fff9729d46c83b4e0106e7c314a733891f7c2", size = 86825, upload-time = "2026-04-22T20:36:04.992Z" },
+]
+
 [[package]]
 name = "six"
 version = "1.17.0"
@@ -579,6 +644,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c2/14/e2a54fabd4f08cd7af1c07030603c3356b74da07f7cc056e600436edfa17/tzlocal-5.3.1-py3-none-any.whl", hash = "sha256:eb1a66c3ef5847adf7a834f1be0800581b683b5608e74f86ecbcef8ab91bb85d", size = 18026, upload-time = "2025-03-05T21:17:39.857Z" },
 ]
 
+[[package]]
+name = "urllib3"
+version = "2.6.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
+]
+
 [[package]]
 name = "werkzeug"
 version = "3.1.8"

frontend/Dockerfile

@@ -4,15 +4,8 @@ COPY package.json bun.lock* ./
 RUN bun install --frozen-lockfile
 COPY . .
 
-ARG BACKEND_DOMAIN
-ARG BACKEND_PORT
-ARG SSL_ENABLED
 ARG VITE_API_URL
 
-ENV BACKEND_DOMAIN=$BACKEND_DOMAIN
-ENV BACKEND_PORT=$BACKEND_PORT
-ENV SSL_ENABLED=$SSL_ENABLED
-
 ENV VITE_API_URL=$VITE_API_URL
 
 RUN bun run build:prod

frontend/bun.lock

@@ -8,8 +8,12 @@
         "@fontsource-variable/jost": "^5.2.8",
         "@fontsource-variable/playfair-display": "^5.2.8",
         "@fontsource-variable/playwrite-hr-lijeva": "^5.2.7",
+        "@fontsource/architects-daughter": "^5.2.7",
         "@fontsource/cutive-mono": "^5.2.8",
+        "@fontsource/kavivanar": "^5.2.8",
         "@fontsource/knewave": "^5.2.7",
+        "@fontsource/redacted-script": "^5.2.8",
+        "@fontsource/space-mono": "^5.2.9",
         "@hookform/resolvers": "^5.2.2",
         "@phosphor-icons/react": "^2.1.10",
         "@tailwindcss/vite": "^4.2.2",
@@ -17,6 +21,8 @@
         "daisyui": "^5.5.19",
         "fabric": "^7.2.0",
         "idb": "^8.0.3",
+        "lenis": "^1.3.23",
+        "motion": "^12.38.0",
         "react": "^19.2.4",
         "react-dom": "^19.2.4",
         "react-hook-form": "^7.72.1",
@@ -118,10 +124,18 @@
 
     "@fontsource-variable/playwrite-hr-lijeva": ["@fontsource-variable/playwrite-hr-lijeva@5.2.7", "", {}, "sha512-cQqbD8HHZDpiKdtgwUxgwAY76TC+GI9iZOxHSW0XkV/L8lA0X18z1wzR+J8yv9XZQYgLJ5WfzBGwzMSLnSLdPA=="],
 
+    "@fontsource/architects-daughter": ["@fontsource/architects-daughter@5.2.7", "", {}, "sha512-W7tHXduV9kRQZDTqcU4Rnc/GtSq9cYUHOnhvcRPjy87u5x/oRqKXPU2PghqbktTECOIh1N0qVZLt9rwqa+aWhg=="],
+
     "@fontsource/cutive-mono": ["@fontsource/cutive-mono@5.2.8", "", {}, "sha512-Y8PKAYfbpl9Empbb1HZBoirlj4W7RtU+G4EhvX27pHzO6RE1sO0I1ElZQH5DMCTS+MSJkMmQT33sJ0+Ji9U8eQ=="],
 
+    "@fontsource/kavivanar": ["@fontsource/kavivanar@5.2.8", "", {}, "sha512-wbr/9vQ2da9aabUngCpWLbbHM08XZK3nkLDuQ0eX/BhdVvoJx0MSPzaKJ0WIiKpVHy3fUL8ewOqpCyidGZlvEg=="],
+
     "@fontsource/knewave": ["@fontsource/knewave@5.2.7", "", {}, "sha512-uzx8jgcTiQgAwKvQ/hWdX7lOQPwS+K74Eij/WCVzYvAkCX7GRTnWnbxXXx0XsKR6UIN16kH/u40LW4K8aHJb1w=="],
 
+    "@fontsource/redacted-script": ["@fontsource/redacted-script@5.2.8", "", {}, "sha512-NOEGJyurXvCx5egCha9yUQB+Tt0IxXriacykYiRlohUvhdbKvisHbucAHQaK8N5/LLB6rlX62SrX8C9+t41PYQ=="],
+
+    "@fontsource/space-mono": ["@fontsource/space-mono@5.2.9", "", {}, "sha512-b61faFOHEISQ/pD25G+cfGY9o/WW6lRv6hBQQfpWvEJ4y1V+S4gmth95EVyBE2VL3qDYHeVQ8nBzrplzdXTDDg=="],
+
     "@hookform/resolvers": ["@hookform/resolvers@5.2.2", "", { "dependencies": { "@standard-schema/utils": "^0.3.0" }, "peerDependencies": { "react-hook-form": "^7.55.0" } }, "sha512-A/IxlMLShx3KjV/HeTcTfaMxdwy690+L/ZADoeaTltLx+CVuzkeVIPuybK3jrRfw7YZnmdKsVVHAlEPIAEUNlA=="],
 
     "@inquirer/ansi": ["@inquirer/ansi@1.0.2", "", {}, "sha512-S8qNSZiYzFd0wAcyG5AXCvUHC5Sr7xpZ9wZ2py9XR88jUz8wooStVx5M6dRzczbBWjic9NP7+rY0Xi7qqK/aMQ=="],
@@ -402,6 +416,8 @@
 
     "form-data": ["form-data@4.0.5", "", { "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "es-set-tostringtag": "^2.1.0", "hasown": "^2.0.2", "mime-types": "^2.1.12" } }, "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w=="],
 
+    "framer-motion": ["framer-motion@12.38.0", "", { "dependencies": { "motion-dom": "^12.38.0", "motion-utils": "^12.36.0", "tslib": "^2.4.0" }, "peerDependencies": { "@emotion/is-prop-valid": "*", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@emotion/is-prop-valid", "react", "react-dom"] }, "sha512-rFYkY/pigbcswl1XQSb7q424kSTQ8q6eAC+YUsSKooHQYuLdzdHjrt6uxUC+PRAO++q5IS7+TamgIw1AphxR+g=="],
+
     "fs-constants": ["fs-constants@1.0.0", "", {}, "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow=="],
 
     "fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
@@ -476,6 +492,8 @@
 
     "jsdom": ["jsdom@29.0.2", "", { "dependencies": { "@asamuzakjp/css-color": "^5.1.5", "@asamuzakjp/dom-selector": "^7.0.6", "@bramus/specificity": "^2.4.2", "@csstools/css-syntax-patches-for-csstree": "^1.1.1", "@exodus/bytes": "^1.15.0", "css-tree": "^3.2.1", "data-urls": "^7.0.0", "decimal.js": "^10.6.0", "html-encoding-sniffer": "^6.0.0", "is-potential-custom-element-name": "^1.0.1", "lru-cache": "^11.2.7", "parse5": "^8.0.0", "saxes": "^6.0.0", "symbol-tree": "^3.2.4", "tough-cookie": "^6.0.1", "undici": "^7.24.5", "w3c-xmlserializer": "^5.0.0", "webidl-conversions": "^8.0.1", "whatwg-mimetype": "^5.0.0", "whatwg-url": "^16.0.1", "xml-name-validator": "^5.0.0" }, "peerDependencies": { "canvas": "^3.0.0" }, "optionalPeers": ["canvas"] }, "sha512-9VnGEBosc/ZpwyOsJBCQ/3I5p7Q5ngOY14a9bf5btenAORmZfDse1ZEheMiWcJ3h81+Fv7HmJFdS0szo/waF2w=="],
 
+    "lenis": ["lenis@1.3.23", "", { "peerDependencies": { "@nuxt/kit": ">=3.0.0", "react": ">=17.0.0", "vue": ">=3.0.0" }, "optionalPeers": ["@nuxt/kit", "react", "vue"] }, "sha512-YxYq3TJqj9sJNv0V9SkyQHejt14xwyIwgDaaMK89Uf9SxQfIszu+gTQSSphh6BWlLTNVKvvXAGkg+Zf+oFIevg=="],
+
     "lightningcss": ["lightningcss@1.32.0", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.32.0", "lightningcss-darwin-arm64": "1.32.0", "lightningcss-darwin-x64": "1.32.0", "lightningcss-freebsd-x64": "1.32.0", "lightningcss-linux-arm-gnueabihf": "1.32.0", "lightningcss-linux-arm64-gnu": "1.32.0", "lightningcss-linux-arm64-musl": "1.32.0", "lightningcss-linux-x64-gnu": "1.32.0", "lightningcss-linux-x64-musl": "1.32.0", "lightningcss-win32-arm64-msvc": "1.32.0", "lightningcss-win32-x64-msvc": "1.32.0" } }, "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ=="],
 
     "lightningcss-android-arm64": ["lightningcss-android-arm64@1.32.0", "", { "os": "android", "cpu": "arm64" }, "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg=="],
@@ -526,6 +544,12 @@
 
     "mkdirp-classic": ["mkdirp-classic@0.5.3", "", {}, "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A=="],
 
+    "motion": ["motion@12.38.0", "", { "dependencies": { "framer-motion": "^12.38.0", "tslib": "^2.4.0" }, "peerDependencies": { "@emotion/is-prop-valid": "*", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@emotion/is-prop-valid", "react", "react-dom"] }, "sha512-uYfXzeHlgThchzwz5Te47dlv5JOUC7OB4rjJ/7XTUgtBZD8CchMN8qEJ4ZVsUmTyYA44zjV0fBwsiktRuFnn+w=="],
+
+    "motion-dom": ["motion-dom@12.38.0", "", { "dependencies": { "motion-utils": "^12.36.0" } }, "sha512-pdkHLD8QYRp8VfiNLb8xIBJis1byQ9gPT3Jnh2jqfFtAsWUA3dEepDlsWe/xMpO8McV+VdpKVcp+E+TGJEtOoA=="],
+
+    "motion-utils": ["motion-utils@12.36.0", "", {}, "sha512-eHWisygbiwVvf6PZ1vhaHCLamvkSbPIeAYxWUuL3a2PD/TROgE7FvfHWTIH4vMl798QLfMw15nRqIaRDXTlYRg=="],
+
     "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
 
     "msw": ["msw@2.13.2", "", { "dependencies": { "@inquirer/confirm": "^5.0.0", "@mswjs/interceptors": "^0.41.2", "@open-draft/deferred-promise": "^2.2.0", "@types/statuses": "^2.0.6", "cookie": "^1.0.2", "graphql": "^16.12.0", "headers-polyfill": "^4.0.2", "is-node-process": "^1.2.0", "outvariant": "^1.4.3", "path-to-regexp": "^6.3.0", "picocolors": "^1.1.1", "rettime": "^0.10.1", "statuses": "^2.0.2", "strict-event-emitter": "^0.5.1", "tough-cookie": "^6.0.0", "type-fest": "^5.2.0", "until-async": "^3.0.2", "yargs": "^17.7.2" }, "peerDependencies": { "typescript": ">= 4.8.x" }, "optionalPeers": ["typescript"], "bin": { "msw": "cli/index.js" } }, "sha512-go2H1TIERKkC48pXiwec5l6sbNqYuvqOk3/vHGo1Zd+pq/H63oFawDQerH+WQdUw/flJFHDG7F+QdWMwhntA/A=="],
@@ -712,6 +736,8 @@
 
     "until-async": ["until-async@3.0.2", "", {}, "sha512-IiSk4HlzAMqTUseHHe3VhIGyuFmN90zMTpD3Z3y8jeQbzLIq500MVM7Jq2vUAnTKAFPJrqwkzr6PoTcPhGcOiw=="],
 
+    "use-sync-external-store": ["use-sync-external-store@1.6.0", "", { "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w=="],
+
     "util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
 
     "vite": ["vite@8.0.8", "", { "dependencies": { "lightningcss": "^1.32.0", "picomatch": "^4.0.4", "postcss": "^8.5.8", "rolldown": "1.0.0-rc.15", "tinyglobby": "^0.2.15" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^20.19.0 || >=22.12.0", "@vitejs/devtools": "^0.1.0", "esbuild": "^0.27.0 || ^0.28.0", "jiti": ">=1.21.0", "less": "^4.0.0", "sass": "^1.70.0", "sass-embedded": "^1.70.0", "stylus": ">=0.54.8", "sugarss": "^5.0.0", "terser": "^5.16.0", "tsx": "^4.8.1", "yaml": "^2.4.2" }, "optionalPeers": ["@types/node", "@vitejs/devtools", "esbuild", "jiti", "less", "sass", "sass-embedded", "stylus", "sugarss", "terser", "tsx", "yaml"], "bin": { "vite": "bin/vite.js" } }, "sha512-dbU7/iLVa8KZALJyLOBOQ88nOXtNG8vxKuOT4I2mD+Ya70KPceF4IAmDsmU0h1Qsn5bPrvsY9HJstCRh3hG6Uw=="],

frontend/e2e/letter.spec.ts

@@ -1,6 +1,7 @@
 import { expect, test } from "@playwright/test";
 import pino from "pino";
 import { AuthHelper } from "./utils/auth";
+import { revealEnvelope } from "./utils/envelope";
 
 const logger = pino({
   transport: {
@@ -22,20 +23,19 @@ test.describe("Letter Drafting (Real Backend)", () => {
     await AuthHelper.registerAndLogin(page, email, name, password);
 
     logger.info(">> [Draft] Navigating to Editor via UI...");
-    await page.getByRole("button", { name: /write something/i }).click();
+    await page.getByTestId("write-letter-btn").click();
 
     logger.info(`>> [Draft] Current URL after click: ${page.url()}`);
 
-    // Wait for the recipient input to be present in the DOM
-    const recipientInput = page.locator("#recipient");
-    await recipientInput.waitFor({ state: "visible", timeout: 20000 });
+    // Editor page
+    await expect(page.getByTestId("recipient-input")).toBeVisible();
+    const recipientInput = page.getByTestId("recipient-input");
 
     const recipientName = "Dear Friend";
     await recipientInput.fill(recipientName);
 
     // Initial load: verify textarea value (populated by Fabric when focused)
-    const canvasInput = page.getByLabel("Canvas text input");
-    await canvasInput.waitFor({ state: "attached" });
+    const canvasInput = page.locator("textarea");
     await canvasInput.focus();
     await expect(canvasInput).toHaveValue(/Take a deep breath/i);
 
@@ -46,10 +46,10 @@ test.describe("Letter Drafting (Real Backend)", () => {
     await page.keyboard.press("Enter");
     await page.keyboard.type("It should persist.");
     logger.info(">> [Draft] Clicking Draft...");
-    await page.getByRole("button", { name: /draft/i }).click();
+    await page.getByTestId("draft-btn").click();
 
     // Verify Success Modal/Alert
-    await expect(page.getByText(/your letter is saved/i)).toBeVisible();
+    await expect(page.getByTestId("save-success-toast")).toBeVisible();
 
     // Verify URL updated with a UUID
     await expect(page).toHaveURL(/\/quill\/[0-9a-f-]{36}/);
@@ -60,19 +60,17 @@ test.describe("Letter Drafting (Real Backend)", () => {
     logger.info(">> [Draft] Reloading to verify persistence...");
     await page.goto(savedUrl);
 
-    // Wait for initial load overlay to disappear
-    await expect(page.getByText(/opening your draft/i)).toBeHidden();
+    // Wait for initial load overlay to appear and then definitely disappear
+    await expect(page.getByTestId("opening-draft-overlay")).toBeHidden();
 
     // Check recipient
-    await expect(page.locator("#recipient")).toHaveValue(recipientName);
+    await expect(page.getByTestId("recipient-input")).toHaveValue(recipientName);
 
     // Check canvas content
     // We wait for the content to appear in the textarea.
     // toHaveValue will poll until it matches or timeouts.
     await canvasInput.focus();
-    await expect(canvasInput).toHaveValue(/This is a secret draft/i, {
-      timeout: 10000,
-    });
+    await expect(canvasInput).toHaveValue(/This is a secret draft/i);
     await expect(canvasInput).toHaveValue(/It should persist/i);
   });
 
@@ -86,67 +84,52 @@ test.describe("Letter Drafting (Real Backend)", () => {
     await AuthHelper.registerAndLogin(page, email, name, password);
 
     logger.info(">> [Seal] Navigating to Editor via UI...");
-    await page.locator("#write-letter-btn").click();
+    await page.getByTestId("write-letter-btn").click();
 
-    const recipientInput = page.locator("#recipient");
-    await recipientInput.waitFor({ state: "visible", timeout: 10000 });
+    const recipientInput = page.getByTestId("recipient-input");
     await recipientInput.fill("A Secret Guest");
 
-    const canvasInput = page.getByLabel("Canvas text input");
+    const canvasInput = page.locator("textarea");
     await canvasInput.focus();
     await canvasInput.fill("This letter will be sealed and shared.");
 
     // Click Seal (open menu, then confirm)
     logger.info(">> [Seal] Clicking Seal...");
-    await page
-      .getByRole("button", { name: /seal/i })
-      .filter({ visible: true })
-      .click();
-    await page
-      .getByRole("button", { name: /seal/i })
-      .filter({ visible: true })
-      .click();
+    await page.getByTestId("seal-trigger-btn").click();
+    await page.getByTestId("seal-confirm-btn").click();
 
     // Should show sealed confirmation modal
     logger.info(">> [Seal] Verifying sealed modal...");
-    await expect(page.getByText(/your letter is sealed/i)).toBeVisible({
-      timeout: 10000,
-    });
+    await expect(page.getByTestId("post-seal-modal")).toBeVisible();
 
     // Navigate to Reader via "View letter"
-    await page.getByRole("button", { name: /view letter/i }).click();
+    await page.getByTestId("view-letter-btn").click();
 
     // Should be on Reader URL
-    await expect(page).toHaveURL(/\/read\/[a-f0-9-]{36}$/, { timeout: 15000 });
+    await expect(page).toHaveURL(/\/read\/[a-f0-9-]{36}$/);
 
     // Open the envelope to reveal the letter
-    await expect(page.getByText(/breaking the seal/i)).toBeHidden({
-      timeout: 10000,
-    });
-    // Flip the envelope to show the seal
-    await page.locator("#env-front").click();
-    await page.waitForTimeout(2500); // Wait for flip transition
-
-    await page.getByAltText("Seal").click();
-    await page.waitForTimeout(1500);
-    await page.locator("#letter").click({ position: { x: 30, y: 15 } });
-    await expect(page.locator("#letter")).toBeHidden({ timeout: 20000 });
+    await expect(page.getByTestId("decryption-overlay")).toBeHidden();
+    // Flip the envelope to show the seal and reveal the letter
+    await revealEnvelope(page);
+    await expect(page.getByTestId("envelope-letter")).toBeHidden();
 
     // Share on demand
     logger.info(">> [Seal] Clicking Share button in Reader...");
-    await page.locator("#share-letter-btn").click();
+    await page.getByTestId("share-letter-btn").click();
 
     // Verify share modal with a valid link
-    await expect(page.getByText(/send this letter/i)).toBeVisible();
+    await expect(page.getByTestId("share-letter-modal")).toBeVisible();
     const linkInput = page.locator("#share-link-input");
     const linkValue = await linkInput.inputValue();
     expect(linkValue).toContain("/read/");
     expect(linkValue).toContain("#");
     logger.info(`>> [Seal] Sharing link: ${linkValue}`);
 
-    await expect(page.getByRole("button", { name: /copy/i })).toBeVisible();
-    await page.getByRole("button", { name: /close/i }).click();
-    await expect(page.getByText(/send this letter/i)).toBeHidden();
+    await expect(page.getByTestId("copy-link-btn")).toBeVisible();
+    // Assuming Close button in ShareModal might need a testid too, but for now let's use text if unique or add testid
+    await page.getByTestId("modal-close-btn").click();
+    await expect(page.getByTestId("share-letter-modal")).toBeHidden();
   });
 
   test("should allow author to access sealed letter from drawer without sharing key", async ({
@@ -161,70 +144,44 @@ test.describe("Letter Drafting (Real Backend)", () => {
     await AuthHelper.registerAndLogin(page, email, name, password);
 
     logger.info(">> [Drawer] Creating and sealing a letter...");
-    await page.getByRole("button", { name: /write something/i }).click();
+    await page.getByTestId("write-letter-btn").click();
 
-    const recipientInput = page.locator("#recipient");
-    await recipientInput.waitFor({ state: "visible" });
+    const recipientInput = page.getByTestId("recipient-input");
     await recipientInput.fill(recipientName);
 
-    const canvasInput = page.getByLabel("Canvas text input");
+    const canvasInput = page.locator("textarea");
     await canvasInput.focus();
     await canvasInput.fill(letterContent);
 
     // Click Seal (open menu, then confirm)
-    await page
-      .getByRole("button", { name: /seal/i })
-      .filter({ visible: true })
-      .click();
-    await page
-      .getByRole("button", { name: /seal/i })
-      .filter({ visible: true })
-      .click();
+    await page.getByTestId("seal-trigger-btn").click();
+    await page.getByTestId("seal-confirm-btn").click();
 
     // Sealed modal should appear — click "Keep it" to go to Drawer
-    await expect(page.getByText(/your letter is sealed/i)).toBeVisible({
-      timeout: 10000,
-    });
-    await page.getByRole("button", { name: /keep it/i }).click();
+    await expect(page.getByTestId("post-seal-modal")).toBeVisible();
+    await page.getByTestId("keep-it-btn").click();
 
     // Open "Kept" section - search for the section with id='kept' and click its toggle button
     logger.info(">> [Drawer] Opening Kept section...");
-    const keptSection = page.locator("#kept");
-    await keptSection.getByRole("button", { name: /kept/i }).click();
+    await page.getByTestId("drawer-section-kept").click();
 
     // Find the sealed letter in the drawer by recipient name and click it
     logger.info(">> [Drawer] Clicking sealed letter in drawer...");
     const sealedItem = page
-      .getByRole("button", { name: new RegExp(recipientName, "i") })
+      .getByTestId(/^letter-item-/)
+      .filter({ hasText: recipientName })
       .first();
     await sealedItem.click();
 
     // Verify it opens the Reader without a hash
     logger.info(">> [Drawer] Verifying Reader page...");
     // Give it a bit more time for decryption
-    await expect(page).toHaveURL(/\/read\/[a-f0-9-]{36}$/, { timeout: 15000 }); // UUID without hash
+    await expect(page).toHaveURL(/\/read\/[a-f0-9-]{36}$/);
     // Reveal and check decrypted content in Reader
-    await expect(page.getByText(/breaking the seal/i)).toBeHidden({
-      timeout: 10000,
-    });
-    // Check recipient on the front of the envelope
-    await expect(page.getByText(new RegExp(recipientName, "i"))).toBeVisible();
-
-    // Flip the envelope to the back
-    await page.getByText(new RegExp(recipientName, "i")).click();
-    // Wait for flip transition (2s)
-    await page.waitForTimeout(2500);
-
-    // Reveal the letter: click seal then click letter
-    await page.getByAltText("Seal").click();
-    // Wait for flap transition
-    await page.waitForTimeout(1500);
-
-    // Click the letter to pull it out
-    await page.locator("#letter").click({ position: { x: 30, y: 15 } });
-
-    // Wait for reveal transition
-    await expect(page.locator("#letter")).toBeHidden({ timeout: 20000 });
+    await expect(page.getByTestId("decryption-overlay")).toBeHidden();
+    // Flip the envelope and reveal the letter
+    await revealEnvelope(page);
+    await expect(page.getByTestId("envelope-letter")).toBeHidden();
 
     // Also check if we are redirected to the Reader if we manually go to the Editor URL
     const readerUrl = page.url();

frontend/e2e/utils/auth.ts

@@ -1,6 +1,7 @@
 import { expect, type Page } from "@playwright/test";
 import pino from "pino";
 import { MailpitHelper } from "./mailpit";
+import { handleWelcomeLetter } from "./envelope";
 
 const logger = pino({
   transport: {
@@ -14,48 +15,46 @@ const logger = pino({
 /**
  * Completes the full registration -> activation -> login cycle.
  */
-export async function registerAndLogin(
+async function registerAndLogin(
   page: Page,
   email: string,
   fullName: string,
   password: string,
 ) {
-  // 1. Registration
+  // Register the User
   logger.info(`[Auth] Registering user: ${email}`);
   await page.goto("/onboard");
-  await page.getByLabel(/pen name/i).fill(fullName);
-  await page.getByLabel("Email", { exact: true }).fill(email);
-  await page.getByLabel("Password", { exact: true }).fill(password);
-  await page.getByLabel(/confirm password/i).fill(password);
-  await page.getByRole("button", { name: /^register$/i }).click();
+  await page.getByTestId("pen-name-input").fill(fullName);
+  await page.getByTestId("email-input").fill(email);
+  await page.getByTestId("password-input").fill(password);
+  await page.getByTestId("confirm-password-input").fill(password);
+  await page.getByTestId("register-submit-btn").click();
 
   await expect(page).toHaveURL(/\/verify-email/);
 
-  // 2. Activation via Mailpit
+  // Get activation URL from Mailpit and activate user
   logger.info(`[Auth] Polling Mailpit for activation email...`);
   const activationLink = await MailpitHelper.getActivationLink(email);
 
   await page.goto(activationLink);
 
-  await expect(page.getByText(/account activated/i)).toBeVisible();
-  await page.getByRole("button", { name: /start writing/i }).click();
+  await expect(page.getByTestId("activation-success-header")).toBeVisible();
+  await page.getByTestId("start-writing-btn").click();
 
-  // 3. Login
+  // Dismiss the Welcom Modal and Perform Login
   logger.info(`[Auth] Logging in...`);
   await expect(page).toHaveURL(/\/login/);
 
-  const welcomeButton = page.getByRole("button", { name: /i understand/i });
-  await welcomeButton.waitFor({ state: "visible", timeout: 10000 });
-  await welcomeButton.click();
-  await expect(welcomeButton).toBeHidden();
+  await page.getByTestId("welcome-dismiss-btn").click();
+  await expect(page.getByTestId("welcome-dismiss-btn")).toBeHidden();
 
-  await page.getByLabel("Email", { exact: true }).fill(email);
-  await page.getByLabel("Password", { exact: true }).fill(password);
-  await page.getByRole("button", { name: /sign in/i }).click();
+  await page.getByTestId("email-input").fill(email);
+  await page.getByTestId("password-input").fill(password);
+  await page.getByTestId("login-submit-btn").click();
 
   await expect(page).toHaveURL(/\/drawer/);
+  await handleWelcomeLetter(page);
   logger.info(`[Auth] Successfully authenticated ${email}`);
 }
 
-// Maintain backward compatibility if needed, or update callers
 export const AuthHelper = { registerAndLogin };

frontend/e2e/utils/envelope.ts

@@ -0,0 +1,38 @@
+import { type Page, expect } from "@playwright/test";
+import pino from "pino";
+
+const logger = pino({
+  transport: {
+    target: "pino-pretty",
+    options: {
+      colorize: true,
+    },
+  },
+});
+
+/**
+ * Reveal a letter from an envelope.
+ */
+export async function revealEnvelope(page: Page) {
+  logger.info("[Envelope] Revealing envelope...");
+  // Click envelope to flip
+  await page.getByTestId("envelope-front").click();
+
+  // Click seal to open flap
+  await page.getByTestId("wax-seal").click();
+
+  // Click letter to reveal
+  await page.getByTestId("envelope-letter").click({ position: { x: 30, y: 15 } });
+}
+
+/**
+ * Handles and dismisses the first welcome letter
+ */
+export async function handleWelcomeLetter(page: Page) {
+  logger.info("[Envelope] Handling Welcome Letter...");
+  await revealEnvelope(page);
+
+  // Click "I'll see you" button
+  await page.getByTestId("dismiss-welcome-letter-btn").click();
+  await expect(page.getByTestId("dismiss-welcome-letter-btn")).toBeHidden();
+}

frontend/e2e/utils/mailpit.ts

@@ -31,8 +31,8 @@ export const MailpitHelper = {
           );
           const details = await detailRes.json();
 
-          const body = details.HTML || details.Text || "";
-          const match = body.match(/https?:\/\/\S+activate\/\S+/);
+          const body = details.Text || "";
+          const match = body.match(/https?:\/\/\S*activate\S*/);
 
           if (match) return match[0];
         }

frontend/index.html

@@ -4,10 +4,14 @@
 <head>
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
+    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
+    <link rel="manifest" href="/site.webmanifest">
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Pi. Ku. | A safe haven for your unsent letters</title>
+    <title>Pi. Ku. | A safe haven for your unsaid and unsent letters</title>
     <meta name="description"
-        content="Pi. Ku. is a minimal, secure, and beautiful way to write and seal digital letters." />
+        content="Pi. Ku. is a minimal, secure, and beautiful way to write and seal your unsaid words into digital letters." />
 </head>
 
 <body>

frontend/package.json

@@ -1,64 +1,70 @@
 {
-  "name": "frontend",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc -b & vite build",
-    "build:prod": "vite build --mode production",
-    "lint": "biome lint --write ./src",
-    "format": "biome format --write ./src",
-    "check": "biome check --write ./src",
-    "check-all": "biome check --write .",
-    "preview": "vite preview",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:e2e": "playwright test",
-    "test:e2e:ui": "playwright test --ui --ui-host=0.0.0.0 --ui-port=43008"
-  },
-  "dependencies": {
-    "@fontsource-variable/jost": "^5.2.8",
-    "@fontsource-variable/playfair-display": "^5.2.8",
-    "@fontsource-variable/playwrite-hr-lijeva": "^5.2.7",
-    "@fontsource/cutive-mono": "^5.2.8",
-    "@fontsource/knewave": "^5.2.7",
-    "@hookform/resolvers": "^5.2.2",
-    "@phosphor-icons/react": "^2.1.10",
-    "@tailwindcss/vite": "^4.2.2",
-    "axios": "^1.15.0",
-    "daisyui": "^5.5.19",
-    "fabric": "^7.2.0",
-    "idb": "^8.0.3",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "react-hook-form": "^7.72.1",
-    "react-router-dom": "^7.14.0",
-    "tailwindcss": "^4.2.2",
-    "zod": "^4.3.6",
-    "zustand": "^5.0.12"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.11",
-    "@playwright/test": "^1.59.1",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
-    "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.6.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-basic-ssl": "^2.3.0",
-    "@vitejs/plugin-react": "^6.0.1",
-    "@vitest/coverage-v8": "^4.1.4",
-    "dotenv": "^17.4.2",
-    "fake-indexeddb": "^6.2.5",
-    "jsdom": "^29.0.2",
-    "msw": "^2.13.2",
-    "pino": "^10.3.1",
-    "pino-pretty": "^13.1.3",
-    "typescript": "~6.0.2",
-    "vite": "^8.0.4",
-    "vitest": "^4.1.4"
-  }
+    "name": "frontend",
+    "private": true,
+    "version": "0.0.0",
+    "type": "module",
+    "scripts": {
+        "dev": "vite",
+        "build": "tsc -b & vite build",
+        "build:prod": "vite build --mode production",
+        "lint": "biome lint --write ./src",
+        "format": "biome format --write ./src",
+        "check": "biome check --write ./src",
+        "check-all": "biome check --write .",
+        "preview": "vite preview",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage",
+        "test:e2e": "playwright test",
+        "test:e2e:ui": "playwright test --ui --ui-host=0.0.0.0 --ui-port=43008"
+    },
+    "dependencies": {
+        "@fontsource-variable/jost": "^5.2.8",
+        "@fontsource-variable/playfair-display": "^5.2.8",
+        "@fontsource-variable/playwrite-hr-lijeva": "^5.2.7",
+        "@fontsource/architects-daughter": "^5.2.7",
+        "@fontsource/cutive-mono": "^5.2.8",
+        "@fontsource/kavivanar": "^5.2.8",
+        "@fontsource/knewave": "^5.2.7",
+        "@fontsource/redacted-script": "^5.2.8",
+        "@fontsource/space-mono": "^5.2.9",
+        "@hookform/resolvers": "^5.2.2",
+        "@phosphor-icons/react": "^2.1.10",
+        "@tailwindcss/vite": "^4.2.2",
+        "axios": "^1.15.0",
+        "daisyui": "^5.5.19",
+        "fabric": "^7.2.0",
+        "idb": "^8.0.3",
+        "lenis": "^1.3.23",
+        "motion": "^12.38.0",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
+        "react-hook-form": "^7.72.1",
+        "react-router-dom": "^7.14.0",
+        "tailwindcss": "^4.2.2",
+        "zod": "^4.3.6",
+        "zustand": "^5.0.12"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.4.11",
+        "@playwright/test": "^1.59.1",
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/react": "^16.3.2",
+        "@testing-library/user-event": "^14.6.1",
+        "@types/node": "^25.6.0",
+        "@types/react": "^19.2.14",
+        "@types/react-dom": "^19.2.3",
+        "@vitejs/plugin-basic-ssl": "^2.3.0",
+        "@vitejs/plugin-react": "^6.0.1",
+        "@vitest/coverage-v8": "^4.1.4",
+        "dotenv": "^17.4.2",
+        "fake-indexeddb": "^6.2.5",
+        "jsdom": "^29.0.2",
+        "msw": "^2.13.2",
+        "pino": "^10.3.1",
+        "pino-pretty": "^13.1.3",
+        "typescript": "~6.0.2",
+        "vite": "^8.0.4",
+        "vitest": "^4.1.4"
+    }
 }

frontend/playwright.config.ts

@@ -15,7 +15,7 @@ const baseUrl = getBaseUrl(
 );
 
 export default defineConfig({
-  timeout: 60000,
+  timeout: 80000,
   expect: {
     timeout: 10000,
   },
@@ -60,7 +60,8 @@ export default defineConfig({
 
   /* Run your local dev server before starting the tests */
   webServer: {
-    command: "npm run dev -- --mode e2e",
+    // NOTE: using npm here for docker compat mainly
+    command: "npm run build -- --mode e2e && npm run preview -- --mode e2e",
     url: getBaseUrl(
       process.env.SSL_ENABLED === "true",
       process.env.FRONTEND_DOMAIN,

frontend/public/site.webmanifest

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

frontend/src/App.tsx

@@ -1,12 +1,10 @@
-import { lazy, Suspense, useEffect } from "react";
+import { lazy, Suspense, useEffect, useRef } from "react";
 import { BrowserRouter, Navigate, Route, Routes } from "react-router-dom";
-import { ProtectedRoute, PublicRoute } from "./components/RouteGuards";
+import { AutoRedirectRoute, ProtectedRoute } from "./components/RouteGuards";
 import SplashScreen from "./components/SplashScreen";
 import { ROUTES } from "./config/routes";
 import { useAuth } from "./hooks/useAuth";
 
-let authInitialized = false;
-
 const Activate = lazy(() => import("./pages/Activate"));
 const Drawer = lazy(() => import("./pages/Drawer"));
 const Editor = lazy(() => import("./pages/Editor"));
@@ -15,14 +13,16 @@ const Login = lazy(() => import("./pages/Login"));
 const Reader = lazy(() => import("./pages/Reader"));
 const Register = lazy(() => import("./pages/Register"));
 const VerifyEmail = lazy(() => import("./pages/VerifyEmail"));
+const About = lazy(() => import("./pages/About"));
 
 export default function App() {
   const { initialize, isInitializing } = useAuth();
+  const authInitialized = useRef<boolean>(false);
 
   useEffect(() => {
-    if (authInitialized) return;
-    authInitialized = true;
-    initialize();
+    if (authInitialized.current) return;
+    authInitialized.current = true;
+    initialize().then();
   }, [initialize]);
 
   if (isInitializing) {
@@ -31,41 +31,48 @@ export default function App() {
 
   return (
     <BrowserRouter>
-      <main className="min-h-screen bg-base-200 flex items-center justify-center w-full">
+      <main className="relative min-h-screen min-w-screen flex items-center justify-center w-full bg-base-200 before:absolute before:top-0 before:left-0 before:w-full before:h-full before:content-[''] before:opacity-[0.03] before:z-50 before:pointer-events-none before:bg-[url('assets/textures/noise.gif')]">
         <Suspense fallback={<SplashScreen />}>
           <Routes>
-            <Route path={ROUTES.HOME} element={<Home />} />
+            <Route
+              path={ROUTES.HOME}
+              element={
+                <AutoRedirectRoute>
+                  <Home />
+                </AutoRedirectRoute>
+              }
+            />
 
             <Route
               path={ROUTES.ONBOARD}
               element={
-                <PublicRoute>
+                <AutoRedirectRoute>
                   <Register />
-                </PublicRoute>
+                </AutoRedirectRoute>
               }
             />
             <Route
               path={ROUTES.LOGIN}
               element={
-                <PublicRoute>
+                <AutoRedirectRoute>
                   <Login />
-                </PublicRoute>
+                </AutoRedirectRoute>
               }
             />
             <Route
               path={ROUTES.VERIFY_EMAIL}
               element={
-                <PublicRoute>
+                <AutoRedirectRoute>
                   <VerifyEmail />
-                </PublicRoute>
+                </AutoRedirectRoute>
               }
             />
             <Route
               path={ROUTES.ACTIVATE}
               element={
-                <PublicRoute>
+                <AutoRedirectRoute>
                   <Activate />
-                </PublicRoute>
+                </AutoRedirectRoute>
               }
             />
 
@@ -86,6 +93,7 @@ export default function App() {
               }
             />
             <Route path={ROUTES.READ} element={<Reader />} />
+            <Route path={ROUTES.ABOUT} element={<About />} />
             <Route path="*" element={<Navigate to={ROUTES.HOME} replace />} />
           </Routes>
         </Suspense>

frontend/src/api/apiClient.ts

@@ -2,19 +2,19 @@ import axios from "axios";
 import { endpoints } from "../config/endpoints";
 import { useAuthStore } from "../store/useAuthStore";
 
+export const apiServerUrl = import.meta.env.VITE_API_URL;
+
 // publicApi for endpoints that don't need authentication (login, refresh, register)
 export const publicApi = axios.create({
-  baseURL: import.meta.env.VITE_API_URL,
+  baseURL: apiServerUrl,
   withCredentials: true,
 });
 
 // api for all authenticated requests
 export const api = axios.create({
-  baseURL: import.meta.env.VITE_API_URL,
+  baseURL: apiServerUrl,
   withCredentials: true,
 });
-
-// auto-attach access token to authenticated requests
 api.interceptors.request.use((config) => {
   const token = useAuthStore.getState().accessToken;
   if (token) {
@@ -22,29 +22,28 @@ api.interceptors.request.use((config) => {
   }
   return config;
 });
-
-// Handle 401 errors by attempting a silent refresh
+// auto handle 401 errors by attempting a silent refresh
 api.interceptors.response.use(
   (response) => response,
   async (error) => {
     const originalRequest = error.config;
 
-    // If 401 and we haven't tried refreshing yet
+    // if first time 401 and we haven't tried refreshing yet, we proceed with silent refresh
+    // else it could mean the refresh also 401'd
     if (error.response?.status === 401 && !originalRequest._retry) {
       originalRequest._retry = true;
 
       try {
-        // Attempt silent refresh
         const { data } = await publicApi.post(endpoints.REFRESH);
         const newAccessToken = data.access;
 
-        // Update store
+        // Update store with the latest accesstoken
         const { user, setAuth } = useAuthStore.getState();
         if (user) {
           setAuth(newAccessToken, user);
         }
 
-        // Retry the original request with the new token
+        // retry the original request with the new token
         originalRequest.headers.Authorization = `Bearer ${newAccessToken}`;
         return api(originalRequest);
       } catch (refreshError) {

frontend/src/api/response.ts

@@ -0,0 +1,24 @@
+export interface LetterResponseData {
+  public_id: string;
+  type: "KEPT" | "SENT" | "VAULT";
+  status: "DRAFT" | "SEALED" | "BURNED";
+  encrypted_content: string;
+  encrypted_metadata: string;
+  encrypted_dek: string;
+  unlock_at: string | null;
+  sealed_at: string | null;
+  created_at: string;
+  updated_at: string;
+  images: LetterImageData[];
+}
+
+export interface LetterImageData {
+  public_id: string;
+  file: string;
+  file_name: string;
+}
+
+export interface LetterMetadata {
+  recipient: string;
+  tags?: string[];
+}

frontend/src/components/Logo.tsx

@@ -1,25 +1,59 @@
 import { DotIcon } from "@phosphor-icons/react";
+import logo from "../assets/logo.svg";
 import "@fontsource/knewave/400.css";
 
-export default function Logo({ scale = 2 }) {
+interface LogoProps {
+  scale?: number;
+  type?: "inline" | "mono" | "logo" | null;
+  ul?: boolean;
+}
+
+export default function Logo({
+  scale = 1,
+  type = null,
+  ul = false,
+}: LogoProps) {
+  if (type === "inline") {
+    return (
+      <span className={"text-accent font-display italic "}>
+        pi<span className="text-primary">.</span>&nbsp;ku
+        <span className="text-primary">.</span>&nbsp;
+      </span>
+    );
+  }
+
+  if (type === "mono") {
+    return (
+      <span className="font-display italic font-bold border-b-3 border-dashed border-stone-800/50">
+        pi. ku.
+      </span>
+    );
+  }
+
+  if (type === "logo") {
+    return (
+      <img src={logo} alt="Pi. Ku. logo" className="mx-4" width={scale * 100} />
+    );
+  }
+
   return (
     <div
       role="img"
-      aria-label="Pi Ku"
-      className="inline-flex items-baseline justify-center leading-none select-none"
+      aria-label="Pi. Ku. logo"
+      className={`inline-flex items-baseline justify-center leading-none select-none ${ul ? "ul-wavy" : ""}`}
       style={{ fontFamily: "'Knewave', serif", scale }}
     >
-      <span className={`text-xl font-light text-accent`}>&nbsp;Pi</span>
+      <span className="text-3xl font-light text-accent">Pi</span>
       <DotIcon
         weight="fill"
-        size={6}
-        className={`text-primary translate-y-1 -mx-px`}
+        size={12}
+        className="text-primary translate-y-1 -mx-px"
       />
-      <span className={`text-xl font-light text-accent`}>&nbsp;Ku</span>
+      <span className="text-3xl font-light text-accent">&nbsp;Ku</span>
       <DotIcon
         weight="fill"
-        size={6}
-        className={`text-primary translate-y-1 -mx-px`}
+        size={12}
+        className="text-primary translate-y-1 -mx-px"
       />
     </div>
   );

frontend/src/components/RouteGuards.test.tsx

@@ -3,14 +3,20 @@ import { MemoryRouter, Route, Routes } from "react-router-dom";
 import { beforeEach, describe, expect, it } from "vitest";
 import { mockUser } from "../../test/fixtures/user.fixture";
 import { useAuthStore } from "../store/useAuthStore";
-import { ProtectedRoute, PublicRoute } from "./RouteGuards";
+import { AutoRedirectRoute, ProtectedRoute } from "./RouteGuards";
 
 function renderGuard(ui: React.ReactNode, mountPath: "/protected" | "/public") {
   return render(
     <MemoryRouter initialEntries={[mountPath]}>
       <Routes>
-        <Route path="/login" element={<div>Login Page</div>} />
-        <Route path="/drawer" element={<div>Drawer Page</div>} />
+        <Route
+          path="/login"
+          element={<div data-testid="login-page">Login Page</div>}
+        />
+        <Route
+          path="/drawer"
+          element={<div data-testid="drawer-page">Drawer Page</div>}
+        />
         <Route path="/protected" element={ui} />
         <Route path="/public" element={ui} />
       </Routes>
@@ -35,13 +41,13 @@ describe("ProtectedRoute", () => {
     });
     renderGuard(
       <ProtectedRoute>
-        <div>Secret</div>
+        <div data-testid="secret-page">Secret</div>
       </ProtectedRoute>,
       "/protected",
     );
 
-    expect(screen.getByText(/Unsealing/i)).toBeInTheDocument();
-    expect(screen.queryByText("Secret")).not.toBeInTheDocument();
+    expect(screen.getByTestId("splash-screen")).toBeInTheDocument();
+    expect(screen.queryByTestId("secret-page")).not.toBeInTheDocument();
   });
 
   it("should redirect unauthenticated users to /login", () => {
@@ -52,12 +58,12 @@ describe("ProtectedRoute", () => {
     });
     renderGuard(
       <ProtectedRoute>
-        <div>Secret</div>
+        <div data-testid="secret-page">Secret</div>
       </ProtectedRoute>,
       "/protected",
     );
-    expect(screen.getByText("Login Page")).toBeInTheDocument();
-    expect(screen.queryByText("Secret")).not.toBeInTheDocument();
+    expect(screen.getByTestId("login-page")).toBeInTheDocument();
+    expect(screen.queryByTestId("secret-page")).not.toBeInTheDocument();
   });
 
   it("should render page for authenticated users", () => {
@@ -68,12 +74,12 @@ describe("ProtectedRoute", () => {
     });
     renderGuard(
       <ProtectedRoute>
-        <div>Secret</div>
+        <div data-testid="secret-page">Secret</div>
       </ProtectedRoute>,
       "/protected",
     );
 
-    expect(screen.getByText("Secret")).toBeInTheDocument();
+    expect(screen.getByTestId("secret-page")).toBeInTheDocument();
   });
 });
 
@@ -85,13 +91,13 @@ describe("PublicRoute", () => {
       user: null,
     });
     renderGuard(
-      <PublicRoute>
-        <div>Login Page</div>
-      </PublicRoute>,
+      <AutoRedirectRoute>
+        <div data-testid="mock-login-page">Login Page</div>
+      </AutoRedirectRoute>,
       "/public",
     );
-    expect(screen.getByText(/Unsealing/i)).toBeInTheDocument();
-    expect(screen.queryByText("Login Page")).not.toBeInTheDocument();
+    expect(screen.getByTestId("splash-screen")).toBeInTheDocument();
+    expect(screen.queryByTestId("mock-login-page")).not.toBeInTheDocument();
   });
 
   it("should redirect authenticated users to /drawer", () => {
@@ -101,13 +107,13 @@ describe("PublicRoute", () => {
       user: mockUser,
     });
     renderGuard(
-      <PublicRoute>
-        <div>Login Form</div>
-      </PublicRoute>,
+      <AutoRedirectRoute>
+        <div data-testid="login-form">Login Form</div>
+      </AutoRedirectRoute>,
       "/public",
     );
-    expect(screen.getByText("Drawer Page")).toBeInTheDocument();
-    expect(screen.queryByText("Login Form")).not.toBeInTheDocument();
+    expect(screen.getByTestId("drawer-page")).toBeInTheDocument();
+    expect(screen.queryByTestId("login-form")).not.toBeInTheDocument();
   });
 
   it("should render page for unauthenticated users", () => {
@@ -117,11 +123,11 @@ describe("PublicRoute", () => {
       user: null,
     });
     renderGuard(
-      <PublicRoute>
-        <div>Login Form</div>
-      </PublicRoute>,
+      <AutoRedirectRoute>
+        <div data-testid="login-form">Login Form</div>
+      </AutoRedirectRoute>,
       "/public",
     );
-    expect(screen.getByText("Login Form")).toBeInTheDocument();
+    expect(screen.getByTestId("login-form")).toBeInTheDocument();
   });
 });

frontend/src/components/RouteGuards.tsx

@@ -4,8 +4,9 @@ import { useAuth } from "../hooks/useAuth";
 import SplashScreen from "./SplashScreen";
 
 /**
- * Post-login routes.
- * Redirects to /login if not already authenticated.
+ * Private route guard.
+ * If not authenticated, capture the current url in route
+ * state so the Login component can link them back after sign-in
  */
 export function ProtectedRoute({ children }: { children: React.ReactNode }) {
   const { isAuthenticated, isInitializing } = useAuth();
@@ -14,7 +15,6 @@ export function ProtectedRoute({ children }: { children: React.ReactNode }) {
   if (isInitializing) return <SplashScreen />;
 
   if (!isAuthenticated) {
-    // Save the intended location to redirect back after login
     return <Navigate to={ROUTES.LOGIN} state={{ from: location }} replace />;
   }
 
@@ -22,10 +22,10 @@ export function ProtectedRoute({ children }: { children: React.ReactNode }) {
 }
 
 /**
- * Pre-login flows.
- * Redirects to /drawer if already authenticated.
+ * Auto-redirect - auth route guard.
+ * If authenticated, redirect all the auth related flows to the drawer
  */
-export function PublicRoute({ children }: { children: React.ReactNode }) {
+export function AutoRedirectRoute({ children }: { children: React.ReactNode }) {
   const { isAuthenticated, isInitializing } = useAuth();
 
   if (isInitializing) return <SplashScreen />;

frontend/src/components/SplashScreen.tsx

@@ -3,7 +3,10 @@ import Logo from "./Logo";
 
 export default function SplashScreen() {
   return (
-    <div className="fixed w-screen h-screen inset-0 bg-base-100 flex flex-col items-center justify-center z-9999">
+    <div
+      data-testid="splash-screen"
+      className="fixed w-screen h-screen inset-0 flex flex-col items-center justify-center z-9999  before:absolute before:top-0 before:left-0 before:w-full before:h-full before:content-[''] before:opacity-[0.03] before:z-10 before:pointer-events-none before:bg-[url('assets/textures/noise.gif')"
+    >
       <div className="flex flex-col items-center gap-6 animate-pulse">
         <Logo />
 
@@ -15,7 +18,7 @@ export default function SplashScreen() {
           />
           <span className="loading loading-ring loading-xl text-primary"></span>
           ...
-          <p className="text-xs uppercase font-sans tracking-[1em] opacity-40">
+          <p className="text-xs uppercase font-sans tracking-widester opacity-40">
             Unsealing
           </p>
         </div>

frontend/src/components/drawer/DrawerSection.tsx

@@ -3,19 +3,23 @@ import { GearFineIcon } from "@phosphor-icons/react";
 interface DrawerSectionProps {
   id: string;
   title: string;
-  count: string;
+  count: number;
+  subtext: string;
   isOpen: boolean;
   onClick: () => void;
   children: React.ReactNode;
+  icon: React.ReactNode;
 }
 
 export function DrawerSection({
   id,
   title,
   count,
+  subtext,
   isOpen,
   onClick,
   children,
+  icon,
 }: DrawerSectionProps) {
   return (
     <div
@@ -23,23 +27,37 @@ export function DrawerSection({
       className={`join-item group flex flex-col transition-colors duration-3000 ease-in-out ${isOpen ? "bg-base-300/30" : ""}`}
     >
       <div
-        className={`transition-all duration-1500 ease-in-out bg-neutral/10 ${
-          isOpen
-            ? "max-h-125 opacity-100 py-3 border-b border-base-content/5 overflow-visible"
-            : "max-h-0 opacity-0 pointer-events-none"
-        }`}
+        className={`bg-neutral/10 transition-all duration-1000 ease-in-out overflow-visible ${isOpen ? "max-h-125" : "max-h-0 pointer-events-none"}`}
       >
-        {children}
+        <div
+          className={`transition-opacity ease-in-out ${
+            isOpen
+              ? "opacity-100 py-3 border-b border-base-content/5 duration-700 delay-500"
+              : "opacity-0 duration-100"
+          }`}
+        >
+          {children}
+          {count === 0 && (
+            <p
+              data-testid={`empty-drawer-message-${id}`}
+              className="text-center text-base-content/20 mt-4"
+            >
+              This drawer remains silent
+            </p>
+          )}
+        </div>
       </div>
 
       <button
         type="button"
         onClick={onClick}
-        className={`w-full p-[24px_28px] cursor-pointer flex items-center gap-5 transition-all duration-2000 ease-in-out outline-none focus-visible:ring-2 focus-visible:ring-primary/50 border border-base-content/10 text-left bg-linear-to-r from-transparent to-base-100/40`}
+        data-testid={`drawer-section-${id}`}
+        className="w-full relative p-[24px_28px] cursor-pointer flex items-center gap-5 transition-all duration-2000 ease-in-out outline-none focus-visible:ring-2 overflow-hidden focus-visible:ring-primary/50 border border-base-content/10 text-left bg-linear-to-r from-transparent to-base-100/40"
       >
         <div className="flex-1">
           <div
-            className={`font-sans text-xs tracking-[0.2em] uppercase transition-colors duration-800 ${
+            data-testid="drawer-section-title"
+            className={`font-sans text-xs tracking-widester uppercase transition-colors duration-800 ${
               isOpen
                 ? "text-base-content"
                 : "text-base-content/40 group-hover:text-base-content/80"
@@ -47,8 +65,15 @@ export function DrawerSection({
           >
             {title}
           </div>
-          <div className="font-sans text-[0.6rem] text-base-content/20 mt-1">
-            {count}
+          <div className="font-sans text-xs text-base-content/20 mt-1">
+            <span className="font-mono text-xs md:text-base -mt-1 absolute text-primary/30">
+              {count}
+            </span>
+            &nbsp;
+            <span className="ml-3">{subtext}</span>
+          </div>
+          <div className="absolute right-5 -translate-y-15 text-base-content/4">
+            {icon}
           </div>
         </div>
 

frontend/src/components/drawer/LetterItem.tsx

@@ -2,6 +2,15 @@ import { LockIcon, LockKeyOpenIcon } from "@phosphor-icons/react";
 import { useNavigate } from "react-router-dom";
 import { PATHS } from "../../config/routes";
 
+interface LetterItemProps {
+  preview: string;
+  timestamp: string;
+  id: string;
+  status: "DRAFT" | "SEALED" | "BURNED";
+  unlock_at?: string;
+  isLocked?: boolean;
+}
+
 export function LetterItem({
   preview,
   timestamp,
@@ -9,14 +18,7 @@ export function LetterItem({
   status,
   unlock_at,
   isLocked = false,
-}: {
-  preview: string;
-  timestamp: string;
-  id: string;
-  status: "DRAFT" | "SEALED" | "BURNED";
-  unlock_at?: string;
-  isLocked?: boolean;
-}) {
+}: LetterItemProps) {
   const navigate = useNavigate();
   function handleNavigate(): void {
     if (isLocked) return;
@@ -31,9 +33,10 @@ export function LetterItem({
     <button
       type="button"
       onClick={handleNavigate}
+      data-testid={`letter-item-${id}`}
       className={`${isLocked ? "pointer-events-none" : ""} p-4 border-base-content/3 flex items-start gap-4 hover:bg-base-300 transition-all delay-75 duration-100 group text-left cursor-pointer w-9/12 mx-auto hover:scale-120 hover:h-24 hover:-translate-y-3 hover:pb-4 hover:border-x-5 hover:border-t-5 border-t-2 hover:-mb-2`}
     >
-      <div className="text-[0.85rem] italic text-base-content/40 flex-1 truncate group-hover:text-base-content/60 transition-none animate-[opacity_200ms_linear_forwards]">
+      <div className="text-sm italic text-base-content/40 flex-1 truncate group-hover:text-base-content/60">
         {preview}
       </div>
       {unlock_at ? (
@@ -50,7 +53,7 @@ export function LetterItem({
           )}
         </div>
       ) : (
-        <div className="font-sans text-[0.6rem] text-base-content/20 transition-none">
+        <div className="font-sans text-xs text-base-content/20">
           {timestamp}
         </div>
       )}

frontend/src/components/drawer/PasskeyModal.tsx

@@ -1,52 +1,59 @@
-import { LockKeyIcon } from "@phosphor-icons/react";
+import { HourglassSimpleMediumIcon } from "@phosphor-icons/react";
+import { useAuth } from "../../hooks/useAuth";
+import { Modal } from "../ui/Modal";
 
-interface PasskeyModalProps {
-  onUnlock: (password: string) => Promise<void>;
-}
+export function PasskeyModal() {
+  const { unlock } = useAuth();
 
-export function PasskeyModal({ onUnlock }: PasskeyModalProps) {
   return (
-    <div className="modal modal-open bg-base-100/20 backdrop-blur-md z-100">
-      <div className="modal-box p-12 flex flex-col items-center">
-        <LockKeyIcon
-          size={48}
-          className="text-primary mx-auto mb-8 animate-pulse"
-        />
-        <h3 className="font-bold text-lg font-display text-primary">
-          Authentication Required
-        </h3>
-        <p className="py-4 font-sans">
-          We need your passkey to open your letters
-        </p>
-        <div className="divider w-1/2 mx-auto text-xs text-neutral-content/30 mt-0"></div>
-        <p className="text-xs text-neutral-content/30 font-mono italic">
-          Your passkey is used to decrypt your data locally.
-        </p>
-        <div className="modal-action items-center gap-4">
-          <form
-            className="form-control w-full inline-flex"
-            onSubmit={async (e: React.SubmitEvent<HTMLFormElement>) => {
-              e.preventDefault();
-              const formData = new FormData(e.currentTarget);
-              const password = formData.get("password") as string;
-              if (!password) return;
-              await onUnlock(password);
-            }}
+    <Modal isOpen={true}>
+      <HourglassSimpleMediumIcon
+        size={48}
+        className="text-primary mx-auto mb-8 animate-pulse"
+        weight="duotone"
+      />
+      <h3
+        data-testid="passkey-modal-title"
+        className="font-bold text-lg font-display text-primary"
+      >
+        You've been away a while.
+      </h3>
+      <p className="py-4 font-sans">
+        Your letters are still there. Just need the key once more.
+      </p>
+      <div className="divider w-1/2 mx-auto text-xs text-neutral-content/30 mt-0"></div>
+      <p className="text-xs text-neutral-content/30 font-mono italic">
+        Nothing was lost.
+      </p>
+      <div className="modal-action items-center gap-4">
+        <form
+          className="form-control w-full inline-flex"
+          onSubmit={async (e: React.SubmitEvent<HTMLFormElement>) => {
+            e.preventDefault();
+            const formData = new FormData(e.currentTarget);
+            const password = formData.get("password") as string;
+            if (!password) return;
+            await unlock(password);
+          }}
+        >
+          <input
+            name="password"
+            required
+            type="password"
+            placeholder="password"
+            data-testid="passkey-input"
+            className="font-sans validator input input-bordered rounded-r-none"
+          />
+          <div className="validator-message text-xs text-error"></div>
+          <button
+            type="submit"
+            data-testid="passkey-submit-btn"
+            className="btn btn-primary rounded-l-none"
           >
-            <input
-              name="password"
-              required
-              type="password"
-              placeholder="password"
-              className="font-sans validator input input-bordered rounded-r-none"
-            />
-            <div className="validator-message text-xs text-error"></div>
-            <button type="submit" className="btn btn-primary rounded-l-none">
-              Unlock
-            </button>
-          </form>
-        </div>
+            Unlock
+          </button>
+        </form>
       </div>
-    </div>
+    </Modal>
   );
 }

frontend/src/components/drawer/WelcomeLetterOverlay.tsx

@@ -0,0 +1,78 @@
+import { AnimatePresence, motion } from "motion/react";
+import { useEffect, useRef, useState } from "react";
+import { getWelcomeLetterContent } from "../../config/welcomeLetter";
+import { formatDate } from "../../utils/dateFormat";
+import { type CanvasTools, ComposeCanvas } from "../editor/ComposeCanvas";
+import { EnvelopeReveal } from "../reader/EnvelopeReveal";
+
+export interface WelcomeLetterOverlayProps {
+  onComplete: () => void;
+  userName: string;
+}
+
+export function WelcomeLetterOverlay({
+  onComplete,
+  userName,
+}: WelcomeLetterOverlayProps) {
+  const [revealState, setRevealState] = useState<"SEALED" | "REVEALED">(
+    "SEALED",
+  );
+  const canvasRef = useRef<CanvasTools>(null);
+
+  useEffect(() => {
+    if (revealState === "REVEALED" && canvasRef.current) {
+      const welcomeContent = getWelcomeLetterContent(userName);
+      canvasRef.current.loadData(welcomeContent);
+    }
+  }, [revealState, userName]);
+
+  return (
+    <div className="fixed inset-0 z-30 backdrop-blur-3xl flex flex-col items-center justify-center p-4 md:p-8 overflow-x-hidden">
+      <div className="fixed inset-0 bg-vig pointer-events-none z-0" />
+
+      <div className="w-full max-w-4xl z-10 flex flex-col items-center">
+        <AnimatePresence mode="wait">
+          {revealState === "SEALED" && (
+            <motion.div
+              key="envelope"
+              initial={{ scale: 0.5, opacity: 0 }}
+              animate={{ scale: 0.8, opacity: 1 }}
+              exit={{
+                scale: 1,
+                opacity: 0,
+                transition: { duration: 0.5, ease: "easeOut" },
+              }}
+              transition={{ duration: 4, delay: 1 }}
+            >
+              <EnvelopeReveal
+                recipient={userName}
+                date={formatDate(new Date())}
+                onRevealComplete={() => setRevealState("REVEALED")}
+                ignite={false}
+              />
+            </motion.div>
+          )}
+        </AnimatePresence>
+        <div
+          className={`w-full space-y-8 py-12 ${revealState === "REVEALED" ? "block" : "hidden"}`}
+        >
+          <div className="bg-paper shadow-warm rounded-sm overflow-hidden mx-auto max-w-180">
+            <div className="p-1 md:p-2 bg-base-content/5 opacity-10 pointer-events-none absolute inset-0 z-10" />
+            <ComposeCanvas ref={canvasRef} readOnly />
+          </div>
+
+          <div className="flex justify-center mt-12">
+            <button
+              type="button"
+              data-testid="dismiss-welcome-letter-btn"
+              onClick={onComplete}
+              className="btn btn-base btn-xs btn-wide opacity-80 shadow-lg font-light tracking-wider"
+            >
+              I'll see you
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/editor/ComposeCanvas.tsx

@@ -1,15 +1,18 @@
 import * as fabric from "fabric";
-import {
-  forwardRef,
-  useCallback,
-  useEffect,
-  useImperativeHandle,
-  useRef,
-} from "react";
+import type * as React from "react";
+import { useCallback, useEffect, useImperativeHandle, useRef } from "react";
+
+import "@fontsource/kavivanar/index.css";
+import "@fontsource/space-mono/index.css";
+import "@fontsource/cutive-mono/index.css";
+import "@fontsource/architects-daughter/index.css";
+import "@fontsource/redacted-script/index.css";
 
 const PAD = 36;
 const BASE_WIDTH = 680;
 const DEFAULT_LOGICAL_HEIGHT = 900;
+const DEFAULT_FONT_FAMILY = "Playfair Display Variable";
+const DEFAULT_FONT_COLOR = "#000";
 
 export interface FabricObjectJSON {
   type: string;
@@ -18,6 +21,7 @@ export interface FabricObjectJSON {
   left: number;
   width: number;
   height: number;
+
   [key: string]: unknown;
 }
 
@@ -33,121 +37,26 @@ export interface CanvasJSON {
   canvasHeight?: number;
 }
 
+export interface CanvasStyle {
+  fontFamily: string;
+  fontColor: string;
+}
+
 export type CanvasTools = {
   addImage: (url: string, file: File) => void;
   getData: () => CanvasJSON;
-  getJsonData: () => string;
   getImages: () => { src: string; file: File }[];
   loadData: (data: CanvasJSON) => Promise<void>;
+  getStyle: () => CanvasStyle;
 };
 
 export interface FabricImageWithFile extends fabric.FabricImage {
   _customRawFile: File;
 }
 
-const waitForLayout = (wrapper: HTMLDivElement): Promise<number> => {
-  return new Promise((resolve) => {
-    const check = () => {
-      const width = wrapper.clientWidth || 0;
-      if (width > 0) resolve(width);
-      else requestAnimationFrame(check);
-    };
-    check();
-  });
-};
-
-const createMainTextbox = (
-  text: string,
-  isReadOnly = false,
-): fabric.Textbox => {
-  return new fabric.Textbox(text, {
-    name: "main-textbox",
-    originX: "left",
-    originY: "top",
-    left: PAD,
-    top: PAD,
-    width: BASE_WIDTH - PAD * 2,
-    fontSize: 18,
-    fontWeight: 500,
-    fontFamily: "Playfair Display Variable",
-    fill: "#000",
-    lineHeight: 1.5,
-    editable: !isReadOnly,
-    selectable: false,
-    evented: !isReadOnly,
-    hasControls: false,
-    hasBorders: false,
-    objectCaching: false,
-    splitByGrapheme: false,
-    lockMovementX: true,
-    lockMovementY: true,
-    lockScalingX: true,
-    lockScalingY: true,
-    lockRotation: true,
-  });
-};
-
-const fixFabricA11y = () => {
-  const textAreas = document.querySelectorAll(
-    'textarea[data-fabric="textarea"]',
-  );
-  for (const area of textAreas) {
-    if (!area.getAttribute("aria-label")) {
-      area.setAttribute("aria-label", "Canvas text input");
-    }
-  }
-};
-
-const initializeCanvas = (
-  el: HTMLCanvasElement,
-  width: number,
-  height: number,
-  readOnly: boolean,
-) => {
-  const canvas = new fabric.Canvas(el, {
-    width,
-    height,
-    selection: !readOnly,
-    preserveObjectStacking: true,
-    allowTouchScrolling: true,
-    enableRetinaScaling: true,
-    objectCaching: false,
-  });
-
-  const wrapperEl = canvas.getElement().parentElement;
-  if (wrapperEl) wrapperEl.style.background = "transparent";
-
-  return canvas;
-};
-
-const getLogicalSize = (data: CanvasJSON | null) => {
-  return {
-    width: data?.canvasWidth ?? BASE_WIDTH,
-    height: data?.canvasHeight ?? DEFAULT_LOGICAL_HEIGHT,
-  };
-};
-
-const getObjectBottom = (obj: fabric.FabricObject) => {
-  const top = obj.top ?? 0;
-  const height =
-    typeof obj.getScaledHeight === "function"
-      ? obj.getScaledHeight()
-      : (obj.height ?? 0) * (obj.scaleY ?? 1);
-
-  return top + height;
-};
-
-const measureLogicalContentHeight = (
-  canvas: fabric.Canvas,
-  minimumHeight = DEFAULT_LOGICAL_HEIGHT,
-) => {
-  const maxBottom = canvas
-    .getObjects()
-    .reduce((max, obj) => Math.max(max, getObjectBottom(obj)), 0);
-
-  return Math.max(minimumHeight, maxBottom + PAD);
-};
-
+// NOTE: We use the same canvasData to render on both mobile and desktop viewports.
+// Instead of calculating the entire objects pad again, we apply a zoom multiplier (scale down or up)
+// over the last saved canvas size.
 const applyResponsiveViewport = (
   canvas: fabric.Canvas,
   wrapper: HTMLDivElement,
@@ -155,8 +64,8 @@ const applyResponsiveViewport = (
   logicalHeight: number,
 ) => {
   const physicalWidth = wrapper.clientWidth || logicalWidth;
-  const zoom = physicalWidth / logicalWidth;
-  const physicalHeight = Math.max(1, logicalHeight * zoom);
+  const zoomMultiplier = physicalWidth / logicalWidth;
+  const physicalHeight = Math.max(1, logicalHeight * zoomMultiplier);
 
   canvas.setDimensions({
     width: physicalWidth,
@@ -164,41 +73,45 @@ const applyResponsiveViewport = (
   });
 
   wrapper.style.height = `${physicalHeight}px`;
-  canvas.setViewportTransform([zoom, 0, 0, zoom, 0, 0]);
+  canvas.setViewportTransform([zoomMultiplier, 0, 0, zoomMultiplier, 0, 0]);
   canvas.requestRenderAll();
 };
 
-const focusTextbox = (
-  fCanvas: fabric.Canvas,
-  textbox: fabric.Textbox,
-  readOnly: boolean,
+// to find the maximum height of the content to dynamically resize the canvas
+// would've been wayyy easier only if canvas supported fit-content like CSS property :)
+const measureLogicalContentHeight = (
+  canvas: fabric.Canvas,
+  minimumHeight = DEFAULT_LOGICAL_HEIGHT,
 ) => {
-  if (readOnly) return;
+  const maxBottom = canvas.getObjects().reduce((maxHeight, currObj) => {
+    const top = currObj.top;
+    const height = currObj.getScaledHeight();
+    return Math.max(maxHeight, top + height);
+  }, 0);
 
-  fCanvas.setActiveObject(textbox);
-  textbox.enterEditing();
-
-  const end = textbox.text?.length ?? 0;
-  textbox.selectionStart = end;
-  textbox.selectionEnd = end;
-
-  fCanvas.requestRenderAll();
-  fixFabricA11y();
+  return Math.max(minimumHeight, maxBottom + PAD);
 };
 
-const findMainTextbox = (canvas: fabric.Canvas): fabric.Textbox | null => {
-  const textbox = canvas.getObjects("Textbox")[0];
+const DEFAULT_INIT_TEXT = "Take a deep breath...";
 
-  return (textbox as fabric.Textbox) ?? null;
-};
+interface ComposeCanvasProps {
+  readOnly?: boolean;
+  initialData?: CanvasJSON | null;
+  style?: CanvasStyle;
+  ref?: React.Ref<CanvasTools>;
+}
 
-export const ComposeCanvas = forwardRef<
-  CanvasTools,
-  { readOnly?: boolean; initialData?: CanvasJSON | null }
->(({ readOnly = false, initialData = null }, ref) => {
+export function ComposeCanvas({
+  readOnly = false,
+  initialData = null,
+  style,
+  ref,
+}: ComposeCanvasProps) {
+  // wrapper is the parent div box
   const wrapperRef = useRef<HTMLDivElement>(null);
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const fabricRef = useRef<fabric.Canvas | null>(null);
+
   const textboxRef = useRef<fabric.Textbox | null>(null);
   const deferredDataRef = useRef<CanvasJSON | null>(null);
   const logicalSizeRef = useRef({
@@ -206,8 +119,16 @@ export const ComposeCanvas = forwardRef<
     height: DEFAULT_LOGICAL_HEIGHT,
   });
 
+  // re-calculates height based on content and applies the zoom transform
   const syncViewport = useCallback(() => {
     if (!(fabricRef.current && wrapperRef.current)) return;
+    textboxRef.current?.initDimensions();
+
+    const minHeight = initialData?.canvasHeight ?? DEFAULT_LOGICAL_HEIGHT;
+    logicalSizeRef.current.height = measureLogicalContentHeight(
+      fabricRef.current,
+      minHeight,
+    );
 
     applyResponsiveViewport(
       fabricRef.current,
@@ -215,177 +136,206 @@ export const ComposeCanvas = forwardRef<
       logicalSizeRef.current.width,
       logicalSizeRef.current.height,
     );
-  }, []);
 
-  const updateLogicalHeightFromContent = useCallback(() => {
-    if (!fabricRef.current) return;
+    fabricRef.current.requestRenderAll();
+  }, [initialData]);
 
-    logicalSizeRef.current.height = measureLogicalContentHeight(
-      fabricRef.current,
-      logicalSizeRef.current.height,
-    );
+  // auto focus the cursor into the main textbox no matter the latest element added
+  const focusTextbox = useCallback(
+    (textbox: fabric.Textbox) => {
+      if (readOnly || !fabricRef.current) return;
 
-    syncViewport();
-  }, [syncViewport]);
+      fabricRef.current.setActiveObject(textbox);
+      textbox.enterEditing();
 
-  const setupTextboxInteractions = useCallback(
-    (fCanvas: fabric.Canvas, textbox: fabric.Textbox) => {
-      textbox.on("changed", () => {
-        updateLogicalHeightFromContent();
-      });
+      // move the cursor to the end of the text
+      const textLength = textbox.text?.length ?? 0;
+      textbox.selectionStart = textLength;
+      textbox.selectionEnd = textLength;
 
-      fCanvas.on("mouse:down", (opt) => {
-        if (!opt.target || opt.target === textbox) {
-          focusTextbox(fCanvas, textbox, readOnly);
-        }
-      });
-
-      if (!readOnly) {
-        setTimeout(() => {
-          focusTextbox(fCanvas, textbox, readOnly);
-        }, 200);
-      }
-    },
-    [readOnly, updateLogicalHeightFromContent],
-  );
-
-  const loadContent = useCallback(
-    async (
-      canvas: fabric.Canvas,
-      data: CanvasJSON | null,
-      wrapper: HTMLDivElement,
-    ): Promise<fabric.Textbox | null> => {
-      const logicalSize = getLogicalSize(data);
-      logicalSizeRef.current = logicalSize;
-
-      canvas.clear();
-
-      let textbox: fabric.Textbox | null = null;
-
-      if (data?.objects?.length) {
-        await canvas.loadFromJSON(data);
-        textbox = findMainTextbox(canvas);
-      } else {
-        textbox = createMainTextbox("Take a deep breath...", readOnly);
-        canvas.add(textbox);
-      }
-
-      if (!textbox) return null;
-
-      textbox.selectable = !readOnly;
-      textbox.evented = !readOnly;
-      textbox.editable = !readOnly;
-      textbox.hasBorders = false;
-      textbox.lockMovementX = true;
-      textbox.lockMovementY = true;
-      textbox.lockScalingX = true;
-      textbox.lockScalingY = true;
-      textbox.lockRotation = true;
-      textbox.objectCaching = false;
-
-      logicalSizeRef.current.height = measureLogicalContentHeight(
-        canvas,
-        logicalSize.height,
-      );
-
-      applyResponsiveViewport(
-        canvas,
-        wrapper,
-        logicalSizeRef.current.width,
-        logicalSizeRef.current.height,
-      );
-
-      if (!(readOnly || data)) {
-        focusTextbox(canvas, textbox, readOnly);
-      }
-
-      return textbox;
+      fabricRef.current.requestRenderAll();
     },
     [readOnly],
   );
 
+  const loadContent = useCallback(
+    async (data: CanvasJSON | null) => {
+      const canvas = fabricRef.current;
+      const wrapper = wrapperRef.current;
+      if (!(canvas && wrapper)) return;
+
+      // clean the canvas everytime and set fresh
+      canvas.clear();
+      let textbox: fabric.Textbox | null = null;
+
+      // restore logical size from prev saved data if available (in case of existing letter)
+      logicalSizeRef.current = {
+        width: data?.canvasWidth ?? BASE_WIDTH,
+        height: data?.canvasHeight ?? DEFAULT_LOGICAL_HEIGHT,
+      };
+
+      if (data?.objects?.length) {
+        await canvas.loadFromJSON(data);
+        textbox = canvas.getObjects("Textbox")[0] as fabric.Textbox;
+      } else {
+        // Create a fresh letter if no data exists
+        textbox = new fabric.Textbox(DEFAULT_INIT_TEXT, {
+          name: "main-textbox",
+          originX: "left",
+          originY: "top",
+          left: PAD,
+          top: PAD,
+          width: BASE_WIDTH - PAD * 2,
+          fontSize: 18,
+          fontWeight: 500,
+          fontFamily: DEFAULT_FONT_FAMILY,
+          fill: DEFAULT_FONT_COLOR,
+          lineHeight: 1.5,
+          splitByGrapheme: false,
+          lockMovementX: true,
+          lockMovementY: true,
+          lockScalingX: true,
+          lockScalingY: true,
+          lockRotation: true,
+          hasControls: false,
+          hasBorders: false,
+          objectCaching: false,
+          noScaleCache: false,
+        });
+        canvas.add(textbox);
+      }
+
+      if (!textbox) return;
+
+      // readonly contraints applicable for post seal view
+      textbox.selectable = !readOnly;
+      textbox.evented = !readOnly;
+      textbox.editable = !readOnly;
+      textbox.hasBorders = false;
+
+      textboxRef.current = textbox;
+
+      // observe and auto-resize the canvas height whenever typed
+      textbox.on("changed", syncViewport);
+
+      // trapping the focus into the textbox wherever clicked on canvas (except images)
+      canvas.on("mouse:down", (e) => {
+        if (!e.target || e.target === textbox) {
+          focusTextbox(textbox);
+        }
+      });
+
+      for (const img of canvas.getObjects("Image")) {
+        img.set({
+          hasControls: !readOnly,
+          hasBorders: !readOnly,
+        });
+      }
+
+      // NOTE: fabric refreshes fonts once the textbox is rendered after initial focus
+      await document.fonts.ready;
+      textbox.set("dirty", true);
+      syncViewport();
+
+      // Hack: Fabric needs a small initial delay to mount before it will accept focus.
+      // otherwise it goes to the front
+      if (!readOnly) {
+        setTimeout(() => focusTextbox(textbox), 200);
+      }
+    },
+    [readOnly, syncViewport, focusTextbox],
+  );
+
+  useEffect(() => {
+    if (style && textboxRef.current) {
+      const textBox = textboxRef.current;
+      textBox.fontFamily = style.fontFamily || textBox.fontFamily;
+      textBox.fill = style.fontColor || textBox.fill;
+      syncViewport();
+    }
+  }, [style, syncViewport]);
+
   useEffect(() => {
     let isMounted = true;
-    let canvas: fabric.Canvas | null = null;
     let resizeObserver: ResizeObserver | null = null;
     let lastWidth = 0;
 
-    const init = async () => {
-      await document.fonts.ready;
-      if (!(wrapperRef.current && canvasRef.current && isMounted)) return;
-
-      const finalWidth = await waitForLayout(wrapperRef.current);
-      if (!(isMounted && canvasRef.current && wrapperRef.current)) return;
-
-      canvas = initializeCanvas(
-        canvasRef.current,
-        finalWidth,
-        DEFAULT_LOGICAL_HEIGHT,
-        readOnly,
-      );
-
-      fabricRef.current = canvas;
-
-      const textbox = await loadContent(
-        canvas,
-        initialData,
-        wrapperRef.current,
-      );
-
-      if (textbox) {
-        textboxRef.current = textbox;
-        setupTextboxInteractions(canvas, textbox);
+    const getInitialWidth = async () => {
+      if (!wrapperRef.current) return BASE_WIDTH;
+      let width = wrapperRef.current.clientWidth;
+      if (width === 0) {
+        await new Promise((resolve) => requestAnimationFrame(resolve));
+        width = wrapperRef.current?.clientWidth || BASE_WIDTH;
       }
+      return width;
+    };
 
-      canvas.requestRenderAll();
-      fixFabricA11y();
-
-      lastWidth = wrapperRef.current.clientWidth;
-
-      resizeObserver = new ResizeObserver(() => {
-        if (!(fabricRef.current && wrapperRef.current)) return;
-
-        const nextWidth = wrapperRef.current.clientWidth;
+    const initResizeOberver = () => {
+      if (!wrapperRef.current) return null;
+      const observer = new ResizeObserver(() => {
+        const nextWidth = wrapperRef.current?.clientWidth;
         if (!nextWidth || nextWidth === lastWidth) return;
-
         lastWidth = nextWidth;
         syncViewport();
       });
-
-      resizeObserver.observe(wrapperRef.current);
-
-      if (deferredDataRef.current) {
-        const data = deferredDataRef.current;
-        deferredDataRef.current = null;
-
-        const textbox = await loadContent(canvas, data, wrapperRef.current);
-        if (textbox) {
-          textboxRef.current = textbox;
-          setupTextboxInteractions(canvas, textbox);
-        }
-
-        canvas.requestRenderAll();
-        fixFabricA11y();
-      }
+      observer.observe(wrapperRef.current);
+      return observer;
     };
 
-    init();
+    const initCanvas = async () => {
+      // HACK: actual font may change the text-width - small ux improvement
+      await document.fonts.ready;
+
+      if (!(wrapperRef.current && canvasRef.current && isMounted)) return;
+
+      const width = await getInitialWidth();
+
+      // init the fabric instance
+      const canvas = new fabric.Canvas(canvasRef.current, {
+        width,
+        height: DEFAULT_LOGICAL_HEIGHT,
+        selection: !readOnly,
+        preserveObjectStacking: true,
+        allowTouchScrolling: true,
+        enableRetinaScaling: true,
+        objectCaching: false,
+      });
+
+      // remove default fabric background to let our CSS show through
+      // TODO: provision custom bg (color in scope, but how does img fit?)
+      const wrapperEl = canvas.getElement().parentElement;
+      if (wrapperEl) wrapperEl.style.background = "transparent";
+
+      fabricRef.current = canvas;
+
+      await loadContent(initialData);
+
+      // sometimes loadData() may be called before the canvas finished the init render
+      // so we retry that stashed render right after the init
+      if (deferredDataRef.current) {
+        await loadContent(deferredDataRef.current);
+        deferredDataRef.current = null;
+      }
+
+      // auto window resizing based width
+      lastWidth = wrapperRef.current.clientWidth;
+      resizeObserver = initResizeOberver();
+    };
+
+    initCanvas().then();
 
     return () => {
       isMounted = false;
       resizeObserver?.disconnect();
-      canvas?.dispose();
+      fabricRef.current?.dispose();
       fabricRef.current = null;
       textboxRef.current = null;
     };
-  }, [
-    initialData,
-    loadContent,
-    readOnly,
-    setupTextboxInteractions,
-    syncViewport,
-  ]);
+  }, [initialData, loadContent, readOnly, syncViewport]);
 
+  // WHY?: fabric doesn't work like react with state and props based optimized re-renders.
+  // everytime we there's a change in the data, we should force the render,
+  // so we let the parent Editor component take control of this.
   useImperativeHandle(ref, () => ({
     addImage: (url: string, file: File) => {
       if (!fabricRef.current) return;
@@ -395,69 +345,39 @@ export const ComposeCanvas = forwardRef<
         img.set({
           originX: "left",
           originY: "top",
-          _customRawFile: file,
           left: PAD,
           top: PAD,
+          noScaleCache: false,
           objectCaching: false,
+          // WHY?: after image object clean-up, its src becomes local blob://
+          // but browser won't let us parse this blob:// into file afterwards. so we hold a local copy
+          _customRawFile: file,
         } as Partial<FabricImageWithFile>);
 
         fabricRef.current?.add(img);
         fabricRef.current?.setActiveObject(img);
 
-        if (!fabricRef.current) return;
-
-        logicalSizeRef.current.height = measureLogicalContentHeight(
-          fabricRef.current,
-          logicalSizeRef.current.height,
-        );
-
-        if (wrapperRef.current) {
-          applyResponsiveViewport(
-            fabricRef.current,
-            wrapperRef.current,
-            logicalSizeRef.current.width,
-            logicalSizeRef.current.height,
-          );
-        } else {
-          fabricRef.current?.requestRenderAll();
-        }
-
+        syncViewport();
+        // clean up memory
         URL.revokeObjectURL(url);
       });
     },
 
     getData: () => {
       if (!fabricRef.current) return { objects: [] };
-
-      logicalSizeRef.current.height = measureLogicalContentHeight(
-        fabricRef.current,
-        logicalSizeRef.current.height,
-      );
+      syncViewport();
 
       const json = fabricRef.current.toJSON() as CanvasJSON;
       json.canvasWidth = logicalSizeRef.current.width;
       json.canvasHeight = logicalSizeRef.current.height;
-
       return json;
     },
 
-    getJsonData: () => {
-      if (!fabricRef.current) return "";
-
-      const json = fabricRef.current.toJSON() as CanvasJSON;
-      json.canvasWidth = logicalSizeRef.current.width;
-      json.canvasHeight = logicalSizeRef.current.height;
-
-      return JSON.stringify(json);
-    },
-
     getImages: () => {
       if (!fabricRef.current) return [];
-
       const images = fabricRef.current.getObjects(
         "Image",
       ) as FabricImageWithFile[];
-
       return images.map((img) => ({
         src: img.getSrc(),
         file: img._customRawFile,
@@ -465,24 +385,21 @@ export const ComposeCanvas = forwardRef<
     },
 
     loadData: async (data: CanvasJSON) => {
-      if (!(fabricRef.current && wrapperRef.current)) {
+      // if canvas isn't ready yet, stash the data and let the useEffect pick it up
+      if (!fabricRef.current) {
         deferredDataRef.current = data;
         return;
       }
+      await loadContent(data);
+    },
 
-      const textbox = await loadContent(
-        fabricRef.current,
-        data,
-        wrapperRef.current,
-      );
+    getStyle: () => {
+      const textBox = textboxRef.current;
 
-      if (textbox) {
-        textboxRef.current = textbox;
-        setupTextboxInteractions(fabricRef.current, textbox);
-      }
-
-      fabricRef.current.requestRenderAll();
-      fixFabricA11y();
+      return {
+        fontFamily: textBox?.fontFamily || DEFAULT_FONT_FAMILY,
+        fontColor: (textBox?.fill as string) || DEFAULT_FONT_COLOR,
+      };
     },
   }));
 
@@ -498,6 +415,6 @@ export const ComposeCanvas = forwardRef<
       />
     </div>
   );
-});
+}
 
 ComposeCanvas.displayName = "ComposeCanvas";

frontend/src/components/editor/PostSealModal.tsx

@@ -1,54 +1,88 @@
 import { LockIcon } from "@phosphor-icons/react";
 import type { NavigateFunction } from "react-router-dom";
 import { PATHS, ROUTES } from "../../config/routes";
+import { Modal } from "../ui/Modal";
 
 interface PostSealModalProps {
   sealedTargetId: string | null;
   navigate: NavigateFunction;
+  type: "KEPT" | "VAULT";
 }
 
 export function PostSealModal({
   sealedTargetId,
   navigate,
+  type = "KEPT",
 }: PostSealModalProps) {
-  if (!sealedTargetId) return null;
   return (
-    <div className="modal modal-open modal-middle bg-base-100/20 backdrop-blur-md z-1000">
-      <div className="modal-box flex flex-col items-center text-center gap-6">
-        <LockIcon size={32} weight="duotone" className="text-primary mt-3" />
-        <h3 className="font-serif text-2xl">Your letter is sealed</h3>
-        <p className="text-base-content/60">
-          It's encrypted and always safe in your drawer.
-        </p>
-        <p className="text-base-content font-sans">
+    <Modal isOpen={!!sealedTargetId} data-testid="post-seal-modal">
+      <LockIcon size={32} weight="duotone" className="text-primary mt-3" />
+      <h3 className="font-serif text-2xl">Your letter is sealed</h3>
+      <p className="text-base-content/60">
+        It's encrypted and always safe in your drawer.
+      </p>
+      {type === "KEPT" ? (
+        <p className="text-base-content/80 text-sm font-sans">
           When you're ready,
           <br />
-          you can{" "}
-          <span className="text-primary font-bold font-display">read</span> it,{" "}
+          you can&nbsp;
+          <span className="text-primary font-bold font-display">read</span>
+          &nbsp; it,&nbsp;
           <span className="text-accent font-bold font-display">send</span> it to
-          someone, or{" "}
+          someone, or&nbsp;
           <span className="text-error font-bold font-display">burn</span> it to
           release
         </p>
-        <div className="modal-action w-full justify-center gap-3 mt-4 mb-4">
+      ) : (
+        <p className="text-base-content/80 text-sm font-sans">
+          Be assured that the letter will find you when the time is right.
+          <br />
+          Till then,&nbsp;
+          <span className="font-bold font-display text-primary">
+            take a deep breath
+          </span>
+          , <span className="font-bold font-display text-accent">manifest</span>
+          , and&nbsp;
+          <span className="font-bold font-display text-success">
+            let it rest
+          </span>
+          .
+        </p>
+      )}
+      <div className="modal-action w-full justify-center gap-3 mt-4 mb-4">
+        {type === "KEPT" ? (
+          <>
+            <button
+              type="button"
+              data-testid="keep-it-btn"
+              className="btn btn-ghost btn-sm"
+              onClick={() => navigate(ROUTES.DRAWER)}
+            >
+              Keep it to myself
+            </button>
+            <button
+              type="button"
+              data-testid="view-letter-btn"
+              className="btn btn-primary btn-sm"
+              onClick={() => {
+                if (sealedTargetId) {
+                  navigate(PATHS.read(sealedTargetId));
+                }
+              }}
+            >
+              View letter
+            </button>
+          </>
+        ) : (
           <button
             type="button"
             className="btn btn-ghost btn-sm"
             onClick={() => navigate(ROUTES.DRAWER)}
           >
-            Keep it to myself
+            Step Away...
           </button>
-          <button
-            type="button"
-            className="btn btn-primary btn-sm"
-            onClick={() =>
-              navigate(PATHS.read(sealedTargetId), { replace: true })
-            }
-          >
-            View letter
-          </button>
-        </div>
+        )}
       </div>
-    </div>
+    </Modal>
   );
 }

frontend/src/components/editor/ToolBar.tsx

@@ -1,49 +1,147 @@
 import {
+  CircleHalfTiltIcon,
   ImageIcon,
   LockIcon,
+  PaintBucketIcon,
   QuestionIcon,
   StampIcon,
+  TextAUnderlineIcon,
   TrayIcon,
   VaultIcon,
+  XCircleIcon,
 } from "@phosphor-icons/react";
+import { Modal } from "../ui/Modal";
+import type { CanvasStyle } from "./ComposeCanvas";
 
 interface ToolBarProps {
-  fileInputRef: React.RefObject<HTMLInputElement | null>;
+  onAddImage: () => void;
   sealBtnClicked: boolean;
   setSealBtnClicked: (v: boolean) => void;
   onSave: (status: "SEALED" | "DRAFT" | "VAULT", date?: Date) => Promise<void>;
   setConfirmModal: (v: "VAULT" | "SEAL" | null) => void;
+  onFontChange: (style: CanvasStyle) => void;
+  latestFontStyle: CanvasStyle;
 }
 
+const FONT_FAMILIES: Map<string, string> = new Map([
+  ["Serif", "Playfair Display Variable"],
+  ["Sans", "Jost Variable"],
+  ["Cursive", "Playwrite HR Lijeva Variable"],
+  ["Handwriting", "Architects Daughter"],
+  ["Slab", "Cutive Mono"],
+  ["Mono", "Space Mono"],
+  ["Ink", "Kavivanar"],
+  ["Crazy(pls no)", "Redacted Script"],
+]);
+const FONT_COLORS: Map<string, string> = new Map([
+  ["Black", "#000"],
+  ["Gold", "#866a0e"],
+  ["Purple", "#711caf"],
+  ["Green", "#1f5b1f"],
+  ["Blue", "#111e67"],
+]);
+
 export function ToolBar({
-  fileInputRef,
+  onAddImage,
   sealBtnClicked,
   setSealBtnClicked,
   onSave,
   setConfirmModal,
+  onFontChange,
+  latestFontStyle,
 }: ToolBarProps) {
   return (
     <div
       id="writer-toolbar"
-      className="flex items-center justify-between mb-8 h-14 bg-base-100/50 backdrop-blur-md rounded-full border border-base-content/5 px-6"
+      className="relative z-10 flex items-center justify-between mb-8 h-14 bg-base-100/50 backdrop-blur-md rounded-full border border-base-content/5 px-6"
     >
       <div className="flex gap-4">
+        {/* Image upload */}
         <button
           type="button"
           className="btn btn-ghost btn-sm group"
-          onClick={() => fileInputRef.current?.click()}
+          onClick={onAddImage}
         >
           <ImageIcon size={18} weight="bold" />
           <span className="hidden md:inline group-hover:inline transition-all duration-1000">
             Add Image
           </span>
         </button>
+        <div className="w-px h-4 bg-base-content/10 mx-2 my-auto hidden md:inline" />
+
+        {/* Font Family */}
+        <div className={"flex items-center gap-2 group"}>
+          <TextAUnderlineIcon
+            size={24}
+            weight="bold"
+            className={"hidden md:inline"}
+          />
+          <select
+            className="select select-sm"
+            onChange={(e) => {
+              onFontChange({ ...latestFontStyle, fontFamily: e.target.value });
+            }}
+            value={latestFontStyle.fontFamily}
+          >
+            {Array.from(FONT_FAMILIES.entries()).map(
+              ([fontFamily, fontName]) => {
+                return (
+                  <option key={fontName} value={fontName}>
+                    {fontFamily}
+                  </option>
+                );
+              },
+            )}
+          </select>
+        </div>
+        <div className="w-px h-4 bg-base-content/10 mx-2 my-auto hidden md:inline" />
+
+        {/* Font Color */}
+        <div className="dropdown dropdown-bottom flex items-center gap-2 group">
+          <PaintBucketIcon
+            size={16}
+            weight="bold"
+            className={"hidden md:flex"}
+          />
+          <button
+            className="btn btn-ghost btn-sm px-2 gap-2 flex items-center"
+            type={"button"}
+          >
+            <CircleHalfTiltIcon
+              size={18}
+              style={{ color: latestFontStyle.fontColor }}
+              weight="duotone"
+            />
+          </button>
+          <ul className="dropdown-content z-50 menu p-2 shadow bg-base-200/95 rounded-full md:ml-4">
+            {Array.from(FONT_COLORS.entries()).map(([_, colorCode]) => (
+              <li key={colorCode}>
+                <button
+                  type="button"
+                  className={`${latestFontStyle.fontColor === colorCode ? "active" : ""}`}
+                  onClick={() => {
+                    onFontChange({ ...latestFontStyle, fontColor: colorCode });
+                    (document.activeElement as HTMLButtonElement)?.blur();
+                  }}
+                >
+                  <CircleHalfTiltIcon
+                    size={18}
+                    style={{ color: colorCode }}
+                    weight="fill"
+                  />
+                </button>
+              </li>
+            ))}
+          </ul>
+        </div>
       </div>
 
+      {/* Draft */}
       <div className="flex items-center gap-2">
         <button
           type="button"
-          className="btn btn-ghost btn-sm text-[10px] group tracking-[0.2em] uppercase font-bold text-base-content/60 hover:text-base-content"
+          data-testid="draft-btn"
+          className="btn btn-ghost btn-sm text-xxs group tracking-widester uppercase font-bold text-base-content/60 hover:text-base-content"
           title="Store in your private drawer"
           onClick={() => onSave("DRAFT")}
         >
@@ -53,10 +151,12 @@ export function ToolBar({
           </span>
         </button>
 
-        <div className="w-px h-4 bg-base-content/10 mx-2" />
+        <div className="w-px h-4 bg-base-content/10 mx-2 hidden md:inline" />
 
+        {/*Seal */}
         <button
           type="button"
+          data-testid="seal-trigger-btn"
           className={`btn btn-primary btn-sm rounded-full px-6 group ${sealBtnClicked ? "invisible" : "visible"}`}
           onClick={() => setSealBtnClicked(true)}
         >
@@ -74,10 +174,11 @@ export function ToolBar({
       </div>
 
       <div
-        className={`flex-col items-center gap-2 absolute right-0 z-100000 bg-primary/20 rounded-full p-8 -m-2 ${sealBtnClicked ? "" : "hidden"}`}
+        className={`flex-col items-center gap-2 absolute right-0 z-10 bg-primary/20 rounded-full p-8 -m-2 ${sealBtnClicked ? "" : "hidden"}`}
       >
         <button
           type="button"
+          data-testid="seal-confirm-btn"
           className="btn btn-accent btn-sm rounded-full px-6 group"
           onClick={() => onSave("SEALED")}
         >
@@ -93,6 +194,7 @@ export function ToolBar({
         </div>
         <button
           type="button"
+          data-testid="vault-trigger-btn"
           className="btn btn-neutral btn-sm rounded-full px-6 group"
           onClick={() => setConfirmModal("VAULT")}
         >
@@ -101,11 +203,31 @@ export function ToolBar({
         </button>
       </div>
       <button
+        className={`z-100001 absolute right-0 bg-transparent cursor-pointer ${sealBtnClicked ? "" : "hidden"}`}
         type="button"
         onClick={() => setSealBtnClicked(false)}
-        className={`bg-transparent cursor-pointer -mt-2 absolute z-1000001 right-0 text-primary  ${sealBtnClicked ? "" : "hidden"}`}
       >
-        <QuestionIcon weight="duotone" size={20} className={""} />
+        <XCircleIcon weight="duotone" size={20} className={"text-error"} />
+      </button>
+      <button
+        type="button"
+        aria-label="Help"
+        className={`bg-transparent cursor-pointer -mt-2 absolute z-100001 right-0 text-primary  ${sealBtnClicked ? "" : "hidden"}`}
+      >
+        <div className="tooltip tooltip-left">
+          <div className="tooltip-content -translate-x-38 text-left">
+            <span className="font-bold text-accent">Seal</span> puts the letter
+            in an envelope, ready to be read right away.
+            <div className="divider my-0"></div>
+            <span className="font-bold text-success">Vault</span> keeps it
+            locked away until the right moment, even from yourself.
+          </div>
+          <QuestionIcon
+            weight="duotone"
+            size={20}
+            className={"absolute -translate-x-38 -translate-y-3"}
+          />
+        </div>
       </button>
     </div>
   );
@@ -116,7 +238,7 @@ export function LetterHead() {
     <div className="flex items-center justify-center mb-8 h-14">
       <div className="badge badge-outline border-primary/20 bg-primary/5 text-primary gap-2 p-4 rounded-full">
         <LockIcon size={14} weight="fill" />
-        <span className="text-[10px] uppercase tracking-widest font-bold">
+        <span className="text-xxs uppercase tracking-widest font-bold">
           Sealed & View Only
         </span>
       </div>
@@ -136,60 +258,63 @@ export function VaultConfirmModal({
   setUnlockDate,
 }: VaultConfirmModalProps) {
   return (
-    <div className={"modal modal-open bg-base-100/20 backdrop-blur-md"}>
-      <div className="modal-box p-12 flex flex-col items-center">
-        <VaultIcon
-          size={48}
-          className="text-primary mx-auto mb-8 animate-pulse"
+    <Modal isOpen={true}>
+      <VaultIcon
+        size={48}
+        className="text-primary mx-auto mb-8 animate-pulse"
+      />
+      <h3 className="font-serif text-3xl">Take it away, then?</h3>
+      <p className="text-base-content/60 text-sm text-center mt-4">
+        By vaulting this letter, you ask me to hold on to this.
+        <br />
+        I'll remember to mail you this on the unlock date.
+        <br />
+        <span className={"font-bold text-primary"}>
+          &nbsp; But I won't let you read or rewrite this letter until then.
+        </span>
+        <br />
+      </p>
+      <form
+        onSubmit={async (e) => {
+          e.preventDefault();
+          const formData = new FormData(e.currentTarget);
+          const unlockDateStr = formData.get("vault-date") as string;
+          const newUnlockDate = new Date(unlockDateStr);
+          setUnlockDate(newUnlockDate);
+          await onSave("VAULT", newUnlockDate);
+          setConfirmModal(null);
+        }}
+        id="vault-form"
+        className="min-w-75"
+      >
+        <div className={"divider tracking-tightest font-display text-sm"}>
+          Set an unlock date
+        </div>
+        <input
+          required
+          type="date"
+          className="input input-bordered w-full"
+          name="vault-date"
         />
-        <h3 className="font-serif text-3xl">Vault this letter?</h3>
-        <p className="text-base-content/60 text-sm text-center mt-4">
-          Vaulting locks the letter permanently and will be{" "}
-          <span className={"font-bold text-primary"}>mailed</span> to you
-          automatically on the unlock date.
-          <br />
-          <span className={"underline"}>
-            You cannot edit or view the contents of the letter until then.
-          </span>
-        </p>
-        <form
-          onSubmit={async (e) => {
-            e.preventDefault();
-            const formData = new FormData(e.currentTarget);
-            const unlockDateStr = formData.get("vault-date") as string;
-            const newUnlockDate = new Date(unlockDateStr);
-            setUnlockDate(newUnlockDate);
-            await onSave("VAULT", newUnlockDate);
-            setConfirmModal(null);
-          }}
-          id="vault-form"
-        >
-          <div className={"divider tracking-tightest font-display text-sm"}>
-            Set an unlock date
-          </div>
-          <input
-            required
-            type="date"
-            className="input input-bordered w-full"
-            name="vault-date"
-          />
-          <button
-            className="btn btn-primary mt-4"
-            type="submit"
-            form="vault-form"
-          >
-            Vault
-          </button>
-
+        <div className="w-full flex justify-center gap-8 mt-4">
           <button
             type="button"
-            className="btn btn-ghost mt-4"
+            data-testid="vault-cancel-btn"
+            className="btn btn-ghost btn-sm mt-4"
             onClick={() => setConfirmModal(null)}
           >
-            Cancel
+            I need time
           </button>
-        </form>
-      </div>
-    </div>
+          <button
+            className="btn btn-primary btn-sm mt-4"
+            type="submit"
+            data-testid="vault-confirm-btn"
+            form="vault-form"
+          >
+            Take it
+          </button>
+        </div>
+      </form>
+    </Modal>
   );
 }

frontend/src/components/login/WelcomeModal.tsx

@@ -0,0 +1,87 @@
+import {
+  HandPalmIcon,
+  ShieldCheckIcon,
+  WarningIcon,
+} from "@phosphor-icons/react";
+import Logo from "../Logo";
+import { Modal } from "../ui/Modal";
+import Saajan from "../ui/Saajan";
+
+export default function WelcomeModal({
+  setShowWelcome,
+}: {
+  setShowWelcome: (show: boolean) => void;
+}) {
+  return (
+    <>
+      <Modal isOpen={true}>
+        <div className="flex flex-col items-center text-center gap-2 md:gap-4">
+          <div className="bg-primary/10 p-4 rounded-full animate-pulse">
+            <ShieldCheckIcon
+              size={48}
+              weight="duotone"
+              className="text-primary"
+            />
+          </div>
+          <h3 className="font-display text-2xl font-bold text-primary">
+            Welcome to&nbsp;
+            <Logo type="inline" />
+          </h3>
+          <p className="inline text-sm md:text-base text-base-content/80">
+            Before we begin, let me make a small promise.
+            <HandPalmIcon
+              size={18}
+              className="inline text-primary"
+              weight="fill"
+            />
+            <span className="divider my-0"></span>
+            Everything you write here is sealed with your password,&nbsp;
+            <span className="font-display text-success">cryptographically</span>
+            , before it leaves your hands.
+            <br />
+            <br />A fancy way of saying, no one else can read them without your
+            key&mdash;not even me.
+          </p>
+
+          <div className="alert alert-warning flex items-start gap-3 text-left py-3">
+            <WarningIcon size={24} weight="fill" className="shrink-0" />
+            <div className="text-xs md:text-sm font-medium text-primary-content tracking-tight">
+              If you ever happen to forget your password, your letters are lost
+              to time, forever.
+              <span className="mt-2 block">
+                I highly, <span className="font-bold italic">highly</span>&nbsp;
+                recommend storing this password in your&nbsp;
+                <a
+                  href="https://www.privacyguides.org/en/passwords/"
+                  target="_blank"
+                  className="link link-neutral!"
+                  rel="noopener noreferrer"
+                >
+                  password manager
+                </a>
+                &nbsp; or somewhere safe to remember it.
+              </span>
+            </div>
+          </div>
+
+          <div className="modal-action w-full">
+            <button
+              type="button"
+              data-testid="welcome-dismiss-btn"
+              onClick={() => setShowWelcome(false)}
+              className="btn btn-primary w-full shadow-lg"
+            >
+              I'll remember
+            </button>
+          </div>
+        </div>
+      </Modal>
+      <div className="absolute bottom-0 md:right-5/12 z-1000 font-sans w-full flex justify-center">
+        <Saajan
+          position="left"
+          message={"I've lost words before.\nI know what it feels like."}
+        />
+      </div>
+    </>
+  );
+}

frontend/src/components/reader/BurnModal.tsx

@@ -1,19 +1,27 @@
-import { CampfireIcon, FlameIcon, XCircleIcon } from "@phosphor-icons/react";
+import { CampfireIcon, FlameIcon } from "@phosphor-icons/react";
 import { useEffect, useState } from "react";
+import { Modal } from "../ui/Modal";
+
+interface BurnModalProps {
+  burnLetter: () => void;
+  isBurning: boolean;
+  setShowBurnModal: (show: boolean) => void;
+  setRevealState: (state: "SEALED" | "REVEALED" | "BURNING" | "BURNED") => void;
+}
 
 export function BurnModal({
   burnLetter,
   isBurning,
   setShowBurnModal,
   setRevealState,
-}) {
+}: BurnModalProps) {
   const [flameOn, setFlameOn] = useState(0);
   const [rotate, setRotate] = useState(0);
   const [burnClicked, setBurnClicked] = useState(false);
   useEffect(() => {
     if (!burnClicked) return;
     if (flameOn === 100) {
-      setRevealState("sealed");
+      setRevealState("SEALED");
       burnLetter();
     }
     const interval = setInterval(() => {
@@ -26,23 +34,15 @@ export function BurnModal({
   const burnStyle = flameOn < 30 ? "" : `contrast(${flameOn / 30})`;
 
   return (
-    <div className="modal modal-open modal-middle bg-base-100/20 backdrop-blur-md">
+    <Modal isOpen={true} onClose={() => setShowBurnModal(false)}>
       <div
-        className={`modal-box flex flex-col items-center gap-4 py-8 text-center transition-all duration-200 ease-in-out ${burnClicked ? "animate-[pulse_15s_linear_infinite]" : ""}`}
+        className={`flex flex-col items-center gap-4 text-center transition-all duration-200 ease-in-out ${burnClicked ? "animate-[pulse_15s_linear_infinite]" : ""}`}
         style={
           {
             transform: `rotate(${rotate}deg)`,
           } as React.CSSProperties
         }
       >
-        <button
-          type="button"
-          className="btn btn-sm btn-circle btn-ghost absolute right-2 top-2"
-          onClick={() => setShowBurnModal(false)}
-          aria-label="Close"
-        >
-          <XCircleIcon size={18} weight="bold" />
-        </button>
         <CampfireIcon
           size={48}
           weight="duotone"
@@ -58,8 +58,8 @@ export function BurnModal({
           Let the echoes of your unsaid be finally released.
         </p>
         <div className="mt-4 font-sans text-sm">
-          <span className="text-error">Press</span> and{" "}
-          <span className="text-error">hold</span> the{" "}
+          <span className="text-error">Press</span> and&nbsp;
+          <span className="text-error">hold</span> the&nbsp;
           <span className="text-amber-300">flame</span> to proceed.
         </div>
         <div className="modal-action w-full justify-center gap-3 mt-2">
@@ -94,6 +94,6 @@ export function BurnModal({
           </button>
         </div>
       </div>
-    </div>
+    </Modal>
   );
 }

frontend/src/components/reader/EnvelopeReveal.tsx

@@ -1,5 +1,6 @@
 import { WavesIcon } from "@phosphor-icons/react";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useState } from "react";
+import candle from "../../assets/envelope/candle.png";
 import stamp from "../../assets/envelope/stamp.png";
 import waxSeal from "../../assets/envelope/waxSeal.png";
 
@@ -9,6 +10,8 @@ export interface EnvelopeRevealProps {
   onRevealComplete: () => void;
   ignite: boolean;
   isFlip?: boolean;
+  isInteractive?: boolean;
+  openFlap?: boolean;
 }
 
 export function EnvelopeReveal({
@@ -17,9 +20,12 @@ export function EnvelopeReveal({
   onRevealComplete,
   ignite,
   isFlip,
+  isInteractive = true,
+  openFlap = false,
 }: EnvelopeRevealProps) {
   const [revealLetter, setRevealLetter] = useState(false);
   const [isFlipped, setIsFlipped] = useState(!!isFlip);
+  const [isFlapOpen, setIsFlapOpen] = useState(!!openFlap);
 
   useEffect(() => {
     setIsFlipped(!!isFlip);
@@ -30,7 +36,9 @@ export function EnvelopeReveal({
     height: 0,
   });
 
-  const flapCheckbox = useRef<HTMLInputElement>(null);
+  useEffect(() => {
+    setIsFlapOpen(openFlap);
+  }, [openFlap]);
 
   useEffect(() => {
     if (!ignite) {
@@ -66,21 +74,25 @@ export function EnvelopeReveal({
             <input
               type="checkbox"
               className="transition checkbox absolute h-full w-full text-transparent bg-transparent z-100"
-              ref={flapCheckbox}
+              checked={isFlapOpen}
+              onChange={() => setIsFlapOpen((prev) => !prev)}
+              disabled={!isInteractive}
             />
           </div>
           <img
+            data-testid="wax-seal"
             className={
               "translate-y-24 delay-2000 absolute z-6 peer-has-checked:pointer-events-none peer-has-checked:opacity-0 peer-has-checked:delay-0 transition-opacity duration-1000 cursor-pointer"
             }
             src={waxSeal}
             alt="Seal"
-            onClick={() => flapCheckbox.current?.click()}
-            onKeyDown={() => flapCheckbox.current?.click()}
+            onClick={() => setIsFlapOpen((prev) => !prev)}
+            onKeyDown={() => setIsFlapOpen((prev) => !prev)}
           />
           <button
             type="button"
             id="letter"
+            data-testid="envelope-letter"
             className={`absolute mx-auto transition-all peer-has-checked:delay-800 peer-has-checked:duration-1000 duration-1000 mt-2 h-55 w-105 bg-paper peer-has-checked:-mt-12 hover:-mt-24 cursor-pointer ${revealLetter ? "duration-1000 peer-has-checked:duration-3000 w-screen max-w-4xl h-screen z-101 -translate-y-90" : "peer-has-checked:z-1"}`}
             onClick={handleClick}
           ></button>
@@ -102,14 +114,21 @@ export function EnvelopeReveal({
 
         <button
           id="env-front"
+          data-testid="envelope-front"
           type="button"
+          disabled={!isInteractive}
           className={`text-left p-10 absolute inset-0 backface-hidden w-110 bg-base-200 z-99 rounded-md -translate-x-2 ${isFlipped ? "pointer-events-none" : ""}`}
           onClick={() => setIsFlipped((prev) => !prev)}
         >
           <span className={"text-neutral-content/60 font-xs font-display"}>
             to
           </span>
-          <h1 className="text-3xl font-bold text-base-content">{recipient}</h1>
+          <h1
+            data-testid="envelope-recipient"
+            className="text-3xl font-bold text-base-content"
+          >
+            {recipient}
+          </h1>
           <p className="text-base-content/60 font-display mt-8">{date}</p>
           <img
             src={stamp}
@@ -129,15 +148,20 @@ export function EnvelopeReveal({
         </button>
       </div>
       {ignite && (
-        <div className="absolute w-115 h-70 z-100 overflow-hidden flex align-baseline -translate-y-70 -translate-x-5">
-          <div
-            className="absolute z-1000 border-2 border-amber-200 -bottom-3 -right-3 w-0 h-0  transition-all duration-500 bg-base-100 rounded-tl-full rounded-bl-full origin-bottom-right"
-            style={{
-              width: 2 * burn.width,
-              height: 2 * burn.height,
-            }}
-          ></div>
-        </div>
+        <>
+          <div className="absolute w-115 h-70 z-100 overflow-hidden flex align-baseline -translate-y-70 -translate-x-5">
+            <div
+              className="absolute z-1000 border-2 border-amber-200 -bottom-3 -right-3 w-0 h-0  transition-all duration-500 bg-base-100 rounded-tl-full rounded-bl-full origin-bottom-right"
+              style={{
+                width: 2 * burn.width,
+                height: 2 * burn.height,
+              }}
+            ></div>
+          </div>
+          <div className="absolute z-1001 bottom-0 right-0 translate-x-15 translate-y-20">
+            <img src={candle} alt="candle" />
+          </div>
+        </>
       )}
     </>
   );

frontend/src/components/reader/PostActionOverlay.tsx

@@ -1,26 +1,30 @@
 import { useNavigate } from "react-router-dom";
 import { ROUTES } from "../../config/routes";
 
-export function PostActionOverlay({ revealState }) {
+interface PostActionOverlayProps {
+  revealState: "SEALED" | "REVEALED" | "BURNING" | "BURNED";
+}
+
+export function PostActionOverlay({ revealState }: PostActionOverlayProps) {
   const navigate = useNavigate();
   return (
     <div
-      className={`flex flex-col items-center justify-center min-h-screen bg-base-100 ${revealState === "burned" ? "opacity-100" : "opacity-0"} transition-all delay-300 duration-1000`}
+      className={`flex flex-col items-center justify-center min-h-screen bg-base-100 ${revealState === "BURNED" ? "opacity-100" : "opacity-0"} transition-all delay-1000 duration-1000`}
     >
       <h1
-        className={`text-6xl ${revealState === "burned" ? "opacity-100" : "opacity-0"} lg:text-9xl italic font-extralight text-base-content animate-[pulse_3s_ease-in-out_3]`}
+        className={`text-6xl ${revealState === "BURNED" ? "opacity-100" : "opacity-0"} lg:text-9xl italic font-extralight text-base-content animate-[pulse_3s_ease-in-out_3]`}
       >
         It is done
       </h1>
       <div
-        className={`text-xl ${revealState === "burned" ? "opacity-100" : "opacity-0"} lg:text-4xl text-center font-extralight text-base-content font-display mt-8 delay-3000 transition-all duration-2000 tracking-wide`}
+        className={`text-xl ${revealState === "BURNED" ? "opacity-100" : "opacity-0"} lg:text-4xl text-center font-extralight text-base-content font-display mt-8 delay-3000 transition-all duration-2000 tracking-wide`}
       >
         <p className="w-full">
           May your <span className="italic text-primary">soul</span> find
           solace,
           <br />
-          just like your <span className="text-accent italic">unsaid</span>{" "}
-          words did.
+          just like your <span className="text-accent italic">unsaid</span>
+          &nbsp; words did.
         </p>
         <div className="divider mx-auto w-24 text-center"></div>
         <button

frontend/src/components/reader/ShareModal.tsx

@@ -1,25 +1,24 @@
-import {
-  EyeSlashIcon,
-  PaperPlaneTiltIcon,
-  XCircleIcon,
-} from "@phosphor-icons/react";
+import { EyeSlashIcon, PaperPlaneTiltIcon } from "@phosphor-icons/react";
+import { Modal } from "../ui/Modal";
+import Saajan from "../ui/Saajan";
 
-export function ShareModal({ shareLink, setShareLink }) {
+interface ShareModalProps {
+  shareLink: string | null;
+  setShareLink: (link: string | null) => void;
+}
+
+export function ShareModal({ shareLink, setShareLink }: ShareModalProps) {
   const copyToClipboard = async () => {
     if (!shareLink) return;
     await navigator.clipboard.writeText(shareLink);
   };
   return (
-    <div className="modal modal-open modal-middle bg-base-100/20 backdrop-blur-md z-100">
-      <div className="modal-box bg-base-100 border border-base-content/5 shadow-2xl relative">
-        <button
-          type="button"
-          className="btn btn-sm btn-circle btn-ghost absolute right-2 top-2"
-          onClick={() => setShareLink(null)}
-          aria-label="Close"
-        >
-          <XCircleIcon size={18} weight="bold" />
-        </button>
+    <>
+      <Modal
+        isOpen={!!shareLink}
+        onClose={() => setShareLink(null)}
+        data-testid="share-letter-modal"
+      >
         <div className="flex flex-col items-center justify-center text-center gap-6 py-4">
           <div className="space-y-2">
             <PaperPlaneTiltIcon
@@ -29,14 +28,17 @@ export function ShareModal({ shareLink, setShareLink }) {
             />
             <h3 className="font-serif text-3xl">Send this letter</h3>
             <p className="text-base-content/80 text-sm font-sans mt-4">
-              You've carried these words long enough. Send your letter now, and
-              let the <span className="text-accent font-display">unsaid</span>{" "}
-              finally find its home.
+              You've carried these words long enough.
+              <br />
+              Send your letter now, and let the&nbsp;
+              <span className="text-accent font-display">unsaid</span> finally
+              find its home.
             </p>
             <div className="divider mx-auto" />
             <blockquote className="text-sm info text-neutral-content/60 font-sans">
-              The recipient will have the same viewing experience like you do
-              now.
+              They'll receive it exactly as you're seeing it now.
+              <br />
+              Nothing more, nothing less.
             </blockquote>
           </div>
           <div className="w-full flex items-center gap-2 bg-base-300 p-2 rounded-xl">
@@ -49,6 +51,7 @@ export function ShareModal({ shareLink, setShareLink }) {
             <button
               type="button"
               onClick={copyToClipboard}
+              data-testid="copy-link-btn"
               className="btn btn-primary font-sans btn-sm rounded-tl-xl rounded-bl-xl rounded-tr-full rounded-br-full"
             >
               Copy
@@ -56,15 +59,21 @@ export function ShareModal({ shareLink, setShareLink }) {
           </div>
           <div className="flex flex-col gap-1 uppercase tracking-widest text-base-content/30 font-sans">
             <p className="textarea-xs flex items-center justify-center">
-              <EyeSlashIcon weight="duotone" size={18} className="mr-2" />{" "}
-              Zero-Knowledge Share:
+              <EyeSlashIcon weight="duotone" size={18} className="mr-2" />
+              &nbsp; Zero-Knowledge Share:
             </p>
             <p className="textarea-xs font-mono text-center">
               The key never leaves your or the recipient's browser.
             </p>
           </div>
         </div>
+      </Modal>
+      <div className="absolute bottom-0 md:right-5/11 z-1000 font-sans w-full">
+        <Saajan
+          position="top"
+          message={`Someone once said,\n"To send a letter is a good way to go somewhere without moving anything but your heart."\nThey were not wrong.`}
+        />
       </div>
-    </div>
+    </>
   );
 }

frontend/src/components/ui/DateDisplay.tsx

@@ -31,7 +31,7 @@ export default function DateDisplay({
 
   return (
     <div className={`text-right flex flex-col gap-2 min-w-35 ${className}`}>
-      <span className="text-[10px] uppercase tracking-[0.4em] text-accent font-bold">
+      <span className="text-xxs uppercase tracking-widester text-accent font-bold">
         Date
       </span>
       <span className="text-sm font-serif text-secondary-content italic whitespace-nowrap">

frontend/src/components/ui/FormField.tsx

@@ -6,6 +6,8 @@ interface FormFieldProps {
   placeholder?: string;
   registration: UseFormRegisterReturn;
   error?: string;
+  handleFocus?: () => void;
+  "data-testid"?: string;
 }
 
 export default function FormField({
@@ -14,23 +16,27 @@ export default function FormField({
   placeholder,
   registration,
   error,
+  handleFocus,
+  "data-testid": testId,
 }: FormFieldProps) {
   return (
     <div className="form-control">
       <label
         htmlFor={registration.name}
-        className="field-label font-display text-base-content/90 font-medium"
+        className="field-label font-display text-neutral-content/80 font-medium"
       >
         {label}
       </label>
       <input
         {...registration}
         id={registration.name}
+        data-testid={testId}
         type={type}
         placeholder={placeholder}
         className={`input input-bordered focus:input-primary ${
           error ? "input-error" : ""
         }`}
+        onFocus={handleFocus}
       />
       {error && <p className="text-error">{error}</p>}
     </div>

frontend/src/components/ui/LogModal.tsx

@@ -1,4 +1,5 @@
-import { WarningIcon, XCircleIcon, XIcon } from "@phosphor-icons/react";
+import { WarningIcon } from "@phosphor-icons/react";
+import { Modal } from "./Modal";
 
 interface LogModalContent {
   status: "WARN" | "ERROR" | "RESET" | "SUCCESS";
@@ -15,40 +16,28 @@ export const LogModal = ({
   onClose,
   status,
 }: LogModalContent) => {
-  return status === "RESET" || !isOpen ? (
-    <div></div>
-  ) : (
-    <div className="modal modal-open modal-middle bg-base-100/20 backdrop-blur-md z-100">
-      <div className="modal-box bg-transparent border-none shadow-none relative">
-        <div
-          className={`alert ${status === "WARN" ? "alert-warning" : "alert-error"} flex flex-col items-center text-center gap-6 py-4`}
-        >
-          {status === "WARN" && (
-            <WarningIcon className="text-warning" size={16} weight="bold" />
-          )}
-          {status === "ERROR" && (
-            <XCircleIcon className="text-error" size={16} weight="bold" />
-          )}
-          {message}
-          <div className="divider text-primary-content text-xs uppercase tracking-widest">
-            Error Stack
-          </div>
-          <div className="mockup-code bg-base-100 text-error w-full">
-            <pre>
-              <code>{String(log)}</code>
-            </pre>
-          </div>
-          <form method="dialog">
-            <button
-              type="button"
-              onClick={onClose}
-              className="btn btn-sm btn-circle btn-ghost absolute right-6 top-6"
-            >
-              <XIcon size={6} weight="bold" />
-            </button>
-          </form>
-        </div>
+  return (
+    <Modal isOpen={isOpen && status !== "RESET"} onClose={onClose}>
+      <div
+        className={`alert ${status === "WARN" ? "alert-warning" : "alert-error"} flex flex-col items-center text-center gap-6 py-4`}
+      >
+        {status === "WARN" && (
+          <WarningIcon className="text-warning" size={16} weight="duotone" />
+        )}
+        <span data-testid="log-modal-message">{message}</span>
+        {log && (
+          <>
+            <div className="divider text-primary-content text-xs uppercase tracking-widest">
+              Error Stack
+            </div>
+            <div className="mockup-code bg-base-100 text-error w-full">
+              <pre>
+                <code>{String(log)}</code>
+              </pre>
+            </div>
+          </>
+        )}
       </div>
-    </div>
+    </Modal>
   );
 };

frontend/src/components/ui/Modal.tsx

@@ -0,0 +1,44 @@
+import { XCircleIcon } from "@phosphor-icons/react";
+import type { ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+interface ModalProps {
+  isOpen: boolean;
+  onClose?: () => void;
+  children: ReactNode;
+  "data-testid"?: string;
+}
+
+export function Modal({
+  isOpen,
+  onClose,
+  children,
+  "data-testid": testId,
+}: ModalProps) {
+  if (!isOpen) return null;
+  // render the modal top of all elements and position them to document viewport (/ the main wrapper).
+  // NOTE: this is recommended approach for modals as it shouldn't be bound to the parent box.
+  const mainContainer = document.querySelector("main") || document.body;
+  return createPortal(
+    <div
+      data-testid={testId}
+      className="modal modal-open modal-middle backdrop-blur-md before:absolute before:top-0 before:left-0 before:w-full before:h-full before:content-[''] before:opacity-[0.03] before:z-10 before:pointer-events-none before:bg-[url('assets/textures/noise.gif')]"
+    >
+      <div className="modal-box border border-neutral/60 relative bg-base-100/60 flex flex-col items-center text-center gap-6">
+        {onClose && (
+          <button
+            type="button"
+            data-testid="modal-close-btn"
+            className="btn btn-sm btn-circle btn-ghost absolute right-2 top-2 z-20"
+            onClick={onClose}
+            aria-label="Close"
+          >
+            <XCircleIcon size={18} weight="bold" />
+          </button>
+        )}
+        {children}
+      </div>
+    </div>,
+    mainContainer,
+  );
+}

frontend/src/components/ui/Navbar.tsx

@@ -21,7 +21,7 @@ export const Navbar = ({ child }: { child?: React.ReactNode }) => {
               className="text-base-content/40 group-hover:text-primary transition-colors"
             />
           </div>
-          <span className="font-sans text-[10px] tracking-[0.3em] uppercase font-bold text-base-content/30 group-hover:text-base-content transition-colors">
+          <span className="font-sans text-xxs tracking-widester uppercase font-bold text-base-content/30 group-hover:text-base-content transition-colors">
             Drawer
           </span>
         </button>

frontend/src/components/ui/Saajan.tsx

@@ -0,0 +1,53 @@
+import { useEffect, useState } from "react";
+import sf_mini from "../../assets/sf_mini.png";
+
+interface SaajanProps {
+  message: string;
+  position?: "top" | "left" | "right" | "bottom";
+}
+
+export default function Saajan({ message, position = "right" }: SaajanProps) {
+  const [animate, setAnimate] = useState<boolean>(false);
+  const [tooltipPosition, setTooltipPosition] =
+    useState<string>("tooltip-right");
+  const [alignment, setAlignment] = useState<string>("justify-start");
+
+  useEffect(() => {
+    setAnimate(true);
+    const timeout = setTimeout(() => {
+      setAnimate(false);
+    }, 1000);
+
+    return () => {
+      clearTimeout(timeout);
+    };
+  }, []);
+
+  useEffect(() => {
+    setTooltipPosition(`tooltip-${position}`);
+    if (position === "top") {
+      setAlignment("justify-center");
+    }
+    if (position === "right") {
+      setAlignment("justify-start");
+    }
+    if (position === "left") {
+      setAlignment("justify-end");
+    }
+  }, [position]);
+
+  return (
+    <div className={`relative w-full flex ${alignment}`}>
+      <div
+        className={`tooltip tooltip-open ${tooltipPosition} before:border before:border-dashed before:border-primary/40 before:max-w-xs before:whitespace-pre-line italic before:text-left`}
+        data-tip={message}
+      >
+        <img
+          src={sf_mini}
+          alt="saajan"
+          className={`sepia-20 w-35 -mb-6 ${animate ? "animate-[pulse_.5s_ease_2]" : ""}`}
+        />
+      </div>
+    </div>
+  );
+}

frontend/src/config/endpoints.ts

@@ -9,14 +9,14 @@ export const endpoints = {
   LETTERS: "/api/letters/",
 };
 
-// simple utility to handle path params
+// constructs dynamic path params for activate flow
 export const replacePathParams = (
   url: string,
   params: Record<string, string>,
 ): string => {
-  let result = url;
+  let constructedUrl = url;
   for (const [key, value] of Object.entries(params)) {
-    result = result.replace(`:${key}`, value);
+    constructedUrl = constructedUrl.replace(`:${key}`, value);
   }
-  return result;
+  return constructedUrl;
 };

frontend/src/config/routes.ts

@@ -1,4 +1,4 @@
-// Route PATTERNS
+// Page Route PATTERNS
 export const ROUTES = {
   HOME: "/",
   ONBOARD: "/onboard",
@@ -6,13 +6,13 @@ export const ROUTES = {
   ACTIVATE: "/activate/:uidb64/:token",
   LOGIN: "/login",
   DRAWER: "/drawer",
-  WRITE: "/quill/:public_id?", // ← static pattern
+  WRITE: "/quill/:public_id?",
   READ: "/read/:public_id",
+  ABOUT: "/know-piku",
 };
 
-// Path BUILDERS
+// Dynamic path BUILDERS
 export const PATHS = {
   write: (public_id?: string) => `/quill/${public_id ?? ""}`,
   read: (public_id: string) => `/read/${public_id}`,
-  activate: (uidb64: string, token: string) => `/activate/${uidb64}/${token}`,
 };

frontend/src/config/welcomeLetter.ts

@@ -0,0 +1,102 @@
+import trainImage from "../assets/screenshots/train.png";
+import type { CanvasJSON } from "../components/editor/ComposeCanvas";
+
+export function getWelcomeLetterContent(userName: string): CanvasJSON {
+  return {
+    objects: [
+      {
+        fontSize: 18,
+        fontWeight: 500,
+        fontFamily: "Kavivanar",
+        fontStyle: "normal",
+        lineHeight: 1.5,
+        text: `\nDear ${userName}, \n\nYou made it this far, which means something already brought you here. \nA name, maybe. A feeling you haven't been able to shake. Something you typed and deleted too many times to count.\n\nMost people carry it quietly. They tell themselves it doesn't matter anymore, or that too much time has passed, or that the other person wouldn't understand anyway. And maybe they're right. \n\nBut the thing is — the unsaid thing doesn't really care about any of that. \nIt just stays.\n\nSo here you are.\n\nYou don't have to know what you want to say yet. \nYou don't have to have it figured out — who it's for, or why it still matters, or what you're hoping will happen after. \n\nA lot of letters written here start without any of that. They find their way.\n\nTake your time. \nNo one's watching. \n\nWhen you're ready, write a letter.\n\nSometimes the wrong train takes you to the right station.\n- S.F.`,
+        charSpacing: 0,
+        textAlign: "left",
+        styles: [],
+        pathStartOffset: 0,
+        pathSide: "left",
+        pathAlign: "baseline",
+        underline: false,
+        overline: false,
+        linethrough: false,
+        textBackgroundColor: "",
+        direction: "ltr",
+        textDecorationThickness: 66.667,
+        minWidth: 20,
+        splitByGrapheme: false,
+        type: "Textbox",
+        version: "7.2.0",
+        originX: "left",
+        originY: "top",
+        left: 36,
+        top: 36,
+        width: 720,
+        height: 813.6,
+        fill: "#111e67",
+        stroke: null,
+        strokeWidth: 1,
+        strokeDashArray: null,
+        strokeLineCap: "butt",
+        strokeDashOffset: 0,
+        strokeLineJoin: "miter",
+        strokeUniform: false,
+        strokeMiterLimit: 4,
+        scaleX: 1,
+        scaleY: 1,
+        angle: 0,
+        flipX: false,
+        flipY: false,
+        opacity: 1,
+        shadow: null,
+        visible: true,
+        backgroundColor: "",
+        fillRule: "nonzero",
+        paintFirst: "fill",
+        globalCompositeOperation: "source-over",
+        skewX: 0,
+        skewY: 0,
+      },
+      {
+        cropX: 0,
+        cropY: 0,
+        type: "Image",
+        version: "7.2.0",
+        originX: "left",
+        originY: "top",
+        left: 298.4065,
+        top: 660.2853,
+        width: 512,
+        height: 400,
+        fill: "rgb(0,0,0)",
+        stroke: null,
+        strokeWidth: 0,
+        strokeDashArray: null,
+        strokeLineCap: "butt",
+        strokeDashOffset: 0,
+        strokeLineJoin: "miter",
+        strokeUniform: false,
+        strokeMiterLimit: 4,
+        scaleX: 0.4753,
+        scaleY: 0.4753,
+        angle: 355.5436,
+        flipX: false,
+        flipY: false,
+        opacity: 1,
+        shadow: null,
+        visible: true,
+        backgroundColor: "",
+        fillRule: "nonzero",
+        paintFirst: "fill",
+        globalCompositeOperation: "source-over",
+        skewX: 0,
+        skewY: 0,
+        src: trainImage,
+        crossOrigin: null,
+        filters: [],
+      },
+    ],
+    canvasWidth: 700,
+    canvasHeight: 900,
+  };
+}

frontend/src/hooks/useAuth.test.ts

@@ -6,6 +6,7 @@ import { mockUser } from "../../test/fixtures/user.fixture";
 import { server } from "../../test/mocks/server";
 import { useAuthStore } from "../store/useAuthStore";
 import { useKeyStore } from "../store/useKeyStore";
+import { CryptoUtils } from "../utils/crypto";
 import {
   clearMasterKey,
   loadMasterKey,
@@ -14,6 +15,7 @@ import {
 import { useAuth } from "./useAuth";
 
 vi.mock("../utils/keystore");
+vi.mock("../utils/crypto");
 
 const VITE_API_URL = "http://piku-server";
 
@@ -30,6 +32,11 @@ beforeEach(() => {
     isInitializing: true,
   });
   useKeyStore.setState({ masterKey: null });
+
+  vi.mocked(CryptoUtils.deriveKeyBundle).mockResolvedValue({
+    masterKey: mockMasterKey,
+    authHash: "mock-hash",
+  });
 });
 
 describe("isAuthenticated", () => {
@@ -201,3 +208,68 @@ describe("initialize", () => {
     expect(useKeyStore.getState().masterKey).not.toBeNull();
   });
 });
+
+describe("unlock", () => {
+  beforeEach(() => {
+    useAuthStore.setState({
+      accessToken: "valid-token",
+      user: mockUser,
+      isInitializing: false,
+    });
+  });
+
+  it("should derive the master key from the user password, validate it via API, and persist it", async () => {
+    let loginCalled = false;
+    server.use(
+      http.post(`${VITE_API_URL}/api/auth/login/`, async () => {
+        loginCalled = true;
+        return HttpResponse.json({ access: "token", user: mockUser });
+      }),
+    );
+    const { result } = renderHook(() => useAuth());
+
+    await act(async () => {
+      await result.current.unlock("password");
+    });
+
+    expect(CryptoUtils.deriveKeyBundle).toHaveBeenCalledWith(
+      "password",
+      mockUser.email,
+    );
+    expect(loginCalled).toBe(true);
+    expect(saveMasterKey).toHaveBeenCalledWith(mockMasterKey);
+    expect(useKeyStore.getState().masterKey).toEqual(mockMasterKey);
+  });
+
+  it("should logout if user is not present", async () => {
+    useAuthStore.setState({ user: null });
+    const { result } = renderHook(() => useAuth());
+
+    await act(async () => {
+      await result.current.unlock("password");
+    });
+
+    expect(CryptoUtils.deriveKeyBundle).not.toHaveBeenCalled();
+    expect(saveMasterKey).not.toHaveBeenCalled();
+    expect(useAuthStore.getState().accessToken).toBeNull();
+    expect(clearMasterKey).toHaveBeenCalled();
+  });
+
+  it("should throw an error and not persist the key if validation fails", async () => {
+    server.use(
+      http.post(
+        `${VITE_API_URL}/api/auth/login/`,
+        () => new HttpResponse(null, { status: 400 }),
+      ),
+    );
+
+    const { result } = renderHook(() => useAuth());
+
+    await act(async () => {
+      await expect(result.current.unlock("wrong-password")).rejects.toThrow();
+    });
+
+    expect(saveMasterKey).not.toHaveBeenCalled();
+    expect(useKeyStore.getState().masterKey).toBeNull();
+  });
+});

frontend/src/hooks/useAuth.ts

@@ -32,7 +32,7 @@ export const useAuth = () => {
   const logout = async () => {
     try {
       await api.post(endpoints.LOGOUT);
-    } catch (_error) {
+    } catch {
     } finally {
       clearAuth();
       setMasterKey(null);
@@ -57,7 +57,6 @@ export const useAuth = () => {
     }
 
     try {
-      // try session refresh
       const { data: refreshData } = await publicApi.post(endpoints.REFRESH);
       const { data: userData } = await api.get(endpoints.ME, {
         headers: { Authorization: `Bearer ${refreshData.access}` },
@@ -71,16 +70,24 @@ export const useAuth = () => {
   }, [setMasterKey]);
 
   const unlock = async (password: string) => {
-    if (!user) return;
+    if (!user) {
+      await logout();
+      return;
+    }
 
-    try {
-      const { masterKey } = await CryptoUtils.deriveKeyBundle(
-        password,
-        user.email,
-      );
-      await saveMasterKey(masterKey);
-      setMasterKey(masterKey);
-    } catch {}
+    const { masterKey, authHash } = await CryptoUtils.deriveKeyBundle(
+      password,
+      user.email,
+    );
+
+    // Validate password by calling login endpoint
+    await api.post(endpoints.LOGIN, {
+      email: user.email,
+      password: authHash,
+    });
+
+    await saveMasterKey(masterKey);
+    setMasterKey(masterKey);
   };
 
   return {

frontend/src/hooks/useLetters.tsx

@@ -1,32 +1,16 @@
 import { useEffect, useMemo, useState } from "react";
 import { api } from "../api/apiClient";
+import type { LetterMetadata, LetterResponseData } from "../api/response";
 import { endpoints } from "../config/endpoints";
 import { useKeyStore } from "../store/useKeyStore";
 import { CryptoUtils } from "../utils/crypto";
 
-export interface Letter {
-  public_id: string;
-  type: "KEPT" | "VAULT" | "SENT";
-  status: "DRAFT" | "SEALED" | "BURNED";
-  updated_at: string;
-  sealed_at?: string;
-  unlock_at: string;
-  encrypted_metadata: string;
-  encrypted_content: string;
-  encrypted_dek: string;
-}
-
-export interface LetterMetadata {
-  recipient: string;
-  tags?: string[];
-}
-
-export interface ProcessedLetter extends Letter {
+export interface ProcessedLetter extends LetterResponseData {
   metadata: LetterMetadata;
 }
 
-async function decryptLetters(
-  letters: Letter[],
+async function decryptLettersMetadata(
+  letters: LetterResponseData[],
   masterKey: CryptoKey,
 ): Promise<ProcessedLetter[]> {
   const cryptoUtils = new CryptoUtils();
@@ -43,7 +27,7 @@ async function decryptLetters(
         )) as LetterMetadata;
 
         return { ...letter, metadata };
-      } catch (_err) {
+      } catch {
         return {
           ...letter,
           metadata: { recipient: "Encrypted Letter" },
@@ -56,19 +40,22 @@ async function decryptLetters(
 export function useLetters() {
   const [letters, setLetters] = useState<ProcessedLetter[]>([]);
   const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
   const [isAuthRequired, setIsAuthRequired] = useState<boolean>(false);
   const { masterKey } = useKeyStore();
 
+  // to fetch the letters and decryypt the metadata on load
   useEffect(() => {
     if (!masterKey) {
       setIsAuthRequired(true);
       return;
     }
     setIsAuthRequired(false);
+    setError(null);
     setLoading(true);
     api
       .get(endpoints.LETTERS)
-      .then((res) => decryptLetters(res.data, masterKey))
+      .then((res) => decryptLettersMetadata(res.data, masterKey))
       .then((decrypted) => {
         setLetters(
           decrypted.sort(
@@ -78,7 +65,9 @@ export function useLetters() {
           ),
         );
       })
-      .catch((_err) => {})
+      .catch((err) => {
+        setError(err);
+      })
       .finally(() => setLoading(false));
   }, [masterKey]);
 
@@ -86,11 +75,15 @@ export function useLetters() {
     return {
       drafts: letters.filter((l) => l.status === "DRAFT"),
       kept: letters.filter((l) => l.type === "KEPT" && l.status === "SEALED"),
-      vault: letters.filter((l) => l.type === "VAULT"),
+      vault: letters.filter((l) => l.type === "VAULT" && l.status === "SEALED"),
       sent: letters.filter((l) => l.type === "SENT" && l.status === "SEALED"),
     };
   }, [letters]);
 
+  if (error) {
+    throw error;
+  }
+
   return {
     ...drawerItems,
     loading,

frontend/src/index.css

@@ -2,60 +2,77 @@
 @plugin "daisyui";
 
 @plugin "daisyui/theme" {
-    name: "piku";
-    default: true;
-    prefersdark: true;
-    color-scheme: dark;
+  name: "piku";
+  default: true;
+  prefersdark: true;
+  color-scheme: dark;
 
-    --color-base-100: oklch(14% 0.012 35);
-    --color-base-200: oklch(18% 0.014 33);
-    --color-base-300: oklch(22% 0.016 32);
-    --color-base-content: oklch(82% 0.02 70);
+  --color-base-100: oklch(14% 0.012 35);
+  --color-base-200: oklch(18% 0.014 33);
+  --color-base-300: oklch(22% 0.016 32);
+  --color-base-content: oklch(82% 0.02 70);
 
-    --color-primary: oklch(67% 0.11 78);
-    --color-primary-content: oklch(15% 0.03 70);
+  --color-primary: oklch(67% 0.11 78);
+  --color-primary-content: oklch(15% 0.03 70);
 
-    --color-secondary: oklch(48% 0.08 305);
-    --color-secondary-content: oklch(92% 0.01 305);
+  --color-secondary: oklch(48% 0.08 305);
+  --color-secondary-content: oklch(92% 0.01 305);
 
-    --color-accent: oklch(55% 0.06 325);
-    --color-accent-content: oklch(18% 0.03 295);
+  --color-accent: oklch(55% 0.06 325);
+  --color-accent-content: oklch(18% 0.03 295);
 
-    --color-neutral: oklch(28% 0.02 45);
-    --color-neutral-content: oklch(80% 0.015 60);
+  --color-neutral: oklch(38% 0.02 45);
+  --color-neutral-content: oklch(80% 0.015 60);
 
-    --color-info: oklch(60% 0.07 240);
-    --color-info-content: oklch(95% 0.01 240);
-    --color-success: oklch(60% 0.08 150);
-    --color-success-content: oklch(16% 0.03 150);
-    --color-warning: oklch(68% 0.08 72);
-    --color-warning-content: oklch(18% 0.03 60);
-    --color-error: oklch(55% 0.1 22);
-    --color-error-content: oklch(92% 0.01 22);
+  --color-info: oklch(60% 0.06 250);
+  --color-info-content: oklch(95% 0.01 240);
+  --color-success: oklch(65% 0.05 140);
+  --color-success-content: oklch(16% 0.03 150);
+  --color-warning: oklch(68% 0.08 72);
+  --color-warning-content: oklch(18% 0.03 60);
+  --color-error: oklch(55% 0.1 22);
+  --color-error-content: oklch(92% 0.01 22);
 
-    --radius-selector: 0.5rem;
-    --radius-field: 0.375rem;
-    --radius-box: 0.5rem;
+  --radius-selector: 0.5rem;
+  --radius-field: 0.375rem;
+  --radius-box: 0.5rem;
 
-    --depth: 1;
-    --noise: 0.03;
+  --depth: 1;
+  --noise: 0.03;
 
-    --border: 1px;
+  --border: 1px;
 }
 
 @theme {
-    --font-display: "Playwrite HR Lijeva Variable", cursive;
-    --font-sans: "Jost Variable", sans-serif;
-    --font-serif: "Playfair Display Variable", serif;
-    --color-glass-bg: rgba(28,
-            22,
-            16,
-            0.45);
-    --shadow-warm: 0 20px 50px -12px rgba(30, 20, 12, 0.6);
-    --radius-xl: 1.5rem;
-    --color-paper: oklch(97% 0.008 80);
+  --font-display: "Playwrite HR Lijeva Variable", cursive;
+  --font-sans: "Jost Variable", sans-serif;
+  --font-serif: "Playfair Display Variable", serif;
+  --font-mono: "Space Mono", monospace;
+  --font-ink: "Kavivanar", sans-serif;
+  --font-redact: "Redacted Script", cursive;
+  --font-slab: "Cutive Mono", monospace;
+  --font-hand: "Architects Daughter", cursive;
+  --color-glass-bg: rgba(28, 22, 16, 0.45);
+  --shadow-warm: 0 20px 50px -12px rgba(30, 20, 12, 0.6);
+  --radius-xl: 1.5rem;
+  --color-paper: oklch(97% 0.008 80);
+  --text-xxs: 10px;
+  --tracking-widester: 0.5em;
+  --background-image-vig: radial-gradient(
+    circle at center,
+    transparent 0%,
+    rgba(0, 0, 0, 0.4) 100%
+  );
 }
 
 .glass-card {
-    @apply bg-glass-bg backdrop-blur-xl border border-white/5 shadow-warm rounded-xl;
+  @apply bg-glass-bg max-w-xs md:max-w-sm backdrop-blur-xl border border-neutral-content/10 shadow-warm rounded-xl m-4;
+}
+
+.ul-wavy {
+  @apply decoration-primary/40 underline decoration-wavy underline-offset-4;
+}
+
+a {
+  @apply text-primary underline decoration-base-content/20 underline-offset-4 hover:decoration-primary/60 transition-colors;
 }

frontend/src/main.tsx

@@ -1,10 +1,13 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
+
 import "./index.css";
+
 import "@fontsource-variable/playwrite-hr-lijeva/wght.css";
 import "@fontsource-variable/jost/wght.css";
 import "@fontsource-variable/playfair-display/wght.css";
-import App from "./App.tsx";
+
+import App from "./App";
 
 const root = document.getElementById("root");
 if (root) {

frontend/src/pages/Activate.tsx

@@ -16,8 +16,6 @@ export default function Activate() {
 
   useEffect(() => {
     if (!(uidb64 && token) || hasCalled.current) return;
-
-    // prevent double api calls
     hasCalled.current = true;
 
     const activateAccount = async () => {
@@ -28,7 +26,7 @@ export default function Activate() {
         });
         await publicApi.get(url);
         setStatus("success");
-      } catch (_err) {
+      } catch {
         setStatus("error");
       }
     };
@@ -46,7 +44,7 @@ export default function Activate() {
       )}
 
       {status === "success" && (
-        <div className="flex flex-col items-center gap-6 animate-in fade-in zoom-in duration-500">
+        <div className="flex flex-col items-center gap-6 duration-500">
           <div className="bg-success/10 p-4 rounded-full">
             <CheckCircleIcon
               size={64}
@@ -54,18 +52,22 @@ export default function Activate() {
               className="text-success"
             />
           </div>
-          <h2 className="font-display text-xl text-success">
-            Account Activated!
+          <h2
+            data-testid="activation-success-header"
+            className="font-display text-xl text-success"
+          >
+            You're in.
           </h2>
-          <p className="opacity-70 mb-8 leading-relaxed">
-            Welcome to <Logo />
+          <p className="opacity-70 leading-relaxed">
+            Welcome to&nbsp;
+            <Logo type="inline" />
             <br />
-            Your identity is now verified and ready for timeless letters.
+            Just one more step and you can start writing timeless letters.
           </p>
-          <div className="divider opacity-10"></div>
-
+          <div className="divider opacity-10 my-0"></div>
           <button
             type="button"
+            data-testid="start-writing-btn"
             className="btn btn-primary w-full shadow-lg"
             onClick={() =>
               navigate(ROUTES.LOGIN, {
@@ -74,7 +76,7 @@ export default function Activate() {
               })
             }
           >
-            Start Writing
+            I'm ready
           </button>
         </div>
       )}
@@ -85,16 +87,17 @@ export default function Activate() {
             <XCircleIcon size={64} weight="duotone" className="text-error" />
           </div>
           <h2 className="font-display text-xl text-error">Activation Failed</h2>
-          <p className="opacity-70 mb-8 leading-relaxed">
+          <p className="opacity-70 leading-relaxed">
             The link might be expired or already used. Please try registering
             again.
           </p>
+          <div className="divider opacity-10 my-0"></div>
           <button
             type="button"
             className="btn btn-ghost w-full"
             onClick={() => navigate(ROUTES.ONBOARD)}
           >
-            Back to Registration
+            Register Again
           </button>
         </div>
       )}

frontend/src/pages/Drawer.test.tsx

@@ -1,12 +1,26 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
 import { MemoryRouter } from "react-router-dom";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { mockUser } from "../../test/fixtures/user.fixture";
+import type { WelcomeLetterOverlayProps } from "../components/drawer/WelcomeLetterOverlay";
 import { useLetters } from "../hooks/useLetters";
 import { useAuthStore } from "../store/useAuthStore";
 import Drawer from "./Drawer";
 
 vi.mock("../hooks/useLetters");
+vi.mock("../components/drawer/WelcomeLetterOverlay", () => ({
+  WelcomeLetterOverlay: ({ onComplete }: WelcomeLetterOverlayProps) => (
+    <div data-testid="welcome-letter-overlay">
+      <button
+        type="button"
+        data-testid="overlay-exit-button"
+        onClick={onComplete}
+      >
+        I'll see you
+      </button>
+    </div>
+  ),
+}));
 
 describe("Drawer Page", () => {
   beforeEach(() => {
@@ -27,17 +41,21 @@ describe("Drawer Page", () => {
     });
   });
 
-  it("renders the cabinet sections and empty state message", () => {
+  it("renders the drawer sections and empty state message", () => {
     render(
       <MemoryRouter>
         <Drawer />
       </MemoryRouter>,
     );
 
-    expect(screen.getByText(/Drafts/i)).toBeInTheDocument();
-    expect(screen.getAllByText(/Kept/i).length).toBeGreaterThanOrEqual(1);
-    expect(screen.getByText(/Vault/i)).toBeInTheDocument();
-    expect(screen.getByText(/This drawer remains silent/i)).toBeInTheDocument();
+    expect(screen.getByTestId("drawer-section-drafts")).toBeInTheDocument();
+    expect(
+      screen.getAllByTestId("drawer-section-title").length,
+    ).toBeGreaterThanOrEqual(1);
+    expect(screen.getByTestId("drawer-section-vault")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("empty-drawer-message-drafts"),
+    ).toBeInTheDocument();
   });
 
   it("renders the loading state", () => {
@@ -56,7 +74,7 @@ describe("Drawer Page", () => {
       </MemoryRouter>,
     );
 
-    expect(screen.getByText(/Opening your cabinet/i)).toBeInTheDocument();
+    expect(screen.getByTestId("drawer-loading-state")).toBeInTheDocument();
   });
 
   it("renders the authentication required modal when api requires auth", () => {
@@ -75,7 +93,36 @@ describe("Drawer Page", () => {
       </MemoryRouter>,
     );
 
-    expect(screen.getByText(/Authentication Required/i)).toBeInTheDocument();
-    expect(screen.getByPlaceholderText(/password/i)).toBeInTheDocument();
+    expect(screen.getByTestId("passkey-modal-title")).toBeInTheDocument();
+    expect(screen.getByTestId("passkey-input")).toBeInTheDocument();
+  });
+
+  it("renders the welcome letter when firstTime state is present", () => {
+    render(
+      <MemoryRouter
+        initialEntries={[{ pathname: "/drawer", state: { firstTime: true } }]}
+      >
+        <Drawer />
+      </MemoryRouter>,
+    );
+
+    expect(screen.getByTestId("welcome-letter-overlay")).toBeInTheDocument();
+  });
+
+  it("renders the drawer content when the letter is closed", () => {
+    render(
+      <MemoryRouter
+        initialEntries={[{ pathname: "/drawer", state: { firstTime: true } }]}
+      >
+        <Drawer />
+      </MemoryRouter>,
+    );
+
+    const completeButton = screen.getByTestId("overlay-exit-button");
+    fireEvent.click(completeButton);
+
+    expect(
+      screen.queryByTestId("welcome-letter-overlay"),
+    ).not.toBeInTheDocument();
   });
 });

frontend/src/pages/Drawer.tsx

@@ -1,23 +1,35 @@
-import { FeatherIcon } from "@phosphor-icons/react";
+import {
+  ArchiveIcon,
+  FeatherIcon,
+  FileDashedIcon,
+  PaperPlaneTiltIcon,
+  VaultIcon,
+} from "@phosphor-icons/react";
 import { useState } from "react";
-import { useNavigate } from "react-router-dom";
-import { DrawerSection } from "../components/drawer/DrawerSection.tsx";
-import { LetterItem } from "../components/drawer/LetterItem.tsx";
-import { PasskeyModal } from "../components/drawer/PasskeyModal.tsx";
+import { useLocation, useNavigate } from "react-router-dom";
+import { DrawerSection } from "../components/drawer/DrawerSection";
+import { LetterItem } from "../components/drawer/LetterItem";
+import { PasskeyModal } from "../components/drawer/PasskeyModal";
+import { WelcomeLetterOverlay } from "../components/drawer/WelcomeLetterOverlay";
 import Logo from "../components/Logo";
+import Saajan from "../components/ui/Saajan";
 import { PATHS } from "../config/routes";
 import { useAuth } from "../hooks/useAuth";
 import { useLetters } from "../hooks/useLetters";
 import {
   formatRelativeDate,
   formatRelativeDateWithoutTime,
-} from "../utils/dateFormat.ts";
+} from "../utils/dateFormat";
 
 export default function Drawer() {
-  const { user, logout, unlock } = useAuth();
+  const { user, logout } = useAuth();
 
   const [openSection, setOpenSection] = useState<string | null>(null);
   const navigate = useNavigate();
+  const location = useLocation();
+  const [showWelcomeLetter, setShowWelcomeLetter] = useState(
+    !!location.state?.firstTime,
+  );
   const { drafts, kept, sent, vault, loading, isAuthRequired } = useLetters();
 
   if (!user) return null;
@@ -27,16 +39,26 @@ export default function Drawer() {
 
   return (
     <div className="min-h-screen w-full bg-base-100 text-base-content flex flex-col items-center py-12 px-5 pb-32 font-serif transition-colors">
-      <div className="fixed inset-0 bg-[radial-gradient(circle_at_center,transparent_0%,rgba(0,0,0,0.5)_100%)] pointer-events-none z-0" />
+      <div className="fixed inset-0 bg-vig pointer-events-none z-0" />
 
-      {isAuthRequired && <PasskeyModal onUnlock={unlock} />}
+      {showWelcomeLetter && (
+        <WelcomeLetterOverlay
+          userName={user.full_name}
+          onComplete={() => {
+            setShowWelcomeLetter(false);
+            navigate(location.pathname, { replace: true, state: {} });
+          }}
+        />
+      )}
+
+      {isAuthRequired && <PasskeyModal />}
       <header className="text-center mb-12 z-10 animate-in fade-in slide-in-from-top-4 duration-500">
         <Logo />
-        <div className="font-sans text-xs tracking-[0.3em] uppercase text-base-content/40 mt-2">
+        <div className="font-sans text-xs tracking-widester uppercase text-base-content/40 mt-2">
           Personal Archive
         </div>
         <div className="mt-6 font-sans text-sm text-base-content flex items-center justify-center gap-2 opacity-60 hover:opacity-100 transition-opacity">
-          Welcome Back{" "}
+          Welcome Back&nbsp;
           <span className="font-semibold text-primary">{user.full_name}</span>
           <button
             type="button"
@@ -52,7 +74,10 @@ export default function Drawer() {
         {loading ? (
           <div className="flex-1 flex flex-col items-center justify-center p-12 gap-4">
             <span className="loading loading-ring loading-lg text-primary opacity-20"></span>
-            <span className="text-[10px] uppercase tracking-[0.3em] font-sans text-base-content/20 animate-pulse">
+            <span
+              data-testid="drawer-loading-state"
+              className="text-xxs uppercase tracking-widester font-sans text-base-content/20 animate-pulse"
+            >
               Opening your cabinet...
             </span>
           </div>
@@ -61,9 +86,11 @@ export default function Drawer() {
             <DrawerSection
               id="drafts"
               title="Drafts"
-              count={`${drafts.length} unfinished whispers`}
+              count={drafts.length}
+              subtext="unfinished whispers"
               isOpen={openSection === "drafts"}
               onClick={() => toggleSection("drafts")}
+              icon={<FileDashedIcon weight="thin" size={128} />}
             >
               {drafts.map((draft) => (
                 <LetterItem
@@ -79,9 +106,11 @@ export default function Drawer() {
             <DrawerSection
               id="kept"
               title="Kept"
-              count={`${kept.length} private letters`}
+              count={kept.length}
+              subtext="private letters"
               isOpen={openSection === "kept"}
               onClick={() => toggleSection("kept")}
+              icon={<ArchiveIcon weight="thin" size={128} />}
             >
               {kept.map((letter) => (
                 <LetterItem
@@ -96,9 +125,11 @@ export default function Drawer() {
             <DrawerSection
               id="sent"
               title="Sent"
-              count={`${sent.length} shared truths`}
+              count={sent.length}
+              subtext="shared truths"
               isOpen={openSection === "sent"}
               onClick={() => toggleSection("sent")}
+              icon={<PaperPlaneTiltIcon weight="thin" size={128} />}
             >
               {sent.map((letter) => (
                 <LetterItem
@@ -109,18 +140,15 @@ export default function Drawer() {
                   timestamp={formatRelativeDate(letter.updated_at)}
                 />
               ))}
-              {sent.length === 0 && (
-                <p className="text-center text-base-content/20 mt-4">
-                  This drawer remains silent
-                </p>
-              )}
             </DrawerSection>
             <DrawerSection
               id="vault"
               title="Vault"
-              count={`${vault.length} things locked;not lost;in time`}
+              count={vault.length}
+              subtext="things locked—not lost—in time"
               isOpen={openSection === "vault"}
               onClick={() => toggleSection("vault")}
+              icon={<VaultIcon weight="thin" size={128} />}
             >
               {vault.map((letter) => (
                 <LetterItem
@@ -143,6 +171,7 @@ export default function Drawer() {
       <button
         type="button"
         id="write-letter-btn"
+        data-testid="write-letter-btn"
         className="group mt-15 z-10 bg-transparent border border-dashed border-base-content/10 px-8 py-4 text-base-content/40 italic cursor-pointer transition-all hover:border-primary/40 hover:text-base-content/60 hover:bg-primary/5 hover:-translate-y-0.5 flex items-center gap-2 focus-visible:ring-2 focus-visible:ring-primary/50 duration-500"
         onClick={() => navigate(PATHS.write(""))}
       >
@@ -151,7 +180,7 @@ export default function Drawer() {
           weight="duotone"
           className="text-primary/30 transition-all duration-300 group-hover:text-primary"
         />
-        Write something{" "}
+        Write something&nbsp;
         <span className="relative inline-flex">
           <span className="transition-opacity duration-500 opacity-80 group-hover:opacity-0">
             . . . . . .
@@ -162,9 +191,17 @@ export default function Drawer() {
         </span>
       </button>
 
-      <footer className="mt-25 font-sans text-[0.6rem] tracking-[0.2em] uppercase text-base-content/10 z-10">
+      <footer className="mt-25 font-sans text-[0.6rem] tracking-widester uppercase text-base-content/10 z-10">
         For your unsaid.
       </footer>
+      {!showWelcomeLetter && (
+        <div className="absolute bottom-0 z-50 font-sans">
+          <Saajan
+            message={`Good to see you again, ${user.full_name}.\nWhat's on your mind today?`}
+            position="top"
+          />
+        </div>
+      )}
     </div>
   );
 }

frontend/src/pages/Editor.test.tsx

@@ -1,4 +1,9 @@
-import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import {
+  fireEvent,
+  render,
+  screen,
+  waitForElementToBeRemoved,
+} from "@testing-library/react";
 import { HttpResponse, http } from "msw";
 import { MemoryRouter, Route, Routes } from "react-router-dom";
 import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -79,42 +84,35 @@ describe("Editor Page", () => {
     );
 
     // Wait for initial load to complete
-    await waitFor(() => {
-      expect(screen.queryByText(/Opening your draft/i)).not.toBeInTheDocument();
-    });
+    await waitForElementToBeRemoved(() =>
+      screen.queryByTestId("opening-draft-overlay"),
+    );
 
-    // Initial state: DRAFT (not read-only)
     const canvas = screen.getByTestId("canvas");
     expect(canvas.getAttribute("data-readonly")).toBe("false");
 
-    // Click Seal in the main toolbar (it's in the div with id="writer-toolbar")
     const toolbar = container.querySelector("#writer-toolbar");
     const sealBtn = toolbar?.querySelector(".btn-primary");
     if (!sealBtn) throw new Error("Seal button not found");
     fireEvent.click(sealBtn);
 
     // Click Vault to show confirm modal
-    const vaultBtn = screen.getByRole("button", { name: /vault/i });
+    const vaultBtn = screen.getByTestId("vault-trigger-btn");
     fireEvent.click(vaultBtn);
 
     // Set date and submit vault form
-    const dateInput = container.querySelector('input[name="vault-date"]');
+    const dateInput = document.body.querySelector('input[name="vault-date"]');
     if (!dateInput) throw new Error("Date input not found");
     fireEvent.change(dateInput, { target: { value: "2026-12-31" } });
 
-    const confirmVaultBtn = container.querySelector(
-      'button[form="vault-form"]',
-    );
-    if (!confirmVaultBtn) throw new Error("Confirm vault button not found");
+    const confirmVaultBtn = screen.getByTestId("vault-confirm-btn");
     fireEvent.click(confirmVaultBtn);
 
     // Wait for save to complete and check readOnly
-    await waitFor(() => {
-      expect(screen.getByText(/Your letter is saved/i)).toBeInTheDocument();
-    });
+    expect(await screen.findByTestId("save-success-toast")).toBeInTheDocument();
 
     expect(canvas.getAttribute("data-readonly")).toBe("true");
-    expect(screen.getByLabelText(/recipient/i)).toBeDisabled();
+    expect(screen.getByTestId("recipient-input")).toBeDisabled();
   });
 
   it("should set canvas to readOnly when status is SEALED", async () => {
@@ -134,7 +132,7 @@ describe("Editor Page", () => {
       }),
     );
 
-    const { container } = render(
+    render(
       <MemoryRouter initialEntries={["/write/test-id"]}>
         <Routes>
           <Route path="/write/:public_id" element={<Editor />} />
@@ -142,27 +140,23 @@ describe("Editor Page", () => {
       </MemoryRouter>,
     );
 
-    await waitFor(() => {
-      expect(screen.queryByText(/Opening your draft/i)).not.toBeInTheDocument();
-    });
+    await waitForElementToBeRemoved(() =>
+      screen.queryByTestId("opening-draft-overlay"),
+    );
 
     const canvas = screen.getByTestId("canvas");
 
-    const toolbar = container.querySelector("#writer-toolbar");
-    const sealBtn = toolbar?.querySelector(".btn-primary");
-    if (!sealBtn) throw new Error("Seal button not found");
+    const sealBtn = screen.getByTestId("seal-trigger-btn");
     fireEvent.click(sealBtn);
 
     // The secondary seal button appears (it has btn-accent class)
-    const secondarySealBtn = container.querySelector(".btn-accent");
+    const secondarySealBtn = screen.getByTestId("seal-confirm-btn");
     if (!secondarySealBtn) throw new Error("Secondary seal button not found");
     fireEvent.click(secondarySealBtn);
 
-    await waitFor(() => {
-      expect(screen.getByText(/Your letter is saved/i)).toBeInTheDocument();
-    });
+    expect(await screen.findByTestId("save-success-toast")).toBeInTheDocument();
 
     expect(canvas.getAttribute("data-readonly")).toBe("true");
-    expect(screen.getByLabelText(/recipient/i)).toBeDisabled();
+    expect(screen.getByTestId("recipient-input")).toBeDisabled();
   });
 });

frontend/src/pages/Editor.tsx

@@ -11,7 +11,9 @@ import {
   useParams,
 } from "react-router-dom";
 import { api } from "../api/apiClient";
+import type { LetterResponseData } from "../api/response";
 import {
+  type CanvasStyle,
   type CanvasTools,
   ComposeCanvas,
 } from "../components/editor/ComposeCanvas";
@@ -23,8 +25,8 @@ import {
 } from "../components/editor/ToolBar";
 import DateDisplay from "../components/ui/DateDisplay";
 import { LogModal } from "../components/ui/LogModal";
+import { Modal } from "../components/ui/Modal";
 import { Navbar } from "../components/ui/Navbar";
-
 import { endpoints } from "../config/endpoints";
 import { PATHS } from "../config/routes";
 import { useKeyStore } from "../store/useKeyStore";
@@ -32,11 +34,12 @@ import { CryptoUtils } from "../utils/crypto";
 import { formatRelativeDate } from "../utils/dateFormat";
 import { decryptCanvasImages, encryptCanvasImages } from "../utils/letterLogic";
 
-type SaveOverlay = "idle" | "saving" | "saved" | "error";
+type SaveOverlay = "IDLE" | "SAVING" | "SAVED" | "ERROR";
 
 const OVERLAY_FADE_MS = 250;
 const SAVED_VISIBLE_MS = 1400;
 const ERROR_VISIBLE_MS = 2400;
+const STOP_SAVE_DATE_PULSE_AFTER_MS = 10000;
 
 const toPlaceholderList = [
   "Someone dear...",
@@ -44,6 +47,7 @@ const toPlaceholderList = [
   "Something to bear...",
 ];
 
+const MAX_FILE_SIZE = 10 * 1024 * 1024;
 export default function Editor() {
   const navigate = useNavigate();
   const navigateRef = useRef<NavigateFunction>(navigate);
@@ -69,7 +73,14 @@ export default function Editor() {
   const [lastSavedPulseTick, setLastSavedPulseTick] = useState(0);
   const [sealBtnClicked, setSealBtnClicked] = useState<boolean>(false);
 
-  const [saveOverlay, setSaveOverlay] = useState<SaveOverlay>("idle");
+  const [saveOverlay, setSaveOverlay] = useState<SaveOverlay>("IDLE");
+  const [logStatus, setLogStatus] = useState<{
+    status: "WARN" | "ERROR" | "RESET";
+    message: string;
+  }>({
+    status: "RESET",
+    message: "",
+  });
   const [showSaveOverlay, setShowSaveOverlay] = useState(false);
   const [confirmModal, setConfirmModal] = useState<"VAULT" | "SEAL" | null>(
     null,
@@ -78,13 +89,17 @@ export default function Editor() {
   const [recipient, setRecipient] = useState("");
   const [unlockDate, setUnlockDate] = useState<Date | null>(null);
   const [placeholderIndex, setPlaceholderIndex] = useState(0);
+  const [canvasFontStyle, setCanvasFontStyle] = useState<CanvasStyle>({
+    fontColor: "",
+    fontFamily: "",
+  });
 
   const { masterKey } = useKeyStore();
 
   const canvasRef = useRef<CanvasTools>(null);
   const fileInputRef = useRef<HTMLInputElement>(null);
 
-  // Placeholder rotation
+  // to continuously rotate placeholder text of the recipient input
   useEffect(() => {
     const interval = setInterval(() => {
       setPlaceholderIndex((prev) => (prev + 1) % toPlaceholderList.length);
@@ -93,17 +108,62 @@ export default function Editor() {
     return () => clearInterval(interval);
   }, []);
 
+  // to load existing letter when public_id param and masterKey is available
+  // NOTE: this has to trigger just once after each save
   useEffect(() => {
     if (!(public_id && masterKey)) return;
     if (justSavedRef.current) {
       justSavedRef.current = false;
       return;
     }
+    const decryptAndLoadLetter = async (
+      letterData: LetterResponseData,
+      masterKey: CryptoKey,
+    ) => {
+      const cryptoUtils = new CryptoUtils();
+      const metadata = await cryptoUtils.decryptMetadata(
+        {
+          encrypted_content: letterData.encrypted_metadata,
+          encrypted_dek: letterData.encrypted_dek,
+        },
+        masterKey,
+      );
+      setRecipient(metadata.recipient || "");
+
+      const decryptedJsonStr = await cryptoUtils.decryptLetter(
+        {
+          encrypted_content: letterData.encrypted_content,
+          encrypted_dek: letterData.encrypted_dek,
+        },
+        masterKey,
+      );
+      const canvasData = JSON.parse(decryptedJsonStr);
+
+      const { errors, isPartialFailure, canvasDataWithDecryptedImages } =
+        await decryptCanvasImages(
+          canvasData,
+          letterData.images ?? [],
+          letterData.encrypted_dek,
+          masterKey,
+          cryptoUtils,
+          true,
+        );
+
+      if (isPartialFailure) {
+        setDecryptionStatus({
+          status: "WARN",
+          message: "Failed to decrypt some elements. Please check the render.",
+          log: errors.toString(),
+        });
+      }
+
+      if (canvasRef.current) {
+        await canvasRef.current.loadData(canvasDataWithDecryptedImages);
+      }
+    };
 
     const loadExistingLetter = async () => {
       setIsInitialLoading(true);
-      const cryptoUtils = new CryptoUtils();
-
       try {
         const res = await api.get(`${endpoints.LETTERS}${public_id}/`);
         const letterData = res.data;
@@ -116,90 +176,53 @@ export default function Editor() {
           return;
         }
 
-        if (!letterData.encrypted_dek) {
-          return;
+        if (letterData.encrypted_dek && masterKey) {
+          await decryptAndLoadLetter(letterData, masterKey);
         }
-
-        const metadata = await cryptoUtils.decryptMetadata(
-          {
-            encrypted_content: letterData.encrypted_metadata,
-            encrypted_dek: letterData.encrypted_dek,
-          },
-          masterKey,
-        );
-        setRecipient(metadata.recipient || "");
-
-        const decryptedJsonStr = await cryptoUtils.decryptLetter(
-          {
-            encrypted_content: letterData.encrypted_content,
-            encrypted_dek: letterData.encrypted_dek,
-          },
-          masterKey,
-        );
-        const canvasData = JSON.parse(decryptedJsonStr);
-
-        const { isDecryptionPartialFailure, error } = await decryptCanvasImages(
-          canvasData,
-          letterData.images ?? [],
-          letterData.encrypted_dek,
-          masterKey,
-          cryptoUtils,
-          true,
-        );
-
-        if (isDecryptionPartialFailure) {
-          setDecryptionStatus({
-            status: "WARN",
-            message:
-              "Failed to decrypt some elements. Please check the render.",
-            log: error,
-          });
-        }
-
-        if (canvasRef.current) {
-          await canvasRef.current.loadData(canvasData);
-        }
-      } catch (_err) {
+      } catch (err) {
         setDecryptionStatus({
           status: "ERROR",
           message: "Failed to decrypt letter. Please try again later.",
-          log: _err instanceof Error ? _err.message : "Unknown error",
+          log: err instanceof Error ? err.message : "Unknown error",
         });
       } finally {
         setIsInitialLoading(false);
       }
     };
-
-    loadExistingLetter();
+    loadExistingLetter().then((_) => {
+      if (canvasRef.current) {
+        setCanvasFontStyle(canvasRef.current.getStyle());
+      }
+    });
   }, [public_id, masterKey]);
 
+  // to trigger short pulse animation for Last Saved AT element
   useEffect(() => {
     if (lastSavedPulseTick === 0) return;
-
     setIsSaveDatePulsing(true);
 
     const timer = setTimeout(() => {
       setIsSaveDatePulsing(false);
-    }, 10000);
+    }, STOP_SAVE_DATE_PULSE_AFTER_MS);
 
     return () => clearTimeout(timer);
   }, [lastSavedPulseTick]);
 
+  // to fade in and fade out the save status overlay after each save operation
+  // Note: otherwise the fade efect is abrupt due to component's immediate unmount
   useEffect(() => {
-    if (saveOverlay === "idle" || saveOverlay === "saving") return;
-
+    if (saveOverlay === "IDLE" || saveOverlay === "SAVING") return;
     const visibleTimer = setTimeout(
       () => {
         setShowSaveOverlay(false);
       },
-      saveOverlay === "saved" ? SAVED_VISIBLE_MS : ERROR_VISIBLE_MS,
+      saveOverlay === "SAVED" ? SAVED_VISIBLE_MS : ERROR_VISIBLE_MS,
     );
-
     const unmountTimer = setTimeout(
       () => {
-        setSaveOverlay("idle");
+        setSaveOverlay("IDLE");
       },
-      (saveOverlay === "saved" ? SAVED_VISIBLE_MS : ERROR_VISIBLE_MS) +
+      (saveOverlay === "SAVED" ? SAVED_VISIBLE_MS : ERROR_VISIBLE_MS) +
         OVERLAY_FADE_MS,
     );
 
@@ -211,79 +234,90 @@ export default function Editor() {
 
   const handleImageUpload = (e: React.ChangeEvent<HTMLInputElement>) => {
     const file = e.target.files?.[0];
-    if (file) {
+    if (file && file.size < MAX_FILE_SIZE) {
       const url = URL.createObjectURL(file);
       canvasRef.current?.addImage(url, file);
+    } else {
+      setLogStatus({
+        status: "WARN",
+        message: "Please upload images with size less than 10MB.",
+      });
     }
   };
 
+  const getRequestData = async (
+    targetId: string,
+    status: string,
+    vaultDate?: Date,
+  ): Promise<FormData> => {
+    const cryptoUtils = new CryptoUtils();
+    await cryptoUtils.initialize();
+
+    const canvasData = (await canvasRef.current?.getData()) || { objects: [] };
+    const canvasImages = canvasRef.current?.getImages() || [];
+
+    const { encryptedImageFiles, encryptedCanvasData } =
+      await encryptCanvasImages(
+        canvasData,
+        canvasImages,
+        // biome-ignore lint/style/noNonNullAssertion: masterkey can never be null here
+        masterKey!,
+        cryptoUtils,
+      );
+
+    const encrypted_letter = await cryptoUtils.encryptLetter(
+      JSON.stringify(encryptedCanvasData),
+      // biome-ignore lint/style/noNonNullAssertion: masterkey can never be null here
+      masterKey!,
+    );
+
+    const encrypted_metadata = await cryptoUtils.encryptMetadata(
+      { recipient, tags: [] },
+      // biome-ignore lint/style/noNonNullAssertion: masterkey can never be null here
+      masterKey!,
+    );
+
+    const formData = new FormData();
+    if (status === "VAULT") {
+      const finalDate = vaultDate || unlockDate;
+      formData.append("type", "VAULT");
+      if (finalDate) formData.append("unlock_at", finalDate.toISOString());
+      formData.append("status", "SEALED");
+    } else {
+      formData.append("type", "KEPT");
+      formData.append("status", status);
+    }
+
+    formData.append("public_id", targetId);
+    formData.append("encrypted_content", encrypted_letter.encrypted_content);
+    formData.append("encrypted_dek", encrypted_letter.encrypted_dek);
+    formData.append("encrypted_metadata", encrypted_metadata.encrypted_content);
+
+    encryptedImageFiles.forEach((blob, filename) => {
+      formData.append("image_files", blob, filename);
+    });
+
+    return formData;
+  };
+
   const handleSave = async (
     status: "SEALED" | "DRAFT" | "VAULT",
     vaultDate?: Date,
   ): Promise<void> => {
     setSealBtnClicked(false);
+    // use the letter's id if an existing letter or create a new id
+    const targetId = public_id || letterIdRef.current || crypto.randomUUID();
 
-    let targetId = public_id || letterIdRef.current;
-    if (!targetId) {
-      targetId = crypto.randomUUID();
-    }
+    if (saveOverlay === "SAVING" || !masterKey) return;
 
-    if (saveOverlay === "saving" || !masterKey) return;
-
-    setSaveOverlay("saving");
+    setSaveOverlay("SAVING");
     setShowSaveOverlay(true);
 
-    const cryptoUtils = new CryptoUtils();
-    await cryptoUtils.initialize();
-
     try {
-      const canvasData = canvasRef.current?.getData() || { objects: [] };
-      const canvasImages = canvasRef.current?.getImages() || [];
-
-      const encImageFilesMap = await encryptCanvasImages(
-        canvasData,
-        canvasImages,
-        masterKey,
-        cryptoUtils,
-      );
-
-      const encrypted_letter = await cryptoUtils.encryptLetter(
-        JSON.stringify(canvasData),
-        masterKey,
-      );
-
-      const encrypted_metadata = await cryptoUtils.encryptMetadata(
-        { recipient, tags: [] },
-        masterKey,
-      );
-
-      const formData = new FormData();
-      if (status === "VAULT") {
-        const finalDate = vaultDate || unlockDate;
-        formData.append("type", "VAULT");
-        if (finalDate) {
-          formData.append("unlock_at", finalDate.toISOString());
-        }
-        formData.append("status", "SEALED");
-      } else {
-        formData.append("type", "KEPT");
-        formData.append("status", status);
-      }
-      formData.append("public_id", targetId);
-      formData.append("encrypted_content", encrypted_letter.encrypted_content);
-      formData.append("encrypted_dek", encrypted_letter.encrypted_dek);
-      formData.append(
-        "encrypted_metadata",
-        encrypted_metadata.encrypted_content,
-      );
-
-      encImageFilesMap.forEach((blob, filename) => {
-        formData.append("image_files", blob, filename);
-      });
-
+      const formData = await getRequestData(targetId, status, vaultDate);
       await api.put(`${endpoints.LETTERS}${targetId}/`, formData);
-      justSavedRef.current = true;
 
+      justSavedRef.current = true;
       if (!public_id) {
         letterIdRef.current = targetId;
         navigate(PATHS.write(targetId), { replace: true });
@@ -293,13 +327,13 @@ export default function Editor() {
       setLetterStatus(status);
       setLastSavedPulseTick((prev) => prev + 1);
 
-      if (status === "SEALED") {
+      if (status === "SEALED" || status === "VAULT") {
         setSealedTargetId(targetId);
       }
-      setSaveOverlay("saved");
+      setSaveOverlay("SAVED");
       setShowSaveOverlay(true);
-    } catch (_error) {
-      setSaveOverlay("error");
+    } catch {
+      setSaveOverlay("ERROR");
       setShowSaveOverlay(true);
     }
   };
@@ -313,8 +347,8 @@ export default function Editor() {
               isSaveDatePulsing ? "animate-pulse" : ""
             }`}
           >
-            <div className="text-sm text-neutral-content/30 flex-col justify-end leading-none text-right">
-              <span className="text-[10px] uppercase tracking-widest font-bold">
+            <div className="text-xxs text-neutral-content/30 flex-col justify-end leading-none text-right">
+              <span className="uppercase tracking-widest font-bold">
                 Last Save
               </span>
               <br />
@@ -348,67 +382,65 @@ export default function Editor() {
                 weight="bold"
                 className="animate-spin text-primary"
               />
-              <p className="text-[10px] uppercase tracking-[0.4em] font-bold text-base-content/40">
+              <p
+                data-testid="opening-draft-overlay"
+                className="text-xxs uppercase tracking-widester font-bold text-base-content/40"
+              >
                 Opening your draft...
               </p>
             </div>
           </div>
         )}
 
-        {saveOverlay !== "idle" && (
-          <div
-            className={`modal modal-open bg-base-100/20 backdrop-blur-md transition-opacity duration-300 ${
-              showSaveOverlay ? "opacity-100" : "opacity-0"
-            }`}
-          >
-            <div className="modal-box p-0 bg-transparent shadow-none transition-all duration-300">
-              {saveOverlay === "saving" && (
-                <div
-                  role="alert"
-                  className={`alert text-center alert-neutral shadow-lg transition-all ease-in-out duration-2000 ${
-                    showSaveOverlay
-                      ? "opacity-100 scale-100 translate-y-0"
-                      : "opacity-0 scale-95 translate-y-1"
-                  }`}
-                >
-                  <SpinnerGapIcon
-                    size={18}
-                    weight="bold"
-                    className="animate-spin"
-                  />
-                  <span className="font-bold">Securing your letter...</span>
-                </div>
-              )}
+        {saveOverlay !== "IDLE" && (
+          <Modal isOpen={showSaveOverlay}>
+            {saveOverlay === "SAVING" && (
+              <div
+                role="alert"
+                className={`alert text-center alert-neutral shadow-lg transition-all ease-in-out duration-2000 ${
+                  showSaveOverlay
+                    ? "opacity-100 scale-100 translate-y-0"
+                    : "opacity-0 scale-95 translate-y-1"
+                }`}
+              >
+                <SpinnerGapIcon
+                  size={18}
+                  weight="bold"
+                  className="animate-spin"
+                />
+                <span className="font-bold">Securing your letter...</span>
+              </div>
+            )}
 
-              {saveOverlay === "saved" && (
-                <div
-                  role="alert"
-                  className={`alert alert-success shadow-lg transition-all ease-in-out duration-2000 ${
-                    showSaveOverlay
-                      ? "opacity-100 scale-100 translate-y-0"
-                      : "opacity-0 scale-95 translate-y-1"
-                  }`}
-                >
-                  <DownloadSimpleIcon size={18} weight="bold" />
-                  <span className="font-bold">Your letter is saved!</span>
-                </div>
-              )}
+            {saveOverlay === "SAVED" && (
+              <div
+                role="alert"
+                data-testid="save-success-toast"
+                className={`alert alert-success shadow-lg transition-all ease-in-out duration-2000 ${
+                  showSaveOverlay
+                    ? "opacity-100 scale-100 translate-y-0"
+                    : "opacity-0 scale-95 translate-y-1"
+                }`}
+              >
+                <DownloadSimpleIcon size={18} weight="bold" />
+                <span className="font-bold">Your letter is saved!</span>
+              </div>
+            )}
 
-              {saveOverlay === "error" && (
-                <div
-                  role="alert"
-                  className={`alert alert-error shadow-lg transition-all duration-300 ${
-                    showSaveOverlay
-                      ? "opacity-100 scale-100 translate-y-0"
-                      : "opacity-0 scale-95 translate-y-1"
-                  }`}
-                >
-                  <XIcon size={18} weight="bold" />
-                  <span className="font-bold">Failed to save letter</span>
-                </div>
-              )}
-            </div>
-          </div>
+            {saveOverlay === "ERROR" && (
+              <div
+                role="alert"
+                className={`alert alert-error shadow-lg transition-all duration-300 ${
+                  showSaveOverlay
+                    ? "opacity-100 scale-100 translate-y-0"
+                    : "opacity-0 scale-95 translate-y-1"
+                }`}
+              >
+                <XIcon size={18} weight="bold" />
+                <span className="font-bold">Failed to save letter</span>
+              </div>
+            )}
+          </Modal>
         )}
 
         {confirmModal === "VAULT" && (
@@ -419,7 +451,11 @@ export default function Editor() {
           />
         )}
         {sealedTargetId && (
-          <PostSealModal sealedTargetId={sealedTargetId} navigate={navigate} />
+          <PostSealModal
+            sealedTargetId={sealedTargetId}
+            navigate={navigate}
+            type={status === "VAULT" ? "VAULT" : "KEPT"}
+          />
         )}
 
         <div className="max-w-180 mx-auto px-1 md:px-0">
@@ -427,12 +463,13 @@ export default function Editor() {
             <div className="flex flex-col gap-2 flex-1">
               <label
                 htmlFor="recipient"
-                className="text-[10px] uppercase tracking-[0.4em] text-secondary-content font-bold"
+                className="text-xxs uppercase tracking-widester text-secondary-content font-bold"
               >
                 Recipient
               </label>
               <input
                 id="recipient"
+                data-testid="recipient-input"
                 type="text"
                 placeholder={toPlaceholderList[placeholderIndex]}
                 value={recipient}
@@ -446,11 +483,13 @@ export default function Editor() {
 
           {status === "DRAFT" ? (
             <ToolBar
-              fileInputRef={fileInputRef}
+              onAddImage={() => fileInputRef.current?.click()}
               sealBtnClicked={sealBtnClicked}
               setSealBtnClicked={setSealBtnClicked}
               onSave={handleSave}
               setConfirmModal={setConfirmModal}
+              onFontChange={setCanvasFontStyle}
+              latestFontStyle={canvasFontStyle}
             />
           ) : (
             <LetterHead />
@@ -464,9 +503,25 @@ export default function Editor() {
             className="hidden"
           />
 
-          <ComposeCanvas ref={canvasRef} readOnly={status !== "DRAFT"} />
+          <ComposeCanvas
+            ref={canvasRef}
+            readOnly={status !== "DRAFT"}
+            style={canvasFontStyle}
+          />
         </div>
       </section>
+      <LogModal
+        status={logStatus.status}
+        message={logStatus.message}
+        log={""}
+        onClose={() =>
+          setLogStatus({
+            status: "RESET",
+            message: "",
+          })
+        }
+        isOpen={logStatus.status !== "RESET"}
+      />
     </>
   );
 }

frontend/src/pages/Home.tsx

@@ -1,9 +1,400 @@
+import { InfoIcon } from "@phosphor-icons/react";
+import { ReactLenis } from "lenis/react";
+import {
+  motion,
+  useMotionValueEvent,
+  useScroll,
+  useTransform,
+} from "motion/react";
+import { useRef, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import letterSample from "../assets/screenshots/letter.webp";
 import Logo from "../components/Logo";
+import { EnvelopeReveal } from "../components/reader/EnvelopeReveal";
+import Saajan from "../components/ui/Saajan";
+import { ROUTES } from "../config/routes";
+import { formatDate } from "../utils/dateFormat";
+
+import "@fontsource/space-mono/index.css";
+import "@fontsource/architects-daughter/index.css";
 
 export default function Home() {
+  const sectionContainer1 = useRef<HTMLDivElement>(null);
+  const { scrollYProgress } = useScroll({
+    target: sectionContainer1,
+  });
+  const [isEnvelopeFlipped, setIsEnvelopeFlipped] = useState(true);
+  const [flapOpen, setFlapOpen] = useState(false);
+  const [recipient, setRecipient] = useState("someone dear");
+  const [ignite, setIgnite] = useState(false);
+
+  const navigate = useNavigate();
+
+  useMotionValueEvent(scrollYProgress, "change", (latestScrollValue) => {
+    if (latestScrollValue > 0.54) {
+      setFlapOpen(false);
+    } else {
+      setFlapOpen(true);
+    }
+    if (latestScrollValue <= 0.6) {
+      setIsEnvelopeFlipped(true);
+    } else {
+      setIsEnvelopeFlipped(false);
+    }
+    if (latestScrollValue > 0.68) {
+      setRecipient("future me");
+    } else {
+      setRecipient("someone dear");
+    }
+    if (latestScrollValue > 0.77) {
+      setIgnite(true);
+    } else {
+      setIgnite(false);
+    }
+  });
+
   return (
-    <div>
-      <Logo />
-    </div>
+    <ReactLenis root options={{ lerp: 0.1, duration: 1.5, smoothWheel: true }}>
+      <section
+        ref={sectionContainer1}
+        className="relative w-full h-[850vh] bg-base-100 font-serif text-neutral-content/90"
+      >
+        <div className="sticky top-0 h-screen w-full flex flex-col items-center justify-center overflow-hidden">
+          {/*  Intro */}
+          <motion.div
+            className="absolute flex flex-col items-center justify-center pointer-events-none"
+            style={{
+              opacity: useTransform(scrollYProgress, [0, 0.12, 1], [1, 0, 0]),
+              scale: useTransform(scrollYProgress, [0, 0.12], [1, 10]),
+            }}
+          >
+            <h1 className="text-neutral text-4xl md:text-6xl text-center px-6">
+              You've been carrying something
+            </h1>
+            <motion.h2 className="text-primary text-5xl md:text-7xl mt-4 italic font-display font-light">
+              unsaid
+            </motion.h2>
+          </motion.div>
+
+          <motion.div
+            className="absolute text-center"
+            style={{
+              opacity: useTransform(scrollYProgress, [0, 0.15, 0.2], [0, 1, 0]),
+              y: useTransform(scrollYProgress, [0, 0.15, 0.2], [40, 0, -40]),
+              scale: useTransform(scrollYProgress, [0, 0.15, 0.2], [0.8, 1, 3]),
+            }}
+          >
+            <div className="mt-6 text-4xl md:text-6xl text-base-content/60 italic">
+              and that's okay...
+            </div>
+          </motion.div>
+          {/*  pi. ku. */}
+          <motion.div
+            className="absolute text-center px-6"
+            style={{
+              opacity: useTransform(
+                scrollYProgress,
+                [0.18, 0.25, 0.3],
+                [0, 1, 0],
+              ),
+              y: useTransform(scrollYProgress, [0.18, 0.25, 0.3], [20, 0, -20]),
+            }}
+            transition={{ delay: 4 }}
+          >
+            <Logo type="logo" scale={1.5} ul={true} />
+            <motion.div
+              className="font-serif italic font-extralight mt-6 text-4xl md:text-6xl text-neutral "
+              style={{
+                opacity: useTransform(
+                  scrollYProgress,
+                  [0.22, 0.25, 0.35, 0.4],
+                  [0, 1, 1, 0],
+                ),
+                y: useTransform(
+                  scrollYProgress,
+                  [0.25, 0.3, 0.35, 0.4],
+                  [20, 0, 0, -20],
+                ),
+              }}
+            >
+              is a{"  "}
+              <span className="font-display text-primary font-extralight">
+                safe space
+              </span>
+              ,<br />
+              <motion.span
+                className="opacity-0 text-2xl md:text-4xl font-hand tracking-widest italic text-neutral"
+                transition={{ delay: 5 }}
+                whileInView={{ opacity: 1 }}
+                viewport={{ once: false, amount: 0.3 }}
+              >
+                where you can
+              </motion.span>
+            </motion.div>
+          </motion.div>
+
+          <div className="relative w-full max-w-5xl h-1/2 flex items-center justify-center mt-20">
+            <motion.h2
+              style={{
+                opacity: useTransform(
+                  scrollYProgress,
+                  [0.3, 0.35, 0.4, 0.45],
+                  [0, 1, 1, 0],
+                ),
+                y: useTransform(
+                  scrollYProgress,
+                  [0.3, 0.35, 0.4, 0.45],
+                  [40, 0, 0, -40],
+                ),
+              }}
+              className="absolute text-4xl md:text-6xl text-center px-10 leading-tight"
+            >
+              pen down your unsaid words into&nbsp;
+              <span className="font-display text-primary font-extralight">
+                letters
+              </span>
+              .
+            </motion.h2>
+            {/*  Seal */}
+            <motion.h2
+              style={{
+                opacity: useTransform(
+                  scrollYProgress,
+                  [0.45, 0.5, 0.55, 0.6],
+                  [0, 1, 1, 0],
+                ),
+                y: useTransform(
+                  scrollYProgress,
+                  [0.45, 0.5, 0.55, 0.6],
+                  [40, 0, 0, -40],
+                ),
+              }}
+              className="absolute text-4xl md:text-6xl text-center px-10 leading-tight"
+            >
+              seal it&nbsp;
+              <span className="text-success font-mono tracking-tighter font-extrabold">
+                secure
+              </span>
+              &nbsp; and&nbsp;
+              <span className="text-info font-mono tracking-tighter italic">
+                private
+              </span>
+              .
+            </motion.h2>
+            {/*  Send / vault */}
+            <motion.h2
+              style={{
+                opacity: useTransform(
+                  scrollYProgress,
+                  [0.6, 0.63, 0.72, 0.75],
+                  [0, 1, 1, 0],
+                ),
+                y: useTransform(
+                  scrollYProgress,
+                  [0.6, 0.63, 0.72, 0.75],
+                  [40, 0, 0, -40],
+                ),
+              }}
+              className="absolute text-4xl md:text-6xl text-center px-10 leading-tight"
+            >
+              send it to&nbsp;
+              <motion.span
+                className="font-display text-accent"
+                style={{
+                  color: useTransform(
+                    scrollYProgress,
+                    [0.67, 1],
+                    ["var(--color-accent)", "var(--color-neutral)"],
+                  ),
+                }}
+              >
+                someone dear
+              </motion.span>
+              <motion.span
+                style={{
+                  opacity: useTransform(scrollYProgress, [0.66, 0.7], [0, 1]),
+                }}
+              >
+                <motion.span
+                  className="font-display text-accent"
+                  style={{
+                    color: useTransform(
+                      scrollYProgress,
+                      [0.67, 1],
+                      ["var(--color-accent)", "var(--color-neutral)"],
+                    ),
+                  }}
+                >
+                  &nbsp; or&nbsp;
+                </motion.span>
+                <span className="font-display text-success">
+                  yourself in the future
+                </span>
+                .
+              </motion.span>
+            </motion.h2>
+            {/*  Burn */}
+            <motion.h2
+              style={{
+                opacity: useTransform(
+                  scrollYProgress,
+                  [0.75, 0.8, 0.85, 0.9],
+                  [0, 1, 1, 0],
+                ),
+                y: useTransform(
+                  scrollYProgress,
+                  [0.75, 0.8, 0.85, 0.9],
+                  [40, 0, 0, -40],
+                ),
+              }}
+              className="absolute text-4xl md:text-6xl text-center px-10 leading-tight"
+            >
+              and even <span className="font-display text-error">burn it</span>
+              &nbsp; to release the burden.
+            </motion.h2>
+            {/*  Outro  */}
+            <motion.h2
+              className={
+                "italic absolute text-4xl md:text-6xl text-center px-10 leading-tight text-neutral-content/50"
+              }
+              style={{
+                opacity: useTransform(scrollYProgress, [0.9, 1], [0, 1]),
+                y: useTransform(scrollYProgress, [0.9, 1], [80, 0]),
+              }}
+            >
+              You've been carrying it long enough.
+            </motion.h2>
+            {/* CTA */}
+            <motion.div
+              className={
+                "z-100 absolute -bottom-12 md:bottom-0 font-hand flex flex-wrap md:flex-nowrap gap-4 md:gap-12 justify-center"
+              }
+              style={{
+                opacity: useTransform(scrollYProgress, [0.98, 1], [0, 1]),
+                y: useTransform(scrollYProgress, [0.98, 1], [80, 0]),
+                display: useTransform(
+                  scrollYProgress,
+                  [0.96, 1],
+                  ["none", "flex"],
+                ),
+              }}
+            >
+              <button
+                className={
+                  "md:opacity-50 hover:opacity-100 btn btn-ghost btn-wide md:btn-xl rounded-full font-extralight md:grayscale hover:grayscale-0 hover:-translate-y-1 transition-all duration-1000"
+                }
+                type={"button"}
+                onClick={() => navigate(ROUTES.ABOUT, { replace: true })}
+              >
+                <InfoIcon className={"text-primary"} />
+                Tell me More
+              </button>
+              <button
+                className={
+                  "md:opacity-50 hover:opacity-100 btn rounded-full btn-primary btn-wide md:btn-xl md:grayscale-50 hover:grayscale-0 focus:grayscale-0 active:grayscale-0 hover:-translate-y-1 transition-all duration-1000"
+                }
+                type={"button"}
+                onClick={() => navigate(ROUTES.ONBOARD, { replace: true })}
+              >
+                I'm ready
+              </button>
+            </motion.div>
+          </div>
+
+          <div className="relative h-1/4 w-full flex flex-col items-center justify-center pointer-events-none">
+            <motion.div
+              className={"z-21 absolute"}
+              style={{
+                opacity: useTransform(
+                  scrollYProgress,
+                  [0.3, 0.4, 0.5, 0.52],
+                  [0, 1, 0.1, 0],
+                ),
+                y: useTransform(
+                  scrollYProgress,
+                  [0.3, 0.45, 0.5],
+                  [300, 0, 200],
+                ),
+                scale: useTransform(
+                  scrollYProgress,
+                  [0.3, 0.4, 0.5],
+                  [1, 1, 0.6],
+                ),
+              }}
+            >
+              <div className="mockup-phone w-[75vw] border-primary">
+                <div className="mockup-phone-camera"></div>
+                <div className="mockup-phone-display">
+                  <img alt="letter" src={letterSample} />
+                </div>
+              </div>
+            </motion.div>
+            {/*  Envelope */}
+            <motion.div
+              className="absolute scale-50 md:scale-80 z-10"
+              style={{
+                opacity: useTransform(
+                  scrollYProgress,
+                  [0.4, 0.45, 0.5, 0.7, 0.9, 1],
+                  [0, 0.6, 1, 1, 0.3, 0],
+                ),
+                y: useTransform(scrollYProgress, [0.45, 0.5, 1], [600, 200, 0]),
+              }}
+            >
+              <EnvelopeReveal
+                isInteractive={false}
+                ignite={ignite}
+                recipient={recipient}
+                date={formatDate(new Date().toISOString())}
+                onRevealComplete={() => {}}
+                isFlip={isEnvelopeFlipped}
+                openFlap={flapOpen}
+              />
+            </motion.div>
+            {/*  Saajan */}
+            <motion.div
+              className="fixed bottom-0 z-10 font-sans -mb-6 scale-85 md:scale-100 md:mb-0"
+              style={{
+                opacity: useTransform(
+                  scrollYProgress,
+                  [0.98, 0.995, 1],
+                  [0, 0.5, 1],
+                ),
+                y: useTransform(scrollYProgress, [0.98, 1], [50, -10]),
+              }}
+            >
+              <Saajan
+                message={
+                  "I think we forget things\nif there is nobody to tell them."
+                }
+                position={"top"}
+              />
+            </motion.div>
+            {/*  Orb */}
+            <motion.div
+              className="w-48 z-100 h-48 rounded-full blur-3xl opacity-20"
+              transition={{
+                backgroundColor: { ease: "easeIn", duration: 2 },
+              }}
+              style={{
+                backgroundColor: useTransform(
+                  scrollYProgress,
+                  [0.45, 0.5, 0.7, 0.75, 1],
+                  [
+                    "var(--color-primary)",
+                    "var(--color-secondary)",
+                    "var(--color-accent)",
+                    "var(--color-success)",
+                    "var(--color-error)",
+                  ],
+                ),
+                scale: useTransform(scrollYProgress, [0, 1], [0.6, 2.5]),
+              }}
+            />
+            <div className="absolute border border-primary/5 w-64 h-64 rounded-full backdrop-blur-[1px]" />
+          </div>
+        </div>
+      </section>
+    </ReactLenis>
   );
 }

frontend/src/pages/Login.test.tsx

@@ -14,16 +14,6 @@ describe("Login Page", () => {
     server.resetHandlers();
   });
 
-  it("should render the sign-in form correctly", () => {
-    render(
-      <MemoryRouter>
-        <Login />
-      </MemoryRouter>,
-    );
-
-    expect(screen.getByText("Sign in to")).toBeInTheDocument();
-  });
-
   it("should display a technical issues message when the server is down", async () => {
     server.use(
       http.post(`${API_URL}${endpoints.LOGIN}`, () =>
@@ -37,11 +27,13 @@ describe("Login Page", () => {
       </MemoryRouter>,
     );
 
-    await userEvent.type(screen.getByLabelText(/email/i), "test@example.com");
-    await userEvent.type(screen.getByLabelText(/password/i), "password123");
-    await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
+    await userEvent.type(screen.getByTestId("email-input"), "test@example.com");
+    await userEvent.type(screen.getByTestId("password-input"), "password123");
+    await userEvent.click(screen.getByTestId("login-submit-btn"));
 
-    expect(await screen.findByText(/technical issues/i)).toBeInTheDocument();
+    expect(await screen.findByTestId("login-error-message")).toHaveTextContent(
+      /technical issues/i,
+    );
   });
 
   it.each([
@@ -83,16 +75,24 @@ describe("Login Page", () => {
       >
         <Routes>
           <Route path="/login" element={<Login />} />
-          <Route path="/drawer" element={<div>Drawer</div>} />
-          <Route path="/read/:publicId" element={<div>Reader</div>} />
+          <Route
+            path="/drawer"
+            element={<div data-testid="drawer-page">Drawer</div>}
+          />
+          <Route
+            path="/read/:publicId"
+            element={<div data-testid="reader-page">Reader</div>}
+          />
         </Routes>
       </MemoryRouter>,
     );
 
-    await userEvent.type(screen.getByLabelText(/email/i), "test@example.com");
-    await userEvent.type(screen.getByLabelText(/password/i), "password123");
-    await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
+    await userEvent.type(screen.getByTestId("email-input"), "test@example.com");
+    await userEvent.type(screen.getByTestId("password-input"), "password123");
+    await userEvent.click(screen.getByTestId("login-submit-btn"));
 
-    expect(await screen.findByText(nextRoute)).toBeInTheDocument();
+    const expectedTestId =
+      nextRoute.toLowerCase() === "drawer" ? "drawer-page" : "reader-page";
+    expect(await screen.findByTestId(expectedTestId)).toBeInTheDocument();
   });
 });

frontend/src/pages/Login.tsx

@@ -1,5 +1,5 @@
 import { zodResolver } from "@hookform/resolvers/zod";
-import { ShieldCheckIcon, WarningIcon } from "@phosphor-icons/react";
+
 import axios from "axios";
 import { useState } from "react";
 import { useForm } from "react-hook-form";
@@ -7,7 +7,9 @@ import { useLocation, useNavigate } from "react-router-dom";
 import { z } from "zod";
 import { api, publicApi } from "../api/apiClient";
 import Logo from "../components/Logo";
+import WelcomeModal from "../components/login/WelcomeModal";
 import FormField from "../components/ui/FormField";
+import Saajan from "../components/ui/Saajan";
 import { endpoints } from "../config/endpoints";
 import { ROUTES } from "../config/routes";
 import { useAuth } from "../hooks/useAuth";
@@ -20,57 +22,6 @@ const loginSchema = z.object({
 
 type LoginInputs = z.infer<typeof loginSchema>;
 
-function WelcomeModal({ setShowWelcome }) {
-  return (
-    <div className="modal modal-open backdrop-blur-sm transition-all duration-1000">
-      <div className="modal-box border border-primary/20 shadow-2xl p-8">
-        <div className="flex flex-col items-center text-center gap-4">
-          <div className="bg-primary/10 p-4 rounded-full animate-pulse">
-            <ShieldCheckIcon
-              size={48}
-              weight="duotone"
-              className="text-primary"
-            />
-          </div>
-          <h3 className="font-display text-2xl font-bold text-primary">
-            Welcome to <Logo />!
-          </h3>
-          <p className="text-base-content/80 leading-relaxed">
-            To ensure <span className="font-bold">complete privacy</span>, all
-            your letters are{" "}
-            <span className="font-bold underline">
-              sealed with your password
-            </span>
-            , which only you have access to.
-            <br />
-            <span className="font-bold">
-              The server never sees it, and it's a solemn promise!
-            </span>
-          </p>
-
-          <div className="alert alert-warning bg-paper/20 border-paper/20 flex items-start gap-3 text-left py-3">
-            <WarningIcon size={24} weight="fill" className="shrink-0 mt-0.5" />
-            <p className="text-sm font-medium text-primary-content">
-              If you ever happen to forget your password, your letters are lost
-              to time, forever.
-            </p>
-          </div>
-
-          <div className="modal-action w-full">
-            <button
-              type="button"
-              onClick={() => setShowWelcome(false)}
-              className="btn btn-primary w-full shadow-lg"
-            >
-              I understand
-            </button>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-
 export default function Login() {
   const navigate = useNavigate();
   const location = useLocation();
@@ -78,6 +29,9 @@ export default function Login() {
   const [apiError, setApiError] = useState<string | null>(null);
   const { setAuthStore } = useAuth();
   const [showWelcome, setShowWelcome] = useState(!!location.state?.firstTime);
+  const [saajanMessage, setSaajanMessage] = useState<string>(
+    "I was wondering when you'd return.",
+  );
   const nextRoute = location.state?.redirectUrl || ROUTES.DRAWER;
 
   const {
@@ -92,7 +46,7 @@ export default function Login() {
     setIsLoading(true);
     setApiError(null);
     try {
-      // client side key derivation for 0 knowledge
+      // client side key derivation for e2e encryption
       const { masterKey, authHash } = await CryptoUtils.deriveKeyBundle(
         data.password,
         data.email,
@@ -108,10 +62,9 @@ export default function Login() {
         headers: { Authorization: `Bearer ${authData.access}` },
       });
 
-      // store the auth related data
       await setAuthStore(authData.access, userData, masterKey);
 
-      navigate(nextRoute, { replace: true });
+      navigate(nextRoute, { replace: true, state: location.state });
     } catch (err) {
       let message =
         "Sorry, we're experiencing technical issues.\nPlease try again later.";
@@ -125,34 +78,41 @@ export default function Login() {
   };
 
   return (
-    <div className="flex flex-col gap-3">
+    <div className="flex flex-col items-center">
+      {!showWelcome && <Saajan message={saajanMessage} position="top" />}
       {showWelcome && <WelcomeModal setShowWelcome={setShowWelcome} />}
       <div className="glass-card w-full max-w-sm p-2 transition-all duration-500 hover:shadow-2xl fade-zoom">
         <form onSubmit={handleSubmit(onSubmit)} className="card-body gap-4">
-          <h1 className="card-title font-display text-2xl justify-center text-primary/80 tracking-tight">
-            Sign in to <Logo />
+          <h1 className="flex items-center font-display text-2xl justify-center text-primary/80 tracking-tight">
+            &nbsp;&nbsp;Enter <Logo type="logo" scale={0.7} /> Archive
           </h1>
 
           {apiError && (
             <div className="alert alert-error text-xs py-2 rounded-md">
-              <span>{apiError}</span>
+              <span data-testid="login-error-message">{apiError}</span>
             </div>
           )}
 
           <FormField
             label="Email"
             type="email"
-            placeholder="you@email.com"
+            placeholder="f.kafka@wrongtrain.com"
+            data-testid="email-input"
             registration={register("email")}
             error={errors.email?.message}
+            handleFocus={() => setSaajanMessage("I remember you.")}
           />
 
           <FormField
             label="Password"
             type="password"
             placeholder="••••••••"
+            data-testid="password-input"
             registration={register("password")}
             error={errors.password?.message}
+            handleFocus={() =>
+              setSaajanMessage("The one thing I cannot know for you.")
+            }
           />
 
           <div className="card-actions mt-4">
@@ -160,27 +120,29 @@ export default function Login() {
               type="submit"
               name="login"
               disabled={isLoading}
-              aria-label="Sign In"
+              data-testid="login-submit-btn"
               className="btn btn-primary w-full shadow-lg"
             >
               {isLoading ? (
                 <span className="loading loading-spinner loading-sm" />
               ) : (
-                "Sign In"
+                "Continue"
               )}
             </button>
           </div>
-
-          <div className="text-center text-sm font-medium text-base-content/70">
-            Don't have an account?{" "}
+          <div className="divider text-neutral my-0">or</div>
+          <div className="text-center text-sm font-medium text-neutral">
+            New to <Logo type="inline" />
+            ?&nbsp;
             <button
               type="button"
               name="register"
               onClick={() => navigate(ROUTES.ONBOARD)}
-              className="link link-primary no-underline hover:underline font-bold"
+              className="link link-primary"
             >
-              Register
+              Start here
             </button>
+            .
           </div>
         </form>
       </div>

frontend/src/pages/Reader.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen, waitFor } from "@testing-library/react";
+import { render, screen } from "@testing-library/react";
 import { HttpResponse, http } from "msw";
 import { MemoryRouter, Route, Routes, useLocation } from "react-router-dom";
 import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -76,9 +76,9 @@ describe("Reader Page", () => {
         </Routes>
       </MemoryRouter>,
     );
-    await waitFor(() => {
-      expect(screen.getByText(/Guest/i)).toBeInTheDocument();
-    });
+    expect(await screen.findByTestId("envelope-recipient")).toHaveTextContent(
+      /Guest/i,
+    );
   });
 
   it("should display an error message if the server request fails", async () => {
@@ -99,9 +99,9 @@ describe("Reader Page", () => {
       </MemoryRouter>,
     );
 
-    expect(
-      await screen.findByText(/Failed to load letter/i),
-    ).toBeInTheDocument();
+    expect(await screen.findByTestId("log-modal-message")).toHaveTextContent(
+      /Failed to load letter/i,
+    );
   });
 
   it("should navigate to the login page with redirect url when the letter has no sharing key and the user is not logged in", async () => {

frontend/src/pages/Reader.tsx

@@ -1,4 +1,5 @@
 import { FlameIcon, PaperPlaneTiltIcon } from "@phosphor-icons/react";
+import type { AxiosResponse } from "axios";
 import { useEffect, useRef, useState } from "react";
 import {
   type NavigateFunction,
@@ -7,6 +8,7 @@ import {
   useParams,
 } from "react-router-dom";
 import { api } from "../api/apiClient";
+import type { LetterImageData, LetterResponseData } from "../api/response";
 import {
   type CanvasJSON,
   type CanvasTools,
@@ -33,6 +35,7 @@ interface LetterMetadata {
   updated_at?: string;
 }
 
+const WAIT_FOR_BURN_MS = 18000;
 export default function Reader() {
   const { public_id } = useParams();
   const location = useLocation();
@@ -44,13 +47,10 @@ export default function Reader() {
 
   const [isDecrypting, setIsDecrypting] = useState(true);
   const [revealState, setRevealState] = useState<
-    "sealed" | "revealed" | "burned"
-  >("sealed");
-  const [error, setError] = useState<{
-    message: string;
-    log: string;
-  } | null>(null);
-  const [warning, setWarning] = useState<{
+    "SEALED" | "REVEALED" | "BURNED" | "BURNING"
+  >("SEALED");
+  const [logTrace, setLogTrace] = useState<{
+    type: "WARN" | "ERROR";
     message: string;
     log: string;
   } | null>(null);
@@ -73,7 +73,8 @@ export default function Reader() {
     const key = await cryptoUtils.extractSharingKey(encryptedDek, masterKey);
     try {
       await api.patch(`${endpoints.LETTERS}${public_id}/`, { type: "SENT" });
-    } catch (_err) {
+    } catch {
+      // shouldn't obstruct share if api operation fails (since it's client side share)
     } finally {
       setShareLink(`${window.location.origin}${PATHS.read(public_id)}#${key}`);
     }
@@ -86,14 +87,17 @@ export default function Reader() {
       await api.patch(`${endpoints.LETTERS}${public_id}/`, {
         status: "BURNED",
       });
-    } catch (_err) {
+    } catch {
+      // should not obstruct burn if api operation fails
+      // WHY?: it disconnects the UX. if you want to burn the letter, you should be able to burn the letter
+      // TODO: maybe say something like: "the wind is strong today, let's try again"? or maybe something less stupid :3
     } finally {
       setIsBurning(false);
       setShowBurnModal(false);
       setIgnite(true);
       setTimeout(() => {
-        setRevealState("burned");
-      }, 13000);
+        setRevealState("BURNED");
+      }, WAIT_FOR_BURN_MS);
     }
   };
 
@@ -105,105 +109,125 @@ export default function Reader() {
       return;
     }
 
-    const loadAndDecrypt = async () => {
+    const decryptImages = async (
+      canvasData: CanvasJSON,
+      images: LetterImageData[],
+      encrypted_dek: string,
+      cryptoUtils: CryptoUtils,
+    ) => {
+      if (!images?.length) return;
+      const isShared = !!sharingKey;
       try {
-        const response = await api.get(`${endpoints.LETTERS}${public_id}/`);
-        const {
-          encrypted_content,
-          encrypted_metadata,
-          encrypted_dek,
-          images,
-          updated_at,
-          status,
-        } = response.data;
-
-        if (status === "BURNED")
-          throw new Error("This letter has been burned.");
-
-        if (encrypted_dek) setEncryptedDek(encrypted_dek);
-
-        const cryptoUtils = new CryptoUtils();
-        const isShared = !!sharingKey;
-
-        if (isShared && !encrypted_content) throw new Error("Content missing");
-        const isDecryptionKeyAvailable = encrypted_dek && masterKey;
-        if (!(isShared || isDecryptionKeyAvailable))
-          throw new Error("Auth required: Decryption key is not available");
-
-        // Decrypt Metadata
-        const decryptedMetadata = isShared
-          ? await cryptoUtils.decryptMetadataWithSharingKey(
-              encrypted_metadata,
-              sharingKey,
-            )
-          : await cryptoUtils.decryptMetadata(
-              { encrypted_content: encrypted_metadata, encrypted_dek },
-              // biome-ignore lint/style/noNonNullAssertion: masterKey is guaranteed to be non-null here as isDecryptionKeyAvailable is true
-              masterKey!,
-            );
-        setMetadata({
-          ...(decryptedMetadata as LetterMetadata),
-          updated_at,
-        });
-
-        // Decrypt Content
-        const decryptedContent = isShared
-          ? await cryptoUtils.decryptLetterWithSharingKey(
-              encrypted_content,
-              sharingKey,
-            )
-          : await cryptoUtils.decryptLetter(
-              { encrypted_content, encrypted_dek },
-              // biome-ignore lint/style/noNonNullAssertion: masterKey is guaranteed to be non-null here as isDecryptionKeyAvailable is true
-              masterKey!,
-            );
-
-        const canvasData: CanvasJSON = JSON.parse(decryptedContent);
-
-        try {
-          // Decrypt Images
-          if (images?.length > 0) {
-            isShared
-              ? await decryptCanvasImagesWithSharingKey(
-                  canvasData,
-                  images,
-                  sharingKey,
-                  cryptoUtils,
-                )
-              : await decryptCanvasImages(
-                  canvasData,
-                  images,
-                  encrypted_dek,
-                  // biome-ignore lint/style/noNonNullAssertion: masterKey is guaranteed to be non-null here as isDecryptionKeyAvailable is true
-                  masterKey!,
-                  cryptoUtils,
-                );
-          }
-        } catch (err) {
-          setWarning({
-            message:
-              "Failed to decrypt elements. Images might not render in the letter as intended.",
-            log: err instanceof Error ? err.message : "Unknown error",
-          });
+        if (isShared) {
+          await decryptCanvasImagesWithSharingKey(
+            canvasData,
+            images,
+            sharingKey,
+            cryptoUtils,
+          );
+        } else {
+          await decryptCanvasImages(
+            canvasData,
+            images,
+            encrypted_dek,
+            // biome-ignore lint/style/noNonNullAssertion: masterKey is guaranteed to be non-null here as isDecryptionKeyAvailable is true
+            masterKey!,
+            cryptoUtils,
+          );
         }
-        setDecryptedCanvasData(canvasData);
       } catch (err) {
-        setError({
-          message: `Failed to load letter :(`,
+        setLogTrace({
+          message:
+            "Failed to decrypt elements. Images might not render in the letter as intended.",
           log: err instanceof Error ? err.message : "Unknown error",
+          type: "WARN",
         });
-      } finally {
-        setIsDecrypting(false);
       }
     };
 
-    loadAndDecrypt();
+    const decryptLetterData = async (
+      data: LetterResponseData,
+      cryptoUtils: CryptoUtils,
+    ) => {
+      const isShared = !!sharingKey;
+      const {
+        encrypted_content,
+        encrypted_metadata,
+        encrypted_dek,
+        images,
+        updated_at,
+      } = data;
+
+      // Decrypt Metadata
+      const decryptedMetadata = isShared
+        ? await cryptoUtils.decryptMetadataWithSharingKey(
+            encrypted_metadata,
+            sharingKey,
+          )
+        : await cryptoUtils.decryptMetadata(
+            { encrypted_content: encrypted_metadata, encrypted_dek },
+            // biome-ignore lint/style/noNonNullAssertion: masterKey is guaranteed to be non-null here as isDecryptionKeyAvailable is true
+            masterKey!,
+          );
+      setMetadata({
+        ...(decryptedMetadata as LetterMetadata),
+        updated_at,
+      });
+
+      // Decrypt Content
+      const decryptedContent = isShared
+        ? await cryptoUtils.decryptLetterWithSharingKey(
+            encrypted_content,
+            sharingKey,
+          )
+        : await cryptoUtils.decryptLetter(
+            { encrypted_content, encrypted_dek },
+            // biome-ignore lint/style/noNonNullAssertion: masterKey is guaranteed to be non-null here as isDecryptionKeyAvailable is true
+            masterKey!,
+          );
+
+      const canvasData: CanvasJSON = JSON.parse(decryptedContent);
+      await decryptImages(canvasData, images, encrypted_dek, cryptoUtils);
+      setDecryptedCanvasData(canvasData);
+    };
+
+    const processLetterData = async (data: LetterResponseData) => {
+      if (data.status === "BURNED")
+        throw new Error("This letter has been burned.");
+
+      if (data.encrypted_dek) setEncryptedDek(data.encrypted_dek);
+
+      const isDecryptionKeyAvailable = data.encrypted_dek && masterKey;
+      if (!(!!sharingKey || isDecryptionKeyAvailable)) {
+        throw new Error("Auth required: Decryption key is not available");
+      }
+
+      const cryptoUtils = new CryptoUtils();
+      await decryptLetterData(data, cryptoUtils);
+    };
+
+    const loadAndDecryptLetter = async () => {
+      try {
+        const response: AxiosResponse<LetterResponseData> = await api.get(
+          `${endpoints.LETTERS}${public_id}/`,
+        );
+        await processLetterData(response.data);
+      } catch (err) {
+        setLogTrace({
+          message: `Failed to load letter ☹`,
+          log: err instanceof Error ? err.message : "Unknown error",
+          type: "ERROR",
+        });
+      }
+    };
+
+    loadAndDecryptLetter().then(() => setIsDecrypting(false));
   }, [public_id, sharingKey, masterKey]);
 
   useEffect(() => {
     if (
       !isDecrypting &&
-      revealState === "revealed" &&
+      revealState === "REVEALED" &&
       decryptedCanvasData &&
       canvasRef.current
     ) {
@@ -213,13 +237,16 @@ export default function Reader() {
 
   if (isDecrypting) {
     return (
-      <div className="flex items-center justify-center bg-base-100 font-serif">
-        <div className="fixed inset-0 bg-[radial-gradient(circle_at_center,transparent_0%,rgba(0,0,0,0.4)_100%)] pointer-events-none z-0" />
+      <div className="flex items-center h-screen w-screen justify-center bg-base-100 font-sans">
+        <div className="fixed inset-0 bg-vig pointer-events-none" />
         <div className="text-center space-y-6 z-10">
           <Logo />
           <div className="flex flex-col items-center gap-2">
             <span className="loading loading-ring loading-md text-primary/40"></span>
-            <p className="text-[10px] uppercase tracking-[0.4em] text-base-content/20 animate-pulse">
+            <p
+              data-testid="decryption-overlay"
+              className="text-xs uppercase tracking-widest text-base-content/20 animate-pulse"
+            >
               Breaking the seal...
             </p>
           </div>
@@ -228,29 +255,32 @@ export default function Reader() {
     );
   }
 
-  if (error) {
+  if (logTrace) {
     return (
       <LogModal
-        isOpen={!!error}
-        onClose={() => (window.location.href = "/")}
-        message={error.message}
-        log={error.log}
-        status="ERROR"
+        isOpen={!!logTrace}
+        onClose={() => {
+          if (logTrace.type === "ERROR") window.location.href = "/";
+          setLogTrace(null);
+        }}
+        message={logTrace.message}
+        log={logTrace.log}
+        status={logTrace.type}
       />
     );
   }
 
   return (
     <section className="min-h-fit w-full bg-base-100 px-4 py-8 md:py-16 font-serif relative overflow-hidden">
-      <div className="fixed inset-0 bg-[radial-gradient(circle_at_center,transparent_0%,rgba(0,0,0,0.5)_100%)] pointer-events-none z-0" />
+      <div className="fixed inset-0 bg-vig pointer-events-none z-0" />
       <div
         className={`transition-all delay-300 duration-1000 relative ${
-          revealState === "revealed"
+          revealState === "REVEALED"
             ? "opacity-0 w-0 h-0 overflow-hidden invisible"
             : "opacity-100"
         }`}
       >
-        {revealState === "sealed" && (
+        {revealState === "SEALED" && (
           <div className="h-[80vh] mx-auto flex-col items-center flex justify-center">
             <div className="perspective-distant scale-80 duration-1000 transition-all animate-[pulse_2s_linear_1]">
               <EnvelopeReveal
@@ -260,7 +290,7 @@ export default function Reader() {
                     ? formatDate(new Date(metadata.updated_at))
                     : undefined
                 }
-                onRevealComplete={() => setRevealState("revealed")}
+                onRevealComplete={() => setRevealState("REVEALED")}
                 ignite={ignite}
               />
             </div>
@@ -270,16 +300,8 @@ export default function Reader() {
 
       {ignite && <PostActionOverlay revealState={revealState} />}
 
-      <LogModal
-        isOpen={!!warning}
-        onClose={() => setWarning(null)}
-        message={warning?.message || ""}
-        log={warning?.log || ""}
-        status="WARN"
-      />
-
-      {revealState === "revealed" && (
-        <div className="max-w-4xl m-8 mx-auto space-y-8 h-full relative inset-0 z-100">
+      {revealState === "REVEALED" && (
+        <div className="max-w-180 m-8 mx-auto space-y-8 h-full relative inset-0 z-100">
           <div className="relative group perspective-1000">
             <div className="absolute inset-0 bg-primary/5 blur-3xl rounded-full scale-75 opacity-0 group-hover:opacity-100 transition-opacity duration-1000 pointer-events-none" />
 
@@ -289,7 +311,7 @@ export default function Reader() {
             </div>
 
             {metadata?.recipient && (
-              <p className="text-center sm:hidden text-[10px] uppercase tracking-[0.3em] text-base-content/20 mt-8">
+              <p className="text-center sm:hidden text-xxs uppercase tracking-widester text-base-content/20 mt-8">
                 For {metadata.recipient}
               </p>
             )}
@@ -309,10 +331,11 @@ export default function Reader() {
         />
       )}
 
-      {isAuthor && revealState !== "burned" && (
+      {isAuthor && revealState !== "BURNED" && (
         <div className="flex justify-center gap-2 mt-8 z-10 relative">
           <button
             id="share-letter-btn"
+            data-testid="share-letter-btn"
             type="button"
             className="btn btn-ghost btn-sm text-base-content/30 hover:text-base-content hover:bg-base-content/10 gap-1.5"
             onClick={handleShare}
@@ -324,6 +347,7 @@ export default function Reader() {
           </button>
           <button
             id="burn-letter-btn"
+            data-testid="burn-letter-btn"
             type="button"
             className="btn btn-ghost btn-sm text-error/40 hover:text-error hover:bg-error/10 gap-1.5"
             onClick={() => setShowBurnModal(true)}
@@ -337,7 +361,7 @@ export default function Reader() {
       )}
 
       <footer className="mt-16 text-center z-10 opacity-10 pointer-events-none">
-        <p className="text-xs font-sans uppercase tracking-[0.5em]">
+        <p className="text-xs font-sans uppercase tracking-widester">
           Read. Remember. Release.
         </p>
       </footer>

frontend/src/pages/Register.tsx

@@ -8,11 +8,11 @@ import { z } from "zod";
 import { publicApi } from "../api/apiClient";
 import Logo from "../components/Logo";
 import FormField from "../components/ui/FormField";
+import Saajan from "../components/ui/Saajan";
 import { endpoints } from "../config/endpoints";
 import { ROUTES } from "../config/routes";
 import { CryptoUtils } from "../utils/crypto";
 
-// validation logic
 const registerSchema = z
   .object({
     full_name: z.string().min(2, "Name must be at least 2 characters"),
@@ -31,6 +31,9 @@ export default function Register() {
   const navigate = useNavigate();
   const [isLoading, setIsLoading] = useState(false);
   const [apiError, setApiError] = useState<string | null>(null);
+  const [saajanMessage, setSaajanMessage] = useState<string>(
+    "I didn't think I'd be here either.\nAnd yet, here we are.",
+  );
 
   const {
     register,
@@ -41,10 +44,11 @@ export default function Register() {
   });
 
   const onSubmit = async (data: RegisterInputs) => {
+    setSaajanMessage("Good. I'll remember that.");
     setIsLoading(true);
     setApiError(null);
     try {
-      // We generate the key bundle here to get the authHash (password) for the server.
+      // we generate the key bundle here to get the authHash (password) to be haSHed and stored in the db.
       const { authHash } = await CryptoUtils.deriveKeyBundle(
         data.password,
         data.email,
@@ -68,74 +72,114 @@ export default function Register() {
   };
 
   return (
-    <div className="glass-card w-full max-w-sm p-2 transition-all duration-500 hover:shadow-2xl fade-zoom">
-      <form onSubmit={handleSubmit(onSubmit)} className="card-body gap-4">
-        <h1 className="card-title font-display text-2xl justify-center text-primary/80 tracking-tight">
-          Create a <Logo /> Account
-        </h1>
-
-        {apiError && (
-          <div className="alert alert-error text-xs py-2 rounded-md">
-            <span>{apiError}</span>
+    <div className="flex flex-col">
+      <Saajan message={saajanMessage} position="right" />
+      <div className="glass-card w-full max-w-sm p-2 transition-all duration-500 hover:shadow-2xl fade-zoom">
+        <form onSubmit={handleSubmit(onSubmit)} className="card-body gap-4">
+          <div className="card-title font-display text-2xl justify-center text-primary/80 tracking-tight whitespace-nowrap">
+            Create a<Logo type="logo" scale={0.7} />
+            Account
           </div>
-        )}
 
-        <FormField
-          label="Pen Name"
-          placeholder="Word Smith"
-          registration={register("full_name")}
-          error={errors.full_name?.message}
-        />
+          {apiError && (
+            <div className="alert alert-error text-xs py-2 rounded-md">
+              <span>{apiError}</span>
+            </div>
+          )}
 
-        <FormField
-          label="Email"
-          type="email"
-          placeholder="f.kafka@email.com"
-          registration={register("email")}
-          error={errors.email?.message}
-        />
+          <FormField
+            label="Pen Name"
+            placeholder="Word Smith"
+            data-testid="pen-name-input"
+            registration={register("full_name")}
+            error={errors.full_name?.message}
+            handleFocus={() =>
+              setSaajanMessage("Hello friend. What should I call you?")
+            }
+          />
 
-        <FormField
-          label="Password"
-          type="password"
-          placeholder="••••••••"
-          registration={register("password")}
-          error={errors.password?.message}
-        />
+          <FormField
+            label="Email"
+            type="email"
+            placeholder="f.kafka@wrongtrain.com"
+            data-testid="email-input"
+            registration={register("email")}
+            error={errors.email?.message}
+            handleFocus={() =>
+              setSaajanMessage(
+                "Where should I send your letters?\nNo empty lunchboxes, please.",
+              )
+            }
+          />
 
-        <FormField
-          label="Confirm Password"
-          type="password"
-          placeholder="••••••••"
-          registration={register("confirm_password")}
-          error={errors.confirm_password?.message}
-        />
+          <FormField
+            label="Password"
+            type="password"
+            placeholder="••••••••"
+            data-testid="password-input"
+            registration={register("password")}
+            error={errors.password?.message}
+            handleFocus={() =>
+              setSaajanMessage(
+                "Something only you know.\nI have one of those too.",
+              )
+            }
+          />
 
-        {/* Warning */}
-        <div className="alert alert-warning items-start text-left p-3 gap-2 rounded-md border-warning/20">
-          <InfoIcon size={20} weight="duotone" className="mt-0.5 shrink-0" />
-          <p className="text-sm font-semibold">
-            Choose a password you won't forget. <br />
-            <span className="underline decoration-2">There is no reset.</span>{" "}
-            If you lose it, your letters cannot be recovered.
-          </p>
-        </div>
+          <FormField
+            label="Confirm Password"
+            type="password"
+            placeholder="••••••••"
+            data-testid="confirm-password-input"
+            registration={register("confirm_password")}
+            error={errors.confirm_password?.message}
+            handleFocus={() =>
+              setSaajanMessage(
+                "Just once? Trust me, \nsome things are worth repeating twice.",
+              )
+            }
+          />
 
-        <div className="card-actions mt-4">
-          <button
-            type="submit"
-            disabled={isLoading}
-            aria-label="Register"
-            className="btn btn-primary w-full shadow-lg"
-          >
-            {isLoading ? (
-              <span className="loading loading-spinner loading-sm" />
-            ) : (
-              "Register"
-            )}
-          </button>
-        </div>
-      </form>
+          <div className="alert alert-warning items-start text-left p-3 gap-2 rounded-md border-warning/20">
+            <InfoIcon size={20} weight="duotone" className="mt-0.5 shrink-0" />
+            <p className="text-sm font-semibold">
+              Choose a password you won't forget. <br />
+              Just like life,&nbsp;
+              <span className="underline decoration-2">there is no reset</span>
+              &nbsp; here. If you lose it, your letters cannot be recovered.
+            </p>
+          </div>
+
+          <div className="card-actions mt-4">
+            <button
+              type="submit"
+              disabled={isLoading}
+              aria-label="Register"
+              data-testid="register-submit-btn"
+              className="btn btn-primary w-full shadow-lg"
+            >
+              {isLoading ? (
+                <span className="loading loading-spinner loading-sm" />
+              ) : (
+                "Begin"
+              )}
+            </button>
+          </div>
+          <div className="divider text-neutral my-0">or</div>
+          <div className="text-center text-sm font-medium text-neutral">
+            Been here before?&nbsp;
+            <button
+              type="button"
+              name="register"
+              onClick={() => navigate(ROUTES.LOGIN)}
+              className="link link-primary"
+            >
+              Continue where you left off
+            </button>
+            .
+          </div>
+        </form>
+      </div>
     </div>
   );
 }

frontend/src/pages/VerifyEmail.tsx

@@ -1,41 +1,55 @@
 import { EnvelopeSimpleOpenIcon } from "@phosphor-icons/react";
 import Logo from "../components/Logo";
+import Saajan from "../components/ui/Saajan";
 
 export default function VerifyEmail() {
   return (
-    <div className="glass-card w-full max-w-sm p-8 text-center flex flex-col items-center gap-6 fade-zoom">
-      <div className="auth-icon-container">
-        <EnvelopeSimpleOpenIcon
-          size={32}
-          weight="duotone"
-          className="text-primary"
-        />
+    <div className="relative">
+      <Saajan
+        message={"I sent something to your inbox.\nOpen it, and we can begin."}
+      />
+
+      <div className="glass-card w-full max-w-sm p-8 text-center flex flex-col items-center gap-6 fade-zoom">
+        <div className="auth-icon-container">
+          <EnvelopeSimpleOpenIcon
+            size={32}
+            weight="duotone"
+            className="text-primary"
+          />
+        </div>
+
+        <div className="space-y-2">
+          <h2 className="font-display text-xl text-primary">
+            Check Your Mailbox
+          </h2>
+          <p className="text-sm opacity-80 leading-relaxed font-sans mt-6">
+            You're one train away from starting your <Logo scale={0.8} />
+            &nbsp; journey.
+          </p>
+        </div>
+
+        <div className="divider opacity-10 my-0"></div>
+
+        <div className="alert bg-base-200/50 p-4 rounded-lg text-xs leading-relaxed opacity-70 text-center">
+          <p>
+            Nothing yet? Sometimes letters take the wrong train. Check your spam
+            folder.
+            <br />
+            <span className="underline font-bold">
+              The link expires in 24 hours.
+            </span>
+            <br /> I'm patient... but not endlessly so
+          </p>
+        </div>
+
+        <button
+          type="button"
+          className="text-xs italic opacity-40 cursor-pointer underline"
+          onClick={() => window.close()}
+        >
+          You can close this window now.
+        </button>
       </div>
-
-      <div className="space-y-2">
-        <h2 className="font-display text-xl text-primary">Check Your Email</h2>
-        <p className="text-sm opacity-80 leading-relaxed font-sans">
-          We've sent an activation link to your inbox. <br />
-          Please click it to verify your <Logo /> account.
-        </p>
-      </div>
-
-      <div className="divider opacity-10"></div>
-
-      <div className="alert bg-base-200/50 p-4 rounded-lg text-xs leading-relaxed text-left opacity-70">
-        <p>
-          Didn't receive it? Check your spam folder or wait for a few minutes.
-          The link will expire in 24 hours.
-        </p>
-      </div>
-
-      <button
-        type="button"
-        className="text-xs italic opacity-40 cursor-pointer underline"
-        onClick={() => window.close()}
-      >
-        You can close this window now.
-      </button>
     </div>
   );
 }

frontend/src/utils/crypto.test.ts

@@ -17,7 +17,7 @@ describe("deriveKeyBundle", () => {
 
     expect(masterKey.type).toBe("secret");
     expect(masterKey).toBeInstanceOf(CryptoKey);
-    expect(authHash).toHaveLength(64); // SHA-256 hex
+    expect(authHash).toHaveLength(64);
     expect(typeof authHash).toBe("string");
   });
 
@@ -216,7 +216,7 @@ describe("extractSharingKey", () => {
   });
 
   it("extracted key should decrypt the ciphertext produced by encryptLetter", async () => {
-    const plaintext = "hello from the owner";
+    const plaintext = "hello";
     const encrypted = await utils.encryptLetter(plaintext, masterKey);
 
     const extracted = await utils.extractSharingKey(

frontend/src/utils/crypto.ts

@@ -1,6 +1,4 @@
-/**
- * 0 knowledge cryptography. No Server involved in encryption/decryption
- */
+import type { LetterMetadata } from "../api/response";
 
 export interface EncryptedLetter {
   encrypted_content: string;
@@ -11,6 +9,7 @@ export interface EncryptedLetter {
 export interface EncryptedLetterMetadata {
   encrypted_content: string;
   encrypted_dek: string;
+  sharingKey?: string | null;
 }
 
 export interface EncryptedImageUpload {
@@ -25,59 +24,88 @@ interface SealedEnvelope {
   sharingKey: string;
 }
 
+// we use a class here to keep track of instantiations (use 1 and the same DEK per letter content and metadata)
+// TODO: try refactoring into a pure function for consistency
 export class CryptoUtils {
-  private dek: CryptoKey = {} as CryptoKey;
-  private static readonly PBKDF2_ITERATIONS = 100_000;
-  private static readonly AES_GCM = { name: "AES-GCM", length: 256 };
+  private dek!: CryptoKey;
+  private static readonly PBKDF2_ITERATIONS =
+    Number(import.meta.env.VITE_PBKDF2_ITERATIONS) || 600_000;
+  // NOTE: https://www.w3.org/TR/webcrypto/#aes-gcm
+  private static readonly AES_ALGO = { name: "AES-GCM", length: 256 };
+  private static readonly IV_BYTE_LENGTH = 12;
 
-  // Generates a fresh Data Encryption Key (DEK)
+  // NOTE: this MUST be called once, per letter, for all operations in a session to a fresh Data Encryption Key (DEK)
   async initialize() {
-    this.dek = await crypto.subtle.generateKey(CryptoUtils.AES_GCM, true, [
+    this.dek = await crypto.subtle.generateKey(CryptoUtils.AES_ALGO, true, [
       "encrypt",
       "decrypt",
     ]);
   }
 
-  // base64 conversion for transit
-  toBase64 = (buf: Uint8Array): string =>
-    btoa(buf.reduce((s, b) => s + String.fromCharCode(b), ""));
+  private toBase64 = (buffer: Uint8Array): string => {
+    // convert buffer to raw string
+    let binaryFileString = "";
+    for (let i = 0; i < buffer.byteLength; i++) {
+      binaryFileString += String.fromCharCode(buffer[i]);
+    }
+    return btoa(binaryFileString);
+  };
 
-  fromBase64 = (b64: string): Uint8Array<ArrayBuffer> => {
-    const str = atob(b64);
-    const arr = new Uint8Array(str.length);
-    for (let i = 0; i < str.length; i++) arr[i] = str.charCodeAt(i);
+  private fromBase64 = (b64String: string): Uint8Array<ArrayBuffer> => {
+    const decodedString = atob(b64String);
+    const arr = new Uint8Array(decodedString.length);
+    for (let i = 0; i < decodedString.length; i++)
+      arr[i] = decodedString.charCodeAt(i);
     return arr;
   };
 
-  // bundle IV + data into a single base64 string
-  packWithIv = (iv: Uint8Array, data: ArrayBuffer): string => {
-    const packed = new Uint8Array(iv.length + data.byteLength);
-    packed.set(iv);
-    packed.set(new Uint8Array(data), iv.length);
-    return this.toBase64(packed);
+  // Required structure: [12 bytes IV][Cipher text][16 bytes Auth Tag]
+  // NOTE: Web Crypto API auto appends the auth tag, so we focus on IV and cipher
+  private packWithIv = (iv: Uint8Array, ciphertext: ArrayBuffer): string => {
+    // create a buffer large enough to hold both iv and cipher text (12 + x bytes)
+    const combinedPayload = new Uint8Array(
+      CryptoUtils.IV_BYTE_LENGTH + ciphertext.byteLength,
+    );
+
+    // place the iv at the start
+    combinedPayload.set(iv, 0);
+
+    // place the ciphertext after the iv
+    combinedPayload.set(new Uint8Array(ciphertext), CryptoUtils.IV_BYTE_LENGTH);
+
+    // convert the buffer to Base64 for transit
+    return this.toBase64(combinedPayload);
   };
 
-  unpackWithIv = (
-    b64: string,
-  ): [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>] => {
-    const buf = this.fromBase64(b64);
-    return [new Uint8Array(buf.buffer, 0, 12), new Uint8Array(buf.buffer, 12)];
+  // For decryption: extracts the IV and the data from the base64 string, easy because we know the size of iv already.
+  private unpackWithIv = (
+    encodedString: string,
+  ): { iv: Uint8Array<ArrayBuffer>; ciphertext: Uint8Array<ArrayBuffer> } => {
+    // decode from base64 to array buffer
+    const fullBuffer = this.fromBase64(encodedString);
+
+    // extract first 12 bytes for iv
+    const iv = fullBuffer.slice(0, CryptoUtils.IV_BYTE_LENGTH);
+    // extract rest for cipher text
+    const ciphertext = fullBuffer.slice(CryptoUtils.IV_BYTE_LENGTH);
+
+    return { iv: new Uint8Array(iv), ciphertext: new Uint8Array(ciphertext) };
   };
 
   /**
-   * Derives a Key Bundle (MasterKey + AuthHash) from a password + email.
-   * Absolute zero knowledge!!
+   * Derive a key bundle (Masterkey + authHash) from email + (plain) password combo
+   * WHY?: This is much secure than relying on server to hash and store the password. Also ensures absolute 0 knowledge
    */
   public static async deriveKeyBundle(
     password: string,
     email: string,
   ): Promise<{ masterKey: CryptoKey; authHash: string }> {
-    const enc = new TextEncoder();
-    const salt = enc.encode(email.toLowerCase());
+    const encoder = new TextEncoder();
+    const salt = encoder.encode(email.toLowerCase());
 
     const baseKey = await crypto.subtle.importKey(
       "raw",
-      enc.encode(password),
+      encoder.encode(password),
       "PBKDF2",
       false,
       ["deriveBits", "deriveKey"],
@@ -91,49 +119,61 @@ export class CryptoUtils {
         hash: "SHA-256",
       },
       baseKey,
-      512, // 512 bits to split
+      512,
     );
 
-    // first 256 bits for MasterKey, last 256 bits for AuthHash
+    // first 256 bits for masterkey, last 256 bits for authHash (password sent in REST)
     const masterKeyBytes = masterSeed.slice(0, 32);
     const authHashBytes = masterSeed.slice(32, 64);
 
-    // Create the MasterKey for client-side encryption
+    // Create the masterkey for client-side encryption
     const masterKey = await crypto.subtle.importKey(
       "raw",
       masterKeyBytes,
-      CryptoUtils.AES_GCM,
+      CryptoUtils.AES_ALGO,
       false,
       ["encrypt", "decrypt", "wrapKey", "unwrapKey"],
     );
 
-    // Create the hex AuthHash for server-side verification
-    const authHash = Array.from(new Uint8Array(authHashBytes))
-      .map((b) => b.toString(16).padStart(2, "0"))
-      .join("");
+    // convert bytes in to hex string
+    let authHash = "";
+    const authHashBuffer = new Uint8Array(authHashBytes);
+
+    for (let i = 0; i < authHashBuffer.byteLength; i++) {
+      // we force every bytes converted to string to be min 2 chars (otherwise 00 0a will be just a and not "000a")
+      authHash += authHashBuffer[i].toString(16).padStart(2, "0");
+    }
 
     return { masterKey, authHash };
   }
 
-  // Internal helper to encrypt data and wrap the key
+  /*
+   * Envelope Encryption - Decryption
+   * WHY?: for guest access where we don't have to share the masterkey just the dek.
+   * This way, raw dek never leaves browser (db stores the encrypted version)
+   */
+
+  // encrypt the plaintext with a DEK and then encrypt (wrap) that DEK with the user's masterkey.
   private async sealEnvelope(
     input: Uint8Array,
     masterKey: CryptoKey,
   ): Promise<SealedEnvelope> {
+    if (!this.dek) {
+      throw new Error("DEK is not available (forgot to .initialize()?)");
+    }
     const plainBytes = new Uint8Array(input);
-
-    // encrypt the content with the DEK
     const contentIv = crypto.getRandomValues(new Uint8Array(12));
+    const dekIv = crypto.getRandomValues(new Uint8Array(12));
+
     const ciphertext = await crypto.subtle.encrypt(
-      { name: "AES-GCM", iv: contentIv },
+      { name: CryptoUtils.AES_ALGO.name, iv: contentIv },
       this.dek,
       plainBytes,
     );
 
-    // wrap the DEK with the Master Key (for self/owner access)
-    const dekIv = crypto.getRandomValues(new Uint8Array(12));
+    // wrap the DEK with the Master Key (for self access)
     const wrappedDek = await crypto.subtle.wrapKey("raw", this.dek, masterKey, {
-      name: "AES-GCM",
+      name: CryptoUtils.AES_ALGO.name,
       iv: dekIv,
     });
 
@@ -147,26 +187,27 @@ export class CryptoUtils {
     };
   }
 
-  // Internal helper to unwrap the key and decrypt data
+  // Unwrap the DEK with the master key to get the key back. Decrypt the content with the DEK.
   private async openEnvelope(
     encryptedContent: string,
     encrypted_dek: string,
     masterKey: CryptoKey,
   ): Promise<Uint8Array<ArrayBuffer>> {
-    const [dekIv, wrappedDek] = this.unpackWithIv(encrypted_dek);
+    const { iv: dekIv, ciphertext: wrappedDek } =
+      this.unpackWithIv(encrypted_dek);
     const dek = await crypto.subtle.unwrapKey(
       "raw",
       wrappedDek,
       masterKey,
-      { name: "AES-GCM", iv: dekIv },
-      CryptoUtils.AES_GCM,
+      { name: CryptoUtils.AES_ALGO.name, iv: dekIv },
+      CryptoUtils.AES_ALGO,
       false,
       ["decrypt"],
     );
 
-    const [contentIv, ciphertext] = this.unpackWithIv(encryptedContent);
+    const { iv: contentIv, ciphertext } = this.unpackWithIv(encryptedContent);
     const plainBytes = await crypto.subtle.decrypt(
-      { name: "AES-GCM", iv: contentIv },
+      { name: CryptoUtils.AES_ALGO.name, iv: contentIv },
       dek,
       ciphertext,
     );
@@ -182,14 +223,14 @@ export class CryptoUtils {
     const dek = await crypto.subtle.importKey(
       "raw",
       dekBytes,
-      CryptoUtils.AES_GCM,
+      CryptoUtils.AES_ALGO,
       false,
       ["decrypt"],
     );
 
-    const [contentIv, ciphertext] = this.unpackWithIv(encryptedContent);
+    const { iv: contentIv, ciphertext } = this.unpackWithIv(encryptedContent);
     const plainBytes = await crypto.subtle.decrypt(
-      { name: "AES-GCM", iv: contentIv },
+      { name: CryptoUtils.AES_ALGO.name, iv: contentIv },
       dek,
       ciphertext,
     );
@@ -206,6 +247,7 @@ export class CryptoUtils {
   ): Promise<EncryptedLetter> {
     const { encryptedContent, encrypted_dek, sharingKey } =
       await this.sealEnvelope(new TextEncoder().encode(plaintext), masterKey);
+
     return { encrypted_content: encryptedContent, encrypted_dek, sharingKey };
   }
 
@@ -218,6 +260,7 @@ export class CryptoUtils {
       encrypted_dek,
       masterKey,
     );
+
     return new TextDecoder().decode(bytes);
   }
 
@@ -229,41 +272,45 @@ export class CryptoUtils {
       encrypted_content,
       sharingKey,
     );
+
     return new TextDecoder().decode(bytes);
   }
 
   public async encryptMetadata(
-    metadata: Record<string, any>,
+    metadata: LetterMetadata,
     masterKey: CryptoKey,
-  ): Promise<EncryptedLetter> {
+  ): Promise<EncryptedLetterMetadata> {
     const { encryptedContent, encrypted_dek, sharingKey } =
       await this.sealEnvelope(
         new TextEncoder().encode(JSON.stringify(metadata)),
         masterKey,
       );
+
     return { encrypted_content: encryptedContent, encrypted_dek, sharingKey };
   }
 
   public async decryptMetadata(
     encrypted_metadata: EncryptedLetter,
     masterKey: CryptoKey,
-  ): Promise<Record<string, any>> {
+  ): Promise<LetterMetadata> {
     const bytes = await this.openEnvelope(
       encrypted_metadata.encrypted_content,
       encrypted_metadata.encrypted_dek,
       masterKey,
     );
+
     return JSON.parse(new TextDecoder().decode(bytes));
   }
 
   public async decryptMetadataWithSharingKey(
     encrypted_content: string,
     sharingKey: string,
-  ): Promise<Record<string, any>> {
+  ): Promise<LetterMetadata> {
     const bytes = await this.openEnvelopeWithSharingKey(
       encrypted_content,
       sharingKey,
     );
+
     return JSON.parse(new TextDecoder().decode(bytes));
   }
 
@@ -290,12 +337,13 @@ export class CryptoUtils {
     masterKey: CryptoKey,
   ): Promise<string> {
     const encryptedBytes = new Uint8Array(await encryptedBlob.arrayBuffer());
-    const bytes = await this.openEnvelope(
+    const plainBytes = await this.openEnvelope(
       this.toBase64(encryptedBytes),
       encrypted_dek,
       masterKey,
     );
-    return URL.createObjectURL(new Blob([bytes]));
+
+    return URL.createObjectURL(new Blob([plainBytes]));
   }
 
   public async decryptImageWithSharingKey(
@@ -303,28 +351,31 @@ export class CryptoUtils {
     sharingKey: string,
   ): Promise<string> {
     const encryptedBytes = new Uint8Array(await encryptedBlob.arrayBuffer());
-    const bytes = await this.openEnvelopeWithSharingKey(
+    const plainBytes = await this.openEnvelopeWithSharingKey(
       this.toBase64(encryptedBytes),
       sharingKey,
     );
-    return URL.createObjectURL(new Blob([bytes]));
+
+    return URL.createObjectURL(new Blob([plainBytes]));
   }
 
-  //  Re-derives the sharing key (raw DEK) on demand (browser only, not sent to server).
+  // derive raw DEK on demand (browser only, not sent to server) for guest access
   public async extractSharingKey(
     encrypted_dek: string,
     masterKey: CryptoKey,
   ): Promise<string> {
-    const [dekIv, wrappedDek] = this.unpackWithIv(encrypted_dek);
+    const { iv: dekIv, ciphertext: wrappedDek } =
+      this.unpackWithIv(encrypted_dek);
     const rawDek = await crypto.subtle.unwrapKey(
       "raw",
       wrappedDek,
       masterKey,
-      { name: "AES-GCM", iv: dekIv },
-      CryptoUtils.AES_GCM,
+      { name: CryptoUtils.AES_ALGO.name, iv: dekIv },
+      CryptoUtils.AES_ALGO,
       true,
       ["decrypt"],
     );
+
     return this.toBase64(
       new Uint8Array(await crypto.subtle.exportKey("raw", rawDek)),
     );

frontend/src/utils/keystore.ts

@@ -1,6 +1,6 @@
 import { openDB } from "idb";
 
-// we use this to store master key in browser - secure and good UX
+// we use indexedDB to securely store master key for easier access across tabs (better UX than having to store in session)
 const db = openDB("piku-keys", 1, {
   upgrade(db) {
     db.createObjectStore("master-key");

frontend/src/utils/letterLogic.test.ts

@@ -12,6 +12,7 @@ vi.mock("../api/apiClient", () => ({
   api: {
     get: vi.fn(),
   },
+  apiServerUrl: "https://remote",
 }));
 
 vi.mock("./fileUtils", () => ({
@@ -21,7 +22,6 @@ vi.mock("./fileUtils", () => ({
 describe("letterLogic image helpers", () => {
   let masterKey: CryptoKey;
   let crypto: CryptoUtils;
-
   beforeEach(async () => {
     const keyBundle = await CryptoUtils.deriveKeyBundle(
       "password123",
@@ -58,15 +58,13 @@ describe("letterLogic image helpers", () => {
 
       const encryptImageSpy = vi.spyOn(CryptoUtils.prototype, "encryptImage");
 
-      const uploads = await encryptCanvasImages(
-        canvasData,
-        [],
-        masterKey,
-        crypto,
-      );
+      const { encryptedImageFiles: uploads, encryptedCanvasData } =
+        await encryptCanvasImages(canvasData, [], masterKey, crypto);
 
       expect(encryptImageSpy).not.toHaveBeenCalled();
-      expect(canvasData.objects[0].src).toBe("already-encrypted.png.bin");
+      expect(encryptedCanvasData.objects[0].src).toBe(
+        "already-encrypted.png.bin",
+      );
       expect(uploads.size).toBe(0);
     });
 
@@ -99,15 +97,11 @@ describe("letterLogic image helpers", () => {
         filename: "photo.png.bin",
       });
 
-      const uploads = await encryptCanvasImages(
-        canvasData,
-        canvasImages,
-        masterKey,
-        crypto,
-      );
+      const { encryptedImageFiles: uploads, encryptedCanvasData } =
+        await encryptCanvasImages(canvasData, canvasImages, masterKey, crypto);
 
       expect(CryptoUtils.prototype.encryptImage).toHaveBeenCalledTimes(1);
-      expect(canvasData.objects[0].src).toBe("photo.png.bin");
+      expect(encryptedCanvasData.objects[0].src).toBe("photo.png.bin");
       expect(uploads.size).toBe(1);
       expect(uploads.has("photo.png.bin")).toBe(true);
     });
@@ -136,7 +130,7 @@ describe("letterLogic image helpers", () => {
         ],
       };
       const remoteImages = [
-        { file_name: "photo.png.bin", file: "https://remote/photo.png.bin" },
+        { file_name: "photo.png.bin", file: `https://remote/photo.png.bin` },
       ];
 
       vi.mocked(api.get).mockResolvedValue({ data: new Blob(["encrypted"]) });
@@ -144,7 +138,7 @@ describe("letterLogic image helpers", () => {
         "blob:http://localhost/decrypted",
       );
 
-      await decryptCanvasImages(
+      const { canvasDataWithDecryptedImages } = await decryptCanvasImages(
         canvasData,
         remoteImages,
         "wrapped-dek",
@@ -152,16 +146,19 @@ describe("letterLogic image helpers", () => {
         crypto,
       );
 
-      expect(api.get).toHaveBeenCalledWith("https://remote/photo.png.bin", {
-        responseType: "blob",
-      });
+      expect(api.get).toHaveBeenCalledWith(
+        `https://remote/photo.png.bin`,
+        expect.objectContaining({ responseType: "blob" }),
+      );
       expect(CryptoUtils.prototype.decryptImage).toHaveBeenCalledWith(
         expect.any(Blob),
         "wrapped-dek",
         masterKey,
       );
-      expect(canvasData.objects[0].src).toBe("blob:http://localhost/decrypted");
-      expect(canvasData.objects[1].text).toBe("hello");
+      expect(canvasDataWithDecryptedImages.objects[0].src).toBe(
+        "blob:http://localhost/decrypted",
+      );
+      expect(canvasDataWithDecryptedImages.objects[1].text).toBe("hello");
     });
 
     it("should include raw file when includeRawFile is true", async () => {
@@ -190,7 +187,7 @@ describe("letterLogic image helpers", () => {
         new File(["raw"], "photo.png.bin"),
       );
 
-      await decryptCanvasImages(
+      const { canvasDataWithDecryptedImages } = await decryptCanvasImages(
         canvasData,
         remoteImages,
         "wrapped-dek",
@@ -203,7 +200,9 @@ describe("letterLogic image helpers", () => {
         "blob:http://localhost/decrypted",
         "photo.png.bin",
       );
-      expect(canvasData.objects[0]._customRawFile).toBeInstanceOf(File);
+      expect(
+        canvasDataWithDecryptedImages.objects[0]._customRawFile,
+      ).toBeInstanceOf(File);
     });
   });
 
@@ -222,7 +221,11 @@ describe("letterLogic image helpers", () => {
         ],
       };
       const remoteImages = [
-        { file_name: "photo.png.bin", file: "https://remote/photo.png.bin" },
+        {
+          public_id: "1234",
+          file_name: "photo.png.bin",
+          file: "https://remote/photo.png.bin",
+        },
       ];
 
       vi.mocked(api.get).mockResolvedValue({ data: new Blob(["encrypted"]) });
@@ -231,20 +234,22 @@ describe("letterLogic image helpers", () => {
         "decryptImageWithSharingKey",
       ).mockResolvedValue("blob:http://localhost/decrypted-shared");
 
-      await decryptCanvasImagesWithSharingKey(
-        canvasData,
-        remoteImages,
-        "raw-sharing-key",
-        crypto,
-      );
+      const { canvasDataWithDecryptedImages } =
+        await decryptCanvasImagesWithSharingKey(
+          canvasData,
+          remoteImages,
+          "raw-sharing-key",
+          crypto,
+        );
 
-      expect(api.get).toHaveBeenCalledWith("https://remote/photo.png.bin", {
-        responseType: "blob",
-      });
+      expect(api.get).toHaveBeenCalledWith(
+        "https://remote/photo.png.bin",
+        expect.objectContaining({ responseType: "blob" }),
+      );
       expect(
         CryptoUtils.prototype.decryptImageWithSharingKey,
       ).toHaveBeenCalledWith(expect.any(Blob), "raw-sharing-key");
-      expect(canvasData.objects[0].src).toBe(
+      expect(canvasDataWithDecryptedImages.objects[0].src).toBe(
         "blob:http://localhost/decrypted-shared",
       );
     });

frontend/src/utils/letterLogic.ts

@@ -1,4 +1,5 @@
-import { api } from "../api/apiClient";
+import { api, apiServerUrl, publicApi } from "../api/apiClient";
+import type { LetterImageData } from "../api/response";
 import type {
   CanvasJSON,
   FabricImageJSON,
@@ -11,6 +12,35 @@ export interface CanvasImageRef {
   file: File;
 }
 
+export interface DecryptedFabricImageJSON extends FabricImageJSON {
+  _customRawFile?: File;
+}
+
+export interface DecryptionResult {
+  canvasDataWithDecryptedImages: CanvasJSON;
+  isPartialFailure: boolean;
+  errors: string[];
+}
+
+export interface EncryptionResult {
+  encryptedImageFiles: Map<string, Blob>;
+  encryptedCanvasData: CanvasJSON;
+}
+
+async function fetchEncryptedBlobFromRemote(remoteUrl: string): Promise<Blob> {
+  // IF served statically from server, we need proper CORS setup
+  if (remoteUrl.includes(apiServerUrl)) {
+    const res = await api.get(remoteUrl, { responseType: "blob" });
+    return res.data;
+  }
+  // Note: S3 Storage fetch (external url) has to bypass our existing CORS setup
+  const res = await publicApi.get(remoteUrl, {
+    responseType: "blob",
+    withCredentials: false,
+  });
+  return res.data;
+}
+
 export async function decryptCanvasImages(
   canvasData: CanvasJSON,
   remoteImages: { file_name: string; file: string }[],
@@ -18,80 +48,120 @@ export async function decryptCanvasImages(
   masterKey: CryptoKey,
   cryptoUtils: CryptoUtils,
   includeRawFile = false,
-): Promise<{ isDecryptionPartialFailure: boolean; error: string }> {
-  if (!canvasData?.objects)
-    return { isDecryptionPartialFailure: false, error: "" };
-  let isDecryptionPartialFailure = false;
-  let error = "";
+): Promise<DecryptionResult> {
+  if (!canvasData?.objects) {
+    return {
+      canvasDataWithDecryptedImages: canvasData,
+      isPartialFailure: false,
+      errors: [],
+    };
+  }
 
   const imageMap = new Map(
     remoteImages.map((img) => [img.file_name, img.file]),
   );
 
-  const decryptionPromises = canvasData.objects.map(async (obj, index) => {
-    if (obj.type !== "Image") return;
-    const imgObj = obj as FabricImageJSON;
-    const remoteUrl = imageMap.get(imgObj.src);
-    if (!remoteUrl) return;
+  const errors: string[] = [];
+  const processedObjects = await Promise.all(
+    canvasData.objects.map(async (obj) => {
+      if (obj.type !== "Image") return obj;
 
-    try {
-      const res = await api.get(remoteUrl, { responseType: "blob" });
-      const originalSrc = imgObj.src;
+      const imgObj = obj as FabricImageJSON;
+      const remoteUrl = imageMap.get(imgObj.src);
+      if (!remoteUrl) return obj;
 
-      const blobUrl = await cryptoUtils.decryptImage(
-        res.data,
-        encrypted_dek,
-        masterKey,
-      );
+      try {
+        const blob = await fetchEncryptedBlobFromRemote(remoteUrl);
+        const blobUrl = await cryptoUtils.decryptImage(
+          blob,
+          encrypted_dek,
+          masterKey,
+        );
 
-      imgObj.src = blobUrl;
+        const decryptedObj: DecryptedFabricImageJSON = {
+          ...imgObj,
+          src: blobUrl,
+        };
 
-      if (includeRawFile) {
-        imgObj._customRawFile = await blobUrlToFile(blobUrl, originalSrc);
+        if (includeRawFile) {
+          decryptedObj._customRawFile = await blobUrlToFile(
+            blobUrl,
+            imgObj.src,
+          );
+        }
+
+        return decryptedObj;
+      } catch (err) {
+        errors.push(
+          `Failed to decrypt ${imgObj.src}: ${err instanceof Error ? err.message : "Unknown error"}`,
+        );
+        return null;
       }
-    } catch (_error) {
-      delete canvasData.objects[index];
-      isDecryptionPartialFailure = true;
-      error = _error instanceof Error ? _error.message : "Unknown error";
-    }
-  });
+    }),
+  );
 
-  await Promise.all(decryptionPromises);
-  canvasData.objects = canvasData.objects.filter(Boolean);
-  return { isDecryptionPartialFailure, error };
+  return {
+    canvasDataWithDecryptedImages: {
+      ...canvasData,
+      objects: processedObjects.filter((obj) => !!obj),
+    },
+    isPartialFailure: errors.length > 0,
+    errors,
+  };
 }
 
 export async function decryptCanvasImagesWithSharingKey(
   canvasData: CanvasJSON,
-  remoteImages: { file_name: string; file: string }[],
+  remoteImages: LetterImageData[],
   sharingKey: string,
   cryptoUtils: CryptoUtils,
-) {
-  if (!canvasData?.objects) return;
+): Promise<DecryptionResult> {
+  if (!canvasData?.objects) {
+    return {
+      canvasDataWithDecryptedImages: canvasData,
+      isPartialFailure: false,
+      errors: [],
+    };
+  }
 
   const imageMap = new Map(
     remoteImages.map((img) => [img.file_name, img.file]),
   );
+  const errors: string[] = [];
 
-  const decryptionPromises = canvasData.objects.map(async (obj) => {
-    if (obj.type !== "Image") return;
+  const processedObjects = await Promise.all(
+    canvasData.objects.map(async (obj) => {
+      if (obj.type !== "Image") return obj;
 
-    const imgObj = obj as FabricImageJSON;
-    const remoteUrl = imageMap.get(imgObj.src);
-    if (!remoteUrl) return;
+      const imgObj = obj as FabricImageJSON;
+      const remoteUrl = imageMap.get(imgObj.src);
+      if (!remoteUrl) return obj;
 
-    try {
-      const res = await api.get(remoteUrl, { responseType: "blob" });
-      imgObj.src = await cryptoUtils.decryptImageWithSharingKey(
-        res.data,
-        sharingKey,
-      );
-    } catch (_error) {
-      // Keep original or handle failure
-    }
-  });
+      try {
+        const blob = await fetchEncryptedBlobFromRemote(remoteUrl);
+        const blobUrl = await cryptoUtils.decryptImageWithSharingKey(
+          blob,
+          sharingKey,
+        );
 
-  await Promise.all(decryptionPromises);
+        return { ...imgObj, src: blobUrl };
+      } catch (err) {
+        errors.push(
+          `Failed to decrypt ${imgObj.src}: ${err instanceof Error ? err.message : "Unknown error"}`,
+        );
+        return null;
+      }
+    }),
+  );
+
+  return {
+    canvasDataWithDecryptedImages: {
+      ...canvasData,
+      objects: processedObjects.filter((obj) => !!obj),
+    },
+    isPartialFailure: errors.length > 0,
+    errors,
+  };
 }
 
 export async function encryptCanvasImages(
@@ -99,23 +169,34 @@ export async function encryptCanvasImages(
   canvasImages: CanvasImageRef[],
   masterKey: CryptoKey,
   cryptoUtils: CryptoUtils,
-) {
-  const encryptedFiles = new Map<string, Blob>();
+): Promise<EncryptionResult> {
+  const encryptedImageFiles = new Map<string, Blob>();
   const filenameMapping = new Map<string, string>();
 
-  for (const img of canvasImages) {
-    if (img.src.endsWith(".bin")) continue;
-    if (!img.file) continue;
-    const { filename, encryptedBlob } = await cryptoUtils.encryptImage(
-      img.file,
-      masterKey,
-    );
-    filenameMapping.set(img.src, filename);
-    encryptedFiles.set(filename, encryptedBlob);
-  }
+  // filter out already encrypted images
+  const imagesToEncrypt = canvasImages.filter(
+    (img) => img.file && !img.src.endsWith(".bin"),
+  );
 
-  if (canvasData?.objects) {
-    canvasData.objects = canvasData.objects.map((obj) => {
+  // encrypt images parallelly
+  await Promise.all(
+    imagesToEncrypt.map(async (img) => {
+      const { filename, encryptedBlob } = await cryptoUtils.encryptImage(
+        img.file,
+        masterKey,
+      );
+      // map the og image url to the encrypted file name and filename to the encrypted source
+      filenameMapping.set(img.src, filename);
+      encryptedImageFiles.set(filename, encryptedBlob);
+    }),
+  );
+
+  if (!canvasData?.objects)
+    return { encryptedImageFiles, encryptedCanvasData: canvasData };
+
+  const newCanvasData = {
+    ...canvasData,
+    objects: canvasData.objects.map((obj) => {
       if (obj.type === "Image") {
         const imgObj = obj as FabricImageJSON;
         if (filenameMapping.has(imgObj.src)) {
@@ -126,8 +207,8 @@ export async function encryptCanvasImages(
         }
       }
       return obj;
-    });
-  }
+    }),
+  };
 
-  return encryptedFiles;
+  return { encryptedImageFiles, encryptedCanvasData: newCanvasData };
 }

frontend/vite.config.ts

@@ -46,5 +46,10 @@ export default defineConfig(({ mode }) => {
       host: env.FRONTEND_DOMAIN,
       https: isSslEnabled ? sslCerts : undefined,
     },
+    preview: {
+      port: Number(env.FRONTEND_PORT),
+      host: env.FRONTEND_DOMAIN,
+      https: isSslEnabled ? sslCerts : undefined,
+    },
   };
 });

frontend/vitest.config.ts

@@ -9,6 +9,8 @@ export default defineConfig({
     env: {
       VITE_API_URL: "http://piku-server",
       TZ: "Asia/Kolkata",
+      // using the actual 600_000 iterations causes timeout in tests
+      VITE_PBKDF2_ITERATIONS: "1",
     },
     include: ["**/*.test.ts", "**/*.test.tsx"],
     environment: "jsdom",

scripts/run-e2e.sh

@@ -55,6 +55,18 @@ until $CONTAINER_BIN exec "$DB_NAME" pg_isready -U "${DB_USER:-test}" >/dev/null
 done
 
 export PIKU_ENV_FILE="$ENV_FILE"
+
+# NOTE: When running in Gitea Actions (within container), We must ponint DB and mail to the internal docker host instead.
+if [ "$GITEA_ACTIONS" = "true" ]; then
+    sudo apt-get update && sudo apt-get install -y iproute2
+    # Sample: "default via <internal docker host IP> dev <network interface> proto dhcp src <IP> metric 100"
+    HOST_IP=$(ip route show default | awk '/default/ {print $3}')
+    echo "Running on Gitea. Internal Docker host... $HOST_IP"
+
+    export DB_HOST=$HOST_IP
+    export EMAIL_HOST=$HOST_IP
+fi
+
 echo "Starting Backend..."
 mkdir -p ./tmp/logs
 (

scripts/setup.sh

@@ -1,6 +1,14 @@
 #!/bin/bash
 set -e
 
+# Setup Env from examples
+if [ ! -f ".env" ]; then
+    cp .env.example .env
+fi
+if [ ! -f ".env.e2e" ]; then
+    cp .env.e2e.example .env.e2e
+fi
+
 NODE_BIN=$(command -v bun || command -v npm || true)
 PY_BIN=$(command -v uv || command -v pip || true)
 DISTRO_BIN=$(command -v apt || command -v yum || command -v pacman || command -v zypper || true)
@@ -35,17 +43,20 @@ else
 fi
 
 # Simplify ssl generation for local - source & credits:- https://github.com/FiloSottile/mkcert
-echo "[Cert] Setting up SSL..."
-# pre-requisites (might be available already, just in case)
-if [ $(basename "$DISTRO_BIN") = "apt" ]; then
-  sudo apt install -y libnss3-tools
-elif [ $(basename "$DISTRO_BIN") = "yum" ]; then
-  sudo yum install -y nss-tools
-elif [ $(basename "$DISTRO_BIN") = "pacman" ]; then
-  sudo pacman -S --noconfirm nss
-elif [ $(basename "$DISTRO_BIN") = "zypper" ]; then
-  sudo zypper install -y mozilla-nss-tools
-fi
+# Note, still try to perform the setup if pkg setups fail
+{
+  echo "[Cert] Setting up SSL..."
+  # pre-requisites (might be available already, just in case)
+  if [ $(basename "$DISTRO_BIN") = "apt" ]; then
+    sudo apt install -y libnss3-tools
+  elif [ $(basename "$DISTRO_BIN") = "yum" ]; then
+    sudo yum install -y nss-tools
+  elif [ $(basename "$DISTRO_BIN") = "pacman" ]; then
+    sudo pacman -S --noconfirm nss
+  elif [ $(basename "$DISTRO_BIN") = "zypper" ]; then
+    sudo zypper install -y mozilla-nss-tools
+  fi
+} || true
 
 # Detect os and arch to get the appropriate bin. Windows: ...NO SOUP FOR YOU!
 OS=$(uname -s)