@alchemy.run/sigil 0.0.0-alpha.3 → 0.0.0-alpha.5

package/src/screen/ansi.ts

@@ -0,0 +1,184 @@
+import { stringWidth } from "#/ansi/string-width.ts";
+import {
+  type AnsiCode,
+  type StyledChar,
+  styledCharsFromTokens,
+  tokenize,
+} from "#/ansi/tokenize.ts";
+import {
+  cellAttributes,
+  createCell,
+  type Cell,
+  type CellStyle,
+  type Color,
+  type Hyperlink,
+  type UnderlineStyle,
+} from "#/screen/cell.ts";
+
+const ESC = "\u001B";
+const BEL = "\u0007";
+const C1_ST = "\u009C";
+const LINK_PREFIX = `${ESC}]8;`;
+
+type ParsedStyle = {
+  foreground?: Color;
+  background?: Color;
+  underlineColor?: Color;
+  underline: UnderlineStyle;
+  attributes: number;
+  hyperlink?: Hyperlink;
+};
+
+/** Converts the renderer's canonical ANSI state into backend-neutral cells. */
+export function cellsFromAnsi(text: string): Cell[] {
+  return styledCharsFromTokens(tokenize(text)).map((character) => cellFromStyledChar(character));
+}
+
+export function cellFromStyledChar(
+  character: StyledChar,
+  width = stringWidth(character.value),
+): Cell {
+  const parsed = parseStyles(character.styles);
+  const style: CellStyle = {
+    ...(parsed.foreground ? { foreground: parsed.foreground } : {}),
+    ...(parsed.background ? { background: parsed.background } : {}),
+    ...(parsed.underlineColor ? { underlineColor: parsed.underlineColor } : {}),
+    underline: parsed.underline,
+    attributes: parsed.attributes,
+  };
+
+  return createCell(character.value, Math.max(1, width), style, parsed.hyperlink);
+}
+
+function parseStyles(codes: readonly AnsiCode[]): ParsedStyle {
+  let foreground: Color | undefined;
+  let background: Color | undefined;
+  let underlineColor: Color | undefined;
+  let underline: UnderlineStyle = "none";
+  let attributes = cellAttributes.none;
+  let hyperlink: Hyperlink | undefined;
+
+  for (const { code } of codes) {
+    if (code.startsWith(LINK_PREFIX)) {
+      hyperlink = parseHyperlink(code);
+      continue;
+    }
+
+    if (!code.startsWith(`${ESC}[`) || !code.endsWith("m")) {
+      continue;
+    }
+
+    const parameters = code.slice(2, -1);
+    const primary = Number.parseInt(parameters, 10);
+
+    if (primary >= 30 && primary <= 37) {
+      foreground = { model: "indexed", index: primary - 30, encoding: "ansi16" };
+    } else if (primary >= 90 && primary <= 97) {
+      foreground = { model: "indexed", index: primary - 90 + 8, encoding: "ansi16" };
+    } else if (primary >= 40 && primary <= 47) {
+      background = { model: "indexed", index: primary - 40, encoding: "ansi16" };
+    } else if (primary >= 100 && primary <= 107) {
+      background = { model: "indexed", index: primary - 100 + 8, encoding: "ansi16" };
+    } else if (primary === 38) {
+      foreground = parseExtendedColor(parameters);
+    } else if (primary === 48) {
+      background = parseExtendedColor(parameters);
+    } else if (primary === 58) {
+      underlineColor = parseExtendedColor(parameters);
+    } else if (primary === 1) {
+      attributes += cellAttributes.bold;
+    } else if (primary === 2) {
+      attributes += cellAttributes.faint;
+    } else if (primary === 3) {
+      attributes += cellAttributes.italic;
+    } else if (primary === 5) {
+      attributes += cellAttributes.blink;
+    } else if (primary === 6) {
+      attributes += cellAttributes.rapidBlink;
+    } else if (primary === 7) {
+      attributes += cellAttributes.inverse;
+    } else if (primary === 8) {
+      attributes += cellAttributes.hidden;
+    } else if (primary === 9) {
+      attributes += cellAttributes.strikethrough;
+    } else if (primary === 4) {
+      underline = parseUnderline(parameters);
+    }
+  }
+
+  return {
+    ...(foreground ? { foreground } : {}),
+    ...(background ? { background } : {}),
+    ...(underlineColor ? { underlineColor } : {}),
+    underline,
+    attributes,
+    ...(hyperlink ? { hyperlink } : {}),
+  };
+}
+
+function parseExtendedColor(parameters: string): Color | undefined {
+  const parts = parameters.split(parameters.includes(":") ? ":" : ";");
+  const model = parts[1];
+
+  if (model === "5") {
+    const index = Number(parts[2]);
+    return Number.isInteger(index) && index >= 0 && index <= 255
+      ? { model: "indexed", index, encoding: "ansi256" }
+      : undefined;
+  }
+
+  if (model !== "2") {
+    return undefined;
+  }
+
+  const channels = parts.slice(-3).map(Number);
+  if (channels.length !== 3 || channels.some((channel) => !isByte(channel))) {
+    return undefined;
+  }
+
+  return {
+    model: "rgb",
+    red: channels[0]!,
+    green: channels[1]!,
+    blue: channels[2]!,
+    alpha: 255,
+  };
+}
+
+function parseUnderline(parameters: string): UnderlineStyle {
+  const variant = parameters.includes(":") ? Number(parameters.split(":").at(-1)) : 1;
+  return (
+    (
+      {
+        0: "none",
+        1: "single",
+        2: "double",
+        3: "curly",
+        4: "dotted",
+        5: "dashed",
+      } as const
+    )[variant] ?? "single"
+  );
+}
+
+function parseHyperlink(code: string): Hyperlink | undefined {
+  let body = code.slice(LINK_PREFIX.length);
+  if (body.endsWith(`${ESC}\\`)) {
+    body = body.slice(0, -2);
+  } else if (body.endsWith(BEL) || body.endsWith(C1_ST)) {
+    body = body.slice(0, -1);
+  }
+
+  const separator = body.indexOf(";");
+  if (separator < 0) {
+    return undefined;
+  }
+
+  const parameters = body.slice(0, separator);
+  const url = body.slice(separator + 1);
+  return parameters ? { url, parameters } : { url };
+}
+
+function isByte(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value <= 255;
+}

package/src/screen/canvas.ts

@@ -0,0 +1,137 @@
+import { sliceAnsi } from "#/ansi/slice.ts";
+import { stringWidth } from "#/ansi/string-width.ts";
+import type { StyledChar } from "#/ansi/tokenize.ts";
+import type { PaintContext } from "#/color/paint.ts";
+import { cellFromStyledChar, Screen, type Cell, type ColorProfile } from "#/screen/index.ts";
+import type { AnsiTransformer } from "#/transform-adapter.ts";
+import { transformAnsiLine } from "#/transform-adapter.ts";
+
+type Options = {
+  width: number;
+  height: number;
+  colorProfile?: ColorProfile;
+  paintContext?: PaintContext;
+};
+type Clip = {
+  x1: number | undefined;
+  x2: number | undefined;
+  y1: number | undefined;
+  y2: number | undefined;
+};
+
+/** Immediate structured drawing canvas with one explicit ANSI compatibility adapter. */
+export class Canvas {
+  width: number;
+  height: number;
+  readonly paintContext: PaintContext;
+  readonly #screen: Screen;
+  readonly #clips: Clip[] = [];
+
+  constructor(options: Options) {
+    this.width = options.width;
+    this.height = options.height;
+    this.paintContext = { profile: options.colorProfile ?? "truecolor", ...options.paintContext };
+    this.#screen = new Screen(this.width, this.height);
+  }
+
+  writeCells(x: number, y: number, lines: readonly (readonly Cell[])[]): void {
+    const clip = this.#clips.at(-1);
+    for (const [rowOffset, line] of lines.entries()) {
+      const currentY = y + rowOffset;
+      if (!this.#insideY(currentY, clip)) continue;
+      let currentX = x;
+      for (const cell of line) {
+        const endX = currentX + cell.width;
+        const clipped =
+          (clip?.x1 !== undefined && currentX < clip.x1) ||
+          (clip?.x2 !== undefined && endX > clip.x2);
+        if (!clipped) this.#composeNativeCell(currentX, currentY, cell);
+        currentX = endX;
+      }
+    }
+  }
+
+  writeAnsi(
+    x: number,
+    y: number,
+    text: string,
+    options: { transformers: AnsiTransformer[] },
+  ): void {
+    if (!text) return;
+    let lines = text.split("\n");
+    const clip = this.#clips.at(-1);
+    if (clip?.y1 !== undefined && y < clip.y1) {
+      lines = lines.slice(clip.y1 - y);
+      y = clip.y1;
+    }
+    if (clip?.y2 !== undefined) lines = lines.slice(0, Math.max(0, clip.y2 - y));
+    for (const [lineIndex, original] of lines.entries()) {
+      const currentY = y + lineIndex;
+      if (!this.#insideY(currentY, clip)) continue;
+      let line = original;
+      let currentX = x;
+      if (clip?.x1 !== undefined && currentX < clip.x1) {
+        line = sliceAnsi(line, clip.x1 - currentX);
+        currentX = clip.x1;
+      }
+      if (clip?.x2 !== undefined) line = sliceAnsi(line, 0, Math.max(0, clip.x2 - currentX));
+      for (const character of transformAnsiLine(line, lineIndex, options.transformers)) {
+        const width = Math.max(1, stringWidth(character.value));
+        if (clip?.x2 !== undefined && currentX + width > clip.x2) break;
+        this.#writeCompatibilityCell(currentX, currentY, character, width);
+        currentX += width;
+      }
+    }
+  }
+
+  clip(clip: Clip): void {
+    this.#clips.push(clip);
+  }
+  unclip(): void {
+    this.#clips.pop();
+  }
+
+  finish(): Screen {
+    return this.#screen;
+  }
+
+  #insideY(y: number, clip: Clip | undefined): boolean {
+    return (
+      y >= 0 &&
+      y < this.#screen.height &&
+      (clip?.y1 === undefined || y >= clip.y1) &&
+      (clip?.y2 === undefined || y < clip.y2)
+    );
+  }
+
+  #composeNativeCell(x: number, y: number, cell: Cell): void {
+    if (x >= this.#screen.width) {
+      return;
+    }
+    this.#screen.composeCell(x, y, {
+      content: { grapheme: cell.grapheme, width: cell.width },
+      foreground: cell.reset?.foreground ? null : (cell.style.foreground ?? null),
+      background: cell.reset?.background ? null : cell.style.background,
+      underlineColor: cell.style.underlineColor ?? null,
+      underline: cell.style.underline,
+      attributes: cell.style.attributes,
+      hyperlink: cell.hyperlink ?? null,
+    });
+  }
+
+  #writeCompatibilityCell(x: number, y: number, character: StyledChar, width: number): void {
+    if (x >= this.#screen.width) {
+      return;
+    }
+    const cell = cellFromStyledChar(character, width);
+    this.#screen.composeCell(x, y, {
+      content: { grapheme: cell.grapheme, width: cell.width },
+      foreground: cell.style.foreground ?? null,
+      background: cell.style.background,
+      underlineColor: cell.style.underlineColor ?? null,
+      underline: cell.style.underline,
+      attributes: cell.style.attributes,
+      hyperlink: cell.hyperlink ?? null,
+    });
+  }
+}

package/src/screen/cell.ts

@@ -0,0 +1,138 @@
+/**
+A terminal color before it is converted to an output profile.
+*/
+export type Color = RgbColor | IndexedColor;
+
+export type RgbColor = {
+  readonly model: "rgb";
+  readonly red: number;
+  readonly green: number;
+  readonly blue: number;
+  readonly alpha: number;
+};
+
+export type IndexedColor = {
+  readonly model: "indexed";
+  readonly index: number;
+  /** Preserve an explicit palette encoding when compatibility requires it. */
+  readonly encoding?: "ansi16" | "ansi256";
+};
+
+/**
+Bit flags for terminal text attributes. Multiple attributes may be combined.
+*/
+export const cellAttributes = {
+  none: 0,
+  bold: 1 << 0,
+  faint: 1 << 1,
+  italic: 1 << 2,
+  blink: 1 << 3,
+  rapidBlink: 1 << 4,
+  inverse: 1 << 5,
+  hidden: 1 << 6,
+  strikethrough: 1 << 7,
+} as const;
+
+export type UnderlineStyle = "none" | "single" | "double" | "curly" | "dotted" | "dashed";
+
+export type CellStyle = {
+  readonly foreground?: Color;
+  readonly background?: Color;
+  readonly underlineColor?: Color;
+  readonly underline: UnderlineStyle;
+  readonly attributes: number;
+};
+
+export type Hyperlink = {
+  readonly url: string;
+  readonly parameters?: string;
+};
+
+export type CellContent = {
+  readonly grapheme: string;
+  readonly width: number;
+};
+
+/**
+A compositing operation for one screen position.
+
+An absent field is transparent and preserves the destination channel. `null`
+explicitly resets a color or hyperlink to the terminal default. Supplying
+`content` paints a grapheme; `{grapheme: " ", width: 1}` is therefore an
+explicit blank, while an absent patch paints nothing at all.
+*/
+export type CellPatch = {
+  readonly content?: CellContent;
+  readonly foreground?: Color | null;
+  readonly background?: Color | null;
+  readonly underlineColor?: Color | null;
+  readonly underline?: UnderlineStyle;
+  readonly attributes?: number;
+  readonly hyperlink?: Hyperlink | null;
+};
+
+/**
+One grapheme cluster in a terminal screen. A width of zero is reserved for the
+continuation columns of a wide grapheme and is created only by `Screen`.
+*/
+export type Cell = {
+  readonly grapheme: string;
+  readonly width: number;
+  readonly style: CellStyle;
+  readonly hyperlink?: Hyperlink;
+  /** Composition intent consumed when this cell is drawn over another surface. */
+  readonly reset?: { readonly foreground?: boolean; readonly background?: boolean };
+};
+
+export const emptyCellStyle: CellStyle = {
+  underline: "none",
+  attributes: cellAttributes.none,
+};
+
+export const emptyCell: Cell = {
+  grapheme: " ",
+  width: 1,
+  style: emptyCellStyle,
+};
+
+export const createCell = (
+  grapheme: string,
+  width: number,
+  style: CellStyle = emptyCellStyle,
+  hyperlink?: Hyperlink,
+  reset?: Cell["reset"],
+): Cell => {
+  if (grapheme.length === 0) {
+    throw new Error("A cell must contain one grapheme cluster");
+  }
+
+  if (!Number.isInteger(width) || width < 1) {
+    throw new Error("A cell width must be a positive integer");
+  }
+
+  return {
+    grapheme,
+    width,
+    style,
+    ...(hyperlink ? { hyperlink } : {}),
+    ...(reset ? { reset } : {}),
+  };
+};
+
+export const cellsEqual = (left: Cell | undefined, right: Cell | undefined): boolean => {
+  if (left === right) return true;
+  if (!left || !right || left.grapheme !== right.grapheme || left.width !== right.width) {
+    return false;
+  }
+
+  const leftStyle = left.style;
+  const rightStyle = right.style;
+  return (
+    leftStyle.attributes === rightStyle.attributes &&
+    leftStyle.underline === rightStyle.underline &&
+    JSON.stringify(leftStyle.foreground) === JSON.stringify(rightStyle.foreground) &&
+    JSON.stringify(leftStyle.background) === JSON.stringify(rightStyle.background) &&
+    JSON.stringify(leftStyle.underlineColor) === JSON.stringify(rightStyle.underlineColor) &&
+    JSON.stringify(left.hyperlink) === JSON.stringify(right.hyperlink)
+  );
+};

package/src/screen/color-profile.ts

@@ -0,0 +1,47 @@
+import { ansi256ToAnsi, rgbToAnsi, rgbToAnsi256 } from "#/ansi/sgr.ts";
+import type { ColorSupportLevel } from "#/capabilities/detect.ts";
+import type { Color } from "#/screen/cell.ts";
+
+/** The color model emitted by a terminal serializer. */
+export type ColorProfile = "none" | "ansi16" | "ansi256" | "truecolor";
+
+export function colorProfileFromLevel(level: ColorSupportLevel): ColorProfile {
+  return (["none", "ansi16", "ansi256", "truecolor"] as const)[level];
+}
+
+/**
+Quantizes a semantic color for an output profile. `undefined` means the
+terminal default and is also the result for the no-color profile.
+*/
+export function quantizeColor(color: Color | undefined, profile: ColorProfile): Color | undefined {
+  if (!color || profile === "none") {
+    return undefined;
+  }
+
+  if (profile === "truecolor") {
+    return color;
+  }
+
+  if (profile === "ansi256") {
+    if (color.model === "indexed") {
+      return color;
+    }
+
+    return {
+      model: "indexed",
+      index: rgbToAnsi256(color.red, color.green, color.blue),
+      encoding: "ansi256",
+    };
+  }
+
+  const ansiCode =
+    color.model === "indexed"
+      ? ansi256ToAnsi(color.index)
+      : rgbToAnsi(color.red, color.green, color.blue);
+
+  return { model: "indexed", index: ansiCodeToPaletteIndex(ansiCode), encoding: "ansi16" };
+}
+
+function ansiCodeToPaletteIndex(code: number): number {
+  return code >= 90 ? code - 90 + 8 : code - 30;
+}

package/src/screen/geometry.ts

@@ -0,0 +1,9 @@
+export type Point = {
+  readonly x: number;
+  readonly y: number;
+};
+
+export type Rect = Point & {
+  readonly width: number;
+  readonly height: number;
+};

package/src/screen/index.ts

@@ -0,0 +1,6 @@
+export * from "#/screen/ansi.ts";
+export * from "#/screen/cell.ts";
+export * from "#/screen/color-profile.ts";
+export * from "#/screen/geometry.ts";
+export * from "#/screen/serialize.ts";
+export { Screen, type Line } from "#/screen/screen.ts";