@nextclaw/ui 0.18.3 → 0.19.0

package/src/features/panel-apps/components/__tests__/panel-app-main-sidebar-nav.test.tsx

@@ -0,0 +1,82 @@
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  getMainSidebarPanelApps,
+  PanelAppMainSidebarNav,
+} from "@/features/panel-apps/components/panel-app-main-sidebar-nav";
+import type { PanelAppEntryView } from "@/shared/lib/api";
+
+const mocks = vi.hoisted(() => ({
+  entries: [] as PanelAppEntryView[],
+}));
+
+vi.mock("@/features/panel-apps/hooks/use-panel-apps", () => ({
+  usePanelApps: () => ({ data: { entries: mocks.entries } }),
+}));
+
+function createEntry(overrides: Partial<PanelAppEntryView> = {}): PanelAppEntryView {
+  return {
+    appId: "demo",
+    clientDeclared: false,
+    clientGranted: false,
+    contentPath: "/api/panel-apps/demo/content",
+    createdAt: "2026-08-19T00:00:00.000Z",
+    favorite: false,
+    fileName: "demo.panel.html",
+    id: "demo",
+    kind: "single-file",
+    mainSidebar: false,
+    openCount: 0,
+    sizeBytes: 10,
+    title: "Demo",
+    updatedAt: "2026-08-19T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+describe("PanelAppMainSidebarNav", () => {
+  beforeEach(() => {
+    mocks.entries = [];
+  });
+
+  it("projects only manually added apps in persisted order", () => {
+    const entries = [
+      createEntry({ appId: "hidden", title: "Hidden" }),
+      createEntry({ appId: "second", mainSidebar: true, mainSidebarOrder: 1, title: "Second" }),
+      createEntry({ appId: "first", mainSidebar: true, mainSidebarOrder: 0, title: "First" }),
+    ];
+
+    expect(getMainSidebarPanelApps(entries).map((entry) => entry.appId)).toEqual([
+      "first",
+      "second",
+    ]);
+  });
+
+  it("renders stable app routes and hides unbound apps", () => {
+    mocks.entries = [
+      createEntry({ appId: "publisher.todo", mainSidebar: true, title: "Todo" }),
+      createEntry({ appId: "hidden", title: "Hidden" }),
+    ];
+
+    render(
+      <MemoryRouter initialEntries={["/apps/panel/publisher.todo"]}>
+        <PanelAppMainSidebarNav isCollapsed={false} />
+      </MemoryRouter>,
+    );
+
+    const link = screen.getByRole("link", { name: "Todo" });
+    expect(link.getAttribute("href")).toBe("/apps/panel/publisher.todo");
+    expect(link.getAttribute("aria-current")).toBe("page");
+    expect(screen.queryByText("Hidden")).toBeNull();
+  });
+
+  it("renders no section when no app was manually added", () => {
+    const { container } = render(
+      <MemoryRouter>
+        <PanelAppMainSidebarNav isCollapsed={false} />
+      </MemoryRouter>,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+});

package/src/features/panel-apps/components/__tests__/panel-app-toolbar.test.tsx

@@ -1,24 +1,31 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { describe, expect, it, vi } from 'vitest';
-import { PanelAppToolbar } from '../panel-app-toolbar';
+import { PanelAppToolbar } from '@/features/panel-apps/components/panel-app-toolbar';
 
 describe('PanelAppToolbar', () => {
-  it('shows the current panel app title in the detail header', async () => {
+  it('keeps placement in the overflow menu without adding a second back action', async () => {
     const user = userEvent.setup();
-    const onOpenApps = vi.fn();
+    const onToggleMainSidebar = vi.fn();
     render(
       <PanelAppToolbar
         appTitle="墨爪助手"
-        onOpenApps={onOpenApps}
+        mainSidebar={false}
         onRefresh={vi.fn()}
+        onToggleMainSidebar={onToggleMainSidebar}
       />,
     );
 
     expect(screen.getByText('墨爪助手')).toBeTruthy();
+    expect(screen.queryByRole('button', { name: 'Apps' })).toBeNull();
 
-    await user.click(screen.getByRole('button', { name: 'Apps' }));
+    expect(screen.queryByRole('button', { name: 'Add to main sidebar' })).toBeNull();
+    await user.click(screen.getByRole('button', { name: 'More panel app actions' }));
+    const addButton = screen.getByRole('button', { name: 'Add to main sidebar' });
+    expect(addButton.getAttribute('aria-pressed')).toBe('false');
+    await user.click(addButton);
 
-    expect(onOpenApps).toHaveBeenCalledTimes(1);
+    expect(onToggleMainSidebar).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole('button', { name: 'Add to main sidebar' })).toBeNull();
   });
 });

package/src/features/panel-apps/components/__tests__/panel-apps-list.test.tsx

@@ -22,6 +22,7 @@ const mocks = vi.hoisted(() => ({
   }>,
   grantPanelAppClient: vi.fn(),
   navigate: vi.fn(),
+  recordOpened: vi.fn(),
   refetchPanelApps: vi.fn(),
   requestAuthorization: vi.fn(async () => true),
   requestDraft: vi.fn(),
@@ -62,7 +63,7 @@ vi.mock('@/features/panel-apps/hooks/use-panel-apps', () => ({
     refetch: mocks.refetchPanelApps,
   }),
   useRecordPanelAppOpened: () => ({
-    mutateAsync: vi.fn(async (id: string) => mocks.entries.find((entry) => entry.id === id)),
+    mutate: mocks.recordOpened,
   }),
   useUpdatePanelAppPreferences: () => ({
     isPending: false,
@@ -96,6 +97,7 @@ describe('PanelAppsList', () => {
     mocks.grantPanelAppClient.mockReset();
     mocks.navigate.mockReset();
     mocks.refetchPanelApps.mockReset();
+    mocks.recordOpened.mockReset();
     mocks.requestAuthorization.mockReset();
     mocks.requestAuthorization.mockResolvedValue(true);
     mocks.requestDraft.mockReset();
@@ -163,5 +165,9 @@ describe('PanelAppsList', () => {
     }));
     expect(mocks.grantPanelAppClient).toHaveBeenCalledWith('demo-app');
     expect(onOpenPanelApp).toHaveBeenCalledWith(entry);
+    expect(mocks.recordOpened).toHaveBeenCalledWith(entry.id);
+    expect(onOpenPanelApp.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.recordOpened.mock.invocationCallOrder[0]!,
+    );
   });
 });

package/src/features/panel-apps/components/panel-app-icon.tsx

@@ -0,0 +1,48 @@
+import { AppWindow } from "lucide-react";
+import { cn } from "@/shared/lib/utils";
+
+export function PanelAppIcon({
+  className,
+  icon,
+  imageClassName,
+  title,
+}: {
+  className?: string;
+  icon?: string;
+  imageClassName?: string;
+  title: string;
+}) {
+  const normalizedIcon = icon?.trim();
+  if (!normalizedIcon) {
+    return <AppWindow className={cn("h-4 w-4", className)} />;
+  }
+  if (isPanelAppImageIcon(normalizedIcon)) {
+    return (
+      <img
+        src={normalizedIcon}
+        alt=""
+        aria-hidden="true"
+        className={cn("h-5 w-5 rounded-sm object-contain", imageClassName, className)}
+        title={title}
+      />
+    );
+  }
+  return (
+    <span
+      aria-hidden="true"
+      className={cn("max-w-6 truncate text-center leading-none", className)}
+      title={title}
+    >
+      {normalizedIcon}
+    </span>
+  );
+}
+
+export function isPanelAppImageIcon(icon: string): boolean {
+  return (
+    icon.startsWith("data:image/") ||
+    icon.startsWith("http://") ||
+    icon.startsWith("https://") ||
+    icon.startsWith("/")
+  );
+}

package/src/features/panel-apps/components/panel-app-list-item.tsx

@@ -1,6 +1,7 @@
 import { useState, type MouseEvent } from 'react';
-import { AppWindow, MoreVertical, Star, Trash2, type LucideIcon } from 'lucide-react';
+import { MoreVertical, PanelLeft, PanelLeftDashed, Star, Trash2, type LucideIcon } from 'lucide-react';
 import type { PanelAppEntryView } from '@/shared/lib/api';
+import { PanelAppIcon } from '@/features/panel-apps/components/panel-app-icon';
 import { ConfirmDialog } from '@/shared/components/ui/confirm-dialog';
 import { Popover, PopoverContent, PopoverTrigger } from '@/shared/components/ui/popover';
 import { getLanguage, getLocale, t } from '@/shared/lib/i18n';
@@ -10,16 +11,20 @@ export function PanelAppListItem({
   deletePending,
   entry,
   favoritePending,
+  mainSidebarPending,
   onDelete,
   onOpen,
   onToggleFavorite,
+  onToggleMainSidebar,
 }: {
   deletePending: boolean;
   entry: PanelAppEntryView;
   favoritePending: boolean;
+  mainSidebarPending: boolean;
   onDelete: () => void;
   onOpen: () => void;
   onToggleFavorite: () => void;
+  onToggleMainSidebar: () => void;
 }) {
   const [isMenuOpen, setIsMenuOpen] = useState(false);
   const [isDeleteDialogOpen, setIsDeleteDialogOpen] = useState(false);
@@ -32,10 +37,17 @@ export function PanelAppListItem({
     event.stopPropagation();
     onToggleFavorite();
   };
+  const handleMainSidebar = () => {
+    setIsMenuOpen(false);
+    onToggleMainSidebar();
+  };
   const openDeleteDialog = () => {
     setIsMenuOpen(false);
     setIsDeleteDialogOpen(true);
   };
+  const mainSidebarLabel = entry.mainSidebar
+    ? t('panelAppsRemoveFromMainSidebar')
+    : t('panelAppsAddToMainSidebar');
 
   return (
     <div className="group w-full min-w-0 rounded-lg border border-border/60 bg-card px-2.5 py-2.5 transition-colors hover:bg-muted/40">
@@ -75,6 +87,12 @@ export function PanelAppListItem({
               </button>
             </PopoverTrigger>
             <PopoverContent align="end" className="w-48 rounded-xl p-1.5">
+              <PanelAppMenuItem
+                disabled={mainSidebarPending}
+                icon={entry.mainSidebar ? PanelLeftDashed : PanelLeft}
+                label={mainSidebarLabel}
+                onClick={handleMainSidebar}
+              />
               <PanelAppMenuItem
                 destructive
                 disabled={deletePending}
@@ -144,30 +162,3 @@ function formatPanelAppTime(value: string): string {
   }
   return new Intl.DateTimeFormat(locale, { year: '2-digit', month: 'numeric', day: 'numeric' }).format(date);
 }
-
-function PanelAppIcon({ icon, title }: { icon?: string; title: string }) {
-  if (!icon) {
-    return <AppWindow className="h-4 w-4" />;
-  }
-  if (isImageIcon(icon)) {
-    return (
-      <img
-        src={icon}
-        alt=""
-        aria-hidden="true"
-        className="h-5 w-5 rounded-sm object-contain"
-        title={title}
-      />
-    );
-  }
-  return <span className="max-w-6 truncate text-center leading-none">{icon}</span>;
-}
-
-function isImageIcon(icon: string): boolean {
-  return (
-    icon.startsWith('data:image/') ||
-    icon.startsWith('http://') ||
-    icon.startsWith('https://') ||
-    icon.startsWith('/')
-  );
-}

package/src/features/panel-apps/components/panel-app-main-sidebar-nav.tsx

@@ -0,0 +1,72 @@
+import { useMemo } from "react";
+import { SidebarNavLinkItem } from "@/app/components/layout/sidebar-items";
+import { SIDEBAR_RAIL_STACK_CLASS } from "@/app/components/layout/sidebar-rail.styles";
+import { PanelAppIcon } from "@/features/panel-apps/components/panel-app-icon";
+import { usePanelApps } from "@/features/panel-apps/hooks/use-panel-apps";
+import type { PanelAppEntryView } from "@/shared/lib/api";
+import { cn } from "@/shared/lib/utils";
+
+const MAIN_SIDEBAR_FALLBACK_ORDER = Number.MAX_SAFE_INTEGER;
+
+export function getMainSidebarPanelApps(
+  entries: readonly PanelAppEntryView[],
+): PanelAppEntryView[] {
+  return entries
+    .filter((entry) => entry.mainSidebar)
+    .sort((left, right) =>
+      (left.mainSidebarOrder ?? MAIN_SIDEBAR_FALLBACK_ORDER) -
+        (right.mainSidebarOrder ?? MAIN_SIDEBAR_FALLBACK_ORDER) ||
+      left.title.localeCompare(right.title)
+    );
+}
+
+export function PanelAppMainSidebarNav({
+  isCollapsed,
+}: {
+  isCollapsed: boolean;
+}) {
+  const panelApps = usePanelApps();
+  const entries = useMemo(
+    () => getMainSidebarPanelApps(panelApps.data?.entries ?? []),
+    [panelApps.data?.entries],
+  );
+
+  if (entries.length === 0) {
+    return null;
+  }
+
+  return (
+    <div
+      className={cn(
+        "mt-1 border-t border-border/50 pt-1",
+        isCollapsed ? "px-0" : "px-3",
+      )}
+      data-testid="panel-app-main-sidebar-nav"
+    >
+      <ul className={isCollapsed ? SIDEBAR_RAIL_STACK_CLASS : "space-y-0.5"}>
+        {entries.map((entry) => (
+          <li
+            key={entry.appId}
+            className={isCollapsed ? "flex justify-center" : undefined}
+          >
+            <SidebarNavLinkItem
+              to={`/apps/panel/${encodeURIComponent(entry.appId)}`}
+              label={entry.title}
+              iconNode={(
+                <PanelAppIcon
+                  icon={entry.icon}
+                  title={entry.title}
+                  className="h-full w-full text-[13px]"
+                  imageClassName="rounded-[3px]"
+                />
+              )}
+              density="compact"
+              collapsed={isCollapsed}
+              className={isCollapsed ? undefined : "rounded-lg px-2.5 py-1.5"}
+            />
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/src/features/panel-apps/components/panel-app-toolbar.tsx

@@ -1,43 +1,104 @@
-import { ArrowLeft, RefreshCw } from 'lucide-react';
+import { useMemo, useState } from 'react';
+import { MoreVertical, PanelLeft, PanelLeftDashed, RefreshCw } from 'lucide-react';
+import { usePanelApps, useUpdatePanelAppPreferences } from '@/features/panel-apps/hooks/use-panel-apps';
+import { IconActionButton } from '@/shared/components/ui/actions/icon-action-button';
+import { Popover, PopoverContent, PopoverTrigger } from '@/shared/components/ui/popover';
 import { t } from '@/shared/lib/i18n';
 
 type PanelAppToolbarProps = {
   appTitle: string;
-  onOpenApps: () => void;
+  mainSidebar?: boolean;
+  mainSidebarPending?: boolean;
   onRefresh: () => void;
+  onToggleMainSidebar?: () => void;
 };
 
 export function PanelAppToolbar({
   appTitle,
-  onOpenApps,
+  mainSidebar = false,
+  mainSidebarPending = false,
   onRefresh,
+  onToggleMainSidebar,
 }: PanelAppToolbarProps) {
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+  const mainSidebarLabel = mainSidebar
+    ? t('panelAppsRemoveFromMainSidebar')
+    : t('panelAppsAddToMainSidebar');
+
   return (
     <div className="flex items-center justify-between gap-2 border-b border-border/70 bg-card px-3.5 py-2 shrink-0">
-      <button
-        type="button"
-        onClick={onOpenApps}
-        className="inline-flex shrink-0 items-center rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-[var(--interaction-hover)] hover:text-accent-foreground"
-        title={t('appsTitle')}
-        aria-label={t('appsTitle')}
-      >
-        <ArrowLeft className="h-3.5 w-3.5" />
-      </button>
       <span
         className="min-w-0 flex-1 truncate text-xs font-medium text-muted-foreground"
         title={appTitle}
       >
         {appTitle}
       </span>
-      <button
-        type="button"
+      {onToggleMainSidebar ? (
+        <Popover open={isMenuOpen} onOpenChange={setIsMenuOpen}>
+          <PopoverTrigger asChild>
+            <IconActionButton
+              icon={<MoreVertical className="h-3.5 w-3.5" />}
+              label={t('panelAppsMoreActions')}
+              size="sm"
+            />
+          </PopoverTrigger>
+          <PopoverContent align="end" className="w-48 rounded-xl p-1.5">
+            <button
+              type="button"
+              disabled={mainSidebarPending}
+              aria-pressed={mainSidebar}
+              className="flex w-full items-center gap-2 rounded-lg px-2.5 py-2 text-left text-sm text-muted-foreground transition-colors hover:bg-[var(--interaction-hover)] hover:text-accent-foreground disabled:cursor-not-allowed disabled:opacity-50"
+              onClick={() => {
+                setIsMenuOpen(false);
+                onToggleMainSidebar();
+              }}
+            >
+              {mainSidebar
+                ? <PanelLeftDashed className="h-4 w-4 shrink-0" />
+                : <PanelLeft className="h-4 w-4 shrink-0" />}
+              <span>{mainSidebarLabel}</span>
+            </button>
+          </PopoverContent>
+        </Popover>
+      ) : null}
+      <IconActionButton
+        icon={<RefreshCw className="h-3.5 w-3.5" />}
+        label={t('panelAppsRefreshCurrent')}
         onClick={onRefresh}
-        className="rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-[var(--interaction-hover)] hover:text-accent-foreground"
-        title={t('panelAppsRefreshCurrent')}
-        aria-label={t('panelAppsRefreshCurrent')}
-      >
-        <RefreshCw className="h-3.5 w-3.5" />
-      </button>
+        size="sm"
+      />
     </div>
   );
 }
+
+export function PanelAppDocBrowserToolbar({
+  appId,
+  appTitle,
+  onRefresh,
+}: {
+  appId: string | null;
+  appTitle: string;
+  onRefresh: () => void;
+}) {
+  const panelApps = usePanelApps();
+  const updatePreferences = useUpdatePanelAppPreferences();
+  const entry = useMemo(
+    () => panelApps.data?.entries.find((candidate) => candidate.appId === appId),
+    [appId, panelApps.data?.entries],
+  );
+
+  return (
+    <PanelAppToolbar
+      appTitle={entry?.title ?? appTitle}
+      mainSidebar={entry?.mainSidebar}
+      mainSidebarPending={updatePreferences.isPending}
+      onRefresh={onRefresh}
+      onToggleMainSidebar={entry
+        ? () => updatePreferences.mutate({
+            id: entry.id,
+            preferences: { mainSidebar: !entry.mainSidebar },
+          })
+        : undefined}
+    />
+  );
+}

package/src/features/panel-apps/components/panel-apps-list.tsx

@@ -3,7 +3,8 @@ import { AppWindow, FileCode2, HelpCircle, MessageSquarePlus, RefreshCw } from '
 import { useNavigate } from 'react-router-dom';
 import { useAppPresenter } from '@/app/components/app-presenter-provider';
 import { PanelAppListItem } from '@/features/panel-apps/components/panel-app-list-item';
-import { useDeletePanelApp, useGrantPanelAppClient, usePanelApps, useRecordPanelAppOpened, useUpdatePanelAppPreferences } from '@/features/panel-apps/hooks/use-panel-apps';
+import { usePanelAppClientGrant } from '@/features/panel-apps/hooks/use-panel-app-client-grant';
+import { useDeletePanelApp, usePanelApps, useRecordPanelAppOpened, useUpdatePanelAppPreferences } from '@/features/panel-apps/hooks/use-panel-apps';
 import { getPanelAppViewEntries } from '@/features/panel-apps/utils/panel-app-view.utils';
 import type { PanelAppViewMode } from '@/features/panel-apps/utils/panel-app-view.utils';
 import type { PanelAppEntryView } from '@/shared/lib/api';
@@ -22,7 +23,7 @@ export function PanelAppsList({
   const deletePanelApp = useDeletePanelApp();
   const updatePreferences = useUpdatePanelAppPreferences();
   const recordOpened = useRecordPanelAppOpened();
-  const grantClient = useGrantPanelAppClient();
+  const { ensurePanelAppClientGrant } = usePanelAppClientGrant();
   const presenter = useAppPresenter();
   const navigate = useNavigate();
   const [viewMode, setViewMode] = useState<PanelAppViewMode>('smart');
@@ -36,37 +37,21 @@ export function PanelAppsList({
     if (!(await ensurePanelAppClientGrant(entry))) {
       return;
     }
-    try {
-      onOpenPanelApp(await recordOpened.mutateAsync(entry.id));
-    } catch {
-      onOpenPanelApp(entry);
-    }
+    onOpenPanelApp(entry);
+    recordOpened.mutate(entry.id);
   };
 
-  const ensurePanelAppClientGrant = async (entry: PanelAppEntryView): Promise<boolean> => {
-    if (!entry.clientDeclared || entry.clientGranted) {
-      return true;
-    }
-    const allowed = await presenter.serviceActionAuthorizationManager.requestAuthorization({
-      panelAppId: entry.appId,
-      actions: [{
-        actionId: 'nextclaw.client',
-        actionTitle: t('panelAppsClientGrantTitle'),
-        actionDescription: t('panelAppsClientGrantDescription'),
-        risk: 'dangerous',
-      }],
+  const toggleFavorite = (entry: PanelAppEntryView) => {
+    updatePreferences.mutate({
+      id: entry.id,
+      preferences: { favorite: !entry.favorite },
     });
-    if (!allowed) {
-      return false;
-    }
-    await grantClient.mutateAsync(entry.appId);
-    return true;
   };
 
-  const toggleFavorite = (entry: PanelAppEntryView) => {
+  const toggleMainSidebar = (entry: PanelAppEntryView) => {
     updatePreferences.mutate({
       id: entry.id,
-      preferences: { favorite: !entry.favorite },
+      preferences: { mainSidebar: !entry.mainSidebar },
     });
   };
 
@@ -144,9 +129,11 @@ export function PanelAppsList({
                 entry={entry}
                 deletePending={deletePanelApp.isPending}
                 favoritePending={updatePreferences.isPending}
+                mainSidebarPending={updatePreferences.isPending}
                 onDelete={() => deleteEntry(entry)}
                 onOpen={() => void openPanelApp(entry)}
                 onToggleFavorite={() => toggleFavorite(entry)}
+                onToggleMainSidebar={() => toggleMainSidebar(entry)}
               />
             ))}
           </div>

package/src/features/panel-apps/hooks/__tests__/use-panel-apps.test.tsx

@@ -0,0 +1,105 @@
+import type { ReactNode } from 'react';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { useUpdatePanelAppPreferences } from '@/features/panel-apps/hooks/use-panel-apps';
+import type { PanelAppEntryView, PanelAppListView } from '@/shared/lib/api';
+import type * as SharedApi from '@/shared/lib/api';
+
+const mocks = vi.hoisted(() => ({
+  updatePreferences: vi.fn(),
+}));
+
+vi.mock('@/shared/lib/api', async (importOriginal) => {
+  const original = await importOriginal<typeof SharedApi>();
+  return {
+    ...original,
+    nextclawClient: {
+      ...original.nextclawClient,
+      panelApps: {
+        ...original.nextclawClient.panelApps,
+        updatePanelAppPreferences: mocks.updatePreferences,
+      },
+    },
+  };
+});
+
+vi.mock('sonner', () => ({ toast: { error: vi.fn() } }));
+
+const entry: PanelAppEntryView = {
+  id: 'todo',
+  appId: 'publisher.todo',
+  fileName: 'todo',
+  kind: 'folder',
+  title: 'Todo',
+  contentPath: '/api/panel-apps/publisher.todo/content',
+  createdAt: '2026-08-19T00:00:00.000Z',
+  updatedAt: '2026-08-19T00:00:00.000Z',
+  sizeBytes: 1,
+  favorite: false,
+  mainSidebar: false,
+  clientDeclared: false,
+  clientGranted: false,
+  openCount: 0,
+};
+
+function createHarness() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  queryClient.setQueryData<PanelAppListView>(['panel-apps'], {
+    workspacePath: '/workspace',
+    panelsPath: '/workspace/panels',
+    entries: [entry],
+  });
+  return {
+    queryClient,
+    wrapper: ({ children }: { children: ReactNode }) => (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    ),
+  };
+}
+
+describe('useUpdatePanelAppPreferences', () => {
+  beforeEach(() => {
+    mocks.updatePreferences.mockReset();
+  });
+
+  it('updates the main-sidebar cache before local persistence completes', async () => {
+    let resolveRequest: (value: PanelAppEntryView) => void = () => undefined;
+    mocks.updatePreferences.mockReturnValue(new Promise((resolve) => {
+      resolveRequest = resolve;
+    }));
+    const { queryClient, wrapper } = createHarness();
+    const { result } = renderHook(() => useUpdatePanelAppPreferences(), { wrapper });
+
+    act(() => result.current.mutate({
+      id: entry.id,
+      preferences: { mainSidebar: true },
+    }));
+
+    await waitFor(() => expect(
+      queryClient.getQueryData<PanelAppListView>(['panel-apps'])?.entries[0]?.mainSidebar,
+    ).toBe(true));
+    expect(result.current.isPending).toBe(true);
+
+    resolveRequest({ ...entry, mainSidebar: true, mainSidebarOrder: 0 });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  });
+
+  it('rolls the optimistic entry back when persistence fails', async () => {
+    mocks.updatePreferences.mockRejectedValue(new Error('write failed'));
+    const { queryClient, wrapper } = createHarness();
+    const { result } = renderHook(() => useUpdatePanelAppPreferences(), { wrapper });
+
+    act(() => result.current.mutate({
+      id: entry.id,
+      preferences: { mainSidebar: true },
+    }));
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(
+      queryClient.getQueryData<PanelAppListView>(['panel-apps'])?.entries[0]?.mainSidebar,
+    ).toBe(false);
+  });
+});