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

package/src/components/Text.tsx

@@ -1,12 +1,11 @@
 /** @jsxImportSource react */
 import { useContext, type ReactNode } from "react";
 
-import { chalk, type ForegroundColorName } from "#/ansi/chalk.ts";
-import { colorize } from "#/colorize.ts";
+import type { Paint } from "#/color/paint.ts";
 import { accessibilityContext } from "#/components/AccessibilityContext.ts";
-import { backgroundContext } from "#/components/BackgroundContext.ts";
+import { cellAttributes } from "#/screen/cell.ts";
+import { parseSemanticColor } from "#/semantic-text-style.ts";
 import { type Styles } from "#/styles.ts";
-import { type LiteralUnion } from "#/types.ts";
 
 export type Props = {
   /**
@@ -22,12 +21,12 @@ export type Props = {
   /**
 	Change text color. Ink uses Chalk under the hood, so all its functionality is supported.
 	*/
-  readonly color?: LiteralUnion<ForegroundColorName, string>;
+  readonly color?: Paint;
 
   /**
 	Same as `color`, but for the background.
 	*/
-  readonly backgroundColor?: LiteralUnion<ForegroundColorName, string>;
+  readonly backgroundColor?: Paint;
 
   /**
 	Dim the color (make it less bright).
@@ -60,7 +59,7 @@ export type Props = {
   readonly inverse?: boolean;
 
   /**
-	This property tells Ink to wrap or truncate text if its width is larger than the container. If `wrap` is passed (the default), Ink will wrap text and split it into multiple lines. If `hard` is passed, Ink will fill each line to the full column width, breaking words as necessary. If `truncate-*` is passed, Ink will truncate text instead, resulting in one line of text with the rest cut off.
+	This property tells Ink to wrap or truncate text if its width is larger than the container. If `wrap` is passed (the default), Ink will wrap text and split it into multiple lines. If `hard` is passed, Ink will fill each line to the full column width, breaking words as necessary. If `truncate-*` is passed, Ink will truncate text instead, resulting in one line of text with the rest cut off. If `none` is passed, the text is neither wrapped nor truncated — it overflows the container (and the screen's nominal width), which is intended for log lines committed to scrollback (e.g. inside `<Static>`), not for live regions.
 	*/
   readonly wrap?: Styles["textWrap"];
 
@@ -85,49 +84,27 @@ export function Text({
   "aria-hidden": ariaHidden = false,
 }: Props) {
   const { isScreenReaderEnabled } = useContext(accessibilityContext);
-  const inheritedBackgroundColor = useContext(backgroundContext);
   const childrenOrAriaLabel = isScreenReaderEnabled && ariaLabel ? ariaLabel : children;
 
   if (childrenOrAriaLabel === undefined || childrenOrAriaLabel === null) {
     return null;
   }
 
-  const transform = (text: string): string => {
-    if (dimColor) {
-      text = chalk.dim(text);
-    }
-
-    if (color) {
-      text = colorize(text, color, "foreground");
-    }
-
-    // Use explicit backgroundColor if provided, otherwise use inherited from parent Box
-    const effectiveBackgroundColor = backgroundColor ?? inheritedBackgroundColor;
-    if (effectiveBackgroundColor) {
-      text = colorize(text, effectiveBackgroundColor, "background");
-    }
-
-    if (bold) {
-      text = chalk.bold(text);
-    }
-
-    if (italic) {
-      text = chalk.italic(text);
-    }
-
-    if (underline) {
-      text = chalk.underline(text);
-    }
-
-    if (strikethrough) {
-      text = chalk.strikethrough(text);
-    }
-
-    if (inverse) {
-      text = chalk.inverse(text);
-    }
-
-    return text;
+  const foreground = typeof color === "object" ? color : parseSemanticColor(color);
+  const background =
+    typeof backgroundColor === "object" ? backgroundColor : parseSemanticColor(backgroundColor);
+  const semanticStyle = {
+    ...(foreground ? { foreground } : {}),
+    ...(background ? { background } : {}),
+    ...(color === "" ? { resetForeground: true } : {}),
+    ...(backgroundColor === "" ? { resetBackground: true } : {}),
+    ...(underline ? { underline: "single" as const } : {}),
+    attributes:
+      (dimColor ? cellAttributes.faint : 0) +
+      (bold ? cellAttributes.bold : 0) +
+      (italic ? cellAttributes.italic : 0) +
+      (strikethrough ? cellAttributes.strikethrough : 0) +
+      (inverse ? cellAttributes.inverse : 0),
   };
 
   if (isScreenReaderEnabled && ariaHidden) {
@@ -137,7 +114,7 @@ export function Text({
   return (
     <ink-text
       style={{ flexGrow: 0, flexShrink: 1, flexDirection: "row", textWrap: wrap }}
-      internal_transform={transform}
+      internal_textStyle={semanticStyle}
     >
       {childrenOrAriaLabel}
     </ink-text>

package/src/components/Transform.tsx

@@ -10,7 +10,7 @@ export type Props = {
   readonly accessibilityLabel?: string;
 
   /**
-	Function that transforms children output. It accepts children and must return transformed children as well. Note that when children use `<Text>` styling props (e.g. `color`, `bold`), the string will contain ANSI escape codes.
+	Compatibility function that transforms the ANSI serialization of this subtree.
 	*/
   readonly transform: (children: string, index: number) => string;
 

package/src/dom.ts

@@ -1,7 +1,8 @@
 import { measureText } from "#/measure-text.ts";
-import { type OutputTransformer } from "#/render-node-to-output.ts";
+import type { SemanticTextStyle } from "#/semantic-text-style.ts";
 import { squashTextNodes } from "#/squash-text-nodes.ts";
 import { type Styles } from "#/styles.ts";
+import { type AnsiTransformer } from "#/transform-adapter.ts";
 import { wrapText } from "#/wrap-text.ts";
 import { Yoga, type Node as YogaNode } from "#/yoga/index.ts";
 
@@ -24,7 +25,9 @@ export type DOMElement = {
   nodeName: ElementNames;
   attributes: Record<string, DOMNodeAttribute>;
   childNodes: DOMNode[];
-  internal_transform?: OutputTransformer;
+  internal_ansi?: boolean;
+  internal_transform?: AnsiTransformer;
+  internal_textStyle?: SemanticTextStyle;
 
   internal_accessibility?: {
     role?:
@@ -240,6 +243,12 @@ const measureTextNode = function (node: DOMNode, width: number): { width: number
   }
 
   const textWrap = node.style?.textWrap ?? "wrap";
+
+  // `none` keeps the intrinsic dimensions and overflows the container.
+  if (textWrap === "none") {
+    return dimensions;
+  }
+
   const wrappedText = wrapText(text, width, textWrap);
 
   return measureText(wrappedText);

package/src/global.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode, type Key, type Ref } from "react";
 
 import { type DOMElement } from "#/dom.ts";
+import type { SemanticTextStyle } from "#/semantic-text-style.ts";
 import { type Styles } from "#/styles.ts";
 
 declare module "react" {
@@ -29,7 +30,9 @@ declare namespace Ink {
     style?: Styles;
 
     // eslint-disable-next-line @typescript-eslint/naming-convention
+    internal_ansi?: boolean;
     internal_transform?: (children: string, index: number) => string;
+    internal_textStyle?: SemanticTextStyle;
     internal_accessibility?: DOMElement["internal_accessibility"];
   };
 }

package/src/hooks/use-capabilities.ts

@@ -0,0 +1,73 @@
+import { useEffect, useEffectEvent, useSyncExternalStore } from "react";
+
+import { type Capabilities } from "#/capabilities/detect.ts";
+import { getCapabilities } from "#/capabilities/store.ts";
+import { useStdinContext } from "#/hooks/use-stdin.ts";
+import { useStdout } from "#/hooks/use-stdout.ts";
+
+/**
+Returns everything knowable about the terminal: size, identity, platform,
+color depth, theme, and feature support.
+
+A thin wrapper over the framework-free capabilities store (`getCapabilities`):
+environment-derived facts are available immediately; facts only the terminal
+itself can answer fill in after a lazy one-time query, and re-mounting
+consumers refreshes the dynamic facts (theme colors, pixel geometry).
+Re-renders on terminal resize and whenever query answers arrive.
+*/
+export const useCapabilities = (): Capabilities => {
+  const { stdout } = useStdout();
+  const { stdin } = useStdinContext();
+  const store = getCapabilities(stdin, stdout);
+
+  const capabilities = useSyncExternalStore(store.subscribe, () => store.current);
+
+  useEffect(() => {
+    void store.query();
+  }, [store]);
+
+  return capabilities;
+};
+
+/**
+Calls `onChange` whenever the terminal changes: resizes (including in-band
+pixel geometry), color scheme switches, window focus, and query answers
+arriving. The React wrapper over `capabilities.subscribe()` for side effects —
+for rendering, use `useCapabilities` instead.
+
+The callback always sees the latest render's closure and changing it does not
+resubscribe. Both the new and previous snapshot are passed, so handlers can
+react to the specific change:
+
+```tsx
+useCapabilitiesChange((next, previous) => {
+  if (next.theme.appearance !== previous.theme.appearance) {
+    // re-theme
+  }
+});
+```
+*/
+export const useCapabilitiesChange = (
+  onChange: (capabilities: Capabilities, previous: Capabilities) => void,
+): void => {
+  const { stdout } = useStdout();
+  const { stdin } = useStdinContext();
+  const store = getCapabilities(stdin, stdout);
+
+  const handleChange = useEffectEvent(onChange);
+
+  useEffect(() => {
+    let previous = store.current;
+    const unsubscribe = store.subscribe((next) => {
+      const before = previous;
+      previous = next;
+      handleChange(next, before);
+    });
+
+    // Make sure the terminal has been asked — push report modes only turn
+    // on once the query has revealed support for them.
+    void store.query();
+
+    return unsubscribe;
+  }, [store]);
+};

package/src/hooks/use-cursor.ts

@@ -1,7 +1,7 @@
 import { useContext, useRef, useCallback, useInsertionEffect } from "react";
 
 import { CursorContext } from "#/components/CursorContext.ts";
-import { type CursorPosition } from "#/log-update.ts";
+import { type CursorPosition } from "#/cursor-position.ts";
 
 /**
 A React hook that returns methods to control the terminal cursor position.
@@ -18,7 +18,7 @@ export const useCursor = () => {
     positionRef.current = position;
   }, []);
 
-  // Propagate cursor position to log-update only during commit phase.
+  // Propagate cursor position to the terminal presenter only during commit.
   // useInsertionEffect runs before resetAfterCommit (which triggers onRender),
   // and does NOT run for abandoned concurrent renders (e.g. suspended components).
   // This prevents cursor state from leaking across render boundaries.

package/src/hooks/use-terminal-osc.ts

@@ -0,0 +1,59 @@
+import { useCallback, useContext, useEffect, useRef } from "react";
+
+import type { ClipboardSelection, TerminalProgressState } from "#/ansi/osc.ts";
+import { TerminalOscContext } from "#/components/TerminalOscContext.ts";
+
+export type ProgressOptions = {
+  readonly state: TerminalProgressState;
+  readonly value?: number;
+};
+
+export const useProgress = ({ state, value }: ProgressOptions): void => {
+  const terminal = useContext(TerminalOscContext);
+  const owner = useRef<symbol>(undefined);
+  owner.current ??= Symbol("terminal-progress");
+
+  useEffect(() => {
+    terminal.publishProgress(owner.current!, state, value);
+  }, [state, terminal, value]);
+
+  useEffect(() => {
+    return () => {
+      terminal.publishProgress(owner.current!, "inactive");
+    };
+  }, [terminal]);
+};
+
+export const useClipboard = (): ((text: string, selection?: ClipboardSelection) => void) => {
+  const terminal = useContext(TerminalOscContext);
+  return useCallback((text, selection) => terminal.copyToClipboard(text, selection), [terminal]);
+};
+
+export const useTitle = (title?: string): void => {
+  const terminal = useContext(TerminalOscContext);
+  const owner = useRef<symbol>(undefined);
+  owner.current ??= Symbol("terminal-title");
+  useEffect(() => {
+    terminal.publishTitle(owner.current!, title);
+  }, [terminal, title]);
+  useEffect(() => () => terminal.publishTitle(owner.current!, undefined), [terminal]);
+};
+
+export const useWorkingDirectory = (directory: URL | string): void => {
+  const terminal = useContext(TerminalOscContext);
+  useEffect(() => {
+    terminal.setWorkingDirectory(directory);
+  }, [directory, terminal]);
+};
+
+export const useNotification = (): ((title: string) => void) => {
+  const terminal = useContext(TerminalOscContext);
+  return useCallback((title) => terminal.notify(title), [terminal]);
+};
+
+export const usePointerShape = (shape: string): void => {
+  const terminal = useContext(TerminalOscContext);
+  useEffect(() => {
+    terminal.setPointerShape(shape);
+  }, [shape, terminal]);
+};

package/src/index.ts

@@ -7,6 +7,8 @@ export type { Props as BoxProps } from "#/components/Box.tsx";
 export { Box } from "#/components/Box.tsx";
 export type { Props as TextProps } from "#/components/Text.tsx";
 export { Text } from "#/components/Text.tsx";
+export type { Props as AnsiTextProps } from "#/components/AnsiText.tsx";
+export { AnsiText } from "#/components/AnsiText.tsx";
 export type { Props as AppProps } from "#/components/AppContext.ts";
 export type { PublicProps as StdinProps } from "#/components/StdinContext.ts";
 export type { Props as StdoutProps } from "#/components/StdoutContext.ts";
@@ -15,9 +17,42 @@ export type { Props as StaticProps } from "#/components/Static.tsx";
 export { Static } from "#/components/Static.tsx";
 export type { Props as TransformProps } from "#/components/Transform.tsx";
 export { Transform } from "#/components/Transform.tsx";
+export type { Props as HyperlinkProps } from "#/components/Hyperlink.tsx";
+export { Hyperlink } from "#/components/Hyperlink.tsx";
 export type { Props as NewlineProps } from "#/components/Newline.tsx";
 export { Newline } from "#/components/Newline.tsx";
 export { Spacer } from "#/components/Spacer.tsx";
+// Keep the Ink-compatible root surface fixed. New terminal-core APIs live on
+// their focused subpaths rather than leaking through this entry point.
+export type {
+  Capabilities,
+  ColorInfo,
+  ColorSupport,
+  ColorSupportLevel,
+  Multiplexer,
+  PixelGeometry,
+  RgbColor,
+  TerminalAppearance,
+  TerminalIdentity,
+} from "#/capabilities/detect.ts";
+export {
+  createSupportsColor,
+  detectCapabilities,
+  detectColorLevel,
+  detectHyperlinkSupport,
+  detectTerminal,
+  detectUnicodeSupport,
+} from "#/capabilities/detect.ts";
+export type { PixelSize, TerminalQueryOptions, TerminalQueryResult } from "#/capabilities/query.ts";
+export {
+  applyTerminalQuery,
+  getTerminalQuery,
+  queryTerminal,
+  refreshTerminalQuery,
+} from "#/capabilities/query.ts";
+export type { CapabilitiesStore } from "#/capabilities/store.ts";
+export { capabilities, getCapabilities } from "#/capabilities/store.ts";
+export { useCapabilities, useCapabilitiesChange } from "#/hooks/use-capabilities.ts";
 export type { Key } from "#/hooks/use-input.ts";
 export { useInput } from "#/hooks/use-input.ts";
 export { usePaste } from "#/hooks/use-paste.ts";
@@ -32,11 +67,20 @@ export { useIsScreenReaderEnabled } from "#/hooks/use-is-screen-reader-enabled.t
 export { useCursor } from "#/hooks/use-cursor.ts";
 export type { AnimationResult } from "#/hooks/use-animation.ts";
 export { useAnimation } from "#/hooks/use-animation.ts";
+export type { ProgressOptions } from "#/hooks/use-terminal-osc.ts";
+export {
+  useClipboard,
+  useNotification,
+  usePointerShape,
+  useProgress,
+  useTitle,
+  useWorkingDirectory,
+} from "#/hooks/use-terminal-osc.ts";
 export type { WindowSize } from "#/hooks/use-window-size.ts";
 export { useWindowSize } from "#/hooks/use-window-size.ts";
 export type { BoxMetrics, UseBoxMetricsResult } from "#/hooks/use-box-metrics.ts";
 export { useBoxMetrics } from "#/hooks/use-box-metrics.ts";
-export type { CursorPosition } from "#/log-update.ts";
+export type { CursorPosition } from "#/cursor-position.ts";
 export { measureElement } from "#/measure-element.ts";
 export type { ElementMetrics } from "#/measure-element.ts";
 export type { DOMElement } from "#/dom.ts";