@nextclaw/ui 0.13.3 → 0.13.5

package/src/shared/components/config/providers-list.tsx

@@ -1,19 +1,19 @@
 import { useMemo, useState } from 'react';
-import { KeyRound, Plus, Search } from 'lucide-react';
-import { useConfig, useConfigMeta, useConfigSchema, useCreateProvider } from '@/shared/hooks/use-config';
+import { KeyRound, MoreHorizontal, Plus, Search, Trash2 } from 'lucide-react';
+import { useCreateProvider, useDeleteProvider, useProviders, useProviderTemplates, useUpdateProvider } from '@/shared/hooks/use-config';
 import { LogoBadge } from '@/shared/components/common/logo-badge';
 import { PageHeader, PageLayout } from '@/app/components/layout/page-layout';
 import { Button } from '@/shared/components/ui/button';
 import { Input } from '@/shared/components/ui/input';
-import { Tabs } from '@/shared/components/ui/tabs-custom';
+import { Switch } from '@/shared/components/ui/switch';
+import { Popover, PopoverContent, PopoverTrigger } from '@/shared/components/ui/popover';
+import { ConfirmDialog } from '@/shared/components/ui/confirm-dialog';
 import { StatusDot } from '@/shared/components/ui/status-dot';
-import { hintForPath } from '@/shared/lib/config-hints';
 import { t } from '@/shared/lib/i18n';
 import { cn } from '@/shared/lib/utils';
 import { ProviderForm } from '@/shared/components/config/provider-form';
 import { useViewportLayout } from '@/app/hooks/use-viewport-layout';
 import {
-  ConfigSelectionCard,
   ConfigSplitEmptyState,
   ConfigSplitPage,
   ConfigSplitPaneBody,
@@ -33,53 +33,84 @@ function formatBasePreview(base?: string | null) {
   }
 }
 
-function sortProvidersForDisplay<T extends { name: string }>(providers: T[]) {
+function sortProvidersForDisplay<T extends { providerId: string; providerType: string | null }>(
+  providers: T[],
+  pinnedProviderIds: string[] = [],
+) {
+  const pinnedOrder = new Map(pinnedProviderIds.map((providerId, index) => [providerId, index]));
   return providers
     .map((provider, index) => ({ provider, index }))
     .sort((left, right) => {
-      const leftPriority = left.provider.name === 'nextclaw' ? 1 : 0;
-      const rightPriority = right.provider.name === 'nextclaw' ? 1 : 0;
+      const leftPinned = pinnedOrder.get(left.provider.providerId);
+      const rightPinned = pinnedOrder.get(right.provider.providerId);
+      if (leftPinned !== undefined || rightPinned !== undefined) {
+        return (leftPinned ?? Number.MAX_SAFE_INTEGER) - (rightPinned ?? Number.MAX_SAFE_INTEGER);
+      }
+      const leftPriority = left.provider.providerType === 'nextclaw' ? 1 : 0;
+      const rightPriority = right.provider.providerType === 'nextclaw' ? 1 : 0;
       return leftPriority !== rightPriority ? leftPriority - rightPriority : left.index - right.index;
     })
     .map(({ provider }) => provider);
 }
 
+function sortTemplatesForPicker<T extends { providerType: string }>(templates: T[]) {
+  const zhipuIndex = templates.findIndex((template) => template.providerType === 'zhipu');
+  const dashScopeIndex = templates.findIndex((template) => template.providerType === 'dashscope-coding-plan');
+  return templates
+    .map((template, index) => ({ template, index }))
+    .sort((left, right) => {
+      const resolveWeight = ({ template, index }: { template: T; index: number }) => {
+        if (template.providerType === 'nextclaw') return Number.MAX_SAFE_INTEGER;
+        if (template.providerType === 'deepseek' && dashScopeIndex >= 0) return dashScopeIndex - 0.5;
+        if (template.providerType === 'mimo' && zhipuIndex >= 0) return zhipuIndex + 0.5;
+        return index;
+      };
+      return resolveWeight(left) - resolveWeight(right);
+    })
+    .map(({ template }) => template);
+}
+
 export function ProvidersList() {
   const { isMobile } = useViewportLayout();
-  const { data: config } = useConfig();
-  const { data: meta } = useConfigMeta();
-  const { data: schema } = useConfigSchema();
+  const { data: providersView } = useProviders();
+  const { data: templatesView } = useProviderTemplates();
   const createProvider = useCreateProvider();
-  const [activeTab, setActiveTab] = useState('installed');
+  const deleteProvider = useDeleteProvider();
+  const updateProvider = useUpdateProvider();
   const [selectedProvider, setSelectedProvider] = useState<string | null>(null);
+  const [providerToDelete, setProviderToDelete] = useState<string | null>(null);
+  const [providerPickerOpen, setProviderPickerOpen] = useState(false);
+  const [recentProviderIds, setRecentProviderIds] = useState<string[]>([]);
   const [query, setQuery] = useState('');
-  const providers = useMemo(() => sortProvidersForDisplay(meta?.providers ?? []), [meta?.providers]);
-  const providersConfig = config?.providers ?? {};
+  const providers = useMemo(
+    () => sortProvidersForDisplay(Object.values(providersView?.providers ?? {}), recentProviderIds),
+    [providersView?.providers, recentProviderIds],
+  );
+  const templates = useMemo(() => templatesView?.providerTemplates ?? [], [templatesView?.providerTemplates]);
+  const pickerTemplates = useMemo(() => sortTemplatesForPicker(templates), [templates]);
+  const templateByType = useMemo(() => new Map(templates.map((template) => [template.providerType, template])), [templates]);
 
   const filteredProviders = useMemo(() => {
     const keyword = query.trim().toLowerCase();
     return providers
-      .filter((provider) =>
-        activeTab !== 'installed' || Boolean(providersConfig[provider.name]?.enabled !== false && providersConfig[provider.name]?.apiKeySet),
-      )
       .filter((provider) => {
         if (!keyword) {
           return true;
         }
-        const display =
-          providersConfig[provider.name]?.displayName?.trim() || provider.displayName || provider.name;
-        return display.toLowerCase().includes(keyword) || provider.name.toLowerCase().includes(keyword);
+        const template = provider.providerType ? templateByType.get(provider.providerType) : null;
+        const display = provider.displayName?.trim() || template?.displayName || provider.providerId;
+        return display.toLowerCase().includes(keyword) || provider.providerId.toLowerCase().includes(keyword);
       });
-  }, [activeTab, providers, providersConfig, query]);
+  }, [providers, query, templateByType]);
 
   const resolvedSelectedProvider = useMemo(() => {
-    if (selectedProvider && filteredProviders.some((provider) => provider.name === selectedProvider)) {
+    if (selectedProvider && filteredProviders.some((provider) => provider.providerId === selectedProvider)) {
       return selectedProvider;
     }
-    return isMobile ? null : filteredProviders[0]?.name ?? null;
+    return isMobile ? null : filteredProviders[0]?.providerId ?? null;
   }, [filteredProviders, isMobile, selectedProvider]);
 
-  if (!config || !meta) {
+  if (!providersView || !templatesView) {
     return <div className="p-8">{t('providersLoading')}</div>;
   }
 
@@ -94,38 +125,67 @@ export function ProvidersList() {
       >
         <ConfigSplitSidebar>
           <ConfigSplitPaneHeader className="space-y-3 px-4 pb-3 pt-4">
-            <Tabs
-              tabs={[
-                {
-                  id: 'installed',
-                  label: t('providersTabConfigured'),
-                  count: providers.filter((provider) => providersConfig[provider.name]?.enabled !== false && providersConfig[provider.name]?.apiKeySet).length,
-                },
-                { id: 'all', label: t('providersTabAll'), count: providers.length },
-              ]}
-              activeTab={activeTab}
-              onChange={setActiveTab}
-              className="mb-0"
-            />
-            <Button
-              type="button"
-              variant="outline"
-              className="w-full justify-center"
-              onClick={async () => {
-                try {
-                  const result = await createProvider.mutateAsync({ data: {} });
-                  setActiveTab('all');
-                  setQuery('');
-                  setSelectedProvider(result.name);
-                } catch {
-                  // toast handled in hook
-                }
-              }}
-              disabled={createProvider.isPending}
-            >
-              <Plus className="mr-2 h-4 w-4" />
-              {createProvider.isPending ? t('saving') : t('providerAddCustom')}
-            </Button>
+            <Popover open={providerPickerOpen} onOpenChange={setProviderPickerOpen}>
+              <PopoverTrigger asChild>
+                <Button type="button" variant="outline" className="w-full justify-center" disabled={createProvider.isPending}>
+                  <Plus className="mr-2 h-4 w-4" />
+                  {createProvider.isPending ? t('saving') : t('providerAdd')}
+                </Button>
+              </PopoverTrigger>
+              <PopoverContent className="w-[42rem] max-w-[calc(100vw-2rem)] p-3" align="start">
+                <div className="mb-2 px-1 text-xs font-semibold text-gray-500">{t('providerTemplatePickerTitle')}</div>
+                <div className="grid max-h-[24rem] grid-cols-2 gap-2 overflow-y-auto sm:grid-cols-3">
+                  <button
+                    type="button"
+                    className="flex min-h-20 w-full flex-col items-start gap-2 rounded-lg border border-dashed border-gray-300 bg-white px-3 py-2 text-left hover:border-primary/40 hover:bg-gray-50"
+                    onClick={async () => {
+                      try {
+                        const result = await createProvider.mutateAsync({ data: { providerType: null } });
+                        setQuery('');
+                        setSelectedProvider(result.providerId);
+                        setRecentProviderIds((current) => [result.providerId, ...current.filter((providerId) => providerId !== result.providerId)]);
+                        setProviderPickerOpen(false);
+                      } catch {
+                        // toast handled in hook
+                      }
+                    }}
+                  >
+                    <LogoBadge name="custom" className="h-8 w-8 rounded-lg border border-gray-200 bg-white" />
+                    <span className="line-clamp-2 min-w-0 text-xs font-semibold leading-4 text-gray-800">
+                      {t('providerAddCustom')}
+                    </span>
+                  </button>
+                  {pickerTemplates.map((template) => (
+                    <button
+                      key={template.providerType}
+                      type="button"
+                      className="flex min-h-20 w-full flex-col items-start gap-2 rounded-lg border border-gray-200 bg-white px-3 py-2 text-left hover:border-primary/40 hover:bg-gray-50"
+                      onClick={async () => {
+                        try {
+                          const result = await createProvider.mutateAsync({ data: { providerType: template.providerType } });
+                          setQuery('');
+                          setSelectedProvider(result.providerId);
+                          setRecentProviderIds((current) => [result.providerId, ...current.filter((providerId) => providerId !== result.providerId)]);
+                          setProviderPickerOpen(false);
+                        } catch {
+                          // toast handled in hook
+                        }
+                      }}
+                    >
+                      <LogoBadge
+                        name={template.providerType}
+                        src={template.logo ? `/logos/${template.logo}` : null}
+                        className="h-8 w-8 rounded-lg border border-gray-200 bg-white"
+                        imgClassName="h-4 w-4 object-contain"
+                      />
+                      <span className="line-clamp-2 min-w-0 text-xs font-semibold leading-4 text-gray-800">
+                        {template.displayName || template.providerType}
+                      </span>
+                    </button>
+                  ))}
+                </div>
+              </PopoverContent>
+            </Popover>
           </ConfigSplitPaneHeader>
 
           <div className="border-b border-gray-100 px-4 py-3">
@@ -142,42 +202,98 @@ export function ProvidersList() {
 
           <ConfigSplitPaneBody className="space-y-2 p-3">
             {filteredProviders.map((provider) => {
-              const providerConfig = providersConfig[provider.name];
-              const isEnabled = providerConfig?.enabled !== false;
-              const isReady = Boolean(isEnabled && providerConfig?.apiKeySet);
-              const providerLabel = providerConfig?.displayName?.trim() || provider.displayName || provider.name;
-              const description = formatBasePreview(providerConfig?.apiBase || provider.defaultApiBase || '') || hintForPath(`providers.${provider.name}`, schema?.uiHints)?.help || t('providersDefaultDescription');
+              const template = provider.providerType ? templateByType.get(provider.providerType) : null;
+              const isEnabled = provider.enabled !== false;
+              const isReady = Boolean(isEnabled && provider.apiKeySet);
+              const providerLabel = provider.displayName?.trim() || template?.displayName || provider.providerId;
+              const description = formatBasePreview(provider.apiBase || template?.defaultApiBase || '') || t('providersDefaultDescription');
 
               return (
-                <ConfigSelectionCard
-                  key={provider.name}
-                  onClick={() => setSelectedProvider(provider.name)}
-                  active={resolvedSelectedProvider === provider.name}
+                <div
+                  key={provider.providerId}
+                  onClick={() => setSelectedProvider(provider.providerId)}
+                  onKeyDown={(event) => {
+                    if (event.key === 'Enter' || event.key === ' ') {
+                      event.preventDefault();
+                      setSelectedProvider(provider.providerId);
+                    }
+                  }}
+                  role="button"
+                  tabIndex={0}
+                  className={cn(
+                    'w-full rounded-xl border p-2.5 text-left transition-all',
+                    resolvedSelectedProvider === provider.providerId
+                      ? 'border-primary/30 bg-primary-50/40 shadow-sm'
+                      : 'border-gray-200/70 bg-white hover:border-gray-300 hover:bg-gray-50/70',
+                  )}
                 >
-                  <div className="flex items-start justify-between gap-3">
-                    <div className="flex min-w-0 items-center gap-3">
+                  <div className="relative min-h-10">
+                    <div className="flex min-w-0 items-center gap-3 pr-20">
                       <LogoBadge
-                        name={provider.name}
-                        src={provider.logo ? `/logos/${provider.logo}` : null}
+                        name={provider.providerType ?? provider.providerId}
+                        src={template?.logo ? `/logos/${template.logo}` : null}
                         className={cn(
                           'h-10 w-10 rounded-lg border',
                           isReady ? 'border-primary/30 bg-white' : 'border-gray-200/70 bg-white',
                         )}
                         imgClassName="h-5 w-5 object-contain"
-                        fallback={<span className="text-sm font-semibold uppercase text-gray-500">{provider.name[0]}</span>}
+                        fallback={<span className="text-sm font-semibold uppercase text-gray-500">{provider.providerId[0]}</span>}
                       />
                       <div className="min-w-0">
                         <p className="truncate text-sm font-semibold text-gray-900">{providerLabel}</p>
-                        <p className="line-clamp-1 text-[11px] text-gray-500">{description}</p>
+                        <p className="truncate font-mono text-[10px] text-gray-400">{provider.providerId}</p>
+                        <p className="line-clamp-1 text-[11px] text-gray-500">
+                          {description} · {provider.models?.length ?? 0}
+                        </p>
+                      </div>
+                    </div>
+                    <div className="absolute right-0 top-0 flex items-center gap-1.5">
+                      <div onClick={(event) => event.stopPropagation()}>
+                        <Switch
+                          checked={isEnabled}
+                          disabled={updateProvider.isPending}
+                          title={isEnabled ? t('disabled') : t('enabled')}
+                          className="h-[18px] w-8"
+                          thumbClassName="h-4 w-4 data-[state=checked]:translate-x-4"
+                          onCheckedChange={(enabled) => {
+                            void updateProvider.mutateAsync({
+                              provider: provider.providerId,
+                              data: { enabled },
+                              silentSuccess: true,
+                            });
+                          }}
+                        />
                       </div>
+                      <Popover>
+                        <PopoverTrigger asChild>
+                          <button
+                            type="button"
+                            className="inline-flex h-7 w-7 items-center justify-center rounded-lg text-gray-400 hover:bg-gray-100 hover:text-gray-700"
+                            onClick={(event) => event.stopPropagation()}
+                            title={t('more')}
+                          >
+                            <MoreHorizontal className="h-4 w-4" />
+                          </button>
+                        </PopoverTrigger>
+                        <PopoverContent className="w-40 p-1" align="end" onClick={(event) => event.stopPropagation()}>
+                          <button
+                            type="button"
+                            className="flex w-full items-center gap-2 rounded-md px-2 py-2 text-sm text-red-600 hover:bg-red-50"
+                            onClick={() => setProviderToDelete(provider.providerId)}
+                          >
+                            <Trash2 className="h-4 w-4" />
+                            {t('providerDelete')}
+                          </button>
+                        </PopoverContent>
+                      </Popover>
                     </div>
                     <StatusDot
                       status={isEnabled ? (isReady ? 'ready' : 'setup') : 'inactive'}
                       label={isEnabled ? (isReady ? t('statusReady') : t('statusSetup')) : t('disabled')}
-                      className="min-w-[56px] justify-center"
+                      className="absolute bottom-0 right-0 justify-end"
                     />
                   </div>
-                </ConfigSelectionCard>
+                </div>
               );
             })}
 
@@ -190,12 +306,34 @@ export function ProvidersList() {
         <ProviderForm
           providerName={resolvedSelectedProvider ?? undefined}
           onProviderDeleted={(deletedProvider) => {
+            setRecentProviderIds((current) => current.filter((providerId) => providerId !== deletedProvider));
             if (deletedProvider === resolvedSelectedProvider) {
               setSelectedProvider(null);
             }
           }}
         />
       </ConfigSplitPage>
+      <ConfirmDialog
+        open={Boolean(providerToDelete)}
+        onOpenChange={(open) => {
+          if (!open) setProviderToDelete(null);
+        }}
+        title={t('providerDelete')}
+        description={providerToDelete ?? undefined}
+        confirmLabel={t('delete')}
+        variant="destructive"
+        onCancel={() => setProviderToDelete(null)}
+        onConfirm={() => {
+          if (!providerToDelete) return;
+          void deleteProvider.mutateAsync({ provider: providerToDelete }).then(() => {
+            setRecentProviderIds((current) => current.filter((providerId) => providerId !== providerToDelete));
+            if (providerToDelete === resolvedSelectedProvider) {
+              setSelectedProvider(null);
+            }
+            setProviderToDelete(null);
+          });
+        }}
+      />
     </PageLayout>
   );
 }

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

@@ -164,7 +164,9 @@ describe('DocBrowserProvider dedupe keys', () => {
       kind: 'apps',
     });
   });
+});
 
+describe('DocBrowserProvider built-in routes', () => {
   it('opens the built-in start page without falling back to docs', () => {
     const { result } = renderHook(() => useDocBrowser(), { wrapper });
 
@@ -211,15 +213,19 @@ describe('DocBrowserProvider dedupe keys', () => {
       title: 'Service Apps',
     });
   });
+});
 
+describe('DocBrowserProvider panel app resources', () => {
   it('opens an already resolved panel app target without reparsing its content URL', () => {
     const { result } = renderHook(() => useDocBrowser(), { wrapper });
 
     act(() => {
       result.current.openTarget({
         dedupeKey: 'panel-app:demo',
+        dockIcon: { type: 'url', url: '/api/panel-apps/demo/assets/icon.png' },
         historyPolicy: 'managed',
         kind: 'panel-app',
+        resourceUri: 'nextclaw://panel-app/demo',
         title: 'Demo Panel App',
         url: '/api/panel-apps/demo/content',
       });
@@ -228,11 +234,15 @@ describe('DocBrowserProvider dedupe keys', () => {
     expect(result.current.currentTab).toMatchObject({
       currentUrl: '/api/panel-apps/demo/content',
       dedupeKey: 'panel-app:demo',
+      dockIcon: { type: 'url', url: '/api/panel-apps/demo/assets/icon.png' },
       kind: 'panel-app',
+      resourceUri: 'nextclaw://panel-app/demo',
       title: 'Demo Panel App',
     });
   });
+});
 
+describe('DocBrowserProvider managed history', () => {
   it('uses managed history for non-doc routes', () => {
     const { result } = renderHook(() => useDocBrowser(), { wrapper });
 
@@ -335,6 +345,44 @@ describe('DocBrowserProvider dedupe keys', () => {
     });
   });
 
+  it('restores panel app history by stable resource URI instead of reparsing content URL as an app id', () => {
+    const { result } = renderHook(() => useDocBrowser(), { wrapper });
+
+    act(() => {
+      result.current.openTarget({
+        dedupeKey: 'panel-app:demo',
+        historyPolicy: 'managed',
+        kind: 'panel-app',
+        resourceUri: 'nextclaw://panel-app/demo',
+        title: 'Demo Panel App',
+        url: '/api/panel-apps/demo/content',
+      });
+      result.current.openNewTab();
+    });
+
+    expect(result.current.currentTab).toMatchObject({
+      currentUrl: 'nextclaw://new-tab',
+      kind: 'home',
+    });
+
+    act(() => {
+      result.current.goBack();
+    });
+
+    expect(result.current.currentTab).toMatchObject({
+      currentUrl: '/api/panel-apps/demo/content',
+      dedupeKey: 'panel-app:demo',
+      kind: 'panel-app',
+      resourceUri: 'nextclaw://panel-app/demo',
+      title: 'Demo Panel App',
+    });
+    expect(result.current.currentTab?.currentUrl).not.toBe('/api/panel-apps/api/content');
+    expect(result.current.activeHistory[result.current.activeHistoryIndex]).toMatchObject({
+      resourceUri: 'nextclaw://panel-app/demo',
+      url: '/api/panel-apps/demo/content',
+    });
+  });
+
   it('truncates forward history before appending manual navigation after going back', () => {
     const { result } = renderHook(() => useDocBrowser(), { wrapper });
 
@@ -377,6 +425,31 @@ describe('DocBrowserProvider dedupe keys', () => {
 });
 
 describe('DocBrowserProvider persistence', () => {
+  it('persists dock icon metadata for restored tabs', async () => {
+    const { result } = renderHook(() => useDocBrowser(), { wrapper });
+
+    act(() => {
+      result.current.openTarget({
+        dedupeKey: 'panel-app:demo',
+        dockIcon: { type: 'text', value: 'D' },
+        historyPolicy: 'managed',
+        kind: 'panel-app',
+        resourceUri: 'nextclaw://panel-app/demo',
+        title: 'Demo App',
+        url: '/api/panel-apps/demo/content',
+      });
+    });
+
+    const savedState = window.localStorage.getItem(docBrowserStorageKey);
+    await resetMemoryThenRehydrate(savedState);
+    const restored = renderHook(() => useDocBrowser(), { wrapper });
+
+    expect(restored.result.current.currentTab).toMatchObject({
+      dockIcon: { type: 'text', value: 'D' },
+      resourceUri: 'nextclaw://panel-app/demo',
+    });
+  });
+
   it('restores the open panel and active tab from the persisted Zustand store', async () => {
     const { result } = renderHook(() => useDocBrowser(), { wrapper });
 

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

@@ -6,6 +6,9 @@ import type { DocBrowserContextValue } from '@/shared/components/doc-browser/typ
 export type {
   DocBrowserActions,
   DocBrowserContextValue,
+  DocBrowserDockControls,
+  DocBrowserDockIcon,
+  DocBrowserDockState,
   DocBrowserMode,
   DocBrowserOpenOptions,
   DocBrowserRouteResolver,

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

@@ -1,6 +1,6 @@
 import type { PointerEvent } from 'react';
-import { ArrowLeft, ArrowRight, Maximize2, PanelRightOpen, Plus, X } from 'lucide-react';
-import type { DocBrowserTab } from './doc-browser-context';
+import { ArrowLeft, ArrowRight, Maximize2, PanelRightOpen, Pin, PinOff, Plus, X } from 'lucide-react';
+import type { DocBrowserDockState, DocBrowserTab } from './doc-browser-context';
 import { cn } from '@/shared/lib/utils';
 import { t } from '@/shared/lib/i18n';
 
@@ -11,9 +11,11 @@ type DocBrowserTabStripProps = {
   canGoForward: boolean;
   isDocked: boolean;
   isFullscreen: boolean;
+  dockState?: DocBrowserDockState;
   onGoBack: () => void;
   onGoForward: () => void;
   onOpenNewTab: () => void;
+  onToggleDock?: () => void;
   onSetActiveTab: (tabId: string) => void;
   onCloseTab: (tabId: string) => void;
   onClose: () => void;
@@ -28,9 +30,11 @@ export function DocBrowserTabStrip({
   canGoForward,
   isDocked,
   isFullscreen,
+  dockState,
   onGoBack,
   onGoForward,
   onOpenNewTab,
+  onToggleDock,
   onSetActiveTab,
   onCloseTab,
   onClose,
@@ -116,6 +120,25 @@ export function DocBrowserTabStrip({
         >
           <Plus className="w-3.5 h-3.5" />
         </button>
+        {dockState?.canDock ? (
+          <button
+            type="button"
+            onClick={onToggleDock}
+            disabled={dockState.isDocked && !dockState.removable}
+            className="rounded-md p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-700 disabled:cursor-not-allowed disabled:text-gray-300 disabled:opacity-60 disabled:hover:bg-transparent disabled:hover:text-gray-300"
+            title={
+              dockState.isDocked
+                ? dockState.removable ? t('sideDockUnpinCurrent') : t('sideDockBuiltInDocked')
+                : t('sideDockPinCurrent')
+            }
+          >
+            {dockState.isDocked && dockState.removable ? (
+              <PinOff className="w-3.5 h-3.5" />
+            ) : (
+              <Pin className="w-3.5 h-3.5" />
+            )}
+          </button>
+        ) : null}
         {!isFullscreen ? (
           <button
             type="button"

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

@@ -237,6 +237,48 @@ describe("DocBrowser", () => {
     expect(docBrowserState.openNewTab).toHaveBeenCalled();
   });
 
+  it("pins the current tab through injected dock controls", () => {
+    const pinTab = vi.fn();
+    const unpinTab = vi.fn();
+
+    render(<DocBrowser dockControls={{
+      getDockState: () => ({ canDock: true, isDocked: false, removable: false }),
+      pinTab,
+      unpinTab,
+    }} />);
+
+    fireEvent.click(screen.getByTitle("Pin to SideDock"));
+
+    expect(pinTab).toHaveBeenCalledWith(docBrowserState.currentTab);
+    expect(unpinTab).not.toHaveBeenCalled();
+  });
+
+  it("unpins a removable docked tab through injected dock controls", () => {
+    const pinTab = vi.fn();
+    const unpinTab = vi.fn();
+
+    render(<DocBrowser dockControls={{
+      getDockState: () => ({ canDock: true, isDocked: true, removable: true }),
+      pinTab,
+      unpinTab,
+    }} />);
+
+    fireEvent.click(screen.getByTitle("Remove from SideDock"));
+
+    expect(unpinTab).toHaveBeenCalledWith(docBrowserState.currentTab);
+    expect(pinTab).not.toHaveBeenCalled();
+  });
+
+  it("disables dock controls for built-in shortcuts", () => {
+    render(<DocBrowser dockControls={{
+      getDockState: () => ({ canDock: true, isDocked: true, removable: false }),
+      pinTab: vi.fn(),
+      unpinTab: vi.fn(),
+    }} />);
+
+    expect(screen.getByTitle("Built-in shortcut")).toHaveProperty("disabled", true);
+  });
+
   it("renders a start page for home tabs", () => {
     const homeTab: DocBrowserTab = {
       id: "home",