A backslash typed into projected link source becomes literal text instead of an escape

[Azganoth]

Summary

Typing a backslash into projected link source turns the link literal, which is what the specification describes, but the backslash lands in the document as an ordinary character rather than as the escape it spells. The run then saves with three backslashes where one is enough, and the resulting document differs from the same file authored by hand.

This is the gesture #245 read from the specification as the inverse of #255's, and recorded as inferred rather than observed. It is reachable today with no other change in place.

Steps to reproduce

1. Open a document containing [a](b) tail.
2. Place the caret in the link so its source projects, and type \ at the start of [a](b).
3. Move the caret out of the run and save.

Expected behavior

The same state a file holding \[a](b) tail produces: the document holds [a](b) tail as literal text with no backslash character in it, and the file saves as \[a](b) tail.

The link must still become literal, which it already does. A backslash the author means as ordinary text must still survive as one.

Actual behavior

Measured against f409cdbf by driving the editor mount used by the plugin tests, comparing the gesture against the same run authored with the escape. The documents are compared as ProseMirror documents rather than as strings, so the comparison sees literalness rather than form.

	Typing \ into projected source	Authored \[a](b) tail
Links after the caret leaves	0	0
Document text	\[a](b) tail	[a](b) tail
Saved	\\\[a](b) tail	\[a](b) tail

The same holds on a realistic link. see [test link](./test.html) tail gives document text see \[test link](./test.html) tail and saves as see \\\[test link](./test.html) tail, against see [test link](./test.html) tail and see \[test link](./test.html) tail for the authored form.

The wrong state is stable rather than self-correcting: reopening \\\[a](b) tail returns the document holding the backslash and saves it back unchanged, so nothing later recovers the escape the author meant.

Related context

• Related issues or pull requests: Project an escape as its two characters so deleting the backslash converts the run #255 rests on this gesture as the inverse of its own and records it as read from the specification rather than observed; How a Markdown escape should be represented in the editor #245 selected Project an escape as its two characters so deleting the backslash converts the run #255's shape on the same reading and flagged it under Residual uncertainty; Typed link source becomes a link #238 is the parent that scopes reverting an unwanted conversion; Commit typed link source to a link when the caret leaves it #239 and its pull request treat it as the reversal path available after a save
• Documentation, decisions, or prior investigation: docs/specification.md Inline Content, which states that invalid or incomplete edits to projected source become exact literal text, and docs/architecture.md Source Projection

Done when

• Typing a backslash before projected link source produces the same document as opening a file that already holds the escaped run.
• The run saves with the escape its text needs rather than with an escaped backslash.
• The link still becomes literal, and a backslash the author intends as ordinary text is still preserved.
• Regression coverage asserts the resulting document, not only its serialization, so a fix cannot pass by writing the right bytes from the wrong state.

Notes, logs, screenshots

Diagnosis

sourceProjectionLinkAdapter.ts falls back to createLiteralSourceProjectionSlice(state, source) when parseLinkSource rejects the edited source, and that slice is built from the raw source string. The backslash the author typed is part of that string, so it enters the document as text like any other character.

The serializer is then correct: a document holding a literal backslash followed by a bracket needs \\ for the backslash and \[ for the bracket, which is where the third one comes from. The defect is in the commit, not in escaping, so it is not one of the classes under #251.

Verified with a throwaway probe under src/features/editor/tests/, run with vitest and deleted. To reproduce: mount the source, enter projection through the rendered a element, place the selection at the start of the source run, type \, move the selection to the document end, then read doc.textContent and getMarkdown() and compare view.state.doc against a mount of the hand-authored escape.

Implementation direction

One constraint and one open decision.

The constraint is that both directions have to keep working. A backslash typed into projected link source has to mean "escape this run", while a backslash the author wants as text still has to reach the document as one, and only the projection context separates them.

The open decision is where the exception lives. docs/specification.md says an invalid edit to projected source becomes exact literal text, and consuming a leading backslash is an exception to that rule rather than an application of it. Whether it belongs in the adapter's parseSource, in the projection commit ahead of the adapter, or in the specification's wording is not settled here.

Out of scope

• Projecting an escape as its two characters, which is Project an escape as its two characters so deleting the backslash converts the run #255. This issue is the gesture that already exists, not the one that has to be built.
• Escape characters other than a backslash before link source. The same commit path serves the other adapters and was not probed.
• The over-escaping classes under Preserve the authored form of a Markdown file on save #251, which concern escapes the serializer emits from a correct document.

[Azganoth]

Probed the two questions this issue left open — whether the defect is confined to a leading backslash, and whether the same commit path breaks the other adapters — along with the interaction with #239.

Measured against f409cdbf by driving the editor mount used by the plugin tests, comparing ProseMirror documents rather than strings, with session ranges read from the projection plugin state. The probes were throwaway files under src/features/editor/tests/, run with vitest and deleted.

The defect is not confined to the leading position

Gesture on [a](b) tail	Document text	Saved
Type \ at the source start	\[a](b) tail	\\\[a](b) tail
Type \ before the (	[a]\(b) tail	\[a]\\(b) tail
A file holding either escape	[a](b) tail	\[a](b) tail

Both positions break the syntax, both commit through the same fallback, and a file holding either one produces the same literal document. The second row saves worse than the first, carrying a spurious \\ alongside the \[ the run genuinely needs. A fix defined by the leading position leaves it standing.

Typing two backslashes is where file parity stops being the rule

Typing \\ into projected source gives document text \\[a](b) tail, saved as \\\\\[a](b) tail. A file holding \\[a](b) tail holds a literal backslash followed by a live link, and round-trips byte-identically.

So "commit what the same characters would mean in a file" cannot be the whole rule: for this input it commits a link, against this issue's requirement that the link becomes literal. A rule that consumes escapes only where the source parses to a single plain text run covers both rows of the table above and leaves this input where it is today.

The footnote adapter shares the defect; the mark adapters do not

Session source read before and after the keystroke:

Adapter	Before	After	Committed
link	[a](b) at [1,7]	\[a](b) at [1,8]	literal \[a](b) tail, saves \\\[a](b) tail
footnote-reference	[^a] at [5,9]	\[^a] at [5,10]	literal text\[^a] tail, saves text\\\[^a] tail
mark	**bold** at [1,9]	**bold** at [2,10]	\ beside strong bold, saves \\**bold** tail

The link and footnote adapters take the character into their source, invalidate, and commit the raw string. One defect, one fix, and the footnote row against the authored text\[^a] tail shows the same triple backslash.

A mark's left boundary pushes the character outside the session instead. The source is never edited, the mark restores clean, and the document holds a literal backslash before live emphasis — which serializes correctly and reopens unchanged. The same holds for *em*, ~~struck~~, and `code`. Typed one character further in, **\bold** is valid mark source and commits strong \bold, saving **\bold** tail, also correct. Marks have no defect here; they have no gesture.

Worth carrying to #255: the symmetry it reads from the specification holds for links and footnote references, not for marks.

The fixed state does not survive #239

The state this fix produces — exactly valid link source, literal, written by the engine's own commit — is reachable today without the fix, by editing projected source to [a](b) x, which is invalid and commits literally. Measured on #246's branch, which is two commits ahead of its origin ref and does not carry #263, which is why its escaping still reads \[a]\(b):

	After the literal commit	After one further caret move
main	\[a](b) x tail, literal	\[a](b) x tail, literal
#246 branch	\[a]\(b) x tail, literal	[a](b) x tail, live link mark

Plugin state there: writtenRanges [{from:1,to:4}], protectedRanges []. The engine's own literal commit is recorded as session-written and unprotected, so the next caret move converts it back into the link the author just escaped. The control holds — source the file escaped stays literal through a caret visit.

Today's defect is what hides this: \[a](b) is not valid link source, so nothing re-commits it. Consuming the backslash removes that accident, and whichever of the two changes lands second has to carry the protection.

It cannot be a blanket rule over the engine's literal commits. The [a](b) x gesture above runs through the same path with no escape in it, and #239 converting that run follows from its own premise rather than being a defect. The condition is the fallback having consumed an escape.