@nextclaw/ui 0.15.0 → 0.15.2

package/src/features/system-status/utils/update-release-notes.utils.ts

@@ -0,0 +1,94 @@
+import type { UpdateSnapshot } from '@nextclaw/shared';
+
+export type ReleaseNotesLocale = 'zh-CN' | 'en-US';
+
+export type ReleaseNotesText = Partial<Record<ReleaseNotesLocale, string>>;
+
+export type ReleaseNotesItem = {
+  title: ReleaseNotesText;
+  body?: ReleaseNotesText;
+};
+
+export type ReleaseNotesSection = {
+  kind: string;
+  title?: ReleaseNotesText;
+  items: ReleaseNotesItem[];
+};
+
+export type ReleaseNotesPayload = {
+  title?: ReleaseNotesText;
+  summary?: ReleaseNotesText;
+  sections: ReleaseNotesSection[];
+};
+
+export function readReleaseNotesText(
+  value: ReleaseNotesText | undefined,
+  locale: ReleaseNotesLocale
+): string | null {
+  const fallbackLocale = locale === 'zh-CN' ? 'en-US' : 'zh-CN';
+  const text = value?.[locale]?.trim() || value?.[fallbackLocale]?.trim();
+  return text || null;
+}
+
+export function resolveReleaseNotesDataUrl(snapshot: UpdateSnapshot): string | null {
+  const releaseNotesUrl = snapshot.releaseNotesUrl?.trim();
+  const version = (snapshot.availableVersion ?? snapshot.downloadedVersion)?.trim();
+  if (!releaseNotesUrl || !version || !/^[0-9A-Za-z.-]+$/.test(version)) {
+    return null;
+  }
+
+  try {
+    return new URL(`/release-notes/nextclaw-v${version}.json`, releaseNotesUrl).toString();
+  } catch {
+    return null;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isReleaseNotesText(value: unknown): value is ReleaseNotesText {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return typeof value['zh-CN'] === 'string' || typeof value['en-US'] === 'string';
+}
+
+function isReleaseNotesItem(value: unknown): value is ReleaseNotesItem {
+  if (!isRecord(value) || !isReleaseNotesText(value.title)) {
+    return false;
+  }
+  return value.body === undefined || isReleaseNotesText(value.body);
+}
+
+function isReleaseNotesSection(value: unknown): value is ReleaseNotesSection {
+  return isRecord(value)
+    && typeof value.kind === 'string'
+    && Array.isArray(value.items)
+    && value.items.every(isReleaseNotesItem)
+    && (value.title === undefined || isReleaseNotesText(value.title));
+}
+
+function isReleaseNotesPayload(value: unknown): value is ReleaseNotesPayload {
+  return isRecord(value)
+    && Array.isArray(value.sections)
+    && value.sections.every(isReleaseNotesSection)
+    && (value.title === undefined || isReleaseNotesText(value.title))
+    && (value.summary === undefined || isReleaseNotesText(value.summary));
+}
+
+export async function fetchReleaseNotesData(url: string): Promise<ReleaseNotesPayload> {
+  const response = await fetch(url, {
+    cache: 'no-store',
+    headers: { accept: 'application/json' }
+  });
+  if (!response.ok) {
+    throw new Error(`Release notes request failed with HTTP ${response.status}.`);
+  }
+  const payload: unknown = await response.json();
+  if (!isReleaseNotesPayload(payload)) {
+    throw new Error('Release notes payload has an unsupported shape.');
+  }
+  return payload;
+}

package/src/index.css

@@ -675,6 +675,24 @@
   --md-table-head-bg: rgba(191, 219, 254, 0.16);
 }
 
+:root[data-theme="work"] .chat-markdown-assistant {
+  --md-link: #1f73c9;
+  --md-border: rgba(0, 0, 0, 0.11);
+  --md-table-head-bg: rgba(0, 0, 0, 0.045);
+}
+
+:root[data-theme="work"] .chat-markdown-user {
+  --md-text: #212121;
+  --md-muted: #737373;
+  --md-border: rgba(0, 0, 0, 0.12);
+  --md-link: #1f73c9;
+  --md-inline-code-bg: rgba(0, 0, 0, 0.06);
+  --md-inline-code-color: #212121;
+  --md-blockquote-border: rgba(0, 0, 0, 0.2);
+  --md-blockquote-bg: rgba(0, 0, 0, 0.04);
+  --md-table-head-bg: rgba(0, 0, 0, 0.045);
+}
+
 :root[data-theme-appearance="dark"] .chat-markdown-assistant {
   --md-text: hsl(var(--foreground));
   --md-muted: hsl(var(--foreground-tertiary));

package/src/shared/components/config-split-page.tsx

@@ -3,7 +3,7 @@ import { ArrowLeft, type LucideIcon } from "lucide-react";
 import { t } from "@/shared/lib/i18n";
 import { cn } from "@/shared/lib/utils";
 
-const CARD_CLASS = "min-w-0 overflow-hidden rounded-2xl border border-border bg-card text-card-foreground shadow-card xl:h-[calc(100vh-180px)] xl:max-h-[860px]";
+const CARD_CLASS = "min-w-0 overflow-hidden rounded-2xl border border-border/75 bg-card text-card-foreground xl:h-[calc(100vh-180px)] xl:max-h-[860px]";
 type DivProps = HTMLAttributes<HTMLDivElement>; type SectionProps = HTMLAttributes<HTMLElement>;
 
 function ConfigSplitPane({ className, ...props }: SectionProps) {
@@ -102,7 +102,7 @@ export function ConfigSplitPaneBody({
 }
 
 export function ConfigSplitPaneFooter({ className, ...props }: DivProps) {
-  return <div className={cn("shrink-0 border-t border-border/70", className)} {...props} />;
+  return <div className={cn("shrink-0 border-t border-border/70 px-4 py-2.5", className)} {...props} />;
 }
 
 export function ConfigSelectionCard({
@@ -115,10 +115,10 @@ export function ConfigSelectionCard({
     <button
       type={type}
       className={cn(
-        "w-full rounded-xl border p-2.5 text-left transition-all",
+        "w-full rounded-xl border p-2.5 text-left transition-colors",
         active
-          ? "border-primary/35 bg-primary-50/45 text-foreground shadow-sm"
-          : "border-border bg-card text-muted-foreground hover:border-primary/35 hover:bg-accent/70 hover:text-accent-foreground",
+          ? "border-border/70 bg-muted/65 text-foreground"
+          : "border-transparent bg-transparent text-muted-foreground hover:border-border/50 hover:bg-muted/40 hover:text-foreground",
         className,
       )}
       {...props}
@@ -140,7 +140,7 @@ export function ConfigSplitEmptyState({
   return (
     <div
       className={cn(
-        "flex min-h-[220px] flex-col items-center justify-center rounded-xl border border-dashed border-border bg-muted/60 px-4 py-10 text-center",
+        "flex min-h-[220px] flex-col items-center justify-center rounded-xl border border-dashed border-border/70 bg-muted/35 px-4 py-10 text-center",
         className,
       )}
       {...props}

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

@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+async function importDocsUrlUtils(language: 'en' | 'zh' = 'en') {
+  const i18n = await import('@/shared/lib/i18n');
+  i18n.setLanguage(language);
+  return await import('@/shared/components/doc-browser/utils/doc-browser-url.utils');
+}
+
+function stubTimeZone(timeZone: string) {
+  vi.spyOn(Intl, 'DateTimeFormat').mockReturnValue({
+    resolvedOptions: () => ({ timeZone }),
+  } as Intl.DateTimeFormat);
+}
+
+describe('doc browser docs URL utilities', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    stubTimeZone('America/Los_Angeles');
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.unstubAllGlobals();
+  });
+
+  it('uses the official docs origin for English users outside mainland by default', async () => {
+    const { getDefaultDocsUrl } = await importDocsUrlUtils('en');
+
+    expect(getDefaultDocsUrl()).toBe('https://docs.nextclaw.io/en/guide/getting-started');
+  });
+
+  it('uses the mainland mirror for users in the mainland timezone', async () => {
+    stubTimeZone('Asia/Shanghai');
+
+    const { getDefaultDocsUrl } = await importDocsUrlUtils('en');
+
+    expect(getDefaultDocsUrl()).toBe('https://docs.nextclaw.net/en/guide/getting-started');
+  });
+
+  it('uses the mainland mirror for Chinese users by default', async () => {
+    const { getDefaultDocsUrl } = await importDocsUrlUtils('zh');
+
+    expect(getDefaultDocsUrl()).toBe('https://docs.nextclaw.net/zh/guide/getting-started');
+  });
+
+  it('lets an explicit docs base override the automatic origin', async () => {
+    vi.stubEnv('VITE_NEXTCLAW_DOCS_BASE_URL', 'https://docs.example.com/');
+
+    const { getDocsUrl } = await importDocsUrlUtils('zh');
+
+    expect(getDocsUrl('/guide/model-selection')).toBe('https://docs.example.com/zh/guide/model-selection');
+  });
+
+  it('does not rewrite non-docs absolute URLs', async () => {
+    const { getDocsUrl } = await importDocsUrlUtils('zh');
+
+    expect(getDocsUrl('https://example.com/help')).toBe('https://example.com/help');
+  });
+
+  it('rewrites official docs URLs to the selected docs origin', async () => {
+    const { getDocsUrl } = await importDocsUrlUtils('zh');
+
+    expect(getDocsUrl('https://docs.nextclaw.io/en/guide/commands?tab=cli#start')).toBe(
+      'https://docs.nextclaw.net/en/guide/commands?tab=cli#start',
+    );
+  });
+
+  it('recognizes the mainland mirror as a docs URL', async () => {
+    const { isDocsUrl } = await importDocsUrlUtils('en');
+
+    expect(isDocsUrl('https://docs.nextclaw.net/zh/guide/getting-started')).toBe(true);
+  });
+});

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

@@ -397,6 +397,54 @@ describe("DocBrowser", () => {
     expect(screen.getByText("Help Docs")).toBeTruthy();
   });
 
+  it("focuses panel app iframes on pointer entry without applying the behavior to generic content iframes", () => {
+    const panelAppTab: DocBrowserTab = {
+      id: "piano",
+      kind: "panel-app" as const,
+      title: "Piano",
+      currentUrl: "/api/panel-apps/piano/content",
+      history: ["/api/panel-apps/piano/content"],
+      historyIndex: 0,
+      navVersion: 0,
+    };
+    docBrowserState.tabs = [panelAppTab];
+    docBrowserState.activeTabId = panelAppTab.id;
+    docBrowserState.currentTab = panelAppTab;
+
+    const { container, unmount } = render(
+      <DocBrowser customTabRenderers={PANEL_APPS_DOC_BROWSER_RENDERERS} />,
+    );
+
+    const panelAppIframe = container.querySelector('iframe[title="Piano"]') as HTMLIFrameElement;
+    const panelAppIframeFocus = vi.spyOn(panelAppIframe, "focus");
+    const panelAppContentFocus = vi.spyOn(panelAppIframe.contentWindow!, "focus").mockImplementation(() => undefined);
+
+    fireEvent.pointerOver(panelAppIframe);
+
+    expect(panelAppIframe.getAttribute("tabindex")).toBe("0");
+    expect(panelAppIframeFocus).toHaveBeenCalledWith({ preventScroll: true });
+    expect(panelAppContentFocus).toHaveBeenCalled();
+
+    unmount();
+    resetDocBrowserTestState();
+    const contentTab: DocBrowserTab = {
+      id: "local-app",
+      kind: "content",
+      title: "Local App",
+      currentUrl: "http://127.0.0.1:5173/dashboard",
+      history: ["http://127.0.0.1:5173/dashboard"],
+      historyIndex: 0,
+      navVersion: 0,
+    };
+    docBrowserState.tabs = [contentTab];
+    docBrowserState.activeTabId = contentTab.id;
+    docBrowserState.currentTab = contentTab;
+
+    render(<DocBrowser />);
+
+    expect(screen.getByTitle("Local App").getAttribute("tabindex")).toBeNull();
+  });
+
 });
 
 describe("DocBrowser floating interactions", () => {

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

@@ -22,6 +22,10 @@ export {
   DOC_BROWSER_HOME_TAB_KIND,
   DOC_BROWSER_HOME_URL,
   DOCS_DEFAULT_BASE_URL,
+  DOCS_MAINLAND_BASE_URL,
+  getDocsBaseUrl,
+  getDocsUrl,
+  getDefaultDocsUrl,
   isDocsUrl,
 } from '@/shared/components/doc-browser/utils/doc-browser-url.utils';
 

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

@@ -1,4 +1,4 @@
-import type { ReactNode, Ref } from 'react';
+import type { PointerEventHandler, ReactNode, Ref } from 'react';
 import {
   ExternalLink,
   RefreshCw,
@@ -29,6 +29,7 @@ type DocBrowserFrameContentProps = {
   iframeSandbox?: string;
   isDragging: boolean;
   isResizing: boolean;
+  onIframePointerOver?: PointerEventHandler<HTMLIFrameElement>;
 };
 
 export function DocBrowserAddressToolbar({
@@ -74,6 +75,7 @@ export function DocBrowserFrameContent({
   iframeSandbox,
   isDragging,
   isResizing,
+  onIframePointerOver,
 }: DocBrowserFrameContentProps) {
   return (
     <div className="flex-1 relative overflow-hidden">
@@ -87,6 +89,8 @@ export function DocBrowserFrameContent({
           className="absolute inset-0 w-full h-full border-0"
           title={currentTab?.title || 'NextClaw Docs'}
           sandbox={iframeSandbox}
+          tabIndex={onIframePointerOver ? 0 : undefined}
+          onPointerOver={onIframePointerOver}
           allow="clipboard-read; clipboard-write"
           allowFullScreen
         />

package/src/shared/components/doc-browser/doc-browser-renderer.types.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import type { PointerEvent, ReactNode } from 'react';
 import type { DocBrowserContextValue, DocBrowserTab } from './doc-browser-context';
 
 export type DocBrowserCustomTabRenderParams = {
@@ -20,6 +20,7 @@ export type DocBrowserCustomTabRenderer = {
   getIframeSandbox?: (tab: DocBrowserTab) => string | undefined;
   getTitle?: (tab: DocBrowserTab) => string;
   onIframeMessage?: (params: DocBrowserIframeMessageParams) => void;
+  onIframePointerOver?: (event: PointerEvent<HTMLIFrameElement>) => void;
   renderContent?: (params: DocBrowserCustomTabRenderParams) => ReactNode;
   renderIcon?: (tab: DocBrowserTab) => ReactNode;
   renderToolbar?: (params: DocBrowserCustomTabRenderParams) => ReactNode;

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

@@ -117,20 +117,20 @@ export function DocBrowserTabStrip({
       tabs={compactTabs}
       actions={actions}
       className={cn(
-        "h-11 gap-2 border-border/70 bg-card px-2.5 shrink-0 select-none",
-        isFullscreen && "h-[calc(env(safe-area-inset-top,0px)+2.75rem)] pt-[env(safe-area-inset-top,0px)]",
+        "h-10 gap-1.5 border-border/50 bg-card/80 px-2 shrink-0 select-none",
+        isFullscreen && "h-[calc(env(safe-area-inset-top,0px)+2.5rem)] pt-[env(safe-area-inset-top,0px)]",
       )}
       scrollClassName={cn(
-        "doc-browser-tab-scrollbar flex h-full items-center gap-1.5",
+        "doc-browser-tab-scrollbar flex h-full items-center gap-0.5",
         !isDocked && !isFullscreen && "cursor-grab active:cursor-grabbing",
       )}
-      tabsClassName="items-center gap-1.5"
-      actionsClassName="h-full items-center gap-1"
-      actionButtonClassName="rounded-md p-1.5 hover:text-foreground disabled:opacity-60"
-      tabBaseClassName="group inline-flex min-w-0 cursor-pointer items-center gap-1 h-7 px-1.5 rounded-lg text-xs border max-w-[220px] shrink-0 transition-colors"
-      activeTabClassName="border-primary/30 bg-primary-50/70 text-foreground shadow-[0_1px_2px_rgba(30,20,10,0.04)]"
-      inactiveTabClassName="border-border bg-muted/60 text-muted-foreground hover:bg-accent hover:text-accent-foreground"
-      labelClassName="px-1 text-xs font-normal"
+      tabsClassName="items-center gap-0.5"
+      actionsClassName="h-full items-center gap-0.5"
+      actionButtonClassName="rounded-md p-1.5 text-muted-foreground hover:bg-muted/60 hover:text-foreground disabled:opacity-50"
+      tabBaseClassName="group inline-flex min-w-0 cursor-pointer items-center gap-0.5 h-7 px-2 rounded-md text-xs max-w-[220px] shrink-0 transition-colors"
+      activeTabClassName="bg-muted/80 text-foreground"
+      inactiveTabClassName="text-muted-foreground hover:bg-muted/45 hover:text-foreground"
+      labelClassName="px-0.5 text-xs font-normal"
       onPointerDown={!isDocked && !isFullscreen ? onDragStart : undefined}
       onScrollPointerDown={(event) => {
         if (shouldBlockHeaderDrag(event.target)) {

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