Summary
While building a clickable-link overlay in the Obsidian plugin (philips/supernote-obsidian-plugin#128), two ILink field doc comments turned out not to match real device-created notes.
LINKTYPE ("1 = internal note link")
Filtering to LINKTYPE === '1' drops real, genuine internal links. In this repo's own tests/input/nomad-3.26.40-link-tag-3p.note fixture, 2 of its 3 links have LINKTYPE: '0'. A second, independently-created real note (two links, on different pages) also had LINKTYPE: '0' on both of its links. Not sure what LINKTYPE actually distinguishes, but it isn't "is this a real internal link" — everything present in sn.links already appears to be a resolved, genuine link.
OBJPAGE ("0-indexed page number this link appears on")
This doesn't match the link's actual source page. Verified directly: rendered a real 4-page note to images via toImage(), drew each link's LINKRECT box onto every rendered page, and measured ink coverage under each box to find which page each link is actually drawn on.
| link |
OBJPAGE |
LINKRECT |
actual source page (0-indexed array position, pixel-verified) |
sn.links key prefix (first 4 chars) |
| A |
4 |
672,220,800,87 |
0 |
0001 |
| B |
1 |
564,500,791,87 |
3 |
0004 |
OBJPAGE doesn't match the verified page under any indexing convention (0- or 1-indexed). The sn.links Record key's first 4 characters, read as a 1-indexed page number, matched perfectly for both links (1 → index 0, 4 → index 3) — that convention isn't documented anywhere I could find, but it's what's actually reliable. Best guess for what OBJPAGE is really tracking: something like the page's own template/display label, which can drift from its current position in the pages array (e.g. after page reordering) — that's speculation though, not verified.
Repro
Using this repo's own tests/input/nomad-3.26.40-link-tag-3p.note fixture: all 3 of its links share sn.links key prefix 0002, i.e. it happens to place every link on the same page — which is exactly what led us to initially (and wrongly) conclude the key prefix wasn't meaningful, before checking a second note with links on different pages. Might be worth adding a fixture (or a second page to this one) with links on more than one page, so this is exercisable from this repo's own test suite rather than needing an external note.
Suggested fix
- Correct/soften
ILink.OBJPAGE's doc comment — at minimum, stop claiming it's "the page this link appears on" until its actual semantics are confirmed.
- Document the
sn.links Record key's actual format (page prefix + rect digits) since it's currently load-bearing for anyone trying to place links on the correct page — e.g. in _parseLinks()'s comments (src/parsing.ts).
Happy to send a PR for the doc-comment fix if useful — filing this first in case there's already a known explanation for OBJPAGE that we're missing. Full writeup of the investigation (and how the plugin resolves links in practice) is at philips/supernote-obsidian-plugin's docs/supernote-links.md.
Summary
While building a clickable-link overlay in the Obsidian plugin (philips/supernote-obsidian-plugin#128), two
ILinkfield doc comments turned out not to match real device-created notes.LINKTYPE("1 = internal note link")Filtering to
LINKTYPE === '1'drops real, genuine internal links. In this repo's owntests/input/nomad-3.26.40-link-tag-3p.notefixture, 2 of its 3 links haveLINKTYPE: '0'. A second, independently-created real note (two links, on different pages) also hadLINKTYPE: '0'on both of its links. Not sure whatLINKTYPEactually distinguishes, but it isn't "is this a real internal link" — everything present insn.linksalready appears to be a resolved, genuine link.OBJPAGE("0-indexed page number this link appears on")This doesn't match the link's actual source page. Verified directly: rendered a real 4-page note to images via
toImage(), drew each link'sLINKRECTbox onto every rendered page, and measured ink coverage under each box to find which page each link is actually drawn on.OBJPAGELINKRECTsn.linkskey prefix (first 4 chars)4672,220,800,87000011564,500,791,8730004OBJPAGEdoesn't match the verified page under any indexing convention (0- or 1-indexed). Thesn.linksRecord key's first 4 characters, read as a 1-indexed page number, matched perfectly for both links (1→ index0,4→ index3) — that convention isn't documented anywhere I could find, but it's what's actually reliable. Best guess for whatOBJPAGEis really tracking: something like the page's own template/display label, which can drift from its current position in thepagesarray (e.g. after page reordering) — that's speculation though, not verified.Repro
Using this repo's own
tests/input/nomad-3.26.40-link-tag-3p.notefixture: all 3 of its links sharesn.linkskey prefix0002, i.e. it happens to place every link on the same page — which is exactly what led us to initially (and wrongly) conclude the key prefix wasn't meaningful, before checking a second note with links on different pages. Might be worth adding a fixture (or a second page to this one) with links on more than one page, so this is exercisable from this repo's own test suite rather than needing an external note.Suggested fix
ILink.OBJPAGE's doc comment — at minimum, stop claiming it's "the page this link appears on" until its actual semantics are confirmed.sn.linksRecord key's actual format (page prefix + rect digits) since it's currently load-bearing for anyone trying to place links on the correct page — e.g. in_parseLinks()'s comments (src/parsing.ts).Happy to send a PR for the doc-comment fix if useful — filing this first in case there's already a known explanation for
OBJPAGEthat we're missing. Full writeup of the investigation (and how the plugin resolves links in practice) is at philips/supernote-obsidian-plugin's docs/supernote-links.md.