feat(web-core): implement keyboard event support (#2594)

## Summary

Implements keyboard event support (`keydown` / `keyup`) for the Lynx web
platform.

### What changed

**`packages/web-platform/web-core/src/constants.rs`**
Added `keydown` and `keyup` to `ELEMENT_REACTIVE_EVENTS` so per-element
event hooks are triggered when keyboard handlers are registered.

**`packages/web-platform/web-core/ts/types/EventType.ts`**
Extended `MinimalRawEventObject` with keyboard fields: `key`, `code`,
`keyCode`, `shiftKey`, `altKey`, `ctrlKey`, `metaKey`.


**`packages/web-platform/web-core/ts/client/mainthread/elementAPIs/createCrossThreadEvent.ts`**
Added a `keydown` / `keyup` branch that forwards all keyboard properties
into the cross-thread event object so they arrive in the React handler.


**`packages/web-platform/web-core/ts/client/mainthread/elementAPIs/WASMJSBinding.ts`**
— two fixes:

1. **Shadow DOM routing**: `rootDom` is a `ShadowRoot`. Keyboard events
fired on focused elements outside the shadow root never propagate into
it, so `rootDom.addEventListener('keydown', ...)` never fires. `keydown`
and `keyup` are now attached to `document` instead, with capture phase,
so they fire regardless of which element has focus.



https://github.com/lynx-family/lynx/blob/be387c0b9fa50af9424a353dfb77f575eac6c2be/core/renderer/dom/fragment/event/platform_event_handler.cc#L78
Is marked as todo

2. **Empty bubble path crash**: For `global-bindkeydown`, the DOM event
originates outside the Lynx element tree. The bubble path is empty, so
Rust passes `target_unique_id = 0`. `getElementByUniqueId(0)` returns
`undefined`, and `generateTargetObject(undefined, ...)` throws a
`TypeError` that is silently swallowed at the WASM boundary, dropping
the event. Fixed by falling back to `currentTarget` (the element that
registered the global handler) when `target` resolves to `undefined`.

**`packages/web-platform/web-core/tests/element-apis.spec.ts`**
Added unit tests for keyboard property forwarding in
`createCrossThreadEvent`.

**`examples/react/src/KeyboardDemo.tsx` + `keyboard.css`**
Visual QWERTY keyboard demo that highlights keys on press using
`global-bindkeydown` / `global-bindkeyup`. Green for regular keys, cyan
for modifiers.

### Scope — web platform only

This PR covers the web platform runtime. Keyboard events **do not work
on native iOS/Android** because the native Lynx runtime has no code path
to forward `UIKeyboardEvent` (iOS) or `KeyEvent` (Android) into the Lynx
JS layer.

Native support is being tracked upstream in `lynx-family/lynx`:
- [#6527 — Track CDP text input support in Lynx
DevTool](lynx-family/lynx#6527)
- [#6529 — Support Input.dispatchKeyEvent in Lynx DevTool
CDP](lynx-family/lynx#6529)

Once those land, the event pipeline added here should work end-to-end on
device without further changes to `lynx-stack`.

### How to test

```bash
# Build the web platform
cd packages/web-platform/web-core && npx tsc --build tsconfig.json
pnpm turbo build --filter=@lynx-js/web-rsbuild-server-middleware --force

# Run the dev server
cd examples/react && pnpm dev
```

Open `http://localhost:<port>/__web_preview?casename=main.web.bundle`
and press keys — the keyboard visualiser lights up.

## Checklist

- [x] Tests updated
- [ ] Documentation updated (not required — internal web platform
detail)
- [x] Changeset added



https://github.com/user-attachments/assets/a4fe1d52-aff9-4a20-ab4a-c6c4cecec7c0





<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Global keyboard event support (keydown, keyup) with key, code, keyCode
and modifier flags.

* **Bug Fixes**
* Document-level keyboard listeners now attach correctly and are
reliably removed during disposal to prevent stray events.

* **Tests**
* Unit and E2E tests added to verify keyboard event serialization,
forwarding, global vs non-global behavior, and modifier handling.

* **Documentation / Examples**
* Interactive keyboard demo app with styling and example project/config
added.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/lynx-family/lynx-stack/pull/2594)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Haoyang Wang <12288479+PupilTong@users.noreply.github.com>

Author: KealanAU

.changeset/feat-web-core-keyboard-events.md

@@ -0,0 +1,7 @@
+---
+"@lynx-js/web-core": minor
+---
+
+feat: support global keyboard events (keydown/keyup) on web
+
+Register `keydown`/`keyup` listeners on `document` instead of the ShadowRoot, which never receives keyboard events. Handle the case where `target_unique_id` is 0 (no element in the Lynx tree) by falling back to `currentTarget`, enabling `global-bindkeydown` and `global-bindkeyup` to work correctly in web previews.

examples/react-keyboard/lynx.config.js

@@ -0,0 +1,25 @@
+import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin';
+import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';
+import { defineConfig } from '@lynx-js/rspeedy';
+
+const enableBundleAnalysis = !!process.env['RSPEEDY_BUNDLE_ANALYSIS'];
+
+export default defineConfig({
+  plugins: [
+    pluginReactLynx(),
+    pluginQRCode({
+      schema(url) {
+        // We use `?fullscreen=true` to open the page in LynxExplorer in full screen mode
+        return `${url}?fullscreen=true`;
+      },
+    }),
+  ],
+  environments: {
+    web: {},
+    lynx: {
+      performance: {
+        profile: enableBundleAnalysis,
+      },
+    },
+  },
+});

examples/react-keyboard/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@lynx-js/example-react-keyboard",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "rspeedy build",
+    "dev": "rspeedy dev"
+  },
+  "dependencies": {
+    "@lynx-js/react": "workspace:*"
+  },
+  "devDependencies": {
+    "@lynx-js/preact-devtools": "^5.0.1",
+    "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
+    "@lynx-js/react-rsbuild-plugin": "workspace:*",
+    "@lynx-js/rspeedy": "workspace:*",
+    "@lynx-js/types": "3.7.0",
+    "@types/react": "^18.3.28"
+  }
+}

examples/react-keyboard/src/App.tsx

@@ -0,0 +1,5 @@
+import { KeyboardDemo } from './KeyboardDemo.js';
+
+export function App() {
+  return <KeyboardDemo />;
+}

examples/react-keyboard/src/KeyboardDemo.tsx

@@ -0,0 +1,229 @@
+import { useState } from '@lynx-js/react';
+import type { BaseKeyEvent } from '@lynx-js/types';
+
+import './keyboard.css';
+
+type LynxKeyEvent = BaseKeyEvent<unknown> & { code?: string };
+
+interface KeyDef {
+  code: string;
+  label: string;
+  flex: number;
+}
+
+const ROW1: KeyDef[] = [
+  { code: 'Backquote', label: '`', flex: 1 },
+  { code: 'Digit1', label: '1', flex: 1 },
+  { code: 'Digit2', label: '2', flex: 1 },
+  { code: 'Digit3', label: '3', flex: 1 },
+  { code: 'Digit4', label: '4', flex: 1 },
+  { code: 'Digit5', label: '5', flex: 1 },
+  { code: 'Digit6', label: '6', flex: 1 },
+  { code: 'Digit7', label: '7', flex: 1 },
+  { code: 'Digit8', label: '8', flex: 1 },
+  { code: 'Digit9', label: '9', flex: 1 },
+  { code: 'Digit0', label: '0', flex: 1 },
+  { code: 'Minus', label: '-', flex: 1 },
+  { code: 'Equal', label: '=', flex: 1 },
+  { code: 'Backspace', label: '⌫', flex: 2 },
+];
+
+const ROW2: KeyDef[] = [
+  { code: 'Tab', label: 'Tab', flex: 1.5 },
+  { code: 'KeyQ', label: 'Q', flex: 1 },
+  { code: 'KeyW', label: 'W', flex: 1 },
+  { code: 'KeyE', label: 'E', flex: 1 },
+  { code: 'KeyR', label: 'R', flex: 1 },
+  { code: 'KeyT', label: 'T', flex: 1 },
+  { code: 'KeyY', label: 'Y', flex: 1 },
+  { code: 'KeyU', label: 'U', flex: 1 },
+  { code: 'KeyI', label: 'I', flex: 1 },
+  { code: 'KeyO', label: 'O', flex: 1 },
+  { code: 'KeyP', label: 'P', flex: 1 },
+  { code: 'BracketLeft', label: '[', flex: 1 },
+  { code: 'BracketRight', label: ']', flex: 1 },
+  { code: 'Backslash', label: '\\', flex: 1.5 },
+];
+
+const ROW3: KeyDef[] = [
+  { code: 'CapsLock', label: 'Caps', flex: 1.75 },
+  { code: 'KeyA', label: 'A', flex: 1 },
+  { code: 'KeyS', label: 'S', flex: 1 },
+  { code: 'KeyD', label: 'D', flex: 1 },
+  { code: 'KeyF', label: 'F', flex: 1 },
+  { code: 'KeyG', label: 'G', flex: 1 },
+  { code: 'KeyH', label: 'H', flex: 1 },
+  { code: 'KeyJ', label: 'J', flex: 1 },
+  { code: 'KeyK', label: 'K', flex: 1 },
+  { code: 'KeyL', label: 'L', flex: 1 },
+  { code: 'Semicolon', label: ';', flex: 1 },
+  { code: 'Quote', label: '\'', flex: 1 },
+  { code: 'Enter', label: '↵ Enter', flex: 2.25 },
+];
+
+const ROW4: KeyDef[] = [
+  { code: 'ShiftLeft', label: '⇧ Shift', flex: 2.25 },
+  { code: 'KeyZ', label: 'Z', flex: 1 },
+  { code: 'KeyX', label: 'X', flex: 1 },
+  { code: 'KeyC', label: 'C', flex: 1 },
+  { code: 'KeyV', label: 'V', flex: 1 },
+  { code: 'KeyB', label: 'B', flex: 1 },
+  { code: 'KeyN', label: 'N', flex: 1 },
+  { code: 'KeyM', label: 'M', flex: 1 },
+  { code: 'Comma', label: ',', flex: 1 },
+  { code: 'Period', label: '.', flex: 1 },
+  { code: 'Slash', label: '/', flex: 1 },
+  { code: 'ShiftRight', label: 'Shift ⇧', flex: 2.75 },
+];
+
+const ROW5: KeyDef[] = [
+  { code: 'ControlLeft', label: 'Ctrl', flex: 1.5 },
+  { code: 'MetaLeft', label: '⌘', flex: 1.25 },
+  { code: 'AltLeft', label: 'Alt', flex: 1.25 },
+  { code: 'Space', label: '', flex: 6 },
+  { code: 'AltRight', label: 'Alt', flex: 1.25 },
+  { code: 'MetaRight', label: '⌘', flex: 1.25 },
+  { code: 'ControlRight', label: 'Ctrl', flex: 1.5 },
+];
+
+const ROWS = [ROW1, ROW2, ROW3, ROW4, ROW5];
+
+const MODIFIER_CODES = new Set([
+  'ShiftLeft',
+  'ShiftRight',
+  'ControlLeft',
+  'ControlRight',
+  'AltLeft',
+  'AltRight',
+  'MetaLeft',
+  'MetaRight',
+  'CapsLock',
+]);
+
+const REGULAR_COLOR = '#2a2a2a';
+const LIT_COLOR = '#39ff14';
+const MOD_COLOR = '#00d4ff';
+
+export function KeyboardDemo() {
+  const [pressed, setPressed] = useState<ReadonlySet<string>>(new Set());
+  const [lastKey, setLastKey] = useState('—');
+
+  const handleKeyDown = (e: LynxKeyEvent) => {
+    'background-only';
+    const code = e.code ?? '';
+    setLastKey(e.key);
+    setPressed(prev => new Set([...prev, code]));
+  };
+
+  const handleKeyUp = (e: LynxKeyEvent) => {
+    'background-only';
+    const code = e.code ?? '';
+    setPressed(prev => {
+      const next = new Set(prev);
+      next.delete(code);
+      return next;
+    });
+  };
+
+  return (
+    <view
+      className='kb-root'
+      {...{
+        'global-bindkeydown': handleKeyDown,
+        'global-bindkeyup': handleKeyUp,
+      }}
+    >
+      {/* Header */}
+      <view className='kb-header'>
+        <text style={{ color: '#fff', fontSize: '22px', fontWeight: 'bold' }}>
+          KEYBOARD EVENTS
+        </text>
+        <text style={{ color: '#555', fontSize: '13px' }}>
+          Click here, then press keys
+        </text>
+      </view>
+
+      {/* Last key */}
+      <view className='kb-last-key-row'>
+        <text style={{ color: '#555', fontSize: '13px', flex: 1 }}>
+          Last key
+        </text>
+        <text
+          style={{
+            color: pressed.size > 0 ? LIT_COLOR : '#444',
+            fontSize: '26px',
+            fontWeight: 'bold',
+          }}
+        >
+          {lastKey}
+        </text>
+      </view>
+
+      {/* Keyboard */}
+      <view className='kb-board'>
+        {ROWS.map((row, rowIdx) => (
+          <view key={rowIdx} className='kb-row'>
+            {row.map((key) => {
+              const isPressed = pressed.has(key.code);
+              const isMod = MODIFIER_CODES.has(key.code);
+              const bg = isPressed
+                ? (isMod ? MOD_COLOR : LIT_COLOR)
+                : REGULAR_COLOR;
+              const labelColor = isPressed ? '#000' : '#bbb';
+              const isSpace = key.code === 'Space';
+
+              return (
+                <view
+                  key={key.code}
+                  className={isSpace ? 'kb-key kb-space' : 'kb-key'}
+                  style={{ flex: key.flex, backgroundColor: bg }}
+                >
+                  {!isSpace && (
+                    <text
+                      style={{
+                        color: labelColor,
+                        fontSize: key.label.length > 3 ? '9px' : '12px',
+                        fontWeight: isPressed ? 'bold' : 'normal',
+                        textAlign: 'center',
+                      }}
+                    >
+                      {key.label}
+                    </text>
+                  )}
+                </view>
+              );
+            })}
+          </view>
+        ))}
+      </view>
+
+      {/* Legend */}
+      <view className='kb-legend'>
+        <view className='kb-legend-item'>
+          <view
+            style={{
+              width: '12px',
+              height: '12px',
+              backgroundColor: LIT_COLOR,
+              borderRadius: '3px',
+              marginRight: '6px',
+            }}
+          />
+          <text style={{ color: '#555', fontSize: '11px' }}>Key</text>
+        </view>
+        <view className='kb-legend-item'>
+          <view
+            style={{
+              width: '12px',
+              height: '12px',
+              backgroundColor: MOD_COLOR,
+              borderRadius: '3px',
+              marginRight: '6px',
+            }}
+          />
+          <text style={{ color: '#555', fontSize: '11px' }}>Modifier</text>
+        </view>
+      </view>
+    </view>
+  );
+}

examples/react-keyboard/src/index.tsx

@@ -0,0 +1,13 @@
+import '@lynx-js/preact-devtools';
+import '@lynx-js/react/debug';
+import { root } from '@lynx-js/react';
+
+import { App } from './App.jsx';
+
+root.render(
+  <App />,
+);
+
+if (import.meta.webpackHot) {
+  import.meta.webpackHot.accept();
+}

examples/react-keyboard/src/keyboard.css

@@ -0,0 +1,75 @@
+.kb-root {
+  width: 100%;
+  min-height: 100vh;
+  background-color: #111;
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  padding: 20px;
+}
+
+.kb-header {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 20px 0 12px;
+}
+
+.kb-last-key-row {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  background-color: #1a1a1a;
+  border-radius: 12px;
+  padding: 14px 16px;
+  margin-bottom: 16px;
+}
+
+.kb-board {
+  background-color: #1a1a1a;
+  border-radius: 16px;
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+}
+
+.kb-row {
+  display: flex;
+  flex-direction: row;
+  margin-bottom: 6px;
+}
+
+.kb-row:last-child {
+  margin-bottom: 0;
+}
+
+.kb-key {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 6px;
+  height: 38px;
+  margin-left: 4px;
+}
+
+.kb-key:first-child {
+  margin-left: 0;
+}
+
+.kb-space {
+  height: 40px;
+}
+
+.kb-legend {
+  display: flex;
+  flex-direction: row;
+  justify-content: center;
+  padding: 14px 0;
+}
+
+.kb-legend-item {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  margin: 0 12px;
+}

examples/react-keyboard/src/rspeedy-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="@lynx-js/rspeedy/client" />