rezi-debug-rendering

name	rezi-debug-rendering
description	Debug rendering and layout issues in Rezi apps. Use when UI looks wrong, has layout problems, or renders unexpectedly.
user-invocable	true
allowed-tools	Read, Glob, Grep, Bash(REZI_PERF=1 *)
argument-hint	[symptom-description]
metadata	{"short-description":"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