smudgy:core — Panes

Generated from smudgy v0.3.5 (smudgy-core.d.ts @ cfcea3b156f6). 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.

export interface Pane {
  readonly name: string;
  readonly kind: "terminal" | "widgets";
  readonly isMain: boolean;
  readonly created?: boolean;
  echo(text: string): void;
  clear(): void;
  close(): void;
  split<D extends SplitDirection>(direction: D, spec: PaneSpec<D>): Pane;
}

A handle to one session pane. Panes are keyed by name: split() with an existing name returns that pane (its spec is ignored, except titleBar). A pane closes when close() is called, when the session ends, or when no script re-claims it during a reload; any split() naming it during the reload keeps it, placement untouched. A later split() 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("clan chat", /tells your clan '/, () => line.redirect(chat));

• name — The pane's name in its display case.
• kind — Whether this pane has a terminal ("terminal") or is widgets-only ("widgets"). Every pane can host widgets; the main pane is always "terminal".
• created — false when split() returned an already-existing pane.
• echo — Write whole lines into this pane's terminal. Throws on widgets-only panes.
• clear — Clear this pane's terminal scrollback (works on main). Throws on widgets-only panes.
• close — Close this pane. Throws on the main pane; safe to repeat otherwise.
• split — Split a new pane off this one (get-or-create by name; an explicit titleBar also updates an existing pane's policy, including main's).

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

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

A session's pane registry: get/list/exists cover your own panes (plus the main pane), and dot access reaches any name (session.panes.chat). On another session, only split, close, and a pane's echo/clear may be used; lookups work on your own session only.

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.

export interface PaneSpecBase {
  name: string;
  terminal?: boolean;
  titleBar?: TitleBarSpec;
}

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

• name — Required. Names are case-insensitive (display case is preserved) and namespaced per package. Up to 64 printable characters; main, get, list, exists and then are reserved.
• terminal — Default true. Pass false for a widgets-only pane with no terminal; echo/clear throw on it. Every pane can host widgets either way.
• titleBar — Default 'normal'. The one spec key that also applies to an existing pane: split() naming an existing pane (including 'main') with an explicit titleBar updates its policy.

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

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

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.

Script API reference · smudgy:core — Sessions & output · smudgy:core — Lines & buffer · smudgy:core — Events · smudgy:core — Automations · smudgy:core — Saved automations · smudgy:widgets · Mapper · smudgy:params