Clipping box borders
OpenTUI's native box draw ignored the scissor stack, so a bordered box painted its border over everything around its scroll container. Fixed upstream in 0.6.0; kept for the detour it describes.
- #opentui
- #patches
- #rendering
Put a bordered <box> inside a <scrollbox> and scroll it. The box's text
clips to the viewport the way you expect. Its border keeps drawing, straight
over whatever sits around the scroll container.
Reproduced on @opentui/core 0.4.5, still there in 0.5.3, and last seen in
0.5.17. It has nothing to do with scrollboxes in particular. A plain
<box overflow="hidden"> leaks its children's borders the same way.
Why the text clips and the border does not
Clipping in OpenTUI is a scissor-rect stack on the buffer. Renderable.updateLayout
pushes a rect for every ancestor whose overflow is not "visible", and the
native draw calls intersect against the top of that stack before they touch a
cell.
Every native draw call reads that stack except one. BoxRenderable.renderSelf
paints through
bufferDrawBox, and bufferDrawBox never reads the stack, while drawText,
drawTextBuffer, fillRect and drawFrameBuffer all do. So a box's children
clip, its background fill clips, and its border glyphs draw at their full
geometry.
Draw somewhere else, then blit
The tempting fix is to reimplement the border: walk the box's edges, work out
which sides are on, place the title, and write the glyphs through drawText,
which respects the scissor. That means owning the border-style table, the
partial-side logic, both title alignments and the focus colour swap, and it
means re-owning them every time upstream changes one.
So upstream still draws the border. drawFrameBuffer honours the scissor
stack, so a partially clipped box can let the original renderSelf draw into
a scratch buffer at the origin and then blit that buffer into place:
Moving _screenX/_screenY to zero for the duration is what makes the scratch
draw land at the buffer's origin, and the finally puts them back before
anything else reads them. ensureScratch creates the buffer with
respectAlpha and clears it to a fully transparent cell, so the cells the box
does not paint leave the destination alone instead of overwriting it.
One buffer is enough for the whole process. Renderables draw sequentially
inside a single pass, and the drawFrameBuffer call on the next line consumes
the contents, so there is nothing to keep between boxes.
Deciding when to detour
Most boxes are nowhere near a clip edge, and they should keep the single native
call they had before. ancestorClip walks up from the box and intersects the
scissor rect of every clipping ancestor:
Three outcomes decide what happens next. No clipping ancestor, or a clip that contains the box whole, takes the untouched native path. A clip the box misses entirely skips the draw, because the blit would write nothing. Only a box straddling an edge pays for the scratch buffer.
A buffered ancestor stops the walk. Its scissor rect uses
frame-buffer-local coordinates, and comparing those against screen coordinates
would clip against the wrong origin, so the walk returns what it has and the
box falls back to the native path. The border then leaks the way it did before
the patch, which beats clipping it against the wrong rectangle.
parent, overflow and getScissorRect are all protected on Renderable.
The casts are deliberate. Keeping each one narrow and local is what shows the
next reader that this module reaches into internals.
The module
Installing it
The patch is on a prototype, so it only has to be in place before anything draws the first box. Put one call at the top of whatever creates the renderer.
It patches BoxRenderable.prototype, so it also covers every subclass that
delegates with super.renderSelf(buffer), including inputs and scrollbox
internals.
Two dead ends
Setting buffered: true on the offending box looks like an easy fix, since a
buffered renderable composites through drawFrameBuffer already. Inside a clip
it renders at the wrong offset and produces garbage.
The other one cost more time. A test written outside the project resolved
@opentui/core to a second copy of the package, the source tree in Bun's
install cache, so patching one copy's prototype left the other untouched, and a
verification script in a scratch directory reported the patch as a no-op. Keep
the tests in the same project that owns the dependency.
Two properties are worth testing once the test file is in the right place.
Fidelity. With nothing clipping it, a patched box renders the same glyphs and the same colours as the unpatched native path, across border styles, partial sides and both title alignments.
Clipping. A bordered box inside a scrollbox paints nothing outside the viewport at any scroll offset.
Resolved in 0.6.0
The exit condition was bufferDrawBox intersecting the scissor stack. 0.6.0
met it by deleting bufferDrawBox. A box now declares its paint through
getNativeScenePaint(), naming its border, style, colours and fill, and the
native scene traversal draws that paint inside the same clip it already
applies to text. The JS BoxRenderable.renderSelf survives as a fallback, and
it draws through OptimizedBuffer.drawBox, which reads the stack.
Three things make the module below inert or broken on 0.6.x, and each one is a seam it depended on:
renderSelf is not called
Painting a plain
<box>no longer goes through the prototype. WrappingBoxRenderable.prototype.renderSelfand counting calls across a frame on 0.6.6 gives zero, so the patch never runs.getScissorRect is gone
ancestorClipwalks ancestors callinggetScissorRect().Renderablehas no such method any more, because layout and clipping live in the native scene. A subclass that overridesrenderSelfwould still reach that walk, and the walk would throw._screenX is read-only
The scratch-buffer detour works by moving
_screenX/_screenYto zero for the duration of the draw. Both are now getters derived from the native scene layout, with no setter, so the patch cannot move the box to the scratch buffer's origin.
Delete the module and its call site when the app moves to 0.6.x. Pinned to 0.5.x, it still applies as written.
Related entries
- Making drag-selection opt-in. The other patch installed beside this one, through a different seam. Still required on 0.6.6.
- Terminal-relative dimensions. Patches the
Renderableprototype as well, for the accessor half of its job. Still required on 0.6.6.
Files in this entry
Saved beside the document, and served as-is.
Related entries
Making drag-selection opt-in
OpenTUI's text renderables are selectable by default, so a click-to-navigate UI starts a drag-selection instead. Flipping the default without disabling selection.
Terminal-relative dimensions
Giving a negative width or height the meaning "terminal size minus that many cells", re-resolved on every resize, since OpenTUI percentages resolve against the parent.
Reading the host terminal's colours
Subscribing to the terminal's own palette from React, including the DEC mode OpenTUI never enables and the cache the poll fallback has to clear.