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

package/src/log-update.ts

@@ -0,0 +1,370 @@
+import { cliCursor } from "./ansi/cursor.ts";
+import { ansiEscapes } from "./ansi/escapes.ts";
+import {
+  type CursorPosition,
+  cursorPositionChanged,
+  buildCursorSuffix,
+  buildCursorOnlySequence,
+  buildReturnToBottomPrefix,
+  hideCursorEscape,
+} from "./cursor-position.ts";
+
+export type { CursorPosition } from "./cursor-position.ts";
+
+export type LogUpdate = {
+  clear: () => void;
+  done: () => void;
+  reset: () => void;
+  sync: (str: string) => void;
+  setCursorPosition: (position: CursorPosition | undefined) => void;
+  isCursorDirty: () => boolean;
+  willRender: (str: string) => boolean;
+  (str: string): boolean;
+};
+
+// Count visible lines in a string, ignoring the trailing empty element
+// that `split('\n')` produces when the string ends with '\n'.
+const visibleLineCount = (lines: string[], str: string): number =>
+  str.endsWith("\n") ? lines.length - 1 : lines.length;
+
+const createStandard = (stream: NodeJS.WritableStream, { showCursor = false } = {}): LogUpdate => {
+  let previousLineCount = 0;
+  let previousOutput = "";
+  let hasHiddenCursor = false;
+  let cursorPosition: CursorPosition | undefined;
+  let cursorDirty = false;
+  let previousCursorPosition: CursorPosition | undefined;
+  let cursorWasShown = false;
+
+  const getActiveCursor = () => (cursorDirty ? cursorPosition : undefined);
+  const hasChanges = (str: string, activeCursor: CursorPosition | undefined): boolean => {
+    const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
+    return str !== previousOutput || cursorChanged;
+  };
+
+  const render = (str: string) => {
+    if (!showCursor && !hasHiddenCursor) {
+      cliCursor.hide(stream);
+      hasHiddenCursor = true;
+    }
+
+    // Only use cursor if setCursorPosition was called since last render.
+    // This ensures stale positions don't persist after component unmount.
+    const activeCursor = getActiveCursor();
+    cursorDirty = false;
+    const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
+
+    if (!hasChanges(str, activeCursor)) {
+      return false;
+    }
+
+    const lines = str.split("\n");
+    const cursorSuffix = buildCursorSuffix(lines.length - 1, activeCursor);
+
+    if (str === previousOutput && cursorChanged) {
+      stream.write(
+        buildCursorOnlySequence({
+          cursorWasShown,
+          previousLineCount,
+          previousCursorPosition,
+          cursorPosition: activeCursor,
+        }),
+      );
+    } else {
+      previousOutput = str;
+      const returnPrefix = buildReturnToBottomPrefix(
+        cursorWasShown,
+        previousLineCount,
+        previousCursorPosition,
+      );
+      stream.write(returnPrefix + ansiEscapes.eraseLines(previousLineCount) + str + cursorSuffix);
+      previousLineCount = lines.length;
+    }
+
+    previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+    cursorWasShown = activeCursor !== undefined;
+    return true;
+  };
+
+  render.clear = () => {
+    const prefix = buildReturnToBottomPrefix(
+      cursorWasShown,
+      previousLineCount,
+      previousCursorPosition,
+    );
+    stream.write(prefix + ansiEscapes.eraseLines(previousLineCount));
+    previousOutput = "";
+    previousLineCount = 0;
+    previousCursorPosition = undefined;
+    cursorWasShown = false;
+  };
+
+  render.done = () => {
+    previousOutput = "";
+    previousLineCount = 0;
+    previousCursorPosition = undefined;
+    cursorWasShown = false;
+
+    if (!showCursor) {
+      cliCursor.show(stream);
+      hasHiddenCursor = false;
+    }
+  };
+
+  render.reset = () => {
+    previousOutput = "";
+    previousLineCount = 0;
+    previousCursorPosition = undefined;
+    cursorWasShown = false;
+  };
+
+  render.sync = (str: string) => {
+    const activeCursor = cursorDirty ? cursorPosition : undefined;
+    cursorDirty = false;
+
+    const lines = str.split("\n");
+    previousOutput = str;
+    previousLineCount = lines.length;
+
+    if (!activeCursor && cursorWasShown) {
+      stream.write(hideCursorEscape);
+    }
+
+    if (activeCursor) {
+      stream.write(buildCursorSuffix(lines.length - 1, activeCursor));
+    }
+
+    previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+    cursorWasShown = activeCursor !== undefined;
+  };
+
+  render.setCursorPosition = (position: CursorPosition | undefined) => {
+    cursorPosition = position;
+    cursorDirty = true;
+  };
+
+  render.isCursorDirty = () => cursorDirty;
+  render.willRender = (str: string) => hasChanges(str, getActiveCursor());
+
+  return render;
+};
+
+const createIncremental = (
+  stream: NodeJS.WritableStream,
+  { showCursor = false } = {},
+): LogUpdate => {
+  let previousLines: string[] = [];
+  let previousOutput = "";
+  let hasHiddenCursor = false;
+  let cursorPosition: CursorPosition | undefined;
+  let cursorDirty = false;
+  let previousCursorPosition: CursorPosition | undefined;
+  let cursorWasShown = false;
+
+  const getActiveCursor = () => (cursorDirty ? cursorPosition : undefined);
+  const hasChanges = (str: string, activeCursor: CursorPosition | undefined): boolean => {
+    const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
+    return str !== previousOutput || cursorChanged;
+  };
+
+  const render = (str: string) => {
+    if (!showCursor && !hasHiddenCursor) {
+      cliCursor.hide(stream);
+      hasHiddenCursor = true;
+    }
+
+    // Only use cursor if setCursorPosition was called since last render.
+    // This ensures stale positions don't persist after component unmount.
+    const activeCursor = getActiveCursor();
+    cursorDirty = false;
+    const cursorChanged = cursorPositionChanged(activeCursor, previousCursorPosition);
+
+    if (!hasChanges(str, activeCursor)) {
+      return false;
+    }
+
+    const nextLines = str.split("\n");
+    const visibleCount = visibleLineCount(nextLines, str);
+    const previousVisible = visibleLineCount(previousLines, previousOutput);
+
+    if (str === previousOutput && cursorChanged) {
+      stream.write(
+        buildCursorOnlySequence({
+          cursorWasShown,
+          previousLineCount: previousLines.length,
+          previousCursorPosition,
+          cursorPosition: activeCursor,
+        }),
+      );
+      previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+      cursorWasShown = activeCursor !== undefined;
+      return true;
+    }
+
+    const returnPrefix = buildReturnToBottomPrefix(
+      cursorWasShown,
+      previousLines.length,
+      previousCursorPosition,
+    );
+
+    if (str === "\n" || previousOutput.length === 0) {
+      const cursorSuffix = buildCursorSuffix(nextLines.length - 1, activeCursor);
+      stream.write(
+        returnPrefix + ansiEscapes.eraseLines(previousLines.length) + str + cursorSuffix,
+      );
+      cursorWasShown = activeCursor !== undefined;
+      previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+      previousOutput = str;
+      previousLines = nextLines;
+      return true;
+    }
+
+    // A frame that grew may need rows past the bottom margin. The
+    // incremental walk moves over unchanged lines with cursorNextLine,
+    // which clamps at the bottom margin instead of scrolling (only a
+    // line feed scrolls), so a grown frame that reaches the bottom
+    // desynchronizes the tracked cursor position from the terminal.
+    // Rewrite the whole frame instead — every line is emitted with a
+    // newline, which scrolls correctly at the bottom.
+    if (visibleCount > previousVisible) {
+      const cursorSuffix = buildCursorSuffix(visibleCount, activeCursor);
+      stream.write(
+        returnPrefix + ansiEscapes.eraseLines(previousLines.length) + str + cursorSuffix,
+      );
+      cursorWasShown = activeCursor !== undefined;
+      previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+      previousOutput = str;
+      previousLines = nextLines;
+      return true;
+    }
+
+    const hasTrailingNewline = str.endsWith("\n");
+
+    // We aggregate all chunks for incremental rendering into a buffer, and then write them to stdout at the end.
+    const buffer: string[] = [];
+
+    buffer.push(returnPrefix);
+
+    // Clear extra lines if the current content's line count is lower than the previous.
+    if (visibleCount < previousVisible) {
+      const previousHadTrailingNewline = previousOutput.endsWith("\n");
+      const extraSlot = previousHadTrailingNewline ? 1 : 0;
+      buffer.push(
+        ansiEscapes.eraseLines(previousVisible - visibleCount + extraSlot),
+        ansiEscapes.cursorUp(visibleCount),
+      );
+    } else {
+      buffer.push(ansiEscapes.cursorUp(previousLines.length - 1));
+    }
+
+    for (let i = 0; i < visibleCount; i++) {
+      const isLastLine = i === visibleCount - 1;
+
+      // We do not write lines if the contents are the same. This prevents flickering during renders.
+      if (nextLines[i] === previousLines[i]) {
+        // Don't move past the last line when there's no trailing newline,
+        // otherwise the cursor overshoots the rendered block.
+        if (!isLastLine || hasTrailingNewline) {
+          buffer.push(ansiEscapes.cursorNextLine);
+        }
+
+        continue;
+      }
+
+      buffer.push(
+        ansiEscapes.cursorTo(0) +
+          nextLines[i] +
+          ansiEscapes.eraseEndLine +
+          // Don't append newline after the last line when the input
+          // has no trailing newline (fullscreen mode).
+          (isLastLine && !hasTrailingNewline ? "" : "\n"),
+      );
+    }
+
+    const cursorSuffix = buildCursorSuffix(nextLines.length - 1, activeCursor);
+    buffer.push(cursorSuffix);
+
+    stream.write(buffer.join(""));
+
+    cursorWasShown = activeCursor !== undefined;
+    previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+    previousOutput = str;
+    previousLines = nextLines;
+    return true;
+  };
+
+  render.clear = () => {
+    const prefix = buildReturnToBottomPrefix(
+      cursorWasShown,
+      previousLines.length,
+      previousCursorPosition,
+    );
+    stream.write(prefix + ansiEscapes.eraseLines(previousLines.length));
+    previousOutput = "";
+    previousLines = [];
+    previousCursorPosition = undefined;
+    cursorWasShown = false;
+  };
+
+  render.done = () => {
+    previousOutput = "";
+    previousLines = [];
+    previousCursorPosition = undefined;
+    cursorWasShown = false;
+
+    if (!showCursor) {
+      cliCursor.show(stream);
+      hasHiddenCursor = false;
+    }
+  };
+
+  render.reset = () => {
+    previousOutput = "";
+    previousLines = [];
+    previousCursorPosition = undefined;
+    cursorWasShown = false;
+  };
+
+  render.sync = (str: string) => {
+    const activeCursor = cursorDirty ? cursorPosition : undefined;
+    cursorDirty = false;
+
+    const lines = str.split("\n");
+    previousOutput = str;
+    previousLines = lines;
+
+    if (!activeCursor && cursorWasShown) {
+      stream.write(hideCursorEscape);
+    }
+
+    if (activeCursor) {
+      stream.write(buildCursorSuffix(lines.length - 1, activeCursor));
+    }
+
+    previousCursorPosition = activeCursor ? { ...activeCursor } : undefined;
+    cursorWasShown = activeCursor !== undefined;
+  };
+
+  render.setCursorPosition = (position: CursorPosition | undefined) => {
+    cursorPosition = position;
+    cursorDirty = true;
+  };
+
+  render.isCursorDirty = () => cursorDirty;
+  render.willRender = (str: string) => hasChanges(str, getActiveCursor());
+
+  return render;
+};
+
+const create = (
+  stream: NodeJS.WritableStream,
+  { showCursor = false, incremental = false } = {},
+): LogUpdate => {
+  if (incremental) {
+    return createIncremental(stream, { showCursor });
+  }
+
+  return createStandard(stream, { showCursor });
+};
+
+export const logUpdate = { create };

package/src/measure-element.ts

@@ -0,0 +1,62 @@
+import { type DOMElement } from "./dom.ts";
+
+type Output = {
+  /**
+	Horizontal position (0-based column) within the live layout region.
+	*/
+  x: number;
+
+  /**
+	Vertical position (0-based row) within the live layout region.
+	*/
+  y: number;
+
+  /**
+	Element width.
+	*/
+  width: number;
+
+  /**
+	Element height.
+	*/
+  height: number;
+};
+
+/**
+Measure the layout metrics of a particular `<Box>` element.
+Returns an object with `x`, `y`, `width`, and `height` properties.
+
+`x` and `y` are the element's position within the live layout region, computed by walking up the layout tree and accumulating each ancestor's offset. These are layout-tree coordinates, not terminal viewport coordinates. To compare them with mouse events, convert the event coordinates using the live region's viewport position. This is necessary even in alternate-screen mode when output, such as `<Static>` content, appears above the live region.
+
+Note: `measureElement()` returns `{x: 0, y: 0, width: 0, height: 0}` when called during render (before layout is calculated). Call it from post-render code, such as `useEffect`, `useLayoutEffect`, input handlers, or timer callbacks. When content changes, pass the relevant dependency to your effect so it re-measures after each update.
+*/
+export const measureElement = (node: DOMElement): Output => {
+  const { yogaNode } = node;
+
+  if (!yogaNode) {
+    return { x: 0, y: 0, width: 0, height: 0 };
+  }
+
+  let x = yogaNode.getComputedLeft();
+  let y = yogaNode.getComputedTop();
+
+  let current = node.parentNode;
+
+  while (current) {
+    if (current.yogaNode) {
+      x += current.yogaNode.getComputedLeft();
+      y += current.yogaNode.getComputedTop();
+    }
+
+    current = current.parentNode;
+  }
+
+  return {
+    x,
+    y,
+    width: yogaNode.getComputedWidth(),
+    height: yogaNode.getComputedHeight(),
+  };
+};
+
+export type { Output as ElementMetrics };

package/src/measure-text.ts

@@ -0,0 +1,31 @@
+import { widestLine } from "./ansi/widest-line.ts";
+import { QuickLru as QuickLRU } from "./quick-lru.ts";
+
+const cache = new QuickLRU<string, Output>({ maxSize: 4096 });
+
+type Output = {
+  width: number;
+  height: number;
+};
+
+export const measureText = (text: string): Output => {
+  if (text.length === 0) {
+    return {
+      width: 0,
+      height: 0,
+    };
+  }
+
+  const cachedDimensions = cache.get(text);
+
+  if (cachedDimensions) {
+    return cachedDimensions;
+  }
+
+  const width = widestLine(text);
+  const height = text.split("\n").length;
+  const dimensions = { width, height };
+  cache.set(text, dimensions);
+
+  return dimensions;
+};