Keeping the map in an example preserves the stable segmentation API while making its coordinate contract inspectable. The explicit unlocatable sentinel is useful, provided consumers never pass negative offsets straight into slicing or annotation code.

I would give that example a small test with repeated sentence text and cleaning that removes characters, so mapping cannot silently choose the first matching occurrence. Comparing different stream chunk boundaries against whole-input processing would also catch local-to-absolute offset mistakes without committing the core API to maintaining those maps.

I haven't stress test the example yet. If you get some free time, you may test it and raise issue or Pr directly to the repo.

I am not able to take on individual reviews, but a focused regression can make the example easier to assess without a broad stress test. Use two identical sentences with different source offsets, remove a hyphenated line break before the second, and verify both map to the intended occurrences.

Repeat that input with several stream chunk boundaries and compare the spans with whole-input processing. Explicitly assert that an unlocatable result remains the sentinel and never becomes a negative-index slice into the source.