@nextclaw/ui 0.13.0 → 0.13.2

package/src/features/panel-apps/utils/panel-app-doc-browser.utils.tsx

@@ -5,14 +5,18 @@ import { getPresenter } from '@/app/presenters/app.presenter';
 import { AppsPanel, type AppsPanelTab } from '@/features/apps';
 import { PanelAppToolbar } from '@/features/panel-apps/components/panel-app-toolbar';
 import {
-  DOC_BROWSER_APPS_TAB_KIND,
-  DOC_BROWSER_APPS_URL,
-  DOC_BROWSER_SERVICE_APPS_URL,
-} from '@/shared/components/doc-browser/utils/doc-browser-route-registry.utils';
+  createPanelAppRightPanelResourceTarget,
+  RIGHT_PANEL_APPS_TAB_KIND,
+  RIGHT_PANEL_APPS_URL,
+  RIGHT_PANEL_HOME_TAB_KIND,
+  RIGHT_PANEL_PANEL_APP_TAB_KIND,
+  RIGHT_PANEL_SERVICE_APPS_URL,
+  RightPanelResourceHomePage,
+} from '@/features/right-panel-resources';
 import { t } from '@/shared/lib/i18n';
 
-export const APPS_TAB_KIND = DOC_BROWSER_APPS_TAB_KIND;
-export const PANEL_APP_TAB_KIND = 'panel-app';
+export const APPS_TAB_KIND = RIGHT_PANEL_APPS_TAB_KIND;
+export const PANEL_APP_TAB_KIND = RIGHT_PANEL_PANEL_APP_TAB_KIND;
 const DEFAULT_APPS_PANEL_TAB: AppsPanelTab = 'panel-apps';
 const PANEL_APP_IFRAME_SANDBOX = [
   'allow-scripts',
@@ -30,7 +34,7 @@ function isAppsPanelTab(value: unknown): value is AppsPanelTab {
 }
 
 export function createAppsPanelUrl(tab: AppsPanelTab = DEFAULT_APPS_PANEL_TAB): string {
-  return tab === DEFAULT_APPS_PANEL_TAB ? DOC_BROWSER_APPS_URL : DOC_BROWSER_SERVICE_APPS_URL;
+  return tab === DEFAULT_APPS_PANEL_TAB ? RIGHT_PANEL_APPS_URL : RIGHT_PANEL_SERVICE_APPS_URL;
 }
 
 export function getAppsPanelTabFromUrl(url: string): AppsPanelTab {
@@ -51,10 +55,14 @@ export function openApps(docBrowser: Pick<DocBrowserContextValue, 'open'>): void
 }
 
 export const PANEL_APPS_DOC_BROWSER_RENDERERS: DocBrowserCustomTabRenderers = {
+  [RIGHT_PANEL_HOME_TAB_KIND]: {
+    getTitle: () => t('docBrowserHomeTitle'),
+    renderContent: ({ open }) => <RightPanelResourceHomePage open={open} />,
+  },
   [APPS_TAB_KIND]: {
     getTitle: () => t('appsTitle'),
     renderIcon: () => <Boxes className="w-4 h-4 text-primary shrink-0" />,
-    renderContent: ({ currentUrl, open }) => (
+    renderContent: ({ currentUrl, open, openTarget }) => (
       <AppsPanel
         activeTab={getAppsPanelTabFromUrl(currentUrl)}
         onActiveTabChange={(tab) => open(createAppsPanelUrl(tab), {
@@ -63,11 +71,7 @@ export const PANEL_APPS_DOC_BROWSER_RENDERERS: DocBrowserCustomTabRenderers = {
           title: t('appsTitle'),
           dedupeKey: 'apps',
         })}
-        onOpenPanelApp={(entry) => open(entry.contentPath, {
-          kind: PANEL_APP_TAB_KIND,
-          title: entry.title,
-          dedupeKey: `panel-app:${entry.id}`,
-        })}
+        onOpenPanelApp={(entry) => openTarget(createPanelAppRightPanelResourceTarget(entry))}
       />
     ),
   },

package/src/features/right-panel-resources/components/right-panel-resource-home-page.tsx

@@ -0,0 +1,96 @@
+import type { ReactNode } from 'react';
+import {
+  BookOpen,
+  Boxes,
+  BrainCircuit,
+  Grid3X3,
+} from 'lucide-react';
+import { useNavigate } from 'react-router-dom';
+import type { DocBrowserContextValue } from '@/shared/components/doc-browser/doc-browser-context';
+import { cn } from '@/shared/lib/utils';
+import {
+  getRightPanelResourceHomeNavigationItems,
+} from '@/features/right-panel-resources/configs/right-panel-resource-routes.config';
+import type {
+  RightPanelResourceHomeNavigationItem,
+  RightPanelResourceNavigationTarget,
+} from '@/features/right-panel-resources/types/right-panel-resource.types';
+
+type RightPanelResourceHomePageProps = {
+  open: DocBrowserContextValue['open'];
+};
+
+type RightPanelResourceHomeItem = {
+  accentClassName: string;
+  hoverAccentClassName: string;
+  icon: ReactNode;
+};
+
+const HOME_ITEM_VIEW_BY_ID: Record<string, RightPanelResourceHomeItem> = {
+  apps: {
+    accentClassName: 'bg-emerald-50 text-emerald-700',
+    hoverAccentClassName: 'group-hover:bg-emerald-100',
+    icon: <Boxes className="h-5 w-5" />,
+  },
+  'service-apps': {
+    accentClassName: 'bg-sky-50 text-sky-700',
+    hoverAccentClassName: 'group-hover:bg-sky-100',
+    icon: <Grid3X3 className="h-5 w-5" />,
+  },
+  docs: {
+    accentClassName: 'bg-amber-50 text-amber-700',
+    hoverAccentClassName: 'group-hover:bg-amber-100',
+    icon: <BookOpen className="h-5 w-5" />,
+  },
+  'skill-marketplace': {
+    accentClassName: 'bg-rose-50 text-rose-700',
+    hoverAccentClassName: 'group-hover:bg-rose-100',
+    icon: <BrainCircuit className="h-5 w-5" />,
+  },
+};
+
+function resolveHomeItemView(item: RightPanelResourceHomeNavigationItem): RightPanelResourceHomeItem {
+  return HOME_ITEM_VIEW_BY_ID[item.id] ?? {
+    accentClassName: 'bg-gray-50 text-gray-700',
+    hoverAccentClassName: 'group-hover:bg-gray-100',
+    icon: <Boxes className="h-5 w-5" />,
+  };
+}
+
+export function RightPanelResourceHomePage({ open }: RightPanelResourceHomePageProps) {
+  const navigate = useNavigate();
+  const items = getRightPanelResourceHomeNavigationItems();
+
+  const openTarget = (target: RightPanelResourceNavigationTarget) => {
+    if (target.type === 'app-route') {
+      navigate(target.path);
+      return;
+    }
+    open(target.uri, target.options);
+  };
+
+  return (
+    <div className="h-full overflow-auto bg-background px-4 py-5">
+      <div className="mx-auto w-full max-w-[520px]">
+        <div className="grid grid-cols-[repeat(auto-fit,minmax(76px,1fr))] gap-x-2 gap-y-4">
+          {items.map((item) => {
+            const view = resolveHomeItemView(item);
+            return (
+              <button
+                key={item.id}
+                type="button"
+                onClick={() => openTarget(item.target)}
+                className="group flex min-h-[68px] flex-col items-center gap-1.5 rounded-md px-1.5 py-1.5 text-center focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              >
+                <span className={cn('flex h-10 w-10 shrink-0 items-center justify-center rounded-md transition-colors', view.accentClassName, view.hoverAccentClassName)}>
+                  {view.icon}
+                </span>
+                <span className="line-clamp-2 min-w-0 max-w-full text-xs font-medium leading-snug text-gray-700 transition-colors group-hover:text-gray-900">{item.label}</span>
+              </button>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/features/right-panel-resources/configs/right-panel-resource-routes.config.ts

@@ -0,0 +1,171 @@
+import { t } from '@/shared/lib/i18n';
+import type { ParsedResourceUri, ResourceUriRouteDefinition } from '@/shared/lib/resource-uri';
+import {
+  getDefaultDocsUrl,
+  inferTabTitle,
+  isDocsUrl,
+  normalizeDocUrl,
+  normalizeUrlByKind,
+} from '@/shared/components/doc-browser/utils/doc-browser-url.utils';
+import type {
+  RightPanelResourceHomeNavigationItem,
+  RightPanelResourceRouteDefinition,
+  RightPanelResourceTarget,
+} from '@/features/right-panel-resources/types/right-panel-resource.types';
+import {
+  RIGHT_PANEL_APPS_URL,
+  RIGHT_PANEL_APPS_TAB_KIND,
+  RIGHT_PANEL_HOME_TAB_KIND,
+  RIGHT_PANEL_HOME_URL,
+  RIGHT_PANEL_PANEL_APP_TAB_KIND,
+  RIGHT_PANEL_SERVICE_APPS_URL,
+  normalizeRightPanelAppsUrl,
+} from '@/features/right-panel-resources/utils/right-panel-resource-uri.utils';
+
+function isUrlWithPrefix(url: string, prefix: string): boolean {
+  return url === prefix || url.startsWith(`${prefix}?`) || url.startsWith(`${prefix}/`);
+}
+
+function resolveNextclawDocsUrl(uri: ParsedResourceUri): string {
+  const docsPath = uri.pathSegments.join('/');
+  const rawPath = docsPath ? `/${docsPath}` : '/';
+  return normalizeUrlByKind(rawPath, 'docs');
+}
+
+function resolvePanelAppPlaceholderUrl(uri: ParsedResourceUri): string {
+  const appId = uri.pathSegments[0] ?? '';
+  return appId ? `nextclaw://panel-app/${encodeURIComponent(appId)}` : 'nextclaw://panel-app';
+}
+
+export const RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS: RightPanelResourceRouteDefinition[] = [
+  {
+    defaultUrl: () => RIGHT_PANEL_HOME_URL,
+    id: 'home',
+    kind: RIGHT_PANEL_HOME_TAB_KIND,
+    match: (uri) => uri.raw === RIGHT_PANEL_HOME_URL,
+    resolve: () => ({
+      historyPolicy: 'managed',
+      kind: RIGHT_PANEL_HOME_TAB_KIND,
+      title: t('docBrowserHomeTitle'),
+      url: RIGHT_PANEL_HOME_URL,
+    }),
+    areEquivalent: (left, right) => left === right,
+  },
+  {
+    defaultUrl: getDefaultDocsUrl,
+    id: 'docs-url',
+    kind: 'docs',
+    match: (uri) => isDocsUrl(uri.raw),
+    resolve: (uri) => {
+      const url = normalizeUrlByKind(uri.raw, 'docs');
+      return {
+        historyPolicy: 'managed',
+        kind: 'docs',
+        title: t('docBrowserHelp'),
+        url,
+      };
+    },
+    areEquivalent: (left, right) => normalizeDocUrl(left) === normalizeDocUrl(right),
+  },
+  {
+    defaultUrl: getDefaultDocsUrl,
+    id: 'nextclaw-docs',
+    kind: 'docs',
+    match: (uri) => uri.scheme === 'nextclaw' && uri.authority === 'docs',
+    resolve: (uri) => {
+      const url = resolveNextclawDocsUrl(uri);
+      return {
+        historyPolicy: 'managed',
+        kind: 'docs',
+        title: t('docBrowserHelp'),
+        url,
+      };
+    },
+    areEquivalent: (left, right) => normalizeDocUrl(left) === normalizeDocUrl(right),
+  },
+  {
+    defaultUrl: () => RIGHT_PANEL_APPS_URL,
+    id: 'apps',
+    kind: RIGHT_PANEL_APPS_TAB_KIND,
+    match: (uri) => isUrlWithPrefix(uri.raw, RIGHT_PANEL_APPS_URL),
+    resolve: (uri) => {
+      const url = normalizeRightPanelAppsUrl(uri.raw);
+      return {
+        dedupeKey: 'apps',
+        historyPolicy: 'managed',
+        kind: RIGHT_PANEL_APPS_TAB_KIND,
+        title: url === RIGHT_PANEL_APPS_URL ? t('appsTitle') : t('serviceAppsTitle'),
+        url,
+      };
+    },
+    areEquivalent: (left, right) => normalizeRightPanelAppsUrl(left) === normalizeRightPanelAppsUrl(right),
+  },
+  {
+    defaultUrl: () => 'nextclaw://panel-app',
+    id: 'panel-app',
+    kind: RIGHT_PANEL_PANEL_APP_TAB_KIND,
+    match: (uri) => uri.scheme === 'nextclaw' && uri.authority === 'panel-app',
+    resolve: (uri) => {
+      const url = resolvePanelAppPlaceholderUrl(uri);
+      const appId = uri.pathSegments[0] ?? '';
+      return {
+        dedupeKey: appId ? `panel-app:${decodeURIComponent(appId)}` : undefined,
+        historyPolicy: 'managed',
+        kind: RIGHT_PANEL_PANEL_APP_TAB_KIND,
+        title: t('panelAppsTitle'),
+        url,
+      };
+    },
+    areEquivalent: (left, right) => left === right,
+  },
+  {
+    defaultUrl: () => 'about:blank',
+    id: 'content',
+    kind: 'content',
+    match: () => true,
+    resolve: (uri) => ({
+      historyPolicy: 'managed',
+      kind: 'content',
+      title: inferTabTitle(uri.raw, 'content', 'Detail'),
+      url: uri.raw || 'about:blank',
+    }),
+    areEquivalent: (left, right) => left === right,
+  },
+];
+
+export const RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS_FOR_RESOURCE_URI: ResourceUriRouteDefinition<RightPanelResourceTarget>[] =
+  RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS.map((definition) => ({
+    areEquivalent: definition.areEquivalent,
+    id: definition.id,
+    match: definition.match,
+    resolve: definition.resolve,
+  }));
+
+export function getRightPanelResourceHomeNavigationItems(): RightPanelResourceHomeNavigationItem[] {
+  return [
+    {
+      id: 'apps',
+      label: t('appsTitle'),
+      target: { type: 'right-panel-resource', uri: RIGHT_PANEL_APPS_URL },
+    },
+    {
+      id: 'service-apps',
+      label: t('serviceAppsTitle'),
+      target: { type: 'right-panel-resource', uri: RIGHT_PANEL_SERVICE_APPS_URL },
+    },
+    {
+      id: 'docs',
+      label: t('docBrowserHelp'),
+      target: {
+        options: { newTab: true },
+        type: 'right-panel-resource',
+        uri: getDefaultDocsUrl(),
+      },
+    },
+    {
+      id: 'skill-marketplace',
+      label: t('marketplaceSkillsPageTitle'),
+      target: { path: '/marketplace/skills', type: 'app-route' },
+    },
+  ];
+}

package/src/features/right-panel-resources/index.ts

@@ -0,0 +1,18 @@
+export { RightPanelResourceHomePage } from '@/features/right-panel-resources/components/right-panel-resource-home-page';
+export { RightPanelResourceRouteResolver } from '@/features/right-panel-resources/utils/right-panel-resource-route-resolver.utils';
+export type {
+  RightPanelResourceHomeNavigationItem,
+  RightPanelResourceKind,
+  RightPanelResourceNavigationTarget,
+  RightPanelResourceTarget,
+} from '@/features/right-panel-resources/types/right-panel-resource.types';
+export {
+  createPanelAppResourceUri,
+  createPanelAppRightPanelResourceTarget,
+  RIGHT_PANEL_APPS_TAB_KIND,
+  RIGHT_PANEL_APPS_URL,
+  RIGHT_PANEL_HOME_TAB_KIND,
+  RIGHT_PANEL_HOME_URL,
+  RIGHT_PANEL_PANEL_APP_TAB_KIND,
+  RIGHT_PANEL_SERVICE_APPS_URL,
+} from '@/features/right-panel-resources/utils/right-panel-resource-uri.utils';

package/src/features/right-panel-resources/types/right-panel-resource.types.ts

@@ -0,0 +1,36 @@
+import type {
+  DocBrowserOpenOptions,
+  DocBrowserRouteTarget,
+  DocBrowserTabKind,
+} from '@/shared/components/doc-browser/types/doc-browser.types';
+import type { ParsedResourceUri } from '@/shared/lib/resource-uri';
+
+export type RightPanelResourceKind = DocBrowserTabKind;
+
+export type RightPanelResourceTarget = DocBrowserRouteTarget;
+
+export type RightPanelResourceRouteDefinition = {
+  areEquivalent?: (left: string, right: string) => boolean;
+  defaultUrl: () => string;
+  id: string;
+  kind: RightPanelResourceKind;
+  match: (uri: ParsedResourceUri) => boolean;
+  resolve: (uri: ParsedResourceUri) => RightPanelResourceTarget;
+};
+
+export type RightPanelResourceNavigationTarget =
+  | {
+    options?: DocBrowserOpenOptions;
+    type: 'right-panel-resource';
+    uri?: string;
+  }
+  | {
+    path: string;
+    type: 'app-route';
+  };
+
+export type RightPanelResourceHomeNavigationItem = {
+  id: string;
+  label: string;
+  target: RightPanelResourceNavigationTarget;
+};

package/src/features/right-panel-resources/utils/right-panel-resource-route-resolver.utils.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { RightPanelResourceRouteResolver } from '@/features/right-panel-resources';
+
+describe('RightPanelResourceRouteResolver', () => {
+  it('normalizes apps resources and keeps service apps distinct', () => {
+    const resolver = new RightPanelResourceRouteResolver();
+
+    expect(resolver.resolve('nextclaw://apps')).toMatchObject({
+      dedupeKey: 'apps',
+      kind: 'apps',
+      url: 'nextclaw://apps',
+    });
+    expect(resolver.resolve('nextclaw://apps?tab=service-apps')).toMatchObject({
+      dedupeKey: 'apps',
+      kind: 'apps',
+      url: 'nextclaw://apps?tab=service-apps',
+    });
+  });
+
+  it('resolves nextclaw docs resources into docs targets', () => {
+    const resolver = new RightPanelResourceRouteResolver();
+    const target = resolver.resolve('nextclaw://docs/guide/getting-started');
+
+    expect(target.kind).toBe('docs');
+    expect(target.title).toBe('Help Docs');
+    expect(target.url).toContain('/guide/getting-started');
+  });
+
+  it('resolves panel app resources to a stable target identity', () => {
+    const resolver = new RightPanelResourceRouteResolver();
+
+    expect(resolver.resolve('nextclaw://panel-app/timer')).toMatchObject({
+      dedupeKey: 'panel-app:timer',
+      kind: 'panel-app',
+      url: 'nextclaw://panel-app/timer',
+    });
+  });
+});

package/src/features/right-panel-resources/utils/right-panel-resource-route-resolver.utils.ts

@@ -0,0 +1,89 @@
+import type {
+  DocBrowserRouteResolver,
+  DocBrowserTab,
+  DocBrowserTabKind,
+} from '@/shared/components/doc-browser/types/doc-browser.types';
+import { isDocsUrl } from '@/shared/components/doc-browser/utils/doc-browser-url.utils';
+import { ResourceUriResolver, parseResourceUri } from '@/shared/lib/resource-uri';
+import {
+  RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS,
+  RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS_FOR_RESOURCE_URI,
+} from '@/features/right-panel-resources/configs/right-panel-resource-routes.config';
+import type {
+  RightPanelResourceRouteDefinition,
+  RightPanelResourceTarget,
+} from '@/features/right-panel-resources/types/right-panel-resource.types';
+
+function inferFallbackKind(url?: string): DocBrowserTabKind {
+  return url && isDocsUrl(url) ? 'docs' : 'content';
+}
+
+export class RightPanelResourceRouteResolver implements DocBrowserRouteResolver {
+  private readonly resourceUriResolver = new ResourceUriResolver<RightPanelResourceTarget>(
+    RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS_FOR_RESOURCE_URI,
+    { getNormalizedUri: (target) => target.url },
+  );
+
+  resolve = (uri: string): RightPanelResourceTarget => this.resourceUriResolver.resolve(uri);
+
+  normalize = (uri: string): string => this.resourceUriResolver.normalize(uri);
+
+  areEquivalent = (left: string, right: string): boolean => this.resourceUriResolver.areEquivalent(left, right);
+
+  resolveOpenTarget = (params: {
+    activeTab?: DocBrowserTab;
+    kind?: DocBrowserTabKind;
+    url?: string;
+  }): RightPanelResourceTarget => {
+    const { activeTab, kind, url: requestedUrl } = params;
+    const route = this.resolveRouteDefinition(requestedUrl, kind, activeTab);
+    const rawUrl = requestedUrl?.trim()
+      || (!kind && activeTab && activeTab.kind !== 'docs'
+        ? activeTab.currentUrl
+        : route.defaultUrl());
+    return route.resolve(parseResourceUri(rawUrl));
+  };
+
+  areUrlsEquivalent = (
+    currentUrl: string,
+    nextUrl: string,
+    currentKind: DocBrowserTabKind,
+    nextKind: DocBrowserTabKind,
+  ): boolean => {
+    if (currentKind !== nextKind) {
+      return false;
+    }
+    const route = this.resolveRouteDefinition(currentUrl, currentKind);
+    return route.areEquivalent?.(currentUrl, nextUrl) ?? this.areEquivalent(currentUrl, nextUrl);
+  };
+
+  usesManagedHistory = (tab: DocBrowserTab): boolean => {
+    return this.resolveRouteDefinition(tab.currentUrl, tab.kind).resolve(parseResourceUri(tab.currentUrl)).historyPolicy === 'managed';
+  };
+
+  private resolveRouteDefinition = (
+    url?: string,
+    kind?: DocBrowserTabKind,
+    activeTab?: DocBrowserTab,
+  ): RightPanelResourceRouteDefinition => {
+    const targetKind = kind ?? (url ? undefined : activeTab?.kind);
+    const routeByKind = targetKind
+      ? RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS.find((route) => route.kind === targetKind)
+      : undefined;
+    if (routeByKind) {
+      return routeByKind;
+    }
+
+    const parsed = url ? parseResourceUri(url) : null;
+    const routeByUrl = parsed
+      ? RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS.find((route) => route.match(parsed))
+      : undefined;
+    if (routeByUrl) {
+      return routeByUrl;
+    }
+
+    const fallbackKind = kind ?? activeTab?.kind ?? inferFallbackKind(url);
+    return RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS.find((route) => route.kind === fallbackKind)
+      ?? RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS[RIGHT_PANEL_RESOURCE_ROUTE_DEFINITIONS.length - 1];
+  };
+}

package/src/features/right-panel-resources/utils/right-panel-resource-uri.utils.ts

@@ -0,0 +1,48 @@
+import type { PanelAppEntryView } from '@/shared/lib/api';
+import type { RightPanelResourceTarget } from '@/features/right-panel-resources/types/right-panel-resource.types';
+
+export const RIGHT_PANEL_HOME_TAB_KIND = 'home';
+export const RIGHT_PANEL_HOME_URL = 'nextclaw://new-tab';
+export const RIGHT_PANEL_APPS_TAB_KIND = 'apps';
+export const RIGHT_PANEL_APPS_URL = 'nextclaw://apps';
+export const RIGHT_PANEL_SERVICE_APPS_URL = `${RIGHT_PANEL_APPS_URL}?tab=service-apps`;
+export const RIGHT_PANEL_PANEL_APP_TAB_KIND = 'panel-app';
+
+export type RightPanelAppsTab = 'panel-apps' | 'service-apps';
+
+const DEFAULT_RIGHT_PANEL_APPS_TAB: RightPanelAppsTab = 'panel-apps';
+
+function isRightPanelAppsTab(value: unknown): value is RightPanelAppsTab {
+  return value === 'panel-apps' || value === 'service-apps';
+}
+
+export function createRightPanelAppsUrl(tab: RightPanelAppsTab = DEFAULT_RIGHT_PANEL_APPS_TAB): string {
+  return tab === DEFAULT_RIGHT_PANEL_APPS_TAB ? RIGHT_PANEL_APPS_URL : RIGHT_PANEL_SERVICE_APPS_URL;
+}
+
+export function getRightPanelAppsTabFromUrl(url: string): RightPanelAppsTab {
+  try {
+    const tab = new URL(url).searchParams.get('tab');
+    return isRightPanelAppsTab(tab) ? tab : DEFAULT_RIGHT_PANEL_APPS_TAB;
+  } catch {
+    return DEFAULT_RIGHT_PANEL_APPS_TAB;
+  }
+}
+
+export function normalizeRightPanelAppsUrl(url: string): string {
+  return createRightPanelAppsUrl(getRightPanelAppsTabFromUrl(url));
+}
+
+export function createPanelAppResourceUri(appId: string): string {
+  return `nextclaw://panel-app/${encodeURIComponent(appId)}`;
+}
+
+export function createPanelAppRightPanelResourceTarget(entry: PanelAppEntryView): RightPanelResourceTarget {
+  return {
+    dedupeKey: `panel-app:${entry.id}`,
+    historyPolicy: 'managed',
+    kind: RIGHT_PANEL_PANEL_APP_TAB_KIND,
+    title: entry.title,
+    url: entry.contentPath,
+  };
+}

package/src/features/side-dock/components/side-dock.test.tsx

@@ -0,0 +1,58 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { SIDE_DOCK_BUILT_IN_ITEMS } from '@/features/side-dock/configs/side-dock-built-in-items.config';
+import { SideDock } from '@/features/side-dock/components/side-dock';
+import { useSideDockStore } from '@/features/side-dock/stores/side-dock.store';
+import type { SideDockManager } from '@/features/side-dock/managers/side-dock.manager';
+import { DocBrowserProvider } from '@/shared/components/doc-browser/doc-browser-context';
+import { DocBrowserManager } from '@/shared/components/doc-browser/managers/doc-browser.manager';
+import { useDocBrowserStore } from '@/shared/components/doc-browser/stores/doc-browser.store';
+import { createDefaultDocBrowserState } from '@/shared/components/doc-browser/utils/doc-browser-state.utils';
+
+describe('SideDock', () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    useSideDockStore.getState().setPinnedItems([]);
+    useDocBrowserStore.getState().setSnapshot(createDefaultDocBrowserState());
+  });
+
+  it('renders built-in entries and opens the selected resource', () => {
+    const openItem = vi.fn();
+    const manager = { openItem } as unknown as SideDockManager;
+    const docBrowserManager = new DocBrowserManager();
+
+    render(
+      <DocBrowserProvider manager={docBrowserManager}>
+        <SideDock manager={manager} />
+      </DocBrowserProvider>,
+    );
+
+    expect(screen.getByTestId('side-dock')).toBeTruthy();
+    SIDE_DOCK_BUILT_IN_ITEMS.forEach((item) => {
+      expect(document.querySelector(`[data-side-dock-item-id="${item.id}"]`)).toBeTruthy();
+    });
+
+    const appsButton = document.querySelector('[data-side-dock-item-id="apps"]');
+    expect(appsButton).toBeTruthy();
+    fireEvent.click(appsButton as Element);
+
+    expect(openItem).toHaveBeenCalledWith(SIDE_DOCK_BUILT_IN_ITEMS[0]);
+  });
+
+  it('does not highlight the default docs tab while DocBrowser is closed', () => {
+    const manager = { openItem: vi.fn() } as unknown as SideDockManager;
+    const docBrowserManager = new DocBrowserManager();
+
+    render(
+      <DocBrowserProvider manager={docBrowserManager}>
+        <SideDock manager={manager} />
+      </DocBrowserProvider>,
+    );
+
+    const docsButton = document.querySelector('[data-side-dock-item-id="docs"]');
+
+    expect(docsButton).toBeTruthy();
+    expect(docsButton?.className).toContain('bg-transparent');
+    expect(docsButton?.className).not.toContain('shadow-sm');
+  });
+});