@massimo-cassandro/minimo 1.16.0 → 1.16.2

package/README.md

@@ -12,14 +12,23 @@ npm i -D @massimo-cassandro/eslint-config
 npm i -D @massimo-cassandro/stylelint-config
 ```
 
-> Note: **minimo** is designed to be used with WebPack using the configuration you can find in the [webpack-setup folder](./webpack-setup/) of this repository. If changes are made (for example, to how SVG files are imported), things may not work as expected.
+> Note: **minimo** is designed to be used with WebPack using the configuration you can find in the [starter-kit folder](./dev-tools/starter-kit/) of this repository. If changes are made (for example, to how SVG files are imported), things may not work as expected.
 >
 
-For a complete install of all required webpack modules, use the install script at `./webpack-setup/starter-install.sh` launching:
+For a complete install of all required webpack modules, use the install script at `./dev-tools/starter-kit/starter-install.sh` launching:
 
 ```bash
-zsh ./node_modules/@massimo-cassandro/minimo/webpack-setup/starter-install.sh
+zsh ./node_modules/@massimo-cassandro/minimo/dev-tools/starter-kit/starter-install.sh
 ```
+
+To bootstrap a project **before** installing the whole package, download only the `starter-kit` folder from the npm tarball and run the script from there:
+
+```bash
+curl -sL "$(npm view @massimo-cassandro/minimo dist.tarball)" | tar xz package/dev-tools/starter-kit
+zsh package/dev-tools/starter-kit/starter-install.sh
+rm -rf package
+```
+
 ---
 
 ## Dev Tools

package/design-tokens/_src/typography.minimo.tokens.mjs

@@ -5,7 +5,7 @@ export default {
       $type: 'fontFamily'
     },
     'family-mono': {
-      $value: "'Monaspace Neon Var', 'Monaspace Neon', 'Aptos Mono', 'Roboto Mono', 'SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', 'Liberation Mono', 'Andale Mono', 'Courier New', monospace",
+      $value: '\'Monaspace Neon Var\', \'Monaspace Neon\', \'Aptos Mono\', \'Roboto Mono\', \'SFMono-Regular\', \'Menlo\', \'Monaco\', \'Consolas\', \'Liberation Mono\', \'Andale Mono\', \'Courier New\', monospace',
       $type: 'fontFamily'
     },
 

package/dev-tools/README.md

@@ -6,27 +6,31 @@ A collection of standalone Node.js CLI utilities to help manage a web project's
 * [Svg Icons Tools](./svg-icons-tools/README.md) — optimizes SVG icons and combines/converts them into symbols, JSX, or SCSS variables
 * [Create favicons](./create-favicons/README.md) — generates the full favicon set (SVG, PNG, ICO, webmanifest, HTML snippet) from a source image
 * [upd@m](./upd@m/README.md) — updates all `@massimo-cassandro/*` packages installed in `node_modules`
-* [webpack-setup](#webpack-setup) — script for installing minimo environment
+* [starter-kit](#starter-kit) — script for installing minimo environment
 
-## webpack-setup
+## starter-kit
 
-`webpack-setup/starter-install.sh` bootstraps a new frontend project: it copies the starter config files (`package.json`, `.gitignore`, `jsconfig.json`, eslint/stylelint configs, webpack config and modules, ...) and installs all the required dev dependencies.
+`starter-kit/starter-install.sh` bootstraps a new frontend project: it copies the starter config files (`package.json`, `.gitignore`, `jsconfig.json`, eslint/stylelint configs, webpack config and modules, ...) and installs all the required dev dependencies.
 
 The script **requires zsh** (it exits with an error if launched with `sh` or `bash`). Existing files are never overwritten: root config files are copied with a `NEW-` prefix, while `package.json` and the `*.code-workspace` file are merged (template keys are appended at the end, prefixed with `_`).
 
 ### If minimo is already installed
 
+The script is exposed as a `bin` of the package:
+
 ```bash
-zsh node_modules/@massimo-cassandro/minimo/dev-tools/webpack-setup/starter-install.sh
+npx starter-kit
 ```
 
+Since the installation is fully overwrite-safe, the script can also be **re-run at any time to update** an existing setup (e.g. to refresh the webpack modules or reinstall the dev dependencies): existing files are skipped or copied with the `NEW-` prefix, and the `package.json` / `*.code-workspace` merges are idempotent (running the script again neither duplicates nor overwrites anything).
+
 ### Without installing minimo
 
-To bootstrap a project **before** (or without) installing the whole package, download only the `webpack-setup` folder from the npm tarball and run the script from there:
+To bootstrap a project **before** installing the whole package, download only the `starter-kit` folder from the npm tarball and run the script from there:
 
 ```bash
-curl -sL "$(npm view @massimo-cassandro/minimo dist.tarball)" | tar xz package/dev-tools/webpack-setup
-zsh package/dev-tools/webpack-setup/starter-install.sh
+curl -sL "$(npm view @massimo-cassandro/minimo dist.tarball)" | tar xz package/dev-tools/starter-kit
+zsh package/dev-tools/starter-kit/starter-install.sh
 rm -rf package
 ```
 

package/dev-tools/starter-kit/TODO.md

@@ -0,0 +1,135 @@
+# TODO — Starter kit: config come punto di regia, moduli autonomi
+
+## Obiettivo
+
+`webpack.config.mjs` deve diventare **solo** un punto di impostazione di scelte e
+parametri (in piccolo già lo è: `useSass`, `useSvgo`, `purgeCSSDebug`, ecc.).
+Tutta la logica deve migrare nei moduli di `webpack-modules/`, che devono diventare
+**completamente autonomi e indipendenti dalle impostazioni e dal layout del progetto**:
+in questo modo potranno essere aggiornati/sovrascritti in qualsiasi progetto senza
+danni, perché il timone resta sempre nel config del progetto.
+
+## Contratto dei moduli (da rispettare in ogni intervento)
+
+1. **Nessun percorso di progetto hardcodato** nei moduli: tutti i path (sorgenti,
+   node_modules, template, ecc.) arrivano come parametri dal config.
+2. Ogni modulo esporta **factory pure** (funzioni che ricevono opzioni e
+   restituiscono rules/plugin/config): nessun side effect a import time.
+3. Ogni parametro ha un **default sensato** e JSDoc: il modulo deve funzionare
+   anche senza opzioni, e un'opzione nuova non deve mai rompere un config vecchio.
+4. **Niente dipendenze implicite tra moduli**: se un modulo ha bisogno di un altro
+   (es. css-rules → postcss config), il collegamento avviene via parametro passato
+   dal config, non con import/path interni.
+5. Aggiornare un modulo non deve mai richiedere modifiche al config esistente,
+   se non per adottare volontariamente opzioni nuove.
+6. **Import opzionali = import dinamici**: i pacchetti usati solo quando una
+   scelta li attiva (es. sass-loader con `useSass`, responsive-loader, svgo)
+   non vanno importati staticamente: con la nuova struttura ogni import
+   condizionato da un flag va fatto con `await import(...)` dentro la factory
+   (come già avviene per `svgo.config.mjs` nel config), così un pacchetto non
+   installato non rompe il caricamento del config/modulo se la relativa
+   funzionalità è disattivata.
+
+## Stato attuale (inventario del coupling)
+
+| Modulo | Stato | Problemi |
+|---|---|---|
+| `get-jsConfig-aliases.mjs` | ✅ autonomo | riceve il path del jsconfig dal config |
+| `purgecss-variables-safelist.mjs` | ✅ autonomo | tutti i glob/seeds arrivano dal config |
+| `svgo.config.mjs` | ✅ autonomo | nessun riferimento al progetto |
+| `mini-svg-data-uri-loader.cjs` | ✅ autonomo | loader puro |
+| `svg-rules.mjs` | ⚠️ quasi | parametrico, ma da riverificare rispetto al contratto (default, JSDoc) |
+| `css-rules.mjs` | ⚠️ quasi | parametrico, ma riceve `postcssConfig_path` (file di config esterno invece di opzioni); scelte come `localIdentName` non sovrascrivibili dal config |
+| `postcss.config.mjs` | ❌ accoppiato | **hardcoda** `../src/css/custom-media.css` (layout del progetto): non aggiornabile senza danni |
+| `webpack.config.mjs` | ❌ contiene logica | blocchi che sono logica, non scelte: sezione PurgeCSS (opzioni comuni + 2 istanze + log debug), test del cacheGroup `shared`, rules asset (js/ejs/html/img/font/video/favicon), BannerPlugin |
+
+## Piano d'azione
+
+### 1. Oggetto `settings` unico nel config
+Raggruppare in testa al config un unico oggetto di scelte e percorsi
+(flag attuali + tutti i path oggi sparsi: sorgenti js/css, template twig/php,
+node_modules di minimo, glob shadow-DOM, seeds, favicons, output...).
+Le factory dei moduli ricevono ciò che serve da qui. Il config diventa:
+`settings` → chiamate alle factory → oggetto `config`.
+
+### 2. `postcss.config.mjs` → factory senza path hardcodati
+- Trasformarlo in una factory (es. `postcssPlugins({ globalDataFiles, preserveCustomMedia })`)
+  che riceve i file per `postcss-global-data` dal config.
+- `css-rules.mjs` non riceve più `postcssConfig_path` (file caricato da
+  postcss-loader) ma direttamente l'oggetto `postcssOptions` (o la factory + le sue
+  opzioni) costruito nel config: sparisce l'ultimo path relativo al layout progetto.
+- Attenzione a preservare il comportamento attuale di `loaderContext.mode`.
+- **DA CONTROLLARE E VALUTARE — eliminazione del file postcss config**: verificare
+  la possibilità di eliminare del tutto il file di config postcss e sostituirlo
+  con regole definite direttamente nel webpack config (plugin postcss dichiarati
+  inline in `postcssOptions`). Considerare però che in certi casi postcss
+  necessita di impostazioni ad hoc per progetto (è il motivo per cui oggi esiste
+  il parametro `postcssConfig_path`): in quel caso la strada è mantenere la
+  possibilità di override — es. default inline nel config + parametro opzionale
+  per un file/oggetto di impostazioni custom. Tenere conto anche degli altri
+  consumatori del file: un postcss config a livello di progetto può servire ad
+  altri tool (stylelint, editor/IDE, CLI postcss) oltre che a postcss-loader.
+
+### 3. Sezione PurgeCSS → `webpack-modules/purgecss-plugins.mjs`
+Factory (es. `purgecssPlugins({ contentGlobs, safelist, variablesSafelistOptions, debug })`)
+che incapsula: opzioni comuni, safelist base (deep `m_`, greedy `&`), le due istanze
+(critical + generale) e il mini-plugin di log `purgedStats`.
+Restituisce l'array di plugin pronto per lo spread nel config.
+Nel config restano SOLO: i glob dei contenuti, le safelist specifiche del progetto
+(standard/seeds), il flag `purgeCSSDebug`. I commenti "strutturali" (problemi a/b/c)
+migrano nel modulo; nel config restano i commenti sulle scelte.
+
+### 4. Rules asset generiche → `webpack-modules/asset-rules.mjs`
+Estrarre js/babel, ejs, html, immagini/pdf, font, video, favicons in una factory
+parametrica con on/off per gruppo (es. `assetRules({ favicons_path_regexp, useVideo, ... })`).
+Le parti oggi commentate nel config (responsive-loader, video) diventano opzioni
+documentate del modulo.
+
+### 5. splitChunks
+Valutare una piccola factory (es. `sharedCacheGroup({ pathsRegexp })`) che incapsuli
+l'esclusione dei moduli css (`module.type !== 'css/mini-extract'`, requisito PurgeCSS)
+lasciando nel config solo l'elenco dei path. In alternativa lasciarla nel config ma
+con l'esclusione css delegata a una helper del modulo purgecss (è un suo requisito).
+
+### 6. `starter-install.sh`
+- Aggiornare l'array `FILES` con i nuovi moduli.
+- Distinguere due categorie nel flusso di copia:
+  - `webpack-modules/` = aggiornabili sempre (una volta autonomi, la copia
+    NEW- può diventare sovrascrittura diretta o diff);
+  - `webpack.config.mjs` e template = mai sovrascritti (proprietà del progetto).
+- **Audit delle dipendenze installate**: verificare la corrispondenza tra i
+  pacchetti degli `npm i -D` dello script e quelli effettivamente usati da
+  config, moduli e template, per evitare installazioni inutili. Da controllare
+  in entrambe le direzioni:
+  - installati ma (forse) mai usati: es. `postcss-preset-env` (assente dal
+    postcss config), `responsive-loader` (solo in blocchi commentati),
+    `style-dictionary` (riguarda i design token, non la build webpack);
+  - usati ma non installati: es. `file-loader` (referenziato dalla rule video
+    del config) e `sass-loader`/`sass` (necessari con `useSass: true`).
+  - i pacchetti legati a funzionalità opzionali (sass, responsive-loader,
+    video, svgr...) escono dall'installazione di default: o vengono installati
+    su richiesta dallo script (prompt/flag) o documentati come "da installare
+    quando si attiva l'opzione X" — coerentemente con la regola degli import
+    dinamici del contratto (punto 6).
+
+### 7. Versionamento dei moduli
+Aggiungere in testa a ogni modulo un commento con versione (o data) per capire a
+colpo d'occhio, nei progetti, quale revisione è installata.
+
+### 8. Documentazione
+README dello starter kit con la mappa: cosa si imposta nel config (e solo lì),
+cosa fa ogni modulo, come aggiornare i moduli in un progetto esistente.
+
+## Ordine consigliato
+
+2 → 3 → 4 → 5 (refactor moduli, uno per volta, build demo di verifica dopo ognuno)
+→ 1 (consolidamento `settings`) → 6 → 7 → 8.
+
+## Note
+
+- `merge-jsonc` è già stato spostato in `src/merge-jsonc.mjs` (convertito in ESM):
+  la dir `src/` ospita le utility interne dell'installer, NON copiate nei progetti;
+  `webpack-modules/` resta la dir dei moduli copiati nei progetti.
+- Criterio di "fatto": si deve poter copiare l'intera `webpack-modules/` aggiornata
+  in un progetto esistente senza toccare il suo `webpack.config.mjs` e ottenere
+  una build identica (o migliorata) senza errori.

package/dev-tools/{webpack-setup/merge-jsonc.cjs → starter-kit/src/merge-jsonc.mjs}

@@ -2,9 +2,9 @@
 // Merge JSONC: aggiunge in fondo al file di destinazione le chiavi di primo
 // livello del template, prefissate con '_', preservando commenti e
 // formattazione di entrambi i file.
-// Uso: node merge-jsonc.cjs <template> <destinazione>
+// Uso: node merge-jsonc.mjs <template> <destinazione>
 
-const fs = require('fs');
+import fs from 'fs';
 
 // Analizza un testo JSONC ignorando stringhe e commenti: individua
 // l'oggetto principale, le virgole a profondità 1 e la posizione
@@ -71,6 +71,34 @@ function firstQuotePos(text) {
   return -1;
 }
 
+// Voci di primo livello di un oggetto JSONC (spezzate sulle virgole a profondità 1)
+function topLevelEntries(text, s) {
+  const body = text.slice(s.open + 1, s.close);
+  const offset = s.open + 1;
+  const bounds = s.commas.map((p) => p - offset).concat(body.length);
+  const entries = [];
+  let prev = 0;
+  for (const b of bounds) {
+    entries.push(body.slice(prev, b));
+    prev = b + 1;
+  }
+  return entries;
+}
+
+// Nome della chiave di una voce (contenuto della prima stringa fuori dai commenti)
+function keyName(entry) {
+  const q = firstQuotePos(entry);
+  if (q < 0) return null;
+  let key = '';
+  let i = q + 1;
+  while (i < entry.length && entry[i] !== '"') {
+    if (entry[i] === '\\') i++;
+    key += entry[i];
+    i++;
+  }
+  return key;
+}
+
 const [tplPath, destPath] = process.argv.slice(2);
 
 try {
@@ -81,23 +109,20 @@ try {
   if (t.open < 0 || t.close < 0) throw new Error(tplPath + ': oggetto JSON non trovato');
   if (d.open < 0 || d.close < 0) throw new Error(destPath + ': oggetto JSON non trovato');
 
-  // voci di primo livello del template (spezzate sulle virgole a profondità 1)
-  const body = tpl.slice(t.open + 1, t.close);
-  const offset = t.open + 1;
-  const bounds = t.commas.map((p) => p - offset).concat(body.length);
-  const entries = [];
-  let prev = 0;
-  for (const b of bounds) {
-    entries.push(body.slice(prev, b));
-    prev = b + 1;
-  }
+  // chiavi di primo livello già presenti nella destinazione
+  const destKeys = new Set(
+    topLevelEntries(dest, d).map((entry) => keyName(entry)).filter((k) => k !== null)
+  );
 
-  // prefissa con '_' la chiave di ogni voce (voci di soli commenti/spazi escluse)
+  // prefissa con '_' la chiave di ogni voce del template, saltando le voci di
+  // soli commenti/spazi e le chiavi già presenti nella destinazione
+  // (così rilanciare lo script non produce duplicati)
   const renamed = [];
-  for (const entry of entries) {
+  for (const entry of topLevelEntries(tpl, t)) {
     const cleaned = entry.replace(/^\s+/, '').replace(/\s+$/, '');
+    const key = keyName(cleaned);
+    if (key === null || destKeys.has('_' + key)) continue;
     const q = firstQuotePos(cleaned);
-    if (q < 0) continue;
     renamed.push('\n  ' + cleaned.slice(0, q + 1) + '_' + cleaned.slice(q + 1));
   }
   if (renamed.length === 0) process.exit(0);

package/dev-tools/{webpack-setup → starter-kit}/starter-install.sh

@@ -1,5 +1,12 @@
 #!/bin/zsh
 
+# IMPORTANTE: questo script è idempotente e deve restare tale.
+# Può essere rilanciato più volte sullo stesso progetto (anche via `npx starter-kit`
+# per aggiornare un setup esistente) senza sovrascrivere nulla né creare duplicati:
+# i file esistenti vengono saltati o copiati con prefisso NEW-, i merge di
+# package.json e *.code-workspace non duplicano le chiavi già presenti.
+# Ogni modifica futura deve conservare questa proprietà.
+
 RED='\033[0;31m'
 YELLOW='\033[0;33m'
 GREEN='\033[0;32m'
@@ -24,7 +31,7 @@ BASE_URL=${0:A:h}
 echo "BASE_URL: ${BASE_URL}"
 
 TEMPLATES_DIR="${BASE_URL}/templates"
-# WEBPACK_SOURCE_DIR="$BASE_URL/webpack-setup"
+# WEBPACK_SOURCE_DIR="$BASE_URL/starter-kit"
 WEBPACK_SOURCE_DIR="$BASE_URL"
 
 # protezione contro la sovrascrittura
@@ -106,6 +113,9 @@ safe_cat "${TEMPLATES_DIR}/_browserslistrc"            .browserslistrc new
 safe_cat "${TEMPLATES_DIR}/_editorconfig"              .editorconfig new
 safe_cat "${TEMPLATES_DIR}/_prettierrc"                .prettierrc new
 safe_cat "${TEMPLATES_DIR}/jsconfig.json"              jsconfig.json new
+safe_cat "${TEMPLATES_DIR}/tokens-config.mjs"          tokens-config.mjs new
+safe_cat "${TEMPLATES_DIR}/_root_htaccess"             _root_htaccess
+safe_cat "${TEMPLATES_DIR}/_root_robots.txt"           _root_robots.txt
 
 # code-workspace: se un file .code-workspace esiste già (qualunque sia il nome),
 # le chiavi del template vengono aggiunte in fondo con prefisso '_'
@@ -119,7 +129,7 @@ elif [ ! -f "$WORKSPACE_TPL" ]; then
   echo -e "${RED}Sorgente mancante: ${WORKSPACE_TPL}${NC}"
 else
   WORKSPACE_FILE="${WORKSPACE_FILES[1]}"
-  if node "${BASE_URL}/merge-jsonc.cjs" "$WORKSPACE_TPL" "$WORKSPACE_FILE"; then
+  if node "${BASE_URL}/src/merge-jsonc.mjs" "$WORKSPACE_TPL" "$WORKSPACE_FILE"; then
     echo -e "${YELLOW}${WORKSPACE_FILE} esistente: chiavi del template aggiunte in fondo con prefisso '_' (da integrare o rimuovere)${NC}"
     BLOCKED_FILES+=("${WORKSPACE_FILE} → merge: chiavi template aggiunte con prefisso \`_\`")
   else
@@ -141,7 +151,9 @@ npm i -D webpack-cli webpack-dev-server webpack-manifest-plugin webpack
 npm i -D @babel/core @babel/preset-env babel-loader terser-webpack-plugin
 npm i -D webpack-remove-empty-scripts copy-webpack-plugin html-loader html-webpack-plugin
 npm i -D postcss autoprefixer postcss-custom-media @csstools/postcss-global-data postcss-loader postcss-preset-env
-npm i -D cssnano mini-css-extract-plugin style-loader css-loader css-minimizer-webpack-plugin
+# NB: niente cssnano: la minificazione è di css-minimizer-webpack-plugin e cssnano
+# nel loader postcss eliminerebbe i commenti `purgecss ignore` prima di PurgeCSS
+npm i -D mini-css-extract-plugin style-loader css-loader css-minimizer-webpack-plugin
 npm i -D responsive-loader
 npm i -D process dotenv-webpack
 npm i -D svgo svg-url-loader svgo-loader svgo-add-viewbox mini-svg-data-uri
@@ -163,6 +175,7 @@ FILES=(
   'svg-rules.mjs'
   'svgo.config.mjs'
   'postcss.config.mjs'
+  'purgecss-variables-safelist.mjs'
 )
 
 # se la cartella esiste già, i moduli vengono copiati in NEW-webpack-modules
@@ -186,6 +199,12 @@ mkdir -p "$TEMPLATE_DIR_NAME"
 cd "$TEMPLATE_DIR_NAME"
 mkdir -p error-pages imgs icons src src/css favicons design-tokens
 cd ..
+
+# template delle entry css (globale/di pagina e critical): ogni entry deve
+# importare direttamente custom-properties.css (vedi commenti nei file stessi)
+safe_cat "${TEMPLATES_DIR}/entry-tpl.css"          "${TEMPLATE_DIR_NAME}/src/entry-tpl.css"
+safe_cat "${TEMPLATES_DIR}/entry-tpl.critical.css" "${TEMPLATE_DIR_NAME}/src/entry-tpl.critical.css"
+
 set +C
 
 # Riepilogo finale dei file già esistenti

package/dev-tools/starter-kit/templates/_root_htaccess

@@ -0,0 +1,68 @@
+
+# no cache
+# <IfModule mod_headers.c>
+#   Header set Cache-Control "no-cache, no-store, must-revalidate"
+#   Header set Pragma "no-cache"
+#   Header set Expires 0
+# </IfModule>
+
+# blocco iframe
+# "deny" = tutti siti
+# "sameorigin" tutti tranne quelli che vengono dalla stessa origine
+# https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options
+Header set X-Frame-Options "sameorigin"
+
+<IfModule mod_expires.c>
+  ExpiresActive On
+  AddType application/vnd.ms-fontobject .eot
+  AddType application/x-font-ttf .ttf
+  AddType application/x-font-opentype .otf
+  AddType application/x-font-woff .woff
+  AddType application/x-font-woff2 .woff2
+  AddType application/font-sfnt otf ttf
+  AddType application/font-woff  woff
+  AddType application/font-woff2 woff2
+  AddType image/svg+xml .svg
+
+  ExpiresByType application/vnd.ms-fontobject "access plus 1 year"
+  ExpiresByType application/x-font-ttf "access plus 1 year"
+  ExpiresByType application/x-font-opentype "access plus 1 year"
+  ExpiresByType application/x-font-woff "access plus 1 year"
+  ExpiresByType application/x-font-woff2 "access plus 1 year"
+  ExpiresByType application/font-sfnt "access plus 1 year"
+  ExpiresByType application/font-woff "access plus 1 year"
+  ExpiresByType application/font-woff2 "access plus 1 year"
+
+  ExpiresByType text/html "access plus 1 hour"
+  ExpiresByType text/css "access plus 1 year"
+  ExpiresByType text/x-javascript "access plus 1 year"
+  ExpiresByType application/javascript "access plus 1 year"
+  ExpiresByType application/x-javascript "access plus 1 year"
+
+  ExpiresByType image/svg+xml "access plus 1 year"
+  ExpiresByType image/gif "access plus 1 year"
+  ExpiresByType image/png "access plus 1 year"
+  ExpiresByType image/jpeg "access plus 1 year"
+  ExpiresByType image/pjpeg "access plus 1 year"
+  ExpiresByType image/webp "access plus 1 year"
+  ExpiresByType image/avif "access plus 1 year"
+
+  ExpiresByType application/pdf "access plus 1 year"
+
+  ExpiresByType video/mp4 "access plus 1 year"
+  ExpiresByType video/webm "access plus 1 year"
+  ExpiresByType video/x-m4v "access plus 1 year"
+  ExpiresByType video/quicktime "access plus 1 year"
+  ExpiresByType audio/mpeg "access plus 1 year"
+  ExpiresByType audio/x-wav "access plus 1 year"
+
+  ExpiresByType image/x-icon "access plus 1 year"
+  ExpiresDefault "access plus 1 year"
+</IfModule>
+
+<IfModule !mod_expires.c>
+  <IfModule mod_headers.c>
+    # 1 year
+    Header set Cache-Control 'public, max-age 31536000'
+  </IfModule>
+</IfModule>

package/dev-tools/starter-kit/templates/_root_robots.txt

@@ -0,0 +1,5 @@
+User-agent: *
+# Allow: /
+Disallow: /
+
+# Sitemap: https://www.example.com/sitemap.xml

package/dev-tools/starter-kit/templates/entry-tpl.critical.css

@@ -0,0 +1,18 @@
+/*
+  Template di entry css critical — rinominare e adattare.
+
+  Le entry con suffisso `.critical` generano asset destinati a essere
+  INLINATI nei template html: devono restare AUTOSUFFICIENTI e minimi.
+  Il suffisso attiva l'istanza PurgeCSS dedicata con purge stretto, in dev
+  e in prod (vedi purgeCSSPluginCritical in webpack.config.mjs), e la regola
+  dedicata in css-rules.mjs.
+
+  Anche qui va importato direttamente custom-properties.css: PurgeCSS
+  elabora gli asset singolarmente e mantiene in questo asset solo le
+  custom properties usate in questo file, quindi l'asset resta minimo
+  senza dipendere dal css globale della pagina.
+*/
+
+@import '@css/custom-properties.css';
+
+/* stili above-the-fold della pagina (layout iniziale, spinner, ecc.) */

package/dev-tools/starter-kit/templates/entry-tpl.css

@@ -0,0 +1,24 @@
+/*
+  Template di entry css (globale o di pagina) — rinominare e adattare.
+
+  NB: OGNI entry css (globale, di pagina, `.critical`) deve importare
+  direttamente custom-properties.css: PurgeCSS elabora gli asset css
+  SINGOLARMENTE e mantiene in ciascuno solo le custom properties
+  effettivamente usate nell'asset stesso (`variables: true`, che
+  sostituisce postcss-jit-props). L'import diretto non produce quindi
+  duplicazioni nel css finale.
+*/
+
+@import '@css/custom-properties.css';
+/* @import '@css/fonts.css'; */
+
+/* @import '@css/custom-media.css'; */ /* NON necessario: iniettato da postcss-global-data */
+
+/* moduli minimo: importare solo quelli effettivamente usati */
+/* @import '@minimo/css/reset.css'; */
+/* @import '@minimo/css/layout-base.css'; */
+/* @import '@minimo/css/container.css'; */
+/* @import '@minimo/css/forms/forms.css'; */
+/* @import '@minimo/css/buttons/buttons.css'; */
+/* @import '@minimo/css/alerts.css'; */
+/* ... */

package/dev-tools/starter-kit/templates/tokens-config.mjs

@@ -0,0 +1,33 @@
+
+// import path from 'path';
+
+// path relativi a questo file
+
+const config = {
+  // build tokens
+  stylelintConfigPath: '../../stylelint.config.mjs',
+  buildPath: '../src/css',
+  destFile: 'custom-properties.css',
+  source: [
+    '../../node_modules/@massimo-cassandro/minimo/design-tokens/_src/**/*.tokens.{mjs,jsonc}',
+    './figma-tokens-OK/*.{jsonc,mjs}',
+  ],
+
+  colorScalePrefixes: ['primary', 'secondary', 'neutral'],
+
+  penpotFormat: 'jsonc',
+  penpotBuildPath: null,
+  penpotDestFile: null,
+  penpotExpressions: 'resolve',
+
+  // ---------------------------------------------------------------------------
+  // check-unresolved-custom-props.mjs settings
+  // ---------------------------------------------------------------------------
+  extra_custom_props_files: [],
+  dir_to_check: '../src', // percorso della dir che include i css da analizzare
+  exclude_pattern: [ // patterns per l'esclusione dal controllo unresolved-props
+    /^--_/,
+  ]
+};
+
+export default config;

package/dev-tools/{webpack-setup → starter-kit}/webpack-modules/css-rules.mjs

@@ -146,7 +146,12 @@ function css_loaders({
         modules: css_modules
           ? {
             auto: true,
-            localIdentName: isDevelopment ? '[local]_[hash:base64:6]' : '[hash:base64:10]',
+            // il prefisso fisso `m_`, presente in ENTRAMBE le modalità, consente
+            // il safelist delle classi dei css modules in PurgeCSS (safelist.deep
+            // [/^m_/], vedi webpack.config.mjs): le classi hashate non possono
+            // comparire nei file di contenuto scansionati, e il purge è attivo
+            // anche in dev
+            localIdentName: isDevelopment ? 'm_[local]_[hash:base64:6]' : 'm_[hash:base64:8]',
             exportLocalsConvention: 'as-is',
 
             // namedExport: false,

package/dev-tools/{webpack-setup → starter-kit}/webpack-modules/postcss.config.mjs

@@ -4,40 +4,34 @@ import { fileURLToPath } from 'url';
 import globalData from '@csstools/postcss-global-data';
 import customMedia from 'postcss-custom-media';
 import autoprefixer from 'autoprefixer';
-import cssnano from 'cssnano';
-import jitProps from 'postcss-jit-props';
-// import openProps from './modulo_cjs.cjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// NB: le custom properties NON sono gestite qui (postcss-jit-props rimosso):
+// ogni entry css importa direttamente custom-properties.css e le props
+// non utilizzate vengono rimosse in build da PurgeCSS (`variables: true`,
+// vedi webpack.config.mjs)
+
+// NB: la minificazione è gestita da CssMinimizerPlugin (webpack.config.mjs):
+// cssnano NON va aggiunto qui, oltre a duplicare la minificazione
+// rimuoverebbe i commenti speciali `/* purgecss start/end ignore */`
+// prima dell'esecuzione di PurgeCSS
+
 export default (loaderContext) => {
   const isDevelopment = loaderContext.mode === 'development';
 
   const plugins = [
+    // rende disponibili le @custom-media a tutti i file css
+    // (il contenuto iniettato viene rimosso a fine elaborazione;
+    // NON aggiungere qui custom-properties.css: duplicherebbe le props
+    // in ogni asset e interferirebbe con il purge, vedi sopra)
     globalData({
       files: [
-        // openProps.
-        path.resolve(__dirname, '../src/css/custom-properties.css'),
         path.resolve(__dirname, '../src/css/custom-media.css'),
       ]
     }),
 
-    // https://github.com/GoogleChromeLabs/postcss-jit-props
-    // https://github.com/argyleink/open-props
-    // require('postcss-jit-props')(require('open-props')),
-    // require('postcss-jit-props')({
-    //   ...require('open-props'),
-    //   custom_selector: ':where(html)'
-    // }),
-    jitProps({
-      files: [
-        // ...openProps,
-        path.resolve(__dirname, '../src/css/custom-properties.css')
-      ],
-      custom_selector: ':where(html)'
-    }),
-
     // per IOS < 17 (test)
     // https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting
     // https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-light-dark-function#readme
@@ -47,7 +41,6 @@ export default (loaderContext) => {
     //}),
     // require('@csstools/postcss-light-dark-function')({preserve: false}), /* NB non funziona benissimo... */
 
-
     // https://github.com/csstools/postcss-plugins/
 
     customMedia({
@@ -58,19 +51,6 @@ export default (loaderContext) => {
     autoprefixer(),
   ];
 
-  if (!isDevelopment) {
-    // per IOS < 17
-    // require('postcss-nesting')({
-    //  edition: '2021',
-    //  noIsPseudoSelector: true
-    //}),
-    // require('@csstools/postcss-light-dark-function'), /* NB non funziona benissimo... */
-
-
-    plugins.push(cssnano({ preset: 'default' }));
-  }
-
-
   return {
     plugins: plugins
   };