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
feat(renderer): an offscreen preview is addressed by its handle, never entered
esengineed75d46766fe
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 3b87a3cdb..04d86eee0 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 113,"beta": 91,- "experimental": 1670,+ "experimental": 1672,"deprecated": 3},- "total": 1874,+ "total": 1876,"subsystems": [{"id": "ecs",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 654163209..49ef20b12 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1507 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1509 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -7258,6 +7258,33 @@ runtime: stringskeletonField: string```+## SkeletalPreview — class @experimental+```+dispose: () => void+height: number+live: boolean+render: (viewProjection: Float32Array) => Promise<ImageData | null>+submit: (batch: SkeletalPreviewBatch) => boolean+width: number+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview+static prototype: SkeletalPreview+```++## SkeletalPreviewBatch — interface @experimental+```+blendMode: number+depth: number | undefined+indexCount: number+indices: Uint8Array<ArrayBufferLike>+layer: number | undefined+materialId: number | undefined+textureId: number+transform: Float32Array<ArrayBufferLike>+vertexCount: number+vertices: Uint8Array<ArrayBufferLike>+```+## SliceBorder — interface @experimental```bottom: numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 7196e63f0..48e6e87c3 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 89 beta · 1526 experimental · 3 deprecated+Symbols: 113 public · 89 beta · 1528 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -7451,6 +7451,33 @@ runtime: stringskeletonField: string```+## SkeletalPreview — class @experimental+```+dispose: () => void+height: number+live: boolean+render: (viewProjection: Float32Array) => Promise<ImageData | null>+submit: (batch: SkeletalPreviewBatch) => boolean+width: number+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview+static prototype: SkeletalPreview+```++## SkeletalPreviewBatch — interface @experimental+```+blendMode: number+depth: number | undefined+indexCount: number+indices: Uint8Array<ArrayBufferLike>+layer: number | undefined+materialId: number | undefined+textureId: number+transform: Float32Array<ArrayBufferLike>+vertexCount: number+vertices: Uint8Array<ArrayBufferLike>+```+## SliceBorder — interface @experimental```bottom: numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 79b4f7ede..37c85f0d1 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 86 beta · 1506 experimental · 3 deprecated+Symbols: 113 public · 86 beta · 1508 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7253,6 +7253,33 @@ runtime: stringskeletonField: string```+## SkeletalPreview — class @experimental+```+dispose: () => void+height: number+live: boolean+render: (viewProjection: Float32Array) => Promise<ImageData | null>+submit: (batch: SkeletalPreviewBatch) => boolean+width: number+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview+static prototype: SkeletalPreview+```++## SkeletalPreviewBatch — interface @experimental+```+blendMode: number+depth: number | undefined+indexCount: number+indices: Uint8Array<ArrayBufferLike>+layer: number | undefined+materialId: number | undefined+textureId: number+transform: Float32Array<ArrayBufferLike>+vertexCount: number+vertices: Uint8Array<ArrayBufferLike>+```+## SliceBorder — interface @experimental```bottom: numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex c8c1a47ff..fb88f8568 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1528 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1530 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7499,6 +7499,33 @@ runtime: stringskeletonField: string```+## SkeletalPreview — class @experimental+```+dispose: () => void+height: number+live: boolean+render: (viewProjection: Float32Array) => Promise<ImageData | null>+submit: (batch: SkeletalPreviewBatch) => boolean+width: number+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview+static prototype: SkeletalPreview+```++## SkeletalPreviewBatch — interface @experimental+```+blendMode: number+depth: number | undefined+indexCount: number+indices: Uint8Array<ArrayBufferLike>+layer: number | undefined+materialId: number | undefined+textureId: number+transform: Float32Array<ArrayBufferLike>+vertexCount: number+vertices: Uint8Array<ArrayBufferLike>+```+## SliceBorder — interface @experimental```bottom: numberdiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 5bc83c751..37618985f 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -345,7 +345,9 @@ renderer_begin: (matrixPtr: number, targetHandle: number, clearFlags: number, r:renderer_beginFrame: (elapsedSec: number) => voidrenderer_captureFrame: ((w: number, h: number) => number) | undefinedrenderer_captureNextFrame: () => void+renderer_createSkeletalPreview: (w: number, h: number) => numberrenderer_createTarget: (width: number, height: number, flags: number) => number+renderer_destroySkeletalPreview: (preview: number) => voidrenderer_diagnose: () => voidrenderer_end: () => voidrenderer_entityVisibleToCamera: ((registry: CppRegistry, entity: number, layer: number, minX: number, minY: number, maxX: number, maxY: number, outVisiblePtr: number) => void) | undefined@@ -365,6 +367,10 @@ renderer_getPreviewPtr: () => numberrenderer_getPreviewSize: () => numberrenderer_getPreviewWidth: () => numberrenderer_getSkeletal: (() => number) | undefined+renderer_getSkeletalPreviewHeight: (preview: number) => number+renderer_getSkeletalPreviewPtr: (preview: number) => number+renderer_getSkeletalPreviewSize: (preview: number) => number+renderer_getSkeletalPreviewWidth: (preview: number) => numberrenderer_getSnapshotHeight: () => numberrenderer_getSnapshotPtr: () => numberrenderer_getSnapshotSize: () => number@@ -379,10 +385,12 @@ renderer_hasCapturedData: () => booleanrenderer_init: (width: number, height: number) => voidrenderer_pollFrameCapture: ((handle: number) => number) | undefinedrenderer_pollPreviewReadback: () => number+renderer_pollSkeletalPreview: (preview: number) => numberrenderer_pollSnapshotReadback: () => numberrenderer_releaseTarget: (handle: number) => voidrenderer_renderMaterialPreview: (materialId: number, w: number, h: number) => voidrenderer_renderMeshPreview: (meshId: number, w: number, h: number) => void+renderer_renderSkeletalPreview: (preview: number, viewProjectionPtr: number) => numberrenderer_replayToDrawCall: (drawCallIndex: number) => voidrenderer_resize: (width: number, height: number) => voidrenderer_setClearColor: (r: number, g: number, b: number, a: number) => void@@ -396,6 +404,7 @@ renderer_setViewport: (x: number, y: number, w: number, h: number) => voidrenderer_setYSortLayers: ((mask: number) => void) | undefinedrenderer_submitAll: (registry: CppRegistry, vpX: number, vpY: number, vpW: number, vpH: number) => voidrenderer_submitSkeletalBatchByEntity: ((registry: CppRegistry, verticesPtr: number, vertexCount: number, indicesPtr: number, indexCount: number, textureId: number, blendMode: number, entity: number, skelScale: number, flipX: boolean, flipY: boolean, layer: number, depth: number, materialId: number) => void) | undefined+renderer_submitSkeletalPreviewBatch: (preview: number, verticesPtr: number, vertexCount: number, indicesPtr: number, indexCount: number, textureId: number, blendMode: number, transformPtr: number, layer: number, depth: number, materialId: number) => numberrenderer_submitTextBatch: ((verticesPtr: number, vertexCount: number, indicesPtr: number, indexCount: number, textureId: number, transformPtr: number, entity: number, layer: number, depth: number, sdf: number, cullBit: number) => void) | undefinedrenderer_takeFrameCapture: ((handle: number, dest: number, destSize: number) => boolean) | undefinedrenderer_updateTransforms: (registry: CppRegistry) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 4b096156f..9ada6b076 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1518 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1520 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7260,6 +7260,33 @@ runtime: stringskeletonField: string```+## SkeletalPreview — class @experimental+```+dispose: () => void+height: number+live: boolean+render: (viewProjection: Float32Array) => Promise<ImageData | null>+submit: (batch: SkeletalPreviewBatch) => boolean+width: number+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview+static prototype: SkeletalPreview+```++## SkeletalPreviewBatch — interface @experimental+```+blendMode: number+depth: number | undefined+indexCount: number+indices: Uint8Array<ArrayBufferLike>+layer: number | undefined+materialId: number | undefined+textureId: number+transform: Float32Array<ArrayBufferLike>+vertexCount: number+vertices: Uint8Array<ArrayBufferLike>+```+## SliceBorder — interface @experimental```bottom: numberdiff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 53249ba27..612946f67 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -93,6 +93,8 @@ export {} from './render/material';export { renderMeshPreview } from './render/assetPreview';+export { SkeletalPreview } from './render/skeletalPreview';+export type { SkeletalPreviewBatch } from './render/skeletalPreview';export {BUILTIN_SHADER_TEMPLATES,diff --git a/sdk/src/render/skeletalPreview.ts b/sdk/src/render/skeletalPreview.tsnew file mode 100644index 000000000..bdf9d6016--- /dev/null+++ b/sdk/src/render/skeletalPreview.ts@@ -0,0 +1,136 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Offscreen preview of posed skeletal geometry, owned by its handle.+ *+ * Unlike a material ball, what is drawn here is not in any scene: the+ * caller poses a skeleton itself and hands over the batches, which the+ * engine copies and replays through the one skeletal path a frame's own+ * geometry takes.+ *+ * Everything names the handle. There is no current preview, no mode and+ * no begin/end pair to get wrong, so two previews in flight cannot reach+ * each other whatever order their calls arrive in — and a render CONSUMES+ * what was handed over, so a frame that fails cannot draw last frame's+ * pose again underneath the next one.+ */+import type { ESEngineModule } from '../wasm';+import { awaitReadback, READBACK_READY } from './readback';+import { withScratch } from '../wasm/wasmScratch';++export type SkeletalPreviewCore = Pick<ESEngineModule,+ 'renderer_createSkeletalPreview' | 'renderer_submitSkeletalPreviewBatch'+ | 'renderer_renderSkeletalPreview' | 'renderer_pollSkeletalPreview'+ | 'renderer_getSkeletalPreviewPtr' | 'renderer_getSkeletalPreviewSize'+ | 'renderer_getSkeletalPreviewWidth' | 'renderer_getSkeletalPreviewHeight'+ | 'renderer_destroySkeletalPreview' | '_malloc' | '_free' | 'HEAPU8'>;++/** The connected core, when it answers the skeletal-preview surface. */+export function skeletalPreviewCore(m: unknown): SkeletalPreviewCore | null {+ const p = m as SkeletalPreviewCore | null;+ return typeof p?.renderer_createSkeletalPreview === 'function' ? p : null;+}++/** One batch of posed geometry, in the format every skeletal runtime emits. */+export interface SkeletalPreviewBatch {+ /** x,y,u,v,r,g,b,a per vertex. */+ vertices: Uint8Array;+ indices: Uint8Array;+ vertexCount: number;+ indexCount: number;+ textureId: number;+ blendMode: number;+ /** Column-major 4×4, as the renderer takes a model matrix. */+ transform: Float32Array;+ materialId?: number;+ layer?: number;+ depth?: number;+}++/**+ * An offscreen preview of one posed skeleton.+ *+ * Its lifetime is the caller's: whoever needs the preview to be alive holds+ * this, and `dispose` ends it. A disposed handle answers nothing rather than+ * quietly addressing whatever was made next.+ */+export class SkeletalPreview {+ private id: number;++ private constructor(private readonly core: SkeletalPreviewCore, id: number,+ readonly width: number, readonly height: number) {+ this.id = id;+ }++ /** A preview of `w`×`h`, or null where this core has no such surface. */+ static create(module: unknown, w: number, h: number): SkeletalPreview | null {+ const core = skeletalPreviewCore(module);+ if (!core || w <= 0 || h <= 0) return null;+ const id = core.renderer_createSkeletalPreview(w, h);+ return id ? new SkeletalPreview(core, id, w, h) : null;+ }++ get live(): boolean {+ return this.id !== 0;+ }++ /** Hand over one batch. The engine copies it, so these buffers are the+ * caller's again the moment this returns. */+ submit(batch: SkeletalPreviewBatch): boolean {+ if (!this.id) return false;+ const core = this.core;+ return withScratch({ _malloc: core._malloc, _free: core._free }, (alloc) => {+ const vp = alloc(batch.vertices.byteLength);+ const ip = alloc(batch.indices.byteLength);+ const tp = alloc(16 * 4);+ core.HEAPU8.set(batch.vertices, vp);+ core.HEAPU8.set(batch.indices, ip);+ core.HEAPU8.set(new Uint8Array(batch.transform.buffer, batch.transform.byteOffset, 16 * 4), tp);+ return core.renderer_submitSkeletalPreviewBatch(+ this.id, vp, batch.vertexCount, ip, batch.indexCount,+ batch.textureId, batch.blendMode, tp,+ batch.layer ?? 0, batch.depth ?? 0, batch.materialId ?? 0) !== 0;+ });+ }++ /**+ * Draw what has been handed over and resolve with the pixels, upright.+ *+ * Null when this preview already has a readback in flight — one at a time,+ * which is what keeps a landed image and the camera it was drawn with from+ * drifting apart. The caller re-renders when the pending one lands.+ */+ async render(viewProjection: Float32Array): Promise<ImageData | null> {+ if (!this.id) return null;+ const core = this.core;+ const started = withScratch({ _malloc: core._malloc, _free: core._free }, (alloc) => {+ const vp = alloc(16 * 4);+ core.HEAPU8.set(new Uint8Array(viewProjection.buffer, viewProjection.byteOffset, 16 * 4), vp);+ return core.renderer_renderSkeletalPreview(this.id, vp) !== 0;+ });+ if (!started) return null;+ if (await awaitReadback(() => core.renderer_pollSkeletalPreview(this.id)) !== READBACK_READY) {+ return null;+ }+ const size = core.renderer_getSkeletalPreviewSize(this.id);+ const w = core.renderer_getSkeletalPreviewWidth(this.id);+ const h = core.renderer_getSkeletalPreviewHeight(this.id);+ if (size === 0 || w === 0 || h === 0) return null;+ const pixels = new Uint8ClampedArray(core.HEAPU8.buffer, core.renderer_getSkeletalPreviewPtr(this.id), size);+ // Readback rows are bottom-up; flip so the preview is upright.+ const flipped = new Uint8ClampedArray(size);+ const rowBytes = w * 4;+ for (let y = 0; y < h; y++) {+ flipped.set(pixels.subarray(y * rowBytes, (y + 1) * rowBytes), (h - 1 - y) * rowBytes);+ }+ return new ImageData(flipped, w, h);+ }++ /** End it. Idempotent, and the id stops answering rather than addressing+ * whatever is made next. */+ dispose(): void {+ if (!this.id) return;+ this.core.renderer_destroySkeletalPreview(this.id);+ this.id = 0;+ }+}diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 960f08f4b..24fd8b206 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -542,6 +542,20 @@ export interface ESEngineModule {renderer_getSnapshotWidth(): number;renderer_getSnapshotHeight(): number;renderer_renderMaterialPreview(materialId: number, w: number, h: number): void;+ /** A skeletal preview, owned by its handle: every call names one, so two of+ * them cannot reach each other and there is no "current" preview. */+ renderer_createSkeletalPreview(w: number, h: number): number;+ renderer_submitSkeletalPreviewBatch(+ preview: number, verticesPtr: number, vertexCount: number,+ indicesPtr: number, indexCount: number, textureId: number, blendMode: number,+ transformPtr: number, layer: number, depth: number, materialId: number): number;+ renderer_renderSkeletalPreview(preview: number, viewProjectionPtr: number): number;+ renderer_pollSkeletalPreview(preview: number): number;+ renderer_getSkeletalPreviewPtr(preview: number): number;+ renderer_getSkeletalPreviewSize(preview: number): number;+ renderer_getSkeletalPreviewWidth(preview: number): number;+ renderer_getSkeletalPreviewHeight(preview: number): number;+ renderer_destroySkeletalPreview(preview: number): void;renderer_renderMeshPreview(meshId: number, w: number, h: number): void;/** Same 0/1/2 readback contract as renderer_pollSnapshotReadback. */renderer_pollPreviewReadback(): number;diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex a0f497b04..8f21a7cf8 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -38,6 +38,7 @@#include <glm/glm.hpp>#include <glm/gtc/matrix_transform.hpp>#include <glm/gtc/type_ptr.hpp>+#include <cstring>#include <utility>namespace esengine {@@ -974,6 +975,67 @@ bool renderer_takeFrameCapture(u32 handle, uintptr_t dest, u32 destSize) {return true;}+u32 renderer_createSkeletalPreview(i32 w, i32 h) {+ if (!g_renderFrame || w <= 0 || h <= 0) return 0;+ return static_cast<u32>(g_renderFrame->createSkeletalPreview(+ static_cast<u32>(w), static_cast<u32>(h)));+}++i32 renderer_submitSkeletalPreviewBatch(+ u32 preview,+ uintptr_t verticesPtr, i32 vertexCount,+ uintptr_t indicesPtr, i32 indexCount,+ u32 textureId, i32 blendMode, uintptr_t transformPtr,+ i32 layer, f32 depth, u32 materialId+) {+ if (!g_renderFrame || vertexCount < 0 || indexCount < 0) return 0;+ // Skeletal vertex format is x,y,u,v,r,g,b,a (8 floats per vertex).+ auto* vertices = boundarySpan<f32>(verticesPtr, static_cast<u64>(vertexCount) * 8,+ "renderer_submitSkeletalPreviewBatch.vertices");+ auto* indices = boundarySpan<u16>(indicesPtr, static_cast<u64>(indexCount),+ "renderer_submitSkeletalPreviewBatch.indices");+ auto* transform = boundarySpan<f32>(transformPtr, 16,+ "renderer_submitSkeletalPreviewBatch.transform");+ if (!vertices || !indices || !transform) return 0;+ return g_renderFrame->submitSkeletalPreviewBatch(+ preview, vertices, vertexCount, indices, indexCount,+ textureId, blendMode, transform, layer, depth, materialId) ? 1 : 0;+}++i32 renderer_renderSkeletalPreview(u32 preview, uintptr_t viewProjectionPtr) {+ if (!g_renderFrame) return 0;+ auto* vp = boundarySpan<f32>(viewProjectionPtr, 16, "renderer_renderSkeletalPreview.vp");+ if (!vp) return 0;+ glm::mat4 viewProjection{1.0f};+ std::memcpy(&viewProjection[0][0], vp, sizeof(f32) * 16);+ return g_renderFrame->renderSkeletalPreview(preview, viewProjection) ? 1 : 0;+}++i32 renderer_pollSkeletalPreview(u32 preview) {+ return g_renderFrame ? g_renderFrame->pollSkeletalPreview(preview) : 2;+}++uintptr_t renderer_getSkeletalPreviewPtr(u32 preview) {+ return g_renderFrame+ ? reinterpret_cast<uintptr_t>(g_renderFrame->skeletalPreviewPixels(preview)) : 0;+}++u32 renderer_getSkeletalPreviewSize(u32 preview) {+ return g_renderFrame ? g_renderFrame->skeletalPreviewSize(preview) : 0;+}++u32 renderer_getSkeletalPreviewWidth(u32 preview) {+ return g_renderFrame ? g_renderFrame->skeletalPreviewWidth(preview) : 0;+}++u32 renderer_getSkeletalPreviewHeight(u32 preview) {+ return g_renderFrame ? g_renderFrame->skeletalPreviewHeight(preview) : 0;+}++void renderer_destroySkeletalPreview(u32 preview) {+ if (g_renderFrame) g_renderFrame->destroySkeletalPreview(preview);+}+void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h) {if (!g_renderFrame || w <= 0 || h <= 0) return;diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 1b5a79507..fc22ce5e0 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -162,6 +162,23 @@ u32 renderer_getSnapshotSize();u32 renderer_getSnapshotWidth();u32 renderer_getSnapshotHeight();+// A skeletal preview is owned by whoever created it: every call names the+// handle, so two of them cannot reach each other and there is no "current" one.+u32 renderer_createSkeletalPreview(i32 w, i32 h);+i32 renderer_submitSkeletalPreviewBatch(+ u32 preview,+ uintptr_t verticesPtr, i32 vertexCount,+ uintptr_t indicesPtr, i32 indexCount,+ u32 textureId, i32 blendMode, uintptr_t transformPtr,+ i32 layer, f32 depth, u32 materialId);+i32 renderer_renderSkeletalPreview(u32 preview, uintptr_t viewProjectionPtr);+i32 renderer_pollSkeletalPreview(u32 preview);+uintptr_t renderer_getSkeletalPreviewPtr(u32 preview);+u32 renderer_getSkeletalPreviewSize(u32 preview);+u32 renderer_getSkeletalPreviewWidth(u32 preview);+u32 renderer_getSkeletalPreviewHeight(u32 preview);+void renderer_destroySkeletalPreview(u32 preview);+void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h);void renderer_renderMeshPreview(u32 meshId, i32 w, i32 h);i32 renderer_pollPreviewReadback();diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 1aff85abc..166385352 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -705,6 +705,17 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_getSnapshotWidth", &esengine::renderer_getSnapshotWidth);emscripten::function("renderer_getSnapshotHeight", &esengine::renderer_getSnapshotHeight);emscripten::function("renderer_renderMaterialPreview", &esengine::renderer_renderMaterialPreview);+ // Skeletal previews. Every one names its handle — there is no current preview+ // and no begin/end pair, so two of them cannot reach each other.+ emscripten::function("renderer_createSkeletalPreview", &esengine::renderer_createSkeletalPreview);+ emscripten::function("renderer_submitSkeletalPreviewBatch", &esengine::renderer_submitSkeletalPreviewBatch);+ emscripten::function("renderer_renderSkeletalPreview", &esengine::renderer_renderSkeletalPreview);+ emscripten::function("renderer_pollSkeletalPreview", &esengine::renderer_pollSkeletalPreview);+ emscripten::function("renderer_getSkeletalPreviewPtr", &esengine::renderer_getSkeletalPreviewPtr);+ emscripten::function("renderer_getSkeletalPreviewSize", &esengine::renderer_getSkeletalPreviewSize);+ emscripten::function("renderer_getSkeletalPreviewWidth", &esengine::renderer_getSkeletalPreviewWidth);+ emscripten::function("renderer_getSkeletalPreviewHeight", &esengine::renderer_getSkeletalPreviewHeight);+ emscripten::function("renderer_destroySkeletalPreview", &esengine::renderer_destroySkeletalPreview);emscripten::function("renderer_renderMeshPreview", &esengine::renderer_renderMeshPreview);emscripten::function("renderer_pollPreviewReadback", &esengine::renderer_pollPreviewReadback);emscripten::function("renderer_getPreviewPtr", &esengine::renderer_getPreviewPtr);diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 100ccf899..65740479a 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -18,7 +18,9 @@#include <algorithm>#include <cmath>+#include <cstring>#include <limits>+#include <utility>#include <vector>namespace esengine {@@ -603,16 +605,22 @@ void RenderFrame::replayToDrawCall(i32 stopAtDrawCall) {}void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewProjection, u32 w, u32 h) {+ renderSurface(registry, viewProjection, preview_, w, h, {});+}++void RenderFrame::renderSurface(ecs::Registry& registry, const glm::mat4& viewProjection,+ PreviewSurface& surface, u32 w, u32 h,+ std::span<const PendingSkeletalBatch> extraSkeletalBatches) {if (w == 0 || h == 0) return;if (!device_.isDeviceUsable()) return;- if (preview_rt_ == 0) {- preview_rt_ = target_manager_.create(w, h, /*depth=*/false, /*linearFilter=*/false);- } else if (auto* existing = target_manager_.get(preview_rt_);+ if (surface.target == 0) {+ surface.target = target_manager_.create(w, h, /*depth=*/false, /*linearFilter=*/false);+ } else if (auto* existing = target_manager_.get(surface.target);existing && (existing->getWidth() != w || existing->getHeight() != h)) {existing->resize(w, h);}- auto* rt = target_manager_.get(preview_rt_);+ auto* rt = target_manager_.get(surface.target);if (!rt) return;RenderPassDesc previewPass{rt->getFramebuffer(), /*clearColor=*/true};@@ -633,6 +641,16 @@ void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewPcollectAll(registry);+ // AFTER the collect, because the clear above would have eaten them. Geometry+ // a caller posed itself and handed over, replayed through the one skeletal+ // path a scene's batches take.+ for (const auto& batch : extraSkeletalBatches) {+ submitSkeletalBatch(batch.vertices.data(), static_cast<i32>(batch.vertices.size() / 8),+ batch.indices.data(), static_cast<i32>(batch.indices.size()),+ batch.textureId, batch.blendMode, &batch.transform[0][0],+ batch.entity, batch.layer, batch.depth, batch.materialId);+ }+draw_list_.finalize(pool_);pool_.upload();context_.updateCameraConstants(viewProjection);@@ -645,19 +663,124 @@ void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewPdevice_.invalidatePipelineCache();// Async readback seam (same shape as the replay snapshot above).- if (preview_readback_ != ReadbackHandle::Invalid) device_.discardReadback(preview_readback_);- preview_w_ = w;- preview_h_ = h;- preview_pixels_.clear();- preview_readback_ = device_.requestReadback(rt->getFramebuffer(), w, h);+ if (surface.readback != ReadbackHandle::Invalid) device_.discardReadback(surface.readback);+ surface.width = w;+ surface.height = h;+ surface.pixels.clear();+ surface.readback = device_.requestReadback(rt->getFramebuffer(), w, h);}i32 RenderFrame::pollSnapshotReadback() {return pollReadback(snapshot_readback_, snapshot_pixels_, snapshot_w_, snapshot_h_);}+RenderFrame::SkeletalPreview* RenderFrame::skeletalPreview(SkeletalPreviewId id) {+ auto it = skeletal_previews_.find(id);+ return it == skeletal_previews_.end() ? nullptr : it->second.get();+}++const RenderFrame::SkeletalPreview* RenderFrame::skeletalPreview(SkeletalPreviewId id) const {+ auto it = skeletal_previews_.find(id);+ return it == skeletal_previews_.end() ? nullptr : it->second.get();+}++RenderFrame::SkeletalPreviewId RenderFrame::createSkeletalPreview(u32 w, u32 h) {+ if (w == 0 || h == 0) return 0;+ auto preview = std::make_unique<SkeletalPreview>();+ // Its own one-entity scene. The transform is identity and stays that way:+ // where a preview stands is the preview camera's business, and a batch+ // arrives with its own model matrix.+ preview->entity = preview->registry.create();+ preview->registry.emplace<ecs::Transform>(preview->entity);+ preview->surface.width = w;+ preview->surface.height = h;+ const SkeletalPreviewId id = next_skeletal_preview_++;+ skeletal_previews_.emplace(id, std::move(preview));+ return id;+}++bool RenderFrame::submitSkeletalPreviewBatch(+ SkeletalPreviewId id,+ const f32* vertices, i32 vertexCount,+ const u16* indices, i32 indexCount,+ u32 textureId, i32 blendMode, const f32* transform16,+ i32 layer, f32 depth, u32 materialId+) {+ auto* preview = skeletalPreview(id);+ if (!preview || !vertices || !indices || vertexCount < 0 || indexCount < 0) return false;+ PendingSkeletalBatch batch;+ // COPIED, not referenced: this sits until the next render call, and the+ // caller's scratch is gone the moment it returns.+ batch.vertices.assign(vertices, vertices + static_cast<usize>(vertexCount) * 8);+ batch.indices.assign(indices, indices + static_cast<usize>(indexCount));+ batch.textureId = textureId;+ batch.blendMode = blendMode;+ if (transform16) std::memcpy(&batch.transform[0][0], transform16, sizeof(f32) * 16);+ batch.entity = preview->entity;+ batch.layer = layer;+ batch.depth = depth;+ batch.materialId = materialId;+ preview->pending.push_back(std::move(batch));+ return true;+}++bool RenderFrame::renderSkeletalPreview(SkeletalPreviewId id, const glm::mat4& viewProjection) {+ auto* preview = skeletalPreview(id);+ if (!preview) return false;+ // One in flight per preview. A second render would land two images for one+ // camera and leave a caller no way to say which its overlay belongs to.+ if (preview->surface.readback != ReadbackHandle::Invalid) return false;+ // Taken before the draw: a render that throws or bails must not leave last+ // frame's geometry to be drawn again on top of the next one.+ const auto batches = std::exchange(preview->pending, {});+ renderSurface(preview->registry, viewProjection, preview->surface,+ preview->surface.width, preview->surface.height, batches);+ return true;+}++i32 RenderFrame::pollSkeletalPreview(SkeletalPreviewId id) {+ auto* preview = skeletalPreview(id);+ if (!preview) return 2;+ return pollReadback(preview->surface.readback, preview->surface.pixels,+ preview->surface.width, preview->surface.height);+}++const u8* RenderFrame::skeletalPreviewPixels(SkeletalPreviewId id) const {+ const auto* preview = skeletalPreview(id);+ return preview ? preview->surface.pixels.data() : nullptr;+}++u32 RenderFrame::skeletalPreviewSize(SkeletalPreviewId id) const {+ const auto* preview = skeletalPreview(id);+ return preview ? static_cast<u32>(preview->surface.pixels.size()) : 0;+}++u32 RenderFrame::skeletalPreviewWidth(SkeletalPreviewId id) const {+ const auto* preview = skeletalPreview(id);+ return preview ? preview->surface.width : 0;+}++u32 RenderFrame::skeletalPreviewHeight(SkeletalPreviewId id) const {+ const auto* preview = skeletalPreview(id);+ return preview ? preview->surface.height : 0;+}++void RenderFrame::destroySkeletalPreview(SkeletalPreviewId id) {+ auto it = skeletal_previews_.find(id);+ if (it == skeletal_previews_.end()) return;+ // Logical ownership ends now; the device's outstanding work is handed back+ // the same way every other readback is, so nothing lands in freed pixels.+ auto& surface = it->second->surface;+ if (surface.readback != ReadbackHandle::Invalid) {+ device_.discardReadback(surface.readback);+ surface.readback = ReadbackHandle::Invalid;+ }+ if (surface.target != 0) target_manager_.release(surface.target);+ skeletal_previews_.erase(it);+}+i32 RenderFrame::pollPreviewReadback() {- return pollReadback(preview_readback_, preview_pixels_, preview_w_, preview_h_);+ return pollReadback(preview_.readback, preview_.pixels, preview_.width, preview_.height);}i32 RenderFrame::pollReadback(ReadbackHandle& handle, std::vector<u8>& pixels, u32 w, u32 h) {diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 996e9fd17..1edbe390b 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -23,6 +23,8 @@#include "../../resource/ResourceManager.hpp"#include <glm/glm.hpp>+#include <span>+#include <unordered_map>#include <vector>#include <string>#include <memory>@@ -171,6 +173,41 @@ public:Entity entity, i32 layer, f32 depth, bool sdf, u32 cullBit = 0);+ /**+ * @brief One offscreen render's resources, correct only together.+ *+ * @details Loose, they were one slot: two previews in flight overwrote each+ * other's target, readback and pixels. As an object, a caller with+ * its own preview owns its own surface.+ */+ struct PreviewSurface {+ RenderTargetManager::Handle target = 0;+ ReadbackHandle readback = ReadbackHandle::Invalid;+ std::vector<u8> pixels;+ u32 width = 0;+ u32 height = 0;+ };++ /**+ * @brief Skeletal geometry a caller holds until it renders, owning its bytes.+ *+ * @details A scene's batches go straight into the frame being built. A+ * preview's cross the ABI, wait for a render call, and are replayed+ * — so they cannot be spans into the caller's scratch. Owning the+ * bytes is what lets `submit` return and the caller reuse its buffer.+ */+ struct PendingSkeletalBatch {+ std::vector<f32> vertices;+ std::vector<u16> indices;+ u32 textureId = 0;+ i32 blendMode = 0;+ glm::mat4 transform{1.0f};+ Entity entity{};+ i32 layer = 0;+ f32 depth = 0.0f;+ u32 materialId = 0;+ };+/*** @brief Batch vertices posed by a skeletal runtime, drawn as one entity's geometry.* @details Serves every such runtime — Spine and DragonBones both arrive here — and@@ -241,14 +278,58 @@ public:* viewport exactly. Clobbers the transient draw list/pool, which the next real frame rebuilds.*/void renderToTarget(ecs::Registry& registry, const glm::mat4& viewProjection, u32 w, u32 h);- const u8* getPreviewPixels() const { return preview_pixels_.data(); }- u32 getPreviewSize() const { return static_cast<u32>(preview_pixels_.size()); }- u32 getPreviewWidth() const { return preview_w_; }- u32 getPreviewHeight() const { return preview_h_; }+ const u8* getPreviewPixels() const { return preview_.pixels.data(); }+ u32 getPreviewSize() const { return static_cast<u32>(preview_.pixels.size()); }+ u32 getPreviewWidth() const { return preview_.width; }+ u32 getPreviewHeight() const { return preview_.height; }/** Lands the preview's async readback; same 0/1/2 contract as pollSnapshotReadback(). */i32 pollPreviewReadback();+ // — Skeletal previews —————————————————————————————————————————————————————+ // Every call names its handle: no current preview, no mode, no begin/end+ // pair, so two in flight cannot reach each other whatever the call order.++ /** A skeletal preview's id. Carries a generation, so a destroyed one cannot+ * come back pointing at whatever took its slot. */+ using SkeletalPreviewId = u64;++ /** A preview of @p w×@p h, or 0 when one cannot be made. */+ SkeletalPreviewId createSkeletalPreview(u32 w, u32 h);++ /** Hand one batch to @p id, which COPIES it: the caller may reuse its+ * buffers the moment this returns. False for an id that is not live — a+ * stale handle is a mistake worth hearing about, not a no-op. */+ bool submitSkeletalPreviewBatch(+ SkeletalPreviewId id,+ const f32* vertices, i32 vertexCount,+ const u16* indices, i32 indexCount,+ u32 textureId, i32 blendMode, const f32* transform16,+ i32 layer, f32 depth, u32 materialId);++ /**+ * Draw everything handed to @p id, and start its readback. CONSUMES the+ * batches, so a render that fails cannot draw last frame's pose again.+ *+ * Refused while this preview's readback is in flight — one at a time keeps a+ * landed image and the camera it was drawn with together.+ */+ bool renderSkeletalPreview(SkeletalPreviewId id, const glm::mat4& viewProjection);++ /** Lands @p id's readback: 0 pending, 1 pixels available, 2 nothing to read. */+ i32 pollSkeletalPreview(SkeletalPreviewId id);+ const u8* skeletalPreviewPixels(SkeletalPreviewId id) const;+ u32 skeletalPreviewSize(SkeletalPreviewId id) const;+ u32 skeletalPreviewWidth(SkeletalPreviewId id) const;+ u32 skeletalPreviewHeight(SkeletalPreviewId id) const;++ /**+ * End @p id. Ownership ends here and the id stops answering; the target and+ * any readback still in the device's hands are released the way every other+ * one is, so nothing lands in freed memory.+ */+ void destroySkeletalPreview(SkeletalPreviewId id);+void addPlugin(std::unique_ptr<RenderTypePlugin> plugin);void collectAll(ecs::Registry& registry);@@ -291,6 +372,17 @@ private:// resets @p handle. Returns the 0/1/2 contract of the public poll methods.i32 pollReadback(ReadbackHandle& handle, std::vector<u8>& pixels, u32 w, u32 h);+ /**+ * The collect+execute body every preview shares, with an explicit target.+ *+ * @p extraSkeletalBatches replay AFTER `collectAll` — before it the draw+ * list is cleared and they are dropped. A span, not a callback: a hook here+ * would become where every future pass is inserted.+ */+ void renderSurface(ecs::Registry& registry, const glm::mat4& viewProjection,+ PreviewSurface& surface, u32 w, u32 h,+ std::span<const PendingSkeletalBatch> extraSkeletalBatches);+Stats stats_;/*** ONE per frame, spanning the graph. GL's TIME_ELAPSED has a single global@@ -304,11 +396,21 @@ private:ReadbackHandle snapshot_readback_ = ReadbackHandle::Invalid;u32 snapshot_w_ = 0;u32 snapshot_h_ = 0;- std::vector<u8> preview_pixels_;- RenderTargetManager::Handle preview_rt_ = 0;- ReadbackHandle preview_readback_ = ReadbackHandle::Invalid;- u32 preview_w_ = 0;- u32 preview_h_ = 0;+ PreviewSurface preview_;++ /** One editor preview: its own scene, its own surface, its own pending work. */+ struct SkeletalPreview {+ ecs::Registry registry;+ Entity entity{};+ std::vector<PendingSkeletalBatch> pending;+ PreviewSurface surface;+ };+ std::unordered_map<SkeletalPreviewId, Unique<SkeletalPreview>> skeletal_previews_;+ /** Never reused, so a destroyed id can only ever be a destroyed id. */+ SkeletalPreviewId next_skeletal_preview_ = 1;++ SkeletalPreview* skeletalPreview(SkeletalPreviewId id);+ const SkeletalPreview* skeletalPreview(SkeletalPreviewId id) const;bool in_frame_ = false;bool flushed_ = false;/// Depth state for the capture's attachment — see applySceneDepthNeed.diff --git a/tools/check-preview-ownership.mjs b/tools/check-preview-ownership.mjsnew file mode 100644index 000000000..9dcc70f9c--- /dev/null+++ b/tools/check-preview-ownership.mjs@@ -0,0 +1,129 @@+#!/usr/bin/env node+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-preview-ownership.mjs — an offscreen preview is addressed, never+ * entered.+ *+ * The shape refused here is a renderer that is "in preview mode": a begin, some+ * submits whose destination depends on the calls around them, and an end. It is+ * the same family as the ambient state the shadow pass and the certificate+ * transport were each moved out of, and it fails the same way — by working until+ * two callers exist.+ *+ * What replaced it: every call names a handle, the batches a preview holds own+ * their bytes, and the one shared render body takes its destination as an+ * argument. Each of those is a decision somebody could undo without noticing.+ *+ * node tools/check-preview-ownership.mjs+ */+import { readFileSync, existsSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const FRAME_H = 'src/esengine/renderer/frame/RenderFrame.hpp';+const FRAME_C = 'src/esengine/renderer/frame/RenderFrame.cpp';+const BINDINGS_H = 'src/esengine/bindings/RendererBindings.hpp';++const missing = [FRAME_H, FRAME_C, BINDINGS_H].filter((f) => !existsSync(path.join(ROOT, f)));+if (missing.length) {+ console.error(`check-preview-ownership is stale: ${missing.join(', ')} does not exist.`);+ process.exit(1);+}++const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');+const strip = (text) => text+ .replace(/\/\*[\s\S]*?\*\//g, '')+ .replace(/\/\/[^\n]*/g, '');++const RULES = [+ {+ rule: 'No renderer state says which preview is the current one. A begin/end pair makes what a submit reaches depend on the calls around it, which is correct until two callers exist.',+ holds: () => {+ const bad = [];+ for (const file of [FRAME_H, FRAME_C, BINDINGS_H]) {+ const text = strip(read(file));+ for (const m of text.matchAll(/\b(current|active|in)_?[Pp]review\w*\b/g)) {+ bad.push(`${file} declares ${m[0]}`);+ }+ if (/\b(begin|end)SkeletalPreview\b/.test(text)) {+ bad.push(`${file} has a begin/end preview pair`);+ }+ }+ return bad.length ? bad.join('; ') : null;+ },+ },+ {+ rule: 'Every skeletal-preview entry takes the preview it is about as its first argument. An entry without one can only mean "the current preview".',+ holds: () => {+ const text = strip(read(BINDINGS_H));+ const bad = [];+ for (const m of text.matchAll(/\b(\w*SkeletalPreview\w*)\s*\(([^)]*)\)/g)) {+ const [, name, args] = m;+ if (name.includes('create')) continue; // creates one rather than naming one+ if (!/^\s*u32 preview\b/.test(args)) bad.push(name);+ }+ return bad.length === 0 ? null+ : `${bad.join(', ')} does not name the preview it acts on`;+ },+ },+ {+ rule: 'The shared render body takes a SPAN of batches, never a callback. A hook there becomes the place every future pass is inserted, and this is a preview rather than a second orchestration door.',+ holds: () => {+ const decl = strip(read(FRAME_H)).match(/void renderSurface\(([\s\S]*?)\);/);+ if (!decl) return 'renderSurface is gone — the shared render body was inlined again';+ return /std::function|auto&&\s*\w+|template/.test(decl[1])+ ? 'renderSurface takes a callback' : null;+ },+ },+ {+ rule: 'A preview\'s batches own their bytes. They cross the ABI and wait for a render call, so a span into the caller\'s scratch would be a lifetime protocol nobody wrote down.',+ holds: () => {+ const body = strip(read(FRAME_H)).match(/struct PendingSkeletalBatch \{([\s\S]*?)\};/);+ if (!body) return 'PendingSkeletalBatch is gone';+ if (/\bconst\s+\w+\s*\*|std::span|_ptr\b/.test(body[1])) {+ return 'PendingSkeletalBatch refers to memory it does not own';+ }+ return /std::vector<f32>[\s\S]*std::vector<u16>/.test(body[1]) ? null+ : 'PendingSkeletalBatch no longer owns its vertices and indices';+ },+ },+ {+ rule: 'Handed-over batches are replayed AFTER the collect. Before it, the draw list is cleared and they are silently dropped — which is the whole reason a preview holds them rather than submitting through.',+ holds: () => {+ const body = strip(read(FRAME_C)).match(/void RenderFrame::renderSurface\([\s\S]*?\n\}/);+ if (!body) return 'renderSurface is gone';+ const collect = body[0].indexOf('collectAll(registry)');+ // The LOOP, not the parameter — which is named in the signature above.+ const replay = body[0].search(/for\s*\([^)]*:\s*extraSkeletalBatches\s*\)/);+ const finalize = body[0].indexOf('draw_list_.finalize');+ if (collect < 0 || replay < 0 || finalize < 0) return 'renderSurface no longer collects, replays and finalizes';+ return collect < replay && replay < finalize ? null+ : 'the replay is not between the collect and the finalize';+ },+ },+ {+ rule: 'A render consumes what it was handed. Left behind, the batches would draw again under the next frame — which is a clear/submit/render protocol wearing different clothes.',+ holds: () => {+ const body = strip(read(FRAME_C)).match(/bool RenderFrame::renderSkeletalPreview\([\s\S]*?\n\}/);+ if (!body) return null; // ownership moved; the ABI's own rule covers it+ return /std::exchange\(\s*\w+->pending/.test(body[0]) ? null+ : 'renderSkeletalPreview does not take its pending batches';+ },+ },+];++const findings = [];+for (const { rule, holds } of RULES) {+ const broken = holds();+ if (broken) findings.push(`${broken}\n the boundary: ${rule}`);+}++if (findings.length === 0) {+ console.log(`check-preview-ownership: ${RULES.length} frozen boundaries — a preview is addressed by its handle, never entered.`);+ process.exit(0);+}+for (const f of findings) console.error(`✗ ${f}`);+console.error('\nChanging one of these is allowed — with a counterexample. Edit this file and say why.');+process.exit(1);diff --git a/tools/gates.mjs b/tools/gates.mjsindex dddd5e685..fd80aa8fb 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -134,6 +134,9 @@ export const GATES = [{ id: 'tilemap-realm', run: 'node tools/check-tilemap-realm.mjs' },// The five spine lifetime invariants, each with the judgment that proves it:// what they replaced were teardown protocols, and a protocol comes back quietly.+ // An offscreen preview is addressed by its handle, never entered: no current+ // preview, no begin/end pair, and batches that own their bytes.+ { id: 'preview-ownership', run: 'node tools/check-preview-ownership.mjs' },{ id: 'spine-lifetimes', run: 'node tools/check-spine-lifetimes.mjs' },// The profiler's spine section renders the realm's report and computes none// of it: one side measures a frame, or two of them disagree about it.