pi-weave 0.1.6 → 0.1.7

package/src/pi/viewer/tui/surface/base.ts

@@ -0,0 +1,182 @@
+/**
+ * surface/base.ts — the shared Pane<Surface> wrapper (weave-view-tui-v2 §6).
+ *
+ * A **Surface** is a harness-free, self-owned component: it holds its own
+ * selection/scroll/filter/expansion state, renders its lines, and handles its
+ * own keys. Surfaces share the GraphModel, BodyStore, and loaders via a
+ * `SurfaceContext`. A **Pane** is a `Component` that hosts a Surface inside a
+ * bordered Box with a title and a focus ring (accent when active, dim `line`
+ * when inactive — conveyed by border + a leading `◆`, not color alone, per
+ * §10).
+ *
+ * The pane owns scrolling via the injected scroll/offset on the surface; the
+ * workspace root routes input to the single active pane's surface.
+ */
+
+import { truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import type { GraphModel } from "../../../../core/graph/model";
+import { BodyStore } from "../bodyStore";
+import type { WeaveLoaders, WeaveTheme } from "../explorer";
+import type { SurfaceKind } from "../workspace";
+import type { ThemeSlot } from "../theme";
+
+/** A cross-pane navigation request a surface emits (resolved by the root). */
+export type SurfaceEvent =
+  | { type: "openDetail"; id: string }
+  | { type: "focusNode"; id: string }
+  | { type: "openEditor"; id: string };
+
+/** A surface emits events (e.g. "open detail") that the workspace root resolves. */
+export type SurfaceEventHandler = (event: SurfaceEvent) => void;
+
+/** Shared, session-level deps every surface reads. */
+export interface SurfaceContext {
+  model: GraphModel;
+  theme: WeaveTheme;
+  loaders: WeaveLoaders;
+  bodies: BodyStore;
+  /** Reference clock (epoch ms); defaults to Date.now at the root. */
+  now: () => number;
+}
+
+/** A surface can also be constructed with a render callback (test seam). */
+export interface SurfaceInit {
+  context: SurfaceContext;
+  /** Emit a cross-pane navigation event. */
+  onEvent?: SurfaceEventHandler;
+}
+
+/** What a surface component must expose on top of the pi-tui Component contract. */
+export interface Surface extends Component {
+  /** The surface kind this hosts. */
+  readonly kind: SurfaceKind;
+  /** Called by the workspace root when focus moves to/from this surface. */
+  setFocused(focused: boolean): void;
+  /** The pane title (surface name), shown in the border. */
+  title(): string;
+  /**
+   * Called after a refresh rebuilds the model, so a surface bound to a node
+   * that no longer exists can rebind to a survivor instead of showing
+   * "(not found)". Optional — surfaces with no node binding omit it.
+   */
+  rebind?(model: GraphModel): void;
+}
+
+/** Minimal theme surface the pane chrome needs. */
+export interface PaneTheme {
+  fg(slot: ThemeSlot, text: string): string;
+  bold(text: string): string;
+}
+
+/** A selectable row within a rendered surface (mirrors model.SelectableRow). */
+export interface PaneRow {
+  id: string;
+  /** Node id a row jumps to on enter (links/backlinks/neighbors). */
+  target?: string;
+}
+
+/** The render result of a surface: lines plus the selectable rows. */
+export interface SurfaceRender {
+  lines: string[];
+  rows: PaneRow[];
+}
+
+/** A generic selectable, windowed body builder used by the surfaces. */
+export function windowLines(
+  lines: string[],
+  selLine: number,
+  scrollOffset: number,
+  window: number,
+  marker: (text: string) => string,
+): string[] {
+  const win = Math.max(1, window);
+  let offset = scrollOffset;
+  if (selLine >= 0) {
+    if (selLine < offset) offset = selLine;
+    else if (selLine >= offset + win) offset = selLine - win + 1;
+  }
+  offset = Math.max(0, Math.min(offset, Math.max(0, lines.length - win)));
+  const out: string[] = [];
+  const end = Math.min(lines.length, offset + win);
+  for (let i = offset; i < end; i++) {
+    const ln = lines[i]!;
+    out.push(i === selLine ? marker(ln) : `  ${ln}`);
+  }
+  return out;
+}
+
+/**
+ * Pane — a bordered Box hosting a Surface. Renders a title + focus ring on
+ * the first line, then the surface's (windowed) lines. This is the v1 single
+ * pane chrome lifted into a reusable wrapper; the workspace root instantiates
+ * one Pane per pane node.
+ */
+export class Pane implements Component {
+  private readonly surface: Surface;
+  private readonly theme: PaneTheme;
+  private readonly borderFn: (slot: ThemeSlot, text: string) => string;
+  /** Current viewport height in rows (for windowing). */
+  rows = 24;
+  focused = false;
+  private cacheKey = "";
+
+  constructor(
+    surface: Surface,
+    theme: PaneTheme,
+    // Bind through the theme object: a bare `theme.fg` default would detach
+    // `this`, so the real pi theme's `fg` (which reads `this.fgColors.get(...)`)
+    // would crash with "Cannot read properties of undefined (reading 'get')".
+    borderFn: (slot: ThemeSlot, text: string) => string = (slot, text) => theme.fg(slot, text),
+  ) {
+    this.surface = surface;
+    this.theme = theme;
+    this.borderFn = borderFn;
+  }
+
+  get surfaceComponent(): Surface {
+    return this.surface;
+  }
+
+  setFocused(focused: boolean): void {
+    this.focused = focused;
+    this.surface.setFocused(focused);
+  }
+
+  invalidate(): void {
+    this.cacheKey = "";
+    this.surface.invalidate();
+  }
+
+  render(width: number): string[] {
+    const inner = Math.max(2, width - 2);
+    // The surface already windows + selection-marks its own lines (each
+    // surface owns its scroll/selection state). The pane only wraps them in a
+    // border and PADS to fill its allocated height so the split looks clean —
+    // it must NOT re-window (that double-applies the indent/marker and corrupts
+    // the layout). Each body line is sliced/padded to `inner` so borders align.
+    const surfaceLines = this.surface.render(inner);
+    const title = this.surface.title();
+    const active = this.focused;
+    const borderSlot = active ? "accent" : "dim";
+    const marker = active ? "◆ " : "  ";
+    const titleText = `${marker}${title}  `;
+    const top = `${this.borderFn(borderSlot, "┌")}${this.borderFn("dim", "─".repeat(inner))}${this.borderFn(borderSlot, "┐")}`;
+    const titleVis = visibleWidth(titleText);
+    const titleLine = `${this.borderFn(borderSlot, "│")}${this.theme.bold(titleText)}${" ".repeat(Math.max(0, inner - titleVis))}${this.borderFn(borderSlot, "│")}`;
+    // top + title + bottom = 3 fixed lines; body fills the rest so both panes
+    // in a split render the same height.
+    const bodyRows = Math.max(0, this.rows - 3);
+    const out = [top, titleLine];
+    for (let i = 0; i < bodyRows; i++) {
+      const ln = surfaceLines[i] ?? "";
+      const slice = visibleWidth(ln) > inner ? truncateToWidth(ln, inner) : ln;
+      const pad = Math.max(0, inner - visibleWidth(slice));
+      out.push(`${this.borderFn(borderSlot, "│")}${slice}${" ".repeat(pad)}${this.borderFn(borderSlot, "│")}`);
+    }
+    const bottom = `${this.borderFn(borderSlot, "└")}${this.borderFn("dim", "─".repeat(inner))}${this.borderFn(borderSlot, "┘")}`;
+    out.push(bottom);
+    return out;
+  }
+}
+
+export type { Component, SurfaceKind };

package/src/pi/viewer/tui/surface/detail.ts

@@ -0,0 +1,315 @@
+/**
+ * surface/detail.ts — the Detail surface as a Component (weave-view-tui-v2 §6).
+ *
+ * Shows a node's meta, its (real Markdown) body, and links/backlinks. Each
+ * Detail pane owns its own bound node + selection/scroll. Enter on a link
+ * rebinds the pane in place (decision: a Detail pane re-navigates within
+ * itself); the body is rendered through the pi-tui `Markdown` component with
+ * a MarkdownTheme mapped from the weave theme (decision 7).
+ */
+
+import { Markdown, matchesKey, type MarkdownTheme, truncateToWidth } from "@earendil-works/pi-tui";
+import { detailModel, sanitizeTerminalText, type DetailModel } from "../model";
+import { kindStyle, provenanceStyle, type ThemeSlot } from "../theme";
+import { type Surface, type SurfaceEvent, type SurfaceInit } from "./base";
+import type { GraphModel } from "../../../../core/graph/model";
+import type { NoteSource } from "../../../../core/types";
+
+/** A flattened Detail render line. `id` marks a selectable row (meta/links/
+ *  backlinks); `target` is the node id an Enter on that row rebinds to. Both
+ *  are optional and may be explicitly `undefined` (body/header lines have
+ *  neither) — declared `| undefined` so the object literals below type-check
+ *  under `exactOptionalPropertyTypes`. */
+type DetailLine = { text: string; id?: string | undefined; target?: string | undefined };
+
+export interface DetailSurfaceState {
+  nodeId: string | null;
+  selectedId: string | null;
+  scrollOffset: number;
+  /** Goto-line buffer: `null`/undefined = not in goto mode; a string (possibly
+   *  empty) = the user is typing a line number to jump to. `/` enters goto,
+   *  digits append, Enter jumps, Backspace deletes, Esc cancels. The workspace
+   *  root treats a non-null `gotoBuf` as a sub-mode so Esc cancels instead of
+   *  quitting (mirrors Explore's `searching`). */
+  gotoBuf?: string | null;
+}
+
+export function bindDetail(init: SurfaceInit, nodeId: string): DetailSurface {
+  const s = new DetailSurface(init);
+  s.state = { nodeId, selectedId: nodeId, scrollOffset: 0 };
+  return s;
+}
+
+export class DetailSurface implements Surface {
+  readonly kind = "detail" as const;
+  private readonly ctx;
+  private readonly onEvent: ((e: SurfaceEvent) => void) | undefined;
+  state: DetailSurfaceState;
+  paneRows = 24;
+  /** Cached flattened render lines (with ids/targets) from the last render, so
+   *  handleInput can compute the viewport center / active row + max scroll
+   *  offset without re-rendering. Bust on invalidate / rebind. */
+  private _lines: DetailLine[] | undefined;
+
+  constructor(init: SurfaceInit) {
+    this.ctx = init.context;
+    this.onEvent = init.onEvent;
+    this.state = { nodeId: init.context.model.nodes[0]?.id ?? null, selectedId: null, scrollOffset: 0 };
+  }
+
+  title(): string {
+    return "Detail";
+  }
+
+  setFocused(_focused: boolean): void {
+    // detail has no focus-only state
+  }
+
+  invalidate(): void {
+    // Drop the cached line layout so the next render rebuilds it from the
+    // current body (BodyStore loads fire onChange at the root → invalidate).
+    this._lines = undefined;
+  }
+
+  rebind(model: GraphModel): void {
+    // After a refresh, a detail pane may be bound to a node that was removed.
+    // Rebind to the first surviving node so the pane never shows a stale
+    // "(node not found)" after the model is rebuilt.
+    if (this.state.nodeId && !model.nodes.some((n) => n.id === this.state.nodeId)) {
+      const first = model.nodes[0]?.id ?? null;
+      this.state = { nodeId: first, selectedId: first, scrollOffset: 0, gotoBuf: null };
+      this._lines = undefined;
+    }
+  }
+
+  handleInput(data: string): void {
+    const paneRows = Math.max(5, this.paneRows);
+    if (!this._lines) this._lines = this.buildLines(80);
+    const maxOffset = Math.max(0, this._lines.length - paneRows);
+    const clamp = (n: number): number => Math.max(0, Math.min(maxOffset, n));
+
+    // Goto-line sub-mode: digits build a line number, Enter jumps, Esc/bs exit.
+    if (this.state.gotoBuf != null) {
+      if (matchesKey(data, "escape")) {
+        this.state = { ...this.state, gotoBuf: null };
+        return;
+      }
+      if (matchesKey(data, "enter")) {
+        const n = parseInt(this.state.gotoBuf, 10);
+        this.state = { ...this.state, scrollOffset: clamp(Number.isNaN(n) || n < 1 ? 0 : n - 1), gotoBuf: null };
+        return;
+      }
+      if (matchesKey(data, "backspace")) {
+        const b = this.state.gotoBuf.slice(0, -1);
+        this.state = { ...this.state, gotoBuf: b.length ? b : null };
+        return;
+      }
+      if (data.length === 1 && data >= "0" && data <= "9" && this.state.gotoBuf.length < 5) {
+        this.state = { ...this.state, gotoBuf: this.state.gotoBuf + data };
+        return;
+      }
+      return; // ignore unmapped keys while typing a line number
+    }
+
+    if (data === "o") {
+      if (this.state.nodeId) this.onEvent?.({ type: "openEditor", id: this.state.nodeId });
+      return;
+    }
+    // Scroll-primary: arrows/page/home/end move the viewport; the selectable
+    // row nearest the viewport center is the active (›) row — Enter opens it.
+    if (matchesKey(data, "up")) {
+      this.state = { ...this.state, scrollOffset: clamp(this.state.scrollOffset - 1) };
+      return;
+    }
+    if (matchesKey(data, "down")) {
+      this.state = { ...this.state, scrollOffset: clamp(this.state.scrollOffset + 1) };
+      return;
+    }
+    if (matchesKey(data, "pageUp")) {
+      this.state = { ...this.state, scrollOffset: clamp(this.state.scrollOffset - paneRows) };
+      return;
+    }
+    if (matchesKey(data, "pageDown")) {
+      this.state = { ...this.state, scrollOffset: clamp(this.state.scrollOffset + paneRows) };
+      return;
+    }
+    if (matchesKey(data, "home")) {
+      this.state = { ...this.state, scrollOffset: 0 };
+      return;
+    }
+    if (matchesKey(data, "end")) {
+      this.state = { ...this.state, scrollOffset: maxOffset };
+      return;
+    }
+    if (data === "/") {
+      this.state = { ...this.state, gotoBuf: "" };
+      return;
+    }
+    if (matchesKey(data, "enter")) {
+      const row = this.activeRow();
+      if (row?.target) {
+        // rebind this detail pane to the target (Obsidian "open in main" in place)
+        this.state = { nodeId: row.target, selectedId: row.target, scrollOffset: 0, gotoBuf: null };
+        this._lines = undefined;
+        this.requestBody(row.target);
+      }
+      return;
+    }
+  }
+
+  /** The selectable row (meta/links/backlinks) nearest the viewport center. */
+  private activeRow(): { id: string; target?: string | undefined } | undefined {
+    const lines = this._lines;
+    if (!lines) return undefined;
+    const paneRows = Math.max(5, this.paneRows);
+    const center = this.state.scrollOffset + Math.floor(paneRows / 2);
+    let bestI = -1;
+    let best = Infinity;
+    for (let i = 0; i < lines.length; i++) {
+      const ln = lines[i]!;
+      if (!ln.id) continue;
+      const d = Math.abs(i - center);
+      if (d < best) {
+        best = d;
+        bestI = i;
+      }
+    }
+    return bestI >= 0 ? { id: lines[bestI]!.id!, target: lines[bestI]!.target } : undefined;
+  }
+
+  /** Flatten the detail (title + meta + body + links + backlinks) into lines. */
+  private buildLines(width: number): DetailLine[] {
+    const t = this.ctx.theme;
+    const id = this.state.nodeId;
+    if (!id) return [];
+    const d = detailModel(this.ctx.model, id);
+    if (!d) return [];
+    const lines: DetailLine[] = [];
+    const marker = this.rowMarker(d.kind, d.provenance);
+    const provBadge = d.provenance ? ` ${provenanceStyle(d.provenance).glyph} ${provenanceStyle(d.provenance).word}` : "";
+    lines.push({ text: t.bold(`${marker}${sanitizeTerminalText(d.label)}`) + t.fg("muted", ` (${d.kind}${provBadge})`) });
+    for (const m of d.meta) {
+      lines.push({ text: `${t.fg("muted", sanitizeTerminalText(m.label))}: ${sanitizeTerminalText(m.value)}`, id: m.id });
+    }
+    const body = this.bodyLinesFor(id, width);
+    for (const b of body) lines.push({ text: b });
+    if (d.links.length > 0) {
+      lines.push({ text: t.fg("accent", "Links") });
+      for (const lk of d.links) {
+        lines.push({ text: `  ${this.rowMarker(lk.kind, lk.provenance)}${sanitizeTerminalText(lk.label)}`, id: lk.id, target: lk.target });
+      }
+    }
+    if (d.backlinks.length > 0) {
+      lines.push({ text: t.fg("accent", "Backlinks") });
+      for (const lk of d.backlinks) {
+        lines.push({ text: `  ${this.rowMarker(lk.kind, lk.provenance)}${sanitizeTerminalText(lk.label)}`, id: lk.id, target: lk.target });
+      }
+    }
+    return lines;
+  }
+
+  render(width: number): string[] {
+    const t = this.ctx.theme;
+    const id = this.state.nodeId;
+    if (!id) return [t.fg("dim", "(no selection)")];
+    const d = detailModel(this.ctx.model, id);
+    if (!d) return [t.fg("dim", "(node not found)")];
+
+    const lines = this.buildLines(width);
+    this._lines = lines;
+    const paneRows = Math.max(5, this.paneRows);
+    const maxOffset = Math.max(0, lines.length - paneRows);
+    const scrollOffset = Math.max(0, Math.min(this.state.scrollOffset, maxOffset));
+    if (scrollOffset !== this.state.scrollOffset) {
+      this.state = { ...this.state, scrollOffset };
+    }
+
+    // Active row = selectable row nearest the viewport center.
+    const center = scrollOffset + Math.floor(paneRows / 2);
+    let activeI = -1;
+    let best = Infinity;
+    for (let i = 0; i < lines.length; i++) {
+      if (!lines[i]!.id) continue;
+      const dist = Math.abs(i - center);
+      if (dist < best) {
+        best = dist;
+        activeI = i;
+      }
+    }
+    const activeId = activeI >= 0 ? (lines[activeI]!.id ?? null) : null;
+    if (this.state.selectedId !== activeId) {
+      this.state = { ...this.state, selectedId: activeId };
+    }
+
+    const inGoto = this.state.gotoBuf != null;
+    // Reserve the last viewport line for the goto prompt when active.
+    const contentRows = inGoto ? Math.max(1, paneRows - 1) : paneRows;
+    const start = scrollOffset;
+    const end = Math.min(lines.length, start + contentRows);
+    const marker2 = (text: string) => `› ${this.ctx.theme.bg("selectedBg", text)}`;
+    const out: string[] = [];
+    for (let i = start; i < end; i++) {
+      out.push(i === activeI ? marker2(lines[i]!.text) : `  ${lines[i]!.text}`);
+    }
+    if (inGoto) {
+      out.push(`${t.fg("accent", "/")}${this.state.gotoBuf}`);
+    }
+    return out.map((l) => truncateToWidth(l, width));
+  }
+
+  private rowMarker(kind: string, prov: NoteSource | null): string {
+    const ks = kindStyle(kind as never);
+    if (kind === "note") {
+      const ps = provenanceStyle(prov);
+      return ps.glyph ? `${ps.glyph} ` : "";
+    }
+    return `${this.ctx.theme.fg(ks.slot as ThemeSlot, `${ks.glyph} `)}`;
+  }
+
+  private requestBody(id: string): void {
+    const node = this.ctx.model.nodes.find((n) => n.id === id);
+    if (!node) return;
+    if (node.kind === "note") this.ctx.bodies.load(id, "note", node.detail.slug);
+    else if (node.kind === "file") this.ctx.bodies.load(id, "file", node.detail.path);
+  }
+
+  /** The node body, rendered through the real Markdown component (decision 7). */
+  private bodyLinesFor(id: string, width: number): string[] {
+    const node = this.ctx.model.nodes.find((n) => n.id === id);
+    if (!node || (node.kind !== "note" && node.kind !== "file")) return [];
+    if (this.ctx.bodies.isLoading(id)) return [this.ctx.theme.fg("dim", "(loading…)")];
+    const body = this.ctx.bodies.get(id);
+    if (body === undefined) {
+      queueMicrotask(() => this.requestBody(id));
+      return [this.ctx.theme.fg("dim", "(loading…)")];
+    }
+    if (body === null || body === "") return [];
+    const md = new Markdown(sanitizeTerminalText(body), 0, 0, markdownTheme(this.ctx.theme), { color: (t) => this.ctx.theme.fg("text", t) }, { renderLatex: false });
+    return md.render(Math.max(10, width - 2)).map((l) => `  ${l}`);
+  }
+}
+
+/** Map the weave theme slots onto a pi-tui MarkdownTheme. */
+export function markdownTheme(theme: {
+  fg: (slot: ThemeSlot, text: string) => string;
+  bold: (text: string) => string;
+}): MarkdownTheme {
+  return {
+    heading: (t) => theme.bold(t),
+    link: (t) => theme.fg("accent", t),
+    linkUrl: (t) => theme.fg("muted", t),
+    code: (t) => theme.fg("warning", t),
+    codeBlock: (t) => theme.fg("text", t),
+    codeBlockBorder: (t) => theme.fg("dim", t),
+    quote: (t) => theme.fg("dim", t),
+    quoteBorder: (t) => theme.fg("dim", t),
+    hr: (t) => theme.fg("dim", t),
+    listBullet: (t) => theme.fg("accent", t),
+    bold: (t) => theme.bold(t),
+    italic: (t) => t,
+    strikethrough: (t) => t,
+    underline: (t) => t,
+  };
+}
+
+export type { DetailModel, GraphModel };

package/src/pi/viewer/tui/surface/explore.ts

@@ -0,0 +1,204 @@
+/**
+ * surface/explore.ts — the Explore surface as a Component (weave-view-tui-v2 §6).
+ *
+ * Wraps the v1 tree view-model (`treeRows` + `reduce`/`ExplorerState`) so each
+ * Explore pane owns its own selection, expansion, filter, provenance cycle,
+ * and search sub-mode — independent of other panes. Cross-pane navigation
+ * (enter → open detail, f → open focus) is emitted as a `SurfaceEvent` that
+ * the workspace root resolves (e.g. into the nearest Detail pane).
+ */
+
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { decodeAction } from "../explorer";
+import {
+  graphRoots,
+  initialState,
+  reduce,
+  treeEmptyHint,
+  treeRows,
+  type Action,
+  type ExplorerState,
+} from "../model";
+import { chevron, kindStyle, provenanceStyle, SELECTION_MARKER, type ThemeSlot } from "../theme";
+import type { GraphModel } from "../../../../core/graph/model";
+import type { NoteSource } from "../../../../core/types";
+import { windowLines, type Surface, type SurfaceEvent, type SurfaceInit, type SurfaceRender } from "./base";
+
+/** The Explore surface's own state (wraps the v1 ExplorerState for the tree). */
+export interface ExploreSurfaceState {
+  selectedId: string | null;
+  expanded: Set<string>;
+  showInternals: boolean;
+  provFilter: NoteSource | null;
+  query: string;
+  searching: boolean;
+  scrollOffset: number;
+}
+
+export function initialExploreState(model: GraphModel): ExploreSurfaceState {
+  const s = initialState(graphRoots(model));
+  return {
+    selectedId: s.selectedId,
+    expanded: s.expanded,
+    showInternals: s.showInternals,
+    provFilter: s.provFilter,
+    query: s.query,
+    searching: s.searching,
+    scrollOffset: 0,
+  };
+}
+
+export class ExploreSurface implements Surface {
+  readonly kind = "explore" as const;
+  private readonly ctx;
+  private readonly onEvent: ((e: SurfaceEvent) => void) | undefined;
+  state: ExploreSurfaceState;
+  private focused = false;
+  /** Pane viewport height (rows); set by the workspace root. */
+  paneRows = 24;
+  private renderCache = new Map<string, string[]>();
+
+  constructor(init: SurfaceInit) {
+    this.ctx = init.context;
+    this.onEvent = init.onEvent;
+    this.state = initialExploreState(this.ctx.model);
+  }
+
+  title(): string {
+    return "Explore";
+  }
+
+  setFocused(focused: boolean): void {
+    this.focused = focused;
+  }
+
+  invalidate(): void {
+    this.renderCache.clear();
+  }
+
+  /** Navigate the tree with a key sequence (delegates to v1 decodeAction + reduce). */
+  handleInput(data: string): void {
+    // o opens the selected node in the external editor (parity with v1's
+    // WeaveExplorer and the Detail surface; the workspace root resolves the
+    // event into loaders.openNote/openFile).
+    if (data === "o" && !this.state.searching) {
+      if (this.state.selectedId) this.onEvent?.({ type: "openEditor", id: this.state.selectedId });
+      return;
+    }
+    const action = decodeAction(data, toExplorerState(this.state));
+    if (!action) return;
+    this.applyAction(action);
+  }
+
+  private applyAction(action: Action): void {
+    // Cross-pane navigation: enter → open detail; f → open focus.
+    if (action.type === "enter" && !this.state.searching) {
+      if (this.state.selectedId) this.onEvent?.({ type: "openDetail", id: this.state.selectedId });
+      return;
+    }
+    if (action.type === "focus" && !this.state.searching) {
+      if (this.state.selectedId) this.onEvent?.({ type: "focusNode", id: this.state.selectedId });
+      return;
+    }
+    const rows = this.renderRows(80);
+    const prev = toExplorerState(this.state);
+    const next = reduce(prev, action, { rows, window: Math.max(5, this.paneRows) });
+    this.state = fromExplorerState(next);
+  }
+
+  private renderRows(width: number): { id: string; target?: string }[] {
+    return this.renderSurface(width).rows;
+  }
+
+  render(width: number): string[] {
+    const key = `${width}:${this.state.scrollOffset}:${this.state.selectedId}:${this.state.query}:${this.state.provFilter ?? ""}:${this.state.showInternals}:${this.state.searching}`;
+    const cached = this.renderCache.get(key);
+    if (cached) return cached;
+    const out = this.renderSurface(width).lines.map((l) => truncateToWidth(l, width));
+    this.renderCache.set(key, out);
+    return out;
+  }
+
+  private renderSurface(width: number): SurfaceRender {
+    const t = this.ctx.theme;
+    const rows = treeRows(this.ctx.model, {
+      expanded: this.state.expanded,
+      showInternals: this.state.showInternals,
+      provFilter: this.state.provFilter,
+      query: this.state.query,
+      now: this.ctx.now(),
+    });
+    const hint = treeEmptyHint(this.ctx.model);
+    if (rows.length === 0 && hint) {
+      return { lines: [t.fg("dim", hint)], rows: [] };
+    }
+    const lines: { text: string; id: string }[] = rows.map((r) => {
+      const chev = chevron(r.expanded, r.hasKids);
+      const marker = this.rowMarker(r.kind, r.provenance);
+      const label = sanitize(r.label);
+      const meta = r.meta ? t.fg("dim", `  ${sanitize(r.meta)}`) : "";
+      const indent = "  ".repeat(r.depth);
+      const body = `${indent}${chev} ${marker}${label}`;
+      return { text: meta ? `${body}${meta}` : body, id: r.id };
+    });
+    const selId = this.state.selectedId;
+    const selLine = selId ? lines.findIndex((l) => l.id === selId) : -1;
+    const marker = (text: string) => `${SELECTION_MARKER} ${this.ctx.theme.bg("selectedBg", text)}`;
+    const out: string[] = windowLines(
+      lines.map((l) => l.text),
+      selLine,
+      this.state.scrollOffset,
+      Math.max(5, this.paneRows),
+      marker,
+    );
+    if (this.state.searching) {
+      const prompt = t.fg("accent", "/");
+      out.push(`${prompt}${sanitize(this.state.query)}`);
+    }
+    return { lines: out, rows: rows.map((r) => ({ id: r.id })) };
+  }
+
+  private rowMarker(kind: string, prov: NoteSource | null): string {
+    const ks = kindStyle(kind as never);
+    if (kind === "note") {
+      const ps = provenanceStyle(prov);
+      return ps.glyph ? `${ps.glyph} ` : "";
+    }
+    return `${this.ctx.theme.fg(ks.slot as ThemeSlot, `${ks.glyph} `)}`;
+  }
+}
+
+function sanitize(s: string): string {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b/g, "").replace(/\x9b/g, "").replace(/\x07/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+}
+
+function toExplorerState(s: ExploreSurfaceState): ExplorerState {
+  return {
+    surface: "tree",
+    searching: s.searching,
+    selectedId: s.selectedId,
+    focusId: null,
+    detailId: null,
+    expanded: s.expanded,
+    showInternals: s.showInternals,
+    provFilter: s.provFilter,
+    query: s.query,
+    helpOpen: false,
+    refreshing: false,
+    version: 0,
+    scrollOffset: s.scrollOffset,
+  };
+}
+
+function fromExplorerState(s: ExplorerState): ExploreSurfaceState {
+  return {
+    selectedId: s.selectedId,
+    expanded: s.expanded,
+    showInternals: s.showInternals,
+    provFilter: s.provFilter,
+    query: s.query,
+    searching: s.searching,
+    scrollOffset: s.scrollOffset,
+  };
+}