Skip to content

Add portable page citation maps - #483

Draft
JSv4 wants to merge 3 commits into
agent/issue-447-preconditionsfrom
agent/issue-454-page-citations
Draft

Add portable page citation maps#483
JSv4 wants to merge 3 commits into
agent/issue-447-preconditionsfrom
agent/issue-454-page-citations

Conversation

@JSv4

@JSv4 JSv4 commented Aug 14, 2026

Copy link
Copy Markdown
Owner

Closes #454.

Summary

  • expose a strict, portable page-map contract through .NET, WASM, npm, Python, and MCP
  • stamp canonical source identities through real conversion and materialize page/column fragments after pagination
  • support main-story content, tables, repeated stories, continued footnotes, endnotes, and all comment render modes
  • add citation lookup/navigation with exact highlight restoration and explicit unavailable/diagnostic states
  • keep page estimates clearly heuristic and reject incomplete available maps

Architecture

The converter owns stable canonical source identity; the browser pagination layer owns physical page geometry. Page maps remain detached DTOs, never serialized DOM snapshots. Paginated conversion always carries the private canonical identity needed for measurement, while public editor anchors remain opt-in.

The citation response includes the exact registered physical page descriptors used by MCP preview. The preview projects the cited source into that page geometry without inventing a second layout algorithm. Critical PageMap/citation schemas are strict and action-specific, and the shared runtime parser rejects unknown fields as well as missing or mistyped required fields.

Adversarial hardening

  • preserve visible endnote targets, backlinks, and Roman/letter markers while retaining conservative fallback for unsafe custom layout
  • partition final deferred notes across visible note-only pages and retain every continuation identity
  • map collapsed inline and margin comments through their visible reference point
  • clip fragment geometry through every overflow ancestor
  • transfer fragment-target ownership from hidden staging to visible pages
  • materialize cited physical pages in MCP preview
  • expose citation pages consistently through .NET, JSON, npm, and Python

Verification

  • focused .NET PageMap/MCP gate: 74 passed
  • focused Chromium real-WASM/page-map/footnote suites: 23 passed
  • npm typecheck
  • pagination/session/editor bundles
  • WASM publish: 3325 KB wire size of 4096 KB budget
  • Python page-map test: 1 passed
  • Python host and MCP server builds
  • independent adversarial re-audit: SHIP; all reported findings closed
  • git diff --check

@JSv4
JSv4 force-pushed the agent/issue-454-page-citations branch from 0a0bb29 to 2a6ae05 Compare August 14, 2026 09:49
@JSv4
JSv4 force-pushed the agent/issue-447-preconditions branch 2 times, most recently from e467c0d to 9222540 Compare August 14, 2026 10:03
@JSv4
JSv4 force-pushed the agent/issue-454-page-citations branch from 2a6ae05 to 308f1df Compare August 14, 2026 10:04
@JSv4
JSv4 force-pushed the agent/issue-447-preconditions branch from 9222540 to a666aa3 Compare August 14, 2026 11:11
@JSv4
JSv4 force-pushed the agent/issue-454-page-citations branch from 308f1df to dc888c7 Compare August 14, 2026 11:11
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.

1 participant