lanternkb-ui 0.1.0__tar.gz

lanternkb_ui-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.DS_Store
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+
+# never commit indexes, configs or personal data
+*.db
+*.db-wal
+*.db-shm
+config.toml
+data/
+runs/
+.env*
+
+# third-party tool installs for the bake-off
+node_modules/

lanternkb_ui-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lanternkb_ui-0.1.0/NOTICE

@@ -0,0 +1,5 @@
+lanternkb
+Copyright 2026 ankitb073
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+Third-party code and data it ships or downloads are listed in THIRD_PARTY_NOTICES.md.

lanternkb_ui-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: lanternkb-ui
+Version: 0.1.0
+Summary: Optional settings page for lanternkb: runs only on demand, on loopback, and exits when closed.
+Author: ankitb073
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: lanternkb==0.1.0
+Description-Content-Type: text/markdown
+
+# lanternkb-ui
+
+The optional settings page for [lanternkb](https://github.com/ankitb073/lanternkb): folders and tiers, features,
+search in the browser, and sync progress. It runs only while you use it (`lanternkb ui`), listens on loopback only,
+and exits when closed. It uses the Python standard library and nothing else.
+
+Install it with lanternkb: `uv tool install "lanternkb[embed,ui]"`. Licence: Apache-2.0.

lanternkb_ui-0.1.0/README.md

@@ -0,0 +1,7 @@
+# lanternkb-ui
+
+The optional settings page for [lanternkb](https://github.com/ankitb073/lanternkb): folders and tiers, features,
+search in the browser, and sync progress. It runs only while you use it (`lanternkb ui`), listens on loopback only,
+and exits when closed. It uses the Python standard library and nothing else.
+
+Install it with lanternkb: `uv tool install "lanternkb[embed,ui]"`. Licence: Apache-2.0.

lanternkb_ui-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "lanternkb-ui"
+version = "0.1.0"
+description = "Optional settings page for lanternkb: runs only on demand, on loopback, and exits when closed."
+readme = "README.md"
+license = "Apache-2.0"  # lanternkb decision 0028
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.12"
+authors = [{ name = "ankitb073" }]
+dependencies = ["lanternkb==0.1.0"]  # and nothing else: the page uses the standard library only. Released together, so pinned
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lanternkb_ui"]
+
+[tool.uv.sources]
+lanternkb = { workspace = true }

lanternkb_ui-0.1.0/src/lanternkb_ui/__init__.py

@@ -0,0 +1 @@
+"""lanternkb-ui: the optional, on-demand settings page (decision 0007)."""

lanternkb_ui-0.1.0/src/lanternkb_ui/app.py

@@ -0,0 +1,627 @@
+"""The settings page server: on demand, loopback only, gone when the tab closes.
+
+Threat model T10 (docs/threat-model.md) and decision 0007:
+- **Loopback only, random port, random path.** The server binds 127.0.0.1 and serves
+  under a random path prefix; the session cookie is scoped to that path, so other servers
+  on 127.0.0.1 (cookies ignore ports) never receive it.
+- **A one-time token** in the opening link is exchanged for the session cookie (HttpOnly,
+  SameSite=Strict), then refused if used again. The link reaches the browser through a
+  private file (mode 600 in a folder only the user can enter), never through a command line
+  other users could read.
+- **Host, Origin and Sec-Fetch-Site checks** on every request (against DNS rebinding and
+  cross-site requests), and a per-session form token on every change. The referrer policy
+  is `same-origin`, so browsers send the page's real Origin with its forms.
+- **Every change goes through `lanternkb.control`,** which validates it, writes the config
+  atomically and records it in the audit log.
+- **Strict headers:** a Content-Security-Policy with per-response nonces, no framing, no
+  caching, no cross-origin access. Nothing is logged, and errors never reach the terminal.
+- **It exits** when its last open page says goodbye or stops its heartbeat, or after 10
+  minutes without a user action.
+"""
+
+from __future__ import annotations
+
+import hmac
+import http.server
+import json
+import logging
+import os
+import secrets
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import urllib.parse
+import webbrowser
+from dataclasses import dataclass, field
+from html import escape
+from http import HTTPStatus
+from pathlib import Path
+from typing import Any
+
+from lanternkb.control import Control, ControlError
+from lanternkb_ui import page
+
+IDLE_S = 600  # exit after this long without a user action
+BEAT_GRACE_S = 150  # a page whose heartbeat stopped this long is gone (hidden tabs beat slowly)
+BYE_GRACE_S = 3  # after the last page says goodbye, wait this long for a reload
+LOGIN_WINDOW_S = 300  # the opening link works this long
+MAX_BODY = 64_000
+
+
+# A looser tier needs a fresh read on an open worker first (review 11), so say so.
+OPEN_LATER = " Its files become open after the next sync reads them again."
+
+
+SEARCH_K = 20  # results on the search page
+RESULTS_KEPT = 20  # searches whose results the page can show again (back, reload)
+RESULTS_KEPT_S = 1800.0
+SEARCH_TIMEOUT_S = 120.0  # the first search may load the models
+
+
+@dataclass
+class State:
+    control: Control
+    port: int = 0
+    prefix: str = field(default_factory=lambda: "/" + secrets.token_urlsafe(12) + "/")
+    token: str = field(default_factory=lambda: secrets.token_urlsafe(32))
+    token_used: bool = False
+    started: float = field(default_factory=time.monotonic)
+    session: str | None = None
+    csrf: str = field(default_factory=lambda: secrets.token_urlsafe(24))
+    searcher: Searcher | None = None  # made on the first search
+    results: dict[str, tuple[float, dict[str, Any]]] = field(default_factory=dict)
+    last_action: float = field(default_factory=time.monotonic)
+    pages: dict[str, float] = field(default_factory=dict)  # page id -> last heartbeat
+    seen_page: bool = False  # a page has beaten at least once
+    bye_at: float | None = None
+    flash: list[tuple[str, str]] = field(default_factory=list)  # (kind, message)
+    sync: dict[str, Any] = field(default_factory=lambda: {"running": False})
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def keep(self, shown: dict[str, Any]) -> str:
+        """Keep a search's results for the page that shows them; returns their handle."""
+        handle = secrets.token_urlsafe(16)
+        now = time.monotonic()
+        with self.lock:
+            for h, (at, _) in list(self.results.items()):
+                if now - at > RESULTS_KEPT_S:
+                    del self.results[h]
+            while len(self.results) >= RESULTS_KEPT:
+                del self.results[next(iter(self.results))]  # the oldest
+            self.results[handle] = (now, shown)
+        return handle
+
+    def result(self, handle: str) -> dict[str, Any] | None:
+        with self.lock:
+            kept = self.results.get(handle)
+        if kept is None or time.monotonic() - kept[0] > RESULTS_KEPT_S:
+            return None
+        return kept[1]
+
+    def hosts(self) -> set[str]:
+        return {f"127.0.0.1:{self.port}", f"localhost:{self.port}"}
+
+    def origins(self) -> set[str]:
+        return {f"http://{h}" for h in self.hosts()}
+
+    @property
+    def cookie(self) -> str:
+        return f"lk_session_{self.port}"
+
+
+class Handler(http.server.BaseHTTPRequestHandler):
+    server_version = "lanternkb-ui"
+    sys_version = ""
+    timeout = 10  # an idle connection cannot hold a thread
+    state: State  # set on the subclass made by Server
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002 - stdlib signature
+        pass  # never log: request lines carry the token and paths
+
+    # -- checks -------------------------------------------------------------------------------
+
+    def _host_ok(self) -> bool:
+        return self.headers.get("Host", "") in self.state.hosts()
+
+    def _session_ok(self) -> bool:
+        session = self.state.session
+        if session is None:
+            return False
+        for part in self.headers.get("Cookie", "").split(";"):
+            name, _, value = part.strip().partition("=")
+            if name == self.state.cookie and hmac.compare_digest(
+                value.encode("utf-8", "replace"), session.encode()
+            ):
+                return True
+        return False
+
+    def _site_ok(self) -> bool:
+        """Browsers say where a request comes from; only this page itself, or the user
+        typing or following the link (`none`), may reach us."""
+        site = self.headers.get("Sec-Fetch-Site")
+        return site is None or site in ("same-origin", "none")
+
+    def _guard(self, write: bool) -> bool:
+        """Host and site for everything; session after login; Origin for changes."""
+        ok = self._host_ok() and self._site_ok() and self._session_ok()
+        if ok and write:
+            ok = self.headers.get("Origin", "") in self.state.origins()
+        if not ok:
+            self._send(HTTPStatus.FORBIDDEN, page.forbidden(), "text/html")
+        return ok
+
+    def _route(self) -> tuple[str, dict[str, list[str]]] | None:
+        """The path inside the app's random prefix, or None (not found)."""
+        url = urllib.parse.urlsplit(self.path)
+        if not url.path.startswith(self.state.prefix):
+            return None
+        return url.path[len(self.state.prefix) :], urllib.parse.parse_qs(url.query)
+
+    # -- responses ----------------------------------------------------------------------------
+
+    def _send(self, status: HTTPStatus, body: str, ctype: str, nonce: str = "",
+              extra: dict[str, str] | None = None) -> None:  # fmt: skip
+        data = body.encode()
+        self.send_response(status)
+        self.send_header("Content-Type", f"{ctype}; charset=utf-8")
+        self.send_header("Content-Length", str(len(data)))
+        script = f"'nonce-{nonce}'" if nonce else "'none'"
+        self.send_header("Content-Security-Policy",
+                         f"default-src 'none'; script-src {script}; style-src {script}; "
+                         "connect-src 'self'; form-action 'self'; base-uri 'none'; "
+                         "frame-ancestors 'none'")  # fmt: skip
+        self.send_header("X-Frame-Options", "DENY")
+        self.send_header("X-Content-Type-Options", "nosniff")
+        # same-origin, not no-referrer: with no-referrer browsers send `Origin: null` on
+        # the page's own form posts, which the Origin check must refuse.
+        self.send_header("Referrer-Policy", "same-origin")
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Cross-Origin-Opener-Policy", "same-origin")
+        self.send_header("Cross-Origin-Resource-Policy", "same-origin")
+        for k, v in (extra or {}).items():
+            self.send_header(k, v)
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(data)
+
+    def _redirect(self, location: str, extra: dict[str, str] | None = None) -> None:
+        self.send_response(HTTPStatus.SEE_OTHER)
+        self.send_header("Location", location)
+        self.send_header("Content-Length", "0")
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Referrer-Policy", "same-origin")
+        for k, v in (extra or {}).items():
+            self.send_header(k, v)
+        self.end_headers()
+
+    def _render(self, html_fn: Any, **kw: Any) -> None:
+        nonce = secrets.token_urlsafe(16)
+        with self.state.lock:
+            flash, self.state.flash = self.state.flash, []
+        body = html_fn(nonce=nonce, csrf=self.state.csrf, flash=flash, **kw)
+        self._send(HTTPStatus.OK, body, "text/html", nonce)
+
+    # -- GET ----------------------------------------------------------------------------------
+
+    def do_GET(self) -> None:  # noqa: N802 - stdlib name
+        route = self._route()
+        if route is None:
+            return self._send(HTTPStatus.NOT_FOUND, page.not_found(), "text/html")
+        path, query = route
+        if path == "start":
+            return self._login(query.get("t", [""])[0])
+        if not self._guard(write=False):
+            return None
+        if path != "sync/status":
+            self.state.last_action = time.monotonic()
+        c = self.state.control
+        if path == "":
+            return self._render(page.main, data=_gather(c), sync=dict(self.state.sync))
+        if path == "purge":
+            try:
+                plan = c.purge(query.get("feature", [""])[0], confirm=False)
+            except (ControlError, ValueError, OSError) as e:
+                self._flash("error", _message(e))
+                return self._redirect(self.state.prefix)
+            return self._render(page.purge_preview, plan=plan)
+        if path == "sync/status":
+            return self._send(HTTPStatus.OK, json.dumps(self.state.sync), "application/json")
+        if path == "search":  # the results of a search just sent (Post/Redirect/Get)
+            kept = self.state.result(query.get("r", [""])[0][:64])
+            searcher = self.state.searcher
+            if kept is None or searcher is None:
+                self._flash("error", "That search has expired; search again.")
+                return self._redirect(self.state.prefix)
+            # what today's config still shows (a hand edit of the config since the search)
+            still = searcher.still([r["path"] for r in kept["results"]])
+            kept = dict(kept, results=[r for r in kept["results"] if r["path"] in still])
+            return self._render(page.search, reveal=REVEAL_LABEL if _revealer() else "",
+                                **kept)  # fmt: skip
+        return self._send(HTTPStatus.NOT_FOUND, page.not_found(), "text/html")
+
+    def _login(self, token: str) -> None:
+        s = self.state
+        fresh = time.monotonic() - s.started < LOGIN_WINDOW_S
+        good = hmac.compare_digest(token.encode("utf-8", "replace"), s.token.encode())
+        if not (self._host_ok() and self._site_ok()) or s.token_used or not fresh or not good:
+            return self._send(HTTPStatus.FORBIDDEN, page.forbidden(), "text/html")
+        s.token_used = True
+        s.session = secrets.token_urlsafe(32)
+        s.last_action = time.monotonic()
+        cookie = f"{s.cookie}={s.session}; HttpOnly; SameSite=Strict; Path={s.prefix}"
+        return self._redirect(s.prefix, {"Set-Cookie": cookie})
+
+    # -- POST ---------------------------------------------------------------------------------
+
+    def do_POST(self) -> None:  # noqa: N802 - stdlib name
+        route = self._route()
+        if route is None:
+            return self._send(HTTPStatus.NOT_FOUND, page.not_found(), "text/html")
+        path, _query = route
+        if not self._guard(write=True):
+            return None
+        try:
+            length = int(self.headers.get("Content-Length") or 0)
+        except ValueError:
+            length = -1
+        if not 0 <= length <= MAX_BODY:
+            return self._send(HTTPStatus.REQUEST_ENTITY_TOO_LARGE, page.forbidden(), "text/html")
+        raw = self.rfile.read(length).decode("utf-8", "replace")
+        form = {k: v[0] for k, v in urllib.parse.parse_qs(raw, keep_blank_values=True).items()}
+        if path in ("beat", "bye"):  # page liveness, not user actions
+            self._liveness(path, form.get("page", "")[:64])
+            return self._send(HTTPStatus.NO_CONTENT, "", "text/plain")
+        if not hmac.compare_digest(form.get("csrf", "").encode(), self.state.csrf.encode()):
+            return self._send(HTTPStatus.FORBIDDEN, page.forbidden(), "text/html")
+        self.state.last_action = time.monotonic()
+        if path == "search":
+            return self._search(form)
+        if path == "reveal":
+            return self._reveal(form)
+        with self.state.lock:  # a change can hide or purge what kept results show (review 26)
+            self.state.results.clear()
+        try:
+            self._act(path, form)
+        except (ControlError, ValueError, OSError) as e:
+            self._flash("error", _message(e))
+        return self._redirect(self.state.prefix)
+
+    def _search(self, form: dict[str, str]) -> None:
+        s = self.state
+        with s.lock:
+            if s.searcher is None:
+                s.searcher = Searcher(s.control.config_path)
+            searcher = s.searcher
+        t0 = time.monotonic()
+        results, error, note = searcher.search(form)
+        took = int((time.monotonic() - t0) * 1000)
+        s.last_action = time.monotonic()  # a slow first search is not idle time
+        # Post/Redirect/Get (review 26): the results stay here under a random handle and the
+        # browser is sent to fetch them, so its history and session hold no form body (the
+        # query) and going back to the results is an ordinary page load.
+        form = {k: form.get(k, "") for k in ("q", "types", "since", "before")}
+        handle = s.keep({"form": form, "results": results, "error": error, "note": note,
+                         "took_ms": took})  # fmt: skip
+        return self._redirect(f"{s.prefix}search?r={handle}")
+
+    def _reveal(self, form: dict[str, str]) -> None:
+        """Show a search result's file in the file manager (never open or run it). Only a
+        result id is accepted, and only a file today's config still shows is revealed."""
+        searcher = self.state.searcher
+        path = (searcher.locate(form.get("id", ""), form.get("path", ""))
+                if searcher is not None else None)  # fmt: skip
+        if path is None or not _show(path):
+            return self._send(HTTPStatus.NOT_FOUND, "not available", "text/plain")
+        return self._send(HTTPStatus.NO_CONTENT, "", "text/plain")
+
+    def _liveness(self, what: str, page_id: str) -> None:
+        s = self.state
+        with s.lock:
+            if what == "beat" and page_id:
+                s.pages[page_id] = time.monotonic()
+                s.seen_page = True
+                s.bye_at = None
+            elif what == "bye":
+                s.pages.pop(page_id, None)
+                if not s.pages:
+                    s.bye_at = time.monotonic()
+
+    def _act(self, path: str, form: dict[str, str]) -> None:
+        c = self.state.control
+        feature, tier = form.get("feature", ""), form.get("tier", "")
+        if path == "feature/enable":
+            c.enable(feature)
+            self._flash("ok", f"{feature} is on. Its files are searchable again; a sync reads "
+                              "any that changed.")  # fmt: skip
+        elif path == "feature/disable":
+            c.disable(feature)
+            self._flash("ok", f"{feature} is off. Its data is hidden now; nothing was deleted.")
+        elif path == "feature/tier":
+            c.set_feature_tier(feature, tier)
+            self._flash("ok", f"{feature} is now {tier}." + (OPEN_LATER if tier == "open" else ""))
+        elif path == "feature/purge":
+            if form.get("confirm") != "yes":
+                raise ControlError("purge needs the confirmation box ticked")
+            plan = c.purge(feature, confirm=True)
+            self._flash("ok", f"Purged {feature}: {plan.files} files and {plan.chunks} chunks "
+                              "deleted securely.")  # fmt: skip
+        elif path == "root/add":
+            raw = form.get("path", "").strip()
+            if not (raw.startswith("/") or raw.startswith("~")):
+                raise ControlError("type the folder's full path (starting with / or ~)")
+            c.add_root(raw, tier or "local-only")
+            added = Path(os.path.expanduser(raw)).resolve()
+            self._flash("ok", f"Added {added} as {tier or 'local-only'}. Run a sync to index "
+                              "it.")  # fmt: skip
+        elif path == "root/tier":
+            c.set_root_tier(form.get("path", ""), tier)
+            self._flash("ok", f"Folder is now {tier}." + (OPEN_LATER if tier == "open" else ""))
+        elif path == "root/remove":
+            if form.get("confirm") != "yes":
+                raise ControlError("removing a folder needs the confirmation box ticked")
+            try:
+                n = c.remove_root(form.get("path", ""), force=form.get("force") == "yes")
+            except ControlError as e:
+                if "--force" in str(e):
+                    hint = ", or tick 'even if files become more visible'"
+                    raise ControlError(str(e).replace(", or use --force", hint)) from e
+                raise
+            self._flash("ok", f"Folder removed; {n} indexed file records deleted.")
+        elif path == "sync":
+            self._start_sync()
+        else:
+            raise ControlError("unknown action")
+
+    def _flash(self, kind: str, message: str) -> None:
+        with self.state.lock:
+            self.state.flash.append((kind, message))
+
+    def _start_sync(self) -> None:
+        s = self.state
+        with s.lock:
+            if s.sync.get("running"):
+                return
+            s.sync = {"running": True, "started": time.time()}
+
+        def progress(stage: str, done: int, total: int) -> None:
+            with s.lock:
+                if s.sync.get("running"):
+                    s.sync.update(stage=stage, done=done, total=total)
+
+        def run() -> None:
+            try:
+                r = s.control.sync(progress)
+                note = "; ".join(x for x in [*r.warnings, r.embed_note] if x)
+                result = {"ok": True, "seen": r.seen, "indexed": r.indexed,
+                          "unchanged": r.unchanged, "removed": r.removed,
+                          "skipped": sum(r.skipped.values()), "errors": r.errors,
+                          "embedded": r.embedded, "pending": r.pending,
+                          "note": note}  # fmt: skip
+            except Exception as e:  # noqa: BLE001 - shown on the page
+                result = {"ok": False, "error": _message(e)}
+            with s.lock:
+                s.sync = {"running": False, "finished": time.time(), "result": result}
+                s.results.clear()  # a sync can remove or change what kept results show
+
+        threading.Thread(target=run, daemon=True).start()
+
+
+def _message(e: BaseException) -> str:
+    """What the page may say about an error: control messages in full, others by type."""
+    return str(e) if isinstance(e, ControlError) else f"that did not work ({type(e).__name__})"
+
+
+REVEAL_LABEL = "Show in Finder" if sys.platform == "darwin" else "Show in folder"
+
+
+def _revealer() -> list[str] | None:
+    """The command that shows a file in the file manager here, if there is one."""
+    if sys.platform == "darwin":
+        return ["/usr/bin/open", "-R"]
+    opener = shutil.which("xdg-open")
+    return [opener] if opener else None
+
+
+def _show(path: str) -> bool:
+    """Show the file (its folder, on Linux) in the file manager; True if that started."""
+    cmd = _revealer()
+    target = path if sys.platform == "darwin" else os.path.dirname(path)
+    if cmd is None or not os.path.isabs(path) or not os.path.isfile(path):
+        return False
+    if sys.platform != "darwin" and not os.path.isdir(target):
+        return False
+    try:
+        subprocess.run([*cmd, target], timeout=10, check=True, stdin=subprocess.DEVNULL,
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)  # fmt: skip
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return True
+
+
+class Searcher:
+    """The search page's searches, run by the MCP server's own search on one thread: the
+    index connection stays on that thread, the models load on the first search and unload
+    when idle, and today's config decides what may be shown, as `lanternkb serve` does.
+    Every tier, except inside Claude Code, where it shows open files only, as the terminal
+    does (docs/threat-model.md: a speed bump, not a wall)."""
+
+    def __init__(self, config_path: Path) -> None:
+        from concurrent.futures import ThreadPoolExecutor
+
+        from lanternkb.server import Server as Core
+        from lanternkb.tiers import ServerTier
+
+        self.open_only = bool(os.environ.get("CLAUDECODE"))
+        self._pool = ThreadPoolExecutor(max_workers=1, thread_name_prefix="lanternkb-search")
+        self._lock = threading.Lock()
+        self._pending: set[Any] = set()
+        self._core = Core(config_path, ServerTier.OPEN if self.open_only else ServerTier.ALL)
+
+    def search(self, form: dict[str, str]) -> tuple[list[dict[str, Any]], str, str]:
+        """(results, error, note) for the form's query and filters."""
+        from lanternkb.server import ToolError
+
+        args = {"query": form.get("q", ""), "k": SEARCH_K, "types": form.get("types", ""),
+                "modified_after": form.get("since", "").strip(),
+                "modified_before": form.get("before", "").strip()}  # fmt: skip
+        if not args["query"].strip():
+            return [], "Type something to search for.", ""
+        fut = None
+        try:
+            fut = self._submit(self._core.tool_search, args)
+            out = fut.result(SEARCH_TIMEOUT_S)
+        except ToolError as e:
+            return [], str(e), ""
+        except TimeoutError:
+            if fut is not None:
+                fut.cancel()  # not run later if it has not started (review 26)
+            return [], "The search took too long; try again in a moment.", ""
+        except Exception as e:  # noqa: BLE001 - shown on the page, never a traceback
+            return [], f"the search did not work ({type(e).__name__})", ""
+        notes = [out["note"]] if out.get("note") else []
+        if self.open_only:
+            notes.append("inside Claude Code: open files only")
+        return out["results"], "", "; ".join(notes)
+
+    def locate(self, result_id: str, path: str) -> str | None:
+        """The file of a search result, if today's config still shows it. The path is
+        checked too: the same text at the same place in two folders has one result id
+        (review 26)."""
+        fut = None
+        try:
+            fut = self._submit(self._core.find_chunk, result_id[:40], path[:4096])
+            hit = fut.result(SEARCH_TIMEOUT_S)
+        except Exception:  # noqa: BLE001 - no such result, a timeout, a closed index
+            if fut is not None:
+                fut.cancel()
+            return None
+        return str(hit.path) if hit is not None else None
+
+    def still(self, paths: list[str]) -> set[str]:
+        """Those of `paths` today's config still shows (none if that cannot be checked)."""
+        try:
+            fut = self._submit(lambda: {p for p in paths if self._core._still_visible(p)})
+            return set(fut.result(SEARCH_TIMEOUT_S))
+        except Exception:  # noqa: BLE001 - shown as no results, never as an error page
+            return set()
+
+    def _submit(self, fn: Any, *args: Any) -> Any:
+        with self._lock:
+            self._pending = {f for f in self._pending if not f.done()}
+            fut = self._pool.submit(fn, *args)
+            self._pending.add(fut)
+        return fut
+
+    def close(self) -> None:
+        with self._lock:
+            for fut in self._pending:
+                fut.cancel()  # queued searches never start
+        self._pool.submit(self._core.close)
+        self._pool.shutdown(wait=False)
+
+
+def _gather(c: Control) -> dict[str, Any]:
+    """Everything the page shows, read through the control API; a read error is shown, not
+    raised."""
+    out: dict[str, Any] = {"config": str(c.config_path), "status": {}, "features": [],
+                           "roots": (), "skipped": [], "notes": [], "error": None}  # fmt: skip
+    try:
+        out["status"] = c.status()
+        out["features"] = c.features()
+        out["roots"] = c.roots()
+        out["skipped"] = c.skipped()
+        out["notes"] = c.notes()
+    except (ControlError, ValueError, OSError) as e:
+        out["error"] = _message(e)
+    return out
+
+
+class _HTTPServer(http.server.ThreadingHTTPServer):
+    daemon_threads = True
+    request_queue_size = 64
+
+    def handle_error(self, request: Any, client_address: Any) -> None:
+        pass  # never print tracebacks (they could carry paths or config text)
+
+
+class Server:
+    """A running settings page. `url` opens it once; `wait()` returns when it has exited."""
+
+    def __init__(self, control: Control, idle_s: float = IDLE_S):
+        self.state = State(control)
+        handler = type("BoundHandler", (Handler,), {"state": self.state})
+        self.httpd = _HTTPServer(("127.0.0.1", 0), handler)
+        self.state.port = self.httpd.server_address[1]
+        self.idle_s = idle_s
+        self._stopped = threading.Event()
+        self._link_dir: str | None = None
+
+    @property
+    def url(self) -> str:
+        return f"http://127.0.0.1:{self.state.port}{self.state.prefix}start?t={self.state.token}"
+
+    def link_file(self) -> Path:
+        """A private file that forwards the browser to the one-time link, so the link never
+        appears on a command line (`ps`) when the browser is started."""
+        self._link_dir = tempfile.mkdtemp(prefix="lanternkb-ui-")  # mode 700
+        path = Path(self._link_dir) / "open.html"
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "w") as f:
+            f.write('<!doctype html><meta charset="utf-8"><meta name="referrer" '
+                    f'content="no-referrer"><meta http-equiv="refresh" content="0; url='
+                    f'{escape(self.url, quote=True)}"><title>lanternkb</title>')  # fmt: skip
+        return path
+
+    def _watch(self) -> None:
+        s = self.state
+        while not self._stopped.wait(0.5):
+            now = time.monotonic()
+            with s.lock:
+                for pid, beat in list(s.pages.items()):
+                    if now - beat > BEAT_GRACE_S:
+                        del s.pages[pid]
+                lapsed = s.seen_page and not s.pages and s.bye_at is None  # beats stopped
+                said_bye = s.bye_at is not None and now - s.bye_at > BYE_GRACE_S
+            idle = now - s.last_action > self.idle_s
+            if s.token_used and self._link_dir:
+                shutil.rmtree(self._link_dir, ignore_errors=True)
+                self._link_dir = None
+            if (idle or said_bye or lapsed) and not s.sync.get("running"):
+                self.stop()
+
+    def start(self) -> None:
+        threading.Thread(target=self.httpd.serve_forever, daemon=True).start()
+        threading.Thread(target=self._watch, daemon=True).start()
+
+    def stop(self) -> None:
+        if not self._stopped.is_set():
+            self._stopped.set()
+            threading.Thread(target=self.httpd.shutdown, daemon=True).start()
+
+    def wait(self) -> None:
+        self._stopped.wait()
+        self.httpd.server_close()
+        if self.state.searcher is not None:
+            self.state.searcher.close()
+        if self._link_dir:
+            shutil.rmtree(self._link_dir, ignore_errors=True)
+
+
+def run(config_path: Path, open_browser: bool = True, idle_s: float = IDLE_S) -> int:
+    """`lanternkb ui`: serve the page until it is closed, then exit."""
+    # lanternkb's warnings (exception names only) stay off the terminal: no handler there
+    logging.getLogger("lanternkb").addHandler(logging.NullHandler())
+    server = Server(Control(config_path), idle_s=idle_s)
+    server.start()
+    print(f"Settings page (this link works once): {server.url}", flush=True)
+    print("It closes with the tab, or after 10 idle minutes.", flush=True)
+    if open_browser:
+        webbrowser.open(server.link_file().as_uri())
+    try:
+        server.wait()
+    except KeyboardInterrupt:
+        server.stop()
+    return 0

lanternkb_ui-0.1.0/src/lanternkb_ui/page.py

@@ -0,0 +1,418 @@
+"""HTML for the settings page, generated from feature manifests (no per-feature UI code).
+
+Every value that comes from the index, the config or a manifest is escaped: file names,
+reasons and third-party manifest text are untrusted. The only script is inline, carries
+the response's CSP nonce, and does five things: a heartbeat, a goodbye when the tab
+closes, sync progress, a search's progress, and showing a result's file without leaving
+the page.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections import defaultdict
+from html import escape
+from typing import Any
+from urllib.parse import quote
+
+from lanternkb.plugins import trust_note
+
+CSS = """
+:root { color-scheme: light dark; --bg:#fbfaf7; --card:#fff; --ink:#1d1d1f; --mute:#6e6e73;
+  --line:#e5e3dd; --accent:#b4651e; --ok:#2e7d32; --err:#b3261e; --chip:#f1efe9; }
+@media (prefers-color-scheme: dark) { :root { --bg:#151514; --card:#1f1f1d; --ink:#ecebe7;
+  --mute:#a1a09b; --line:#33322f; --accent:#e39a50; --ok:#7bc47f; --err:#f28b82;
+  --chip:#2a2927; } }
+* { box-sizing: border-box; }
+body { margin:0; font:15px/1.5 -apple-system, system-ui, sans-serif; background:var(--bg);
+  color:var(--ink); }
+main { max-width: 980px; margin: 0 auto; padding: 24px 16px 64px; }
+h1 { font-size: 22px; margin: 0 0 4px; } h2 { font-size: 17px; margin: 28px 0 10px; }
+.sub { color: var(--mute); margin: 0 0 16px; font-size: 13px; word-break: break-all; }
+.card { background: var(--card); border: 1px solid var(--line); border-radius: 12px;
+  padding: 14px 16px; margin: 10px 0; }
+.row { display: flex; gap: 12px; align-items: center; flex-wrap: wrap; }
+.grow { flex: 1 1 260px; min-width: 0; }
+.chip { display: inline-block; background: var(--chip); border-radius: 999px;
+  padding: 1px 9px; font-size: 12px; color: var(--mute); margin: 2px 4px 2px 0; }
+.on { color: var(--ok); } .off { color: var(--mute); }
+.chip.warn, small.warn { color: var(--err); }
+.stat { display: inline-block; margin-right: 18px; } .stat b { font-size: 18px; }
+.flash { padding: 10px 14px; border-radius: 10px; margin: 8px 0; }
+.flash.ok { background: color-mix(in srgb, var(--ok) 14%, transparent); }
+.flash.error { background: color-mix(in srgb, var(--err) 16%, transparent); }
+button, select, input[type=text] { font: inherit; border-radius: 8px; border: 1px solid
+  var(--line); background: var(--card); color: var(--ink); padding: 5px 11px; }
+button { cursor: pointer; } button.primary { background: var(--accent); color: #fff;
+  border-color: var(--accent); } button.danger { color: var(--err); }
+form { display: inline; margin: 0; } input[type=text] { width: 100%; }
+table { width: 100%; border-collapse: collapse; font-size: 13px; }
+td, th { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--line);
+  vertical-align: top; word-break: break-all; }
+th { color: var(--mute); font-weight: 600; } small, .mute { color: var(--mute); }
+details summary { cursor: pointer; color: var(--mute); }
+form.search { display: block; } form.search .row { flex-wrap: nowrap; gap: 8px; }
+input[type=search] { font: inherit; border-radius: 8px; border: 1px solid var(--line);
+  background: var(--card); color: var(--ink); padding: 5px 11px; flex: 1 1 auto;
+  min-width: 0; }
+form.search button { flex: none; white-space: nowrap; }
+.filters { display: grid; grid-template-columns: repeat(auto-fill, minmax(118px, 1fr));
+  gap: 8px; margin-top: 10px; max-width: 560px; }
+.filters label { display: flex; flex-direction: column; gap: 2px; font-size: 12px;
+  color: var(--mute); } .filters input[type=text] { font-size: 14px; padding: 4px 9px; }
+p.snippet { margin: 6px 0 0; white-space: pre-wrap; overflow-wrap: anywhere; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden;
+  clip: rect(0 0 0 0); white-space: nowrap; }
+mark { background: color-mix(in srgb, var(--accent) 30%, transparent); color: inherit;
+  border-radius: 3px; padding: 0 1px; } form.reveal button { font-size: 13px;
+  padding: 2px 9px; }
+a { color: var(--accent); } .controls { display: flex; gap: 6px; flex-wrap: wrap;
+  align-items: center; } .card, .grow, small { overflow-wrap: anywhere; }
+"""
+
+SCRIPT = """
+const pageId = crypto.randomUUID();
+const body = () => new URLSearchParams({page: pageId});
+const closed = () => {
+  const b = document.getElementById('closed');
+  if (b) b.hidden = false;
+};
+const beat = () => fetch('beat', {method: 'POST', body: body()})
+  .then(r => { if (!r.ok) closed(); }).catch(closed);
+beat(); setInterval(beat, 10000);
+addEventListener('pagehide', () => navigator.sendBeacon('bye', body()));
+const say = (b, text) => {
+  b.textContent = text;
+  const a = document.getElementById('announce');
+  if (a) a.textContent = (b.getAttribute('aria-label') || '') + ': ' + text;
+};
+document.querySelectorAll('form.reveal').forEach(f => f.addEventListener('submit', e => {
+  e.preventDefault();
+  const b = f.querySelector('button');
+  fetch('reveal', {method: 'POST', body: new URLSearchParams(new FormData(f))})
+    .then(r => { say(b, r.ok ? 'Shown' : 'Not available'); })
+    .catch(() => { say(b, 'Not available'); });
+}));
+const sf = document.querySelector('form.search');
+if (sf) sf.addEventListener('submit', () => {
+  sf.querySelector('button').textContent = 'Searching...';
+});
+const syncing = document.getElementById('syncing');
+if (syncing) {
+  const poll = async () => {
+    try {
+      const s = await (await fetch('sync/status')).json();
+      if (!s.running) { location.reload(); return; }
+      const stages = {checking: 'checking files', reading: 'reading changed files',
+                      embedding: 'embedding passages'};
+      const at = s.stage ? ': ' + stages[s.stage] + ' ' + s.done.toLocaleString() +
+        (s.total ? ' of ' + s.total.toLocaleString() : '') : '';
+      syncing.textContent = 'Sync running for ' +
+        Math.round(Date.now() / 1000 - s.started) + ' s' + (at || '...');
+    } catch (e) {}
+    setTimeout(poll, 1000);
+  };
+  poll();
+}
+"""
+
+
+def _e(value: Any) -> str:
+    return escape(str(value), quote=True)
+
+
+CATEGORY_ORDER = ("documents", "code", "images", "audio", "search", "safety")
+
+
+def _n(count: int, word: str) -> str:
+    return f"{count:,} {word}{'' if count == 1 else 's'}"
+
+
+def _size(n: int) -> str:
+    for unit in ("bytes", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:,.0f} {unit}" if unit == "bytes" else f"{n:,.1f} {unit}"
+        n /= 1024  # type: ignore[assignment]
+    return str(n)
+
+
+def _shell(title: str, body: str, nonce: str = "") -> str:
+    style = f'<style nonce="{_e(nonce)}">{CSS}</style>' if nonce else ""
+    script = f'<script nonce="{_e(nonce)}">{SCRIPT}</script>' if nonce else ""
+    return (f'<!doctype html><html lang="en"><head><meta charset="utf-8">'
+            f'<meta name="viewport" content="width=device-width, initial-scale=1">'
+            f"<title>{_e(title)}</title>{style}</head><body><main>{body}</main>"
+            f"{script}</body></html>")  # fmt: skip
+
+
+def _form(action: str, csrf: str, fields: str, label: str, cls: str = "") -> str:
+    return (f'<form method="post" action="{_e(action.lstrip("/"))}">'
+            f'<input type="hidden" name="csrf" value="{_e(csrf)}">{fields}'
+            f'<button class="{_e(cls)}" type="submit">{_e(label)}</button></form>')  # fmt: skip
+
+
+def _hidden(name: str, value: str) -> str:
+    return f'<input type="hidden" name="{_e(name)}" value="{_e(value)}">'
+
+
+def _tier_select(current: str, what: str = "") -> str:
+    """The tier choice; `what` names the folder or feature for screen readers, which
+    otherwise hear a row of identical "tier" lists."""
+    opts = "".join(f'<option value="{t}"{" selected" if t == current else ""}>{t}</option>'
+                   for t in ("open", "local-only"))  # fmt: skip
+    label = f"tier for {what}" if what else "tier"
+    return f'<select name="tier" aria-label="{_e(label)}">{opts}</select>'
+
+
+def _flash(flash: list[tuple[str, str]]) -> str:
+    closed = ('<div id="closed" class="flash error" role="alert" hidden>This settings page has '
+              "closed. Run <code>lanternkb ui</code> again to reopen it.</div>")  # fmt: skip
+    return closed + "".join(f'<div class="flash {_e(k)}" role="status">{_e(m)}</div>'
+                            for k, m in flash)  # fmt: skip
+
+
+def _search_form(csrf: str, q: str = "", types: str = "", since: str = "",
+                 before: str = "") -> str:  # fmt: skip
+    """The search box. It is sent by POST and answered with a redirect to the results under
+    a random handle (Post/Redirect/Get), so a query never enters the page's address, title,
+    history or saved session (which may sync to a cloud account); autocomplete is off, which
+    also keeps typed text out of the browser's saved form state."""
+
+    def box(name: str, value: str, label: str, hint: str) -> str:
+        return (f'<label>{_e(label)}<input type="text" name="{name}" value="{_e(value)}" '
+                f'placeholder="{_e(hint)}" autocomplete="off" spellcheck="false">'
+                "</label>")  # fmt: skip
+
+    return ('<form method="post" action="search" class="card search" role="search">'
+            f'<input type="hidden" name="csrf" value="{_e(csrf)}"><div class="row">'
+            f'<input type="search" name="q" value="{_e(q)}" required maxlength="2000" '
+            'aria-label="search your files" placeholder="Search your files, or * for the latest" '
+            'autocomplete="off" spellcheck="false">'
+            '<button class="primary" type="submit">Search</button></div>'
+            '<div class="filters">' + box("types", types, "File types", "pdf, md")
+            + box("since", since, "Changed since", "30d")
+            + box("before", before, "Changed before", "2026-06-30") + "</div></form>")  # fmt: skip
+
+
+def _home(path: str) -> str:
+    home = os.path.expanduser("~").rstrip("/")
+    return "~" + path[len(home) :] if home and path.startswith(home + "/") else path
+
+
+def _marked(snippet: str, query: str) -> str:
+    """A snippet, escaped, with the query's words marked where a word starts with them."""
+    from lanternkb.search import match_spans
+
+    text = re.sub(r"\n\s*\n", "\n", snippet.strip())
+    out, k = [], 0
+    for a, b in match_spans(text, query):
+        out += [_e(text[k:a]), f"<mark>{_e(text[a:b])}</mark>"]
+        k = b
+    return "".join(out) + _e(text[k:])
+
+
+def search(nonce: str, csrf: str, flash: list[tuple[str, str]], form: dict[str, str],
+           results: list[dict[str, Any]], error: str, note: str, took_ms: int,
+           reveal: str = "") -> str:  # fmt: skip
+    """Search results. The title never carries the query (browsers keep titles in their
+    history too). `reveal` labels a button that shows a result's file in the file manager."""
+    box = _search_form(csrf, *(form.get(k, "") for k in ("q", "types", "since", "before")))
+    parts = ['<h1>Search</h1><p class="sub"><a href="./">Back to settings</a></p>',
+             _flash(flash), box]  # fmt: skip
+    if error:
+        parts.append(f'<div class="flash error" role="alert">{_e(error)}</div>')
+    else:
+        found = _n(len(results), "result") if results else "No results"
+        parts.append(f'<p class="mute" role="status">{found} in {took_ms} ms'
+                     f"{' · ' + _e(note) if note else ''}</p>")  # fmt: skip
+    for r in results:
+        folder, _, name = r["path"].rpartition("/")
+        label = reveal.replace(" in ", f" {name} in ", 1)  # "Show notes.md in Finder"
+        show = (f'<form method="post" action="reveal" class="reveal">{_hidden("csrf", csrf)}'
+                f'{_hidden("id", r["id"])}{_hidden("path", r["path"])}'
+                f'<button type="submit" aria-label="{_e(label)}">{_e(reveal)}</button></form>'
+                if reveal else "")  # fmt: skip
+        text = _marked(r["snippet"], form.get("q", ""))
+        parts.append(
+            f'<article class="card hit"><div class="row"><b class="grow">{_e(name)}</b>'
+            f'<span class="chip">{_e(r["tier"])}</span>{show}</div>'
+            f'<small>{_e(_home(folder))}/ · {_e(r["location"])}'
+            f'{" · " + _e(r["modified"][:16].replace("T", " ")) if r.get("modified") else ""}'
+            f'</small><p class="snippet">{text}</p></article>')  # fmt: skip
+    parts.append('<p id="announce" class="sr-only" aria-live="polite"></p>')
+    return _shell("lanternkb search", "".join(parts), nonce)
+
+
+def main(nonce: str, csrf: str, flash: list[tuple[str, str]], data: dict[str, Any],
+         sync: dict[str, Any]) -> str:  # fmt: skip
+    st = data["status"]
+    parts = [f"<h1>lanternkb settings</h1><p class=\"sub\">{_e(data['config'])}</p>",
+             _flash(flash), _search_form(csrf)]  # fmt: skip
+    if data.get("error"):
+        parts.append(f'<div class="flash error" role="alert">The index or config could not be '
+                     f"read: {_e(data['error'])}. Run <code>lanternkb doctor</code>."
+                     "</div>")  # fmt: skip
+    # status and sync
+    by_tier = st.get("by_tier", {}) if isinstance(st, dict) else {}
+    stats = "".join(f'<span class="stat"><b>{_e(v)}</b> {_e(k)}</span>'
+                    for k, v in (("files indexed", st.get("indexed", 0)),
+                                 ("open", by_tier.get("open", 0)),
+                                 ("local-only", by_tier.get("local-only", 0)),
+                                 ("chunks", st.get("chunks", 0)),
+                                 ("skipped", sum(st.get("skipped", {}).values())))
+                    )  # fmt: skip
+    emb = st.get("embeddings", {})
+    emb_parts = []
+    for key, info in emb.items() if isinstance(emb, dict) else []:
+        if isinstance(info, dict):
+            done = "complete" if info.get("complete") else f"{info.get('pending', 0):,} pending"
+            emb_parts.append(f"{_e(key)}: {_e(done)}")
+    emb_line = "; ".join(emb_parts)
+    if sync.get("running"):
+        sync_ui = '<span id="syncing" class="mute">Sync running...</span>'
+    else:
+        sync_ui = _form("/sync", csrf, "", "Sync now", "primary")
+        result = sync.get("result")
+        if result and result.get("ok"):
+            sync_ui += (f' <span class="mute">Last: {result["indexed"]} indexed, '
+                        f'{result["unchanged"]} unchanged, {result["removed"]} removed, '
+                        f'{result["errors"]} errors; {result["pending"]} chunks waiting for '
+                        f"embeddings.</span>")  # fmt: skip
+        elif result:
+            sync_ui += f' <span class="flash error">Sync failed: {_e(result.get("error"))}</span>'
+    parts.append(
+        f'<div class="card"><div class="row"><div class="grow">{stats}</div>'
+        f"<div>{sync_ui}</div></div>"
+        f'<small>Last sync: {_e(st.get("last_sync") or "never")}'
+        f"{' · semantic search: ' + emb_line if emb_line else ''}"
+        f"{' · old pages wait in the WAL until the next sync' if st.get('wal_pending') else ''}"
+        f"</small></div>"
+    )  # fmt: skip
+    # features, grouped by category (generated from manifests)
+    groups: dict[str, list[Any]] = defaultdict(list)
+    for f in data["features"]:
+        groups[f.manifest.category].append(f)
+    parts.append("<h2>Features</h2>")
+    order = sorted(groups, key=lambda c: (CATEGORY_ORDER.index(c) if c in CATEGORY_ORDER
+                                          else len(CATEGORY_ORDER), c))  # fmt: skip
+    for category in order:
+        parts.append(f'<h3 class="mute">{_e(category.title())}</h3>')
+        for f in groups[category]:
+            parts.append(_feature_card(f, csrf))
+    # roots
+    parts.append("<h2>Folders</h2>")
+    for r in data["roots"]:
+        path = str(r.path)
+        parts.append(
+            f'<div class="card"><div class="row"><div class="grow"><b>{_e(path)}</b></div>'
+            + _form("/root/tier", csrf, _hidden("path", path) + _tier_select(r.tier.value, path),
+                    "Set tier")
+            + "</div><details><summary>Remove this folder</summary>"
+            + _form("/root/remove", csrf, _hidden("path", path)
+                    + '<label><input type="checkbox" name="confirm" value="yes" required> '
+                      "Delete everything indexed from this folder</label> "
+                    + '<label><input type="checkbox" name="force" value="yes"> even if files '
+                      "become more visible (it sits inside an open folder)</label> ",
+                    "Remove", "danger")
+            + "</details></div>"
+        )  # fmt: skip
+    parts.append(
+        '<div class="card"><div class="row">'
+        + _form("/root/add", csrf,
+                '<span class="grow"><input type="text" name="path" required autocomplete="off" '
+                'placeholder="/full/path/to/a/folder or ~/folder" '
+                'aria-label="folder path"></span> '
+                + _tier_select("local-only", "the new folder") + " ", "Add folder")
+        + '</div><small>New folders are local-only unless you choose open. Open files can '
+          "reach cloud assistants.</small></div>"
+    )  # fmt: skip
+    # skipped files and notes
+    skipped = data["skipped"]
+    rows = "".join(f"<tr><td>{_e(p)}</td><td>{_e(r)}</td></tr>" for p, r in skipped[:300])
+    more = f'<p class="mute">and {len(skipped) - 300} more</p>' if len(skipped) > 300 else ""
+    table = (f'<div class="card"><table><tr><th>File</th><th>Why</th></tr>{rows}</table>'
+             f"{more}</div>")  # fmt: skip
+    parts.append(f"<h2>Skipped files ({len(skipped)})</h2>"
+                 + (table if skipped else '<p class="mute">None.</p>'))  # fmt: skip
+    if data["notes"]:
+        rows = "".join(f"<tr><td>{_e(p)}</td><td>{_e(n)}</td></tr>" for p, n in data["notes"][:300])
+        parts.append(f'<h2>Partly read files</h2><div class="card"><table>{rows}</table></div>')
+    return _shell("lanternkb settings", "".join(parts), nonce)
+
+
+def _feature_card(f: Any, csrf: str) -> str:
+    m = f.manifest
+    caps = "".join(f'<span class="chip">reads {_e(r)}</span>' for r in m.reads)
+    caps += "".join(f'<span class="chip">needs {_e(p)}</span>' for p in m.os_permissions)
+    note = trust_note(m.id)
+    in_process = note is not None and m.kind != "extractor"
+    if in_process:  # its declarations are not enforced: do not show them as if they were
+        caps = '<span class="chip warn">runs with your privileges</span>'
+    else:
+        caps += '<span class="chip">no network</span>'
+    if note:
+        caps += f'<br><small class="{"warn" if in_process else "mute"}">This is {_e(note)}</small>'
+    state = '<b class="on">On</b>' if f.enabled else '<b class="off">Off</b>'
+    pending = "" if f.applied else ' <span class="chip">applies at the next sync</span>'
+    if m.kind == "embedder":  # its data is vectors; their tier is each file's own
+        counts = f"{_n(f.chunks, 'vector')}, {_size(f.bytes)}"
+    elif m.kind == "extractor":
+        counts = (f"{_n(f.files, 'file')}, {_n(f.chunks, 'chunk')}, {_size(f.bytes)}"
+                  + (f", {f.skipped:,} skipped" if f.skipped else ""))  # fmt: skip
+    else:
+        counts = ""
+    if m.required:
+        controls = '<span class="chip">required</span>'
+    elif m.kind == "embedder":
+        action = "/feature/disable" if f.enabled else "/feature/enable"
+        label = "Turn off" if f.enabled else "Turn on"
+        toggle = _form(action, csrf, _hidden("feature", m.id), label)
+        controls = f'{toggle} <a href="purge?feature={quote(m.id, safe="")}">Delete vectors...</a>'
+    else:
+        action = "/feature/disable" if f.enabled else "/feature/enable"
+        label = "Turn off" if f.enabled else "Turn on"
+        toggle = _form(action, csrf, _hidden("feature", m.id), label)
+        tier = _form("/feature/tier", csrf,
+                     _hidden("feature", m.id) + _tier_select(f.tier.value, m.title),
+                     "Set tier")  # fmt: skip
+        purge = f'<a href="purge?feature={quote(m.id, safe="")}">Purge data...</a>'
+        controls = f"{toggle} {tier} {purge}"
+    return (f'<div class="card"><div class="row"><div class="grow"><b>{_e(m.title)}</b> '
+            f"{state}{pending}<br><small>{_e(m.description)}</small><br>{caps}<br>"
+            f'<small>{_e(counts)}</small></div><div class="controls">{controls}</div></div>'
+            "</div>")  # fmt: skip
+
+
+def purge_preview(nonce: str, csrf: str, flash: list[tuple[str, str]], plan: Any) -> str:
+    if plan.feature.startswith("embedder."):
+        what = (f"<b>{_n(plan.chunks, 'vector')}</b> ({_e(_size(plan.bytes))}) made by this "
+                "embedder. Search uses keywords until a sync embeds again "
+                "(if it is on).")  # fmt: skip
+        body = (f"<h1>Delete the vectors of {_e(plan.feature)}?</h1>{_flash(flash)}"
+                f'<div class="card"><p>This deletes, securely and for good, {what}</p>'
+                + _form("/feature/purge", csrf, _hidden("feature", plan.feature)
+                        + '<label><input type="checkbox" name="confirm" value="yes" required> '
+                          "Yes, delete them</label> ", "Delete", "danger")
+                + ' <a href=".">Cancel</a></div>')  # fmt: skip
+        return _shell(f"Delete vectors of {plan.feature}", body, nonce)
+    body = (f"<h1>Purge {_e(plan.feature)}?</h1>{_flash(flash)}"
+            f'<div class="card"><p>This deletes, securely and for good, everything indexed by '
+            f"this feature: <b>{plan.files:,}</b> files, <b>{plan.skipped:,}</b> skipped-file "
+            f"records, <b>{plan.chunks:,}</b> chunks ({_e(_size(plan.bytes))} of text), and "
+            f"their vectors. The files on disk are not touched; a later sync with the feature "
+            f"on would index them again.</p>"
+            + _form("/feature/purge", csrf, _hidden("feature", plan.feature)
+                    + '<label><input type="checkbox" name="confirm" value="yes" required> '
+                      "Yes, delete it</label> ", "Purge", "danger")
+            + ' <a href=".">Cancel</a></div>')  # fmt: skip
+    return _shell(f"Purge {plan.feature}", body, nonce)
+
+
+def forbidden() -> str:
+    return _shell("Not allowed", "<h1>Not allowed</h1><p>Open the settings page from the link "
+                  "that <code>lanternkb ui</code> printed. Each link works once.</p>")  # fmt: skip
+
+
+def not_found() -> str:
+    return _shell("Not found", "<h1>Not found</h1>")