ThothII/docs/contracts/portal-shell-adapter-v1.md

# Portal Shell Adapter v1

Contratto minimo della presentazione embedded. La revisione approvata il 2026-09-13
sostituisce il precedente trasporto a eventi personalizzati con l'osservazione del
documento condiviso. Non trasferisce identità, token o stato di autenticazione.

## Configurazione

Sul Mac:

```yaml
shell:
  mode: full
  defaultLocale: en
```

Sul server Omics:

```yaml
shell:
  mode: embedded
  adapter: omics-portal
```

Se `shell` o `mode` sono omessi, la modalità è embedded. L'adapter embedded
predefinito è `omics-portal`; un nome sconosciuto è un errore di configurazione.
Questi default sono normalizzati dal CLI prima della proiezione. Nel browser,
shell interamente omessa ha gli stessi default, ma un oggetto `shell` parziale
senza `mode` o `defaultLocale` viene rifiutato: non scrivere proiezioni a mano.
Full non istanzia adapter. `defaultLocale` inizializza full; in embedded il locale
proviene dal portale. L'autenticazione si configura separatamente dalla shell.

## API applicativa

```ts
export type PortalSnapshot = {
  locale: string;
  theme: "light" | "dark";
  fullscreen: boolean;
};

export interface PortalAdapter {
  subscribe(
    onState: (state: PortalSnapshot) => void,
    onError: (error: Error) => void,
  ): () => void;
}
```

Una sottoscrizione installa gli osservatori e consegna lo snapshot iniziale senza
richiedere messaggi all'altro applicativo. Gli aggiornamenti contengono snapshot
completi e validati. La disiscrizione elimina tutti i listener e osservatori.
La lingua viene risolta tramite i cataloghi UI, con fallback inglese.

## Implementazione Omics

L'integrazione monta React nel documento Django, non in un iframe.

| Dato | Fonte privata dell'adapter | Aggiornamento |
| --- | --- | --- |
| Locale | `data-lang` del selettore `.omics-language-select` | nuova pagina Django dopo `set_language` |
| Tema | `data-bs-theme` su `html` | osservazione limitata a quell'attributo |
| Fullscreen | stato effettivo del documento | evento del browser, inclusa uscita con Esc |

Il template Omics aggiornato allinea anche `html lang` alla lingua Django, ma
la fonte dell'adapter rimane `select.omics-language-select[data-lang]`. Leggere
il valore renderizzato evita di anticipare un cambio lingua prima che il form
abbia successo. Cambiare soltanto `select.value` o `data-lang` senza il normale
reload non è un trasporto runtime implementato per la lingua.

L'assenza del contesto host atteso produce un errore di integrazione; non abilita
controlli locali. Non si introducono eventi `ready/state`, handshake, timeout,
versioni dei messaggi o comandi duplicati. Selettori e dettagli Omics non devono
essere letti dai componenti applicativi.

## Proprietà per modalità

| Funzione | Full | Embedded |
| --- | --- | --- |
| Header | ThothII | solo Omics |
| Lingua | selettore locale | selettore Omics, normale reload Django |
| Tema | toggle locale light/dark | stato Omics |
| Fullscreen | controllo locale, stato reale | controllo Omics, stato reale |
| Login/logout | ThothII local/OIDC; upstream non offre logout locale | autenticazione Omics esistente |
| Nome utente | header ThothII | header Omics |
| Rotellina amministrativa | mai | eventuale comando del portale |

## Accesso e continuità

Il server Omics verifica l'accesso a Datamart Builder e il proxy trasmette i
principal header normalizzati al backend ThothII. La UI usa `/me`; non effettua
un secondo login. Un altro portale deve soddisfare anche questo contratto server,
oltre a fornire una nuova implementazione dell'adapter UI.

Il [contratto upstream](../install/authentication-upstream.md) specifica header,
origine, rete e configurazioni incompatibili. Lo snapshot non può contenere
`authenticated`, utente, ruoli, cookie o token; un evento browser non autorizza
una richiesta API. Il prefisso API viene configurato separatamente prima del
caricamento React, non viene dedotto dall'adapter.

Il logout del portale segue la sua navigazione. Una perdita di accesso rilevata
dal server chiude lo stato protetto; un 403 di una singola operazione non equivale
automaticamente a logout. La riconnessione degli eventi e il ritorno alla pagina
ricontrollano l'accesso. Non si garantisce revoca istantanea di una connessione
aperta in un'altra scheda attraverso il solo controllo iniziale del proxy.

Il cambio lingua può ricaricare la pagina: conservare la selezione della sessione,
proteggere le modifiche non salvate e non avviare una nuova generazione al reload.
Non si conserva una trascrizione integrale nel browser. La lingua della sessione
rimane quella registrata nel manifest, secondo ADR 0022.

## Sostituzione e verifiche

Un nuovo adapter può usare un diverso documento o trasporto, ma deve rispettare
la stessa sottoscrizione e mantenere la conoscenza del portale nella propria
implementazione. Oggi `ShellProvider` istanzia direttamente `OmicsPortalAdapter`:
per sostituirlo aggiornare quel punto e i nomi accettati in
`tools/tht/internal/config/shell.go` e `frontend/src/api/runtime-config.ts`.
Non è disponibile il caricamento dinamico di classi da una stringa YAML.
Non occorre implementare ora iframe o un secondo portale.

La nuova implementazione deve pubblicare uno snapshot iniziale completo, poi gli
aggiornamenti; segnalare contesto invalido; liberare tutti i listener alla
disiscrizione. Locale ben formato ma non tradotto significa fallback inglese;
locale assente/malformato e tema diverso da light/dark sono errori di integrazione.
Non cambiare componenti applicativi o workflow per aggiungere selettori specifici
del nuovo portale.

Verificare snapshot prima/dopo il montaggio, tema, fullscreen con Esc, cleanup,
contesto host mancante, assenza di header ThothII embedded, accesso singolo,
locale dopo reload e compatibilità del prefisso API. Full deve funzionare senza
alcun elemento Omics presente.

Vedere anche [architettura del rendering](../architecture/application-shell.md)
e [matrice di accettazione](../testing/authentication-manual-acceptance.md).