[ethan-james]

Fixes #5981.

After a double tap on iOS 27, a tap within the thought being edited is withheld (#5660), and iOS moves the caret into the tapped word and then back to where it was before the tap, within about 300ms. A new useRevertCorrection hook, mounted beside useCaretRestore on the thought being edited and on a focused note, notices that return while the tap is still open and puts the caret where the tap landed, on the next animation frame. On a thought it goes through the same setCaretOffset as useEditMode's mousedown handler, so the cursor offset in Redux follows the corrected caret.

The return is detected from the selection itself rather than after a fixed delay: on devices it came between 150ms and 280ms after the touchstart, and on BrowserStack at about 145ms. A move back to the offset the caret had before the touch is only treated as a revert while the touch is still open, and only after the selection first moved away from it. There is no time limit: the watch ends with the touch, at its touchend or touchcancel or once it moves farther than TOUCH_SLOP, or on any other input, namely a touchstart, mousedown, keydown or beforeinput anywhere. A tap whose computed offset is the caret's own position, such as a tap on the caret, is left alone.

Plan

1. Existing surface area

• docs/cursor-and-caret.md "Caret restoration on iOS": useCaretRestore "keeps the caret where it belongs, scoped to isTouch && isSafari(). It registers a selectionchange listener that restores the caret to its editable when the selection has left it". The restore is to one end of the text "rather than to a remembered position, which cannot go stale against an edit that shortens the value".
• src/components/Editable/useCaretRestore.ts already tracks the press on the editable and reacts to selectionchange, but deliberately ignores a press in progress:

  const onTouchStart = () => {
    pressingRef.current = true
    scrubbingRef.current = false
  }
  ...
  if (pressingRef.current || lastTouch.isRecent()) return

  It is mounted for the thought being edited (useEditMode.ts:66, useCaretRestore({ editableRef: contentRef, enabled: isCursor && !!editing })) and for a focused note (Note.tsx:83).
• src/device/getCaretOffset.ts:459 computes the offset a tap at a point places the caret at, with iOS-style word snapping, and is what useEditMode's onMouseDown uses for a tap that is not withheld:

  const getCaretOffset = (editable: HTMLElement | null, { clientX, clientY }: Coordinates): CaretOffsetResult => {

• src/device/selection.ts:259-261 offsetFromNode(node) returns the caret offset within an editable, or null when the selection is outside it:

  export const offsetFromNode = (node: Node): number | null => {
    const selection = window.getSelection()
    if (!selection?.focusNode || !node.contains(selection.focusNode)) return null

• src/stores/osVersionStore.ts gates other iOS 27 workarounds (useLongPress.ts:135):

  if (!pressing || (osVersionStore.getState() ?? 0) < 27) return

2. Build vs. extend

Extend two existing pieces. initEvents' capture-phase touchstart already latches per-touch state into touchStore (pressOnCaret, measuring the caret once per touch), so it records the watch there too, and its capture-phase listeners end it on any other input. The correction itself is a new hook, useRevertCorrection, mounted wherever useCaretRestore is (the thought being edited and a focused note), with the same scoping. useCaretRestore keeps its one job, the keyboard trackpad. On a thought, useEditMode passes its setCaretOffset, hoisted out of its caret effect so that onMouseDown and the correction share it.

3. Adjacent behaviour

• Keyboard trackpad restore ([iOS] Caret disappears after using virtual keyboard trackpad #3276): unchanged. useCaretRestore is untouched, and the correction is a separate hook that only acts while a watch is open.
• Caret drag / loupe: on device, drags that swept back across their starting offset were taken for a revert, flashing the caret to the word edge mid-drag. The watch now ends once the touch moves farther than TOUCH_SLOP. A slow drag becomes a long press, and the mousedown iOS sends about 600ms in ends the watch before the loupe moves the caret. In about 40 device drags, the watch always ended before the first caret move.
• Double tap: the word selection is a range, which is ignored. The first tap of a double tap can move and return (seen on a device as 9 then 14), but there the computed offset equals the original one, so nothing is done.
• Taps with mouse events: useEditMode's onMouseDown and iOS's own placement are unaffected ([iOS] Caret: a tap near the start of a word puts the caret at its end after a double tap on iOS 27 #5982 is separate).
• iOS 26 and earlier: the watch only starts on WebKit 27, where touchend is withheld, and ends at the touchend. On earlier versions the revert of a tap near the caret comes after the touchend ([iOS] Caret is not moved to adjacent word when tapping in the proximity of 4 -5 characters #4220), so it is not covered here. Put the caret where a tap landed when iOS reverts it after the touchend #6002 removes both the version gate and the touchend end to cover it.
• Typing, undo, IME: each sends a keydown or beforeinput, which ends the watch.

4. Approaches

• Timer after the touch (as in Re-place the caret on iOS when WebKit reverts a tap near the caret #5655): rejected. The revert's timing varies, and a timer either races it or adds a visible delay.
• In useEditMode's caret effect (the prototype): rejected. It would cover thoughts only and duplicate the press tracking useCaretRestore already does.
• All in useCaretRestore, with its own listeners per editable: rejected. It duplicates the touch tracking initEvents already does for every touch.
• Correction inside useCaretRestore: rejected. It mixes two unrelated jobs behind one selectionchange listener and only sets the DOM selection, leaving the cursor offset in Redux behind.
• Watch in initEvents and touchStore, correction in useRevertCorrection, applied through useEditMode's setCaretOffset on thoughts: chosen.

5. Diff sketch

• touchStore.ts: a revertWatch field.
• initEvents.ts: in the capture-phase touchstart, on WebKit 27, record the focused editable, the touch point and the collapsed caret offset of a single-finger touch. Capture-phase listeners end the watch on touchend, touchcancel, mousedown, keydown, beforeinput, and a touchmove beyond TOUCH_SLOP.
• useRevertCorrection.ts (new): on selectionchange, mark a move away from that offset, and on the return place the caret at getCaretOffset of the touch point, through onCorrect if given.
• useEditMode.ts: hoist setCaretOffset and pass it to useRevertCorrection. Note.tsx: mount useRevertCorrection.
• docs/cursor-and-caret.md: a paragraph under "Caret restoration on iOS".
• The BrowserStack test in doubleTap.ios27.ts, unskipped.

[github-actions]

Preview Deployment · Oct 27, 2026, 6:08 PM UTC · 10a4e72

[ethan-james]

Too many return statements in this function, but they all have a purpose. Would it be better to move them into helper functions?

[trevinhofmann]

The return statements are reasonable IMO, but it might be helpful to include a comment for each explaining what that purpose is.

[trevinhofmann]

Generally LGTM, just a few minor comments below.

[trevinhofmann]

The return statements are reasonable IMO, but it might be helpful to include a comment for each explaining what that purpose is.

[trevinhofmann]

Is there a reason to use toBeGreaterThanOrEqual rather than asserting the exact expected offset?

[ethan-james]

Copilot says:

The exact value would be 15, 'Existentialism '.length, the start of "eternally". But asserting it exactly would make the test depend on details that don't matter to the user.

An exact 15 tests em's word snapping, not the bug. It would depend on where the synthesized tap lands relative to the middle of the word. 19 is only half a character from tying with the end. A slightly different landing could snap to 24, which is just as correct.

I would support that argument mainly because our word snapping works a little differently from Safari's, and I foresee a future in which we fix that because it can be annoying to have the caret bouncing around.

[trevinhofmann]

There's a potential race condition here, but I'm not sure how we can avoid it without adding complexity to the implementation.

Maybe we could wait for the offset where iOS moves the caret, and then wait for the offset where we place the caret back? There's likely a separate worse race condition there, though, where the caret is placed back before the test detects the original move by iOS.

IMO, this await browser.pause isn't ideal, but acceptable as-is and the comment clarifying the 300ms-vs-1000ms race helps justify it.

[ethan-james]

OK, I worked out a version that waits for the revert and correct events, or passes if they don't arrive by the timeout. That way it will fail if a revert goes uncorrected, but will pass if the revert never occurs.

[ethan-james]

If #6123 is merged, the revert correction will go into #6002 and the iOS 27-specific part can be discarded.

[trevinhofmann]

LGTM, pending the merge conflicts and #6123 / #6002 related changes. @ethan-james - LMK if you'd like another review if any meaningful changes are pushed based on those.

[raineorshine]

Hi, thanks for the submission. I have spent some time looking at the proposed change.

I have some concerns about the risk that we would be taking on. This PR adds multiple effects, refs, timers, requestAnimationFrame, selectionchange listeners, out-of-dispatch direct store access, direct DOM access, persistent ministore state, and manual browser selection. It's simply too much complexity for what it does. I don't think I would be comfortable merging it as it stands.

Does the strategy change at all given that #6123 has been discontinued and we plan on waiting for the next Safari patch to fix the withheld touch in iOS27?

FYI I'm still seeing incorrect caret placement with this PR, though it appears slightly different than the original issue. Here the caret is set at the end of "eternally" after tapping at the end of "Existentialism". I'm not sure if this would be considered to share the same root cause or if this PR is meant to have a more limited scope.

I'm going to put the original issue #5981 on hold since we have higher priority issues. I would still be interested in hearing any other thoughts you have on this. Thank you!

[ethan-james]

Hi, thanks for the submission. I have spent some time looking at the proposed change.

I have some concerns about the risk that we would be taking on. This PR adds multiple effects, refs, timers, requestAnimationFrame, selectionchange listeners, out-of-dispatch direct store access, direct DOM access, persistent ministore state, and manual browser selection. It's simply too much complexity for what it does. I don't think I would be comfortable merging it as it stands.

Does the strategy change at all given that #6123 has been discontinued and we plan on waiting for the next Safari patch to fix the withheld touch in iOS27?

#5981 is specific to iOS 27, so everything in here is required to make it work there. This was also the base branch for #6002, which fixes #4220. Since we're not going forward with this PR, I moved the core architecture over into that branch and rebased it on main. That will run on all iOS versions and doesn't fix #5981, but it seems to be about half as complicated. That solution gets rid of the changes in initEvents and touchStore, as well as the extra stuff in useEditMode apart from the invocation of the new hook.

There's still one effect in useRevertCorrection, plus the selectionchange handler that is load-bearing for the caret corrections. That seems to be the only signal that iOS moved the caret. And selection.set is the only way to put the caret back after it was moved.

There are still a bunch of new event handlers to catch all of the events that end the revert window, rather than the arbitrary CARET_REVERT_TIMEOUT timer from #5665.

Next Steps

I could look into moving selection.set plus the dispatch out into useEditMode and see if they can be shared with the existing caret management code. That could result in simplification, or it could end up being more complicated.

requestAnimationFrame is still in there but I'm going to dig into whether it's necessary in the new version.

FYI I'm still seeing incorrect caret placement with this PR, though it appears slightly different than the original issue. Here the caret is set at the end of "eternally" after tapping at the end of "Existentialism". I'm not sure if this would be considered to share the same root cause or if this PR is meant to have a more limited scope.

I'll double check now that it's all living in the #4220 branch. That corrects a wider range of caret revert behavior than this PR. Since it's based around proximity to the caret, setting it at the end of "eternally" probably wouldn't be fixed by #6002. iOS behavior shouldn't be reverting the caret from more than about 40px away.

I tried to figure out if the 44px dead zone was connected to this, but Copilot didn't think that constant was likely to be used anywhere else. It would probably be in closed-source UIKit code rather than WebKit.

I'm going to put the original issue #5981 on hold since we have higher priority issues. I would still be interested in hearing any other thoughts you have on this. Thank you!

You're welcome! Let me know if #6002 seems like it's still too complex.