@aliou/pi-processes 0.10.9 → 0.11.0

package/extensions/processes-logs/components/log-file-viewer.ts

@@ -9,10 +9,16 @@ import {
   displayTextOf,
   type LogLineEmphasis,
   renderLogLine,
+  renderLogLineWrap,
 } from "../../shared/log-line";
 import { truncateToWidth } from "../../shared/truncate";
 import type { ProcessLogLine } from "../logs-client";
 
+interface DisplayRow {
+  text: string;
+  logicalIndex: number;
+}
+
 export type StreamFilter = "both" | "stdout" | "stderr";
 
 interface LogFileViewerOptions {
@@ -30,6 +36,8 @@ export class LogFileViewer {
   private searchMatches: number[] = [];
   private searchCurrentMatch = -1;
   private centerTarget: number | null = null;
+  private wrapEnabled = false;
+  private lastRenderWidth = 0;
   private readonly notifyLines = new Set<string>();
 
   constructor(
@@ -59,12 +67,11 @@ export class LogFileViewer {
   }
 
   scrollBy(delta: number): void {
-    const visible = this.visibleLines();
     this.follow = false;
-    this.anchorEnd ??= visible.length;
+    this.anchorEnd ??= this.totalDisplayRows(0);
     this.anchorEnd = Math.max(
       0,
-      Math.min(visible.length, this.anchorEnd - delta),
+      Math.min(this.totalDisplayRows(0), this.anchorEnd - delta),
     );
   }
 
@@ -75,12 +82,12 @@ export class LogFileViewer {
 
   scrollToBottom(): void {
     this.follow = false;
-    this.anchorEnd = this.visibleLines().length;
+    this.anchorEnd = this.totalDisplayRows(0);
   }
 
   toggleFollow(): boolean {
     this.follow = !this.follow;
-    this.anchorEnd = this.follow ? null : this.visibleLines().length;
+    this.anchorEnd = this.follow ? null : this.totalDisplayRows(0);
     return this.follow;
   }
 
@@ -88,6 +95,18 @@ export class LogFileViewer {
     return this.follow;
   }
 
+  toggleWrap(): boolean {
+    this.wrapEnabled = !this.wrapEnabled;
+    // Reset anchor so the viewport snaps to the latest content in the new
+    // display-row space (row counts change when wrap toggles).
+    this.anchorEnd = this.follow ? null : this.totalDisplayRows(0);
+    return this.wrapEnabled;
+  }
+
+  isWrapEnabled(): boolean {
+    return this.wrapEnabled;
+  }
+
   cycleStreamFilter(): StreamFilter {
     this.streamFilter =
       this.streamFilter === "both"
@@ -95,7 +114,7 @@ export class LogFileViewer {
         : this.streamFilter === "stdout"
           ? "stderr"
           : "both";
-    this.anchorEnd = this.visibleLines().length;
+    this.anchorEnd = this.totalDisplayRows(0);
     this.refreshMatches();
     return this.streamFilter;
   }
@@ -106,7 +125,7 @@ export class LogFileViewer {
 
   setSearch(query: string): void {
     this.follow = false;
-    this.anchorEnd ??= this.visibleLines().length;
+    this.anchorEnd ??= this.totalDisplayRows(0);
     this.searchQuery = query;
     this.refreshMatches();
     if (this.searchMatches.length > 0) {
@@ -168,11 +187,24 @@ export class LogFileViewer {
   }
 
   render(width: number, height: number): string[] {
+    this.lastRenderWidth = width;
     const visible = this.visibleLines();
     if (visible.length === 0) {
       return this.renderEmpty(width, height);
     }
 
+    if (!this.wrapEnabled) {
+      return this.renderTruncated(visible, width, height);
+    }
+
+    return this.renderWrapped(visible, width, height);
+  }
+
+  private renderTruncated(
+    visible: ProcessLogLine[],
+    width: number,
+    height: number,
+  ): string[] {
     if (this.centerTarget !== null) {
       const half = Math.floor(height / 2);
       this.anchorEnd = Math.min(visible.length, this.centerTarget + half + 1);
@@ -186,6 +218,11 @@ export class LogFileViewer {
       visible.length,
       Math.max(Math.min(height, visible.length), rawEnd),
     );
+    // Write the clamped end back so the anchor always matches the screen.
+    // Otherwise scrolling mutates a stale anchor while the clamp above
+    // swallows the change, leaving a dead zone of up to a screenful of
+    // scroll keypresses.
+    if (!this.follow && this.anchorEnd !== null) this.anchorEnd = end;
     const start = Math.max(0, end - height);
     const matchSet = new Set(this.searchMatches);
     const currentMatchIndex =
@@ -211,12 +248,81 @@ export class LogFileViewer {
     return rendered.slice(-height);
   }
 
+  private renderWrapped(
+    visible: ProcessLogLine[],
+    width: number,
+    height: number,
+  ): string[] {
+    // Build a flat list of display rows from all visible logical lines.
+    // Each entry carries its source logical-line index so emphasis can be
+    // applied per logical line (not per wrapped chunk).
+    const matchSet = new Set(this.searchMatches);
+    const currentMatchIndex =
+      this.searchCurrentMatch >= 0
+        ? this.searchMatches[this.searchCurrentMatch]
+        : undefined;
+
+    const rows: DisplayRow[] = [];
+    // Track the starting display-row offset of each logical line so we can
+    // resolve centerTarget (a logical-line index) to a display row.
+    const logicalToDisplayRow: number[] = [];
+
+    for (let index = 0; index < visible.length; index++) {
+      logicalToDisplayRow[index] = rows.length;
+      const line = visible[index];
+      const emphasis: LogLineEmphasis =
+        index === currentMatchIndex
+          ? "search-current"
+          : matchSet.has(index)
+            ? "search"
+            : this.notifyLines.has(line.text) ||
+                this.notifyLines.has(displayTextOf(line))
+              ? "notify"
+              : "none";
+      const wrapped = renderLogLineWrap(line, {
+        theme: this.theme,
+        width,
+        emphasis,
+      });
+      for (const text of wrapped) {
+        rows.push({ text, logicalIndex: index });
+      }
+    }
+
+    const totalDisplayRows = rows.length;
+
+    // Resolve centerTarget from logical-line index to display-row index.
+    if (this.centerTarget !== null) {
+      const half = Math.floor(height / 2);
+      const displayRow = logicalToDisplayRow[this.centerTarget] ?? 0;
+      this.anchorEnd = Math.min(totalDisplayRows, displayRow + half + 1);
+      this.centerTarget = null;
+    }
+
+    const rawEnd = this.follow
+      ? totalDisplayRows
+      : (this.anchorEnd ?? totalDisplayRows);
+    const end = Math.min(
+      totalDisplayRows,
+      Math.max(Math.min(height, totalDisplayRows), rawEnd),
+    );
+    // Same anchor normalization as the truncated path: keep the stored
+    // anchor truthful so scrollBy starts from the rendered bottom edge.
+    if (!this.follow && this.anchorEnd !== null) this.anchorEnd = end;
+    const start = Math.max(0, end - height);
+
+    const rendered = rows.slice(start, end).map((row) => row.text);
+
+    while (rendered.length < height) rendered.unshift("");
+    return rendered.slice(-height);
+  }
+
   getStatusParts(): { left: string[]; right: string[] } {
     const dim = (value: string) => this.theme.fg("dim", value);
     const accent = (value: string) => this.theme.fg("accent", value);
     const error = (value: string) => this.theme.fg("error", value);
     const visible = this.visibleLines();
-    const total = visible.length;
+    const total = this.wrapEnabled ? this.totalDisplayRows(0) : visible.length;
 
     const left: string[] = [];
     const search = this.getSearchInfo();
@@ -239,6 +345,7 @@ export class LogFileViewer {
       right.push(dim(`${pct}% L${end}/${total}`));
     }
     if (this.streamFilter !== "both") right.push(dim(`[${this.streamFilter}]`));
+    if (this.wrapEnabled) right.push(dim("wrap"));
 
     return { left, right };
   }
@@ -257,6 +364,26 @@ export class LogFileViewer {
     return this.lines.filter((line) => line.type === this.streamFilter);
   }
 
+  /**
+   * Total display rows for the visible lines at the last render width.
+   * When wrapping is off (or no width is known), equals the logical-line
+   * count. The `fallbackWidth` is used before the first render.
+   */
+  private totalDisplayRows(fallbackWidth: number): number {
+    if (!this.wrapEnabled) return this.visibleLines().length;
+    const width = this.lastRenderWidth || fallbackWidth;
+    if (width <= 0) return this.visibleLines().length;
+    let total = 0;
+    for (const line of this.visibleLines()) {
+      const wrapped = renderLogLineWrap(line, {
+        theme: this.theme,
+        width,
+      });
+      total += Math.max(1, wrapped.length);
+    }
+    return total;
+  }
+
   private refreshMatches(): void {
     if (!this.searchQuery) {
       this.searchMatches = [];

package/extensions/processes-logs/components/log-overlay-component.ts

@@ -4,21 +4,29 @@ import {
   type Component,
   Input,
   Key,
-  matchesKey,
+  parseKey,
   type TUI,
   visibleWidth,
 } from "@earendil-works/pi-tui";
+import { LIVE_STATUSES, type ProcessInfo } from "../../../src/types";
+import { formatRuntime } from "../../../src/utils/format";
+import { truncateForDisplay } from "../../shared/display-text";
+import { renderProcessTab } from "../../shared/process-tabs";
 import {
   CHANNELS,
   type ProcessesChangedPayload,
   type ProcessProtocolConfig,
   type ProcessProtocolNotificationPayload,
-} from "../../../src/protocol";
-import { LIVE_STATUSES, type ProcessInfo } from "../../../src/types";
-import { formatRuntime } from "../../../src/utils/format";
-import { isRecord } from "../../../src/utils/is-record";
-import { truncateForDisplay } from "../../shared/display-text";
-import { renderProcessTab } from "../../shared/process-tabs";
+} from "../../shared/protocol";
+import {
+  renderShortcutHints,
+  SHORTCUTS_KEY,
+  type ShortcutHint,
+} from "../../shared/shortcut-hints";
+import {
+  type ShortcutGroup,
+  showShortcutsOverlay,
+} from "../../shared/shortcuts-overlay";
 import { truncateToWidth } from "../../shared/truncate";
 import { LineComponent, LinesComponent, RuleComponent } from "../../shared/ui";
 import { requestProcessList } from "../client";
@@ -82,6 +90,8 @@ export class LogOverlayComponent implements Component {
    * survive a round-trip. Mirrors the notifyMarkers persistence pattern.
    */
   private readonly viewers = new Map<string, LogFileViewer>();
+  /** Disposer for the "?" shortcuts overlay, when open. */
+  private shortcutsHelp: (() => void) | null = null;
 
   constructor(private readonly opts: LogOverlayOptions) {
     this.configureSearchInput();
@@ -89,7 +99,7 @@ export class LogOverlayComponent implements Component {
     this.refreshProcesses(opts.initialProcessId);
     this.disposers.push(
       opts.events.on(CHANNELS.CHANGED, (payload) => {
-        if (isChangedPayload(payload)) this.handleProcessesChanged(payload);
+        this.handleProcessesChanged(payload as ProcessesChangedPayload);
       }),
     );
     this.disposers.push(
@@ -99,8 +109,9 @@ export class LogOverlayComponent implements Component {
     );
   }
 
-  private handleNotification(payload: unknown): void {
-    if (!isLogMatchNotification(payload)) return;
+  private handleNotification(rawPayload: unknown): void {
+    const payload = rawPayload as ProcessProtocolNotificationPayload;
+    if (payload.kind !== "log_match" || !payload.logMatch) return;
     const mark: NotifyMatchMark = {
       pattern: payload.logMatch.pattern,
       line: payload.logMatch.line,
@@ -144,6 +155,31 @@ export class LogOverlayComponent implements Component {
     return panel.render(width);
   }
 
+  /**
+   * Key dispatch for normal mode, keyed by parsed key id. Close keys and
+   * the mode-specific search keys are handled in `handleInput` before the
+   * table is consulted.
+   */
+  private readonly keyActions: Record<string, () => void> = {
+    [Key.tab]: () => this.selectRelative(1),
+    [Key.shift("tab")]: () => this.selectRelative(-1),
+    [Key.down]: () => this.viewer?.scrollBy(-1),
+    [Key.up]: () => this.viewer?.scrollBy(1),
+    [Key.pageDown]: () => this.viewer?.scrollBy(-this.logRows()),
+    [Key.pageUp]: () => this.viewer?.scrollBy(this.logRows()),
+    [Key.ctrl("d")]: () => this.viewer?.scrollBy(-this.halfPageRows()),
+    [Key.ctrl("u")]: () => this.viewer?.scrollBy(this.halfPageRows()),
+    j: () => this.viewer?.scrollBy(-1),
+    k: () => this.viewer?.scrollBy(1),
+    g: () => this.viewer?.scrollToTop(),
+    G: () => this.viewer?.scrollToBottom(),
+    s: () => this.viewer?.cycleStreamFilter(),
+    f: () => this.viewer?.toggleFollow(),
+    w: () => this.viewer?.toggleWrap(),
+    "/": () => this.startSearch(),
+    [SHORTCUTS_KEY]: () => this.openShortcutsHelp(),
+  };
+
   handleInput(data: string): void {
     if (this.mode === "search-typing") {
       this.searchInput.handleInput?.(data);
@@ -151,25 +187,27 @@ export class LogOverlayComponent implements Component {
       return;
     }
 
+    const key = parseKey(data);
+
     if (this.mode === "search-active") {
-      if (matchesKey(data, Key.escape)) {
+      if (key === "escape") {
         this.viewer?.clearSearch();
         this.searchInput.setValue("");
         this.mode = "normal";
         this.opts.tui.requestRender();
         return;
       }
-      if (data === "n") {
+      if (key === "n") {
         this.viewer?.nextMatch();
         this.opts.tui.requestRender();
         return;
       }
-      if (data === "N") {
+      if (key === "N") {
         this.viewer?.previousMatch();
         this.opts.tui.requestRender();
         return;
       }
-      if (data === "/") {
+      if (key === "/") {
         this.searchInput.setValue(this.viewer?.getSearchInfo()?.query ?? "");
         this.mode = "search-typing";
         this.opts.tui.requestRender();
@@ -177,26 +215,12 @@ export class LogOverlayComponent implements Component {
       }
     }
 
-    if (
-      matchesKey(data, Key.escape) ||
-      matchesKey(data, Key.ctrl("c")) ||
-      data === "q" ||
-      data === "Q"
-    ) {
+    if (key === "escape" || key === "ctrl+c" || key === "q" || key === "Q") {
       this.close();
       return;
     }
 
-    if (matchesKey(data, Key.tab)) this.selectRelative(1);
-    else if (matchesKey(data, Key.shift("tab"))) this.selectRelative(-1);
-    else if (matchesKey(data, Key.down) || data === "j")
-      this.viewer?.scrollBy(-1);
-    else if (matchesKey(data, Key.up) || data === "k") this.viewer?.scrollBy(1);
-    else if (data === "g") this.viewer?.scrollToTop();
-    else if (data === "G") this.viewer?.scrollToBottom();
-    else if (data === "s") this.viewer?.cycleStreamFilter();
-    else if (data === "f") this.viewer?.toggleFollow();
-    else if (data === "/") this.startSearch();
+    this.keyActions[key ?? ""]?.();
 
     this.opts.tui.requestRender();
   }
@@ -223,6 +247,8 @@ export class LogOverlayComponent implements Component {
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;
+    this.shortcutsHelp?.();
+    this.shortcutsHelp = null;
     if (this.renderTimer) {
       clearTimeout(this.renderTimer);
       this.renderTimer = null;
@@ -318,6 +344,24 @@ export class LogOverlayComponent implements Component {
     this.opts.onClose();
   }
 
+  /** Rows scrolled by ctrl+u / ctrl+d (half a viewport). */
+  private halfPageRows(): number {
+    return Math.max(1, Math.floor(this.logRows() / 2));
+  }
+
+  /**
+   * Open the "?" shortcuts overlay on top of this overlay. While open it
+   * captures input; closing it restores focus here. Disposed with the
+   * overlay so a background close (auto-hide, kill) cannot leave it behind.
+   */
+  private openShortcutsHelp(): void {
+    if (this.shortcutsHelp) return;
+    this.shortcutsHelp = showShortcutsOverlay(this.opts.tui, {
+      theme: this.opts.theme,
+      groups: this.shortcutGroups(),
+    });
+  }
+
   private refreshProcesses(preferredProcessId?: string): void {
     this.processes = this.sortProcesses(requestProcessList(this.opts.events));
     if (this.processes.some((process) => process.status === "running")) {
@@ -604,37 +648,98 @@ export class LogOverlayComponent implements Component {
 
     const leftPrefix = this.message ?? statusLeft.join("  ");
     const prefix = leftPrefix ? `${leftPrefix}  ` : "";
-    const keys = this.renderFooterKeys(
+    const keys = renderShortcutHints(
+      this.footerHints(),
+      this.opts.theme,
       Math.max(1, width - visibleWidth(prefix)),
     );
     return truncateToWidth(`${prefix}${keys}`, width);
   }
 
-  private renderFooterKeys(width: number): string {
-    const dim = (value: string) => this.opts.theme.fg("dim", value);
-    const accent = (value: string) => this.opts.theme.fg("accent", value);
-
+  /** Footer hint list; search mode adds its extra keys up front. */
+  private footerHints(): ShortcutHint[] {
+    const hints: ShortcutHint[] = [];
     if (this.mode === "search-active") {
-      return truncateToWidth(
-        `${dim("n")} next  ${dim("N")} prev  ${dim("/")} edit  ${dim("esc")} clear  ${dim("j/k")} scroll  ${dim("q")} close`,
-        width,
+      hints.push(
+        { key: "n", label: "next" },
+        { key: "N", label: "prev" },
+        { key: "/", label: "edit" },
+        { key: "esc", label: "clear" },
       );
     }
-
     const streamFilter = this.viewer?.getStreamFilter() ?? "both";
-    const stdout =
-      streamFilter === "both" || streamFilter === "stdout"
-        ? accent("stdout")
-        : dim("stdout");
-    const stderr =
-      streamFilter === "both" || streamFilter === "stderr"
-        ? accent("stderr")
-        : dim("stderr");
-
-    return truncateToWidth(
-      `${dim("tab/shift+tab")} switch  ${dim("g/G")} top/bot  ${dim("j/k")} scroll  ${dim("/")} search  ${dim("s:")}${stdout}${dim("+")}${stderr}  ${dim("f")} follow  ${dim("q")} close`,
-      width,
+    const stream = (on: boolean) => (on ? "accent" : "dim");
+    const wrapOn = this.viewer?.isWrapEnabled() ?? false;
+    hints.push(
+      {
+        key: "w",
+        label: [{ text: "wrap", style: wrapOn ? "accent" : "dim" }],
+      },
+      { key: "f", label: "follow" },
+      { key: "/", label: "search" },
+      {
+        key: "s",
+        label: [
+          { text: "stdout", style: stream(streamFilter !== "stderr") },
+          { text: "+", style: "dim" },
+          { text: "stderr", style: stream(streamFilter !== "stdout") },
+        ],
+      },
+      { key: "j/k", label: "scroll" },
+      { key: "pgup/pgdn", label: "page" },
+      { key: "^u/^d", label: "half-page" },
+      { key: "q", label: "close" },
+      { key: "g/G", label: "top/bot" },
+      { key: "tab/shift+tab", label: "switch" },
+    );
+    return hints;
+  }
+
+  /**
+   * Groups for the "?" shortcuts overlay. The search group is only present
+   * while a search is active; every other key works in both modes.
+   */
+  private shortcutGroups(): ShortcutGroup[] {
+    const groups: ShortcutGroup[] = [];
+    if (this.mode === "search-active") {
+      groups.push({
+        title: "search",
+        rows: [
+          { keys: "n / N", description: "next / previous match" },
+          { keys: "/", description: "edit query" },
+          { keys: "esc", description: "clear search" },
+        ],
+      });
+    }
+    groups.push(
+      {
+        title: "scrolling",
+        rows: [
+          { keys: "j / k", description: "line up / down" },
+          { keys: "pgup / pgdn", description: "page up / down" },
+          { keys: "ctrl+u / ctrl+d", description: "half page up / down" },
+          { keys: "g / G", description: "top / bottom" },
+        ],
+      },
+      {
+        title: "view",
+        rows: [
+          { keys: "w", description: "wrap long lines" },
+          { keys: "f", description: "follow newest output" },
+          { keys: "s", description: "stream: stdout + stderr" },
+          { keys: "/", description: "search" },
+        ],
+      },
+      {
+        title: "tabs",
+        rows: [{ keys: "tab / shift+tab", description: "switch process" }],
+      },
+      {
+        title: "general",
+        rows: [{ keys: "q", description: "close" }],
+      },
     );
+    return groups;
   }
 }
 
@@ -655,34 +760,3 @@ function centeredBlock(
   lines[row] = truncateToWidth(`${" ".repeat(leftPad)}${content}`, width);
   return lines;
 }
-
-function isChangedPayload(
-  payload: unknown,
-): payload is ProcessesChangedPayload {
-  return (
-    isRecord(payload) &&
-    (payload.reason === "started" ||
-      payload.reason === "ended" ||
-      payload.reason === "cleared")
-  );
-}
-
-function isLogMatchNotification(
-  payload: unknown,
-): payload is ProcessProtocolNotificationPayload & {
-  kind: "log_match";
-  logMatch: NonNullable<ProcessProtocolNotificationPayload["logMatch"]>;
-} {
-  if (!isRecord(payload)) return false;
-  if (payload.kind !== "log_match") return false;
-  if (typeof payload.processId !== "string") return false;
-  if (typeof payload.timestamp !== "number") return false;
-  const logMatch = payload.logMatch;
-  if (!isRecord(logMatch)) return false;
-  if (typeof logMatch.pattern !== "string") return false;
-  if (typeof logMatch.line !== "string") return false;
-  if (logMatch.stream !== "stdout" && logMatch.stream !== "stderr")
-    return false;
-  if (typeof logMatch.matcherIndex !== "number") return false;
-  return true;
-}

package/extensions/processes-logs/logs-client.ts

@@ -4,9 +4,7 @@ import {
   type LogsChunkPayload,
   type LogsSubscribePayload,
   type LogsUnsubscribePayload,
-} from "../../src/protocol";
-import { isRecord } from "../../src/utils/is-record";
-
+} from "../shared/protocol";
 export type ProcessLogLine = { type: "stdout" | "stderr"; text: string };
 
 export interface LogsConnection {
@@ -29,8 +27,7 @@ export function connectToProcessLogs(
 
   const disposeChunkListener = events.on(CHANNELS.LOGS_CHUNK, (raw) => {
     if (disposed) return;
-    if (!isLogsChunkPayload(raw)) return;
-    const chunk = raw;
+    const chunk = raw as LogsChunkPayload;
     if (chunk.subscriberId !== subscriberId || chunk.processId !== processId)
       return;
 
@@ -81,21 +78,3 @@ export function connectToProcessLogs(
     },
   };
 }
-
-function isLogsChunkPayload(payload: unknown): payload is LogsChunkPayload {
-  return (
-    isRecord(payload) &&
-    typeof payload.subscriberId === "string" &&
-    typeof payload.processId === "string" &&
-    Array.isArray(payload.lines) &&
-    payload.lines.every(isProcessLogLine)
-  );
-}
-
-function isProcessLogLine(line: unknown): line is ProcessLogLine {
-  return (
-    isRecord(line) &&
-    (line.type === "stdout" || line.type === "stderr") &&
-    typeof line.text === "string"
-  );
-}