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**: ```bash 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**: ```typescript 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 |