
Blockstudio 7.6 rende un progetto consultabile e visualizzabile da PHP e trasferisce le impostazioni predefinite del frontend di produzione in `blockstudio.json`: un inventario API, rendering autonomo, helper di template per media e Tailwind, profili di prestazioni, una sola directory della cache, prerendering statico con distribuzione anticipata, preset di analisi più rigorosi e strumenti di progetto generati per gli agenti di programmazione.

Due chiamate coprono la maggior parte delle funzionalità della versione. `Canvas::inventory()` restituisce ogni pagina, blocco, pattern, template e parte di template dell'Editor del sito e ogni esempio UI incluso registrato dal progetto. `Render::document()` restituisce HTML completi per ciascuno di essi, con esattamente gli asset usati per il rendering.

> **Aggiornamento di 7.6.2:** le pagine basate su file non vengono più riconciliate durante le normali richieste WordPress. Eseguite `wp bs pages sync` o chiamate `Blockstudio\Pages::reconcile()` per applicare le modifiche alle sorgenti. L'instradamento delle raccolte e le impostazioni predefinite di `templateFor` usano la configurazione runtime salvata; la riconciliazione esplicita evita la precedente query OR-meta di grandi dimensioni per più lingue. L'opzione `themeDefaults.syncPagesInDevelopment` a breve durata è stata rimossa, poiché la sincronizzazione delle pagine non viene più eseguita dagli hook delle richieste. `Pages::init()` ora viene usato solo durante l'avvio; le integrazioni che passavano `force` devono usare `Pages::reconcile()` o il CLI. L'apertura di Canvas esegue comunque una riconciliazione esplicita autenticata per l'inventario di creazione.

> **7.6.12 aggiornamento:** I fogli di stile dell’editor vengono ora prefissati con un’unica
> passata di riscrittura, invece di compilare SASS per ogni risorsa, così una
> build a freddo dell’editor su un sito con molti blocchi non rischia più di
> esaurire un limite di memoria modesto. Una pagina prerenderizzata in cache il cui
> foglio di stile Tailwind con hash del contenuto è stato espulso viene
> renderizzata di nuovo anziché essere servita senza stili, sia tramite la cache PHP
> sia tramite il drop-in Early Serve. Gli attributi dei blocchi scritti al livello superiore vengono
> letti al momento del rendering invece di essere ignorati, quindi lo schema Blockstudio
> registrato su `WP_Block_Type` viene rispettato anche dagli strumenti che scrivono
> programmaticamente.

> **7.6.11 aggiornamento:** L’installazione degli artefatti Graph ora sostituisce atomicamente il
> documento di una route quando la copia nello store è cambiata mantenendo la stessa chiave, lascia
> intatti i documenti identici e segnala le route promosse, sostituite, ignorate e
> mantenute tramite `Static_Prerender_Early_Serve::last_promotion()`.

> **7.6.10 aggiornamento:** Gli accessi alla cache runtime ora rilevano le risorse compilate rimosse anche
> durante il debounce del watch; inoltre, le cache runtime piatte precedenti alla 7.6 vengono messe
> atomicamente in quarantena ed eliminate in batch di cron dimensioni limitate. Le variabili globali UI incluse nel bundle vengono emesse una sola volta
> per pagina. Early Serve in modalità Graph può servire route renderizzate dal vivo al di fuori della
> mappa delle route distribuite, usando la cache di identità. Tailwind può generare facoltativamente il proprio file di cache con hash del contenuto tramite `tailwind.output: "link"`; l’output inline resta
> l’impostazione predefinita.

In breve:

- **Inventario del progetto**: `Canvas::inventory()` restituisce ogni record registrato,
  con le relative fonti e un ordine di visualizzazione stabile.
- **Selezione mirata**: indicare blocchi e pagine limita individuazione, sincronizzazione,
  rendering e compilazione a quei record.
- **Rendering autonomo**: `Blockstudio\Render` restituisce HTML pronti per
  un blocco, una composizione o un documento completo.
- **Famiglie di componenti UI**: `Blockstudio\Ui` raggruppa la libreria inclusa
  in una famiglia pubblica per componente, ciascuna con un esempio.
- **Dimensioni immagine stabili**: `bs_media_image()` renderizza le risorse del tema con dimensioni
  reali, ricavate da un `assets/media.json` generato.
- **Helper di classe Tailwind**: `bs_tw_merge()` e `bs_tw_variants()` compongono
  classi in PHP con un’unione che tiene conto dei conflitti.
- **Profili di prestazioni**: `performance.profile` attiva in una volta sola le impostazioni predefinite
  per il frontend in produzione; i valori secondari hanno la precedenza.
- **Accesso tipizzato alle impostazioni**: `Settings::get_bool()` e i relativi metodi leggono
  `blockstudio.json` usando i tipi effettivi e segnalano gli errori di analisi.
- **Un’unica directory di cache**: tutti i file generati si trovano sotto `cache.path`, con chiavi
  basate su un’identità runtime.
- **Prerendering statico**: i documenti HTML anonimi possono essere messi in cache, invalidati tramite un
  grafo delle dipendenze e serviti prima che WordPress venga avviato.
- **Preset di analisi**: `theme`, `extreme-theme` e `wordpress-render` estendono
  `blockstudio/phpstan` oltre i template dei blocchi.
- **Hook di commit gestito**: `blockstudio-githooks sync` scrive e gestisce un
  hook pre-commit che esegue il preset configurato.
- **Contratto del progetto**: `blockstudio-agents` scrive un `AGENTS.md` che descrive
  cosa crea il progetto, quali funzionalità abilita e cosa impone il suo preset.
- **Indice della documentazione**: il file di contesto per l’IA ora elenca tutti i
  documenti, il loro scopo e gli identificatori di cui sono responsabili.
- **Tag canonici dei blocchi**: un comando autonomo riscrive le forme abbreviate di prefissi e alias in `<bs:namespace-slug>`, con una simulazione.
- **Compatibilità predefinita**: nessuna delle funzionalità sopra modifica un sito finché non viene indicata in
  `blockstudio.json`.

## Lettura e rendering di un progetto

### Inventario del progetto

`Canvas::inventory()` restituisce in un semplice array tutto ciò che un progetto registra,
senza eseguire alcun rendering.

```php
use Blockstudio\Canvas;

$result = Canvas::inventory();

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

I record sono raggruppati per tipo: `pages`, `blocks`, `patterns`, `templates`,
`parts` e `ui`. `order` definisce l’ordine di visualizzazione stabile per tutti i tipi,
`sources` associa ogni record ai percorsi delle sue fonti, mentre `warnings` e `errors`
raccolgono i problemi in voci strutturate.

I record dei blocchi includono `id`, `name`, `title`, `source`, `path`, `provenance` e un `declaration`
pronto per il rendering. I record delle pagine mantengono `source` come identità stabile
e `path` come template usato per il rendering.

### Selezione mirata

Indicare i record restringe il lavoro, invece di filtrare i risultati in seguito.

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

Questo restituisce un blocco e una pagina. `patterns`, `templates`, `parts` e `ui`
restituiscono array vuoti e le relative fonti non vengono mai lette, sincronizzate, renderizzate o
compilate.

Le regole sono precise:

- Se non si specificano chiavi di tipo, vengono caricati tutti i tipi.
- `true`, `null` o `"*"` carica tutti i record di quel tipo.
- Una stringa o un elenco corrisponde esattamente a ID, nome, slug, percorso o percorso della fonte.
- Una stringa vuota, un elenco vuoto o `false` non carica alcun record di quel tipo.
- Quando è presente una chiave di tipo, i tipi omessi restano invariati.

Gli identificatori che non esistono più vengono restituiti sotto `deleted` invece di causare un errore,
e l’endpoint di aggiornamento di Canvas REST applica la stessa regola ai parametri `blocks` e
`pages`.

`Canvas::documents()` applica la stessa selezione e aggiunge un documento renderizzato
per ogni record. Le pagine selezionate vengono renderizzate in un contesto frontend ripristinato, così le condizioni delle query,
le classi del body, gli shortcode, i layout, i redirect e le callback di enqueue vedono quella pagina,
non la richiesta che ha chiesto il rendering.

### Rendering autonomo

`Blockstudio\Render` restituisce HTML renderizzato come stringa, attraverso la stessa
pipeline usata dal frontend.

```php
use Blockstudio\Render;

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

Alla base c’è un’unica struttura di dichiarazione con quattro chiavi: `name`, `attributes`,
`content` e `children`. `root`, `data`, `inner`, `innerBlocks`, `layers` e
`example` sono pratiche opzioni di input che `Render::normalize()` integra nella struttura.
I componenti figli vengono renderizzati ricorsivamente e, se l’input non è valido, viene generata un’eccezione che indica il blocco
incriminato.

`Render::document()` racchiude l’output in un documento HTML autonomo e completo.

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

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

`body` è il solo output del blocco, `html` il documento assemblato, `blocks` i
nomi dei blocchi che vi hanno contribuito e `assets` suddivide il markup in `head`,
`footer`, `styles`, `scripts`, `modules`, `interactivity`, `ui` e `tailwind`.
Le risorse sono limitate a quelle usate nel rendering, quindi non compaiono mai risorse riservate all’editor.

`Render::document_from_html()` racchiude HTML renderizzato altrove, mentre
`Render::content()` renderizza il contenuto serializzato dei blocchi senza un documento. Chiamate
`Blockstudio\Batch_Render::reset()` tra un documento e l’altro all’interno di un unico processo PHP;
`Canvas::documents()` lo fa già.

### Famiglie di componenti UI

`Blockstudio\Ui` presenta la libreria UI inclusa come una voce per ogni
componente pubblico, invece di mostrare un elenco di parti interne.

`Ui::inventory()` restituisce una voce per ogni famiglia, con il blocco radice, il titolo e
i blocchi di implementazione necessari. `Ui::examples()` aggiunge una
struttura di dichiarazione deterministica per ogni famiglia: conserva i valori predefiniti, annida i livelli figli obbligatori sotto i rispettivi genitori e usa testo illustrativo stabile quando un campo sarebbe vuoto. Questa
struttura è canonica e può quindi essere inserita direttamente in `Render::document()`.

Canvas raggruppa gli elementi allo stesso modo. UI incluso nel bundle compare sotto il tipo `ui`, con un
esempio per ogni famiglia; le registrazioni di implementazione non compaiono in `blocks`.

Le famiglie sono pensate per essere assemblate: un selettore si apre in una finestra di dialogo con il relativo listbox sovrapposto al pulsante di apertura; menu e caselle combinate si ancorano usando coordinate fisse nella finestra, che restano corrette durante lo scorrimento; le finestre modali si sovrappongono e si chiudono una alla volta premendo Escape; ogni piè di pagina combina lo stesso controllo di chiusura con una variante. Per scoprire come funzionano queste integrazioni e quali invarianti le mantengono operative, consultate il [capitolo sulle composizioni](https://blockstudio.dev/it/ui/composition/); [/ui/examples](https://blockstudio.dev/it/ui/examples/) mostra le composizioni in funzione.

## Helper per i template

### Dimensioni immagine stabili

`bs_media_image()` renderizza le risorse del tema con larghezza e altezza reali e un rapporto
proporzionale riservato, così le immagini fuori dalla libreria multimediale non fanno più saltare il layout.

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

L’output è un `figure.blockstudio-media` con un `aspect-ratio` inline attorno
a un `img` che include i valori reali di `width`, `height`, `loading` e `decoding`. Le dimensioni
provengono da un `assets/media.json` generato, creato da
`Blockstudio\Media_Metadata_Builder` durante la build o manualmente.

`src` accetta un percorso relativo al tema, un percorso assoluto o un URL completo; `attachmentId` gestisce le immagini della libreria multimediale. `eager` disattiva il caricamento differito
sopra la piega e `sources` genera un `<picture>`.

Quando `performance.media.lazy` è attivo, il vero URL viene spostato in `data-src` dietro un segnaposto
con le dimensioni corrette.

### Helper per le classi Tailwind

`bs_tw_merge()` e `bs_tw_variants()` compongono le classi Tailwind nei template PHP,
usando il motore già incluso in Blockstudio.

`bs_tw_merge('px-2 text-sm', 'px-4')` restituisce `text-sm px-4`: la classe `px-2` in conflitto viene rimossa e prevale il valore successivo. Sono accettati anche array annidati di valori di classe.

`bs_tw_variants()` restituisce una piccola funzione richiamabile per le varianti dei componenti:

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

Il risultato è `inline-flex items-center h-12 px-6 rounded`. Sono supportati classi di base,
varianti, varianti predefinite, varianti composte e `class` o `className` specificati
per ogni chiamata.

## Configurazione per la produzione

### Profili di prestazioni

`performance.profile` attiva in un unico punto le impostazioni predefinite del frontend per la produzione.

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

`compat` è l’impostazione predefinita e non modifica nulla. `speed` e `strict` attivano
lo stesso insieme di impostazioni: rimuovono dall’head i generatori, le emoji, il feed, l’individuazione e l’output degli articoli correlati; eliminano l’individuazione oEmbed e gli script host; disattivano XML-RPC, i pingback
e l’individuazione remota dell’editor; rimuovono le risorse frontend generiche di core;
applicano le impostazioni predefinite per l’output delle immagini; limitano Heartbeat al di fuori degli editor; eseguono il prefetch dei documenti della stessa origine al passaggio del puntatore o quando si prevede che un elemento riceva il focus; e usano il caricatore di immagini di Blockstudio.

Ogni valore secondario prevale sul profilo, come avviene sopra per `preload.links`. La rimozione
delle risorse frontend di core è la prima cosa da verificare, perché una pagina che ne dipende si rompe in modo evidente. `Runtime_Settings::current()` espone il profilo risolto.

`themeDefaults` gestisce due aspetti che altrimenti i temi dovrebbero configurare manualmente: `titleTag` e `suppressDirectoryUpdates` nascondono il tema figlio attivo e quello genitore dai risultati degli aggiornamenti.

### Accesso tipizzato alle impostazioni

`Blockstudio\Settings` legge la configurazione usando i tipi effettivi, invece di restituire
qualsiasi valore contenuto in 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);
}
```

Gli JSON malformati vengono segnalati tramite `Settings::errors()` invece di risolversi nei
valori predefiniti. `Settings::get_raw()` restituisce solo ciò che è stato dichiarato dalla fonte attiva,
per distinguere un valore impostato a `false` da uno mai impostato.

`Settings::fingerprint()` restituisce un’identità stabile per le impostazioni effettive
e l’accesso ricarica la configurazione quando cambia `blockstudio.json`.

### Un’unica directory di cache

Ora tutti i file generati si trovano sotto `cache.path`, che per impostazione predefinita è
`wp-content/blockstudio/cache`.

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

I payload di build, i dati di registrazione dei blocchi, le risorse dell’editor, gli Tailwind CSS compilati,
i documenti di rendering, i frammenti delle isole, gli HTML statici, gli indici Graph, le code di riscaldamento e
i dati diagnostici si trovano tutti sotto quella directory principale. Un percorso relativo viene risolto a partire da
`WP_CONTENT_DIR`; un percorso assoluto lo indirizza a un volume dedicato.

Gli oggetti vengono archiviati sotto la rete e il sito correnti, quindi sotto un’identità runtime:
un’impronta digitale delle versioni di Blockstudio, WordPress e PHP,
delle impostazioni effettive, del tema e dei plugin attivi, delle fonti di individuazione e dei file sorgente coinvolti. Quando cambia un input, gli oggetti interessati vengono sostituiti; quelli vecchi vengono eliminati.

Le build a freddo vengono eseguite una sola volta: una richiesta crea e pubblica atomicamente il risultato, mentre le altre attendono. Se un aggiornamento non riesce, continua a essere servito l’ultimo oggetto valido e l’errore resta visibile; `Blockstudio\Runtime_Cache::purge('tailwind')` cancella un singolo ambito.

## Prerendering statico

Il prerendering statico memorizza in cache documenti HTML completi e anonimi e può servirli
prima che WordPress venga avviato. È disattivato per impostazione predefinita.

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

### Requisiti di idoneità

Sono idonei solo i documenti HTML completi e anonimi. Vengono esclusi dalle regole i metodi diversi da GET, le stringhe di query,
l’amministrazione, REST, Ajax, cron, i feed, la ricerca, le anteprime, le richieste con nonce, i cookie personalizzati e tutti i percorsi sotto `dynamicPaths`.
Una risposta può escludersi completamente tramite un marcatore `<!-- blockstudio:no-cache -->`.

La corrispondenza dei percorsi rispetta i confini: `/account` include `/account/orders`, ma
non `/accounting`.

### Modalità con firma e modalità Graph

`invalidate` determina quando scadono le voci. La modalità predefinita `signature` crea
una risposta associata all’identità quando manca una voce anonima e la rinnova dopo modifiche a livello di sito: è adatta ai siti comuni.

La modalità `graph` è destinata agli strumenti espliciti di build e distribuzione. Registra le dipendenze sorgente di ogni pagina, così un piano ricostruisce solo gli URL interessati.

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

### Servizio anticipato

Quando `earlyServe` è attivo, Blockstudio gestisce una piccola mappa delle route per ogni sito e un drop-in `advanced-cache.php` che trasmette una risposta idonea in cache prima dell’avvio di WordPress, dei plugin o del tema.

Non sovrascrive mai una mappa, un drop-in o una dichiarazione `WP_CACHE` di terze parti. Prima di sostituire la mappa, un artefatto Graph verifica ogni file HTML a cui si fa riferimento, così una distribuzione renderizzata solo in parte lascia attivo il grafo precedente. Le voci multisito restano isolate per host, percorso home e ID del sito.

### Riscaldamento e stato

Tre comandi WP-CLI coprono le attività quotidiane:

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

`status` mostra l’identità attiva, il numero di file e di byte, i record Graph, lo stato della coda e, per ogni ambito, i contatori di accessi, mancate corrispondenze, build ed errori.

## Analisi e strumenti per agenti

### Preset di analisi

`blockstudio/phpstan` aggiunge tre livelli all’analisi dei blocchi e un comando
che esegue il livello selezionato dal progetto.

| Preset | Cosa aggiunge |
| --- | --- |
| `base` | Le analisi esistenti di schema, template, hook, impostazioni e API. |
| `theme` | Directory radice del tema, intestazioni degli stili, risorse, ambiti dei selettori, valori predefiniti dei campi e limiti dei repeater. |
| `extreme-theme` | PHPStan `max`, PHP non sicuri, escaping, Tailwind, JavaScript e verifiche Interactivity. |
| `wordpress-render` | Un controllo live del rendering fornito dal chiamante, oltre a `extreme-theme`. |

Le impostazioni predefinite provengono da `blockstudio.json`, così esecuzioni interattive, CI e hook di commit
condividono un’unica configurazione:

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

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

I codici di uscita sono `0` in caso di esito positivo, `1` per le diagnostiche e `2` per l’uso non valido. Il wrapper compone la configurazione nella directory temporanea di sistema, senza salvare nel progetto configurazioni, baseline o cache generate, e aumenta il limite di memoria di PHPStan a `1G`.

Include anche un provider BC Math, così i controlli JavaScript non richiedono più
`ext-bcmath`.

### Hook di commit gestito

Un’impostazione e un comando trasformano il preset configurato in un controllo prima del commit.

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

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

La sincronizzazione scrive l’hook e un record di proprietà nella directory comune di Git,
indirizza `core.hooksPath` alla directory gestita e concatena l’eventuale hook pre-commit configurato in precedenza. Al momento del commit, l’hook individua il repository e la directory principale del progetto, quindi funziona con checkout collegati e percorsi contenenti spazi.

L’hook esegue `vendor/bin/blockstudio-phpstan` e nient’altro: non formatta né riscrive file. Impostando `commit` su `false` e sincronizzando di nuovo, oppure eseguendo `blockstudio-githooks remove`, viene ripristinato il percorso dell’hook registrato e vengono eliminati solo i file gestiti da Blockstudio.

### Contratto del progetto

`blockstudio-agents` scrive un `AGENTS.md` che specifica dove si trovano i blocchi, cosa rappresenta una
pagina nel progetto, quali funzionalità sono attive e quali elementi l’analizzatore rifiuterà.

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

Il documento viene generato dai dati del progetto, non da un template. Il contratto di un tema con intestazione `style.css`,
blocchi e pagine basate su file è diverso da quello di un plugin che registra solo blocchi e riporta i conteggi, le directory, i namespace e i linguaggi dei template individuati dallo scanner. `blockstudio.json` determina quali funzionalità compaiono,
quindi un progetto senza prerendering statico non ne fa mai menzione.

La sezione sulla correttezza viene letta dai file di regole del preset selezionato, livello per livello; se un preset acquisisce una nuova regola, questa modifica ogni contratto generato con quel preset.

La gestione della proprietà segue le stesse regole dell’hook di commit. Un file privo del marcatore di generazione viene rifiutato invece di essere sostituito, a meno che `--force` non indichi diversamente; una sezione di note in fondo viene conservata durante la rigenerazione; `--check` restituisce il codice `1` se il contratto non è aggiornato; `--stdout` lo stampa senza modificare il filesystem.

### Indice della documentazione

`blockstudio-llm.txt` ora è un indice, non una concatenazione. Ogni documento
pubblicato compare una sola volta, nella propria sezione e sottosezione, con la route,
il file sorgente, una breve descrizione dello scopo e gli identificatori di cui è responsabile: percorsi
 delle impostazioni, nomi degli hook, funzioni e classi PHP e comandi.

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

Un agente legge l’indice, individua il documento che contiene l’identificatore che gli interessa e apre quel documento. La concatenazione precedente da mezzo megabyte viene comunque generata e pubblicata in `/blockstudio-llm-full.txt`; semplicemente non è più la prima cosa che viene fornita.

## Tag canonici dei blocchi

Un comando autonomo riscrive le abbreviazioni di prefisso e alias nella forma canonica `<bs:namespace-slug>`, che registra il vero nome del blocco e si risolve senza che sia caricato un filtro di progetto.

Con un prefisso `brand` su `theme-components` e un prefisso `ui` su `bsui`, questa abbreviazione:

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

equivale a:

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

I prefissi e gli alias esatti continuano a funzionare e non sono deprecati. Il comando non carica WordPress e non scrive nulla senza `--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` associa ogni prefisso ai suoi namespace e `--known-blocks` elenca i nomi dei blocchi registrati. Il rapporto registra le corrispondenze da forme legacy a forme canoniche con il numero di occorrenze, gli hash per file e gli elenchi separati di tag sconosciuti, alias ambigui e tag dinamici. `--apply` rifiuta di scrivere finché ne rimane qualcuno, a meno che non venga passato `--allow-unresolved`.

Vengono gestiti markup appaiati, annidati e autochiudenti, compresi i tag letterali nelle stringhe PHP. Cambiano solo i nomi dei tag, una seconda esecuzione non produce modifiche e gli esempi nei commenti, nei blocchi di codice, in `<pre>` o in `<code>` vengono inclusi solo nel rapporto.

## Comportamento predefinito

L'installazione della versione 7.6, da sola, non cambia nulla.

**Il profilo delle prestazioni è impostato per impostazione predefinita su `compat`.** L'output dell'head, oEmbed, XML-RPC, Heartbeat, le impostazioni predefinite delle immagini, il prefetch dei link, il caricamento differito e `<title>` del frontend restano come li hanno lasciati WordPress e il tema.

**Queste funzioni restano disattivate finché non vengono abilitate:** tutte le chiavi `performance.staticPrerender`, `performance.measurement`, `performance.media` e `themeDefaults`, oltre a `githooks.commit`, `dev.canvas.enabled`, `ui.enabled`, `tailwind.enabled` e `blockTags.enabled`. Quando la pre-generazione statica è disattivata, non scrive file né installa drop-in.

**Canvas e Render sono passivi.** Leggono i registri esistenti e generano solo ciò che viene richiesto; nessuno dei due si integra nell'output del frontend né registra route. La schermata di amministrazione di Canvas richiede ancora `dev.canvas.enabled` e `edit_posts`.

**Per un'analisi più rigorosa, occorre specificarla.** L'installazione di `blockstudio/phpstan` abilita solo l'estensione di base e il comando canonico esegue `base`, a meno che il progetto non specifichi un preset.

**I file generati richiedono l'esecuzione del relativo comando.** `githooks.commit` non fa nulla finché non viene eseguito `blockstudio-githooks sync`; lo stesso vale per `AGENTS.md` finché non viene eseguito `blockstudio-agents`.

## Aggiornamento dalla versione 7.5

I requisiti non cambiano: PHP 8.2 o versione successiva, WordPress 6.7 o versione successiva.

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

**Le cache vengono ricostruite una volta.** L'identità di runtime include la versione Blockstudio, quindi la prima richiesta dopo l'aggiornamento parte da una cache fredda e gli oggetti precedenti vengono eliminati. È possibile eliminare la vecchia cache Tailwind in `wp-content/uploads/blockstudio/tailwind/cache`; uno snippet che ne utilizzava i file con un glob dovrebbe usare invece `Blockstudio\Runtime_Cache::purge('tailwind')`.

La vecchia directory piatta `wp-content/blockstudio/cache/runtime`, precedente alla versione 7.6, viene automaticamente rinominata e spostata fuori dal percorso attivo, poi rimossa tramite passaggi WP-Cron limitati. Non è quindi necessario eliminare i grandi alberi di file di lock legacy durante una richiesta di deployment.

**I file generati hanno una destinazione precisa.** `assets/media.json` deve essere incluso nel controllo di versione o in un passaggio di build. La mappa delle route, il drop-in `advanced-cache.php` e la dichiarazione `WP_CACHE` esistono solo quando `earlyServe` è abilitato; l'hook pre-commit esiste solo quando la sincronizzazione è attiva. Tutti gli altri file generati si trovano sotto `cache.path` e possono essere eliminati senza problemi.

**Non è stato rimosso né rinominato nulla.** `bs_render_block()`, `bs_block()`, `Blockstudio\Pages` e `Blockstudio\Patterns` restano le superfici di contenuto canoniche basate su file.

**Il rollback è specifico per funzionalità.** Riportare `performance.profile` a `compat`, `staticPrerender.enabled` a `false`, `githooks.commit` a `false` insieme a `sync`, e `cache.enabled` a `false` annulla ogni volta un livello.

Un ordine di adozione ragionevole:

1. Impostate `performance.profile` su `speed`, poi controllate l'output dell'head, i feed e gli eventuali plugin che dipendono da oEmbed o XML-RPC.
2. Generate `assets/media.json`, spostate i template in `bs_media_image()`, poi abilitate `performance.media.lazy`.
3. Abilitate `performance.staticPrerender` lasciando disattivato `earlyServe`, verificate le chiamate con `wp bs prerender status`, poi attivate `earlyServe`.
4. Eseguite `blockstudio-phpstan --preset theme` finché non è pulito, prima di mettere qualsiasi preset dietro `githooks.commit`.

## Dove trovare i dettagli

- [Canvas](https://blockstudio.dev/it/docs/dev/canvas/) e il suo [inventarioAPI e ](https://blockstudio.dev/it/docs/dev/canvas/#public-inventory-and-document-api)documento⟦I0:⟧
- [Rendering](https://blockstudio.dev/it/docs/blocks/rendering/#structured-compositions-and-complete-documents), [UI Componenti](https://blockstudio.dev/it/ui/#public-inventory-and-examples) e [UI Composizione](https://blockstudio.dev/it/ui/composition/)
- [Impostazioni](https://blockstudio.dev/it/docs/general/settings/) e [prestazioni](https://blockstudio.dev/it/docs/general/settings/#performance)
- [Prestazioni](https://blockstudio.dev/it/docs/production/performance/), [Caching](https://blockstudio.dev/it/docs/production/caching/) e [Pre-generazione statica](https://blockstudio.dev/it/docs/production/static-prerendering/)
- [Tailwind CSS](https://blockstudio.dev/it/docs/tailwind/#template-composition-helpers)
- [PHPStan](https://blockstudio.dev/it/docs/dev/phpstan/): [preset](https://blockstudio.dev/it/docs/dev/phpstan/#analysis-presets), [comando canonico](https://blockstudio.dev/it/docs/dev/phpstan/#canonical-command), [hook commit gestito](https://blockstudio.dev/it/docs/dev/phpstan/#managed-commit-hook) e il [contratto del progetto](https://blockstudio.dev/it/docs/dev/phpstan/#project-contract-for-coding-agents)
- [Integrazione AI](https://blockstudio.dev/it/docs/dev/ai/): l'indice della documentazione e il testo completo
- [Migrazione](https://blockstudio.dev/it/docs/dev/migration/v7/#canonical-block-tags) e [PHP Hooks](https://blockstudio.dev/it/docs/blocks/hooks/php/)
