@downdraft/engine 0.3.0 → 0.3.1

package/modules/devtools/src/doctor-panel.ts

@@ -1,182 +0,0 @@
-// ============================================================================
-// 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); }
-      };
-    })`,
-  };
-}

package/modules/devtools/src/label-overlay.ts

@@ -1,154 +0,0 @@
-// ============================================================================
-// LabelOverlay — HTML-based billboard labels for dev mode
-// Generic DOM management + projection; game provides labels via ILabelProvider.
-// ============================================================================
-
-import { calculateViewProj, type RenderSurface } from "@downdraft/engine";
-import type { ILabelProvider } from "./types";
-
-interface LabelEntry {
-  el: HTMLDivElement;
-}
-
-const MAX_LABELS = 512;
-
-export class LabelOverlay {
-  private container: HTMLDivElement;
-  private labels: Map<string, LabelEntry> = new Map();
-  private active = false;
-  private canvas: HTMLCanvasElement;
-  private provider: ILabelProvider | null = null;
-
-  constructor(surface: RenderSurface) {
-    // DOM-overlay widget — the canvas/element members it touches
-    // (parentElement, 2d overlay canvas) are DOM-host concepts; on native
-    // they degrade to the compat stubs (display:none anyway).
-    const canvas = surface as unknown as HTMLCanvasElement;
-    this.canvas = canvas;
-    this.container = document.createElement("div");
-    this.container.className = "label-overlay";
-    this.container.style.cssText = `
-      position: absolute;
-      top: 0; left: 0;
-      width: 100%; height: 100%;
-      pointer-events: none;
-      overflow: hidden;
-      z-index: 0;
-      display: none;
-    `;
-    const parent = canvas.parentElement;
-    if (parent) {
-      parent.style.position = parent.style.position || "relative";
-      parent.appendChild(this.container);
-    } else {
-      document.body.appendChild(this.container);
-    }
-  }
-
-  setProvider(provider: ILabelProvider): void {
-    this.provider = provider;
-  }
-
-  setActive(active: boolean): void {
-    this.active = active;
-    this.container.style.display = active ? "block" : "none";
-    if (!active) {
-      this.clearLabels();
-    }
-  }
-
-  isActive(): boolean {
-    return this.active;
-  }
-
-  private clearLabels(): void {
-    for (const entry of this.labels.values()) {
-      entry.el.remove();
-    }
-    this.labels.clear();
-  }
-
-  private getOrCreateLabel(key: string): HTMLDivElement | null {
-    let entry = this.labels.get(key);
-    if (entry) return entry.el;
-
-    if (this.labels.size >= MAX_LABELS) return null;
-
-    const el = document.createElement("div");
-    el.className = "dev-label";
-    el.style.cssText = `
-      position: absolute;
-      font-family: monospace;
-      font-size: 11px;
-      color: #fff;
-      background: rgba(0, 0, 0, 0.65);
-      border-radius: 3px;
-      padding: 1px 5px;
-      white-space: nowrap;
-      pointer-events: none;
-      transform: translate(-50%, -100%);
-      will-change: transform, left, top;
-      border: 1px solid rgba(255, 255, 255, 0.15);
-    `;
-    this.container.appendChild(el);
-    this.labels.set(key, { el });
-    return el;
-  }
-
-  private projectToScreen(
-    worldX: number, worldY: number, worldZ: number,
-    viewProj: Float32Array,
-    canvasW: number, canvasH: number,
-  ): { x: number; y: number; behind: boolean } | null {
-    const x = viewProj[0] * worldX + viewProj[4] * worldY + viewProj[8] * worldZ + viewProj[12];
-    const y = viewProj[1] * worldX + viewProj[5] * worldY + viewProj[9] * worldZ + viewProj[13];
-    const w = viewProj[3] * worldX + viewProj[7] * worldY + viewProj[11] * worldZ + viewProj[15];
-
-    if (w <= 0) return { x: 0, y: 0, behind: true };
-
-    const ndcX = x / w;
-    const ndcY = y / w;
-
-    const screenX = (ndcX + 1) * 0.5 * canvasW;
-    const screenY = (1 - ndcY) * 0.5 * canvasH;
-
-    return { x: screenX, y: screenY, behind: false };
-  }
-
-  update(camera: Parameters<typeof calculateViewProj>[0]): void {
-    if (!this.active || !this.provider) return;
-
-    const viewProj = calculateViewProj(camera);
-    const canvasW = this.canvas.clientWidth;
-    const canvasH = this.canvas.clientHeight;
-
-    const labels = this.provider.getLabels();
-    const usedKeys = new Set<string>();
-
-    for (let _i = 0, _it = labels, _n = _it.length; _i < _n; _i++) { const label = _it[_i];
-      usedKeys.add(label.key);
-      const proj = this.projectToScreen(label.x, label.y, label.z, viewProj, canvasW, canvasH);
-      if (!proj || proj.behind) continue;
-
-      const el = this.getOrCreateLabel(label.key);
-      if (!el) continue;
-
-      el.textContent = label.text;
-      el.style.left = `${proj.x}px`;
-      el.style.top = `${proj.y}px`;
-      el.style.color = label.color;
-      el.style.display = "block";
-    }
-
-    for (const [key, entry] of this.labels.entries()) {
-      if (!usedKeys.has(key)) {
-        entry.el.style.display = "none";
-      }
-    }
-  }
-
-  destroy(): void {
-    this.clearLabels();
-    this.container.remove();
-  }
-}

package/modules/devtools/src/material-stats-panel.ts

@@ -1,188 +0,0 @@
-// ============================================================================
-// createMaterialStatsPanelExtension — reusable DevTools "Materials" tab for
-// any game using the unified material system.
-//
-// Shows:
-//   - Registered material count, material types breakdown
-//   - Variant cache size, LRU hits/misses
-//   - Shader graph node count, compiled WGSL size
-//   - GPU texture count/bytes (from GPUResourceTracker)
-//
-// Gated by requiredMethods: ["getMaterialStats"]. The framework auto-provides
-// getMaterialStats() from the renderer's MaterialLibrary / variant cache
-// (feature-detected in createDevToolsRendererAdapter or registered via
-// devtools.registerDataFeed).
-// ============================================================================
-
-import type { IDevToolsPanelExtension } from "./types";
-
-export interface MaterialStatsPanelOptions {
-  tabLabel?: string;
-  tabTooltip?: string;
-  order?: number;
-  /** Optional callback to append custom rows to the stats grid. */
-  extraRows?: (stats: any) => [string, string][];
-}
-
-export function createMaterialStatsPanelExtension(
-  opts: MaterialStatsPanelOptions = {},
-): IDevToolsPanelExtension {
-  const tabLabel = opts.tabLabel ?? "Materials";
-  const tabTooltip = opts.tabTooltip ?? "Material system stats (library, variants, GPU textures)";
-  const order = opts.order ?? 25;
-  const hasExtra = typeof opts.extraRows === "function";
-  const extraRowsSrc = hasExtra ? opts.extraRows!.toString() : "null";
-
-  const html = `
-<div class="panel-header">
-  <h3>Materials</h3>
-  <span id="mat-status-badge" class="perf-status">Waiting for data...</span>
-</div>
-<div id="mat-stats-panel">
-  <div class="debug-section">
-    <h4>Library</h4>
-    <div id="mat-library-grid" class="debug-grid"></div>
-  </div>
-  <div class="debug-section">
-    <h4>Variants</h4>
-    <div id="mat-variants-grid" class="debug-grid"></div>
-  </div>
-  <div class="debug-section">
-    <h4>GPU Textures</h4>
-    <div id="mat-textures-grid" class="debug-grid"></div>
-  </div>
-  <div class="debug-section">
-    <h4>Shader Graph</h4>
-    <div id="mat-graph-grid" class="debug-grid"></div>
-  </div>
-</div>
-`;
-
-  const css = `
-#mat-stats-panel {
-  flex: 1;
-  overflow-y: auto;
-  padding: 8px 12px;
-}
-#mat-stats-panel .debug-section {
-  margin-bottom: 12px;
-}
-#mat-stats-panel .debug-section h4 {
-  font-size: 12px;
-  color: #569cd6;
-  margin: 8px 0 4px 0;
-  border-bottom: 1px solid #333;
-  padding-bottom: 2px;
-}
-#mat-status-badge.running { color: #98c379; }
-#mat-status-badge.empty { color: #e5c07b; }
-`;
-
-  const script = `
-(function(DevToolsPanel) {
-  var callInspector = DevToolsPanel.callInspector;
-  var evalInPage = DevToolsPanel.evalInPage;
-  var escapeHtml = DevToolsPanel.escapeHtml;
-  var fmtVal = DevToolsPanel.fmtVal;
-  var debugGridHtml = DevToolsPanel.debugGridHtml;
-
-  var extraRowsFn = ${extraRowsSrc};
-
-  function refreshMatStats() {
-    var libEl = document.getElementById("mat-library-grid");
-    var varEl = document.getElementById("mat-variants-grid");
-    var texEl = document.getElementById("mat-textures-grid");
-    var graphEl = document.getElementById("mat-graph-grid");
-    var statusEl = document.getElementById("mat-status-badge");
-
-    evalInPage(
-      "window.__sceneInspector ? JSON.stringify(window.__sceneInspector.getMaterialStats()) : null",
-      function (result, err) {
-        if (err || !result) {
-          if (libEl) libEl.innerHTML = '<div class="debug-label">Not available</div>';
-          if (statusEl) { statusEl.textContent = "Not available"; statusEl.className = "perf-status"; }
-          return;
-        }
-        try {
-          var s = JSON.parse(result);
-          if (!s) {
-            if (libEl) libEl.innerHTML = '<div class="debug-label">Not available</div>';
-            return;
-          }
-
-          // Library stats
-          var libRows = [
-            ["Registered", s.library?.count ?? 0],
-            ["Types", s.library?.types?.join(", ") ?? "—"],
-          ];
-          if (libEl) libEl.innerHTML = debugGridHtml(libRows);
-
-          // Variant stats
-          var varRows = [
-            ["Cached Pipelines", s.variants?.cachedPipelines ?? 0],
-            ["Max Pipelines", s.variants?.maxPipelines ?? 0],
-            ["LRU Hits", s.variants?.lruHits ?? 0],
-            ["LRU Misses", s.variants?.lruMisses ?? 0],
-            ["Permutation Count", s.variants?.permutationCount ?? 0],
-          ];
-          if (varEl) varEl.innerHTML = debugGridHtml(varRows);
-
-          // GPU textures
-          var texRows = [
-            ["Texture Count", s.textures?.count ?? 0],
-            ["Texture Memory", fmtVal((s.textures?.bytes ?? 0) / 1048576, 1) + " MB"],
-            ["Bindless Entries", s.textures?.bindlessEntries ?? 0],
-          ];
-          if (texEl) texEl.innerHTML = debugGridHtml(texRows);
-
-          // Shader graph
-          var graphRows = [
-            ["Graph Materials", s.graph?.materialCount ?? 0],
-            ["Total Nodes", s.graph?.totalNodes ?? 0],
-            ["Total Connections", s.graph?.totalConnections ?? 0],
-            ["Compiled WGSL Size", fmtVal((s.graph?.compiledWgslBytes ?? 0) / 1024, 1) + " KB"],
-          ];
-          if (graphEl) graphEl.innerHTML = debugGridHtml(graphRows);
-
-          // Extra rows
-          if (extraRowsFn && s) {
-            try {
-              var extra = extraRowsFn(s);
-              if (extra && extra.length) {
-                var extraHtml = debugGridHtml(extra);
-                if (graphEl) graphEl.innerHTML += extraHtml;
-              }
-            } catch (e) { /* ignore */ }
-          }
-
-          if (statusEl) {
-            var count = s.library?.count ?? 0;
-            statusEl.textContent = count > 0 ? count + " materials" : "No materials";
-            statusEl.className = "perf-status " + (count > 0 ? "running" : "empty");
-          }
-        } catch (e) {
-          if (libEl) libEl.innerHTML = '<div class="debug-label">Error: ' + escapeHtml(String(e)) + '</div>';
-        }
-      }
-    );
-  }
-
-  return {
-    onActivate: function () { refreshMatStats(); },
-    onRefresh: refreshMatStats,
-    onDeactivate: function () {},
-  };
-})
-`;
-
-  return {
-    id: "material-stats",
-    tabLabel,
-    tabTooltip,
-    order,
-    requiredMethods: ["getMaterialStats"],
-    html,
-    css,
-    script,
-  };
-}