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

package/src/structured-text.ts

@@ -0,0 +1,325 @@
+import { tokenizeAnsi } from "#/ansi-tokenizer.ts";
+import { graphemes } from "#/ansi/graphemes.ts";
+import { stringWidth } from "#/ansi/string-width.ts";
+import { stripAnsi } from "#/ansi/strip.ts";
+import { samplePaint, type PaintContext } from "#/color/index.ts";
+import type { Paint } from "#/color/paint.ts";
+import type { DOMElement, DOMNode } from "#/dom.ts";
+import { cellsFromAnsi } from "#/screen/ansi.ts";
+import { createCell, type Cell, type CellStyle } from "#/screen/cell.ts";
+import type { Rect } from "#/screen/geometry.ts";
+import {
+  emptySemanticTextStyle,
+  mergeSemanticTextStyles,
+  semanticTextStyleToCellStyle,
+  type SemanticTextStyle,
+} from "#/semantic-text-style.ts";
+import type { Styles } from "#/styles.ts";
+
+type SemanticCell = Cell & {
+  readonly foregroundPaint?: Paint;
+  readonly backgroundPaint?: Paint;
+};
+
+/** Whether a text subtree must retain the ANSI compatibility pipeline. */
+export function hasCompatibilityText(node: DOMElement): boolean {
+  if (node.internal_transform && !node.internal_textStyle) {
+    return true;
+  }
+
+  return node.childNodes.some((child) => child.nodeName !== "#text" && hasCompatibilityText(child));
+}
+
+/** Rasterizes an unwrapped native Text subtree into semantic cell lines. */
+export function structuredTextLines(node: DOMElement): readonly (readonly SemanticCell[])[] {
+  const lines: SemanticCell[][] = [[]];
+  appendNode(node, emptySemanticTextStyle, lines, false);
+  return lines;
+}
+
+/** Samples semantic paints only after wrapping and final layout are known. */
+export function sampleStructuredText(
+  lines: readonly (readonly SemanticCell[])[],
+  bounds: Rect,
+  context: PaintContext,
+): readonly (readonly Cell[])[] {
+  return lines.map((line, row) => {
+    let column = 0;
+    return line.map((cell) => {
+      const foreground = cell.foregroundPaint
+        ? samplePaint(cell.foregroundPaint, bounds.x + column, bounds.y + row, bounds, context)
+        : cell.style.foreground;
+      const background = cell.backgroundPaint
+        ? samplePaint(cell.backgroundPaint, bounds.x + column, bounds.y + row, bounds, context)
+        : cell.style.background;
+      column += cell.width;
+      return createCell(
+        cell.grapheme,
+        cell.width,
+        {
+          ...cell.style,
+          ...(foreground ? { foreground } : {}),
+          ...(background ? { background } : {}),
+        },
+        cell.hyperlink,
+        cell.reset,
+      );
+    });
+  });
+}
+
+export function structuredTextBaseStyle(node: DOMElement): CellStyle {
+  return semanticTextStyleToCellStyle(
+    mergeSemanticTextStyles(emptySemanticTextStyle, node.internal_textStyle),
+  );
+}
+
+/** Wraps or truncates semantic cells without converting them through ANSI. */
+export function wrapStructuredText(
+  input: readonly (readonly Cell[])[],
+  maxWidth: number,
+  wrap: Styles["textWrap"],
+  baseStyle?: CellStyle,
+): readonly (readonly Cell[])[] {
+  if (wrap === "none") {
+    return input.map((line) => [...line]);
+  }
+
+  if (maxWidth < 1) {
+    return [[]];
+  }
+
+  return input.flatMap((line) => {
+    if (lineWidth(line) <= maxWidth) {
+      return [[...line]];
+    }
+
+    if (wrap === "hard") {
+      return hardWrap(line, maxWidth);
+    }
+
+    if (wrap === "wrap") {
+      return wordWrap(line, maxWidth);
+    }
+
+    return [truncate(line, maxWidth, wrap, baseStyle)];
+  });
+}
+
+function wordWrap(line: readonly Cell[], maxWidth: number): Cell[][] {
+  const words: Cell[][] = [[]];
+  const spaces: Cell[] = [];
+
+  for (const cell of line) {
+    if (cell.grapheme === " ") {
+      spaces.push(cell);
+      words.push([]);
+    } else {
+      words.at(-1)!.push(cell);
+    }
+  }
+
+  const output: Cell[][] = [[]];
+  appendHard(output, words[0]!, maxWidth);
+
+  for (let index = 1; index < words.length; index++) {
+    appendHard(output, [spaces[index - 1]!], maxWidth);
+    const word = words[index]!;
+    const current = output.at(-1)!;
+    const wordWidth = lineWidth(word);
+    const currentWidth = lineWidth(current);
+
+    if (wordWidth <= maxWidth && currentWidth + wordWidth > maxWidth) {
+      output.push([]);
+    } else if (wordWidth > maxWidth && currentWidth > 0) {
+      const remaining = maxWidth - currentWidth;
+      const breaksHere = 1 + Math.floor((wordWidth - remaining - 1) / maxWidth);
+      const breaksNext = Math.floor((wordWidth - 1) / maxWidth);
+      if (breaksNext < breaksHere) {
+        output.push([]);
+      }
+    }
+
+    appendHard(output, word, maxWidth);
+  }
+
+  return output;
+}
+
+function hardWrap(line: readonly Cell[], maxWidth: number): Cell[][] {
+  const output: Cell[][] = [[]];
+  appendHard(output, line, maxWidth);
+  return output;
+}
+
+function appendHard(output: Cell[][], cells: readonly Cell[], maxWidth: number): void {
+  for (const cell of cells) {
+    const current = output.at(-1)!;
+    if (current.length > 0 && lineWidth(current) + cell.width > maxWidth) {
+      output.push([]);
+    }
+
+    output.at(-1)!.push(cell);
+  }
+}
+
+function truncate(
+  line: readonly Cell[],
+  maxWidth: number,
+  wrap: Styles["textWrap"],
+  baseStyle: CellStyle | undefined,
+): Cell[] {
+  if (maxWidth === 1) {
+    return [ellipsis(baseStyle ?? cellStyleIntersection(line.at(0), line.at(-1)))];
+  }
+
+  if (wrap === "truncate-start") {
+    const right = sliceCells(line, lineWidth(line) - maxWidth + 1, lineWidth(line));
+    return [ellipsis(right[0]?.style), ...right];
+  }
+
+  if (wrap === "truncate-middle") {
+    const half = Math.min(Math.floor(maxWidth / 2), maxWidth - 1);
+    const left = sliceCells(line, 0, half);
+    const rightWidth = maxWidth - half - 1;
+    const right = sliceCells(line, lineWidth(line) - rightWidth, lineWidth(line));
+    return [
+      ...left,
+      ellipsis(baseStyle ?? cellStyleIntersection(left.at(-1), right.at(0))),
+      ...right,
+    ];
+  }
+
+  const left = sliceCells(line, 0, maxWidth - 1);
+  return [...left, ellipsis(left.at(-1)?.style)];
+}
+
+function sliceCells(line: readonly Cell[], start: number, end: number): Cell[] {
+  const output: Cell[] = [];
+  let column = 0;
+
+  for (const cell of line) {
+    const nextColumn = column + cell.width;
+    if (column >= start && nextColumn <= end) {
+      output.push(cell);
+    }
+
+    column = nextColumn;
+  }
+
+  return output;
+}
+
+function ellipsis(style = semanticTextStyleToCellStyle(emptySemanticTextStyle)): Cell {
+  return createCell("…", 1, style);
+}
+
+function cellStyleIntersection(left: Cell | undefined, right: Cell | undefined): Cell["style"] {
+  if (!left) {
+    return right?.style ?? semanticTextStyleToCellStyle(emptySemanticTextStyle);
+  }
+
+  if (!right) {
+    return left.style;
+  }
+
+  return {
+    ...(sameColor(left.style.foreground, right.style.foreground)
+      ? { foreground: left.style.foreground }
+      : {}),
+    ...(sameColor(left.style.background, right.style.background)
+      ? { background: left.style.background }
+      : {}),
+    ...(sameColor(left.style.underlineColor, right.style.underlineColor)
+      ? { underlineColor: left.style.underlineColor }
+      : {}),
+    underline: left.style.underline === right.style.underline ? left.style.underline : "none",
+    // eslint-disable-next-line no-bitwise
+    attributes: left.style.attributes & right.style.attributes,
+  };
+}
+
+function sameColor(left: Cell["style"]["foreground"], right: Cell["style"]["foreground"]): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function lineWidth(line: readonly Cell[]): number {
+  return line.reduce((width, cell) => width + cell.width, 0);
+}
+
+function appendNode(
+  node: DOMNode,
+  inherited: SemanticTextStyle,
+  lines: SemanticCell[][],
+  ansi: boolean,
+): void {
+  if (node.nodeName === "#text") {
+    if (ansi) appendAnsiText(node.nodeValue, inherited, lines);
+    else appendText(node.nodeValue, inherited, lines);
+    return;
+  }
+
+  const style = mergeSemanticTextStyles(inherited, node.internal_textStyle);
+  for (const child of node.childNodes) {
+    appendNode(child, style, lines, ansi || node.internal_ansi === true);
+  }
+}
+
+function appendAnsiText(text: string, semantic: SemanticTextStyle, lines: SemanticCell[][]): void {
+  const base = semanticTextStyleToCellStyle(semantic);
+  for (const cell of cellsFromAnsi(text)) {
+    if (cell.grapheme === "\n" || cell.grapheme === "\r\n") {
+      lines.push([]);
+      continue;
+    }
+
+    const hasForeground = cell.style.foreground !== undefined;
+    const hasBackground = cell.style.background !== undefined;
+    lines.at(-1)!.push({
+      ...cell,
+      style: {
+        ...((cell.style.foreground ?? base.foreground)
+          ? { foreground: cell.style.foreground ?? base.foreground }
+          : {}),
+        ...((cell.style.background ?? base.background)
+          ? { background: cell.style.background ?? base.background }
+          : {}),
+        ...(cell.style.underlineColor ? { underlineColor: cell.style.underlineColor } : {}),
+        underline: cell.style.underline === "none" ? base.underline : cell.style.underline,
+        // eslint-disable-next-line no-bitwise
+        attributes: base.attributes | cell.style.attributes,
+      },
+      ...(!hasForeground && semantic.foreground ? { foregroundPaint: semantic.foreground } : {}),
+      ...(!hasBackground && semantic.background ? { backgroundPaint: semantic.background } : {}),
+    });
+  }
+}
+
+function appendText(text: string, style: SemanticTextStyle, lines: SemanticCell[][]): void {
+  const cellStyle = semanticTextStyleToCellStyle(style);
+
+  const plainText = tokenizeAnsi(text)
+    .filter((token) => token.type === "text")
+    .map((token) => token.value)
+    .join("");
+  for (const segment of graphemes(stripAnsi(plainText))) {
+    if (segment === "\n" || segment === "\r\n") {
+      lines.push([]);
+      continue;
+    }
+
+    lines.at(-1)!.push({
+      ...createCell(
+        segment,
+        Math.max(1, stringWidth(segment)),
+        cellStyle,
+        undefined,
+        style.resetForeground || style.resetBackground
+          ? { foreground: style.resetForeground, background: style.resetBackground }
+          : undefined,
+      ),
+      ...(style.foreground ? { foregroundPaint: style.foreground } : {}),
+      ...(style.background ? { backgroundPaint: style.background } : {}),
+    });
+  }
+}

package/src/styles.ts

@@ -1,11 +1,15 @@
-import { type ForegroundColorName } from "#/ansi/sgr.ts";
+import type { Paint } from "#/color/paint.ts";
 import { type BoxGlyphs, type BoxStyle } from "#/glyphs.ts";
-import { type LiteralUnion } from "#/types.ts";
 import { Yoga, type Node as YogaNode, type PositionType } from "#/yoga/index.ts";
 
 export type Styles = {
   /*
 	We keep this as a single enum so overflow is one complete choice and invalid combinations like wrap + truncate-middle are unrepresentable. In hindsight, `normal` would have been a clearer default value than `wrap`, since it describes the standard behavior instead of repeating the prop name.
+
+	`none` neither wraps nor truncates: the text overflows the container (and
+	the screen's nominal width). Meant for scrollback content (`<Static>`),
+	not live regions, where a physically soft-wrapped line breaks the
+	presenter's line accounting.
 	*/
   readonly textWrap?:
     | "wrap"
@@ -13,7 +17,8 @@ export type Styles = {
     | "truncate-end"
     | "truncate"
     | "truncate-middle"
-    | "truncate-start";
+    | "truncate-start"
+    | "none";
 
   /**
 	Controls how the element is positioned.
@@ -274,27 +279,27 @@ export type Styles = {
   /**
 	Change border color. A shorthand for setting `borderTopColor`, `borderRightColor`, `borderBottomColor`, and `borderLeftColor`.
 	*/
-  readonly borderColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderColor?: Paint;
 
   /**
 	Change the top border color. Accepts the same values as `color` in `Text` component.
 	*/
-  readonly borderTopColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderTopColor?: Paint;
 
   /**
 	Change the bottom border color. Accepts the same values as `color` in `Text` component.
 	*/
-  readonly borderBottomColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderBottomColor?: Paint;
 
   /**
 	Change the left border color. Accepts the same values as `color` in `Text` component.
 	*/
-  readonly borderLeftColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderLeftColor?: Paint;
 
   /**
 	Change the right border color. Accepts the same values as `color` in `Text` component.
 	*/
-  readonly borderRightColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderRightColor?: Paint;
 
   /**
 	Dim the border color. A shorthand for setting `borderTopDimColor`, `borderBottomDimColor`, `borderLeftDimColor`, and `borderRightDimColor`.
@@ -334,27 +339,27 @@ export type Styles = {
   /**
 	Change border background color. A shorthand for setting `borderTopBackgroundColor`, `borderRightBackgroundColor`, `borderBottomBackgroundColor`, and `borderLeftBackgroundColor`.
 	*/
-  readonly borderBackgroundColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderBackgroundColor?: Paint;
 
   /**
 	Change top border background color. Accepts the same values as `backgroundColor` in `Text` component.
 	*/
-  readonly borderTopBackgroundColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderTopBackgroundColor?: Paint;
 
   /**
 	Change bottom border background color. Accepts the same values as `backgroundColor` in `Text` component.
 	*/
-  readonly borderBottomBackgroundColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderBottomBackgroundColor?: Paint;
 
   /**
 	Change left border background color. Accepts the same values as `backgroundColor` in `Text` component.
 	*/
-  readonly borderLeftBackgroundColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderLeftBackgroundColor?: Paint;
 
   /**
 	Change right border background color. Accepts the same values as `backgroundColor` in `Text` component.
 	*/
-  readonly borderRightBackgroundColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly borderRightBackgroundColor?: Paint;
 
   /**
 	Behavior for an element's overflow in both directions.
@@ -382,7 +387,7 @@ export type Styles = {
 
 	Accepts the same values as `color` in the `<Text>` component.
 	*/
-  readonly backgroundColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly backgroundColor?: Paint;
 };
 
 const positionEdges = [

package/src/terminal/index.ts

@@ -0,0 +1,2 @@
+export * from "#/terminal/input.ts";
+export * from "#/terminal/session.ts";

package/src/terminal/inline-presenter.ts

@@ -0,0 +1,120 @@
+import { cliCursor } from "#/ansi/cursor.ts";
+import { ansiEscapes } from "#/ansi/escapes.ts";
+import {
+  buildCursorOnlySequence,
+  buildCursorSuffix,
+  buildReturnToBottomPrefix,
+  cursorPositionChanged,
+  hideCursorEscape,
+  type CursorPosition,
+} from "#/cursor-position.ts";
+
+export type InlinePresenter = {
+  clear: () => void;
+  done: () => void;
+  reset: () => void;
+  sync: (output: string) => void;
+  setCursorPosition: (position: CursorPosition | undefined) => void;
+  isCursorDirty: () => boolean;
+  willRender: (output: string) => boolean;
+  (output: string): boolean;
+};
+
+/** Full-rewrite fallback and cursor state for the structured inline renderer. */
+export function createInlinePresenter(
+  stream: NodeJS.WritableStream,
+  options: { readonly showCursor?: boolean } = {},
+): InlinePresenter {
+  let previousLineCount = 0;
+  let previousOutput = "";
+  let hasHiddenCursor = false;
+  let cursorPosition: CursorPosition | undefined;
+  let cursorDirty = false;
+  let previousCursorPosition: CursorPosition | undefined;
+  let cursorWasShown = false;
+  const showCursor = options.showCursor ?? false;
+
+  const activeCursor = () => (cursorDirty ? cursorPosition : undefined);
+  const hasChanges = (output: string, cursor: CursorPosition | undefined) =>
+    output !== previousOutput || cursorPositionChanged(cursor, previousCursorPosition);
+
+  const present = (output: string): boolean => {
+    if (!showCursor && !hasHiddenCursor) {
+      cliCursor.hide(stream);
+      hasHiddenCursor = true;
+    }
+    const cursor = activeCursor();
+    cursorDirty = false;
+    const cursorChanged = cursorPositionChanged(cursor, previousCursorPosition);
+    if (!hasChanges(output, cursor)) return false;
+    const lines = output.split("\n");
+    const suffix = buildCursorSuffix(lines.length - 1, cursor);
+    if (output === previousOutput && cursorChanged) {
+      stream.write(
+        buildCursorOnlySequence({
+          cursorWasShown,
+          previousLineCount,
+          previousCursorPosition,
+          cursorPosition: cursor,
+        }),
+      );
+    } else {
+      previousOutput = output;
+      stream.write(
+        buildReturnToBottomPrefix(cursorWasShown, previousLineCount, previousCursorPosition) +
+          ansiEscapes.eraseLines(previousLineCount) +
+          output +
+          suffix,
+      );
+      previousLineCount = lines.length;
+    }
+    previousCursorPosition = cursor ? { ...cursor } : undefined;
+    cursorWasShown = cursor !== undefined;
+    return true;
+  };
+
+  present.clear = () => {
+    stream.write(
+      buildReturnToBottomPrefix(cursorWasShown, previousLineCount, previousCursorPosition) +
+        ansiEscapes.eraseLines(previousLineCount),
+    );
+    previousOutput = "";
+    previousLineCount = 0;
+    previousCursorPosition = undefined;
+    cursorWasShown = false;
+  };
+  present.done = () => {
+    previousOutput = "";
+    previousLineCount = 0;
+    previousCursorPosition = undefined;
+    cursorWasShown = false;
+    if (!showCursor) {
+      cliCursor.show(stream);
+      hasHiddenCursor = false;
+    }
+  };
+  present.reset = () => {
+    previousOutput = "";
+    previousLineCount = 0;
+    previousCursorPosition = undefined;
+    cursorWasShown = false;
+  };
+  present.sync = (output: string) => {
+    const cursor = activeCursor();
+    cursorDirty = false;
+    const lines = output.split("\n");
+    previousOutput = output;
+    previousLineCount = lines.length;
+    if (!cursor && cursorWasShown) stream.write(hideCursorEscape);
+    if (cursor) stream.write(buildCursorSuffix(lines.length - 1, cursor));
+    previousCursorPosition = cursor ? { ...cursor } : undefined;
+    cursorWasShown = cursor !== undefined;
+  };
+  present.setCursorPosition = (position: CursorPosition | undefined) => {
+    cursorPosition = position;
+    cursorDirty = true;
+  };
+  present.isCursorDirty = () => cursorDirty;
+  present.willRender = (output: string) => hasChanges(output, activeCursor());
+  return present;
+}

package/src/terminal/input.ts

@@ -0,0 +1,86 @@
+import type { CapabilitiesStore } from "#/capabilities/store.ts";
+import { createInputParser, type InputEvent } from "#/input-parser.ts";
+
+export type MouseButton = "left" | "middle" | "right" | "none" | "wheel-up" | "wheel-down";
+export type TerminalMouseEvent = {
+  readonly type: "press" | "release" | "move" | "wheel";
+  readonly x: number;
+  readonly y: number;
+  readonly button: MouseButton;
+  readonly shift: boolean;
+  readonly alt: boolean;
+  readonly ctrl: boolean;
+};
+
+const sgrMouse = /^\u001B\[<(\d+);(\d+);(\d+)([Mm])$/;
+
+/** Stateful stdin decoder that separates terminal reports from application input. */
+export class TerminalInput {
+  readonly #parser = createInputParser();
+  readonly #capabilities: CapabilitiesStore;
+  readonly #mouseListeners = new Set<(event: TerminalMouseEvent) => void>();
+
+  constructor(capabilities: CapabilitiesStore) {
+    this.#capabilities = capabilities;
+  }
+
+  push(chunk: string): InputEvent[] {
+    return this.#parser.push(chunk).filter((event) => {
+      if (typeof event !== "string") return true;
+      if (this.#capabilities.ingest(event)) return false;
+      const mouse = parseMouseEvent(event);
+      if (!mouse) return true;
+      for (const listener of this.#mouseListeners) listener(mouse);
+      return false;
+    });
+  }
+
+  subscribeMouse(listener: (event: TerminalMouseEvent) => void): () => void {
+    this.#mouseListeners.add(listener);
+    return () => this.#mouseListeners.delete(listener);
+  }
+
+  hasPendingEscape(): boolean {
+    return this.#parser.hasPendingEscape();
+  }
+
+  flushPendingEscape(): string | undefined {
+    return this.#parser.flushPendingEscape();
+  }
+
+  reset(): void {
+    this.#parser.reset();
+  }
+}
+
+export function parseMouseEvent(sequence: string): TerminalMouseEvent | undefined {
+  const match = sequence.match(sgrMouse);
+  if (!match) return;
+  const code = Number(match[1]);
+  const column = Number(match[2]);
+  const row = Number(match[3]);
+  if (column < 1 || row < 1) return;
+  const wheel = (code & 64) !== 0;
+  const move = (code & 32) !== 0;
+  const buttonCode = code & 3;
+  const button: MouseButton = wheel
+    ? buttonCode === 0
+      ? "wheel-up"
+      : "wheel-down"
+    : (["left", "middle", "right", "none"] as const)[buttonCode]!;
+  return {
+    type: wheel
+      ? "wheel"
+      : move
+        ? "move"
+        : match[4] === "m" || buttonCode === 3
+          ? "release"
+          : "press",
+    x: column - 1,
+    y: row - 1,
+    button,
+    shift: (code & 4) !== 0,
+    alt: (code & 8) !== 0,
+    ctrl: (code & 16) !== 0,
+  };
+}

package/src/terminal/render-scheduler.ts

@@ -0,0 +1,37 @@
+import { throttle, type Throttled } from "#/throttle.ts";
+
+export type RenderScheduler = {
+  readonly intervalMs: number;
+  readonly throttled: Throttled<never[]> | undefined;
+  readonly pending: boolean;
+  readonly schedule: () => void;
+  readonly immediate: () => void;
+  markRendered: () => void;
+};
+
+/** Owns frame cadence independently of React reconciliation and terminal presentation. */
+export function createRenderScheduler(
+  render: () => void,
+  options: { readonly unthrottled: boolean; readonly maxFps: number },
+): RenderScheduler {
+  const frameInterval = options.maxFps > 0 ? Math.max(1, Math.ceil(1000 / options.maxFps)) : 0;
+  let pending = false;
+  const throttled = options.unthrottled ? undefined : throttle(render, frameInterval);
+  return {
+    intervalMs: options.unthrottled ? 0 : frameInterval,
+    throttled,
+    get pending() {
+      return pending;
+    },
+    schedule: options.unthrottled
+      ? render
+      : () => {
+          pending = true;
+          throttled!();
+        },
+    immediate: render,
+    markRendered() {
+      pending = false;
+    },
+  };
+}