fix(terminal): address review of the iOS IME preview

- Observe keydown in the capture phase on terminal.element, an ancestor of
  the helper textarea, so the controller sees it before xterm's own capture
  listener finalizes the composition and emits the commit through onData.
  Finalize on exactly the keys CompositionHelper.keydown does (every keyCode
  except 20/229/16/17/18), ignoring isComposing and key as xterm does.
- Bound awaitingCommit with the same 2 s fallback as the committed phase, so
  a composition whose commit never reaches onData cannot turn the next
  unrelated keystroke or paste into an IME commit.
- pagehide resets the controller instead of destroying it, so a back-forward
  cache restore keeps the preview working.
- Give the preview an opaque background from the terminal theme.
- Route an IME commit through the ordinary printable/paste local echo branch
  and complete the commit afterwards; drop the send-on-throw fallback.
- Pin the event order with an xterm stand-in registered in the capture phase
  ahead of the controller, and against real xterm in a browser test.
- CLAUDE.md: note the IME commit routing and the z-index 6 preview layer.

test/mobile-ime-preview-structure.test.ts

@@ -72,6 +72,7 @@ function createPreviewHarness(
     createThrows?: boolean;
     omitGlobal?: boolean;
     themeForeground?: string;
+    themeBackground?: string;
     themeGetterThrows?: boolean;
   } = {}
 ) {
@@ -140,12 +141,17 @@ function createPreviewHarness(
   });
   windowStub.codemanCurrentXtermTheme = () => {
     if (options.themeGetterThrows) throw new Error('theme unavailable');
-    return { foreground: '#334455' };
+    return { foreground: '#334455', background: '#223344' };
   };
   const app: App = Object.assign(Object.create(mixin), {
     terminal: {
       textarea: {},
-      options: { theme: options.themeForeground ? { foreground: options.themeForeground } : undefined },
+      options: {
+        theme:
+          options.themeForeground || options.themeBackground
+            ? { foreground: options.themeForeground, background: options.themeBackground }
+            : undefined,
+      },
       element: { querySelector: (selector: string) => (selector === '.xterm-helpers' ? helpers : null) },
     },
     activeSessionId: 'session-a',
@@ -202,6 +208,9 @@ describe('mobile IME preview lifecycle', () => {
     app._initMobileImePreview();
     expect(mobileImePreview?.create).toHaveBeenCalledOnce();
     expect(mobileImePreview?.create.mock.calls[0][0].textarea).toBe(app.terminal.textarea);
+    // Keydown is observed on the terminal element (an ancestor of the
+    // textarea), so it runs before xterm's own capture listener finalizes.
+    expect(mobileImePreview?.create.mock.calls[0][0].keydownTarget).toBe(app.terminal.element);
     expect(helpers.children).toEqual([previewNodes[0]]);
     expect(previewNodes[0]).toMatchObject({ className: 'codeman-ime-preview', hidden: true });
     expect(previewNodes[0].attributes['aria-hidden']).toBe('true');
@@ -233,6 +242,21 @@ describe('mobile IME preview lifecycle', () => {
     expect(windowStub.removeEventListener).toHaveBeenCalledTimes(2);
   });
 
+  it('pagehide resets the controller instead of destroying it, so a bfcache restore keeps the preview', () => {
+    const { app, createdControllers, previewNodes, windowStub } = createPreviewHarness();
+    app._initMobileImePreview();
+    const pagehide = (windowStub.addEventListener as Fn).mock.calls.find((call) => call[0] === 'pagehide')?.[1];
+    expect(pagehide).toBeTypeOf('function');
+    pagehide();
+    expect(createdControllers[0].reset).toHaveBeenCalledOnce();
+    expect(createdControllers[0].destroy).not.toHaveBeenCalled();
+    expect(previewNodes[0].remove).not.toHaveBeenCalled();
+    expect(app._mobileImePreview).toBe(createdControllers[0]);
+    // A second hide after the page came back from the cache still works.
+    pagehide();
+    expect(createdControllers[0].reset).toHaveBeenCalledTimes(2);
+  });
+
   it('resets the controller exactly once when the active session changes', () => {
     const { app, createdControllers } = createPreviewHarness();
     app._initMobileImePreview();
@@ -256,9 +280,10 @@ describe('mobile IME preview lifecycle', () => {
     expect(helpers.classList.contains('codeman-ime-preview-owned')).toBe(false);
   });
 
-  it('uses the terminal foreground while mirroring native composition font metrics', () => {
+  it('uses the terminal foreground and opaque background while mirroring native composition font metrics', () => {
     const { app, compositionView, previewNodes, createdControllers } = createPreviewHarness({
       themeForeground: '#1f2328',
+      themeBackground: '#fafafa',
     });
     app._initMobileImePreview();
     createdControllers[0].callbacks.render({ text: '入力', phase: 'provisional' });
@@ -270,15 +295,24 @@ describe('mobile IME preview lifecycle', () => {
       lineHeight: compositionView.style.lineHeight,
       height: compositionView.style.height,
       color: '#1f2328',
+      backgroundColor: '#fafafa',
     });
   });
 
+  it('falls back to the current skin theme when the terminal options carry no theme', () => {
+    const { app, previewNodes, createdControllers } = createPreviewHarness();
+    app._initMobileImePreview();
+    createdControllers[0].callbacks.render({ text: '入力', phase: 'provisional' });
+    expect(previewNodes[0].style).toMatchObject({ color: '#334455', backgroundColor: '#223344' });
+  });
+
   it('keeps rendering with a safe foreground when the theme getter throws', () => {
     const { app, previewNodes, createdControllers } = createPreviewHarness({ themeGetterThrows: true });
     app._initMobileImePreview();
     expect(() => createdControllers[0].callbacks.render({ text: '安全', phase: 'provisional' })).not.toThrow();
     expect(previewNodes[0].textContent).toBe('安全');
     expect(previewNodes[0].style.color).toBe('#e0e0e0');
+    expect(previewNodes[0].style.backgroundColor).toBe('#0d0d0d');
   });
 
   it.each(['query', 'create', 'append', 'className', 'hidden'] as const)(
@@ -464,17 +498,34 @@ describe('mobile IME commit onData routing', () => {
   });
 
   it.each([
-    ['the overlay is missing', { overlayMissing: true }, '日本'],
     ['appendText throws', { appendThrows: true }, '失敗'],
     ['addChar throws', { addThrows: true }, '字'],
-  ])('sends the committed text exactly once when %s', (_label, extra, text) => {
+  ])('never sends a commit the overlay may already hold when %s', (_label, extra, text) => {
+    // One code path with typed text: no send-on-throw fallback, which would
+    // double-send if the overlay threw after appending.
     const { controller, sent, handle } = onDataApp({ localEcho: true, ...extra });
-    expect(() => handle(text)).not.toThrow();
-    expect(sent).toEqual([text]);
-    // Nothing else shows the text yet, so the preview keeps it.
+    expect(() => handle(text)).toThrow('overlay failed');
+    expect(sent).toEqual([]);
+    // Nothing shows the text, so the preview keeps it until its fallback.
     expect(controller.completeCommit).not.toHaveBeenCalled();
   });
 
+  it('keeps the preview when the overlay is missing, exactly like typed text', () => {
+    const { controller, sent, handle } = onDataApp({ localEcho: true, overlayMissing: true });
+    expect(() => handle('日本')).not.toThrow();
+    expect(sent).toEqual([]);
+    expect(controller.completeCommit).not.toHaveBeenCalled();
+  });
+
+  it('completes the commit only after the printable branch has put it in the overlay', () => {
+    const { controller, overlay, handle } = onDataApp({ localEcho: true });
+    controller.completeCommit.mockImplementation(() => {
+      expect(overlay.pendingText).toBe('界');
+    });
+    handle('界');
+    expect(controller.completeCommit).toHaveBeenCalledOnce();
+  });
+
   it('keeps an untagged paste on the existing local echo path', () => {
     const { controller, overlay, sent, handle } = onDataApp({ localEcho: true, tagged: false });
     handle('plain paste');

test/mobile-ime-preview.browser.test.ts

@@ -0,0 +1,128 @@
+/**
+ * The iOS IME preview controller against a REAL xterm 6 instance.
+ *
+ * The controller's logic is unit-tested in test/mobile-ime-preview.test.ts
+ * with a stand-in for xterm. What only real xterm proves is the event ORDER:
+ * `terminal.open()` registers xterm's keydown listener in the capture phase on
+ * the helper textarea, and CompositionHelper.keydown finalizes a composition
+ * there and emits the commit through onData synchronously. The controller must
+ * observe that keydown first (capture phase on `terminal.element`), and must
+ * finalize on exactly the keys xterm does.
+ *
+ * No server: a blank page loads the vendored xterm bundle and the controller.
+ * Browser-driven, so it is excluded from `npm run test:ci` like the other
+ * Playwright suites. Run locally:
+ *   npm run test:browser -- test/mobile-ime-preview.browser.test.ts
+ */
+
+import { resolve } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { chromium, type Browser, type Page } from 'playwright';
+
+const root = resolve(import.meta.dirname, '..');
+
+type Step =
+  | ['start']
+  | ['update', string]
+  | ['end', string]
+  | ['key', number, string, boolean]
+  | ['wait', number]
+  | ['consume', string];
+
+describe('mobile IME preview with real xterm', () => {
+  let browser: Browser;
+  let page: Page;
+
+  beforeAll(async () => {
+    browser = await chromium.launch({ headless: true });
+    page = await browser.newPage();
+    await page.setContent('<div id="t" style="width:600px;height:300px"></div>');
+    await page.addScriptTag({ path: resolve(root, 'node_modules/@xterm/xterm/lib/xterm.js') });
+    await page.addScriptTag({ path: resolve(root, 'src/web/public/mobile-ime-preview.js') });
+  }, 60000);
+
+  afterAll(async () => {
+    if (browser) await browser.close();
+  });
+
+  async function drive(steps: Step[]) {
+    return page.evaluate(async (steps: Step[]) => {
+      const w = window as any;
+      const host = document.getElementById('t') as HTMLElement;
+      host.innerHTML = '';
+      const term = new w.Terminal();
+      term.open(host);
+      const textarea = term.textarea as HTMLTextAreaElement;
+      const renders: Array<{ text: string; phase: string }> = [];
+      const onData: Array<{ data: string; consumed: boolean }> = [];
+      const controller = w.MobileImePreview.create({
+        textarea,
+        keydownTarget: term.element,
+        render: (r: { text: string; phase: string }) => renders.push(r),
+        clear: () => {},
+      });
+      term.onData((data: string) => onData.push({ data, consumed: controller.consumeTerminalData(data) }));
+      textarea.focus();
+      const tick = (ms: number) => new Promise((r) => setTimeout(r, ms));
+      for (const step of steps) {
+        if (step[0] === 'start') textarea.dispatchEvent(new CompositionEvent('compositionstart', { data: '' }));
+        if (step[0] === 'update') {
+          textarea.value = step[1];
+          textarea.dispatchEvent(new CompositionEvent('compositionupdate', { data: step[1] }));
+        }
+        if (step[0] === 'end') textarea.dispatchEvent(new CompositionEvent('compositionend', { data: step[1] }));
+        if (step[0] === 'key') {
+          const [, keyCode, key, isComposing] = step;
+          const event = new KeyboardEvent('keydown', { key, isComposing, bubbles: true, cancelable: true });
+          Object.defineProperty(event, 'keyCode', { get: () => keyCode });
+          textarea.dispatchEvent(event);
+        }
+        if (step[0] === 'wait') await tick(step[1]);
+        if (step[0] === 'consume') onData.push({ data: step[1], consumed: controller.consumeTerminalData(step[1]) });
+      }
+      await tick(20);
+      const { composing, awaitingCommit, committed, latest } = controller.state;
+      const result = { onData, state: { composing, awaitingCommit, committed, latest }, lastRender: renders.at(-1) };
+      controller.destroy();
+      term.dispose();
+      return result;
+    }, steps);
+  }
+
+  it('Enter mid-composition: xterm emits the commit and the controller takes it as committed', async () => {
+    // compositionupdate's textarea end offset is recorded by xterm on a 0 ms timer.
+    const result = await drive([['start'], ['update', '確定'], ['wait', 10], ['key', 13, 'Enter', false]]);
+    expect(result.onData).toEqual([
+      { data: '確定', consumed: true },
+      { data: '\r', consumed: false },
+    ]);
+    expect(result.state).toMatchObject({ awaitingCommit: false, committed: true, latest: '確定' });
+    expect(result.lastRender).toEqual({ text: '確定', phase: 'committed' });
+  });
+
+  it('keyCode 229 with isComposing false: xterm keeps composing, so the preview keeps following', async () => {
+    const result = await drive([
+      ['start'],
+      ['update', 'か'],
+      ['wait', 10],
+      ['key', 229, 'k', false],
+      ['update', 'かな'],
+    ]);
+    expect(result.onData).toEqual([]);
+    expect(result.state).toMatchObject({ composing: true, awaitingCommit: false, latest: 'かな' });
+    expect(result.lastRender).toEqual({ text: 'かな', phase: 'provisional' });
+  });
+
+  it('a deleted composition stops waiting after 2 s, so a later paste is not taken as its commit', async () => {
+    const result = await drive([
+      ['start'],
+      ['update', 'abc'],
+      ['update', ''],
+      ['end', ''],
+      ['wait', 2100],
+      ['consume', 'pasted'],
+    ]);
+    expect(result.onData).toEqual([{ data: 'pasted', consumed: false }]);
+    expect(result.state).toMatchObject({ awaitingCommit: false, committed: false });
+  });
+});

test/mobile-ime-preview.test.ts

@@ -1,15 +1,21 @@
 import { readFileSync } from 'node:fs';
 import vm from 'node:vm';
 
-import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 
 type Listener = (event: Record<string, unknown>) => void;
 type ListenerOptions = boolean | { capture?: boolean };
 type RegisteredListener = { listener: Listener; capture: boolean };
 
-class FakeTextarea {
-  value = 'unchanged';
-  private listeners = new Map<string, RegisteredListener[]>();
+/**
+ * A DOM node with just enough event dispatch to reproduce listener ORDER: an
+ * ancestor's capture listeners, then the target's capture listeners, then the
+ * target's bubble listeners (at-target capture-first, as in Chromium 89+ and
+ * WebKit), then the ancestor's bubble listeners.
+ */
+class FakeNode {
+  parent: FakeNode | null = null;
+  protected listeners = new Map<string, RegisteredListener[]>();
 
   addEventListener(type: string, listener: Listener, options?: ListenerOptions) {
     const listeners = this.listeners.get(type) ?? [];
@@ -26,31 +32,46 @@ class FakeTextarea {
     if (index >= 0) listeners.splice(index, 1);
   }
 
-  dispatch(type: string, event: Record<string, unknown> = {}) {
-    const listeners = [...(this.listeners.get(type) ?? [])];
-    for (const phase of [true, false]) {
-      for (const registered of listeners) {
-        if (registered.capture === phase) registered.listener({ type, ...event });
-      }
+  run(type: string, capture: boolean, event: Record<string, unknown>) {
+    for (const registered of [...(this.listeners.get(type) ?? [])]) {
+      if (registered.capture === capture) registered.listener(event);
     }
   }
 
+  dispatch(type: string, event: Record<string, unknown> = {}) {
+    const full = { type, target: this, ...event };
+    const ancestors: FakeNode[] = [];
+    for (let node = this.parent; node; node = node.parent) ancestors.unshift(node);
+    for (const ancestor of ancestors) ancestor.run(type, true, full);
+    this.run(type, true, full);
+    this.run(type, false, full);
+    for (const ancestor of [...ancestors].reverse()) ancestor.run(type, false, full);
+  }
+
   listenerCount() {
     return [...this.listeners.values()].reduce((total, listeners) => total + listeners.length, 0);
   }
 }
 
+class FakeTextarea extends FakeNode {
+  value = 'unchanged';
+}
+
 type Scheduled = { id: number; callback: () => void; delay?: number };
 
 function harness(
   overrides: Record<string, unknown> = {},
-  beforeCreate?: (textarea: FakeTextarea, getController: () => Record<string, unknown> | undefined) => void
+  beforeCreate?: (textarea: FakeTextarea, getController: () => Record<string, any> | undefined) => void
 ) {
   const source = readFileSync(new URL('../src/web/public/mobile-ime-preview.js', import.meta.url), 'utf8');
   const context = vm.createContext({ navigator: {} });
   vm.runInContext(source, context, { filename: 'mobile-ime-preview.js' });
   const api = vm.runInContext('MobileImePreview', context);
+  // The terminal element: an ancestor of the helper textarea, like xterm's
+  // `.xterm` root is of `.xterm-helper-textarea`.
+  const element = new FakeNode();
   const textarea = new FakeTextarea();
+  textarea.parent = element;
   const frames: Scheduled[] = [];
   const timers: Scheduled[] = [];
   let nextId = 1;
@@ -79,6 +100,7 @@ function harness(
   beforeCreate?.(textarea, () => controller);
   controller = api.create({
     textarea,
+    keydownTarget: element,
     render,
     clear,
     onCommit,
@@ -93,6 +115,7 @@ function harness(
 
   return {
     api,
+    element,
     textarea,
     frames,
     timers,
@@ -222,34 +245,177 @@ describe('MobileImePreview', () => {
     const h = harness();
     h.textarea.dispatch('compositionstart');
     h.textarea.dispatch('compositionupdate', { data: '確定' });
-    h.textarea.dispatch('keydown', { key: 'Enter', isComposing: false });
+    h.textarea.dispatch('keydown', { key: 'Enter', keyCode: 13, isComposing: false });
     expect(h.controller.consumeTerminalData('確定')).toBe(true);
     h.textarea.dispatch('compositionend', { data: 'stale' });
     expect(h.controller.consumeTerminalData('stale')).toBe(false);
   });
 
-  test('capture keydown finalization precedes an earlier xterm bubble onData listener', () => {
-    const consumed: boolean[] = [];
+  /**
+   * Stand-in for xterm 6.0: `terminal.open()` registers a CAPTURE keydown
+   * listener on the helper textarea (CoreBrowserTerminal.ts:379), and
+   * CompositionHelper.keydown (CompositionHelper.ts:94-108) finalizes the
+   * composition there, emitting the commit through onData synchronously, for
+   * every keyCode except 20/229 and 16/17/18. It is registered BEFORE the
+   * controller is created, exactly as terminal.open() precedes
+   * _initMobileImePreview().
+   */
+  function withXtermStandIn() {
+    const emitted: Array<{ data: string; consumed: boolean }> = [];
+    let composing = false;
+    let composition = '';
     const h = harness({}, (textarea, getController) => {
-      textarea.addEventListener('keydown', () => {
-        const controller = getController() as { consumeTerminalData(data: string): boolean };
-        consumed.push(controller.consumeTerminalData('確定'));
+      const emit = (data: string) => emitted.push({ data, consumed: getController()?.consumeTerminalData(data) });
+      textarea.addEventListener('compositionstart', () => {
+        composing = true;
+        composition = '';
       });
+      textarea.addEventListener('compositionupdate', (event) => {
+        composition = String(event.data ?? '');
+      });
+      textarea.addEventListener(
+        'keydown',
+        (event) => {
+          if (composing && ![20, 229, 16, 17, 18].includes(event.keyCode as number)) {
+            composing = false;
+            emit(composition);
+          }
+          if (event.keyCode === 13) emit('\r');
+        },
+        true
+      );
     });
+    return { ...h, emitted, isXtermComposing: () => composing };
+  }
+
+  test('Enter mid-composition hands the commit xterm emits in its capture keydown to the preview', () => {
+    const h = withXtermStandIn();
     h.textarea.dispatch('compositionstart');
     h.textarea.dispatch('compositionupdate', { data: '確定' });
-    h.textarea.dispatch('keydown', { key: 'Enter', isComposing: false });
+    h.flushFrame();
+    h.textarea.dispatch('keydown', { key: 'Enter', keyCode: 13, isComposing: false });
 
-    expect(consumed).toEqual([true]);
-    expect(h.controller.consumeTerminalData('確定')).toBe(false);
-    expect(h.onCommit).toHaveBeenCalledOnce();
+    expect(h.emitted).toEqual([
+      { data: '確定', consumed: true },
+      { data: '\r', consumed: false },
+    ]);
+    expect(h.onCommit).toHaveBeenCalledWith('確定');
+    expect(h.controller.state).toMatchObject({ composing: false, awaitingCommit: false, committed: true });
+    h.flushFrame();
+    expect(h.render).toHaveBeenLastCalledWith({ text: '確定', phase: 'committed' });
 
+    // The next unrelated keystroke is ordinary input, not an IME commit.
+    expect(h.controller.consumeTerminalData('x')).toBe(false);
+  });
+
+  test.each([
+    // keyCode 229 with isComposing:false and a real key identity: xterm keeps
+    // composing, so the controller must too.
+    ['the IME composition character', 'k', 229],
+    ['CapsLock', 'CapsLock', 20],
+    ['Shift', 'Shift', 16],
+    ['Control', 'Control', 17],
+    ['Alt', 'Alt', 18],
+  ])('a keydown for %s keeps tracking the composition xterm is still composing', (_label, key, keyCode) => {
+    const h = withXtermStandIn();
+    h.textarea.dispatch('compositionstart');
+    h.textarea.dispatch('compositionupdate', { data: 'か' });
+    h.textarea.dispatch('keydown', { key, keyCode, isComposing: false });
+    expect(h.isXtermComposing()).toBe(true);
+    expect(h.controller.state).toMatchObject({ composing: true, awaitingCommit: false });
+
+    // The preview follows the composition instead of freezing on the old value.
+    h.textarea.dispatch('compositionupdate', { data: 'かな' });
+    h.flushFrame();
+    expect(h.render).toHaveBeenLastCalledWith({ text: 'かな', phase: 'provisional' });
+    expect(h.emitted).toEqual([]);
+  });
+
+  test('ignores keydowns that did not target the helper textarea', () => {
+    const h = harness();
+    const sibling = new FakeNode();
+    sibling.parent = h.element;
+    h.textarea.dispatch('compositionstart');
+    h.textarea.dispatch('compositionupdate', { data: '漢字' });
+    sibling.dispatch('keydown', { key: 'Enter', keyCode: 13, isComposing: false });
+    expect(h.controller.state).toMatchObject({ composing: true, awaitingCommit: false });
+  });
+
+  test('destroy stops the controller observing keydown on the terminal element', () => {
+    const h = withXtermStandIn();
     h.controller.destroy();
     h.textarea.dispatch('compositionstart');
     h.textarea.dispatch('compositionupdate', { data: 'later' });
-    h.textarea.dispatch('keydown', { key: 'Enter', isComposing: false });
-    expect(consumed).toEqual([true, false]);
-    expect(h.onCommit).toHaveBeenCalledOnce();
+    h.textarea.dispatch('keydown', { key: 'Enter', keyCode: 13, isComposing: false });
+    expect(h.emitted).toEqual([
+      { data: 'later', consumed: false },
+      { data: '\r', consumed: false },
+    ]);
+    expect(h.onCommit).not.toHaveBeenCalled();
+    expect(h.element.listenerCount()).toBe(0);
+  });
+
+  describe('a commit that never reaches onData', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+
+    function realTimerHarness() {
+      return harness({
+        setTimer: (callback: () => void, delay: number) => setTimeout(callback, delay),
+        clearTimer: (id: ReturnType<typeof setTimeout>) => clearTimeout(id),
+      });
+    }
+
+    test.each([
+      ['compositionend', (h: ReturnType<typeof harness>) => h.textarea.dispatch('compositionend', { data: '' })],
+      [
+        'a finalizing keydown',
+        (h: ReturnType<typeof harness>) => h.textarea.dispatch('keydown', { key: 'Enter', keyCode: 13 }),
+      ],
+    ])('stops waiting after the same 2 s bound when finalized by %s', (_label, finalize) => {
+      const h = realTimerHarness();
+      h.textarea.dispatch('compositionstart');
+      h.textarea.dispatch('compositionupdate', { data: 'deleted' });
+      finalize(h);
+      h.clear.mockClear();
+      expect(h.controller.state).toMatchObject({ awaitingCommit: true, timerPending: true });
+
+      vi.advanceTimersByTime(1999);
+      expect(h.controller.state.awaitingCommit).toBe(true);
+      vi.advanceTimersByTime(1);
+      expect(h.controller.state).toMatchObject({ awaitingCommit: false, latest: '', timerPending: false });
+      expect(h.clear).toHaveBeenCalledOnce();
+
+      // The next unrelated keystroke or paste is not adopted as the IME commit.
+      expect(h.controller.consumeTerminalData('x')).toBe(false);
+      expect(h.controller.consumeTerminalData('pasted line')).toBe(false);
+      expect(h.onCommit).not.toHaveBeenCalled();
+    });
+
+    test('a commit that arrives in time replaces the wait bound with the committed one', () => {
+      const h = realTimerHarness();
+      h.textarea.dispatch('compositionstart');
+      h.textarea.dispatch('compositionend', { data: '日本' });
+      vi.advanceTimersByTime(1500);
+      expect(h.controller.consumeTerminalData('日本')).toBe(true);
+      // The wait bound would have fired at 2000 ms; the committed bound runs
+      // a full 2 s from the commit instead.
+      vi.advanceTimersByTime(1000);
+      expect(h.controller.state.committed).toBe(true);
+      vi.advanceTimersByTime(1000);
+      expect(h.controller.state.committed).toBe(false);
+    });
+
+    test('a new composition cancels the previous wait bound', () => {
+      const h = realTimerHarness();
+      h.textarea.dispatch('compositionstart');
+      h.textarea.dispatch('compositionend', { data: '' });
+      vi.advanceTimersByTime(1500);
+      h.textarea.dispatch('compositionstart');
+      h.textarea.dispatch('compositionupdate', { data: 'next' });
+      vi.advanceTimersByTime(1000);
+      expect(h.controller.state).toMatchObject({ composing: true, latest: 'next' });
+    });
   });
 
   test('generation fences stale frames and timers', () => {
@@ -332,6 +498,7 @@ describe('MobileImePreview', () => {
     destroy.textarea.dispatch('compositionend');
     expect(destroy.controller.consumeTerminalData('final')).toBe(true);
     expect(destroy.textarea.listenerCount()).toBe(0);
+    expect(destroy.element.listenerCount()).toBe(0);
     expect(destroy.frames).toHaveLength(0);
     expect(destroy.timers).toHaveLength(0);
     expect(destroy.controller.state.latest).toBe('');
@@ -353,6 +520,7 @@ describe('MobileImePreview', () => {
     clearController = clear.controller;
     expect(() => clear.textarea.dispatch('compositionstart')).not.toThrow();
     expect(clear.textarea.listenerCount()).toBe(0);
+    expect(clear.element.listenerCount()).toBe(0);
     expect(clear.frames).toHaveLength(0);
     expect(clear.timers).toHaveLength(0);
   });
@@ -453,10 +621,12 @@ describe('MobileImePreview', () => {
     const h = harness();
     h.textarea.dispatch('compositionstart');
     h.textarea.dispatch('compositionupdate', { data: 'pending' });
-    expect(h.textarea.listenerCount()).toBe(6);
+    expect(h.textarea.listenerCount()).toBe(5);
+    expect(h.element.listenerCount()).toBe(1);
     h.controller.destroy();
     h.controller.destroy();
     expect(h.textarea.listenerCount()).toBe(0);
+    expect(h.element.listenerCount()).toBe(0);
     expect(h.frames).toHaveLength(0);
     h.textarea.dispatch('compositionupdate', { data: 'ignored' });
     expect(h.scheduleFrame).toHaveBeenCalledOnce();