docs: draw the menus the application actually has - #162
Merged
Merged
Conversation
The diagram that opened the README described a first-level menu of BIP-39 / SSKR / BIP-85 / Version / Quit -- three formats and two entries that are not menu entries. That menu is on neither of the two interfaces this application draws, and it was the first thing a reader saw. Same shape as before: one figure per interface, laid out as the file already lays its diagrams out -- titled subgraphs chained left to right, numbered nodes, a nested subgraph for the stage that is one, and a diamond where the application rather than the user decides what comes next. Each verdict forks, as the old diagram's did: the failing arm is drawn, not implied. Two figures rather than one, and the reason is not that the menus have different lengths. The touch devices put four intentions behind the home page's action button, with the version, the copyright and Quit on the home page itself; the Nanos have a single flow where Version and Quit are steps beside the three intentions rather than behind them, and no BIP-85 at all -- src/bagl holds not one BIP-85 screen. A single diagram would have carried a conditional branch at almost every node. The Nano figure keeps the five chained columns the old diagram had, and that is not nostalgia: three intentions, then Version, then Quit is exactly what ux_idle_flow walks. The old diagram had the right shape for the wrong stack. Every box is a screen that exists, named with the words that screen shows: no function names, and no format names the interface no longer says out loud. Every label is a single line, and that is a rendering constraint rather than a preference. Drawn on GitHub, the multi-line labels came back with their words glued together at each break -- "Your Phraseis not valid,doesn't matchor is correct". Neither mermaid generation reproduces it locally, with GitHub's own securityLevel and its own sanitiser replayed over the output, so rather than guess at a renderer that cannot be observed from here, the diagrams no longer contain a single line break: the renderer wraps what is too long by itself, and every wrap then falls on a real space. That costs width, so the review screens carry their values on one row and a few sentences are shortened to pay for it. The explanations that open each journey are in, because skipping them would misrepresent what the user walks through; the review pages and the warnings that end them are in for the same reason, as is the confirmation that stands in front of erasing the Shares. The verdict is drawn with its three outcomes -- invalid, doesn't match, valid -- where the old diagram knew two, and the fourth BIP-85 application, the PIN, is present. Both figures were rendered and looked at, not just read, under the two mermaid generations that matter: they do not lay out identically, so the older one is the one to trust for what GitHub draws.
They were added in one commit in July 2024 and they show the menus the application had then -- "Check BIP39 & Generate SSKR", "Check SSKR & Recover BIP39" -- on Nano S and Stax. Their README presented them as "animations of some of the menu flows", present tense, with no date. Kept rather than replaced. There is no versioned tool here that produces them, so replacing them means writing one and then re-recording four devices instead of two, in a directory that already weighs 9.8 MB in a tracked tree; the same objection that closed a snapshot pull request before would apply, and would be right. Nothing in the test suite reads these files, so what they cost is the tree's weight and nothing else. The README now dates them, says which interface they show, and points at the current diagrams and at the functional tests, which do walk the live screens on every supported device.
Every link in this file has been broken since the file was added: the
lines start with a stray ")](" -- the "[
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
2 participants
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.
Three documentation fixes, no code touched.
The menu diagram described a menu that is on neither interface
The diagram that opened the README showed a first-level menu of BIP-39 /
SSKR / BIP-85 / Version / Quit — three formats and two entries that are not
menu entries. It is replaced by one figure per interface, because the two do
not arrange their utilities the same way:
action button, with the version, the copyright and Quit on the home page
itself.
beside the three intentions rather than behind them, and no BIP-85 at all —
src/baglholds not one BIP-85 screen.A single diagram would have carried a conditional branch at almost every node.
Every box is a screen that exists, named with the words that screen shows.
Each verdict forks, so the failing arm is drawn rather than implied, and the
verdict carries its three outcomes — invalid, doesn't match, valid — where the
old diagram knew two. The fourth BIP-85 application, the PIN, is present.
Labels are single-line on purpose: rendered on GitHub, multi-line mermaid
labels came back with their words run together. Both figures were rendered and
looked at under the mermaid generation GitHub uses, which does not lay out
identically to the current one.
The animations were undated and show a former interface
tests/functional/screenshots/holds recordings from July 2024 showing menusthe application no longer has ("Check BIP39 & Generate SSKR"), presented in
the present tense with no date. They are kept rather than re-recorded — that
directory already weighs 9.8 MB in a tracked tree and nothing in the test
suite reads it — but their README now dates them, says which devices they
show, and points at the current diagrams and at the functional tests.
Every link in demos/README.md was broken
The lines start with a stray
)](— the[![that opens a thumbnail linkingto a video was lost in a paste — so four videos rendered as two bare URLs and
a bracket. Three of the four thumbnails also pointed at a
demosbranch thatdoes not exist; all three returned 404. The thumbnails are in that directory,
so the links now use them. The five video URLs and the four thumbnails were
checked and all respond.