Web-Skript

Status: Entwurf

Vorschläge von Claude – nicht verbindlich, bis Daniel sie freigibt.

Wie das Review-Overlay ohne Build-Schritt auf jeder Website läuft. Was Nutzende sehen: Web-Skript.

Heute hängt das Overlay in vier Dingen vom Sphinx-Build ab: den Klassen dw-el-<n> und der Zuordnung #deciwa-page auf jeder Seite, elements.json (Text und Fingerprint jedes Elements), config.json (Review-Regeln) und der Quelldatei der Seite. Das Web-Skript findet all das im Browser.

Vorschlag: Das Skript zu laden genügt – deciwa erscheint immer PROP_WEB_ONE_LINE
status: approved
refines: DEC_INTEGRATIONS
refined by: PROP_OVERLAY_PARTS, PROP_WEB_SOURCE, Q_WEB_STEP

Ein einzelnes <script src=".../deciwa.js" defer> ohne Attribute zeigt den deciwa-Button auf jeder Seite und funktioniert offline im Browser. Zum Ausprobieren braucht es keine Konfigurationsdatei, keinen Build-Schritt und keine Seitenzuordnung. Alles andere ist ein optionales Attribut (Web-Skript). Entschieden: Ein Script-Tag genügt – dec... (DEC_WEB_ONE_LINE). data-activate="param" ist ein Opt-in für öffentliche Websites: deciwa lädt dann nur, wenn die Adresse ?deciwa enthält.
Vorschlag: Das Overlay ist aufgeteilt in Elementquelle, Speicher und Oberfläche PROP_OVERLAY_PARTS
status: draft
refines: DEC_CLI_MASTER, PROP_WEB_ONE_LINE
refined by: PROP_WEB_BUNDLE

Part

Variants

element source

Sphinx (#deciwa-page from the build) · DOM scan (the HTML adapter below)

store

deciwa serve · offline in the browser · a remote deciwa server (later)

UI

card, panel, bars, guided review – unchanged

Die Teile treffen sich an kleinen Schnittstellen: eine Elementquelle liefert die Elementliste der Seite, ein Speicher beantwortet die Aufrufe, die das Overlay heute macht (/api/page, /api/annotate, …). Die Sphinx-Integration funktioniert unverändert weiter und ist der Test, dass die Aufteilung nichts kaputt gemacht hat.
Vorschlag: Ein Bundle, gebaut mit esbuild, die Oberfläche in einem Shadow DOM PROP_WEB_BUNDLE
status: draft
refines: PROP_OVERLAY_PARTS
refined by: PROP_WEB_HOSTING

Die Quellen des Overlays werden ES-Module in packages/ui/js/. esbuild (kein Framework) baut zwei Dateien:

  • deciwa-overlay.js – für das Python-Paket und die Sphinx-Erweiterung, wie heute,

  • deciwa.js – das Web-Skript: eine Datei, CSS und deciwa-Bild eingebettet.

Auf fremden Seiten lebt die Oberfläche in einem Shadow DOM, damit das CSS der Seite das Overlay nicht kaputt machen und das CSS des Overlays die Seite nicht verändern kann.
Vorschlag: Das Web-Skript wird mit der Doku unter einem versionierten Pfad gehostet PROP_WEB_HOSTING
status: approved
refines: PROP_WEB_BUNDLE

Der Docs-Workflow veröffentlicht deciwa.js unter https://deciwa.danwos.dev/js/<release>/deciwa.js, wobei das Release Major und Minor aus packages/ui/package.json ist (0.2); /js/latest/deciwa.js folgt dem neuesten Release. In der Prototyp-Phase überschreibt jedes Deployment das eine veröffentlichte Release – die Release-Nummer wird noch nicht erhöht. Sobald Releases erhöht werden, bleiben die Builds früherer Releases erhalten, damit sich ein veröffentlichtes Release nie ändert und Websites es mit einem Subresource-Integrity-Hash pinnen können. Entschieden: Das Web-Skript wird mit der... (DEC_WEB_HOSTING).
Vorschlag: Eine Seite wird erkannt an ihrem Meta-Tag, einer Zuordnungsregel oder ihrer Adresse PROP_WEB_SOURCE
status: approved
refines: DEC_DECIWA_FOLDER, PROP_WEB_ONE_LINE
refined by: PROP_WEB_FILES, PROP_WEB_INDEX

Die Quelle einer Seite ist, in dieser Reihenfolge:

  1. <meta name="deciwa-source" content="…"> auf der Seite,

  2. die erste passende Regel aus [web].sources in .deciwa/config.toml (von der CLI beim Import angewendet, siehe Dateiformat),

  3. der Fallback, der immer funktioniert: web:<host><path>, z. B. web:danwos.dev/services/. Query und Fragment fallen weg, index.html und ein fehlender Schrägstrich am Ende zählen als dieselbe Seite.

Der Browser speichert immer die Adresse; eine später ergänzte Zuordnung verschiebt die Annotationen in die Quelldatei, ohne eine zu verlieren. Entschieden: Seiten Quelldateien zuzuord... (DEC_WEB_SOURCE).
Vorschlag: Der Browser merkt sich die Elemente jeder besuchten Seite PROP_WEB_INDEX
status: draft
refines: PROP_WEB_SOURCE

Ohne Build gibt es keine elements.json. Das Web-Skript speichert die Elementliste jeder gesehenen Seite (Selektor, Art, Label, Text, Fingerprint) im Browser, damit das Projekt-Panel alle besuchten Seiten auflistet und veraltete Elemente gefunden werden, wenn eine Seite wieder geöffnet wird. Ein Export trägt diesen Index mit, damit die CLI Web-Annotationen ohne HTML-Adapter in Python auflösen kann. sitemap.xml zu lesen, um alle Seiten vorab aufzulisten, kann später kommen.
Vorschlag: Seiten, die sich nach dem Laden ändern, werden erneut gescannt PROP_WEB_RESCAN
status: draft
refines: PROP_DOM_ADAPTER

Das Skript scannt erneut nach clientseitiger Navigation (popstate, astro:page-load, turbo:load) und, gedrosselt, wenn ein MutationObserver Änderungen innerhalb der Review-Wurzel sieht. Offene Karten bleiben über den Selektor an ihrem Element.
Frage: Wann kommt das Web-Skript? Q_WEB_STEP
status: answered
to: Daniel
refines: PROP_WEB_ONE_LINE

Vorschlag war: direkt nach dem Prototyp, vor VS Code – der erste echte Einsatz ist die danwos-Website, und die Chrome-Erweiterung baut darauf auf. Von Daniel beantwortet (2026-10-20): ja, als 0.2 – siehe Das Web-Skript kommt als 0.... (DEC_WEB_SCRIPT_FIRST).

Erster Einsatz: die danwos-Website

  • src/layouts/Base.astro bekommt den Script-Tag mit data-activate="param".

  • Das Website-Repository bekommt .deciwa/config.toml mit [web].sources für seine Content Collections.

  • Das selbstgebaute Feedback-Tool in der Astro-Dev-Toolbar (.feedback/feedback.json) wird ersetzt, sobald deciwa dort funktioniert.