Clicking into a block with a link puts the caret in the wrong place: the caret map is fed a node-relative offset

[BattermanZ]

Found while doing live acceptance for #252, on Hatchdoor 2.6.1. It is not that bug and not caused by its fix: escaped and unescaped wikilinks are affected identically.

What happens

Click inside a rendered link to start editing that block. The block flips to its Markdown source and the caret lands in the wrong place, roughly where the click was on screen rather than at the character you clicked.

Reproduce

Note body, one paragraph:

See [[Some Note|alias]] TAILWORD here.

It renders as See alias TAILWORD here.. Click between TAIL and WORD, which is rendered offset 19. The caret should land at source offset 50, inside TAILWORD. It lands at 34, one character into alias, inside the link's target.

Measured in the live editor against just dev-start, with a real mouse click:

link form	source	caret lands	should be
[[Some Note|alias]]	60 chars	34	50
[[Some Note\\|alias]]	61 chars	35	51

The one-character difference between the two rows is just the extra escape character, which is what shows the two forms behave alike.

Cause

caretSourceOffset in frontend/src/components/note-page/EditableBlock.tsx (around line 45) does:

const position = doc.caretPositionFromPoint?.(clientX, clientY);
if (position) {
  return sourceOffsetForRenderedOffset(source, position.offset);
}

caretPositionFromPoint returns an offset within the text node under the pointer, but sourceOffsetForRenderedOffset documents and expects an offset within the whole rendered block. In the example the click is inside the TAILWORD here. text node, so position.offset is 5, not 19, and the map faithfully converts the wrong number. The same applies to the WebKit caretRangeFromPoint branch just below it.

sourceOffsetForRenderedOffset itself is correct: given 19 it returns 50.

Scope

Any block whose rendered output splits into more than one node is affected, so links, bold, italic and inline code, not only wikilinks. A block of plain prose is a single text node, where the node-relative and block-relative offsets coincide, which is why this has gone unnoticed.

Suggested fix

Walk from the block root to the returned node and add up the text length in front of it, then pass that block-relative offset to sourceOffsetForRenderedOffset. Worth a test per inline construct, since the current unit tests exercise the map with correct input and so never catch the caller.

[BattermanZ]

This was generated by AI during triage.

Agent Brief

Category: bug

Summary: The click-to-edit caret map is handed an offset measured inside a single text node while it expects one measured across the whole rendered block, so clicking into any block that renders as more than one node lands the caret in the wrong place.

Verified during triage

Reproduced the mechanism in headless Chromium on a paragraph rendering as See alias TAILWORD here., where alias is a link, so the paragraph has three child nodes. Clicking between TAIL and WORD:

reading	value
offset across the whole rendered block	14
caretPositionFromPoint(...).offset	5
caretRangeFromPoint(...).startOffset	5

Both browser APIs report the position inside the text node under the pointer, which is the third node here. Walking the reported example source by hand through the map: fed 5 it returns an offset inside the link's target, fed the correct 14 it returns the character that was clicked. The map is correct. Its caller measures the wrong thing, on both the standard and the WebKit branch.

Current behavior

Entering a block by click asks the browser for a caret position at the pointer and passes the returned offset straight to the rendered-to-source map. That offset is relative to the text node under the pointer, not to the block, so the map converts a number that means something else. A block of plain prose is a single text node, where the two readings coincide, which is why only blocks containing links, bold, italic or inline code are visibly wrong.

Desired behavior

The offset handed to the map is measured across the block's whole rendered text: the sum of the text length of every text node before the one under the pointer, plus the offset within it.

Three cases must not produce a confident wrong answer, and should fall back to no caret preference, which opens the block with the default caret:

• the browser reports no position at all;
• the reported node is not inside this block, which is possible because both APIs are document-wide and a click can land on padding or a neighbouring block;
• the reported node is an element rather than a text node, where the offset counts child nodes rather than characters.

The map's own approximation rule stands unchanged: landing a few characters out is fine, landing always at 0 or always at the end is not.

Key interfaces

• The rendered-to-source map (sourceOffsetForRenderedOffset) keeps its current signature, contract and behavior. It is not the defect and must not be edited to compensate for its caller.
• The conversion from (block root, reported node, offset within that node) to a block-relative offset should be its own function so it can be tested directly. jsdom implements neither caret API, so the existing click-path tests cannot reach this code, and a function taking a hand-built DOM is the only seam where a test can fail today and pass after the fix.
• The block wrapper already holds a ref to its own root element, which is what bounds the walk.

Acceptance criteria

• Clicking a character after a wikilink, in a paragraph such as See [[Some Note|alias]] TAILWORD here., opens the block with the caret on the clicked character rather than inside the link target.
• The same holds for the escaped form [[Some Note\|alias]], which the reporter measured as behaving identically.
• The same holds for a Markdown link [label](/target), bold, italic and inline code.
• Plain-prose blocks, which are a single text node, keep their current behavior exactly.
• A reported node outside the clicked block, or an element node rather than a text node, yields no caret preference rather than an offset.
• New unit tests cover the node-to-block conversion for each inline construct above, against a constructed DOM, and fail against the current caller.
• caretMap's existing tests pass unmodified.

Out of scope

• Multi-line blocks. A hard-wrapped paragraph is one block over two source lines and the map's line-prefix handling only looks at the start of the string. Separate defect, separate ticket.
• Improving the map's approximations for syntax that has no rendered counterpart.
• Block entry gestures: the double-tap rule on touch, the click targets that keep their own behavior, keyboard entry.
• The block-editor replacement option sketched in docs/architecture/frontend-assessment.md.

Work packet

Outcome: as stated under Desired behavior. This packet narrows the reported outcome and authorizes no broader work or opportunistic cleanup.

Boundaries

• Module: Note editing and vault actions. Kind: product capability/adapter; safety-sensitive.

Owned paths

• frontend/src/components/note-page/EditableBlock.tsx
• frontend/src/lib/caretMap.ts and frontend/src/lib/caretMap.test.ts
• one new module for the DOM walk plus its test, if the seam is extracted, under frontend/src/lib/ or frontend/src/components/note-page/

Public contract

Stable: sourceOffsetForRenderedOffset(source, renderedOffset) and the inline block editing behavior the module map already records. Declared changes: none. The fix is internal to the module, so no interface-change checklist is triggered.

Coordination paths

• docs/architecture/module-map.md — only if a production file is added, and only to list it under this module's owned paths and validation.

Consumed dependencies

• The inline editor context (enterBlock, sourceOf) and the line mapping in frontend/src/lib/sourceMap.ts. Used, not owned.

Forbidden paths and invariants

• Do not change block operations, autosave, or the write path. Nothing re-serializes a note; edits replace only the lines a block owns.
• Do not change the map's behavior for correct input.
• Do not widen the diff to multi-line block support.

Validation

Focused, from frontend/:

npx vitest run src/lib/caretMap.test.ts src/components/note-page/inlineEditing.test.tsx

plus the new test file.

Full, from frontend/:

npm ci
npm run lint
npm run typecheck
npm test
npm run build

From the repository root, only if a production file is added or moved:

node scripts/check-module-map.mjs

[BattermanZ]

This was generated by AI.

Fixed by #283, merged into development as 98974c8.

The caret map now receives an offset measured across the block's whole rendered text rather than one measured inside the text node under the pointer. caretMap itself was not touched; it was being handed the wrong number, not applying the wrong rule.

Verified in the live editor with real mouse clicks on the W of TAILWORD, one block per inline construct. Every case lands on the clicked character, and plain prose is unchanged.

link form	caret lands	should be
[[Some Note|alias]]	28	28
[[Some Note\\|alias]]	29	29
[alias](/target)	25	25
**alias**	18	18
*alias*	16	16
`alias`	16	16
plain prose	14	14

The multi-line follow-up this issue deferred is filed as #284, with one correction: an unindented hard-wrapped paragraph turns out to map correctly today. The defect there is indentation on continuation lines, plus a separate chrome problem on fenced code blocks.