rtlzeromemory/rezi-debug-rendering

When to use

Use this skill when:

• UI does not look right or has layout problems
• Widgets overlap, disappear, or have wrong dimensions
• Unexpected re-renders or flicker
• Performance issues during rendering

Source of truth

• packages/core/src/app/widgetRenderer.ts — full render pipeline
• packages/core/src/app/__tests__/widgetRenderer.transition.test.ts — transition behavior expectations
• packages/core/src/runtime/commit.ts — VNode → RuntimeInstance tree
• packages/core/src/layout/ — layout engine
• packages/core/src/renderer/renderToDrawlist/ — draw operations
• packages/core/src/widgets/composition.ts — animation hook implementations
• packages/core/src/ui/ — design tokens, recipes, and capability tiers

Debugging steps

1. Enable profiling:

   REZI_PERF=1 REZI_PERF_DETAIL=1 node your-app.js
   

2. Check VNode tree structure — ensure no missing children or null nodes

3. Check widget IDs — must be unique across the entire tree. Duplicate IDs cause unpredictable behavior

4. Check nesting depth:

   • Warning at 200 levels
   • Fatal at 500 levels
   • Flatten unnecessary wrapper nodes

5. Check key props on list items — missing keys cause full re-render and lost state

6. Inspect with test renderer:

   const r = createTestRenderer({ viewport: { cols: 80, rows: 24 } });
   const result = r.render(myView(state));
   console.log(result.toText());  // see actual output
   result.findById("my-widget");  // locate specific nodes
   

7. Review layout props: width, height, flex, p, gap, align

8. If animation is involved, verify:

   • container widgets (ui.box, ui.row, ui.column, ui.grid) use transition with expected properties (position, size, opacity)
   • properties: [] is not accidentally disabling tracks
   • opacity stays within [0..1]
   • exitTransition exists on nodes that should animate out before removal
   • keyed re-entry behavior is intentional (same key cancels in-flight exit)
   • exiting nodes are expected to be render-only (not focusable/hit-testable)
   • animation hooks are not conditionally called

9. Read enriched runtime errors carefully:

   • ZRUI_DUPLICATE_ID now includes both conflicting widget kinds + ctx.id() guidance
   • ZRUI_DUPLICATE_KEY includes the duplicate key and parent context
   • ZRUI_INVALID_PROPS includes prop name, widget kind, and expected type
   • ZRUI_UPDATE_DURING_RENDER includes guidance to move updates into event handlers/effects

Common causes

| Symptom | Likely cause | |---------|-------------| | Widget not visible | Missing from VNode tree, or zero width/height | | Overlapping widgets | Wrong container type (use column/row not box) | | Content truncated | Fixed width too small, missing flex | | Flicker/full re-render | Missing key on list items | | Transition not animating | transition missing, wrong properties, or no actual value delta | | Opacity animation looks wrong | opacity outside [0..1] (clamped) or properties excludes opacity | | Exit animation not visible | Missing exitTransition, zero/invalid duration, or node has no stable key | | Exit node still interactive | Exit nodes are render-only; focus/hit-test should come from active tree only | | Crash on deep tree | Nesting depth > 500 | | DS styling not applied | DS styling is automatic with ThemeDefinition; check semantic tokens/theme activation (no dsVariant required) | | Wheel scrolling not working | Ensure the container uses overflow: "scroll" and content exceeds viewport size |