Ansi Safe Border Caption Embedding

SKILL: ANSI-Safe Border Caption Embedding

Domain: output-rendering Trigger: Apply when you must insert text into a border line (top or bottom) while preserving the border characters, colors, and alignment, even if the caption is wider than available space. Source Pattern: Distilled from reviewed terminal rendering, layout, animation, and accessibility implementations.

Core Method

Treat the border as a sequence of uniformly repeated characters, compute the textual width, and trim or center the caption before joining it back into the border; this keeps the corners intact. Use the helper that calculates string width (respecting wide characters), convert position into an absolute column, and split the border into before/text/after fragments so colors/dim states can be reapplied independently.

Key Rules

• Always compute string width on the caption and the border to avoid breaking wide glyphs when aligning.
• Guard with max width: if text length border length 2, cut the caption so it fits without overwriting corner glyphs.
• Reapply color/dim styling separately to the prefix, caption, and suffix before writing to the output buffer so ANSI escapes stay symmetric.
• Support start, end, and center alignments plus offset adjustments so captions can hug either edge without manual math.

Example Application

When labeling a dialog border, call this method with position:'top', align:'center', and the pre-rendered caption string; clip it if the window narrows, and keep the corner and side glyphs in place so the divider stays crisp.

Anti-Patterns (What NOT to do)

• Do not blur characters by writing the caption directly into the border string without recalculating width; wide glyphs will be truncated incorrectly.
• Do not drop color/dim styling while embedding text, which makes the caption disappear under multi-colored borders.