From 3a3a62a50c59d08a576cf928a13c73310bbaff78 Mon Sep 17 00:00:00 2001
From: Greg Pomerantz <gmp@wow.st>
Date: Sat, 9 May 2026 17:22:31 -0400
Subject: [PATCH] Document BottomBar visible window positioning and pixel/DP
 conversion

---
 doc/shaper_usage.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/shaper_usage.md b/doc/shaper_usage.md
index a471d05..8e83bfb 100644
--- a/doc/shaper_usage.md
+++ b/doc/shaper_usage.md
@@ -571,6 +571,24 @@ visualGap = (line2Baseline - line1Baseline) - (ascent1 + ascent2)
 With `LineHeightScale = 1.0`: `visualGap ≈ 0` (lines touch)
 With `LineHeightScale = 1.2`: `visualGap ≈ 0.2 * lineHeight` (20% padding)
 
+## 9.5 Drawing Elements Inside the Visible Window
+
+When drawing elements like the BottomBar, the region Y computed from `screenHeight` may be outside the visible window area. This happens because `app.ConfigEvent` reports the **physical pixel size** of the window, which can be much larger than the requested DP size (e.g., macOS reports 1560×3376 pixels when we requested 390×844 DP).
+
+**The fix**: Use `gtx.Constraints.Max.Y` (in physical pixels) to clamp the draw position to the visible area:
+
+```go
+// gtx.Constraints.Max.Y is in physical pixels.
+// Convert to DP using gtx.Metric.PxPerDp.
+scale := gtx.Metric.PxPerDp
+bottomBarHeightPx := int(24 * scale)
+marginPx := int(10 * scale)
+drawYPx := gtx.Constraints.Max.Y - bottomBarHeightPx - marginPx
+drawY := unit.Dp(float64(drawYPx) / float64(scale))
+```
+
+**Key insight**: `gtx.Constraints.Max.X/Y` are in **physical pixels**, not DP. Always convert using `gtx.Metric.PxPerDp` when mixing pixels and DP.
+
 ## 10. Summary
 
 - **Always** use `fixed.I(gtx.Sp(size))` for `PxPerEm`
@@ -580,6 +598,8 @@ With `LineHeightScale = 1.2`: `visualGap ≈ 0.2 * lineHeight` (20% padding)
 - **Baseline spacing** = `lineHeight * LineHeightScale` (default 1.2)
 - **For tight multi-line layouts**, use `LineHeightScale: 1.0` or set explicit `LineHeight`
 - **Visual gap** between lines = `baselineSpacing - (ascent1 + ascent2)`
+- **gtx.Constraints.Max.X/Y** are in **physical pixels**, not DP. Convert using `gtx.Metric.PxPerDp`.
+- **When drawing at the bottom of the window**, use `gtx.Constraints.Max.Y - elementHeight - margin` to clamp to visible area.
 - **Avoid** using `material.Label()` when you need precise glyph positions
 - **Reuse** glyph data for measurement, hit testing, and rendering
 - **Follow** Gio's `paintGlyph` as the reference implementation