@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/terminal-multiplexer.d.ts

@@ -1,20 +1,133 @@
-/** True when this process is running inside a Herdr pane. */
-export declare function isInsideHerdr(env?: NodeJS.ProcessEnv): boolean;
-/** Terminal multiplexers zeta recognizes as owning the screen grid. */
-export type TerminalMultiplexer = "herdr" | "tmux" | "screen" | "zellij" | "cmux" | "wmux";
+import type { TerminalMultiplexerModule, TerminalMultiplexerNotificationRequest } from "./multiplexers/types";
 /**
- * Classify which terminal multiplexer owns the current screen grid, or `null`
- * for a direct terminal. Single source of truth for both the render-path gate
+ * Every multiplexer omp recognizes, in classification order within each
+ * precedence tier. Adding a multiplexer means adding its module here.
+ */
+declare const registry: readonly [{
+    readonly id: "herdr";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["HERDR_ENV", "HERDR_PANE_ID", "HERDR_TAB_ID", "HERDR_WORKSPACE_ID"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "pane";
+        readonly send: ({ message, env }: TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly hyperlinks: "render";
+    readonly honorsSynchronizedOutput: true;
+    readonly imagesRequireOverride: true;
+}, {
+    readonly id: "tmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["TMUX"];
+    readonly termPrefix: "tmux";
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "inBand";
+        readonly send: ({ sequence, write }: TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly hyperlinks: {
+        readonly forward: {
+            readonly termProgram: "tmux";
+            readonly major: 3;
+            readonly minor: 4;
+        };
+    };
+    readonly backgroundColorCache: {
+        readonly passthrough: typeof import("./tmux").wrapTmuxPassthrough;
+        readonly settleMs: 100;
+    };
+    readonly expandsRepPadding: true;
+    readonly expiresSynchronizedOutput: true;
+    readonly altRestoreEndsSynchronizedOutput: true;
+    readonly growsBeforeSigwinch: true;
+}, {
+    readonly id: "screen";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["STY"];
+    readonly termPrefix: "screen";
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly hyperlinks: "drop";
+}, {
+    readonly id: "zellij";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["ZELLIJ"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "inBand";
+        readonly send: ({ sequence, write }: TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly backgroundQueryBrokenOn: readonly ["darwin"];
+}, {
+    readonly id: "cmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["CMUX_WORKSPACE_ID", "CMUX_SURFACE_ID", "CMUX_REMOTE_TRANSPORT"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "surface";
+        readonly send: ({ message, env }: TerminalMultiplexerNotificationRequest) => boolean;
+    };
+}, {
+    readonly id: "wmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["WMUX", "WMUX_SURFACE_ID"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+}, {
+    readonly id: "orca";
+    readonly precedence: "outerApp";
+    readonly sessionEnvKeys: readonly ["ORCA_PANE_KEY", "ORCA_WORKTREE_ID"];
+    readonly ownsScreenGrid: false;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+}];
+/** Terminal multiplexers omp recognizes. */
+export type TerminalMultiplexer = (typeof registry)[number]["id"];
+/** Every environment variable multiplexer classification reads, including the TERM fallback. */
+export declare const TERMINAL_MULTIPLEXER_ENV_KEYS: readonly string[];
+/**
+ * Whether an explicit session marker identifies the current provider.
+ *
+ * TERM is intentionally excluded: it is a classification fallback, not proof
+ * that a particular multiplexer session owns the current grid.
+ */
+export declare function hasTerminalMultiplexerSession(multiplexer: TerminalMultiplexer, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Every multiplexer whose explicit session markers are present, in registry
+ * order. Nested sessions all appear; TERM is not consulted.
+ */
+export declare function terminalMultiplexerSessions(env?: NodeJS.ProcessEnv): TerminalMultiplexerModule<TerminalMultiplexer>[];
+/**
+ * The multiplexer TERM names, whether or not its session markers survived.
+ * This is classification's TERM fallback; session markers are not consulted.
+ */
+export declare function terminalMultiplexerForTerm(env?: NodeJS.ProcessEnv): TerminalMultiplexerModule<TerminalMultiplexer> | undefined;
+/**
+ * Registry entry for the multiplexer hosting the current process, or
+ * `undefined` for a direct terminal. Same precedence as
+ * {@link classifyTerminalMultiplexer}.
+ */
+export declare function classifyTerminalMultiplexerModule(env?: NodeJS.ProcessEnv): TerminalMultiplexerModule<TerminalMultiplexer> | undefined;
+/**
+ * Classify which terminal multiplexer hosts the current process, or `null` for
+ * a direct terminal. Single source of truth for both the render-path gate
  * (`isInsideTerminalMultiplexer`) and the debug snapshot label.
  *
- * TMUX/STY/ZELLIJ, Herdr, and the CMUX/WMUX workspace/surface/remote-transport
- * markers are authoritative session signals. TERM can also survive when those
- * are stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh). Do not
- * use CMUX_SOCKET_PATH / WMUX_CLI / WMUX_PIPE here: they are CLI socket/path
- * overrides and can be set outside a CMUX/WMUX terminal. wmux is a Windows
- * multiplexer (Electron + xterm.js) modeled on cmux/herdr that repaints its
- * pane in place and exports WMUX=1 plus a native WMUX_SURFACE_ID.
+ * Session markers are authoritative. TERM can also survive when those markers
+ * are stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh), so a
+ * `tmux`/`screen` TERM prefix comes next. Outer applications such as Orca rank
+ * last so a multiplexer running inside them wins.
  */
 export declare function classifyTerminalMultiplexer(env?: NodeJS.ProcessEnv): TerminalMultiplexer | null;
-/** True when a terminal multiplexer owns the current screen grid. */
+/** True when the classified multiplexer owns the current screen grid. */
 export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Offer a notification to every active session's notifier, innermost tier
+ * first. Returns whether one delivered it; otherwise the terminal fallback
+ * applies unchanged.
+ */
+export declare function routeTerminalMultiplexerNotification(request: TerminalMultiplexerNotificationRequest): boolean;
+export {};

package/src/terminal-multiplexer.ts

@@ -1,45 +1,124 @@
-/** True when this process is running inside a Herdr pane. */
-export function isInsideHerdr(env: NodeJS.ProcessEnv = Bun.env): boolean {
-	// HERDR_ENV=1 is canonical. Identity vars survive env-sanitizing launchers
-	// that drop HERDR_ENV. Do not use HERDR_SOCKET_PATH, HERDR_BIN_PATH,
-	// HERDR_SESSION, HERDR_CONFIG_PATH, or HERDR_CLIENT_SOCKET_PATH here: they
-	// are client-side and can be set outside a Herdr pane, matching the
-	// CMUX_SOCKET_PATH warning below.
-	if (env.HERDR_ENV === "1") return true;
-	if (env.HERDR_PANE_ID || env.HERDR_TAB_ID || env.HERDR_WORKSPACE_ID) return true;
-	return false;
+import { cmuxMultiplexer } from "./multiplexers/cmux";
+import { herdrMultiplexer } from "./multiplexers/herdr";
+import { orcaMultiplexer } from "./multiplexers/orca";
+import { screenMultiplexer } from "./multiplexers/screen";
+import { tmuxMultiplexer } from "./multiplexers/tmux";
+import type { TerminalMultiplexerModule, TerminalMultiplexerNotificationRequest } from "./multiplexers/types";
+import { wmuxMultiplexer } from "./multiplexers/wmux";
+import { zellijMultiplexer } from "./multiplexers/zellij";
+
+/**
+ * Every multiplexer omp recognizes, in classification order within each
+ * precedence tier. Adding a multiplexer means adding its module here.
+ */
+const registry = [
+	herdrMultiplexer,
+	tmuxMultiplexer,
+	screenMultiplexer,
+	zellijMultiplexer,
+	cmuxMultiplexer,
+	wmuxMultiplexer,
+	orcaMultiplexer,
+] as const satisfies readonly TerminalMultiplexerModule[];
+
+/** Terminal multiplexers omp recognizes. */
+export type TerminalMultiplexer = (typeof registry)[number]["id"];
+
+const TERMINAL_MULTIPLEXERS: readonly TerminalMultiplexerModule<TerminalMultiplexer>[] = registry;
+const MULTIPLEXERS_BY_ID = Object.fromEntries(
+	TERMINAL_MULTIPLEXERS.map(multiplexer => [multiplexer.id, multiplexer]),
+) as Record<TerminalMultiplexer, TerminalMultiplexerModule<TerminalMultiplexer>>;
+const SESSION_TIER = TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.precedence === "session");
+const OUTER_APP_TIER = TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.precedence === "outerApp");
+const NOTIFICATION_TIER_ORDER = ["pane", "surface", "inBand"] as const;
+// Innermost target first: a pane inside a surface must receive its own signal
+// before the containing surface, followed by in-band rewrites. Registry order
+// breaks ties within a tier (sort is stable).
+const NOTIFIERS = TERMINAL_MULTIPLEXERS.flatMap(multiplexer =>
+	multiplexer.notifier ? [{ multiplexer, notifier: multiplexer.notifier }] : [],
+).sort((a, b) => NOTIFICATION_TIER_ORDER.indexOf(a.notifier.tier) - NOTIFICATION_TIER_ORDER.indexOf(b.notifier.tier));
+
+/** Every environment variable multiplexer classification reads, including the TERM fallback. */
+export const TERMINAL_MULTIPLEXER_ENV_KEYS: readonly string[] = [
+	...TERMINAL_MULTIPLEXERS.flatMap(multiplexer => multiplexer.sessionEnvKeys),
+	"TERM",
+];
+
+/**
+ * Whether an explicit session marker identifies the current provider.
+ *
+ * TERM is intentionally excluded: it is a classification fallback, not proof
+ * that a particular multiplexer session owns the current grid.
+ */
+export function hasTerminalMultiplexerSession(
+	multiplexer: TerminalMultiplexer,
+	env: NodeJS.ProcessEnv = Bun.env,
+): boolean {
+	return MULTIPLEXERS_BY_ID[multiplexer].isInside(env);
 }
 
-/** Terminal multiplexers zeta recognizes as owning the screen grid. */
-export type TerminalMultiplexer = "herdr" | "tmux" | "screen" | "zellij" | "cmux" | "wmux";
+/**
+ * Every multiplexer whose explicit session markers are present, in registry
+ * order. Nested sessions all appear; TERM is not consulted.
+ */
+export function terminalMultiplexerSessions(
+	env: NodeJS.ProcessEnv = Bun.env,
+): TerminalMultiplexerModule<TerminalMultiplexer>[] {
+	return TERMINAL_MULTIPLEXERS.filter(multiplexer => multiplexer.isInside(env));
+}
 
 /**
- * Classify which terminal multiplexer owns the current screen grid, or `null`
- * for a direct terminal. Single source of truth for both the render-path gate
+ * The multiplexer TERM names, whether or not its session markers survived.
+ * This is classification's TERM fallback; session markers are not consulted.
+ */
+export function terminalMultiplexerForTerm(
+	env: NodeJS.ProcessEnv = Bun.env,
+): TerminalMultiplexerModule<TerminalMultiplexer> | undefined {
+	const term = env.TERM?.toLowerCase() ?? "";
+	return TERMINAL_MULTIPLEXERS.find(
+		multiplexer => multiplexer.termPrefix !== undefined && term.startsWith(multiplexer.termPrefix),
+	);
+}
+
+/**
+ * Registry entry for the multiplexer hosting the current process, or
+ * `undefined` for a direct terminal. Same precedence as
+ * {@link classifyTerminalMultiplexer}.
+ */
+export function classifyTerminalMultiplexerModule(
+	env: NodeJS.ProcessEnv = Bun.env,
+): TerminalMultiplexerModule<TerminalMultiplexer> | undefined {
+	return (
+		SESSION_TIER.find(multiplexer => multiplexer.isInside(env)) ??
+		terminalMultiplexerForTerm(env) ??
+		OUTER_APP_TIER.find(multiplexer => multiplexer.isInside(env))
+	);
+}
+
+/**
+ * Classify which terminal multiplexer hosts the current process, or `null` for
+ * a direct terminal. Single source of truth for both the render-path gate
  * (`isInsideTerminalMultiplexer`) and the debug snapshot label.
  *
- * TMUX/STY/ZELLIJ, Herdr, and the CMUX/WMUX workspace/surface/remote-transport
- * markers are authoritative session signals. TERM can also survive when those
- * are stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh). Do not
- * use CMUX_SOCKET_PATH / WMUX_CLI / WMUX_PIPE here: they are CLI socket/path
- * overrides and can be set outside a CMUX/WMUX terminal. wmux is a Windows
- * multiplexer (Electron + xterm.js) modeled on cmux/herdr that repaints its
- * pane in place and exports WMUX=1 plus a native WMUX_SURFACE_ID.
+ * Session markers are authoritative. TERM can also survive when those markers
+ * are stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh), so a
+ * `tmux`/`screen` TERM prefix comes next. Outer applications such as Orca rank
+ * last so a multiplexer running inside them wins.
  */
 export function classifyTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): TerminalMultiplexer | null {
-	if (isInsideHerdr(env)) return "herdr";
-	if (env.TMUX) return "tmux";
-	if (env.STY) return "screen";
-	if (env.ZELLIJ) return "zellij";
-	if (env.CMUX_WORKSPACE_ID || env.CMUX_SURFACE_ID || env.CMUX_REMOTE_TRANSPORT) return "cmux";
-	if (env.WMUX === "1" || env.WMUX_SURFACE_ID) return "wmux";
-	const term = env.TERM?.toLowerCase() ?? "";
-	if (term.startsWith("tmux")) return "tmux";
-	if (term.startsWith("screen")) return "screen";
-	return null;
+	return classifyTerminalMultiplexerModule(env)?.id ?? null;
 }
 
-/** True when a terminal multiplexer owns the current screen grid. */
+/** True when the classified multiplexer owns the current screen grid. */
 export function isInsideTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): boolean {
-	return classifyTerminalMultiplexer(env) !== null;
+	return classifyTerminalMultiplexerModule(env)?.ownsScreenGrid ?? false;
+}
+
+/**
+ * Offer a notification to every active session's notifier, innermost tier
+ * first. Returns whether one delivered it; otherwise the terminal fallback
+ * applies unchanged.
+ */
+export function routeTerminalMultiplexerNotification(request: TerminalMultiplexerNotificationRequest): boolean {
+	return NOTIFIERS.some(({ multiplexer, notifier }) => multiplexer.isInside(request.env) && notifier.send(request));
 }

package/src/terminal.d.ts

@@ -1,4 +1,5 @@
 import { type TspHello } from "./native/encode";
+export { writeTerminalSequence, writeThroughActiveTerminal } from "./active-terminal";
 /**
  * Split `data` into chunks whose encoded UTF-8 byte length is no greater than
  * `maxChunkBytes`, preferring a line boundary (`\n`) as the cut point so
@@ -69,16 +70,6 @@ export declare class StdoutStallWatchdog {
 }
 /** Record alternate-screen state (called by the TUI on `?1049h`/`?1049l` writes). */
 export declare function setAltScreenActive(active: boolean): void;
-/**
- * Route an out-of-band escape sequence (e.g. an OSC title update) through the
- * active terminal's output path. While a TUI owns stdout, frame paints go
- * through the off-thread write pump and can split across multiple write(2)
- * calls; a direct main-thread `process.stdout.write` can land between two of
- * them — mid escape sequence — and the host terminal then prints the payload
- * as literal text at the cursor position. Returns false when no terminal has
- * started, in which case the caller owns stdout and may write directly.
- */
-export declare function writeThroughActiveTerminal(data: string): boolean;
 /**
  * Emergency terminal restore - call this from signal/crash handlers
  * Resets terminal state without requiring access to the ProcessTerminal instance
@@ -137,13 +128,21 @@ export type TspHelloHandler = (hello: TspHello | null) => void;
 export type CursorShape = "default" | "block" | "underline" | "bar";
 export declare const CURSOR_SHAPE_CODES: Record<CursorShape, number>;
 export interface Terminal {
+    /**
+     * Start the terminal with input, resize, and host-disconnect handlers.
+     * Unless input is deferred, this sends capability probes; a terminal that
+     * cannot parse one may leave concealed bytes on the cursor row, so the
+     * caller repaints after starting.
+     */
     start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
     /**
      * Take ownership of stdin after a `deferInput` start: enable raw mode,
      * attach input handlers, and run the capability probes start() skipped.
      * Bytes the user typed in cooked mode meanwhile are replayed through
-     * `onInput`. No-op when input was never deferred. Optional so custom
-     * Terminals built against older pi-tui versions keep working.
+     * `onInput`. No-op when input was never deferred. Like {@link start}, the
+     * probes may leave concealed bytes on the cursor row, so the caller
+     * repaints afterwards. Optional so custom Terminals built against older
+     * pi-tui versions keep working.
      */
     enableInput?(): void;
     stop(): void;
@@ -231,6 +230,12 @@ export interface Terminal {
      * `status` is the DECRPM value when the terminal answered DECRQM.
      */
     onPrivateModeReport?(callback: PrivateModeReportHandler): void;
+    /**
+     * Report whether DA1 advertises SIXEL (attribute 4), replaying the latest
+     * advertisement to late subscribers. A missing attribute does not rule out
+     * support discovered through another graphics query.
+     */
+    onSixelSupport?(callback: (supported: boolean) => void): void;
     /**
      * Register a callback fired once the startup Glyph Protocol handshake
      * resolves (see {@link GlyphProtocolReportHandler}). A subscriber that
@@ -299,10 +304,11 @@ export declare class ProcessTerminal implements Terminal {
     onAppearanceReport(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): () => void;
     /**
      * Re-query the terminal background through the startup DA1-sentinel FIFO,
-     * pending/queued gating, parsing, dedup, and appearance callbacks. Inside
-     * tmux, only this explicit path first passes an OSC 11 query to the outer
-     * terminal, waits briefly for tmux to consume the response into its cache,
-     * then reads that cache with a direct query. The outer query deliberately has
+     * pending/queued gating, parsing, dedup, and appearance callbacks. Inside a
+     * multiplexer that answers OSC 11 from a cache (tmux), only this explicit
+     * path first passes an OSC 11 query to the outer terminal, waits briefly for
+     * the multiplexer to consume the response into its cache, then reads that
+     * cache with a direct query. The outer query deliberately has
      * no DA1 sentinel: multiplexers can decode a fragmented DA1 response as a key
      * sequence and leak the remaining bytes into the editor. Startup and Mode 2031
      * probes remain direct. Suppressed while inactive, headless, or after teardown.
@@ -310,6 +316,7 @@ export declare class ProcessTerminal implements Terminal {
     refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
     onPrivateModeReport(callback: PrivateModeReportHandler): void;
     onGlyphProtocolReport(callback: GlyphProtocolReportHandler): void;
+    onSixelSupport(callback: (supported: boolean) => void): void;
     onTspHello(callback: TspHelloHandler): void;
     get tspProbePending(): boolean;
     get tspExpected(): boolean;