@linxiraos/pi-tui 1.1.8 → 1.1.9

package/CHANGELOG.md

@@ -2,10 +2,9 @@
 
 ## [Unreleased]
 
-## [1.1.8] - 2026-09-04
+## [1.1.9] - 2026-09-05
 
-- Restored the sidebar gutter engine + `SidebarComponent` + `/sidebar` command (Zeta-only surface dropped by an earlier upstream merge).
-- OMP sync v18.1.2–v18.1.5: sub-frame history ownership (the frame provider owns history), CoW worktree cloning support, and renderer fixes.
+- Sidebar gutter: provider-render frames now honor the reserved main width and paint the right gutter column (sidebar was dead code in production since the frame-provider refactor); overlay close clears the painted column.
 
 ## [1.1.3] - 2026-08-25
 

package/package.json

@@ -1,72 +1,66 @@
 {
-	"type": "module",
-	"name": "@linxiraos/pi-tui",
-	"version": "1.1.8",
-	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
-	"homepage": "https://linxira-os.github.io/zeta/",
-	"author": "Stencil Labs, Inc.",
-	"contributors": [
-		"Mario Zechner"
-	],
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
-		"directory": "packages/tui"
-	},
-	"bugs": {
-		"url": "https://github.com/Linxira-OS/linxira-zeta/issues"
-	},
-	"keywords": [
-		"tui",
-		"terminal",
-		"ui",
-		"text-editor",
-		"differential-rendering",
-		"typescript",
-		"cli"
-	],
-	"main": "./src/index.ts",
-	"types": "./dist/types/index.d.ts",
-	"scripts": {
-		"check": "biome check . && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
-		"lint": "biome lint .",
-		"test": "bun test --parallel test/*.test.ts",
-		"fix": "biome check --write --unsafe .",
-		"fmt": "biome format --write ."
-	},
-	"dependencies": {
-		"@linxiraos/pi-natives": "1.1.8",
-		"@linxiraos/pi-utils": "1.1.8"
-	},
-	"devDependencies": {
-		"kitty-vt-wasm": "^0.2.0"
-	},
-	"engines": {
-		"bun": ">=1.3.14"
-	},
-	"files": [
-		"src",
-		"README.md",
-		"CHANGELOG.md",
-		"LICENSE",
-		"THIRD-PARTY-NOTICES.txt",
-		"dist/types"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/types/index.d.ts",
-			"import": "./src/index.ts"
-		},
-		"./*": {
-			"types": "./dist/types/*.d.ts",
-			"import": "./src/*.ts"
-		},
-		"./components/*": {
-			"types": "./dist/types/components/*.d.ts",
-			"import": "./src/components/*.ts"
-		},
-		"./*.js": "./src/*.ts"
-	}
+  "exports": {
+    "./*.js": "./src/*.ts",
+    "./components/*": {
+      "import": "./src/components/*.ts",
+      "types": "./src/components/*.ts"
+    },
+    "./*": {
+      "import": "./src/*.ts",
+      "types": "./src/*.ts"
+    },
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "devDependencies": {
+    "kitty-vt-wasm": "^0.2.0"
+  },
+  "dependencies": {
+    "@linxiraos/pi-utils": "1.1.9",
+    "@linxiraos/pi-natives": "1.1.9"
+  },
+  "scripts": {
+    "test": "bun test --parallel test/*.test.ts",
+    "check:types": "tsgo -p tsconfig.json --noEmit",
+    "check": "tsgo -p tsconfig.json --noEmit"
+  },
+  "types": "./src/index.ts",
+  "main": "./src/index.ts",
+  "keywords": [
+    "tui",
+    "terminal",
+    "ui",
+    "text-editor",
+    "differential-rendering",
+    "typescript",
+    "cli"
+  ],
+  "bugs": {
+    "url": "https://github.com/Linxira-OS/linxira-zeta/issues"
+  },
+  "repository": {
+    "directory": "packages/tui",
+    "url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+    "type": "git"
+  },
+  "license": "MIT",
+  "contributors": [
+    "Mario Zechner"
+  ],
+  "author": "Stencil Labs, Inc.",
+  "homepage": "https://linxira-os.github.io/zeta/",
+  "description": "Terminal User Interface library with differential rendering for efficient text-based applications",
+  "version": "1.1.9",
+  "name": "@linxiraos/pi-tui",
+  "type": "module"
 }

package/src/components/composer/band.ts

@@ -24,9 +24,13 @@ export const bandComposerStyle: ComposerStyle = {
 		return 0;
 	},
 
-	renderTop(ctx: ComposerChromeContext): string | undefined {
+	renderTop(ctx: ComposerChromeContext): string {
 		const { topBorder, width } = ctx;
-		if (!topBorder?.content) return undefined;
+		// The band always owns one chrome row (`verticalChrome: 1`): keep it
+		// reserved while the status line has nothing to show yet — the startup
+		// prepaint mounts the editor before the session-aware status line
+		// attaches — so the band fills in later without shifting the layout.
+		if (!topBorder?.content) return "";
 		// The band builder already sizes its groups + gauge to the full width;
 		// truncation only guards against a stale provider during resize.
 		return topBorder.width > width ? truncateToWidth(topBorder.content, width) : topBorder.content;

package/src/components/markdown.ts

@@ -1254,6 +1254,52 @@ function lexDocument(text: string): Token[] {
 	return lexWindowed(text);
 }
 
+/** A hyperlink as the renderer sees it: inline `[text](href)`, `<autolink>`, bare GFM URL, or reference link. */
+export interface MarkdownLink {
+	/** Visible link text (equals `href` for autolinks and bare URLs). */
+	text: string;
+	/** Destination exactly as marked resolved it (references resolved, no normalization). */
+	href: string;
+}
+
+/**
+ * Every link token in `text`, in document order, from the same configured
+ * lexer the renderer uses — so fenced code, code spans, escapes, reference
+ * definitions and the GFM autolink rules agree with what is drawn on screen.
+ * Duplicate hrefs are kept; callers decide how to fold them.
+ */
+export function extractMarkdownLinks(text: string): MarkdownLink[] {
+	const links: MarkdownLink[] = [];
+	const walk = (tokens: readonly Token[] | undefined): void => {
+		if (!tokens) return;
+		for (const token of tokens) {
+			if (token.type === "link") {
+				const link = token as Tokens.Link;
+				if (typeof link.href === "string" && link.href.length > 0) {
+					links.push({
+						text: typeof link.text === "string" && link.text.length > 0 ? link.text : link.href,
+						href: link.href,
+					});
+				}
+				continue;
+			}
+			// Containers: paragraphs, emphasis, lists, blockquotes, table cells.
+			const any = token as {
+				tokens?: Token[];
+				items?: Token[];
+				header?: Array<{ tokens?: Token[] }>;
+				rows?: Array<Array<{ tokens?: Token[] }>>;
+			};
+			walk(any.tokens);
+			walk(any.items);
+			if (any.header) for (const cell of any.header) walk(cell.tokens);
+			if (any.rows) for (const row of any.rows) for (const cell of row) walk(cell.tokens);
+		}
+	};
+	walk(lexDocument(text));
+	return links;
+}
+
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export function clearRenderCache(): void {
 	renderCache.clear();
@@ -1300,6 +1346,15 @@ export interface HighlightStreamSession {
 	push(chunk: string): string;
 }
 
+/** Collect distinct hyperlink destinations using the renderer's Markdown grammar, excluding images and code. */
+export function getMarkdownLinkUrls(text: string): string[] {
+	const urls = new Set<string>();
+	markdownParser.walkTokens(markdownParser.lexer(text), token => {
+		if (token.type === "link" && typeof token.href === "string") urls.add(token.href);
+	});
+	return [...urls];
+}
+
 /**
  * Theme functions for markdown elements.
  * Each function takes text and returns styled text with ANSI codes.
@@ -1308,6 +1363,8 @@ export interface MarkdownTheme {
 	heading: (text: string) => string;
 	link: (text: string) => string;
 	linkUrl: (text: string) => string;
+	/** Resolve the OSC 8 destination without changing visible text; undefined preserves the authored URL. */
+	resolveLink?: (href: string) => string | undefined;
 	code: (text: string) => string;
 	codeBlock: (text: string) => string;
 	codeBlockBorder: (text: string) => string;
@@ -3162,7 +3219,8 @@ export class Markdown implements Component {
 					const linkText = this.#renderInlineTokens(token.tokens || [], resolvedStyleContext);
 					const styledLinkText = this.#theme.link(this.#theme.underline(linkText));
 					const href = typeof token.href === "string" ? token.href : "";
-					const clickableLinkText = formatHyperlink(styledLinkText, href);
+					const target = (href && this.#theme.resolveLink?.(href)) || href;
+					const clickableLinkText = formatHyperlink(styledLinkText, target);
 					// If link text matches href, only show the link once. A missing
 					// href (malformed/partial link token) renders as plain link text
 					// instead of crashing the renderer or emitting an empty "()"
@@ -3175,7 +3233,7 @@ export class Markdown implements Component {
 						result += clickableLinkText + stylePrefix;
 					else {
 						const styledLinkUrl = this.#theme.linkUrl(`(${href})`);
-						result += `${clickableLinkText} ${formatHyperlink(styledLinkUrl, href)}${stylePrefix}`;
+						result += `${clickableLinkText} ${formatHyperlink(styledLinkUrl, target)}${stylePrefix}`;
 					}
 					break;
 				}

package/src/tui.ts

@@ -711,6 +711,13 @@ export class TUI extends Container {
 	#previousFrameLength = 0;
 	#previousWidth = 0;
 	#previousHeight = 0;
+	/**
+	 * Physical terminal width of the last provider frame. `#previousWidth`
+	 * tracks the composed (main-area) width once a sidebar reservation is
+	 * active, while scrollback reflow follows the terminal's own wrap width —
+	 * resize-replay dedup must compare physical to physical.
+	 */
+	#previousPhysicalWidth = 0;
 	#focusedComponent: Component | null = null;
 	#debugServer: TuiDebugServer | undefined;
 	#debugPaint:
@@ -905,6 +912,17 @@ export class TUI extends Container {
 		const next = width !== null && Number.isInteger(width) && width > 0 ? width : null;
 		if (this.#mainWidthOverride === next) return;
 		this.#mainWidthOverride = next;
+		// The composed row width changes, so already-committed scrollback would
+		// sit shredded at the old width. Re-offer finalized history and force a
+		// full viewport repaint on the next frame, mirroring the settled-resize
+		// replay in #prepareResizeReplay.
+		if (this.#hasEverRendered) {
+			const provider = this.#frameProvider;
+			if (provider?.beginHistoryReplay) {
+				provider.beginHistoryReplay();
+				this.#forceViewportRepaintOnNextRender = true;
+			}
+		}
 		this.requestRender();
 	}
 
@@ -2357,14 +2375,14 @@ export class TUI extends Container {
 		const coalesced = coalesceAdjacentSgr(line);
 		return coalesced + (line.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
 	}
-	#renderProviderFrame(width: number, height: number): void {
+	#renderProviderFrame(mainWidth: number, rawWidth: number, height: number): void {
 		const provider = this.#frameProvider;
-		if (!provider || width <= 0 || height <= 0) return;
+		if (!provider || mainWidth <= 0 || height <= 0) return;
 		this.#debugNextWindowTop = 0;
 		let plan: TerminalFramePlan;
 		do {
 			this.#imageBudget.beginPass();
-			plan = provider.renderFrame({ columns: width, rows: height });
+			plan = provider.renderFrame({ columns: mainWidth, rows: height });
 		} while (this.#imageBudget.endPass());
 		let viewport = Array.from(plan.viewport);
 		if (viewport.length > height) {
@@ -2374,7 +2392,36 @@ export class TUI extends Container {
 			viewport = viewport.slice(0, height);
 		}
 		if (this.#maybeDeferGhosttyInitialImagePaint()) return;
-		this.#emitPlanFrame(width, height, viewport, plan.history, provider);
+		this.#emitPlanFrame(mainWidth, height, viewport, plan.history, provider);
+		this.#previousPhysicalWidth = rawWidth;
+		this.#paintGutter(mainWidth, rawWidth, height, viewport.length);
+	}
+
+	/**
+	 * Paint (or clear) the right-hand gutter column after a frame's content
+	 * block, inside the same synchronous paint. Content is composed at
+	 * `mainWidth`, so absolute-positioned gutter writes at column `mainWidth + 1`
+	 * compose with it without touching the frame or scrollback. The gutter
+	 * component composes into the column width it owns (`rawWidth - mainWidth`).
+	 * When no gutter applies this frame — component cleared, or an overlay frame
+	 * composing at full width — a previously painted gutter is erased row by row.
+	 */
+	#paintGutter(mainWidth: number, rawWidth: number, height: number, viewportRows: number): void {
+		const gutter = this.#gutterComponent && mainWidth < rawWidth ? this.#gutterComponent : null;
+		if (gutter) {
+			const rows = gutter.render(rawWidth - mainWidth);
+			const seq = this.#gutterPaintSequence(rows, rawWidth - mainWidth, mainWidth, viewportRows, 0);
+			if (seq) this.terminal.write(seq);
+			this.#paintedGutterRows = rows;
+		} else if (this.#paintedGutterRows !== null) {
+			// Gutter removed: clear the margin column once via absolute EL per row.
+			const col = mainWidth + 1;
+			let seq = "";
+			for (let row = 0; row < height; row++) seq += `\x1b[${row + 1};${col}H\x1b[K`;
+			seq += "\x1b[H";
+			this.terminal.write(seq);
+			this.#paintedGutterRows = null;
+		}
 	}
 	/**
 	 * Re-offer finalized history once after a settled resize.
@@ -2395,7 +2442,7 @@ export class TUI extends Container {
 		const size = `${width}x${height}`;
 		if (
 			!this.#hasEverRendered ||
-			(this.#previousWidth === width && this.#previousHeight === height) ||
+			(this.#previousPhysicalWidth === width && this.#previousHeight === height) ||
 			this.#resizeReplaySize === size ||
 			this.#resizeScrollbackMode === "preserve"
 		) {
@@ -2412,7 +2459,7 @@ export class TUI extends Container {
 			this.#prepareForcedRender(true);
 			return;
 		}
-		if (width === this.#previousWidth) return;
+		if (width === this.#previousPhysicalWidth) return;
 		provider.beginHistoryReplay();
 		this.#forceViewportRepaintOnNextRender = true;
 	}
@@ -2724,8 +2771,11 @@ export class TUI extends Container {
 			return;
 		}
 		if (this.#frameProvider !== undefined) {
+			const mainWidth = this.#effectiveMainWidth(width);
+			// Physical size keys: scrollback reflow follows the terminal's wrap
+			// width, not the composed main-area width.
 			this.#prepareResizeReplay(width, height);
-			this.#renderProviderFrame(width, height);
+			this.#renderProviderFrame(mainWidth, width, height);
 			return;
 		}
 		this.#renderChildrenFrame(width, this.#effectiveMainWidth(width), height);
@@ -2737,7 +2787,6 @@ export class TUI extends Container {
 	 * mutable viewport. Nothing is ever appended to terminal history.
 	 */
 	#renderChildrenFrame(rawWidth: number, width: number, height: number): void {
-		const gutter = this.#gutterComponent && width < rawWidth ? this.#gutterComponent : null;
 		let composed: readonly string[];
 		do {
 			this.#imageBudget.beginPass();
@@ -2747,22 +2796,7 @@ export class TUI extends Container {
 		this.#debugNextWindowTop = Math.max(0, composed.length - height);
 		const viewport = composed.length > height ? composed.slice(composed.length - height) : Array.from(composed);
 		this.#emitPlanFrame(width, height, viewport, undefined, undefined);
-		if (gutter) {
-			const rows = gutter.render(width);
-			// Paint the freed right margin after the frame block: absolute-positioned
-			// writes at column width+1 never touch the composed frame or scrollback.
-			const seq = this.#gutterPaintSequence(rows, rawWidth - width, width, viewport.length, 0);
-			if (seq) this.terminal.write(seq);
-			this.#paintedGutterRows = rows;
-		} else if (this.#paintedGutterRows !== null) {
-			// Gutter removed: clear the margin column once via absolute EL per row.
-			const col = width + 1;
-			let seq = "";
-			for (let row = 0; row < height; row++) seq += `\x1b[${row + 1};${col}H\x1b[K`;
-			seq += "\x1b[H";
-			this.terminal.write(seq);
-			this.#paintedGutterRows = null;
-		}
+		this.#paintGutter(width, rawWidth, height, viewport.length);
 	}
 
 	/** Stateless variant for overlay-composited windows and alt-screen frames. */