@jmoyers/harness 0.1.0

package/src/services/runtime-render-flush.ts

@@ -0,0 +1,146 @@
+interface RuntimeRenderFlushResult {
+  readonly changedRowCount: number;
+  readonly wroteOutput: boolean;
+  readonly shouldShowCursor: boolean;
+}
+
+interface RuntimeRenderFlushInput<TConversation, TFrame, TSelection, TLayout> {
+  readonly layout: TLayout;
+  readonly projectPaneActive: boolean;
+  readonly homePaneActive: boolean;
+  readonly activeConversation: TConversation | null;
+  readonly rightFrame: TFrame | null;
+  readonly renderSelection: TSelection | null;
+  readonly selectionRows: readonly number[];
+  readonly railAnsiRows: readonly string[];
+  readonly rightRows: readonly string[];
+}
+
+interface RuntimeRenderFlushOptions<
+  TConversation,
+  TFrame,
+  TSelection,
+  TLayout,
+  TModalOverlay,
+  TStatusRow,
+> {
+  readonly perfNowNs: () => bigint;
+  readonly statusFooterForConversation: (conversation: TConversation) => string;
+  readonly currentStatusNotice: () => string | null;
+  readonly currentStatusRow: () => TStatusRow;
+  readonly onStatusLineComposed?: (input: {
+    activeConversation: TConversation | null;
+    statusFooter: string;
+    statusRow: TStatusRow;
+    projectPaneActive: boolean;
+    homePaneActive: boolean;
+  }) => void;
+  readonly buildRenderRows: (
+    layout: TLayout,
+    railRows: readonly string[],
+    rightRows: readonly string[],
+    statusRow: TStatusRow,
+    statusFooter: string,
+  ) => string[];
+  readonly buildModalOverlay: () => TModalOverlay | null;
+  readonly applyModalOverlay: (rows: string[], overlay: TModalOverlay) => void;
+  readonly renderSelectionOverlay: (
+    layout: TLayout,
+    rightFrame: TFrame,
+    selection: TSelection | null,
+  ) => string;
+  readonly flush: (input: {
+    layout: TLayout;
+    rows: readonly string[];
+    rightFrame: TFrame | null;
+    selectionRows: readonly number[];
+    selectionOverlay: string;
+  }) => RuntimeRenderFlushResult;
+  readonly onFlushOutput: (input: {
+    activeConversation: TConversation | null;
+    rightFrame: TFrame | null;
+    rows: readonly string[];
+    flushResult: RuntimeRenderFlushResult;
+    changedRowCount: number;
+  }) => void;
+  readonly recordRenderSample: (durationMs: number, changedRowCount: number) => void;
+}
+
+export class RuntimeRenderFlush<
+  TConversation,
+  TFrame,
+  TSelection,
+  TLayout,
+  TModalOverlay,
+  TStatusRow,
+> {
+  constructor(
+    private readonly options: RuntimeRenderFlushOptions<
+      TConversation,
+      TFrame,
+      TSelection,
+      TLayout,
+      TModalOverlay,
+      TStatusRow
+    >,
+  ) {}
+
+  flushRender(input: RuntimeRenderFlushInput<TConversation, TFrame, TSelection, TLayout>): void {
+    const renderStartedAtNs = this.options.perfNowNs();
+    const baseStatusFooter =
+      !input.projectPaneActive && !input.homePaneActive && input.activeConversation !== null
+        ? this.options.statusFooterForConversation(input.activeConversation)
+        : '';
+    const statusNotice = this.options.currentStatusNotice();
+    const statusFooter =
+      statusNotice === null || statusNotice.length === 0
+        ? baseStatusFooter
+        : `${baseStatusFooter.length > 0 ? `${baseStatusFooter}  ` : ''}${statusNotice}`;
+    const statusRow = this.options.currentStatusRow();
+    this.options.onStatusLineComposed?.({
+      activeConversation: input.activeConversation,
+      statusFooter,
+      statusRow,
+      projectPaneActive: input.projectPaneActive,
+      homePaneActive: input.homePaneActive,
+    });
+    const rows = this.options.buildRenderRows(
+      input.layout,
+      input.railAnsiRows,
+      input.rightRows,
+      statusRow,
+      statusFooter,
+    );
+    const modalOverlay = this.options.buildModalOverlay();
+    if (modalOverlay !== null) {
+      this.options.applyModalOverlay(rows, modalOverlay);
+    }
+    const selectionOverlay =
+      input.rightFrame === null
+        ? ''
+        : this.options.renderSelectionOverlay(
+            input.layout,
+            input.rightFrame,
+            input.renderSelection,
+          );
+    const flushResult = this.options.flush({
+      layout: input.layout,
+      rows,
+      rightFrame: input.rightFrame,
+      selectionRows: input.selectionRows,
+      selectionOverlay,
+    });
+    const changedRowCount = flushResult.changedRowCount;
+    if (flushResult.wroteOutput) {
+      this.options.onFlushOutput({
+        activeConversation: input.activeConversation,
+        rightFrame: input.rightFrame,
+        rows,
+        flushResult,
+        changedRowCount,
+      });
+    }
+    const renderDurationMs = Number(this.options.perfNowNs() - renderStartedAtNs) / 1e6;
+    this.options.recordRenderSample(renderDurationMs, changedRowCount);
+  }
+}

package/src/services/runtime-render-lifecycle.ts

@@ -0,0 +1,104 @@
+interface ScreenLike {
+  clearDirty(): void;
+  isDirty(): boolean;
+  markDirty(): void;
+}
+
+interface RuntimeRenderLifecycleOptions {
+  readonly screen: ScreenLike;
+  readonly render: () => void;
+  readonly isShuttingDown: () => boolean;
+  readonly setShuttingDown: (next: boolean) => void;
+  readonly setStop: (next: boolean) => void;
+  readonly restoreTerminalState: () => void;
+  readonly formatErrorMessage: (error: unknown) => string;
+  readonly writeStderr: (text: string) => void;
+  readonly exitProcess: (code: number) => void;
+  readonly setImmediateFn?: (callback: () => void) => void;
+  readonly setTimeoutFn?: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+  readonly clearTimeoutFn?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+
+const FATAL_EXIT_DELAY_MS = 1200;
+
+export class RuntimeRenderLifecycle {
+  private readonly setImmediateFn: (callback: () => void) => void;
+  private readonly setTimeoutFn: (
+    callback: () => void,
+    delayMs: number,
+  ) => ReturnType<typeof setTimeout>;
+  private readonly clearTimeoutFn: (timer: ReturnType<typeof setTimeout>) => void;
+  private renderScheduled = false;
+  private runtimeFatal: { origin: string; error: unknown } | null = null;
+  private runtimeFatalExitTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly options: RuntimeRenderLifecycleOptions) {
+    this.setImmediateFn = options.setImmediateFn ?? setImmediate;
+    this.setTimeoutFn = options.setTimeoutFn ?? setTimeout;
+    this.clearTimeoutFn = options.clearTimeoutFn ?? clearTimeout;
+  }
+
+  hasFatal(): boolean {
+    return this.runtimeFatal !== null;
+  }
+
+  clearRenderScheduled(): void {
+    this.renderScheduled = false;
+  }
+
+  clearRuntimeFatalExitTimer(): void {
+    if (this.runtimeFatalExitTimer === null) {
+      return;
+    }
+    this.clearTimeoutFn(this.runtimeFatalExitTimer);
+    this.runtimeFatalExitTimer = null;
+  }
+
+  markDirty(): void {
+    if (this.options.isShuttingDown()) {
+      return;
+    }
+    this.options.screen.markDirty();
+    this.scheduleRender();
+  }
+
+  scheduleRender(): void {
+    if (this.options.isShuttingDown() || this.renderScheduled) {
+      return;
+    }
+    this.renderScheduled = true;
+    this.setImmediateFn(() => {
+      this.renderScheduled = false;
+      try {
+        this.options.render();
+        if (this.options.screen.isDirty()) {
+          this.scheduleRender();
+        }
+      } catch (error: unknown) {
+        this.handleRuntimeFatal('render', error);
+      }
+    });
+  }
+
+  handleRuntimeFatal(origin: string, error: unknown): void {
+    if (this.runtimeFatal !== null) {
+      return;
+    }
+    this.runtimeFatal = {
+      origin,
+      error,
+    };
+    this.options.setShuttingDown(true);
+    this.options.setStop(true);
+    this.options.screen.clearDirty();
+    this.options.writeStderr(
+      `[mux] fatal runtime error (${origin}): ${this.options.formatErrorMessage(error)}\n`,
+    );
+    this.options.restoreTerminalState();
+    this.runtimeFatalExitTimer = this.setTimeoutFn(() => {
+      this.options.writeStderr('[mux] fatal runtime error forced exit\n');
+      this.options.exitProcess(1);
+    }, FATAL_EXIT_DELAY_MS);
+    this.runtimeFatalExitTimer.unref?.();
+  }
+}

package/src/services/runtime-render-orchestrator.ts

@@ -0,0 +1,108 @@
+interface RuntimeRenderStateResult<TConversation, TFrame, TSelection> {
+  readonly projectPaneActive: boolean;
+  readonly homePaneActive: boolean;
+  readonly activeConversation: TConversation | null;
+  readonly rightFrame: TFrame | null;
+  readonly renderSelection: TSelection | null;
+  readonly selectionRows: readonly number[];
+}
+
+interface RuntimeLeftRailRenderResult<TRailViewRows> {
+  readonly ansiRows: readonly string[];
+  readonly viewRows: TRailViewRows;
+}
+
+interface RuntimeRenderOrchestratorOptions<
+  TLayout,
+  TConversation,
+  TFrame,
+  TSelection,
+  TSelectionDrag,
+  TRailViewRows,
+> {
+  readonly isScreenDirty: () => boolean;
+  readonly clearDirty: () => void;
+  readonly prepareRenderState: (
+    selection: TSelection | null,
+    selectionDrag: TSelectionDrag | null,
+  ) => RuntimeRenderStateResult<TConversation, TFrame, TSelection> | null;
+  readonly renderLeftRail: (layout: TLayout) => RuntimeLeftRailRenderResult<TRailViewRows>;
+  readonly setLatestRailViewRows: (rows: TRailViewRows) => void;
+  readonly renderRightRows: (input: {
+    layout: TLayout;
+    rightFrame: TFrame | null;
+    homePaneActive: boolean;
+    projectPaneActive: boolean;
+    activeDirectoryId: string | null;
+  }) => readonly string[];
+  readonly flushRender: (input: {
+    layout: TLayout;
+    projectPaneActive: boolean;
+    homePaneActive: boolean;
+    activeConversation: TConversation | null;
+    rightFrame: TFrame | null;
+    renderSelection: TSelection | null;
+    selectionRows: readonly number[];
+    railAnsiRows: readonly string[];
+    rightRows: readonly string[];
+  }) => void;
+  readonly activeDirectoryId: () => string | null;
+}
+
+interface RuntimeRenderOrchestratorInput<TLayout, TSelection, TSelectionDrag> {
+  readonly shuttingDown: boolean;
+  readonly layout: TLayout;
+  readonly selection: TSelection | null;
+  readonly selectionDrag: TSelectionDrag | null;
+}
+
+export class RuntimeRenderOrchestrator<
+  TLayout,
+  TConversation,
+  TFrame,
+  TSelection,
+  TSelectionDrag,
+  TRailViewRows,
+> {
+  constructor(
+    private readonly options: RuntimeRenderOrchestratorOptions<
+      TLayout,
+      TConversation,
+      TFrame,
+      TSelection,
+      TSelectionDrag,
+      TRailViewRows
+    >,
+  ) {}
+
+  render(input: RuntimeRenderOrchestratorInput<TLayout, TSelection, TSelectionDrag>): void {
+    if (input.shuttingDown || !this.options.isScreenDirty()) {
+      return;
+    }
+    const renderState = this.options.prepareRenderState(input.selection, input.selectionDrag);
+    if (renderState === null) {
+      this.options.clearDirty();
+      return;
+    }
+    const rail = this.options.renderLeftRail(input.layout);
+    this.options.setLatestRailViewRows(rail.viewRows);
+    const rightRows = this.options.renderRightRows({
+      layout: input.layout,
+      rightFrame: renderState.rightFrame,
+      homePaneActive: renderState.homePaneActive,
+      projectPaneActive: renderState.projectPaneActive,
+      activeDirectoryId: this.options.activeDirectoryId(),
+    });
+    this.options.flushRender({
+      layout: input.layout,
+      projectPaneActive: renderState.projectPaneActive,
+      homePaneActive: renderState.homePaneActive,
+      activeConversation: renderState.activeConversation,
+      rightFrame: renderState.rightFrame,
+      renderSelection: renderState.renderSelection,
+      selectionRows: renderState.selectionRows,
+      railAnsiRows: rail.ansiRows,
+      rightRows,
+    });
+  }
+}

package/src/services/runtime-render-pipeline.ts

@@ -0,0 +1,167 @@
+import type { computeDualPaneLayout } from '../mux/dual-pane-core.ts';
+import type { PaneSelection, PaneSelectionDrag } from '../mux/live-mux/selection.ts';
+import type {
+  TaskFocusedPaneRepositoryRecord,
+  TaskFocusedPaneTaskRecord,
+} from '../mux/task-focused-pane.ts';
+import type { TerminalSnapshotFrameCore } from '../terminal/snapshot-oracle.ts';
+import { RuntimeLeftRailRender } from './runtime-left-rail-render.ts';
+import { RuntimeRenderFlush } from './runtime-render-flush.ts';
+import { RuntimeRenderOrchestrator } from './runtime-render-orchestrator.ts';
+import { RuntimeRenderState } from './runtime-render-state.ts';
+import { RuntimeRightPaneRender } from './runtime-right-pane-render.ts';
+
+type RuntimeLayout = ReturnType<typeof computeDualPaneLayout>;
+
+type RuntimeRenderFlushOptions<TConversation, TModalOverlay, TStatusRow> = ConstructorParameters<
+  typeof RuntimeRenderFlush<
+    TConversation,
+    TerminalSnapshotFrameCore,
+    PaneSelection,
+    RuntimeLayout,
+    TModalOverlay,
+    TStatusRow
+  >
+>[0];
+
+type RuntimeRightPaneRenderOptions<
+  TRepositoryRecord extends TaskFocusedPaneRepositoryRecord,
+  TTaskRecord extends TaskFocusedPaneTaskRecord,
+> = ConstructorParameters<typeof RuntimeRightPaneRender<TRepositoryRecord, TTaskRecord>>[0];
+
+type RuntimeLeftRailRenderOptions<
+  TDirectoryRecord,
+  TConversation,
+  TRepositoryRecord,
+  TRepositorySnapshot,
+  TGitSummary,
+  TProcessUsage,
+  TShortcutBindings,
+  TRailViewRows,
+> = ConstructorParameters<
+  typeof RuntimeLeftRailRender<
+    TDirectoryRecord,
+    TConversation,
+    TRepositoryRecord,
+    TRepositorySnapshot,
+    TGitSummary,
+    TProcessUsage,
+    TShortcutBindings,
+    TRailViewRows
+  >
+>[0];
+
+type RuntimeRenderStateOptions<TConversation> = ConstructorParameters<
+  typeof RuntimeRenderState<TConversation, TerminalSnapshotFrameCore>
+>[0];
+
+interface RuntimeRenderPipelineOptions<
+  TConversation,
+  TRepositoryRecord extends TaskFocusedPaneRepositoryRecord,
+  TTaskRecord extends TaskFocusedPaneTaskRecord,
+  TDirectoryRecord,
+  TRepositorySnapshot,
+  TGitSummary,
+  TProcessUsage,
+  TShortcutBindings,
+  TRailViewRows,
+  TModalOverlay,
+  TStatusRow,
+> {
+  readonly renderFlush: RuntimeRenderFlushOptions<TConversation, TModalOverlay, TStatusRow>;
+  readonly rightPaneRender: RuntimeRightPaneRenderOptions<TRepositoryRecord, TTaskRecord>;
+  readonly leftRailRender: RuntimeLeftRailRenderOptions<
+    TDirectoryRecord,
+    TConversation,
+    TRepositoryRecord,
+    TRepositorySnapshot,
+    TGitSummary,
+    TProcessUsage,
+    TShortcutBindings,
+    TRailViewRows
+  >;
+  readonly renderState: RuntimeRenderStateOptions<TConversation>;
+  readonly isScreenDirty: () => boolean;
+  readonly clearDirty: () => void;
+  readonly setLatestRailViewRows: (rows: TRailViewRows) => void;
+  readonly activeDirectoryId: () => string | null;
+}
+
+type RuntimeRenderPipelineInput = Parameters<
+  RuntimeRenderOrchestrator<
+    RuntimeLayout,
+    unknown,
+    TerminalSnapshotFrameCore,
+    PaneSelection,
+    PaneSelectionDrag,
+    unknown
+  >['render']
+>[0];
+
+export class RuntimeRenderPipeline<
+  TConversation,
+  TRepositoryRecord extends TaskFocusedPaneRepositoryRecord,
+  TTaskRecord extends TaskFocusedPaneTaskRecord,
+  TDirectoryRecord,
+  TRepositorySnapshot,
+  TGitSummary,
+  TProcessUsage,
+  TShortcutBindings,
+  TRailViewRows,
+  TModalOverlay,
+  TStatusRow,
+> {
+  private readonly renderOrchestrator: RuntimeRenderOrchestrator<
+    RuntimeLayout,
+    TConversation,
+    TerminalSnapshotFrameCore,
+    PaneSelection,
+    PaneSelectionDrag,
+    TRailViewRows
+  >;
+
+  constructor(
+    options: RuntimeRenderPipelineOptions<
+      TConversation,
+      TRepositoryRecord,
+      TTaskRecord,
+      TDirectoryRecord,
+      TRepositorySnapshot,
+      TGitSummary,
+      TProcessUsage,
+      TShortcutBindings,
+      TRailViewRows,
+      TModalOverlay,
+      TStatusRow
+    >,
+  ) {
+    const renderFlush = new RuntimeRenderFlush(options.renderFlush);
+    const rightPaneRender = new RuntimeRightPaneRender(options.rightPaneRender);
+    const leftRailRender = new RuntimeLeftRailRender(options.leftRailRender);
+    const renderState = new RuntimeRenderState(options.renderState);
+    this.renderOrchestrator = new RuntimeRenderOrchestrator({
+      isScreenDirty: options.isScreenDirty,
+      clearDirty: options.clearDirty,
+      prepareRenderState: (selection, selectionDrag) =>
+        renderState.prepareRenderState(selection, selectionDrag),
+      renderLeftRail: (layout) => leftRailRender.render(layout),
+      setLatestRailViewRows: options.setLatestRailViewRows,
+      renderRightRows: (input) =>
+        rightPaneRender.renderRightRows({
+          layout: input.layout,
+          rightFrame: input.rightFrame,
+          homePaneActive: input.homePaneActive,
+          projectPaneActive: input.projectPaneActive,
+          activeDirectoryId: input.activeDirectoryId,
+        }),
+      flushRender: (input) => {
+        renderFlush.flushRender(input);
+      },
+      activeDirectoryId: options.activeDirectoryId,
+    });
+  }
+
+  render(input: RuntimeRenderPipelineInput): void {
+    this.renderOrchestrator.render(input);
+  }
+}

package/src/services/runtime-render-state.ts

@@ -0,0 +1,72 @@
+import type { WorkspaceModel } from '../domain/workspace.ts';
+import type { PaneSelection, PaneSelectionDrag } from '../mux/live-mux/selection.ts';
+
+interface RuntimeRenderStateOptions<TConversation, TFrame> {
+  readonly workspace: WorkspaceModel;
+  readonly hasDirectory: (directoryId: string) => boolean;
+  readonly activeConversationId: () => string | null;
+  readonly activeConversation: () => TConversation | null;
+  readonly snapshotFrame: (conversation: TConversation) => TFrame;
+  readonly selectionVisibleRows: (
+    frame: TFrame,
+    selection: PaneSelection | null,
+  ) => readonly number[];
+}
+
+interface RuntimeRenderStateResult<TConversation, TFrame> {
+  readonly projectPaneActive: boolean;
+  readonly homePaneActive: boolean;
+  readonly activeConversation: TConversation | null;
+  readonly rightFrame: TFrame | null;
+  readonly renderSelection: PaneSelection | null;
+  readonly selectionRows: readonly number[];
+}
+
+export class RuntimeRenderState<TConversation, TFrame> {
+  constructor(private readonly options: RuntimeRenderStateOptions<TConversation, TFrame>) {}
+
+  prepareRenderState(
+    selection: PaneSelection | null,
+    selectionDrag: PaneSelectionDrag | null,
+  ): RuntimeRenderStateResult<TConversation, TFrame> | null {
+    const workspace = this.options.workspace;
+    const projectPaneActive =
+      workspace.mainPaneMode === 'project' &&
+      workspace.activeDirectoryId !== null &&
+      this.options.hasDirectory(workspace.activeDirectoryId);
+    const homePaneActive = workspace.mainPaneMode === 'home';
+    if (!projectPaneActive && !homePaneActive && this.options.activeConversationId() === null) {
+      return null;
+    }
+
+    const activeConversation = this.options.activeConversation();
+    if (!projectPaneActive && !homePaneActive && activeConversation === null) {
+      return null;
+    }
+
+    const rightFrame =
+      !projectPaneActive && !homePaneActive && activeConversation !== null
+        ? this.options.snapshotFrame(activeConversation)
+        : null;
+    const renderSelection =
+      rightFrame !== null && selectionDrag !== null && selectionDrag.hasDragged
+        ? {
+            anchor: selectionDrag.anchor,
+            focus: selectionDrag.focus,
+            text: '',
+          }
+        : rightFrame !== null
+          ? selection
+          : null;
+    const selectionRows =
+      rightFrame === null ? [] : this.options.selectionVisibleRows(rightFrame, renderSelection);
+    return {
+      projectPaneActive,
+      homePaneActive,
+      activeConversation,
+      rightFrame,
+      renderSelection,
+      selectionRows,
+    };
+  }
+}