bib: context-aware jump-link resolver — page/¶-ordinal/raw-anchor/quote refs + page↔paragraph transmutation #635

New Issue

kert · 2026-08-17T18:18:07Z

kert commented

2026-08-17 18:18:07 +00:00

bib.frlink.resolve(ref, *, store, item_key=None) -> JumpLink(url, item_key, page, p_id, ordinal, snippet) accepting:

"91 FR 44218" → {html_url}#page-44218 — rule found by volume + page-range containment over fr_anchor_docs; ambiguity raises with candidates.
"91 FR 44218 ¶3" (also para 3/p.3) → 3rd paragraph on that page → #p-N.
"p-3600" (needs item_key or unambiguous context) → validated #p-3600.
Quoted passage ≥15 chars → normalized substring search over fr_anchors.text; exactly-one match required, zero/many raise with diagnostics.

Transmutations both directions: page_of(item_key, p_id), paragraphs_of("91 FR 44218") (anchors + ordinals + snippets). md_link(ref, text=None) renders [91 FR 44218 ¶3](url) for notebooks.

Tests: every ref form, ambiguity errors, both transmutations, md output; live check that resolve('91 FR 44218 ¶2') lands in the §414.1425 QP passage.

Depends on #634. Spec: docs/superpowers/specs/2026-08-17-fr-jump-links-design.md.

`bib.frlink.resolve(ref, *, store, item_key=None) -> JumpLink(url, item_key, page, p_id, ordinal, snippet)` accepting: 1. `"91 FR 44218"` → `{html_url}#page-44218` — rule found by volume + page-range containment over `fr_anchor_docs`; ambiguity raises with candidates. 2. `"91 FR 44218 ¶3"` (also `para 3`/`p.3`) → 3rd paragraph on that page → `#p-N`. 3. `"p-3600"` (needs item_key or unambiguous context) → validated `#p-3600`. 4. Quoted passage ≥15 chars → normalized substring search over `fr_anchors.text`; exactly-one match required, zero/many raise with diagnostics. Transmutations both directions: `page_of(item_key, p_id)`, `paragraphs_of("91 FR 44218")` (anchors + ordinals + snippets). `md_link(ref, text=None)` renders `[91 FR 44218 ¶3](url)` for notebooks. Tests: every ref form, ambiguity errors, both transmutations, md output; live check that `resolve('91 FR 44218 ¶2')` lands in the §414.1425 QP passage. Depends on #634. Spec: docs/superpowers/specs/2026-08-17-fr-jump-links-design.md.

kert added this to the P40: FR Jump Links — page/paragraph deep links for every FR citation milestone 2026-08-17 18:18:07 +00:00

kert added the bib cli labels 2026-08-17 18:18:07 +00:00

kert referenced this issue

2026-08-17 18:18:19 +00:00

bib: :pincite: FR locator grammar + jump_url on the citation graph #636

kert referenced this issue

2026-08-17 18:18:19 +00:00

bib: place() + Zotero child link attachments (linkMode=3) for cited FR paragraphs #637

kert referenced this issue from a commit

2026-08-17 18:44:53 +00:00

feat(bib): context-aware FR jump resolver — page/ordinal/anchor/quote + transmutations (closes #635)

kert closed this issue