
Blockstudio 7.6 macht Projekte über PHP lesbar und renderbar und verlagert standardmäßiges Frontend-Verhalten in der Produktion nach `blockstudio.json`: ein Inventar API, Rendering ohne Seitenkontext, Template-Helfer für Medien und Tailwind, Leistungsprofile, ein Cache-Verzeichnis, statisches Prerendering mit frühzeitiger Auslieferung, strengere Analyse-Presets und generierte Projektwerkzeuge für Coding-Agents.

Zwei Aufrufe decken den Großteil der Version ab. `Canvas::inventory()` liefert alle Seiten, Blöcke, Patterns, Site-Editor-Templates, Template-Teile und registrierten Beispiele für gebündeltes UI eines Projekts zurück. `Render::document()` liefert für jedes davon fertiges HTML samt genau den beim Rendering verwendeten Assets zurück.

> **Update 7.6.2:** Datei-basierte Seiten werden bei gewöhnlichen WordPress-Anfragen nicht mehr abgeglichen. Führe `wp bs pages sync` aus oder rufe `Blockstudio\Pages::reconcile()` auf, wenn du Quelländerungen übernehmen möchtest. Collection-Routing und `templateFor`-Standards verwenden persistierte Runtime-Konfigurationen, und beim expliziten Abgleich entfällt die frühere große mehrsprachige OR-Meta-Abfrage. Die kurzlebige Option `themeDefaults.syncPagesInDevelopment` wurde entfernt, weil die Seitensynchronisierung nicht mehr über Anfrage-Hooks läuft. `Pages::init()` dient jetzt nur noch dem Bootstrap; Integrationen, die `force` übergeben haben, müssen `Pages::reconcile()` oder CLI verwenden. Beim Öffnen von Canvas erfolgt für das Autoreninventar weiterhin ein einmaliger, authentifizierter, expliziter Abgleich.

> **Update 7.6.12:** Editor-Stylesheets werden jetzt in einem einzigen
> Durchlauf statt bei jedem Asset per SASS kompiliert und mit Präfixen versehen. Dadurch läuft ein frischer Editor-Build auf einer Website mit vielen Blöcken nicht mehr Gefahr, ein knappes Speicherlimit zu überschreiten. Eine zwischengespeicherte, vorab gerenderte Seite wird neu gerendert, wenn ihr Tailwind-Stylesheet mit Inhalts-Hash entfernt wurde, statt ohne Styles ausgeliefert zu werden. Das gilt sowohl für den PHP-Cache als auch für das Early-Serve-Drop-in. Blockattribute auf oberster Ebene werden beim Rendern gelesen, statt verworfen zu werden. Dadurch wird das Schema Blockstudio, das auf `WP_Block_Type` registriert ist, auch von programmatischen Schreibern berücksichtigt.

> **Update 7.6.11:** Die Installation von Graph-Artefakten ersetzt ein Routendokument jetzt atomar, wenn sich die gespeicherte Kopie unter demselben Schlüssel geändert hat, lässt identische Dokumente unverändert und meldet über `Static_Prerender_Early_Serve::last_promotion()`, welche Routen übernommen, ersetzt, übersprungen oder beibehalten wurden.

> **Update 7.6.10:** Treffer im Runtime-Cache erkennen jetzt auch während des Watch-Debounce-Fensters entfernte kompilierte Assets. Flache Runtime-Caches aus Versionen vor 7.6 werden atomar isoliert und in begrenzten cron-Chargen gelöscht. Globale Variablen aus gebündelten UI werden nur einmal pro Seite ausgegeben. Early Serve im Graph-Modus kann live gerenderte Routen außerhalb der bereitgestellten Routenkarte aus dem Identity-Cache ausliefern. Tailwind kann die Cache-Datei mit Inhalts-Hash optional mit `tailwind.output: "link"` ausgeben; standardmäßig bleibt die Ausgabe inline.

Kurz gesagt:

- **Projektübersicht**: `Canvas::inventory()` gibt alle registrierten Einträge mit ihren Quellen und einer stabilen Anzeigereihenfolge zurück.
- **Gezielte Auswahl**: Die Angabe von Blöcken und Seiten beschränkt Erkennung, Synchronisierung, Rendering und Kompilierung auf diese Einträge.
- **Eigenständiges Rendering**: `Blockstudio\Render` gibt fertiges HTML für einen Block, eine Komposition oder ein vollständiges Dokument zurück.
- **UI-Komponentenfamilien**: `Blockstudio\Ui` gruppiert die gebündelte Bibliothek in eine öffentliche Familie pro Komponente, jeweils mit einem Beispiel.
- **Stabile Bildabmessungen**: `bs_media_image()` rendert Theme-Assets mit echten Abmessungen aus einem generierten `assets/media.json`.
- **Tailwind-Klassenhilfen**: `bs_tw_merge()` und `bs_tw_variants()` kombinieren Klassen in PHP und lösen Konflikte auf.
- **Performanceprofile**: `performance.profile` aktiviert auf einmal die Frontend-Standardwerte für den Produktivbetrieb; Werte untergeordneter Einstellungen haben Vorrang.
- **Zugriff auf typisierte Einstellungen**: `Settings::get_bool()` und die zugehörigen Funktionen lesen `blockstudio.json` mit echten Typen und zeigen Parse-Fehler an.
- **Ein Cache-Verzeichnis**: Alle generierten Dateien liegen unter `cache.path` und sind nach einer Runtime-Identität geordnet.
- **Statisches Vorabrendern**: Anonyme HTML können zwischengespeichert, über einen Abhängigkeitsgraphen ungültig gemacht und vor dem Start von WordPress ausgeliefert werden.
- **Analyse-Voreinstellungen**: `theme`, `extreme-theme` und `wordpress-render` erweitern `blockstudio/phpstan` über Blockvorlagen hinaus.
- **Verwalteter Commit-Hook**: `blockstudio-githooks sync` schreibt und verwaltet einen Pre-Commit-Hook, der die konfigurierte Voreinstellung ausführt.
- **Projektvertrag**: `blockstudio-agents` schreibt ein `AGENTS.md`, das beschreibt, was ein Projekt erstellt, welche Funktionen es aktiviert und was seine Voreinstellung durchsetzt.
- **Dokumentationsindex**: Die KI-Kontextdatei ist jetzt ein Index aller Dokumente, ihrer Zwecke und der jeweils zugehörigen Kennungen.
- **Kanonische Block-Tags**: Ein eigenständiger Befehl wandelt Präfix- und Alias-Kurzformen mit einem Probelauf in `<bs:namespace-slug>` um.
- **Standardmäßig kompatibel**: Nichts davon ändert eine Website, bis es in `blockstudio.json` angegeben wird.

## Ein Projekt lesen und rendern

### Projektübersicht

`Canvas::inventory()` gibt alles, was ein Projekt registriert, als einfaches Array zurück, ohne etwas zu rendern.

```php
use Blockstudio\Canvas;

$result = Canvas::inventory();

foreach ($result['inventory']['blocks'] as $block) {
    echo $block['name'] . "\n";
}
```

Die Einträge sind nach Typ gruppiert: `pages`, `blocks`, `patterns`, `templates`, `parts` und `ui`. `order` legt die stabile Anzeigereihenfolge über alle Typen hinweg fest, `sources` ordnet jedem Eintrag seine Quellpfade zu, und `warnings` sowie `errors` sammeln Probleme als strukturierte Einträge.

Blockeinträge enthalten `id`, `name`, `title`, `source`, `path`, `provenance` und ein sofort renderbares `declaration`. Seiteneinträge behalten `source` als stabile Kennung und `path` als zu rendernde Vorlage bei.

### Gezielte Auswahl

Durch die Angabe von Einträgen wird der Arbeitsumfang direkt eingeschränkt, statt die Ergebnisse nachträglich zu filtern.

```php
$changed = Canvas::inventory([
    'blocks' => ['mytheme/hero'],
    'pages' => ['about'],
]);
```

Das gibt einen Block und eine Seite zurück. `patterns`, `templates`, `parts` und `ui` bleiben leer. Ihre Quellen werden weder gelesen noch synchronisiert, gerendert oder kompiliert.

Die Regeln sind eindeutig:

- Ohne Typ-Schlüssel werden alle Typen geladen.
- `true`, `null` oder `"*"` lädt alle Einträge dieses Typs.
- Eine Zeichenfolge oder Liste wird exakt mit ID, Name, Slug, Pfad oder Quellpfad abgeglichen.
- Eine leere Zeichenfolge, eine leere Liste oder `false` lädt keine Einträge dieses Typs.
- Sobald ein Typ-Schlüssel angegeben ist, bleiben die ausgelassenen Typen unangetastet.

Nicht mehr vorhandene Kennungen werden unter `deleted` zurückgegeben, statt einen Fehler auszulösen. Auch der Canvas-Endpunkt REST zum Aktualisieren wendet dieselbe Regel auf die Parameter `blocks` und `pages` an.

`Canvas::documents()` übernimmt dieselbe Auswahl und fügt pro Eintrag ein gerendertes Dokument hinzu. Ausgewählte Seiten werden in einem wiederhergestellten Frontend-Kontext gerendert. Dadurch beziehen sich Abfragebedingungen, Body-Klassen, Shortcodes, Layouts, Weiterleitungen und Enqueue-Callbacks auf die jeweilige Seite und nicht auf die Anfrage, die das Rendering ausgelöst hat.

### Eigenständiges Rendering

`Blockstudio\Render` gibt gerendertes HTML als Zeichenfolge über dieselbe Pipeline zurück, die auch das Frontend verwendet.

```php
use Blockstudio\Render;

$html = Render::composition([
    'root' => 'mytheme/card',
    'data' => ['heading' => 'Example card'],
    'layers' => [
        ['name' => 'mytheme/button', 'data' => ['label' => 'Continue']],
    ],
]);
```

Darunter liegt eine gemeinsame Deklarationsform mit vier Schlüsseln: `name`, `attributes`, `content` und `children`. `root`, `data`, `inner`, `innerBlocks`, `layers` und `example` erleichtern die Eingabe; `Render::normalize()` fügt sie in diese Form ein. Untergeordnete Elemente werden rekursiv gerendert. Bei fehlerhaften Eingaben wird eine Ausnahme ausgelöst, die den betroffenen Block nennt.

`Render::document()` verpackt die Ausgabe in ein vollständiges eigenständiges HTML-Dokument.

```php
$document = Render::document('mytheme/hero', [
    'title' => 'Hero preview',
]);

echo $document['html'];
```

`body` enthält nur die Blockausgabe, `html` das zusammengesetzte Dokument und `blocks` die Namen der beteiligten Blöcke. `assets` teilt das Markup in `head`, `footer`, `styles`, `scripts`, `modules`, `interactivity`, `ui` und `tailwind` auf. Es werden nur die Assets der gerenderten Inhalte eingebunden, nie solche, die nur im Editor verwendet werden.

`Render::document_from_html()` umschließt ein anderswo gerendertes HTML, und `Render::content()` rendert serialisierte Blockinhalte ohne Dokument. Rufe `Blockstudio\Batch_Render::reset()` zwischen Dokumenten innerhalb eines PHP-Prozesses auf; `Canvas::documents()` erledigt das bereits.

### UI-Komponentenfamilien

`Blockstudio\Ui` stellt die gebündelte UI-Bibliothek mit einem Eintrag pro öffentlicher Komponente bereit, statt interne Teile aufzulisten.

`Ui::inventory()` gibt einen Eintrag pro Familie mit ihrem Stammblock, Titel und den benötigten Implementierungsblöcken zurück. `Ui::examples()` ergänzt eine deterministische Deklaration pro Familie: Standardwerte bleiben erhalten, erforderliche untergeordnete Ebenen werden unter ihren übergeordneten Elementen verschachtelt, und leere Felder erhalten stabilen Beispieltext. Diese Deklaration ist kanonisch und kann direkt in `Render::document()` übernommen werden.

Canvas gruppiert die Elemente auf dieselbe Weise. Gebündeltes UI erscheint unter dem Typ `ui` mit einem Beispiel pro Familie; Implementierungsregistrierungen werden in `blocks` nicht angezeigt.

Die Familien sind auf die Zusammensetzung ausgelegt: Ein Select öffnet sich in einem Dialog, dessen Listbox über dem Auslöser liegt. Menüs und Comboboxen bleiben mit festen Viewport-Koordinaten auch beim Scrollen verankert. Modals lassen sich stapeln und mit Escape einzeln schließen. Jeder Footer kombiniert dieselbe Schließen-Steuerung mit einer Variante. Wie diese Verbindungen funktionieren und welche Invarianten sie gewährleisten, erklärt das [Kapitel zur Komposition](https://blockstudio.dev/de/ui/composition/); [/ui/examples](https://blockstudio.dev/de/ui/examples/) zeigt die Kompositionen in Aktion.

## Vorlagenhilfen

### Stabile Bildabmessungen

`bs_media_image()` rendert Theme-Assets mit echten Breiten- und Höhenangaben und reserviertem Seitenverhältnis. So verschieben Bilder außerhalb der Mediathek nicht mehr das Layout.

```php
<?php
echo bs_media_image([
    'src' => 'assets/images/hero.webp',
    'alt' => 'Hero',
]);
```

Die Ausgabe ist ein `figure.blockstudio-media` mit einem eingebetteten `aspect-ratio` um ein `img`, das echte Werte für `width`, `height`, `loading` und `decoding` enthält. Die Abmessungen stammen aus einem generierten `assets/media.json`, das entweder beim Build-Schritt von `Blockstudio\Media_Metadata_Builder` geschrieben oder manuell angelegt wird.

`src` akzeptiert einen relativen Theme-Pfad, einen absoluten Pfad oder eine vollständige URL. `attachmentId` deckt Bilder aus der Mediathek ab. Mit `eager` wird Lazy Loading oberhalb des sichtbaren Bereichs deaktiviert, und `sources` gibt ein `<picture>` aus.

Wenn `performance.media.lazy` aktiviert ist, wird das echte URL hinter einem korrekt dimensionierten Platzhalter nach `data-src` verschoben.

### Tailwind-Klassenhilfen

`bs_tw_merge()` und `bs_tw_variants()` kombinieren Tailwind-Klassen in PHP-Vorlagen mit der Engine, die Blockstudio bereits bündelt.

`bs_tw_merge('px-2 text-sm', 'px-4')` gibt `text-sm px-4` zurück: Die widersprüchliche `px-2` wird entfernt, und der spätere Wert hat Vorrang. Verschachtelte Arrays mit Klassenwerten werden unterstützt.

`bs_tw_variants()` gibt eine kleine aufrufbare Funktion für Komponentenvarianten zurück:

```php
$button = bs_tw_variants([
    'base' => 'inline-flex items-center',
    'variants' => [
        'size' => ['sm' => 'h-8 px-3', 'lg' => 'h-12 px-6'],
    ],
    'defaultVariants' => ['size' => 'sm'],
]);

echo $button(['size' => 'lg', 'class' => 'rounded']);
```

Das gibt `inline-flex items-center h-12 px-6 rounded` aus. Basisklassen, Varianten, Standardvarianten, kombinierte Varianten sowie ein Aufruf mit `class` oder `className` werden unterstützt.

## Produktivkonfiguration

### Performanceprofile

`performance.profile` aktiviert die Frontend-Standardwerte für den Produktivbetrieb an einer zentralen Stelle.

```json title="blockstudio.json"
{
  "performance": {
    "profile": "speed",
    "preload": {
      "links": "off"
    }
  }
}
```

`compat` ist die Standardeinstellung und ändert nichts. `speed` und `strict` aktivieren dieselben Funktionen: Generator-, Emoji-, Feed-, Erkennungs- und benachbarte Beitragsausgaben werden aus dem Head entfernt; oEmbed-Erkennung und Host-Skripte werden entfernt; XML-RPC, Pingbacks und die Erkennung externer Editoren werden deaktiviert; allgemeine Frontend-Assets von Core werden entfernt; Standardwerte für die Bildausgabe werden angewendet; Heartbeat wird außerhalb von Editoren gedrosselt; gleich-originige Dokumente werden bei beabsichtigtem Hover oder Fokus vorab geladen; und der Bildlader von Blockstudio wird verwendet.

Jeder Wert untergeordneter Einstellungen hat Vorrang vor dem Profil, wie oben bei `preload.links`. Das Entfernen von Core-Frontend-Assets solltest du zuerst testen, da davon abhängige Seiten sichtbar beeinträchtigt werden. `Runtime_Settings::current()` gibt das aufgelöste Profil zurück.

`themeDefaults` deckt zwei Aufgaben ab, die Themes sonst selbst umsetzen: `titleTag` und `suppressDirectoryUpdates` blenden das aktive Child- und Parent-Theme aus den Update-Ergebnissen aus.

### Zugriff auf typisierte Einstellungen

`Blockstudio\Settings` liest die Konfiguration mit echten Typen aus, statt einfach zurückzugeben, was in JSON steht.

```php
use Blockstudio\Settings;

$lazy = Settings::get_bool('performance/media/lazy');
$margin = Settings::get_string('performance/media/rootMargin', '300px');
$ttl = Settings::get_int('performance/staticPrerender/ttl', 86400);
$roles = Settings::get_array('users/roles');

foreach (Settings::errors() as $error) {
    error_log($error);
}
```

Fehlerhaftes JSON wird über `Settings::errors()` gemeldet, statt auf Standardwerte zurückzufallen. `Settings::get_raw()` gibt nur zurück, was die aktive Quelle deklariert hat. So lässt sich unterscheiden, ob ein Wert auf `false` gesetzt oder nie festgelegt wurde.

`Settings::fingerprint()` gibt eine stabile Identität für die effektiven Einstellungen zurück. Der Zugriff lädt die Einstellungen neu, wenn sich `blockstudio.json` ändert.

### Ein Cache-Verzeichnis

Alle generierten Dateien liegen jetzt unter `cache.path`, standardmäßig unter `wp-content/blockstudio/cache`.

```json title="blockstudio.json"
{
  "cache": {
    "enabled": true,
    "path": "cache/blockstudio"
  }
}
```

Build-Payloads, Blockregistrierungsdaten, Editor-Assets, kompilierte Tailwind CSS, Render-Dokumente, Island-Fragmente, statische HTML, Graph-Indizes, Aufwärmwarteschlangen und Diagnosen liegen alle unter diesem Stammverzeichnis. Ein relativer Pfad wird ausgehend von `WP_CONTENT_DIR` aufgelöst; ein absoluter Pfad verweist auf ein dediziertes Volume.

Objekte werden unter dem aktuellen Netzwerk und der aktuellen Website abgelegt und anschließend nach einer Runtime-Identität geordnet. Diese Identität ist ein Fingerabdruck der Versionen von Blockstudio, WordPress und PHP, der effektiven Einstellungen, des aktiven Themes und der Plugins, der Erkennungsquellen sowie der beteiligten Quelldateien. Ändert sich eine Eingabe, werden die betroffenen Objekte neu angelegt; die alten werden bereinigt.

Bei einem frischen Build wird nur eine Anfrage ausgeführt: Eine Anfrage erstellt und veröffentlicht das Ergebnis atomar, während die übrigen warten. Bei einer fehlgeschlagenen Aktualisierung wird weiterhin das letzte funktionierende Objekt ausgeliefert, und der Fehler bleibt sichtbar. Mit `Blockstudio\Runtime_Cache::purge('tailwind')` wird ein Bereich geleert.

## Statisches Vorabrendern

Statisches Vorabrendern speichert vollständige, anonyme HTML-Dokumente zwischen und kann sie ausliefern, bevor WordPress startet. Standardmäßig ist die Funktion deaktiviert.

```json title="blockstudio.json"
{
  "performance": {
    "staticPrerender": {
      "enabled": true,
      "ttl": 3600,
      "earlyServe": true,
      "dynamicPaths": ["/account", "/checkout"]
    }
  }
}
```

### Eignung

Nur vollständige, anonyme HTML-Dokumente kommen infrage. Anfragen, die keine GET-Anfragen sind oder Query-Strings enthalten, sowie Admin-, REST-, Ajax-, cron-, Feed-, Such-, Vorschau- und Nonce-Anfragen, Anfragen mit personalisierten Cookies und alle Pfade unter `dynamicPaths` werden umgangen. Eine Antwort kann sich mit einem `<!-- blockstudio:no-cache -->`-Marker vollständig davon ausschließen.

Beim Abgleich von Pfaden werden Grenzen berücksichtigt: `/account` umfasst `/account/orders`, aber nicht `/accounting`.

### Signatur- und Graph-Modi

`invalidate` legt fest, wann Einträge ablaufen. Der Standardmodus `signature` füllt bei einer anonymen Anfrage ohne Treffer eine nach Identität geordnete Antwort und erneuert sie nach Änderungen auf Website-Ebene. Das eignet sich für gewöhnliche Websites.

Der Modus `graph` ist für explizite Build- und Bereitstellungswerkzeuge gedacht. Er erfasst die Quellabhängigkeiten jeder Seite einzeln, damit ein Plan nur betroffene URLs neu erstellt.

```php
use Blockstudio\Static_Prerender_Runtime;

$plan = Static_Prerender_Runtime::build_plan($sourceUrls);

foreach ($plan['affectedUrls'] as $url) {
    $result = render_with_dependencies($url);

    Static_Prerender_Runtime::persist_built_response(
        $url,
        $result['html'],
        $result['files'],
        $result['virtualHashes']
    );
}

Static_Prerender_Runtime::garbage_collect(array_keys($plan['live']));
```

### Frühe Auslieferung

Wenn `earlyServe` aktiviert ist, verwaltet Blockstudio eine kleine Routenkarte pro Website und ein `advanced-cache.php`-Drop-in, das einen geeigneten Treffer ausliefert, bevor WordPress, Plugins oder das Theme starten.

Es überschreibt niemals eine fremde Routenkarte, ein fremdes Drop-in oder eine fremde `WP_CACHE`-Deklaration. Ein Graph-Artefakt prüft jede referenzierte HTML-Datei, bevor die Routenkarte ausgetauscht wird. So bleibt bei einer unvollständigen Bereitstellung der vorherige Graph aktiv. Einträge in Multisite-Installationen bleiben nach Host, Home-Pfad und Website-ID getrennt.

### Aufwärmen und Status

Drei WP-CLI-Befehle decken den Alltag ab:

```bash
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
```

`status` meldet die aktive Identität, Datei- und Byte-Anzahl, Graph-Einträge, Warteschlangenstatus sowie Treffer-, Fehl-, Build- und Fehlerzähler pro Bereich.

## Analyse- und Agentenwerkzeuge

### Analyse-Voreinstellungen

`blockstudio/phpstan` ergänzt seine Blockanalyse um drei Ebenen und einen Befehl, der die vom Projekt ausgewählte Ebene ausführt.

| Voreinstellung | Ergänzungen |
| --- | --- |
| `base` | Die bestehende Analyse von Schema, Vorlage, Hooks, Einstellungen und API. |
| `theme` | Theme-Stammverzeichnisse, Style-Header, Assets, Selektorbereiche, Feldstandardwerte und Grenzen für Wiederholungen. |
| `extreme-theme` | PHPStan `max`, unsicheres PHP, Escaping, Tailwind, JavaScript und Interactivity-Prüfungen. |
| `wordpress-render` | Eine vom Aufrufer bereitgestellte Live-Render-Prüfung zusätzlich zu `extreme-theme`. |

Die Standardwerte stammen aus `blockstudio.json`, damit interaktive Ausführungen, CI und Commit-Hooks dieselbe Konfiguration verwenden:

```json title="blockstudio.json"
{
  "phpstan": {
    "preset": "theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}
```

```bash
vendor/bin/blockstudio-phpstan --root . -- --no-progress
```

Die Rückgabecodes sind `0` bei Erfolg, `1` bei Diagnosen und `2` bei ungültiger Verwendung. Der Wrapper erstellt seine Konfiguration im temporären Systemverzeichnis. Dadurch werden keine generierte Konfiguration, Baseline oder Cache-Dateien im Projekt abgelegt. Außerdem erhöht er das Speicherlimit von PHPStan auf `1G`.

Außerdem ist ein BC-Math-Provider enthalten, sodass die JavaScript-Prüfungen `ext-bcmath` nicht mehr benötigen.

### Verwalteter Commit-Hook

Mit einer Einstellung und einem Befehl wird die konfigurierte Voreinstellung zur Commit-Schranke.

```json title="blockstudio.json"
{
  "githooks": {
    "commit": true
  }
}
```

```bash
vendor/bin/blockstudio-githooks sync
```

Die Synchronisierung schreibt den Hook und einen Besitznachweis in Git's common-Verzeichnis, setzt `core.hooksPath` auf das verwaltete Verzeichnis und verkettet einen zuvor konfigurierten Pre-Commit-Hook. Der Hook ermittelt das Repository und das Projektstammverzeichnis beim Commit. Dadurch funktionieren verknüpfte Checkouts und Pfade mit Leerzeichen.

Der Hook führt nur `vendor/bin/blockstudio-phpstan` aus und sonst nichts; er formatiert oder ändert niemals Dateien. Wenn du `commit` auf `false` setzt und erneut synchronisierst oder `blockstudio-githooks remove` ausführst, wird der gespeicherte Hook-Pfad wiederhergestellt und es werden nur von Blockstudio verwaltete Dateien gelöscht.

### Projektvertrag

`blockstudio-agents` schreibt ein `AGENTS.md`, das festhält, wo sich Blöcke befinden, was in diesem Projekt als Seite gilt, welche Funktionen aktiviert sind und was der Analysator zurückweist.

```bash
vendor/bin/blockstudio-agents
```

Das Dokument wird aus dem Projekt abgeleitet und nicht aus einer Vorlage erstellt. Ein Theme mit einem `style.css`-Header, Blöcken und dateibasierten Seiten erhält einen anderen Vertrag als ein Plugin, das nur Blöcke registriert. Darin stehen die erkannten Anzahlen, Verzeichnisse, Namensräume und Vorlagensprachen. `blockstudio.json` legt fest, welche Funktionen aufgeführt werden. Ein Projekt ohne statisches Vorabrendern wird daher nicht erwähnt.

Der Abschnitt zur Korrektheit wird Ebene für Ebene aus den Regeldateien der ausgewählten Voreinstellung gelesen. Fügt eine Voreinstellung eine Regel hinzu, ändert sich dadurch jeder generierte Vertrag.

Die Besitzverwaltung funktioniert wie beim Commit-Hook. Eine Datei ohne generierten Marker wird abgelehnt, statt ersetzt zu werden, sofern `--force` nichts anderes festlegt. Ein Notizbereich am Ende bleibt bei der Neuerstellung erhalten. `--check` gibt `1` zurück, wenn der Vertrag veraltet ist, und `--stdout` gibt ihn aus, ohne das Dateisystem anzutasten.

### Dokumentationsindex

`blockstudio-llm.txt` ist jetzt ein Index statt einer Zusammenführung. Jedes veröffentlichte Dokument erscheint einmal in seinem Abschnitt und Unterabschnitt mit Route, Quelldatei, einer kurzen Zweckbeschreibung und den zugehörigen Kennungen: Einstellungspfade, Hook-Namen, PHP-Funktionen und -Klassen sowie Befehle.

```text
## Docs / Dev / Inspection Tools

### Canvas
route: /docs/dev/canvas
file: docs/docs/dev/canvas.md
purpose: A visual workspace and public inventory API for Blockstudio content.
settings: dev/canvas/enabled, ui
hooks: blockstudio/settings/dev/canvas/admin_bar, blockstudio/settings/dev/canvas/enabled
php: Blockstudio\Canvas, Canvas::documents(), Canvas::inventory()
```

Ein Agent liest den Index, findet das eine Dokument, das die gesuchte Kennung enthält, und öffnet es. Die bisherige Zusammenführung mit einer halben Megabyte wird weiterhin unter `/blockstudio-llm-full.txt` generiert und veröffentlicht; sie wird nur nicht mehr als Erstes ausgegeben.

## Kanonische Block-Tags

Ein eigenständiger Befehl schreibt Präfix- und Alias-Kurzformen in die kanonische Schreibweise `<bs:namespace-slug>` um. Sie enthält den tatsächlichen Blocknamen und lässt sich ohne geladenen Projektfilter auflösen.

Mit einem Präfix `brand` für `theme-components` und einem Präfix `ui` für `bsui` bedeutet diese Kurzform:

```html
<brand-card>
  <ui-input />
</brand-card>
```

dasselbe wie:

```html
<bs:theme-components-card>
  <bs:bsui-input />
</bs:theme-components-card>
```

Präfixe und exakte Aliase funktionieren weiterhin und gelten nicht als veraltet. Der Befehl lädt WordPress nicht und schreibt ohne `--apply` nichts:

```bash
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/prefixes.json \
  --known-blocks=/tmp/blocks.json \
  --report=/tmp/tag-migration.json \
  --dry-run
```

`--prefix-map` ordnet jedes Präfix seinen Namespaces zu, und `--known-blocks` listet die registrierten Blocknamen auf. Der Bericht hält Zuordnungen von alten zu kanonischen Schreibweisen samt Vorkommenszahlen, Dateihashes und separaten Listen unbekannter Tags, mehrdeutiger Aliase und dynamischer Tags fest. `--apply` verweigert das Schreiben, solange noch Einträge vorhanden sind, außer wenn `--allow-unresolved` übergeben wird.

Gepaarte, verschachtelte und selbstschließende Markup-Tags werden verarbeitet, einschließlich wörtlicher Tags in PHP-Strings. Nur Tagnamen werden geändert, ein zweiter Durchlauf nimmt keine Änderungen vor, und Beispiele in Kommentaren, Codeblöcken, `<pre>` oder `<code>` werden nur im Bericht aufgeführt.

## Standardverhalten

Die Installation von 7.6 ändert für sich genommen nichts.

**Das Leistungsprofil ist standardmäßig auf `compat` eingestellt.** Die Ausgabe im Head, oEmbed, XML-RPC, Heartbeat, Bildstandards, Link-Prefetching, Lazy Loading und das Frontend-`<title>` bleiben so, wie WordPress und das Theme sie eingerichtet haben.

**Diese Funktionen bleiben deaktiviert, bis du sie aktivierst:** alle `performance.staticPrerender`-, `performance.measurement`-, `performance.media`- und `themeDefaults`-Schlüssel sowie `githooks.commit`, `dev.canvas.enabled`, `ui.enabled`, `tailwind.enabled` und `blockTags.enabled`. Solange statisches Prerendering deaktiviert ist, werden keine Dateien geschrieben und kein Drop-in installiert.

**Canvas und Render arbeiten passiv.** Sie lesen vorhandene Registries und rendern nur, was ein Aufrufer anfordert; weder greifen sie in die Frontend-Ausgabe ein noch registrieren sie Routen. Für den Canvas-Administrationsbildschirm sind weiterhin `dev.canvas.enabled` und `edit_posts` erforderlich.

**Eine strengere Analyse musst du ausdrücklich benennen.** Die Installation von `blockstudio/phpstan` aktiviert nur die Basiserweiterung, und der kanonische Befehl führt `base` aus, sofern im Projekt kein Preset angegeben ist.

**Generierte Dateien erfordern den passenden Befehl.** `githooks.commit` tut nichts, bis `blockstudio-githooks sync` ausgeführt wird, und `AGENTS.md` nichts, bis `blockstudio-agents` ausgeführt wird.

## Upgrade von 7.5

Die Anforderungen bleiben unverändert: PHP 8.2 oder neuer, WordPress 6.7 oder neuer.

```bash
composer require blockstudio/blockstudio
```

**Caches werden einmal neu aufgebaut.** Zur Laufzeitidentität gehört die Version von Blockstudio. Daher ist die erste Anfrage nach dem Upgrade ein Kaltstart und alte Objekte werden bereinigt. Der alte Tailwind-Cache unter `wp-content/uploads/blockstudio/tailwind/cache` kann gelöscht werden; ein Snippet, das dieses Verzeichnis mit einem Glob-Muster durchsucht hat, sollte stattdessen `Blockstudio\Runtime_Cache::purge('tailwind')` aufrufen.

Das flache `wp-content/blockstudio/cache/runtime`-Verzeichnis aus Versionen vor 7.6 wird automatisch aus dem aktiven Pfad umbenannt und in begrenzten WP-Cron-Durchläufen entfernt. Große Verzeichnisbäume mit alten Sperrdateien müssen daher nicht während einer Deployment-Anfrage gelöscht werden.

**Generierte Dateien haben festgelegte Zuständigkeiten.** `assets/media.json` gehört in die Versionsverwaltung oder in einen Build-Schritt. Die Routenübersicht, das Drop-in `advanced-cache.php` und die Deklaration `WP_CACHE` sind nur vorhanden, solange `earlyServe` aktiviert ist; der Pre-Commit-Hook nur, solange die Synchronisierung aktiv ist. Alle anderen generierten Dateien liegen unter `cache.path` und können gefahrlos gelöscht werden.

**Nichts wurde entfernt oder umbenannt.** `bs_render_block()`, `bs_block()`, `Blockstudio\Pages` und `Blockstudio\Patterns` bleiben die kanonischen dateibasierten Inhaltsbereiche.

**Ein Rollback erfolgt je Funktion.** `performance.profile` zurück auf `compat`, `staticPrerender.enabled` auf `false`, `githooks.commit` auf `false` samt einem `sync` und `cache.enabled` auf `false` machen jeweils eine Ebene rückgängig.

Eine sinnvolle Reihenfolge für die Einführung:

1. Setze `performance.profile` auf `speed` und prüfe dann die Head-Ausgabe, Feeds und alle Plugins, die auf oEmbed oder XML-RPC angewiesen sind.
2. Generiere `assets/media.json`, verschiebe die Templates nach `bs_media_image()` und aktiviere dann `performance.media.lazy`.
3. Aktiviere `performance.staticPrerender` bei deaktiviertem `earlyServe`, prüfe Treffer mit `wp bs prerender status` und aktiviere dann `earlyServe`.
4. Führe `blockstudio-phpstan --preset theme` aus, bis keine Probleme mehr gemeldet werden, bevor du ein Preset hinter `githooks.commit` legst.

## Wo du die Details findest

- [Canvas](https://blockstudio.dev/de/docs/dev/canvas/) und sein [Bestandsverzeichnis und die Dokument-API](https://blockstudio.dev/de/docs/dev/canvas/#public-inventory-and-document-api)
- [Rendering](https://blockstudio.dev/de/docs/blocks/rendering/#structured-compositions-and-complete-documents), [UI Components](https://blockstudio.dev/de/ui/#public-inventory-and-examples) und [UI Composition](https://blockstudio.dev/de/ui/composition/)
- [Einstellungen](https://blockstudio.dev/de/docs/general/settings/) und [Leistung](https://blockstudio.dev/de/docs/general/settings/#performance)
- [Leistung](https://blockstudio.dev/de/docs/production/performance/), [Caching](https://blockstudio.dev/de/docs/production/caching/) und [Static Prerendering](https://blockstudio.dev/de/docs/production/static-prerendering/)
- [Tailwind CSS](https://blockstudio.dev/de/docs/tailwind/#template-composition-helpers)
- [PHPStan](https://blockstudio.dev/de/docs/dev/phpstan/): [Presets](https://blockstudio.dev/de/docs/dev/phpstan/#analysis-presets), [kanonischer Befehl](https://blockstudio.dev/de/docs/dev/phpstan/#canonical-command), [verwalteter Commit-Hook](https://blockstudio.dev/de/docs/dev/phpstan/#managed-commit-hook) und der [Projektvertrag](https://blockstudio.dev/de/docs/dev/phpstan/#project-contract-for-coding-agents)
- [KI-Integration](https://blockstudio.dev/de/docs/dev/ai/): der Dokumentationsindex und der vollständige Text
- [Migration](https://blockstudio.dev/de/docs/dev/migration/v7/#canonical-block-tags) und [PHP Hooks](https://blockstudio.dev/de/docs/blocks/hooks/php/)
