fix: commit a projected escape as the text it spells - #268
Merged
Conversation
An edit that stopped being valid committed the raw source, so a backslash typed to escape a run landed in the document as an ordinary character and saved as an escaped backslash beside the escape the text still needed. The literal commit now decodes escapes the way a file holding those same characters would. An escaped backslash spells one backslash and leaves the run literal rather than reviving the link such a file would carry, since committing an object out of the invalid path is what the rule forbids.
Azganoth
force-pushed
the
bug/projected-escape-literal
branch
from
August 18, 2026 03:15
93359fb to
5513894
Compare
Azganoth
enabled auto-merge (squash)
August 18, 2026 03:15
Azganoth
added a commit
that referenced
this pull request
Aug 18, 2026
## Summary Typing `[a](b)`, `https://example.com`, or `<https://example.com>` left literal text while pasting the same characters created a link. A run of text that is exactly one link's source now becomes that link when the caret leaves it, for inline links, autolink literals, and URI autolinks. - The run is never projected. It is already the source, so the caret sitting in it changes nothing; the link adapter validates it through the same `parseLinkSource` that already turns edited projected source into a link, and the engine's existing `appendTransaction` trigger commits it. - The caret has left once whitespace, a line break, or another block separates it from the run. Until then the next character can still move where the source ends, which is what keeps a bare URL whole while it is typed: the parser reads `https://example.com/path.` as a link stopping before the dot the author is still typing. - Only source the session wrote commits, and never a run the file escaped. A file can hold escaped source because its author wanted the characters, and the escape does not survive parsing, so the document alone cannot tell the two apart. The engine records the ranges the session writes, and the source run a write lands in while the document there still reads as the file wrote it; a commit needs the first and must avoid the second. - A run an escape spent in projection also stays literal. #265 makes a backslash typed into projected source commit the run as the text it spells, and that text is exactly the source this rule commits, written by the session and named by nothing else. The commit that spends an escape records the range it wrote, which puts the run where a file-escaped one already sits. - History clears that record, so an undone commit stays undone rather than returning on the next caret move. - A committed link projects its source again whenever the caret returns, so the visible text never changes. ## Related Issue Closes #239 Refs #238, #265 ## Verification Focused tests in `sourceProjectionTypedLink.test.tsx` cover each form committing when the caret leaves it and when the sentence continues past it; a typed URL committing once at its full length; `Enter` and `Shift+Enter`; backslash-escaped, incomplete, and code-block source staying literal; typing and plain-text paste of the same characters reaching the same document; a committed link projecting its source again, and the link the caret lands in projecting while the run it left commits. Nine tests pin the escape hatch. Source the file escaped stays literal through a caret visit, through an edit elsewhere in its paragraph, through an edit inside it, through one change that writes into it twice, and through a word dropped into it by either a move or a copy, while replacing it outright commits it. Source an escape spent in projection stays literal through repeated caret moves and through an edit inside it, matching what the file-escaped run does. One guards the gesture that the strict alternative would have broken: source written by hand around words the file already held still commits. One pins reversal: `Undo` returns a committed link to the source it was written as, and a caret move afterwards leaves it reverted. `markdownCompatibility.test.tsx` carries #234's typed-source fixtures forward. With the caret still on the source, all three forms still serialize escaped; once a space follows, the same fixtures assert the live form, which is the behavior this change accepts. Nine assertions in `sourceProjectionTypedLink.test.tsx` moved to the single escape #263 now writes, from `\[test link]\(./test.html)` to `\[test link](./test.html)`. Each still asserts what it always did, that the run stays literal, since the subject is literalness rather than which character carries the escape. The label split by a line ending keeps its pair, where the opening bracket sits in an earlier sibling than that analysis reads. Measured the added cost against `main` by driving the editor mount used by the plugin tests, medians of seven 120-operation batches per workload, each in its own mount (ms per keystroke or caret move): | Workload | `main` | This branch | | --- | --- | --- | | Typing in a 600-character prose paragraph | 0.140 | 0.150 | | Typing in a paragraph holding link syntax | 0.098 | 0.196 | | Typing in a 10k-character paragraph whose link syntax is far from the caret | 0.066 | 0.078 | | Typing in a paragraph of 200 links | 1.194 | 1.191 | | Caret moves through an edited document | 0.204 | 0.277 | | First character written into an untouched region | 0.310 | 0.694 | Not verified: those figures were taken at `f0d1da57`, before the rebase onto #263, #267, and #268, and they were not taken again after it. What those releases change is what the serializer writes and what reaches projected source, while the scan these numbers describe parses and is untouched. Also not verified: the desktop E2E suite and manual verification in the Tauri application. The rest of the change is document text and serialization, both observable in the automated DOM tests. ## Notes Caret-leave is the only trigger, including when the caret leaves by writing. Typing a space after `[a](b)` commits it, because that space is what puts the caret off the run; without that, source typed mid-sentence would never commit, since the caret leaves such a run by writing rather than by moving. #239 rules out an eager commit on a boundary character, and no boundary character is a trigger here: the same separation rule decides every case. `Enter` and `Shift+Enter` commit through that rule rather than through `finalizeSourceProjection`, which serves an active session and there is none. The line break separates the caret from the run, so the behavior #239 asks for holds without a second path. The escape-hatch tests exist because the first implementation broke #238's shared decision that `\[a](b)` round-trips as literal text: a caret passing through `corpus/commonmark/links-and-images.md`'s `\[intentionally literal](garden.md)` converted it and the save rewrote the file. Requiring the whole run to be written would close that hole too, but it refuses source wrapped by hand around words the file already held, so the run a write lands in is recorded instead. Recognizing it costs the extra time in the last row of the table, once per region rather than once per keystroke. It locates the change by its two ends, which name the same place in the document before and after it however many steps ran, and stands down under an active projection, where the source belongs to the engine rather than to the file. Standing down there is also why an escape spent in projection needs the commit to report itself. The engine writes that run while its own session is still open, so nothing classifies it as source a file holds, and the record the commit leaves is what a later caret move reads. The condition is that the commit consumed an escape rather than that it committed literal text at all: an author who edits projected source into `[a](b) x` typed those characters, and committing that run is this rule working rather than failing. An edit inside a protected run leaves it protected here, as it already did for source the file escaped, and only replacing the run outright commits it. If writing into a run was meant to spend its escape instead, the assertion that pins it is the one to change. Before parsing a text block, the adapter looks for link markers within 1000 characters of the caret. That radius is a ceiling rather than a guarantee: source whose markers all sit further away, or a form the marker pattern does not describe, stays the literal text it already was. Without it, a URL anywhere in a 10k-character paragraph cost 1.2 ms of parsing per keystroke; the table above is measured with it. The written-range record grows with the number of distinct places a session edits, not with the number of edits — continuous typing merges into one range. Two thousand scattered single-character edits leave 1911 ranges and add about 0.1 ms per keystroke. It is uncapped: every safe drop policy loses coverage, and the cost of growth is gradual rather than a cliff, while dropping the wrong range would withhold a commit the author expects. What the engine now knows, the author cannot see. A run the file escaped and a run typed a moment ago read identically, yet only one of them commits, and the escape has no character to remove: converting a protected run means deleting it and retyping it. The consequence reaches the clipboard too. An in-app copy carries characters rather than literalness, so pasting a copy of literal link source now commits it to a link where it stayed literal before, and the Markdown flavor of such a copy is written unescaped whatever this branch does. #255 supplies the gesture that answers the first half, and #244 covers the clipboard writing live source. Neither is a precondition for this change: the protections here hold without them, and both were reachable before it. The changelog's #234 entry claimed typed source stays literal when a space follows it. It now describes the escaping fix that entry was really about, since the space case is what this change alters.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A backslash typed into projected link source turned the link literal, which the specification asks for, but the backslash itself landed in the document as an ordinary character. The run then saved with three backslashes where one was enough, and the document differed from the same file authored by hand.
The literal commit now reads the source as the text it spells rather than as the characters it is written with, which is what a file holding those same characters would hold.
decodeSourceProjectionEscapesconsumes a backslash before CommonMark's escapable punctuation and keeps every other backslash, soa \ bandC:\Users\mestill reach the document intact.[a]\(b)and\[a](b)produce the same document, exactly as the two files do.An escaped backslash is where this stops short of what the file means.
\\[a](b)in a file is a literal backslash followed by a live link; committed out of projection it spells one backslash and leaves the run literal, because committing an object out of the invalid path is the one thing the projection rule forbids.Related Issue
Closes #265
Refs #238, #255
Verification
src/features/editor/plugins/sourceProjection.test.tsxgains five cases insource editing. A backslash typed at a link's source start and one typed before its destination each produce a document equal to mounting\[a](b) tail, compared as ProseMirror documents rather than as strings, and each saves as\[a](b) tail. The same holds for a footnote reference againsttext\[^a] tail. A backslash the author means as text survives, and an escaped backslash spells one character. Four of the five fail with the adapters stashed and the tests otherwise untouched; the fifth is the guard against consuming too much, and passes either way.src/features/editor/tests/sourceProjectionClipboard.test.tsxpins the consequence for an in-app copy: the editor flavor of escaped invalid source carries the text it spells, while the plain-text flavor keeps the exact projected characters the event writes from the selection.The corpus round trip and the rest of the editor suites are unchanged.
Not verified: no manual pass in the Tauri application. The gesture is text input and serialization, both driven directly by the editor mount.
Notes
docs/specification.mdsaid invalid edits become exact literal text anddocs/decisions.mdsaid no projected character is lost. Both now carry the escape rule, since this drops the backslash deliberately.Files already saved with the extra backslashes are not repaired.
\\\[a](b)reopens as a document holding the backslash and saves back unchanged, so an author who hit this deletes the stray character by hand.This does not touch what #246 does with the run afterwards. The literal commit now lands text that is exactly valid link source inside a range that branch records as written and does not protect, so the escape is spent on the next caret move; measured there and recorded in that pull request. The protection belongs with whichever of the two lands second, conditional on the fallback having consumed an escape rather than blanket over every literal commit.