From 4c96c4ac2b312f7a29285ad7e87461bfdd6ba08a Mon Sep 17 00:00:00 2001 From: ShadowDara <128976697+ShadowDara@users.noreply.github.com> Date: Wed, 9 Sep 2026 20:59:59 +0200 Subject: [PATCH 01/76] Create AGENTS.md --- finder-template-generator-ssg/AGENTS.md | 409 ++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 finder-template-generator-ssg/AGENTS.md diff --git a/finder-template-generator-ssg/AGENTS.md b/finder-template-generator-ssg/AGENTS.md new file mode 100644 index 00000000..86bcbb41 --- /dev/null +++ b/finder-template-generator-ssg/AGENTS.md @@ -0,0 +1,409 @@ +# AGENTS — Pages SSG Plugin + JSX Runtime + +Dieses Dokument beschreibt den eigenen Vite-Plugin-Stack in diesem Projekt: das Seiten-Plugin, die JSX-Runtime und den Ablauf, wie aus `.tsx`/`.jsx`-Dateien statische Seiten entstehen. + +Ziel: + +- versteht, wie Seiten in `pages/` automatisch erkannt werden +- erklärt, wie die JSX-Runtime HTML erzeugt +- zeigt, was man damit praktisch bauen kann +- macht die Verbindung zwischen Page-Route, `window.PAGE_ID` und dem Render-Export klar + +--- + +## 1) Überblick + +Das Projekt hat ein eigenes SSG-/Pages-Plugin in: + +- `pages-ssg-plugin.ts` +- `src/jsx-runtime.ts` +- `src/main.ts` + +Das Plugin scannt Dateien im `pages/`-Ordner, baut daraus eine virtuelle `virtual:pages`-Map und erzeugt dabei per Route eine eigene HTML-Datei. + +Wichtig: + +- Jede Seite ist normalerweise eine Datei unter `pages/` +- Jede Seite exportiert eine Standardfunktion wie `default function render(el) { ... }` +- Diese Funktion bekommt ein `HTMLDivElement` und schreibt dort den gerenderten Inhalt hinein +- Die erzeugten Inhalte sind keine React-Komponenten, sondern HTML-Strings, die von der eigenen JSX-Runtime gebaut werden + +--- + +## 2) Wie das Plugin funktioniert + +### 2.1 Seiten entdecken + +Im Plugin `pages-ssg-plugin.ts` läuft die Logik grob so: + +1. `scanPages()` liest alle Dateien im `pages/`-Verzeichnis +2. `scanDocs()` liest Markdown-Dateien aus `docs/` +3. `preparePages()` sammelt alle Seiten zu einer Liste +4. `createVirtualModule()` erzeugt eine virtuelle Module-Datei mit einer Map wie: + +```ts +export const pages = { + home: { id: "home", type: "component", load: () => import("/pages/home.tsx"), styles: [...] }, + viewer: { id: "viewer", type: "component", load: () => import("/pages/viewer.tsx"), styles: [...] }, +}; +``` + +Das ist wichtig, weil `src/main.ts` nicht manuell jede Seite importiert, sondern genau diese virtuelle Map verwendet. + +### 2.2 Route + PAGE_ID + +Die generierte HTML-Seite setzt in der Vorlage ein globales Fenster-Flag: + +```html + +``` + +Dann startet `src/main.ts`: + +```ts +const id = window.PAGE_ID; +const page = pages[id]; +``` + +Wenn die Seite gefunden wird, lädt sie dynamisch: + +```ts +const module = await page.load(); +await module.default(app, page.data); +``` + +Das heißt: die HTML-Seite selbst ist nur das Shell-HTML; die eigentliche Seite kommt aus der Page-Datei. + +--- + +## 3) Wie JSX-Seiten funktionieren + +### 3.1 Die JSX-Factory + +Die eigentliche JSX-Erzeugung geschieht in `src/jsx-runtime.ts`: + +```ts +export function jsx(tag, props, ...children) { ... } +export function Fragment(props) { ... } +export function raw(value) { ... } +``` + +Die zentrale Idee ist: Statt React zu verwenden, erzeugt die Funktion direkt ein HTML-Fragment als String. + +Beispiel: + +```tsx +return ( +
+

Finder

+ +
+); +``` + +wird intern ungefähr so verarbeitet: + +```ts +jsx( + "header", + { class: "nav" }, + jsx("h1", null, "Finder"), + jsx("button", null, "Download"), +); +``` + +und diese `jsx`-Funktion baut daraus einen String wie: + +```html +
+

Finder

+ +
+``` + +### 3.2 Escaping + +Die Runtime escaped Text und Attribute automatisch: + +- `&` -> `&` +- `<` -> `<` +- `>` -> `>` +- `"` -> `"` +- `'` -> `'` + +Damit werden User-Eingaben sicher in HTML gebracht, statt ungefiltert eingefügt zu werden. + +Das geschieht in `escapeText()` und `escapeAttribute()`. + +### 3.3 Raw HTML + +Manchmal will man bewusst echten HTML-Inhalt einbauen, z. B. CSS- oder JS-Code, ohne Escaping. Dafür gibt es: + +```ts +export function raw(value: string): HtmlValue; +``` + +Das ist nützlich für vertrauenswürdigen Inhalt, etwa: + +```tsx + +``` + +Vorsicht: `raw()` sollte nur für interne, kontrollierte Strings verwendet werden, nicht für beliebige Nutzerdaten. + +### 3.4 Boolean-Attribute + +Die Runtime behandelt HTML-Boolean-Attribute wie `disabled`, `checked`, `required`, `hidden`, etc. speziell: + +```tsx + +``` + +Ergebnis: + +```html + +``` + +Nur wenn der Wert `true` ist, erscheint das Attribut; bei `false` oder `null` fällt es weg. + +### 3.5 `Fragment` + +Es gibt ein `Fragment`-Konstrukt, damit mehrere Ebenen ohne extra Wrapper zurückgegeben werden können: + +```tsx +function App() { + return ( + +