PlumePilot

Assistente indipendente per Pegaso, Mercatorum e San Raffaele

View the Project on GitHub PlumePilot/plumepilot

Inside PlumePilot

Anatomia di una browser extension reale

JavaScript, WebExtensions, DOM, API, asincronia e software engineering attraverso un progetto reale.

Questo libro usa PlumePilot come caso di studio. L’obiettivo non è soltanto capire cosa fa il codice, ma imparare a riconoscere problemi, concetti e decisioni architetturali riutilizzabili in altri progetti.

Il manoscritto è completo: Introduzione + Capitoli 1–17, glossario e fonti. Per la lettura senza connessione è disponibile anche un singolo file HTML self-contained, con indice laterale, ricerca, tema chiaro/scuro, navigazione fra capitoli e ripristino locale della posizione di lettura.

Inizia dall’introduzione → · Edizione HTML offline · Glossario · Fonti · Edizione completa in un solo Markdown · Repository PlumePilot

Versioni di riferimento

Il libro segue volutamente l’evoluzione reale del progetto invece di riscrivere retroattivamente la storia come se l’architettura finale fosse sempre esistita.

Quando un capitolo cita una scelta poi modificata, la mantiene come parte del caso di studio: capire perché una soluzione sembrava corretta, dove ha fallito e quale informazione mancava è parte del percorso.

Indice

# Capitolo
00 Introduzione — Dal problema al prodotto
01 Anatomia di PlumePilot — Cosa succede quando l’estensione prende vita
02 Contesti e messaging — Far parlare mondi separati
03 DOM e pagine dinamiche — Lavorare in una UI che non controlliamo
04 API e reverse engineering — Capire la piattaforma osservandone il traffico
05 Asincronia JavaScript — Eventi, Promise, timeout e race condition
06 Stato, cache e storage — Dove vive la verità
07 Autoplay come state machine
08 Trovare la prima attività incompleta — Euristiche, master call e fallback
09 Generare PDF, HTML ed EPUB nel browser
10 Un piccolo rich-text editor — Selection, Range, liste e callout
11 UI senza framework — Popup, menu fluttuante e sincronizzazione
12 Performance e memoria — Quando il browser diventa il nostro runtime
13 Chrome, Edge e Firefox — Una base comune, runtime diversi
14 Debug, test e regressioni — Trasformare un bug in conoscenza permanente
15 Git, branch, PR, build e release engineering — Il software oltre il codice
16 Lezioni architetturali — I pattern emersi dal progetto reale
17 Cosa rifaremmo diversamente oggi? — Una retrospettiva senza senno di poi

Sono inclusi anche il Glossario e le Fonti e riferimenti.

Percorsi di studio

Non è obbligatorio leggere tutto in ordine.

Fondamenti di browser extension
01 → 02 → 03 → 06 → 13

Architettura e asincronia
02 → 05 → 06 → 07 → 08 → 12 → 16 → 17

Document generation
05 → 09 → 12

Software engineering
14 → 15 → 16 → 17

Come leggere gli esempi

I capitoli riportano estratti e riferimenti al codice reale di PlumePilot. Le versioni di riferimento sopra servono a rendere stabile il contesto storico: il progetto continuerà a evolversi, mentre il libro conserva le decisioni studiate nel momento in cui sono state prese.

I diagrammi Mermaid sono leggibili direttamente su GitHub; il testo resta comunque autosufficiente anche quando un renderer non li visualizza graficamente.

Correzioni e contributi

Se trovi un errore tecnico, un link rotto o un passaggio poco chiaro, puoi aprire una GitHub Issue o proporre una pull request sul repository.

Inizia da: 00 — Introduzione: dal problema al prodotto

Edizione offline

L’edizione HTML offline contiene l’intero libro in un singolo file e non carica risorse remote. Tema e ultima posizione di lettura vengono salvati soltanto nel browser locale. I diagrammi Mermaid rimangono disponibili come sorgente leggibile nell’HTML offline; GitHub li renderizza graficamente nelle pagine Markdown del repository.

Rigenerare l’HTML

L’edizione offline è generata dai capitoli Markdown. Con Node.js e Pandoc installato:

node scripts/build-inside-plumepilot.mjs

Il comando ricostruisce docs/inside-plumepilot/Inside-PlumePilot.html; i file Markdown restano la sorgente canonica.