PaintContext architecture & enforced clipping refactor

[sastraxi]

The current drawing API conflates where the widget is and what part of it is dirty, providing only one parameter: real_box. For full refreshes, these rectangles are identical and there's no information loss. But for partial updates, it makes it impossible to properly perform coordinate changes.

The bug

The current code uses real_box (the dirty clip) as the drawing origin for children. So during a partial refresh, text is drawn a few pixels from where it should be. The final paste only covered the clip region, leaving fringe pixels from the wrong-position drawn outside it. Those leaked pixels then sat under the correctly-positioned text on the next full refresh, effectively overdrawing text in some cases and reproducing whole parts of the image where they shouldn't be.

New paint architecture

_do_draw now takes:

• PaintContext — a frozen dataclass carrying (image, draw, clip, pool) passed down recursively.
• Frame — where this widget is, in the current target's coordinate space. Cascades from parent: child.frame = child.box.offset(parent.frame).
• Clip — the dirty rect in the current target's coordinate space.

All drawing is now wrapped in a context manager PaintContext.painting(frame), which enforces clip boundaries. If possible, it draws directly on the backing image. When the frame is not fully contained in the clip, it falls back to a "slow path": a temporary buffer is allocated from a buffer pool which is blanked out with RGBA(0, 0, 0, 0) then only the clip region is composited over the target.

This buffer pool returns the "best fitting" buffer for the visible = clip ∩ frame region.

New in this PR

• uilib/paint.py — PaintContext, painting() manager, and BufferPool
• Widget._do_draw — consolidated to a single body using enforced clipping
• ContainerWidget — optimized to repaint only dirty regions and use the framework pool
• Box.contains & Box.size — geometric helpers
• FootswitchWidget — corrected box sizing (60x60) to prevent truncation
• tests/test_paint_context.py — unit tests for clipping logic, dirty propagation, and pool lifecycle
• Fixes for visual artifacts in various UI snapshots

Author checklist

• figure out dimming / menu drawing bug that shows up when merged with feat/multi-wifi

[sastraxi]

If you look at pistomp/lcd320x240.py, the update_footswitch method already handles this correctly:

def update_footswitch(self, footswitch):
    for wfs in self.w_footswitches:
        if wfs.object == footswitch:
            wfs.toggle(footswitch.enabled == False) # 1. Update state
            # ... update label ...
            break
    self.footswitch_panel.refresh()                 # 2. Trigger redraw

Because the caller immediately triggers footswitch_panel.refresh(), the framework will:

1. Walk down the tree.
2. Call _do_draw on each footswitch.
3. Pass in a fresh, valid PaintContext.
4. The footswitch will see its new self.is_bypassed state and draw the correct halo color.

[sastraxi]

I'm going a different route with this one.