@downdraft/engine 0.1.1 → 0.2.0

package/dist/core/src/telemetry/gpu-resource-tracker.js

@@ -0,0 +1,234 @@
+// ============================================================================
+// GPUResourceTracker — wraps GPUDevice to track texture/buffer allocations
+// Provides live VRAM usage visibility for the DevTools GPU tab
+// ============================================================================
+function getCallsite() {
+    const stack = new Error().stack;
+    if (!stack)
+        return "";
+    const lines = stack.split("\n");
+    // Walk the stack and return the first frame that is NOT inside GPUResourceTracker.
+    // This is more robust than a fixed skip count because Vite/dev mode may add
+    // extra wrapper frames (module system, HMR, etc.).
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line || line.includes("GPUResourceTracker"))
+            continue;
+        // Extract the file:line:col part from the stack line
+        // Chrome format: "at FunctionName (file:line:col)" or "at file:line:col"
+        const match = line.match(/\((.*?):(\d+):(\d+)\)/) || line.match(/at\s+(.*?):(\d+):(\d+)/);
+        if (match) {
+            let file = match[1];
+            // Strip Vite query params (e.g. "file.ts?t=1682345678" -> "file.ts")
+            file = file.split("?")[0];
+            const lineNum = match[2];
+            // Shorten to just the filename + line
+            const shortFile = file.split("/").pop() || file;
+            return shortFile + ":" + lineNum;
+        }
+        return line;
+    }
+    return "";
+}
+let nextResourceId = 1;
+function nextId() {
+    const id = nextResourceId;
+    nextResourceId = (nextResourceId + 1) % 0xFFFFFFFF;
+    return id;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return bytes + " B";
+    if (bytes < 1048576)
+        return (bytes / 1024).toFixed(1) + " KB";
+    return (bytes / 1048576).toFixed(2) + " MB";
+}
+function textureByteSize(format, width, height, depthOrArrayLayers, mipLevelCount) {
+    // Bytes per pixel for common WebGPU formats
+    const bppMap = {
+        "r8unorm": 1,
+        "r8snorm": 1,
+        "r8uint": 1,
+        "r8sint": 1,
+        "r16uint": 2,
+        "r16sint": 2,
+        "r16float": 2,
+        "rg8unorm": 2,
+        "rg8snorm": 2,
+        "rg8uint": 2,
+        "rg8sint": 2,
+        "r32uint": 4,
+        "r32sint": 4,
+        "r32float": 4,
+        "rg16uint": 4,
+        "rg16sint": 4,
+        "rg16float": 4,
+        "rgba8unorm": 4,
+        "rgba8unorm-srgb": 4,
+        "rgba8snorm": 4,
+        "rgba8uint": 4,
+        "rgba8sint": 4,
+        "bgra8unorm": 4,
+        "bgra8unorm-srgb": 4,
+        "rgb9e5ufloat": 4,
+        "rgb10a2uint": 4,
+        "rgb10a2unorm": 4,
+        "rg11b10ufloat": 4,
+        "rg32uint": 8,
+        "rg32sint": 8,
+        "rg32float": 8,
+        "rgba16uint": 8,
+        "rgba16sint": 8,
+        "rgba16float": 8,
+        "rgba32uint": 16,
+        "rgba32sint": 16,
+        "rgba32float": 16,
+        "stencil8": 1,
+        "depth16unorm": 2,
+        "depth24plus": 3,
+        "depth24plus-stencil8": 4,
+        "depth32float": 4,
+        "depth32float-stencil8": 5,
+        "bc1-rgba-unorm": 0.5,
+        "bc1-rgba-unorm-srgb": 0.5,
+        "bc2-rgba-unorm": 1,
+        "bc2-rgba-unorm-srgb": 1,
+        "bc3-rgba-unorm": 1,
+        "bc3-rgba-unorm-srgb": 1,
+        "bc4-r-unorm": 0.5,
+        "bc4-r-snorm": 0.5,
+        "bc5-rg-unorm": 1,
+        "bc5-rg-snorm": 1,
+        "bc6h-rgb-ufloat": 1,
+        "bc6h-rgb-float": 1,
+        "bc7-rgba-unorm": 1,
+        "bc7-rgba-unorm-srgb": 1,
+    };
+    const bpp = bppMap[format] ?? 4; // default to 4 bytes per pixel
+    const bytesPerPixel = typeof bpp === "number" ? bpp : 4;
+    let total = 0;
+    let w = width;
+    let h = height;
+    for (let m = 0; m < mipLevelCount; m++) {
+        total += Math.max(1, w) * Math.max(1, h) * bytesPerPixel;
+        w = Math.max(1, Math.floor(w / 2));
+        h = Math.max(1, Math.floor(h / 2));
+    }
+    return total * depthOrArrayLayers;
+}
+export class GPUResourceTracker {
+    resources = new Map();
+    textureBytes = 0;
+    bufferBytes = 0;
+    textureCount = 0;
+    bufferCount = 0;
+    dirty = false;
+    cachedSortedResources = [];
+    /**
+     * Capture `new Error().stack` callsites for unlabeled resources. Off by
+     * default — stack capture + regex parsing per allocation is expensive for
+     * transient per-frame resources and distorts the profiling it's meant to
+     * inform. Enable via constructor for leak-hunting sessions.
+     */
+    captureCallsites;
+    constructor(opts = {}) {
+        this.captureCallsites = opts.captureCallsites ?? false;
+    }
+    wrapDevice(device) {
+        const tracker = this;
+        const origCreateTexture = device.createTexture.bind(device);
+        const origCreateBuffer = device.createBuffer.bind(device);
+        device.createTexture = function (descriptor) {
+            const tex = origCreateTexture(descriptor);
+            const id = nextId();
+            const hasLabel = !!descriptor.label;
+            const label = descriptor.label || `texture_${id}`;
+            const callsite = !hasLabel && tracker.captureCallsites ? getCallsite() : undefined;
+            const size = descriptor.size;
+            const width = Math.max(0, typeof size === "object" && "width" in size ? (size.width ?? 1) : (typeof size === "number" ? size : 1));
+            const height = Math.max(0, typeof size === "object" && "height" in size ? (size.height ?? 1) : 1);
+            const depthOrArrayLayers = typeof size === "object" && "depthOrArrayLayers" in size ? (size.depthOrArrayLayers ?? 1) : 1;
+            const mipLevelCount = descriptor.mipLevelCount ?? 1;
+            const format = descriptor.format;
+            const bytes = textureByteSize(format, width, height, depthOrArrayLayers, mipLevelCount);
+            tracker.resources.set(id, {
+                id, type: "texture", label, size: bytes,
+                callsite,
+                width, height, depthOrArrayLayers, format,
+                mipLevelCount, sampleCount: descriptor.sampleCount ?? 1, usage: descriptor.usage,
+            });
+            tracker.textureBytes += bytes;
+            tracker.textureCount++;
+            tracker.dirty = true;
+            // Wrap destroy to remove from tracking
+            const origDestroy = tex.destroy.bind(tex);
+            tex.destroy = function () {
+                const r = tracker.resources.get(id);
+                if (r) {
+                    tracker.textureBytes -= r.size;
+                    tracker.resources.delete(id);
+                    tracker.textureCount--;
+                    tracker.dirty = true;
+                }
+                origDestroy();
+            };
+            return tex;
+        };
+        device.createBuffer = function (descriptor) {
+            const buf = origCreateBuffer(descriptor);
+            const id = nextId();
+            const hasLabel = !!descriptor.label;
+            const label = descriptor.label || `buffer_${id}`;
+            const callsite = !hasLabel && tracker.captureCallsites ? getCallsite() : undefined;
+            const bytes = descriptor.size;
+            tracker.resources.set(id, {
+                id, type: "buffer", label, size: bytes,
+                callsite,
+                usageFlags: descriptor.usage,
+            });
+            tracker.bufferBytes += bytes;
+            tracker.bufferCount++;
+            tracker.dirty = true;
+            // Wrap destroy to remove from tracking
+            const origDestroy = buf.destroy.bind(buf);
+            buf.destroy = function () {
+                const r = tracker.resources.get(id);
+                if (r) {
+                    tracker.bufferBytes -= r.size;
+                    tracker.resources.delete(id);
+                    tracker.bufferCount--;
+                    tracker.dirty = true;
+                }
+                origDestroy();
+            };
+            return buf;
+        };
+        return device;
+    }
+    getStats() {
+        if (this.dirty) {
+            this.cachedSortedResources = Array.from(this.resources.values()).sort((a, b) => b.size - a.size);
+            this.dirty = false;
+        }
+        return {
+            textureCount: this.textureCount,
+            bufferCount: this.bufferCount,
+            totalBytes: this.textureBytes + this.bufferBytes,
+            textureBytes: this.textureBytes,
+            bufferBytes: this.bufferBytes,
+            resources: this.cachedSortedResources,
+        };
+    }
+    formatBytes(bytes) {
+        return formatBytes(bytes);
+    }
+    reset() {
+        this.resources.clear();
+        this.textureBytes = 0;
+        this.bufferBytes = 0;
+        this.textureCount = 0;
+        this.bufferCount = 0;
+        this.dirty = false;
+        this.cachedSortedResources = [];
+    }
+}

package/dist/core/src/telemetry/gpu-timer-pool.js

@@ -0,0 +1,223 @@
+import { isGpuTimestampSafe } from "./gpu-timestamp-gate.js";
+/**
+ * Multi-pass GPU timestamp query pool.
+ *
+ * Requires the "timestamp-query" feature on the GPUDevice.
+ * If the feature is not available, all methods are no-ops and readAll returns empty.
+ *
+ * Usage:
+ *   const pool = new GPUTimerPool(device, maxPasses);
+ *   pool.begin(passEncoder, 0);  // begin pass 0
+ *   ... render pass 0 ...
+ *   pool.end(passEncoder, 0);    // end pass 0
+ *   pool.begin(passEncoder, 1);  // begin pass 1
+ *   ... render pass 1 ...
+ *   pool.end(passEncoder, 1);    // end pass 1
+ *   pool.resolve(commandEncoder); // resolve all queries
+ *   const results = await pool.readAll(); // read GPU times
+ */
+export class GPUTimerPool {
+    querySet = null;
+    resolveBuffer = null;
+    readBuffer = null;
+    supported = false;
+    pending = false;
+    bufferMapped = false;
+    pendingResolve = false;
+    maxPasses;
+    lastResults = new Map();
+    constructor(device, maxPasses = 16) {
+        this.maxPasses = maxPasses;
+        this.init(device);
+    }
+    init(device) {
+        const features = device.features;
+        // writeTimestamp on a pass encoder requires the inside-passes feature
+        // ("timestamp-query-inside-passes", FeaturesWGPU on the native wgpu shim).
+        // The whole timestamp path is additionally gated on real hardware —
+        // lavapipe-class software rasterizers lose the device on
+        // writeTimestamp/resolveQuerySet (see isGpuTimestampSafe).
+        const timestampsOk = isGpuTimestampSafe(device);
+        const insidePassTimestamps = timestampsOk &&
+            features.has("timestamp-query-inside-passes");
+        if (!features.has("timestamp-query") || !insidePassTimestamps) {
+            this.supported = false;
+            // Encoder-level timestamps may still be available (base "timestamp-query")
+            this.initEncoderTimestamps(device);
+            if (this.encoderTimestampSupported) {
+                // Allocate query set for encoder-level timestamps even if inside-pass is unsupported
+                try {
+                    const queryCount = this.maxPasses * 2;
+                    this.querySet = device.createQuerySet({ type: "timestamp", count: queryCount });
+                    this.resolveBuffer = device.createBuffer({
+                        size: queryCount * 8,
+                        usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+                    });
+                    this.readBuffer = device.createBuffer({
+                        size: queryCount * 8,
+                        usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+                    });
+                }
+                catch {
+                    this.encoderTimestampSupported = false;
+                }
+            }
+            return;
+        }
+        // Inside-pass timestamps supported → encoder timestamps also supported
+        this.initEncoderTimestamps(device);
+        try {
+            const queryCount = this.maxPasses * 2; // begin + end per pass
+            this.querySet = device.createQuerySet({
+                type: "timestamp",
+                count: queryCount,
+            });
+            this.resolveBuffer = device.createBuffer({
+                size: queryCount * 8,
+                usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+            });
+            this.readBuffer = device.createBuffer({
+                size: queryCount * 8,
+                usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+            });
+            this.supported = true;
+        }
+        catch {
+            this.supported = false;
+        }
+    }
+    isSupported() {
+        return this.supported;
+    }
+    getMaxPasses() {
+        return this.maxPasses;
+    }
+    begin(pass, passIdx) {
+        if (!this.supported || !this.querySet || passIdx >= this.maxPasses)
+            return;
+        const write = pass.writeTimestamp;
+        if (typeof write !== "function") {
+            this.supported = false;
+            return;
+        }
+        write.call(pass, this.querySet, passIdx * 2);
+    }
+    end(pass, passIdx) {
+        if (!this.supported || !this.querySet || passIdx >= this.maxPasses)
+            return;
+        const write = pass.writeTimestamp;
+        if (typeof write !== "function") {
+            this.supported = false;
+            return;
+        }
+        write.call(pass, this.querySet, passIdx * 2 + 1);
+    }
+    resolve(encoder) {
+        // Encoder-level timestamps (blit/copy passes) can be resolved even when
+        // inside-pass timestamps aren't supported.
+        if ((!this.supported && !this.encoderTimestampSupported) || !this.querySet || !this.resolveBuffer || !this.readBuffer)
+            return;
+        if (this.bufferMapped) {
+            // Queue the resolve for the next frame — readBuffer is still mapped.
+            this.pendingResolve = true;
+            return;
+        }
+        const queryCount = this.maxPasses * 2;
+        encoder.resolveQuerySet(this.querySet, 0, queryCount, this.resolveBuffer, 0);
+        encoder.copyBufferToBuffer(this.resolveBuffer, 0, this.readBuffer, 0, queryCount * 8);
+        this.pending = true;
+    }
+    async readAll() {
+        if ((!this.supported && !this.encoderTimestampSupported) || !this.readBuffer || !this.pending)
+            return this.lastResults;
+        this.pending = false;
+        this.bufferMapped = true;
+        try {
+            await this.readBuffer.mapAsync(GPUMapMode.READ);
+            const data = new BigUint64Array(this.readBuffer.getMappedRange());
+            // Reuse lastResults Map — clear() instead of new Map() to avoid per-read allocation
+            const results = this.lastResults;
+            results.clear();
+            for (let i = 0; i < this.maxPasses; i++) {
+                const begin = Number(data[i * 2]);
+                const end = Number(data[i * 2 + 1]);
+                if (end > begin && end > 0 && begin > 0) {
+                    results.set(i, (end - begin) / 1_000_000);
+                }
+            }
+            this.readBuffer.unmap();
+            this.bufferMapped = false;
+            // If a resolve was queued while the buffer was mapped, mark pending so
+            // the next resolve() call will actually execute.
+            if (this.pendingResolve) {
+                this.pendingResolve = false;
+                this.pending = true;
+            }
+            return results;
+        }
+        catch {
+            this.bufferMapped = false;
+            if (this.pendingResolve) {
+                this.pendingResolve = false;
+                this.pending = true;
+            }
+            return this.lastResults;
+        }
+    }
+    getPassGpuMs(passIdx) {
+        return this.lastResults.get(passIdx) ?? 0;
+    }
+    destroy() {
+        this.querySet?.destroy();
+        this.resolveBuffer?.destroy();
+        this.readBuffer?.destroy();
+        this.querySet = null;
+        this.resolveBuffer = null;
+        this.readBuffer = null;
+        this.supported = false;
+    }
+    // ─── Encoder-level timestamps (for blit/copy passes) ────────────────────
+    //
+    // Blit passes (buffer/texture copies, resolves) don't have a pass encoder —
+    // they're commands on the GPUCommandEncoder. When the "timestamp-query"
+    // feature is present without the inside-passes variant, begin()/end() above
+    // are no-ops but encoder-level timestamp commands may still work. We track
+    // encoder-level support separately.
+    encoderTimestampSupported = false;
+    /** Check if encoder-level timestamps are available (for blit passes). */
+    isEncoderTimestampSupported() {
+        return this.encoderTimestampSupported;
+    }
+    /**
+     * Initialize encoder-level timestamp support. Called automatically by init()
+     * when the "timestamp-query" feature is present (even without the inside-passes
+     * variant). Can also be called manually after construction.
+     */
+    initEncoderTimestamps(device) {
+        // Encoder-level timestamps require "timestamp-query-inside-encoders"
+        // (a FeaturesWGPU extension) on the wgpu shim. Native is additionally
+        // gated on real hardware (isGpuTimestampSafe).
+        const isNative = "adapterInfo" in device;
+        this.encoderTimestampSupported =
+            device.features.has("timestamp-query") &&
+                isGpuTimestampSafe(device) &&
+                (!isNative || device.features.has("timestamp-query-inside-encoders"));
+    }
+    /**
+     * Write a begin timestamp on the command encoder (for blit passes).
+     * Uses the same query set + pass index as begin().
+     */
+    beginEncoder(encoder, passIdx) {
+        if (!this.encoderTimestampSupported || !this.querySet || passIdx >= this.maxPasses)
+            return;
+        encoder.writeTimestamp(this.querySet, passIdx * 2);
+    }
+    /**
+     * Write an end timestamp on the command encoder (for blit passes).
+     */
+    endEncoder(encoder, passIdx) {
+        if (!this.encoderTimestampSupported || !this.querySet || passIdx >= this.maxPasses)
+            return;
+        encoder.writeTimestamp(this.querySet, passIdx * 2 + 1);
+    }
+}

package/dist/core/src/telemetry/gpu-timer.js

@@ -0,0 +1,117 @@
+import { isGpuTimestampSafe } from "./gpu-timestamp-gate.js";
+/**
+ * GPU timestamp query helper for measuring GPU execution time.
+ *
+ * Requires the "timestamp-query" feature on the GPUDevice.
+ * If the feature is not available, all methods are no-ops and getTimeMs returns 0.
+ */
+export class GPUTimer {
+    querySet = null;
+    resolveBuffer = null;
+    readBuffer = null;
+    supported = false;
+    pending = false;
+    lastTimeMs = 0;
+    queryCount = 2; // begin + end
+    constructor(device) {
+        this.init(device);
+    }
+    init(device) {
+        const features = device.features;
+        if (!features.has("timestamp-query") || !isGpuTimestampSafe(device)) {
+            this.supported = false;
+            return;
+        }
+        try {
+            this.querySet = device.createQuerySet({
+                type: "timestamp",
+                count: this.queryCount,
+            });
+            this.resolveBuffer = device.createBuffer({
+                size: this.queryCount * 8,
+                usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+            });
+            this.readBuffer = device.createBuffer({
+                size: this.queryCount * 8,
+                usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+            });
+            this.supported = true;
+        }
+        catch {
+            this.supported = false;
+        }
+    }
+    isSupported() {
+        return this.supported;
+    }
+    /**
+     * Write timestamp markers into a render pass.
+     * Call begin() at the start of the pass and end() at the end.
+     */
+    begin(pass) {
+        if (!this.supported || !this.querySet)
+            return;
+        const write = pass.writeTimestamp;
+        if (typeof write !== "function") {
+            this.supported = false;
+            return;
+        }
+        write.call(pass, this.querySet, 0);
+    }
+    end(pass) {
+        if (!this.supported || !this.querySet)
+            return;
+        const write = pass.writeTimestamp;
+        if (typeof write !== "function") {
+            this.supported = false;
+            return;
+        }
+        write.call(pass, this.querySet, 1);
+    }
+    /**
+     * Resolve the timestamp queries and copy to the read buffer.
+     * Call this after the pass ends, on the same command encoder.
+     */
+    resolve(encoder) {
+        if (!this.supported || !this.querySet || !this.resolveBuffer || !this.readBuffer)
+            return;
+        encoder.resolveQuerySet(this.querySet, 0, this.queryCount, this.resolveBuffer, 0);
+        encoder.copyBufferToBuffer(this.resolveBuffer, 0, this.readBuffer, 0, this.queryCount * 8);
+        this.pending = true;
+    }
+    /**
+     * Map the read buffer and compute the GPU time in milliseconds.
+     * Returns a promise that resolves to the time in ms, or 0 if unsupported.
+     */
+    async readTimeMs() {
+        if (!this.supported || !this.readBuffer || !this.pending)
+            return 0;
+        this.pending = false;
+        try {
+            await this.readBuffer.mapAsync(GPUMapMode.READ);
+            const data = new BigUint64Array(this.readBuffer.getMappedRange());
+            const begin = Number(data[0]);
+            const end = Number(data[1]);
+            this.readBuffer.unmap();
+            if (end > begin) {
+                this.lastTimeMs = (end - begin) / 1_000_000;
+            }
+            return this.lastTimeMs;
+        }
+        catch {
+            return this.lastTimeMs;
+        }
+    }
+    getTimeMs() {
+        return this.lastTimeMs;
+    }
+    destroy() {
+        this.querySet?.destroy();
+        this.resolveBuffer?.destroy();
+        this.readBuffer?.destroy();
+        this.querySet = null;
+        this.resolveBuffer = null;
+        this.readBuffer = null;
+        this.supported = false;
+    }
+}

package/dist/core/src/telemetry/gpu-timestamp-gate.js

@@ -0,0 +1,22 @@
+import { getHostCapabilities } from "../platform/runtime.js";
+/**
+ * Whether GPU timestamp queries are safe on this device.
+ *
+ * The wgpu timestamp path (writeTimestamp / resolveQuerySet / map_async
+ * readback) loses the device on lavapipe-class software rasterizers and has
+ * been observed to lose real discrete Vulkan devices under sustained in-game
+ * use — on native it stays behind DOWNDRAFT_GPU_TIMESTAMPS (debug opt-in),
+ * additionally refusing on adapters that report deviceType "cpu" so the
+ * flag can't be used to wedge a software-rendered test run.
+ *
+ * Non-native runtimes always allow it — feature availability is checked
+ * separately by the caller.
+ */
+export function isGpuTimestampSafe(device) {
+    if (getHostCapabilities().runtime !== "native")
+        return true;
+    if (!process.env.DOWNDRAFT_GPU_TIMESTAMPS)
+        return false;
+    const adapterInfo = device.adapterInfo;
+    return adapterInfo?.deviceType !== "cpu";
+}

package/dist/core/src/telemetry/reporter.js

@@ -0,0 +1,56 @@
+export class TelemetryReporter {
+    collector;
+    constructor(collector) {
+        this.collector = collector;
+    }
+    getSnapshot() {
+        const mem = this.collector.getMemoryUsage();
+        const drawStats = this.collector.getDrawStats();
+        return {
+            threads: this.collector.getThreadMetrics(),
+            systemTimings: this.collector.getSystemTimings(),
+            frameTimes: this.collector.getFrameTimes(),
+            averageFrameTime: this.collector.getAverageFrameTime(),
+            p99FrameTime: this.collector.getFrameTimePercentile(0.99),
+            p95FrameTime: this.collector.getFrameTimePercentile(0.95),
+            fps: this.collector.getFPS(),
+            drawCalls: drawStats.drawCalls,
+            triangles: drawStats.triangles,
+            gpuTimeMs: this.collector.getGpuTime(),
+            memory: mem,
+            timestamp: Date.now(),
+        };
+    }
+    toJSON() {
+        return JSON.stringify(this.getSnapshot());
+    }
+    getMCPFormat() {
+        const snap = this.getSnapshot();
+        return {
+            threads: snap.threads.map((t) => ({
+                thread: t.threadName,
+                gc: { totalMs: t.gcPauseTotal, count: t.gcPauseCount, maxMs: t.gcPauseMax },
+                memory: { heapUsed: t.heapUsed, heapTotal: t.heapTotal, rss: t.rss },
+                cpu: { timeMs: t.cpuTime },
+                tick: t.tick,
+            })),
+            frame: {
+                avgMs: snap.averageFrameTime,
+                p95Ms: snap.p95FrameTime,
+                p99Ms: snap.p99FrameTime,
+                fps: snap.fps,
+                history: snap.frameTimes,
+            },
+            draw: {
+                calls: snap.drawCalls,
+                triangles: snap.triangles,
+                gpuTimeMs: snap.gpuTimeMs,
+            },
+            memory: snap.memory,
+            systems: snap.systemTimings.map((s) => ({
+                name: s.name,
+                durationMs: s.durationMs,
+            })),
+        };
+    }
+}

package/dist/core/src/types/engine-types.js

@@ -0,0 +1,21 @@
+// ============================================================================
+// Engine-level shared types — math, identifiers, enums, and message protocols
+// Generic types used across engine core and any game implementation.
+// ============================================================================
+// --- Camera ---
+// CameraMode is exported from ./render/camera — not duplicated here.
+// --- Entity Flags (generic engine-level flags) ---
+export var EntityFlags;
+(function (EntityFlags) {
+    EntityFlags[EntityFlags["None"] = 0] = "None";
+    EntityFlags[EntityFlags["Static"] = 1] = "Static";
+    EntityFlags[EntityFlags["NoCollision"] = 2] = "NoCollision";
+    EntityFlags[EntityFlags["Underwater"] = 4] = "Underwater";
+    EntityFlags[EntityFlags["Onboard"] = 8] = "Onboard";
+    EntityFlags[EntityFlags["Docked"] = 16] = "Docked";
+    EntityFlags[EntityFlags["Sleeping"] = 32] = "Sleeping";
+    EntityFlags[EntityFlags["Dead"] = 64] = "Dead";
+    EntityFlags[EntityFlags["Hostile"] = 128] = "Hostile";
+    EntityFlags[EntityFlags["Tameable"] = 256] = "Tameable";
+    EntityFlags[EntityFlags["Bioluminescent"] = 512] = "Bioluminescent";
+})(EntityFlags || (EntityFlags = {}));