Skip to content

fix(smart-toolbar): keep a Paint format press made before the engine loads - #77

Merged
HMarzban merged 35 commits into
mainfrom
fix/paint-early-click
Nov 15, 2026
Merged

HMarzban merged 35 commits into
mainfrom
fix/paint-early-click

Conversation

@HMarzban

Copy link
Copy Markdown
Contributor

What and why

Clicking the Paint format brush (selection bubble or phone selection cells) before the lazy formatting engine had loaded showed nothing, and the press was dropped as soon as the user selected the text to paint. For Paint format, selecting the target is the intended next step, so the brush must survive that move.

Now the brush shows pressed at once, with the copy cursor and the "Select text to paint · Esc to cancel" pill (touch: "Select text, then tap the brush again"). It keeps the text it was pressed on, and once the engine lands it arms on that text. If a mouse selection of other text ended in the meantime (on touch, the brush was tapped again on new text), it paints that selection too. A second press on the same text, or Esc in the text, cancels. A failed load says "Couldn’t load formatting tools." with Retry, which presses again on the same text. Other queued E actions (Repeat key, palette rows, ⋯ menu) keep the "only if the selection has not moved" rule.

Root cause

  • PaintFormatButton went through runWithEngine (lib/editor-actions/v11-actions.ts). That runs a queued action only if the selection has not moved, and the brush had no pending state to render.
  • A second issue turned up while fixing it. y-tiptap's relative positions stick to the character on their left. Stored as is, the pressed range widened when someone (for example a collaborator) typed right before it, and then picked up "plain". The start is now kept one character in, on the first pressed character. A unit test covers a remote insert at that boundary.

Changes

  • components/smart-toolbar/formats/paint-pending.ts (new, lazy surface chunks only). It holds the pending press per editor (WeakMap), the usePainting hook (moved from use-e-action.ts, its only user is the brush) and pressBrush. Its listeners exist only while a press is pending. The range is a Yjs-relative SessionRange (absolute positions mapped per transaction without a binding). A landing in the middle of a drag waits for that drag's pointer-up.
  • lib/editor-actions/paint-format.ts: togglePaint(editor, touch, source?) arms on a given range. The bundle is read from EditorState.create({ doc, selection }), so bundle.ts is untouched (the palette imports it).
  • lib/editor-actions/paint-format-ui.ts (new): PAINTING_CLASS and PAINT_PILLS, shared by the engine and the pending press without pulling the engine in.
  • v11-actions.ts: ENGINE_LOAD_FAILED is now exported for both failure paths. The toggle type gains a source argument.
  • relative-range.ts: toSessionRange takes { anchor, head } (type only).

How verified

  • bun run check, bun run lint, bun run typecheck, bun run test (1239 pass).
  • New unit tests in tests/unit/components/paint-pending.test.ts:
    • a collaborator's insert before the pressed text
    • arm only when the selection did not move
    • a landing mid-drag waits for the pointer-up
    • a second press or Esc cancels
    • read-only drops the press
  • New e2e tests (engine chunk held through the new holdChunk() helper until after the selection moved):
    • paint-format.spec.ts:
      • pressed at once, and the drag is painted once the engine lands
      • the range follows a paragraph inserted before it
      • a second click or Esc cancels, and nothing is painted
      • a keyboard selection then ⌘⌥V paints
    • mobile-bar.spec.ts: the touch case
    • selection-bubble.spec.ts: the queued-click test now also asserts the immediate pressed state
  • Every new or changed test ran with --repeat-each=5 after the final code change (30/30).
  • Full runs passed for paint-format, selection-bubble, lazy-surfaces (its 404 + Retry brush case included), mobile-bar, palette and editor-leak (chromium, own servers on 6504/4504).
  • Before/after screenshots (1440 bubble and 375 phone cells, light and dark; clicked, target selected, landed) are in the session scratchpad (wf2/paint-early-click/{before,after}). Before: the brush stays unpressed, and on the phone it ends up armed on the target instead of painting it. After: pressed with the pill right away, and the target painted with "Formatting applied". PAINT_EARLY_SCREENS_DIR=<dir> regenerates them.

Budgets

  • Eager editor chunk: 397,407 → 397,417 B gz, +10 B (the exported ENGINE_LOAD_FAILED). The Hocus URL is not in the eager group, so the two builds compare cleanly.
  • Palette first Alt+/ (PALETTE_BUDGET=1, production build): 20,475 → 20,475 B, 0 B (same chunk hashes).

Follow-ups

  • ⋯ → Paint format and the palette's Paint format still use the unmoved-selection rule before the engine lands. The palette loads after the engine, so in practice this is only the ⋯ menu.
  • Without a Yjs binding (absolute ranges), text typed right after the pressed text joins the range.
  • Pre-existing and not investigated: in a test, a raw tr.insert(paragraph.create(...)) dispatched through view.dispatch made the next mouse drag collapse to a caret near the end of the document (via ProseMirror's readDOMChange). It happens without the brush. The e2e test uses insertContentAt instead.
  • palette.spec.ts, lazy-surfaces.spec.ts and selection-bubble.spec.ts each keep a local copy of the hold-chunk helper. They could use holdChunk().

The phone status pill spans the docked bar's width 8px above it, in
the band where the presence and Discord/GitHub/Privacy chips float, so
a refused "/" pick, a removed format's Undo or an unavailable cell's
reason covered them. Hide the chips while the bar holds a pill, as
they already hide for the selection bar; they come back when it closes.
The colour hover preview drew one decoration over each selection range,
so Red text or Yellow highlight showed over inline code and code blocks
although applying never colours them: inlineCode excludes every mark
and a code block allows none.

setActionPreview now takes { attrs, mark } and decorates only the inline
nodes addMark would mark (the parent allows the mark and no mark on the
node excludes it), merging adjacent runs. A collaborator's redraw keeps
the same rule.

A highlight preview's run that starts after the selection nests the
blurred selection's span inside its mark, so the colour panel's
stylesheet keeps that tint off.
…loads

A brush press before the lazy formatting engine landed went through
runWithEngine, which runs a queued action only if the selection has not
moved. For Paint format the next selection is the intended next step, so
the press was dropped and the brush never showed pressed.

The brushes now keep the press in paint-pending.ts: pressed at once, with
the copy cursor and the pill, the pressed text kept as a session range
that follows edits. Once the engine lands it arms on that range and paints
a mouse selection made meanwhile (on touch, the second tap). Other queued
actions keep the unmoved-selection rule.
A pointer-up that started in the text set the pending press's apply
flag even for a plain click, and landing then painted whatever was
selected, a keyboard selection too. Read the selection a frame after
the pointer-up, as the armed listener does, keep it only when it is
other text, and on landing paint only if it is still that selection;
otherwise just arm. The touch second press keeps its selection the
same way.
@HMarzban

Copy link
Copy Markdown
Contributor Author

Review blockers fixed in 2a853fe (code + tests) and d802534 (docs).

1. apply stuck on and did not follow the selection (paint-pending.ts).

  • apply: boolean is replaced by target: SessionRange | null, the selection to paint on landing.
  • Mouse. On a pointer-up that started in the text, the selection is read a frame later, as the armed listener in paint-format.ts does. It is kept only if it is other text: non-empty and not the source. A caret click resets target to null, and the latest pointer-up wins.
  • Touch. The second press keeps the current selection the same way.
  • Edits. target is mapped through transactions like source. It is stored as a Yjs relative position in a collaborative editor.
  • Landing. land() paints only if sameRange(fromSessionRange(state, target), state.selection) and the selection is still other text. Otherwise it only arms. A Retry after a failed load starts with target: null.
  • Race. dragging now stays true until the pointer-up's frame has run. An engine landing between the pointer-up and that frame waits for it (landOnUp), so a drag that has just ended is not lost.

Tests

  • New unit tests in tests/unit/components/paint-pending.test.ts:
    • Caret click, the pointer-up's frame, then keyboard selection sel("wor"), then landing: it arms only and "wor" is unpainted.
    • A mouse selection, then a keyboard change before landing: it arms only.
    • A landing right after the pointer-up, before its frame: it paints at the frame.
  • How the unit tests differ from your repro. They hold requestAnimationFrame (Object.defineProperty on globalThis, restored in afterEach) and run the pointer-up's frame before sel("wor"). In your sequence sel("wor") runs in the same tick as the pointer-up, before the frame. A real Shift+Arrow cannot arrive that early, and the armed path would read "wor" there too.
  • Confirmed failing before the fix. The two arm-only unit tests fail against b2f9da3.
  • New e2e in paint-format.spec.ts: "a click in the text then Shift+arrows while it loads only arms; nothing is painted". It holds the engine chunk, clicks into "target", presses Shift+ArrowRight twice, then releases the engine. It asserts "Picked up …", the brush still pressed, and only "source" marked. It fails against b2f9da3.

Checks

  • bun run check: only the 7 warnings already there.
  • bun run lint, bun run typecheck and bun run test (1242 pass) are clean.
  • Playwright (chromium) passed in full: paint-format, selection-bubble, lazy-surfaces, and mobile-bar's selection cells.
  • With --repeat-each=5, all pass: the early-press tests in paint-format.spec.ts, the mobile-bar early-tap test, and the selection-bubble early-brush test.

Budgets

  • Eager editor chunk: +0 B. paint-pending stays in the bubble and phone-cell chunks; the gate reports a growth of +19.1 KB against a +23.5 KB budget.
  • Palette first Alt+/: 20,475 B, unchanged (PALETTE_BUDGET=1 on a production build).

Screenshots. The early-press screenshots (1440 bubble, 375 phone, light and dark) were re-shot and show no visual change; this fix only changes behaviour.

A "/" typed while an earlier fetch of the menu chunk was still failing
(the chunk runtime fetches a failed chunk once more, a moment later)
joined that fetch. When it failed, nothing loaded the chunk again while
the menu stayed open, so the menu never showed even once the chunk could
load. A failed load is now fetched once more straight away.
@HMarzban
HMarzban merged commit d84c3b4 into main Nov 15, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant