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.

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.json
index 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.mjs
deleted file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
deleted file mode 100644
index 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.mjs
new file mode 100644
index 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;
+}