@downdraft/engine 0.1.1 → 0.2.0

package/dist/modules/devtools/src/debug-raycast.js

@@ -0,0 +1,296 @@
+// ============================================================================
+// DebugRaycast — 3D aim ray visualization with entity highlighting
+// Generic GPU rendering logic; game provides raycast results via IRaycastProvider.
+// ============================================================================
+import { calculateViewProj, createValidatedShaderModule, DEPTH_FORMAT, MSAA_SAMPLE_COUNT } from "@downdraft/engine";
+const RAY_MAX_DIST = 60;
+const RAY_THICKNESS = 0.06;
+const DEBUG_RAY_WGSL = /* wgsl */ `
+struct DebugRayUniforms {
+  viewProj: mat4x4<f32>,
+  color: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> uniforms: DebugRayUniforms;
+
+struct VSIn {
+  @location(0) position: vec3<f32>,
+};
+
+struct VSOut {
+  @builtin(position) clipPos: vec4<f32>,
+};
+
+@vertex
+fn vs_main(input: VSIn) -> VSOut {
+  var out: VSOut;
+  out.clipPos = uniforms.viewProj * vec4<f32>(input.position, 1.0);
+  return out;
+}
+
+@fragment
+fn fs_main(input: VSOut) -> @location(0) vec4<f32> {
+  return uniforms.color;
+}
+`;
+const CUBE_EDGE_VERTS = new Float32Array([
+    -1, -1, -1, 1, -1, -1,
+    1, -1, -1, 1, -1, 1,
+    1, -1, 1, -1, -1, 1,
+    -1, -1, 1, -1, -1, -1,
+    -1, 1, -1, 1, 1, -1,
+    1, 1, -1, 1, 1, 1,
+    1, 1, 1, -1, 1, 1,
+    -1, 1, 1, -1, 1, -1,
+    -1, -1, -1, -1, 1, -1,
+    1, -1, -1, 1, 1, -1,
+    1, -1, 1, 1, 1, 1,
+    -1, -1, 1, -1, 1, 1,
+]);
+const rayBoxVerts = new Float32Array(36 * 3);
+const cubeVerts = new Float32Array(CUBE_EDGE_VERTS.length);
+const rayUniformData = new Float32Array(20);
+const highlightUniformData = new Float32Array(20);
+export class DebugRaycast {
+    device;
+    format;
+    show = false;
+    provider = null;
+    triPipeline = null;
+    linePipeline = null;
+    bindGroupLayout = null;
+    rayUniformBuffer = null;
+    rayBindGroup = null;
+    highlightUniformBuffer = null;
+    highlightBindGroup = null;
+    rayVertBuffer = null;
+    cubeVertBuffer = null;
+    viewProj = new Float32Array(16);
+    rayOrigin = [0, 0, 0];
+    rayEnd = [0, 0, 0];
+    hit = null;
+    constructor(device, format) {
+        this.device = device;
+        this.format = format;
+    }
+    setProvider(provider) {
+        this.provider = provider;
+    }
+    init() {
+        this.rayUniformBuffer = this.device.createBuffer({
+            size: 80,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.highlightUniformBuffer = this.device.createBuffer({
+            size: 80,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.bindGroupLayout = this.device.createBindGroupLayout({
+            entries: [
+                {
+                    binding: 0,
+                    visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+                    buffer: { type: "uniform" },
+                },
+            ],
+        });
+        this.rayBindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [{ binding: 0, resource: { buffer: this.rayUniformBuffer } }],
+        });
+        this.highlightBindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [{ binding: 0, resource: { buffer: this.highlightUniformBuffer } }],
+        });
+        const shaderModule = createValidatedShaderModule(this.device, { code: DEBUG_RAY_WGSL, label: "DebugRaycast" });
+        const blendState = {
+            alpha: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+            color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+        };
+        const depthState = {
+            format: DEPTH_FORMAT,
+            depthWriteEnabled: false,
+            depthCompare: "less-equal",
+        };
+        const vertexState = {
+            module: shaderModule,
+            entryPoint: "vs_main",
+            buffers: [
+                {
+                    arrayStride: 12,
+                    attributes: [{ shaderLocation: 0, offset: 0, format: "float32x3" }],
+                },
+            ],
+        };
+        const fragmentState = {
+            module: shaderModule,
+            entryPoint: "fs_main",
+            targets: [{ format: this.format, blend: blendState }],
+        };
+        this.triPipeline = this.device.createRenderPipeline({
+            layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.bindGroupLayout] }),
+            vertex: vertexState,
+            fragment: fragmentState,
+            primitive: { topology: "triangle-list" },
+            multisample: { count: MSAA_SAMPLE_COUNT },
+            depthStencil: depthState,
+        });
+        this.linePipeline = this.device.createRenderPipeline({
+            layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.bindGroupLayout] }),
+            vertex: vertexState,
+            fragment: fragmentState,
+            primitive: { topology: "line-list" },
+            multisample: { count: MSAA_SAMPLE_COUNT },
+            depthStencil: depthState,
+        });
+        this.rayVertBuffer = this.device.createBuffer({
+            size: 432,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.cubeVertBuffer = this.device.createBuffer({
+            size: CUBE_EDGE_VERTS.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+    }
+    setShow(show) {
+        this.show = show;
+    }
+    isShown() {
+        return this.show;
+    }
+    update(camera, origin, direction) {
+        if (!this.show || !this.provider)
+            return;
+        this.viewProj = calculateViewProj(camera);
+        const [ox, oy, oz] = origin;
+        const [dx, dy, dz] = direction;
+        const hit = this.provider.raycast(ox, oy, oz, dx, dy, dz, RAY_MAX_DIST);
+        if (hit) {
+            this.rayOrigin = [ox, oy, oz];
+            this.rayEnd = [hit.worldX, hit.worldY, hit.worldZ];
+            this.hit = hit;
+        }
+        else {
+            this.rayOrigin = [ox, oy, oz];
+            this.rayEnd = [ox + dx * RAY_MAX_DIST, oy + dy * RAY_MAX_DIST, oz + dz * RAY_MAX_DIST];
+            this.hit = null;
+        }
+    }
+    buildRayBoxVerts(ox, oy, oz, ex, ey, ez, out) {
+        let dx = ex - ox;
+        let dy = ey - oy;
+        let dz = ez - oz;
+        const dlen = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (dlen < 1e-6) {
+            dx = 0;
+            dy = 1;
+            dz = 0;
+        }
+        else {
+            dx /= dlen;
+            dy /= dlen;
+            dz /= dlen;
+        }
+        let ux, uy, uz;
+        if (Math.abs(dy) < 0.99) {
+            ux = dz;
+            uy = 0;
+            uz = -dx;
+        }
+        else {
+            ux = 0;
+            uy = -dz;
+            uz = dy;
+        }
+        const ulen = Math.sqrt(ux * ux + uy * uy + uz * uz) || 1;
+        ux /= ulen;
+        uy /= ulen;
+        uz /= ulen;
+        const vx = dy * uz - dz * uy;
+        const vy = dz * ux - dx * uz;
+        const vz = dx * uy - dy * ux;
+        const r = RAY_THICKNESS;
+        const o0x = ox - r * ux - r * vx, o0y = oy - r * uy - r * vy, o0z = oz - r * uz - r * vz;
+        const o1x = ox + r * ux - r * vx, o1y = oy + r * uy - r * vy, o1z = oz + r * uz - r * vz;
+        const o2x = ox + r * ux + r * vx, o2y = oy + r * uy + r * vy, o2z = oz + r * uz + r * vz;
+        const o3x = ox - r * ux + r * vx, o3y = oy - r * uy + r * vy, o3z = oz - r * uz + r * vz;
+        const e0x = ex - r * ux - r * vx, e0y = ey - r * uy - r * vy, e0z = ez - r * uz - r * vz;
+        const e1x = ex + r * ux - r * vx, e1y = ey + r * uy - r * vy, e1z = ez + r * uz - r * vz;
+        const e2x = ex + r * ux + r * vx, e2y = ey + r * uy + r * vy, e2z = ez + r * uz + r * vz;
+        const e3x = ex - r * ux + r * vx, e3y = ey - r * uy + r * vy, e3z = ez - r * uz + r * vz;
+        const tris = [
+            o0x, o0y, o0z, o1x, o1y, o1z, o2x, o2y, o2z,
+            o0x, o0y, o0z, o2x, o2y, o2z, o3x, o3y, o3z,
+            e0x, e0y, e0z, e2x, e2y, e2z, e1x, e1y, e1z,
+            e0x, e0y, e0z, e3x, e3y, e3z, e2x, e2y, e2z,
+            o0x, o0y, o0z, e0x, e0y, e0z, e1x, e1y, e1z,
+            o0x, o0y, o0z, e1x, e1y, e1z, o1x, o1y, o1z,
+            o1x, o1y, o1z, e1x, e1y, e1z, e2x, e2y, e2z,
+            o1x, o1y, o1z, e2x, e2y, e2z, o2x, o2y, o2z,
+            o2x, o2y, o2z, e2x, e2y, e2z, e3x, e3y, e3z,
+            o2x, o2y, o2z, e3x, e3y, e3z, o3x, o3y, o3z,
+            o3x, o3y, o3z, e3x, e3y, e3z, e0x, e0y, e0z,
+            o3x, o3y, o3z, e0x, e0y, e0z, o0x, o0y, o0z,
+        ];
+        out.set(tris, 0);
+    }
+    render(passEncoder) {
+        if (!this.show || !this.triPipeline || !this.linePipeline)
+            return;
+        if (!this.rayBindGroup || !this.highlightBindGroup)
+            return;
+        if (!this.rayUniformBuffer || !this.highlightUniformBuffer)
+            return;
+        if (!this.rayVertBuffer || !this.cubeVertBuffer)
+            return;
+        rayUniformData.set(this.viewProj, 0);
+        rayUniformData[16] = 0.0;
+        rayUniformData[17] = 1.0;
+        rayUniformData[18] = 1.0;
+        rayUniformData[19] = 0.7;
+        this.device.queue.writeBuffer(this.rayUniformBuffer, 0, rayUniformData);
+        this.buildRayBoxVerts(this.rayOrigin[0], this.rayOrigin[1], this.rayOrigin[2], this.rayEnd[0], this.rayEnd[1], this.rayEnd[2], rayBoxVerts);
+        this.device.queue.writeBuffer(this.rayVertBuffer, 0, rayBoxVerts);
+        highlightUniformData.set(this.viewProj, 0);
+        highlightUniformData[16] = 1.0;
+        highlightUniformData[17] = 0.93;
+        highlightUniformData[18] = 0.0;
+        highlightUniformData[19] = 0.9;
+        this.device.queue.writeBuffer(this.highlightUniformBuffer, 0, highlightUniformData);
+        if (this.hit) {
+            const h = this.hit;
+            const halfExtent = h.scale > 0 ? h.scale : 1;
+            for (let v = 0; v < CUBE_EDGE_VERTS.length; v += 3) {
+                cubeVerts[v] = h.posX + CUBE_EDGE_VERTS[v] * halfExtent;
+                cubeVerts[v + 1] = h.posY + CUBE_EDGE_VERTS[v + 1] * halfExtent;
+                cubeVerts[v + 2] = h.posZ + CUBE_EDGE_VERTS[v + 2] * halfExtent;
+            }
+            this.device.queue.writeBuffer(this.cubeVertBuffer, 0, cubeVerts);
+        }
+        passEncoder.setPipeline(this.triPipeline);
+        passEncoder.setBindGroup(0, this.rayBindGroup);
+        passEncoder.setVertexBuffer(0, this.rayVertBuffer);
+        passEncoder.draw(36);
+        if (this.hit) {
+            passEncoder.setPipeline(this.linePipeline);
+            passEncoder.setBindGroup(0, this.highlightBindGroup);
+            passEncoder.setVertexBuffer(0, this.cubeVertBuffer);
+            passEncoder.draw(24);
+        }
+    }
+    destroy() {
+        this.triPipeline = null;
+        this.linePipeline = null;
+        this.bindGroupLayout = null;
+        this.rayBindGroup = null;
+        this.highlightBindGroup = null;
+        this.rayUniformBuffer?.destroy();
+        this.highlightUniformBuffer?.destroy();
+        this.rayVertBuffer?.destroy();
+        this.cubeVertBuffer?.destroy();
+        this.rayUniformBuffer = null;
+        this.highlightUniformBuffer = null;
+        this.rayVertBuffer = null;
+        this.cubeVertBuffer = null;
+    }
+}

package/dist/modules/devtools/src/debug-store.js

@@ -0,0 +1,28 @@
+import { createStore } from "zustand/vanilla";
+import { subscribeWithSelector } from "zustand/middleware";
+export const useDebugStore = createStore()(subscribeWithSelector((set) => ({
+    showDebugPage: false,
+    toggleDebugPage: () => set((s) => ({ showDebugPage: !s.showDebugPage })),
+    setDebugPage: (show) => set({ showDebugPage: show }),
+    showHitboxes: false,
+    toggleHitboxes: () => set((s) => ({ showHitboxes: !s.showHitboxes })),
+    setShowHitboxes: (show) => set({ showHitboxes: show }),
+    hitboxLineWidth: 3,
+    setHitboxLineWidth: (width) => set({ hitboxLineWidth: Math.max(1, width) }),
+    showLightGizmos: false,
+    toggleLightGizmos: () => set((s) => ({ showLightGizmos: !s.showLightGizmos })),
+    setShowLightGizmos: (show) => set({ showLightGizmos: show }),
+    showRaycast: false,
+    toggleRaycast: () => set((s) => ({ showRaycast: !s.showRaycast })),
+    setShowRaycast: (show) => set({ showRaycast: show }),
+    gcStats: {},
+    updateGCStats: (stats) => set((s) => ({ gcStats: { ...s.gcStats, [stats.label]: stats } })),
+    gcControllerStats: {},
+    updateGCControllerStats: (label, stats) => set((s) => ({ gcControllerStats: { ...s.gcControllerStats, [label]: stats } })),
+    gcConfig: null,
+    setGCConfig: (config) => set((s) => ({ gcConfig: s.gcConfig ? { ...s.gcConfig, ...config } : { ...config } })),
+    collisionLog: [],
+    setCollisionLog: (log) => set({ collisionLog: log }),
+    rendererStats: null,
+    setRendererStats: (stats) => set({ rendererStats: stats }),
+})));

package/dist/modules/devtools/src/debug-view-descriptors.js

@@ -0,0 +1,24 @@
+// ============================================================================
+// Debug View Descriptors — declarative registration of in-game profiler views.
+//
+// Profiling surfaces read these descriptors to know which views to render.
+// The devtools module registers the 10 built-in views; games can register
+// custom views via devtools.registerView().
+//
+// View kinds:
+//   memory, cpu, task-latency, iops-opfs, iops-idb, event-loop,
+//   gc-heap, flame-graph, gpu-passes, warnings
+// ============================================================================
+/** The 10 built-in view descriptors. */
+export const BUILTIN_VIEW_DESCRIPTORS = [
+    { id: "memory", label: "Memory", kind: "memory", icon: "memory", order: 0, tooltip: "Heap usage per worker" },
+    { id: "cpu", label: "CPU", kind: "cpu", icon: "cpu", order: 1, tooltip: "CPU time + frame time per worker" },
+    { id: "task-latency", label: "Task Latency", kind: "task-latency", icon: "latency", order: 2, tooltip: "Task/tick latency percentiles" },
+    { id: "iops-opfs", label: "IOPS: OPFS", kind: "iops-opfs", icon: "disk", order: 3, tooltip: "OPFS I/O operations" },
+    { id: "iops-idb", label: "IOPS: IDB", kind: "iops-idb", icon: "database", order: 4, tooltip: "IndexedDB I/O operations" },
+    { id: "event-loop", label: "Event Loop", kind: "event-loop", icon: "loop", order: 5, tooltip: "rAF jitter, long tasks, idle headroom" },
+    { id: "gc-heap", label: "GC & Heap", kind: "gc-heap", icon: "gc", order: 6, tooltip: "GC pauses, heap over time, snapshot + force-GC" },
+    { id: "flame-graph", label: "Flame Graph", kind: "flame-graph", icon: "flame", order: 7, tooltip: "Puffin-style task latency flame graph" },
+    { id: "gpu-passes", label: "GPU Passes", kind: "gpu-passes", icon: "gpu", order: 8, tooltip: "WebGPU pass timings (render/compute/blit)" },
+    { id: "warnings", label: "Warnings", kind: "warnings", icon: "warning", order: 9, tooltip: "Profiling warnings + auto-trace log" },
+];

package/dist/modules/devtools/src/doctor-panel.js

@@ -0,0 +1,163 @@
+// ============================================================================
+// downdraft doctor — devtools panel for module graph diagnostics
+//
+// Displays the resolved module graph, resource table, system schedule,
+// diagnostics (unresolved requires, version conflicts, leaks), and the
+// cross-thread dependency report (sim + renderer).
+// ============================================================================
+/** Escape untrusted strings before interpolating into innerHTML — mod
+ *  manifests are third-party content and must not be able to inject markup. */
+function esc(s) {
+    return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+export function createDoctorPanelExtension(opts = {}) {
+    return {
+        id: "downdraft-doctor",
+        tabLabel: "Doctor",
+        tabTooltip: "Module graph diagnostics: resolved dependencies, resource table, version conflicts, leak detection",
+        order: 5,
+        html: `
+      <div class="dd-doctor">
+        <div class="dd-doctor__header">
+          <h2>downdraft doctor</h2>
+          <button class="dd-doctor__refresh">Refresh</button>
+        </div>
+        <div class="dd-doctor__summary"></div>
+        <div class="dd-doctor__plugins"></div>
+        <div class="dd-doctor__user-plugins"></div>
+        <div class="dd-doctor__resources"></div>
+        <div class="dd-doctor__issues"></div>
+      </div>
+    `,
+        css: `
+      .dd-doctor { padding: 12px; font-family: monospace; font-size: 12px; color: #ccc; }
+      .dd-doctor h2 { margin: 0 0 8px; font-size: 16px; color: #4fc3f7; }
+      .dd-doctor__header { display: flex; align-items: center; gap: 12px; margin-bottom: 12px; }
+      .dd-doctor__refresh { padding: 4px 12px; background: #333; color: #ccc; border: 1px solid #555; border-radius: 4px; cursor: pointer; }
+      .dd-doctor__refresh:hover { background: #444; }
+      .dd-doctor__summary { margin-bottom: 16px; padding: 8px; background: #1a1a2e; border-radius: 4px; }
+      .dd-doctor__summary div { margin: 2px 0; }
+      .dd-doctor__plugins h3, .dd-doctor__resources h3, .dd-doctor__issues h3, .dd-doctor__user-plugins h3 { color: #4fc3f7; margin: 12px 0 4px; font-size: 13px; }
+      .dd-doctor__badge { display: inline-block; padding: 1px 6px; border-radius: 3px; font-size: 10px; margin-right: 4px; }
+      .dd-doctor__badge--format { background: #2a3a4a; color: #64b5f6; }
+      .dd-doctor__badge--tier { background: #3a2a4a; color: #ce93d8; }
+      .dd-doctor__badge--thread { background: #2a4a3a; color: #81c784; }
+      .dd-doctor__badge--perm { background: #4a3a2a; color: #ffb74d; }
+      .dd-doctor__status--active { color: #81c784; }
+      .dd-doctor__status--error { color: #ef5350; }
+      .dd-doctor__status--loading, .dd-doctor__status--pending { color: #ffb74d; }
+      .dd-doctor__status--disabled { color: #888; }
+      .dd-doctor__table { width: 100%; border-collapse: collapse; margin-bottom: 12px; }
+      .dd-doctor__table th { text-align: left; padding: 4px 8px; background: #1a1a2e; color: #888; font-weight: normal; }
+      .dd-doctor__table td { padding: 4px 8px; border-bottom: 1px solid #222; }
+      .dd-doctor__table .dd-thread-sim { color: #81c784; }
+      .dd-doctor__table .dd-thread-renderer { color: #64b5f6; }
+      .dd-doctor__table .dd-thread-shared { color: #ffb74d; }
+      .dd-doctor__issue { padding: 6px 8px; margin: 4px 0; border-radius: 4px; }
+      .dd-doctor__issue--error { background: #3e1e1e; color: #ef5350; }
+      .dd-doctor__issue--warning { background: #3e3a1e; color: #ffb74d; }
+      .dd-doctor__issue--ok { background: #1e3e2a; color: #81c784; }
+    `,
+        script: `(() => {
+      const helpers = arguments[0];
+      const container = helpers.container;
+      const opts = window.__ddDoctorOpts || {};
+      let refreshTimer = null;
+
+      function render() {
+        const simModules = opts.getSimModules ? opts.getSimModules() : [];
+        const rendererModules = opts.getRendererModules ? opts.getRendererModules() : [];
+        let report = opts.getReport ? opts.getReport() : null;
+        if (!report && (simModules.length || rendererModules.length)) {
+          // Build report inline if no pre-built report provider
+          const { buildCrossThreadReport } = window.__ddCrossThread || {};
+          if (buildCrossThreadReport) {
+            report = buildCrossThreadReport(simModules, rendererModules);
+          }
+        }
+        if (!report) {
+          report = { modules: [...simModules, ...rendererModules], unresolved: [], shared: [], versionConflicts: [] };
+        }
+
+        // Summary
+        const summary = container.querySelector('.dd-doctor__summary');
+        const simCount = report.modules.filter(p => p.thread === 'sim').length;
+        const rendererCount = report.modules.filter(p => p.thread === 'renderer').length;
+        const sharedCount = report.shared.length;
+        const unresolvedCount = report.unresolved.length;
+        const conflictCount = report.versionConflicts.length;
+        summary.innerHTML = [
+          '<div>Sim modules: <b>' + simCount + '</b></div>',
+          '<div>Renderer modules: <b>' + rendererCount + '</b></div>',
+          '<div>Shared resources: <b>' + sharedCount + '</b></div>',
+          '<div>Unresolved requires: <b style="color:' + (unresolvedCount ? '#ef5350' : '#81c784') + '">' + unresolvedCount + '</b></div>',
+          '<div>Version conflicts: <b style="color:' + (conflictCount ? '#ef5350' : '#81c784') + '">' + conflictCount + '</b></div>',
+        ].join('');
+
+        // Modules table
+        const pluginsDiv = container.querySelector('.dd-doctor__plugins');
+        if (report.modules.length === 0) {
+          pluginsDiv.innerHTML = '<h3>Modules</h3><p>No modules registered.</p>';
+        } else {
+          let html = '<h3>Modules (' + report.modules.length + ')</h3>';
+          html += '<table class="dd-doctor__table"><thead><tr><th>Name</th><th>Version</th><th>Thread</th><th>Provides</th><th>Requires</th><th>Status</th></tr></thead><tbody>';
+          for (const p of report.modules) {
+            const threadClass = 'dd-thread-' + esc(p.thread);
+            html += '<tr><td>' + esc(p.name) + '</td><td>' + esc(p.version) + '</td><td class="' + threadClass + '">' + esc(p.thread) + '</td><td>' + esc(p.provides.join(', ') || '—') + '</td><td>' + esc(p.requires.join(', ') || '—') + '</td><td>' + (p.active ? '✓ active' : 'inactive') + '</td></tr>';
+          }
+          html += '</tbody></table>';
+          pluginsDiv.innerHTML = html;
+        }
+
+        // User-authored plugins (modding system)
+        const userPluginsDiv = container.querySelector('.dd-doctor__user-plugins');
+        const plugins = opts.getPlugins ? opts.getPlugins() : [];
+        if (plugins.length === 0) {
+          userPluginsDiv.innerHTML = '';
+        } else {
+          let phtml = '<h3>Plugins (' + plugins.length + ')</h3>';
+          phtml += '<table class="dd-doctor__table"><thead><tr><th>ID</th><th>Version</th><th>Format</th><th>Tier</th><th>Thread</th><th>Permissions</th><th>Status</th></tr></thead><tbody>';
+          for (const p of plugins) {
+            const fmtBadge = '<span class="dd-doctor__badge dd-doctor__badge--format">' + esc(p.format) + '</span>';
+            const tierBadge = '<span class="dd-doctor__badge dd-doctor__badge--tier">' + esc(p.tier) + '</span>';
+            const threadBadge = '<span class="dd-doctor__badge dd-doctor__badge--thread">' + esc(p.thread) + '</span>';
+            const permBadges = p.permissions.map(function(perm) { return '<span class="dd-doctor__badge dd-doctor__badge--perm">' + esc(perm) + '</span>'; }).join('');
+            const statusClass = 'dd-doctor__status--' + esc(p.status);
+            const statusText = esc(p.status + (p.error ? ': ' + p.error : ''));
+            phtml += '<tr><td>' + esc(p.id) + '</td><td>' + esc(p.version) + '</td><td>' + fmtBadge + '</td><td>' + tierBadge + '</td><td>' + threadBadge + '</td><td>' + (permBadges || '—') + '</td><td class="' + statusClass + '">' + statusText + '</td></tr>';
+          }
+          phtml += '</tbody></table>';
+          userPluginsDiv.innerHTML = phtml;
+        }
+
+        // Issues
+        const issuesDiv = container.querySelector('.dd-doctor__issues');
+        let issuesHtml = '<h3>Diagnostics</h3>';
+        if (report.unresolved.length > 0) {
+          issuesHtml += '<div class="dd-doctor__issue dd-doctor__issue--error">Unresolved requires: ' + esc(report.unresolved.join(', ')) + '</div>';
+        }
+        if (report.versionConflicts.length > 0) {
+          for (const vc of report.versionConflicts) {
+            issuesHtml += '<div class="dd-doctor__issue dd-doctor__issue--error">Version conflict: ' + esc(vc.name) + ' (sim=' + esc(vc.simVersion) + ', renderer=' + esc(vc.rendererVersion) + ')</div>';
+          }
+        }
+        if (report.shared.length > 0) {
+          issuesHtml += '<div class="dd-doctor__issue dd-doctor__issue--ok">Shared resources: ' + esc(report.shared.join(', ')) + '</div>';
+        }
+        if (report.unresolved.length === 0 && report.versionConflicts.length === 0) {
+          issuesHtml += '<div class="dd-doctor__issue dd-doctor__issue--ok">✓ No issues detected</div>';
+        }
+        issuesDiv.innerHTML = issuesHtml;
+      }
+
+      container.querySelector('.dd-doctor__refresh').addEventListener('click', render);
+      render();
+
+      return {
+        onActivate() { refreshTimer = setInterval(render, 2000); },
+        onDeactivate() { if (refreshTimer) { clearInterval(refreshTimer); refreshTimer = null; } },
+        onDestroy() { if (refreshTimer) clearInterval(refreshTimer); }
+      };
+    })`,
+    };
+}

package/dist/modules/devtools/src/gizmo-module.js

@@ -0,0 +1,95 @@
+// ============================================================================
+// TransformGizmoModule — RendererModule adapter for TransformGizmo
+//
+// Wires a `TransformGizmo` instance to the renderer plugin system's input bus
+// and render-pass hook. The game creates the gizmo (with device/format and
+// game-specific `onTransformUpdate` callback) and passes it to
+// `createTransformGizmoModule(gizmo)`. The plugin handles:
+//  - pointerdown → hitTest → startDrag (with capture priority so a gizmo drag
+//    blocks the camera controller via stopPropagation)
+//  - pointermove → updateDrag (if dragging)
+//  - pointerup → endDrag
+//  - render-pass hook → gizmo.render(passEncoder, camera)
+// ============================================================================
+/**
+ * Creates a `RendererModule` that wires a `TransformGizmo` to the renderer
+ * plugin system's input bus and render-pass hook.
+ */
+export function createTransformGizmoModule(gizmo, opts = {}) {
+    const capture = opts.captureInput ?? true;
+    const priority = opts.inputPriority ?? 50;
+    let dragging = false;
+    // Cached camera + canvas size from the last render-pass hook, used by
+    // pointer handlers for hitTest/screenToRay.
+    let lastCamera = null;
+    let lastCanvasW = 0;
+    let lastCanvasH = 0;
+    return {
+        name: "devtools:gizmo",
+        version: "0.1.0",
+        register(ctx) {
+            const bus = ctx.getInputBus();
+            const canvas = ctx.getSurface();
+            const onPointerDown = (e, ctrl) => {
+                if (!gizmo.isVisible())
+                    return;
+                if (lastCamera === null)
+                    return;
+                const rect = canvas.getBoundingClientRect();
+                const mx = e.clientX - rect.left;
+                const my = e.clientY - rect.top;
+                const part = gizmo.hitTest(mx, my, lastCanvasW, lastCanvasH, lastCamera);
+                if (part) {
+                    // Get the current transform of the entity being manipulated.
+                    // Falls back to the gizmo's position + identity rotation/scale.
+                    const transform = opts.getTransform
+                        ? opts.getTransform()
+                        : {
+                            position: gizmo.getPosition(),
+                            rotation: [0, 0, 0, 1],
+                            scale: [1, 1, 1],
+                        };
+                    gizmo.startDrag(part, mx, my, lastCanvasW, lastCanvasH, lastCamera, transform);
+                    dragging = true;
+                    if (capture)
+                        ctrl.stopPropagation();
+                }
+            };
+            const onPointerMove = (e, ctrl) => {
+                if (!dragging || !lastCamera)
+                    return;
+                const rect = canvas.getBoundingClientRect();
+                const mx = e.clientX - rect.left;
+                const my = e.clientY - rect.top;
+                gizmo.updateDrag(mx, my, lastCanvasW, lastCanvasH, lastCamera);
+                if (capture)
+                    ctrl.stopPropagation();
+            };
+            const onPointerUp = (_e, _ctrl) => {
+                if (dragging) {
+                    gizmo.endDrag();
+                    dragging = false;
+                }
+            };
+            bus.onPointerDown(onPointerDown, priority);
+            bus.onPointerMove(onPointerMove, priority);
+            bus.onPointerUp(onPointerUp, priority);
+            // Render-pass hook: render the gizmo inside the scene pass and cache
+            // camera/canvas info for the pointer handlers.
+            ctx.onRenderPass((passEncoder, camera, viewportIdx) => {
+                if (viewportIdx !== 0)
+                    return; // gizmo only on first viewport
+                lastCamera = camera;
+                lastCanvasW = canvas.width;
+                lastCanvasH = canvas.height;
+                if (gizmo.isVisible()) {
+                    gizmo.render(passEncoder, camera);
+                }
+            });
+            ctx.onDispose(() => {
+                dragging = false;
+                gizmo.endDrag();
+            });
+        },
+    };
+}