Merge pull request #108 from shinokada/fix/footer-nav

* **New Features**
  * Added global navigation shortcuts: `g` (Top) and `G` (End).
  * New "Import from URL" option.
  * Dedicated help overlay for the "I Feel Lucky" screen; press `?` to toggle it.

* **Documentation**
  * Updated keyboard shortcut listings and in-app help text to include new keys.

* **Refactor**
  * Help text now appears in a bottom-aligned help bar across multiple list and selection views for consistent layout.

Author: shinokada

docs/README.md

@@ -660,6 +660,7 @@ You can edit this file directly or use the Settings menu.
 | Key         | Action        |
 | ----------- | ------------- |
 | `↑↓` / `jk` | Navigate      |
+| `g` / `G`   | Top / End     |
 | `Enter`     | Select / Play |
 | `Esc`       | Back / Stop   |
 | `0`         | Main Menu     |

v3/README.md

@@ -571,6 +571,7 @@ You can edit this file directly or use the Settings menu.
 | Key         | Action        |
 | ----------- | ------------- |
 | `↑↓` / `jk` | Navigate      |
+| `g` / `G`   | Top / End     |
 | `Enter`     | Select / Play |
 | `Esc`       | Back / Stop   |
 | `0`         | Main Menu     |

v3/internal/ui/components/help.go

@@ -287,6 +287,56 @@ func CreateTagsPlayingHelp() []HelpSection {
 	}
 }
 
+// CreateLuckyHelp creates help sections for the I Feel Lucky screen
+func CreateLuckyHelp() []HelpSection {
+	return []HelpSection{
+		{
+			Title: "Input",
+			Items: []HelpItem{
+				{"Tab", "Switch focus (keyword ↔ history)"},
+				{"Enter", "Search / select history"},
+				{"ctrl+t", "Toggle shuffle mode"},
+				{"↑↓/jk", "Navigate history (nav mode)"},
+				{"1-N", "Quick pick history (nav mode)"},
+				{"Esc", "Back to main menu"},
+			},
+		},
+		{
+			Title: "Playback",
+			Items: []HelpItem{
+				{"Space", "Pause / Resume"},
+				{"*", "Volume up (+5%)"},
+				{"/", "Volume down (-5%)"},
+				{"m", "Toggle mute"},
+				{"Esc", "Stop & back to input"},
+				{"0", "Main menu"},
+			},
+		},
+		{
+			Title: "Actions",
+			Items: []HelpItem{
+				{"f", "Save to Quick Favorites"},
+				{"s", "Save to another list"},
+				{"v", "Vote for station"},
+				{"r", "Rate station (1-5)"},
+				{"t", "Add tag"},
+				{"T", "Manage tags"},
+				{"b", "Block station"},
+				{"u", "Undo block (5s)"},
+			},
+		},
+		{
+			Title: "Shuffle",
+			Items: []HelpItem{
+				{"n", "Next station"},
+				{"[", "Previous station"},
+				{"p", "Pause / resume timer"},
+				{"h", "Stop shuffle, keep playing"},
+			},
+		},
+	}
+}
+
 func CreateAppearanceHelp() []HelpSection {
 	return []HelpSection{
 		{

v3/internal/ui/gist.go

@@ -534,41 +534,42 @@ func (m GistModel) View() string {
 		return ""
 	}
 
+	h := m.height
 	switch m.state {
 	case gistStateMenu:
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Gist Management",
 			Subtitle: "Select an Option",
 			Content:  m.menuList.View() + "\n" + m.renderMessage(),
 			Help:     "↑↓/jk: Navigate • Enter: Select • 1-7: Quick select • Esc: Back • Ctrl+C: Quit",
-		})
+		}, h)
 	case gistStateCreateVisibility:
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Create Gist",
 			Subtitle: "Choose Visibility",
 			Content:  m.visibilityMenu.View() + "\n" + m.renderMessage(),
 			Help:     "↑↓/jk: Navigate • Enter: Select • 1-2: Quick select • Esc: Back",
-		})
+		}, h)
 	case gistStateCreateName:
 		visibility := "Secret"
 		if m.createPublic {
 			visibility = "Public"
 		}
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Create Gist",
 			Subtitle: fmt.Sprintf("Enter Gist Name (%s)", visibility),
 			Content:  fmt.Sprintf("Enter a name/description for your gist:\n\n%s", m.textInput.View()) + "\n\n" + m.renderMessage(),
 			Help:     "Enter: Create • Esc: Back",
-		})
+		}, h)
 	case gistStateCreate:
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Create Gist",
 			Subtitle: "Uploading favorites to GitHub",
 			Content:  "Creating gist...\n\nPlease wait while your favorites are uploaded.\n\n" + m.renderMessage(),
 			Help:     "Please wait...",
-		})
+		}, h)
 	case gistStateImportURL:
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Import from URL",
 			Subtitle: "Paste a public gist URL or ID",
 			Content: fmt.Sprintf("Enter a gist URL or ID to import favorites:\n\n"+
@@ -577,7 +578,7 @@ func (m GistModel) View() string {
 				"  • Raw gist ID (e.g., abc123def456...)\n\n"+
 				"%s", m.textInput.View()) + "\n\n" + m.renderMessage(),
 			Help: "Enter: Import • Esc: Back",
-		})
+		}, h)
 	case gistStateList, gistStateUpdate, gistStateDelete, gistStateRecover:
 		action := "My Gists"
 		switch m.state {
@@ -594,26 +595,26 @@ func (m GistModel) View() string {
 			content = "No gists available.\n\nCreate a gist first from the main menu."
 		}
 
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    action,
 			Subtitle: "Select a Gist",
 			Content:  content + "\n" + m.renderMessage(),
 			Help:     "↑↓/jk: Navigate • Enter: Select • Esc: Back",
-		})
+		}, h)
 	case gistStateTokenMenu:
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Token Management",
 			Subtitle: "Manage your GitHub Token",
 			Content:  m.tokenMenuList.View() + "\n" + m.renderMessage(),
 			Help:     "↑↓/jk: Navigate • Enter: Select • 1-4: Quick select • Esc: Back • Ctrl+C: Quit",
-		})
+		}, h)
 	case gistStateTokenSetup:
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Setup Token",
 			Subtitle: "Paste your GitHub Token",
 			Content:  fmt.Sprintf("Token will be hidden for security.\n\n%s", m.textInput.View()) + "\n\n" + m.renderMessage(),
 			Help:     "Enter: Save • Esc: Cancel",
-		})
+		}, h)
 	case gistStateTokenView:
 		masked := gist.GetMaskedToken(m.token)
 		sourceInfo := ""
@@ -634,34 +635,34 @@ func (m GistModel) View() string {
 				}
 			}
 		}
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Current Token",
 			Subtitle: "View Token Status",
 			Content:  fmt.Sprintf("Token: %s%s", masked, sourceInfo) + "\n\n" + m.renderMessage(),
 			Help:     "Enter/Esc: Back",
-		})
+		}, h)
 	case gistStateUpdateInput:
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Update Gist",
 			Subtitle: "Enter new description",
 			Content:  fmt.Sprintf("Current: %s\n\nNew Description:\n%s", m.selectedGist.Description, m.textInput.View()) + "\n\n" + m.renderMessage(),
 			Help:     "Enter: Update • Esc: Cancel",
-		})
+		}, h)
 	case gistStateDeleteConfirm:
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Delete Gist",
 			Subtitle: "Confirm Deletion",
 			Content:  fmt.Sprintf("Are you sure you want to delete this gist?\n%s\n\nType 'yes' to confirm:\n%s", m.selectedGist.Description, m.textInput.View()) + "\n\n" + m.renderMessage(),
 			Help:     "Enter: Confirm • Esc: Cancel",
-		})
+		}, h)
 	case gistStateTokenDelete:
 		masked := gist.GetMaskedToken(m.token)
-		return RenderPage(PageLayout{
+		return RenderPageWithBottomHelp(PageLayout{
 			Title:    "Delete Token",
 			Subtitle: "⚠️  WARNING",
 			Content:  fmt.Sprintf("This will delete your stored GitHub token!\n\nToken: %s\n\nYou won't be able to use Gist features until you set up a new token.\n\nType 'yes' to confirm deletion:\n%s", masked, m.textInput.View()) + "\n\n" + m.renderMessage(),
 			Help:     "Enter: Confirm • Esc: Cancel",
-		})
+		}, h)
 	}
 
 	return ""

v3/internal/ui/lucky.go

@@ -36,6 +36,13 @@ const (
 	luckyStateManageTags
 )
 
+// Footer help text constants for the I Feel Lucky screen
+const (
+	luckyHelpInputFooter   = "Tab: Switch focus • Enter: Search • ctrl+t: Shuffle • Esc: Back • ?: Help"
+	luckyHelpPlayingFooter = "Space: Pause • f: Fav • s: List • 0: Main Menu • ?: Help"
+	luckyHelpShuffleFooter = "Space: Pause • n: Next • [: Prev • f: Fav • h: Stop shuffle • 0: Main Menu • ?: Help"
+)
+
 // LuckyModel represents the I Feel Lucky screen
 type LuckyModel struct {
 	state           luckyState
@@ -162,7 +169,7 @@ func NewLuckyModel(apiClient *api.Client, favoritePath string, blocklistManager
 		searchHistory:    history,
 		width:            80,
 		height:           24,
-		helpModel:        components.NewHelpModel(components.CreatePlayingHelp()),
+		helpModel:        components.NewHelpModel(components.CreateLuckyHelp()),
 		votedStations:    votedStations,
 		shuffleEnabled:   false,
 		shuffleConfig:    shuffleConfig,
@@ -538,6 +545,13 @@ func (m LuckyModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 func (m LuckyModel) updateInput(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	key := msg.String()
 
+	// Handle '?' for help overlay
+	if key == "?" {
+		m.helpModel.SetSize(m.width, m.height)
+		m.helpModel.Toggle()
+		return m, nil
+	}
+
 	// Handle escape - return to main menu
 	if key == "esc" {
 		m.numberBuffer = "" // Clear buffer
@@ -1291,15 +1305,7 @@ func (m LuckyModel) viewInput() string {
 		}
 	}
 
-	helpText := "Tab: Switch focus • Enter: Search • ctrl+t: Toggle shuffle"
-	if m.searchHistory != nil && len(m.searchHistory.LuckyQueries) > 0 {
-		maxItems := len(m.searchHistory.LuckyQueries)
-		if maxItems > m.searchHistory.MaxSize {
-			maxItems = m.searchHistory.MaxSize
-		}
-		helpText += fmt.Sprintf(" • 1-%d: Quick pick (nav mode)", maxItems)
-	}
-	helpText += " • ↑↓: History (nav mode) • Esc: Back"
+	helpText := luckyHelpInputFooter
 
 	return RenderPageWithBottomHelp(PageLayout{
 		Content: content.String(),
@@ -1405,7 +1411,7 @@ func (m LuckyModel) viewPlaying() string {
 		content.WriteString(msgStyle.Render(m.saveMessage))
 	}
 
-	helpText := "Space: Pause • f: Fav • s: List • v: Vote • b: Block • r: Rate • 0: Main Menu • ?: Help"
+	helpText := luckyHelpPlayingFooter
 	return RenderPageWithBottomHelp(PageLayout{
 		Title:   "🎵 Now Playing",
 		Content: content.String(),
@@ -1942,7 +1948,7 @@ func (m LuckyModel) viewShufflePlaying() string {
 	}
 
 	title := fmt.Sprintf("🎵 Now Playing (🔀 Shuffle: %s)", m.lastSearchKeyword)
-	help := "Space: Pause • n: Next • [: Prev • f: Fav • b: Block • p: Pause timer • h: Stop shuffle • 0: Main Menu • ?: Help"
+	help := luckyHelpShuffleFooter
 
 	return RenderPageWithBottomHelp(PageLayout{
 		Title:   title,

v3/internal/ui/most_played.go

@@ -357,6 +357,7 @@ func (m MostPlayedModel) handleListInput(msg tea.KeyMsg) (MostPlayedModel, tea.C
 		return m, func() tea.Msg { return navigateMsg{screen: screenMainMenu} }
 
 	case "?":
+		m.helpModel.SetSize(m.width, m.height)
 		m.helpModel.Show()
 		return m, nil
 
@@ -694,11 +695,11 @@ func (m MostPlayedModel) viewList() string {
 		}
 	}
 
-	return RenderPage(PageLayout{
+	return RenderPageWithBottomHelp(PageLayout{
 		Title:   "📊 Most Played Stations",
 		Content: content.String(),
-		Help:    "↑↓/jk: Navigate • Enter: Play • s: Sort • f: Fav • ?: Help • Esc: Back",
-	})
+		Help:    "↑↓/jk: Navigate • g/G: Top/End • Enter: Play • s: Sort • f: Fav • ?: Help • Esc: Back",
+	}, m.height)
 }
 
 func (m MostPlayedModel) viewPlaying() string {
@@ -800,11 +801,11 @@ func (m MostPlayedModel) viewSavePrompt() string {
 	content.WriteString("[L] Choose from list\n")
 	content.WriteString("[N] Cancel")
 
-	return RenderPage(PageLayout{
+	return RenderPageWithBottomHelp(PageLayout{
 		Title:   "💾 Save Station",
 		Content: content.String(),
 		Help:    "Y: My-favorites • L: Choose list • N: Cancel",
-	})
+	}, m.height)
 }
 
 func (m MostPlayedModel) viewSelectList() string {
@@ -813,9 +814,9 @@ func (m MostPlayedModel) viewSelectList() string {
 	content.WriteString("Select a list:\n\n")
 	content.WriteString(m.listModel.View())
 
-	return RenderPage(PageLayout{
+	return RenderPageWithBottomHelp(PageLayout{
 		Title:   "📁 Select List",
 		Content: content.String(),
 		Help:    "↑↓: Navigate • Enter: Select • Esc: Cancel",
-	})
+	}, m.height)
 }

v3/internal/ui/play.go

@@ -1245,13 +1245,13 @@ func (m PlayModel) viewListSelection() string {
 		content.WriteString(style.Render(m.saveMessage))
 	}
 
-	// Use the consistent page template
-	return RenderPage(PageLayout{
+	// Use the consistent page template with bottom-aligned help
+	return RenderPageWithBottomHelp(PageLayout{
 		Title:    "Play from Favorites",
 		Subtitle: "Select a Favorite List",
 		Content:  content.String(),
-		Help:     "↑↓/jk: Navigate • Enter: Select • Esc: Back • Ctrl+C: Quit",
-	})
+		Help:     "↑↓/jk: Navigate • g/G: Top/End • Enter: Select • Esc: Back • Ctrl+C: Quit",
+	}, m.height)
 }
 
 // viewPlaying renders the playback view
@@ -1424,12 +1424,12 @@ func (m PlayModel) viewStationSelection() string {
 		content.WriteString(style.Render(m.saveMessage))
 	}
 
-	// Use the consistent page template
-	return RenderPage(PageLayout{
+	// Use the consistent page template with bottom-aligned help
+	return RenderPageWithBottomHelp(PageLayout{
 		Title:   "Play from Favorites",
 		Content: content.String(),
-		Help:    "↑↓/jk: Navigate • /: Filter • Enter: Play • d: Delete • Esc: Back • 0: Main Menu • Ctrl+C: Quit",
-	})
+		Help:    "↑↓/jk: Navigate • g/G: Top/End • /: Filter • Enter: Play • d: Delete • Esc: Back • 0: Main Menu • Ctrl+C: Quit",
+	}, m.height)
 }
 
 // noStationsView renders the view when a list is empty