@alchemy.run/sigil 0.0.0-alpha.1 → 0.0.0-alpha.10

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,92 @@
+import { isTerminalQueryResponse } from "#/capabilities/query.ts";
+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).flatMap((event): InputEvent[] => {
+      if (typeof event !== "string") return [event];
+      // A user Escape immediately before a reply is not an Alt-modified key.
+      if (event.startsWith("\u001B\u001B") && isTerminalQueryResponse(event.slice(1))) {
+        return ["\u001B"];
+      }
+      if (this.#capabilities.ingest(event)) return [];
+      if (isTerminalQueryResponse(event)) return [];
+      const mouse = parseMouseEvent(event);
+      if (!mouse) return [event];
+      for (const listener of this.#mouseListeners) listener(mouse);
+      return [];
+    });
+  }
+
+  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;
+    },
+  };
+}

package/src/terminal/screen-presenter.ts

@@ -0,0 +1,242 @@
+import { cliCursor } from "#/ansi/cursor.ts";
+import { ansiEscapes } from "#/ansi/escapes.ts";
+import {
+  buildCursorOnlySequence,
+  buildCursorSuffix,
+  buildReturnToBottomPrefix,
+  cursorPositionChanged,
+  type CursorPosition,
+} from "#/cursor-position.ts";
+import { cellAttributes, cellsEqual, type Cell } from "#/screen/cell.ts";
+import type { ColorProfile } from "#/screen/color-profile.ts";
+import type { Line, Screen } from "#/screen/screen.ts";
+import { serializeLine, serializeScreen } from "#/screen/serialize.ts";
+
+type Write = (data: string) => boolean;
+
+/** Presents structured frames in an inline terminal region. */
+export class ScreenPresenter {
+  #screen: Screen | undefined;
+  #lineCount = 0;
+  #cursor: CursorPosition | undefined;
+  #cursorWasShown = false;
+  #fullscreen = false;
+  #hidden = false;
+  readonly #write: Write;
+  readonly #stream: NodeJS.WritableStream;
+
+  constructor(write: Write, stream: NodeJS.WritableStream) {
+    this.#write = write;
+    this.#stream = stream;
+  }
+
+  present(
+    screen: Screen,
+    options: {
+      readonly colorProfile: ColorProfile;
+      readonly cursor?: CursorPosition;
+      readonly fullscreen?: boolean;
+      readonly forceRewrite?: boolean;
+    },
+  ): boolean {
+    if (!this.#hidden) {
+      cliCursor.hide(this.#stream);
+      this.#hidden = true;
+    }
+
+    const previousScreen = this.#screen;
+    const sameScreen = previousScreen !== undefined && screensEqual(previousScreen, screen);
+    const cursorChanged = cursorPositionChanged(options.cursor, this.#cursor);
+    const fullscreen = options.fullscreen ?? false;
+    const presentationModeChanged = this.#fullscreen !== fullscreen;
+    if (!options.forceRewrite && sameScreen && !cursorChanged && !presentationModeChanged) {
+      return false;
+    }
+
+    if (!options.forceRewrite && sameScreen && !presentationModeChanged) {
+      this.#write(
+        buildCursorOnlySequence({
+          cursorWasShown: this.#cursorWasShown,
+          previousLineCount: this.#lineCount,
+          previousCursorPosition: this.#cursor,
+          cursorPosition: options.cursor,
+        }),
+      );
+      this.#remember(screen, options.cursor, options.fullscreen ?? false);
+      return true;
+    }
+
+    const canRewriteSuffix =
+      !options.forceRewrite &&
+      previousScreen !== undefined &&
+      previousScreen.width === screen.width &&
+      this.#fullscreen === fullscreen;
+    const firstChangedRow = canRewriteSuffix
+      ? findFirstChangedRow(previousScreen, screen)
+      : undefined;
+    const serializeOptions = {
+      colorProfile: options.colorProfile,
+      styles: options.colorProfile !== "none",
+    } as const;
+
+    if (firstChangedRow !== undefined) {
+      const eraseCount = this.#lineCount - firstChangedRow;
+      const body = screen
+        .toRows()
+        .slice(firstChangedRow)
+        .map((line) => serializeLine(line, serializeOptions))
+        .join("\n");
+      const output = fullscreen || body === "" ? body : `${body}\n`;
+      this.#write(
+        buildReturnToBottomPrefix(this.#cursorWasShown, this.#lineCount, this.#cursor) +
+          ansiEscapes.eraseLines(eraseCount) +
+          output +
+          buildCursorSuffix(screen.height - (fullscreen ? 1 : 0), options.cursor),
+      );
+    } else {
+      const body = serializeScreen(screen, serializeOptions);
+      const output = fullscreen ? body : `${body}\n`;
+      this.#write(
+        buildReturnToBottomPrefix(this.#cursorWasShown, this.#lineCount, this.#cursor) +
+          ansiEscapes.eraseLines(this.#lineCount) +
+          output +
+          buildCursorSuffix(screen.height - (fullscreen ? 1 : 0), options.cursor),
+      );
+    }
+
+    this.#remember(screen, options.cursor, fullscreen);
+    return true;
+  }
+
+  willPresent(
+    screen: Screen,
+    cursor: CursorPosition | undefined,
+    fullscreen = false,
+    forceRewrite = false,
+  ): boolean {
+    return (
+      forceRewrite ||
+      this.#screen === undefined ||
+      !screensEqual(this.#screen, screen) ||
+      cursorPositionChanged(cursor, this.#cursor) ||
+      fullscreen !== this.#fullscreen
+    );
+  }
+
+  /**
+  Erases the presented frame from the cursor upward.
+
+  `columns` is the terminal's current width. When it is narrower than the width
+  the frame was painted at, a reflowing emulator (xterm.js, Ghostty, kitty,
+  iTerm2, WezTerm, tmux, …) has already rewrapped every wider row onto several
+  physical rows before the resize event reaches us, so the erase has to cover
+  that physical footprint. Erasing only the logical row count leaves the frame's
+  top rows behind as ghosts, one more batch per resize event.
+  */
+  clear(options: { readonly columns?: number } = {}): void {
+    this.#write(
+      buildReturnToBottomPrefix(this.#cursorWasShown, this.#lineCount, this.#cursor) +
+        ansiEscapes.eraseLines(this.#physicalLineCount(options.columns)),
+    );
+    this.#lineCount = 0;
+    this.#cursor = undefined;
+    this.#cursorWasShown = false;
+    this.#fullscreen = false;
+  }
+
+  #physicalLineCount(columns: number | undefined): number {
+    if (
+      this.#screen === undefined ||
+      this.#lineCount === 0 ||
+      columns === undefined ||
+      columns < 1
+    ) {
+      return this.#lineCount;
+    }
+    let rows = 0;
+    for (const line of this.#screen.toRows()) {
+      rows += Math.max(1, Math.ceil(contentWidth(line) / columns));
+    }
+    return rows + (this.#fullscreen ? 0 : 1);
+  }
+
+  reset(): void {
+    this.#screen = undefined;
+    this.#lineCount = 0;
+    this.#cursor = undefined;
+    this.#cursorWasShown = false;
+  }
+
+  done(): void {
+    this.reset();
+    if (this.#hidden) {
+      cliCursor.show(this.#stream);
+      this.#hidden = false;
+    }
+  }
+
+  get current(): Screen | undefined {
+    return this.#screen;
+  }
+
+  #remember(screen: Screen, cursor: CursorPosition | undefined, fullscreen: boolean): void {
+    this.#screen = screen;
+    this.#lineCount = screen.height + (fullscreen ? 0 : 1);
+    this.#cursor = cursor ? { ...cursor } : undefined;
+    this.#cursorWasShown = cursor !== undefined;
+    this.#fullscreen = fullscreen;
+  }
+}
+
+/**
+The columns a row occupies once written: everything up to its last visible
+cell. Trailing unstyled blanks are trimmed by the serializer and never reach
+the terminal, while styled blanks (a highlighted tab's padding) do.
+*/
+function contentWidth(line: Line): number {
+  let width = 0;
+  let end = 0;
+  for (const cell of line) {
+    width += cell.width;
+    if (!isBlank(cell)) end = width;
+  }
+  return end;
+}
+
+function isBlank(cell: Cell): boolean {
+  const { style } = cell;
+  return (
+    (cell.grapheme === " " || cell.width === 0) &&
+    style.foreground === undefined &&
+    style.background === undefined &&
+    style.underlineColor === undefined &&
+    style.underline === "none" &&
+    style.attributes === cellAttributes.none &&
+    cell.hyperlink === undefined
+  );
+}
+
+function findFirstChangedRow(previous: Screen, next: Screen): number | undefined {
+  const height = Math.max(previous.height, next.height);
+  for (let y = 0; y < height; y++) {
+    if (!rowsEqual(previous, next, y)) return y;
+  }
+  return undefined;
+}
+
+function rowsEqual(left: Screen, right: Screen, y: number): boolean {
+  // Rows can extend past the nominal width when overflow content painted.
+  const length = Math.max(left.rowLength(y), right.rowLength(y));
+  for (let x = 0; x < length; x++) {
+    if (!cellsEqual(left.cellAt(x, y), right.cellAt(x, y))) return false;
+  }
+  return true;
+}
+
+function screensEqual(left: Screen, right: Screen): boolean {
+  if (left.width !== right.width || left.height !== right.height) return false;
+  for (let y = 0; y < left.height; y++) {
+    if (!rowsEqual(left, right, y)) return false;
+  }
+  return true;
+}