Repository navigation
Guide: readable screenshots, step summaries, formatting, smoother zoom - #1
Merged
Merged
Conversation
The HTML guide put text and images in one 860px column. A full-window screenshot (2320px) showed at a third of its size, so the UI text in it could not be read. Showing images at full window width fixed the size but made the page hard to follow: huge images next to small text. Now: - the page column is 1100px; step text keeps an 860px reading width - each image is indented to start where its step text starts, so it reads as part of that step rather than a separate block - the step number and the first line of text share one 28px height, so the number sits centred on the line instead of a few pixels off - an image shown smaller than its real size can be clicked to open at full size on a dark overlay, which fades and scales in over 0.2s (no animation with prefers-reduced-motion); a click or Esc closes it - step text is regular weight at 1.15rem instead of bold 1.3rem, so the screenshots carry the page Printing and PDF keep the old full-width, unindented images; the overlay is hidden in print. Tested: tests/test_export.py passes (20 passed, 1 skipped). In headless Chromium at 1920px, dark scheme, an 18-step guide: number centre 216.8px vs first text line 216.3px; image left edge equals text left edge (476px); no sideways scrolling; the overlay is at opacity 0.58 after 80ms, 1 when open, and hidden after Esc. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A guide step had one text field, so a step was either a terse line or a long paragraph with the action buried in it. A reader skimming the guide could not see what each step does at a glance. A step can now carry a "title": a short summary shown in bold next to the number, with the "text" below it as the explanation and the image under both. Steps without a title render exactly as before. Markdown writes the title in bold as the list item; the Pillow PDF fallback puts it on the first line. Tested: tests/test_export.py passes (21 passed, 1 skipped), including a new test for the HTML and Markdown output. In headless Chromium at 1920px, a nine-step guide with titles has the title, the explanation and the image starting at the same left edge (476px), no sideways scrolling. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Step text was plain, so a guide could not show a button name in bold, a field or command as code, or a short list of options under a step. Those had to be crammed into one sentence. Step text now takes a small Markdown subset: **bold**, `code`, and lines starting with "- " as a list. In HTML they render inside the step, indented under its number; Markdown keeps them as written, with a blank line after a list so the next sentence does not join its last item; the Pillow PDF fallback drops the marks and draws list lines as bullets. A step without a title keeps its text in the heading, with bold and code but no list. Tested: tests/test_export.py passes (22 passed, 1 skipped), with a new test for all three marks in HTML, Markdown and PDF. The full suite has one failure, tests/test_privacy.py::test_dom_fixture, which also fails on the commit before this one. Rendered a demo step in headless Chromium, dark scheme: code text is 15.3px. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…verlay The zoom opened the image at its real pixel size, so a wide screenshot needed sideways scrolling to read, and the near-black overlay hid the guide completely, so it felt like leaving the page. The zoomed image now scales down to fit the window in both directions, and the overlay is 70% black, so the guide stays faintly visible behind. Tested: tests/test_export.py passes. In headless Chromium a 2320px screenshot opens at 1872x647 in a 1920x1080 window and 1318x456 in 1366x768, with no scrolling in either direction. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Agents write steps.json from this reference, so without it they would never use the bold summary or the bold, code and list formatting that guide steps now support. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
visul
approved these changes
Oct 10, 2026
visul
left a comment
visul
left a comment
Contributor
There was a problem hiding this comment.
Thanks, this is a real improvement for full-window captures. Reviewed the diff: text is escaped before the bold/code formatting, print and PDF stay unchanged, and the full test suite passes locally with both PRs merged (584 passed, web tests excluded). Merging.
visul
added a commit
that referenced
this pull request
Oct 10, 2026
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Guides with full-window screenshots were hard to read: the 860px column shrank a 2320px capture to a third of its size, and each step was one bold paragraph.
Same 9-step Microsoft Foundry guide, same screenshots, built before and after this change:
Before
After: a bold summary per step, the explanation underneath with bold,
codeand short lists, and the picture indented under its number.Click a picture to see it as large as the window allows. It fades in over a dimmed page; a click or Esc closes it.
What changes:
"title"(the bold summary). Steps without one render as before.**bold**,`code`and-lists. Markdown keeps them as written; the Pillow PDF fallback draws plain text with bullets.skills/ainotate/references/spec.mdmentions the new fields, so agents use them.Tested:
tests/test_export.pypasses (22 passed, 1 skipped), with new tests for the title and the formatting. Checked in headless Chromium at 1920x1080 and 1366x768: no sideways scrolling on the page or in the zoom.tests/test_privacy.py::test_dom_fixturefails on Linux onmainas well.🤖 Generated with Claude Code