blog · · engineering

Refreshing the outline is what deleted the paste

Paste a link copied out of an email into the block you are editing and nothing appeared. Leave the block and the link was gone from the .md too, with nothing on screen to say so. The paste had landed: paste_markdown_at wrote it through the op log and the reply carried the refreshed page. Both GUI clients hold the block being edited as a draft seeded once, so the outline refreshed around a textarea still holding the pre-paste string, and the next Esc committed that back over the paste. A caret paste is the one mutation whose result an editor has to be told rather than shown, so PasteOutcome now carries host_text and a codepoint host_caret: the merge can insert a separating space, and the caret is not the end of the text.

A
10 min read

Paste a link copied out of an email into the block you are editing, and nothing appears.

Leave the block and the link is gone from the .md too, with nothing on screen to say anything happened. A plain URL pasted into the same block was fine every time, which is what made this read as a rich-clipboard bug.

It is not one. matthieu403 reported it with the detail that made it findable: the link was in the .md for a moment, and leaving the block took it out again.

the paste landed, and leaving the block took it back out

A paste with the caret inside a block is the one anchor that rewrites a block that already exists and is already on screen. It is spelled out in crates/outl-actions/src/paste/mod.rs:

AtCaret {
    /// Block currently being edited.
    block: NodeId,
    /// Caret position, measured in `char` offsets into the block's
    /// text (not byte offsets).
    caret: usize,
},

paste_at_caret merges the first pasted bullet into the host block’s text through edit_text, which is an ordinary Op::Edit in the log, then creates the remaining bullets as siblings. The Tauri command returns the refreshed page, the client folds it in with applyView, and the outline redraws.

The editor does not read the outline. In the desktop client the block being edited is a Solid signal on the row, crates/outl-desktop/src/components/BlockRow.tsx:

const [draft, setDraft] = createSignal<string>(rawTextWithTodo(props.block));

Its comment says why it lives there: the lifetime of a draft is the row, not the edit session, because <BlockEditor /> is mounted and disposed every time the user enters and leaves Insert. Seeding it inside the editor would re-seed it on every entry. So the draft is seeded once per row instance, and startEdit is the one place that re-seeds it.

Which means that after a paste, the workspace holds the pasted text, the refreshed outline holds the pasted text, and the textarea the user is looking at holds the string from before. Then they press Esc:

const raw = props.text();
const wire = props.wireText();
if (raw !== wire) {
  await props.cb.onCommit(props.blockId, raw);
  return;
}

wireText reads the block out of the refreshed view. raw is the draft. The comparison exists so that leaving a block you did not touch writes nothing, and after a paste the two differ by exactly the paste, so the guard fires and onCommit writes the draft back. The check that exists to prevent a pointless write is what guaranteed this one happened, and the more faithfully applyView refreshed the outline, the more certain the overwrite became.

Mobile has the same shape with different spelling. commitEdit in Journal.tsx skips the write only when text === rawTextWithTodo(current), and after a paste it never is.

Both writes are real Op::Edits. Nothing failed, nothing was swallowed, and there was no error to surface: one mutation added the link and a second one, half a second later, removed it. The op log has both.

a trivial paste never leaves the browser, which is why a plain URL was fine

choosePasteRoute in crates/outl-frontend-shared/src/paste/index.ts is the one owner of whether a paste goes to the backend at all:

const md = html ? htmlToOutlMarkdown(html) : "";
if (md !== "" && md !== plain.trim()) {
  return { route: "rich", text: md };
}

A link copied out of an email carries a text/html flavour: the label, with the address behind it. Turndown turns that into [See the invoice](https://example.test/i), which differs from the text/plain flavour (See the invoice), so the route is rich, the clipboard goes through paste_markdown_at, and the block is rewritten under the editor.

A plain URL has no HTML flavour and is one line, so it falls to native: the browser splices it into the textarea itself, no command runs, the draft and the block never disagree. The clipboard’s richness decided nothing about the defect. It decided whether the defect was reachable.

the first line of a pasted outline went the same way, and the rest did not

Paste four bullets at the caret and three of them show up. That symptom is a map of which parts of the page the editor holds a copy of.

paste_at_caret puts the first bullet into the host block, makes the remaining root bullets siblings after it, and adds whatever was right of the caret as one more sibling so nothing typed is lost. The siblings are new blocks that exist only in the refreshed view, and no draft is holding those. The first bullet is the host block, and the host block is the one thing the editor owns a copy of.

So the lines below appeared, the first line did not, and the user is left with a report that sounds like a parser bug.

the backend owns the merged text, because the merge can insert a space

The obvious fix is to have the client re-seed its draft with “the text I had, spliced at the offset I sent”. That is wrong, and here is the whole reason, from crates/outl-actions/src/paste/anchors.rs:

fn join_caret_left_with(left: &str, addition: &str) -> String {
    if left.is_empty() {
        return addition.to_string();
    }
    let ends_ws = left
        .chars()
        .last()
        .map(|c| c.is_whitespace())
        .unwrap_or(true);
    let starts_ws = addition
        .chars()
        .next()
        .map(|c| c.is_whitespace())
        .unwrap_or(true);
    if ends_ws || starts_ws {
        format!("{left}{addition}")
    } else {
        format!("{left} {addition}")
    }
}

One character, inserted conditionally. A client arithmetic that ignores it is right most of the time and off by one whenever both sides of the join are word characters, and when it is off the client writes a string the op log never had on the next commit. That is the same bug one layer up.

So PasteOutcome carries the string the function built:

/// New text of the host block when `AtCaret` was used and the
/// host's text changed. `None` for the other anchors.
///
/// A client editing that block holds its text in a draft it seeded
/// once, so it has to be handed the new text or it shows the
/// pre-paste string and commits it back over the paste on the way
/// out of the editor ([issue #488](https://github.com/outlmd/outl/issues/488)).
pub host_text: Option<String>,

This is the move eight copies of a sort nobody owned argued for, applied before the copies exist: the place that builds a value is the only place entitled to answer questions about it. commands::block::paste_reply in outl-tauri-shared is deliberately one function shared by both paste commands, with the comment saying that a second copy of the mapping is how one of them starts forgetting to carry the caret.

the caret is not the end of the host text

The second field is the one I would have got wrong if the two paste paths had not disagreed so loudly.

With formatting, everything merged in sits to the left and the tail became a sibling, so the end of the host text really is the end of the pasted run. Even there it is measured rather than derived:

// Measured rather than derived from `caret`:
// `join_caret_left_with` may have inserted a separating space.
let host_caret = host_text.chars().count();

Without formatting, the tail stays in the same block, and “end of the text” would be the wrong answer by the length of whatever the user had typed after the caret:

let host_caret = left.chars().count() + text.chars().count();

a_plain_caret_paste_reports_the_caret_between_the_splice_and_the_tail pins it with hello world, a caret at 6 and BRAVE pasted: the text is hello BRAVE world and the caret is 12, not 17. Collapsing those two cases into one rule would have shipped a paste that works and then drops you past the sentence you were in the middle of.

codepoints leave, UTF-16 units come back

host_caret is a codepoint offset, because str::chars is what counts it. A textarea’s selectionStart is UTF-16 code units. For anything in the Basic Multilingual Plane those are the same number, which is why this class of mistake survives every test written in ASCII.

a_caret_paste_counts_codepoints_not_utf16_units pastes ok into a block holding a single 🎉, with the caret at 1:

assert_eq!(out.host_text.as_deref(), Some("🎉ok"));
assert_eq!(out.host_caret, Some(3));

Three codepoints, four code units. charOffsetToUtf16Offset converts on the way back and clamps past the end rather than running off it, so a caret from a reply that raced an edit lands harmlessly at the end instead of producing a NaN selection. The outbound direction, utf16OffsetToCharOffset, already existed; this change only added its inverse.

It is the same problem as making the caret a property of a character rather than a glyph you insert, one layer down: a cursor position is meaningless without the unit it is counted in, and every boundary it crosses is a chance for the two sides to be counting different things.

present, not truthy

pasteEditorUpdate is the clients’ one reader, and its two lines of policy are the parts worth quoting:

if (text == null) return null;
// A reply carrying the text but not the caret: the end of the text
// beats discarding the paste.
if (reply.host_caret == null) return { text, caret: text.length };
return { text, caret: charOffsetToUtf16Offset(text, reply.host_caret) };

== null and not === undefined, because “absent” is spelled by a missing key only thanks to skip_serializing_if on a struct one crate away, and a null arriving instead must not write { text: null } into a textarea.

The check is on presence, not truth. Pasting over a whole selection with an empty clipboard legitimately empties the block, and host_text: "" is a real update: a falsy check there leaves the stale draft in place, which is the bug this function exists to close. accepts an empty host text as a real update is the test.

The DTO itself is pinned across the language boundary by paste_reply_matches_its_interface in outl-tauri-shared/tests/wire_types.rs, which builds the reply with both optionals as Some on purpose: with None the keys would not be serialised and the pin would compare an interface against a reply that never mentions the fields the clients read.

applying it stays per client, because the mechanics differ

The desktop writes the textarea directly as well as the signal:

props.setText(update.text);
if (!ta) return;
ta.value = update.text;
ta.setSelectionRange(update.caret, update.caret);

Solid’s value={props.text()} binding lands in a later effect, so setSelectionRange against the not-yet-updated value would clamp the caret to the old text’s length. Mobile cannot use a bare el.value = at all: on WKWebView that jumps the caret to the end, so Journal.block-ops.ts goes through spliceText and then parks the caret twice, once now and once after setDraft, which is the pattern crates/outl-mobile/src/lib/textarea.ts owns. It also bails if editingId() moved during the round trip, because the user can tap out of a block while a command is in flight and the draft then belongs to somebody else.

That is two implementations of the last step, and only the decision is shared. It is the honest split, and it is also the remaining place where the two clients can drift.

the TUI was never affected, for a reason worth stating

Not because it was careful. Because it has no host block to disagree about.

if !looks_structured(&text) {
    if let Mode::Insert { buffer, .. } = &mut self.mode {
        buffer.insert_str(&text);
        self.status = "pasted text".into();
        return;
    }
}
self.graft_paste(text, false);

An unstructured paste in Insert mode is spliced into the EditBuffer, which is the editor, so it is a keystroke. A structured paste calls graft_paste, which commits the in-flight buffer first and then anchors AfterBlock. Either way, nothing rewrites a block while a separate copy of its text is live somewhere else. The TUI gets the shared half of this change anyway, and PasteOutcome is where the answer lives if it ever adopts AtCaret.

what this did not fix

The same mechanism is still live one door over, and it is written down rather than fixed. The desktop draft is seeded once per row instance, setOutline reconciles on id, and a block a peer rewrote keeps its row instance and its old draft. Entering Insert through a path that bypasses startEdit, which i and A do by writing editingBlockId straight from the action handlers, shows the stale text and commits it over the peer’s edit. crates/outl-desktop/CLAUDE.md carries that as a known, pre-existing gap. Same class of defect, different trigger, and a paste is simply the trigger that fires reliably enough to be reported.

The decision itself is 29 added lines of Rust across paste/mod.rs and paste/anchors.rs, with no deletions. The change is 38 files and 1,206 insertions, which is what it costs to carry one offset to three clients and pin it: four tests in outl-actions, the shared reader’s tests, a desktop sequence test, a desktop editor test, a mobile test, and the wire pin. Each one fails if the apply step is removed again, which was verified by removing it.

Three files were already at their size ratchet, so the change came out of them rather than growing them: OutlineView.tsx 942 to 921, commands.ts 872 to 831, Journal.tsx 1,823 to 1,798. api/paste.ts and components/outline-paste.ts are new, and api/types.ts went up by two lines for the re-export that keeps every import path unchanged. .github/file-size-baseline.txt records that raise with its reason, because a ratchet that can be quietly nudged is not one.

The lesson is not that drafts are a bad idea. A draft is the right answer to never making a keystroke wait for the disk: the editor is fast precisely because it owns its text and the workspace catches up. What a mutation reply refreshes is every surface that derives from it, and a draft is not derived from it; it was seeded from it once and has been the authority ever since. So the question to ask before shipping a mutation is not which surfaces will redraw. It is which surface will be the authority on the next write, and whether anybody told it.

PasteOutcome is in crates/outl-actions/src/paste/mod.rs, the two caret derivations are in paste/anchors.rs, and the clients’ one reader is pasteEditorUpdate in crates/outl-frontend-shared/src/paste/index.ts, all in the outl repository.