cmux 0.3.6 → 0.4.0

package/dist/src/protocol/commands.js

@@ -0,0 +1 @@
+export {};

package/dist/src/protocol/common.d.ts

@@ -0,0 +1,74 @@
+/** A JSON value accepted by the cmux-tui protocol. */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** A JSON object accepted by the cmux-tui protocol. */
+export type JsonObject = {
+    [key: string]: Json;
+};
+/** An implemented numeric protocol identifier (`uint64` on the wire). */
+export type Id = number;
+/** A numeric id or proposed stable short id. */
+export type IdRef = Id | string;
+/** Standard base64 text. */
+export type Base64 = string;
+/** A `#rrggbb` color string. */
+export type ColorHex = `#${string}`;
+/** A terminal cell grid. */
+export interface Size {
+    cols: number;
+    rows: number;
+}
+/** The canonical empty command result. */
+export type EmptyResult = Record<string, never>;
+/** Fields common to every command request envelope. */
+export interface CmuxRequestBase {
+    id?: Json;
+    cmd: string;
+}
+/** A successful command response envelope. */
+export interface CmuxSuccessResponse<T = Json> {
+    id?: Json;
+    ok: true;
+    data: T;
+}
+export type CmuxErrorDelivery = "known-not-delivered" | "ambiguous";
+/** A failed command response envelope. */
+export interface CmuxFailureResponse {
+    id?: Json;
+    ok: false;
+    error: string;
+    /** Additive machine-readable classification for expected command failures. */
+    error_code?: string;
+    error_delivery?: CmuxErrorDelivery;
+}
+/** The canonical command response envelope. */
+export type CmuxResponse<T = Json> = CmuxSuccessResponse<T> | CmuxFailureResponse;
+/** Split orientation used by canonical and declarative layouts. */
+export type SplitDirection = "right" | "down";
+/** Four-way pane navigation direction. */
+export type PaneDirection = "left" | "right" | "up" | "down";
+/** Notification severity. */
+export type NotificationLevel = "info" | "warning" | "error";
+/** An agent's reported lifecycle state. */
+export type AgentState = "working" | "blocked" | "idle" | "done" | "unknown";
+/** The authority that produced an agent record. */
+export type AgentSource = "detected" | "socket" | "hook";
+/** A source accepted by `report-agent`. */
+export type AgentReportSource = "socket" | "hook";
+/** One authoritative agent status record. */
+export interface AgentRecord {
+    surface: Id;
+    state: AgentState;
+    source: AgentSource;
+    session: string | null;
+    updated_at_ms: number;
+}
+/** One posted mux notification. */
+export interface Notification {
+    notification: Id;
+    title: string;
+    body: string;
+    level: NotificationLevel;
+    surface: Id | null;
+}

package/dist/src/protocol/common.js

@@ -0,0 +1 @@
+export {};

package/dist/src/protocol/events.d.ts

@@ -0,0 +1,349 @@
+import type { AgentSource, AgentState, Base64, ColorHex, Id, NotificationLevel } from "./common.js";
+import type { ClientTransport } from "./commands.js";
+import type { RenderDeltaEvent, RenderStateEvent } from "./render.js";
+import type { Pane, Screen, Tab, Workspace } from "./tree.js";
+export interface TreeChangedEvent {
+    event: "tree-changed";
+}
+export interface LayoutChangedEvent {
+    event: "layout-changed";
+    screen: Id;
+}
+export interface SurfaceOutputEvent {
+    event: "surface-output";
+    surface: Id;
+}
+/** `offset` is the row offset used by the scrollbar geometry. */
+export interface ScrollChangedEvent {
+    event: "scroll-changed";
+    surface: Id;
+    offset: number;
+    at_bottom: boolean;
+}
+export interface SurfaceResizedEvent {
+    event: "surface-resized";
+    surface: Id;
+    cols: number;
+    rows: number;
+    reservation_id?: number | null;
+}
+export interface SurfaceResizeFailedEvent {
+    event: "surface-resize-failed";
+    surface: Id;
+    cols: number;
+    rows: number;
+    error: string;
+    retry_after_ms: number | null;
+    reservation_id?: number | null;
+}
+export interface SurfaceExitedEvent {
+    event: "surface-exited";
+    surface: Id;
+}
+export interface TitleChangedEvent {
+    event: "title-changed";
+    surface: Id;
+    title?: string;
+}
+export interface BellEvent {
+    event: "bell";
+    surface: Id;
+}
+export interface NotificationEvent {
+    event: "notification";
+    notification: Id;
+    title: string;
+    body: string;
+    level: NotificationLevel;
+    surface: Id | null;
+}
+export interface ConfigReloadRequestedEvent {
+    event: "config-reload-requested";
+}
+export interface WindowTitleRequestedEvent {
+    event: "window-title-requested";
+    title: string;
+}
+export interface ClientAttachedEvent {
+    event: "client-attached";
+    client: Id;
+    transport: ClientTransport;
+    name: string | null;
+    kind: string | null;
+}
+export interface ClientChangedEvent {
+    event: "client-changed";
+    client: Id;
+    name: string | null;
+    kind: string | null;
+}
+export interface ClientDetachedEvent {
+    event: "client-detached";
+    client: Id;
+}
+export interface TerminalRegistryChangedEvent {
+    event: "terminal-registry-changed";
+    registry_id: string;
+    generation: string;
+    terminal_revision: number;
+    refetch: "terminal-events-or-list-terminals";
+}
+export interface EmptyEvent {
+    event: "empty";
+}
+export interface WorkspaceAddedEvent {
+    event: "workspace-added";
+    workspace: Id;
+    index: number;
+    /** Absent when the server does not advertise `workspace-registry-v1`. */
+    workspace_revision?: number;
+    entity: Workspace;
+}
+export interface WorkspaceClosedEvent {
+    event: "workspace-closed";
+    workspace: Id;
+    index: number;
+    /** Absent when the server does not advertise `workspace-registry-v1`. */
+    workspace_revision?: number;
+    entity: Workspace;
+}
+export interface WorkspaceRenamedEvent {
+    event: "workspace-renamed";
+    workspace: Id;
+    /** Absent when the server does not advertise `workspace-registry-v1`. */
+    workspace_revision?: number;
+    entity: Workspace;
+}
+export interface WorkspaceMovedEvent {
+    event: "workspace-moved";
+    workspace: Id;
+    index: number;
+    workspace_revision: number;
+    entity: Workspace & {
+        key: string;
+    };
+}
+export interface ScreenAddedEvent {
+    event: "screen-added";
+    workspace: Id;
+    screen: Id;
+    index: number;
+    entity: Screen;
+}
+export interface ScreenClosedEvent {
+    event: "screen-closed";
+    workspace: Id;
+    screen: Id;
+    index: number;
+    entity: Screen;
+}
+export interface ScreenRenamedEvent {
+    event: "screen-renamed";
+    workspace: Id;
+    screen: Id;
+    entity: Screen;
+}
+export interface PaneAddedEvent {
+    event: "pane-added";
+    workspace: Id;
+    screen: Id;
+    pane: Id;
+    index: number;
+    entity: Pane;
+}
+export interface PaneClosedEvent {
+    event: "pane-closed";
+    workspace: Id;
+    screen: Id;
+    pane: Id;
+    index: number;
+    entity: Pane;
+}
+export interface TabAddedEvent {
+    event: "tab-added";
+    workspace: Id;
+    screen: Id;
+    pane: Id;
+    surface: Id;
+    index: number;
+    entity: Tab;
+}
+export interface TabClosedEvent {
+    event: "tab-closed";
+    workspace: Id;
+    screen: Id;
+    pane: Id;
+    surface: Id;
+    index: number;
+    entity: Tab;
+}
+export interface TabRenamedEvent {
+    event: "tab-renamed";
+    workspace: Id;
+    screen: Id;
+    pane: Id;
+    surface: Id;
+    entity: Tab;
+}
+/** Protocol v7 tree lifecycle deltas. */
+export type TreeDeltaEvent = WorkspaceAddedEvent | WorkspaceClosedEvent | WorkspaceRenamedEvent | WorkspaceMovedEvent | ScreenAddedEvent | ScreenClosedEvent | ScreenRenamedEvent | PaneAddedEvent | PaneClosedEvent | TabAddedEvent | TabClosedEvent | TabRenamedEvent;
+/** Effective special colors for an attached terminal surface. */
+export interface TerminalColors {
+    fg: ColorHex | null;
+    bg: ColorHex | null;
+    cursor: ColorHex | null;
+    selection_bg: ColorHex | null;
+    selection_fg: ColorHex | null;
+    /** Protocol v6 additive extension. Older servers omit this field. */
+    cursor_style?: "block" | "underline" | "bar" | null;
+    /** Protocol v6 additive extension. Older servers omit this field. */
+    cursor_blink?: boolean | null;
+    /** Protocol v7 sparse application-authored OSC 4 overrides by palette index. */
+    palette?: Record<string, ColorHex>;
+}
+/** Initial base64 VT replay for an attached PTY surface. */
+export interface VtStateEvent {
+    event: "vt-state";
+    surface: Id;
+    cols: number;
+    rows: number;
+    data: Base64;
+    /** Protocol v6 additive extension. Older servers omit this field. */
+    colors?: TerminalColors;
+}
+/** Live base64 PTY bytes after the attach snapshot. */
+export interface OutputEvent {
+    event: "output";
+    surface: Id;
+    data: Base64;
+    /** Present when output and its complete color state are one transition. */
+    colors?: TerminalColors;
+}
+interface ResizedEventBase {
+    event: "resized";
+    surface: Id;
+    cols: number;
+    rows: number;
+    /** Protocol v7 theme-portable color snapshot for the replacement replay. Older servers omit it. */
+    colors?: TerminalColors;
+}
+/** A replacement replay using the protocol-v7 field or protocol-v6 compatibility field. */
+export type ResizedEvent = ResizedEventBase & ({
+    replay: Base64;
+    data?: Base64;
+} | {
+    data: Base64;
+    replay?: Base64;
+});
+export interface DetachedEvent {
+    event: "detached";
+    surface: Id;
+}
+export interface OverflowEvent {
+    event: "overflow";
+    error: string;
+    scope?: "surface";
+    surface?: Id;
+}
+/** Updated effective special colors for this attach stream's surface. */
+export interface ColorsChangedEvent extends TerminalColors {
+    event: "colors-changed";
+    /** Protocol v7 adds the subject id; protocol v6 servers omit it. */
+    surface?: Id;
+}
+export interface BrowserFrame {
+    seq: number;
+    /** CSS viewport width used for browser input mapping, or 0 when CDP omits it. */
+    width: number;
+    /** CSS viewport height used for browser input mapping, or 0 when CDP omits it. */
+    height: number;
+    /** Encoded PNG width. Older servers omit this field. */
+    image_width?: number;
+    /** Encoded PNG height. Older servers omit this field. */
+    image_height?: number;
+    data: Base64;
+}
+export interface BrowserStateEvent {
+    event: "browser-state";
+    surface: Id;
+    cols: number;
+    rows: number;
+    url: string;
+    title: string;
+    status: string;
+    error: string | null;
+    frames_stalled: boolean;
+    frame?: BrowserFrame | null;
+}
+export interface BrowserFrameEvent extends BrowserFrame {
+    event: "frame";
+    surface: Id;
+}
+/** Proposed event retained for forward-compatible protocol v6 clients. */
+export interface AgentStateChangedEvent {
+    event: "agent-state-changed";
+    surface: Id;
+    previous: AgentState | null;
+    state: AgentState;
+    source: AgentSource;
+    session: string | null;
+    updated_at_ms: number;
+}
+/** Proposed notification event shape with its creation timestamp. */
+export interface ProposedNotificationEvent extends NotificationEvent {
+    created_at_ms: number;
+}
+/** A forward-compatible event that is not known to this SDK version. */
+export interface UnknownEvent {
+    event: string;
+    [key: string]: unknown;
+}
+/** All currently implemented subscribe event payloads. */
+export type KnownSubscribeEvent = TreeDeltaEvent | TreeChangedEvent | LayoutChangedEvent | SurfaceOutputEvent | ScrollChangedEvent | SurfaceResizedEvent | SurfaceResizeFailedEvent | SurfaceExitedEvent | TitleChangedEvent | BellEvent | NotificationEvent | ConfigReloadRequestedEvent | WindowTitleRequestedEvent | ClientAttachedEvent | ClientChangedEvent | ClientDetachedEvent | TerminalRegistryChangedEvent | EmptyEvent | OverflowEvent;
+/** Subscribe events, including unknown future event names. */
+export type SubscribeEvent = KnownSubscribeEvent | UnknownEvent;
+/** All currently implemented attach event payloads. */
+export type KnownAttachEvent = VtStateEvent | OutputEvent | ResizedEvent | ColorsChangedEvent | BrowserStateEvent | BrowserFrameEvent | RenderStateEvent | RenderDeltaEvent | ScrollChangedEvent | DetachedEvent | OverflowEvent;
+/** Wire-format attach events, including unknown future event names. */
+export type AttachEvent = KnownAttachEvent | UnknownEvent;
+/** Every known implemented subscribe or attach event. */
+export type KnownCmuxEvent = KnownSubscribeEvent | KnownAttachEvent | AgentStateChangedEvent | ProposedNotificationEvent;
+/** Every cmux event, discriminated by `event`, with an unknown-event fallback. */
+export type CmuxEvent = KnownCmuxEvent | UnknownEvent;
+/** A decoded initial replay yielded by `attachSurface()`. */
+export interface DecodedVtStateEvent extends Omit<VtStateEvent, "data"> {
+    data: Uint8Array;
+}
+/** Decoded live PTY bytes yielded by `attachSurface()`. */
+export interface DecodedOutputEvent extends Omit<OutputEvent, "data"> {
+    data: Uint8Array;
+}
+/** A decoded replacement replay yielded by `attachSurface()`. */
+export interface DecodedResizedEvent extends Omit<ResizedEvent, "data" | "replay"> {
+    data: Uint8Array;
+    /** @deprecated Use `data`. Retained for compatibility with early protocol-v6 SDK builds. */
+    replay: Uint8Array;
+}
+/** A special-color update yielded by `attachSurface()`. */
+export type DecodedColorsChangedEvent = ColorsChangedEvent;
+/** Browser frame dimensions after the client fills legacy CSS-size defaults. */
+export interface DecodedBrowserFrame extends BrowserFrame {
+    image_width: number;
+    image_height: number;
+}
+/** A browser-state event whose optional frame has normalized image dimensions. */
+export interface DecodedBrowserStateEvent extends Omit<BrowserStateEvent, "frame"> {
+    frame?: DecodedBrowserFrame | null;
+}
+/** A frame event with normalized image dimensions. */
+export interface DecodedBrowserFrameEvent extends BrowserFrameEvent {
+    image_width: number;
+    image_height: number;
+}
+/** Attach events as yielded by the client after base64 decoding. */
+export type DecodedAttachEvent = DecodedVtStateEvent | DecodedOutputEvent | DecodedResizedEvent | DecodedColorsChangedEvent | DecodedBrowserStateEvent | DecodedBrowserFrameEvent | ScrollChangedEvent | DetachedEvent | OverflowEvent | UnknownEvent;
+/** Known events yielded by a protocol v7 render attachment. */
+export type KnownRenderAttachEvent = RenderStateEvent | RenderDeltaEvent | ScrollChangedEvent | DetachedEvent | OverflowEvent;
+/** Render attachment events, including unknown future event names. */
+export type RenderAttachEvent = KnownRenderAttachEvent | UnknownEvent;
+export {};

package/dist/src/protocol/events.js

@@ -0,0 +1 @@
+export {};

package/dist/src/protocol/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./common.js";
+export * from "./tree.js";
+export * from "./render.js";
+export * from "./commands.js";
+export * from "./events.js";

package/dist/src/protocol/index.js

@@ -0,0 +1,5 @@
+export * from "./common.js";
+export * from "./tree.js";
+export * from "./render.js";
+export * from "./commands.js";
+export * from "./events.js";

package/dist/src/protocol/render.d.ts

@@ -0,0 +1,49 @@
+import type { ColorHex, Id, Size } from "./common.js";
+/** Exact underline style for a terminal render run. */
+export type RenderUnderline = "single" | "double" | "curly" | "dotted" | "dashed";
+/** One maximally coalesced span of styled terminal cells. */
+export interface RenderRun {
+    text: string;
+    fg: ColorHex | null;
+    bg: ColorHex | null;
+    attrs: number;
+    underline?: RenderUnderline;
+    width_hint?: number;
+}
+/** One zero-based row in a viewport or scrollback page. */
+export interface RenderRow {
+    row: number;
+    runs: RenderRun[];
+}
+/** Authoritative terminal cursor state for a render frame. */
+export interface RenderCursor {
+    x: number;
+    y: number;
+    style: "block" | "underline" | "bar";
+    blink: boolean;
+    visible: boolean;
+    color: ColorHex | null;
+}
+/** Initial complete viewport snapshot for a render attachment. */
+export interface RenderStateEvent {
+    event: "render-state";
+    surface: Id;
+    size: Size;
+    cursor: RenderCursor;
+    default_fg: ColorHex;
+    default_bg: ColorHex;
+    scrollback_rows: number;
+    rows: RenderRow[];
+}
+/** One render frame containing dirty rows or a full viewport replacement. */
+export interface RenderDeltaEvent {
+    event: "render-delta";
+    surface: Id;
+    cursor: RenderCursor;
+    full: boolean;
+    size?: Size;
+    default_fg?: ColorHex;
+    default_bg?: ColorHex;
+    scrollback_rows?: number;
+    rows: RenderRow[];
+}

package/dist/src/protocol/render.js

@@ -0,0 +1 @@
+export {};

package/dist/src/protocol/tree.d.ts

@@ -0,0 +1,95 @@
+import type { Id, Size, SplitDirection } from "./common.js";
+/** The canonical pane split tree. */
+export type Layout = {
+    type: "leaf";
+    pane: Id;
+} | {
+    type: "split";
+    /** Stable split id. Absent only when connected to a pre-v8 server. */
+    split?: Id;
+    dir: SplitDirection;
+    ratio: number;
+    a: Layout;
+    b: Layout;
+} | {
+    type: "stack";
+    panes: [Id, ...Id[]];
+    expanded: Id;
+};
+/** A declarative split tree used by `apply-layout`. */
+export type DeclarativeLayout = {
+    type: "leaf";
+    cwd?: string | null;
+    command?: string[] | null;
+} | {
+    type: "split";
+    dir: SplitDirection;
+    ratio: number;
+    a: DeclarativeLayout;
+    b: DeclarativeLayout;
+} | {
+    type: "stack";
+    panes: [Id, ...Id[]];
+    expanded: Id;
+};
+/** A live PTY or browser tab. */
+export interface Tab {
+    surface: Id;
+    kind: "pty" | "browser";
+    browser_source: "external" | "launched" | null;
+    name: string | null;
+    title: string;
+    size: Size | null;
+    dead: boolean;
+}
+/** A live pane containing tabs. */
+export interface LivePane {
+    id: Id;
+    name: string | null;
+    active_tab: number;
+    focused_at?: number;
+    tabs: Tab[];
+}
+/** A defensive placeholder for a tree leaf whose pane state is missing. */
+export interface DeadPane {
+    id: Id;
+    dead: true;
+}
+/** A pane in a tree snapshot. */
+export type Pane = LivePane | DeadPane;
+/** One appended horizontal viewport column and its frontend-relative width. */
+export interface ViewportSplit {
+    split: Id;
+    width: number;
+}
+/** A named split-tree screen. */
+export interface Screen {
+    id: Id;
+    name: string | null;
+    active: boolean;
+    active_pane: Id;
+    zoomed_pane: Id | null;
+    layout: Layout;
+    /** First viewport column width; absent on ordinary tiled screens. */
+    viewport_base_width?: number;
+    /** Appended viewport columns; absent on ordinary tiled screens. */
+    viewport_splits?: ViewportSplit[];
+    panes: Pane[];
+}
+/** A workspace containing one or more screens. */
+export interface Workspace {
+    id: Id;
+    /** Stable registry key. Absent without the `workspace-registry-v1` capability. */
+    key?: string;
+    name: string;
+    active: boolean;
+    screens: Screen[];
+}
+/** The complete workspace, screen, pane, tab, and layout snapshot. */
+export interface Tree {
+    /** Ordered-registry revision. Absent without the `workspace-registry-v1` capability. */
+    workspace_revision?: number;
+    /** Live pane-membership revision. Absent on older servers. */
+    pane_revision?: number;
+    workspaces: Workspace[];
+}

package/dist/src/protocol/tree.js

@@ -0,0 +1 @@
+export {};

package/dist/src/transport.d.ts

@@ -0,0 +1,15 @@
+/** Removes a transport event listener. */
+export type Unsubscribe = () => void;
+/** Transport-independent delivery of complete JSON messages. */
+export interface Transport {
+    /** Sends one complete JSON message. */
+    send(json: string): void;
+    /** Observes one complete received JSON message. */
+    onMessage(handler: (json: string) => void): Unsubscribe;
+    /** Observes transport closure. */
+    onClose(handler: () => void): Unsubscribe;
+    /** Observes transport failures. */
+    onError(handler: (error: Error) => void): Unsubscribe;
+    /** Closes the transport and releases its listeners. */
+    close(): void;
+}

package/dist/src/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types.d.ts

@@ -0,0 +1,4 @@
+/** @deprecated Import protocol and client types from the package root. */
+export * from "./protocol/index.js";
+export type { CmuxClientOptions, AttachSurfaceOptions, NewBrowserTabOptions, NewScreenOptions, NewTabOptions, NewPaneRightOptions, NewWorkspaceOptions, ResizeTransactionOptions, SelectOptions, SelectTabOptions, SendOptions, SplitOptions, SubscribeOptions, } from "./client.js";
+export type { ClientOptions } from "./node-client.js";

package/dist/src/types.js

@@ -0,0 +1,2 @@
+/** @deprecated Import protocol and client types from the package root. */
+export * from "./protocol/index.js";