OpenParable
Skip to content
← Back to skills

Rezi Debug Rendering

Testing & Quality
rezi-debug-rendering

Rezi Debug Rendering is an Agent Skill for testing & quality published in the RtlZeroMemory/Rezi repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Debug rendering and layout issues in Rezi apps. Use when UI looks wrong, has layout problems, or renders unexpectedly.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/RtlZeroMemory/Rezi/blob/HEAD/.claude/skills/rezi-debug-rendering/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rezi-debug-rendering, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

SymptomLikely cause
Widget not visibleMissing from VNode tree, or zero width/height
Overlapping widgetsWrong container type (use column/row not box)
Content truncatedFixed width too small, missing flex
Flicker/full re-renderMissing key on list items
Transition not animatingtransition missing, wrong properties, or no actual value delta
Opacity animation looks wrongopacity outside [0..1] (clamped) or properties excludes opacity
Exit animation not visibleMissing exitTransition, zero/invalid duration, or node has no stable key
Exit node still interactiveExit nodes are render-only; focus/hit-test should come from active tree only
Crash on deep treeNesting depth > 500
DS styling not appliedDS styling is automatic with ThemeDefinition; check semantic tokens/theme activation (no dsVariant required)
Wheel scrolling not workingEnsure the container uses overflow: "scroll" and content exceeds viewport size