From 83fffe2087ce9646641e4de5f5738bde90cf7e9a Mon Sep 17 00:00:00 2001
From: mignot <garcia.andreas.1991@gmail.com>
Date: Mon, 26 Oct 2026 16:11:30 +0100
Subject: [PATCH 1/5] docs: align song/track/recording wording with domain
 glossary

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 packages/app-kit/src/genre-tree/api/library/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/app-kit/src/genre-tree/api/library/index.ts b/packages/app-kit/src/genre-tree/api/library/index.ts
index 7c73181..6389ea7 100644
--- a/packages/app-kit/src/genre-tree/api/library/index.ts
+++ b/packages/app-kit/src/genre-tree/api/library/index.ts
@@ -1,5 +1,5 @@
 /**
- * "reference" (community genre tree, grow-the-music-tree-api) tracks are MusicBrainz recordings,
+ * "reference" (community genre tree, grow-the-music-tree-api) tracks are songs (keyed on a representative MusicBrainz recording id),
  * played via embedded YouTube when a video is linked, so they get a "recordings" endpoint group
  * (list/detail/delete only). Other scopes/track kinds are injected by consumers via
  * `TrackListProvider`'s `listEndpoint`/`listQueryKey` props rather than defined here.

From b986ffe7d18b837a93aca768e7b406b79a13296b Mon Sep 17 00:00:00 2001
From: mignot <garcia.andreas.1991@gmail.com>
Date: Mon, 26 Oct 2026 16:32:27 +0100
Subject: [PATCH 2/5] feat(genre-tree): Google Maps-style action band and
 previous button in the search field

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  9 ++
 .../src/genre-tree/GenreActionBand.tsx        | 92 +++++++++++++++++++
 .../src/genre-tree/GenreSearch.test.tsx       | 23 -----
 .../app-kit-ui/src/genre-tree/GenreSearch.tsx | 65 +++++--------
 .../src/genre-tree/GenreTreeView.tsx          | 49 ++++++++--
 5 files changed, 161 insertions(+), 77 deletions(-)
 create mode 100644 packages/app-kit-ui/src/genre-tree/GenreActionBand.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a37fde6..8510f90 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,15 @@ easy to spot when bumping.
 
 ## [Unreleased]
 
+### Added
+
+- `GenreTreeView` (wheel, pop-core): genre-tree-view's "Previous" button now sits inside the search field, left of the genre name, and fades in sliding from the left; the field's left padding widens to make room.
+- `GenreActionBand`: Google Maps-style band under the detail panel header (icon over label) holding Play/Pause, Focus and the `additionalActions`.
+
+### Breaking
+
+- `GenreSearch`: `onZoomIn`, `onPlayPause` and `isPlaying` are removed; those actions moved to the detail panel's action band. The search icon now sits right of the field's text, left of the clear button.
+
 ## [13.5.0] - 2026-10-26
 
 ### Added
diff --git a/packages/app-kit-ui/src/genre-tree/GenreActionBand.tsx b/packages/app-kit-ui/src/genre-tree/GenreActionBand.tsx
new file mode 100644
index 0000000..26fb577
--- /dev/null
+++ b/packages/app-kit-ui/src/genre-tree/GenreActionBand.tsx
@@ -0,0 +1,92 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { Pause, Play, Plus, ZoomIn } from "lucide-react";
+import type {
+  GenreTreeAction,
+  GenreTreeNode,
+} from "@behindthemusictree/genre-tree-view";
+
+export type GenreActionBandProps = {
+  node: GenreTreeNode;
+  /** When set, shows the Play/Pause action. */
+  onPlayPause?: () => void;
+  isPlaying?: boolean;
+  /** When set, shows the "Zoom in" action. */
+  onZoomIn?: () => void;
+  /** When set, shows the "Add" (sub-genre) action. */
+  onAddChild?: () => void;
+  /** Only `placement: "primary"` actions show here; the rest stay in the panel's overflow menu. */
+  additionalActions?: (node: GenreTreeNode) => GenreTreeAction[];
+};
+
+type BandItem = {
+  key: string;
+  label: string;
+  icon: ReactNode;
+  onClick: (event: React.MouseEvent) => void;
+  disabled?: boolean;
+};
+
+export default function GenreActionBand({
+  node,
+  onPlayPause,
+  isPlaying = false,
+  onZoomIn,
+  onAddChild,
+  additionalActions,
+}: GenreActionBandProps) {
+  const items: BandItem[] = [];
+  if (onPlayPause) {
+    items.push({
+      key: "play-pause",
+      label: isPlaying ? "Pause" : "Play",
+      icon: isPlaying ? (
+        <Pause aria-hidden="true" className="w-5 h-5" />
+      ) : (
+        <Play aria-hidden="true" className="w-5 h-5" />
+      ),
+      onClick: onPlayPause,
+    });
+  }
+  if (onZoomIn) {
+    items.push({
+      key: "zoom-in",
+      label: "Focus",
+      icon: <ZoomIn aria-hidden="true" className="w-5 h-5" />,
+      onClick: onZoomIn,
+    });
+  }
+  if (onAddChild) {
+    items.push({ key: "add-child", label: "Add", icon: <Plus aria-hidden="true" className="w-5 h-5" />, onClick: onAddChild });
+  }
+  for (const action of (additionalActions?.(node) ?? []).filter((action) => action.placement === "primary")) {
+    items.push({
+      key: action.key,
+      label: action.label(node),
+      icon: action.icon(node),
+      onClick: (event) => action.onClick(event, node),
+      disabled: action.enabled ? !action.enabled(node) : false,
+    });
+  }
+  if (items.length === 0) return null;
+
+  return (
+    <div className="genre-action-band flex gap-1 px-2 py-3 overflow-x-auto border-b border-[var(--color-neutral-200)]">
+      {items.map((item) => (
+        <button
+          key={item.key}
+          type="button"
+          disabled={item.disabled}
+          onClick={item.onClick}
+          className="group flex flex-col items-center gap-1 w-16 shrink-0 text-xs text-center text-[var(--color-text)] bg-transparent disabled:opacity-50"
+        >
+          <span className="flex items-center justify-center w-10 h-10 rounded-full bg-[var(--color-neutral-100)] transition-colors group-hover:bg-[var(--color-neutral-200)] group-disabled:group-hover:bg-[var(--color-neutral-100)]">
+            {item.icon}
+          </span>
+          {item.label}
+        </button>
+      ))}
+    </div>
+  );
+}
diff --git a/packages/app-kit-ui/src/genre-tree/GenreSearch.test.tsx b/packages/app-kit-ui/src/genre-tree/GenreSearch.test.tsx
index b552e57..efc5e26 100644
--- a/packages/app-kit-ui/src/genre-tree/GenreSearch.test.tsx
+++ b/packages/app-kit-ui/src/genre-tree/GenreSearch.test.tsx
@@ -95,27 +95,4 @@ describe("GenreSearch", () => {
     expect(onClear).toHaveBeenCalledTimes(1);
     expect(screen.getByLabelText("Search a genre")).toHaveValue("");
   });
-
-  it("shows Zoom in only when onZoomIn is given, and fires it", () => {
-    const onZoomIn = vi.fn();
-    const { rerender } = render(<GenreSearch genrePlaylists={genrePlaylists} onSelect={vi.fn()} />);
-    expect(screen.queryByRole("button", { name: "Zoom in" })).not.toBeInTheDocument();
-
-    rerender(<GenreSearch genrePlaylists={genrePlaylists} onSelect={vi.fn()} onZoomIn={onZoomIn} />);
-    fireEvent.click(screen.getByRole("button", { name: "Zoom in" }));
-
-    expect(onZoomIn).toHaveBeenCalledOnce();
-  });
-
-  it("shows Play or Pause per isPlaying when onPlayPause is given, and fires it", () => {
-    const onPlayPause = vi.fn();
-    const { rerender } = render(
-      <GenreSearch genrePlaylists={genrePlaylists} onSelect={vi.fn()} onPlayPause={onPlayPause} />,
-    );
-    fireEvent.click(screen.getByRole("button", { name: "Play" }));
-    expect(onPlayPause).toHaveBeenCalledOnce();
-
-    rerender(<GenreSearch genrePlaylists={genrePlaylists} onSelect={vi.fn()} onPlayPause={onPlayPause} isPlaying />);
-    expect(screen.getByRole("button", { name: "Pause" })).toBeInTheDocument();
-  });
 });
diff --git a/packages/app-kit-ui/src/genre-tree/GenreSearch.tsx b/packages/app-kit-ui/src/genre-tree/GenreSearch.tsx
index 543d130..55633f0 100644
--- a/packages/app-kit-ui/src/genre-tree/GenreSearch.tsx
+++ b/packages/app-kit-ui/src/genre-tree/GenreSearch.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Pause, Play, Search, X, ZoomIn } from "lucide-react";
+import { ArrowLeft, Search, X } from "lucide-react";
 import { Input } from "@behindthemusictree/ui";
 
 import { CriteriaPlaylistSimple, useGenreSearch } from "@behindthemusictree/app-kit/genre-tree";
@@ -10,13 +10,10 @@ export type GenreSearchProps = {
   onSelect: (genrePlaylist: CriteriaPlaylistSimple) => void;
   /** Name of the currently selected genre; fills the input whenever it changes. */
   selectedName?: string | null;
+  /** When set, renders a "Previous" button left of the text; shown only when the host's CSS reveals `.genre-search-previous`. */
+  onPrevious?: () => void;
   /** Called by the clear button, after it empties the input. */
   onClear?: () => void;
-  /** When set, shows a "Zoom in" button that fires it. */
-  onZoomIn?: () => void;
-  /** When set, shows a Play/Pause button at the right end of the field that fires it. */
-  onPlayPause?: () => void;
-  isPlaying?: boolean;
   placeholder?: string;
 };
 
@@ -25,9 +22,7 @@ export default function GenreSearch({
   onSelect,
   selectedName = null,
   onClear,
-  onZoomIn,
-  onPlayPause,
-  isPlaying = false,
+  onPrevious,
   placeholder = "Search a genre…",
 }: GenreSearchProps) {
   const { query, setQuery, results, canClear, clear, select } = useGenreSearch({
@@ -39,31 +34,29 @@ export default function GenreSearch({
 
   return (
     <div className="genre-search relative w-[264px] shrink-0">
-      <Search
-        aria-hidden="true"
-        className="absolute left-3 top-1/2 w-4 h-4 text-[var(--color-neutral-500)] -translate-y-1/2 pointer-events-none"
-      />
+      {onPrevious && (
+        <button
+          type="button"
+          aria-label="Previous"
+          title="Previous"
+          className="genre-search-previous absolute left-2 top-1/2 z-10 hidden p-1.5 text-[var(--color-neutral-500)] bg-transparent rounded-full -translate-y-1/2 hover:bg-[var(--color-neutral-100)] hover:text-[var(--color-text)]"
+          onClick={onPrevious}
+        >
+          <ArrowLeft aria-hidden="true" className="w-4 h-4" />
+        </button>
+      )}
       <Input
         type="text"
         value={query}
         onChange={(event) => setQuery(event.target.value)}
         placeholder={placeholder}
         aria-label="Search a genre"
-        className={`pl-9 ${onPlayPause ? (onZoomIn ? "pr-24" : "pr-16") : onZoomIn ? "pr-16" : "pr-9"} bg-white border-[var(--color-neutral-200)] rounded-full shadow-md`}
+        className="pl-4 pr-16 transition-[padding] duration-200 ease-out motion-reduce:transition-none bg-white border-[var(--color-neutral-200)] rounded-full shadow-md"
       />
-      {(onZoomIn || onPlayPause || canClear) && (
-        <div className="absolute right-2 top-1/2 flex items-center -translate-y-1/2">
-          {onZoomIn && (
-            <button
-              type="button"
-              aria-label="Zoom in"
-              title="Zoom in"
-              className="p-1 text-[var(--color-neutral-500)] bg-transparent rounded-full hover:bg-[var(--color-neutral-100)] hover:text-[var(--color-text)]"
-              onClick={onZoomIn}
-            >
-              <ZoomIn aria-hidden="true" className="w-4 h-4" />
-            </button>
-          )}
+      <div className="absolute right-2 top-1/2 flex items-center -translate-y-1/2">
+          <span className="p-1 text-[var(--color-neutral-500)] pointer-events-none">
+            <Search aria-hidden="true" className="w-4 h-4" />
+          </span>
           {canClear && (
             <button
               type="button"
@@ -74,23 +67,7 @@ export default function GenreSearch({
               <X aria-hidden="true" className="w-4 h-4" />
             </button>
           )}
-          {onPlayPause && (
-            <button
-              type="button"
-              aria-label={isPlaying ? "Pause" : "Play"}
-              title={isPlaying ? "Pause" : "Play"}
-              className="p-1 text-[var(--color-neutral-500)] bg-transparent rounded-full hover:bg-[var(--color-neutral-100)] hover:text-[var(--color-text)]"
-              onClick={onPlayPause}
-            >
-              {isPlaying ? (
-                <Pause aria-hidden="true" className="w-4 h-4" />
-              ) : (
-                <Play aria-hidden="true" className="w-4 h-4" />
-              )}
-            </button>
-          )}
-        </div>
-      )}
+      </div>
       {results.length > 0 && (
         <ul className="genre-search-results absolute z-40 w-full max-h-64 mt-1 overflow-y-auto bg-white border border-[var(--color-neutral-200)] rounded-xl shadow-md">
           {results.map((genrePlaylist) => (
diff --git a/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx b/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx
index b7380e5..0d1c1fa 100644
--- a/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx
+++ b/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, type ReactNode } from "react";
+import { useCallback, useRef, type ReactNode } from "react";
 import { z } from "zod";
 import { Plus } from "lucide-react";
 import { IconTextButton, Button } from "@behindthemusictree/ui";
@@ -31,6 +31,20 @@ import GenrePlaylistTreeWheel from "./playlist-tree/TreeWheel";
 import GenrePlaylistTreeWheelRadialPopCore, { type GenreFocusProps } from "./playlist-tree/TreeWheelRadialPopCore";
 import { GenreTreeWheelHandoff } from "./GenreTreeWheelHandoff";
 import GenreSearch from "./GenreSearch";
+import GenreActionBand from "./GenreActionBand";
+
+// genre-tree-view's "previous" button (back to the last selected genre) renders inside the info panel, which sits
+// under the floating search bar. It is hidden and its click is proxied by the search field's own button, which
+// appears (fading in, sliding from the left) whenever the original exists; the field makes room for it.
+const PREVIOUS_BUTTON_CSS = `
+.genre-tree-view .search-overlay .gtv-info-panel-previous { display: none; }
+.genre-tree-view:has(.search-overlay .gtv-info-panel-previous) .genre-search input { padding-left: 44px; }
+.genre-tree-view:has(.search-overlay .gtv-info-panel-previous) .genre-search-previous { display: flex; }
+@keyframes genre-tree-view-previous-in { from { opacity: 0; transform: translate(-8px, -50%); } to { opacity: 1; transform: translate(0, -50%); } }
+@media (prefers-reduced-motion: no-preference) {
+  .genre-search-previous { animation: genre-tree-view-previous-in 200ms ease-out; }
+}
+`;
 
 export type {
   ControlsOrientation,
@@ -149,6 +163,11 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
     criteriaOverviewSchema,
   });
 
+  const rootRef = useRef<HTMLDivElement>(null);
+  const handlePrevious = () => {
+    rootRef.current?.querySelector<HTMLButtonElement>(".search-overlay .gtv-info-panel-previous")?.click();
+  };
+
   const handleSelectedNodeChange = selectNode;
   const handleGenreSearchClear = clearSelection;
   const handleGenreSearchSelect = selectGenrePlaylist;
@@ -198,6 +217,15 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
       const genreUuid = genrePlaylist?.criteria?.uuid;
       if (!genrePlaylist || !genreUuid) return null;
       return (
+        <>
+          <GenreActionBand
+            node={node}
+            onPlayPause={canPlay ? handleGenreSearchPlayPause : undefined}
+            isPlaying={isSelectedPlaying}
+            onZoomIn={canZoomIn ? handleGenreSearchZoomIn : undefined}
+            onAddChild={readOnly ? undefined : () => handleGenreCreationAction(genrePlaylist.criteria ?? null)}
+            additionalActions={additionalActions}
+          />
         <GenreDetailExtras<O>
           key={genreUuid}
           genreUuid={genreUuid}
@@ -213,9 +241,11 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
           renderRecordingActions={renderRecordingActions}
           renderTracksToolbar={renderTracksToolbar}
         />
+        </>
       );
     },
-    [genrePlaylistByNodeId, scope, getBackendBaseUrl, criteriaOverviewSchema,
+    [genrePlaylistByNodeId, canPlay, isSelectedPlaying, canZoomIn, additionalActions, readOnly, handleGenreCreationAction,
+      handleGenreSearchPlayPause, handleGenreSearchZoomIn, scope, getBackendBaseUrl, criteriaOverviewSchema,
       renderGenreDetailExtras,
       renderArtistLink,
       renderSummary,
@@ -237,9 +267,7 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
           onSelect={handleGenreSearchSelect}
           selectedName={selectedGenrePlaylist?.name ?? null}
           onClear={handleGenreSearchClear}
-          onZoomIn={canZoomIn ? handleGenreSearchZoomIn : undefined}
-          onPlayPause={canPlay ? handleGenreSearchPlayPause : undefined}
-          isPlaying={isSelectedPlaying}
+          onPrevious={handlePrevious}
         />
       )}
       {!isLoading && !isControlled && (
@@ -318,7 +346,8 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
   );
 
   return (
-    <div className={["relative flex flex-col h-full", className].filter(Boolean).join(" ")}>
+    <div ref={rootRef} className={["genre-tree-view relative flex flex-col h-full", className].filter(Boolean).join(" ")}>
+      <style>{PREVIOUS_BUTTON_CSS}</style>
       <div className="actions-container absolute left-5 top-5 z-30 flex items-center gap-2">
         {actions}
       </div>
@@ -331,7 +360,7 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
             // the header inset (10px padding + 38px = the search bar's bottom edge) extends its fill behind the search bar,
             // Google Maps style; the 8px bottom padding mirrors the 8px above the bar, and the hidden title's height is zeroed.
             // The panel's own Zoom in button is hidden: the search bar carries it.
-            <div className="tree-container relative flex-1 w-full min-h-0 [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:38px] [&_.gtv-info-panel-header]:pb-2 [&_.gtv-info-panel-title--hidden]:h-0 [&_.gtv-toolbar>.gtv-toolbar-btn:first-child]:hidden">
+            <div className="tree-container search-overlay relative flex-1 w-full min-h-0 [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:38px] [&_.gtv-info-panel-header]:pb-2 [&_.gtv-info-panel-title--hidden]:h-0 [&_.gtv-toolbar>.gtv-toolbar-btn]:hidden">
               <GenreTreeWheelHandoff skeleton={<GenreTreeWheelSkeleton />}>
                 <GenrePlaylistTreeWheel
                   scope={scope}
@@ -358,7 +387,7 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
           ) : viewMode === "pop-core" ? (
             // The info panel's top edge aligns with the tree's, 8px above the h-10 search bar at top-5;
             // the header inset (8px + 40px + 4px) extends its fill behind the search bar, Google Maps style.
-            <div className="tree-container relative flex-1 w-full min-h-0 [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:38px] [&_.gtv-info-panel-header]:pb-2 [&_.gtv-info-panel-title--hidden]:h-0 [&_.gtv-toolbar>.gtv-toolbar-btn:first-child]:hidden [&_.gtv-info-panel-zoom-in]:hidden">
+            <div className="tree-container search-overlay relative flex-1 w-full min-h-0 [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:38px] [&_.gtv-info-panel-header]:pb-2 [&_.gtv-info-panel-title--hidden]:h-0 [&_.gtv-toolbar>.gtv-toolbar-btn]:hidden [&_.gtv-info-panel-zoom-in]:hidden">
               <GenreTreeWheelHandoff skeleton={<GenreTreeWheelSkeleton />}>
                 <GenrePlaylistTreeWheelRadialPopCore
                   scope={scope}
@@ -384,7 +413,7 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
               </GenreTreeWheelHandoff>
             </div>
           ) : viewMode === "outline" ? (
-            <div className="tree-container flex-1 min-h-0 w-full overflow-y-auto relative [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:52px]">
+            <div className="tree-container flex-1 min-h-0 w-full overflow-y-auto relative [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:52px] [&_.gtv-toolbar>.gtv-toolbar-btn]:hidden">
               <GenrePlaylistTreeWheelRadialPopCore
                 outline
                 scope={scope}
@@ -406,7 +435,7 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
               />
             </div>
           ) : (
-            <div className="tree-container relative flex flex-col gap-4 w-full pt-14 overflow-x-auto overflow-y-auto text-[var(--color-text)]">
+            <div className="tree-container relative flex flex-col gap-4 w-full pt-14 overflow-x-auto overflow-y-auto text-[var(--color-text)] [&_.gtv-toolbar>.gtv-toolbar-btn]:hidden">
               {Object.entries(groupedGenrePlaylistsByRoot).map(
                 ([uuid, genrePlaylistTreePerRoot], rootIndex) => {
                   return (

From 4badb3253675978b5854de4b3ee1f03ea4a7010c Mon Sep 17 00:00:00 2001
From: mignot <garcia.andreas.1991@gmail.com>
Date: Mon, 26 Oct 2026 17:06:24 +0100
Subject: [PATCH 3/5] feat(genre-tree): move all node actions into the action
 band, directly under the header

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 +-
 .../src/genre-tree/GenreActionBand.test.tsx   | 51 +++++++++++
 .../src/genre-tree/GenreActionBand.tsx        | 17 +++-
 .../src/genre-tree/GenreTreeView.test.tsx     | 62 ++++++++++++-
 .../src/genre-tree/GenreTreeView.tsx          | 86 +++++++++++--------
 5 files changed, 174 insertions(+), 44 deletions(-)
 create mode 100644 packages/app-kit-ui/src/genre-tree/GenreActionBand.test.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8510f90..10f9c15 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,7 +14,7 @@ easy to spot when bumping.
 ### Added
 
 - `GenreTreeView` (wheel, pop-core): genre-tree-view's "Previous" button now sits inside the search field, left of the genre name, and fades in sliding from the left; the field's left padding widens to make room.
-- `GenreActionBand`: Google Maps-style band under the detail panel header (icon over label) holding Play/Pause, Focus and the `additionalActions`.
+- `GenreActionBand`: Google Maps-style band under the detail panel header (icon over label) holding Play/Pause, Focus, Add, Rename, Parent and the `additionalActions`; genre-tree-view's own toolbar and its ⋮ menu are hidden.
 
 ### Breaking
 
diff --git a/packages/app-kit-ui/src/genre-tree/GenreActionBand.test.tsx b/packages/app-kit-ui/src/genre-tree/GenreActionBand.test.tsx
new file mode 100644
index 0000000..28ed2ae
--- /dev/null
+++ b/packages/app-kit-ui/src/genre-tree/GenreActionBand.test.tsx
@@ -0,0 +1,51 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import type { GenreTreeAction, GenreTreeNode } from "@behindthemusictree/genre-tree-view";
+import GenreActionBand from "./GenreActionBand";
+
+const node = { id: "gp1" } as GenreTreeNode;
+
+describe("GenreActionBand", () => {
+  it("renders nothing when no action applies", () => {
+    const { container } = render(<GenreActionBand node={node} />);
+
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders each provided action and wires its click", () => {
+    const handlers = {
+      onPlayPause: vi.fn(),
+      onZoomIn: vi.fn(),
+      onAddChild: vi.fn(),
+      onRename: vi.fn(),
+      onChangeParent: vi.fn(),
+    };
+    render(<GenreActionBand node={node} {...handlers} />);
+
+    for (const name of ["Play", "Focus", "Add", "Rename", "Parent"]) {
+      fireEvent.click(screen.getByRole("button", { name }));
+    }
+
+    for (const handler of Object.values(handlers)) expect(handler).toHaveBeenCalledOnce();
+  });
+
+  it("labels the play action Pause while playing", () => {
+    render(<GenreActionBand node={node} onPlayPause={vi.fn()} isPlaying />);
+
+    expect(screen.getByRole("button", { name: "Pause" })).toBeInTheDocument();
+  });
+
+  it("renders additional actions and disables those that are not enabled", () => {
+    const onClick = vi.fn();
+    const actions: GenreTreeAction[] = [
+      { key: "a", label: () => "Merge", icon: () => <span />, onClick },
+      { key: "b", label: () => "Locked", icon: () => <span />, onClick, enabled: () => false },
+    ];
+    render(<GenreActionBand node={node} additionalActions={() => actions} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Merge" }));
+
+    expect(onClick).toHaveBeenCalledWith(expect.anything(), node);
+    expect(screen.getByRole("button", { name: "Locked" })).toBeDisabled();
+  });
+});
diff --git a/packages/app-kit-ui/src/genre-tree/GenreActionBand.tsx b/packages/app-kit-ui/src/genre-tree/GenreActionBand.tsx
index 26fb577..2572586 100644
--- a/packages/app-kit-ui/src/genre-tree/GenreActionBand.tsx
+++ b/packages/app-kit-ui/src/genre-tree/GenreActionBand.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import type { ReactNode } from "react";
-import { Pause, Play, Plus, ZoomIn } from "lucide-react";
+import { MoveUpRight, Pause, Pencil, Play, Plus, ZoomIn } from "lucide-react";
 import type {
   GenreTreeAction,
   GenreTreeNode,
@@ -16,7 +16,10 @@ export type GenreActionBandProps = {
   onZoomIn?: () => void;
   /** When set, shows the "Add" (sub-genre) action. */
   onAddChild?: () => void;
-  /** Only `placement: "primary"` actions show here; the rest stay in the panel's overflow menu. */
+  /** When set, shows the "Rename" action. */
+  onRename?: () => void;
+  /** When set, shows the "Parent" (change parent) action. */
+  onChangeParent?: () => void;
   additionalActions?: (node: GenreTreeNode) => GenreTreeAction[];
 };
 
@@ -34,6 +37,8 @@ export default function GenreActionBand({
   isPlaying = false,
   onZoomIn,
   onAddChild,
+  onRename,
+  onChangeParent,
   additionalActions,
 }: GenreActionBandProps) {
   const items: BandItem[] = [];
@@ -60,7 +65,13 @@ export default function GenreActionBand({
   if (onAddChild) {
     items.push({ key: "add-child", label: "Add", icon: <Plus aria-hidden="true" className="w-5 h-5" />, onClick: onAddChild });
   }
-  for (const action of (additionalActions?.(node) ?? []).filter((action) => action.placement === "primary")) {
+  if (onRename) {
+    items.push({ key: "rename", label: "Rename", icon: <Pencil aria-hidden="true" className="w-5 h-5" />, onClick: onRename });
+  }
+  if (onChangeParent) {
+    items.push({ key: "change-parent", label: "Parent", icon: <MoveUpRight aria-hidden="true" className="w-5 h-5" />, onClick: onChangeParent });
+  }
+  for (const action of additionalActions?.(node) ?? []) {
     items.push({
       key: action.key,
       label: action.label(node),
diff --git a/packages/app-kit-ui/src/genre-tree/GenreTreeView.test.tsx b/packages/app-kit-ui/src/genre-tree/GenreTreeView.test.tsx
index a0fccf1..8f6c163 100644
--- a/packages/app-kit-ui/src/genre-tree/GenreTreeView.test.tsx
+++ b/packages/app-kit-ui/src/genre-tree/GenreTreeView.test.tsx
@@ -1221,15 +1221,20 @@ describe("GenreTreeView", () => {
       expect(treeWheelPropsMock.mock.calls.at(-1)?.[0].selectedNodeId).toBeNull();
     });
 
-    it("plays the selected genre from the search bar's Play button", () => {
+    function openBand(id: string) {
+      const output = treeWheelPropsMock.mock.calls.at(-1)?.[0].renderExtraDetails({ id });
+      render(<>{output}</>);
+    }
+
+    it("plays the selected genre from the action band's Play button", () => {
       const jazz = makePlaylist({ uuid: "gp1", name: "Jazz", criteria: { uuid: "c1", name: "Jazz" } });
       useListFullGenrePlaylistsMock.mockReturnValue({ data: [jazz], isPending: false });
       renderView();
       fireEvent.click(screen.getByRole("button", { name: "Wheel" }));
-      expect(screen.queryByRole("button", { name: "Play" })).not.toBeInTheDocument();
 
       fireEvent.change(screen.getByRole("textbox", { name: "Search a genre" }), { target: { value: "Ja" } });
       fireEvent.click(screen.getByRole("button", { name: "Jazz" }));
+      openBand("gp1");
       fireEvent.click(screen.getByRole("button", { name: "Play" }));
 
       expect(playNewTrackListFromGenrePlaylistMock).toHaveBeenCalledWith(jazz, "me");
@@ -1244,6 +1249,7 @@ describe("GenreTreeView", () => {
 
       fireEvent.change(screen.getByRole("textbox", { name: "Search a genre" }), { target: { value: "Ja" } });
       fireEvent.click(screen.getByRole("button", { name: "Jazz" }));
+      openBand("gp1");
       fireEvent.click(screen.getByRole("button", { name: "Play" }));
 
       expect(setIsPlayingMock).toHaveBeenCalledWith(true);
@@ -1262,13 +1268,14 @@ describe("GenreTreeView", () => {
 
       fireEvent.change(screen.getByRole("textbox", { name: "Search a genre" }), { target: { value: "Ja" } });
       fireEvent.click(screen.getByRole("button", { name: "Jazz" }));
+      openBand("gp1");
       fireEvent.click(screen.getByRole("button", { name: "Play" }));
 
       await waitFor(() => expect(errorSpy).toHaveBeenCalledWith("Failed to load genre playlist tracks:", failure));
       errorSpy.mockRestore();
     });
 
-    it("zooms from the search bar in pop-core when the selected genre has children", () => {
+    it("zooms from the action band in pop-core when the selected genre has children", () => {
       const parent = makePlaylist({ uuid: "gp1", name: "Mainstream Pop", root: { uuid: "gp1" }, criteria: { uuid: "c1", name: "Mainstream Pop" } });
       const child = makePlaylist({
         uuid: "gp2",
@@ -1282,11 +1289,58 @@ describe("GenreTreeView", () => {
 
       fireEvent.change(screen.getByRole("textbox", { name: "Search a genre" }), { target: { value: "Main" } });
       fireEvent.click(screen.getByRole("button", { name: "Mainstream Pop" }));
-      fireEvent.click(screen.getByRole("button", { name: "Zoom in" }));
+      const output = treeWheelRadialPopCorePropsMock.mock.calls.at(-1)?.[0].renderExtraDetails({ id: "gp1" });
+      render(<>{output}</>);
+      fireEvent.click(screen.getByRole("button", { name: "Focus" }));
 
       expect(onFocusGenreChange).toHaveBeenCalledWith("gp1", "zoom-in");
     });
 
+    it("wires the action band's Add, Rename and Parent actions to the host callbacks", () => {
+      const jazz = makePlaylist({ uuid: "gp1", name: "Jazz", criteria: { uuid: "c1", name: "Jazz" } });
+      useListFullGenrePlaylistsMock.mockReturnValue({ data: [jazz], isPending: false });
+      const props = renderView();
+      fireEvent.click(screen.getByRole("button", { name: "Wheel" }));
+      openBand("gp1");
+
+      fireEvent.click(screen.getByRole("button", { name: "Add" }));
+      fireEvent.click(screen.getByRole("button", { name: "Rename" }));
+      fireEvent.click(screen.getByRole("button", { name: "Parent" }));
+
+      expect(props.handleGenreCreationAction).toHaveBeenCalledWith(jazz.criteria);
+      expect(props.handleGenreRenameAction).toHaveBeenCalledWith(jazz.criteria);
+    });
+
+    it("hides the mutating band actions when read-only", () => {
+      useListFullGenrePlaylistsMock.mockReturnValue({ data: [makePlaylist()], isPending: false });
+      renderView({ readOnly: true });
+      fireEvent.click(screen.getByRole("button", { name: "Wheel" }));
+      openBand("gp1");
+
+      expect(screen.queryByRole("button", { name: "Add" })).not.toBeInTheDocument();
+      expect(screen.queryByRole("button", { name: "Rename" })).not.toBeInTheDocument();
+      expect(screen.queryByRole("button", { name: "Parent" })).not.toBeInTheDocument();
+    });
+
+    it("proxies the search field's Previous button to genre-tree-view's own previous button", () => {
+      useListFullGenrePlaylistsMock.mockReturnValue({ data: [makePlaylist()], isPending: false });
+      const { container } = render(
+        <GenreTreeView scope="me" handleGenreCreationAction={vi.fn()} handleGenreRenameAction={vi.fn()} getBackendBaseUrl={getBackendBaseUrl} />,
+      );
+      const libPrevious = document.createElement("button");
+      libPrevious.className = "gtv-info-panel-previous";
+      const onClick = vi.fn();
+      libPrevious.addEventListener("click", onClick);
+      const overlay = document.createElement("div");
+      overlay.className = "search-overlay";
+      overlay.appendChild(libPrevious);
+      container.querySelector(".genre-tree-view")?.appendChild(overlay);
+
+      fireEvent.click(screen.getByRole("button", { name: "Previous", hidden: true }));
+
+      expect(onClick).toHaveBeenCalledOnce();
+    });
+
     it("follows a controlled selectedNodeId and reports user selections without owning them", () => {
       useListFullGenrePlaylistsMock.mockReturnValue({
         data: [
diff --git a/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx b/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx
index 0d1c1fa..4a578b8 100644
--- a/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx
+++ b/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef, type ReactNode } from "react";
+import { useCallback, useRef, type ComponentProps, type ReactNode } from "react";
 import { z } from "zod";
 import { Plus } from "lucide-react";
 import { IconTextButton, Button } from "@behindthemusictree/ui";
@@ -16,7 +16,7 @@ import type {
   GenreTreeViewMode,
 } from "@behindthemusictree/genre-tree-view";
 
-import { CriteriaMinimum } from "@behindthemusictree/app-kit/genre-tree";
+import { CriteriaMinimum, CriteriaPlaylistSimple } from "@behindthemusictree/app-kit/genre-tree";
 import { CriteriaOverview } from "@behindthemusictree/app-kit/genre-tree";
 import { Scope } from "@behindthemusictree/app-kit/transport";
 import { useGenreTreeViewState, useTrackList, TrackListOriginType } from "@behindthemusictree/app-kit/genre-tree";
@@ -37,6 +37,8 @@ import GenreActionBand from "./GenreActionBand";
 // under the floating search bar. It is hidden and its click is proxied by the search field's own button, which
 // appears (fading in, sliding from the left) whenever the original exists; the field makes room for it.
 const PREVIOUS_BUTTON_CSS = `
+.genre-tree-view .gtv-info-panel-body { display: flex; flex-direction: column; }
+.genre-tree-view .gtv-info-panel-extra { order: -1; }
 .genre-tree-view .search-overlay .gtv-info-panel-previous { display: none; }
 .genre-tree-view:has(.search-overlay .gtv-info-panel-previous) .genre-search input { padding-left: 44px; }
 .genre-tree-view:has(.search-overlay .gtv-info-panel-previous) .genre-search-previous { display: flex; }
@@ -46,6 +48,34 @@ const PREVIOUS_BUTTON_CSS = `
 }
 `;
 
+type GenreNodeActionBandProps = Omit<ComponentProps<typeof GenreActionBand>, "onPlayPause" | "isPlaying"> & {
+  genrePlaylist: CriteriaPlaylistSimple;
+  scope: Scope;
+};
+
+function GenreNodeActionBand({ genrePlaylist, scope, ...bandProps }: GenreNodeActionBandProps) {
+  const { isPlaying, setIsPlaying } = usePlayer();
+  const { trackList, playNewTrackListFromGenrePlaylist } = useTrackList();
+  const isCurrentTrackList =
+    trackList?.origin.type === TrackListOriginType.GENRE_PLAYLIST && trackList.origin.uuid === genrePlaylist.uuid;
+  const handlePlayPause = () => {
+    if (isCurrentTrackList) {
+      setIsPlaying(!isPlaying);
+      return;
+    }
+    playNewTrackListFromGenrePlaylist(genrePlaylist, scope).catch((error) => {
+      console.error("Failed to load genre playlist tracks:", error);
+    });
+  };
+  return (
+    <GenreActionBand
+      {...bandProps}
+      onPlayPause={genrePlaylist.tracksCount > 0 ? handlePlayPause : undefined}
+      isPlaying={isCurrentTrackList && isPlaying}
+    />
+  );
+}
+
 export type {
   ControlsOrientation,
   FocusChangeReason,
@@ -172,27 +202,6 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
   const handleGenreSearchClear = clearSelection;
   const handleGenreSearchSelect = selectGenrePlaylist;
 
-  const { isPlaying, setIsPlaying } = usePlayer();
-  const { trackList, playNewTrackListFromGenrePlaylist } = useTrackList();
-  const isSelectedPlaying =
-    trackList?.origin.type === TrackListOriginType.GENRE_PLAYLIST &&
-    trackList.origin.uuid === selectedGenrePlaylist?.uuid &&
-    isPlaying;
-  const canPlay =
-    selectedGenrePlaylist !== undefined &&
-    selectedGenrePlaylist !== null &&
-    selectedGenrePlaylist.tracksCount > 0;
-  const handleGenreSearchPlayPause = () => {
-    if (!selectedGenrePlaylist) return;
-    if (trackList?.origin.type === TrackListOriginType.GENRE_PLAYLIST && trackList.origin.uuid === selectedGenrePlaylist.uuid) {
-      setIsPlaying(!isPlaying);
-      return;
-    }
-    playNewTrackListFromGenrePlaylist(selectedGenrePlaylist, scope).catch((error) => {
-      console.error("Failed to load genre playlist tracks:", error);
-    });
-  };
-
   // Mirrors genre-tree-view's isZoomableNode: a node zooms when it has children and at most one pop-side child.
   const selectedUuid = selectedGenrePlaylist?.uuid;
   const selectedChildren = selectedUuid
@@ -208,22 +217,27 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
   const handleGenreSearchZoomIn = () => {
     if (selectedUuid) focus.onFocusGenreChange?.(selectedUuid, "zoom-in");
   };
+  const zoomInRef = useRef<(() => void) | undefined>(undefined);
+  zoomInRef.current = canZoomIn ? handleGenreSearchZoomIn : undefined;
 
   // Stable across selections: the overview fetch lives in GenreDetailExtras, so its loading
   // states re-render only the info panel, never the tree.
   const renderExtraDetails = useCallback(
     (node: GenreTreeNode): ReactNode => {
       const genrePlaylist = genrePlaylistByNodeId.get(node.id);
-      const genreUuid = genrePlaylist?.criteria?.uuid;
-      if (!genrePlaylist || !genreUuid) return null;
+      const criteria = genrePlaylist?.criteria;
+      if (!genrePlaylist || !criteria) return null;
+      const genreUuid = criteria.uuid;
       return (
         <>
-          <GenreActionBand
+          <GenreNodeActionBand
             node={node}
-            onPlayPause={canPlay ? handleGenreSearchPlayPause : undefined}
-            isPlaying={isSelectedPlaying}
-            onZoomIn={canZoomIn ? handleGenreSearchZoomIn : undefined}
-            onAddChild={readOnly ? undefined : () => handleGenreCreationAction(genrePlaylist.criteria ?? null)}
+            genrePlaylist={genrePlaylist}
+            scope={scope}
+            onZoomIn={zoomInRef.current}
+            onAddChild={readOnly ? undefined : () => handleGenreCreationAction(criteria)}
+            onRename={readOnly ? undefined : () => handleGenreRenameAction(criteria)}
+            onChangeParent={readOnly ? undefined : () => requestReparent(genrePlaylist.uuid)}
             additionalActions={additionalActions}
           />
         <GenreDetailExtras<O>
@@ -244,8 +258,8 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
         </>
       );
     },
-    [genrePlaylistByNodeId, canPlay, isSelectedPlaying, canZoomIn, additionalActions, readOnly, handleGenreCreationAction,
-      handleGenreSearchPlayPause, handleGenreSearchZoomIn, scope, getBackendBaseUrl, criteriaOverviewSchema,
+    [genrePlaylistByNodeId, additionalActions, readOnly, handleGenreCreationAction, handleGenreRenameAction, requestReparent,
+      scope, getBackendBaseUrl, criteriaOverviewSchema,
       renderGenreDetailExtras,
       renderArtistLink,
       renderSummary,
@@ -360,7 +374,7 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
             // the header inset (10px padding + 38px = the search bar's bottom edge) extends its fill behind the search bar,
             // Google Maps style; the 8px bottom padding mirrors the 8px above the bar, and the hidden title's height is zeroed.
             // The panel's own Zoom in button is hidden: the search bar carries it.
-            <div className="tree-container search-overlay relative flex-1 w-full min-h-0 [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:38px] [&_.gtv-info-panel-header]:pb-2 [&_.gtv-info-panel-title--hidden]:h-0 [&_.gtv-toolbar>.gtv-toolbar-btn]:hidden">
+            <div className="tree-container search-overlay relative flex-1 w-full min-h-0 [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:38px] [&_.gtv-info-panel-header]:pb-2 [&_.gtv-info-panel-title--hidden]:h-0 [&_.gtv-toolbar]:hidden">
               <GenreTreeWheelHandoff skeleton={<GenreTreeWheelSkeleton />}>
                 <GenrePlaylistTreeWheel
                   scope={scope}
@@ -387,7 +401,7 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
           ) : viewMode === "pop-core" ? (
             // The info panel's top edge aligns with the tree's, 8px above the h-10 search bar at top-5;
             // the header inset (8px + 40px + 4px) extends its fill behind the search bar, Google Maps style.
-            <div className="tree-container search-overlay relative flex-1 w-full min-h-0 [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:38px] [&_.gtv-info-panel-header]:pb-2 [&_.gtv-info-panel-title--hidden]:h-0 [&_.gtv-toolbar>.gtv-toolbar-btn]:hidden [&_.gtv-info-panel-zoom-in]:hidden">
+            <div className="tree-container search-overlay relative flex-1 w-full min-h-0 [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:38px] [&_.gtv-info-panel-header]:pb-2 [&_.gtv-info-panel-title--hidden]:h-0 [&_.gtv-toolbar]:hidden [&_.gtv-info-panel-zoom-in]:hidden">
               <GenreTreeWheelHandoff skeleton={<GenreTreeWheelSkeleton />}>
                 <GenrePlaylistTreeWheelRadialPopCore
                   scope={scope}
@@ -413,7 +427,7 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
               </GenreTreeWheelHandoff>
             </div>
           ) : viewMode === "outline" ? (
-            <div className="tree-container flex-1 min-h-0 w-full overflow-y-auto relative [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:52px] [&_.gtv-toolbar>.gtv-toolbar-btn]:hidden">
+            <div className="tree-container flex-1 min-h-0 w-full overflow-y-auto relative [--gtv-info-panel-top:12px] [--gtv-info-panel-header-inset:52px] [&_.gtv-toolbar]:hidden">
               <GenrePlaylistTreeWheelRadialPopCore
                 outline
                 scope={scope}
@@ -435,7 +449,7 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
               />
             </div>
           ) : (
-            <div className="tree-container relative flex flex-col gap-4 w-full pt-14 overflow-x-auto overflow-y-auto text-[var(--color-text)] [&_.gtv-toolbar>.gtv-toolbar-btn]:hidden">
+            <div className="tree-container relative flex flex-col gap-4 w-full pt-14 overflow-x-auto overflow-y-auto text-[var(--color-text)] [&_.gtv-toolbar]:hidden">
               {Object.entries(groupedGenrePlaylistsByRoot).map(
                 ([uuid, genrePlaylistTreePerRoot], rootIndex) => {
                   return (

From 8c57e65511d6af80954790f903a864d4a51b737e Mon Sep 17 00:00:00 2001
From: Andreas Garcia <garcia.andreas.1991@gmail.com>
Date: Mon, 26 Oct 2026 17:26:26 +0100
Subject: [PATCH 4/5] feat(genre-tree): optional extra result group in the
 genre search (#314)

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  1 +
 .../src/genre-tree/GenreSearch.test.tsx       | 61 +++++++++++++++++++
 .../app-kit-ui/src/genre-tree/GenreSearch.tsx | 58 ++++++++++++++++--
 .../src/genre-tree/GenreTreeView.tsx          | 10 ++-
 packages/app-kit-ui/src/genre-tree/index.ts   |  2 +-
 5 files changed, 126 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 10f9c15..9591e26 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@ easy to spot when bumping.
 
 ### Added
 
+- `GenreSearch` / `GenreTreeView`: optional `onQueryChange` / `onSearchQueryChange` and `extraResults` / `searchExtraResults` let the host add a second result group (e.g. artists) to the search dropdown, shown under "Genres" and the group's label. Unset, the dropdown is unchanged.
 - `GenreTreeView` (wheel, pop-core): genre-tree-view's "Previous" button now sits inside the search field, left of the genre name, and fades in sliding from the left; the field's left padding widens to make room.
 - `GenreActionBand`: Google Maps-style band under the detail panel header (icon over label) holding Play/Pause, Focus, Add, Rename, Parent and the `additionalActions`; genre-tree-view's own toolbar and its ⋮ menu are hidden.
 
diff --git a/packages/app-kit-ui/src/genre-tree/GenreSearch.test.tsx b/packages/app-kit-ui/src/genre-tree/GenreSearch.test.tsx
index efc5e26..3501561 100644
--- a/packages/app-kit-ui/src/genre-tree/GenreSearch.test.tsx
+++ b/packages/app-kit-ui/src/genre-tree/GenreSearch.test.tsx
@@ -95,4 +95,65 @@ describe("GenreSearch", () => {
     expect(onClear).toHaveBeenCalledTimes(1);
     expect(screen.getByLabelText("Search a genre")).toHaveValue("");
   });
+
+  describe("extraResults", () => {
+    const extra = (onSelect = vi.fn()) => ({
+      label: "Artists",
+      items: [{ key: "a", content: "Taylor Swift", onSelect }],
+      status: "1 artist found",
+    });
+
+    it("groups genres and extra results under headings", () => {
+      render(<GenreSearch genrePlaylists={genrePlaylists} onSelect={vi.fn()} extraResults={extra()} />);
+
+      fireEvent.change(screen.getByRole("textbox"), { target: { value: "amb" } });
+
+      expect(screen.getByText("Genres")).toBeInTheDocument();
+      expect(screen.getByText("Artists")).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "Taylor Swift" })).toBeInTheDocument();
+      expect(screen.getByRole("status")).toHaveTextContent("1 artist found");
+    });
+
+    it("shows no headings without extra results", () => {
+      render(<GenreSearch genrePlaylists={genrePlaylists} onSelect={vi.fn()} />);
+
+      fireEvent.change(screen.getByRole("textbox"), { target: { value: "amb" } });
+
+      expect(screen.queryByText("Genres")).not.toBeInTheDocument();
+    });
+
+    it("reports typing, and clears the query when an extra result is picked", () => {
+      const onQueryChange = vi.fn();
+      const onSelect = vi.fn();
+      render(
+        <GenreSearch
+          genrePlaylists={genrePlaylists}
+          onSelect={vi.fn()}
+          onQueryChange={onQueryChange}
+          extraResults={extra(onSelect)}
+        />,
+      );
+
+      fireEvent.change(screen.getByRole("textbox"), { target: { value: "tay" } });
+      expect(onQueryChange).toHaveBeenLastCalledWith("tay");
+      fireEvent.click(screen.getByRole("button", { name: "Taylor Swift" }));
+
+      expect(onSelect).toHaveBeenCalledOnce();
+      expect(onQueryChange).toHaveBeenLastCalledWith("");
+      expect(screen.getByRole("textbox")).toHaveValue("");
+    });
+
+    it("does not report the query when the selected name refills the input", () => {
+      const onQueryChange = vi.fn();
+      const { rerender } = render(
+        <GenreSearch genrePlaylists={genrePlaylists} onSelect={vi.fn()} onQueryChange={onQueryChange} />,
+      );
+
+      rerender(
+        <GenreSearch genrePlaylists={genrePlaylists} onSelect={vi.fn()} onQueryChange={onQueryChange} selectedName="Ambient" />,
+      );
+
+      expect(onQueryChange).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/packages/app-kit-ui/src/genre-tree/GenreSearch.tsx b/packages/app-kit-ui/src/genre-tree/GenreSearch.tsx
index 55633f0..4228469 100644
--- a/packages/app-kit-ui/src/genre-tree/GenreSearch.tsx
+++ b/packages/app-kit-ui/src/genre-tree/GenreSearch.tsx
@@ -1,10 +1,19 @@
 "use client";
 
+import type { ReactNode } from "react";
 import { ArrowLeft, Search, X } from "lucide-react";
 import { Input } from "@behindthemusictree/ui";
 
 import { CriteriaPlaylistSimple, useGenreSearch } from "@behindthemusictree/app-kit/genre-tree";
 
+export type GenreSearchExtraResults = {
+  /** Heading of this group; genre matches then get a "Genres" heading above it. */
+  label: string;
+  items: { key: string; content: ReactNode; onSelect: () => void }[];
+  /** Announced politely, e.g. "No artists found". */
+  status?: string;
+};
+
 export type GenreSearchProps = {
   genrePlaylists: CriteriaPlaylistSimple[];
   onSelect: (genrePlaylist: CriteriaPlaylistSimple) => void;
@@ -15,6 +24,10 @@ export type GenreSearchProps = {
   /** Called by the clear button, after it empties the input. */
   onClear?: () => void;
   placeholder?: string;
+  /** Called with what the user types, and with "" on clear or pick; never when `selectedName` refills the input. */
+  onQueryChange?: (query: string) => void;
+  /** A second result group (e.g. artists) the host resolves from `onQueryChange`. */
+  extraResults?: GenreSearchExtraResults;
 };
 
 export default function GenreSearch({
@@ -24,6 +37,8 @@ export default function GenreSearch({
   onClear,
   onPrevious,
   placeholder = "Search a genre…",
+  onQueryChange,
+  extraResults,
 }: GenreSearchProps) {
   const { query, setQuery, results, canClear, clear, select } = useGenreSearch({
     genrePlaylists,
@@ -32,6 +47,10 @@ export default function GenreSearch({
     onClear,
   });
 
+  const extraItems = query !== "" && query !== selectedName ? (extraResults?.items ?? []) : [];
+  const showList = results.length > 0 || extraItems.length > 0;
+  const heading = "px-3 pt-2 pb-1 text-xs font-medium uppercase text-[var(--color-neutral-500)]";
+
   return (
     <div className="genre-search relative w-[264px] shrink-0">
       {onPrevious && (
@@ -48,7 +67,10 @@ export default function GenreSearch({
       <Input
         type="text"
         value={query}
-        onChange={(event) => setQuery(event.target.value)}
+        onChange={(event) => {
+          setQuery(event.target.value);
+          onQueryChange?.(event.target.value);
+        }}
         placeholder={placeholder}
         aria-label="Search a genre"
         className="pl-4 pr-16 transition-[padding] duration-200 ease-out motion-reduce:transition-none bg-white border-[var(--color-neutral-200)] rounded-full shadow-md"
@@ -62,26 +84,54 @@ export default function GenreSearch({
               type="button"
               aria-label="Clear search"
               className="p-1 text-[var(--color-neutral-500)] bg-transparent rounded-full hover:bg-[var(--color-neutral-100)] hover:text-[var(--color-text)]"
-              onClick={clear}
+              onClick={() => {
+                clear();
+                onQueryChange?.("");
+              }}
             >
               <X aria-hidden="true" className="w-4 h-4" />
             </button>
           )}
       </div>
-      {results.length > 0 && (
+      {extraResults?.status && (
+        <p role="status" aria-live="polite" className="sr-only">
+          {extraResults.status}
+        </p>
+      )}
+      {showList && (
         <ul className="genre-search-results absolute z-40 w-full max-h-64 mt-1 overflow-y-auto bg-white border border-[var(--color-neutral-200)] rounded-xl shadow-md">
+          {extraResults && results.length > 0 && <li className={heading}>Genres</li>}
           {results.map((genrePlaylist) => (
             <li key={genrePlaylist.uuid}>
               <button
                 type="button"
                 className="w-full px-3 py-1.5 text-left bg-transparent rounded-none hover:bg-[var(--color-neutral-100)]"
-                onClick={() => select(genrePlaylist)}
+                onClick={() => {
+                  select(genrePlaylist);
+                  onQueryChange?.("");
+                }}
               >
                 {genrePlaylist.name}
                 {genrePlaylist.isUmbrella && <span className="ml-2 text-xs italic text-[var(--color-neutral-500)]">umbrella</span>}
               </button>
             </li>
           ))}
+          {extraResults && extraItems.length > 0 && <li className={heading}>{extraResults.label}</li>}
+          {extraItems.map((item) => (
+            <li key={item.key}>
+              <button
+                type="button"
+                className="w-full px-3 py-1.5 text-left bg-transparent rounded-none hover:bg-[var(--color-neutral-100)]"
+                onClick={() => {
+                  setQuery("");
+                  onQueryChange?.("");
+                  item.onSelect();
+                }}
+              >
+                {item.content}
+              </button>
+            </li>
+          ))}
         </ul>
       )}
     </div>
diff --git a/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx b/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx
index 4a578b8..24666e1 100644
--- a/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx
+++ b/packages/app-kit-ui/src/genre-tree/GenreTreeView.tsx
@@ -30,7 +30,7 @@ import GenrePlaylistTreePerRoot from "./playlist-tree/TreePerRoot";
 import GenrePlaylistTreeWheel from "./playlist-tree/TreeWheel";
 import GenrePlaylistTreeWheelRadialPopCore, { type GenreFocusProps } from "./playlist-tree/TreeWheelRadialPopCore";
 import { GenreTreeWheelHandoff } from "./GenreTreeWheelHandoff";
-import GenreSearch from "./GenreSearch";
+import GenreSearch, { type GenreSearchProps } from "./GenreSearch";
 import GenreActionBand from "./GenreActionBand";
 
 // genre-tree-view's "previous" button (back to the last selected genre) renders inside the info panel, which sits
@@ -115,6 +115,10 @@ export type GenreTreeViewProps<O extends CriteriaOverview = CriteriaOverview> =
   controlsOrientation?: ControlsOrientation;
   /** When set, artist names in the info panel's track list render through it (e.g. a router `Link`). */
   renderArtistLink?: RenderArtistLink;
+  /** Forwarded to the search bar: what the user types, so the host can resolve `searchExtraResults`. */
+  onSearchQueryChange?: GenreSearchProps["onQueryChange"];
+  /** A second result group in the search dropdown, e.g. artists. */
+  searchExtraResults?: GenreSearchProps["extraResults"];
 } & GenreDetailSlots<O> &
   GenrePlaylistTracksSlots &
   InfoPanelCurationProps &
@@ -138,6 +142,8 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
   renderGenreDetailExtras,
   controlsOrientation,
   renderArtistLink,
+  onSearchQueryChange,
+  searchExtraResults,
   renderSummary,
   renderEssentialTracks,
   renderRecordingLeading,
@@ -282,6 +288,8 @@ export function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({
           selectedName={selectedGenrePlaylist?.name ?? null}
           onClear={handleGenreSearchClear}
           onPrevious={handlePrevious}
+          onQueryChange={onSearchQueryChange}
+          extraResults={searchExtraResults}
         />
       )}
       {!isLoading && !isControlled && (
diff --git a/packages/app-kit-ui/src/genre-tree/index.ts b/packages/app-kit-ui/src/genre-tree/index.ts
index 1bd9a71..7f675a5 100644
--- a/packages/app-kit-ui/src/genre-tree/index.ts
+++ b/packages/app-kit-ui/src/genre-tree/index.ts
@@ -5,7 +5,7 @@ export type { InfoPanelCurationProps } from "./playlist-tree/infoPanelCurationPr
 export { default as GenrePlaylistTreePerRoot } from "./playlist-tree/TreePerRoot";
 export type { GenrePlaylistTreePerRootProps } from "./playlist-tree/TreePerRoot";
 export { default as GenreSearch } from "./GenreSearch";
-export type { GenreSearchProps } from "./GenreSearch";
+export type { GenreSearchProps, GenreSearchExtraResults } from "./GenreSearch";
 export {
   GenreTreeSkeleton,
   GenreTreeWheelSkeleton,

From c013209f41f817e05afc21995d55e51370a34d5e Mon Sep 17 00:00:00 2001
From: mignot <garcia.andreas.1991@gmail.com>
Date: Mon, 26 Oct 2026 17:27:14 +0100
Subject: [PATCH 5/5] chore: release 14.0.0

---
 CHANGELOG.md                     | 2 ++
 packages/app-kit-ui/package.json | 4 ++--
 packages/app-kit/package.json    | 2 +-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9591e26..4c68e33 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,8 @@ easy to spot when bumping.
 
 ## [Unreleased]
 
+## [14.0.0] - 2026-10-26
+
 ### Added
 
 - `GenreSearch` / `GenreTreeView`: optional `onQueryChange` / `onSearchQueryChange` and `extraResults` / `searchExtraResults` let the host add a second result group (e.g. artists) to the search dropdown, shown under "Genres" and the group's label. Unset, the dropdown is unchanged.
diff --git a/packages/app-kit-ui/package.json b/packages/app-kit-ui/package.json
index 1db2f50..95834fd 100644
--- a/packages/app-kit-ui/package.json
+++ b/packages/app-kit-ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@behindthemusictree/app-kit-ui",
-  "version": "13.5.0",
+  "version": "14.0.0",
   "description": "Styled BehindTheMusicTree React components (popups, auth callback, genre tree) built on the headless @behindthemusictree/app-kit",
   "repository": {
     "type": "git",
@@ -46,7 +46,7 @@
     "test": "vitest run --coverage"
   },
   "peerDependencies": {
-    "@behindthemusictree/app-kit": "^13.5.0",
+    "@behindthemusictree/app-kit": "^14.0.0",
     "@behindthemusictree/ui": "^0.2.0",
     "@tanstack/react-query": ">=5.0.0",
     "next": ">=14.0.0",
diff --git a/packages/app-kit/package.json b/packages/app-kit/package.json
index 3e934a7..1ed7817 100644
--- a/packages/app-kit/package.json
+++ b/packages/app-kit/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@behindthemusictree/app-kit",
-  "version": "13.5.0",
+  "version": "14.0.0",
   "description": "Headless transport, auth, popup state, player, and genre-tree data plumbing for BehindTheMusicTree React apps",
   "repository": {
     "type": "git",