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

package/src/{boxes.ts → glyphs.ts}

@@ -1,20 +1,5 @@
 // Derived from `cli-boxes` (MIT, Sindre Sorhus).
-
-/**
-Style of the box border.
-*/
-export type BoxStyle = {
-  readonly topLeft: string;
-  readonly top: string;
-  readonly topRight: string;
-  readonly right: string;
-  readonly bottomRight: string;
-  readonly bottom: string;
-  readonly bottomLeft: string;
-  readonly left: string;
-};
-
-export const boxes = {
+export const BOXES = {
   single: {
     topLeft: "┌",
     top: "─",
@@ -95,6 +80,20 @@ export const boxes = {
     bottomLeft: "↗",
     left: "→",
   },
-} as const satisfies Record<string, BoxStyle>;
+} as const;
 
-export type Boxes = typeof boxes;
+export type BoxStyle = keyof typeof BOXES;
+
+/**
+The set of glyphs making up a box border, for custom `borderStyle` objects.
+*/
+export type BoxGlyphs = {
+  readonly topLeft: string;
+  readonly top: string;
+  readonly topRight: string;
+  readonly right: string;
+  readonly bottomRight: string;
+  readonly bottom: string;
+  readonly bottomLeft: string;
+  readonly left: string;
+};

package/src/hooks/use-animation.ts

@@ -1,6 +1,6 @@
 import { useState, useLayoutEffect, useRef, useCallback, useContext } from "react";
 
-import { animationContext as AnimationContext } from "../components/AnimationContext.ts";
+import { animationContext as AnimationContext } from "#/components/AnimationContext.ts";
 
 const defaultAnimationInterval = 100;
 const maximumTimerInterval = 2_147_483_647;

package/src/hooks/use-app.ts

@@ -1,6 +1,6 @@
 import { useContext } from "react";
 
-import { AppContext } from "../components/AppContext.ts";
+import { AppContext } from "#/components/AppContext.ts";
 
 /**
 A React hook that returns app lifecycle methods like `exit()` and `waitUntilRenderFlush()`.

package/src/hooks/use-box-metrics.ts

@@ -1,6 +1,6 @@
 import { type RefObject, useState, useEffect, useCallback, useMemo } from "react";
 
-import { type DOMElement, addLayoutListener } from "../dom.ts";
+import { type DOMElement, addLayoutListener } from "#/dom.ts";
 
 // Yoga's `right`/`bottom` are omitted: always `0` for flow layout and unintuitive for absolute positioning.
 /**

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 { CursorContext } from "#/components/CursorContext.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-focus-manager.ts

@@ -1,6 +1,6 @@
 import { useContext } from "react";
 
-import { FocusContext, type Props } from "../components/FocusContext.ts";
+import { FocusContext, type Props } from "#/components/FocusContext.ts";
 
 type Output = {
   /**

package/src/hooks/use-focus.ts

@@ -1,7 +1,7 @@
-import { useEffect, useContext, useMemo } from "react";
+import { useEffect, useContext, useId } from "react";
 
-import { FocusContext } from "../components/FocusContext.ts";
-import { useStdin } from "./use-stdin.ts";
+import { FocusContext } from "#/components/FocusContext.ts";
+import { useStdin } from "#/hooks/use-stdin.ts";
 
 type Input = {
   /**
@@ -44,9 +44,8 @@ export const useFocus = ({
   const { isRawModeSupported, setRawMode } = useStdin();
   const { activeId, add, remove, activate, deactivate, focus } = useContext(FocusContext);
 
-  const id = useMemo(() => {
-    return customId ?? Math.random().toString().slice(2, 7);
-  }, [customId]);
+  const autoId = useId();
+  const id = customId ?? autoId;
 
   useEffect(() => {
     add(id, { autoFocus });

package/src/hooks/use-input.ts

@@ -1,9 +1,9 @@
 import { useEffect, useEffectEvent } from "react";
 
-import { ESC } from "../ansi/escapes.ts";
-import { parseKeypress, nonAlphanumericKeys } from "../parse-keypress.ts";
-import { reconciler } from "../reconciler.ts";
-import { useStdinContext } from "./use-stdin.ts";
+import { ESC } from "#/ansi/escapes.ts";
+import { useStdinContext } from "#/hooks/use-stdin.ts";
+import { parseKeypress, nonAlphanumericKeys } from "#/parse-keypress.ts";
+import { reconciler } from "#/reconciler.ts";
 
 /**
 Handy information about a key that was pressed.

package/src/hooks/use-is-screen-reader-enabled.ts

@@ -1,6 +1,6 @@
 import { useContext } from "react";
 
-import { accessibilityContext } from "../components/AccessibilityContext.ts";
+import { accessibilityContext } from "#/components/AccessibilityContext.ts";
 
 /**
 A React hook that returns whether a screen reader is enabled.

package/src/hooks/use-paste.ts

@@ -1,7 +1,7 @@
 import { useEffect, useEffectEvent } from "react";
 
-import { reconciler } from "../reconciler.ts";
-import { useStdinContext } from "./use-stdin.ts";
+import { useStdinContext } from "#/hooks/use-stdin.ts";
+import { reconciler } from "#/reconciler.ts";
 
 type Options = {
   /**

package/src/hooks/use-stderr.ts

@@ -1,6 +1,6 @@
 import { useContext } from "react";
 
-import { StderrContext } from "../components/StderrContext.ts";
+import { StderrContext } from "#/components/StderrContext.ts";
 
 /**
 A React hook that returns the stderr stream.

package/src/hooks/use-stdin.ts

@@ -1,6 +1,6 @@
 import { useContext } from "react";
 
-import { StdinContext, type PublicProps, type Props } from "../components/StdinContext.ts";
+import { StdinContext, type PublicProps, type Props } from "#/components/StdinContext.ts";
 
 /**
 A React hook that returns the stdin stream and stdin-related utilities.

package/src/hooks/use-stdout.ts

@@ -1,6 +1,6 @@
 import { useContext } from "react";
 
-import { StdoutContext } from "../components/StdoutContext.ts";
+import { StdoutContext } from "#/components/StdoutContext.ts";
 
 /**
 A React hook that returns the stdout stream where Ink renders your app.

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/hooks/use-window-size.ts

@@ -1,7 +1,7 @@
 import { useState, useEffect } from "react";
 
-import { getWindowSize } from "../utils.ts";
-import { useStdout } from "./use-stdout.ts";
+import { useStdout } from "#/hooks/use-stdout.ts";
+import { getWindowSize } from "#/utils.ts";
 
 /**
 Dimensions of the terminal window.

package/src/index.ts

@@ -1,44 +1,88 @@
-export type { RenderOptions, Instance } from "./render.ts";
-export type { CapturedOutputSource } from "./ink.tsx";
-export { render } from "./render.ts";
-export type { RenderToStringOptions } from "./render-to-string.ts";
-export { renderToString } from "./render-to-string.ts";
-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 AppProps } from "./components/AppContext.ts";
-export type { PublicProps as StdinProps } from "./components/StdinContext.ts";
-export type { Props as StdoutProps } from "./components/StdoutContext.ts";
-export type { Props as StderrProps } from "./components/StderrContext.ts";
-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 NewlineProps } from "./components/Newline.tsx";
-export { Newline } from "./components/Newline.tsx";
-export { Spacer } from "./components/Spacer.tsx";
-export type { Key } from "./hooks/use-input.ts";
-export { useInput } from "./hooks/use-input.ts";
-export { usePaste } from "./hooks/use-paste.ts";
-export type { SuspendTerminal, TerminalSuspension } from "./components/AppContext.ts";
-export { useApp } from "./hooks/use-app.ts";
-export { useStdin } from "./hooks/use-stdin.ts";
-export { useStdout } from "./hooks/use-stdout.ts";
-export { useStderr } from "./hooks/use-stderr.ts";
-export { useFocus } from "./hooks/use-focus.ts";
-export { useFocusManager } from "./hooks/use-focus-manager.ts";
-export { useIsScreenReaderEnabled } from "./hooks/use-is-screen-reader-enabled.ts";
-export { useCursor } from "./hooks/use-cursor.ts";
-export type { AnimationResult } from "./hooks/use-animation.ts";
-export { useAnimation } from "./hooks/use-animation.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 { measureElement } from "./measure-element.ts";
-export type { ElementMetrics } from "./measure-element.ts";
-export type { DOMElement } from "./dom.ts";
-export { kittyFlags, kittyModifiers } from "./kitty-keyboard.ts";
-export type { KittyKeyboardOptions, KittyFlagName } from "./kitty-keyboard.ts";
+export type { RenderOptions, Instance } from "#/render.ts";
+export type { CapturedOutputSource } from "#/ink.tsx";
+export { render } from "#/render.ts";
+export type { RenderToStringOptions } from "#/render-to-string.ts";
+export { renderToString } from "#/render-to-string.ts";
+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";
+export type { Props as StderrProps } from "#/components/StderrContext.ts";
+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";
+export type { SuspendTerminal, TerminalSuspension } from "#/components/AppContext.ts";
+export { useApp } from "#/hooks/use-app.ts";
+export { useStdin } from "#/hooks/use-stdin.ts";
+export { useStdout } from "#/hooks/use-stdout.ts";
+export { useStderr } from "#/hooks/use-stderr.ts";
+export { useFocus } from "#/hooks/use-focus.ts";
+export { useFocusManager } from "#/hooks/use-focus-manager.ts";
+export { useIsScreenReaderEnabled } from "#/hooks/use-is-screen-reader-enabled.ts";
+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 "#/cursor-position.ts";
+export { measureElement } from "#/measure-element.ts";
+export type { ElementMetrics } from "#/measure-element.ts";
+export type { DOMElement } from "#/dom.ts";
+export { kittyFlags, kittyModifiers } from "#/kitty-keyboard.ts";
+export type { KittyKeyboardOptions, KittyFlagName } from "#/kitty-keyboard.ts";