Ottimizzatore e asset

01Panoramica

Il frontend accoda il CSS e il JS dei soli blocchi presenti in un documento Nucleo. Il compilatore scrive l'elenco nei metadati del post. Sopra questa base, il runtime applica una tabella di regole a tutti gli stili e script in coda, anche quelli di plugin e tema. La tabella è l'artefatto asset-rules. Viene compilata dalle regole dell'utente e da regole predefinite per moduli e WooCommerce. L'audit (Pro) misura gli asset caricati da ogni tipo di template e propone regole. Il purger (Pro) riduce i fogli di terzi al CSS che può corrispondere al DOM della pagina. Le varianti ridotte finiscono nello stesso artefatto asset-rules. Il CSS critico va inline nella pagina. Con un critico pubblicato, i fogli locali passano a un loader che non blocca il rendering. L'ottimizzazione dal pannello Prestazioni (Pro) unisce riduzione e critico: misura nel browser dell'amministratore, calcola un candidato, lo controlla e pubblica solo le parti senza differenze. Il sito pubblico non verifica la licenza: regole, varianti ridotte e critico già pubblicati restano attivi anche senza licenza.

Chiave del template: le regole, le varianti ridotte e il critico usano la chiave del template corrente: 404, search, home, page, single, product, single-<post_type>, archive. Con WooCommerce e il pacchetto Pro si aggiungono product, cart, checkout, account e product-archive. La chiave d'oggetto è <post_type>:<ID>, per esempio page:12.

02Caricamento degli asset sul frontend

Asset dei documenti Nucleo

Cosa fa: su una pagina singola costruita con Nucleo accoda i fogli e gli script elencati nei metadati della pagina. Rimuove i duplicati per src: vince la prima occorrenza. I fogli ricevono l'handle nucleo-<8 caratteri dell'MD5 dell'URL>. Gli script eager vanno in fondo alla pagina con defer. Gli script con strategia visible, interaction o idle passano al loader nucleo-loader tramite window.ncLazy.

Come si usa: automatico. Il token CSS del sito va inline sull'handle nucleo-tokens, accodato per primo.

Parametri: nessuno.

Permessi: nessuno, è il frontend pubblico.

Edizione: Free

Limiti noti: la modalità di emergenza (costante NUCLEO_SAFE_MODE o opzione nucleo_safe_mode) spegne tutti gli asset Nucleo e anche le regole sugli asset. Il loader attiva visible e interaction su ogni elemento .nc-<tipo> della pagina e carica lo script una volta; senza quegli elementi lo script non parte. La strategia idle non cerca elementi: parte quando il browser è libero, o dopo 200 ms dove quella funzione non esiste.

Preload del font principale

Cosa fa: invia un header HTTP Link: <url>; rel=preload; as=font; type="font/woff2"; crossorigin per ogni font da precaricare, fino a due URL senza duplicati: il file del font $font.body a peso 400 normale (se presente, altrimenti il primo file della famiglia o il primo font installato) e il file del font heading a peso 700, se presente.

Come si usa: automatico. L'URL viene salvato nella chiave preload dell'artefatto tokens. Font locali e fallback: vedi il capitolo Design token.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: al massimo due file. Solo sulle pagine singole con metadati Nucleo. Se gli header sono già partiti, il preload non viene inviato.

Applicazione delle regole

Cosa fa: in wp_enqueue_scripts, a priorità 9999, legge l'artefatto asset-rules e applica la tabella alla coda di stili e script. Ordine: dequeue e replace sugli stili, sostituzione con le varianti ridotte, regole sugli script, poi il CSS critico. Ripete la sostituzione delle varianti e il passaggio al loader in wp_print_styles e wp_print_footer_scripts (priorità 1), per i fogli accodati tardi.

Come si usa: automatico su ogni pagina del frontend, anche se non costruita con Nucleo. Lo store degli artefatti è in wp-content/uploads/nucleo/store (cartella di generazione), con fallback sulle opzioni.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free. Nessun controllo di edizione.

Limiti noti: senza artefatto asset-rules non applica regole né varianti, ma applica comunque il critico. Gli handle si cercano con lo stesso nome tra stili e script: una regola su foo vale per lo stile e per lo script foo. L'azione defer sugli stili non ha effetto.

Anteprima CSS (?nucleo_css=)

Cosa fa: genera la pagina in una modalità di confronto.

• original: nessuna variante ridotta e nessun critico.
• candidate: varianti e critico del candidato non pubblicato.
• critical: solo il critico del candidato, senza fogli locali e senza loader.
• published: come il frontend, ma senza il caricamento dei CSS completi.

Con un'anteprima attiva la pagina si genera come per un visitatore, senza barra di amministrazione e senza redirect del checkout vuoto.

Come si usa: https://sito/pagina/?nucleo_css=candidate, da un utente collegato. Lo usa il pannello Prestazioni.

Parametri:

Permessi: manage_options. Per gli altri utenti il parametro si ignora.

Edizione: Free. Il candidato si produce solo con le ability Pro.

Limiti noti: nessun nonce, per scelta (anteprima in sola lettura). Un cambio di utente durante la richiesta chiude l'anteprima.

03Regole per handle

Formato delle regole

Cosa fa: descrive cosa fare di un handle di WordPress (stile o script) per template o per singolo oggetto. Le regole vengono compilate in una tabella per chiave e handle. Le regole non valide si ignorano. Un page:<slug> o post:<slug> che non corrisponde a nessuna pagina o articolo salta la regola e produce un avviso. Con più regole sulla stessa chiave e lo stesso handle vince l'ultima.

Come si usa: elenco JSON passato a nucleo/assets-rules-set. Esempio:

[
  {"action": "dequeue", "handle": "contact-form-7", "templates": ["*"], "except": ["page:12"]},
  {"action": "defer", "handle": "plugin-x-analytics", "strategy": "async"},
  {"action": "replace", "handle": "swiper-old", "with": "swiper"}
]

Parametri:

Permessi: vedi nucleo/assets-rules-set.

Edizione: Free

Limiti noti: alla pubblicazione page:<slug> e post:<slug> diventano page:<ID> e post:<ID>. Se lo slug non esiste la regola viene saltata e il messaggio compare in nucleo_asset_rules_warnings. Un elemento con forma non valida in templates o except scarta l'intera regola.

Risoluzione e precedenza

Cosa fa: per ogni handle in coda cerca la voce nell'ordine: chiave d'oggetto, chiave di template, *. Una voce il cui except contiene il template o l'oggetto corrente non vale e lascia il passo al livello successivo. Un dequeue che rimuoverebbe un handle da cui dipende un altro handle ancora in coda non si applica: la regola finisce tra le regole bloccate, che il runtime ignora.

Come si usa: automatico.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: replace rimuove sempre l'handle. Accoda with solo se è registrato; altrimenti equivale a un dequeue, senza controllo delle dipendenze. defer con interaction o idle imposta strategy: defer e aggiunge l'attributo data-nc-load="<strategia>" al tag. Il tag diventa <script type="text/plain"> con data-nc-src, e il loader lo attiva: interaction al primo gesto dell'utente (pointerdown, keydown, scroll o touchstart), idle quando il browser è libero o dopo 2 secondi. Con almeno uno script ritardato Nucleo accoda il loader, anche su una pagina senza blocchi lazy. Uno script con dipendenti in coda o con script inline non si ritarda: resta defer.

Regole predefinite

Cosa fa: Nucleo mette prima delle regole dell'utente due gruppi di regole predefinite. Una regola utente sulla stessa chiave e handle le sostituisce.

• Moduli: dequeue su * degli asset di Contact Form 7 (contact-form-7, swv), Gravity Forms (gform_gravityforms, gform_json), WPForms (wpforms-full), Fluent Forms (fluent-form-styles, fluent-form-submission). except contiene le pagine che dipendono da form:<plugin>.
• WooCommerce (solo pacchetto Pro, con WooCommerce attivo): dequeue su * di woocommerce-general, woocommerce-layout, woocommerce-smallscreen, wc-blocks-style, woocommerce, wc-add-to-cart, wc-order-attribution, sourcebuster-js, woocommerce-inline, tranne product, product-archive, cart, checkout, account. Inoltre dequeue di wc-cart-fragments ovunque, salvo opzione nucleo_woo_fragments = keep.

Come si usa: automatico.

Parametri: impostazione performance.wooFragments (keep oppure off) di nucleo/settings-set.

Permessi: nessuno per l'applicazione.

Edizione: moduli Free. WooCommerce: richiede i file del pacchetto Pro, senza controllo della licenza.

Limiti noti: le regole predefinite non compaiono tra le regole dell'utente né nel campo rules del report.

Pubblicazione della tabella

Cosa fa: salva le regole utente nell'opzione nucleo_asset_rules (autoload false) e riscrive l'artefatto asset-rules come { table, purged }. Conserva le varianti ridotte già prodotte. Gli avvisi dell'ultima pubblicazione stanno nell'opzione nucleo_asset_rules_warnings (autoload false).

Come si usa: nucleo/assets-rules-set, import del sito (rules/assets.json, vedi il capitolo sui comandi WP-CLI). Ripubblica anche all'attivazione o alla disattivazione di un plugin, dopo la modifica di un documento e nella ricostruzione dello store.

Parametri: nessuno.

Permessi: quelli del punto di ingresso.

Edizione: Free

Limiti noti: la pubblicazione sostituisce tutte le regole utente. Non esiste un salvataggio parziale.

nucleo/assets-rules-set

Cosa fa: sostituisce le regole asset dell'utente e ripubblica la tabella. Registra l'evento assets-rules-set nel registro attività.

Come si usa: ability, oppure scheda Prestazioni → Regole (Pro). Da riga di comando:

# sostituisce le regole asset con l'utente indicato
wp nucleo ability run assets-rules-set --input='{"rules":[...]}' --user=admin

La scheda completa è nel capitolo sulle ability di scrittura.

Parametri:

Permessi: manage_options; scope OAuth nucleo:design.

Edizione: Free

Limiti noti: risponde { ok: true, count, warnings }. count è il numero di regole ricevute, valide o no. warnings è la lista di testi che descrivono le regole saltate (per esempio uno slug page:<slug> inesistente).

04Audit degli asset

Audit per template

Cosa fa: pianifica un job per ogni template campione e li esegue uno alla volta in WP-Cron (nucleo_asset_audit), a 10 secondi di distanza. Ogni job fa una richiesta loopback alla pagina campione con un token firmato. Il token attiva la cattura degli stili e degli script in coda a fine pagina.

Come si usa: nucleo/assets-audit, oppure scheda Prestazioni → Audit (Pro).

Parametri: vedi nucleo/assets-audit. URL campione per template:

Permessi: vedi nucleo/assets-audit.

Edizione: Pro

Limiti noti:

• Timeout della richiesta: 20 secondi. Il token è valido 10 minuti e firmato con HMAC-SHA256 usando wp_salt('auth').
• La richiesta verifica il certificato SSL quando l'URL è sul dominio del sito o su localhost. Gli URL campione sono sul dominio del sito: un sito con certificato non valido produce un job fallito.
• Se il sito non raggiunge se stesso, il job finisce in failed con il messaggio di errore o il codice HTTP.
• Le chiavi vecchie post, category e product_cat si leggono come single, archive e product-archive nei job dell'audit e nelle varianti ridotte salvate.
• Un nuovo avvio sostituisce il piano precedente e azzera i job completati e falliti.

Dati salvati dall'audit

Cosa fa: salva lo stato del piano e il registro degli asset.

• Opzione nucleo_asset_audit (autoload false): { jobs, done, failed }.
• Transient nucleo_capture_<job> per un'ora: la cattura grezza.
• Opzione nucleo_asset_registry (autoload false): per template { styles, scripts, url, date }. Ogni asset ha handle, src, origin, hash (SHA-1), size, gzip e library.

Come si usa: lettura con nucleo/assets-report.

Parametri: nessuno.

Permessi: nessuno (dati interni).

Edizione: Pro

Limiti noti: il registro tiene solo i file locali (sotto ABSPATH o WP_CONTENT_DIR). Gli asset esterni si scartano. origin vale plugin:<cartella>, theme:<cartella>, core, nucleo o external. Il valore gzip arriva nel report solo quando è noto.

Riconoscimento delle librerie

Cosa fa: riconosce una libreria dal banner (primi 2 KB del file) o dal percorso. Restituisce nome@versione. Librerie note: jquery-ui, jquery, swiper, slick, bootstrap, fontawesome, lodash, gsap, owl-carousel, select2, flatpickr, lightbox, magnific-popup, isotope, masonry, aos, animate.css.

Come si usa: automatico durante l'audit.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Pro

Limiti noti: versioni solo nel formato X.Y.Z.

Report degli asset

Cosa fa: costruisce il report dal registro.

• assets: per handle src, origin, hash, size, gzip (quando noto), library, templates.
• duplicates: gruppi di handle con lo stesso hash.
• versions: librerie presenti in più versioni.
• templates: per template bytes, styles, scripts, cssBytes, jsBytes, url, date e heaviest (i tre file più pesanti).
• suggestions: un dequeue per ogni duplicato oltre il primo (ordine alfabetico), con i template dove compare; un review per ogni libreria in più versioni.

Come si usa: nucleo/assets-report, che aggiunge audited, pending, failed, rules (le regole utente attive), urls e warnings. Scheda Prestazioni → Asset (Pro).

Parametri: nessuno.

Permessi: manage_options; scope OAuth nucleo:read.

Edizione: Pro

Limiti noti: size è la dimensione non compressa. Il report non individua asset "caricati ma non necessari". Il motivo di dequeue è una stringa italiana fissa (duplicato di <handle> (stesso hash)), non tradotta.

nucleo/assets-audit

Cosa fa: pianifica l'audit dei template campione, tutti o quelli indicati.

Come si usa: ability. Da riga di comando: wp nucleo ability run assets-audit --user=admin. La scheda completa è nel capitolo sulle ability di scrittura.

Parametri:

Permessi: manage_options; scope OAuth nucleo:design.

Edizione: Pro

Limiti noti: nessun template valido produce { ok: false, error: { code: "no_templates" } }. L'esito { ok: true, jobs } indica solo i job pianificati: il risultato arriva dopo, con nucleo/assets-report.

05Riduzione del CSS di terzi (purger)

Purger

Cosa fa: rimuove da un foglio CSS le regole che non possono corrispondere al DOM. Il DOM viene letto dall'HTML: tag, classi, ID e nomi di attributo.

• Tiene una regola se almeno un selettore può corrispondere. Toglie dalla regola i soli selettori impossibili.
• Ignora il contenuto di :is(), :where(), :has(), :not() e le pseudo-classi semplici; verifica il resto.
• Tiene sempre i selettori con escape (\) o ::selection, e quelli con una classe che inizia con una voce della safelist.
• Tiene intere le regole con proprietà custom (--x).
• Filtra dentro @media, @supports e @layer; toglie i blocchi rimasti vuoti. Le altre at-rule (per esempio @font-face) restano intere.
• Toglie i @keyframes non referenziati da animation o animation-name nelle regole rimaste.

Come si usa: interno. Lo usano nucleo/css-purge e nucleo/css-optimize.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Pro

Limiti noti: un CSS che il parser non riesce ad analizzare torna intero. Output compatto.

Safelist

Cosa fa: elenco di prefissi di classe che il purger tiene sempre. Predefiniti: is-open, active, show, open, select2-, added, loading, processing, blockUI, woocommerce-message, woocommerce-error, woocommerce-info, woocommerce-notices-wrapper, wc-block-components-notice, woocommerce-invalid, woocommerce-validated, wc-variation-selection-needed, woocommerce-variation. Si aggiungono le voci dell'opzione nucleo_purge_safelist.

Come si usa: nucleo/settings-set con { "settings": { "performance": { "purgeSafelist": ["mio-stato"] } } }, oppure scheda Prestazioni → Ottimizzazione, riquadro Safelist (una classe per riga). Lettura con nucleo/settings-get.

Parametri:

Permessi: manage_options; scope OAuth nucleo:admin (settings-set).

Edizione: Free per l'impostazione. Ha effetto solo con le funzioni Pro di riduzione.

Limiti noti: per le voci senza prefisso il confronto è "la classe inizia con la voce". Una voce con il punto (.is-open) confronta la classe esatta; una voce con # (#bar) confronta l'ID esatto. Un selettore complesso non è supportato, anche se la descrizione di settings-set parla di "selettori".

nucleo/css-purge

Cosa fa: riduce i fogli indicati per un tipo di template sull'HTML di una pagina campione. Scrive uploads/nucleo/purged/<handle>.<template>.<sha1 8>.css, riscrive gli url() e gli @import relativi in assoluti e registra la variante nelle regole asset del template. Il sito serve la variante al posto del foglio originale.

Come si usa: ability. Esempio di input: {"template":"page","handles":[{"handle":"plugin-x","src":"https://sito/wp-content/plugins/x/style.css"}]}. La scheda completa è nel capitolo sulle ability di scrittura.

Parametri:

Permessi: manage_options; scope OAuth nucleo:design.

Edizione: Pro

Limiti noti:

• Pagina campione: ultimo post pubblicato per page, single (articolo) e product; per gli altri template la home. Una sola pagina, richiesta anonima con timeout di 15 secondi.
• Errori nell'esito { ok: false, error: { code } }: sample_unreachable (la pagina non risponde 200), dir_unwritable, write_failed.
• Gli handle con src non locale si saltano senza errore.
• Le classi aggiunte dal JavaScript non si vedono: servono la safelist o l'ottimizzazione dal pannello.
• Annullamento: nucleo/css-optimize-off sullo stesso template. Dopo ogni nucleo/css-purge riuscito, i file .css in uploads/nucleo/purged non più referenziati vengono cancellati. nucleo/css-optimize-off non li cancella: restano fino al successivo nucleo/css-purge.

Servizio delle varianti ridotte

Cosa fa: sul frontend sostituisce lo src di un foglio in coda con la variante del template corrente. Serve la variante solo se il file è sotto la cartella uploads.

• Modalità predefinita: dopo il primo pointerdown, keydown o scroll, uno script inline (handle nucleo-full-css) aggiunge i link ai CSS originali.
• Modalità strict (opzione nucleo_purge_mode = strict): i CSS originali non si caricano mai.

Come si usa: automatico. La modalità si sceglie con nucleo/settings-set, { "settings": { "assets": { "purgeMode": "strict" } } }, oppure "normal" per tornare alla modalità predefinita.

Parametri: impostazione assets.purgeMode di nucleo/settings-set (normal o strict), salvata nell'opzione nucleo_purge_mode.

Permessi: manage_options; scope OAuth nucleo:admin (settings-set).

Edizione: Free. Il runtime non controlla l'edizione.

Limiti noti: nelle anteprime ?nucleo_css= i CSS originali non si caricano.

06CSS critico

Salvataggio e uso del critico

Cosa fa: tiene un CSS critico per template nell'artefatto critical ({ template: css }). Sul frontend lo stampa inline sull'handle nucleo-tokens. Poi toglie dalla coda tutti i fogli con file locale (Nucleo e terzi, dipendenze comprese, in ordine di stampa) e li passa al loader tramite window.nucleoCss. Il loader li inserisce subito dopo lo stile inline con media="print" e li porta al loro media al caricamento. Lo stile inline di ogni foglio rimosso resta nella pagina con l'handle <handle>-nc-inline.

Come si usa: nucleo/critical-set, nucleo/css-optimize-apply, CLI locale nucleo critical, servizio esterno.

Parametri: nessuno.

Permessi: quelli del punto di ingresso.

Edizione: Free

Limiti noti:

• Limite di 50 KB (51200 byte) dopo la rimozione di </style.
• Fallback: senza critico per il template, la pagina carica i fogli normalmente con <link> bloccanti.
• I fogli esterni (CDN) restano <link> normali.

nucleo/critical-set

Cosa fa: salva il critico di un template e sostituisce quello precedente.

Come si usa: ability. La usano la CLI locale, il servizio esterno (callback) e il riquadro "Critical CSS" della scheda Ottimizzazione, dove il CSS si incolla a mano. La scheda completa è nel capitolo sulle ability di scrittura.

Parametri:

Permessi: edit_theme_options; scope OAuth nucleo:design.

Edizione: Free

Limiti noti: oltre 50 KB o template vuoto: WP_Error invalid_critical_css. Tipi errati: WP_Error invalid_input. Esito { ok: true, bytes }. Non aggiorna lo stato di nucleo/css-status.

nucleo/critical-request

Cosa fa: chiede a un servizio esterno il calcolo del critico. Invia POST <url>/v1/jobs con Authorization: Bearer <key> e corpo { site, templates: [{ template, url }], callback }. callback è l'URL REST di nucleo/critical-set.

Come si usa: ability, oppure pulsante "Request from service" della scheda Ottimizzazione. Configurazione con nucleo/settings-set, gruppo service (url, key), salvato nell'opzione nucleo_service. La scheda completa è nel capitolo sulle ability di scrittura.

Parametri:

Permessi: edit_theme_options; scope OAuth nucleo:design.

Edizione: Free per l'ability. La scheda Impostazioni → Servizio è Pro.

Limiti noti:

• URL non https:// o chiave vuota: WP_Error service_not_configured. Errore di rete: service_unreachable. Risposta non 2xx: service_error. Timeout di 15 secondi.
• URL campione: ultimo post pubblicato per page, single e product; la home per tutti gli altri template, anche archive, search e 404.

CLI locale nucleo critical

Cosa fa: apre ogni URL con Playwright (Chromium), misura la copertura CSS e scrive <template>.css con i soli intervalli usati di ogni foglio. Senza --no-push invia ogni file a nucleo/critical-set.

Come si usa:

# calcola il critico per due template e lo invia al sito
nucleo critical --urls home=https://sito.it/,page=https://sito.it/chi-siamo/ [--out critical] [--no-push]

Autenticazione Basic (utente e Application Password) verso l'Abilities API. Dettagli nel capitolo sulla CLI locale.

Parametri:

Permessi: edit_theme_options per l'invio; manage_options per leggere il report.

Edizione: Free con --urls. Senza --urls richiede nucleo/assets-report (Pro).

Limiti noti:

• Senza --urls una voce di urls senza URL assoluto finisce tra le saltate. Senza nessun URL il comando stampa "no URL to analyse" ed esce con 1.
• Una coppia di --urls senza =, senza template o senza URL è un errore d'uso, prima di ogni chiamata.
• Il critico raccoglie le regole che colpiscono gli elementi della prima schermata in quattro viewport: 390×844, 820×1180, 1440×900 e 2560×1440. Si ferma a 50 KB. Se nucleo/critical-set rifiuta il CSS, il comando si ferma con il messaggio del sito.

07Ottimizzazione CSS dal pannello

Flusso dell'ottimizzazione

Cosa fa: per un tipo di template esegue nel browser dell'amministratore questi passi:

Come si usa: Prestazioni → Ottimizzazione (pagina nucleo-performance).

Parametri: nessuno.

Permessi: pagina edit_theme_options; le ability richiedono manage_options.

Edizione: Pro (pagina con 'edition' => 'pro' nel registro).

Limiti noti: timeout di caricamento di ogni iframe: 30 secondi. Al massimo 20 differenze conservate.

Pagine campione

Cosa fa: elenca fino a 5 URL per template, con le chiavi di template: home, page (esclusa la front page statica), single, archive (categorie non vuote), search, 404. Con WooCommerce: product, product-archive (prima la pagina Shop), cart, checkout, account. Tiene solo i template con almeno un URL.

Come si usa: interno, esposto da nucleo/css-status nel campo urls.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Pro

Limiti noti: nessun campione per i tipi di post personalizzati (single-<tipo>).

nucleo/css-optimize

Cosa fa: calcola il candidato di un template. Legge i fogli <link rel="stylesheet" id="<handle>-css"> locali dei campioni, uno per handle. Riduce i fogli di terzi sul DOM unito di tutti i campioni, con safelist e classi ricevute. Lascia interi i fogli nucleo-*. Esclude admin-bar e dashicons. Scrive i file ridotti in uploads/nucleo/purged. Calcola il critico riducendo tutti i fogli concatenati sul DOM della prima schermata, senza safelist; un foglio con media proprio va dentro la sua @media. Salva il candidato, senza pubblicarlo.

Come si usa: ability, chiamata dal pannello. La scheda completa è nel capitolo sulle ability di scrittura.

Parametri:

Permessi: manage_options; scope OAuth nucleo:design.

Edizione: Pro

Limiti noti: l'esito contiene candidateId, da passare a nucleo/css-optimize-apply. Errori nell'esito { ok: false, error: { code } }: no_stylesheets, dir_unwritable, write_failed. Critico oltre 50 KB: candidate.critical.error = critical_too_big e nessun critico. Senza elementi nella prima schermata il critico non si calcola. Input non valido: WP_Error invalid_input.

nucleo/css-optimize-apply

Cosa fa: pubblica le parti del candidato scelte e rimuove il candidato. Toglie prima tutte le varianti ridotte del template. Con purge registra le varianti del candidato. Con critical e un critico nel candidato lo salva; altrimenti cancella il critico del template. Salva la voce di stato nell'opzione nucleo_css_status (autoload false), con le impronte MD5 dei fogli di origine.

Come si usa: ability, chiamata dal pannello. La scheda completa è nel capitolo sulle ability di scrittura.

Parametri:

Permessi: manage_options; scope OAuth nucleo:design.

Edizione: Pro

Limiti noti: se il candidato salvato non è quello con candidateId, per esempio perché un'altra misura lo ha sostituito, la chiamata risponde candidate_changed e non pubblica nulla. Un candidato misurato prima di un cambio del sito dà candidate_stale: va misurato di nuovo. Stato risultante active (riduzione pubblicata e critico pubblicato o assente nel candidato), partial (solo una delle due) o failed (nessuna). Senza candidato: { ok: false, error: { code: "no_candidate" } }. Critico oltre 50 KB: critical_too_big.

nucleo/css-optimize-off

Cosa fa: spegne riduzione e critico di un template. Toglie le varianti dall'artefatto asset-rules e il critico dall'artefatto critical. Conserva la voce di stato con state: off.

Come si usa: ability, oppure pulsante di spegnimento nella scheda Ottimizzazione. La scheda completa è nel capitolo sulle ability di scrittura.

Parametri:

Permessi: manage_options; scope OAuth nucleo:design.

Edizione: Pro

Limiti noti: annulla anche le varianti create con nucleo/css-purge e il critico salvato con nucleo/critical-set. Non cancella i file in uploads/nucleo/purged: restano fino al successivo nucleo/css-purge.

nucleo/css-status

Cosa fa: restituisce una voce per ogni template dei campioni. Stati: none (mai ottimizzato), off, active, partial, failed. stale vale true se una voce active o partial ha un foglio di origine cambiato (MD5 diverso) o non più trovato. Quando il sito cambia dopo la misura, il plugin ritira l'ottimizzazione pubblicata: la voce diventa off con reason: site_changed e il sito pubblico torna ai fogli originali, senza critico. Contano come cambi del sito il salvataggio di un documento, la pubblicazione dei token, l'aggiornamento o l'attivazione di un plugin e il cambio di tema.

Come si usa: ability. La scheda completa è nel capitolo sulle ability di lettura.

Parametri: nessuno.

Permessi: manage_options; scope OAuth nucleo:design.

Edizione: Pro

Limiti noti: i template ottimizzati ma non più presenti tra i campioni non compaiono.

08Compilazione degli stili dei documenti

Compilatore degli stili

Cosa fa: trasforma gli stili dei nodi in CSS minificato e in una classe per nodo. Ordine dell'output: regole base e style.custom, un blocco @media (min-width) per breakpoint, un blocco @container per i discendenti di un nodo con settings.responsiveMode: "container", le regole di visibilità per breakpoint (display:none!important), i @keyframes dei preset usati, una regola @media (prefers-reduced-motion:reduce) che spegne animazioni e transizioni.

• Nodi con lo stesso stile normalizzato condividono la classe nc-h<sha1 6>. Gli altri ricevono nc-<scope><id>; un id senza cifre prende il prefisso n-.
• I token ($gruppo.nome) si risolvono anche nei valori composti. Un token sconosciuto scarta la dichiarazione.
• style.parts.<parte> accetta solo le chiavi dei gruppi size, spacing, typography, color, border, effects, layout, motion, e solo per le parti dichiarate dal blocco.
• style.custom: selettore che inizia con & e usa caratteri sicuri; proprietà ^-{0,2}[a-z][a-z0-9-]{0,60}$; valori senza url(.

Come si usa: interno al compilatore. Dettagli dello schema nel capitolo sullo schema e i blocchi, e nel capitolo su compilatore e runtime.

Parametri: breakpoint predefiniti base 0, md 768, lg 1024, xl 1920 px (mobile first).

Permessi: nessuno.

Edizione: Free

Limiti noti: valori non validi si scartano in silenzio, anche in compilazione.

Chiavi di stile

Cosa fa: mappa le chiavi camelCase dei documenti sulle proprietà CSS, per gruppo.

• spacing: padding, margin, gap.
• size: width, maxWidth, minWidth, maxHeight, minHeight, height, aspectRatio.
• color: color, background, accentColor.
• typography: fontSize, fontWeight, lineHeight, letterSpacing, fontFamily, fontStyle, textAlign, textDecoration, textTransform, whiteSpace.
• layout: display, columns, direction, wrap, justify, align, order, flexGrow, flexShrink, flexBasis, alignSelf, justifySelf.
• border: border, borderTop, borderRight, borderBottom, borderLeft, borderRadius, boxShadow.
• effects: opacity, objectFit, filter, transform.
• position: position, top, right, bottom, left, inset, zIndex, scrollMarginTop, overflow, overflowX, overflowY.
• menu (nc/menu): itemColor, itemColorHover, itemColorActive, itemBackground, itemBackgroundHover, itemBackgroundActive, itemDecoration, itemDecorationHover, itemWeight, itemWeightActive, itemPadding, itemRadius, itemGap, submenuBackground, panelWidth, panelBackground.
• motion: animation, animationDuration, animationDelay, transition.
• Parti dei blocchi interattivi: gruppi controls, buttons, choices, carousel, link, results, fields. Ogni chiave scrive una variabile --nc-* sul nodo.
• Stati: le chiavi color, background, border, borderTop, borderRight, borderBottom, borderLeft, boxShadow, opacity, filter, fontWeight e textDecoration accettano i suffissi Hover (:is(:hover,:focus-within)) e Current (.is-current).

Come si usa: chiavi in style dei nodi.

Parametri: valori ammessi principali:

Permessi: nessuno.

Edizione: Free

Limiti noti: un numero riceve px, salvo proprietà senza unità (font-weight, line-height, opacity, order, flex-grow, flex-shrink, z-index, column-count e ogni proprietà che finisce in -weight). Valori con ;, {, }, <, >, \, caratteri di controllo, /* o */ si scartano.

Animazioni e transizioni

Cosa fa: gestisce il gruppo motion.

• animation: preset fade-in, slide-up, pop, spin, pulse, shimmer, progress, oppure none. Ogni preset usa i keyframe nc-k-<nome>.
• animationDuration, animationDelay: 0.8s, 800ms o un numero (millisecondi).
• transition: <proprietà> <durata> [easing] [ritardo], più voci separate da virgola. Proprietà all o un nome CSS. Easing ease, linear, ease-in, ease-out, ease-in-out.

Come si usa: chiavi in style dei nodi o delle parti.

Parametri: vedi sopra.

Permessi: nessuno.

Edizione: Free

Limiti noti: un valore non valido non produce dichiarazioni. Le transizioni accettano solo gli easing elencati, non cubic-bezier().

09Hook e filtri

Hook usati dal sistema

Cosa fa: il sistema non definisce filtri o azioni pubblici propri. Usa questi hook di WordPress:

• wp_enqueue_scripts (priorità 9999): applicazione delle regole.
• wp_print_styles, wp_print_footer_scripts (priorità 1): fogli tardivi. wp_print_footer_scripts (priorità 9999): cattura dell'audit.
• script_loader_tag: attributo data-nc-load.
• activated_plugin, deactivated_plugin, nucleo/document_saved (priorità 20): ripubblicazione della tabella.
• nucleo_asset_audit (evento cron): job successivo dell'audit.
• nucleo/pro: decide l'edizione (vedi sotto).

Come si usa: nessun punto di estensione dedicato.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: nessuno rilevato.

10Licenza scaduta

Comportamento senza licenza attiva

Cosa fa: senza licenza l'edizione Pro risulta non attiva. Le ability Pro (nucleo/assets-audit, nucleo/assets-report, nucleo/css-purge, nucleo/css-status, nucleo/css-optimize, nucleo/css-optimize-apply e nucleo/css-optimize-off) non si registrano. La pagina Prestazioni risulta bloccata (edition: pro).

• Sul frontend resta tutto attivo: regole, varianti ridotte, critico e caricamento dei CSS completi continuano a funzionare.
• Le regole predefinite WooCommerce restano, se i file del pacchetto Pro sono installati.
• nucleo/assets-rules-set, nucleo/critical-set e nucleo/critical-request restano disponibili (Free).
• Un audit già pianificato continua a girare in cron: l'audit e la cattura si registrano senza controllo dell'edizione.
• Senza licenza nessuna ability toglie le varianti ridotte: nucleo/css-optimize-off non è registrata e nucleo/assets-rules-set conserva le varianti. Il critico si neutralizza con nucleo/critical-set e css vuoto, perché la stringa vuota vale come critico assente.

Come si usa: nessuna azione.

Parametri: nessuno.

Permessi: nessuno.

Edizione: riguarda il pacchetto Pro senza licenza.

Limiti noti: nel pacchetto Free i file Pro mancano. In quel caso riduzione, audit e ottimizzatore non sono presenti, ma il sito serve comunque le varianti e il critico già pubblicati.