Table of Contents

smudgy:core — Panes

Generated from smudgy v0.5.4-dev (smudgy-core.d.ts @ a1c9d1939ffb). Index: scriptref.

Session panes: split named panes off the main pane (or off each other) and write lines into them. Panes host widgets (see widgets) and, unless created widgets-only, a terminal; a pane can also carry its own input line whose submissions go to your handler.

Pane

export interface Pane {
  readonly name: string;
  readonly kind: "terminal" | "widgets";
  readonly isMain: boolean;
  readonly created?: boolean;
  echo(text: string | StyledText): void;
  echo(text: TemplateStringsArray, ...values: unknown[]): void;
  clear(): void;
  close(): void;
  readonly input: InputHandle | undefined;
  split<D extends SplitDirection>(direction: D, spec: PaneSpec<D>): Pane;
  addTab(spec: TabPaneSpec): Pane;
  hide(): void;
  show(): void;
  readonly isHidden: boolean;
  setFontSize(px: number | null): void;
  readonly fontSize: number | undefined;
  resize(size: { width?: number; height?: number }): void;
  readonly size: { width: number; height: number } | undefined;
  relocate<D extends SplitDirection>(
    direction: D,
    reference?: Pane | string,
    size?: RelocateSize<D>,
  ): void;
  groupWith(reference: Pane, options?: GroupWithOptions): void;
  select(): void;
  tearOut(opts?: { width?: number; height?: number }): void;
  swap(otherPane: Pane): void;
}

A handle to one session pane. Panes are keyed by name: split() or addTab() with an existing name returns that pane. Most of the spec is then ignored, with two exceptions. An explicit titleBar updates the pane's policy. And input is part of what the pane is: asking for one on an existing pane that has none throws (close it first), while re-splitting a pane that has one re-registers its onSubmit (placeholder changes are ignored). A pane closes when close() is called, when the session ends, or when no script re-claims it during a reload; either creation call naming it during the reload keeps it, placement untouched. A later creation call with the same name recreates the pane and re-attaches its widgets. 

import { session, createTrigger, line } from "smudgy:core";
// A chat pane above the main terminal; clan tells route into it.
const chat = session.mainPane.split("top", { name: "Chat", height: 100 });
createTrigger(/tells your clan '/, () => line.redirect(chat));

PaneRegistry

export type PaneRegistry = PaneRegistryMethods & { readonly [name: string]: Pane | undefined };

A pane registry with both method and property access (panes.get("chat") and panes.chat).

PaneRegistryMethods

export interface PaneRegistryMethods {
  get(name: string): Pane | undefined;
  list(): Pane[];
  exists(name: string): boolean;
}

A session's pane registry: get/list/exists cover panes in the caller's namespace (plus main), and dot access reaches any name (session.panes.chat). The same lookup surface works on a same-server foreign session handle.

PaneSpec

export type PaneSpec<D extends SplitDirection> = PaneSpecBase &
(D extends "left" | "right"
  ? { width?: number; height?: never }
  : { height?: number; width?: never });

The spec for Pane.split. Give the new pane's starting size in pixels along the split axis: width when splitting left/right, height when splitting top/bottom. The user can resize it afterwards.

PaneSpecBase

export interface PaneSpecBase {
  name: string;
  terminal?: boolean;
  titleBar?: TitleBarSpec;
  hidden?: boolean;
  fontSize?: number;
  input?: PaneInputSpec;
}

The direction-independent half of the spec for Pane.split.

PaneInputSpec

export interface PaneInputSpec {
  onSubmit: (text: string) => void;
  placeholder?: string;
}

A pane's own input line (see PaneSpecBase.input). What the user submits there goes to your onSubmit handler and nowhere else: nothing is sent, matched against aliases, or echoed unless the handler does it, and the main input's history is untouched. session.send(text) inside the handler reproduces normal typed-command behavior. 

import { session } from "smudgy:core";
// A chat pane whose input auto-prefixes the channel.
session.mainPane.split("right", {
  name: "Chat",
  width: 300,
  input: { onSubmit: (text) => session.send(`gt ${text}`), placeholder: "group tell..." },
});

TabPaneSpec

export type TabPaneSpec = PaneSpecBase & {
  selected?: boolean;
  width?: never;
  height?: never;
};

The spec for Pane.addTab.

TabPosition

export type TabPosition = "before" | "after" | "end";

GroupWithOptions

export interface GroupWithOptions {
  position?: TabPosition;
  selected?: boolean;
}

RelocateSize

export type RelocateSize<D extends SplitDirection> = D extends "left" | "right"
? { width?: number; height?: never }
: { height?: number; width?: never };

The optional extent for Pane.relocate, keyed to the split axis exactly like a split's initial size.

SplitDirection

export type SplitDirection = "left" | "right" | "top" | "bottom";

Which side of the pane you split from the new pane appears on.

TitleBarSpec

export type TitleBarSpec = "normal" | "always-show";

When a pane's title bar (its header, which is also its drag handle) is shown. 'normal' follows the global distraction-free rule: headers show while the window's toolbar is expanded, or when the “hide panel headers” setting is off. 'always-show' keeps the header visible regardless. A pane without a visible header cannot be drag-rearranged; dividers still resize it.

layout

export const layout: {
  save(name: string): void;
  apply(name: string): void;
  list(): string[];
};

Named workspace layouts for the current session's server. A layout is a saved snapshot of the windows that hold at least one of this server's panes – their splits, tab groups, sizes, and pane positions – stored under the server and addressed by name. Names are case-insensitive: "Combat" and "combat" are the same layout.

apply rearranges only what already exists: live panes of this session's server move into the saved arrangement, panes the layout doesn't mention keep riding with their groups, and slots for panes or sessions that aren't open are held open for them to fill later. It never opens or closes sessions, never prompts, and never creates, closes, moves, or resizes app windows – those are user actions, available through the Layouts toolbar menu.

Layouts exist so users' saved arrangements win. split() sizes and placements are creation defaults, while an explicit pane.resize() is imperative intent that overrides the user's saved geometry – exactly as a user divider drag would. So resizing panes at load time is an anti-pattern: it permanently defeats the sizes users saved. Use split defaults at creation and reserve resize for genuine runtime reactions; switch whole arrangements with layout.apply.

Every layout method requires both the panes and session: ["reach-others"] capabilities: rearranging the workspace reaches every window showing this server, not just the panes this script made.

Pane events: smudgy:events/pane

visibility

export const visibility: EventConsumer<{
  pane: string;
  hidden: boolean;
}>;

Fires on every actual visibility toggle of a pane — the user's title-bar eyeball and scripted hide()/show() alike (including the main pane, which only the user can toggle). pane is the pane's display-cased name, resolvable in your own namespace; hidden is the new toggle state. Subscribing requires the panes capability.

resize

export const resize: EventConsumer<{
  pane: string;
  width: number;
  height: number;
}>;

Fires when a pane's laid-out size settles on a new value — after a divider drag comes to rest, a window resize, or a scripted resize(); never per drag frame. width/height are logical px, the same values Pane.size reads. Subscribing requires the panes capability.

Script API reference · ← smudgy:core — Saved automations · smudgy:widgets — Overview → · Scripting manual