@nextclaw/ui 0.18.4 → 0.19.1

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);
+  });
+});

package/src/features/panel-apps/hooks/use-panel-app-client-grant.ts

@@ -0,0 +1,50 @@
+import { useCallback, useRef } from "react";
+import { useAppPresenter } from "@/app/components/app-presenter-provider";
+import { useGrantPanelAppClient } from "@/features/panel-apps/hooks/use-panel-apps";
+import type { PanelAppEntryView } from "@/shared/lib/api";
+import { t } from "@/shared/lib/i18n";
+
+export function usePanelAppClientGrant() {
+  const presenter = useAppPresenter();
+  const { isPending, mutateAsync: grantPanelAppClient } = useGrantPanelAppClient();
+  const pendingGrantsRef = useRef(new Map<string, Promise<boolean>>());
+
+  const ensurePanelAppClientGrant = useCallback(async (
+    entry: PanelAppEntryView,
+  ): Promise<boolean> => {
+    if (!entry.clientDeclared || entry.clientGranted) {
+      return true;
+    }
+    const pendingGrant = pendingGrantsRef.current.get(entry.appId);
+    if (pendingGrant) {
+      return await pendingGrant;
+    }
+    const grant = (async () => {
+      const allowed = await presenter.serviceActionAuthorizationManager.requestAuthorization({
+        panelAppId: entry.appId,
+        actions: [{
+          actionId: "nextclaw.client",
+          actionTitle: t("panelAppsClientGrantTitle"),
+          actionDescription: t("panelAppsClientGrantDescription"),
+          risk: "dangerous",
+        }],
+      });
+      if (!allowed) {
+        return false;
+      }
+      await grantPanelAppClient(entry.appId);
+      return true;
+    })();
+    pendingGrantsRef.current.set(entry.appId, grant);
+    try {
+      return await grant;
+    } finally {
+      pendingGrantsRef.current.delete(entry.appId);
+    }
+  }, [grantPanelAppClient, presenter]);
+
+  return {
+    ensurePanelAppClientGrant,
+    isPending,
+  };
+}

package/src/features/panel-apps/hooks/use-panel-app-main-runtime.ts

@@ -0,0 +1,66 @@
+import { useId } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { usePanelAppClientGrant } from "@/features/panel-apps/hooks/use-panel-app-client-grant";
+import {
+  PANEL_APPS_QUERY_KEY,
+  replacePanelAppListEntry,
+} from "@/features/panel-apps/hooks/use-panel-apps";
+import {
+  nextclawClient,
+  type PanelAppEntryView,
+  type PanelAppListView,
+} from "@/shared/lib/api";
+
+export type PanelAppMainRuntimeState = "allowed" | "checking" | "denied" | "error" | "idle";
+
+export function usePanelAppMainRuntime(entry: PanelAppEntryView | undefined) {
+  const queryClient = useQueryClient();
+  const runtimeInstanceId = useId();
+  const { ensurePanelAppClientGrant } = usePanelAppClientGrant();
+  const requiresClientGrant = Boolean(
+    entry?.clientDeclared && !entry.clientGranted,
+  );
+  const grantQuery = useQuery({
+    queryKey: [
+      "panel-app-main-client-grant",
+      entry?.appId ?? "none",
+      entry?.clientGranted ?? false,
+    ],
+    queryFn: async () => await ensurePanelAppClientGrant(entry!),
+    enabled: requiresClientGrant,
+    gcTime: 0,
+    retry: false,
+    staleTime: Number.POSITIVE_INFINITY,
+  });
+  const state: PanelAppMainRuntimeState = !entry
+    ? "idle"
+    : !requiresClientGrant
+      ? "allowed"
+      : grantQuery.isError
+        ? "error"
+        : grantQuery.isPending
+          ? "checking"
+          : grantQuery.data
+            ? "allowed"
+            : "denied";
+
+  useQuery({
+    queryKey: ["panel-app-main-open", runtimeInstanceId, entry?.appId ?? "none"],
+    queryFn: async () => {
+      const opened = await nextclawClient.panelApps.recordPanelAppOpened(entry!.id);
+      queryClient.setQueryData<PanelAppListView>(
+        PANEL_APPS_QUERY_KEY,
+        (current) => replacePanelAppListEntry(current, opened),
+      );
+      return opened;
+    },
+    enabled: Boolean(entry && state === "allowed"),
+    retry: false,
+    staleTime: Number.POSITIVE_INFINITY,
+  });
+
+  return {
+    retryClientGrant: grantQuery.refetch,
+    state,
+  };
+}

package/src/features/panel-apps/hooks/use-panel-apps.ts

@@ -1,8 +1,70 @@
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
 import { nextclawClient } from '@/shared/lib/api';
-import type { PanelAppPreferencesUpdateView } from '@/shared/lib/api';
+import type {
+  PanelAppEntryView,
+  PanelAppListView,
+  PanelAppPreferencesUpdateView,
+} from '@/shared/lib/api';
+import { t } from '@/shared/lib/i18n';
 
-const PANEL_APPS_QUERY_KEY = ['panel-apps'] as const;
+export const PANEL_APPS_QUERY_KEY = ['panel-apps'] as const;
+
+type PanelAppPreferencesMutation = {
+  id: string;
+  preferences: PanelAppPreferencesUpdateView;
+};
+
+function matchesPanelApp(entry: PanelAppEntryView, id: string): boolean {
+  return entry.id === id || entry.appId === id;
+}
+
+function updateCachedPanelApp(
+  current: PanelAppListView | undefined,
+  id: string,
+  update: (entry: PanelAppEntryView) => PanelAppEntryView,
+): PanelAppListView | undefined {
+  if (!current) {
+    return current;
+  }
+  return {
+    ...current,
+    entries: current.entries.map((entry) => matchesPanelApp(entry, id) ? update(entry) : entry),
+  };
+}
+
+export function replacePanelAppListEntry(
+  current: PanelAppListView | undefined,
+  entry: PanelAppEntryView,
+): PanelAppListView | undefined {
+  return updateCachedPanelApp(current, entry.id, () => entry);
+}
+
+function applyOptimisticPreferences(
+  current: PanelAppListView | undefined,
+  mutation: PanelAppPreferencesMutation,
+): PanelAppListView | undefined {
+  const nextMainSidebarOrder = current?.entries.reduce(
+    (maximum, entry) => Math.max(maximum, entry.mainSidebarOrder ?? -1),
+    -1,
+  ) ?? -1;
+  return updateCachedPanelApp(current, mutation.id, (entry) => ({
+    ...entry,
+    ...(typeof mutation.preferences.favorite === 'boolean'
+      ? { favorite: mutation.preferences.favorite }
+      : {}),
+    ...(typeof mutation.preferences.mainSidebar === 'boolean'
+      ? mutation.preferences.mainSidebar
+        ? {
+            mainSidebar: true,
+            mainSidebarOrder: entry.mainSidebar
+              ? entry.mainSidebarOrder
+              : nextMainSidebarOrder + 1,
+          }
+        : { mainSidebar: false, mainSidebarOrder: undefined }
+      : {}),
+  }));
+}
 
 export function usePanelApps(options: { enabled?: boolean } = {}) {
   return useQuery({
@@ -16,15 +78,39 @@ export function usePanelApps(options: { enabled?: boolean } = {}) {
 export function useUpdatePanelAppPreferences() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: ({
-      id,
-      preferences,
-    }: {
-      id: string;
-      preferences: PanelAppPreferencesUpdateView;
-    }) => nextclawClient.panelApps.updatePanelAppPreferences(id, preferences),
-    onSuccess: () => {
-      void queryClient.invalidateQueries({ queryKey: PANEL_APPS_QUERY_KEY });
+    mutationFn: ({ id, preferences }: PanelAppPreferencesMutation) =>
+      nextclawClient.panelApps.updatePanelAppPreferences(id, preferences),
+    onMutate: async (mutation) => {
+      await queryClient.cancelQueries({ queryKey: PANEL_APPS_QUERY_KEY });
+      const previousEntry = queryClient
+        .getQueryData<PanelAppListView>(PANEL_APPS_QUERY_KEY)
+        ?.entries.find((entry) => matchesPanelApp(entry, mutation.id));
+      queryClient.setQueryData<PanelAppListView>(
+        PANEL_APPS_QUERY_KEY,
+        (current) => applyOptimisticPreferences(current, mutation),
+      );
+      return { previousEntry };
+    },
+    onSuccess: (entry) => {
+      queryClient.setQueryData<PanelAppListView>(
+        PANEL_APPS_QUERY_KEY,
+        (current) => replacePanelAppListEntry(current, entry),
+      );
+    },
+    onError: (error, mutation, context) => {
+      const previousEntry = context?.previousEntry;
+      if (previousEntry) {
+        queryClient.setQueryData<PanelAppListView>(
+          PANEL_APPS_QUERY_KEY,
+          (current) => updateCachedPanelApp(
+            current,
+            mutation.id,
+            () => previousEntry,
+          ),
+        );
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      toast.error(`${t('panelAppsPreferenceUpdateFailed')}: ${message}`);
     },
   });
 }
@@ -33,8 +119,11 @@ export function useRecordPanelAppOpened() {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: (id: string) => nextclawClient.panelApps.recordPanelAppOpened(id),
-    onSuccess: () => {
-      void queryClient.invalidateQueries({ queryKey: PANEL_APPS_QUERY_KEY });
+    onSuccess: (entry) => {
+      queryClient.setQueryData<PanelAppListView>(
+        PANEL_APPS_QUERY_KEY,
+        (current) => replacePanelAppListEntry(current, entry),
+      );
     },
   });
 }

package/src/features/panel-apps/index.ts

@@ -1,4 +1,6 @@
 export { PanelAppsList } from './components/panel-apps-list';
+export { PanelAppMainSidebarNav } from './components/panel-app-main-sidebar-nav';
+export { PanelAppMainPage } from './pages/panel-app-main-page';
 export {
   useGrantPanelAppClient,
   usePanelApps,

package/src/features/panel-apps/managers/__tests__/panel-app-bridge.manager.test.ts

@@ -48,10 +48,7 @@ function createIframeHarness(manager: PanelAppBridgeManager) {
   const iframe = { contentWindow } as HTMLIFrameElement;
   return {
     postMessage,
-    send: (
-      data: Record<string, unknown>,
-      iframeInstanceId = 'tab-1:0:0',
-    ) => manager.handleIframeMessage({
+    send: (data: Record<string, unknown>) => manager.handleIframeMessage({
       event: {
         data: {
           appId: 'mood-calendar',
@@ -61,16 +58,6 @@ function createIframeHarness(manager: PanelAppBridgeManager) {
         source: contentWindow,
       } as MessageEvent,
       iframe,
-      iframeInstanceId,
-      tab: {
-        currentUrl: '/api/panel-apps/mood-calendar/content',
-        history: [],
-        historyIndex: 0,
-        id: 'tab-1',
-        kind: 'content',
-        navVersion: 0,
-        title: 'Mood Calendar',
-      },
     }),
   };
 }

package/src/features/panel-apps/managers/panel-app-bridge.manager.ts

@@ -11,9 +11,13 @@ import type {
   ServiceActionListView,
 } from '@nextclaw/client-sdk';
 import type { ServiceActionAuthorizationManager } from '@/features/service-apps';
-import type { DocBrowserIframeMessageParams } from '@/shared/components/doc-browser/doc-browser-renderer.types';
 import { nextclawClient } from '@/shared/lib/api';
 
+export type PanelAppIframeMessageParams = {
+  event: MessageEvent;
+  iframe: HTMLIFrameElement | null;
+};
+
 type PanelAppBridgeRequest = {
   type: 'nextclaw:panel-app-service-actions:request';
   requestId: string;
@@ -59,18 +63,18 @@ type PanelAppBridgeResponse =
 export class PanelAppBridgeManager {
   constructor(private readonly authorizationManager: ServiceActionAuthorizationManager) {}
 
-  handleIframeMessage = ({ event, iframe, iframeInstanceId, tab }: DocBrowserIframeMessageParams): void => {
+  handleIframeMessage = ({ event, iframe }: PanelAppIframeMessageParams): void => {
     if (!this.isBridgeRequest(event.data)) {
       return;
     }
     if (!iframe?.contentWindow || event.source !== iframe.contentWindow) {
       return;
     }
-    void this.handleBridgeRequest({ event, iframe, iframeInstanceId, tab }, event.data);
+    void this.handleBridgeRequest({ event, iframe }, event.data);
   };
 
   private handleBridgeRequest = async (
-    params: DocBrowserIframeMessageParams,
+    params: PanelAppIframeMessageParams,
     request: PanelAppBridgeRequest,
   ): Promise<void> => {
     try {
@@ -340,7 +344,7 @@ export class PanelAppBridgeManager {
   };
 
   private postResponse = (
-    params: DocBrowserIframeMessageParams,
+    params: PanelAppIframeMessageParams,
     response: PanelAppBridgeResponse,
   ): void => {
     params.iframe?.contentWindow?.postMessage(response, '*');

package/src/features/panel-apps/pages/__tests__/panel-app-main-page.test.tsx

@@ -0,0 +1,183 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter, Route, Routes } from "react-router-dom";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { PanelAppMainPage } from "@/features/panel-apps/pages/panel-app-main-page";
+import { PANEL_APP_IFRAME_SANDBOX } from "@/features/panel-apps/utils/panel-app-iframe.utils";
+import type { PanelAppEntryView } from "@/shared/lib/api";
+import type * as SharedApi from "@/shared/lib/api";
+
+const mocks = vi.hoisted(() => ({
+  bridgeMessage: vi.fn(),
+  ensureClientGrant: vi.fn(async () => true),
+  entries: [] as PanelAppEntryView[],
+  openApps: vi.fn(),
+  openTarget: vi.fn(),
+  recordOpenedApi: vi.fn(),
+  refetch: vi.fn(),
+  updatePreferences: vi.fn(),
+}));
+
+vi.mock("@/app/components/app-presenter-provider", () => ({
+  useAppPresenter: () => ({
+    panelAppBridgeManager: { handleIframeMessage: mocks.bridgeMessage },
+  }),
+}));
+
+vi.mock("@/features/panel-apps/hooks/use-panel-app-client-grant", () => ({
+  usePanelAppClientGrant: () => ({
+    ensurePanelAppClientGrant: mocks.ensureClientGrant,
+    isPending: false,
+  }),
+}));
+
+vi.mock("@/features/panel-apps/hooks/use-panel-apps", () => ({
+  usePanelApps: () => ({
+    data: { entries: mocks.entries },
+    error: null,
+    isError: false,
+    isLoading: false,
+    refetch: mocks.refetch,
+  }),
+  useUpdatePanelAppPreferences: () => ({
+    isPending: false,
+    mutate: mocks.updatePreferences,
+  }),
+}));
+
+vi.mock("@/shared/lib/api", async (importOriginal) => {
+  const actual = await importOriginal<typeof SharedApi>();
+  return {
+    ...actual,
+    nextclawClient: {
+      ...actual.nextclawClient,
+      panelApps: {
+        ...actual.nextclawClient.panelApps,
+        recordPanelAppOpened: mocks.recordOpenedApi,
+      },
+    },
+  };
+});
+
+vi.mock("@/shared/components/doc-browser", () => ({
+  useDocBrowser: () => ({ openTarget: mocks.openTarget }),
+}));
+
+vi.mock("@/features/panel-apps/utils/panel-app-doc-browser.utils", () => ({
+  openApps: mocks.openApps,
+}));
+
+function createEntry(overrides: Partial<PanelAppEntryView> = {}): PanelAppEntryView {
+  return {
+    appId: "publisher.todo",
+    clientDeclared: false,
+    clientGranted: false,
+    contentPath: "/api/panel-apps/publisher.todo/content",
+    createdAt: "2026-08-19T00:00:00.000Z",
+    favorite: false,
+    fileName: "todo.panel.html",
+    id: "todo",
+    kind: "single-file",
+    mainSidebar: true,
+    mainSidebarOrder: 0,
+    openCount: 0,
+    sizeBytes: 10,
+    title: "Rust Todo",
+    updatedAt: "2026-08-19T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+function createQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+}
+
+function renderPage(queryClient = createQueryClient()) {
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <MemoryRouter initialEntries={["/apps/panel/publisher.todo"]}>
+        <Routes>
+          <Route path="/apps/panel/:appId" element={<PanelAppMainPage />} />
+        </Routes>
+      </MemoryRouter>
+    </QueryClientProvider>,
+  );
+}
+
+describe("PanelAppMainPage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.entries = [createEntry()];
+    mocks.ensureClientGrant.mockResolvedValue(true);
+    mocks.recordOpenedApi.mockResolvedValue(createEntry());
+  });
+
+  it("hosts the selected app in the existing sandbox and records one open", async () => {
+    renderPage();
+
+    const iframe = await screen.findByTitle("Rust Todo");
+    expect(iframe.getAttribute("src")).toBe("/api/panel-apps/publisher.todo/content");
+    expect(iframe.getAttribute("sandbox")).toBe(PANEL_APP_IFRAME_SANDBOX);
+    await waitFor(() => expect(mocks.recordOpenedApi).toHaveBeenCalledWith("todo"));
+
+    fireEvent(window, new MessageEvent("message", { data: { type: "ignored" } }));
+    expect(mocks.bridgeMessage).toHaveBeenCalledWith(expect.objectContaining({
+      event: expect.any(MessageEvent),
+      iframe,
+    }));
+  });
+
+  it("renders the app edge-to-edge without a duplicate host header", async () => {
+    renderPage();
+    const iframe = await screen.findByTitle("Rust Todo");
+
+    expect(screen.queryByRole("heading", { name: "Rust Todo" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Open in right panel" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Refresh current panel app" })).toBeNull();
+    expect(iframe.parentElement?.children).toHaveLength(1);
+    expect(iframe.className).toContain("h-full");
+    expect(iframe.className).toContain("w-full");
+  });
+
+  it("does not mount a client-enabled app when authorization is denied", async () => {
+    mocks.entries = [createEntry({ clientDeclared: true })];
+    mocks.ensureClientGrant.mockResolvedValue(false);
+    renderPage();
+
+    expect(await screen.findByText(/required NextClaw Client permission was not granted/)).toBeTruthy();
+    expect(screen.queryByTitle("Rust Todo")).toBeNull();
+    expect(mocks.recordOpenedApi).not.toHaveBeenCalled();
+  });
+
+  it("does not reuse an old client grant decision across main-page instances", async () => {
+    const queryClient = createQueryClient();
+    mocks.entries = [createEntry({ clientDeclared: true })];
+    const first = renderPage(queryClient);
+    await screen.findByTitle("Rust Todo");
+    expect(mocks.ensureClientGrant).toHaveBeenCalledTimes(1);
+
+    first.unmount();
+    await waitFor(() => expect(queryClient.getQueryData([
+      "panel-app-main-client-grant",
+      "publisher.todo",
+      false,
+    ])).toBeUndefined());
+
+    renderPage(queryClient);
+    await screen.findByTitle("Rust Todo");
+    expect(mocks.ensureClientGrant).toHaveBeenCalledTimes(2);
+  });
+
+  it("shows a recoverable unavailable state for disabled or uninstalled apps", async () => {
+    const user = userEvent.setup();
+    mocks.entries = [];
+    renderPage();
+
+    expect(screen.getByText(/This panel app is unavailable/)).toBeTruthy();
+    await user.click(screen.getByRole("button", { name: "Open app management" }));
+    expect(mocks.openApps).toHaveBeenCalledTimes(1);
+  });
+});