Biblioteci și CDN într-un proiect pentru browser

Îi cereți lui Claude Code să facă un joc de șah în browser. Deschideți pagina: tabla e acolo, piesele sunt așezate, iar pionul urmează cuminte cursorul. Puteți juca. Dar, ca să verificați, îl mutați direct trei pătrățele înainte - și rămâne acolo. Apoi încercați să mutați de două ori la rând cu piesele negre. Pagina nu protestează nici de data asta.

Până la aceste două mutări, proiectul părea aproape gata. Acum se vede că partea esențială nu funcționează: nimeni nu verifică regulile. Îi puteți cere agentului să interzică o astfel de mutare a pionului. Dar apoi va trebui să rezolvați și ordinea mutărilor, șahul, rocada și transformarea pionului. După fiecare corectare rămâne aceeași întrebare: ce regulă ați mai uitat?

Aici merită să vă opriți și să căutați cod gata făcut pentru această sarcină. Regulile șahului sunt deja implementate în biblioteca chess.js. Îi puteți trimite o mutare și primi rezultatul verificării. Codul dumneavoastră se ocupă atunci de legătura simplă: preia mutarea de pe tablă, o verifică prin bibliotecă și afișează poziția corectă a pieselor.

Mai rămâne să aduceți biblioteca în browser și s-o integrați în pagina web. O variantă e s-o încărcați printr-un link de la un CDN. Mai jos vedem cum funcționează și de ce un link apărut în cod nu înseamnă, prin el însuși, că pionul nu mai poate merge oriunde.

Ce face biblioteca

O bibliotecă este cod scris de altcineva, pe care îl conectați la proiect ca să nu rescrieți lucruri deja implementate. chess.js e un exemplu bun: știe cum se mută fiecare piesă, ce înseamnă șahul și rocada, poate enumera toate mutările legale din poziția curentă și vă spune dacă partida s-a încheiat.

Și aici e ușor să cădeți în capcană: conectați biblioteca și așteptați ca jocul să funcționeze. Nu va funcționa. Biblioteca ține în memorie regulile și poziția partidei; nu desenează nimic și nici nu știe că pe pagină există o tablă.

Uitați-vă ce se întâmplă la o mutare obișnuită. Trageți pionul de pe e2 direct pe e5. Interfața detectează mutarea, iar codul de legătură întreabă biblioteca: "Este legală mutarea asta?" Biblioteca răspunde "nu", iar codul de legătură pune piesa înapoi pe e2. Dacă nimeni nu pune întrebarea, pionul ajunge liniștit pe e5: pagina nu are niciun motiv să nu-l deseneze acolo.

Ambele ramuri se încheie cu aceeași acțiune: codul de legătură afișează poziția din bibliotecă. După o mutare legală, poziția e nouă; după una ilegală, rămâne cea veche, așa că piesa revine pe pătrățelul inițial.

De aici rezultă cum e bine să formulați sarcina. Cererea "conectează chess.js" poate fi îndeplinită literal: apare o linie de încărcare și atât. Cereți legătura completă: mutarea de pe tablă ajunge la bibliotecă, răspunsul ei decide dacă piesa se mută, iar poziția de după mutare vine din starea bibliotecii, nu din locul unde ați lăsat cursorul.

Cum primește browserul codul prin CDN

Trebuie să luați fișierul bibliotecii de undeva. Îl puteți descărca și pune lângă pagina dumneavoastră sau puteți indica în cod un link către fișierul găzduit de un serviciu extern. Pentru asta se folosește des un CDN (Content Delivery Network, rețea de distribuție a conținutului). Este o rețea de servere care livrează fișiere utilizatorilor din locuri diferite. Prin CDN se livrează, de exemplu, imagini, stiluri și biblioteci JavaScript. În exemplul nostru, fișierul bibliotecii este livrat de jsDelivr.

Când deschideți pagina, browserul îi citește codul și găsește linkul către bibliotecă. Cere fișierul la adresa respectivă, îl descarcă, apoi execută codul paginii care folosește biblioteca. Biblioteca rulează în browserul utilizatorului. CDN-ul îi livrează codul; verificarea mutărilor de șah se face deja pe dispozitivul dumneavoastră.

Cadrul din schemă separă browserul de serviciul extern. După încărcare, biblioteca se află în pagină, iar codul de legătură o folosește de acolo. Nu e nevoie să trimiteți fiecare mutare la CDN.

Conectarea lui chess.js arată așa:

<script type="module">
  import { Chess } from 'https://cdn.jsdelivr.net/npm/chess.js@1.4.0/+esm'

  const chess = new Chess()
  console.log(chess.fen())
  // rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
</script>

Contează trei detalii. Primul este type="module". Biblioteca vine ca modul ES, iar Chess poate fi preluat doar prin import; eticheta obișnuită <script src="..."> nu poate interpreta același fișier și dă eroare la export-ul din interiorul lui. Unele biblioteci au și o formă mai veche de livrare, fără module: acolo e suficientă eticheta obișnuită, iar pe pagină apare automat o variabilă globală. chess.js nu are un astfel de build, deci există o singură variantă.

Al doilea detaliu este numărul versiunii chiar în adresă, chess.js@1.4.0. Modul de conectare și numele metodelor trebuie luate din documentația versiunii indicate în link. Mai devreme sau mai târziu, o adresă fără număr va duce la alt fișier, iar codul scris după documentația veche nu va mai funcționa.

Al treilea detaliu, cel mai ușor de trecut cu vederea, este sufixul /+esm de la sfârșitul adresei. Nu e un ornament, ci o cerere către CDN să genereze fișierul ca modul. Fără ea, aceeași adresă livrează altă variantă, iar import nu găsește nimic.

Puteți verifica dacă biblioteca s-a încărcat fără să construiți tot jocul: adăugați câteva linii în același <script type="module"> și deschideți consola browserului (fila Console din instrumentele pentru dezvoltatori, F12 sau Ctrl+Shift+I):

// pionul alb nu poate merge direct de pe e2 pe e5
try {
  chess.move('e5')
} catch (error) {
  console.log('mutare respinsă:', error.message) // Invalid move: e5
}

chess.move('e4')          // biblioteca acceptă această mutare
console.log(chess.turn()) // b, urmează piesele negre

Poziția inițială în consolă, mutarea respinsă și faptul că după e4 urmează piesele negre arată că fișierul s-a încărcat și regulile funcționează. Mai rămâne să le legați de tablă.

Și o precizare, ca să nu vă faceți iluzii: CDN-ul nu elimină dependența de rețea. Browserul poate reutiliza fișierul din cache, din copia salvată local, deci nu trebuie să-l descarce din nou la fiecare deschidere a paginii. Dar dacă nu există o copie potrivită și CDN-ul nu este disponibil, biblioteca nu se va încărca, iar jocul nu va putea folosi regulile ei.

Cum funcționează împreună cu Claude Code

Cererea "conectează biblioteca prin CDN" îi lasă agentului câteva decizii: de unde ia fișierul, ce versiune alege, cum o încarcă în această pagină și cum confirmă rezultatul. E mai simplu să precizați aceste lucruri direct în sarcină. Mai jos sunt prompturi pentru situații diferite; nu trebuie să le trimiteți pe toate.

Alegeți linkul de conectare

Dacă agentul vă propune o bibliotecă, cereți-i mai întâi să afle cum se conectează la proiectul dumneavoastră. Veți primi o adresă concretă și explicația de unde provine.

Verifică cum este construită pagina mea și dacă chess.js este deja conectat.
Găsește în documentația bibliotecii și în jsDelivr metoda de încărcare prin CDN
potrivită pentru browser. Propune un URL cu o versiune precisă și explică
componentele adresei. Include linkuri către documentație. Nu modifica încă codul.
Dacă nu ai putut verifica documentația, spune-mi.

În răspuns căutați numărul versiunii, metoda de conectare și motivul alegerii. Un simplu "iată un link funcțional" nu ajunge: nu știți dacă agentul a verificat adresa în documentație și dacă fișierul se potrivește paginii dumneavoastră.

Conectați biblioteca la tablă

După ce ați ales adresa, dați-i agentului o sarcină cu rezultat vizibil. Pentru o pagină HTML simplă, puteți preciza de la început că vreți să păstrați metoda actuală de pornire.

Conectează chess.js folosind adresa CDN aleasă, cu versiune fixă.
Păstrează metoda existentă de pornire a paginii. Leagă biblioteca
de tablă: transmite-i fiecare mutare și afișează poziția din starea ei.
La o mutare ilegală, pune piesa înapoi pe pătrățelul inițial.
Arată unde ai adăugat conectarea și unde tratezi răspunsul bibliotecii.

Aici sunt două rezultate separate: browserul a primit biblioteca, iar mutările de pe tablă trec acum prin regulile ei. Dacă îi cereți agentului să arate ambele locuri din cod, veți vedea exact ce a adăugat.

Verificați rezultatul în browser

Prezența linkului în HTML confirmă doar modificarea fișierului. Sarcina următoare vă ajută să verificați încărcarea propriu-zisă și comportamentul jocului.

Deschide pagina și verifică încărcarea chess.js în fila Network
din instrumentele pentru dezvoltatori. Verifică erorile din Console. Apoi, din
poziția inițială, încearcă e2-e5: mutarea trebuie respinsă, pionul să rămână pe e2.
După aceea, fă e2-e4: mutarea trebuie acceptată, iar rândul să treacă la piesele negre.
Spune-mi ce ai observat la fiecare pas. Dacă nu ai acces la browser,
dă-mi pașii scurți de verificare și precizează că nu ai verificat personal.

Fila Network arată cererile de rețea ale paginii, iar în Console apar mesajele și erorile codului. Dacă fișierul s-a încărcat, dar pionul ajunge totuși pe e5, cauza trebuie căutată în tratarea mutării. Schimbarea linkului CDN nu va repara singură această legătură.

Investigați eroarea de încărcare

Dacă apare o problemă, transmiteți-i agentului textul exact al erorii din Console și adresa cererii eșuate din Network. Astfel poate verifica o cauză concretă, în loc să încerce linkuri la întâmplare.

După conectarea bibliotecii, pagina afișează o eroare.
Textul din Console: [inserați mesajul complet].
URL-ul și rezultatul cererii din Network: [inserați adresa și statusul].
Verifică dacă fișierul este disponibil, dacă formatul lui se potrivește importului
nostru și dacă numele din cod corespund documentației versiunii alese.
Mai întâi spune care este cauza pe baza acestor date, apoi fă o modificare
minimă și repetă verificarea. Nu schimba în același timp CDN-ul, versiunea și codul jocului.

Înlocuiți textul dintre paranteze pătrate cu datele dumneavoastră. Dacă cererea către bibliotecă nu apare deloc în Network, menționați și asta: e un indiciu util. După corectare, verificați din nou cele două mutări ca să vă asigurați că legătura completă funcționează.

Pregătiți-vă pentru indisponibilitatea CDN-ului

Dacă biblioteca nu s-a încărcat, tabla activă poate crea impresia falsă că încă se poate juca. Cereți-i agentului să facă această situație clară pentru utilizator.

Tratează situația în care chess.js nu se poate încărca de pe CDN.
Cât timp biblioteca nu este gata, nu permite mutări. La eroare, afișează
un mesaj clar și o opțiune de reîncărcare a paginii.
Verifică ce se întâmplă când cererea către CDN este blocată, apoi după
eliminarea blocării. Ține cont de cache: simpla deconectare de la rețea poate
lăsa disponibilă o copie încărcată anterior. Descrie exact cum ai testat eroarea.

E mai ușor să faceți această verificare separat de o partidă obișnuită. Ar trebui să vedeți două stări clare: biblioteca este disponibilă și mutările sunt verificate; încărcarea a eșuat, iar pagina explică de ce nu se poate juca momentan.