@bismawy/pi-vision-watcher 1.0.15 โ†’ 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,13 +3,14 @@
3
3
  * describes images during vision handoff.
4
4
  *
5
5
  * Uses the same patterns as pi's built-in selectors and pi-hide-providers:
6
- * - Lists connected (authenticated) models, vision-capable ones first (๐Ÿ‘€ badge)
6
+ * - Lists connected (authenticated) models, vision-capable ones first (โœฆ badge)
7
7
  * - A leading "None" row clears the configured vision model
8
8
  * - Space selects the highlighted model as the primary describer (toggle)
9
- * - Ctrl+Alt+F toggles the highlighted model in/out of the failover chain (max 3)
10
- * - Ctrl+T walks the thinking ladder, Ctrl+A toggles async paste handoff
9
+ * - Tab toggles the highlighted model in/out of the failover chain (max 3)
10
+ * - Ctrl+Shift+R clears the failover chain, Shift+Tab walks the thinking ladder,
11
+ * Alt+A / Ctrl+Alt+A toggles async paste handoff, Alt+โ†‘โ†“ reorders rows
11
12
  * - Enter or Ctrl+S saves, Esc / Ctrl+C cancels
12
- * - The primary is marked โœ“, chain members ๐Ÿ”
13
+ * - The primary is marked โœ“, chain members โ‡†
13
14
  */
14
15
 
15
16
  import {
@@ -25,23 +26,74 @@ import {
25
26
  visibleWidth,
26
27
  wrapTextWithAnsi,
27
28
  } from "@earendil-works/pi-tui";
28
- import type { Theme } from "@earendil-works/pi-coding-agent";
29
+ import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
29
30
  import type { ThinkingLevel } from "@earendil-works/pi-ai";
30
- import { DynamicBorder, keyText } from "@earendil-works/pi-coding-agent";
31
+ import { keyText } from "@earendil-works/pi-coding-agent";
31
32
  import { formatModelRef, isVisionModel, THINKING_LEVELS } from "./index.js";
32
33
 
33
34
  /** Failover chain length cap โ€” three is already far past the point where a
34
35
  * fourth describer would ever be reached. */
35
36
  export const MAX_FALLBACKS = 3;
36
37
 
37
- /** Key that toggles failover-chain membership, and the hint shown for it.
38
+ type OklchLike = { kind?: string; l?: number; c?: number; h?: number };
39
+ type ThemeLike = Pick<Theme, "fg" | "bold"> & {
40
+ colors?: Readonly<Record<string, OklchLike>>;
41
+ style?(text: string, options: { fg: OklchLike }): string;
42
+ };
43
+
44
+ // pi >=1.2 rejects custom theme tokens (accentSoft), so the arnative soft tier is
45
+ // derived from an official token with the theme generator's recipe: L 0.82,
46
+ // chroma x 0.18, hue kept. Older runtimes without colors/style keep fallback.
47
+ const SOFT_L = 0.82;
48
+ const SOFT_CHROMA_SCALE = 0.18;
49
+
50
+ export function softPainter(th: ThemeLike, base: ThemeColor, fallback: ThemeColor): (text: string) => string {
51
+ const style = th.style?.bind(th);
52
+ const declared = th.colors?.accentSoft;
53
+ if (style && declared?.kind === "oklch") return (t) => style(t, { fg: declared });
54
+ const c = th.colors?.[base];
55
+ if (style && c?.kind === "oklch") {
56
+ const fg = { kind: "oklch", l: SOFT_L, c: (c.c ?? 0) * SOFT_CHROMA_SCALE, h: c.h ?? 0 };
57
+ return (t) => style(t, { fg });
58
+ }
59
+ return (t) => th.fg(fallback, t);
60
+ }
61
+
62
+ export function boxEdge(left: string, right: string, width: number, paint: (s: string) => string): string {
63
+ return width < 2 ? "" : paint(left + "โ”€".repeat(width - 2) + right);
64
+ }
65
+
66
+ // Truncate before wrapping so a long row never pushes the right wall out of the frame.
67
+ export function boxRow(content: string, width: number, paint: (s: string) => string): string {
68
+ if (width < 4) return "";
69
+ const inner = truncateToWidth(content, width - 4, "");
70
+ const pad = " ".repeat(Math.max(0, width - 4 - visibleWidth(inner)));
71
+ return paint("โ”‚") + " " + inner + pad + " " + paint("โ”‚");
72
+ }
73
+
74
+ /** Key that toggles failover-chain membership.
75
+ *
76
+ * Tab is one byte (0x09) on every terminal and OS, and no terminal, window manager
77
+ * or multiplexer binds it. The search input has no Tab handler, and this chord is
78
+ * intercepted before the input. ctrl+enter (1.1.0) maximises the window in some
79
+ * terminals, and without the kitty keyboard protocol it cannot be told from enter.
80
+ * ctrl+f is Search in herdr. The older ctrl+q hit POSIX tty flow control (IXON)
81
+ * and pi's app.message.followUp; ctrl+shift+q hit VTE's close-terminal accelerator.
38
82
  *
39
- * Deliberately a single control byte nobody else wants: `ctrl+alt+f` never
40
- * survives Windows conhost/Windows Terminal (AltGr handling drops or downgrades
41
- * it), `alt+f` is pi's editor word-right, and `ctrl+f` is pi's find-text. */
42
- const FALLBACK_KEY = Key.ctrl("q");
43
- const FALLBACK_KEY_HINT = "ctrl+q";
44
- const RESET_FALLBACKS_KEY = Key.ctrlShift("q");
83
+ * Reset uses `ctrl+shift+r` because R reads as Reset. It is unbound in every
84
+ * default terminal (VTE, Konsole, Windows Terminal, iTerm2 โ€” kitty is the lone
85
+ * exception, where it resizes a window) and unbound anywhere in pi. On legacy
86
+ * 7-bit terminals it degrades to plain `ctrl+r`, which the app does not use, so
87
+ * the worst case is a no-op rather than a wrong action. The old `ctrl+shift+q`
88
+ * was impossible to type on those terminals: both it and `ctrl+q` emit 0x11. */
89
+ const FALLBACK_KEY = "tab";
90
+ const FALLBACK_KEY_HINT = "tab";
91
+ const REORDER_UP_KEY = Key.alt("up");
92
+ const REORDER_DOWN_KEY = Key.alt("down");
93
+ /** Hint printed next to the async toggle in the detail pane (and the legend).
94
+ * `ctrl+alt+a` is the Linux-safe half: AltGr occupies alt+a on intl layouts
95
+ * (`@`, `ล‚`), so the selector accepts both chords. */
96
+ const ASYNC_KEY_HINT = "[Ctrl+alt+a]";
45
97
 
46
98
  /** Provider ids that don't title-case cleanly. Everything else falls back to
47
99
  * word-capitalisation (`custom-openrouter-ai` โ†’ "Custom Openrouter AI"). */
@@ -101,6 +153,8 @@ export interface VisionModelSelectorResult {
101
153
  }
102
154
 
103
155
  export class VisionModelSelectorComponent implements Component {
156
+ /** Session thinking level; the frame follows it like Pi's own editor border. */
157
+ private readonly borderLevel?: Parameters<Theme["getThinkingBorderColor"]>[0];
104
158
  private theme: Theme;
105
159
  private done: (result: VisionModelSelectorResult) => void;
106
160
 
@@ -145,7 +199,9 @@ export class VisionModelSelectorComponent implements Component {
145
199
  currentAsyncClipboardHandoff: boolean,
146
200
  done: (result: VisionModelSelectorResult) => void,
147
201
  currentFallbacks: string[] = [],
202
+ borderLevel?: Parameters<Theme["getThinkingBorderColor"]>[0],
148
203
  ) {
204
+ this.borderLevel = borderLevel;
149
205
  this.theme = theme;
150
206
  this.done = done;
151
207
  this.currentRef = currentRef;
@@ -174,15 +230,21 @@ export class VisionModelSelectorComponent implements Component {
174
230
  }
175
231
 
176
232
  render(width: number): string[] {
233
+ // The user asked for the frame to follow the session thinking level, like Pi's editor border;
234
+ // the soft tier only applies when no level or no thinking-border API is available.
235
+ const thinkingBorder = this.borderLevel ? this.theme.getThinkingBorderColor?.(this.borderLevel) : undefined;
236
+ const border = thinkingBorder ?? softPainter(this.theme, "borderAccent", "accent");
237
+ const body = this.bodyLines(Math.max(1, width - 4)).flatMap((line) => line.split("\n"));
238
+ return [
239
+ boxEdge("โ•ญ", "โ•ฎ", width, border),
240
+ ...body.map((line) => boxRow(line, width, border)),
241
+ boxEdge("โ•ฐ", "โ•ฏ", width, border),
242
+ ];
243
+ }
244
+
245
+ private bodyLines(width: number): string[] {
177
246
  const lines: string[] = [];
178
- lines.push(...new DynamicBorder((s) => this.theme.fg("accent", s)).render(width));
179
- lines.push(
180
- truncateToWidth(
181
- this.theme.fg("accent", this.theme.bold("Vision Watcher")),
182
- width,
183
- "",
184
- ),
185
- );
247
+ lines.push(this.theme.fg("accent", this.theme.bold("Vision Watcher")));
186
248
  lines.push(
187
249
  ...wrapTextWithAnsi(
188
250
  this.theme.fg(
@@ -206,8 +268,7 @@ export class VisionModelSelectorComponent implements Component {
206
268
  lines.push(...this.detailLines(width));
207
269
  lines.push("");
208
270
  lines.push(...this.footerText.render(width));
209
- lines.push(...new DynamicBorder((s) => this.theme.fg("accent", s)).render(width));
210
- return lines.map((line) => truncateToWidth(line, width, ""));
271
+ return lines;
211
272
  }
212
273
 
213
274
  handleInput(data: string): void {
@@ -233,7 +294,27 @@ export class VisionModelSelectorComponent implements Component {
233
294
  return;
234
295
  }
235
296
 
297
+ // Reorder the highlighted model inside the list. The failover chain is
298
+ // tried in list order, so moving a row is how you change which fallback
299
+ // runs first. Only meaningful on the unfiltered list (the filter is a
300
+ // view, not an ordering); skip edits that would cross the pinned None row.
301
+ if (matchesKey(data, REORDER_UP_KEY) || matchesKey(data, REORDER_DOWN_KEY)) {
302
+ if (this.searchInput.getValue()) return;
303
+ const item = this.filteredItems[this.selectedIndex];
304
+ if (item?.ref) this.moveItem(item.ref, matchesKey(data, REORDER_DOWN_KEY) ? 1 : -1);
305
+ return;
306
+ }
307
+
308
+ // Confirming saves the configuration. When a filter query is typed, Enter
309
+ // ALSO adopts the highlighted model as the primary describer โ€” the search
310
+ // field has already consumed every `space`, so without this the highlighted
311
+ // model could never be picked while filtering and the stale primary would
312
+ // be saved silently.
236
313
  if (kb.matches(data, "tui.select.confirm") || matchesKey(data, Key.ctrl("s"))) {
314
+ if (this.searchInput.getValue()) {
315
+ const item = this.filteredItems[this.selectedIndex];
316
+ if (item) this.selectPrimary(item.ref);
317
+ }
237
318
  this.save();
238
319
  return;
239
320
  }
@@ -268,7 +349,7 @@ export class VisionModelSelectorComponent implements Component {
268
349
  // chosen together. Intercepted before the search input (like the other ctrl
269
350
  // shortcuts) so the key never lands in the filter text. See
270
351
  // {@link FALLBACK_KEY} for why it isn't ctrl+f.
271
- if (matchesKey(data, RESET_FALLBACKS_KEY)) {
352
+ if (matchesKey(data, "ctrl+shift+r")) {
272
353
  this.clearFallbacks();
273
354
  return;
274
355
  }
@@ -279,16 +360,21 @@ export class VisionModelSelectorComponent implements Component {
279
360
  return;
280
361
  }
281
362
 
282
- if (matchesKey(data, Key.ctrl("a"))) {
363
+ // alt+a on Windows/macOS, ctrl+alt+a on Linux where AltGr takes alt+a
364
+ // (intl layouts: `@`, `ล‚`). `ctrl+a` is the editor's cursorLineStart (Home)
365
+ // and GNU Screen / tmux's command prefix, so it cannot be repurposed here.
366
+ // Intercepted before the search input so it never lands in the filter text.
367
+ if (matchesKey(data, Key.alt("a")) || matchesKey(data, Key.ctrlAlt("a"))) {
283
368
  this.asyncClipboardHandoff = !this.asyncClipboardHandoff;
284
369
  this.updateList();
285
370
  return;
286
371
  }
287
372
 
288
- // ctrl+t walks the whole thinking ladder (off โ†’ minimal โ†’ โ€ฆ โ†’ max โ†’ off) so
289
- // one key covers on/off *and* effort โ€” no separate shift+tab binding.
290
- // Intercepted before the search input so it never lands in the filter text.
291
- if (kb.matches(data, "app.thinking.toggle") || matchesKey(data, Key.ctrl("t"))) {
373
+ // shift+tab walks the whole thinking ladder (off, minimal ... max, off). It is one
374
+ // sequence (ESC [ Z) on every terminal and is pi's own app.thinking.cycle, so the
375
+ // meaning carries over. ctrl+shift+t opened a new tab in Windows Terminal and GNOME
376
+ // Terminal and is pi's app.session.tree. Intercepted before the search input.
377
+ if (matchesKey(data, "shift+tab")) {
292
378
  this.cycleThinking();
293
379
  this.updateList();
294
380
  return;
@@ -356,21 +442,37 @@ export class VisionModelSelectorComponent implements Component {
356
442
 
357
443
  // One legend line: the count carries the accent colour so it is the first
358
444
  // thing the eye lands on, while the keys stay dim so they do not compete
359
- // with the picker itself. ctrl+a toggles the async clipboard handoff; it
360
- // is deliberately left out so this line stays readable at 80 columns.
445
+ // with the picker itself. The chords need roughly 130 columns, which wraps
446
+ // gracefully; the async chord is hinted beside the state it toggles (and in
447
+ // the README) instead of bloating this strip. `Move` is the highlight, not
448
+ // the row: reordering is `alt+โ†‘โ†“` and lives in the README.
361
449
  const confirm = keyText("tui.select.confirm");
362
450
  const legend = [
451
+ "[โ†‘โ†“] Move",
363
452
  `[${confirm.charAt(0).toUpperCase()}${confirm.slice(1)}] Done`,
364
453
  "[Space] Vision",
365
- "[Ctrl+q] Fallback",
366
- "[Ctrl+Shift+q] Reset",
367
- "[Ctrl+t] Think",
454
+ "[Tab] Fallback",
455
+ "[Ctrl+shift+r] Reset",
456
+ "[Shift+tab] Think",
368
457
  "[Esc] Cancel",
369
458
  ].join(" ");
370
459
 
371
460
  return `${this.theme.fg("dim", " ")}${this.theme.fg("accent", count)}${this.theme.fg("dim", ` ยท ${legend}`)}`;
372
461
  }
373
462
 
463
+ /** Move `ref` one row up/down in the display list. The None row is pinned at
464
+ * index 0; no move may cross it or run off either end. */
465
+ private moveItem(ref: string, delta: number): void {
466
+ const from = this.allItems.findIndex((i) => i.ref === ref);
467
+ const to = from + delta;
468
+ if (from <= 0 || to <= 0 || to >= this.allItems.length) return;
469
+ const [item] = this.allItems.splice(from, 1);
470
+ this.allItems.splice(to, 0, item!);
471
+ this.filteredItems = this.allItems;
472
+ this.selectedIndex = to;
473
+ this.updateList();
474
+ }
475
+
374
476
  private clearFallbacks(): void {
375
477
  if (this.fallbacks.size === 0) return;
376
478
  this.fallbacks.clear();
@@ -459,9 +561,9 @@ export class VisionModelSelectorComponent implements Component {
459
561
  label = this.theme.fg("warning", item.modelName);
460
562
  } else {
461
563
  const labelled = isSelected
462
- ? this.theme.fg("accent", item.modelId)
564
+ ? softPainter(this.theme, "accent", "accent")(this.theme.bold(item.modelId))
463
565
  : item.modelId;
464
- const badge = item.vision ? this.theme.fg("success", " ๐Ÿ‘€") : this.theme.fg("muted", " ยท");
566
+ const badge = item.vision ? this.theme.fg("success", " โœฆ") : this.theme.fg("muted", " ยท");
465
567
  const providerBadge = this.theme.fg("muted", ` [${item.provider}]`);
466
568
  label = `${labelled}${providerBadge}${badge}`;
467
569
  }
@@ -476,7 +578,7 @@ export class VisionModelSelectorComponent implements Component {
476
578
  // chain behind it).
477
579
  const fallbackMark =
478
580
  item.ref && this.fallbacks.has(item.ref)
479
- ? this.theme.fg("warning", " ๐Ÿ”")
581
+ ? this.theme.fg("warning", " โ‡†")
480
582
  : "";
481
583
 
482
584
  this.listContainer.addChild(new Text(`${prefix}${label}${current}${fallbackMark}`, 0, 0));
@@ -512,7 +614,7 @@ export class VisionModelSelectorComponent implements Component {
512
614
  }
513
615
 
514
616
  /** The detail pane summarises the *configuration* (primary, failover chain
515
- * and toggles) rather than the highlighted row, so each space / ctrl+q
617
+ * and toggles) rather than the highlighted row, so each space / tab
516
618
  * press shows exactly what will be saved.
517
619
  *
518
620
  * Built per frame rather than cached in a child component because the
@@ -521,18 +623,33 @@ export class VisionModelSelectorComponent implements Component {
521
623
  private detailLines(width: number): string[] {
522
624
  const out: string[] = [];
523
625
 
524
- const line = (label: string, value: string) => {
525
- const indent = " ".repeat(2 + visibleWidth(label));
526
- const wrapped = wrapTextWithAnsi(
527
- value,
528
- Math.max(8, width - visibleWidth(indent)),
529
- );
530
- out.push(`${this.theme.fg("dim", ` ${label}`)}${wrapped[0] ?? ""}`);
626
+ // Arnative status-panel rows: `Label ยท STATUS | detail`, the label column
627
+ // padded to the widest label so every `ยท` divider sits in one column, one
628
+ // status word per row (success = on, muted = off). A long detail wraps
629
+ // under its own value column instead of spilling to column 0.
630
+ const labels = {
631
+ vision: " Vision-capable โœฆ",
632
+ fallback: " Fallback โ‡†",
633
+ thinking: " Thinking",
634
+ async: " Async pasted-path fallback",
635
+ };
636
+ const col = Math.max(...Object.values(labels).map((l) => visibleWidth(l)));
637
+
638
+ const row = (labelText: string, status: string, color: ThemeColor, detail: string) => {
639
+ const head =
640
+ this.theme.fg("dim", labelText) +
641
+ " ".repeat(col - visibleWidth(labelText)) +
642
+ this.theme.fg("dim", " ยท ") +
643
+ this.theme.fg(color, status);
644
+ // Continuations clear the " | " separator so they line up with the detail.
645
+ const indent = " ".repeat(visibleWidth(head) + 3);
646
+ const wrapped = wrapTextWithAnsi(detail, Math.max(8, width - indent.length));
647
+ out.push(`${head}${detail ? this.theme.fg("dim", " | ") + (wrapped[0] ?? "") : ""}`);
531
648
  for (const extra of wrapped.slice(1)) out.push(indent + extra);
532
649
  };
533
650
 
534
651
  // Free-standing sentence (warning / transient notice), hanging-indented
535
- // under its own `โš `/first word.
652
+ // under its own first word.
536
653
  const note = (text: string) => {
537
654
  const indent = " ";
538
655
  wrapTextWithAnsi(text, Math.max(8, width - indent.length)).forEach(
@@ -540,33 +657,35 @@ export class VisionModelSelectorComponent implements Component {
540
657
  );
541
658
  };
542
659
 
543
- line(
544
- "Vision-capable (๐Ÿ‘€): ",
660
+ row(
661
+ labels.vision,
662
+ this.currentRef ? "ON" : "OFF",
663
+ this.currentRef ? "success" : "muted",
545
664
  this.currentRef
546
665
  ? this.refLabel(this.currentRef)
547
- : this.theme.fg("muted", "none โ€” vision handoff disabled"),
666
+ : this.theme.fg("muted", "none โ€” vision watcher disabled"),
548
667
  );
549
668
 
550
669
  const chain = this.orderedFallbacks();
551
- line(
552
- "Fallback (๐Ÿ”): ",
553
- chain.length
554
- ? `${this.theme.fg("success", "on")} - ${chain.map((r) => this.refLabel(r)).join(", ")}`
555
- : this.theme.fg("muted", "off"),
670
+ row(
671
+ labels.fallback,
672
+ chain.length ? "ON" : "OFF",
673
+ chain.length ? "success" : "muted",
674
+ chain.length ? `${chain.map((r) => this.refLabel(r)).join(" โ†’ ")} (max ${MAX_FALLBACKS})` : "",
556
675
  );
557
676
 
558
- line(
559
- "Thinking: ",
560
- this.thinking
561
- ? this.theme.fg("success", `on (${this.thinkingLevel})`)
562
- : this.theme.fg("muted", "off"),
677
+ row(
678
+ labels.thinking,
679
+ this.thinking ? "ON" : "OFF",
680
+ this.thinking ? "success" : "muted",
681
+ this.thinking ? this.thinkingLevel : "",
563
682
  );
564
683
 
565
- line(
566
- "Async pasted-path fallback: ",
567
- this.asyncClipboardHandoff
568
- ? this.theme.fg("success", "on")
569
- : this.theme.fg("muted", "off"),
684
+ row(
685
+ labels.async,
686
+ this.asyncClipboardHandoff ? "ON" : "OFF",
687
+ this.asyncClipboardHandoff ? "success" : "muted",
688
+ ASYNC_KEY_HINT,
570
689
  );
571
690
 
572
691
  // The warning follows the *highlighted* row: it answers "what happens if I
@@ -576,7 +695,7 @@ export class VisionModelSelectorComponent implements Component {
576
695
  note(
577
696
  this.theme.fg(
578
697
  "warning",
579
- ` โš  ${highlighted.modelId} declares no reasoning โ€” thinking will be ignored`,
698
+ ` Warning: ${highlighted.modelId} declares no reasoning โ€” thinking will be ignored`,
580
699
  ),
581
700
  );
582
701
  }