@massimo-cassandro/minimo 1.15.1 → 1.16.1

package/README.md

@@ -12,13 +12,13 @@ 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
 ```
 ---
 

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,9 +6,35 @@ 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** — script for installing minimo environment
+* [starter-kit](#starter-kit) — script for installing minimo environment
 
-## Usage of SVG adn favicons tools
+## starter-kit
+
+`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
+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 `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
+```
+
+## SVG adn favicons tools
 
 ```bash
 ## SVG Icons Tools

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/starter-kit/src/merge-jsonc.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// 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.mjs <template> <destinazione>
+
+import fs from 'fs';
+
+// Analizza un testo JSONC ignorando stringhe e commenti: individua
+// l'oggetto principale, le virgole a profondità 1 e la posizione
+// dell'ultimo carattere significativo (non spazio, non commento)
+function scan(text) {
+  let depth = 0;
+  let open = -1;
+  let close = -1;
+  let last = -1;
+  const commas = [];
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    const next = text[i + 1];
+    if (c === '"') {
+      i++;
+      while (i < text.length && text[i] !== '"') {
+        if (text[i] === '\\') i++;
+        i++;
+      }
+      last = i;
+    } else if (c === '/' && next === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      continue;
+    } else if (c === '/' && next === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i++;
+    } else {
+      if (c === '{' || c === '[') {
+        if (depth === 0 && open === -1 && c === '{') open = i;
+        depth++;
+      } else if (c === '}' || c === ']') {
+        depth--;
+        if (depth === 0 && close === -1) close = i;
+      } else if (c === ',' && depth === 1) {
+        commas.push(i);
+      }
+      if (!/\s/.test(c)) last = i;
+    }
+    i++;
+  }
+  return { open, close, commas, last };
+}
+
+// Posizione della prima doppia virgoletta fuori dai commenti
+function firstQuotePos(text) {
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    const next = text[i + 1];
+    if (c === '/' && next === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+    } else if (c === '/' && next === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i += 2;
+    } else if (c === '"') {
+      return i;
+    } else {
+      i++;
+    }
+  }
+  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 {
+  const tpl = fs.readFileSync(tplPath, 'utf8');
+  const dest = fs.readFileSync(destPath, 'utf8');
+  const t = scan(tpl);
+  const d = scan(dest);
+  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');
+
+  // 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 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 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);
+    renamed.push('\n  ' + cleaned.slice(0, q + 1) + '_' + cleaned.slice(q + 1));
+  }
+  if (renamed.length === 0) process.exit(0);
+
+  // aggiunge le voci prima della chiusura dell'oggetto principale della
+  // destinazione, inserendo una virgola dopo l'ultima voce esistente se serve
+  const dBody = dest.slice(d.open + 1, d.close);
+  const b = scan(dBody);
+  const needsComma = b.last >= 0 && dBody[b.last] !== ',';
+  const insertAt = d.open + 1 + b.last + 1;
+  const out = needsComma
+    ? dest.slice(0, insertAt) + ',' + dest.slice(insertAt, d.close) + renamed.join(',') + '\n' + dest.slice(d.close)
+    : dest.slice(0, d.close) + renamed.join(',') + '\n' + dest.slice(d.close);
+
+  fs.writeFileSync(destPath, out);
+} catch (err) {
+  console.error('merge-jsonc: ' + err.message);
+  process.exit(1);
+}

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

@@ -1,8 +1,20 @@
 #!/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'
+NC='\033[0m' # No Color
+
 # Questo script richiede zsh: se lanciato con sh/bash blocca l'esecuzione
 if [ -z "$ZSH_VERSION" ]; then
-  echo "Errore: lanciare con 'zsh starter-install.sh', non con sh/bash." >&2
+  printf "${RED}Errore: lanciare con 'zsh starter-install.sh', non con sh/bash.${NC}\n" >&2
   exit 1
 fi
 
@@ -19,14 +31,9 @@ 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"
 
-RED='\033[0;31m'
-YELLOW='\033[0;33m'
-GREEN='\033[0;32m'
-NC='\033[0m' # No Color
-
 # protezione contro la sovrascrittura
 set -C
 
@@ -58,7 +65,25 @@ safe_cat() {
 }
 
 echo -e "${GREEN}...package.json${NC}"
-safe_cat "${TEMPLATES_DIR}/package-tpl.json" package.json new
+if [ ! -f package.json ]; then
+  safe_cat "${TEMPLATES_DIR}/package-tpl.json" package.json
+elif [ ! -f "${TEMPLATES_DIR}/package-tpl.json" ]; then
+  echo -e "${RED}Sorgente mancante: ${TEMPLATES_DIR}/package-tpl.json${NC}"
+else
+  # package.json esistente: merge con il template, aggiungendo in fondo
+  # le chiavi del template prefissate con '_' (ordine originale preservato)
+  node -e '
+    const fs = require("fs");
+    const existing = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    const tpl = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+    for (const [key, value] of Object.entries(tpl)) {
+      existing["_" + key] = value;
+    }
+    fs.writeFileSync("package.json", JSON.stringify(existing, null, 2) + "\n");
+  ' "${TEMPLATES_DIR}/package-tpl.json"
+  echo -e "${YELLOW}package.json esistente: chiavi del template aggiunte in fondo con prefisso '_' (da integrare o rimuovere)${NC}"
+  BLOCKED_FILES+=("package.json → merge: chiavi template aggiunte con prefisso \`_\`")
+fi
 
 echo -e "${GREEN}...gitignore${NC}"
 safe_cat "${TEMPLATES_DIR}/_gitignore" .gitignore new
@@ -88,7 +113,29 @@ 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}/__project__.code-workspace" __project__.code-workspace 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 '_'
+WORKSPACE_TPL="${TEMPLATES_DIR}/__project__.code-workspace"
+WORKSPACE_FILES=( *.code-workspace(N) )
+if [ ${#WORKSPACE_FILES[@]} -gt 1 ]; then
+  echo -e "${RED}Trovati più file .code-workspace (${WORKSPACE_FILES[*]}): merge non eseguito${NC}"
+elif [ ${#WORKSPACE_FILES[@]} -eq 0 ]; then
+  safe_cat "$WORKSPACE_TPL" __project__.code-workspace
+elif [ ! -f "$WORKSPACE_TPL" ]; then
+  echo -e "${RED}Sorgente mancante: ${WORKSPACE_TPL}${NC}"
+else
+  WORKSPACE_FILE="${WORKSPACE_FILES[1]}"
+  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
+    echo -e "${RED}Merge di ${WORKSPACE_FILE} non riuscito${NC}"
+  fi
+fi
 
 
 echo -e "\n${GREEN}...eslint${NC}"
@@ -104,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
@@ -126,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
@@ -149,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/{webpack-setup → starter-kit}/templates/package-tpl.json

@@ -32,6 +32,6 @@
     "build tokens": "npx buildTokens --config ./path/to/tokens-config.mjs",
     "check unresolved props": "npx checkUnresolvedProps --config ./path/to/tokens-config.mjs"
   },
-  "dependencies": {},
-  "devDependencies": {}
+  "devDependencies": {},
+  "dependencies": {}
 }

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

package/dev-tools/starter-kit/webpack-modules/purgecss-variables-safelist.mjs

@@ -0,0 +1,92 @@
+// webpack-modules/purgecss-variables-safelist.mjs
+import fs from 'fs';
+import { globSync } from 'glob';
+
+/*
+  Genera l'elenco di custom properties da passare a `safelist.variables` di PurgeCSS.
+  L'elenco viene ricalcolato in memoria a ogni avvio di webpack: nessun file su disco.
+
+  Perché serve: PurgeCSS (`variables: true`) registra l'uso delle variabili solo
+  nelle regole che effettivamente elabora, all'interno del singolo asset css.
+  Restano quindi "invisibili" gli usi di var() che avvengono:
+
+  1. nei blocchi racchiusi tra i commenti `purgecss start/end ignore`
+     (presenti ad es. nei sorgenti di minimo): le regole vengono mantenute,
+     ma le custom properties che consumano verrebbero rimosse dal :root;
+  2. nei css caricati fuori dagli asset purgati (shadow DOM dei web components,
+     import con `?raw`): consumano le props del :root della pagina;
+  3. nelle dichiarazioni di un asset consumate in un altro asset
+     (es. override di tema definiti nel css di una pagina e consumati
+     dal css globale): vanno indicate tramite `seeds`.
+
+  Inoltre `safelist.variables` NON segue le catene di dipendenze (una prop
+  safelisted resta nel css, ma i suoi riferimenti var() non vengono marcati
+  come usati: `--a: var(--b)` in safelist non salva `--b`): l'elenco viene
+  quindi espanso con la chiusura transitiva calcolata sul grafo di tutte le
+  dichiarazioni `--x: ...` presenti nei sorgenti.
+*/
+
+const VAR_REFS_REGEX = /var\(\s*(--[A-Za-z0-9_-]+)/g;
+const DECLARATION_REGEX = /(--[A-Za-z0-9_-]+)\s*:\s*([^;}]+)/g;
+const IGNORE_START_REGEX = /\/\*\s*purgecss start ignore\s*\*\//;
+const IGNORE_END_REGEX = /\/\*\s*purgecss end ignore\s*\*\//;
+
+const varRefs = (cssText) => [...cssText.matchAll(VAR_REFS_REGEX)].map(m => m[1]);
+
+/**
+ * @param {object} params
+ * @param {string[]} params.declarationGlobs glob dei css che contribuiscono al grafo
+ *   delle dipendenze; i loro blocchi `purgecss ignore` contano come usi
+ * @param {string[]} [params.shadowGlobs] glob dei css usati fuori dagli asset purgati
+ *   (shadow DOM / `?raw`): TUTTI i loro usi di var() contano
+ * @param {(string|RegExp)[]} [params.seeds] props da mantenere comunque (nomi o pattern
+ *   risolti sui nomi dichiarati), es. override consumati in un altro asset
+ * @returns {string[]} elenco ordinato di nomi di custom properties
+ */
+export function purgecssVariablesSafelist({ declarationGlobs, shadowGlobs = [], seeds = [] }) {
+
+  const declaredRefs = new Map(); // nome → Set(var() referenziate nelle sue dichiarazioni)
+  const usages = new Set();       // usi da mantenere (blocchi ignore + shadow css)
+
+  for (const file of globSync(declarationGlobs, { nodir: true })) {
+    const src = fs.readFileSync(file, 'utf8');
+
+    // grafo delle dipendenze: ogni dichiarazione `--x: ...` con le var() nel valore
+    for (const declaration of src.matchAll(DECLARATION_REGEX)) {
+      const [, name, value] = declaration;
+      if (!declaredRefs.has(name)) {
+        declaredRefs.set(name, new Set());
+      }
+      varRefs(value).forEach(ref => declaredRefs.get(name).add(ref));
+    }
+
+    // usi di var() nei blocchi `purgecss start/end ignore`
+    src.split(IGNORE_START_REGEX).slice(1).forEach(chunk => {
+      varRefs(chunk.split(IGNORE_END_REGEX)[0]).forEach(ref => usages.add(ref));
+    });
+  }
+
+  // shadow css: ogni uso di var() conta
+  for (const file of globSync(shadowGlobs, { nodir: true })) {
+    varRefs(fs.readFileSync(file, 'utf8')).forEach(ref => usages.add(ref));
+  }
+
+  // risoluzione dei seeds sui nomi dichiarati
+  const declaredNames = [...declaredRefs.keys()];
+  const seedNames = seeds.flatMap(seed =>
+    typeof seed === 'string' ? [seed] : declaredNames.filter(name => seed.test(name))
+  );
+
+  // chiusura transitiva delle dipendenze
+  const result = new Set();
+  const queue = [...seedNames, ...usages];
+  while (queue.length > 0) {
+    const name = queue.pop();
+    if (!result.has(name)) {
+      result.add(name);
+      queue.push(...(declaredRefs.get(name) ?? []));
+    }
+  }
+
+  return [...result].sort();
+}

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

@@ -1,4 +1,4 @@
-// webpack.config.mjs
+// webpack.config.mjs __project_name__
 import path from 'path';
 import { fileURLToPath } from 'url';
 import webpack from 'webpack';
@@ -22,6 +22,7 @@ import { PurgeCSSPlugin } from 'purgecss-webpack-plugin';
 import { globSync } from 'glob';
 
 import { cssRules } from './webpack-modules/css-rules.mjs';
+import { purgecssVariablesSafelist } from './webpack-modules/purgecss-variables-safelist.mjs';
 import { getJsConfigAliases } from './webpack-modules/get-jsConfig-aliases.mjs';
 import { svgRules } from './webpack-modules/svg-rules.mjs';
 
@@ -41,6 +42,7 @@ const isDevelopment = process.env.NODE_ENV === 'development'
   ,favicons_path_regexp = new RegExp(favicons_path) // source pattern per le favicons (regexp o null)
   ,jsConfigAliases = getJsConfigAliases(path.resolve(__dirname, './jsconfig.json'))
   ,packageJson = JSON.parse(fs.readFileSync(path.resolve(__dirname, './package.json'), 'utf-8'))
+  ,purgeCSSDebug = false // true per loggare i selettori rimossi da PurgeCSS a fine build
   // ,manifest_shared_seed = {}
 ;
 
@@ -87,6 +89,111 @@ const CopyWebpackPluginPatterns = [
   // }
 ];
 
+// =>> PurgeCSS: opzioni e istanze (usate nei plugins e dal log di debug)
+//
+// Vengono create DUE istanze, attive in ENTRAMBE le modalità (dev e prod),
+// così i problemi di purge emergono subito durante lo sviluppo:
+// - `purgeCSSPluginCritical`: solo le entry `*.critical` (purge stretto, gli asset
+//   devono essere autosufficienti e minimi perché inlinati nei template html)
+// - `purgeCSSPlugin`: tutti gli asset (il doppio passaggio sui critical è idempotente)
+//
+// NB (watch mode): i template twig NON sono osservati da webpack: dopo aver
+// aggiunto una classe solo in un twig occorre rilanciare la build (o toccare
+// un file js/css) perché il purge venga ricalcolato.
+// NB (dev): il plugin agisce solo sugli asset css emessi; con
+// `inlineCssInDevMode: true` i css non-critical in dev sono iniettati da
+// style-loader e non vengono purgati (i critical passano comunque da
+// MiniCssExtract e sono sempre purgati)
+
+// `paths`: SOLO file che generano markup o classi (html/ejs, twig, php, js);
+// NIENTE file css tra i paths: verrebbero letti come "contenuto" e ogni selettore
+// risulterebbe usato, vanificando il purge
+const purgeCSSCommonOptions = {
+  paths: () => globSync(
+    [
+      path.resolve(__dirname, './src/**/*.{js,mjs,jsx}'),
+      path.resolve(__dirname, './*.ejs'), // template html di webpack
+      path.resolve(__dirname, './src/**/*.ejs'),
+      // progetti symfony: template twig e classi generate lato php
+      // path.resolve(__dirname, '../templates/**/*.twig'),
+      // path.resolve(__dirname, '../src/**/*.php'),
+      // il js di minimo genera markup con classi proprie (snackbar, unsplash-page, ecc.)
+      // NB: adattare il percorso di node_modules se questo config è in una
+      // sottodirectory del progetto (es. frontend/ → '../node_modules/...')
+      path.resolve(__dirname, './node_modules/@massimo-cassandro/minimo/src/**/*.{js,mjs}'),
+    ],
+    { nodir: true }
+  ),
+
+  // extractor di default (/[A-Za-z0-9_-]+/g): adeguato a classi/tag/id,
+  // NON definire extractors custom (il vecchio /[A-z0-9-:/]+/ era buggato:
+  // il range [A-z] include caratteri non voluti come `[`, `\`, `^`, ...)
+
+  variables: true, // rimuove le custom properties non usate (sostituisce postcss-jit-props)
+  keyframes: true, // rimuove i @keyframes non referenziati
+  // fontFace resta false (default): i font sono referenziati solo tramite
+  // var(--font-family) e purgecss non risolve le custom properties nei valori,
+  // quindi con `true` i @font-face verrebbero rimossi anche se usati
+
+  rejected: purgeCSSDebug // popola purgedStats per il log di debug
+};
+
+// safelist base minima, comune alle due istanze
+const purgeCSSSafelistBase = {
+  standard: [
+    // classi costruite dinamicamente nei template o lato server, invisibili
+    // all'analisi statica dei paths. Esempio (da adattare al progetto):
+    // flash messages twig con class="alert alert-{{ label }}"
+    /^alert-(success|notice|error|warning)$/
+  ],
+  deep: [
+    // css modules: prefisso `m_` presente in dev e prod (vedi css-rules.mjs),
+    // le classi hashate non possono comparire nei file scansionati
+    /^m_/
+  ],
+  greedy: [
+    // INDISPENSABILE: purgecss non riconosce il nesting selector nativo e senza
+    // questo pattern i selettori annidati composti solo da `&` + pseudo classi
+    // (&:hover, &:focus-visible, `&` semplice, ecc.) verrebbero SEMPRE rimossi
+    /^&$/
+  ]
+};
+
+// css della pagina critici (inlinati nei template): purge stretto,
+// devono essere autosufficienti e minimi
+const purgeCSSPluginCritical = new PurgeCSSPlugin({
+  ...purgeCSSCommonOptions,
+  only: ['.critical'],
+  safelist: purgeCSSSafelistBase
+});
+
+// tutti gli altri asset (il purge è idempotente: il secondo passaggio
+// sui critical non rimuove altro)
+const purgeCSSPlugin = new PurgeCSSPlugin({
+  ...purgeCSSCommonOptions,
+  safelist: {
+    ...purgeCSSSafelistBase,
+    // elenco generato: usi di var() nei blocchi `purgecss ignore` e nei css
+    // shadow-DOM/`?raw`, override cross-asset (seeds), con chiusura transitiva
+    // delle dipendenze (vedi webpack-modules/purgecss-variables-safelist.mjs)
+    variables: purgecssVariablesSafelist({
+      declarationGlobs: [
+        path.resolve(__dirname, './src/**/*.css'),
+        path.resolve(__dirname, './node_modules/@massimo-cassandro/minimo/src/**/*.css'),
+      ],
+      shadowGlobs: [
+        path.resolve(__dirname, './src/web-components/**/*.css'),
+        path.resolve(__dirname, './node_modules/@massimo-cassandro/minimo/src/web-components/**/*.css'),
+      ],
+      seeds: [
+        // props dichiarate in un asset ma consumate in un altro (es. override
+        // di tema definiti nel css di una pagina e consumati dal css globale):
+        // indicarle qui per nome ('--btn-primary-bg') o pattern (/^--btn-/)
+      ]
+    })
+  }
+});
+
 // recupero metadata immagini
 // const require = createRequire(import.meta.url);
 // responsive-loader adapter (CJS) — use createRequire
@@ -96,8 +203,14 @@ const CopyWebpackPluginPatterns = [
 /** CONFIG **/
 
 // =>> entries
+// NB: percorsi dalla root del progetto
 const entries = {
-  'xxxxxx': './src/index.js' // NB percorso dalla root
+  'xxxxxx': './src/index.js'
+
+  // css critici inlinati nei template html: il suffisso `.critical` nel nome
+  // della entry attiva l'istanza PurgeCSS dedicata con purge stretto
+  // (vedi purgeCSSPluginCritical) e la regola dedicata in css-rules.mjs
+  // ,'xxxxxx.critical': './src/xxxxxx.critical.css'
 };
 
 
@@ -106,7 +219,14 @@ const config = {
 
   // watch: isDevelopment, // necessario se non si usa devServer
   watchOptions: {
-    ignored: [ 'build', '**/node_modules', '.git', '_private' ],
+    ignored: [
+      '**/build/**',
+      '**/_dev/**',
+      '**/.git/**',
+      '**/_private/**',
+      '**/node_modules/**',
+      '!**/node_modules/@massimo-cassandro/**'
+    ],
     // poll: 1000, // se necessario, risolve il problema `Error: EMFILE: too many open files, watch`
   },
 
@@ -153,7 +273,7 @@ const config = {
         extractComments: false
       })
     ],
-    runtimeChunk: true,
+    runtimeChunk: 'single', // true
     splitChunks: {
       cacheGroups: {
 
@@ -172,7 +292,18 @@ const config = {
         },
 
         shared: {
-          test: shared_chunk_paths,
+          // solo moduli js (module.type !== 'css/mini-extract'): il css estratto
+          // resta nel chunk della entry che lo importa, così ogni asset css è
+          // autosufficiente. Necessario per PurgeCSS (`variables: true` funziona
+          // per singolo asset) e per i critical css inlinati nei template
+          //
+          // TODO: se in futuro la duplicazione di css tra le pagine dovesse crescere
+          // (componenti importati dal js di più entry), valutare un cacheGroup `styles`
+          // dedicato ai css condivisi: andranno escluse le entry `.critical` (devono
+          // restare autosufficienti) e gestite in safelist.variables le custom properties
+          // definite/consumate tra asset diversi (vedi purgecss-variables-safelist.mjs)
+          test: (module) => module.type !== 'css/mini-extract'
+            && shared_chunk_paths.test(module.nameForCondition?.() ?? ''),
           // test: /[\\/]node_modules[\\/]/,
 
           // alternativa: non include nel chunk shared i path che contengono la stringa `blurhash`
@@ -281,7 +412,7 @@ const config = {
     //   removeKeyHash: true, // /([a-f0-9]{32}\.?)/gi, // /(\?as_asset)$/,
     //   // rimuove i font dal manifest. Non necessari, rendono il file inutilmente grande
     //   filter: isDevelopment? undefined : (FileDescriptor) => {
-    //     return /_fonts/.test(FileDescriptor.path)? false : true;
+    //     return /fonts/.test(FileDescriptor.path)? false : true;
     //   },
     //   sort: isDevelopment? undefined : (a, b) => a.name.localeCompare(b.name)
     // }),
@@ -368,41 +499,42 @@ const config = {
         );
       },
       raw: true,
-      // exclude: /\.critical/ // chunk name
+      // niente banner nei critical css: vengono inlinati nei template html
+      exclude: /\.critical/ // chunk name
     }),
 
-    // =>> plugins: PurgeCSSPlugin (per ultimo)
+    // =>> plugins: PurgeCSSPlugin (per ultimo, attivo in dev e prod: i problemi
+    // di purge devono emergere subito durante lo sviluppo, non solo in build)
     // https://github.com/FullHuman/purgecss/tree/main/packages/purgecss-webpack-plugin
     // https://purgecss.com/configuration.html
-    // https://github.com/isaacs/node-glob#readme
-    new PurgeCSSPlugin({
-
-      // css da pulire
-      paths: globSync(
-
-        // path.resolve(__dirname, '@minimo/**/!(*.module).css'),
-        path.resolve(__dirname, '@src/**/*.{css,js,ejs}'),
-        //   path.resolve(__dirname, '@src/**/*.js'),
-        //   path.resolve(__dirname, '@app/**/*.ejs'),
-        //   path.join(__dirname, './templates/**/*.twig')
-
-        { nodir: true }
-      ), // .filter(filePath => !filePath.endsWith('.module.css'));
-
-
-
-      variables: false, // Analizza le variabili custom
-      safelist: {
-        standard: ['body', 'html', 'button', 'a'],
-        deep: [/^btn/],
-        greedy: []
-
-      },
-
-      // verbose: true,
-      // rejected: true,
-      // stdout: true
-    })
+    //
+    // NB: il plugin elabora ogni asset css SINGOLARMENTE, quindi con `variables: true`
+    // una custom property viene mantenuta solo se definita e usata nello stesso asset.
+    // Per questo:
+    // - ogni entry css importa direttamente custom-properties.css (che sostituisce
+    //   postcss-jit-props: le props non usate vengono rimosse qui)
+    // - il chunk `shared` contiene solo js (vedi optimization.splitChunks)
+    // - le props dichiarate in un asset ma consumate altrove (override di tema,
+    //   shadow DOM dei web components) sono gestite dalla safelist generata
+    //   (vedi purgecss-variables-safelist.mjs)
+    purgeCSSPluginCritical,
+    purgeCSSPlugin,
+
+    // log dei selettori rimossi (richiede `rejected: true` nei plugin, vedi purgeCSSDebug).
+    // NB: legge `purgedStats` dalle ISTANZE del plugin, non da compilation.purgedStats
+    // (proprietà inesistente: il vecchio log basato su di essa era codice morto)
+    ...(purgeCSSDebug ? [{
+      apply: (compiler) => {
+        compiler.hooks.afterEmit.tap('PurgeCSSLog', () => {
+          /* eslint-disable no-console */
+          console.log('\n--- [PurgeCSS] Selettori rimossi (critical) ---');
+          console.dir(purgeCSSPluginCritical.purgedStats, { depth: null, maxArrayLength: null });
+          console.log('\n--- [PurgeCSS] Selettori rimossi ---');
+          console.dir(purgeCSSPlugin.purgedStats, { depth: null, maxArrayLength: null });
+          /* eslint-enable no-console */
+        });
+      }
+    }] : [])
 
   ], // end plugins
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.15.1",
+  "version": "1.16.1",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",
@@ -24,7 +24,8 @@
     "update-version": "./dev-tools/update-version/index.mjs",
     "upd@m": "./dev-tools/upd@m/index.mjs",
     "svgIconsTools": "./dev-tools/svg-icons-tools/index.mjs",
-    "create-favicons": "./dev-tools/create-favicons/index.mjs"
+    "create-favicons": "./dev-tools/create-favicons/index.mjs",
+    "starter-kit": "./dev-tools/starter-kit/starter-install.sh"
   },
   "repository": {
     "type": "git",