@nextclaw/ui 0.15.5 → 0.15.7

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

@@ -4,11 +4,20 @@ export type ReleaseNotesLocale = 'zh-CN' | 'en-US';
 
 export type ReleaseNotesText = Partial<Record<ReleaseNotesLocale, string>>;
 
+export type ReleaseNotesLink = {
+  url: string;
+  versionLabel: string;
+};
+
 export type ReleaseNotesItem = {
   title: ReleaseNotesText;
   body?: ReleaseNotesText;
 };
 
+export type ReleaseNotesLinks = {
+  html?: ReleaseNotesText;
+};
+
 export type ReleaseNotesSection = {
   kind: string;
   title?: ReleaseNotesText;
@@ -18,9 +27,12 @@ export type ReleaseNotesSection = {
 export type ReleaseNotesPayload = {
   title?: ReleaseNotesText;
   summary?: ReleaseNotesText;
+  links?: ReleaseNotesLinks;
   sections: ReleaseNotesSection[];
 };
 
+const DEFAULT_RELEASE_NOTES_BASE_URL = 'https://docs.nextclaw.io/';
+
 export function readReleaseNotesText(
   value: ReleaseNotesText | undefined,
   locale: ReleaseNotesLocale
@@ -33,17 +45,40 @@ export function readReleaseNotesText(
 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)) {
+  if (!releaseNotesUrl) {
     return null;
   }
+  return resolveVersionReleaseNotesDataUrl(version, releaseNotesUrl);
+}
 
+export function resolveVersionReleaseNotesDataUrl(version: string | null | undefined, baseUrl = DEFAULT_RELEASE_NOTES_BASE_URL): string | null {
+  const normalizedVersion = version?.trim();
+  if (!normalizedVersion || !/^[0-9A-Za-z.-]+$/.test(normalizedVersion)) {
+    return null;
+  }
   try {
-    return new URL(`/release-notes/nextclaw-v${version}.json`, releaseNotesUrl).toString();
+    return new URL(`/release-notes/nextclaw-v${normalizedVersion}.json`, baseUrl).toString();
   } catch {
     return null;
   }
 }
 
+export function resolveReleaseNotesHtmlUrl(payload: ReleaseNotesPayload | undefined, locale: ReleaseNotesLocale): string | null {
+  return readReleaseNotesText(payload?.links?.html, locale);
+}
+
+export function resolveUpdateReleaseNotesLink(snapshot: UpdateSnapshot): ReleaseNotesLink | null {
+  const url = snapshot.releaseNotesUrl?.trim();
+  const version = (snapshot.downloadedVersion ?? snapshot.availableVersion)?.trim();
+  if (!url || !version) {
+    return null;
+  }
+  return {
+    url,
+    versionLabel: `v${version}`
+  };
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -70,12 +105,18 @@ function isReleaseNotesSection(value: unknown): value is ReleaseNotesSection {
     && (value.title === undefined || isReleaseNotesText(value.title));
 }
 
+function isReleaseNotesLinks(value: unknown): value is ReleaseNotesLinks {
+  return isRecord(value)
+    && (value.html === undefined || isReleaseNotesText(value.html));
+}
+
 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));
+    && (value.summary === undefined || isReleaseNotesText(value.summary))
+    && (value.links === undefined || isReleaseNotesLinks(value.links));
 }
 
 export async function fetchReleaseNotesData(url: string): Promise<ReleaseNotesPayload> {

package/src/index.css

@@ -719,8 +719,9 @@
   --md-table-head-bg: hsl(var(--muted) / 0.84);
 }
 
+/* The root flow owns external spacing; individual blocks only own their surface. */
 .chat-markdown > * + * {
-  margin-top: 0.72rem;
+  margin-block-start: 0.75rem;
 }
 
 .chat-markdown p,
@@ -729,21 +730,19 @@
   color: var(--md-text);
 }
 
-.chat-markdown h1,
-.chat-markdown h2,
-.chat-markdown h3,
-.chat-markdown h4,
-.chat-markdown h5,
-.chat-markdown h6 {
-  margin: 0.2rem 0 0;
-  padding-bottom: 0.5em;
+.chat-markdown :is(h1, h2, h3, h4, h5, h6) {
+  margin: 0;
   font-weight: 700;
   line-height: 1.35;
   letter-spacing: -0.01em;
 }
 
-.chat-markdown :is(h1, h2, h3, h4, h5, h6) + * {
-  margin-top: 0;
+.chat-markdown > :is(h1, h2, h3, h4, h5, h6):not(:first-child) {
+  margin-block-start: 1.25rem;
+}
+
+.chat-markdown > :is(h1, h2, h3, h4, h5, h6) + * {
+  margin-block-start: 0.5rem;
 }
 
 .chat-markdown h1 {
@@ -766,7 +765,6 @@
 
 .chat-markdown ul,
 .chat-markdown ol {
-  margin: 0.35rem 0;
   padding-left: 1.5rem;
   list-style-position: outside;
 }
@@ -839,7 +837,6 @@
 .chat-markdown hr {
   border: 0;
   border-top: 1px solid var(--md-border);
-  margin: 0.92rem 0;
 }
 
 .chat-markdown a {
@@ -874,7 +871,6 @@
 }
 
 .chat-codeblock {
-  margin: 0.2rem 0 0.1rem;
   border: 1px solid var(--md-code-toolbar-border);
   border-radius: 0.5rem;
   overflow: hidden;
@@ -1299,7 +1295,6 @@
 }
 
 .chat-table-wrap {
-  margin: 0.15rem 0;
   border: 1px solid var(--md-border);
   border-radius: 0.72rem;
   overflow-x: auto;
@@ -1378,7 +1373,6 @@
 }
 
 .chat-markdown blockquote {
-  margin: 0.2rem 0;
   border-left: 3px solid var(--md-blockquote-border);
   border-radius: 0 0.55rem 0.55rem 0;
   padding: 0.45rem 0.72rem;

package/src/shared/components/common/__tests__/brand-header.test.tsx

@@ -10,7 +10,9 @@ import { setLanguage } from '@/shared/lib/i18n';
 
 const mocks = vi.hoisted(() => ({
   applyDownloadedUpdate: vi.fn(),
-  downloadUpdate: vi.fn()
+  downloadUpdate: vi.fn(),
+  fetchReleaseNotes: vi.fn(),
+  openExternalUrl: vi.fn()
 }));
 
 vi.mock('@/features/system-status', async () => {
@@ -25,7 +27,30 @@ vi.mock('@/features/system-status', async () => {
   };
 });
 
-function renderBrandHeader() {
+vi.mock('@/shared/lib/host-capabilities', () => ({
+  hostCapabilityManager: {
+    openExternalUrl: mocks.openExternalUrl,
+  },
+}));
+
+function createReleaseNotesResponse(urls?: { zh?: string; en?: string }): Response {
+  return new Response(JSON.stringify({
+    links: urls
+      ? {
+          html: {
+            ...(urls.zh ? { 'zh-CN': urls.zh } : {}),
+            ...(urls.en ? { 'en-US': urls.en } : {})
+          }
+        }
+      : undefined,
+    sections: []
+  }), {
+    headers: { 'content-type': 'application/json' },
+    status: 200
+  });
+}
+
+function renderBrandHeader(options: { productVersion?: string } = {}) {
   const queryClient = new QueryClient({
     defaultOptions: {
       queries: {
@@ -35,7 +60,7 @@ function renderBrandHeader() {
   });
   queryClient.setQueryData(['app-meta'], {
     name: 'NextClaw',
-    productVersion: '0.18.11'
+    productVersion: options.productVersion ?? '0.18.11'
   });
   return render(
     <QueryClientProvider client={queryClient}>
@@ -57,6 +82,10 @@ describe('BrandHeader', () => {
     });
     mocks.applyDownloadedUpdate.mockReset();
     mocks.downloadUpdate.mockReset();
+    mocks.fetchReleaseNotes.mockReset();
+    mocks.fetchReleaseNotes.mockResolvedValue(createReleaseNotesResponse());
+    mocks.openExternalUrl.mockReset();
+    vi.stubGlobal('fetch', mocks.fetchReleaseNotes);
   });
 
   it('shows update progress next to the product version', async () => {
@@ -105,6 +134,84 @@ describe('BrandHeader', () => {
     expect(screen.queryByRole('button', { name: '更新' })).toBeNull();
   });
 
+  it('opens release notes from the current version tooltip when that version has docs notes', async () => {
+    const user = userEvent.setup();
+    mocks.fetchReleaseNotes.mockResolvedValueOnce(createReleaseNotesResponse({
+      zh: 'https://docs.nextclaw.io/zh/notes/2026-07-15-nextclaw-v0-23-0',
+      en: 'https://docs.nextclaw.io/en/notes/2026-07-15-nextclaw-v0-23-0'
+    }));
+
+    renderBrandHeader({ productVersion: '0.23.0' });
+
+    const version = await screen.findByRole('button', {
+      name: '当前版本 v0.23.0，查看 v0.23.0 更新说明'
+    });
+
+    await user.hover(version);
+    expect((await screen.findByRole('tooltip')).textContent).toContain('点击查看 v0.23.0 更新说明');
+
+    await user.click(version);
+
+    expect(mocks.fetchReleaseNotes).toHaveBeenCalledWith(
+      'https://docs.nextclaw.io/release-notes/nextclaw-v0.23.0.json',
+      expect.objectContaining({ cache: 'no-store' })
+    );
+    expect(mocks.openExternalUrl).toHaveBeenCalledWith('https://docs.nextclaw.io/zh/notes/2026-07-15-nextclaw-v0-23-0');
+  });
+
+  it('keeps update target release notes available without replacing the current version link', async () => {
+    const user = userEvent.setup();
+    mocks.fetchReleaseNotes.mockResolvedValueOnce(createReleaseNotesResponse({
+      zh: 'https://docs.nextclaw.io/zh/notes/2026-07-14-nextclaw-v0-18-11'
+    }));
+    useRuntimeUpdateStore.setState({
+      supported: true,
+      initialized: true,
+      busyAction: null,
+      snapshot: {
+        status: 'update-available',
+        installationKind: 'npm-runtime-bundle',
+        channel: 'stable',
+        hostVersion: '0.18.11',
+        currentVersion: '0.18.11',
+        availableVersion: '0.18.12',
+        downloadedVersion: null,
+        minimumHostVersion: null,
+        releaseNotesUrl: 'https://docs.nextclaw.io/zh/notes/2026-07-15-nextclaw-v0-18-12',
+        lastCheckedAt: null,
+        progress: null,
+        canAutoDownload: true,
+        canApplyInApp: false,
+        requiresRestart: false,
+        blockReason: null,
+        recoveryCommand: null,
+        errorMessage: null,
+        preferences: {
+          automaticChecks: true,
+          autoDownload: true
+        }
+      }
+    });
+
+    renderBrandHeader();
+
+    const currentVersion = await screen.findByRole('button', {
+      name: '当前版本 v0.18.11，查看 v0.18.11 更新说明'
+    });
+    await user.click(currentVersion);
+    expect(mocks.openExternalUrl).toHaveBeenCalledWith('https://docs.nextclaw.io/zh/notes/2026-07-14-nextclaw-v0-18-11');
+
+    await user.click(screen.getByRole('button', { name: '下载' }));
+    expect(mocks.downloadUpdate).toHaveBeenCalledTimes(1);
+
+    const updateReleaseNotes = screen.getByRole('button', { name: '查看 v0.18.12 更新说明' });
+    await user.hover(updateReleaseNotes);
+    expect((await screen.findByRole('tooltip')).textContent).toBe('查看 v0.18.12 更新说明');
+
+    await user.click(updateReleaseNotes);
+    expect(mocks.openExternalUrl).toHaveBeenCalledWith('https://docs.nextclaw.io/zh/notes/2026-07-15-nextclaw-v0-18-12');
+  });
+
   it('applies the downloaded update from the version-adjacent update button', async () => {
     const user = userEvent.setup();
     useRuntimeUpdateStore.setState({

package/src/shared/components/common/brand-header.tsx

@@ -1,11 +1,20 @@
 import type { UpdateSnapshot } from '@nextclaw/shared';
-import { runtimeUpdateManager, useRuntimeUpdateStore } from '@/features/system-status';
+import {
+  runtimeUpdateManager,
+  resolveUpdateReleaseNotesLink,
+  useCurrentVersionReleaseNotesLink,
+  useRuntimeUpdateStore,
+  type ReleaseNotesLink,
+  type RuntimeUpdateBusyAction
+} from '@/features/system-status';
 import { useAppMeta } from '@/shared/hooks/use-app-meta';
 import type { ReactNode } from 'react';
 import { RuntimeStatusEntry } from '@/app/components/layout/runtime-status-entry';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/shared/components/ui/tooltip';
+import { hostCapabilityManager } from '@/shared/lib/host-capabilities';
 import { t } from '@/shared/lib/i18n';
 import { cn } from '@/shared/lib/utils';
+import { ExternalLink } from 'lucide-react';
 
 type BrandHeaderProps = {
   className?: string;
@@ -15,9 +24,11 @@ type BrandHeaderProps = {
 
 export function BrandHeader({ className, density = 'sidebar', suffix }: BrandHeaderProps) {
   const { data } = useAppMeta();
+  const { supported, busyAction, snapshot } = useRuntimeUpdateStore();
   const productName = data?.name ?? 'NextClaw';
   const productVersion = data?.productVersion?.trim();
   const versionLabel = productVersion ? `v${productVersion}` : null;
+  const releaseNotesLink = useCurrentVersionReleaseNotesLink(productVersion);
   const resolvedSuffix = suffix ?? <RuntimeStatusEntry />;
   const shouldReserveMacWindowControls = typeof window !== 'undefined' && window.nextclawDesktop?.platform === 'darwin';
   const isChromeDensity = density === 'chrome';
@@ -42,9 +53,9 @@ export function BrandHeader({ className, density = 'sidebar', suffix }: BrandHea
           >
             {productName}
           </span>
-          {versionLabel ? <BrandVersionLabel versionLabel={versionLabel} density={density} /> : null}
+          {versionLabel ? <BrandVersionLabel versionLabel={versionLabel} density={density} releaseNotesLink={releaseNotesLink} /> : null}
         </div>
-        <RuntimeUpdateInlineStatus />
+        <RuntimeUpdateInlineStatus supported={supported} busyAction={busyAction} snapshot={snapshot} />
         {resolvedSuffix ? <span className="inline-flex items-center shrink-0">{resolvedSuffix}</span> : null}
       </div>
     </div>
@@ -54,68 +65,143 @@ export function BrandHeader({ className, density = 'sidebar', suffix }: BrandHea
 function BrandVersionLabel({
   versionLabel,
   density,
+  releaseNotesLink,
 }: {
   versionLabel: string;
   density: BrandHeaderProps['density'];
+  releaseNotesLink: ReleaseNotesLink | null;
 }) {
   const isChromeDensity = density === 'chrome';
+  const triggerClassName = cn(
+    'block min-w-0 flex-1 truncate font-medium text-gray-500 outline-none',
+    isChromeDensity ? 'text-[12px]' : 'text-[12px]',
+    releaseNotesLink && 'cursor-pointer rounded-sm transition-colors hover:text-gray-700 hover:underline focus-visible:ring-2 focus-visible:ring-gray-300'
+  );
+  const tooltip = releaseNotesLink
+    ? [
+        t('desktopUpdatesVersionTooltipCurrent').replace('{version}', versionLabel),
+        t('desktopUpdatesVersionTooltipReleaseNotes').replace('{version}', releaseNotesLink.versionLabel)
+      ].join('\n')
+    : versionLabel;
+  const trigger = releaseNotesLink ? (
+    <button
+      type="button"
+      aria-label={t('desktopUpdatesVersionReleaseNotesLabel').replace('{currentVersion}', versionLabel).replace('{releaseVersion}', releaseNotesLink.versionLabel)}
+      className={cn(triggerClassName, 'border-0 bg-transparent p-0 text-left')}
+      onClick={() => void hostCapabilityManager.openExternalUrl(releaseNotesLink.url)}
+    >
+      {versionLabel}
+    </button>
+  ) : (
+    <span tabIndex={0} aria-label={versionLabel} className={triggerClassName}>
+      {versionLabel}
+    </span>
+  );
 
   return (
     <TooltipProvider delayDuration={250}>
       <Tooltip>
-        <TooltipTrigger asChild>
-          <span
-            tabIndex={0}
-            aria-label={versionLabel}
-            className={cn(
-              'block min-w-0 flex-1 truncate font-medium text-gray-500 outline-none',
-              isChromeDensity ? 'text-[12px]' : 'text-[12px]',
-            )}
-          >
-            {versionLabel}
-          </span>
-        </TooltipTrigger>
-        <TooltipContent side="bottom" className="text-xs">{versionLabel}</TooltipContent>
+        <TooltipTrigger asChild>{trigger}</TooltipTrigger>
+        <TooltipContent side="bottom" className="max-w-72 whitespace-pre-line text-xs leading-relaxed">{tooltip}</TooltipContent>
       </Tooltip>
     </TooltipProvider>
   );
 }
 
-function RuntimeUpdateInlineStatus() {
-  const { supported, busyAction, snapshot } = useRuntimeUpdateStore();
+function RuntimeUpdateInlineStatus({
+  supported,
+  busyAction,
+  snapshot,
+}: {
+  supported: boolean;
+  busyAction: RuntimeUpdateBusyAction;
+  snapshot: UpdateSnapshot | null;
+}) {
   if (!supported || !snapshot) {
     return null;
   }
-  if (snapshot.status === 'downloading' || snapshot.status === 'blocked' || snapshot.status === 'failed') {
+  const releaseNotesLink = resolveUpdateReleaseNotesLink(snapshot);
+  if (snapshot.status === 'downloading') {
+    return (
+      <RuntimeUpdateInlineGroup>
+        <RuntimeUpdateInlineBadge snapshot={snapshot} />
+        {releaseNotesLink ? <RuntimeUpdateReleaseNotesButton link={releaseNotesLink} tone="amber" /> : null}
+      </RuntimeUpdateInlineGroup>
+    );
+  }
+  if (snapshot.status === 'blocked' || snapshot.status === 'failed') {
     return <RuntimeUpdateInlineBadge snapshot={snapshot} />;
   }
   if (snapshot.status === 'downloaded') {
     return (
-      <button
-        type="button"
-        className="inline-flex h-5 shrink-0 items-center rounded-full bg-emerald-50 px-2 text-[11px] font-semibold leading-none text-emerald-700 ring-1 ring-emerald-100 transition-colors hover:bg-emerald-100 disabled:opacity-70"
-        disabled={busyAction === 'applying'}
-        onClick={() => void runtimeUpdateManager.applyDownloadedUpdate()}
-      >
-        {busyAction === 'applying' ? t('desktopUpdatesInlineApplying') : t('desktopUpdatesInlineReady')}
-      </button>
+      <RuntimeUpdateInlineGroup>
+        <button
+          type="button"
+          className="inline-flex h-5 shrink-0 items-center rounded-full bg-emerald-50 px-2 text-[11px] font-semibold leading-none text-emerald-700 ring-1 ring-emerald-100 transition-colors hover:bg-emerald-100 disabled:opacity-70"
+          disabled={busyAction === 'applying'}
+          onClick={() => void runtimeUpdateManager.applyDownloadedUpdate()}
+        >
+          {busyAction === 'applying' ? t('desktopUpdatesInlineApplying') : t('desktopUpdatesInlineReady')}
+        </button>
+        {releaseNotesLink ? <RuntimeUpdateReleaseNotesButton link={releaseNotesLink} tone="emerald" /> : null}
+      </RuntimeUpdateInlineGroup>
     );
   }
   if (snapshot.status === 'update-available') {
     return (
-      <button
-        type="button"
-        className="inline-flex h-5 shrink-0 items-center rounded-full bg-amber-50 px-2 text-[11px] font-semibold leading-none text-amber-700 ring-1 ring-amber-100 transition-colors hover:bg-amber-100 disabled:opacity-70"
-        disabled={busyAction === 'downloading'}
-        onClick={() => void runtimeUpdateManager.downloadUpdate()}
-      >
-        {busyAction === 'downloading' ? t('desktopUpdatesInlineDownloading') : t('desktopUpdatesInlineDownload')}
-      </button>
+      <RuntimeUpdateInlineGroup>
+        <button
+          type="button"
+          className="inline-flex h-5 shrink-0 items-center rounded-full bg-amber-50 px-2 text-[11px] font-semibold leading-none text-amber-700 ring-1 ring-amber-100 transition-colors hover:bg-amber-100 disabled:opacity-70"
+          disabled={busyAction === 'downloading'}
+          onClick={() => void runtimeUpdateManager.downloadUpdate()}
+        >
+          {busyAction === 'downloading' ? t('desktopUpdatesInlineDownloading') : t('desktopUpdatesInlineDownload')}
+        </button>
+        {releaseNotesLink ? <RuntimeUpdateReleaseNotesButton link={releaseNotesLink} tone="amber" /> : null}
+      </RuntimeUpdateInlineGroup>
     );
   }
   return null;
 }
 
+function RuntimeUpdateInlineGroup({ children }: { children: ReactNode }) {
+  return <span className="inline-flex shrink-0 items-center gap-1">{children}</span>;
+}
+
+function RuntimeUpdateReleaseNotesButton({
+  link,
+  tone,
+}: {
+  link: ReleaseNotesLink;
+  tone: 'amber' | 'emerald';
+}) {
+  const label = t('desktopUpdatesUpdateReleaseNotesLabel').replace('{version}', link.versionLabel);
+  const className = cn(
+    'inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-full text-[11px] ring-1 transition-colors focus-visible:outline-none focus-visible:ring-2',
+    tone === 'emerald'
+      ? 'bg-emerald-50 text-emerald-700 ring-emerald-100 hover:bg-emerald-100 focus-visible:ring-emerald-300'
+      : 'bg-amber-50 text-amber-700 ring-amber-100 hover:bg-amber-100 focus-visible:ring-amber-300'
+  );
+  return (
+    <TooltipProvider delayDuration={250}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <button
+            type="button"
+            aria-label={label}
+            className={className}
+            onClick={() => void hostCapabilityManager.openExternalUrl(link.url)}
+          >
+            <ExternalLink className="h-3 w-3" aria-hidden="true" />
+          </button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" className="text-xs">{label}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}
+
 function RuntimeUpdateInlineBadge({ snapshot }: { snapshot: UpdateSnapshot }) {
   if (snapshot.status === 'blocked' || snapshot.status === 'failed') {
     return <RuntimeUpdateIssueIcon snapshot={snapshot} />;