Add full shell, replaceable Omics adapter and bilingual interaction

Implement approved specification #32 and tickets #33-#37. Keep host authentication server-verified and pin session interaction language. Compile scoped base selectors for browser compatibility and retain full gutters during CSS pruning.

docs/reports/2026-09-13-shell-simplification-review.md

@@ -0,0 +1,195 @@
+# Revisione della semplificazione della shell
+
+Data: 2026-09-13. Oggetto: piano full/embedded, ADR 0021–0022 e contratto
+Portal Shell Adapter v1. Questa è una revisione con raccomandazioni: non modifica il
+codice applicativo né sostituisce automaticamente i contratti accettati.
+
+## Valutazione
+
+La separazione tra shell, autenticazione e lingua delle sessioni è corretta. La
+semplificazione precedente ha però mantenuto un protocollo di comunicazione non
+necessario per il montaggio corrente e ha lasciato ambigue alcune condizioni di
+compatibilità. Raccomando un adapter che osservi il documento già condiviso con
+Omics, riutilizzi l'autenticazione esistente e non imponga un nuovo bridge al portale.
+
+La revisione considera il sorgente locale di ThothII e Omics Portal al commit
+`aff7581`, già ottenuto con il pull richiesto. Non certifica quali immagini,
+configurazioni o modifiche siano attualmente attive sul server.
+
+## Problemi individuati e correzioni raccomandate
+
+### 1. Il cambio lingua senza ricaricamento non corrisponde a Omics
+
+In `templates/partials/topbar.html:74–87`, Omics usa il form Django `set_language`
+con `onchange="this.form.submit()"`. La lingua cambia attraverso una nuova pagina
+renderizzata dal server. Il criterio 2 del contratto v1 promette invece aggiornamenti
+senza ricaricamento per tutte le preferenze.
+
+Raccomandazione: rispettare il comportamento del portale. In full, lingua e tema
+cambiano immediatamente. In embedded, il tema cambia immediatamente e la lingua
+segue il normale ricaricamento Omics. Evitare di intercettare il form per cambiare
+solo ThothII: lascerebbe header, sidebar e testi Django nella lingua precedente.
+
+Il ricaricamento va verificato durante una sessione attiva e con modifiche non
+salvate: deve essere possibile ritrovare la sessione senza avviare una nuova
+generazione; eventuali bozze richiedono una protezione dalla navigazione. Lo stato
+persistito del workflow non equivale alla conservazione automatica della bozza UI
+o del flusso di messaggi in memoria. Questa verifica è necessaria anche mantenendo
+il protocollo a eventi del piano precedente.
+
+### 2. Un protocollo ready/state non è necessario nello stesso documento
+
+`templates/kokoro/datamart_builder.html` monta React in `#root`, nello stesso
+documento dell'header. L'adapter può ottenere direttamente:
+
+- lingua effettivamente renderizzata: `data-lang` del selettore
+  `.omics-language-select`;
+- tema: attributo `data-bs-theme` sull'elemento `html`;
+- fullscreen: stato del documento e relativo evento del browser.
+
+Un'osservazione limitata all'attributo del tema e un listener del fullscreen
+coprono gli aggiornamenti attuali. La lingua viene riletta quando Django restituisce
+la pagina. Questi selettori e dettagli devono comparire soltanto dentro
+`OmicsPortalAdapter`, con test basati sul template reale.
+
+Attenzione: `templates/base.html:3` contiene oggi `lang="en"` fisso; quell'attributo
+non è una fonte attendibile per la lingua Omics. Se in futuro il portale espone la
+lingua su un attributo dedicato del punto di montaggio, si modifica soltanto l'adapter.
+
+La proposta elimina due eventi personalizzati, la versione del protocollo, il
+timeout di avvio e il rischio che il messaggio iniziale parta prima del listener.
+L'osservazione va installata prima di consegnare lo snapshot iniziale; la funzione
+di disiscrizione rimuove tutte le risorse. L'assenza dei dati Omics attesi produce
+un errore di integrazione comprensibile, senza attivare la shell full.
+
+Il costo accettato è una dipendenza esplicita dal piccolo contratto DOM Omics,
+confinata nell'adapter. Un secondo portale potrà fornire gli stessi dati usando
+un'altra implementazione, anche con un diverso trasporto. Non occorre costruirla ora.
+
+### 3. `authenticated` duplica uno stato che il server già verifica
+
+`kokoro/datamart_catalog_views.py:49` e `nginx/nginx.conf:69` verificano l'accesso
+Omics e trasmettono al backend identità e autorizzazioni normalizzate. ThothII
+ottiene già l'utente tramite `/me`. Non serve un ulteriore login né un flag nel
+documento che dichiari l'utente autenticato.
+
+Il logout Omics attuale è una navigazione (`topbar.html:118`), non un evento di
+revoca. Un click sul link non prova che il logout sia stato completato; inoltre,
+un flag inviato una volta non rileva la scadenza della sessione o un logout in
+un'altra scheda.
+
+Raccomandazione: togliere `authenticated` dallo snapshot visivo. La verifica
+dell'accesso rimane nel percorso di autenticazione esistente. In embedded,
+perdita dell'accesso significa chiudere i dati protetti e demandare il rientro
+al portale, senza mostrare il form di login ThothII.
+
+Serve verificare la gestione dei rifiuti Omics: l'endpoint di autorizzazione
+restituisce attualmente 403 anche quando l'accesso non è disponibile, mentre
+`frontend/src/api/client.ts` pulisce automaticamente lo stato su 401. Un 403
+ordinario può anche significare che manca il permesso per una sola operazione;
+non va trasformato indiscriminatamente in logout. La verifica `/me` deve
+distinguere la perdita di accesso all'applicazione dal rifiuto di una sua funzione.
+
+`frontend/src/stream/useSessionStream.ts` esegue già un controllo di autenticazione
+quando il collegamento eventi fallisce: riutilizzare quel percorso. Non promettere
+revoca istantanea di una connessione già aperta in un'altra scheda sulla sola base
+di `auth_request` o di un evento nella pagina corrente. Il contratto deve dichiarare
+quando l'accesso viene ricontrollato e verificare anche il ritorno a una scheda
+rimasta aperta.
+
+In full sul Mac resta il login locale esistente. Il logout backend esiste già
+(`backend/src/auth/routes.ts:355`): il lavoro riguarda il collegamento all'header
+e la pulizia della UI. Per installazioni full con OIDC va consentito anche quel
+logout; oggi `AuthGate` lo espone soltanto per `mode === "local"`. La revoca della
+sessione ThothII non va descritta come logout globale dal fornitore d'identità.
+
+### 4. Il default embedded contraddice l'adapter obbligatorio
+
+Il piano dichiara compatibilità con descrittori senza `shell`, ma il contratto
+richiede `adapter` in embedded. Inoltre, pretendere un nuovo bridge renderebbe
+inutilizzabile la vecchia pagina Omics finché non fosse aggiornata.
+
+Raccomandazione: risolvere i valori in un unico punto di configurazione:
+
+- assenza di `shell`: embedded con adapter Omics predefinito;
+- embedded senza `adapter`: `omics-portal`;
+- full: nessun adapter istanziato;
+- nome adapter sconosciuto: errore esplicito di configurazione.
+
+L'adapter che legge lo stato già esistente rende questa compatibilità concreta.
+Sul Mac rimangono espliciti `mode: full` e `defaultLocale: en`. La proiezione
+pubblica può usare il `config.js` già presente; non serve un nuovo servizio di
+configurazione. Va verificato anche il prefisso API `/datamart-builder/api` nel
+montaggio Omics: il default frontend `/api` non basta a dimostrare che il deploy
+funzioni. Prima si aggiorna il lettore del descrittore, poi il file installato,
+poiché il lettore corrente rifiuta chiavi sconosciute.
+
+### 5. Fullscreen e dark mode hanno già elementi riutilizzabili
+
+ThothII possiede già token scuri in `frontend/src/index.css:67`, attivati anche da
+`data-bs-theme="dark"`. Il lavoro è completarne la copertura e verificare contrasto,
+form, menu e finestre, riutilizzando questi token.
+
+Omics cambia la classe `fullscreen-enable` al click (`static/js/app.js:702`)
+prima di conoscere il risultato. Il ramo di uscita usa metodi storici e non
+contiene `document.exitFullscreen()`. Non va copiato nella shell full: l'icona
+deve seguire lo stato effettivo, compresi Esc e richieste rifiutate. La correzione
+equivalente dell'header Omics appartiene al suo modulo UI, non a un secondo
+controllo fullscreen dentro ThothII embedded.
+
+La fascia vuota sinistra si realizza con una misura CSS condivisa, almeno 20 px,
+bilanciata con lo spazio destro. Non richiede un modulo di navigazione vuoto.
+Poiché il documento è condiviso, verificare anche che stili globali ThothII e
+contenuti sovrapposti non alterino header e sidebar del portale: il template Omics
+contiene già correzioni per reset CSS e altezza `100vh`.
+
+## Elementi da conservare
+
+La lingua dell'interfaccia, quella delle domande al revisore e quella dei contenuti
+del workspace hanno proprietari e durate diverse. Conservare la separazione di
+ADR 0022: semplificarla in un'unica preferenza globale introdurrebbe errori in
+ripresa e nei workspace italiani.
+
+Precisare tre regole d'implementazione:
+
+- una nuova sessione salva il locale UI effettivamente risolto, dopo il fallback
+  delle traduzioni;
+- una sessione esistente conserva la propria lingua anche se un altro revisore
+  usa un'interfaccia diversa;
+- per manifest precedenti senza campo lingua, usare la lingua del workspace come
+  criterio di compatibilità e fissarla alla prima ripresa con un aggiornamento
+  idempotente. Non dedurla dalla lingua del browser del nuovo revisore. La lingua
+  storica esatta non è ricostruibile se il workspace è stato cambiato nel frattempo.
+
+L'i18n resta il lavoro trasversale principale: include pagine amministrative,
+errori, accessibilità e testi deterministici dei widget, anche quelli costruiti
+fuori da React. Aggiungere soltanto i cataloghi dell'header non soddisfa la richiesta.
+Il modello deve ricevere la lingua dal manifest autorevole, senza tradurre a
+posteriori payload delle decisioni, SQL o contenuti del workspace.
+
+## Struttura raccomandata
+
+Un solo controller di shell alimenta l'interfaccia. In full gestisce preferenze
+locali e header; in embedded riceve `{ locale, theme, fullscreen }` da un
+`PortalAdapter.subscribe(...)`. I componenti applicativi usano quello stato e
+non conoscono Omics. Nessun registro dinamico di plugin, protocollo di comandi o
+controller separato per ciascun pulsante.
+
+L'autenticazione continua a usare il modulo esistente, con presentazione dell'accesso
+coerente con la shell. L'integrazione con un futuro portale richiede anche che il
+suo lato server soddisfi il contratto di identità verificata: sostituire una classe
+JavaScript non può da solo sostituire l'autenticazione server. Documentare insieme
+l'adapter UI e la configurazione server Omics, senza introdurre nuove dipendenze
+Omics nel workflow o nelle pagine ThothII.
+
+## Verifiche necessarie prima della consegna
+
+Verificare full sul Mac con default inglese, accesso/logout, tema e fullscreen;
+embedded sul template Omics, con preferenze già impostate prima del montaggio,
+cambio tema e lingua, Esc, assenza di header ThothII e descrittore precedente.
+Verificare nuova sessione, ripresa, manifest precedente, ricaricamento durante
+la revisione e perdita dell'accesso con collegamento eventi attivo.
+
+Sono verifiche del comportamento, non motivi per costruire un'infrastruttura
+generica. Questa revisione si basa sull'ispezione del sorgente; non sono stati
+eseguiti test runtime né modificati i due applicativi.