@downdraft/engine 0.0.0 → 0.1.1

package/modules/devtools/src/debug-raycast.ts

@@ -0,0 +1,328 @@
+// ============================================================================
+// 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";
+import type { IRaycastProvider, IRaycastResult } from "./types";
+
+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 {
+  private device: GPUDevice;
+  private format: GPUTextureFormat;
+  private show = false;
+  private provider: IRaycastProvider | null = null;
+
+  private triPipeline: GPURenderPipeline | null = null;
+  private linePipeline: GPURenderPipeline | null = null;
+  private bindGroupLayout: GPUBindGroupLayout | null = null;
+
+  private rayUniformBuffer: GPUBuffer | null = null;
+  private rayBindGroup: GPUBindGroup | null = null;
+  private highlightUniformBuffer: GPUBuffer | null = null;
+  private highlightBindGroup: GPUBindGroup | null = null;
+
+  private rayVertBuffer: GPUBuffer | null = null;
+  private cubeVertBuffer: GPUBuffer | null = null;
+
+  private viewProj: Float32Array = new Float32Array(16);
+
+  private rayOrigin: [number, number, number] = [0, 0, 0];
+  private rayEnd: [number, number, number] = [0, 0, 0];
+  private hit: IRaycastResult | null = null;
+
+  constructor(device: GPUDevice, format: GPUTextureFormat) {
+    this.device = device;
+    this.format = format;
+  }
+
+  setProvider(provider: IRaycastProvider): void {
+    this.provider = provider;
+  }
+
+  init(): void {
+    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: GPUBlendState = {
+      alpha: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+      color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+    };
+    const depthState: GPUDepthStencilState = {
+      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" as GPUVertexFormat }],
+        },
+      ],
+    };
+    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: boolean): void {
+    this.show = show;
+  }
+
+  isShown(): boolean {
+    return this.show;
+  }
+
+  update(
+    camera: Parameters<typeof calculateViewProj>[0],
+    origin: [number, number, number],
+    direction: [number, number, number],
+  ): void {
+    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;
+    }
+  }
+
+  private buildRayBoxVerts(
+    ox: number, oy: number, oz: number,
+    ex: number, ey: number, ez: number,
+    out: Float32Array,
+  ): void {
+    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: number, uy: number, uz: number;
+    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: GPURenderPassEncoder): void {
+    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(): void {
+    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/modules/devtools/src/debug-store.ts

@@ -0,0 +1,92 @@
+import type { GCControllerConfig, GCControllerStats, GCStats } from "@downdraft/engine";
+import { createStore } from "zustand/vanilla";
+import { subscribeWithSelector } from "zustand/middleware";
+
+export interface CollisionLogEntry {
+  label: string;
+  count: number;
+  lastCollisionTime: number;
+}
+
+interface DebugState {
+  showDebugPage: boolean;
+  toggleDebugPage: () => void;
+  setDebugPage: (show: boolean) => void;
+
+  showHitboxes: boolean;
+  toggleHitboxes: () => void;
+  setShowHitboxes: (show: boolean) => void;
+  hitboxLineWidth: number;
+  setHitboxLineWidth: (width: number) => void;
+
+  showLightGizmos: boolean;
+  toggleLightGizmos: () => void;
+  setShowLightGizmos: (show: boolean) => void;
+
+  showRaycast: boolean;
+  toggleRaycast: () => void;
+  setShowRaycast: (show: boolean) => void;
+
+  gcStats: Record<string, GCStats>;
+  updateGCStats: (stats: GCStats) => void;
+
+  gcControllerStats: Record<string, GCControllerStats>;
+  updateGCControllerStats: (label: string, stats: GCControllerStats) => void;
+  gcConfig: GCControllerConfig | null;
+  setGCConfig: (config: Partial<GCControllerConfig>) => void;
+
+  collisionLog: CollisionLogEntry[];
+  setCollisionLog: (log: CollisionLogEntry[]) => void;
+
+  rendererStats: {
+    fps: number;
+    entityCount: number;
+    playerCount: number;
+    tick: number;
+    canvasW: number;
+    canvasH: number;
+    viewportW: number;
+    viewportH: number;
+    extra: Record<string, any>;
+  } | null;
+  setRendererStats: (stats: DebugState["rendererStats"]) => void;
+}
+
+export const useDebugStore = createStore<DebugState>()(
+  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 } as GCControllerConfig })),
+
+  collisionLog: [],
+  setCollisionLog: (log) => set({ collisionLog: log }),
+
+  rendererStats: null,
+  setRendererStats: (stats) => set({ rendererStats: stats }),
+  })),
+);

package/modules/devtools/src/debug-view-descriptors.ts

@@ -0,0 +1,59 @@
+// ============================================================================
+// 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 kinds. */
+export type BuiltinViewKind =
+  | "memory"
+  | "cpu"
+  | "task-latency"
+  | "iops-opfs"
+  | "iops-idb"
+  | "event-loop"
+  | "gc-heap"
+  | "flame-graph"
+  | "gpu-passes"
+  | "warnings";
+
+/** A view descriptor — describes a panel in the profiler overlay. */
+export interface DebugViewDescriptor {
+  /** Unique id for this view (e.g. "memory", "cpu", "custom:foo"). */
+  id: string;
+  /** Display label shown in the view selector. */
+  label: string;
+  /** The view kind — determines which data source the ProfilerScene reads. */
+  kind: BuiltinViewKind | "custom";
+  /** Icon name (rendered by the ProfilerScene). */
+  icon?: string;
+  /** Order/priority for view placement. Built-in views: 0-100. Default: 100. */
+  order?: number;
+  /** Whether this view is visible by default. Default: true. */
+  visible?: boolean;
+  /** Optional tooltip describing the view. */
+  tooltip?: string;
+  /** For custom views: the scene module URL that renders this view.
+   *  The ProfilerScene dynamically imports it and calls its factory. */
+  customSceneUrl?: string;
+}
+
+/** The 10 built-in view descriptors. */
+export const BUILTIN_VIEW_DESCRIPTORS: DebugViewDescriptor[] = [
+  { 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/modules/devtools/src/doctor-panel.ts

@@ -0,0 +1,182 @@
+// ============================================================================
+// 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).
+// ============================================================================
+
+import type { CrossThreadReport, ModuleThreadInfo, PluginInfo } from "@downdraft/engine";
+import type { IDevToolsPanelExtension } from "./types";
+
+export interface DoctorPanelOptions {
+  /** Snapshot provider for sim-side modules. */
+  getSimModules?: () => ModuleThreadInfo[];
+  /** Snapshot provider for renderer-side modules. */
+  getRendererModules?: () => ModuleThreadInfo[];
+  /** Snapshot provider for the cross-thread report (pre-built). */
+  getReport?: () => CrossThreadReport | null;
+  /** Snapshot provider for user-authored plugins (the modding system). */
+  getPlugins?: () => PluginInfo[];
+}
+
+/** Escape untrusted strings before interpolating into innerHTML — mod
+ *  manifests are third-party content and must not be able to inject markup. */
+function esc(s: unknown): string {
+  return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+export function createDoctorPanelExtension(opts: DoctorPanelOptions = {}): IDevToolsPanelExtension {
+  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); }
+      };
+    })`,
+  };
+}