restty 0.1.21 → 0.1.22

package/README.md

@@ -1,6 +1,7 @@
 # restty
 
 [![Version](https://img.shields.io/npm/v/restty?style=flat-square)](https://www.npmjs.com/package/restty)
+[![Downloads](https://img.shields.io/npm/dm/restty)](https://www.npmjs.com/package/restty)
 [![Package Size](https://img.shields.io/npm/unpacked-size/restty?style=flat-square)](https://www.npmjs.com/package/restty)
 [![CI](https://img.shields.io/github/actions/workflow/status/wiedymi/restty/ci.yml?branch=main&style=flat-square)](https://github.com/wiedymi/restty/actions/workflows/ci.yml)
 [![Publish](https://img.shields.io/github/actions/workflow/status/wiedymi/restty/publish.yml?style=flat-square&label=publish)](https://github.com/wiedymi/restty/actions/workflows/publish.yml)
@@ -154,6 +155,78 @@ const restty = new Restty({
 });
 ```
 
+### Plugin system (native)
+
+Use plugins when you want to extend restty behavior without patching core.
+
+```ts
+import type { ResttyPlugin } from "restty";
+
+const metricsPlugin: ResttyPlugin = {
+  id: "example/metrics",
+  apiVersion: 1,
+  activate(ctx) {
+    const paneCreated = ctx.on("pane:created", ({ paneId }) => {
+      console.log("pane created", paneId);
+    });
+    const outgoing = ctx.addInputInterceptor(({ text }) => text.replace(/\t/g, "  "));
+    const lifecycle = ctx.addLifecycleHook(({ phase, action }) => {
+      console.log("lifecycle", phase, action);
+    });
+    return () => {
+      paneCreated.dispose();
+      outgoing.dispose();
+      lifecycle.dispose();
+    };
+  },
+};
+
+await restty.use(metricsPlugin, { sampleRate: 1 });
+console.log(restty.pluginInfo("example/metrics"));
+restty.unuse("example/metrics");
+```
+
+Declarative loading (manifest + registry):
+
+```ts
+await restty.loadPlugins(
+  [{ id: "example/metrics", options: { sampleRate: 1 } }],
+  {
+    "example/metrics": () => metricsPlugin,
+  },
+);
+```
+
+See `docs/plugins.md` for full plugin authoring details.
+
+### xterm compatibility layer
+
+For migration from xterm.js-style app code, use `restty/xterm`:
+
+```ts
+import { Terminal } from "restty/xterm";
+
+const term = new Terminal({ cols: 100, rows: 30 });
+term.open(document.getElementById("terminal") as HTMLElement);
+
+term.onData((data) => console.log("input", data));
+term.onResize(({ cols, rows }) => console.log("resize", cols, rows));
+
+term.write("hello");
+term.writeln(" world");
+term.resize(120, 40);
+term.loadAddon({
+  activate() {},
+  dispose() {},
+});
+```
+
+Compatibility scope:
+
+- Good for common embed/migration flows.
+- Not full xterm internals parity (buffer/parser/marker ecosystem APIs are not all implemented).
+- Prefer native `Restty` API for long-term integrations.
+
 ## API Snapshot
 
 Primary class:
@@ -161,6 +234,11 @@ Primary class:
 - `new Restty({ root, ...options })`
 - `createRestty(options)`
 
+Xterm compatibility:
+
+- `import { Terminal } from "restty/xterm"`
+- Supports `open`, `write`, `writeln`, `resize`, `focus`, `blur`, `clear`, `reset`, `onData`, `onResize`, `options`, `loadAddon`, `dispose`
+
 Pane access:
 
 - `panes()` / `pane(id)` / `activePane()` / `focusedPane()` / `forEachPane(visitor)`
@@ -175,9 +253,15 @@ Active-pane convenience:
 - `setMouseMode("auto" | "on" | "off")`
 - `sendInput(text)` / `sendKeyInput(text)`
 - `copySelectionToClipboard()` / `pasteFromClipboard()`
+- `resize(cols, rows)` / `focus()` / `blur()`
 - `updateSize(force?)`
 - `destroy()`
 
+Plugin host:
+
+- `use(plugin, options?)` / `loadPlugins(manifest, registry)` / `unuse(pluginId)` / `plugins()` / `pluginInfo(pluginId?)`
+- plugin context supports `on(...)`, `addInputInterceptor(...)`, `addOutputInterceptor(...)`, `addLifecycleHook(...)`, `addRenderHook(...)`
+
 ## Advanced / Internal Modules
 
 Use these only when you need lower-level control:
@@ -214,6 +298,7 @@ bun run pty           # PTY websocket server only
 
 - `docs/README.md` - docs index
 - `docs/usage.md` - practical integration guide
+- `docs/xterm-compat.md` - xterm migration shim
 - `docs/how-it-works.md` - runtime flow
 - `docs/internals/` - implementation notes and architecture
 - `THIRD_PARTY_NOTICES.md` - third-party credits and notices

package/dist/app/clipboard-paste.d.ts

@@ -0,0 +1,5 @@
+export type ResttyPastePayload = {
+    kind: "text";
+    text: string;
+};
+export declare function readPastePayloadFromDataTransfer(dataTransfer: DataTransfer | null | undefined): ResttyPastePayload | null;

package/dist/app/index.d.ts

@@ -2,7 +2,8 @@ import type { ResttyApp, ResttyAppOptions } from "./types";
 export { createResttyAppSession, getDefaultResttyAppSession } from "./session";
 export { createResttyPaneManager, createDefaultResttyPaneContextMenuItems, getResttyShortcutModifierLabel, } from "./panes";
 export { Restty } from "./restty";
-export type { ResttyAppElements, ResttyAppCallbacks, FontSource, ResttyFontSource, ResttyTouchSelectionMode, ResttyUrlFontSource, ResttyBufferFontSource, ResttyLocalFontSource, ResttyWasmLogListener, ResttyAppSession, ResttyAppOptions, ResttyApp, } from "./types";
+export { RESTTY_PLUGIN_API_VERSION } from "./restty";
+export type { ResttyAppElements, ResttyAppCallbacks, FontSource, ResttyFontSource, ResttyTouchSelectionMode, ResttyUrlFontSource, ResttyBufferFontSource, ResttyLocalFontSource, ResttyWasmLogListener, ResttyAppSession, ResttyAppInputPayload, ResttyAppOptions, ResttyApp, } from "./types";
 export type { ResttyPaneSplitDirection, ResttyPaneContextMenuItem, ResttyPaneDefinition, ResttyPaneStyleOptions, ResttyPaneStylesOptions, ResttyPaneShortcutsOptions, ResttyPaneContextMenuOptions, CreateResttyPaneManagerOptions, ResttyPaneManager, ResttyPaneWithApp, CreateDefaultResttyPaneContextMenuItemsOptions, } from "./panes";
-export type { ResttyOptions } from "./restty";
+export type { ResttyOptions, ResttyPluginApiRange, ResttyPlugin, ResttyPluginCleanup, ResttyPluginContext, ResttyPluginDisposable, ResttyPluginEvents, ResttyPluginInfo, ResttyPluginRequires, ResttyInputInterceptor, ResttyInputInterceptorPayload, ResttyInterceptorOptions, ResttyLifecycleHook, ResttyLifecycleHookPayload, ResttyPluginLoadResult, ResttyPluginLoadStatus, ResttyPluginManifestEntry, ResttyPluginRegistry, ResttyPluginRegistryEntry, ResttyRenderHook, ResttyRenderHookPayload, ResttyOutputInterceptor, ResttyOutputInterceptorPayload, } from "./restty";
 export declare function createResttyApp(options: ResttyAppOptions): ResttyApp;

package/dist/app/restty.d.ts

@@ -16,6 +16,158 @@ export type ResttyOptions = Omit<CreateResttyAppPaneManagerOptions, "appOptions"
         focus?: boolean;
     };
 };
+/** Current Restty plugin API version. */
+export declare const RESTTY_PLUGIN_API_VERSION = 1;
+/** Plugin API version requirements. */
+export type ResttyPluginApiRange = {
+    min: number;
+    max?: number;
+};
+/** Optional compatibility requirements declared by plugins. */
+export type ResttyPluginRequires = {
+    pluginApi?: number | ResttyPluginApiRange;
+};
+/** Diagnostics snapshot for a plugin. */
+export type ResttyPluginInfo = {
+    id: string;
+    version: string | null;
+    apiVersion: number | null;
+    requires: ResttyPluginRequires | null;
+    active: boolean;
+    activatedAt: number | null;
+    lastError: string | null;
+    listeners: number;
+    inputInterceptors: number;
+    outputInterceptors: number;
+    lifecycleHooks: number;
+    renderHooks: number;
+};
+/** Declarative plugin manifest entry for registry-based loading. */
+export type ResttyPluginManifestEntry = {
+    id: string;
+    enabled?: boolean;
+    options?: unknown;
+};
+/** Provider entry for plugin registry lookups. */
+export type ResttyPluginRegistryEntry = ResttyPlugin | (() => ResttyPlugin | Promise<ResttyPlugin>);
+/** Registry shape accepted by loadPlugins. */
+export type ResttyPluginRegistry = ReadonlyMap<string, ResttyPluginRegistryEntry> | Record<string, ResttyPluginRegistryEntry>;
+/** Status for manifest-driven plugin load attempts. */
+export type ResttyPluginLoadStatus = "loaded" | "skipped" | "missing" | "failed";
+/** Result row returned by loadPlugins. */
+export type ResttyPluginLoadResult = {
+    id: string;
+    status: ResttyPluginLoadStatus;
+    error: string | null;
+};
+/** Event payloads emitted by the Restty plugin host. */
+export type ResttyPluginEvents = {
+    "plugin:activated": {
+        pluginId: string;
+    };
+    "plugin:deactivated": {
+        pluginId: string;
+    };
+    "pane:created": {
+        paneId: number;
+    };
+    "pane:closed": {
+        paneId: number;
+    };
+    "pane:split": {
+        sourcePaneId: number;
+        createdPaneId: number;
+        direction: ResttyPaneSplitDirection;
+    };
+    "pane:active-changed": {
+        paneId: number | null;
+    };
+    "layout:changed": {};
+    "pane:resized": {
+        paneId: number;
+        cols: number;
+        rows: number;
+    };
+    "pane:focused": {
+        paneId: number;
+    };
+    "pane:blurred": {
+        paneId: number;
+    };
+};
+/** A disposable resource returned by plugin APIs. */
+export type ResttyPluginDisposable = {
+    dispose: () => void;
+};
+/** Optional cleanup return supported by plugin activation. */
+export type ResttyPluginCleanup = void | (() => void) | ResttyPluginDisposable;
+/** Payload passed to input interceptors before terminal/program input is written. */
+export type ResttyInputInterceptorPayload = {
+    paneId: number;
+    text: string;
+    source: string;
+};
+/** Payload passed to output interceptors before PTY data is rendered. */
+export type ResttyOutputInterceptorPayload = {
+    paneId: number;
+    text: string;
+    source: string;
+};
+/** Input interceptor contract. */
+export type ResttyInputInterceptor = (payload: ResttyInputInterceptorPayload) => string | null | void;
+/** Output interceptor contract. */
+export type ResttyOutputInterceptor = (payload: ResttyOutputInterceptorPayload) => string | null | void;
+/** Payload passed to lifecycle hooks registered by plugins. */
+export type ResttyLifecycleHookPayload = {
+    phase: "before" | "after";
+    action: "create-initial-pane" | "split-active-pane" | "split-pane" | "close-pane" | "set-active-pane" | "mark-pane-focused" | "connect-pty" | "disconnect-pty" | "resize" | "focus" | "blur";
+    paneId?: number | null;
+    sourcePaneId?: number;
+    createdPaneId?: number | null;
+    direction?: ResttyPaneSplitDirection;
+    cols?: number;
+    rows?: number;
+    ok?: boolean;
+    error?: string | null;
+};
+/** Lifecycle hook contract. */
+export type ResttyLifecycleHook = (payload: ResttyLifecycleHookPayload) => void;
+/** Payload passed to render hooks registered by plugins. */
+export type ResttyRenderHookPayload = {
+    phase: "before" | "after";
+    paneId: number;
+    text: string;
+    source: string;
+    dropped: boolean;
+};
+/** Render hook contract. */
+export type ResttyRenderHook = (payload: ResttyRenderHookPayload) => void;
+/** Shared options for interceptor ordering. */
+export type ResttyInterceptorOptions = {
+    priority?: number;
+};
+/** Context object provided to each plugin on activation. */
+export type ResttyPluginContext = {
+    restty: Restty;
+    options: unknown;
+    panes: () => ResttyPaneHandle[];
+    pane: (id: number) => ResttyPaneHandle | null;
+    activePane: () => ResttyPaneHandle | null;
+    focusedPane: () => ResttyPaneHandle | null;
+    on: <E extends keyof ResttyPluginEvents>(event: E, listener: (payload: ResttyPluginEvents[E]) => void) => ResttyPluginDisposable;
+    addInputInterceptor: (interceptor: ResttyInputInterceptor, options?: ResttyInterceptorOptions) => ResttyPluginDisposable;
+    addOutputInterceptor: (interceptor: ResttyOutputInterceptor, options?: ResttyInterceptorOptions) => ResttyPluginDisposable;
+    addLifecycleHook: (hook: ResttyLifecycleHook, options?: ResttyInterceptorOptions) => ResttyPluginDisposable;
+    addRenderHook: (hook: ResttyRenderHook, options?: ResttyInterceptorOptions) => ResttyPluginDisposable;
+};
+/** Plugin contract for extending Restty behavior. */
+export type ResttyPlugin = {
+    id: string;
+    version?: string;
+    apiVersion?: number;
+    requires?: ResttyPluginRequires;
+    activate: (context: ResttyPluginContext, options?: unknown) => ResttyPluginCleanup | Promise<ResttyPluginCleanup>;
+};
 /**
  * Public API surface exposed by each pane handle.
  */
@@ -38,6 +190,9 @@ export type ResttyPaneApi = {
     copySelectionToClipboard: () => Promise<boolean>;
     pasteFromClipboard: () => Promise<boolean>;
     dumpAtlasForCodepoint: (cp: number) => void;
+    resize: (cols: number, rows: number) => void;
+    focus: () => void;
+    blur: () => void;
     updateSize: (force?: boolean) => void;
     getBackend: () => string;
     getRawPane: () => ResttyManagedAppPane;
@@ -68,6 +223,9 @@ export declare class ResttyPaneHandle implements ResttyPaneApi {
     copySelectionToClipboard(): Promise<boolean>;
     pasteFromClipboard(): Promise<boolean>;
     dumpAtlasForCodepoint(cp: number): void;
+    resize(cols: number, rows: number): void;
+    focus(): void;
+    blur(): void;
     updateSize(force?: boolean): void;
     getBackend(): string;
     getRawPane(): ResttyManagedAppPane;
@@ -80,6 +238,15 @@ export declare class ResttyPaneHandle implements ResttyPaneApi {
 export declare class Restty {
     readonly paneManager: ResttyPaneManager<ResttyManagedAppPane>;
     private fontSources;
+    private readonly pluginListeners;
+    private readonly pluginRuntimes;
+    private readonly pluginDiagnostics;
+    private readonly inputInterceptors;
+    private readonly outputInterceptors;
+    private readonly lifecycleHooks;
+    private readonly renderHooks;
+    private nextInterceptorId;
+    private nextInterceptorOrder;
     constructor(options: ResttyOptions);
     getPanes(): ResttyManagedAppPane[];
     getPaneById(id: number): ResttyManagedAppPane | null;
@@ -107,6 +274,12 @@ export declare class Restty {
     }): void;
     requestLayoutSync(): void;
     hideContextMenu(): void;
+    use(plugin: ResttyPlugin, options?: unknown): Promise<void>;
+    loadPlugins(manifest: ReadonlyArray<ResttyPluginManifestEntry>, registry: ResttyPluginRegistry): Promise<ResttyPluginLoadResult[]>;
+    unuse(pluginId: string): boolean;
+    plugins(): string[];
+    pluginInfo(pluginId: string): ResttyPluginInfo | null;
+    pluginInfo(): ResttyPluginInfo[];
     destroy(): void;
     connectPty(url?: string): void;
     disconnectPty(): void;
@@ -125,11 +298,39 @@ export declare class Restty {
     copySelectionToClipboard(): Promise<boolean>;
     pasteFromClipboard(): Promise<boolean>;
     dumpAtlasForCodepoint(cp: number): void;
+    resize(cols: number, rows: number): void;
+    focus(): void;
+    blur(): void;
     updateSize(force?: boolean): void;
     getBackend(): string;
     private makePaneHandle;
     private requirePaneById;
     private requireActivePaneHandle;
+    private createPluginContext;
+    private attachRuntimeDisposer;
+    private addInputInterceptor;
+    private addOutputInterceptor;
+    private addLifecycleHook;
+    private addRenderHook;
+    private registerInterceptor;
+    private applyInputInterceptors;
+    private applyOutputInterceptors;
+    private runLifecycleHooks;
+    private runRenderHooks;
+    private applyInterceptors;
+    private runHooks;
+    private normalizePluginMetadata;
+    private assertPluginCompatibility;
+    private lookupPluginRegistryEntry;
+    private resolvePluginRegistryEntry;
+    private setPluginLoadError;
+    private updatePluginDiagnostic;
+    private buildPluginInfo;
+    private errorToMessage;
+    private onPluginEvent;
+    private emitPluginEvent;
+    private teardownPluginRuntime;
+    private normalizePluginCleanup;
 }
 /** Create a new Restty instance with the given options. */
 export declare function createRestty(options: ResttyOptions): Restty;

package/dist/app/types.d.ts

@@ -136,6 +136,11 @@ export type ResttyFontPreset = "default-cdn" | "none";
  * - off: disable touch selection entirely
  */
 export type ResttyTouchSelectionMode = "drag" | "long-press" | "off";
+/** Input payload passed to ResttyApp before-input hooks. */
+export type ResttyAppInputPayload = {
+    text: string;
+    source: string;
+};
 /**
  * Options for creating a ResttyApp instance.
  */
@@ -207,6 +212,16 @@ export type ResttyAppOptions = {
     debugExpose?: boolean;
     /** PTY transport layer for terminal I/O. */
     ptyTransport?: PtyTransport;
+    /**
+     * Optional hook to transform or suppress terminal/program input
+     * before it is written to the terminal core.
+     */
+    beforeInput?: (payload: ResttyAppInputPayload) => string | null | void;
+    /**
+     * Optional hook to transform or suppress PTY output before it is
+     * queued for rendering.
+     */
+    beforeRenderOutput?: (payload: ResttyAppInputPayload) => string | null | void;
 };
 /**
  * Public API for a terminal app instance.
@@ -252,6 +267,12 @@ export type ResttyApp = {
     pasteFromClipboard: () => Promise<boolean>;
     /** Dump the glyph atlas entry for a given Unicode codepoint. */
     dumpAtlasForCodepoint: (cp: number) => void;
+    /** Resize terminal grid to explicit columns/rows. */
+    resize: (cols: number, rows: number) => void;
+    /** Focus terminal input targets. */
+    focus: () => void;
+    /** Blur terminal input targets. */
+    blur: () => void;
     /** Recalculate terminal dimensions from the canvas size. */
     updateSize: (force?: boolean) => void;
     /** Return the name of the active renderer backend. */