Fix ILink.OBJPAGE and LINKTYPE doc comments to match observed data - #36
Merged
Conversation
Both were verified wrong against real device-created notes (see #32): - OBJPAGE ("0-indexed page number this link appears on") doesn't match a link's actual source page under any indexing convention. In this repo's own nomad-3.26.40-link-tag-3p.note fixture, 3 links on the same source page have 3 different OBJPAGE values (1, 2, 0). - LINKTYPE ("1 = internal note link") doesn't reliably distinguish real internal links either -- 2 of that same fixture's 3 links have LINKTYPE: '0', and everything in SupernoteX.links is already a resolved link regardless of this value. What's actually reliable: the SupernoteX.links Record key's first 4 characters, read as an integer, are the link's 1-indexed source page. Documents that in _parseLinks()'s comment, and adds a regression test against the existing fixture pinning both the key-prefix convention and OBJPAGE's unreliability, so a future "fix" to OBJPAGE's doc comment can't silently drop the fact that it disagrees with the key prefix on this repo's own test data.
philips
marked this pull request as ready for review
July 28, 2026 20:54
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.
Summary
Fixes #32. Both
ILink.OBJPAGEandILink.LINKTYPE's doc comments claimed things that don't hold on real device-created notes:OBJPAGE(doc comment: "0-indexed page number this link appears on") — doesn't match a link's actual source page under any indexing convention. Verified two ways:tests/input/nomad-3.26.40-link-tag-3p.notefixture, all 3 links are drawn on the same source page, yet have 3 differentOBJPAGEvalues (1,2,0).toImage(), drew each link'sLINKRECTon every page, and measured ink coverage to find each link's true source page directly —OBJPAGEdidn't match under 0- or 1-indexing either.LINKTYPE(doc comment: "1 = internal note link") — doesn't reliably distinguish real internal links. 2 of that same fixture's 3 links haveLINKTYPE: '0', and everything present inSupernoteX.linksis already a resolved, genuine link regardless of this value.What's actually reliable: the
SupernoteX.linksRecord key's first 4 characters, read as an integer, are the link's 1-indexed source page (verified against the same real notes above; the remaining characters are the link's ownLINKRECTy,x,h,wdigits, zero-padded and concatenated, just to keep same-page keys unique). This wasn't documented anywhere, so_parseLinks()insrc/parsing.tsnow documents it, and bothILinkdoc comments are corrected/softened to stop claiming the wrong thing and point at it instead.Also adds a regression test against the existing fixture pinning both the key-prefix convention and
OBJPAGE's unreliability (3 links, same source page, 3 differentOBJPAGEvalues) — so a future doc-comment "fix" can't silently drop the fact that it disagrees with the key prefix on this repo's own test data.Not included: a new fixture with links on more than one source page (the issue notes this repo's existing fixture happens to put every link on the same page, which is what let this go unnoticed). The real multi-page-link note used to verify
OBJPAGEin the issue is external/personal and not available here; fabricating an equivalent.notebinary by hand felt too error-prone to be worth it for a doc-comment fix. Flagging in case a real multi-page fixture becomes available later.Test plan
npm run build(tsc) succeedsnpm run lintpassesnpm test— full suite passes (36/36), including the new regression test