@groeponline/pi-wishcraft 1.16.0 → 1.23.0

package/src/welcome/overlay.ts

@@ -5,9 +5,14 @@ import { dim, renderWelcomeBox } from "./renderer.ts";
 import { fgOnly } from "../theme/colors.ts";
 import type { WelcomeData } from "./types.ts";
 import type { LoadedCounts, RecentSession } from "./types.ts";
-import { renderWelcomeArtWithReveal, BOOT_REVEAL_MS } from "./banner.ts";
+import { renderWelcomeArtWithReveal, BOOT_REVEAL_MS, revealElapsedForArt } from "./banner.ts";
 import { tr } from "../i18n/index.ts";
 import type { WelcomeArtTheme } from "./welcome-art.ts";
+import { quickLaunchItems } from "./quick-launch.ts";
+import type { WelcomeFocus, WelcomeSection } from "./types.ts";
+
+/** Tab order of the cockpit sections. */
+const SECTIONS: readonly WelcomeSection[] = ["news", "sessions", "shortcuts"];
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Welcome Components
@@ -21,6 +26,11 @@ export class WelcomeComponent implements Component {
   private data: WelcomeData;
   private countdown: number = 30;
   private mountedAt = 0;
+  private timerPaused = false;
+  private selectedWhatsNew: number | null = null;
+  private focus: WelcomeFocus = { section: "news", index: 0 };
+  /** True once a navigation key has been seen; keeps the default render calm. */
+  private focusEngaged = false;
 
   constructor(
     modelName: string,
@@ -55,6 +65,99 @@ export class WelcomeComponent implements Component {
     this.countdown = seconds;
   }
 
+  isTimerPaused(): boolean {
+    return this.timerPaused;
+  }
+
+  /**
+   * Step through the `What's new` bullets so truncated entries can be read in
+   * full. Interacting pauses the auto-dismiss countdown; only non-printable
+   * navigation keys call this, so typing a prompt still just dismisses.
+   */
+  moveSelection(delta: -1 | 1): void {
+    const count = this.data.whatsNew?.length ?? 0;
+    if (count === 0) return;
+    this.timerPaused = true;
+    this.selectedWhatsNew =
+      this.selectedWhatsNew === null
+        ? delta > 0
+          ? 0
+          : count - 1
+        : (this.selectedWhatsNew + delta + count) % count;
+  }
+
+  getSelectedWhatsNew(): number | null {
+    return this.selectedWhatsNew;
+  }
+
+  /** How many rows a section can highlight (0 = section is skipped). */
+  private rowsFor(section: WelcomeSection): number {
+    switch (section) {
+      case "news":
+        return this.data.whatsNew?.length ?? 0;
+      case "sessions":
+        return Math.min(3, this.data.recentSessions.length);
+      case "shortcuts":
+        return quickLaunchItems().length;
+      default:
+        return 0;
+    }
+  }
+
+  /**
+   * Move inside the focused section. The news section keeps its wrapping
+   * expanded-bullet behaviour; other sections clamp at the ends.
+   */
+  moveFocus(delta: -1 | 1): void {
+    if (this.focus.section === "news") {
+      this.moveSelection(delta);
+      if (this.selectedWhatsNew !== null) {
+        this.focusEngaged = true;
+        this.focus = { section: "news", index: this.selectedWhatsNew };
+      }
+      return;
+    }
+    const rows = this.rowsFor(this.focus.section);
+    if (rows === 0) return;
+    this.timerPaused = true;
+    this.focusEngaged = true;
+    this.focus = {
+      section: this.focus.section,
+      index: Math.max(0, Math.min(rows - 1, this.focus.index + delta)),
+    };
+  }
+
+  /** Tab / Shift+Tab: step to the next non-empty section. */
+  cycleSection(delta: -1 | 1): void {
+    const start = SECTIONS.indexOf(this.focus.section);
+    for (let step = 1; step <= SECTIONS.length; step++) {
+      const next = (((start + delta * step) % SECTIONS.length) + SECTIONS.length) % SECTIONS.length;
+      const section = SECTIONS[next];
+      if (this.rowsFor(section) === 0) continue;
+      this.timerPaused = true;
+      this.focusEngaged = true;
+      this.focus = {
+        section,
+        index: section === "news" ? (this.selectedWhatsNew ?? 0) : 0,
+      };
+      return;
+    }
+  }
+
+  getFocus(): WelcomeFocus | null {
+    return this.focusEngaged ? { ...this.focus } : null;
+  }
+
+  /**
+   * Enter on the focused row. Only meaningful once navigation paused the
+   * countdown, and only quick-launch rows carry text for the editor.
+   */
+  activate(): string | null {
+    if (!this.timerPaused || this.focus.section !== "shortcuts") return null;
+    const item = quickLaunchItems()[this.focus.index];
+    return item?.insert ?? null;
+  }
+
   setArt(art: WelcomeArtTheme, animate: boolean): void {
     this.data.art = art;
     this.data.animateArt = animate;
@@ -88,7 +191,9 @@ export class WelcomeComponent implements Component {
     );
 
     // Bottom line with countdown
-    const countdownText = ` ${tr("welcome.countdown", "Press any key to continue ({n}s)", { n: this.countdown })} `;
+    const countdownText = this.timerPaused
+      ? ` ${this.pausedHint()} `
+      : ` ${tr("welcome.countdown", "Press any key to continue ({n}s)", { n: this.countdown })} `;
     const countdownStyled = dim(countdownText);
     const bottomContentWidth = boxWidth - 2;
     const countdownVisLen = visibleWidth(countdownText);
@@ -100,20 +205,47 @@ export class WelcomeComponent implements Component {
       countdownStyled +
       dim(hChar.repeat(Math.max(0, rightPad)));
 
-    return renderWelcomeBox(this.data, termWidth, bottomLine, this.revealArt(termWidth));
+    const renderData: WelcomeData = {
+      ...this.data,
+      whatsNewSelected: this.selectedWhatsNew,
+      focus: this.getFocus() ?? undefined,
+    };
+    return renderWelcomeBox(renderData, termWidth, bottomLine, this.revealArt(termWidth));
+  }
+
+  /** One hint per section: what the arrows and Enter can do right now. */
+  private pausedHint(): string {
+    switch (this.focus.section) {
+      case "sessions":
+        return tr(
+          "welcome.pausedHint.sessions",
+          "↑/↓ browse crafts · tab switches section · any other key continues",
+        );
+      case "shortcuts":
+        return tr(
+          "welcome.pausedHint.shortcuts",
+          "↑/↓ choose · enter primes the prompt · tab switches section",
+        );
+      default:
+        return tr("welcome.pausedHint", "↑/↓ browse news · any other key continues");
+    }
   }
 
-  /** Left-column reveal frames while the boot window is open. */
+  /**
+   * Left-column art override. Animated lanterns keep their own frame source
+   * after the boot window so the flame never freezes on the first paint.
+   */
   private revealArt(termWidth: number): string[] | undefined {
     if (this.mountedAt === 0) return undefined;
     const now = Date.now();
     const elapsed = now - this.mountedAt;
-    if (elapsed >= BOOT_REVEAL_MS) return undefined;
+    const revealElapsed = revealElapsedForArt(elapsed, this.data.animateArt === true);
+    if (revealElapsed === undefined) return undefined;
     const frames = renderWelcomeArtWithReveal(
       this.data.art ?? "lantern",
       termWidth,
-      this.data.animateArt === true,
-      elapsed,
+      this.data.animateArt === true || revealElapsed < BOOT_REVEAL_MS,
+      revealElapsed,
       now,
     );
     const boxLayout = getBoxLayout(termWidth);

package/src/welcome/quick-launch.ts

@@ -0,0 +1,44 @@
+import { tr } from "../i18n/index.ts";
+
+/**
+ * Quick Launch rows. The welcome cockpit renders these and lets non-printable
+ * navigation move between them, so the list lives here once instead of being
+ * hardcoded inside the widget.
+ *
+ * `insert` is the text primed in the prompt editor when the row is activated.
+ * Rows without `insert` are genuine keybindings — the overlay cannot press a
+ * key for the operator, so activating them only closes the overlay.
+ */
+export interface QuickLaunchItem {
+  id: string;
+  keys: string;
+  label: string;
+  insert?: string;
+}
+
+export function quickLaunchItems(): QuickLaunchItem[] {
+  return [
+    {
+      id: "idea",
+      keys: "# <idea>",
+      label: tr("welcome.shortcuts.idea", "capture idea to queue"),
+      insert: "# ",
+    },
+    {
+      id: "deck",
+      keys: "alt+p",
+      label: tr("welcome.shortcuts.deck", "tactical powerline overlay"),
+    },
+    {
+      id: "bash",
+      keys: "!cmd",
+      label: tr("welcome.shortcuts.bash", "sticky bash session"),
+      insert: "! ",
+    },
+    {
+      id: "stash",
+      keys: "alt+s",
+      label: tr("welcome.shortcuts.stash", "stash/pop prompt draft"),
+    },
+  ];
+}

package/src/welcome/types.ts

@@ -12,6 +12,15 @@ export interface RecentSession {
   timeAgo: string;
 }
 
+/** Sections the welcome overlay lets the operator step through with Tab. */
+export type WelcomeSection = "news" | "sessions" | "shortcuts";
+
+export interface WelcomeFocus {
+  section: WelcomeSection;
+  /** Row index within that section. */
+  index: number;
+}
+
 export interface WelcomeData {
   modelName: string;
   providerName: string;
@@ -22,6 +31,10 @@ export interface WelcomeData {
   hasStash?: boolean;
   nextIdeaText?: string;
   whatsNew?: string[];
+  /** Index of the `whatsNew` bullet shown expanded (wrapped, not truncated). */
+  whatsNewSelected?: number | null;
+  /** Which section Tab is on and which row inside it is highlighted. */
+  focus?: WelcomeFocus;
   /**
    * Heading above `whatsNew`. Defaults to "What's new"; the first-run flow
    * swaps it for a short "Getting started" so a brand-new operator sees three

package/src/welcome/widgets/sessions-widget.ts

@@ -6,19 +6,23 @@ export const SessionsWidget: WelcomeWidget = {
   render(ctx: WidgetRenderContext): string[] {
     const { data, dim, bold, color } = ctx;
     const lines: string[] = [];
-    
+    const focused =
+      data.focus?.section === "sessions" ? data.focus.index : null;
+
     lines.push(` ${bold(color("accent", tr("welcome.sessions", "Recent Crafts")))}`);
 
     if (data.recentSessions.length === 0) {
       lines.push(` ${dim(tr("welcome.sessions.none", "No recent sessions"))}`);
-    } else {
-      for (const session of data.recentSessions.slice(0, 3)) {
-        lines.push(
-          ` ${dim("• ")}${color("path", session.name)}${dim(` (${session.timeAgo})`)}`
-        );
-      }
+      return lines;
     }
-    
+
+    data.recentSessions.slice(0, 3).forEach((session, index) => {
+      const marker = focused === index ? color("accent", "▸ ") : dim("• ");
+      lines.push(
+        ` ${marker}${color("path", session.name)}${dim(` (${session.timeAgo})`)}`
+      );
+    });
+
     return lines;
-  }
+  },
 };

package/src/welcome/widgets/shortcuts-widget.ts

@@ -1,17 +1,25 @@
 import { tr } from "../../i18n/index.ts";
 import type { WelcomeWidget, WidgetRenderContext } from "../types.ts";
+import { quickLaunchItems } from "../quick-launch.ts";
+
+const KEYS_WIDTH = 10;
 
 export const ShortcutsWidget: WelcomeWidget = {
   id: "shortcuts",
   render(ctx: WidgetRenderContext): string[] {
-    const { dim, bold, color } = ctx;
+    const { data, dim, bold, color } = ctx;
     const lines: string[] = [];
+    const focused =
+      data.focus?.section === "shortcuts" ? data.focus.index : null;
 
     lines.push(` ${bold(color("accent", tr("welcome.shortcuts", "Quick Launch / Tactical")))}`);
-    lines.push(` ${dim("# <idea>  ")} ${tr("welcome.shortcuts.idea", "capture idea to queue")}`);
-    lines.push(` ${dim("alt+p     ")} ${tr("welcome.shortcuts.deck", "tactical powerline overlay")}`);
-    lines.push(` ${dim("!cmd      ")} ${tr("welcome.shortcuts.bash", "sticky bash session")}`);
-    lines.push(` ${dim("alt+s     ")} ${tr("welcome.shortcuts.stash", "stash/pop prompt draft")}`);
+
+    quickLaunchItems().forEach((item, index) => {
+      const marker = focused === index ? color("accent", "▸") : " ";
+      const keys = item.keys.padEnd(KEYS_WIDTH);
+      const keysStyled = focused === index ? color("accent", keys) : dim(keys);
+      lines.push(`${marker}${keysStyled} ${item.label}`);
+    });
 
     return lines;
   },

package/src/welcome/widgets/whats-new-widget.ts

@@ -1,3 +1,4 @@
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { tr } from "../../i18n/index.ts";
 import type { WelcomeWidget, WidgetRenderContext } from "../types.ts";
 
@@ -16,9 +17,21 @@ export const WhatsNewWidget: WelcomeWidget = {
 
     const lines: string[] = [];
     lines.push(` ${bold(color("accent", title))}`);
-    for (const entry of entries) {
-      lines.push(` ${dim("• ")}${entry}`);
-    }
+    const selected =
+      data.focus?.section === "news"
+        ? data.focus.index
+        : (data.whatsNewSelected ?? null);
+    entries.forEach((entry, index) => {
+      if (selected !== index) {
+        lines.push(` ${dim("• ")}${entry}`);
+        return;
+      }
+      // Expanded: wrap instead of letting the column truncate the bullet.
+      const wrapped = wrapTextWithAnsi(entry, Math.max(12, ctx.width - 4));
+      wrapped.forEach((line, row) => {
+        lines.push(row === 0 ? ` ${color("accent", "▸ ")}${line}` : `   ${line}`);
+      });
+    });
     return lines;
   },
 };

package/src/working-vibes/frames.ts

@@ -1,25 +1,101 @@
 /** Pure working-indicator frames shared by status renderers and tests. */
 
-export type WorkingIndicatorStyle = "dots" | "pulse" | "bar" | "ascii";
-
-const FRAMES: Record<WorkingIndicatorStyle, readonly string[]> = {
+const FRAMES = {
   dots: ["·  ", "·· ", "···", " ··", "  ·", " ··"],
   pulse: ["○", "◌", "●", "◌"],
   bar: ["[=  ]", "[== ]", "[===]", "[ ==]", "[  =]"],
   ascii: ["-", "\\", "|", "/"],
+  lantern: ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█", "▇", "▆", "▅", "▄", "▃", "▂"],
+  braille: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+} as const satisfies Record<string, readonly string[]>;
+
+/** Styles with a fixed frame table of their own. */
+export type BuiltinIndicatorStyle = keyof typeof FRAMES;
+
+/**
+ * `motion` is not a frame table: it borrows the frames of whichever MotionDef
+ * the Motion Catalog is running (see `src/motion/catalog.ts`), falling back to
+ * the lantern ramp when no catalog frame is supplied.
+ */
+export type WorkingIndicatorStyle = BuiltinIndicatorStyle | "motion";
+
+/** Frames `motion` falls back to when the caller has no MotionDef. */
+export const MOTION_STYLE_FALLBACK: BuiltinIndicatorStyle = "lantern";
+
+const NATIVE_INTERVAL_MS: Record<BuiltinIndicatorStyle, number> = {
+  dots: 140,
+  pulse: 160,
+  bar: 120,
+  ascii: 100,
+  lantern: 90,
+  braille: 80,
 };
 
+/** Fixed frames for a style; `motion` resolves to the lantern ramp. */
+export function framesForStyle(
+  style: WorkingIndicatorStyle = "dots",
+): readonly string[] {
+  if (style === "motion") return FRAMES[MOTION_STYLE_FALLBACK];
+  return FRAMES[style] ?? FRAMES.dots;
+}
+
 export function workingIndicatorFrame(
   style: WorkingIndicatorStyle = "dots",
   tick = 0,
   motion: "full" | "reduced" | "functional" | "off" = "full",
 ): string {
-  const frames = FRAMES[style] ?? FRAMES.dots;
+  const frames = framesForStyle(style);
   if (motion === "off" || motion === "reduced") return frames[0]!;
   if (motion === "functional") return frames[tick % 2 === 0 ? 0 : Math.min(1, frames.length - 1)]!;
   return frames[Math.abs(Math.floor(tick)) % frames.length]!;
 }
 
 export function workingIndicatorStyles(): WorkingIndicatorStyle[] {
-  return Object.keys(FRAMES) as WorkingIndicatorStyle[];
+  return [...(Object.keys(FRAMES) as BuiltinIndicatorStyle[]), "motion"];
+}
+
+/** Every glyph any style can draw, for stripping spinner noise from captured text. */
+export function allWorkingIndicatorFrames(): string[] {
+  return Object.values(FRAMES).flatMap((frames) => [...frames]);
+}
+
+export interface NativeIndicatorSpec {
+  frames: string[];
+  intervalMs: number;
+}
+
+/** Interval of a built-in style, or of the supplied catalog motion. */
+function nativeInterval(
+  style: WorkingIndicatorStyle,
+  catalog?: NativeIndicatorSpec,
+): number {
+  if (style === "motion") {
+    return catalog?.intervalMs ?? NATIVE_INTERVAL_MS[MOTION_STYLE_FALLBACK];
+  }
+  return NATIVE_INTERVAL_MS[style] ?? NATIVE_INTERVAL_MS.dots;
+}
+
+/**
+ * Options for Pi's native `ctx.ui.setWorkingIndicator`. Pi owns the timer, so
+ * this is set once per run (not per tick): full motion animates every frame,
+ * functional motion alternates two frames slowly, reduced/off hold one frame.
+ */
+export function nativeWorkingIndicator(
+  style: WorkingIndicatorStyle = "dots",
+  motion: "full" | "reduced" | "functional" | "off" = "full",
+  ascii = false,
+  /** Frames + cadence of the active MotionDef, used by the `motion` style. */
+  catalog?: NativeIndicatorSpec,
+): NativeIndicatorSpec {
+  const key: WorkingIndicatorStyle = ascii ? "ascii" : style;
+  const source =
+    key === "motion" && catalog?.frames.length ? catalog.frames : framesForStyle(key);
+  const frames = source.length > 0 ? [...source] : ["·"];
+  if (motion === "off" || motion === "reduced") {
+    return { frames: [frames[0]!], intervalMs: 1000 };
+  }
+  if (motion === "functional") {
+    return { frames: [frames[0]!, frames[Math.min(1, frames.length - 1)]!], intervalMs: 500 };
+  }
+  return { frames, intervalMs: nativeInterval(key, catalog) };
 }

package/src/working-vibes/index.ts

@@ -20,7 +20,12 @@ export {
 
 export type { VibeMode } from "./storage.ts";
 export type { WorkingIndicatorStyle } from "./frames.ts";
-export { workingIndicatorFrame, workingIndicatorStyles } from "./frames.ts";
+export {
+  allWorkingIndicatorFrames,
+  nativeWorkingIndicator,
+  workingIndicatorFrame,
+  workingIndicatorStyles,
+} from "./frames.ts";
 
 export type {
   GenerateVibesResult,

package/src/working-vibes/native-indicator.ts

@@ -0,0 +1,71 @@
+// native-indicator.ts
+// Drives Pi's own working spinner (`ctx.ui.setWorkingIndicator`) from the
+// `wishcraft.workingIndicatorStyle` setting and the active motion policy.
+// Pi owns the animation timer; this only hands it frames once per run, so it
+// never competes with the MotionScheduler and idle sessions cost zero ticks.
+
+import { effectiveLevel, framesOf, getMotion, prefersAsciiGlyphs } from "../motion/index.ts";
+import type { MotionPolicy } from "../motion/index.ts";
+import { hasNerdFonts } from "../theme/icons.ts";
+import { nativeWorkingIndicator } from "./frames.ts";
+import type { NativeIndicatorSpec } from "./frames.ts";
+import { vibeState } from "./storage.ts";
+
+type NativeIndicatorUi = {
+  setWorkingIndicator?: (options?: { frames?: string[]; intervalMs?: number }) => void;
+  theme?: { fg?: (color: "accent", text: string) => string };
+};
+
+/**
+ * Catalog frames for the `motion` style. Resolved from the Motion Catalog so
+ * the native spinner runs the same glyphs as the status rail instead of a
+ * second, divergent animation.
+ */
+function motionSpec(motionId: string | undefined): NativeIndicatorSpec | undefined {
+  if (!motionId) return undefined;
+  const def = getMotion(motionId);
+  if (!def) return undefined;
+  const frames = framesOf(def);
+  if (frames.length === 0) return undefined;
+  return { frames: [...frames], intervalMs: def.generator?.intervalMs ?? 100 };
+}
+
+export function applyNativeWorkingIndicator(
+  ui: NativeIndicatorUi | undefined,
+  policy: MotionPolicy,
+  activeMotionId?: string,
+): void {
+  if (!ui?.setWorkingIndicator) return;
+  try {
+    const level = effectiveLevel(policy);
+    const ascii = prefersAsciiGlyphs(policy, hasNerdFonts());
+    const style = vibeState.config.workingIndicatorStyle;
+    const spec = nativeWorkingIndicator(
+      style,
+      level,
+      ascii,
+      style === "motion" && !ascii && level === "full"
+        ? motionSpec(activeMotionId)
+        : undefined,
+    );
+    // Custom frames render verbatim, so colour them like Pi's default spinner.
+    const paint = (frame: string): string => {
+      try {
+        return ui.theme?.fg?.("accent", frame) ?? frame;
+      } catch {
+        return frame;
+      }
+    };
+    ui.setWorkingIndicator({ frames: spec.frames.map(paint), intervalMs: spec.intervalMs });
+  } catch (error) {
+    console.debug("[working-vibes] native indicator failed:", error);
+  }
+}
+
+export function resetNativeWorkingIndicator(ui: NativeIndicatorUi | undefined): void {
+  try {
+    ui?.setWorkingIndicator?.();
+  } catch (error) {
+    console.debug("[working-vibes] native indicator reset failed:", error);
+  }
+}

package/src/working-vibes/storage.ts

@@ -9,7 +9,8 @@ import { join, dirname } from "node:path";
 import { getAgentPath } from "../paths/agent-dirs.ts";
 
 export type VibeMode = "generate" | "file";
-export type WorkingIndicatorStyle = "dots" | "pulse" | "bar" | "ascii";
+import { workingIndicatorStyles, type WorkingIndicatorStyle } from "./frames.ts";
+export type { WorkingIndicatorStyle };
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Constants
@@ -186,8 +187,9 @@ export function loadConfig(): VibeConfig {
     ? settings.wishcraft.workingIndicatorStyle
     : settings.workingIndicatorStyle;
   const workingIndicatorStyle: WorkingIndicatorStyle =
-    rawIndicator === "pulse" || rawIndicator === "bar" || rawIndicator === "ascii"
-      ? rawIndicator
+    typeof rawIndicator === "string" &&
+    (workingIndicatorStyles() as string[]).includes(rawIndicator)
+      ? (rawIndicator as WorkingIndicatorStyle)
       : "dots";
 
   const maxLength =