pi-weave 0.1.12 → 0.1.13

package/src/core/view/detail.ts

@@ -33,7 +33,7 @@ export interface DetailModel {
   backlinks: DetailLinkRow[];
 }
 
-/** Ordered meta keys shown in the detail header (weave-view-tui-design §5.2). */
+/** Ordered meta keys shown in the detail header. */
 const META_ORDER = [
   "path",
   "slug",

package/src/core/view/health.ts

@@ -1,6 +1,6 @@
 /**
  * healthModel — staleness + link health, derived exclusively from the
- * GraphModel (weave-view-tui-design §5.4 / weave-workspace §3).
+ * GraphModel (weave-workspace §3).
  *
  * Zero new server/core fields: everything here is a projection of nodes,
  * edges, and `model.staleness`.

package/src/core/view/tree.ts

@@ -269,7 +269,7 @@ export function treeRows(model: GraphModel, state: TreeState): TreeRow[] {
   return rows;
 }
 
-/** Empty-state hint for the tree surface (weave-view-tui-design §5.1). */
+/** Empty-state hint for the tree surface. */
 export function treeEmptyHint(model: GraphModel): string | null {
   const vault = model.nodes.find((n) => n.kind === "vault");
   if (!vault) return null;

package/src/pi/index.ts

@@ -11,7 +11,6 @@ import {
 } from "../core";
 import { registerNoteTool } from "./tools/noteTool";
 import { registerRepoTool } from "./tools/repoTool";
-import { formatSessionScanResult, scanPiSessions } from "./sessionScan";
 import { deepScanRepository, formatDeepScanResult } from "./summarize";
 import { runWeaveViewTui } from "./viewer/tui/run";
 import { WebWorkspaceController } from "./viewer/web/run";
@@ -79,7 +78,7 @@ export default function piWeave(pi: ExtensionAPI): void {
     } catch {
       // ignore
     }
-    const indicator = (isActive || inFlightDeepScans.size > 0 || inFlightSessionScans.size > 0)
+    const indicator = (isActive || inFlightDeepScans.size > 0)
       ? (theme?.fg ? theme.fg("accent", "●") : "●")
       : (theme?.fg ? theme.fg("dim", "○") : "○");
     // With no base text the marker stands alone (`○ web:51234`) rather than
@@ -158,20 +157,9 @@ export default function piWeave(pi: ExtensionAPI): void {
 
   pi.registerCommand("weave-scan", {
     description:
-      "Build or refresh the repository knowledge index (.okf); 'deep' also summarizes files with the session model; 'sessions' summarizes pi session history into the vault",
+      "Build or refresh the repository knowledge index (.okf); 'deep' also summarizes files with the session model",
     handler: async (args, ctx) => {
       const mode = args.trim().toLowerCase();
-      if (mode === "sessions") {
-        // Repo-agnostic by definition: no git requirement, works from any cwd.
-        if (inFlightSessionScans.size > 0) {
-          ctx.ui.notify("pi-weave: a session scan is already running — run /weave-scan-cancel to stop it.", "warning");
-          return;
-        }
-        const status = await getWorkspaceStatus(ctx.cwd);
-        startSessionScan(ctx, status, updateStatus);
-        return; // the background scan owns the status line until it settles
-      }
-
       const root = await findGitRoot(ctx.cwd);
       if (!root) {
         ctx.ui.notify("pi-weave: not inside a git repository.", "warning");
@@ -203,17 +191,15 @@ export default function piWeave(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("weave-scan-cancel", {
-    description: "Cancel an in-flight /weave-scan deep or sessions run",
+    description: "Cancel an in-flight /weave-scan deep run",
     handler: async (_args, ctx) => {
       const root = await findGitRoot(ctx.cwd);
       const deep = root ? inFlightDeepScans.get(root) : undefined;
-      const sessions = inFlightSessionScans.get(SESSIONS_SCAN_KEY);
-      if (!deep && !sessions) {
+      if (!deep) {
         ctx.ui.notify("pi-weave: no deep scan is currently running.", "info");
         return;
       }
       deep?.controller.abort();
-      sessions?.controller.abort();
       ctx.ui.notify("pi-weave: scan cancellation requested.", "info");
     },
   });
@@ -278,24 +264,12 @@ interface InFlightDeepScan {
 /** In-flight deep scans keyed by repo root — the /weave-scan-cancel target. */
 const inFlightDeepScans = new Map<string, InFlightDeepScan>();
 
-/**
- * The in-flight session scan, under a reserved key that cannot collide with
- * a git root (absolute paths always start with `/`).
- */
-export const SESSIONS_SCAN_KEY = "(pi-weave:sessions)";
-const inFlightSessionScans = new Map<string, InFlightDeepScan>();
-
 /** Test seam: resolve when the in-flight deep scan for `root` settles. */
 export async function deepScanDone(root: string): Promise<void | undefined> {
   const canonical = await findGitRoot(root).catch(() => null);
   return inFlightDeepScans.get(canonical ?? root)?.done;
 }
 
-/** Test seam: resolve when the background session scan settles. */
-export async function sessionScanDone(): Promise<void | undefined> {
-  return inFlightSessionScans.get(SESSIONS_SCAN_KEY)?.done;
-}
-
 interface SettledMessage {
   text: string;
   level: "info" | "warning";
@@ -306,9 +280,7 @@ interface SettledMessage {
  * off the command handler so the user keeps control of the session (a
  * blocking command can't be cancelled in the TUI — Esc only aborts
  * streaming/bash). Progress is pushed to the status line; the completion
- * message is notified; the settled status is restored when the scan settles
- * (`settledStatus` lets a scan recompute it — a session scan grows the vault,
- * so its restored line should say so).
+ * message is notified; the settled status is restored when the scan settles.
  */
 function startBackgroundScan(
   store: Map<string, InFlightDeepScan>,
@@ -317,7 +289,6 @@ function startBackgroundScan(
   baseStatus: WorkspaceStatus,
   updateStatus: (ctx?: ExtensionContext | ExtensionCommandContext, text?: string) => void,
   run: (signal: AbortSignal) => Promise<SettledMessage | null>,
-  settledStatus: (() => Promise<WorkspaceStatus>) | undefined = undefined,
 ): void {
   const controller = new AbortController();
   let doneResolve: () => void;
@@ -335,11 +306,8 @@ function startBackgroundScan(
     } finally {
       // Restore the settled status before removing the map entry, so a caller
       // awaiting the done seam observes the settled status line.
-      const final = settledStatus
-        ? await settledStatus().catch(() => baseStatus)
-        : baseStatus;
       store.delete(key);
-      updateStatus(ctx, formatStatusLine(final));
+      updateStatus(ctx, formatStatusLine(baseStatus));
       doneResolve!();
     }
   })();
@@ -379,50 +347,3 @@ function startDeepScan(
     return null;
   });
 }
-
-/**
- * Kick off a session scan (docs/session-scan.md) in the background — same
- * lifecycle as deep scans; keyed globally, not per repo.
- */
-function startSessionScan(
-  ctx: ExtensionCommandContext,
-  baseStatus: WorkspaceStatus,
-  updateStatus: (ctx?: ExtensionContext | ExtensionCommandContext, text?: string) => void,
-): void {
-  startBackgroundScan(
-    inFlightSessionScans,
-    SESSIONS_SCAN_KEY,
-    ctx,
-    baseStatus,
-    updateStatus,
-    async (signal) => {
-      updateStatus(ctx, "🕸️ session scan: starting…");
-      const outcome = await scanPiSessions(ctx, {
-        onProgress: ({ current, total, path }) => {
-          const pct = total > 0 ? Math.round((current / total) * 100) : 100;
-          updateStatus(ctx, `🕸️ session scan: ${current}/${total} (${pct}%) — ${path}`);
-        },
-        signal,
-      });
-      if (signal.aborted) {
-        return { text: "pi-weave: session scan cancelled.", level: "warning" };
-      }
-      if (outcome.kind === "no-model") {
-        return {
-          text: "pi-weave: session scan needs an active session model — none configured.",
-          level: "warning",
-        };
-      }
-      const result = outcome.result;
-      if (result.discovered === 0) {
-        return { text: "pi-weave: session scan complete — no pi sessions found.", level: "info" };
-      }
-      return { text: `pi-weave: session scan complete — ${formatSessionScanResult(result)}`, level: "info" };
-    },
-    // Unlike the deep scan (whose settled status is precomputed to avoid git
-    // contention), the session scan writes vault notes and takes no git lock:
-    // recompute the workspace status so the settled line counts the notes it
-    // just wrote.
-    () => getWorkspaceStatus(ctx.cwd),
-  );
-}

package/src/pi/summarize.ts

@@ -45,8 +45,8 @@ const MAX_OUTPUT_TOKENS = 220;
 const REQUEST_TIMEOUT_MS = 30_000;
 
 /**
- * The shared session-model wiring behind every pi-weave summarizer (deep
- * scan, session scan): resolve the session's already-configured model — no
+ * The shared model wiring behind the deep scan: resolve the session's
+ * already-configured model — no
  * extra keys or providers (docs/scan-modes.md) — drive completion through
  * `ctx.modelRegistry`, which owns auth, and reject empty outputs so a
  * degraded model cannot silently blank a note.

package/src/pi/viewer/tui/bodyStore.ts

@@ -1,15 +1,12 @@
 /**
  * BodyStore — shared note/.okf body cache (weave-view-tui-v2 §6, §9.1).
  *
- * The v1 WeaveExplorer cached bodies in private maps. v2 lifts that cache into
- * a per-session store so every pane (e.g. two Detail panes reading the same
- * note) shares one fetch per node id. Behavior is identical to v1's
- * per-explorer cache: a body load is kicked off once per id, in-flight loads
- * are deduped, and a refresh busts the cache so the next read re-fetches.
+ * Every pane (e.g. two Detail panes reading the same note) shares one fetch
+ * per node id. A body load is kicked off once per id, in-flight loads are
+ * deduped, and a refresh busts the cache so the next read re-fetches.
  *
  * The store is harness-free (takes injected loaders + an optional
- * onChange callback), so it is unit-tested with fake loaders exactly like
- * v1's body tests.
+ * onChange callback).
  */
 
 import type { ViewNote } from "../../../core/graph/current";

package/src/pi/viewer/tui/branding.ts

@@ -1,155 +1,14 @@
-/**
- * branding.ts — weave-view TUI logo & wordmark tiers (weave-view-tui-v2 §5).
- *
- * Renders the brand as a small, casual in-bar mark. Three tiers, auto-selected
- * once per session from terminal capability and cached:
- *
- *   1. "kitty"   — the real raster logo via pi-tui's `Image` component (a small
- *                  ~2×2-cell favicon). The raw JPG is bundled and base64'd once.
- *   2. "glyph"   — a tiny curated Unicode glyph derived from the logo silhouette.
- *   3. "plain"   — `🕸️` + wordmark, forced by PI_WEAVE_TUI_PLAIN.
- *
- * The line-art/unicode constants contain no ESC by construction (decision 1:
- * the representation fallback is a curated constant, never generated at runtime).
- */
-
-import { detectCapabilities, getCapabilities, Image, type Component } from "@earendil-works/pi-tui";
+import { visibleWidth } from "@earendil-works/pi-tui";
 import type { ThemeSlot } from "./theme";
 
-/** Logo render tier. */
-export type LogoTier = "kitty" | "glyph" | "plain";
-
-/** A tiny Unicode mark derived from the logo silhouette (decision 1 fallback). */
+/** The TUI uses one terminal-safe mark. */
 export const MARK_GLYPH = "◈";
-/** Absolute last-resort mark (also the forced plain tier). */
-export const PLAIN_MARK = "🕸️";
-/** The wordmark shown after the mark. */
 export const WORDMARK = "weave view";
 
-/** Env var that forces the plain tier. */
-export const PLAIN_ENV = "PI_WEAVE_TUI_PLAIN";
-
-/** MIME of the bundled raster logo asset (downscaled transparent PNG of the logo). */
-export const LOGO_MIME = "image/png";
-
-/**
- * Bundled downscaled raster copy of `docs/pi-weave-logo.png` (the transparent-
- * background spider, 32×32, ~1.7 KB). Decision 1 (§15): ship a small raster copy
- * and embed it via pi-tui's `Image`
- * (Kitty graphics) as a small ~2×2-cell favicon in the header strip — a casual
- * in-bar mark, not a hero splash. Stored base64 so the render path needs no
- * fs/path resolution and the asset is trivially unit-testable.
- */
-export const LOGO_B64 =
-  "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";
-
-/** Terminal capability surface branding probes. */
-export interface BrandCapabilities {
-  /** Kitty graphics protocol available. */
-  kitty: boolean;
-}
-
-/** Pure tier selection; exported for direct unit testing. */
-export function logoTierFor(caps: BrandCapabilities, forcePlain: boolean): LogoTier {
-  if (forcePlain) return "plain";
-  if (caps.kitty) return "kitty";
-  return "glyph";
-}
-
-/**
- * Resolve the environment (PI_WEAVE_TUI_PLAIN) to a plain flag. Exported as a
- * small pure function so the env read is testable in isolation.
- */
-export function plainEnv(env: Record<string, string | undefined> = process.env): boolean {
-  const v = env[PLAIN_ENV];
-  return v !== undefined && v !== "" && v !== "0";
-}
-
-// Session-level probe cache (probed once, reused for the whole session §5.1).
-let cachedTier: LogoTier | null = null;
-let cachedCaps: BrandCapabilities | null = null;
-
-/**
- * Return the session-cached capabilities (probed once). The probe runs at most
- * once per process; subsequent calls reuse the cache. `getCaps` is injectable
- * for tests (defaults to a live kitty probe). Never throws.
- */
-export function probeGraphics(getCaps: () => BrandCapabilities): BrandCapabilities {
-  if (cachedCaps) return cachedCaps;
-  try {
-    cachedCaps = getCaps();
-  } catch {
-    cachedCaps = { kitty: false };
-  }
-  return cachedCaps;
-}
-
-/**
- * Resolve the session logo tier, probing terminal capability once and caching
- * for the process. `env` is injectable for tests.
- */
-export function logoTier(env: Record<string, string | undefined> = process.env): LogoTier {
-  if (cachedTier) return cachedTier;
-  const caps = probeGraphics(() => getBrandCapabilities());
-  cachedTier = logoTierFor(caps, plainEnv(env));
-  return cachedTier;
-}
-
-/** Reset the session probe cache (test seam). */
-export function resetBrandCache(): void {
-  cachedTier = null;
-  cachedCaps = null;
-}
-
-/** A live kitty-capability probe backed by pi-tui's terminal capability query. */
-export function getBrandCapabilities(): BrandCapabilities {
-  return { kitty: detectCapabilities().images === "kitty" };
-}
-
-/**
- * The mark rendered as a single header line (≤ width). This is the string the
- * header strip / empty state embed. For the kitty tier the mark glyph is used
- * in the text strip; the real raster is emitted via `logoImage()` when a kitty
- * surface is available.
- */
-export function renderMark(tier: LogoTier, theme: { fg: (slot: ThemeSlot, text: string) => string }, width: number): string {
-  let mark: string;
-  if (tier === "plain") {
-    mark = theme.fg("muted", PLAIN_MARK);
-  } else {
-    // kitty and glyph tiers share the curated glyph in the text strip.
-    mark = theme.fg("accent", MARK_GLYPH);
-  }
-  return mark.slice(0, Math.max(1, width));
-}
-
-/**
- * A small pi-tui `Image` component for the kitty tier (decision 1 favicon).
- * Takes the base64 JPG + mime; renders at ~2×2 cells. Returns a component that
- * emits the Kitty sequence when the terminal supports it, else a text fallback.
- */
-export function logoImage(
-  base64Data: string,
-  mimeType: string,
-  theme: { fg: (slot: ThemeSlot, text: string) => string },
-): Component {
-  return new Image(base64Data, mimeType, { fallbackColor: (t) => theme.fg("text", t) }, {
-    maxWidthCells: 2,
-    maxHeightCells: 2,
-  });
-}
-
-/**
- * Build the bundled kitty raster logo `Image` (decision 1 favicon). Returns a
- * component only when the terminal supports the Kitty graphics protocol;
- * `null` otherwise so the caller keeps the one-line glyph header. The render
- * path splices this component's lines onto their own row(s) — never inlined
- * into a styled text line. The base64 asset is a compile-time constant, so the
- * only fallback needed is the Kitty gate (no fs/path reads at runtime).
- */
-export function bundledLogoImage(
+export function renderMark(
   theme: { fg: (slot: ThemeSlot, text: string) => string },
-): Component | null {
-  if (getCapabilities().images === "kitty") return logoImage(LOGO_B64, LOGO_MIME, theme);
-  return null;
+  width: number,
+): string {
+  const mark = theme.fg("accent", MARK_GLYPH);
+  return visibleWidth(mark) <= width ? mark : "";
 }

package/src/pi/viewer/tui/run.ts

@@ -1,9 +1,9 @@
 /**
- * runWeaveViewTui — wires the WeaveExplorer into a pi session
+ * runWeaveViewTui — wires the workspace explorer into a pi session
  * (weave-view-tui-design §2, §4.1, §3.2).
  *
  * Guards (interactive terminal only), builds the graph from disk in the
- * handler, then hands a ready WeaveExplorer to `ctx.ui.custom` so the
+ * handler, then hands a ready workspace explorer to `ctx.ui.custom` so the
  * explorer owns input for its whole lifetime. After `done(null)` resolves,
  * the workspace status line is refreshed. Dependencies are injected so the
  * component never touches a real terminal directly.
@@ -15,12 +15,10 @@ import {
   readNoteForView,
   readOkfFileForView,
   resolveVaultRoot,
-  type GraphModel,
 } from "../../../core";
 import { openNoteInEditor } from "./openNote";
-import { bundledLogoImage, logoTier, renderMark } from "./branding";
 import { WeaveWorkspace } from "./workspaceRoot";
-import type { WeaveLoaders, WeaveTheme, WeaveTui } from "./explorer";
+import type { WeaveLoaders, WeaveTheme, WeaveTui } from "./surface/base";
 import { getWorkspaceStatus, formatStatusLine } from "../../../core";
 
 /** Open the in-terminal knowledge explorer. Returns when the explorer closes. */
@@ -47,11 +45,6 @@ export async function runWeaveViewTui(ctx: ExtensionCommandContext): Promise<voi
 
   await ctx.ui.custom(
     (tui, theme, _keybindings, done) => {
-      const tier = logoTier();
-      const logo = renderMark(tier, theme as unknown as WeaveTheme, 20);
-      // bundledLogoImage gates on Kitty support itself and returns null (glyph
-      // header) when unavailable.
-      const logoImage = bundledLogoImage(theme as unknown as WeaveTheme);
       const explorer = new WeaveWorkspace({
         model,
         theme: theme as unknown as WeaveTheme,
@@ -59,8 +52,6 @@ export async function runWeaveViewTui(ctx: ExtensionCommandContext): Promise<voi
         loaders,
         done,
         rows: tui.terminal.rows,
-        logo,
-        logoImage,
       });
       return explorer;
     },
@@ -78,8 +69,3 @@ export async function runWeaveViewTui(ctx: ExtensionCommandContext): Promise<voi
   const indicator = theme?.fg ? theme.fg("dim", "○") : "○";
   ctx.ui.setStatus("weave", `${indicator} ${formatStatusLine(status)}`);
 }
-
-/** Test seam: build the model the explorer opens with, without a terminal. */
-export async function buildTuiModel(cwd: string, vaultRoot: string = resolveVaultRoot()): Promise<GraphModel> {
-  return buildCurrentGraph(cwd, vaultRoot);
-}

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

@@ -16,10 +16,31 @@
 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 { ViewNote } from "../../../../core/graph/current";
 import type { SurfaceKind } from "../workspace";
 import type { ThemeSlot } from "../theme";
 
+/** Minimal theme surface shared by the workspace root and its surfaces. */
+export interface WeaveTheme {
+  fg(slot: ThemeSlot, text: string): string;
+  bg(slot: "selectedBg", text: string): string;
+  bold(text: string): string;
+}
+
+/** Minimal TUI surface shared by the workspace root and its adapter. */
+export interface WeaveTui {
+  requestRender(force?: boolean): void;
+  terminal: { rows: number; columns: number };
+}
+
+/** Injected readers/actions bound to the vault and repository by run.ts. */
+export interface WeaveLoaders {
+  loadNote: (slug: string) => Promise<ViewNote | null>;
+  loadOkf: (rel: string) => Promise<{ path: string; body: string } | null>;
+  openNote: (slug: string) => Promise<boolean>;
+  rebuild: () => Promise<GraphModel>;
+}
+
 /** A cross-pane navigation request a surface emits (resolved by the root). */
 export type SurfaceEvent =
   | { type: "openDetail"; id: string }
@@ -151,7 +172,7 @@ export class Pane implements Component {
     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 —
+    // border and PADS to fill its allocated height so the multi-pane view 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);
@@ -164,7 +185,7 @@ export class Pane implements Component {
     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.
+    // in a multi-pane render the same height.
     const bodyRows = Math.max(0, this.rows - 3);
     const out = [top, titleLine];
     for (let i = 0; i < bodyRows; i++) {

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

@@ -8,8 +8,7 @@
  * the workspace root resolves (e.g. into the nearest Detail pane).
  */
 
-import { truncateToWidth } from "@earendil-works/pi-tui";
-import { decodeAction } from "../explorer";
+import { matchesKey, parseKey, truncateToWidth } from "@earendil-works/pi-tui";
 import {
   formatTreeMeta,
   graphRoots,
@@ -25,6 +24,43 @@ 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";
 
+/** Decode terminal input into the Explore surface's state-machine actions. */
+export function decodeAction(data: string, state: Pick<ExplorerState, "searching">): Action | null {
+  if (matchesKey(data, "up")) return { type: "up" };
+  if (matchesKey(data, "down")) return { type: "down" };
+  if (matchesKey(data, "left")) return { type: "left" };
+  if (matchesKey(data, "right")) return { type: "right" };
+  if (matchesKey(data, "enter")) return { type: "enter" };
+  if (matchesKey(data, "escape")) return { type: "esc" };
+  if (matchesKey(data, "pageUp")) return { type: "pageUp" };
+  if (matchesKey(data, "pageDown")) return { type: "pageDown" };
+  if (matchesKey(data, "home")) return { type: "home" };
+  if (matchesKey(data, "end")) return { type: "end" };
+  if (state.searching) {
+    if (matchesKey(data, "backspace")) return { type: "searchBackspace" };
+    const ch = parseKey(data);
+    if (ch === undefined) return null;
+    if (ch === "space") return { type: "searchChar", ch: " " };
+    if (ch.length === 1) return { type: "searchChar", ch };
+    return null;
+  }
+  if (data === "k") return { type: "up" };
+  if (data === "j") return { type: "down" };
+  if (data === "h") return { type: "left" };
+  if (data === "l") return { type: "right" };
+  if (data === "/") return { type: "searchStart" };
+  if (data === "p") return { type: "cycleProvenance" };
+  if (data === "i") return { type: "toggleInternals" };
+  if (data === "f") return { type: "focus" };
+  if (data === "g") return { type: "focusExit" };
+  if (data === "1") return { type: "surfaceTree" };
+  if (data === "2") return { type: "surfaceHealth" };
+  if (data === "r") return { type: "refresh" };
+  if (data === "?") return { type: "toggleHelp" };
+  if (data === "q") return { type: "quit" };
+  return null;
+}
+
 /** The Explore surface's own state (wraps the v1 ExplorerState for the tree). */
 export interface ExploreSurfaceState {
   selectedId: string | null;
@@ -77,11 +113,10 @@ export class ExploreSurface implements Surface {
     this.renderCache.clear();
   }
 
-  /** Navigate the tree with a key sequence (delegates to v1 decodeAction + reduce). */
+  /** Navigate the tree with a key sequence. */
   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).
+    // o opens the selected node in the external editor; 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;