PWA, one send/stop button, audio in and out, web search as a tool

Four pieces of work.

**Installable.** A manifest carrying the instance name, PWA icons rasterised
from the existing mark at design time, a service worker and a themed offline
page. The worker caches the shell only and bails out on /api/, /auth/, /admin/
and anything accepting text/event-stream -- passing a reply stream through a
worker turns it into one delivery at the end, or nothing. It is served from
GET /sw.js rather than the static mount because a worker's scope is the path it
came from.

**Send and Stop are one button.** They were two, and the hidden one was never
hidden: `.btn` is display: inline-flex, which outranks the browser's own
`[hidden] { display: none }`, so Stop sat permanently beside Send. app.css now
forces the attribute to win -- every control toggled with `hidden` depended on
that -- and the composer renders one button carrying both icons, with ui.js
flipping data-composer-action and the type with it.

**Audio.** Speech to text and text to speech against any OpenAI-shaped
/v1/audio/* endpoint: dictate into the composer, have a reply read out.
Instance settings in Admin, per-reader overrides in Settings, with the voice
list discovered from the server where it offers one. Recorded audio is capped
and never written to disk -- it is not an attachment, it has no owner, and
nothing would ever sweep it.

**Web search, as a tool.** This is the tool loop PLAN.md described as the real
work: one reply is now a bounded sequence of requests rather than one. The model
asks, the tool runs, the result goes back and it is asked again, up to three
rounds. Providers are DuckDuckGo (no setup), SearXNG and Firecrawl.

Two decisions worth stating. Tools are only offered to models flagged `tools`,
because an endpoint without support rejects the whole request rather than
ignoring the array -- the same reason images only reach models flagged
`vision`. And tool results are not replayed as context on the next turn, for the
same reasons reasoning is not: the answer already contains what the model made
of them, and replaying stale results into every later request wastes the window
and reliably sends a small model into a search loop. The sources stay visible in
the transcript instead.

Search results are untrusted third-party text and are treated as such: escaped,
and only http/https URLs rendered as links.

338 tests, ruff clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/lembas/api/admin.py

@@ -13,7 +13,7 @@ from sqlalchemy.orm import Session as DBSession
 from lembas.api.deps import AdminUser, Db
 from lembas.db.models import Connection, Model, User
 from lembas.services import settings_store
-from lembas.services.crypto import decrypt, encrypt, mask
+from lembas.services.crypto import UNCHANGED_SENTINEL, decrypt, encrypt, mask
 from lembas.services.llm.openai_client import Endpoint, LLMError, list_models
 from lembas.web.templating import render
 
@@ -21,11 +21,6 @@ log = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/admin", tags=["admin"])
 
-# Sent back in place of a stored key. If a submitted key still equals this, the
-# admin did not touch the field and the existing key must be kept -- otherwise
-# saving a name change would silently wipe the credential.
-UNCHANGED_SENTINEL = "•" * 12
-
 
 def _connection(db: DBSession, connection_id: str) -> Connection:
     connection = db.get(Connection, connection_id)

src/lembas/api/admin_audio.py

@@ -0,0 +1,187 @@
+"""Audio administration: the transcription and speech endpoints."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Form, Request, Response, status
+from fastapi.responses import RedirectResponse
+
+from lembas.api.deps import AdminUser, Db
+from lembas.services import audio as audio_service
+from lembas.services import settings_store
+from lembas.services.crypto import UNCHANGED_SENTINEL, decrypt, keep_or_replace, mask
+from lembas.services.llm.openai_client import LLMError
+from lembas.web.templating import render
+
+log = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/admin/audio", tags=["admin-audio"])
+
+# Read out by the speech test. Short, and the one line this project would pick.
+TEST_PHRASE = "Speak, friend, and enter."
+
+
+def _page_context(db: Db) -> dict:
+    config = settings_store.audio(db)
+    return {
+        "values": config,
+        "formats": audio_service.FORMATS,
+        "masked": {
+            "stt": mask(decrypt(config.get("stt_api_key_encrypted") or "")),
+            "tts": mask(decrypt(config.get("tts_api_key_encrypted") or "")),
+        },
+        "unchanged": UNCHANGED_SENTINEL,
+    }
+
+
+@router.get("")
+async def audio_page(request: Request, db: Db, user: AdminUser, saved: bool = False):
+    from lembas.api.audio import available_voices
+
+    context = _page_context(db)
+    voices, error = await available_voices(context["values"])
+    return render(
+        request,
+        "admin/audio.html",
+        {**context, "voices": voices, "voice_error": error, "saved": saved},
+    )
+
+
+@router.post("")
+async def save_audio(
+    db: Db,
+    user: AdminUser,
+    stt_enabled: bool = Form(False),
+    stt_base_url: str = Form(""),
+    stt_api_key: str = Form(""),
+    stt_model: str = Form(""),
+    stt_language: str = Form(""),
+    tts_enabled: bool = Form(False),
+    tts_base_url: str = Form(""),
+    tts_api_key: str = Form(""),
+    tts_model: str = Form(""),
+    tts_voice: str = Form(""),
+    tts_format: str = Form("mp3"),
+    tts_speed: float = Form(1.0),
+    tts_autoplay: bool = Form(False),
+) -> Response:
+    """Save both endpoints.
+
+    Unchecked checkboxes are absent from a form post, which is why every toggle
+    defaults to False here -- that absence *is* the "off" signal.
+    """
+    current = settings_store.audio(db)
+
+    settings_store.update(
+        db,
+        {
+            "stt_enabled": stt_enabled,
+            "stt_base_url": stt_base_url.strip().rstrip("/"),
+            "stt_api_key_encrypted": keep_or_replace(
+                stt_api_key, current.get("stt_api_key_encrypted") or ""
+            ),
+            "stt_model": stt_model.strip() or "whisper-1",
+            "stt_language": stt_language.strip()[:16],
+            "tts_enabled": tts_enabled,
+            "tts_base_url": tts_base_url.strip().rstrip("/"),
+            "tts_api_key_encrypted": keep_or_replace(
+                tts_api_key, current.get("tts_api_key_encrypted") or ""
+            ),
+            "tts_model": tts_model.strip() or "tts-1",
+            "tts_voice": tts_voice.strip()[:120],
+            "tts_format": tts_format if tts_format in audio_service.FORMATS else "mp3",
+            "tts_speed": min(max(tts_speed, 0.25), 4.0),
+            "tts_autoplay": tts_autoplay,
+        },
+        key=settings_store.AUDIO,
+    )
+
+    # The voice list belongs to whatever URL was configured before; keeping it
+    # would show the previous server's voices against the new one.
+    audio_service.forget_voices()
+    log.info("audio settings saved by %s", user.email)
+    return RedirectResponse("/admin/audio?saved=1", status_code=status.HTTP_303_SEE_OTHER)
+
+
+@router.post("/test/{side}")
+async def test_audio(request: Request, db: Db, user: AdminUser, side: str):
+    """Contact one of the two endpoints and report what happened.
+
+    Speech is tested by synthesising a phrase and measuring the bytes back;
+    transcription by sending a short generated tone, which is *expected* to come
+    back as no words at all. That still proves what matters -- the URL resolves,
+    the key is accepted and the response parses.
+    """
+    context = _page_context(db)
+    config = context["values"]
+    message, kind = "", "success"
+
+    try:
+        if side == "tts":
+            _, stream = await audio_service.speak(
+                audio_service.endpoint_for(config, "tts"),
+                TEST_PHRASE,
+                model=config.get("tts_model") or "tts-1",
+                voice=config.get("tts_voice") or "",
+                fmt=config.get("tts_format") or "mp3",
+                speed=float(config.get("tts_speed") or 1.0),
+            )
+            size = 0
+            async for chunk in stream:
+                size += len(chunk)
+            message = f"Spoke the test phrase: {size:,} bytes of audio."
+        elif side == "stt":
+            text = await audio_service.transcribe(
+                audio_service.endpoint_for(config, "stt"),
+                data=_silent_wav(),
+                filename="test.wav",
+                content_type="audio/wav",
+                model=config.get("stt_model") or "whisper-1",
+                language=config.get("stt_language") or "",
+            )
+            heard = f'Heard "{text}".' if text else "Heard nothing, as expected."
+            message = f"The endpoint answered. {heard}"
+        else:
+            message, kind = "Unknown endpoint.", "error"
+    except LLMError as exc:
+        message, kind = exc.message, "error"
+
+    voices, voice_error = [], ""
+    if side == "tts":
+        from lembas.api.audio import available_voices
+
+        voices, voice_error = await available_voices(config, refresh=True)
+
+    return render(
+        request,
+        "admin/_audio_result.html",
+        {
+            "side": side,
+            "message": message,
+            "message_kind": kind,
+            "voices": voices,
+            "voice_error": voice_error,
+            "values": config,
+        },
+    )
+
+
+def _silent_wav(seconds: float = 0.5, rate: int = 16000) -> bytes:
+    """A valid, silent WAV.
+
+    Generated rather than committed: half a second of silence is fourteen lines
+    of header arithmetic, and a binary fixture in the repository would be one
+    more thing nobody can review.
+    """
+    import struct
+
+    frames = int(rate * seconds)
+    data = b"\x00\x00" * frames
+    header = struct.pack(
+        "<4sI4s4sIHHIIHH4sI",
+        b"RIFF", 36 + len(data), b"WAVE",
+        b"fmt ", 16, 1, 1, rate, rate * 2, 2, 16,
+        b"data", len(data),
+    )
+    return header + data

src/lembas/api/admin_search.py

@@ -0,0 +1,110 @@
+"""Web search administration: which provider, and how to reach it."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Form, Request, Response, status
+from fastapi.responses import RedirectResponse
+
+from lembas.api.deps import AdminUser, Db
+from lembas.services import search as search_service
+from lembas.services import settings_store
+from lembas.services.crypto import UNCHANGED_SENTINEL, decrypt, keep_or_replace, mask
+from lembas.services.search.base import SearchError
+from lembas.web.templating import render
+
+log = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/admin/search", tags=["admin-search"])
+
+SAFESEARCH = ("off", "moderate", "strict")
+
+
+@router.get("")
+async def search_page(request: Request, db: Db, user: AdminUser, saved: bool = False):
+    values = settings_store.search(db)
+    return render(
+        request,
+        "admin/search.html",
+        {
+            "values": values,
+            "providers": search_service.PROVIDERS,
+            # Keyed by provider so the form can show an install hint against
+            # the one that needs it, without the template knowing why.
+            "problems": {
+                p.key: search_service.availability(p.key) for p in search_service.PROVIDERS
+            },
+            "safesearch_options": SAFESEARCH,
+            "masked": mask(decrypt(values.get("firecrawl_api_key_encrypted") or "")),
+            "unchanged": UNCHANGED_SENTINEL,
+            "saved": saved,
+        },
+    )
+
+
+@router.post("")
+async def save_search(
+    db: Db,
+    user: AdminUser,
+    enabled: bool = Form(False),
+    provider: str = Form("ddgs"),
+    max_results: int = Form(5),
+    region: str = Form("wt-wt"),
+    safesearch: str = Form("moderate"),
+    searxng_base_url: str = Form(""),
+    firecrawl_base_url: str = Form(""),
+    firecrawl_api_key: str = Form(""),
+    timeout: float = Form(20.0),
+) -> Response:
+    current = settings_store.search(db)
+    known = {p.key for p in search_service.PROVIDERS}
+
+    settings_store.update(
+        db,
+        {
+            "enabled": enabled,
+            "provider": provider if provider in known else "ddgs",
+            # An upper bound on what any single search may put in the prompt.
+            # Twenty results is already more than a model reads carefully.
+            "max_results": min(max(max_results, 1), 20),
+            "region": region.strip()[:16] or "wt-wt",
+            "safesearch": safesearch if safesearch in SAFESEARCH else "moderate",
+            "searxng_base_url": searxng_base_url.strip().rstrip("/"),
+            "firecrawl_base_url": firecrawl_base_url.strip().rstrip("/")
+            or "https://api.firecrawl.dev",
+            "firecrawl_api_key_encrypted": keep_or_replace(
+                firecrawl_api_key, current.get("firecrawl_api_key_encrypted") or ""
+            ),
+            "timeout": min(max(timeout, 5.0), 120.0),
+        },
+        key=settings_store.SEARCH,
+    )
+    log.info("web search %s by %s", "enabled" if enabled else "disabled", user.email)
+    return RedirectResponse("/admin/search?saved=1", status_code=status.HTTP_303_SEE_OTHER)
+
+
+@router.post("/test")
+async def test_search(request: Request, db: Db, user: AdminUser, query: str = Form("")):
+    """Run one real search and show what came back.
+
+    Against the stored settings rather than the unsaved form, so what is tested
+    is what a chat would actually do.
+    """
+    config = settings_store.search(db)
+    query = query.strip() or "lembas"
+
+    try:
+        results = await search_service.run(config, query)
+        message, kind = (
+            f"{search_service.provider(config.get('provider')).label} returned "
+            f"{len(results)} result{'' if len(results) == 1 else 's'}."
+        ), "success"
+    except SearchError as exc:
+        results, message, kind = [], exc.message, "error"
+
+    return render(
+        request,
+        "admin/_search_result.html",
+        {"results": results, "message": message, "message_kind": kind, "query": query},
+    )

src/lembas/api/audio.py

@@ -0,0 +1,183 @@
+"""Dictation and read-aloud.
+
+Both directions go through the server rather than from the browser to the audio
+endpoint directly, for the same reason model requests do: the endpoint is often
+on a private address the browser cannot reach, and its API key must never leave
+this process.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile, status
+from fastapi.responses import PlainTextResponse, Response, StreamingResponse
+from sqlalchemy.orm import Session as DBSession
+
+from lembas.api.deps import Db, RequiredUser, require_permission
+from lembas.db.models import Chat, Message, User
+from lembas.services import audio as audio_service
+from lembas.services import settings_store
+from lembas.services.llm.openai_client import LLMError
+from lembas.services.markdown import speakable_text
+
+log = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/audio", tags=["audio"])
+
+# A minute of speech is well under a megabyte in any browser codec; this is a
+# ceiling on nonsense, not a budget. Recorded audio is held in memory and never
+# written to disk: it is not an attachment, has no owner and nothing would ever
+# sweep it up.
+MAX_AUDIO_BYTES = 25 * 1024 * 1024
+
+
+def _user_audio(user: User) -> dict:
+    return dict((user.settings_json or {}).get("audio") or {})
+
+
+def resolve_voice(config: dict, user: User) -> str:
+    """The voice a given user should be read to in.
+
+    Their own choice, then the instance default, then whatever the endpoint
+    picks. Not validated against the discovered list: a voice can disappear
+    when a server is reconfigured, and falling back beats failing.
+    """
+    return (_user_audio(user).get("voice") or config.get("tts_voice") or "").strip()
+
+
+def resolve_speed(config: dict, user: User) -> float:
+    """The playback speed for this user, in the range every endpoint accepts.
+
+    Key presence decides which layer wins, not truthiness: chained `or` would
+    make a stored speed of 0 fall through to the default instead of being
+    clamped, which is a different answer for no stated reason.
+    """
+    preferences = _user_audio(user)
+    if "speed" in preferences:
+        raw = preferences["speed"]
+    elif "tts_speed" in config:
+        raw = config["tts_speed"]
+    else:
+        return 1.0
+
+    try:
+        chosen = float(raw)
+    except (TypeError, ValueError):
+        return 1.0
+    # Clamped rather than dropped, unlike the sampling parameters: a speed of 0
+    # is not a slower reading, it is silence.
+    return min(max(chosen, 0.25), 4.0)
+
+
+@router.post(
+    "/transcribe", dependencies=[Depends(require_permission("audio.transcribe"))]
+)
+async def transcribe(
+    db: Db, user: RequiredUser, file: UploadFile = File(...)
+) -> Response:
+    """Turn a recording into text for the composer.
+
+    Returns plain text, not HTML: the caller assigns it to a textarea's value,
+    where it is never parsed as markup.
+    """
+    config = settings_store.audio(db)
+    if not config.get("stt_enabled"):
+        raise HTTPException(
+            status.HTTP_404_NOT_FOUND, "Dictation is not enabled on this instance."
+        )
+
+    data = await file.read(MAX_AUDIO_BYTES + 1)
+    if len(data) > MAX_AUDIO_BYTES:
+        raise HTTPException(
+            status.HTTP_413_CONTENT_TOO_LARGE, "That recording is too long."
+        )
+    if not data:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "The recording was empty.")
+
+    language = (_user_audio(user).get("language") or config.get("stt_language") or "").strip()
+
+    try:
+        text = await audio_service.transcribe(
+            audio_service.endpoint_for(config, "stt"),
+            data=data,
+            filename=file.filename or "speech.webm",
+            content_type=file.content_type or "audio/webm",
+            model=config.get("stt_model") or "whisper-1",
+            language=language,
+        )
+    except LLMError as exc:
+        log.info("transcription failed: %s", exc.message)
+        raise HTTPException(status.HTTP_502_BAD_GATEWAY, exc.message) from exc
+
+    return PlainTextResponse(text)
+
+
+@router.get(
+    "/speech/{chat_id}/{message_id}",
+    dependencies=[Depends(require_permission("audio.listen"))],
+)
+async def speech(db: Db, user: RequiredUser, chat_id: str, message_id: str) -> Response:
+    """Read one message aloud."""
+    config = settings_store.audio(db)
+    if not config.get("tts_enabled"):
+        raise HTTPException(
+            status.HTTP_404_NOT_FOUND, "Read-aloud is not enabled on this instance."
+        )
+
+    message = _owned_message(db, chat_id, message_id, user)
+    text = speakable_text(message.content)
+    if not text:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "There is nothing to read out.")
+
+    try:
+        media_type, stream = await audio_service.speak(
+            audio_service.endpoint_for(config, "tts"),
+            text,
+            model=config.get("tts_model") or "tts-1",
+            voice=resolve_voice(config, user),
+            fmt=config.get("tts_format") or "mp3",
+            speed=resolve_speed(config, user),
+        )
+    except LLMError as exc:
+        log.info("speech failed: %s", exc.message)
+        raise HTTPException(status.HTTP_502_BAD_GATEWAY, exc.message) from exc
+
+    return StreamingResponse(
+        stream,
+        media_type=media_type,
+        # Not cached: the voice can change under the reader between plays, and
+        # a message can be regenerated at the same URL.
+        headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+    )
+
+
+async def available_voices(config: dict, *, refresh: bool = False) -> tuple[list[str], str]:
+    """Discovered voices and, if discovery failed, why.
+
+    Returns rather than raises: a settings page whose voice list could not be
+    fetched should still render, with the reason next to an empty list.
+    """
+    if not config.get("tts_enabled") or not (config.get("tts_base_url") or "").strip():
+        return [], ""
+    try:
+        return await audio_service.voices(
+            audio_service.endpoint_for(config, "tts"), refresh=refresh
+        ), ""
+    except LLMError as exc:
+        return [], exc.message
+
+
+def _owned_message(db: DBSession, chat_id: str, message_id: str, user: User) -> Message:
+    """The message, if it belongs to a chat this user owns.
+
+    404 rather than 403 throughout, matching api/chats.py: whether a given id
+    exists is not information these endpoints hand out.
+    """
+    chat = db.get(Chat, chat_id)
+    if chat is None or chat.user_id != user.id:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "That chat no longer exists.")
+    message = db.get(Message, message_id)
+    if message is None or message.chat_id != chat.id:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "That message no longer exists.")
+    return message

src/lembas/api/chats.py

@@ -16,6 +16,7 @@ from lembas.api.deps import Db, RequiredUser, require_permission
 from lembas.db.models import ROLE_ASSISTANT, ROLE_USER, Chat, Message, User
 from lembas.db.session import session_scope
 from lembas.security import permissions
+from lembas.services import audio as audio_service
 from lembas.services import chat as chat_service
 from lembas.services import files as files_service
 from lembas.services import generation as generation_service
@@ -183,6 +184,7 @@ async def post_message(
             "models_by_id": {
                 m.model_id: m for m in chat_service.available_models(db, user)
             },
+            **audio_service.template_flags(db, user),
         },
     )
 
@@ -217,6 +219,13 @@ async def stream_message(
     )
 
 
+def _tool_activity(events: list[dict], *, live: bool = True) -> str:
+    """Render the tool block. Whole, never a delta, like every other frame."""
+    return templates.get_template("chat/_tool_activity.html").render(
+        {"tool_events": events, "live": live}
+    )
+
+
 async def _follow(chat_id: str, message_id: str) -> AsyncIterator[str]:
     """Stream a generation that is running independently of this request.
 
@@ -238,6 +247,8 @@ async def _follow(chat_id: str, message_id: str) -> AsyncIterator[str]:
                 seen = generation.version
                 if generation.thinking:
                     yield sse.event("reasoning", escape_text(generation.thinking))
+                if generation.tool_events:
+                    yield sse.event("tools", _tool_activity(generation.tool_events))
                 if generation.content:
                     yield sse.event("render", render_markdown(generation.text))
 
@@ -259,6 +270,7 @@ async def _follow(chat_id: str, message_id: str) -> AsyncIterator[str]:
             yield sse.event("close", "")
             return
 
+        owner = db.get(User, chat.user_id)
         final_html = templates.get_template("chat/_message.html").render(
             {
                 "message": message,
@@ -267,10 +279,18 @@ async def _follow(chat_id: str, message_id: str) -> AsyncIterator[str]:
                 # Passed even though an assistant bubble never reads it: the
                 # template shares both roles, and a missing `user` would only
                 # blow up on whichever branch is not being exercised here.
-                "user": db.get(User, chat.user_id),
+                "user": owner,
                 "models_by_id": {
                     m.model_id: m for m in chat_service.available_models(db, None)
                 },
+                # This frame replaces the whole bubble, so it has to carry the
+                # speaker button's conditions too -- and the owner's, not the
+                # follower's: there is no request here to ask who is watching.
+                **audio_service.template_flags(db, owner),
+                # The one render that means "this reply just landed", which is
+                # what read-aloud-automatically keys off. A page load must not
+                # set it or reopening a chat would start talking.
+                "just_finished": True,
             }
         )
         title_html = templates.get_template("chat/_title_oob.html").render({"chat": chat})
@@ -294,6 +314,7 @@ def _thread_context(db: DBSession, chat: Chat, user: User) -> dict:
             if m.role == ROLE_ASSISTANT and m.content
         },
         "models_by_id": {m.model_id: m for m in chat_service.available_models(db, user)},
+        **audio_service.template_flags(db, user),
     }
 
 
@@ -565,6 +586,7 @@ async def regenerate(
             "models_by_id": {
                 m.model_id: m for m in chat_service.available_models(db, user)
             },
+            **audio_service.template_flags(db, user),
         },
     )
 

src/lembas/api/pages.py

@@ -2,20 +2,27 @@
 
 from __future__ import annotations
 
-from fastapi import APIRouter, HTTPException, Request, status
-from fastapi.responses import RedirectResponse
+from fastapi import APIRouter, HTTPException, Request, Response, status
+from fastapi.responses import FileResponse, JSONResponse, RedirectResponse
 from sqlalchemy import select
 from sqlalchemy.orm import Session as DBSession
 
 from lembas.api.deps import Db, RequiredUser
 from lembas.db.models import Chat, Folder, Message, User
 from lembas.security import permissions
+from lembas.services import audio as audio_service
 from lembas.services import chat as chat_service
+from lembas.services import settings_store
 from lembas.services.markdown import render_markdown
-from lembas.web.templating import render
+from lembas.web.templating import STATIC_DIR, render
 
 router = APIRouter(tags=["pages"])
 
+# Matches --bg for each theme in tokens.css. Duplicated here because the
+# manifest is JSON read by the operating system before any stylesheet exists;
+# there is nowhere for a CSS variable to resolve.
+THEME_COLOUR = {"moria": "#101317", "shire": "#F6F1E4"}
+
 
 def _chat_context(db: DBSession, user: User, chat: Chat | None) -> dict:
     """Model lists and permissions every chat page needs.
@@ -35,6 +42,7 @@ def _chat_context(db: DBSession, user: User, chat: Chat | None) -> dict:
         # may not be the model the chat is set to now. Keyed by model_id, the
         # denormalised value stored on each message.
         "models_by_id": {m.model_id: m for m in models},
+        **audio_service.template_flags(db, user),
     }
 
 
@@ -74,6 +82,70 @@ async def home(user: RequiredUser):
     return RedirectResponse("/chat", status_code=status.HTTP_303_SEE_OTHER)
 
 
+# --- Installing as an app -----------------------------------------------------
+# All three routes below are deliberately unauthenticated. A browser fetches a
+# manifest and a service worker outside any page's session, and an offline page
+# has by definition no server to ask who is looking at it.
+
+
+@router.get("/manifest.webmanifest", include_in_schema=False)
+async def manifest(db: Db) -> Response:
+    """The web app manifest.
+
+    A route rather than a static file because the name is an instance setting,
+    and an installed app showing "LLeMbas" when the instance is called something
+    else would be wrong on the one screen that is hardest to correct: the
+    launcher.
+    """
+    name = settings_store.get(db, "instance_name") or "LLeMbas"
+    return JSONResponse(
+        {
+            "id": "/",
+            "name": name,
+            "short_name": name[:12],
+            "description": "A web UI for your language models.",
+            "start_url": "/chat",
+            "scope": "/",
+            "display": "standalone",
+            "background_color": THEME_COLOUR["moria"],
+            "theme_color": THEME_COLOUR["moria"],
+            "icons": [
+                {"src": "/static/img/icon-192.png", "sizes": "192x192",
+                 "type": "image/png", "purpose": "any"},
+                {"src": "/static/img/icon-512.png", "sizes": "512x512",
+                 "type": "image/png", "purpose": "any"},
+                {"src": "/static/img/icon-maskable-512.png", "sizes": "512x512",
+                 "type": "image/png", "purpose": "maskable"},
+            ],
+        },
+        media_type="application/manifest+json",
+    )
+
+
+@router.get("/sw.js", include_in_schema=False)
+async def service_worker() -> Response:
+    """The service worker, served from the root.
+
+    A worker may only control pages at or below the path it was served from, so
+    one delivered by the /static mount would have scope /static/js/ and control
+    nothing. Serving it here is simpler than the Service-Worker-Allowed header
+    that would be needed otherwise.
+
+    no-store because a stale worker is a worker that keeps serving a stale
+    cache: the one file in the application that must never be held onto.
+    """
+    return FileResponse(
+        STATIC_DIR / "js" / "sw.js",
+        media_type="text/javascript",
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+@router.get("/offline", include_in_schema=False)
+async def offline(request: Request) -> Response:
+    return render(request, "offline.html", {})
+
+
 @router.get("/chat")
 async def chat_index(request: Request, db: Db, user: RequiredUser, model: str = ""):
     """A composer with no chat behind it yet.
@@ -177,6 +249,13 @@ async def settings_page(
     error: str = "",
     saved: str = "",
 ):
+    from lembas.api.audio import available_voices
+
+    context = _chat_context(db, user, None)
+    # Fetched here rather than by the template so a speech server that is down
+    # leaves the page renderable, with the reason beside an empty list.
+    voices, voice_error = await available_voices(context["audio"])
+
     # error/saved arrive as query parameters because the password form redirects
     # back here: a POST that re-rendered in place would re-submit on refresh.
     return render(
@@ -186,7 +265,9 @@ async def settings_page(
             "chat": None,
             "error": error,
             "saved": saved,
-            **_chat_context(db, user, None),
+            "voices": voices,
+            "voice_error": voice_error,
+            **context,
             **_sidebar_context(db, user),
         },
     )

src/lembas/api/preferences.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import logging
 
 from fastapi import APIRouter, Body, Form, Request, status
@@ -66,6 +67,40 @@ async def set_default_model(
     return RedirectResponse("/settings?saved=Default+model+updated.", status_code=303)
 
 
+@router.post("/audio")
+async def set_audio(
+    db: Db,
+    user: RequiredUser,
+    voice: str = Form(""),
+    speed: str = Form(""),
+    language: str = Form(""),
+    autoplay: bool = Form(False),
+) -> Response:
+    """Per-reader audio choices, overriding the instance defaults.
+
+    The voice is deliberately not checked against the discovered list. Voices
+    come and go when a speech server is reconfigured, and rejecting a saved
+    preference because a list fetched a moment ago did not mention it would be
+    a confusing failure with no obvious fix.
+    """
+    chosen: dict[str, object] = {"autoplay": autoplay}
+    if voice.strip():
+        chosen["voice"] = voice.strip()[:120]
+    if language.strip():
+        chosen["language"] = language.strip()[:16]
+    if speed.strip():
+        # An unreadable speed leaves the default in place rather than failing:
+        # nothing else on the form should be lost to a typo in one field.
+        with contextlib.suppress(ValueError):
+            chosen["speed"] = min(max(float(speed), 0.25), 4.0)
+
+    # Whole-dict reassignment: an in-place edit of a JSON column is not
+    # reliably detected as a change.
+    user.settings_json = {**(user.settings_json or {}), "audio": chosen}
+    db.commit()
+    return RedirectResponse("/settings?saved=Audio+preferences+updated.", status_code=303)
+
+
 @router.post("/password")
 async def change_password(
     request: Request,