10 changed files with 33 additions and 1342 deletions
--- a/BEDIENUNGSANLEITUNG.md
+++ b/BEDIENUNGSANLEITUNG.md
@ -1,851 +0,0 @@
 # mdgrep – Bedienungsanleitung
 **mdgrep** ist eine Volltextsuche für Markdown-Dateien und beliebige andere Texte. Sie versteht
 Wortbestandteile, Phrasen, reguläre Ausdrücke und logische Verknüpfungen mit Klammern – und lässt
 sich auf vier Arten nutzen:
 | Baustein | Wofür |
 |---|---|
 | **Kommandozeile** `mdgrep` | schnell im Terminal suchen, wie `grep` – aber blockweise und mit UND/ODER/NICHT |
 | **Python-Bibliothek** | Suche in eigene Programme einbauen, auch für Nicht-Markdown-Daten |
 | **Web-API** (Flask) | JSON-Suchschnittstelle für Webseiten und andere Dienste |
 | **Such-Widget** (JavaScript) | fertige Suchmaske mit Live-Ergebnissen für jede Webseite |
 Version: 0.1.2 · Lizenz: MIT · Repository: https://kitux.de/forgejo/dschlueter/mdgrep
 ---
 ## Inhaltsverzeichnis
 1. [Installation](#1-installation)
 2. [Suchsyntax](#2-suchsyntax)
 3. [Kommandozeile](#3-kommandozeile)
 4. [Python-Bibliothek](#4-python-bibliothek)
 5. [Web-API](#5-web-api)
 6. [Such-Widget](#6-such-widget)
 7. [Betrieb auf einem Server](#7-betrieb-auf-einem-server)
 8. [Voraussetzungen an die Dokumente](#8-voraussetzungen-an-die-dokumente)
 9. [Rezepte](#9-rezepte)
 10. [Fehlermeldungen](#10-fehlermeldungen)
 11. [Fehlersuche](#11-fehlersuche)
 12. [Entwicklung & neue Versionen](#12-entwicklung--neue-versionen)
 ---
 ## 1. Installation
 Voraussetzung: Python 3.10 oder neuer, `git` (für die Installation aus dem Repository).
 ```bash
 # nur Bibliothek + Kommandozeile
 pip install "mdgrep @ git+https://kitux.de/forgejo/dschlueter/mdgrep.git@v0.1.2"
 # zusätzlich Web-API (installiert Flask)
 pip install "mdgrep[web] @ git+https://kitux.de/forgejo/dschlueter/mdgrep.git@v0.1.2"
 ```
 In einer `requirements.txt`:
 ```
 mdgrep[web] @ git+https://kitux.de/forgejo/dschlueter/mdgrep.git@v0.1.2
 ```
 Prüfen:
 ```bash
 mdgrep --version            # mdgrep 0.1.2
 python -c "import mdgrep; print(mdgrep.__version__)"
 ```
 > **Hinweis:** mdgrep ist nicht auf PyPI veröffentlicht. Immer mit Git-URL und Versions-Tag
 > installieren – ein bloßes `pip install mdgrep` findet das Paket nicht (oder, falls jemand den
 > Namen dort später belegt, ein fremdes).
 ---
 ## 2. Suchsyntax
 Groß- und Kleinschreibung spielen **nie** eine Rolle (auch nicht bei Umlauten).
 | Eingabe | Bedeutung | Beispiel findet … |
 |---|---|---|
 | `rust` | Wortbestandteil | „Rust", „Rustacean", „trusted" |
 | `"open source"` | genaue Phrase; beliebiger Leerraum (auch Zeilenumbruch) zwischen den Wörtern | „Open Source", „open<br>source" |
 | `/llms?\b/` | regulärer Ausdruck | „LLM", „LLMs" |
 | `a b` · `a AND b` · `a UND b` · `a & b` · `a && b` | beide Begriffe | |
 | `a OR b` · `a ODER b` · `a \| b` · `a \|\| b` | mindestens einer | |
 | `NOT a` · `NICHT a` · `-a` · `!a` | Begriff darf nicht vorkommen | |
 | `( … )` | Klammern | |
 **Vorrang:** NICHT bindet stärker als UND, UND stärker als ODER.
 `a OR b AND c` bedeutet also `a OR (b AND c)`. Im Zweifel Klammern setzen.
 **Hinweise:**
 - Operatoren werden nur in **Großbuchstaben** erkannt: `and` ist ein normales Suchwort, `AND` der Operator.
 - Wortbestandteile treffen auch mitten im Wort: `go` findet „**Go**ddard". Für **ganze Wörter**
  einen regulären Ausdruck mit Wortgrenzen verwenden: `/\bgo\b/`.
 - Im regulären Ausdruck einen Schrägstrich als `\/` schreiben: `/tcp\/ip/`.
 - In Phrasen ein Anführungszeichen als `\"` schreiben.
 - Wörter mit Sonderzeichen funktionieren direkt: `AT&T`, `TCP/IP`, `e-mail`
  (ein `-` oder `&` *innerhalb* eines Wortes ist kein Operator).
 **Beispiele:**
 ```text
 (rust ODER go) UND NICHT crypto
 "machine learning" -/pytorch|tensorflow/
 llm (datenschutz OR privacy)
 /\bgpt-\d+\b/ NICHT "open source"
 ```
 **Grenzen (Standard):** höchstens 500 Zeichen und 50 Suchbegriffe pro Anfrage
 (die Web-API begrenzt zusätzlich auf 300 Zeichen).
 ---
 ## 3. Kommandozeile
 ```bash
 mdgrep SUCHANFRAGE [PFAD ...] [Optionen]
 ```
 Ohne Pfad wird das aktuelle Verzeichnis durchsucht. Verzeichnisse werden rekursiv nach `*.md`
 durchsucht. Die Suchanfrage immer in **einfache Anführungszeichen** setzen, damit die Shell
 Klammern, `!`, `|` und `&` nicht selbst auswertet.
 ### 3.1 Beispiele
 ```bash
 mdgrep '(rust OR go) AND NOT crypto' notizen/          # alle *.md unter notizen/
 mdgrep '/\bllms?\b/' docs/*.md --split list           # ein Treffer pro Listenpunkt
 mdgrep 'todo' . -l                                     # nur Dateinamen
 mdgrep 'release' . -c                                  # nur Anzahl der Treffer
 mdgrep '"open source"' . --json > treffer.json         # JSON für andere Programme
 mdgrep 'fehler' logs/ -g '*.txt'                       # andere Dateien als Markdown
 mdgrep 'rust' . -m 5                                   # nach 5 Treffern aufhören
 ```
 Ausgabe (Fundstellen farbig, wenn die Ausgabe ein Terminal ist):
 ```text
 notizen/sprachen.md:5
    Rust guarantees memory safety without a garbage collector. Its borrow checker
    rejects data races at compile time.
 ```
 ### 3.2 Optionen
 | Option | Bedeutung | Standard |
 |---|---|---|
 | `-s`, `--split MODUS` | Einheit, die durchsucht und angezeigt wird (siehe 3.3) | `paragraph` |
 | `-g`, `--glob MUSTER` | Dateimuster in Verzeichnissen | `*.md` |
 | `-c`, `--count` | nur Anzahl der Treffer-Blöcke ausgeben | |
 | `-l`, `--files-with-matches` | nur Dateinamen ausgeben | |
 | `-j`, `--json` | JSON-Ausgabe (gleiches Format wie die Web-API) | |
 | `-C`, `--context N` | Zeichen Kontext um Treffer bei langen Blöcken | `80` |
 | `--max-chars N` | Blöcke über N Zeichen kürzen (`0` = nie) | `400` |
 | `-m`, `--max-count N` | nach N Treffern aufhören (`0` = alle) | `0` |
 | `--timeout SEK` | Zeitlimit für die ganze Suche | `30` |
 | `--color auto\|always\|never` | Farbe (`NO_COLOR` wird beachtet) | `auto` |
 | `-V`, `--version` | Version anzeigen | |
 ### 3.3 Split-Modi – was ist ein Treffer?
 | Modus | Ein Block ist … | Geeignet für |
 |---|---|---|
 | `paragraph` | ein durch Leerzeilen getrennter Absatz | Fließtext, Notizen |
 | `list` | ein Listenpunkt der obersten Ebene (mit eingerückten Unterpunkten); Text außerhalb von Listen wird zu Absätzen | Aufzählungen, Berichte, Changelogs |
 | `heading` | ein Abschnitt von Überschrift zu Überschrift | Dokumentation, Wikis |
 | `file` | eine ganze Datei | „In welchen Dateien kommt X und Y vor?" |
 Die logische Verknüpfung gilt **pro Block**: `rust AND go` findet nur Blöcke, in denen beide
 Wörter vorkommen. Mit `--split file` gilt sie für die ganze Datei.
 ### 3.4 Rückgabewerte (für Skripte)
 | Code | Bedeutung |
 |---|---|
 | `0` | Treffer gefunden |
 | `1` | kein Treffer |
 | `2` | Fehler: Syntaxfehler (mit Markierung der Position), Datei nicht lesbar oder Zeitlimit erreicht |
 ```bash
 if mdgrep 'TODO OR FIXME' src/ -c > /dev/null; then echo "Es gibt noch offene Punkte"; fi
 ```
 ---
 ## 4. Python-Bibliothek
 ### 4.1 Nur die Suchsprache
 ```python
 from mdgrep import compile_query, QuerySyntaxError
 q = compile_query('(rust OR go) AND NOT /crypto(currency)?/')
 q.matches("Rust 2.0 is out")        # True
 q.spans("Rust and Go")              # [(0, 4), (9, 11)]  → Positionen zum Hervorheben
 try:
    compile_query("(rust OR go")
 except QuerySyntaxError as e:
    print(e.code, e.position, e.message)   # unclosed_paren 0 Missing closing parenthesis
 ```
 - `compile_query(text, max_length=500, max_terms=50)` → `Query`
 - `Query.matches(text, timeout=None)` → `bool`
 - `Query.spans(text, timeout=None)` → Liste von `(start, ende)`, sortiert und zusammengefasst;
  Begriffe unter NICHT werden nicht markiert
 - Bei Überschreitung von `timeout` (Sekunden) wird `QueryTimeout` ausgelöst
 ### 4.2 Markdown-Dateien durchsuchen
 ```python
 from mdgrep import load_markdown, SearchEngine
 blocks = load_markdown("docs/", split="list", relative_to="docs/")
 engine = SearchEngine(blocks)
 result = engine.search("rust -crypto", limit=20)
 print(result.total_blocks, "Treffer")
 for group in result.groups:
    b = group.block
    print(f"{b.source}:{b.line}", "".join(s["t"] for s in group.segments))
 ```
 `load_markdown(pfade, ...)`:
 | Parameter | Bedeutung | Standard |
 |---|---|---|
 | `paths` | Datei, Verzeichnis oder Liste davon | |
 | `split` | `file` · `heading` · `list` · `paragraph` | `paragraph` |
 | `meta` | Funktion `pfad → dict`; wird in die Metadaten jedes Blocks der Datei übernommen | |
 | `relative_to` | Verzeichnis, relativ zu dem `source`/`id` angegeben werden (wichtig für Web: keine Serverpfade preisgeben) | absolute/angegebene Pfade |
 | `pattern` | Dateimuster in Verzeichnissen | `*.md` |
 | `dialect` | `commonmark` oder `python-markdown` (siehe 4.6) | `commonmark` |
 | `encoding` | Zeichenkodierung | `utf-8` |
 Jeder Block bekommt in `meta` automatisch: `section` (nächste Überschrift darüber),
 `kind` (`file`/`section`/`item`/`paragraph`) und `markdown` (Original-Quelltext).
 Durchsucht wird der Text **ohne** Markdown-Zeichen (Links, Fett, Code …).
 ### 4.3 Eigene Daten durchsuchen
 mdgrep ist nicht auf Markdown beschränkt. Jede Datenquelle lässt sich als Liste von `Block`-Objekten
 übergeben:
 ```python
 from mdgrep import Block, SearchEngine
 tickets = [
    Block(id="42", title="Ticket 42", text="Login schlägt mit SSO fehl", meta={"status": "offen"}),
    Block(id="43", title="Ticket 43", text="Dunkelmodus-Schalter defekt", meta={"status": "erledigt"}),
 ]
 engine = SearchEngine(tickets)
 engine.search("login ODER sso", filters={"status": "offen"})
 ```
 | Feld | Bedeutung |
 |---|---|
 | `id` | eindeutige Kennung |
 | `title` | wird durchsucht und als Überschrift angezeigt (nicht im `text` wiederholen) |
 | `text` | wird durchsucht und als Ausschnitt angezeigt |
 | `anchor` | optionale Sprungmarke (`#anchor`), Linkziel im Widget, wenn kein `href` gesetzt ist |
 | `source`, `line` | Herkunft (Datei, Zeile ab 1) |
 | `meta` | beliebiges Wörterbuch; wird unverändert durchgereicht, Filter arbeiten darauf |
 ### 4.4 Suchoptionen
 ```python
 result = engine.search(
    "rust",
    filters={"lang": ["de", "en"]},            # alle Schlüssel müssen passen; leere Werte = egal
    predicate=lambda b: b.line > 1,             # zusätzlicher eigener Filter
    group_by=lambda b: b.meta.get("url"),       # gleiche Schlüssel → ein Ergebnis, Rest in group.also
    sort_key=lambda b: b.meta["date"], reverse=True,   # neueste zuerst
    offset=0, limit=30,                         # Seiten (zählt Gruppen)
    time_budget=1.5,                            # Sekunden; danach Teilergebnis mit truncated=True
    snippet_chars=700, context=120,             # lange Texte auf Fenster um die Treffer kürzen
 )
 ```
 Das Ergebnis (`SearchResult`):
 | Attribut | Bedeutung |
 |---|---|
 | `groups` | Treffer der aktuellen Seite; je Gruppe `block`, `segments`, `title_segments`, `hits`, `also` |
 | `total_groups`, `total_blocks` | Anzahl Ergebnisse bzw. Fundstellen insgesamt |
 | `next_offset` | `offset` der nächsten Seite oder `None` |
 | `truncated` | `True`, wenn das Zeitbudget aufgebraucht wurde |
 | `elapsed_ms` | Suchdauer |
 | `to_dict()` | JSON-fähiges Wörterbuch (Format siehe 5.3) |
 `segments` ist eine Liste `[{"t": "Text", "hit": False}, {"t": "Treffer", "hit": True}, …]` –
 fertig zum Anzeigen mit Hervorhebung.
 ### 4.5 Automatisch neu laden
 Ändern sich die Dateien, lädt die Suchmaschine sie selbst neu – ohne Neustart:
 ```python
 from pathlib import Path
 def stand(verzeichnis=Path("docs")):
    dateien = [p.stat() for p in verzeichnis.rglob("*.md")]
    return len(dateien), max((s.st_mtime for s in dateien), default=0)
 engine = SearchEngine(lambda: load_markdown("docs", relative_to="docs"),
                      reload_check=stand, reload_interval=60)
 ```
 `reload_check` liefert einen beliebigen vergleichbaren Wert; ändert er sich, wird neu geladen.
 Geprüft wird höchstens alle `reload_interval` Sekunden. `engine.reload()` lädt sofort neu.
 ### 4.6 Markdown-Dialekt – wenn Treffer auf HTML-Elemente verlinken
 Wer Treffer mit Sprungmarken in gerenderten HTML-Seiten verknüpft, braucht dieselbe Aufteilung wie
 der Markdown-Renderer. Die Renderer unterscheiden sich bei Listen:
 | | `commonmark` (Standard) | `python-markdown` |
 |---|---|---|
 | Liste direkt unter einer Absatzzeile (ohne Leerzeile) | beginnt eine Liste | gehört zum Absatz |
 | Unterpunkt mit 1–3 Leerzeichen Einrückung | verschachtelt | eigener Punkt auf oberster Ebene |
 ```python
 split_markdown(text, split="list", dialect="python-markdown")
 ```
 ### 4.7 Weitere Funktionen
 | Funktion | Zweck |
 |---|---|
 | `split_markdown(text, source=…, split=…, meta=…, dialect=…)` | einen Markdown-Text (statt Dateien) zerlegen |
 | `markdown_to_text(md)` | Markdown-Zeichen entfernen, Zeilen erhalten |
 | `segments(text, spans, max_chars=…, context=…)` | Text + Fundstellen → Anzeige-Segmente |
 | `export_static(zielverzeichnis)` | Widget-Dateien (JS + CSS) kopieren, siehe 6.4 |
 ---
 ## 5. Web-API
 Benötigt `mdgrep[web]`.
 ### 5.1 Eigenständige App
 ```python
 # app.py
 from mdgrep import SearchEngine, load_markdown
 from mdgrep.web import create_app
 engine = SearchEngine(lambda: load_markdown("docs", split="list", relative_to="docs"))
 app = create_app(engine, filters=["kind"])       # GET /search?q=…&kind=…
 ```
 ### 5.2 In eine bestehende Flask-App einhängen
 ```python
 from mdgrep.web import create_blueprint
 app.register_blueprint(create_blueprint(engine, filters=["lang"]), url_prefix="/api")
 # → GET /api/search?q=…   und Widget-Dateien unter /api/mdgrep-static/
 ```
 Optionen von `create_blueprint()` (zusätzlich zu `group_by`, `sort_key`, `reverse`,
 `time_budget`, `snippet_chars`, `context` aus 4.4):
 | Option | Bedeutung | Standard |
 |---|---|---|
 | `filters` | Metadaten-Schlüssel, die als URL-Parameter filterbar sind | keine |
 | `default_limit` / `max_limit` | Ergebnisse pro Seite / Obergrenze | `30` / `100` |
 | `max_query_length` | maximale Länge der Suchanfrage | `300` |
 | `hide_meta` | Metadaten-Schlüssel, die nicht ausgeliefert werden | `("markdown",)` |
 | `name` | Blueprint-Name (bei mehreren Suchen in einer App) | `mdgrep` |
 `create_app(engine, url_prefix="", static_dir=None, **optionen)` – mit `static_dir` liefert die App
 zusätzlich die Dateien dieses Verzeichnisses unter `/` aus (praktisch zum Testen einer statischen Seite).
 ### 5.3 Anfragen und Antworten
 ```text
 GET /search?q=rust%20-crypto&lang=de&offset=0&limit=30
 ```
 - `q` – Suchanfrage (leer → leeres Ergebnis)
 - je Name in `filters` ein Parameter: leer oder `all` = keine Einschränkung, `de,en` = mehrere Werte
 - `offset`, `limit` – Seiten
 Antwort (HTTP 200):
 ```json
 {
  "query": "rust -crypto", "total_groups": 12, "total_blocks": 15,
  "offset": 0, "limit": 30, "next_offset": null, "truncated": false, "elapsed_ms": 3.2,
  "results": [{
    "block": {
      "id": "a.md:4", "title": "…", "anchor": "", "source": "a.md", "line": 4, "meta": {},
      "title_segments": [{"t": "…", "hit": false}],
      "segments": [{"t": "The ", "hit": false}, {"t": "Rust", "hit": true}, {"t": " team …", "hit": false}],
      "hits": 1
    },
    "also": [{"id": "b.md:9", "title": "…", "anchor": "", "source": "b.md", "line": 9, "meta": {}}]
  }]
 }
 ```
 Fehler (HTTP 400):
 ```json
 {"error": {"code": "unclosed_paren", "message": "Missing closing parenthesis", "position": 0}}
 ```
 ### 5.4 Entwicklungsserver
 ```bash
 python -m mdgrep.web --dir docs --split list --static site --port 8000
 # → http://127.0.0.1:8000/          (Dateien aus site/)
 # → http://127.0.0.1:8000/api/search (API)
 ```
 | Option | Bedeutung | Standard |
 |---|---|---|
 | `--dir` | Verzeichnis mit Markdown-Dateien (Pflicht) | |
 | `--split` | Split-Modus | `paragraph` |
 | `--static` | dieses Verzeichnis unter `/` ausliefern; API dann unter `--api-prefix` | |
 | `--api-prefix` | Pfad der API, wenn `--static` gesetzt ist | `/api` |
 | `--filters` | kommagetrennte Metadaten-Schlüssel als Filter, z. B. `kind,section` | |
 | `--host`, `--port` | Adresse | `127.0.0.1`, `8000` |
 Neue oder geänderte Dateien werden im Entwicklungsserver nach spätestens 5 Sekunden übernommen.
 Ein vollständiges Beispiel liegt in `examples/`:
 ```bash
 python -m mdgrep.web --dir examples/docs --split list --static examples/site
 ```
 ---
 ## 6. Such-Widget
 Eine fertige Suchmaske: Ergebnisse erscheinen beim Tippen, veraltete Anfragen werden abgebrochen,
 die Suche steht in der URL (teilbar, Zurück-Taste funktioniert), Filter, „Mehr laden",
 aufklappbare Syntaxhilfe, Fehlermeldungen mit Position, Beschriftung Deutsch oder Englisch.
 Alle Texte werden sicher als Text eingefügt (kein HTML vom Server → kein Cross-Site-Scripting).
 Keine Abhängigkeiten, kein Framework.
 ### 6.1 Einbinden
 ```html
 <link rel="stylesheet" href="/api/mdgrep-static/mdgrep-widget.css">
 <div id="suche"></div>
 <script src="/api/mdgrep-static/mdgrep-widget.js"></script>
 <script>
  MdGrep.mount(document.getElementById('suche'), {
    endpoint: '/api/search',
    labels: 'de',
    filters: [
      { name: 'lang', label: 'Sprache', options: [
        { value: '', label: 'Alle' }, { value: 'de', label: 'Deutsch' }, { value: 'en', label: 'Englisch' } ] },
    ],
    badgeFields: ['lang'],
    dateField: 'date',
  });
 </script>
 ```
 Ganz ohne eigenes JavaScript:
 ```html
 <div data-mdgrep data-endpoint="/api/search" data-labels="de"
     data-filters='[{"name":"kind","label":"Art","options":[{"value":"","label":"Alle"},{"value":"item","label":"Listenpunkte"}]}]'
     data-badge-fields="kind"></div>
 ```
 ### 6.2 Optionen
 | Option | Bedeutung | Standard |
 |---|---|---|
 | `endpoint` | URL der Such-API (relativ oder absolut) | `search` |
 | `labels` | `'de'`, `'en'` oder Objekt mit einzelnen Texten (siehe 6.5) | `'en'` |
 | `filters` | Auswahlfelder `[{name, label, options:[{value,label}], value}]`; `name` = URL-Parameter der API | `[]` |
 | `live` | beim Tippen suchen | `true` |
 | `debounce` | Wartezeit nach dem letzten Tastendruck (ms) | `300` |
 | `minChars` | Mindestlänge der Eingabe | `2` |
 | `limit` | Ergebnisse pro Seite | `30` |
 | `syncUrl` | Suche und Filter in der Seiten-URL halten | `true` |
 | `autofocus` | Eingabefeld beim Laden fokussieren | `true` |
 | `help` | Syntaxhilfe anzeigen | `true` |
 | `hrefField` | Metadaten-Feld mit dem Linkziel | `href` |
 | `href(block)` | eigene Funktion für das Linkziel (hat Vorrang) | |
 | `dateField` | Metadaten-Feld, das als Datum angezeigt wird | |
 | `badgeFields` | Metadaten-Felder, die als Plaketten angezeigt werden | `[]` |
 | `formatBadge(feld, wert, block)` | Text einer Plakette anpassen | |
 | `alsoText(block)` | Linktext in der Liste „auch in …" | Datum bzw. Titel |
 Ohne `href` und ohne `hrefField`-Wert verlinkt ein Treffer auf `#anchor` des Blocks.
 ### 6.3 Steuern per JavaScript
 ```javascript
 var suche = MdGrep.mount(element, optionen);
 suche.setQuery('rust -crypto');       // Suchbegriff setzen und suchen
 suche.search();                       // erneut suchen
 suche.input;                          // das Eingabefeld
 element.addEventListener('mdgrep:results', function (e) {
  console.log(e.detail.total_groups); // vollständige API-Antwort
 });
 ```
 Ist die Seite mit `?q=…` aufgerufen worden, sucht das Widget sofort. So kann ein einfaches
 Formular auf einer anderen Seite zur Suchseite weiterleiten:
 ```html
 <form action="suche.html"><input type="search" name="q"><button>Suchen</button></form>
 ```
 ### 6.4 Statische Webseiten
 Liegt die Seite nicht in Flask, die Widget-Dateien einmalig (oder bei jedem Build) kopieren:
 ```python
 import mdgrep
 mdgrep.export_static("site/static")    # schreibt mdgrep-widget.js und mdgrep-widget.css
 ```
 Die Dateien werden nur neu geschrieben, wenn sich ihr Inhalt geändert hat.
 ### 6.5 Aussehen anpassen
 Farben und Rundungen über CSS-Variablen (an `:root` oder einem umgebenden Element):
 ```css
 :root {
  --mdgrep-text: #1a1d2e;       /* Text */
  --mdgrep-muted: #6b7394;      /* Nebentexte */
  --mdgrep-surface: #ffffff;    /* Kästchen, Eingabefeld */
  --mdgrep-border: #d5d8e3;     /* Rahmen */
  --mdgrep-accent: #4a7cff;     /* Fokus, Hover */
  --mdgrep-mark-bg: #ffe58a;    /* Hervorhebung */
  --mdgrep-mark-text: inherit;
  --mdgrep-error: #c0392b;      /* Fehlermeldungen */
  --mdgrep-radius: 0.5rem;
 }
 ```
 Für einen Dunkelmodus die Variablen auf die eigenen Farbvariablen abbilden, z. B.
 `--mdgrep-surface: var(--meine-flaeche);` – dann folgt das Widget dem Seitenthema automatisch.
 Einzelne Texte überschreiben:
 ```javascript
 labels: { lang: 'de', none: 'Leider nichts gefunden.', more: 'Weitere Treffer' }
 ```
 ---
 ## 7. Betrieb auf einem Server
 Der Flask-Entwicklungsserver ist nur zum Testen gedacht. Für den Dauerbetrieb:
 ### 7.1 Mit gunicorn
 ```bash
 pip install gunicorn
 gunicorn --workers 2 --bind 127.0.0.1:8790 app:app
 ```
 Jeder Worker hält alle Blöcke im Speicher (Richtwert: ca. 90 MB für 15 MB Markdown / 26 000 Blöcke).
 ### 7.2 Als systemd-Dienst
 ```ini
 # /etc/systemd/system/meine-suche.service
 [Unit]
 Description=Volltextsuche (mdgrep)
 After=network.target
 [Service]
 User=meinuser
 WorkingDirectory=/home/meinuser/projekt
 ExecStart=/home/meinuser/projekt/venv/bin/gunicorn --workers 2 --bind 127.0.0.1:8790 app:app
 Restart=on-failure
 NoNewPrivileges=true
 PrivateTmp=true
 [Install]
 WantedBy=multi-user.target
 ```
 ```bash
 sudo systemctl daemon-reload && sudo systemctl enable --now meine-suche
 systemctl status meine-suche
 journalctl -u meine-suche -n 50
 ```
 ### 7.3 Hinter nginx mit Ratenbegrenzung
 ```nginx
 # http-Kontext, z. B. /etc/nginx/conf.d/suche.conf
 limit_req_zone $binary_remote_addr zone=suche:10m rate=5r/s;
 # im server-Block
 location = /api/search {
    limit_req zone=suche burst=20 nodelay;
    limit_req_status 429;
    proxy_pass http://127.0.0.1:8790/search$is_args$args;
    proxy_read_timeout 10s;
 }
 ```
 Das Widget zeigt bei HTTP 429 „Zu viele Anfragen – bitte einen Moment warten."
 ### 7.4 Sicherheit
 - **Bösartige reguläre Ausdrücke** (z. B. `/(a|aa)+$/`) können exponentiell lange rechnen. mdgrep
  begrenzt jede Suche auf `time_budget` (Web-API: 1,5 s) und liefert danach ein Teilergebnis
  mit `truncated: true`.
 - **Ratenbegrenzung** im Reverse-Proxy (7.3) verhindert, dass viele Anfragen den Server auslasten.
 - **Keine Serverpfade** preisgeben: `load_markdown(..., relative_to=…)` verwenden.
 - **Interne Metadaten** mit `hide_meta` aus Antworten entfernen.
 - Das Widget fügt Ergebnisse nur als Text ein – auch Markdown mit eingebettetem HTML ist sicher.
 ### 7.5 Leistung
 Ohne Index werden alle Blöcke bei jeder Suche durchlaufen. Richtwerte für 26 000 Blöcke (15 MB):
 einfache Begriffe und Phrasen 30–70 ms, reguläre Ausdrücke und Verknüpfungen 100–150 ms.
 Für deutlich größere Datenmengen (Hunderte MB) ist ein Index-basiertes Werkzeug besser geeignet.
 ---
 ## 8. Voraussetzungen an die Dokumente
 Welche Bedingungen eine Sammlung (z. B. Markdown-Dateien) erfüllen sollte – getrennt nach
 „sinnvoll durchsuchen" und „Treffer springen direkt an die Fundstelle".
 ### 8.1 Für die Suche
 1. **Textdateien mit bekannter Kodierung** – Standard UTF-8; sonst `encoding=`. Andere Endungen
   als `.md` über `-g '*.txt'` bzw. `pattern=`.
 2. **Größe passend zum Ansatz** – mdgrep arbeitet ohne Index: alle Blöcke liegen im Speicher und
   werden bei jeder Suche durchlaufen. Bis etwa 50 MB Text unproblematisch (Richtwert: 15 MB →
   30–150 ms pro Suche); bei Hunderten MB ist ein Index-basiertes Werkzeug besser.
 3. **Gliederung, die zu einem Split-Modus passt** – die UND/ODER/NICHT-Logik gilt **pro Block**,
   die Blockgröße bestimmt also die Trefferqualität:
   | Aufbau der Dokumente | Split-Modus |
   |---|---|
   | Absätze, durch Leerzeilen getrennt | `paragraph` |
   | Einträge als Listenpunkte (Berichte, Changelogs, Protokolle) | `list` |
   | Abschnitte mit Überschriften (Dokumentation, Wiki) | `heading` |
   | kurze Einzeldokumente | `file` |
   Zu große Blöcke machen `a AND b` beliebig (in einer langen Datei steht fast alles), zu kleine
   verfehlen Begriffe, die in benachbarten Sätzen stehen.
 4. **Ableitbare Metadaten** – für Filter (Sprache, Kategorie), Sortierung (Datum) und Gruppierung
   (gleicher Eintrag in mehreren Dateien) braucht jeder Block Werte in `meta`:
   - am einfachsten über ein **einheitliches Datei- oder Pfad-Schema**
     (z. B. `2026_10_12_bericht_de.md`) und `meta=lambda pfad: {…}`;
   - YAML-Frontmatter wird **nicht** ausgewertet, sondern als Text durchsucht – dafür einen kleinen
     Adapter schreiben, der Frontmatter liest und `Block`-Objekte erzeugt (siehe 4.3);
   - zum Zusammenfassen von Duplikaten (`group_by`) einen **stabilen Schlüssel** pro Eintrag
     (URL, ID).
 5. **Grenzen einplanen**
   - **Keine Wortstammsuche:** „Haus" findet nicht „Häuser" → `/h(au|äu)s/` oder `haus ODER häuser`.
   - **Keine Relevanz-Sortierung:** die Reihenfolge bestimmt `sort_key` (z. B. Datum).
   - Markdown-Zeichen (Links, Fett, Code) werden vor der Suche entfernt; **direkt eingebettetes
     HTML** (`<dl>`) und Tabellen-Striche bleiben als Text stehen.
 ### 8.2 Für Sprungmarken
 Damit ein Treffer direkt an die Fundstelle einer gerenderten Seite springt, müssen **zwei Seiten
 exakt zusammenpassen**: die Blöcke von mdgrep und die IDs im HTML.
 1. **Gerenderte Seiten mit vorhersagbarer URL** – aus jeder Quelldatei muss sich ihr HTML-Pfad
   berechnen lassen (`docs/a/b.md` → `site/a/b.html`). Diesen Pfad mit Sprungmarke in
   `meta["href"]` schreiben (das Widget verlinkt darauf, siehe 6.2).
 2. **Jeder Block hat eine ID, die im HTML existiert** – drei Wege:
   | Weg | Voraussetzung | Bewertung |
   |---|---|---|
   | **Überschriften** (`split="heading"`) | Der Renderer erzeugt Überschriften-IDs mit **demselben** Verfahren wie mdgrep (`slugify`, GitHub-Stil) | wenig Aufwand, aber prüfen: Python-Markdown (`toc`), MkDocs, Hugo und GitHub behandeln Umlaute, Sonderzeichen und doppelte Überschriften unterschiedlich |
   | **Listenpunkte/Absätze** (`split="list"` / `paragraph`) | Eigenes Nachbearbeitungs-Skript nummeriert die HTML-Elemente nach **derselben Reihenfolge-Regel** wie die Blöcke und setzt `block.anchor` entsprechend | mittlerer Aufwand, robust |
   | **Text Fragments** (`seite.html#:~:text=…`) | Aktueller Browser; keine Änderung am HTML. Im Widget über die Option `href(block)` bauen | kein Aufwand, aber unzuverlässig bei mehrdeutigem oder umformatiertem Text |
   > **Bekannte Einschränkung:** `slugify` hängt bei **doppelten** Überschriften kein `-1`, `-2` an
   > (anders als GitHub). Kommen Überschriften mehrfach vor, springen Treffer zur ersten.
 3. **Gleicher Markdown-Dialekt wie der Renderer** – Renderer zerlegen Listen unterschiedlich
   (siehe 4.6). Passt `dialect` nicht, verschiebt sich die Nummerierung und Links zeigen auf falsche
   Absätze.
 4. **Quelle und HTML auf demselben Stand** – nach jeder Änderung einer Quelldatei deren Seite neu
   erzeugen; ändert sich die Zählregel, **alle** Seiten.
 5. **Einmal vollständig prüfen** – für jeden Block muss die Sprungmarke im HTML existieren **und**
   auf ein Element zeigen, das seinen Text enthält. Skizze:
   ```python
   import re
   from bs4 import BeautifulSoup
   def pruefe(blocks, html_von):            # html_von(block) → gerendertes HTML der Seite
       fehler = []
       for b in blocks:
           el = BeautifulSoup(html_von(b), "html.parser").find(id=b.anchor)
           probe = re.sub(r"\s+", " ", (b.title or b.text))[:40].lower()
           if el is None or probe not in re.sub(r"\s+", " ", el.get_text()).lower():
               fehler.append((b.source, b.anchor))
       return fehler
   ```
   Das deckt Formatvarianten älterer Dokumente auf, die man sonst übersieht.
 ### 8.3 Checkliste
 | | Bedingung |
 |---|---|
 | ☐ | Textdateien, bekannte Kodierung, insgesamt höchstens im zweistelligen MB-Bereich |
 | ☐ | Gliederung passt zu einem Split-Modus; Blöcke sind sinnvolle Einheiten |
 | ☐ | Metadaten über einheitliches Datei-Namensschema (oder Adapter) |
 | ☐ | stabiler Schlüssel pro Eintrag, falls Duplikate zusammengefasst werden |
 | ☐ | *Sprungmarken:* HTML-Pfad aus Quellpfad berechenbar |
 | ☐ | *Sprungmarken:* IDs im HTML nach derselben Regel wie die Blöcke, gleicher Dialekt |
 | ☐ | *Sprungmarken:* HTML nach jeder Änderung neu erzeugt; Konsistenz einmal geprüft |
 ---
 ## 9. Rezepte
 **Notizen nach zwei Begriffen im selben Absatz durchsuchen**
 ```bash
 mdgrep 'kubernetes "persistent volume"' ~/notizen
 ```
 **Dateien finden, die A enthalten, aber nicht B**
 ```bash
 mdgrep 'docker -podman' ~/wiki --split file -l
 ```
 **Changelog: alle Einträge zu Sicherheitslücken**
 ```bash
 mdgrep '/\bCVE-\d{4}-\d+\b/ OR security' CHANGELOG.md --split list
 ```
 **Treffer in einem Skript weiterverarbeiten**
 ```bash
 mdgrep 'rust' docs --json | python -c "import json,sys; print([r['block']['source'] for r in json.load(sys.stdin)['results']])"
 ```
 **Suche mit Sprachfilter aus dem Dateinamen** (`bericht_de.md`, `bericht_en.md`)
 ```python
 engine = SearchEngine(load_markdown("berichte", split="list", relative_to="berichte",
                                    meta=lambda p: {"lang": p.stem.rsplit("_", 1)[-1]}))
 engine.search("datenschutz", filters={"lang": "de"})
 ```
 **Gleiche Einträge aus mehreren Dateien zusammenfassen, neueste zuerst**
 ```python
 engine.search("rust", group_by=lambda b: b.meta.get("url"),
              sort_key=lambda b: b.meta["date"], reverse=True)
 ```
 **Praxisbeispiel:** Die Hacker-News-Berichte auf https://jamulix.de/HackerNews/search.html nutzen
 mdgrep mit einem kleinen Adapter (`hnews_search.py` im Projekt *hackernews*): Stories und Insights
 als Blöcke, Sprache/Datum/Linkziel als Metadaten, Gruppierung gleicher Stories, Sprungmarken in den
 HTML-Seiten (`dialect="python-markdown"`).
 ---
 ## 10. Fehlermeldungen
 Ungültige Anfragen liefern einen festen Code (für eigene Übersetzungen), eine Meldung und die
 Position (0-basiert; das Widget zeigt sie 1-basiert an).
 | Code | Bedeutung | Beispiel |
 |---|---|---|
 | `empty_query` | leere Anfrage | `   ` |
 | `empty_phrase` | leere Phrase | `""` |
 | `unterminated_phrase` | schließendes Anführungszeichen fehlt | `"open source` |
 | `unterminated_regex` | schließender Schrägstrich fehlt | `/abc` |
 | `invalid_regex` | regulärer Ausdruck ungültig | `/a(b/` |
 | `missing_operand` | Suchbegriff erwartet | `rust OR` · `AND go` |
 | `unexpected_paren` | schließende Klammer ohne öffnende | `rust)` |
 | `unexpected_token` | Operator an unerwarteter Stelle | |
 | `unclosed_paren` | schließende Klammer fehlt | `(rust OR go` |
 | `empty_group` | leere Klammern | `()` |
 | `too_long` | Anfrage zu lang | |
 | `too_many_terms` | zu viele Suchbegriffe | |
 Auf der Kommandozeile wird die Stelle markiert:
 ```text
 mdgrep: Missing closing parenthesis
  (rust OR go
  ^
 ```
 ---
 ## 11. Fehlersuche
 | Problem | Ursache / Lösung |
 |---|---|
 | `bash: !…: event not found` | Suchanfrage in **einfache** Anführungszeichen setzen: `mdgrep 'rust !crypto'` |
 | `go` findet zu viel | Wortbestandteile treffen auch in „Goddard" – ganze Wörter mit `/\bgo\b/` |
 | `and`/`or` wirken nicht als Operator | Operatoren nur in Großbuchstaben: `AND`, `OR`, `NOT` (oder `UND`, `ODER`, `NICHT`) |
 | Keine Treffer in `.txt`-Dateien | Standardmuster ist `*.md` → `-g '*.txt'` bzw. `pattern="*.txt"` |
 | `ModuleNotFoundError: flask` | Web-Teil braucht `pip install "mdgrep[web] @ git+…"` |
 | Widget zeigt „Die Suche ist fehlgeschlagen" | API nicht erreichbar: `endpoint` prüfen, Browser-Konsole/Netzwerk ansehen |
 | Widget zeigt „Zu viele Anfragen" | Ratenbegrenzung des Proxys greift (HTTP 429) – kurz warten oder `burst` erhöhen |
 | „Zeitlimit erreicht" | sehr aufwendiger regulärer Ausdruck; vereinfachen oder `time_budget` erhöhen |
 | Neue Dateien werden nicht gefunden | `reload_check` gesetzt? Geprüft wird nur alle `reload_interval` Sekunden |
 | Sprungmarken zeigen auf falsche Stellen | gleichen Markdown-`dialect` wie der HTML-Renderer verwenden (4.6) |
 | Widget-Darstellung „verbogen" | Seiten-CSS überschreibt Elemente (z. B. `details`, `ol`, `button`); gezielt unter `.mdgrep …` zurücksetzen |
 ---
 ## 12. Entwicklung & neue Versionen
 ```bash
 git clone https://kitux.de/forgejo/dschlueter/mdgrep.git && cd mdgrep
 python -m venv .venv && .venv/bin/pip install -e ".[dev]"
 .venv/bin/pytest                      # alle Tests
 ```
 Aufbau:
 ```
 src/mdgrep/
 ├── query.py      # Suchsprache: Tokenizer, Parser, Auswertung, Fundstellen
 ├── engine.py     # Block, SearchEngine, SearchResult
 ├── snippets.py   # Anzeige-Segmente, Kürzen um Treffer
 ├── markdown.py   # Markdown → Blöcke, Markdown → Text
 ├── cli.py        # Kommandozeile
 ├── web.py        # Flask-Blueprint/-App, Entwicklungsserver
 └── static/       # mdgrep-widget.js, mdgrep-widget.css
 ```
 Neue Version veröffentlichen:
 1. Version in `pyproject.toml` **und** `src/mdgrep/__init__.py` erhöhen (bei Widget-Änderungen auch im Kopf von `mdgrep-widget.js`)
 2. `CHANGELOG.md`: Abschnitt `[Unreleased]` in die neue Version umbenennen (mit Datum), „Beim Update zu tun"
   ergänzen; bei Änderungen am inneren Aufbau auch `FUNKTIONSWEISE.md` aktualisieren
 3. Tests laufen lassen: `.venv/bin/pytest`
 4. Commit, Tag und Push: `git tag -a v0.1.2 -m "mdgrep 0.1.2" && git push origin main --tags`
 5. In den nutzenden Projekten den Tag in `requirements.txt` anpassen und `pip install -r requirements.txt`
   ausführen; laufende Dienste neu starten.
 Versionsregel: Änderungen an öffentlichen Funktionen, am JSON-Format oder an Widget-Optionen, die
 bestehende Nutzer brechen, nur mit erhöhter Nebenversion (0.**2**.0) und Hinweis im Commit.
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -1,58 +0,0 @@
 # Änderungsprotokoll
 Alle nennenswerten Änderungen an mdgrep. Format nach [Keep a Changelog](https://keepachangelog.com/de/1.1.0/),
 Versionen nach [Semantic Versioning](https://semver.org/lang/de/) (vor 1.0: Nebenversion = möglicher Bruch).
 Jede Version ist als Git-Tag verfügbar:
 `pip install "mdgrep[web] @ git+https://kitux.de/forgejo/dschlueter/mdgrep.git@vX.Y.Z"`
 ## [Unreleased]
 ## [0.1.2] – 2026-10-15
 ### Dokumentation
 - `BEDIENUNGSANLEITUNG.md` (deutsch): Installation, Suchsyntax, Kommandozeile, Python-API, Web-API, Widget,
  Serverbetrieb, Voraussetzungen an die Dokumente, Rezepte, Fehlercodes, Fehlersuche, Release-Ablauf.
 - `FUNKTIONSWEISE.md`: interner Aufbau, Datenfluss und Designentscheidungen.
 - `CHANGELOG.md` (diese Datei).
 ### Beim Update zu tun
 - Nichts; nur Dokumentation, Code unverändert und voll kompatibel zu 0.1.1. Widget-Dateien unverändert
  (Kopfzeile meldet weiterhin v0.1.0).
 ## [0.1.1] – 2026-10-12
 ### Neu
 - `split_markdown()` / `load_markdown()`: Parameter `dialect="commonmark" | "python-markdown"`, damit Listen-Blöcke
  zur HTML-Struktur des verwendeten Renderers passen (Python-Markdown: Liste braucht Leerzeile davor,
  Verschachtelung erst ab 4 Leerzeichen).
 ### Geändert
 - Deutlich schneller: der durchsuchte Text (Titel + Text) wird beim Laden einmal vorberechnet; das
  Regex-Zeitlimit gilt nur noch für `/regex/`-Terme (Wörter und Phrasen laufen linear). Typische Suchen über
  26 000 Blöcke: ca. 30–140 ms statt 250–700 ms.
 ### Beim Update zu tun
 - Nichts; voll kompatibel zu 0.1.0. Widget-Dateien unverändert (Kopfzeile meldet weiterhin v0.1.0).
 ## [0.1.0] – 2026-10-12
 Erstveröffentlichung.
 ### Neu
 - Suchsprache: Wortbestandteile, `"Phrasen"`, `/reguläre Ausdrücke/`, `AND`/`OR`/`NOT` (auch `UND`/`ODER`/
  `NICHT`, `&`, `|`, `-`, `!`) mit Klammern; Groß-/Kleinschreibung egal; Fehler mit festem Code und Position;
  Schutz vor katastrophalen regulären Ausdrücken durch Zeitlimits.
 - `SearchEngine` über Blöcke im Speicher: Filter, eigene Prädikate, Gruppierung, Sortierung, Seiten,
  Zeitbudget, automatisches Neuladen, Ausschnitte mit Hervorhebung.
 - Markdown-Zerleger mit den Modi `file`, `heading`, `list`, `paragraph`; Markdown → Text.
 - Kommandozeile `mdgrep` (grep-artig, JSON-Ausgabe, grep-Rückgabewerte).
 - Flask-Blueprint/-App mit JSON-API und Auslieferung der Widget-Dateien; Entwicklungsserver
  `python -m mdgrep.web`.
 - JavaScript-Such-Widget ohne Framework: Live-Suche, URL-Zustand, Filter, „Mehr laden", Syntaxhilfe,
  deutsch/englisch, Gestaltung über CSS-Variablen; `export_static()` für statische Seiten.
 [Unreleased]: https://kitux.de/forgejo/dschlueter/mdgrep/compare/v0.1.2...main
 [0.1.2]: https://kitux.de/forgejo/dschlueter/mdgrep/compare/v0.1.1...v0.1.2
 [0.1.1]: https://kitux.de/forgejo/dschlueter/mdgrep/compare/v0.1.0...v0.1.1
 [0.1.0]: https://kitux.de/forgejo/dschlueter/mdgrep/src/tag/v0.1.0
--- a/FUNKTIONSWEISE.md
+++ b/FUNKTIONSWEISE.md
@ -1,339 +0,0 @@
 # mdgrep – Funktionsweise
 Dieses Dokument erklärt, **wie mdgrep innen arbeitet und warum es so gebaut ist**. Für die Benutzung siehe
 [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md), für Änderungen je Version [CHANGELOG.md](CHANGELOG.md).
 Stand: Version 0.1.2
 ---
 ## Inhaltsverzeichnis
 1. [Überblick](#1-überblick)
 2. [Module](#2-module)
 3. [Suchsprache: vom Text zum Syntaxbaum](#3-suchsprache-vom-text-zum-syntaxbaum)
 4. [Auswertung und Zeitlimit](#4-auswertung-und-zeitlimit)
 5. [Hervorhebung und Ausschnitte](#5-hervorhebung-und-ausschnitte)
 6. [Markdown-Zerlegung](#6-markdown-zerlegung)
 7. [Suchmaschine](#7-suchmaschine)
 8. [Web-API und Widget](#8-web-api-und-widget)
 9. [Designentscheidungen](#9-designentscheidungen)
 10. [Grenzen und Erweiterungsideen](#10-grenzen-und-erweiterungsideen)
 ---
 ## 1. Überblick
 mdgrep hat **keinen Suchindex**. Alle Texte liegen als *Blöcke* im Speicher; jede Suche prüft jeden Block
 (nach Filtern) gegen die übersetzte Suchanfrage. Das ist einfach, unterstützt beliebige reguläre Ausdrücke
 und ist bei einigen Megabyte Text schnell genug.
 ```mermaid
 flowchart TB
    subgraph Anfrage
        direction TB
        Q["Suchtext<br/>(rust OR go) -crypto"] --> T[Tokenizer]
        T --> P[Parser]
        P --> AST["Syntaxbaum<br/>And / Or / Not / Term"]
    end
    subgraph Daten
        direction TB
        D["Markdown-Dateien<br/>oder eigene Daten"] --> L["load_markdown()<br/>split_markdown()"]
        L --> B["Blöcke<br/>title, text, meta"]
    end
    AST --> E["SearchEngine.search()"]
    B --> E
    E --> F["Filter"]
    F --> M["Treffer prüfen<br/>(mit Zeitbudget)"]
    M --> S["sortieren, gruppieren,<br/>Seite ausschneiden"]
    S --> H["Fundstellen (Spans)<br/>→ Ausschnitte (Segmente)"]
    H --> R["SearchResult<br/>.to_dict()"]
    R --> CLI["mdgrep<br/>(Terminal)"]
    R --> API["Flask<br/>GET /search"]
    API --> W["Widget<br/>(Browser)"]
 ```
 Drei Begriffe tragen das ganze Design:
 | Begriff | Bedeutung |
 |---|---|
 | **Block** | kleinste durchsuchbare Einheit – ein Absatz, Listenpunkt, Abschnitt, eine Datei oder ein eigener Datensatz. Die logische Verknüpfung gilt *pro Block*. |
 | **Span** | Fundstelle als `(start, ende)` im Text eines Blocks |
 | **Segment** | Anzeigestück `{"t": Text, "hit": bool}`; eine Liste von Segmenten ergibt den hervorgehobenen Ausschnitt |
 ---
 ## 2. Module
 | Modul | Aufgabe | Wichtigste Namen |
 |---|---|---|
 | `query.py` | Suchsprache: Tokenizer, Parser, Auswertung, Fundstellen | `compile_query`, `Query`, `QuerySyntaxError`, `QueryTimeout` |
 | `engine.py` | Blöcke halten, filtern, prüfen, sortieren, gruppieren, Seiten | `Block`, `SearchEngine`, `SearchResult`, `Group` |
 | `snippets.py` | Fundstellen → Anzeige-Segmente, Kürzen um Treffer | `segments` |
 | `markdown.py` | Markdown → Blöcke; Markdown → Klartext | `load_markdown`, `split_markdown`, `markdown_to_text`, `slugify` |
 | `cli.py` | Kommandozeile | `main` (Einstieg `mdgrep`) |
 | `web.py` | Flask-Blueprint/-App, Entwicklungsserver | `create_blueprint`, `create_app` |
 | `static/` | Browser-Widget | `mdgrep-widget.js` (`MdGrep.mount`), `mdgrep-widget.css` |
 | `__init__.py` | öffentliche API, `export_static()` | |
 Abhängigkeiten zeigen nur in eine Richtung: `engine` nutzt `query` und `snippets`, `markdown` nutzt
 `engine` (für `Block`), `cli` und `web` nutzen alles. `query` und `snippets` hängen von nichts im Paket ab.
 Nur `web.py` braucht Flask; der Rest kommt mit dem Paket `regex` aus.
 ---
 ## 3. Suchsprache: vom Text zum Syntaxbaum
 ### 3.1 Tokenizer (`_tokenize`)
 Der Suchtext wird Zeichen für Zeichen in Tokens zerlegt:
 | Zeichen am Token-Anfang | Token |
 |---|---|
 | Leerraum | wird übersprungen |
 | `(` `)` | Klammer |
 | `&` / `&&`, `\|` / `\|\|` | `AND` / `OR` |
 | `!` | `NOT` |
 | `-` **gefolgt von Nicht-Leerraum** | `NOT` (ein einzelnes `-` mit Leerzeichen danach ist ein normales Suchwort) |
 | `"` … `"` | Phrase; `\"` steht für ein Anführungszeichen |
 | `/` … `/` | regulärer Ausdruck; `\/` wird zu `/`, andere `\x` bleiben erhalten |
 | sonst | Wort bis zum nächsten Leerraum, `(`, `)` oder `"` |
 Ein Wort, das genau `AND`, `OR`, `NOT`, `UND`, `ODER` oder `NICHT` lautet, wird zum Operator – **nur in
 Großbuchstaben**. Weil `-`, `&`, `|`, `!` und `/` nur *am Token-Anfang* Sonderbedeutung haben, bleiben Wörter
 wie `e-mail`, `AT&T` oder `TCP/IP` normale Suchwörter.
 ### 3.2 Parser (rekursiver Abstieg)
 ```text
 query    := or_expr  EOF
 or_expr  := and_expr ( OR and_expr )*
 and_expr := not_expr ( [AND] not_expr )*      ← AND darf fehlen (Leerzeichen = UND)
 not_expr := NOT not_expr | primary
 primary  := TERM | "(" or_expr ")"
 ```
 Daraus ergibt sich der Vorrang **NOT > AND > OR**. Ein implizites UND wird erkannt, wenn nach einem Ausdruck
 direkt ein Term, eine öffnende Klammer oder ein NOT folgt.
 Fehler werden als `QuerySyntaxError(message, position, code)` gemeldet; `position` zeigt auf das Token (bzw. die
 öffnende Klammer oder das Textende), `code` ist stabil und übersetzbar (Liste in der Bedienungsanleitung).
 Nebenbei merkt sich der Parser für jeden Term, ob er unter einer **ungeraden Anzahl von NOT** steht
 (`negated`). Das braucht später die Hervorhebung: `rust -crypto` markiert nur „rust".
 ### 3.3 Terme werden zu regulären Ausdrücken
 | Term | Muster | Beispiel |
 |---|---|---|
 | Wort | `regex.escape(wort)` | `c++` → `c\+\+` |
 | Phrase | Wörter maskiert, verbunden mit `\s+` | `"open source"` → `open\s+source` (trifft auch über Zeilenumbrüche) |
 | Regex | unverändert | `/llms?\b/` |
 Alle Muster werden mit `IGNORECASE | UNICODE` des PyPI-Moduls **`regex`** kompiliert (Umlaute inklusive).
 Ungültige reguläre Ausdrücke fallen schon hier als `invalid_regex` auf – nicht erst bei der Suche.
 ---
 ## 4. Auswertung und Zeitlimit
 Der Syntaxbaum besteht aus `Term`, `Not`, `And`, `Or`; jeder Knoten hat `evaluate(text, deadline)`.
 `And`/`Or` nutzen `all()`/`any()` und brechen daher früh ab.
 **Zeitlimit:** Bestimmte reguläre Ausdrücke brauchen exponentiell lange („katastrophales Backtracking",
 z. B. `/(a|aa)+$/`). Das Modul `regex` kann jede Suche mit `timeout=` abbrechen. Der Parameter ist aber teuer
 (etwa vierfache Laufzeit pro Aufruf), daher:
 - **Wörter und Phrasen** laufen **ohne** Zeitlimit – maskierte Literale und `\s+` sind linear, können also nicht
  entarten.
 - **Reguläre Ausdrücke** bekommen als Zeitlimit die Restzeit bis zur Frist (`deadline`).
 - `Query.matches()` prüft die Frist **einmal pro Aufruf**; ist sie abgelaufen, folgt `QueryTimeout`.
 Die Suchmaschine setzt eine Frist für die ganze Suche (`time_budget`). Läuft sie ab, endet die Schleife und
 das Ergebnis trägt `truncated = True` – der Server bleibt erreichbar, der Nutzer bekommt ein Teilergebnis.
 ---
 ## 5. Hervorhebung und Ausschnitte
 **Fundstellen (`Query.spans`)**: Für jeden *positiven* Term (nicht unter NOT) werden alle Treffer gesucht,
 Treffer der Länge 0 (z. B. von `/x*/`) verworfen, dann sortiert und überlappende oder angrenzende Bereiche
 zusammengefasst. Aus `open OR source` auf „open source" werden so zwei getrennte Markierungen, aus
 `abc OR bcd` auf „abcd" eine durchgehende.
 **Ausschnitte (`snippets.segments`)**: Ist der Text kürzer als `max_chars`, wird er komplett in Segmente
 zerlegt. Sonst:
 1. Um jede Fundstelle wird ein Fenster von `context` Zeichen gelegt.
 2. Fensterränder werden an Wortgrenzen verschoben (höchstens 20 Zeichen weit), damit keine Wörter zerschnitten
   werden.
 3. Überlappende Fenster verschmelzen.
 4. Fenster werden aufgenommen, solange das Budget `max_chars` reicht – das **erste Fenster immer**, damit
   mindestens ein Treffer sichtbar ist.
 5. Lücken und abgeschnittene Enden werden durch `" … "` markiert.
 Ohne Fundstelle im Text (Treffer nur im Titel) wird der Textanfang gezeigt.
 ---
 ## 6. Markdown-Zerlegung
 `split_markdown()` arbeitet **zeilenbasiert** mit einem kleinen Scanner, nicht mit einem vollständigen
 Markdown-Parser. Der Scanner liefert je Zeile: Index, Inhalt, „in Code-Block?" und ggf. die erkannte
 Überschrift (`#` bis `######`). Zeilen innerhalb von Code-Blöcken (` ``` ` oder `~~~`) werden nie als
 Überschrift oder Listenpunkt gedeutet.
 | Modus | Regel |
 |---|---|
 | `file` | eine Datei = ein Block; Titel = erste Überschrift |
 | `heading` | neuer Block bei jeder Überschrift; Titel = Überschrift, Anker = `slugify(Überschrift)` |
 | `paragraph` | neuer Block nach jeder Leerzeile (außerhalb von Code-Blöcken); Trennlinien werden übersprungen |
 | `list` | neuer Block bei jedem Listenpunkt der obersten Ebene; eingerückte Zeilen und Zeilen direkt darunter („lazy continuation") gehören dazu; Text außerhalb von Listen wird zu Absatz-Blöcken; Trennlinien und Überschriften beenden einen Block |
 **Dialekte** (nur Modus `list`): Markdown-Renderer zerlegen Listen unterschiedlich. Damit Blöcke zu den
 Elementen im gerenderten HTML passen (wichtig für Sprungmarken), gibt es zwei Regelsätze:
 | | `commonmark` | `python-markdown` |
 |---|---|---|
 | Listenmarker | `-` `*` `+` `1.` `1)` am Zeilenanfang | dazu bis zu 3 Leerzeichen Einrückung; nummeriert nur `1.` |
 | Liste direkt unter einer Absatzzeile | beginnt eine Liste | gehört zum Absatz |
 Jeder Block bekommt `meta["section"]` (letzte Überschrift darüber), `meta["kind"]` und `meta["markdown"]`
 (Originaltext), dazu `source`, `line` und `id = "<source>:<line>"`.
 **Markdown → Klartext** (`markdown_to_text`): pro Zeile werden Listen-, Zitat- und Überschriftenmarker entfernt,
 Bilder durch ihren Alternativtext, Links durch ihren Linktext ersetzt, Inline-Code, Fett, Kursiv und
 Durchgestrichen ausgepackt (Unterstriche nur an Wortgrenzen, damit `snake_case` erhalten bleibt). Zeilen
 bleiben erhalten, mehrere Leerzeilen werden zu einer. Durchsucht und angezeigt wird dieser Klartext.
 In den Modi `file` und `heading` wird der Titel vom Textanfang entfernt, damit er im Ergebnis nicht doppelt
 erscheint.
 ---
 ## 7. Suchmaschine
 ### 7.1 Laden
 `SearchEngine(quelle, reload_check=…, reload_interval=…)` nimmt eine Liste von Blöcken oder eine Funktion, die
 sie liefert. Beim Laden wird für jeden Block der **Suchtext** `titel + "\n" + text` einmal vorberechnet –
 Titel und Text werden gemeinsam durchsucht, aber getrennt angezeigt.
 **Neuladen:** Mit Ladefunktion und `reload_check` (liefert einen beliebigen vergleichbaren Wert, etwa
 Dateianzahl und neueste Änderungszeit) prüft die Suchmaschine höchstens alle `reload_interval` Sekunden, ob
 sich der Wert geändert hat, und lädt dann neu. Blöcke und Suchtexte werden zusammen als ein Tupel ersetzt –
 laufende Suchen sehen immer einen konsistenten Stand.
 ### 7.2 Ablauf von `search()`
 ```mermaid
 flowchart TD
    A["Anfrage kompilieren<br/>(oder fertige Query)"] --> B["Frist = jetzt + time_budget"]
    B --> C["ggf. neu laden"]
    C --> D{"für jeden Block"}
    D -->|"Filter / Prädikat passen nicht"| D
    D -->|passt| E{"query.matches()"}
    E -->|ja| F[in Trefferliste]
    E -->|nein| D
    E -->|QueryTimeout| G["truncated = True,<br/>Schleife beenden"]
    F --> D
    D -->|fertig| H["sortieren (sort_key, reverse)"]
    G --> H
    H --> I["gruppieren (group_by)<br/>Reihenfolge = erster Treffer je Gruppe"]
    I --> J["Seite: Gruppen offset … offset+limit"]
    J --> K["nur für die Seite:<br/>Spans + Segmente des ersten Blocks je Gruppe"]
    K --> L[SearchResult]
 ```
 Wichtige Details:
 - **Filter** vergleichen `block.meta[schlüssel]` mit einem Wert oder einer Menge von Werten; leere Werte werden
  ignoriert.
 - **Gruppierung**: `group_by(block)` liefert einen Schlüssel oder `None` (= eigene Gruppe). Weil vorher sortiert
  wird, ist der erste Block einer Gruppe der „beste" (z. B. neueste); die übrigen landen in `also`.
 - **Seiten** zählen Gruppen, nicht Blöcke. `next_offset` ist `None`, wenn keine weitere Seite existiert.
 - **Teure Arbeit nur für die sichtbare Seite**: Fundstellen und Ausschnitte werden nur für die bis zu
  `limit` angezeigten Gruppen berechnet, nicht für alle Treffer.
 ---
 ## 8. Web-API und Widget
 ### 8.1 Web-API (`web.py`)
 `create_blueprint()` registriert `GET /search` und liefert die Widget-Dateien unter `/mdgrep-static/` aus.
 Ablauf einer Anfrage: Parameter lesen und begrenzen (`offset ≥ 0`, `1 ≤ limit ≤ max_limit`, Länge der
 Anfrage) → Filter-Parameter übernehmen (leer/`all` = keine Einschränkung, `a,b` = mehrere Werte) →
 `engine.search()` → interne Metadaten (`hide_meta`, Standard `markdown`) entfernen → JSON.
 `QuerySyntaxError` wird zu HTTP 400 mit `{"error": {code, message, position}}`.
 `create_app()` baut eine eigenständige Flask-App (Unicode im JSON nicht maskiert) und kann zusätzlich ein
 Verzeichnis statisch ausliefern; `send_from_directory` verhindert dabei Zugriffe außerhalb dieses Verzeichnisses.
 ### 8.2 Widget (`static/mdgrep-widget.js`)
 Ein einzelnes Skript ohne Abhängigkeiten, das `window.MdGrep = {mount, labels, version}` bereitstellt.
 ```mermaid
 sequenceDiagram
    participant U as Nutzer
    participant W as Widget
    participant A as API
    U->>W: tippt „rust -cr"
    Note over W: Debounce 300 ms – nichts senden
    U->>W: tippt „ypto"
    W->>W: URL aktualisieren (?q=…)
    W->>A: GET search?q=rust -crypto (AbortController #1)
    U->>W: ändert Filter „Sprache"
    W->>A: Anfrage #1 abbrechen, GET … &lang=de (#2)
    A-->>W: JSON #2
    W->>W: Kästchen per createElement/textContent bauen
    W-->>U: Ergebnisse, Statuszeile
 ```
 - **Zustand in der URL** (`history.replaceState`): Suchbegriff und Filter stehen in `?q=…&lang=…`; beim Laden
  liest das Widget sie wieder ein und sucht sofort. Dadurch sind Suchen teilbar, und die Zurück-Taste aus einem
  geöffneten Treffer stellt die Suche wieder her.
 - **Veraltete Antworten** werden doppelt abgefangen: `AbortController` bricht die alte Anfrage ab, und eine
  Antwort wird nur angezeigt, wenn sie zur zuletzt gestarteten Anfrage gehört.
 - **Sicherheit:** Alle Texte aus der Antwort werden mit `textContent` bzw. als Textknoten eingefügt, `<mark>`
  entsteht per `createElement`. HTML aus Dokumenten wird so nie ausgeführt.
 - **Fehler:** HTTP 400 → übersetzte Meldung zum `code` plus Position; 429 → „zu viele Anfragen"; sonst
  allgemeine Meldung.
 - **Gestaltung:** nur Klassen `mdgrep-*` und CSS-Variablen `--mdgrep-*` mit Standardwerten als Fallback;
  `[hidden]` wird mit `!important` erzwungen, damit Seiten-CSS ausgeblendete Elemente nicht wieder einblendet.
 - **Ohne Skriptcode:** Elemente mit `data-mdgrep` werden beim Laden automatisch eingerichtet.
 ---
 ## 9. Designentscheidungen
 | Entscheidung | Verworfene Alternativen | Grund |
 |---|---|---|
 | **Kein Index – Volltext-Scan im Speicher** | Whoosh, SQLite FTS, Elasticsearch | Reguläre Ausdrücke lassen sich ohnehin nicht über einen Wortindex beantworten; Whoosh ist seit 2016 ungepflegt; bei einigen MB Text ist der Scan schnell genug (≈ 30–150 ms bei 15 MB) und es gibt nichts zu synchronisieren. |
 | **PyPI-`regex` statt `re`** | Standardmodul `re` | Nur `regex` kann eine laufende Suche per `timeout=` abbrechen – Voraussetzung, um Nutzer-Regex auf einem Server zu erlauben. |
 | **Zeitlimit nur für Regex-Terme** | Zeitlimit für alle Terme | Der Timeout-Parameter vervierfacht die Kosten pro Aufruf; Wörter und Phrasen können nicht entarten. Zusammen mit den vorberechneten Suchtexten gemessen 4–9× schnellere Suchen (Version 0.1.1). |
 | **Logik pro Block** | pro Datei, pro Satz | Datei ist zu grob (`a AND b` trifft fast immer), Satz zu fein; der Split-Modus lässt den Nutzer die passende Einheit wählen. |
 | **Titel und Text getrennt** | Titel als erste Textzeile | Sonst erscheint der Titel im Ergebnis doppelt; Programme mit eigenen Daten können einen echten Titel setzen. |
 | **Zeilenbasierter Markdown-Zerleger** | vollständiger Markdown-Parser (z. B. markdown-it) | Für Blockgrenzen genügt ein kleiner Scanner, keine zusätzliche Abhängigkeit; Abweichungen einzelner Renderer deckt die `dialect`-Option ab. |
 | **`dialect`-Option** | eine feste Regel | Sprungmarken funktionieren nur, wenn Blöcke exakt den HTML-Elementen des Renderers entsprechen; CommonMark und Python-Markdown unterscheiden sich bei Listen messbar (im hnews-Archiv zwei Fehlerbilder in 70 bzw. 197 Dateien). |
 | **`relative_to`** | absolute Pfade | Eine Web-API soll keine Serverpfade preisgeben. |
 | **Stabile Fehlercodes** | nur Fehlermeldungstext | Oberflächen können Meldungen übersetzen (Widget: de/en), ohne Texte zu parsen. |
 | **Widget ohne Framework, nur `textContent`** | React/Vue, `innerHTML` | Läuft in jeder Seite, keine Build-Kette, keine XSS-Lücke durch Dokumentinhalte. |
 | **Eigenes Repository, Installation per Git-Tag** | PyPI, Unterordner eines Projekts | Wiederverwendbar in beliebigen Projekten, unabhängig versioniert, ohne Veröffentlichung auf PyPI. |
 | **MIT-Lizenz** | GPL | Einfache Wiederverwendung, auch in fremden Projekten. |
 ---
 ## 10. Grenzen und Erweiterungsideen
 | Grenze | Auswirkung | Mögliche Erweiterung |
 |---|---|---|
 | Linearer Scan | Laufzeit wächst mit der Textmenge; bei Hunderten MB zu langsam | Vorfilter mit Trigramm-Index für Wörter/Phrasen |
 | Jeder Server-Worker hält alle Blöcke | ca. 90 MB pro Worker bei 15 MB Markdown | gemeinsamer Speicher oder Index auf Platte |
 | Keine Wortstämme | „Haus" findet nicht „Häuser" | optionale Stemming-Stufe (z. B. Snowball) |
 | Keine Relevanz-Sortierung | Reihenfolge nur nach `sort_key` | Score aus Trefferzahl/Position |
 | Doppelte Überschriften | `slugify` hängt kein `-1`, `-2` an (anders als GitHub) | Zähler je Datei wie GitHub |
 | Nur ATX-Überschriften (`#`) | Setext-Überschriften (unterstrichen mit `===`/`---`) werden nicht erkannt | Scanner erweitern |
 | Operatoren nur in Großbuchstaben | `and` ist ein Suchwort | bewusst so; ggf. Option |
 | Titel und Text gemeinsam durchsucht | eine Phrase kann theoretisch über die Grenze Titel/Text hinweg treffen | Grenzzeichen statt Zeilenumbruch |
--- a/README.md
+++ b/README.md
@ -9,20 +9,11 @@ Boolean full-text search over Markdown (and any other text) – as a **Python li
 - protection against catastrophic regular expressions (time limit per search)
 - no search index: blocks live in memory, a few MB of text are searched in milliseconds
 ## Documentation
 | Document | Content |
 |---|---|
 | [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md) | User manual (German): installation, syntax, CLI, API, widget, operation, troubleshooting |
 | [FUNKTIONSWEISE.md](FUNKTIONSWEISE.md) | How it works (German): architecture, data flow, design decisions, limits |
 | [CHANGELOG.md](CHANGELOG.md) | Changes per version and what to do when updating |
 | [LICENSE](LICENSE) | MIT |
 ## Installation
 ```bash
-pip install "mdgrep @ git+https://kitux.de/forgejo/dschlueter/mdgrep.git@v0.1.2"        # library + CLI
+pip install "mdgrep @ git+https://kitux.de/forgejo/dschlueter/mdgrep.git@v0.1.0"        # library + CLI
-pip install "mdgrep[web] @ git+https://kitux.de/forgejo/dschlueter/mdgrep.git@v0.1.2"   # + Flask API
+pip install "mdgrep[web] @ git+https://kitux.de/forgejo/dschlueter/mdgrep.git@v0.1.0"   # + Flask API
 ```
 Requires Python ≥ 3.10. Dependencies: [`regex`](https://pypi.org/project/regex/) (and `flask` for `[web]`).
@ -106,10 +97,6 @@ engine.search("login OR sso", filters={"status": "open"})
 `load_markdown()` adds `meta["section"]` (nearest heading), `meta["kind"]`
 (`file`/`section`/`item`/`paragraph`) and `meta["markdown"]` (raw source).
 `dialect` (for `split="list"`) makes blocks line up with the HTML of your Markdown renderer:
 `"commonmark"` (default) or `"python-markdown"` (a list needs a blank line before it; nesting
 needs 4 spaces of indentation). Important if you link results to element ids in rendered HTML.
 ### `SearchEngine(source, *, reload_check=None, reload_interval=60)`
 `source` is a list of blocks or a callable returning them. With a callable plus `reload_check`
--- a/pyproject.toml
+++ b/pyproject.toml
@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "mdgrep"
-version = "0.1.2"
+version = "0.1.0"
 description = "Boolean full-text search (substrings, phrases, regex, AND/OR/NOT, parentheses) over Markdown and other text blocks, with CLI, Flask API and a JavaScript search widget"
 readme = "README.md"
 license = "MIT"
--- a/src/mdgrep/init.py
+++ b/src/mdgrep/init.py
@ -5,7 +5,7 @@ from .markdown import load_markdown, markdown_to_text, split_markdown
 from .query import Query, QuerySyntaxError, QueryTimeout, compile_query
 from .snippets import segments
-__version__ = "0.1.2"
+__version__ = "0.1.0"
 STATIC_FILES = ("mdgrep-widget.js", "mdgrep-widget.css")
--- a/src/mdgrep/engine.py
+++ b/src/mdgrep/engine.py
@ -103,17 +103,12 @@ class SearchEngine:
        self._lock = threading.Lock()
        self._token = reload_check() if reload_check else None
        self._checked_at = time.monotonic()
-        self._set_blocks(list(source() if callable(source) else source))
+        self._blocks: list[Block] = list(source() if callable(source) else source)
    def _set_blocks(self, blocks: list[Block]) -> None:
        # Text that is searched (title + text), precomputed once per load.
        haystacks = [f"{b.title}\n{b.text}" if b.title else b.text for b in blocks]
        self._data = (blocks, haystacks)
    @property
    def blocks(self) -> list[Block]:
        self._maybe_reload()
-        return self._data[0]
+        return self._blocks
    def reload(self) -> None:
        """Reload blocks from the loader (no-op for a static block list)."""
@ -121,7 +116,7 @@ class SearchEngine:
            return
        blocks = list(self._loader())
        with self._lock:
-            self._set_blocks(blocks)
+            self._blocks = blocks
            self._token = self._reload_check() if self._reload_check else None
            self._checked_at = time.monotonic()
@ -165,19 +160,14 @@ class SearchEngine:
        started = time.monotonic()
        q = query if isinstance(query, Query) else compile_query(query)
        deadline = started + time_budget if time_budget else None
-        self._maybe_reload()
+        candidates = self._filter(self.blocks, filters, predicate)
        blocks, haystacks = self._data
        conditions = self._conditions(filters)
        matched: list[Block] = []
        truncated = False
-        for i, block in enumerate(blocks):
+        for block in candidates:
            if conditions and any(block.meta.get(k) not in allowed for k, allowed in conditions):
                continue
            if predicate is not None and not predicate(block):
                continue
            try:
-                if q.matches(haystacks[i], deadline=deadline):
+                if q.matches(f"{block.title}\n{block.text}" if block.title else block.text,
                             deadline=deadline):
                    matched.append(block)
            except QueryTimeout:
                truncated = True
@ -224,11 +214,16 @@ class SearchEngine:
        )
    @staticmethod
-    def _conditions(filters):
+    def _filter(blocks, filters, predicate):
        conditions = []
        for key, value in (filters or {}).items():
            if value is None or value == "" or value == []:
                continue
            allowed = set(value) if isinstance(value, (list, tuple, set, frozenset)) else {value}
            conditions.append((key, allowed))
-        return conditions
+        for block in blocks:
            if any(block.meta.get(k) not in allowed for k, allowed in conditions):
                continue
            if predicate is not None and not predicate(block):
                continue
            yield block
--- a/src/mdgrep/markdown.py
+++ b/src/mdgrep/markdown.py
@ -9,13 +9,6 @@ Split modes:
 Every block gets `meta["section"]` (nearest preceding heading text), `meta["kind"]`
 ("file", "section", "item" or "paragraph") and `meta["markdown"]` (the raw source).
 `dialect` (list mode) decides how list items are recognised, so blocks line up with the HTML
 your Markdown renderer produces:
    commonmark       (default) a list may interrupt a paragraph; only unindented markers start
                     top-level items
    python-markdown  a list needs a blank line before it; markers indented by up to 3 spaces
                     still start top-level items (nesting needs 4 spaces)
 The searchable `text` is plain text with Markdown syntax removed. In `file` and `heading`
 mode the heading becomes the block title (and is removed from the text); list items and
 paragraphs have no title.
@ -29,22 +22,19 @@ from typing import Callable, Iterable
 from .engine import Block
-__all__ = ["load_markdown", "split_markdown", "markdown_to_text", "slugify", "SPLIT_MODES", "DIALECTS"]
+__all__ = ["load_markdown", "split_markdown", "markdown_to_text", "slugify", "SPLIT_MODES"]
 SPLIT_MODES = ("file", "heading", "list", "paragraph")
 DIALECTS = ("commonmark", "python-markdown")
 _HEADING = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$")
 _FENCE = re.compile(r"^\s*(```|~~~)")
 _LIST_ITEM = re.compile(r"^([-*+]|\d{1,9}[.)])\s+")
 _LIST_ITEM_PYMD = re.compile(r"^ {0,3}([-*+]|\d{1,9}\.)\s+")
 _HR = re.compile(r"^\s*([-*_])(\s*\1){2,}\s*$")
 def load_markdown(paths: str | Path | Iterable[str | Path], *, split: str = "paragraph",
                  meta: Callable[[Path], dict] | None = None, encoding: str = "utf-8",
-                  pattern: str = "*.md", relative_to: str | Path | None = None,
+                  pattern: str = "*.md", relative_to: str | Path | None = None) -> list[Block]:
                  dialect: str = "commonmark") -> list[Block]:
    """Load Markdown files (directories are searched recursively for `pattern`).
    `meta(path)` may return a dict merged into every block's meta of that file.
@ -57,7 +47,7 @@ def load_markdown(paths: str | Path | Iterable[str | Path], *, split: str = "par
        text = path.read_text(encoding=encoding)
        extra = meta(path) if meta else {}
        source = path.resolve().relative_to(base).as_posix() if base else str(path)
-        blocks.extend(split_markdown(text, source=source, split=split, meta=extra, dialect=dialect))
+        blocks.extend(split_markdown(text, source=source, split=split, meta=extra))
    return blocks
@ -74,19 +64,18 @@ def _expand(paths, pattern):
 def split_markdown(text: str, *, source: str = "", split: str = "paragraph",
-                   meta: dict | None = None, dialect: str = "commonmark") -> list[Block]:
+                   meta: dict | None = None) -> list[Block]:
-    """Split one Markdown document into blocks (see module docstring for modes and dialects)."""
+    """Split one Markdown document into blocks (see module docstring for modes)."""
    if split not in SPLIT_MODES:
        raise ValueError(f"split must be one of {SPLIT_MODES}, got {split!r}")
    if dialect not in DIALECTS:
        raise ValueError(f"dialect must be one of {DIALECTS}, got {dialect!r}")
    meta = meta or {}
    lines = text.splitlines()
-    if split == "list":
+    raw_blocks = {
-        raw_blocks = _split_list(lines, dialect == "python-markdown")
+        "file": _split_file,
-    else:
+        "heading": _split_heading,
-        raw_blocks = {"file": _split_file, "heading": _split_heading,
+        "list": _split_list,
-                      "paragraph": _split_paragraph}[split](lines)
+        "paragraph": _split_paragraph,
    }[split](lines)
    blocks = []
    for start, end, kind, section, title, anchor in raw_blocks:
@ -138,7 +127,7 @@ def _split_heading(lines):
    return out
-def _split_list(lines, pymd=False):
+def _split_list(lines):
    out = []
    section = ""
    cur = None           # [start, kind]
@ -150,7 +139,6 @@ def _split_list(lines, pymd=False):
            out.append((cur[0], end, cur[1], section, "", ""))
            cur = None
    item_re = _LIST_ITEM_PYMD if pymd else _LIST_ITEM
    prev_blank = True
    for i, line, in_fence, heading in _scan(lines):
        if heading:
@ -166,9 +154,7 @@ def _split_list(lines, pymd=False):
        if in_fence:
            if cur is None:
                cur = [i, "paragraph"]
-        elif pymd and cur is not None and cur[1] == "paragraph" and not prev_blank:
+        elif _LIST_ITEM.match(line):
            pass                                   # Python-Markdown: no list without blank line
        elif item_re.match(line):
            close(last_content + 1)
            cur = [i, "item"]
        elif _HR.match(line):
--- a/src/mdgrep/query.py
+++ b/src/mdgrep/query.py
@ -133,11 +133,7 @@ class Term:
    pattern: regex.Pattern = field(repr=False)
    def evaluate(self, text: str, deadline: float | None) -> bool:
-        # Words and phrases are escaped literals and run in linear time; only user-supplied
+        return self.pattern.search(text, timeout=_remaining(deadline)) is not None
        # regular expressions can backtrack catastrophically and need the (costly) timeout.
        if self.kind == "regex":
            return self.pattern.search(text, timeout=_remaining(deadline)) is not None
        return self.pattern.search(text) is not None
@dataclass
@ -289,7 +285,6 @@ class Query:
        if deadline is None and timeout is not None:
            deadline = time.monotonic() + timeout
        try:
            _remaining(deadline)
            return self._root.evaluate(text, deadline)
        except TimeoutError as e:
            raise QueryTimeout(str(e) or "Search time limit exceeded") from None
@ -301,8 +296,7 @@ class Query:
        found = []
        try:
            for term in self.positive_terms:
-                timeout = _remaining(deadline) if term.kind == "regex" else None
+                for m in term.pattern.finditer(text, timeout=_remaining(deadline)):
                for m in term.pattern.finditer(text, timeout=timeout):
                    if m.end() > m.start():
                        found.append((m.start(), m.end()))
        except TimeoutError as e:
--- a/tests/test_markdown.py
+++ b/tests/test_markdown.py
@ -63,29 +63,6 @@ def test_split_list():
    assert "not a heading" in blocks[6].text
 def test_dialect_list_interrupting_paragraph():
    doc = "**1. Trend**\n* stories: a\n* why: b\n\n- real item\n"
    common = split_markdown(doc, split="list")
    assert [b.meta["kind"] for b in common] == ["paragraph", "item", "item", "item"]
    pymd = split_markdown(doc, split="list", dialect="python-markdown")
    assert [b.meta["kind"] for b in pymd] == ["paragraph", "item"]
    assert "stories: a" in pymd[0].text
 def test_dialect_nesting_indent():
    doc = "1. **Trend A**\n   - why: x\n   - how: y\n\n2. **Trend B**\n    - nested: z\n"
    common = split_markdown(doc, split="list")
    assert [b.line for b in common] == [1, 5]
    pymd = split_markdown(doc, split="list", dialect="python-markdown")
    assert [b.line for b in pymd] == [1, 2, 3, 5]      # 3 spaces: no nesting in Python-Markdown
    assert "nested: z" in pymd[-1].text
 def test_invalid_dialect():
    with pytest.raises(ValueError):
        split_markdown("x", split="list", dialect="gfm")
 def test_split_heading():
    blocks = split_markdown(DOC, split="heading")
    assert [(b.title, b.anchor) for b in blocks] == [