restty 0.1.16 → 0.1.18

package/README.md

@@ -170,10 +170,7 @@ Active-pane convenience:
 
 Use these only when you need lower-level control:
 
-- `restty/wasm`: low-level WASM ABI wrapper (`loadResttyWasm`, `ResttyWasm`)
-- `restty/input`: key/mouse/input encoding utilities
-- `restty/pty`: PTY transport helpers
-- `restty/internal`: full internal barrel (unstable)
+- `restty/internal`: full internal barrel (unstable; includes low-level modules like WASM/input/pty helpers)
 
 ## Local Development
 
@@ -183,8 +180,6 @@ cd restty
 git submodule update --init --recursive
 bun install
 bun run build:themes
-bun run build:assets
-bun run pty
 bun run playground
 ```
 
@@ -198,9 +193,9 @@ bun run test          # full tests
 bun run test:ci       # CI-safe test target
 bun run lint          # lint
 bun run format:check  # formatting check
-bun run build:assets  # playground bundles
-bun run pty           # local PTY websocket server
-bun run playground    # playground dev server
+bun run build:assets  # static playground bundle (playground/public/playground.js)
+bun run playground    # one-command local dev (PTY + playground dev server)
+bun run pty           # PTY websocket server only
 ```
 
 ## Documentation

package/dist/app/atlas-builder.d.ts

@@ -1,9 +1,27 @@
+/**
+ * Metadata for constrained glyph rendering.
+ * - cp: Unicode code point
+ * - constraintWidth: target cell width constraint
+ * - variable: whether glyph can render at multiple widths
+ * - widths: set of all required cell widths for this glyph
+ */
 export type GlyphConstraintMeta = {
     cp: number;
     constraintWidth: number;
     variable?: boolean;
     widths?: Set<number>;
 };
+/**
+ * Context for constraint-based atlas building, primarily for Nerd Fonts symbol alignment.
+ * - cellW: cell width in pixels
+ * - cellH: cell height in pixels
+ * - yPad: vertical padding
+ * - baselineOffset: baseline offset adjustment
+ * - baselineAdjust: additional baseline adjustment
+ * - fontScale: scale factor for font rendering
+ * - nerdMetrics: Nerd Fonts specific layout metrics
+ * - fontEntry: reference to font entry object
+ */
 export type AtlasConstraintContext = {
     cellW: number;
     cellH: number;
@@ -60,6 +78,17 @@ type BuildAtlasDeps = {
         atlasScale: number;
     }) => boolean;
 };
+/**
+ * Parameters for font atlas building.
+ * - entry: font entry containing the font object and cached atlas
+ * - neededGlyphIds: set of glyph IDs required in the atlas
+ * - glyphMeta: optional constraint metadata for symbol font glyphs
+ * - fontSizePx: base font size in pixels
+ * - atlasScale: scaling factor for high-DPI rendering
+ * - fontIndex: index in the font fallback chain (0 = primary font)
+ * - constraintContext: optional constraint context for symbol alignment
+ * - deps: external dependencies for atlas building
+ */
 export type BuildFontAtlasParams = {
     entry: any;
     neededGlyphIds: Set<number>;
@@ -70,6 +99,14 @@ export type BuildFontAtlasParams = {
     constraintContext?: AtlasConstraintContext | null;
     deps: BuildAtlasDeps;
 };
+/**
+ * Result from font atlas building.
+ * - rebuilt: true if a new atlas was generated
+ * - atlas: the atlas object containing glyph metrics and bitmap
+ * - rgba: RGBA pixel data ready for WebGL upload
+ * - colorGlyphs: set of glyph IDs that are color emoji
+ * - preferNearest: whether to use nearest-neighbor texture filtering
+ */
 export type BuildFontAtlasResult = {
     rebuilt: boolean;
     atlas: any | null;
@@ -77,5 +114,6 @@ export type BuildFontAtlasResult = {
     colorGlyphs?: Set<number>;
     preferNearest: boolean;
 };
+/** Builds or reuses a font atlas, detecting when rebuild is needed based on glyph requirements, size changes, or constraint updates. */
 export declare function buildFontAtlasIfNeeded(params: BuildFontAtlasParams): BuildFontAtlasResult;
 export {};

package/dist/app/font-sources.d.ts

@@ -1,3 +1,5 @@
 import type { ResttyFontPreset, ResttyFontSource } from "./types";
+/** Default font fallback chain with JetBrains Mono, Nerd Fonts symbols, Noto symbols, color emoji, black emoji, and CJK support. */
 export declare const DEFAULT_FONT_SOURCES: ResttyFontSource[];
+/** Validates user-provided font sources or returns defaults based on preset (none returns empty array, otherwise default CDN fonts). */
 export declare function normalizeFontSources(sources: ResttyFontSource[] | undefined, preset: ResttyFontPreset | undefined): ResttyFontSource[];

package/dist/app/pane-app-manager.d.ts

@@ -1,28 +1,55 @@
 import { type ResttyPaneStyleOptions, type ResttyPaneStylesOptions, type ResttyPaneContextMenuOptions, type ResttyPaneManager, type ResttyPaneShortcutsOptions, type ResttyPaneWithApp } from "./panes";
 import type { ResttyAppOptions, ResttyAppSession } from "./types";
+/**
+ * A pane created by the app pane manager, extending the base pane
+ * with DOM elements needed by the terminal app.
+ */
 export type ResttyManagedAppPane = ResttyPaneWithApp & {
+    /** The canvas element used for terminal rendering. */
     canvas: HTMLCanvasElement;
+    /** Hidden textarea for IME composition input. */
     imeInput: HTMLTextAreaElement;
+    /** Pre element for terminal debug / accessibility output. */
     termDebugEl: HTMLPreElement;
 };
+/**
+ * Default CSS class names for pane DOM elements.
+ */
 export type ResttyPaneDomDefaults = {
     paneClassName?: string;
     canvasClassName?: string;
     imeInputClassName?: string;
     termDebugClassName?: string;
 };
+/** Style options for managed panes (alias for ResttyPaneStyleOptions). */
 export type ResttyManagedPaneStyleOptions = ResttyPaneStyleOptions;
+/** Style configuration including enabled flag (alias for ResttyPaneStylesOptions). */
 export type ResttyManagedPaneStylesOptions = ResttyPaneStylesOptions;
+/** App options minus the DOM/session fields that the pane manager provides. */
 export type ResttyPaneAppOptionsInput = Omit<ResttyAppOptions, "canvas" | "imeInput" | "session">;
+/**
+ * Configuration for the built-in default context menu.
+ */
 export type ResttyDefaultPaneContextMenuOptions = {
+    /** Whether the default context menu is enabled (default true). */
     enabled?: boolean;
+    /** Guard predicate; return false to suppress the menu for a given event. */
     canOpen?: (event: MouseEvent, pane: ResttyManagedAppPane) => boolean;
+    /** Override the modifier key label shown in shortcut hints. */
     modKeyLabel?: string;
+    /** Provide the PTY WebSocket URL for the connect/disconnect menu item. */
     getPtyUrl?: () => string | null | undefined;
 };
+/**
+ * Options for creating an app-level pane manager that wires up DOM
+ * elements, the terminal app, and the shared session automatically.
+ */
 export type CreateResttyAppPaneManagerOptions = {
+    /** Root element that will contain all pane DOM trees. */
     root: HTMLElement;
+    /** Shared session for WASM/WebGPU resources (defaults to the global session). */
     session?: ResttyAppSession;
+    /** Per-pane app options, static object or factory receiving pane context. */
     appOptions?: ResttyPaneAppOptionsInput | ((context: {
         id: number;
         sourcePane: ResttyManagedAppPane | null;
@@ -30,17 +57,33 @@ export type CreateResttyAppPaneManagerOptions = {
         imeInput: HTMLTextAreaElement;
         termDebugEl: HTMLPreElement;
     }) => ResttyPaneAppOptionsInput);
+    /** Override default CSS class names for pane DOM elements. */
     paneDom?: ResttyPaneDomDefaults;
+    /** Automatically call app.init() after pane creation (default true). */
     autoInit?: boolean;
+    /** Minimum pane size in pixels during split-resize (default 96). */
     minPaneSize?: number;
+    /** Enable or configure built-in pane CSS styles. */
     paneStyles?: boolean | ResttyManagedPaneStylesOptions;
+    /** Enable or configure keyboard shortcuts for splitting. */
     shortcuts?: boolean | ResttyPaneShortcutsOptions;
+    /** Custom context menu implementation (overrides defaultContextMenu). */
     contextMenu?: ResttyPaneContextMenuOptions<ResttyManagedAppPane> | null;
+    /** Enable or configure the built-in default context menu. */
     defaultContextMenu?: boolean | ResttyDefaultPaneContextMenuOptions;
+    /** Called after a new pane is created. */
     onPaneCreated?: (pane: ResttyManagedAppPane) => void;
+    /** Called after a pane is closed. */
     onPaneClosed?: (pane: ResttyManagedAppPane) => void;
+    /** Called after a pane is split. */
     onPaneSplit?: (sourcePane: ResttyManagedAppPane, createdPane: ResttyManagedAppPane, direction: "vertical" | "horizontal") => void;
+    /** Called when the active pane changes (or becomes null). */
     onActivePaneChange?: (pane: ResttyManagedAppPane | null) => void;
+    /** Called when the layout changes (splits, closes, resizes). */
     onLayoutChanged?: () => void;
 };
+/**
+ * Create an app-aware pane manager that automatically constructs
+ * canvas, IME input, and terminal app instances for each pane.
+ */
 export declare function createResttyAppPaneManager(options: CreateResttyAppPaneManagerOptions): ResttyPaneManager<ResttyManagedAppPane>;

package/dist/app/panes-context-menu.d.ts

@@ -1,4 +1,13 @@
 import type { ResttyPaneContextMenuOptions, ResttyPaneDefinition, ResttyPaneManager } from "./panes-types";
+/**
+ * Context menu controller for pane right-click interactions.
+ * - element: the menu DOM node
+ * - isOpen: returns true if menu is currently visible
+ * - containsTarget: checks if an event target is inside the menu
+ * - show: displays the menu at client coordinates for a given pane
+ * - hide: hides the menu
+ * - destroy: removes the menu from the DOM
+ */
 export type PaneContextMenuController<TPane extends ResttyPaneDefinition> = {
     element: HTMLDivElement;
     isOpen: () => boolean;
@@ -7,6 +16,7 @@ export type PaneContextMenuController<TPane extends ResttyPaneDefinition> = {
     hide: () => void;
     destroy: () => void;
 };
+/** Creates a context menu controller that renders menu items, handles positioning within viewport bounds, and manages click-to-hide behavior. */
 export declare function createPaneContextMenuController<TPane extends ResttyPaneDefinition>(options: {
     contextMenu: ResttyPaneContextMenuOptions<TPane>;
     doc: Document;

package/dist/app/panes-styles.d.ts

@@ -1,6 +1,11 @@
 import type { ResttyPaneStyleOptions } from "./panes-types";
+/** Default style options for pane layout and appearance. */
 export declare const DEFAULT_RESTTY_PANE_STYLE_OPTIONS: Required<ResttyPaneStyleOptions>;
+/** Validates and normalizes pane style options, clamping numeric values to safe ranges and applying defaults. */
 export declare function normalizePaneStyleOptions(options: ResttyPaneStyleOptions): Required<ResttyPaneStyleOptions>;
+/** Injects the pane stylesheet into the document if not already present. */
 export declare function ensureResttyPaneStylesDocument(doc: Document): void;
+/** Applies pane style options to a root element via CSS custom properties. */
 export declare function applyPaneStyleOptionsToRoot(root: HTMLElement, options: Readonly<Required<ResttyPaneStyleOptions>>): void;
+/** Removes pane style class and custom properties from a root element. */
 export declare function clearPaneStyleOptionsFromRoot(root: HTMLElement): void;

package/dist/app/panes-types.d.ts

@@ -1,86 +1,175 @@
 import type { ResttyApp } from "./types";
+/**
+ * Direction for splitting a pane.
+ * - vertical: split left/right
+ * - horizontal: split top/bottom
+ */
 export type ResttyPaneSplitDirection = "vertical" | "horizontal";
+/**
+ * A single item in a pane context menu.
+ */
 export type ResttyPaneContextMenuItem = {
+    /** Display text for the menu item. */
     label: string;
+    /** Keyboard shortcut hint shown alongside the label. */
     shortcut?: string;
+    /** Whether the item is interactive (default true). */
     enabled?: boolean;
+    /** Render the item with destructive/warning styling. */
     danger?: boolean;
+    /** Callback invoked when the item is selected. */
     action: () => void | Promise<void>;
 };
+/**
+ * Minimum definition of a pane managed by the pane manager.
+ */
 export type ResttyPaneDefinition = {
+    /** Unique numeric identifier for this pane. */
     id: number;
+    /** DOM container element that holds the pane content. */
     container: HTMLDivElement;
+    /** Element to receive focus when the pane is activated. */
     focusTarget?: HTMLElement | null;
 };
+/**
+ * Configuration for pane keyboard shortcuts.
+ */
 export type ResttyPaneShortcutsOptions = {
+    /** Enable or disable shortcut handling (default true). */
     enabled?: boolean;
+    /** Guard that determines whether a keyboard event should be handled. */
     canHandleEvent?: (event: KeyboardEvent) => boolean;
+    /** Guard that determines whether the event target is an allowed input element. */
     isAllowedInputTarget?: (target: HTMLElement) => boolean;
 };
+/**
+ * Configuration for the pane right-click context menu.
+ */
 export type ResttyPaneContextMenuOptions<TPane extends ResttyPaneDefinition> = {
+    /** Guard that determines whether the context menu may open for a given event and pane. */
     canOpen?: (event: MouseEvent, pane: TPane) => boolean;
+    /** Build the list of menu items and separators for a pane. */
     getItems: (pane: TPane, manager: ResttyPaneManager<TPane>) => Array<ResttyPaneContextMenuItem | "separator">;
 };
+/**
+ * Visual styling options for pane layout and dividers.
+ */
 export type ResttyPaneStyleOptions = {
+    /** CSS background color for the split container. */
     splitBackground?: string;
+    /** CSS background color for individual panes. */
     paneBackground?: string;
+    /** Opacity applied to inactive panes (0-1). */
     inactivePaneOpacity?: number;
+    /** Opacity applied to the active pane (0-1). */
     activePaneOpacity?: number;
+    /** Duration in ms for opacity transitions between active/inactive states. */
     opacityTransitionMs?: number;
+    /** Divider/gutter thickness in CSS pixels. */
     dividerThicknessPx?: number;
 };
+/**
+ * Pane style options with an enable/disable toggle.
+ */
 export type ResttyPaneStylesOptions = ResttyPaneStyleOptions & {
+    /** Enable or disable automatic pane styling (default true). */
     enabled?: boolean;
 };
+/**
+ * Options for creating a pane manager instance.
+ */
 export type CreateResttyPaneManagerOptions<TPane extends ResttyPaneDefinition> = {
+    /** Root DOM element that contains all pane containers. */
     root: HTMLElement;
+    /** Factory function called to create a new pane. */
     createPane: (context: {
         id: number;
         sourcePane: TPane | null;
         manager: ResttyPaneManager<TPane>;
     }) => TPane;
+    /** Cleanup function called when a pane is removed. */
     destroyPane?: (pane: TPane) => void;
+    /** Called after a new pane has been created and inserted into the layout. */
     onPaneCreated?: (pane: TPane) => void;
+    /** Called after a pane has been closed and removed from the layout. */
     onPaneClosed?: (pane: TPane) => void;
+    /** Called after a pane has been split into two. */
     onPaneSplit?: (sourcePane: TPane, createdPane: TPane, direction: ResttyPaneSplitDirection) => void;
+    /** Called when the active pane changes (null when all panes are closed). */
     onActivePaneChange?: (pane: TPane | null) => void;
+    /** Called after any layout change (split, close, resize). */
     onLayoutChanged?: () => void;
+    /** Minimum pane size in CSS pixels before further splits are rejected. */
     minPaneSize?: number;
+    /** Context menu configuration, or null to disable. */
     contextMenu?: ResttyPaneContextMenuOptions<TPane> | null;
+    /** Keyboard shortcut configuration, or a boolean to enable/disable with defaults. */
     shortcuts?: boolean | ResttyPaneShortcutsOptions;
+    /** Pane styling configuration, or a boolean to enable/disable with defaults. */
     styles?: boolean | ResttyPaneStylesOptions;
 };
+/**
+ * Public API for managing a split-pane layout.
+ */
 export type ResttyPaneManager<TPane extends ResttyPaneDefinition> = {
+    /** Return all currently open panes. */
     getPanes: () => TPane[];
+    /** Look up a pane by its numeric ID, or null if not found. */
     getPaneById: (id: number) => TPane | null;
+    /** Return the currently active pane, or null if none. */
     getActivePane: () => TPane | null;
+    /** Return the pane that currently has DOM focus, or null if none. */
     getFocusedPane: () => TPane | null;
+    /** Create the first pane in an empty layout. */
     createInitialPane: (options?: {
         focus?: boolean;
     }) => TPane;
+    /** Set a pane as active by ID, optionally moving DOM focus to it. */
     setActivePane: (id: number, options?: {
         focus?: boolean;
     }) => void;
+    /** Mark a pane as focused by ID without necessarily changing the active pane. */
     markPaneFocused: (id: number, options?: {
         focus?: boolean;
     }) => void;
+    /** Split an existing pane by ID in the given direction, returning the new pane or null on failure. */
     splitPane: (id: number, direction: ResttyPaneSplitDirection) => TPane | null;
+    /** Split the currently active pane, returning the new pane or null on failure. */
     splitActivePane: (direction: ResttyPaneSplitDirection) => TPane | null;
+    /** Close a pane by ID, returning true if it was found and removed. */
     closePane: (id: number) => boolean;
+    /** Return the current resolved style options. */
     getStyleOptions: () => Readonly<Required<ResttyPaneStyleOptions>>;
+    /** Update style options and reapply them to the layout. */
     setStyleOptions: (options: ResttyPaneStyleOptions) => void;
+    /** Schedule an asynchronous layout recalculation. */
     requestLayoutSync: () => void;
+    /** Dismiss any open context menu. */
     hideContextMenu: () => void;
+    /** Tear down all panes, event listeners, and DOM structures. */
     destroy: () => void;
 };
+/**
+ * Pane definition extended with a ResttyApp instance and pause control.
+ */
 export type ResttyPaneWithApp = ResttyPaneDefinition & {
+    /** The terminal app running inside this pane. */
     app: ResttyApp;
+    /** Whether the pane's renderer is currently paused. */
     paused?: boolean;
+    /** Pause or resume this pane's renderer. */
     setPaused?: (value: boolean) => void;
 };
+/**
+ * Options for building the default set of context menu items for a pane with an app.
+ */
 export type CreateDefaultResttyPaneContextMenuItemsOptions<TPane extends ResttyPaneWithApp> = {
+    /** The pane the context menu was opened on. */
     pane: TPane;
+    /** Subset of the pane manager API needed for split/close actions. */
     manager: Pick<ResttyPaneManager<TPane>, "splitPane" | "closePane" | "getPanes">;
+    /** Platform modifier key label (e.g. "Cmd" or "Ctrl") shown in shortcut hints. */
     modKeyLabel?: string;
+    /** Provider for the current PTY URL, used for reconnect/copy-URL items. */
     getPtyUrl?: () => string | null | undefined;
 };

package/dist/app/panes.d.ts

@@ -1,5 +1,15 @@
 import type { CreateDefaultResttyPaneContextMenuItemsOptions, CreateResttyPaneManagerOptions, ResttyPaneContextMenuItem, ResttyPaneDefinition, ResttyPaneManager, ResttyPaneWithApp } from "./panes-types";
 export type { CreateDefaultResttyPaneContextMenuItemsOptions, CreateResttyPaneManagerOptions, ResttyPaneContextMenuItem, ResttyPaneContextMenuOptions, ResttyPaneDefinition, ResttyPaneManager, ResttyPaneShortcutsOptions, ResttyPaneSplitDirection, ResttyPaneStyleOptions, ResttyPaneStylesOptions, ResttyPaneWithApp, } from "./panes-types";
+/** Return the platform-appropriate shortcut modifier label ("Cmd" on macOS, "Ctrl" elsewhere). */
 export declare function getResttyShortcutModifierLabel(): "Cmd" | "Ctrl";
+/**
+ * Build the standard right-click context menu items for a pane
+ * (copy, paste, split, close, clear, PTY toggle, pause toggle).
+ */
 export declare function createDefaultResttyPaneContextMenuItems<TPane extends ResttyPaneWithApp>(options: CreateDefaultResttyPaneContextMenuItemsOptions<TPane>): Array<ResttyPaneContextMenuItem | "separator">;
+/**
+ * Create a pane manager that owns a split-pane layout inside a root
+ * element. Handles pane creation, splitting, resizing, focus
+ * tracking, keyboard shortcuts, and context menus.
+ */
 export declare function createResttyPaneManager<TPane extends ResttyPaneDefinition>(options: CreateResttyPaneManagerOptions<TPane>): ResttyPaneManager<TPane>;

package/dist/app/restty.d.ts

@@ -3,13 +3,22 @@ import type { GhosttyTheme } from "../theme";
 import { type CreateResttyAppPaneManagerOptions, type ResttyManagedAppPane, type ResttyManagedPaneStyleOptions, type ResttyPaneAppOptionsInput } from "./pane-app-manager";
 import type { ResttyPaneManager, ResttyPaneSplitDirection } from "./panes";
 import type { ResttyFontSource } from "./types";
+/**
+ * Top-level configuration for creating a Restty instance.
+ */
 export type ResttyOptions = Omit<CreateResttyAppPaneManagerOptions, "appOptions"> & {
+    /** Per-pane app options, static or factory. */
     appOptions?: CreateResttyAppPaneManagerOptions["appOptions"];
+    /** Font sources applied to every pane. */
     fontSources?: ResttyPaneAppOptionsInput["fontSources"];
+    /** Whether to create the first pane automatically (default true). */
     createInitialPane?: boolean | {
         focus?: boolean;
     };
 };
+/**
+ * Public API surface exposed by each pane handle.
+ */
 export type ResttyPaneApi = {
     id: number;
     setRenderer: (value: "auto" | "webgpu" | "webgl2") => void;
@@ -33,6 +42,11 @@ export type ResttyPaneApi = {
     getBackend: () => string;
     getRawPane: () => ResttyManagedAppPane;
 };
+/**
+ * Thin wrapper around a managed pane that delegates calls to the
+ * underlying app. Resolves the pane lazily so it stays valid across
+ * layout changes.
+ */
 export declare class ResttyPaneHandle implements ResttyPaneApi {
     private readonly resolvePane;
     constructor(resolvePane: () => ResttyManagedAppPane);
@@ -58,6 +72,11 @@ export declare class ResttyPaneHandle implements ResttyPaneApi {
     getBackend(): string;
     getRawPane(): ResttyManagedAppPane;
 }
+/**
+ * Main entry point for the restty terminal widget. Manages a set of
+ * split panes, each running its own terminal app, and exposes
+ * convenience methods that operate on the active pane.
+ */
 export declare class Restty {
     readonly paneManager: ResttyPaneManager<ResttyManagedAppPane>;
     private fontSources;
@@ -112,4 +131,5 @@ export declare class Restty {
     private requirePaneById;
     private requireActivePaneHandle;
 }
+/** Create a new Restty instance with the given options. */
 export declare function createRestty(options: ResttyOptions): Restty;

package/dist/app/session.d.ts

@@ -1,3 +1,9 @@
 import type { ResttyAppSession } from "./types";
+/**
+ * Create a new app session that lazily loads the WASM module and
+ * initializes the WebGPU core on first use. Multiple panes can
+ * share a single session to avoid duplicate resource loading.
+ */
 export declare function createResttyAppSession(): ResttyAppSession;
+/** Return the global default session, creating it on first call. */
 export declare function getDefaultResttyAppSession(): ResttyAppSession;