Layout Inspector

Debug GPUI layout issues by combining visual probes, computed layout dumps, and automated invariant checks. Use this when elements disappear, get clipped, or have wrong sizes.

Quick Diagnosis Flow

When an element is missing or not rendering:

1. •Add a debug probe — bright-colored div to test if the container is working
2. •Build and capture — screenshot to check if probe is visible
3. •Read the screenshot — visually confirm what rendered
4. •Interpret results — probe visible = container works, element is the problem; probe invisible = container/parent is broken

Debug Probe Pattern

Add a brightly colored div near the suspected problem area:

// Add AFTER the suspected missing element
.child(div().h(px(50.)).w_full().bg(gpui::red()))

// Add BEFORE to test if parent is rendering children at all
.child(div().h(px(50.)).w_full().bg(gpui::blue()))

Remove debug probes after diagnosis. They are not meant to be committed.

Interpreting Probe Results

Common Flex Layout Failures

"Content eats the column" (most common)

In a flex column with overflow_hidden():

• •Content area refuses to shrink (min-height auto / min-content semantics)
• •It expands to fill the column
• •Fixed-height elements below get pushed past the bottom
• •overflow_hidden() clips them — they "disappear"

Fix: Ensure the expanding content area has .min_h_0() or .min_h(px(0.)) so it can shrink below its content size:

// CORRECT: content can shrink, fixed footer stays visible
div().flex().flex_col().h_full().overflow_hidden()
    .child(
        div().flex_1().min_h_0().overflow_hidden()  // content area shrinks
            .child(scrollable_content)
    )
    .child(fixed_footer)  // always visible at bottom

Canonical "scrollable + fixed" pattern

From render_impl.rs:385:

.child(div().flex_1().w_full().min_h(px(0.)).child(main_content))

Key: flex_1() + min_h(px(0.)) + parent has overflow_hidden().

Common mistakes

Layout Dump System (stdin JSONL protocol)

Status: This is the design spec. Implementation requires patching the GPUI crate's TaffyLayoutEngine.

Triggering a dump

Send via stdin:

{"type":"debug.layout_dump","window":"ai","path":"./target/layout_ai.json"}

Optional fields:

• •ids: array of element ID strings to focus on in by_id output
• •include_tree: boolean (default true) — full tree traversal
• •include_by_id: boolean (default true) — flat index by element ID
• •pretty: boolean (default false) — pretty-print JSON

Acknowledgment

Stdout JSONL response:

{"type":"debug.layout_dumped","window":"ai","path":"./target/layout_ai.json","ok":true}

Dump JSON Schema (v1)

{
  "schema_version": 1,
  "window": "ai",
  "scale_factor": 2.0,
  "tree": {
    "id": "root",
    "node": 1,
    "bounds": { "x": 0, "y": 0, "w": 1200, "h": 800 },
    "children": [
      {
        "id": "ai-main-panel",
        "node": 42,
        "bounds": { "x": 0, "y": 52, "w": 1200, "h": 748 },
        "children": []
      }
    ]
  },
  "by_id": {
    "ai-input-area": [
      { "node": 99, "bounds": { "x": 0, "y": 700, "w": 1200, "h": 48 } }
    ]
  }
}

Node ID format:

• •Elements with .id("name") → "name"
• •Unlabeled nodes → "@node:123" (Taffy node ID)

Agent Assertions

Minimum invariants for the ACP Chat input area:

by_id["ai-input-area"][0].bounds.h > 0          # not collapsed
by_id["ai-input-area"][0].bounds.w > 0          # not zero-width
ai-input-area.y + h <= ai-main-panel.y + main_h # not clipped
ai-composer.h == COMPOSER_H (36px)               # correct height

Failure Signatures

Implementation Hook Points (for patching GPUI)

Where identity mapping goes

During layout node creation, register LayoutId -> DebugNodeInfo in debug builds:

#[cfg(debug_assertions)]
pub struct DebugNodeInfo {
    pub element_id: Option<String>,     // from .id("ai-input-area")
    pub source_file: Option<&'static str>,
    pub source_line: Option<u32>,
    pub style: DebugStyleInfo,          // overflow, display, flex_grow, etc.
}

Where dump happens

After TaffyLayoutEngine::compute_layout() — layout is not computed during Render, so dumping from render is wrong.

Sequence:

1. •stdin thread parses JSON → enqueues LayoutDumpRequest
2. •Window render loop processes request → calls window.request_layout_dump(spec)
3. •Next frame, after Taffy compute_layout, GPUI writes dump atomically
4. •GPUI emits stdout JSONL ack

Atomic file writing

#[cfg(debug_assertions)]
fn write_atomic_json(path: &Path, value: &impl Serialize) -> io::Result<()> {
    let tmp = path.with_extension("tmp");
    let mut f = fs::File::create(&tmp)?;
    f.write_all(&serde_json::to_vec(value).expect("serialize"))?;
    f.write_all(b"\n")?;
    f.sync_all()?;
    fs::rename(tmp, path)?;
    Ok(())
}

Agentic Fix-Verify Loop

Without layout dump (current state)

1. •Probe: Add debug colored div near suspected issue
2. •Build: cargo build
3. •Capture: Use named-pipe test script (see visual-test skill)
4. •Read: Read the PNG screenshot to visually verify
5. •Diagnose: Interpret probe visibility per table above
6. •Fix: Apply the fix based on diagnosis
7. •Verify: Rebuild, recapture, confirm fix
8. •Clean: Remove debug probes

With layout dump (when implemented)

1. •Build: cargo build
2. •Start app: Named pipe pattern from visual-test skill
3. •Show window: echo '{"type":"show"}' >&3
4. •Trigger dump: echo '{"type":"debug.layout_dump","window":"ai","path":"./target/layout_acp.json"}' >&3
5. •Wait for ack: Check stdout log for debug.layout_dumped
6. •Read dump: Parse JSON, run invariant assertions
7. •Diagnose: Match failure signature (collapsed vs clipped)
8. •Fix: Apply targeted fix based on computed bounds data
9. •Verify: Retrigger dump + screenshot, confirm all invariants pass

Key Element IDs (ACP Chat)

Window Layout Constants

Related Skills

• •visual-test — Named-pipe test scripts, captureWindow, screenshot workflow
• •gpui-patterns — Layout chains, flex patterns, theme system
• •dev-loop — Background dev server, log monitoring