@textui/core 0.1.0

package/src/runtime/paint.ts

@@ -0,0 +1,737 @@
+import type { Rect } from '../types/geometry.js';
+import type { Style } from '../types/style.js';
+import type { ResolvedTheme } from '../types/theme.js';
+import type { TerminalCapabilities } from '../types/capabilities.js';
+import type { Cell, Color } from '../types/cells.js';
+import { ATTR_DIM } from '../types/cells.js';
+import type { CellStyle, PaintSurface, RenderContext } from '../types/render.js';
+import type { LayoutBox } from '../render/layout.js';
+import { overflowOn } from '../render/layout.js';
+import type { Instance } from './instance.js';
+import type { Buffer } from '../render/buffer.js';
+import { COLOR_DEFAULT, mix, packColor, type PackedColor } from '../render/color.js';
+import { rectIntersect } from '../types/geometry.js';
+import {
+  graphemes, graphemeWidth, sanitize, stringWidth, truncate,
+  truncateSideOf, wrapModeOf, wrapText,
+} from '../util/text.js';
+import {
+  attrsFromStyle, NO_INTERACTION, packStyleColor, resolveBorder,
+  resolveStyle, type InteractionState, type ResolvedBorder,
+} from './style.js';
+
+/**
+ * Painting.
+ *
+ * The tree is walked twice per frame: once to build layout boxes, once to
+ * paint them. Both walks skip function components entirely - they contribute
+ * their children and nothing else - so the layout engine and the painter only
+ * ever see `box`, `text` and `canvas`.
+ */
+
+// ------------------------------------------------------------ paint surface
+
+class Surface implements PaintSurface {
+  /**
+   * What a cell gets when the caller does not name a background.
+   *
+   * `COLOR_DEFAULT` for the painters that own the whole box, and the box's own
+   * resolved background for a `canvas`, which does not. A canvas is drawn
+   * *onto* something - a panel, a selected row, a themed surface - and a glyph
+   * written with only an `fg` was resetting the cell behind it to the
+   * terminal's default, punching a hole through whatever it was sitting on.
+   *
+   * A painter that really wants the terminal's own background can still say
+   * so, because `'default'` is a colour it can pass.
+   */
+  constructor(
+    private buffer: Buffer,
+    readonly rect: Rect,
+    private clipRect: Rect,
+    private defaultBg: PackedColor = COLOR_DEFAULT,
+  ) {}
+
+  private visible(ax: number, ay: number): boolean {
+    return (
+      ax >= this.clipRect.x && ax < this.clipRect.x + this.clipRect.width &&
+      ay >= this.clipRect.y && ay < this.clipRect.y + this.clipRect.height
+    );
+  }
+
+  put(x: number, y: number, char: string, style?: CellStyle): void {
+    const ax = this.rect.x + x;
+    const ay = this.rect.y + y;
+    if (!this.visible(ax, ay)) return;
+    this.buffer.put(
+      ax, ay, char,
+      style?.fg === undefined ? COLOR_DEFAULT : packColor(style.fg),
+      style?.bg === undefined ? this.defaultBg : packColor(style.bg),
+      style?.attrs ?? 0,
+      style?.link,
+    );
+  }
+
+  /*
+   * One style, packed once.
+   *
+   * `put` packs both colours out of the style it is handed, which is right for
+   * one cell and wrong for the two callers that write a *run* of them: a
+   * twenty-character label was twenty pairs of `packColor` calls on the same
+   * two values, and a filled box was one pair per cell of the box. Packing is
+   * what a colour becomes, and it becomes the same thing every time.
+   */
+  text(x: number, y: number, text: string, style?: CellStyle): number {
+    const fg = style?.fg === undefined ? COLOR_DEFAULT : packColor(style.fg);
+    const bg = style?.bg === undefined ? this.defaultBg : packColor(style.bg);
+    const attrs = style?.attrs ?? 0;
+    const link = style?.link;
+    const oy = this.rect.y + y;
+
+    let cx = x;
+    for (const g of graphemes(sanitize(text))) {
+      const w = graphemeWidth(g);
+      if (w === 0) continue;
+      const ax = this.rect.x + cx;
+      if (this.visible(ax, oy)) this.buffer.put(ax, oy, g, fg, bg, attrs, link);
+      cx += w;
+    }
+    return cx - x;
+  }
+
+  fill(rect: Rect | undefined, char: string, style?: CellStyle): void {
+    const r = rect ?? { x: 0, y: 0, width: this.rect.width, height: this.rect.height };
+    const fg = style?.fg === undefined ? COLOR_DEFAULT : packColor(style.fg);
+    const bg = style?.bg === undefined ? this.defaultBg : packColor(style.bg);
+    const attrs = style?.attrs ?? 0;
+    const link = style?.link;
+
+    for (let y = r.y; y < r.y + r.height; y++) {
+      const ay = this.rect.y + y;
+      for (let x = r.x; x < r.x + r.width; x++) {
+        const ax = this.rect.x + x;
+        if (this.visible(ax, ay)) this.buffer.put(ax, ay, char, fg, bg, attrs, link);
+      }
+    }
+  }
+
+  cell(x: number, y: number, cell: Cell): void {
+    this.put(x, y, cell.char, {
+      fg: cell.fg, bg: cell.bg, attrs: cell.attrs, link: cell.link,
+    });
+  }
+
+  clip(rect: Rect): PaintSurface {
+    const absolute = {
+      x: this.rect.x + rect.x,
+      y: this.rect.y + rect.y,
+      width: rect.width,
+      height: rect.height,
+    };
+    return new Surface(this.buffer, absolute, rectIntersect(this.clipRect, absolute), this.defaultBg);
+  }
+}
+
+/** Direct writer for the runtime itself, in absolute buffer coordinates. */
+function rawSurface(buffer: Buffer, clip: Rect): PaintSurface {
+  return new Surface(buffer, { x: 0, y: 0, width: buffer.width, height: buffer.height }, clip);
+}
+
+// ------------------------------------------------------------ render context
+
+export function createRenderContext(
+  theme: ResolvedTheme,
+  capabilities: TerminalCapabilities,
+  state: InteractionState = NO_INTERACTION,
+): RenderContext {
+  return {
+    theme,
+    capabilities,
+    focused: state.focused,
+    hovered: state.hovered,
+    active: state.active,
+    selected: state.selected,
+    disabled: state.disabled,
+    color: (c, fallback = 'default') =>
+      c === undefined ? fallback : (theme.color(String(c)) as Color),
+    glyph: (name) => {
+      const g = (theme.glyphs as unknown as Record<string, unknown>)[name];
+      return typeof g === 'string' ? g : '';
+    },
+    measureText: stringWidth,
+  };
+}
+
+// ------------------------------------------------------------- layout build
+
+export interface PaintEnv {
+  theme: ResolvedTheme;
+  capabilities: TerminalCapabilities;
+  /** Interaction state for an instance, resolved by the runtime. */
+  stateOf(instance: Instance): InteractionState;
+}
+
+interface HostVisual {
+  style: Style;
+  border: ResolvedBorder;
+  /** Effective colour: this box's own, or the one it inherited. */
+  fg: PackedColor;
+  bg: PackedColor;
+  attrs: number;
+  /** True when the background is this box's rather than an ancestor's. */
+  ownBg: boolean;
+  /** The same question for the foreground, which the border has to ask. */
+  ownFg: boolean;
+}
+
+/** Colour and attributes handed down to a box's children. */
+interface Inherited {
+  fg: PackedColor;
+  bg: PackedColor;
+  attrs: number;
+}
+
+const NO_INHERITANCE: Inherited = { fg: COLOR_DEFAULT, bg: COLOR_DEFAULT, attrs: 0 };
+
+const VISUAL = Symbol('textui.visual');
+
+interface VisualBox extends LayoutBox {
+  [VISUAL]?: HostVisual;
+  instance?: Instance;
+}
+
+/**
+ * Colour is inherited; a box's own always wins.
+ *
+ * Without this a `text` inside a coloured box is drawn in the terminal's
+ * default colours - and because a cell holds one background, the glyphs punch
+ * a hole through the box behind them. That is a label in the wrong colour on a
+ * button, a selected row whose text stays the unselected colour, and a filled
+ * block with a ragged bar of default background across the middle of it.
+ */
+function visualFor(
+  instance: Instance,
+  env: PaintEnv,
+  inherited: Inherited = NO_INHERITANCE,
+): HostVisual {
+  const state = env.stateOf(instance);
+  const style = resolveStyle(
+    instance.props,
+    env.theme,
+    instance.component,
+    instance.definition?.defaultStyle,
+    state,
+  );
+  const border = resolveBorder(style.border, env.theme);
+
+  const ownFg = packStyleColor(style.fg, env.theme);
+  const ownBg = packStyleColor(style.bg, env.theme);
+
+  return {
+    style,
+    border,
+    fg: ownFg === COLOR_DEFAULT ? inherited.fg : ownFg,
+    bg: ownBg === COLOR_DEFAULT ? inherited.bg : ownBg,
+    // Attributes accumulate: `bold` on a row is bold for what is in the row.
+    attrs: attrsFromStyle(style) | inherited.attrs,
+    // Stating a background makes a box opaque, even when the background it
+    // states is the terminal's own. The two are not the same thing: a box
+    // that says nothing inherits what is behind it, and a box that says
+    // `bg: 'default'` fills itself with spaces at the terminal's colour.
+    //
+    // Every colour in the `mono` theme is `default`, so the old test - is the
+    // packed colour something other than the default? - made every surface in
+    // that theme transparent. A palette opened over a document drew its border
+    // and its rows and left the document showing through the gaps between
+    // them, which is unreadable and looked like a compositing bug.
+    ownBg: style.bg !== undefined,
+    ownFg: style.fg !== undefined,
+  };
+}
+
+/** Boxes contributed by an instance. Function components contribute none. */
+export function buildBoxes(
+  instance: Instance,
+  env: PaintEnv,
+  inherited: Inherited = NO_INHERITANCE,
+): LayoutBox[] {
+  if (instance.kind !== 'host') {
+    // A function component contributes no box, and no colour of its own.
+    const out: LayoutBox[] = [];
+    for (const child of instance.children) out.push(...buildBoxes(child, env, inherited));
+    return out;
+  }
+
+  const visual = visualFor(instance, env, inherited);
+  const box: VisualBox = {
+    style: visual.style,
+    borderEdges: visual.border.edges,
+    children: [],
+    rect: { x: 0, y: 0, width: 0, height: 0 },
+    content: { x: 0, y: 0, width: 0, height: 0 },
+    scrollTop: typeof instance.props.scrollTop === 'number' ? instance.props.scrollTop : 0,
+    scrollLeft: typeof instance.props.scrollLeft === 'number' ? instance.props.scrollLeft : 0,
+    [VISUAL]: visual,
+    instance,
+  };
+
+  switch (instance.component) {
+    case 'text':
+      box.measure = textMeasure(instance, visual.style);
+      break;
+    case 'canvas': {
+      const intrinsic = instance.props.intrinsic as { width?: number; height?: number } | undefined;
+      box.measure = () => ({ width: intrinsic?.width ?? 0, height: intrinsic?.height ?? 0 });
+      break;
+    }
+    case 'spacer': {
+      const size = typeof instance.props.size === 'number' ? instance.props.size : undefined;
+      // No size and no flex means take what is left. A spacer that measures
+      // zero and does not grow is a node that does nothing, which is never
+      // what anyone wrote one for - and it is what `size` has always been
+      // documented to mean when it is unset.
+      if (size === undefined && box.style.flex === undefined) {
+        box.style = { ...box.style, flex: 1 };
+      }
+      box.measure = () => ({ width: size ?? 0, height: size ?? 0 });
+      break;
+    }
+    default:
+      break;
+  }
+
+  const handDown: Inherited = { fg: visual.fg, bg: visual.bg, attrs: visual.attrs };
+  for (const child of instance.children) {
+    box.children.push(...buildBoxes(child, env, handDown));
+  }
+
+  // Painting and hit-testing order within one parent.
+  box.children.sort((a, b) => (a.style.zIndex ?? 0) - (b.style.zIndex ?? 0));
+
+  instance.box = box;
+  return [box];
+}
+
+function textContent(instance: Instance): string {
+  const { content, children } = instance.props;
+  if (typeof content === 'string') return content;
+  if (typeof content === 'number') return String(content);
+  if (typeof children === 'string') return children;
+  if (typeof children === 'number') return String(children);
+  if (Array.isArray(children)) {
+    return children
+      .filter((c) => typeof c === 'string' || typeof c === 'number')
+      .join('');
+  }
+  return '';
+}
+
+/**
+ * Flatten to one row, for the truncating wrap modes.
+ *
+ * A newline in a text that has one row to live in has nowhere to go. Joining
+ * with a space keeps the sentence readable and keeps the cut where the reader
+ * can see it; dropping everything after the first newline would silently lose
+ * text that the ellipsis then claims was merely too long.
+ */
+function oneLine(text: string): string {
+  return text.includes('\n') ? text.split('\n').join(' ') : text;
+}
+
+function textMeasure(instance: Instance, style: Style): (w: number, h: number) => { width: number; height: number } {
+  return (maxWidth: number) => {
+    const text = sanitize(textContent(instance));
+    if (text === '') return { width: 0, height: text.includes('\n') ? 1 : 1 };
+
+    const wrap = style.wrap ?? 'none';
+
+    // A truncating text is one row, always. It still asks for the width it
+    // would like - a box sizing itself around it gets the whole string when
+    // there is room, and only cuts when there is not.
+    if (truncateSideOf(wrap) !== undefined) {
+      return { width: stringWidth(oneLine(text)), height: 1 };
+    }
+
+    if (wrap === 'none') {
+      const lines = text.split('\n');
+      return {
+        width: Math.max(...lines.map(stringWidth)),
+        height: lines.length,
+      };
+    }
+    const limit = Number.isFinite(maxWidth) && maxWidth > 0 ? maxWidth : stringWidth(text);
+    const lines = wrapText(text, limit, wrapModeOf(wrap));
+    return {
+      width: Math.min(limit, Math.max(0, ...lines.map(stringWidth))),
+      height: Math.max(1, lines.length),
+    };
+  };
+}
+
+// ------------------------------------------------------------------- paint
+
+export function paintTree(
+  buffer: Buffer,
+  instance: Instance,
+  env: PaintEnv,
+  clip: Rect,
+): void {
+  if (instance.kind !== 'host') {
+    for (const child of instance.children) paintTree(buffer, child, env, clip);
+    return;
+  }
+
+  const box = instance.box as VisualBox | undefined;
+  if (!box) return;
+
+  const visual = box[VISUAL] ?? visualFor(instance, env);
+  const rect = box.rect;
+  if (rect.width <= 0 || rect.height <= 0) return;
+
+  const own = rectIntersect(clip, rect);
+  if (own.width <= 0 || own.height <= 0) {
+    // Fully clipped, but absolutely-positioned descendants may still be visible
+    // if they escaped - they do not, so nothing to do.
+    return;
+  }
+
+  const surface = rawSurface(buffer, own);
+
+  // 1. background
+  //
+  // Only when this box states one: an inherited background has already been
+  // painted by whoever owns it, and filling it again per nested box would be
+  // the same cells written several times a frame.
+  if (visual.ownBg || visual.style.fill) {
+    /*
+     * Straight to the buffer, with the colours it already has.
+     *
+     * This loop used to build a style object per cell and call `colorOf` twice
+     * to fill it - unpacking two packed colours into `Color` values so that
+     * `put` could pack them straight back. On a full-screen background that is
+     * five allocations a cell and sixty thousand a frame, all of it to arrive
+     * at the two integers `visual.fg` and `visual.bg` already held.
+     *
+     * Iterating the clipped rect rather than the box's own also drops the
+     * per-cell visibility test: `own` is the intersection, so every cell in it
+     * is visible by construction.
+     */
+    const fill = visual.style.fill ?? ' ';
+    for (let y = own.y; y < own.y + own.height; y++) {
+      for (let x = own.x; x < own.x + own.width; x++) {
+        buffer.put(x, y, fill, visual.fg, visual.bg);
+      }
+    }
+  }
+
+  // 2. scrim: recede what is already here, rather than cover it
+  if (visual.style.scrim !== undefined && visual.style.scrim !== false) {
+    washRegion(
+      buffer,
+      own,
+      packStyleColor(visual.style.scrim === true ? 'scrim' : visual.style.scrim, env.theme),
+      visual.style.scrimStrength ?? 0.55,
+    );
+  }
+
+  // 3. border, with its title and footer
+  if (visual.border.style !== 'none') {
+    paintBorder(surface, rect, visual, instance, env);
+  }
+
+  // 4. content
+  switch (instance.component) {
+    case 'text':
+      paintText(surface, box, visual, instance, env);
+      break;
+    case 'canvas':
+      paintCanvas(buffer, box, instance, env, own, visual.bg);
+      break;
+    default:
+      break;
+  }
+
+  // 5. children, clipped to this box's content when overflow is contained -
+  // per axis, so a row that scrolls sideways can still spill downwards.
+  const clipX = overflowOn(visual.style, 'x') !== 'visible';
+  const clipY = overflowOn(visual.style, 'y') !== 'visible';
+  const childClip = clipX || clipY
+    ? rectIntersect(clip, {
+        x: clipX ? box.content.x : clip.x,
+        y: clipY ? box.content.y : clip.y,
+        width: clipX ? box.content.width : clip.width,
+        height: clipY ? box.content.height : clip.height,
+      })
+    : clip;
+
+  for (const child of instance.children) {
+    paintTree(buffer, child, env, childClip);
+  }
+}
+
+/**
+ * Blend a region toward one colour.
+ *
+ * A terminal has no alpha, so the choice is between covering the content
+ * behind a modal and moving it toward the scrim colour. Moving it keeps the
+ * screen recognisable - you can still see what the dialog is about - and it is
+ * what dimming means on a display that cannot dim.
+ *
+ * A cell left at the terminal's default colour cannot be blended, because we
+ * do not know what colour it is; it gets the dim attribute instead.
+ */
+function washRegion(buffer: Buffer, rect: Rect, color: PackedColor, strength: number): void {
+  const amount = Math.max(0, Math.min(1, strength));
+
+  /*
+   * Straight at the cells, not through `get()`.
+   *
+   * `Buffer.get` builds a friendly object - unpacking both colours into `Color`
+   * values - and this immediately packs them back to compare and mix. That is
+   * an allocation and a round trip per cell, and a scrim covers a whole dialog
+   * area: an 80x30 modal is 2,400 objects per frame to answer a question the
+   * packed integers already answer. `get()` stays the public shape; the
+   * renderer's inner loop is not the place for it.
+   */
+  for (let y = rect.y; y < rect.y + rect.height; y++) {
+    for (let x = rect.x; x < rect.x + rect.width; x++) {
+      const at = buffer.packedAt(x, y);
+      if (!at) continue;
+
+      buffer.put(
+        x, y, at.char,
+        at.fg === COLOR_DEFAULT ? at.fg : mix(at.fg, color, amount),
+        at.bg === COLOR_DEFAULT ? at.bg : mix(at.bg, color, amount),
+        at.fg === COLOR_DEFAULT || at.bg === COLOR_DEFAULT ? at.attrs | ATTR_DIM : at.attrs,
+        at.link,
+      );
+    }
+  }
+}
+
+function colorOf(packed: PackedColor): Color {
+  if (packed === COLOR_DEFAULT) return 'default';
+  if (packed >= 0x1000000) {
+    return { rgb: [(packed >> 16) & 0xff, (packed >> 8) & 0xff, packed & 0xff] };
+  }
+  return { palette: packed };
+}
+
+function paintBorder(
+  surface: PaintSurface,
+  rect: Rect,
+  visual: HostVisual,
+  instance: Instance,
+  env: PaintEnv,
+): void {
+  const { chars, sides, colors } = visual.border;
+  /*
+   * A frame is the theme's `border` unless this box asked for something else.
+   *
+   * "Something else" is a colour on the border spec, or a colour on the box -
+   * `<box fg="danger" border="single">` means a danger frame, and that is
+   * worth keeping. What it must *not* mean is a colour the box merely
+   * inherited: the test used to be `visual.fg === COLOR_DEFAULT`, and
+   * `visual.fg` is the effective colour, so any box under an ancestor that set
+   * one took that instead of the border token. An application whose shell
+   * states its text colour - which is most of them - drew every frame in the
+   * text colour, as bright as the words inside it, and the `border` token in
+   * the theme went unused.
+   *
+   * `ownFg` is the same question `ownBg` already asks for the background.
+   */
+  const fg = visual.border.color !== undefined
+    ? colorOf(packStyleColor(visual.border.color, env.theme))
+    : visual.ownFg
+      ? colorOf(visual.fg)
+      : colorOf(packStyleColor('border', env.theme));
+  const bg = colorOf(visual.bg);
+  // `dim` on the border spec dims the frame and nothing else. Setting it on
+  // the box would take the title, the content and every child with it.
+  const attrs = visual.attrs | (visual.border.dim ? ATTR_DIM : 0);
+  const style: CellStyle = { fg, bg, attrs };
+
+  /** One edge's style: its own colour if it named one, the frame's otherwise. */
+  const edge = (side: 'top' | 'right' | 'bottom' | 'left'): CellStyle => {
+    const own = colors[side];
+    return own === undefined ? style : { fg: colorOf(packStyleColor(own, env.theme)), bg, attrs };
+  };
+  const top = edge('top');
+  const bottomStyle = edge('bottom');
+
+  const { x, y, width: w, height: h } = rect;
+  const right = x + w - 1;
+  const bottom = y + h - 1;
+
+  if (sides.top) {
+    for (let i = x; i <= right; i++) surface.put(i, y, chars.top, top);
+  }
+  if (sides.bottom && h > 1) {
+    for (let i = x; i <= right; i++) surface.put(i, bottom, chars.bottom, bottomStyle);
+  }
+  if (sides.left) {
+    const left = edge('left');
+    for (let i = y; i <= bottom; i++) surface.put(x, i, chars.left, left);
+  }
+  if (sides.right && w > 1) {
+    const rightStyle = edge('right');
+    for (let i = y; i <= bottom; i++) surface.put(right, i, chars.right, rightStyle);
+  }
+
+  // A corner is one cell and two edges meet in it, so one of them has to win.
+  // The horizontal rule takes it: a box reads as a top and a bottom line with
+  // sides between them, and breaking a long rule's colour at its own ends is
+  // the more visible mistake.
+  if (sides.top && sides.left) surface.put(x, y, chars.topLeft, top);
+  if (sides.top && sides.right && w > 1) surface.put(right, y, chars.topRight, top);
+  if (sides.bottom && sides.left && h > 1) surface.put(x, bottom, chars.bottomLeft, bottomStyle);
+  if (sides.bottom && sides.right && w > 1 && h > 1) {
+    surface.put(right, bottom, chars.bottomRight, bottomStyle);
+  }
+
+  const inner = w - 2;
+  if (inner <= 0) return;
+
+  /*
+   * A second label on the top rule, hard against the right.
+   *
+   * Painted *before* the title, and the title is then given the width it
+   * leaves, so the two cannot land on the same cells whatever `titleAlign`
+   * says. That order also decides which one loses when there is not enough
+   * room: the right label is the short one - a count, a shortcut, a state -
+   * and the title is the one that can be truncated and still be read.
+   */
+  const rightTitle = instance.props.rightTitle;
+  let reserved = 0;
+  if (sides.top && typeof rightTitle === 'string' && rightTitle !== '') {
+    const label = ` ${rightTitle} `;
+    reserved = Math.min(inner, stringWidth(sanitize(label)));
+    paintBorderLabel(
+      surface, x, y, inner, label, 'right',
+      { ...style, fg: colorOf(packStyleColor('muted', env.theme)), attrs: visual.attrs },
+      env.theme.glyphs.ellipsis,
+    );
+  }
+
+  const title = instance.props.title;
+  if (sides.top && typeof title === 'string' && title !== '' && inner - reserved > 0) {
+    paintBorderLabel(
+      surface, x, y, inner - reserved, ` ${title} `,
+      (instance.props.titleAlign as 'left' | 'center' | 'right') ?? 'left',
+      { ...style, fg: colorOf(visual.fg === COLOR_DEFAULT ? packStyleColor('text', env.theme) : visual.fg), attrs: visual.attrs },
+      env.theme.glyphs.ellipsis,
+    );
+  }
+
+  const footer = instance.props.footer;
+  if (sides.bottom && h > 1 && typeof footer === 'string' && footer !== '') {
+    paintBorderLabel(
+      surface, x, bottom, inner, ` ${footer} `,
+      (instance.props.footerAlign as 'left' | 'center' | 'right') ?? 'left',
+      { ...style, fg: colorOf(packStyleColor('muted', env.theme)), attrs: visual.attrs },
+      env.theme.glyphs.ellipsis,
+    );
+  }
+}
+
+function paintBorderLabel(
+  surface: PaintSurface,
+  x: number,
+  y: number,
+  inner: number,
+  label: string,
+  align: 'left' | 'center' | 'right',
+  style: CellStyle,
+  ellipsis: string,
+): void {
+  const text = truncate(sanitize(label), inner, ellipsis);
+  const w = stringWidth(text);
+  const offset =
+    align === 'center' ? Math.max(0, Math.floor((inner - w) / 2))
+      : align === 'right' ? Math.max(0, inner - w)
+        : 0;
+  surface.text(x + 1 + offset, y, text, style);
+}
+
+function paintText(
+  surface: PaintSurface,
+  box: LayoutBox,
+  visual: HostVisual,
+  instance: Instance,
+  env: PaintEnv,
+): void {
+  const content = sanitize(textContent(instance));
+  if (content === '') return;
+
+  const { content: area } = box;
+  if (area.width <= 0 || area.height <= 0) return;
+
+  const style: CellStyle = {
+    fg: colorOf(visual.fg),
+    bg: colorOf(visual.bg),
+    attrs: visual.attrs,
+    link: typeof instance.props.link === 'string' ? instance.props.link : undefined,
+  };
+
+  const wrap = visual.style.wrap ?? 'none';
+  const align = visual.style.textAlign ?? 'left';
+  // The ellipsis is a glyph like any other: on an ascii terminal it is '...'.
+  const ellipsis = typeof instance.props.ellipsis === 'string'
+    ? instance.props.ellipsis
+    : env.theme.glyphs.ellipsis;
+
+  // Where the cut goes, if there is one. `wrap` names it for the whole text;
+  // the older `truncate` prop still wins where both are set, so a caller that
+  // wants word wrap *and* an ellipsis on the last row can still ask for it -
+  // that is a combination `wrap` alone cannot express.
+  const wrapSide = truncateSideOf(wrap);
+  const explicit = instance.props.truncate as 'end' | 'start' | 'middle' | false | undefined;
+  const truncateSide = explicit ?? wrapSide;
+
+  const raw = wrapSide !== undefined
+    ? [oneLine(content)]
+    : wrap === 'none' ? content.split('\n') : wrapText(content, area.width, wrapModeOf(wrap));
+
+  for (let i = 0; i < raw.length && i < area.height; i++) {
+    let line = raw[i] as string;
+    if (stringWidth(line) > area.width) {
+      line = truncateSide === false
+        ? line
+        : truncate(line, area.width, ellipsis, truncateSide ?? 'end');
+    }
+    const w = stringWidth(line);
+    const offset =
+      align === 'center' ? Math.max(0, Math.floor((area.width - w) / 2))
+        : align === 'right' ? Math.max(0, area.width - w)
+          : 0;
+    surface.text(area.x + offset, area.y + i, line, style);
+  }
+}
+
+/**
+ * The escape hatch. A canvas draws in its own coordinate space starting at
+ * 0,0, clipped to its content box - so a chart can be written without knowing
+ * where on screen it landed.
+ */
+function paintCanvas(
+  buffer: Buffer,
+  box: LayoutBox,
+  instance: Instance,
+  env: PaintEnv,
+  clip: Rect,
+  /** The box's own resolved background, which is what it is drawn onto. */
+  background: PackedColor,
+): void {
+  const draw = instance.props.draw;
+  if (typeof draw !== 'function') return;
+
+  const area = box.content;
+  if (area.width <= 0 || area.height <= 0) return;
+
+  const surface = new Surface(buffer, area, rectIntersect(clip, area), background);
+  const ctx = createRenderContext(env.theme, env.capabilities, env.stateOf(instance));
+  try {
+    (draw as (s: PaintSurface, c: RenderContext) => void)(surface, ctx);
+  } catch (err) {
+    instance.runtime.onError(err, `canvas draw in <${instance.component}>`);
+  }
+}