From bc19bc2360a5556821fe59db0a3ae8ae7eeb4d38 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 6 Oct 2026 21:40:38 +0000
Subject: [PATCH 1/4] feat(ui): add text input fields backed by a hidden DOM
 input

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014VktGvQk7RUMN8yxuAUXER
---
 .cspell/project-words.txt                     |   3 +
 src/input/index.ts                            |   1 +
 .../keyboard-input-source.test.ts             |  82 +++
 .../input-sources/keyboard-input-source.ts    |  53 +-
 src/input/text-entry/index.ts                 |   1 +
 src/input/text-entry/text-entry.test.ts       | 193 ++++++
 src/input/text-entry/text-entry.ts            | 467 ++++++++++++++
 src/rendering/systems/render-system.test.ts   |   1 +
 src/text/components/text-mesh-component.ts    |   8 +
 src/text/rendering/glyph-quad.test.ts         |   2 +
 src/text/systems/text-shaping-system.test.ts  |   1 +
 src/text/systems/text-shaping-system.ts       |   3 +-
 src/text/utilities/shape-text.test.ts         |  78 +++
 src/text/utilities/shape-text.ts              | 175 ++++-
 src/ui/components/index.ts                    |   1 +
 .../components/text-input-component.test.ts   |  57 ++
 src/ui/components/text-input-component.ts     | 184 ++++++
 src/ui/systems/index.ts                       |   1 +
 src/ui/systems/ui-interaction-system.ts       |   2 +-
 src/ui/systems/ui-raycast-system.ts           | 172 +----
 src/ui/systems/ui-slider-system.ts            |   7 +-
 src/ui/systems/ui-text-input-system.test.ts   | 434 +++++++++++++
 src/ui/systems/ui-text-input-system.ts        | 609 ++++++++++++++++++
 src/ui/utilities/create-text-input.test.ts    | 116 ++++
 src/ui/utilities/create-text-input.ts         | 345 ++++++++++
 src/ui/utilities/index.ts                     |   2 +
 src/ui/utilities/raycast-ui-canvas.test.ts    |  84 +++
 src/ui/utilities/raycast-ui-canvas.ts         | 144 +++++
 src/ui/utilities/register-ui-systems.ts       |  15 +-
 .../resolve-canvas-pointer-position.test.ts   |  15 +-
 .../resolve-canvas-pointer-position.ts        |  12 +-
 31 files changed, 3045 insertions(+), 223 deletions(-)
 create mode 100644 src/input/text-entry/index.ts
 create mode 100644 src/input/text-entry/text-entry.test.ts
 create mode 100644 src/input/text-entry/text-entry.ts
 create mode 100644 src/ui/components/text-input-component.test.ts
 create mode 100644 src/ui/components/text-input-component.ts
 create mode 100644 src/ui/systems/ui-text-input-system.test.ts
 create mode 100644 src/ui/systems/ui-text-input-system.ts
 create mode 100644 src/ui/utilities/create-text-input.test.ts
 create mode 100644 src/ui/utilities/create-text-input.ts
 create mode 100644 src/ui/utilities/raycast-ui-canvas.test.ts
 create mode 100644 src/ui/utilities/raycast-ui-canvas.ts

diff --git a/.cspell/project-words.txt b/.cspell/project-words.txt
index dbd1070ae..a418833cf 100644
--- a/.cspell/project-words.txt
+++ b/.cspell/project-words.txt
@@ -48,6 +48,7 @@ devicerestored
 diegetic
 dppx
 eamodio
+enterkeyhint
 Erdokovy
 esbenp
 evented
@@ -83,6 +84,7 @@ implementability
 impluse
 Infima
 inigo
+inputmode
 interactable
 interactables
 isampler
@@ -100,6 +102,7 @@ letterboxed
 letterboxing
 lifecycles
 matterjs
+maxlength
 mediump
 Menlo
 mesher
diff --git a/src/input/index.ts b/src/input/index.ts
index 497d0ca76..c8b990076 100644
--- a/src/input/index.ts
+++ b/src/input/index.ts
@@ -11,3 +11,4 @@ export * from './mouse/index.js';
 export * from './keyboard/index.js';
 export * from './gamepad/index.js';
 export * from './register-inputs.js';
+export * from './text-entry/index.js';
diff --git a/src/input/keyboard/input-sources/keyboard-input-source.test.ts b/src/input/keyboard/input-sources/keyboard-input-source.test.ts
index 313c74b62..930053199 100644
--- a/src/input/keyboard/input-sources/keyboard-input-source.test.ts
+++ b/src/input/keyboard/input-sources/keyboard-input-source.test.ts
@@ -52,6 +52,7 @@ describe('KeyboardInputSource', () => {
   it('dispatches key up trigger actions', () => {
     expect(keyUpAction.isTriggered).toBe(false);
 
+    window.dispatchEvent(new KeyboardEvent('keydown', { code: keyCodes.a }));
     window.dispatchEvent(new KeyboardEvent('keyup', { code: keyCodes.a }));
     expect(keyUpAction.isTriggered).toBe(true);
 
@@ -304,6 +305,87 @@ describe('KeyboardInputSource', () => {
     expect(axis1dAction.value).toBe(0);
   });
 
+  describe('keys typed into editable elements', () => {
+    const dispatchKey = (
+      target: EventTarget,
+      type: 'keydown' | 'keyup',
+      code: string,
+    ): void => {
+      target.dispatchEvent(
+        new KeyboardEvent(type, { code, bubbles: true, composed: true }),
+      );
+    };
+
+    let input: HTMLInputElement;
+
+    beforeEach(() => {
+      input = document.createElement('input');
+      document.body.appendChild(input);
+    });
+
+    it('ignores a key pressed in an <input>, and its release', () => {
+      dispatchKey(input, 'keydown', keyCodes.s);
+      expect(keyDownAction.isTriggered).toBe(false);
+
+      dispatchKey(input, 'keydown', keyCodes.a);
+      dispatchKey(input, 'keyup', keyCodes.a);
+      expect(keyUpAction.isTriggered).toBe(false);
+
+      input.remove();
+    });
+
+    it('ignores keys pressed in a <textarea>, a <select> and a contentEditable element', () => {
+      const textarea = document.createElement('textarea');
+      const select = document.createElement('select');
+      const editable = document.createElement('div');
+
+      editable.contentEditable = 'true';
+      // jsdom doesn't implement isContentEditable.
+      Object.defineProperty(editable, 'isContentEditable', { value: true });
+
+      for (const element of [textarea, select, editable]) {
+        document.body.appendChild(element);
+        dispatchKey(element, 'keydown', keyCodes.s);
+        element.remove();
+      }
+
+      expect(keyDownAction.isTriggered).toBe(false);
+      input.remove();
+    });
+
+    it('ignores a key pressed in an <input> inside a shadow root', () => {
+      const host = document.createElement('div');
+      const shadowInput = document.createElement('input');
+
+      host.attachShadow({ mode: 'open' }).appendChild(shadowInput);
+      document.body.appendChild(host);
+
+      dispatchKey(shadowInput, 'keydown', keyCodes.s);
+      expect(keyDownAction.isTriggered).toBe(false);
+
+      host.remove();
+      input.remove();
+    });
+
+    it('still releases a key held before typing started', () => {
+      dispatchKey(window, 'keydown', keyCodes.space);
+      expect(keyHoldAction.isHeld).toBe(true);
+
+      dispatchKey(input, 'keyup', keyCodes.space);
+      expect(keyHoldAction.isHeld).toBe(false);
+
+      input.remove();
+    });
+
+    it('does not report a key released outside the input after being pressed in it', () => {
+      dispatchKey(input, 'keydown', keyCodes.a);
+      input.remove();
+      dispatchKey(window, 'keyup', keyCodes.a);
+
+      expect(keyUpAction.isTriggered).toBe(false);
+    });
+  });
+
   describe('switching the active input group', () => {
     const menuGroup = 'menu';
 
diff --git a/src/input/keyboard/input-sources/keyboard-input-source.ts b/src/input/keyboard/input-sources/keyboard-input-source.ts
index 99e2961c7..ac9535ad0 100644
--- a/src/input/keyboard/input-sources/keyboard-input-source.ts
+++ b/src/input/keyboard/input-sources/keyboard-input-source.ts
@@ -1,4 +1,4 @@
-import { Resettable, Stoppable } from '../../../common/index.js';
+import { Stoppable } from '../../../common/index.js';
 import { clamp } from '../../../math/index.js';
 import { Axis1dAction, Axis2dAction } from '../../actions/index.js';
 import { KeyboardHoldBinding } from '../bindings/keyboard-hold-binding.js';
@@ -16,6 +16,27 @@ import {
   TriggerInputSource,
 } from '../../input-sources/index.js';
 
+/**
+ * Whether `event` was typed into an editable element: an `<input>`,
+ * `<textarea>`, `<select>` or a `contentEditable` element. Reads the
+ * event's composed path rather than `target`, since at the window `target`
+ * is the shadow host for an element inside a shadow root.
+ */
+function isTypedIntoEditableElement(event: KeyboardEvent): boolean {
+  const [origin] = event.composedPath();
+
+  if (!(origin instanceof HTMLElement)) {
+    return false;
+  }
+
+  return (
+    origin instanceof HTMLInputElement ||
+    origin instanceof HTMLTextAreaElement ||
+    origin instanceof HTMLSelectElement ||
+    origin.isContentEditable
+  );
+}
+
 /** Represents a keyboard input source with associated bindings. */
 export class KeyboardInputSource
   implements
@@ -23,8 +44,7 @@ export class KeyboardInputSource
     HoldInputSource<KeyboardHoldBinding>,
     Axis2dInputSource<KeyboardAxis2dBinding>,
     Axis1dInputSource<KeyboardAxis1dBinding>,
-    Stoppable,
-    Resettable
+    Stoppable
 {
   /** The set of trigger bindings associated with this input source. */
   public readonly triggerBindings = new Set<KeyboardTriggerBinding>();
@@ -38,8 +58,13 @@ export class KeyboardInputSource
 
   private readonly _inputManager: InputManager;
 
-  private readonly _keyPressesDown = new Set<KeyCode>();
-  private readonly _keyPressesUps = new Set<KeyCode>();
+  /**
+   * The keys the game saw go down and hasn't seen released yet. A key typed
+   * into an editable element never enters this set, and a release of a key
+   * that isn't in it is ignored, so typing into an HTML text box (Forge's
+   * own text fields included) never reaches the game, while a key held
+   * before typing started is still released.
+   */
   private readonly _keyHolds = new Set<KeyCode>();
 
   /** Constructs a new KeyboardInputSource.
@@ -48,21 +73,13 @@ export class KeyboardInputSource
   constructor(inputManager: InputManager) {
     this._inputManager = inputManager;
 
-    this._inputManager.addResettable(this);
-
     globalThis.addEventListener('keydown', this._onKeyDownHandler);
     globalThis.addEventListener('keyup', this._onKeyUpHandler);
   }
 
-  public reset(): void {
-    this._keyPressesDown.clear();
-    this._keyPressesUps.clear();
-  }
-
   public stop(): void {
     globalThis.removeEventListener('keydown', this._onKeyDownHandler);
     globalThis.removeEventListener('keyup', this._onKeyUpHandler);
-    this._inputManager.removeResettable(this);
   }
 
   private readonly _onKeyDownHandler = (event: KeyboardEvent) => {
@@ -71,9 +88,12 @@ export class KeyboardInputSource
       return;
     }
 
+    if (isTypedIntoEditableElement(event)) {
+      return;
+    }
+
     const keyCode = event.code as KeyCode;
 
-    this._keyPressesDown.add(keyCode);
     this._keyHolds.add(keyCode);
 
     this._handleTriggerBindingsOnKeyDown(keyCode);
@@ -109,7 +129,10 @@ export class KeyboardInputSource
 
     const keyCode = event.code as KeyCode;
 
-    this._keyPressesUps.add(keyCode);
+    if (!this._keyHolds.has(keyCode)) {
+      return;
+    }
+
     this._keyHolds.delete(keyCode);
 
     this._handleTriggerBindingsOnKeyUp(keyCode);
diff --git a/src/input/text-entry/index.ts b/src/input/text-entry/index.ts
new file mode 100644
index 000000000..51111e49c
--- /dev/null
+++ b/src/input/text-entry/index.ts
@@ -0,0 +1 @@
+export * from './text-entry.js';
diff --git a/src/input/text-entry/text-entry.test.ts b/src/input/text-entry/text-entry.test.ts
new file mode 100644
index 000000000..be61fc0fe
--- /dev/null
+++ b/src/input/text-entry/text-entry.test.ts
@@ -0,0 +1,193 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createTextEntry, TextEntry } from './text-entry';
+
+describe('createTextEntry', () => {
+  let container: HTMLDivElement;
+  let entry: TextEntry;
+
+  const keyDown = (
+    code: string,
+    init: KeyboardEventInit = {},
+  ): KeyboardEvent => {
+    const event = new KeyboardEvent('keydown', {
+      code,
+      key: code,
+      bubbles: true,
+      cancelable: true,
+      ...init,
+    });
+
+    entry.element.dispatchEvent(event);
+
+    return event;
+  };
+
+  const type = (value: string): void => {
+    entry.element.value = value;
+    entry.element.dispatchEvent(new Event('input', { bubbles: true }));
+  };
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    entry = createTextEntry(container);
+  });
+
+  afterEach(() => {
+    entry.dispose();
+    container.remove();
+  });
+
+  it('appends a hidden input to the container and makes the container a positioning context', () => {
+    expect(entry.element.parentElement).toBe(container);
+    expect(entry.element.style.position).toBe('absolute');
+    expect(entry.element.style.pointerEvents).toBe('none');
+    expect(container.style.position).toBe('relative');
+  });
+
+  it('leaves an already positioned container alone', () => {
+    const positioned = document.createElement('div');
+
+    positioned.style.position = 'absolute';
+
+    const other = createTextEntry(positioned);
+
+    expect(positioned.style.position).toBe('absolute');
+    other.dispose();
+  });
+
+  it('places the element over a screen rect', () => {
+    entry.setScreenRect({ left: 10, top: 20, width: 200, height: 40 });
+
+    expect(entry.element.style.left).toBe('10px');
+    expect(entry.element.style.top).toBe('20px');
+    expect(entry.element.style.width).toBe('200px');
+    expect(entry.element.style.height).toBe('40px');
+  });
+
+  it('sets and removes attributes', () => {
+    entry.setAttributes({
+      ariaLabel: 'Pilot name',
+      inputMode: 'numeric',
+      enterKeyHint: 'done',
+      maxLength: 12,
+    });
+
+    expect(entry.element.getAttribute('aria-label')).toBe('Pilot name');
+    expect(entry.element.getAttribute('inputmode')).toBe('numeric');
+    expect(entry.element.getAttribute('enterkeyhint')).toBe('done');
+    expect(entry.element.getAttribute('maxlength')).toBe('12');
+
+    entry.setAttributes({ maxLength: Number.POSITIVE_INFINITY });
+
+    expect(entry.element.hasAttribute('aria-label')).toBe(false);
+    expect(entry.element.hasAttribute('maxlength')).toBe(false);
+  });
+
+  it('reports typing as a change and drains events once', () => {
+    type('abc');
+
+    expect(entry.value).toBe('abc');
+    expect(entry.takeEvents().changed).toBe(true);
+    expect(entry.takeEvents().changed).toBe(false);
+  });
+
+  it('keeps the selection inside the value when it is replaced', () => {
+    entry.setValue('hello');
+    entry.setSelection(5, 5);
+    entry.setValue('hi');
+
+    expect(entry.selectionStart).toBe(2);
+    expect(entry.selectionEnd).toBe(2);
+    expect(entry.takeEvents().changed).toBe(false);
+  });
+
+  it('tracks focus and reports blur', () => {
+    entry.focus();
+    expect(entry.isFocused).toBe(true);
+
+    entry.blur();
+    expect(entry.isFocused).toBe(false);
+    expect(entry.takeEvents().blurred).toBe(true);
+  });
+
+  it('submits on Enter and cancels on Escape, without browser behavior', () => {
+    const enter = keyDown('Enter');
+
+    expect(enter.defaultPrevented).toBe(true);
+
+    const escape = keyDown('Escape');
+
+    expect(escape.defaultPrevented).toBe(true);
+
+    const events = entry.takeEvents();
+
+    expect(events.submitted).toBe(true);
+    expect(events.cancelled).toBe(true);
+  });
+
+  it('submits once while Enter is held', () => {
+    keyDown('Enter');
+    entry.takeEvents();
+    keyDown('Enter', { repeat: true });
+
+    expect(entry.takeEvents().submitted).toBe(false);
+  });
+
+  it('does not submit or cancel during an IME composition', () => {
+    keyDown('Enter', { isComposing: true });
+    keyDown('Escape', { keyCode: 229 });
+
+    const events = entry.takeEvents();
+
+    expect(events.submitted).toBe(false);
+    expect(events.cancelled).toBe(false);
+  });
+
+  it('cancels Tab', () => {
+    expect(keyDown('Tab').defaultPrevented).toBe(true);
+  });
+
+  it('does not let a key held before focusing auto-repeat into the input', () => {
+    entry.focus();
+
+    const repeat = keyDown('KeyA', { repeat: true });
+    const enterRepeat = keyDown('Enter', { repeat: true });
+
+    expect(repeat.defaultPrevented).toBe(true);
+    expect(enterRepeat.defaultPrevented).toBe(true);
+    expect(entry.takeEvents().submitted).toBe(false);
+  });
+
+  it('lets a key pressed while focused auto-repeat', () => {
+    entry.focus();
+    keyDown('KeyA');
+
+    expect(keyDown('KeyA', { repeat: true }).defaultPrevented).toBe(false);
+  });
+
+  it('tracks the IME composition range and reports its end as a change', () => {
+    entry.setValue('ab');
+    entry.setSelection(2, 2);
+
+    entry.element.dispatchEvent(new CompositionEvent('compositionstart'));
+    entry.element.dispatchEvent(
+      new CompositionEvent('compositionupdate', { data: 'にほ' }),
+    );
+
+    expect(entry.composition).toEqual({ start: 2, end: 4 });
+
+    entry.element.dispatchEvent(new CompositionEvent('compositionend'));
+
+    expect(entry.composition).toBeNull();
+    expect(entry.takeEvents().changed).toBe(true);
+  });
+
+  it('removes the element on dispose', () => {
+    const { element } = entry;
+
+    entry.dispose();
+
+    expect(element.isConnected).toBe(false);
+  });
+});
diff --git a/src/input/text-entry/text-entry.ts b/src/input/text-entry/text-entry.ts
new file mode 100644
index 000000000..853f736e6
--- /dev/null
+++ b/src/input/text-entry/text-entry.ts
@@ -0,0 +1,467 @@
+/** A DOM rectangle: CSS pixels, origin at the container's top-left, Y down. */
+export interface CssRect {
+  /** Distance from the container's left edge, in CSS pixels. */
+  left: number;
+
+  /** Distance from the container's top edge, in CSS pixels. */
+  top: number;
+
+  /** Width, in CSS pixels. */
+  width: number;
+
+  /** Height, in CSS pixels. */
+  height: number;
+}
+
+/**
+ * The HTML attributes a text entry's hidden `<input>` carries. Phone
+ * keyboards read them when the input is focused, and screen readers
+ * announce `ariaLabel`. Leave a field `undefined` to use the browser's
+ * default.
+ */
+export interface TextEntryAttributes {
+  /** The input's accessible name (`aria-label`), announced by screen readers. */
+  ariaLabel?: string;
+
+  /** Which on-screen keyboard to show (`inputmode`), e.g. `'numeric'`. */
+  inputMode?:
+    | 'none'
+    | 'text'
+    | 'decimal'
+    | 'numeric'
+    | 'tel'
+    | 'search'
+    | 'email'
+    | 'url';
+
+  /** Whether and how the browser may autofill the input (`autocomplete`), e.g. `'off'` or `'nickname'`. */
+  autocomplete?: string;
+
+  /** How phone keyboards capitalize what's typed (`autocapitalize`). */
+  autocapitalize?: 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
+
+  /** The label of a phone keyboard's Enter key (`enterkeyhint`). */
+  enterKeyHint?:
+    'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';
+
+  /**
+   * The most UTF-16 code units the player can type (`maxlength`). A
+   * non-finite value means no limit.
+   */
+  maxLength?: number;
+}
+
+/** What happened to a text entry since the last {@link TextEntry.takeEvents}. */
+export interface TextEntryEvents {
+  /** The value changed through typing, pasting or an IME. */
+  changed: boolean;
+
+  /** Enter was pressed outside an IME composition. */
+  submitted: boolean;
+
+  /** Escape was pressed outside an IME composition. */
+  cancelled: boolean;
+
+  /** The browser took focus away (a click elsewhere, a phone's "Done", a tab switch). */
+  blurred: boolean;
+}
+
+/** A range of UTF-16 code units in a text entry's value. */
+export interface TextRange {
+  /** The index of the range's first code unit. */
+  start: number;
+
+  /** The index one past the range's last code unit. */
+  end: number;
+}
+
+/**
+ * One hidden DOM `<input>` that receives typing for text the game draws
+ * itself. The browser does the hard parts (keyboard layouts, IME
+ * composition, clipboard, phone keyboards, screen readers); the entry
+ * exposes the result as data.
+ */
+export interface TextEntry {
+  /** The current text, as the DOM input holds it. */
+  readonly value: string;
+
+  /** The start of the selection, in UTF-16 code units. Equal to `selectionEnd` when it's just a caret. */
+  readonly selectionStart: number;
+
+  /** The end of the selection, in UTF-16 code units. */
+  readonly selectionEnd: number;
+
+  /** The IME composition range, or `null` when the player isn't composing. */
+  readonly composition: TextRange | null;
+
+  /** Whether the hidden input has focus, so the player's typing goes to it. */
+  readonly isFocused: boolean;
+
+  /** The hidden `<input>` element, for tests and for advanced integrations. */
+  readonly element: HTMLInputElement;
+
+  /**
+   * Replaces the text, for clearing or prefilling it. The selection is
+   * clamped to the new text. Doesn't count as a change in
+   * {@link TextEntryEvents}, the same way setting a DOM input's value
+   * doesn't raise `input`.
+   * @param value - The new text.
+   */
+  setValue(value: string): void;
+
+  /**
+   * Selects a range of the text, or places the caret when `start` equals
+   * `end`.
+   * @param start - The selection's start, in UTF-16 code units.
+   * @param end - The selection's end, in UTF-16 code units.
+   */
+  setSelection(start: number, end: number): void;
+
+  /**
+   * Places the hidden element over a rectangle, so phone keyboards scroll
+   * it into view and IME candidate windows open next to it.
+   * @param rect - The rectangle, in CSS pixels relative to the container.
+   */
+  setScreenRect(rect: CssRect): void;
+
+  /**
+   * Sets the element's HTML attributes. Fields left `undefined` are
+   * removed.
+   * @param attributes - The attributes to set.
+   */
+  setAttributes(attributes: TextEntryAttributes): void;
+
+  /**
+   * Focuses the hidden element. A phone only opens its keyboard when this
+   * is called inside a user gesture's event handler (`pointerup`, `click`,
+   * `touchend`).
+   */
+  focus(): void;
+
+  /** Removes focus from the hidden element. */
+  blur(): void;
+
+  /**
+   * Returns what happened since the last call, and clears it. Events
+   * arrive from the DOM between ticks; draining them once per tick lets a
+   * system react to each one exactly once.
+   * @returns The events since the last call.
+   */
+  takeEvents(): TextEntryEvents;
+
+  /** Removes the hidden element and its listeners. */
+  dispose(): void;
+}
+
+const enterCode = 'Enter';
+const escapeCode = 'Escape';
+const tabCode = 'Tab';
+
+/** The `keyCode` browsers report for a key event that's part of an IME composition. */
+const imeProcessKeyCode = 229;
+
+const attributeNames: Record<keyof TextEntryAttributes, string> = {
+  ariaLabel: 'aria-label',
+  inputMode: 'inputmode',
+  autocomplete: 'autocomplete',
+  autocapitalize: 'autocapitalize',
+  enterKeyHint: 'enterkeyhint',
+  maxLength: 'maxlength',
+};
+
+function createNoEvents(): TextEntryEvents {
+  return {
+    changed: false,
+    submitted: false,
+    cancelled: false,
+    blurred: false,
+  };
+}
+
+function toAttributeValue(
+  key: keyof TextEntryAttributes,
+  value: TextEntryAttributes[keyof TextEntryAttributes],
+): string | null {
+  if (value === undefined) {
+    return null;
+  }
+
+  if (key === 'maxLength') {
+    return Number.isFinite(value)
+      ? String(Math.max(0, Math.floor(Number(value))))
+      : null;
+  }
+
+  return String(value);
+}
+
+function createHiddenInput(): HTMLInputElement {
+  const element = document.createElement('input');
+
+  element.type = 'text';
+  element.spellcheck = false;
+
+  // Invisible but still focusable and still laid out over the field: a
+  // phone scrolls a focused input into view above its keyboard, and an IME
+  // opens its candidate window next to it, so it has to be where the field
+  // is. `opacity: 0` also hides the browser's own caret and selection
+  // highlight, which the game draws itself. `pointer-events: none` lets
+  // taps through to the game's own hit test. A 16px font stops iOS from
+  // zooming the page when the input is focused.
+  Object.assign(element.style, {
+    position: 'absolute',
+    left: '0px',
+    top: '0px',
+    width: '1px',
+    height: '1px',
+    margin: '0',
+    padding: '0',
+    border: '0',
+    outline: 'none',
+    boxSizing: 'border-box',
+    background: 'transparent',
+    color: 'transparent',
+    caretColor: 'transparent',
+    fontSize: '16px',
+    opacity: '0',
+    pointerEvents: 'none',
+  });
+
+  return element;
+}
+
+function isComposingKey(event: KeyboardEvent): boolean {
+  // `keyCode` is deprecated, but it's the only way to recognize the
+  // keydown that some browsers send just before `compositionstart`.
+  // eslint-disable-next-line sonarjs/deprecation
+  return event.isComposing || event.keyCode === imeProcessKeyCode;
+}
+
+/**
+ * Creates a text entry: a hidden `<input>` appended to `container` that
+ * receives the player's typing for text the game draws itself.
+ *
+ * It enforces the keyboard rules a game needs around a text box:
+ * - A key that was already held when the input was focused (e.g. the Enter
+ *   that opened the menu) doesn't auto-repeat into it.
+ * - Enter and Escape are recorded as `submitted`/`cancelled` and have no
+ *   browser behavior, except during an IME composition, where Enter
+ *   commits the composition and Escape cancels it. Holding Enter submits
+ *   once.
+ * - Tab does nothing, since there's no tab order between game text fields.
+ *
+ * `KeyboardInputSource` ignores every key typed into an editable element,
+ * so keys typed here never reach the game's input actions.
+ *
+ * If `container` isn't positioned, it's made `position: relative`, so the
+ * element can be placed over a rectangle of it.
+ * @param container - The element the game's canvas is in.
+ * @returns The text entry.
+ */
+export function createTextEntry(container: HTMLElement): TextEntry {
+  const element = createHiddenInput();
+  const keysPressedWhileFocused = new Set<string>();
+  const attributes = new Map<string, string>();
+  let lastRect: CssRect | null = null;
+  let events = createNoEvents();
+  let isFocused = false;
+  let composition: TextRange | null = null;
+
+  if (getComputedStyle(container).position === 'static') {
+    container.style.position = 'relative';
+  }
+
+  const onKeyDown = (event: KeyboardEvent): void => {
+    if (event.repeat && !keysPressedWhileFocused.has(event.code)) {
+      event.preventDefault();
+
+      return;
+    }
+
+    keysPressedWhileFocused.add(event.code);
+
+    if (isComposingKey(event)) {
+      return;
+    }
+
+    if (event.code === enterCode || event.key === enterCode) {
+      event.preventDefault();
+      events.submitted ||= !event.repeat;
+
+      return;
+    }
+
+    if (event.code === escapeCode || event.key === escapeCode) {
+      event.preventDefault();
+      events.cancelled ||= !event.repeat;
+
+      return;
+    }
+
+    if (event.code === tabCode || event.key === tabCode) {
+      event.preventDefault();
+    }
+  };
+
+  const onKeyUp = (event: KeyboardEvent): void => {
+    keysPressedWhileFocused.delete(event.code);
+  };
+
+  const onInput = (): void => {
+    events.changed = true;
+  };
+
+  const onCompositionStart = (): void => {
+    const start = element.selectionStart ?? element.value.length;
+
+    composition = { start, end: start };
+  };
+
+  const onCompositionUpdate = (event: CompositionEvent): void => {
+    if (composition === null) {
+      onCompositionStart();
+    }
+
+    if (composition !== null) {
+      composition = {
+        start: composition.start,
+        end: composition.start + event.data.length,
+      };
+    }
+  };
+
+  const onCompositionEnd = (): void => {
+    composition = null;
+    events.changed = true;
+  };
+
+  const onFocus = (): void => {
+    isFocused = true;
+    keysPressedWhileFocused.clear();
+  };
+
+  const onBlur = (): void => {
+    isFocused = false;
+    composition = null;
+    keysPressedWhileFocused.clear();
+    events.blurred = true;
+  };
+
+  element.addEventListener('keydown', onKeyDown);
+  element.addEventListener('keyup', onKeyUp);
+  element.addEventListener('input', onInput);
+  element.addEventListener('compositionstart', onCompositionStart);
+  element.addEventListener('compositionupdate', onCompositionUpdate);
+  element.addEventListener('compositionend', onCompositionEnd);
+  element.addEventListener('focus', onFocus);
+  element.addEventListener('blur', onBlur);
+
+  container.appendChild(element);
+
+  return {
+    get value(): string {
+      return element.value;
+    },
+    get selectionStart(): number {
+      return element.selectionStart ?? element.value.length;
+    },
+    get selectionEnd(): number {
+      return element.selectionEnd ?? element.value.length;
+    },
+    get composition(): TextRange | null {
+      return composition;
+    },
+    get isFocused(): boolean {
+      return isFocused;
+    },
+    element,
+
+    setValue(value: string): void {
+      if (element.value === value) {
+        return;
+      }
+
+      const start = element.selectionStart ?? value.length;
+      const end = element.selectionEnd ?? value.length;
+
+      element.value = value;
+      element.setSelectionRange(
+        Math.min(start, value.length),
+        Math.min(end, value.length),
+      );
+    },
+
+    setSelection(start: number, end: number): void {
+      element.setSelectionRange(start, end);
+    },
+
+    setScreenRect(rect: CssRect): void {
+      if (
+        lastRect &&
+        lastRect.left === rect.left &&
+        lastRect.top === rect.top &&
+        lastRect.width === rect.width &&
+        lastRect.height === rect.height
+      ) {
+        return;
+      }
+
+      lastRect = { ...rect };
+      element.style.left = `${rect.left}px`;
+      element.style.top = `${rect.top}px`;
+      element.style.width = `${rect.width}px`;
+      element.style.height = `${rect.height}px`;
+    },
+
+    setAttributes(newAttributes: TextEntryAttributes): void {
+      for (const key of Object.keys(attributeNames) as Array<
+        keyof TextEntryAttributes
+      >) {
+        const name = attributeNames[key];
+        const value = toAttributeValue(key, newAttributes[key]);
+
+        if ((attributes.get(name) ?? null) === value) {
+          continue;
+        }
+
+        if (value === null) {
+          attributes.delete(name);
+          element.removeAttribute(name);
+
+          continue;
+        }
+
+        attributes.set(name, value);
+        element.setAttribute(name, value);
+      }
+    },
+
+    focus(): void {
+      element.focus({ preventScroll: true });
+    },
+
+    blur(): void {
+      element.blur();
+    },
+
+    takeEvents(): TextEntryEvents {
+      const taken = events;
+
+      events = createNoEvents();
+
+      return taken;
+    },
+
+    dispose(): void {
+      element.removeEventListener('keydown', onKeyDown);
+      element.removeEventListener('keyup', onKeyUp);
+      element.removeEventListener('input', onInput);
+      element.removeEventListener('compositionstart', onCompositionStart);
+      element.removeEventListener('compositionupdate', onCompositionUpdate);
+      element.removeEventListener('compositionend', onCompositionEnd);
+      element.removeEventListener('focus', onFocus);
+      element.removeEventListener('blur', onBlur);
+      element.remove();
+    },
+  };
+}
diff --git a/src/rendering/systems/render-system.test.ts b/src/rendering/systems/render-system.test.ts
index 5c993f629..72b596991 100644
--- a/src/rendering/systems/render-system.test.ts
+++ b/src/rendering/systems/render-system.test.ts
@@ -155,6 +155,7 @@ describe('createRenderEcsSystem', () => {
     world.addComponent<TextMeshEcsComponent>(entity, textMeshId, {
       glyphs: [],
       bounds: { width: 0, height: 0 },
+      caretStops: [],
       fillRenderable: renderable,
       effectsRenderable: renderable,
       ...mesh,
diff --git a/src/text/components/text-mesh-component.ts b/src/text/components/text-mesh-component.ts
index 749f8f191..d772c9b6c 100644
--- a/src/text/components/text-mesh-component.ts
+++ b/src/text/components/text-mesh-component.ts
@@ -43,6 +43,14 @@ export interface TextMeshEcsComponent {
    */
   readonly bounds: { width: number; height: number };
 
+  /**
+   * Where a caret sits at every UTF-16 boundary of the shaped text (see
+   * `ShapedText.caretStops`): `text.length + 1` positions, each an offset
+   * from the text's anchor in world units, its y on the line's baseline.
+   * Used to draw a text field's caret and selection.
+   */
+  readonly caretStops: readonly Vector2[];
+
   /**
    * The `FontAtlas`-backed `Renderable` these glyphs' fill draws with. See
    * `createTextRenderable`'s doc comment for why fill and effects are two
diff --git a/src/text/rendering/glyph-quad.test.ts b/src/text/rendering/glyph-quad.test.ts
index 583b11adc..acb2bc14f 100644
--- a/src/text/rendering/glyph-quad.test.ts
+++ b/src/text/rendering/glyph-quad.test.ts
@@ -52,6 +52,7 @@ function buildTextMesh(glyphs: GlyphQuad[]): TextMeshEcsComponent {
   return {
     glyphs,
     bounds: { width: 0, height: 0 },
+    caretStops: [],
     fillRenderable,
     effectsRenderable,
   };
@@ -418,6 +419,7 @@ describe('buildTextCameraCommands', () => {
             {
               glyphs: [glyph],
               bounds: { width: 0, height: 0 },
+              caretStops: [],
               fillRenderable: mismatchedRenderable,
               effectsRenderable: mismatchedRenderable,
             },
diff --git a/src/text/systems/text-shaping-system.test.ts b/src/text/systems/text-shaping-system.test.ts
index 54d686b8d..8416b30ef 100644
--- a/src/text/systems/text-shaping-system.test.ts
+++ b/src/text/systems/text-shaping-system.test.ts
@@ -170,6 +170,7 @@ describe('createTextShapingEcsSystem', () => {
     // y (3.5) down by 9.
     expect(mesh?.glyphs[0].offset).toEqual({ x: 3, y: 3.5 - 9 });
     expect(mesh?.bounds).toEqual({ width: 6, height: 12 });
+    expect(mesh?.caretStops).toHaveLength(2);
   });
 
   it('does not re-shape unchanged text on a later tick', () => {
diff --git a/src/text/systems/text-shaping-system.ts b/src/text/systems/text-shaping-system.ts
index da2e92ca3..c945483aa 100644
--- a/src/text/systems/text-shaping-system.ts
+++ b/src/text/systems/text-shaping-system.ts
@@ -130,7 +130,7 @@ export const createTextShapingEcsSystem = (
           continue;
         }
 
-        const { glyphs, bounds } = shapeText(
+        const { glyphs, bounds, caretStops } = shapeText(
           textComponent.text,
           textComponent.fontAtlas.data,
           {
@@ -152,6 +152,7 @@ export const createTextShapingEcsSystem = (
         world.addComponent<TextMeshEcsComponent>(entity, textMeshId, {
           glyphs,
           bounds,
+          caretStops,
           fillRenderable,
           effectsRenderable,
         });
diff --git a/src/text/utilities/shape-text.test.ts b/src/text/utilities/shape-text.test.ts
index 475167cc7..2b860e092 100644
--- a/src/text/utilities/shape-text.test.ts
+++ b/src/text/utilities/shape-text.test.ts
@@ -643,4 +643,82 @@ describe('shapeText', () => {
       expect(glyphs[4].offset.y).toBeCloseTo(3.5 - 48 - 9);
     });
   });
+
+  describe('caret stops', () => {
+    const baseline = { size: 10, verticalAlign: 'baseline' as const };
+
+    it('has one stop per UTF-16 boundary, including whitespace and the end', () => {
+      const { caretStops } = shapeText(
+        'A V ',
+        buildFixtureFontAtlasData(),
+        baseline,
+      );
+
+      expect(caretStops.map((stop) => stop.x)).toEqual([0, 6, 9, 15, 18]);
+      expect(caretStops.every((stop) => stop.y === 0)).toBe(true);
+    });
+
+    it('puts the stop before a kerned glyph after the kerning', () => {
+      const { caretStops } = shapeText(
+        'AV',
+        buildFixtureFontAtlasData(),
+        baseline,
+      );
+
+      expect(caretStops[1].x).toBeCloseTo(5.2);
+      expect(caretStops[2].x).toBeCloseTo(11.2);
+    });
+
+    it('gives a missing glyph a stop with no advance', () => {
+      const { caretStops } = shapeText(
+        'A?A',
+        buildFixtureFontAtlasData(),
+        baseline,
+      );
+
+      expect(caretStops.map((stop) => stop.x)).toEqual([0, 6, 6, 12]);
+    });
+
+    it('gives the boundary inside a surrogate pair the pair start', () => {
+      const { caretStops } = shapeText(
+        'A😀',
+        buildFixtureFontAtlasData(),
+        baseline,
+      );
+
+      expect(caretStops).toHaveLength(4);
+      expect(caretStops.map((stop) => stop.x)).toEqual([0, 6, 6, 6]);
+    });
+
+    it('has a single stop for an empty string, at the aligned origin', () => {
+      const { caretStops } = shapeText('', buildFixtureFontAtlasData(), {
+        ...baseline,
+        maxWidth: 100,
+        horizontalAlign: 'center',
+      });
+
+      expect(caretStops).toEqual([{ x: 50, y: 0 }]);
+    });
+
+    it('applies alignment and the vertical offset', () => {
+      const { caretStops } = shapeText('A', buildFixtureFontAtlasData(), {
+        size: 10,
+        maxWidth: 20,
+        horizontalAlign: 'right',
+      });
+
+      expect(caretStops.map((stop) => stop.x)).toEqual([14, 20]);
+      expect(caretStops[0].y).toBeCloseTo(-9);
+    });
+
+    it('moves the stops of a wrapped word to the next line', () => {
+      const { caretStops } = shapeText('A V', buildFixtureFontAtlasData(), {
+        ...baseline,
+        maxWidth: 8,
+      });
+
+      expect(caretStops[2]).toEqual({ x: 0, y: -12 });
+      expect(caretStops[3]).toEqual({ x: 6, y: -12 });
+    });
+  });
 });
diff --git a/src/text/utilities/shape-text.ts b/src/text/utilities/shape-text.ts
index df7ed4303..c66fab606 100644
--- a/src/text/utilities/shape-text.ts
+++ b/src/text/utilities/shape-text.ts
@@ -1,3 +1,4 @@
+import type { Vector2 } from '../../math/index.js';
 import type { GlyphQuad } from '../components/text-mesh-component.js';
 import {
   type FontAtlasData,
@@ -73,6 +74,16 @@ export interface ShapedText {
 
   /** The shaped block's own bounds, in world units. */
   bounds: { width: number; height: number };
+
+  /**
+   * Where a caret sits at every UTF-16 boundary of the text, from `0`
+   * (before the first character) to `text.length` (after the last): the
+   * final x and the line's baseline y, offset from the block's anchor
+   * like `glyphs`, after alignment, justification and the vertical offset.
+   * Whitespace and characters with no glyph get stops too. The boundary
+   * inside a surrogate pair gets the position of the pair's start.
+   */
+  caretStops: Vector2[];
 }
 
 const defaultShapeTextOptions = {
@@ -87,6 +98,20 @@ const defaultShapeTextOptions = {
 interface ShapedWord {
   glyphs: GlyphQuad[];
   width: number;
+
+  /** The pen position before each of the word's code points, relative to the word's start. */
+  caretOffsets: number[];
+}
+
+/**
+ * Where a caret sits before one code point (or after the last one), within
+ * its unaligned line: the line it's on, its x from the line's start, and
+ * the index of the word whose justification shift it moves with.
+ */
+interface CaretPlacement {
+  lineIndex: number;
+  x: number;
+  wordIndex: number;
 }
 
 /** A word placed within a line, at `startX` from the line's own (unaligned) start. */
@@ -125,6 +150,7 @@ function shapeWord(
   letterSpacing: number,
 ): ShapedWord {
   const glyphs: GlyphQuad[] = [];
+  const caretOffsets: number[] = [];
   let penX = 0;
   let previousCodePoint: number | null = null;
   let hasPreviousGlyph = false;
@@ -134,6 +160,7 @@ function shapeWord(
     const glyph = fontAtlasData.glyphs.get(codePoint);
 
     if (!glyph) {
+      caretOffsets.push(penX);
       previousCodePoint = null;
 
       continue;
@@ -159,6 +186,8 @@ function shapeWord(
       penX += (fontAtlasData.kerning.get(kerningKey) ?? 0) * size;
     }
 
+    caretOffsets.push(penX);
+
     if (glyph.planeBounds && glyph.atlasBounds) {
       const { planeBounds, atlasBounds } = glyph;
       const glyphWidth = (planeBounds.right - planeBounds.left) * size;
@@ -203,36 +232,57 @@ function shapeWord(
     hasPreviousGlyph = true;
   }
 
-  return { glyphs, width: Math.max(0, penX) };
+  return { glyphs, width: Math.max(0, penX), caretOffsets };
 }
 
 /**
- * Sums the advance of a run of whitespace characters, in world units. Never
- * kerns and never applies `letterSpacing`: {@link wrapIntoLines} adds one
- * letter space per word gap itself, so a gap is the whitespace's advance
- * plus exactly one letter space however many whitespace characters it has.
- * @param whitespace - A run of whitespace characters.
+ * The advance of a single whitespace character, in world units. Never kerns
+ * and never applies `letterSpacing`: {@link wrapIntoLines} adds one letter
+ * space per word gap itself, so a gap is the whitespace's advance plus
+ * exactly one letter space however many whitespace characters it has.
+ * @param character - A whitespace character.
  * @param fontAtlasData - The font atlas metrics to look up advances in.
  * @param size - Font size, in world units.
- * @returns The whitespace run's total advance.
+ * @returns The character's advance, or `0` if the font has no glyph for it.
  */
 function getWhitespaceAdvance(
-  whitespace: string,
+  character: string,
   fontAtlasData: FontAtlasData,
   size: number,
 ): number {
-  let advance = 0;
+  const glyph = fontAtlasData.glyphs.get(character.codePointAt(0) as number);
 
-  for (const character of whitespace) {
-    const codePoint = character.codePointAt(0) as number;
-    const glyph = fontAtlasData.glyphs.get(codePoint);
+  return glyph ? glyph.advance * size : 0;
+}
 
-    if (glyph) {
-      advance += glyph.advance * size;
-    }
+/**
+ * Measures a run of whitespace: its total advance, and the pen position
+ * before each of its characters, relative to the run's start.
+ * @param whitespace - A run of whitespace characters.
+ * @param fontAtlasData - The font atlas metrics to look up advances in.
+ * @param size - Font size, in world units.
+ * @returns The run's width and caret offsets.
+ */
+function measureWhitespace(
+  whitespace: string,
+  fontAtlasData: FontAtlasData,
+  size: number,
+): { width: number; caretOffsets: number[] } {
+  const caretOffsets: number[] = [];
+  let width = 0;
+
+  for (const character of whitespace) {
+    caretOffsets.push(width);
+    width += getWhitespaceAdvance(character, fontAtlasData, size);
   }
 
-  return advance;
+  return { width, caretOffsets };
+}
+
+/** The lines {@link wrapIntoLines} produced, plus one caret placement per code point and one after the last. */
+interface WrappedText {
+  lines: ShapedLine[];
+  caretPlacements: CaretPlacement[];
 }
 
 /**
@@ -248,7 +298,8 @@ function getWhitespaceAdvance(
  * @param letterSpacing - Extra spacing between adjacent glyphs, in ems.
  * @param maxWidth - The width to wrap at, in world units, or `undefined` to
  * never wrap (the whole string becomes one line).
- * @returns The wrapped lines, each with its placed words and content width.
+ * @returns The wrapped lines, each with its placed words and content width,
+ * and where a caret sits before each code point and after the last.
  */
 function wrapIntoLines(
   text: string,
@@ -256,9 +307,10 @@ function wrapIntoLines(
   size: number,
   letterSpacing: number,
   maxWidth: number | undefined,
-): ShapedLine[] {
+): WrappedText {
   const tokens = text.split(/(\s+)/).filter((token) => token.length > 0);
   const lines: ShapedLine[] = [];
+  const caretPlacements: CaretPlacement[] = [];
 
   let currentWords: LineWord[] = [];
   let penX = 0;
@@ -271,9 +323,30 @@ function wrapIntoLines(
     lineContentWidth = 0;
   };
 
+  const placeCarets = (
+    startX: number,
+    caretOffsets: readonly number[],
+    wordIndex: number,
+  ): void => {
+    for (const caretOffset of caretOffsets) {
+      caretPlacements.push({
+        lineIndex: lines.length,
+        x: startX + caretOffset,
+        wordIndex,
+      });
+    }
+  };
+
+  // A caret between words (in whitespace, or in a word with no glyphs)
+  // moves with the previous word when a justified line stretches its gaps.
+  const previousWordIndex = (): number => Math.max(0, currentWords.length - 1);
+
   for (const token of tokens) {
     if (/^\s/.test(token)) {
-      penX += getWhitespaceAdvance(token, fontAtlasData, size);
+      const whitespace = measureWhitespace(token, fontAtlasData, size);
+
+      placeCarets(penX, whitespace.caretOffsets, previousWordIndex());
+      penX += whitespace.width;
 
       continue;
     }
@@ -283,6 +356,8 @@ function wrapIntoLines(
     // A word whose code points are all missing from the atlas draws nothing
     // and takes up no space, so it mustn't add a letter space either.
     if (word.glyphs.length === 0 && word.width === 0) {
+      placeCarets(penX, word.caretOffsets, previousWordIndex());
+
       continue;
     }
 
@@ -302,14 +377,46 @@ function wrapIntoLines(
       wordGap = 0;
     }
 
-    currentWords.push({ word, startX: penX + wordGap });
+    const startX = penX + wordGap;
+
+    placeCarets(startX, word.caretOffsets, currentWords.length);
+    currentWords.push({ word, startX });
     penX += wordGap + word.width;
     lineContentWidth = penX;
   }
 
+  placeCarets(penX, [0], previousWordIndex());
   commitLine();
 
-  return lines;
+  return { lines, caretPlacements };
+}
+
+/**
+ * Expands one caret stop per code point (plus the final one) to one per
+ * UTF-16 code unit boundary: a code point outside the Basic Multilingual
+ * Plane is two code units, and the boundary between them gets the pair's
+ * start.
+ * @param text - The shaped text.
+ * @param codePointStops - One stop before each code point, then one after the last.
+ * @returns One stop per UTF-16 boundary, `text.length + 1` in all.
+ */
+function toUtf16CaretStops(text: string, codePointStops: Vector2[]): Vector2[] {
+  const stops: Vector2[] = [];
+  let index = 0;
+
+  for (const character of text) {
+    const stop = codePointStops[index];
+
+    for (let unit = 0; unit < character.length; unit++) {
+      stops.push({ x: stop.x, y: stop.y });
+    }
+
+    index++;
+  }
+
+  stops.push(codePointStops[index]);
+
+  return stops;
 }
 
 /**
@@ -507,7 +614,7 @@ export function shapeText(
     horizontalAlignPivot,
   } = { ...defaultShapeTextOptions, ...options };
 
-  const lines = wrapIntoLines(
+  const { lines, caretPlacements } = wrapIntoLines(
     text,
     fontAtlasData,
     size,
@@ -540,6 +647,7 @@ export function shapeText(
   // `'middle'` can measure this exact block's actual rendered ink before
   // `verticalOffset` (which depends on that measurement) is applied below.
   const glyphs: GlyphQuad[] = [];
+  const lineOffsets: { x: number; y: number; justifyGapStretch: number }[] = [];
 
   lines.forEach((line, lineIndex) => {
     const isLastLine = lineIndex === lines.length - 1;
@@ -564,6 +672,12 @@ export function shapeText(
     );
     const lineY = -lineIndex * actualLineHeight;
 
+    lineOffsets.push({
+      x: boxLeftOffset + uniformOffset,
+      y: lineY,
+      justifyGapStretch,
+    });
+
     line.words.forEach(({ word, startX }, wordIndex) => {
       const x =
         startX + boxLeftOffset + uniformOffset + wordIndex * justifyGapStretch;
@@ -590,5 +704,20 @@ export function shapeText(
     glyph.offset.y += verticalOffset;
   }
 
-  return { glyphs, bounds: { width: contentWidth, height: blockHeight } };
+  const codePointStops = caretPlacements.map(
+    ({ lineIndex, x, wordIndex }): Vector2 => {
+      const lineOffset = lineOffsets[lineIndex];
+
+      return {
+        x: x + lineOffset.x + wordIndex * lineOffset.justifyGapStretch,
+        y: lineOffset.y + verticalOffset,
+      };
+    },
+  );
+
+  return {
+    glyphs,
+    bounds: { width: contentWidth, height: blockHeight },
+    caretStops: toUtf16CaretStops(text, codePointStops),
+  };
 }
diff --git a/src/ui/components/index.ts b/src/ui/components/index.ts
index 80fed27f9..3d89b7d68 100644
--- a/src/ui/components/index.ts
+++ b/src/ui/components/index.ts
@@ -5,6 +5,7 @@ export * from './content-size-fitter-component.js';
 export * from './layout-element-component.js';
 export * from './layout-group-component.js';
 export * from './rect-transform-component.js';
+export * from './text-input-component.js';
 export * from './tooltip-component.js';
 export * from './ui-color-transition-component.js';
 export * from './ui-dropdown-component.js';
diff --git a/src/ui/components/text-input-component.test.ts b/src/ui/components/text-input-component.test.ts
new file mode 100644
index 000000000..c30c219bd
--- /dev/null
+++ b/src/ui/components/text-input-component.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import {
+  addTextInputComponent,
+  editTextInput,
+  setTextInputValue,
+} from './text-input-component.js';
+import { EcsWorld } from '../../ecs/index.js';
+import { createTextEntry } from '../../input/index.js';
+
+describe('TextInputEcsComponent', () => {
+  const build = () => {
+    const world = new EcsWorld();
+    const entity = world.createEntity();
+    const entry = createTextEntry(document.createElement('div'));
+    const component = addTextInputComponent(world, entity, {
+      entry,
+      textLabel: world.createEntity(),
+      placeholderLabel: world.createEntity(),
+      caret: world.createEntity(),
+      selection: world.createEntity(),
+      compositionUnderline: world.createEntity(),
+      value: 'start',
+    });
+
+    return { world, entity, entry, component };
+  };
+
+  it('defaults to no length limit and no attributes, with the initial value in the entry', () => {
+    const { component, entry } = build();
+
+    expect(component.maxLength).toBe(Number.POSITIVE_INFINITY);
+    expect(component.attributes).toEqual({});
+    expect(component.value).toBe('start');
+    expect(component.isEditing).toBe(false);
+    expect(entry.value).toBe('start');
+  });
+
+  it("setTextInputValue writes the field's entry", () => {
+    const { world, entity, entry, component } = build();
+
+    setTextInputValue(world, entity, 'next');
+
+    expect(entry.value).toBe('next');
+    // `value` is the system's to update, on the next tick.
+    expect(component.value).toBe('start');
+  });
+
+  it("editTextInput focuses the field's entry", () => {
+    const { world, entity, entry } = build();
+
+    document.body.appendChild(entry.element);
+    editTextInput(world, entity);
+
+    expect(entry.isFocused).toBe(true);
+    entry.dispose();
+  });
+});
diff --git a/src/ui/components/text-input-component.ts b/src/ui/components/text-input-component.ts
new file mode 100644
index 000000000..e50da1dcc
--- /dev/null
+++ b/src/ui/components/text-input-component.ts
@@ -0,0 +1,184 @@
+import { createComponentId } from '../../ecs/ecs-component.js';
+import { EcsWorld } from '../../ecs/ecs-world.js';
+import { ForgeEvent, ParameterizedForgeEvent } from '../../events/index.js';
+import type {
+  TextEntry,
+  TextEntryAttributes,
+} from '../../input/text-entry/text-entry.js';
+
+/**
+ * The HTML attributes a text field's hidden input carries (see
+ * `TextEntryAttributes`), except `maxLength`, which is the field's own
+ * {@link TextInputDefaultedOptions.maxLength}.
+ */
+export type TextInputAttributes = Omit<TextEntryAttributes, 'maxLength'>;
+
+/**
+ * Fields of {@link TextInputEcsComponent} with no sensible default; callers
+ * must always provide these. `createTextInput` creates all of them.
+ */
+export interface TextInputRequiredOptions {
+  /**
+   * The field's hidden DOM input (see `createTextEntry`). It holds the text,
+   * the selection and the IME composition; the component mirrors them.
+   * Disposed by `createUiTextInputEcsSystem` when the component is removed.
+   */
+  readonly entry: TextEntry;
+
+  /** The label entity the field's text is drawn with. Its `TextEcsComponent.text` is written by the text input system. */
+  readonly textLabel: number;
+
+  /**
+   * The label entity shown, instead of `textLabel`, while the field is
+   * empty. Its text and color are the placeholder's; the text input system
+   * only shows and hides it.
+   */
+  readonly placeholderLabel: number;
+
+  /** The panel entity drawn as the caret. Placed, sized and blinked by the text input system. */
+  readonly caret: number;
+
+  /** The panel entity drawn behind selected text. Placed and sized by the text input system. */
+  readonly selection: number;
+
+  /** The panel entity drawn under text that's still being composed with an IME. */
+  readonly compositionUnderline: number;
+}
+
+/**
+ * Fields of {@link TextInputEcsComponent} with a sensible default, or that
+ * are genuinely optional; callers may omit these.
+ */
+export interface TextInputDefaultedOptions {
+  /**
+   * The most UTF-16 code units the field holds. Defaults to no limit. A
+   * field doesn't scroll, so pick a limit whose longest value fits its
+   * width.
+   */
+  maxLength: number;
+
+  /**
+   * Transforms what was typed before it's accepted, e.g. upper-casing a
+   * code or dropping leading spaces. Runs after characters the field's font
+   * can't draw are removed, and before `maxLength` is applied. Must return
+   * the same text when given text it already returned.
+   */
+  filter?: (text: string) => string;
+
+  /** The hidden input's HTML attributes (`aria-label`, `inputmode`, ...). Defaults to none. */
+  attributes: TextInputAttributes;
+}
+
+/**
+ * A single-line text field: the player types into a hidden DOM input
+ * (`entry`), and the field draws its value, caret and selection with
+ * ordinary UI entities. Build one with `createTextInput`.
+ *
+ * Editing is separate from UI focus: a field is edited after a tap or
+ * click on it, a submit while it's focused, or `editTextInput`, and stops
+ * on Enter (`onSubmit`), Escape (`onCancel`) or when the browser takes
+ * focus away. UI focus can move anywhere meanwhile.
+ */
+export interface TextInputEcsComponent
+  extends TextInputRequiredOptions, TextInputDefaultedOptions {
+  /**
+   * The field's committed text: what was typed, after filtering. Text
+   * that's still being composed with an IME isn't part of it until it's
+   * committed. System-owned, written by `createUiTextInputEcsSystem`;
+   * change it with `setTextInputValue`.
+   */
+  value: string;
+
+  /**
+   * Whether the field is being typed into, i.e. its hidden input has focus.
+   * System-owned, written by `createUiTextInputEcsSystem`; start editing
+   * with `editTextInput`.
+   */
+  isEditing: boolean;
+
+  /** Raised with the new `value` whenever it changes. */
+  readonly onValueChanged: ParameterizedForgeEvent<string>;
+
+  /** Raised with `value` when the player presses Enter. Editing ends. */
+  readonly onSubmit: ParameterizedForgeEvent<string>;
+
+  /** Raised when the player presses Escape. Editing ends; the value is kept. */
+  readonly onCancel: ForgeEvent;
+}
+
+export const textInputId =
+  createComponentId<TextInputEcsComponent>('textInput');
+
+const defaultTextInputOptions: TextInputDefaultedOptions = {
+  maxLength: Number.POSITIVE_INFINITY,
+  attributes: {},
+};
+
+/**
+ * Attaches a {@link TextInputEcsComponent} to `entity`. Needs a
+ * `RectTransformEcsComponent` and a `UiInteractableEcsComponent` on the
+ * same entity; use `createTextInput` to build a whole field.
+ * @param world - The ECS world `entity` belongs to.
+ * @param entity - The entity to attach the component to.
+ * @param options - The field's entry, part entities and settings, plus an
+ * optional initial `value`.
+ * @returns The attached component.
+ */
+export function addTextInputComponent(
+  world: EcsWorld,
+  entity: number,
+  options: TextInputRequiredOptions &
+    Partial<TextInputDefaultedOptions> & { value?: string },
+): TextInputEcsComponent {
+  const { value, ...rest } = options;
+
+  if (value !== undefined) {
+    options.entry.setValue(value);
+  }
+
+  const component: TextInputEcsComponent = {
+    ...defaultTextInputOptions,
+    ...rest,
+    value: options.entry.value,
+    isEditing: false,
+    onValueChanged: new ParameterizedForgeEvent('textInput.onValueChanged'),
+    onSubmit: new ParameterizedForgeEvent('textInput.onSubmit'),
+    onCancel: new ForgeEvent('textInput.onCancel'),
+  };
+
+  return world.addComponent(entity, textInputId, component);
+}
+
+/**
+ * Replaces a text field's text, e.g. to clear or prefill it. The text goes
+ * through the field's filters like typed text, and `value` and
+ * `onValueChanged` update on the next tick.
+ * @param world - The ECS world `field` belongs to.
+ * @param field - The text field entity.
+ * @param value - The new text.
+ * @throws An error if `field` has no `TextInputEcsComponent`.
+ */
+export function setTextInputValue(
+  world: EcsWorld,
+  field: number,
+  value: string,
+): void {
+  world
+    .getComponentRequired<TextInputEcsComponent>(field, textInputId)
+    .entry.setValue(value);
+}
+
+/**
+ * Starts editing a text field, as a tap on it would, e.g. when its panel
+ * opens. `isEditing` updates on the next tick. A phone only opens its
+ * keyboard when this is called inside a user gesture's event handler; taps
+ * on the field itself always are.
+ * @param world - The ECS world `field` belongs to.
+ * @param field - The text field entity.
+ * @throws An error if `field` has no `TextInputEcsComponent`.
+ */
+export function editTextInput(world: EcsWorld, field: number): void {
+  world
+    .getComponentRequired<TextInputEcsComponent>(field, textInputId)
+    .entry.focus();
+}
diff --git a/src/ui/systems/index.ts b/src/ui/systems/index.ts
index a0b8fa557..23f476e69 100644
--- a/src/ui/systems/index.ts
+++ b/src/ui/systems/index.ts
@@ -8,6 +8,7 @@ export * from './ui-progress-bar-system.js';
 export * from './ui-raycast-system.js';
 export * from './ui-safe-area-system.js';
 export * from './ui-slider-system.js';
+export * from './ui-text-input-system.js';
 export * from './ui-toggle-system.js';
 export * from './ui-tooltip-system.js';
 export * from './ui-transition-system.js';
diff --git a/src/ui/systems/ui-interaction-system.ts b/src/ui/systems/ui-interaction-system.ts
index ae3a69ed5..4ed1128ef 100644
--- a/src/ui/systems/ui-interaction-system.ts
+++ b/src/ui/systems/ui-interaction-system.ts
@@ -184,7 +184,7 @@ export const createUiInteractionEcsSystem = (
           world,
           canvas,
           renderContext,
-          pointerSource,
+          pointerSource.position,
         );
         pointerPositionByCanvas.set(canvasEntity, position);
       }
diff --git a/src/ui/systems/ui-raycast-system.ts b/src/ui/systems/ui-raycast-system.ts
index 5c1e409f1..6b4984f70 100644
--- a/src/ui/systems/ui-raycast-system.ts
+++ b/src/ui/systems/ui-raycast-system.ts
@@ -1,135 +1,17 @@
 import { EcsSystem } from '../../ecs/ecs-system.js';
-import { EcsWorld } from '../../ecs/ecs-world.js';
-import { Rects } from '../../math/index.js';
-import {
-  CameraEcsComponent,
-  cameraId,
-  RenderContext,
-  SpriteEcsComponent,
-  spriteId,
-} from '../../rendering/index.js';
-import { matchesMask } from '../../utilities/matches-mask.js';
+import { RenderContext } from '../../rendering/index.js';
 import {
   CanvasEcsComponent,
   canvasId,
 } from '../components/canvas-component.js';
-import {
-  RectTransformEcsComponent,
-  rectTransformId,
-} from '../components/rect-transform-component.js';
-import {
-  UiInteractableEcsComponent,
-  uiInteractableId,
-} from '../components/ui-interactable-component.js';
 import { UiPointerSource } from '../types/ui-pointer-source.js';
-import { findOwningCanvas } from '../utilities/find-owning-canvas.js';
-import { resolveCanvasGroupState } from '../utilities/resolve-canvas-group-state.js';
-import { resolveCanvasPointerPosition } from '../utilities/resolve-canvas-pointer-position.js';
-
-/**
- * Whether `camera` can actually see `entity` - `true` when `entity` has no
- * `SpriteEcsComponent` (an invisible hit region has nothing to cull) or its
- * `Renderable.category` matches the camera's `cullingMask`. An element
- * culled from its canvas's camera must not be clickable either, or the UI
- * develops invisible hit regions.
- */
-function isVisibleToCamera(
-  world: EcsWorld,
-  entity: number,
-  camera: CameraEcsComponent | null,
-): boolean {
-  const sprite = world.getComponent<SpriteEcsComponent>(entity, spriteId);
-
-  if (!sprite) {
-    return true;
-  }
-
-  return (
-    !!camera && matchesMask(sprite.renderable.category, camera.cullingMask)
-  );
-}
-
-/** Groups interactable indices (into `interactableEntities`/`rectTransforms`) by their owning canvas entity. */
-function groupInteractableIndicesByCanvas(
-  world: EcsWorld,
-  interactableEntities: readonly number[],
-): Map<number, number[]> {
-  const indicesByCanvas = new Map<number, number[]>();
-
-  for (let i = 0; i < interactableEntities.length; i++) {
-    const owningCanvas = findOwningCanvas(world, interactableEntities[i]);
-
-    if (owningCanvas === null) {
-      continue;
-    }
-
-    let indices = indicesByCanvas.get(owningCanvas);
-
-    if (!indices) {
-      indices = [];
-      indicesByCanvas.set(owningCanvas, indices);
-    }
-
-    indices.push(i);
-  }
-
-  return indicesByCanvas;
-}
+import { raycastUiCanvas } from '../utilities/raycast-ui-canvas.js';
 
 /**
- * Scans `indices` (already sorted topmost-first) for the first one whose
- * `blocksRaycasts` interactable is visible to `camera` and whose resolved
- * rect contains `pointerPosition`.
- */
-function findRaycastHit(
-  world: EcsWorld,
-  indices: readonly number[],
-  interactableEntities: readonly number[],
-  interactables: readonly UiInteractableEcsComponent[],
-  rectTransforms: readonly RectTransformEcsComponent[],
-  camera: CameraEcsComponent | null,
-  pointerPosition: ReturnType<typeof resolveCanvasPointerPosition>,
-): number | null {
-  if (!pointerPosition) {
-    return null;
-  }
-
-  for (const index of indices) {
-    if (!interactables[index].blocksRaycasts) {
-      continue;
-    }
-
-    const entity = interactableEntities[index];
-
-    if (
-      !isVisibleToCamera(world, entity, camera) ||
-      !resolveCanvasGroupState(world, entity).blocksRaycasts
-    ) {
-      continue;
-    }
-
-    if (Rects.contains(rectTransforms[index].rect, pointerPosition)) {
-      return entity;
-    }
-  }
-
-  return null;
-}
-
-/**
- * Creates a system that, per `CanvasEcsComponent`, converts the pointer
- * source's position into that canvas's UI world space and scans its
- * `UiInteractableEcsComponent`s in reverse hierarchy order (topmost first,
- * by `RectTransformEcsComponent.sortDepth`) for the first whose resolved
- * `rect` contains it - a linear reverse-depth scan: element counts here are
- * in the hundreds, not the hundreds of thousands, so a plain scan is a few
- * microseconds with no acceleration structure to build or invalidate. An
- * element with `blocksRaycasts: false` is transparent to the scan (never
- * considered, hit or not) - so is one with an ancestor
- * `CanvasGroupEcsComponent` whose own `blocksRaycasts` is `false` (see
- * `resolveCanvasGroupState`); an element culled from the canvas's camera by
- * `cullingMask` is skipped the same way an invisible element shouldn't be
- * clickable.
+ * Creates a system that, per `CanvasEcsComponent`, hit-tests the pointer
+ * source's position against that canvas's `UiInteractableEcsComponent`s
+ * with `raycastUiCanvas` (topmost first; `blocksRaycasts`, canvas groups
+ * and camera culling respected - see its doc comment).
  *
  * Writes `CanvasEcsComponent.hoveredEntity` (the topmost hit, or `null`) and
  * `isPointerOverUi` (`hoveredEntity !== null`) every tick - read by
@@ -150,49 +32,13 @@ export const createUiRaycastEcsSystem = (
   name: 'uiRaycast',
   query: [canvasId],
   update: (world, { entities: canvasEntities, components: [canvases] }) => {
-    const {
-      entities: interactableEntities,
-      components: [interactables, rectTransforms],
-    } = world.query<[UiInteractableEcsComponent, RectTransformEcsComponent]>([
-      uiInteractableId,
-      rectTransformId,
-    ]);
-
-    const indicesByCanvas = groupInteractableIndicesByCanvas(
-      world,
-      interactableEntities,
-    );
-
     for (let c = 0; c < canvasEntities.length; c++) {
-      const canvasEntity = canvasEntities[c];
       const canvas = canvases[c];
-
-      const indices = indicesByCanvas.get(canvasEntity) ?? [];
-
-      indices.sort(
-        (a, b) => rectTransforms[b].sortDepth - rectTransforms[a].sortDepth,
-      );
-
-      const pointerPosition = resolveCanvasPointerPosition(
+      const hitEntity = raycastUiCanvas(
         world,
-        canvas,
+        canvasEntities[c],
         renderContext,
-        pointerSource,
-      );
-
-      const camera = world.getComponent<CameraEcsComponent>(
-        canvas.camera,
-        cameraId,
-      );
-
-      const hitEntity = findRaycastHit(
-        world,
-        indices,
-        interactableEntities,
-        interactables,
-        rectTransforms,
-        camera,
-        pointerPosition,
+        pointerSource.position,
       );
 
       canvas.hoveredEntity = hitEntity;
diff --git a/src/ui/systems/ui-slider-system.ts b/src/ui/systems/ui-slider-system.ts
index 9e89d68b3..422a24f9d 100644
--- a/src/ui/systems/ui-slider-system.ts
+++ b/src/ui/systems/ui-slider-system.ts
@@ -60,7 +60,12 @@ function applyActiveDrag(
       ? world.getComponent<CanvasEcsComponent>(owningCanvasEntity, canvasId)
       : null;
   const pointerPosition = canvas
-    ? resolveCanvasPointerPosition(world, canvas, renderContext, pointerSource)
+    ? resolveCanvasPointerPosition(
+        world,
+        canvas,
+        renderContext,
+        pointerSource.position,
+      )
     : null;
 
   if (!pointerPosition) {
diff --git a/src/ui/systems/ui-text-input-system.test.ts b/src/ui/systems/ui-text-input-system.test.ts
new file mode 100644
index 000000000..91956a1b5
--- /dev/null
+++ b/src/ui/systems/ui-text-input-system.test.ts
@@ -0,0 +1,434 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createUiTextInputEcsSystem } from './ui-text-input-system.js';
+import {
+  addParentComponent,
+  addPositionComponent,
+  Time,
+} from '../../common/index.js';
+import { EcsWorld } from '../../ecs/index.js';
+import {
+  addCameraComponent,
+  Color,
+  Renderable,
+  RenderContext,
+  spriteId,
+} from '../../rendering/index.js';
+import type { FontAtlas } from '../../text/font-atlas/font-atlas.js';
+import { textId, TextMeshEcsComponent, textMeshId } from '../../text/index.js';
+import { addCanvasComponent } from '../components/canvas-component.js';
+import {
+  addRectTransformComponent,
+  rectTransformId,
+} from '../components/rect-transform-component.js';
+import {
+  editTextInput,
+  setTextInputValue,
+  TextInputEcsComponent,
+  textInputId,
+} from '../components/text-input-component.js';
+import { addUiInteractableComponent } from '../components/ui-interactable-component.js';
+import { createTextInput, TextInput } from '../utilities/create-text-input.js';
+
+const glyph = (codePoint: number) => ({
+  codePoint,
+  advance: 0.5,
+  planeBounds: null,
+  atlasBounds: null,
+});
+
+const fontAtlas = {
+  data: {
+    metrics: {
+      lineHeight: 1.2,
+      ascender: 0.8,
+      descender: -0.2,
+      capHeight: 0.7,
+    },
+    glyphs: new Map(
+      [...'abcdefghijklmnopqrstuvwxyzAB'].map((character) => [
+        character.codePointAt(0)!,
+        glyph(character.codePointAt(0)!),
+      ]),
+    ),
+  },
+} as unknown as FontAtlas;
+
+const buildSprite = () => ({
+  width: 1,
+  height: 1,
+  renderable: { category: 1 } as Renderable,
+  pivot: { x: 0.5, y: 0.5 },
+  tintColor: Color.white,
+  uvOffset: { x: 0, y: 0 },
+  uvScale: { x: 1, y: 1 },
+  enabled: true,
+  layer: 0,
+});
+
+const pointer = (type: string, x: number, y: number): MouseEvent =>
+  new MouseEvent(type, {
+    clientX: x,
+    clientY: y,
+    button: 0,
+    bubbles: true,
+    cancelable: true,
+  });
+
+describe('createUiTextInputEcsSystem', () => {
+  let container: HTMLDivElement;
+  let renderContext: RenderContext;
+  let world: EcsWorld;
+  let field: TextInput;
+  let textInput: TextInputEcsComponent;
+  let canvasEntity: number;
+
+  const type = (value: string): void => {
+    textInput.entry.element.value = value;
+    textInput.entry.element.setSelectionRange(value.length, value.length);
+    textInput.entry.element.dispatchEvent(new Event('input'));
+  };
+
+  const keyDown = (code: string): void => {
+    textInput.entry.element.dispatchEvent(
+      new KeyboardEvent('keydown', { code, key: code, cancelable: true }),
+    );
+  };
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+
+    const canvas = document.createElement('canvas');
+
+    container.appendChild(canvas);
+
+    renderContext = {
+      canvas,
+      width: 800,
+      height: 600,
+      cssWidth: 800,
+      cssHeight: 600,
+      pixelRatio: 1,
+    } as unknown as RenderContext;
+
+    world = new EcsWorld();
+
+    const camera = world.createEntity();
+
+    addPositionComponent(world, camera);
+    addCameraComponent(world, camera, { verticalWorldUnits: 600 });
+
+    canvasEntity = world.createEntity();
+    addPositionComponent(world, canvasEntity);
+    addRectTransformComponent(world, canvasEntity);
+    addCanvasComponent(world, canvasEntity, { camera });
+
+    field = createTextInput(world, canvasEntity, {
+      renderContext,
+      sprite: buildSprite(),
+      fillSprite: buildSprite(),
+      fontAtlas,
+      size: 20,
+      placeholder: 'Name',
+    });
+    textInput = field.textInput;
+
+    // The field covers the world origin, i.e. the middle of the canvas.
+    world.getComponent(field.entity, rectTransformId)!.rect = {
+      min: { x: -100, y: -20 },
+      max: { x: 100, y: 20 },
+    };
+
+    world.addSystem(
+      createUiTextInputEcsSystem(renderContext, {
+        rawDeltaTimeInMilliseconds: 16,
+      } as Time),
+    );
+  });
+
+  afterEach(() => {
+    world.stop();
+    container.remove();
+  });
+
+  it('mirrors typed text into value and raises onValueChanged', () => {
+    const listener = vi.fn();
+
+    field.onValueChanged.registerListener(listener);
+    type('abc');
+    world.update();
+
+    expect(textInput.value).toBe('abc');
+    expect(listener).toHaveBeenCalledWith('abc');
+    expect(world.getComponent(field.textLabel, textId)!.text).toBe('abc');
+  });
+
+  it("drops characters the font can't draw, keeping spaces and the caret position", () => {
+    type('a é b');
+    textInput.entry.setSelection(3, 3);
+    world.update();
+
+    expect(textInput.value).toBe('a  b');
+    expect(textInput.entry.value).toBe('a  b');
+    expect(textInput.entry.selectionStart).toBe(2);
+  });
+
+  it('runs the font filter, then the game filter, then maxLength', () => {
+    textInput.filter = (text) => text.toUpperCase();
+    textInput.maxLength = 3;
+    type('aé1bcd');
+    world.update();
+
+    expect(textInput.value).toBe('ABC');
+  });
+
+  it('does not filter or accept text during an IME composition', () => {
+    const { element } = textInput.entry;
+
+    element.dispatchEvent(new CompositionEvent('compositionstart'));
+    element.dispatchEvent(
+      new CompositionEvent('compositionupdate', { data: 'にa' }),
+    );
+    element.value = 'にa';
+    world.update();
+
+    expect(textInput.value).toBe('');
+    expect(element.value).toBe('にa');
+    expect(world.getComponent(field.textLabel, textId)!.text).toBe('にa');
+    expect(
+      world.getComponent(textInput.compositionUnderline, spriteId)!.enabled,
+    ).toBe(true);
+
+    element.dispatchEvent(new CompositionEvent('compositionend'));
+    world.update();
+
+    expect(textInput.value).toBe('a');
+  });
+
+  it('starts editing when the field is invoked', () => {
+    field.interactable.wasInvokedThisFrame = true;
+    world.update();
+
+    expect(textInput.isEditing).toBe(true);
+    expect(document.activeElement).toBe(textInput.entry.element);
+  });
+
+  it('starts editing through editTextInput', () => {
+    editTextInput(world, field.entity);
+    world.update();
+
+    expect(textInput.isEditing).toBe(true);
+  });
+
+  it('does not start editing a field that is not interactable', () => {
+    field.interactable.interactable = false;
+    field.interactable.wasInvokedThisFrame = true;
+    world.update();
+
+    expect(textInput.isEditing).toBe(false);
+  });
+
+  it('submits on Enter with the value, ending editing', () => {
+    const listener = vi.fn();
+
+    field.onSubmit.registerListener(listener);
+    editTextInput(world, field.entity);
+    type('ab');
+    keyDown('Enter');
+    world.update();
+
+    expect(listener).toHaveBeenCalledWith('ab');
+    expect(textInput.isEditing).toBe(false);
+  });
+
+  it('cancels on Escape, keeping the value and ending editing', () => {
+    const listener = vi.fn();
+
+    field.onCancel.registerListener(listener);
+    editTextInput(world, field.entity);
+    type('ab');
+    keyDown('Escape');
+    world.update();
+
+    expect(listener).toHaveBeenCalledOnce();
+    expect(textInput.value).toBe('ab');
+    expect(textInput.isEditing).toBe(false);
+  });
+
+  it('keeps editing when UI focus moves elsewhere, and stops when the input loses focus', () => {
+    editTextInput(world, field.entity);
+    world.update();
+
+    field.interactable.isFocused = false;
+    field.interactable.isHovered = false;
+    world.update();
+
+    expect(textInput.isEditing).toBe(true);
+
+    textInput.entry.blur();
+    world.update();
+
+    expect(textInput.isEditing).toBe(false);
+  });
+
+  it('accepts a value set with setTextInputValue on the next tick, through the filters', () => {
+    const listener = vi.fn();
+
+    field.onValueChanged.registerListener(listener);
+    setTextInputValue(world, field.entity, 'hé');
+    world.update();
+
+    expect(textInput.value).toBe('h');
+    expect(listener).toHaveBeenCalledWith('h');
+  });
+
+  it('shows the placeholder only while the field is empty', () => {
+    world.update();
+
+    expect(world.getComponent(field.placeholderLabel, textId)!.enabled).toBe(
+      true,
+    );
+
+    type('a');
+    world.update();
+
+    expect(world.getComponent(field.placeholderLabel, textId)!.enabled).toBe(
+      false,
+    );
+  });
+
+  it('places the caret and selection from the text mesh caret stops', () => {
+    world.addComponent<TextMeshEcsComponent>(field.textLabel, textMeshId, {
+      glyphs: [],
+      bounds: { width: 30, height: 24 },
+      caretStops: [
+        { x: 0, y: 0 },
+        { x: 10, y: 0 },
+        { x: 20, y: 0 },
+        { x: 30, y: 0 },
+      ],
+      fillRenderable: {} as Renderable,
+      effectsRenderable: {} as Renderable,
+    });
+    editTextInput(world, field.entity);
+    type('abc');
+    textInput.entry.setSelection(2, 2);
+    world.update();
+
+    const caret = world.getComponent(textInput.caret, rectTransformId)!;
+
+    expect(caret.anchoredPosition).toEqual({ x: 20, y: -4 });
+    expect(world.getComponent(textInput.caret, spriteId)!.enabled).toBe(true);
+    expect(world.getComponent(textInput.selection, spriteId)!.enabled).toBe(
+      false,
+    );
+
+    textInput.entry.setSelection(1, 3);
+    world.update();
+
+    const selection = world.getComponent(textInput.selection, rectTransformId)!;
+
+    expect(selection.anchoredPosition.x).toBe(10);
+    expect(selection.x.kind === 'point' && selection.x.size).toBe(20);
+    expect(world.getComponent(textInput.selection, spriteId)!.enabled).toBe(
+      true,
+    );
+    expect(world.getComponent(textInput.caret, spriteId)!.enabled).toBe(false);
+  });
+
+  it('blinks the caret', () => {
+    editTextInput(world, field.entity);
+    world.update();
+
+    const caretSprite = world.getComponent(textInput.caret, spriteId)!;
+
+    expect(caretSprite.enabled).toBe(true);
+
+    for (let i = 0; i < 40; i++) {
+      world.update();
+    }
+
+    expect(caretSprite.enabled).toBe(false);
+  });
+
+  it('places the hidden input over the field in CSS pixels', () => {
+    world.update();
+
+    const { style } = textInput.entry.element;
+
+    expect(style.left).toBe('300px');
+    expect(style.top).toBe('280px');
+    expect(style.width).toBe('200px');
+    expect(style.height).toBe('40px');
+  });
+
+  it('focuses the field inside the tap that lands on it', () => {
+    world.update();
+
+    container.dispatchEvent(pointer('pointerdown', 400, 300));
+    container.dispatchEvent(pointer('pointerup', 400, 300));
+
+    expect(document.activeElement).toBe(textInput.entry.element);
+  });
+
+  it('does not let a press on the field take focus away from it', () => {
+    world.update();
+
+    const mouseDown = pointer('mousedown', 400, 300);
+
+    container.dispatchEvent(mouseDown);
+
+    expect(mouseDown.defaultPrevented).toBe(true);
+  });
+
+  it('does not focus the field for a drag that started elsewhere', () => {
+    world.update();
+
+    container.dispatchEvent(pointer('pointerdown', 10, 10));
+    container.dispatchEvent(pointer('pointerup', 400, 300));
+
+    expect(document.activeElement).not.toBe(textInput.entry.element);
+  });
+
+  it('does not focus a field covered by another element', () => {
+    const cover = world.createEntity();
+
+    addPositionComponent(world, cover);
+    addParentComponent(world, cover, { parent: canvasEntity });
+    addRectTransformComponent(world, cover, {
+      rect: { min: { x: -200, y: -200 }, max: { x: 200, y: 200 } },
+      sortDepth: 100,
+    });
+    addUiInteractableComponent(world, cover);
+    world.update();
+
+    container.dispatchEvent(pointer('pointerdown', 400, 300));
+    container.dispatchEvent(pointer('pointerup', 400, 300));
+
+    expect(document.activeElement).not.toBe(textInput.entry.element);
+  });
+
+  it("removes a field's hidden input with its component, and every input on cleanup", () => {
+    const other = createTextInput(world, canvasEntity, {
+      renderContext,
+      sprite: buildSprite(),
+      fillSprite: buildSprite(),
+      fontAtlas,
+      size: 20,
+    });
+
+    world.update();
+
+    const { element } = textInput.entry;
+
+    world.removeComponent(field.entity, textInputId);
+    world.update();
+
+    expect(element.isConnected).toBe(false);
+    expect(other.textInput.entry.element.isConnected).toBe(true);
+
+    world.stop();
+
+    expect(other.textInput.entry.element.isConnected).toBe(false);
+  });
+});
diff --git a/src/ui/systems/ui-text-input-system.ts b/src/ui/systems/ui-text-input-system.ts
new file mode 100644
index 000000000..0c089d71b
--- /dev/null
+++ b/src/ui/systems/ui-text-input-system.ts
@@ -0,0 +1,609 @@
+import { PositionEcsComponent, positionId, Time } from '../../common/index.js';
+import { EcsSystem } from '../../ecs/ecs-system.js';
+import { EcsWorld } from '../../ecs/ecs-world.js';
+import type { TextEntry } from '../../input/text-entry/text-entry.js';
+import { Vector2 } from '../../math/index.js';
+import {
+  CameraEcsComponent,
+  cameraId,
+  computeCameraView,
+  RenderContext,
+  SpriteEcsComponent,
+  spriteId,
+} from '../../rendering/index.js';
+import {
+  TextEcsComponent,
+  textId,
+  TextMeshEcsComponent,
+  textMeshId,
+} from '../../text/index.js';
+import {
+  CanvasEcsComponent,
+  canvasId,
+} from '../components/canvas-component.js';
+import {
+  RectTransformEcsComponent,
+  rectTransformId,
+} from '../components/rect-transform-component.js';
+import {
+  TextInputEcsComponent,
+  textInputId,
+} from '../components/text-input-component.js';
+import {
+  UiInteractableEcsComponent,
+  uiInteractableId,
+} from '../components/ui-interactable-component.js';
+import { uiCanvasRenderModes } from '../types/ui-canvas-render-mode.js';
+import { findOwningCanvas } from '../utilities/find-owning-canvas.js';
+import { raycastUiCanvas } from '../utilities/raycast-ui-canvas.js';
+import { resolveCanvasGroupState } from '../utilities/resolve-canvas-group-state.js';
+
+/** How long the caret stays visible, then hidden, in each blink. */
+const caretBlinkHalfPeriodMilliseconds = 530;
+
+const primaryButton = 0;
+
+/** What the caret was last drawn for, to restart its blink on any change. */
+interface CaretState {
+  text: string;
+  selectionStart: number;
+  selectionEnd: number;
+  isEditing: boolean;
+  elapsedMilliseconds: number;
+}
+
+/**
+ * Removes the characters `glyphs` has no glyph for, keeping spaces, so a
+ * field never holds a character the player can't see.
+ */
+function keepDrawableCharacters(
+  text: string,
+  glyphs: ReadonlyMap<number, unknown>,
+): string {
+  let kept = '';
+
+  for (const character of text) {
+    if (character === ' ' || glyphs.has(character.codePointAt(0) as number)) {
+      kept += character;
+    }
+  }
+
+  return kept;
+}
+
+/**
+ * Runs `text` through a field's filters: the font's glyphs, then the
+ * field's own `filter`, then `maxLength`.
+ */
+function filterText(
+  text: string,
+  textInput: TextInputEcsComponent,
+  glyphs: ReadonlyMap<number, unknown>,
+): string {
+  const drawable = keepDrawableCharacters(text, glyphs);
+  const filtered = textInput.filter ? textInput.filter(drawable) : drawable;
+
+  return Number.isFinite(textInput.maxLength)
+    ? filtered.slice(0, Math.max(0, textInput.maxLength))
+    : filtered;
+}
+
+/**
+ * Accepts the entry's text into `value` once it isn't mid-composition:
+ * filters it, writes the filtered text back to the entry (keeping the caret
+ * after the same characters) and raises `onValueChanged` if it changed.
+ */
+function mirrorValue(
+  textInput: TextInputEcsComponent,
+  glyphs: ReadonlyMap<number, unknown>,
+): void {
+  const { entry } = textInput;
+
+  if (entry.composition !== null || entry.value === textInput.value) {
+    return;
+  }
+
+  const filtered = filterText(entry.value, textInput, glyphs);
+
+  if (filtered !== entry.value) {
+    const caret = Math.min(
+      filterText(entry.value.slice(0, entry.selectionEnd), textInput, glyphs)
+        .length,
+      filtered.length,
+    );
+
+    entry.setValue(filtered);
+    entry.setSelection(caret, caret);
+  }
+
+  if (filtered === textInput.value) {
+    return;
+  }
+
+  textInput.value = filtered;
+  textInput.onValueChanged.raise(filtered);
+}
+
+function setSpriteEnabled(
+  world: EcsWorld,
+  entity: number,
+  enabled: boolean,
+): void {
+  const sprite = world.getComponent<SpriteEcsComponent>(entity, spriteId);
+
+  if (sprite) {
+    sprite.enabled = enabled;
+  }
+}
+
+/**
+ * Places one of a field's visual parts relative to the text's origin, and
+ * sizes it on whichever axes are given. The parts are children of a
+ * zero-size origin entity, so `anchoredPosition` is an offset from it.
+ */
+function placePart(
+  world: EcsWorld,
+  entity: number,
+  position: Vector2,
+  size: { x?: number; y?: number },
+): void {
+  const rectTransform = world.getComponent<RectTransformEcsComponent>(
+    entity,
+    rectTransformId,
+  );
+
+  if (!rectTransform) {
+    return;
+  }
+
+  rectTransform.anchoredPosition.x = position.x;
+  rectTransform.anchoredPosition.y = position.y;
+
+  if (size.x !== undefined && rectTransform.x.kind === 'point') {
+    rectTransform.x.size = size.x;
+  }
+
+  if (size.y !== undefined && rectTransform.y.kind === 'point') {
+    rectTransform.y.size = size.y;
+  }
+}
+
+/**
+ * Converts a field's resolved rect (its canvas's UI world space) to CSS
+ * pixels relative to the canvas, through the canvas's camera. `null` for a
+ * field not on a screen-space canvas, or whose camera can't give a view.
+ */
+function toCanvasCssRect(
+  world: EcsWorld,
+  entity: number,
+  rectTransform: RectTransformEcsComponent,
+  renderContext: RenderContext,
+): { left: number; top: number; width: number; height: number } | null {
+  const canvasEntity = findOwningCanvas(world, entity);
+  const canvas =
+    canvasEntity === null
+      ? null
+      : world.getComponent<CanvasEcsComponent>(canvasEntity, canvasId);
+
+  if (!canvas || canvas.renderMode !== uiCanvasRenderModes.screenSpace) {
+    return null;
+  }
+
+  const camera = world.getComponent<CameraEcsComponent>(
+    canvas.camera,
+    cameraId,
+  );
+  const cameraPosition = world.getComponent<PositionEcsComponent>(
+    canvas.camera,
+    positionId,
+  );
+
+  if (!camera || !cameraPosition) {
+    return null;
+  }
+
+  const view = computeCameraView(camera, cameraPosition, renderContext);
+  const { min, max } = rectTransform.rect;
+  const topLeft = view.worldToViewport({ x: min.x, y: max.y });
+  const bottomRight = view.worldToViewport({ x: max.x, y: min.y });
+
+  return {
+    left: topLeft.x,
+    top: topLeft.y,
+    width: bottomRight.x - topLeft.x,
+    height: bottomRight.y - topLeft.y,
+  };
+}
+
+/**
+ * Creates the system that runs every `TextInputEcsComponent`: it decides
+ * when a field is being edited, mirrors and filters its value, raises its
+ * events, keeps its hidden input over it on screen, and draws its text,
+ * placeholder, caret, selection and IME composition underline.
+ *
+ * **Editing.** A field is being edited exactly while its hidden input has
+ * focus. Editing starts when the field is invoked (a click, a tap, or the
+ * canvas's `submitInput` while it has UI focus) or through
+ * `editTextInput`, and ends on Enter (`onSubmit`), Escape (`onCancel`), or
+ * when the browser takes focus away (a click elsewhere, a phone's "Done"
+ * key, switching tabs). Hovering or navigating to another element doesn't
+ * end it. A field that isn't interactable (itself or through a canvas
+ * group) can't be edited.
+ *
+ * **Phone keyboards.** A phone only opens its keyboard when an input is
+ * focused inside a user gesture's event handler, and an ECS tick runs
+ * later. So the system listens for `pointerup` on the canvas's container
+ * and runs the UI's own hit test (`raycastUiCanvas`) right there: if the
+ * press and release both landed on the same field, and it's the only
+ * element hit on any canvas, its input is focused inside the gesture.
+ *
+ * **Value.** Outside an IME composition, the input's text is filtered
+ * (characters the field's font has no glyph for are dropped, then the
+ * field's `filter` runs, then `maxLength` applies), written back to the
+ * input if filtering changed it, and copied to `value`, raising
+ * `onValueChanged`. During a composition the uncommitted text is shown,
+ * underlined, but isn't part of `value`.
+ *
+ * **Visuals.** The caret and selection are placed from the text label's
+ * `TextMeshEcsComponent.caretStops`. Text shaping and layout run after
+ * this system, so they trail the typed text by a frame or two. The caret
+ * blinks, restarting whenever the text or selection changes.
+ *
+ * Fields on world-space canvases are edited and drawn the same way, but
+ * their hidden input isn't moved over them.
+ *
+ * Every field's input is removed when its component is, and all of them
+ * are removed in `cleanup`.
+ *
+ * Must be registered after `createUiNavigationEcsSystem` and
+ * `createUiInteractionEcsSystem` (it reads `wasInvokedThisFrame`), which
+ * `registerUiSystems` does.
+ * @param renderContext - The render context whose canvas the fields are
+ * drawn on. Its canvas's parent element receives the tap listeners.
+ * @param time - The time the caret blinks by. It uses unscaled time, so
+ * the caret blinks while the game is paused.
+ * @returns The UI text input ECS system.
+ */
+export const createUiTextInputEcsSystem = (
+  renderContext: RenderContext,
+  time: Time,
+): EcsSystem<
+  [TextInputEcsComponent, UiInteractableEcsComponent, RectTransformEcsComponent]
+> => {
+  const entries = new Map<TextInputEcsComponent, TextEntry>();
+  const caretStates = new WeakMap<TextInputEcsComponent, CaretState>();
+  let currentWorld: EcsWorld | null = null;
+  let container: HTMLElement | null = null;
+  let pressedField: number | null = null;
+
+  const toViewportPosition = (event: MouseEvent): Vector2 => {
+    const bounds = renderContext.canvas.getBoundingClientRect();
+
+    return { x: event.clientX - bounds.left, y: event.clientY - bounds.top };
+  };
+
+  const isEditable = (world: EcsWorld, entity: number): boolean => {
+    const interactable = world.getComponent<UiInteractableEcsComponent>(
+      entity,
+      uiInteractableId,
+    );
+
+    return (
+      !!interactable &&
+      interactable.interactable &&
+      resolveCanvasGroupState(world, entity).interactable
+    );
+  };
+
+  /**
+   * The text field under a pointer event, or `null`. Only counts when it's
+   * the single element hit across every canvas, so a field under an
+   * element on another canvas is never edited by mistake.
+   */
+  const findFieldAt = (event: MouseEvent): number | null => {
+    if (!currentWorld) {
+      return null;
+    }
+
+    const world = currentWorld;
+    const viewportPosition = toViewportPosition(event);
+    const hits: number[] = [];
+
+    for (const canvasEntity of world.query([canvasId]).entities) {
+      const hit = raycastUiCanvas(
+        world,
+        canvasEntity,
+        renderContext,
+        viewportPosition,
+      );
+
+      if (hit !== null) {
+        hits.push(hit);
+      }
+    }
+
+    if (hits.length !== 1) {
+      return null;
+    }
+
+    const [hit] = hits;
+
+    return world.getComponent(hit, textInputId) && isEditable(world, hit)
+      ? hit
+      : null;
+  };
+
+  const onPointerDown = (event: PointerEvent): void => {
+    pressedField = event.button === primaryButton ? findFieldAt(event) : null;
+  };
+
+  // Pressing anywhere that isn't focusable moves the browser's focus to the
+  // page, which would end editing for a moment when the player presses the
+  // field they're typing in. A pressed field keeps focus where it is
+  // instead; the release then focuses it.
+  const onMouseDown = (event: MouseEvent): void => {
+    if (findFieldAt(event) !== null) {
+      event.preventDefault();
+    }
+  };
+
+  const onPointerUp = (event: PointerEvent): void => {
+    const field = pressedField;
+
+    pressedField = null;
+
+    if (
+      !currentWorld ||
+      field === null ||
+      event.button !== primaryButton ||
+      findFieldAt(event) !== field
+    ) {
+      return;
+    }
+
+    currentWorld
+      .getComponentRequired<TextInputEcsComponent>(field, textInputId)
+      .entry.focus();
+  };
+
+  const listen = (): void => {
+    if (container) {
+      return;
+    }
+
+    container = renderContext.canvas.parentElement;
+    container?.addEventListener('pointerdown', onPointerDown);
+    container?.addEventListener('mousedown', onMouseDown);
+    container?.addEventListener('pointerup', onPointerUp);
+  };
+
+  const updateEditing = (
+    world: EcsWorld,
+    entity: number,
+    textInput: TextInputEcsComponent,
+    interactable: UiInteractableEcsComponent,
+  ): void => {
+    const { entry } = textInput;
+    const editable = isEditable(world, entity);
+
+    if (!editable && entry.isFocused) {
+      entry.blur();
+    }
+
+    if (editable && interactable.wasInvokedThisFrame && !entry.isFocused) {
+      entry.focus();
+    }
+  };
+
+  const updateVisuals = (
+    world: EcsWorld,
+    textInput: TextInputEcsComponent,
+  ): void => {
+    const { entry } = textInput;
+    const label = world.getComponentRequired<TextEcsComponent>(
+      textInput.textLabel,
+      textId,
+    );
+    const displayedText =
+      entry.composition === null ? textInput.value : entry.value;
+
+    label.text = displayedText;
+
+    const placeholder = world.getComponent<TextEcsComponent>(
+      textInput.placeholderLabel,
+      textId,
+    );
+
+    if (placeholder) {
+      placeholder.enabled = displayedText.length === 0;
+    }
+
+    const caretStops =
+      world.getComponent<TextMeshEcsComponent>(textInput.textLabel, textMeshId)
+        ?.caretStops ?? [];
+    const stopAt = (index: number): Vector2 =>
+      caretStops[Math.min(index, caretStops.length - 1)] ?? { x: 0, y: 0 };
+
+    const { ascender, descender } = label.fontAtlas.data.metrics;
+    const lineBottom = descender * label.size;
+    const lineHeight = (ascender - descender) * label.size;
+    const start = Math.min(entry.selectionStart, entry.selectionEnd);
+    const end = Math.max(entry.selectionStart, entry.selectionEnd);
+
+    const caretStop = stopAt(entry.selectionEnd);
+
+    placePart(
+      world,
+      textInput.caret,
+      { x: caretStop.x, y: caretStop.y + lineBottom },
+      { y: lineHeight },
+    );
+    setSpriteEnabled(
+      world,
+      textInput.caret,
+      textInput.isEditing &&
+        start === end &&
+        isCaretBlinkVisible(textInput, displayedText, start, end),
+    );
+
+    const selectionStart = stopAt(start);
+
+    placePart(
+      world,
+      textInput.selection,
+      { x: selectionStart.x, y: selectionStart.y + lineBottom },
+      { x: stopAt(end).x - selectionStart.x, y: lineHeight },
+    );
+    setSpriteEnabled(
+      world,
+      textInput.selection,
+      textInput.isEditing && start !== end,
+    );
+
+    const { composition } = entry;
+
+    if (composition !== null) {
+      const compositionStart = stopAt(composition.start);
+
+      placePart(
+        world,
+        textInput.compositionUnderline,
+        {
+          x: compositionStart.x,
+          y: compositionStart.y + lineBottom / 2,
+        },
+        { x: stopAt(composition.end).x - compositionStart.x },
+      );
+    }
+
+    setSpriteEnabled(
+      world,
+      textInput.compositionUnderline,
+      composition !== null,
+    );
+  };
+
+  /** Advances the caret's blink, restarting it when anything it's drawn for changed. */
+  const isCaretBlinkVisible = (
+    textInput: TextInputEcsComponent,
+    text: string,
+    selectionStart: number,
+    selectionEnd: number,
+  ): boolean => {
+    const previous = caretStates.get(textInput);
+    const unchanged =
+      previous &&
+      previous.text === text &&
+      previous.selectionStart === selectionStart &&
+      previous.selectionEnd === selectionEnd &&
+      previous.isEditing === textInput.isEditing;
+    const elapsedMilliseconds = unchanged
+      ? previous.elapsedMilliseconds + time.rawDeltaTimeInMilliseconds
+      : 0;
+
+    caretStates.set(textInput, {
+      text,
+      selectionStart,
+      selectionEnd,
+      isEditing: textInput.isEditing,
+      elapsedMilliseconds,
+    });
+
+    return (
+      elapsedMilliseconds % (caretBlinkHalfPeriodMilliseconds * 2) <
+      caretBlinkHalfPeriodMilliseconds
+    );
+  };
+
+  return {
+    name: 'uiTextInput',
+    query: [textInputId, uiInteractableId, rectTransformId],
+    update: (
+      world,
+      { entities, components: [textInputs, interactables, rectTransforms] },
+    ) => {
+      currentWorld = world;
+
+      const current = new Set<TextInputEcsComponent>();
+
+      if (entities.length > 0) {
+        listen();
+      }
+
+      for (let i = 0; i < entities.length; i++) {
+        const entity = entities[i];
+        const textInput = textInputs[i];
+        const { entry } = textInput;
+
+        current.add(textInput);
+        entries.set(textInput, entry);
+
+        entry.setAttributes({
+          ...textInput.attributes,
+          maxLength: textInput.maxLength,
+        });
+
+        updateEditing(world, entity, textInput, interactables[i]);
+
+        const events = entry.takeEvents();
+        const label = world.getComponentRequired<TextEcsComponent>(
+          textInput.textLabel,
+          textId,
+        );
+
+        mirrorValue(textInput, label.fontAtlas.data.glyphs);
+
+        if (events.submitted) {
+          entry.blur();
+          textInput.onSubmit.raise(textInput.value);
+        }
+
+        if (events.cancelled) {
+          entry.blur();
+          textInput.onCancel.raise();
+        }
+
+        textInput.isEditing = entry.isFocused;
+
+        const screenRect = toCanvasCssRect(
+          world,
+          entity,
+          rectTransforms[i],
+          renderContext,
+        );
+
+        if (screenRect) {
+          // The rect is relative to the canvas; the input is positioned in
+          // the canvas's container, which the entry made its offset parent.
+          entry.setScreenRect({
+            ...screenRect,
+            left: screenRect.left + renderContext.canvas.offsetLeft,
+            top: screenRect.top + renderContext.canvas.offsetTop,
+          });
+        }
+
+        updateVisuals(world, textInput);
+      }
+
+      for (const [textInput, entry] of entries) {
+        if (!current.has(textInput)) {
+          entry.dispose();
+          entries.delete(textInput);
+        }
+      }
+    },
+    cleanup: () => {
+      container?.removeEventListener('pointerdown', onPointerDown);
+      container?.removeEventListener('mousedown', onMouseDown);
+      container?.removeEventListener('pointerup', onPointerUp);
+      container = null;
+      currentWorld = null;
+
+      for (const entry of entries.values()) {
+        entry.dispose();
+      }
+
+      entries.clear();
+    },
+  };
+};
diff --git a/src/ui/utilities/create-text-input.test.ts b/src/ui/utilities/create-text-input.test.ts
new file mode 100644
index 000000000..edc780e88
--- /dev/null
+++ b/src/ui/utilities/create-text-input.test.ts
@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { createTextInput } from './create-text-input.js';
+import { parentId } from '../../common/index.js';
+import { EcsWorld } from '../../ecs/index.js';
+import {
+  Color,
+  Renderable,
+  RenderContext,
+  spriteId,
+} from '../../rendering/index.js';
+import type { FontAtlas } from '../../text/font-atlas/font-atlas.js';
+import { textId } from '../../text/index.js';
+import { uiColorTransitionId } from '../components/ui-color-transition-component.js';
+import { uiInteractableId } from '../components/ui-interactable-component.js';
+import { textInputId } from '../components/text-input-component.js';
+
+const fontAtlas = {
+  data: {
+    metrics: {
+      lineHeight: 1.2,
+      ascender: 0.8,
+      descender: -0.2,
+      capHeight: 0.7,
+    },
+    glyphs: new Map(),
+  },
+} as unknown as FontAtlas;
+
+const buildSprite = () => ({
+  width: 1,
+  height: 1,
+  renderable: {} as Renderable,
+  pivot: { x: 0.5, y: 0.5 },
+  tintColor: Color.white,
+  uvOffset: { x: 0, y: 0 },
+  uvScale: { x: 1, y: 1 },
+  enabled: true,
+  layer: 0,
+});
+
+describe('createTextInput', () => {
+  const container = document.createElement('div');
+  const canvas = document.createElement('canvas');
+
+  container.appendChild(canvas);
+
+  const renderContext = { canvas } as unknown as RenderContext;
+
+  afterEach(() => {
+    container.replaceChildren(canvas);
+  });
+
+  it('builds an interactable field with a text entry in the canvas container', () => {
+    const world = new EcsWorld();
+    const parent = world.createEntity();
+
+    const field = createTextInput(world, parent, {
+      renderContext,
+      sprite: buildSprite(),
+      fillSprite: buildSprite(),
+      fontAtlas,
+      size: 20,
+      value: 'hi',
+      placeholder: 'Name',
+      maxLength: 8,
+      attributes: { ariaLabel: 'Name' },
+    });
+
+    expect(world.getComponent(field.entity, parentId)).toEqual({ parent });
+    expect(world.getComponent(field.entity, uiInteractableId)).toBe(
+      field.interactable,
+    );
+    expect(
+      world.getComponent(field.entity, uiColorTransitionId),
+    ).not.toBeNull();
+    expect(world.getComponent(field.entity, textInputId)).toBe(field.textInput);
+
+    expect(field.textInput.value).toBe('hi');
+    expect(field.textInput.maxLength).toBe(8);
+    expect(field.textInput.attributes).toEqual({ ariaLabel: 'Name' });
+    expect(field.textInput.entry.element.parentElement).toBe(container);
+    expect(field.textInput.entry.value).toBe('hi');
+
+    expect(world.getComponent(field.textLabel, textId)!.text).toBe('hi');
+    expect(world.getComponent(field.placeholderLabel, textId)!.text).toBe(
+      'Name',
+    );
+    expect(world.getComponent(field.placeholderLabel, textId)!.enabled).toBe(
+      false,
+    );
+
+    for (const part of [
+      field.textInput.caret,
+      field.textInput.selection,
+      field.textInput.compositionUnderline,
+    ]) {
+      expect(world.getComponent(part, spriteId)!.enabled).toBe(false);
+    }
+  });
+
+  it('throws when the render context canvas has no parent element', () => {
+    const world = new EcsWorld();
+
+    expect(() =>
+      createTextInput(world, world.createEntity(), {
+        renderContext: {
+          canvas: document.createElement('canvas'),
+        } as unknown as RenderContext,
+        sprite: buildSprite(),
+        fillSprite: buildSprite(),
+        fontAtlas,
+        size: 20,
+      }),
+    ).toThrow(/no parent element/);
+  });
+});
diff --git a/src/ui/utilities/create-text-input.ts b/src/ui/utilities/create-text-input.ts
new file mode 100644
index 000000000..1db038b90
--- /dev/null
+++ b/src/ui/utilities/create-text-input.ts
@@ -0,0 +1,345 @@
+import {
+  addParentComponent,
+  addPositionComponent,
+} from '../../common/index.js';
+import { EcsWorld } from '../../ecs/ecs-world.js';
+import { ForgeEvent, ParameterizedForgeEvent } from '../../events/index.js';
+import { createTextEntry } from '../../input/text-entry/text-entry.js';
+import { Vector2 } from '../../math/index.js';
+import {
+  Color,
+  NineSliceOptions,
+  RenderContext,
+  SpriteEcsComponent,
+} from '../../rendering/index.js';
+import type { FontAtlas } from '../../text/font-atlas/font-atlas.js';
+import {
+  textHorizontalAlignments,
+  textVerticalAlignments,
+} from '../../text/index.js';
+import { addRectTransformComponent } from '../components/rect-transform-component.js';
+import {
+  addTextInputComponent,
+  TextInputAttributes,
+  TextInputEcsComponent,
+} from '../components/text-input-component.js';
+import {
+  addUiColorTransitionComponent,
+  UiColorTransitionDefaultedOptions,
+} from '../components/ui-color-transition-component.js';
+import {
+  addUiInteractableComponent,
+  UiInteractableDefaultedOptions,
+  UiInteractableEcsComponent,
+} from '../components/ui-interactable-component.js';
+import { UiAnchor, UiAnchorConfig } from '../types/ui-anchor.js';
+import { UiAxis } from '../types/ui-axis.js';
+import { createLabel } from './create-label.js';
+import { createPanel } from './create-panel.js';
+
+/**
+ * Fields of {@link CreateTextInputOptions} with no sensible default; callers
+ * must always provide these.
+ */
+export interface CreateTextInputRequiredOptions {
+  /**
+   * The render context the field is drawn with. The field's hidden input
+   * is added to its canvas's parent element (the game's container).
+   */
+  renderContext: RenderContext;
+
+  /** The sprite to draw the field's background with, e.g. from `createImageSprite`. */
+  sprite: SpriteEcsComponent;
+
+  /**
+   * A plain sprite (e.g. a white pixel) the caret, the selection highlight
+   * and the IME composition underline are drawn with, tinted by
+   * `caretColor` and `selectionColor`.
+   */
+  fillSprite: SpriteEcsComponent;
+
+  /** The loaded font atlas the text is drawn from. Characters it has no glyph for can't be typed. */
+  fontAtlas: FontAtlas;
+
+  /** The text's font size, in reference pixels. */
+  size: number;
+}
+
+/**
+ * Fields of {@link CreateTextInputOptions} with a sensible default, or that
+ * are genuinely optional; callers may omit these.
+ */
+export interface CreateTextInputDefaultedOptions {
+  /**
+   * The anchor to place the field with - see `UiAnchor` for common presets.
+   * Defaults to `UiAnchor.center({ x: 400, y: 64 })`.
+   */
+  anchor: UiAnchorConfig;
+
+  /** Offset of the field's pivot from its anchor reference point, in reference pixels. */
+  anchoredPosition?: Vector2;
+
+  /** Overrides `sprite.slices` for the background. */
+  slices?: NineSliceOptions;
+
+  /** Space between the field's left edge and its text, in reference pixels. Defaults to `16`. */
+  padding: number;
+
+  /** The field's initial text. Defaults to `''`. */
+  value: string;
+
+  /** The text shown while the field is empty. Defaults to `''`. */
+  placeholder: string;
+
+  /** The text's color. Defaults to `Color.black`. */
+  textColor: Color;
+
+  /** The placeholder's color. Defaults to a translucent gray. */
+  placeholderColor: Color;
+
+  /** The caret's and composition underline's color. Defaults to `Color.black`. */
+  caretColor: Color;
+
+  /** The selection highlight's color. Defaults to a translucent blue. */
+  selectionColor: Color;
+
+  /** The caret's width, in reference pixels. Defaults to `2`. */
+  caretWidth: number;
+
+  /**
+   * The render category the text and placeholder draw with (see
+   * `createLabel`'s `category`). Pass the value you gave the canvas's
+   * `cullingMask`.
+   */
+  category?: number;
+
+  /** See `TextInputDefaultedOptions.maxLength`. Defaults to no limit. */
+  maxLength?: number;
+
+  /** See `TextInputDefaultedOptions.filter`. */
+  filter?: (text: string) => string;
+
+  /** The hidden input's HTML attributes, e.g. `{ ariaLabel: 'Pilot name' }`. */
+  attributes?: TextInputAttributes;
+
+  /** Overrides for the field's `UiInteractableEcsComponent`. */
+  interactable?: Partial<UiInteractableDefaultedOptions>;
+
+  /** Overrides for the field's `UiColorTransitionEcsComponent` (its hover/pressed/disabled tints). */
+  transition?: Partial<UiColorTransitionDefaultedOptions>;
+}
+
+export type CreateTextInputOptions = CreateTextInputRequiredOptions &
+  Partial<CreateTextInputDefaultedOptions>;
+
+/** The entities and components {@link createTextInput} created. */
+export interface TextInput {
+  /** The field's root entity: background panel, `UiInteractableEcsComponent` and `TextInputEcsComponent`. */
+  entity: number;
+
+  /** The field's `TextInputEcsComponent`, for reading `value` and `isEditing`. */
+  textInput: TextInputEcsComponent;
+
+  /** The field's `UiInteractableEcsComponent`. */
+  interactable: UiInteractableEcsComponent;
+
+  /** The label the value is drawn with. */
+  textLabel: number;
+
+  /** The label shown while the field is empty. */
+  placeholderLabel: number;
+
+  /** `textInput.onValueChanged`. */
+  onValueChanged: ParameterizedForgeEvent<string>;
+
+  /** `textInput.onSubmit`. */
+  onSubmit: ParameterizedForgeEvent<string>;
+
+  /** `textInput.onCancel`. */
+  onCancel: ForgeEvent;
+}
+
+/** A zero-size point at the text origin, so a child's anchored position is an offset from it. */
+const originAnchor = (pivot: Vector2, size: Vector2): UiAnchorConfig => ({
+  x: UiAxis.point(0, { pivot: pivot.x, size: size.x }),
+  y: UiAxis.point(0, { pivot: pivot.y, size: size.y }),
+});
+
+/**
+ * Creates a single-line text field: a background panel (see `createPanel`)
+ * with a `UiInteractableEcsComponent` (so it's hoverable, focusable and
+ * reachable by navigation), a `UiColorTransitionEcsComponent` and a
+ * `TextInputEcsComponent`, plus child entities for the selection
+ * highlight, the text, the placeholder, the IME composition underline and
+ * the caret. The player types into a hidden DOM input the field owns;
+ * `createUiTextInputEcsSystem` (registered by `registerUiSystems`) does the
+ * rest.
+ *
+ * The text sits `padding` from the field's left edge, its baseline placed
+ * so the font's ascender-to-descender box is centered vertically. The field
+ * doesn't scroll or clip, so choose a `maxLength` whose longest value fits
+ * its width.
+ * @param world - The ECS world to create the field in.
+ * @param parent - The parent entity - a canvas (see `createUiCanvas`) or
+ * another UI element.
+ * @param options - Options for configuring the field. `renderContext`,
+ * `sprite`, `fillSprite`, `fontAtlas` and `size` must always be provided.
+ * @returns The created field.
+ * @throws An error if the render context's canvas isn't in the document.
+ */
+export function createTextInput(
+  world: EcsWorld,
+  parent: number,
+  options: CreateTextInputOptions,
+): TextInput {
+  // Built inside the function body since it references `Color`, which
+  // `rendering` and `ui`'s load-time import cycle may not have defined yet
+  // at this module's top level (see `createButton`).
+  const defaultCreateTextInputOptions = {
+    anchor: UiAnchor.center({ x: 400, y: 64 }),
+    padding: 16,
+    value: '',
+    placeholder: '',
+    textColor: Color.black,
+    placeholderColor: new Color(0, 0, 0, 0.45),
+    caretColor: Color.black,
+    selectionColor: new Color(0.25, 0.5, 1, 0.4),
+    caretWidth: 2,
+  };
+
+  const {
+    renderContext,
+    anchor,
+    anchoredPosition,
+    sprite,
+    slices,
+    fillSprite,
+    fontAtlas,
+    size,
+    padding,
+    value,
+    placeholder,
+    textColor,
+    placeholderColor,
+    caretColor,
+    selectionColor,
+    caretWidth,
+    category,
+    maxLength,
+    filter,
+    attributes,
+    interactable: interactableOptions,
+    transition: transitionOptions,
+  } = { ...defaultCreateTextInputOptions, ...options };
+
+  const container = renderContext.canvas.parentElement;
+
+  if (!container) {
+    throw new Error(
+      'Unable to create a text input: the render context canvas has no parent element to add its hidden input to.',
+    );
+  }
+
+  const entity = createPanel(world, parent, {
+    anchor,
+    ...(anchoredPosition && { anchoredPosition }),
+    sprite,
+    slices,
+  });
+
+  const interactable = addUiInteractableComponent(
+    world,
+    entity,
+    interactableOptions,
+  );
+
+  addUiColorTransitionComponent(world, entity, transitionOptions);
+
+  const { ascender, descender } = fontAtlas.data.metrics;
+  const lineHeight = (ascender - descender) * size;
+
+  const origin = world.createEntity();
+
+  addPositionComponent(world, origin);
+  addParentComponent(world, origin, { parent: entity });
+  addRectTransformComponent(world, origin, {
+    x: UiAxis.point(0, { pivot: 0, size: 0 }),
+    y: UiAxis.point(0.5, { size: 0 }),
+    anchoredPosition: { x: padding, y: (-(ascender + descender) / 2) * size },
+  });
+
+  const createFill = (
+    color: Color,
+    pivot: Vector2,
+    partSize: Vector2,
+  ): number => {
+    const part = createPanel(world, origin, {
+      anchor: originAnchor(pivot, partSize),
+      sprite: { ...fillSprite, tintColor: color, enabled: false },
+    });
+
+    return part;
+  };
+
+  const selection = createFill(
+    selectionColor,
+    { x: 0, y: 0 },
+    { x: 0, y: lineHeight },
+  );
+
+  const labelOptions = {
+    fontAtlas,
+    size,
+    anchor: originAnchor({ x: 0, y: 0 }, { x: 0, y: 0 }),
+    horizontalAlign: textHorizontalAlignments.left,
+    verticalAlign: textVerticalAlignments.baseline,
+    ...(category !== undefined && { category }),
+  };
+
+  const textLabel = createLabel(world, origin, {
+    ...labelOptions,
+    text: value,
+    color: textColor,
+  });
+  const placeholderLabel = createLabel(world, origin, {
+    ...labelOptions,
+    text: placeholder,
+    color: placeholderColor,
+    enabled: value.length === 0,
+  });
+
+  const compositionUnderline = createFill(
+    caretColor,
+    { x: 0, y: 0.5 },
+    { x: 0, y: caretWidth },
+  );
+  const caret = createFill(
+    caretColor,
+    { x: 0.5, y: 0 },
+    { x: caretWidth, y: lineHeight },
+  );
+
+  const textInput = addTextInputComponent(world, entity, {
+    entry: createTextEntry(container),
+    textLabel,
+    placeholderLabel,
+    caret,
+    selection,
+    compositionUnderline,
+    value,
+    ...(maxLength !== undefined && { maxLength }),
+    ...(filter && { filter }),
+    ...(attributes && { attributes }),
+  });
+
+  return {
+    entity,
+    textInput,
+    interactable,
+    textLabel,
+    placeholderLabel,
+    onValueChanged: textInput.onValueChanged,
+    onSubmit: textInput.onSubmit,
+    onCancel: textInput.onCancel,
+  };
+}
diff --git a/src/ui/utilities/index.ts b/src/ui/utilities/index.ts
index ad942a2e4..b99122137 100644
--- a/src/ui/utilities/index.ts
+++ b/src/ui/utilities/index.ts
@@ -4,10 +4,12 @@ export * from './create-label.js';
 export * from './create-panel.js';
 export * from './create-progress-bar.js';
 export * from './create-slider.js';
+export * from './create-text-input.js';
 export * from './create-toggle.js';
 export * from './create-tooltip.js';
 export * from './create-ui-canvas.js';
 export * from './find-owning-canvas.js';
+export * from './raycast-ui-canvas.js';
 export * from './register-ui-systems.js';
 export * from './resolve-canvas-group-state.js';
 export * from './resolve-canvas-pointer-position.js';
diff --git a/src/ui/utilities/raycast-ui-canvas.test.ts b/src/ui/utilities/raycast-ui-canvas.test.ts
new file mode 100644
index 000000000..130b95c62
--- /dev/null
+++ b/src/ui/utilities/raycast-ui-canvas.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import { raycastUiCanvas } from './raycast-ui-canvas.js';
+import {
+  addParentComponent,
+  addPositionComponent,
+} from '../../common/index.js';
+import { EcsWorld } from '../../ecs/index.js';
+import { addCameraComponent, RenderContext } from '../../rendering/index.js';
+import { addCanvasComponent } from '../components/canvas-component.js';
+import { addRectTransformComponent } from '../components/rect-transform-component.js';
+import { addUiInteractableComponent } from '../components/ui-interactable-component.js';
+
+const renderContext = {
+  width: 800,
+  height: 600,
+  cssWidth: 800,
+  cssHeight: 600,
+  pixelRatio: 1,
+} as RenderContext;
+
+function buildCanvas(world: EcsWorld): number {
+  const camera = world.createEntity();
+
+  addPositionComponent(world, camera);
+  addCameraComponent(world, camera, { verticalWorldUnits: 600 });
+
+  const canvas = world.createEntity();
+
+  addPositionComponent(world, canvas);
+  addRectTransformComponent(world, canvas);
+  addCanvasComponent(world, canvas, { camera });
+
+  return canvas;
+}
+
+function addElement(
+  world: EcsWorld,
+  canvas: number,
+  sortDepth: number,
+  blocksRaycasts = true,
+): number {
+  const entity = world.createEntity();
+
+  addPositionComponent(world, entity);
+  addParentComponent(world, entity, { parent: canvas });
+  addRectTransformComponent(world, entity, {
+    rect: { min: { x: -50, y: -50 }, max: { x: 50, y: 50 } },
+    sortDepth,
+  });
+  addUiInteractableComponent(world, entity, { blocksRaycasts });
+
+  return entity;
+}
+
+describe('raycastUiCanvas', () => {
+  it('returns the topmost raycast-blocking element under a viewport position', () => {
+    const world = new EcsWorld();
+    const canvas = buildCanvas(world);
+
+    addElement(world, canvas, 1);
+    const top = addElement(world, canvas, 2);
+
+    addElement(world, canvas, 3, false);
+
+    expect(
+      raycastUiCanvas(world, canvas, renderContext, { x: 400, y: 300 }),
+    ).toBe(top);
+    expect(
+      raycastUiCanvas(world, canvas, renderContext, { x: 10, y: 10 }),
+    ).toBeNull();
+  });
+
+  it("ignores another canvas's elements", () => {
+    const world = new EcsWorld();
+    const canvas = buildCanvas(world);
+    const otherCanvas = buildCanvas(world);
+
+    addElement(world, otherCanvas, 1);
+
+    expect(
+      raycastUiCanvas(world, canvas, renderContext, { x: 400, y: 300 }),
+    ).toBeNull();
+  });
+});
diff --git a/src/ui/utilities/raycast-ui-canvas.ts b/src/ui/utilities/raycast-ui-canvas.ts
new file mode 100644
index 000000000..b4945175e
--- /dev/null
+++ b/src/ui/utilities/raycast-ui-canvas.ts
@@ -0,0 +1,144 @@
+import { EcsWorld } from '../../ecs/ecs-world.js';
+import { Rects, Vector2 } from '../../math/index.js';
+import {
+  CameraEcsComponent,
+  cameraId,
+  RenderContext,
+  SpriteEcsComponent,
+  spriteId,
+} from '../../rendering/index.js';
+import { matchesMask } from '../../utilities/matches-mask.js';
+import {
+  CanvasEcsComponent,
+  canvasId,
+} from '../components/canvas-component.js';
+import {
+  RectTransformEcsComponent,
+  rectTransformId,
+} from '../components/rect-transform-component.js';
+import {
+  UiInteractableEcsComponent,
+  uiInteractableId,
+} from '../components/ui-interactable-component.js';
+import { findOwningCanvas } from './find-owning-canvas.js';
+import { resolveCanvasGroupState } from './resolve-canvas-group-state.js';
+import { resolveCanvasPointerPosition } from './resolve-canvas-pointer-position.js';
+
+/**
+ * Whether `camera` can actually see `entity` - `true` when `entity` has no
+ * `SpriteEcsComponent` (an invisible hit region has nothing to cull) or its
+ * `Renderable.category` matches the camera's `cullingMask`. An element
+ * culled from its canvas's camera must not be clickable either, or the UI
+ * develops invisible hit regions.
+ */
+function isVisibleToCamera(
+  world: EcsWorld,
+  entity: number,
+  camera: CameraEcsComponent | null,
+): boolean {
+  const sprite = world.getComponent<SpriteEcsComponent>(entity, spriteId);
+
+  if (!sprite) {
+    return true;
+  }
+
+  return (
+    !!camera && matchesMask(sprite.renderable.category, camera.cullingMask)
+  );
+}
+
+/**
+ * Finds the topmost `UiInteractableEcsComponent` on `canvasEntity`'s canvas
+ * under a pointer position: the canvas's interactables are scanned in
+ * reverse hierarchy order (topmost first, by
+ * `RectTransformEcsComponent.sortDepth`) for the first whose resolved
+ * `rect` contains the position - a linear reverse-depth scan: element
+ * counts here are in the hundreds, not the hundreds of thousands, so a
+ * plain scan is a few microseconds with no acceleration structure to build
+ * or invalidate. An element with `blocksRaycasts: false` is transparent to
+ * the scan (never considered, hit or not) - so is one with an ancestor
+ * `CanvasGroupEcsComponent` whose own `blocksRaycasts` is `false` (see
+ * `resolveCanvasGroupState`); an element culled from the canvas's camera
+ * by `cullingMask` is skipped the same way an invisible element shouldn't
+ * be clickable.
+ *
+ * `createUiRaycastEcsSystem` calls this once per canvas per tick. It's a
+ * plain function so code that has to react inside a DOM event handler
+ * (e.g. `createUiTextInputEcsSystem` focusing a text field during a tap, so
+ * a phone opens its keyboard) gets the same answer, occlusion included.
+ * Reads the rects `createUiLayoutEcsSystem` resolved on the last tick.
+ * @param world - The ECS world the canvas belongs to.
+ * @param canvasEntity - The canvas entity to hit-test.
+ * @param renderContext - The render context the canvas's camera renders
+ * through, used to convert the pointer position.
+ * @param viewportPosition - The pointer position, in CSS pixels from the
+ * canvas's top-left corner, Y-down.
+ * @returns The topmost hit entity, or `null` if nothing was hit (or the
+ * canvas's camera can't convert the position).
+ */
+export function raycastUiCanvas(
+  world: EcsWorld,
+  canvasEntity: number,
+  renderContext: RenderContext,
+  viewportPosition: Vector2,
+): number | null {
+  const canvas = world.getComponentRequired<CanvasEcsComponent>(
+    canvasEntity,
+    canvasId,
+  );
+  const pointerPosition = resolveCanvasPointerPosition(
+    world,
+    canvas,
+    renderContext,
+    viewportPosition,
+  );
+
+  if (!pointerPosition) {
+    return null;
+  }
+
+  const {
+    entities,
+    components: [interactables, rectTransforms],
+  } = world.query<[UiInteractableEcsComponent, RectTransformEcsComponent]>([
+    uiInteractableId,
+    rectTransformId,
+  ]);
+
+  const indices: number[] = [];
+
+  for (let i = 0; i < entities.length; i++) {
+    if (
+      interactables[i].blocksRaycasts &&
+      findOwningCanvas(world, entities[i]) === canvasEntity
+    ) {
+      indices.push(i);
+    }
+  }
+
+  indices.sort(
+    (a, b) => rectTransforms[b].sortDepth - rectTransforms[a].sortDepth,
+  );
+
+  const camera = world.getComponent<CameraEcsComponent>(
+    canvas.camera,
+    cameraId,
+  );
+
+  for (const index of indices) {
+    const entity = entities[index];
+
+    if (
+      !isVisibleToCamera(world, entity, camera) ||
+      !resolveCanvasGroupState(world, entity).blocksRaycasts
+    ) {
+      continue;
+    }
+
+    if (Rects.contains(rectTransforms[index].rect, pointerPosition)) {
+      return entity;
+    }
+  }
+
+  return null;
+}
diff --git a/src/ui/utilities/register-ui-systems.ts b/src/ui/utilities/register-ui-systems.ts
index d8da04ac1..511d58342 100644
--- a/src/ui/utilities/register-ui-systems.ts
+++ b/src/ui/utilities/register-ui-systems.ts
@@ -12,6 +12,7 @@ import { createUiProgressBarEcsSystem } from '../systems/ui-progress-bar-system.
 import { createUiRaycastEcsSystem } from '../systems/ui-raycast-system.js';
 import { createUiSafeAreaEcsSystem } from '../systems/ui-safe-area-system.js';
 import { createUiSliderEcsSystem } from '../systems/ui-slider-system.js';
+import { createUiTextInputEcsSystem } from '../systems/ui-text-input-system.js';
 import { createUiToggleEcsSystem } from '../systems/ui-toggle-system.js';
 import { createUiTooltipEcsSystem } from '../systems/ui-tooltip-system.js';
 import { createUiTransitionEcsSystem } from '../systems/ui-transition-system.js';
@@ -43,8 +44,8 @@ export interface RegisterUiSystemsOptions {
 
 /**
  * Registers every system a `createUiCanvas` canvas depends on: layout,
- * layout groups, aspect ratio fitting, progress bars, canvas groups, focus navigation, color transitions, toggles, and
- * tooltips - plus, once a
+ * layout groups, aspect ratio fitting, progress bars, canvas groups, focus navigation, color transitions, toggles,
+ * tooltips and text inputs - plus, once a
  * `pointerSource` is supplied, pointer raycasting/interaction/sliders, and
  * once `getSafeAreaInsets` is supplied, safe-area insetting - each wired in
  * the order their cross-system reads/writes require.
@@ -59,8 +60,8 @@ export interface RegisterUiSystemsOptions {
  * touch system registration.
  *
  * Registration order: raycast, then navigation, then interaction, then
- * toggle/transition/tooltip (order between those three doesn't matter, none
- * reads another's writes), then slider - raycast must run before navigation
+ * toggle/transition/tooltip/text input (order between those doesn't matter,
+ * none reads another's writes), then slider - raycast must run before navigation
  * and interaction read its hit-test result, interaction must run before
  * transition/tooltip read the interaction state it just wrote, navigation
  * must run before interaction because navigation is what resets
@@ -144,6 +145,10 @@ export function registerUiSystems(
 
   world.addSystem(tooltip, { after: [navigation] });
 
+  const textInput = createUiTextInputEcsSystem(renderContext, time);
+
+  world.addSystem(textInput, { after: [navigation] });
+
   if (pointerSource) {
     const raycast = createUiRaycastEcsSystem(pointerSource, renderContext);
 
@@ -156,7 +161,7 @@ export function registerUiSystems(
 
     world.addSystem(interaction, {
       after: [navigation, raycast],
-      before: [transition, toggle, tooltip],
+      before: [transition, toggle, tooltip, textInput],
     });
 
     const slider = createUiSliderEcsSystem(pointerSource, renderContext);
diff --git a/src/ui/utilities/resolve-canvas-pointer-position.test.ts b/src/ui/utilities/resolve-canvas-pointer-position.test.ts
index d9491d834..89dd0321d 100644
--- a/src/ui/utilities/resolve-canvas-pointer-position.test.ts
+++ b/src/ui/utilities/resolve-canvas-pointer-position.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { resolveCanvasPointerPosition } from './resolve-canvas-pointer-position.js';
 import { addPositionComponent } from '../../common/index.js';
 import { EcsWorld } from '../../ecs/index.js';
-import { MouseInputSource } from '../../input/index.js';
+import { Vector2 } from '../../math/index.js';
 import { addCameraComponent, RenderContext } from '../../rendering/index.js';
 import { addCanvasComponent } from '../components/canvas-component.js';
 import { addRectTransformComponent } from '../components/rect-transform-component.js';
@@ -16,8 +16,7 @@ const buildRenderContext = (width: number, height: number): RenderContext =>
     pixelRatio: 1,
   }) as RenderContext;
 
-const buildMouseInputSource = (x: number, y: number): MouseInputSource =>
-  ({ position: { x, y } }) as MouseInputSource;
+const buildViewportPosition = (x: number, y: number): Vector2 => ({ x, y });
 
 describe('resolveCanvasPointerPosition', () => {
   it('converts the pointer position into the canvas camera UI world space', () => {
@@ -38,7 +37,7 @@ describe('resolveCanvasPointerPosition', () => {
       world,
       canvas,
       renderContext,
-      buildMouseInputSource(960, 540),
+      buildViewportPosition(960, 540),
     );
 
     expect(center).toEqual({ x: 0, y: 0 });
@@ -49,7 +48,7 @@ describe('resolveCanvasPointerPosition', () => {
       world,
       canvas,
       renderContext,
-      buildMouseInputSource(0, 0),
+      buildViewportPosition(0, 0),
     );
 
     expect(topLeft).toEqual({ x: -960, y: 540 });
@@ -82,7 +81,7 @@ describe('resolveCanvasPointerPosition', () => {
         world,
         canvas,
         renderContext,
-        buildMouseInputSource(480, 270),
+        buildViewportPosition(480, 270),
       ),
     ).toEqual({ x: 0, y: 0 });
     expect(
@@ -90,7 +89,7 @@ describe('resolveCanvasPointerPosition', () => {
         world,
         canvas,
         renderContext,
-        buildMouseInputSource(0, 0),
+        buildViewportPosition(0, 0),
       ),
     ).toEqual({ x: -960, y: 540 });
   });
@@ -110,7 +109,7 @@ describe('resolveCanvasPointerPosition', () => {
       world,
       canvas,
       renderContext,
-      buildMouseInputSource(0, 0),
+      buildViewportPosition(0, 0),
     );
 
     expect(result).toBeNull();
diff --git a/src/ui/utilities/resolve-canvas-pointer-position.ts b/src/ui/utilities/resolve-canvas-pointer-position.ts
index 3379bafc5..e97f0eb70 100644
--- a/src/ui/utilities/resolve-canvas-pointer-position.ts
+++ b/src/ui/utilities/resolve-canvas-pointer-position.ts
@@ -8,10 +8,10 @@ import {
   RenderContext,
 } from '../../rendering/index.js';
 import { CanvasEcsComponent } from '../components/canvas-component.js';
-import { UiPointerSource } from '../types/ui-pointer-source.js';
 
 /**
- * Converts a pointer's current position - CSS pixels, Y-down - into
+ * Converts a pointer position - CSS pixels from the canvas's top-left
+ * corner, Y-down, e.g. `UiPointerSource.position` - into
  * `canvas`'s own UI world space, through its dedicated camera. Two canvases
  * with different cameras (e.g. different `verticalWorldUnits`) convert the
  * same pointer position differently, which is why this takes a specific
@@ -20,8 +20,8 @@ import { UiPointerSource } from '../types/ui-pointer-source.js';
  * @param canvas - The canvas to convert the pointer position for.
  * @param renderContext - The render context the canvas's camera renders
  * through.
- * @param pointerSource - The pointer source to read the canvas-space
- * position from.
+ * @param viewportPosition - The pointer position, in CSS pixels from the
+ * canvas's top-left corner, Y-down.
  * @returns The pointer position in `canvas`'s UI world space, or `null` if
  * the canvas's camera entity is missing its `CameraEcsComponent`/
  * `PositionEcsComponent`.
@@ -30,7 +30,7 @@ export function resolveCanvasPointerPosition(
   world: EcsWorld,
   canvas: CanvasEcsComponent,
   renderContext: RenderContext,
-  pointerSource: UiPointerSource,
+  viewportPosition: Vector2,
 ): Vector2 | null {
   const camera = world.getComponent<CameraEcsComponent>(
     canvas.camera,
@@ -46,5 +46,5 @@ export function resolveCanvasPointerPosition(
     camera,
     cameraPosition,
     renderContext,
-  ).viewportToWorld(pointerSource.position);
+  ).viewportToWorld(viewportPosition);
 }

From d28a84d40cf562338b6f7a9f6cd52f02d92a1913 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 6 Oct 2026 21:57:51 +0000
Subject: [PATCH 2/4] feat(ui): document, demo and e2e-test text input fields

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014VktGvQk7RUMN8yxuAUXER
---
 AGENTS.md                                     |   4 +-
 CHANGELOG.md                                  |   9 +
 design/input-action-state.md                  |   2 +-
 design/text-input-field.md                    | 591 ------------------
 design/ui-system.md                           |  90 +--
 .../docs/docs/input/keyboard.md               |  10 +-
 .../docs/docs/input/text-entry.md             |  78 +++
 documentation-site/docs/docs/ui/index.md      |   2 +
 documentation-site/docs/docs/ui/text-input.md | 186 ++++++
 documentation-site/src/data/demos.ts          |   7 +
 .../pages/demos/ui-text-input/_create-game.ts | 351 +++++++++++
 .../src/pages/demos/ui-text-input/index.tsx   |  54 ++
 e2e/fixtures/scenes/ui-text-input.ts          | 287 +++++++++
 e2e/specs/ui-text-input.spec.ts               | 157 +++++
 src/ui/components/text-input-component.ts     |   4 +-
 src/ui/systems/ui-text-input-system.ts        |   8 +-
 16 files changed, 1195 insertions(+), 645 deletions(-)
 delete mode 100644 design/text-input-field.md
 create mode 100644 documentation-site/docs/docs/input/text-entry.md
 create mode 100644 documentation-site/docs/docs/ui/text-input.md
 create mode 100644 documentation-site/src/pages/demos/ui-text-input/_create-game.ts
 create mode 100644 documentation-site/src/pages/demos/ui-text-input/index.tsx
 create mode 100644 e2e/fixtures/scenes/ui-text-input.ts
 create mode 100644 e2e/specs/ui-text-input.spec.ts

diff --git a/AGENTS.md b/AGENTS.md
index 35b5ca242..d990df736 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -105,7 +105,7 @@ this step by step for bug fixes.
   /ecs                     # Entity-Component-System core
   /events                  # Event system
   /finite-state-machine    # FSM implementation
-  /input                   # Input handling
+  /input                   # Input handling (keyboard, mouse, gamepad, hidden-DOM text entry)
   /lifecycle               # Lifecycle management
   /math                    # Math utilities
   /particles               # Particle system
@@ -115,7 +115,7 @@ this step by step for bug fixes.
   /states                  # Game states (createGameState), inState/onEnter/onExit run conditions, state-scoped entities
   /text                    # MSDF font atlas loading and text rendering
   /timer                   # Timer utilities
-  /ui                      # Retained-mode UI (anchored rect tree layout, canvases, panels, labels, buttons, focus navigation, toggles, sliders, progress bars, dropdowns, layout groups, content size/aspect ratio fitters)
+  /ui                      # Retained-mode UI (anchored rect tree layout, canvases, panels, labels, buttons, focus navigation, toggles, sliders, progress bars, dropdowns, text inputs, layout groups, content size/aspect ratio fitters)
   /utilities               # General utilities
   index.ts                 # Main exports
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 80243f9ea..116d62992 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **states:** New `@forge-game-engine/forge/states` module for a game's top-level states (menu, playing, paused, game over). `createGameState(world, initial)` returns a `GameState` whose `set` switches state at the start of the next tick. Its `exitGroup` and `enterGroup` run once per transition, before any other system, holding systems that use `onExit`/`onEnter` as their `runIf`; `inState` runs a system only in some states. The initial state is entered on the first tick, and setting the current state again restarts it. `addStateScopedComponent` removes an entity when its state leaves one of `removeOnExit` or enters one of `removeOnEnter`. See the new Game States guide and demo
 - **rendering:** `getCameraView(world, camera, renderContext)` (and `computeCameraView(camera, position, renderContext)` for systems that already hold the camera's components) returns what a camera sees: the world area it shows (`bounds`, `size`, accounting for its position and zoom), its `pixelsPerUnit` in CSS pixels, and `worldToViewport`/`viewportToWorld` conversions to and from CSS pixels on the canvas. To place something drawn by one camera over something drawn by another, convert through the viewport: `hudView.viewportToWorld(gameView.worldToViewport(position))`
 - **text:** The engine's default font can be imported through a bundler from `@forge-game-engine/forge/fonts/default/default.json` and `@forge-game-engine/forge/fonts/default/default.png`, so you no longer need to copy it out of `node_modules`
+- **ui:** Text input fields. `createTextInput(world, parent, { renderContext, sprite, fillSprite, fontAtlas, size })` builds a single-line field the player types into through a hidden DOM `<input>`, so keyboard layouts, IME composition, paste, phone keyboards and screen readers work. Its `TextInputEcsComponent` holds the filtered `value` (characters the font can't draw are dropped, then an optional `filter` and `maxLength` apply), `isEditing`, and `onValueChanged`/`onSubmit`/`onCancel` events; `setTextInputValue` and `editTextInput` change it from code. Editing is separate from UI focus: it starts on a click, a tap (focusing inside the tap, so phone keyboards open) or `submitInput` while focused, and ends on Enter, Escape or blur. `registerUiSystems` registers the new `createUiTextInputEcsSystem`
+- **input:** `createTextEntry(container)` creates the hidden-input primitive text fields are built on, for game-drawn text that isn't a UI field (a chat box, a debug console): it exposes the value, selection and IME composition, and reports Enter/Escape/changes/blur through `takeEvents()`
+- **text:** `shapeText` returns `caretStops`, the position of every UTF-16 boundary in the shaped text (whitespace and missing glyphs included), and `TextMeshEcsComponent.caretStops` carries them
+- **ui:** `raycastUiCanvas(world, canvasEntity, renderContext, viewportPosition)` returns the topmost interactable under a pointer position on a canvas, the same hit test `createUiRaycastEcsSystem` runs each tick
 
 #### Changed
 
@@ -36,6 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **rendering:** `createProjectionMatrix` now takes the world-space `Rect` to show, such as `getCameraView(...).bounds`, instead of `(width, height, cameraPosition, zoom, pixelsPerUnit)`
 - **ui:** A `'screenPixels'`-unit size or margin, and `UiSafeAreaEcsComponent` insets, now follow the canvas camera's `zoom`, so they keep their on-screen size on a world-space canvas whose camera zooms. A screen-space canvas's root rect now fills its camera's view, so it follows a moved or zoomed UI camera
 - **text:** `FontAtlasCache.getOrLoad` takes the URL of both atlas files, `getOrLoad({ metricsUrl, imageUrl })`, instead of finding the image next to the JSON, so atlases imported through Vite, webpack or another bundler that renames files now load. Pass the URLs your bundler gives you for the `.json` and `.png` (with Vite, `import metricsUrl from './my-font.json?url'` and `import imageUrl from './my-font.png'`), and look loaded atlases up with `get(metricsUrl)`. `getOrLoad` rejects if the image's size doesn't match the JSON's `atlasSize`, or if one `metricsUrl` is requested with two different image URLs. Concurrent calls for the same atlas now share one load. `FontAtlasCache` no longer implements `AssetCache` and its `load` method and `assets` map are no longer public; call `getOrLoad` instead. `FontAtlasData` and `FontAtlasFileData` no longer have an `atlasImage` field and `forge-generate-font-atlas` no longer writes one; existing JSON files that have it still load
+- **ui:** `resolveCanvasPointerPosition` takes the pointer's viewport position (CSS pixels, Y-down) as its last argument instead of a `UiPointerSource`. Pass `pointerSource.position`
 
 #### Removed
 
@@ -43,6 +48,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **rendering:** `calculateVisibleWorldSize`, `calculatePixelsPerUnit`, `screenToWorldSpace`, `worldToScreenSpace` and `canvasToWorldSpace` are removed; use the camera's view instead. `calculateVisibleWorldSize(width, height, verticalWorldUnits)` becomes `getCameraView(world, camera, renderContext).size`, which also accounts for zoom; `screenToWorldSpace(pointer, ...)` becomes `view.viewportToWorld(pointer)`; `worldToScreenSpace(...)` becomes `view.worldToViewport(position)`, which unlike the old function flips Y to the Y-down viewport; `calculatePixelsPerUnit(...)` becomes `view.pixelsPerUnit`. Constants that mirrored a camera's `verticalWorldUnits` for these calls can be deleted
 - **rendering:** `CameraEcsComponent.scissorRect`, which nothing read, is removed
 
+#### Fixed
+
+- **input:** `KeyboardInputSource` ignores keys typed into an editable element (`<input>`, `<textarea>`, `<select>`, `contentEditable`, including inside a shadow root): they don't count as held and don't dispatch bindings, and a release of a key it never saw go down is ignored. Typing into an HTML form next to the game no longer moves the player, while a key held before typing started is still released. `KeyboardInputSource` no longer implements `Resettable` (its `reset()` only cleared unused state), so remove any `inputManager.addResettable(keyboardInputSource)` call
+
 ## [0.25.8] - 2026-10-03
 
 #### Fixed
diff --git a/design/input-action-state.md b/design/input-action-state.md
index 00cda14b7..735507333 100644
--- a/design/input-action-state.md
+++ b/design/input-action-state.md
@@ -6,7 +6,7 @@
 | **Kind**                              | Defect                                                                                                                                              |
 | **Found in**                          | Galactic Journey demo: `src/input/create-inputs.ts` (three `actionResetTypes.noReset` axes), `src/run/run-input.system.ts` (`shootInput.endHold()`) |
 | **Engine version at time of writing** | `0.25.8`                                                                                                                                            |
-| **Related**                           | [`text-input-field.md`](./text-input-field.md) (keyboard source changes)                                                                            |
+| **Related**                           | the text input field, which made the keyboard source ignore keys typed into editable elements                                                       |
 
 ## 0. Targeted modules
 
diff --git a/design/text-input-field.md b/design/text-input-field.md
deleted file mode 100644
index 83cca1aa0..000000000
--- a/design/text-input-field.md
+++ /dev/null
@@ -1,591 +0,0 @@
-# Design: Text Input Field
-
-|                                       |                                                                                                                                                                                                                                                                                                                          |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Status**                            | Draft, for review                                                                                                                                                                                                                                                                                                        |
-| **Kind**                              | Missing feature                                                                                                                                                                                                                                                                                                          |
-| **Found in**                          | Galactic Journey demo: `src/ui/create-text-input.ts`, `src/ui/text-input.component.ts`, `src/ui/text-input.system.ts`, `src/game-over/pilot-panel*.ts`                                                                                                                                                                   |
-| **Engine version at time of writing** | `0.25.8`                                                                                                                                                                                                                                                                                                                 |
-| **Related**                           | [#586](https://github.com/Forge-Game-Engine/Forge/issues/586) (this design answers its open questions), `ui-system.md` DL-10, [#583](https://github.com/Forge-Game-Engine/Forge/issues/583) (clipping), [`input-action-state.md`](./input-action-state.md), [`hierarchical-visibility.md`](./hierarchical-visibility.md) |
-
-## 0. Targeted modules
-
-| Path                                                        | Change   | Notes                                                                                                      |
-| ----------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
-| `src/input/text-entry/text-entry.ts`                        | **New**  | `createTextEntry`: one hidden DOM `<input>` (value, selection, composition, focus, keyboard and IME rules) |
-| `src/input/keyboard/input-sources/keyboard-input-source.ts` | Modified | Keys pressed in an editable element never count as held; their releases are ignored                        |
-| `src/ui/components/text-input-component.ts`                 | **New**  | `TextInputEcsComponent`: a field's settings, its value and editing state (outputs) and its events          |
-| `src/ui/systems/ui-text-input-system.ts`                    | **New**  | Owns each field's text entry: editing state, placement, value mirroring, caret and selection visuals       |
-| `src/ui/systems/ui-raycast-system.ts`                       | Modified | Its hit test becomes a function the tap handler can call synchronously                                     |
-| `src/ui/utilities/create-text-input.ts`                     | **New**  | `createTextInput`: background panel, text, placeholder, caret and selection entities in one call           |
-| `src/ui/utilities/register-ui-systems.ts`                   | Modified | Registers the text input system in the UI pipeline                                                         |
-| `src/text/utilities/shape-text.ts`                          | Modified | Also returns caret stops: the final position of every character boundary, whitespace included              |
-| `src/text/components/text-mesh-component.ts`                | Modified | `TextMeshEcsComponent.caretStops`, written by the shaping system                                           |
-| `documentation-site/docs/docs/ui/text-input.md`             | **New**  | Guide                                                                                                      |
-| `documentation-site/src/pages/demos/ui-text-input/`         | **New**  | Demo page (a name entry form)                                                                              |
-
----
-
-## 1. Summary
-
-Forge has no way to type text. The demo needed one for its flight log
-("BADGE NUMBER" and "PILOT NAME" entry) and built it from scratch, around
-200 lines across three files:
-
-- a hidden, 1-pixel, transparent DOM `<input>` appended to `document.body`
-  to receive the typing, so keyboard layouts, paste and phone keyboards
-  work;
-- `stopPropagation` on its `keydown`, because Forge's
-  `KeyboardInputSource` listens on the window, and every key typed would
-  otherwise also move UI focus or press the focused button (Enter) or
-  back out of the menu (Escape);
-- deliberately _not_ stopping `keyup`, so a key held down before typing
-  started is still released in the game;
-- a set of keys pressed since activation, so a key already held when the
-  field activated (Enter, from pressing the menu button that opened it)
-  doesn't auto-repeat into it and submit at once;
-- a document-wide `click` listener that re-focuses the input, because
-  clicking a button blurs it, and because a phone's keyboard only opens
-  from a focus inside a tap;
-- an ECS component that copies the DOM events into per-tick signals
-  (`isChanged`, `isSubmitted`, `isCancelled`, `isKeyPressed`) so systems
-  read them once each, in any order;
-- a system that sanitizes what was typed (the font atlas has printable
-  ASCII only, and Forge silently drops missing glyphs), and draws the value
-  with a blinking `_` caret appended as a character, because there is no
-  caret rendering.
-
-The approach is the one `ui-system.md` already chose in DL-10 and split
-out as [#586](https://github.com/Forge-Game-Engine/Forge/issues/586): a
-hidden DOM input for the hard parts (IME, soft keyboards, clipboard,
-accessibility), Forge rendering for the visible field. This design fills
-in #586 using what the demo learned, in two layers:
-
-1. **`/src/input`: a text entry primitive.** It owns one hidden input
-   positioned over a screen rectangle, exposes its value, selection and
-   IME composition as data, and enforces the keyboard rules above. The
-   keyboard input source stops treating keys typed into an editable
-   element as game input.
-2. **`/src/ui`: a text input field.** A UI element with its own text entry
-   and an editing state that's separate from UI focus. It mirrors its
-   entry's value, draws a real caret and selection from the shaped text,
-   filters characters the font can't draw, and raises submit, cancel and
-   change events.
-
----
-
-## 2. Scope
-
-### In scope
-
-- Single-line text fields on screen-space UI canvases.
-- The DOM bridge: creation inside the game's container, positioning over
-  the field's screen rect (so phone keyboards and IME candidate windows
-  appear next to it), attributes (`aria-label`, `inputmode`,
-  `autocomplete`, `autocapitalize`, `enterkeyhint`, `maxlength`), focus,
-  blur, removal on cleanup.
-- Keyboard rules: typed keys aren't game input; keys held before editing
-  don't auto-repeat into the field; releases of keys the game saw go down
-  always reach the game.
-- IME rules: committing or cancelling a composition doesn't submit or
-  cancel the field, and the value isn't rewritten mid-composition.
-- An editing state separate from UI focus (§5.2).
-- Starting to edit from a tap synchronously, inside the browser's gesture
-  handler, so phone keyboards open (§5.4).
-- Value, caret and selection rendering, including IME composition
-  (underlined while composing).
-- Character filtering: the field's font must have a glyph for each
-  character (always), plus an optional game-supplied filter.
-- `onValueChanged`, `onSubmit`, `onCancel` events.
-
-### Out of scope
-
-- **Multi-line fields** (`<textarea>`). Enter, caret movement and wrapping
-  differ; designed later on the same primitive.
-- **Scrolling a value wider than its field.** Needs per-sprite clipping
-  ([#583](https://github.com/Forge-Game-Engine/Forge/issues/583)). Until
-  then `maxLength` and the field's width have to agree; the guide says
-  so.
-- **Password masking**, rich text, and on-screen keyboards for gamepads
-  (consoles provide their own; browsers don't).
-- **Tab between fields.** Leaving a field is Escape or Enter (as in the
-  demo); Tab does nothing inside a field. Tab order needs a way to ask
-  the navigation system to move focus, which it doesn't have (open
-  question 2).
-- **World-space canvases.** The same conversion through the canvas's
-  camera would place the element; they're left out only because a field
-  in a moving world keeps the DOM element chasing it every frame, and
-  nothing needs it yet.
-
----
-
-## 3. Background
-
-### 3.1 Why typing can't be built from `KeyboardInputSource`
-
-`ui-system.md` DL-10 and #586 already record this: IME composition,
-phone keyboards (which only open on a focused DOM element), clipboard,
-autocorrect and screen-reader access are all things browsers do for a
-real `<input>`, and would each be a project to rebuild over raw key
-events. The demo confirms the choice: its hidden input handled a phone's
-keyboard and paste with no extra code.
-
-### 3.2 What the engine gets wrong around a DOM input today
-
-`KeyboardInputSource` (`src/input/keyboard/input-sources/keyboard-input-source.ts`)
-listens for `keydown`/`keyup` on `globalThis` and dispatches every key to
-the bindings, whatever element the key was typed into. Any game embedded
-in a page with a form has the same problem the demo worked around: typing
-in a text box moves the player. Browsers bubble a key typed into an input
-up to the window, so the source has to look at where the key was typed.
-
-### 3.3 The demo's lessons, kept as requirements
-
-| Demo behavior                                            | Why it matters                                                                                      |
-| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| Key presses typed into the field don't reach the game    | Enter would press the focused button; Escape would close the menu; arrows would move focus          |
-| Key releases always reach the game                       | A movement key held while the field opened would otherwise stay held forever                        |
-| Keys held at activation don't auto-repeat into the field | The Enter that opened the panel would otherwise auto-repeat and submit it immediately               |
-| Refocus inside a click handler                           | A phone keyboard only opens from `focus()` called during a user gesture                             |
-| Signals moved into the component once per tick           | DOM events arrive between ticks; systems must each see them once, in any order                      |
-| Sanitize to the font's characters                        | Forge silently skips missing glyphs; a name with "é" would be stored with a letter nobody could see |
-| UI focus stays on the submit button while typing         | The player types, then presses the focused button; focus and typing are different things            |
-
----
-
-## 4. How established engines handle this
-
-- **Browser engines** (PixiJS, Phaser plugins): an `<input>` positioned
-  over the canvas, made transparent, with the game drawing the visible
-  text. This is the approach DL-10 already chose. Godot's web export does
-  the same for phone keyboards (a hidden input next to the canvas whose
-  `input` events forward the value and selection).
-- **Unity** (`TMP_InputField`): a selectable UI element with a caret and
-  selection drawn by the UI, `characterValidation`/`onValidateInput` for
-  filtering, `characterLimit`, and `onSubmit`/`onEndEdit`/`onValueChanged`
-  events. On mobile it opens the platform keyboard
-  (`TouchScreenKeyboard`) when selected. Unity can treat selection as
-  editing because its selection doesn't follow the pointer's hover.
-- **Godot** (`LineEdit`): since 4.4, editing is separate from focus:
-  `edit()`, `unedit()`, `is_editing()` and an `editing_toggled` signal.
-  Keyboard focus alone doesn't start editing; a click or the accept
-  action does. `max_length`, `text_changed`/`text_submitted` signals, IME
-  support through the display server. A focused `LineEdit` stops key
-  events from reaching `_unhandled_input`, but polled input
-  (`Input.is_action_pressed`) still sees keys typed into it.
-- **Bevy**: 0.19 added a built-in editable text widget (`EditableText`);
-  before that, community crates followed the same pattern (focusable node,
-  events, IME through `winit`).
-
-The common shape: the field is an ordinary UI element; while editing it
-consumes key input; it validates characters; it reports change and submit
-as events; the platform's own text machinery does the typing. Forge's
-actions are polled, so ignoring typed keys at the keyboard source is
-stricter than Godot's `accept_event`, and that's what the demo needs.
-
----
-
-## 5. Design
-
-### 5.1 Layer 1: the text entry primitive (`/src/input`)
-
-```ts
-interface TextEntry {
-  /** The current text, as the DOM input holds it. */
-  readonly value: string;
-  /** Selection (equal when it's just a caret), in UTF-16 code units. */
-  readonly selectionStart: number;
-  readonly selectionEnd: number;
-  /** The IME composition range, if the player is composing. */
-  readonly composition: { start: number; end: number } | null;
-  readonly isFocused: boolean;
-
-  /** Replaces the text (for clearing or prefilling the field). */
-  setValue(value: string): void;
-  /** Places the hidden element over a rect in CSS pixels, Y down, relative to the container. */
-  setScreenRect(rect: CssRect): void;
-  setAttributes(attributes: TextEntryAttributes): void;
-  focus(): void;
-  blur(): void;
-
-  /** Events since the last `takeEvents()`; the UI system drains these once per tick. */
-  takeEvents(): TextEntryEvents;
-  dispose(): void;
-}
-
-/** A DOM rectangle: CSS pixels, origin top-left, Y down. */
-interface CssRect {
-  left: number;
-  top: number;
-  width: number;
-  height: number;
-}
-
-interface TextEntryEvents {
-  changed: boolean;
-  submitted: boolean; // Enter, outside a composition
-  cancelled: boolean; // Escape, outside a composition
-  blurred: boolean; // the browser took focus away (a click elsewhere, a phone's "Done", a tab switch)
-}
-
-function createTextEntry(container: HTMLElement): TextEntry;
-```
-
-`CssRect` is deliberately not Forge's `Rect`, which is Y-up world space.
-
-Rules the primitive enforces:
-
-- **Placement.** The `<input>` is appended to the game's container (not
-  `document.body`) and absolutely positioned over `setScreenRect`'s rect,
-  with transparent text, caret, border and background, and
-  `pointer-events: none` (taps go through the UI's hit test, §5.4). Forge
-  doesn't position the container today, so the primitive makes it a
-  positioning context (`position: relative` if it's `static`). Being over
-  the field, rather than at the page's corner, is what makes a phone
-  scroll the field into view above its keyboard and puts an IME candidate
-  window next to the text.
-- **Held keys don't repeat in.** The primitive records which keys went
-  down while it was focused. A repeating `keydown` for any other key is
-  cancelled (`preventDefault`), which is exactly the demo's
-  `keysPressedHere` rule.
-- **Enter and Escape** are cancelled (no form submission, no browser
-  behavior) and recorded as `submitted`/`cancelled`, except during an IME
-  composition (`event.isComposing`, or key code 229): there, Enter commits
-  the composition and Escape cancels it, and neither ends editing. A
-  repeating Enter doesn't submit twice.
-- **Tab** is cancelled (§2).
-- **Composition.** The primitive doesn't change the value while a
-  composition is in progress; rewriting it would end the composition. The
-  UI system filters on `compositionend` instead (§5.2).
-- **Blur** is recorded as an event, so the field knows editing ended.
-- Events accumulate between ticks and are drained by `takeEvents()`.
-
-`KeyboardInputSource` gains one rule, which applies whether or not a
-Forge text field exists, stated in terms of the source's own state so it
-holds before or after [`input-action-state.md`](./input-action-state.md):
-
-> A key whose `keydown` targets an editable element (`<input>`,
-> `<textarea>`, `<select>`, or `isContentEditable`) never enters the
-> source's set of held keys. A `keyup` for a key that isn't in that set is
-> ignored: nothing is reported, and no up-moment trigger fires.
-
-The target is read from `event.composedPath()[0]`, since at the window
-`event.target` is the shadow host for elements inside a shadow
-root. That's the demo's `stopPropagation` and "releases still reach
-the game" logic as a general rule, so it also fixes games embedded next to
-HTML forms. The source's unused `_keyPressesDown`/`_keyPressesUps` sets go
-in the same change.
-
-### 5.2 Layer 2: the field (`/src/ui`)
-
-```ts
-interface TextInputEcsComponent {
-  /** The current text. Written by the text input system only. */
-  readonly value: string;
-  /** Whether the field is being typed into. Written by the text input system only. */
-  readonly isEditing: boolean;
-  /** Shown, in the placeholder's color, while `value` is empty. */
-  placeholder: string;
-  maxLength: number;
-  /**
-   * Transforms what was typed before it's accepted, e.g. upper-casing a
-   * code or dropping leading spaces. Runs after the font filter.
-   */
-  filter?: (text: string) => string;
-  attributes: TextEntryAttributes; // aria-label, inputmode, autocapitalize...
-  readonly onValueChanged: ParameterizedForgeEvent<string>;
-  readonly onSubmit: ParameterizedForgeEvent<string>;
-  readonly onCancel: ForgeEvent;
-}
-
-/** Replaces a field's text; the value updates on the next tick. */
-function setTextInputValue(world: EcsWorld, field: Entity, value: string): void;
-/** Starts editing a field (e.g. when its panel opens), as a tap would. */
-function editTextInput(world: EcsWorld, field: Entity): void;
-```
-
-`createTextInput(world, parent, options)` builds the field from existing
-parts, the way `createButton` does: a panel for the background, a label
-for the text (and one for the placeholder), a thin panel for the caret
-and one behind the text for the selection highlight, and a
-`UiInteractableEcsComponent` so the field is hoverable, focusable and
-reachable by navigation.
-
-**Editing is separate from focus.** Forge's UI focus follows the pointer's
-hover and controller navigation, and games set it themselves (the demo
-keeps it on its submit button while the player types). Tying typing to
-focus would start typing whenever the pointer crossed a field, and stop
-it when the pointer moved to the submit button. So, as in Godot 4.4, the
-field has its own editing state, owned by the text input system:
-
-- **Starts** on a tap or click on the field (§5.4), on the canvas's
-  `submitInput` while the field has UI focus (a controller's A, Enter
-  from navigation), or through `editTextInput`.
-- **Ends** on Enter (`onSubmit`), Escape (`onCancel`), or the browser
-  blurring the input (a tap elsewhere, a phone's "Done" key, switching
-  tabs).
-- UI focus can be anywhere meanwhile. At most one field per page is
-  editing, since only one DOM element has focus.
-
-`createUiTextInputEcsSystem` owns each field's text entry (one per field,
-created when the field's component appears and disposed when it's removed
-or in the system's `cleanup`; the container is the render context's
-canvas parent):
-
-1. **Editing.** Applies the rules above, focusing and blurring the entry,
-   and writes `isEditing`.
-2. **Placement.** Every tick, the editing field's resolved rect is
-   converted from UI world space to a `CssRect` through the canvas's
-   camera (the inverse of `resolveCanvasPointerPosition`, through the camera
-   view's `worldToViewport`).
-3. **Value.** On `changed` outside a composition (or on `compositionend`),
-   the entry's value is run through the font filter (drop characters the
-   field's `FontAtlas` has no glyph for), then `filter`, then `maxLength`;
-   if the result differs, it's written back with `setValue` (the caret is
-   kept at the same logical position). The component's `value` is
-   updated and `onValueChanged` raised.
-4. **Submit/cancel.** Raised from the drained events, with the value.
-5. **Visuals.** The caret and selection are placed from the shaped
-   text's caret stops (below). The caret blinks, restarting on every
-   change. The selection highlight spans the stops between
-   `selectionStart` and `selectionEnd`. Composed IME text is underlined.
-
-`ui-system.md` DL-10 expected `TextMeshEcsComponent.glyphs` to be enough
-for caret placement. It isn't: a `GlyphQuad` doesn't record which
-character it came from, and whitespace and missing glyphs produce no quad
-at all, so there's nothing to place a caret after a trailing space. So
-`shapeText` also returns **caret stops**: for every UTF-16 boundary from
-`0` to `text.length`, the final x and baseline y. They're computed at the
-end of shaping, after pivot, alignment, justification and the vertical
-offset are applied, because pen positions during shaping are relative to
-each word and whitespace runs are advanced as a block. Shaping walks code
-points while DOM selection indices are UTF-16, so the boundary inside a
-surrogate pair gets the position of the pair's start.
-`TextMeshEcsComponent.caretStops` carries them, written by the shaping
-system like the rest of the mesh.
-
-Because the DOM input holds the text, the component's `value` has one
-writer: the system. Game code that wants to change it calls
-`setTextInputValue`, which writes the field's own DOM input, and the value
-comes back through step 3 like typed text. One entry per field is what
-makes that work for a field that isn't being edited.
-
-### 5.3 Navigation while typing
-
-While a field is editing, keys typed into it are ignored by the keyboard
-source (§5.1), so the canvas's keyboard-bound `navigateInput` and
-`submitInput` don't fire. Enter submits the field and Escape cancels it,
-both ending editing. Gamepad navigation still works, since the gamepad
-source isn't affected: a controller user can move UI focus off the field
-while typing on a physical keyboard, and editing continues until it's
-submitted, cancelled or blurred.
-
-### 5.4 Phone keyboards and the gesture rule
-
-Browsers only open a phone's keyboard when `focus()` is called during a
-user gesture (a `touchend`/`click` handler). An ECS tick runs later, from
-`requestAnimationFrame`, so focusing from the system works on desktop but
-not on phones.
-
-So the text input system listens for `pointerup` on the container and,
-inside the handler, runs the UI's hit test synchronously. The raycast
-system's hit test (topmost interactable at a point, respecting
-`blocksRaycasts`, canvas groups and draw order) becomes a function that
-both the raycast system and this handler call, so a tap on a modal that
-covers a field doesn't start editing the field underneath. If the topmost
-hit is a field, its entry is focused right there, inside the gesture, and
-the field starts editing on the next tick. Each field's entry already has
-its value and attributes (`inputmode`, `autocapitalize`, `enterkeyhint`,
-`maxlength`), which phone keyboards read at focus time.
-
-### 5.5 Character filtering
-
-Shaping silently skips characters with no glyph (`shapeText` documents
-this as a content problem, not an error). For a text field, that would
-mean storing characters the player can't see. So a field accepts only the
-characters its font atlas has a glyph for (and the space character), by
-default and always. The demo's `sanitizeName` keeps only its second rule
-(no leading spaces) as its `filter`; its badge sanitizer (upper-casing and
-an alphabet) stays a game filter.
-
-### 5.6 Accessibility
-
-The hidden input is a real, labelled form control (`aria-label` from the
-field's attributes), so screen readers announce the field and what's
-typed into it. This is the one part of canvas UI that gets screen-reader
-access for free; the wider problem is
-[#634](https://github.com/Forge-Game-Engine/Forge/issues/634).
-
----
-
-## 6. Phases
-
-### Phase 1: Keyboard input stops reading typed keys
-
-| #   | Task                                                                                                                                          | Size |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
-| 1.1 | `KeyboardInputSource`: keys pressed in editable elements (via `composedPath()`) never held; their releases ignored; unused press sets deleted | S    |
-| 1.2 | Unit tests with keydown/keyup events targeting an `<input>`, including one in a shadow root                                                   | S    |
-| 1.3 | Changelog under `#### Fixed`                                                                                                                  | S    |
-
-**Definition of done:** typing into any HTML input next to (or over) the
-game doesn't trigger game actions, and keys held before typing are still
-released. Useful on its own for games embedded in pages with forms.
-
-### Phase 2: Text entry primitive and the UI field
-
-| #   | Task                                                                                                                                                           | Size |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
-| 2.1 | `createTextEntry`: element in the container, positioning context, placement, attributes, events (blur included), held-key, IME and Enter/Escape rules, dispose | M    |
-| 2.2 | The raycast hit test as a shared function; synchronous tap-to-edit (§5.4)                                                                                      | M    |
-| 2.3 | `TextInputEcsComponent`, `setTextInputValue`, `editTextInput`, `createTextInput`                                                                               | M    |
-| 2.4 | `createUiTextInputEcsSystem`: one entry per field, editing state, placement, value mirroring, font filter, events                                              | L    |
-| 2.5 | `shapeText` caret stops (final positions, UTF-16) and `TextMeshEcsComponent.caretStops`; caret, selection and composition rendering                            | M    |
-| 2.6 | Unit tests (jsdom `<input>`), e2e: typing, Enter submits, Escape cancels, typed keys don't move UI focus, hovering another element doesn't end editing         | M    |
-| 2.7 | Guide `ui/text-input.md`, docs-site demo, changelog under `#### Added`                                                                                         | M    |
-
-**Definition of done:** the demo's pilot panel can be rebuilt with two
-`createTextInput` fields and no DOM code of its own (its inactivity
-countdown resets on `onValueChanged` and submit instead of on any key); a
-phone opens its keyboard when a field is tapped; IME input works.
-
-### Phase 3 (future): long values and multi-line
-
-Horizontal scrolling of a value wider than the field (needs #583's
-clipping) and a `<textarea>`-backed multi-line field. Listed so Phase 2's
-component shape leaves room for them.
-
----
-
-## 7. Decision log
-
-### DL-1: Two layers, split between `/src/input` and `/src/ui`
-
-**Decision.** Keep #586's split: the DOM bridge in `/src/input`, the field
-in `/src/ui`.
-
-**Rationale.** The bridge is reusable (a debug console, a chat box drawn
-by the game itself) and keeps all DOM access out of the UI module, which
-restores the UI module's "no DOM-backed widgets" invariant recorded in
-`ui-system.md`.
-
-### DL-2: The keyboard source ignores keys typed into editable elements
-
-**Options.** (a) Each text field stops propagation of its own key events
-(the demo). (b) The keyboard source ignores `keydown` events targeting
-editable elements.
-
-**Decision: (b).**
-
-**Rationale.** It fixes the layer that owns the behavior: "is this key
-game input?" is the keyboard source's question. (a) needs every
-DOM-based widget, including ones outside Forge, to cooperate.
-
-### DL-3: The DOM input is the source of truth for the text
-
-**Options.** (a) The component's `value` is writable and the system syncs
-it to the DOM. (b) The DOM holds the text; the component mirrors it, and
-game code changes it through `setTextInputValue`.
-
-**Decision: (b).**
-
-**Rationale.** With (a), the game and the system both write `value`, and
-a write on the same tick as a keystroke loses one of them. (b) has one
-writer per value. The DOM must hold the text anyway, since that's where
-IME and the selection live, and with one entry per field every field's
-text is in the DOM, whether or not it's being edited.
-
-### DL-4: Filter to the font's glyphs by default, without an option
-
-**Options.** (a) Accept anything and let shaping skip what it can't draw.
-(b) Drop characters the font can't draw, always. (c) An option to choose.
-
-**Decision: (b).**
-
-**Rationale.** A field that stores characters the player can't see is
-never what a game wants. Games that need wider coverage generate an atlas
-with a wider charset (`forge-generate-font-atlas --charset`). No option,
-because no game wants (a).
-
-### DL-5: Editing is separate from UI focus
-
-**Options.** (a) A focused field is being typed into (Unity). (b) Editing
-is its own state, started by a tap, a submit or code, and ended by
-submit, cancel or blur (Godot 4.4).
-
-**Decision: (b).**
-
-**Rationale.** Forge's focus follows hover, so (a) would start and stop
-typing as the pointer moves. (b) also lets a game keep UI focus on a
-button while the player types, as the demo does. The alternative would be
-to remove hover-follows-focus from the UI, which is a larger change to
-the UI's design than this feature justifies.
-
-### DL-6: One text entry per field
-
-**Options.** (a) One entry per canvas, rebound to the field being edited.
-(b) One entry per field.
-
-**Decision: (b).**
-
-**Rationale.** A field's value, attributes and selection live in its DOM
-input (DL-3), and a phone keyboard reads the attributes at focus time, so
-a shared entry would have to swap all of them inside the tap handler and
-would leave fields that aren't being edited with nowhere to keep their
-text. One hidden input per field is a few DOM nodes per screen.
-
-### DL-7: Tap-to-edit runs the UI's own hit test
-
-**Rationale.** It's the only way phone keyboards open (§5.4). Calling the
-raycast's hit test, rather than testing field rects, keeps occlusion
-(modals, `blocksRaycasts`, canvas groups) identical to every other
-pointer interaction.
-
----
-
-## 8. Open questions
-
-1. **Should hover still set UI focus?** DL-5 keeps it. If the team would
-   rather focus mean "selected" (Unity's model), editing could follow
-   focus, but hover-follows-focus would have to go for every UI element.
-   - (a) Keep hover focus; editing is separate (proposed). (b) Remove
-     hover focus from the UI and let editing follow focus.
-2. **Tab between fields.** Needs a way for the field to ask the navigation
-   system to move focus, and probably an explicit tab order, since Forge
-   navigation is spatial.
-   - (a) Leave it out (proposed). (b) Add a navigation request and tab
-     order first.
-3. **Selection by pointer drag inside the field.** The hidden input has
-   `pointer-events: none`, so drags don't reach it. Forwarding them would
-   make selection-by-mouse work.
-   - (a) Phase 2 supports keyboard selection only (proposed). (b) Forward
-     pointer drags to the input in Phase 2.
-
----
-
-## 9. Testing considerations
-
-- Unit (jsdom): `KeyboardInputSource` with events dispatched on an
-  `<input>` (and one inside a shadow root) versus on `window`; the
-  held-key repeat rule; Enter and Escape during a composition; blur as an
-  event; `takeEvents` draining; filter order (font, then game filter,
-  then length), and no filtering mid-composition.
-- Unit (system): editing starts on submit while focused and through
-  `editTextInput`; hovering another element doesn't end it; blur does;
-  entries are disposed with their fields.
-- e2e: real keyboard typing into a field via Playwright
-  (`page.keyboard.type`), asserting the rendered value changed (relative
-  pixel check, per the `write-e2e-test` skill), that UI focus didn't move
-  while typing arrows, and that Enter submits once even when held; a tap
-  on a panel covering a field doesn't start editing it.
-
-## 10. Documentation and demo follow-up
-
-- New guide `ui/text-input.md`: creating a field, editing versus focus,
-  filters, events, the phone keyboard rule, the `maxLength`/width caveat
-  until clipping lands.
-- Update `input/keyboard.md`: keys typed into HTML inputs aren't game
-  input.
-- Demo: `create-text-input.ts`, `text-input.component.ts` and
-  `text-input.system.ts` are deleted; the pilot panel creates two fields,
-  listens to their events, and keeps its UI focus on the submit button.
diff --git a/design/ui-system.md b/design/ui-system.md
index 73c26faa6..7a89c64bc 100644
--- a/design/ui-system.md
+++ b/design/ui-system.md
@@ -1,11 +1,11 @@
 # Design: Forge UI System
 
-|                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Status**                            | In progress — Phase 0 (prerequisites), Phase 1 (layout core: `RectTransformEcsComponent`, `resolveRect`, `UiAnchor`, `CanvasEcsComponent`/`createUiCanvas`, `createUiLayoutEcsSystem`, `createPanel`/`createLabel`), Phase 2 (interaction: `UiInteractableEcsComponent`, `createUiRaycastEcsSystem`, `createUiInteractionEcsSystem`, `UiFocusEcsComponent`/`createUiNavigationEcsSystem`, `createButton`, `UiColorTransitionEcsComponent`/`createUiTransitionEcsSystem`), most of Phase 3 (controls: `UiToggleEcsComponent`/`UiToggleGroupEcsComponent`/`createUiToggleEcsSystem`/`createToggle`, `UiSliderEcsComponent`/`createUiSliderEcsSystem`/`createSlider`, `UiProgressBarEcsComponent`/`createUiProgressBarEcsSystem`/`createProgressBar`, `UiDropdownEcsComponent`/`createDropdown`), and all of Phase 4 (layout groups: `LayoutElementEcsComponent`, `createUiLayoutGroupEcsSystem`, horizontal/vertical/grid layout groups, `ContentSizeFitterEcsComponent`, `AspectRatioFitterEcsComponent` - [#622](https://github.com/Forge-Game-Engine/Forge/pull/622) - plus the column-aligned form layout extras: `LayoutElementEcsComponent.sizeToText` and `GridLayoutGroupEcsComponent.columnWidthMode`/`rowHeightMode`/`cellAlignment` - [#630](https://github.com/Forge-Game-Engine/Forge/pull/630)) have landed on `dev`, documented at `documentation-site/docs/docs/ui`. [#631](https://github.com/Forge-Game-Engine/Forge/pull/631) subsequently replaced `RectTransformEcsComponent`'s `anchorMin`/`anchorMax`/`pivot`/`sizeOrMargin` fields with typed per-axis `UiAxis` (`x`/`y`, each a `UiPointAxis` or `UiStretchAxis` built via `UiAxis.point`/`UiAxis.stretch`) and `UiAnchor`'s presets with factory functions taking the size/margin their own axes need - a breaking change; §6's API sketch and the examples below reflect the current shape. Phase 5 (polish) is in progress - see the backlog table in §8 for per-item status. Backlog 3.3 (`RectMaskEcsComponent`) and 3.5 (`TextInputEcsComponent`) remain out of scope per the table below; 3.4 (`ScrollRectEcsComponent`) remains blocked on rect clipping; radial fill (part of backlog 3.7) was deferred alongside clipping - see that item's note. Two of the three external dependencies have landed: text rendering ([#584](https://github.com/Forge-Game-Engine/Forge/issues/584)) and the sprite pivot convention ([#585](https://github.com/Forge-Game-Engine/Forge/issues/585)). Rect clipping ([#583](https://github.com/Forge-Game-Engine/Forge/issues/583)) and text input ([#586](https://github.com/Forge-Game-Engine/Forge/issues/586)) remain open, and continue to block only `ScrollRectEcsComponent`/`TextInputEcsComponent` (backlog 3.4/3.5). |
-| **Target module**                     | `/src/ui` → `@forge-game-engine/forge/ui`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| **Engine version at time of writing** | `0.24.2`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| **Model**                             | Retained **anchored rect tree** (canvas → rect transforms → graphics + event routing) — _not_ immediate-mode, _not_ markup-and-stylesheet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+|                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Status**                            | In progress — Phase 0 (prerequisites), Phase 1 (layout core: `RectTransformEcsComponent`, `resolveRect`, `UiAnchor`, `CanvasEcsComponent`/`createUiCanvas`, `createUiLayoutEcsSystem`, `createPanel`/`createLabel`), Phase 2 (interaction: `UiInteractableEcsComponent`, `createUiRaycastEcsSystem`, `createUiInteractionEcsSystem`, `UiFocusEcsComponent`/`createUiNavigationEcsSystem`, `createButton`, `UiColorTransitionEcsComponent`/`createUiTransitionEcsSystem`), most of Phase 3 (controls: `UiToggleEcsComponent`/`UiToggleGroupEcsComponent`/`createUiToggleEcsSystem`/`createToggle`, `UiSliderEcsComponent`/`createUiSliderEcsSystem`/`createSlider`, `UiProgressBarEcsComponent`/`createUiProgressBarEcsSystem`/`createProgressBar`, `UiDropdownEcsComponent`/`createDropdown`), and all of Phase 4 (layout groups: `LayoutElementEcsComponent`, `createUiLayoutGroupEcsSystem`, horizontal/vertical/grid layout groups, `ContentSizeFitterEcsComponent`, `AspectRatioFitterEcsComponent` - [#622](https://github.com/Forge-Game-Engine/Forge/pull/622) - plus the column-aligned form layout extras: `LayoutElementEcsComponent.sizeToText` and `GridLayoutGroupEcsComponent.columnWidthMode`/`rowHeightMode`/`cellAlignment` - [#630](https://github.com/Forge-Game-Engine/Forge/pull/630)) have landed on `dev`, documented at `documentation-site/docs/docs/ui`. [#631](https://github.com/Forge-Game-Engine/Forge/pull/631) subsequently replaced `RectTransformEcsComponent`'s `anchorMin`/`anchorMax`/`pivot`/`sizeOrMargin` fields with typed per-axis `UiAxis` (`x`/`y`, each a `UiPointAxis` or `UiStretchAxis` built via `UiAxis.point`/`UiAxis.stretch`) and `UiAnchor`'s presets with factory functions taking the size/margin their own axes need - a breaking change; §6's API sketch and the examples below reflect the current shape. Phase 5 (polish) is in progress - see the backlog table in §8 for per-item status. Backlog 3.3 (`RectMaskEcsComponent`) remains out of scope per the table below; 3.5 (`TextInputEcsComponent`) has landed; 3.4 (`ScrollRectEcsComponent`) remains blocked on rect clipping; radial fill (part of backlog 3.7) was deferred alongside clipping - see that item's note. Two of the three external dependencies have landed: text rendering ([#584](https://github.com/Forge-Game-Engine/Forge/issues/584)) and the sprite pivot convention ([#585](https://github.com/Forge-Game-Engine/Forge/issues/585)). Text input ([#586](https://github.com/Forge-Game-Engine/Forge/issues/586)) has landed too. Rect clipping ([#583](https://github.com/Forge-Game-Engine/Forge/issues/583)) remains open, and continues to block only `ScrollRectEcsComponent` (backlog 3.4). |
+| **Target module**                     | `/src/ui` → `@forge-game-engine/forge/ui`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **Engine version at time of writing** | `0.24.2`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| **Model**                             | Retained **anchored rect tree** (canvas → rect transforms → graphics + event routing) — _not_ immediate-mode, _not_ markup-and-stylesheet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 ---
 
@@ -158,7 +158,7 @@ data.
 | Off-screen targets & compositing | `RenderTarget`, `createPresentEcsSystem`, camera `layer`  | Lets UI skip the world's post-processing stack.                                                                                                                                                                                                                                                                                                     |
 | Action-based input with groups   | `InputManager`, `TriggerAction`, `HoldAction`             | Group gating (`activeGroup`) is the natural "menu open, game paused" switch. `CameraEcsComponent.zoomInput`/`panInput` are the precedent for a component taking `InputAction`s rather than raw input — the UI canvas follows it (DL-14).                                                                                                            |
 | Tweening + easing                | `createAnimationEcsSystem`, `easing-functions/`           | Button press/hover transitions get this for free.                                                                                                                                                                                                                                                                                                   |
-| Events                           | `ForgeEvent`, `ParameterizedForgeEvent`                   | The idiom for `onInvoke`.                                                                                                                                                                                                                                                                                                                         |
+| Events                           | `ForgeEvent`, `ParameterizedForgeEvent`                   | The idiom for `onInvoke`.                                                                                                                                                                                                                                                                                                                           |
 
 ### 4.2 The gaps
 
@@ -618,8 +618,14 @@ export type UiAxis = UiPointAxis | UiStretchAxis;
 
 // Build one with the `UiAxis.point`/`UiAxis.stretch` factories, not a raw object literal.
 export const UiAxis = {
-  point: (anchor: number, options?: { size?: number; pivot?: number }): UiPointAxis => ({/* ... */}),
-  stretch: (range: { min: number; max: number }, options?: { margin?: number; pivot?: number }): UiStretchAxis => ({/* ... */}),
+  point: (
+    anchor: number,
+    options?: { size?: number; pivot?: number },
+  ): UiPointAxis => ({/* ... */}),
+  stretch: (
+    range: { min: number; max: number },
+    options?: { margin?: number; pivot?: number },
+  ): UiStretchAxis => ({/* ... */}),
 };
 
 export interface RectTransformDefaultedOptions {
@@ -716,9 +722,7 @@ const playButton = createButton(world, panel, {
   preferredHeight: 64,
 });
 
-playButton.onInvoke.registerListener(() =>
-  inputManager.setActiveGroup('game'),
-);
+playButton.onInvoke.registerListener(() => inputManager.setActiveGroup('game'));
 ```
 
 ---
@@ -1448,30 +1452,30 @@ ratio changes.
 
 ### Phase 2 — Interaction
 
-| #     | Item                                                                         | Size | Notes                                                                                                                                                            |
-| ----- | ---------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| #     | Item                                                                         | Size | Notes                                                                                                                                                        |
+| ----- | ---------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | 2.1 ⛓ | `UiInteractableEcsComponent` — config, events, and current interaction state | S    | `blocksRaycasts`, `interactable`, `onInvoke` + the pointer event set, `isHovered`/`isFocused`/`isPressed`/`isDragging`/`wasInvokedThisFrame`. (DL-13, DL-14) |
-| 2.2 ⛓ | `createUiRaycastEcsSystem`                                                   | M    | Reverse-depth scan, first hit wins, publishes `isPointerOverUi`. (DL-08)                                                                                         |
-| 2.3 ⛓ | `createUiInteractionEcsSystem`                                               | M    | The §5.7 pointer state machine; polled state + `ForgeEvent`s. Raises `onInvoke` on the pointer path.                                                           |
-| 2.4 ⛓ | `UiFocusEcsComponent` + `createUiNavigationEcsSystem`                        | M    | Directional focus traversal and `submitInput`/`cancelInput`. Raises `onInvoke` on the focus path. **Core, not polish** (DL-14).                                |
-| 2.5   | `createButton` aggregate factory                                             | S    | Assembles interactable + transitions + label. No `ButtonEcsComponent`. (DL-13)                                                                                   |
-| 2.6   | `createUiTransitionEcsSystem`                                                | S    | Color tint / sprite swap / scale per state, via the existing easing functions.                                                                                   |
-| 2.7   | Input-group interop docs                                                     | S    | The "UI is open, pause the game" and "click landed on UI" patterns.                                                                                              |
+| 2.2 ⛓ | `createUiRaycastEcsSystem`                                                   | M    | Reverse-depth scan, first hit wins, publishes `isPointerOverUi`. (DL-08)                                                                                     |
+| 2.3 ⛓ | `createUiInteractionEcsSystem`                                               | M    | The §5.7 pointer state machine; polled state + `ForgeEvent`s. Raises `onInvoke` on the pointer path.                                                         |
+| 2.4 ⛓ | `UiFocusEcsComponent` + `createUiNavigationEcsSystem`                        | M    | Directional focus traversal and `submitInput`/`cancelInput`. Raises `onInvoke` on the focus path. **Core, not polish** (DL-14).                              |
+| 2.5   | `createButton` aggregate factory                                             | S    | Assembles interactable + transitions + label. No `ButtonEcsComponent`. (DL-13)                                                                               |
+| 2.6   | `createUiTransitionEcsSystem`                                                | S    | Color tint / sprite swap / scale per state, via the existing easing functions.                                                                               |
+| 2.7   | Input-group interop docs                                                     | S    | The "UI is open, pause the game" and "click landed on UI" patterns.                                                                                          |
 
 **Phase 2 exit criterion:** A main menu with hoverable, clickable, keyboard-
 focusable buttons, where clicking a button does not also fire the player's weapon.
 
 ### Phase 3 — Controls
 
-| #   | Item                                                                                                                                                                                                                                                                                    | Size |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
-| 3.1 | **Landed.** `UiToggleEcsComponent`/`UiToggleGroupEcsComponent`/`createUiToggleEcsSystem`/`createToggle` (checkbox / radio via toggle groups)                                                                                                                                            | S    |
-| 3.2 | **Landed.** `UiSliderEcsComponent`/`createUiSliderEcsSystem`/`createSlider` (drag handle, fill, min/max, whole-number mode)                                                                                                                                                             | M    |
-| 3.3 | ~~`RectMaskEcsComponent` + per-instance clip rect~~ — **out of scope**, tracked in [#583](https://github.com/Forge-Game-Engine/Forge/issues/583)                                                                                                                                        | —    |
-| 3.4 | `ScrollRectEcsComponent` (drag + wheel, inertia, elasticity, scrollbars) — **blocked on [#583](https://github.com/Forge-Game-Engine/Forge/issues/583)**                                                                                                                                 | L    |
-| 3.5 | ~~`TextInputEcsComponent`~~ — **out of scope**, tracked in [#586](https://github.com/Forge-Game-Engine/Forge/issues/586) (no longer blocked on text — [#584](https://github.com/Forge-Game-Engine/Forge/issues/584) has landed)                                                         | —    |
-| 3.6 | **Landed.** `UiDropdownEcsComponent`/`createDropdown` - no generic system (see the component's own doc comment for why); closing on an outside click is a known limitation, not implemented                                                                                             | M    |
-| 3.7 | **Landed** as a linear fill: `UiProgressBarEcsComponent`/`createUiProgressBarEcsSystem`/`createProgressBar`. Radial fill deferred - it needs a shader-level fill-amount uniform, not just a rect resize like the linear case, real render-pipeline work disproportionate to an "S" item | S    |
+| #   | Item                                                                                                                                                                                                                                                                                                                                                                                                   | Size |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
+| 3.1 | **Landed.** `UiToggleEcsComponent`/`UiToggleGroupEcsComponent`/`createUiToggleEcsSystem`/`createToggle` (checkbox / radio via toggle groups)                                                                                                                                                                                                                                                           | S    |
+| 3.2 | **Landed.** `UiSliderEcsComponent`/`createUiSliderEcsSystem`/`createSlider` (drag handle, fill, min/max, whole-number mode)                                                                                                                                                                                                                                                                            | M    |
+| 3.3 | ~~`RectMaskEcsComponent` + per-instance clip rect~~ — **out of scope**, tracked in [#583](https://github.com/Forge-Game-Engine/Forge/issues/583)                                                                                                                                                                                                                                                       | —    |
+| 3.4 | `ScrollRectEcsComponent` (drag + wheel, inertia, elasticity, scrollbars) — **blocked on [#583](https://github.com/Forge-Game-Engine/Forge/issues/583)**                                                                                                                                                                                                                                                | L    |
+| 3.5 | **Landed.** `TextInputEcsComponent`/`createUiTextInputEcsSystem`/`createTextInput`, on a hidden DOM input from `createTextEntry` (`/src/input`) as DL-10 proposed; editing is separate from UI focus, and the caret is placed from `TextMeshEcsComponent.caretStops`. No horizontal scrolling of long values until rect clipping ([#583](https://github.com/Forge-Game-Engine/Forge/issues/583)) lands | M    |
+| 3.6 | **Landed.** `UiDropdownEcsComponent`/`createDropdown` - no generic system (see the component's own doc comment for why); closing on an outside click is a known limitation, not implemented                                                                                                                                                                                                            | M    |
+| 3.7 | **Landed** as a linear fill: `UiProgressBarEcsComponent`/`createUiProgressBarEcsSystem`/`createProgressBar`. Radial fill deferred - it needs a shader-level fill-amount uniform, not just a rect resize like the linear case, real render-pipeline work disproportionate to an "S" item                                                                                                                | S    |
 
 ### Phase 4 — Layout groups
 
@@ -1482,25 +1486,25 @@ column-aligned form layout extras
 `rowHeightMode`/`cellAlignment`, letting a label/control grid align every row's control to the
 widest label with no hand-computed offsets. Documented in the UI doc's "Layout groups" section.
 
-| #   | Item                                                        | Size |
-| --- | ------------------------------------------------------------ | ---- |
+| #   | Item                                                                                      | Size |
+| --- | ----------------------------------------------------------------------------------------- | ---- |
 | 4.1 | **Landed.** `LayoutElementEcsComponent` (min/preferred/flexible sizes, plus `sizeToText`) | S    |
-| 4.2 | **Landed.** `createUiLayoutGroupEcsSystem` — two-pass measure/arrange  | M    |
-| 4.3 | **Landed.** Horizontal / Vertical layout groups                        | M    |
-| 4.4 | **Landed.** Grid layout group (plus `columnWidthMode`/`rowHeightMode`/`cellAlignment`) | M    |
-| 4.5 | **Landed.** `ContentSizeFitterEcsComponent`                            | S    |
-| 4.6 | **Landed.** `AspectRatioFitterEcsComponent`                            | S    |
+| 4.2 | **Landed.** `createUiLayoutGroupEcsSystem` — two-pass measure/arrange                     | M    |
+| 4.3 | **Landed.** Horizontal / Vertical layout groups                                           | M    |
+| 4.4 | **Landed.** Grid layout group (plus `columnWidthMode`/`rowHeightMode`/`cellAlignment`)    | M    |
+| 4.5 | **Landed.** `ContentSizeFitterEcsComponent`                                               | S    |
+| 4.6 | **Landed.** `AspectRatioFitterEcsComponent`                                               | S    |
 
 ### Phase 5 — Polish
 
-| #   | Item                                                                        | Size      |
-| --- | --------------------------------------------------------------------------- | --------- |
-| 5.2 | **Landed.** `CanvasGroupEcsComponent` (inherited alpha / interactable / blocksRaycasts) | M         |
-| 5.3 | **Landed.** World-space canvas render mode (diegetic UI, health bars)        | M         |
+| #   | Item                                                                                                                                                                                                                                                                                                                                | Size      |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| 5.2 | **Landed.** `CanvasGroupEcsComponent` (inherited alpha / interactable / blocksRaycasts)                                                                                                                                                                                                                                             | M         |
+| 5.3 | **Landed.** World-space canvas render mode (diegetic UI, health bars)                                                                                                                                                                                                                                                               | M         |
 | 5.4 | **Landed**, outside this module: text effects (outline, drop shadow, glow as MSDF shader parameters) shipped via `/src/text` ([#608](https://github.com/Forge-Game-Engine/Forge/pull/608), [#610](https://github.com/Forge-Game-Engine/Forge/pull/610)), documented in the text module's Text Effects doc. Nothing left to do here. | S         |
-| 5.5 | **Landed.** Tooltips + a UI-safe-area concept for notched displays          | S         |
-| 5.6 | **Landed.** UI stress-test demo - dirty-tracking optimization evaluated and deferred, not warranted at the scale measured; see DL-12 | M (DL-12) |
-| 5.7 | **Scoped out.** Rich text tags (`<b>`, `<color>`) — scoping surfaced real architectural gaps (no per-glyph styling data model, no bold-weight concept in the font-atlas pipeline); see [`design/rich-text-tags.md`](./rich-text-tags.md) for the design addendum instead of a guessed implementation. | L         |
+| 5.5 | **Landed.** Tooltips + a UI-safe-area concept for notched displays                                                                                                                                                                                                                                                                  | S         |
+| 5.6 | **Landed.** UI stress-test demo - dirty-tracking optimization evaluated and deferred, not warranted at the scale measured; see DL-12                                                                                                                                                                                                | M (DL-12) |
+| 5.7 | **Scoped out.** Rich text tags (`<b>`, `<color>`) — scoping surfaced real architectural gaps (no per-glyph styling data model, no bold-weight concept in the font-atlas pipeline); see [`design/rich-text-tags.md`](./rich-text-tags.md) for the design addendum instead of a guessed implementation.                               | L         |
 
 ---
 
diff --git a/documentation-site/docs/docs/input/keyboard.md b/documentation-site/docs/docs/input/keyboard.md
index ce0bc63b8..89093b834 100644
--- a/documentation-site/docs/docs/input/keyboard.md
+++ b/documentation-site/docs/docs/input/keyboard.md
@@ -104,13 +104,19 @@ Bindings on a _different_ source (a gamepad, say) that target the same
 action don't combine with the keyboard's: whichever source dispatches most
 recently sets the value.
 
+Keys typed into an editable element (an `<input>`, `<textarea>`, `<select>`
+or `contentEditable` element, including one inside a shadow root) aren't
+game input: such a key isn't held, dispatches no binding, and its release
+is ignored too. A key that went down outside the element is still released
+when its `keyup` arrives in the element. This covers HTML forms next to the
+game and Forge's own [text fields](../ui/text-input.md).
+
 Key repeat events are ignored (the browser's
 [`KeyboardEvent.repeat`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat)
 flag), so holding a key down dispatches bindings exactly once on press and
 once on release, not on every repeated `keydown`.
 
 [`KeyboardInputSource.stop()`](/Forge/docs/api/classes/KeyboardInputSource#stop)
-removes its `keydown`/`keyup` listeners and unregisters it from the
-`InputManager`. Call it when the source is no longer needed, for example
+removes its `keydown`/`keyup` listeners. Call it when the source is no longer needed, for example
 when tearing down a game instance in tests, since the listeners are attached
 to `globalThis` and otherwise outlive the source.
diff --git a/documentation-site/docs/docs/input/text-entry.md b/documentation-site/docs/docs/input/text-entry.md
new file mode 100644
index 000000000..22a8893da
--- /dev/null
+++ b/documentation-site/docs/docs/input/text-entry.md
@@ -0,0 +1,78 @@
+---
+sidebar_position: 5
+---
+
+# Text Entry
+
+A text entry is a hidden HTML `<input>` that receives typing for text the
+game draws itself. The browser handles keyboard layouts, IME composition,
+paste and phone keyboards; the entry exposes the text, the selection and
+the composition as data. Forge's [text fields](../ui/text-input.md) are
+built on it. Use it directly for something that isn't a UI field, such as
+a debug console.
+
+## Creating a text entry
+
+```ts
+import { createTextEntry } from '@forge-game-engine/forge/input';
+
+const entry = createTextEntry(game.container);
+```
+
+[`createTextEntry`](/Forge/docs/api/functions/createTextEntry) appends the
+input to the container, and makes the container `position: relative` if it
+isn't positioned. The input is transparent and has
+`pointer-events: none`.
+
+## Placing the input
+
+```ts
+entry.setScreenRect({ left: 200, top: 120, width: 300, height: 40 });
+```
+
+`setScreenRect` takes CSS pixels relative to the container, with Y down.
+Place the input over the text the game draws: a phone scrolls the focused
+input into view above its keyboard, and an IME opens its candidate window
+next to it.
+
+## Focusing and blurring
+
+`focus()` sends the player's typing to the input and `blur()` stops it.
+`isFocused` tells which is the case. A phone opens its keyboard only when
+`focus()` is called inside the event handler of a user gesture.
+
+While the entry has focus:
+
+- a key that was already held when it was focused doesn't auto-repeat into
+  it;
+- Enter and Escape have no browser behavior, and are reported as
+  `submitted` and `cancelled`, except during an IME composition;
+- Tab does nothing.
+
+## Reading the text
+
+`value`, `selectionStart` and `selectionEnd` read the input's current
+state. `composition` is the range of text being composed with an IME, or
+`null`. `setValue` and `setSelection` change them.
+
+## Reading events
+
+DOM events arrive between ticks. `takeEvents()` returns what happened since
+its last call and clears it:
+
+```ts
+const events = entry.takeEvents();
+
+if (events.submitted) {
+  runCommand(entry.value);
+  entry.setValue('');
+}
+```
+
+`changed` is set when typing, pasting or an IME changed the text,
+`submitted` and `cancelled` by Enter and Escape, and `blurred` when the
+input lost focus.
+
+## Removing a text entry
+
+`dispose()` removes the input and its event listeners.
diff --git a/documentation-site/docs/docs/ui/index.md b/documentation-site/docs/docs/ui/index.md
index cd34e3268..200958ac7 100644
--- a/documentation-site/docs/docs/ui/index.md
+++ b/documentation-site/docs/docs/ui/index.md
@@ -39,6 +39,8 @@ Guides in this section:
   arrangement, content-size fitting, and aspect-ratio fitting.
 - [Canvas Groups and Tooltips](./canvas-groups-and-tooltips.md): fading or
   disabling a whole subtree at once, and hover/focus tooltips.
+- [Text Input](./text-input.md): single-line text fields, editing versus
+  focus, filtering, and submit/cancel events.
 
 ## Quick Start
 
diff --git a/documentation-site/docs/docs/ui/text-input.md b/documentation-site/docs/docs/ui/text-input.md
new file mode 100644
index 000000000..f769235f3
--- /dev/null
+++ b/documentation-site/docs/docs/ui/text-input.md
@@ -0,0 +1,186 @@
+---
+sidebar_position: 9
+---
+
+# Text Input
+
+A text input is a single-line field the player types into. The typing goes
+to a hidden HTML `<input>` the field owns, so keyboard layouts, IME
+composition, paste, phone keyboards and screen readers work the way they
+do in any web page, and the field draws its text, caret and selection with
+ordinary UI entities.
+
+## Parts of a text input
+
+[`createTextInput`](/Forge/docs/api/functions/createTextInput) creates:
+
+- a background panel with a
+  [`UiInteractableEcsComponent`](/Forge/docs/api/interfaces/UiInteractableEcsComponent),
+  so the field is hoverable, focusable and reachable by navigation like a
+  button;
+- a [`TextInputEcsComponent`](/Forge/docs/api/interfaces/TextInputEcsComponent)
+  on the same entity, holding the field's `value`, its `isEditing` state,
+  its settings and its events;
+- a [`TextEntry`](/Forge/docs/api/interfaces/TextEntry) (the
+  component's `entry`): the hidden `<input>`, added to the element the
+  game's canvas is in;
+- child entities for the text label, the placeholder label, the caret, the
+  selection highlight and the IME composition underline.
+
+`createUiTextInputEcsSystem` runs every field. `registerUiSystems` registers
+it, so a game that calls `registerUiSystems` needs nothing else.
+
+## Creating a text input
+
+```ts
+import { createTextInput, UiAnchor } from '@forge-game-engine/forge/ui';
+
+const nameField = createTextInput(world, canvas, {
+  renderContext,
+  sprite: fieldSprite,
+  fillSprite: whiteSprite,
+  fontAtlas,
+  size: 28,
+  anchor: UiAnchor.center({ x: 420, y: 64 }),
+  placeholder: 'Your name',
+  maxLength: 16,
+  attributes: { ariaLabel: 'Your name', autocapitalize: 'words' },
+  category: uiLayer,
+});
+```
+
+`sprite` draws the background. `fillSprite` is a plain sprite (a white
+pixel, for example) that the caret, the selection and the composition
+underline are drawn with, tinted by `caretColor` and `selectionColor`.
+`attributes` are set on the hidden input: phone keyboards read them
+(`inputMode`, `autocapitalize`, `enterKeyHint`) and screen readers announce
+`ariaLabel`.
+
+:::caution
+A field doesn't scroll or clip text that's wider than it. Pick a
+`maxLength` whose longest value fits the field's width.
+:::
+
+## Editing and focus
+
+Editing is separate from UI focus. A field is being edited while its hidden
+input has focus, and `isEditing` is `true` exactly then. Editing starts
+when:
+
+- the player clicks or taps the field;
+- the canvas's `submitInput` triggers while the field has UI focus;
+- the game calls [`editTextInput`](/Forge/docs/api/functions/editTextInput).
+
+Editing ends when the player presses Enter or Escape, or when the browser
+takes focus away from the input (a click elsewhere, a phone keyboard's
+"Done" key, switching tabs). Moving UI focus, by hovering or navigating to
+another element, doesn't end editing, so a game can keep UI focus on a
+submit button while the player types.
+
+```ts
+import { editTextInput } from '@forge-game-engine/forge/ui';
+
+editTextInput(world, nameField.entity);
+```
+
+A field that isn't interactable, or whose canvas group isn't, can't be
+edited.
+
+:::note
+A phone only opens its keyboard when an input is focused inside the event
+handler of a user gesture. A tap on a field focuses its input inside the
+tap's `pointerup` handler, using the same hit test as every other UI
+pointer interaction, so the keyboard opens. `editTextInput` called from a
+system runs outside any gesture, so it focuses the field without opening a
+phone keyboard.
+:::
+
+Keys typed into the field aren't game input:
+[`KeyboardInputSource`](../input/keyboard.md) ignores keys typed into an
+editable element, so the canvas's keyboard-bound `navigateInput` and
+`submitInput` don't trigger while the player types. Tab does nothing inside
+a field. A gamepad still navigates UI focus.
+
+## Reading the value
+
+`value` holds the field's text. It's updated by the text input system, once
+per tick, from what was typed:
+
+1. Characters the field's font atlas has no glyph for are removed (spaces
+   are kept).
+2. The field's `filter`, if it has one, runs on the result.
+3. The result is cut to `maxLength`.
+
+If filtering changed the text, the filtered text is written back to the
+hidden input, with the caret after the same characters. Text that's still
+being composed with an IME is drawn, underlined, but isn't filtered or
+part of `value` until the composition ends.
+
+```ts
+const codeField = createTextInput(world, canvas, {
+  // ...
+  filter: (text) => text.toUpperCase(),
+});
+```
+
+## Setting the value
+
+[`setTextInputValue`](/Forge/docs/api/functions/setTextInputValue) replaces
+a field's text, for example to clear or prefill it. The text goes through
+the same filters as typed text, and `value` and `onValueChanged` update on
+the next tick.
+
+```ts
+import { setTextInputValue } from '@forge-game-engine/forge/ui';
+
+setTextInputValue(world, nameField.entity, '');
+```
+
+## Reacting to changes, submit and cancel
+
+```ts
+nameField.onValueChanged.registerListener((value) => {
+  previewLabelText.text = value;
+});
+
+nameField.onSubmit.registerListener((value) => {
+  savePlayerName(value);
+});
+
+nameField.onCancel.registerListener(() => {
+  closeNamePanel();
+});
+```
+
+- `onValueChanged` is raised with the new `value` whenever it changes.
+- `onSubmit` is raised with `value` when the player presses Enter outside
+  an IME composition. Holding Enter submits once.
+- `onCancel` is raised when the player presses Escape outside an IME
+  composition. `value` is kept.
+
+Enter and Escape during an IME composition commit or cancel the
+composition, and don't submit or cancel the field.
+
+## Placeholder
+
+The placeholder label is drawn instead of the text while the field is
+empty. Its text and color are the `placeholder` and `placeholderColor`
+options; change them later through the label's
+[`TextEcsComponent`](/Forge/docs/api/interfaces/TextEcsComponent)
+(`nameField.placeholderLabel`).
+
+## Caret and selection
+
+The caret and the selection highlight are placed from the text label's
+[`TextMeshEcsComponent.caretStops`](/Forge/docs/api/interfaces/TextMeshEcsComponent#caretstops):
+the position of every boundary between characters in the shaped text. The
+caret blinks while the field is being edited, and restarts its blink when
+the text or the selection changes. Selection uses the keyboard (Shift with
+the arrow keys, or select-all); the hidden input doesn't receive pointer
+drags.
+
+## Removing a text input
+
+Removing the field's entity, or its `TextInputEcsComponent`, removes its
+hidden input on the next tick. When the text input system is removed from
+the world, or the world is stopped, every field's hidden input is removed.
diff --git a/documentation-site/src/data/demos.ts b/documentation-site/src/data/demos.ts
index 5cfca78f5..46dad5345 100644
--- a/documentation-site/src/data/demos.ts
+++ b/documentation-site/src/data/demos.ts
@@ -186,6 +186,13 @@ export const demos: Demo[] = [
       'A moving, resizing window with four levels of nested anchored children.',
     categories: ['ui'],
   },
+  {
+    slug: 'ui-text-input',
+    title: 'UI Text Input',
+    description:
+      'A name entry form: typing, filtering, submit and cancel in text fields.',
+    categories: ['ui'],
+  },
   {
     slug: 'ui-button',
     title: 'UI Buttons',
diff --git a/documentation-site/src/pages/demos/ui-text-input/_create-game.ts b/documentation-site/src/pages/demos/ui-text-input/_create-game.ts
new file mode 100644
index 000000000..91f8ec484
--- /dev/null
+++ b/documentation-site/src/pages/demos/ui-text-input/_create-game.ts
@@ -0,0 +1,351 @@
+import {
+  addPositionComponent,
+  createTransformEcsSystem,
+  Time,
+} from '@forge-game-engine/forge/common';
+import { EcsWorld } from '@forge-game-engine/forge/ecs';
+import defaultFontImageUrl from '@forge-game-engine/forge/fonts/default/default.png';
+import {
+  actionResetTypes,
+  Axis2dAction,
+  buttonMoments,
+  KeyboardAxis2dBinding,
+  keyCodes,
+  KeyboardInputSource,
+  KeyboardTriggerBinding,
+  MouseInputSource,
+  registerInputs,
+  TriggerAction,
+} from '@forge-game-engine/forge/input';
+import {
+  addSpriteComponent,
+  Color,
+  createCamera,
+  createCameraEcsSystem,
+  createImageSprite,
+  createPresentEcsSystem,
+  createRenderEcsSystem,
+  getCameraView,
+  RenderContext,
+  SpriteEcsComponent,
+} from '@forge-game-engine/forge/rendering';
+import {
+  createTextShapingEcsSystem,
+  FontAtlas,
+  FontAtlasCache,
+  textHorizontalAlignments,
+  textId,
+} from '@forge-game-engine/forge/text';
+import {
+  canvasId,
+  createButton,
+  createLabel,
+  createTextInput,
+  createUiCanvas,
+  registerUiSystems,
+  setTextInputValue,
+  setUiFocus,
+  UiAnchor,
+  UiAxis,
+} from '@forge-game-engine/forge/ui';
+import { createGame, Game } from '@forge-game-engine/forge/utilities';
+import { DEMO_VERTICAL_WORLD_UNITS } from '@site/src/utils/demo-camera';
+import { getAssetUrl } from '@site/src/utils/get-asset-url';
+
+const renderLayers = {
+  world: 1 << 0,
+  ui: 1 << 1,
+};
+
+const textColor = new Color(0.12, 0.12, 0.16, 1);
+const fieldWidth = 640;
+
+async function createBackdrop(
+  world: EcsWorld,
+  camera: number,
+  renderContext: RenderContext,
+  whiteSprite: SpriteEcsComponent,
+): Promise<void> {
+  const { x: width, y: height } = getCameraView(
+    world,
+    camera,
+    renderContext,
+  ).size;
+
+  const backdrop = world.createEntity();
+
+  addPositionComponent(world, backdrop);
+  addSpriteComponent(world, backdrop, {
+    ...whiteSprite,
+    width,
+    height,
+    tintColor: new Color(0.09, 0.11, 0.16, 1),
+  });
+}
+
+/**
+ * Wires a `MouseInputSource` and a `KeyboardInputSource`: the arrow keys
+ * navigate UI focus and Enter submits the focused element. Keys typed into
+ * a text field never reach these bindings.
+ */
+function createUiInputs(
+  world: EcsWorld,
+  time: Time,
+  game: Game,
+): {
+  mouseInputSource: MouseInputSource;
+  submitInput: TriggerAction;
+  navigateInput: Axis2dAction;
+} {
+  const submitInput = new TriggerAction('ui-submit');
+  const navigateInput = new Axis2dAction(
+    'ui-navigate',
+    undefined,
+    actionResetTypes.noReset,
+  );
+
+  const inputManager = registerInputs(world, time, {
+    triggerActions: [submitInput],
+    axis2dActions: [navigateInput],
+  });
+
+  const mouseInputSource = new MouseInputSource(inputManager, game.container);
+  const keyboardInputSource = new KeyboardInputSource(inputManager);
+
+  keyboardInputSource.axis2dBindings.add(
+    new KeyboardAxis2dBinding(
+      navigateInput,
+      keyCodes.arrowUp,
+      keyCodes.arrowDown,
+      keyCodes.arrowRight,
+      keyCodes.arrowLeft,
+    ),
+  );
+
+  keyboardInputSource.triggerBindings.add(
+    new KeyboardTriggerBinding(submitInput, keyCodes.enter, buttonMoments.down),
+  );
+
+  return { mouseInputSource, submitInput, navigateInput };
+}
+
+/** Keeps letters and digits, upper-cased: a badge code like "AX7Q". */
+const badgeFilter = (text: string): string =>
+  text.toUpperCase().replace(/[^A-Z0-9]/g, '');
+
+/** Drops leading spaces, so a name can't start with one. */
+const nameFilter = (text: string): string => text.replace(/^ +/, '');
+
+/**
+ * Builds the text input demo: a name entry form with two text fields
+ * (`createTextInput`) and a "Log in" button. Click or tap a field, or
+ * focus it with the arrow keys and press Enter, to type into it. Enter
+ * submits the field and Escape cancels it. Keys typed into a field don't
+ * reach the UI's arrow-key navigation or its Enter binding, so they don't
+ * move UI focus or press the focused button.
+ * @returns The created game.
+ */
+export const createTextInputGame = async (): Promise<Game> => {
+  const { game, world, renderContext, time } = createGame('demo-game');
+
+  const camera = createCamera(world, {
+    isStatic: true,
+    cullingMask: renderLayers.world,
+    verticalWorldUnits: DEMO_VERTICAL_WORLD_UNITS,
+  });
+
+  const whiteImage = await renderContext.imageCache.getOrLoad(
+    getAssetUrl('img/White.png'),
+  );
+  const createWhiteSprite = (layer: number): SpriteEcsComponent =>
+    createImageSprite(whiteImage, renderContext, { pixelsPerUnit: 1, layer });
+
+  await createBackdrop(
+    world,
+    camera,
+    renderContext,
+    createWhiteSprite(renderLayers.world),
+  );
+
+  const fontAtlasCache = new FontAtlasCache(renderContext.imageCache);
+  const fontAtlas: FontAtlas = await fontAtlasCache.getOrLoad({
+    // Importing the JSON would give its parsed contents, so `new URL` asks
+    // webpack for its URL instead.
+    metricsUrl: new URL(
+      '@forge-game-engine/forge/fonts/default/default.json',
+      import.meta.url,
+    ).href,
+    imageUrl: defaultFontImageUrl,
+  });
+
+  const { mouseInputSource, submitInput, navigateInput } = createUiInputs(
+    world,
+    time,
+    game,
+  );
+
+  registerUiSystems(world, renderContext, time, {
+    pointerSource: mouseInputSource,
+  });
+
+  const canvas = createUiCanvas(world, renderContext, {
+    cullingMask: renderLayers.ui,
+    referenceResolution: { x: 1920, y: 1080 },
+    submitInput,
+    navigateInput,
+  });
+
+  const panelImage = await renderContext.imageCache.getOrLoad(
+    getAssetUrl('img/kenney_fantasy-ui-borders/PNG/Double/Panel/panel-030.png'),
+  );
+  const panelSprite = createImageSprite(panelImage, renderContext, {
+    pixelsPerUnit: 1,
+    layer: renderLayers.ui,
+    slices: {
+      left: 26,
+      right: 26,
+      top: 26,
+      bottom: 26,
+      nativeWidth: 96,
+      nativeHeight: 96,
+    },
+  });
+  const fillSprite = createWhiteSprite(renderLayers.ui);
+
+  const transition = {
+    normalColor: Color.white,
+    hoverColor: new Color(0.85, 0.85, 0.85, 1),
+    pressedColor: new Color(0.65, 0.65, 0.65, 1),
+    disabledColor: new Color(0.5, 0.5, 0.5, 0.6),
+  };
+
+  const fieldOptions = {
+    renderContext,
+    sprite: panelSprite,
+    fillSprite,
+    fontAtlas,
+    size: 38,
+    padding: 28,
+    textColor,
+    caretColor: textColor,
+    category: renderLayers.ui,
+    transition,
+  };
+
+  const createFieldLabel = (text: string, y: number): void => {
+    createLabel(world, canvas, {
+      text,
+      fontAtlas,
+      size: 28,
+      // A label's text starts at its pivot, so a left pivot lines it up
+      // with the field's left edge.
+      anchor: {
+        x: UiAxis.point(0.5, { pivot: 0, size: fieldWidth }),
+        y: UiAxis.point(0.5, { size: 30 }),
+      },
+      anchoredPosition: { x: -fieldWidth / 2, y },
+      color: new Color(0.7, 0.75, 0.85, 1),
+      category: renderLayers.ui,
+    });
+  };
+
+  createFieldLabel('PILOT NAME', 270);
+
+  const nameField = createTextInput(world, canvas, {
+    ...fieldOptions,
+    anchor: UiAnchor.center({ x: fieldWidth, y: 88 }),
+    anchoredPosition: { x: 0, y: 190 },
+    placeholder: 'Your name',
+    maxLength: 16,
+    filter: nameFilter,
+    attributes: { ariaLabel: 'Pilot name', autocapitalize: 'words' },
+  });
+
+  createFieldLabel('BADGE NUMBER', 100);
+
+  const badgeField = createTextInput(world, canvas, {
+    ...fieldOptions,
+    anchor: UiAnchor.center({ x: fieldWidth, y: 88 }),
+    anchoredPosition: { x: 0, y: 20 },
+    placeholder: 'AX7Q',
+    maxLength: 6,
+    filter: badgeFilter,
+    attributes: {
+      ariaLabel: 'Badge number',
+      autocapitalize: 'characters',
+      autocomplete: 'off',
+    },
+  });
+
+  const logInButton = createButton(world, canvas, {
+    anchor: UiAnchor.center({ x: 300, y: 80 }),
+    anchoredPosition: { x: 0, y: -130 },
+    sprite: panelSprite,
+    label: 'Log in',
+    fontAtlas,
+    labelSize: 32,
+    labelColor: textColor,
+    labelCategory: renderLayers.ui,
+    transition,
+  });
+
+  const statusLabel = createLabel(world, canvas, {
+    text: 'Click a field and type',
+    fontAtlas,
+    size: 30,
+    // `horizontalAlign: 'center'` centers within `maxWidth` measured from
+    // the label's pivot, so the pivot sits at the box's left edge.
+    anchor: {
+      x: UiAxis.point(0.5, { pivot: 0, size: 900 }),
+      y: UiAxis.point(0.5, { size: 40 }),
+    },
+    anchoredPosition: { x: -450, y: -230 },
+    horizontalAlign: textHorizontalAlignments.center,
+    maxWidth: 900,
+    color: Color.white,
+    category: renderLayers.ui,
+  });
+  const statusText = world.getComponent(statusLabel, textId)!;
+
+  nameField.onSubmit.registerListener((name) => {
+    statusText.text = `Name entered: ${name}`;
+  });
+  badgeField.onSubmit.registerListener((badge) => {
+    statusText.text = `Badge entered: ${badge}`;
+  });
+  nameField.onCancel.registerListener(() => {
+    statusText.text = 'Name editing cancelled';
+  });
+  badgeField.onCancel.registerListener(() => {
+    statusText.text = 'Badge editing cancelled';
+  });
+
+  logInButton.onInvoke.registerListener(() => {
+    const name = nameField.textInput.value;
+    const badge = badgeField.textInput.value;
+
+    statusText.text =
+      name && badge
+        ? `Welcome aboard, ${name} (${badge})`
+        : 'Enter a name and a badge number';
+
+    if (name && badge) {
+      setTextInputValue(world, badgeField.entity, '');
+    }
+  });
+
+  // Starts with the button focused, so Enter outside a field presses it.
+  setUiFocus(
+    world,
+    world.getComponentRequired(canvas, canvasId),
+    logInButton.entity,
+  );
+
+  world.addSystem(createCameraEcsSystem(time));
+  world.addSystem(createTransformEcsSystem());
+  world.addSystem(createTextShapingEcsSystem(renderContext));
+  world.addSystem(createRenderEcsSystem(renderContext));
+  world.addSystem(createPresentEcsSystem(renderContext));
+
+  return game;
+};
diff --git a/documentation-site/src/pages/demos/ui-text-input/index.tsx b/documentation-site/src/pages/demos/ui-text-input/index.tsx
new file mode 100644
index 000000000..95cdf0596
--- /dev/null
+++ b/documentation-site/src/pages/demos/ui-text-input/index.tsx
@@ -0,0 +1,54 @@
+import React, { JSX } from 'react';
+import { createTextInputGame } from './_create-game';
+import gameCode from '!!raw-loader!./_create-game';
+
+import { Demo } from '@site/src/components/Demo';
+import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
+import { KeyboardKey } from '@site/src/components/_KeyboardKey';
+
+const badgeStyle: React.CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  width: 20,
+  height: 20,
+  borderRadius: '50%',
+  backgroundColor: 'var(--ifm-color-emphasis-300)',
+  fontSize: 12,
+};
+
+export default function UiTextInput(): JSX.Element {
+  return (
+    <Demo
+      metaData={{
+        title: 'UI Text Input',
+        description:
+          'A demo showcasing createTextInput from the ui module: a name entry form with two text fields, character filters, and submit/cancel events.',
+      }}
+      header="UI Text Input"
+      blurb="A name entry form built from two text fields (createTextInput) and a button. Click or tap a field to type into it; Enter submits the field and Escape cancels it. The pilot name can't start with a space and the badge number keeps only upper-cased letters and digits. Keys typed into a field don't move UI focus or press the focused button."
+      createGame={createTextInputGame}
+      interactions={
+        <>
+          <InteractionInstruction
+            displayElement={
+              <div style={badgeStyle}>
+                <i className="fa-solid fa-computer-mouse" />
+              </div>
+            }
+            text="Click a field to type into it."
+          />
+          <InteractionInstruction
+            displayElement={<KeyboardKey keyCode="⏎" />}
+            text="Submit the field you're typing in."
+          />
+          <InteractionInstruction
+            displayElement={<KeyboardKey keyCode="Esc" />}
+            text="Cancel typing."
+          />
+        </>
+      }
+      codeFiles={[{ name: 'game.ts', content: gameCode }]}
+    />
+  );
+}
diff --git a/e2e/fixtures/scenes/ui-text-input.ts b/e2e/fixtures/scenes/ui-text-input.ts
new file mode 100644
index 000000000..ea353f591
--- /dev/null
+++ b/e2e/fixtures/scenes/ui-text-input.ts
@@ -0,0 +1,287 @@
+import fontImageUrl from '../../../assets/fonts/default/default.png?url';
+import fontMetricsUrl from '../../../assets/fonts/default/default.json?url';
+import {
+  addPositionComponent,
+  createTransformEcsSystem,
+  Time,
+} from '../../../src/common/index.js';
+import { EcsWorld } from '../../../src/ecs/index.js';
+import {
+  actionResetTypes,
+  Axis2dAction,
+  buttonMoments,
+  KeyboardAxis2dBinding,
+  KeyboardInputSource,
+  KeyboardTriggerBinding,
+  keyCodes,
+  MouseInputSource,
+  registerInputs,
+  TriggerAction,
+} from '../../../src/input/index.js';
+import {
+  addCameraComponent,
+  Color,
+  createCanvas,
+  createImageSprite,
+  createPresentEcsSystem,
+  createRenderContext,
+  createRenderEcsSystem,
+  spriteId,
+} from '../../../src/rendering/index.js';
+import {
+  createTextShapingEcsSystem,
+  FontAtlasCache,
+} from '../../../src/text/index.js';
+import {
+  addUiInteractableComponent,
+  CanvasEcsComponent,
+  canvasId,
+  createPanel,
+  createTextInput,
+  createUiCanvas,
+  registerUiSystems,
+  setUiFocus,
+  UiAnchor,
+  uiScaleModes,
+} from '../../../src/ui/index.js';
+import { createSquareImage } from './create-square-image.js';
+import { PixelBounds, scanPixelBounds } from './input-scene-helpers.js';
+import { CreateScene, SceneHandle } from './scene.js';
+
+const defaultStepDeltaMilliseconds = 16.6666;
+
+const worldRenderCategory = 1 << 0;
+const uiRenderCategory = 1 << 1;
+
+/** Where the field and the button sit, in CSS pixels from the canvas's top-left. */
+const fieldCenter = { x: 400, y: 300 };
+const buttonCenter = { x: 400, y: 150 };
+
+/** The handle `ui-text-input.spec.ts` drives and asserts against. */
+export interface UiTextInputSceneHandle extends SceneHandle {
+  /** The field's committed value. */
+  readonly value: string;
+
+  /** Whether the field is being typed into. */
+  readonly isEditing: boolean;
+
+  /** How many times `onSubmit` was raised, and with what values. */
+  readonly submittedValues: string[];
+
+  /** How many times `onCancel` was raised. */
+  readonly cancelCount: number;
+
+  /** Whether the button above the field has UI focus. */
+  readonly isButtonFocused: boolean;
+
+  /** The field's center, in page CSS pixels. */
+  readonly fieldCenter: { x: number; y: number };
+
+  /** The button's center, in page CSS pixels. */
+  readonly buttonCenter: { x: number; y: number };
+
+  /** Gives the button above the field UI focus. */
+  focusButton(): void;
+
+  /** Shows or hides a panel that covers the field and blocks the pointer. */
+  setCoverVisible(visible: boolean): void;
+
+  /**
+   * The on-screen bounds of the field's dark text ink, from the rendered
+   * canvas, or `null` when no text is drawn. The caret is red, so it isn't
+   * counted. Must be called in the same `page.evaluate` task as the
+   * preceding `step()`.
+   */
+  measureTextInk(): PixelBounds | null;
+}
+
+/**
+ * Builds a screen-space UI canvas (1 reference pixel per CSS pixel) with a
+ * text field in the middle, a focusable button above it, and a hidden
+ * cover panel over the field. The canvas navigates with the arrow keys and
+ * submits with Enter, so the spec can check that keys typed into the
+ * field don't reach either.
+ * @param container - The element to render the scene's canvas into.
+ * @returns The scene's handle.
+ */
+export const createScene: CreateScene = async (
+  container: HTMLElement,
+): Promise<UiTextInputSceneHandle> => {
+  const time = new Time();
+  const world = new EcsWorld();
+  const canvas = createCanvas(container);
+
+  canvas.width = 800;
+  canvas.height = 600;
+
+  const renderContext = createRenderContext(canvas, {
+    preserveDrawingBuffer: true,
+  });
+
+  const submitInput = new TriggerAction('ui-submit');
+  const navigateInput = new Axis2dAction(
+    'ui-navigate',
+    undefined,
+    actionResetTypes.noReset,
+  );
+  const inputManager = registerInputs(world, time, {
+    triggerActions: [submitInput],
+    axis2dActions: [navigateInput],
+  });
+  const mouseInputSource = new MouseInputSource(inputManager, container);
+  const keyboardInputSource = new KeyboardInputSource(inputManager);
+
+  keyboardInputSource.axis2dBindings.add(
+    new KeyboardAxis2dBinding(
+      navigateInput,
+      keyCodes.arrowUp,
+      keyCodes.arrowDown,
+      keyCodes.arrowRight,
+      keyCodes.arrowLeft,
+    ),
+  );
+  keyboardInputSource.triggerBindings.add(
+    new KeyboardTriggerBinding(submitInput, keyCodes.enter, buttonMoments.down),
+  );
+
+  const worldCameraEntity = world.createEntity();
+
+  addPositionComponent(world, worldCameraEntity);
+  addCameraComponent(world, worldCameraEntity, {
+    isStatic: true,
+    clearColor: new Color(0.8, 0.8, 0.8, 1),
+    cullingMask: worldRenderCategory,
+  });
+
+  registerUiSystems(world, renderContext, time, {
+    pointerSource: mouseInputSource,
+  });
+
+  const uiCanvas = createUiCanvas(world, renderContext, {
+    cullingMask: uiRenderCategory,
+    scaleMode: uiScaleModes.constantPixelSize,
+    submitInput,
+    navigateInput,
+  });
+
+  const fontAtlas = await new FontAtlasCache(
+    renderContext.imageCache,
+  ).getOrLoad({ metricsUrl: fontMetricsUrl, imageUrl: fontImageUrl });
+
+  const whiteImage = await createSquareImage('#fff');
+
+  const sprite = (tint: Color) => {
+    const created = createImageSprite(whiteImage, renderContext, {
+      pixelsPerUnit: 1,
+      layer: uiRenderCategory,
+    });
+
+    created.tintColor = tint;
+
+    return created;
+  };
+
+  const button = createPanel(world, uiCanvas, {
+    sprite: sprite(new Color(0.3, 0.5, 0.9, 1)),
+    anchor: UiAnchor.center({ x: 200, y: 60 }),
+    anchoredPosition: { x: 0, y: 300 - buttonCenter.y },
+  });
+  const buttonInteractable = addUiInteractableComponent(world, button);
+
+  const field = createTextInput(world, uiCanvas, {
+    renderContext,
+    sprite: sprite(Color.white),
+    fillSprite: sprite(Color.white),
+    fontAtlas,
+    size: 32,
+    anchor: UiAnchor.center({ x: 400, y: 60 }),
+    textColor: Color.black,
+    caretColor: Color.red,
+    category: uiRenderCategory,
+    maxLength: 16,
+    attributes: { ariaLabel: 'Name' },
+  });
+
+  const cover = createPanel(world, uiCanvas, {
+    sprite: sprite(new Color(0.1, 0.6, 0.2, 1)),
+    anchor: UiAnchor.center({ x: 440, y: 100 }),
+  });
+  const coverInteractable = addUiInteractableComponent(world, cover, {
+    blocksRaycasts: false,
+  });
+  const coverSprite = world.getComponentRequired(cover, spriteId);
+
+  coverSprite.enabled = false;
+
+  const submittedValues: string[] = [];
+  let cancelCount = 0;
+
+  field.onSubmit.registerListener((value) => submittedValues.push(value));
+  field.onCancel.registerListener(() => cancelCount++);
+
+  world.addSystem(createTransformEcsSystem());
+  world.addSystem(createTextShapingEcsSystem(renderContext));
+  world.addSystem(createRenderEcsSystem(renderContext));
+  world.addSystem(createPresentEcsSystem(renderContext));
+
+  let clockInMilliseconds = 0;
+
+  const toPage = (point: { x: number; y: number }) => {
+    const bounds = canvas.getBoundingClientRect();
+
+    return { x: bounds.left + point.x, y: bounds.top + point.y };
+  };
+
+  return {
+    step(deltaMilliseconds: number = defaultStepDeltaMilliseconds): void {
+      clockInMilliseconds += deltaMilliseconds;
+      time.update(clockInMilliseconds);
+      world.update();
+    },
+
+    get value(): string {
+      return field.textInput.value;
+    },
+
+    get isEditing(): boolean {
+      return field.textInput.isEditing;
+    },
+
+    get submittedValues(): string[] {
+      return [...submittedValues];
+    },
+
+    get cancelCount(): number {
+      return cancelCount;
+    },
+
+    get isButtonFocused(): boolean {
+      return buttonInteractable.isFocused;
+    },
+
+    get fieldCenter(): { x: number; y: number } {
+      return toPage(fieldCenter);
+    },
+
+    get buttonCenter(): { x: number; y: number } {
+      return toPage(buttonCenter);
+    },
+
+    focusButton(): void {
+      setUiFocus(
+        world,
+        world.getComponentRequired<CanvasEcsComponent>(uiCanvas, canvasId),
+        button,
+      );
+    },
+
+    setCoverVisible(visible: boolean): void {
+      coverSprite.enabled = visible;
+      coverInteractable.blocksRaycasts = visible;
+    },
+
+    measureTextInk(): PixelBounds | null {
+      return scanPixelBounds(canvas, (r, g, b) => r < 90 && g < 90 && b < 90);
+    },
+  };
+};
diff --git a/e2e/specs/ui-text-input.spec.ts b/e2e/specs/ui-text-input.spec.ts
new file mode 100644
index 000000000..4cbb8679e
--- /dev/null
+++ b/e2e/specs/ui-text-input.spec.ts
@@ -0,0 +1,157 @@
+import { expect, test } from '@playwright/test';
+import type { UiTextInputSceneHandle } from '../fixtures/scenes/ui-text-input.js';
+
+type Hooks = UiTextInputSceneHandle;
+type Page = import('@playwright/test').Page;
+
+const capture = (page: Page) =>
+  page.evaluate(() => {
+    const scene = window.__forgeTestHooks as unknown as Hooks;
+
+    scene.step();
+
+    const ink = scene.measureTextInk();
+
+    return {
+      value: scene.value,
+      isEditing: scene.isEditing,
+      submittedValues: scene.submittedValues,
+      cancelCount: scene.cancelCount,
+      isButtonFocused: scene.isButtonFocused,
+      inkWidth: ink ? ink.right - ink.left : 0,
+    };
+  });
+
+/** Steps a few frames so the typed text is shaped, laid out and drawn. */
+const settle = async (page: Page) => {
+  for (let frame = 0; frame < 3; frame++) {
+    // eslint-disable-next-line no-await-in-loop
+    await capture(page);
+  }
+
+  return capture(page);
+};
+
+const clickField = async (page: Page) => {
+  const center = await page.evaluate(
+    () => (window.__forgeTestHooks as unknown as Hooks).fieldCenter,
+  );
+
+  await page.mouse.click(center.x, center.y);
+};
+
+test.describe('ui text input', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/?scene=ui-text-input');
+    await page.waitForFunction(() => window.__forgeTestHooks !== undefined);
+    await settle(page);
+  });
+
+  test('clicking the field and typing draws the typed text', async ({
+    page,
+  }) => {
+    const empty = await settle(page);
+
+    expect(empty.inkWidth).toBe(0);
+
+    await clickField(page);
+    expect((await settle(page)).isEditing).toBe(true);
+
+    await page.keyboard.type('Ada');
+
+    const short = await settle(page);
+
+    expect(short.value).toBe('Ada');
+    expect(short.inkWidth).toBeGreaterThan(0);
+
+    await page.keyboard.type(' Lovelace');
+
+    const long = await settle(page);
+
+    expect(long.value).toBe('Ada Lovelace');
+    // Relative, same-run measurement: the drawn text gets wider as the
+    // value gets longer.
+    expect(long.inkWidth).toBeGreaterThan(short.inkWidth * 2);
+  });
+
+  test('Enter submits once even when held, and ends editing', async ({
+    page,
+  }) => {
+    await clickField(page);
+    await settle(page);
+    await page.keyboard.type('Ada');
+    await settle(page);
+
+    await page.keyboard.down('Enter');
+    await page.keyboard.down('Enter');
+    await page.keyboard.down('Enter');
+
+    const submitted = await settle(page);
+
+    await page.keyboard.up('Enter');
+
+    expect(submitted.submittedValues).toEqual(['Ada']);
+    expect(submitted.isEditing).toBe(false);
+  });
+
+  test('Escape cancels, keeping the value', async ({ page }) => {
+    await clickField(page);
+    await settle(page);
+    await page.keyboard.type('Ada');
+    await page.keyboard.press('Escape');
+
+    const cancelled = await settle(page);
+
+    expect(cancelled.cancelCount).toBe(1);
+    expect(cancelled.value).toBe('Ada');
+    expect(cancelled.isEditing).toBe(false);
+  });
+
+  test('keys typed into the field do not move UI focus or press the focused element', async ({
+    page,
+  }) => {
+    await clickField(page);
+    await settle(page);
+    await page.evaluate(() =>
+      (window.__forgeTestHooks as unknown as Hooks).focusButton(),
+    );
+
+    await page.keyboard.press('ArrowDown');
+    await page.keyboard.press('ArrowRight');
+    await page.keyboard.type('x');
+
+    const typed = await settle(page);
+
+    expect(typed.isButtonFocused).toBe(true);
+    expect(typed.isEditing).toBe(true);
+    expect(typed.value).toBe('x');
+  });
+
+  test('hovering another element does not end editing', async ({ page }) => {
+    await clickField(page);
+    await settle(page);
+
+    const button = await page.evaluate(
+      () => (window.__forgeTestHooks as unknown as Hooks).buttonCenter,
+    );
+
+    await page.mouse.move(button.x, button.y);
+
+    const hovered = await settle(page);
+
+    expect(hovered.isButtonFocused).toBe(true);
+    expect(hovered.isEditing).toBe(true);
+  });
+
+  test('a tap on a panel covering the field does not start editing it', async ({
+    page,
+  }) => {
+    await page.evaluate(() =>
+      (window.__forgeTestHooks as unknown as Hooks).setCoverVisible(true),
+    );
+    await settle(page);
+    await clickField(page);
+
+    expect((await settle(page)).isEditing).toBe(false);
+  });
+});
diff --git a/src/ui/components/text-input-component.ts b/src/ui/components/text-input-component.ts
index e50da1dcc..3d82b6b9a 100644
--- a/src/ui/components/text-input-component.ts
+++ b/src/ui/components/text-input-component.ts
@@ -8,8 +8,8 @@ import type {
 
 /**
  * The HTML attributes a text field's hidden input carries (see
- * `TextEntryAttributes`), except `maxLength`, which is the field's own
- * {@link TextInputDefaultedOptions.maxLength}.
+ * `TextEntryAttributes`), except `maxLength`: a field applies its own
+ * {@link TextInputDefaultedOptions.maxLength} after filtering.
  */
 export type TextInputAttributes = Omit<TextEntryAttributes, 'maxLength'>;
 
diff --git a/src/ui/systems/ui-text-input-system.ts b/src/ui/systems/ui-text-input-system.ts
index 0c089d71b..64c871b01 100644
--- a/src/ui/systems/ui-text-input-system.ts
+++ b/src/ui/systems/ui-text-input-system.ts
@@ -538,10 +538,10 @@ export const createUiTextInputEcsSystem = (
         current.add(textInput);
         entries.set(textInput, entry);
 
-        entry.setAttributes({
-          ...textInput.attributes,
-          maxLength: textInput.maxLength,
-        });
+        // `maxLength` isn't passed on as the input's `maxlength`: the
+        // browser would count characters the filters are about to remove,
+        // so the field applies it itself, after filtering.
+        entry.setAttributes(textInput.attributes);
 
         updateEditing(world, entity, textInput, interactables[i]);
 

From 8f87a6f7f26b69e6c2dbf1286b0285287c96a086 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 6 Oct 2026 22:34:06 +0000
Subject: [PATCH 3/4] test(ui): cover text input edge cases

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014VktGvQk7RUMN8yxuAUXER
---
 src/input/text-entry/text-entry.test.ts       | 28 ++++++
 .../components/text-input-component.test.ts   | 18 ++++
 src/ui/systems/ui-text-input-system.test.ts   | 85 +++++++++++++++++++
 src/ui/utilities/create-text-input.test.ts    | 24 ++++++
 src/ui/utilities/raycast-ui-canvas.test.ts    | 13 +++
 5 files changed, 168 insertions(+)

diff --git a/src/input/text-entry/text-entry.test.ts b/src/input/text-entry/text-entry.test.ts
index be61fc0fe..feeaa1168 100644
--- a/src/input/text-entry/text-entry.test.ts
+++ b/src/input/text-entry/text-entry.test.ts
@@ -166,6 +166,34 @@ describe('createTextEntry', () => {
     expect(keyDown('KeyA', { repeat: true }).defaultPrevented).toBe(false);
   });
 
+  it('stops letting a key auto-repeat once it is released', () => {
+    entry.focus();
+    keyDown('KeyA');
+    entry.element.dispatchEvent(
+      new KeyboardEvent('keyup', { code: 'KeyA', bubbles: true }),
+    );
+
+    expect(keyDown('KeyA', { repeat: true }).defaultPrevented).toBe(true);
+  });
+
+  it('starts a composition from an update that arrives without a start', () => {
+    entry.setValue('ab');
+    entry.setSelection(1, 1);
+    entry.element.dispatchEvent(
+      new CompositionEvent('compositionupdate', { data: 'x' }),
+    );
+
+    expect(entry.composition).toEqual({ start: 1, end: 2 });
+  });
+
+  it('ends a composition when the input loses focus', () => {
+    entry.focus();
+    entry.element.dispatchEvent(new CompositionEvent('compositionstart'));
+    entry.blur();
+
+    expect(entry.composition).toBeNull();
+  });
+
   it('tracks the IME composition range and reports its end as a change', () => {
     entry.setValue('ab');
     entry.setSelection(2, 2);
diff --git a/src/ui/components/text-input-component.test.ts b/src/ui/components/text-input-component.test.ts
index c30c219bd..f355acc57 100644
--- a/src/ui/components/text-input-component.test.ts
+++ b/src/ui/components/text-input-component.test.ts
@@ -35,6 +35,24 @@ describe('TextInputEcsComponent', () => {
     expect(entry.value).toBe('start');
   });
 
+  it("starts from the entry's own value when no value is given", () => {
+    const world = new EcsWorld();
+    const entry = createTextEntry(document.createElement('div'));
+
+    entry.setValue('kept');
+
+    const component = addTextInputComponent(world, world.createEntity(), {
+      entry,
+      textLabel: world.createEntity(),
+      placeholderLabel: world.createEntity(),
+      caret: world.createEntity(),
+      selection: world.createEntity(),
+      compositionUnderline: world.createEntity(),
+    });
+
+    expect(component.value).toBe('kept');
+  });
+
   it("setTextInputValue writes the field's entry", () => {
     const { world, entity, entry, component } = build();
 
diff --git a/src/ui/systems/ui-text-input-system.test.ts b/src/ui/systems/ui-text-input-system.test.ts
index 91956a1b5..f9a607d1d 100644
--- a/src/ui/systems/ui-text-input-system.test.ts
+++ b/src/ui/systems/ui-text-input-system.test.ts
@@ -205,6 +205,28 @@ describe('createUiTextInputEcsSystem', () => {
     expect(textInput.value).toBe('a');
   });
 
+  it('raises no change when every typed character is filtered out', () => {
+    const listener = vi.fn();
+
+    field.onValueChanged.registerListener(listener);
+    type('é');
+    world.update();
+
+    expect(textInput.value).toBe('');
+    expect(textInput.entry.value).toBe('');
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('stops editing a field that becomes non-interactable', () => {
+    editTextInput(world, field.entity);
+    world.update();
+
+    field.interactable.interactable = false;
+    world.update();
+
+    expect(textInput.isEditing).toBe(false);
+  });
+
   it('starts editing when the field is invoked', () => {
     field.interactable.wasInvokedThisFrame = true;
     world.update();
@@ -362,6 +384,69 @@ describe('createUiTextInputEcsSystem', () => {
     expect(style.height).toBe('40px');
   });
 
+  it('does not move the hidden input for a field on a world-space canvas', () => {
+    const worldCanvas = world.createEntity();
+
+    addPositionComponent(world, worldCanvas);
+    addRectTransformComponent(world, worldCanvas);
+    addCanvasComponent(world, worldCanvas, {
+      renderMode: 'worldSpace',
+      camera: world.createEntity(),
+    });
+
+    const worldField = createTextInput(world, worldCanvas, {
+      renderContext,
+      sprite: buildSprite(),
+      fillSprite: buildSprite(),
+      fontAtlas,
+      size: 20,
+    });
+
+    world.update();
+
+    expect(worldField.textInput.entry.element.style.left).toBe('0px');
+  });
+
+  it("does not move the hidden input when the canvas's camera is missing", () => {
+    const canvasWithoutCamera = world.createEntity();
+
+    addPositionComponent(world, canvasWithoutCamera);
+    addRectTransformComponent(world, canvasWithoutCamera);
+    addCanvasComponent(world, canvasWithoutCamera, {
+      camera: world.createEntity(),
+    });
+
+    const orphan = createTextInput(world, canvasWithoutCamera, {
+      renderContext,
+      sprite: buildSprite(),
+      fillSprite: buildSprite(),
+      fontAtlas,
+      size: 20,
+    });
+
+    world.update();
+
+    expect(orphan.textInput.entry.element.style.left).toBe('0px');
+  });
+
+  it('ignores presses that are not on a field, or not with the primary button', () => {
+    world.update();
+
+    const mouseDown = pointer('mousedown', 10, 10);
+
+    container.dispatchEvent(mouseDown);
+    expect(mouseDown.defaultPrevented).toBe(false);
+
+    container.dispatchEvent(
+      new MouseEvent('pointerdown', { clientX: 400, clientY: 300, button: 2 }),
+    );
+    container.dispatchEvent(
+      new MouseEvent('pointerup', { clientX: 400, clientY: 300, button: 2 }),
+    );
+
+    expect(document.activeElement).not.toBe(textInput.entry.element);
+  });
+
   it('focuses the field inside the tap that lands on it', () => {
     world.update();
 
diff --git a/src/ui/utilities/create-text-input.test.ts b/src/ui/utilities/create-text-input.test.ts
index edc780e88..8eb249a1b 100644
--- a/src/ui/utilities/create-text-input.test.ts
+++ b/src/ui/utilities/create-text-input.test.ts
@@ -12,6 +12,7 @@ import type { FontAtlas } from '../../text/font-atlas/font-atlas.js';
 import { textId } from '../../text/index.js';
 import { uiColorTransitionId } from '../components/ui-color-transition-component.js';
 import { uiInteractableId } from '../components/ui-interactable-component.js';
+import { rectTransformId } from '../components/rect-transform-component.js';
 import { textInputId } from '../components/text-input-component.js';
 
 const fontAtlas = {
@@ -98,6 +99,29 @@ describe('createTextInput', () => {
     }
   });
 
+  it('passes the anchored position, filter and category through', () => {
+    const world = new EcsWorld();
+    const filter = (text: string): string => text.toUpperCase();
+
+    const field = createTextInput(world, world.createEntity(), {
+      renderContext,
+      sprite: buildSprite(),
+      fillSprite: buildSprite(),
+      fontAtlas,
+      size: 20,
+      anchoredPosition: { x: 10, y: 20 },
+      filter,
+      category: 4,
+    });
+
+    expect(
+      world.getComponent(field.entity, rectTransformId)!.anchoredPosition,
+    ).toEqual({ x: 10, y: 20 });
+    expect(field.textInput.filter).toBe(filter);
+    expect(field.textInput.maxLength).toBe(Number.POSITIVE_INFINITY);
+    expect(world.getComponent(field.textLabel, textId)!.category).toBe(4);
+  });
+
   it('throws when the render context canvas has no parent element', () => {
     const world = new EcsWorld();
 
diff --git a/src/ui/utilities/raycast-ui-canvas.test.ts b/src/ui/utilities/raycast-ui-canvas.test.ts
index 130b95c62..aa117dcb9 100644
--- a/src/ui/utilities/raycast-ui-canvas.test.ts
+++ b/src/ui/utilities/raycast-ui-canvas.test.ts
@@ -70,6 +70,19 @@ describe('raycastUiCanvas', () => {
     ).toBeNull();
   });
 
+  it("returns null when the canvas's camera can't convert the position", () => {
+    const world = new EcsWorld();
+    const canvas = world.createEntity();
+
+    addPositionComponent(world, canvas);
+    addRectTransformComponent(world, canvas);
+    addCanvasComponent(world, canvas, { camera: world.createEntity() });
+
+    expect(
+      raycastUiCanvas(world, canvas, renderContext, { x: 400, y: 300 }),
+    ).toBeNull();
+  });
+
   it("ignores another canvas's elements", () => {
     const world = new EcsWorld();
     const canvas = buildCanvas(world);

From f220337bc94910c7f05552e066d2fcad03cdbf0b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 6 Oct 2026 23:09:23 +0000
Subject: [PATCH 4/4] style(text): format text shaping system

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014VktGvQk7RUMN8yxuAUXER
---
 src/text/systems/text-shaping-system.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/text/systems/text-shaping-system.ts b/src/text/systems/text-shaping-system.ts
index 67e1714d9..1841f44e9 100644
--- a/src/text/systems/text-shaping-system.ts
+++ b/src/text/systems/text-shaping-system.ts
@@ -144,7 +144,7 @@ export const createTextShapingEcsSystem = (
             verticalAlign: textComponent.verticalAlign,
             maxWidth: textComponent.maxWidth,
             horizontalAlignPivot: textComponent.horizontalAlignPivot,
-          richText: textComponent.richText,
+            richText: textComponent.richText,
           },
         );