@studio/core

Gemeinsames technisches Fundament der Astro-Websites des Studios.

core wird nie direkt bearbeitet, um eine einzelne Site zu aendern. Alles, was nur eine Site betrifft, gehoert in deren packages/ui. Faustregel: taucht in einer Datei hier ein Markenname, eine Domain oder eine Farbe auf, ist sie am falschen Ort.

Gehoert das hierher?

Die Faustregel oben haelt core sauber. Die Umkehrung faellt seltener auf: Code, der technisch generisch ist, aber trotzdem nur in einer Site liegt - meist, weil er dort im Zuge einer Funktion fuer genau diese Site entstanden ist, ohne dass jemand bewusst "das ist eigentlich core" gedacht hat. Zwei Fragen entscheiden:

1. Braeuchte site-kollege exakt diese Datei, unveraendert bis auf Konfiguration?
2. Liest man die Datei durch, ohne auf einen Markennamen, eine Domain oder eine Farbe zu stossen?

Beide Ja -> gehoert nach core, auch wenn aktuell nur eine Site sie nutzt. Beispiele:

Gehoert in core	Gehoert in die Site
Bildoptimierung, ResponsiveImage, Social-Vorschaubild (reine Technik)	Logo, Firmenadresse, Kontaktdaten (src/lib/company.ts)
A11y-Panel-Verhalten: Schriftgroesse/Kontrast/Bewegung umschalten, Zustand persistieren	A11y-Panel-Optik: Icons, Layout, Beschriftungstexte (packages/ui)
Eine Funktion, die aus einer Liste von Namen ein AdministrativeArea-Schema baut	Die Liste der bedienten Regionen selbst - echte Standortdaten
Deploy-Workflow als Kopiervorlage (bewusst kein Import, s.u.)	Eine tatsaechlich abweichende Auslieferung (z. B. eigener VPS statt Webspace)

packages/ui ist fuer die visuelle Identitaet einer Site reserviert - nicht als genereller Auffangort fuer alles, was diese Site zuerst gebraucht hat. Ein Astro-Component oder Skript ohne jeden Markenbezug dort ist ein Warnsignal.

Im Zweifel lieber einmal zu oft fragen "braeuchte die naechste Site das auch?", als eine zweite Site zwingen, denselben Code zu duplizieren.

Inhalt

Pfad	Zweck	Nutzung
layouts/BaseLayout.astro	HTML-Huelle, Meta-Tags, SEO, Open Graph, A11y-Preferences	Import
components/ResponsiveImage.astro	<picture> mit AVIF/WebP aus dem Bild-Manifest	Import
components/A11yControls.astro	Bedienung des A11y-Panels (Schrift, Kontrast, Bewegung); erwartet IDs/Data-Attribute aus der site-eigenen Markup, siehe Kopfkommentar	Import
components/SlideDeck.astro	Folienpraesentation zum Einbetten in Seiten: Einzelfolien-Ansicht, Pfeiltasten, Wischen, Vollbild, Deep-Link #id-nr; ohne JS und im Druck stehen alle Folien untereinander. Nur Struktur-CSS (Spezifitaet 0), Optik ueber --slide-* und site-eigenes CSS	Import
components/Slide.astro	Einzelne Folie (Props title/body/image/layout oder Slot), wird von SlideDeck aus Daten erzeugt oder von Hand im Slot gesetzt	Import
lib/slides.ts	Typ SlideData fuer Folien aus CMS-Daten	Import
lib/rich-text.ts	Renderer fuer Markdown-Strings aus dem CMS	Import
lib/social-image.ts	Loest og:image/twitter:image auf die 1200x630-Variante aus dem Bild-Manifest auf	Import
lib/image-manifest.ts	Gemeinsames Lesen von .astro/image-manifest.json fuer die drei Bausteine oben	Import
scripts/optimize-images.mjs	Erzeugt AVIF/WebP/Social-Varianten aus public/images/ und original-images/, schreibt das Manifest	CLI (bin: studio-optimize-images), benoetigt sharp als eigene Abhaengigkeit der Site
scripts/rehype-responsive-images.mjs	Ersetzt <img> in CMS-Markdown durch dieselben Manifest-Varianten	Import (Markdown-Plugin)
astro-preset/	Gemeinsame Astro- und TS-Basiskonfiguration	Import
decap/config.template.yml	Decap-Konfiguration fuer eine neue Site	Kopiervorlage
decap/slides.template.yml	Decap-Feld slides (Liste) zum Einfuegen in eine Collection	Kopiervorlage
decap/admin.template.html	Decap-Einstiegspunkt /admin/	Kopiervorlage
ci/deploy.forgejo.yml	Build- und Deploy-Workflow	Kopiervorlage

Kopiervorlagen sind bewusst keine Imports: Decaps config.yml und Forgejos Workflow-Dateien sind statische Dateien, die zur Laufzeit bzw. vom Runner an einem festen Pfad erwartet werden. Ein Import waere hier eine Abstraktion ohne Gegenwert.

Einbindung in eine Site

{
  "dependencies": {
    "@studio/core": "git+https://FORGEJO_HOST/OWNER/core.git#v1.0.0"
  }
}

Version wird ueber Git-Tags gefuehrt (Variante A der Architekturskizze). Ein Update in einer Site heisst: Tag in der package.json hochsetzen, npm install.

Tags werden von git push nicht automatisch mitgeschickt. Nach einem neuen Tag also git push origin main --follow-tags - sonst schlaegt npm install in den Sites mit "The git reference could not be found" fehl.

Damit npm ci in der CI ohne Zugangsdaten funktioniert, muss dieses Repo auf der Forgejo-Instanz oeffentlich lesbar sein. Es enthaelt keine Geheimnisse. Bliebe es privat, braeuchte jede Site zusaetzlich einen Read-Token im Deploy-Workflow, etwa per git config --global url."https://<token>@host/".insteadOf "https://host/" vor dem npm ci.

Versionierung

Git-Tags, semantisch:

• patch - Fehlerbehebung, Ausgabe unveraendert
• minor - neue optionale Prop oder neuer Slot, rueckwaertskompatibel
• major - geaenderte oder entfernte Prop, geaenderte HTML-Ausgabe

Nach jedem Tag: in den Site-Repos die Referenz hochsetzen und einen Build gegenpruefen, bevor deployt wird.