# Sady: záznam a publikování (https://docs.vitrinka.ai/cs/dev/cli/sets) ## Založení sady [#init] Vytvoří v repozitáři `.vitrinka` konfiguraci sady, aby pushe věděly, kam míří. ```bash vitrinka board init ``` ## Pořízení snímku [#capture] Pořídí snímek rovnou do sady a na pozadí ho nahraje — jen nový soubor, který se během pár sekund objeví na nástěnce sady. Umí řídit iOS simulátor, Android emulátor nebo macOS, případně převzít obrázek, který už máte. Webový snímek se vždy přebírá: pořiďte ho vlastním nástrojem prohlížeče — browser MCP, skriptem v Playwrightu — a soubor předejte přes `--file`. `capture safari --url ` místo toho řídí Mobile Safari v iOS Simulátoru přes Appium, v jednom ze šesti stavů `--state` (`default`, `keyboard`, `scrolled`, `scroll-end`, `landscape`, `overscroll`) — klávesnice se opravdu otevře, stránka se opravdu posune — a naměřené safe-area insety putují spolu se snímkem. ```bash vitrinka board capture web \ --file checkout.png \ --viewport 1440x900 \ --route /checkout \ --note "sleva se počítá dvakrát" \ --url https://localhost:3000/checkout ``` `--note` a `--route` jsou povinné: snímek bez obojího je obrázek, který nikdo nezařadí. ## Přepínače pro capture [#capture-flags] | Přepínač | Co dělá | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--route` | **Povinné.** Routa aplikace, na které snímek vznikl. | | `--note` | **Povinné.** Popisek. | | `--title` | Lidský název — zároveň pojmenuje soubor. | | `--label` | Stabilní označení snímku. Míří na něj propojení cest. | | `--next` | Větev cesty: označení cílového snímku. Lze opakovat. | | `--action` | Co se na této obrazovce udělalo; po `--next` popisek drátu této větve. | | `--target` | JSON bbox `{x,y,w,h}` prvku, na který se kliklo — následuje po `--next`. | | `--open` | Deep link, který se otevře před pořízením snímku — simulátory, emulátory a macOS; nikdy spolu s `--file`. | | `--settle` | Kolik sekund počkat. Výchozí 4 s `--open`, jinak 0. | | `--viewport` | `WxH` nebo `WxH@scale`, např. `393x852@3`. U webového snímku CSS viewport stránky. | | `--hidpi` | Web: drží soubor na 2×, když je znám `--viewport`. Výchozí: `capture.hidpi` repozitáře, zapnuto; `--hidpi=false` promine tento jeden snímek — [níže](#hidpi). | | `--device` | Název zařízení. | | `--udid` | UDID iOS simulátoru. | | `--region` | Oblast pro macOS, `x,y,w,h`. | | `--file` | Převezme existující obrázek místo pořízení nového. | | `--hq` | Plná kvalita: bez ztrátové rekomprese a bez zmenšení. | | `--boxes` | Textová mapa z runneru v pixelech zdrojového obrázku (výchozí: `.boxes.json` převzatého obrázku) — [nástroje pro review](/cs/qa/review-toolkit#boxes). | | `--src` | Zdrojový soubor, který to implementuje. Lze opakovat nebo oddělit čárkami. | | `--state` | Významný stav aplikace nebo přihlášení. | | `--url` | Adresa původu — v manifestu má přednost před `--open`. | | `--root` | Kořen záznamu. Výchozí `.vitrinka/screenshots`. | ## Webové snímky ve 2× [#hidpi] Webové snímky mají dvojnásobné měřítko zařízení — v Playwrightu `deviceScaleFactor: 2` — aby nástěnka na retina displeji zůstala ostrá. Když je zadaný `--viewport WxH`, `capture web` odmítne soubor užší než dvojnásobek té šířky s kódem `quality_gate` a odpověď pojmenuje nové pořízení i obě cesty ven; bez `--viewport` se měřítko posoudit nedá a snímek projde. Pravidlo patří repozitáři: `capture.hidpi` v commitnutém `vitrinka.config.json`, zapnuté, pokud není nastaveno jinak. Snímky ze simulátoru, emulátoru a macOS už mají nativní rozlišení a nikdy se nekontrolují ani nezmenšují. ```bash vitrinka config hidpi # ukáže nastavení repozitáře vitrinka config hidpi off # pustí 1× webové soubory všem v tomto repozitáři ``` ## Odeslání sady [#push] Synchronizuje kořen záznamu se sadou soubor po souboru: nahraje se jen to, co nasazení ještě nemá. Push jen přidává — snímky, které sada má a složka ne (čerstvý worktree, vyčištěná složka), zůstanou a push řekne, kolik jich je. Idempotentní — opakované spuštění nic nového nepošle. Nahrávání na pozadí, které selhalo, protože jste byli offline nebo ho server odmítl, nechá v kořeni záznamu diagnózu a opravu; další snímek ji jednou vypíše a další push pošle jen to, co chybí. Sady s artefaktem (`doc.json`) jdou dál jako jeden archiv, stejně jako každý push na nasazení bez dveří pro jednotlivé soubory — to celou sadu nahradí obsahem složky. Snímky smažete tak, že je odstraníte lokálně a pushnete s `--prune`: sada pak zrcadlí složku. Když by prune smazal snímky, které karty na boardu ještě ukazují, nasazení ho odmítne a nabídne `board pull`; `--confirm` je smaže i tak. Push do artefaktu, který někdo smazal, je odmítnut (`artifact_deleted`) — smazání bylo rozhodnutí a opakovaný push ho nesmí vrátit. Odmítnutí odkazuje na stránku artefaktu, kde ho **Restore** obnoví; nebo pushněte s `--revive` a publikujte ho znovu na stejné stránce. Po 30 dnech v koši je odstraněn a klíč je opět volný. ```bash vitrinka board push --title "Košík — třetí kolo" ``` | Přepínač | Co dělá | | ------------- | ---------------------------------------------------------------------------------------------------------------- | | `--root` | Kořen záznamu. Výchozí `.vitrinka/screenshots`. | | `--title` | Lidský název, posílá se při každém pushi. | | `--source` | Prováže zdrojovou sadu: `project/branchSlug/key`. | | `--no-fix` | Přeskočí preflight autoopravu doc.json (poškozený JSON; starší soubor `{meta, blocks}` přepsaný na element doc). | | `--no-render` | Přeskočí serverový smoke render po publikování i stažení jeho `render.png`. | | `--no-design` | Přeskočí odeslání `DESIGN.md` z repozitáře při pushi artefaktu. | | `--prune` | Zrcadlí složku: smaže soubory sady, které složka už nemá. | | `--revive` | Publikuje do artefaktu, který byl smazán: jeho stránka se vrátí na stejnou adresu, místo aby byl push odmítnut. | ## Stažení sady [#pull] Kořen záznamu žije v jednom worktree, sada ho přežije. `pull` obnoví soubory sady do kořene, takže čerstvý worktree v sadě pokračuje místo prázdné složky. Soubory, které kořen už má, se nikdy nepřepíšou, a `manifest.json` se sloučí — nejdřív snímky sady, pak vlastní snímky složky. Bez deskriptoru v kořeni sadu určí `--project`, `--branch` a `--key` jako u `board init`. ```bash vitrinka board pull --branch feature/checkout --key 2026-09-26 ``` ## Pojmenování a rámec [#meta] `meta` nastaví hlavičku cesty — kicker, název, akcent, úvod a chipy. `rename` dá sadě stabilní vlastní jméno, takže čitelná adresa funguje vedle číselné. ```bash vitrinka board meta --title "Košík" --kicker "třetí kolo" vitrinka board rename myapp/main/7 payout-flow ``` ## Dokumenty a stránky [#docs] Sada může místo galerie nést dokument: `doc.json` z elementů v kořeni sady a sourozenecké stránky pod `pages/.json`. Push zpracuje celý strom jedním požadavkem: * **Preflight** — `doc.json` se před nahráním ověří proti slovníku elementů téhle instalace; poškozený JSON se automaticky opraví a starší soubor `{meta, blocks}` se přepíše na element doc, pokud nepředáte `--no-fix`; skutečná chyba kontraktu push zastaví s pojmenovaným elementem. * **Ze stránek jsou karty** — každý `pages/.json` se vyrazí jako sourozenecká karta dokumentu, odkazy `page:` uvnitř elementů `ref` se přepíšou na id karet a opakovaný push id zachová, takže odkazy zůstávají stabilní. * **Smoke render** — push artefaktu odpoví s `render.png` výsledku, takže se agent může podívat na to, co odeslal, aniž by otevíral prohlížeč. Slovník samotný — každý druh elementu s jeho obsahem — je [reference elementů](/cs/reference/elements); jak se dokumenty vnořují a rozkládají, popisuje [skládání nástěnek](/cs/dev/compose). ## Artefakty [#artifact] Artefakt je samostatná interaktivní stránka, ne galerie. `init` ji připraví i s konfigurací sady, `create` postaví report z existující sady snímků. ```bash vitrinka board artifact init --slug checkout-report vitrinka board artifact create --slug checkout-report --from ./captures ```