@m4ike1/ion-tui 0.1.0

package/dist/native-platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-platform.js","sourceRoot":"","sources":["../src/native-platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAEpE,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAkBlD,sFAAsF;AACtF,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4C,CAAC;AAEpE,SAAS,wBAAwB,CAAC,QAAgB,EAAE,MAAM,GAAG,EAAE,EAAoC;IAClG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IACzD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAC3B,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,GAAG,QAAQ,IAAI,IAAI,EAAE,EACrB,GAAG,QAAQ,YAAY,MAAM,OAAO,CACpC,CAAC;IACF,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAE5D,KAAK,MAAM,UAAU,IAAI,yBAAyB,CAAC,UAAU,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAyC,CAAC;YAC9E,IAAI,OAAO,MAAM,EAAE,OAAO,KAAK,UAAU,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;gBACpF,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,MAA8B,CAAC,CAAC;gBACxD,OAAO,MAA8B,CAAC;YACvC,CAAC;QACF,CAAC;QAAC,MAAM,CAAC;YACR,4CAA4C;QAC7C,CAAC;IACF,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACnC,OAAO,SAAS,CAAC;AAAA,CACjB;AAED,MAAM,UAAU,uBAAuB,GAAqC;IAC3E,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IACpF,OAAO,wBAAwB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAAA,CAClD;AAED,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,GAAgC;IACjE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,uBAAuB,EAAE,CAAC;IACnE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,wBAAwB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAAA,CACjD","sourcesContent":["import { createRequire } from \"node:module\";\nimport * as path from \"node:path\";\nimport { getNativeModuleCandidates } from \"./native-module-path.ts\";\n\nconst cjsRequire = createRequire(import.meta.url);\n\nexport type ModifierKey = \"shift\" | \"command\" | \"control\" | \"option\";\n\nexport interface NativeClipboard {\n\t/** Undefined means unavailable, null means no text; transfer failures reject. */\n\tgetText(): Promise<string | null | undefined>;\n\t/** Undefined means unavailable, null means no image; transfer failures reject. */\n\tgetImage(): Promise<Uint8Array | null | undefined>;\n\t/** Linux uses command-line tools to retain clipboard ownership instead. */\n\tsetText?(text: string): Promise<void>;\n}\n\ntype NativePlatformHelper = NativeClipboard & {\n\tenableVirtualTerminalInput?: () => boolean;\n\tisModifierPressed?: (name: ModifierKey) => boolean;\n};\n\n// Cache module loading, not display availability: a disconnected display can recover.\nconst helpers = new Map<string, NativePlatformHelper | undefined>();\n\nfunction loadNativePlatformHelper(platform: string, suffix = \"\"): NativePlatformHelper | undefined {\n\tconst arch = process.arch;\n\tif (arch !== \"x64\" && arch !== \"arm64\") return undefined;\n\tconst nativePath = path.join(\n\t\t\"native\",\n\t\tplatform,\n\t\t\"prebuilds\",\n\t\t`${platform}-${arch}`,\n\t\t`${platform}-platform${suffix}.node`,\n\t);\n\tif (helpers.has(nativePath)) return helpers.get(nativePath);\n\n\tfor (const modulePath of getNativeModuleCandidates(nativePath)) {\n\t\ttry {\n\t\t\tconst helper = cjsRequire(modulePath) as Partial<NativePlatformHelper> | null;\n\t\t\tif (typeof helper?.getText === \"function\" && typeof helper.getImage === \"function\") {\n\t\t\t\thelpers.set(nativePath, helper as NativePlatformHelper);\n\t\t\t\treturn helper as NativePlatformHelper;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Try the next possible packaging location.\n\t\t}\n\t}\n\thelpers.set(nativePath, undefined);\n\treturn undefined;\n}\n\nexport function getNativePlatformHelper(): NativePlatformHelper | undefined {\n\tif (process.platform !== \"darwin\" && process.platform !== \"win32\") return undefined;\n\treturn loadNativePlatformHelper(process.platform);\n}\n\n/** Load a clipboard helper without opening the display until a read is requested. */\nexport function getNativeClipboard(): NativeClipboard | undefined {\n\tif (process.platform !== \"linux\") return getNativePlatformHelper();\n\tif (!process.env.DISPLAY) return undefined;\n\treturn loadNativePlatformHelper(\"linux\", \"-x11\");\n}\n"]}

package/dist/pty-host.d.ts

@@ -0,0 +1,224 @@
+/**
+ * PTY host spike (tui-overhaul 1.1-1.5).
+ *
+ * Spawns the stock ion TUI inside a pseudoterminal and relays bytes
+ * bidirectionally between the PTY master and the session owner. The TUI
+ * itself stays raw-terminal plus alt-screen and is never rewritten for
+ * hosting: this mirrors the Claude Code seam where a separate server hosts
+ * the stock TUI under node-pty (see TUI.claude.md section 1.4).
+ *
+ * Seam rules (pinned by test/pty-host.test.ts):
+ * - The core TUI (index.ts, terminal.ts, tui.ts) never imports this module.
+ * - node-pty resolves at runtime with prebuilt-first lookup; when no binary
+ *   is available the caller gets an actionable install hint and the plain
+ *   terminal path keeps working.
+ *
+ * Transport decision (task 1.5): in-process handle. A Unix-socket transport
+ * would only pay off for reattach-across-process, which no consumer needs
+ * yet (the future session-share viewer attaches in-process). Sockets would
+ * add framing, auth, and lifecycle management for zero current benefit, so
+ * the host is a plain object owning its PTY child. Revisit when an
+ * out-of-process attacher arrives.
+ *
+ * Reattach replay is best-effort byte replay: the host journals PTY output
+ * in a bounded ring and, on reattach, nudges the child with a same-dims
+ * resize (SIGWINCH repaint, the setWinSize semantic) then replays everything
+ * journaled while detached. A terminal-emulator-backed screen dump is
+ * future work, not part of this spike.
+ *
+ * Minimum dimensions stay an open product question: the spike validates
+ * positive integers only. Layouts below ~40 columns are known to degrade
+ * (the 40x12 golden case pins bounded behavior, not beauty).
+ */
+/** Transport backing session handles. Pinned to in-process by the task 1.5 decision above. */
+export declare const PTY_HOST_TRANSPORT = "in-process";
+/** Default cap for the reattach replay journal. */
+export declare const PTY_HOST_JOURNAL_LIMIT_BYTES: number;
+/**
+ * Resync prefix used only when the journal overflowed while detached and
+ * replay can no longer continue the previous screen state.
+ */
+export declare const PTY_RESYNC_SEQUENCE = "\u001B[2J\u001B[H";
+/** Caller-specified PTY dimensions in character cells. */
+export interface PtyDimensions {
+    cols: number;
+    rows: number;
+}
+/** Throw unless cols/rows are positive integers. Integers only: fractional cells do not exist. */
+export declare function assertPtyDimensions(cols: number, rows: number): void;
+/**
+ * Minimal structural backend over a PTY child. Matches the node-pty
+ * surface the host needs without depending on node-pty types, so tests
+ * inject fakes and the core TUI never sees this module.
+ */
+export interface PtyBackend {
+    readonly pid: number;
+    onData(callback: (data: string) => void): void;
+    onExit(callback: (exitCode: number, signal: number | undefined) => void): void;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+    /** Optional raw-mode mirror; real PTY slaves are raw by default so most backends omit this. */
+    setRawMode?(active: boolean): void;
+}
+/** Options passed to a backend spawn function. */
+export interface PtySpawnOptions {
+    command: string;
+    args: string[];
+    cols: number;
+    rows: number;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    name: string;
+}
+/** Injectable backend factory. Tests pass fakes; production passes the node-pty adapter. */
+export type PtySpawnFn = (options: PtySpawnOptions) => PtyBackend;
+/** Minimal structural view of the node-pty module (spawn only). */
+export interface NodePtyModule {
+    spawn(file: string, args: string[], options: {
+        name: string;
+        cols: number;
+        rows: number;
+        cwd: string;
+        env: NodeJS.ProcessEnv;
+    }): {
+        pid: number;
+        onData(callback: (data: string) => void): void;
+        onExit(callback: (event: {
+            exitCode: number;
+            signal?: number;
+        }) => void): void;
+        write(data: string): void;
+        resize(cols: number, rows: number): void;
+        kill(signal?: string): void;
+    };
+}
+/** node-pty resolved and ready: prebuilt-first lookup hit. */
+export interface PtyResolutionSuccess {
+    available: true;
+    /** Which specifier resolved (explicit ION_PTY_MODULE override or "node-pty"). */
+    source: string;
+    spawn: PtySpawnFn;
+}
+/** node-pty unavailable: hint carries the actionable install instructions. */
+export interface PtyResolutionFailure {
+    available: false;
+    hint: string;
+}
+export type PtyResolution = PtyResolutionSuccess | PtyResolutionFailure;
+export interface ResolveNodePtyOptions {
+    /** Injectable loader for tests. Defaults to require relative to this module. */
+    loadModule?: (specifier: string) => unknown;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve node-pty at runtime, prebuilt-first (node-pty's own packaging
+ * prefers prebuilds via prebuild-install). Lookup order: explicit
+ * ION_PTY_MODULE override path first, then the "node-pty" package.
+ * Never throws: failure returns an actionable hint instead.
+ */
+export declare function resolveNodePty(options?: ResolveNodePtyOptions): PtyResolution;
+/** Thrown by createPtyHost when node-pty is unavailable. Carries the install hint as message. */
+export declare class PtyHostUnavailableError extends Error {
+    constructor(hint: string);
+}
+export interface PtyHostOptions {
+    /** Stock TUI binary to spawn inside the PTY (host never rewrites the TUI). */
+    command: string;
+    args?: string[];
+    cols: number;
+    rows: number;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** TERM value for the PTY slave. */
+    name?: string;
+    /** Replay journal cap in bytes. Defaults to PTY_HOST_JOURNAL_LIMIT_BYTES. */
+    journalLimitBytes?: number;
+    /** Injected backend. Production callers omit this and go through createPtyHost. */
+    spawn: PtySpawnFn;
+    /** Convenience exit listener, equivalent to onExit(). */
+    onExit?: (exitCode: number, signal: number | undefined) => void;
+}
+export type CreatePtyHostOptions = Omit<PtyHostOptions, "spawn"> & {
+    spawn?: PtySpawnFn;
+    resolveOptions?: ResolveNodePtyOptions;
+};
+/**
+ * Create a host, resolving node-pty unless the caller injects a backend.
+ * Throws PtyHostUnavailableError (message = install hint) when no PTY
+ * binary resolves; callers fall back to the plain terminal path.
+ */
+export declare function createPtyHost(options: CreatePtyHostOptions): PtyHost;
+/** Owner callback receiving PTY master output bytes verbatim. */
+export type PtyOwnerCallback = (data: string) => void;
+/** PTY child exit listener. */
+export type PtyExitCallback = (exitCode: number, signal: number | undefined) => void;
+/**
+ * In-process owner of one PTY-hosted TUI session. Byte relay is fully
+ * transparent in both directions: the host never interprets owner input
+ * (Ctrl+C arrives as 0x03, escape sequences pass through untouched) and
+ * forwards child output verbatim. Raw-mode passthrough mirrors the owner
+ * raw state to backends that support it; it never gates the byte stream.
+ */
+export declare class PtyHost {
+    private readonly backend;
+    private readonly journalLimit;
+    private owner;
+    private readonly exitListeners;
+    private colsValue;
+    private rowsValue;
+    private rawModeValue;
+    private disposedValue;
+    private exitedValue;
+    private exitCodeValue;
+    private journal;
+    private journalBytes;
+    private detachChunkIndex;
+    private detachOverflow;
+    constructor(options: PtyHostOptions);
+    get cols(): number;
+    get rows(): number;
+    get pid(): number;
+    get isAttached(): boolean;
+    get isDetached(): boolean;
+    get isDisposed(): boolean;
+    get exited(): boolean;
+    get exitCode(): number | undefined;
+    get rawMode(): boolean;
+    /** Initial owner attach. Throws when already attached or disposed. */
+    attach(owner: PtyOwnerCallback): void;
+    /** Owner disconnects; the PTY session keeps running and output is journaled. Idempotent. */
+    detach(): void;
+    /**
+     * New owner attaches and immediately receives everything journaled
+     * while detached (the current screen state, best-effort). A same-dims
+     * resize nudges the child to repaint first. Throws when an owner is
+     * already attached or the host is disposed.
+     */
+    reattach(owner: PtyOwnerCallback): void;
+    /**
+     * Owner input reaches the PTY byte-transparent. Dropped while
+     * detached (no owner exists to produce input); throws after dispose.
+     */
+    write(data: string): void;
+    /**
+     * Forward owner resize events to the PTY (setWinSize semantics); the
+     * stock TUI re-layouts to the new dimensions itself.
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * Mirror owner raw-mode state to the backend when it supports it.
+     * Returns whether the backend honored the request. The byte stream
+     * is never gated on this flag.
+     */
+    setRawMode(active: boolean): boolean;
+    /** Subscribe to PTY child exit. Returns an unsubscribe function. */
+    onExit(callback: PtyExitCallback): () => void;
+    /** Kill the PTY session and release the owner. Idempotent. */
+    dispose(): void;
+    private handleBackendData;
+    private handleBackendExit;
+    private appendJournal;
+    private throwIfDisposed;
+}
+//# sourceMappingURL=pty-host.d.ts.map

package/dist/pty-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty-host.d.ts","sourceRoot":"","sources":["../src/pty-host.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * PTY host spike (tui-overhaul 1.1-1.5).\n *\n * Spawns the stock ion TUI inside a pseudoterminal and relays bytes\n * bidirectionally between the PTY master and the session owner. The TUI\n * itself stays raw-terminal plus alt-screen and is never rewritten for\n * hosting: this mirrors the Claude Code seam where a separate server hosts\n * the stock TUI under node-pty (see TUI.claude.md section 1.4).\n *\n * Seam rules (pinned by test/pty-host.test.ts):\n * - The core TUI (index.ts, terminal.ts, tui.ts) never imports this module.\n * - node-pty resolves at runtime with prebuilt-first lookup; when no binary\n *   is available the caller gets an actionable install hint and the plain\n *   terminal path keeps working.\n *\n * Transport decision (task 1.5): in-process handle. A Unix-socket transport\n * would only pay off for reattach-across-process, which no consumer needs\n * yet (the future session-share viewer attaches in-process). Sockets would\n * add framing, auth, and lifecycle management for zero current benefit, so\n * the host is a plain object owning its PTY child. Revisit when an\n * out-of-process attacher arrives.\n *\n * Reattach replay is best-effort byte replay: the host journals PTY output\n * in a bounded ring and, on reattach, nudges the child with a same-dims\n * resize (SIGWINCH repaint, the setWinSize semantic) then replays everything\n * journaled while detached. A terminal-emulator-backed screen dump is\n * future work, not part of this spike.\n *\n * Minimum dimensions stay an open product question: the spike validates\n * positive integers only. Layouts below ~40 columns are known to degrade\n * (the 40x12 golden case pins bounded behavior, not beauty).\n */\n\nimport { createRequire } from \"node:module\";\n\nconst moduleRequire = createRequire(import.meta.url);\n\n/** Transport backing session handles. Pinned to in-process by the task 1.5 decision above. */\nexport const PTY_HOST_TRANSPORT = \"in-process\";\n\n/** Default cap for the reattach replay journal. */\nexport const PTY_HOST_JOURNAL_LIMIT_BYTES = 256 * 1024;\n\n/**\n * Resync prefix used only when the journal overflowed while detached and\n * replay can no longer continue the previous screen state.\n */\nexport const PTY_RESYNC_SEQUENCE = \"\\x1b[2J\\x1b[H\";\n\n/** Caller-specified PTY dimensions in character cells. */\nexport interface PtyDimensions {\n\tcols: number;\n\trows: number;\n}\n\n/** Throw unless cols/rows are positive integers. Integers only: fractional cells do not exist. */\nexport function assertPtyDimensions(cols: number, rows: number): void {\n\tif (!Number.isInteger(cols) || cols < 1) {\n\t\tthrow new RangeError(`PTY cols must be a positive integer, got ${cols}`);\n\t}\n\tif (!Number.isInteger(rows) || rows < 1) {\n\t\tthrow new RangeError(`PTY rows must be a positive integer, got ${rows}`);\n\t}\n}\n\n/**\n * Minimal structural backend over a PTY child. Matches the node-pty\n * surface the host needs without depending on node-pty types, so tests\n * inject fakes and the core TUI never sees this module.\n */\nexport interface PtyBackend {\n\treadonly pid: number;\n\tonData(callback: (data: string) => void): void;\n\tonExit(callback: (exitCode: number, signal: number | undefined) => void): void;\n\twrite(data: string): void;\n\tresize(cols: number, rows: number): void;\n\tkill(signal?: string): void;\n\t/** Optional raw-mode mirror; real PTY slaves are raw by default so most backends omit this. */\n\tsetRawMode?(active: boolean): void;\n}\n\n/** Options passed to a backend spawn function. */\nexport interface PtySpawnOptions {\n\tcommand: string;\n\targs: string[];\n\tcols: number;\n\trows: number;\n\tcwd: string;\n\tenv: NodeJS.ProcessEnv;\n\tname: string;\n}\n\n/** Injectable backend factory. Tests pass fakes; production passes the node-pty adapter. */\nexport type PtySpawnFn = (options: PtySpawnOptions) => PtyBackend;\n\n/** Minimal structural view of the node-pty module (spawn only). */\nexport interface NodePtyModule {\n\tspawn(\n\t\tfile: string,\n\t\targs: string[],\n\t\toptions: { name: string; cols: number; rows: number; cwd: string; env: NodeJS.ProcessEnv },\n\t): {\n\t\tpid: number;\n\t\tonData(callback: (data: string) => void): void;\n\t\tonExit(callback: (event: { exitCode: number; signal?: number }) => void): void;\n\t\twrite(data: string): void;\n\t\tresize(cols: number, rows: number): void;\n\t\tkill(signal?: string): void;\n\t};\n}\n\n/** node-pty resolved and ready: prebuilt-first lookup hit. */\nexport interface PtyResolutionSuccess {\n\tavailable: true;\n\t/** Which specifier resolved (explicit ION_PTY_MODULE override or \"node-pty\"). */\n\tsource: string;\n\tspawn: PtySpawnFn;\n}\n\n/** node-pty unavailable: hint carries the actionable install instructions. */\nexport interface PtyResolutionFailure {\n\tavailable: false;\n\thint: string;\n}\n\nexport type PtyResolution = PtyResolutionSuccess | PtyResolutionFailure;\n\nexport interface ResolveNodePtyOptions {\n\t/** Injectable loader for tests. Defaults to require relative to this module. */\n\tloadModule?: (specifier: string) => unknown;\n\tenv?: NodeJS.ProcessEnv;\n}\n\nfunction defaultLoadModule(specifier: string): unknown {\n\treturn moduleRequire(specifier);\n}\n\nfunction buildNodePtyHint(failures: string[]): string {\n\tconst lines = [\n\t\t\"node-pty is unavailable and the PTY host cannot start.\",\n\t\t\"Install it with `npm install node-pty` (prebuilt binaries are used when available;\",\n\t\t\"building from source needs python3, make, and g++).\",\n\t\t\"Set ION_PTY_MODULE to load node-pty from a custom path.\",\n\t\t\"The plain terminal path keeps working without it.\",\n\t];\n\tif (failures.length > 0) {\n\t\tlines.push(`Looked up: ${failures.join(\"; \")}`);\n\t}\n\treturn lines.join(\" \");\n}\n\nfunction adaptNodePty(moduleRef: NodePtyModule, options: PtySpawnOptions): PtyBackend {\n\tconst child = moduleRef.spawn(options.command, options.args, {\n\t\tname: options.name,\n\t\tcols: options.cols,\n\t\trows: options.rows,\n\t\tcwd: options.cwd,\n\t\tenv: options.env,\n\t});\n\treturn {\n\t\tpid: child.pid,\n\t\tonData: (callback) => child.onData(callback),\n\t\tonExit: (callback) => child.onExit((event) => callback(event.exitCode, event.signal)),\n\t\twrite: (data) => child.write(data),\n\t\tresize: (cols, rows) => child.resize(cols, rows),\n\t\tkill: (signal) => child.kill(signal),\n\t};\n}\n\n/**\n * Resolve node-pty at runtime, prebuilt-first (node-pty's own packaging\n * prefers prebuilds via prebuild-install). Lookup order: explicit\n * ION_PTY_MODULE override path first, then the \"node-pty\" package.\n * Never throws: failure returns an actionable hint instead.\n */\nexport function resolveNodePty(options: ResolveNodePtyOptions = {}): PtyResolution {\n\tconst loadModule = options.loadModule ?? defaultLoadModule;\n\tconst env = options.env ?? process.env;\n\tconst override = env.ION_PTY_MODULE?.trim();\n\tconst candidates = override ? [override, \"node-pty\"] : [\"node-pty\"];\n\tconst failures: string[] = [];\n\tfor (const candidate of candidates) {\n\t\ttry {\n\t\t\tconst loaded = loadModule(candidate) as Partial<NodePtyModule> | undefined;\n\t\t\tif (loaded && typeof loaded.spawn === \"function\") {\n\t\t\t\tconst moduleRef = loaded as NodePtyModule;\n\t\t\t\treturn {\n\t\t\t\t\tavailable: true,\n\t\t\t\t\tsource: candidate,\n\t\t\t\t\tspawn: (spawnOptions) => adaptNodePty(moduleRef, spawnOptions),\n\t\t\t\t};\n\t\t\t}\n\t\t\tfailures.push(`${candidate}: module loaded but has no spawn() export`);\n\t\t} catch (error) {\n\t\t\tfailures.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);\n\t\t}\n\t}\n\treturn { available: false, hint: buildNodePtyHint(failures) };\n}\n\n/** Thrown by createPtyHost when node-pty is unavailable. Carries the install hint as message. */\nexport class PtyHostUnavailableError extends Error {\n\tconstructor(hint: string) {\n\t\tsuper(hint);\n\t\tthis.name = \"PtyHostUnavailableError\";\n\t}\n}\n\nexport interface PtyHostOptions {\n\t/** Stock TUI binary to spawn inside the PTY (host never rewrites the TUI). */\n\tcommand: string;\n\targs?: string[];\n\tcols: number;\n\trows: number;\n\tcwd?: string;\n\tenv?: NodeJS.ProcessEnv;\n\t/** TERM value for the PTY slave. */\n\tname?: string;\n\t/** Replay journal cap in bytes. Defaults to PTY_HOST_JOURNAL_LIMIT_BYTES. */\n\tjournalLimitBytes?: number;\n\t/** Injected backend. Production callers omit this and go through createPtyHost. */\n\tspawn: PtySpawnFn;\n\t/** Convenience exit listener, equivalent to onExit(). */\n\tonExit?: (exitCode: number, signal: number | undefined) => void;\n}\n\nexport type CreatePtyHostOptions = Omit<PtyHostOptions, \"spawn\"> & {\n\tspawn?: PtySpawnFn;\n\tresolveOptions?: ResolveNodePtyOptions;\n};\n\nfunction requireSpawn(resolveOptions?: ResolveNodePtyOptions): PtySpawnFn {\n\tconst resolution = resolveNodePty(resolveOptions);\n\tif (!resolution.available) {\n\t\tthrow new PtyHostUnavailableError(resolution.hint);\n\t}\n\treturn resolution.spawn;\n}\n\n/**\n * Create a host, resolving node-pty unless the caller injects a backend.\n * Throws PtyHostUnavailableError (message = install hint) when no PTY\n * binary resolves; callers fall back to the plain terminal path.\n */\nexport function createPtyHost(options: CreatePtyHostOptions): PtyHost {\n\tconst spawn = options.spawn ?? requireSpawn(options.resolveOptions);\n\treturn new PtyHost({ ...options, spawn });\n}\n\n/** Owner callback receiving PTY master output bytes verbatim. */\nexport type PtyOwnerCallback = (data: string) => void;\n\n/** PTY child exit listener. */\nexport type PtyExitCallback = (exitCode: number, signal: number | undefined) => void;\n\n/**\n * In-process owner of one PTY-hosted TUI session. Byte relay is fully\n * transparent in both directions: the host never interprets owner input\n * (Ctrl+C arrives as 0x03, escape sequences pass through untouched) and\n * forwards child output verbatim. Raw-mode passthrough mirrors the owner\n * raw state to backends that support it; it never gates the byte stream.\n */\nexport class PtyHost {\n\tprivate readonly backend: PtyBackend;\n\tprivate readonly journalLimit: number;\n\tprivate owner: PtyOwnerCallback | undefined;\n\tprivate readonly exitListeners = new Set<PtyExitCallback>();\n\tprivate colsValue: number;\n\tprivate rowsValue: number;\n\tprivate rawModeValue = false;\n\tprivate disposedValue = false;\n\tprivate exitedValue = false;\n\tprivate exitCodeValue: number | undefined;\n\tprivate journal: string[] = [];\n\tprivate journalBytes = 0;\n\tprivate detachChunkIndex: number | undefined;\n\tprivate detachOverflow = false;\n\n\tconstructor(options: PtyHostOptions) {\n\t\tassertPtyDimensions(options.cols, options.rows);\n\t\tthis.colsValue = options.cols;\n\t\tthis.rowsValue = options.rows;\n\t\tthis.journalLimit = options.journalLimitBytes ?? PTY_HOST_JOURNAL_LIMIT_BYTES;\n\t\tif (options.onExit) {\n\t\t\tthis.exitListeners.add(options.onExit);\n\t\t}\n\t\tthis.backend = options.spawn({\n\t\t\tcommand: options.command,\n\t\t\targs: options.args ? [...options.args] : [],\n\t\t\tcols: options.cols,\n\t\t\trows: options.rows,\n\t\t\tcwd: options.cwd ?? process.cwd(),\n\t\t\tenv: options.env ?? process.env,\n\t\t\tname: options.name ?? \"xterm-256color\",\n\t\t});\n\t\tthis.backend.onData((data) => this.handleBackendData(data));\n\t\tthis.backend.onExit((exitCode, signal) => this.handleBackendExit(exitCode, signal));\n\t}\n\n\tget cols(): number {\n\t\treturn this.colsValue;\n\t}\n\n\tget rows(): number {\n\t\treturn this.rowsValue;\n\t}\n\n\tget pid(): number {\n\t\treturn this.backend.pid;\n\t}\n\n\tget isAttached(): boolean {\n\t\treturn this.owner !== undefined;\n\t}\n\n\tget isDetached(): boolean {\n\t\treturn !this.disposedValue && this.owner === undefined;\n\t}\n\n\tget isDisposed(): boolean {\n\t\treturn this.disposedValue;\n\t}\n\n\tget exited(): boolean {\n\t\treturn this.exitedValue;\n\t}\n\n\tget exitCode(): number | undefined {\n\t\treturn this.exitCodeValue;\n\t}\n\n\tget rawMode(): boolean {\n\t\treturn this.rawModeValue;\n\t}\n\n\t/** Initial owner attach. Throws when already attached or disposed. */\n\tattach(owner: PtyOwnerCallback): void {\n\t\tthis.throwIfDisposed();\n\t\tif (this.owner) {\n\t\t\tthrow new Error(\"PtyHost already has an owner; detach first\");\n\t\t}\n\t\tthis.owner = owner;\n\t}\n\n\t/** Owner disconnects; the PTY session keeps running and output is journaled. Idempotent. */\n\tdetach(): void {\n\t\tthis.throwIfDisposed();\n\t\tthis.owner = undefined;\n\t\tthis.detachChunkIndex = this.journal.length;\n\t\tthis.detachOverflow = false;\n\t}\n\n\t/**\n\t * New owner attaches and immediately receives everything journaled\n\t * while detached (the current screen state, best-effort). A same-dims\n\t * resize nudges the child to repaint first. Throws when an owner is\n\t * already attached or the host is disposed.\n\t */\n\treattach(owner: PtyOwnerCallback): void {\n\t\tthis.throwIfDisposed();\n\t\tif (this.owner) {\n\t\t\tthrow new Error(\"PtyHost already has an owner; detach first\");\n\t\t}\n\t\tif (this.detachChunkIndex === undefined) {\n\t\t\tthis.owner = owner;\n\t\t\treturn;\n\t\t}\n\t\tconst replay = this.detachOverflow\n\t\t\t? PTY_RESYNC_SEQUENCE + this.journal.join(\"\")\n\t\t\t: this.journal.slice(this.detachChunkIndex).join(\"\");\n\t\tthis.detachChunkIndex = undefined;\n\t\tthis.detachOverflow = false;\n\t\tif (!this.exitedValue) {\n\t\t\tthis.backend.resize(this.colsValue, this.rowsValue);\n\t\t}\n\t\tthis.owner = owner;\n\t\tif (replay.length > 0) {\n\t\t\towner(replay);\n\t\t}\n\t}\n\n\t/**\n\t * Owner input reaches the PTY byte-transparent. Dropped while\n\t * detached (no owner exists to produce input); throws after dispose.\n\t */\n\twrite(data: string): void {\n\t\tthis.throwIfDisposed();\n\t\tif (!this.owner) return;\n\t\tthis.backend.write(data);\n\t}\n\n\t/**\n\t * Forward owner resize events to the PTY (setWinSize semantics); the\n\t * stock TUI re-layouts to the new dimensions itself.\n\t */\n\tresize(cols: number, rows: number): void {\n\t\tthis.throwIfDisposed();\n\t\tassertPtyDimensions(cols, rows);\n\t\tthis.colsValue = cols;\n\t\tthis.rowsValue = rows;\n\t\tif (!this.exitedValue) {\n\t\t\tthis.backend.resize(cols, rows);\n\t\t}\n\t}\n\n\t/**\n\t * Mirror owner raw-mode state to the backend when it supports it.\n\t * Returns whether the backend honored the request. The byte stream\n\t * is never gated on this flag.\n\t */\n\tsetRawMode(active: boolean): boolean {\n\t\tthis.throwIfDisposed();\n\t\tthis.rawModeValue = active;\n\t\tif (typeof this.backend.setRawMode === \"function\") {\n\t\t\tthis.backend.setRawMode(active);\n\t\t\treturn true;\n\t\t}\n\t\treturn false;\n\t}\n\n\t/** Subscribe to PTY child exit. Returns an unsubscribe function. */\n\tonExit(callback: PtyExitCallback): () => void {\n\t\tthis.exitListeners.add(callback);\n\t\treturn () => {\n\t\t\tthis.exitListeners.delete(callback);\n\t\t};\n\t}\n\n\t/** Kill the PTY session and release the owner. Idempotent. */\n\tdispose(): void {\n\t\tif (this.disposedValue) return;\n\t\tthis.disposedValue = true;\n\t\tthis.owner = undefined;\n\t\tthis.exitListeners.clear();\n\t\ttry {\n\t\t\tthis.backend.kill();\n\t\t} catch {\n\t\t\t// Backend already gone; dispose still releases host state.\n\t\t}\n\t}\n\n\tprivate handleBackendData(data: string): void {\n\t\tthis.appendJournal(data);\n\t\tthis.owner?.(data);\n\t}\n\n\tprivate handleBackendExit(exitCode: number, signal: number | undefined): void {\n\t\tif (this.disposedValue) return;\n\t\tthis.exitedValue = true;\n\t\tthis.exitCodeValue = exitCode;\n\t\tfor (const listener of this.exitListeners) {\n\t\t\tlistener(exitCode, signal);\n\t\t}\n\t}\n\n\tprivate appendJournal(data: string): void {\n\t\tif (this.journalLimit <= 0 || data.length === 0) return;\n\t\tthis.journal.push(data);\n\t\tthis.journalBytes += data.length;\n\t\twhile (this.journal.length > 1 && this.journalBytes > this.journalLimit) {\n\t\t\tconst dropped = this.journal.shift() as string;\n\t\t\tthis.journalBytes -= dropped.length;\n\t\t\tif (this.detachChunkIndex !== undefined) {\n\t\t\t\tif (this.detachChunkIndex > 0) {\n\t\t\t\t\tthis.detachChunkIndex -= 1;\n\t\t\t\t} else {\n\t\t\t\t\tthis.detachOverflow = true;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate throwIfDisposed(): void {\n\t\tif (this.disposedValue) {\n\t\t\tthrow new Error(\"PtyHost is disposed\");\n\t\t}\n\t}\n}\n"]}

package/dist/pty-host.js

@@ -0,0 +1,347 @@
+/**
+ * PTY host spike (tui-overhaul 1.1-1.5).
+ *
+ * Spawns the stock ion TUI inside a pseudoterminal and relays bytes
+ * bidirectionally between the PTY master and the session owner. The TUI
+ * itself stays raw-terminal plus alt-screen and is never rewritten for
+ * hosting: this mirrors the Claude Code seam where a separate server hosts
+ * the stock TUI under node-pty (see TUI.claude.md section 1.4).
+ *
+ * Seam rules (pinned by test/pty-host.test.ts):
+ * - The core TUI (index.ts, terminal.ts, tui.ts) never imports this module.
+ * - node-pty resolves at runtime with prebuilt-first lookup; when no binary
+ *   is available the caller gets an actionable install hint and the plain
+ *   terminal path keeps working.
+ *
+ * Transport decision (task 1.5): in-process handle. A Unix-socket transport
+ * would only pay off for reattach-across-process, which no consumer needs
+ * yet (the future session-share viewer attaches in-process). Sockets would
+ * add framing, auth, and lifecycle management for zero current benefit, so
+ * the host is a plain object owning its PTY child. Revisit when an
+ * out-of-process attacher arrives.
+ *
+ * Reattach replay is best-effort byte replay: the host journals PTY output
+ * in a bounded ring and, on reattach, nudges the child with a same-dims
+ * resize (SIGWINCH repaint, the setWinSize semantic) then replays everything
+ * journaled while detached. A terminal-emulator-backed screen dump is
+ * future work, not part of this spike.
+ *
+ * Minimum dimensions stay an open product question: the spike validates
+ * positive integers only. Layouts below ~40 columns are known to degrade
+ * (the 40x12 golden case pins bounded behavior, not beauty).
+ */
+import { createRequire } from "node:module";
+const moduleRequire = createRequire(import.meta.url);
+/** Transport backing session handles. Pinned to in-process by the task 1.5 decision above. */
+export const PTY_HOST_TRANSPORT = "in-process";
+/** Default cap for the reattach replay journal. */
+export const PTY_HOST_JOURNAL_LIMIT_BYTES = 256 * 1024;
+/**
+ * Resync prefix used only when the journal overflowed while detached and
+ * replay can no longer continue the previous screen state.
+ */
+export const PTY_RESYNC_SEQUENCE = "\x1b[2J\x1b[H";
+/** Throw unless cols/rows are positive integers. Integers only: fractional cells do not exist. */
+export function assertPtyDimensions(cols, rows) {
+    if (!Number.isInteger(cols) || cols < 1) {
+        throw new RangeError(`PTY cols must be a positive integer, got ${cols}`);
+    }
+    if (!Number.isInteger(rows) || rows < 1) {
+        throw new RangeError(`PTY rows must be a positive integer, got ${rows}`);
+    }
+}
+function defaultLoadModule(specifier) {
+    return moduleRequire(specifier);
+}
+function buildNodePtyHint(failures) {
+    const lines = [
+        "node-pty is unavailable and the PTY host cannot start.",
+        "Install it with `npm install node-pty` (prebuilt binaries are used when available;",
+        "building from source needs python3, make, and g++).",
+        "Set ION_PTY_MODULE to load node-pty from a custom path.",
+        "The plain terminal path keeps working without it.",
+    ];
+    if (failures.length > 0) {
+        lines.push(`Looked up: ${failures.join("; ")}`);
+    }
+    return lines.join(" ");
+}
+function adaptNodePty(moduleRef, options) {
+    const child = moduleRef.spawn(options.command, options.args, {
+        name: options.name,
+        cols: options.cols,
+        rows: options.rows,
+        cwd: options.cwd,
+        env: options.env,
+    });
+    return {
+        pid: child.pid,
+        onData: (callback) => child.onData(callback),
+        onExit: (callback) => child.onExit((event) => callback(event.exitCode, event.signal)),
+        write: (data) => child.write(data),
+        resize: (cols, rows) => child.resize(cols, rows),
+        kill: (signal) => child.kill(signal),
+    };
+}
+/**
+ * Resolve node-pty at runtime, prebuilt-first (node-pty's own packaging
+ * prefers prebuilds via prebuild-install). Lookup order: explicit
+ * ION_PTY_MODULE override path first, then the "node-pty" package.
+ * Never throws: failure returns an actionable hint instead.
+ */
+export function resolveNodePty(options = {}) {
+    const loadModule = options.loadModule ?? defaultLoadModule;
+    const env = options.env ?? process.env;
+    const override = env.ION_PTY_MODULE?.trim();
+    const candidates = override ? [override, "node-pty"] : ["node-pty"];
+    const failures = [];
+    for (const candidate of candidates) {
+        try {
+            const loaded = loadModule(candidate);
+            if (loaded && typeof loaded.spawn === "function") {
+                const moduleRef = loaded;
+                return {
+                    available: true,
+                    source: candidate,
+                    spawn: (spawnOptions) => adaptNodePty(moduleRef, spawnOptions),
+                };
+            }
+            failures.push(`${candidate}: module loaded but has no spawn() export`);
+        }
+        catch (error) {
+            failures.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { available: false, hint: buildNodePtyHint(failures) };
+}
+/** Thrown by createPtyHost when node-pty is unavailable. Carries the install hint as message. */
+export class PtyHostUnavailableError extends Error {
+    constructor(hint) {
+        super(hint);
+        this.name = "PtyHostUnavailableError";
+    }
+}
+function requireSpawn(resolveOptions) {
+    const resolution = resolveNodePty(resolveOptions);
+    if (!resolution.available) {
+        throw new PtyHostUnavailableError(resolution.hint);
+    }
+    return resolution.spawn;
+}
+/**
+ * Create a host, resolving node-pty unless the caller injects a backend.
+ * Throws PtyHostUnavailableError (message = install hint) when no PTY
+ * binary resolves; callers fall back to the plain terminal path.
+ */
+export function createPtyHost(options) {
+    const spawn = options.spawn ?? requireSpawn(options.resolveOptions);
+    return new PtyHost({ ...options, spawn });
+}
+/**
+ * In-process owner of one PTY-hosted TUI session. Byte relay is fully
+ * transparent in both directions: the host never interprets owner input
+ * (Ctrl+C arrives as 0x03, escape sequences pass through untouched) and
+ * forwards child output verbatim. Raw-mode passthrough mirrors the owner
+ * raw state to backends that support it; it never gates the byte stream.
+ */
+export class PtyHost {
+    backend;
+    journalLimit;
+    owner;
+    exitListeners = new Set();
+    colsValue;
+    rowsValue;
+    rawModeValue = false;
+    disposedValue = false;
+    exitedValue = false;
+    exitCodeValue;
+    journal = [];
+    journalBytes = 0;
+    detachChunkIndex;
+    detachOverflow = false;
+    constructor(options) {
+        assertPtyDimensions(options.cols, options.rows);
+        this.colsValue = options.cols;
+        this.rowsValue = options.rows;
+        this.journalLimit = options.journalLimitBytes ?? PTY_HOST_JOURNAL_LIMIT_BYTES;
+        if (options.onExit) {
+            this.exitListeners.add(options.onExit);
+        }
+        this.backend = options.spawn({
+            command: options.command,
+            args: options.args ? [...options.args] : [],
+            cols: options.cols,
+            rows: options.rows,
+            cwd: options.cwd ?? process.cwd(),
+            env: options.env ?? process.env,
+            name: options.name ?? "xterm-256color",
+        });
+        this.backend.onData((data) => this.handleBackendData(data));
+        this.backend.onExit((exitCode, signal) => this.handleBackendExit(exitCode, signal));
+    }
+    get cols() {
+        return this.colsValue;
+    }
+    get rows() {
+        return this.rowsValue;
+    }
+    get pid() {
+        return this.backend.pid;
+    }
+    get isAttached() {
+        return this.owner !== undefined;
+    }
+    get isDetached() {
+        return !this.disposedValue && this.owner === undefined;
+    }
+    get isDisposed() {
+        return this.disposedValue;
+    }
+    get exited() {
+        return this.exitedValue;
+    }
+    get exitCode() {
+        return this.exitCodeValue;
+    }
+    get rawMode() {
+        return this.rawModeValue;
+    }
+    /** Initial owner attach. Throws when already attached or disposed. */
+    attach(owner) {
+        this.throwIfDisposed();
+        if (this.owner) {
+            throw new Error("PtyHost already has an owner; detach first");
+        }
+        this.owner = owner;
+    }
+    /** Owner disconnects; the PTY session keeps running and output is journaled. Idempotent. */
+    detach() {
+        this.throwIfDisposed();
+        this.owner = undefined;
+        this.detachChunkIndex = this.journal.length;
+        this.detachOverflow = false;
+    }
+    /**
+     * New owner attaches and immediately receives everything journaled
+     * while detached (the current screen state, best-effort). A same-dims
+     * resize nudges the child to repaint first. Throws when an owner is
+     * already attached or the host is disposed.
+     */
+    reattach(owner) {
+        this.throwIfDisposed();
+        if (this.owner) {
+            throw new Error("PtyHost already has an owner; detach first");
+        }
+        if (this.detachChunkIndex === undefined) {
+            this.owner = owner;
+            return;
+        }
+        const replay = this.detachOverflow
+            ? PTY_RESYNC_SEQUENCE + this.journal.join("")
+            : this.journal.slice(this.detachChunkIndex).join("");
+        this.detachChunkIndex = undefined;
+        this.detachOverflow = false;
+        if (!this.exitedValue) {
+            this.backend.resize(this.colsValue, this.rowsValue);
+        }
+        this.owner = owner;
+        if (replay.length > 0) {
+            owner(replay);
+        }
+    }
+    /**
+     * Owner input reaches the PTY byte-transparent. Dropped while
+     * detached (no owner exists to produce input); throws after dispose.
+     */
+    write(data) {
+        this.throwIfDisposed();
+        if (!this.owner)
+            return;
+        this.backend.write(data);
+    }
+    /**
+     * Forward owner resize events to the PTY (setWinSize semantics); the
+     * stock TUI re-layouts to the new dimensions itself.
+     */
+    resize(cols, rows) {
+        this.throwIfDisposed();
+        assertPtyDimensions(cols, rows);
+        this.colsValue = cols;
+        this.rowsValue = rows;
+        if (!this.exitedValue) {
+            this.backend.resize(cols, rows);
+        }
+    }
+    /**
+     * Mirror owner raw-mode state to the backend when it supports it.
+     * Returns whether the backend honored the request. The byte stream
+     * is never gated on this flag.
+     */
+    setRawMode(active) {
+        this.throwIfDisposed();
+        this.rawModeValue = active;
+        if (typeof this.backend.setRawMode === "function") {
+            this.backend.setRawMode(active);
+            return true;
+        }
+        return false;
+    }
+    /** Subscribe to PTY child exit. Returns an unsubscribe function. */
+    onExit(callback) {
+        this.exitListeners.add(callback);
+        return () => {
+            this.exitListeners.delete(callback);
+        };
+    }
+    /** Kill the PTY session and release the owner. Idempotent. */
+    dispose() {
+        if (this.disposedValue)
+            return;
+        this.disposedValue = true;
+        this.owner = undefined;
+        this.exitListeners.clear();
+        try {
+            this.backend.kill();
+        }
+        catch {
+            // Backend already gone; dispose still releases host state.
+        }
+    }
+    handleBackendData(data) {
+        this.appendJournal(data);
+        this.owner?.(data);
+    }
+    handleBackendExit(exitCode, signal) {
+        if (this.disposedValue)
+            return;
+        this.exitedValue = true;
+        this.exitCodeValue = exitCode;
+        for (const listener of this.exitListeners) {
+            listener(exitCode, signal);
+        }
+    }
+    appendJournal(data) {
+        if (this.journalLimit <= 0 || data.length === 0)
+            return;
+        this.journal.push(data);
+        this.journalBytes += data.length;
+        while (this.journal.length > 1 && this.journalBytes > this.journalLimit) {
+            const dropped = this.journal.shift();
+            this.journalBytes -= dropped.length;
+            if (this.detachChunkIndex !== undefined) {
+                if (this.detachChunkIndex > 0) {
+                    this.detachChunkIndex -= 1;
+                }
+                else {
+                    this.detachOverflow = true;
+                }
+            }
+        }
+    }
+    throwIfDisposed() {
+        if (this.disposedValue) {
+            throw new Error("PtyHost is disposed");
+        }
+    }
+}
+//# sourceMappingURL=pty-host.js.map