gulp-mu-css 2.0.0

package/docs/manual/microCSS-Handbuch.md

@@ -0,0 +1,774 @@
+# Einführung
+
+µCSS ist ein Node-Modul zur Verarbeitung von CSS-Dateien und zur Generierung von Web-Grafiken. Dieses Handbuch beschreibt die Version 2 — den Node-basierten Nachfolger des 2013 eingeführten, Adobe-Photoshop-basierten µCSS 1: Aus erweiterten Quell-Stylesheets (`.µ.css`) und den Medienquellen (z. B. PSD-Entwürfen) entstehen per Gulp die fertigen Skin-Dateien — Standard-CSS plus alle benötigten Bilder, Sprites, Cursor, Fonts und Sounds. Die Bilderzeugung übernimmt das Schwester-Modul µPS, das die alten PS-Plugins ohne Adobe-Abhängigkeit nachbildet.
+
+Da das µ-Zeichen in Paket- und Repository-Namen (npm, git) immer wieder Probleme bereitet, lauten die technischen Namen `gulp-mu-css` und `gulp-mu-ps` — µCSS und µPS sind die Anzeigenamen.
+
+Die wichtigsten Eigenschaften von µCSS 2:
+
+- Quell-Stylesheets bleiben **syntaktisch valides CSS** — Editoren, Linter und Diff-Werkzeuge funktionieren unverändert.
+- **Benannte CSS-Eigenschaften** über Skin-Variablen (`$.name`).
+- **Berechnung von CSS-Werten durch JavaScript-Ausdrücke** direkt im Stylesheet — ohne Ersatzzeichen wie `«»¡`.
+- **Mehrere Layouts (Skins)** aus denselben Quellen über Manifest-Dateien.
+- **Automatische Sprite-Atlas-Generierung** inklusive Retina-Varianten (`@2x`) und `image-set()`.
+- **Cursor-Verwaltung** mit Hotspot, Fallback und Retina-Unterstützung.
+- **Vorladen von CSS-Bildern** über eine generierte Preload-Regel.
+- **Automatische Bilderzeugung** aus PSD-Entwürfen (Buttons, Icons, App-Icons, Animations-Strips) via µPS.
+- **Inkrementeller Build mit Cache** — nur Geändertes wird neu generiert.
+- **Aussagekräftige Fehlermeldungen** mit Datei, Zeile und Quelltext-Ausschnitt.
+
+Im Gegensatz zu µCSS 1 läuft Version 2 vollständig in Node.js (ab Version 18) und benötigt weder Photoshop noch andere Adobe-Produkte. Die Build-Steuerung erfolgt über Gulp oder direkt über die Node-API.
+
+## Einordnung: Warum µCSS?
+
+Für fast jeden Teilaspekt von µCSS existiert ein etabliertes Einzelwerkzeug — aber kein System, das alles bündelt:
+
+| Funktion | Nächstes existierendes Pendant | Was dort fehlt |
+| :--- | :--- | :--- |
+| Variablen & Farbfunktionen | Sass/LESS (`lighten()`, `mix()`), natives CSS (`color-mix()`, Custom Properties) | kein eingebettetes JavaScript |
+| JavaScript in CSS-Werten | postcss-functions (registrierte JS-Funktionen als CSS-Funktionen) | nur benannte Funktionen — keine freien Ausdrücke, keine Direktiven mit Regel-/Dokument-Zugriff |
+| Stylesheets mit voller JS-Power | vanilla-extract (Stylesheets-in-TypeScript) | umgekehrter Ansatz — das normale CSS-Format geht verloren |
+| Sprite-Atlas aus CSS-Referenzen | spritesmith-Familie, postcss-sprites | weitgehend eingefroren, kein Retina-`image-set`-Workflow, kein gemeinsamer Cache |
+| Bilderzeugung aus PSD-Entwürfen | nur Bausteine (`ag-psd`, Asset-Export aus Figma/Sketch) | kein Serien-Rendering mit Ebenenstil-Übertragung, nicht mit dem CSS-Build gekoppelt |
+| Cursor, Preload, Skin-Manifest, Medien-Cache | handgestrickte Build-Skripte | nirgends gebündelt |
+
+Ein Teil der ursprünglichen µCSS-Motivation von 2013 ist heute durch natives CSS gelöst (Custom Properties, `color-mix()`, Nesting) — deshalb verzichtet µCSS 2 bewusst auf LESS-Unterstützung und Vendor-Prefixes. Der verbleibende Kern ist konkurrenzlos: beliebige JavaScript-Ausdrücke im CSS plus Direktiven mit AST-Zugriff, gekoppelt mit Sprite-Atlas inklusive Retina, PSD-Render-Pipeline und inkrementellem Cache, gesteuert über ein Manifest pro Skin. Und da µCSS intern eine PostCSS-Pipeline ist, bleibt das gesamte PostCSS-Ökosystem (cssnano, Stylelint, …) andockbar, statt in Konkurrenz dazu zu stehen.
+
+# Installation und Start
+
+µCSS und µPS sind als npm-Module `gulp-mu-css` und `gulp-mu-ps` verfügbar. Die Installation erfolgt im eigenen Projekt:
+
+```
+npm install gulp-mu-css gulp-mu-ps
+```
+
+µCSS hängt von µPS ab (Atlas- und Bilderzeugung) — nicht umgekehrt. Beide Module sind separat verwendbar.
+
+Der typische Einstieg ist ein Gulp-Task, der ein Skin-Manifest baut:
+
+```js
+// gulpfile.mjs
+import gulp from "gulp";
+import { BuildSkin } from "gulp-mu-css";
+
+export async function SkinStd() {
+	await BuildSkin("skins/src/std.µcss.mjs");
+}
+export function SkinWatch() {
+	gulp.watch(["skins/src/**", "dev/media/final/**"], SkinStd);
+}
+```
+
+Der Aufruf `npx gulp SkinStd` kompiliert den Skin „std" in das Verzeichnis `skins/std/`. `BuildSkin` ist idempotent und cache-gestützt: Ein zweiter Aufruf ohne Änderungen ist nach wenigen Millisekunden fertig (siehe Kapitel „Build-Ablauf").
+
+# Anwendungsfälle
+
+Die folgenden Abschnitte zeigen die typischen Einsatzszenarien — analog zu den Use Cases des alten µCSS-Handbuchs, aber in der neuen Syntax.
+
+## Benannte Eigenschaften (Variablen)
+
+Der einfachste Anwendungsfall: Ein Wert wird einmal im Skin-Manifest benannt und an beliebig vielen Stellen verwendet. Im Manifest:
+
+```js
+// skins/src/std.µcss.mjs
+import { DefineSkin } from "gulp-mu-css";
+
+export default DefineSkin({
+	vars: {
+		textColor: "#ff0000",
+		backColor: "#0000ff"
+	},
+	files: [{ source: "src.µ.css", target: "std.css" }]
+});
+```
+
+Im Quell-Stylesheet `src.µ.css`:
+
+```css
+div.mydiv {
+	padding: 5px;
+	font-size: 24px;
+	color: µ($.textColor);
+	background-color: µ($.backColor);
+	border: 10px µ($.backColor) solid;
+	border-radius: 10px;
+}
+```
+
+Kompiliert nach `std.css`:
+
+```css
+div.mydiv {
+	padding: 5px;
+	font-size: 24px;
+	color: #ff0000;
+	background-color: #0000ff;
+	border: 10px #0000ff solid;
+	border-radius: 10px;
+}
+```
+
+Anders als beim alten µCSS sind keine Platzhalter-Properties und keine `Set*`-Direktiven mehr nötig: Der Wert steht direkt dort, wo er hingehört.
+
+## Berechnungen und Ausdrücke
+
+Der Inhalt von `µ(...)` ist ein beliebiger JavaScript-Ausdruck. Damit sind Berechnungen, Bedingungen und Farboperationen direkt im Stylesheet möglich:
+
+```css
+td.subheadline {
+	border-bottom: 1px dashed µ(Lighten($.selectBaseBrgdColor, 0.7));
+}
+div.panel {
+	padding: µ(Math.floor($.basePadding * 0.2))px;
+	background-color: µ(Alpha($.baseBrgdColor, 0.85));
+	z-index: µ($.PanelZIndex + 10);
+}
+div.hint {
+	color: µ($.darkMode ? "#e0e0e0" : "#202020");
+}
+```
+
+Für Operationen, die mehrere Properties erzeugen oder die Regel als Ganzes verändern, gibt es Direktiven (`-µ:`), zum Beispiel mit eigenen Makro-Funktionen aus dem Manifest:
+
+```css
+div.menu {
+	-µ: Borders($.menuBaseBrgdColor, 1, 0.3, -0.3, -0.3, 0.3);
+}
+```
+
+Die Direktive ruft die Helper-Funktion `Borders` auf, die vier `border-*`-Properties berechnet und in die Regel einfügt (siehe Kapitel „µ-Auswertungskontext").
+
+## Mehrere Layouts über Skin-Manifeste
+
+Das alte Template-Compiling (eine Vorlagen-CSS plus je eine `µ.layout.css` pro Layout) wird durch mehrere Manifeste ersetzt, die sich dieselben `.µ.css`-Quellen teilen:
+
+```js
+// skins/src/layout_a.mjs
+import { DefineSkin } from "gulp-mu-css";
+export default DefineSkin({
+	vars: { textColor: "#ff0000", backColor: "#0000ff" },
+	files: [{ source: "template.µ.css", target: "layout_a.css" }]
+});
+```
+
+```js
+// skins/src/layout_b.mjs
+import { DefineSkin } from "gulp-mu-css";
+export default DefineSkin({
+	vars: { textColor: "#ff00ff", backColor: "#00ff00" },
+	files: [{ source: "template.µ.css", target: "layout_b.css" }]
+});
+```
+
+Jedes Manifest erzeugt ein eigenes Ausgabeverzeichnis (`skins/layout_a/`, `skins/layout_b/`) mit eigener CSS, eigenen Bildern und eigenem Build-Cache. Gemeinsame Variablen lassen sich als normales JavaScript-Modul importieren und in beiden Manifesten verwenden.
+
+## Automatische Sprite-Generierung
+
+Eines der Highlights von µCSS (in Version 1 wie in Version 2) ist die automatische Erzeugung von Sprite-Atlanten. Die Direktive `Sprite(url)` registriert das Bild einer Regel für den Atlas:
+
+```css
+div.loginbutton {
+	display: inline-block;
+	-µ: Sprite("imgs/aqua/but_login_normal.png");
+}
+div.loginbutton:hover {
+	display: inline-block;
+	-µ: Sprite("imgs/aqua/but_login_hover.png");
+}
+div.helpbutton {
+	display: inline-block;
+	-µ: Sprite("imgs/aqua/but_help_normal.png");
+}
+```
+
+Beim Build werden alle registrierten Bilder in ein einziges Atlas-Bild gepackt (`imgs/sprites.png`, dazu `imgs/sprites@2x.png` aus den `@2x`-Quellbildern) und die Regeln umgeschrieben:
+
+```css
+div.loginbutton {
+	display: inline-block;
+	background-image: url(imgs/sprites.png);
+	background-image: image-set(url(imgs/sprites.png)1x, url(imgs/sprites@2x.png)2x);
+	background-repeat: no-repeat;
+	background-position: 0px 0px;
+	width: 55px;
+	height: 55px;
+}
+```
+
+`width`, `height`, `background-position` und `background-repeat` werden automatisch gesetzt; vorhandene Deklarationen dieser Properties in der Regel werden ersetzt. Anders als beim alten µCSS entfallen die Vendor-Prefix-Varianten (`-webkit-image-set` usw.) — alle relevanten Browser unterstützen `image-set()` seit Jahren unprefixt.
+
+Identische Quellbilder teilen sich automatisch eine Atlas-Position (Duplikat-Reduktion). Der Atlas wird nur neu gepackt, wenn sich die Bildmenge oder ein Quellbild geändert hat.
+
+## Bilder vorladen (Preload)
+
+Wichtige Bilder (z. B. Hover-Zustände und Cursor) können beim Laden der Seite vorab geladen werden. µCSS sammelt die Bild-URLs und erzeugt eine Preload-Regel, wenn die Manifest-Option `sprites.preloadRule` gesetzt ist:
+
+```css
+div.csspreload {
+	background-image: url(imgs/sprites.png), url(imgs/general/gui/cursors/zoom.png);
+	display: none;
+}
+```
+
+In der HTML-Seite genügt ein leeres Element mit dieser Klasse:
+
+```html
+<div class="csspreload"></div>
+```
+
+Cursor-Bilder aus den `cursors`-Definitionen werden automatisch in die Preload-Liste aufgenommen.
+
+## Cursor mit Hotspot und Fallback
+
+Cursor werden im Manifest definiert und im Stylesheet per Name verwendet. Definition:
+
+```js
+cursors: [
+	{ name: "zoom", fallback: "zoom-in", image: "imgs/general/gui/cursors/zoom.png", hotspot: [10, 8] },
+	{ name: "wait", fallback: "wait", image: "imgs/general/gui/cursors/wait.png", hotspot: [12, 12] }
+]
+```
+
+Verwendung als Direktive oder als Wertform:
+
+```css
+*.cursor_zoom {
+	-µ: Cursor("zoom");
+}
+a.preview {
+	cursor: µ(Cursor("zoom"));
+}
+```
+
+Die Direktive erzeugt die `url()`-Form mit Hotspot und Fallback sowie — wenn eine `@2x`-Bilddatei existiert — zusätzlich die `image-set()`-Variante:
+
+```css
+*.cursor_zoom {
+	cursor: url(imgs/general/gui/cursors/zoom.png) 10 8, zoom-in;
+	cursor: image-set(url(imgs/general/gui/cursors/zoom.png)1x, url(imgs/general/gui/cursors/zoom@2x.png)2x) 10 8, zoom-in;
+}
+```
+
+## Automatische Bilderzeugung (media-Steps)
+
+Was früher die µCSS-Plugins (ButtonCreator, AppIconMaker, FileCopy) erledigt haben, übernehmen jetzt die `media`-Einträge im Manifest. Sie laufen vor der CSS-Kompilierung und erzeugen bzw. kopieren alle Medien in das Skin-Verzeichnis:
+
+```js
+media: [
+	{ buttonsAndIcons: "dev/media/final/general/gui/panelbuttons.psd", layout: "std", outputDir: "imgs/general/gui/panelbuttons" },
+	{ buttonsAndIcons: "dev/media/final/general/gui/cursors.psd", layout: "std", outputDir: "imgs/general/gui/cursors" },
+	{ appIcons: "dev/media/final/favicon.psd", layout: "std", profiles: ["web"] },
+	{ sequenceStrip: "dev/media/raw/glittery/imgs", outputFile: "imgs/general/gui/glittery/glittery.png" },
+	{ copy: "dev/media/final/general/gui/teaserbgrd.png", to: "imgs/general/gui" },
+	{ copyFolder: "dev/media/final/fonts", to: "fonts" }
+]
+```
+
+- **`buttonsAndIcons`** rendert aus einem geschichteten PSD-Entwurf (Layouts × Icon-Glyphen) komplette Button- und Icon-Serien inklusive `@2x`-Varianten — der Nachfolger des ButtonCreator-Plugins. Die Fülloptionen (Schlagschatten, Verläufe, Schein usw.) werden von microPS nachgebildet.
+
+![Dieselben Icon-Glyphen, gerendert mit zwei Layouts desselben Entwurfsdokuments („alu" und „aqua")](imgs/bc_alu.png)
+
+![](imgs/bc_aqua.png)
+
+  Mit `mode: "topLayerSets"` arbeitet der Step im zweiten Legacy-Modus (`CreateByTopLayerSets`): Statt der Icon×State-Matrix wird **jede direkte Untergruppe der Layout-Gruppe zu genau einem Bild**, benannt nach dem Gruppennamen. Eine `icons`-Gruppe ist hier nicht nötig — typisch für Logos, Animationsframes (z. B. `activityindicator`) und Emoticons. Optional grenzt `setPattern` (Regex-String) die exportierten Gruppen ein.
+
+```js
+{ buttonsAndIcons: "dev/media/final/general/activityindicator.psd", layout: "std",
+  mode: "topLayerSets", outputDir: "imgs/general" }
+```
+
+- **`appIcons`** erzeugt App-Icons und Favicons profilbasiert (`web`, `ios`, `play`) aus einem quadratischen Master — der modernisierte AppIconMaker.
+- **`sequenceStrip`** baut aus einer Bildsequenz (Einzeldateien oder ein Bild im DSD-Format) einen horizontalen Animations-Strip mit JSON-Frame-Daten:
+
+![Animations-Strip, generiert aus 19 Einzel-Frames einer Rauch-Animation](imgs/strip_result_smoke.png)
+- **`copy` / `copyFolder`** kopieren statische Dateien (Make-artig: nur wenn die Quelle neuer ist).
+
+Die Details der Bildgeneratoren (Ebenenstruktur der Entwürfe, DSD-Format, Profile) beschreibt die µPS-Dokumentation.
+
+### Zwischenschritte raw → final (`outputBase`)
+
+Standardmäßig schreiben alle Steps in das Skin-Ausgabeverzeichnis. Mit `outputBase: "project"` schreibt ein Step stattdessen relativ zum Projektstamm — damit lässt sich die Erzeugung von Zwischenergebnissen (z. B. Sequenz-Strips aus `dev/media/raw/...` nach `dev/media/final/...`) direkt im Manifest abbilden. Die Steps laufen in Manifest-Reihenfolge, ein nachfolgender `copy`/`copyFolder`-Step übernimmt das Ergebnis dann wie jedes andere Final-Asset in den Skin:
+
+```js
+media: [
+	// 1. Strip aus den Roh-Frames in den final-Baum generieren ...
+	{ sequenceStrip: "dev/media/raw/flyex/frames", outputFile: "dev/media/final/general/gui/flyex/flyex.png", outputBase: "project" },
+	// 2. ... und von dort wie gewohnt in den Skin kopieren.
+	{ copyFolder: "dev/media/final/general/gui/flyex", to: "imgs/general/gui/flyex", filter: "\\.(png|json)$" }
+]
+```
+
+Auch für diese Steps gilt der inkrementelle Build: Generiert wird nur, wenn das Ergebnis fehlt oder sich Konfiguration bzw. Quellen (mtime/Größe) geändert haben. Alternativ kann der raw-→-final-Schritt natürlich weiterhin als eigener Gulp-Task vor dem µCSS-Build laufen — `outputBase: "project"` ist der Weg, wenn alles in einer Manifest-Datei stehen soll.
+
+# Grundideen von µCSS
+
+## Das .µ.css-Format
+
+Quell-Stylesheets heißen `*.µ.css`. Das Doppelsuffix sorgt dafür, dass Editoren die Dateien als normales CSS erkennen und das Syntax-Highlighting ohne weitere Konfiguration funktioniert. Für den Compiler ist die Endung irrelevant — das Manifest referenziert die Quellen explizit; wer das µ-Zeichen in Dateinamen vermeiden möchte, kann ebenso `*.mu.css` verwenden. Inhaltlich ist eine `.µ.css`-Datei Standard-CSS mit genau zwei Erweiterungspunkten — beide sind syntaktisch valides CSS, so dass Editoren und Linter normal funktionieren:
+
+1. **Werte-Interpolation** `µ(Ausdruck)` — überall, wo ein CSS-Wert steht.
+2. **Direktiven** `-µ: Ausdruck;` — als Deklaration innerhalb einer Regel.
+
+Wer das µ-Zeichen nicht auf der Tastatur hat, verwendet die ASCII-Aliasse `mu(...)` und `-mu:` — beide Formen sind gleichwertig.
+
+Anders als beim alten µCSS gibt es **keine Steuer-Regeln** (`::-µcss-init` usw.) mehr im Stylesheet: Alles, was die Kompilierung steuert (Variablen, Cursor-Definitionen, Medienerzeugung, Dateizuordnung), steht im Skin-Manifest — einer normalen JavaScript-Datei (siehe unten).
+
+## Werte-Interpolation µ(Ausdruck)
+
+`µ(...)` ist aus CSS-Sicht eine unbekannte, aber valide Funktion. Beim Kompilieren wird der Inhalt als JavaScript-Ausdruck ausgewertet und das `µ(...)`-Vorkommen durch das Ergebnis ersetzt:
+
+```css
+::selection {
+	background-color: µ($.selectBaseBrgdOnDarkColor);
+	color: µ($.selectBaseTextColor);
+}
+```
+
+Mehrere Interpolationen pro Wert sind erlaubt (`padding: µ($.padY)px µ($.padX)px;`), ebenso Interpolationen in At-Rule-Parametern (z. B. `@media (max-width: µ($.breakpoint)px)`). Liefert ein Ausdruck `null` oder `undefined`, bricht die Kompilierung mit einer Fehlermeldung ab — so fallen Tippfehler in Variablennamen sofort auf.
+
+Diese eine Erweiterung ersetzt die komplette `Set*`-Familie des alten µCSS (`SetColor`, `SetBackgroundColor`, `SetZIndex`, `SetWidth`, `AddProperty` für einfache Werte usw.): Die Property steht wieder an ihrem Platz, ein Platzhalter-Wert ist nicht mehr nötig.
+
+## Direktiven -µ: Ausdruck
+
+Direktiven sind Deklarationen mit dem Property-Namen `-µ` (oder `-mu`). Ihr Wert ist ein einzelner JavaScript-Ausdruck, der mit Zugriff auf die umgebende Regel und das Dokument ausgeführt wird. Die Direktive selbst wird aus der Ausgabe entfernt:
+
+```css
+div.panel.modal div.companylogo {
+	-µ: Sprite("imgs/logos/dosing_logo.png");
+	margin-left: auto;
+}
+*.cursor_zoom {
+	-µ: Cursor("zoom");
+}
+div.content.glittery {
+	-µ: Sprite("imgs/general/gui/glittery/glittery.png", { afterWork: GlitterySprite });
+}
+```
+
+Das `µ.`-Präfix des alten µCSS entfällt — der Kontext ist implizit. Direktiven werden in Dokumentreihenfolge ausgewertet.
+
+## Das Skin-Manifest
+
+Pro Skin (CSS-Thema) liegt im Quellverzeichnis eine Manifest-Datei `<skinname>.µcss.mjs` — normales JavaScript (ES6+), importierbar und testbar. Das Doppelsuffix `.µcss.mjs` (ASCII-Alternative `.mucss.mjs`) kennzeichnet die Datei eindeutig als µCSS-Skin-Manifest, damit sie nicht mit einem gewöhnlichen Modul oder Gulpfile verwechselt wird; der Skin-Name ergibt sich aus dem Teil davor (`std.µcss.mjs` → Skin `std`). Sie ersetzt die alte Steuerdatei `µ.std.css` vollständig:
+
+```js
+// skins/src/std.µcss.mjs — Skin "std", Ziel: skins/std/
+import { DefineSkin } from "gulp-mu-css";
+import { GlitterySprite, FlyEx, Borders, TableBackgrounds } from "./helpers.mjs";
+
+export default DefineSkin({
+	vars: {
+		baseBrgdColor: "#202020",
+		selectBaseBrgdColor: "#007570",
+		PanelZIndex: 9000
+	},
+	helpers: { GlitterySprite, FlyEx, Borders, TableBackgrounds },
+	cursors: [
+		{ name: "zoom", fallback: "zoom-in", image: "imgs/general/gui/cursors/zoom.png", hotspot: [10, 8] }
+	],
+	media: [
+		{ buttonsAndIcons: "dev/media/final/general/gui/panelbuttons.psd", layout: "std", outputDir: "imgs/general/gui/panelbuttons" },
+		{ copyFolder: "dev/media/final/fonts", to: "fonts" }
+	],
+	imageFormat: "png",
+	sprites: { file: "imgs/sprites.png", retina: true, preloadRule: true },
+	files: [
+		{ source: "src.µ.css", target: "std.css" },
+		{ source: "src_tinymce.µ.css", target: "std_tinymce.css" }
+	]
+});
+```
+
+Der Skin-Name ergibt sich aus dem Dateinamen des Manifests, das Ausgabeverzeichnis aus dem Skin-Namen. Die vollständige Feld-Referenz steht im Kapitel „Manifest-Referenz".
+
+## JavaScript ohne Ersatzzeichen
+
+Bei µCSS 1 mussten die Zeichen `{`, `}` und `;` in JavaScript-Anweisungen durch `«`, `»` und `¡` ersetzt werden, um CSS-Syntaxkonflikte zu vermeiden. Dieses Muster entfällt in Version 2 ersatzlos:
+
+- In `µ(...)` und `-µ: ...` stehen **einzelne Ausdrücke** — der Parser zählt Klammern und berücksichtigt Strings, so dass auch Objekt-Literale (`{ afterWork: ... }`) und verschachtelte Aufrufe problemlos funktionieren.
+- **Mehrzeilige Logik** (Schleifen, Funktionsdefinitionen) gehört nicht ins Stylesheet, sondern in die Helper-Module des Manifests — echte `.mjs`-Dateien mit Syntax-Highlighting, Linting und Debugger.
+
+# Build-Ablauf und Gulp-Integration
+
+Das alte µCSS wurde über ein modales Dialogfenster in Photoshop bedient. An dessen Stelle treten `BuildSkin` und Gulp: Der Build ist ein normaler, skriptbarer Node-Prozess — geeignet für Watch-Modus, CI und Automatisierung.
+
+## Verzeichniskonventionen
+
+Für ein Manifest `skins/src/std.µcss.mjs` gilt (alle Pfade überschreibbar):
+
+| Pfad | Bedeutung |
+| :--- | :--- |
+| `skins/src/` | Quellverzeichnis: Manifeste, `.µ.css`-Dateien, Helper-Module |
+| `skins/std/` | Ausgabeverzeichnis des Skins „std": CSS, Bilder, Fonts, Sounds |
+| `skins/std/.cache/build.json` | Build-Cache des Skins (Fingerprints, Atlas-Positionen) |
+| Projektstamm | Zwei Ebenen über dem Manifest; Basis für `media`-Quellpfade wie `dev/media/...` |
+
+`BuildSkin(manifestPfad, optionen)` akzeptiert `{ outputDir, rootDir, force }` zum Übersteuern.
+
+## Kompilierungs-Ablauf
+
+Ein `BuildSkin`-Lauf führt fünf Schritte aus:
+
+1. **media-Steps**: Alle Bilder werden erzeugt bzw. kopiert (microPS) — sie müssen existieren, bevor Atlas und Cursor-Prüfungen laufen.
+2. **Kompilierung**: Jede `files`-Quelle wird geparst (PostCSS); Direktiven und Interpolationen werden in Dokumentreihenfolge ausgewertet. `Sprite()`-/`Cursor()`-Aufrufe registrieren zunächst nur ihre Bildreferenzen.
+3. **Sprite-Atlas**: Alle registrierten Bilder werden gepackt (inkl. `@2x`); danach werden die betroffenen Regeln umgeschrieben.
+4. **Hooks**: `afterWork`-Callbacks laufen mit Atlas-Ergebnis und AST-Zugriff.
+5. **Ausgabe**: Die kompilierten CSS-Dateien werden in das Skin-Verzeichnis geschrieben, der Cache wird gespeichert.
+
+## Inkrementeller Build und Cache
+
+Jeder Lauf erzeugt nur das neu, was sich tatsächlich geändert hat. Primärer Mechanismus sind Datei-Modifikations-Zeitstempel (`mtime` plus Dateigröße) — bei großen PSD-Quellen um Größenordnungen schneller als Inhalts-Hashes:
+
+- **Generator-Steps** (`buttonsAndIcons`, `appIcons`, `sequenceStrip`) werden übersprungen, wenn ihre Konfiguration unverändert ist, alle Quelldateien unveränderte Fingerprints haben und alle Ausgabedateien noch existieren. PSD-Rendering ist der teuerste Posten des Builds — hier zahlt der Cache am meisten.
+- **`copy`/`copyFolder`** arbeiten Make-artig: kopiert wird nur, wenn die Quelle neuer als das Ziel ist.
+- **Der Sprite-Atlas** wird nur neu gepackt, wenn sich die Bildmenge oder ein Quellbild (inkl. `@2x`) geändert hat — sonst werden die gespeicherten Positionen wiederverwendet und nur die CSS-Regeln damit umgeschrieben.
+- **Die CSS-Kompilierung** selbst ist billig und läuft im Zweifel immer.
+
+Der Cache liegt pro Skin in `<outputDir>/.cache/build.json` und trägt die Versionsnummern von µCSS und das Cache-Schema; bei Abweichung wird er verworfen (Vollbuild). `BuildSkin(manifest, { force: true })` oder das Löschen von `.cache/` erzwingt den Vollbuild explizit.
+
+## Gulp-Tasks und Watch
+
+Ein Task pro Skin genügt; `BuildSkin` ist re-entrant:
+
+```js
+import gulp from "gulp";
+import { BuildSkin } from "gulp-mu-css";
+
+export async function SkinStd() {
+	const report = await BuildSkin("skins/src/std.µcss.mjs");
+	console.log(`${report.skin}: ${report.files.length} Dateien, Atlas ${report.atlasSkipped ? "aus Cache" : "neu gepackt"}, ${report.duration} ms`);
+}
+export function SkinWatch() {
+	gulp.watch(["skins/src/**/*.µ.css", "skins/src/*.mjs", "dev/media/final/**"], SkinStd);
+}
+```
+
+Der Rückgabewert von `BuildSkin` ist ein Report mit `skin`, `outputDir`, `media` (Step-Ergebnisse mit `skipped`-Flag), `files`, `atlas`, `atlasSkipped` und `duration`.
+
+# Manifest-Referenz (DefineSkin)
+
+`DefineSkin(konfiguration)` deklariert die Skin-Konfiguration (Default-Export des Manifests) und validiert die Grundstruktur. Alle Felder sind optional, sofern nicht anders angegeben.
+
+## vars
+
+Objekt mit den Skin-Variablen — der Ersatz für `µ.$.*`. In `.µ.css`-Ausdrücken als `$.name` zugreifbar, in Helper-Funktionen als `this.$.name`. Werte sind beliebige JavaScript-Werte (Strings, Zahlen, Objekte, auch berechnete).
+
+```js
+vars: { baseBrgdColor: "#202020", PanelZIndex: 9000, icon_pencil: "\\e91c" }
+```
+
+## helpers
+
+Objekt mit benutzerdefinierten Funktionen (Makros und Hooks). Sie stehen in `.µ.css`-Ausdrücken unter ihrem Namen zur Verfügung. Funktionen, die mit `function` (nicht als Arrow-Function) deklariert sind, erhalten beim Aufruf `this` = Auswertungs-Scope (siehe Kapitel „µ-Auswertungskontext").
+
+```js
+import { Borders, GlitterySprite } from "./helpers.mjs";
+// ...
+helpers: { Borders, GlitterySprite }
+```
+
+## cursors
+
+Liste der Cursor-Definitionen — der Ersatz für `µ.DefCursor`:
+
+| Feld | Default | Bedeutung |
+| :--- | :--- | :--- |
+| `name` | — (Pflicht) | Name, unter dem der Cursor mit `Cursor("name")` verwendet wird. |
+| `fallback` | = `name` | Standard-Cursor-Name (W3C) als Fallback. |
+| `image` | `""` | Bild-URL relativ zum Skin-Verzeichnis; leer = Definition nur als Fallback-Mapping. |
+| `hotspot` | `[0, 0]` | Klickpunkt `[x, y]` im Bild; `0,0` wird in der Ausgabe weggelassen. |
+| `forceFallback` | `false` | Hängt den Fallback zusätzlich als letzte `cursor`-Deklaration an. |
+
+Cursor-Bilder werden automatisch in die Preload-Liste aufgenommen.
+
+## media
+
+Liste der Medien-Steps; sie laufen in der angegebenen Reihenfolge vor der Kompilierung. Der Step-Typ ergibt sich aus dem Schlüsselfeld:
+
+| Step | Pflichtfelder | Weitere Felder | Wirkung |
+| :--- | :--- | :--- | :--- |
+| `buttonsAndIcons` | Quell-PSD, `layout`, `outputDir` | `retina` (Default `true`), `format`, `mode`, `setPattern` | Button-/Icon-Serien aus einem Entwurfsdokument rendern (microPS ButtonAndIconCreator). `mode: "topLayerSets"` schaltet auf „ein Bild pro Top-Untergruppe" um (Legacy-`CreateByTopLayerSets`, ohne `icons`-Gruppe — für Logos, Animationsframes, Emoticons); `setPattern` (Regex-String) filtert dabei die exportierten Gruppen. |
+| `appIcons` | Quell-PSD/PNG | `outputDir`, `profiles`, `layout`, `background`, `appName`, `shortName`, `themeColor` | App-Icons/Favicons profilbasiert generieren (microPS AppIconMaker). |
+| `sequenceStrip` | Quelle (Ordner oder DSD-Bild), `outputFile` | `retina` (Default `true`), `writeMapFile` (Default `true`), `format` | Horizontalen Animations-Strip plus JSON-Frame-Daten erzeugen (microPS SequenceStrip). |
+| `copy` | Quelldatei | `to` (Zielordner, Default Skin-Wurzel) | Einzeldatei kopieren, wenn die Quelle neuer ist. |
+| `copyFolder` | Quellordner | `to` (Default = Ordnername), `filter` (Regex-String, z. B. `"\\.(woff2?\|ttf)$"`) | Ordner rekursiv kopieren (Make-artig), optional gefiltert. |
+
+Quellpfade sind relativ zum Projektstamm, Zielpfade relativ zum Skin-Verzeichnis. Jeder Step akzeptiert zusätzlich `outputBase: "skin"` (Default) oder `"project"`: Mit `"project"` ist der Zielpfad relativ zum Projektstamm — für Zwischenschritte wie raw → final (siehe Kapitel „Automatische Bilderzeugung").
+
+## imageFormat
+
+Globaler Bildformat-Schalter: `"png"` (Default) oder `"webp"`. Gilt für den Sprite-Atlas und alle bilderzeugenden media-Steps; einzelne Steps können das Format per eigenem `format`-Feld übersteuern. Direkt referenzierte Bestandsbilder (`url(...)` in den Quellen, `copy`-Steps) bleiben unangetastet.
+
+## sprites
+
+Optionen des Sprite-Atlas — der Ersatz für `µ.options.sprites.*`:
+
+| Feld | Default | Bedeutung |
+| :--- | :--- | :--- |
+| `file` | `"imgs/sprites.png"` | Atlas-Datei (URL, wie sie in der CSS erscheint). Bei `imageFormat: "webp"` wird die Endung automatisch getauscht. |
+| `retina` | `true` | Erzeugt zusätzlich `<name>@2x` aus den `@2x`-Quellbildern (müssen neben den 1x-Quellen liegen). |
+| `padding` | `0` | Abstand in Pixeln zwischen den Sprites. |
+| `preloadRule` | `false` | Erzeugt die `div.csspreload`-Regel im ersten Stylesheet. |
+
+## files
+
+Liste der zu kompilierenden Stylesheets — der Ersatz für `µ.DependentCSSFile`. `source` ist relativ zum Quellverzeichnis, `target` relativ zum Skin-Verzeichnis; beide Felder sind Pflicht:
+
+```js
+files: [
+	{ source: "src.µ.css", target: "std.css" },
+	{ source: "src_tinymce.µ.css", target: "std_tinymce.css" }
+]
+```
+
+Alle Dateien eines Skins teilen sich Variablen, Helpers und den Sprite-Atlas. Die Preload-Regel landet im ersten Stylesheet.
+
+# µ-Auswertungskontext (Referenz)
+
+Jeder `µ(...)`-Ausdruck und jede `-µ:`-Direktive wird in einem Scope ausgewertet, der die folgenden Bindungen enthält. Er entspricht dem alten globalen `µ`-Objekt — nur ohne Präfix.
+
+## Das $-Objekt
+
+`$` enthält die `vars` des Manifests. Lesen und Schreiben ist möglich; Änderungen gelten für den weiteren Verlauf der Kompilierung (Dokumentreihenfolge, über alle `files` eines Skins hinweg).
+
+```css
+div.box { z-index: µ($.PanelZIndex + 1); }
+```
+
+## Farb- und Wert-Funktionen
+
+| Funktion | Beschreibung |
+| :--- | :--- |
+| `Lighten(color, step, model = "hsl")` | Hellt eine Farbe relativ auf (positiver `step`) oder dunkelt sie ab (negativer `step`): `L' = clamp(L + L · step)`. Das Modell `"hsl"` ist bitgenau zum alten µCSS; `"oklch"` skaliert wahrnehmungsgleichmäßig. Alpha bleibt erhalten. |
+| `Alpha(color, alpha)` | Ersetzt den Alpha-Kanal einer Farbe. `alpha` nach den Regeln aus „Arbeiten mit Farben". |
+| `MixColors(color1, color2)` | Kanalweiser Mittelwert zweier Farben (inklusive Alpha). |
+| `AlphaValue(alpha)` | Wandelt eine Alpha-Angabe in ein Byte (0–255) um. |
+| `ParseColor(color)` | Parst eine CSS-Farbe in die interne 32-Bit-Darstellung `0xAARRGGBB`. |
+| `FormatColor(color, alphaDecimals = 3)` | Serialisiert die interne Darstellung zurück zu CSS (`#rrggbb` bzw. `rgba(...)`). |
+| `PxUnit(value)` | Zahlen werden zu `"<n>px"`, alles andere (z. B. `calc()`-Strings) wird unverändert durchgereicht. |
+
+## Regel- und Dokument-Methoden
+
+Innerhalb von Direktiven (und Helper-Funktionen mit `this`-Bindung) stehen zusätzlich die Manipulations-Methoden der umgebenden Regel bereit:
+
+| Methode / Eigenschaft | Beschreibung |
+| :--- | :--- |
+| `AddProperty(name, value, important?)` | Hängt eine Deklaration an die Regel an (Duplikate erlaubt — für Fallback-Ketten wie mehrfache `background-image`). |
+| `ChangeProperty(name, value, important?)` | Ändert alle Deklarationen der Property bzw. legt sie an, wenn sie fehlt. |
+| `RemoveProperty(name)` | Entfernt alle Deklarationen der Property. |
+| `AddRule(selector)` | Fügt eine neue Regel am Dokumentende an; Rückgabe ist die Regel (mit denselben Methoden). |
+| `InsertRule(selector)` | Fügt eine neue Regel direkt hinter der aktuellen Regel ein; aufeinanderfolgende Aufrufe behalten ihre Reihenfolge. Ersatz für das alte `AddBlock(n, µ.elementNo)`. |
+| `rule` | Die umgebende Regel als `CssRule`-Objekt (`rule.selector`, `rule.GetProperty(...)`, …). |
+| `document` | Das gesamte Stylesheet als `CssDocument` — z. B. für Pfad-Adressierung: `document.FindRule("@keyframes glittery", "from")`. Ersatz für die alten RememberBlocks. |
+
+## Sprite()
+
+Registriert das Bild der Regel für den Sprite-Atlas (nur als Direktive):
+
+```css
+-µ: Sprite(url, optionen?);
+```
+
+| Parameter / Option | Default | Beschreibung |
+| :--- | :--- | :--- |
+| `url` | — (Pflicht) | Bild-URL relativ zum Skin-Verzeichnis. |
+| `offsetWidth` | `0` | Wird zur berechneten `width` addiert. |
+| `offsetHeight` | `0` | Wird zur berechneten `height` addiert. |
+| `offsetPosX` | `0` | Wird zur `background-position`-X-Koordinate addiert. |
+| `offsetPosY` | `0` | Wird zur `background-position`-Y-Koordinate addiert. |
+| `afterWork` | — | Hook-Funktion, läuft nach der Atlas-Auflösung (siehe unten). |
+
+Beim Atlas-Auflösen werden `background-image` (`url(...)` plus `image-set(...)` bei Retina), `background-repeat`, `background-position`, `width` und `height` der Regel gesetzt; vorhandene Deklarationen dieser Properties werden ersetzt.
+
+## Cursor()
+
+Wendet eine Cursor-Definition aus dem Manifest an — als Direktive (`-µ: Cursor("zoom");`, schreibt die `cursor`-Deklarationen der Regel um) oder als Wertform (`cursor: µ(Cursor("zoom"));`, liefert nur den `url(...) x y, fallback`-String). Unbekannte Namen werden unverändert durchgereicht — Standard-Cursor wie `pointer` funktionieren so ohne Definition.
+
+## Helper-Funktionen und this-Bindung
+
+Helper aus dem Manifest, die mit `function` deklariert sind, werden mit `this` = Auswertungs-Scope aufgerufen. Damit lassen sich Makros im Stil der alten `µ.$.Funktionen` schreiben — nur als normales, testbares JavaScript:
+
+```js
+// helpers.mjs
+import { Lighten } from "gulp-mu-css";
+
+export function Borders(_baseColor, _pixelWidth, _topLighten, _rightLighten, _bottomLighten, _leftLighten) {
+	this.AddProperty("border-top", `${_pixelWidth}px solid ${Lighten(_baseColor, _topLighten)}`);
+	this.AddProperty("border-right", `${_pixelWidth}px solid ${Lighten(_baseColor, _rightLighten)}`);
+	this.AddProperty("border-bottom", `${_pixelWidth}px solid ${Lighten(_baseColor, _bottomLighten)}`);
+	this.AddProperty("border-left", `${_pixelWidth}px solid ${Lighten(_baseColor, _leftLighten)}`);
+}
+```
+
+Über `this` sind alle Scope-Bindungen erreichbar: `this.AddProperty(...)`, `this.InsertRule(...)`, `this.rule`, `this.document` und `this.$`. Die Bindung bleibt auch erhalten, wenn ein Helper als `afterWork`-Wert an `Sprite()` übergeben wird. Arrow-Functions haben kein eigenes `this` und eignen sich daher nur für Helpers ohne Regel-Zugriff.
+
+Portierte Referenz-Makros des AiDPix-Projekts (`Borders`, `TableBackgrounds`, `GlitterySprite`, `FlyEx`, `FlyExUtils`) liegen im µCSS-Repository unter `examples/aidpix-helpers.mjs`.
+
+## afterWork-Hooks
+
+Der `afterWork`-Hook einer Sprite-Registrierung läuft, nachdem der Atlas gepackt und die Regel umgeschrieben wurde. Er erhält einen Kontext mit allen Ergebnisdaten:
+
+| Feld | Beschreibung |
+| :--- | :--- |
+| `rule` | Die umgeschriebene Regel (`CssRule`). |
+| `document` | Das Stylesheet (`CssDocument`). |
+| `url` | Die registrierte Bild-URL. |
+| `baseDir` | Skin-Verzeichnis (zum Auflösen von Nachbar-Dateien, z. B. `.json`-Maps). |
+| `sprite` | `{ x, y, width, height }` — Position und Größe im Atlas. |
+| `atlas` | `{ file, retinaFile, width, height }` — die Atlas-Dateien und -Gesamtgröße. |
+
+Typischer Einsatz: Animations-Keyframes aus den Frame-Daten eines `sequenceStrip` generieren (siehe `GlitterySprite` in den Referenz-Makros).
+
+# Arbeiten mit Farben
+
+## Farben definieren
+
+Die interne Darstellung einer Farbe ist ein vorzeichenloser 32-Bit-Integer der Form `0xAARRGGBB` (Alpha, Rot, Grün, Blau; je 8 Bit). In allen Farb-Funktionen sind folgende Eingabeformen möglich:
+
+- **32-Bit-Integer** wie die interne Darstellung, z. B. `0xffff0000` für deckendes Rot.
+- **`#`-Notation** mit zwei Hex-Ziffern pro Kanal, z. B. `"#00ff00"` (Alpha wird auf deckend gesetzt).
+- **Kurze `#`-Notation** mit einer Hex-Ziffer pro Kanal, z. B. `"#0f0"`.
+- **Erweiterte `#`-Notation** mit Alpha-Kanal als vierte Komponente, z. B. `"#0000ff80"` für halbtransparentes Blau.
+- **`rgb()`-Notation**, absolut oder prozentual, z. B. `"rgb(255,0,0)"` oder `"rgb(100%,0%,0%)"`.
+- **`rgba()`-Notation** mit Float-Alpha, z. B. `"rgba(255,0,0,0.5)"`.
+- **CSS-Farbnamen** (W3C CSS Color Module, erweiterte Liste), z. B. `"red"`, `"teal"`, `"rebeccapurple"` sowie `"transparent"`.
+
+Werte außerhalb des gültigen Bereichs werden begrenzt (geclippt).
+
+## Alpha-Werte
+
+Alpha-Angaben (z. B. für `Alpha(color, a)`) sind in mehreren Formen möglich:
+
+- **Float** zwischen `0.0` (transparent) und `1.0` (deckend).
+- **Integer** zwischen `0` und `255`.
+- **Hex-String**, z. B. `"0x80"`.
+- **Prozent-String** von `"0%"` bis `"100%"`.
+- **Schlüsselwörter** `"transparent"` (0), `"translucent"` (128) und `"opaque"` (255).
+
+## Farbberechnungen
+
+Die Funktionen `Lighten`, `Alpha` und `MixColors` (Kapitel „µ-Auswertungskontext") decken die typischen Berechnungen ab. Deckende Ergebnisse werden als `#rrggbb` ausgegeben, transparente als `rgba(r,g,b,a)` mit drei Alpha-Nachkommastellen — identisch zum alten µCSS.
+
+```css
+div.menu {
+	background-color: µ(Alpha($.baseBrgdColor, 0.9));
+	border-top: 1px solid µ(Lighten($.baseBrgdColor, 0.3));
+	border-bottom: 1px solid µ(Lighten($.baseBrgdColor, -0.3));
+}
+```
+
+Für neue Skins empfiehlt sich das `"oklch"`-Modell von `Lighten`: Es verändert die wahrgenommene Helligkeit gleichmäßig über alle Farbtöne, während das Legacy-Modell `"hsl"` bei gesättigten Farben sichtbar springen kann.
+
+# Node-API
+
+Neben dem Manifest-Workflow ist jede Schicht von µCSS auch direkt als Node-API nutzbar — etwa für eigene Gulp-Transformationen oder Tests.
+
+| Export | Beschreibung |
+| :--- | :--- |
+| `CompileMcss(source, options)` | Kompiliert `.µ.css`-Quelltext zu einem `CssDocument`. Optionen: `vars`, `helpers`, `from` (Dateiname für Fehlermeldungen), `context` (gemeinsamer `MuContext`), `sprites` (SpriteManager), `cursors` (CursorManager). |
+| `CssDocument` / `CssRule` | JSON-fähiger Wrapper über den PostCSS-AST: `FromFile`/`FromString`, `FindRule(...pfad)`, `FindRules(selektorOderRegex)`, `AddRule`, `GetProperty`/`AddProperty`/`ChangeProperty`/`RemoveProperty`, `ToCss()`, `ToFile()`, `ToJson()`/`FromJson()`. Für Spezialfälle ist der rohe PostCSS-AST über `document.root` zugänglich. |
+| `SpriteManager` | Sprite-Registrierung und Atlas-Auflösung: `new SpriteManager({ baseDir, atlasFile, retina, padding, preloadRule, preload, writeMapFile })`, `Register(rule, url, optionen)`, `await Resolve(document)`. |
+| `CursorManager` | Cursor-Definitionen: `new CursorManager(definitionen, { baseDir, preload })`, `Apply(rule, name)`, `Value(name)`. |
+| `PreloadRegistry` | Sammelt Bild-URLs und erzeugt die `div.csspreload`-Regel. |
+| `DefineSkin(config)` / `BuildSkin(manifest, options)` | Manifest-Deklaration und Skin-Build (siehe Kapitel „Build-Ablauf"). |
+| `MuContext` | Auswertungskontext für eigene Pipelines: `new MuContext({ vars, helpers })`, `Evaluate(quelltext, extraScope)`. |
+| `Lighten`, `Alpha`, `AlphaValue`, `MixColors`, `ParseColor`, `FormatColor`, `PxUnit` | Die Farb- und Wert-Funktionen als direkte Importe. |
+
+Beispiel einer JSON-basierten Gulp-Manipulation:
+
+```js
+import { CssDocument } from "gulp-mu-css";
+
+const doc = await CssDocument.FromFile("skins/src/src.µ.css");
+doc.FindRules(/^div\.panel/).forEach((_rule) => _rule.AddProperty("outline", "none"));
+doc.FindRule("@keyframes glittery", "from").ChangeProperty("background-position-x", "-128px");
+const json = doc.ToJson();
+await doc.ToFile("out/std.css");
+```
+
+# Fehlerdiagnostik
+
+Build-Fehler nennen immer den Verursacher samt Quellbezug:
+
+- **Inline-JavaScript** (`µ(...)`-Interpolationen und `-µ:`-Direktiven): Fehler werden als PostCSS-Fehler mit Datei, Zeile, Spalte und Quelltext-Ausschnitt gemeldet. Bei mehreren `µ(...)` in einem Wert wird der fehlschlagende Ausdruck genannt. JavaScript-Syntaxfehler erscheinen als `invalid JavaScript expression "<Quelltext>" (...)`.
+
+```
+CssSyntaxError: skins/src/std.µ.css:2:2: microCSS: µ(NopeFn(1)): NopeFn is not defined
+
+  1 | div.b {
+> 2 |     border: 1px solid µ(NopeFn(1));
+    |     ^
+  3 | }
+```
+
+- **Fehlende Sprite-Bilder**: Vor dem Packen des Atlas wird die Existenz aller Quellbilder (inklusive `@2x` bei `retina: true`) geprüft. Alle fehlenden Dateien werden gesammelt in einem Fehler gemeldet — jeweils mit URL, aufgelöstem Pfad und der referenzierenden Regel:
+
+```
+SpriteManager: 2 sprite image(s) not found:
+  - "imgs/nope.png" -> C:\...\skins\std\imgs\nope.png - selector "div.bad1" (skin.µ.css:2)
+  - "imgs/alsonope.png" -> C:\...\skins\std\imgs\alsonope.png - selector "div.bad2" (skin.µ.css:3)
+```
+
+- **`afterWork`-Hooks**: Fehler im Hook werden mit Sprite-URL und Regel-Quellposition ummantelt; der Original-Fehler bleibt als `cause` erhalten.
+- **Fehlende Cursor-Bilder** erzeugen nur eine Warnung (einmal pro Cursor), da die CSS über den Fallback-Cursor funktionsfähig bleibt.
+- **media-Steps**: Fehler nennen Step-Nummer und -Typ, z. B. `BuildSkin: media step 3 of 7 (buttonsAndIcons: "dev/media/buttons.psd") failed: ...`. Fehlende Quellen werden vor der Ausführung geprüft: `copy`/`copyFolder` und Generator-Steps melden den aufgelösten Pfad statt eines rohen Dateisystemfehlers — bei `copyFolder` mit dem Hinweis, dass vermutlich der erzeugende Schritt (z. B. Sequenzbild-Generierung nach `dev/media/final/...`) nicht gelaufen ist.
+- **files-Einträge**: Fehlende Quelldateien werden mit Eintrag und aufgelöstem Pfad gemeldet, bevor kompiliert wird.
+
+# Migration von µCSS
+
+Für Bestandsprojekte existiert ein Konverter-Werkzeug (`tools/convert-mucss.mjs` im µCSS-Repository), das die alte Syntax mechanisch übersetzt:
+
+| Alt (µCSS 1) | Neu (µCSS 2) |
+| :--- | :--- |
+| `-µcss: µ.Cursor("wait");` plus `cursor: wait;` | `cursor: µ(Cursor("wait"));` |
+| `-µcss: µ.SetBackgroundColor(µ.$.x);` plus Platzhalter | `background-color: µ($.x);` |
+| `-µcss: µ.AddProperty("border", "1px solid " + µ.Lighten(...));` | `border: 1px solid µ(Lighten(...));` |
+| `-µcss: µ.Sprite("p.png");` | `-µ: Sprite("p.png");` |
+| `-µcss: µ.SetRememberBlock("n");` | entfällt — Pfad-Adressierung: `document.FindRule("@keyframes x", "from")` |
+| `-µcss: //µ.X(...)` (deaktiviert) | `/* -µ: X(...) */` |
+| `µ.$.name = wert` (in `µ.std.css`) | `vars`-Eintrag im Manifest |
+| `µ.DefCursor(...)` | `cursors`-Eintrag im Manifest |
+| `µ.plugins.*` / FileCopy | `media`-Einträge im Manifest |
+| `µ.$.Fn = function(...)«…»` | exportierte Funktion in `helpers.mjs` |
+
+Die `«»¡`-Funktionskörper werden zu normalem JavaScript zurückübersetzt und landen als Startpunkt in `helpers.mjs`; manuelle Nacharbeit ist hier eingeplant.
+
+**raw → final automatisch:** Das alte µCSS kopierte nur die bereits fertig erzeugten `final`-Ordner in den Skin (z. B. `flyex`, `glittery`); die Strips selbst entstanden außerhalb (SpriteTools). Der Konverter erkennt solche `CopyFolder2Skin`-Aufrufe auf `dev/media/final/<…>/<name>` und stellt — falls eine passende Quelle `dev/media/raw/<name>/imgs` existiert — automatisch den passenden `sequenceStrip`-Step mit `outputBase: "project"` davor: eine **nummerierte PNG-Frame-Sequenz** (z. B. `glittery`) wird zu einem Ordner-Strip, **einzeln benannte Bilder** (z. B. die DSD-Bilder `flyex.png`/`flyexutils.png`) je zu einem DSD-Strip. So baut die neue Pipeline `final` reproduzierbar aus `raw` und der nachfolgende `copyFolder` übernimmt das Ergebnis in den Skin.
+
+Der Konverter wurde am vollständigen AiDPix-Bestand validiert: Ein Vergleichswerkzeug (`tools/compare-aidpix.mjs`) baut den konvertierten Skin und vergleicht ihn regel- und property-weise gegen die alte kompilierte Ausgabe — Ergebnis: 2 951 Regeln, 0 unerwartete Differenzen (53 dokumentierte Drift-Fälle, z. B. nach dem letzten µCSS-Lauf editierte Quellen).
+
+Bewusst **nicht** übernommen wurden aus dem alten µCSS:
+
+- **Vendor-Prefixes** (`-webkit-`/`-moz-`/`-ms-`-Duplikate): Alle genutzten Features sind seit Jahren unprefixt verfügbar. Vendor-spezifische Selektoren ohne Standard-Pendant (z. B. `::-webkit-scrollbar`) werden natürlich unverändert durchgereicht.
+- **Photoshop-Dialogfenster** im Build: Interaktive Parameter gehören in das Manifest oder in Umgebungsvariablen.
+- **FTP-Synchronisation**: Dafür gibt es heute etablierte Werkzeuge (CI/CD, rsync, gulp-Plugins).
+- **Die Ersatzzeichen `«»¡`**: siehe Kapitel „Grundideen".
+
+# Versionshistorie
+
+| Datum | Version | Anmerkungen |
+| :--- | :--- | :--- |
+| 2013 | 1.0 | Ursprüngliches µCSS als Adobe-Photoshop-Script: `-µcss:`-Direktiven, Sprite-Atlas, PSD-Plugins, Steuerung über `µ.std.css`. |
+| 2026-06 | 2.0.0 | Vollständige Node.js-Neuimplementierung (npm-Paket `gulp-mu-css`, ohne Adobe-Abhängigkeit): Core-Pipeline (M1), Sprites & Cursor (M2), Manifest & Build mit inkrementellem Cache (M3), Hooks & Makros (M4), AiDPix-Migration mit Konverter und Abnahmetest (M5), Handbuch (M6). |
+
+# Rechtliches
+
+Diese Software wird unter der MIT-Lizenz veröffentlicht und ist für freie und kommerzielle Nutzung freigegeben. Weder Dongleware noch der Autor haften für Schäden, die durch die Nutzung dieser Software entstehen. Die Nutzung erfolgt auf eigenes Risiko; sichern Sie Ihre Arbeit, bevor Sie die Werkzeuge einsetzen.
+
+Autor: Meinolf Amekudzi.
+
+## MIT-Lizenz (Originaltext)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Marken
+
+Photoshop ist eine eingetragene Marke von Adobe Inc.; Affinity Photo ist eine Marke von Serif (Europe) Ltd. Die Nennung von Namen und Produkten dient ausschließlich der Information und stellt keinen Missbrauch der jeweiligen Handelsnamen oder Marken dar.
+
+## Verwendete Bibliotheken
+
+µCSS und µPS nutzen Open-Source-Bibliotheken Dritter, insbesondere PostCSS (CSS-Parser, MIT-Lizenz), sharp (Bildverarbeitung, Apache-2.0-Lizenz) und ag-psd (PSD-Leser, MIT-Lizenz). Der Bin-Packer des Sprite-Atlas basiert auf node-bin-packing (©2011 Jake Gordon und Mitwirkende, MIT-Lizenz).