@alchemy.run/sigil 0.0.0-alpha.4 → 0.0.0-alpha.6

package/src/screen/screen.ts

@@ -0,0 +1,305 @@
+import { blend } from "#/color/sample.ts";
+import { createCell, emptyCell, type Cell, type CellPatch, type CellStyle } from "#/screen/cell.ts";
+import type { Rect } from "#/screen/geometry.ts";
+
+export type Line = readonly Cell[];
+
+/** A half-open range of changed columns in one row. */
+export type DirtySpan = {
+  readonly y: number;
+  readonly start: number;
+  readonly end: number;
+};
+
+/**
+A mutable two-dimensional terminal cell buffer. Cells themselves are immutable,
+so current and next screens can compare them by value or safely share constants.
+*/
+export class Screen {
+  #width: number;
+  #height: number;
+
+  #rows: Cell[][];
+  #painted: boolean[][];
+  #dirty: Array<{ start: number; end: number } | undefined>;
+
+  constructor(width: number, height: number) {
+    validateDimensions(width, height);
+
+    this.#width = width;
+    this.#height = height;
+    this.#rows = Array.from({ length: height }, () => Array<Cell>(width).fill(emptyCell));
+    this.#painted = Array.from({ length: height }, () => Array<boolean>(width).fill(false));
+    this.#dirty = Array.from({ length: height }, () =>
+      width > 0 ? { start: 0, end: width } : undefined,
+    );
+  }
+
+  get width(): number {
+    return this.#width;
+  }
+
+  /**
+  The populated length of one row: the nominal width, or more when overflow
+  writes (`textWrap: "none"` content) extended it past the screen's width.
+  */
+  rowLength(y: number): number {
+    return Math.max(this.#width, this.#rows[y]?.length ?? 0);
+  }
+
+  get height(): number {
+    return this.#height;
+  }
+
+  bounds(): Rect {
+    return { x: 0, y: 0, width: this.width, height: this.height };
+  }
+
+  cellAt(x: number, y: number): Cell | undefined {
+    return this.#rows[y]?.[x];
+  }
+
+  /** Whether a drawable explicitly touched this position. */
+  isPainted(x: number, y: number): boolean {
+    return this.#painted[y]?.[x] ?? false;
+  }
+
+  setCell(x: number, y: number, cell: Cell, options?: { overflow?: boolean }): void {
+    const row = this.#rows[y];
+    const overflow = options?.overflow === true;
+    if (!row || x < 0 || (!overflow && x >= this.width)) {
+      return;
+    }
+
+    if (!Number.isInteger(cell.width) || cell.width < 1) {
+      throw new Error("Only leading cells with a positive width may be written");
+    }
+
+    const finalColumn = x + cell.width;
+    if (overflow && finalColumn > row.length) {
+      this.#growRow(row, y, finalColumn);
+    }
+
+    const capacity = overflow ? row.length : this.width;
+    const clipped = finalColumn > capacity;
+    const overwriteEnd = Math.min(finalColumn, capacity);
+
+    for (let column = x; column < overwriteEnd; column++) {
+      this.#clearGraphemeAt(row, y, column);
+    }
+
+    if (clipped) {
+      for (let column = x; column < capacity; column++) {
+        row[column] = emptyCell;
+      }
+      this.#markDirty(y, x, capacity);
+
+      return;
+    }
+
+    row[x] = cell;
+    this.#painted[y]![x] = true;
+
+    for (let column = x + 1; column < finalColumn; column++) {
+      row[column] = {
+        grapheme: "",
+        width: 0,
+        style: cell.style,
+        ...(cell.hyperlink ? { hyperlink: cell.hyperlink } : {}),
+      };
+      this.#painted[y]![column] = true;
+    }
+    this.#markDirty(y, x, finalColumn);
+  }
+
+  /**
+  Composes independent cell channels over the existing cell. An undefined
+  patch is transparent; an explicit space in `content` paints a blank.
+  */
+  composeCell(
+    x: number,
+    y: number,
+    patch: CellPatch | undefined,
+    options?: { overflow?: boolean },
+  ): void {
+    if (!patch) {
+      return;
+    }
+
+    const row = this.#rows[y];
+    if (!row || x < 0 || (options?.overflow !== true && x >= this.width)) {
+      return;
+    }
+
+    let leadingColumn = x;
+    while (leadingColumn > 0 && row[leadingColumn]?.width === 0) {
+      leadingColumn--;
+    }
+
+    const destination = row[leadingColumn] ?? emptyCell;
+    const writeColumn = patch.content ? x : leadingColumn;
+    const style: CellStyle = {
+      ...this.#composeColor(destination.style, patch, "foreground"),
+      ...this.#composeColor(destination.style, patch, "background"),
+      ...this.#composeColor(destination.style, patch, "underlineColor"),
+      underline: patch.underline ?? destination.style.underline,
+      attributes: patch.attributes ?? destination.style.attributes,
+    };
+    const content = patch.content ?? destination;
+    const hyperlink =
+      patch.hyperlink === undefined ? destination.hyperlink : (patch.hyperlink ?? undefined);
+
+    this.setCell(
+      writeColumn,
+      y,
+      createCell(content.grapheme, content.width, style, hyperlink),
+      options,
+    );
+  }
+
+  /** Composes a patch throughout a rectangle, clipped to this screen. */
+  fill(bounds: Rect, patch: CellPatch | undefined): void {
+    if (!patch) {
+      return;
+    }
+
+    const startX = Math.max(0, bounds.x);
+    const startY = Math.max(0, bounds.y);
+    const endX = Math.min(this.width, bounds.x + bounds.width);
+    const endY = Math.min(this.height, bounds.y + bounds.height);
+    const step = Math.max(1, patch.content?.width ?? 1);
+
+    for (let y = startY; y < endY; y++) {
+      for (let x = startX; x < endX; x += step) {
+        this.composeCell(x, y, patch);
+      }
+    }
+  }
+
+  /** Resizes while preserving complete graphemes in the shared top-left area. */
+  resize(width: number, height: number): void {
+    validateDimensions(width, height);
+
+    const rows = Array.from({ length: height }, () => Array<Cell>(width).fill(emptyCell));
+    const painted = Array.from({ length: height }, () => Array<boolean>(width).fill(false));
+    const sharedHeight = Math.min(height, this.height);
+
+    for (let y = 0; y < sharedHeight; y++) {
+      const source = this.#rows[y]!;
+      const destination = rows[y]!;
+      for (let x = 0; x < Math.min(width, this.width); x++) {
+        const cell = source[x]!;
+        if (cell.width === 0 || x + cell.width > width) {
+          continue;
+        }
+
+        destination[x] = cell;
+        painted[y]![x] = this.#painted[y]![x]!;
+        for (let column = x + 1; column < x + cell.width; column++) {
+          destination[column] = source[column]!;
+          painted[y]![column] = this.#painted[y]![column]!;
+        }
+      }
+    }
+
+    this.#width = width;
+    this.#height = height;
+    this.#rows = rows;
+    this.#painted = painted;
+    this.#dirty = Array.from({ length: height }, () =>
+      width > 0 ? { start: 0, end: width } : undefined,
+    );
+  }
+
+  clear(): void {
+    for (const [y, row] of this.#rows.entries()) {
+      row.fill(emptyCell);
+      this.#painted[y]!.fill(true);
+      this.#markDirty(y, 0, this.rowLength(y));
+    }
+  }
+
+  toRows(): readonly Line[] {
+    return this.#rows;
+  }
+
+  dirtySpans(): readonly DirtySpan[] {
+    return this.#dirty.flatMap((span, y) => (span ? [{ y, ...span }] : []));
+  }
+
+  takeDirtySpans(): readonly DirtySpan[] {
+    const spans = this.dirtySpans();
+    this.#dirty.fill(undefined);
+    return spans;
+  }
+
+  /** Extends a row (and its paint mask) so overflow writes land past `width`. */
+  #growRow(row: Cell[], y: number, length: number): void {
+    const painted = this.#painted[y]!;
+    while (row.length < length) {
+      row.push(emptyCell);
+      painted.push(false);
+    }
+  }
+
+  #clearGraphemeAt(row: Cell[], y: number, x: number): void {
+    const existing = row[x];
+    if (!existing || existing === emptyCell) {
+      return;
+    }
+
+    let leadingColumn = x;
+    while (leadingColumn > 0 && row[leadingColumn]?.width === 0) {
+      leadingColumn--;
+    }
+
+    const leadingCell = row[leadingColumn];
+    const width = Math.max(1, leadingCell?.width ?? 1);
+    for (
+      let column = leadingColumn;
+      column < Math.min(leadingColumn + width, row.length);
+      column++
+    ) {
+      row[column] = emptyCell;
+      this.#painted[y]![column] = true;
+    }
+    this.#markDirty(y, leadingColumn, leadingColumn + width);
+  }
+
+  #composeColor(
+    destination: CellStyle,
+    patch: CellPatch,
+    channel: "foreground" | "background" | "underlineColor",
+  ): Partial<CellStyle> {
+    const value = patch[channel];
+    if (value === undefined) {
+      return destination[channel] ? { [channel]: destination[channel] } : {};
+    }
+
+    if (value === null) return {};
+    const destinationColor = destination[channel];
+    if (value.model === "rgb" && value.alpha < 255 && destinationColor) {
+      return { [channel]: blend(value, destinationColor) };
+    }
+    return { [channel]: value };
+  }
+
+  #markDirty(y: number, start: number, end: number): void {
+    if (y < 0 || y >= this.height || start >= end) {
+      return;
+    }
+
+    const clippedStart = Math.max(0, start);
+    const clippedEnd = Math.min(this.rowLength(y), end);
+    const current = this.#dirty[y];
+    this.#dirty[y] = current
+      ? { start: Math.min(current.start, clippedStart), end: Math.max(current.end, clippedEnd) }
+      : { start: clippedStart, end: clippedEnd };
+  }
+}
+
+function validateDimensions(width: number, height: number): void {
+  if (!Number.isInteger(width) || width < 0 || !Number.isInteger(height) || height < 0) {
+    throw new Error("Screen dimensions must be non-negative integers");
+  }
+}

package/src/screen/serialize.ts

@@ -0,0 +1,129 @@
+import {
+  getEndCode,
+  styledCharsToString,
+  type AnsiCode,
+  type StyledChar,
+} from "#/ansi/tokenize.ts";
+import { cellAttributes, type Cell, type Color, type Hyperlink } from "#/screen/cell.ts";
+import { quantizeColor, type ColorProfile } from "#/screen/color-profile.ts";
+import type { Line, Screen } from "#/screen/screen.ts";
+
+const ESC = "\u001B";
+const BEL = "\u0007";
+
+export type SerializeOptions = {
+  readonly colorProfile: ColorProfile;
+  readonly trimEnd?: boolean;
+  readonly styles?: boolean;
+};
+
+/** Serializes one structured cell run with minimal style transitions. */
+export function serializeLine(line: Line, options: SerializeOptions): string {
+  const characters = line.map((cell) =>
+    styledCharFromCell(cell, options.colorProfile, options.styles ?? true),
+  );
+  const output = styledCharsToString(characters);
+  return options.trimEnd === false ? output : output.trimEnd();
+}
+
+export function serializeScreen(screen: Screen, options: SerializeOptions): string {
+  return screen
+    .toRows()
+    .map((line) => serializeLine(line, options))
+    .join("\n");
+}
+
+/** Converts a semantic cell to the canonical ANSI compatibility style state. */
+export function styledCharFromCell(cell: Cell, profile: ColorProfile, styles = true): StyledChar {
+  return {
+    type: "char",
+    value: cell.grapheme,
+    fullWidth: cell.width > 1,
+    styles: styles ? ansiCodesFromCell(cell, profile) : [],
+  };
+}
+
+function ansiCodesFromCell(cell: Cell, profile: ColorProfile): AnsiCode[] {
+  const result: AnsiCode[] = [];
+  const { style } = cell;
+
+  if (cell.hyperlink) {
+    result.push(codePair(hyperlinkStart(cell.hyperlink)));
+  }
+
+  // This order mirrors the nesting produced by the Ink-compatible Text API,
+  // while remaining deterministic for cells produced by custom drawables.
+  addAttribute(result, style.attributes, cellAttributes.inverse, 7);
+  addAttribute(result, style.attributes, cellAttributes.hidden, 8);
+  addAttribute(result, style.attributes, cellAttributes.strikethrough, 9);
+
+  if (style.underline !== "none") {
+    const variant = {
+      single: "4",
+      double: "4:2",
+      curly: "4:3",
+      dotted: "4:4",
+      dashed: "4:5",
+    }[style.underline];
+    result.push(codePair(`${ESC}[${variant}m`));
+  }
+
+  addAttribute(result, style.attributes, cellAttributes.italic, 3);
+  addAttribute(result, style.attributes, cellAttributes.bold, 1);
+  addAttribute(result, style.attributes, cellAttributes.rapidBlink, 6);
+  addAttribute(result, style.attributes, cellAttributes.blink, 5);
+
+  const background = quantizeColor(style.background, profile);
+  if (background) {
+    result.push(codePair(colorCode(background, "background")));
+  }
+
+  const foreground = quantizeColor(style.foreground, profile);
+  if (foreground) {
+    result.push(codePair(colorCode(foreground, "foreground")));
+  }
+
+  addAttribute(result, style.attributes, cellAttributes.faint, 2);
+
+  const underlineColor = quantizeColor(style.underlineColor, profile);
+  if (underlineColor) {
+    result.push(codePair(colorCode(underlineColor, "underline")));
+  }
+
+  return result;
+}
+
+function addAttribute(
+  result: AnsiCode[],
+  attributes: number,
+  attribute: number,
+  sgr: number,
+): void {
+  if (Math.floor(attributes / attribute) % 2 === 1) {
+    result.push(codePair(`${ESC}[${sgr}m`));
+  }
+}
+
+function colorCode(color: Color, channel: "foreground" | "background" | "underline"): string {
+  const prefix = { foreground: 38, background: 48, underline: 58 }[channel];
+
+  if (color.model === "rgb") {
+    return `${ESC}[${prefix};2;${color.red};${color.green};${color.blue}m`;
+  }
+
+  if (channel === "underline" || color.index >= 16 || color.encoding === "ansi256") {
+    return `${ESC}[${prefix};5;${color.index}m`;
+  }
+
+  const basic = color.index < 8 ? color.index : color.index - 8 + 60;
+  const channelOffset = channel === "background" ? 40 : 30;
+  return `${ESC}[${channelOffset + basic}m`;
+}
+
+function hyperlinkStart(hyperlink: Hyperlink): string {
+  return `${ESC}]8;${hyperlink.parameters ?? ""};${hyperlink.url}${BEL}`;
+}
+
+function codePair(code: string): AnsiCode {
+  return { code, endCode: getEndCode(code) };
+}

package/src/screen.ts

@@ -0,0 +1 @@
+export * from "#/screen/index.ts";

package/src/semantic-text-style.ts

@@ -0,0 +1,118 @@
+import { hexToRgb } from "#/ansi/sgr.ts";
+import type { Paint } from "#/color/paint.ts";
+import { cellAttributes, type CellStyle, type Color } from "#/screen/cell.ts";
+
+export type SemanticTextStyle = {
+  readonly foreground?: Paint;
+  readonly background?: Paint;
+  readonly resetForeground?: boolean;
+  readonly resetBackground?: boolean;
+  readonly underline?: CellStyle["underline"];
+  readonly attributes: number;
+};
+
+export const emptySemanticTextStyle: SemanticTextStyle = {
+  attributes: cellAttributes.none,
+};
+
+const namedColors: Record<string, number> = {
+  black: 0,
+  red: 1,
+  green: 2,
+  yellow: 3,
+  blue: 4,
+  magenta: 5,
+  cyan: 6,
+  white: 7,
+  blackBright: 8,
+  gray: 8,
+  grey: 8,
+  redBright: 9,
+  greenBright: 10,
+  yellowBright: 11,
+  blueBright: 12,
+  magentaBright: 13,
+  cyanBright: 14,
+  whiteBright: 15,
+};
+
+const rgbPattern = /^rgb\(\s?(\d+),\s?(\d+),\s?(\d+)\s?\)$/;
+const ansi256Pattern = /^ansi256\(\s?(\d+)\s?\)$/;
+
+export function parseSemanticColor(value: string | Color | undefined): Color | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (typeof value !== "string") return value;
+
+  const named = namedColors[value];
+  if (named !== undefined) {
+    return { model: "indexed", index: named, encoding: "ansi16" };
+  }
+
+  if (value.startsWith("#")) {
+    const [red, green, blue] = hexToRgb(value);
+    return { model: "rgb", red, green, blue, alpha: 255 };
+  }
+
+  const rgb = rgbPattern.exec(value);
+  if (rgb) {
+    return {
+      model: "rgb",
+      red: Number(rgb[1]),
+      green: Number(rgb[2]),
+      blue: Number(rgb[3]),
+      alpha: 255,
+    };
+  }
+
+  const ansi256 = ansi256Pattern.exec(value);
+  if (ansi256) {
+    return { model: "indexed", index: Number(ansi256[1]), encoding: "ansi256" };
+  }
+
+  return undefined;
+}
+
+export function mergeSemanticTextStyles(
+  parent: SemanticTextStyle,
+  child: SemanticTextStyle | undefined,
+): SemanticTextStyle {
+  if (!child) {
+    return parent;
+  }
+
+  // Attribute flags are intentionally additive across nested Text nodes.
+  // eslint-disable-next-line no-bitwise
+  const attributes = parent.attributes | child.attributes;
+  const foreground = child.resetForeground ? undefined : (child.foreground ?? parent.foreground);
+  const background = child.resetBackground ? undefined : (child.background ?? parent.background);
+  return {
+    ...(foreground ? { foreground } : {}),
+    ...(background ? { background } : {}),
+    ...(child.resetForeground ? { resetForeground: true } : {}),
+    ...(child.resetBackground ? { resetBackground: true } : {}),
+    ...((child.underline ?? parent.underline)
+      ? { underline: child.underline ?? parent.underline }
+      : {}),
+    attributes,
+  };
+}
+
+export function semanticTextStyleToCellStyle(style: SemanticTextStyle): CellStyle {
+  const foreground = solidColor(style.foreground);
+  const background = solidColor(style.background);
+  return {
+    ...(foreground ? { foreground } : {}),
+    ...(background ? { background } : {}),
+    underline: style.underline ?? "none",
+    attributes: style.attributes,
+  };
+}
+
+function solidColor(paint: Paint | undefined): Color | undefined {
+  if (!paint) return undefined;
+  if (typeof paint === "string") return parseSemanticColor(paint);
+  return "model" in paint ? paint : undefined;
+}

package/src/squash-text-nodes.ts

@@ -1,9 +1,7 @@
 import { type DOMElement } from "#/dom.ts";
 import { sanitizeAnsi } from "#/sanitize-ansi.ts";
 
-// Squashing text nodes allows to combine multiple text nodes into one and write
-// to `Output` instance only once. For example, <Text>hello{' '}world</Text>
-// is actually 3 text nodes, which would result 3 writes to `Output`.
+// Squashing text nodes combines the host text nodes into one compatibility run.
 //
 // Also, this is necessary for libraries like ink-link (https://github.com/sindresorhus/ink-link),
 // which need to wrap all children at once, instead of wrapping 3 text nodes separately.
@@ -26,8 +24,7 @@ export const squashTextNodes = (node: DOMElement): string => {
         nodeText = squashTextNodes(childNode);
       }
 
-      // Since these text nodes are being concatenated, `Output` instance won't be able to
-      // apply children transform, so we have to do it manually here for each text node
+      // Nested compatibility transforms must run before the enclosing transform.
       if (nodeText.length > 0 && typeof childNode.internal_transform === "function") {
         nodeText = childNode.internal_transform(nodeText, index);
       }