00 — Introduzione: dal problema al prodotto

Perché studiare proprio PlumePilot?

Molti corsi di programmazione insegnano un concetto attraverso esempi costruiti apposta per essere semplici:

fetch('/api/users')
  .then(response => response.json())
  .then(users => console.log(users));

L'esempio è utile per imparare fetch, ma elimina quasi tutti i problemi che rendono interessante il software reale:

• chi decide quando eseguire la richiesta?
• cosa succede se la pagina cambia nel frattempo?
• dove conserviamo il risultato?
• quanto possiamo fidarci del dato ricevuto?
• cosa accade se due parti dell'applicazione avviano la stessa operazione?
• come comunichiamo il risultato a una UI che vive in un altro contesto?
• cosa succede in Firefox se l'API usata in Chrome non è disponibile allo stesso modo?

PlumePilot contiene tutte queste domande perché non è nato come esercizio didattico. È nato da problemi concreti: avanzare tra attività di un corso, organizzare materiali, creare quiz consultabili offline, generare PDF ed EPUB, osservare cambiamenti nello stato degli esami e offrire tutto questo in tre browser diversi.

Per questo il progetto è un buon laboratorio: i concetti non vengono aggiunti artificialmente alla spiegazione. Sono già lì perché il problema li ha resi necessari.

Da script utile a piccolo sistema software

All'inizio è naturale immaginare una browser extension come “JavaScript che gira sopra una pagina”.

Questa descrizione smette presto di essere sufficiente.

L'attuale PlumePilot contiene, tra le altre cose:

• un popup dell'estensione;
• un background/service worker;
• più gruppi di content script caricati in momenti e contesti differenti;
• un bridge tra il runtime dell'estensione e il runtime della pagina;
• storage persistente;
• coordinamento di operazioni lunghe;
• generatori separati per PDF, EPUB e quiz;
• un menu fluttuante inserito nelle pagine supportate;
• compatibilità con Chrome, Edge e Firefox;
• un processo di build e validazione delle release.

Quindi una prima idea fondamentale è questa:

Una browser extension non è necessariamente un singolo programma. Può essere un insieme di piccoli programmi che vivono in contesti differenti e devono coordinarsi.

Il manifest.json è il documento che dice al browser quali pezzi esistono e quando devono essere caricati.

Sarà il punto di partenza del Capitolo 1.

Il tema ricorrente: dove vive la verità?

Durante tutto il libro torneremo spesso a una domanda:

Qual è la nostra source of truth?

Supponiamo che nella UI del corso un capitolo mostri 80%.

Quel numero potrebbe essere utile per capire che probabilmente c'è qualcosa da completare. Ma è sufficiente per decidere esattamente quale attività aprire?

Non necessariamente.

Potremmo avere contemporaneamente:

DOM visibile
    ↓
percentuale del capitolo

risposta API
    ↓
stato delle lezioni

cache PlumePilot
    ↓
informazioni già osservate

Tre fonti diverse, con costi e livelli di affidabilità diversi.

Uno dei passaggi più interessanti nello sviluppo della ricerca della prima attività incompleta è stato proprio smettere di trattare una singola fonte come risposta universale e usare invece alcune informazioni come indice per decidere dove verificare.

Questa distinzione è generalizzabile ben oltre PlumePilot:

Un'informazione può non essere abbastanza affidabile da essere la verità finale, ma essere abbastanza affidabile da ridurre enormemente lo spazio di ricerca.

È il tipo di scelta che incontriamo nei sistemi distribuiti, nelle cache, nei motori di ricerca e nei database indicizzati.

Il secondo tema: il tempo

Nel software sincrono da manuale, una cosa succede dopo l'altra.

Nel browser, invece:

• una pagina carica;
• un content script parte;
• una risposta API arriva;
• l'utente apre o chiude un capitolo;
• il video termina;
• il popup viene chiuso e riaperto;
• un timer scade;
• una scheda viene ricaricata;
• il background può essere sospeso e riattivato.

La correttezza non dipende soltanto da cosa fa il codice, ma anche da quando accadono gli eventi.

Per questo parleremo molto di:

• Promise;
• eventi;
• timeout;
• polling;
• lease;
• serializzazione;
• race condition;
• cancellazione;
• idempotenza.

Il monitor della commissione è un ottimo esempio. Nel codice reale, bridge.js non si limita a dire “controlla la commissione”: prima chiede al background il diritto temporaneo di eseguire il controllo, riceve un leaseId, effettua l'operazione e infine rilascia il lease.

Non è burocrazia. È coordinamento concorrente.

Il terzo tema: i confini

PlumePilot vive contemporaneamente vicino a tre sistemi:

┌────────────────────┐
│ Browser / Extension│
│ API                │
└─────────┬──────────┘
          │
          │
┌─────────▼──────────┐
│ PlumePilot         │
└─────────┬──────────┘
          │
          │
┌─────────▼──────────┐
│ Multiversity       │
│ pagina + servizi   │
└────────────────────┘

Ogni confine introduce regole diverse.

Il codice della pagina può accedere agli oggetti JavaScript della pagina, ma non automaticamente alle API privilegiate dell'estensione. Un content script isolato può usare API dell'estensione, ma non condivide lo stesso scope JavaScript della pagina. Il background può coordinare l'estensione, ma non può manipolare direttamente il DOM di una scheda.

Molte scelte architetturali di PlumePilot sono conseguenze di questi confini.

Da backend developer: un'analogia utile

Senza prenderla troppo alla lettera, puoi iniziare a pensare ad alcuni componenti così:

Popup / Floating UI
        ↓
   presentation
        ↓
Bridge / messaging
        ↓
 application boundary
        ↓
Background coordinator
        ↓
 state / orchestration

E la pagina Multiversity può essere vista contemporaneamente come:

• una UI esterna da osservare e modificare;
• un client di API che possiamo comprendere osservandone il comportamento;
• una fonte di eventi;
• un ambiente JavaScript separato.

L'analogia con un backend a servizi non è perfetta, ma è utile: invece di function call dirette tra tutti i componenti, spesso abbiamo messaggi e contratti.

Cosa significa “finished” per questo libro

Il software non è mai definitivamente immobile. Browser, piattaforme e requisiti cambiano.

Per noi “PlumePilot finito” significa qualcosa di più pratico:

• il prodotto ha un perimetro funzionale maturo;
• le principali decisioni architetturali sono osservabili;
• esiste una storia sufficiente di bug, regressioni e miglioramenti;
• possiamo studiare il sistema senza inseguire continuamente una nuova feature fondamentale.

Questo rende possibile passare da costruire il progetto a comprenderlo sistematicamente.

Come useremo il codice

Non commenteremo migliaia di righe in ordine.

Partiremo invece da domande.

Per esempio:

Cosa succede quando clicco l'icona di PlumePilot?

oppure:

Come fa PlumePilot a comunicare con una funzione che esiste nel contesto JavaScript della pagina?

oppure:

Perché una percentuale di progresso può accelerare una ricerca pur non essendo affidabile al 100%?

Solo dopo andremo nel codice necessario a rispondere.

Questa è una modalità di lettura molto più vicina a quella usata quando si entra in un codebase reale.

Concetti da portarsi dietro

Source of truth
La fonte che consideriamo autorevole per uno stato o una decisione.

Boundary
Il confine tra due componenti o runtime che non possono condividere tutto direttamente.

Message passing
Comunicazione tramite messaggi invece di chiamate di funzione nello stesso contesto.

Race condition
Un errore o comportamento imprevisto che dipende dall'ordine temporale di operazioni concorrenti.

Idempotenza
Proprietà per cui ripetere un'operazione non produce effetti ulteriori indesiderati.

Graceful degradation
Capacità di continuare a funzionare, magari con meno funzionalità, quando una capacità non è disponibile.

Li incontreremo di nuovo nel codice, non soltanto nel glossario.

Prima di proseguire

Apri mentalmente una nuova domanda:

Se popup.js, background.js, bridge.js e content.js sono tutti JavaScript, perché PlumePilot non potrebbe semplicemente mettere tutto in un solo file?

Il Capitolo 1 nasce dalla risposta.

Precedente: Indice
Successivo: 01 — Anatomia di PlumePilot

01 — Anatomia di PlumePilot

Cosa succede quando l'estensione prende vita?

Una browser extension non parte da main().

Non esiste necessariamente un unico punto di ingresso. Il browser legge invece un file speciale, manifest.json, e da lì scopre quali componenti deve creare, dove devono vivere e quando devono essere eseguiti.

Nel nostro snapshot di riferimento, il manifest inizia così:

{
  "manifest_version": 3,
  "name": "PlumePilot – Assistente per Multiversity",
  "version": "2.35.1"
}

manifest_version: 3 ci dice che stiamo usando il modello moderno delle extension Chromium e delle WebExtensions compatibili.

Ma le righe realmente interessanti arrivano poco dopo.

1. Il manifest come mappa del sistema

Nel manifest.json di PlumePilot troviamo quattro famiglie importanti:

manifest.json
├── action
│   └── popup.html
│
├── background
│   └── background.js (+ script di supporto)
│
├── content_scripts
│   ├── MAIN world
│   └── ISOLATED world
│
└── web_accessible_resources
    └── asset utilizzabili dalle pagine supportate

Questa è già una prima lezione architetturale:

Il browser crea confini prima ancora che il nostro codice inizi a girare.

Non possiamo comprendere PlumePilot guardando soltanto le funzioni. Dobbiamo capire in quale runtime gira ogni funzione.

2. Il popup: una pagina dell'estensione

Il manifest dichiara:

"action": {
  "default_title": "PlumePilot – Assistente per Multiversity",
  "default_popup": "popup.html"
}

Quando premiamo l'icona di PlumePilot, il browser apre popup.html, che carica la logica del popup.

È importante capire cosa non è il popup.

Non è un elemento HTML inserito nella pagina Multiversity.

È una pagina appartenente all'estensione, con un proprio documento, un proprio ciclo di vita e accesso alle API permesse all'estensione.

Quando il popup viene aperto, popup.js ricostruisce buona parte dello stato visibile leggendo chrome.storage.local:

chrome.storage.local.get(
  {
    enabled: true,
    stopAtTests: false,
    autoplaySkipCompletedVideos: false,
    themePreference: "system",
    menuSize: "medium",
    floatingMenuEnabled: true,
    commissionCheckEnabled: false,
    // ...
  },
  (result) => {
    // aggiorna la UI
  },
);

File reale: popup.js, circa righe 1308–1375 nello snapshot di riferimento.

Perché ricostruire lo stato?

Perché il popup è effimero.

L'utente può aprirlo, chiuderlo e riaprirlo. Non è una buona idea trattare le variabili JavaScript del popup come memoria persistente dell'estensione.

Da backend developer puoi pensare al popup più come a una view che viene ricostruita partendo dallo stato persistente che come a un processo centrale sempre vivo.

Questa scelta anticipa un concetto che approfondiremo nel capitolo sullo storage:

La lifetime di una UI non coincide necessariamente con la lifetime dello stato dell'applicazione.

3. Il background: il coordinatore che non vede il DOM

Nel manifest troviamo:

"background": {
  "scripts": [
    "achievements.js",
    "commission-state.js",
    "sound-settings.js",
    "whats-new.js",
    "background.js"
  ],
  "service_worker": "background.js"
}

Questa configurazione serve alla base multipiattaforma.

Nel modello Manifest V3 di Chrome, background.js viene usato come extension service worker. Firefox supporta la forma scripts per il background. La stessa base sorgente può quindi essere trasformata dal processo di build nel pacchetto più adatto al browser.

Il ruolo concettuale del background è più importante del dettaglio di packaging:

Il background coordina attività che appartengono all'estensione nel suo insieme, non a una singola pagina visualizzata.

Per esempio, alla fine di background.js troviamo un vero dispatcher di messaggi:

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  let action = null;

  if (message?.type === "PEGASO_GET_OPERATION")
    action = reconcileOperationOwner();
  else if (message?.type === "PEGASO_START_EXPORT")
    action = startExport({ ...message, sourceTabId });
  else if (message?.type === "PEGASO_CANCEL_EXPORT")
    action = cancelExport(message);
  else if (message?.type === "PEGASO_COMMISSION_CHECK_CLAIM")
    action = claimCommissionCheck(sourceTabId, message.platformId);

  // ...

  action.then(sendResponse).catch(/* ... */);
  return true;
});

File reale: background.js, circa righe 918–945.

Questa forma assomiglia molto a un router o controller backend:

message.type
    ↓
dispatcher
    ↓
handler
    ↓
risposta asincrona

Non è HTTP, ma il modello mentale è sorprendentemente simile.

Ma allora perché il background non fa tutto?

Perché non vive nel DOM della pagina.

Se deve sapere quali lezioni sono renderizzate, leggere un bottone della pagina o osservare uno stato JavaScript del sito, ha bisogno di codice che viva nella scheda.

Ed entrano in scena i content script.

4. Content script: JavaScript dentro una pagina, ma non necessariamente della pagina

Il manifest di PlumePilot registra diversi gruppi di content_scripts.

Uno di essi carica:

{
  "js": ["commission-interceptor.js"],
  "run_at": "document_start",
  "all_frames": false,
  "world": "MAIN"
}

Un altro carica:

{
  "js": [
    "commission-state.js",
    "sound-settings.js",
    "bridge.js"
  ],
  "run_at": "document_start",
  "all_frames": false
}

Qui world non è specificato, quindi il content script usa normalmente il mondo ISOLATED.

Questa differenza è fondamentale.

5. MAIN world e ISOLATED world

Immagina la pagina Multiversity come una stanza con lo stesso tavolo — il DOM — ma due serie separate di variabili JavaScript.

                 stesso DOM
                    │
        ┌───────────┴───────────┐
        │                       │
   MAIN world              ISOLATED world
        │                       │
 codice pagina            content script
 + content.js             bridge.js
 + interceptor            floating-menu.js
        │                       │
        └──── window.postMessage ────┘

MAIN world

Il codice gira nello stesso ambiente JavaScript della pagina.

Questo è utile quando PlumePilot deve osservare o interagire con comportamenti che appartengono direttamente all'applicazione web.

Ma c'è un prezzo: quel codice non gode automaticamente dell'isolamento e delle API privilegiate tipiche del content script.

ISOLATED world

Il codice condivide il documento e quindi può lavorare sul DOM, ma il proprio scope JavaScript è separato da quello della pagina.

In compenso è il posto adatto per usare API dell'estensione come chrome.storage e chrome.runtime.

Questa riga di commento dentro content.js racconta l'architettura quasi meglio del manifest:

// Receives the enabled/paused state from bridge.js, which runs in the
// extension's isolated world and therefore has access to chrome.storage.

File reale: content.js, circa righe 248–249.

Subito dopo content.js ascolta messaggi provenienti dallo stesso window:

window.addEventListener("message", (event) => {
  if (event.source !== window) return;
  if (!event.data) return;

  // interpreta i messaggi del bridge
});

Abbiamo quindi un pattern deliberato:

ISOLATED world
bridge.js
    │
    │ window.postMessage(...)
    ▼
MAIN world
content.js / interceptor

E viceversa.

6. Perché serve bridge.js?

Il nome non è metaforico. È davvero un ponte.

Prendiamo il controllo della commissione.

bridge.js può parlare con il background:

chrome.runtime.sendMessage({
  type: "PEGASO_COMMISSION_CHECK_CLAIM",
  platformId: PLATFORM_ID,
}, (response) => {
  // ...
});

Ma quando deve chiedere al codice che vive nel MAIN world di effettuare un'operazione legata alla pagina, usa:

window.postMessage({
  type: COMMISSION_REQUEST,
  requestId: leaseId,
  expiresAt,
}, "*");

Possiamo rappresentare il flusso così:

sequenceDiagram
    participant B as Background
    participant Br as bridge.js (ISOLATED)
    participant P as Page scripts (MAIN)

    Br->>B: PEGASO_COMMISSION_CHECK_CLAIM
    B-->>Br: leaseId + expiresAt
    Br->>P: window.postMessage(COMMISSION_REQUEST)
    P-->>Br: window.postMessage(risultato)
    Br->>B: memorizza/rilascia stato

Questo è message passing tra boundary.

Se tutti i componenti vivessero nello stesso scope, potremmo chiamare una funzione direttamente:

requestCommissionData();

Ma qui i runtime sono separati. Il messaggio diventa il contratto.

7. Popup → scheda: un altro tipo di messaggio

Il popup deve anche interrogare direttamente la scheda attiva.

In popup.js troviamo:

chrome.tabs.sendMessage(
  tabId,
  { type: "PEGASO_COURSE_PROGRESS_STATUS_REQUEST" },
  { frameId: 0 },
  (response) => {
    if (chrome.runtime.lastError || !response?.status) return;
    renderCourseProgress(response.status);
  },
);

Qui non stiamo usando window.postMessage.

Perché?

Perché mittente e destinatario non sono due world JavaScript della stessa pagina: il mittente è una extension page (popup) e il destinatario è un content script nella tab.

Quindi abbiamo già almeno due bus di comunicazione differenti:

chrome.runtime / chrome.tabs messaging
    → tra componenti dell'estensione

window.postMessage
    → tra world JavaScript nella stessa pagina

Questa distinzione sarà il cuore del Capitolo 2.

8. Un diagramma più completo

A questo punto possiamo costruire una prima mappa utile dell'architettura.

flowchart TD
    U[Utente] --> P[Popup<br/>popup.html + popup.js]
    U --> F[Floating menu<br/>ISOLATED world]

    P -->|chrome.runtime.sendMessage| B[Background coordinator<br/>background.js]
    P -->|chrome.tabs.sendMessage| Br[bridge.js<br/>ISOLATED world]

    F --> Br
    Br -->|chrome.runtime messaging| B

    Br <-->|window.postMessage| M[MAIN world<br/>content.js / commission-interceptor.js]

    M --> D[DOM Multiversity]
    M --> A[Stato / API osservabili dalla pagina]

    B --> S[chrome.storage.local]
    Br --> S
    P --> S

Non è ancora la mappa completa di tutte le feature, ma è sufficiente per rispondere alla domanda iniziale:

Perché non possiamo mettere tutto in un singolo file?

Perché le responsabilità richiedono privilegi, lifetime e ambienti di esecuzione differenti.

9. run_at: anche quando conta

I content script non sono caricati tutti nello stesso momento.

PlumePilot usa sia:

"run_at": "document_start"

sia:

"run_at": "document_idle"

document_start è utile quando dobbiamo essere presenti molto presto nel ciclo di vita della pagina. document_idle è adatto quando possiamo aspettare che il documento sia sostanzialmente pronto.

Per esempio, commission-interceptor.js viene caricato nel MAIN world a document_start.

Questo suggerisce una regola generale:

Se devi osservare un comportamento della pagina che potrebbe avvenire molto presto, arrivare dopo significa potenzialmente perdere l'evento.

Al contrario, una UI che dipende da elementi già presenti nella pagina può spesso aspettare document_idle.

Quindi il manifest non specifica soltanto dove eseguire il codice. Specifica anche quando inserirlo nella vita del documento.

10. all_frames: una pagina non è sempre un solo documento

Alcuni gruppi di script usano:

"all_frames": true

Questo ricorda che una tab può contenere iframe e quindi più documenti.

È facile dire “lo script gira nella pagina”, ma tecnicamente la domanda più corretta è:

In quale frame del tab gira?

Nel popup, quando PlumePilot invia alcune richieste alla tab, specifica esplicitamente:

{ frameId: 0 }

cioè il frame principale.

È un dettaglio apparentemente piccolo, ma previene ambiguità quando la stessa estensione può essere caricata in più frame.

11. web_accessible_resources: asset dell'estensione visibili alla pagina

Il manifest espone anche alcune risorse, per esempio immagini della modalità Gaming, font e audio.

Non tutto ciò che è contenuto nel pacchetto di un'estensione deve essere automaticamente raggiungibile da una pagina web.

web_accessible_resources dichiara esplicitamente quali file possono essere richiesti dai contesti corrispondenti ai pattern indicati.

Questo è un altro esempio del principio del least privilege:

esponi ciò che serve, non l'intero pacchetto.

Lo stesso principio tornerà quando parleremo di permissions e host_permissions.

12. Permessi: ciò che PlumePilot può fare non è implicito

Nello snapshot corrente il manifest dichiara:

"permissions": ["storage"]

oltre a host_permissions per host necessari alla gestione di materiali e risorse.

Le extension API sono capability esplicite. Questo è diverso da una normale pagina web, dove il codice parte già all'interno del modello di sicurezza dell'origine del sito.

Quando progetteremo mentalmente una feature, una buona domanda sarà sempre:

In quale contesto dovrebbe vivere questa funzione e qual è il minimo privilegio necessario?

Questa domanda spesso determina l'architettura prima ancora del codice.

13. Un caso concreto: il popup vuole mostrare il progresso

Seguiamo finalmente un piccolo percorso end-to-end.

Passo 1 — l'utente apre il popup

Il browser crea popup.html e viene eseguito popup.js.

Passo 2 — il popup ricostruisce preferenze persistenti

popup.js
    ↓
chrome.storage.local.get(...)
    ↓
render della UI

Passo 3 — individua la tab attiva

Nel codice troviamo:

chrome.tabs.query({ active: true, currentWindow: true }, ...)

Passo 4 — chiede lo stato del corso

popup
  │
  │ PEGASO_COURSE_PROGRESS_STATUS_REQUEST
  ▼
content script della tab

tramite chrome.tabs.sendMessage.

Passo 5 — riceve lo stato e renderizza

renderCourseProgress(response.status);

Passo 6 — resta in ascolto

Il popup registra anche:

chrome.runtime.onMessage.addListener(...)

per aggiornarsi quando riceve nuovi stati mentre è aperto.

Quindi il popup non “possiede” il progresso. Lo visualizza.

Questo è un ottimo esempio di separazione tra stato e presentazione.

14. Da backend developer: tre analogie

chrome.runtime.onMessage come router interno

Puoi pensare ai message.type come a endpoint logici:

PEGASO_START_EXPORT
PEGASO_CANCEL_EXPORT
PEGASO_GET_OPERATION
...

Non sono URL, ma identificano comandi e richieste.

Il background come application service

Coordina operazioni, storage e ownership senza conoscere il dettaglio visuale del DOM.

Il bridge come adapter

Converte comunicazione e capacità tra due ambienti incompatibili:

Extension APIs ⇄ bridge ⇄ Page runtime

In architettura software chiameremmo spesso un componente simile adapter o gateway.

15. Una nota architetturale importante: file grande ≠ automaticamente cattiva architettura

Lo snapshot corrente contiene file molto grandi, tra cui content.js, floating-menu.js e popup.js.

È facile guardare soltanto la dimensione e concludere che il sistema sia monolitico.

Ma esistono due livelli diversi:

1. modularità fisica — come dividiamo il codice in file;
2. modularità runtime — quali responsabilità vivono in processi/contesti distinti.

PlumePilot ha margine per una maggiore modularità fisica, tema che affronteremo nell'ultimo capitolo. Ma possiede già confini runtime reali imposti e sfruttati dall'architettura WebExtensions.

È importante non confondere le due cose.

16. Cosa abbiamo imparato dal solo manifest.json

Senza ancora studiare autoplay, API o EPUB, sappiamo già che PlumePilot:

• usa Manifest V3;
• ha una UI popup separata dalla pagina;
• possiede un background coordinator;
• esegue codice sia nel MAIN sia nell'ISOLATED world;
• usa timing diversi (document_start / document_idle);
• considera esplicitamente frame diversi;
• espone soltanto determinate risorse alla pagina;
• richiede capability attraverso permessi dichiarati;
• deve usare messaging per attraversare i boundary.

Il manifest è quindi molto più di “metadata per lo store”.

È una mappa dichiarativa dell'architettura runtime.

Concetti da portarsi dietro

Execution context

L'ambiente in cui gira un pezzo di codice: quali globali vede, quali API può usare e quale lifetime possiede.

MAIN world

Il contesto JavaScript condiviso con la pagina web.

ISOLATED world

Contesto separato usato dai content script, che condivide il DOM ma non lo stesso scope JavaScript della pagina.

Extension page

Una pagina HTML appartenente all'estensione, come il popup.

Background / service worker

Componente dedicato alla gestione di eventi e operazioni che non appartengono a una singola pagina.

Message passing

Comunicazione tra componenti separati attraverso messaggi serializzabili.

Adapter / bridge

Componente che traduce tra interfacce o ambienti differenti.

Least privilege

Concedere ed esporre soltanto le capacità necessarie.

Piccolo esercizio mentale

Prima di leggere il prossimo capitolo, prova a classificare queste operazioni:

1. salvare la preferenza themePreference;
2. leggere un valore JavaScript appartenente alla pagina Multiversity;
3. mostrare il valore nel popup;
4. coordinare un export che deve sopravvivere alla chiusura del popup;
5. aggiornare un elemento del DOM del corso.

Per ciascuna chiediti:

Dove dovrebbe vivere?
Popup?
Background?
MAIN world?
ISOLATED world?

Non tutte hanno una sola risposta possibile. Il punto è iniziare a ragionare in termini di confini e responsabilità.

Approfondimenti

Fonti primarie consigliate:

• MDN — Anatomy of an extension: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension
• MDN — Content scripts: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts
• MDN — content_scripts manifest key: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts
• MDN — background manifest key: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background
• Chrome for Developers — chrome.scripting e execution worlds: https://developer.chrome.com/docs/extensions/reference/api/scripting
• Chrome for Developers — Manifest V3 overview: https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3

Quando leggi documentazione sulle extension, fai attenzione a due assi distinti:

Manifest V2 vs Manifest V3
Chrome vs Firefox/WebExtensions

Un esempio trovato online può essere corretto in un browser e non rappresentare esattamente il runtime dell'altro.

Nel prossimo capitolo

Ora sappiamo chi sono i componenti.

La domanda successiva è:

Come fanno a parlarsi senza trasformare l'estensione in una rete di messaggi impossibile da seguire?

Seguiremo un messaggio reale dalla UI al background, dalla tab al bridge e dal bridge al MAIN world. Vedremo callback, Promise, sendResponse, lifetime asincrona dei listener, window.postMessage e i primi veri problemi di concorrenza.

Precedente: 00 — Introduzione
Indice: Inside PlumePilot

02 — Contesti e messaging

Far parlare mondi separati

Nel capitolo precedente abbiamo visto che PlumePilot non vive in un unico ambiente JavaScript.

Il popup, il background, i content script nel mondo isolato, gli script nel MAIN world e le pagine builder sono componenti distinti. Possono appartenere alla stessa estensione, ma non condividono automaticamente memoria, scope globale o ciclo di vita.

Questo cambia radicalmente il modo in cui dobbiamo ragionare sul programma.

In una normale funzione possiamo fare questo:

const result = calculateSomething(input);

Il chiamante conosce direttamente la funzione, le passa un valore e riceve il risultato.

Tra due contesti dell'estensione, invece, spesso la situazione assomiglia di più a questa:

componente A
    │
    │  { type: "DO_SOMETHING", ... }
    ▼
confine
    │
    ▼
componente B
    │
    │  { accepted: true, ... }
    ▼
componente A

Il componente A non chiama direttamente una funzione privata di B. Invia invece un messaggio che descrive ciò che vuole ottenere.

Questa è la base del message passing.

Ed è uno dei concetti più importanti per comprendere PlumePilot.

1. Da chiamate di funzione a contratti

Quando due pezzi di codice vivono nello stesso scope, il contratto può essere semplicemente la firma di una funzione:

startExport(format, tabId);

Quando attraversiamo un boundary, il contratto diventa invece un oggetto serializzabile:

{  type: "PEGASO_START_EXPORT",
  format: "materials",
  sourceTabId: tabId,
  requestSource: "toolbar-popup"
}

Questo oggetto non contiene comportamento. Contiene dati che descrivono una richiesta.

Il campo più importante è spesso type.

Puoi pensarlo come a una route:

POST /exports/start

nel backend, oppure come a un nome di evento:

PEGASO_START_EXPORT

nel sistema di messaging.

Il destinatario guarda quel valore e decide quale handler eseguire.

In background.js accade esattamente questo:

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  let action = null;

  if (message?.type === "PEGASO_GET_OPERATION")
    action = reconcileOperationOwner();
  else if (message?.type === "PEGASO_START_EXPORT")
    action = startExport({ ...message, sourceTabId });
  else if (message?.type === "PEGASO_CANCEL_EXPORT")
    action = cancelExport(message);

  // ...
});

Riferimento reale: background.js, dispatcher dei messaggi.

Il background si comporta quindi come un piccolo dispatcher:

message.type
     │
     ├── PEGASO_START_EXPORT ─────► startExport()
     ├── PEGASO_CANCEL_EXPORT ────► cancelExport()
     ├── PEGASO_GET_OPERATION ────► reconcileOperationOwner()
     └── ...

Concetto da portarsi dietro

Quando attraversiamo un boundary non stiamo soltanto "chiamando una funzione in un altro posto".

Stiamo definendo un protocollo.

Anche se il protocollo è interno all'applicazione.

2. I tre canali principali di PlumePilot

PlumePilot usa soprattutto tre meccanismi di comunicazione:

1. chrome.runtime.sendMessage()
2. chrome.tabs.sendMessage()
3. window.postMessage()

Sembrano simili, ma risolvono problemi differenti.

chrome.runtime.sendMessage()

Invia un messaggio ad altri contesti dell'estensione, tipicamente al background.

Esempio dal popup:

chrome.runtime.sendMessage(message, (response) => {
  // usa la risposta
});

È appropriato quando la destinazione appartiene al runtime dell'estensione, non quando vogliamo indirizzare direttamente un content script in una specifica scheda.

chrome.tabs.sendMessage()

Invia un messaggio ai content script presenti in una scheda precisa.

PlumePilot lo usa, per esempio, per comunicare con il corso aperto dall'utente:

chrome.tabs.sendMessage(
  tabId,
  { type: "PEGASO_COURSE_PROGRESS_STATUS_REQUEST" },
  { frameId: 0 },
  callback,
);

Qui compare già una seconda informazione importante: la destinazione non è soltanto l'estensione, ma una specifica tab e persino uno specifico frame.

window.postMessage()

È invece una API Web standard, non specifica delle estensioni.

In PlumePilot viene usata soprattutto per attraversare il confine tra:

ISOLATED world  ◄────►  MAIN world

perché entrambi i mondi osservano lo stesso window, pur non condividendo lo stesso scope JavaScript.

Per esempio bridge.js può fare:

window.postMessage(
  { type: "PEGASO_COURSE_PROGRESS_STATUS_REQUEST" },
  "*",
);

mentre content.js ascolta:

window.addEventListener("message", (event) => {
  if (event.source !== window) return;
  if (!event.data) return;

  if (event.data.type === "PEGASO_COURSE_PROGRESS_STATUS_REQUEST") {
    // ...
  }
});

La stessa pagina diventa quindi una specie di bus locale di messaggi.

3. Una mappa mentale dei canali

Prima di seguire un caso reale, fissiamo una regola pratica.

                         ESTENSIONE

 popup / builder                       background
      │                                    ▲
      │ chrome.runtime.sendMessage         │
      └────────────────────────────────────┘

 background / popup
      │
      │ chrome.tabs.sendMessage(tabId)
      ▼
 bridge.js / content script isolato
      │
      │ window.postMessage
      ▼
 content.js / MAIN world
      │
      ▼
 pagina Multiversity

Naturalmente la comunicazione può anche risalire nella direzione opposta.

Il punto fondamentale è questo:

Il tipo di messaggio dipende dal boundary che dobbiamo attraversare.

Questa è una domanda utile ogni volta che leggi PlumePilot:

"Da quale contesto sto partendo, e quale contesto devo raggiungere?"

Spesso è sufficiente per capire perché sia stata usata una API invece di un'altra.

Parte I — Un flusso semplice

4. Caso reale: il popup chiede il progresso del corso

Cominciamo da una richiesta relativamente semplice.

Quando il popup viene aperto, vuole mostrare il progresso del corso corrente.

In popup.js troviamo:

chrome.tabs.sendMessage(
  tabId,
  { type: "PEGASO_COURSE_PROGRESS_STATUS_REQUEST" },
  { frameId: 0 },
  (response) => {
    if (chrome.runtime.lastError || !response?.status) return;
    renderCourseProgress(response.status);
  },
);

Riferimento: popup.js L1392–L1399.

Il popup conosce l'ID della tab attiva e manda quindi un messaggio al content script della pagina.

Primo passaggio

popup.js
   │
   │ chrome.tabs.sendMessage(tabId, ...)
   ▼
bridge.js

Perché arriva a bridge.js?

Perché bridge.js è registrato come content script nel mondo isolato e ascolta chrome.runtime.onMessage.

Il suo handler contiene:

if (message?.type === "PEGASO_COURSE_PROGRESS_STATUS_REQUEST") {
  window.postMessage(
    { type: "PEGASO_COURSE_PROGRESS_STATUS_REQUEST" },
    "*",
  );

  sendResponse({
    accepted: true,
    status: courseProgressStatus,
  });

  return;
}

Riferimento: bridge.js L368–L371.

Qui accadono due cose diverse.

Il bridge:

1. restituisce immediatamente al popup l'ultimo stato che conosce;
2. chiede contemporaneamente al MAIN world di aggiornare lo stato.

Questa distinzione è molto interessante.

5. Risposta immediata e aggiornamento successivo

Potremmo immaginare una soluzione ingenua:

popup
  ↓
calcola da zero il progresso
  ↓
attendi
  ↓
rispondi

PlumePilot adotta invece un modello più reattivo:

popup
  │
  ├──► riceve subito l'ultimo snapshot noto
  │
  └──► provoca un refresh nel MAIN world
                    │
                    ▼
             nuovo stato calcolato
                    │
                    ▼
             aggiornamento push

Il courseProgressStatus custodito dal bridge è quindi una snapshot cache.

Può essere abbastanza recente da mostrare subito qualcosa, mentre il sistema aggiorna lo stato reale in parallelo.

Il popup non deve rimanere bloccato aspettando che ogni calcolo sia terminato.

Questo introduce un concetto: eventual consistency

Per un breve intervallo due componenti possono non possedere esattamente la stessa informazione.

Poi gli eventi li riallineano.

Non significa necessariamente che il sistema sia "sbagliato".

Significa che la consistenza non è ottenuta tramite memoria condivisa e sincrona, ma tramite propagazione dello stato.

Questo modello è comunissimo nei sistemi distribuiti, nelle UI reattive e nelle applicazioni event-driven.

PlumePilot ce ne offre una versione molto piccola e osservabile.

6. Attraversiamo il confine ISOLATED → MAIN

Il bridge ha fatto:

window.postMessage(
  { type: "PEGASO_COURSE_PROGRESS_STATUS_REQUEST" },
  "*",
);

content.js, che gira nel MAIN world, riceve il messaggio:

if (event.data.type === "PEGASO_COURSE_PROGRESS_STATUS_REQUEST") {
  scheduleCourseProgressInitialization(0);
  publishCourseProgressStatus();
  return;
}

Riferimento: content.js L423–L426.

A questo punto siamo passati da:

WebExtension API world

al codice che vive insieme alla pagina.

Il MAIN world calcola il proprio stato e lo pubblica nuovamente:

window.postMessage({
  type: "PEGASO_COURSE_PROGRESS_STATUS",
  status: {
    courseCode: state.courseCode,
    available: percent !== null && state.chapterCount > 0,
    percent,
    chapterCount: state.chapterCount,
    knownChapters: courseProgressChapters.size,
    exact: exactAvailable,
    // ...
  },
}, "*");

Riferimento: content.js L4478–L4500.

Questa volta la direzione è opposta:

MAIN world
   │
   │ window.postMessage
   ▼
bridge.js

7. Il bridge come adapter

Il bridge riceve il nuovo stato e non lo inoltra ciecamente.

Prima lo normalizza:

courseProgressStatus = courseCode ? {
  platformId: PLATFORM_ID,
  courseCode,
  available: source.available === true && Number.isFinite(percent),
  percent: Number.isFinite(percent)
    ? Math.max(0, Math.min(100, Math.floor(percent)))
    : null,
  chapterCount: Math.max(0, Math.floor(Number(source.chapterCount) || 0)),
  knownChapters: Math.max(0, Math.floor(Number(source.knownChapters) || 0)),
  exact: source.exact === true,
  updatedByStudyWing: source.updatedByStudyWing === true,
  message: safeText(source.message, 160) || "",
} : null;

Poi lo rimanda nel runtime dell'estensione:

chrome.runtime.sendMessage({
  type: "PEGASO_COURSE_PROGRESS_STATUS",
  status: courseProgressStatus,
});

Riferimento: bridge.js L513–L534.

Questo ci mostra perché il nome bridge è appropriato.

Non è soltanto un cavo.

È anche un adapter.

MAIN world payload
       │
       ▼
validazione / normalizzazione
       │
       ▼
extension runtime payload

Notiamo alcune difese:

Number.isFinite(percent)
Math.max(...)
Math.min(...)
safeText(...)

Il bridge decide quale forma dei dati è accettabile prima di portarli nell'altro contesto.

Concetto generale

Ogni boundary è un buon posto in cui:

• validare;
• normalizzare;
• ridurre i dati;
• rifiutare input non valido;
• tradurre da un modello a un altro.

È lo stesso motivo per cui in un backend potresti avere DTO, serializer o adapter tra layer.

8. Il popup riceve l'aggiornamento push

popup.js non si limita alla risposta iniziale.

Ascolta anche aggiornamenti successivi:

chrome.runtime.onMessage.addListener((message, sender) => {
  if (
    message?.type === "PEGASO_COURSE_PROGRESS_STATUS" &&
    sender?.tab?.id === activeCourseTabId
  ) {
    renderCourseProgress(message.status || null);
  }
});

Riferimento: popup.js L1402–L1409.

Qui compare un'altra difesa importante:

sender?.tab?.id === activeCourseTabId

Il popup potrebbe ricevere eventi provenienti da più tab.

Non vuole mostrare nel corso A il progresso ricevuto dalla tab B.

Quindi non basta chiedersi:

"Che tipo di messaggio è?"

Bisogna anche chiedersi:

"Chi lo ha inviato?"

9. Il flusso completo del progresso

Possiamo finalmente rappresentarlo per intero:

sequenceDiagram
    participant P as popup.js
    participant B as bridge.js (ISOLATED)
    participant C as content.js (MAIN)

    P->>B: tabs.sendMessage(PROGRESS_STATUS_REQUEST)
    B-->>P: sendResponse(snapshot nota)
    B->>C: window.postMessage(PROGRESS_STATUS_REQUEST)
    C->>C: aggiorna/calcola stato
    C->>B: window.postMessage(PROGRESS_STATUS)
    B->>B: valida e normalizza
    B->>P: runtime.sendMessage(PROGRESS_STATUS)
    P->>P: renderCourseProgress()

Questo è un pattern molto più ricco di una semplice richiesta sincrona.

Contiene:

• richiesta;
• risposta immediata;
• refresh asincrono;
• evento di aggiornamento;
• cache locale;
• controllo del mittente.

Ed è ancora uno dei flussi relativamente semplici di PlumePilot.

Parte II — Request/response asincrona

10. sendResponse() e il problema del tempo

Consideriamo ora il listener nel background:

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  let action = null;

  // ... selezione dell'azione ...

  action
    .then(sendResponse)
    .catch((error) => {
      sendResponse({ accepted: false, reason: error.message });
    });

  return true;
});

Perché quel return true?

Per capirlo dobbiamo distinguere due casi.

Risposta sincrona

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  sendResponse({ accepted: true });
});

La risposta viene inviata prima che il listener termini.

Risposta asincrona

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  doSomethingAsync().then((result) => {
    sendResponse(result);
  });

  return true;
});

Il listener termina prima che la Promise completi.

return true segnala al runtime che il canale di risposta deve restare disponibile perché sendResponse() verrà chiamato successivamente.

Questo dettaglio è facile da ignorare e può generare bug apparentemente inspiegabili:

messaggio inviato
    ↓
handler avviato
    ↓
operazione async partita
    ↓
handler termina
    ↓
canale chiuso      ← se non viene mantenuto
    ↓
Promise completa
    ↓
sendResponse(...)  ← troppo tardi

Con return true:

handler termina
    ↓
canale mantenuto
    ↓
Promise completa
    ↓
sendResponse(...)

La documentazione WebExtensions descrive esplicitamente questo pattern.

Collegamento con il backend

È vagamente simile alla differenza tra:

return response;

e un handler che deve aspettare una query o un servizio asincrono prima di poter completare la risposta.

La differenza è che qui il meccanismo di risposta è gestito dal runtime dell'estensione.

11. Perché PlumePilot trasforma i callback in Promise

Nel popup troviamo:

function runtimeMessage(message) {
  return new Promise((resolve) =>
    chrome.runtime.sendMessage(message, (response) =>
      resolve(
        chrome.runtime.lastError
          ? { accepted: false, reason: chrome.runtime.lastError.message }
          : response,
      ),
    ),
  );
}

Riferimento: popup.js L1296–L1306.

Il chiamante può quindi scrivere:

const response = await runtimeMessage({
  type: "PEGASO_START_EXPORT",
  // ...
});

invece di annidare callback.

Questa funzione svolge due lavori:

1. converte un'API callback-style in una Promise;
2. converte chrome.runtime.lastError in un normale valore applicativo.

Il secondo punto è importante.

Invece di obbligare ogni chiamante a ricordare:

if (chrome.runtime.lastError) {
  // ...
}

l'errore viene trasformato in una risposta coerente:

{
  accepted: false,
  reason: "..."
}

Un piccolo adapter asincrono

Possiamo pensare a runtimeMessage() come a:

API del browser
(callback + runtime.lastError)
          │
          ▼
runtimeMessage()
          │
          ▼
API interna PlumePilot
(Promise + accepted/reason)

Ancora una volta compare lo stesso principio:

I boundary sono posti naturali in cui tradurre un'interfaccia in un'altra.

Parte III — Un workflow lungo

12. Caso reale: esportare le dispense

Il flusso del progresso era corto.

L'export delle dispense è molto più interessante perché l'operazione:

• parte dal popup;
• viene coordinata dal background;
• viene eseguita sulla pagina del corso;
• attraversa i due execution world;
• invia aggiornamenti intermedi;
• termina aprendo una nuova pagina builder;
• continua a vivere anche se il popup viene chiuso.

Questa ultima proprietà è essenziale.

Se l'operazione appartenesse al popup, chiudere il popup potrebbe distruggere lo stato del processo.

Invece il popup è soltanto uno dei client del workflow.

13. Step 1 — Il popup invia un comando

Quando l'utente avvia la raccolta delle dispense:

const response = await runtimeMessage({
  type: "PEGASO_START_EXPORT",
  format: "materials",
  sourceTabId: tabId,
  requestSource: "toolbar-popup",
});

Riferimento: popup.js L2112–L2133.

Questo messaggio è semanticamente un command.

Sta dicendo:

"Per favore, prova ad avviare questa operazione."

Non sta semplicemente annunciando che qualcosa è successo.

Questa distinzione sarà utile per leggere meglio i nomi dei messaggi.

Command

Esprime un'intenzione:

START_EXPORT
CANCEL_EXPORT
FIND_FIRST_INCOMPLETE

Event

Descrive qualcosa che è già avvenuto:

COURSE_PROGRESS_STATUS
COURSE_MATERIALS_COLLECTED
EXPORT_COLLECTION_FAILED

Il codice non applica formalmente una convenzione CQRS o event sourcing, ma la distinzione concettuale è già presente.

14. Step 2 — Il background acquisisce l'operazione

Il dispatcher del background instrada il comando verso:

startExport(...)

All'interno troviamo:

const result = await acquire(format, message.sourceTabId);
if (!result.accepted) return result;

Riferimento: background.js L700–L719.

Il background non ordina immediatamente alla pagina di raccogliere materiale.

Prima acquisisce il diritto di eseguire l'operazione.

Questo impedisce che workflow incompatibili partano contemporaneamente.

Ne parleremo molto meglio nei capitoli su stato, concorrenza e race condition; per ora basta notare che il background è il punto centrale adatto a decidere:

"C'è già qualcosa in esecuzione?"

Una singola tab non avrebbe necessariamente una visione globale sufficiente.

15. Step 3 — Nasce un operationId

Dopo l'acquisizione, l'operazione possiede un identificatore:

result.operation.id

Il background lo invia alla tab:

const response = await sendTabMessage(message.sourceTabId, {
  type: "PEGASO_COLLECT_COURSE_MATERIALS",
  format,
  operationId: result.operation.id,
});

L'operationId è uno dei concetti architetturali più utili dell'intero flusso.

Senza di esso avremmo messaggi del tipo:

"raccolta iniziata"
"25%"
"raccolta completata"

Ma a quale raccolta appartengono?

Con l'identificatore possiamo invece avere:

operationId = 9f2...

START      9f2...
STATUS     9f2...
STATUS     9f2...
COMPLETE   9f2...

Questo è un correlation ID.

Serve a collegare messaggi diversi allo stesso workflow logico.

È un pattern molto comune nei sistemi a messaggi, nelle code, nelle pipeline asincrone e nel tracing distribuito.

16. Step 4 — Il background indirizza una tab precisa

La funzione helper è:

function sendTabMessage(tabId, message) {
  return new Promise((resolve, reject) =>
    chrome.tabs.sendMessage(
      tabId,
      message,
      { frameId: 0 },
      (response) =>
        chrome.runtime.lastError
          ? reject(new Error(chrome.runtime.lastError.message))
          : resolve(response),
    ),
  );
}

Riferimento: background.js L677–L683.

Qui compaiono due coordinate:

tabId
frameId: 0

Il messaggio non è un broadcast generico al browser.

È indirizzato al top frame di una scheda precisa.

Questa è un'altra somiglianza con i sistemi distribuiti: oltre al contenuto del messaggio serve spesso una forma di addressing.

17. Step 5 — Il bridge deduplica prima di inoltrare

Il messaggio arriva a bridge.js:

if (message?.type === "PEGASO_COLLECT_COURSE_MATERIALS") {
  const operationId = exportOperationId(message.operationId);

  if (!operationId) {
    sendResponse({
      accepted: false,
      reason: "Identificativo operazione mancante.",
    });
    return;
  }

  if (requestedExportOperationIds.has(operationId)) {
    sendResponse({ accepted: true, duplicate: true });
    return;
  }

  rememberExportOperation(requestedExportOperationIds, operationId);

  window.postMessage({
    type: "PEGASO_COLLECT_COURSE_MATERIALS_REQUEST",
    format: message.format,
    operationId,
  }, "*");

  sendResponse({ accepted: true, duplicate: false });
}

Riferimento: bridge.js L373–L390.

Qui vediamo una misura di robustezza molto concreta:

requestedExportOperationIds.has(operationId)

Se per qualche motivo lo stesso comando viene recapitato nuovamente, il bridge evita di avviare una seconda raccolta identica.

Questa tecnica si chiama deduplicazione.

È strettamente collegata all'idempotenza.

Idempotenza perfetta vs deduplicazione

Un'operazione idempotente produce naturalmente lo stesso effetto anche se ripetuta.

Per esempio:

SET theme = dark
SET theme = dark
SET theme = dark

ha lo stesso risultato di una sola chiamata.

Una raccolta di dispense, invece, è un'operazione costosa e non vogliamo necessariamente eseguirla tre volte.

Quindi PlumePilot usa un'altra strategia:

"Ho già visto questo operationId?"
       │
   sì ─┴─► ignora duplicato

Non rende magicamente ogni effetto idempotente, ma avvicina il workflow a un comportamento at-most-once per quell'identificatore, entro la memoria e la lifetime del componente che conserva il set.

Questa precisazione è importante: non dobbiamo attribuire al codice garanzie più forti di quelle che possiede realmente.

18. Step 6 — MAIN world: la raccolta comincia davvero

Il bridge inoltra la richiesta tramite window.postMessage().

content.js la riceve:

if (event.data.type === "PEGASO_COLLECT_COURSE_MATERIALS_REQUEST") {
  const operationId = /* normalizzazione */;

  if (!operationId) return;

  if (handledExportOperationIds.has(operationId)) {
    return;
  }

  rememberHandledExportOperation(operationId);

  void collectCourseMaterials(format, operationId).finally(() => {
    // log conclusivo
  });

  return;
}

Riferimento: content.js L287–L311.

Notiamo che la deduplicazione compare anche qui.

Perché duplicarla in due layer?

Perché i due boundary hanno responsabilità differenti.

Il bridge protegge il passaggio:

extension runtime → MAIN world

content.js protegge invece il vero side effect:

messaggio MAIN → collectCourseMaterials()

È un esempio di defence in depth applicata all'affidabilità, non soltanto alla sicurezza.

19. void collectCourseMaterials(...): perché non viene fatto await?

Questa riga è interessante:

void collectCourseMaterials(format, operationId).finally(...);

L'handler del messaggio non aspetta che l'intera raccolta termini.

La raccolta può durare molto.

Il messaggio iniziale ha già svolto il suo compito:

far partire il workflow.

Da quel momento gli aggiornamenti viaggeranno come eventi separati.

Questa è una distinzione fondamentale:

request/response breve
        ≠
workflow asincrono lungo

Tentare di tenere aperta una singola risposta per tutta la durata della raccolta renderebbe il sistema più fragile e accoppiato.

PlumePilot usa invece:

COMMAND: avvia
EVENT: stato aggiornato
EVENT: stato aggiornato
EVENT: completato

Il modello assomiglia a quello che in un backend potresti usare per un job asincrono:

POST /exports
→ 202 Accepted + jobId

GET /jobs/:id
oppure eventi push

20. Step 7 — Gli aggiornamenti risalgono la catena

Durante la raccolta content.js pubblica aggiornamenti:

window.postMessage(
  {
    type: "PEGASO_EXPORT_COLLECTION_STATUS",
    operationId,
    message,
  },
  "*",
);

Riferimento: content.js L2388–L2401.

Il bridge li riceve e li converte in messaggi per il background:

chrome.runtime.sendMessage({
  type: "PEGASO_UPDATE_OPERATION",
  operationId,
  patch: { message: event.data.message },
});

Riferimento: bridge.js L584–L588.

Il background aggiorna quindi lo stato centrale dell'operazione.

Possiamo leggere il flusso come:

content.js
   │
   │ EVENT status
   ▼
bridge.js
   │
   │ command/update
   ▼
background
   │
   ▼
stato operazione

Il popup può essere chiuso.

La raccolta continua comunque.

Quando il popup verrà riaperto, potrà ricostruire la UI a partire dallo stato dell'operazione.

Questo è un risultato architetturale importante:

La UI non possiede il job. Osserva il job.

21. Step 8 — La raccolta termina con un evento

Quando i dati sono pronti, il MAIN world pubblica un evento del tipo:

PEGASO_COURSE_MATERIALS_COLLECTED

Il bridge controlla nuovamente l'operationId e utilizza un secondo set di deduplicazione:

if (terminalExportOperationIds.has(operationId)) {
  return;
}

rememberExportOperation(
  terminalExportOperationIds,
  operationId,
);

Poi invia al background:

chrome.runtime.sendMessage({
  type: "PEGASO_OPEN_EXPORT_BUILDER",
  format: event.data.format,
  operationId,
  payload: event.data.payload,
});

Riferimento: bridge.js L550–L570.

Perché un secondo concetto di "già visto"?

Perché un evento terminale è diverso dal comando iniziale.

Vogliamo evitare, ad esempio, che due notifiche di completamento aprano due builder.

Quindi il workflow possiede almeno due momenti da proteggere:

START      → non partire due volte
COMPLETE   → non finalizzare due volte

22. Step 9 — Il background apre il builder una volta sola

Anche il background effettua una propria verifica:

if (
  operation.phase === "building" ||
  operation.jobKey ||
  Number.isInteger(operation.builderTabId)
) {
  return {
    accepted: true,
    duplicate: true,
    operation,
  };
}

Riferimento: background.js L784–L850.

Poi genera un nuovo identificatore:

const jobId = crypto.randomUUID();

salva il payload nello storage:

const storageKey = `pegasoExportJob:${jobId}`;

await storageSet({
  [storageKey]: {
    ...message.payload,
    format,
    operationId: operation.id,
    courseTabId: operation.sourceTabId,
  },
});

ed apre una nuova pagina dell'estensione:

chrome.tabs.create({
  url: chrome.runtime.getURL(`${builderPage}?job=${jobId}`),
});

Questa parte è molto elegante dal punto di vista dei boundary.

Il payload potenzialmente grande non viene infilato nell'URL.

L'URL contiene soltanto un riferimento:

?job=<jobId>

La pagina builder recupererà il contenuto dallo storage.

Questo assomiglia al pattern:

identificatore piccolo → lookup di stato grande

che incontriamo continuamente lato backend.

23. Il workflow completo dell'export

Mettiamo tutto insieme.

sequenceDiagram
    participant P as popup.js
    participant BG as background.js
    participant BR as bridge.js
    participant C as content.js (MAIN)
    participant S as storage
    participant BU as materials-builder

    P->>BG: runtime.sendMessage(START_EXPORT)
    BG->>BG: acquire() + operationId
    BG->>BR: tabs.sendMessage(COLLECT_MATERIALS, operationId)
    BR->>BR: deduplica command
    BR->>C: window.postMessage(COLLECT_REQUEST)
    BR-->>BG: accepted
    BG-->>P: operation accepted

    C->>C: collectCourseMaterials()
    C->>BR: EXPORT_COLLECTION_STATUS
    BR->>BG: UPDATE_OPERATION

    C->>BR: COURSE_MATERIALS_COLLECTED
    BR->>BR: deduplica terminal event
    BR->>BG: OPEN_EXPORT_BUILDER
    BG->>BG: verifica duplicate finalization
    BG->>S: salva payload con jobId
    BG->>BU: apre builder?job=...
    BU->>S: legge job

Guardandolo così, è evidente che non stiamo più parlando di "uno script che clicca dei bottoni".

Stiamo osservando un piccolo sistema event-driven.

Parte IV — Affidabilità del protocollo

24. accepted non significa completed

Molte risposte di PlumePilot hanno questa forma:

{
  accepted: true
}

È importante interpretarla correttamente.

Per esempio, quando il bridge risponde:

sendResponse({ accepted: true, duplicate: false });

non sta dicendo:

"Le dispense sono pronte."

Sta dicendo:

"Ho accettato la richiesta e il workflow può proseguire."

Questa distinzione è cruciale nei sistemi asincroni.

accepted ≠ completed

Un backend potrebbe esprimerla tramite HTTP 202 Accepted.

PlumePilot la esprime tramite il proprio protocollo applicativo.

25. Tre classi di messaggi

Per studiare il progetto può essere utile classificare mentalmente i messaggi in tre gruppi.

A. Query

Chiedono informazioni.

PEGASO_GET_OPERATION
PEGASO_COURSE_PROGRESS_STATUS_REQUEST
PEGASO_CHAPTER_LIMIT_STATUS_REQUEST

B. Command

Chiedono di fare qualcosa.

PEGASO_START_EXPORT
PEGASO_CANCEL_EXPORT
PEGASO_FIND_FIRST_INCOMPLETE_COMMAND

C. Event

Comunicano qualcosa che è successo.

PEGASO_COURSE_PROGRESS_STATUS
PEGASO_COURSE_MATERIALS_COLLECTED
PEGASO_EXPORT_COLLECTION_FAILED

Il codice non impone formalmente questa tassonomia, ma usarla durante la lettura aiuta moltissimo.

Quando incontri un nuovo message.type, chiediti:

È una query?
È un command?
È un event?

Quasi sempre capirai subito chi dovrebbe produrlo e chi dovrebbe consumarlo.

26. Fire-and-forget e request/response

Non tutti i messaggi richiedono una risposta.

Request/response

chrome.runtime.sendMessage(message, (response) => {
  // la risposta è importante
});

Fire-and-forget

chrome.runtime.sendMessage({
  type: "PEGASO_UPDATE_OPERATION",
  operationId,
  patch: { message },
});

Qui il mittente comunica un aggiornamento ma non ha necessariamente bisogno di bloccare il proprio flusso in attesa di una risposta.

Questo riduce l'accoppiamento, ma cambia il modo in cui dobbiamo gestire gli errori.

Se nessuno attende una conferma, il sistema deve essere progettato in modo che un fallimento non lasci uno stato ambiguo o invisibile.

Non esiste una scelta universalmente migliore.

La domanda corretta è:

Il mittente ha bisogno di sapere che il destinatario ha completato il lavoro, oppure gli basta aver pubblicato l'informazione?

27. Errori di trasporto ed errori applicativi

PlumePilot distingue implicitamente due famiglie di errore.

Errore del canale

Per esempio:

chrome.runtime.lastError

Può significare che il destinatario non esiste più, la tab è stata chiusa, il content script non è disponibile, ecc.

Errore applicativo

Il messaggio è arrivato correttamente, ma l'azione viene rifiutata:

{
  accepted: false,
  reason: "Scheda del corso non disponibile."
}

Questa distinzione è molto simile a:

network / transport error
        ≠
HTTP 4xx / domain error

in un sistema web.

Entrambi possono impedire l'operazione, ma hanno cause e strategie di recupero differenti.

28. Perché runtime.lastError viene controllato spesso

Considera questo pattern:

chrome.tabs.sendMessage(tabId, message, (response) => {
  if (chrome.runtime.lastError) {
    // gestione errore
    return;
  }

  // usa response
});

Le API callback-style di Chrome comunicano diversi errori asincroni tramite chrome.runtime.lastError.

Se ignorassimo questo valore potremmo interpretare:

response === undefined

come una risposta applicativa valida, quando in realtà il messaggio non è mai arrivato al destinatario.

La wrapper runtimeMessage() che abbiamo visto prima serve proprio a trasformare questa peculiarità dell'API browser in un modello più facile da usare nel resto dell'applicazione.

29. Messaggi serializzabili

Quando passiamo un oggetto attraverso il sistema di messaging non stiamo condividendo lo stesso riferimento JavaScript.

Concettualmente dobbiamo trattare il messaggio come dati serializzabili.

Questo significa che è una cattiva idea immaginare di poter inviare direttamente:

{
  callback: () => doSomething(),
  domNode: document.querySelector("video")
}

come se il destinatario condividesse lo stesso heap.

Un messaggio dovrebbe contenere dati come:

{
  type: "PEGASO_UPDATE_OPERATION",
  operationId: "...",
  patch: {
    phase: "building",
    message: "Preparazione in corso…"
  }
}

Questa limitazione, apparentemente scomoda, ha anche un vantaggio:

Ci costringe a rendere espliciti i contratti tra componenti.

Parte V — window.postMessage() e il trust boundary

30. Condividere window non significa condividere fiducia

content.js e bridge.js comunicano con:

window.postMessage(...)

Gli handler spesso iniziano con:

if (event.source !== window || !event.data) return;

Questo controllo assicura che il messaggio osservato provenga dallo stesso oggetto window, non per esempio da un'altra finestra che possiede un riferimento.

Ma è importante non interpretarlo come autenticazione crittografica.

Il codice JavaScript della stessa pagina può usare anch'esso window.postMessage().

Per questo il boundary MAIN/ISOLATED va trattato come un posto in cui:

• non fidarsi ciecamente dei payload;
• limitare i tipi accettati;
• controllare identificatori e tipi;
• evitare di spostare segreti inutilmente;
• normalizzare le informazioni prima di passarle al runtime privilegiato.

PlumePilot lo fa in diversi punti attraverso funzioni come:

safeText(...)
exportOperationId(...)
Number.isFinite(...)
Array.isArray(...)

Lezione generale

Un bridge dovrebbe essere stretto.

Meglio:

5 messaggi espliciti e validati

che:

"esegui arbitrariamente quello che mi manda l'altro lato"

Questo principio vale per browser extension, iframe, worker, plugin system e API backend.

31. Perché usare "*" come targetOrigin qui non equivale a "mandare il dato su Internet"

Una riga come:

window.postMessage(message, "*");

può sembrare allarmante se la leggiamo senza contesto.

"*" significa che il mittente non limita il target origin del destinatario del messaggio.

Non significa però che il browser trasmetta automaticamente quel payload a qualunque sito su Internet.

Nel nostro caso il target è lo stesso window della pagina.

Resta comunque buona pratica progettare i payload come se il canale fosse osservabile dal codice che vive nella pagina e quindi non usarlo come contenitore di segreti.

Quando una applicazione usa postMessage tra finestre di origini differenti, la verifica di origin diventa ancora più importante.

Parte VI — Concorrenza nascosta nei messaggi

32. Due messaggi possono essere corretti e produrre comunque un bug

Supponiamo di avere:

A: START_EXPORT
B: CANCEL_EXPORT

Entrambi sono validi.

Ma cosa succede se arrivano quasi contemporaneamente?

Oppure:

A: STATUS 40%
B: COMPLETE
C: STATUS 50%  ← arrivato in ritardo

Il problema non è il contenuto di un singolo messaggio.

È l'ordine temporale.

Qui nasce la concorrenza.

Ed è uno dei motivi per cui PlumePilot possiede:

• operationId;
• fasi dell'operazione;
• set di deduplicazione;
• funzioni serializzate nel background;
• controlli sugli eventi terminali.

Nel capitolo dedicato all'asincronia studieremo meglio le race condition.

Per ora basta una regola:

In un sistema a messaggi, il tempo e l'ordine diventano parte del problema.

33. Lo stato terminale è speciale

Guarda questo controllo nel bridge:

if (terminalExportOperationIds.has(operationId)) {
  return;
}

Perché separare gli eventi terminali?

Perché una volta che un workflow è terminato, eventi duplicati o tardivi non dovrebbero normalmente riaprirlo.

Possiamo pensare al ciclo di vita così:

idle
  ↓
collecting
  ↓
building
  ↓
completed / released

Un messaggio ricevuto fuori fase potrebbe essere valido dal punto di vista sintattico ma non valido dal punto di vista temporale.

Questa è già una piccola anticipazione delle state machine.

Parte VII — Startup e sincronizzazione

34. Un listener può nascere troppo tardi

C'è una riga in content.js particolarmente istruttiva:

// bridge.js may have sent its startup state before this document-idle
// listener existed. Request an explicit synchronization after subscribing.
window.postMessage({ type: "PEGASO_AUTONEXT_STATE_REQUEST" }, "*");

Riferimento: content.js L557–L559.

Questa piccola soluzione racconta una classe intera di bug asincroni.

Ricordiamo dal manifest:

bridge.js  → document_start
content.js → document_idle

Quindi può verificarsi:

bridge caricato
    ↓
invia stato
    ↓
content.js non ha ancora registrato il listener
    ↓
messaggio perso

Un postMessage non è automaticamente una coda persistente.

Se nessun listener utile è presente in quel momento, il messaggio non verrà recuperato magicamente più tardi.

La soluzione è semplice e robusta:

1. content.js registra il listener
2. content.js chiede esplicitamente lo stato corrente
3. bridge.js lo ripubblica

Questo pattern si chiama spesso handshake o explicit synchronization.

Concetto importante

Gli eventi sono ottimi per dire:

"qualcosa è cambiato"

ma un nuovo subscriber ha spesso bisogno anche di poter chiedere:

"qual è lo stato adesso?"

Per questo molti sistemi reali combinano:

snapshot + events

invece di affidarsi esclusivamente a uno dei due.

È esattamente ciò che abbiamo visto anche nel progresso del corso.

35. Snapshot + eventi: un pattern ricorrente

Il modello compare più volte:

QUERY
  ↓
stato corrente

EVENT
  ↓
aggiornamenti futuri

È una combinazione potente perché risolve due esigenze diverse.

Snapshot

Serve quando un componente nasce o viene riaperto.

"Dimmi dove siamo adesso."

Eventi

Servono dopo la sincronizzazione iniziale.

"Avvisami quando cambia qualcosa."

Da backend developer puoi confrontarlo con:

GET /resource
+
WebSocket / SSE per gli update

oppure con:

query iniziale
+
subscription

Il meccanismo tecnico è diverso, ma il problema architetturale è lo stesso.

Parte VIII — Come leggere il messaging di PlumePilot

36. Metodo pratico di reverse engineering

Quando incontri un message.type nel repository, puoi ricostruirne il percorso in quattro passi.

1. Trova chi lo produce

Cerca:

{ type: "NOME_MESSAGGIO" }

Domanda:

chi lo invia?

2. Trova chi lo consuma

Cerca:

message?.type === "NOME_MESSAGGIO"

o:

event.data.type === "NOME_MESSAGGIO"

Domanda:

chi lo riceve?

3. Identifica il canale

Guarda se il produttore usa:

runtime.sendMessage
 tabs.sendMessage
window.postMessage

Questo ti dice quale boundary viene attraversato.

4. Cerca la risposta o l'evento successivo

Per esempio:

REQUEST → STATUS
START   → UPDATE → COMPLETE

A questo punto hai ricostruito il protocollo.

Questo metodo è utile non soltanto per PlumePilot.

È un modo generale per comprendere sistemi event-driven che non conosci.

37. Una tabella dei boundary principali

Questa tabella è quasi una mappa delle dipendenze runtime di PlumePilot.

Parte IX — Cosa avremmo potuto fare diversamente?

38. Un unico bus di messaggi?

Potremmo immaginare di costruire una astrazione unica:

bus.send("START_EXPORT", payload);

che nasconda completamente se sotto usa:

runtime.sendMessage
tabs.sendMessage
postMessage

Vantaggio

Il codice chiamante sarebbe più uniforme.

Svantaggio

Rischieremmo di nascondere informazioni architetturali importanti:

Dove sta andando il messaggio?
Quale boundary attraversa?
Quale runtime lo riceve?

Nel caso di PlumePilot, mantenere una certa visibilità del meccanismo sottostante è spesso utile proprio perché i contesti hanno capacità diverse.

Una astrazione migliore potrebbe quindi non essere:

"nascondi ogni differenza"

ma:

"centralizza error handling e contratti mantenendo esplicita la destinazione"

È una distinzione architetturale importante.

39. Un registro centralizzato dei message type?

Attualmente molti nomi dei messaggi sono stringhe distribuite nel codice:

"PEGASO_START_EXPORT"
"PEGASO_UPDATE_OPERATION"
"PEGASO_COURSE_PROGRESS_STATUS"

Una possibile evoluzione architetturale sarebbe centralizzarli:

const Messages = Object.freeze({
  START_EXPORT: "PEGASO_START_EXPORT",
  UPDATE_OPERATION: "PEGASO_UPDATE_OPERATION",
  COURSE_PROGRESS_STATUS: "PEGASO_COURSE_PROGRESS_STATUS",
});

oppure, in TypeScript, definire anche i payload associati.

Cosa guadagneremmo?

• meno typo;
• refactoring più semplice;
• contratti più visibili;
• possibilità di type checking.

Cosa costerebbe?

• ulteriore infrastruttura;
• necessità di rendere disponibile il modulo in più execution context;
• beneficio limitato per messaggi molto semplici.

Non significa che l'implementazione attuale sia sbagliata.

È il tipo di trade-off che discuteremo nell'ultimo capitolo: cosa rifaremmo diversamente dopo aver visto crescere il progetto.

40. Un protocollo versionato?

In un singolo pacchetto di estensione tutti i componenti vengono normalmente aggiornati insieme.

Per questo PlumePilot non ha bisogno di qualcosa come:

protocolVersion: 3

in ogni messaggio.

Ma immagina un sistema in cui mittente e destinatario possano essere aggiornati indipendentemente.

A quel punto il contratto di messaging diventerebbe una vera API da versionare.

Questa osservazione ci aiuta a capire una cosa:

La complessità necessaria dipende anche dal modo in cui i componenti vengono distribuiti.

PlumePilot può permettersi un protocollo interno relativamente leggero perché i componenti appartengono alla stessa release.

Parte X — Collegamenti con il backend

41. Un vocabolario comune

Molti concetti di questo capitolo hanno equivalenti familiari lato server.

Le analogie non sono equivalenze perfette.

Un browser non è un cluster distribuito e postMessage non è Kafka.

Ma i problemi logici sono della stessa famiglia:

• componenti separati;
• messaggi serializzabili;
• delivery asincrona;
• errori parziali;
• ordine temporale;
• correlazione;
• duplicati;
• stato non condiviso.

Per questo studiare bene l'architettura di un'estensione è sorprendentemente utile anche fuori dal browser.

Parte XI — Piccoli esercizi

42. Esercizio 1 — Scegli il canale

Immagina di dover implementare queste funzioni.

A. Il popup vuole chiedere al background se esiste già un export attivo

Quale useresti?

runtime.sendMessage

Perché il destinatario è il coordinatore dell'estensione.

B. Il background vuole dire alla tab 37 di fermare la raccolta

tabs.sendMessage(37, ...)

Perché dobbiamo indirizzare un content script specifico.

C. content.js nel MAIN world vuole chiedere al bridge di leggere una preferenza dallo storage

window.postMessage

per attraversare MAIN → ISOLATED; sarà poi il bridge a usare le WebExtension API appropriate.

43. Esercizio 2 — Trova il bug

Considera:

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  fetchSomething().then((result) => {
    sendResponse(result);
  });
});

Cosa manca nel modello callback-style usato da PlumePilot?

La risposta:

return true;

per mantenere disponibile il canale di risposta asincrono.

44. Esercizio 3 — Query o command?

Classifica:

PEGASO_GET_OPERATION

→ query.

PEGASO_CANCEL_EXPORT

→ command.

PEGASO_EXPORT_COLLECTION_FAILED

→ event.

Questa classificazione non è richiesta dal browser.

Serve a noi per ragionare meglio sul sistema.

45. Esercizio 4 — Perché serve l'operationId?

Immagina due export quasi contemporanei:

Export A
Export B

poi ricevi:

"raccolta completata"

Senza un correlation ID non sai a quale dei due appartiene.

Con:

operationId: A

il problema diventa deterministico.

46. Esercizio 5 — Evento perso allo startup

Supponiamo:

bridge.js: document_start
content.js: document_idle

Il bridge pubblica lo stato una sola volta appena parte.

Perché il content.js potrebbe non riceverlo?

Perché il listener potrebbe non essere ancora stato registrato.

Qual è una soluzione?

subscribe → request current snapshot

che è proprio ciò che fa PEGASO_AUTONEXT_STATE_REQUEST.

Parte XII — Concetti da portarsi dietro

47. Message passing

Comunicare attraverso messaggi invece di condividere direttamente funzioni e memoria.

48. Protocollo

L'insieme delle forme, dei nomi e delle aspettative che permettono a mittente e destinatario di capirsi.

In PlumePilot il protocollo è composto in gran parte da oggetti con type e payload associati.

49. Dispatcher

Componente che riceve messaggi e li instrada verso l'handler corretto.

Il blocco runtime.onMessage del background ne è un esempio.

50. Command

Messaggio che esprime l'intenzione di eseguire un'azione.

51. Event

Messaggio che descrive un fatto già avvenuto.

52. Query

Messaggio che richiede informazioni senza voler rappresentare un cambiamento di stato come scopo principale.

53. Correlation ID

Identificatore che permette di collegare più messaggi allo stesso workflow.

operationId è il nostro esempio principale.

54. Deduplicazione

Riconoscere e ignorare la ripetizione di una richiesta o di un evento già processato.

55. Eventual consistency

Situazione in cui componenti differenti possono avere temporaneamente snapshot non identici, ma convergono tramite aggiornamenti successivi.

56. Fire-and-forget

Invio di un messaggio senza aspettare una risposta applicativa prima di continuare.

57. Request/response

Interazione in cui il mittente ha bisogno di una risposta correlata alla richiesta.

58. Handshake / explicit synchronization

Procedura con cui un componente appena inizializzato chiede esplicitamente lo stato corrente per evitare di dipendere da eventi pubblicati prima che fosse pronto ad ascoltarli.

59. Boundary validation

Validazione e normalizzazione dei dati nel punto in cui attraversano un confine tra componenti o trust domain.

Parte XIII — Approfondimenti

60. Documentazione primaria consigliata

Chrome Extensions — Message passing

https://developer.chrome.com/docs/extensions/develop/concepts/messaging

Da leggere per:

• runtime.sendMessage();
• tabs.sendMessage();
• one-time requests;
• connessioni persistenti.

Chrome Extensions — Tabs API

https://developer.chrome.com/docs/extensions/reference/api/tabs

Utile soprattutto per capire perché tabs.sendMessage() possiede un tabId e può essere indirizzato a uno specifico frame/document.

MDN — runtime.sendMessage()

https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage

MDN — runtime.onMessage

https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage

Particolarmente importante per comprendere:

• sendResponse();
• risposta sincrona;
• risposta asincrona;
• return true;
• Promise e differenze storiche di compatibilità.

MDN — Window.postMessage()

https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage

Da leggere insieme alla sezione sulla sicurezza e sul controllo dell'origine quando si comunica tra finestre o origini differenti.

Chrome — Execution worlds

https://developer.chrome.com/docs/extensions/reference/api/scripting#type-ExecutionWorld

Serve a ricollegare questo capitolo alla distinzione MAIN / ISOLATED studiata nel Capitolo 1.

61. Cosa abbiamo imparato davvero

A prima vista questo capitolo parlava di API come:

sendMessage()
postMessage()
onMessage

Ma il punto più importante è più generale.

PlumePilot ci mostra che quando un'applicazione viene suddivisa in contesti con lifetime e privilegi differenti, la comunicazione diventa parte dell'architettura.

Non possiamo più ragionare soltanto in termini di:

funzione A chiama funzione B

Dobbiamo ragionare in termini di:

chi produce il messaggio?
chi lo riceve?
attraverso quale boundary?
la consegna richiede risposta?
la risposta può arrivare più tardi?
come correlare gli aggiornamenti?
cosa accade se il messaggio arriva due volte?
cosa accade se arriva fuori ordine?
cosa accade se il subscriber non esiste ancora?

Queste domande ci porteranno naturalmente ai prossimi argomenti.

Nel Capitolo 3 usciremo dall'infrastruttura dell'estensione e guarderemo il territorio più instabile in cui PlumePilot deve lavorare:

il DOM di una applicazione web che non controlliamo.

Vedremo perché leggere un elemento HTML è facile, mentre costruire automazioni affidabili sopra una UI dinamica è tutta un'altra storia.

03 — DOM e pagine dinamiche

Lavorare in una UI che non controlliamo

Nel capitolo precedente abbiamo seguito i messaggi mentre attraversavano popup, background, bridge e MAIN world.

Ora arriviamo al punto in cui PlumePilot deve fare qualcosa di più difficile: capire una pagina web costruita da qualcun altro mentre quella pagina continua a cambiare sotto i suoi piedi.

È facile descrivere un content script dicendo:

legge il DOM e clicca alcuni elementi.

Tecnicamente è vero.

Ma è una descrizione quasi inutile.

Il vero problema non è trovare un elemento una volta.

Il vero problema è rispondere a domande come:

• l'elemento esiste già oppure verrà renderizzato tra poco?
• quello che vedo nel DOM rappresenta davvero lo stato della piattaforma?
• il nodo che ho salvato cinque secondi fa esiste ancora?
• un accordion chiuso significa che il capitolo non esiste, oppure soltanto che non è renderizzato?
• due capitoli con lo stesso numero sono lo stesso capitolo?
• se faccio .click(), quando posso considerare concluso l'effetto del click?
• se la tab è nascosta, i timeout hanno ancora lo stesso significato?
• se il frontend ricostruisce la sidebar, posso continuare a usare il vecchio riferimento DOM?

Queste non sono domande specifiche di PlumePilot.

Sono problemi tipici di qualunque software che debba integrarsi con una UI dinamica non controllata: browser extension, userscript, test end-to-end, automazione, accessibility tooling, web scraping interattivo o integrazioni con applicazioni legacy.

In questo capitolo useremo PlumePilot per imparare una regola fondamentale:

Il DOM è una rappresentazione temporanea dello stato dell'applicazione, non necessariamente lo stato dell'applicazione stesso.

Parte I — Il DOM non è un database

1. Che cos'è davvero il DOM?

Quando il browser interpreta HTML costruisce una struttura ad albero di oggetti JavaScript.

Per esempio:

<div class="course">
  <div class="chapter">
    <span>1 - Introduzione</span>
  </div>
</div>

può essere immaginato come:

Document
└── div.course
    └── div.chapter
        └── span
            └── "1 - Introduzione"

JavaScript può attraversare e modificare quell'albero:

document.querySelector(".chapter");

Il risultato è un oggetto Element che rappresenta quel nodo in quel momento.

Questa ultima parte è importante.

In un sito moderno la pagina può fare:

stato applicativo cambia
        ↓
frontend ricalcola la UI
        ↓
vecchi nodi rimossi
        ↓
nuovi nodi creati

Visivamente l'utente può vedere ancora:

1 - Introduzione

ma JavaScript potrebbe trovarsi davanti a un oggetto completamente diverso.

Il testo è lo stesso.

L'identità DOM no.

2. Un riferimento DOM non è un'identità logica

Supponiamo di fare:

const row = document.querySelector(".lesson");

Dopo qualche secondo la piattaforma aggiorna la sidebar e ricrea quel ramo del DOM.

Ora possono esistere due realtà:

variabile row ───────► vecchio nodo, ormai staccato

DOM corrente ────────► nuovo nodo che rappresenta la stessa lezione

La variabile continua a contenere un oggetto valido.

Ma quell'oggetto potrebbe non appartenere più al documento corrente.

Questo tipo di riferimento viene spesso chiamato stale reference: un riferimento che era corretto quando è stato ottenuto, ma non rappresenta più il componente attuale della UI.

È una distinzione che incontreremo ripetutamente:

DOM identity       ≠       domain identity

Per PlumePilot:

"questo specifico <div>"    ≠    "questa specifica lezione"

La lezione è un concetto del dominio.

Il <div> è soltanto una delle sue rappresentazioni temporanee.

3. Primo esempio reale: lessons()

In content.js PlumePilot individua le righe delle lezioni così:

function lessons() {
  return [...document.querySelectorAll("div.border-t")].filter((x) =>
    x.querySelector(":scope > div.cursor-pointer"),
  );
}

Riferimento reale: content.js L647-L651.

Notiamo già una scelta importante.

La funzione non conserva una lista globale del tipo:

const allLessons = document.querySelectorAll(...);

E poi la riutilizza per sempre.

Ogni chiamata a lessons() riesegue la query sul DOM corrente.

Questo è particolarmente appropriato in una pagina dinamica.

4. querySelectorAll() restituisce uno snapshot statico

Secondo la documentazione DOM, querySelectorAll() restituisce una NodeList statica, non live.

In altre parole:

const rows = document.querySelectorAll(".lesson");

fotografa l'insieme dei nodi che corrispondono in quel momento.

Se successivamente il DOM cambia, rows non si aggiorna automaticamente con i nuovi elementi.

PlumePilot converte subito la NodeList in un array:

[...document.querySelectorAll(...)]

Da quel momento è ancora più chiaramente uno snapshot.

Possiamo immaginarlo così:

t0
DOM: A B C
querySelectorAll() → [A, B, C]


t1
DOM: A D C
array precedente  → [A, B, C]
nuova query        → [A, D, C]

Il vecchio array non acquisisce magicamente D.

E B può perfino essere stato rimosso dalla pagina.

Per questo funzioni come:

lessons()
chapters()
sections()

sono più interessanti di quanto sembrino.

Non sono semplicemente utility.

Sono lettori dello stato visibile corrente.

Approfondimento

MDN descrive querySelectorAll() come una query che restituisce una NodeList non live:

https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll

Parte II — I selettori sono contratti impliciti

5. Un selettore CSS può diventare una dipendenza software

Consideriamo ancora:

document.querySelectorAll("div.border-t")

Quella classe non è stata definita da PlumePilot.

Appartiene alla piattaforma.

Quindi la funzione dipende implicitamente da un contratto esterno:

la piattaforma continuerà a rappresentare le righe delle lezioni
con una struttura compatibile con questo selettore

Questo contratto non è formalizzato in una API.

Nessuno promette a PlumePilot che .border-t esisterà anche domani.

Per questo l'integrazione DOM è intrinsecamente più fragile di una API versionata.

6. Selettore sintattico vs selettore semantico

Immaginiamo due possibilità.

Selettore molto strutturale

div > div:nth-child(3) > div:nth-child(2) > span

Selettore più semantico

[aria-label="lesson-progress"]

Il primo dipende fortemente dal layout.

Il secondo dipende da un significato.

Idealmente preferiremmo sempre elementi con identificatori semantici stabili:

data-* dedicati
aria-label
role
id documentati
URL
identificatori di dominio

Ma quando integriamo una pagina che non controlliamo, spesso questi dati non esistono.

PlumePilot deve quindi combinare diversi segnali:

classi CSS
struttura relativa
contenuto testuale
URL
icone
stato visuale
API

Non esiste un selettore universalmente perfetto.

La domanda corretta diventa:

Quale combinazione di segnali è abbastanza stabile per questo compito?

7. :scope riduce le ambiguità

In lessons() troviamo:

x.querySelector(":scope > div.cursor-pointer")

>, in CSS, significa figlio diretto.

:scope indica l'elemento sul quale stiamo eseguendo la query.

Quindi non stiamo chiedendo:

esiste da qualche parte sotto questa riga un elemento cliccabile?

Stiamo chiedendo:

il figlio diretto previsto dalla struttura della riga è cliccabile?

La differenza sembra piccola, ma riduce i falsi positivi.

Questo:

row
└── wrapper.cursor-pointer

corrisponde.

Questo:

row
└── qualcos'altro
    └── qualche widget interno
        └── .cursor-pointer

non basta.

È un esempio di selettore che codifica una piccola aspettativa strutturale, non soltanto una classe.

8. closest() legge il contesto dell'elemento

PlumePilot utilizza spesso anche closest().

Per esempio, nell'identificazione di capitoli Mercatorum:

const clickable =
  span.closest("div.cursor-pointer.relative.align-middle") ||
  span.closest("div.cursor-pointer");

Riferimento: content.js L1180-L1198.

closest() parte dal nodo corrente e risale verso gli antenati fino a trovare il primo match.

È utile quando conosciamo un elemento interno significativo ma l'azione reale appartiene a un contenitore superiore.

Mentalmente:

clickable div
└── wrapper
    └── span con "3 - Titolo"
         ▲
         │
      partiamo qui

closest() ci permette di recuperare il componente interattivo che contiene quello span.

Documentazione:

https://developer.mozilla.org/en-US/docs/Web/API/Element/closest

Parte III — Una piattaforma, più strutture DOM

9. sections() è già un piccolo adapter multipiattaforma

Quando PlumePilot supportava soltanto una piattaforma, una certa struttura DOM poteva sembrare universale.

Con Pegaso, Mercatorum e San Raffaele, questa assunzione non regge più.

Guardiamo:

function sections() {
  const nativeSections = pegasoStyleSections();
  if (nativeSections.length) return nativeSections;

  const fallbackChapters = mercatorumChapterRows();
  if (!fallbackChapters.length) return [];

  return [{
    outer: document.documentElement,
    header: null,
    span: fallbackChapters[0].clickable,
    text: MERCATORUM_STATIC_SECTION,
    static: true,
  }];
}

Riferimento: content.js L1201-L1213.

Il resto dell'algoritmo vuole ragionare in termini di:

sections
  └── chapters
      └── activities

Ma non tutte le piattaforme espongono esattamente la stessa UI.

Invece di spargere continuamente condizioni come:

if (isMercatorum) ...
else if (isPegaso) ...

ovunque, sections() prova a restituire una forma concettuale comune.

Questo è un primo esempio di DOM adapter.

La pagina dice:

"io rappresento il corso così"

PlumePilot traduce:

"per il mio dominio, questa cosa è una section"

10. Normalizzare prima, ragionare dopo

Questa strategia è molto simile a ciò che faresti lato backend con provider differenti.

Immaginiamo:

Provider A → customer_id
Provider B → userCode
Provider C → account.id

L'application layer preferisce ricevere:

{
  customerId: ...
}

in tutti i casi.

Qui abbiamo lo stesso principio:

DOM Pegaso ───────┐
                  ├──► modello concettuale PlumePilot
DOM Mercatorum ───┘

Questa separazione diventerà ancora più importante quando parleremo dell'architettura che potremmo adottare se riscrivessimo PlumePilot oggi.

Parte IV — Il problema del tempo

11. document_idle non significa "applicazione pronta"

Nel manifest.json, content.js viene caricato con:

"run_at": "document_idle"

Potremmo interpretarlo ingenuamente così:

content.js parte
        ↓
la pagina è pronta

Ma document_idle riguarda il caricamento del documento dal punto di vista dell'estensione.

Non significa che tutti i dati asincroni dell'applicazione host siano già arrivati, né che ogni componente UI sia stato renderizzato.

Una Single Page Application può fare:

HTML iniziale disponibile
        ↓
content script avviato
        ↓
fetch applicativo
        ↓
risposta API
        ↓
render capitoli
        ↓
render lezione attiva

Quindi al tempo t0 questo può essere vero:

chapters().length === 0

mentre al tempo t0 + 800 ms:

chapters().length === 42

Nessuna delle due letture è "sbagliata".

Descrivono due momenti diversi.

12. Un bug reale: DOM inizialmente vuoto

Il changelog di PlumePilot conserva una regressione molto istruttiva.

Nella v2.14.5 venne corretto il comportamento della ricerca della prima attività incompleta dopo un reload:

• la struttura del corso veniva renderizzata asincronamente;
• l'algoritmo partiva prima che esistesse la riga della lezione attiva;
• un DOM inizialmente vuoto veniva interpretato come fallimento definitivo.

Riferimento storico: CHANGELOG.md L793-L799.

Il punto fondamentale è questo:

"non trovato ora"

non equivale necessariamente a:

"non esiste"

Può significare:

"non è ancora stato renderizzato"

Sono tre stati semanticamente diversi.

13. Il problema dei tre valori

Molti bug DOM nascono perché modelliamo implicitamente una condizione come booleana:

found / not found

quando la realtà è più simile a:

FOUND
NOT_READY_YET
DEFINITELY_MISSING

Questa distinzione è fondamentale nelle UI asincrone.

Se chapters() restituisce zero elementi durante lo startup, come facciamo a sapere se:

1. il corso non ha capitoli;
2. non siamo nella pagina giusta;
3. il frontend non ha ancora renderizzato i capitoli;
4. il selettore si è rotto dopo un aggiornamento della piattaforma?

Dal solo array vuoto non possiamo distinguerli.

Serve contesto temporale e applicativo.

Parte V — Aspettare una condizione, non un numero arbitrario

14. waitFor()

PlumePilot possiede una utility semplice ma centrale:

async function waitFor(fn, timeout = WAIT_MS) {
  let start = Date.now();

  while (Date.now() - start < timeout) {
    const x = fn();

    if (x) {
      return x;
    }

    await sleep(100);
  }

  return null;
}

La versione reale gestisce anche la visibilità della pagina; il cuore del pattern però è questo.

Riferimento: content.js L1577-L1609.

Invece di dire:

await sleep(2000);
const chapter = findChapter(...);

PlumePilot dice:

const chapter = await waitFor(() => findChapter(...));

La differenza concettuale è enorme.

15. Delay fisso vs attesa condizionale

Delay fisso

aspetta esattamente 2 secondi
        ↓
prova

Problemi:

la pagina è pronta dopo 100 ms  → hai perso 1.9 secondi
la pagina è pronta dopo 2.1 s   → fallisci comunque

Attesa condizionale

ogni 100 ms:
    la condizione è vera?
        sì → continua subito
        no → riprova fino al timeout

Ora il tempo massimo è una deadline, non la previsione esatta di quanto impiegherà la UI.

Questo è un pattern generale molto utile.

16. Polling

waitFor() implementa una forma di polling.

Il polling significa verificare periodicamente una condizione:

t0      check
        false

t0+100  check
        false

t0+200  check
        true
        ↓
        continua

Il polling viene spesso visto come meno elegante di un evento dedicato.

Ma quando integriamo una UI che non controlliamo, un evento affidabile può semplicemente non esistere.

In quel caso un polling:

• limitato nel tempo;
• con intervallo ragionevole;
• basato su una condizione precisa;

può essere una soluzione robusta.

17. Quando sarebbe preferibile un evento?

Se controllassimo la piattaforma potremmo avere qualcosa del tipo:

courseStore.on("chaptersLoaded", callback);

oppure:

window.dispatchEvent(new CustomEvent("course-ready"));

Ma PlumePilot non possiede quel contratto.

Deve inferire la readiness dall'esterno.

Quindi usa strumenti osservabili:

DOM
URL
video
API
MutationObserver
polling

Questa è una differenza fondamentale tra software che possiede lo stato e software che osserva lo stato di un altro sistema.

Parte VI — MutationObserver: sapere che qualcosa è cambiato

18. Perché una scansione iniziale non basta

Alla fine di content.js troviamo:

function scan() {
  document.querySelectorAll("video").forEach(attach);
  const activeRow = currentLesson();
  if (activeRow) rememberPlaybackLesson(activeRow);
  scheduleSessionConflictScan();

  if (!courseProgressState || courseProgressState.baselinePercent === null) {
    scheduleCourseProgressInitialization(250);
  }
}

new MutationObserver(scan).observe(document.documentElement, {
  childList: true,
  subtree: true,
});

scan();

Riferimento: content.js L7066-L7090.

La sequenza è:

1. scan iniziale
2. osserva mutazioni future
3. ogni volta che cambia l'albero → scan()

Questo risolve un problema essenziale.

Il video che ci interessa potrebbe non esistere ancora quando parte PlumePilot.

19. MutationObserver

MutationObserver è una API standard del browser per ricevere notifiche quando cambia il DOM.

Qui PlumePilot osserva:

{
  childList: true,
  subtree: true,
}

cioè:

childList → nodi aggiunti o rimossi
subtree   → non soltanto figli diretti, ma tutto il sottoalbero

Il target è:

document.documentElement

quindi praticamente l'intero documento.

MDN:

https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver

20. MutationObserver non dice necessariamente cosa significa il cambiamento

Questa distinzione è importante.

MutationObserver può dirci:

è stato aggiunto un nodo

ma non sa che quel nodo rappresenta:

"il nuovo player video della lezione 7"

Il significato lo deve ricostruire PlumePilot.

Per questo il callback non tenta di interpretare direttamente ogni singola mutation.

Fa semplicemente:

scan();

e scan() ricalcola le informazioni che interessano.

È una strategia molto comune:

mutation notification
        ↓
"qualcosa potrebbe essere cambiato"
        ↓
ricalcola una piccola vista dello stato

21. Observer come invalidation signal

Possiamo pensare al MutationObserver come a un segnale di invalidazione:

cache mentale:
"so quali video esistono"

DOM mutation
     ↓
questa conoscenza potrebbe non essere più valida
     ↓
scan()

È concettualmente simile a una cache invalidation.

L'observer non ci consegna necessariamente la nuova verità già pronta.

Ci dice che dobbiamo rileggerla.

Parte VII — Attaccarsi a elementi che possono nascere dopo

22. document.querySelectorAll("video").forEach(attach)

Una delle responsabilità di scan() è:

document.querySelectorAll("video").forEach(attach);

Questo pattern risolve il caso:

PlumePilot parte
    ↓
nessun <video>
    ↓
frontend carica la lezione
    ↓
crea <video>
    ↓
MutationObserver
    ↓
scan()
    ↓
attach(video)

Senza observer, il primo scan con zero video potrebbe essere l'ultimo.

23. Ma un observer globale può essere costoso

Osservare tutto:

document.documentElement

con:

subtree: true

significa ricevere notifiche per molte mutazioni potenzialmente irrilevanti.

In una UI complessa potrebbero cambiare:

• tooltip;
• contatori;
• animazioni;
• notifiche;
• menu;
• classi indirette;
• componenti non legati all'autoplay.

Per questo un observer dovrebbe idealmente avere callback poco costosi o meccanismi di debounce/coalescing.

Nel caso di PlumePilot scan() è relativamente mirato, ma il principio architetturale rimane:

Osservare un'area ampia è comodo, ma aumenta il numero di invalidazioni che dobbiamo saper assorbire.

24. Observer specifico vs observer generale

Potremmo immaginare due strategie.

Strategia A — generale

observe(document.documentElement, {
  childList: true,
  subtree: true,
});

Vantaggi:

• robusta rispetto a dove compare il nuovo componente;
• semplice da implementare;
• funziona anche se il frontend ricrea alberi interi.

Svantaggi:

• molte notifiche;
• il callback deve filtrare il rumore.

Strategia B — specifica

observe(sidebar, {
  childList: true,
  subtree: true,
});

Vantaggi:

• meno rumore;
• semantica più chiara.

Svantaggi:

• se sidebar viene sostituita interamente, stiamo osservando il vecchio nodo;
• prima dobbiamo essere sicuri che la sidebar esista.

In un DOM ostile o poco stabile, l'approccio più generale può essere pragmaticamente migliore.

Parte VIII — Il bug più interessante: un nodo può sparire mentre lo aspettiamo

25. Autoplay e accordion chiuso

Arriviamo a uno dei casi studio più importanti.

Una lezione termina.

PlumePilot deve:

1. confermare il completamento
2. trovare la lezione corrente
3. trovare quella successiva
4. aprirla

Sembra semplice.

Ma durante l'attesa la piattaforma può aggiornare la sidebar.

Oppure l'utente può chiudere l'accordion.

Il changelog della v2.35.1 ricorda esplicitamente:

miglioramento del recupero con accordion chiusi, handoff dagli Obiettivi e routing dei capitoli.

Riferimento: CHANGELOG.md L3-L10.

Il codice contiene una spiegazione ancora più interessante:

// Completion can update the sidebar or the user can close its accordion
// while we wait. Keep the identity so a detached row is never used for
// finding the next activity after the wait.
const completedLesson = playbackContext;

Riferimento: content.js L6680-L6683.

Queste tre righe descrivono un concetto architetturale molto importante.

26. Il problema del nodo staccato

Supponiamo che cur sia la riga corrente:

const cur = currentLesson();

Poi aspettiamo che la piattaforma confermi il completamento:

await waitForLessonCompletion(cur, video);

Durante l'attesa:

sidebar vecchia
└── row A   ← cur

può essere sostituita con:

sidebar nuova
└── row B   ← stessa lezione dal punto di vista del dominio

Ora cur continua a puntare a row A.

Ma row A non descrive più il DOM corrente.

Se cercassimo:

nextLesson(cur)

potremmo calcolare il successore partendo da una struttura ormai obsoleta.

27. Non conservare il nodo: conserva l'identità

PlumePilot introduce playbackContext:

playbackContext = {
  videoElement,
  courseCode: courseCodeFromUrl(),
  lessonNumber: lessonNumberFromUrl(),
  identity,
  name: lessonName(row),
  index,
};

Riferimento: content.js L663-L677.

Qui non memorizziamo soltanto il nodo.

Memorizziamo dati che ci permettono di ritrovare concettualmente la stessa lezione:

courseCode
lessonNumber
chapter identity
lesson name
index

Questa è una strategia fondamentale:

riferimento fragile
       ↓
estrai identità stabile
       ↓
quando serve, risolvi di nuovo l'identità sul DOM corrente

28. recoverPlaybackLesson()

La funzione di recupero rende il pattern esplicito:

async function recoverPlaybackLesson(videoElement) {
  const visible = currentLesson();

  if (visible) {
    rememberPlaybackLesson(visible, videoElement);
    return visible;
  }

  const context = playbackContext;

  // verifica che il contesto appartenga ancora allo stesso corso/modulo
  // ...

  if (!(await openChapter(context.identity))) return null;

  const row = await waitFor(() => playbackLessonRow(context));

  if (row) rememberPlaybackLesson(row, videoElement);
  return row;
}

Riferimento: content.js L691-L705.

Il ragionamento è:

la riga è ancora visibile?
    │
    ├── sì → usa la versione corrente
    │
    └── no
         ↓
    ho un'identità salvata?
         ↓
    riapri il capitolo
         ↓
    ritrova la riga nel DOM nuovo

Questo è molto più robusto di:

const current = currentLesson();
await somethingAsync();
useForever(current);

29. Pattern generale: resolve late

Potremmo chiamare questa strategia resolve late.

Invece di risolvere un riferimento una volta e trascinarlo per tutta un'operazione lunga:

resolve DOM node
      ↓
wait 5 seconds
      ↓
use old node

manteniamo un'identità e risolviamo il nodo vicino al momento dell'uso:

store logical identity
      ↓
wait
      ↓
resolve current DOM node
      ↓
use it

È simile a memorizzare un userId invece di un oggetto ORM che potrebbe essere stale dopo una transazione lunga.

Da backend developer

Pensa a:

const user = await repo.findById(id);
await longExternalOperation();
// assumere che user rappresenti ancora lo stato attuale

contro:

const userId = id;
await longExternalOperation();
const freshUser = await repo.findById(userId);

Non è esattamente lo stesso problema, ma il modello mentale è sorprendentemente simile.

Parte IX — Fare click non significa che l'azione sia finita

30. .click() è l'inizio di una transizione

In openSection() PlumePilot fa:

section.span.scrollIntoView({ block: "center", behavior: "instant" });
section.span.click();

Ma non ritorna immediatamente true.

Subito dopo verifica:

const opened = await waitFor(() => {
  section = getSection();
  return isOpen() && section ? section : null;
});

Riferimento: content.js L1668-L1705.

Quindi:

.click()
   ↓
richiesta di transizione
   ↓
frontend reagisce
   ↓
DOM cambia
   ↓
PlumePilot verifica il nuovo stato

Non:

.click() == operazione conclusa

31. Command + verification

Questo pattern può essere descritto come:

COMMAND
   ↓
WAIT
   ↓
VERIFY

Per esempio:

clicca capitolo
   ↓
attendi
   ↓
chevron-up esiste?

È concettualmente simile a sistemi distribuiti dove:

invia richiesta
   ↓
attendi convergenza
   ↓
leggi stato risultante

La UI è locale, ma la natura asincrona introduce una dinamica simile.

32. Perché non basta leggere subito dopo il click?

Questo codice è fragile:

chapter.span.click();
return isChapterOpen(identity);

Perché il click può innescare:

event handler
    ↓
aggiornamento di stato framework
    ↓
scheduling render
    ↓
DOM update

Il rendering non deve necessariamente essersi completato prima della riga JavaScript successiva.

PlumePilot quindi verifica il risultato in un intervallo temporale.

Parte X — Verificare sul DOM corrente

33. Nota il getSection() dentro il polling

Dentro openSection():

const getSection = () =>
  sections().find((section) => section.text === sectionText);

Poi, durante l'attesa:

section = getSection();

Perché non usare semplicemente l'oggetto section originale?

Perché il click potrebbe aver provocato una ricostruzione del DOM.

PlumePilot preferisce recuperare una versione fresca della section.

Ancora una volta:

identità: sectionText
rappresentazione corrente: getSection()

34. Il prefisso fresh nel codice non è casuale

In diverse parti del progetto compaiono variabili come:

fresh
freshModal
freshTest

Non è soltanto stile di naming.

Esprime una preoccupazione architetturale reale:

dopo un'operazione asincrona, verifica di nuovo il DOM invece di assumere che il vecchio nodo sia ancora autorevole.

Questa è una disciplina molto utile quando si lavora con UI dinamiche.

Parte XI — Accordion chiuso: assenza visuale ≠ assenza logica

35. Il problema della virtualizzazione locale

Molte UI ad accordion non mantengono necessariamente tutti i contenuti figli sempre renderizzati.

Quando un capitolo è chiuso possiamo avere:

Chapter header

Quando è aperto:

Chapter header
├── Video 1
├── Video 2
├── Test
└── Obiettivi

Quindi una query come:

find lesson row

può fallire non perché la lezione non esista, ma perché il contenitore che la rende visibile è chiuso.

Questo è un esempio di differenza tra:

logical state

e:

rendered state

36. openChapter() tratta l'apertura come una precondizione

PlumePilot verifica prima se il capitolo è aperto:

const isOpen = () => {
  const fresh = getChapter();
  if (!fresh) return false;

  const outer = getOuterChapter(fresh);
  return !!outer?.querySelector('[id*="chevron-up"]');
};

Se non lo è:

chapter.span.click();

Poi attende una nuova lettura:

const readOpenedChapter = () => (isOpen() ? getChapter() : null);
const opened = await waitFor(readOpenedChapter);

Riferimento: content.js L5502-L5561.

Il capitolo è quindi trattato come una risorsa che deve trovarsi nello stato:

OPEN

prima di poter effettuare certe query sui figli.

37. Precondition recovery

Questo pattern può essere generalizzato:

voglio eseguire X
      ↓
precondizione P è vera?
      │
      ├── sì → X
      │
      └── no → prova a ripristinare P
                    ↓
                verifica P
                    ↓
                    X

Per PlumePilot:

voglio trovare la lezione
      ↓
capitolo aperto?
      │
      ├── sì
      └── no → aprilo → verifica → continua

È una forma di self-healing locale.

Parte XII — Un elemento visibile può essere un segnale migliore di uno nascosto

38. Leggere la percentuale del corso

PlumePilot cerca la percentuale visuale con:

function readPegasoCoursePercentage() {
  const candidates = [...document.querySelectorAll("div.percent")]
    .filter((element) =>
      element.querySelector("circle.circular-progress") &&
      element.querySelector(".number-container"),
    )
    .map((element) => {
      const match = String(element.textContent || "")
        .trim()
        .match(/^(\d{1,3})%$/);

      const rect = element.getBoundingClientRect();

      return match && rect.width > 0 && rect.height > 0
        ? Math.max(0, Math.min(100, Number(match[1])))
        : null;
    })
    .filter((value) => value !== null);

  return candidates.length === 1 ? candidates[0] : null;
}

Riferimento: content.js L4347-L4362.

Questa funzione è didatticamente molto interessante.

39. Non prende semplicemente il primo .percent

Il codice non fa:

return document.querySelector(".percent").textContent;

Filtra invece i candidati usando più segnali:

classe .percent
+
contiene circular-progress
+
contiene number-container
+
testo esattamente NN%
+
dimensioni visibili

Poi impone una regola ulteriore:

return candidates.length === 1 ? candidates[0] : null;

Se esistono due candidati plausibili, PlumePilot preferisce non indovinare.

Questo è un principio molto importante.

40. Ambiguità esplicita > scelta arbitraria

Consideriamo:

0 candidati → non so
1 candidato → probabilmente corretto
2 candidati → ambiguo

Una strategia ingenua potrebbe fare:

return candidates[0];

Ma sarebbe una scelta arbitraria.

PlumePilot usa:

ambiguità → null

Il null non è sempre un fallimento.

Può rappresentare una decisione deliberata:

non possiedo abbastanza informazioni per affermare qualcosa con sicurezza.

Questa è una forma di fail-safe inference.

41. getBoundingClientRect() come filtro pragmatico

La funzione controlla:

const rect = element.getBoundingClientRect();
rect.width > 0 && rect.height > 0

getBoundingClientRect() restituisce dimensioni e posizione dell'elemento rispetto al viewport.

Qui viene usato come euristica per escludere elementi che non occupano spazio visuale.

Documentazione:

https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect

Attenzione però: questo non equivale a una definizione universale di visibilità.

Un elemento può avere dimensioni positive ed essere:

opacity: 0
coperto da un altro elemento
fuori dalla parte visibile del viewport

Quindi il check significa più precisamente:

questo candidato possiede un rettangolo renderizzato non nullo.

È sufficiente per l'euristica specifica, non una funzione generale isVisible().

Parte XIII — DOM come baseline, non sempre source of truth

42. La percentuale è una baseline

Il codice di progresso contiene:

const domPercent = readPegasoCoursePercentage();

if (domPercent !== null && courseProgressState.baselinePercent === null) {
  courseProgressState.baselinePercent = domPercent;
  courseProgressState.domPercent = domPercent;
}

Poi la percentuale visibile può essere calcolata con:

const value = exactAvailable
  ? Number(state.exactPercent)
  : state.baselinePercent + Math.max(0, Number(state.sessionDelta) || 0);

Riferimenti:

• content.js L4440-L4455
• content.js L4463-L4469

Il DOM quindi fornisce una baseline.

Ma quando esiste un valore più preciso:

exactPercent

quello prevale.

43. Hierarchy of evidence

Possiamo descrivere questa architettura come una gerarchia di evidenze:

valore esatto disponibile
        │
        ├── sì → usa exactPercent
        │
        └── no
             ↓
      baseline DOM
             +
      delta osservato nella sessione

Non esiste necessariamente una sola fonte che sappia tutto in ogni momento.

PlumePilot combina fonti con livelli diversi di affidabilità.

Questo ci prepara direttamente ai capitoli 04, 06 e 08:

DOM
API
cache
master call
stato locale

non avranno tutti lo stesso peso.

44. Source of truth vs source of signal

È utile distinguere due concetti.

Source of truth

Fonte considerata autorevole per determinare il valore reale.

Source of signal

Fonte che ci fornisce un'indicazione utile, senza essere necessariamente definitiva.

Il DOM spesso è una source of signal eccellente.

Per esempio:

la UI mostra 82%

è un ottimo punto di partenza.

Ma per alcune decisioni può essere preferibile confermare con dati più strutturati.

Parte XIV — URL come identità più stabile del testo visuale

45. La UI può cambiare etichetta mentre l'URL rimane stabile

Nel codice del limite capitoli troviamo un commento molto interessante:

// The visible chapter label is not a stable identifier: Pegaso may rebuild
// it while lesson percentages change. The URL lesson number is the same
// display-order identity used by the course APIs and remains stable while
// PlumePilot moves between videos of the same chapter.

Il codice quindi preferisce:

const lessonNumber = lessonNumberFromUrl();

Riferimento al parser dell'URL: content.js L4336-L4345.

Questa è un'altra manifestazione dello stesso principio:

rappresentazione visuale mutevole
            ↓
identificatore logico più stabile

46. Testo visuale come identificatore: quando è accettabile?

PlumePilot usa comunque anche testo:

{
  sectionText: chapter.sectionText,
  chapterText: chapter.text,
}

perché non sempre dispone immediatamente di ID migliori.

Quindi dobbiamo evitare una regola dogmatica del tipo:

non usare mai il testo come identità.

La domanda è sempre:

quali identificatori espone realmente il sistema che sto integrando?

Possiamo ordinare grossolanamente le preferenze così:

ID di dominio stabile
    ↓
ID/chiave nell'URL
    ↓
attributo semantico stabile
    ↓
combinazione di campi
    ↓
testo visuale
    ↓
posizione pura nel DOM

Ma ogni progetto può imporre compromessi diversi.

Parte XV — Identità composta

47. Perché il numero del capitolo non basta

PlumePilot supporta corsi con più sezioni:

Analisi Matematica I
  1 - ...
  2 - ...

Analisi Matematica II
  1 - ...
  2 - ...

Se usassimo soltanto:

chapterNumber = 1

avremmo una collisione.

Per questo chapterIdentity() restituisce:

{
  sectionText: chapter.sectionText,
  chapterText: chapter.text,
}

Riferimento: content.js L1235-L1238.

Il changelog della v1.8.0 conserva esattamente questa decisione: i capitoli vengono identificati tramite sezione + titolo affinché la numerazione possa ricominciare da 1 in sezioni differenti.

Riferimento: CHANGELOG.md L1255-L1263.

48. Composite key

Dal punto di vista dei dati, questo è molto simile a una chiave composta.

In un database potremmo avere:

PRIMARY KEY (section_id, chapter_number)

In PlumePilot abbiamo concettualmente:

(sectionText, chapterText)

Nessuno dei due valori è ideale quanto un ID ufficiale immutabile, ma la coppia distingue casi che il solo numero non saprebbe distinguere.

Parte XVI — Event delegation

49. Un listener sul documento può sopravvivere alla sostituzione dei figli

Alla fine di content.js troviamo anche:

document.addEventListener("click", (event) => {
  const row = event.target?.closest?.("div.border-t");

  if (row && row.querySelector(":scope > div.cursor-pointer")) {
    setTimeout(() => {
      const selected = currentLesson();
      if (selected) rememberPlaybackLesson(selected);
    }, 0);
  }
}, true);

Riferimento: content.js L7080-L7089.

Questo è un esempio di event delegation.

Invece di aggiungere un listener a ogni riga:

row1 → listener
row2 → listener
row3 → listener

aggiungiamo un listener a un antenato stabile:

document → listener

Quando avviene un click, risaliamo dal target:

event.target.closest("div.border-t")

50. Perché è particolarmente utile in un DOM dinamico

Se il frontend distrugge e ricrea le righe:

row A eliminata
row B creata

un listener attaccato direttamente ad A muore insieme ad A.

Il listener su document, invece, continua a esistere.

Quindi anche una futura row B può essere intercettata.

Questo è uno dei vantaggi più forti dell'event delegation nelle applicazioni dinamiche.

51. Perché c'è setTimeout(..., 0)?

Dopo il click PlumePilot non legge immediatamente currentLesson().

Fa:

setTimeout(() => {
  const selected = currentLesson();
  // ...
}, 0);

Il timeout zero non significa:

esegui immediatamente

Significa, semplificando:

programma questo lavoro per un task futuro

Così il codice lascia prima terminare il task corrente e permette agli handler della pagina di aggiornare il proprio stato/DOM.

È una piccola forma di defer.

MDN, event loop e task/microtask:

https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide

Non garantisce che qualsiasi render asincrono sia concluso; infatti per operazioni più importanti PlumePilot usa waitFor(). Qui è sufficiente come tentativo di leggere la selezione immediatamente successiva al click.

Parte XVII — Hidden tabs e tempo non affidabile

52. Il browser può rallentare una pagina non visibile

La versione reale di waitFor() contiene più logica di quella mostrata inizialmente:

const hiddenEpochAtStart = pageHiddenEpoch;
const startedHidden = documentIsHidden();

Dopo il primo timeout controlla se la pagina è stata nascosta durante l'attesa e può concedere una nuova finestra di attesa quando torna visibile.

Perché?

Perché i browser applicano ottimizzazioni e throttling alle tab in background.

Quindi un timeout osservato in una tab nascosta può significare:

"l'operazione non è avvenuta"

oppure:

"la pagina non ha avuto le stesse opportunità temporali di quando era visibile"

53. Tempo di muro vs progresso dell'applicazione

Date.now() misura il tempo reale trascorso.

Ma il fatto che siano passati 5 secondi non implica che una tab in background abbia eseguito lo stesso volume di lavoro JavaScript/rendering di una tab attiva.

Quindi:

5 secondi wall-clock

non sono necessariamente:

5 secondi di progresso applicativo equivalente

Questa distinzione tornerà nel capitolo sull'asincronia.

Parte XVIII — DOM e API: due punti di vista sullo stesso dominio

54. Perché PlumePilot non ha abbandonato il DOM dopo aver scoperto le API?

Una domanda naturale potrebbe essere:

se abbiamo accesso ai dati delle API della piattaforma, perché continuare a leggere e manipolare il DOM?

Perché i due strumenti risolvono problemi differenti.

Le API sono forti quando vogliamo sapere

qual è la percentuale?
quali attività esistono?
qual è lo stato di una lezione?
qual è il dato strutturato del corso?

Il DOM è necessario quando vogliamo sapere o fare

cosa è attualmente renderizzato?
quale riga è selezionata?
il capitolo è aperto?
dove posso cliccare?
il player esiste in questa pagina?
quale UI sta vedendo l'utente?

Non sono due tecnologie concorrenti.

Sono due proiezioni differenti del sistema.

55. Data plane e presentation plane

Possiamo usare una distinzione informale:

API / dati strutturati
        ↓
   data plane

DOM / elementi visibili
        ↓
presentation plane

PlumePilot deve spesso passare dall'uno all'altro.

Per esempio:

API: capitolo 5 contiene un'attività incompleta
        ↓
DOM: trova il componente che rappresenta capitolo 5
        ↓
DOM: aprilo
        ↓
DOM/API: verifica la specifica attività

Questa combinazione è alla base della ricerca moderna della prima attività incompleta, che studieremo nel Capitolo 8.

Parte XIX — Un piccolo modello di affidabilità

56. Non tutti i segnali DOM hanno lo stesso valore

Possiamo classificare alcuni esempi.

Molto debole

"il terzo div della seconda colonna"

Debole

una classe CSS puramente stilistica

Medio

struttura + testo + ruolo visivo

Più forte

URL + identificatore di dominio + conferma API

PlumePilot contiene combinazioni di tutti questi livelli perché è cresciuto insieme alla conoscenza della piattaforma.

Questo è normale nei software di integrazione.

57. Robustezza = più segnali + verifica

Molte delle soluzioni più affidabili del progetto seguono implicitamente questa formula:

ROBUSTEZZA
    ≈
identità ragionevolmente stabile
+
lettura fresca
+
verifica post-azione
+
fallback

Esempio:

chapter identity
    +
findChapter() fresco
    +
click
    +
waitFor(isOpen)

Non eliminiamo l'incertezza.

La gestiamo.

Parte XX — Perché il codice DOM diventa rapidamente complesso

58. Un querySelector() può nascondere molto dominio

Guardando soltanto questa riga:

const el = document.querySelector(...);

potremmo pensare che il problema sia "conoscere CSS selectors".

Ma in un'integrazione reale dobbiamo decidere:

quando fare la query
su quale scope
con quale fallback
come riconoscere l'ambiguità
cosa fare se non esiste ancora
come capire se il nodo è stale
come riaprirne il contenitore
come validare l'effetto del click
come distinguere piattaforme diverse

Il selettore è quasi la parte meno interessante.

59. Questo spiega perché i test E2E possono essere fragili

Gli stessi problemi compaiono in Playwright, Selenium, Cypress e strumenti simili.

Un test fragile spesso fa:

sleep 2 secondi
click sul terzo bottone
sleep 1 secondo
leggi testo

Un test più robusto ragiona in termini di:

aspetta la condizione significativa
individua l'elemento semanticamente
esegui l'azione
verifica lo stato risultante

PlumePilot non è un framework E2E, ma l'esperienza accumulata è molto simile.

Parte XXI — Se riscrivessimo oggi il layer DOM

60. Potremmo estrarre un CoursePageAdapter

Attualmente molte funzioni DOM vivono direttamente in content.js.

Una possibile evoluzione architetturale potrebbe essere:

content.js
    │
    ▼
CoursePageAdapter
    │
    ├── getSections()
    ├── getChapters()
    ├── getCurrentLesson()
    ├── openChapter(identity)
    ├── readVisibleProgress()
    └── findRenderedActivity(identity)

Poi implementazioni specifiche:

PegasoCoursePageAdapter
MercatorumCoursePageAdapter
UtsrCoursePageAdapter

Questo renderebbe esplicito qualcosa che nel codice attuale esiste già in forma più organica.

61. Cosa guadagneremmo?

Separazione delle responsabilità

L'autoplay potrebbe ragionare in termini di:

await page.openChapter(identity);

senza conoscere classi CSS o chevron.

Testabilità

Potremmo testare il dominio contro un adapter finto:

fakePage.openChapter(...)

senza costruire sempre il DOM completo della piattaforma.

Isolamento dei cambiamenti

Se domani Pegaso cambia:

.bg-white.text-base...

potremmo modificare principalmente l'adapter della pagina.

62. Cosa costerebbe?

Ogni astrazione ha un prezzo.

Dovremmo:

• definire interfacce coerenti;
• migrare una grande quantità di codice esistente;
• evitare adapter troppo generici;
• gestire casi in cui le piattaforme differiscono semanticamente, non soltanto nel markup.

Quindi non significa che la struttura attuale sia "sbagliata".

Significa che ora il progetto è abbastanza maturo da rendere visibile un boundary che all'inizio non era ancora evidente.

Questa è una delle lezioni più importanti dell'architettura evolutiva.

Parte XXII — Caso di studio completo: dalla fine del video al prossimo elemento

63. Ricostruiamo il rischio

Immaginiamo:

utente sta guardando Video B
sidebar aperta
PlumePilot conosce row B

Il video termina.

PlumePilot aspetta che la piattaforma registri il completamento.

Nel frattempo può succedere:

A. la sidebar aggiorna le percentuali
B. React/il frontend ricrea le righe
C. l'utente chiude l'accordion
D. il nodo row B originale si stacca

L'algoritmo ingenuo sarebbe:

const row = currentLesson();
await waitForCompletion(row);
const next = nextLesson(row);
clickRow(next);

Il problema è l'ultima parte:

row potrebbe appartenere al vecchio DOM

64. L'algoritmo reale recupera il contesto

Nel flusso attuale:

let cur = await recoverPlaybackLesson(v);

poi conserva:

const completedLesson = playbackContext;

attende:

const completed = await waitForLessonCompletion(cur, v);

quindi recupera di nuovo:

const stableCur = await recoverPlaybackLesson(v);

Infine verifica che la lezione recuperata corrisponda ancora al contesto completato.

Riferimento: content.js L6671-L6702.

Questa sequenza è importante:

resolve
  ↓
remember identity
  ↓
await external/dynamic change
  ↓
re-resolve
  ↓
validate identity
  ↓
continue

È quasi una piccola transazione ottimistica.

65. Optimistic concurrency, in miniatura

Non esiste un vero lock sul DOM.

PlumePilot non può dire alla piattaforma:

"non modificare la sidebar finché non ho finito"

Quindi procede ottimisticamente:

1. fotografa l'identità
2. lascia che il mondo cambi
3. verifica che le precondizioni siano ancora valide
4. solo allora continua

È concettualmente simile all'optimistic concurrency control:

read version
work
check version still compatible
commit

Qui la "versione" non è un numero esplicito, ma la corrispondenza tra il playback context e il DOM nuovamente risolto.

Parte XXIII — Errori che sembrano DOM bug ma non lo sono

66. Non ogni elemento mancante è un selettore rotto

Quando una query ritorna null, le possibili cause sono molte:

1. selettore sbagliato
2. pagina non ancora renderizzata
3. accordion chiuso
4. siamo nella route sbagliata
5. tab nascosta / rendering ritardato
6. piattaforma differente
7. componente rimosso intenzionalmente
8. sessione cambiata
9. nodo presente in un frame differente

Un buon debug non dovrebbe saltare immediatamente alla conclusione:

il CSS selector non funziona.

Prima bisogna capire in quale stato si trova il sistema.

67. Loggare significato, non soltanto oggetti

Messaggi come:

"Chapter did not open"
"Could not determine current lesson"
"Advance cancelled because the completed lesson changed or disappeared"

sono più utili di:

console.log(element);

perché descrivono l'invariante che è fallita.

Un log efficace dovrebbe rispondere a:

cosa stavamo cercando di fare?
quale precondizione mancava?
quale identità stavamo seguendo?

Non soltanto:

qual era il valore di questa variabile?

Parte XXIV — Metodo pratico per integrare una pagina dinamica

68. Passo 1 — Trova l'identità di dominio

Prima di scrivere il selettore chiediti:

cosa rappresenta davvero questo elemento?

Esempio:

non "questo span"
ma "capitolo 5 della sezione X"

69. Passo 2 — Trova la rappresentazione DOM corrente

Solo dopo:

findChapter(identity)

Il DOM diventa un adapter verso quell'identità.

70. Passo 3 — Definisci la readiness

Chiediti:

quale condizione dimostra che il componente è pronto?

Non:

quanti millisecondi penso che servano?

Esempio:

chapters().length > 0

oppure:

isChapterOpen(identity)

71. Passo 4 — Esegui l'azione

Per esempio:

chapter.span.click();

72. Passo 5 — Verifica l'effetto

await waitFor(() => isChapterOpen(identity));

Non assumere che l'azione abbia avuto successo soltanto perché non ha lanciato eccezioni.

73. Passo 6 — Preparati alla sostituzione dei nodi

Dopo ogni lunga operazione asincrona chiediti:

sto usando ancora un Element ottenuto prima dell'await?

Se sì, valuta se devi risolverlo di nuovo.

Questa domanda da sola può prevenire molti bug.

Parte XXV — Esercizi

74. Esercizio 1 — Quale codice è più robusto?

Versione A

const chapter = findChapter(identity);
chapter.span.click();
await sleep(1000);
return chapter;

Versione B

const chapter = findChapter(identity);
chapter.span.click();

return await waitFor(() => {
  const fresh = findChapter(identity);
  return fresh && isChapterOpen(identity) ? fresh : null;
});

Quale preferiresti?

Ragionamento

La B.

Non perché 1000 sia necessariamente troppo corto.

Ma perché la B:

attende una condizione
+
risolve nuovamente il DOM
+
verifica il risultato

La A indovina il tempo e restituisce un riferimento potenzialmente stale.

75. Esercizio 2 — Perché questa cache è pericolosa?

const cachedLessons = lessons();

async function next() {
  await somethingSlow();
  return cachedLessons[3];
}

Risposta

Perché l'array contiene riferimenti ottenuti da uno snapshot precedente.

La pagina può avere ricreato le righe durante somethingSlow().

Una soluzione migliore è conservare l'identità della lezione e richiamare lessons() o una funzione di lookup quando serve.

76. Esercizio 3 — Che cosa significa null?

const percent = readPegasoCoursePercentage();

percent === null può significare:

A. non esistono indicatori
B. esistono ma non sono ancora renderizzati correttamente
C. esistono più candidati ambigui
D. siamo nella pagina sbagliata
E. il markup della piattaforma è cambiato

La risposta corretta è:

potenzialmente tutte.

Il chiamante deve interpretare il valore nel contesto.

77. Esercizio 4 — Observer o polling?

Devi aspettare che un capitolo appena cliccato sia aperto.

Hai due possibilità:

MutationObserver globale

oppure:

waitFor(() => isChapterOpen(identity))

Quale useresti?

Una buona risposta

Per una singola transizione circoscritta, waitFor() è semplice e leggibile.

Per accorgersi in modo permanente che parti arbitrarie della pagina possono nascere in futuro, MutationObserver è più adatto.

Non esiste una API sempre superiore: rispondono a scale temporali differenti.

78. Esercizio 5 — Trova il domain identity

Hai questo elemento:

<span>2 - Funzioni</span>

Qual è l'identità?

Non possiamo saperlo dal solo nodo.

Potrebbero esistere:

Sezione A / 2 - Funzioni
Sezione B / 2 - Funzioni

Servono altre informazioni.

Questa è esattamente la ragione delle identità composte.

Parte XXVI — Concetti da portarsi dietro

79. DOM snapshot

Una lettura del DOM descrive uno stato in un preciso momento. In una pagina dinamica non va confusa con una struttura immutabile.

80. Stale DOM reference

Riferimento a un nodo ottenuto in passato che non rappresenta più il componente corrente della UI.

81. Logical identity

Identità del concetto di dominio indipendente dal particolare nodo DOM che lo rappresenta.

82. Selector contract

Dipendenza implicita dalla struttura, dalle classi o dagli attributi della pagina host utilizzati per ritrovare un elemento.

83. Readiness condition

Condizione osservabile che indica quando un componente è realmente pronto per l'operazione successiva.

84. Polling

Controllo periodico di una condizione finché diventa vera o viene raggiunta una deadline.

85. MutationObserver

API browser che notifica modifiche all'albero DOM. È particolarmente utile quando componenti rilevanti possono essere creati o rimossi dopo lo startup.

86. Event delegation

Gestione degli eventi tramite un antenato stabile invece di attaccare listener a ogni elemento dinamico.

87. Command + verification

Pattern in cui un'azione viene inviata alla UI e il codice verifica successivamente che il sistema abbia raggiunto lo stato desiderato.

88. Resolve late

Strategia di conservare identità stabili e risolvere i riferimenti concreti il più vicino possibile al momento del loro utilizzo.

89. Precondition recovery

Tentativo di ripristinare automaticamente una condizione necessaria prima di proseguire, per esempio riaprire un accordion prima di cercarne i figli.

90. Hierarchy of evidence

Ordinamento delle fonti in base all'affidabilità. Un valore API esatto, una baseline DOM e un'euristica possono coesistere senza avere la stessa autorità.

Parte XXVII — Approfondimenti

91. DOM selection

MDN — Document.querySelector()

https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector

MDN — Document.querySelectorAll()

https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll

La parte particolarmente importante per questo capitolo è che querySelectorAll() restituisce una NodeList statica.

MDN — DOM selection and traversal

https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Selection_and_traversal_on_the_DOM_tree

92. Navigazione relativa

MDN — Element.closest()

https://developer.mozilla.org/en-US/docs/Web/API/Element/closest

Utile per capire perché PlumePilot può partire da uno span o dal target di un click e risalire al componente logico che lo contiene.

93. Osservare il DOM

MDN — MutationObserver

https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver

Quando lo studi, prova a distinguere sempre:

"so che il DOM è cambiato"

contro:

"so che cosa significa semanticamente il cambiamento"

La seconda informazione non viene fornita automaticamente dall'observer.

94. Layout e dimensioni

MDN — Element.getBoundingClientRect()

https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect

Serve a comprendere perché una dimensione positiva può essere un segnale utile di rendering senza costituire una definizione completa di visibilità.

95. Task e defer

MDN — Microtask guide / event loop

https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide

È utile per comprendere perché setTimeout(..., 0) non significa "esegui adesso" e perché gli effetti di un evento possono diventare osservabili soltanto in un momento successivo.

96. Cosa abbiamo imparato davvero

Il punto più importante di questo capitolo non è come usare querySelector().

È imparare a vedere una pagina dinamica come un sistema con rappresentazioni temporanee.

Abbiamo visto che:

un nodo DOM

non è necessariamente:

un'identità di dominio

che:

non trovato

non significa necessariamente:

non esiste

che:

.click()

non significa:

transizione completata

che:

MutationObserver

non ci consegna il significato del cambiamento, ma ci dice che la nostra fotografia potrebbe essere diventata obsoleta.

E soprattutto abbiamo visto un pattern che tornerà continuamente in PlumePilot:

identità stabile
      ↓
lettura fresca
      ↓
azione
      ↓
attesa condizionale
      ↓
verifica
      ↓
fallback / recovery

Questa è già architettura software, anche se stiamo lavorando con dei <div>.

Nel prossimo capitolo

Finora abbiamo osservato la piattaforma soprattutto dalla superficie:

DOM
URL
interazioni

Ma PlumePilot ha imparato progressivamente a guardare anche dietro l'interfaccia, verso le richieste che la piattaforma stessa effettua.

Nel Capitolo 04 entreremo in:

API e reverse engineering — capire la piattaforma osservandone il traffico

Vedremo:

• che cosa significa realmente "reverse engineering" in questo contesto;
• request e response HTTP;
• JSON come rappresentazione del dominio;
• come riconoscere endpoint e identificatori;
• perché usare la sessione già autenticata è diverso dal conservare credenziali;
• master call e chiamate di dettaglio;
• come confrontare ciò che dice una API con ciò che mostra il DOM;
• perché le API hanno reso alcuni algoritmi di PlumePilot più veloci e affidabili;
• e dove, nonostante tutto, il DOM rimane indispensabile.

Passeremo quindi da:

"che cosa vedo nella pagina?"

alla domanda:

"da dove arrivano i dati che la pagina sta mostrando?"

Ed è qui che l'integrazione con una web app comincia a diventare davvero interessante.

04 — API e reverse engineering

Capire la piattaforma osservandone il traffico

Nei primi capitoli abbiamo guardato PlumePilot dall'esterno verso l'interno.

Abbiamo visto:

popup
  ↓
background
  ↓
bridge
  ↓
content script
  ↓
DOM

Ma una web app moderna non vive soltanto nel DOM.

Quello che vediamo nella pagina è spesso il risultato finale di un'altra conversazione:

browser
  ↓ HTTP
backend
  ↓ JSON
browser
  ↓ stato applicativo
DOM

Quando la piattaforma mostra un capitolo, una percentuale, una dispensa o un test, quei dati devono essere arrivati da qualche parte.

PlumePilot ha imparato progressivamente a osservare proprio questo livello.

Ed è qui che entra il tema del capitolo:

reverse engineering di una web app attraverso il traffico che la web app stessa genera.

Il termine può sembrare più aggressivo di ciò che accade realmente.

Nel nostro caso non significa:

bypassare autenticazione
forzare endpoint non autorizzati
indovinare credenziali
accedere a contenuti non disponibili all'utente

Significa invece:

la pagina è già autenticata
        ↓
la pagina chiama le proprie API
        ↓
PlumePilot osserva forma e semantica delle chiamate
        ↓
riusa, quando opportuno, la stessa sessione già autorizzata
        ↓
normalizza le risposte
        ↓
usa quei dati per funzioni locali dell'estensione

Questa distinzione sarà importante per tutto il capitolo.

Parte I — Una web app è anche un client HTTP

1. Guardare oltre il DOM

Nel Capitolo 03 abbiamo visto che il DOM è una rappresentazione temporanea dello stato dell'applicazione.

Ora possiamo aggiungere un secondo livello al modello mentale:

backend
   ↓
API response
   ↓
frontend state
   ↓
DOM

Quindi, quando leggiamo:

80%

dalla sidebar, potremmo stare osservando un valore che il frontend ha:

1. ricevuto da una API;
2. trasformato;
3. memorizzato nello stato interno;
4. infine renderizzato come testo.

Il DOM è quindi spesso l'ultimo anello della catena, non il primo.

Questo spiega perché, per alcune operazioni, interrogare i dati più vicino alla sorgente può essere:

• più veloce;
• più completo;
• meno dipendente dalla struttura grafica della pagina;
• più semplice da correlare con identificatori stabili.

Ma non significa automaticamente che una API sia sempre "più vera" del DOM.

Ci torneremo.

2. API pubblica e API usata dal frontend non sono la stessa cosa

Quando si dice "API" si pensa spesso a qualcosa documentato per sviluppatori esterni:

GET /v1/users
Authorization: Bearer ...

con documentazione, versioning e contratti espliciti.

Una web app, però, utilizza quasi sempre anche interfacce HTTP pensate principalmente per il proprio frontend.

Il browser deve comunque poter chiedere al backend:

quali sono i moduli del corso?
qual è il progresso?
quali attività contiene una lezione?
dove si trova la dispensa?
quali esami risultano completati?

Questi endpoint possono essere perfettamente normali API HTTP anche se non sono pubblicizzati come API per integrazioni di terze parti.

Da un punto di vista architetturale:

Multiversity frontend
        │
        │ HTTP + JSON
        ▼
Multiversity backend

PlumePilot si trova già dentro quel client browser e può osservare questa conversazione.

Parte II — Perché commission-interceptor.js vive nel MAIN world

3. Il problema architetturale

Nel Capitolo 01 abbiamo visto che commission-interceptor.js viene caricato con:

"world": "MAIN"

Questa scelta diventa molto più chiara adesso.

Se vogliamo osservare:

window.fetch

usato dal JavaScript della pagina, dobbiamo trovarci nellostesso JavaScript world della pagina.

Un content script isolato vede lo stesso DOM, ma non necessariamente gli stessi oggetti JavaScript modificati dal sito.

PlumePilot sfrutta quindi il MAIN world come punto di osservazione del runtime host.

Riferimento: manifest.json.

4. Le API origin supportate

All'inizio di commission-interceptor.js troviamo:

const PLATFORM_API_ORIGINS = Object.freeze([
  ["pegaso", "pegaso.multiversity.click", "https://lms-api.prod.pegaso.multiversity.click"],
  ["mercatorum", "mercatorum.multiversity.click", "https://lms-api.prod.mercatorum.multiversity.click"],
  ["utsr", "utsr.multiversity.click", "https://lms-api.prod.utsr.multiversity.click"],
]);

Riferimento: commission-interceptor.js L21-L25.

Questa tabella fa qualcosa di più importante di quanto sembri.

Definisce un confine esplicito:

pagina Pegaso      → API Pegaso
pagina Mercatorum  → API Mercatorum
pagina UTSR        → API UTSR

L'interceptor non dice:

osserva qualunque Authorization header del browser

Dice invece:

interessati soltanto alle richieste dirette all'API della piattaforma corrente

Questo principio prende spesso il nome di least privilege o, più genericamente, minimizzazione dell'ambito.

Parte III — Osservare fetch() senza rompere la pagina

5. Conservare l'implementazione originale

PlumePilot salva prima il riferimento originale:

const originalFetch = window.fetch;

poi installa un wrapper:

window.fetch = function studyWingFetch(input, init) {
  // osservazione PlumePilot
  const promise = originalFetch.call(this, input, init);
  // osservazione della risposta
  return promise;
};

Riferimento: commission-interceptor.js L708-L720.

Questo pattern viene spesso chiamato:

• wrapping;
• instrumentation;
• monkey patching, in senso più informale.

L'idea è:

pagina chiama fetch()
        ↓
wrapper PlumePilot
        ↓
fetch originale
        ↓
network

Il wrapper osserva la chiamata senza sostituirne il comportamento applicativo.

6. Una proprietà fondamentale del wrapper

Il codice ritorna il Promise originale:

return promise;

Questo è essenziale.

Immaginiamo che il frontend faccia:

const response = await fetch(url);

Se il wrapper di PlumePilot cambiasse accidentalmente il tipo di ritorno:

window.fetch = () => undefined;

la piattaforma si romperebbe.

Un buon wrapper dovrebbe quindi preservare il contratto osservabile della funzione originale.

Idealmente:

stessi argomenti accettati
stesso this appropriato
stesso valore di ritorno
stessi errori della chiamata originale

L'instrumentation deve essere il meno invasiva possibile.

7. call(this, ...)

Il wrapper invoca:

originalFetch.call(this, input, init)

anziché semplicemente:

originalFetch(input, init)

In questo specifico caso window.fetch non dipende normalmente da un this applicativo complesso, ma preservare il receiver rende il wrapper più fedele alla chiamata originale.

È un'abitudine importante quando si decorano API che non possediamo.

Parte IV — Leggere una risposta senza consumarla

8. Il body di una Response non è un valore riutilizzabile all'infinito

Una Response Fetch contiene uno stream.

Se facessimo semplicemente:

const body = await response.json();

nel wrapper, rischieremmo di consumare il body prima che lo faccia la pagina.

Il frontend host potrebbe poi tentare:

await response.json();

e trovare il body già usato.

PlumePilot evita questo problema con:

const body = await response.clone().json();

Riferimento: commission-interceptor.js L688-L705.

Il clone permette quindi due consumatori concettuali:

Response originale ─────► frontend Multiversity

Response clone ─────────► PlumePilot

9. Un clone non è gratis

Response.clone() è utilissimo, ma ha implicazioni di memoria e buffering.

Se una risposta è molto grande e i due consumer avanzano a velocità differenti, il browser può dover mantenere dati bufferizzati.

Per PlumePilot le risposte JSON intercettate in questi flussi sono molto più piccole di un PDF completo, quindi il compromesso è ragionevole.

Ma questa osservazione tornerà nel capitolo sulla performance:

una API comoda può nascondere copie e buffer impliciti.

Parte V — Perché vengono intercettati anche gli XMLHttpRequest

10. Non possiamo assumere che una web app usi soltanto fetch()

Il frontend host potrebbe usare:

fetch
XMLHttpRequest
una libreria che internamente usa uno dei due
componenti vecchi e nuovi insieme

PlumePilot quindi instrumenta anche XMLHttpRequest.

Conserva:

const originalOpen = XMLHttpRequest.prototype.open;
const originalSend = XMLHttpRequest.prototype.send;
const originalSetRequestHeader = XMLHttpRequest.prototype.setRequestHeader;

Riferimento: commission-interceptor.js L723-L725.

11. Ricostruire una richiesta XHR

Con XHR l'URL arriva durante:

xhr.open(method, url)

mentre l'header può arrivare dopo:

xhr.setRequestHeader("Authorization", value)

PlumePilot deve quindi ricordare temporaneamente:

this.__studyWingRequestUrl = url;

in open().

Poi, quando vede l'header authorization, può correlare:

questo token
   ↓
questa richiesta
   ↓
questa API origin

È già un piccolo esempio di correlation state.

Parte VI — L'autenticazione già esistente

12. Il Bearer token

Le richieste della piattaforma contengono un header di autenticazione.

PlumePilot cerca:

const authorization = new Headers(headers)
  .get("authorization")
  ?.trim();

if (/^Bearer\s+\S+$/i.test(authorization || "")) {
  bearerToken = authorization;
}

Riferimento: commission-interceptor.js L73-L83.

Un header del tipo:

Authorization: Bearer <token>

significa, in termini generali:

"questa richiesta presenta una credenziale che il server può verificare"

Il token non è la password dell'utente.

È una credenziale di sessione/accesso già ottenuta dal frontend attraverso il normale processo di autenticazione della piattaforma.

13. Authentication e authorization

I termini vengono spesso confusi.

Possiamo distinguerli così:

Authentication
"chi sei?"

Authorization
"cosa ti è permesso fare?"

In pratica i due meccanismi sono spesso collegati.

Il Bearer token presentato alla API consente al backend di collegare la richiesta alla sessione e ai privilegi dell'utente.

PlumePilot non crea privilegi nuovi.

Riusa le richieste nel contesto dell'utente già autenticato.

14. Dove vive il token in PlumePilot?

Questa è una decisione architetturale molto importante.

Nel codice:

let bearerToken = null;

Il token vive nella closure di commission-interceptor.js.

Non viene messo in:

chrome.storage.local
localStorage PlumePilot
payload window.postMessage
log applicativi
server PlumePilot

Il resto dell'estensione non riceve:

{ token: "..." }

Riceve invece un'interfaccia di capacità:

{
  action: "lesson",
  courseCode,
  lessonNumber,
  ...
}

L'interceptor usa internamente la credenziale e restituisce soltanto dati normalizzati.

Questo è un pattern architetturale molto interessante.

15. Secret containment

Possiamo rappresentarlo così:

content.js
   │
   │ "dammi i dati della lezione 5"
   ▼
commission-interceptor.js
   │
   │ possiede temporaneamente il Bearer token
   ▼
Multiversity API

contro una soluzione più rischiosa:

interceptor
   │
   └──► passa il token a content.js
             │
             ├──► bridge
             ├──► background
             ├──► storage
             └──► altri componenti

Ridurre il numero di componenti che vedono un segreto riduce anche la superficie in cui quel segreto può essere:

• loggato accidentalmente;
• serializzato;
• persistito;
• inviato nel posto sbagliato.

Possiamo chiamare questo principio secret containment o credential minimization.

Parte VII — Non intercettare tutto

16. Validare l'origin prima di guardare l'Authorization header

La funzione:

function isCurrentPlatformApiUrl(value) {
  try {
    return new URL(String(value), window.location.href).origin === API_ORIGIN;
  } catch {
    return false;
  }
}

Riferimento: commission-interceptor.js L52-L58.

viene usata prima di memorizzare l'autorizzazione.

La logica è:

request qualunque
      ↓
è diretta alla API della piattaforma corrente?
      │
   no └──► ignora
      │
   sì ▼
leggi eventualmente Authorization

Questa è una difesa semplice ma fondamentale.

17. Allowlist invece di osservazione generica

La strategia può essere descritta come una allowlist:

solo questi host
solo questa API origin
solo alcune route interessanti

È preferibile a:

intercetta tutto e poi vediamo

perché rende più chiaro:

• lo scopo del codice;
• cosa può essere letto;
• quali dati attraversano il sistema;
• quali assunzioni dobbiamo testare.

Parte VIII — Il primo endpoint fondamentale: l'indice del corso

18. Quello che nel progetto chiamiamo "master call"

Uno degli endpoint più importanti è costruito così:

url = `${API_ORIGIN}/student/course/${encodeURIComponent(courseCode)}/video-lessons/0`;

Riferimento: commission-interceptor.js L453-L455.

Nel nostro lessico durante lo sviluppo l'abbiamo spesso chiamato master call.

Non è necessariamente il nome ufficiale dell'endpoint.

È il nostro nome concettuale per una risposta che descrive l'insieme dei moduli del corso e il loro stato sintetico.

Possiamo pensarla come:

corso
 ├── modulo A   100%
 ├── modulo B   100%
 ├── modulo C    80%
 ├── modulo D     0%
 └── modulo E   100%

Questo tipo di vista aggregata è preziosissima.

19. Da payload grezzo a modello interno

PlumePilot non passa direttamente il JSON del server al resto dell'estensione.

Lo normalizza:

return {
  displayOrder,
  masterOrder,
  folderId,
  id,
  lpId,
  title,
  percentage,
};

Riferimento: commission-interceptor.js L99-L120.

Questa fase è molto simile a ciò che in un backend potresti chiamare:

DTO mapping
adapter
anti-corruption layer
normalization layer

Il resto di PlumePilot non deve conoscere ogni dettaglio del JSON originale.

20. Perché normalizzare?

Supponiamo che il backend risponda con:

{
  "display_order": "5",
  "percentage": "80",
  "lp_id": 123
}

Il codice di dominio preferisce ricevere:

{
  displayOrder: 5,
  percentage: 80,
  lpId: 123
}

con vincoli già verificati.

Questo sposta la complessità al confine:

external schema
      ↓
validation + normalization
      ↓
internal schema