@alchemy.run/sigil 0.0.0-alpha.4 → 0.0.0-alpha.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy.run/sigil",
-  "version": "0.0.0-alpha.4",
+  "version": "0.0.0-alpha.6",
   "description": "React for CLIs. A self-contained fork of Ink with an integrated TypeScript Yoga layout engine.",
   "keywords": [
     "cli",
@@ -37,25 +37,44 @@
   },
   "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,15 +85,25 @@
     "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",
+    "@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",
     "zigpty": "^0.2.1"
@@ -99,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,3 +1,5 @@
+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.
@@ -17,16 +19,16 @@ import {
   type ModifierName,
 } from "#/ansi/sgr.ts";
 import {
-  supportsColor as supportsColorDetection,
+  createSupportsColor,
   type ColorInfo,
   type ColorSupportLevel,
-} from "#/ansi/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;

package/src/ansi/escapes.ts

@@ -58,6 +58,17 @@ 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";
@@ -93,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

@@ -4,11 +4,13 @@
 
 // Styling
 export { chalk } from "#/ansi/chalk.ts";
-export { supportsColor } from "#/ansi/supports-color.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 * from "#/ansi/escapes.ts";
+export * from "#/ansi/osc.ts";
 export { cliCursor } from "#/ansi/cursor.ts";
 
 // Measurement

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/tokenize.ts

@@ -8,6 +8,7 @@ import { isFullwidthGrapheme } from "#/ansi/east-asian-width.ts";
 // `src/ansi-tokenizer.ts` (also behind sanitize-ansi), and grapheme widths
 // come from `east-asian-width.ts` — one grammar, one width table.
 import { BEL, C1_ST, ESC } from "#/ansi/escapes.ts";
+import { graphemes } from "#/ansi/graphemes.ts";
 import { codes as sgrCodes, foreground, background, styles } from "#/ansi/sgr.ts";
 
 // Single-character introducer suffixes (`ESC [` = CSI, `ESC ]` = OSC).
@@ -119,8 +120,6 @@ export function isIntensityCode(code: AnsiCode): boolean {
   return code.code === styles.bold.open || code.code === styles.dim.open;
 }
 
-const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
-
 /**
 Splits compound SGR sequences like `\u001B[1;3;31m` into individual components.
 */
@@ -139,7 +138,7 @@ function splitCompoundSgrSequences(code: string): string[] {
   for (let index = 0; index < codeParts.length; index++) {
     const rawCode = codeParts[index]!;
     // Keep 8-bit and 24-bit color codes (containing multiple ";") together
-    if (rawCode === "38" || rawCode === "48") {
+    if (rawCode === "38" || rawCode === "48" || rawCode === "58") {
       if (index + 2 < codeParts.length && codeParts[index + 1] === "5") {
         // 8-bit color, followed by another number
         result.push(codeParts.slice(index, index + 3).join(";"));
@@ -171,7 +170,7 @@ export function tokenize(string: string, endChar = Number.POSITIVE_INFINITY): To
 
   outer: for (const ansiToken of tokenizeAnsi(string)) {
     if (ansiToken.type === "text") {
-      for (const { segment } of segmenter.segment(ansiToken.value)) {
+      for (const segment of graphemes(ansiToken.value)) {
         const fullWidth = isFullwidthGrapheme(segment, segment.codePointAt(0)!);
         result.push({
           type: "char",

package/src/capabilities/color-policy.ts

@@ -0,0 +1,34 @@
+import type { ColorSupportLevel } from "#/capabilities/detect.ts";
+import { colorProfileFromLevel, type ColorProfile } from "#/screen/color-profile.ts";
+
+/** A user-selected output policy. `auto` follows the target stream. */
+export type ColorPolicy = "auto" | ColorProfile;
+
+/** The three distinct inputs and result of terminal color negotiation. */
+export type ColorState = {
+  /** The stream/terminal fact after environment and query detection. */
+  readonly detected: ColorProfile;
+  /** The application's policy for this render instance. */
+  readonly policy: ColorPolicy;
+  /** The profile the serializer must actually emit. */
+  readonly effective: ColorProfile;
+};
+
+export function resolveColorProfile(
+  detectedLevel: ColorSupportLevel,
+  policy: ColorPolicy = "auto",
+): ColorProfile {
+  return policy === "auto" ? colorProfileFromLevel(detectedLevel) : policy;
+}
+
+export function colorState(
+  capabilities: { readonly color: { readonly level: ColorSupportLevel } },
+  policy: ColorPolicy = "auto",
+): ColorState {
+  const detected = colorProfileFromLevel(capabilities.color.level);
+  return {
+    detected,
+    policy,
+    effective: policy === "auto" ? detected : policy,
+  };
+}