Hermes Agent
407 lines
15 KiB
Markdown
407 lines
15 KiB
Markdown
# Whiteboard URL-Referenzen — Implementierungsplan
|
||
|
||
> **Status:** Planungsphase · **Ziel:** Base64-Bilder durch URL-Referenzen ersetzen · **Erwartete Wirkung:** 50+ Bilder ohne OOM
|
||
|
||
---
|
||
|
||
## Ziel
|
||
|
||
Statt jedes Bild als 50MB Base64-String im Excalidraw-JSON zu speichern, soll nur eine **URL** gespeichert werden. Der Browser lädt das Bild nur beim Hinscrollen in den Viewport.
|
||
|
||
```
|
||
// VORHER (Status Quo):
|
||
"files": {
|
||
"abc123": {
|
||
"dataURL": "data:image/png;base64,iVBORw0KGgoAAAAA...", // ← 50 MB
|
||
"mimeType": "image/png"
|
||
}
|
||
}
|
||
|
||
// NACHHER (Ziel):
|
||
"files": {
|
||
"abc123": {
|
||
"url": "/remote.php/dav/files/Hermes/WhiteboardAssets/abc123.png",
|
||
"thumbUrl": "data:image/png;base64,...", // ← 5 KB Thumbnail (256px)
|
||
"mimeType": "image/png",
|
||
"width": 4000,
|
||
"height": 3000
|
||
}
|
||
}
|
||
```
|
||
|
||
**RAM-Effekt:**
|
||
- Vorher: 50 Bilder × 50 MB = **2,5 GB** 💥
|
||
- Nachher: 50 Bilder × 5 KB (Thumbnail) + 3 geladene Vollbilder × 50 MB = **~150 MB** ✅
|
||
|
||
---
|
||
|
||
## Architektur: 3 Eingriffspunkte
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ BROWSER │
|
||
│ │
|
||
│ 1. IMPORT-HANDLER │
|
||
│ Whiteboard JS (NcSelect) │
|
||
│ ┌──────────────────────────────────┐ │
|
||
│ │ File dropped by user │ │
|
||
│ │ ├─ Upload full image to NC │ ← NEU: WebDAV PUT │
|
||
│ │ ├─ Generate thumbnail (256px) │ ← NEU: Canvas │
|
||
│ │ └─ Store URL in file object │ ← NEU │
|
||
│ └──────────────────────────────────┘ │
|
||
│ │
|
||
│ 2. JSON-SPEICHERUNG │
|
||
│ Excalidraw data model │
|
||
│ ┌──────────────────────────────────┐ │
|
||
│ │ fileObject.url = "/dav/..." │ ← NEU │
|
||
│ │ fileObject.thumbUrl = "data:..." │ ← NEU (256px) │
|
||
│ │ fileObject.dataURL = DEPRECATED │ │
|
||
│ └──────────────────────────────────┘ │
|
||
│ │
|
||
│ 3. RENDERING │
|
||
│ Excalidraw renderer │
|
||
│ ┌──────────────────────────────────┐ │
|
||
│ │ Viewport check → load from url? │ ← NEU: Lazy Load │
|
||
│ │ Not visible → show thumbnail │ ← NEU: LOD │
|
||
│ │ Zoom > 150% → load full image │ ← NEU: Progressive │
|
||
│ └──────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
│ WebDAV / Files API
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ NEXTCLOUD SERVER │
|
||
│ ┌──────────────────────────────────┐ │
|
||
│ │ /WhiteboardAssets/ │ ← NEU: Ordner │
|
||
│ │ ├─ abc123.png │ │
|
||
│ │ ├─ def456.jpg │ │
|
||
│ │ └─ ... │ │
|
||
│ │ CORS: Allow-Origin: * │ ← NEU: Config │
|
||
│ └──────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Vorbereitung: Test-Toolkit
|
||
|
||
| Tool | Zweck |
|
||
|---|---|
|
||
| `curl` | Server-seitige Verifikation (CORS-Header, Datei-Upload, JSON-Inhalt) |
|
||
| Playwright | Browser-Automation (Drag-Drop, Canvas-Screenshot, Console-Logs, RAM-Messung) |
|
||
| Chrome DevTools → Performance Monitor | Live RAM/Task-Manager während manuellem Test |
|
||
| `verify-whiteboard-patches.sh` | Regression: bestehende 6 JS-Patches noch aktiv? |
|
||
| Testbilder-Generator | PNGs mit exakten Dimensionen (500×400 bis 8000×6000) |
|
||
|
||
### Testbilder generieren
|
||
|
||
```bash
|
||
ssh orange@niklashmotion.art "python3 -c \"
|
||
import struct, zlib
|
||
def create_png(w, h):
|
||
def chunk(ctype, data):
|
||
c = ctype + data
|
||
crc = struct.pack('>I', zlib.crc32(c) & 0xffffffff)
|
||
return struct.pack('>I', len(data)) + c + crc
|
||
sig = b'\\\\x89PNG\\\\r\\\\n\\\\x1a\\\\n'
|
||
ihdr = chunk(b'IHDR', struct.pack('>IIBBBBB', w, h, 8, 2, 0, 0, 0))
|
||
raw = b''
|
||
for y in range(h):
|
||
raw += b'\\\\x00' + bytes([(x+y) % 256 for x in range(w*3)])
|
||
idat = chunk(b'IDAT', zlib.compress(raw))
|
||
iend = chunk(b'IEND', b'')
|
||
return sig + ihdr + idat + iend
|
||
|
||
sizes = [(500, 400, 'small'), (2000, 1500, 'medium'), (5000, 3750, 'large'), (8000, 6000, 'xl')]
|
||
for w, h, label in sizes:
|
||
with open(f'/tmp/test-{label}-{w}x{h}.png', 'wb') as f:
|
||
f.write(create_png(w, h))
|
||
print(f'Created test-{label}-{w}x{h}.png')
|
||
\""
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 0: Baseline messen
|
||
|
||
**Ziel:** Aktuellen RAM-Verbrauch und Bildgrößen dokumentieren, um Verbesserung zu quantifizieren.
|
||
|
||
```bash
|
||
# 0.1 Bestehende Patches verifizieren
|
||
ssh orange@niklashmotion.art \
|
||
"bash /opt/data/skills/devops/whiteboard-patches/scripts/verify-whiteboard-patches.sh"
|
||
|
||
# 0.2 RAM vor/nach Board-Öffnung (Chrome Task-Manager Shift+Esc)
|
||
|
||
# 0.3 Board-JSON-Größe: 1 Bild 2000×1500px → dataURL-Länge messen
|
||
```
|
||
|
||
**Erwartet:** 2000×1500px → ~12 MB Base64 · 5000×3750px → ~70 MB Base64 · 3 große Bilder → ~200 MB RAM → OOM-Risiko
|
||
|
||
> ### 🚦 GATE Phase 0
|
||
> - [ ] `verify-whiteboard-patches.sh` zeigt alle 6 Patches als aktiv
|
||
> - [ ] RAM-Messung dokumentiert (Baseline)
|
||
> - [ ] Testbilder existieren auf orange-desktop unter `/tmp/test-*.png`
|
||
>
|
||
> **Erst wenn alle 3 Checks grün sind → weiter zu Phase 1.**
|
||
|
||
---
|
||
|
||
## Phase 1: CORS + WebDAV-Zugriff
|
||
|
||
### 1.1 Whiteboard-Assets-Ordner anlegen
|
||
|
||
```bash
|
||
source /opt/data/home/.hermes/nextcloud.env
|
||
curl -s -u "$NEXTCLOUD_USER:$NEXTCLOUD_TOKEN" -X MKCOL \
|
||
"$NEXTCLOUD_URL/remote.php/dav/files/$NEXTCLOUD_USER/WhiteboardAssets"
|
||
```
|
||
|
||
### 1.2 CORS für Bild-URLs aktivieren
|
||
|
||
Damit der Browser Bilder cross-origin laden kann:
|
||
|
||
```nginx
|
||
# In /etc/nginx/sites-available/nextcloud.conf
|
||
location ~ \.(png|jpg|jpeg|gif|webp|svg)$ {
|
||
add_header Access-Control-Allow-Origin "*";
|
||
}
|
||
```
|
||
|
||
Nginx reload: `sudo nginx -s reload`
|
||
|
||
### 1.3 Upload-Test
|
||
|
||
```bash
|
||
source /opt/data/home/.hermes/nextcloud.env
|
||
curl -s -u "$NEXTCLOUD_USER:$NEXTCLOUD_TOKEN" -X PUT \
|
||
--data-binary @/tmp/test-small-500x400.png \
|
||
"$NEXTCLOUD_URL/remote.php/dav/files/$NEXTCLOUD_USER/WhiteboardAssets/test.png"
|
||
```
|
||
|
||
> ### 🚦 GATE Phase 1
|
||
> - [ ] `curl -sI "$URL" | grep "Access-Control-Allow-Origin"` → `*`
|
||
> - [ ] Upload per curl erfolgreich (HTTP 201)
|
||
> - [ ] Download per Browser möglich (kein CORS-Error in Console)
|
||
> - [ ] Playwright: `new Image()` mit crossOrigin lädt korrekt, `naturalWidth === 500`
|
||
>
|
||
> **Erst wenn alle 4 Checks grün sind → weiter zu Phase 2.**
|
||
|
||
---
|
||
|
||
## Phase 2: Import-Handler patchen
|
||
|
||
### 2.1 File-Drop-Handler in NcSelect finden
|
||
|
||
Im `NcSelect-CknHatsl.chunk.mjs` den Callback identifizieren, der aktuell `reader.readAsDataURL()` aufruft.
|
||
|
||
### 2.2 Durch WebDAV-Upload ersetzen
|
||
|
||
```javascript
|
||
// STATT: reader.readAsDataURL(file) → dataURL
|
||
// NEU:
|
||
async function uploadToNextcloud(file, fileId) {
|
||
const ext = file.name.split('.').pop();
|
||
const url = `/remote.php/dav/files/${userId}/WhiteboardAssets/${fileId}.${ext}`;
|
||
await fetch(url, { method: 'PUT', body: file, credentials: 'include' });
|
||
return `/remote.php/dav/files/${userId}/WhiteboardAssets/${fileId}.${ext}`;
|
||
}
|
||
```
|
||
|
||
### 2.3 Thumbnail parallel generieren
|
||
|
||
```javascript
|
||
// 256px Thumbnail, ~5 KB
|
||
const canvas = document.createElement('canvas');
|
||
const ctx = canvas.getContext('2d');
|
||
const scale = Math.min(256 / img.width, 256 / img.height);
|
||
canvas.width = img.width * scale;
|
||
canvas.height = img.height * scale;
|
||
ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
|
||
const thumbDataURL = canvas.toDataURL('image/jpeg', 0.7);
|
||
```
|
||
|
||
### 2.4 File-Objekt anpassen
|
||
|
||
```javascript
|
||
// fileObject speichert URL statt dataURL
|
||
fileObject.url = uploadedUrl;
|
||
fileObject.thumbUrl = thumbDataURL;
|
||
fileObject.width = img.naturalWidth;
|
||
fileObject.height = img.naturalHeight;
|
||
// fileObject.dataURL = undefined (nicht mehr setzen!)
|
||
```
|
||
|
||
> ### 🚦 GATE Phase 2 (Playwright-Test)
|
||
> ```javascript
|
||
> // test-phase2.js — muss alle Checks bestehen:
|
||
> const checks = {
|
||
> hasUrl: !!file?.url, // ← Bild hat URL
|
||
> hasThumbUrl: !!file?.thumbUrl, // ← Thumbnail generiert
|
||
> noDataUrl: !file?.dataURL, // ← KEIN 50MB Base64 mehr
|
||
> ramDelta: ramAfter - ramBefore, // ← < 5 MB (statt 50 MB)
|
||
> noErrors: errors.length === 0, // ← Kein fileTooBig, kein CORS
|
||
> };
|
||
> // ALLE müssen true sein.
|
||
> ```
|
||
>
|
||
> - [ ] `checks.hasUrl === true`
|
||
> - [ ] `checks.hasThumbUrl === true`
|
||
> - [ ] `checks.noDataUrl === true`
|
||
> - [ ] `checks.ramDelta < 5 * 1024 * 1024` (5 MB)
|
||
> - [ ] `checks.noErrors === true`
|
||
> - [ ] Board-JSON via curl: enthält `"url"`, NICHT `"dataURL"`
|
||
> - [ ] `verify-whiteboard-patches.sh` zeigt alle 6 Patches weiterhin aktiv
|
||
>
|
||
> **Erst wenn alle 7 Checks grün sind → weiter zu Phase 3.**
|
||
|
||
---
|
||
|
||
## Phase 3: Excalidraw-Rendering patchen (LOD)
|
||
|
||
### 3.1 File-Objekt-Schema erweitern
|
||
|
||
Im `percentages-BXMCSKIN-D6x-nnv3.chunk.mjs`:
|
||
- `url` als neues Feld im File-Objekt akzeptieren
|
||
- `dataURL` als optional/Fallback behandeln
|
||
|
||
### 3.2 Lazy-Loading im Renderer
|
||
|
||
```javascript
|
||
// PSEUDO-CODE
|
||
if (file.url && !imageLoaded) {
|
||
// Thumbnail sofort rendern
|
||
ctx.drawImage(thumbnailImg, x, y, w, h);
|
||
|
||
// Zoom > 1.5 → Vollbild nachladen
|
||
if (zoom > 1.5 && !fullImageLoading) {
|
||
fullImageLoading = true;
|
||
const img = new Image();
|
||
img.crossOrigin = 'anonymous';
|
||
img.src = file.url;
|
||
img.onload = () => {
|
||
file._fullImageLoaded = true;
|
||
fullImageLoading = false;
|
||
// Re-render mit Vollbild
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.3 Viewport-Culling
|
||
|
||
```javascript
|
||
function isInViewport(element, scrollX, scrollY, zoom, viewportW, viewportH) {
|
||
const elX = element.x + scrollX;
|
||
const elY = element.y + scrollY;
|
||
return elX + element.width * zoom > -viewportW/2
|
||
&& elX < viewportW + viewportW/2
|
||
&& elY + element.height * zoom > -viewportH/2
|
||
&& elY < viewportH + viewportH/2;
|
||
}
|
||
```
|
||
|
||
> ### 🚦 GATE Phase 3 (Playwright-Test)
|
||
> ```javascript
|
||
> // test-phase3.js — Board mit 10 Bildern:
|
||
> const state = {
|
||
> ramAllThumbnails: performance.memory.usedJSHeapSize, // ← < 100 MB
|
||
> fullResCount: countWhere(files, f => f._fullImageLoaded), // ← 0 (nur Thumbnails)
|
||
> };
|
||
> // Reinzoomen auf Bild #1 (zoom = 2.0):
|
||
> const afterZoom = {
|
||
> fullResCount: countWhere(files, f => f._fullImageLoaded), // ← 1–3 (sichtbare)
|
||
> thumbnailCount: countWhere(files, f => !f._fullImageLoaded), // ← 7–9
|
||
> };
|
||
> // Rauszoomen (zoom = 0.5):
|
||
> const afterUnload = {
|
||
> ramAfter: performance.memory.usedJSHeapSize, // ← nahe ramAllThumbnails
|
||
> };
|
||
> ```
|
||
>
|
||
> - [ ] RAM 10 Thumbnails < 100 MB
|
||
> - [ ] Vor Zoom: 0 Vollbilder geladen
|
||
> - [ ] Nach Zoom 2.0×: 1–3 Vollbilder geladen, Rest Thumbnails
|
||
> - [ ] Nach Zoom 0.5×: RAM sinkt (Vollbilder entladen)
|
||
> - [ ] Kein visuelles Flackern bei Thumbnail→Vollbild-Wechsel
|
||
> - [ ] `verify-whiteboard-patches.sh` weiterhin grün
|
||
>
|
||
> **Erst wenn alle 6 Checks grün sind → weiter zu Phase 4.**
|
||
|
||
---
|
||
|
||
## Phase 4: Migration + Stress-Test
|
||
|
||
### 4.1 Bestehende Boards migrieren
|
||
|
||
```javascript
|
||
// Beim Öffnen: dataURL → Blob → WebDAV-Upload → url setzen
|
||
for (const [fileId, file] of Object.entries(files)) {
|
||
if (file.dataURL && !file.url) {
|
||
const blob = dataURLtoBlob(file.dataURL);
|
||
const url = await uploadToNextcloud(blob, fileId);
|
||
file.url = url;
|
||
file.thumbUrl = await generateThumbnail(blob);
|
||
delete file.dataURL;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.2 50-Bilder-Stress-Test
|
||
|
||
```javascript
|
||
// Playwright: 50 Bilder nacheinander importieren
|
||
for (let i = 0; i < 50; i++) {
|
||
await page.dropFile('canvas', '/tmp/test-medium-2000x1500.png');
|
||
await page.waitForTimeout(500);
|
||
}
|
||
const ram = await page.evaluate(() => performance.memory.usedJSHeapSize);
|
||
// Speichern + neu laden + Prüfen: kein Datenverlust
|
||
```
|
||
|
||
> ### 🚦 GATE Phase 4
|
||
> - [ ] Bestehendes Board mit dataURL-Bildern öffnet OHNE Fehler
|
||
> - [ ] Nach Migration: Board-JSON via curl → alle Bilder haben `url`, keine `dataURL`
|
||
> - [ ] 50 Bilder importiert → RAM < 200 MB
|
||
> - [ ] Board speichern + neu laden → alle 50 Bilder sichtbar (Thumbnails)
|
||
> - [ ] Netzwerk-Fehler-Simulation: Bild lädt auch ohne WebDAV (Thumbnail-Fallback)
|
||
> - [ ] `verify-whiteboard-patches.sh` weiterhin grün
|
||
|
||
---
|
||
|
||
## Entscheidungen (vor Implementierung zu klären)
|
||
|
||
| Frage | Optionen |
|
||
|---|---|
|
||
| Wo Bilder speichern? | A) `/WhiteboardAssets/` (eigener Ordner) · B) gleicher Ordner wie Whiteboard-Datei |
|
||
| Thumbnail-Größe? | 256px (5 KB) vs. 512px (12 KB) |
|
||
| Lazy-Load-Zoom-Schwelle? | 1.0× (immer lazy) vs. 1.5× vs. 2.0× |
|
||
| Auth-Methode im JS? | A) Session-Cookie · B) App-Passwort hardcoded |
|
||
| Migration automatisieren? | Ja (beim Öffnen) vs. Nein (nur neue Bilder) |
|
||
|
||
---
|
||
|
||
## Aufwandsschätzung
|
||
|
||
| Phase | Aufwand | Tests |
|
||
|---|---|---|
|
||
| Phase 1: CORS + WebDAV | 30 min | 4 Checks |
|
||
| Phase 2: Import-Handler | 2–4 h | 7 Checks |
|
||
| Phase 3: Rendering/LOD | 4–8 h | 6 Checks |
|
||
| Phase 4: Migration + Stress | 1–2 h | 6 Checks |
|
||
| **Total** | **1–2 Tage** | **23 Gates** |
|
||
|
||
---
|
||
|
||
## Failure Modes (worauf achten)
|
||
|
||
| Symptom | Ursache | Prüfung |
|
||
|---|---|---|
|
||
| `hasUrl = false` nach Import | Import-Patch nicht aktiv | Console-Log auf Fehler |
|
||
| CORS-Error in Console | Nginx-CORS-Header fehlt | `curl -sI \| grep Access-Control` |
|
||
| Bild nicht sichtbar | `crossOrigin` nicht gesetzt | `img.crossOrigin = 'anonymous'` |
|
||
| RAM steigt trotz URLs | Vollbild sofort geladen | Viewport-Check debuggen |
|
||
| Board crasht beim Öffnen | Migration schlägt fehl | try/catch + Fallback auf dataURL |
|
||
| Browser-Cache zeigt alte JS | Cachebuster nicht erhöht | `curl -sI \| grep cachebuster` |
|
||
| Bestehende Patches kaputt | Seiteneffekte in Bundle | `verify-whiteboard-patches.sh` |
|