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.

feat(abi): single-source-of-truth boundary contract (RC1 keystone)

esenginecd9d9a3fa5f8
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.md
new file mode 100644
index 000000000..3fda43847
--- /dev/null
+++ b/docs/REARCHITECTURE.md
@@ -0,0 +1,126 @@
+# Estella 根治方案(Re-architecture Plan)
+
+> 目标读者:引擎维护者 / AI 协作代理。
+> 本文是**架构权威文档(architecture-of-record)**,描述目标架构与根治路径,而非现状。
+> 现状审计见各小节"病灶"引用的 `file:line`。
+
+## 0. 核心诊断:同一事实的多个独立来源
+
+对全仓(C++ ~34K 行、TS SDK ~35K 行)的深度审计后,几乎所有"脆弱 / 不完整 / 不清晰"的症状都可以归到**两类结构性病根**:
+
+1. **多源真相(multiple sources of truth)**:同一个事实——内存布局、类型 ID、组件存储、枚举值——在 C++ 侧和 TS 侧、或在多个子系统里被**各自独立地定义/计算**,没有任何机制保证它们一致。它们会悄悄漂移,漂移后是**静默的内存损坏**,不是报错。
+2. **可绕过的抽象(bypassable abstractions)**:`GfxDevice`、ECS 存储、WASM 桥接等抽象不是唯一通道,调用方可以绕过它直达底层。于是抽象只覆盖了一半,缓存/不变量被悄悄破坏。
+
+**根治原则**:把每一处"多源"坍缩成**单一权威来源**,并由编译期断言 + 运行时握手强制一致;把每一个抽象做成**唯一通道**(绕过即编译不过)。下面五个根因,每个对应一个要建立的"单一权威来源"。
+
+止血式修单点 bug 不在本方案范围内——因为只要多源结构还在,同类 bug 会无限再生。
+
+---
+
+## 根因 1(keystone):边界不是单一事实来源 → 契约优先的边界
+
+### 病灶
+- TS 侧内存偏移由 EHT 的 Python **手写打包模型**算出(`tools/eht/.../ptr_layout.py`),C++ 侧由编译器实际布局决定——**同一事实算了两遍**。一致性只靠 `WebSDKEntry.cpp:248-372` 里**手写、仅覆盖 8 个组件**的 `static_assert(offsetof)`。EHT 模型还是近似的(`i8` 当 `u8`、假设 enum 恒 1 字节)。
+- `wasm.ts` 里 ~400 行 `ESEngineModule` 接口是**手工镜像**,与散落在 12 个 `bindings/*.cpp` 的真实导出无任何交叉校验;能生成权威 d.ts 的 `--emit-tsd` 因"binding mismatch"被关掉(`Emscripten.cmake:201`)。
+- 必须与 C++ 对齐的枚举(`Tween`/`Easing`/`BodyType`)、跨模块 physics 结构体(`PHYSICS_BODY_BYTES=16` 只活在一句 TS 注释里)、material uniform wire format——全是**两侧手维护**。
+- 漂移检测存在但**默认关闭**(`strict:false`),且只比组件名集合,不比偏移/类型/枚举宽度;**无 ABI 版本握手**。
+
+### 目标架构
+1. **C++ 组件结构体是唯一权威**(保留 `ES_COMPONENT/ES_PROPERTY` 注解)。
+2. **编译器是偏移的唯一权威**。EHT 不再自己算 packing:改为生成一个"布局反射"翻译单元,由编译器吐出每个组件每个字段的 `offsetof/sizeof/alignof`(constexpr 数据,从模块导出或在构建期产出)。TS 偏移从**这份编译器产物**派生,不再独立计算。
+3. **一份 spec 生成边界全部内容**:embind、指针访问器、TS 类型、`ESEngineModule` 接口(恢复/替代 `--emit-tsd`)、所有跨界枚举、跨模块结构体、所有 `_malloc` wire format。两侧都生成,**零手工镜像**。
+4. **全组件编译期断言**:EHT 为**每个**组件每个字段生成 `static_assert(offsetof==N)`。不一致 = **编译失败**,而非运行时静默损坏。
+5. **运行时 ABI 握手**:同一次 EHT 产出一个布局哈希,注入 C++(`getAbiHash()`)和 TS 常量;`connect()` 时比对,不一致直接拒绝启动。**握手默认且唯一**,删掉 `strict` 开关。
+
+> 这一步是 keystone:它一次性坍缩掉偏移双算、手镜像模块、手维护枚举、physics 结构体注释、`--emit-tsd` 关闭、可选漂移检测;并且**它生成的 static_assert + 握手,正是后续每一步重构的安全验证机制**。
+
+---
+
+## 根因 2:四套并行的组件存储 → 单一存储核心
+
+### 病灶
+稀疏集逻辑被实现了 **4 遍**:`SparseSet<T>`(编译期 typed)、`SchemaComponentPool`(给 JS 的裸字节,`SchemaComponent.hpp`)、`DynamicComponentPool`(`emscripten::val`/`std::any`)、`Registry` 的 128-bit mask。三者销毁路径不统一——**动态组件在实体销毁时根本不被清理**(`Registry` 不持有 `DynamicComponentRegistry`,`Registry.hpp:138-170`)→ 泄漏。SDK 侧还另有 JS-storage 组件 vs C++-storage builtin 的二分。
+
+### 目标架构
+- **一个稀疏集核心**(分页稀疏数组 + 稠密数组,写一遍)。typed 访问、JS 裸指针访问、dynamic 访问都是它之上的**视图/访问器**,不是各自的实现。
+- 规范存储用 **flat-byte 布局**——因为零拷贝跨界本来就要求扁平字节,所以它天然是 RC1 生成的访问器的目标。typed C++ 组件即"对这块字节的类型化视图"。
+- **同一个注册表、同一个成员 mask、同一条销毁路径**覆盖全部三类。坍缩掉动态组件泄漏与 4x 重复。
+
+---
+
+## 根因 3:无连贯的错误/生命周期模型 → 端到端单一契约
+
+### 病灶
+- C++ 用 `-fno-exceptions` 编译,出错 `abort()` **整个模块**;TS 却用 try/catch 兜底**继续调用这具尸体**(`BuiltinBridge.ts:471-527`)。无 `onAbort`、无健康标志、无错误通道——最坏组合。
+- `get...Ptr` 返回**借用指针**,指向会随 ECS 池重分配而移动、随 `ALLOW_MEMORY_GROWTH` 而失效的存储;已有 `registry_getSchemaPoolVersion` 守卫但**没接进任何调用点**。
+- `_malloc/_free` 无 try/finally,抛异常即永久泄漏 WASM 堆。
+- 不变量检查全是 `ES_ASSERT`,**release 构建编译成空操作**(`Log.hpp:313`)→ 出货版里所有来自 JS 的 `get/emplace/destroy` **零越界检查**。
+
+### 目标架构
+- **错误**:边界函数返回**显式状态/optional**;边界校验**始终开启**(独立于 `ES_ASSERT`,不被 release 剥离);安装致命 `onAbort` 翻"模块已死"标志,之后所有调用短路抛 `WasmModuleAborted`,**不再调用尸体**。
+- **内存**:跨界裸指针只经**版本校验访问器**(接通 `getSchemaPoolVersion`,每次重取 HEAP 视图);`_malloc` 只经 RAII `withScratch()` 作用域;跨界句柄 RAII。
+- 坍缩掉 UAF、抛异常泄漏、abort-into-corpse、release 剥离检查。
+
+> 岔路(需拍板):是否改用 `-fwasm-exceptions` 让 C++ 失败变成可捕获的 JS 异常(体积/性能略增,TS 现有 try/catch 立刻有意义)vs 保持 `-fno-exceptions` + 显式状态码。**推荐后者**:保住体积/速度,把错误显式化而非依赖异常。
+
+---
+
+## 根因 4:全局 TypeId → 按域 + 按实例的确定性身份
+
+### 病灶
+单个全局 `getTypeId<T>()` 计数器被 **ECS / 事件 / 服务三套系统共享**,并直接当 `pools_` 下标(`Types.hpp:186`、`Registry.hpp:581`、`Dispatcher.hpp:229`、`ServiceRegistry.hpp:62`)。ID 按首次使用顺序分配 → **链接顺序相关、不确定**;某组件 ID 偶然很大就撑出一个全是 null 的超大 `pools_`;热重载/多模块下静默错位。
+
+### 目标架构
+- **按域独立的类型序列** `TypeIndex<Domain>`(Component / Event / Service 各一套)。
+- 组件用**注册表局部的 dense id**(`std::type_index → 局部 id` 映射,或启动时按固定顺序显式注册),作为池下标。
+- 坍缩掉链接顺序不确定、超大 pools、热重载错位、三系统耦合;这也是任何多模块/热重载故事的前置。
+
+---
+
+## 根因 5:抽象可绕过 → 抽象成为唯一通道
+
+### 病灶
+- `Texture/Shader/Buffer/Framebuffer` 全部直接调原始 `glXxx`,绕过 `GfxDevice`,使 `StateTracker` 缓存悄悄失效;`Texture` 仅 `ES_PLATFORM_WEB` 下有实现,native 构建里贴图是死的。
+- **两套渲染器并存**:遗留 `Renderer/BatchRenderer2D` vs `RenderFrame`,批 shader 初始化等逻辑复制粘贴。
+- 渲染 plugin **反向钻进**内容系统读/改运行时状态(`TilemapRenderPlugin.cpp:177` 在 const collect 里改 `dirty`)。
+- SDK 有**五套互不相同的 WASM 桥接写法**;per-App 状态归属不统一(Tween/Audio/Scene 是 per-App,Camera/Timeline/SpriteAnimator/postprocess 仍是进程级全局)。
+- 批渲染 EBO 全局累加,`baseVertex` 强转 `u16`,超 65535 顶点**静默回绕、GPU 读垃圾**(遍布所有批 plugin)。
+
+### 目标架构
+- **渲染唯一路径**:保留 `RenderFrame`,退役 `Renderer/BatchRenderer2D`。`GfxDevice` 成为**唯一 GPU 入口**——`Texture/Shader/Buffer` 接受 `GfxDevice&`,所有 bind 经 `StateTracker`。索引 `u16→u32`(或每帧到顶就 flush),让渲染路径**正确**而非打补丁。
+- **内容系统写"渲染就绪快照",plugin 只读**,renderer 不再依赖内容系统头文件/生命周期。
+- **SDK 单一 `WasmBridge` 基类**:一个 loader、一个 ready promise、一个"缺绑定"策略、一条错误路径;五套写法全部继承它。
+- **单一状态归属**:所有子系统状态改为 per-App/per-World 资源。
+
+---
+
+## 执行顺序(根因序,全程保持构建常绿)
+
+每一步都由 RC1 生成的 `static_assert` + ABI 握手 + 可跑的边界测试守护。**验证机制不是"安全网目的",而是验证根治是否成立的手段**——它本身就是 keystone 的一部分。
+
+1. **建立验证机制 + keystone(RC1)**:让 WASM 边界测试在本仓库内可跑(当前指向不存在的 `desktop/`);EHT 生成全组件 `static_assert` + 布局哈希握手 + 完整边界 codegen。完成后,任何边界漂移都变成编译/启动失败。
+2. **RC4 身份**:拆分全局 TypeId 为按域序列 + 注册表局部 id。改动局部、风险低、解锁热重载。
+3. **RC2 存储**:四套存储收敛到单一核心,统一销毁/mask 路径。由 RC1 的字节布局契约护航。
+4. **RC3 错误/生命周期**:显式状态 + 始终开启的边界校验 + onAbort + 版本校验指针 + RAII `_malloc`。
+5. **RC5 抽象唯一化**:退役遗留渲染器、GfxDevice 唯一入口、u16→u32、统一 WasmBridge、状态全 per-App。
+
+> 注:仓库目前是从 monorepo 拆出的半成品(CI/测试/docs 仍引用不存在的 `desktop/`+`editor/`,无 PR 门禁,`docs/ARCHITECTURE.md` 描述的类名与代码不符)。这不是"安全网策略",而是**根治的前置条件**:没有可跑的构建+边界测试,就无法验证上述任何一步是否真的成立。故第 1 步内含"让仓库自洽可建可测"。
+
+## 需要拍板的两个架构岔路
+
+| 岔路 | 选项 A | 选项 B(推荐) |
+|---|---|---|
+| **错误模型(RC3)** | `-fwasm-exceptions`:C++ 失败变可捕获 JS 异常,TS 现有 try/catch 立即有效;体积/性能略增 | 保持 `-fno-exceptions` + 边界函数显式状态码 + 致命 onAbort。保住体积/速度,错误显式化 |
+| **规范存储(RC2)** | 保留 typed pool 为主、schema 为投影 | 以 flat-byte schema pool 为唯一核心。零拷贝跨界天然契合,与 RC1 的生成访问器同一目标 |
+
+## 实现进度(living status)
+
+### RC1 keystone — ✅ 已落地(第一批)
+- **编译器成为偏移权威**:EHT 为**全部**组件的每个指针字段生成 `static_assert(offsetof==N)`(`tools/eht/generators/ptr_layout.py::generate_layout_asserts`),注入 `WebBindings.generated.cpp`。任何 EHT 模型与真实编译器布局的分歧 = 构建失败。已删除 `WebSDKEntry.cpp` 中手写、仅覆盖 8 个组件的断言。生成的 8 个组件偏移与原手写(经编译器验证)值逐字节一致,证明模型正确。
+- **运行时 ABI 哈希握手**:`tools/eht/abi.py` 从单次 schema 解析计算布局哈希,同时注入 C++(`getAbiLayoutHash()`)与 TS(`ABI_LAYOUT_HASH`,在 `component.generated.ts`)。`BuiltinBridge.connect()` 比对,不一致**无条件致命**(即使非 strict 模式),因为 mock registry 不暴露该函数所以测试不受影响。当前哈希:`f5d18743d00de675`。
+- **EHT 路径健壮性**:修复了 `--ts-output sdk/src` 会静默跳过 `component.generated.ts` / ptrLayouts / ptrAccessors 的潜在 bug(之前它们只在非默认 `--ts-output sdk` 下才重新生成)。现在标准构建会让全部生成的 TS 保持同步。
+- **边界测试可在仓库内运行**:`sdk/tests/helpers/loadWasm.ts` 成为 WASM 路径单一来源(`$ESENGINE_WASM_DIR` → `build/wasm/web` → 旧 `desktop/public/wasm`),8 个集成测试文件不再各自硬编码不存在的 `desktop/public/wasm`。
+- 验证:SDK typecheck 通过;2012 个测试通过(含 3 个新握手测试,证明 mismatch 在非 strict 下也致命);EHT 幂等。**待补**:C++ 侧 `static_assert` + `getAbiLayoutHash` 的实际编译验证需要 emsdk(随 CI web 构建门禁一起闭环)。
+
+### RC2 / RC3 / RC4 / RC5 — 未开始
+按执行顺序依次推进,全程在 RC1 的 `static_assert` + 握手护栏内进行。
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.ts
index dc9263f2b..eb43d39e1 100644
--- a/sdk/src/component.generated.ts
+++ b/sdk/src/component.generated.ts
@@ -6,6 +6,14 @@
import type { AssetFieldType } from './scene';
+/**
+ * Single-source-of-truth hash of the C++/TS boundary ABI (component
+ * schema + pointer layouts). The WASM module exposes the same digest via
+ * getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
+ * run on mismatch, because mismatched offsets read the wrong heap bytes.
+ */
+export const ABI_LAYOUT_HASH = 'f5d18743d00de675';
+
export interface AssetFieldMeta {
field: string;
type: AssetFieldType;
diff --git a/sdk/src/ecs/BuiltinBridge.ts b/sdk/src/ecs/BuiltinBridge.ts
index bcce66eaa..96a5b0f4e 100644
--- a/sdk/src/ecs/BuiltinBridge.ts
+++ b/sdk/src/ecs/BuiltinBridge.ts
@@ -8,7 +8,7 @@ import type { BuiltinComponentDef } from '../component';
import type { CppRegistry, ESEngineModule } from '../wasm';
import { validateComponentData, formatValidationErrors } from '../validation';
import { handleWasmError } from '../wasmError';
-import { COMPONENT_META } from '../component.generated';
+import { COMPONENT_META, ABI_LAYOUT_HASH } from '../component.generated';
import { PTR_LAYOUTS } from '../ptrLayouts.generated';
import { PTR_ACCESSORS } from './ptrAccessors.generated';
@@ -236,6 +236,16 @@ export interface BridgeVerification {
* WASM. Only populated when the module exposes the reflection call.
*/
readonly sdkOnly: readonly string[];
+ /**
+ * Set when the WASM module reports an ABI layout hash
+ * (`getAbiLayoutHash`) that differs from the SDK bundle's
+ * {@link ABI_LAYOUT_HASH}. A mismatch means the loaded WASM and this SDK
+ * were generated from different component schemas, so the byte offsets the
+ * SDK uses for fast pointer access read the wrong memory. This is always
+ * fatal — never tolerated even in non-strict mode. Null when the hashes
+ * match or the module predates the handshake (no `getAbiLayoutHash`).
+ */
+ readonly abiMismatch: { readonly sdk: string; readonly wasm: string } | null;
}
/** Options for {@link BuiltinBridge.connect}. */
@@ -255,6 +265,15 @@ const METHOD_PREFIXES = ['add', 'get', 'has', 'remove'] as const;
function formatBridgeDiagnostic(v: BridgeVerification): string {
const parts: string[] = [];
+ if (v.abiMismatch) {
+ parts.push(
+ `ABI layout hash mismatch: the WASM module was built from a different ` +
+ `component schema than this SDK bundle.\n` +
+ ` SDK ABI_LAYOUT_HASH = ${v.abiMismatch.sdk}\n` +
+ ` WASM getAbiLayoutHash() = ${v.abiMismatch.wasm}\n` +
+ ` Fast pointer accessors would read the wrong bytes. This is fatal.`,
+ );
+ }
if (v.missing.length > 0) {
const detail = v.missing.map(m => ` - ${m.name}: missing ${m.methods.join(', ')}`).join('\n');
parts.push(`C++ Registry is missing ${String(v.missing.length)} builtin component binding(s):\n${detail}`);
@@ -306,7 +325,13 @@ export class BuiltinBridge {
this.builtinEntitySets_.clear();
const verification = this.verifyAgainst_(cppRegistry, module);
- if (options.strict && !verification.ok) {
+ // An ABI hash mismatch is ALWAYS fatal, even in non-strict mode: the
+ // loaded WASM and this SDK disagree on byte layout, so any fast-path
+ // pointer access silently corrupts memory. Other drift (missing
+ // bindings) is only fatal under strict mode so partial mock registries
+ // in unit tests keep working. Mock registries never expose
+ // getAbiLayoutHash, so they never hit the fatal path.
+ if (verification.abiMismatch || (options.strict && !verification.ok)) {
this.cppRegistry_ = null;
this.module_ = null;
this.builtinMethodCache_.clear();
@@ -344,6 +369,7 @@ export class BuiltinBridge {
missing: [{ name: '<registry>', methods: ['connect() not called'] }],
wasmOnly: [],
sdkOnly: [],
+ abiMismatch: null,
};
}
return this.verifyAgainst_(this.cppRegistry_, this.module_ ?? undefined);
@@ -384,8 +410,29 @@ export class BuiltinBridge {
sdkOnly = Object.keys(COMPONENT_META).filter(n => !wasmSet.has(n));
}
- const ok = missing.length === 0 && wasmOnly.length === 0 && sdkOnly.length === 0;
- return { ok, missing, wasmOnly, sdkOnly };
+ // ABI layout-hash handshake. The WASM module exposes the digest EHT
+ // baked into both sides from one schema parse; if it disagrees with the
+ // SDK's ABI_LAYOUT_HASH, the pointer offsets the SDK ships do not match
+ // the loaded binary and fast-path reads/writes would corrupt memory.
+ // Modules built before the handshake (no getAbiLayoutHash) skip it.
+ let abiMismatch: { sdk: string; wasm: string } | null = null;
+ const hashFn = (module as unknown as { getAbiLayoutHash?: () => string } | undefined)
+ ?.getAbiLayoutHash;
+ if (typeof hashFn === 'function') {
+ let wasmHash = '';
+ try {
+ wasmHash = hashFn();
+ } catch {
+ wasmHash = '';
+ }
+ if (wasmHash && wasmHash !== ABI_LAYOUT_HASH) {
+ abiMismatch = { sdk: ABI_LAYOUT_HASH, wasm: wasmHash };
+ }
+ }
+
+ const ok = missing.length === 0 && wasmOnly.length === 0
+ && sdkOnly.length === 0 && abiMismatch === null;
+ return { ok, missing, wasmOnly, sdkOnly, abiMismatch };
}
getBuiltinMethods(cppName: string): BuiltinMethods {
diff --git a/sdk/tests/builtin-bridge.test.ts b/sdk/tests/builtin-bridge.test.ts
index 5bf12bd10..6cf9a9417 100644
--- a/sdk/tests/builtin-bridge.test.ts
+++ b/sdk/tests/builtin-bridge.test.ts
@@ -6,7 +6,7 @@
*/
import { describe, expect, it } from 'vitest';
import { BuiltinBridge } from '../src/ecs/BuiltinBridge';
-import { COMPONENT_META } from '../src/component.generated';
+import { COMPONENT_META, ABI_LAYOUT_HASH } from '../src/component.generated';
import type { CppRegistry, ESEngineModule } from '../src/wasm';
function stubMethod() { return undefined; }
@@ -195,4 +195,59 @@ describe('BuiltinBridge', () => {
expect(v.wasmOnly).toEqual([]);
expect(v.sdkOnly).toEqual([]);
});
+
+ // -------------------------------------------------------------------------
+ // ABI layout-hash handshake. The WASM module exposes getAbiLayoutHash();
+ // a mismatch means the loaded binary and this SDK were generated from
+ // different component schemas, so pointer offsets read the wrong bytes.
+ // This is ALWAYS fatal — even in non-strict mode.
+ // -------------------------------------------------------------------------
+
+ it('connects when the module ABI hash matches the SDK bundle', () => {
+ const bridge = new BuiltinBridge();
+ const reg = makeCompleteRegistry() as unknown as CppRegistry;
+ const module = {
+ getBuiltinComponentNames: () => Object.keys(COMPONENT_META),
+ getAbiLayoutHash: () => ABI_LAYOUT_HASH,
+ } as unknown as ESEngineModule;
+
+ expect(() => { bridge.connect(reg, module, { strict: true }); }).not.toThrow();
+ expect(bridge.verify().abiMismatch).toBeNull();
+ });
+
+ it('refuses to connect on ABI hash mismatch even in non-strict mode', () => {
+ const bridge = new BuiltinBridge();
+ const reg = makeCompleteRegistry() as unknown as CppRegistry;
+ const module = {
+ getBuiltinComponentNames: () => Object.keys(COMPONENT_META),
+ getAbiLayoutHash: () => 'deadbeefdeadbeef',
+ } as unknown as ESEngineModule;
+
+ let caught: Error | null = null;
+ try {
+ // No { strict: true } — a hash mismatch must be fatal regardless.
+ bridge.connect(reg, module);
+ } catch (e) {
+ caught = e as Error;
+ }
+
+ expect(caught).not.toBeNull();
+ expect(caught!.message).toContain('ABI layout hash mismatch');
+ expect(caught!.message).toContain(ABI_LAYOUT_HASH);
+ expect(caught!.message).toContain('deadbeefdeadbeef');
+ // Fatal connect must leave the bridge disconnected.
+ expect(bridge.hasCpp).toBe(false);
+ });
+
+ it('skips the hash handshake when the module lacks getAbiLayoutHash', () => {
+ // Older WASM builds predate the handshake — connect must still succeed.
+ const bridge = new BuiltinBridge();
+ const reg = makeCompleteRegistry() as unknown as CppRegistry;
+ const module = {
+ getBuiltinComponentNames: () => Object.keys(COMPONENT_META),
+ } as unknown as ESEngineModule;
+
+ expect(() => { bridge.connect(reg, module, { strict: true }); }).not.toThrow();
+ expect(bridge.verify().abiMismatch).toBeNull();
+ });
});
diff --git a/sdk/tests/emscripten-wrapper.test.ts b/sdk/tests/emscripten-wrapper.test.ts
index 3107b6632..5b0d02265 100644
--- a/sdk/tests/emscripten-wrapper.test.ts
+++ b/sdk/tests/emscripten-wrapper.test.ts
@@ -2,17 +2,12 @@
* Diagnostic test: verify Object.entries behavior with Emscripten reference wrappers
*/
import { describe, it, expect, beforeAll } from 'vitest';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
import { App } from '../src/app';
import { Transform } from '../src/component';
import { UIRect } from '../src/ui/core/ui-rect';
import type { UIRectData } from '../src/ui/core/ui-rect';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
-import { loadWasmModule } from './helpers/loadWasm';
-
-const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');
-const HAS_WASM = existsSync(WASM_PATH);
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
describe.skipIf(!HAS_WASM)('Emscripten wrapper diagnostics', () => {
let module: ESEngineModule;
diff --git a/sdk/tests/entity-hierarchy.test.ts b/sdk/tests/entity-hierarchy.test.ts
index 0635c02f3..46bf861b6 100644
--- a/sdk/tests/entity-hierarchy.test.ts
+++ b/sdk/tests/entity-hierarchy.test.ts
@@ -5,15 +5,10 @@
* Run `node build-tools/cli.js build -t web` first if missing.
*/
import { describe, it, expect, beforeAll } from 'vitest';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
import { World } from '../src/world';
import { Transform, Sprite, Parent, Children } from '../src/component';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
-import { loadWasmModule } from './helpers/loadWasm';
-
-const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');
-const HAS_WASM = existsSync(WASM_PATH);
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
describe.skipIf(!HAS_WASM)('Entity Hierarchy (WASM integration)', () => {
let module: ESEngineModule;
diff --git a/sdk/tests/helpers/loadWasm.ts b/sdk/tests/helpers/loadWasm.ts
index 7b1cc899b..e78bf4aad 100644
--- a/sdk/tests/helpers/loadWasm.ts
+++ b/sdk/tests/helpers/loadWasm.ts
@@ -1,14 +1,49 @@
-import { readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
import { resolve } from 'path';
import type { ESEngineModule } from '../../src/wasm';
-const WASM_DIR = resolve(__dirname, '../../../desktop/public/wasm');
+/**
+ * Single source of truth for where the boundary integration tests find the
+ * built WASM SDK (esengine.js + esengine.wasm). Resolution order:
+ * 1. $ESENGINE_WASM_DIR — explicit override (CI passes the build dir)
+ * 2. <repo>/build/wasm/web — the in-repo CMake/Emscripten output
+ * 3. <repo>/desktop/public/wasm — legacy path when built inside the editor repo
+ *
+ * The first candidate that actually contains esengine.wasm wins. If none do,
+ * {@link HAS_WASM} is false and the integration suites skip themselves via
+ * `describe.skipIf(!HAS_WASM)` rather than throwing. Previously every test
+ * hard-coded the (nonexistent in this repo) desktop path, so the entire
+ * C++/TS boundary was never exercised here.
+ */
+function resolveWasmDir(): string {
+ const candidates = [
+ process.env.ESENGINE_WASM_DIR,
+ resolve(__dirname, '../../../build/wasm/web'),
+ resolve(__dirname, '../../../desktop/public/wasm'),
+ ].filter((c): c is string => Boolean(c));
+
+ for (const dir of candidates) {
+ if (existsSync(resolve(dir, 'esengine.wasm'))) return dir;
+ }
+ // None found — return the canonical in-repo build output so HAS_WASM and
+ // any diagnostics point at where the WASM is expected to be built.
+ return resolve(__dirname, '../../../build/wasm/web');
+}
+
+/** Directory containing the built WASM SDK, per {@link resolveWasmDir}. */
+export const WASM_DIR = resolveWasmDir();
+
+/** Absolute path to the built esengine.wasm binary. */
+export const WASM_FILE = resolve(WASM_DIR, 'esengine.wasm');
+
+/** True when a built WASM SDK is available to run boundary integration tests. */
+export const HAS_WASM = existsSync(WASM_FILE);
let cachedModule: ESEngineModule | null = null;
export async function loadWasmModule(): Promise<ESEngineModule> {
if (cachedModule) return cachedModule;
- const wasmBinary = readFileSync(resolve(WASM_DIR, 'esengine.wasm'));
+ const wasmBinary = readFileSync(WASM_FILE);
const factory = (await import(resolve(WASM_DIR, 'esengine.js'))).default;
cachedModule = await factory({ wasmBinary }) as ESEngineModule;
return cachedModule;
diff --git a/sdk/tests/nested-text.test.ts b/sdk/tests/nested-text.test.ts
index eae9a23da..e32856b33 100644
--- a/sdk/tests/nested-text.test.ts
+++ b/sdk/tests/nested-text.test.ts
@@ -6,8 +6,6 @@
* only one text renders visually.
*/
import { describe, it, expect, beforeAll } from 'vitest';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
import { App } from '../src/app';
import { Transform, Sprite, Canvas } from '../src/component';
import type { SpriteData } from '../src/component';
@@ -23,10 +21,7 @@ import type { TextData } from '../src/ui/core/text';
import { textPlugin } from '../src/ui/TextPlugin';
import { INVALID_TEXTURE } from '../src/types';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
-import { loadWasmModule } from './helpers/loadWasm';
-
-const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');
-const HAS_WASM = existsSync(WASM_PATH);
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
describe.skipIf(!HAS_WASM)('Nested Text Entities (WASM integration)', () => {
let module: ESEngineModule;
diff --git a/sdk/tests/scrollview.test.ts b/sdk/tests/scrollview.test.ts
index af873e619..8816ddc6d 100644
--- a/sdk/tests/scrollview.test.ts
+++ b/sdk/tests/scrollview.test.ts
@@ -1,6 +1,4 @@
import { describe, it, expect, beforeAll } from 'vitest';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
import { App } from '../src/app';
import { Transform, Sprite, Canvas } from '../src/component';
import type { TransformData } from '../src/component';
@@ -17,10 +15,7 @@ import type { ScrollViewData } from '../src/ui/ScrollView';
import { UIInteraction } from '../src/ui/behavior/interactable';
import { Interactable } from '../src/ui/behavior/interactable';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
-import { loadWasmModule } from './helpers/loadWasm';
-
-const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');
-const HAS_WASM = existsSync(WASM_PATH);
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
describe.skipIf(!HAS_WASM)('ScrollView (WASM)', () => {
let module: ESEngineModule;
diff --git a/sdk/tests/text-multi-render.test.ts b/sdk/tests/text-multi-render.test.ts
index 986a816ef..4caa658bc 100644
--- a/sdk/tests/text-multi-render.test.ts
+++ b/sdk/tests/text-multi-render.test.ts
@@ -4,8 +4,6 @@
* in the editor, implying earlier textures are lost or overwritten.
*/
import { describe, it, expect, beforeAll } from 'vitest';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
import { App } from '../src/app';
import { Transform, Sprite, Canvas } from '../src/component';
import type { SpriteData } from '../src/component';
@@ -19,10 +17,7 @@ import { textPlugin } from '../src/ui/TextPlugin';
import { Text } from '../src/ui/core/text';
import { INVALID_TEXTURE } from '../src/types';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
-import { loadWasmModule } from './helpers/loadWasm';
-
-const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');
-const HAS_WASM = existsSync(WASM_PATH);
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
describe.skipIf(!HAS_WASM)('Multiple Text Entities (WASM)', () => {
let module: ESEngineModule;
diff --git a/sdk/tests/timeline-wasm-integration.test.ts b/sdk/tests/timeline-wasm-integration.test.ts
index 45c400a02..dfdf1c5e3 100644
--- a/sdk/tests/timeline-wasm-integration.test.ts
+++ b/sdk/tests/timeline-wasm-integration.test.ts
@@ -5,13 +5,11 @@
* Run `node build-tools/cli.js build -t web` first if missing.
*/
import { describe, it, expect, beforeAll } from 'vitest';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
import { World } from '../src/world';
import { Transform, Children, Name, getComponent } from '../src/component';
import { UIRect, type UIRectData } from '../src/ui/core/ui-rect';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
-import { loadWasmModule } from './helpers/loadWasm';
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
import {
WrapMode,
TrackType,
@@ -20,9 +18,6 @@ import {
} from '../src/timeline/TimelineTypes';
import { setNestedProperty } from '../src/timeline/TimelinePlugin';
-const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');
-const HAS_WASM = existsSync(WASM_PATH);
-
describe.skipIf(!HAS_WASM)('Timeline WASM Integration', () => {
let module: ESEngineModule;
diff --git a/sdk/tests/ui-components.test.ts b/sdk/tests/ui-components.test.ts
index bdcdbe6f8..995f53cb3 100644
--- a/sdk/tests/ui-components.test.ts
+++ b/sdk/tests/ui-components.test.ts
@@ -6,8 +6,6 @@
* Run `node build-tools/cli.js build -t web` first if missing.
*/
import { describe, it, expect, beforeAll } from 'vitest';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
import { App } from '../src/app';
import { World } from '../src/world';
import { Transform, Sprite, Canvas } from '../src/component';
@@ -21,10 +19,7 @@ import { UICameraInfo, type UICameraData } from '../src/ui/UICameraInfo';
import { uiLayoutPlugin } from '../src/ui/UILayoutPlugin';
import { uiRenderOrderPlugin } from '../src/ui/UIRenderOrderPlugin';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
-import { loadWasmModule } from './helpers/loadWasm';
-
-const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');
-const HAS_WASM = existsSync(WASM_PATH);
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
describe.skipIf(!HAS_WASM)('UI Components (WASM integration)', () => {
let module: ESEngineModule;
diff --git a/sdk/tests/ui-layout-integration.test.ts b/sdk/tests/ui-layout-integration.test.ts
index dcde04611..890e5aee4 100644
--- a/sdk/tests/ui-layout-integration.test.ts
+++ b/sdk/tests/ui-layout-integration.test.ts
@@ -5,8 +5,6 @@
* Run `node build-tools/cli.js build -t web` first if missing.
*/
import { describe, it, expect, beforeAll } from 'vitest';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
import { App } from '../src/app';
import { World } from '../src/world';
import { UIRect, type UIRectData } from '../src/ui/core/ui-rect';
@@ -16,10 +14,7 @@ import { uiLayoutPlugin } from '../src/ui/UILayoutPlugin';
import { uiRenderOrderPlugin } from '../src/ui/UIRenderOrderPlugin';
import { Transform, Sprite } from '../src/component';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
-import { loadWasmModule } from './helpers/loadWasm';
-
-const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');
-const HAS_WASM = existsSync(WASM_PATH);
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
describe.skipIf(!HAS_WASM)('UI Layout via App.tick() (WASM integration)', () => {
let module: ESEngineModule;
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 0d9842e8f..c43e3cb94 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -7,6 +7,8 @@
#ifdef ES_PLATFORM_WEB
#include <emscripten/bind.h>
+#include <cstddef>
+#include <string>
#include "../ecs/Registry.hpp"
#include "../math/Math.hpp"
#include "../core/UITypes.hpp"
@@ -1791,4 +1793,251 @@ EMSCRIPTEN_BINDINGS(esengine_reflection) {
emscripten::function("getBuiltinComponentNames", &esengineGetBuiltinComponentNames);
}
+// =============================================================================
+// ABI Layout Asserts -- the compiler is the offset authority
+// =============================================================================
+// EHT computes each pointer-field offset; the asserts below prove the real
+// compiler layout matches. A failure here means the TS pointer accessors would
+// read the wrong bytes -- fix the struct or regenerate EHT. DO NOT EDIT.
+
+static_assert(offsetof(esengine::ecs::BitmapText, color) == 0, "ABI offset drift: esengine::ecs::BitmapText.color (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::BitmapText, fontSize) == 16, "ABI offset drift: esengine::ecs::BitmapText.fontSize (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::BitmapText, align) == 20, "ABI offset drift: esengine::ecs::BitmapText.align (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::BitmapText, spacing) == 24, "ABI offset drift: esengine::ecs::BitmapText.spacing (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::BitmapText, layer) == 28, "ABI offset drift: esengine::ecs::BitmapText.layer (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::BitmapText, font) == 32, "ABI offset drift: esengine::ecs::BitmapText.font (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::BitmapText, enabled) == 36, "ABI offset drift: esengine::ecs::BitmapText.enabled (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::Camera, projectionType) == 0, "ABI offset drift: esengine::ecs::Camera.projectionType (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Camera, fov) == 4, "ABI offset drift: esengine::ecs::Camera.fov (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::Camera, orthoSize) == 8, "ABI offset drift: esengine::ecs::Camera.orthoSize (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::Camera, nearPlane) == 12, "ABI offset drift: esengine::ecs::Camera.nearPlane (EHT expected 12)");
+static_assert(offsetof(esengine::ecs::Camera, farPlane) == 16, "ABI offset drift: esengine::ecs::Camera.farPlane (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::Camera, aspectRatio) == 20, "ABI offset drift: esengine::ecs::Camera.aspectRatio (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::Camera, isActive) == 24, "ABI offset drift: esengine::ecs::Camera.isActive (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::Camera, priority) == 28, "ABI offset drift: esengine::ecs::Camera.priority (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::Camera, viewport) == 32, "ABI offset drift: esengine::ecs::Camera.viewport (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::Camera, clearFlags) == 48, "ABI offset drift: esengine::ecs::Camera.clearFlags (EHT expected 48)");
+static_assert(offsetof(esengine::ecs::Canvas, designResolution) == 0, "ABI offset drift: esengine::ecs::Canvas.designResolution (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Canvas, pixelsPerUnit) == 8, "ABI offset drift: esengine::ecs::Canvas.pixelsPerUnit (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::Canvas, scaleMode) == 12, "ABI offset drift: esengine::ecs::Canvas.scaleMode (EHT expected 12)");
+static_assert(offsetof(esengine::ecs::Canvas, matchWidthOrHeight) == 16, "ABI offset drift: esengine::ecs::Canvas.matchWidthOrHeight (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::Canvas, backgroundColor) == 20, "ABI offset drift: esengine::ecs::Canvas.backgroundColor (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::BoxCollider, halfExtents) == 0, "ABI offset drift: esengine::ecs::BoxCollider.halfExtents (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::BoxCollider, offset) == 8, "ABI offset drift: esengine::ecs::BoxCollider.offset (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::BoxCollider, density) == 16, "ABI offset drift: esengine::ecs::BoxCollider.density (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::BoxCollider, friction) == 20, "ABI offset drift: esengine::ecs::BoxCollider.friction (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::BoxCollider, restitution) == 24, "ABI offset drift: esengine::ecs::BoxCollider.restitution (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::BoxCollider, isSensor) == 28, "ABI offset drift: esengine::ecs::BoxCollider.isSensor (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::BoxCollider, enabled) == 29, "ABI offset drift: esengine::ecs::BoxCollider.enabled (EHT expected 29)");
+static_assert(offsetof(esengine::ecs::BoxCollider, categoryBits) == 32, "ABI offset drift: esengine::ecs::BoxCollider.categoryBits (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::BoxCollider, maskBits) == 36, "ABI offset drift: esengine::ecs::BoxCollider.maskBits (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::CircleCollider, radius) == 0, "ABI offset drift: esengine::ecs::CircleCollider.radius (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::CircleCollider, offset) == 4, "ABI offset drift: esengine::ecs::CircleCollider.offset (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::CircleCollider, density) == 12, "ABI offset drift: esengine::ecs::CircleCollider.density (EHT expected 12)");
+static_assert(offsetof(esengine::ecs::CircleCollider, friction) == 16, "ABI offset drift: esengine::ecs::CircleCollider.friction (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::CircleCollider, restitution) == 20, "ABI offset drift: esengine::ecs::CircleCollider.restitution (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::CircleCollider, isSensor) == 24, "ABI offset drift: esengine::ecs::CircleCollider.isSensor (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::CircleCollider, enabled) == 25, "ABI offset drift: esengine::ecs::CircleCollider.enabled (EHT expected 25)");
+static_assert(offsetof(esengine::ecs::CircleCollider, categoryBits) == 28, "ABI offset drift: esengine::ecs::CircleCollider.categoryBits (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::CircleCollider, maskBits) == 32, "ABI offset drift: esengine::ecs::CircleCollider.maskBits (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, radius) == 0, "ABI offset drift: esengine::ecs::CapsuleCollider.radius (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, halfHeight) == 4, "ABI offset drift: esengine::ecs::CapsuleCollider.halfHeight (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, offset) == 8, "ABI offset drift: esengine::ecs::CapsuleCollider.offset (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, density) == 16, "ABI offset drift: esengine::ecs::CapsuleCollider.density (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, friction) == 20, "ABI offset drift: esengine::ecs::CapsuleCollider.friction (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, restitution) == 24, "ABI offset drift: esengine::ecs::CapsuleCollider.restitution (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, isSensor) == 28, "ABI offset drift: esengine::ecs::CapsuleCollider.isSensor (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, enabled) == 29, "ABI offset drift: esengine::ecs::CapsuleCollider.enabled (EHT expected 29)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, categoryBits) == 32, "ABI offset drift: esengine::ecs::CapsuleCollider.categoryBits (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::CapsuleCollider, maskBits) == 36, "ABI offset drift: esengine::ecs::CapsuleCollider.maskBits (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::SegmentCollider, point1) == 0, "ABI offset drift: esengine::ecs::SegmentCollider.point1 (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::SegmentCollider, point2) == 8, "ABI offset drift: esengine::ecs::SegmentCollider.point2 (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::SegmentCollider, density) == 16, "ABI offset drift: esengine::ecs::SegmentCollider.density (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::SegmentCollider, friction) == 20, "ABI offset drift: esengine::ecs::SegmentCollider.friction (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::SegmentCollider, restitution) == 24, "ABI offset drift: esengine::ecs::SegmentCollider.restitution (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::SegmentCollider, isSensor) == 28, "ABI offset drift: esengine::ecs::SegmentCollider.isSensor (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::SegmentCollider, enabled) == 29, "ABI offset drift: esengine::ecs::SegmentCollider.enabled (EHT expected 29)");
+static_assert(offsetof(esengine::ecs::SegmentCollider, categoryBits) == 32, "ABI offset drift: esengine::ecs::SegmentCollider.categoryBits (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::SegmentCollider, maskBits) == 36, "ABI offset drift: esengine::ecs::SegmentCollider.maskBits (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::FlexContainer, direction) == 0, "ABI offset drift: esengine::ecs::FlexContainer.direction (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::FlexContainer, wrap) == 1, "ABI offset drift: esengine::ecs::FlexContainer.wrap (EHT expected 1)");
+static_assert(offsetof(esengine::ecs::FlexContainer, justifyContent) == 2, "ABI offset drift: esengine::ecs::FlexContainer.justifyContent (EHT expected 2)");
+static_assert(offsetof(esengine::ecs::FlexContainer, alignItems) == 3, "ABI offset drift: esengine::ecs::FlexContainer.alignItems (EHT expected 3)");
+static_assert(offsetof(esengine::ecs::FlexContainer, alignContent) == 4, "ABI offset drift: esengine::ecs::FlexContainer.alignContent (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::FlexContainer, gap) == 8, "ABI offset drift: esengine::ecs::FlexContainer.gap (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::FlexItem, flexGrow) == 0, "ABI offset drift: esengine::ecs::FlexItem.flexGrow (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::FlexItem, flexShrink) == 4, "ABI offset drift: esengine::ecs::FlexItem.flexShrink (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::FlexItem, flexBasis) == 8, "ABI offset drift: esengine::ecs::FlexItem.flexBasis (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::FlexItem, order) == 12, "ABI offset drift: esengine::ecs::FlexItem.order (EHT expected 12)");
+static_assert(offsetof(esengine::ecs::FlexItem, alignSelf) == 16, "ABI offset drift: esengine::ecs::FlexItem.alignSelf (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::FlexItem, minWidth) == 20, "ABI offset drift: esengine::ecs::FlexItem.minWidth (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::FlexItem, minHeight) == 24, "ABI offset drift: esengine::ecs::FlexItem.minHeight (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::FlexItem, maxWidth) == 28, "ABI offset drift: esengine::ecs::FlexItem.maxWidth (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::FlexItem, maxHeight) == 32, "ABI offset drift: esengine::ecs::FlexItem.maxHeight (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::FlexItem, widthPercent) == 36, "ABI offset drift: esengine::ecs::FlexItem.widthPercent (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::FlexItem, heightPercent) == 40, "ABI offset drift: esengine::ecs::FlexItem.heightPercent (EHT expected 40)");
+static_assert(offsetof(esengine::ecs::GridLayout, direction) == 0, "ABI offset drift: esengine::ecs::GridLayout.direction (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::GridLayout, crossAxisCount) == 4, "ABI offset drift: esengine::ecs::GridLayout.crossAxisCount (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::GridLayout, itemSize) == 8, "ABI offset drift: esengine::ecs::GridLayout.itemSize (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::GridLayout, spacing) == 16, "ABI offset drift: esengine::ecs::GridLayout.spacing (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::Interactable, enabled) == 0, "ABI offset drift: esengine::ecs::Interactable.enabled (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Interactable, blockRaycast) == 1, "ABI offset drift: esengine::ecs::Interactable.blockRaycast (EHT expected 1)");
+static_assert(offsetof(esengine::ecs::Interactable, raycastTarget) == 2, "ABI offset drift: esengine::ecs::Interactable.raycastTarget (EHT expected 2)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, rate) == 0, "ABI offset drift: esengine::ecs::ParticleEmitter.rate (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, burstCount) == 4, "ABI offset drift: esengine::ecs::ParticleEmitter.burstCount (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, burstInterval) == 8, "ABI offset drift: esengine::ecs::ParticleEmitter.burstInterval (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, duration) == 12, "ABI offset drift: esengine::ecs::ParticleEmitter.duration (EHT expected 12)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, looping) == 16, "ABI offset drift: esengine::ecs::ParticleEmitter.looping (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, playOnStart) == 17, "ABI offset drift: esengine::ecs::ParticleEmitter.playOnStart (EHT expected 17)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, maxParticles) == 20, "ABI offset drift: esengine::ecs::ParticleEmitter.maxParticles (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, lifetimeMin) == 24, "ABI offset drift: esengine::ecs::ParticleEmitter.lifetimeMin (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, lifetimeMax) == 28, "ABI offset drift: esengine::ecs::ParticleEmitter.lifetimeMax (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, shape) == 32, "ABI offset drift: esengine::ecs::ParticleEmitter.shape (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeRadius) == 36, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeRadius (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeSize) == 40, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeSize (EHT expected 40)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeAngle) == 48, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeAngle (EHT expected 48)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMin) == 52, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMin (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMax) == 56, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMax (EHT expected 56)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMin) == 60, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMin (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMax) == 64, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMax (EHT expected 64)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMin) == 68, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMin (EHT expected 68)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMax) == 72, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMax (EHT expected 72)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMin) == 76, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMin (EHT expected 76)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMax) == 80, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMax (EHT expected 80)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, sizeEasing) == 84, "ABI offset drift: esengine::ecs::ParticleEmitter.sizeEasing (EHT expected 84)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, startColor) == 88, "ABI offset drift: esengine::ecs::ParticleEmitter.startColor (EHT expected 88)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, endColor) == 104, "ABI offset drift: esengine::ecs::ParticleEmitter.endColor (EHT expected 104)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, colorEasing) == 120, "ABI offset drift: esengine::ecs::ParticleEmitter.colorEasing (EHT expected 120)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMin) == 124, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMin (EHT expected 124)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMax) == 128, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMax (EHT expected 128)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMin) == 132, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMin (EHT expected 132)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMax) == 136, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMax (EHT expected 136)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, gravity) == 140, "ABI offset drift: esengine::ecs::ParticleEmitter.gravity (EHT expected 140)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, damping) == 148, "ABI offset drift: esengine::ecs::ParticleEmitter.damping (EHT expected 148)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, texture) == 152, "ABI offset drift: esengine::ecs::ParticleEmitter.texture (EHT expected 152)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteColumns) == 156, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteColumns (EHT expected 156)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteRows) == 160, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteRows (EHT expected 160)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteFPS) == 164, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteFPS (EHT expected 164)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteLoop) == 168, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteLoop (EHT expected 168)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, blendMode) == 172, "ABI offset drift: esengine::ecs::ParticleEmitter.blendMode (EHT expected 172)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, layer) == 176, "ABI offset drift: esengine::ecs::ParticleEmitter.layer (EHT expected 176)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, material) == 180, "ABI offset drift: esengine::ecs::ParticleEmitter.material (EHT expected 180)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, simulationSpace) == 184, "ABI offset drift: esengine::ecs::ParticleEmitter.simulationSpace (EHT expected 184)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 188, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 188)");
+static_assert(offsetof(esengine::ecs::RigidBody, bodyType) == 0, "ABI offset drift: esengine::ecs::RigidBody.bodyType (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::RigidBody, gravityScale) == 4, "ABI offset drift: esengine::ecs::RigidBody.gravityScale (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::RigidBody, linearDamping) == 8, "ABI offset drift: esengine::ecs::RigidBody.linearDamping (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::RigidBody, angularDamping) == 12, "ABI offset drift: esengine::ecs::RigidBody.angularDamping (EHT expected 12)");
+static_assert(offsetof(esengine::ecs::RigidBody, fixedRotation) == 16, "ABI offset drift: esengine::ecs::RigidBody.fixedRotation (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::RigidBody, bullet) == 17, "ABI offset drift: esengine::ecs::RigidBody.bullet (EHT expected 17)");
+static_assert(offsetof(esengine::ecs::RigidBody, enabled) == 18, "ABI offset drift: esengine::ecs::RigidBody.enabled (EHT expected 18)");
+static_assert(offsetof(esengine::ecs::ShapeRenderer, shapeType) == 0, "ABI offset drift: esengine::ecs::ShapeRenderer.shapeType (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::ShapeRenderer, color) == 4, "ABI offset drift: esengine::ecs::ShapeRenderer.color (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::ShapeRenderer, size) == 20, "ABI offset drift: esengine::ecs::ShapeRenderer.size (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::ShapeRenderer, cornerRadius) == 28, "ABI offset drift: esengine::ecs::ShapeRenderer.cornerRadius (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::ShapeRenderer, layer) == 32, "ABI offset drift: esengine::ecs::ShapeRenderer.layer (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::ShapeRenderer, enabled) == 36, "ABI offset drift: esengine::ecs::ShapeRenderer.enabled (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, timeScale) == 0, "ABI offset drift: esengine::ecs::SpineAnimation.timeScale (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, loop) == 4, "ABI offset drift: esengine::ecs::SpineAnimation.loop (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, playing) == 5, "ABI offset drift: esengine::ecs::SpineAnimation.playing (EHT expected 5)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, flipX) == 6, "ABI offset drift: esengine::ecs::SpineAnimation.flipX (EHT expected 6)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, flipY) == 7, "ABI offset drift: esengine::ecs::SpineAnimation.flipY (EHT expected 7)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, color) == 8, "ABI offset drift: esengine::ecs::SpineAnimation.color (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, layer) == 24, "ABI offset drift: esengine::ecs::SpineAnimation.layer (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, skeletonScale) == 28, "ABI offset drift: esengine::ecs::SpineAnimation.skeletonScale (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, material) == 32, "ABI offset drift: esengine::ecs::SpineAnimation.material (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::SpineAnimation, enabled) == 36, "ABI offset drift: esengine::ecs::SpineAnimation.enabled (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::Sprite, texture) == 0, "ABI offset drift: esengine::ecs::Sprite.texture (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Sprite, color) == 4, "ABI offset drift: esengine::ecs::Sprite.color (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::Sprite, size) == 20, "ABI offset drift: esengine::ecs::Sprite.size (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::Sprite, pivot) == 28, "ABI offset drift: esengine::ecs::Sprite.pivot (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::Sprite, uvOffset) == 36, "ABI offset drift: esengine::ecs::Sprite.uvOffset (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::Sprite, uvScale) == 44, "ABI offset drift: esengine::ecs::Sprite.uvScale (EHT expected 44)");
+static_assert(offsetof(esengine::ecs::Sprite, layer) == 52, "ABI offset drift: esengine::ecs::Sprite.layer (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::Sprite, flipX) == 56, "ABI offset drift: esengine::ecs::Sprite.flipX (EHT expected 56)");
+static_assert(offsetof(esengine::ecs::Sprite, flipY) == 57, "ABI offset drift: esengine::ecs::Sprite.flipY (EHT expected 57)");
+static_assert(offsetof(esengine::ecs::Sprite, tileSize) == 60, "ABI offset drift: esengine::ecs::Sprite.tileSize (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::Sprite, tileSpacing) == 68, "ABI offset drift: esengine::ecs::Sprite.tileSpacing (EHT expected 68)");
+static_assert(offsetof(esengine::ecs::Sprite, material) == 76, "ABI offset drift: esengine::ecs::Sprite.material (EHT expected 76)");
+static_assert(offsetof(esengine::ecs::Sprite, enabled) == 80, "ABI offset drift: esengine::ecs::Sprite.enabled (EHT expected 80)");
+static_assert(offsetof(esengine::ecs::StateVisuals, transitionFlags) == 0, "ABI offset drift: esengine::ecs::StateVisuals.transitionFlags (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::StateVisuals, fadeDuration) == 4, "ABI offset drift: esengine::ecs::StateVisuals.fadeDuration (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot0Color) == 8, "ABI offset drift: esengine::ecs::StateVisuals.slot0Color (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot0Sprite) == 24, "ABI offset drift: esengine::ecs::StateVisuals.slot0Sprite (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot0Scale) == 28, "ABI offset drift: esengine::ecs::StateVisuals.slot0Scale (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot1Color) == 32, "ABI offset drift: esengine::ecs::StateVisuals.slot1Color (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot1Sprite) == 48, "ABI offset drift: esengine::ecs::StateVisuals.slot1Sprite (EHT expected 48)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot1Scale) == 52, "ABI offset drift: esengine::ecs::StateVisuals.slot1Scale (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot2Color) == 56, "ABI offset drift: esengine::ecs::StateVisuals.slot2Color (EHT expected 56)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot2Sprite) == 72, "ABI offset drift: esengine::ecs::StateVisuals.slot2Sprite (EHT expected 72)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot2Scale) == 76, "ABI offset drift: esengine::ecs::StateVisuals.slot2Scale (EHT expected 76)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot3Color) == 80, "ABI offset drift: esengine::ecs::StateVisuals.slot3Color (EHT expected 80)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot3Sprite) == 96, "ABI offset drift: esengine::ecs::StateVisuals.slot3Sprite (EHT expected 96)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot3Scale) == 100, "ABI offset drift: esengine::ecs::StateVisuals.slot3Scale (EHT expected 100)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot4Color) == 104, "ABI offset drift: esengine::ecs::StateVisuals.slot4Color (EHT expected 104)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot4Sprite) == 120, "ABI offset drift: esengine::ecs::StateVisuals.slot4Sprite (EHT expected 120)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot4Scale) == 124, "ABI offset drift: esengine::ecs::StateVisuals.slot4Scale (EHT expected 124)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot5Color) == 128, "ABI offset drift: esengine::ecs::StateVisuals.slot5Color (EHT expected 128)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot5Sprite) == 144, "ABI offset drift: esengine::ecs::StateVisuals.slot5Sprite (EHT expected 144)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot5Scale) == 148, "ABI offset drift: esengine::ecs::StateVisuals.slot5Scale (EHT expected 148)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot6Color) == 152, "ABI offset drift: esengine::ecs::StateVisuals.slot6Color (EHT expected 152)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot6Sprite) == 168, "ABI offset drift: esengine::ecs::StateVisuals.slot6Sprite (EHT expected 168)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot6Scale) == 172, "ABI offset drift: esengine::ecs::StateVisuals.slot6Scale (EHT expected 172)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot7Color) == 176, "ABI offset drift: esengine::ecs::StateVisuals.slot7Color (EHT expected 176)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot7Sprite) == 192, "ABI offset drift: esengine::ecs::StateVisuals.slot7Sprite (EHT expected 192)");
+static_assert(offsetof(esengine::ecs::StateVisuals, slot7Scale) == 196, "ABI offset drift: esengine::ecs::StateVisuals.slot7Scale (EHT expected 196)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, cellSize) == 0, "ABI offset drift: esengine::ecs::TilemapLayer.cellSize (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, originOffset) == 8, "ABI offset drift: esengine::ecs::TilemapLayer.originOffset (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, tileset) == 16, "ABI offset drift: esengine::ecs::TilemapLayer.tileset (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, tilesetColumns) == 20, "ABI offset drift: esengine::ecs::TilemapLayer.tilesetColumns (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, tilesetRows) == 24, "ABI offset drift: esengine::ecs::TilemapLayer.tilesetRows (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, renderLayer) == 28, "ABI offset drift: esengine::ecs::TilemapLayer.renderLayer (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, tintColor) == 32, "ABI offset drift: esengine::ecs::TilemapLayer.tintColor (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, opacity) == 48, "ABI offset drift: esengine::ecs::TilemapLayer.opacity (EHT expected 48)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, parallaxFactor) == 52, "ABI offset drift: esengine::ecs::TilemapLayer.parallaxFactor (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::TilemapLayer, visible) == 60, "ABI offset drift: esengine::ecs::TilemapLayer.visible (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::Transform, position) == 0, "ABI offset drift: esengine::ecs::Transform.position (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Transform, rotation) == 12, "ABI offset drift: esengine::ecs::Transform.rotation (EHT expected 12)");
+static_assert(offsetof(esengine::ecs::Transform, scale) == 28, "ABI offset drift: esengine::ecs::Transform.scale (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::Transform, worldPosition) == 40, "ABI offset drift: esengine::ecs::Transform.worldPosition (EHT expected 40)");
+static_assert(offsetof(esengine::ecs::Transform, worldRotation) == 52, "ABI offset drift: esengine::ecs::Transform.worldRotation (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::Transform, worldScale) == 68, "ABI offset drift: esengine::ecs::Transform.worldScale (EHT expected 68)");
+static_assert(offsetof(esengine::ecs::UIInteraction, hovered) == 0, "ABI offset drift: esengine::ecs::UIInteraction.hovered (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::UIInteraction, pressed) == 1, "ABI offset drift: esengine::ecs::UIInteraction.pressed (EHT expected 1)");
+static_assert(offsetof(esengine::ecs::UIInteraction, justPressed) == 2, "ABI offset drift: esengine::ecs::UIInteraction.justPressed (EHT expected 2)");
+static_assert(offsetof(esengine::ecs::UIInteraction, justReleased) == 3, "ABI offset drift: esengine::ecs::UIInteraction.justReleased (EHT expected 3)");
+static_assert(offsetof(esengine::ecs::UIMask, enabled) == 0, "ABI offset drift: esengine::ecs::UIMask.enabled (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::UIMask, mode) == 1, "ABI offset drift: esengine::ecs::UIMask.mode (EHT expected 1)");
+static_assert(offsetof(esengine::ecs::UIRect, anchorMin) == 0, "ABI offset drift: esengine::ecs::UIRect.anchorMin (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::UIRect, anchorMax) == 8, "ABI offset drift: esengine::ecs::UIRect.anchorMax (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::UIRect, offsetMin) == 16, "ABI offset drift: esengine::ecs::UIRect.offsetMin (EHT expected 16)");
+static_assert(offsetof(esengine::ecs::UIRect, offsetMax) == 24, "ABI offset drift: esengine::ecs::UIRect.offsetMax (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::UIRect, size) == 32, "ABI offset drift: esengine::ecs::UIRect.size (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::UIRect, pivot) == 40, "ABI offset drift: esengine::ecs::UIRect.pivot (EHT expected 40)");
+static_assert(offsetof(esengine::ecs::UIRenderer, visualType) == 0, "ABI offset drift: esengine::ecs::UIRenderer.visualType (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::UIRenderer, texture) == 4, "ABI offset drift: esengine::ecs::UIRenderer.texture (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::UIRenderer, color) == 8, "ABI offset drift: esengine::ecs::UIRenderer.color (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::UIRenderer, uvOffset) == 24, "ABI offset drift: esengine::ecs::UIRenderer.uvOffset (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::UIRenderer, uvScale) == 32, "ABI offset drift: esengine::ecs::UIRenderer.uvScale (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::UIRenderer, sliceBorder) == 40, "ABI offset drift: esengine::ecs::UIRenderer.sliceBorder (EHT expected 40)");
+static_assert(offsetof(esengine::ecs::UIRenderer, material) == 56, "ABI offset drift: esengine::ecs::UIRenderer.material (EHT expected 56)");
+static_assert(offsetof(esengine::ecs::UIRenderer, enabled) == 60, "ABI offset drift: esengine::ecs::UIRenderer.enabled (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::Velocity, linear) == 0, "ABI offset drift: esengine::ecs::Velocity.linear (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drift: esengine::ecs::Velocity.angular (EHT expected 12)");
+
+
+// =============================================================================
+// ABI Hash -- runtime handshake against the SDK bundle
+// =============================================================================
+
+static const char* kEsAbiLayoutHash = "f5d18743d00de675";
+
+std::string esengineGetAbiLayoutHash() {
+ return std::string(kEsAbiLayoutHash);
+}
+
+EMSCRIPTEN_BINDINGS(esengine_abi) {
+ emscripten::function("getAbiLayoutHash", &esengineGetAbiLayoutHash);
+}
+
#endif // ES_PLATFORM_WEB
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 55902edcb..6af3ede14 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -245,26 +245,11 @@ resource::ResourceManager* getResourceManager() {
// Pointer-based Component Access
// =============================================================================
-static_assert(offsetof(ecs::Transform, position) == 0);
-static_assert(offsetof(ecs::Transform, rotation) == 12);
-static_assert(offsetof(ecs::Transform, scale) == 28);
-static_assert(offsetof(ecs::Transform, worldPosition) == 40);
-static_assert(offsetof(ecs::Transform, worldRotation) == 52);
-static_assert(offsetof(ecs::Transform, worldScale) == 68);
-
-static_assert(offsetof(ecs::Sprite, texture) == 0);
-static_assert(offsetof(ecs::Sprite, color) == 4);
-static_assert(offsetof(ecs::Sprite, size) == 20);
-static_assert(offsetof(ecs::Sprite, pivot) == 28);
-static_assert(offsetof(ecs::Sprite, uvOffset) == 36);
-static_assert(offsetof(ecs::Sprite, uvScale) == 44);
-static_assert(offsetof(ecs::Sprite, layer) == 52);
-static_assert(offsetof(ecs::Sprite, flipX) == 56);
-static_assert(offsetof(ecs::Sprite, flipY) == 57);
-static_assert(offsetof(ecs::Sprite, tileSize) == 60);
-static_assert(offsetof(ecs::Sprite, tileSpacing) == 68);
-static_assert(offsetof(ecs::Sprite, material) == 76);
-static_assert(offsetof(ecs::Sprite, enabled) == 80);
+// NOTE: Per-field component layout offsets are asserted for ALL components in
+// WebBindings.generated.cpp (generated by EHT's PtrLayoutGenerator), which is
+// the single source of truth for the pointer ABI. Do not hand-maintain
+// static_assert(offsetof(...)) here — they drifted and only covered 8 of N
+// components. See docs/REARCHITECTURE.md (root cause 1).
int getTransformPtr(ecs::Registry& r, u32 e) {
auto* t = r.tryGet<ecs::Transform>(Entity::fromRaw(e));
@@ -279,92 +264,36 @@ int getSpritePtr(ecs::Registry& r, u32 e) {
return static_cast<int>(reinterpret_cast<uintptr_t>(s));
}
-// Velocity: 2x vec3 = 24 bytes pure float
-static_assert(offsetof(ecs::Velocity, linear) == 0);
-static_assert(offsetof(ecs::Velocity, angular) == 12);
-
int getVelocityPtr(ecs::Registry& r, u32 e) {
auto* v = r.tryGet<ecs::Velocity>(Entity::fromRaw(e));
if (!v) return 0;
return static_cast<int>(reinterpret_cast<uintptr_t>(v));
}
-// Camera: enum u8 + padding + floats + bool + i32
-static_assert(offsetof(ecs::Camera, projectionType) == 0);
-static_assert(offsetof(ecs::Camera, fov) == 4);
-static_assert(offsetof(ecs::Camera, orthoSize) == 8);
-static_assert(offsetof(ecs::Camera, nearPlane) == 12);
-static_assert(offsetof(ecs::Camera, farPlane) == 16);
-static_assert(offsetof(ecs::Camera, aspectRatio) == 20);
-static_assert(offsetof(ecs::Camera, isActive) == 24);
-static_assert(offsetof(ecs::Camera, priority) == 28);
-static_assert(offsetof(ecs::Camera, viewport) == 32);
-static_assert(offsetof(ecs::Camera, clearFlags) == 48);
-
int getCameraPtr(ecs::Registry& r, u32 e) {
auto* c = r.tryGet<ecs::Camera>(Entity::fromRaw(e));
if (!c) return 0;
return static_cast<int>(reinterpret_cast<uintptr_t>(c));
}
-// UIRect: 6x vec2 (48 bytes) + computed fields
-static_assert(offsetof(ecs::UIRect, anchorMin) == 0);
-static_assert(offsetof(ecs::UIRect, anchorMax) == 8);
-static_assert(offsetof(ecs::UIRect, offsetMin) == 16);
-static_assert(offsetof(ecs::UIRect, offsetMax) == 24);
-static_assert(offsetof(ecs::UIRect, size) == 32);
-static_assert(offsetof(ecs::UIRect, pivot) == 40);
-static_assert(offsetof(ecs::UIRect, computed_size_) == 48);
-
int getUIRectPtr(ecs::Registry& r, u32 e) {
auto* rect = r.tryGet<ecs::UIRect>(Entity::fromRaw(e));
if (!rect) return 0;
return static_cast<int>(reinterpret_cast<uintptr_t>(rect));
}
-// RigidBody: enum u8 + padding + floats + bools
-static_assert(offsetof(ecs::RigidBody, bodyType) == 0);
-static_assert(offsetof(ecs::RigidBody, gravityScale) == 4);
-static_assert(offsetof(ecs::RigidBody, linearDamping) == 8);
-static_assert(offsetof(ecs::RigidBody, angularDamping) == 12);
-static_assert(offsetof(ecs::RigidBody, fixedRotation) == 16);
-static_assert(offsetof(ecs::RigidBody, bullet) == 17);
-static_assert(offsetof(ecs::RigidBody, enabled) == 18);
-
int getRigidBodyPtr(ecs::Registry& r, u32 e) {
auto* rb = r.tryGet<ecs::RigidBody>(Entity::fromRaw(e));
if (!rb) return 0;
return static_cast<int>(reinterpret_cast<uintptr_t>(rb));
}
-// BoxCollider: vec2 + vec2 + floats + bools + u32s
-static_assert(offsetof(ecs::BoxCollider, halfExtents) == 0);
-static_assert(offsetof(ecs::BoxCollider, offset) == 8);
-static_assert(offsetof(ecs::BoxCollider, density) == 16);
-static_assert(offsetof(ecs::BoxCollider, friction) == 20);
-static_assert(offsetof(ecs::BoxCollider, restitution) == 24);
-static_assert(offsetof(ecs::BoxCollider, isSensor) == 28);
-static_assert(offsetof(ecs::BoxCollider, enabled) == 29);
-static_assert(offsetof(ecs::BoxCollider, categoryBits) == 32);
-static_assert(offsetof(ecs::BoxCollider, maskBits) == 36);
-
int getBoxColliderPtr(ecs::Registry& r, u32 e) {
auto* bc = r.tryGet<ecs::BoxCollider>(Entity::fromRaw(e));
if (!bc) return 0;
return static_cast<int>(reinterpret_cast<uintptr_t>(bc));
}
-// CircleCollider: f32 + vec2 + floats + bools + u32s
-static_assert(offsetof(ecs::CircleCollider, radius) == 0);
-static_assert(offsetof(ecs::CircleCollider, offset) == 4);
-static_assert(offsetof(ecs::CircleCollider, density) == 12);
-static_assert(offsetof(ecs::CircleCollider, friction) == 16);
-static_assert(offsetof(ecs::CircleCollider, restitution) == 20);
-static_assert(offsetof(ecs::CircleCollider, isSensor) == 24);
-static_assert(offsetof(ecs::CircleCollider, enabled) == 25);
-static_assert(offsetof(ecs::CircleCollider, categoryBits) == 28);
-static_assert(offsetof(ecs::CircleCollider, maskBits) == 32);
-
int getCircleColliderPtr(ecs::Registry& r, u32 e) {
auto* cc = r.tryGet<ecs::CircleCollider>(Entity::fromRaw(e));
if (!cc) return 0;
diff --git a/tools/eht/__main__.py b/tools/eht/__main__.py
index 656bc2116..005d7c70c 100644
--- a/tools/eht/__main__.py
+++ b/tools/eht/__main__.py
@@ -5,6 +5,7 @@ import argparse
from pathlib import Path
from .parser import CppParser
+from .abi import compute_abi_hash
from .generators import (
EmbindGenerator, TypeScriptGenerator, MetadataGenerator,
AnimTargetGenerator, PtrLayoutGenerator, EditorAPIGenerator,
@@ -44,6 +45,15 @@ def main() -> int:
print("Warning: No components found!")
return 1
+ # ── Boundary ABI: single source of truth ──
+ # Compute pointer layouts and the ABI hash first; both the C++ bindings and
+ # the TS metadata embed the same hash so connect() can verify they match.
+ ptr_gen = PtrLayoutGenerator(cpp_parser.components, cpp_parser.enums)
+ abi_hash = compute_abi_hash(
+ cpp_parser.components, cpp_parser.enums, ptr_gen.layouts
+ )
+ print(f"ABI layout hash: {abi_hash}")
+
# ── C++ Editor API ──
editor_api_path = args.output / 'EditorAPI.generated.cpp'
print(f"Generating: {editor_api_path}")
@@ -54,31 +64,40 @@ def main() -> int:
args.output.mkdir(parents=True, exist_ok=True)
embind_path = args.output / 'WebBindings.generated.cpp'
print(f"Generating: {embind_path}")
- embind_gen = EmbindGenerator(cpp_parser.components, cpp_parser.enums)
+ embind_gen = EmbindGenerator(
+ cpp_parser.components, cpp_parser.enums,
+ layout_asserts=ptr_gen.generate_layout_asserts(),
+ abi_hash=abi_hash,
+ )
embind_path.write_text(embind_gen.generate(), encoding='utf-8')
+ # Resolve the TS source directory robustly. Callers historically pass either
+ # the package root (`sdk`) or the source dir (`sdk/src`); detect which by
+ # looking for the `ecs/` subfolder. Previously a `sdk/src` argument made every
+ # `/ 'src' /` path resolve to a non-existent `sdk/src/src`, silently skipping
+ # component.generated.ts / ptrLayouts / ptrAccessors. Generation must never
+ # silently no-op a file.
+ ts_root = args.ts_output
+ if (ts_root / 'ecs').is_dir():
+ ts_src_dir = ts_root
+ else:
+ ts_src_dir = ts_root / 'src'
+ ts_src_dir.mkdir(parents=True, exist_ok=True)
+
+ def write_ts(rel: str, content: str) -> None:
+ out = ts_src_dir / rel
+ out.parent.mkdir(parents=True, exist_ok=True)
+ print(f"Generating: {out}")
+ out.write_text(content, encoding='utf-8')
+
# ── TypeScript Definitions ──
ts_gen = TypeScriptGenerator(cpp_parser.components, cpp_parser.enums)
ts_content = ts_gen.generate()
-
- args.ts_output.mkdir(parents=True, exist_ok=True)
- ts_path = args.ts_output / 'wasm.generated.ts'
- print(f"Generating: {ts_path}")
- ts_path.write_text(ts_content, encoding='utf-8')
-
- ts_src_path = args.ts_output / 'src' / 'wasm.generated.ts'
- if ts_src_path.parent.exists():
- print(f"Generating: {ts_src_path}")
- ts_src_path.write_text(ts_content, encoding='utf-8')
+ write_ts('wasm.generated.ts', ts_content)
# ── Component Metadata ──
- meta_gen = MetadataGenerator(cpp_parser.components, cpp_parser.enums)
- meta_content = meta_gen.generate()
-
- meta_path = args.ts_output / 'src' / 'component.generated.ts'
- if meta_path.parent.exists():
- print(f"Generating: {meta_path}")
- meta_path.write_text(meta_content, encoding='utf-8')
+ meta_gen = MetadataGenerator(cpp_parser.components, cpp_parser.enums, abi_hash=abi_hash)
+ write_ts('component.generated.ts', meta_gen.generate())
# ── Animation Targets ──
anim_gen = AnimTargetGenerator(cpp_parser.components, cpp_parser.enums)
@@ -87,22 +106,11 @@ def main() -> int:
print(f"Generating: {anim_hpp_path}")
anim_hpp_path.write_text(anim_gen.generate_hpp(), encoding='utf-8')
- anim_ts_path = args.ts_output / 'src' / 'timeline' / 'animTargets.generated.ts'
- if anim_ts_path.parent.exists():
- print(f"Generating: {anim_ts_path}")
- anim_ts_path.write_text(anim_gen.generate_ts(), encoding='utf-8')
+ write_ts('timeline/animTargets.generated.ts', anim_gen.generate_ts())
# ── Pointer Layouts & Accessors ──
- ptr_gen = PtrLayoutGenerator(cpp_parser.components, cpp_parser.enums)
- ptr_path = args.ts_output / 'src' / 'ptrLayouts.generated.ts'
- if ptr_path.parent.exists():
- print(f"Generating: {ptr_path}")
- ptr_path.write_text(ptr_gen.generate(), encoding='utf-8')
-
- accessor_path = args.ts_output / 'src' / 'ecs' / 'ptrAccessors.generated.ts'
- if accessor_path.parent.exists():
- print(f"Generating: {accessor_path}")
- accessor_path.write_text(ptr_gen.generate_accessors(), encoding='utf-8')
+ write_ts('ptrLayouts.generated.ts', ptr_gen.generate())
+ write_ts('ecs/ptrAccessors.generated.ts', ptr_gen.generate_accessors())
print("[OK] Done!")
return 0
diff --git a/tools/eht/abi.py b/tools/eht/abi.py
new file mode 100644
index 000000000..ef4cc4115
--- /dev/null
+++ b/tools/eht/abi.py
@@ -0,0 +1,52 @@
+"""ABI layout hashing — single source of truth for the C++/TS boundary contract.
+
+The hash is computed ONCE here (in Python) from the parsed component schema and
+the computed pointer layouts, then emitted verbatim into BOTH the C++ binding
+(`getAbiLayoutHash()`) and the TS bundle (`ABI_LAYOUT_HASH`). At `connect()` the
+SDK compares the two: a mismatch means the loaded WASM binary and the shipped SDK
+were generated from different schemas, so the pointer offsets the SDK uses would
+read the wrong bytes. Refusing to run is the only safe response.
+
+This is the runtime half of the keystone. The compile-time half is the generated
+`static_assert(offsetof(...))` block, which proves EHT's computed offsets equal
+the real compiler layout. Together: TS offset == EHT offset == compiler offset,
+and the loaded WASM's schema == the SDK's schema.
+"""
+
+import hashlib
+from typing import Dict, List
+
+from .data import Component, Enum
+
+
+def _canonical(components: List[Component], enums: List[Enum],
+ layouts: List[Dict]) -> str:
+ """Build an order-independent canonical description of the boundary ABI.
+
+ Components/enums/layouts are sorted by name so the hash is stable regardless
+ of filesystem glob order (which is not guaranteed across machines).
+ """
+ parts: List[str] = []
+
+ for enum in sorted(enums, key=lambda e: e.name):
+ vals = ','.join(enum.values)
+ parts.append(f'ENUM {enum.name}:{enum.underlying_type}={vals}')
+
+ for comp in sorted(components, key=lambda c: c.name):
+ fields = ';'.join(f'{p.name}:{p.cpp_type}' for p in comp.properties)
+ parts.append(f'COMP {comp.name}|{fields}')
+
+ for layout in sorted(layouts, key=lambda l: l['name']):
+ flds = ';'.join(
+ f"{f['name']}:{f['type']}@{f['offset']}" for f in layout['fields']
+ )
+ parts.append(f"PTR {layout['name']}|{flds}")
+
+ return '\n'.join(parts)
+
+
+def compute_abi_hash(components: List[Component], enums: List[Enum],
+ layouts: List[Dict]) -> str:
+ """Return a stable 16-hex-char digest of the boundary ABI."""
+ canonical = _canonical(components, enums, layouts)
+ return hashlib.sha1(canonical.encode('utf-8')).hexdigest()[:16]
diff --git a/tools/eht/generators/embind.py b/tools/eht/generators/embind.py
index 712246d42..a6bf57c1a 100644
--- a/tools/eht/generators/embind.py
+++ b/tools/eht/generators/embind.py
@@ -6,10 +6,16 @@ from ..type_system import TypeSystem
class EmbindGenerator:
- def __init__(self, components: List[Component], enums: List[Enum]):
+ def __init__(self, components: List[Component], enums: List[Enum],
+ layout_asserts: str = '', abi_hash: str = ''):
self.components = components
self.enums = enums
self.types = TypeSystem(enums)
+ # C++ static_assert(offsetof) block from PtrLayoutGenerator, and the
+ # single-source-of-truth ABI hash. Both injected so the boundary
+ # contract lives in one generated TU. See tools/eht/abi.py.
+ self.layout_asserts = layout_asserts
+ self.abi_hash = abi_hash
def generate(self) -> str:
lines = self._gen_header()
@@ -19,11 +25,40 @@ class EmbindGenerator:
lines.extend(self._gen_components())
lines.extend(self._gen_registry())
lines.extend(self._gen_reflection())
+ lines.extend(self._gen_layout_asserts())
+ lines.extend(self._gen_abi_hash())
lines.append('')
lines.append('#endif // ES_PLATFORM_WEB')
lines.append('')
return '\n'.join(lines)
+ def _gen_layout_asserts(self) -> List[str]:
+ if not self.layout_asserts:
+ return []
+ return ['', self.layout_asserts]
+
+ def _gen_abi_hash(self) -> List[str]:
+ """Emit getAbiLayoutHash() — the runtime half of the boundary contract.
+
+ Returns the same digest EHT baked into the TS bundle as ABI_LAYOUT_HASH.
+ The SDK compares them at connect() and refuses to run on mismatch."""
+ return [
+ '',
+ '// =============================================================================',
+ '// ABI Hash -- runtime handshake against the SDK bundle',
+ '// =============================================================================',
+ '',
+ f'static const char* kEsAbiLayoutHash = "{self.abi_hash}";',
+ '',
+ 'std::string esengineGetAbiLayoutHash() {',
+ ' return std::string(kEsAbiLayoutHash);',
+ '}',
+ '',
+ 'EMSCRIPTEN_BINDINGS(esengine_abi) {',
+ ' emscripten::function("getAbiLayoutHash", &esengineGetAbiLayoutHash);',
+ '}',
+ ]
+
def _gen_header(self) -> List[str]:
return [
'/**',
@@ -35,6 +70,8 @@ class EmbindGenerator:
'#ifdef ES_PLATFORM_WEB',
'',
'#include <emscripten/bind.h>',
+ '#include <cstddef>',
+ '#include <string>',
'#include "../ecs/Registry.hpp"',
'#include "../math/Math.hpp"',
'#include "../core/UITypes.hpp"',
diff --git a/tools/eht/generators/metadata.py b/tools/eht/generators/metadata.py
index c42b1d9d6..1840d0abf 100644
--- a/tools/eht/generators/metadata.py
+++ b/tools/eht/generators/metadata.py
@@ -11,11 +11,13 @@ from ..field_utils import (
class MetadataGenerator:
"""Generates component.generated.ts with defaults and metadata."""
- def __init__(self, components: List[Component], enums: List[Enum]):
+ def __init__(self, components: List[Component], enums: List[Enum],
+ abi_hash: str = ''):
self.components = components
self.enums = enums
self.types = TypeSystem(enums)
self._enum_values = build_enum_value_map(enums)
+ self.abi_hash = abi_hash
def _get_asset_fields(self, comp: Component) -> List[Dict[str, str]]:
fields = []
@@ -74,6 +76,14 @@ class MetadataGenerator:
'',
"import type { AssetFieldType } from './scene';",
'',
+ '/**',
+ ' * Single-source-of-truth hash of the C++/TS boundary ABI (component',
+ ' * schema + pointer layouts). The WASM module exposes the same digest via',
+ ' * getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to',
+ ' * run on mismatch, because mismatched offsets read the wrong heap bytes.',
+ ' */',
+ f"export const ABI_LAYOUT_HASH = '{self.abi_hash}';",
+ '',
'export interface AssetFieldMeta {',
' field: string;',
' type: AssetFieldType;',
diff --git a/tools/eht/generators/ptr_layout.py b/tools/eht/generators/ptr_layout.py
index 1f3de6ee8..33250bcf6 100644
--- a/tools/eht/generators/ptr_layout.py
+++ b/tools/eht/generators/ptr_layout.py
@@ -99,12 +99,43 @@ class PtrLayoutGenerator:
offset += size
if fields:
+ full = f'{comp.namespace}::{comp.name}' if comp.namespace else comp.name
self.layouts.append({
'name': comp.name,
+ 'cpp_full': full,
'ptrFn': f'get{comp.name}Ptr',
'fields': fields,
})
+ def generate_layout_asserts(self) -> str:
+ """Emit a C++ static_assert(offsetof) for every pointer-accessed field.
+
+ This makes the *compiler* the authority on struct layout: EHT computes
+ each offset, and these asserts prove the real compiler layout agrees.
+ Any divergence (a reordered/retyped field, a packing surprise EHT's
+ model doesn't capture) becomes a BUILD ERROR rather than a silent
+ cross-boundary heap-corruption at runtime. Injected into the web-only
+ WebBindings.generated.cpp, which already includes every component header.
+ """
+ lines = [
+ '// =============================================================================',
+ '// ABI Layout Asserts -- the compiler is the offset authority',
+ '// =============================================================================',
+ '// EHT computes each pointer-field offset; the asserts below prove the real',
+ '// compiler layout matches. A failure here means the TS pointer accessors would',
+ '// read the wrong bytes -- fix the struct or regenerate EHT. DO NOT EDIT.',
+ '',
+ ]
+ for layout in self.layouts:
+ full = layout['cpp_full']
+ for f in layout['fields']:
+ msg = f'ABI offset drift: {full}.{f["name"]} (EHT expected {f["offset"]})'
+ lines.append(
+ f'static_assert(offsetof({full}, {f["name"]}) == {f["offset"]}, "{msg}");'
+ )
+ lines.append('')
+ return '\n'.join(lines)
+
def generate(self) -> str:
lines = [
'/**',