A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file binding-surface.test.ts
* @brief Handshake guard for the hand-written WASM function-binding surface.
*
* The EHT-generated boundary (components/enums/ptr accessors/ABI hash) is
* single-sourced and handshake-guarded, but the FUNCTION surface of the main
* module is still maintained by hand on both sides: `emscripten::function`
* registrations in bindings/WebSDKEntry.cpp + bindings/TilemapBindings.cpp,
* mirrored by the `ESEngineModule` interface (wasm.ts) and `TilemapModule`
* (tilemap/tilemapAPI.ts). Nothing cross-checked them until now: a binding
* added on one side and forgotten on the other only fails at runtime — an
* undefined call in whatever code path first touches it.
*
* This test IS the handshake: it parses the real registration sites and the
* real TS interfaces and asserts the two surfaces match, in both directions,
* plus the embind class surfaces (ResourceManager, EstellaContext). Same
* pattern as cpp-contract.test.ts, extended from constants to functions.
*
* Side modules are hand-mirrored too and guarded the same way: physics and
* spine export via `EMSCRIPTEN_KEEPALIVE` C functions (JS-visible as `_name`,
* spine additionally reached through the `cw('name', ...)` cwrap table),
* basis via the CMake `EXPORTED_FUNCTIONS` list (the link already verifies
* that list against the C++ definitions — the unverified edge is TS↔CMake).
*
* Deliberately NOT asserted (possible future tightening): optionality
* coherence — a `#ifdef`-gated C++ registration being declared required in
* TS. All shipping variants currently compile every gated feature, and TS
* optionality also serves older-wasm compatibility, so existence is the
* contract we pin here.
*/
import { describe, it, expect } from 'vitest';
import { readFileSync, existsSync } from 'node:fs';
import { resolve } from 'node:path';
import {
DISPOSITIONS, TEST_PROBE_BINDINGS, PROBE_GUARD, PROBE_HEADER,
type TestProbeBinding,
} from '../../tools/bindingDispositions.mjs';
const CPP = resolve(__dirname, '../../src/esengine');
const SDK = resolve(__dirname, '../src');
const read = (abs: string): string => {
// Fail loud (not skip) if a source moved — a silently-disabled guard is
// worse than no guard.
if (!existsSync(abs)) throw new Error(`binding-surface source missing: ${abs}`);
return readFileSync(abs, 'utf8');
};
/** Strip C/C++/TS comments, preserving newlines so offsets stay line-stable. */
function stripComments(src: string): string {
return src
.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
.replace(/\/\/[^\n]*/g, '');
}
// =============================================================================
// C++ side: emscripten registration parsing
// =============================================================================
/**
* Registration names inside `#ifdef <macro>` … `#endif` blocks. What keeps a
* probe out of a release build is the guard, so a census row claiming one is
* checked against the preprocessor rather than against its own say-so.
*/
function parseGuardedRegistrations(cppSource: string, macro: string): Set<string> {
const src = stripComments(cppSource);
const out = new Set<string>();
const re = new RegExp(`#if(?:def)?\\s+${macro}\\b([\\s\\S]*?)#endif`, 'g');
for (let m = re.exec(src); m; m = re.exec(src)) {
for (const name of parseFunctionRegistrations(m[1])) out.add(name);
}
return out;
}
/** All `emscripten::function("name", ...)` registration names in a file. */
function parseFunctionRegistrations(cppSource: string): Set<string> {
const out = new Set<string>();
const re = /emscripten::function\(\s*"(\w+)"/g;
const src = stripComments(cppSource);
for (let m = re.exec(src); m; m = re.exec(src)) out.add(m[1]);
return out;
}
/**
* Method registrations of one `emscripten::class_<T>("Name")` chain: every
* `.function("name", &target)` between the class_ head and the chain's
* terminating `;` (the chain itself contains no semicolons), mapped to the
* target's last identifier.
*/
function parseClassRegistration(cppSource: string, className: string): Map<string, string> {
const src = stripComments(cppSource);
const head = src.indexOf(`("${className}")`);
if (head < 0) throw new Error(`embind class_ registration '${className}' not found`);
const end = src.indexOf(';', head);
const chain = src.slice(head, end);
const out = new Map<string, string>();
const re = /\.function\(\s*"(\w+)"\s*,\s*[^&]*&([\w:]+)/g;
for (let m = re.exec(chain); m; m = re.exec(chain)) {
const parts = m[2].split('::');
out.set(m[1], parts[parts.length - 1]);
}
return out;
}
/**
* All `EMSCRIPTEN_KEEPALIVE` C exports in a file: the identifier right before
* the parameter list that follows each annotation, with parameter count.
*/
function parseKeepaliveSigs(cppSource: string): Map<string, number> {
const src = stripComments(cppSource);
const out = new Map<string, number>();
const re = /EMSCRIPTEN_KEEPALIVE\b/g;
for (let m = re.exec(src); m; m = re.exec(src)) {
// Not the portability fallback (`#define EMSCRIPTEN_KEEPALIVE` for a native
// build, where the attribute has no meaning) — that is not an export, and
// reading past it would attribute the next function in the file to it.
const lineStart = src.lastIndexOf('\n', m.index) + 1;
if (src.slice(lineStart, m.index).trimStart().startsWith('#define')) continue;
const paren = src.indexOf('(', m.index);
if (paren < 0) continue;
const tokens = src.slice(m.index + m[0].length, paren).match(/\w+/g);
if (!tokens?.length) throw new Error(`EMSCRIPTEN_KEEPALIVE with no function name at offset ${m.index}`);
out.set(tokens[tokens.length - 1], countParams(src, paren));
}
return out;
}
function parseKeepaliveExports(cppSource: string): Set<string> {
return new Set(parseKeepaliveSigs(cppSource).keys());
}
/** Count the top-level parameters of a parenthesized list starting at `open`. */
function countParams(src: string, open: number): number {
let depth = 0;
let commas = 0;
let sawToken = false;
for (let i = open; i < src.length; i++) {
const ch = src[i];
if (ch === '(' || ch === '{' || ch === '[') depth++;
else if (ch === ')' || ch === '}' || ch === ']') {
depth--;
if (depth === 0) return sawToken ? commas + 1 : 0;
} else if (ch === ',' && depth === 1) commas++;
else if (depth === 1 && /\S/.test(ch)) sawToken = true;
}
throw new Error(`unbalanced parameter list at offset ${open}`);
}
/**
* Every plausible arity of `symbol` in the pooled C++ sources: each
* `symbol(...)` occurrence (declaration, definition, or call — argument
* counts equal parameter counts, these bindings have no default arguments)
* contributes its top-level comma count.
*/
function cppArities(pooled: string, symbol: string): Set<number> {
const out = new Set<number>();
const re = new RegExp(`\\b${symbol}\\s*\\(`, 'g');
for (let m = re.exec(pooled); m; m = re.exec(pooled)) {
out.add(countParams(pooled, m.index + m[0].length - 1));
}
return out;
}
interface Registration {
name: string;
/** last identifier of the bound `&esengine::...` target; null for lambdas */
symbol: string | null;
/** lambda registrations carry their arity directly */
lambdaArity: number | null;
}
/** `emscripten::function("name", &esengine::sym | +[](...){...})` entries. */
function parseRegistrationTargets(cppSource: string): Registration[] {
const src = stripComments(cppSource);
const out: Registration[] = [];
const re = /emscripten::function\(\s*"(\w+)"\s*,\s*(&[\w:]+|\+?\[\]\s*\()/g;
for (let m = re.exec(src); m; m = re.exec(src)) {
if (m[2].startsWith('&')) {
const parts = m[2].slice(1).split('::');
out.push({ name: m[1], symbol: parts[parts.length - 1], lambdaArity: null });
} else {
out.push({ name: m[1], symbol: null, lambdaArity: countParams(src, m.index + m[0].length - 1) });
}
}
return out;
}
/**
* The `-sEXPORTED_FUNCTIONS=['_a','_b',...]` list of the link target whose
* line contains `marker` (how modules without KEEPALIVE annotations export).
*/
function parseExportedFunctions(cmakeSource: string, marker: string): Set<string> {
const line = cmakeSource.split('\n').find((l) => l.includes('EXPORTED_FUNCTIONS') && l.includes(marker));
if (!line) throw new Error(`no EXPORTED_FUNCTIONS line containing '${marker}' in cmake source`);
const out = new Set<string>();
const re = /'(\w+)'/g;
for (let m = re.exec(line); m; m = re.exec(line)) out.add(m[1]);
return out;
}
// =============================================================================
// TS side: interface member parsing
// =============================================================================
/**
* Call-signature members (`name(...)` / `name?(...)`) declared at the top
* level of `interface <name> { ... }`, with their parameter counts. Property
* members (`HEAPU8: ...`, `Registry: new () => ...`) and members of nested
* object types (`GL: {...}`, inline return-type literals) are excluded: a
* member must sit at brace depth 0 of the body and start after `;`/`{`/`}`.
*/
function parseInterfaceMethodSigs(tsSource: string, interfaceName: string): Map<string, number> {
const src = stripComments(tsSource);
const head = new RegExp(`interface\\s+${interfaceName}\\s*\\{`).exec(src);
if (!head) throw new Error(`TS interface '${interfaceName}' not found`);
const start = head.index + head[0].length;
let depth = 1;
let end = -1;
for (let i = start; i < src.length; i++) {
const ch = src[i];
if (ch === '{') depth++;
else if (ch === '}' && --depth === 0) { end = i; break; }
}
if (end < 0) throw new Error(`TS interface '${interfaceName}': unterminated body`);
const body = src.slice(start, end);
const out = new Map<string, number>();
const memberRe = /(\w+)\s*\??\(/g;
for (let m = memberRe.exec(body); m; m = memberRe.exec(body)) {
let braces = 0;
for (let i = 0; i < m.index; i++) {
if (body[i] === '{') braces++;
else if (body[i] === '}') braces--;
}
if (braces !== 0) continue;
let j = m.index - 1;
while (j >= 0 && /\s/.test(body[j])) j--;
if (j >= 0 && !';{}'.includes(body[j])) continue;
out.set(m[1], countParams(body, m.index + m[0].length - 1));
}
return out;
}
function parseInterfaceMethods(tsSource: string, interfaceName: string): Set<string> {
return new Set(parseInterfaceMethodSigs(tsSource, interfaceName).keys());
}
/**
* `cw('name', ret, [argTypes])` / `cwrap(...)` call-site literals in a TS
* file, mapped to their argTypes count (the arity the wrapper calls with).
*/
function parseCwrapSigs(tsSource: string): Map<string, number> {
const src = stripComments(tsSource);
const out = new Map<string, number>();
const re = /\bcw(?:rap)?\(\s*['"](\w+)['"]\s*,\s*(?:null|'[^']*'|"[^"]*")\s*,\s*\[([^\]]*)\]/g;
for (let m = re.exec(src); m; m = re.exec(src)) {
out.set(m[1], m[2].trim() ? m[2].split(',').length : 0);
}
return out;
}
function parseCwrapNames(tsSource: string): Set<string> {
return new Set(parseCwrapSigs(tsSource).keys());
}
const sorted = (s: Iterable<string>): string[] => [...s].sort();
const missingFrom = (names: Iterable<string>, universe: Set<string>): string[] =>
sorted([...names].filter((n) => !universe.has(n)));
// =============================================================================
// The two surfaces
// =============================================================================
// Hand-written registration sites (the mirrors under guard) + the generated
// ones (their TS twins are generated too, but their names must count when
// checking that a TS declaration is not a phantom).
const webSdkEntry = read(resolve(CPP, 'bindings/WebSDKEntry.cpp'));
const tilemapBindings = read(resolve(CPP, 'bindings/TilemapBindings.cpp'));
const generatedCpp = [
read(resolve(CPP, 'bindings/WebBindings.generated.cpp')),
read(resolve(CPP, 'bindings/EditorAPI.generated.cpp')),
];
const handRegistered = new Set([
...parseFunctionRegistrations(webSdkEntry),
...parseFunctionRegistrations(tilemapBindings),
]);
const allRegistered = new Set([
...handRegistered,
...generatedCpp.flatMap((src) => [...parseFunctionRegistrations(src)]),
]);
const wasmTs = read(resolve(SDK, 'wasm.ts'));
const tilemapApiTs = read(resolve(SDK, 'tilemap/tilemapAPI.ts'));
const moduleDeclared = parseInterfaceMethods(wasmTs, 'ESEngineModule');
const tilemapDeclared = parseInterfaceMethods(tilemapApiTs, 'TilemapModule');
const allDeclared = new Set([...moduleDeclared, ...tilemapDeclared]);
// Emscripten-runtime exports declared for ergonomics; not embind registrations.
const RUNTIME_EXPORTS = new Set(['_malloc', '_free']);
/** The census: which registrations are deliberately not production. */
const probeDeclared = new Set<string>(TEST_PROBE_BINDINGS.map((b: TestProbeBinding) => b.id));
const probeGuarded = parseGuardedRegistrations(webSdkEntry, PROBE_GUARD);
describe('WASM binding surface: module functions (hand-written mirror handshake)', () => {
it('every TS-declared ESEngineModule function is a real registration (no phantom decls)', () => {
const phantom = missingFrom(
[...moduleDeclared].filter((n) => !RUNTIME_EXPORTS.has(n)),
allRegistered,
);
expect(phantom, `declared in wasm.ts but registered nowhere in bindings/*.cpp: ${phantom.join(', ')}`)
.toEqual([]);
});
it('every TS-declared TilemapModule function is a real registration (no phantom decls)', () => {
const phantom = missingFrom(
[...tilemapDeclared].filter((n) => !RUNTIME_EXPORTS.has(n)),
allRegistered,
);
expect(phantom, `declared in tilemapAPI.ts but registered nowhere in bindings/*.cpp: ${phantom.join(', ')}`)
.toEqual([]);
});
it('every hand-registered binding is declared in the TS surface (no unmirrored bindings)', () => {
// Minus the ones a census declares are not production. `production` is the
// default, so an unlisted binding is still held to the strict rule.
const production = [...handRegistered].filter((n) => !probeDeclared.has(n));
const unmirrored = missingFrom(production, allDeclared);
expect(unmirrored, `registered in WebSDKEntry/TilemapBindings but declared in no TS interface`
+ ` (and not declared a test-probe in tools/bindingDispositions.mjs): ${unmirrored.join(', ')}`)
.toEqual([]);
});
it('a test-probe binding stays OUT of the production TS surface', () => {
const leaked = [...probeDeclared].filter((n) => allDeclared.has(n));
expect(leaked, `declared test-probe in tools/bindingDispositions.mjs but present in the`
+ ` shipping TS surface, which is a release ABI: ${leaked.join(', ')}`)
.toEqual([]);
});
it('a test-probe binding is registered behind the probe guard', () => {
const unguarded = [...probeDeclared].filter((n) => !probeGuarded.has(n));
expect(unguarded, `declared test-probe but registered outside #ifdef ${PROBE_GUARD},`
+ ` so a release build would export it: ${unguarded.join(', ')}`)
.toEqual([]);
});
it('a test-probe binding is declared in the probe-only header', () => {
const probeHeader = read(resolve(CPP, PROBE_HEADER));
const misplaced = [...probeDeclared].filter((n) => !new RegExp(`\\b${n}\\s*\\(`).test(probeHeader));
expect(misplaced, `declared test-probe but not declared in ${PROBE_HEADER} — the header`
+ ` tool reads the shipping ones and does not read #ifdef: ${misplaced.join(', ')}`)
.toEqual([]);
});
it('every declared test-probe still exists (no stale disposition)', () => {
const gone = [...probeDeclared].filter((n) => !handRegistered.has(n));
expect(gone, `declared test-probe in tools/bindingDispositions.mjs but registered nowhere;`
+ ` a disposition outliving its binding reads as an answered question: ${gone.join(', ')}`)
.toEqual([]);
});
it('every disposition class the census uses is one this contract defines', () => {
const classes = Object.keys(DISPOSITIONS);
expect(classes, 'the census must define production and test-probe')
.toEqual(expect.arrayContaining(['production', 'test-probe']));
const unexplained = TEST_PROBE_BINDINGS.filter((b: TestProbeBinding) => !b.why);
expect(unexplained.map((b: TestProbeBinding) => b.id), 'a test-probe row owes a `why`')
.toEqual([]);
});
});
// =============================================================================
// Side modules (C exports)
// =============================================================================
// Emscripten runtime members declared on the side-module interfaces.
const SIDE_RUNTIME = new Set(['_malloc', '_free', 'cwrap', 'UTF8ToString', 'stringToNewUTF8']);
function expectMirrored(label: string, tsDeclared: Set<string>, cppExports: Set<string>): void {
const exported = new Set([...cppExports].map((n) => `_${n}`));
const declared = new Set([...tsDeclared].filter((n) => !SIDE_RUNTIME.has(n)));
const phantom = missingFrom(declared, exported);
const unmirrored = missingFrom(exported, declared);
expect(phantom, `${label}: declared in TS but exported nowhere: ${phantom.join(', ')}`).toEqual([]);
expect(unmirrored, `${label}: exported but not reachable from TS: ${unmirrored.join(', ')}`).toEqual([]);
}
describe('WASM binding surface: side modules (C exports)', () => {
// The four TUs the SDK's own interface mirrors. PhysicsReadback.cpp is
// deliberately absent: its `*Bytes` helpers exist so a NATIVE wrapper can copy
// exactly what a getter published, and no SDK caller ever names them.
const PHYSICS_TUS = ['PhysicsModuleEntry.cpp', 'PhysicsShapes.cpp',
'PhysicsJoints.cpp', 'PhysicsQueries.cpp'];
it('PhysicsWasmModule mirrors the physics module exports exactly', () => {
const cpp = new Set(
PHYSICS_TUS.flatMap((f) => [...parseKeepaliveExports(read(resolve(CPP, 'bindings/modules/physics', f)))]),
);
const ts = parseInterfaceMethods(read(resolve(SDK, 'physics/PhysicsModuleLoader.ts')), 'PhysicsWasmModule');
expectMirrored('physics', ts, cpp);
});
// The native half of the same surface. A device reaches physics through QuickJS
// wrappers EHT generates from PhysicsBindings.hpp, so a declaration missing there
// is an entry point the device silently does not answer — and one that exists
// there but nowhere else is a wrapper that will not link.
it('PhysicsBindings.hpp declares exactly what the module exports', () => {
const header = stripComments(read(resolve(CPP, 'bindings/modules/physics/PhysicsBindings.hpp')));
const declared = new Set([...header.matchAll(/\b(physics_\w+)\s*\(/g)].map((m) => m[1]!));
const exported = new Set([...PHYSICS_TUS, 'PhysicsReadback.cpp']
.flatMap((f) => [...parseKeepaliveExports(read(resolve(CPP, 'bindings/modules/physics', f)))]));
const undeclared = [...exported].filter((n) => !declared.has(n)).sort();
const phantom = [...declared].filter((n) => !exported.has(n)).sort();
expect(undeclared, `exported but not declared in PhysicsBindings.hpp (no native wrapper): ${undeclared.join(', ')}`)
.toEqual([]);
expect(phantom, `declared in PhysicsBindings.hpp but defined nowhere: ${phantom.join(', ')}`)
.toEqual([]);
});
// The device build reads this list to generate its QuickJS wrappers, and it is
// the only consumer — so a header that moves takes ~17 minutes of Dawn build to
// report itself, at release time, on the one workflow that compiles for a phone.
// v0.36.0's release failed exactly here, four headers behind a reorganisation.
it('every binding header the native build lists is where it says it is', async () => {
const { NATIVE_BINDING_HEADERS } = await import('../../build-tools/tasks/native.js');
const missing = (NATIVE_BINDING_HEADERS as string[])
.filter((h) => !existsSync(resolve(CPP, 'bindings', h)));
expect(missing, `listed in build-tools/tasks/native.js but absent: ${missing.join(', ')}`)
.toEqual([]);
});
// Exported for the NATIVE side only, so no SDK caller names them: which spine
// runtime a host linked (the web names the artifact instead — spine38 / 41 / 42)
// and how much the event buffer published, which a native wrapper needs to copy
// the readback into the caller's heap. See SpineBindings.hpp.
const SPINE_NATIVE_ONLY = new Set(['spine_runtimeVersion', 'spine_eventBufferBytes']);
it('SpineWasmModule + its cwrap table mirror the spine module exports exactly', () => {
const cpp = new Set(
[...parseKeepaliveExports(read(resolve(CPP, 'bindings/modules/spine/SpineModuleEntry.cpp')))]
.filter((n) => !SPINE_NATIVE_ONLY.has(n)),
);
const loaderTs = read(resolve(SDK, 'spine/SpineModuleLoader.ts'));
const declared = new Set([
...parseInterfaceMethods(loaderTs, 'SpineWasmModule'),
...[...parseCwrapNames(loaderTs)].map((n) => `_${n}`),
]);
expectMirrored('spine', declared, cpp);
});
// The native half, as for physics: a device reaches spine through wrappers EHT
// generates from SpineBindings.hpp, so a declaration missing there is an entry
// point the device does not answer, and one with no definition is a wrapper that
// will not link.
it('SpineBindings.hpp declares exactly what the module exports', () => {
const header = stripComments(read(resolve(CPP, 'bindings/modules/spine/SpineBindings.hpp')));
const declared = new Set([...header.matchAll(/\b(spine_\w+)\s*\(/g)].map((m) => m[1]!));
const exported = new Set(
[...parseKeepaliveExports(read(resolve(CPP, 'bindings/modules/spine/SpineModuleEntry.cpp')))]
.filter((n) => n.startsWith('spine_')),
);
const undeclared = [...exported].filter((n) => !declared.has(n)).sort();
const phantom = [...declared].filter((n) => !exported.has(n)).sort();
expect(undeclared, `exported but not declared in SpineBindings.hpp: ${undeclared.join(', ')}`)
.toEqual([]);
expect(phantom, `declared in SpineBindings.hpp but defined nowhere: ${phantom.join(', ')}`)
.toEqual([]);
});
// Read off the WRAPPED interface rather than the cwrap call sites, because this
// loader binds through `w('loadSkeleton', …)` and lets the helper add the `db_`
// — there is no `cwrap('db_loadSkeleton')` literal to find. The interface is a
// faithful stand-in for the table: tsc rejects a member with no `w(…)` behind it
// and a `w(…)` with no member, so the two cannot drift.
it('DragonBonesWrappedAPI mirrors the module exports exactly', () => {
const cpp = parseKeepaliveExports(read(resolve(CPP, 'bindings/modules/dragonbones/DragonBonesModuleEntry.cpp')));
const loaderTs = read(resolve(SDK, 'dragonbones/DragonBonesModuleLoader.ts'));
const declared = new Set(
[...parseInterfaceMethods(loaderTs, 'DragonBonesWrappedAPI')].map((n) => `_db_${n}`),
);
expectMirrored('dragonbones', declared, cpp);
});
// The native half, as for physics and spine. This one has already been the bug
// it guards: the module was linked into the Android host and unreachable from
// it, because the ABI lived only in the .cpp and the generator had nothing to
// read. A declaration missing here is an entry point a device does not answer.
it('DragonBonesBindings.hpp declares exactly what the module exports', () => {
const header = stripComments(read(resolve(CPP, 'bindings/modules/dragonbones/DragonBonesBindings.hpp')));
const declared = new Set([...header.matchAll(/\b(db_\w+)\s*\(/g)].map((m) => m[1]!));
const exported = new Set(
[...parseKeepaliveExports(read(resolve(CPP, 'bindings/modules/dragonbones/DragonBonesModuleEntry.cpp')))]
.filter((n) => n.startsWith('db_')),
);
const undeclared = [...exported].filter((n) => !declared.has(n)).sort();
const phantom = [...declared].filter((n) => !exported.has(n)).sort();
expect(undeclared, `exported but not declared in DragonBonesBindings.hpp: ${undeclared.join(', ')}`)
.toEqual([]);
expect(phantom, `declared in DragonBonesBindings.hpp but defined nowhere: ${phantom.join(', ')}`)
.toEqual([]);
});
it('BasisWasmModule mirrors the basis EXPORTED_FUNCTIONS list exactly', () => {
const cmake = read(resolve(CPP, '../../cmake/Emscripten.cmake'));
const exported = parseExportedFunctions(cmake, 'es_basis');
exported.delete('_malloc');
exported.delete('_free');
const ts = new Set(
[...parseInterfaceMethods(read(resolve(SDK, 'asset/basisTranscoder.ts')), 'BasisWasmModule')]
.filter((n) => !SIDE_RUNTIME.has(n)),
);
const phantom = missingFrom(ts, exported);
const unmirrored = missingFrom(exported, ts);
expect(phantom, `basis: declared in TS but not in EXPORTED_FUNCTIONS: ${phantom.join(', ')}`).toEqual([]);
expect(unmirrored, `basis: exported but not declared in TS: ${unmirrored.join(', ')}`).toEqual([]);
});
});
describe('WASM binding surface: embind class methods', () => {
it('CppResourceManager mirrors class_<ResourceManager> exactly', () => {
const cpp = parseClassRegistration(webSdkEntry, 'ResourceManager');
const ts = parseInterfaceMethods(wasmTs, 'CppResourceManager');
// Native (embedded-Dawn) byte-upload methods: no wasm heap to marshal into,
// so they take the RGBA bytes directly and have NO embind counterpart on the
// web ResourceManager. Optional + native-only by construction — exempt from
// the web mirror the way embind's implicit `delete` is below.
ts.delete('createTextureFromBytes');
ts.delete('createTextureArrayFromBytes');
ts.delete('updateTextureSubregionFromBytes');
ts.delete('createTextureFromKTX2'); // KTX2 transcode lives in the native host, not embind
expect(sorted(ts)).toEqual(sorted(cpp.keys()));
});
it('CppEngineContext mirrors class_<EstellaContext> exactly (embind-implicit delete aside)', () => {
const cpp = parseClassRegistration(webSdkEntry, 'EstellaContext');
const ts = parseInterfaceMethods(wasmTs, 'CppEngineContext');
ts.delete('delete'); // added by embind on every class instance, never registered
expect(sorted(ts)).toEqual(sorted(cpp.keys()));
});
});
// =============================================================================
// Signature arity handshake
// =============================================================================
// Existence drift is pinned above; this pins the parameter COUNT of every
// mirrored function. TS types are erased at runtime, so an arity-drifted
// declaration compiles every SDK call site happily and only explodes when the
// path is exercised — this catches it at test time instead. Types stay
// hand-written (the TS mirror is deliberately richer than what generation
// from C++ could produce); embind/cwrap check value kinds at call time.
const pooledModuleCpp = [
'bindings/WebSDKEntry.cpp',
'bindings/TilemapBindings.cpp',
'bindings/RendererBindings.hpp',
'bindings/RendererBindings.cpp',
'bindings/UIBindings.hpp',
'bindings/UIBindings.cpp',
'bindings/ResourceManagerBindings.hpp',
'bindings/ResourceManagerBindings.cpp',
'bindings/GeometryBindings.hpp',
'bindings/GeometryBindings.cpp',
'bindings/ImmediateDrawBindings.hpp',
'bindings/ImmediateDrawBindings.cpp',
'bindings/PostProcessBindings.hpp',
'bindings/PostProcessBindings.cpp',
'bindings/TilemapBindings.hpp',
'bindings/AnimationBindings.hpp',
'bindings/AnimationBindings.cpp',
'bindings/MaterialBindings.hpp',
'bindings/MaterialBindings.cpp',
].map((f) => stripComments(read(resolve(CPP, f)))).join('\n');
function expectArities(label: string, tsSigs: Map<string, number>, cppSigs: Map<string, number>): void {
const problems: string[] = [];
for (const [name, tsArity] of tsSigs) {
if (SIDE_RUNTIME.has(name)) continue;
const cppArity = cppSigs.get(name.replace(/^_/, ''));
if (cppArity == null) continue; // existence guard covers missing exports
if (cppArity !== tsArity) problems.push(`${name}: TS declares ${tsArity} params, C++ has ${cppArity}`);
}
expect(problems, `${label}:\n${problems.join('\n')}`).toEqual([]);
}
describe('WASM binding surface: signature arity handshake', () => {
it('parser self-check: known signatures parse to their real arities', () => {
// Guards the guard: if a parser regresses into returning empty/zero
// sets, every comparison above it would pass vacuously.
expect(parseInterfaceMethodSigs(wasmTs, 'ESEngineModule').get('draw_line')).toBe(9);
expect(parseInterfaceMethodSigs(wasmTs, 'ESEngineModule').get('renderer_end')).toBe(0);
expect(cppArities(pooledModuleCpp, 'draw_line')).toContain(9);
expect(parseKeepaliveSigs(read(resolve(CPP, 'bindings/modules/physics/PhysicsModuleEntry.cpp'))).get('physics_step')).toBe(1);
expect(parseCwrapSigs(read(resolve(SDK, 'spine/SpineModuleLoader.ts'))).get('spine_setSkin')).toBe(2);
});
it('every hand-registered module function has a matching TS parameter count', () => {
const regs = [
...parseRegistrationTargets(webSdkEntry),
...parseRegistrationTargets(tilemapBindings),
];
const declarations = [
['wasm.ts', parseInterfaceMethodSigs(wasmTs, 'ESEngineModule')],
['tilemapAPI.ts', parseInterfaceMethodSigs(tilemapApiTs, 'TilemapModule')],
] as const;
const problems: string[] = [];
for (const reg of regs) {
const candidates = reg.lambdaArity != null
? new Set([reg.lambdaArity])
: cppArities(pooledModuleCpp, reg.symbol!);
if (candidates.size === 0) {
problems.push(`${reg.name}: no C++ prototype found for '${reg.symbol}' — extend the source pool`);
continue;
}
for (const [file, sigs] of declarations) {
const tsArity = sigs.get(reg.name);
if (tsArity == null) continue; // existence guard covers
if (!candidates.has(tsArity)) {
problems.push(`${reg.name} (${file}): TS declares ${tsArity} params, C++ has ${sorted(
[...candidates].map(String),
).join('/')}`);
}
}
}
expect(problems, problems.join('\n')).toEqual([]);
});
it('CppResourceManager parameter counts match (embind drops the instance param)', () => {
const chain = parseClassRegistration(webSdkEntry, 'ResourceManager');
const ts = parseInterfaceMethodSigs(wasmTs, 'CppResourceManager');
const problems: string[] = [];
for (const [name, sym] of chain) {
const tsArity = ts.get(name);
if (tsArity == null) continue;
const candidates = cppArities(pooledModuleCpp, sym);
if (candidates.size === 0) {
problems.push(`${name}: no C++ prototype found for '${sym}'`);
} else if (![...candidates].some((c) => c - 1 === tsArity)) {
problems.push(`${name}: TS declares ${tsArity} params, C++ has ${sorted(
[...candidates].map((c) => String(c - 1)),
).join('/')} after the instance param`);
}
}
expect(problems, problems.join('\n')).toEqual([]);
});
it('physics: parameter counts match', () => {
const cpp = new Map(
['PhysicsModuleEntry.cpp', 'PhysicsShapes.cpp', 'PhysicsJoints.cpp', 'PhysicsQueries.cpp']
.flatMap((f) => [...parseKeepaliveSigs(read(resolve(CPP, 'bindings/modules/physics', f)))]),
);
const ts = parseInterfaceMethodSigs(read(resolve(SDK, 'physics/PhysicsModuleLoader.ts')), 'PhysicsWasmModule');
expectArities('physics', ts, cpp);
});
it('spine: raw members and the cwrap table both match', () => {
const loaderTs = read(resolve(SDK, 'spine/SpineModuleLoader.ts'));
const cpp = parseKeepaliveSigs(read(resolve(CPP, 'bindings/modules/spine/SpineModuleEntry.cpp')));
expectArities('spine raw members', parseInterfaceMethodSigs(loaderTs, 'SpineWasmModule'), cpp);
expectArities('spine cwrap table', parseCwrapSigs(loaderTs), cpp);
});
it('basis: parameter counts match', () => {
const src = stripComments(read(resolve(CPP, 'bindings/modules/basis/BasisModuleEntry.cpp')));
const ts = parseInterfaceMethodSigs(read(resolve(SDK, 'asset/basisTranscoder.ts')), 'BasisWasmModule');
const problems: string[] = [];
for (const [name, tsArity] of ts) {
if (SIDE_RUNTIME.has(name)) continue;
const candidates = cppArities(src, name.replace(/^_/, ''));
if (candidates.size === 0) problems.push(`${name}: no C++ definition found`);
else if (!candidates.has(tsArity)) {
problems.push(`${name}: TS declares ${tsArity} params, C++ has ${sorted([...candidates].map(String)).join('/')}`);
}
}
expect(problems, problems.join('\n')).toEqual([]);
});
});