smudgy:core — Panes

Generated from smudgy v0.4.2-dev (smudgy-core.d.ts @ 5110ac599715). 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.

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;
}

A handle to one session pane. Panes are keyed by name: split() 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; 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(/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. Takes styled text too, and works directly as a template tag.
• 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.
• input — This pane's own input line, or undefined for panes created without one (see PaneInputSpec). The same handle as InputHandle, addressed at this pane: its text, focus, masking, completion words, and history are all the pane input's own, independent of the main input's. On the main pane this is undefined too; its input is Session.input.
• 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 };

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

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;
  input?: PaneInputSpec;
}

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'. Also applies to an existing pane: split() naming an existing pane (including 'main') with an explicit titleBar updates its policy.
• input — Give the pane its own input line (see PaneInputSpec). Part of what the pane is, like terminal: split() naming an existing pane that has no input while asking for one throws (close it first). Works on either pane kind; usable on your own session only. Re-splitting with the same spec re-registers onSubmit, which is also how a handler comes back after your script reloads.

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..." },
});

• onSubmit — Receives each submitted line. The text is yours alone: nothing is sent to the server, matched against aliases, or echoed unless you do it here, and the main input's history never records it.
• placeholder — Hint text shown while the input is empty.

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 — Saved automations · smudgy:widgets — Overview → · Scripting manual