restty 0.1.16 → 0.1.18

package/dist/fonts/manager.d.ts

@@ -1,20 +1,44 @@
 import type { FontEntry, FontManagerState, ShapedCluster, FallbackFontSource, FontScaleOverride } from "./types";
+/** Check whether a font entry is a symbol/icon font based on its label. */
 export declare function isSymbolFont(entry: FontEntry | null | undefined): boolean;
+/** Check whether a font entry is a Nerd Font symbols font. */
 export declare function isNerdSymbolFont(entry: FontEntry | null | undefined): boolean;
+/** Check whether a font entry is a color emoji font. */
 export declare function isColorEmojiFont(entry: FontEntry | null | undefined): boolean;
+/** Return the maximum cell span for a font (2 for CJK/emoji, 1 otherwise). */
 export declare function fontMaxCellSpan(entry: FontEntry | null | undefined): number;
+/** Return the scale multiplier for a font entry by matching its label against overrides. */
 export declare function fontScaleOverride(entry: FontEntry | null | undefined, overrides?: FontScaleOverride[]): number;
+/** Compute the atlas raster scale for a font, applying symbol atlas scaling for fallback symbol fonts. */
 export declare function fontRasterScale(entry: FontEntry | null | undefined, fontIndex: number, maxSymbolAtlasScale: number, overrides?: FontScaleOverride[]): number;
+/** Create a new FontEntry with empty caches and default metadata. */
 export declare function createFontEntry(font: any, label: string): FontEntry;
+/** Clear all caches and reset rendering metadata on a font entry. */
 export declare function resetFontEntry(entry: FontEntry): void;
+/** Create an empty FontManagerState for initialization. */
 export declare function createFontManagerState(): FontManagerState;
+/** Check whether a font has a non-zero glyph ID for the given character. */
 export declare function fontHasGlyph(font: any, ch: string): boolean;
+/** Get the horizontal advance width in font design units, computing and caching it if needed. */
 export declare function fontAdvanceUnits(entry: FontEntry, shapeClusterWithFont: (entry: FontEntry, text: string) => ShapedCluster): number;
+/** Get the bounding-box width of a glyph in font design units, with caching. */
 export declare function glyphWidthUnits(entry: FontEntry, glyphId: number | undefined | null): number;
+/**
+ * Select the best font index from the manager's font list for rendering the
+ * given text cluster, searching in fallback order similar to Ghostty.
+ */
 export declare function pickFontIndexForText(state: FontManagerState, text: string, expectedSpan: number, shapeClusterWithFont: (entry: FontEntry, text: string) => ShapedCluster): number;
+/** Fetch a font file from a URL and return its ArrayBuffer, or null on failure. */
 export declare function tryFetchFontBuffer(url: string): Promise<ArrayBuffer | null>;
+/** Query locally installed fonts via the Local Font Access API and return the first match, or null. */
 export declare function tryLocalFontBuffer(matchers: string[]): Promise<ArrayBuffer | null>;
+/**
+ * Load the primary font buffer, trying local Nerd Font matchers first,
+ * then a remote fallback URL, then broader local font matchers. Throws
+ * if all sources fail.
+ */
 export declare function loadPrimaryFontBuffer(localMatchers: string[], fallbackUrl: string, fallbackLocalMatchers: string[]): Promise<ArrayBuffer>;
+/** Load fallback font buffers from a list of sources, trying remote URLs then local matchers. */
 export declare function loadFallbackFontBuffers(sources: FallbackFontSource[]): Promise<{
     name: string;
     buffer: ArrayBuffer;

package/dist/fonts/nerd-constraints.d.ts

@@ -1,3 +1,4 @@
+/** Rendering constraints for Nerd Font symbols (sizing, alignment, padding). */
 export type NerdConstraint = {
     size?: "none" | "fit" | "cover" | "fit_cover1" | "stretch";
     align_horizontal?: "none" | "start" | "end" | "center" | "center1";
@@ -14,10 +15,13 @@ export type NerdConstraint = {
     max_xy_ratio?: number;
     max_constraint_width?: number;
 };
+/** Codepoint range with associated rendering constraint. */
 export type NerdConstraintRange = {
     start: number;
     end: number;
     constraint: NerdConstraint;
 };
+/** Nerd Font symbol rendering constraints by codepoint range. */
 export declare const NERD_CONSTRAINTS: NerdConstraintRange[];
+/** Binary search for the rendering constraint matching a Nerd Font codepoint, or null if none. */
 export declare function getNerdConstraint(cp: number): NerdConstraint | null;

package/dist/fonts/nerd-ranges.d.ts

@@ -1,2 +1,4 @@
+/** Unicode codepoint ranges for Nerd Font symbols (start, end inclusive). */
 export declare const NERD_SYMBOL_RANGES: Array<[number, number]>;
+/** Check if a codepoint falls within Nerd Font symbol ranges. */
 export declare function isNerdSymbolCodepoint(cp: number): boolean;

package/dist/fonts/types.d.ts

@@ -1,40 +1,91 @@
+/**
+ * A loaded font with its associated caches and rendering metadata.
+ */
 export type FontEntry = {
+    /** text-shaper Font instance. */
     font: any;
+    /** Human-readable font name. */
     label: string;
+    /** Cache of shaped glyph clusters keyed by input string. */
     glyphCache: Map<string, ShapedCluster>;
+    /** Cache of glyph advance bounds keyed by glyph ID. */
     boundsCache: Map<number, number>;
+    /** Map of glyph IDs to their original text for color emoji fallback. */
     colorGlyphTexts: Map<number, string>;
+    /** Set of all glyph IDs available in this font. */
     glyphIds: Set<number>;
+    /** GPU texture atlas for this font, or null if not yet built. */
     atlas: any | null;
+    /** Font size in CSS pixels. */
     fontSizePx: number;
+    /** Scale factor applied when rasterizing to the atlas. */
     atlasScale: number;
+    /** Horizontal advance width in font design units. */
     advanceUnits: number;
+    /** Signature string used to detect constraint changes for atlas invalidation. */
     constraintSignature?: string;
 };
+/**
+ * Result of shaping a text cluster into positioned glyphs.
+ */
 export type ShapedCluster = {
+    /** Ordered list of glyphs produced by the shaper. */
     glyphs: ShapedGlyph[];
+    /** Total horizontal advance of the cluster in font units. */
     advance: number;
 };
+/**
+ * A single positioned glyph within a shaped cluster.
+ */
 export type ShapedGlyph = {
+    /** Font-internal glyph identifier. */
     glyphId: number;
+    /** Horizontal advance after this glyph in font units. */
     xAdvance: number;
+    /** Vertical advance after this glyph in font units. */
     yAdvance: number;
+    /** Horizontal offset from the current pen position. */
     xOffset: number;
+    /** Vertical offset from the current pen position. */
     yOffset: number;
 };
+/**
+ * Internal state of the font manager.
+ */
 export type FontManagerState = {
+    /** Primary text-shaper Font instance, or null before initialization. */
     font: any | null;
+    /** Loaded font entries in priority order (primary + fallbacks). */
     fonts: FontEntry[];
+    /** Current font size in CSS pixels. */
     fontSizePx: number;
+    /**
+     * How font size maps to design units.
+     * - height: size equals cell height
+     * - width: size equals cell width
+     * - upem: size equals units-per-em
+     */
     sizeMode: "height" | "width" | "upem";
+    /** Cache mapping text strings to the index of the font chosen to render them. */
     fontPickCache: Map<string, number>;
 };
+/**
+ * Descriptor for a fallback font to load on demand.
+ */
 export type FallbackFontSource = {
+    /** Display name of the fallback font. */
     name: string;
+    /** URL to fetch the font file from. */
     url: string;
+    /** Unicode range or script patterns this font covers. */
     matchers: string[];
 };
+/**
+ * Per-font scale override applied when a font's label matches the pattern.
+ */
 export type FontScaleOverride = {
+    /** Regex tested against the font label. */
     match: RegExp;
+    /** Multiplier applied to the font's atlas scale. */
     scale: number;
 };

package/dist/grid/grid.d.ts

@@ -1,22 +1,44 @@
 import type { CellMetrics, GridConfig, GridState } from "./types";
+/**
+ * Font metrics interface used to measure glyph dimensions and compute cell sizes.
+ */
 export type FontMetricsProvider = {
+    /** Return the scale factor for a given pixel size and sizing mode. */
     scaleForSize(sizePx: number, sizeMode: string): number;
+    /** Look up the glyph ID for a character, or null/undefined if missing. */
     glyphIdForChar(char: string): number | undefined | null;
+    /** Return the advance width of a glyph in font units. */
     advanceWidth(glyphId: number): number;
+    /** Font ascender in font units. */
     readonly ascender: number;
+    /** Font descender in font units (typically negative). */
     readonly descender?: number;
+    /** Explicit font height in font units, if available. */
     readonly height?: number;
+    /** Units per em of the font. */
     readonly upem: number;
 };
+/** Result of shaping a text cluster, containing its advance width. */
 export type ShapeResult = {
     advance: number;
 };
+/** Resolve the font height in font units, falling back to ascender-descender or upem. */
 export declare function fontHeightUnits(font: FontMetricsProvider): number;
+/**
+ * Compute cell width, height, and baseline from font metrics, grid config,
+ * and device pixel ratio. Returns null if the font is unavailable.
+ */
 export declare function computeCellMetrics(font: FontMetricsProvider, config: GridConfig, dpr: number, shapeCluster: (text: string) => ShapeResult): CellMetrics | null;
+/** Create a zeroed-out grid state with default values. */
 export declare function createGridState(): GridState;
+/**
+ * Recompute grid dimensions from cell metrics and canvas size.
+ * Mutates state in place and returns whether cols/rows/metrics changed.
+ */
 export declare function updateGridState(state: GridState, metrics: CellMetrics, canvasWidth: number, canvasHeight: number): {
     changed: boolean;
     cols: number;
     rows: number;
 };
+/** Clamp a number to the inclusive [min, max] range. */
 export declare function clamp(value: number, min: number, max: number): number;

package/dist/grid/types.d.ts

@@ -1,24 +1,56 @@
+/**
+ * Current grid dimensions and cell metrics.
+ */
 export type GridState = {
+    /** Number of columns in the terminal grid. */
     cols: number;
+    /** Number of rows in the terminal grid. */
     rows: number;
+    /** Cell width in CSS pixels. */
     cellW: number;
+    /** Cell height in CSS pixels. */
     cellH: number;
+    /** Resolved font size in CSS pixels. */
     fontSizePx: number;
+    /** Device pixel ratio (DPR) scale factor. */
     scale: number;
+    /** Line height multiplier applied to font metrics. */
     lineHeight: number;
+    /** Vertical offset from cell top to text baseline in CSS pixels. */
     baselineOffset: number;
+    /** Vertical padding added to the top of the grid in CSS pixels. */
     yPad: number;
 };
+/**
+ * Computed cell measurement values derived from font metrics and DPR.
+ */
 export type CellMetrics = {
+    /** Cell width in CSS pixels. */
     cellW: number;
+    /** Cell height in CSS pixels. */
     cellH: number;
+    /** Resolved font size in CSS pixels. */
     fontSizePx: number;
+    /** Device pixel ratio (DPR) scale factor. */
     scale: number;
+    /** Line height multiplier applied to font metrics. */
     lineHeight: number;
+    /** Vertical offset from cell top to text baseline in CSS pixels. */
     baselineOffset: number;
+    /** Vertical padding added to the top of the grid in CSS pixels. */
     yPad: number;
 };
+/**
+ * Grid configuration for font sizing.
+ */
 export type GridConfig = {
+    /** Base font size value interpreted according to sizeMode. */
     fontSize: number;
+    /**
+     * How fontSize is interpreted.
+     * - height: CSS px height of glyphs
+     * - width: CSS px width of a single cell
+     * - upem: units-per-em (raw font units)
+     */
     sizeMode: "height" | "width" | "upem";
 };

package/dist/ime/ime.d.ts

@@ -1,14 +1,27 @@
 import type { ImeState, CursorPosition } from "./types";
+/** Create a fresh IME state with no active composition. */
 export declare function createImeState(): ImeState;
+/** Set the preedit string on the IME state and sync it to the hidden input element. */
 export declare function setPreedit(state: ImeState, text: string, imeInput?: HTMLInputElement | null): void;
+/** Clear the preedit string, reset selection offsets, and empty the hidden input. */
 export declare function clearPreedit(state: ImeState, imeInput?: HTMLInputElement | null): void;
+/** Begin an IME composition session, marking the state as composing and setting initial preedit. */
 export declare function startComposition(state: ImeState, data: string, imeInput?: HTMLInputElement | null): void;
+/** Update the preedit text during an active composition without changing composing state. */
 export declare function updateComposition(state: ImeState, data: string, imeInput?: HTMLInputElement | null): void;
+/** End the composition session and return the committed preedit text. */
 export declare function endComposition(state: ImeState): string;
+/** Read the current selection range from the hidden input and sync it into the IME state. */
 export declare function syncImeSelection(state: ImeState, imeInput: HTMLInputElement | null): void;
+/** Reposition the hidden IME input element to align with the terminal cursor. */
 export declare function updateImePosition(imeInput: HTMLInputElement | null, cursor: CursorPosition | null, cellW: number, cellH: number, dpr: number, canvasRect: DOMRect): void;
+/** Default RGBA background color for the preedit overlay. */
 export declare const PREEDIT_BG: readonly [0.16, 0.16, 0.2, 0.9];
+/** Default RGBA background color for the active (selected) preedit segment. */
 export declare const PREEDIT_ACTIVE_BG: readonly [0.3, 0.32, 0.42, 0.95];
+/** Default RGBA foreground color for preedit text. */
 export declare const PREEDIT_FG: readonly [0.95, 0.95, 0.98, 1];
+/** Default RGBA color for the preedit underline. */
 export declare const PREEDIT_UL: readonly [0.7, 0.7, 0.8, 0.9];
+/** Default RGBA color for the preedit caret. */
 export declare const PREEDIT_CARET: readonly [0.95, 0.95, 0.98, 1];

package/dist/ime/types.d.ts

@@ -1,9 +1,17 @@
+/**
+ * Current state of an active IME composition session.
+ */
 export type ImeState = {
+    /** Whether a composition is currently in progress. */
     composing: boolean;
+    /** The uncommitted preedit string shown during composition. */
     preedit: string;
+    /** Start offset of the selected range within the preedit string. */
     selectionStart: number;
+    /** End offset of the selected range within the preedit string. */
     selectionEnd: number;
 };
+/** Cursor position in terminal row/column coordinates. */
 export type CursorPosition = {
     row: number;
     col: number;

package/dist/input/ansi.d.ts

@@ -1,6 +1,9 @@
+/** Parse a DEC private mode set/reset sequence (CSI ? ... h/l) into mode codes and enabled state. */
 export declare function parsePrivateModeSeq(seq: string): {
     codes: number[];
     enabled: boolean;
 } | null;
+/** Parse a window manipulation sequence (CSI ... t) into its numeric parameters. */
 export declare function parseWindowOpSeq(seq: string): number[] | null;
+/** Test whether a CSI sequence is a Device Attributes query (DA1/DA2/DA3). */
 export declare function isDeviceAttributesQuery(seq: string): boolean;

package/dist/input/mouse.d.ts

@@ -1,12 +1,22 @@
 import type { CellPosition, MouseMode, MouseStatus } from "./types";
+/**
+ * Construction options for MouseController.
+ */
 export type MouseControllerOptions = {
+    /** Sink for mouse report sequences sent back to the PTY. */
     sendReply: (data: string) => void;
+    /** Map pointer events to 0-based cell coordinates. */
     positionToCell: (event: MouseEvent | PointerEvent | WheelEvent) => CellPosition;
+    /** Map pointer events to 1-based pixel coordinates (for SGR-Pixels mode). */
     positionToPixel?: (event: MouseEvent | PointerEvent | WheelEvent) => {
         x: number;
         y: number;
     };
 };
+/**
+ * Tracks mouse reporting state (mode, format, motion tracking) and encodes
+ * pointer events into terminal mouse sequences (X10, UTF-8, URxvt, SGR).
+ */
 export declare class MouseController {
     private mode;
     private enabled;

package/dist/input/output.d.ts

@@ -1,17 +1,28 @@
 import type { CursorPosition, WindowOp } from "./types";
 import type { MouseController } from "./mouse";
+/**
+ * Construction options for OutputFilter.
+ */
 export type OutputFilterOptions = {
+    /** Provide the current 1-based cursor position for CPR replies. */
     getCursorPosition: () => CursorPosition;
+    /** Sink for reply sequences (CPR, DA, OSC color queries). */
     sendReply: (data: string) => void;
+    /** MouseController instance for delegating mouse mode toggling. */
     mouse: MouseController;
+    /** Provide default colors for OSC 10/11/12 queries (RGB 0-255). */
     getDefaultColors?: () => {
         fg?: [number, number, number];
         bg?: [number, number, number];
         cursor?: [number, number, number];
     };
+    /** Handler for OSC 52 clipboard write requests. */
     onClipboardWrite?: (text: string) => void | Promise<void>;
+    /** Handler for OSC 52 clipboard read requests. */
     onClipboardRead?: () => string | null | Promise<string | null>;
+    /** Handler for window manipulation sequences (CSI ... t). */
     onWindowOp?: (op: WindowOp) => void;
+    /** Provider for XTWINOPS report queries (CSI 14/16/18 t). */
     getWindowMetrics?: () => {
         rows: number;
         cols: number;

package/dist/input/types.d.ts

@@ -28,11 +28,13 @@ export type InputHandlerConfig = {
      */
     enableCtrlCombos?: boolean;
 };
+/** Default terminal colors for OSC 10/11/12 query responses (RGB 0-255). */
 export type DefaultColors = {
     fg?: [number, number, number];
     bg?: [number, number, number];
     cursor?: [number, number, number];
 };
+/** Terminal window metrics for XTWINOPS reporting (CSI 14/16/18 t). */
 export type WindowMetrics = {
     rows: number;
     cols: number;
@@ -41,6 +43,11 @@ export type WindowMetrics = {
     cellWidthPx: number;
     cellHeightPx: number;
 };
+/**
+ * Parsed window manipulation operation (CSI ... t).
+ * - resize: terminal resize request
+ * - unknown: unhandled window operation
+ */
 export type WindowOp = {
     type: "resize";
     rows: number;