Skip to content

Fix ILink.OBJPAGE and LINKTYPE doc comments to match observed data - #36

Merged
philips merged 1 commit into
mainfrom
fix-link-doc-comments
Jul 28, 2026
Merged

Fix ILink.OBJPAGE and LINKTYPE doc comments to match observed data#36
philips merged 1 commit into
mainfrom
fix-link-doc-comments

Conversation

@philips-clanker

Copy link
Copy Markdown
Collaborator

Summary

Fixes #32. Both ILink.OBJPAGE and ILink.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:
    • In this repo's own tests/input/nomad-3.26.40-link-tag-3p.note fixture, all 3 links are drawn on the same source page, yet have 3 different OBJPAGE values (1, 2, 0).
    • The issue's author rendered a real 4-page note via toImage(), drew each link's LINKRECT on every page, and measured ink coverage to find each link's true source page directly — OBJPAGE didn'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 have LINKTYPE: '0', and everything present in SupernoteX.links is already a resolved, genuine 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 (verified against the same real notes above; the remaining characters are the link's own LINKRECT y,x,h,w digits, zero-padded and concatenated, just to keep same-page keys unique). This wasn't documented anywhere, so _parseLinks() in src/parsing.ts now documents it, and both ILink doc 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 different OBJPAGE values) — 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 OBJPAGE in the issue is external/personal and not available here; fabricating an equivalent .note binary 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) succeeds
  • npm run lint passes
  • npm test — full suite passes (36/36), including the new regression test

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
philips marked this pull request as ready for review July 28, 2026 20:54
@philips
philips merged commit 78c2d0f into main Jul 28, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ILink.OBJPAGE and LINKTYPE doc comments don't match observed data

2 participants