Artifact

Rules for producing, checking and opening PDFs, HTML reports, slides and formulas. Check every artifact visually before showing it: text visible and legible, consistent, inside its borders.

Visual design check

Before showing a diagram, chart, slide or report: the primary takeaway is apparent at a glance to its audience; every accent colour carries information; every size or colour difference means something; elements sit on one grid and text aligns to its reading direction (right for Persian); steps and containers have room to breathe.

PDFs

• For a scanned PDF: run pdfinfo, then one pdftotext -layout check; if it is empty, render pages with pdftoppm to tmp/pdfs/ and inspect the PNGs at original detail.
• Keep a short inventory: page count, text-extraction result and what the pages contain.
• Stay local; use no online OCR or upload unless the user asks.
• After creating or editing a PDF the user will inspect, render a page to check it, then open it for the user with the environment's opener and confirm the viewer started.

HTML reports

• After creating or materially editing a user-facing HTML artifact, open it for the user unless they say not to. A screenshot or headless render verifies it; it does not replace opening it.
• Open HTML in Chromium. For a site folder, especially one with assets, scripts or maps, serve it locally: setsid python3 -m http.server <port> --directory <site-dir> >/tmp/<task>-server.log 2>&1 &, then open http://127.0.0.1:<port>/.... Use file:// only for a simple standalone page; if Chromium keeps loading, switch to the local server before saying it is open.
• Browser automation and screenshots are costly. Use cheaper local checks unless the UI, formulas or charts are new or materially changed; then do one visual pass before opening.
• Make alternative designs switchable in the HTML rather than describing them in chat.

Slides and print layout

• For browser-printed HTML slides, do not rely on .active styles: print mode often forces every .slide to display:flex, so put flex-direction, justify-content and gap on the base .slide class.
• Check layout by rendering the PDF pages, not by reading extracted text: spot-check the most layout-sensitive pages and make a contact sheet for the whole deck.
• In RTL decks with image and text split layouts, a grid inherits direction: rtl and reverses its columns. Set the split container to direction:ltr and the text area back to direction:rtl.
• For mixed Persian and English slide text, prefer Persian-led phrasing and isolate short English terms; long English-led bullets often render in broken order in PDF.

Formulas in HTML

• Browsers show raw TeX delimiters (\(...\), \[...\], $$...$$) as text unless a renderer or MathML is present.
• In handwritten HTML, write native MathML; Chromium and Firefox render it offline without JavaScript:

<div class="math-display">
  <math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
    <msub><mi>s</mi><mi>k</mi></msub><mo>=</mo>
    <munderover><mo>&#x2211;</mo><mrow><mi>j</mi><mo>=</mo><mn>0</mn></mrow><mi>k</mi></munderover>
    <msub><mi>p</mi><mi>r</mi></msub><mo>(</mo><msub><mi>r</mi><mi>j</mi></msub><mo>)</mo>
  </math>
</div>

Give .math-display direction: ltr and overflow: auto so wide formulas scroll inside RTL pages.

• From Markdown, or when hand-written MathML is too slow for a large document, convert with Pandoc and keep the .md beside the .html: pandoc input.md -s --mathml -c style.css -o output.html.
• MathJax or KaTeX is acceptable only when its script and CSS are included and verified; avoid CDN renderers unless network use is acceptable.
• A plain-text formula is acceptable only when the user does not need typeset math; explain ambiguous notation in words, for example that G_inverse(s_k) means the inverse CDF.
• Before delivery, confirm the formulas became MathML with no raw delimiters left, then open the page and check they render as math:

rg -n '<math' output.html | head
rg -n '\[|\]|\$\$' output.html | head