Skip to content

Render content images at their original position in the prose flow - #22

Merged
yrstm merged 2 commits into
mainfrom
inline-image-positions
Jul 28, 2026
Merged

Render content images at their original position in the prose flow#22
yrstm merged 2 commits into
mainfrom
inline-image-positions

Conversation

@yrstm

@yrstm yrstm commented Jul 23, 2026

Copy link
Copy Markdown
Owner

Why

Mantis previously appended all images as a batch at the end of Markdown while data tables were already rendered inline. Content images should stay near the prose and tables they accompanied on the page.

What

  • Live-DOM content images now carry a position anchor: the index of the captured block they follow, or -1 when they lead the document.
  • Images and data tables are positioned together and receive a shared flowOrder, preserving their actual DOM order when they share an anchor.
  • toMarkdown() validates anchors before splicing. Missing, fractional, non-finite, negative out-of-range, and past-the-end positions use the trailing fallback instead of being dropped.
  • Positioned images retain render priority 4, so the outline budget still sheds images first and images do not consume a section's lead priority.
  • unpositionedImages, MantisImage.position, and the shared flowOrder fields are documented in the type declarations.
  • README and public-page changelog copy describe the behavior.

Compatibility

  • Stored and vision-pipeline articles without positions keep the previous trailing-list behavior.
  • No image downloading is introduced; Markdown continues to reference remote URLs.
  • Table rendering and the clipboard-first flow are unchanged.

Testing

  • 7 focused tests cover inline image placement, leading/title-adjacent images, mixed image/table DOM order in both directions, invalid-anchor fallback, stored-article fallback, and transient DOM-reference cleanup.
  • npm test: 70 passing.
  • npm run types:check: passing.
  • npm run benchmark: 129/129.
  • npm run perf: fidelity checks passing.
  • npm pack --dry-run: passing.
  • GitHub Actions test and demo-browser: passing.

yrstm and others added 2 commits July 23, 2026 04:10
Images captured from a live DOM now carry a `position` anchor (the index
of the block they follow, or -1 to lead the document), mirroring how data
tables are anchored. toMarkdown splices positioned images into the flow,
interleaved with prose and tables, instead of listing every image at the
document tail. Images without a position (vision pipeline, stored
articles, out-of-range anchors) keep the trailing-list fallback, and a
new `unpositionedImages` diagnostic mirrors `unpositionedTables`.

Spliced images keep the lowest render priority, so the "outline" budget
still sheds images first and never spends heading/lead budget on them.

Co-Authored-By: Claude Fable 5 <[email protected]>
@yrstm
yrstm marked this pull request as ready for review July 28, 2026 14:45
@yrstm
yrstm merged commit 9e46269 into main Jul 28, 2026
4 checks 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.

1 participant