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/web/static/css/app.css

@@ -18,6 +18,19 @@ body {
   height: 100%;
 }
 
+/*
+  The `hidden` attribute has to win.
+
+  The browser's own rule is `[hidden] { display: none }`, which any component
+  rule setting `display` outranks -- `.btn` is `display: inline-flex`, so a
+  button hidden from JavaScript stayed visible. That is not a styling nit: it
+  is how the Stop button came to sit permanently beside Send. Anything toggled
+  with `hidden` anywhere in the application depends on this line.
+*/
+[hidden] {
+  display: none !important;
+}
+
 body {
   margin: 0;
   font-family: var(--font-body);

src/lembas/web/static/css/chat.css

@@ -197,6 +197,67 @@
   50% { opacity: 1; }
 }
 
+/* --- Tool activity --------------------------------------------------------
+   Deliberately the same object as the reasoning block: both answer "what did
+   it do before it replied", and giving them two visual languages would suggest
+   a difference that is not there. */
+.tool-activity-list:empty { display: none; }
+
+.tool-activity {
+  margin: 0 0 var(--sp-3);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: color-mix(in srgb, var(--surface) 70%, transparent);
+  font-size: var(--text-sm);
+}
+.tool-activity--error { border-color: var(--danger); }
+
+.tool-activity__summary {
+  display: flex;
+  align-items: center;
+  gap: var(--sp-2);
+  padding: var(--sp-2) var(--sp-3);
+  cursor: pointer;
+  color: var(--ink-muted);
+  list-style: none;
+  user-select: none;
+  border-radius: var(--radius);
+}
+.tool-activity__summary::-webkit-details-marker { display: none; }
+.tool-activity__summary:hover { color: var(--ink); background: var(--surface-hover); }
+.tool-activity__icon { color: var(--gold); flex: none; }
+.tool-activity__label { flex: 1; }
+.tool-activity__count { color: var(--ink-faint); }
+.tool-activity[open] .reasoning__chevron { transform: rotate(180deg); }
+
+.tool-activity__body {
+  padding: 0 var(--sp-3) var(--sp-3);
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-3);
+}
+.tool-activity__error { margin: 0; color: var(--ink-muted); }
+
+.tool-result {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding-left: var(--sp-3);
+  border-left: 2px solid var(--border-strong);
+  min-width: 0;
+}
+.tool-result__title {
+  color: var(--accent);
+  font-weight: 500;
+  overflow-wrap: anywhere;
+}
+.tool-result__host { color: var(--ink-faint); font-size: var(--text-xs); }
+.tool-result__snippet {
+  margin: 0;
+  color: var(--ink-muted);
+  line-height: var(--leading-relaxed);
+}
+
 /* --- Stop, notes and editing ---------------------------------------------- */
 .msg__waiting {
   display: flex;
@@ -208,15 +269,45 @@
    the dots go, but Stop must stay reachable until the stream ends. */
 .msg__body--live:not(:empty) + .msg__waiting .dots { display: none; }
 
-.composer__stop {
+/* Send and Stop are one button. Which icon shows is decided here rather than
+   in JavaScript, so the state is visible in the markup and the swap is free. */
+.composer__icon { display: flex; }
+[data-composer-action="send"] .composer__icon--stop,
+[data-composer-action="stop"] .composer__icon--send { display: none; }
+
+.composer__btn[data-composer-action="stop"] {
   background: var(--danger);
   border-color: var(--danger);
   color: var(--ink-inverse);
 }
-.composer__stop:hover:not(:disabled) {
+.composer__btn[data-composer-action="stop"]:hover:not(:disabled) {
   background: var(--danger-hover);
   border-color: var(--danger-hover);
 }
+/* The microphone is the same shape: one button, state in a data attribute. */
+[data-mic-state="idle"] .composer__icon--recording,
+[data-mic-state="working"] .composer__icon--recording,
+[data-mic-state="recording"] .composer__icon--mic { display: none; }
+
+.composer__mic[data-mic-state="recording"] {
+  background: var(--danger);
+  border-color: var(--danger);
+  color: var(--ink-inverse);
+  animation: mic-pulse 1.6s ease-in-out infinite;
+}
+
+@keyframes mic-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 var(--accent-soft); }
+  50% { box-shadow: 0 0 0 5px transparent; }
+}
+
+/* Play and stop on the read-aloud button, chosen by the class audio.js sets. */
+.speak__icon { display: flex; }
+[data-speak] .speak__icon--stop,
+[data-speak].is-speaking .speak__icon--play { display: none; }
+[data-speak].is-speaking .speak__icon--stop { display: flex; }
+[data-speak].is-speaking { color: var(--accent); }
+
 .composer__stop-square {
   width: 0.7rem;
   height: 0.7rem;

src/lembas/web/static/js/app.js

@@ -26,6 +26,16 @@
       localStorage.setItem(THEME_KEY, name);
     } catch (e) { /* private mode */ }
 
+    /* Installed, the browser's own chrome is the application's chrome, so it
+       has to follow the theme too. Read from the stylesheet rather than
+       repeating the hex here: tokens.css is the one place colours live. */
+    var meta = document.querySelector('meta[name="theme-color"]');
+    if (meta) {
+      var bg = getComputedStyle(document.documentElement)
+        .getPropertyValue("--bg").trim();
+      if (bg) meta.setAttribute("content", bg);
+    }
+
     document.querySelectorAll("[data-theme-toggle]").forEach(function (el) {
       el.setAttribute("aria-label", name === "moria" ? "Switch to Shire (light)"
                                                      : "Switch to Moria (dark)");
@@ -190,13 +200,51 @@
     });
   }
 
+  /* --- Installing as an app ----------------------------------------------
+     Chromium fires beforeinstallprompt when it decides the app is installable
+     and lets the page defer the prompt. The event is the only handle on it, so
+     it is kept; there is no way to ask later whether one is available.
+
+     Nothing appears unless the browser offers it. Firefox and desktop Safari
+     never fire the event, and there is no useful button to show in their
+     place -- an "Install" that does nothing is worse than none. */
+  var installPrompt = null;
+
+  function revealInstall(show) {
+    document.querySelectorAll("[data-install-app]").forEach(function (el) {
+      el.hidden = !show;
+    });
+  }
+
+  function promptInstall() {
+    if (!installPrompt) return;
+    installPrompt.prompt();
+    installPrompt.userChoice.then(function () {
+      // A prompt is single-use, accepted or dismissed.
+      installPrompt = null;
+      revealInstall(false);
+    });
+  }
+
+  window.addEventListener("beforeinstallprompt", function (event) {
+    event.preventDefault();
+    installPrompt = event;
+    revealInstall(true);
+  });
+
+  window.addEventListener("appinstalled", function () {
+    installPrompt = null;
+    revealInstall(false);
+  });
+
   window.lembas = {
     applyTheme: applyTheme,
     toggleTheme: toggleTheme,
     copyText: copyText,
     scrollThread: scrollThread,
     autosize: autosize,
-    uploadFiles: uploadFiles
+    uploadFiles: uploadFiles,
+    promptInstall: promptInstall
   };
 
   /* --- Wiring ------------------------------------------------------------ */

src/lembas/web/static/js/audio.js

@@ -0,0 +1,209 @@
+/*
+  Dictation and read-aloud.
+
+  Both halves are progressive: without this file the composer and the message
+  bubbles still work, they simply have two buttons that do nothing. Neither
+  feature's markup is rendered at all unless an administrator has configured an
+  endpoint for it, so that state is rare rather than normal.
+*/
+(function () {
+  "use strict";
+
+  function notify(message, kind) {
+    if (window.lembas && window.lembas.notify) {
+      window.lembas.notify(message, { kind: kind || "info" });
+    }
+  }
+
+  /* --- Dictation ---------------------------------------------------------
+     MediaRecorder writes whatever container the browser prefers -- webm/opus
+     almost everywhere, mp4 on Safari. The file is passed upstream with the
+     type the browser reported rather than being converted here: whisper.cpp
+     and friends decode through ffmpeg and take all of them, and converting in
+     the browser would mean shipping an encoder. */
+  var recorder = null;
+  var chunks = [];
+  var micButton = null;
+
+  function setMicState(button, state) {
+    if (!button) return;
+    button.dataset.micState = state;
+    button.disabled = state === "working";
+    button.setAttribute(
+      "aria-label",
+      state === "recording" ? "Stop recording" : "Dictate a message"
+    );
+    button.title = button.getAttribute("aria-label");
+  }
+
+  function composerInput() {
+    return document.querySelector("[data-composer-input]");
+  }
+
+  function insertTranscript(text) {
+    var input = composerInput();
+    if (!input || !text) return;
+    // Appended rather than replacing: dictation is usually finishing a thought
+    // that was already half typed.
+    var existing = input.value.trim();
+    input.value = existing ? existing + " " + text : text;
+    if (window.lembas && window.lembas.autosize) window.lembas.autosize(input);
+    input.focus();
+    input.selectionStart = input.selectionEnd = input.value.length;
+  }
+
+  function upload(blob, button) {
+    var body = new FormData();
+    // The extension only has to be something the server can name the part;
+    // the endpoint sniffs the container itself.
+    var extension = (blob.type.indexOf("mp4") !== -1) ? "mp4" : "webm";
+    body.append("file", blob, "dictation." + extension);
+
+    setMicState(button, "working");
+    fetch("/api/audio/transcribe", {
+      method: "POST",
+      body: body,
+      credentials: "same-origin",
+    })
+      .then(function (response) {
+        if (!response.ok) {
+          return response.json()
+            .catch(function () { return {}; })
+            .then(function (payload) {
+              throw new Error(payload.detail || "Transcription failed.");
+            });
+        }
+        return response.text();
+      })
+      .then(function (text) {
+        setMicState(button, "idle");
+        if (!text.trim()) {
+          notify("Nothing was heard in that recording.", "info");
+          return;
+        }
+        insertTranscript(text.trim());
+      })
+      .catch(function (error) {
+        setMicState(button, "idle");
+        notify(error.message || "Transcription failed.", "error");
+      });
+  }
+
+  function startRecording(button) {
+    /* getUserMedia is undefined on plain http, which a self-hosted install on
+       a LAN address often is. Saying so beats a button that silently does
+       nothing -- the fix is not something the page can apply for them. */
+    if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia ||
+        typeof MediaRecorder === "undefined") {
+      notify(
+        "The microphone needs HTTPS or localhost. This page is served over " +
+        "plain HTTP, so the browser will not grant it.",
+        "error"
+      );
+      return;
+    }
+
+    navigator.mediaDevices.getUserMedia({ audio: true }).then(function (stream) {
+      chunks = [];
+      recorder = new MediaRecorder(stream);
+      micButton = button;
+
+      recorder.addEventListener("dataavailable", function (event) {
+        if (event.data && event.data.size) chunks.push(event.data);
+      });
+      recorder.addEventListener("stop", function () {
+        // Release the microphone immediately: leaving the track live keeps the
+        // browser's recording indicator on long after anyone is talking.
+        stream.getTracks().forEach(function (track) { track.stop(); });
+        var blob = new Blob(chunks, { type: recorder.mimeType || "audio/webm" });
+        recorder = null;
+        if (blob.size) upload(blob, button); else setMicState(button, "idle");
+      });
+
+      recorder.start();
+      setMicState(button, "recording");
+    }).catch(function () {
+      notify("The microphone could not be opened. Permission may be blocked.", "error");
+    });
+  }
+
+  function stopRecording() {
+    if (recorder && recorder.state !== "inactive") recorder.stop();
+  }
+
+  /* --- Reading a reply aloud ---------------------------------------------
+     One <audio> element for the whole page. Two replies talking over each
+     other is never what was wanted, and a shared element makes that
+     impossible rather than merely unlikely. */
+  var player = null;
+  var speaking = null;
+
+  function audioPlayer() {
+    if (!player) {
+      player = new Audio();
+      player.addEventListener("ended", function () { markSpeaking(null); });
+      player.addEventListener("error", function () {
+        if (speaking) notify("That reply could not be read out.", "error");
+        markSpeaking(null);
+      });
+    }
+    return player;
+  }
+
+  function markSpeaking(button) {
+    document.querySelectorAll("[data-speak]").forEach(function (el) {
+      el.classList.toggle("is-speaking", el === button);
+    });
+    speaking = button;
+  }
+
+  function speak(button) {
+    var element = audioPlayer();
+    if (speaking === button) {
+      element.pause();
+      markSpeaking(null);
+      return;
+    }
+    element.pause();
+    element.src = button.dataset.speak;
+    markSpeaking(button);
+    element.play().catch(function () {
+      /* Autoplay policies reject a play() the reader did not ask for. That is
+         the browser working as intended, so it is not reported as an error. */
+      markSpeaking(null);
+    });
+  }
+
+  /* --- Wiring ------------------------------------------------------------ */
+  document.addEventListener("click", function (event) {
+    var mic = event.target.closest("[data-mic]");
+    if (mic) {
+      event.preventDefault();
+      if (mic.dataset.micState === "recording") stopRecording();
+      else if (mic.dataset.micState === "idle") startRecording(mic);
+      return;
+    }
+
+    var speaker = event.target.closest("[data-speak]");
+    if (speaker) {
+      event.preventDefault();
+      speak(speaker);
+    }
+  });
+
+  /* A reply that has just finished streaming carries data-speak-auto, set only
+     on that one frame. Any swap can bring it in, so this watches them all and
+     clears the attribute after acting -- a later swap of the same bubble must
+     not start it again. */
+  function playArrivals() {
+    document.querySelectorAll("[data-speak-auto]").forEach(function (button) {
+      button.removeAttribute("data-speak-auto");
+      speak(button);
+    });
+  }
+
+  document.addEventListener("DOMContentLoaded", playArrivals);
+  if (document.body) {
+    document.body.addEventListener("htmx:afterSettle", playArrivals);
+  }
+})();

src/lembas/web/static/js/sw.js

@@ -0,0 +1,116 @@
+/*
+  Service worker.
+
+  Served from /sw.js rather than /static/js/sw.js: a worker's scope is the
+  directory it is served from, so one under /static/ could never control the
+  pages it is meant to serve. See api/pages.py.
+
+  What this is for is installability and an honest offline page -- NOT offline
+  chat. LLeMbas renders every page on the server, so a cached conversation
+  would be a snapshot that silently went stale, and a cached one belonging to
+  whoever was signed in last. The shell is cached; nothing with a user in it is.
+
+  The cache is versioned from the query string the registration adds
+  (/sw.js?v=<app version>), so a release invalidates it with no separate step.
+*/
+"use strict";
+
+var VERSION = new URL(self.location).searchParams.get("v") || "dev";
+var CACHE = "lembas-" + VERSION;
+
+/* The shell: everything needed to draw a page, plus the page shown when there
+   is no network. Deliberately no HTML but /offline -- see above. */
+var SHELL = [
+  "/offline",
+  "/static/css/tokens.css",
+  "/static/css/app.css",
+  "/static/css/chat.css",
+  "/static/css/admin.css",
+  "/static/js/app.js",
+  "/static/js/ui.js",
+  "/static/js/audio.js",
+  "/static/vendor/htmx.min.js",
+  "/static/vendor/htmx-ext-sse.js",
+  "/static/vendor/alpine.min.js",
+  "/static/img/favicon.svg",
+  "/static/img/logo-mark.svg",
+  "/static/img/icon-192.png",
+  "/static/img/icon-512.png",
+];
+
+self.addEventListener("install", function (event) {
+  event.waitUntil(
+    caches.open(CACHE).then(function (cache) {
+      // addAll is all-or-nothing: one 404 would leave the worker uninstalled
+      // and the whole feature silently off, so each entry is added on its own.
+      return Promise.all(
+        SHELL.map(function (path) {
+          return cache.add(new Request(path, { cache: "reload" })).catch(function () {});
+        })
+      );
+    }).then(function () { return self.skipWaiting(); })
+  );
+});
+
+self.addEventListener("activate", function (event) {
+  event.waitUntil(
+    caches.keys().then(function (names) {
+      return Promise.all(
+        names.map(function (name) {
+          if (name !== CACHE && name.indexOf("lembas-") === 0) return caches.delete(name);
+          return null;
+        })
+      );
+    }).then(function () { return self.clients.claim(); })
+  );
+});
+
+/* Paths this worker must never touch. /api/ carries the reply stream, the
+   unread poll, uploads and attachment downloads; /auth/ and /admin/ carry
+   credentials and settings. A cached response on any of them is at best stale
+   and at worst somebody else's. */
+function isExcluded(url) {
+  return url.pathname.indexOf("/api/") === 0 ||
+         url.pathname.indexOf("/auth/") === 0 ||
+         url.pathname.indexOf("/admin/") === 0 ||
+         url.pathname === "/sw.js";
+}
+
+self.addEventListener("fetch", function (event) {
+  var request = event.request;
+  if (request.method !== "GET") return;
+
+  var url = new URL(request.url);
+  if (url.origin !== self.location.origin) return;
+  if (isExcluded(url)) return;
+
+  /* A reply arrives as an endless event stream. Passing one through a worker
+     is the reliable way to turn a streaming answer into a single delivery at
+     the end, or into nothing at all -- so it is left entirely alone. */
+  if ((request.headers.get("accept") || "").indexOf("text/event-stream") !== -1) return;
+
+  if (request.mode === "navigate") {
+    event.respondWith(
+      fetch(request).catch(function () {
+        return caches.match("/offline");
+      })
+    );
+    return;
+  }
+
+  // Static assets: serve from cache, refresh in the background. They are
+  // versioned by the cache name, so a stale one only lasts until the next
+  // release.
+  event.respondWith(
+    caches.match(request).then(function (hit) {
+      var live = fetch(request).then(function (response) {
+        if (response && response.ok) {
+          var copy = response.clone();
+          caches.open(CACHE).then(function (cache) { cache.put(request, copy); });
+        }
+        return response;
+      }).catch(function () { return hit; });
+      return hit || live;
+    })
+  );
+});

src/lembas/web/static/js/ui.js

@@ -400,11 +400,17 @@ document.addEventListener("lembas:unread", function (event) {
 /*
   Send becomes Stop while a reply is being written.
 
-  The composer and the streaming bubble are far apart in the document, so the
-  link between them is made here: whenever the thread changes, look for a
-  message that is still streaming and point the button at it. A MutationObserver
-  rather than htmx events, because the bubble is replaced by an SSE swap that
-  does not always surface as one.
+  One button in the markup (see chat/_composer.html), retargeted here. The
+  composer and the streaming bubble are far apart in the document, so the link
+  between them is made at runtime: whenever the thread changes, look for a
+  message that is still streaming and point the button at it. A
+  MutationObserver rather than htmx events, because the bubble is replaced by
+  an SSE swap that does not always surface as one.
+
+  This used to build a second button and hide it with the `hidden` attribute,
+  which did nothing at all: `.btn` sets `display: inline-flex`, and that beats
+  the browser's `[hidden] { display: none }`. app.css now forces the attribute
+  to win, and there is only one button to get wrong.
 */
 (function () {
   "use strict";
@@ -418,48 +424,43 @@ document.addEventListener("lembas:unread", function (event) {
   }
 
   function sync() {
-    var form = document.querySelector(".composer__form");
-    if (!form) return;
-    var send = form.querySelector('[type="submit"]');
-    var stop = form.querySelector("[data-composer-stop]");
+    var button = document.querySelector("[data-composer-action]");
+    if (!button) return;
     var active = streamingMessage();
 
-    if (active) {
-      if (send) send.hidden = true;
-      if (!stop) {
-        stop = document.createElement("button");
-        stop.type = "button";
-        stop.className = "btn btn--icon composer__btn composer__stop";
-        stop.setAttribute("data-composer-stop", "");
-        stop.setAttribute("aria-label", "Stop generating");
-        stop.title = "Stop generating";
-        stop.innerHTML = '<span class="composer__stop-square"></span>';
-        stop.addEventListener("click", function () {
-          var target = streamingMessage();
-          if (!target) return;
-          stop.disabled = true;
-          fetch(
-            "/api/chats/" + target.chatId + "/messages/" + target.messageId + "/stop",
-            { method: "POST", credentials: "same-origin" }
-          ).catch(function () { stop.disabled = false; });
-        });
-        (send ? send.parentNode : form).appendChild(stop);
-      }
-      stop.hidden = false;
-      stop.disabled = false;
-    } else {
-      if (send) send.hidden = false;
-      if (stop) stop.hidden = true;
-    }
+    button.dataset.composerAction = active ? "stop" : "send";
+    // As a submit button the form sends; as a plain button the click handler
+    // below stops. Nothing else distinguishes the two states.
+    button.type = active ? "button" : "submit";
+    button.setAttribute("aria-label", active ? "Stop generating" : "Send");
+    button.title = active ? "Stop generating" : "";
+    button.disabled = false;
   }
 
+  document.addEventListener("click", function (event) {
+    var button = event.target.closest('[data-composer-action="stop"]');
+    if (!button) return;
+    event.preventDefault();
+
+    var target = streamingMessage();
+    if (!target) return;
+    // Disabled until the next sync, so a second click cannot fire a second
+    // request at a generation that is already stopping.
+    button.disabled = true;
+    fetch(
+      "/api/chats/" + target.chatId + "/messages/" + target.messageId + "/stop",
+      { method: "POST", credentials: "same-origin" }
+    ).catch(function () { button.disabled = false; });
+  });
+
   function watch() {
     var thread = document.getElementById("thread");
-    if (!thread) return;
-    new MutationObserver(sync).observe(thread, { childList: true, subtree: true });
+    if (thread) {
+      new MutationObserver(sync).observe(thread, { childList: true, subtree: true });
+    }
     sync();
   }
 
   document.addEventListener("DOMContentLoaded", watch);
-  document.body && document.body.addEventListener("htmx:afterSwap", sync);
+  document.body && document.body.addEventListener("htmx:afterSettle", sync);
 })();