Knihovny a CDN v projektu pro prohlížeč

Požádáte Claude Code, aby vytvořil šachy v prohlížeči. Otevřete stránku: šachovnice je na místě, figurky jsou rozmístěné a pěšec poslušně následuje kurzor. Dá se hrát. Jenže na zkoušku ho posunete rovnou o tři políčka dopředu - a on tam zůstane. Pak zkusíte dvakrát po sobě táhnout černými. Stránka ani tentokrát nic nenamítá.

Před těmito dvěma tahy vypadal projekt skoro hotový. Teď se ukáže, že to hlavní ještě nefunguje: nikdo nekontroluje pravidla. Můžete agenta požádat, aby takový tah pěšcem zakázal. Hned potom ale budete muset řešit střídání tahů, šach, rošádu i proměnu pěšce. Po každé opravě zůstane otázka: na kterou podmínku jste ještě zapomněli?

V tu chvíli je dobré se zastavit a poohlédnout se po hotovém kódu pro tento úkol. Šachová pravidla už implementuje knihovna chess.js. Předáte jí tah a dostanete výsledek kontroly. Vlastní kód pak zajišťuje srozumitelné propojení: převezme tah ze šachovnice, ověří ho přes knihovnu a zobrazí správné rozmístění figurek.

Zbývá dostat knihovnu do prohlížeče a zapojit ji do stránky. Jednou z možností je načíst ji přes odkaz z CDN. Níže si ukážeme, jak to funguje a proč samotný odkaz v kódu ještě neznamená, že pěšec přestal táhnout kamkoli.

Co dělá knihovna

Knihovna je cizí kód, který připojíte ke svému projektu, abyste nemuseli znovu psát něco, co už někdo napsal. Přesně taková je chess.js: zná tahy jednotlivých figurek, ví, co znamená šach a rošáda, umí vypsat všechny povolené tahy z aktuální pozice a zjistit, zda už partie skončila.

A tady se snadno dostanete do pasti: připojíte knihovnu a čekáte, že hra začne fungovat. Jenže nezačne. Knihovna si pamatuje pravidla a aktuální pozici partie, nic nekreslí a vůbec netuší, že je na stránce nějaká šachovnice.

Podívejte se, co se stane při běžném tahu. Táhnete pěšce z e2 rovnou na e5. Rozhraní zachytí přetažení a propojovací kód se knihovny zeptá: "Je tento tah povolený?" Knihovna odpoví "ne" a propojovací kód vrátí figurku na e2. Pokud se nikdo nezeptá, pěšec klidně skončí na e5: stránce nic nebrání, aby ho tam vykreslila.

Obě větve končí stejným krokem: propojovací kód zobrazí pozici z knihovny. Po povoleném tahu už jde o novou pozici, po nepovoleném zůstane původní, takže se figurka vrátí na výchozí políčko.

Z toho plyne, jak zadání formulovat. Požadavek "připoj chess.js" lze splnit doslova: přibude řádek pro načtení a tím to skončí. Zadejte raději celé propojení: tah ze šachovnice se předá knihovně, její odpověď rozhodne, zda figurkou pohnout, a pozice po tahu se převezme ze stavu knihovny, ne z místa, kam jste pustili myš.

Jak prohlížeč získá kód přes CDN

Soubor knihovny musíte odněkud vzít. Můžete ho stáhnout a uložit vedle stránky, nebo v kódu stránky uvést odkaz na soubor v externí službě. Často se k tomu používá CDN (Content Delivery Network, síť pro doručování obsahu). Jde o síť serverů, které poskytují soubory uživatelům z různých míst. Přes CDN se doručují například obrázky, styly a JavaScriptové knihovny. V našem příkladu poskytuje soubor knihovny služba jsDelivr.

Když otevřete stránku, prohlížeč přečte její kód a narazí na odkaz na knihovnu. Vyžádá si soubor na této adrese, stáhne ho a pak spustí kód stránky, který knihovnu používá. Knihovna běží v prohlížeči uživatele. CDN doručí její kód; kontrola šachových tahů už probíhá na vašem zařízení.

Rámeček ve schématu odděluje prohlížeč od externí služby. Po načtení je knihovna uvnitř stránky a propojovací kód s ní pracuje přímo tam. Každý tah na CDN posílat nemusíte.

Připojení chess.js vypadá takto:

<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>

Důležité jsou tu tři detaily. První je type="module". Knihovna se načítá jako ES modul a Chess z ní získáte jen pomocí importu; běžný tag <script src="..."> stejný soubor nezpracuje - skončí chybou na export uvnitř souboru. Některé knihovny se dodávají i ve starší podobě bez modulů: tam stačí běžný tag a na stránce se sama objeví globální proměnná. chess.js takové sestavení nemá, takže je tu jediná možnost.

Druhým detailem je číslo verze přímo v adrese, chess.js@1.4.0. Způsob připojení a názvy metod se řídí dokumentací konkrétní verze uvedené v odkazu. Adresa bez čísla dříve či později povede k jinému souboru a kód napsaný podle starší dokumentace přestane fungovat.

A třetí detail, který snadno přehlédnete, je koncovka adresy /+esm. Není tam na ozdobu, ale žádá CDN, aby soubor připravila právě jako modul: bez ní přijde ze stejné adresy jiné sestavení a import nic nenajde.

Ověřit, že se knihovna opravdu načetla, můžete i bez toho, abyste dodělali celou hru. Přidejte pár řádků do stejného <script type="module"> a otevřete konzoli prohlížeče (záložka Console ve vývojářských nástrojích, F12 nebo Ctrl+Shift+I):

// bílý pěšec nemůže táhnout z e2 rovnou na e5
try {
  chess.move('e5')
} catch (error) {
  console.log('tah odmítnut:', error.message) // Invalid move: e5
}

chess.move('e4')          // tento tah knihovna přijme
console.log(chess.turn()) // b, na tahu jsou černí

Počáteční pozice v konzoli, odmítnutý tah a černí na tahu po e4 znamenají, že se soubor načetl a pravidla fungují. Teď už zbývá propojit je se šachovnicí.

A ještě jedna poznámka, ať nevznikají falešná očekávání. CDN neodstraňuje závislost na síti. Prohlížeč může znovu použít soubor z mezipaměti, tedy svou uloženou kopii, takže ho nemusí stahovat při každém otevření stránky. Pokud ale žádnou vhodnou kopii nemá a CDN není dostupná, knihovna se nenačte a hra nebude moci uplatnit její pravidla.

Jak to funguje ve spojení s Claude Code

Požadavek "připoj knihovnu přes CDN" nechává na agentovi několik rozhodnutí: odkud vzít soubor, jakou verzi zvolit, jak ji načíst na této stránce a jak potvrdit výsledek. Lepší je uvést tato rozhodnutí rovnou v zadání. Níže jsou prompty pro různé situace; nemusíte posílat všechny za sebou.

Vyberte odkaz pro připojení

Pokud agent navrhne knihovnu, nejprve ho požádejte, aby zjistil, jak ji připojit ve vašem projektu. Dostanete konkrétní adresu a vysvětlení, odkud se vzala.

Podívej se, jak je moje stránka sestavená a zda už používá chess.js.
V dokumentaci knihovny a služby jsDelivr najdi způsob načítání přes CDN,
vhodný pro prohlížeč. Navrhni URL s konkrétní verzí a vysvětli její části.
Přidej odkazy na dokumentaci. Zatím kód neměň.
Pokud dokumentaci nešlo ověřit, řekni to.

V odpovědi hledejte číslo verze, způsob připojení a důvod volby. Samotné "tady je funkční odkaz" nestačí: nepoznáte z něj, jestli agent adresu ověřil v dokumentaci a zda se soubor hodí pro vaši stránku.

Propojte knihovnu se šachovnicí

Jakmile je adresa vybraná, zadejte agentovi úkol s viditelným výsledkem. U jednoduché HTML stránky můžete rovnou říct, že chcete zachovat dosavadní způsob spuštění.

Připoj chess.js přes vybranou CDN adresu s pevně určenou verzí.
Zachovej dosavadní způsob spouštění stránky. Propoj knihovnu
se šachovnicí: předávej jí každý tah a zobrazuj pozici podle jejího stavu.
Při nepovoleném tahu vrať figurku na původní políčko.
Ukaž, kde se knihovna připojuje a kde se zpracovává její odpověď.

Jde o dva samostatné výsledky: prohlížeč získal knihovnu a tahy na šachovnici se začaly řídit jejími pravidly. Když požádáte o ukázku obou míst v kódu, uvidíte, co přesně agent přidal.

Ověřte výsledek v prohlížeči

Odkaz v HTML potvrzuje pouze úpravu souboru. Následující zadání pomůže ověřit samotné načtení i chování hry.

Otevři stránku a na záložce Network ve vývojářských nástrojích
ověř, že se chess.js načetla. Zkontroluj chyby v Console. Pak z počáteční
pozice zkus e2-e5: tah má být odmítnut a pěšec má zůstat na e2.
Potom zahraj e2-e4: tah má projít a na tahu mají být černí.
Popiš, co jsi při každém kroku pozoroval. Pokud nemáš přístup k prohlížeči,
napiš mi stručný postup kontroly a uveď, že jsi ji sám neprovedl.

Na záložce Network uvidíte síťové požadavky stránky, v Console zase zprávy a chyby jejího kódu. Pokud se soubor načetl, ale pěšec přesto dojde na e5, hledejte příčinu ve zpracování tahu. Samotná výměna odkazu na CDN toto propojení neopraví.

Vyřešte chybu při načítání

Když se něco pokazí, předejte agentovi přesné znění chyby z Console a adresu neúspěšného požadavku z Network. Může tak ověřit konkrétní příčinu místo zkoušení různých odkazů.

Po připojení knihovny stránka hlásí chybu.
Text z Console: [vložte celou zprávu].
URL a výsledek požadavku v Network: [vložte adresu a stav].
Ověř, zda je soubor dostupný, zda jeho formát odpovídá našemu importu
a zda názvy v kódu souhlasí s dokumentací zvolené verze.
Nejprve podle těchto údajů urči příčinu, potom proveď minimální
opravu a kontrolu zopakuj. Neměň zároveň CDN, verzi i kód hry.

Text v hranatých závorkách nahraďte vlastními údaji. Pokud v Network vůbec není požadavek na knihovnu, řekněte to také: je to užitečná stopa. Po opravě zopakujte kontrolu obou tahů a ověřte, že funguje celé propojení.

Počítejte s nedostupnou CDN

Pokud se knihovna nenačte, šachovnice, která vypadá aktivně, může vzbudit mylný dojem, že se dá hrát. Požádejte agenta, aby tento stav uživateli srozumitelně ukázal.

Ošetři situaci, kdy se chess.js nepodaří načíst z CDN.
Dokud knihovna není připravená, nedovoluj tahy. Při chybě zobraz
srozumitelnou zprávu a možnost zkusit stránku načíst znovu.
Ověř chování při zablokovaném požadavku na CDN a potom po
odstranění blokace. Počítej s mezipamětí: pouhé odpojení od sítě může
ponechat dostupnou dříve načtenou kopii. Popiš, jak přesně jsi chybu ověřil.

Takovou kontrolu je lepší provést zvlášť, mimo běžnou partii. Výsledkem mají být dva srozumitelné stavy: knihovna je dostupná a tahy se ověřují; načtení se nezdařilo a stránka vysvětluje, proč zatím nelze hrát.