Sady: záznam a publikování

Založení sady

Vytvoří v repozitáři .vitrinka konfiguraci sady, aby pushe věděly, kam míří.

vitrinka board init

Pořízení snímku

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

vitrinka board capture web \
  --file checkout.png \
  --viewport 1440x900 \
  --route /checkout \
  --note "sleva se počítá dvakrát" \
  --url https://localhost:3000/checkout

Přepínače pro capture

Webové snímky ve 2×

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

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

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

vitrinka board push --title "Košík — třetí kolo"

Stažení sady

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.

vitrinka board pull --branch feature/checkout --key 2026-09-26

Pojmenování a rámec

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

vitrinka board meta --title "Košík" --kicker "třetí kolo"
vitrinka board rename myapp/main/7 payout-flow

Dokumenty a stránky

Sada může místo galerie nést dokument: doc.json z elementů v kořeni sady a sourozenecké stránky pod pages/<slug>.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/<slug>.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ů; jak se dokumenty vnořují a rozkládají, popisuje skládání nástěnek.

Artefakty

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

vitrinka board artifact init --slug checkout-report
vitrinka board artifact create --slug checkout-report --from ./captures