
Blockstudio 7.6 tekee projektista luettavan ja renderöitävän kohteesta PHP sekä siirtää tuotannon käyttöliittymän oletukset kohteeseen `blockstudio.json`: resurssiluettelo API, itsenäinen renderöinti, median ja Tailwind malliapurit, suorituskykyprofiilit, yksi välimuistihakemisto, staattinen esirenderöinti varhaisella tarjoilulla, tiukemmat analyysimääritykset ja koodausagenttien projektityökalujen luonti.

Kaksi kutsua kattaa suurimman osan julkaisusta. `Canvas::inventory()` palauttaa jokaisen projektin rekisteröimän sivun, lohkon, kuvion, Site Editor -mallin, malliosan ja paketoidun UI-esimerkin. `Render::document()` palauttaa niistä minkä tahansa valmiina HTML-sisältönä sekä täsmälleen renderöinnissä käytetyt resurssit.

> **7.6.2-päivitys:** Tiedostopohjaisia sivuja ei enää täsmäytetä tavallisten WordPress-pyyntöjen aikana. Suorita `wp bs pages sync` tai kutsu funktiota `Blockstudio\Pages::reconcile()` lähdemuutoksia käyttöön otettaessa. Kokoelmien reititys ja `templateFor`-oletukset käyttävät tallennettua ajonaikaisen ympäristön määritystä, ja nimenomainen täsmäytys välttää aiemman suuren monikielisen OR-meta-kyselyn. Lyhytikäinen `themeDefaults.syncPagesInDevelopment`-asetus on poistettu, koska sivujen synkronointia ei enää tehdä pyyntökoukkujen kautta. `Pages::init()` toimii nyt vain käynnistyksessä; integraatioiden, jotka välittivät `force`-arvon, on käytettävä toimintoa `Pages::reconcile()` tai CLI-arvoa. Canvasin avaaminen suorittaa yhä yhden todennetun, nimenomaisen täsmäytyksen sisällönmuokkauksen luetteloa varten.

> **7.6.12-päivitys:** Editorin tyylitiedostot saavat nyt etuliitteet yhdellä
> uudelleenkirjoituskierroksella sen sijaan, että jokainen resurssi käännettäisiin
> erikseen SASSilla. Näin editorin kylmä koonti sivustolla, jolla on paljon lohkoja,
> ei enää vaaranna vaatimattoman muistirajan ylittymistä. Välimuistissa oleva esirenderöity sivu, jonka sisältötiivisteellä nimetty Tailwind tyylitiedosto on
> poistettu välimuistista, renderöidään uudelleen tyylittömänä tarjoamisen sijaan sekä PHP-välimuistin että Early Serve -lisäosan kautta. Ylätasolle kirjoitetut lohkoattribuutit luetaan renderöinnin yhteydessä sen sijaan, että ne hylättäisiin, joten skeeman Blockstudio
> rekisteröinti kohteessa `WP_Block_Type` huomioidaan ohjelmallisissa kirjoittajissa.

> **7.6.11-päivitys:** Kaaviomallin artefaktien asennus korvaa nyt reitin
> dokumentin atomisesti, kun tallennuskopion sisältö on muuttunut saman avaimen
> alla. Identtiset dokumentit jätetään ennalleen, ja ylennetyt, korvatut, ohitetut
> sekä säilytetyt reitit ilmoitetaan `Static_Prerender_Early_Serve::last_promotion()`-kohteen kautta.

> **7.6.10-päivitys:** Ajonaikaisen välimuistin osumat tunnistavat nyt poistetut käännetyt resurssit myös tarkkailun viiveen aikana, ja versiota 7.6 vanhemmat litteät ajonaikaiset välimuistit siirretään atomisesti karanteeniin ja poistetaan rajatuissa cron-erissä. Mukana toimitetut UI-yleismuuttujat tulostetaan kerran sivua kohden. Kaaviomallin Early Serve voi tarjota käytössä renderöityjä reittejä, jotka eivät ole käyttöönotettujen reittien kartassa, identiteettivälimuistista. Tailwind voi halutessaan tulostaa sisältötiivisteellä nimetyn välimuistitiedostonsa käyttäen `tailwind.output: "link"`; oletuksena tuloste lisätään sivun sisään.

Lyhyesti:

- **Projektin luettelo**: `Canvas::inventory()` palauttaa kaikki rekisteröidyt tietueet lähteineen ja vakaassa näyttöjärjestyksessä.
- **Kohdennettu valinta**: Lohkojen ja sivujen nimeäminen rajaa etsinnän, synkronoinnin, renderöinnin ja kääntämisen kyseisiin tietueisiin.
- **Itsenäinen renderöinti**: `Blockstudio\Render` palauttaa valmiin HTML-sisällön lohkolle, koostumukselle tai kokonaiselle dokumentille.
- **UI-komponenttiperheet**: `Blockstudio\Ui` ryhmittelee mukana toimitetun kirjaston niin, että kustakin komponentista on yksi julkinen perhe ja esimerkki.
- **Vakaat kuvamitat**: `bs_media_image()` renderöi teeman resurssit todellisine mittoineen, jotka saadaan luodusta `assets/media.json`-tiedostosta.
- **Tailwind-luokka-apurit**: `bs_tw_merge()` ja `bs_tw_variants()` koostavat luokkia kohteessa PHP ristiriidat huomioiden.
- **Suorituskykyprofiilit**: `performance.profile` ottaa tuotantokäyttöön tarkoitetut käyttöliittymän oletukset käyttöön kerralla; aliavainten arvot ohittavat ne.
- **Tyypitettyjen asetusten käyttö**: `Settings::get_bool()` ja sen sisarukset lukevat `blockstudio.json`-sisällön oikeilla tyypeillä ja tuovat jäsennysvirheet esiin.
- **Yksi välimuistihakemisto**: Kaikki luodut tiedostot tallennetaan kohteeseen `cache.path` ajonaikaisen identiteetin mukaan.
- **Staattinen esirenderöinti**: Anonyymi HTML voidaan tallentaa välimuistiin, mitätöidä riippuvuuskaavion kautta ja tarjota ennen kuin WordPress käynnistyy.
- **Analyysin esiasetukset**: `theme`, `extreme-theme` ja `wordpress-render` laajentavat kohteen `blockstudio/phpstan` lohkomallien ulkopuolelle.
- **Hallittu commit-koukku**: `blockstudio-githooks sync` kirjoittaa ja hallinnoi pre-commit-koukkua, joka suorittaa määritetyn esiasetuksen.
- **Projektisopimus**: `blockstudio-agents` kirjoittaa `AGENTS.md`-tiedoston, joka kuvaa projektin tekijöille, mitä projektissa luodaan, mitkä ominaisuudet ovat käytössä ja mitä esiasetus valvoo.
- **Dokumentaation hakemisto**: Tekoälyn kontekstitiedosto on nyt hakemisto kaikista dokumenteista, niiden tarkoituksista ja niiden omistamista tunnisteista.
- **Lohkojen kanoniset tunnisteet**: Itsenäinen komento muuntaa etuliite- ja aliastunnukset muotoon `<bs:namespace-slug>`, ja käytettävissä on myös kuiva ajo.
- **Yhteensopiva oletuksena**: Mikään yllä mainituista ei muuta sivustoa, ennen kuin se nimetään kohteessa `blockstudio.json`.

## Projektin lukeminen ja renderöinti

### Projektin luettelo

`Canvas::inventory()` palauttaa kaiken, mitä projekti rekisteröi, yhtenä tavallisena taulukkona ilman renderöintiä.

```php
use Blockstudio\Canvas;

$result = Canvas::inventory();

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

Tietueet ryhmitellään tyypin mukaan: `pages`, `blocks`, `patterns`, `templates`,
`parts` ja `ui`. `order` määrittää vakaan näyttöjärjestyksen kaikille tyypeille,
`sources` yhdistää kunkin tietueen sen lähdepolkuihin, ja `warnings` sekä `errors`
keräävät ongelmat rakenteisiksi merkinnöiksi.

Lohkotietueet sisältävät `id`, `name`, `title`, `source`, `path`, `provenance` ja valmiin renderöitävän kohteen `declaration`. Sivutietueissa `source` säilyy vakaana tunnisteena ja `path` renderöivänä mallina.

### Kohdennettu valinta

Tietueiden nimeäminen rajaa käsiteltävät kohteet sen sijaan, että tuloksia suodatettaisiin jälkikäteen.

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

Tämä palauttaa yhden lohkon ja yhden sivun. `patterns`, `templates`, `parts` ja `ui`
palautuvat tyhjinä, eikä niiden lähteitä lueta, synkronoida, renderöidä tai
käännetä.

Säännöt ovat täsmälliset:

- Jos tyyppiavaimia ei ole lainkaan, ladataan kaikki tyypit.
- `true`, `null` tai `"*"` lataa kaikki kyseisen tyypin tietueet.
- Merkkijono tai luettelo vastaa täsmälleen tunnistetta, nimeä, polkutunnusta, polkua tai lähdepolkua.
- Tyhjä merkkijono, tyhjä luettelo tai `false` lataa kyseisestä tyypistä ei mitään.
- Kun jokin tyyppiavain on annettu, pois jätetyt tyypit jäävät koskemattomiksi.

Tunnisteet, joita ei enää ole, palautetaan kohteessa `deleted` virheen sijaan,
ja Canvasin REST-päivityspäätepiste noudattaa samaa sääntöä parametreilleen
`blocks` ja `pages`.

`Canvas::documents()` ottaa vastaan saman valinnan ja lisää kullekin tietueelle yhden renderöidyn dokumentin. Valitut sivut renderöidään palautetussa käyttöliittymäkontekstissa, joten kyselyehdot, body-luokat, lyhytkoodit, asettelut, uudelleenohjaukset ja resurssien latauskutsut käsittelevät kyseistä sivua sen pyynnön sijaan, joka sitä pyysi.

### Itsenäinen renderöinti

`Blockstudio\Render` palauttaa renderöidyn HTML-sisällön merkkijonona samaa putkea käyttäen kuin käyttöliittymä.

```php
use Blockstudio\Render;

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

Taustalla on yksi määritysmuoto, jossa on neljä avainta: `name`, `attributes`,
`content` ja `children`. `root`, `data`, `inner`, `innerBlocks`, `layers` ja
`example` ovat syötteen käyttöä helpottavia oikoteitä, jotka `Render::normalize()` yhdistää siihen.
Alielementit renderöidään rekursiivisesti, ja virheellinen syöte aiheuttaa poikkeuksen, jossa mainitaan ongelmallinen lohko.

`Render::document()` käärii tulosteen täydelliseen itsenäiseen HTML-dokumenttiin.

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

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

`body` on pelkkä lohkon tuloste, `html` koottu dokumentti, `blocks`
lohkojen nimet, jotka vaikuttivat tulokseen, ja `assets` jakaa merkinnät osiin:
`head`, `footer`, `styles`, `scripts`, `modules`, `interactivity`, `ui` ja `tailwind`.
Resurssit rajataan renderöityyn sisältöön, joten pelkän editorin resurssit eivät näy.

`Render::document_from_html()` käärii muualla renderöidyn kohteen HTML, ja
`Render::content()` renderöi sarjoitetun lohkosisällön ilman dokumenttia. Kutsu
`Blockstudio\Batch_Render::reset()` dokumenttien välillä saman PHP-prosessin aikana;
`Canvas::documents()` tekee sen jo.

### UI-komponenttiperheet

`Blockstudio\Ui` tarjoaa mukana toimitetun UI-kirjaston siten, että kustakin julkisesta komponentista on yksi merkintä sisäisten osien luettelon sijaan.

`Ui::inventory()` palauttaa kustakin perheestä yhden merkinnän, jossa on sen juurilohko, otsikko ja tarvittavat toteutuslohkot. `Ui::examples()` lisää kuhunkin perheeseen deterministisen määrityksen: oletusarvot säilytetään, pakolliset alitasot sisällytetään vanhempiinsa ja tyhjille kentille lisätään vakaat esimerkkitekstit. Määritys on kanoninen, joten sen voi siirtää suoraan kohteeseen `Render::document()`.

Canvas ryhmittelee samalla tavalla. Mukana toimitettu UI näkyy tyypissä `ui` yhtenä esimerkkinä perhettä kohti, eikä toteutuksen rekisteröintejä näytetä kohteessa `blocks`.

Perheet on suunniteltu koottaviksi: valitsin avautuu valintaikkunan sisällä ja sen luetteloruutu asettuu käynnistimen päälle, valikot ja yhdistelmäruudut ankkuroidaan kiinteillä näkymäalueen koordinaateilla, jotka säilyvät vieritettäessä, valintaikkunat pinoutuvat ja sulkeutuvat yksi kerrallaan Escape-näppäimellä, ja jokaisessa alatunnisteessa käytetään samaa sulkemispainiketta eri muunnelmilla. Näiden liitoskohtien toimintaa ja niiden toimintaa ylläpitäviä ehtoja käsitellään [koostamista käsittelevässä luvussa](https://blockstudio.dev/fi/ui/composition/); [/ui/examples](https://blockstudio.dev/fi/ui/examples/) näyttää koostetut käyttöliittymät toiminnassa.

## Mallien apurit

### Vakaat kuvamitat

`bs_media_image()` renderöi teeman resurssit todellisella leveydellä ja korkeudella sekä varatulla kuvasuhteella, joten mediakirjaston ulkopuoliset kuvat eivät enää siirrä asettelua.

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

Tuloste on `figure.blockstudio-media`, jossa on sisäinen `aspect-ratio` `img`-elementin ympärillä; elementissä on todelliset arvot `width`, `height`, `loading` ja `decoding`. Mitat saadaan luodusta `assets/media.json`-tiedostosta, jonka `Blockstudio\Media_Metadata_Builder` kirjoittaa koontivaiheessa tai jonka voi kirjoittaa käsin.

`src` hyväksyy teemaan suhteutetun polun, absoluuttisen polun tai täydellisen URL-osoitteen, ja `attachmentId` kattaa mediakirjaston kuvat. `eager` poistaa laiskan latauksen käytöstä näkyvän alueen yläpuolella, ja `sources` tuottaa kohteen `<picture>`.

Kun `performance.media.lazy` on käytössä, varsinainen URL siirtyy kohteeseen `data-src` oikein mitoitetun paikkamerkin taakse.

### Tailwind-luokka-apurit

`bs_tw_merge()` ja `bs_tw_variants()` kokoavat Tailwind-luokkia kohteen PHP-malleissa käyttäen moottoria Blockstudio, joka toimitetaan jo mukana.

`bs_tw_merge('px-2 text-sm', 'px-4')` palauttaa arvon `text-sm px-4`: ristiriitainen
`px-2` poistetaan ja myöhemmin annettu arvo voittaa. Sisäkkäiset luokka-arvoja sisältävät taulukot hyväksytään.

`bs_tw_variants()` palauttaa pienen kutsuttavan funktion komponenttimuunnelmille:

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

Tämä tulostaa `inline-flex items-center h-12 px-6 rounded`. Perusluokkia,
muunnelmia, oletusmuunnelmia, yhdistelmämuunnelmia ja kutsukohtaista arvoa `class` tai
`className` tuetaan.

## Tuotantoasetukset

### Suorituskykyprofiilit

`performance.profile` ottaa tuotantokäyttöön tarkoitetut käyttöliittymän oletukset käyttöön yhdessä paikassa.

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

`compat` on oletusarvo eikä muuta mitään. `speed` ja `strict` ottavat käyttöön saman kokonaisuuden: ylätunnisteesta poistetaan generaattori-, emoji-, syöte-, etsintä- ja viereisen artikkelin tiedot; oEmbed-etsintä ja palvelimen komentosarjat poistetaan käytöstä; XML–RPC, pingbackit ja etäeditorin etsintä poistetaan käytöstä; yleiset ydinjärjestelmän käyttöliittymäresurssit poistetaan; kuvien tulosteen oletukset otetaan käyttöön; Heartbeatia rajoitetaan editorien ulkopuolella; saman alkuperän dokumentit esiladataan osoittimen tai kohdistuksen perusteella; ja käytössä on kohteen Blockstudio kuvien lataaja.

Jokainen lapsiarvo ohittaa profiilin, kuten yllä oleva `preload.links` tekee. Ydinjärjestelmän käyttöliittymäresurssien poistaminen käytöstä kannattaa testata ensin, sillä niistä riippuvainen sivu rikkoutuu näkyvästi. `Runtime_Settings::current()` näyttää ratkaistun profiilin.

`themeDefaults` kattaa kaksi asiaa, jotka teemat muuten toteuttaisivat itse: `titleTag` ja
`suppressDirectoryUpdates`, joilla aktiivinen alatason teema ja pääteema piilotetaan päivitystuloksista.

### Tyypitettyjen asetusten käyttö

`Blockstudio\Settings` lukee asetukset oikeilla tietotyypeillä sen sijaan, että palauttaisi mitä tahansa, mitä JSON sisälsi.

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

Virheellisestä kohteesta JSON ilmoitetaan kohteen `Settings::errors()` kautta oletusarvoihin siirtymisen sijaan. `Settings::get_raw()` palauttaa vain aktiivisen lähteen määrittämät arvot, jolloin arvon asettaminen arvoon `false` erottuu siitä, ettei arvoa ole koskaan asetettu.

`Settings::fingerprint()` palauttaa tehokkaiden asetusten vakaan identiteetin, ja käyttö lataa asetukset uudelleen, kun `blockstudio.json` muuttuu.

### Yksi välimuistihakemisto

Kaikki luodut tiedostot tallennetaan nyt kohteen `cache.path` alle, jonka oletusarvo on `wp-content/blockstudio/cache`.

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

Koontikuormat, lohkojen rekisteröintitiedot, editorin resurssit, käännetyt Tailwind CSS-tiedostot, renderöidyt dokumentit, saarekeosiot, staattiset HTML-tiedostot, kaavioindeksit, lämmitysjono ja diagnostiikkatiedot sijaitsevat kaikki kyseisen juurihakemiston alla. Suhteellinen polku ratkaistaan kohteesta `WP_CONTENT_DIR`, ja absoluuttinen polku ohjaa sen omaan levyyn.

Objektit tallennetaan ensin nykyisen verkon ja sivuston alle ja sitten ajonaikaisen identiteetin mukaan. Identiteetti on sormenjälki, joka muodostuu versioista Blockstudio, WordPress ja PHP, tehokkaista asetuksista, aktiivisesta teemasta ja lisäosista, etsinnän lähteistä sekä mukana olevista lähdetiedostoista. Kun syöte muuttuu, siihen liittyvistä objekteista luodaan uudet versiot ja vanhat siivotaan pois.

Kylmät koonnit suoritetaan yksi kerrallaan: yksi pyyntö luo ja julkaisee tuloksen atomisesti muiden odottaessa. Epäonnistuneen päivityksen jälkeen viimeisin onnistunut objekti pysyy käytössä virheen ollessa edelleen havaittavissa, ja `Blockstudio\Runtime_Cache::purge('tailwind')` tyhjentää yhden rajauksen.

## Staattinen esirenderöinti

Staattinen esirenderöinti tallentaa täydelliset anonyymit HTML-dokumentit välimuistiin ja voi tarjota ne ennen kuin WordPress käynnistyy. Ominaisuus ei ole oletuksena käytössä.

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

### Kelpoisuus

Vain täydelliset anonyymit HTML-dokumentit kelpaavat. Muut kuin GET-pyynnöt, kyselymerkkijonot, ylläpito, REST, Ajax, cron, syötteet, haut, esikatselut, nonce-arvoja sisältävät pyynnöt, yksilöllistävät evästeet ja kaikki kohteen `dynamicPaths` alla olevat polut ohitetaan.
Vastauksen voi jättää kokonaan pois välimuistista `<!-- blockstudio:no-cache -->`-merkillä.

Polkujen vertailussa huomioidaan rajat, joten `/account` kattaa kohteen `/account/orders` mutta ei kohdetta `/accounting`.

### Allekirjoitus- ja kaaviomallitilat

`invalidate` määrittää, miten merkinnät vanhenevat. Oletusarvoinen `signature`-tila tallentaa identiteettiavaimella varustetun vastauksen välimuistiin anonyymin pyynnön osuessa välimuistin ohi ja kierrättää vastauksia sivustotason muutosten jälkeen. Se sopii tavalliselle sivustolle.

`graph`-tila on tarkoitettu erikseen määritetyille koonti- ja käyttöönottotyökaluille. Se tallentaa kunkin sivun omat lähderiippuvuudet, joten suunnitelmassa rakennetaan uudelleen vain muuttuneiden sivujen URL-osoitteet.

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

### Varhainen tarjoilu

Kun `earlyServe` on käytössä, Blockstudio hallinnoi pientä sivustokohtaista reittikarttaa ja `advanced-cache.php`-lisäosaa, joka lähettää kelvollisen osuman ennen kuin WordPress, lisäosat tai teema käynnistyvät.

Se ei koskaan korvaa muiden omistamaa karttaa, lisäosaa tai `WP_CACHE`-määrittelyä. Kaavioartefakti vahvistaa jokaisen siihen viitatun HTML-tiedoston ennen kartan vaihtamista, joten keskeneräinen käyttöönotto jättää edellisen kaavion aktiiviseksi. Multisite-merkinnät pysyvät erillään isäntänimen, kotipolun ja sivustotunnuksen perusteella.

### Lämmitys ja tila

Kolme WP-CLI-komentoa kattavat päivittäisen käytön:

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

`status` ilmoittaa aktiivisen identiteetin, tiedosto- ja tavumäärät, kaaviotietueet, jonon tilan sekä osumien, ohitusten, koontien ja virheiden määrät kussakin rajauksessa.

## Analyysi- ja agenttityökalut

### Analyysin esiasetukset

`blockstudio/phpstan` saa lohkoanalyysinsä lisäksi kolme tasoa ja yhden komennon, joka suorittaa projektin valitseman tason.

| Esiasetus | Lisäykset |
| --- | --- |
| `base` | Aiempi skeema-, malli-, koukku-, asetus- ja API-analyysi. |
| `theme` | Teemojen juurihakemistot, tyylien otsakkeet, resurssit, valitsinten rajaus, kenttien oletusarvot ja toistimien rajat. |
| `extreme-theme` | PHPStan `max`, vaarallinen PHP, escapetus, Tailwind, JavaScript ja Interactivity-tarkistukset. |
| `wordpress-render` | Kutsujan toimittama reaaliaikainen renderöintitarkistus kohteen `extreme-theme` lisäksi. |

Oletusarvot tulevat kohteesta `blockstudio.json`, joten vuorovaikutteiset ajot, CI ja commit-koukut käyttävät samaa määritystä:

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

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

Paluukoodit ovat `0` onnistumiselle, `1` diagnostiikalle ja `2` virheelliselle käytölle. Kääre kokoaa määrityksensä järjestelmän väliaikaishakemistossa, joten projektiin ei synny määritystiedostoja, lähtötasoja tai välimuisteja, ja se nostaa kohteen PHPStan muistirajan arvoon `1G`.

Se sisältää myös BC Math -tarjoajan, joten JavaScript-tarkistukset eivät enää tarvitse kohdetta `ext-bcmath`.

### Hallittu commit-koukku

Yksi asetus ja yksi komento muuttavat määritetyn esiasetuksen commit-portinvartijaksi.

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

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

Synkronointi kirjoittaa koukun ja omistajuustietueen kohteen Git yhteiseen hakemistoon, ohjaa kohteen `core.hooksPath` hallittuun hakemistoon ja ketjuttaa aiemmin määritetyn pre-commit-koukun. Koukku ratkaisee repositorion ja projektin juurihakemiston commitin yhteydessä, joten linkitetyt työkopiot ja välilyöntejä sisältävät polut toimivat.

Koukku suorittaa `vendor/bin/blockstudio-phpstan` eikä mitään muuta; se ei koskaan muotoile tai kirjoita tiedostoja uudelleen. Kun `commit` asetetaan arvoon `false` ja synkronoidaan uudelleen tai suoritetaan `blockstudio-githooks remove`, tallennettu koukkupolku palautetaan ja poistetaan vain tiedostot, jotka ovat kohteen Blockstudio omistuksessa.

### Projektisopimus

`blockstudio-agents` kirjoittaa tiedoston `AGENTS.md`, jossa määritetään, missä lohkot sijaitsevat, mitä sivu tarkoittaa tässä projektissa, mitkä ominaisuudet ovat käytössä ja mitä analysoija hylkää.

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

Dokumentti luodaan projektin perusteella, eikä se ole mallipohja. Teema, jossa on `style.css`-otsake, lohkoja ja tiedostopohjaisia sivuja, saa erilaisen sopimuksen kuin lisäosa, joka rekisteröi vain lohkoja. Sopimukseen kirjataan etsinnässä löytyneet määrät, hakemistot, nimiavaruudet ja mallikielet. `blockstudio.json` määrittää, mitkä ominaisuudet otetaan mukaan, joten ilman staattista esirenderöintiä toimivassa projektissa sitä ei mainita.

Oikeellisuutta käsittelevä osio luetaan valitun esiasetuksen omista sääntötiedostoista taso kerrallaan. Kun esiasetukseen lisätään sääntö, se muuttaa kaikkia luotuja sopimuksia.

Omistajuus toimii samalla tavalla kuin commit-koukussa. Tiedostoa, jossa ei ole luontimerkkiä, ei korvata, ellei `--force` muuta määrää. Lopussa oleva muistiinpanoalue säilyy uudelleenluonnissa, `--check` palauttaa arvon `1`, jos sopimus on vanhentunut, ja `--stdout` tulostaa sen koskematta tiedostojärjestelmään.

### Dokumentaation hakemisto

`blockstudio-llm.txt` on nyt hakemisto koonnin sijaan. Jokainen julkaistu dokumentti esiintyy kerran omassa osiossaan ja alaosiossaan. Siinä ilmoitetaan dokumentin reitti, lähdetiedosto, tarkoitus yhdellä rivillä ja sen omistamat tunnisteet: asetuspolut, koukkujen nimet, kohteen PHP funktiot ja luokat sekä komennot.

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

Agentti lukee indeksin, löytää sen dokumentin, joka omistaa tarvitsemansa tunnisteen, ja avaa sen. Aiempi puolen megatavun yhdistelmä luodaan ja julkaistaan edelleen kohdassa `/blockstudio-llm-full.txt`; se ei enää ole ensimmäinen asia, joka kenellekään annetaan.

## Kanoniset lohkotunnisteet

Erillinen komento kirjoittaa etuliite- ja aliasshokkeamat kanoniseen `<bs:namespace-slug>`-muotoon, joka tallentaa todellisen lohkonimen ja toimii ilman ladattua projektisuodatinta.

Kun etuliite `brand` kuuluu joukkoon `theme-components` ja etuliite `ui` joukkoon `bsui`, tämä lyhennys:

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

tarkoittaa samaa kuin:

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

Etuliitteet ja täsmälliset aliakset toimivat edelleen, eikä niitä ole vanhennettu. Komento ei lataa kohdetta WordPress eikä kirjoita mitään ilman kohdetta `--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` yhdistää kunkin etuliitteen nimiavaruuksiinsa, ja `--known-blocks` listaa rekisteröidyt lohkonimet. Raportissa ovat vanhojen ja kanonisten muotojen väliset vastaavuudet esiintymismäärineen, tiedostokohtaiset tiivisteet sekä erilliset listat tuntemattomista tunnisteista, monitulkintaisista aliaksista ja dynaamisista tunnisteista. `--apply` kieltäytyy kirjoittamasta, jos niitä on vielä, ellei anneta valitsinta `--allow-unresolved`.

Paritetut, sisäkkäiset ja itsestään sulkeutuvat merkinnät käsitellään, myös kirjaimelliset tunnisteet merkkijonoissa PHP. Vain tunnisteiden nimet muuttuvat, toinen suoritus ei tee muutoksia, ja kommenteissa, koodiaidoissa, kohteessa `<pre>` tai kohteessa `<code>` olevat esimerkit näkyvät vain raportissa.

## Oletustoiminta

Version 7.6 asentaminen ei itsessään muuta mitään.

**Suorituskykyprofiilin oletusarvo on `compat`.** Head-tuloste, oEmbed, XML–RPC, Heartbeat, kuvien oletukset, linkkien esilataus, laiska lataus ja käyttöliittymän `<title>` säilyvät sellaisina kuin WordPress ja teema ne jättivät.

**Nämä pysyvät poissa käytöstä, ellei niitä oteta käyttöön:** jokainen avain `performance.staticPrerender`, `performance.measurement`, `performance.media` ja `themeDefaults` sekä `githooks.commit`, `dev.canvas.enabled`, `ui.enabled`, `tailwind.enabled` ja `blockTags.enabled`. Staattinen esirenderöinti ei kirjoita tiedostoja eikä asenna lisäosaa, kun se ei ole käytössä.

**Canvas ja Render ovat passiivisia.** Ne lukevat olemassa olevia rekistereitä ja renderöivät vain sen, mitä kutsuja pyytää; kumpikaan ei kytkeydy käyttöliittymän tulosteeseen eikä rekisteröi reittejä. Canvasin ylläpitonäkymä edellyttää edelleen kohteita `dev.canvas.enabled` ja `edit_posts`.

**Tiukempi analyysi edellyttää sen nimeämistä.** Kohteen `blockstudio/phpstan` asentaminen ottaa käyttöön vain peruslaajennuksen, ja kanoninen komento suorittaa kohteen `base`, ellei projektissa nimetä esiasetusta.

**Luodut tiedostot edellyttävät vastaavan komennon suorittamista.** `githooks.commit` ei tee mitään ennen kuin `blockstudio-githooks sync` suoritetaan, eikä `AGENTS.md` ennen kuin `blockstudio-agents` suoritetaan.

## Päivittäminen versiosta 7.5

Vaatimukset ovat ennallaan: PHP 8.2 tai uudempi, WordPress 6.7 tai uudempi.

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

**Välimuistit rakennetaan uudelleen kerran.** Ajon aikainen identiteetti sisältää version Blockstudio, joten ensimmäinen pyyntö päivityksen jälkeen on kylmä ja vanhat objektit siivotaan. Vanhan Tailwind-välimuistin kohteessa `wp-content/uploads/blockstudio/tailwind/cache` voi poistaa; sen tiedostoja hakevan koodinpätkän pitäisi kutsua sen sijaan kohdetta `Blockstudio\Runtime_Cache::purge('tailwind')`.

Ennen versiota 7.6 käytössä ollut litteä `wp-content/blockstudio/cache/runtime`-hakemisto nimetään automaattisesti pois aktiivisesta polusta ja poistetaan rajatuissa WP-Cron-ajoissa. Suuria vanhoja lukitustiedostopuita ei siksi tarvitse poistaa käyttöönottopyynnön aikana.

**Luoduilla tiedostoilla on omistajansa.** `assets/media.json` kuuluu versionhallintaan tai koontivaiheeseen. Reittikartta, `advanced-cache.php`-lisäosa ja `WP_CACHE`-määritys ovat olemassa vain, kun `earlyServe` on käytössä, ja esikäsittelykoukku vain synkronoinnin aikana. Kaikki muu luotu sisältö sijaitsee kohteen `cache.path` alla, ja sen voi poistaa turvallisesti.

**Mitään ei poistettu eikä nimetty uudelleen.** `bs_render_block()`, `bs_block()`, `Blockstudio\Pages` ja `Blockstudio\Patterns` ovat edelleen kanoniset tiedostopohjaiset sisältöpinnat.

**Palautus tehdään ominaisuuskohtaisesti.** `performance.profile` takaisin kohteeseen `compat`, `staticPrerender.enabled` kohteeseen `false`, `githooks.commit` kohteeseen `false` ja lisäksi `sync` sekä `cache.enabled` kohteeseen `false` palauttavat kukin yhden kerroksen.

Järkevä käyttöönottojärjestys:

1. Aseta `performance.profile` arvoksi `speed` ja tarkista sitten head-tuloste, syötteet ja kaikki lisäosat, jotka käyttävät oEmbediä tai kohdetta XML–RPC.
2. Luo kohde `assets/media.json`, siirrä mallit kohteeseen `bs_media_image()` ja ota sitten käyttöön `performance.media.lazy`.
3. Ota käyttöön `performance.staticPrerender` niin, että `earlyServe` ei ole käytössä, tarkista osumat kohteella `wp bs prerender status` ja ota sitten `earlyServe` käyttöön.
4. Suorita kohdetta `blockstudio-phpstan --preset theme`, kunnes tulos on puhdas, ennen kuin asetat esiasetuksen kohteen `githooks.commit` taakse.

## Mistä lisätiedot löytyvät

- [Canvas](https://blockstudio.dev/fi/docs/dev/canvas/) ja sen [luettelo sekä dokumentin API](https://blockstudio.dev/fi/docs/dev/canvas/#public-inventory-and-document-api)
- [Renderöinti](https://blockstudio.dev/fi/docs/blocks/rendering/#structured-compositions-and-complete-documents), [UI-komponentit](https://blockstudio.dev/fi/ui/#public-inventory-and-examples) ja [UI-koostaminen](https://blockstudio.dev/fi/ui/composition/)
- [Asetukset](https://blockstudio.dev/fi/docs/general/settings/) ja [suorituskyky](https://blockstudio.dev/fi/docs/general/settings/#performance)
- [Suorituskyky](https://blockstudio.dev/fi/docs/production/performance/), [välimuisti](https://blockstudio.dev/fi/docs/production/caching/) ja [staattinen esirenderöinti](https://blockstudio.dev/fi/docs/production/static-prerendering/)
- [Tailwind CSS](https://blockstudio.dev/fi/docs/tailwind/#template-composition-helpers)
- [PHPStan](https://blockstudio.dev/fi/docs/dev/phpstan/): [esiasetukset](https://blockstudio.dev/fi/docs/dev/phpstan/#analysis-presets), [kanoninen komento](https://blockstudio.dev/fi/docs/dev/phpstan/#canonical-command), [hallittu commit-koukku](https://blockstudio.dev/fi/docs/dev/phpstan/#managed-commit-hook) ja [projektisopimus](https://blockstudio.dev/fi/docs/dev/phpstan/#project-contract-for-coding-agents)
- [AI-integraatio](https://blockstudio.dev/fi/docs/dev/ai/): dokumentaatiohakemisto ja koko teksti
- [Migraatio](https://blockstudio.dev/fi/docs/dev/migration/v7/#canonical-block-tags) ja [PHP-koukut](https://blockstudio.dev/fi/docs/blocks/hooks/php/)
