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

package/src/render-border.ts

@@ -0,0 +1,167 @@
+import { graphemes } from "#/ansi/graphemes.ts";
+import { stringWidth } from "#/ansi/string-width.ts";
+import type { Paint, PaintContext } from "#/color/paint.ts";
+import { samplePaint } from "#/color/sample.ts";
+import { type DOMNode } from "#/dom.ts";
+import { BOXES } from "#/glyphs.ts";
+import type { Canvas } from "#/screen/canvas.ts";
+import type { Rect } from "#/screen/geometry.ts";
+import { cellAttributes, createCell, type Cell } from "#/screen/index.ts";
+
+const stylePiece = (
+  segment: string,
+  x: number,
+  y: number,
+  bounds: Rect,
+  context: PaintContext,
+  fg?: Paint,
+  bg?: Paint,
+  dim?: boolean,
+): Cell[] => {
+  let column = x;
+  return [...graphemes(segment)].map((grapheme) => {
+    const foreground = fg ? samplePaint(fg, column, y, bounds, context) : undefined;
+    const background = bg ? samplePaint(bg, column, y, bounds, context) : undefined;
+    const width = Math.max(1, stringWidth(grapheme));
+    column += width;
+    return createCell(grapheme, width, {
+      ...(foreground ? { foreground } : {}),
+      ...(background ? { background } : {}),
+      underline: "none",
+      attributes: dim ? cellAttributes.faint : cellAttributes.none,
+    });
+  });
+};
+
+export const renderBorder = (x: number, y: number, node: DOMNode, output: Canvas): void => {
+  if (node.style.borderStyle) {
+    const width = node.yogaNode!.getComputedWidth();
+    const height = node.yogaNode!.getComputedHeight();
+    const bounds = { x, y, width, height };
+    const box =
+      typeof node.style.borderStyle === "string"
+        ? BOXES[node.style.borderStyle]
+        : node.style.borderStyle;
+
+    const topBorderColor = node.style.borderTopColor ?? node.style.borderColor;
+    const bottomBorderColor = node.style.borderBottomColor ?? node.style.borderColor;
+    const leftBorderColor = node.style.borderLeftColor ?? node.style.borderColor;
+    const rightBorderColor = node.style.borderRightColor ?? node.style.borderColor;
+
+    const topBorderBackgroundColor =
+      node.style.borderTopBackgroundColor ?? node.style.borderBackgroundColor;
+    const bottomBorderBackgroundColor =
+      node.style.borderBottomBackgroundColor ?? node.style.borderBackgroundColor;
+    const leftBorderBackgroundColor =
+      node.style.borderLeftBackgroundColor ?? node.style.borderBackgroundColor;
+    const rightBorderBackgroundColor =
+      node.style.borderRightBackgroundColor ?? node.style.borderBackgroundColor;
+
+    const dimTopBorderColor = node.style.borderTopDimColor ?? node.style.borderDimColor;
+
+    const dimBottomBorderColor = node.style.borderBottomDimColor ?? node.style.borderDimColor;
+
+    const dimLeftBorderColor = node.style.borderLeftDimColor ?? node.style.borderDimColor;
+
+    const dimRightBorderColor = node.style.borderRightDimColor ?? node.style.borderDimColor;
+
+    const showTopBorder = node.style.borderTop !== false;
+    const showBottomBorder = node.style.borderBottom !== false;
+    const showLeftBorder = node.style.borderLeft !== false;
+    const showRightBorder = node.style.borderRight !== false;
+
+    const contentWidth = width - (showLeftBorder ? 1 : 0) - (showRightBorder ? 1 : 0);
+
+    const topBorder = showTopBorder
+      ? (showLeftBorder ? box.topLeft : "") +
+        box.top.repeat(contentWidth) +
+        (showRightBorder ? box.topRight : "")
+      : undefined;
+
+    let verticalBorderHeight = height;
+
+    if (showTopBorder) {
+      verticalBorderHeight -= 1;
+    }
+
+    if (showBottomBorder) {
+      verticalBorderHeight -= 1;
+    }
+
+    const offsetY = showTopBorder ? 1 : 0;
+
+    const bottomBorder = showBottomBorder
+      ? (showLeftBorder ? box.bottomLeft : "") +
+        box.bottom.repeat(contentWidth) +
+        (showRightBorder ? box.bottomRight : "")
+      : undefined;
+
+    if (topBorder) {
+      output.writeCells(x, y, [
+        stylePiece(
+          topBorder,
+          x,
+          y,
+          bounds,
+          output.paintContext,
+          topBorderColor,
+          topBorderBackgroundColor,
+          dimTopBorderColor,
+        ),
+      ]);
+    }
+
+    if (showLeftBorder) {
+      output.writeCells(
+        x,
+        y + offsetY,
+        Array.from({ length: verticalBorderHeight }, (_, row) =>
+          stylePiece(
+            box.left,
+            x,
+            y + offsetY + row,
+            bounds,
+            output.paintContext,
+            leftBorderColor,
+            leftBorderBackgroundColor,
+            dimLeftBorderColor,
+          ),
+        ),
+      );
+    }
+
+    if (showRightBorder) {
+      output.writeCells(
+        x + width - 1,
+        y + offsetY,
+        Array.from({ length: verticalBorderHeight }, (_, row) =>
+          stylePiece(
+            box.right,
+            x + width - 1,
+            y + offsetY + row,
+            bounds,
+            output.paintContext,
+            rightBorderColor,
+            rightBorderBackgroundColor,
+            dimRightBorderColor,
+          ),
+        ),
+      );
+    }
+
+    if (bottomBorder) {
+      output.writeCells(x, y + height - 1, [
+        stylePiece(
+          bottomBorder,
+          x,
+          y + height - 1,
+          bounds,
+          output.paintContext,
+          bottomBorderColor,
+          bottomBorderBackgroundColor,
+          dimBottomBorderColor,
+        ),
+      ]);
+    }
+  }
+};

package/src/render-frame.ts

@@ -0,0 +1,83 @@
+import type { PaintContext } from "#/color/paint.ts";
+import { type DOMElement } from "#/dom.ts";
+import { paintTree, renderAccessibleText } from "#/paint-tree.ts";
+import { Canvas } from "#/screen/canvas.ts";
+import { type ColorProfile } from "#/screen/index.ts";
+import type { Screen } from "#/screen/screen.ts";
+
+type Result = {
+  screen?: Screen;
+  staticScreen?: Screen;
+  accessibleText?: string;
+  staticAccessibleText?: string;
+};
+
+type RendererOptions = {
+  colorProfile?: ColorProfile;
+  paintContext?: PaintContext;
+};
+
+const renderDimension = (value: number): number =>
+  Number.isFinite(value) ? Math.max(0, Math.ceil(value)) : 0;
+
+export const renderFrame = (
+  node: DOMElement,
+  isScreenReaderEnabled: boolean,
+  options: RendererOptions = {},
+): Result => {
+  if (node.yogaNode) {
+    if (isScreenReaderEnabled) {
+      const output = renderAccessibleText(node, {
+        skipStaticElements: true,
+      });
+
+      let staticOutput = "";
+
+      if (node.staticNode) {
+        staticOutput = renderAccessibleText(node.staticNode, {
+          skipStaticElements: false,
+        });
+      }
+
+      return {
+        accessibleText: output,
+        staticAccessibleText: staticOutput,
+      };
+    }
+
+    const output = new Canvas({
+      width: renderDimension(node.yogaNode.getComputedWidth()),
+      height: renderDimension(node.yogaNode.getComputedHeight()),
+      colorProfile: options.colorProfile,
+      paintContext: options.paintContext,
+    });
+
+    paintTree(node, output, {
+      skipStaticElements: true,
+    });
+
+    let staticOutput;
+
+    if (node.staticNode?.yogaNode) {
+      staticOutput = new Canvas({
+        width: renderDimension(node.staticNode.yogaNode.getComputedWidth()),
+        height: renderDimension(node.staticNode.yogaNode.getComputedHeight()),
+        colorProfile: options.colorProfile,
+        paintContext: options.paintContext,
+      });
+
+      paintTree(node.staticNode, staticOutput, {
+        skipStaticElements: false,
+      });
+    }
+
+    return {
+      screen: output.finish(),
+      ...(staticOutput ? { staticScreen: staticOutput.finish() } : {}),
+    };
+  }
+
+  return {
+    accessibleText: "",
+  };
+};

package/src/render-to-string.ts

@@ -0,0 +1,146 @@
+import type { ReactNode } from "react";
+import { LegacyRoot } from "react-reconciler/constants.js";
+
+import { detectColorLevel } from "#/capabilities/detect.ts";
+import { createNode, type DOMElement } from "#/dom.ts";
+import { reconciler } from "#/reconciler.ts";
+import { renderFrame } from "#/render-frame.ts";
+import { colorProfileFromLevel, type ColorProfile } from "#/screen/index.ts";
+import { serializeScreen } from "#/screen/serialize.ts";
+import { Yoga } from "#/yoga/index.ts";
+
+export type RenderToStringOptions = {
+  /**
+	Width of the virtual terminal in columns.
+
+	@default 80
+	*/
+  columns?: number;
+
+  /**
+	Color profile used for deterministic serialization. By default this retains
+	the process color level for Ink compatibility.
+	*/
+  colorProfile?: ColorProfile;
+};
+
+/**
+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;
+  const colorProfile = options?.colorProfile ?? colorProfileFromLevel(detectColorLevel());
+
+  // 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 { staticScreen } = renderFrame(rootNode, false, { colorProfile });
+    const staticOutput = staticScreen
+      ? `${serializeScreen(staticScreen, { colorProfile, styles: colorProfile !== "none" })}\n`
+      : "";
+    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 { screen } = renderFrame(rootNode, false, { colorProfile });
+  const output = screen
+    ? serializeScreen(screen, { colorProfile, styles: colorProfile !== "none" })
+    : "";
+
+  // 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));
+  }
+
+  // Static terminal output ends with a newline 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,284 @@
+import { Stream, type Writable } from "node:stream";
+
+import type { ReactNode } from "react";
+
+import type { ClipboardSelection, TerminalProgressState } from "#/ansi/osc.ts";
+import { createInk, type Ink, type Options as InkOptions, type RenderMetrics } from "#/ink.tsx";
+import { instances } from "#/instances.ts";
+import { type KittyKeyboardOptions } from "#/kitty-keyboard.ts";
+import { type ColorProfile } from "#/screen/color-profile.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;
+
+  /**
+	Override the output color profile for this render instance. When omitted,
+	the profile follows the capabilities of `stdout` and capability upgrades
+	redraw the live frame. Static content already written to scrollback is not
+	replayed or recolored.
+	*/
+  colorProfile?: ColorProfile;
+
+  /**
+	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 (the `CI` environment variable) 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;
+
+  /** Copy text through the renderer-owned terminal session. */
+  copyToClipboard: (text: string, selection?: ClipboardSelection) => boolean;
+
+  /** Update terminal-native progress through the renderer-owned session. */
+  setProgress: (state: TerminalProgressState, value?: number) => boolean;
+};
+
+/**
+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,
+    concurrent: false,
+    alternateScreen: false,
+    ...getOptions(options),
+  };
+
+  const instance: Ink = getInstance(inkOptions.stdout, () => createInk(inkOptions));
+  instance.render(node);
+
+  return {
+    rerender: instance.render,
+    unmount() {
+      instance.unmount();
+    },
+    waitUntilExit: instance.waitUntilExit,
+    waitUntilRenderFlush: instance.waitUntilRenderFlush,
+    cleanup() {
+      instance.unmount();
+    },
+    clear: instance.clear,
+    copyToClipboard: instance.copyToClipboard,
+    setProgress: instance.setProgress,
+  };
+};
+
+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;
+};