feat: Code mit Farbe, Anleitung im Repo, Galerie mit Seitengroesse

CODE MIT FARBE, ohne Bibliothek. Ein Hervorheber wie highlight.js wiegt mehr
als diese ganze Oberflaeche und kann fuenfzig Sprachen, von denen hier drei
vorkommen. Was Code lesbar macht, sind drei Unterscheidungen -- Kommentar,
Zeichenkette, Schluesselwort. Der Rest ist Zierde. Also ein Tokenizer in einem
Ausdruck, der seine Grenzen kennt: verschachtelte Sonderfaelle faerbt er
falsch, und bei zehn Zeilen Beispiel ist das der richtige Tausch.

DIE ANLEITUNG liegt als docs/API.md IM REPO und damit unter Versionskontrolle,
statt nur im Wiki zu stehen, wo niemand sieht, wann sie zuletzt stimmte. Sie
nennt nicht nur die Endpunkte, sondern was schiefgehen kann und wie die Antwort
dann aussieht -- samt der beiden Proxy-Fallen, die uns heute begegnet sind.

Das Gitea-Wiki gibt es noch NICHT: Gitea legt das Wiki-Repo erst an, wenn die
erste Seite ueber die Oberflaeche erstellt wird (davor antwortet der Klon mit
500). Die API-Seite verlinkt es trotzdem schon -- und sobald es existiert,
schiebt ein Befehl docs/API.md hinein.

GALERIE: die Seitengroesse ist waehlbar (30/60/120/200 statt fester 60), und
die Ordnerspalte rueckt ab 1536 px nach LINKS AUS dem Hauptbereich heraus --
15rem Spalte plus 1rem Abstand sind genau die 16rem, um die dort nach links
gezogen wird. Damit steht das Raster auf derselben Breite wie jede andere
Seite, statt um die Spaltenbreite schmaler zu sein. Darunter stapelt es wie
bisher; auf einem 1280er Schirm gaebe es keinen Rand, in den etwas ruecken
koennte.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/API.md

@@ -0,0 +1,218 @@
+# Die API von d4rk_media
+
+Diese Seite ist für den Fall geschrieben, dass jemand ein Skript anbindet und
+etwas nicht tut, was es soll. Sie nennt deshalb nicht nur die Endpunkte,
+sondern auch **was schiefgehen kann und wie die Antwort dann aussieht**.
+
+Der Dienst läuft unter `https://fivemanage.d4rkst3r.de`. Dateien liegen darunter
+unter `/f/`.
+
+---
+
+## Der Grundsatz: der Pfad ist der Schlüssel
+
+`vehicles/adder.webp` bleibt `vehicles/adder.webp`. Die öffentliche Adresse
+entsteht daraus, indem der Ursprung davorgesetzt wird:
+
+```
+vehicles/adder.webp   →   https://fivemanage.d4rkst3r.de/f/vehicles/adder.webp
+```
+
+Deshalb kann die Vorlage in einem Handy-Skript schlicht `{model}.webp` lauten.
+**Die Adressen stehen nirgends in der Datenbank** — sie werden bei jeder
+Antwort neu gebaut. Ein Umzug auf einen anderen Namen ist eine geänderte
+Variable, kein Datenbankeingriff.
+
+### Erlaubte Pfade
+
+Jeder Teil zwischen den Schrägstrichen muss mit einem **Buchstaben oder einer
+Ziffer** beginnen; danach sind zusätzlich Punkt, Strich und Unterstrich
+erlaubt. Höchstens 8 Ebenen, höchstens 200 Zeichen.
+
+Damit sind `..`, versteckte Dateien und alles mit Backslash von vornherein
+draußen. Was nicht passt, wird **abgelehnt und nicht zurechtgebogen** — sonst
+läge eine Datei unter einem anderen Namen als dem, den der Aufrufer erwartet,
+und niemand merkte es, bis das Bild fehlt.
+
+> Ein führender Unterstrich fällt durch. Das ist kein erfundener Fall: das
+> Fotostudio legt seine Leerbilder als `_plate` ab.
+
+---
+
+## Anmeldung: Token
+
+Alle Skript-Wege brauchen einen Token im Kopf:
+
+```
+Authorization: Bearer d4rk_…
+```
+
+Tokens werden im Dashboard angelegt. Der Klartext wird **genau einmal** gezeigt
+— danach steht nur noch sein Hash in der Datenbank, und auch der Dienst kann
+ihn nicht mehr herausgeben.
+
+Ein Token kann zwei Fesseln haben:
+
+| Fessel | Wirkung |
+|---|---|
+| Präfix | darf nur unterhalb dieses Pfades schreiben, z. B. `vehicles/` |
+| darf löschen | ohne dieses Recht antwortet `DELETE` mit 403 |
+
+---
+
+## POST /api/upload
+
+Nimmt die Datei in einer von **drei Rumpfformen** entgegen:
+
+1. `multipart/form-data` mit dem Feld `file`
+2. Base64-Text, wenn `X-Encoding: base64` gesetzt ist
+3. rohe Bytes, sonst
+
+### Kopfzeilen
+
+| Kopf | Bedeutung |
+|---|---|
+| `X-Path` | Wohin die Datei kommt. **Ohne ihn** wird aus dem SHA-256 ein Pfad gebaut — dann ist die Adresse nicht mehr vorhersagbar. |
+| `X-Encoding` | `base64`, wenn der Rumpf Base64-Text ist. Ein Data-URL-Vorspann (`data:image/webp;base64,`) wird abgeschnitten. |
+| `X-Overwrite` | `false` verweigert das Überschreiben und antwortet mit 409. Standard ist überschreiben. |
+| `X-Mime` | Überschreibt die Art. Sonst entscheidet die Endung. |
+
+### Antwort
+
+```json
+{
+  "url": "https://fivemanage.d4rkst3r.de/f/vehicles/adder.webp",
+  "path": "vehicles/adder.webp",
+  "size": 132760,
+  "sha256": "36cb4ddf…",
+  "mime": "image/webp",
+  "replaced": false
+}
+```
+
+### Was schiefgehen kann
+
+| Antwort | Grund |
+|---|---|
+| 401 | Token fehlt oder ist unbekannt |
+| 403 | Der Token darf dort nicht schreiben (Präfix-Fessel) |
+| 400 | Pfad unzulässig, Rumpf leer, kaputtes Base64 |
+| 409 | `X-Overwrite: false` und der Pfad ist belegt |
+| 413 | größer als `MAX_UPLOAD_MB` (Standard 64) |
+
+Jede Fehlerantwort ist JSON mit einem Feld `error` und einem **Satz auf
+Deutsch**. Ein nackter 500 ohne Text ist genau der Fehler, wegen dem dieser
+Dienst gebaut wurde.
+
+---
+
+## Aus einer FiveM-Resource
+
+```lua
+local TOKEN = 'd4rk_…'   -- im Dashboard anlegen
+
+local function hochladen(pfad, bytes, cb)
+    PerformHttpRequest('https://fivemanage.d4rkst3r.de/api/upload',
+        function(status, body)
+            if status ~= 200 then return cb(nil, body) end
+            cb(json.decode(body).url)
+        end, 'POST', B64.encode(bytes), {
+            ['Authorization'] = 'Bearer ' .. TOKEN,
+            ['X-Path']        = pfad,
+            ['X-Encoding']    = 'base64',
+            ['Content-Type']  = 'text/plain; charset=utf-8',
+        })
+end
+```
+
+**Warum Base64 und nicht die rohen Bytes.** `PerformHttpRequest` nimmt den
+Rumpf als Lua-Zeichenkette, und ob Nullbytes darin unverändert ankommen, hat
+hier niemand nachgemessen — ein PNG besteht zu gutem Teil daraus. Base64 kostet
+ein Drittel mehr auf der Leitung und nimmt die Frage aus dem Weg. Nachgemessen
+ist: Base64 kommt mit demselben SHA-256 an wie die rohen Bytes.
+
+**Warum vom Server und nicht aus der NUI.** Die NUI läuft unter `https`, und
+CEF hebt jede `http`-Adresse selbst dorthin an. Ein Upload aus dem Fenster
+heraus wäre entweder Mixed Content oder ginge ins Leere.
+
+---
+
+## GET /api/exists/<pfad>
+
+Für „nur fehlende" in einem Serienlauf: eine winzige Antwort gegen 130 KB
+Upload.
+
+```json
+{ "exists": true, "path": "vehicles/adder.webp",
+  "url": "…", "size": 132760, "sha256": "…", "updated_at": 1786466462488 }
+```
+
+> **Drei Zustände, nicht zwei.** Wer einen Netzfehler als „nicht da" durchgehen
+> lässt, lädt bei einem Husten alles ein zweites Mal hoch. Ein Aufrufer sollte
+> zwischen `exists: false` und „ich weiß es nicht" unterscheiden.
+
+---
+
+## DELETE /api/media/<pfad>
+
+Braucht einen Token mit dem Recht **darf löschen**.
+
+```json
+{ "deleted": "vehicles/adder.webp" }
+```
+
+Löschen ist endgültig: die Datei ist von der Platte weg, und es gibt keinen
+Papierkorb. Die tägliche Sicherung hilft nur bis zum letzten Lauf.
+
+---
+
+## Grenzen
+
+| | |
+|---|---|
+| Größte Datei | 64 MB (`MAX_UPLOAD_MB`) |
+| Pfadlänge | 200 Zeichen, höchstens 8 Ebenen |
+| Anmeldeversuche | 5 frei, danach Sperre ab 30 s (verdoppelt bis 15 min) |
+| Sitzung | 30 Tage |
+
+---
+
+## Der Zwischenspeicher des Proxys
+
+Vor dem Dienst steht Nginx Proxy Manager. Dessen `assets.conf` greift über eine
+Regel auf **jede URL, die auf `.webp`, `.png`, `.js`, `.css` … endet** — und
+legt die Antwort für 30 Minuten weg, dabei ignoriert sie unsere eigenen
+Kopfzeilen.
+
+Das hatte zwei sichtbare Folgen, beide nachgemessen und beide behoben:
+
+- Ein **überschriebenes Bild** blieb bis zu 30 Minuten alt, obwohl Upload und
+  Datenbank „fertig" sagten.
+- `/api/exists/…webp` wurde mit Antwort zwischengespeichert und danach **auch
+  ohne Token** ausgeliefert.
+
+Behoben durch drei Blöcke in der *Custom Nginx Configuration* des Proxy-Hosts:
+
+```nginx
+location ^~ /api/ { proxy_cache off; include conf.d/include/proxy.conf; }
+location ^~ /f/   { proxy_cache off; include conf.d/include/proxy.conf; }
+location ^~ /t/   { proxy_cache off; include conf.d/include/proxy.conf; }
+```
+
+Das `^~` ist der ganze Trick: eine gewöhnliche Präfix-Regel **verliert** gegen
+die Regex aus `assets.conf`. In einem Wegwerf-Nginx nachgemessen.
+
+---
+
+## Export
+
+Im Dashboard unter **API** — oder direkt, mit gültiger Sitzung:
+
+```
+/api/dash/export?format=json      alles, was der Dienst weiß
+/api/dash/export?format=csv       Semikolon und CRLF, für Excel
+/api/dash/export?format=lua       fertige Tabelle Name → Adresse
+/api/dash/export?format=lua&folder=vehicles
+```
+
+Die Lua-Fassung liest man in einer Resource als `Urls.adder` aus.

server/ui/src/components/Code.tsx

@@ -0,0 +1,86 @@
+import { Check, Copy } from 'lucide-react'
+import { useKopieren } from './Bausteine'
+import { useStore } from '../store'
+
+/** Code mit Farbe — ohne Bibliothek.
+ *
+ *  Ein Hervorheber wie highlight.js wiegt mehr als diese ganze Oberfläche und
+ *  kann fünfzig Sprachen, von denen hier drei vorkommen. Was man wirklich
+ *  braucht, um Code lesbar zu machen, sind drei Unterscheidungen: Kommentar,
+ *  Zeichenkette, Schlüsselwort. Der Rest ist Zierde.
+ *
+ *  Deshalb ein Tokenizer in einem Ausdruck. Er ist bewusst einfach und kennt
+ *  seine Grenzen — verschachtelte Sonderfälle färbt er falsch. Bei einem
+ *  Beispielblock von zehn Zeilen ist das der richtige Tausch. */
+
+type Sprache = 'lua' | 'bash' | 'json'
+
+const MUSTER: Record<Sprache, RegExp> = {
+    // Reihenfolge zählt: Kommentare zuerst, sonst frisst eine Zeichenkette
+    // das `--` einer Kommentarzeile.
+    lua: /(--[^\n]*)|('[^'\n]*'|"[^"\n]*")|(\b(?:local|function|end|if|then|else|elseif|return|for|in|do|while|nil|true|false|and|or|not)\b)|(\b\d+\b)/g,
+    bash: /(#[^\n]*)|('[^'\n]*'|"[^"\n]*")|(\b(?:curl|echo|export|cd|if|then|fi|for|do|done)\b)|(-{1,2}[A-Za-z][\w-]*)/g,
+    json: /()("(?:[^"\\]|\\.)*")|(\b(?:true|false|null)\b)|(-?\b\d+(?:\.\d+)?\b)/g,
+}
+
+const FARBEN = ['text-schrift-leise/70 italic', 'text-gut', 'text-akzent', 'text-warn']
+
+function faerben(text: string, sprache: Sprache) {
+    const muster = new RegExp(MUSTER[sprache].source, 'g')
+    const stuecke: React.ReactNode[] = []
+    let letzte = 0
+    let treffer: RegExpExecArray | null
+
+    while ((treffer = muster.exec(text)) !== null) {
+        // Ein leerer Treffer wuerde die Schleife anhalten — bei json steht
+        // eine leere Gruppe fuer "keine Kommentare".
+        if (treffer[0] === '') {
+            muster.lastIndex++
+            continue
+        }
+        if (treffer.index > letzte) stuecke.push(text.slice(letzte, treffer.index))
+
+        const gruppe = [1, 2, 3, 4].find((i) => treffer![i] !== undefined)
+        stuecke.push(
+            <span key={treffer.index} className={FARBEN[(gruppe ?? 1) - 1]}>
+                {treffer[0]}
+            </span>,
+        )
+        letzte = treffer.index + treffer[0].length
+    }
+    if (letzte < text.length) stuecke.push(text.slice(letzte))
+    return stuecke
+}
+
+export function Code({
+    text,
+    sprache = 'bash',
+    marke,
+}: {
+    text: string
+    sprache?: Sprache
+    marke: string
+}) {
+    const note = useStore((s) => s.note)
+    const { kopiert, kopieren } = useKopieren()
+
+    return (
+        <div className="group relative">
+            <pre className="overflow-x-auto rounded-md border border-rand bg-grund p-3 pr-12 font-mono text-xs leading-relaxed">
+                <code>{faerben(text, sprache)}</code>
+            </pre>
+            <button
+                onClick={async () => {
+                    if (!(await kopieren(text, marke)))
+                        note('fehler', 'Die Zwischenablage ist gesperrt.')
+                }}
+                className="absolute top-2 right-2 rounded border border-rand bg-flaeche px-2 py-1
+                           text-schrift-leise opacity-0 transition-opacity group-hover:opacity-100
+                           focus-visible:opacity-100 hover:bg-flaeche-hoch hover:text-schrift"
+                aria-label="Kopieren"
+            >
+                {kopiert === marke ? <Check size={13} className="text-gut" /> : <Copy size={13} />}
+            </button>
+        </div>
+    )
+}

server/ui/src/components/Ordner.tsx

@@ -53,7 +53,7 @@ export function Ordner({
     )
 
     return (
-        <aside className="w-full shrink-0 self-start rounded-lg border border-rand bg-flaeche p-2 lg:w-72">
+        <aside className="w-full shrink-0 self-start rounded-lg border border-rand bg-flaeche p-2 lg:w-60">
             <h2 className="px-2 py-1 text-xs font-semibold text-schrift-leise">Ordner</h2>
 
             {zeile(

server/ui/src/pages/Api.tsx

@@ -3,6 +3,8 @@ import { Check, Copy, Download, FileJson, FileSpreadsheet, FileCode2 } from 'luc
 import { api, type Uebersicht } from '../api'
 import { useStore } from '../store'
 import { Karte, useKopieren } from '../components/Bausteine'
+import { Code } from '../components/Code'
+import { BookOpen, ExternalLink } from 'lucide-react'
 
 /** Anleitung und Export für die eigenen Skripte.
  *
@@ -34,24 +36,29 @@ export function Api() {
         if (!(await kopieren(text, marke))) note('fehler', 'Die Zwischenablage ist gesperrt.')
     }
 
-    const block = (marke: string, text: string) => (
-        <div className="relative">
-            <pre className="overflow-x-auto rounded-md border border-rand bg-grund p-3 font-mono text-xs leading-relaxed">
-                {text}
-            </pre>
-            <button
-                onClick={() => void kopiereBlock(text, marke)}
-                className="absolute top-2 right-2 rounded border border-rand bg-flaeche px-2 py-1
-                           text-schrift-leise hover:bg-flaeche-hoch hover:text-schrift"
-                aria-label="Kopieren"
-            >
-                {kopiert === marke ? <Check size={13} className="text-gut" /> : <Copy size={13} />}
-            </button>
-        </div>
-    )
-
     return (
         <div className="flex flex-col gap-4">
+            {/* Die ausfuehrliche Fassung liegt im Wiki. HIER steht das, was man
+                beim Anbinden in der Hand haben muss — dort das Drumherum, das
+                sich in einer Karte nicht lesen laesst. */}
+            <a
+                href="https://git.d4rkst3r.de/D4rkst3r/d4rk_media/wiki"
+                target="_blank"
+                rel="noreferrer"
+                className="flex items-center gap-3 rounded-lg border border-rand bg-flaeche px-4 py-3
+                           text-sm transition-colors hover:border-akzent"
+            >
+                <BookOpen size={18} className="shrink-0 text-akzent" />
+                <span className="flex-1">
+                    Die ausführliche Anleitung im Wiki
+                    <span className="block text-xs text-schrift-leise">
+                        Alle Endpunkte, Fehlermeldungen, Grenzen — und was beim Anbinden
+                        schiefgehen kann.
+                    </span>
+                </span>
+                <ExternalLink size={15} className="shrink-0 text-schrift-leise" />
+            </a>
+
             <Karte titel="Export">
                 <div className="flex flex-wrap items-center gap-2">
                     {(
@@ -87,9 +94,10 @@ export function Api() {
                     <code className="font-mono">PerformHttpRequest</code> den Rumpf als
                     Lua-Zeichenkette nimmt und ein Bild voller Nullbytes ist.
                 </p>
-                {block(
+                <Code
-                    'lua-upload',
+                    sprache="lua"
-                    `local TOKEN = 'd4rk_…'   -- im Dashboard unter Token anlegen
+                    marke="lua-upload"
+                    text={`local TOKEN = 'd4rk_…'   -- im Dashboard unter Token anlegen
 
 local function hochladen(pfad, bytes, cb)
     PerformHttpRequest('${B}/api/upload', function(status, body)
@@ -101,36 +109,39 @@ local function hochladen(pfad, bytes, cb)
         ['X-Encoding']    = 'base64',
         ['Content-Type']  = 'text/plain; charset=utf-8',
     })
-end`,
+end`}
-                )}
+                />
             </Karte>
 
             <Karte titel="Die drei Wege der Skript-API">
                 <div className="flex flex-col gap-3">
-                    {block(
+                    <Code
-                        'curl-upload',
+                        sprache="bash"
-                        `# Hochladen — rohe Bytes, X-Path bestimmt die spätere Adresse
+                        marke="curl-upload"
+                        text={`# Hochladen — rohe Bytes, X-Path bestimmt die spätere Adresse
 curl -X POST ${B}/api/upload \\
   -H "Authorization: Bearer d4rk_…" \\
   -H "X-Path: vehicles/adder.webp" \\
   --data-binary @adder.webp
 
-# → {"url":"${F}/vehicles/adder.webp","size":…,"sha256":…,"replaced":false}`,
+# → {"url":"${F}/vehicles/adder.webp","size":…,"sha256":…,"replaced":false}`}
-                    )}
+                    />
-                    {block(
+                    <Code
-                        'curl-exists',
+                        sprache="bash"
-                        `# Gibt es das schon? — für "nur fehlende" in einem Serienlauf
+                        marke="curl-exists"
+                        text={`# Gibt es das schon? — für "nur fehlende" in einem Serienlauf
 curl -H "Authorization: Bearer d4rk_…" \\
   ${B}/api/exists/vehicles/adder.webp
 
-# → {"exists":true,"url":"${F}/vehicles/adder.webp","size":…}`,
+# → {"exists":true,"url":"${F}/vehicles/adder.webp","size":…}`}
-                    )}
+                    />
-                    {block(
+                    <Code
-                        'curl-delete',
+                        sprache="bash"
-                        `# Löschen — der Token braucht dafür das Recht "darf löschen"
+                        marke="curl-delete"
+                        text={`# Löschen — der Token braucht dafür das Recht "darf löschen"
 curl -X DELETE -H "Authorization: Bearer d4rk_…" \\
-  ${B}/api/media/vehicles/adder.webp`,
+  ${B}/api/media/vehicles/adder.webp`}
-                    )}
+                    />
                 </div>
             </Karte>
 

server/ui/src/pages/Galerie.tsx

@@ -39,7 +39,7 @@ import { Ansehen } from '../components/Ansehen'
 import { Verschieben } from '../components/Verschieben'
 import { useAuffrischen } from '../auffrischen'
 
-const PRO_SEITE = 60
+const SEITENGROESSEN = [30, 60, 120, 200] as const
 
 export function Galerie() {
     const note = useStore((s) => s.note)
@@ -49,6 +49,7 @@ export function Galerie() {
     const [seite, setSeite] = useState(0)
     const [art, setArt] = useState<Art>('')
     const [arten, setArten] = useState<Arten | null>(null)
+    const [proSeite, setProSeite] = useState(60)
     const [sortierung, setSortierung] = useState<Sortierung>('geaendert')
     const [richtung, setRichtung] = useState<Richtung>('ab')
     const [daten, setDaten] = useState<MediaPage | null>(null)
@@ -87,8 +88,8 @@ export function Galerie() {
                 sucheAktiv,
                 ordner,
                 art,
-                PRO_SEITE,
+                proSeite,
-                seite * PRO_SEITE,
+                seite * proSeite,
                 sortierung,
                 richtung,
             )
@@ -100,7 +101,7 @@ export function Galerie() {
         } finally {
             if (meine === lauf.current) setLaedt(false)
         }
-    }, [sucheAktiv, ordner, art, seite, sortierung, richtung, note])
+    }, [sucheAktiv, ordner, art, seite, proSeite, sortierung, richtung, note])
 
     useEffect(() => {
         void laden()
@@ -153,7 +154,7 @@ export function Galerie() {
 
     const items = daten?.items ?? []
     const gesamt = daten?.total ?? 0
-    const seiten = Math.max(1, Math.ceil(gesamt / PRO_SEITE))
+    const seiten = Math.max(1, Math.ceil(gesamt / proSeite))
 
     function umschalten(id: number) {
         setGewaehlt((alt) => {
@@ -223,7 +224,14 @@ export function Galerie() {
     }
 
     return (
-        <div className="flex flex-col gap-4 lg:flex-row">
+        // Ab 2xl (1536 px) rueckt die Ordnerspalte nach LINKS AUS dem
+        // Hauptbereich heraus: 15rem Spalte + 1rem Abstand = die 16rem, um die
+        // hier nach links gezogen wird. Damit steht das Raster auf genau
+        // derselben Breite wie jede andere Seite.
+        //
+        // Darunter stapelt es wie bisher — auf einem 1280er Schirm waere kein
+        // Rand da, in den etwas ruecken koennte.
+        <div className="flex flex-col gap-4 lg:flex-row 2xl:-ml-64">
             <Ordner
                 daten={ordnerDaten}
                 gewaehlt={ordner}
@@ -358,6 +366,22 @@ export function Galerie() {
                         <option value="pfad">Pfad</option>
                         <option value="groesse">Größe</option>
                     </select>
+                    <select
+                        value={proSeite}
+                        onChange={(e) => {
+                            setProSeite(Number(e.target.value))
+                            setSeite(0)
+                        }}
+                        title="wie viele Kacheln je Seite"
+                        className="rounded-md border border-rand bg-flaeche px-2 py-1.5 text-sm
+                                   text-schrift focus:border-akzent focus:outline-none"
+                    >
+                        {SEITENGROESSEN.map((n) => (
+                            <option key={n} value={n}>
+                                {n} / Seite
+                            </option>
+                        ))}
+                    </select>
                     <button
                         onClick={() => {
                             setRichtung(richtung === 'ab' ? 'auf' : 'ab')