Debugging Tools and Techniques

import { debugPanel } from "@rezi-ui/core";

app.view((state) => {
  return ui.column({ gap: 1 }, [
    debugPanel({ position: "top-right" }),  // FPS counter + render stats
    // ... your UI
  ]);
});

type DebugPanelPosition = 
  | "top-left" 
  | "top-right" 
  | "bottom-left" 
  | "bottom-right";

debugPanel({ position: "bottom-left" })

import { createAppWithInspectorOverlay } from "@rezi-ui/core";
import { createNodeBackend } from "@rezi-ui/node";

const backend = await createNodeBackend();
const { app, inspector } = createAppWithInspectorOverlay({
  backend,
  initialState: { count: 0 },
});

// Toggle inspector with F12
app.keys("f12", () => {
  inspector.toggle();
});

// Show/hide inspector
inspector.show();
inspector.hide();
inspector.toggle();

// Check state
if (inspector.isVisible()) {
  console.log("Inspector is active");
}

// Configure
inspector.setOptions({
  showBoundaries: true,
  showMetadata: true,
  highlightFocused: true,
});

import { createNodeApp } from "@rezi-ui/node";
import { exportReproBundleBytes } from "@rezi-ui/core";
import { writeFile } from "fs/promises";

const app = createNodeApp({ 
  initialState: {},
  config: {
    enableRepro: true,  // Enable recording
  },
});

// After running the app
const reproBundle = app.exportReproBundle();
const bytes = exportReproBundleBytes(reproBundle);
await writeFile("session.repro", bytes);

import { parseReproBundleBytes, runReproReplayHarness } from "@rezi-ui/core";
import { readFile } from "fs/promises";

const bytes = await readFile("session.repro");
const bundle = parseReproBundleBytes(bytes);

if (!bundle.ok) {
  console.error("Failed to parse repro bundle:", bundle.error);
  process.exit(1);
}

const result = await runReproReplayHarness({
  bundle: bundle.bundle,
  view: myViewFunction,
  onFrame: (frameNumber, snapshot) => {
    console.log(`Frame ${frameNumber}: ${snapshot.widgets.length} widgets`);
  },
});

if (!result.ok) {
  console.error("Replay failed:", result.fatal || result.mismatch);
}

import { createDebugController } from "@rezi-ui/core";

const debugController = createDebugController({
  categories: ["frame", "event", "perf", "error"],  // What to log
  onRecord: (record) => {
    console.log(`[${record.category}] ${JSON.stringify(record.payload)}`);
  },
});

const app = createNodeApp({ 
  initialState: {},
  config: {
    debugController,  // Attach debug controller
  },
});

import { inspect, debug } from "@rezi-ui/core";

const view = (state) => {
  const tree = ui.column({ gap: 1 }, [
    ui.text("Title"),
    ui.button({ id: "save", label: "Save" }),
  ]);
  
  // Log widget tree structure
  console.log(inspect(tree));
  
  return tree;
};

Column {
  gap: 1,
  children: [
    Text { content: "Title" },
    Button { id: "save", label: "Save" },
  ]
}

import { ui } from "@rezi-ui/core";

ui.errorBoundary({
  id: "main-boundary",
  fallback: (error) => ui.column({ gap: 1, p: 1 }, [
    ui.text("Something went wrong", { style: { fg: "error", bold: true } }),
    ui.text(error.message, { style: { fg: "fg.secondary" } }),
    ui.button({ id: "reload", label: "Reload" }),
  ]),
}, [
  // Protected content
  riskyWidget(state),
])

app.onError((error) => {
  console.error("App error:", error);
  
  // Log to file
  appendFileSync("errors.log", `${new Date().toISOString()} ${error.stack}\n`);
  
  // Show error dialog
  app.update(s => ({
    showErrorDialog: true,
    errorMessage: error.message,
  }));
});

import { createTestRenderer } from "@rezi-ui/core";

const renderer = createTestRenderer({
  width: 80,
  height: 24,
});

const tree = ui.column({ gap: 1 }, [
  ui.text("Hello"),
  ui.text("World"),
]);

const result = renderer.render(tree);

console.log(result.output);  // Rendered text
console.log(result.widgets);  // Widget tree
console.log(result.layout);   // Layout metadata

import { captureSnapshot, serializeSnapshot } from "@rezi-ui/core";

const snapshot = captureSnapshot(tree, { width: 80, height: 24 });
const serialized = serializeSnapshot(snapshot);

// Compare with golden
expect(serialized).toMatchSnapshot();

// Same state + same view = same output (always)
const state = { count: 42 };
const tree = myViewFunction(state);

const output1 = renderer.render(tree);
const output2 = renderer.render(tree);

assert(output1.output === output2.output);  // Always true

const app = createNodeApp({
  initialState: {},
  config: {
    internal_onRender: (metrics) => {
      if (metrics.totalMs > 16.67) {  // Dropped frame at 60 FPS
        console.warn(`Slow frame: ${metrics.totalMs.toFixed(2)}ms`);
        console.log(`  Layout: ${metrics.layoutMs.toFixed(2)}ms`);
        console.log(`  Commit: ${metrics.commitMs.toFixed(2)}ms`);
        console.log(`  Render: ${metrics.renderMs.toFixed(2)}ms`);
      }
    },
  },
});

const app = createNodeApp({
  initialState: {},
  config: {
    internal_onLayout: (snapshot) => {
      console.log(`Laid out ${snapshot.totalWidgets} widgets`);
      console.log(`Dirty widgets: ${snapshot.dirtyWidgets}`);
      console.log(`Layout passes: ${snapshot.passes}`);
    },
  },
});

// ❌ Error: Button requires id
ui.button({ label: "Save" })

// ✅ Fixed
ui.button({ id: "save", label: "Save" })

// ❌ Bad: Creates new object every render
const view = (state) => {
  app.update(s => ({ ...s, timestamp: Date.now() }));  // Infinite loop!
  return ui.text("Hello");
};

// ✅ Fixed: Update in event handler
const view = (state) => {
  return ui.button({ 
    id: "refresh",
    label: "Refresh",
  });
};

app.on("event", (event, state) => {
  if (event.action === "press" && event.id === "refresh") {
    return { timestamp: Date.now() };
  }
});

// ❌ Bad: Conditional hook
const Widget = defineWidget((props, ctx) => {
  if (props.enabled) {
    const value = ctx.useState(0);  // Hook called conditionally!
  }
});

// ✅ Fixed: Unconditional hook
const Widget = defineWidget((props, ctx) => {
  const value = ctx.useState(0);
  
  if (!props.enabled) {
    return ui.text("Disabled");
  }
  
  // Use value...
});