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

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;
+};

package/src/router/components.tsx

@@ -0,0 +1,343 @@
+/** @jsxImportSource react */
+// MemoryRouter/Routes/Route/Navigate/Outlet are ported from react-router's
+// declarative components (lib/components.tsx, MIT). Link is Sigil-native.
+import {
+  Children,
+  Fragment,
+  isValidElement,
+  startTransition,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { Text, type Props as TextProps } from "#/components/Text.tsx";
+import { useFocus } from "#/hooks/use-focus.ts";
+import { useInput } from "#/hooks/use-input.ts";
+import { LocationContext, NavigationContext, type Navigator } from "#/router/context.ts";
+import {
+  createMemoryHistory,
+  type InitialEntry,
+  type Location,
+  type To,
+} from "#/router/history.ts";
+import {
+  useLocation,
+  useNavigate,
+  useOutlet,
+  useResolvedPath,
+  useRoutes,
+} from "#/router/hooks.tsx";
+import { normalizePathname, type RouteObject } from "#/router/matcher.ts";
+
+export type MemoryRouterProps = {
+  /**
+	The navigation stack to start with. Defaults to `["/"]`.
+	*/
+  initialEntries?: InitialEntry[];
+
+  /**
+	The index of the initial entry to render. Defaults to the last entry.
+	*/
+  initialIndex?: number;
+
+  children?: ReactNode;
+};
+
+/**
+The routing container for a Sigil app. Stores the navigation stack in memory —
+routes aren't URLs, they're screen states.
+
+```tsx
+<MemoryRouter>
+  <Routes>
+    <Route path="/" element={<Home />} />
+    <Route path="/settings" element={<Settings />} />
+  </Routes>
+</MemoryRouter>
+```
+*/
+export function MemoryRouter({ initialEntries, initialIndex, children }: MemoryRouterProps) {
+  const historyRef = useRef<ReturnType<typeof createMemoryHistory> | null>(null);
+  historyRef.current ??= createMemoryHistory({ initialEntries, initialIndex });
+
+  const history = historyRef.current;
+  const [state, setState] = useState({
+    action: history.action,
+    location: history.location,
+  });
+
+  // Navigation is a transition: if the destination screen suspends, the
+  // current screen stays visible until it's ready.
+  useLayoutEffect(
+    () =>
+      history.listen(({ action, location }) => {
+        startTransition(() => {
+          setState({ action, location });
+        });
+      }),
+    [history],
+  );
+
+  const navigator = useMemo<Navigator>(
+    () => ({
+      push: (to, historyState) => history.push(to, historyState),
+      replace: (to, historyState) => history.replace(to, historyState),
+      go: (delta) => history.go(delta),
+      canGoBack: () => history.canGoBack,
+      canGoForward: () => history.canGoForward,
+    }),
+    [history],
+  );
+
+  const navigationContext = useMemo(() => ({ navigator }), [navigator]);
+  const locationContext = useMemo(
+    () => ({ location: state.location, navigationType: state.action }),
+    [state],
+  );
+
+  return (
+    <NavigationContext.Provider value={navigationContext}>
+      <LocationContext.Provider value={locationContext}>{children}</LocationContext.Provider>
+    </NavigationContext.Provider>
+  );
+}
+
+export type RouteProps = {
+  /**
+	The path pattern to match, relative to the parent route. Supports `:param`
+	dynamic segments, optional segments (`:param?`, `edit?`), and a trailing
+	`*` splat.
+	*/
+  path?: string;
+
+  /**
+	Render this route in the parent's `<Outlet>` at the parent's exact path.
+	Index routes cannot have children.
+	*/
+  index?: boolean;
+
+  /**
+	The element to render when this route matches.
+	*/
+  element?: ReactNode;
+
+  /**
+	Nested `<Route>` elements, rendered into this route's `<Outlet>`.
+	*/
+  children?: ReactNode;
+};
+
+/**
+Declares a route. Only valid as a child of `<Routes>` or another `<Route>`.
+*/
+export function Route(_props: RouteProps): ReactElement | null {
+  throw new Error(
+    "A <Route> is only ever to be used as the child of a <Routes> element, " +
+      "never rendered directly. Please wrap your <Route> in a <Routes>.",
+  );
+}
+
+function createRoutesFromChildren(children: ReactNode): RouteObject[] {
+  const routes: RouteObject[] = [];
+
+  Children.forEach(children, (element) => {
+    if (!isValidElement(element)) {
+      // Ignore non-elements. This allows people to more easily inline
+      // conditionals in their route config.
+      return;
+    }
+
+    if (element.type === Fragment) {
+      // Transparently support React.Fragment and its children.
+      routes.push(
+        ...createRoutesFromChildren((element.props as { children?: ReactNode }).children),
+      );
+      return;
+    }
+
+    if (element.type !== Route) {
+      throw new Error(
+        `[${typeof element.type === "string" ? element.type : ((element.type as { name?: string }).name ?? "unknown")}] ` +
+          `is not a <Route> component. All component children of <Routes> must be a <Route> or <React.Fragment>.`,
+      );
+    }
+
+    const props = element.props as RouteProps;
+    const route: RouteObject = {
+      path: props.path,
+      index: props.index,
+      element: props.element,
+    };
+
+    if (props.children) {
+      route.children = createRoutesFromChildren(props.children);
+    }
+
+    routes.push(route);
+  });
+
+  return routes;
+}
+
+export type RoutesProps = {
+  children?: ReactNode;
+
+  /**
+	Match against this location instead of the current one. Useful for
+	rendering a screen other than the one navigated to (e.g. transitions).
+	*/
+  location?: Partial<Location> | string;
+};
+
+/**
+Renders the branch of child `<Route>` elements that best matches the current
+location.
+*/
+export function Routes({ children, location }: RoutesProps): ReactElement | null {
+  return useRoutes(createRoutesFromChildren(children), location);
+}
+
+export type OutletProps = {
+  /**
+	A value to make available to descendant routes via `useOutletContext()`.
+	*/
+  context?: unknown;
+};
+
+/**
+Renders the matching child route of a parent route, or nothing if no child
+matches.
+*/
+export function Outlet(props: OutletProps): ReactElement | null {
+  return useOutlet(props.context);
+}
+
+export type NavigateProps = {
+  to: To;
+  replace?: boolean;
+  state?: unknown;
+};
+
+/**
+Navigates as soon as it renders. The component form of `useNavigate`, for
+declarative redirects:
+
+```tsx
+<Route path="/" element={<Navigate to="/home" replace />} />
+```
+*/
+export function Navigate({ to, replace, state }: NavigateProps): null {
+  const navigate = useNavigate();
+  const { pathname, search } = useResolvedPath(to);
+
+  useEffect(() => {
+    navigate({ pathname, search }, { replace, state });
+  }, [navigate, pathname, search, replace, state]);
+
+  return null;
+}
+
+type LinkRenderState = {
+  /**
+	Whether this link currently has focus.
+	*/
+  isFocused: boolean;
+
+  /**
+	Whether the current location is the link's destination or a descendant of
+	it.
+	*/
+  isActive: boolean;
+};
+
+export type LinkProps = Omit<TextProps, "children"> & {
+  /**
+	The destination to navigate to when the link is activated.
+	*/
+  to: To;
+
+  /**
+	Replace the current entry in the navigation stack instead of pushing.
+	*/
+  replace?: boolean;
+
+  /**
+	State to attach to the destination location.
+	*/
+  state?: unknown;
+
+  /**
+	Focus this link if nothing else is focused yet.
+	*/
+  autoFocus?: boolean;
+
+  /**
+	An ID for programmatic focus via `useFocusManager().focus(id)`.
+	*/
+  id?: string;
+
+  /**
+	Link content. Pass a function to take full control of rendering based on
+	focus and active state.
+	*/
+  children?: ReactNode | ((state: LinkRenderState) => ReactNode);
+};
+
+/**
+A focusable navigation element — the terminal's `<a>` tag. Focus it with
+<kbd>Tab</kbd> and activate it with <kbd>Enter</kbd>. By default the focused
+link renders inverse; pass a function as `children` (or any `Text` props) to
+customize.
+
+```tsx
+<Link to="/settings">Settings</Link>
+```
+*/
+export function Link({
+  to,
+  replace = false,
+  state,
+  autoFocus = false,
+  id,
+  children,
+  ...textProps
+}: LinkProps) {
+  const navigate = useNavigate();
+  const path = useResolvedPath(to);
+  const { pathname: locationPathname } = useLocation();
+  const { isFocused } = useFocus({ autoFocus, id });
+
+  const toPathname = normalizePathname(path.pathname);
+  const isActive =
+    locationPathname === toPathname ||
+    (locationPathname.startsWith(toPathname) && locationPathname.charAt(toPathname.length) === "/");
+
+  const activate = useCallback(() => {
+    navigate({ pathname: path.pathname, search: path.search }, { replace, state });
+  }, [navigate, path.pathname, path.search, replace, state]);
+
+  useInput(
+    (_input, key) => {
+      if (key.return) {
+        activate();
+      }
+    },
+    { isActive: isFocused },
+  );
+
+  if (typeof children === "function") {
+    return <>{children({ isFocused, isActive })}</>;
+  }
+
+  return (
+    <Text inverse={isFocused} {...textProps}>
+      {children}
+    </Text>
+  );
+}

package/src/router/context.ts

@@ -0,0 +1,41 @@
+import { createContext, type ReactElement } from "react";
+
+import { type Location, type NavigationType, type Path } from "#/router/history.ts";
+import { type RouteMatch } from "#/router/matcher.ts";
+
+/**
+The imperative interface `useNavigate` drives. Backed by the memory history
+inside `<MemoryRouter>`.
+*/
+export type Navigator = {
+  push: (to: Path, state?: unknown) => void;
+  replace: (to: Path, state?: unknown) => void;
+  go: (delta: number) => void;
+  canGoBack: () => boolean;
+  canGoForward: () => boolean;
+};
+
+export type NavigationContextObject = {
+  navigator: Navigator;
+};
+
+export const NavigationContext = createContext<NavigationContextObject | null>(null);
+
+export type LocationContextObject = {
+  location: Location;
+  navigationType: NavigationType;
+};
+
+export const LocationContext = createContext<LocationContextObject | null>(null);
+
+export type RouteContextObject = {
+  outlet: ReactElement | null;
+  matches: RouteMatch[];
+};
+
+export const RouteContext = createContext<RouteContextObject>({
+  outlet: null,
+  matches: [],
+});
+
+export const OutletContext = createContext<unknown>(null);