@oh-my-pi/pi-tui 17.4.0 → 17.4.2

package/dist/types/components/editor.d.ts

@@ -120,6 +120,15 @@ export declare class Editor implements Component, Focusable {
     /** Whether the buffer text equals `value`, without `getText()`'s full join —
      *  O(1) for the hot per-keystroke probes against short single-line values. */
     textEquals(value: string): boolean;
+    /** Register `label` as a collapsed atom expanding to `expansion` on submit, without inserting
+     *  it — for hosts that re-collapse restored draft text via {@link setText}. */
+    registerAtom(label: string, expansion: string): void;
+    /** Insert `label` (plus a trailing space) at the cursor and register it as an atom expanding
+     *  to `expansion` on submit. Pair with {@link atomicTokenPattern} so the label deletes as a
+     *  unit. */
+    insertAtom(label: string, expansion: string): void;
+    /** Drop every registered atom expansion (draft cleared or replaced by the host). */
+    clearAtoms(): void;
     /**
      * Get text with paste markers expanded to their actual content.
      * Use this when you need the full content (e.g., for external editor).

package/dist/types/tui.d.ts

@@ -98,6 +98,13 @@ export interface NativeScrollbackLiveRegion {
     getNativeScrollbackLiveRegionStart(): number | undefined;
     /** Keeps the mutable suffix viewport-local instead of recording frozen snapshots. */
     isNativeScrollbackLiveRegionPinned?(): boolean;
+    /**
+     * Local row where viewport pinning begins. When omitted, pinning (if
+     * reported) starts at {@link getNativeScrollbackLiveRegionStart}. A nested
+     * transcript uses this to keep an earlier unpinned live seam while still
+     * capping commits at a later pinned dashboard (hub wait, todo snapshot).
+     */
+    getNativeScrollbackLiveRegionPinnedStart?(): number | undefined;
 }
 export interface NativeScrollbackCommittedRows {
     setNativeScrollbackCommittedRows(rows: number): void;

package/package.json

@@ -1,10 +1,10 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "17.4.0",
+	"version": "17.4.2",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
-	"author": "Can Boluk",
+	"author": "Stencil Labs, Inc.",
 	"contributors": [
 		"Mario Zechner"
 	],
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "17.4.0",
-		"@oh-my-pi/pi-utils": "17.4.0"
+		"@oh-my-pi/pi-natives": "17.4.2",
+		"@oh-my-pi/pi-utils": "17.4.2"
 	},
 	"devDependencies": {
 		"ghostty-web": "^0.4.0"
@@ -50,6 +50,8 @@
 		"src",
 		"README.md",
 		"CHANGELOG.md",
+		"LICENSE",
+		"THIRD-PARTY-NOTICES.txt",
 		"dist/types"
 	],
 	"exports": {

package/src/components/editor.ts

@@ -484,6 +484,9 @@ export class Editor implements Component, Focusable {
 	#pastes: Map<number, string> = new Map();
 	#pasteCounter: number = 0;
 
+	// Host-registered atomic chip tokens: exact buffer label → expansion emitted on submit.
+	#atoms: Map<string, string> = new Map();
+
 	/** Optional pattern matching atomic placeholder tokens (e.g. `[Image #1, 800x600]` or
 	 *  `[Paste #2, +30 lines]`) that the editor treats as indivisible: a backspace or forward-delete
 	 *  landing on any character of a token removes the whole token instead of corrupting it into
@@ -1752,13 +1755,48 @@ export class Editor implements Component, Focusable {
 		return this.getText() === value;
 	}
 
+	/** Expand collapsed markers — `[Paste #N]` tokens and registered atom labels — into their
+	 *  stored content. Single pass so replaced content is never rescanned (a pasted body that
+	 *  happens to contain another token's label must survive verbatim). Longer atom labels are
+	 *  tried first so `#1` never shadows `#10`. */
 	#expandPasteMarkers(text: string): string {
-		let result = text;
-		for (const [pasteId, pasteContent] of this.#pastes) {
-			const markerRegex = new RegExp(`\\[Paste #${pasteId}(?:, (?:\\+\\d+ lines|\\d+ chars))?\\]`, "g");
-			result = result.replace(markerRegex, () => pasteContent);
-		}
-		return result;
+		const sources: string[] = [];
+		for (const pasteId of this.#pastes.keys()) {
+			sources.push(`\\[Paste #${pasteId}(?:, (?:\\+\\d+ lines|\\d+ chars))?\\]`);
+		}
+		const labels = [...this.#atoms.keys()].sort((a, b) => b.length - a.length);
+		for (const label of labels) sources.push(RegExp.escape(label));
+		if (sources.length === 0) return text;
+		const markerRegex = new RegExp(sources.join("|"), "g");
+		return text.replace(markerRegex, match => {
+			const paste = /^\[Paste #(\d+)/.exec(match);
+			if (paste) return this.#pastes.get(Number(paste[1])) ?? match;
+			return this.#atoms.get(match) ?? match;
+		});
+	}
+
+	/** Register `label` as a collapsed atom expanding to `expansion` on submit, without inserting
+	 *  it — for hosts that re-collapse restored draft text via {@link setText}. */
+	registerAtom(label: string, expansion: string): void {
+		this.#atoms.set(label, expansion);
+	}
+
+	/** Insert `label` (plus a trailing space) at the cursor and register it as an atom expanding
+	 *  to `expansion` on submit. Pair with {@link atomicTokenPattern} so the label deletes as a
+	 *  unit. */
+	insertAtom(label: string, expansion: string): void {
+		this.#historyIndex = -1;
+		this.#resetKillSequence();
+		this.#recordUndoState();
+		this.registerAtom(label, expansion);
+		this.#withUndoSuspended(() => {
+			this.#insertTextAtCursor(`${label} `);
+		});
+	}
+
+	/** Drop every registered atom expansion (draft cleared or replaced by the host). */
+	clearAtoms(): void {
+		this.#atoms.clear();
 	}
 
 	/**
@@ -2213,6 +2251,7 @@ export class Editor implements Component, Focusable {
 		this.#state = { lines: [""], cursorLine: 0, cursorCol: 0 };
 		this.#pastes.clear();
 		this.#pasteCounter = 0;
+		this.#atoms.clear();
 		this.#historyIndex = -1;
 		this.#scrollOffset = 0;
 		this.#undoStack.length = 0;

package/src/tui.ts

@@ -216,6 +216,13 @@ export interface NativeScrollbackLiveRegion {
 	getNativeScrollbackLiveRegionStart(): number | undefined;
 	/** Keeps the mutable suffix viewport-local instead of recording frozen snapshots. */
 	isNativeScrollbackLiveRegionPinned?(): boolean;
+	/**
+	 * Local row where viewport pinning begins. When omitted, pinning (if
+	 * reported) starts at {@link getNativeScrollbackLiveRegionStart}. A nested
+	 * transcript uses this to keep an earlier unpinned live seam while still
+	 * capping commits at a later pinned dashboard (hub wait, todo snapshot).
+	 */
+	getNativeScrollbackLiveRegionPinnedStart?(): number | undefined;
 }
 
 export interface NativeScrollbackCommittedRows {
@@ -278,6 +285,13 @@ function getNativeScrollbackLiveRegionStart(component: Component): number | unde
 	return (component as Component & Partial<NativeScrollbackLiveRegion>).getNativeScrollbackLiveRegionStart?.();
 }
 
+function getNativeScrollbackLiveRegionPinnedStart(component: Component): number | undefined {
+	const start = (
+		component as Component & Partial<NativeScrollbackLiveRegion>
+	).getNativeScrollbackLiveRegionPinnedStart?.();
+	return start === undefined || !Number.isFinite(start) ? undefined : start;
+}
+
 /**
  * Opt-in stability report for components that mutate their returned render
  * array in place across frames (instead of returning a fresh array per
@@ -901,6 +915,8 @@ interface FrameSegment {
 	widthEpochRevision?: number;
 	liveLocalStart?: number;
 	liveRegionPinned: boolean;
+	/** Local pin start; when omitted, pinning begins at `liveLocalStart`. */
+	liveRegionPinnedStart?: number;
 }
 
 /** Depth-first identity search through `Container`-shaped children. */
@@ -1372,6 +1388,13 @@ export class TUI extends Container {
 	#multiplexerResizeTimer: RenderTimer | undefined;
 	#deferredForcedClearScrollback = false;
 	#multiplexerResizeHasPendingRender = false;
+	// Rows a mux pane pushed into its own scrollback on a height-only shrink
+	// without the engine committing them, plus the commit seam at push time.
+	// A later height grow pulls the pane's scrollback tail back into the grid:
+	// the pushed rows come out first — but only while no commit has buried
+	// them — and only the remainder of the pull removes committed rows.
+	#muxPushedRows = 0;
+	#muxPushSeam = 0;
 	// True from the first SIGWINCH of a non-multiplexer drag until the settle
 	// timer fires. While set, every `#doRender` short-circuits to the viewport
 	// fast path (`#renderResizeViewport`) instead of an authoritative full
@@ -1661,12 +1684,14 @@ export class TUI extends Container {
 			let childLines: readonly string[];
 			let liveLocalStart: number | undefined;
 			let liveRegionPinned = false;
+			let liveRegionPinnedStart: number | undefined;
 			let widthEpochRevision: number | undefined;
 			let reported: number | undefined;
 			if (reuse) {
 				childLines = previous.lines;
 				liveLocalStart = previous.liveLocalStart;
 				liveRegionPinned = previous.liveRegionPinned;
+				liveRegionPinnedStart = previous.liveRegionPinnedStart;
 				widthEpochRevision = previous.widthEpochRevision;
 			} else {
 				// Feed the engine's committed-row claim (from the previous frame's
@@ -1697,6 +1722,15 @@ export class TUI extends Container {
 					liveRegionPinned =
 						(child as Component & Partial<NativeScrollbackLiveRegion>).isNativeScrollbackLiveRegionPinned?.() ===
 						true;
+					if (liveRegionPinned) {
+						const pinStart = getNativeScrollbackLiveRegionPinnedStart(child);
+						if (pinStart !== undefined) {
+							liveRegionPinnedStart = Math.max(
+								liveLocalStart,
+								Math.min(childLines.length, Math.trunc(pinStart)),
+							);
+						}
+					}
 				}
 				// Consume the stability report unconditionally for implementers:
 				// reading re-bases the component's baseline to the state this
@@ -1722,7 +1756,7 @@ export class TUI extends Container {
 				// even when an earlier unpinned seam won the topmost merge above:
 				// its rows (a growing anchored panel) must never reach scrollback.
 				if (liveRegionPinned && this.#nativeScrollbackPinnedBoundary === undefined) {
-					this.#nativeScrollbackPinnedBoundary = start;
+					this.#nativeScrollbackPinnedBoundary = offset + (liveRegionPinnedStart ?? liveLocalStart);
 				}
 			}
 			if (chainStable) {
@@ -1754,6 +1788,7 @@ export class TUI extends Container {
 				widthEpochRevision,
 				liveLocalStart,
 				liveRegionPinned,
+				liveRegionPinnedStart,
 			};
 			offset += childLines.length;
 		}
@@ -3761,6 +3796,37 @@ export class TUI extends Container {
 			!isMultiplexerSession() &&
 			(committedRowsResynced || frameLength <= this.#committedRows);
 		const fullPaint = firstPaint || replaceRequested || geometryRebuild || divergenceRebuild;
+		// Height-only mux resizes move rows between the pane's scrollback and its
+		// grid. A shrink with a full grid pushes the grid-top rows into pane
+		// scrollback without a commit; a grow pulls the scrollback tail back into
+		// the grid, where the forced in-place window rewrite overwrites it — gone
+		// from history. The scrollback is a stack: pushed rows sit at the tail
+		// only until the next commit buries them, so they shield a pull only
+		// while the commit seam has not moved since the push. The unshielded
+		// remainder removes committed rows — drop the commit seam by it and let
+		// the next chunk re-commit them. A short frame gains blank rows instead
+		// of pulling.
+		if (fullPaint || widthChanged) {
+			this.#muxPushedRows = 0;
+		} else if (
+			geometryChanged &&
+			this.#previousHeight > 0 &&
+			this.#previousFrameLength - this.#windowTopRow >= this.#previousHeight
+		) {
+			if (this.#committedRows !== this.#muxPushSeam) this.#muxPushedRows = 0;
+			if (height < this.#previousHeight) {
+				this.#muxPushedRows += this.#previousHeight - height;
+				this.#muxPushSeam = this.#committedRows;
+			} else if (height > this.#previousHeight) {
+				const pull = height - this.#previousHeight;
+				const fromPushed = Math.min(pull, this.#muxPushedRows);
+				this.#muxPushedRows -= fromPushed;
+				const fromCommitted = Math.min(pull - fromPushed, this.#committedRows);
+				this.#committedRows -= fromCommitted;
+				this.#committedPrefix.length = this.#committedRows;
+				this.#muxPushSeam = this.#committedRows;
+			}
+		}
 		let windowTop: number;
 		let chunkTo: number;
 		let widthEpochAppendFrom = 0;
@@ -3828,11 +3894,23 @@ export class TUI extends Container {
 			// the viewport. Rebase the commit seam to that exposed frame tail before
 			// the forced rewrite; flooring at the old seam would paint only the live
 			// suffix followed by blanks, then preserve that gap on every stream tick.
-			committedPrefixResliced = true;
 			windowTop = Math.max(0, frameLength - height);
 			chunkTo = windowTop;
 			this.#committedRows = windowTop;
-			this.#committedPrefix = rawFrame.slice(0, windowTop);
+			if (widthChanged) {
+				// A rewrap invalidated the recorded bytes: re-base the audit prefix
+				// at the new width so the accepted wrap drift does not read as a
+				// violation on the next ordinary frame.
+				committedPrefixResliced = true;
+				this.#committedPrefix = rawFrame.slice(0, windowTop);
+			} else {
+				// Height-only reflow: the pane did not rewrap, so the recorded
+				// bytes are still the true tape record. Truncate instead of
+				// reslicing from the current frame — replacing the record with
+				// live content would bless drifted frozen snapshots as verified
+				// and skip their finalize-time recommit (rows lost from history).
+				this.#committedPrefix.length = Math.min(this.#committedPrefix.length, windowTop);
+			}
 		} else {
 			// Re-anchor to the frame tail, floored at the committed boundary: a
 			// shrink (or overlay close) pulls the window back down, but never
@@ -3845,15 +3923,15 @@ export class TUI extends Container {
 			// record; nothing that was painted may vanish. Overlays freeze
 			// commits: composited rows must never enter history, and the hidden
 			// gap backfills via the chunk once the overlay closes. A multiplexer
-			// resize also commits nothing — the pane keeps its own (old-wrap)
-			// history — and re-bases the audit prefix at the new width so the
+			// resize also commits nothing — the pane keeps its own history — and
+			// a width rewrap re-bases the audit prefix at the new width so the
 			// accepted wrap drift does not read as a violation on the next
 			// ordinary frame.
 			chunkTo =
 				hasVisibleOverlay || geometryChanged
 					? this.#committedRows
 					: Math.min(windowTop, Math.max(this.#committedRows, commitCeiling));
-			if (geometryChanged) {
+			if (widthChanged) {
 				committedPrefixResliced = true;
 				this.#committedPrefix = rawFrame.slice(0, this.#committedRows);
 			}