@alchemy.run/sigil 0.0.0-alpha.3 → 0.0.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy.run/sigil",
-  "version": "0.0.0-alpha.3",
+  "version": "0.0.0-alpha.5",
   "description": "React for CLIs. A self-contained fork of Ink with an integrated TypeScript Yoga layout engine.",
   "keywords": [
     "cli",
@@ -33,29 +33,48 @@
   ],
   "type": "module",
   "imports": {
-    "#/": "./src"
+    "#/*": "./src/*"
   },
   "exports": {
     ".": {
-      "typescript": "./src/index.ts",
-      "bun": "./src/index.ts",
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
     "./ansi": {
-      "typescript": "./src/ansi/index.ts",
-      "bun": "./src/ansi/index.ts",
       "import": "./dist/ansi.js",
       "types": "./dist/ansi.d.ts",
       "default": "./dist/ansi.js"
     },
     "./yoga": {
-      "typescript": "./src/yoga/index.ts",
-      "bun": "./src/yoga/index.ts",
       "import": "./dist/yoga.js",
       "types": "./dist/yoga.d.ts",
       "default": "./dist/yoga.js"
+    },
+    "./router": {
+      "import": "./dist/router.js",
+      "types": "./dist/router.d.ts",
+      "default": "./dist/router.js"
+    },
+    "./capabilities": {
+      "import": "./dist/capabilities.js",
+      "types": "./dist/capabilities.d.ts",
+      "default": "./dist/capabilities.js"
+    },
+    "./color": {
+      "import": "./dist/color.js",
+      "types": "./dist/color.d.ts",
+      "default": "./dist/color.js"
+    },
+    "./screen": {
+      "import": "./dist/screen.js",
+      "types": "./dist/screen.d.ts",
+      "default": "./dist/screen.js"
+    },
+    "./terminal": {
+      "import": "./dist/terminal.js",
+      "types": "./dist/terminal.d.ts",
+      "default": "./dist/terminal.js"
     }
   },
   "publishConfig": {
@@ -66,26 +85,33 @@
     "scheduler": "^0.27.0"
   },
   "devDependencies": {
+    "@slopus/ghostty-wasm": "^1.3.6",
     "@types/node": "^25.5.2",
     "@types/react": "^19.2.18",
     "@types/react-reconciler": "^0.33.0",
     "@types/scheduler": "^0.26.0",
-    "@types/ws": "^8.18.1",
+    "@vitest/ui": "^4.1.11",
+    "@xterm/addon-clipboard": "^0.2.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-image": "^0.9.0",
+    "@xterm/addon-unicode11": "^0.9.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/addon-webgl": "^0.19.0",
+    "@xterm/headless": "^6.0.0",
+    "@xterm/xterm": "^6.0.0",
     "react": "^19.2.8",
     "react-devtools-core": "^7.0.1",
-    "react-router": "^8.3.0",
     "tsx": "^4.21.0",
     "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@^0.2.9",
     "vite-plus": "^0.2.9",
     "vitest": "4.1.11",
-    "ws": "^8.20.0",
     "zigpty": "^0.2.1"
   },
   "peerDependencies": {
     "@types/react": ">=19.2.0",
     "react": ">=19.2.0",
-    "react-devtools-core": ">=6.1.2",
-    "ws": ">=8.20.0"
+    "react-devtools-core": ">=6.1.2"
   },
   "peerDependenciesMeta": {
     "@types/react": {
@@ -93,9 +119,6 @@
     },
     "react-devtools-core": {
       "optional": true
-    },
-    "ws": {
-      "optional": true
     }
   },
   "engines": {
@@ -105,12 +128,15 @@
     "dev": "vp pack -w",
     "build": "vp pack",
     "test": "vp test",
+    "e2e": "vp test test/e2e.test.ts",
+    "explorer": "node --import=tsx scripts/explorer.ts",
     "lint": "vp lint",
     "format": "vp fmt .",
     "check": "vp check",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test/contracts/tsconfig.json",
     "inspect": "vpx react-devtools",
     "build:reference": "tsx scripts/build-reference.ts",
+    "bench:terminal": "tsx benchmark/terminal-core.tsx --check",
     "fuzz": "tsx test/yoga/fuzz/typescript.ts",
     "fuzz:differential": "vpr build:reference && tsx test/yoga/fuzz/differential.ts",
     "fuzz:loop": "vpr build:reference && tsx test/yoga/fuzz/loop.ts"

package/src/ansi/chalk.ts

@@ -1,7 +1,9 @@
+import { isatty } from "node:tty";
+
 // Terminal string styling with a chalk-compatible API for the styles Ink uses.
 // Ported from `chalk` (MIT, Sindre Sorhus) without the chaining builder —
 // Ink only ever applies one style per call.
-import { ESC } from "./escapes.ts";
+import { ESC } from "#/ansi/escapes.ts";
 import {
   background,
   backgroundColorNames,
@@ -15,18 +17,18 @@ import {
   type BackgroundColorName,
   type ForegroundColorName,
   type ModifierName,
-} from "./sgr.ts";
+} from "#/ansi/sgr.ts";
 import {
-  supportsColor as supportsColorDetection,
+  createSupportsColor,
   type ColorInfo,
   type ColorSupportLevel,
-} from "./supports-color.ts";
+} from "#/capabilities/detect.ts";
 
 export type { BackgroundColorName, ForegroundColorName, ModifierName };
 
 export type StyleFunction = (text: string) => string;
 
-const { stdout: stdoutColor } = supportsColorDetection;
+const stdoutColor = createSupportsColor({ isTTY: isatty(1) });
 
 // `level` → color model for hex/rgb downsampling
 const levelMapping = ["ansi", "ansi", "ansi256", "ansi16m"] as const;
@@ -38,50 +40,6 @@ const state = {
 
 // Replace every occurrence of `substring` with `substring + replacer`,
 // re-opening a style after a nested close code would have ended it.
-const stringReplaceAll = (string: string, substring: string, replacer: string): string => {
-  let index = string.indexOf(substring);
-  if (index === -1) {
-    return string;
-  }
-
-  const substringLength = substring.length;
-  let endIndex = 0;
-  let returnValue = "";
-  do {
-    returnValue += string.slice(endIndex, index) + substring + replacer;
-    endIndex = index + substringLength;
-    index = string.indexOf(substring, endIndex);
-  } while (index !== -1);
-
-  returnValue += string.slice(endIndex);
-  return returnValue;
-};
-
-// Close the style before every line break and reopen it after, to prevent
-// background bleed across lines (https://github.com/chalk/chalk/pull/92).
-const stringEncaseCRLFWithFirstIndex = (
-  string: string,
-  prefix: string,
-  postfix: string,
-  index: number,
-): string => {
-  let endIndex = 0;
-  let returnValue = "";
-  do {
-    const gotCR = string[index - 1] === "\r";
-    returnValue +=
-      string.slice(endIndex, gotCR ? index - 1 : index) +
-      prefix +
-      (gotCR ? "\r\n" : "\n") +
-      postfix;
-    endIndex = index + 1;
-    index = string.indexOf("\n", endIndex);
-  } while (index !== -1);
-
-  returnValue += string.slice(endIndex);
-  return returnValue;
-};
-
 const applyStyle = (open: string, close: string, text: string): string => {
   if (state.level <= 0 || !text) {
     return text;
@@ -92,12 +50,13 @@ const applyStyle = (open: string, close: string, text: string): string => {
   if (string.includes(ESC)) {
     // Re-open the style wherever the text already contains its close code,
     // otherwise only the part before that code would stay styled.
-    string = stringReplaceAll(string, close, open);
+    string = string.replaceAll(close, close + open);
   }
 
-  const lfIndex = string.indexOf("\n");
-  if (lfIndex !== -1) {
-    string = stringEncaseCRLFWithFirstIndex(string, close, open, lfIndex);
+  if (string.includes("\n")) {
+    // Close the style before every line break and reopen it after, to prevent
+    // background bleed across lines (https://github.com/chalk/chalk/pull/92).
+    string = string.replaceAll(/\r?\n/g, `${close}$&${open}`);
   }
 
   return open + string + close;

package/src/ansi/cursor.ts

@@ -1,10 +1,8 @@
+import { cursorHide, cursorShow } from "#/ansi/escapes.ts";
 // Derived from `cli-cursor` + `restore-cursor` (MIT, Sindre Sorhus),
 // collapsed into one module. Restores the cursor on process exit once
 // `hide()` has been called, like `restore-cursor` did.
-import process from "node:process";
-
-import { signalExit } from "../signal-exit.ts";
-import { cursorHide, cursorShow } from "./escapes.ts";
+import { signalExit } from "#/signal-exit.ts";
 
 type CursorStream = {
   isTTY?: boolean;

package/src/ansi/east-asian-width.ts

@@ -206,6 +206,50 @@ export function eastAsianWidth(
   return 1;
 }
 
+/**
+Grapheme-cluster width test shared by the tokenizer (slice/clip path): the
+base code point's East Asian Width, plus emoji presentation rules.
+*/
+export function isFullwidthGrapheme(grapheme: string, baseCodePoint: number): boolean {
+  if (isFullwidthCodePoint(baseCodePoint)) return true;
+  // Variation Selector 16 forces emoji presentation (2 columns wide)
+  if (grapheme.includes("\uFE0F")) return true;
+  // Regional indicator pairs form flag emoji (2 columns wide)
+  if (baseCodePoint >= 0x1f1e6 && baseCodePoint <= 0x1f1ff) return true;
+  return false;
+}
+
+/**
+Wide code points not covered by string-width's CJKT script regex or emoji
+regex — the fallback bucket of its block parser. A disjoint decomposition of
+the `wide` table above, kept alongside it so the width data lives in one
+module.
+*/
+export const isWideNotCJKTNotEmoji = (x: number): boolean => {
+  return (
+    x === 0x231b ||
+    x === 0x2329 ||
+    (x >= 0x2ff0 && x <= 0x2fff) ||
+    (x >= 0x3001 && x <= 0x303e) ||
+    (x >= 0x3099 && x <= 0x30ff) ||
+    (x >= 0x3105 && x <= 0x312f) ||
+    (x >= 0x3131 && x <= 0x318e) ||
+    (x >= 0x3190 && x <= 0x31e3) ||
+    (x >= 0x31ef && x <= 0x321e) ||
+    (x >= 0x3220 && x <= 0x3247) ||
+    (x >= 0x3250 && x <= 0x4dbf) ||
+    (x >= 0xfe10 && x <= 0xfe19) ||
+    (x >= 0xfe30 && x <= 0xfe52) ||
+    (x >= 0xfe54 && x <= 0xfe66) ||
+    (x >= 0xfe68 && x <= 0xfe6b) ||
+    (x >= 0x1f200 && x <= 0x1f202) ||
+    (x >= 0x1f210 && x <= 0x1f23b) ||
+    (x >= 0x1f240 && x <= 0x1f248) ||
+    (x >= 0x20000 && x <= 0x2fffd) ||
+    (x >= 0x30000 && x <= 0x3fffd)
+  );
+};
+
 export function isFullwidthCodePoint(codePoint: number): boolean {
   if (!Number.isInteger(codePoint)) {
     return false;

package/src/ansi/escapes.ts

@@ -1,7 +1,4 @@
-import os from "node:os";
 // Derived from `ansi-escapes` (MIT, Sindre Sorhus), reduced to the escapes Ink uses.
-import process from "node:process";
-
 // Control characters and sequence introducers. This module is the single
 // home for escape sequences: everything else imports these instead of
 // spelling out `\u001B[...` inline.
@@ -51,35 +48,27 @@ export const eraseLines = (count: number): string => {
   return clear;
 };
 
-// Windows 10 builds before 10586 don't support the `3J` escape.
-const isOldWindows = (): boolean => {
-  if (process.platform !== "win32") {
-    return false;
-  }
-
-  const parts = os.release().split(".");
-  const major = Number(parts[0]);
-  const build = Number(parts[2] ?? 0);
-
-  if (major < 10) {
-    return true;
-  }
-
-  return major === 10 && build < 10_586;
-};
-
-export const clearTerminal = isOldWindows()
-  ? `${eraseScreen}${CSI}0f`
-  : // 1. Erases the screen (only done in case `2` is not supported)
-    // 2. Erases the whole screen including scrollback buffer
-    // 3. Moves cursor to the top-left position
-    `${eraseScreen}${CSI}3J${CSI}H`;
+// 1. Erases the screen (only done in case `2` is not supported)
+// 2. Erases the whole screen including scrollback buffer
+// 3. Moves cursor to the top-left position
+export const clearTerminal = `${eraseScreen}${CSI}3J${CSI}H`;
 
 export const enterAlternativeScreen = CSI + "?1049h";
 export const exitAlternativeScreen = CSI + "?1049l";
 
 export const cursorShow = CSI + "?25h";
 export const cursorHide = CSI + "?25l";
+export type CursorShape = "block" | "underline" | "bar";
+export const cursorShape = (shape: CursorShape, blinking = true): string => {
+  const value = {
+    block: blinking ? 1 : 2,
+    underline: blinking ? 3 : 4,
+    bar: blinking ? 5 : 6,
+  }[shape];
+  return `${CSI}${value} q`;
+};
+export const cursorColor = (color: string): string => `${OSC}12;${color}${BEL}`;
+export const resetCursorColor = `${OSC}112${BEL}`;
 
 export const enableBracketedPaste = CSI + "?2004h";
 export const disableBracketedPaste = CSI + "?2004l";
@@ -115,6 +104,9 @@ export const ansiEscapes = {
   exitAlternativeScreen,
   cursorShow,
   cursorHide,
+  cursorShape,
+  cursorColor,
+  resetCursorColor,
   enableBracketedPaste,
   disableBracketedPaste,
   pasteStart,

package/src/ansi/graphemes.ts

@@ -0,0 +1,8 @@
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** The canonical grapheme segmentation service for measurement and rasterization. */
+export function* graphemes(text: string): Generator<string> {
+  for (const { segment } of segmenter.segment(text)) {
+    yield segment;
+  }
+}

package/src/ansi/hyperlink.ts

@@ -0,0 +1,44 @@
+// Standalone OSC 8 hyperlink builder with fallback — the string counterpart
+// to the <Hyperlink> component, for use outside the React renderer.
+import { link } from "#/ansi/escapes.ts";
+import { detectHyperlinkSupport } from "#/capabilities/detect.ts";
+
+type HyperlinkOptions = {
+  /**
+	When the terminal does not support OSC 8 hyperlinks, append the URL in
+	parentheses after the text so it stays reachable. Set to `false` to
+	return the text alone.
+
+	@default true
+	*/
+  fallback?: boolean;
+
+  /**
+	The stream the text will be written to, for support detection.
+
+	@default process.stdout
+	*/
+  stream?: { isTTY?: boolean };
+};
+
+/**
+Wraps text in a clickable OSC 8 hyperlink when the terminal supports it,
+falling back to `text (url)`.
+
+```ts
+import { hyperlink } from "@alchemy.run/sigil/ansi";
+
+console.log(hyperlink("Documentation", "https://example.com"));
+```
+*/
+export const hyperlink = (
+  text: string,
+  url: string,
+  { fallback = true, stream = process.stdout }: HyperlinkOptions = {},
+): string => {
+  if (detectHyperlinkSupport(stream)) {
+    return link(text, url);
+  }
+
+  return fallback ? `${text} (${url})` : text;
+};

package/src/ansi/index.ts

@@ -3,25 +3,25 @@
 // `@alchemy.run/sigil/ansi`.
 
 // Styling
-export { chalk } from "./chalk.ts";
-export { supportsColor } from "./supports-color.ts";
-export * from "./sgr.ts";
+export { chalk } from "#/ansi/chalk.ts";
+export { supportsColor } from "#/ansi/chalk.ts";
+export { hyperlink } from "#/ansi/hyperlink.ts";
+export * from "#/ansi/sgr.ts";
 
 // Escape sequences (raw building blocks + named sequences)
-export { ansiEscapes } from "./escapes.ts";
-export * from "./escapes.ts";
-export { cliCursor } from "./cursor.ts";
+export * from "#/ansi/escapes.ts";
+export * from "#/ansi/osc.ts";
+export { cliCursor } from "#/ansi/cursor.ts";
 
 // Measurement
-export { stringWidth } from "./string-width.ts";
-export { widestLine } from "./widest-line.ts";
-export * from "./east-asian-width.ts";
+export { stringWidth, widestLine } from "#/ansi/string-width.ts";
+export * from "#/ansi/east-asian-width.ts";
 
 // String manipulation
-export { stripAnsi, ansiRegex } from "./strip.ts";
-export { sliceAnsi } from "./slice.ts";
-export { cliTruncate as truncateAnsi } from "./truncate.ts";
-export { wrapAnsi } from "./wrap.ts";
+export { stripAnsi } from "#/ansi/strip.ts";
+export { sliceAnsi } from "#/ansi/slice.ts";
+export { cliTruncate as truncateAnsi } from "#/ansi/truncate.ts";
+export { wrapAnsi } from "#/ansi/wrap.ts";
 
 // Tokenizer: style-aware parsing and minimal re-emission
-export * from "./tokenize.ts";
+export * from "#/ansi/tokenize.ts";

package/src/ansi/osc.ts

@@ -0,0 +1,77 @@
+import { pathToFileURL } from "node:url";
+
+import { ESC, OSC, ST } from "#/ansi/escapes.ts";
+
+export type ClipboardSelection = "clipboard" | "primary" | "selection";
+export type TerminalProgressState = "inactive" | "normal" | "error" | "indeterminate" | "paused";
+
+const clipboardCode: Record<ClipboardSelection, string> = {
+  clipboard: "c",
+  primary: "p",
+  selection: "s",
+};
+
+const progressCode: Record<TerminalProgressState, number> = {
+  inactive: 0,
+  normal: 1,
+  error: 2,
+  indeterminate: 3,
+  paused: 4,
+};
+
+const field = (value: string): string => value.replace(/[\u0000-\u001F\u007F-\u009F]/g, "");
+
+const command = (code: number, payload: string): string => `${OSC}${code};${payload}${ST}`;
+
+/** Change the terminal window title (OSC 2). */
+export const setWindowTitle = (title: string): string => command(2, field(title));
+
+/** Announce the current directory as a file URI (OSC 7). */
+export const setWorkingDirectory = (directory: URL | string): string => {
+  const uri =
+    directory instanceof URL
+      ? directory
+      : directory.startsWith("file:")
+        ? new URL(directory)
+        : pathToFileURL(directory);
+  if (uri.protocol !== "file:") throw new Error("Terminal working directory must be a file URI");
+  return command(7, uri.href);
+};
+
+/** Show a desktop notification (OSC 9). */
+export const notify = (title: string): string => {
+  const safe = field(title);
+  return command(9, /^\d+;/.test(safe) ? ` ${safe}` : safe);
+};
+
+/** Change the terminal pointer shape (OSC 22; terminal support varies). */
+export const setPointerShape = (shape: string): string => command(22, field(shape));
+
+/** Write UTF-8 text to a terminal clipboard using OSC 52. */
+export const setClipboard = (text: string, selection: ClipboardSelection = "clipboard"): string =>
+  command(52, `${clipboardCode[selection]};${Buffer.from(text).toString("base64")}`);
+
+/** Request clipboard contents. The response is another OSC 52 sequence. */
+export const queryClipboard = (selection: ClipboardSelection = "clipboard"): string =>
+  command(52, `${clipboardCode[selection]};?`);
+
+/** Clear a terminal clipboard. */
+export const clearClipboard = (selection: ClipboardSelection = "clipboard"): string =>
+  command(52, `${clipboardCode[selection]};`);
+
+/** Report terminal-native progress using OSC 9;4. */
+export const setTerminalProgress = (state: TerminalProgressState, value?: number): string => {
+  const code = progressCode[state];
+  if (state === "inactive" || state === "indeterminate") {
+    return command(9, `4;${code}`);
+  }
+  if (value === undefined && (state === "error" || state === "paused")) {
+    return command(9, `4;${code}`);
+  }
+  const percentage = Math.max(0, Math.min(100, Math.round(value ?? 0)));
+  return command(9, `4;${code};${percentage}`);
+};
+
+/** Wrap a sequence for transport through tmux's DCS passthrough. */
+export const tmuxPassthrough = (sequence: string): string =>
+  `${ESC}Ptmux;${sequence.replaceAll(ESC, `${ESC}${ESC}`)}${ST}`;

package/src/ansi/sgr.ts

@@ -1,6 +1,6 @@
 // ANSI SGR style tables and color-space conversions.
 // Ported from `ansi-styles` (MIT, Sindre Sorhus).
-import { CSI } from "./escapes.ts";
+import { CSI } from "#/ansi/escapes.ts";
 
 const ANSI_BACKGROUND_OFFSET = 10;
 
@@ -173,10 +173,7 @@ export const hexToRgb = (hex: string): [number, number, number] => {
   let [colorString] = matches;
 
   if (colorString.length === 3) {
-    colorString = colorString
-      .split("")
-      .map((character) => character + character)
-      .join("");
+    colorString = colorString.replaceAll(/./g, "$&$&");
   }
 
   const integer = Number.parseInt(colorString, 16);

package/src/ansi/slice.ts

@@ -8,7 +8,7 @@ import {
   styledCharsToString,
   tokenize,
   type StyledChar,
-} from "./tokenize.ts";
+} from "#/ansi/tokenize.ts";
 
 export function sliceAnsi(string: string, start: number, end?: number): string {
   const sliceEnd = end ?? Number.POSITIVE_INFINITY;