pi-weave 0.1.6 → 0.1.8

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

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+import type { ViewNote } from "../../../core/graph/current";
+
+/** The body loaders a BodyStore is bound to (bound to vault/cwd by run.ts). */
+export interface BodyLoaders {
+  loadNote: (slug: string) => Promise<ViewNote | null>;
+  loadOkf: (rel: string) => Promise<{ path: string; body: string } | null>;
+}
+
+export interface BodyStoreOptions {
+  loaders: BodyLoaders;
+  /** Invoked (no args) when an async load resolves so the owner can re-render. */
+  onChange?: () => void;
+}
+
+/**
+ * A cache+dedup keyed by node id. `get` never throws and never double-loads.
+ *
+ * - `null` body = the node exists but has no loadable body (or it loaded to
+ *   null); the pane renders nothing for it.
+ * - `undefined` = not yet requested (the pane shows a placeholder and asks the
+ *   store to load, mirroring v1's `bodyLinesFor`).
+ * - `isLoading(id)` = an in-flight request is outstanding (pane shows "loading").
+ */
+export class BodyStore {
+  private readonly loaders: BodyLoaders;
+  private readonly onChange: (() => void) | undefined;
+  private cache = new Map<string, string | null>();
+  private loading = new Set<string>();
+
+  constructor(opts: BodyStoreOptions) {
+    this.loaders = opts.loaders;
+    this.onChange = opts.onChange;
+  }
+
+  /** True when the id is mid-load. */
+  isLoading(id: string): boolean {
+    return this.loading.has(id);
+  }
+
+  /** Cached body for the id, or undefined when not yet requested. */
+  get(id: string): string | null | undefined {
+    return this.cache.get(id);
+  }
+
+  /** True once a body has been requested for the id (cached or failed). */
+  has(id: string): boolean {
+    return this.cache.has(id);
+  }
+
+  /**
+   * Kick off a load for `id` if not already requested/in-flight. Returns true
+   * when a load was started (so the caller can show a placeholder). The load
+   * uses `kind` (note/file) to pick the loader and `ref` (slug/rel path).
+   */
+  load(id: string, kind: "note" | "file", ref: string | undefined): boolean {
+    if (ref === undefined) return false;
+    if (this.cache.has(id) || this.loading.has(id)) return false;
+    this.loading.add(id);
+    if (kind === "note") {
+      void this.loaders
+        .loadNote(ref)
+        .then((note) => this.finish(id, note?.body ?? null))
+        .catch(() => this.finish(id, null));
+    } else {
+      void this.loaders
+        .loadOkf(ref)
+        .then((file) => this.finish(id, file?.body ?? null))
+        .catch(() => this.finish(id, null));
+    }
+    return true;
+  }
+
+  /** Drop all cached bodies and in-flight markers (the `r` refresh). */
+  clear(): void {
+    this.cache.clear();
+    this.loading.clear();
+  }
+
+  private finish(id: string, body: string | null): void {
+    this.cache.set(id, body);
+    this.loading.delete(id);
+    this.onChange?.();
+  }
+}

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

@@ -0,0 +1,154 @@
+/**
+ * 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 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). */
+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 JPEG of the logo). */
+export const LOGO_MIME = "image/jpeg";
+
+/**
+ * Bundled downscaled raster copy of `docs/pi-weave-logo.jpg` (32×32, ~1.3 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 =
+  "/9j/4AAQSkZJRgABAQAASABIAAD/4QDORXhpZgAATU0AKgAAAAgABgESAAMAAAABAAEAAAEaAAUAAAABAAAAVgEbAAUAAAABAAAAXgEoAAMAAAABAAIAAAExAAIAAAAVAAAAZodpAAQAAAABAAAAfAAAAAAAAABIAAAAAQAAAEgAAAABUGl4ZWxtYXRvciBQcm8gMi4xLjMAAAAEkAQAAgAAABQAAACyoAEAAwAAAAEAAQAAoAIABAAAAAEAAAAgoAMABAAAAAEAAAAgAAAAADIwMjY6MDg6MjIgMTk6NTY6MjIA/+0AZFBob3Rvc2hvcCAzLjAAOEJJTQQEAAAAAAAsHAFaAAMbJUccAgAAAgACHAI+AAgyMDI2MDgyMhwCPwALMTk1NjIyKzAwMDA4QklNBCUAAAAAABBB7D4+CxrdyaRylkhoEmIW/8AAEQgAIAAgAwEiAAIRAQMRAf/EAB8AAAEFAQEBAQEBAAAAAAAAAAABAgMEBQYHCAkKC//EALUQAAIBAwMCBAMFBQQEAAABfQECAwAEEQUSITFBBhNRYQcicRQygZGhCCNCscEVUtHwJDNicoIJChYXGBkaJSYnKCkqNDU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6g4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2drh4uPk5ebn6Onq8fLz9PX29/j5+v/EAB8BAAMBAQEBAQEBAQEAAAAAAAABAgMEBQYHCAkKC//EALURAAIBAgQEAwQHBQQEAAECdwABAgMRBAUhMQYSQVEHYXETIjKBCBRCkaGxwQkjM1LwFWJy0QoWJDThJfEXGBkaJicoKSo1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoKDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uLj5OXm5+jp6vLz9PX29/j5+v/bAEMAAgICAgICAwICAwUDAwMFBgUFBQUGCAYGBgYGCAoICAgICAgKCgoKCgoKCgwMDAwMDA4ODg4ODw8PDw8PDw8PD//bAEMBAgICBAQEBwQEBxALCQsQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEP/dAAQAAv/aAAwDAQACEQMRAD8A/E8Lk4rQsocXcD46SIf/AB4VDbpvYDua95+HfhtZtHn8QpBbXEdvKyM00iKW2RtKY4Vcjc+xGY45wAByQD62FwzqO17Luc0pWPC7yHNzM2Orsf1NUGXBxXu/xH8O/Y7Cy114baCG9m8oNBIrbCYlmCTKmdr7JEbHJwcH5gQPEZ02sR6UsThnTdr3XcIyuf/Q/GHT/JkcQzbQpO7Lccjtn3r0Dwv/AG1fMdH0e+e1e+kRTaEM4uZwTtBXhSRk7c8YOO/PlwJByK14dZvI7dbXcDEpJAKjv79ccetezQxfLHlZw1acn8L1PTPE+nanZpb2Wr6i99JBkw2gV4xbzSk8KuGA3BckgYKjGQMVzPjG70+ygh8LaXFZSQWshuGurdd8kkkqDKGY5YqgABUfKH3ECsW48U6vcWs1k02IbjbvUKBnb0AOMgdsA4xxXOE55oxGJ5lZDjRVk5atH//Z";
+
+/** 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(
+  theme: { fg: (slot: ThemeSlot, text: string) => string },
+): Component | null {
+  if (getCapabilities().images === "kitty") return logoImage(LOGO_B64, LOGO_MIME, theme);
+  return null;
+}

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

@@ -13,6 +13,7 @@
  */
 
 import { matchesKey, parseKey, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { BodyStore } from "./bodyStore";
 
 import type { GraphModel, GraphNode, NodeKind } from "../../../core/graph/model";
 import type { NoteSource } from "../../../core/types";
@@ -20,6 +21,7 @@ import type { ViewNote } from "../../../core/graph/current";
 import {
   detailModel,
   focusModel,
+  formatTreeMeta,
   graphRoots,
   healthModel,
   initialState,
@@ -141,10 +143,8 @@ export class WeaveExplorer implements Component {
   private readonly nowFn: () => number;
 
   state: ExplorerState;
-  /** Cached note/okf bodies keyed by node id; null = not yet loaded. */
-  private bodyCache = new Map<string, string | null>();
-  /** In-flight body loads, keyed by node id. */
-  private bodyLoading = new Set<string>();
+  /** Shared note/okf body cache (dedup by node id, bust-on-refresh). */
+  private readonly bodies: BodyStore;
   /** Render cache keyed by `${width}:${version}`. */
   private renderCache = new Map<string, string[]>();
   wantsKeyRelease = false;
@@ -157,14 +157,21 @@ export class WeaveExplorer implements Component {
     this.done = opts.done;
     this.rows = opts.rows ?? 24;
     this.nowFn = opts.now ?? Date.now;
+    this.bodies = new BodyStore({
+      loaders: opts.loaders,
+      onChange: () => {
+        this.state = { ...this.state, version: this.state.version + 1 };
+        this.invalidate();
+        this.tui.requestRender();
+      },
+    });
     this.state = initialState(graphRoots(this.model));
   }
 
   /** Replace the graph (used by the `r` refresh). Preserves selection by id. */
   setModel(model: GraphModel): void {
     this.model = model;
-    this.bodyCache.clear();
-    this.bodyLoading.clear();
+    this.bodies.clear();
     this.state = reduce(this.state, { type: "refreshDone" });
     // Re-resolve selection: keep id if still present, else first root.
     if (this.state.selectedId && !this.nodeExists(this.state.selectedId)) {
@@ -353,8 +360,8 @@ export class WeaveExplorer implements Component {
       showInternals: this.state.showInternals,
       provFilter: this.state.provFilter,
       query: this.state.query,
-      now: this.nowFn(),
     });
+    const now = this.nowFn();
     const hint = treeEmptyHint(this.model);
     if (rows.length === 0 && hint) {
       return { lines: [{ text: t.fg("dim", hint) }], rows: [] };
@@ -363,7 +370,8 @@ export class WeaveExplorer implements Component {
       const chev = chevron(r.expanded, r.hasKids);
       const marker = this.rowMarker(r.kind, r.provenance);
       const label = sanitizeTerminalText(r.label);
-      const meta = r.meta ? t.fg("dim", `  ${sanitizeTerminalText(r.meta)}`) : "";
+      const metaText = formatTreeMeta(r.meta, now);
+      const meta = metaText ? t.fg("dim", `  ${sanitizeTerminalText(metaText)}`) : "";
       const indent = "  ".repeat(r.depth);
       const body = `${indent}${chev} ${marker}${label}`;
       const text = meta ? `${body}${meta}` : body;
@@ -504,31 +512,12 @@ export class WeaveExplorer implements Component {
   }
 
   private maybeLoadBody(id: string): void {
-    if (this.bodyCache.has(id) || this.bodyLoading.has(id)) return;
     const node = this.model.nodes.find((n) => n.id === id);
     if (!node) return;
     if (node.kind === "note") {
-      const slug = node.detail.slug;
-      if (!slug) return;
-      this.bodyLoading.add(id);
-      void this.loaders.loadNote(slug).then((note) => {
-        this.bodyCache.set(id, note?.body ?? null);
-        this.bodyLoading.delete(id);
-        this.state = { ...this.state, version: this.state.version + 1 };
-        this.invalidate();
-        this.tui.requestRender();
-      });
+      this.bodies.load(id, "note", node.detail.slug);
     } else if (node.kind === "file") {
-      const rel = node.detail.path;
-      if (!rel) return;
-      this.bodyLoading.add(id);
-      void this.loaders.loadOkf(rel).then((file) => {
-        this.bodyCache.set(id, file?.body ?? null);
-        this.bodyLoading.delete(id);
-        this.state = { ...this.state, version: this.state.version + 1 };
-        this.invalidate();
-        this.tui.requestRender();
-      });
+      this.bodies.load(id, "file", node.detail.path);
     }
   }
 
@@ -539,8 +528,8 @@ export class WeaveExplorer implements Component {
     // never completes (maybeLoadBody skips non-note/file kinds).
     const node = this.model.nodes.find((n) => n.id === id);
     if (!node || (node.kind !== "note" && node.kind !== "file")) return [];
-    if (this.bodyLoading.has(id)) return [this.theme.fg("dim", "(loading…)")];
-    const body = this.bodyCache.get(id);
+    if (this.bodies.isLoading(id)) return [this.theme.fg("dim", "(loading…)")];
+    const body = this.bodies.get(id);
     if (body === undefined) {
       // not yet requested — trigger a load (render is sync, so show placeholder)
       queueMicrotask(() => this.maybeLoadBody(id));