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

package/src/input-parser.ts

@@ -0,0 +1,303 @@
+import { ESC, pasteStart, pasteEnd } from "#/ansi/escapes.ts";
+
+const escape = ESC;
+
+export type InputEvent = string | { readonly paste: string };
+
+type ParsedInput = {
+  readonly events: InputEvent[];
+  readonly pending: string;
+};
+
+type ParsedSequence =
+  | {
+      readonly sequence: string;
+      readonly nextIndex: number;
+    }
+  | "pending"
+  | undefined;
+
+const isCsiParameterByte = (byte: number): boolean => {
+  return byte >= 0x30 && byte <= 0x3f;
+};
+
+const isCsiIntermediateByte = (byte: number): boolean => {
+  return byte >= 0x20 && byte <= 0x2f;
+};
+
+const isCsiFinalByte = (byte: number): boolean => {
+  return byte >= 0x40 && byte <= 0x7e;
+};
+
+const parseCsiSequence = (
+  input: string,
+  startIndex: number,
+  prefixLength: number,
+): ParsedSequence => {
+  const csiPayloadStart = startIndex + prefixLength + 1;
+  let index = csiPayloadStart;
+  for (; index < input.length; index++) {
+    const byte = input.codePointAt(index);
+    if (byte === undefined) {
+      return "pending";
+    }
+
+    // A new Escape or Ctrl+C cancels a truncated control sequence. Keep the
+    // cancelling byte for the next event, never insert the abandoned prefix.
+    if (byte === 0x1b || byte === 0x03) {
+      return { sequence: "", nextIndex: index };
+    }
+
+    if (isCsiParameterByte(byte) || isCsiIntermediateByte(byte)) {
+      continue;
+    }
+
+    // Preserve legacy terminal function-key sequences like ESC[[A and ESC[[5~.
+    if (byte === 0x5b && index === csiPayloadStart) {
+      continue;
+    }
+
+    if (isCsiFinalByte(byte)) {
+      return {
+        sequence: input.slice(startIndex, index + 1),
+        nextIndex: index + 1,
+      };
+    }
+
+    return;
+  }
+
+  return "pending";
+};
+
+const parseSs3Sequence = (
+  input: string,
+  startIndex: number,
+  prefixLength: number,
+): ParsedSequence => {
+  const nextIndex = startIndex + prefixLength + 2;
+  if (nextIndex > input.length) {
+    return "pending";
+  }
+
+  const finalByte = input.codePointAt(nextIndex - 1);
+  if (finalByte === undefined || !isCsiFinalByte(finalByte)) {
+    return;
+  }
+
+  return {
+    sequence: input.slice(startIndex, nextIndex),
+    nextIndex,
+  };
+};
+
+const parseControlSequence = (
+  input: string,
+  startIndex: number,
+  prefixLength: number,
+): ParsedSequence => {
+  const sequenceType = input[startIndex + prefixLength];
+  if (sequenceType === undefined) {
+    return "pending";
+  }
+
+  if (sequenceType === "[") {
+    return parseCsiSequence(input, startIndex, prefixLength);
+  }
+
+  // OSC, DCS and APC replies are single events, even across stdin chunks.
+  if (sequenceType === "]" || sequenceType === "P" || sequenceType === "_") {
+    for (let index = startIndex + prefixLength + 1; index < input.length; index++) {
+      if (
+        input[index] === "\u0003" ||
+        (input[index] === escape && index + 1 < input.length && input[index + 1] !== "\\")
+      ) {
+        return { sequence: "", nextIndex: index };
+      }
+      const bel = sequenceType === "]" && input[index] === "\u0007";
+      const st = input[index] === escape && input[index + 1] === "\\";
+      if (bel || st) {
+        const nextIndex = index + (st ? 2 : 1);
+        return { sequence: input.slice(startIndex, nextIndex), nextIndex };
+      }
+    }
+    return "pending";
+  }
+
+  if (sequenceType === "O") {
+    return parseSs3Sequence(input, startIndex, prefixLength);
+  }
+
+  return;
+};
+
+const parseEscapedCodePoint = (
+  input: string,
+  escapeIndex: number,
+): {
+  readonly sequence: string;
+  readonly nextIndex: number;
+} => {
+  const nextCodePoint = input.codePointAt(escapeIndex + 1);
+  const nextCodePointLength = nextCodePoint !== undefined && nextCodePoint > 0xff_ff ? 2 : 1;
+  const nextIndex = escapeIndex + 1 + nextCodePointLength;
+
+  return {
+    sequence: input.slice(escapeIndex, nextIndex),
+    nextIndex,
+  };
+};
+
+type ParsedEscapeSequence =
+  | {
+      readonly sequence: string;
+      readonly nextIndex: number;
+    }
+  | "pending";
+
+const parseEscapeSequence = (input: string, escapeIndex: number): ParsedEscapeSequence => {
+  if (escapeIndex === input.length - 1) {
+    return "pending";
+  }
+
+  const next = input[escapeIndex + 1]!;
+  if (next === escape) {
+    if (escapeIndex + 2 >= input.length) {
+      return "pending";
+    }
+
+    const doubleEscapeSequence = parseControlSequence(input, escapeIndex, 2);
+    if (doubleEscapeSequence === "pending") {
+      return "pending";
+    }
+
+    if (doubleEscapeSequence) {
+      return doubleEscapeSequence;
+    }
+
+    return {
+      sequence: input.slice(escapeIndex, escapeIndex + 2),
+      nextIndex: escapeIndex + 2,
+    };
+  }
+
+  const controlSequence = parseControlSequence(input, escapeIndex, 1);
+  if (controlSequence === "pending") {
+    return "pending";
+  }
+
+  if (controlSequence) {
+    return controlSequence;
+  }
+
+  return parseEscapedCodePoint(input, escapeIndex);
+};
+
+/**
+Split a chunk of non-escape text so that backspace bytes (`0x7F` and `0x08`) become individual events. When a user holds the backspace key, the terminal sends repeated bytes in a single stdin chunk. Without splitting, `parseKeypress` receives the multi-byte string and fails to recognize it as a key event, corrupting the input state.
+
+Other control characters like `\r` and `\t` are NOT split because they can legitimately appear inside pasted text.
+*/
+const splitBackspaceBytes = (text: string, events: InputEvent[]): void => {
+  let textSegmentStart = 0;
+
+  for (let index = 0; index < text.length; index++) {
+    const character = text[index]!;
+    if (character === "\u007F" || character === "\u0008") {
+      if (index > textSegmentStart) {
+        events.push(text.slice(textSegmentStart, index));
+      }
+
+      events.push(character);
+      textSegmentStart = index + 1;
+    }
+  }
+
+  if (textSegmentStart < text.length) {
+    events.push(text.slice(textSegmentStart));
+  }
+};
+
+const parseKeypresses = (input: string): ParsedInput => {
+  const events: InputEvent[] = [];
+  let index = 0;
+  const pendingFrom = (pendingStartIndex: number): ParsedInput => ({
+    events,
+    pending: input.slice(pendingStartIndex),
+  });
+
+  while (index < input.length) {
+    const escapeIndex = input.indexOf(escape, index);
+    if (escapeIndex === -1) {
+      splitBackspaceBytes(input.slice(index), events);
+      return {
+        events,
+        pending: "",
+      };
+    }
+
+    if (escapeIndex > index) {
+      splitBackspaceBytes(input.slice(index, escapeIndex), events);
+    }
+
+    const parsedEscapeSequence = parseEscapeSequence(input, escapeIndex);
+    if (parsedEscapeSequence === "pending") {
+      return pendingFrom(escapeIndex);
+    }
+
+    if (parsedEscapeSequence.sequence === pasteStart) {
+      const afterStart = parsedEscapeSequence.nextIndex;
+      const endIndex = input.indexOf(pasteEnd, afterStart);
+      if (endIndex === -1) {
+        return pendingFrom(escapeIndex);
+      }
+
+      events.push({ paste: input.slice(afterStart, endIndex) });
+      index = endIndex + pasteEnd.length;
+      continue;
+    }
+
+    if (parsedEscapeSequence.sequence.length > 0) events.push(parsedEscapeSequence.sequence);
+    index = parsedEscapeSequence.nextIndex;
+  }
+
+  return {
+    events,
+    pending: "",
+  };
+};
+
+export type InputParser = {
+  push: (chunk: string) => InputEvent[];
+  hasPendingEscape: () => boolean;
+  flushPendingEscape: () => string | undefined;
+  reset: () => void;
+};
+
+export const createInputParser = (): InputParser => {
+  let pending = "";
+  // Only ambiguous Escape/Alt prefixes may time out. Once a control
+  // sequence starts, keep it intact until its terminator arrives.
+  const hasPendingEscape = () => pending.startsWith(escape) && !/^\u001B{1,2}[[\]P_]/.test(pending);
+
+  return {
+    push(chunk) {
+      const parsedInput = parseKeypresses(pending + chunk);
+      pending = parsedInput.pending;
+      return parsedInput.events;
+    },
+    hasPendingEscape,
+    flushPendingEscape() {
+      if (!hasPendingEscape()) {
+        return;
+      }
+
+      const pendingEscape = pending;
+      pending = "";
+      return pendingEscape;
+    },
+    reset() {
+      pending = "";
+    },
+  };
+};

package/src/instances.ts

@@ -0,0 +1,9 @@
+// Store all instances of Ink (instance.js) to ensure that consecutive render() calls
+// use the same instance of Ink and don't create a new one
+//
+// This map has to be stored in a separate file, because render.js creates instances,
+// but instance.js should delete itself from the map on unmount
+
+import type { Ink } from "#/ink.tsx";
+
+export const instances = new WeakMap<NodeJS.WritableStream, Ink>();

package/src/jsx-dev-runtime.ts

@@ -0,0 +1,3 @@
+// See jsx-runtime.ts for why the names are enumerated.
+export { Fragment, jsxDEV } from "react/jsx-dev-runtime";
+export type { JSX } from "react/jsx-dev-runtime";

package/src/jsx-runtime.ts

@@ -0,0 +1,6 @@
+// `react/jsx-runtime` is CommonJS; a star re-export carries no static names
+// through the bundler, so the automatic-runtime surface is spelled out.
+export { Fragment, jsx, jsxs } from "react/jsx-runtime";
+// `jsxImportSource` looks up the `JSX` namespace on this module to type
+// elements and props. Type-only, so the bundle is unaffected.
+export type { JSX } from "react/jsx-runtime";

package/src/kitty-keyboard.ts

@@ -0,0 +1,185 @@
+import { kittyQuery } from "#/ansi/escapes.ts";
+
+// Kitty keyboard protocol flags.
+// @see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+export const kittyFlags = {
+  disambiguateEscapeCodes: 1,
+  reportEventTypes: 2,
+  reportAlternateKeys: 4,
+  reportAllKeysAsEscapeCodes: 8,
+  reportAssociatedText: 16,
+} as const;
+
+// Valid flag names for the kitty keyboard protocol.
+export type KittyFlagName = keyof typeof kittyFlags;
+
+// Converts an array of flag names to the corresponding bitmask value.
+export function resolveFlags(flags: KittyFlagName[]): number {
+  let result = 0;
+  for (const flag of flags) {
+    // eslint-disable-next-line no-bitwise
+    result |= kittyFlags[flag];
+  }
+
+  return result;
+}
+
+// Kitty keyboard modifier bits.
+// These are used in the modifier parameter of CSI u sequences.
+// Note: The actual modifier value is (modifiers - 1) as per the protocol.
+export const kittyModifiers = {
+  shift: 1,
+  alt: 2,
+  ctrl: 4,
+  super: 8,
+  hyper: 16,
+  meta: 32,
+  capsLock: 64,
+  numLock: 128,
+} as const;
+
+// Options for configuring kitty keyboard protocol.
+export type KittyKeyboardOptions = {
+  // Mode for kitty keyboard protocol support.
+  // - 'auto': Attempt to detect terminal support (default)
+  // - 'enabled': Force enable the protocol
+  // - 'disabled': Never enable the protocol
+  mode?: "auto" | "enabled" | "disabled";
+
+  // Protocol flags to request from the terminal.
+  // Pass an array of flag name strings.
+  //
+  // Available flags:
+  // - 'disambiguateEscapeCodes' - Disambiguate escape codes (default)
+  // - 'reportEventTypes' - Report key press, repeat, and release events
+  // - 'reportAlternateKeys' - Report alternate key encodings
+  // - 'reportAllKeysAsEscapeCodes' - Report all keys as escape codes
+  // - 'reportAssociatedText' - Report associated text with key events
+  flags?: KittyFlagName[];
+};
+
+const textEncoder = new TextEncoder();
+
+const kittyQueryEscapeByte = 0x1b;
+const kittyQueryOpenBracketByte = 0x5b;
+const kittyQueryQuestionMarkByte = 0x3f;
+const kittyQueryLetterByte = 0x75;
+const zeroByte = 0x30;
+const nineByte = 0x39;
+
+type KittyQueryResponseMatch = { state: "complete"; endIndex: number } | { state: "partial" };
+
+const isDigitByte = (byte: number): boolean => byte >= zeroByte && byte <= nineByte;
+
+const matchKittyQueryResponse = (
+  buffer: number[],
+  startIndex: number,
+): KittyQueryResponseMatch | undefined => {
+  if (
+    buffer[startIndex] !== kittyQueryEscapeByte ||
+    buffer[startIndex + 1] !== kittyQueryOpenBracketByte ||
+    buffer[startIndex + 2] !== kittyQueryQuestionMarkByte
+  ) {
+    return;
+  }
+
+  let index = startIndex + 3;
+  const digitsStartIndex = index;
+  while (index < buffer.length && isDigitByte(buffer[index]!)) {
+    index++;
+  }
+
+  if (index === digitsStartIndex) {
+    return;
+  }
+
+  if (index === buffer.length) {
+    return { state: "partial" };
+  }
+
+  if (buffer[index] === kittyQueryLetterByte) {
+    return { state: "complete", endIndex: index };
+  }
+
+  return;
+};
+
+const hasCompleteKittyQueryResponse = (buffer: number[]): boolean => {
+  for (let index = 0; index < buffer.length; index++) {
+    const match = matchKittyQueryResponse(buffer, index);
+    if (match?.state === "complete") {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+const stripKittyQueryResponsesAndTrailingPartial = (buffer: number[]): number[] => {
+  const keptBytes: number[] = [];
+  let index = 0;
+  while (index < buffer.length) {
+    const match = matchKittyQueryResponse(buffer, index);
+    if (match?.state === "complete") {
+      index = match.endIndex + 1;
+      continue;
+    }
+
+    if (match?.state === "partial") {
+      break;
+    }
+
+    keptBytes.push(buffer[index]!);
+    index++;
+  }
+
+  return keptBytes;
+};
+
+// Query the terminal for kitty keyboard protocol support. The CSI ? u query is
+// safe to send to any terminal — unsupporting terminals simply won't respond,
+// and the 200ms timeout handles that. Stdin bytes that aren't part of the
+// protocol response are re-emitted so they aren't lost from the caller's input
+// pipeline. Returns a cancel function; cancelling (or the timeout firing)
+// means `onSupported` never runs.
+export const detectKittySupport = (
+  stdin: NodeJS.ReadableStream,
+  stdout: { write: (data: string) => unknown },
+  onSupported: () => void,
+): (() => void) => {
+  let responseBuffer: number[] = [];
+
+  const cleanup = (): void => {
+    clearTimeout(timer);
+    stdin.removeListener("data", onData);
+
+    // Re-emit any buffered data that wasn't the protocol response.
+    // Clear responseBuffer afterwards to make cleanup idempotent.
+    const remaining = stripKittyQueryResponsesAndTrailingPartial(responseBuffer);
+    responseBuffer = [];
+    if (remaining.length > 0) {
+      stdin.unshift(Uint8Array.from(remaining));
+    }
+  };
+
+  const onData = (data: Uint8Array | string): void => {
+    const chunk = typeof data === "string" ? textEncoder.encode(data) : data;
+    for (const byte of chunk) {
+      responseBuffer.push(byte);
+    }
+
+    if (hasCompleteKittyQueryResponse(responseBuffer)) {
+      cleanup();
+      onSupported();
+    }
+  };
+
+  // Attach listener before writing the query so that synchronous
+  // or immediate responses are not missed.
+  stdin.on("data", onData);
+  const timer = setTimeout(cleanup, 200);
+
+  stdout.write(kittyQuery);
+
+  return cleanup;
+};

package/src/measure-element.ts

@@ -0,0 +1,62 @@
+import { type DOMElement } from "#/dom.ts";
+
+type Output = {
+  /**
+	Horizontal position (0-based column) within the live layout region.
+	*/
+  x: number;
+
+  /**
+	Vertical position (0-based row) within the live layout region.
+	*/
+  y: number;
+
+  /**
+	Element width.
+	*/
+  width: number;
+
+  /**
+	Element height.
+	*/
+  height: number;
+};
+
+/**
+Measure the layout metrics of a particular `<Box>` element.
+Returns an object with `x`, `y`, `width`, and `height` properties.
+
+`x` and `y` are the element's position within the live layout region, computed by walking up the layout tree and accumulating each ancestor's offset. These are layout-tree coordinates, not terminal viewport coordinates. To compare them with mouse events, convert the event coordinates using the live region's viewport position. This is necessary even in alternate-screen mode when output, such as `<Static>` content, appears above the live region.
+
+Note: `measureElement()` returns `{x: 0, y: 0, width: 0, height: 0}` when called during render (before layout is calculated). Call it from post-render code, such as `useEffect`, `useLayoutEffect`, input handlers, or timer callbacks. When content changes, pass the relevant dependency to your effect so it re-measures after each update.
+*/
+export const measureElement = (node: DOMElement): Output => {
+  const { yogaNode } = node;
+
+  if (!yogaNode) {
+    return { x: 0, y: 0, width: 0, height: 0 };
+  }
+
+  let x = yogaNode.getComputedLeft();
+  let y = yogaNode.getComputedTop();
+
+  let current = node.parentNode;
+
+  while (current) {
+    if (current.yogaNode) {
+      x += current.yogaNode.getComputedLeft();
+      y += current.yogaNode.getComputedTop();
+    }
+
+    current = current.parentNode;
+  }
+
+  return {
+    x,
+    y,
+    width: yogaNode.getComputedWidth(),
+    height: yogaNode.getComputedHeight(),
+  };
+};
+
+export type { Output as ElementMetrics };

package/src/measure-text.ts

@@ -0,0 +1,31 @@
+import { widestLine } from "#/ansi/string-width.ts";
+import { QuickLru as QuickLRU } from "#/quick-lru.ts";
+
+const cache = new QuickLRU<string, Output>({ maxSize: 4096 });
+
+type Output = {
+  width: number;
+  height: number;
+};
+
+export const measureText = (text: string): Output => {
+  if (text.length === 0) {
+    return {
+      width: 0,
+      height: 0,
+    };
+  }
+
+  const cachedDimensions = cache.get(text);
+
+  if (cachedDimensions) {
+    return cachedDimensions;
+  }
+
+  const width = widestLine(text);
+  const height = text.split("\n").length;
+  const dimensions = { width, height };
+  cache.set(text, dimensions);
+
+  return dimensions;
+};