# notizi Connector (Chrome / Edge / Vivaldi)

Speichert die aktuelle Seite, markierten Text oder einen Bildausschnitt
direkt als Notiz in der notizi-Anwendung.

## Einrichtung

**1. In notizi freischalten**

Einstellungen → *Browser-Erweiterung* → Häkchen bei
*Verbindungen von Browser-Erweiterungen annehmen*.
Der Listener horcht ausschließlich auf `127.0.0.1` und ist von außen nicht
erreichbar.

**2. Erweiterung laden**

- `chrome://extensions` öffnen (bei Vivaldi `vivaldi://extensions`)
- *Entwicklermodus* einschalten
- *Entpackte Erweiterung laden* → diesen Ordner auswählen

**3. Koppeln**

- In notizi: *Kopplung für 2 Minuten freigeben*
- Im Browser auf das Erweiterungssymbol → *Koppeln*
- Der Browser zeigt einen sechsstelligen Code. notizi fragt nach und
  zeigt denselben Code. Stimmt er überein → *Ja*.

Ohne diesen Schritt lehnt die Anwendung jede Anfrage ab. Es gibt bewusst
keine automatische Kopplung: Andernfalls könnte sich jedes lokal laufende
Programm unbemerkt verbinden.

## Kopplung und Datenbanken

Die Kopplung gilt der **Anwendung**, nicht einer einzelnen Datenbank. Sie
liegt in der `settings.json` von notizi und bleibt bestehen, egal
welche Notiz-Datenbank gerade aktiv ist.

Neue Notizen landen immer in der **gerade aktiven** Datenbank. Welche das
ist, steht hinter dem Zahnrad unter *Ziel-Datenbank* und wird nach dem
Speichern in der Meldung genannt. Wer dort etwas anderes braucht,
wechselt in notizi die Datenbank – die Kopplung bleibt davon
unberuehrt.

## Alltag

Nach der Kopplung zeigt das Popup nur noch die Aktionen. Es erscheint keine
Statusmeldung, solange alles funktioniert. Eine rote Zeile taucht nur auf,
wenn die Anwendung nicht erreichbar oder die Kopplung weg ist – dann sind
auch die Aktionsknoepfe gesperrt, damit man nicht ins Leere klickt.

Alles zur Verbindung steckt hinter dem Zahnrad oben rechts: Port,
Verbindungstest und Kopplung.

## Bedienung

| Weg | Aktion |
|---|---|
| Rechtsklick auf Auswahl | Auswahl als Notiz speichern |
| Rechtsklick auf die Seite | Seite bzw. Bildausschnitt als Notiz |
| Symbolleiste | Popup mit allen drei Aktionen |
| `Alt+Shift+S` | Markierten Text |
| `Alt+Shift+P` | Seite |
| `Alt+Shift+B` | Bildausschnitt aufziehen |
| `Alt+Shift+E` | Bildausschnitt im Editor öffnen |

Jede so erzeugte Notiz bekommt automatisch ein Quellen-Badge mit der
Adresse der Seite.

### Wie eine Seite uebernommen wird

Zuerst wird der Container mit dem meisten Fliesstext bestimmt – nicht das
erste `<article>`, das ist auf Nachrichtenseiten meist nur ein Teaser.
Navigation, Fusszeilen, Werbung, Cookie-Hinweise, Kommentare und
Teaserlisten fliegen vorher raus. Deckt der beste Kandidat weniger als ein
Viertel des Gesamttextes ab, wird die ganze Seite genommen.

Danach wird die **Struktur** in Dokumentreihenfolge eingesammelt und in der
Notiz nachgebaut:

| Auf der Seite | In der Notiz |
|---|---|
| `h1`–`h6` | Ueberschrift, Groesse nach Ebene |
| `p`, Textknoten | Absatz |
| `ul`, `ol` | Aufzaehlung bzw. Nummerierung |
| `blockquote` | Zitat mit Randstrich |
| `pre` | Codeblock in Consolas |
| `img`, `figure` | Bild, Bildunterschrift als Kleintext |
| `hr` | Trennlinie |

Dazu kommen Beschreibung, Autor, Datum und Domain als Kopfbereich.

**Bilder** werden im Hintergrunddienst nachgeladen, auf maximal 1200 Pixel
Kantenlaenge verkleinert und als JPEG eingebettet. Das passiert bewusst
nicht auf der Seite selbst: ein Canvas dort waere bei fremden Bildquellen
"tainted" und liesse sich nicht auslesen. Grenzen: hoechstens 14 Bilder und
8 MB pro Notiz, Bilder unter 150x110 Pixel sowie extreme Seitenverhaeltnisse
(Spacer, Trennlinien, Logos) werden uebersprungen. Nicht ladbare Bilder
(CORS, 403) fallen still weg.

Deshalb steht in `manifest.json` auch `<all_urls>` unter
`host_permissions` – ohne Zugriff auf beliebige Bildquellen bliebe die
Notiz reiner Text. Wer das nicht moechte, entfernt den Eintrag: dann
funktioniert alles weiter, nur ohne Bilder.

## Technisch

- `POST /pair` – Kopplung, nur im freigegebenen Zeitfenster und nach
  Bestätigung im Programm. Antwortet mit einem Token.
- `POST /note` – legt eine Notiz an, benötigt den Header
  `x-notizi-token`.
- `POST /screenshot` – öffnet das Bild im Screenshot-Editor der Anwendung.
  Was danach damit geschieht, entscheidet sich dort.
- `POST /open` – holt eine Notiz anhand ihrer Kennung in den Vordergrund.
- `GET /ping` – Statusabfrage.

Das Token liegt in `chrome.storage.local` und wird ungültig, sobald die
Kopplung in notizi aufgehoben wird.

## Nach dem Speichern

Rechts unten erscheint eine Meldung mit der Wortzahl und dem Knopf
*Notiz öffnen*. Ein Klick holt die Notiz in der Anwendung nach vorn
(Endpunkt `POST /open`). Die Meldung bleibt neun Sekunden stehen und
pausiert, solange die Maus darauf liegt.

## Aktualisieren

Die Kopplung bleibt bei einem Update erhalten. Es genuegt:

1. Die Dateien in **demselben** Ordner ueberschreiben
2. In `chrome://extensions` auf das Neu-laden-Symbol der Erweiterung klicken

Kein Entfernen, kein erneutes Koppeln. Das Token liegt in
`chrome.storage.local` und wird nur beim *Entfernen* der Erweiterung
geloescht – nicht beim Neuladen und nicht bei einer neuen Version.

Damit das auch bei einem Ordnerwechsel gilt, enthaelt `manifest.json` ein
Feld `key`. Ohne dieses Feld leitet Chrome die Erweiterungs-ID aus dem
Pfad ab, und ein anderer Ordner waere eine voellig neue Erweiterung mit
leerem Speicher. Mit dem festen Schluessel lautet die ID immer:

```
mkefcaakoadaiiijhkobkhemfminngma
```

**Empfehlung:** Den Ordner `browser-extension` einmal an einen festen Platz
kopieren (nicht bei jedem Entpacken neu woanders hin) und Chrome von dort
laden.

### Falls die Kopplung doch verloren geht

In notizi: Einstellungen -> Browser-Erweiterung -> Kopplung
auswaehlen -> *Token kopieren*. Im Popup hinter dem Zahnrad in das Feld
*Token* einfuegen und uebernehmen. Das spart die erneute Kopplung.

## Versionen

Erweiterung und Anwendung tragen dieselbe Buildkennung. Sichtbar sind sie:

- **Erweiterung**: Popup -> Zahnrad, unterste Zeile
- **Anwendung**: Einstellungen unten links, oder Tray-Menue

Weichen die Kennungen voneinander ab, faerbt sich die Zeile im Popup
orange. Ein Klick darauf kopiert beide Angaben – praktisch fuer eine
Rueckmeldung.

Aktuell: **1.1.0 (Build 2026-09-17.1)**

## Wenn es nicht geht

- *Keine Verbindung*: Läuft die Anwendung? Ist die Schnittstelle in den
  Einstellungen aktiviert? Stimmt der Port auf beiden Seiten überein?
- *Port belegt*: In notizi einen anderen Port eintragen und im Popup
  denselben setzen.
- *Bildausschnitt leer*: Auf `chrome://`-Seiten und im Web Store lässt
  Chrome grundsätzlich keine Skripte oder Screenshots zu.
- *Keine Bilder in der Notiz*: In `chrome://extensions` bei dieser
  Erweiterung auf *Details* gehen und **Website-Zugriff** auf *Auf allen
  Websites* stellen. Ohne das darf der Hintergrunddienst keine Bilder von
  fremden Servern laden. Die Meldung nach dem Speichern nennt das
  Verhaeltnis, etwa "3 von 9 Bildern" – dann blockieren einzelne Server den
  Abruf.
