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

package/src/render-node-to-output.ts

@@ -0,0 +1,191 @@
+import { widestLine } from "./ansi/widest-line.ts";
+import { type DOMElement } from "./dom.ts";
+import { getMaxWidth } from "./get-max-width.ts";
+import { indentString } from "./indent-string.ts";
+import type { Output } from "./output.ts";
+import { renderBackground } from "./render-background.ts";
+import { renderBorder } from "./render-border.ts";
+import { squashTextNodes } from "./squash-text-nodes.ts";
+import { wrapText } from "./wrap-text.ts";
+import { Yoga } from "./yoga/index.ts";
+
+// If parent container is `<Box>`, text nodes will be treated as separate nodes in
+// the tree and will have their own coordinates in the layout.
+// To ensure text nodes are aligned correctly, take X and Y of the first text node
+// and use it as offset for the rest of the nodes
+// Only first node is taken into account, because other text nodes can't have margin or padding,
+// so their coordinates will be relative to the first node anyway
+const applyPaddingToText = (node: DOMElement, text: string): string => {
+  const yogaNode = node.childNodes[0]?.yogaNode;
+
+  if (yogaNode) {
+    const offsetX = yogaNode.getComputedLeft();
+    const offsetY = yogaNode.getComputedTop();
+    text = "\n".repeat(offsetY) + indentString(text, offsetX);
+  }
+
+  return text;
+};
+
+export type OutputTransformer = (s: string, index: number) => string;
+
+export const renderNodeToScreenReaderOutput = (
+  node: DOMElement,
+  options: {
+    parentRole?: string;
+    skipStaticElements?: boolean;
+  } = {},
+): string => {
+  if (options.skipStaticElements && node.internal_static) {
+    return "";
+  }
+
+  if (node.yogaNode?.getDisplay() === Yoga.DISPLAY_NONE) {
+    return "";
+  }
+
+  let output = "";
+
+  if (node.nodeName === "ink-text") {
+    output = squashTextNodes(node);
+  } else if (node.nodeName === "ink-box" || node.nodeName === "ink-root") {
+    const separator =
+      node.style.flexDirection === "row" || node.style.flexDirection === "row-reverse" ? " " : "\n";
+
+    const childNodes =
+      node.style.flexDirection === "row-reverse" || node.style.flexDirection === "column-reverse"
+        ? [...node.childNodes].reverse()
+        : [...node.childNodes];
+
+    output = childNodes
+      .map((childNode) => {
+        const screenReaderOutput = renderNodeToScreenReaderOutput(childNode as DOMElement, {
+          parentRole: node.internal_accessibility?.role,
+          skipStaticElements: options.skipStaticElements,
+        });
+        return screenReaderOutput;
+      })
+      .filter(Boolean)
+      .join(separator);
+  }
+
+  if (node.internal_accessibility) {
+    const { role, state } = node.internal_accessibility;
+
+    if (state) {
+      const stateKeys = Object.keys(state) as Array<keyof typeof state>;
+      const stateDescription = stateKeys.filter((key) => state[key]).join(", ");
+
+      if (stateDescription) {
+        output = `(${stateDescription}) ${output}`;
+      }
+    }
+
+    if (role && role !== options.parentRole) {
+      output = `${role}: ${output}`;
+    }
+  }
+
+  return output;
+};
+
+// After nodes are laid out, render each to output object, which later gets rendered to terminal
+export const renderNodeToOutput = (
+  node: DOMElement,
+  output: Output,
+  options: {
+    offsetX?: number;
+    offsetY?: number;
+    transformers?: OutputTransformer[];
+    skipStaticElements: boolean;
+  },
+) => {
+  const { offsetX = 0, offsetY = 0, transformers = [], skipStaticElements } = options;
+
+  if (skipStaticElements && node.internal_static) {
+    return;
+  }
+
+  const { yogaNode } = node;
+
+  if (yogaNode) {
+    if (yogaNode.getDisplay() === Yoga.DISPLAY_NONE) {
+      return;
+    }
+
+    // Left and top positions in Yoga are relative to their parent node
+    const x = offsetX + yogaNode.getComputedLeft();
+    const y = offsetY + yogaNode.getComputedTop();
+
+    // Transformers are functions that transform final text output of each component
+    // See Output class for logic that applies transformers
+    let newTransformers = transformers;
+
+    if (typeof node.internal_transform === "function") {
+      newTransformers = [node.internal_transform, ...transformers];
+    }
+
+    if (node.nodeName === "ink-text") {
+      let text = squashTextNodes(node);
+
+      if (text.length > 0) {
+        const currentWidth = widestLine(text);
+        const maxWidth = getMaxWidth(yogaNode);
+
+        if (currentWidth > maxWidth) {
+          const textWrap = node.style.textWrap ?? "wrap";
+          text = wrapText(text, maxWidth, textWrap);
+        }
+
+        text = applyPaddingToText(node, text);
+
+        output.write(x, y, text, { transformers: newTransformers });
+      }
+
+      return;
+    }
+
+    let clipped = false;
+
+    if (node.nodeName === "ink-box") {
+      renderBackground(x, y, node, output);
+      renderBorder(x, y, node, output);
+
+      const clipHorizontally =
+        node.style.overflowX === "hidden" || node.style.overflow === "hidden";
+      const clipVertically = node.style.overflowY === "hidden" || node.style.overflow === "hidden";
+
+      if (clipHorizontally || clipVertically) {
+        const x1 = clipHorizontally ? x + yogaNode.getComputedBorder(Yoga.EDGE_LEFT) : undefined;
+
+        const x2 = clipHorizontally
+          ? x + yogaNode.getComputedWidth() - yogaNode.getComputedBorder(Yoga.EDGE_RIGHT)
+          : undefined;
+
+        const y1 = clipVertically ? y + yogaNode.getComputedBorder(Yoga.EDGE_TOP) : undefined;
+
+        const y2 = clipVertically
+          ? y + yogaNode.getComputedHeight() - yogaNode.getComputedBorder(Yoga.EDGE_BOTTOM)
+          : undefined;
+
+        output.clip({ x1, x2, y1, y2 });
+        clipped = true;
+      }
+    }
+
+    if (node.nodeName === "ink-root" || node.nodeName === "ink-box") {
+      for (const childNode of node.childNodes) {
+        renderNodeToOutput(childNode as DOMElement, output, {
+          offsetX: x,
+          offsetY: y,
+          transformers: newTransformers,
+          skipStaticElements,
+        });
+      }
+
+      if (clipped) {
+        output.unclip();
+      }
+    }
+  }
+};

package/src/render-to-string.ts

@@ -0,0 +1,131 @@
+import type { ReactNode } from "react";
+import { LegacyRoot } from "react-reconciler/constants.js";
+
+import { createNode, type DOMElement } from "./dom.ts";
+import { reconciler } from "./reconciler.ts";
+import { renderer } from "./renderer.ts";
+import { Yoga } from "./yoga/index.ts";
+
+export type RenderToStringOptions = {
+  /**
+	Width of the virtual terminal in columns.
+
+	@default 80
+	*/
+  columns?: number;
+};
+
+/**
+Render a React element to a string synchronously. Unlike `render()`, this function does not write to stdout, does not set up any terminal event listeners, and returns the rendered output as a string.
+
+Useful for generating documentation, writing output to files, testing, or any scenario where you need the rendered output as a string without starting a persistent terminal application.
+
+**Notes:**
+
+- Terminal-specific hooks (`useInput`, `useStdin`, `useStdout`, `useStderr`, `useApp`, `useFocus`, `useFocusManager`) return default no-op values since there is no terminal session. They will not throw, but they will not function as in a live terminal.
+- `useEffect` callbacks will execute during rendering (due to synchronous rendering mode), but state updates they trigger will not affect the returned output, which reflects the initial render.
+- `useLayoutEffect` callbacks fire synchronously during commit, so state updates they trigger **will** be reflected in the output.
+- The `<Static>` component is supported — its output is prepended to the dynamic output.
+- If a component throws during rendering, the error is propagated to the caller after cleanup.
+
+@example
+```
+import {renderToString, Text, Box} from 'ink';
+
+const output = renderToString(
+	<Box padding={1}>
+		<Text color="green">Hello World</Text>
+	</Box>,
+	{columns: 40}
+);
+
+console.log(output);
+```
+*/
+export const renderToString = (node: ReactNode, options?: RenderToStringOptions): string => {
+  const columns = options?.columns ?? 80;
+
+  // Create a standalone root node — no stdout, stdin, or terminal bindings
+  const rootNode: DOMElement = createNode("ink-root");
+
+  // Capture static output from intermediate renders.
+  // The <Static> component uses useLayoutEffect to clear its children after
+  // the first commit. The reconciler's resetAfterCommit calls onImmediateRender
+  // when static content is dirty (and returns early, skipping the normal
+  // onRender callback), giving us a chance to capture it before it's cleared
+  // by the subsequent re-render.
+  let capturedStaticOutput = "";
+
+  rootNode.onComputeLayout = () => {
+    rootNode.yogaNode!.setWidth(columns);
+    rootNode.yogaNode!.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR);
+  };
+
+  rootNode.onImmediateRender = () => {
+    const { staticOutput } = renderer(rootNode, false);
+    if (staticOutput && staticOutput !== "\n") {
+      capturedStaticOutput += staticOutput;
+    }
+  };
+
+  // Capture the first uncaught error so we can re-throw it after cleanup.
+  // React's reconciler catches component errors internally and reports them
+  // via onUncaughtError rather than letting them propagate. For a synchronous
+  // utility like renderToString, callers expect errors to throw.
+  let uncaughtError: unknown;
+
+  // Create a reconciler container in legacy (synchronous) mode.
+  // The four trailing callbacks are: onUncaughtError, onCaughtError,
+  // onRecoverableError, and onHostTransitionComplete.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+  const container = reconciler.createContainer(
+    rootNode,
+    LegacyRoot,
+    null,
+    false,
+    null,
+    "render-to-string",
+    (error: unknown) => {
+      uncaughtError ??= error;
+    },
+    () => {},
+    () => {},
+    () => {},
+  );
+
+  // Synchronously render the React tree into the container
+  reconciler.updateContainerSync(node, container, null, () => {});
+  reconciler.flushSyncWork();
+
+  // Yoga layout has already been calculated by onComputeLayout during commit.
+  // Render the DOM tree to a string — this captures the dynamic (non-static) output.
+  const { output } = renderer(rootNode, false);
+
+  // Tear down: unmount the tree so the reconciler cleans up child nodes
+  // and runs effect cleanup functions. The reconciler detaches removed
+  // subtrees (removeChildFromContainer → detachYogaSubtree); the garbage
+  // collector reclaims the Yoga nodes.
+  reconciler.updateContainerSync(null, container, null, () => {});
+  reconciler.flushSyncWork();
+
+  // Re-throw after full cleanup so callers see the original error.
+  if (uncaughtError !== undefined) {
+    throw uncaughtError instanceof Error
+      ? uncaughtError
+      : // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        new Error(String(uncaughtError));
+  }
+
+  // The renderer appends a trailing newline to static output for terminal
+  // rendering (so dynamic output starts on a fresh line). Strip it here
+  // so renderToString returns clean output.
+  const normalizedStaticOutput = capturedStaticOutput.endsWith("\n")
+    ? capturedStaticOutput.slice(0, -1)
+    : capturedStaticOutput;
+
+  if (normalizedStaticOutput && output) {
+    return normalizedStaticOutput + "\n" + output;
+  }
+
+  return normalizedStaticOutput || output;
+};

package/src/render.ts

@@ -0,0 +1,276 @@
+import process from "node:process";
+import { Stream, type Writable } from "node:stream";
+
+import type { ReactNode } from "react";
+
+import { Ink, type Options as InkOptions, type RenderMetrics } from "./ink.tsx";
+import { instances } from "./instances.ts";
+import { type KittyKeyboardOptions } from "./kitty-keyboard.ts";
+
+export type RenderOptions = {
+  /**
+	Output stream where the app will be rendered.
+
+	@default process.stdout
+	*/
+  stdout?: NodeJS.WritableStream;
+
+  /**
+	Input stream where app will listen for input.
+
+	@default process.stdin
+	*/
+  stdin?: NodeJS.ReadableStream;
+
+  /**
+	Error stream.
+	@default process.stderr
+	*/
+  stderr?: NodeJS.WritableStream;
+
+  /**
+	If true, each update will be rendered as separate output, without replacing the previous one.
+
+	@default false
+	*/
+  debug?: boolean;
+
+  /**
+	Configure whether Ink should listen for Ctrl+C keyboard input and exit the app. This is needed in case `process.stdin` is in raw mode, because then Ctrl+C is ignored by default and the process is expected to handle it manually.
+
+	@default true
+	*/
+  exitOnCtrlC?: boolean;
+
+  /**
+	Patch console methods to ensure console output doesn't mix with Ink's output.
+
+	Pass `"stdio"` to additionally intercept direct `stdout.write` / `stderr.write` calls on the streams Ink renders to (output from dependencies, native warnings, child tooling). Captured chunks are line-buffered and spliced above the live frame like console output; partial lines are flushed at unmount. Use `onCapturedOutput` to observe captured chunks or take over their display.
+
+	Note: Once unmount starts, Ink restores the native console (and stream writes) before React cleanup runs. Teardown-time output then follows the normal behavior instead of being rerouted through Ink.
+
+	@default true
+	*/
+  patchConsole?: boolean | "stdio";
+
+  /**
+	Observe output captured by `patchConsole` before Ink displays it.
+
+	Receives each captured chunk with its origin (`"console"` or `"stdio"`). Return `true` to take ownership of the chunk: Ink will not display it, so the app can render it itself — for example inside a `<Static>` transcript.
+	*/
+  onCapturedOutput?: (
+    stream: "stdout" | "stderr",
+    data: string,
+    source: "console" | "stdio",
+  ) => boolean | undefined | void;
+
+  /**
+	Runs the given callback after each render and re-render with render metrics.
+
+	Note: this callback runs after Ink commits a frame, but it does not wait for `stdout`/`stderr` stream callbacks.
+	To run code after output is flushed, use `waitUntilRenderFlush()`.
+	*/
+  onRender?: (metrics: RenderMetrics) => void;
+
+  /**
+	Enable screen reader support. See https://github.com/vadimdemedes/ink/blob/master/readme.md#screen-reader-support
+
+	@default process.env['SIGIL_SCREEN_READER'] === 'true'
+	*/
+  isScreenReaderEnabled?: boolean;
+
+  /**
+	Maximum frames per second for render updates.
+	This controls how frequently the UI can update to prevent excessive re-rendering.
+	Higher values allow more frequent updates but may impact performance.
+
+	@default 30
+	*/
+  maxFps?: number;
+
+  /**
+	Enable incremental rendering mode which only updates changed lines instead of redrawing the entire output.
+	This can reduce flickering and improve performance for frequently updating UIs.
+
+	@default false
+	*/
+  incrementalRendering?: boolean;
+
+  /**
+	Enable React Concurrent Rendering mode.
+
+	When enabled:
+	- Suspense boundaries work correctly with async data
+	- `useTransition` and `useDeferredValue` are fully functional
+	- Updates can be interrupted for higher priority work
+
+	Note: Concurrent mode changes the timing of renders. Some tests may need to use `act()` to properly await updates. Reusing the same stdout across multiple `render()` calls without unmounting is unsupported. Call `unmount()` first if you need to change the rendering mode or create a fresh instance.
+
+	@default false
+	*/
+  concurrent?: boolean;
+
+  /**
+	Configure kitty keyboard protocol support for enhanced keyboard input.
+	Enables additional modifiers (super, hyper, capsLock, numLock) and
+	disambiguated key events in terminals that support the protocol.
+
+	@see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+	*/
+  kittyKeyboard?: KittyKeyboardOptions;
+
+  /**
+	Override automatic interactive mode detection.
+
+	By default, Ink detects whether the environment is interactive based on CI detection (via [`is-in-ci`](https://github.com/sindresorhus/is-in-ci)) and `stdout.isTTY`. Most users should not need to set this.
+
+	When non-interactive, Ink disables ANSI erase sequences, cursor manipulation, synchronized output, resize handling, and kitty keyboard auto-detection, writing only the final frame at unmount.
+
+	Set to `false` to force non-interactive mode or `true` to force interactive mode when the automatic detection doesn't suit your use case.
+
+	Note: Reusing the same stdout across multiple `render()` calls without unmounting is unsupported. Call `unmount()` first if you need to change this option or create a fresh instance.
+
+	@default true (false if in CI or `stdout.isTTY` is falsy)
+	*/
+  interactive?: boolean;
+
+  /**
+	Render the app in the terminal's alternate screen buffer. When enabled, the app renders on a separate screen, and the original terminal content is restored when the app exits. This is the same mechanism used by programs like vim, htop, and less.
+
+	Note: The terminal's scrollback buffer is not available while in the alternate screen. This is standard terminal behavior; programs like vim use the alternate screen specifically to avoid polluting the user's scrollback history.
+
+	Note: Ink intentionally treats alternate-screen teardown output as disposable. It does not preserve or replay teardown-time frames, hook writes, or `console.*` output after restoring the primary screen.
+
+	Only works in interactive mode. Ignored when `interactive` is `false` or in a non-interactive environment (CI, piped stdout).
+
+	Note: Reusing the same stdout across multiple `render()` calls without unmounting is unsupported. Call `unmount()` first if you need to change this option or create a fresh instance.
+
+	@default false
+	*/
+  alternateScreen?: boolean;
+};
+
+export type Instance = {
+  /**
+	Replace the previous root node with a new one or update props of the current root node.
+	*/
+  rerender: Ink["render"];
+
+  /**
+	Manually unmount the whole Ink app.
+	*/
+  unmount: Ink["unmount"];
+
+  /**
+	Returns a promise that settles when the app is unmounted.
+
+	It resolves with the value passed to `exit(value)` and rejects with the error passed to `exit(error)`.
+	When `unmount()` is called manually, it settles after unmount-related stdout writes complete.
+
+	@example
+	```jsx
+	const {unmount, waitUntilExit} = render(<MyApp />);
+
+	setTimeout(unmount, 1000);
+
+	await waitUntilExit(); // resolves after `unmount()` is called
+	```
+	*/
+  waitUntilExit: Ink["waitUntilExit"];
+
+  /**
+	Returns a promise that settles after pending render output is flushed to stdout.
+
+	This can be used after `rerender()` when you need to run code only after the frame is written.
+
+	@example
+	```jsx
+	const {rerender, waitUntilRenderFlush} = render(<MyApp step="loading" />);
+
+	rerender(<MyApp step="ready" />);
+	await waitUntilRenderFlush(); // output for "ready" is flushed
+
+	runNextCommand();
+	```
+	*/
+  waitUntilRenderFlush: Ink["waitUntilRenderFlush"];
+
+  /**
+	Unmount the current app and remove the internal Ink instance for this stdout.
+
+	This is mostly useful for advanced cases where you need `render()` to create a fresh instance for the same stream without leaving terminal state such as the alternate screen behind.
+	*/
+  cleanup: () => void;
+
+  /**
+	Clear output.
+	*/
+  clear: () => void;
+};
+
+/**
+Mount a component and render the output.
+*/
+export const render = (node: ReactNode, options?: Writable | RenderOptions): Instance => {
+  const inkOptions: InkOptions = {
+    stdout: process.stdout,
+    stdin: process.stdin,
+    stderr: process.stderr,
+    debug: false,
+    exitOnCtrlC: true,
+    patchConsole: true,
+    maxFps: 30,
+    incrementalRendering: false,
+    concurrent: false,
+    alternateScreen: false,
+    ...getOptions(options),
+  };
+
+  const instance: Ink = getInstance(inkOptions.stdout, () => new Ink(inkOptions));
+  instance.render(node);
+
+  return {
+    rerender: instance.render.bind(instance),
+    unmount() {
+      instance.unmount();
+    },
+    waitUntilExit: instance.waitUntilExit.bind(instance),
+    waitUntilRenderFlush: instance.waitUntilRenderFlush.bind(instance),
+    cleanup() {
+      instance.unmount();
+    },
+    clear: instance.clear.bind(instance),
+  };
+};
+
+const getOptions = (stdout: Writable | RenderOptions | undefined = {}): RenderOptions => {
+  if (stdout instanceof Stream) {
+    return {
+      stdout,
+      stdin: process.stdin,
+    };
+  }
+
+  return stdout;
+};
+
+const getInstance = (stdout: NodeJS.WritableStream, createInstance: () => Ink): Ink => {
+  const instance = instances.get(stdout);
+
+  if (instance === undefined) {
+    const newInstance = createInstance();
+    instances.set(stdout, newInstance);
+    return newInstance;
+  }
+
+  // Ink keeps one live renderer per stdout. Reusing the same stream without
+  // unmounting is unsupported, but return the existing instance so we don't
+  // create two renderers that compete for the same output. Write the warning
+  // directly to native stderr so an existing alternate-screen renderer cannot
+  // swallow it via patchConsole.
+  process.stderr.write(
+    "Warning: render() was called again for the same stdout before the previous Ink instance was unmounted. Reusing stdout across multiple render() calls is unsupported. Call unmount() first.\n",
+  );
+
+  return instance;
+};

package/src/renderer.ts

@@ -0,0 +1,73 @@
+import { type DOMElement } from "./dom.ts";
+import { Output } from "./output.ts";
+import { renderNodeToOutput, renderNodeToScreenReaderOutput } from "./render-node-to-output.ts";
+
+type Result = {
+  output: string;
+  outputHeight: number;
+  staticOutput: string;
+};
+
+export const renderer = (node: DOMElement, isScreenReaderEnabled: boolean): Result => {
+  if (node.yogaNode) {
+    if (isScreenReaderEnabled) {
+      const output = renderNodeToScreenReaderOutput(node, {
+        skipStaticElements: true,
+      });
+
+      const outputHeight = output === "" ? 0 : output.split("\n").length;
+
+      let staticOutput = "";
+
+      if (node.staticNode) {
+        staticOutput = renderNodeToScreenReaderOutput(node.staticNode, {
+          skipStaticElements: false,
+        });
+      }
+
+      return {
+        output,
+        outputHeight,
+        staticOutput: staticOutput ? `${staticOutput}\n` : "",
+      };
+    }
+
+    const output = new Output({
+      width: node.yogaNode.getComputedWidth(),
+      height: node.yogaNode.getComputedHeight(),
+    });
+
+    renderNodeToOutput(node, output, {
+      skipStaticElements: true,
+    });
+
+    let staticOutput;
+
+    if (node.staticNode?.yogaNode) {
+      staticOutput = new Output({
+        width: node.staticNode.yogaNode.getComputedWidth(),
+        height: node.staticNode.yogaNode.getComputedHeight(),
+      });
+
+      renderNodeToOutput(node.staticNode, staticOutput, {
+        skipStaticElements: false,
+      });
+    }
+
+    const { output: generatedOutput, height: outputHeight } = output.get();
+
+    return {
+      output: generatedOutput,
+      outputHeight,
+      // Newline at the end is needed, because static output doesn't have one, so
+      // interactive output will override last line of static output
+      staticOutput: staticOutput ? `${staticOutput.get().output}\n` : "",
+    };
+  }
+
+  return {
+    output: "",
+    outputHeight: 0,
+    staticOutput: "",
+  };
+};

package/src/sanitize-ansi.ts

@@ -0,0 +1,33 @@
+import { hasAnsiControlCharacters, tokenizeAnsi } from "./ansi-tokenizer.ts";
+
+const sgrParametersRegex = /^[\d:;]*$/;
+
+// Strip ANSI escape sequences that would conflict with Ink's layout.
+// Preserved: SGR sequences (colors, bold, etc. - end with 'm') and
+// OSC sequences (hyperlinks, etc. - ESC ] or C1 OSC).
+// Stripped: cursor movement, screen clearing, and other control sequences.
+export const sanitizeAnsi = (text: string): string => {
+  if (!hasAnsiControlCharacters(text)) {
+    return text;
+  }
+
+  let output = "";
+
+  for (const token of tokenizeAnsi(text)) {
+    if (token.type === "text" || token.type === "osc") {
+      output += token.value;
+      continue;
+    }
+
+    if (
+      token.type === "csi" &&
+      token.finalCharacter === "m" &&
+      token.intermediateString === "" &&
+      sgrParametersRegex.test(token.parameterString)
+    ) {
+      output += token.value;
+    }
+  }
+
+  return output;
+};