@bastani/atomic 0.8.31-alpha.4 → 0.9.0-alpha.1

package/dist/builtin/workflows/src/tui/graph-view-input.ts

@@ -0,0 +1,333 @@
+import { expandedStageTarget } from "../shared/expanded-workflow-graph.js";
+import {
+  GRAPH_SCROLL_STEP_ROWS,
+} from "./graph-view-constants.js";
+import { GraphViewRenderer } from "./graph-view-render.js";
+import { isKeybindingsLike, type KeybindingsLike } from "./keybindings-adapter.js";
+import {
+  defaultResponseFor,
+  handlePromptCardInput,
+} from "./prompt-card.js";
+import { filterStages, type SwitcherState } from "./switcher.js";
+import { Key, matchesKey } from "./text-helpers.js";
+
+/** Keyboard, mouse, switcher, prompt, and focus navigation handling. */
+export abstract class GraphViewInputController extends GraphViewRenderer {
+  /** Returns true if consumed. */
+  handleInput(data: string): boolean {
+    if (this.switcherOpen) {
+      return this._handleSwitcherInput(data);
+    }
+    // Stage-local HIL is represented by graph nodes and remains graph-first;
+    // only the legacy run-level prompt card sets `promptState`. Keep that
+    // fallback answerable, but let a narrow set of non-text graph controls
+    // through first so the workflow overlay can still be detached or scrolled
+    // instead of feeling modal while a prompt is visible. Printable keys such
+    // as "/" belong to the prompt card while legacy run-level text/editor
+    // prompts own input.
+    if (this.promptState) {
+      if (this._isNonTextGraphControlBeforePrompt(data)) {
+        return this._handleGraphInput(data);
+      }
+      return this._handlePromptInput(data);
+    }
+    return this._handleGraphInput(data);
+  }
+
+  private _promptKeybindings(): KeybindingsLike | undefined {
+    return isKeybindingsLike(this.piKeybindings) ? this.piKeybindings : undefined;
+  }
+
+  private _isNonTextGraphControlBeforePrompt(data: string): boolean {
+    return (
+      this._mouseWheelDeltaRows(data) !== 0 ||
+      matchesKey(data, Key.ctrl("d"))
+    );
+  }
+
+  private _handlePromptInput(data: string): boolean {
+    const state = this.promptState;
+    if (!state) return false;
+    const action = handlePromptCardInput(data, state, this._promptKeybindings());
+    if (action.kind === "noop") return true;
+    const runId = this.runId;
+    if (!runId) return true;
+    const response =
+      action.kind === "cancel" ? defaultResponseFor(state.prompt) : action.response;
+    this._resolvePrompt(runId, state.prompt.id, response);
+    return true;
+  }
+
+  private _resolvePrompt(runId: string, promptId: string, response: unknown): void {
+    // Clear local state immediately so the card disappears even if the
+    // host doesn't re-emit a store snapshot between resolve and render.
+    this.promptState = null;
+    if (this.onPromptResolve) {
+      this.onPromptResolve(runId, promptId, response);
+      return;
+    }
+    // Fallback path used by callers that wire GraphView directly without
+    // injecting onPromptResolve. Best-effort — if the store rejects (stale
+    // id) we already cleared local state, so we don't try to re-arm.
+    this.store.resolvePendingPrompt(runId, promptId, response);
+  }
+
+  private _handleGraphInput(data: string): boolean {
+    const stageCount = this.cachedLayout.length;
+    const wheelDeltaRows = this._mouseWheelDeltaRows(data);
+    if (wheelDeltaRows !== 0) {
+      this._scrollGraphBy(wheelDeltaRows);
+      return true;
+    }
+
+    // Vertical-graph navigation: up/down step between depth levels
+    // (col), left/right step between siblings at the same depth (row).
+    // j/k preserved as a flat-order fallback for muscle memory.
+    if (matchesKey(data, Key.down))
+      return this._moveByDepth(+1);
+    if (matchesKey(data, Key.up))
+      return this._moveByDepth(-1);
+    if (matchesKey(data, Key.right))
+      return this._moveBySibling(+1);
+    if (matchesKey(data, Key.left))
+      return this._moveBySibling(-1);
+    if (matchesKey(data, "j")) {
+      this._setFocusedIndex(Math.min(this.focusedIndex + 1, stageCount - 1));
+      return true;
+    }
+    if (matchesKey(data, "k")) {
+      this._setFocusedIndex(Math.max(this.focusedIndex - 1, 0));
+      return true;
+    }
+    if (matchesKey(data, "g")) {
+      const now = Date.now();
+      if (this._lastGTime != null && now - this._lastGTime < 500) {
+        this._setFocusedIndex(0);
+        this._lastGTime = null;
+      } else {
+        this._lastGTime = now;
+      }
+      return true;
+    }
+    if (matchesKey(data, "/")) {
+      this.switcherOpen = true;
+      this.switcherState = { query: "", selectedIndex: 0 };
+      return true;
+    }
+    if (matchesKey(data, Key.enter)) {
+      // Enter attaches the popup interior to the focused stage. The
+      // attach shell swaps in the stage-chat view without remounting
+      // the overlay; without a callback, fall back to the legacy
+      // expand/collapse toggle so non-attach hosts still work.
+      if (this._attachFocusedStage()) return true;
+      this.detailsExpanded = !this.detailsExpanded;
+      return true;
+    }
+    // `ctrl+d` detaches the whole popup (host hides the overlay). This
+    // is the graph-mode counterpart of the in-chat back affordance.
+    if (matchesKey(data, Key.ctrl("d"))) {
+      if (this.onDetach) {
+        this.onDetach();
+      } else if (this.onHide) {
+        this.onHide();
+      }
+      return true;
+    }
+    // `q` kills the active run (no confirm). `h` hides the pane via
+    // the overlay's setHidden() flag (not unmount); Escape/Ctrl+C closes.
+    if (matchesKey(data, "q")) {
+      const run = this._getCurrentRun();
+      const targetRunId = this._focusedStageTarget()?.runId ?? run?.id;
+      const targetRun = targetRunId !== undefined
+        ? this.currentSnapshot?.runs.find((candidate) => candidate.id === targetRunId)
+        : undefined;
+      if (targetRun && targetRun.endedAt === undefined && this.onKill) {
+        this.onKill(targetRun.id);
+      }
+      this.onClose?.();
+      return true;
+    }
+    if (matchesKey(data, "h") && this.onHide) {
+      this.onHide();
+      return true;
+    }
+    if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+      this.onClose?.();
+      return true;
+    }
+    return false;
+  }
+
+  private _handleSwitcherInput(data: string): boolean {
+    const stages = this.cachedLayout.map((layoutNode) => layoutNode.stage);
+
+    if (matchesKey(data, Key.escape)) {
+      this.switcherOpen = false;
+      return true;
+    }
+    if (matchesKey(data, Key.enter)) {
+      const filtered = filterStages(stages, this.switcherState.query);
+      const selected = filtered[this.switcherState.selectedIndex];
+      if (selected) {
+        const idx = this.cachedLayout.findIndex(
+          (n) => n.stage.id === selected.id,
+        );
+        if (idx !== -1) {
+          this._setFocusedIndex(idx);
+          // Selecting from the `/` switcher should complete the same
+          // action as pressing Enter on a graph node: jump straight
+          // into that stage's chat when the attach shell is present.
+          this.switcherOpen = false;
+          if (this._attachFocusedStage()) return true;
+        }
+      }
+      this.switcherOpen = false;
+      return true;
+    }
+    if (matchesKey(data, Key.down)) {
+      const filtered = filterStages(stages, this.switcherState.query);
+      this.switcherState = {
+        ...this.switcherState,
+        selectedIndex: Math.min(
+          this.switcherState.selectedIndex + 1,
+          filtered.length - 1,
+        ),
+      };
+      return true;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.switcherState = {
+        ...this.switcherState,
+        selectedIndex: Math.max(this.switcherState.selectedIndex - 1, 0),
+      };
+      return true;
+    }
+    if (matchesKey(data, Key.backspace)) {
+      this.switcherState = {
+        query: this.switcherState.query.slice(0, -1),
+        selectedIndex: 0,
+      };
+      return true;
+    }
+    if (data.length === 1 && data >= " ") {
+      this.switcherState = {
+        query: this.switcherState.query + data,
+        selectedIndex: 0,
+      };
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Move focus to the nearest node `step` depth-levels away (↑/↓).
+   * Picks the sibling with the closest `row` to the current node so
+   * navigation feels spatially continuous in the vertical layout.
+   */
+  private _moveByDepth(step: number): boolean {
+    const cur = this.cachedLayout[this.focusedIndex];
+    if (!cur) return true;
+    const targetCol = cur.col + step;
+    const candidates = this.cachedLayout
+      .map((n, i) => ({ n, i }))
+      .filter(({ n }) => n.col === targetCol);
+    if (candidates.length === 0) return true;
+    let best = candidates[0]!;
+    let bestDist = Math.abs(best.n.row - cur.row);
+    for (const c of candidates) {
+      const d = Math.abs(c.n.row - cur.row);
+      if (d < bestDist) {
+        best = c;
+        bestDist = d;
+      }
+    }
+    this._setFocusedIndex(best.i);
+    return true;
+  }
+
+  /**
+   * Move focus to the next sibling at the same depth (←/→). Clamps
+   * at the band edges — no wrap, so the user always knows when they
+   * hit a boundary.
+   */
+  private _moveBySibling(step: number): boolean {
+    const cur = this.cachedLayout[this.focusedIndex];
+    if (!cur) return true;
+    const siblings = this.cachedLayout
+      .map((n, i) => ({ n, i }))
+      .filter(({ n }) => n.col === cur.col)
+      .sort((a, b) => a.n.row - b.n.row);
+    const pos = siblings.findIndex(({ i }) => i === this.focusedIndex);
+    if (pos === -1) return true;
+    const next = siblings[pos + step];
+    if (!next) return true;
+    this._setFocusedIndex(next.i);
+    return true;
+  }
+
+  private _attachFocusedStage(): boolean {
+    if (!this.onStageAttach) return false;
+    const node = this.cachedLayout[this.focusedIndex];
+    const run = this._getCurrentRun();
+    if (!node || !run) return false;
+    const target = expandedStageTarget(this.expandedGraph, node.stage.id) ?? {
+      runId: run.id,
+      stageId: node.stage.id,
+    };
+    this.onStageAttach(target.runId, target.stageId);
+    return true;
+  }
+
+  private _focusedStageTarget(): { runId: string; stageId: string } | undefined {
+    const node = this.cachedLayout[this.focusedIndex];
+    if (!node) return undefined;
+    const target = expandedStageTarget(this.expandedGraph, node.stage.id);
+    return target ? { runId: target.runId, stageId: target.stageId } : undefined;
+  }
+
+  private _setFocusedIndex(index: number): void {
+    const max = Math.max(0, this.cachedLayout.length - 1);
+    const next = Math.max(0, Math.min(index, max));
+    if (next === this.focusedIndex) return;
+    this.focusedIndex = next;
+    this.pendingEnsureFocusedVisible = true;
+  }
+
+  private _scrollGraphBy(deltaRows: number): void {
+    this.pendingEnsureFocusedVisible = false;
+    this.graphScrollOffset = Math.max(0, this.graphScrollOffset + deltaRows);
+  }
+
+  private _mouseWheelDeltaRows(data: string): number {
+    const sgr = data.match(/^\x1b\[<(\d+);\d+;\d+M$/);
+    if (sgr) {
+      return this._wheelDeltaForButtonCode(Number.parseInt(sgr[1]!, 10));
+    }
+    if (data.startsWith("\x1b[M") && data.length >= 6) {
+      return this._wheelDeltaForButtonCode(data.charCodeAt(3) - 32);
+    }
+    return 0;
+  }
+
+  private _wheelDeltaForButtonCode(code: number): number {
+    if ((code & 64) === 0) return 0;
+    const direction = code & 3;
+    if (direction === 0) return -GRAPH_SCROLL_STEP_ROWS;
+    if (direction === 1) return GRAPH_SCROLL_STEP_ROWS;
+    return 0;
+  }
+
+  // ---- test seams ----
+  get _focusedIndex(): number {
+    return this.focusedIndex;
+  }
+  get _switcherOpen(): boolean {
+    return this.switcherOpen;
+  }
+  get _switcherState(): SwitcherState {
+    return this.switcherState;
+  }
+  get _graphScrollOffset(): number {
+    return this.graphScrollOffset;
+  }
+}

package/dist/builtin/workflows/src/tui/graph-view-render-helpers.ts

@@ -0,0 +1,336 @@
+import { GraphCanvas } from "./graph-canvas.js";
+import {
+  HINT_KEYS,
+  MODE_PILL_LABEL,
+  OVERLAY_LINE_COUNT,
+  OVERLAY_VERTICAL_MARGIN_ROWS,
+} from "./graph-view-constants.js";
+import { GraphViewState } from "./graph-view-state.js";
+import { renderOutlinePill } from "./header.js";
+import { NODE_H, NODE_W } from "./layout.js";
+import {
+  sliceColumns,
+  truncateToWidth,
+  visibleWidth,
+} from "./text-helpers.js";
+import { BOLD, hexBg, hexToAnsi, RESET } from "./color-utils.js";
+
+/** Low-level overlay geometry, chrome, ANSI canvas, and edge helpers. */
+export abstract class GraphViewRenderHelpers extends GraphViewState {
+  /**
+   * Number of rows the overlay frame must paint. Pi-tui anchors the
+   * overlay vertically by counting rendered lines, so to truly fill the
+   * terminal under `maxHeight: "100%"` the component must emit
+   * approximately `terminal.rows` lines. When a host reports fewer
+   * than the legacy 32 rows, honour that shorter viewport where the
+   * graph chrome can still fit so the bottom status controls are not
+   * clipped by pi-tui's overlay max-height slicing. A host that doesn't
+   * surface terminal dimensions keeps the previous stable rectangle.
+   */
+  protected _overlayLineCount(): number {
+    const reported = this.getViewportRows?.();
+    if (typeof reported !== "number" || !Number.isFinite(reported)) {
+      return OVERLAY_LINE_COUNT;
+    }
+    // Header (3) + one body row + statusline (3) is the absolute
+    // minimum useful frame. Margins are dropped automatically at this
+    // size by `_overlayVerticalMarginRows`.
+    return Math.max(7, Math.floor(reported));
+  }
+
+  /** Rows available for the graph body (between header and statusline). */
+  protected _overlayBodyRows(lineCount: number): number {
+    return Math.max(1, lineCount - 3 /* header */ - 3 /* statusline */);
+  }
+
+  protected _overlayVerticalMarginRows(lineCount = this._overlayLineCount()): number {
+    return lineCount >= 9 ? OVERLAY_VERTICAL_MARGIN_ROWS : 0;
+  }
+
+  protected _overlayPanelLineCount(): number {
+    const lineCount = this._overlayLineCount();
+    const margins = this._overlayVerticalMarginRows(lineCount) * 2;
+    return Math.max(7, lineCount - margins);
+  }
+
+  protected _marginRow(width: number): string {
+    return " ".repeat(width);
+  }
+
+  protected _withVerticalMargins(panelLines: string[], width: number): string[] {
+    const expected = this._overlayLineCount();
+    const marginRows = this._overlayVerticalMarginRows(expected);
+    const panelTarget = this._overlayPanelLineCount();
+    const body = panelLines.slice(0, panelTarget);
+    while (body.length < panelTarget) body.push(this._blankRow(width));
+    const margins = Array.from({ length: marginRows }, () => this._marginRow(width));
+    const lines = [...margins, ...body, ...margins];
+    if (lines.length > expected) return lines.slice(0, expected);
+    while (lines.length < expected) {
+      const insertAt = marginRows > 0 ? Math.max(0, lines.length - marginRows) : lines.length;
+      lines.splice(insertAt, 0, this._blankRow(width));
+    }
+    return lines;
+  }
+
+  /**
+   * Three-row statusline pinned to the bottom of the overlay. Mirrors
+   * the header band: `backgroundPanel` chrome, outlined accent pill
+   * flush-left, hints flowing right on the centre row.
+   */
+  protected _renderStatusline(width: number): string[] {
+    const t = this.graphTheme;
+    const chromeBg = hexBg(t.backgroundPanel);
+    const text = hexToAnsi(t.text);
+    const muted = hexToAnsi(t.textMuted);
+    const dim = hexToAnsi(t.dim);
+
+    const {
+      top,
+      mid,
+      bot,
+      visibleWidth: pillW,
+    } = renderOutlinePill(MODE_PILL_LABEL, t.accent, chromeBg);
+
+    // Hints — `<key> <label>` separated by `  ·  `.
+    const sep = `${chromeBg}  ${dim}·${RESET}${chromeBg}  `;
+    const segments = HINT_KEYS.map(
+      ({ key, label }) =>
+        `${text}${BOLD}${key}${RESET}${chromeBg} ${muted}${label}${RESET}${chromeBg}`,
+    );
+    const hintsStyledRaw = segments.join(sep);
+
+    const leftEdgePad = 1;
+    const rightEdgePad = 2;
+    const hintsBudget = Math.max(0, width - leftEdgePad - pillW - rightEdgePad);
+    const hintsStyled = truncateToWidth(hintsStyledRaw, hintsBudget, "");
+    const hintsVisibleLen = visibleWidth(hintsStyled);
+    const fillerVisible = Math.max(0, hintsBudget - hintsVisibleLen);
+    const filler = " ".repeat(fillerVisible);
+    const blankAcross = " ".repeat(Math.max(0, width - leftEdgePad - pillW));
+
+    return [
+      `${chromeBg} ${RESET}${top}${chromeBg}${blankAcross}${RESET}`,
+      `${chromeBg} ${RESET}${mid}${chromeBg}${filler}${hintsStyled}${chromeBg}${" ".repeat(rightEdgePad)}${RESET}`,
+      `${chromeBg} ${RESET}${bot}${chromeBg}${blankAcross}${RESET}`,
+    ];
+  }
+
+  /** Blank canvas row — single line of `bg`. */
+  protected _blankRow(width: number): string {
+    return `${hexBg(this.graphTheme.bg)}${" ".repeat(width)}${RESET}`;
+  }
+
+  protected _centerCanvasContent(content: string, width: number): string {
+    const truncated = truncateToWidth(content, width, "…", true);
+    const leftPad = Math.max(0, Math.floor((width - visibleWidth(truncated)) / 2));
+    return `${" ".repeat(leftPad)}${truncated}`;
+  }
+
+  /** Wrap content in a canvas-bg row, padded to `width`. Re-emits the
+   * bg ANSI right before the trailing fill so any internal `RESET`
+   * from cards/edges doesn't let the terminal default bleed through. */
+  protected _canvasRow(content: string, width: number): string {
+    const bg = hexBg(this.graphTheme.bg);
+    const truncated = truncateToWidth(content, width, "…", true);
+    const padLen = Math.max(0, width - visibleWidth(truncated));
+    return `${bg}${truncated}${bg}${" ".repeat(padLen)}${RESET}`;
+  }
+
+  /** Pad pre-styled content out to canvas width without truncation.
+   * Re-emits the body bg ANSI right before the trailing fill so any
+   * internal RESET inside `content` doesn't leak the terminal default. */
+  protected _padCanvas(content: string, width: number): string {
+    const bg = hexBg(this.graphTheme.bg);
+    const padLen = Math.max(0, width - visibleWidth(content));
+    return `${bg}${content}${bg}${" ".repeat(padLen)}${RESET}`;
+  }
+
+  /**
+   * Compose a pre-styled card line over a canvas row at `leftPad` columns.
+   * The base row keeps its `bg` (so background colour matches canvas);
+   * the card slice replaces the cells starting at `leftPad`, and the
+   * residual columns to the right are repainted with bg.
+   *
+   * We don't try to keep the parts of `base` that fall *under* the card
+   * — pi-tui paints flat lines, not z-buffered cells, so the card's panel
+   * background winning is fine.
+   */
+  protected _overlayCard(
+    _base: string,
+    cardLine: string,
+    leftPad: number,
+    totalWidth: number,
+  ): string {
+    const bg = hexBg(this.graphTheme.bg);
+    const cardW = visibleWidth(cardLine);
+    const rightPadLen = Math.max(0, totalWidth - leftPad - cardW);
+    return `${bg}${" ".repeat(leftPad)}${RESET}${cardLine}${bg}${" ".repeat(rightPadLen)}${RESET}`;
+  }
+
+  protected _clampGraphScroll(totalRows: number, bodyRows: number): void {
+    const maxOffset = Math.max(0, totalRows - bodyRows);
+    this.graphScrollOffset = Math.max(
+      0,
+      Math.min(maxOffset, this.graphScrollOffset),
+    );
+  }
+
+  protected _clampGraphHorizontalScroll(totalCols: number, viewportCols: number): void {
+    const maxOffset = Math.max(0, totalCols - viewportCols);
+    this.graphScrollColOffset = Math.max(
+      0,
+      Math.min(maxOffset, this.graphScrollColOffset),
+    );
+  }
+
+  protected _scrollFocusedColumnIntoView(
+    viewportCols: number,
+    totalCols: number,
+  ): void {
+    const node = this.cachedLayout[this.focusedIndex];
+    if (!node) return;
+    const start = node.x;
+    const end = node.x + NODE_W - 1;
+    if (start < this.graphScrollColOffset) {
+      this.graphScrollColOffset = start;
+    } else if (end >= this.graphScrollColOffset + viewportCols) {
+      this.graphScrollColOffset = end - viewportCols + 1;
+    }
+    this._clampGraphHorizontalScroll(totalCols, viewportCols);
+  }
+
+  protected _scrollFocusedIntoView(
+    frameWidth: number,
+    bodyRows: number,
+    totalRows: number,
+  ): void {
+    const range = this._focusedGraphRowRange(frameWidth);
+    if (!range) return;
+    if (range.start < this.graphScrollOffset) {
+      this.graphScrollOffset = range.start;
+    } else if (range.end >= this.graphScrollOffset + bodyRows) {
+      this.graphScrollOffset = range.end - bodyRows + 1;
+    }
+    this._clampGraphScroll(totalRows, bodyRows);
+  }
+
+  protected _focusedGraphRowRange(_frameWidth: number): { start: number; end: number } | null {
+    const node = this.cachedLayout[this.focusedIndex];
+    if (!node) return null;
+    return { start: node.y, end: node.y + NODE_H - 1 };
+  }
+
+  /**
+   * Plot a parent → child edge for the vertical orientation. The edge
+   * exits from the parent's bottom-centre, runs through a horizontal
+   * spine half-way down the gap, and re-enters from the child's
+   * top-centre. Cells are merged by direction set so fan-out, fan-in,
+   * and crossings produce stable orthogonal junctions instead of
+   * stacked rounded corners.
+   */
+  protected _plotEdge(
+    canvas: GraphCanvas,
+    px: number,
+    py: number,
+    cx: number,
+    cy: number,
+    color: string,
+  ): void {
+    const parentCol = px + Math.floor(NODE_W / 2);
+    const childCol = cx + Math.floor(NODE_W / 2);
+    const parentExitRow = py + NODE_H; // first row below parent's bottom border
+    const childEntryRow = cy - 1; // last row above child's top border
+    if (childEntryRow < parentExitRow) return;
+
+    if (parentCol === childCol) {
+      canvas.vline(parentCol, parentExitRow, childEntryRow, color);
+      return;
+    }
+
+    const spineRow = Math.max(
+      parentExitRow,
+      Math.min(childEntryRow, Math.floor((parentExitRow + childEntryRow) / 2)),
+    );
+
+    // Down stub from parent into the spine row.
+    if (spineRow > parentExitRow) {
+      canvas.vline(parentCol, parentExitRow, spineRow - 1, color);
+    }
+    this._placeJunction(canvas, spineRow, parentCol, ["u", childCol > parentCol ? "r" : "l"], color);
+
+    // Horizontal spine segment.
+    const hloCol = Math.min(parentCol, childCol) + 1;
+    const hhiCol = Math.max(parentCol, childCol) - 1;
+    if (hhiCol >= hloCol) {
+      canvas.hline(spineRow, hloCol, hhiCol, color);
+    }
+    this._placeJunction(canvas, spineRow, childCol, [childCol > parentCol ? "l" : "r", "d"], color);
+
+    // Down stub from spine into child.
+    if (childEntryRow > spineRow) {
+      canvas.vline(childCol, spineRow + 1, childEntryRow, color);
+    }
+  }
+
+  protected _placeJunction(
+    canvas: GraphCanvas,
+    row: number,
+    col: number,
+    newDirs: Array<"u" | "d" | "l" | "r">,
+    color: string,
+  ): void {
+    canvas.mergeCell(row, col, newDirs, color);
+  }
+
+  /**
+   * Split the canvas-rendered edge row at card boundaries into spans of
+   * `{ startCol, visibleWidth, content }` so the composer can interleave
+   * cards without colliding.
+   */
+  protected _edgeRowToCells(line: string): string {
+    return line;
+  }
+
+  /**
+   * Interleave a single edge row with the node cards that cross it.
+   * Cards take precedence at their column ranges; edge characters fill
+   * the gaps. Returns one composed line padded with spaces.
+   */
+  protected _composeRow(
+    edgeRow: string,
+    cards: Array<{ startCol: number; width: number; line: string }>,
+    _edgeColor: string,
+  ): string {
+    const bg = hexBg(this.graphTheme.bg);
+    const sorted = cards.slice().sort((a, b) => a.startCol - b.startCol);
+    let cursor = 0;
+    let out = "";
+    for (const card of sorted) {
+      if (card.startCol > cursor) {
+        // Edge segment up to card start — prepend bg so empty cells
+        // in this stretch keep the body bg instead of falling back
+        // to the terminal default once any prior RESET fired.
+        out += `${bg}${this._edgeSegment(edgeRow, cursor, card.startCol)}`;
+        cursor = card.startCol;
+      }
+      out += card.line;
+      cursor += card.width;
+    }
+    // Trailing edge tail — same bg re-priming.
+    out += `${bg}${this._edgeSegment(edgeRow, cursor, Math.max(cursor, visibleWidth(edgeRow)))}`;
+    return out;
+  }
+
+  protected _edgeSegment(line: string, fromCol: number, toCol: number): string {
+    if (fromCol >= toCol) return "";
+    const segment = this._sliceColumns(line, fromCol, toCol);
+    const visible = visibleWidth(segment);
+    return `${segment}${" ".repeat(Math.max(0, toCol - fromCol - visible))}`;
+  }
+
+  protected _sliceColumns(line: string, fromCol: number, toCol: number): string {
+    if (fromCol >= toCol) return "";
+    return sliceColumns(line, fromCol, toCol - fromCol, true);
+  }
+}