agentvibes 5.14.0 → 5.15.1

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20260719
+20260721

package/.claude/hooks-windows/agentvibes-session-id.ps1

@@ -0,0 +1,83 @@
+#
+# File: .claude/hooks-windows/agentvibes-session-id.ps1
+#
+# AgentVibes - Text-to-Speech WITH personality for AI Assistants
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Licensed under the Apache License, Version 2.0
+#
+# @fileoverview Print a short spoken self-identifier for THIS session, e.g.
+#   "Claude on AgentVibes in Windows Terminal"
+# @why With several agent sessions open at once, every one saying the same thing
+#   makes it impossible to tell which tab just spoke. Prefixing each session's
+#   speech with who+where answers "which one is that?" (community request).
+# @usage agentvibes-session-id.ps1 <llm-key> <project-dir>
+#   Also used via the {{session}} token in a per-LLM PRETEXT (see play-tts.ps1).
+#
+# PowerShell mirror of .claude/hooks/agentvibes-session-id.sh — the LLM name map,
+# the project-name fallback, and the terminal-detection ORDER must stay identical
+# so a given session announces itself the same way on either runtime.
+#
+param(
+    [string]$LlmKey     = "claude-code",
+    [string]$ProjectDir = ""
+)
+
+$ErrorActionPreference = "SilentlyContinue"
+
+if (-not $ProjectDir) { $ProjectDir = (Get-Location).Path }
+
+# LLM display name (same mapping as the bash version)
+$LlmName = switch -Regex ($LlmKey) {
+    '^claude'            { "Claude"; break }
+    '^gemini'            { "Gemini"; break }
+    '^(codex|openai|gpt)' { "Codex";  break }
+    '^cursor'            { "Cursor"; break }
+    '^default$'          { "Agent";  break }
+    default              { $LlmKey }
+}
+
+# Project name = leaf of the project dir. Split-Path is used rather than
+# Get-Item so a path that no longer exists still yields a usable name.
+$ProjName = ""
+try { $ProjName = Split-Path -Leaf ($ProjectDir.TrimEnd('\', '/')) } catch { }
+if (-not $ProjName -or $ProjName -in @('/', '.', '\')) { $ProjName = "this project" }
+
+# Terminal detection — prefer the most specific signal available.
+# Order mirrors the bash version exactly.
+$TermName = ""
+if ($env:WT_SESSION) {
+    $TermName = "Windows Terminal"
+} elseif ($env:TERM_PROGRAM) {
+    $TermName = switch ($env:TERM_PROGRAM) {
+        "vscode"         { "VS Code" }
+        "iTerm.app"      { "iTerm" }
+        "Apple_Terminal" { "Terminal" }
+        # One entry only: PowerShell's switch is case-insensitive by default, so
+        # separate "ghostty"/"Ghostty" arms BOTH match and both emit, yielding
+        # "Ghostty Ghostty". Bash needs the two arms; PowerShell must not have them.
+        "ghostty"        { "Ghostty" }
+        "WezTerm"        { "WezTerm" }
+        "Hyper"          { "Hyper" }
+        "tmux"           { "tmux" }
+        "Tabby"          { "Tabby" }
+        default          { $env:TERM_PROGRAM }
+    }
+} elseif ($env:TERMINAL_EMULATOR) {
+    $TermName = $env:TERMINAL_EMULATOR
+} elseif ($env:KITTY_WINDOW_ID) {
+    $TermName = "kitty"
+} elseif ($env:ALACRITTY_WINDOW_ID) {
+    $TermName = "Alacritty"
+} elseif ($env:TMUX) {
+    $TermName = "tmux"
+}
+
+# -NoNewline so the caller can embed the result directly in a pretext, matching
+# the bash version's printf (which also emits no trailing newline).
+if ($TermName) {
+    Write-Host -NoNewline "$LlmName on $ProjName in $TermName"
+} else {
+    Write-Host -NoNewline "$LlmName on $ProjName"
+}

package/.claude/hooks-windows/play-tts.ps1

@@ -73,7 +73,8 @@ $HooksDir = "$ClaudeDir\hooks-windows"
 $ProviderFile = "$ClaudeDir\tts-provider.txt"
 $MuteFile = "$ClaudeDir\tts-muted.txt"
 
-# Check if TTS is muted
+# Check if TTS is muted (receiver master switch — /agent-vibes:receiver off).
+# Kept as an absolute pre-check so existing behaviour does not regress.
 if (Test-Path $MuteFile) {
     $muteStatus = Get-Content $MuteFile -Raw
     if ($muteStatus.Trim() -eq "true") {
@@ -81,6 +82,35 @@ if (Test-Path $MuteFile) {
     }
 }
 
+# ---------------------------------------------------------------------------
+# MUTE PRECEDENCE (parity with .claude/hooks/play-tts.sh:89-114).
+#
+# Until now this player read ONLY tts-muted.txt above, which /agent-vibes:mute
+# never writes — so `/agent-vibes:mute` did not silence Windows audio at all,
+# and the global `~/.agentvibes-muted` kill-switch was ignored on Windows.
+# Same three levels as bash, in the same order:
+#   1. project agentvibes-unmuted -> speak (overrides a global mute)
+#   2. project agentvibes-muted   -> silent
+#   3. global ~/.agentvibes-muted -> silent
+#
+# The project markers live under the REAL project root (CLAUDE_PROJECT_DIR when
+# set), not $ClaudeDir, which falls back to the user profile for global installs.
+# $HOME is preferred over $env:USERPROFILE so markers written by bash under
+# git-bash resolve to the same file here.
+$HomeDir = if ($env:HOME) { $env:HOME } else { $env:USERPROFILE }
+$MuteScopeDir = if ($env:CLAUDE_PROJECT_DIR -and (Test-Path "$env:CLAUDE_PROJECT_DIR\.claude")) {
+    "$env:CLAUDE_PROJECT_DIR\.claude"
+} else {
+    $ClaudeDir
+}
+if (Test-Path (Join-Path $MuteScopeDir "agentvibes-unmuted")) {
+    # explicit per-project enable — wins over the global kill-switch
+} elseif (Test-Path (Join-Path $MuteScopeDir "agentvibes-muted")) {
+    exit 0
+} elseif (Test-Path (Join-Path $HomeDir ".agentvibes-muted")) {
+    exit 0
+}
+
 # Determine active provider
 $ActiveProvider = "windows-sapi"
 if (Test-Path $ProviderFile) {
@@ -453,6 +483,70 @@ elseif (-not $PlanOk -and $_LlmVoice -and -not $VoiceOverride) {
     $VoiceOverride = $_LlmVoice
 }
 
+# --- Dynamic session self-ID ({{session}} token) ------------------------------
+# Parity with play-tts.sh:250-296. A per-LLM PRETEXT containing {{session}}
+# expands to "<LLM> on <Project> in <Terminal>" so multi-session users can tell
+# which window just spoke. Announced ONCE per session; on later utterances the
+# token is dropped rather than prefixing every line. Opt-in — this whole block
+# is inert unless the configured pretext actually contains the token.
+if ($_LlmPretext -like "*{{session}}*") {
+    # Session key. There is no true Claude-session id available to a hook, so
+    # this is best-effort: a terminal-session id when the emulator exports one
+    # (stable for that tab's life), else this process's parent PID. Worst case
+    # the self-ID repeats or is skipped — cosmetic, and only when opted in.
+    $_SidRaw = if ($env:WT_SESSION) { $env:WT_SESSION }
+               elseif ($env:TERM_SESSION_ID) { $env:TERM_SESSION_ID }
+               elseif ($env:TMUX) { $env:TMUX }
+               else {
+                   try { (Get-CimInstance Win32_Process -Filter "ProcessId=$PID").ParentProcessId } catch { $PID }
+               }
+    $_SidProj = ""
+    $_SidProjDirRaw = if ($env:CLAUDE_PROJECT_DIR) { $env:CLAUDE_PROJECT_DIR } else { $ClaudeDir }
+    try { $_SidProj = Split-Path -Leaf ($_SidProjDirRaw.TrimEnd('\', '/')) } catch { }
+    $_SidKey = (("$llm|$_SidProj|$_SidRaw") -replace '[^A-Za-z0-9]', '_')
+
+    # Announce-marker dir under the per-user temp path (already user-scoped on
+    # Windows: %LOCALAPPDATA%\Temp), so no cross-user marker collisions.
+    $_AnnDir  = Join-Path ([System.IO.Path]::GetTempPath()) "agentvibes-session"
+    $_AnnOk   = $false
+    try { $null = New-Item -ItemType Directory -Path $_AnnDir -Force -ErrorAction Stop; $_AnnOk = $true } catch { }
+    $_AnnFile = Join-Path $_AnnDir "announced-$_SidKey"
+
+    # First utterance -> replacement is the self-ID; later utterances -> empty.
+    $_SessionId = ""
+    if ($_AnnOk -and (Test-Path $_AnnFile)) {
+        $_SessionId = ""
+    } else {
+        $_SidScript = Join-Path $HooksDir "agentvibes-session-id.ps1"
+        if (Test-Path $_SidScript) {
+            $_SidProjDir = if ($env:CLAUDE_PROJECT_DIR) { $env:CLAUDE_PROJECT_DIR } else { $ClaudeDir }
+            try { $_SessionId = & $_SidScript -LlmKey $llm -ProjectDir $_SidProjDir } catch { $_SessionId = "" }
+        }
+        if ($_AnnOk) {
+            try {
+                if (-not (Test-Path $_AnnFile)) { $null = New-Item -ItemType File -Path $_AnnFile -ErrorAction Stop }
+                # Bound growth: drop announce-markers older than a day.
+                Get-ChildItem -Path $_AnnDir -Filter 'announced-*' -ErrorAction SilentlyContinue |
+                    Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-1) } |
+                    Remove-Item -Force -ErrorAction SilentlyContinue
+            } catch { }
+        }
+    }
+
+    if ($_SessionId) {
+        $_LlmPretext = $_LlmPretext -replace [regex]::Escape('{{session}}'), $_SessionId
+    } else {
+        # Empty replacement: also swallow one adjacent ", " so "Hey {{session}}, ready"
+        # becomes "Hey ready", not "Hey , ready"; then drop any bare token.
+        $_LlmPretext = $_LlmPretext -replace [regex]::Escape('{{session}}, '), ''
+        $_LlmPretext = $_LlmPretext -replace [regex]::Escape(', {{session}}'), ''
+        $_LlmPretext = $_LlmPretext -replace [regex]::Escape('{{session}}'), ''
+    }
+    # Final tidy: collapse doubled/edge commas and runs of whitespace.
+    $_LlmPretext = $_LlmPretext -replace ',\s*,', ',' -replace '^\s*,\s*', '' -replace '\s*,\s*$', '' -replace '\s{2,}', ' '
+    $_LlmPretext = $_LlmPretext.Trim()
+}
+
 # --- Apply LLM-specific pretext ----------------------------------------------
 # Prepend the configured pretext (e.g. "Agent Vibes Here") to the speech
 # text.  Guard against double-prefixing on re-entrant or looped calls by

package/.claude/hooks-windows/session-start-tts.ps1

@@ -33,6 +33,42 @@ if ($env:CLAUDE_PROJECT_DIR -and (Test-Path "$env:CLAUDE_PROJECT_DIR\.claude"))
     $ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptDir)) ".claude"
 }
 
+# ---------------------------------------------------------------------------
+# OPT-IN INJECTION GATE (Issue: global-install cacophony).
+#
+# Mirror of the gate in .claude/hooks/session-start-tts.sh — see the long
+# rationale there. Previously this hook injected the ~250-token TTS protocol
+# into EVERY Windows session where AgentVibes was found on disk, so a global
+# install made every open session start speaking at once, and idle sessions
+# still paid the token cost. Injection is now OPT-IN on Windows too.
+#
+# Precedence (identical to bash, so injection and audio agree):
+#   1. project agentvibes-unmuted  -> inject   (explicit per-project ON)
+#   2. project agentvibes-muted    -> silent
+#   3. global ~/.agentvibes-muted  -> silent   (the global kill-switch)
+#   4. project agentvibes-enabled, OR global opt-in
+#      (~/.claude/agentvibes-enabled or ~/.claude/agentvibes-unmuted) -> inject
+#   5. otherwise                   -> silent   (opt-in default; zero tokens)
+#
+# $HOME is honoured ahead of $env:USERPROFILE so the markers resolve the same
+# way under git-bash (where bash writes them) as under native PowerShell.
+$HomeDir = if ($env:HOME) { $env:HOME } else { $env:USERPROFILE }
+if (Test-Path (Join-Path $ProjectClaudeDir "agentvibes-unmuted")) {
+    # explicit per-project enable — wins over a global mute, as in play-tts.sh
+} elseif (Test-Path (Join-Path $ProjectClaudeDir "agentvibes-muted")) {
+    exit 0
+} elseif (Test-Path (Join-Path $HomeDir ".agentvibes-muted")) {
+    exit 0   # global kill-switch, no per-project override
+} elseif ((Test-Path (Join-Path $ProjectClaudeDir "agentvibes-enabled")) -or
+          (Test-Path (Join-Path $HomeDir ".claude\agentvibes-enabled"))  -or
+          (Test-Path (Join-Path $HomeDir ".claude\agentvibes-unmuted"))) {
+    # opted in (project install marker, or a deliberate global opt-in)
+} else {
+    # Not enabled for this project -> inject nothing (zero tokens).
+    # Enable for this project with:  /agent-vibes:unmute
+    exit 0
+}
+
 # Build the -ProjectDir flag to inject into TTS commands (empty string = omit flag).
 # Sanitize: strip any embedded quotes that would break PowerShell argument quoting.
 $ProjectDirFlag = ""

package/README.md

@@ -58,7 +58,21 @@ New here? The [**Quick Start guide**](docs/quick-start.md) walks you through you
 
 ---
 
-## 🆕 Reliable setup and complete audio previews (v5.14.0)
+## 🆕 Know where your preview plays (v5.15.1)
+
+- **Every preview shows where it plays** — voice and music previews now display **(locally)** or **(remotely via SSH)** right on the row you're auditioning, so you're never guessing (or hearing silence on a headless box).
+- **Preview standardized across the app** — the voice pickers (Kokoro, Piper, ElevenLabs, per-agent BMAD) and the Music page all show the same indicator; music previews now follow a project's remote receiver too.
+- **Cleaner Agents tab** — it lists your real BMAD agents (not a skill's internal helpers) and re-checks itself on focus; **Reset** moved off `X` (which jumped to the Receiver tab) to **`Del`**.
+
+### v5.15.0 — Multi-session control on Windows
+
+- **Sessions stay quiet unless you enable them** — a session speaks only in a project you've turned on; others add no instructions and no token cost.
+- **`/agent-vibes:mute` now works on Windows** — it previously had no effect there. Both project and global mute are honoured on every platform.
+- **Sessions can introduce themselves on Windows** — `{{session}}` announces "Claude on my-app in Windows Terminal", once per session.
+- **Self-introductions now reach global installs** — the script behind them was never delivered by the updater on any platform.
+- **Note for global Windows installs:** sessions are off by default after this update — enable with `/agent-vibes:unmute`.
+
+### v5.14.0 — Reliable setup and complete audio previews
 
 Includes all changes from 5.13.2, which was not published to npm.
 
@@ -258,7 +272,7 @@ anything (no new network calls, no behavior change) for every current install.
 
 ## About
 
-**AgentVibes** · v5.14.0 · Licensed under [Apache-2.0](LICENSE)
+**AgentVibes** · v5.15.1 · Licensed under [Apache-2.0](LICENSE)
 
 Built by **Paul Preibisch** — [@997Fire on X](https://x.com/997Fire) · [agentvibes.org](https://agentvibes.org) · [github.com/paulpreibisch/AgentVibes](https://github.com/paulpreibisch/AgentVibes)
 

package/RELEASE_NOTES.md

@@ -1,5 +1,108 @@
 # AgentVibes Release Notes
 
+## v5.15.1 — Know where your preview plays
+
+**Released:** 2026-07-21 · `npm install agentvibes@latest`
+
+Here's the thing we kept running into: when you press Space to preview a voice
+or a music track, there was no way to tell whether it was about to play *on your
+own machine* or get sent *to your remote receiver*. On a headless box that meant
+pressing preview and hearing… nothing — with no idea why.
+
+So we fixed it. Every preview now tells you exactly where the sound is going —
+**(locally)** or **(remotely via SSH)** — right on the row you're auditioning.
+No more guessing.
+
+And while we were in there, we **standardized preview across the whole app**.
+The voice pickers (Kokoro, Piper, ElevenLabs, and per-agent BMAD voices) and the
+Music page now all show the same `Previewing (locally / remotely via SSH)`
+indicator, so it looks and behaves identically everywhere. It's a small thing
+that turns out to be genuinely useful.
+
+One practical upshot: if a project routes its TTS to a remote receiver, **music
+previews now follow it too** — before, they quietly played on the local machine,
+which is silence on a headless server.
+
+### Also in this release
+
+- **The Agents tab shows your real BMAD agents** (Mary, Winston, Amelia, John,
+  Paige, Sally…) instead of a skill's internal helpers — and it re-checks itself
+  when you switch back to the tab, so a fresh BMAD install shows up without a
+  restart.
+- **Reset no longer yanks you to the Receiver tab.** It was mapped to `X`, the
+  same key that globally jumps to Receiver; it's now `Del`.
+
+## v5.15.0 — Multi-session control on Windows
+
+**Released:** 2026-07-20 · `npm install agentvibes@latest`
+
+If you run several agent sessions at once, this release gives Windows the same
+control macOS and Linux gained in 5.13.0: sessions stay quiet unless you turn
+them on, and each one can tell you which window is speaking.
+
+### Sessions no longer all speak at once
+
+Running AgentVibes across several projects previously meant every open session
+announced itself, with no straightforward way to keep just one talking. On
+macOS and Linux this was addressed in 5.13.0. **On Windows it was not** — the
+Windows session hook enabled speech in every session regardless of your
+settings.
+
+Windows now follows the same rule: a session speaks only in a project you have
+explicitly enabled. Projects you have not enabled contribute **nothing at all**
+— not silent audio, but no added instructions and no token cost.
+
+### Mute now works on Windows
+
+`/agent-vibes:mute` had no effect on Windows audio. It silenced macOS and Linux
+only, because the Windows player read a different setting than the one the
+command wrote.
+
+Both the project mute and the global switch are now honoured on Windows:
+
+- `/agent-vibes:mute` — quiet this project
+- `/agent-vibes:unmute` — turn this project back on, even while everything else
+  is globally muted
+
+This makes "off everywhere, on in the one project I am working in" a single
+pair of commands on every platform.
+
+### Sessions can identify themselves on Windows
+
+Include `{{session}}` in your pretext and a session introduces itself once:
+
+```
+Claude on my-app in Windows Terminal
+```
+
+It names the project and detects the terminal — Windows Terminal, VS Code,
+Ghostty, iTerm, Terminal, WezTerm, tmux and others. Announced once per session
+rather than before every line. This previously worked only on macOS and Linux.
+
+### A related fix for every platform
+
+The script that produces that introduction was missing from the update process,
+so on a global install it was never delivered and the feature silently did
+nothing. It is now included on macOS, Linux and Windows alike.
+
+### Upgrading
+
+Your existing choices are preserved — if you have already muted, unmuted, or
+enabled a project, updating leaves that setting alone.
+
+**One change worth noting for Windows users on a global install:** because
+sessions are now off unless enabled, a global Windows install will be quiet
+after updating. Turn on the projects you want with `/agent-vibes:unmute`.
+Project installs are enabled automatically and are unaffected.
+
+### Quality
+
+New regression tests assert that the session gate, the mute rules, and the
+self-identification behave identically on both runtimes, so the platforms
+cannot drift apart again without the build failing.
+
+---
+
 ## v5.14.0 — Reliable setup and complete audio previews
 
 **Released:** 2026-07-19 · `npm install agentvibes@latest`

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.14.0",
+  "version": "5.15.1",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/src/console/footer-config.js

@@ -33,7 +33,7 @@ export const FOOTER_CONFIG = {
   },
   agents: {
     color: '#9c27b0',
-    text: ` ${key('↑↓')} Navigate  ${key('Enter')} Edit Agent  ${key('Space')} Sample  ${key('R')} Reset`,
+    text: ` ${key('↑↓')} Navigate  ${key('Enter')} Edit Agent  ${key('Space')} Sample  ${key('Del')} Reset`,
   },
   receiver: {
     color: '#00897b',

package/src/console/music-preview.js

@@ -15,11 +15,17 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { spawn } from 'node:child_process';
+import { detectRemoteLlm } from './audio-env.js';
 
 // Transport providers route audio to a remote receiver; local MP3 playback is
 // silent on a headless/remote box, so track previews must be forwarded instead.
 export const REMOTE_PROVIDERS = ['ssh-remote', 'agentvibes-receiver'];
 
+// Preview transport badge + row spinner live in the neutral preview-transport
+// module (shared with the voice pickers). Re-exported here for the music
+// surfaces that already import from music-preview.js.
+export { transportBadge, createRowSpinner, previewRowContent, SPIN_FRAMES } from './preview-transport.js';
+
 /**
  * Resolve the active provider and the project dir it was read from, using the
  * same search order as the voice pickers (CLAUDE_PROJECT_DIR → cwd → package →
@@ -30,16 +36,26 @@ export const REMOTE_PROVIDERS = ['ssh-remote', 'agentvibes-receiver'];
  */
 export function resolveMusicProvider(packageRoot) {
   const dirs = [process.env.CLAUDE_PROJECT_DIR, process.cwd(), packageRoot, os.homedir()].filter(Boolean);
+
+  // A configured remote TTS transport (transport-config.json mode=remote) routes
+  // audio to a receiver, so a LOCAL music preview would be silent on this box —
+  // forward it too, matching the voice preview. This is a SEPARATE signal from
+  // the provider file: a project can carry tts-provider.txt=piper (local) while
+  // the global transport routes TTS to a remote receiver, and the two surfaces
+  // must agree or the picker plays to an inaudible local sink.
+  const transportRemote = !!detectRemoteLlm();
+
   for (const d of dirs) {
     const p = path.join(d, '.claude', 'tts-provider.txt');
     try {
       if (fs.existsSync(p)) {
         const provider = fs.readFileSync(p, 'utf8').trim();
-        return { remote: REMOTE_PROVIDERS.includes(provider), projectDir: d };
+        return { remote: REMOTE_PROVIDERS.includes(provider) || transportRemote, projectDir: d };
       }
     } catch { /* next */ }
   }
-  return { remote: false, projectDir: '' };
+  // No provider file found anywhere — still forward if a remote transport is set.
+  return { remote: transportRemote, projectDir: process.env.CLAUDE_PROJECT_DIR || process.cwd() };
 }
 
 /**

package/src/console/preview-transport.js

@@ -0,0 +1,174 @@
+/**
+ * AgentVibes — Shared preview transport badge + row spinner.
+ *
+ * Every music & voice preview surface renders an identical "previewing" cue ON
+ * THE SELECTED ROW (not a separate bottom line), so the user always sees where a
+ * preview is going and can stop it:
+ *
+ *   ⠹ Previewing (locally)            (Space to stop)   — green, plays here
+ *   ⠹ Previewing (remotely via SSH)   (Space to stop)   — red, forwarded to receiver
+ *
+ * The item name is intentionally omitted — the animated row IS the selected item.
+ * Kept in one neutral module so music and voice pickers can't drift.
+ */
+
+/** Braille spinner frames, shared by every preview surface. */
+export const SPIN_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/**
+ * Color-coded transport badge shown right after "Previewing".
+ * @param {boolean} remote - true when forwarded to the SSH receiver
+ * @returns {string} blessed-tagged badge, e.g. "{red-fg}(remotely via SSH){/red-fg}"
+ */
+export function transportBadge(remote) {
+  return remote
+    ? '{red-fg}(remotely via SSH){/red-fg}'
+    : '{green-fg}(locally){/green-fg}';
+}
+
+/**
+ * Right-pad a blessed-tagged string with spaces to a target VISIBLE width, so a
+ * shorter row fully overwrites a longer previous row (blessed's list.setItem does
+ * not clear leftover cells → the old tail ghosts through). Color tags don't count
+ * toward width. Over-padding is safe: a non-wrapping list clips the overflow.
+ * @param {string} tagged
+ * @param {number} width - target visible width (e.g. the list's outer width)
+ * @returns {string}
+ */
+export function padTaggedTo(tagged, width) {
+  if (!width || width <= 0) return tagged;
+  const visible = tagged.replace(/\{[^}]*\}/g, '');
+  const pad = width - visible.length;
+  return pad > 0 ? tagged + ' '.repeat(pad) : tagged;
+}
+
+/**
+ * The full "previewing" row content (spinner frame + Previewing + badge + hint).
+ * @param {string} frameChar - one SPIN_FRAMES glyph
+ * @param {boolean} remote
+ * @param {string} [stopHint]
+ * @returns {string} blessed-tagged row content
+ */
+export function previewRowContent(frameChar, remote, stopHint = 'Space to stop') {
+  return `{cyan-fg}${frameChar} Previewing {/cyan-fg}${transportBadge(remote)}{cyan-fg}  (${stopHint}){/cyan-fg}`;
+}
+
+/**
+ * Preview indicator APPENDED after a row's existing label (keepLabel mode).
+ * Used where replacing the label would be jarring — e.g. the Music tab, whose
+ * rows carry emoji: keeping the name in place avoids a perceived "jump", and
+ * only the trailing spinner char changes per frame so blessed never re-diffs the
+ * (wide) emoji cell.
+ * @param {string} baseRow - the row's normal content (with its label/emoji)
+ * @param {string} frameChar
+ * @param {boolean} remote
+ * @param {string} [stopHint]
+ * @returns {string}
+ */
+export function previewRowAppend(baseRow, frameChar, remote, stopHint = 'Space to stop') {
+  return `${baseRow}   {cyan-fg}${frameChar}{/cyan-fg} ${transportBadge(remote)}{cyan-fg}  (${stopHint}){/cyan-fg}`;
+}
+
+/**
+ * Attach an animated preview indicator to the SELECTED row of a blessed list.
+ * Generalizes the Kokoro picker's row spinner so every picker behaves identically.
+ *
+ * @param {object}   list        - blessed list (needs setItem(idx, str))
+ * @param {object}   screen      - blessed screen (needs render())
+ * @param {(idx:number)=>string} renderItem - returns a row's normal content (to restore on stop)
+ * @param {object}   [opts]
+ * @param {()=>boolean} [opts.isClosed] - guard: true once the picker is torn down
+ * @param {()=>number}  [opts.now]      - clock (ms); injectable for tests
+ * @param {number}   [opts.intervalMs]  - frame interval (default 80)
+ * @param {number}   [opts.minVisibleMs]- min on-screen window for fire-and-forget remote (default 1100)
+ * @returns {{ start:Function, stop:Function, stopWithFloor:Function, isActive:Function, activeIdx:Function }}
+ */
+export function createRowSpinner(list, screen, renderItem, opts = {}) {
+  const isClosed = opts.isClosed ?? (() => false);
+  const now = opts.now ?? (() => Date.now());
+  const intervalMs = opts.intervalMs ?? 80;
+  const minVisibleMs = opts.minVisibleMs ?? 1100;
+  // fullRedraw: force a complete repaint (realloc) instead of a diff render.
+  // Needed for lists containing double-width emoji (the Music tab): blessed's
+  // diff render desyncs the terminal cursor around wide chars during rapid
+  // in-place updates, corrupting rows — even though the internal buffer is
+  // correct. A realloc rewrites the terminal from that correct buffer.
+  const fullRedraw = opts.fullRedraw ?? false;
+  // keepLabel: append the indicator after the row's existing label instead of
+  // replacing it (avoids a perceived "jump" on emoji rows — see previewRowAppend).
+  const keepLabel = opts.keepLabel ?? false;
+  // isStatic: write the indicator ONCE (no animation). Needed for lists with
+  // double-width emoji (the Music tab): repeated in-place mutation of emoji rows
+  // desyncs blessed's terminal output. One write + full-width space padding is
+  // the least-fragile option there. A frozen "♪" stands in for the spinner.
+  const isStatic = opts.static ?? false;
+
+  let timer = null;
+  let floor = null;
+  let frame = 0;
+  let idx = -1;
+  let remote = false;
+  let startTs = 0;
+
+  // full=true forces a complete repaint (realloc) — used ONCE on start and stop
+  // to fix the wide-char cursor desync from the emoji-row→spinner transition (and
+  // stale decorations). Per-frame renders are plain diffs: the spinner row has no
+  // wide chars, so animating it is clean AND doesn't shimmer the whole screen.
+  function _render(full) {
+    if (full && fullRedraw && typeof screen.realloc === 'function') { try { screen.realloc(); } catch { /* ignore */ } }
+    screen.render();
+  }
+
+  function _paint(full) {
+    if (idx < 0) return;
+    // Pad to the widest reliable measure so the row fully overwrites the previous
+    // (longer) content. list.width may still be a percentage string pre-layout, so
+    // fall back to the screen width; over-padding is clipped by the non-wrapping list.
+    const lw = (typeof list.width === 'number' && list.width > 0) ? list.width : 0;
+    const sw = (screen && typeof screen.width === 'number' && screen.width > 0) ? screen.width : 0;
+    const w = Math.max(lw, sw, 80);
+    const spin = isStatic ? '♪' : SPIN_FRAMES[frame++ % SPIN_FRAMES.length];
+    const content = keepLabel
+      ? previewRowAppend(renderItem(idx), spin, remote)
+      : previewRowContent(spin, remote);
+    list.setItem(idx, padTaggedTo(content, w));
+    _render(full);
+  }
+
+  function stop() {
+    if (floor) { clearTimeout(floor); floor = null; }
+    if (timer) { clearInterval(timer); timer = null; }
+    if (idx >= 0 && !isClosed()) {
+      list.setItem(idx, renderItem(idx));
+      _render(true);   // one full repaint to clear the wide-char desync on restore
+    }
+    idx = -1;
+  }
+
+  return {
+    start(rowIdx, isRemote) {
+      stop();
+      idx = rowIdx;
+      frame = 0;
+      remote = !!isRemote;
+      startTs = now();
+      _paint(fullRedraw);   // one repaint (realloc only if fullRedraw) fixes the transition
+      if (isStatic) return; // static indicator: written once, no animation loop
+      timer = setInterval(() => { if (isClosed()) { stop(); return; } _paint(false); }, intervalMs);
+      // A UI spinner must never keep the process alive (blessed's stdin does that
+      // in the real TUI); unref so a leaked spinner can't hang node --test on exit.
+      if (timer.unref) timer.unref();
+    },
+    // Fire-and-forget remote sends exit in ms; keep the row visible ≥ minVisibleMs
+    // so the user still sees a "preview sent" cue, then restore and run `after`.
+    stopWithFloor(after) {
+      if (floor) { clearTimeout(floor); floor = null; }
+      const wait = Math.max(0, minVisibleMs - (now() - startTs));
+      floor = setTimeout(() => { floor = null; stop(); if (!isClosed() && after) after(); }, wait);
+      if (floor.unref) floor.unref();
+    },
+    stop,
+    isActive: () => idx >= 0,
+    activeIdx: () => idx,
+  };
+}