Expand description
The preview guide (fleet rule work.preview-is-guided): what the person
reads before they are asked to approve a preview.
The person works on several projects at once and does not remember where
this one stood, so “Ship repo@sha?” alone gives them nothing to decide
with. preview register therefore takes a markdown guide, refuses one
that lacks a required section (check), and renders it to a small,
self-contained HTML page beside it (render).
The converter is hand-rolled on purpose, for the constrained subset a
guide needs: headings, paragraphs, bullet and numbered lists (one level of
nesting), fenced code, block quotes, and inline bold, code, links, images
and bare URLs. Everything else is text, and every text byte is escaped. A
markdown crate would be a new dependency on a trust path (ADR-0020,
change.dependency-bar) for a page nobody but the person reads.
Structs§
- Guide
- A parsed guide: what precedes the first H2, and each section.
- Page
- What the page is made from.
- Proof
- A design image and the built screen it is compared with, for one state.
Constants§
- DIFFERENCES
- The section a guide adds when its commit carries a picked mockup.
- MAX_
BYTES - A guide larger than this is not a guide.
- SECTIONS
- The sections a guide must carry, as H2 headings, in the order the page shows them.
Functions§
- check
- What a guide lacks, one line each; empty when it is complete.
- check_
mockup - What a guide lacks in mockup mode — its commit carries the picked
artboards of
screens— on top ofcheck. Images resolve againstfolder, the guide’s own. - escape
- file_
url - A
file://URL for an absolute path, percent-encoded. A Windows verbatim prefix (\\?\) is dropped and backslashes become slashes. - images
- Every image source the guide references, in order.
- missing_
images - Relative image sources that do not exist beside the guide.
- parse
- png_
width - Width of a PNG, from its IHDR chunk;
Nonefor anything else. - proofs
- The design/built pairs, matched by what their names share besides the
role word:
artboard.pngwithafter.png,artboard-empty.pngwithlive-empty.png. - render
- The guide as one self-contained HTML page: inline CSS, no script, no external asset; images are the guide’s own, relative to the page.
- width_
warnings - Pairs whose two PNGs differ in width by more than a tenth: a divergence would read as a scaling difference.