Investigate live preview caret behavior in empty list items

[jsgrrchg]

Problem

Live preview has an edge case with empty Markdown list items where the caret and bullet marker become visually misaligned or confusing.

Observed examples:

- Probando
- 
    - eeeee

or nested variants such as:

- eeeee
    - 

In live preview, the empty item can show a preview bullet while the caret appears on a separate/awkward visual position, or the raw - marker can appear if we reveal the Markdown source. The result feels unstable: neither fully polished live preview nor fully honest source editing.

Why this is tricky

The rendered bullet is currently a CSS pseudo-element on the line decoration (.cm-lp-li-line::before). It is not real editable document text. CodeMirror still needs a real document position to place the caret when the user is editing an empty list item.

That creates a three-way tension:

• Keep the live preview bullet visible and hide raw - .
• Keep a stable, editable caret position where typing continues the list item.
• Avoid ghost spacing, duplicated markers, or the caret appearing detached from the bullet.

For non-empty list items this works well because there is real content after the marker. For empty list items, the only editable anchor is the marker/spacing itself.

Approaches Tried

1. Reveal raw Markdown for active empty list items

Behavior:

• If the item is active and empty, skip live-preview list decoration for that line.
• Show - / - as raw Markdown.

Pros:

• Technically stable.
• Caret position is honest and predictable.
• Avoids fighting CodeMirror's caret model.

Cons:

• Visually jarring in live preview.
• The raw - appears while editing, which is not the desired polished preview behavior.

Outcome: rejected because it fixed caret anchoring but degraded the live preview UX.

2. Hide the marker and replace only the trailing marker space with an invisible zero-width anchor

Behavior:

• Keep the pseudo-bullet.
• Hide the raw marker.
• Replace the final source space with a tiny/zero-width widget so CodeMirror has an anchor.

Pros:

• Avoided showing raw -.
• Preserved the preview bullet.

Cons:

• The caret still appeared awkwardly positioned in practice.
• The source-space/widget interaction remained too dependent on CodeMirror inline layout details.

Outcome: rejected because the visual edge case still reproduced.

3. Replace the whole empty list prefix with an inline caret shim widget

Behavior:

• Replace - or - with a widget that draws the bullet and reserves indent + marker + gap width.
• Let the caret sit immediately after that widget.

Pros:

• More principled than a zero-width anchor.
• Tests could verify the decoration model for normal and nested empty list items.

Cons:

• Still did not feel correct visually in the real editor.
• The widget is contenteditable=false, so caret placement around it remains delicate.
• Risks around keyboard navigation, IME composition, accessibility, selection, and screen reader behavior.

Outcome: rejected after manual visual testing.

Related Code

Likely hotspots:

• apps/desktop/src/features/editor/extensions/livePreviewInline.ts
• listMarkRule
• applyLooseListFallback
• isActiveEmptyListLine
• apps/desktop/src/features/editor/extensions/livePreviewTheme.ts
• .cm-lp-li-line::before
• .cm-lp-list-continuation
• apps/desktop/src/features/editor/markdownLists.ts
• parseMarkdownListItem

Current Understanding

This is probably not a simple CSS spacing bug. It is an editing-model problem caused by rendering list markers as pseudo-elements while hiding the actual source marker. Empty list items have no content after the marker, so the caret has no natural visible text anchor.

A robust solution may need a more explicit editing mode for active empty list items, possibly accepting that raw Markdown should appear for that exact line, or introducing a custom CodeMirror widget/decoration strategy with careful browser-level testing.

Acceptance Criteria for a Future Fix

• Empty unordered list items in live preview do not show duplicated/ghost markers.
• Empty nested list items behave consistently with top-level empty items.
• The caret appears visually attached to the intended typing position.
• Typing into the empty item immediately produces a normal live-preview list item.
• Backspace/Enter/Tab/Shift-Tab behavior remains correct.
• Task list items (- [ ]) are not regressed.
• Multiline selection across list items still reveals raw Markdown where appropriate.
• IME/composition and accessibility are considered before shipping.

Notes

This came up while hardening live preview caret behavior. A separate inline emphasis boundary issue was fixed independently in PR #101; this issue is specifically about empty list item caret/list marker behavior.

[spamsch]

Started by pinning the bug down with two failing tests in apps/desktop/src/features/editor/extensions/livePreviewInline.test.ts. They encode the acceptance criterion that top-level and nested active empty list items must behave the same way — specifically, the trailing source space after the marker must be collapsed so the caret sits flush with the rendered bullet instead of one column past it.

// Regression coverage for jsgrrchg/NeverWrite#102.
// The live-preview line already reserves padding for indent + marker
// + gap, and the bullet is drawn as a CSS pseudo-element. The trailing
// source space after the marker must be collapsed too — otherwise it
// renders as a real character past the pseudo-bullet and pushes the
// caret one column away from the bullet, the artifact described in #102.
it("collapses the trailing marker space on an active empty top-level list item (#102)", () => {
    const { plugin, parent, view } = createView(
        "- ",
        EditorSelection.cursor(2),
    );

    const decorations = collectDecorations(view, plugin);

    expect(hasHiddenRange(decorations, 0, 2)).toBe(true);

    view.destroy();
    parent.remove();
});

it("collapses the trailing marker space on an active empty nested list item (#102)", () => {
    const doc = "- parent\n    - ";
    const { plugin, parent, view } = createView(
        doc,
        EditorSelection.cursor(doc.length),
    );

    const decorations = collectDecorations(view, plugin);

    // Line 2 spans positions 9..15 ("    - "). The whole prefix should
    // be hidden so the caret sits flush with the rendered bullet,
    // matching the behaviour expected for top-level empty items.
    expect(hasHiddenRange(decorations, 9, doc.length)).toBe(true);

    view.destroy();
    parent.remove();
});

Both fail today against listMarkRule in livePreviewInline.ts, where the active-empty branch only hides line.from..node.to (the marker) and leaves the trailing source space visible:

× collapses the trailing marker space on an active empty top-level list item (#102)
  AssertionError: expected false to be true
  expect(hasHiddenRange(decorations, 0, 2)).toBe(true);

× collapses the trailing marker space on an active empty nested list item (#102)
  AssertionError: expected false to be true
  expect(hasHiddenRange(decorations, 9, doc.length)).toBe(true);

This is closest in spirit to approach 2 from the issue description (collapse the source space) and is intentionally a decoration-model assertion, not a layout assertion — vitest/jsdom can't measure the caret pixel position, so the test pins the model state that should produce a correctly anchored caret. Open question before going further: is collapsing the trailing space (with no widget anchor) the direction worth re-trying, or should the test instead assert a widget-based anchor at that position?

[jsgrrchg]

Your take makes a lot of sense, I'm over complicating things, I think it’s worth retrying the simpler model first, collapse the full active empty-list prefix, including the trailing marker space, without adding a widget anchor yet.

The “space after the marker remains as real text” explanation matches the visual artifact we’re seeing. If hiding - / - entirely gives CodeMirror a sane caret position in manual testing, that’s much cleaner than the shim approach.

[spamsch]

Pushed a starting point for reproducing this in tests on a branch in my fork: tests/issue-102-empty-list-caret (commit).

Two layers, both failing on main against listMarkRule in livePreviewInline.ts:

Model layer — vitest (jsdom)

apps/desktop/src/features/editor/extensions/livePreviewInline.test.ts — two new tests that assert the full prefix (- and -) is collapsed for an active empty list item. Today only the marker character is hidden; the trailing source space stays visible.

Visual layer — Playwright (chromium)

New e2e harness under apps/desktop/e2e/ — mounts a minimal CodeMirror EditorView with createInlineLivePreviewPlugin + livePreviewTheme, then measures the native caret rect against the line's content-box left edge (line.left + paddingLeft).

Reproduces a 9.59 px offset (≈1ch in 16px monospace) for both top-level - and nested - — the trailing space rendering past the pseudo-bullet:

× active empty top-level list item: caret sits flush with the bullet (#102)
  expect(Math.abs(cursorLeft - contentBoxLeft)).toBeLessThan(2);
  Received: 9.5912

× active empty nested list item: caret sits flush with the bullet (#102)
  Received: 9.5912

✓ non-empty list item: caret sits flush with content (control)

Same gap at both nesting levels — confirms the issue's "nested should behave consistently with top-level" criterion at the pixel level.

Note: this is a starting point, not a fix. No change to listMarkRule is included. The decoration-model assertion (hasHiddenRange(decorations, 0, 2)) encodes one possible direction (approach 2 from the issue body — collapse the trailing space) without prescribing a widget anchor. Whether the right resolution is space-collapsing, a widget shim, or something else entirely is the open design question — the tests just pin the symptom so any chosen fix has a target.

Harness scripts: npm run test:e2e (CI) / npm run test:e2e:ui (debug).

[jsgrrchg]

Great! I'll take a look, thank you so much.

[jsgrrchg]

This is excellent, thank you. The Playwright layer is especially helpful because it turns the “caret feels off” issue into a measurable 1ch offset, great idea.

I agree with the direction, the simplest next step seems to be collapsing the full active empty-list prefix, including the trailing marker space, without introducing a widget anchor yet. If that passes both the decoration model tests and the Chromium caret measurement, it’s much cleaner than the shim approach.

If you’re up for it, I’d be very happy for you to take the fix from here using this branch as the target 🙏. This is a bit outside my current skill set, so I’d be happy to learn from your approach.

[jsgrrchg]

Hey, I tried the straightforward fix based on your diagnosis to try fix it myself in listMarkRule, I changed the empty active list item case so it collapses the full prefix (- / -) instead of only the marker character.

That made the decoration/model-level tests pass, including top-level, nested, and empty task-list cases. But after testing it visually in the editor, the caret can still end up hidden/misplaced for an active empty list item.

So I think your diagnosis about the trailing source space is correct, but it seems to be only one layer of the issue. Once the full prefix is collapsed, the line still has no real visible text anchor for the native caret, since the bullet is rendered by live preview decorations/styling rather than editable text.

My takeaway is that the final fix probably needs a visual/DOM strategy for active empty list items, not just collapsing the trailing space.

The branch where I tested is test/empty-list-caret-prefix-collapse, I already push it.

Here’s a screenshot of the caret partially hidden after the attempted fix.

[spamsch]

Good catch — confirmed and pinned in the e2e suite.

I pulled test/empty-list-caret-prefix-collapse and ran my Playwright spec against it. With the prefix collapsed, horizontal position is correct (within 2 px) but the native caret rect comes back as 0×0 — there is no editable glyph to anchor the browser's caret to, so Selection.getRangeAt(0).getClientRects() reports a zero-sized rect. Visually the caret disappears, which matches your screenshot.

Strengthened the spec (d5ecda5) to assert caret height ≥ 10 px in addition to horizontal position. Both #102 e2e tests now fail in both states:

State	Position assertion	Visibility assertion
main (today)	❌ caret ~9.6 px past content-box	✅ caret has line-height
test/empty-list-caret-prefix-collapse	✅ within 2 px	❌ caret is 0×0

So the bar a real fix has to clear: caret must be at content-box left and have a non-zero rect. That rules out both the trailing-space-leak state and the "collapse everything" state, and points squarely at the visual/DOM strategy you described — keeping a real editable anchor on the line (a real glyph, a zero-width-non-breaking-space, a WidgetType that exposes itself as text to selection, or wiring up the drawSelection extension which renders an explicit cursor element with its own height independent of text content).

Branch: tests/issue-102-empty-list-caret on my fork.

[jsgrrchg]

Quick update: I think we found a working direction. I spent the afternoon trying different approaches.

The simple full-prefix collapse fixed the horizontal offset, but as you predicted it still left the caret with no real geometry in some cases. The version that worked is a combination of:

1. Collapse the full source prefix for active empty list items (- / -), and also the full task prefix ([ ] ).
2. Add a tiny zero-width caret anchor widget only for active empty list items, so drawSelection() has real geometry to measure without changing the global cursor styling.
3. Normalize clicks that land inside the collapsed source prefix: if CodeMirror resolves the click to a hidden prefix position, move the selection to the visual content start instead.

That last part was important: Enter worked, but clicking near the bullet could still place the caret inside the collapsed prefix and make it disappear again.

With that approach, the unit tests pass and I added an e2e case for clicking the hidden prefix too:

• 44/44 unit tests passing
• 10/10 Playwright e2e tests passing

This feels much more natural than the global cursor min-height workaround. I linked a PR to this issue, if you can please give it a check. This still has one little flaw, the dot is unaligned vertically with the text by a few pixels, Im working on that now.

[jsgrrchg]

The alignment issue was easy, thank God 😂 It’s already up in the PR. Simon, thank you so much for your help and expertise.

Best

José.-