npm - @nextclaw/ui - Versions diffs - 0.5.0 → 0.5.2 - Mend

@nextclaw/ui 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/CHANGELOG.md +15 -0
package/dist/assets/index-CKTsCtI-.css +1 -0
package/dist/assets/index-D8W5lAHk.js +337 -0
package/dist/index.html +2 -2
package/package.json +1 -1
package/src/api/marketplace.ts +10 -0
package/src/api/types.ts +25 -8
package/src/components/config/ChannelForm.tsx +14 -10
package/src/components/config/ProviderForm.tsx +17 -16
package/src/components/config/RuntimeConfig.tsx +33 -27
package/src/components/doc-browser/DocBrowser.tsx +94 -19
package/src/components/doc-browser/DocBrowserContext.tsx +33 -10
package/src/components/marketplace/MarketplacePage.tsx +422 -65
package/src/hooks/useMarketplace.ts +18 -1
package/dist/assets/index-1h_LfFkZ.js +0 -337
package/dist/assets/index-Wn63frSd.css +0 -1

package/dist/index.html CHANGED Viewed

@@ -6,8 +6,8 @@
   <link rel="icon" type="image/svg+xml" href="/logo.svg" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>NextClaw - 系统配置</title>
-  <script type="module" crossorigin src="/assets/index-1h_LfFkZ.js"></script>
-  <link rel="stylesheet" crossorigin href="/assets/index-Wn63frSd.css">
+  <script type="module" crossorigin src="/assets/index-D8W5lAHk.js"></script>
+  <link rel="stylesheet" crossorigin href="/assets/index-CKTsCtI-.css">
 </head>
 <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ui",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/api/marketplace.ts CHANGED Viewed

@@ -2,6 +2,8 @@ import { api } from './client';
 import type {
   MarketplaceInstallRequest,
   MarketplaceInstallResult,
+  MarketplaceManageRequest,
+  MarketplaceManageResult,
   MarketplaceInstalledView,
   MarketplaceItemType,
   MarketplaceItemView,
@@ -108,3 +110,11 @@ export async function fetchMarketplaceInstalled(): Promise<MarketplaceInstalledV
   }
   return response.data;
 }
+export async function manageMarketplaceItem(request: MarketplaceManageRequest): Promise<MarketplaceManageResult> {
+  const response = await api.post<MarketplaceManageResult>('/api/marketplace/manage', request);
+  if (!response.ok) {
+    throw new Error(response.error.message);
+  }
+  return response.data;
+}

package/src/api/types.ts CHANGED Viewed

@@ -244,9 +244,9 @@ export type WsEvent =
 export type MarketplaceItemType = 'plugin' | 'skill';
-export type MarketplaceSort = 'relevance' | 'updated' | 'downloads';
+export type MarketplaceSort = 'relevance' | 'updated';
-export type MarketplaceInstallKind = 'npm' | 'clawhub' | 'git';
+export type MarketplaceInstallKind = 'npm' | 'clawhub' | 'git' | 'builtin';
 export type MarketplaceInstallSpec = {
   kind: MarketplaceInstallKind;
@@ -254,11 +254,6 @@ export type MarketplaceInstallSpec = {
   command: string;
 };
-export type MarketplaceItemMetrics = {
-  downloads30d?: number;
-  stars?: number;
-};
 export type MarketplaceItemSummary = {
   id: string;
   slug: string;
@@ -268,7 +263,6 @@ export type MarketplaceItemSummary = {
   tags: string[];
   author: string;
   install: MarketplaceInstallSpec;
-  metrics?: MarketplaceItemMetrics;
   updatedAt: string;
 };
@@ -299,10 +293,15 @@ export type MarketplaceRecommendationView = {
 export type MarketplaceInstalledRecord = {
   type: MarketplaceItemType;
+  id?: string;
   spec: string;
   label?: string;
   source?: string;
   installedAt?: string;
+  enabled?: boolean;
+  runtimeStatus?: string;
+  origin?: string;
+  installPath?: string;
 };
 export type MarketplaceInstalledView = {
@@ -315,6 +314,7 @@ export type MarketplaceInstalledView = {
 export type MarketplaceInstallRequest = {
   type: MarketplaceItemType;
   spec: string;
+  kind?: MarketplaceInstallKind;
   version?: string;
   registry?: string;
   force?: boolean;
@@ -326,3 +326,20 @@ export type MarketplaceInstallResult = {
   message: string;
   output?: string;
 };
+export type MarketplaceManageAction = 'enable' | 'disable' | 'uninstall';
+export type MarketplaceManageRequest = {
+  type: MarketplaceItemType;
+  action: MarketplaceManageAction;
+  id?: string;
+  spec?: string;
+};
+export type MarketplaceManageResult = {
+  type: MarketplaceItemType;
+  action: MarketplaceManageAction;
+  id: string;
+  message: string;
+  output?: string;
+};

package/src/components/config/ChannelForm.tsx CHANGED Viewed

@@ -13,6 +13,7 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Switch } from '@/components/ui/switch';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
 import { TagInput } from '@/components/common/TagInput';
 import { t } from '@/lib/i18n';
 import { hintForPath } from '@/lib/config-hints';
@@ -410,18 +411,21 @@ export function ChannelForm() {
                   )}
                   {field.type === 'select' && (
-                    <select
-                      id={field.name}
+                    <Select
                       value={(formData[field.name] as string) || ''}
-                      onChange={(e) => updateField(field.name, e.target.value)}
-                      className="flex h-10 w-full rounded-lg border border-gray-200 bg-white px-3 py-2 text-sm"
+                      onValueChange={(v) => updateField(field.name, v)}
                     >
-                      {(field.options ?? []).map((option) => (
-                        <option key={option.value} value={option.value}>
-                          {option.label}
-                        </option>
-                      ))}
-                    </select>
+                      <SelectTrigger className="rounded-xl">
+                        <SelectValue />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {(field.options ?? []).map((option) => (
+                          <SelectItem key={option.value} value={option.value}>
+                            {option.label}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
                   )}
                   {field.type === 'json' && (

package/src/components/config/ProviderForm.tsx CHANGED Viewed

@@ -12,6 +12,7 @@ import {
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
 import { MaskedInput } from '@/components/common/MaskedInput';
 import { KeyValueEditor } from '@/components/common/KeyValueEditor';
 import { t } from '@/lib/i18n';
@@ -149,22 +150,22 @@ export function ProviderForm() {
                   <Hash className="h-3.5 w-3.5 text-gray-500" />
                   {wireApiHint?.label ?? t('wireApi')}
                 </Label>
-                <select
-                  id="wireApi"
-                  value={wireApi}
-                  onChange={(e) => setWireApi(e.target.value as 'auto' | 'chat' | 'responses')}
-                  className="flex h-10 w-full rounded-lg border border-gray-200 bg-white px-3 py-2 text-sm focus:outline-none disabled:cursor-not-allowed disabled:opacity-50"
-                >
-                  {(providerSpec.wireApiOptions || ['auto', 'chat', 'responses']).map((option) => (
-                    <option key={option} value={option}>
-                      {option === 'chat'
-                        ? t('wireApiChat')
-                        : option === 'responses'
-                          ? t('wireApiResponses')
-                          : t('wireApiAuto')}
-                    </option>
-                  ))}
-                </select>
+                <Select value={wireApi} onValueChange={(v) => setWireApi(v as 'auto' | 'chat' | 'responses')}>
+                  <SelectTrigger className="rounded-xl">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {(providerSpec.wireApiOptions || ['auto', 'chat', 'responses']).map((option) => (
+                      <SelectItem key={option} value={option}>
+                        {option === 'chat'
+                          ? t('wireApiChat')
+                          : option === 'responses'
+                            ? t('wireApiResponses')
+                            : t('wireApiAuto')}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
               </div>
             )}

package/src/components/config/RuntimeConfig.tsx CHANGED Viewed

@@ -5,6 +5,7 @@ import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { Input } from '@/components/ui/input';
 import { Switch } from '@/components/ui/switch';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
 import { hintForPath } from '@/lib/config-hints';
 import { Plus, Save, Trash2 } from 'lucide-react';
 import { toast } from 'sonner';
@@ -84,9 +85,9 @@ export function RuntimeConfig() {
           accountId: binding.match?.accountId ?? '',
           peer: binding.match?.peer
             ? {
-                kind: binding.match.peer.kind,
-                id: binding.match.peer.id
-              }
+              kind: binding.match.peer.kind,
+              id: binding.match.peer.id
+            }
             : undefined
         }
       }))
@@ -260,17 +261,18 @@ export function RuntimeConfig() {
           </div>
           <div className="space-y-2">
             <label className="text-sm font-medium text-gray-800">{dmScopeHint?.label ?? 'DM Scope'}</label>
-            <select
-              value={dmScope}
-              onChange={(event) => setDmScope(event.target.value as DmScope)}
-              className="flex h-10 w-full rounded-lg border border-gray-200 bg-white px-3 py-2 text-sm"
-            >
-              {DM_SCOPE_OPTIONS.map((option) => (
-                <option key={option.value} value={option.value}>
-                  {option.label}
-                </option>
-              ))}
-            </select>
+            <Select value={dmScope} onValueChange={(v) => setDmScope(v as DmScope)}>
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {DM_SCOPE_OPTIONS.map((option) => (
+                  <SelectItem key={option.value} value={option.value}>
+                    {option.label}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
           </div>
           <div className="space-y-2">
             <label className="text-sm font-medium text-gray-800">
@@ -429,10 +431,10 @@ export function RuntimeConfig() {
                     }
                     placeholder="Account ID (optional)"
                   />
-                  <select
-                    value={peerKind}
-                    onChange={(event) => {
-                      const nextKind = event.target.value as PeerKind;
+                  <Select
+                    value={peerKind || '__none__'}
+                    onValueChange={(v) => {
+                      const nextKind = v === '__none__' ? '' : v as PeerKind;
                       if (!nextKind) {
                         updateBinding(index, {
                           ...binding,
@@ -454,13 +456,17 @@ export function RuntimeConfig() {
                         }
                       });
                     }}
-                    className="flex h-10 w-full rounded-lg border border-gray-200 bg-white px-3 py-2 text-sm"
                   >
-                    <option value="">Peer kind (optional)</option>
-                    <option value="direct">direct</option>
-                    <option value="group">group</option>
-                    <option value="channel">channel</option>
-                  </select>
+                    <SelectTrigger>
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      <SelectItem value="__none__">Peer kind (optional)</SelectItem>
+                      <SelectItem value="direct">direct</SelectItem>
+                      <SelectItem value="group">group</SelectItem>
+                      <SelectItem value="channel">channel</SelectItem>
+                    </SelectContent>
+                  </Select>
                   <Input
                     value={binding.match.peer?.id ?? ''}
                     onChange={(event) =>
@@ -470,9 +476,9 @@ export function RuntimeConfig() {
                           ...binding.match,
                           peer: peerKind
                             ? {
-                                kind: peerKind,
-                                id: event.target.value
-                              }
+                              kind: peerKind,
+                              id: event.target.value
+                            }
                             : undefined
                         }
                       })

package/src/components/doc-browser/DocBrowser.tsx CHANGED Viewed

@@ -23,20 +23,26 @@ import {
  */
 export function DocBrowser() {
     const {
-        isOpen, mode, currentUrl,
+        isOpen, mode, currentUrl, navVersion,
         close, toggleMode,
         goBack, goForward, canGoBack, canGoForward,
-        navigate,
+        navigate, syncUrl,
     } = useDocBrowser();
     const [urlInput, setUrlInput] = useState('');
     const [isDragging, setIsDragging] = useState(false);
-    const [floatPos, setFloatPos] = useState({ x: 120, y: 80 });
+    const [isResizing, setIsResizing] = useState(false);
+    const [floatPos, setFloatPos] = useState(() => ({
+        x: Math.max(40, window.innerWidth - 520),
+        y: 80,
+    }));
     const [floatSize, setFloatSize] = useState({ w: 480, h: 600 });
     const [dockedWidth, setDockedWidth] = useState(420);
     const dragRef = useRef<{ startX: number; startY: number; startPosX: number; startPosY: number } | null>(null);
     const resizeRef = useRef<{ startX: number; startY: number; startW: number; startH: number } | null>(null);
     const dockResizeRef = useRef<{ startX: number; startW: number } | null>(null);
+    const iframeRef = useRef<HTMLIFrameElement>(null);
+    const prevNavVersionRef = useRef(navVersion);
     // Sync URL input with current URL
     useEffect(() => {
@@ -48,16 +54,43 @@ export function DocBrowser() {
         }
     }, [currentUrl]);
+    // When currentUrl changes without navVersion bump (goBack/goForward),
+    // use postMessage to SPA-navigate inside the iframe instead of remounting
+    useEffect(() => {
+        if (navVersion !== prevNavVersionRef.current) {
+            // navVersion changed — iframe will remount via key, no need to postMessage
+            prevNavVersionRef.current = navVersion;
+            return;
+        }
+        // Same navVersion — means goBack/goForward triggered
+        if (iframeRef.current?.contentWindow) {
+            try {
+                const path = new URL(currentUrl).pathname;
+                iframeRef.current.contentWindow.postMessage({ type: 'docs-navigate', path }, '*');
+            } catch { /* ignore */ }
+        }
+    }, [currentUrl, navVersion]);
+    // Reposition floating window near right edge when switching from docked
+    useEffect(() => {
+        if (mode === 'floating') {
+            setFloatPos(prev => ({
+                x: Math.max(40, window.innerWidth - floatSize.w - 40),
+                y: prev.y,
+            }));
+        }
+    }, [mode, floatSize.w]);
     // Listen for route changes from the iframe via postMessage
     useEffect(() => {
         const handler = (e: MessageEvent) => {
             if (e.data?.type === 'docs-route-change' && typeof e.data.url === 'string') {
-                navigate(e.data.url);
+                syncUrl(e.data.url);
             }
         };
         window.addEventListener('message', handler);
         return () => window.removeEventListener('message', handler);
-    }, [navigate]);
+    }, [syncUrl]);
     const handleUrlSubmit = useCallback((e: React.FormEvent) => {
         e.preventDefault();
@@ -105,10 +138,12 @@ export function DocBrowser() {
         };
     }, [isDragging]);
-    // --- Resize logic (floating mode — bottom-right corner) ---
+    // --- Resize logic (floating mode) ---
     const onResizeStart = useCallback((e: React.MouseEvent) => {
         e.preventDefault();
         e.stopPropagation();
+        setIsResizing(true);
+        const axis = (e.currentTarget as HTMLElement).dataset.axis; // 'x', 'y', or undefined (both)
         resizeRef.current = {
             startX: e.clientX,
             startY: e.clientY,
@@ -117,12 +152,13 @@ export function DocBrowser() {
         };
         const onMove = (ev: MouseEvent) => {
             if (!resizeRef.current) return;
-            setFloatSize({
-                w: Math.max(360, resizeRef.current.startW + (ev.clientX - resizeRef.current.startX)),
-                h: Math.max(400, resizeRef.current.startH + (ev.clientY - resizeRef.current.startY)),
-            });
+            setFloatSize(prev => ({
+                w: axis === 'y' ? prev.w : Math.max(360, resizeRef.current!.startW + (ev.clientX - resizeRef.current!.startX)),
+                h: axis === 'x' ? prev.h : Math.max(400, resizeRef.current!.startH + (ev.clientY - resizeRef.current!.startY)),
+            }));
         };
         const onUp = () => {
+            setIsResizing(false);
             resizeRef.current = null;
             window.removeEventListener('mousemove', onMove);
             window.removeEventListener('mouseup', onUp);
@@ -135,14 +171,15 @@ export function DocBrowser() {
     const onDockResizeStart = useCallback((e: React.MouseEvent) => {
         e.preventDefault();
         e.stopPropagation();
+        setIsResizing(true);
         dockResizeRef.current = { startX: e.clientX, startW: dockedWidth };
         const onMove = (ev: MouseEvent) => {
             if (!dockResizeRef.current) return;
-            // Dragging left should increase width (since resize handle is on the left edge)
             const delta = dockResizeRef.current.startX - ev.clientX;
             setDockedWidth(Math.max(320, Math.min(800, dockResizeRef.current.startW + delta)));
         };
         const onUp = () => {
+            setIsResizing(false);
             dockResizeRef.current = null;
             window.removeEventListener('mousemove', onMove);
             window.removeEventListener('mouseup', onUp);
@@ -151,6 +188,29 @@ export function DocBrowser() {
         window.addEventListener('mouseup', onUp);
     }, [dockedWidth]);
+    // --- Left-edge resize logic (floating mode — adjusts both position and width) ---
+    const onLeftResizeStart = useCallback((e: React.MouseEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+        setIsResizing(true);
+        const startX = e.clientX;
+        const startW = floatSize.w;
+        const startPosX = floatPos.x;
+        const onMove = (ev: MouseEvent) => {
+            const delta = startX - ev.clientX;
+            const newW = Math.max(360, startW + delta);
+            setFloatSize(prev => ({ ...prev, w: newW }));
+            setFloatPos(prev => ({ ...prev, x: startPosX - (newW - startW) }));
+        };
+        const onUp = () => {
+            setIsResizing(false);
+            window.removeEventListener('mousemove', onMove);
+            window.removeEventListener('mouseup', onUp);
+        };
+        window.addEventListener('mousemove', onMove);
+        window.addEventListener('mouseup', onUp);
+    }, [floatSize.w, floatPos.x]);
     if (!isOpen) return null;
     const isDocked = mode === 'docked';
@@ -246,13 +306,18 @@ export function DocBrowser() {
             {/* Iframe Content */}
             <div className="flex-1 relative overflow-hidden">
                 <iframe
-                    key={currentUrl}
+                    ref={iframeRef}
+                    key={navVersion}
                     src={currentUrl}
                     className="absolute inset-0 w-full h-full border-0"
                     title="NextClaw Documentation"
                     sandbox="allow-same-origin allow-scripts allow-popups allow-forms"
                     allow="clipboard-read; clipboard-write"
                 />
+                {/* Transparent overlay during resize to prevent iframe from stealing mouse events */}
+                {(isResizing || isDragging) && (
+                    <div className="absolute inset-0 z-10" />
+                )}
             </div>
             {/* Footer */}
@@ -261,6 +326,7 @@ export function DocBrowser() {
                     href={currentUrl}
                     target="_blank"
                     rel="noopener noreferrer"
+                    data-doc-external
                     className="flex items-center gap-1.5 text-xs text-primary hover:text-primary-hover font-medium transition-colors"
                 >
                     {t('docBrowserOpenExternal')}
@@ -268,14 +334,23 @@ export function DocBrowser() {
                 </a>
             </div>
-            {/* Resize Handle (floating only — bottom-right corner) */}
+            {/* Resize Handles (floating only) */}
             {!isDocked && (
-                <div
-                    className="absolute bottom-0 right-0 w-5 h-5 cursor-se-resize flex items-center justify-center text-gray-300 hover:text-gray-500 transition-colors"
-                    onMouseDown={onResizeStart}
-                >
-                    <GripVertical className="w-3 h-3 rotate-[-45deg]" />
-                </div>
+                <>
+                    {/* Left edge */}
+                    <div className="absolute top-0 left-0 w-1.5 h-full cursor-ew-resize z-20 hover:bg-primary/10 transition-colors" onMouseDown={onLeftResizeStart} />
+                    {/* Right edge */}
+                    <div className="absolute top-0 right-0 w-1.5 h-full cursor-ew-resize z-20 hover:bg-primary/10 transition-colors" onMouseDown={onResizeStart} data-axis="x" />
+                    {/* Bottom edge */}
+                    <div className="absolute bottom-0 left-0 h-1.5 w-full cursor-ns-resize z-20 hover:bg-primary/10 transition-colors" onMouseDown={onResizeStart} data-axis="y" />
+                    {/* Bottom-right corner */}
+                    <div
+                        className="absolute bottom-0 right-0 w-4 h-4 cursor-se-resize z-30 flex items-center justify-center text-gray-300 hover:text-gray-500 transition-colors"
+                        onMouseDown={onResizeStart}
+                    >
+                        <GripVertical className="w-3 h-3 rotate-[-45deg]" />
+                    </div>
+                </>
             )}
         </div>
     );

package/src/components/doc-browser/DocBrowserContext.tsx CHANGED Viewed

@@ -1,24 +1,31 @@
 import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from 'react';
 const DOCS_PRIMARY_DOMAIN = 'docs.nextclaw.io';
-const DOCS_FALLBACK_DOMAIN = 'nextclaw-docs.pages.dev';
+const DOCS_PAGES_DEV = 'nextclaw-docs.pages.dev';
 const DOCS_HOSTS = new Set([
     DOCS_PRIMARY_DOMAIN,
     `www.${DOCS_PRIMARY_DOMAIN}`,
-    DOCS_FALLBACK_DOMAIN,
-    `www.${DOCS_FALLBACK_DOMAIN}`,
+    DOCS_PAGES_DEV,
+    `www.${DOCS_PAGES_DEV}`,
 ]);
-export const DOCS_DEFAULT_BASE_URL = `https://${DOCS_FALLBACK_DOMAIN}`;
+export const DOCS_DEFAULT_BASE_URL = `https://${DOCS_PRIMARY_DOMAIN}`;
 export type DocBrowserMode = 'floating' | 'docked';
+/** Normalize URL for comparison: strip .html and trailing slash */
+function normalizeDocUrl(u: string): string {
+    try { return new URL(u).pathname.replace(/\.html$/, '').replace(/\/$/, ''); } catch { return u; }
+}
 interface DocBrowserState {
     isOpen: boolean;
     mode: DocBrowserMode;
     currentUrl: string;
     history: string[];
     historyIndex: number;
+    /** Increments on parent-initiated navigation (navigate/goBack/goForward) */
+    navVersion: number;
 }
 interface DocBrowserActions {
@@ -26,7 +33,10 @@ interface DocBrowserActions {
     close: () => void;
     toggleMode: () => void;
     setMode: (mode: DocBrowserMode) => void;
+    /** Parent-initiated navigation — will cause iframe to reload to this URL */
     navigate: (url: string) => void;
+    /** Iframe-initiated sync — records URL to history without reloading iframe */
+    syncUrl: (url: string) => void;
     goBack: () => void;
     goForward: () => void;
     canGoBack: boolean;
@@ -60,6 +70,7 @@ export function DocBrowserProvider({ children }: { children: ReactNode }) {
         currentUrl: `${DOCS_DEFAULT_BASE_URL}/guide/getting-started`,
         history: [`${DOCS_DEFAULT_BASE_URL}/guide/getting-started`],
         historyIndex: 0,
+        navVersion: 0,
     });
     const open = useCallback((url?: string) => {
@@ -70,6 +81,7 @@ export function DocBrowserProvider({ children }: { children: ReactNode }) {
             currentUrl: targetUrl,
             history: [...prev.history.slice(0, prev.historyIndex + 1), targetUrl],
             historyIndex: prev.historyIndex + 1,
+            navVersion: prev.navVersion + 1,
         }));
     }, [state.currentUrl]);
@@ -85,14 +97,24 @@ export function DocBrowserProvider({ children }: { children: ReactNode }) {
         setState(prev => ({ ...prev, mode }));
     }, []);
+    /** Parent-initiated: push to history AND bump navVersion so iframe reloads */
     const navigate = useCallback((url: string) => {
         setState(prev => {
-            // Normalize URLs for comparison (strip trailing slash, .html suffix)
-            const normalize = (u: string) => {
-                try { return new URL(u).pathname.replace(/\.html$/, '').replace(/\/$/, ''); } catch { return u; }
+            if (normalizeDocUrl(url) === normalizeDocUrl(prev.currentUrl)) return prev;
+            return {
+                ...prev,
+                currentUrl: url,
+                history: [...prev.history.slice(0, prev.historyIndex + 1), url],
+                historyIndex: prev.historyIndex + 1,
+                navVersion: prev.navVersion + 1,
             };
-            // Skip if same as current URL (prevents loop from postMessage echo)
-            if (normalize(url) === normalize(prev.currentUrl)) return prev;
+        });
+    }, []);
+    /** Iframe-initiated: push to history but do NOT bump navVersion (no iframe reload) */
+    const syncUrl = useCallback((url: string) => {
+        setState(prev => {
+            if (normalizeDocUrl(url) === normalizeDocUrl(prev.currentUrl)) return prev;
             return {
                 ...prev,
                 currentUrl: url,
@@ -128,11 +150,12 @@ export function DocBrowserProvider({ children }: { children: ReactNode }) {
         toggleMode,
         setMode,
         navigate,
+        syncUrl,
         goBack,
         goForward,
         canGoBack,
         canGoForward,
-    }), [state, open, close, toggleMode, setMode, navigate, goBack, goForward, canGoBack, canGoForward]);
+    }), [state, open, close, toggleMode, setMode, navigate, syncUrl, goBack, goForward, canGoBack, canGoForward]);
     return (
         <DocBrowserContext.Provider value={value}>