Problem
When a review marker is serialized into the document as an inline HTML comment (the format the spec itself uses, <!-- REVIEW(@author): text -->), the renderer prints it as literal body text instead of hiding it. Surfaced in the spec-945 smoke host: the seeded marker on the "## Summary" block renders as <!-- REVIEW(@reviewer): is this scoped to v1 only? --> This document describes... inside the paragraph.
Root cause: per spec D7 the renderer uses markdown-it with html: false, so an HTML comment is escaped and shown as text rather than dropped.
Why it is not a trivial fix
The marker occupies its own source line, and the data-line source-mapping (spec D5) depends on line positions staying stable. Simply stripping the comment line would shift every line number below it and break marker anchoring. So the fix is not "remove the comment"; it is "render the document so marker lines do not appear as content without disturbing the line accounting the overlay relies on."
This is really a host-serialization / source-mapping decision (relates to #859)
How markers reach the canvas is the host's concern (spec D3):
- A host using sidecar markers (markers stored outside the body) never puts comments in the rendered text, so this issue does not arise for it.
- A host using inline
<!-- REVIEW --> comments needs a strategy: e.g. the renderer recognizes and suppresses REVIEW-marker comment lines while keeping their line slots in the mapping, or the host strips markers before render and supplies a line-offset map alongside the parsed markers.
Picking between these is part of host integration (#859), which is out of scope for the foundational package (spec 945).
Suggested approach
Decide the contract during #859: either (a) hosts pre-strip markers and pass a stable line map, or (b) the renderer gains an opt-in "suppress marker-comment lines" mode that preserves data-line slots. Then implement + test (the smoke-host fixture is a ready reproduction).
Out of scope
Changing spec 945's v1 renderer behavior. The current behavior is correct for sidecar-marker hosts and is only cosmetic for the inline-comment demo fixture.
Origin
Surfaced during visual review of PR #1027 (spec 945) via the examples/ smoke host. Sibling to #1029 (package layering) and #863 (polished marker UI). The overlay-anchoring half of the smoke-host feedback was fixed directly in PR #1027; this half is deferred here because it is entangled with host serialization.
Problem
When a review marker is serialized into the document as an inline HTML comment (the format the spec itself uses,
<!-- REVIEW(@author): text -->), the renderer prints it as literal body text instead of hiding it. Surfaced in the spec-945 smoke host: the seeded marker on the "## Summary" block renders as<!-- REVIEW(@reviewer): is this scoped to v1 only? --> This document describes...inside the paragraph.Root cause: per spec D7 the renderer uses
markdown-itwithhtml: false, so an HTML comment is escaped and shown as text rather than dropped.Why it is not a trivial fix
The marker occupies its own source line, and the
data-linesource-mapping (spec D5) depends on line positions staying stable. Simply stripping the comment line would shift every line number below it and break marker anchoring. So the fix is not "remove the comment"; it is "render the document so marker lines do not appear as content without disturbing the line accounting the overlay relies on."This is really a host-serialization / source-mapping decision (relates to #859)
How markers reach the canvas is the host's concern (spec D3):
<!-- REVIEW -->comments needs a strategy: e.g. the renderer recognizes and suppresses REVIEW-marker comment lines while keeping their line slots in the mapping, or the host strips markers before render and supplies a line-offset map alongside the parsed markers.Picking between these is part of host integration (#859), which is out of scope for the foundational package (spec 945).
Suggested approach
Decide the contract during #859: either (a) hosts pre-strip markers and pass a stable line map, or (b) the renderer gains an opt-in "suppress marker-comment lines" mode that preserves
data-lineslots. Then implement + test (the smoke-host fixture is a ready reproduction).Out of scope
Changing spec 945's v1 renderer behavior. The current behavior is correct for sidecar-marker hosts and is only cosmetic for the inline-comment demo fixture.
Origin
Surfaced during visual review of PR #1027 (spec 945) via the
examples/smoke host. Sibling to #1029 (package layering) and #863 (polished marker UI). The overlay-anchoring half of the smoke-host feedback was fixed directly in PR #1027; this half is deferred here because it is entangled with host serialization.