/makepad-2.0-troubleshooting

name: makepad-2.0-troubleshooting
description: |
  CRITICAL: Use for Makepad 2.0 troubleshooting and common mistakes. Triggers on:
  makepad error, makepad bug, makepad problem, makepad issue, makepad not working,
  text invisible, widget not showing, click not working, height zero,
  makepad pitfall, makepad gotcha, makepad FAQ, makepad help,
  script_mod error, compile error, widget not found, render not updating,
  hot reload not working, wasm build error, port conflict, server lock,
  IME popup, selection handle, popup window crash,
  canvas splash, POST splash loop, 100% CPU, set_visible not working,
  on_render empty, event bridge unreliable, float time display,
  fn tick not called, on_audio not called, button click through,
  常见错误, 问题排查, 故障排除, 不显示, 不工作, 看不见, 热重载, 编译错误

Makepad 2.0 Common Pitfalls & Troubleshooting Guide

This skill covers common mistakes when building with Makepad 2.0 and the Splash scripting language. Each pitfall includes:

• What the user sees (symptom)
• Why it happens (root cause)
• How to fix it (correct code)

Reference documents: `AGENTS.md`, `splash.md`

---

Pitfall #1: Container height is 0px -- UI is invisible

**Symptom:** Your entire UI or a section of it does not appear. The container renders with zero height, making all children invisible.

**Root Cause:** All View-based containers (`View`, `SolidView`, `RoundedView`, etc.) default to `height: Fill`. When a `Fill` container is placed inside a `Fit` parent (or any context where the available height is determined by children), the height resolves to 0px due to circular dependency: the parent asks the child how tall it is, the child says "as tall as my parent", and the result is zero.

**Fix:** Always set `height: Fit` on containers that should shrink-wrap their content.

// WRONG -- height defaults to Fill, resolves to 0px in a Fit context
View{
    flow: Down
    Label{text: "Hello"}
}

// CORRECT -- height: Fit makes the container wrap its children
View{
    height: Fit
    flow: Down
    Label{text: "Hello"}
}

**Rule of thumb:** Write `height: Fit` immediately after the opening brace of every container unless you have a fixed-height parent or you explicitly want `height: Fill` inside a known fixed-size ancestor.

**Exception:** Inside a fixed-height parent, `height: Fill` is valid:

View{
    height: 300
    View{
        height: Fill
        Label{text: "I fill the 300px"}
    }
}

---

Pitfall #2: Text invisible on colored background -- missing new_batch

**Symptom:** You add a `Label` inside a `RoundedView` or `SolidView` with a background color, but the text is invisible. The container appears correctly colored but the text cannot be seen, even though `draw_text.color` is set to a contrasting color.

**Root Cause:** Makepad batches draw calls by shader type for GPU performance. All `Label` widgets using the same text shader get batched into one draw call, and all backgrounds into another. Without `new_batch: true`, the text draw call may execute *before* the background draw call, placing the text geometrically behind the opaque background.

**Fix:** Add `new_batch: true` to any View-based container that has a visible background (`show_bg: true` or pre-styled views like `SolidView`, `RoundedView`) and contains text children.

// WRONG -- text is drawn behind the background due to batching
RoundedView{
    height: Fit
    draw_bg.color: #333
    Label{text: "Can't see me"}
}

// CORRECT -- new_batch forces background to draw before children's text
RoundedView{
    height: Fit
    new_batch: true
    draw_bg.color: #333
    Label{text: "Now visible" draw_text.color: #fff}
}

**When you MUST use `new_batch: true`:**

• Any container with `show_bg: true` (or pre-styled like `SolidView`, `RoundedView`) that contains text
• Hoverable items with background animator -- text disappears on hover without it
• Parent containers of repeated items that each have their own background

---

Pitfall #3: Named child override does not work -- used `:` instead of `:=`

**Symptom:** You define a template with `let` and try to override a child property per-instance, but the override is silently ignored. The default text always shows.

**Root Cause:** In Splash, `:` creates a **static** property, while `:=` creates a **named/dynamic** child that is addressable and overridable. If you declare `label: Label{...}` (with `:`), the child has no addressable name and the override path `label.text:` cannot find it.

**Fix:** Use `:=` for any child you want to reference or override later.

// WRONG -- static child, override fails silently
let Card = View{
    height: Fit
    title: Label{text: "default"}
}
Card{title.text: "new text"}  // Fails! title is not addressable

// CORRECT -- named child with :=, override works
let Card = View{
    height: Fit
    title := Label{text: "default"}
}
Card{title.text: "new text"}  // Works! title is a named child

**Additional rule:** Named children inside anonymous containers are UNREACHABLE. Every container in the path from root to child must also be named:

// WRONG -- label is inside an anonymous View, unreachable
let Item = View{
    height: Fit
    View{
        flow: Down
        label := Label{text: "default"}
    }
}
Item{label.text: "new"}  // Fails! No path to label through anonymous View

// CORRECT -- full named path
let Item = View{
    height: Fit
    texts := View{
        flow: Down
        label := Label{text: "default"}
    }
}
Item{texts.label.text: "new"}  // Works! Full dot-path through named containers

---

Pitfall #4: Hex color with letter 'e' renders wrong or causes parse error

**Symptom:** A hex color like `#2ecc71` causes a cryptic parse error such as `expected at least one digit in exponent`, or the color renders incorrectly.

**Root Cause:** The Rust tokenizer inside `script_mod!{}` interprets a digit followed by `e` as the start of a scientific notation number (e.g., `2e` looks like `2 * 10^...`)