@nextclaw/ui 0.15.1 → 0.15.3

package/src/shared/components/doc-browser/doc-browser.tsx

@@ -1,7 +1,8 @@
 import { useState, useRef, useCallback, useEffect } from 'react';
 import {
-  DOCS_DEFAULT_BASE_URL,
   DOC_BROWSER_HOME_TAB_KIND,
+  getDefaultDocsUrl,
+  getDocsUrl,
   type DocBrowserDockControls,
   type DocBrowserDockState,
   type DocBrowserTab,
@@ -137,11 +138,11 @@ function useDocBrowserAddressBar({
     const input = urlInput.trim();
     if (!input) return;
     if (isDocsTab && input.startsWith('/')) {
-      navigate(`${DOCS_DEFAULT_BASE_URL}${input}`);
+      navigate(getDocsUrl(input));
     } else if (isDocsTab && input.startsWith('http')) {
       navigate(input);
     } else if (isDocsTab) {
-      navigate(`${DOCS_DEFAULT_BASE_URL}/${input}`);
+      navigate(getDocsUrl(`/${input}`));
     } else {
       navigate(resolveContentUrlInput(input, currentUrl));
     }
@@ -180,7 +181,7 @@ export function DocBrowser({ customTabRenderers = {}, displayMode = 'desktop', d
   const [floatRect, setFloatRect] = useState<FloatingPanelRect>(createInitialFloatingPanelRect);
   const [floatInteraction, setFloatInteraction] = useState<FloatingPanelInteraction | null>(null);
   const iframeRef = useRef<HTMLIFrameElement>(null);
-  const currentUrl = currentTab?.currentUrl ?? DOCS_DEFAULT_BASE_URL;
+  const currentUrl = currentTab?.currentUrl ?? getDefaultDocsUrl();
   const navVersion = currentTab?.navVersion ?? 0;
   const iframeInstanceId = `${activeTabId}:${navVersion}:${iframeReloadVersion}`;
   const pendingParentDocsUrlRef = useRef<string | null>(null);
@@ -374,6 +375,7 @@ export function DocBrowser({ customTabRenderers = {}, displayMode = 'desktop', d
         iframeSandbox={iframeSandbox}
         isDragging={floatInteraction?.kind === 'drag'}
         isResizing={floatInteraction?.kind === 'resize'}
+        onIframePointerOver={customRenderer?.onIframePointerOver}
       />
 
       <DocBrowserExternalLink currentUrl={currentUrl} isVisible={isDocsTab || isContentTab} />

package/src/shared/components/doc-browser/utils/doc-browser-url.utils.ts

@@ -2,15 +2,19 @@ import { getLanguage, type I18nLanguage } from '@/shared/lib/i18n';
 import type { DocBrowserTabKind } from '@/shared/components/doc-browser/types/doc-browser.types';
 
 const DOCS_PRIMARY_DOMAIN = 'docs.nextclaw.io';
+const DOCS_MAINLAND_DOMAIN = 'docs.nextclaw.net';
 const DOCS_PAGES_DEV = 'nextclaw-docs.pages.dev';
 const DOCS_HOSTS = new Set([
   DOCS_PRIMARY_DOMAIN,
   `www.${DOCS_PRIMARY_DOMAIN}`,
+  DOCS_MAINLAND_DOMAIN,
+  `www.${DOCS_MAINLAND_DOMAIN}`,
   DOCS_PAGES_DEV,
   `www.${DOCS_PAGES_DEV}`,
 ]);
 
 export const DOCS_DEFAULT_BASE_URL = `https://${DOCS_PRIMARY_DOMAIN}`;
+export const DOCS_MAINLAND_BASE_URL = `https://${DOCS_MAINLAND_DOMAIN}`;
 export const DOC_BROWSER_HOME_TAB_KIND = 'home';
 export const DOC_BROWSER_HOME_URL = 'nextclaw://new-tab';
 const DOCS_DEFAULT_GUIDE_PATH = '/guide/getting-started';
@@ -33,19 +37,68 @@ function ensureLocalizedDocsPath(pathname: string, locale: 'en' | 'zh'): string
   return `/${locale}${normalized}`;
 }
 
+function normalizeDocsBaseUrl(value?: string): string | undefined {
+  const raw = value?.trim();
+  if (!raw) {
+    return undefined;
+  }
+
+  try {
+    return new URL(raw).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+function getBrowserTimeZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone ?? '';
+  } catch {
+    return '';
+  }
+}
+
+function isAbsoluteUrl(value: string): boolean {
+  return /^[a-z][a-z\d+.-]*:/i.test(value.trim());
+}
+
+function isLikelyMainlandDocsAudience(): boolean {
+  return getLanguage() === 'zh' || getBrowserTimeZone() === 'Asia/Shanghai';
+}
+
+export function getDocsBaseUrl(): string {
+  const configuredBaseUrl = normalizeDocsBaseUrl(import.meta.env.VITE_NEXTCLAW_DOCS_BASE_URL);
+  if (configuredBaseUrl) {
+    return configuredBaseUrl;
+  }
+
+  if (isLikelyMainlandDocsAudience()) {
+    return normalizeDocsBaseUrl(import.meta.env.VITE_NEXTCLAW_DOCS_CN_BASE_URL) ?? DOCS_MAINLAND_BASE_URL;
+  }
+
+  return DOCS_DEFAULT_BASE_URL;
+}
+
 function resolveLocalizedDocsUrl(url: string): string {
   const locale = toDocsLocale(getLanguage());
+  const docsBaseUrl = getDocsBaseUrl();
 
   try {
-    const parsed = new URL(url, DOCS_DEFAULT_BASE_URL);
-    if (!DOCS_HOSTS.has(parsed.hostname)) {
+    const parsed = new URL(url, docsBaseUrl);
+    const docsBase = new URL(docsBaseUrl);
+    const shouldResolveAsDocs = !isAbsoluteUrl(url)
+      || DOCS_HOSTS.has(parsed.hostname)
+      || parsed.origin === docsBase.origin;
+    if (!shouldResolveAsDocs) {
       return parsed.toString();
     }
 
+    parsed.protocol = docsBase.protocol;
+    parsed.host = docsBase.host;
     parsed.pathname = ensureLocalizedDocsPath(parsed.pathname, locale);
     return parsed.toString();
   } catch {
-    return new URL(`/${locale}${DOCS_DEFAULT_GUIDE_PATH}`, DOCS_DEFAULT_BASE_URL).toString();
+    return new URL(`/${locale}${DOCS_DEFAULT_GUIDE_PATH}`, docsBaseUrl).toString();
   }
 }
 
@@ -53,6 +106,10 @@ export function getDefaultDocsUrl(): string {
   return resolveLocalizedDocsUrl(DOCS_DEFAULT_GUIDE_PATH);
 }
 
+export function getDocsUrl(pathOrUrl: string): string {
+  return resolveLocalizedDocsUrl(pathOrUrl);
+}
+
 export function normalizeDocUrl(url: string): string {
   try {
     return new URL(url).pathname.replace(/\.html$/, '').replace(/\/$/, '');
@@ -78,7 +135,8 @@ export function inferTabTitle(url: string, kind: DocBrowserTabKind, fallback = '
 
 export function isDocsUrl(url: string): boolean {
   try {
-    const parsed = new URL(url, window.location.origin);
+    const fallbackOrigin = typeof window !== 'undefined' ? window.location.origin : DOCS_DEFAULT_BASE_URL;
+    const parsed = new URL(url, fallbackOrigin);
     return DOCS_HOSTS.has(parsed.hostname);
   } catch {
     return false;

package/src/shared/components/resizable-right-panel/__tests__/resizable-right-panel.test.tsx

@@ -63,4 +63,22 @@ describe("ResizableRightPanel", () => {
     ).toBeNull();
     expect(screen.getByTestId("right-panel").className).toContain("fixed");
   });
+
+  it("can scope overlay positioning to its container", () => {
+    render(
+      <ResizableRightPanel
+        data-testid="right-panel"
+        overlay
+        overlayScope="container"
+      >
+        Content
+      </ResizableRightPanel>,
+    );
+
+    expect(
+      screen.queryByTestId("resizable-right-panel-handle"),
+    ).toBeNull();
+    expect(screen.getByTestId("right-panel").className).toContain("absolute");
+    expect(screen.getByTestId("right-panel").className).not.toContain("fixed");
+  });
 });

package/src/shared/components/resizable-right-panel/resizable-right-panel.tsx

@@ -1,12 +1,33 @@
 import { useRef, useState, type ComponentPropsWithoutRef } from "react";
 import { cn } from "@/shared/lib/utils";
 
-type ResizableRightPanelProps = ComponentPropsWithoutRef<"aside"> & { defaultWidth?: number; minWidth?: number; maxWidth?: number; overlay?: boolean };
+type ResizableRightPanelProps = ComponentPropsWithoutRef<"aside"> & {
+  defaultWidth?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  overlay?: boolean;
+  overlayScope?: "viewport" | "container";
+};
 
-export function ResizableRightPanel({ children, className, style, defaultWidth = 420, minWidth = 320, maxWidth = 860, overlay = false, ...props }: ResizableRightPanelProps) {
+export function ResizableRightPanel({
+  children,
+  className,
+  style,
+  defaultWidth = 420,
+  minWidth = 320,
+  maxWidth = 860,
+  overlay = false,
+  overlayScope = "viewport",
+  ...props
+}: ResizableRightPanelProps) {
   const resizeRef = useRef<{ startX: number; startWidth: number } | null>(null);
   const [isResizing, setIsResizing] = useState(false);
   const [width, setWidth] = useState(defaultWidth);
+  const overlayClassName = overlay
+    ? overlayScope === "container"
+      ? "absolute inset-0 z-30"
+      : "fixed inset-0 z-40"
+    : "border-l border-border";
 
   const onResizeStart = (event: React.PointerEvent<HTMLDivElement>) => {
     if (overlay) return;
@@ -36,7 +57,11 @@ export function ResizableRightPanel({ children, className, style, defaultWidth =
   return (
     <aside
       {...props}
-      className={cn("relative flex h-full min-h-0 shrink-0 overflow-hidden bg-card text-card-foreground", overlay ? "fixed inset-0 z-40" : "border-l border-border", className)}
+      className={cn(
+        "relative flex h-full min-h-0 shrink-0 overflow-hidden bg-card text-card-foreground",
+        overlayClassName,
+        className,
+      )}
       style={overlay ? style : { ...style, width }}
     >
       {!overlay ? (

package/src/shared/components/ui/actions/__tests__/icon-action-button.test.tsx

@@ -0,0 +1,36 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { IconActionButton } from '@/shared/components/ui/actions/icon-action-button';
+
+describe('IconActionButton', () => {
+  it('applies compact size and strong tone classes for nested hover surfaces', () => {
+    render(
+      <IconActionButton
+        size="sm"
+        tone="strong"
+        icon={<span data-testid="icon" />}
+        label="Pin"
+      />,
+    );
+
+    const button = screen.getByRole('button', { name: 'Pin' });
+    expect(button.className).toContain('h-6');
+    expect(button.className).toContain('w-6');
+    expect(button.className).toContain('p-1');
+    expect(button.className).toContain('hover:bg-black/10');
+  });
+
+  it('defaults to medium size and soft accent hover', () => {
+    render(
+      <IconActionButton
+        icon={<span data-testid="icon" />}
+        label="More"
+      />,
+    );
+
+    const button = screen.getByRole('button', { name: 'More' });
+    expect(button.className).toContain('h-7');
+    expect(button.className).toContain('w-7');
+    expect(button.className).toContain('hover:bg-accent');
+  });
+});

package/src/shared/components/ui/actions/form-actions.tsx

@@ -0,0 +1,25 @@
+import type { HTMLAttributes } from 'react';
+import { cn } from '@/shared/lib/utils';
+
+type FormActionsProps = HTMLAttributes<HTMLDivElement> & {
+  align?: 'start' | 'end' | 'between';
+};
+
+export function FormActions({
+  align = 'end',
+  className,
+  ...props
+}: FormActionsProps) {
+  return (
+    <div
+      className={cn(
+        'flex flex-wrap items-center gap-2',
+        align === 'start' && 'justify-start',
+        align === 'end' && 'justify-end',
+        align === 'between' && 'justify-between',
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/src/shared/components/ui/actions/icon-action-button.tsx

@@ -7,16 +7,35 @@ import {
 } from '@/shared/components/ui/tooltip';
 import { cn } from '@/shared/lib/utils';
 
+type IconActionButtonSize = 'sm' | 'md' | 'lg';
+type IconActionButtonTone = 'default' | 'strong';
+
 type IconActionButtonProps = Omit<
   React.ButtonHTMLAttributes<HTMLButtonElement>,
   'children' | 'type'
 > & {
   icon: React.ReactNode;
   label: string;
+  size?: IconActionButtonSize;
+  /** default: soft accent hover. strong: denser gray hover for nested hover surfaces. */
+  tone?: IconActionButtonTone;
   tooltip?: string | false | null;
   tooltipSide?: 'top' | 'right' | 'bottom' | 'left';
 };
 
+const SIZE_CLASS: Record<IconActionButtonSize, string> = {
+  sm: 'h-6 w-6 rounded-md p-1',
+  md: 'h-7 w-7 rounded-md p-1.5',
+  lg: 'h-8 w-8 rounded-lg p-1.5',
+};
+
+const TONE_CLASS: Record<IconActionButtonTone, string> = {
+  default:
+    'text-muted-foreground hover:bg-accent hover:text-accent-foreground disabled:text-muted-foreground/45 disabled:hover:bg-transparent disabled:hover:text-muted-foreground/45',
+  strong:
+    'text-muted-foreground hover:bg-black/10 hover:text-foreground disabled:text-muted-foreground/45 disabled:hover:bg-transparent disabled:hover:text-muted-foreground/45',
+};
+
 const IconActionButton = React.forwardRef<HTMLButtonElement, IconActionButtonProps>(
   (
     {
@@ -24,6 +43,8 @@ const IconActionButton = React.forwardRef<HTMLButtonElement, IconActionButtonPro
       disabled = false,
       icon,
       label,
+      size = 'md',
+      tone = 'default',
       tooltip,
       tooltipSide = 'bottom',
       ...buttonProps
@@ -38,8 +59,9 @@ const IconActionButton = React.forwardRef<HTMLButtonElement, IconActionButtonPro
         disabled={disabled}
         aria-label={label}
         className={cn(
-          'inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 disabled:cursor-not-allowed',
-          'text-muted-foreground hover:bg-accent hover:text-accent-foreground disabled:text-muted-foreground/45 disabled:hover:bg-transparent disabled:hover:text-muted-foreground/45',
+          'inline-flex shrink-0 items-center justify-center transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-border disabled:cursor-not-allowed',
+          SIZE_CLASS[size],
+          TONE_CLASS[tone],
           className
         )}
       >
@@ -63,3 +85,4 @@ const IconActionButton = React.forwardRef<HTMLButtonElement, IconActionButtonPro
 IconActionButton.displayName = 'IconActionButton';
 
 export { IconActionButton };
+export type { IconActionButtonProps, IconActionButtonSize, IconActionButtonTone };

package/src/shared/components/ui/button.tsx

@@ -3,7 +3,7 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '@/shared/lib/utils';
 
 const buttonVariants = cva(
-  'inline-flex items-center justify-center whitespace-nowrap rounded-full text-sm font-medium ring-offset-background transition-colors duration-fast focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  'inline-flex items-center justify-center whitespace-nowrap rounded-full text-sm font-medium ring-offset-background transition-colors duration-fast focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-border disabled:pointer-events-none disabled:opacity-50',
   {
     variants: {
       variant: {

package/src/shared/components/ui/card.tsx

@@ -3,13 +3,21 @@ import { cn } from '@/shared/lib/utils';
 
 const Card = React.forwardRef<
   HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement> & { hover?: boolean }
->(({ className, hover = true, ...props }, ref) => (
+  React.HTMLAttributes<HTMLDivElement> & {
+    hover?: boolean;
+    /** Flat settings-style surface: light border, no shadow. */
+    surface?: 'raised' | 'flat';
+  }
+>(({ className, hover = true, surface = 'raised', ...props }, ref) => (
   <div
     ref={ref}
     className={cn(
-      'rounded-2xl border border-border bg-card text-card-foreground shadow-card transition-all duration-base',
-      hover && 'hover:border-primary/25 hover:shadow-card-hover',
+      'rounded-2xl border bg-card text-card-foreground transition-colors duration-base',
+      surface === 'raised'
+        ? 'border-border shadow-card'
+        : 'border-border/75 shadow-none',
+      hover && surface === 'raised' && 'hover:border-primary/25 hover:shadow-card-hover',
+      hover && surface === 'flat' && 'hover:bg-muted/40',
       className
     )}
     {...props}

package/src/shared/components/ui/dialog.tsx

@@ -42,7 +42,7 @@ const DialogContent = React.forwardRef<
       {...props}
     >
       {children}
-      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-lg p-1 opacity-70 ring-offset-background transition-all duration-fast hover:bg-accent hover:text-accent-foreground hover:opacity-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 disabled:pointer-events-none">
+      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-lg p-1 opacity-70 transition-all duration-fast hover:bg-accent hover:text-accent-foreground hover:opacity-100 focus:outline-none focus-visible:ring-1 focus-visible:ring-border disabled:pointer-events-none">
         <X className="h-4 w-4 text-muted-foreground" />
         <span className="sr-only">Close</span>
       </DialogPrimitive.Close>

package/src/shared/components/ui/input.tsx

@@ -9,7 +9,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
       <input
         type={type}
         className={cn(
-          'flex h-9 w-full rounded-xl border border-border bg-card px-3.5 py-2 text-sm text-foreground file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground/55 placeholder:font-normal focus:outline-none focus:ring-1 focus:ring-primary/40 focus:border-primary/50 transition-colors disabled:cursor-not-allowed disabled:opacity-50',
+          'flex h-9 w-full rounded-xl border border-border/75 bg-card px-3.5 py-2 text-sm text-foreground file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground/55 placeholder:font-normal transition-colors focus:outline-none focus:ring-0 focus:border-border disabled:cursor-not-allowed disabled:opacity-50',
           className
         )}
         ref={ref}

package/src/shared/components/ui/select.tsx

@@ -25,7 +25,7 @@ const SelectTrigger = React.forwardRef<
     <SelectPrimitive.Trigger
         ref={ref}
         className={cn(
-            "flex h-9 w-full items-center justify-between whitespace-nowrap rounded-xl border border-border bg-card px-3 py-2 text-sm text-foreground shadow-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-primary/40 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1",
+            "flex h-9 w-full items-center justify-between whitespace-nowrap rounded-xl border border-border/75 bg-card px-3 py-2 text-sm text-foreground ring-offset-background placeholder:text-muted-foreground transition-colors focus:outline-none focus:ring-0 focus:border-border disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1",
             className
         )}
         {...props}

package/src/shared/components/ui/switch.tsx

@@ -17,7 +17,7 @@ const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(
         data-state={checked ? 'checked' : 'unchecked'}
         ref={ref}
         className={cn(
-          'switch-track peer inline-flex h-[22px] w-10 shrink-0 cursor-pointer items-center rounded-full border-2 transition-colors duration-fast focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50',
+          'switch-track peer inline-flex h-[22px] w-10 shrink-0 cursor-pointer items-center rounded-full border-2 transition-colors duration-fast focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-border disabled:cursor-not-allowed disabled:opacity-50',
           checked ? 'border-primary/70 bg-primary' : 'border-border/60 bg-muted hover:bg-accent',
           className
         )}

package/src/shared/components/ui/tab-strip/compact-tab-strip.tsx

@@ -147,11 +147,12 @@ function CompactTabItem({
       <CompactTabLabelButton tab={tab} labelClassName={labelClassName} />
       {tab.onClose && tab.closePlacement !== "leading-hover" ? (
         <IconActionButton
+          size="sm"
+          tone="strong"
           icon={<X className="h-3 w-3" />}
           label={tab.closeLabel ?? ""}
           tooltip={tab.closeLabel ?? null}
           onClick={(event) => closeCompactTab(event, tab.onClose!)}
-          className="h-5 w-5 rounded p-0.5 hover:bg-black/10"
         />
       ) : null}
     </div>

package/src/shared/components/ui/tabs.tsx

@@ -64,7 +64,7 @@ export function TabsTrigger({ value, children, className }: TabsTriggerProps) {
       aria-pressed={isActive}
       data-state={isActive ? 'active' : 'inactive'}
       className={cn(
-        'inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-[13px] font-medium ring-offset-background transition-all duration-fast focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+        'inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-[13px] font-medium transition-all duration-fast focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-border disabled:pointer-events-none disabled:opacity-50',
         isActive
           ? 'bg-card text-foreground shadow-sm'
           : 'text-muted-foreground hover:bg-accent hover:text-accent-foreground',

package/src/shared/components/ui/textarea.tsx

@@ -7,7 +7,7 @@ export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
   ({ className, ...props }, ref) => (
     <textarea
       className={cn(
-        "flex min-h-28 w-full rounded-xl border border-border bg-card px-3.5 py-2.5 text-sm text-foreground placeholder:text-muted-foreground/55 placeholder:font-normal focus:outline-none focus:ring-1 focus:ring-primary/40 focus:border-primary/50 transition-colors disabled:cursor-not-allowed disabled:opacity-50",
+        "flex min-h-28 w-full rounded-xl border border-border/75 bg-card px-3.5 py-2.5 text-sm text-foreground placeholder:text-muted-foreground/55 placeholder:font-normal transition-colors focus:outline-none focus:ring-0 focus:border-border disabled:cursor-not-allowed disabled:opacity-50",
         className,
       )}
       ref={ref}

package/src/shared/hooks/use-server-path-browse.ts

@@ -1,19 +1,41 @@
 import { useQuery } from '@tanstack/react-query';
 import { fetchServerPathBrowse } from '@/shared/lib/api';
 
+export function buildServerPathBrowseQueryKey(params: {
+  path?: string | null;
+  basePath?: string | null;
+  includeFiles?: boolean;
+}) {
+  return [
+    'server-path-browse',
+    params.path?.trim() ?? '',
+    params.basePath?.trim() ?? '',
+    params.includeFiles ?? false,
+  ] as const;
+}
+
 export function useServerPathBrowse(params: {
   path?: string | null;
+  basePath?: string | null;
   includeFiles?: boolean;
   enabled?: boolean;
 }) {
+  const { basePath, enabled, includeFiles, path } = params;
+  const normalizedPath = path?.trim() ?? '';
+  const normalizedBasePath = basePath?.trim() ?? '';
   return useQuery({
-    queryKey: ['server-path-browse', params.path ?? null, params.includeFiles ?? false],
+    queryKey: buildServerPathBrowseQueryKey({
+      path: normalizedPath,
+      basePath: normalizedBasePath,
+      includeFiles,
+    }),
     queryFn: () =>
       fetchServerPathBrowse({
-        path: params.path,
-        includeFiles: params.includeFiles,
+        path: normalizedPath,
+        basePath: normalizedBasePath,
+        includeFiles,
       }),
-    enabled: params.enabled ?? true,
+    enabled: enabled ?? true,
     staleTime: 0,
   });
 }

package/src/shared/hooks/use-server-path-read.ts

@@ -1,6 +1,13 @@
 import { useQuery } from '@tanstack/react-query';
 import { fetchServerPathRead } from '@/shared/lib/api';
 
+export function buildServerPathReadQueryKey(params: {
+  path?: string | null;
+  basePath?: string | null;
+}) {
+  return ['server-path-read', params.path?.trim() ?? '', params.basePath ?? null] as const;
+}
+
 export function useServerPathRead(params: {
   path?: string | null;
   basePath?: string | null;
@@ -8,7 +15,10 @@ export function useServerPathRead(params: {
 }) {
   const normalizedPath = params.path?.trim() ?? '';
   return useQuery({
-    queryKey: ['server-path-read', normalizedPath, params.basePath ?? null],
+    queryKey: buildServerPathReadQueryKey({
+      path: normalizedPath,
+      basePath: params.basePath,
+    }),
     queryFn: () =>
       fetchServerPathRead({
         path: normalizedPath,

package/src/shared/lib/api/utils/server-path.utils.ts

@@ -17,6 +17,7 @@ function encodeServerPathSegments(path: string): string {
 
 export async function fetchServerPathBrowse(params?: {
   path?: string | null;
+  basePath?: string | null;
   includeFiles?: boolean;
 }): Promise<ServerPathBrowseView> {
   return await nextclawClient.serverPaths.browse(params);