react-x11 2.16.0 → 2.17.0

package/src/win32/ime.js

@@ -0,0 +1,267 @@
+// The input method, as the tree sees it.
+//
+// The bridge answers the IMM32 messages and hands over four events
+// (windows/src/ime.cc); this turns them into the composition events the
+// renderer already has — `CompositionStart`, `CompositionUpdate`,
+// `CompositionEnd` — so that a `<textinput>` on Windows composes through
+// exactly the machinery a `<textinput>` on Wayland composes through, and an
+// application that handles one handles both.
+//
+// The order is the one `src/wayland/textinput.js` `_apply` fixes, because it
+// is the order the events are defined in rather than a detail of either
+// protocol: **the commit first, then the new preedit.** One
+// WM_IME_COMPOSITION can carry both, and together they mean "this text is
+// settled, and this is what is still being typed".
+//
+// The other half is telling the IME where to put its candidate list. The
+// preedit is drawn in the field (src/nodes/preedit.js), so the candidate list
+// is the only thing the IME still draws, and it has to sit at the caret
+// rather than in the corner of the screen. `sync()` is what keeps it there:
+// the frame loop calls it after each tick, when the layout the caret is read
+// off is the one just painted.
+import { runWithPriority, DiscreteEventPriority } from '../priority.js';
+
+const TRACE = process.env.REACT_X11_TRACE_IME === '1';
+
+/** How many code points `units` UTF-16 code units cover.
+ *
+ * The bridge counts in code units because that is what IMM32 hands it, and
+ * the tree counts in code points. JS strings are UTF-16, so slicing at the
+ * bridge's offset and counting the result is the whole conversion — and it is
+ * done here rather than there because here is where the string is. */
+function codePointsIn(text, units) {
+  if (!(units > 0)) return 0;
+  return Array.from(text.slice(0, units)).length;
+}
+
+export class Win32InputMethod {
+  constructor(app) {
+    this.app = app;
+    this._native = app._native;
+    /** The field the IME is enabled for: `{ wnd, node, rect }`, or null. */
+    this.active = null;
+    /** Whether the tree has heard a `CompositionStart` it is owed an end for. */
+    this.composing = false;
+  }
+
+  // --- what the tree says ---------------------------------------------------
+
+  /**
+   * The focused text control of a window, or null.
+   *
+   * The duck type is `defaultComposition` + `textCaretRect`, which is what
+   * `<textinput>` and `<textarea>` implement and what a registered element
+   * with a caret of its own would implement to be reached the same way —
+   * the same test `src/wayland/textinput.js` makes, deliberately.
+   *
+   * A `sensitive` field answers null: a password is not offered to an input
+   * method, whose word history is one more place it must not reach. Windows
+   * does the same for its own password boxes.
+   */
+  _focusedTextControl(wnd) {
+    const node = wnd._reactX11Node?.events?.focusManager?.focused ?? null;
+    if (!node || node.destroyed) return null;
+    if (node.root?.window !== wnd) return null;
+    if (typeof node.defaultComposition !== 'function') return null;
+    if (typeof node.textCaretRect !== 'function') return null;
+    if (node.composes === false) return null;
+    if (node.props?.sensitive) return null;
+    return node;
+  }
+
+  /**
+   * Where the caret is, in the window's client pixels — which is the space
+   * the tree is already in on this backend (a mouse event's `x` reaches the
+   * tree exactly as the bridge sent it), so there is no scale to divide out
+   * and no frame inset to add. A field whose text has no layout yet offers
+   * its content box, which at least puts the list under the field.
+   */
+  _caretRect(wnd, node) {
+    let rect = null;
+    try {
+      const chars = Array.from(node.value ?? '');
+      const caret = Number.isInteger(node._caret)
+        ? Math.max(0, Math.min(node._caret, chars.length))
+        : chars.length;
+      rect = node.textCaretRect(caret);
+    } catch {
+      rect = null;
+    }
+    if (!rect) {
+      const box = node.contentBox?.() ?? node.abs;
+      if (!box) return null;
+      rect = { x: box.x, y: box.y, width: 0, height: box.height };
+    }
+    return {
+      x: Math.round(rect.x),
+      y: Math.round(rect.y),
+      width: Math.max(1, Math.round(rect.width ?? 0)),
+      height: Math.max(1, Math.round(rect.height ?? 0)),
+    };
+  }
+
+  /**
+   * Bring the IME up to date about a window's focused field.
+   *
+   * Called at the end of every frame the window ran, which is cheap when
+   * nothing changed: one duck-type check and four comparisons. Nothing is
+   * sent to the UI thread unless the field or the caret actually moved.
+   */
+  sync(wnd) {
+    if (this._destroyed || !wnd || wnd._destroyed) return;
+    const node = this._focusedTextControl(wnd);
+    if (node !== this.active?.node) {
+      if (this.active) this._disable();
+      if (node) this._enable(wnd, node);
+      return;
+    }
+    if (node) this._place(wnd, node);
+  }
+
+  _enable(wnd, node) {
+    this.active = { wnd, node, rect: null };
+    this.composing = false;
+    this._native.imeEnable(wnd.id, true);
+    this._place(wnd, node);
+    if (TRACE) trace(`enable <${node.kind}>`);
+  }
+
+  /**
+   * Take the IME off this window, and end the composition the tree is owed.
+   *
+   * The field's own blur has already cleared the preedit it was drawing; what
+   * is owed is the `CompositionEnd` an application that saw the start is
+   * waiting for, with no data — which is how an abandoned composition has
+   * always ended.
+   */
+  _disable() {
+    const active = this.active;
+    this.active = null;
+    if (!active) return;
+    if (this.composing) {
+      this.composing = false;
+      const node = active.node;
+      const events = node.destroyed ? null : node.root?.events;
+      if (events) {
+        runWithPriority(DiscreteEventPriority, () =>
+          events._composition('End', node, '', null),
+        );
+      }
+    }
+    this._native.imeEnable(active.wnd.id, false);
+    if (TRACE) trace('disable');
+  }
+
+  /** Move the candidate list to the caret, if it is not already there. */
+  _place(wnd, node) {
+    const rect = this._caretRect(wnd, node);
+    const was = this.active?.rect;
+    if (!rect) return;
+    if (
+      was &&
+      was.x === rect.x &&
+      was.y === rect.y &&
+      was.width === rect.width &&
+      was.height === rect.height
+    ) {
+      return;
+    }
+    if (this.active) this.active.rect = rect;
+    this._native.imeCaret(wnd.id, rect.x, rect.y, rect.width, rect.height);
+  }
+
+  // --- what the input method says -------------------------------------------
+
+  /**
+   * One `ime-*` event from the bridge.
+   *
+   * Every one is dispatched at `DiscreteEventPriority`: a composition is a
+   * keystroke's worth of user intent and must not be batched behind a
+   * transition, exactly as the Wayland transport dispatches its own.
+   */
+  handle(event, wnd) {
+    const active = this.active;
+    if (!active || active.wnd !== wnd) return;
+    const node = active.node;
+    if (node.destroyed) return;
+    const events = node.root?.events;
+    if (!events) return;
+
+    // There is no key behind an input method's commit, which is what a
+    // handler reading `nativeEvent` needs to be told.
+    const native = { type: 'ime' };
+
+    switch (event.type) {
+      case 'ime-start':
+        // The renderer's `CompositionStart` is raised lazily, with the first
+        // text — the same as every other backend, so that a composition that
+        // begins and ends with nothing in it never reaches an application.
+        // This only clears a flag a previous session could have left.
+        if (TRACE) trace('start');
+        return;
+
+      case 'ime-commit': {
+        const text = event.text ?? '';
+        if (!text) return;
+        if (TRACE) trace(`commit ${JSON.stringify(text)}`);
+        runWithPriority(DiscreteEventPriority, () => {
+          if (!this.composing) events._composition('Start', node, '', native);
+          this.composing = false;
+          // `defaultComposition` inserts it the way a typed character is
+          // inserted — through `_insert`, with `maxLength`, `onChange` and
+          // the undo run all in play.
+          events._composition('End', node, text, native);
+        });
+        return;
+      }
+
+      case 'ime-preedit': {
+        const text = event.text ?? '';
+        if (TRACE)
+          trace(`preedit ${JSON.stringify(text)} ${event.a}..${event.b}`);
+        runWithPriority(DiscreteEventPriority, () => {
+          if (text) {
+            if (!this.composing) {
+              events._composition('Start', node, '', native);
+              this.composing = true;
+            }
+            // The clause the IME is converting, which is what it wants drawn
+            // as the selection inside the preedit.
+            const cursor = {
+              cursorBegin: codePointsIn(text, event.a),
+              cursorEnd: codePointsIn(text, event.b),
+            };
+            events._composition('Update', node, text, native, cursor);
+          } else if (this.composing) {
+            this.composing = false;
+            events._composition('End', node, '', native);
+          }
+        });
+        return;
+      }
+
+      case 'ime-end':
+        // Usually nothing to do: the commit or an emptied preedit has already
+        // ended it. An IME that cancels without either lands here.
+        if (!this.composing) return;
+        if (TRACE) trace('end');
+        runWithPriority(DiscreteEventPriority, () => {
+          this.composing = false;
+          events._composition('End', node, '', native);
+        });
+        return;
+
+      default:
+        return;
+    }
+  }
+
+  destroy() {
+    this._destroyed = true;
+    this.active = null;
+  }
+}
+
+function trace(line) {
+  process.stderr.write(`react-x11 win32: ime ${line}\n`);
+}

package/src/win32/keymap.js

@@ -0,0 +1,116 @@
+// Windows key events -> the renderer's keysym vocabulary (src/keysyms.js).
+//
+// The rule mirrors X's own, as the Cocoa map does: a Latin-1 keysym is its
+// code point, anything else printable is 0x01000000 + code point, and the
+// editing and navigation keys have fixed keysyms looked up here by virtual
+// key code.
+//
+// The bridge has already done the part only it can do — asking the active
+// layout what the key types, once with the modifiers that are down and once
+// with none (src/win32.cc, EmitKey). That gives the two character roles
+// events.js reads:
+//
+//   baseCodepoint (nothing held)      -> baseKeysym — what chords match
+//   codepoint     (Shift/AltGr held)  -> keysym / codepoint — what was typed
+//
+// A key that types nothing reports 0 for both, and the table below is what
+// gives it a keysym at all. Tab is the one to keep an eye on: it *does* type
+// a character on Windows (U+0009), and letting the character rule have it
+// would make the keysym 9 instead of XK_Tab — which is why the table wins.
+import { keysymOf, MOD } from '../keysyms.js';
+
+// Virtual key codes -> X keysyms, for keys whose character is a control code
+// or nothing at all.
+const VK_KEYSYMS = new Map([
+  [0x08, 0xff08], // Backspace
+  [0x09, 0xff09], // Tab
+  [0x0d, 0xff0d], // Return
+  [0x13, 0xff13], // Pause
+  [0x14, 0xffe5], // Caps Lock
+  [0x1b, 0xff1b], // Escape
+  [0x21, 0xff55], // Page Up
+  [0x22, 0xff56], // Page Down
+  [0x23, 0xff57], // End
+  [0x24, 0xff50], // Home
+  [0x25, 0xff51], // Left
+  [0x26, 0xff52], // Up
+  [0x27, 0xff53], // Right
+  [0x28, 0xff54], // Down
+  [0x2c, 0xfd1d], // Print Screen -> XK_3270_PrintScreen
+  [0x2d, 0xff63], // Insert
+  [0x2e, 0xffff], // Delete
+  [0x5b, 0xffeb], // Left Super
+  [0x5c, 0xffec], // Right Super
+  [0x5d, 0xff67], // Menu
+  [0x90, 0xff7f], // Num Lock
+  [0x91, 0xff14], // Scroll Lock
+  [0xa0, 0xffe1], // Left Shift
+  [0xa1, 0xffe2], // Right Shift
+  [0xa2, 0xffe3], // Left Control
+  [0xa3, 0xffe4], // Right Control
+  [0xa4, 0xffe9], // Left Alt
+  [0xa5, 0xffea], // Right Alt
+  // The keypad, which has keysyms of its own so that a caret can tell
+  // KP_Left from Left even when Num Lock is off.
+  [0x6a, 0xffaa], // KP_Multiply
+  [0x6b, 0xffab], // KP_Add
+  [0x6d, 0xffad], // KP_Subtract
+  [0x6e, 0xffae], // KP_Decimal
+  [0x6f, 0xffaf], // KP_Divide
+]);
+
+// F1..F24 are contiguous on both sides, so they are a range rather than 24
+// table entries.
+const VK_F1 = 0x70;
+const XK_F1 = 0xffbe;
+
+// The keypad digits, likewise: VK_NUMPAD0..9 -> XK_KP_0..9.
+const VK_NUMPAD0 = 0x60;
+const XK_KP_0 = 0xffb0;
+
+function fixedKeysym(vk) {
+  const known = VK_KEYSYMS.get(vk);
+  if (known) return known;
+  if (vk >= VK_F1 && vk <= VK_F1 + 23) return XK_F1 + (vk - VK_F1);
+  if (vk >= VK_NUMPAD0 && vk <= VK_NUMPAD0 + 9)
+    return XK_KP_0 + (vk - VK_NUMPAD0);
+  return 0;
+}
+
+const keysymFromCodepoint = (cp) =>
+  cp && cp >= 0x20 ? keysymOf(String.fromCodePoint(cp)) : 0;
+
+/**
+ * The three key facts events.js reads off a native key event, from the
+ * bridge's payload: `a` the virtual key, `b` what it typed, `c` what it
+ * would type with nothing held.
+ */
+export function decodeKey(event) {
+  const vk = event.a;
+  const fixed = fixedKeysym(vk);
+  if (fixed) {
+    // A key with a fixed keysym reports no code point even when Windows
+    // says it types one. Tab and Return type U+0009 and U+000D, and letting
+    // those through would insert a control character into every text field
+    // the moment a caret was in one.
+    return { keysym: fixed, baseKeysym: fixed, codepoint: undefined };
+  }
+  const keysym = keysymFromCodepoint(event.b);
+  const baseKeysym = keysymFromCodepoint(event.c) || keysym;
+  return {
+    keysym: keysym || baseKeysym,
+    baseKeysym,
+    codepoint: event.b ? event.b : undefined,
+  };
+}
+
+/** The bridge's modifier bits -> the X-style state mask events carry. */
+export function modifierMask(bits) {
+  let mask = 0;
+  if (bits & 1) mask |= MOD.Shift;
+  if (bits & 2) mask |= MOD.Control;
+  if (bits & 4) mask |= MOD.Alt;
+  if (bits & 8) mask |= MOD.Super;
+  if (bits & 16) mask |= MOD.Lock;
+  return mask;
+}

package/src/win32/native.js

@@ -0,0 +1,54 @@
+// The bridge to @windowkit/win32 — the Windows backend's native half.
+// Resolved lazily so that importing react-x11 anywhere else costs nothing;
+// `createRoot` only walks in here once the backend decision has landed on
+// 'win32'. That laziness is what lets the package be an *optional* dependency:
+// off Windows npm skips it (its `os` field is win32-only) and nothing here
+// ever asks for it.
+//
+// Resolution order: `REACT_X11_WIN32_PATH` (a checkout, for development), then
+// the installed `@windowkit/win32`. This mirrors src/cocoa/native.js down to
+// the loader, including why `createRequire` is made from `process.execPath`
+// when there is no module URL — a single-executable build (docs/packaging.md
+// tier 3) is CommonJS, and esbuild leaves `import.meta` an empty object there.
+import { createRequire } from 'node:module';
+
+const PACKAGE = '@windowkit/win32';
+
+let require = null;
+function load(spec) {
+  require ??= createRequire(import.meta.url ?? process.execPath);
+  return require(spec);
+}
+
+let cached = null;
+
+export function loadNative() {
+  if (cached) return cached;
+  if (process.platform !== 'win32') {
+    throw new Error(
+      "react-x11: the 'win32' backend is Windows-only. On this platform use " +
+        'the X11 backend (the default when DISPLAY is set), or pass ' +
+        "createRoot({ backend: 'x11' }).",
+    );
+  }
+  const tried = [];
+  const path = process.env.REACT_X11_WIN32_PATH;
+  for (const spec of [path, PACKAGE].filter(Boolean)) {
+    try {
+      const mod = load(spec);
+      cached = mod.native ?? mod;
+      return cached;
+    } catch (err) {
+      tried.push(`  ${spec}: ${err.message}`);
+    }
+  }
+  throw new Error(
+    `react-x11: the win32 backend needs the ${PACKAGE} native bridge and ` +
+      'none could be loaded:\n' +
+      tried.join('\n') +
+      `\nInstall it with \`npm install ${PACKAGE}\` (Windows; prebuilds ship ` +
+      'for x64 and ARM64, and building from source needs Visual Studio with ' +
+      'the "Desktop development with C++" workload). To use X11 instead, set ' +
+      "DISPLAY and pass createRoot({ backend: 'x11' }).",
+  );
+}

package/src/win32/panehost.js

@@ -0,0 +1,106 @@
+// The host's half of a Windows frame pane: one visual over the window's
+// content — the same stacking a `<glarea>` gets — whose content is the
+// buffer the pane process is drawing into. The pane owns its buffers and its
+// drawing; this side owns the visual, the layout and the input. CPU
+// offloading, not isolation (docs/frame.md).
+//
+// The seam is `setRect` / `present` / `destroy`, the same three methods the
+// Cocoa host implements, and the difference between the two backends lives
+// entirely inside `present`. There a Cocoa host is told a **different**
+// IOSurface every frame and points its layer at each one; here it is told
+// the **same** composition surface handle every time, because the pane's
+// swapchain flips inside that one handle. So this one attaches once and
+// recognises the handle ever after — after which the pane's frames arrive
+// with nothing at all crossing the process boundary.
+export class Win32PaneHost {
+  constructor(app, wnd) {
+    this.app = app;
+    this.wnd = wnd;
+    this._native = app._native;
+    this.destroyed = false;
+    /** The bridge's id for the attached visual; 0 until the first present,
+     *  because there is no buffer to attach before the pane names one. */
+    this._view = 0;
+    /** The handle that view was opened from, so the same one arriving again
+     *  is recognised rather than re-opened. */
+    this._handle = 0;
+    this._rect = null;
+  }
+
+  /**
+   * Where the pane goes, in the host window's device pixels — the node's
+   * `abs`. The size is a **clip**, not a scale: the pane draws at whatever
+   * size it was last told over the channel, and the two disagree for the
+   * length of a round trip whenever the box changes. Bounding it here is
+   * what keeps a pane that has not caught up from painting over its
+   * neighbours (`paneSetRect`, windows/src/pane.cc).
+   */
+  setRect(rect) {
+    if (this.destroyed || !rect) return;
+    const prev = this._rect;
+    if (
+      prev &&
+      prev.x === rect.x &&
+      prev.y === rect.y &&
+      prev.width === rect.width &&
+      prev.height === rect.height
+    ) {
+      return;
+    }
+    this._rect = { ...rect };
+    this._place();
+  }
+
+  _place() {
+    const rect = this._rect;
+    if (!this._view || !rect) return;
+    this._native.paneSetRect(
+      this._view,
+      Math.round(rect.x),
+      Math.round(rect.y),
+      Math.max(0, Math.round(rect.width)),
+      Math.max(0, Math.round(rect.height)),
+    );
+  }
+
+  /**
+   * The pane named the buffer its frames are in.
+   *
+   * On the first one this opens the handle and hangs it in the window's
+   * visual tree; on every one after it there is nothing to do, and saying so
+   * quickly is the point — the compositor is already scanning out of
+   * whatever the pane last presented, so a frame reaches the screen without
+   * this method being called at all.
+   *
+   * A *different* handle means a different pane behind the same host, which
+   * is what a restart looks like from here: drop the old view and open the
+   * new one, rather than leaving the window showing a buffer whose process
+   * has gone.
+   */
+  present(handle) {
+    if (this.destroyed || !handle) return;
+    if (handle === this._handle && this._view) return;
+    if (this._view) {
+      this._native.paneDetach(this._view);
+      this._view = 0;
+    }
+    const view = this._native.paneAttach(this.wnd.id, handle);
+    if (!view) {
+      // Nothing was shown and nothing was lost; the pane will say so again
+      // with its next pane-rect, and a host window not yet composed is the
+      // one way this happens.
+      return;
+    }
+    this._handle = handle;
+    this._view = view;
+    this._place();
+  }
+
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this._view) this._native.paneDetach(this._view);
+    this._view = 0;
+    this._handle = 0;
+  }
+}