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
test(editor): the authoring surface gets a suite, and one plumbing to run it on
yhh861eff472533
diff --git a/desktop/package.json b/desktop/package.jsonindex 6e3c43899..731b152a8 100644--- a/desktop/package.json+++ b/desktop/package.json@@ -58,6 +58,7 @@"verify:render:material:preview": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-tint.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-tint.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_PREVIEW=\"{\\\"w\\\":64,\\\"h\\\":64,\\\"rgb\\\":[255,0,0],\\\"tol\\\":45}\" electron scripts/headless-verify.mjs","verify:render:ysort": "vite build && ESTELLA_VERIFY_YSORT=1 ESTELLA_VERIFY_SCENE=/scenes/ysort.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ysort.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":30},{\\\"x\\\":0.5,\\\"y\\\":0.25,\\\"rgb\\\":[255,0,0],\\\"tol\\\":30},{\\\"x\\\":0.5,\\\"y\\\":0.75,\\\"rgb\\\":[0,255,0],\\\"tol\\\":30}]\" electron scripts/headless-verify.mjs","verify:render:ysort:off": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ysort.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ysort.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":30}]\" electron scripts/headless-verify.mjs",+ "verify:editor": "vite build && node scripts/editor-checks/run.mjs","verify:smoke": "vite build && electron scripts/headless-smoke.mjs","verify:render:tilemap:hex": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-hex.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-hex.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=6 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.40,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.40,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.50,\\\"y\\\":0.55,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.70,\\\"y\\\":0.55,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs","verify:render:mesh2d": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mesh2d.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mesh2d.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=4 ESTELLA_VERIFY_EXPECT='[{\"x\":0.30,\"y\":0.556,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.30,\"y\":0.40,\"rgb\":[255,0,0],\"tol\":40}]' electron scripts/headless-verify.mjs",diff --git a/desktop/scripts/editor-25d-check.mjs b/desktop/scripts/editor-25d-check.mjsdeleted file mode 100644index 2ed4045bf..000000000--- a/desktop/scripts/editor-25d-check.mjs+++ /dev/null@@ -1,278 +0,0 @@-// SPDX-License-Identifier: Apache-2.0-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-/**- * @file editor-25d-check.mjs — the 2.5D AUTHORING surface, driven for real.- *- * The engine half of 2.5D is covered by verify:render:depth (a paired pixel check- * that painter's order cannot pass). What no unit test can cover is whether the- * editor shows a person what the game will show, and every seam between the- * project setting and the viewport is a place that can be wired wrong while every- * test stays green — which is exactly what happened: depth layers reached the play- * realm and never the edit viewport, so the setting was real everywhere except- * where it is set.- *- * Two opaque squares occupy the SAME place: near red at z = +150 in sorting layer- * 1, far blue at z = -150 in the HIGHER layer 2. Paint order draws blue over red;- * only the depth buffer puts red in front. So the centre pixel of the viewport- * names the answer with no coordinate mapping to get wrong, and the same scene- * asks two more questions of the editor:- *- * depth — the centre of the EDIT viewport is red, not blue- * pick — a click anywhere on the pair selects the near sprite, never the far- * one (ranking hits by list order used to select what is hidden)- * grid — under the perspective eye the grid still reaches the frame's border- * (it was sized from orthoSize, a field that view does not render- * through, and became a bounded island in the middle of the panel)- *- * Run from desktop/ after a dist build: node scripts/editor-25d-check.mjs- * OUT=<dir> writes the captures out, since a pixel assertion is worth looking at.- */-import { spawn } from 'node:child_process';-import { mkdtemp, rm, writeFile } from 'node:fs/promises';-import { inflateSync } from 'node:zlib';-import os from 'node:os';-import path from 'node:path';-import { fileURLToPath } from 'node:url';--const DESKTOP = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');-const OUT = process.env.OUT ?? null;--// ── the project ──────────────────────────────────────────────────────────────--const MATERIAL = JSON.stringify({- version: '1.0', type: 'material', shader: 'opaque.esshader',- blendMode: 9, depthTest: false, properties: {},-}, null, 2);--// Fragment-only: the vertex stage is the one ShaderParser injects, which is the-// stage that has to carry z for any of this to mean anything.-const SHADER = `#pragma shader "Opaque Unlit"-#pragma version 300 es-#pragma domain Unlit2D--#pragma fragment-precision mediump float;-in vec4 v_color;-in vec2 v_texCoord;-uniform sampler2D u_textures[8];-out vec4 fragColor;-void main() {- fragColor = texture(u_textures[0], v_texCoord) * v_color;-}-#pragma end-`;--const sprite = (name, z, layer, color) => ({- id: layer, name, parent: null, children: [],- visible: true,- components: [- { type: 'Transform', data: { position: { x: 0, y: 0, z } } },- {- type: 'Sprite',- data: {- size: { x: 260, y: 260 }, color, layer,- material: 'assets/materials/opaque.esmaterial',- },- },- ],-});--const SCENE = JSON.stringify({- version: '1.0', name: 'Main',- entities: [- {- id: 0, name: 'Camera', parent: null, children: [], visible: true,- components: [- { type: 'Transform', data: { position: { x: 0, y: 0, z: 10 } } },- { type: 'Camera', data: { projectionType: 1, orthoSize: 300, isActive: true, priority: 0 } },- ],- },- sprite('NearRed', 150, 1, { r: 1, g: 0, b: 0, a: 1 }),- sprite('FarBlue', -150, 2, { r: 0, g: 0, b: 1, a: 1 }),- ],-}, null, 1);--const PROJECT = JSON.stringify({- formatVersion: '1', name: 'Depth 2.5D Check', version: '0.1.0',- defaultScene: 'assets/scenes/main.esscene',- designResolution: { width: 800, height: 600 },- features: { rendering: { sortingLayers: ['Default', 'Near', 'Far'], depthLayers: [1, 2] } },-}, null, 2);--const tmpRoot = await mkdtemp(path.join(os.tmpdir(), 'estella-25d-'));-const project = path.join(tmpRoot, 'proj');-const write = async (rel, text) => {- const file = path.join(project, rel);- await rm(file, { force: true });- await writeFile(file, text);-};-const { mkdir } = await import('node:fs/promises');-await mkdir(path.join(project, 'assets', 'scenes'), { recursive: true });-await mkdir(path.join(project, 'assets', 'materials'), { recursive: true });-await write('project.esproject', PROJECT);-await write('assets/scenes/main.esscene', SCENE);-await write('assets/materials/opaque.esmaterial', MATERIAL);-await write('assets/materials/opaque.esshader', SHADER);--// ── a PNG reader, for the two pixels the claims live in ──────────────────────--/** Decode an 8-bit RGB/RGBA PNG into { w, h, px(x, y) → [r,g,b] }. */-function readPNG(buf) {- let pos = 8; // skip the signature- let w = 0, h = 0, colorType = 6;- const idat = [];- while (pos < buf.length) {- const len = buf.readUInt32BE(pos);- const type = buf.toString('ascii', pos + 4, pos + 8);- const data = buf.subarray(pos + 8, pos + 8 + len);- if (type === 'IHDR') {- w = data.readUInt32BE(0);- h = data.readUInt32BE(4);- if (data[8] !== 8) throw new Error(`unsupported bit depth ${data[8]}`);- colorType = data[9];- if (colorType !== 2 && colorType !== 6) throw new Error(`unsupported colour type ${colorType}`);- if (data[12] !== 0) throw new Error('interlaced PNG');- } else if (type === 'IDAT') idat.push(data);- else if (type === 'IEND') break;- pos += 12 + len;- }- const bpp = colorType === 6 ? 4 : 3;- const raw = inflateSync(Buffer.concat(idat));- const stride = w * bpp;- const out = Buffer.alloc(h * stride);- for (let y = 0; y < h; y++) {- const filter = raw[y * (stride + 1)];- const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));- for (let x = 0; x < stride; x++) {- const a = x >= bpp ? out[y * stride + x - bpp] : 0;- const b = y > 0 ? out[(y - 1) * stride + x] : 0;- const c = x >= bpp && y > 0 ? out[(y - 1) * stride + x - bpp] : 0;- let v = line[x];- if (filter === 1) v += a;- else if (filter === 2) v += b;- else if (filter === 3) v += (a + b) >> 1;- else if (filter === 4) {- const p = a + b - c;- const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);- v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;- }- out[y * stride + x] = v & 0xff;- }- }- return {- w, h,- px: (x, y) => {- const i = y * stride + x * bpp;- return [out[i], out[i + 1], out[i + 2]];- },- };-}--const near = (got, want, tol = 60) => got.every((v, i) => Math.abs(v - want[i]) <= tol);-const isBlack = (p) => p[0] < 12 && p[1] < 12 && p[2] < 12;--// ── the driver ───────────────────────────────────────────────────────────────--const child = spawn(process.execPath, ['scripts/editor-mcp.mjs', '--editor'], {- cwd: DESKTOP, stdio: ['pipe', 'pipe', 'pipe'],- env: { ...process.env, ESTELLA_MCP_ALLOW_WRITES: '1' },-});-let buf = ''; const waiters = new Map();-child.stdout.on('data', (d) => {- buf += d.toString();- let nl;- while ((nl = buf.indexOf('\n')) >= 0) {- const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1);- if (!line) continue;- let m; try { m = JSON.parse(line); } catch { continue; }- if (m.id != null && waiters.has(m.id)) { waiters.get(m.id)(m); waiters.delete(m.id); }- }-});-child.stderr.on('data', (d) => { if (process.env.V) process.stderr.write(d); });-const send = (m) => child.stdin.write(JSON.stringify(m) + '\n');-let nextId = 0;-const rpc = (method, params, ms = 120000) => new Promise((res, rej) => {- const id = ++nextId;- const t = setTimeout(() => rej(new Error(`timeout ${method}`)), ms);- waiters.set(id, (m) => { clearTimeout(t); res(m); });- send({ jsonrpc: '2.0', id, method, params });-});-const call = async (name, args, ms) => {- const r = await rpc('tools/call', { name, arguments: args ?? {} }, ms);- if (r.result?.isError) throw new Error(`${name}: ${r.result?.content?.[0]?.text}`);- return r.result?.content?.[0];-};-const json = async (name, args, ms) => JSON.parse((await call(name, args, ms))?.text ?? 'null');-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));-const failures = [];-const check = (ok, message) => { if (!ok) failures.push(message); return ok; };--const done = async (code, msg) => {- console.log(msg);- child.kill();- await sleep(400);- await rm(tmpRoot, { recursive: true, force: true }).catch(() => {});- process.exit(code);-};-process.on('exit', () => { try { child.kill(); } catch {} });--async function capture(label) {- await call('step', { frames: 3 }, 30000);- const block = await call('capture_viewport', {}, 60000);- const png = Buffer.from(block.data ?? '', 'base64');- if (OUT) await writeFile(path.join(OUT, `25d-${label}.png`), png);- return readPNG(png);-}--try {- await rpc('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: '25d', version: '0' } }, 180000);- send({ jsonrpc: '2.0', method: 'notifications/initialized' });- await call('open_project', { root: project }, 180000);- await call('open_scene', { path: 'assets/scenes/main.esscene' }, 120000);- await sleep(2000);-- // 1. Depth reaches the edit viewport. The two squares coincide, so the centre- // pixel IS the answer — no canvas geometry to get wrong.- const ortho = await capture('edit-ortho');- const centre = ortho.px(Math.floor(ortho.w / 2), Math.floor(ortho.h / 2));- check(- near(centre, [255, 0, 0]),- `depth: the edit viewport centre is rgb(${centre}), expected the NEAR sprite's red — `- + 'the project\'s depth layers are not reaching the edit World (blue = paint order).',- );-- // 2. Picking ranks by what was drawn. Both squares cover the same pixels, so- // every hit on them must be the near one; the far one being pickable at all- // means the ranking is on list order rather than on depth.- const tree = await json('get_scene_tree', {}, 30000);- const nearId = tree.find((e) => e.name === 'NearRed')?.id;- const farId = tree.find((e) => e.name === 'FarBlue')?.id;- const picked = new Set();- for (let x = 200; x <= 1500; x += 20) {- for (const y of [300, 400]) {- const id = await json('pick', { clientX: x, clientY: y }, 30000);- if (id != null) picked.add(id);- }- }- check(picked.has(nearId), `pick: no click anywhere on the pair selected the near sprite (${[...picked]})`);- check(!picked.has(farId), 'pick: a click selected the FAR sprite, which is behind the near one everywhere');-- // 3. The grid covers the frame under the perspective eye, not a bounded island.- await call('run_editor_command', { id: 'view.toggleViewPerspective' }, 30000);- await sleep(800);- const persp = await capture('edit-perspective');- const band = Math.max(2, Math.floor(persp.h * 0.04));- let lit = 0;- for (let x = 0; x < persp.w; x += 2) {- for (const y of [band, persp.h - 1 - band]) if (!isBlack(persp.px(x, y))) lit++;- }- check(lit > 0, 'grid: the top/bottom border of the perspective viewport is empty — the grid quad is not covering what this projection sees');-- const centreP = persp.px(Math.floor(persp.w / 2), Math.floor(persp.h / 2));- check(near(centreP, [255, 0, 0]), `depth: the perspective viewport centre is rgb(${centreP}), expected red`);-- if (failures.length) await done(1, `FAIL\n - ${failures.join('\n - ')}`);- await done(0, 'PASS: depth resolves in the edit viewport, picking follows it, and the grid covers the perspective frame');-} catch (e) {- await done(1, `FAIL: ${e.message}`);-}diff --git a/desktop/scripts/editor-checks/depth-layers.mjs b/desktop/scripts/editor-checks/depth-layers.mjsnew file mode 100644index 000000000..ec2dd8bf7--- /dev/null+++ b/desktop/scripts/editor-checks/depth-layers.mjs@@ -0,0 +1,135 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file depth-layers — the 2.5D AUTHORING surface, driven for real.+ *+ * The engine half of 2.5D is covered by verify:render:depth (a paired pixel+ * check painter's order cannot pass). What no unit test can cover is whether the+ * editor shows a person what the game will show: every seam between the project+ * setting and the viewport can be wired wrong while every test stays green,+ * which is exactly what happened — depth layers reached the play realm and+ * neither the edit viewport nor any exported build.+ *+ * Two opaque squares occupy the SAME place: near red at z = +150 in sorting+ * layer 1, far blue at z = -150 in the HIGHER layer 2. Paint order draws blue+ * over red; only the depth buffer puts red in front. So the centre pixel of the+ * viewport names the answer with no coordinate mapping to get wrong, and the+ * same scene asks two more questions of the editor.+ */+import { makeProject, checker, near, isBlack } from '../lib/editorDriver.mjs';++const MATERIAL = JSON.stringify({+ version: '1.0', type: 'material', shader: 'opaque.esshader',+ blendMode: 9, depthTest: false, properties: {},+}, null, 2);++// Fragment-only on purpose: the vertex stage is the one ShaderParser injects,+// which is the stage that has to carry z for any of this to mean anything.+const SHADER = `#pragma shader "Opaque Unlit"+#pragma version 300 es+#pragma domain Unlit2D++#pragma fragment+precision mediump float;+in vec4 v_color;+in vec2 v_texCoord;+uniform sampler2D u_textures[8];+out vec4 fragColor;+void main() {+ fragColor = texture(u_textures[0], v_texCoord) * v_color;+}+#pragma end+`;++const sprite = (name, z, layer, color) => ({+ id: layer, name, parent: null, children: [], visible: true,+ components: [+ { type: 'Transform', data: { position: { x: 0, y: 0, z } } },+ {+ type: 'Sprite',+ data: {+ size: { x: 260, y: 260 }, color, layer,+ material: 'assets/materials/opaque.esmaterial',+ },+ },+ ],+});++const SCENE = JSON.stringify({+ version: '1.0', name: 'Main',+ entities: [+ {+ id: 0, name: 'Camera', parent: null, children: [], visible: true,+ components: [+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 10 } } },+ { type: 'Camera', data: { projectionType: 1, orthoSize: 300, isActive: true, priority: 0 } },+ ],+ },+ sprite('NearRed', 150, 1, { r: 1, g: 0, b: 0, a: 1 }),+ sprite('FarBlue', -150, 2, { r: 0, g: 0, b: 1, a: 1 }),+ ],+}, null, 1);++const PROJECT = JSON.stringify({+ formatVersion: '1', name: 'Depth 2.5D Check', version: '0.1.0',+ defaultScene: 'assets/scenes/main.esscene',+ designResolution: { width: 800, height: 600 },+ features: { rendering: { sortingLayers: ['Default', 'Near', 'Far'], depthLayers: [1, 2] } },+}, null, 2);++export const name = 'depth-layers';+export const describes = 'depth resolves in the edit viewport, picking follows it, the grid covers the perspective frame';++export async function run(ed) {+ const root = await makeProject({+ 'project.esproject': PROJECT,+ 'assets/scenes/main.esscene': SCENE,+ 'assets/materials/opaque.esmaterial': MATERIAL,+ 'assets/materials/opaque.esshader': SHADER,+ });+ const check = checker();+ await ed.open(root, 'assets/scenes/main.esscene');++ // 1. Depth reaches the edit viewport. The two squares coincide, so the centre+ // pixel IS the answer — no canvas geometry to get wrong.+ const ortho = await ed.capture('depth-edit-ortho');+ const centre = ortho.px(Math.floor(ortho.w / 2), Math.floor(ortho.h / 2));+ check(+ near(centre, [255, 0, 0]),+ `depth: the edit viewport centre is rgb(${centre}), expected the NEAR sprite's red — `+ + "the project's depth layers are not reaching the edit World (blue = paint order).",+ );++ // 2. Picking ranks by what was drawn. Both squares cover the same pixels, so+ // every hit must be the near one; the far one being pickable at all means+ // the ranking is on list order rather than on depth.+ const tree = await ed.json('get_scene_tree', {}, 30000);+ const nearId = tree.find((e) => e.name === 'NearRed')?.id;+ const farId = tree.find((e) => e.name === 'FarBlue')?.id;+ const picked = new Set();+ for (let x = 200; x <= 1500; x += 20) {+ for (const y of [300, 400]) {+ const id = await ed.json('pick', { clientX: x, clientY: y }, 30000);+ if (id != null) picked.add(id);+ }+ }+ check(picked.has(nearId), `pick: no click anywhere on the pair selected the near sprite (${[...picked]})`);+ check(!picked.has(farId), 'pick: a click selected the FAR sprite, which is behind the near one everywhere');++ // 3. The grid covers the frame under the perspective eye, not a bounded island.+ await ed.call('run_editor_command', { id: 'view.toggleViewPerspective' }, 30000);+ await ed.sleep(800);+ const persp = await ed.capture('depth-edit-perspective');+ const band = Math.max(2, Math.floor(persp.h * 0.04));+ let lit = 0;+ for (let x = 0; x < persp.w; x += 2) {+ for (const y of [band, persp.h - 1 - band]) if (!isBlack(persp.px(x, y))) lit++;+ }+ check(lit > 0, 'grid: the top/bottom border of the perspective viewport is empty — '+ + 'the grid quad is not covering what this projection sees');++ const centreP = persp.px(Math.floor(persp.w / 2), Math.floor(persp.h / 2));+ check(near(centreP, [255, 0, 0]), `depth: the perspective viewport centre is rgb(${centreP}), expected red`);++ return check.failures;+}diff --git a/desktop/scripts/editor-checks/perspective.mjs b/desktop/scripts/editor-checks/perspective.mjsnew file mode 100644index 000000000..a37bc9295--- /dev/null+++ b/desktop/scripts/editor-checks/perspective.mjs@@ -0,0 +1,115 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file perspective — the editor's perspective eye, driven for real.+ *+ * Unit tests can prove editorCameraInfo builds a perspective matrix; they cannot+ * prove the toggle reaches the renderer. The store flag, the sync effect, the+ * engine resource and the renderer are four seams between the button and the+ * pixels, and every one of them can be wired wrong while every test stays green.+ *+ * So this opens a real editor against a copy of an example, captures the+ * viewport, runs the same command the toolbar button runs, and captures again.+ * "Different pixels" is necessary and not sufficient — a hidden panel would also+ * change them — so it also asks what only a projection can do: content off the+ * z = 0 plane moves, and content ON it does not, in the same frame.+ */+import { cp } from 'node:fs/promises';+import path from 'node:path';+import { makeProject, checker, DESKTOP } from '../lib/editorDriver.mjs';++const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'sprite-rendering');++/** Two sprites, same size, one on the 2D plane and one well behind it. */+const SCENE = JSON.stringify({+ version: '1.0', name: 'Main',+ entities: [+ {+ id: 0, name: 'Camera', parent: null, children: [], visible: true,+ components: [+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 10 } } },+ { type: 'Camera', data: { projectionType: 1, orthoSize: 300, isActive: true, priority: 0 } },+ ],+ },+ {+ id: 1, name: 'OnPlane', parent: null, children: [], visible: true,+ components: [+ { type: 'Transform', data: { position: { x: -200, y: 0, z: 0 } } },+ { type: 'Sprite', data: { size: { x: 120, y: 120 }, color: { r: 1, g: 0, b: 0, a: 1 } } },+ ],+ },+ {+ id: 2, name: 'Behind', parent: null, children: [], visible: true,+ components: [+ { type: 'Transform', data: { position: { x: 200, y: 0, z: -400 } } },+ { type: 'Sprite', data: { size: { x: 120, y: 120 }, color: { r: 0, g: 1, b: 0, a: 1 } } },+ ],+ },+ ],+}, null, 1);++export const name = 'perspective';+export const describes = 'the 2D/3D toggle reaches the renderer, and only off-plane content moves';++/** Horizontal centre of the pixels matching `want`, or null when none are lit. */+function centroidX(png, want, tol = 60) {+ let sum = 0, n = 0;+ for (let y = 0; y < png.h; y += 2) {+ for (let x = 0; x < png.w; x += 2) {+ const p = png.px(x, y);+ if (Math.abs(p[0] - want[0]) <= tol && Math.abs(p[1] - want[1]) <= tol && Math.abs(p[2] - want[2]) <= tol) {+ sum += x; n++;+ }+ }+ }+ return n > 0 ? sum / n : null;+}++export async function run(ed) {+ // A real project (scripts, tsconfig, assets) with a scene of our own, so the+ // claim is about the projection rather than about one example's content.+ const root = await makeProject({ 'assets/scenes/main.esscene': SCENE });+ await cp(path.join(EXAMPLE, 'project.esproject'), path.join(root, 'project.esproject'));+ await cp(path.join(EXAMPLE, 'src'), path.join(root, 'src'), { recursive: true });+ const check = checker();+ await ed.open(root, 'assets/scenes/main.esscene');++ const ortho = await ed.capture('perspective-ortho');+ const orthoOn = centroidX(ortho, [255, 0, 0]);+ const orthoBehind = centroidX(ortho, [0, 255, 0]);+ if (!check(orthoOn != null && orthoBehind != null, 'the orthographic capture shows neither sprite')) {+ return check.failures;+ }++ await ed.call('run_editor_command', { id: 'view.toggleViewPerspective' }, 30000);+ await ed.sleep(800);+ const persp = await ed.capture('perspective-3d');+ const perspOn = centroidX(persp, [255, 0, 0]);+ const perspBehind = centroidX(persp, [0, 255, 0]);+ if (!check(perspOn != null && perspBehind != null, 'the perspective capture shows neither sprite')) {+ return check.failures;+ }++ // The z = 0 sprite is where an orthographic view of the same framing puts it:+ // the editor view frames the scene camera, and on that plane the two+ // projections agree. A toggle that moved everything would be a zoom, not a+ // projection.+ check(+ Math.abs(perspOn - orthoOn) < ortho.w * 0.04,+ `the sprite ON the 2D plane moved from x=${orthoOn?.toFixed(0)} to ${perspOn?.toFixed(0)} — `+ + 'the toggle changed the framing rather than the projection',+ );++ // ...and the one at z = -400 is further from the centre of the frame under+ // perspective, because it is further away. That is the divide, and nothing+ // else in the editor can produce it.+ const centre = ortho.w / 2;+ check(+ Math.abs(perspBehind - centre) < Math.abs(orthoBehind - centre) * 0.95,+ `the sprite at z = -400 sits ${Math.abs(perspBehind - centre).toFixed(0)}px from the centre under `+ + `perspective and ${Math.abs(orthoBehind - centre).toFixed(0)}px orthographically — depth is not `+ + 'reaching the projection',+ );++ return check.failures;+}diff --git a/desktop/scripts/editor-checks/run.mjs b/desktop/scripts/editor-checks/run.mjsnew file mode 100644index 000000000..2e7ebebfd--- /dev/null+++ b/desktop/scripts/editor-checks/run.mjs@@ -0,0 +1,64 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file run.mjs — the editor's authoring surface, gated.+ *+ * The engine has had a pixel gate for a long time (verify:render). The EDITOR+ * had none: every check that opens the real app was a script somebody ran once,+ * on the machine that wrote it, which is how depth layers shipped reaching the+ * play realm and neither the viewport nor a build.+ *+ * Each check is a module exporting `{ name, describes, run(ed) → failures[] }`+ * and gets its OWN editor (a boot is ~15s and a shared one would let the first+ * check's project decide the second's answers). Adding a check is adding a file.+ *+ * node scripts/editor-checks/run.mjs all of them+ * node scripts/editor-checks/run.mjs depth one by name+ * OUT=<dir> … keep the captures+ * V=1 … stream the editor's stderr+ */+import { readdir } from 'node:fs/promises';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { withEditor } from '../lib/editorDriver.mjs';++const HERE = path.dirname(fileURLToPath(import.meta.url));+const wanted = process.argv.slice(2).filter((a) => !a.startsWith('-'));++const files = (await readdir(HERE)).filter((f) => f.endsWith('.mjs') && f !== 'run.mjs').sort();+const checks = [];+for (const file of files) {+ const mod = await import(new URL(file, `file://${HERE.replace(/\\/g, '/')}/`).href);+ if (typeof mod.run !== 'function') continue;+ const name = mod.name ?? path.basename(file, '.mjs');+ if (wanted.length && !wanted.some((w) => name.includes(w))) continue;+ checks.push({ name, describes: mod.describes ?? '', run: mod.run });+}++if (checks.length === 0) {+ console.error(`no editor checks matched ${wanted.join(', ') || '(none given)'}`);+ process.exit(1);+}++let failed = 0;+for (const check of checks) {+ const started = Date.now();+ process.stdout.write(`\n=== ${check.name}: ${check.describes}\n`);+ let failures;+ try {+ failures = await withEditor((ed) => check.run(ed), { client: check.name });+ } catch (err) {+ failures = [`threw: ${err instanceof Error ? err.message : String(err)}`];+ }+ const secs = ((Date.now() - started) / 1000).toFixed(1);+ if (failures?.length) {+ failed++;+ console.error(`FAIL ${check.name} (${secs}s)`);+ for (const f of failures) console.error(` - ${f}`);+ } else {+ console.log(`PASS ${check.name} (${secs}s)`);+ }+}++console.log(`\neditor checks: ${checks.length - failed}/${checks.length} passed`);+process.exit(failed ? 1 : 0);diff --git a/desktop/scripts/editor-mcp-e2e.mjs b/desktop/scripts/editor-mcp-e2e.mjsindex d8deb653e..c360b5bdd 100644--- a/desktop/scripts/editor-mcp-e2e.mjs+++ b/desktop/scripts/editor-mcp-e2e.mjs@@ -6,101 +6,66 @@* tools/list → tools/call), exercising the full path: stdio transport → SDK* Server → executeJavaScript driver → EditorControlSurface → engine. Run from* desktop/ after a dist build: pnpm editor:mcp:e2e+ *+ * The walk is everything a client needs before it can do anything useful —+ * a scene load, a read, the write path, a stepped capture that has to come+ * back as a real PNG block, the resources side — so a break in any of it is+ * a break in all of it. The plumbing lives in lib/editorDriver.mjs; this+ * file is the walk.*/-import { spawn } from 'node:child_process';-import path from 'node:path';-import { fileURLToPath } from 'node:url';+import { withEditor, checker } from './lib/editorDriver.mjs';-const DESKTOP = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const failures = await withEditor(async (ed) => {+ const check = checker();-// The server front is plain node (the Electron half is spawned by the front itself).-const child = spawn(process.execPath, ['scripts/editor-mcp.mjs'], {- cwd: DESKTOP,- stdio: ['pipe', 'pipe', 'pipe'],- env: { ...process.env, ESTELLA_MCP_ALLOW_WRITES: '1' },-});--let buf = '';-const waiters = new Map();-child.stdout.on('data', (d) => {- buf += d.toString();- let nl;- while ((nl = buf.indexOf('\n')) >= 0) {- const line = buf.slice(0, nl).trim();- buf = buf.slice(nl + 1);- if (!line) continue;- let msg;- try { msg = JSON.parse(line); } catch { continue; } // skip stray non-JSON stdout- if (msg.id != null && waiters.has(msg.id)) { waiters.get(msg.id)(msg); waiters.delete(msg.id); }- }-});-child.stderr.on('data', (d) => process.stderr.write(d));--const send = (msg) => child.stdin.write(JSON.stringify(msg) + '\n');-const rpc = (id, method, params) => new Promise((resolve, reject) => {- const t = setTimeout(() => reject(new Error(`timeout waiting for ${method}`)), 30000);- waiters.set(id, (m) => { clearTimeout(t); resolve(m); });- send({ jsonrpc: '2.0', id, method, params });-});-const fail = (m) => { console.log('E2E FAIL:', m); child.kill(); process.exit(1); };--try {- const init = await rpc(1, 'initialize', {- protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'e2e', version: '0' },- });- if (!init.result?.serverInfo) fail('no serverInfo in initialize');- console.log('initialize OK — server:', init.result.serverInfo.name);- send({ jsonrpc: '2.0', method: 'notifications/initialized' });-- const list = await rpc(2, 'tools/list', {});+ const list = await ed.rpc('tools/list', {}, 30000);const names = (list.result?.tools ?? []).map((t) => t.name);- if (!names.includes('load_scene') || !names.includes('get_scene_tree')) fail(`tools/list missing tools: ${names}`);+ check(names.includes('load_scene') && names.includes('get_scene_tree'), `tools/list missing tools: ${names}`);console.log(`tools/list OK — ${names.length} tools`);- const load = await rpc(3, 'tools/call', {- name: 'load_scene',- arguments: { sceneUrl: '/scenes/sprite-rendering.esscene', manifestUrl: '/scenes/sprite-rendering.textures.json' },- });- if (load.result?.isError) fail(`load_scene error: ${load.result?.content?.[0]?.text}`);- console.log('load_scene OK — entityCount:', load.result?.content?.[0]?.text);+ const loaded = await ed.call('load_scene', {+ sceneUrl: '/scenes/sprite-rendering.esscene',+ manifestUrl: '/scenes/sprite-rendering.textures.json',+ }, 60000);+ console.log('load_scene OK — entityCount:', loaded?.text);- const tree = await rpc(4, 'tools/call', { name: 'get_scene_tree', arguments: {} });- if (tree.result?.isError) fail(`get_scene_tree error: ${tree.result?.content?.[0]?.text}`);- const parsed = JSON.parse(tree.result?.content?.[0]?.text ?? 'null');- if (!Array.isArray(parsed) || parsed.length === 0) fail('get_scene_tree returned no nodes');- console.log(`get_scene_tree OK — ${parsed.length} root nodes`);+ const tree = await ed.json('get_scene_tree', {}, 30000);+ check(Array.isArray(tree) && tree.length > 0, 'get_scene_tree returned no nodes');+ console.log(`get_scene_tree OK — ${tree.length} root nodes`);- // Write path (server spawned with ESTELLA_MCP_ALLOW_WRITES=1): spawn + mutate.- const add = await rpc(5, 'tools/call', { name: 'add_entity', arguments: {} });- const newId = Number(add.result?.content?.[0]?.text);- if (add.result?.isError || !Number.isFinite(newId)) fail(`add_entity error: ${add.result?.content?.[0]?.text}`);+ // Write path (the server is spawned with ESTELLA_MCP_ALLOW_WRITES=1).+ const newId = Number((await ed.call('add_entity', {}, 30000))?.text);+ check(Number.isFinite(newId), 'add_entity did not return an id');console.log('add_entity OK — id', newId);- const set = await rpc(6, 'tools/call', {- name: 'set_field',- arguments: { entity: newId, component: 'Transform', key: 'position', type: 'vec3', value: [64, 32, 0] },- });- if (set.result?.isError) fail(`set_field error: ${set.result?.content?.[0]?.text}`);+ await ed.call('set_field', {+ entity: newId, component: 'Transform', key: 'position', type: 'vec3', value: [64, 32, 0],+ }, 30000);console.log('set_field OK');// Observation: a stepped frame captures as a real PNG image content block.- await rpc(7, 'tools/call', { name: 'step', arguments: { frames: 2 } });- const cap = await rpc(8, 'tools/call', { name: 'capture_viewport', arguments: {} });- const img = cap.result?.content?.[0];- if (cap.result?.isError || img?.type !== 'image' || img?.mimeType !== 'image/png' || (img?.data?.length ?? 0) < 100)- fail(`capture_viewport did not return a PNG image block (${JSON.stringify(img)?.slice(0, 120)})`);- console.log(`capture_viewport OK — ${img.data.length} base64 chars`);+ await ed.call('step', { frames: 2 }, 30000);+ const img = await ed.call('capture_viewport', {}, 60000);+ check(+ img?.type === 'image' && img?.mimeType === 'image/png' && (img?.data?.length ?? 0) >= 100,+ `capture_viewport did not return a PNG image block (${JSON.stringify(img)?.slice(0, 120)})`,+ );+ console.log(`capture_viewport OK — ${img?.data?.length} base64 chars`);// Resources: list + read the scene tree as an MCP resource.- const resList = await rpc(9, 'resources/list', {});+ const resList = await ed.rpc('resources/list', {}, 30000);const uris = (resList.result?.resources ?? []).map((r) => r.uri);- if (!uris.includes('editor://scene/tree')) fail(`resources/list missing scene tree: ${uris}`);- const resRead = await rpc(10, 'resources/read', { uri: 'editor://scene/tree' });- if ((resRead.result?.contents?.[0]?.text?.length ?? 0) < 3) fail('resources/read returned no JSON');+ check(uris.includes('editor://scene/tree'), `resources/list missing scene tree: ${uris}`);+ const resRead = await ed.rpc('resources/read', { uri: 'editor://scene/tree' }, 30000);+ check((resRead.result?.contents?.[0]?.text?.length ?? 0) >= 3, 'resources/read returned no JSON');console.log('resources OK — list + read scene tree');- console.log('\nE2E PASS — MCP server drives EditorControlSurface end-to-end');- child.kill();- process.exit(0);-} catch (e) {- fail(String(e?.message ?? e));+ return check.failures;+}, { mode: 'headless', client: 'e2e' });++if (failures.length) {+ console.error('\nE2E FAIL:');+ for (const f of failures) console.error(` - ${f}`);+ process.exit(1);}+console.log('\nE2E PASS — MCP server drives EditorControlSurface end-to-end');+process.exit(0);diff --git a/desktop/scripts/editor-perspective-check.mjs b/desktop/scripts/editor-perspective-check.mjsdeleted file mode 100644index dc94911f0..000000000--- a/desktop/scripts/editor-perspective-check.mjs+++ /dev/null@@ -1,87 +0,0 @@-// SPDX-License-Identifier: Apache-2.0-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-/**- * @file editor-perspective-check.mjs — the editor's perspective eye, driven for real.- *- * Unit tests can prove editorCameraInfo builds a perspective matrix; they cannot- * prove the toggle reaches the renderer. This opens a REAL editor over MCP against- * a temp copy of an example, captures the viewport, runs the same command the- * toolbar button runs, and captures again — failing if the screen did not change.- * The two PNGs are written out (OUT=dir) so the change can be looked at, since- * "different pixels" is necessary but not sufficient for "this is perspective".- * Run from desktop/ after a dist build: node scripts/editor-perspective-check.mjs- */-import { spawn } from 'node:child_process';-import { cp, mkdtemp, rm, writeFile } from 'node:fs/promises';-import os from 'node:os';-import path from 'node:path';--import { fileURLToPath } from 'node:url';-const DESKTOP = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');-const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'sprite-rendering');-const tmpRoot = await mkdtemp(path.join(os.tmpdir(), 'estella-persp-'));-const project = path.join(tmpRoot, 'proj');-await cp(EXAMPLE, project, {- recursive: true,- filter: (src) => !/[/\\](\.esengine|node_modules|dist)([/\\]|$)/.test(src),-});--const child = spawn(process.execPath, ['scripts/editor-mcp.mjs', '--editor'], {- cwd: DESKTOP, stdio: ['pipe', 'pipe', 'pipe'],- env: { ...process.env, ESTELLA_MCP_ALLOW_WRITES: '1' },-});-let buf = ''; const waiters = new Map();-child.stdout.on('data', (d) => {- buf += d.toString();- let nl;- while ((nl = buf.indexOf('\n')) >= 0) {- const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1);- if (!line) continue;- let m; try { m = JSON.parse(line); } catch { continue; }- if (m.id != null && waiters.has(m.id)) { waiters.get(m.id)(m); waiters.delete(m.id); }- }-});-child.stderr.on('data', (d) => { if (process.env.V) process.stderr.write(d); });-const send = (m) => child.stdin.write(JSON.stringify(m) + '\n');-let nextId = 0;-const rpc = (method, params, ms = 120000) => new Promise((res, rej) => {- const id = ++nextId;- const t = setTimeout(() => rej(new Error(`timeout ${method}`)), ms);- waiters.set(id, (m) => { clearTimeout(t); res(m); });- send({ jsonrpc: '2.0', id, method, params });-});-const call = async (name, args, ms) => {- const r = await rpc('tools/call', { name, arguments: args ?? {} }, ms);- if (r.result?.isError) throw new Error(`${name}: ${r.result?.content?.[0]?.text}`);- return r.result?.content?.[0];-};-const done = async (code, msg) => {- console.log(msg); child.kill();- await new Promise((r) => setTimeout(r, 400));- await rm(tmpRoot, { recursive: true, force: true }).catch(() => {});- process.exit(code);-};-process.on('exit', () => { try { child.kill(); } catch {} });--try {- await rpc('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'persp', version: '0' } }, 180000);- send({ jsonrpc: '2.0', method: 'notifications/initialized' });- await call('open_project', { root: project }, 120000);- await call('open_scene', { path: 'assets/scenes/main.esscene' }, 120000);- await new Promise((r) => setTimeout(r, 1500));-- const ortho = await call('capture_viewport', {}, 60000);- await call('run_editor_command', { id: 'view.toggleViewPerspective' }, 30000);- await new Promise((r) => setTimeout(r, 1500));- const persp = await call('capture_viewport', {}, 60000);-- const a = ortho.data ?? '', b = persp.data ?? '';- console.log(`ortho ${a.length} chars, perspective ${b.length} chars`);- if (a.length < 100 || b.length < 100) await done(1, 'FAIL: a capture was not an image');- if (a === b) await done(1, 'FAIL: the perspective toggle changed nothing on screen');- await writeFile(path.join(process.env.OUT ?? '/tmp', 'persp-ortho.png'), Buffer.from(a, 'base64'));- await writeFile(path.join(process.env.OUT ?? '/tmp', 'persp-persp.png'), Buffer.from(b, 'base64'));- await done(0, 'PASS: the viewport re-rendered through a perspective projection');-} catch (e) {- await done(1, `FAIL: ${e.message}`);-}diff --git a/desktop/scripts/lib/editorDriver.mjs b/desktop/scripts/lib/editorDriver.mjsnew file mode 100644index 000000000..88c6dfe90--- /dev/null+++ b/desktop/scripts/lib/editorDriver.mjs@@ -0,0 +1,220 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file editorDriver.mjs — drive a REAL editor over MCP, from a script.+ *+ * The editor's authoring surface has failures no unit test can reach: a project+ * setting that never arrives, a click that selects what is behind what you can+ * see, an overlay drawn on the wrong plane. Each of those is only provable by+ * opening the editor and looking, so the checks that prove them are scripts —+ * and every one of them was re-implementing the same forty lines of JSON-RPC+ * plumbing, which is how the fourth copy ends up with a different timeout and+ * no stderr on failure.+ *+ * This is that plumbing, once: spawn, line-framed RPC, the tool wrappers, a PNG+ * reader for pixel assertions, and a temp project builder. A check is then only+ * its claim.+ *+ * One script keeps its own copy on purpose: editor-mcp-editor-e2e drives an+ * ALTERNATE front (`ESTELLA_E2E_FRONT` points at the shipped bundle, to prove+ * the distribution artifact end to end), which is a different question than+ * "open the editor and look".+ */+import { spawn } from 'node:child_process';+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';+import { inflateSync } from 'node:zlib';+import os from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++export const DESKTOP = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');++/** Write a temp project from `{ 'project-relative/path': text }` and return its root. */+export async function makeProject(files) {+ const root = path.join(await mkdtemp(path.join(os.tmpdir(), 'estella-check-')), 'proj');+ for (const [rel, text] of Object.entries(files)) {+ const abs = path.join(root, rel);+ await mkdir(path.dirname(abs), { recursive: true });+ await writeFile(abs, text);+ }+ return root;+}++/**+ * Decode an 8-bit RGB/RGBA PNG into `{ w, h, px(x, y) → [r,g,b] }`.+ *+ * Pixel assertions are the point of capturing anything: "the picture changed" is+ * what a byte-length comparison can say, and it is not the same claim as "this+ * is the right colour" — a hidden panel changes bytes too.+ */+export function readPNG(buf) {+ let pos = 8; // skip the signature+ let w = 0, h = 0, colorType = 6;+ const idat = [];+ while (pos < buf.length) {+ const len = buf.readUInt32BE(pos);+ const type = buf.toString('ascii', pos + 4, pos + 8);+ const data = buf.subarray(pos + 8, pos + 8 + len);+ if (type === 'IHDR') {+ w = data.readUInt32BE(0);+ h = data.readUInt32BE(4);+ if (data[8] !== 8) throw new Error(`unsupported bit depth ${data[8]}`);+ colorType = data[9];+ if (colorType !== 2 && colorType !== 6) throw new Error(`unsupported colour type ${colorType}`);+ if (data[12] !== 0) throw new Error('interlaced PNG');+ } else if (type === 'IDAT') idat.push(data);+ else if (type === 'IEND') break;+ pos += 12 + len;+ }+ const bpp = colorType === 6 ? 4 : 3;+ const raw = inflateSync(Buffer.concat(idat));+ const stride = w * bpp;+ const out = Buffer.alloc(h * stride);+ for (let y = 0; y < h; y++) {+ const filter = raw[y * (stride + 1)];+ const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));+ for (let x = 0; x < stride; x++) {+ const a = x >= bpp ? out[y * stride + x - bpp] : 0;+ const b = y > 0 ? out[(y - 1) * stride + x] : 0;+ const c = x >= bpp && y > 0 ? out[(y - 1) * stride + x - bpp] : 0;+ let v = line[x];+ if (filter === 1) v += a;+ else if (filter === 2) v += b;+ else if (filter === 3) v += (a + b) >> 1;+ else if (filter === 4) {+ const p = a + b - c;+ const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);+ v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;+ }+ out[y * stride + x] = v & 0xff;+ }+ }+ return {+ w, h,+ px: (x, y) => {+ const i = y * stride + x * bpp;+ return [out[i], out[i + 1], out[i + 2]];+ },+ };+}++/** Whether a pixel is within `tol` of the wanted colour, per channel. */+export const near = (got, want, tol = 60) => got.every((v, i) => Math.abs(v - want[i]) <= tol);+/** Whether a pixel is (near enough to) the clear colour. */+export const isBlack = (p) => p[0] < 12 && p[1] < 12 && p[2] < 12;++const sleep = (ms) => new Promise((r) => setTimeout(r, ms));++/**+ * Open a real editor, hand it to `body`, and always shut it down.+ *+ * `mode: 'editor'` (default) launches the app itself — the only mode that can+ * answer a question about the viewport. `'headless'` is the dev-repo host, which+ * is enough for surface/protocol questions.+ *+ * On a thrown error the editor's last stderr is printed: a check that fails in+ * CI with only "timeout tools/call" has cost somebody the debugging session that+ * this line pays for.+ */+export async function withEditor(body, opts = {}) {+ const args = ['scripts/editor-mcp.mjs'];+ if ((opts.mode ?? 'editor') === 'editor') args.push('--editor');+ const child = spawn(process.execPath, args, {+ cwd: DESKTOP, stdio: ['pipe', 'pipe', 'pipe'],+ env: { ...process.env, ESTELLA_MCP_ALLOW_WRITES: '1' },+ });++ let buf = '';+ const waiters = new Map();+ const errLines = [];+ child.stdout.on('data', (d) => {+ buf += d.toString();+ let nl;+ while ((nl = buf.indexOf('\n')) >= 0) {+ const line = buf.slice(0, nl).trim();+ buf = buf.slice(nl + 1);+ if (!line) continue;+ let m;+ try { m = JSON.parse(line); } catch { continue; }+ if (m.id != null && waiters.has(m.id)) { waiters.get(m.id)(m); waiters.delete(m.id); }+ }+ });+ child.stderr.on('data', (d) => {+ const text = d.toString();+ if (process.env.V) process.stderr.write(text);+ errLines.push(...text.split('\n').filter(Boolean));+ if (errLines.length > 60) errLines.splice(0, errLines.length - 60);+ });++ let nextId = 0;+ const rpc = (method, params, ms = 120000) => new Promise((res, rej) => {+ const id = ++nextId;+ const timer = setTimeout(() => rej(new Error(`timeout ${method} ${params?.name ?? ''}`.trim())), ms);+ waiters.set(id, (m) => { clearTimeout(timer); res(m); });+ child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);+ });++ const call = async (name, args_, ms) => {+ const r = await rpc('tools/call', { name, arguments: args_ ?? {} }, ms);+ if (r.result?.isError) throw new Error(`${name}: ${r.result?.content?.[0]?.text}`);+ return r.result?.content?.[0];+ };++ const out = process.env.OUT ?? null;+ const editor = {+ /** The raw JSON-RPC door, for the protocol itself (tools/list, resources/*). */+ rpc,+ call,+ /** A tool whose reply is JSON text (the scene tree, a pick, the play state). */+ json: async (name, args_, ms) => JSON.parse((await call(name, args_, ms))?.text ?? 'null'),+ sleep,+ /** Step to a settled frame, capture the viewport, decode it. `OUT=dir` keeps the PNG. */+ capture: async (label, frames = 3) => {+ await call('step', { frames }, 30000);+ const block = await call('capture_viewport', {}, 60000);+ const png = Buffer.from(block.data ?? '', 'base64');+ if (out) await writeFile(path.join(out, `${label}.png`), png);+ return readPNG(png);+ },+ /** The composited window (the only way to see gizmo overlays or the play realm). */+ screenshot: async (label) => {+ const block = await call('screenshot', {}, 60000);+ const png = Buffer.from(block.data ?? '', 'base64');+ if (out) await writeFile(path.join(out, `${label}.png`), png);+ return readPNG(png);+ },+ /** Open a project and its scene, settled. */+ open: async (root, scene) => {+ await call('open_project', { root }, 180000);+ if (scene) await call('open_scene', { path: scene }, 120000);+ await sleep(2000);+ },+ };++ try {+ await rpc('initialize', {+ protocolVersion: '2024-11-05', capabilities: {},+ clientInfo: { name: opts.client ?? 'check', version: '0' },+ }, 180000);+ child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`);+ return await body(editor);+ } catch (err) {+ if (errLines.length) {+ console.error(`--- editor stderr (last ${errLines.length} lines) ---`);+ for (const l of errLines) console.error(l);+ console.error('--- end editor stderr ---');+ }+ throw err;+ } finally {+ child.kill();+ await sleep(400);+ }+}++/** Collect failures without stopping at the first: one run, every claim tested. */+export function checker() {+ const failures = [];+ const check = (ok, message) => { if (!ok) failures.push(message); return ok; };+ check.failures = failures;+ return check;+}