Add performance timing metrics for React reconciliation and ImGui rendering

Implement comprehensive performance monitoring system that measures and displays timing statistics:

**JavaScript Measurements:**

1. React Reconciliation (lib/react-imgui-reconciler/):
   - Measure in host-config.js prepareForCommit → resetAfterCommit
   - Captures actual reconciliation work (component execution + React diffing + commit)
   - Calculate statistics in perf-stats.js:
     * Moving average from last 30 samples
     * Time-windowed max (last 5 seconds)
   - Module-scope variables for efficiency

2. ImGui Rendering (lib/imgui-unit/renderer.js):
   - Measure tree traversal and ImGui FFI calls
   - Runs every frame
   - Export timing via globalThis.perfMetrics

**C++ Display (lib/imgui-runtime/imgui-runtime.cpp):**
- Read metrics from JavaScript globalThis in update_performance_metrics()
- Calculate EMA for ImGui render time (α=0.1)
- Update display values once per second (prevents blurring)
- Render with Sokol Debug Text at bottom-left corner:
  * FPS: 60
  * ImGui: 850us (EMA, per frame)
  * React: 120/235us (avg/max in microseconds)

**CLAUDE.md Updates:**
- Add development workflow rule: Do not commit before user review and testing

Author: tmikov

CLAUDE.md

@@ -11,6 +11,18 @@ When modifying the project structure, build system, architecture, or implementat
 
 Always update CLAUDE.md as part of your work - do not defer documentation updates.
 
+## IMPORTANT: Development Workflow
+
+**⚠️ DO NOT COMMIT CODE BEFORE USER REVIEW AND TESTING**
+
+When implementing changes:
+1. Write and test the code
+2. Wait for the user to review the changes
+3. Wait for the user to test the implementation
+4. Only commit after explicit user approval
+
+Never commit code immediately after implementation. The user must review and test first.
+
 ## Project Overview
 
 This project implements a custom React reconciler that renders to DearImGUI using Static Hermes. The goal is to use React's declarative component model and JSX syntax to describe ImGUI interfaces, while learning how React works internally.

lib/imgui-runtime/imgui-runtime.cpp

@@ -103,6 +103,15 @@ static uint64_t s_start_time = 0;
 static uint64_t s_last_fps_time = 0;
 static double s_fps = 0;
 
+// Performance metrics
+static double s_react_avg_ms = 0;              // React reconciliation average (accumulated)
+static double s_react_max_ms = 0;              // React reconciliation max (accumulated)
+static double s_imgui_avg_ms = 0;              // ImGui render average (EMA, accumulated)
+static double s_react_avg_ms_display = 0;      // React avg (displayed, updated once/sec)
+static double s_react_max_ms_display = 0;      // React max (displayed, updated once/sec)
+static double s_imgui_avg_ms_display = 0;      // ImGui render average (displayed, updated once/sec)
+
+
 extern "C" int load_image(const char *path) {
   s_images.emplace_back(std::make_unique<Image>(path));
   return s_images.size() - 1;
@@ -192,6 +201,34 @@ static void app_event(const sapp_event *ev) {
 static float s_bg_color[4] = {0.0f, 0.0f, 0.0f, 0.0f};
 extern "C" float *get_bg_color() { return s_bg_color; }
 
+static void update_performance_metrics() {
+  // Read performance metrics from JavaScript
+  try {
+    auto global = s_hermesApp->hermes->global();
+
+    if (global.hasProperty(*s_hermesApp->hermes, "perfMetrics")) {
+      auto metrics = global.getPropertyAsObject(*s_hermesApp->hermes, "perfMetrics");
+
+      // Read React reconciliation stats (calculated in JS)
+      if (metrics.hasProperty(*s_hermesApp->hermes, "reconciliationAvg")) {
+        s_react_avg_ms = metrics.getProperty(*s_hermesApp->hermes, "reconciliationAvg").asNumber();
+      }
+      if (metrics.hasProperty(*s_hermesApp->hermes, "reconciliationMax")) {
+        s_react_max_ms = metrics.getProperty(*s_hermesApp->hermes, "reconciliationMax").asNumber();
+      }
+
+      // Read and calculate EMA for ImGui render time (every frame)
+      if (metrics.hasProperty(*s_hermesApp->hermes, "renderTime")) {
+        double renderTime = metrics.getProperty(*s_hermesApp->hermes, "renderTime").asNumber();
+        const double alpha = 0.1;  // Smoothing factor
+        s_imgui_avg_ms = s_imgui_avg_ms * (1.0 - alpha) + renderTime * alpha;
+      }
+    }
+  } catch (...) {
+    // Ignore errors reading metrics
+  }
+}
+
 static void app_frame() {
   uint64_t now = stm_now();
   double curTimeMs = stm_ms(now);
@@ -201,10 +238,13 @@ static void app_frame() {
     s_start_time = now;
     s_last_fps_time = now;
   } else {
-    // Update FPS every second
+    // Update FPS and displayed performance metrics every second
     uint64_t diff = stm_diff(now, s_last_fps_time);
     if (diff > 1000000000) {
-      s_fps = 1.0 / sapp_frame_duration(); // stm_sec(diff);
+      s_fps = 1.0 / sapp_frame_duration();
+      s_imgui_avg_ms_display = s_imgui_avg_ms;  // Update displayed value
+      s_react_avg_ms_display = s_react_avg_ms;  // Update displayed value
+      s_react_max_ms_display = s_react_max_ms;  // Update displayed value
       s_last_fps_time = now;
     }
   }
@@ -247,9 +287,24 @@ static void app_frame() {
     slog_func("ERROR", 1, 0, e.what(), __LINE__, __FILE__, nullptr);
   }
 
+  update_performance_metrics();
+
   simgui_render();
   sdtx_canvas((float)sapp_width(), (float)sapp_height());
-  sdtx_printf("FPS: %d", (int)(s_fps + 0.5));
+
+  // Position at bottom-left corner
+  // Each character is 8x8 pixels, calculate rows from bottom
+  int num_rows = (int)sapp_height() / 8;
+  int num_lines = s_react_avg_ms_display > 0 ? 3 : 2;  // FPS + ImGui [+ React]
+  sdtx_pos(0.0f, (float)(num_rows - num_lines));
+
+  sdtx_printf("FPS: %d\n", (int)(s_fps + 0.5));
+  sdtx_printf("ImGui: %dus\n", (int)(s_imgui_avg_ms_display * 1000.0 + 0.5));
+  if (s_react_avg_ms_display > 0) {
+    sdtx_printf("React: %d/%dus",
+                (int)(s_react_avg_ms_display * 1000.0 + 0.5),
+                (int)(s_react_max_ms_display * 1000.0 + 0.5));
+  }
   sdtx_draw();
   sg_end_pass();
   sg_commit();

lib/imgui-unit/renderer.js

@@ -709,6 +709,8 @@ function renderNode(node: any): void {
 // Export render function
 globalThis.imguiUnit = {
   renderTree: function(): void {
+    const startTime = globalThis.performance.now();
+
     const reactApp = globalThis.reactApp;
     if (reactApp && reactApp.rootChildren) {
       // Validate that only one root component exists
@@ -728,6 +730,14 @@ globalThis.imguiUnit = {
         renderNode(reactApp.rootChildren[i]);
       }
     }
+
+    const duration = globalThis.performance.now() - startTime;
+
+    // Store for C++ to read
+    if (!globalThis.perfMetrics) {
+      globalThis.perfMetrics = {};
+    }
+    globalThis.perfMetrics.renderTime = duration;
   },
 
   onTreeUpdate: function(): void {

lib/react-imgui-reconciler/host-config.js

@@ -3,9 +3,13 @@
 // See LICENSE file for full license text
 
 import { TreeNode, TextNode } from './tree-node.js';
+import { updateReconciliationStats } from './perf-stats.js';
 
 // React host config loaded
 
+// Timing for reconciliation
+let reconciliationStartTime = 0;
+
 /**
  * Host Config for React Reconciler
  *
@@ -351,6 +355,7 @@ const hostConfig = {
    * @returns null (we don't need to track anything)
    */
   prepareForCommit(containerInfo) {
+    reconciliationStartTime = performance.now();
     return null;
   },
 
@@ -360,6 +365,14 @@ const hostConfig = {
    * This syncs our tree to globalThis so the ImGui renderer can access it.
    */
   resetAfterCommit(containerInfo) {
+    // Measure reconciliation time
+    if (reconciliationStartTime > 0) {
+      const duration = performance.now() - reconciliationStartTime;
+      // console.log(`Reconciliation took ${duration.toFixed(3)}ms`);
+      updateReconciliationStats(duration);
+      reconciliationStartTime = 0;
+    }
+
     // Update global reference after every reconciliation
     if (globalThis.reactApp) {
       globalThis.reactApp.rootChildren = containerInfo.rootChildren || [];

lib/react-imgui-reconciler/perf-stats.js

@@ -0,0 +1,52 @@
+// Copyright (c) Tzvetan Mikov and contributors
+// SPDX-License-Identifier: MIT
+// See LICENSE file for full license text
+
+// Reconciliation timing statistics - module scope for efficiency
+const RECONCILIATION_SAMPLE_SIZE = 30;
+const MAX_WINDOW_SECONDS = 5;
+
+let reconciliationSamples = [];  // Array of {time: timestamp, duration: ms}
+let reconciliationAverage = 0;
+let reconciliationMax = 0;
+
+/**
+ * Update reconciliation timing statistics.
+ * Maintains a moving average of the last N samples and a time-windowed max.
+ */
+export function updateReconciliationStats(duration) {
+  const now = performance.now();
+
+  // Add new sample
+  reconciliationSamples.push({ time: now, duration });
+
+  // Keep only last N samples for average
+  if (reconciliationSamples.length > RECONCILIATION_SAMPLE_SIZE) {
+    reconciliationSamples.shift();
+  }
+
+  // Calculate average from all samples
+  let sum = 0;
+  for (let i = 0; i < reconciliationSamples.length; i++) {
+    sum += reconciliationSamples[i].duration;
+  }
+  reconciliationAverage = sum / reconciliationSamples.length;
+
+  // Calculate max from samples within time window
+  const cutoffTime = now - (MAX_WINDOW_SECONDS * 1000);
+  reconciliationMax = 0;
+  for (let i = 0; i < reconciliationSamples.length; i++) {
+    if (reconciliationSamples[i].time >= cutoffTime) {
+      if (reconciliationSamples[i].duration > reconciliationMax) {
+        reconciliationMax = reconciliationSamples[i].duration;
+      }
+    }
+  }
+
+  // Expose to globalThis for C++ access
+  if (!globalThis.perfMetrics) {
+    globalThis.perfMetrics = {};
+  }
+  globalThis.perfMetrics.reconciliationAvg = reconciliationAverage;
+  globalThis.perfMetrics.reconciliationMax = reconciliationMax;
+}