
Blockstudio 7.6 pozwala odczytywać projekt i renderować jego elementy z poziomu PHP, a domyślne ustawienia produkcyjnego frontendu przenosi do `blockstudio.json`: wykaz API, samodzielne renderowanie, pomocniki szablonów dla mediów i Tailwind, profile wydajności, jeden katalog pamięci podręcznej, wstępne renderowanie statyczne z wczesnym serwowaniem, bardziej rygorystyczne ustawienia analizy oraz generowane narzędzia projektowe dla agentów programistycznych.

Większość możliwości wydania opiera się na dwóch wywołaniach. `Canvas::inventory()` zwraca każdą stronę,
blok, wzorzec, szablon edytora witryny, część szablonu i przykład UI dołączony do projektu. `Render::document()` zwraca gotowy HTML dla dowolnego z nich,
wraz dokładnie z tymi zasobami, które wykorzystano podczas renderowania.

> **Aktualizacja 7.6.2:** strony oparte na plikach nie są już uzgadniane podczas zwykłych żądań WordPress. Uruchom `wp bs pages sync` lub wywołaj `Blockstudio\Pages::reconcile()` podczas stosowania zmian źródłowych. Domyślne wartości tras kolekcji i `templateFor` korzystają z utrwalonej konfiguracji środowiska uruchomieniowego, a jawne uzgadnianie pozwala uniknąć wcześniejszego, dużego zapytania OR po metadanych dla wielu języków. Krótkotrwała opcja `themeDefaults.syncPagesInDevelopment` została usunięta, ponieważ synchronizacja stron nie odbywa się już w hakach żądań. `Pages::init()` służy teraz wyłącznie do inicjalizacji; integracje, które przekazywały `force`, muszą używać `Pages::reconcile()` lub CLI. Otwarcie Canvas nadal wykonuje jedno jawne uzgadnianie uwierzytelnionej listy elementów do edycji.

> **7.6.12 aktualizacja:** Arkusze stylów edytora są teraz poprzedzane prefiksami podczas jednego przebiegu przepisywania zamiast osobnej kompilacji SASS dla każdego zasobu, dzięki czemu kompilacja edytora od zera w witrynie z wieloma blokami nie grozi już przekroczeniem niewielkiego limitu pamięci. Buforowana, wstępnie renderowana strona, której arkusz stylów Tailwind z hashem zawartości został usunięty z pamięci podręcznej, jest renderowana ponownie zamiast wyświetlać się bez stylów; dotyczy to zarówno pamięci podręcznej PHP, jak i drop-in Early Serve. Atrybuty bloków zapisane na najwyższym poziomie są odczytywane podczas renderowania zamiast pomijane, dzięki czemu schemat Blockstudio zarejestrowany w `WP_Block_Type` jest uwzględniany przez programowe narzędzia zapisujące.

> **7.6.11 aktualizacja:** Instalacja artefaktów Graph atomowo zastępuje dokument trasy, gdy kopia w magazynie zmieniła się pod tym samym kluczem, pozostawia identyczne dokumenty bez zmian i raportuje trasy promowane, zastąpione, pominięte oraz zachowane za pośrednictwem `Static_Prerender_Early_Serve::last_promotion()`.

> **7.6.10 aktualizacja:** Trafienia w pamięci podręcznej środowiska uruchomieniowego wykrywają teraz usunięte skompilowane zasoby nawet w trakcie opóźnienia debouncingu obserwatora, a płaskie pamięci podręczne środowiska sprzed wersji 7.6 są atomowo poddawane kwarantannie i usuwane w ograniczonych partiach cron. Globalne elementy z pakietu UI są emitowane raz na stronę. Early Serve w trybie Graph może obsługiwać trasy renderowane na żywo, których nie ma na wdrożonej mapie tras, korzystając z pamięci podręcznej tożsamości. Tailwind może opcjonalnie emitować plik pamięci podręcznej z hashem zawartości za pomocą `tailwind.output: "link"`; domyślnie nadal używane jest wyjście inline.

W skrócie:

- **Spis projektu**: `Canvas::inventory()` zwraca każdy zarejestrowany rekord wraz ze źródłami i stabilną kolejnością wyświetlania.
- **Wybór ukierunkowany**: wskazanie bloków i stron zawęża wykrywanie, synchronizację, renderowanie i kompilację do tych rekordów.
- **Renderowanie samodzielne**: `Blockstudio\Render` zwraca gotowe HTML dla bloku, kompozycji lub całego dokumentu.
- **UI rodziny komponentów**: `Blockstudio\Ui` grupuje dołączoną bibliotekę w jedną publiczną rodzinę dla każdego komponentu, wraz z przykładem.
- **Stabilne wymiary obrazów**: `bs_media_image()` renderuje zasoby motywu z rzeczywistymi wymiarami z wygenerowanego pliku `assets/media.json`.
- **Tailwind funkcje pomocnicze klas**: `bs_tw_merge()` i `bs_tw_variants()` łączą klasy w PHP z uwzględnieniem konfliktów.
- **Profile wydajności**: `performance.profile` jednocześnie włącza produkcyjne ustawienia domyślne frontendu; wartości podrzędne je nadpisują.
- **Dostęp do typowanych ustawień**: `Settings::get_bool()` i jego odpowiedniki odczytują `blockstudio.json` z rzeczywistymi typami i zgłaszają błędy parsowania.
- **Jeden katalog pamięci podręcznej**: każdy wygenerowany plik znajduje się w `cache.path`, z kluczem opartym na tożsamości środowiska uruchomieniowego.
- **Statyczne wstępne renderowanie**: anonimowe HTML można buforować, unieważniać za pomocą grafu zależności i serwować przed uruchomieniem WordPress.
- **Gotowe konfiguracje analizy**: `theme`, `extreme-theme` i `wordpress-render` rozszerzają `blockstudio/phpstan` poza szablony bloków.
- **Zarządzany hook zatwierdzania**: `blockstudio-githooks sync` zapisuje hook pre-commit, zarządza nim i uruchamia w nim skonfigurowaną gotową konfigurację.
- **Kontrakt projektu**: `blockstudio-agents` zapisuje plik `AGENTS.md` opisujący, co tworzy autor projektu, jakie funkcje włącza i czego wymaga jego gotowa konfiguracja.
- **Indeks dokumentacji**: plik kontekstu AI jest teraz indeksem wszystkich dokumentów, ich przeznaczenia i przypisanych im identyfikatorów.
- **Kanoniczne znaczniki bloków**: samodzielne polecenie przepisuje skrócone prefiksy i aliasy do postaci `<bs:namespace-slug>`; dostępny jest tryb próbny.
- **Zgodność domyślnie**: żadna z powyższych funkcji nie zmienia witryny, dopóki nie zostanie wskazana w `blockstudio.json`.

## Odczytywanie i renderowanie projektu

### Spis projektu

`Canvas::inventory()` zwraca w jednej zwykłej tablicy wszystko, co rejestruje projekt, bez renderowania czegokolwiek.

```php
use Blockstudio\Canvas;

$result = Canvas::inventory();

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

Rekordy są pogrupowane według typu: `pages`, `blocks`, `patterns`, `templates`, `parts` i `ui`. `order` określa stabilną kolejność wyświetlania dla wszystkich typów, `sources` przypisuje każdemu rekordowi ścieżki źródłowe, a `warnings` i `errors` zbierają problemy w postaci ustrukturyzowanych wpisów.

Rekordy bloków zawierają `id`, `name`, `title`, `source`, `path`, `provenance` oraz gotowy do renderowania element `declaration`. Rekordy stron zachowują `source` jako stabilną tożsamość, a `path` jako szablon używany do renderowania.

### Wybór ukierunkowany

Wskazanie rekordów zawęża zakres pracy zamiast filtrować wyniki dopiero później.

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

Zwraca to jeden blok i jedną stronę. `patterns`, `templates`, `parts` i `ui` pozostają puste, a ich źródła nie są odczytywane, synchronizowane, renderowane ani kompilowane.

Zasady są precyzyjne:

- Brak kluczy typów powoduje załadowanie wszystkich typów.
- `true`, `null` lub `"*"` powoduje załadowanie wszystkich rekordów danego typu.
- Ciąg znaków lub lista dopasowuje dokładnie identyfikator, nazwę, slug, ścieżkę lub ścieżkę źródłową.
- Pusty ciąg znaków, pusta lista lub `false` powoduje, że nie są ładowane żadne rekordy danego typu.
- Gdy podano dowolny klucz typu, pominięte typy pozostają nietknięte.

Nieistniejące już identyfikatory są zwracane w `deleted` zamiast powodować błąd, a endpoint odświeżania Canvas REST stosuje tę samą zasadę do parametrów `blocks` i `pages`.

`Canvas::documents()` przyjmuje ten sam wybór i dodaje po jednym wyrenderowanym dokumencie na rekord. Wybrane strony są renderowane w odtworzonym kontekście frontendu, dzięki czemu warunki zapytań, klasy body, shortcodes, układy, przekierowania i callbacki enqueue widzą tę stronę, a nie żądanie, które o nią poprosiło.

### Renderowanie samodzielne

`Blockstudio\Render` zwraca wyrenderowane HTML jako ciąg znaków, korzystając z tego samego potoku co frontend.

```php
use Blockstudio\Render;

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

U podstaw leży jeden kształt deklaracji z czterema kluczami: `name`, `attributes`, `content` i `children`. `root`, `data`, `inner`, `innerBlocks`, `layers` i `example` to ułatwienia wprowadzania danych, które `Render::normalize()` sprowadza do tej postaci. Elementy potomne są renderowane rekurencyjnie, a nieprawidłowe dane wejściowe powodują wyjątek wskazujący problematyczny blok.

`Render::document()` opakowuje wynik w kompletny, samodzielny dokument HTML.

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

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

`body` to wyłącznie wynik bloku, `html` to złożony dokument, `blocks` zawiera nazwy bloków, które wniosły do niego swój wkład, a `assets` dzieli znacznikowanie na `head`, `footer`, `styles`, `scripts`, `modules`, `interactivity`, `ui` i `tailwind`. Zasoby są ograniczone do tych, które zostały użyte podczas renderowania, więc zasoby przeznaczone wyłącznie dla edytora nigdy się nie pojawiają.

`Render::document_from_html()` opakowuje treść HTML wyrenderowaną gdzie indziej, a `Render::content()` renderuje serializowaną treść bloku bez dokumentu. Wywołaj `Blockstudio\Batch_Render::reset()` między dokumentami w jednym procesie PHP; `Canvas::documents()` już to robi.

### Rodziny komponentów UI

`Blockstudio\Ui` udostępnia dołączoną bibliotekę UI w postaci jednego wpisu dla każdego publicznego komponentu zamiast listy wewnętrznych części.

`Ui::inventory()` zwraca po jednym wpisie dla każdej rodziny: z jej głównym blokiem, tytułem i potrzebnymi blokami implementacyjnymi. `Ui::examples()` dodaje deterministyczną deklarację dla każdej rodziny: z zachowanymi wartościami domyślnymi, wymaganymi warstwami potomnymi zagnieżdżonymi w rodzicach i stabilnym tekstem przykładowym w pustych polach. Ta deklaracja jest kanoniczna, więc trafia bezpośrednio do `Render::document()`.

Canvas grupuje je w ten sam sposób. Dołączony element UI pojawia się jako jeden przykład dla każdej rodziny w typie `ui`, a rejestracje implementacyjne nie trafiają do `blocks`.

Rodziny zaprojektowano z myślą o składaniu: selektor otwiera się w oknie dialogowym, a jego lista nakłada się na element wyzwalający; menu i comboboksy są kotwiczone za pomocą stałych współrzędnych obszaru widoku, które nie zmieniają się podczas przewijania; okna modalne układają się warstwami i zamykają po jednym naciśnięciu Escape; każda stopka łączy ten sam przycisk zamykania z wariantem. Zasady działania tych połączeń i niezmienniki, które je podtrzymują, opisuje [rozdział o kompozycjach](https://blockstudio.dev/pl/ui/composition/); w [/ui/examples](https://blockstudio.dev/pl/ui/examples/) można zobaczyć działające kompozycje.

## Funkcje pomocnicze szablonów

### Stabilne wymiary obrazów

`bs_media_image()` renderuje zasoby motywu z rzeczywistą szerokością i wysokością oraz zarezerwowanymi proporcjami obrazu, dzięki czemu obrazy spoza biblioteki mediów nie powodują już przesuwania układu.

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

Wynikiem jest `figure.blockstudio-media` z elementem `aspect-ratio` wbudowanym wokół elementu `img`, który zawiera rzeczywiste wartości `width`, `height`, `loading` i `decoding`. Wymiary pochodzą z wygenerowanego pliku `assets/media.json`, zapisanego przez `Blockstudio\Media_Metadata_Builder` w ramach procesu kompilacji lub ręcznie.

`src` przyjmuje ścieżkę względną wobec motywu, ścieżkę bezwzględną lub pełny URL, a `attachmentId` obsługuje obrazy z biblioteki mediów. `eager` wyłącza leniwe ładowanie powyżej linii zgięcia, a `sources` emituje `<picture>`.

Gdy włączono `performance.media.lazy`, rzeczywisty element URL trafia do `data-src` za prawidłowo zwymiarowanym elementem zastępczym.

### Funkcje pomocnicze klas Tailwind

`bs_tw_merge()` i `bs_tw_variants()` łączą klasy Tailwind w szablonach PHP, korzystając z silnika Blockstudio, który jest już dołączony.

`bs_tw_merge('px-2 text-sm', 'px-4')` zwraca `text-sm px-4`: konfliktujące `px-2` jest usuwane, a późniejsza wartość ma pierwszeństwo. Akceptowane są zagnieżdżone tablice wartości klas.

`bs_tw_variants()` zwraca niewielką funkcję do wywołania dla wariantów komponentu:

```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']);
```

Wynikiem jest `inline-flex items-center h-12 px-6 rounded`. Obsługiwane są klasy bazowe, warianty, warianty domyślne, warianty złożone oraz przekazywane przy każdym wywołaniu `class` lub `className`.

## Konfiguracja produkcyjna

### Profile wydajności

`performance.profile` włącza w jednym miejscu produkcyjne ustawienia domyślne frontendu.

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

`compat` jest ustawieniem domyślnym i niczego nie zmienia. `speed` i `strict` włączają ten sam zestaw: usuwają z sekcji head generator, emoji, kanały informacyjne, mechanizm wykrywania i wyjście z wpisami sąsiadującymi; pomijają wykrywanie oEmbed i skrypty hosta; wyłączają XML-RPC, pingbacki i zdalne wykrywanie edytora; usuwają ogólne zasoby frontendu rdzenia; stosują domyślne ustawienia wyjścia obrazów; ograniczają działanie Heartbeat poza edytorami; wstępnie pobierają dokumenty z tej samej domeny przy najechaniu kursorem lub zamiarze ustawienia fokusu; oraz używają modułu ładującego obrazy z Blockstudio.

Każda wartość podrzędna zastępuje profil, tak jak robi to powyżej `preload.links`. Najpierw warto przetestować usuwanie zasobów frontendu rdzenia, ponieważ strona, która ich wymaga, będzie wyraźnie uszkodzona. `Runtime_Settings::current()` udostępnia rozwiązany profil.

`themeDefaults` obejmuje dwie rzeczy, które motywy zwykle muszą tworzyć samodzielnie: `titleTag` oraz `suppressDirectoryUpdates`, które ukrywa aktywny motyw potomny i nadrzędny w wynikach aktualizacji.

### Dostęp do typowanych ustawień

`Blockstudio\Settings` odczytuje konfigurację z rzeczywistymi typami zamiast zwracać dowolną wartość przechowywaną przez JSON.

```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);
}
```

Nieprawidłowe JSON jest zgłaszane przez `Settings::errors()` zamiast rozwiązywać się do wartości domyślnych. `Settings::get_raw()` zwraca tylko to, co zadeklarowało aktywne źródło, dzięki czemu można odróżnić wartość ustawioną na `false` od wartości, której nigdy nie ustawiono.

`Settings::fingerprint()` zwraca stabilną tożsamość efektywnych ustawień, a dostęp jest ponownie ładowany po zmianie `blockstudio.json`.

### Jeden katalog pamięci podręcznej

Każdy wygenerowany plik znajduje się teraz w `cache.path`, którego domyślną wartością jest `wp-content/blockstudio/cache`.

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

Ładunki kompilacji, dane rejestracji bloków, zasoby edytora, skompilowane pliki Tailwind CSS, dokumenty renderowania, fragmenty wysp, statyczne pliki HTML, indeksy Graph, kolejki rozgrzewania i diagnostyka znajdują się w tym katalogu głównym. Ścieżka względna jest rozwiązywana względem `WP_CONTENT_DIR`, a ścieżka bezwzględna kieruje do dedykowanego woluminu.

Obiekty są porządkowane według bieżącej sieci i witryny, a następnie według tożsamości środowiska uruchomieniowego: odcisku palca wersji Blockstudio, WordPress i PHP, efektywnych ustawień, aktywnego motywu i wtyczek, źródeł wykrywania oraz użytych plików źródłowych. Po zmianie danych wejściowych powstają nowe obiekty dla tych, których dotyczy zmiana; stare są usuwane.

Kompilacje od zera są wykonywane w trybie single-flight: jedno żądanie tworzy i atomowo publikuje wynik, podczas gdy pozostałe czekają. Nieudane odświeżenie pozostawia ostatni poprawny obiekt do wyświetlania, a błąd jest nadal widoczny; polecenie `Blockstudio\Runtime_Cache::purge('tailwind')` czyści jeden zakres.

## Statyczne wstępne renderowanie

Statyczne wstępne renderowanie buforuje kompletne, anonimowe dokumenty HTML i może je serwować przed uruchomieniem WordPress. Domyślnie jest wyłączone.

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

### Kwalifikacja

Kwalifikują się tylko kompletne, anonimowe dokumenty HTML. Pomijane są żądania inne niż GET, ciągi zapytania, panel administracyjny, REST, Ajax, cron, kanały informacyjne, wyszukiwanie, podglądy, żądania zawierające nonce, spersonalizowane pliki cookie oraz każda ścieżka w obrębie `dynamicPaths`. Odpowiedź może całkowicie wyłączyć tę funkcję za pomocą znacznika `<!-- blockstudio:no-cache -->`.

Dopasowywanie ścieżek uwzględnia granice, więc `/account` obejmuje `/account/orders`, ale nie `/accounting`.

### Tryby sygnatury i grafu

`invalidate` określa, kiedy wpisy wygasają. Domyślny tryb `signature` wypełnia odpowiedź powiązaną z tożsamością po anonimowym żądaniu bez trafienia i rotuje ją po zmianach w obrębie witryny, co sprawdza się w zwykłej witrynie.

Tryb `graph` służy do jawnych narzędzi kompilacji i wdrażania. Rejestruje własne zależności źródłowe każdej strony, dzięki czemu plan przebudowuje tylko te adresy URL, których dotyczy zmiana.

```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']));
```

### Wczesne serwowanie

Gdy włączono `earlyServe`, Blockstudio zarządza niewielką mapą tras dla każdej witryny i drop-inem `advanced-cache.php`, który przesyła strumieniowo pasujące trafienie, zanim zostaną uruchomione WordPress, wtyczki lub motyw.

Nigdy nie nadpisuje obcej mapy, drop-inu ani deklaracji `WP_CACHE`. Zanim mapa zostanie podmieniona, artefakt grafu sprawdza każdy wskazany plik HTML, dzięki czemu niekompletne wdrożenie pozostawia poprzedni graf aktywny. Wpisy w konfiguracji multisite pozostają odizolowane według hosta, ścieżki strony głównej i identyfikatora witryny.

### Rozgrzewanie i stan

Trzy polecenia WP-CLI wystarczą do codziennego użytku:

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

`status` raportuje aktywną tożsamość, liczbę plików i bajtów, rekordy grafu, stan kolejki oraz liczniki trafień, chybień, kompilacji i błędów dla każdego zakresu.

## Narzędzia do analizy i pracy agentów

### Gotowe konfiguracje analizy

`blockstudio/phpstan` zyskuje trzy dodatkowe warstwy ponad analizą bloków oraz jedno polecenie uruchamiające wybraną przez projekt warstwę.

| Gotowa konfiguracja | Co dodaje |
| --- | --- |
| `base` | Dotychczasową analizę schematów, szablonów, hooków, ustawień i API. |
| `theme` | Katalogi główne motywów, nagłówki stylów, zasoby, ograniczanie zakresu selektorów, domyślne wartości pól i limity repeaterów. |
| `extreme-theme` | PHPStan `max`, niebezpieczne PHP, escapowanie, Tailwind, JavaScript i kontrole Interactivity. |
| `wordpress-render` | Udostępniane przez wywołującego sondowanie renderowania na żywo, uzupełniające `extreme-theme`. |

Wartości domyślne pochodzą z `blockstudio.json`, dzięki czemu uruchomienia interaktywne, CI i hooki zatwierdzania korzystają z jednej konfiguracji:

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

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

Kody wyjścia to `0` przy powodzeniu, `1` w przypadku diagnostyki i `2` przy nieprawidłowym użyciu. Wrapper składa swoją konfigurację w tymczasowym katalogu systemowym, więc wygenerowana konfiguracja, punkt odniesienia ani pamięć podręczna nie trafiają do projektu; zwiększa też limit pamięci PHPStan do `1G`.

Dołączony jest też dostawca BC Math, dzięki czemu kontrole JavaScript nie wymagają już `ext-bcmath`.

### Zarządzany hook zatwierdzania

Jedno ustawienie i jedno polecenie zamieniają skonfigurowaną gotową konfigurację w kontrolę zatwierdzania.

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

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

Synchronizacja zapisuje hook i rekord własności w katalogu wspólnym Git, kieruje `core.hooksPath` do zarządzanego katalogu i łączy go z wcześniej skonfigurowanym hookiem pre-commit. Hook ustala repozytorium i katalog główny projektu w chwili zatwierdzania, dzięki czemu działają połączone kopie robocze i ścieżki zawierające spacje.

Hook uruchamia `vendor/bin/blockstudio-phpstan` i nic więcej; nigdy nie formatuje ani nie przepisuje plików. Ustawienie `commit` na `false` i ponowna synchronizacja lub uruchomienie `blockstudio-githooks remove` przywraca zapisaną ścieżkę hooka i usuwa wyłącznie pliki należące do Blockstudio.

### Kontrakt projektu

`blockstudio-agents` zapisuje plik `AGENTS.md`, który określa, gdzie znajdują się bloki, czym w tym projekcie jest strona, które funkcje są włączone i co analizator odrzuci.

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

Dokument jest generowany na podstawie projektu, a nie szablonu. Motyw z nagłówkiem `style.css`, blokami i stronami opartymi na plikach otrzymuje inny kontrakt niż wtyczka rejestrująca wyłącznie bloki; kontrakt zawiera liczbę elementów, katalogi, przestrzenie nazw i języki szablonów wykryte przez skaner. `blockstudio.json` decyduje o widocznych funkcjach, więc projekt bez statycznego wstępnego renderowania nie zobaczy o nim wzmianki.

Sekcja dotycząca poprawności jest odczytywana warstwa po warstwie z plików reguł wybranej gotowej konfiguracji, więc dodanie do niej reguły zmienia każdy wygenerowany kontrakt.

Zasady własności są takie same jak w przypadku hooka zatwierdzania. Plik bez wygenerowanego znacznika jest odrzucany zamiast zastępowany, chyba że `--force` stanowi inaczej; sekcja notatek na końcu pozostaje po ponownym generowaniu; `--check` kończy działanie z kodem `1`, gdy kontrakt jest nieaktualny; a `--stdout` wyświetla go bez modyfikowania systemu plików.

### Indeks dokumentacji

`blockstudio-llm.txt` jest teraz indeksem zamiast sklejeniem dokumentów. Każdy opublikowany dokument pojawia się raz, w swojej sekcji i podsekcji, wraz ze swoją trasą, plikiem źródłowym, krótkim opisem przeznaczenia i przypisanymi mu identyfikatorami: ścieżkami ustawień, nazwami hooków, funkcjami i klasami PHP oraz poleceniami.

```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()
```

Agent odczytuje indeks, znajduje dokument zawierający interesujący go identyfikator i otwiera ten dokument. Wcześniejsze połączenie o rozmiarze pół megabajta nadal jest generowane i publikowane pod `/blockstudio-llm-full.txt`; nie jest już pierwszą rzeczą, którą otrzymuje każdy.

## Kanoniczne tagi bloków

Samodzielne polecenie przepisuje skróty prefiksów i aliasów na kanoniczną pisownię `<bs:namespace-slug>`, która podaje rzeczywistą nazwę bloku i jest rozpoznawana bez załadowanego filtra projektu.

Przy prefiksie `brand` dla `theme-components` i prefiksie `ui` dla `bsui` ten skrót:

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

oznacza to samo co:

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

Prefiksy i dokładne aliasy nadal działają i nie są przestarzałe. Polecenie nie ładuje WordPress i niczego nie zapisuje bez `--apply`:

```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` przypisuje każdy prefiks do jego przestrzeni nazw, a `--known-blocks` wyświetla zarejestrowane nazwy bloków. Raport zapisuje mapowania ze starych nazw na kanoniczne wraz z liczbą wystąpień i skrótami poszczególnych plików, a także osobne listy nieznanych tagów, niejednoznacznych aliasów i tagów dynamicznych. `--apply` odmawia zapisu, dopóki którekolwiek z nich pozostają, chyba że podano `--allow-unresolved`.

Obsługiwane są sparowane, zagnieżdżone i samozamykające się znaczniki, w tym dosłowne tagi w ciągach PHP. Zmieniane są tylko nazwy tagów, drugie uruchomienie nie wprowadza zmian, a przykłady w komentarzach, blokach kodu, `<pre>` lub `<code>` są uwzględniane tylko w raporcie.

## Domyślne działanie

Samo zainstalowanie wersji 7.6 niczego nie zmienia.

**Profil wydajności domyślnie ma wartość `compat`.** Nagłówek strony, oEmbed, XML-RPC, Heartbeat, domyślne ustawienia obrazów, wstępne pobieranie linków, leniwe ładowanie i frontendowe `<title>` pozostają takie, jakie ustawiły WordPress i motyw.

**Pozostają wyłączone, dopóki ich nie włączysz:** każdy klucz `performance.staticPrerender`, `performance.measurement`, `performance.media` i `themeDefaults`, a także `githooks.commit`, `dev.canvas.enabled`, `ui.enabled`, `tailwind.enabled` i `blockTags.enabled`. Gdy statyczne wstępne renderowanie jest wyłączone, nie zapisuje plików ani nie instaluje drop-inu.

**Canvas i Render działają pasywnie.** Odczytują istniejące rejestry i renderują tylko to, o co poprosi wywołujący; żaden z nich nie ingeruje w wynik frontendu ani nie rejestruje tras. Ekran administracyjny Canvas nadal wymaga `dev.canvas.enabled` i `edit_posts`.

**Aby włączyć bardziej rygorystyczną analizę, trzeba ją wskazać.** Zainstalowanie `blockstudio/phpstan` włącza tylko rozszerzenie bazowe, a kanoniczne polecenie uruchamia `base`, chyba że projekt wskazuje preset.

**Wygenerowane pliki wymagają uruchomienia odpowiedniego polecenia.** `githooks.commit` nic nie robi, dopóki nie zostanie uruchomione `blockstudio-githooks sync`, a `AGENTS.md` — dopóki nie zostanie wykonane `blockstudio-agents`.

## Aktualizacja z wersji 7.5

Wymagania pozostają bez zmian: PHP 8.2 lub nowszy, WordPress 6.7 lub nowszy.

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

**Pamięci podręczne przebudowują się raz.** Tożsamość środowiska wykonawczego obejmuje wersję Blockstudio, więc pierwsze żądanie po aktualizacji nie korzysta z pamięci podręcznej, a stare obiekty są usuwane. Starą pamięć podręczną Tailwind w `wp-content/uploads/blockstudio/tailwind/cache` można usunąć; fragment kodu, który wyszukiwał tam pliki za pomocą glob, powinien zamiast tego wywoływać `Blockstudio\Runtime_Cache::purge('tailwind')`.

Płaski katalog `wp-content/blockstudio/cache/runtime` sprzed wersji 7.6 jest automatycznie przenoszony poza aktywną ścieżkę i usuwany w ograniczonych przebiegach WP-Cron. Dlatego dużych drzew starych plików blokad nie trzeba usuwać podczas obsługi żądania wdrożeniowego.

**Wygenerowane pliki mają przypisanych właścicieli.** `assets/media.json` należy przechowywać w systemie kontroli wersji lub generować w ramach procesu budowania. Mapa tras, drop-in `advanced-cache.php` i deklaracja `WP_CACHE` istnieją tylko wtedy, gdy włączono `earlyServe`, a hak pre-commit — tylko wtedy, gdy jest zsynchronizowany. Wszystkie pozostałe wygenerowane pliki znajdują się w `cache.path` i można je bezpiecznie usunąć.

**Nic nie zostało usunięte ani przemianowane.** `bs_render_block()`, `bs_block()`, `Blockstudio\Pages` i `Blockstudio\Patterns` nadal są kanonicznymi powierzchniami treści opartymi na plikach.

**Wycofanie zmian dotyczy poszczególnych funkcji.** Powrót z `performance.profile` do `compat`, z `staticPrerender.enabled` do `false`, z `githooks.commit` do `false` wraz z `sync` oraz z `cache.enabled` do `false` — każde z tych działań cofa jedną warstwę.

Rozsądna kolejność wdrażania:

1. Ustaw `performance.profile` na `speed`, a następnie sprawdź nagłówek strony, kanały i wtyczki korzystające z oEmbed lub XML-RPC.
2. Wygeneruj `assets/media.json`, przenieś szablony do `bs_media_image()`, a następnie włącz `performance.media.lazy`.
3. Włącz `performance.staticPrerender` przy wyłączonym `earlyServe`, sprawdź trafienia za pomocą `wp bs prerender status`, a następnie włącz `earlyServe`.
4. Uruchamiaj `blockstudio-phpstan --preset theme`, aż nie będzie zgłaszać problemów, zanim skonfigurujesz jakikolwiek preset w `githooks.commit`.

## Gdzie znaleźć szczegóły

- [Canvas](https://blockstudio.dev/pl/docs/dev/canvas/) i jego [spis zasobów i dokumentAPI](https://blockstudio.dev/pl/docs/dev/canvas/#public-inventory-and-document-api)
- [Renderowanie](https://blockstudio.dev/pl/docs/blocks/rendering/#structured-compositions-and-complete-documents), [UI Komponenty](https://blockstudio.dev/pl/ui/#public-inventory-and-examples) i [UI Kompozycja](https://blockstudio.dev/pl/ui/composition/)
- [Ustawienia](https://blockstudio.dev/pl/docs/general/settings/) i [wydajność](https://blockstudio.dev/pl/docs/general/settings/#performance)
- [Wydajność](https://blockstudio.dev/pl/docs/production/performance/), [Buforowanie](https://blockstudio.dev/pl/docs/production/caching/) i [Statyczne wstępne renderowanie](https://blockstudio.dev/pl/docs/production/static-prerendering/)
- [Tailwind CSS](https://blockstudio.dev/pl/docs/tailwind/#template-composition-helpers)
- [PHPStan](https://blockstudio.dev/pl/docs/dev/phpstan/): [presety](https://blockstudio.dev/pl/docs/dev/phpstan/#analysis-presets), [polecenie kanoniczne](https://blockstudio.dev/pl/docs/dev/phpstan/#canonical-command), [zarządzany hak zatwierdzania](https://blockstudio.dev/pl/docs/dev/phpstan/#managed-commit-hook) i [kontrakt projektu](https://blockstudio.dev/pl/docs/dev/phpstan/#project-contract-for-coding-agents)
- [Integracja AI](https://blockstudio.dev/pl/docs/dev/ai/): indeks dokumentacji i pełny tekst
- [Migracja](https://blockstudio.dev/pl/docs/dev/migration/v7/#canonical-block-tags) i [PHP Hooki](https://blockstudio.dev/pl/docs/blocks/hooks/php/)
