Die Desktop-App¶
apps/desktop ist Schreibzeug als Desktop-App für Windows, macOS und Linux, gebaut mit Tauri 3
(Alpha). Sie arbeitet an einem von zwei Orten, gewählt auf ihrer Startseite und für den nächsten
Start gemerkt:
- Auf diesem Computer: die Dateien im Dokumente-Ordner (oder einem anderen Ordner), über einen kleinen Server, den die App neben ihrem Fenster startet (unten). Kein Konto, kein Netzwerk.
- Auf einem Schreibzeug-Server: Die App fragt einmal nach der Adresse des Servers, merkt sich die letzten und zeigt dann die eigene Web-App des Servers. Alles, was der Browser kann, funktioniert genauso, und ein Update des Servers aktualisiert auch die Seiten der App.
┌─▶ http://127.0.0.1:<port> (apps/local + the web app inside the app) ─▶ ~/Documents
Schreibzeug window (Tauri) ┤
start page └─▶ https://your-server (apps/server + apps/web/dist)
Wie es zusammenpasst¶
- Die Startseite (
apps/desktop/index.html,src/main.ts,src/servers.ts,src/start.ts) ist die eigene Seite der App. „Öffnen“ startet den lokalen Server und öffnet den Ordner; „Ordner ändern …“ wählt einen anderen. Für einen Server ergänzt sie, was eingetippt wird (schreibzeug.example.orgbekommthttps://,localhost:3000oder eine Adresse im lokalen Netzhttp://), prüft, dass unter/api/healthetwas antwortet, und behält die letzten fünf Server in ihrem eigenen Speicher. Der nächste Start geht dorthin zurück, wo die App zuletzt war: zum Ordner oder zum neuesten Server. - Der Server liefert die Web-App aus: Wenn
SCHREIBZEUG_WEB_DIRaufapps/web/distzeigt, beantwortet der API-Server jeden Pfad, der nicht/apiist, mit der gebauten App und unbekannte Pfade mitindex.html(apps/server/src/web.ts). Das Fenster lädt die Adresse des Servers direkt, sodass Sitzungen, der Socket der Zusammenarbeit und die Engine genau wie in einem Browser auf diesem Server funktionieren; keine Cross-Origin-Anfragen, keine zweite Kopie der Oberfläche in der App. - Das Fenster (
src-tauri/src/lib.rs): Downloads gehen in den Download-Ordner („Downloads“ im Home-Verzeichnis, wo Linux keinen eingerichtet hat), ohne eine Datei zu überschreiben (downloads.rs). Eine Seite desselben Servers, die ein neues Fenster öffnet (ein neues oder kopiertes Dokument), bekommt ein Fenster der App, in dem die Sitzung gilt; jeder andere Link (Strg+Klick auf einen Link in einem Dokument) öffnet sich im Browser des Systems, nur für http, https und mailto. „Auf diesem Computer“, „Ordner wählen …“ und „Mit Server verbinden …“ (zurück zur Startseite) stehen im ⋮-Menü neben dem Namen unten links; das Fenster hat keine eigene Menüleiste, nur macOS behält eine oben am Bildschirm. Die App markiert jede Seite, die sie zeigt (window.schreibzeugDesktop), und ein Befehl ist eine Navigation zuhttps://desktop.schreibzeug.invalid/<command>, die das Fenster abfängt, bevor sie lädt (windows.rsdesktop_action), sodass weder die lokalen noch die Seiten eines Servers dafür native Aufrufe brauchen (apps/web/src/desktop.ts). - Der lokale Server (
local.rs): beim ersten Gebrauch mit einem zufälligen Schlüssel gestartet, mit der App beendet; er endet auch, wenn sein stdin schließt, sodass eine abgestürzte App nichts laufen lässt. Ein neuer Ordner startet ihn neu und schließt die Fenster, die den alten zeigten. Der Ordner wird insettings.jsonim Konfigurationsordner der App gespeichert (settings.rs); ohne Eintrag ist es der Dokumente-Ordner des Systems (der Known Folder von Windows,~/Documentsauf macOS, der von XDG auf Linux), in der App „Dokumente“ genannt. - Native Aufrufe nur von der Startseite: Ihre drei Befehle (
open_local,local_folder,choose_folder) gehören der App selbst; die Seiten eines Servers oder des lokalen Servers bekommen keine (capabilities/default.jsongewährt nur die Core-Standards, und nur dem eigenen Fensterinhalt der App).
Die Browser-Engine ist auf Windows (WebView2, Chromium) und macOS (WebKit) die des Systems. Auf
Linux bringt die App Chromium selbst mit (CEF, tauri-runtime-cef von Tauri 3) statt WebKitGTK,
das mit dem Canvas der Editoren langsam ist und sich von den Browsern unterscheidet, in denen die
Web-App getestet wird. Das macht die Linux-Pakete um etwa 170 MB größer. In einem Linux-Build kann
nur eine Engine stecken (die Runtime von WebKitGTK baut auf GTK 3, CEF auf GTK 4), deshalb läuft
der Ordnerdialog dort über das XDG Desktop Portal (den eigenen Dialog des Desktops) statt über
GTK 3. Tauri 3 und seine CEF-Runtime sind Alpha-Versionen.
Chromium, wie CEF es baut, spricht von sich aus mit Google: Secure-DNS-Proben, Anmeldestatus,
Suche, das Übersetzungsmodell, Netzwerkzeit und Komponenten-Updates. Die App schaltet all das ab
(runtime() in src-tauri/src/lib.rs); ein Net-Log der App (--log-net-log) zeigt dann nur
Anfragen an die eigenen Seiten und den Server der App. In den Linux-Paketen verschiebt der Bundler
das Binary der App nach /usr/share/Schreibzeug/ und lässt den lokalen Server in /usr/bin/; die
App sucht an beiden Stellen (local.rs).
Dateien auf diesem Computer¶
apps/local ist ein kleiner Server, um ohne Schreibzeug-Server zu arbeiten: Er spricht den Teil der
Dateien-API, den eine einzelne Person braucht (dieselben Routen und Formen wie apps/server, aus
@schreibzeug/files-api), über einem Ordner auf dem Computer, standardmäßig dem Dokumente-Ordner
des Systems. Die Web-App ist dieselbe; sie fragt /api/info, mit welcher Art Server sie spricht,
benennt bei local die oberste Ebene nach dem Ordner („Dokumente“) und lässt weg, was nur mit
Konten sinnvoll ist.
- Dateien sind die Dateien: Ein Ordner in der App ist ein Ordner auf der Festplatte, eine Datei
ist eine Datei. Neue Dokumente, Uploads, Kopien, Umbenennen und Verschieben geschehen dort; ein
Speichern überschreibt die Datei (zuerst unter einem temporären Namen daneben geschrieben, dann
umbenannt). Versteckte Dateien, die
~$-Sperrdateien von Office unddesktop.ini/Thumbs.dbwerden nicht gelistet, und eine neue Datei, ein Ordner oder ein Name, den die Liste verstecken würde, wird abgelehnt (400), bevor auf der Festplatte etwas geschieht. - IDs: Die API benennt Knoten per UUID; hier ist die ID eines Knotens eine UUID v5 seines Pfads
unterhalb der obersten Ebene, sodass ein Link nach einem Neustart gleich bleibt. Ein Umbenennen
oder Verschieben behält die ID, solange der Server läuft (
src/ids.ts), sodass ein offener Editor bei seiner Datei bleibt. - Löschen verschiebt in den Papierkorb des Systems (
gio trashauf Linux, der Finder auf macOS, der Papierkorb auf Windows;src/trash.ts) und gilt erst als erledigt, wenn die Datei weg ist. Es gibt keine eigene Papierkorb-Seite, kein Teilen, keine Links, keine Versionen zum Zurückgehen, keine Suche und keine Jobs für ein offenes Dokument; diese Routen antworten „Das gibt es nur auf einem Schreibzeug-Server“ (src/app.ts). Die Versionsnummer zählt nur die Speichervorgänge seit dem Start des Servers, die die Bearbeitungssitzung braucht. - Speicherplatz:
/api/storagenennt den Platz auf dem Laufwerk des Ordners und keine eigene Belegung; die App zeigt dafür keinen Balken, das übernimmt der Dateimanager des Systems, nur den Hinweis, wenn weniger als 1 GB frei ist (Dateien). - Markdown- und Textdateien öffnen sich im Texteditor (Markdown- und Textdateien): Ein Speichern geht nur durch, solange die Datei auf der Festplatte noch die Bytes sind, aus denen es entstand, sodass eine Änderung durch ein anderes Programm (einen Editor, ein Sync-Werkzeug) nicht überschrieben wird; der Editor fragt stattdessen.
- Bearbeiten nutzt dasselbe Relay wie der Server (
apps/server/src/collab), sodass zwei Fenster auf derselben Datei gemeinsam bearbeiten. Eine Sitzung öffnet die Version, bei der sie begann, und spielt ihre Änderungen darauf ab, auch nachdem Speichervorgänge die Datei weitergebracht haben; der Ordner behält keine älteren Versionen, deshalb hält der Server die Bytes der ersten Version jeder Sitzung, solange die Sitzung dauert (src/session-bases.ts), und liefert sie für?version=aus (eine Datei, die vor dem ersten Laden der Sitzung von außen geschrieben wurde, ohne dass schon eine Änderung gemacht ist, startet die Sitzung, wie sie ist). Bilder, die beim Bearbeiten eingefügt werden, warten in einem Cache-Ordner, bis die Datei mit ihnen gespeichert ist. - Nur für diesen Computer (
src/gate.ts): Der Server lauscht auf 127.0.0.1 und will den Schlüssel, den die App beim Start erzeugt hat. Die App öffnet/api/local/unlock?token=…, das ein HttpOnly-Cookie mit SameSite=Strict hinterlässt; eine Anfrage mit fremdem Hostnamen (DNS Rebinding) oder eine Änderung, die von der Seite einer anderen Site geschickt wird, wird abgelehnt. - MCP (
src/mcp.ts):/mcpbietet dieselben Werkzeuge wie ein Server (MCP-Server), ohne Schlüssel, hinter derselben Prüfung von Host und Origin; seine Werkzeuge erreichen die lokale API mit dem eigenen Schlüssel der App. Die App startet den lokalen Server auf einem freien Port (PORT=0,src-tauri/src/local.rs), bei jedem Start einem anderen, sodass ein MCP-Client, der mit der Adresse der App eingerichtet ist, nach einem Neustart der App nicht mehr funktioniert.
| Variable | Bedeutung |
|---|---|
SCHREIBZEUG_LOCAL_ROOT |
Der gezeigte Ordner; ohne Angabe ~/Documents, sonst das Home-Verzeichnis |
SCHREIBZEUG_LOCAL_ROOT_NAME |
Wie die App ihn nennt; ohne Angabe der eigene Name des Ordners |
SCHREIBZEUG_LOCAL_TOKEN |
Der Schlüssel (mindestens 16 Zeichen); ohne Angabe ein zufälliger, ausgegeben mit der Entsperr-Adresse |
PORT |
0 (Standard): irgendein freier Port |
SCHREIBZEUG_WEB_DIR |
Die gebaute Web-App, die neben der API ausgeliefert wird |
SCHREIBZEUG_LOCAL_CACHE |
Wo Bilder warten, bis sie gespeichert sind; standardmäßig ein Ordner im Temp-Ordner des Systems |
SCHREIBZEUG_MAX_UPLOAD_MB |
Die größte Datei zum Hochladen oder Speichern; standardmäßig 512 |
SCHREIBZEUG_LOCAL_EXIT_WITH_STDIN |
1: beenden, wenn stdin schließt; das setzt die Desktop-App, damit der Server mit ihr endet (src-tauri/src/local.rs) |
USER, USERNAME |
Der Name, der für die eine Person gezeigt wird; der Name des Systemkontos |
Sobald er lauscht, gibt er SCHREIBZEUG_LOCAL_READY http://127.0.0.1:<port> aus. Von Hand, mit dem
Dev-Server der Web-App davor:
SCHREIBZEUG_LOCAL_ROOT=~/Dokumente PORT=3300 bun run --filter @schreibzeug/local start
SCHREIBZEUG_API_URL=http://localhost:3300 bun run --filter @schreibzeug/web dev
# dann http://localhost:5173/api/local/unlock?token=<das ausgegebene Token> öffnen
Bauen¶
Die App enthält die gebaute Web-App (apps/web/dist, mit der Engine) und den lokalen Server,
mit bun build --compile zu einem Executable pro Plattform kompiliert (scripts/sidecar.ts, von
Tauri vor jedem Build nach src-tauri/binaries/ ausgeführt). Also zuerst die Web-App bauen:
bun run engine:prepare && bun run build # apps/web/dist (Linux x86_64 für die Schriften der Engine)
bun run --filter @schreibzeug/desktop desktop:dev # die App gegen den Dev-Server der Startseite
bun run --filter @schreibzeug/desktop desktop:build # Installer für diesen Rechner
Die Schriften der Engine und die Bun-Runtime machen die Installer groß (etwa 200 MB); die Schriften zu verschlanken kommt später.
Linux braucht GTK 4.14 oder neuer (libgtk-4-dev librsvg2-dev; Ubuntu 24.04, Debian 13); Chromium
(CEF, etwa 1 GB) lädt der erste Build herunter, nach CEF_PATH, falls gesetzt. Der Workflow
Actions → Desktop app baut die Web-App einmal auf Linux und dann alle drei Plattformen:
AppImage, .deb und .rpm; .msi und eine Setup-.exe; eine .dmg für Intel und Apple Silicon. Von Hand
gestartet behält er sie als Artefakte; jedes Release (Actions → Bump version, siehe
Entwicklung) baut sie ebenfalls und hängt sie an das GitHub-Release. Die
Version kommt aus apps/desktop/package.json, das der Bump auf der Version des Releases hält. Die
.rpm wird mit zstd auf Stufe 3 komprimiert und die Setup-.exe mit zlib (tauri.conf.json) statt
mit den Standards des Bundlers, zstd auf Stufe 19 und LZMA, die jeweils etwa vier Minuten
brauchten, für eine etwas größere Datei.
Gepatchte Tauri-CLI¶
Vorübergehend, bis Tauri es behebt (#12): Der
Bundler von Tauri 3 Alpha kopiert libEGL.so und libGLESv2.so aus CEF in jedes Linux-Paket, und
CEF 154 liefert sie nicht mehr mit, also scheitert jedes Linux-Paket. Auf Linux baut
apps/desktop/scripts/tauri.ts deshalb die Tauri-CLI der Version in package.json aus den Quellen
von Tauri, mit apps/desktop/patches/*.patch angewendet (einmal, nach
src-tauri/target/patched-cli/), und die Skripte des Desktop-Pakets nutzen sie: tauri
(cd apps/desktop && bun run tauri …; die Wurzel hat kein solches Skript), desktop:dev und
desktop:build (der desktop-Job der CI baut sie auf main, sodass ein Release, das auf seinem
Tag läuft und den Cache von main liest, sie dort findet, statt vier Minuten dafür zu brauchen);
Windows und macOS nutzen die veröffentlichte CLI. Das Skript bricht ab, wenn ein Patch auf eine
neue Version nicht mehr passt: Dann prüfen, ob dieses Release den Fehler behebt, und den Patch
entfernen, wie in apps/desktop/patches/README.md beschrieben.
Die Builds sind noch nicht signiert. Windows SmartScreen zeigt „Unbekannter Herausgeber“ („Weitere Informationen“ → „Trotzdem ausführen“). macOS Gatekeeper verweigert beim ersten Mal das Öffnen der App; seit macOS 15 (Sequoia) kommt Rechtsklick → „Öffnen“ nicht mehr daran vorbei: Versuche die App einmal zu öffnen und erlaube sie dann unter „Systemeinstellungen“ → „Datenschutz & Sicherheit“ → „Dennoch öffnen“. Linux-Pakete brauchen keine Signatur.
Tests¶
apps/local/test/files.test.ts führt die lokale API über einem temporären Ordner aus,
gate.test.ts die Prüfung von Host, Origin und Schlüssel, mcp.test.ts den MCP-Endpunkt,
units.test.ts die Einstellungen und die IDs. e2e/local.spec.ts öffnet die App auf dem lokalen
Server und arbeitet mit Dateien in seinem Ordner; apps/desktop/src/*.test.ts deckt die Startseite
ab.
Als Nächstes¶
- Lokale und Server-Dateien nebeneinander, mehrere Ordner.
- Schreibzeug als Standard-App für .docx, .xlsx und .pptx.
- Signieren und Updates über den Tauri-Updater.