Skip to content

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.

fix(release): prepare v0.77.0 candidate and portable validation

yhh7238c18dc160
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 8636aa4aa..3be6b212e 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -584,6 +584,9 @@ jobs:
working-directory: desktop
env:
ELECTRON_DISABLE_SANDBOX: '1'
+ # OS focus and first-paint acceptance use this runner's virtual desktop.
+ # Local checks default to hidden windows so they do not interrupt a user.
+ ESTELLA_MCP_EDITOR_VISIBLE: '1'
run: xvfb-run -a --server-args="-screen 0 1920x1080x24" node scripts/editor-checks/run.mjs --shard ${{ matrix.shard }}/4 || [ $? -eq 2 ]
# Between the two heavy steps, so the disk each one costs is attributable.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 16d54a35a..4e6ae5d19 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,8 +14,14 @@ published separately; it ships inside the editor.
## [Unreleased]
+## [0.77.0] - 2026-10-10
+
### Added
+- **Text input hints can follow the game's language.** `TextInput` and `createTextInput` accept `placeholderI18nKey`. An empty field resolves the key through Localization and responds to locale, catalog and preview changes; typed values and authored literal placeholders remain intact. Placeholder-only scenes also load localization tables.
+
+- **The UI Debugger follows the live game.** Pick a UI element in Play and inspect its hierarchy, layout bounds, input settings, text input and dialog state. Mask diagnostics show ancestor masks and rectangular clipping. Focus inspection follows runtime controls and Tab traversal. Event recording observes actual entity dispatch, shows propagation paths, and keeps recording when switching debugger tabs.
+
- UI text inspection and pseudolocalization previews. The editor can inspect
computed text boxes, show overflow before clipping or ellipsis, and select
the authored entity. Runtime localization can opt into accent and length
@@ -23,10 +29,32 @@ published separately; it ships inside the editor.
and custom fonts are marked for visual review. The multilingual sample
documents the scope and remaining platform checks.
+- **A selected camera has a preview without advancing gameplay.** The preview uses the authored camera, restores the editor view afterwards, and can be pinned or closed. Refreshes run at most once per second and slow down when recurring render/readback work is expensive; initial shader and target setup do not set the ongoing refresh budget.
+
+- **Tilemap edits can be reviewed before applying them.** Preview replacements over a selection or layer, inspect terrain-rule mismatches, and keep reusable stamps with the project. The `tilemap-workflows` example demonstrates the workflow. The platformer example also demonstrates stretchable nine-slice sprites.
+
+- **Device quality profiles can be previewed in the editor.** An opt-in policy selects low, medium or high settings from device information and project rules. Profiles control render scale, MSAA, shadows, particles and post-processing, with optional dynamic resolution. The default remains off; projects keep their authored quality until they opt in.
+
+### Changed
+
+- **Unchanged plain translations use a bounded cache.** Up to 256 parameter-free string translations are reused per Localization instance. Locale, fallback, catalog and preview changes invalidate the cache. Parameterized, plural and missing-key messages remain live.
+
+- **Gizmo controls keep a 2D scene easier to edit.** Detailed geometry defaults to selected entities, inactive handles no longer intercept ordinary scene interaction, and visibility and icon size are saved per project. The menu separates common controls from advanced types. New preview, tilemap and debugger controls use the editor's shared button and theme styles; text entities put content and layout first in the Inspector.
+
+- **Device reports can inspect prebuilt native apps.** Android frame reports no longer require hooks in a project's source, and native boot verification can run a supplied application without a packaging template.
+
+- **Full-editor MCP checks can run without showing windows.** `editor-mcp.mjs --editor --hidden` keeps the real authoring and Play surface available without a desktop window. Local authoring checks use this mode by default; CI uses its virtual desktop for OS-focus acceptance.
+
### Fixed
+- **Keyboard and pointer focus stay with eligible UI controls.** Web Tab traversal stays inside the game, nested modal dialogs constrain focus to the innermost modal, and hierarchically hidden dialogs no longer capture it. Hiding or disabling the focused control clears stale focus. A quick pointer press and release between frames still sets focus.
+
+- **Text cache entries respect overflow and parameter boundaries.** Changing clipping or ellipsis invalidates cached layout, and escaped localization parameters no longer collide with another parameter combination.
+
- **A project that moves keeps answering its textures from its own cache.** The editor remembered where each compressed texture was kept as an absolute path, so a project copied elsewhere went on serving textures from the old folder, and from none once that was deleted. It is kept relative to the project now; a record written by 0.76.0 is still read.
+- **Release checks compare the content that ships.** Windows CRLF checkouts no longer appear to have stale generated bindings or baked scenes. Native-template verification compares the SDK hash embedded in bytecode instead of copy timestamps. First-screen timing presents the page before measuring browser paint, and gizmo checks explicitly choose the visibility they inspect. The tilemap workflow scene now ships in the current scene format.
+
## [0.76.0] - 2026-10-01
### Changed
@@ -13822,7 +13850,8 @@ not kept before this file was introduced — see the Git history at
`github.com/esengine/estella` for the full commit-level record since the first
commit on 2026-01-25.
-[Unreleased]: https://github.com/esengine/estella/compare/v0.76.0...HEAD
+[Unreleased]: https://github.com/esengine/estella/compare/v0.77.0...HEAD
+[0.77.0]: https://github.com/esengine/estella/compare/v0.76.0...v0.77.0
[0.76.0]: https://github.com/esengine/estella/compare/v0.75.0...v0.76.0
[0.75.0]: https://github.com/esengine/estella/compare/v0.74.0...v0.75.0
[0.74.0]: https://github.com/esengine/estella/compare/v0.73.0...v0.74.0
diff --git a/README.md b/README.md
index f151a02aa..01a5ace6e 100644
--- a/README.md
+++ b/README.md
@@ -125,6 +125,8 @@ Full documentation: [estellaengine.com/docs](https://estellaengine.com/docs)
We welcome contributions! Please read the [Contributing Guide](CONTRIBUTING.md) before submitting a Pull Request.
+Maintainers: see the [release procedure](RELEASING.md) for candidate builds, acceptance evidence and publishing.
+
## License
This repository — the engine runtime, the SDK, the asset pipeline, the CLI, the
diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 000000000..b15b8e11e
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,131 @@
+# Estella 发布流程
+
+发布的是同一版本的引擎、SDK、编辑器和原生运行时模板。版本规则见
+[VERSIONING.md](VERSIONING.md),验收项目以 [tools/releaseGate.mjs](tools/releaseGate.mjs)
+为准。本次候选的进度见 [v0.77.0 发布记录](docs/releases/0.77.0.md)。
+
+## 1. 冻结范围和准备提交
+
+- 从最新 `origin/master` 建立独立发布分支,保留正在开发的工作区。
+- 优先纳入已完成的 2D 制作、UI、输入、Tilemap 和交付修复。逐一确认 PR 的合并状态,未合并功能不算已发布能力。
+- 同步根目录和 `desktop/package.json` 的版本、CHANGELOG 版本段与比较链接、SECURITY 支持版本,以及 `tools/releaseNotes.mjs` 的提交归类。
+- 编辑器是独立的私有仓库。先提交并推送编辑器,再提交引擎的 `desktop` gitlink;CI 必须能从远端取到该提交。
+- 合并编辑器与引擎发布变更后,冻结最终引擎 SHA 和编辑器 SHA。合并、补修或改版本产生新 SHA 后,重新取得对应验证证据。
+
+从干净的最终发布检出运行以下只读检查。以下命令使用 PowerShell:
+
+```powershell
+git fetch origin --tags
+git -C desktop fetch origin
+git status --short
+git -C desktop status --short
+git rev-parse HEAD
+git rev-parse origin/master
+git ls-tree HEAD desktop
+git -C desktop rev-parse HEAD
+node tools/check-release-metadata.mjs
+node tools/check-changelog-covers.mjs
+node tools/check-release-gate.mjs
+node tools/run-release-gate.mjs --plan
+```
+
+两个工作区必须干净;引擎 HEAD 必须是已冻结的 `origin/master`,编辑器 HEAD 必须等于引擎记录的 gitlink。`--plan` 和 `check-release-gate` 检查验收项目能否执行,不代表项目已经通过。
+
+## 2. 在后台验证最终提交
+
+本地构建、类型检查和单元测试后台执行。完整编辑器 MCP 也可隐藏运行:
+
+```powershell
+pnpm install --frozen-lockfile
+pnpm --filter ./sdk build
+pnpm --dir desktop run build
+Push-Location desktop
+node scripts/editor-checks/run.mjs camera-preview gizmo-menu icon-pick
+Pop-Location
+```
+
+Authoring runner 默认隐藏窗口。直接使用 MCP 时传 `--editor --hidden`;
+`ESTELLA_MCP_EDITOR_VISIBLE=1` 仅用于需要窗口的验收。隐藏的完整编辑器与默认的简化 headless fixture host 是两种运行方式:项目打开、Play 和导出检查使用完整编辑器。
+
+OS 焦点、Tab 输入、首次绘制等窗口相关检查在 CI 的虚拟桌面上运行。
+本地不运行会弹出窗口的首屏测量或设备验收。设备相关验收使用其指定主机,模拟器结果与真机结果分别记录。
+
+在最终 SHA 仍为 master 的情况下触发三条流水线:
+
+```powershell
+gh workflow run build.yml --repo esengine/estella --ref master
+gh workflow run nightly.yml --repo esengine/estella --ref master
+gh workflow run release-desktop.yml --repo esengine/estella --ref master
+gh run list --repo esengine/estella --branch master --limit 15 --json databaseId,workflowName,headSha,status,conclusion,url
+```
+
+逐个确认 `headSha` 等于冻结 SHA,再保存 Run ID、链接、各 job 结果和失败日志。
+查看 Build、Nightly 的验收输出,包括 `UNANSWERED`、跳过、取消和人工项目。
+某条工作流显示绿色,不能代替完整验收记录。
+
+手动触发 `Release Desktop App` 是 **dry run**:构建 Windows/macOS 安装包和五个平台的原生模板,不创建或发布 GitHub Release。它不运行 tag 发布中的 `smoke-templates`;需要候选分支上的原生启动检查时,另行运行:
+
+```powershell
+gh workflow run native-smoke.yml --repo esengine/estella --ref master -f template-source=head
+```
+
+记录该运行的 SHA,以及它构建的模板与待发布版本。原生 smoke 当前只提供报告,不会自动阻止正式发布,发布负责人仍须审阅真实启动失败。
+
+## 3. 验收候选安装包
+
+dry run 的产物保留三天,及时下载。用上一节保存的候选构建 Run ID:
+
+```powershell
+$candidateRun = Read-Host '候选构建 Run ID'
+gh run view $candidateRun --repo esengine/estella --json headSha,status,conclusion,url,jobs
+gh run download $candidateRun --repo esengine/estella --name installer-windows-latest --dir out/release-candidate/windows
+gh run download $candidateRun --repo esengine/estella --name installer-macos-latest --dir out/release-candidate/macos
+gh run download $candidateRun --repo esengine/estella --pattern 'native-template-*' --dir out/release-candidate/templates
+```
+
+记录安装包文件名、SHA-256、版本和候选 SHA,使用下载的包验证:
+
+- Windows/macOS 安装、启动和版本显示;从上一正式版本升级,重新打开保存的项目。
+- 新建 2D 项目;打开旧项目;编辑、保存、关闭并重新打开;Play/Stop 后场景数据保持正确。
+- UI 输入、焦点、文本溢出与本地化预览;Tilemap 拼接、Stamp 和替换;Gizmo 与相机预览。
+- 导出并启动 Web 游戏,以及此次发布支持的小游戏和原生目标。验证实际包的资源加载、输入、声音与渲染,而不只检查导出命令的退出码。
+- 检查模板归档结构与嵌入 SDK 的内容一致性;审阅 native smoke 的启动结果。
+- 完成 releaseGate 声明的人工项目:官网主图来源、安装版诊断导出、稳定性文档、包装/启动 P0 问题清单。
+
+每项写 PASS、FAIL 或 UNANSWERED,附证据和平台。缺设备或缺工具属于 UNANSWERED。
+关键功能失败须修复;纯测试环境问题只有在同一问题被另一种有效验证覆盖、并记录原因和结果后才能放行。
+
+## 4. 推送标签并正式发布
+
+验收完成后,在同一冻结检出确认版本号、两仓库状态、远端 master 和 gitlink。
+确认本地与远端均没有该版本标签。以下步骤是正式发布,不是候选构建:
+
+```powershell
+$releaseVersion = (Get-Content package.json -Raw | ConvertFrom-Json).version
+git fetch origin --tags
+git rev-parse HEAD
+git rev-parse origin/master
+git status --short
+git -C desktop status --short
+git tag --list "v$releaseVersion"
+git ls-remote --tags origin "refs/tags/v$releaseVersion"
+# 上述状态与发布记录一致,且标签不存在后执行:
+git tag -a "v$releaseVersion" -m "v$releaseVersion"
+git push origin "refs/tags/v$releaseVersion"
+```
+
+`v*` 标签会自动创建草稿、重新构建安装包和模板,核对更新清单引用、归档内容及发布说明,然后公开 Release 并更新 latest。镜像和文档部署随后运行。
+**这条发布工作流没有依赖 Build/Nightly 的验收结果,因此必须先完成前面的验收。**
+
+当前 `build-tools/release.js` 会同时修改版本、提交、推送 master 和标签;它不执行完整验收。在独立工作树里不要用它代替以上已验证提交的标签步骤。
+
+## 5. 发布后检查与失败处理
+
+- 核对标签目标 SHA、公开 Release 版本和说明。检查安装包、更新清单、清单引用文件及原生模板完整可下载。
+- 检查 Windows 签名为 Valid 或 NotSigned;macOS 按实际签名/公证结果记录,未签名不能记作自动更新已通过。
+- 安装最终 Release 下载的包并抽查旧项目、Play、Web 导出和诊断;候选包验收不代表 tag 构建的每个字节相同。
+- 检查镜像、官网文档和下载链接版本。构建通过、镜像成功、设备接受是分别记录的结果。
+- 打包或资产校验失败时,保留草稿和日志,修复后重跑失败 job;修改源码则按新提交重新验证并发布新版本。
+- 已公开的标签不删除、不改指向;用户可回退上一已验证版本。严重问题修复后发补丁版本,必要时将 latest 指回上一稳定 Release。
+
+操作记录至少包含:版本、引擎 SHA、编辑器 SHA、三个主流水线 Run ID、原生启动报告、安装包摘要、自动与人工验收结果、未覆盖平台、发布 URL、镜像和官网状态。
diff --git a/SECURITY.md b/SECURITY.md
index 57a902313..5eb39ef80 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -7,8 +7,8 @@ upgrading to the latest release is the supported path to a fix.
| Version | Supported |
|---------|-----------|
-| 0.76.x | Yes |
-| < 0.76 | No |
+| 0.77.x | Yes |
+| < 0.77 | No |
`tools/check-release-metadata.mjs` fails the build if this table stops matching
the version being shipped, so it cannot quietly fall behind again.
diff --git a/desktop b/desktop
index c0f3e625c..fbf0512bf 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit c0f3e625cc27529bda4cf5fd35183982fdb0de8f
+Subproject commit fbf0512bfae3c3fe0549c03851e34a2deb51c3b7
diff --git a/docs/releases/0.77.0.md b/docs/releases/0.77.0.md
new file mode 100644
index 000000000..2d8843475
--- /dev/null
+++ b/docs/releases/0.77.0.md
@@ -0,0 +1,45 @@
+# v0.77.0 发布准备记录
+
+更新日期:2026-10-10。状态:准备中,尚未打标签或公开发布。
+操作流程见 [RELEASING.md](../../RELEASING.md)。
+
+## 范围与来源
+
+- 发布分支:`codex/release-v0.77.0`。
+- 引擎起点:`c6c8d508f8b4d77ca05c183536a59864fe281596`。
+- 编辑器起点:`c0f3e625cc27529bda4cf5fd35183982fdb0de8f`。
+- 上一正式版本:v0.76.0。
+- 范围:已合并的 UI Debugger、焦点/输入和文本修复、Tilemap 工作流、相机预览、2D Gizmo、设备质量预览,以及发布检查修复。
+- PR #90/#91 已于 2026-10-10 合并:本地化字符串缓存和输入框提示翻译纳入版本。旧游戏工作区的实验性地形与透光修改不在本次范围。
+- 根目录和编辑器版本已准备为 0.77.0;最终 SHA 尚未冻结,以下结果是本地准备阶段证据。
+
+## 已验证
+
+| 项目 | 结果 | 证据与范围 |
+|---|---|---|
+| SDK 构建 | PASS | 候选工作树本地构建 |
+| 编辑器构建与类型检查 | PASS | 完整 build,包括 MCP bundle |
+| 输入回调类型修复 | PASS | 输入 parity 的 4 项测试;SDK 类型基线无新增错误,仍有既有类型债务 |
+| 原生 SDK 内容摘要校验 | PASS | 2 项单元测试;真实模板运行尚待 CI |
+| Gizmo 绘制、点选与显示检查 | PASS | 13 项可视编辑器检查;相机预览另行修复验证 |
+| 隐藏完整编辑器检查 | PASS | camera-preview、gizmo-menu、icon-pick 共 3/3;无可见窗口句柄 |
+| 相机预览实际定时刷新 | PASS | 4.02 秒内 2 次刷新;相对主帧 CPU 预算约 7.47%;预览与暂停 Play 的 57,600 像素比较无差异 |
+| 生成代码、资源引用、烘焙内容 | PASS | Windows 换行兼容修复后的对应检查 |
+| 编辑器主题、Inspector 注册、删除重试 | PASS | 对应静态检查 |
+| 版本元数据 | PASS | CHANGELOG/SECURITY 指向 0.77.0;仍须核对最终编辑器 gitlink |
+| 发布验收目录 | PASS | 38 项:34 项自动、4 项人工;只验证项目与命令存在 |
+
+## 发布前待完成
+
+- [ ] 完成提交、推送与 PR 合并;冻结最终引擎/编辑器 SHA。
+- [ ] 最终 SHA 的 Build 完整回归通过。
+- [ ] 最终 SHA 的 Nightly 发布验收通过,逐项审阅 FAIL/UNANSWERED。
+- [ ] 最终 SHA 的 Release Desktop App dry run,通过全部候选构建。
+- [ ] Windows/macOS 候选安装、升级、旧项目、保存、Play 和导出验收;记录包摘要。
+- [ ] 首屏测量在 CI 虚拟桌面通过。此前本地 Slow 4G 测得 416 ms,未满足现有 300 ms 上限;不能据此放行。
+- [ ] 原生模板内容一致性与实际启动验收,分别记录模拟器和真机覆盖。
+- [ ] 官网主图、安装版诊断导出、稳定性文档及包装/启动 P0 清单四项人工验收。
+- [ ] 推送 v0.77.0 标签,确认公开 Release、更新清单与最终包。
+- [ ] 镜像、官网文档、下载和更新路径核对完成。
+
+主流水线 Run ID、最终 SHA、安装包摘要和发布 URL 待生成后填写。
diff --git a/examples/tilemap-workflows/assets/scenes/main.esscene b/examples/tilemap-workflows/assets/scenes/main.esscene
index c6f12a022..f8985f180 100644
--- a/examples/tilemap-workflows/assets/scenes/main.esscene
+++ b/examples/tilemap-workflows/assets/scenes/main.esscene
@@ -1,5 +1,5 @@
{
- "version": "1.0",
+ "version": 4,
"name": "Tilemap Workflows",
"entities": [
{
diff --git a/package.json b/package.json
index e5c8d8ce6..4735feb63 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "estella",
- "version": "0.76.0",
+ "version": "0.77.0",
"private": true,
"type": "module",
"description": "Estella - A fast 2D/3D game engine powered by WebAssembly and ECS",
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index 246c53f59..45e38d360 100644
--- a/pipeline/bin/estella.mjs
+++ b/pipeline/bin/estella.mjs
@@ -469,17 +469,18 @@ async function bakeScene(baker, meta, sceneFile, check) {
const importer = JSON.parse(readFileSync(`${atlasFile}.meta`, 'utf8')).importer ?? {};
staleSettings = JSON.stringify(baker.claimedLightmapImporter(importer, result.size)) !== JSON.stringify(importer);
}
- const staleScene = readFileSync(sceneFile, 'utf8') !== document;
+ const readText = (file) => readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
+ const staleScene = readText(sceneFile) !== document;
const staleGrids = [...grids.values()].some((g) => {
const file = path.join(sceneDir, g.name);
- return !existsSync(file) || readFileSync(file, 'utf8') !== g.text;
+ return !existsSync(file) || readText(file) !== g.text;
});
const staleReflections = reflectionText != null && (
!existsSync(reflectionFile)
|| Buffer.compare(readFileSync(reflectionFile),
Buffer.from(result.reflection.atlasBytes)) !== 0
|| !existsSync(reflectionDocFile)
- || readFileSync(reflectionDocFile, 'utf8') !== reflectionText);
+ || readText(reflectionDocFile) !== reflectionText);
if (staleAtlas || staleSettings || staleScene || staleGrids || staleReflections) {
const what = [staleAtlas && 'the atlas', staleSettings && "the atlas's import settings", staleScene && 'the scene',
staleGrids && 'a probe grid',
diff --git a/sdk/tests/input-parity.test.ts b/sdk/tests/input-parity.test.ts
index b9daadbd4..d882adfd3 100644
--- a/sdk/tests/input-parity.test.ts
+++ b/sdk/tests/input-parity.test.ts
@@ -24,7 +24,7 @@ function recorder(): { callbacks: InputEventCallbacks; trace: Trace } {
return {
trace,
callbacks: {
- onKeyDown: (code) => trace.push(`keyDown ${code}`),
+ onKeyDown: (code) => { trace.push(`keyDown ${code}`); },
onKeyUp: (code) => trace.push(`keyUp ${code}`),
onPointerMove: (x, y) => trace.push(`pointerMove ${x},${y}`),
onPointerDown: (b, x, y) => trace.push(`pointerDown ${b} ${x},${y}`),
diff --git a/tools/check-asset-refs.mjs b/tools/check-asset-refs.mjs
index 85ad512e5..5bd99a72a 100644
--- a/tools/check-asset-refs.mjs
+++ b/tools/check-asset-refs.mjs
@@ -30,7 +30,7 @@ const CORPUS = ['examples', 'templates', 'sdk/src', 'tools/fixtures'];
/** Which fields carry an asset, read from the declaration rather than listed
* here: a list would be a second author, and it is the one that goes stale. */
function assetFieldsByComponent() {
- const gen = readFileSync(path.join(ROOT, 'sdk/src/ecs/component.generated.ts'), 'utf8');
+ const gen = readFileSync(path.join(ROOT, 'sdk/src/ecs/component.generated.ts'), 'utf8').replace(/\r\n/g, '\n');
const entry = /^ {4}([A-Za-z0-9_]+): \{$/gm;
const marks = [];
let m;
diff --git a/tools/check-generated-fresh.mjs b/tools/check-generated-fresh.mjs
index 3de6bf94f..008df81f3 100644
--- a/tools/check-generated-fresh.mjs
+++ b/tools/check-generated-fresh.mjs
@@ -84,7 +84,8 @@ for (const file of emitted) {
const rel = path.join(root[1], path.relative(root[0], file));
const committed = path.join(ROOT, rel);
if (!existsSync(committed)) { stale.push([rel, 'not committed at all']); continue; }
- if (readFileSync(committed).equals(readFileSync(file))) continue;
+ // Git may check text out as CRLF; EHT always writes LF.
+ if (readFileSync(committed, 'utf8').replace(/\r\n/g, '\n') === readFileSync(file, 'utf8').replace(/\r\n/g, '\n')) continue;
stale.push([rel, 'differs from what the generator produces now']);
}
rmSync(out, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
diff --git a/tools/launchers/launch-export.mjs b/tools/launchers/launch-export.mjs
index 7ece8241f..5bc0e3beb 100644
--- a/tools/launchers/launch-export.mjs
+++ b/tools/launchers/launch-export.mjs
@@ -291,6 +291,10 @@ const SCENE = flag('scene', '');
}
}
+ // Paint Timing excludes a page hidden before its first contentful paint.
+ // A boot measurement must present the page before navigation; background
+ // throttling alone only keeps its JavaScript running. Do not steal focus.
+ if (BOOT) win.showInactive();
await win.loadURL(base);
// A boot measurement waits for the boot, not for a canvas with a size: the
diff --git a/tools/lib/nativeBytecode.mjs b/tools/lib/nativeBytecode.mjs
new file mode 100644
index 000000000..0d2d643b6
--- /dev/null
+++ b/tools/lib/nativeBytecode.mjs
@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+
+/** Match the source identity already stored by native/tools/mkbc.c and checked
+ * by native/host/Runtime.cpp. Artifact extraction and rebuilding an unchanged SDK
+ * alter file times, but neither changes which SDK the bytecode contains. */
+export function bytecodeMatchesBundle(bytecode, bundle) {
+ if (bytecode.length <= 8) return false;
+ // generateSdkBundle embeds one leading newline before the UTF-8 bundle.
+ let hash = 1469598103934665603n;
+ for (const byte of Buffer.concat([Buffer.from('\n'), Buffer.from(bundle)])) {
+ hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * 1099511628211n);
+ }
+ return bytecode.readBigUInt64LE(0) === hash;
+}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 14321f184..dcd023a8f 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,12 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'perf(i18n): cache bounded plain translations with invalidation':
+ { note: 'Unchanged plain translations use a bounded cache.' },
+ 'fix(editor): stabilize camera previews and hidden authoring checks':
+ { note: 'A selected camera has a preview without advancing gameplay.' },
+ 'fix(release): prepare v0.77.0 candidate and portable validation':
+ { note: 'Release checks compare the content that ships.' },
'feat(build): the size panel says which budget each byte is on':
{ note: "The build's size panel marks which files are in a subpackage." },
@@ -1334,4 +1340,74 @@ export const NOTED = {
{ note: 'A project that moves keeps answering its textures from its own cache' },
'fix(eht): the generator writes LF on every platform':
{ internal: 'The engine header tool is a repository generator; on Windows it rewrote every generated file with CRLF, which only a contributor there ever saw.' },
+
+ // v0.77.0: audited engine and editor changes.
+ "fix(tools): load production hierarchy button styles (#87)":
+ {"internal":"Loads shipped styles in a repository measurement harness; no production behavior changes."},
+ "fix(ui): escape text cache parameter boundaries (#86)":
+ {"note":"Text cache entries respect overflow and parameter boundaries."},
+ "fix(ui): invalidate text cache when overflow changes (#85)":
+ {"note":"Text cache entries respect overflow and parameter boundaries."},
+ "fix(ui): restrict nested dialog focus to inner modal (#84)":
+ {"note":"Keyboard and pointer focus stay with eligible UI controls."},
+ "fix(ui): retain quick-click edges for pointer focus (#81)":
+ {"note":"Keyboard and pointer focus stay with eligible UI controls."},
+ "fix(ui): exclude hierarchically hidden dialogs from focus scope (#80)":
+ {"note":"Keyboard and pointer focus stay with eligible UI controls."},
+ "fix(ui): clear focus when live navigation eligibility changes (#79)":
+ {"note":"Keyboard and pointer focus stay with eligible UI controls."},
+ "fix(ui): keep Web keyboard traversal in the game (#78)":
+ {"note":"Keyboard and pointer focus stay with eligible UI controls."},
+ "feat(events): expose immutable dispatch observations for UI debugger (#75)":
+ {"note":"The UI Debugger follows the live game."},
+ "fix: integrate less intrusive 2D gizmo interaction":
+ {"note":"Gizmo controls keep a 2D scene easier to edit."},
+ "feat: publish screen UI projection helpers for debugger picking":
+ {"note":"The UI Debugger follows the live game."},
+ "feat(ui): export mask mode and verify nested mask inspection":
+ {"note":"The UI Debugger follows the live game."},
+ "feat(ui): verify layout and input inspection in Web fixture (#73)":
+ {"note":"The UI Debugger follows the live game."},
+ "feat(ui): add pseudolocalization and text layout diagnostics":
+ {"note":"UI text inspection and pseudolocalization previews."},
+ "feat: render camera previews without advancing gameplay":
+ {"note":"A selected camera has a preview without advancing gameplay."},
+ "fix(editor): integrate selected-only gizmos and 2D priorities":
+ {"note":"Gizmo controls keep a 2D scene easier to edit."},
+ "fix: publish Android frame reports without source hooks":
+ {"note":"Device reports can inspect prebuilt native apps."},
+ "fix: verify prebuilt native apps without packaging templates":
+ {"note":"Device reports can inspect prebuilt native apps."},
+ "feat: add device quality policy and lighting validation":
+ {"note":"Device quality profiles can be previewed in the editor."},
+ "fix(editor): align UI debugger hierarchy rows (#17)":
+ {"note":"The UI Debugger follows the live game."},
+ "fix(editor): preserve event recording across debugger tabs (#16)":
+ {"note":"The UI Debugger follows the live game."},
+ "fix(editor): inspect text input and dialog components (#15)":
+ {"note":"The UI Debugger follows the live game."},
+ "feat(editor): inspect live runtime focus and Tab traversal (#14)":
+ {"note":"The UI Debugger follows the live game."},
+ "fix(editor): clarify event paths and filtered empty state (#13)":
+ {"note":"The UI Debugger follows the live game."},
+ "feat(editor): record actual entity event dispatch in UI debugger (#12)":
+ {"note":"The UI Debugger follows the live game."},
+ "fix: reduce gizmo clutter and inactive handle interception":
+ {"note":"Gizmo controls keep a 2D scene easier to edit."},
+ "feat: add UI debugger element picking and live inspection":
+ {"note":"The UI Debugger follows the live game."},
+ "feat(ui): diagnose ancestor masks and rectangular clipping":
+ {"note":"The UI Debugger follows the live game."},
+ "feat(ui): inspect layout bounds and input configuration (#10)":
+ {"note":"The UI Debugger follows the live game."},
+ "feat(ui): add localization preview and text overflow inspector":
+ {"note":"UI text inspection and pseudolocalization previews."},
+ "feat: add selected camera preview and editor acceptance checks":
+ {"note":"A selected camera has a preview without advancing gameplay."},
+ "fix(viewport): show detailed gizmos for selected entities":
+ {"note":"Gizmo controls keep a 2D scene easier to edit."},
+ "fix: test paired engine changes in editor CI":
+ {"internal":"Chooses the matching engine branch in editor CI; changes only contributor verification."},
+ "feat: preview device quality and stabilize lighting workflows":
+ {"note":"Device quality profiles can be previewed in the editor."},
};
diff --git a/tools/tests/native-bytecode.test.ts b/tools/tests/native-bytecode.test.ts
new file mode 100644
index 000000000..0d4b892e4
--- /dev/null
+++ b/tools/tests/native-bytecode.test.ts
@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, expect, it } from 'vitest';
+import { bytecodeMatchesBundle } from '../lib/nativeBytecode.mjs';
+
+describe('native bytecode source identity', () => {
+ // mkbc's 64-bit source header for the newline-prefixed UTF-8 bundle below.
+ const bytecode = Buffer.from('4efef755917e96b8010203', 'hex');
+ const bundle = Buffer.from('globalThis.ESEngine = {};');
+ it('accepts the matching SDK independent of when files were copied or rebuilt', () => {
+ expect(bytecodeMatchesBundle(bytecode, bundle)).toBe(true);
+ expect(bytecodeMatchesBundle(Buffer.from(bytecode), Buffer.from(bundle))).toBe(true);
+ });
+ it('rejects changed SDK bytes and malformed bytecode', () => {
+ expect(bytecodeMatchesBundle(bytecode, Buffer.from('globalThis.ESEngine = {changed: true};'))).toBe(false);
+ expect(bytecodeMatchesBundle(bytecode.subarray(0, 8), bundle)).toBe(false);
+ const corrupt = Buffer.from(bytecode); corrupt[0] ^= 1;
+ expect(bytecodeMatchesBundle(corrupt, bundle)).toBe(false);
+ });
+});
diff --git a/tools/verify-native-conformance.mjs b/tools/verify-native-conformance.mjs
index 2bef3f29c..f72b7b30f 100644
--- a/tools/verify-native-conformance.mjs
+++ b/tools/verify-native-conformance.mjs
@@ -28,6 +28,7 @@ import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { installedTemplateDir } from '../build-tools/utils/nativeTemplate.js';
import { desktopExecutableIn } from '../build-tools/utils/desktopApp.js';
+import { bytecodeMatchesBundle } from './lib/nativeBytecode.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const PROJECT = path.join(ROOT, 'fixtures', 'aot-conformance');
@@ -73,11 +74,12 @@ function newestSource(dir) {
// run was started to find. Exactly that happened while sabotaging markChanged_.
const bytecode = path.join(template, 'esengine.native.qjsbc');
const bundle = path.join(ROOT, 'sdk', 'dist', 'index.native.bundled.js');
-const stale = !existsSync(bytecode) || !existsSync(bundle) ? null
+const stale = !existsSync(bytecode) || !existsSync(bundle)
+ ? { why: 'SDK bundle or template bytecode is missing', fix: `pnpm --filter ./sdk build && node build-tools/cli.js native --target ${os}` }
: newestSource(path.join(ROOT, 'sdk', 'src')) > statSync(bundle).mtimeMs
? { why: 'sdk/dist is older than sdk/src', fix: 'pnpm --filter ./sdk build' }
- : statSync(bundle).mtimeMs > statSync(bytecode).mtimeMs
- ? { why: `the ${os} template embeds an older SDK than sdk/dist`,
+ : !bytecodeMatchesBundle(readFileSync(bytecode), readFileSync(bundle))
+ ? { why: `the ${os} template embeds a different SDK from sdk/dist`,
fix: `node build-tools/cli.js native --target ${os}` }
: null;
if (stale) {