@nextclaw/ui 0.15.3 → 0.15.4

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

@@ -12,8 +12,18 @@ import {
 } from './doc-browser-url.utils';
 import { t } from '@/shared/lib/i18n';
 
+export const DOC_BROWSER_DOCKED_DEFAULT_WIDTH = 420;
+export const DOC_BROWSER_DOCKED_MIN_WIDTH = 320;
+export const DOC_BROWSER_DOCKED_MAX_WIDTH = 860;
+
 let tabCounter = 0;
 
+export function normalizeDocBrowserDockedWidth(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.min(DOC_BROWSER_DOCKED_MAX_WIDTH, Math.max(DOC_BROWSER_DOCKED_MIN_WIDTH, value))
+    : DOC_BROWSER_DOCKED_DEFAULT_WIDTH;
+}
+
 function nextTabId(): string {
   tabCounter += 1;
   return `doc-tab-${Date.now()}-${tabCounter}`;
@@ -58,6 +68,7 @@ export function createDefaultDocBrowserState(): DocBrowserState {
   return {
     isOpen: false,
     mode: 'docked',
+    dockedWidth: DOC_BROWSER_DOCKED_DEFAULT_WIDTH,
     tabs: [initialTab],
     activeTabId: initialTab.id,
     activeHistory: [createDocBrowserActiveHistoryEntry(initialTab)],

package/src/shared/components/file-type-icon.tsx

@@ -0,0 +1,272 @@
+import { Icon, type IconifyIcon } from "@iconify/react";
+import defaultFileIcon from "@iconify/icons-vscode-icons/default-file";
+import audioIcon from "@iconify/icons-vscode-icons/file-type-audio";
+import bunIcon from "@iconify/icons-vscode-icons/file-type-bun";
+import configIcon from "@iconify/icons-vscode-icons/file-type-config";
+import cppIcon from "@iconify/icons-vscode-icons/file-type-cpp";
+import csharpIcon from "@iconify/icons-vscode-icons/file-type-csharp";
+import cssIcon from "@iconify/icons-vscode-icons/file-type-css";
+import dockerIcon from "@iconify/icons-vscode-icons/file-type-docker";
+import dotenvIcon from "@iconify/icons-vscode-icons/file-type-dotenv";
+import eslintIcon from "@iconify/icons-vscode-icons/file-type-eslint";
+import excelIcon from "@iconify/icons-vscode-icons/file-type-excel";
+import fontIcon from "@iconify/icons-vscode-icons/file-type-font";
+import gitIcon from "@iconify/icons-vscode-icons/file-type-git";
+import goIcon from "@iconify/icons-vscode-icons/file-type-go";
+import graphqlIcon from "@iconify/icons-vscode-icons/file-type-graphql";
+import htmlIcon from "@iconify/icons-vscode-icons/file-type-html";
+import imageIcon from "@iconify/icons-vscode-icons/file-type-image";
+import javaIcon from "@iconify/icons-vscode-icons/file-type-java";
+import javascriptIcon from "@iconify/icons-vscode-icons/file-type-js";
+import jsonIcon from "@iconify/icons-vscode-icons/file-type-json";
+import kotlinIcon from "@iconify/icons-vscode-icons/file-type-kotlin";
+import licenseIcon from "@iconify/icons-vscode-icons/file-type-license";
+import luaIcon from "@iconify/icons-vscode-icons/file-type-lua";
+import makefileIcon from "@iconify/icons-vscode-icons/file-type-makefile";
+import markdownIcon from "@iconify/icons-vscode-icons/file-type-markdown";
+import npmIcon from "@iconify/icons-vscode-icons/file-type-npm";
+import pdfIcon from "@iconify/icons-vscode-icons/file-type-pdf2";
+import phpIcon from "@iconify/icons-vscode-icons/file-type-php";
+import pnpmIcon from "@iconify/icons-vscode-icons/file-type-pnpm";
+import powerpointIcon from "@iconify/icons-vscode-icons/file-type-powerpoint";
+import prettierIcon from "@iconify/icons-vscode-icons/file-type-prettier";
+import pythonIcon from "@iconify/icons-vscode-icons/file-type-python";
+import reactJavascriptIcon from "@iconify/icons-vscode-icons/file-type-reactjs";
+import reactTypescriptIcon from "@iconify/icons-vscode-icons/file-type-reactts";
+import rubyIcon from "@iconify/icons-vscode-icons/file-type-ruby";
+import rustIcon from "@iconify/icons-vscode-icons/file-type-rust";
+import sassIcon from "@iconify/icons-vscode-icons/file-type-sass";
+import shellIcon from "@iconify/icons-vscode-icons/file-type-shell";
+import sqlIcon from "@iconify/icons-vscode-icons/file-type-sql";
+import svelteIcon from "@iconify/icons-vscode-icons/file-type-svelte";
+import svgIcon from "@iconify/icons-vscode-icons/file-type-svg";
+import swiftIcon from "@iconify/icons-vscode-icons/file-type-swift";
+import tailwindIcon from "@iconify/icons-vscode-icons/file-type-tailwind";
+import textIcon from "@iconify/icons-vscode-icons/file-type-text";
+import tomlIcon from "@iconify/icons-vscode-icons/file-type-toml";
+import tsconfigIcon from "@iconify/icons-vscode-icons/file-type-tsconfig";
+import typescriptIcon from "@iconify/icons-vscode-icons/file-type-typescript";
+import videoIcon from "@iconify/icons-vscode-icons/file-type-video";
+import viteIcon from "@iconify/icons-vscode-icons/file-type-vite";
+import vitestIcon from "@iconify/icons-vscode-icons/file-type-vitest";
+import vueIcon from "@iconify/icons-vscode-icons/file-type-vue";
+import wordIcon from "@iconify/icons-vscode-icons/file-type-word";
+import xmlIcon from "@iconify/icons-vscode-icons/file-type-xml";
+import yamlIcon from "@iconify/icons-vscode-icons/file-type-yaml";
+import yarnIcon from "@iconify/icons-vscode-icons/file-type-yarn";
+import zipIcon from "@iconify/icons-vscode-icons/file-type-zip";
+import { cn } from "@/shared/lib/utils";
+
+type FileTypeIconProps = {
+  className?: string;
+  fileName: string;
+  size?: "compact" | "default";
+};
+
+type FileIconVisual = {
+  icon: IconifyIcon;
+  name: string;
+};
+
+type BundledIcon = IconifyIcon | { default: IconifyIcon };
+
+type FileIconRule = FileIconVisual & {
+  extensions: readonly string[];
+};
+
+const SPECIAL_FILE_RULES: Array<FileIconVisual & { pattern: RegExp }> = [
+  {
+    icon: dockerIcon,
+    name: "docker",
+    pattern: /^(dockerfile|\.dockerignore)$/,
+  },
+  { icon: dotenvIcon, name: "dotenv", pattern: /^\.env(?:\.|$)/ },
+  {
+    icon: gitIcon,
+    name: "git",
+    pattern: /^\.git(?:attributes|ignore|modules)$/,
+  },
+  { icon: makefileIcon, name: "makefile", pattern: /^makefile$/ },
+  { icon: licenseIcon, name: "license", pattern: /^licen[cs]e(?:\.|$)/ },
+  { icon: markdownIcon, name: "markdown", pattern: /^readme(?:\.|$)/ },
+  { icon: npmIcon, name: "npm", pattern: /^package(?:-lock)?\.json$/ },
+  {
+    icon: pnpmIcon,
+    name: "pnpm",
+    pattern: /^(pnpm-lock\.yaml|pnpm-workspace\.yaml)$/,
+  },
+  { icon: yarnIcon, name: "yarn", pattern: /^yarn\.lock$/ },
+  { icon: bunIcon, name: "bun", pattern: /^bun\.lockb?$/ },
+  {
+    icon: tsconfigIcon,
+    name: "tsconfig",
+    pattern: /^tsconfig(?:\..+)?\.json$/,
+  },
+  { icon: viteIcon, name: "vite", pattern: /^vite\.config\./ },
+  { icon: vitestIcon, name: "vitest", pattern: /^vitest(?:\..+)?\.config\./ },
+  { icon: tailwindIcon, name: "tailwind", pattern: /^tailwind\.config\./ },
+  {
+    icon: eslintIcon,
+    name: "eslint",
+    pattern: /^(eslint\.config\.|\.eslintrc)/,
+  },
+  {
+    icon: prettierIcon,
+    name: "prettier",
+    pattern: /^(prettier\.config\.|\.prettierrc)/,
+  },
+];
+
+const FILE_ICON_RULES: FileIconRule[] = [
+  { icon: reactTypescriptIcon, name: "react-typescript", extensions: ["tsx"] },
+  { icon: reactJavascriptIcon, name: "react-javascript", extensions: ["jsx"] },
+  {
+    icon: typescriptIcon,
+    name: "typescript",
+    extensions: ["ts", "mts", "cts"],
+  },
+  {
+    icon: javascriptIcon,
+    name: "javascript",
+    extensions: ["js", "mjs", "cjs"],
+  },
+  { icon: jsonIcon, name: "json", extensions: ["json", "json5", "jsonc"] },
+  { icon: markdownIcon, name: "markdown", extensions: ["md", "mdx"] },
+  { icon: htmlIcon, name: "html", extensions: ["html", "htm"] },
+  { icon: cssIcon, name: "css", extensions: ["css", "pcss", "less"] },
+  { icon: sassIcon, name: "sass", extensions: ["sass", "scss"] },
+  { icon: vueIcon, name: "vue", extensions: ["vue"] },
+  { icon: svelteIcon, name: "svelte", extensions: ["svelte"] },
+  { icon: pythonIcon, name: "python", extensions: ["py", "pyw"] },
+  { icon: goIcon, name: "go", extensions: ["go"] },
+  { icon: rustIcon, name: "rust", extensions: ["rs"] },
+  { icon: javaIcon, name: "java", extensions: ["java"] },
+  { icon: kotlinIcon, name: "kotlin", extensions: ["kt", "kts"] },
+  { icon: swiftIcon, name: "swift", extensions: ["swift"] },
+  { icon: cppIcon, name: "cpp", extensions: ["c", "cc", "cpp", "h", "hpp"] },
+  { icon: csharpIcon, name: "csharp", extensions: ["cs"] },
+  { icon: phpIcon, name: "php", extensions: ["php"] },
+  { icon: rubyIcon, name: "ruby", extensions: ["rb"] },
+  { icon: luaIcon, name: "lua", extensions: ["lua"] },
+  {
+    icon: shellIcon,
+    name: "shell",
+    extensions: ["sh", "bash", "zsh", "fish", "ps1"],
+  },
+  { icon: graphqlIcon, name: "graphql", extensions: ["graphql", "gql"] },
+  { icon: yamlIcon, name: "yaml", extensions: ["yaml", "yml"] },
+  { icon: tomlIcon, name: "toml", extensions: ["toml"] },
+  { icon: xmlIcon, name: "xml", extensions: ["xml"] },
+  { icon: sqlIcon, name: "sql", extensions: ["sql", "sqlite", "db"] },
+  { icon: svgIcon, name: "svg", extensions: ["svg"] },
+  {
+    icon: imageIcon,
+    name: "image",
+    extensions: [
+      "avif",
+      "bmp",
+      "gif",
+      "heic",
+      "ico",
+      "jpeg",
+      "jpg",
+      "png",
+      "tif",
+      "tiff",
+      "webp",
+    ],
+  },
+  {
+    icon: audioIcon,
+    name: "audio",
+    extensions: ["aac", "flac", "m4a", "mp3", "ogg", "opus", "wav", "weba"],
+  },
+  {
+    icon: videoIcon,
+    name: "video",
+    extensions: ["avi", "m4v", "mkv", "mov", "mp4", "webm", "wmv"],
+  },
+  { icon: pdfIcon, name: "pdf", extensions: ["pdf"] },
+  { icon: wordIcon, name: "word", extensions: ["doc", "docx", "odt", "rtf"] },
+  {
+    icon: excelIcon,
+    name: "excel",
+    extensions: ["csv", "numbers", "ods", "tsv", "xls", "xlsx"],
+  },
+  {
+    icon: powerpointIcon,
+    name: "powerpoint",
+    extensions: ["odp", "ppt", "pptx"],
+  },
+  {
+    icon: zipIcon,
+    name: "archive",
+    extensions: ["7z", "bz2", "gz", "rar", "tar", "tgz", "zip"],
+  },
+  {
+    icon: fontIcon,
+    name: "font",
+    extensions: ["eot", "otf", "ttf", "woff", "woff2"],
+  },
+  {
+    icon: configIcon,
+    name: "config",
+    extensions: ["cfg", "conf", "ini", "properties"],
+  },
+  { icon: textIcon, name: "text", extensions: ["log", "txt"] },
+];
+
+const DEFAULT_FILE_VISUAL: FileIconVisual = {
+  icon: defaultFileIcon,
+  name: "default",
+};
+
+function readFileName(value: string): string {
+  return value.trim().split(/[\\/]/).filter(Boolean).pop() ?? value.trim();
+}
+
+function readFileExtension(fileName: string): string {
+  return /\.([a-z0-9]{1,16})$/i.exec(fileName)?.[1]?.toLowerCase() ?? "";
+}
+
+function resolveFileIconVisual(value: string): FileIconVisual {
+  const fileName = readFileName(value).toLowerCase();
+  const specialVisual = SPECIAL_FILE_RULES.find(({ pattern }) =>
+    pattern.test(fileName),
+  );
+  if (specialVisual) {
+    return specialVisual;
+  }
+
+  const extension = readFileExtension(fileName);
+  return (
+    FILE_ICON_RULES.find(({ extensions }) => extensions.includes(extension)) ??
+    DEFAULT_FILE_VISUAL
+  );
+}
+
+function resolveBundledIcon(icon: IconifyIcon): IconifyIcon {
+  const bundledIcon = icon as unknown as BundledIcon;
+  return "body" in bundledIcon ? bundledIcon : bundledIcon.default;
+}
+
+export function FileTypeIcon({
+  className,
+  fileName,
+  size = "default",
+}: FileTypeIconProps) {
+  const visual = resolveFileIconVisual(fileName);
+
+  return (
+    <Icon
+      aria-hidden="true"
+      data-file-type-icon={visual.name}
+      icon={resolveBundledIcon(visual.icon)}
+      className={cn(
+        "shrink-0",
+        size === "compact" ? "h-3.5 w-3.5" : "h-4 w-4",
+        className,
+      )}
+    />
+  );
+}

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

@@ -21,12 +21,14 @@ describe("ResizableRightPanel", () => {
   });
 
   it("resizes horizontally from the left handle and clamps to max width", () => {
+    const onWidthCommit = vi.fn();
     render(
       <ResizableRightPanel
         data-testid="right-panel"
         defaultWidth={420}
         minWidth={320}
         maxWidth={500}
+        onWidthCommit={onWidthCommit}
       >
         Content
       </ResizableRightPanel>,
@@ -46,6 +48,8 @@ describe("ResizableRightPanel", () => {
 
     firePointerEvent(window, "pointerup", { clientX: 600, pointerId: 1 });
 
+    expect(onWidthCommit).toHaveBeenCalledWith(500);
+
     expect(
       screen.queryByTestId("resizable-right-panel-resize-shield"),
     ).toBeNull();
@@ -64,6 +68,24 @@ describe("ResizableRightPanel", () => {
     expect(screen.getByTestId("right-panel").className).toContain("fixed");
   });
 
+  it("applies a persisted controlled width after store rehydration", () => {
+    const view = render(
+      <ResizableRightPanel data-testid="right-panel" width={480}>
+        Content
+      </ResizableRightPanel>,
+    );
+
+    expect(screen.getByTestId("right-panel").style.width).toBe("480px");
+
+    view.rerender(
+      <ResizableRightPanel data-testid="right-panel" width={620}>
+        Content
+      </ResizableRightPanel>,
+    );
+
+    expect(screen.getByTestId("right-panel").style.width).toBe("620px");
+  });
+
   it("can scope overlay positioning to its container", () => {
     render(
       <ResizableRightPanel

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

@@ -5,8 +5,10 @@ type ResizableRightPanelProps = ComponentPropsWithoutRef<"aside"> & {
   defaultWidth?: number;
   minWidth?: number;
   maxWidth?: number;
+  onWidthCommit?: (width: number) => void;
   overlay?: boolean;
   overlayScope?: "viewport" | "container";
+  width?: number;
 };
 
 export function ResizableRightPanel({
@@ -16,13 +18,18 @@ export function ResizableRightPanel({
   defaultWidth = 420,
   minWidth = 320,
   maxWidth = 860,
+  onWidthCommit,
   overlay = false,
   overlayScope = "viewport",
+  width: controlledWidth,
   ...props
 }: ResizableRightPanelProps) {
   const resizeRef = useRef<{ startX: number; startWidth: number } | null>(null);
+  const widthRef = useRef(controlledWidth ?? defaultWidth);
   const [isResizing, setIsResizing] = useState(false);
-  const [width, setWidth] = useState(defaultWidth);
+  const [dragWidth, setDragWidth] = useState<number | null>(null);
+  const [uncontrolledWidth, setUncontrolledWidth] = useState(defaultWidth);
+  const width = dragWidth ?? controlledWidth ?? uncontrolledWidth;
   const overlayClassName = overlay
     ? overlayScope === "container"
       ? "absolute inset-0 z-30"
@@ -35,14 +42,22 @@ export function ResizableRightPanel({
     event.stopPropagation();
     event.currentTarget.setPointerCapture?.(event.pointerId);
     setIsResizing(true);
+    widthRef.current = width;
     resizeRef.current = { startX: event.clientX, startWidth: width };
     const onMove = (moveEvent: PointerEvent) => {
       const resizing = resizeRef.current;
       if (!resizing) return;
       const nextWidth = resizing.startWidth + resizing.startX - moveEvent.clientX;
-      setWidth(Math.max(minWidth, Math.min(maxWidth, nextWidth)));
+      const clampedWidth = Math.max(minWidth, Math.min(maxWidth, nextWidth));
+      widthRef.current = clampedWidth;
+      setDragWidth(clampedWidth);
     };
     const onUp = () => {
+      if (controlledWidth === undefined) {
+        setUncontrolledWidth(widthRef.current);
+      }
+      onWidthCommit?.(widthRef.current);
+      setDragWidth(null);
       setIsResizing(false);
       resizeRef.current = null;
       window.removeEventListener("pointermove", onMove);

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

@@ -1,4 +1,5 @@
 import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   CompactTabStrip,
@@ -126,4 +127,41 @@ describe("CompactTabStrip", () => {
     expect(onClose).toHaveBeenCalledTimes(1);
     expect(onSelect).not.toHaveBeenCalled();
   });
+
+  it("opens a tab action menu without selecting the tab or restoring stale focus after an action", async () => {
+    const user = userEvent.setup();
+    const onAction = vi.fn();
+    const onSelect = vi.fn();
+
+    render(
+      <CompactTabStrip
+        tabs={[
+          {
+            key: "source-tab",
+            label: "index.html",
+            active: true,
+            menuLabel: "File actions",
+            menuActions: [
+              {
+                key: "preview",
+                icon: <span />,
+                label: "Open preview",
+                onClick: onAction,
+              },
+            ],
+            onSelect,
+          },
+        ]}
+        actions={[]}
+      />,
+    );
+
+    const menuTrigger = screen.getByRole("button", { name: "File actions" });
+    await user.click(menuTrigger);
+    await user.click(screen.getByRole("menuitem", { name: "Open preview" }));
+
+    expect(onAction).toHaveBeenCalledTimes(1);
+    expect(onSelect).not.toHaveBeenCalled();
+    expect(document.activeElement).not.toBe(menuTrigger);
+  });
 });

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

@@ -1,6 +1,11 @@
 import * as React from "react";
-import { X } from "lucide-react";
+import { MoreVertical, X } from "lucide-react";
 import { IconActionButton } from "@/shared/components/ui/actions/icon-action-button";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/shared/components/ui/popover";
 import {
   Tooltip,
   TooltipContent,
@@ -15,10 +20,13 @@ export type CompactTabStripTab = {
   active: boolean;
   tooltip?: string | null;
   leadingIcon?: React.ReactNode;
+  labelClassName?: string;
   badge?: React.ReactNode;
   unreadIndicator?: React.ReactNode;
   closeLabel?: string;
   closePlacement?: "leading-hover" | "trailing";
+  menuLabel?: string;
+  menuActions?: readonly CompactTabStripAction[];
   onSelect: () => void;
   onClose?: () => void;
 };
@@ -55,6 +63,77 @@ function closeCompactTab(event: React.MouseEvent<HTMLButtonElement>, onClose: ()
   onClose();
 }
 
+function CompactTabMenu({ tab }: { tab: CompactTabStripTab }) {
+  const [open, setOpen] = React.useState(false);
+  const restoreTriggerFocus = React.useRef(true);
+  if (!tab.menuActions?.length) {
+    return null;
+  }
+
+  const menuLabel = tab.menuLabel ?? tab.label;
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(nextOpen) => {
+        if (nextOpen) {
+          restoreTriggerFocus.current = true;
+        }
+        setOpen(nextOpen);
+      }}
+    >
+      <div
+        className={cn(
+          "-ml-1.5 flex w-0 shrink-0 overflow-hidden opacity-0 transition-[width,margin,opacity] group-hover:ml-0 group-hover:w-5 group-hover:opacity-100 group-focus-within:ml-0 group-focus-within:w-5 group-focus-within:opacity-100",
+          open ? "ml-0 w-5 opacity-100" : null,
+        )}
+      >
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            aria-label={menuLabel}
+            onClick={(event) => event.stopPropagation()}
+            className="inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-md text-gray-400 transition-colors hover:bg-gray-200 hover:text-gray-700 focus-visible:bg-gray-200 focus-visible:text-gray-700 focus-visible:outline-none"
+          >
+            <MoreVertical className="h-3.5 w-3.5" />
+          </button>
+        </PopoverTrigger>
+      </div>
+      <PopoverContent
+        align="end"
+        className="w-40 rounded-xl p-1.5"
+        onClick={(event) => event.stopPropagation()}
+        onCloseAutoFocus={(event) => {
+          if (!restoreTriggerFocus.current) {
+            event.preventDefault();
+          }
+        }}
+      >
+        <div role="menu" aria-label={menuLabel}>
+          {tab.menuActions.map((action) => (
+            <button
+              key={action.key}
+              type="button"
+              role="menuitem"
+              disabled={action.disabled}
+              className="flex w-full items-center gap-2 rounded-lg px-2.5 py-2 text-left text-xs text-gray-700 transition-colors hover:bg-gray-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-border disabled:cursor-not-allowed disabled:opacity-45"
+              onClick={() => {
+                restoreTriggerFocus.current = false;
+                setOpen(false);
+                action.onClick();
+              }}
+            >
+              <span className="inline-flex h-4 w-4 shrink-0 items-center justify-center">
+                {action.icon}
+              </span>
+              <span>{action.label}</span>
+            </button>
+          ))}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
 function CompactTabLabelButton({
   labelClassName,
   tab,
@@ -77,7 +156,7 @@ function CompactTabLabelButton({
           {leadingIcon}
         </span>
       ) : null}
-      <span className={cn("min-w-0 truncate text-[12px] font-medium", labelClassName)}>
+      <span className={cn("min-w-0 truncate text-[12px] font-medium", labelClassName, tab.labelClassName)}>
         {tab.label}
       </span>
       {tab.badge}
@@ -145,6 +224,7 @@ function CompactTabItem({
         </button>
       ) : null}
       <CompactTabLabelButton tab={tab} labelClassName={labelClassName} />
+      <CompactTabMenu tab={tab} />
       {tab.onClose && tab.closePlacement !== "leading-hover" ? (
         <IconActionButton
           size="sm"

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

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { buildServerPathContentUrl } from "@/shared/lib/api/utils/server-path.utils";
+
+describe("buildServerPathContentUrl", () => {
+  it("uses the query content route for absolute files", () => {
+    expect(buildServerPathContentUrl("/tmp/logo.svg")).toContain(
+      "/api/server-paths/content?path=%2Ftmp%2Flogo.svg",
+    );
+  });
+
+  it("uses the same query content route for Windows files", () => {
+    expect(buildServerPathContentUrl("C:\\Users\\me\\logo.svg")).toContain(
+      "path=C%3A%5CUsers%5Cme%5Clogo.svg",
+    );
+  });
+
+  it("builds a base-path content URL for relative Markdown images", () => {
+    const url = buildServerPathContentUrl("assets/logo.svg", "/tmp/project");
+
+    expect(url).toContain("/api/server-paths/content?");
+    expect(url).toContain("path=assets%2Flogo.svg");
+    expect(url).toContain("basePath=%2Ftmp%2Fproject");
+  });
+
+  it("rejects relative content paths when no base path is available", () => {
+    expect(buildServerPathContentUrl("assets/logo.svg", null)).toBeNull();
+  });
+});

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

@@ -3,17 +3,6 @@ import { nextclawClient } from '@/shared/lib/api/managers/client.manager';
 import type { ServerPathBrowseView, ServerPathReadView } from '@/shared/lib/api/types';
 
 const SERVER_PATH_CONTENT_BASE_PATH = '/api/server-paths/content';
-const SERVER_PATH_CONTENT_ABSOLUTE_SCOPE = '__abs__';
-const SERVER_PATH_CONTENT_WINDOWS_SCOPE = '__win__';
-
-function encodeServerPathSegments(path: string): string {
-  return path
-    .replace(/\\/g, '/')
-    .split('/')
-    .filter(Boolean)
-    .map((segment) => encodeURIComponent(segment))
-    .join('/');
-}
 
 export async function fetchServerPathBrowse(params?: {
   path?: string | null;
@@ -30,14 +19,24 @@ export async function fetchServerPathRead(params: {
   return await nextclawClient.serverPaths.read(params);
 }
 
-export function buildServerPathContentUrl(resolvedPath: string): string {
-  const normalizedPath = resolvedPath.trim();
-  if (/^[a-z]:[\\/]/i.test(normalizedPath)) {
-    const [drive, ...segments] = normalizedPath.replace(/\\/g, '/').split('/');
-    return `${API_BASE}${SERVER_PATH_CONTENT_BASE_PATH}/${SERVER_PATH_CONTENT_WINDOWS_SCOPE}/${encodeURIComponent(drive)}/${segments
-      .filter(Boolean)
-      .map((segment) => encodeURIComponent(segment))
-      .join('/')}`;
+export function buildServerPathContentUrl(path: string): string;
+export function buildServerPathContentUrl(
+  path: string,
+  basePath: string | null,
+): string | null;
+export function buildServerPathContentUrl(
+  path: string,
+  basePath?: string | null,
+): string | null {
+  const normalizedPath = path.trim();
+  const isAbsolute = normalizedPath.startsWith("/") || /^[a-z]:[\\/]/i.test(normalizedPath);
+  const normalizedBasePath = basePath?.trim() ?? "";
+  if (!isAbsolute && !normalizedBasePath) {
+    return null;
+  }
+  const query = new URLSearchParams({ path: normalizedPath });
+  if (normalizedBasePath) {
+    query.set("basePath", normalizedBasePath);
   }
-  return `${API_BASE}${SERVER_PATH_CONTENT_BASE_PATH}/${SERVER_PATH_CONTENT_ABSOLUTE_SCOPE}/${encodeServerPathSegments(normalizedPath)}`;
+  return `${API_BASE}${SERVER_PATH_CONTENT_BASE_PATH}?${query.toString()}`;
 }