Add plan: simplified board_config with broker-constructor wiring

[bdbarnett]

Summary

Adds docs/handoff/board-config-simplification-plan.md, a planning/discussion document (no code changes) for simplifying board_config.py while keeping the refresh timer owned by eventsys.Broker.

The doc covers:

• Three layouts compared — original (Jan 1, 2026, commit ef14624e: display-owned timer via DisplayDriver(auto_refresh=...)), current (main: broker-owned timer, hand-wired per config), and proposed (Broker(display_drv=..., touch_read=..., pump_read=...) does the wiring internally).
• Worked example — board_configs/busdisplay/i80/wt32sc01-plus in all three layouts, plus the runtime-verified 1-tuple touch_read bug in diy_esp32_ili9341_xpt2046 as motivation for validated named parameters.
• Refresh policy — displays declare a boolean needs_refresh; the period is owned by eventsys as a single DEFAULT_REFRESH_MS = 33, overridable per board via Broker(refresh_period=...).
• Display-refresh claim API — claim_display_refresh() / release() (plus a context-manager form) replaces the bare broker.display_refresh attribute convention; the broker retaining the refresh spec is what makes release trivial.
• Implicit quit handling — the constructor installs stop-timer + release-display on QUIT; register_quit_cleanup disappears from configs, with a single before_quit hook kept for LVGL shutdown.
• Quit signaling — poll_quit_discarding_others (written for output-only demos, now spread to ~26 files with drifted semantics: subscribers still receive events through it, and tower_climb double-polls around it) is deleted in favor of a sticky broker.quit_requested property set by _handle_quit(); checking a flag consumes nothing, eliminating the misuse class.
• TIMER_ASYNC retirement — replaced by a broker.timer_async read-only property.
• Naming review — decision table covering QUEUE→PUMP (event pump), data=/data2=→ real kwargs, create(type=...)→ per-type add_* methods, Broker vs Hub, board_config export set, and Broker no longer subclassing Device.
• Push-mode polling discussion — broker-owned timer enables opt-in autopoll() (events pushed to subscribers without an app loop); useful for REPL liveliness and event-driven apps, with signal-handler/ISR re-entrancy hazards analyzed; recommended as follow-up starting with the AsyncTimer path.
• Other opportunities — touch-read contract standardization, rotation tables as touch-driver attributes, manifest-driven config generation, release lockstep, stale-test cleanup, and a test list.
• Pros/cons, alternatives, and implementation order with explicit DECISION items for sign-off.

Testing

• ✅ Runtime check confirming the 1-tuple touch_read_func bug claim (TypeError: 'tuple' object is not callable) and that a callable read works.
• ⚠️ .venv/bin/python -m unittest discover -s tests — 14 errors, identical on main (pre-existing: stale auto_refresh kwargs in tests, _frame_recorder attribute), unrelated to this docs-only change. The plan now includes fixing these in the eventsys/displaysys test pass.

  

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.