@flyingrobots/bijou-tui 3.1.0 → 4.1.0

package/dist/overlay.d.ts

@@ -2,6 +2,7 @@
  * Overlay compositing primitives for TUI apps.
  *
  * - `composite()` — paint overlays onto a background string (ANSI-safe)
+ * - `compositeSurface()` — paint overlays onto a background surface
  * - `modal()` — centered dialog overlay with title, body, hint
  * - `toast()` — anchored notification overlay with variant icons
  * - `tooltip()` — positioned overlay relative to a target element
@@ -28,22 +29,26 @@ export interface CompositeOptions {
     /** Wrap background lines in dim (ANSI 2m). */
     readonly dim?: boolean;
 }
+/** Structured overlay content accepted by the surface-native overlay family. */
+export type OverlayContent = string | Surface;
 /**
  * Configuration for the {@link modal} overlay.
  */
 export interface ModalOptions {
     /** Optional title displayed at the top of the modal (bolded when ctx provided). */
     readonly title?: string;
-    /** Body content of the modal. */
-    readonly body: string;
-    /** Optional hint text displayed below the body (muted when ctx provided). */
-    readonly hint?: string;
+    /** Body content of the modal. Accepts plain text or a structured surface. */
+    readonly body: OverlayContent;
+    /** Optional hint content displayed below the body (muted when ctx provided). */
+    readonly hint?: OverlayContent;
     /** Screen width in columns, used for centering. */
     readonly screenWidth: number;
     /** Screen height in rows, used for centering. */
     readonly screenHeight: number;
     /** Preferred minimum width — shorter lines are padded but longer lines are not truncated (default: auto from content). */
     readonly width?: number;
+    /** Preferred edge inset from the viewport when the dialog is centered. */
+    readonly margin?: number;
     /** Design token for the border color. */
     readonly borderToken?: TokenValue;
     /** Background fill token for the overlay interior. */
@@ -89,6 +94,22 @@ export interface ToastOptions {
  * @returns Composited string with all overlays applied.
  */
 export declare function composite(background: string, overlays: readonly Overlay[], options?: CompositeOptions): string;
+/**
+ * Paint one or more overlays onto a background surface.
+ *
+ * Overlays are applied in array order, with later overlays painting over
+ * earlier ones. String-only overlays are normalized through an explicit
+ * ANSI-to-surface bridge at the composition edge.
+ */
+export declare function compositeSurface(background: Surface, overlays: readonly Overlay[], options?: CompositeOptions): Surface;
+/**
+ * Paint overlays onto an existing target surface, optionally starting from an
+ * existing background surface.
+ *
+ * When `background` and `target` are the same object, the surface is
+ * composited in place without an extra clone.
+ */
+export declare function compositeSurfaceInto(background: Surface, target: Surface, overlays: readonly Overlay[], options?: CompositeOptions): Surface;
 /**
  * Create a centered modal dialog overlay.
  *
@@ -115,8 +136,8 @@ export type DrawerAnchor = 'left' | 'right' | 'top' | 'bottom';
  * Configuration for the {@link drawer} overlay.
  */
 interface DrawerBaseOptions {
-    /** Content string to display inside the drawer. */
-    readonly content: string;
+    /** Content to display inside the drawer. Accepts plain text or a structured surface. */
+    readonly content: OverlayContent;
     /** Screen width in columns, used for positioning. */
     readonly screenWidth: number;
     /** Screen height in rows, used for sizing. */
@@ -179,8 +200,8 @@ export type TooltipDirection = 'top' | 'bottom' | 'left' | 'right';
  * Configuration for the {@link tooltip} overlay.
  */
 export interface TooltipOptions {
-    /** Content string to display inside the tooltip. */
-    readonly content: string;
+    /** Content to display inside the tooltip. Accepts plain text or a structured surface. */
+    readonly content: OverlayContent;
     /** Row of the target element (0-based). */
     readonly row: number;
     /** Column of the target element (0-based). */

package/dist/overlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"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"}

package/dist/overlay.js

@@ -2,12 +2,14 @@
  * Overlay compositing primitives for TUI apps.
  *
  * - `composite()` — paint overlays onto a background string (ANSI-safe)
+ * - `compositeSurface()` — paint overlays onto a background surface
  * - `modal()` — centered dialog overlay with title, body, hint
  * - `toast()` — anchored notification overlay with variant icons
  * - `tooltip()` — positioned overlay relative to a target element
  */
-import { makeBgFill } from '@flyingrobots/bijou';
+import { createSurface, graphemeClusterWidth, parseAnsiToSurface, segmentGraphemes, shouldApplyBg, stripAnsi, surfaceToString, } from '@flyingrobots/bijou';
 import { sliceAnsi, visibleLength, clipToWidth } from './viewport.js';
+import { clampCenteredPosition, resolveOverlayMargin } from './design-language.js';
 // ---------------------------------------------------------------------------
 // Border characters (same as core box.ts)
 // ---------------------------------------------------------------------------
@@ -78,30 +80,170 @@ export function composite(background, overlays, options) {
     }
     return bgLines.join('\n');
 }
-// ---------------------------------------------------------------------------
-// renderBox (shared between modal and toast)
-// ---------------------------------------------------------------------------
 /**
- * Render lines inside a unicode box border.
+ * Paint one or more overlays onto a background surface.
  *
- * Compute inner width from the widest line, then wrap all lines
- * with vertical borders and pad to uniform width.
+ * Overlays are applied in array order, with later overlays painting over
+ * earlier ones. String-only overlays are normalized through an explicit
+ * ANSI-to-surface bridge at the composition edge.
+ */
+export function compositeSurface(background, overlays, options) {
+    const result = background.clone();
+    return compositeSurfaceInto(result, result, overlays, options);
+}
+/**
+ * Paint overlays onto an existing target surface, optionally starting from an
+ * existing background surface.
  *
- * @param lines - Content lines to place inside the box.
- * @param borderColor - Function to apply border styling (identity for unstyled).
- * @param bgFill - Optional function to wrap interior content with background color styling.
- * @returns Box string with top/bottom borders and bordered content lines.
+ * When `background` and `target` are the same object, the surface is
+ * composited in place without an extra clone.
  */
-function renderBox(lines, borderColor, bgFill) {
-    const innerWidth = lines.reduce((max, l) => Math.max(max, visibleLength(l)), 0);
-    const top = borderColor(BORDER.tl + BORDER.h.repeat(innerWidth + 2) + BORDER.tr);
-    const bottom = borderColor(BORDER.bl + BORDER.h.repeat(innerWidth + 2) + BORDER.br);
-    const fill = bgFill ?? ((s) => s);
-    const body = lines.map((l) => {
-        const pad = innerWidth - visibleLength(l);
-        return borderColor(BORDER.v) + fill(' ' + l + ' '.repeat(pad) + ' ') + borderColor(BORDER.v);
-    });
-    return [top, ...body, bottom].join('\n');
+export function compositeSurfaceInto(background, target, overlays, options) {
+    if (target !== background) {
+        target.clear();
+        target.blit(background, 0, 0);
+    }
+    if (options?.dim) {
+        for (const cell of target.cells) {
+            if (cell.empty || cell.char === ' ')
+                continue;
+            const modifiers = cell.modifiers ?? [];
+            if (!modifiers.includes('dim')) {
+                cell.modifiers = [...modifiers, 'dim'];
+            }
+            cell.empty = false;
+        }
+    }
+    for (const overlay of overlays) {
+        target.blit(overlay.surface ?? surfaceFromContent(overlay.content), overlay.col, overlay.row);
+    }
+    return target;
+}
+function styleFromToken(token, ctx) {
+    if (!ctx || token == null)
+        return {};
+    return {
+        fg: token.hex,
+        bg: token.bg,
+        modifiers: token.modifiers ? [...token.modifiers] : undefined,
+    };
+}
+function backgroundStyleFromToken(token, ctx) {
+    if (!ctx || !shouldApplyBg(ctx) || !token?.bg)
+        return {};
+    return { bg: token.bg };
+}
+function mergeStyles(base, extra) {
+    const modifiers = [...(base.modifiers ?? []), ...(extra.modifiers ?? [])];
+    return {
+        fg: extra.fg ?? base.fg,
+        bg: extra.bg ?? base.bg,
+        modifiers: modifiers.length > 0 ? Array.from(new Set(modifiers)) : undefined,
+    };
+}
+function plainSurfaceToString(surface) {
+    const lines = [];
+    for (let y = 0; y < surface.height; y++) {
+        let line = '';
+        for (let x = 0; x < surface.width; x++) {
+            line += surface.get(x, y).char;
+        }
+        lines.push(line);
+    }
+    return lines.join('\n');
+}
+function overlayContentFromSurface(surface, ctx) {
+    return ctx ? surfaceToString(surface, ctx.style) : plainSurfaceToString(surface);
+}
+function setStyledCell(surface, x, y, char, style) {
+    surface.set(x, y, { char, ...style, empty: false });
+}
+function setStyledGrapheme(surface, x, y, char, style) {
+    if (x >= surface.width)
+        return 0;
+    const width = Math.max(1, graphemeClusterWidth(char));
+    setStyledCell(surface, x, y, char, style);
+    for (let offset = 1; offset < width && x + offset < surface.width; offset++) {
+        setStyledCell(surface, x + offset, y, '', style);
+    }
+    return width;
+}
+function lineSurface(text, style = {}) {
+    if (text.length === 0)
+        return createSurface(0, 1);
+    const plain = stripAnsi(text);
+    const width = Math.max(0, visibleLength(text));
+    if (width === 0)
+        return createSurface(0, 1);
+    if (plain !== text && style.fg == null && style.bg == null && style.modifiers == null) {
+        return parseAnsiToSurface(text, width, 1);
+    }
+    const graphemes = segmentGraphemes(plain);
+    const surface = createSurface(width, 1);
+    let x = 0;
+    for (const grapheme of graphemes) {
+        if (x >= width)
+            break;
+        x += setStyledGrapheme(surface, x, 0, grapheme, style);
+    }
+    return surface;
+}
+function lineWithInheritedBackground(line, bg) {
+    if (bg == null || line.width === 0)
+        return line;
+    const result = line.clone();
+    for (let x = 0; x < result.width; x++) {
+        const cell = result.get(x, 0);
+        if (cell.empty)
+            continue;
+        result.set(x, 0, { ...cell, bg: cell.bg ?? bg, empty: false });
+    }
+    return result;
+}
+function surfaceRows(surface, maxWidth) {
+    const width = maxWidth != null ? Math.max(0, Math.min(surface.width, maxWidth)) : surface.width;
+    if (surface.height <= 0)
+        return [createSurface(width, 1)];
+    const rows = [];
+    for (let y = 0; y < surface.height; y++) {
+        const row = createSurface(width, 1);
+        if (width > 0)
+            row.blit(surface, 0, 0, 0, y, width, 1);
+        rows.push(row);
+    }
+    return rows;
+}
+function contentLines(content, maxWidth) {
+    if (typeof content === 'string') {
+        return content.split('\n').map((line) => lineSurface(maxWidth != null ? clipToWidth(line, maxWidth) : line));
+    }
+    return surfaceRows(content, maxWidth);
+}
+function renderBoxSurface(lines, borderStyle, fillStyle, innerWidthOverride) {
+    const innerWidth = innerWidthOverride ?? lines.reduce((max, line) => Math.max(max, line.width), 0);
+    const width = innerWidth + 4;
+    const height = lines.length + 2;
+    const surface = createSurface(width, height);
+    setStyledCell(surface, 0, 0, BORDER.tl, borderStyle);
+    for (let x = 1; x < width - 1; x++)
+        setStyledCell(surface, x, 0, BORDER.h, borderStyle);
+    setStyledCell(surface, width - 1, 0, BORDER.tr, borderStyle);
+    setStyledCell(surface, 0, height - 1, BORDER.bl, borderStyle);
+    for (let x = 1; x < width - 1; x++)
+        setStyledCell(surface, x, height - 1, BORDER.h, borderStyle);
+    setStyledCell(surface, width - 1, height - 1, BORDER.br, borderStyle);
+    for (let i = 0; i < lines.length; i++) {
+        const y = i + 1;
+        setStyledCell(surface, 0, y, BORDER.v, borderStyle);
+        for (let x = 1; x < width - 1; x++)
+            setStyledCell(surface, x, y, ' ', fillStyle);
+        setStyledCell(surface, width - 1, y, BORDER.v, borderStyle);
+        const line = lineWithInheritedBackground(lines[i], fillStyle.bg);
+        if (line.width > 0 && innerWidth > 0) {
+            surface.blit(line, 2, y, 0, 0, Math.min(line.width, innerWidth), 1);
+        }
+    }
+    return surface;
 }
 // ---------------------------------------------------------------------------
 // modal()
@@ -117,41 +259,25 @@ function renderBox(lines, borderColor, bgFill) {
  */
 export function modal(options) {
     const { title, body, hint, screenWidth, screenHeight, ctx } = options;
-    const contentLines = [];
+    const lines = [];
     if (title != null) {
-        const titleText = ctx ? ctx.style.bold(title) : title;
-        contentLines.push(titleText, '');
+        lines.push(lineSurface(title, ctx ? { modifiers: ['bold'] } : {}), createSurface(0, 1));
     }
-    contentLines.push(...body.split('\n'));
+    lines.push(...contentLines(body));
     if (hint != null) {
-        contentLines.push('');
-        const hintText = ctx
-            ? ctx.style.styled(ctx.semantic('muted'), hint)
-            : hint;
-        contentLines.push(hintText);
-    }
-    // If width override, constrain inner width
-    if (options.width != null) {
-        const targetInner = options.width - 4; // border + padding
-        // Pad short lines, but don't truncate (user controls width)
-        for (let i = 0; i < contentLines.length; i++) {
-            const vis = visibleLength(contentLines[i]);
-            if (vis < targetInner) {
-                contentLines[i] = contentLines[i] + ' '.repeat(targetInner - vis);
-            }
+        lines.push(createSurface(0, 1));
+        if (typeof hint === 'string') {
+            lines.push(lineSurface(hint, styleFromToken(ctx?.semantic('muted'), ctx)));
+        }
+        else {
+            lines.push(...surfaceRows(hint));
         }
     }
-    const borderColor = ctx && options.borderToken
-        ? (s) => ctx.style.styled(options.borderToken, s)
-        : (s) => s;
-    const bgFill = makeBgFill(options.bgToken, ctx);
-    const boxStr = renderBox(contentLines, borderColor, bgFill);
-    const boxLines = boxStr.split('\n');
-    const boxHeight = boxLines.length;
-    const boxWidth = visibleLength(boxLines[0]);
-    const row = Math.max(0, Math.floor((screenHeight - boxHeight) / 2));
-    const col = Math.max(0, Math.floor((screenWidth - boxWidth) / 2));
-    return { content: boxStr, row, col };
+    const surface = renderBoxSurface(lines, styleFromToken(options.borderToken, ctx), backgroundStyleFromToken(options.bgToken, ctx), options.width != null ? Math.max(0, options.width - 4) : undefined);
+    const margin = resolveOverlayMargin(screenWidth, screenHeight, options.margin);
+    const row = clampCenteredPosition(screenHeight, surface.height, margin);
+    const col = clampCenteredPosition(screenWidth, surface.width, margin);
+    return { content: overlayContentFromSurface(surface, ctx), surface, row, col };
 }
 // ---------------------------------------------------------------------------
 // toast()
@@ -178,44 +304,34 @@ const TOAST_BORDER = {
  * @returns Overlay positioned at the specified screen corner.
  */
 export function toast(options) {
-    const { message, variant = 'info', anchor = 'bottom-right', screenWidth, screenHeight, margin = 1, ctx, } = options;
+    const { message, variant = 'info', anchor = 'bottom-right', screenWidth, screenHeight, margin, ctx, } = options;
+    const resolvedMargin = resolveOverlayMargin(screenWidth, screenHeight, margin);
     const icon = TOAST_ICONS[variant];
-    let line = icon + ' ' + message;
-    if (ctx) {
-        line = ctx.style.styled(ctx.semantic(variant), line);
-    }
-    const borderKey = TOAST_BORDER[variant];
-    const borderColor = ctx
-        ? (s) => ctx.style.styled(ctx.border(borderKey), s)
-        : (s) => s;
-    const bgFill = makeBgFill(options.bgToken, ctx);
-    const boxStr = renderBox([line], borderColor, bgFill);
-    const boxLines = boxStr.split('\n');
-    const boxHeight = boxLines.length;
-    const boxWidth = visibleLength(boxLines[0]);
+    const line = lineSurface(`${icon} ${message}`, styleFromToken(ctx?.semantic(variant), ctx));
+    const surface = renderBoxSurface([line], styleFromToken(ctx?.border(TOAST_BORDER[variant]), ctx), backgroundStyleFromToken(options.bgToken, ctx));
     let row;
     let col;
     switch (anchor) {
         case 'top-right':
-            row = margin;
-            col = screenWidth - boxWidth - margin;
+            row = resolvedMargin;
+            col = screenWidth - surface.width - resolvedMargin;
             break;
         case 'bottom-right':
-            row = screenHeight - boxHeight - margin;
-            col = screenWidth - boxWidth - margin;
+            row = screenHeight - surface.height - resolvedMargin;
+            col = screenWidth - surface.width - resolvedMargin;
             break;
         case 'bottom-left':
-            row = screenHeight - boxHeight - margin;
-            col = margin;
+            row = screenHeight - surface.height - resolvedMargin;
+            col = resolvedMargin;
             break;
         case 'top-left':
-            row = margin;
-            col = margin;
+            row = resolvedMargin;
+            col = resolvedMargin;
             break;
     }
     row = Math.max(0, row);
     col = Math.max(0, col);
-    return { content: boxStr, row, col };
+    return { content: overlayContentFromSurface(surface, ctx), surface, row, col };
 }
 // ---------------------------------------------------------------------------
 // drawer()
@@ -240,51 +356,54 @@ export function drawer(options) {
     const dims = resolveDrawerDimensions(options, region);
     const { width, height, row, col } = dims;
     const innerWidth = Math.max(0, width - 4); // border + padding on each side
-    const borderColor = ctx && options.borderToken
-        ? (s) => ctx.style.styled(options.borderToken, s)
-        : (s) => s;
-    const bgFill = makeBgFill(options.bgToken, ctx);
-    const fill = bgFill ?? ((s) => s);
-    // Build top border
-    let topInner;
-    if (title) {
-        const titleText = ctx ? ctx.style.bold(title) : title;
-        const titleVis = visibleLength(titleText);
-        const remaining = Math.max(0, innerWidth + 2 - titleVis - 2); // +2 for padding around border, -2 for spaces around title
-        const leftDash = Math.floor(remaining / 2);
-        const rightDash = remaining - leftDash;
-        topInner = BORDER.h.repeat(leftDash) + ' ' + titleText + ' ' + BORDER.h.repeat(rightDash);
+    const borderStyle = styleFromToken(options.borderToken, ctx);
+    const fillStyle = backgroundStyleFromToken(options.bgToken, ctx);
+    const titleStyle = ctx ? { modifiers: ['bold'] } : {};
+    const surface = createSurface(width, height);
+    if (width === 0 || height === 0) {
+        return { content: overlayContentFromSurface(surface, ctx), surface, row, col };
     }
-    else {
-        topInner = BORDER.h.repeat(innerWidth + 2);
+    for (let x = 0; x < width; x++) {
+        const topChar = x === 0 ? BORDER.tl : x === width - 1 ? BORDER.tr : BORDER.h;
+        setStyledCell(surface, x, 0, topChar, borderStyle);
+        if (height > 1) {
+            const bottomChar = x === 0 ? BORDER.bl : x === width - 1 ? BORDER.br : BORDER.h;
+            setStyledCell(surface, x, height - 1, bottomChar, borderStyle);
+        }
     }
-    const topLine = fitLineExact(borderColor(BORDER.tl + topInner + BORDER.tr), width);
-    const bottomLine = fitLineExact(borderColor(BORDER.bl + BORDER.h.repeat(innerWidth + 2) + BORDER.br), width);
-    // Build content lines
-    const contentLines = content.split('\n');
-    const availableHeight = Math.max(0, height - 2); // minus top + bottom border
-    const bodyLines = [];
-    for (let i = 0; i < availableHeight; i++) {
-        const raw = contentLines[i] ?? '';
-        const vis = visibleLength(raw);
-        let clipped;
-        if (vis > innerWidth) {
-            clipped = clipToWidth(raw, innerWidth);
+    if (title != null && width > 2) {
+        const titleLine = lineSurface(title, titleStyle);
+        const spanWidth = Math.min(width - 2, titleLine.width + 2);
+        const startX = 1 + Math.max(0, Math.floor(((width - 2) - spanWidth) / 2));
+        setStyledCell(surface, startX, 0, ' ', borderStyle);
+        const mergedTitleStyle = mergeStyles(borderStyle, titleStyle);
+        for (let x = 0; x < Math.min(titleLine.width, Math.max(0, spanWidth - 2)); x++) {
+            setStyledCell(surface, startX + 1 + x, 0, titleLine.get(x, 0).char, mergedTitleStyle);
         }
-        else {
-            clipped = raw + ' '.repeat(innerWidth - vis);
+        if (spanWidth >= 2) {
+            setStyledCell(surface, startX + spanWidth - 1, 0, ' ', borderStyle);
         }
-        bodyLines.push(fitLineExact(borderColor(BORDER.v) + fill(' ' + clipped + ' ') + borderColor(BORDER.v), width));
     }
-    const allLines = [];
-    if (height === 1) {
-        allLines.push(topLine);
-    }
-    else if (height >= 2) {
-        allLines.push(topLine, ...bodyLines, bottomLine);
+    const rows = contentLines(content, innerWidth);
+    const availableHeight = Math.max(0, height - 2);
+    for (let i = 0; i < availableHeight; i++) {
+        const y = i + 1;
+        if (width >= 1)
+            setStyledCell(surface, 0, y, BORDER.v, borderStyle);
+        for (let x = 1; x < Math.max(1, width - 1); x++) {
+            if (x < width - 1)
+                setStyledCell(surface, x, y, ' ', fillStyle);
+        }
+        if (width >= 2)
+            setStyledCell(surface, width - 1, y, BORDER.v, borderStyle);
+        const line = lineWithInheritedBackground(rows[i] ?? createSurface(0, 1), fillStyle.bg);
+        if (line.width > 0 && innerWidth > 0 && width >= 4) {
+            surface.blit(line, 2, y, 0, 0, Math.min(line.width, innerWidth), 1);
+        }
     }
     return {
-        content: allLines.join('\n'),
+        content: overlayContentFromSurface(surface, ctx),
+        surface,
         row,
         col,
     };
@@ -348,13 +467,6 @@ function clampRegion(region, screenWidth, screenHeight) {
         height: Math.floor(clamp(region.height, 0, maxHeight)),
     };
 }
-/** Clip or pad a single line to exactly `width` visible columns. */
-function fitLineExact(line, width) {
-    const target = Math.max(0, width);
-    const clipped = clipToWidth(line, target);
-    const vis = visibleLength(clipped);
-    return clipped + ' '.repeat(Math.max(0, target - vis));
-}
 /** Clamp a number between min and max. */
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
@@ -374,38 +486,37 @@ function clamp(value, min, max) {
 export function tooltip(options) {
     const { content, row: targetRow, col: targetCol, direction = 'top', screenWidth, screenHeight, borderToken, bgToken, ctx, } = options;
     const maxContentWidth = Math.max(0, screenWidth - 4);
-    const contentLines = content.split('\n').map((l) => clipToWidth(l, maxContentWidth));
-    const borderColor = ctx && borderToken
-        ? (s) => ctx.style.styled(borderToken, s)
-        : (s) => s;
-    const bgFill = makeBgFill(bgToken, ctx);
-    const boxStr = renderBox(contentLines, borderColor, bgFill);
-    const boxLines = boxStr.split('\n');
-    const boxHeight = boxLines.length;
-    const boxWidth = visibleLength(boxLines[0]);
+    const lines = contentLines(content, maxContentWidth);
+    const surface = renderBoxSurface(lines, styleFromToken(borderToken, ctx), backgroundStyleFromToken(bgToken, ctx));
     let tipRow;
     let tipCol;
     switch (direction) {
         case 'top':
-            tipRow = targetRow - boxHeight;
-            tipCol = targetCol - Math.floor(boxWidth / 2);
+            tipRow = targetRow - surface.height;
+            tipCol = targetCol - Math.floor(surface.width / 2);
             break;
         case 'bottom':
             tipRow = targetRow + 1;
-            tipCol = targetCol - Math.floor(boxWidth / 2);
+            tipCol = targetCol - Math.floor(surface.width / 2);
             break;
         case 'left':
-            tipRow = targetRow - Math.floor(boxHeight / 2);
-            tipCol = targetCol - boxWidth;
+            tipRow = targetRow - Math.floor(surface.height / 2);
+            tipCol = targetCol - surface.width;
             break;
         case 'right':
-            tipRow = targetRow - Math.floor(boxHeight / 2);
+            tipRow = targetRow - Math.floor(surface.height / 2);
             tipCol = targetCol + 1;
             break;
     }
     // Clamp to screen bounds
-    tipRow = Math.max(0, Math.min(tipRow, screenHeight - boxHeight));
-    tipCol = Math.max(0, Math.min(tipCol, screenWidth - boxWidth));
-    return { content: boxStr, row: tipRow, col: tipCol };
+    tipRow = Math.max(0, Math.min(tipRow, screenHeight - surface.height));
+    tipCol = Math.max(0, Math.min(tipCol, screenWidth - surface.width));
+    return { content: overlayContentFromSurface(surface, ctx), surface, row: tipRow, col: tipCol };
+}
+function surfaceFromContent(content) {
+    const lines = content.split('\n');
+    const width = Math.max(1, ...lines.map((line) => visibleLength(line)));
+    const height = Math.max(1, lines.length);
+    return parseAnsiToSurface(content, width, height);
 }
 //# sourceMappingURL=overlay.js.map