Repository navigation
Direct delivery with safe shortcut boundaries and hidden-completion guards - #32
Conversation
Rich web editors (Gmail compose and similar) re-render the DOM during IME
composition and turn every composing preedit state into permanent text,
including the grey ghost suffix, which duplicated fragments of the word.
Chrome and Electron reach IBus through GTK im-ibus without the
SURROUNDING_TEXT capability, so delivered text cannot be verified there,
and a forwarded BackSpace is queued while commit_text applies at once, so
"delete N, then insert" can run out of order.
For clients without SURROUNDING_TEXT ("delivery": {"mode": "auto"}, the
default) the adapter now never shows a preedit and never revises: nothing
is delivered while the dual buffer is in its hypothesis phase; once the
language locks the word is committed in its final script and later keys
only append. The only deletion is one character for the operator's own
consumed BackSpace; any other revision is refused, the core's word ends,
the delivered text stays, and a refused key that emitted nothing is
handled by the client natively (a BackSpace deletes one character, a
letter is typed as the layout gives it). No action of a batch runs after
a refusal. Keys the client handles itself (navigation, shortcuts, Tab,
Right, Escape) first receive the undelivered word, then the word ends.
Undisplayed ghost completions are never typed. A delivery-mode change
takes down a live preedit and ends the word; focus-out delivers nothing
more (ibus-daemon has already moved its focus). A content-type switch
forgets the word; Tab in a sensitive field replays nothing; the
Super+Escape kill switch still reaches the core; the language-choice popup
and external rewrites are disabled in this mode. Clients with surrounding
text (Qt, ordinary GTK widgets) keep the composing preedit. "mode": "off"
restores the old behaviour everywhere; "direct" forces the new one.
Tests: 35 adapter tests (caret-aware editor model, including the audit
repros); full ibus suite green. Verified in an isolated X server with
Chrome and an isolated ibus-daemon: textarea, contenteditable,
value-rewriting and re-rendering editors all end with the exact expected
text for mixed English/Bulgarian input.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
handoff_preedit_for_delivery() commits the composing word and keeps it open with its script fixed at the dual buffer's current winner: later keys append in that script, a BackSpace is forwarded and the boundary types nothing again. It is the native-completion handoff without client ownership, so a focus-in keeps the word. Direct delivery (clients without surrounding text) uses it when the operator pauses or presses a shortcut modifier. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
In direct delivery a word stays invisible while the core's dual buffer is
in its hypothesis phase, which never ends before four letters. A mouse
click (Chrome sends Reset) or a window switch (focus-out) carries no
keystroke and discarded that word, so a short last word vanished when a
send button was clicked right after it.
After 800 ms without a key event, or on a Control, Alt, Super, Meta or
Hyper press, the core now takes the word over
(handoff_preedit_for_delivery): it is typed as typed so far and stays open
with its script fixed, so a later contrary hypothesis cannot leave a
mixed-script word behind (homoglyphs included). Without that core API
nothing is typed early. Reset and focus-out still drop an undelivered
word, because a flush there could land at a moved caret or in the next
window. The timers run below D-Bus dispatch priority, so a queued reset,
focus-out or focus-in always runs first.
Chrome answers a re-rendering editor's DOM change after a commit with
FocusOut and an immediate FocusIn on the same field, and may create a new
input context that announces SURROUNDING_TEXT for a moment. Either ended
the word and let its rest be decided again as a new word. A focus-out
within 50 ms of a commit made for a key or after a pause now waits that
long for the focus-in, and a switch from direct to preedit while a word is
in flight waits that long (or until the next key) for the capabilities to
come back. A modifier's commit never counts, so Alt+Tab cannot carry a
word into another window; the switch to direct is never held.
A consumed key other than the operator's BackSpace (the Super+Escape kill
switch) now only ends a delivered word instead of counting as a refused
revision that let the chord through to the client.
A content-free trace counts early deliveries (pause or modifier) and
undelivered words dropped by reset, focus-out, disable, a mode switch or a
secret field. smartkey.json "delivery": {"idle_ms": N} sets the pause:
0 disables it, other values are kept within 200-5000.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 59566a032f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| and not getattr(self, "_direct_key_inert", False) | ||
| and not {"commit", "replace"} & set(types) | ||
| and (getattr(self, "_direct_pending", "") or getattr(self, "_direct_word", "")) |
There was a problem hiding this comment.
Retire handed-off words before forwarding editing shortcuts
After an idle or modifier handoff, _direct_commit() clears both _direct_pending and _direct_word, although the core deliberately retains the open word and its fixed layout. Consequently, this condition skips _direct_end_word() for a subsequent Ctrl+A, Ctrl+BackSpace, or paste shortcut. The core's Ctrl/Alt shortcut path only returns ForwardKey, so typing after the client replaces or deletes the text continues the stale token in its previous script and eventually learns a concatenated word that was never present in the editor. Track the still-open handed-off token when retiring state for editing shortcuts, rather than relying solely on these cleared adapter buffers.
Useful? React with 👍 / 👎.
| typed, ghost = decoded | ||
| self._direct_pending = typed | ||
| self._direct_ghost = ghost | ||
| if getattr(self, "_direct_word", "") or self._direct_decided(): | ||
| refused = not self._direct_apply(typed) |
There was a problem hiding this comment.
Disable core Space acceptance when hiding direct-mode ghosts
With space_accept enabled, suppressing the composing display here does not stop MasterLoop::note_shown_ghost() from recording the returned ghost as displayed. A subsequent Space therefore passes the core's display attestation and accepts and learns the full prediction. _direct_commit() then strips the unseen suffix from the client output, but the core has already updated its context, acceptance metrics, and learning for a different word. Disable Space acceptance or its display attestation in direct mode so an undisplayed completion cannot corrupt learning even when its text is filtered out.
Useful? React with 👍 / 👎.
| if direct and keyval in _DIRECT_DELIVER_MODIFIERS and not state & _MOD_RELEASE: | ||
| # A shortcut or a window switch follows: type the undelivered word | ||
| # first and keep it open; the modifier itself changes nothing else. | ||
| self._direct_deliver_early("modifier") |
There was a problem hiding this comment.
Invalidate the refocus grace period on window-switch modifiers
If Alt+Tab follows a locked-word commit within 50 ms, the Alt press leaves _direct_commit_at pointing to that ordinary commit: _direct_deliver_early() does nothing because the word is already delivered. _direct_refocus_hold() consequently treats the real window switch as an editor refocus, and an immediate FocusIn in the destination window cancels the reset while retaining the previous window's word. Subsequent typing there continues the old script/token instead of starting a new word. Invalidate the prior commit's refocus eligibility when a window-switch modifier is pressed; merely excluding modifier-triggered commits from timestamp updates does not prevent this case.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
🟡 Changes recommended
An unresolved finding remains—the _CAP_PREEDIT_TEXT constant is dead code that is defined but never referenced, with the PREEDIT bit still checked via a magic literal.
1 open issue
What changed in this PR
This PR adds a direct delivery path to the IBus adapter for clients that reach IBus through GTK im-ibus without the SURROUNDING_TEXT capability (Chrome/Electron, e.g. the Gmail compose box). Because such rich web editors re-render their DOM during IME composition and turn every preedit state (ghost suffix included) into permanent text, the adapter stops showing a composing preedit for these clients and instead decides, delivers, and never revises: nothing is emitted while the dual buffer is in its hypothesis phase, and once the language locks the word is committed in its final script with later keys only appending. It also adds early delivery: after an ~800 ms pause (or on a Control/Alt/Super/Meta/Hyper press), the core hands the in-flight word over (handoff_preedit_for_delivery), typing it as-typed with its script fixed so an unstable hypothesis can never leave a mixed-script word.
Changes:
- New
_execute_actions_directstate machine in the IBus adapter plus timer logic for the idle pause, Chrome refocus (FocusOut/FocusIn), and capability-flicker mode-switch holds;do_process_key_eventnow wraps_process_key_event_implwith direct-delivery guards. - New core API
handoff_preedit_for_delivery(input.rs) exposed throughmaster_loop.rsand thesmartkey-pybinding, keeping the word owned by the core in a fixed script. - Configurable via
smartkey.json"delivery": {"mode": "auto"|"off"|"direct", "idle_ms": N}with clamping to 200–5000 ms (0 disables), and extensive new tests.
| File | Description |
|---|---|
ibus/smartkey_engine.py |
Core of the feature: direct-delivery execution, idle/refocus/mode-switch timers, capability-driven mode selection, config parsing, key-event wrapper. |
ibus/test_direct_delivery.py |
New 1084-line test suite covering delivery, revision refusal, pause/modifier early delivery, refocus, mode flicker, sensitive fields, and config clamping. |
crates/smartkey-core/src/input.rs |
New handoff_preedit_for_delivery that delivers the composing word and keeps it open in a fixed script, with 3 new tests. |
crates/smartkey-core/src/master_loop.rs |
MasterLoop wrapper invalidating language choice and clearing the last shown ghost before the core handoff. |
crates/smartkey-py/src/lib.rs |
PyO3 binding exposing handoff_preedit_for_delivery to the Python adapter. |
I reviewed the state machine (timers are one-shot, cancelled in do_destroy/clear paths, and run on the single IBus main-loop thread, so no concurrency hazard), the do_process_key_event refactor (original behavior preserved in _process_key_event_impl; guards correctly wrap it), the config clamping (matches all parametrized test cases), the capability-flicker/refocus hold logic, and the Rust handoff and its wrappers. The implementation is coherent and exceptionally well-tested; I found no functional defects. One minor maintainability nit is noted inline (an unused _CAP_PREEDIT_TEXT constant while the PREEDIT bit is still checked via a magic self._caps & 1).
Review effort: Balanced
| _MOD_RELEASE = 1 << 30 # IBus.ModifierType.RELEASE_MASK | ||
|
|
||
| _MOD_SUPER = (1 << 6) | (1 << 26) # MOD4_MASK | SUPER_MASK | ||
| _CAP_PREEDIT_TEXT = 0x01 |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b0f9ead0a1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| self._core.set_external_rewrite_supported( | ||
| bool(getattr(self, "_caps", 0) & _CAP_SURROUNDING_TEXT) and not self._direct_delivery | ||
| ) |
There was a problem hiding this comment.
Suppress composing-only corrections in direct mode
With post_commit_autocorrect enabled, disabling external rewrites here does not prevent corrections: the Space/Return and punctuation paths in InputMethodCore::handle_key() still allow them whenever dual_buffer.is_some(). commit_boundary_word() can therefore learn the corrected word and update lexical context before returning a commit followed by replacements. The direct adapter delivers the original commit, clears its word buffers in _direct_commit(), and skips those replacements as unverifiable, leaving the client text different from the learned word. Disable these corrections in the core for direct delivery, rather than relying solely on the external-rewrite capability.
Useful? React with 👍 / 👎.
| and keyval == IBus.KEY_BackSpace | ||
| and not state & (_MOD_CONTROL | _MOD_ALT | _MOD_SUPER) | ||
| ) | ||
| self._direct_key_inert = keycode in _NO_DELIVERY_KEYCODES |
There was a problem hiding this comment.
Classify zero-keycode events by their key symbol
For clients using the supported keyval fallback (keycode == 0), this marks every event as inert, including real navigation keys. For example, KP_Left (0xFF96) becomes Key::Other in keyval_to_key() and returns ForwardKey; _execute_actions_direct() then skips its deliver-and-retire guard because _direct_key_inert is true. With an undelivered word pending, the client moves its caret while the adapter retains the old word, so subsequent typing can deliver that word at the new position. Classify zero-keycode events using their keyval instead of exempting all of them from boundary handling.
Useful? React with 👍 / 👎.

Rich editors can turn IME composing preedit, including a completion suffix, into permanent duplicated text. For clients without surrounding-text support, this change delivers typed text directly once its layout is selected and never sends composing preedit or an unseen completion.
Direct mode now also disables completion-display attribution in the core, so Space cannot accept or learn a suffix the editor never displayed. Actual editing shortcuts reaching IBus deliver the pending token once and retire it before forwarding the command. A bare modifier does not deliver or fix the token's script. Early-delivered tokens, when explicitly requested, do not train the profile or enter lexical context, and punctuation/digits/shortcuts retire them correctly.
Idle delivery is off by default (
delivery.idle_ms = 0). Explicit nonzero values remain available within 200–5000 ms; they can fix the script of an unfinished word too early. The same-prefix handoff now uses the normal word-boundary resolver. Refocus eligibility is invalidated on shortcut modifiers, and releases/phantom events no longer force a pending capability transition.Validation includes regression tests against the old candidate, actual Rust/PyO3 adapter tests checking both visible output and learned state, the full core/Python suites, and an isolated native Chrome/IBus run in plain and rerendering contenteditables. Independent core and adapter reviews cover the reported P2 scenarios and the additional modifier-tap and Super-shortcut findings. Final-source checks: 979 Rust core tests passed (one ignored); 299 audited-native Python tests and 891 remaining Python tests passed; Clippy and formatting passed. Native Chrome validation: all 23 scenarios passed on the final clean build of b0f9ead, with its exact native-module hash verified and all isolated test processes cleaned up.
Known limits:
Configuration:
delivery.modeacceptsauto,off, ordirect;offrestores composing preedit. Adapter startup requires the matching native completion-display API, so source and native module must be deployed together.