---
name: mcp-grid-ui-debugger
description: >
  Diagnose and fix recurring rendering, scroll, flicker, drag, virtualization, and first-load layout bugs in complex data grids through live DOM inspection and iterative screenshot comparison. Use for grid geometry, scrollbar/footer, first-render, or virtualized-drag symptoms across DevExpress, AG Grid, MUI, Kendo/Telerik, and similar libraries. Treat DevExpress/Blazor steps as optional stack-specific examples. Use mcp-frontend-performance-debugger for systemic slowness, long tasks, render/DOM churn, listener leaks, or trace-driven profiling; use mcp-browser-automation for generic E2E flows.
---

# MCP Grid UI Debugger

Skill specialistico per diagnosticare e risolvere bug ricorrenti di rendering, scroll, flicker, drag e layout al primo caricamento in componenti data-grid complessi o virtualizzati. Nasce da quattro sessioni di sviluppo indipendenti sul progetto interno "SuperPlanning" (componente grid "TesiGrid", stack Blazor+DevExpress) che hanno individuato lo stesso pattern di anomalie visive non ancora risolto strutturalmente: glitch di rendering al primo caricamento, flicker della summary/footer, scrollbar che esce dal limite, drag rotto su griglie virtualizzate. Il pattern è stato osservato ripetutamente sia in sessioni Claude Code sia in sessioni Codex CLI sullo stesso sistema, segnale forte di ripetibilità strutturale.

**Ambito di validità — leggi prima di applicare su uno stack diverso.** La metodologia diagnostica (screenshot baseline, ispezione DOM live, ipotesi timing/stile, verifica con reload pulito, documentazione dei tentativi) è generica e si applica a qualunque libreria grid complessa o virtualizzata (DevExpress, AG Grid, MUI DataGrid, Kendo/Telerik, react-window, ecc.): i concetti usati (bounding rect, computed style, overflow, virtualizzazione, transform) sono standard del DOM/CSS, non specifici di un vendor. **L'evidenza reale che ha originato questa skill è però solo DevExpress+Blazor.** Su uno stack diverso: applica la metodologia cosi' com'e', ma tratta come "esempio da adattare, non requisito" i passaggi esplicitamente legati a Blazor/DevExpress (rebuild obbligatorio, API `DXGrid`/`GetGridInstance` in `references/dom-inspection-checklist.md` sezione D) — su stack con hot-reload reale (tipicamente React/Vue/Svelte con Vite/webpack dev server) il passaggio di rebuild esplicito potrebbe non servire, ma la regola di **non fidarsi del solo hot-reload per dichiarare un fix verificato** resta valida ovunque.

## Quick Routing

Usa questa skill quando serve:

- diagnosticare e risolvere un bug visivo su una griglia complessa/proprietaria al primo caricamento o su reload;
- correggere glitch di scroll, flicker di summary/footer, comportamenti anomali della scrollbar su una griglia con virtualizzazione o 100+ righe;
- risolvere malfunzionamenti di drag-and-drop su componenti griglia virtualizzate;
- iterare su uno stesso sintomo visivo che ricorre nella stessa griglia tra sessioni di sviluppo diverse (trattenersi bug), per capire se è una race condition di timing, un conflitto di stile, o un'anomalia di stato del componente;
- documentare il percorso diagnostico e i tentativi di fix per garantire continuità tra sessioni future.

Non usarla per:

- scrivere test E2E generici o validazione di flow (→ `mcp-browser-automation`);
- correzioni cosmetiche CSS isolate non correlate a un glitch/symptom specifico di una griglia;
- bug backend/API senza manifestazione visiva UI (→ `mcp-technical-analyst` o `mcp-database-expert`);
- correzioni CSS "una tantum" su elementiUI non virtualizzati o non legati a rendering/scroll di griglia.

## Regole Permanenti

1. **Non dichiarare un fix verificato basandosi solo su hot-reload o screenshot singolo.** Testare sempre un reload pulito (full page reload, non hot-refresh) della pagina, e se applicabile, con dataset di dimensione realistica (100+ righe). Il sintomo deve scomparire in modo stabile al reload, non solo in transizioni hot-reload che nascondono race condition.

2. **Se lo stack richiede un rebuild esplicito per applicare la modifica (tipico di Blazor e stack compilati, meno comune su dev server JS con hot-reload reale come Vite/webpack), chiedilo sempre prima di verificare il fix.** Non assumere mai che la modifica sia stata applicata senza conferma esplicita dell'utente; su stack che invece supportano hot-reload affidabile, questo passaggio puo' essere superfluo — ma la verifica con reload pulito (regola 1) resta comunque obbligatoria in entrambi i casi.

3. **Preferisci ipotesi di timing/race condition o conflitto di stile prima di ipotesi di refactorizzazione strutturale.** La maggior parte di questi bug sono: *timing* (il componente monta prima che CSS/dati siano pronti) oppure *conflitti di stile* (z-index, overflow, calcoli di dimensione errati su elementi virtualizzati). Verifica queste due categorie prima di suggerire riscritture di logica di virtualizzazione o cambio di libreria.

4. **Aggiorna sempre il documento di "genesi e tentativi" del componente, anche se il fix sembra banale.** Il valore è nella continuità tra sessioni: ogni tentativo fallito, ogni ipotesi verificata, ogni lezione imparata va registrata nel documento storico del componente. Questo evita di ripetere gli stessi tentativi e accelera la risoluzione al ricorrere del bug.

## Workflow Operativo

### 1. Riproduci il sintomo

Naviga alla pagina/vista che contiene la griglia, con un dataset che riproduce le condizioni del bug. Se il sintomo è legato a virtualizzazione (lag su drag, layout instabile), assicurati che il dataset sia di dimensione realistica (100+ righe). Se il sintomo è "glitch al primo caricamento", naviga alla pagina da freddo (primo load dopo un reload completo della pagina o avvio dell'app).

### 2. Cattura una baseline visiva

Scatta uno screenshot iniziale che mostra il sintomo, prima di ogni modifica. Descrivi il sintomo osservato: posizione dell'anomalia, colore/visibilità, comportamento (scompare dopo N secondi? è coerente? varia col dataset?). Questa baseline sarà il punto di confronto per tutte le verifiche successive.

### 3. Ispeziona il DOM live

Usa gli strumenti disponibili nel browser dell'host (valutazione JS nella pagina, strumenti di sviluppo, console) per leggere lo stato reale del componente **al momento in cui il sintomo è visibile**, non solo l'aspetto visivo. Raccogli:

- **Bounding rect** di elementi chiave (griglia, scrollbar, summary/footer) tramite `element.getBoundingClientRect()`;
- **Computed style** di proprietà CSS critiche (overflow, position, z-index, display, width/height, transform) tramite `getComputedStyle(element)`;
- **Classi CSS applicate** al componente e ai suoi figli (es. `.grid-virtualized`, `.row-container`, stato di hover/selection);
- **Stato del componente griglia** se esposto (es. `grid.isInitialized()`, `grid.selectedRows`, proprietà di virtualizzazione se disponibili);
- **Timeline di mount vs disponibilità dati**: il componente monta prima che i dati siano stati ricevuti? C'è un flag di loading che potrebbe influenzare il layout iniziale?

### 4. Formula un'ipotesi mirata

Sulla base dell'ispezione DOM e della baseline visiva, formula un'ipotesi. La maggior parte di questi bug appartiene a due categorie:

- **Race condition di timing**: il componente monta/renderizza prima che CSS/dati/dimensioni siano pronti, causando un layout iniziale errato che si ripercuote su scroll/virtualizzazione successivi.
- **Conflitto di stile**: z-index di overlay/scrollbar in conflitto, overflow non impostato correttamente su container virtualizzati, calcoli di dimensione errati su righe virtualizzate (altezza fissa vs dinamica), transform/translate applicati a elementi che dovrebbero essere static.

Se non ricadi in una di queste due, raccogli ulteriori evidenze (log di browser console, timing di rete se applicabile) prima di ipotizzare anomalie di logica.

### 5. Applica una modifica mirata e chiedi conferma di rebuild

Applica una modifica circoscritta al componente/sintomo (CSS o JS), **non refactorizzare** la struttura più ampia. Esempi: aggiungere `will-change`, fissare l'altezza del container virtualizzato, aggiungere `z-index` esplicito a scrollbar, aggiungere un delay di mount/render tramite callback di lifecycle.

**Chiedi sempre conferma esplicita per un rebuild** se il progetto lo richiede (Blazor, compilazione): "Ho applicato [modifica]; il progetto richiede un rebuild per vederne gli effetti. Puoi eseguire [comando rebuild] e farmi sapere quando è pronto?"

### 6. Riverifica con reload pulito

Dopo la modifica (e dopo il rebuild, se richiesto), esegui un reload completo della pagina (Ctrl+R, non hot-refresh), naviga di nuovo alla pagina della griglia, ricatta uno screenshot. Ispeziona il DOM con gli stessi passi del punto 3, confronta con la baseline. Il sintomo deve scomparire in modo stabile, non essere semplicemente meno visibile.

### 7. Itera finché la stabilità è confermata

Ripeti i passi 4-6 per ogni ipotesi e modifica, fino a quando il sintomo non scompare stabilmente al reload completo, con dataset di dimensione realistica (100+ righe, se applicabile). Se il bug ricorre durante l'iterazione, torna al passo 3 (ispezione DOM live) e raccogli ulteriori evidenze.

### 8. Documenta genesi e tentativi

Crea o aggiorna il documento di "genesi e tentativi" per il componente griglia (es. "TesiGrid_genesis_attempts.md"). Registra:

- **Sintomo osservato**: descrizione precisa con contesto (primo load? su drag? con dataset di N righe?);
- **Root cause ipotizzato**: categoria di timing/conflitto di stile/altro, con evidenze dal DOM (bounding rect, computed style, stato componente);
- **Tentativi e risultati**: lista di modifiche applicate, esito di ogni tentativo (risolto? peggiorato? senza effetto?), motivo del fallimento se applicabile;
- **Fix definitivo**: modifica finale che ha risolto il sintomo, con spiegazione tecnica di perché funziona;
- **Regressione da verificare**: se rilevante, descrivi un test manuale veloce o punti di attenzione per sessioni future.

Questo documento sarà il riferimento quando il bug ricorre nelle sessioni successive.

## Sinergie

- con **`mcp-browser-automation`**: una volta che il fix è stabilizzato, scrivi un test di regressione Playwright che catturi il sintomo e verifichi che il fix sia duraturo. Questa skill diagnostica e itera sul sintomo singolo, l'altra valida in modo strutturato e ripetibile su suite più ampia.

- con **`mcp-frontend-performance-debugger`**: quando il problema non è solo geometrico ma include long task, render/interop ripetuto, DOM churn o leak. Mantieni qui la diagnosi visuale della grid e demanda all'altra skill profiling, budget e soak.

- con **`mcp-docs-navigator`**: organizza e indicizza il documento di "genesi e tentativi" nel corpus documentale aziendale, taggando per dominio (grid, rendering, virtualizzazione) e per componente (es. TesiGrid). Consente ricerca storica e continuità tra sessioni.

## References

- [references/symptom-patterns.md](references/symptom-patterns.md)
- [references/dom-inspection-checklist.md](references/dom-inspection-checklist.md)