From 7766d6a7f4d0123933a9f60419e9015ff6407de4 Mon Sep 17 00:00:00 2001
From: Shaojin Wen <szujobs@gmail.com>
Date: Fri, 3 Jul 2026 20:07:01 +0800
Subject: [PATCH 1/3] feat(web-shell): show more slash commands with category
 headers

The slash-command menu capped its visible height at exactly four rows, so
with 40+ merged commands users had to scroll a thin list to find anything,
and the built-in custom/skill/system grouping was only a faint 1px divider
with no label.

Raise the cap to min(12 rows, 40vh) and render the category name as a visible
header at each group boundary (custom / skill / system), keeping the divider
between groups. Sub-command menus are ungrouped and unchanged.
---
 .../client/components/ChatEditor.module.css      | 16 ++++++++++------
 .../web-shell/client/components/ChatEditor.tsx   |  8 ++++++--
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/packages/web-shell/client/components/ChatEditor.module.css b/packages/web-shell/client/components/ChatEditor.module.css
index 0891125d391..0a0acf54863 100644
--- a/packages/web-shell/client/components/ChatEditor.module.css
+++ b/packages/web-shell/client/components/ChatEditor.module.css
@@ -181,12 +181,7 @@
 .slashPanel {
   position: fixed;
   z-index: var(--web-shell-popover-z-index, 1000);
-  --slash-panel-max-height: min(
-    calc(
-      (22px + 10px) + (22px + 10px) + (22px + 10px) + (22px + 10px) + 6px + 12px
-    ),
-    50vh
-  );
+  --slash-panel-max-height: min(calc(12 * (22px + 10px) + 6px + 12px), 40vh);
   --slash-anchor-width: 620px;
   --slash-command-col: 20ch;
   --slash-desc-col: 32ch;
@@ -262,6 +257,15 @@
   background: var(--chat-editor-border-color);
 }
 
+.slashSectionHeader {
+  padding: 4px 8px 2px;
+  color: var(--muted-foreground);
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.02em;
+  user-select: none;
+}
+
 .slashItem {
   position: relative;
   display: grid;
diff --git a/packages/web-shell/client/components/ChatEditor.tsx b/packages/web-shell/client/components/ChatEditor.tsx
index 32f579e5dd4..7925438d6ed 100644
--- a/packages/web-shell/client/components/ChatEditor.tsx
+++ b/packages/web-shell/client/components/ChatEditor.tsx
@@ -721,13 +721,17 @@ function SlashCommandPanel({
               const section = item.section;
               const showSection =
                 menu.kind === 'command' &&
-                index > 0 &&
                 section !== undefined &&
                 section !== lastSection;
               lastSection = section ?? lastSection;
               return (
                 <div key={`${item.id}:${index}`} className={styles.slashEntry}>
-                  {showSection && <div className={styles.slashSection} />}
+                  {showSection && (
+                    <>
+                      {index > 0 && <div className={styles.slashSection} />}
+                      <div className={styles.slashSectionHeader}>{section}</div>
+                    </>
+                  )}
                   <button
                     ref={(node) => {
                       itemRefs.current[index] = node;

From 6e3bf7af2d94a6122899338fdfb6cb6e53f25c75 Mon Sep 17 00:00:00 2001
From: Shaojin Wen <szujobs@gmail.com>
Date: Fri, 3 Jul 2026 21:02:31 +0800
Subject: [PATCH 2/3] feat(web-shell): fuzzy-match slash commands and show
 per-group counts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Typing in the slash menu now fuzzy-ranks commands with the same fzf engine the
TUI uses, so abbreviated input like "mdl" finds "model" and "arf" finds
"agent-reproduce-feature" — substring matching alone could not. An empty query
still browses the category-ordered list; a non-empty query switches to a flat
relevance-ranked list (headers are dropped since results interleave categories).

Each category header also shows how many commands the group holds (e.g. "Skill
commands  28"), so the volume hidden below the fold is visible at a glance.

The fzf index is built once per command set (keyed on the array identity) and
falls back to substring filtering if construction fails.
---
 package-lock.json                             |  1 +
 .../completions/slashCompletion.test.ts       | 76 +++++++++++++++++++
 .../client/completions/slashCompletion.ts     | 76 +++++++++++++++++--
 .../client/components/ChatEditor.module.css   | 12 +++
 .../client/components/ChatEditor.tsx          | 20 ++++-
 packages/web-shell/package.json               |  1 +
 6 files changed, 177 insertions(+), 9 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index d961e8500b7..eff18f4475f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -27343,6 +27343,7 @@
         "@codemirror/view": "^6.35.0",
         "@tanstack/react-virtual": "^3.13.26",
         "codemirror": "^6.0.0",
+        "fzf": "^0.5.2",
         "katex": "^0.16.47",
         "mermaid": "^11.15.0",
         "react-markdown": "^9.0.0",
diff --git a/packages/web-shell/client/completions/slashCompletion.test.ts b/packages/web-shell/client/completions/slashCompletion.test.ts
index d26c4d9e76d..c77eeb5645c 100644
--- a/packages/web-shell/client/completions/slashCompletion.test.ts
+++ b/packages/web-shell/client/completions/slashCompletion.test.ts
@@ -178,6 +178,82 @@ describe('getSlashCommandCompletionResult', () => {
     ]);
   });
 
+  it('fuzzy-ranks top-level commands for an abbreviated query', () => {
+    const commands: CommandInfo[] = [
+      { name: 'model', description: 'Switch model', source: 'builtin-command' },
+      {
+        name: 'memory',
+        description: 'Manage memory',
+        source: 'builtin-command',
+      },
+      {
+        name: 'agent-reproduce-feature',
+        description: 'Reproduce a feature',
+        source: 'skill-dir-command',
+      },
+    ];
+
+    const mdl = getSlashCommandCompletionResult(
+      '/mdl',
+      4,
+      commands,
+      [],
+      'en',
+      getTranslator('en'),
+    );
+    expect(mdl?.items[0]?.label).toBe('/model');
+
+    const arf = getSlashCommandCompletionResult(
+      '/arf',
+      4,
+      commands,
+      [],
+      'en',
+      getTranslator('en'),
+    );
+    expect(arf?.items.map((item) => item.label)).toContain(
+      '/agent-reproduce-feature',
+    );
+  });
+
+  it('drops section headers while searching but keeps them while browsing', () => {
+    const commands: CommandInfo[] = [
+      {
+        name: 'clear',
+        description: 'Clear the screen',
+        source: 'builtin-command',
+      },
+      {
+        name: 'demo:ping',
+        description: 'Project command',
+        source: 'skill-dir-command',
+      },
+    ];
+
+    const browsing = getSlashCommandCompletionResult(
+      '/',
+      1,
+      commands,
+      [],
+      'en',
+      getTranslator('en'),
+    );
+    expect(browsing?.items.every((item) => Boolean(item.section))).toBe(true);
+
+    const searching = getSlashCommandCompletionResult(
+      '/c',
+      2,
+      commands,
+      [],
+      'en',
+      getTranslator('en'),
+    );
+    expect(searching?.items.map((item) => item.label)).toEqual(['/clear']);
+    expect(searching?.items.every((item) => item.section === undefined)).toBe(
+      true,
+    );
+  });
+
   it('honors panel category order and filtered commands', () => {
     const commands: CommandInfo[] = [
       {
diff --git a/packages/web-shell/client/completions/slashCompletion.ts b/packages/web-shell/client/completions/slashCompletion.ts
index fbf39770166..275fe01cc0a 100644
--- a/packages/web-shell/client/completions/slashCompletion.ts
+++ b/packages/web-shell/client/completions/slashCompletion.ts
@@ -4,6 +4,7 @@ import type {
   CompletionResult,
   CompletionSection,
 } from '@codemirror/autocomplete';
+import { Fzf } from 'fzf';
 import type { CommandInfo } from '../adapters/types';
 import type { WebShellLanguage } from '../i18n';
 import {
@@ -332,6 +333,58 @@ function getLineBounds(text: string, cursor: number) {
   };
 }
 
+// The visible slash menu (React SlashCommandPanel) drives its top-level command
+// list through getSlashCommandCompletionResult. For a non-empty query we rank
+// with fzf — the same fuzzy engine the TUI uses — so abbreviated input like
+// "mdl" surfaces "model" and "arf" surfaces "agent-reproduce-feature". Building
+// the index is keyed on the commands array identity, so it happens once per
+// command set rather than on every keystroke. (slashCompletionSource, the
+// CodeMirror source below, is not wired into the live editor and still does
+// substring filtering.)
+const commandFzfCache = new WeakMap<
+  readonly CommandInfo[],
+  { fzf: Fzf<readonly string[]>; byName: Map<string, CommandInfo> }
+>();
+
+function getCommandFzf(commands: CommandInfo[]) {
+  let entry = commandFzfCache.get(commands);
+  if (!entry) {
+    const names: string[] = [];
+    const byName = new Map<string, CommandInfo>();
+    for (const command of commands) {
+      if (byName.has(command.name)) continue;
+      names.push(command.name);
+      byName.set(command.name, command);
+    }
+    entry = {
+      fzf: new Fzf(names, { fuzzy: 'v2', casing: 'case-insensitive' }),
+      byName,
+    };
+    commandFzfCache.set(commands, entry);
+  }
+  return entry;
+}
+
+function fuzzyRankCommands(
+  commands: CommandInfo[],
+  query: string,
+): CommandInfo[] {
+  try {
+    const { fzf, byName } = getCommandFzf(commands);
+    const matches: CommandInfo[] = [];
+    for (const result of fzf.find(query)) {
+      const command = byName.get(result.item);
+      if (command) matches.push(command);
+    }
+    return matches;
+  } catch {
+    const lp = query.toLowerCase();
+    return commands.filter((command) =>
+      command.name.toLowerCase().includes(lp),
+    );
+  }
+}
+
 export function getSlashCommandCompletionResult(
   text: string,
   cursor: number,
@@ -423,13 +476,15 @@ export function getSlashCommandCompletionResult(
   if (!match) return null;
 
   const prefix = match[1];
-  const lp = prefix.toLowerCase();
-  const filteredCommands = commands
-    .filter((command) => {
-      if (!prefix) return true;
-      return command.name.toLowerCase().includes(lp);
-    })
-    .sort((a, b) => compareSlashCommands(a, b, lp, categoryOrder));
+  // Empty query: browse the full list grouped and ordered by category.
+  // Non-empty query: fuzzy-rank by relevance (best match first), matching the
+  // TUI, so partial or abbreviated input surfaces the command the user means.
+  const isBrowsing = prefix.length === 0;
+  const filteredCommands = isBrowsing
+    ? [...commands].sort((a, b) =>
+        compareSlashCommands(a, b, '', categoryOrder),
+      )
+    : fuzzyRankCommands(commands, prefix);
 
   const items = filteredCommands.map((command): SlashCommandCompletionItem => {
     const apply = `/${command.name} `;
@@ -441,7 +496,12 @@ export function getSlashCommandCompletionResult(
       detail: command.description || undefined,
       apply,
       category,
-      section: translate(COMMAND_SECTION_KEYS[category]),
+      // Section headers only make sense while browsing the category-ordered
+      // list; a relevance-ranked result set interleaves categories, so headers
+      // would appear before nearly every row. Drop them during search.
+      ...(isBrowsing
+        ? { section: translate(COMMAND_SECTION_KEYS[category]) }
+        : {}),
       ...(showCommandInfo && command.description
         ? { type: 'command-info' as const }
         : {}),
diff --git a/packages/web-shell/client/components/ChatEditor.module.css b/packages/web-shell/client/components/ChatEditor.module.css
index 0a0acf54863..e5b1f98e4cf 100644
--- a/packages/web-shell/client/components/ChatEditor.module.css
+++ b/packages/web-shell/client/components/ChatEditor.module.css
@@ -258,6 +258,10 @@
 }
 
 .slashSectionHeader {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
   padding: 4px 8px 2px;
   color: var(--muted-foreground);
   font-size: 11px;
@@ -266,6 +270,14 @@
   user-select: none;
 }
 
+.slashSectionCount {
+  flex: 0 0 auto;
+  color: var(--muted-foreground);
+  font-weight: 400;
+  font-variant-numeric: tabular-nums;
+  opacity: 0.7;
+}
+
 .slashItem {
   position: relative;
   display: grid;
diff --git a/packages/web-shell/client/components/ChatEditor.tsx b/packages/web-shell/client/components/ChatEditor.tsx
index 7925438d6ed..38728e948e3 100644
--- a/packages/web-shell/client/components/ChatEditor.tsx
+++ b/packages/web-shell/client/components/ChatEditor.tsx
@@ -683,6 +683,17 @@ function SlashCommandPanel({
   } as CSSProperties;
 
   let lastSection: string | undefined;
+  const sectionCounts = new Map<string, number>();
+  if (menu.kind === 'command') {
+    for (const item of menu.items) {
+      if (item.section) {
+        sectionCounts.set(
+          item.section,
+          (sectionCounts.get(item.section) ?? 0) + 1,
+        );
+      }
+    }
+  }
 
   if (!anchorRect) return null;
 
@@ -729,7 +740,14 @@ function SlashCommandPanel({
                   {showSection && (
                     <>
                       {index > 0 && <div className={styles.slashSection} />}
-                      <div className={styles.slashSectionHeader}>{section}</div>
+                      <div className={styles.slashSectionHeader}>
+                        <span>{section}</span>
+                        {section && sectionCounts.get(section) ? (
+                          <span className={styles.slashSectionCount}>
+                            {sectionCounts.get(section)}
+                          </span>
+                        ) : null}
+                      </div>
                     </>
                   )}
                   <button
diff --git a/packages/web-shell/package.json b/packages/web-shell/package.json
index 54e856d4757..a3db05b7361 100644
--- a/packages/web-shell/package.json
+++ b/packages/web-shell/package.json
@@ -29,6 +29,7 @@
     "@codemirror/view": "^6.35.0",
     "@tanstack/react-virtual": "^3.13.26",
     "codemirror": "^6.0.0",
+    "fzf": "^0.5.2",
     "katex": "^0.16.47",
     "mermaid": "^11.15.0",
     "react-markdown": "^9.0.0",

From 5dc3a8629c116c43b56e4a76db9f142fc2a6f2bd Mon Sep 17 00:00:00 2001
From: Shaojin Wen <szujobs@gmail.com>
Date: Fri, 3 Jul 2026 22:00:16 +0800
Subject: [PATCH 3/3] refactor(web-shell): address slash menu review feedback

- Extract the section header/divider boundary logic into a pure
  `planSlashSectionRows` helper and unit-test it (headers at group
  boundaries, first row header without a divider, no repeated headers for
  adjacent duplicate sections, per-group counts). This also moves the
  section-count computation past the `!anchorRect` early return so it no
  longer runs on first render.
- Simplify `--slash-panel-max-height` to a round `min(460px, 45vh)` instead
  of a `12 * rowHeight` formula that ignored header/divider overhead and so
  showed only ~9-10 rows; the panel now shows ~12-13 rows.
- Log a warning when fzf fuzzy search throws before falling back to
  substring matching, so a silent failure is diagnosable.
- Add a completion test for the zero-match case returning null.
---
 .../completions/slashCompletion.test.ts       | 15 ++++
 .../client/completions/slashCompletion.ts     |  6 +-
 .../client/components/ChatEditor.module.css   |  4 +-
 .../client/components/ChatEditor.tsx          | 35 +++------
 .../client/utils/slashSectionPlan.test.ts     | 74 +++++++++++++++++++
 .../client/utils/slashSectionPlan.ts          | 52 +++++++++++++
 6 files changed, 160 insertions(+), 26 deletions(-)
 create mode 100644 packages/web-shell/client/utils/slashSectionPlan.test.ts
 create mode 100644 packages/web-shell/client/utils/slashSectionPlan.ts

diff --git a/packages/web-shell/client/completions/slashCompletion.test.ts b/packages/web-shell/client/completions/slashCompletion.test.ts
index c77eeb5645c..afd733962b0 100644
--- a/packages/web-shell/client/completions/slashCompletion.test.ts
+++ b/packages/web-shell/client/completions/slashCompletion.test.ts
@@ -254,6 +254,21 @@ describe('getSlashCommandCompletionResult', () => {
     );
   });
 
+  it('returns null when fuzzy search matches nothing', () => {
+    const commands: CommandInfo[] = [
+      { name: 'clear', description: 'Clear', source: 'builtin-command' },
+    ];
+    const result = getSlashCommandCompletionResult(
+      '/zzzzzzz',
+      8,
+      commands,
+      [],
+      'en',
+      getTranslator('en'),
+    );
+    expect(result).toBeNull();
+  });
+
   it('honors panel category order and filtered commands', () => {
     const commands: CommandInfo[] = [
       {
diff --git a/packages/web-shell/client/completions/slashCompletion.ts b/packages/web-shell/client/completions/slashCompletion.ts
index 275fe01cc0a..c0419a36e3f 100644
--- a/packages/web-shell/client/completions/slashCompletion.ts
+++ b/packages/web-shell/client/completions/slashCompletion.ts
@@ -377,7 +377,11 @@ function fuzzyRankCommands(
       if (command) matches.push(command);
     }
     return matches;
-  } catch {
+  } catch (error) {
+    console.warn(
+      '[web-shell] slash fuzzy search failed, falling back to substring match:',
+      error,
+    );
     const lp = query.toLowerCase();
     return commands.filter((command) =>
       command.name.toLowerCase().includes(lp),
diff --git a/packages/web-shell/client/components/ChatEditor.module.css b/packages/web-shell/client/components/ChatEditor.module.css
index e5b1f98e4cf..7e87343ab6b 100644
--- a/packages/web-shell/client/components/ChatEditor.module.css
+++ b/packages/web-shell/client/components/ChatEditor.module.css
@@ -181,7 +181,9 @@
 .slashPanel {
   position: fixed;
   z-index: var(--web-shell-popover-z-index, 1000);
-  --slash-panel-max-height: min(calc(12 * (22px + 10px) + 6px + 12px), 40vh);
+  /* Round cap sized for ~12 command rows plus their section headers/dividers,
+     bounded by 45vh so it stays proportional on short viewports. */
+  --slash-panel-max-height: min(460px, 45vh);
   --slash-anchor-width: 620px;
   --slash-command-col: 20ch;
   --slash-desc-col: 32ch;
diff --git a/packages/web-shell/client/components/ChatEditor.tsx b/packages/web-shell/client/components/ChatEditor.tsx
index 38728e948e3..89c7bfd0cd4 100644
--- a/packages/web-shell/client/components/ChatEditor.tsx
+++ b/packages/web-shell/client/components/ChatEditor.tsx
@@ -31,6 +31,7 @@ import {
   getComposerTagValue,
 } from '../hooks/useComposerCore';
 import { ModeIcon } from './ModeIcon';
+import { planSlashSectionRows } from '../utils/slashSectionPlan';
 import { getModelDisplayName } from '../utils/modelDisplay';
 import { VoiceButton } from '../voice/VoiceButton';
 import styles from './ChatEditor.module.css';
@@ -682,21 +683,10 @@ function SlashCommandPanel({
     '--slash-column-gap': hasDetailColumn ? '2ch' : '0px',
   } as CSSProperties;
 
-  let lastSection: string | undefined;
-  const sectionCounts = new Map<string, number>();
-  if (menu.kind === 'command') {
-    for (const item of menu.items) {
-      if (item.section) {
-        sectionCounts.set(
-          item.section,
-          (sectionCounts.get(item.section) ?? 0) + 1,
-        );
-      }
-    }
-  }
-
   if (!anchorRect) return null;
 
+  const rowPlans = planSlashSectionRows(menu.items, menu.kind);
+
   const positionedPanelStyle = {
     ...panelStyle,
     ...themeVars,
@@ -729,22 +719,19 @@ function SlashCommandPanel({
             onScroll={() => setHoverDetail(null)}
           >
             {menu.items.map((item, index) => {
-              const section = item.section;
-              const showSection =
-                menu.kind === 'command' &&
-                section !== undefined &&
-                section !== lastSection;
-              lastSection = section ?? lastSection;
+              const plan = rowPlans[index];
               return (
                 <div key={`${item.id}:${index}`} className={styles.slashEntry}>
-                  {showSection && (
+                  {plan.showHeader && (
                     <>
-                      {index > 0 && <div className={styles.slashSection} />}
+                      {plan.showDivider && (
+                        <div className={styles.slashSection} />
+                      )}
                       <div className={styles.slashSectionHeader}>
-                        <span>{section}</span>
-                        {section && sectionCounts.get(section) ? (
+                        <span>{item.section}</span>
+                        {plan.count > 0 ? (
                           <span className={styles.slashSectionCount}>
-                            {sectionCounts.get(section)}
+                            {plan.count}
                           </span>
                         ) : null}
                       </div>
diff --git a/packages/web-shell/client/utils/slashSectionPlan.test.ts b/packages/web-shell/client/utils/slashSectionPlan.test.ts
new file mode 100644
index 00000000000..9447e7c3174
--- /dev/null
+++ b/packages/web-shell/client/utils/slashSectionPlan.test.ts
@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import { planSlashSectionRows } from './slashSectionPlan';
+
+describe('planSlashSectionRows', () => {
+  it('shows a header at each group boundary', () => {
+    const plans = planSlashSectionRows(
+      [
+        { section: 'Custom commands' },
+        { section: 'Custom commands' },
+        { section: 'Skill commands' },
+        { section: 'System commands' },
+      ],
+      'command',
+    );
+    expect(plans.map((p) => p.showHeader)).toEqual([true, false, true, true]);
+  });
+
+  it('shows a header but no divider on the first row', () => {
+    const plans = planSlashSectionRows(
+      [{ section: 'Skill commands' }, { section: 'System commands' }],
+      'command',
+    );
+    expect(plans[0]).toMatchObject({ showHeader: true, showDivider: false });
+    expect(plans[1]).toMatchObject({ showHeader: true, showDivider: true });
+  });
+
+  it('does not repeat headers for adjacent duplicate sections', () => {
+    const plans = planSlashSectionRows(
+      [
+        { section: 'System commands' },
+        { section: 'System commands' },
+        { section: 'System commands' },
+      ],
+      'command',
+    );
+    expect(plans.filter((p) => p.showHeader)).toHaveLength(1);
+  });
+
+  it('reports the number of rows in each section on the header row', () => {
+    const plans = planSlashSectionRows(
+      [
+        { section: 'Skill commands' },
+        { section: 'Skill commands' },
+        { section: 'System commands' },
+      ],
+      'command',
+    );
+    expect(plans[0].count).toBe(2);
+    expect(plans[1].count).toBe(0);
+    expect(plans[2].count).toBe(1);
+  });
+
+  it('never groups subcommand menus', () => {
+    const plans = planSlashSectionRows(
+      [{ section: 'Skill commands' }, { section: 'System commands' }],
+      'subcommand',
+    );
+    expect(plans.every((p) => !p.showHeader && p.count === 0)).toBe(true);
+  });
+
+  it('shows no headers when items carry no section (search results)', () => {
+    const plans = planSlashSectionRows(
+      [{ section: undefined }, { section: undefined }],
+      'command',
+    );
+    expect(plans.every((p) => !p.showHeader)).toBe(true);
+  });
+});
diff --git a/packages/web-shell/client/utils/slashSectionPlan.ts b/packages/web-shell/client/utils/slashSectionPlan.ts
new file mode 100644
index 00000000000..57d58eb761b
--- /dev/null
+++ b/packages/web-shell/client/utils/slashSectionPlan.ts
@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** Per-row rendering plan for the slash command panel's section grouping. */
+export interface SlashSectionRowPlan {
+  /** Render the category header above this row (group boundary). */
+  showHeader: boolean;
+  /** Render the divider above the header (every boundary except the first row). */
+  showDivider: boolean;
+  /** Number of rows in this row's section; 0 when no header is shown. */
+  count: number;
+}
+
+/**
+ * Decide, for each item, whether it starts a new section (and so needs a header,
+ * a divider, and the group count). Extracted as a pure function so the section
+ * boundary logic — headers at group boundaries, a header but no divider on the
+ * first row, and no redundant headers for adjacent duplicate sections — is unit
+ * testable without rendering the panel.
+ *
+ * Only 'command' menus are grouped; subcommand menus render flat (no headers).
+ */
+export function planSlashSectionRows(
+  items: ReadonlyArray<{ section?: string }>,
+  kind: 'command' | 'subcommand',
+): SlashSectionRowPlan[] {
+  const counts = new Map<string, number>();
+  if (kind === 'command') {
+    for (const item of items) {
+      if (item.section) {
+        counts.set(item.section, (counts.get(item.section) ?? 0) + 1);
+      }
+    }
+  }
+
+  let lastSection: string | undefined;
+  return items.map((item, index) => {
+    const section = item.section;
+    const showHeader =
+      kind === 'command' && section !== undefined && section !== lastSection;
+    const showDivider = showHeader && index > 0;
+    lastSection = section ?? lastSection;
+    return {
+      showHeader,
+      showDivider,
+      count: showHeader && section ? (counts.get(section) ?? 0) : 0,
+    };
+  });
+}