M2: Meili search + saved searches, sync windows + backfill progress, threading & image fixes

Search:
- Meilisearch backend (app/search/meili.py) + factory wiring; pinned SDK 2.7
- Search-as-you-type: debounced query + Postgres prefix matching, built from
  the DB tokenizer so full email addresses match (email stays one lexeme)
- Saved searches API + sidebar virtual mailboxes; save affordance in the box

Account sync windows (SPEC §12 M2):
- Choose at setup: All (recent 30d first, then remainder), Last 3 months, New only
- Per-account sync_window + "Sync remaining mail" from settings (idempotent re-run)
- Provider windowed backfill (SINCE/BEFORE), message_count, newest_uid
- migration 0012: accounts.sync_window + backfill_total/backfill_done

Backfill progress UX:
- Floating progress card (auto-dissolves after 10s) + spinning sidebar ring that
  fills with the account colour; driven by sync.progress over WS

Thread list pagination:
- Server-side offset + accurate grand total, with filter/order in SQL; working
  prev/next across all synced mail

Reading panel:
- "Load images" one-off now actually renders images (?images=1) without trusting
  the sender; envelope carries images_allowed so a trusted sender shows no prompt

Threading:
- Subject fallback no longer merges messages that declare an explicit (different)
  parent; true siblings still group via a shared-parent reference match. Fixes
  unrelated auto-replies with the same subject landing in one thread

Backend 257 tests green, ruff + mypy --strict clean; frontend tsc/eslint/vitest clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U72FZiF1W1pb8XxyWBTREA

backend/tests/api/test_api.py

@@ -378,12 +378,13 @@ async def test_accounts_list(api: ApiCtx) -> None:
     assert resp.json()[0]["email"] == "me@example.com"
 
 
-async def test_thread_pagination_cursor(api: ApiCtx) -> None:
-    first = await api.client.get("/api/threads", params={"limit": 1})
+async def test_thread_pagination_offset(api: ApiCtx) -> None:
+    first = await api.client.get("/api/threads", params={"limit": 1, "offset": 0})
     body = first.json()
     assert len(body["threads"]) == 1
-    assert body["cursor"] is not None
-    second = await api.client.get("/api/threads", params={"limit": 1, "cursor": body["cursor"]})
+    assert body["total"] >= 2  # more than one page of threads exists
+    second = await api.client.get("/api/threads", params={"limit": 1, "offset": 1})
     body2 = second.json()
     assert len(body2["threads"]) == 1
+    assert body2["total"] == body["total"]  # grand total is stable across pages
     assert body2["threads"][0]["id"] != body["threads"][0]["id"]

backend/tests/api/test_saved_searches.py

@@ -0,0 +1,141 @@
+"""Saved searches CRUD — stored queries shown as virtual mailboxes (SPEC §12 M2)."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+
+import httpx
+import pytest_asyncio
+from httpx import ASGITransport
+from sqlalchemy import delete
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import get_settings
+from app.identity.passwords import hash_password
+from app.identity.sessions import create_session
+from app.main import create_app
+from app.models import User
+
+CSRF = "csrf"
+
+
+@dataclass
+class Ctx:
+    client: httpx.AsyncClient
+    user_id: uuid.UUID
+
+
+def _hdr() -> dict[str, str]:
+    return {"X-CSRF": CSRF}
+
+
+@pytest_asyncio.fixture
+async def ctx() -> AsyncIterator[Ctx]:
+    engine = create_async_engine(get_settings().database_url, poolclass=NullPool)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+    session = sm()
+    user = User(handle=f"ss{uuid.uuid4().hex[:8]}@test.local", password_hash=hash_password("pw"))
+    session.add(user)
+    await session.commit()
+    token = await create_session(user.id, "pytest")
+    client = httpx.AsyncClient(
+        transport=ASGITransport(app=create_app()),
+        base_url="http://testserver",
+        cookies={"session": token, "csrf": CSRF},
+    )
+    try:
+        yield Ctx(client=client, user_id=user.id)
+    finally:
+        await client.aclose()
+        await session.execute(delete(User).where(User.id == user.id))
+        await session.commit()
+        await session.close()
+        await engine.dispose()
+
+
+async def test_saved_search_crud_and_upsert(ctx: Ctx) -> None:
+    # Empty to start.
+    resp = await ctx.client.get("/api/saved-searches")
+    assert resp.status_code == 200
+    assert resp.json() == []
+
+    # Create.
+    resp = await ctx.client.post(
+        "/api/saved-searches",
+        json={"name": "Unread from boss", "query": "is:unread from:boss"},
+        headers=_hdr(),
+    )
+    assert resp.status_code == 200
+    created = resp.json()
+    assert created["name"] == "Unread from boss"
+    assert created["query"] == "is:unread from:boss"
+    assert created["pinned"] is True
+    sid = created["id"]
+
+    # It lists back.
+    resp = await ctx.client.get("/api/saved-searches")
+    assert [s["name"] for s in resp.json()] == ["Unread from boss"]
+
+    # Re-saving under the same name upserts (updates query, keeps a single row).
+    resp = await ctx.client.post(
+        "/api/saved-searches",
+        json={"name": "Unread from boss", "query": "is:unread from:ceo"},
+        headers=_hdr(),
+    )
+    assert resp.status_code == 200
+    assert resp.json()["id"] == sid  # same row
+    assert resp.json()["query"] == "is:unread from:ceo"
+
+    rows = (await ctx.client.get("/api/saved-searches")).json()
+    assert len(rows) == 1 and rows[0]["query"] == "is:unread from:ceo"
+
+    # Delete.
+    resp = await ctx.client.delete(f"/api/saved-searches/{sid}", headers=_hdr())
+    assert resp.status_code == 200
+    assert (await ctx.client.get("/api/saved-searches")).json() == []
+
+    # Deleting a missing row 404s.
+    resp = await ctx.client.delete(f"/api/saved-searches/{uuid.uuid4()}", headers=_hdr())
+    assert resp.status_code == 404
+
+
+async def test_saved_search_requires_csrf(ctx: Ctx) -> None:
+    # No CSRF header -> rejected (state-changing route).
+    resp = await ctx.client.post(
+        "/api/saved-searches", json={"name": "x", "query": "y"}
+    )
+    assert resp.status_code == 403
+
+
+async def test_saved_search_is_per_user(ctx: Ctx) -> None:
+    await ctx.client.post(
+        "/api/saved-searches",
+        json={"name": "Mine", "query": "in:inbox"},
+        headers=_hdr(),
+    )
+    # A different user's client sees none of the above.
+    other = User(handle=f"ss{uuid.uuid4().hex[:8]}@test.local", password_hash=hash_password("pw"))
+    engine = create_async_engine(get_settings().database_url, poolclass=NullPool)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+    session = sm()
+    session.add(other)
+    await session.commit()
+    token = await create_session(other.id, "pytest")
+    try:
+        client = httpx.AsyncClient(
+            transport=ASGITransport(app=create_app()),
+            base_url="http://testserver",
+            cookies={"session": token, "csrf": CSRF},
+        )
+        try:
+            assert (await client.get("/api/saved-searches")).json() == []
+        finally:
+            await client.aclose()
+    finally:
+        await session.execute(delete(User).where(User.id == other.id))
+        await session.commit()
+        await session.close()
+        await engine.dispose()

backend/tests/search/test_meili.py

@@ -0,0 +1,79 @@
+"""Meilisearch backend (SPEC §8, M2). Runs against the live Meili in the dev/CI
+stack; skips if it is unreachable so the rest of the suite still runs locally."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+
+import pytest
+
+from app.search.base import SearchDoc
+from app.search.meili import MeiliSearchBackend
+from app.search.queryparser import to_search_query
+
+
+def _doc(user_id: uuid.UUID) -> SearchDoc:
+    return SearchDoc(
+        message_id=uuid.uuid4(),
+        thread_id=uuid.uuid4(),
+        user_id=user_id,
+        account_id=uuid.uuid4(),
+        mailbox_special_use="inbox",
+        from_=[{"name": "Bob Vendor", "email": "bob@vendor.com"}],
+        to=[{"name": "Me", "email": "me@x.com"}],
+        cc=[],
+        subject="Your invoice for March",
+        body_text="Please find attached the invoice, amount due soon.",
+        attachment_names=["invoice.pdf"],
+        has_attachments=True,
+        is_unread=True,
+        is_starred=False,
+        date=int(time.time()),
+        size_bytes=2048,
+    )
+
+
+async def _poll(backend: MeiliSearchBackend, q: str, user_id: uuid.UUID) -> int:
+    """Indexing is async in Meili; retry briefly until the doc is searchable."""
+    for _ in range(60):
+        hits, _c = await backend.query(to_search_query(q, user_id), limit=10, cursor=None)
+        if hits:
+            return len(hits)
+        await asyncio.sleep(0.05)
+    return 0
+
+
+async def test_meili_typo_tolerance_and_filters() -> None:
+    backend = MeiliSearchBackend()
+    user_id = uuid.uuid4()
+    try:
+        await backend.index(_doc(user_id))
+
+        # Acceptance (§12 M2): a typo still finds the message.
+        hits, _c = await backend.query(
+            to_search_query("invocie", user_id), limit=10, cursor=None
+        )
+        if not hits:  # wait for the async index task
+            assert await _poll(backend, "invocie", user_id) == 1
+            hits, _c = await backend.query(
+                to_search_query("invocie", user_id), limit=10, cursor=None
+            )
+        assert len(hits) == 1
+        assert "<mark>" in hits[0].highlights.get("subject", "")
+
+        async def n(query: str) -> int:
+            res, _c = await backend.query(to_search_query(query, user_id), limit=10, cursor=None)
+            return len(res)
+
+        assert await n("is:unread invoice") == 1
+        assert await n("is:read invoice") == 0  # the doc is unread
+        assert await n("from:vendor") == 1  # field operator folded into the query
+        assert await n("larger:1k invoice") == 1
+        assert await n("larger:5k invoice") == 0
+        assert await n("in:sent invoice") == 0  # doc is in the inbox
+    except (ConnectionError, OSError) as exc:  # Meili not running locally
+        pytest.skip(f"Meilisearch unavailable: {exc}")
+    finally:
+        await backend.delete_user(user_id)

backend/tests/search/test_search_api.py

@@ -150,6 +150,24 @@ async def test_free_text(seeded: Ctx) -> None:
     assert await _search(seeded, "lunch") == 1
 
 
+async def test_free_text_prefix_matches_while_typing(seeded: Ctx) -> None:
+    # Search-as-you-type: a partial word finds the message before it is complete.
+    assert await _search(seeded, "reven") == 1  # -> "revenue"
+    assert await _search(seeded, "lun") == 1  # -> "lunch"
+    # Prefix is anchored at word start, not a substring match.
+    assert await _search(seeded, "enue") == 0
+    # Multiple partial words are ANDed as prefixes.
+    assert await _search(seeded, "quart reven") == 1  # "Quarterly revenue"
+    assert await _search(seeded, "quart lun") == 0
+
+
+async def test_free_text_full_email_address(seeded: Ctx) -> None:
+    # Postgres keeps an email as a single lexeme; searching the *whole* address
+    # must still match (regression: prefix-splitting on word chars broke this).
+    assert await _search(seeded, "bob@corp.com") == 1
+    assert await _search(seeded, "bob@corp.co") == 1  # prefix while still typing
+
+
 async def test_from_operator(seeded: Ctx) -> None:
     assert await _search(seeded, "from:bob") == 1
     assert await _search(seeded, "from:corp.com") == 3  # all three share the domain

backend/tests/sync/test_backfill_window.py

@@ -0,0 +1,160 @@
+"""Sync-window backfill strategies at account setup (SPEC §12 M2): all (recent
+first, then remainder), 3months (windowed), new (no history, watermark only)."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator
+from datetime import UTC, date, datetime, timedelta
+from email.message import EmailMessage
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import get_settings
+from app.identity.passwords import hash_password
+from app.models import Account, Mailbox, Message, User
+from app.providers.base import RemoteMailbox, RemoteMessage
+from app.sync import engine as sync_engine
+
+
+def _raw(mid: str) -> bytes:
+    m = EmailMessage()
+    m["Subject"] = "hi"
+    m["From"] = "me@example.com"
+    m["To"] = "bob@example.com"
+    m["Message-ID"] = mid
+    m["Date"] = "Mon, 09 Mar 2026 08:36:37 +0100"
+    m.set_content("body")
+    return m.as_bytes()
+
+
+class _FakeProvider:
+    def __init__(self) -> None:
+        self.backfill_calls: list[tuple[str, date | None, date | None]] = []
+        self.count_calls: list[tuple[str, date | None]] = []
+        self.newest_calls: list[str] = []
+
+    async def list_mailboxes(self) -> list[RemoteMailbox]:
+        return [RemoteMailbox(path="INBOX", special_use="inbox", uidvalidity=1)]
+
+    async def message_count(self, mailbox: str, *, since: date | None = None) -> int:
+        self.count_calls.append((mailbox, since))
+        return 3
+
+    async def newest_uid(self, mailbox: str) -> int:
+        self.newest_calls.append(mailbox)
+        return 42
+
+    async def backfill(  # type: ignore[no-untyped-def]
+        self, mailbox, *, newest_first=True, batch_size=200, since=None, before=None
+    ) -> AsyncIterator[list[RemoteMessage]]:
+        self.backfill_calls.append((mailbox, since, before))
+        # Distinct UID per pass so recent + remainder both persist a row.
+        uid = 100 if since is not None else 50
+        yield [
+            RemoteMessage(
+                uid=uid,
+                raw=_raw(f"<{mailbox}-{uid}@x.com>"),
+                flags=frozenset(),
+                internal_date=datetime.now(UTC),
+            )
+        ]
+
+    async def close(self) -> None:
+        return None
+
+
+async def _seed(sm: async_sessionmaker, window: str) -> tuple[uuid.UUID, uuid.UUID]:  # type: ignore[type-arg]
+    session = sm()
+    user = User(handle=f"bf{uuid.uuid4().hex[:8]}@test.local", password_hash=hash_password("pw"))
+    session.add(user)
+    await session.flush()
+    account = Account(
+        user_id=user.id,
+        email="me@example.com",
+        imap_config={},
+        smtp_config={},
+        secret_ct=b"",
+        discovery_src="manual",
+        sync_window=window,
+    )
+    session.add(account)
+    await session.commit()
+    aid = account.id
+    await session.close()
+    return user.id, aid
+
+
+async def test_window_new_sets_watermark_and_skips_backfill(monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    engine = create_async_engine(get_settings().database_url, poolclass=NullPool)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+    _uid, account_id = await _seed(sm, "new")
+    fake = _FakeProvider()
+    monkeypatch.setattr(sync_engine, "build_provider", lambda _a: fake)
+    try:
+        count = await sync_engine.bootstrap_and_backfill(account_id)
+        assert count == 0
+        assert fake.backfill_calls == []  # no history fetched
+        assert fake.newest_calls == ["INBOX"]
+
+        session = sm()
+        acct = await session.get(Account, account_id)
+        assert acct is not None and acct.state == "live" and acct.backfill_total == 0
+        mb = await session.scalar(select(Mailbox).where(Mailbox.account_id == account_id))
+        assert mb is not None and mb.last_seen_uid == 42  # moved to the tip
+        msgs = await session.scalar(
+            select(func.count()).select_from(Message).where(Message.mailbox_id == mb.id)
+        )
+        assert msgs == 0  # nothing imported
+        await session.close()
+    finally:
+        await engine.dispose()
+
+
+async def test_window_all_imports_recent_then_remainder(monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    engine = create_async_engine(get_settings().database_url, poolclass=NullPool)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+    _uid, account_id = await _seed(sm, "all")
+    fake = _FakeProvider()
+    monkeypatch.setattr(sync_engine, "build_provider", lambda _a: fake)
+    try:
+        await sync_engine.bootstrap_and_backfill(account_id)
+
+        # Two passes per mailbox: recent window (since set), then the older
+        # remainder (before set) — the "usable fast, then fill in" strategy.
+        cutoff = date.today() - timedelta(days=sync_engine._RECENT_DAYS)
+        assert fake.backfill_calls == [("INBOX", cutoff, None), ("INBOX", None, cutoff)]
+        assert fake.count_calls == [("INBOX", None)]  # denominator = whole mailbox
+
+        session = sm()
+        acct = await session.get(Account, account_id)
+        assert acct is not None and acct.state == "live"
+        assert acct.backfill_total == 3 and acct.backfill_done == 2
+        mb = await session.scalar(select(Mailbox).where(Mailbox.account_id == account_id))
+        assert mb is not None
+        msgs = await session.scalar(
+            select(func.count()).select_from(Message).where(Message.mailbox_id == mb.id)
+        )
+        assert msgs == 2  # one from each pass
+        await session.close()
+    finally:
+        await engine.dispose()
+
+
+async def test_window_3months_single_dated_pass(monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    engine = create_async_engine(get_settings().database_url, poolclass=NullPool)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+    _uid, account_id = await _seed(sm, "3months")
+    fake = _FakeProvider()
+    monkeypatch.setattr(sync_engine, "build_provider", lambda _a: fake)
+    try:
+        await sync_engine.bootstrap_and_backfill(account_id)
+
+        since = date.today() - timedelta(days=sync_engine._WINDOW_DAYS["3months"])
+        assert fake.backfill_calls == [("INBOX", since, None)]  # single windowed pass
+        assert fake.count_calls == [("INBOX", since)]  # denominator counts the window
+        await engine.dispose()
+    finally:
+        pass

backend/tests/threading/test_threading.py

@@ -72,6 +72,48 @@ async def test_broken_client_subject_only_joins(env: ThreadingEnv) -> None:
     assert a.thread_id == b.thread_id
 
 
+async def test_auto_replies_to_different_originals_do_not_join(env: ThreadingEnv) -> None:
+    # Two out-of-office auto-replies, same subject and same recipient, but each
+    # replying to a DIFFERENT (absent) original. They must not be subject-merged.
+    a = await env.add(
+        message_id="autoA@tvp.pl",
+        subject="Automatyczna odpowiedź: Silent Hill",
+        from_email="robert@tvp.pl",
+        to_email="me@gmail.com",
+        in_reply_to="orig1@mail.gmail.com",
+        references=["orig1@mail.gmail.com"],
+    )
+    b = await env.add(
+        message_id="autoB@wfdif.com.pl",
+        subject="Automatyczna odpowiedź: Silent Hill",
+        from_email="dyrektor@wfdif.com.pl",
+        to_email="me@gmail.com",
+        in_reply_to="orig2@mail.gmail.com",
+        references=["orig2@mail.gmail.com"],
+        minutes=5,
+    )
+    assert a.thread_id != b.thread_id
+
+
+async def test_replies_to_same_absent_parent_join(env: ThreadingEnv) -> None:
+    # Two replies that reference the SAME (absent) original — and not each other —
+    # still thread together via the shared parent reference.
+    a = await env.add(
+        message_id="r1@x.com",
+        subject="Re: Topic",
+        in_reply_to="orig@x.com",
+        references=["orig@x.com"],
+    )
+    b = await env.add(
+        message_id="r2@x.com",
+        subject="Re: Topic",
+        in_reply_to="orig@x.com",
+        references=["orig@x.com"],
+        minutes=3,
+    )
+    assert a.thread_id == b.thread_id
+
+
 async def test_distinct_topic_same_subject_does_not_join(env: ThreadingEnv) -> None:
     a = await env.add(
         message_id="a@x.com",