Internal rendering helpers shared by the streaming presenters.
Purpose
-------
:class:`RenderBatcher` debounces UI refresh calls so a fast-streaming
model (DeepSeek-v4-pro can hit 80+ tokens/sec) does not peg the
terminal at one redraw per token. It enforces a minimum interval
between refreshes (10–20 FPS by default) but force-flushes early
when:
* a newline arrives — preserves perceived latency on line breaks; and
* a fenced code block closes (the closing ``\\`\\`\\``) — so the
post-stream Markdown render of the closed block lands without the
user staring at half a fence.
This module is private (``_render``) because its API is an
implementation detail of
:class:`~oc_ui.terminal.rich_presenter.RichPresenter` and the future
:class:`TextualPresenter`. Tests live in
``oc_chat/tests/unit/test_render_batcher.py``.
Responsibilities
----------------
- :class:`RenderBatcher` — decide when streaming chunks should
trigger a UI refresh, given chunk content, target FPS, and a
monotonic clock.
- Track open/closed fence state across chunks so the close-fence
flush is detected reliably.
Diagnostics
-----------
Domain: OC_UI.TERMINAL
Levels:
L2 — lifecycle events
L3 — semantic details
L4 — deep tracing
Contracts
---------
- The batcher's clock is injectable for tests (``now`` parameter).
- ``should_refresh`` is a pure decision — it returns a bool and may
read internal state but never sleeps or performs I/O.
- A ``force=True`` call always returns ``True`` regardless of timing.
- Module is *private* — callers outside ``oc_ui.terminal`` must not
import it.
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
1.15.0