claude-code/src/ink/screen.ts at main · hmmhmmhm/claude-code

Repository navigation

8000

import {

type AnsiCode,

ansiCodesToString,

diffAnsiCodes,

} from '@alcalzone/ansi-tokenize'

import {

type Point,

type Rectangle,

type Size,

unionRect,

} from './layout/geometry.js'

import { BEL, ESC, SEP } from './termio/ansi.js'

import * as warn from './warn.js'

// --- Shared Pools (interning for memory efficiency) ---

// Character string pool shared across all screens.

// With a shared pool, interned char IDs are valid across screens,

// so blitRegion can copy IDs directly (no re-interning) and

// diffEach can compare IDs as integers (no string lookup).

export class CharPool {

private strings: string[] = [' ', ''] // Index 0 = space, 1 = empty (spacer)

private stringMap = new Map<string, number>([

[' ', 0],

['', 1],

])

private ascii: Int32Array = initCharAscii() // charCode → index, -1 = not interned

intern(char: string): number {

// ASCII fast-path: direct array lookup instead of Map.get

if (char.length === 1) {

const code = char.charCodeAt(0)

if (code < 128) {

const cached = this.ascii[code]!

if (cached !== -1) return cached

const index = this.strings.length

this.strings.push(char)

this.ascii[code] = index

return index

}

const existing = this.stringMap.get(char)

if (existing !== undefined) return existing

const index = this.strings.length

this.strings.push(char)

this.stringMap.set(char, index)

return index

}

get(index: number): string {

return this.strings[index] ?? ' '

}

// Hyperlink string pool shared across all screens.

// Index 0 = no hyperlink.

export class HyperlinkPool {

private strings: string[] = [''] // Index 0 = no hyperlink

private stringMap = new Map<string, number>()

intern(hyperlink: string | undefined): number {

if (!hyperlink) return 0

let id = this.stringMap.get(hyperlink)

if (id === undefined) {

id = this.strings.length

this.strings.push(hyperlink)

this.stringMap.set(hyperlink, id)

}

return id

}

get(id: number): string | undefined {

return id === 0 ? undefined : this.strings[id]

}

// SGR 7 (inverse) as an AnsiCode. endCode '\x1b[27m' flags VISIBLE_ON_SPACE

// so bit 0 of the resulting styleId is set → renderer won't skip inverted

// spaces as invisible.

const INVERSE_CODE: AnsiCode = {

type: 'ansi',

code: '\x1b[7m',

endCode: '\x1b[27m',

}

// Bold (SGR 1) — stacks cleanly, no reflow in monospace. endCode 22

// also cancels dim (SGR 2); harmless here since we never add dim.

const BOLD_CODE: AnsiCode = {

type: 'ansi',

code: '\x1b[1m',

endCode: '\x1b[22m',

}

// Underline (SGR 4). Kept alongside yellow+bold — the underline is the

// unambiguous visible-on-any-theme marker. Yellow-bg-via-inverse can

// clash with existing bg colors (user-prompt style, tool chrome, syntax

// bg). If you see underline but no yellow, the yellow is being lost in

// the existing cell styling — the overlay IS finding the match.

const UNDERLINE_CODE: AnsiCode = {

type: 'ansi',

code: '\x1b[4m',

endCode: '\x1b[24m',

}

// fg→yellow (SGR 33). With inverse already in the stack, the terminal

// swaps fg↔bg at render — so yellow-fg becomes yellow-BG. Original bg

// becomes fg (readable on most themes: dark-bg → dark-text on yellow).

// endCode 39 is 'default fg' — cancels any prior fg color cleanly.

const YELLOW_FG_CODE: AnsiCode = {

type: 'ansi',

code: '\x1b[33m',

endCode: '\x1b[39m',

}

export class StylePool {

private ids = new Map<string, number>()

private styles: AnsiCode[][] = []

private transitionCache = new Map<number, string>()

readonly none: number

constructor() {

this.none = this.intern([])

}

/**

* Intern a style and return its ID. Bit 0 of the ID encodes whether the

* style has a visible effect on space characters (background, inverse,

* underline, etc.). Foreground-only styles get even IDs; styles visible

* on spaces get odd IDs. This lets the renderer skip invisible spaces

* with a single bitmask check on the packed word.

intern(styles: AnsiCode[]): number {

const key = styles.length === 0 ? '' : styles.map(s => s.code).join('\0')

let id = this.ids.get(key)

if (id === undefined) {

const rawId = this.styles.length

this.styles.push(styles.length === 0 ? [] : styles)

id =

(rawId << 1) |

(styles.length > 0 && hasVisibleSpaceEffect(styles) ? 1 : 0)

this.ids.set(key, id)

}

return id

}

/** Recover styles from an encoded ID. Strips the bit-0 flag via >>> 1. */

get(id: number): AnsiCode[] {

return this.styles[id >>> 1] ?? []

}

/**

* Returns the pre-serialized ANSI string to transition from one style to

* another. Cached by (fromId, toId) — zero allocations after first call

* for a given pair.

transition(fromId: number, toId: number): string {

if (fromId === toId) return ''

const key = fromId * 0x100000 + toId

let str = this.transitionCache.get(key)

if (str === undefined) {

str = ansiCodesToString(diffAnsiCodes(this.get(fromId), this.get(toId)))

this.transitionCache.set(key, str)

}

return str

}

/**

* Intern a style that is `base + inverse`. Cached by base ID so

* repeated calls for the same underlying style don't re-scan the

* AnsiCode[] array. Used by the selection overlay.

private inverseCache = new Map<number, number>()

withInverse(baseId: number): number {

let id = this.inverseCache.get(baseId)

if (id === undefined) {

const baseCodes = this.get(baseId)

// If already inverted, use as-is (avoids SGR 7 stacking)

const hasInverse = baseCodes.some(c => c.endCode === '\x1b[27m')

id = hasInverse ? baseId : this.intern([...baseCodes, INVERSE_CODE])

this.inverseCache.set(baseId, id)

}

return id

}

/** Inverse + bold + yellow-bg-via-fg-swap for the CURRENT search match.

* OTHER matches are plain inverse — bg inherits from the theme. Current

* gets a distinct yellow bg (via fg-then-inverse swap) plus bold weight

* so it stands out in a sea of inverse. Underline was too subtle. Zero

* reflow risk: all pure SGR overlays, per-cell, post-layout. The yellow

* overrides any existing fg (syntax highlighting) on those cells — fine,

* the "you are here" signal IS the point, syntax color can yield. */

private currentMatchCache = new Map<number, number>()

withCurrentMatch(baseId: number): number {

let id = this.currentMatchCache.get(baseId)

if (id === undefined) {

const baseCodes = this.get(baseId)

// Filter BOTH fg + bg so yellow-via-inverse is unambiguous.

// User-prompt cells have an explicit bg (grey box); with that bg

// still set, inverse swaps yellow-fg↔grey-bg → grey-on-yellow on

// SOME terminals, yellow-on-grey on others (inverse semantics vary

// when both colors are explicit). Filtering both gives clean

// yellow-bg + terminal-default-fg everywhere. Bold/dim/italic

// coexist — keep those.

const codes = baseCodes.filter(

c => c.endCode !== '\x1b[39m' && c.endCode !== '\x1b[49m',

)

// fg-yellow FIRST so inverse swaps it to bg. Bold after inverse is

// fine — SGR 1 is fg-attribute-only, order-independent vs 7.

codes.push(YELLOW_FG_CODE)

if (!baseCodes.some(c => c.endCode === '\x1b[27m'))

codes.push(INVERSE_CODE)

if (!baseCodes.some(c => c.endCode === '\x1b[22m')) codes.push(BOLD_CODE)

// Underline as the unambiguous marker — yellow-bg can clash with

// existing bg styling (user-prompt bg, syntax bg). If you see

// underline but no yellow on a match, the overlay IS finding it;

// the yellow is just losing a styling fight.

if (!baseCodes.some(c => c.endCode === '\x1b[24m'))

codes.push(UNDERLINE_CODE)

id = this.intern(codes)

this.currentMatchCache.set(baseId, id)

}

return id

}

/**

* Selection overlay: REPLACE the cell's background with a solid color

* while preserving its foreground (color, bold, italic, dim, underline).

* Matches native terminal selection — a dedicated bg color, not SGR-7

* inverse. Inverse swaps fg/bg per-cell, which fragments visually over

* syntax-highlighted text (every fg color becomes a different bg stripe).

* Strips any existing bg (endCode 49m — REPLACES, so diff-added green

* etc. don't bleed through) and any existing inverse (endCode 27m —

* inverse on top of a solid bg would re-swap and look wrong).

* bg is set via setSelectionBg(); null → fallback to withInverse() so the

* overlay still works before theme wiring sets a color (tests, first frame).

* Cache is keyed by baseId only — setSelectionBg() clears it on change.

private selectionBgCode: AnsiCode | null = null

private selectionBgCache = new Map<number, number>()

setSelectionBg(bg: AnsiCode | null): void {

if (this.selectionBgCode?.code === bg?.code) return

this.selectionBgCode = bg

this.selectionBgCache.clear()

}

withSelectionBg(baseId: number): number {

const bg = this.selectionBgCode

if (bg === null) return this.withInverse(baseId)

let id = this.selectionBgCache.get(baseId)

if (id === undefined) {

// Keep everything except bg (49m) and inverse (27m). Fg, bold, dim,

// italic, underline, strikethrough all preserved.

const kept = this.get(baseId).filter(

c => c.endCode !== '\x1b[49m' && c.endCode !== '\x1b[27m',

)

kept.push(bg)

id = this.intern(kept)

this.selectionBgCache.set(baseId, id)

}

return id

}

// endCodes that produce visible effects on space characters

const VISIBLE_ON_SPACE = new Set([

'\x1b[49m', // background color

'\x1b[27m', // inverse

'\x1b[24m', // underline

'\x1b[29m', // strikethrough

'\x1b[55m', // overline

])

function hasVisibleSpaceEffect(styles: AnsiCode[]): boolean {

for (const style of styles) {

if (VISIBLE_ON_SPACE.has(style.endCode)) return true

}

return false

}

/**

* Cell width classification for handling double-wide characters (CJK, emoji,

* etc.)

* We use explicit spacer cells rather than inferring width at render time. This

* makes the data structure self-describing and simplifies cursor positioning

* logic.

* @see https://mitchellh.com/writing/grapheme-clusters-in-terminals

// const enum is inlined at compile time - no runtime object, no property access

export const enum CellWidth {

// Not a wide character, cell width 1

Narrow = 0,

// Wide character, cell width 2. This cell contains the actual character.

Wide = 1,

// Spacer occupying the second visual column of a wide character. Do not render.

SpacerTail = 2,

// Spacer at the end of a soft-wrapped line indicating that a wide character

// continues on the next line. Used for preserving wide character semantics

// across line breaks during soft wrapping.

SpacerHead = 3,

}

export type Hyperlink = string | undefined

/**

* Cell is a view type returned by cellAt(). Cells are stored as packed typed

* arrays internally to avoid GC pressure from allocating objects per cell.

export type Cell = {

char: string

styleId: number

width: CellWidth

hyperlink: Hyperlink

}

// Constants for empty/spacer cells to enable fast comparisons

// These are indices into the charStrings table, not codepoints

const EMPTY_CHAR_INDEX = 0 // ' ' (space)

const SPACER_CHAR_INDEX = 1 // '' (empty string for spacer cells)

// Unwritten cells are [EMPTY_CHAR_INDEX=0, packWord1(emptyStyleId=0,0,0)=0].

// Since StylePool.none is always 0 (first intern), unwritten cells are

// indistinguishable from explicitly-cleared cells in the packed array.

// This is intentional: diffEach can compare raw ints with zero normalization.

// isEmptyCellByIndex checks if both words are 0 to identify "never visually written" cells.

function initCharAscii(): Int32Array {

const table = new Int32Array(128)

table.fill(-1)

table[32] = EMPTY_CHAR_INDEX // ' ' (space)

return table

}

// --- Packed cell layout ---

// Each cell is 2 consecutive Int32 elements in the cells array:

// word0 (cells[ci]): charId (full 32 bits)

// word1 (cells[ci + 1]): styleId[31:17] | hyperlinkId[16:2] | width[1:0]

const STYLE_SHIFT = 17

const HYPERLINK_SHIFT = 2

const HYPERLINK_MASK = 0x7fff // 15 bits

const WIDTH_MASK = 3 // 2 bits

// Pack styleId, hyperlinkId, and width into a single Int32

function packWord1(

styleId: number,

hyperlinkId: number,

width: number,

): number {

return (styleId << STYLE_SHIFT) | (hyperlinkId << HYPERLINK_SHIFT) | width

}

// Unwritten cell as BigInt64 — both words are 0, so the 64-bit value is 0n.

// Used by BigInt64Array.fill() for bulk clears (resetScreen, clearRegion).

// Not used for comparison — BigInt element reads cause heap allocation.

const EMPTY_CELL_VALUE = 0n

/**

* Screen uses a packed Int32Array instead of Cell objects to eliminate GC

* pressure. For a 200x120 screen, this avoids allocating 24,000 objects.

* Cell data is stored as 2 Int32s per cell in a single contiguous array:

* word0: charId (full 32 bits — index into CharPool)

* word1: styleId[31:17] | hyperlinkId[16:2] | width[1:0]

* This layout halves memory accesses in diffEach (2 int loads vs 4) and

* enables future SIMD comparison via Bun.indexOfFirstDifference.

export type Screen = Size & {

// Packed cell data — 2 Int32s per cell: [charId, packed(styleId|hyperlinkId|width)]

// cells and cells64 are views over the same ArrayBuffer.

cells: Int32Array

cells64: BigInt64Array // 1 BigInt64 per cell — used for bulk fill in resetScreen/clearRegion

// Shared pools — IDs are valid across all screens using the same pools

charPool: CharPool

hyperlinkPool: HyperlinkPool

// Empty style ID for comparisons

emptyStyleId: number

/**

* Bounding box of cells that were written to (not blitted) during rendering.

* Used by diff() to limit iteration to only the region that could have changed.

damage: Rectangle | undefined

/**

* Per-cell noSelect bitmap — 1 byte per cell, 1 = exclude from text

* selection (copy + highlight). Used by <NoSelect> to mark gutters

* (line numbers, diff sigils) so click-drag over a diff yields clean

* copyable code. Fully reset each frame in resetScreen; blitRegion

* copies it alongside cells so the blit optimization preserves marks.

noSelect: Uint8Array

/**

* Per-ROW soft-wrap continuation marker. softWrap[r]=N>0 means row r

* is a word-wrap continuation of row r-1 (the `\n` before it was

* inserted by wrapAnsi, not in the source), and row r-1's written

* content ends at absolute column N (exclusive — cells [0..N) are the

* fragment, past N is unwritten padding). 0 means row r is NOT a

* continuation (hard newline or first row). Selection copy checks

* softWrap[r]>0 to join row r onto row r-1 without a newline, and

* reads softWrap[r+1] to know row r's content end when row r+1

* continues from it. The content-end column is needed because an

* unwritten cell and a written-unstyled-space are indistinguishable in

* the packed typed array (both all-zero) — without it we'd either drop

* the word-separator space (trim) or include trailing padding (no

* trim). This encoding (continuation-on-self, prev-content-end-here)

* is chosen so shiftRows preserves the is-continuation semantics: when

* row r scrolls off the top and row r+1 shifts to row r, sw[r] gets

* old sw[r+1] — which correctly says the new row r is a continuation

10000

* of what's now in scrolledOffAbove. Reset each frame; copied by

* blitRegion/shiftRows.

softWrap: Int32Array

}

function isEmptyCellByIndex(screen: Screen, index: number): boolean {

// An empty/unwritten cell has both words === 0:

// word0 = EMPTY_CHAR_INDEX (0), word1 = packWord1(emptyStyleId=0, 0, 0) = 0.

const ci = index << 1

return screen.cells[ci] === 0 && screen.cells[ci | 1] === 0

}

export function isEmptyCellAt(screen: Screen, x: number, y: number): boolean {

if (x < 0 || y < 0 || x >= screen.width || y >= screen.height) return true

return isEmptyCellByIndex(screen, y * screen.width + x)

}

/**

* Check if a Cell (view object) represents an empty cell.

export function isCellEmpty(screen: Screen, cell: Cell): boolean {

// Check if cell looks like an empty cell (space, empty style, narrow, no link).

// Note: After cellAt mapping, unwritten cells have emptyStyleId, so this

// returns true for both unwritten AND cleared cells. Use isEmptyCellAt

// for the internal distinction.

return (

cell.char === ' ' &&

cell.styleId === screen.emptyStyleId &&

cell.width === CellWidth.Narrow &&

!cell.hyperlink

)

}

// Intern a hyperlink string and return its ID (0 = no hyperlink)

function internHyperlink(screen: Screen, hyperlink: Hyperlink): number {

return screen.hyperlinkPool.intern(hyperlink)

}

// ---

export function createScreen(

width: number,

height: number,

styles: StylePool,

charPool: CharPool,

hyperlinkPool: HyperlinkPool,

): Screen {

// Warn if dimensions are not valid integers (likely bad yoga layout output)

warn.ifNotInteger(width, 'createScreen width')

warn.ifNotInteger(height, 'createScreen height')

// Ensure width and height are valid integers to prevent crashes

if (!Number.isInteger(width) || width < 0) {

width = Math.max(0, Math.floor(width) || 0)

}

if (!Number.isInteger(height) || height < 0) {

height = Math.max(0, Math.floor(height) || 0)

}

const size = width * height

// Allocate one buffer, two views: Int32Array for per-word access,

// BigInt64Array for bulk fill in resetScreen/clearRegion.

// ArrayBuffer is zero-filled, which is exactly the empty cell value:

// [EMPTY_CHAR_INDEX=0, packWord1(emptyStyleId=0,0,0)=0].

const buf = new ArrayBuffer(size << 3) // 8 bytes per cell

const cells = new Int32Array(buf)

const cells64 = new BigInt64Array(buf)

return {

width,

height,

cells,

cells64,

charPool,

hyperlinkPool,

emptyStyleId: styles.none,

damage: undefined,

noSelect: new Uint8Array(size),

softWrap: new Int32Array(height),

}

/**

* Reset an existing screen for reuse, avoiding allocation of new typed arrays.

* Resizes if needed and clears all cells to empty/unwritten state.

* For double-buffering, this allows swapping between front and back buffers

* without allocating new Screen objects each frame.

export function resetScreen(

screen: Screen,

width: number,

height: number,

): void {

// Warn if dimensions are not valid integers

warn.ifNotInteger(width, 'resetScreen width')

warn.ifNotInteger(height, 'resetScreen height')

// Ensure width and height are valid integers to prevent crashes

if (!Number.isInteger(width) || width < 0) {

width = Math.max(0, Math.floor(width) || 0)

}

if (!Number.isInteger(height) || height < 0) {

height = Math.max(0, Math.floor(height) || 0)

}

const size = width * height

// Resize if needed (only grow, to avoid reallocations)

if (screen.cells64.length < size) {

const buf = new ArrayBuffer(size << 3)

screen.cells = new Int32Array(buf)

screen.cells64 = new BigInt64Array(buf)

screen.noSelect = new Uint8Array(size)

}

if (screen.softWrap.length < height) {

screen.softWrap = new Int32Array(height)

}

// Reset all cells — single fill call, no loop

screen.cells64.fill(EMPTY_CELL_VALUE, 0, size)

screen.noSelect.fill(0, 0, size)

screen.softWrap.fill(0, 0, height)

// Update dimensions

screen.width = width

screen.height = height

// Shared pools accumulate — no clearing needed. Unique char/hyperlink sets are bounded.

// Clear damage tracking

screen.damage = undefined

}

/**

* Re-intern a screen's char and hyperlink IDs into new pools.

* Used for generational pool reset — after migrating, the screen's

* typed arrays contain valid IDs for the new pools, and the old pools

* can be GC'd.

* O(width * height) but only called occasionally (e.g., between conversation turns).

export function migrateScreenPools(

screen: Screen,

charPool: CharPool,

hyperlinkPool: HyperlinkPool,

): void {

const oldCharPool = screen.charPool

const oldHyperlinkPool = screen.hyperlinkPool

if (oldCharPool === charPool && oldHyperlinkPool === hyperlinkPool) return

const size = screen.width * screen.height

const cells = screen.cells

// Re-intern chars and hyperlinks in a single pass, stride by 2

for (let ci = 0; ci < size << 1; ci += 2) {

// Re-intern charId (word0)

const oldCharId = cells[ci]!

cells[ci] = charPool.intern(oldCharPool.get(oldCharId))

// Re-intern hyperlinkId (packed in word1)

const word1 = cells[ci + 1]!

const oldHyperlinkId = (word1 >>> HYPERLINK_SHIFT) & HYPERLINK_MASK

if (oldHyperlinkId !== 0) {

const oldStr = oldHyperlinkPool.get(oldHyperlinkId)

const newHyperlinkId = hyperlinkPool.intern(oldStr)

// Repack word1 with new hyperlinkId, preserving styleId and width

const styleId = word1 >>> STYLE_SHIFT

const width = word1 & WIDTH_MASK

cells[ci + 1] = packWord1(styleId, newHyperlinkId, width)

}

screen.charPool = charPool

screen.hyperlinkPool = hyperlinkPool

}

/**

* Get a Cell view at the given position. Returns a new object each call -

* this is intentional as cells are stored packed, not as objects.

export function cellAt(screen: Screen, x: number, y: number): Cell | undefined {

if (x < 0 || y < 0 || x >= screen.width || y >= screen.height)

return undefined

return cellAtIndex(screen, y * screen.width + x)

}

/**

* Get a Cell view by pre-computed array index. Skips bounds checks and

* index computation — caller must ensure index is valid.

export function cellAtIndex(screen: Screen, index: number): Cell {

const ci = index << 1

const word1 = screen.cells[ci + 1]!

const hid = (word1 >>> HYPERLINK_SHIFT) & HYPERLINK_MASK

return {

// Unwritten cells have charIndex=0 (EMPTY_CHAR_INDEX); charPool.get(0) returns ' '

char: screen.charPool.get(screen.cells[ci]!),

styleId: word1 >>> STYLE_SHIFT,

width: word1 & WIDTH_MASK,

hyperlink: hid === 0 ? undefined : screen.hyperlinkPool.get(hid),

}

/**

* Get a Cell at the given index, or undefined if it has no visible content.

* Returns undefined for spacer cells (charId 1), empty unstyled spaces, and

* fg-only styled spaces that match lastRenderedStyleId (cursor-forward

* produces an identical visual result, avoiding a Cell allocation).

* @param lastRenderedStyleId - styleId of the last rendered cell on this

* line, or -1 if none yet.

export function visibleCellAtIndex(

cells: Int32Array,

charPool: CharPool,

hyperlinkPool: HyperlinkPool,

index: number,

lastRenderedStyleId: number,

): Cell | undefined {

const ci = index << 1

const charId = cells[ci]!

if (charId === 1) return undefined // spacer

const word1 = cells[ci + 1]!

// For spaces: 0x3fffc masks bits 2-17 (hyperlinkId + styleId visibility

// bit). If zero, the space has no hyperlink and at most a fg-only style.

// Then word1 >>> STYLE_SHIFT is the foreground style — skip if it's zero

// (truly invisible) or matches the last rendered style on this line.

if (charId === 0 && (word1 & 0x3fffc) === 0) {

const fgStyle = word1 >>> STYLE_SHIFT

if (fgStyle === 0 || fgStyle === lastRenderedStyleId) return undefined

}

const hid = (word1 >>> HYPERLINK_SHIFT) & HYPERLINK_MASK

return {

char: charPool.get(charId),

styleId: word1 >>> STYLE_SHIFT,

width: word1 & WIDTH_MASK,

hyperlink: hid === 0 ? undefined : hyperlinkPool.get(hid),

}

/**

* Write cell data into an existing Cell object to avoid allocation.

* Caller must ensure index is valid.

function cellAtCI(screen: Screen, ci: number, out: Cell): void {

const w1 = ci | 1

const word1 = screen.cells[w1]!

out.char = screen.charPool.get(screen.cells[ci]!)

out.styleId = word1 >>> STYLE_SHIFT

out.width = word1 & WIDTH_MASK

const hid = (word1 >>> HYPERLINK_SHIFT) & HYPERLINK_MASK

out.hyperlink = hid === 0 ? undefined : screen.hyperlinkPool.get(hid)

}

10BC8

export function charInCellAt(

screen: Screen,

x: number,

y: number,

): string | undefined {

if (x < 0 || y < 0 || x >= screen.width || y >= screen.height)

return undefined

const ci = (y * screen.width + x) << 1

return screen.charPool.get(screen.cells[ci]!)

}

/**

* Set a cell, optionally creating a spacer for wide characters.

* Wide characters (CJK, emoji) occupy 2 cells in the buffer:

* 1. First cell: Contains the actual character with width = Wide

* 2. Second cell: Spacer cell with width = SpacerTail (empty, not rendered)

* If the cell has width = Wide, this function automatically creates the

* corresponding SpacerTail in the next column. This two-cell model keeps

* the buffer aligned to visual columns, making cursor positioning

* straightforward.

* TODO: When soft-wrapping is implemented, SpacerHead cells will be explicitly

* placed by the wrapping logic at line-end positions where wide characters

* wrap to the next line. This function doesn't need to handle SpacerHead

* automatically - it will be set directly by the wrapping code.

export function setCellAt(

screen: Screen,

x: number,

y: number,

cell: Cell,

): void {

if (x < 0 || y < 0 || x >= screen.width || y >= screen.height) return

const ci = (y * screen.width + x) << 1

const cells = screen.cells

// When a Wide char is overwritten by a Narrow char, its SpacerTail remains

// as a ghost cell that the diff/render pipeline skips, causing stale content

// to leak through from previous frames.

const prevWidth = cells[ci + 1]! & WIDTH_MASK

if (prevWidth === CellWidth.Wide && cell.width !== CellWidth.Wide) {

const spacerX = x + 1

if (spacerX < screen.width) {

const spacerCI = ci + 2

if ((cells[spacerCI + 1]! & WIDTH_MASK) === CellWidth.SpacerTail) {

cells[spacerCI] = EMPTY_CHAR_INDEX

cells[spacerCI + 1] = packWord1(

screen.emptyStyleId,

CellWidth.Narrow,

)

}

// Track cleared Wide position for damage expansion below

let clearedWideX = -1

if (

prevWidth === CellWidth.SpacerTail &&

cell.width !== CellWidth.SpacerTail

) {

// Overwriting a SpacerTail: clear the orphaned Wide char at (x-1).

// Keeping the wide character with Narrow width would cause the terminal

// to still render it with width 2, desyncing the cursor model.

if (x > 0) {

const wideCI = ci - 2

if ((cells[wideCI + 1]! & WIDTH_MASK) === CellWidth.Wide) {

cells[wideCI] = EMPTY_CHAR_INDEX

cells[wideCI + 1] = packWord1(screen.emptyStyleId, 0, CellWidth.Narrow)

clearedWideX = x - 1

}

// Pack cell data into cells array

cells[ci] = internCharString(screen, cell.char)

cells[ci + 1] = packWord1(

cell.styleId,

internHyperlink(screen, cell.hyperlink),

cell.width,

)

// Track damage - expand bounds in place instead of allocating new objects

// Include the main cell position and any cleared orphan cells

const minX = clearedWideX >= 0 ? Math.min(x, clearedWideX) : x

const damage = screen.damage

if (damage) {

const right = damage.x + damage.width

const bottom = damage.y + damage.height

if (minX < damage.x) {

damage.width += damage.x - minX

damage.x = minX

} else if (x >= right) {

damage.width = x - damage.x + 1

}

if (y < damage.y) {

damage.height += damage.y - y

damage.y = y

} else if (y >= bottom) {

damage.height = y - damage.y + 1

}

} else {

screen.damage = { x: minX, y, width: x - minX + 1, height: 1 }

}

// If this is a wide character, create a spacer in the next column

if (cell.width === CellWidth.Wide) {

const spacerX = x + 1

if (spacerX < screen.width) {

const spacerCI = ci + 2

// If the cell we're overwriting with our SpacerTail is itself Wide,

// clear ITS SpacerTail at x+2 too. Otherwise the orphan SpacerTail

// makes diffEach report it as `added` and log-update's skip-spacer

// rule prevents clearing whatever prev content was at that column.

// Scenario: [a, 💻, spacer] → [本, spacer, ORPHAN spacer] when

// yoga squishes a💻 to height 0 and 本 renders at the same y.

if ((cells[spacerCI + 1]! & WIDTH_MASK) === CellWidth.Wide) {

const orphanCI = spacerCI + 2

if (

spacerX + 1 < screen.width &&

(cells[orphanCI + 1]! & WIDTH_MASK) === CellWidth.SpacerTail

) {

cells[orphanCI] = EMPTY_CHAR_INDEX

cells[orphanCI + 1] = packWord1(

screen.emptyStyleId,

CellWidth.Narrow,

)

}

cells[spacerCI] = SPACER_CHAR_INDEX

cells[spacerCI + 1] = packWord1(

screen.emptyStyleId,

CellWidth.SpacerTail,

)

// Expand damage to include SpacerTail so diff() scans it

const d = screen.damage

if (d && spacerX >= d.x + d.width) {

d.width = spacerX - d.x + 1

}

/**

* Replace the styleId of a cell in-place without disturbing char, width,

* or hyperlink. Preserves empty cells as-is (char stays ' '). Tracks damage

* for the cell so diffEach picks up the change.

export function setCellStyleId(

screen: Screen,

x: number,

y: number,

styleId: number,

): void {

if (x < 0 || y < 0 || x >= screen.width || y >= screen.height) return

const ci = (y * screen.width + x) << 1

const cells = screen.cells

const word1 = cells[ci + 1]!

const width = word1 & WIDTH_MASK

// Skip spacer cells — inverse on the head cell visually covers both columns

if (width === CellWidth.SpacerTail || width === CellWidth.SpacerHead) return

const hid = (word1 >>> HYPERLINK_SHIFT) & HYPERLINK_MASK

cells[ci + 1] = packWord1(styleId, hid, width)

// Expand damage so diffEach scans this cell

const d = screen.damage

if (d) {

screen.damage = unionRect(d, { x, y, width: 1, height: 1 })

} else {

screen.damage = { x, y, width: 1, height: 1 }

}

/**

* Intern a character string via the screen's shared CharPool.

* Supports grapheme clusters like family emoji.

function internCharString(screen: Screen, char: string): number {

return screen.charPool.intern(char)

}

/**

* Bulk-copy a rectangular region from src to dst using TypedArray.set().

* Single cells.set() call per row (or one call for contiguous blocks).

* Damage is computed once for the whole region.

* Clamps negative regionX/regionY to 0 (matching clearRegion) — absolute-

* positioned overlays in tiny terminals can compute negative screen coords.

* maxX/maxY should already be clamped to both screen bounds by the caller.

export function blitRegion(

dst: Screen,

src: Screen,

regionX: number,

regionY: number,

maxX: number,

maxY: number,

): void {

regionX = Math.max(0, regionX)

regionY = Math.max(0, regionY)

if (regionX >= maxX || regionY >= maxY) return

const rowLen = maxX - regionX

const srcStride = src.width << 1

const dstStride = dst.width << 1

const rowBytes = rowLen << 1 // 2 Int32s per cell

const srcCells = src.cells

const dstCells = dst.cells

const srcNoSel = src.noSelect

const dstNoSel = dst.noSelect

// softWrap is per-row — copy the row range regardless of stride/width.

// Partial-width blits still carry the row's wrap provenance since the

// blitted content (a cached ink-text node) is what set the bit.

dst.softWrap.set(src.softWrap.subarray(regionY, maxY), regionY)

// Fast path: contiguous memory when copying full-width rows at same stride

if (regionX === 0 && maxX === src.width && src.width === dst.width) {

const srcStart = regionY * srcStride

const totalBytes = (maxY - regionY) * srcStride

dstCells.set(

srcCells.subarray(srcStart, srcStart + totalBytes),

srcStart, // srcStart === dstStart when strides match and regionX === 0

)

// noSelect is 1 byte/cell vs cells' 8 — same region, different scale

const nsStart = regionY * src.width

const nsLen = (maxY - regionY) * src.width

dstNoSel.set(srcNoSel.subarray(nsStart, nsStart + nsLen), nsStart)

} else {

// Per-row copy for partial-width or mismatched-stride regions

let srcRowCI = regionY * srcStride + (regionX << 1)

let dstRowCI = regionY * dstStride + (regionX << 1)

let srcRowNS = regionY * src.width + regionX

let dstRowNS = regionY * dst.width + regionX

for (let y = regionY; y < maxY; y++) {

dstCells.set(srcCells.subarray(srcRowCI, srcRowCI + rowBytes), dstRowCI)

dstNoSel.set(srcNoSel.subarray(srcRowNS, srcRowNS + rowLen), dstRowNS)

srcRowCI += srcStride

dstRowCI += dstStride

srcRowNS += src.width

dstRowNS += dst.width

}

// Compute damage once for the whole region

const regionRect = {

x: regionX,

y: regionY,

width: rowLen,

height: maxY - regionY,

}

if (dst.damage) {

dst.damage = unionRect(dst.damage, regionRect)

} else {

dst.damage = regionRect

}

// Handle wide char at right edge: spacer might be outside blit region

// but still within dst bounds. Per-row check only at the boundary column.

if (maxX < dst.width) {

let srcLastCI = (regionY * src.width + (maxX - 1)) << 1

let dstSpacerCI = (regionY * dst.width + maxX) << 1

let wroteSpacerOutsideRegion = false

for (let y = regionY; y < maxY; y++) {

if ((srcCells[srcLastCI + 1]! & WIDTH_MASK) === CellWidth.Wide) {

dstCells[dstSpacerCI] = SPACER_CHAR_INDEX

dstCells[dstSpacerCI + 1] = packWord1(

dst.emptyStyleId,

CellWidth.SpacerTail,

)

wroteSpacerOutsideRegion = true

}

srcLastCI += srcStride

dstSpacerCI += dstStride

}

// Expand damage to include SpacerTail column if we wrote any

if (wroteSpacerOutsideRegion && dst.damage) {

const rightEdge = dst.damage.x + dst.damage.width

if (rightEdge === maxX) {

dst.damage = { ...dst.damage, width: dst.damage.width + 1 }

}

/**

* Bulk-clear a rectangular region of the screen.

* Uses BigInt64Array.fill() for fast row clears.

* Handles wide character boundary cleanup at region edges.

export function clearRegion(

screen: Screen,

regionX: number,

regionY: number,

regionWidth: number,

regionHeight: number,

): void {

const startX = Math.max(0, regionX)

const startY = Math.max(0, regionY)

const maxX = Math.min(regionX + regionWidth, screen.width)

const maxY = Math.min(regionY + regionHeight, screen.height)

if (startX >= maxX || startY >= maxY) return

const cells = screen.cells

const cells64 = screen.cells64

const screenWidth = screen.width

const rowBase = startY * screenWidth

let damageMinX = startX

let damageMaxX = maxX

// EMPTY_CELL_VALUE (0n) matches the zero-initialized state:

// word0=EMPTY_CHAR_INDEX(0), word1=packWord1(0,0,0)=0

if (startX === 0 && maxX === screenWidth) {

// Full-width: single fill, no boundary checks needed

cells64.fill(

EMPTY_CELL_VALUE,

rowBase,

rowBase + (maxY - startY) * screenWidth,

)

} else {

// Partial-width: single loop handles boundary cleanup and fill per row.

const stride = screenWidth << 1 // 2 Int32s per cell

const rowLen = maxX - startX

const checkLeft = startX > 0

const checkRight = maxX < screenWidth

let leftEdge = (rowBase + startX) << 1

let rightEdge = (rowBase + maxX - 1) << 1

let fillStart = rowBase + startX

for (let y = startY; y < maxY; y++) {

// Left boundary: if cell at startX is a SpacerTail, the Wide char

// at startX-1 (outside the region) will be orphaned. Clear it.

View remainder of file in raw view

FilesExpand file tree

screen.ts

Latest commit

History

screen.ts

File metadata and controls