A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(native): a device's soft keyboard is the field's editing surface
esenginec91de5fe7f9d
diff --git a/build-tools/tasks/nativePackage.js b/build-tools/tasks/nativePackage.jsindex 8bd56c5fd..d26d3a175 100644--- a/build-tools/tasks/nativePackage.js+++ b/build-tools/tasks/nativePackage.js@@ -8,7 +8,7 @@import path from 'path';import { existsSync, readFileSync } from 'fs';-import { mkdir, copyFile, cp, rm, writeFile } from 'fs/promises';+import { mkdir, copyFile, cp, rm, writeFile, readdir } from 'fs/promises';import config from '../build.config.js';import * as logger from '../utils/logger.js';import { runCommand } from '../utils/emscripten.js';@@ -27,6 +27,11 @@ const HOST_LIBRARY = 'libestella_js_host.so';export const BYTECODE_FILE = 'esengine.native.qjsbc';const MANIFEST_TEMPLATE = path.join('native', 'android', 'host', 'AndroidManifest.xml.in');+/** The Java shim's sources — the IME's own side of an editable field, which has+ * to be Java because only a Java View gets an InputConnection to compose into+ * (see native/android/java/.../TextEditor.java). */+const JAVA_DIR = path.join('native', 'android', 'java');+/** The APK is named after the app it contains, so packaging a second project does* not quietly replace the first one's file. */const apkName = (appId) => `${appId.split('.').pop() || 'estella'}.apk`;@@ -55,6 +60,41 @@ async function debugKeystore(jdk) {// a zip entry name must use forward slashes — so AAssetManager could not open// anything in a subdirectory. Invisible while the packaged content was a handful// of flat files; every real project export has directories.+/**+ * Compile the Java shim to a classes.dex in `staging`. javac + d8 are already+ * beside the tools packaging uses (the JDK apksigner needs, the build-tools aapt2+ * comes from), so this stays a plain APK build with no Gradle. Returns false when+ * there is nothing to compile, which leaves an APK whose host reports no editing+ * surface rather than one that fails to build.+ */+async function compileJavaShim(staging, sdk, platform, jdk, rootDir) {+ const sourceDir = path.join(rootDir, JAVA_DIR);+ if (!existsSync(sourceDir)) return false;+ const sources = (await readdir(sourceDir, { recursive: true }))+ .filter((f) => String(f).endsWith('.java'))+ .map((f) => path.join(sourceDir, String(f)));+ if (sources.length === 0) return false;++ const classes = path.join(staging, 'classes');+ await mkdir(classes, { recursive: true });+ // Java 8 bytecode: d8 accepts it everywhere, and the shim uses nothing newer.+ await runCommand(jdkTool('javac', jdk), [+ // The sources are UTF-8; javac otherwise reads them in the platform's+ // default charset, which on a Windows build machine is not.+ '-encoding', 'UTF-8', '-source', '8', '-target', '8', '-nowarn',+ '-bootclasspath', platformJar(sdk, platform),+ '-d', classes, ...sources,+ ]);+ const classFiles = (await readdir(classes, { recursive: true }))+ .filter((f) => String(f).endsWith('.class'))+ .map((f) => path.join(classes, String(f)));+ await runCommand(buildTool(sdk, 'd8'), [+ '--lib', platformJar(sdk, platform),+ '--output', staging, ...classFiles,+ ]);+ return existsSync(path.join(staging, 'classes.dex'));+}+async function addToApk(apk, stagingDir, entries, jdk) {await runCommand(jdkTool('jar', jdk), ['ufM', apk, ...entries.flatMap((e) => ['-C', stagingDir, e])]);}@@ -127,6 +167,10 @@ export async function packageNativeApk(options = {}) {// The app the content asks to be: identity, version, and the orientation the// OS must lock the window to. The manifest is a template because all four vary// per project — a static one is why every example installed over the last.+ logger.step('Compiling the Java shim (javac + d8)...');+ const hasDex = await compileJavaShim(staging, sdk, platform, options.jdk, rootDir);+ if (!hasDex) logger.warn('No classes.dex: the app will have no soft keyboard (typing is off).');+const app = readAppConfig(content, (m) => logger.warn(m));const manifest = path.join(staging, 'AndroidManifest.xml');await writeFile(manifest, fillTemplate(readFileSync(path.join(rootDir, MANIFEST_TEMPLATE), 'utf8'), {@@ -135,6 +179,7 @@ export async function packageNativeApk(options = {}) {VERSION_NAME: app.version,VERSION_CODE: app.versionCode,SCREEN_ORIENTATION: androidScreenOrientation(app.orientation),+ HAS_CODE: hasDex ? 'true' : 'false',}));logger.info(`App: ${app.name} (${app.id}) v${app.version} — ${app.orientation}`);@@ -151,7 +196,7 @@ export async function packageNativeApk(options = {}) {]);logger.step('Adding the native libraries and the game...');- await addToApk(unsigned, staging, ['lib', 'assets'], options.jdk);+ await addToApk(unsigned, staging, ['lib', 'assets', ...(hasDex ? ['classes.dex'] : [])], options.jdk);logger.step('Aligning + signing...');await rm(aligned, { force: true });diff --git a/build-tools/utils/android.js b/build-tools/utils/android.jsindex 32cd27e6a..fe1b0b8a6 100644--- a/build-tools/utils/android.js+++ b/build-tools/utils/android.js@@ -42,8 +42,10 @@ const exe = process.platform === 'win32' ? '.exe' : '';export function buildTool(sdk, name) {const dir = newest(path.join(sdk, 'build-tools'));if (!dir) throw new Error(`No build-tools under ${sdk}/build-tools. Install them via the SDK Manager.`);- // apksigner is a script (.bat on Windows), the rest are native binaries.- const suffix = name === 'apksigner' ? (process.platform === 'win32' ? '.bat' : '') : exe;+ // apksigner and d8 are JVM launchers — a shell script, or a .bat on Windows;+ // the rest are native binaries.+ const script = name === 'apksigner' || name === 'd8';+ const suffix = script ? (process.platform === 'win32' ? '.bat' : '') : exe;const tool = path.join(dir, name + suffix);if (!existsSync(tool)) throw new Error(`${name} not found at ${tool}.`);return tool;diff --git a/native/CMakeLists.txt b/native/CMakeLists.txtindex b34f5ce41..2a8bf2895 100644--- a/native/CMakeLists.txt+++ b/native/CMakeLists.txt@@ -207,6 +207,7 @@ if(ESTELLA_QUICKJS_DIR)host/bindings/AssetBindings.cpphost/bindings/AudioBindings.cpphost/bindings/NetBindings.cpp+ host/bindings/TextEditorBindings.cpphost/media/native_audio.cpphost/media/ktx2_decode.cpphost/media/glyph_raster.cppdiff --git a/native/android/host/AndroidManifest.xml.in b/native/android/host/AndroidManifest.xml.inindex abf7f6515..19738a07e 100644--- a/native/android/host/AndroidManifest.xml.in+++ b/native/android/host/AndroidManifest.xml.in@@ -4,9 +4,10 @@the exported project's app.config.json: an installed app has one identity, oneversion and one orientation, and none of them can be decided here.- Everything left alone is the host itself: a NativeActivity (no Java, so hasCode- is false), Vulkan 1.0.3 as a hard requirement, and the config changes the host- handles rather than being restarted for.+ Everything left alone is the host itself: a NativeActivity, Vulkan 1.0.3 as a+ hard requirement, and the config changes the host handles rather than being+ restarted for. `hasCode` follows whether the Java shim compiled — the game is+ native, and the only Java in the package is the IME's side of a text field.--><manifest xmlns:android="http://schemas.android.com/apk/res/android"package="@APP_ID@"@@ -14,7 +15,7 @@android:versionName="@VERSION_NAME@"><uses-sdk android:minSdkVersion="26" android:targetSdkVersion="33" /><uses-feature android:name="android.hardware.vulkan.version" android:version="0x400003" android:required="true" />- <application android:label="@APP_NAME@" android:hasCode="false" android:extractNativeLibs="true">+ <application android:label="@APP_NAME@" android:hasCode="@HAS_CODE@" android:extractNativeLibs="true"><!-- A game's window, stated before any code runs: no title, no status bar.The host asks for the rest (navigation bar, display cutout) once ithas the UI thread — see onWindowFocusChanged in platform/android.cpp. -->diff --git a/native/android/java/com/estella/host/TextEditor.java b/native/android/java/com/estella/host/TextEditor.javanew file mode 100644index 000000000..ef7ca5aaa--- /dev/null+++ b/native/android/java/com/estella/host/TextEditor.java@@ -0,0 +1,181 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+package com.estella.host;++import android.app.Activity;+import android.text.Editable;+import android.text.InputType;+import android.text.TextWatcher;+import android.view.Gravity;+import android.view.KeyEvent;+import android.view.View;+import android.view.ViewGroup;+import android.view.inputmethod.BaseInputConnection;+import android.view.inputmethod.EditorInfo;+import android.view.inputmethod.InputMethodManager;+import android.widget.EditText;+import android.widget.TextView;++/**+ * The app's editing surface: one real EditText, invisible, that the IME talks to.+ *+ * An IME does not deliver composed text (Chinese, Japanese, prediction) as key+ * events -- it commits through an InputConnection, which only a Java View has.+ * That is the whole reason this class exists: everything else about the field --+ * how it looks, where the caret is, what it does with the text -- is engine code+ * on the other side of the JNI, and this holds only what the platform insists on+ * owning.+ *+ * Every method that touches the view runs on the UI thread; the native side calls+ * in from the game thread, and reports go back the other way through the static+ * natives, whose C++ queues them for the next frame.+ */+public final class TextEditor implements TextWatcher {++ private final Activity activity;+ private EditText field;+ /** Set while the native side is writing, so its own write is not reported back. */+ private boolean writing;++ public TextEditor(Activity activity) {+ this.activity = activity;+ }++ /** Open the keyboard on `value`, with the caret/selection where the field has it. */+ public void focus(final String value, final int selectionStart, final int selectionEnd,+ final boolean multiline, final int maxLength, final boolean password) {+ activity.runOnUiThread(new Runnable() {+ @Override public void run() {+ ensureField();+ writing = true;+ field.setInputType(inputType(multiline, password));+ field.setImeOptions(multiline ? EditorInfo.IME_ACTION_NONE : EditorInfo.IME_ACTION_DONE);+ field.setFilters(maxLength > 0+ ? new android.text.InputFilter[] { new android.text.InputFilter.LengthFilter(maxLength) }+ : new android.text.InputFilter[0]);+ field.setText(value);+ setSelection(selectionStart, selectionEnd);+ writing = false;+ field.setVisibility(View.VISIBLE);+ field.requestFocus();+ imm().showSoftInput(field, InputMethodManager.SHOW_IMPLICIT);+ }+ });+ }++ /** Close the keyboard and give up focus. */+ public void blur() {+ activity.runOnUiThread(new Runnable() {+ @Override public void run() {+ if (field == null) return;+ imm().hideSoftInputFromWindow(field.getWindowToken(), 0);+ field.clearFocus();+ // Gone, not invisible: a focusable view left in the tree can take+ // focus back from the game's own surface on the next layout.+ field.setVisibility(View.GONE);+ }+ });+ }++ /** Adopt a value + selection the app decided (setValue, a tap that moved the caret). */+ public void write(final String value, final int selectionStart, final int selectionEnd) {+ activity.runOnUiThread(new Runnable() {+ @Override public void run() {+ if (field == null) return;+ writing = true;+ if (!field.getText().toString().equals(value)) field.setText(value);+ setSelection(selectionStart, selectionEnd);+ writing = false;+ }+ });+ }++ // -- TextWatcher: the IME's commits and the user's typing --------------------++ @Override public void beforeTextChanged(CharSequence s, int start, int count, int after) {}++ @Override public void onTextChanged(CharSequence s, int start, int before, int count) {}++ @Override public void afterTextChanged(Editable s) {+ report();+ }++ /** Hand the field's whole state to the engine. Composing is asked of the+ * Editable itself: a preedit is a span the IME put there, not a flag. */+ private void report() {+ if (writing || field == null) return;+ final Editable text = field.getText();+ final boolean composing = BaseInputConnection.getComposingSpanStart(text) >= 0+ && BaseInputConnection.getComposingSpanEnd(text) >= 0;+ nativeState(text.toString(), field.getSelectionStart(), field.getSelectionEnd(), composing);+ }++ private void setSelection(int start, int end) {+ final int len = field.getText().length();+ field.setSelection(clamp(start, len), clamp(end, len));+ }++ private static int clamp(int index, int length) {+ return index < 0 ? 0 : (index > length ? length : index);+ }++ private static int inputType(boolean multiline, boolean password) {+ if (password) return InputType.TYPE_CLASS_TEXT | InputType.TYPE_TEXT_VARIATION_PASSWORD;+ int type = InputType.TYPE_CLASS_TEXT;+ if (multiline) type |= InputType.TYPE_TEXT_FLAG_MULTI_LINE;+ return type;+ }++ private InputMethodManager imm() {+ return (InputMethodManager) activity.getSystemService(Activity.INPUT_METHOD_SERVICE);+ }++ /** The view, created on first use and left in the tree. 1x1 and transparent:+ * it must be a real, laid-out, focusable view for the IME to attach to it,+ * but the game draws the field itself. */+ private void ensureField() {+ if (field != null) return;+ field = new EditText(activity) {+ @Override protected void onSelectionChanged(int start, int end) {+ super.onSelectionChanged(start, end);+ report(); // a caret move is state too, and TextWatcher never sees it+ }+ };+ field.setBackgroundColor(0);+ field.setTextColor(0);+ field.setCursorVisible(false);+ field.setSingleLine(false);+ field.addTextChangedListener(this);+ field.setOnEditorActionListener(new TextView.OnEditorActionListener() {+ @Override public boolean onEditorAction(TextView v, int actionId, KeyEvent event) {+ if (actionId == EditorInfo.IME_ACTION_DONE || actionId == EditorInfo.IME_ACTION_GO+ || actionId == EditorInfo.IME_ACTION_SEND+ || (event != null && event.getKeyCode() == KeyEvent.KEYCODE_ENTER)) {+ nativeSubmit();+ return true;+ }+ return false;+ }+ });+ // Back dismisses the keyboard without committing — the field should lose+ // focus, exactly as Escape does on the web.+ field.setOnKeyListener(new View.OnKeyListener() {+ @Override public boolean onKey(View v, int keyCode, KeyEvent event) {+ if (keyCode == KeyEvent.KEYCODE_BACK && event.getAction() == KeyEvent.ACTION_UP) {+ nativeCancel();+ return true;+ }+ return false;+ }+ });+ final ViewGroup.LayoutParams params = new ViewGroup.LayoutParams(1, 1);+ field.setGravity(Gravity.TOP | Gravity.START);+ activity.addContentView(field, params);+ }++ // -- Into the engine (registered from C++ with RegisterNatives) --------------++ private static native void nativeState(String value, int selectionStart, int selectionEnd, boolean composing);+ private static native void nativeSubmit();+ private static native void nativeCancel();+}diff --git a/native/host/Bindings.hpp b/native/host/Bindings.hppindex a861d8afa..86b35b246 100644--- a/native/host/Bindings.hpp+++ b/native/host/Bindings.hpp@@ -51,8 +51,17 @@ void registerAudioBindings(HostState& h, JSValue global);/** es_fetch over the platform's native networking. */void registerNetBindings(HostState& h, JSValue global);+/** es_textEditor_* over the platform's soft keyboard — bound ONLY when the+ * platform has one, so the SDK gates its editing surface on real availability+ * exactly as it does audio. */+void registerTextEditorBindings(HostState& h, JSValue global);+/** Run the JS callbacks for HTTP replies that arrived since the last frame. JS* thread only; {@link deliverFetch} queued them from the completion thread. */void drainFetches(HostState& h);+/** Push what the editing surface did since the last frame into JS. JS thread+ * only; the deliverTextEditor* calls queued it from the platform's UI thread. */+void drainTextEditor(HostState& h);+} // namespace eshostdiff --git a/native/host/Host.hpp b/native/host/Host.hppindex 0494c6267..6c60b560a 100644--- a/native/host/Host.hpp+++ b/native/host/Host.hpp@@ -110,6 +110,25 @@ struct Platform {* with the same `req.id`. The OS owns the TLS stack, so this is where native* networking necessarily differs between iOS and Android. */virtual void startFetch(const FetchRequest& req) = 0;++ /**+ * The OS text-editing surface: a soft keyboard with its IME. A platform that+ * has one overrides these and reports what the user did through+ * {@link deliverTextEditorState} / Submit / Cancel; one that does not leaves+ * the defaults, `hasTextEditor()` stays false, the es_textEditor_* entry+ * points are never bound, and the SDK sees a realm where fields render but+ * cannot be typed into.+ *+ * The surface OWNS the value and the selection while a field is focused —+ * an IME composes into it, and the app's own edits go through `write`.+ */+ virtual bool hasTextEditor() const { return false; }+ virtual void textEditorFocus(const std::string& /*value*/, int /*selectionStart*/,+ int /*selectionEnd*/, bool /*multiline*/,+ int /*maxLength*/, bool /*password*/) {}+ virtual void textEditorBlur() {}+ virtual void textEditorWrite(const std::string& /*value*/, int /*selectionStart*/,+ int /*selectionEnd*/) {}};/** Deliver an HTTP reply for a {@link Platform::startFetch}. Thread-safe: the@@ -117,6 +136,16 @@ struct Platform {* queued and the JS callback runs on the next frame, on the JS thread. */void deliverFetch(FetchResult result);+/** The editing surface's whole state, after the user (or its IME) changed it.+ * Thread-safe, like {@link deliverFetch}: the platform calls it from its UI+ * thread and the JS side is told on the next frame. `composing` is true while an+ * IME preedit sits inside `value`. */+void deliverTextEditorState(std::string value, int selectionStart, int selectionEnd, bool composing);+/** The keyboard's done/go key on a single-line field. Thread-safe. */+void deliverTextEditorSubmit();+/** The keyboard was dismissed without committing (back gesture, done). Thread-safe. */+void deliverTextEditorCancel();+/** @brief Boots Dawn, EstellaContext, QuickJS, the SDK bundle and the packaged* project. Call once, when a window first exists; @p platform must* outlive the host.diff --git a/native/host/Runtime.cpp b/native/host/Runtime.cppindex f7869519f..4e9754acc 100644--- a/native/host/Runtime.cpp+++ b/native/host/Runtime.cpp@@ -378,6 +378,7 @@ void initRuntime(HostState& h) {registerAssetBindings(h, global);registerAudioBindings(h, global);registerNetBindings(h, global);+ registerTextEditorBindings(h, global);// The generated halves: per-component accessors, then the engine's binding// entry points — both from the same reflection the web's embind bindings comediff --git a/native/host/bindings/TextEditorBindings.cpp b/native/host/bindings/TextEditorBindings.cppnew file mode 100644index 000000000..120b4d977--- /dev/null+++ b/native/host/bindings/TextEditorBindings.cpp@@ -0,0 +1,159 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file TextEditorBindings.cpp+ * @brief es_textEditor_* over the platform's soft keyboard, and the+ * thread-safe hand-back that makes it usable from JS.+ * @details Host-owned, and for the same reason networking is: the editing surface+ * IS the OS — its keyboard layouts, its IME, its candidate window. The+ * SDK asks for one through a single contract (PlatformTextEditor); this+ * is the device's side of it.+ *+ * The keyboard reports on the OS UI thread, which is not the JS thread,+ * so a report is queued as POD and drained in the frame loop — the same+ * shape {@link deliverFetch} uses, and for the same reason: no JS value+ * is ever touched off-thread.+ *+ * @author ESEngine Team+ * @date 2026+ *+ * @copyright Copyright (c) 2026 ESEngine Team+ * Licensed under the Apache License, Version 2.0.+ */+#include "Bindings.hpp"++#include <mutex>+#include <queue>+#include <string>+#include <utility>++using namespace esengine;++namespace eshost {+namespace {++/** One thing the surface did, as POD — what crosses the thread boundary. */+struct EditorPush {+ enum class Kind { State, Submit, Cancel };+ Kind kind = Kind::State;+ std::string value;+ int selectionStart = 0;+ int selectionEnd = 0;+ bool composing = false;+};++// Namespace-scope, so the deliver* functions (which the glue calls from the UI+// thread) are safe before boot and after teardown alike.+std::mutex g_mutex;+std::queue<EditorPush> g_queue;++void push(EditorPush item) {+ std::lock_guard<std::mutex> lk(g_mutex);+ g_queue.push(std::move(item));+}++std::string argString(JSContext* ctx, JSValueConst v) {+ std::string out;+ if (const char* s = JS_ToCString(ctx, v)) {+ out = s;+ JS_FreeCString(ctx, s);+ }+ return out;+}++int argInt(JSContext* ctx, JSValueConst v) {+ int32_t out = 0;+ JS_ToInt32(ctx, &out, v);+ return out;+}++// es_textEditor_focus(value, selectionStart, selectionEnd, multiline, maxLength, password)+JSValue js_textEditor_focus(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 6 || !hostAlive() || !host().platform) return JS_UNDEFINED;+ host().platform->textEditorFocus(argString(ctx, argv[0]), argInt(ctx, argv[1]),+ argInt(ctx, argv[2]), JS_ToBool(ctx, argv[3]) != 0,+ argInt(ctx, argv[4]), JS_ToBool(ctx, argv[5]) != 0);+ return JS_UNDEFINED;+}++JSValue js_textEditor_blur(JSContext*, JSValueConst, int, JSValueConst*) {+ if (hostAlive() && host().platform) host().platform->textEditorBlur();+ return JS_UNDEFINED;+}++// es_textEditor_write(value, selectionStart, selectionEnd)+JSValue js_textEditor_write(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 3 || !hostAlive() || !host().platform) return JS_UNDEFINED;+ host().platform->textEditorWrite(argString(ctx, argv[0]), argInt(ctx, argv[1]),+ argInt(ctx, argv[2]));+ return JS_UNDEFINED;+}++/** The push as the SDK's `es_onNativeTextEditor` reads it. */+JSValue makePush(HostState& h, const EditorPush& item) {+ JSValue obj = JS_NewObject(h.js);+ switch (item.kind) {+ case EditorPush::Kind::State:+ JS_SetPropertyStr(h.js, obj, "kind", JS_NewString(h.js, "state"));+ JS_SetPropertyStr(h.js, obj, "value", JS_NewString(h.js, item.value.c_str()));+ JS_SetPropertyStr(h.js, obj, "selectionStart", JS_NewInt32(h.js, item.selectionStart));+ JS_SetPropertyStr(h.js, obj, "selectionEnd", JS_NewInt32(h.js, item.selectionEnd));+ JS_SetPropertyStr(h.js, obj, "composing", JS_NewBool(h.js, item.composing));+ break;+ case EditorPush::Kind::Submit:+ JS_SetPropertyStr(h.js, obj, "kind", JS_NewString(h.js, "submit"));+ break;+ case EditorPush::Kind::Cancel:+ JS_SetPropertyStr(h.js, obj, "kind", JS_NewString(h.js, "cancel"));+ break;+ }+ return obj;+}++} // namespace++void drainTextEditor(HostState& h) {+ std::queue<EditorPush> pending;+ { std::lock_guard<std::mutex> lk(g_mutex); pending.swap(g_queue); }+ if (pending.empty()) return;++ JSValue global = JS_GetGlobalObject(h.js);+ JSValue fn = JS_GetPropertyStr(h.js, global, "es_onNativeTextEditor");+ while (!pending.empty()) {+ const EditorPush item = std::move(pending.front());+ pending.pop();+ if (!JS_IsFunction(h.js, fn)) continue; // the SDK has not installed it (yet)+ JSValue arg = makePush(h, item);+ JSValue ret = JS_Call(h.js, fn, JS_UNDEFINED, 1, &arg);+ if (JS_IsException(ret)) logJsError(h.js, "es_onNativeTextEditor");+ JS_FreeValue(h.js, ret);+ JS_FreeValue(h.js, arg);+ }+ JS_FreeValue(h.js, fn);+ JS_FreeValue(h.js, global);+}++void registerTextEditorBindings(HostState& h, JSValue global) {+ // Only when the platform has a keyboard: the SDK treats the entry points as+ // an all-or-nothing group, so a half-bound host has no surface at all rather+ // than one that opens a keyboard nobody reads.+ if (!h.platform || !h.platform->hasTextEditor()) return;+ bindGlobal(h, global, "es_textEditor_focus", js_textEditor_focus, 6);+ bindGlobal(h, global, "es_textEditor_blur", js_textEditor_blur, 0);+ bindGlobal(h, global, "es_textEditor_write", js_textEditor_write, 3);+}++// Thread-safe: the platform reports from its UI thread, the frame loop delivers.+void deliverTextEditorState(std::string value, int selectionStart, int selectionEnd, bool composing) {+ push({EditorPush::Kind::State, std::move(value), selectionStart, selectionEnd, composing});+}++void deliverTextEditorSubmit() {+ push({EditorPush::Kind::Submit, {}, 0, 0, false});+}++void deliverTextEditorCancel() {+ push({EditorPush::Kind::Cancel, {}, 0, 0, false});+}++} // namespace eshostdiff --git a/native/host/platform/android.cpp b/native/host/platform/android.cppindex 432846b9a..942565df4 100644--- a/native/host/platform/android.cpp+++ b/native/host/platform/android.cpp@@ -246,10 +246,140 @@ struct AndroidPlatform final : eshost::Platform {eshost::deliverFetch(std::move(r));}).detach();}++ // -- The editing surface: com.estella.host.TextEditor ---------------------+ //+ // An IME commits composed text through an InputConnection, which only a Java+ // View has — so the keyboard's own side of a field is a small Java class in+ // the APK, and this is the call across. The class handles its own threading+ // (every method posts to the UI thread), so these can be called from the+ // frame loop like any other platform call.++ /** Set once the shim class is loaded and its natives registered (UI thread). */+ jobject editor = nullptr; // global ref to the TextEditor instance+ jmethodID editorFocus = nullptr;+ jmethodID editorBlur = nullptr;+ jmethodID editorWrite = nullptr;++ bool hasTextEditor() const override { return editor != nullptr; }++ void textEditorFocus(const std::string& value, int selectionStart, int selectionEnd,+ bool multiline, int maxLength, bool password) override {+ withEditor([&](JNIEnv* env) {+ jstring text = env->NewStringUTF(value.c_str());+ env->CallVoidMethod(editor, editorFocus, text, (jint)selectionStart, (jint)selectionEnd,+ (jboolean)multiline, (jint)maxLength, (jboolean)password);+ env->DeleteLocalRef(text);+ });+ }++ void textEditorBlur() override {+ withEditor([&](JNIEnv* env) { env->CallVoidMethod(editor, editorBlur); });+ }++ void textEditorWrite(const std::string& value, int selectionStart, int selectionEnd) override {+ withEditor([&](JNIEnv* env) {+ jstring text = env->NewStringUTF(value.c_str());+ env->CallVoidMethod(editor, editorWrite, text, (jint)selectionStart, (jint)selectionEnd);+ env->DeleteLocalRef(text);+ });+ }++ /** Run `body` with a JNIEnv for THIS thread (the frame loop's, which is not+ * the UI thread — the shim posts from there). */+ template <typename F>+ void withEditor(F&& body) {+ if (!editor || !vm) return;+ JNIEnv* env = nullptr;+ if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {+ if (vm->AttachCurrentThread(&env, nullptr) != JNI_OK || !env) return;+ }+ body(env);+ if (env->ExceptionCheck()) {+ env->ExceptionDescribe();+ env->ExceptionClear();+ }+ }};AndroidPlatform g_platform;+// -- The shim's reports, on the UI thread -------------------------------------+// Queued as POD; the frame loop hands them to JS (see TextEditorBindings.cpp).++void jniTextState(JNIEnv* env, jclass, jstring value, jint selectionStart, jint selectionEnd,+ jboolean composing) {+ const char* utf8 = value ? env->GetStringUTFChars(value, nullptr) : nullptr;+ eshost::deliverTextEditorState(utf8 ? utf8 : "", (int)selectionStart, (int)selectionEnd,+ composing != JNI_FALSE);+ if (utf8) env->ReleaseStringUTFChars(value, utf8);+}++void jniTextSubmit(JNIEnv*, jclass) { eshost::deliverTextEditorSubmit(); }+void jniTextCancel(JNIEnv*, jclass) { eshost::deliverTextEditorCancel(); }++/**+ * Load com.estella.host.TextEditor, register its natives and construct it.+ *+ * Runs on the frame-loop thread, before boot binds the es_textEditor_* entry+ * points — the surface has to exist by then or the SDK correctly concludes there+ * is none. FindClass would fail here (off the UI thread it resolves through the+ * SYSTEM class loader, which knows nothing of the APK), so the app's own loader+ * is asked by name instead. Nothing touches a View: the shim posts all of that+ * to the UI thread itself.+ */+void attachTextEditor(ANativeActivity* activity) {+ if (g_platform.editor || !activity->vm) return;+ JNIEnv* env = nullptr;+ if (activity->vm->AttachCurrentThread(&env, nullptr) != JNI_OK || !env) return;++ jclass activityCls = env->GetObjectClass(activity->clazz);+ const jmethodID getClassLoader =+ env->GetMethodID(activityCls, "getClassLoader", "()Ljava/lang/ClassLoader;");+ env->DeleteLocalRef(activityCls);+ if (!getClassLoader) { env->ExceptionClear(); return; }+ jobject loader = env->CallObjectMethod(activity->clazz, getClassLoader);+ jclass loaderCls = env->FindClass("java/lang/ClassLoader");+ const jmethodID loadClass =+ env->GetMethodID(loaderCls, "loadClass", "(Ljava/lang/String;)Ljava/lang/Class;");+ env->DeleteLocalRef(loaderCls);+ jstring name = env->NewStringUTF("com.estella.host.TextEditor");+ jclass cls = (jclass)env->CallObjectMethod(loader, loadClass, name);+ env->DeleteLocalRef(name);+ env->DeleteLocalRef(loader);+ if (!cls || env->ExceptionCheck()) {+ env->ExceptionClear();+ __android_log_print(ANDROID_LOG_WARN, LOG_TAG,+ "text editor: com.estella.host.TextEditor not in the APK — typing is off");+ return;+ }+ const JNINativeMethod natives[] = {+ {"nativeState", "(Ljava/lang/String;IIZ)V", (void*)jniTextState},+ {"nativeSubmit", "()V", (void*)jniTextSubmit},+ {"nativeCancel", "()V", (void*)jniTextCancel},+ };+ if (env->RegisterNatives(cls, natives, 3) != JNI_OK) {+ env->ExceptionClear();+ env->DeleteLocalRef(cls);+ return;+ }++ const jmethodID ctor = env->GetMethodID(cls, "<init>", "(Landroid/app/Activity;)V");+ g_platform.editorFocus = env->GetMethodID(cls, "focus", "(Ljava/lang/String;IIZIZ)V");+ g_platform.editorBlur = env->GetMethodID(cls, "blur", "()V");+ g_platform.editorWrite = env->GetMethodID(cls, "write", "(Ljava/lang/String;II)V");+ if (!ctor || !g_platform.editorFocus || !g_platform.editorBlur || !g_platform.editorWrite) {+ env->ExceptionClear();+ env->DeleteLocalRef(cls);+ return;+ }+ jobject instance = env->NewObject(cls, ctor, activity->clazz);+ if (instance) g_platform.editor = env->NewGlobalRef(instance);+ if (instance) env->DeleteLocalRef(instance);+ env->DeleteLocalRef(cls);+ __android_log_print(ANDROID_LOG_INFO, LOG_TAG, "text editor: soft keyboard up (IME)");+}+int32_t onInput(android_app*, AInputEvent* ev) {if (!eshost::booted() || AInputEvent_getType(ev) != AINPUT_EVENT_TYPE_MOTION) return 0;const int32_t action = AMotionEvent_getAction(ev) & AMOTION_EVENT_ACTION_MASK;@@ -476,6 +606,9 @@ void onWindowFocusChanged(ANativeActivity* activity, int hasFocus) {void android_main(android_app* app) {g_platform.assets = app->activity->assetManager; // APK assets/ (the exported project)g_platform.vm = app->activity->vm; // for JNI HttpURLConnection (es_fetch)+ // Before boot: whether there is an editing surface decides whether the+ // es_textEditor_* entry points are bound at all.+ attachTextEditor(app->activity);if (app->activity->internalDataPath) g_platform.cache = app->activity->internalDataPath;app->onAppCmd = onAppCmd;app->onInputEvent = onInput;diff --git a/native/host/platform/ios.mm b/native/host/platform/ios.mmindex aedf8843f..836b0fa4b 100644--- a/native/host/platform/ios.mm+++ b/native/host/platform/ios.mm@@ -33,10 +33,40 @@ using esengine::WebGPUDevice;@class EstellaViewController;+/** What the platform needs of whoever owns the keyboard's responder. A role, not+ * a class, so the C++ side names no view controller. */+@protocol EstellaTextEditorHost <NSObject>+- (void)textEditorFocus:(NSString*)value selectionStart:(NSInteger)selectionStart+ selectionEnd:(NSInteger)selectionEnd multiline:(BOOL)multiline+ maxLength:(NSInteger)maxLength password:(BOOL)password;+- (void)textEditorBlur;+- (void)textEditorWrite:(NSString*)value selectionStart:(NSInteger)selectionStart+ selectionEnd:(NSInteger)selectionEnd;+@end+namespace {struct IOSPlatform final : eshost::Platform {CAMetalLayer* layer = nil;+ // Whoever owns the responder the keyboard talks to (the view controller); set+ // once it has loaded, which is also what makes hasTextEditor() true.+ __weak id<EstellaTextEditorHost> editorHost = nil;++ bool hasTextEditor() const override { return editorHost != nil; }++ void textEditorFocus(const std::string& value, int selectionStart, int selectionEnd,+ bool multiline, int maxLength, bool password) override {+ NSString* text = [NSString stringWithUTF8String:value.c_str()] ?: @"";+ [editorHost textEditorFocus:text selectionStart:selectionStart selectionEnd:selectionEnd+ multiline:multiline maxLength:maxLength password:password];+ }++ void textEditorBlur() override { [editorHost textEditorBlur]; }++ void textEditorWrite(const std::string& value, int selectionStart, int selectionEnd) override {+ NSString* text = [NSString stringWithUTF8String:value.c_str()] ?: @"";+ [editorHost textEditorWrite:text selectionStart:selectionStart selectionEnd:selectionEnd];+ }// A file shipped inside the .app bundle — the packaged-asset analog of the// APK's assets/. Paths are project-relative ("game.config.json", "logo.png"),@@ -197,12 +227,19 @@ IOSPlatform g_platform;+ (Class)layerClass { return [CAMetalLayer class]; }@end-@interface EstellaViewController : UIViewController+// The app's editing surface: a real UITextView, invisible, that the keyboard and+// its IME talk to. Core Text draws the field itself, but composition (pinyin,+// kana, prediction) is delivered only to a UIKit responder — so the responder is+// what this holds, and nothing else about the field lives here.+@interface EstellaViewController : UIViewController <UITextViewDelegate, EstellaTextEditorHost>@end@implementation EstellaViewController {CADisplayLink* _displayLink;BOOL _booted;+ UITextView* _editor;+ BOOL _multiline;+ BOOL _writing; // set while adopting a value the app decided, so it is not echoed back}- (void)loadView {@@ -212,6 +249,9 @@ IOSPlatform g_platform;- (void)viewDidLoad {[super viewDidLoad];+ // Before boot: whether there is an editing surface decides whether the+ // es_textEditor_* entry points are bound at all.+ g_platform.editorHost = self;_displayLink = [CADisplayLink displayLinkWithTarget:self selector:@selector(step:)];[_displayLink addToRunLoop:NSRunLoop.mainRunLoop forMode:NSRunLoopCommonModes];@@ -285,6 +325,92 @@ IOSPlatform g_platform;- (BOOL)prefersStatusBarHidden { return YES; }+// -- The editing surface ------------------------------------------------------++/** The responder, created on first use. Off-screen and clear: it must be a real,+ * attached view for the keyboard to attach to, but the game draws the field. */+- (UITextView*)ensureEditor {+ if (_editor) return _editor;+ _editor = [[UITextView alloc] initWithFrame:CGRectMake(-100, -100, 1, 1)];+ _editor.delegate = self;+ _editor.backgroundColor = UIColor.clearColor;+ _editor.textColor = UIColor.clearColor;+ _editor.tintColor = UIColor.clearColor; // no system caret; the game draws its own+ _editor.autocorrectionType = UITextAutocorrectionTypeNo;+ _editor.autocapitalizationType = UITextAutocapitalizationTypeNone;+ [self.view addSubview:_editor];+ return _editor;+}++- (void)textEditorFocus:(NSString*)value selectionStart:(NSInteger)selectionStart+ selectionEnd:(NSInteger)selectionEnd multiline:(BOOL)multiline+ maxLength:(NSInteger)maxLength password:(BOOL)password {+ UITextView* editor = [self ensureEditor];+ _multiline = multiline;+ _writing = YES;+ editor.text = value;+ editor.returnKeyType = multiline ? UIReturnKeyDefault : UIReturnKeyDone;+ // The field renders its own bullets; this is for the keyboard's benefit — no+ // suggestion strip or autocorrect over a password.+ editor.textContentType = password ? UITextContentTypePassword : nil;+ editor.secureTextEntry = password;+ [self setEditorSelectionStart:selectionStart end:selectionEnd];+ _writing = NO;+ [editor becomeFirstResponder];+}++- (void)textEditorBlur {+ [_editor resignFirstResponder];+}++- (void)textEditorWrite:(NSString*)value selectionStart:(NSInteger)selectionStart+ selectionEnd:(NSInteger)selectionEnd {+ if (!_editor) return;+ _writing = YES;+ if (![_editor.text isEqualToString:value]) _editor.text = value;+ [self setEditorSelectionStart:selectionStart end:selectionEnd];+ _writing = NO;+}++- (void)setEditorSelectionStart:(NSInteger)start end:(NSInteger)end {+ const NSInteger length = (NSInteger)_editor.text.length;+ const NSInteger lo = MAX(0, MIN(start, length));+ const NSInteger hi = MAX(lo, MIN(end, length));+ _editor.selectedRange = NSMakeRange((NSUInteger)lo, (NSUInteger)(hi - lo));+}++/** Hand the responder's whole state to the engine. A marked range IS the IME+ * preedit, so that is what `composing` asks about. */+- (void)reportEditorState {+ if (_writing || !_editor) return;+ const NSRange selection = _editor.selectedRange;+ const BOOL composing = _editor.markedTextRange != nil;+ eshost::deliverTextEditorState(_editor.text.UTF8String ?: "",+ (int)selection.location,+ (int)(selection.location + selection.length), composing);+}++- (void)textViewDidChange:(UITextView*)textView { [self reportEditorState]; }++- (void)textViewDidChangeSelection:(UITextView*)textView { [self reportEditorState]; }++- (BOOL)textView:(UITextView*)textView shouldChangeTextInRange:(NSRange)range+ replacementText:(NSString*)text {+ // Return on a single-line field submits instead of inserting a newline —+ // the same rule the web's Enter follows.+ if (!_multiline && [text isEqualToString:@"\n"]) {+ eshost::deliverTextEditorSubmit();+ return NO;+ }+ return YES;+}++- (void)textViewDidEndEditing:(UITextView*)textView {+ // The keyboard went away (done, or another responder took over): for a UI+ // field that is losing focus, which is what Escape does on the web.+ eshost::deliverTextEditorCancel();+}+@end@interface EstellaAppDelegate : UIResponder <UIApplicationDelegate>diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex b401324f3..58e1e42a6 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -4088,6 +4088,7 @@ registerInput: (listener: NativeInputListener) => () => voidremoveStorageItem: (key: string) => voidsetStorageItem: (key: string, value: string) => voidstorageKeys: () => string[]+textEditor: NativeTextEditorBridge | undefinedwriteCacheFile: ((key: string, bytes: ArrayBuffer) => Promise<void>) | undefined```@@ -4146,6 +4147,9 @@ es_readCacheFile: ((key: string) => ArrayBuffer | null) | undefinedes_removeStorageItem: ((key: string) => void) | undefinedes_setStorageItem: ((key: string, value: string) => void) | undefinedes_storageKeys: (() => string[]) | undefined+es_textEditor_blur: (() => void) | undefined+es_textEditor_focus: ((value: string, selectionStart: number, selectionEnd: number, multiline: boolean, maxLength: number, password: boolean) => void) | undefined+es_textEditor_write: ((value: string, selectionStart: number, selectionEnd: number) => void) | undefinedes_writeCacheFile: ((key: string, bytes: ArrayBuffer | Uint8Array | string) => boolean) | undefined```@@ -4173,6 +4177,7 @@ clearStorage: (prefix: string) => voidcreateAudioBackend: (() => PlatformAudioBackend) | undefinedcreateCanvas: (_width: number, _height: number) => PlatformCanvascreateImage: () => PlatformImage+createTextEditor: () => PlatformTextEditor | nullcreateVideoBackend: (ctx: VideoBackendContext) => PlatformVideoBackenddevicePixelRatio: () => numberfetch: (url: string, options?: PlatformRequestOptions) => Promise<PlatformResponse>diff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.tsindex 6d6bbb04b..73cbd4783 100644--- a/sdk/src/platform/native/adapter.ts+++ b/sdk/src/platform/native/adapter.ts@@ -25,6 +25,7 @@ import type {PlatformImage,PlatformGlyph,PlatformGlyphRequest,+ PlatformTextEditor,} from '../types';import type { PlatformAudioBackend } from '../../audio/PlatformAudioBackend';import type { PlatformVideoBackend, VideoBackendContext } from '../../video/PlatformVideoBackend';@@ -32,6 +33,7 @@ import { WasmVideoBackend } from '../../video/WasmVideoBackend';import { setPlatform } from '../base';import { createPrimaryPointer } from '../primaryPointer';import { NativeAudioBackend } from '../../audio/NativeAudioBackend';+import { createNativeTextEditor } from './textEditor';import type { NativeBridge, NativeInputListener } from './bridge';export class NativePlatformAdapter implements PlatformAdapter {@@ -117,6 +119,13 @@ export class NativePlatformAdapter implements PlatformAdapter {throw new Error('[native] no DOM images — decode via loadImagePixels');}+ /** The OS soft keyboard + IME, when the host wired one. Null → editable+ * fields render but cannot be typed into (platform/native/textEditor.ts). */+ createTextEditor(): PlatformTextEditor | null {+ const editor = this.bridge_.textEditor;+ return editor ? createNativeTextEditor(editor) : null;+ }+now(): number {return this.bridge_.now?.() ?? Date.now();}diff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.tsindex e45243663..ae23c0471 100644--- a/sdk/src/platform/native/bridge.ts+++ b/sdk/src/platform/native/bridge.ts@@ -49,6 +49,41 @@ export interface NativeInputListener {onKeyUp?(code: string): void;}+/** What the OS editing surface reports back. `state` carries the surface's whole+ * value + selection (it is the owner while focused); `composing` is absent on a+ * host that cannot tell whether an IME preedit is in flight. */+export type NativeTextEditorPush =+ | {+ kind: 'state';+ value: string;+ selectionStart: number;+ selectionEnd: number;+ composing?: boolean;+ }+ | { kind: 'submit' }+ | { kind: 'cancel' };++/**+ * The host's text-editing surface: the OS soft keyboard and its IME. Present only+ * when the host bound it — a host without one omits `NativeBridge.textEditor`+ * and editable fields render but do not type, the way a host without a sound+ * device stays silent.+ *+ * `focus` opens the keyboard on the field's current value; `write` pushes an edit+ * the app made (a programmatic setValue, a tap that moved the caret); everything+ * the user does comes back through `subscribe`.+ */+export interface NativeTextEditorBridge {+ focus(+ value: string, selectionStart: number, selectionEnd: number,+ multiline: boolean, maxLength: number, password: boolean,+ ): void;+ blur(): void;+ write(value: string, selectionStart: number, selectionEnd: number): void;+ /** Returns an unsubscribe. */+ subscribe(handler: (push: NativeTextEditorPush) => void): () => void;+}+/*** The host's native audio engine, wrapped as a small object so {@link* NativeAudioBackend} stays a thin adapter over it (mirroring the WeChat backend@@ -139,6 +174,11 @@ export interface NativeBridge {* Null backend. See {@link NativeAudioBridge}. */audio?: NativeAudioBridge;+ /** The OS text-editing surface (soft keyboard + IME), when the host has wired+ * one. Absent → fields render but cannot be typed into, exactly as a host+ * with no audio device stays silent. See {@link NativeTextEditorBridge}. */+ textEditor?: NativeTextEditorBridge;+/** App foreground/background signals (no DOM visibility on native): the shell* pushes them, the adapter surfaces them as `onAppShow`/`onAppHide`, and the* Lifecycle plugin auto-pauses on hide. Each returns an unsubscribe. Optional —diff --git a/sdk/src/platform/native/hostBridge.ts b/sdk/src/platform/native/hostBridge.tsindex 6eeb86dde..590f17b96 100644--- a/sdk/src/platform/native/hostBridge.ts+++ b/sdk/src/platform/native/hostBridge.ts@@ -13,7 +13,10 @@*/import { log } from '../../logger';-import type { NativeAudioBridge, NativeBridge, NativeFetchResult, NativeInputListener } from './bridge';+import type {+ NativeAudioBridge, NativeBridge, NativeFetchResult, NativeInputListener,+ NativeTextEditorBridge, NativeTextEditorPush,+} from './bridge';import type { PlatformGlyph, PlatformGlyphRequest, PlatformRequestOptions } from '../types';import { assertHostEnvironment } from './hostEnvironment';import { hasAudioBindings } from '../../ecs/nativeBindings';@@ -73,6 +76,17 @@ export interface NativeHostBindings {/** The native audio engine, all-or-nothing (see {@link AUDIO_BINDINGS}). A* host without a sound device binds none and stays silent. */+ // The OS text-editing surface (soft keyboard + IME). Optional as a group:+ // hasTextEditorBindings gates them, so a host that wired none simply has no+ // editing surface. The host pushes what the user did through+ // es_onNativeTextEditor, installed here.+ es_textEditor_focus?(+ value: string, selectionStart: number, selectionEnd: number,+ multiline: boolean, maxLength: number, password: boolean,+ ): void;+ es_textEditor_blur?(): void;+ es_textEditor_write?(value: string, selectionStart: number, selectionEnd: number): void;+es_audioLoad?(bytes: ArrayBuffer): { id: number; duration: number; bytes: number } | null;es_audioUnload?(bufferId: number): void;es_audioPlay?(bufferId: number, volume: number, pan: number, loop: boolean, rate: number): number;@@ -120,6 +134,7 @@ export function createHostBridge(const storage = hostStorage(bindings);const audio = hostAudio(bindings, scope);+ const textEditor = hostTextEditor(bindings, scope);const lifecycle = hostLifecycle(scope);return {@@ -156,6 +171,7 @@ export function createHostBridge(},devicePixelRatio: () => bindings.es_devicePixelRatio?.() ?? 1,...(audio ? { audio } : {}),+ ...(textEditor ? { textEditor } : {}),...lifecycle,};}@@ -247,6 +263,37 @@ function hostAudio(};}+/**+ * The host's editing surface, when it bound one: calls out through its+ * `es_textEditor_*` entry points, and takes what the user did through+ * `es_onNativeTextEditor`, installed here the way the lifecycle signals are.+ * All-or-nothing — a host with only some of the entry points has no surface,+ * rather than one that opens a keyboard it cannot read.+ */+function hostTextEditor(+ bindings: NativeHostBindings,+ scope: Record<string, unknown>,+): NativeTextEditorBridge | undefined {+ if (!bindings.es_textEditor_focus || !bindings.es_textEditor_blur || !bindings.es_textEditor_write) {+ return undefined;+ }+ let subs: ((push: NativeTextEditorPush) => void)[] = [];+ scope.es_onNativeTextEditor = (push: NativeTextEditorPush): void => {+ for (const cb of subs) cb(push);+ };+ return {+ focus: (value, selectionStart, selectionEnd, multiline, maxLength, password) =>+ bindings.es_textEditor_focus!(value, selectionStart, selectionEnd, multiline, maxLength, password),+ blur: () => bindings.es_textEditor_blur!(),+ write: (value, selectionStart, selectionEnd) =>+ bindings.es_textEditor_write!(value, selectionStart, selectionEnd),+ subscribe: (handler) => {+ subs.push(handler);+ return () => { subs = subs.filter((s) => s !== handler); };+ },+ };+}+/*** The lifecycle signals the host pushes (like touch), each installed as an* `es_onNative*` entry the shell calls and exposed as a subscribe/unsubscribe ondiff --git a/sdk/src/platform/native/textEditor.ts b/sdk/src/platform/native/textEditor.tsnew file mode 100644index 000000000..aefec3f49--- /dev/null+++ b/sdk/src/platform/native/textEditor.ts@@ -0,0 +1,88 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file platform/native/textEditor.ts+ * @brief The device's editing surface — the OS soft keyboard and its IME —+ * behind the platform's {@link PlatformTextEditor} contract.+ *+ * The keyboard lives on the OS side of the boundary and reports asynchronously+ * (a UI-thread callback, drained into the frame), while a field reads its value+ * synchronously while rendering. So this keeps a MIRROR of the surface's state,+ * refreshed by every push from the host, and answers `read()` from it. The host+ * remains the owner: an edit the app makes goes out through `write` and comes+ * back as a push, so there is one order of events and never two truths.+ */+import type {+ PlatformTextEditor, TextEditorEvent, TextEditorOptions, TextEditorState,+} from '../types';+import type { NativeTextEditorBridge } from './bridge';++export function createNativeTextEditor(bridge: NativeTextEditorBridge): PlatformTextEditor {+ let state: TextEditorState = { value: '', selectionStart: 0, selectionEnd: 0, backward: false };+ let focused = false;+ let composingNow = false;+ const handlers = new Set<(event: TextEditorEvent) => void>();+ const emit = (event: TextEditorEvent): void => {+ for (const handler of handlers) handler(event);+ };++ const unsubscribe = bridge.subscribe((next) => {+ switch (next.kind) {+ case 'state': {+ const composing = next.composing;+ state = {+ value: next.value,+ selectionStart: next.selectionStart,+ selectionEnd: next.selectionEnd,+ backward: false, // no platform keyboard reports a selection's direction+ };+ if (composing !== undefined && composing !== composingNow) {+ composingNow = composing;+ emit({ kind: 'composition', composing });+ }+ emit({ kind: 'change' });+ break;+ }+ case 'submit':+ emit({ kind: 'submit' });+ break;+ case 'cancel':+ // The keyboard was dismissed (back gesture / done): the field is no+ // longer being edited, which for a UI field means losing focus.+ focused = false;+ emit({ kind: 'blur' });+ break;+ }+ });++ return {+ focus(next: TextEditorState, options: TextEditorOptions): void {+ state = { ...next };+ focused = true;+ bridge.focus(next.value, next.selectionStart, next.selectionEnd,+ options.multiline, options.maxLength, options.password);+ },+ blur(): void {+ if (!focused) return;+ focused = false;+ bridge.blur();+ },+ read(): TextEditorState {+ return state;+ },+ write(next: TextEditorState): void {+ state = { ...next };+ bridge.write(next.value, next.selectionStart, next.selectionEnd);+ },+ subscribe(handler: (event: TextEditorEvent) => void): () => void {+ handlers.add(handler);+ return () => { handlers.delete(handler); };+ },+ dispose(): void {+ unsubscribe();+ handlers.clear();+ if (focused) bridge.blur();+ focused = false;+ },+ };+}