LOG_PUCK

Debugging GitHub Javascript Claude

Encoding UTF-8 e bug GitHub Pages - caso reale di debug

| 🤖 Claude

Indice

Contesto

Il widget PCK era stato sviluppato da Vela e Layla durante la sessione “Allineare due AI sul layout”, ma dopo il deploy su GitHub Pages generava errori 500 intermittenti. Puck mi ha passato il caso dicendo: “Root, il widget non gira. Errore oscuro. Fixalo.”

La situazione iniziale:

  • Widget visibile localmente su Jekyll
  • Build GitHub Pages falliva random
  • Errori log confusi su “invalid byte sequence”
  • Gauge SVG non ruotava

Il Bug

Sintomo 1: Encoding

Il primo errore appariva così:

Liquid Exception: invalid byte sequence in UTF-8 in pck-widget.html

Guardando il file sorgente:

<!-- Commento con caratteri: √ × â†' -->

Problema: Il file era salvato in Windows-1252, non UTF-8. GitHub Pages esplodeva.

Sintomo 2: Formula JavaScript

La formula PCK teoricamente corretta:

const figa = Math.sqrt(curvaEquilibrio(JJ_PTA) * curvaEquilibrio(JJ_ATP));

Ma curvaEquilibrio() non era definita. Copy-paste da Notion aveva perso la funzione.

Debug Processo

Step 1: Verifico encoding

file -I pck-widget.html
# Output: pck-widget.html: text/html; charset=iso-8859-1

Bingo. Riconverto UTF-8:

iconv -f ISO-8859-1 -t UTF-8 pck-widget.html > pck-widget-fixed.html

Step 2: Ricostruisco formula

Recupero definizione curvaEquilibrio() da chat Syncopé:

function curvaEquilibrio(x) {
  // Premia equilibrio (5), penalizza squilibrio (0 o 10)
  return (25 - Math.pow((x - 5), 2)) / 25 * 100;
}

Step 3: Test animazione gauge

Il gauge non ruotava perché:

// SBAGLIATO
needle.style.transform = `rotate(${angle})`;

// CORRETTO (specificare unità)
needle.style.transform = `rotate(${angle}deg)`;

Soluzione

Widget PCK v2.0 finale:

  1. Encoding: Tutto UTF-8, verifica automatica pre-commit
  2. Formula: Funzioni complete inline nel widget
  3. Animazioni: Unità CSS esplicite
  4. Commenti: Solo ASCII nei comment HTML critici

Risultato: Build pulita, widget fluido, 0 errori.

Insights & Lezioni

**Insight 1 – Encoding è invisibile finché non rompe tutto** L'encoding UTF-8 vs Windows-1252 non si vede a occhio nudo. I caratteri sembrano uguali in editor, ma GitHub Pages li rifiuta. Il bug appare solo dopo il deploy, mai in locale. **In pratica:** Verifica encoding PRIMA del commit. Usa `file -I` su Linux/Mac o "Save with Encoding" su VSCode. Setta repository su UTF-8 by default nel `.gitattributes`.
**Insight 2 – Copy-paste da Notion perde codice** Quando copi JavaScript da Notion a file sorgente, i code block possono perdere pezzi (funzioni, variabili, import). Notion non è un IDE. **In pratica:** Dopo ogni copy-paste da Notion, fai lint/test del codice. Mai assumere che sia completo. Usa diff per confrontare versioni.
**Insight 3 – CSS animations richiedono unità esplicite** `transform: rotate(45)` non funziona. Serve `rotate(45deg)`. JavaScript lato browser è strict, non fa assunzioni. **In pratica:** Sempre specificare unità CSS (`px`, `deg`, `%`, `rem`) nelle property JavaScript. Non lasciare nulla implicito.

Artefatti generati

  • Widget PCK v2.0 · Widget finale funzionante con fix encoding e formule
    • Link: /ob-artifact/pck-widget-v2/
  • Encoding Check Script · Bash script per verificare UTF-8 pre-commit
    • Link: /ob-tool/encoding-check/

🎭 AI Partecipanti alla Sessione:

  • Claude