@nextclaw/ui 0.12.35-beta.6 → 0.12.35

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

@@ -1,14 +1,16 @@
 import { useState, useRef, useCallback, useEffect } from 'react';
 import {
   DOCS_DEFAULT_BASE_URL,
+  DOC_BROWSER_HOME_TAB_KIND,
   useDocBrowser,
 } from './doc-browser-context';
+import { normalizeDocUrl } from './utils/doc-browser-url.utils';
+import { DocBrowserHomePage } from './doc-browser-home-page';
 import type { DocBrowserCustomTabRenderers } from './doc-browser-renderer.types';
 import {
   DocBrowserDocsToolbar,
   DocBrowserExternalLink,
   DocBrowserFrameContent,
-  DocBrowserPanelHeader,
 } from './doc-browser-panel-parts';
 import { DocBrowserTabStrip } from './doc-browser-tab-strip';
 import { ResizableRightPanel } from '@/shared/components/resizable-right-panel/resizable-right-panel';
@@ -38,6 +40,15 @@ function clamp(value: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, value));
 }
 
+function createInitialFloatingPanelRect(): FloatingPanelRect {
+  return {
+    x: Math.max(FLOATING_PANEL_MARGIN, window.innerWidth - 520),
+    y: 80,
+    w: 480,
+    h: 600,
+  };
+}
+
 export function DocBrowser({
   customTabRenderers = {},
   displayMode = 'desktop',
@@ -47,8 +58,11 @@ export function DocBrowser({
     mode,
     tabs,
     activeTabId,
+    activeHistory,
+    activeHistoryIndex,
     currentTab,
     open,
+    openNewTab,
     close,
     toggleMode,
     goBack,
@@ -61,18 +75,18 @@ export function DocBrowser({
 
   const [urlInput, setUrlInput] = useState('');
   const [iframeReloadVersion, setIframeReloadVersion] = useState(0);
-  const [floatRect, setFloatRect] = useState<FloatingPanelRect>(() => ({
-    x: Math.max(FLOATING_PANEL_MARGIN, window.innerWidth - 520),
-    y: 80,
-    w: 480,
-    h: 600,
-  }));
+  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 navVersion = currentTab?.navVersion ?? 0;
+  const iframeInstanceId = `${activeTabId}:${navVersion}:${iframeReloadVersion}`;
+  const pendingParentDocsUrlRef = useRef<string | null>(null);
   const prevNavVersionRef = useRef(navVersion);
   const isDocsTab = currentTab?.kind === 'docs';
+  const isHomeTab = currentTab?.kind === DOC_BROWSER_HOME_TAB_KIND;
+  const canGoBack = activeHistoryIndex > 0;
+  const canGoForward = activeHistoryIndex < activeHistory.length - 1;
   const customRenderer = currentTab ? customTabRenderers[currentTab.kind] : undefined;
 
   useEffect(() => {
@@ -92,16 +106,19 @@ export function DocBrowser({
   // use postMessage to SPA-navigate inside the iframe instead of remounting.
   useEffect(() => {
     if (!isDocsTab) {
+      pendingParentDocsUrlRef.current = null;
       return;
     }
     if (navVersion !== prevNavVersionRef.current) {
       prevNavVersionRef.current = navVersion;
+      pendingParentDocsUrlRef.current = normalizeDocUrl(currentUrl);
       return;
     }
 
     if (iframeRef.current?.contentWindow) {
       try {
         const path = new URL(currentUrl).pathname;
+        pendingParentDocsUrlRef.current = normalizeDocUrl(currentUrl);
         iframeRef.current.contentWindow.postMessage({ type: 'docs-navigate', path }, '*');
       } catch {
         // ignore postMessage errors
@@ -115,12 +132,17 @@ export function DocBrowser({
         return;
       }
       if (e.data?.type === 'docs-route-change' && typeof e.data.url === 'string') {
+        const eventUrl = normalizeDocUrl(e.data.url);
+        if (pendingParentDocsUrlRef.current && eventUrl !== pendingParentDocsUrlRef.current) {
+          return;
+        }
+        pendingParentDocsUrlRef.current = null;
         syncUrl(e.data.url);
       }
     };
     window.addEventListener('message', handler);
     return () => window.removeEventListener('message', handler);
-  }, [syncUrl, isDocsTab]);
+  }, [currentUrl, syncUrl, isDocsTab]);
 
   useEffect(() => {
     if (!currentTab || !customRenderer?.onIframeMessage) {
@@ -130,12 +152,13 @@ export function DocBrowser({
       customRenderer.onIframeMessage?.({
         event,
         iframe: iframeRef.current,
+        iframeInstanceId,
         tab: currentTab,
       });
     };
     window.addEventListener('message', handler);
     return () => window.removeEventListener('message', handler);
-  }, [currentTab, customRenderer]);
+  }, [currentTab, customRenderer, iframeInstanceId]);
 
   const startFloatDrag = useCallback((event: React.PointerEvent<HTMLElement>) => {
     event.preventDefault();
@@ -236,36 +259,34 @@ export function DocBrowser({
     tab: currentTab,
   } : undefined;
   const customToolbar = customRenderParams ? customRenderer?.renderToolbar?.(customRenderParams) : null;
-  const customContent = customRenderParams ? customRenderer?.renderContent?.(customRenderParams) : null;
+  const customContent = customRenderParams
+    ? customRenderer?.renderContent?.(customRenderParams) ?? (isHomeTab ? <DocBrowserHomePage open={open} /> : null)
+    : null;
   const iframeSandbox = currentTab
     ? customRenderer?.getIframeSandbox?.(currentTab) ?? 'allow-same-origin allow-scripts allow-popups allow-forms'
     : 'allow-same-origin allow-scripts allow-popups allow-forms';
 
   const panelContent = (
     <>
-      <DocBrowserPanelHeader
-        currentTab={currentTab}
-        customRenderer={customRenderer}
-        isDocked={isDocked}
-        isFullscreen={isFullscreen}
-        onClose={close}
-        onDragStart={startFloatDrag}
-        onToggleMode={toggleMode}
-      />
-
       <DocBrowserTabStrip
         tabs={tabs}
         activeTabId={activeTabId}
-        onOpenDocs={() => open(undefined, { kind: 'docs', newTab: true, title: 'Docs' })}
+        canGoBack={canGoBack}
+        canGoForward={canGoForward}
+        isDocked={isDocked}
+        isFullscreen={isFullscreen}
+        onGoBack={goBack}
+        onGoForward={goForward}
+        onOpenNewTab={openNewTab}
         onSetActiveTab={setActiveTab}
         onCloseTab={closeTab}
+        onClose={close}
+        onDragStart={startFloatDrag}
+        onToggleMode={toggleMode}
       />
 
       <DocBrowserDocsToolbar
-        currentTab={currentTab}
         isDocsTab={isDocsTab}
-        onBack={goBack}
-        onForward={goForward}
         onSubmit={handleUrlSubmit}
         onUrlInputChange={setUrlInput}
         urlInput={urlInput}
@@ -274,16 +295,14 @@ export function DocBrowser({
       {customToolbar}
 
       <DocBrowserFrameContent
-        activeTabId={activeTabId}
         currentTab={currentTab}
         currentUrl={currentUrl}
         customContent={customContent}
         iframeRef={iframeRef}
-        iframeReloadVersion={iframeReloadVersion}
+        iframeInstanceId={iframeInstanceId}
         iframeSandbox={iframeSandbox}
         isDragging={floatInteraction?.kind === 'drag'}
         isResizing={floatInteraction?.kind === 'resize'}
-        navVersion={navVersion}
       />
 
       <DocBrowserExternalLink currentUrl={currentUrl} isDocsTab={isDocsTab} />

package/src/shared/components/doc-browser/managers/doc-browser.manager.ts

@@ -1,4 +1,5 @@
 import type {
+  DocBrowserActiveHistoryEntry,
   DocBrowserOpenOptions,
   DocBrowserState,
   DocBrowserStateUpdate,
@@ -6,15 +7,17 @@ import type {
   DocBrowserTabKind,
 } from '@/shared/components/doc-browser/types/doc-browser.types';
 import {
+  createDocBrowserActiveHistoryEntry,
   createDefaultDocBrowserState,
   createDocBrowserTab,
 } from '@/shared/components/doc-browser/utils/doc-browser-state.utils';
 import {
+  DOC_BROWSER_HOME_TAB_KIND,
   getDefaultDocsUrl,
-  inferTabKind,
-  normalizeDocUrl,
-  normalizeUrlByKind,
 } from '@/shared/components/doc-browser/utils/doc-browser-url.utils';
+import {
+  docBrowserRouteRegistry,
+} from '@/shared/components/doc-browser/utils/doc-browser-route-registry.utils';
 import { useDocBrowserStore } from '@/shared/components/doc-browser/stores/doc-browser.store';
 
 function updateTab(
@@ -32,61 +35,103 @@ function updateActiveTab(state: DocBrowserState, updater: (tab: DocBrowserTab) =
   return updateTab(state, state.activeTabId, updater);
 }
 
-function areOpenUrlsEquivalent(
-  currentUrl: string,
-  nextUrl: string,
-  currentKind: DocBrowserTabKind,
-  nextKind: DocBrowserTabKind,
+function appendManualNavigation(tab: DocBrowserTab, url: string): Pick<DocBrowserTab, 'history' | 'historyIndex'> {
+  const history = [...tab.history.slice(0, tab.historyIndex + 1), url];
+  return {
+    history,
+    historyIndex: history.length - 1,
+  };
+}
+
+function areActiveHistoryEntriesEquivalent(
+  current: DocBrowserActiveHistoryEntry,
+  next: DocBrowserActiveHistoryEntry,
 ): boolean {
-  if (currentKind === 'docs' && nextKind === 'docs') {
-    return normalizeDocUrl(currentUrl) === normalizeDocUrl(nextUrl);
+  return current.tabId === next.tabId
+    && current.kind === next.kind
+    && docBrowserRouteRegistry.areUrlsEquivalent(current.url, next.url, current.kind, next.kind);
+}
+
+function pushActiveHistory(state: DocBrowserState, entry: DocBrowserActiveHistoryEntry): DocBrowserState {
+  const current = state.activeHistory[state.activeHistoryIndex];
+  if (current && areActiveHistoryEntriesEquivalent(current, entry)) {
+    return state;
+  }
+  const activeHistory = [...state.activeHistory.slice(0, state.activeHistoryIndex + 1), entry];
+  return {
+    ...state,
+    activeHistory,
+    activeHistoryIndex: activeHistory.length - 1,
+  };
+}
+
+function findTabHistoryIndex(tab: DocBrowserTab, url: string): number {
+  for (let index = tab.history.length - 1; index >= 0; index -= 1) {
+    if (docBrowserRouteRegistry.areUrlsEquivalent(tab.history[index], url, tab.kind, tab.kind)) {
+      return index;
+    }
   }
-  return currentUrl === nextUrl;
+  return -1;
+}
+
+function restoreActiveHistoryEntry(state: DocBrowserState, entry: DocBrowserActiveHistoryEntry): DocBrowserState {
+  const tab = state.tabs.find((item) => item.id === entry.tabId);
+  if (!tab) {
+    return state;
+  }
+  const target = docBrowserRouteRegistry.resolveOpenTarget({
+    activeTab: tab,
+    kind: entry.kind,
+    url: entry.url,
+  });
+  const historyIndex = findTabHistoryIndex(tab, target.url);
+  return updateTab(
+    {
+      ...state,
+      activeTabId: tab.id,
+      isOpen: true,
+    },
+    tab.id,
+    (currentTab) => ({
+      ...currentTab,
+      currentUrl: target.url,
+      dedupeKey: target.dedupeKey,
+      historyIndex: historyIndex >= 0 ? historyIndex : currentTab.historyIndex,
+      kind: target.kind,
+      title: target.title,
+    }),
+  );
 }
 
 function updateTabForOpen(
   tab: DocBrowserTab,
-  url: string,
-  kind: DocBrowserTabKind,
+  target: {
+    kind: DocBrowserTabKind;
+    title: string;
+    url: string;
+  },
   options?: DocBrowserOpenOptions,
   dedupeKey?: string,
 ): DocBrowserTab {
   const baseTab = {
     ...tab,
-    title: options?.title || tab.title,
-    kind,
+    title: options?.title || target.title || tab.title,
+    kind: target.kind,
     dedupeKey,
   };
 
-  if (areOpenUrlsEquivalent(tab.currentUrl, url, tab.kind, kind)) {
+  if (docBrowserRouteRegistry.areUrlsEquivalent(tab.currentUrl, target.url, tab.kind, target.kind)) {
     return baseTab;
   }
 
   return {
     ...baseTab,
-    currentUrl: url,
-    history: [...tab.history.slice(0, tab.historyIndex + 1), url],
-    historyIndex: tab.historyIndex + 1,
+    currentUrl: target.url,
+    ...appendManualNavigation(tab, target.url),
     navVersion: tab.navVersion + 1,
   };
 }
 
-function resolveOpenTargetUrl(params: {
-  url?: string;
-  kind: DocBrowserTabKind;
-  activeTab?: DocBrowserTab;
-}): string {
-  const { activeTab, kind, url } = params;
-  if (url && url.trim().length > 0) {
-    return normalizeUrlByKind(url, kind);
-  }
-
-  if (kind === 'docs') {
-    return getDefaultDocsUrl();
-  }
-  return activeTab?.currentUrl ?? getDefaultDocsUrl();
-}
-
 function openDocBrowserState(
   prev: DocBrowserState,
   url?: string,
@@ -100,9 +145,12 @@ function openDocBrowserState(
     title,
   } = options ?? {};
   const activeTab = prev.tabs.find((tab) => tab.id === prev.activeTabId) ?? prev.tabs[0];
-  const targetKind = kind ?? (url ? inferTabKind(url) : activeTab?.kind ?? 'docs');
-  const targetUrl = resolveOpenTargetUrl({ url, kind: targetKind, activeTab });
-  const dedupeKey = rawDedupeKey?.trim() || undefined;
+  const target = docBrowserRouteRegistry.resolveOpenTarget({
+    activeTab,
+    kind,
+    url,
+  });
+  const dedupeKey = rawDedupeKey?.trim() || target.dedupeKey;
   const matchedTab = dedupeKey
     ? prev.tabs.find((tab) => tab.dedupeKey === dedupeKey)
     : undefined;
@@ -111,30 +159,40 @@ function openDocBrowserState(
     const next = updateTab(
       prev,
       matchedTab.id,
-      (tab) => updateTabForOpen(tab, targetUrl, targetKind, options, dedupeKey),
+      (tab) => updateTabForOpen(tab, target, options, dedupeKey),
     );
-    return {
+    const shouldActivate = activate !== false;
+    const activeTabId = shouldActivate ? matchedTab.id : prev.activeTabId;
+    const nextState = {
       ...next,
-      activeTabId: activate === false ? prev.activeTabId : matchedTab.id,
+      activeTabId,
       isOpen: true,
     };
+    const shouldPushActiveHistory = shouldActivate || matchedTab.id === prev.activeTabId;
+    return shouldPushActiveHistory
+      ? pushActiveHistory(nextState, { kind: target.kind, tabId: matchedTab.id, url: target.url })
+      : nextState;
   }
 
-  if (shouldForceNewTab || dedupeKey || !activeTab || activeTab.kind !== targetKind) {
-    const newTab = createDocBrowserTab(targetUrl, targetKind, title, dedupeKey);
-    return {
+  if (shouldForceNewTab || dedupeKey || !activeTab || activeTab.kind !== target.kind) {
+    const newTab = createDocBrowserTab(target.url, target.kind, title ?? target.title, dedupeKey);
+    const nextState = {
       ...prev,
       isOpen: true,
       tabs: [...prev.tabs, newTab],
       activeTabId: newTab.id,
     };
+    return pushActiveHistory(nextState, createDocBrowserActiveHistoryEntry(newTab));
   }
 
   const next = updateActiveTab(
     prev,
-    (tab) => updateTabForOpen(tab, targetUrl, targetKind, options, dedupeKey),
+    (tab) => updateTabForOpen(tab, target, options, dedupeKey),
+  );
+  return pushActiveHistory(
+    { ...next, isOpen: true },
+    { kind: target.kind, tabId: prev.activeTabId, url: target.url },
   );
-  return { ...next, isOpen: true };
 }
 
 export class DocBrowserManager {
@@ -146,6 +204,10 @@ export class DocBrowserManager {
     this.setSnapshot((prev) => openDocBrowserState(prev, url, options));
   };
 
+  readonly openNewTab = (): void => {
+    this.open(undefined, { kind: DOC_BROWSER_HOME_TAB_KIND, newTab: true });
+  };
+
   readonly close = (): void => {
     this.setSnapshot((prev) => ({ ...prev, isOpen: false }));
   };
@@ -166,24 +228,30 @@ export class DocBrowserManager {
         };
       }
 
-      return updateActiveTab(prev, (tab) => {
-        if (tab.kind !== 'docs') {
+      const next = updateActiveTab(prev, (tab) => {
+        if (!docBrowserRouteRegistry.usesManagedHistory(tab)) {
           return tab;
         }
+        const target = docBrowserRouteRegistry.resolveOpenTarget({ activeTab: tab, url });
 
-        const targetUrl = normalizeUrlByKind(url, 'docs');
-        if (normalizeDocUrl(targetUrl) === normalizeDocUrl(tab.currentUrl)) {
+        if (docBrowserRouteRegistry.areUrlsEquivalent(tab.currentUrl, target.url, tab.kind, target.kind)) {
           return tab;
         }
 
         return {
           ...tab,
-          currentUrl: targetUrl,
-          history: [...tab.history.slice(0, tab.historyIndex + 1), targetUrl],
-          historyIndex: tab.historyIndex + 1,
+          currentUrl: target.url,
+          dedupeKey: target.dedupeKey,
+          ...appendManualNavigation(tab, target.url),
+          kind: target.kind,
           navVersion: tab.navVersion + 1,
+          title: target.title,
         };
       });
+      const currentTab = next.tabs.find((tab) => tab.id === next.activeTabId);
+      return currentTab
+        ? pushActiveHistory(next, createDocBrowserActiveHistoryEntry(currentTab))
+        : next;
     });
   };
 
@@ -198,39 +266,58 @@ export class DocBrowserManager {
         };
       }
 
-      return updateActiveTab(prev, (tab) => {
-        if (tab.kind !== 'docs') {
+      const next = updateActiveTab(prev, (tab) => {
+        if (!docBrowserRouteRegistry.usesManagedHistory(tab)) {
           return tab;
         }
+        const target = docBrowserRouteRegistry.resolveOpenTarget({ activeTab: tab, kind: tab.kind, url });
 
-        if (normalizeDocUrl(url) === normalizeDocUrl(tab.currentUrl)) {
+        if (docBrowserRouteRegistry.areUrlsEquivalent(tab.currentUrl, target.url, tab.kind, target.kind)) {
           return tab;
         }
 
         return {
           ...tab,
-          currentUrl: url,
-          history: [...tab.history.slice(0, tab.historyIndex + 1), url],
-          historyIndex: tab.historyIndex + 1,
+          currentUrl: target.url,
+          dedupeKey: target.dedupeKey,
+          ...appendManualNavigation(tab, target.url),
+          kind: target.kind,
+          title: target.title,
         };
       });
+      const currentTab = next.tabs.find((tab) => tab.id === next.activeTabId);
+      return currentTab
+        ? pushActiveHistory(next, createDocBrowserActiveHistoryEntry(currentTab))
+        : next;
     });
   };
 
   readonly goBack = (): void => {
-    this.setSnapshot((prev) => updateActiveTab(prev, (tab) => {
-      if (tab.kind !== 'docs' || tab.historyIndex <= 0) return tab;
-      const newIndex = tab.historyIndex - 1;
-      return { ...tab, historyIndex: newIndex, currentUrl: tab.history[newIndex] };
-    }));
+    this.setSnapshot((prev) => {
+      if (prev.activeHistoryIndex <= 0) {
+        return prev;
+      }
+      const activeHistoryIndex = prev.activeHistoryIndex - 1;
+      const entry = prev.activeHistory[activeHistoryIndex];
+      if (!entry) {
+        return prev;
+      }
+      return restoreActiveHistoryEntry({ ...prev, activeHistoryIndex }, entry);
+    });
   };
 
   readonly goForward = (): void => {
-    this.setSnapshot((prev) => updateActiveTab(prev, (tab) => {
-      if (tab.kind !== 'docs' || tab.historyIndex >= tab.history.length - 1) return tab;
-      const newIndex = tab.historyIndex + 1;
-      return { ...tab, historyIndex: newIndex, currentUrl: tab.history[newIndex] };
-    }));
+    this.setSnapshot((prev) => {
+      if (prev.activeHistoryIndex >= prev.activeHistory.length - 1) {
+        return prev;
+      }
+      const activeHistoryIndex = prev.activeHistoryIndex + 1;
+      const entry = prev.activeHistory[activeHistoryIndex];
+      if (!entry) {
+        return prev;
+      }
+      return restoreActiveHistoryEntry({ ...prev, activeHistoryIndex }, entry);
+    });
   };
 
   readonly closeTab = (tabId: string): void => {
@@ -253,11 +340,29 @@ export class DocBrowserManager {
         ? nextTabs[Math.max(0, index - 1)]?.id ?? nextTabs[0].id
         : prev.activeTabId;
 
-      return {
+      const nextState = {
         ...prev,
         tabs: nextTabs,
         activeTabId: nextActiveId,
       };
+      const activeHistory = nextState.activeHistory.filter((entry) => entry.tabId !== tabId);
+      const activeHistoryBeforeIndex = nextState.activeHistory
+        .slice(0, nextState.activeHistoryIndex + 1)
+        .filter((entry) => entry.tabId !== tabId);
+      const nextActiveTab = nextTabs.find((tab) => tab.id === nextActiveId) ?? nextTabs[0];
+      const reconciledState = {
+        ...nextState,
+        activeHistory: activeHistory.length > 0
+          ? activeHistory
+          : [createDocBrowserActiveHistoryEntry(nextActiveTab)],
+        activeHistoryIndex: Math.min(
+          Math.max(0, activeHistoryBeforeIndex.length - 1),
+          Math.max(0, activeHistory.length - 1),
+        ),
+      };
+      return prev.activeTabId === tabId
+        ? pushActiveHistory(reconciledState, createDocBrowserActiveHistoryEntry(nextActiveTab))
+        : reconciledState;
     });
   };
 
@@ -266,7 +371,14 @@ export class DocBrowserManager {
       if (!prev.tabs.some((tab) => tab.id === tabId)) {
         return prev;
       }
-      return { ...prev, activeTabId: tabId, isOpen: true };
+      const tab = prev.tabs.find((item) => item.id === tabId);
+      if (!tab) {
+        return prev;
+      }
+      return pushActiveHistory(
+        { ...prev, activeTabId: tabId, isOpen: true },
+        createDocBrowserActiveHistoryEntry(tab),
+      );
     });
   };
 }

package/src/shared/components/doc-browser/stores/doc-browser.store.ts

@@ -1,6 +1,7 @@
 import { create } from 'zustand';
 import { createJSONStorage, persist } from 'zustand/middleware';
 import type {
+  DocBrowserActiveHistoryEntry,
   DocBrowserMode,
   DocBrowserState,
   DocBrowserStateUpdate,
@@ -71,6 +72,36 @@ function normalizePersistedDocBrowserTab(value: unknown): DocBrowserTab | null {
   };
 }
 
+function createActiveHistoryEntryFromTab(tab: DocBrowserTab): DocBrowserActiveHistoryEntry {
+  return {
+    kind: tab.kind,
+    tabId: tab.id,
+    url: tab.currentUrl,
+  };
+}
+
+function normalizePersistedActiveHistoryEntry(
+  value: unknown,
+  tabsById: Map<string, DocBrowserTab>,
+): DocBrowserActiveHistoryEntry | null {
+  if (
+    !isRecord(value)
+    || typeof value.tabId !== 'string'
+    || typeof value.kind !== 'string'
+    || typeof value.url !== 'string'
+    || value.url.trim().length === 0
+    || !tabsById.has(value.tabId)
+  ) {
+    return null;
+  }
+
+  return {
+    kind: value.kind,
+    tabId: value.tabId,
+    url: value.url,
+  };
+}
+
 function normalizePersistedDocBrowserState(value: unknown): DocBrowserState | null {
   if (!isRecord(value)) {
     return null;
@@ -88,12 +119,30 @@ function normalizePersistedDocBrowserState(value: unknown): DocBrowserState | nu
   const activeTabId = tabs.some((tab) => tab.id === persistedActiveTabId)
     ? persistedActiveTabId ?? tabs[0].id
     : tabs[0].id;
+  const tabsById = new Map(tabs.map((tab) => [tab.id, tab]));
+  const activeHistory = Array.isArray(value.activeHistory)
+    ? value.activeHistory
+      .map((entry) => normalizePersistedActiveHistoryEntry(entry, tabsById))
+      .filter((entry): entry is DocBrowserActiveHistoryEntry => entry !== null)
+    : [];
+  const fallbackHistory = [createActiveHistoryEntryFromTab(tabsById.get(activeTabId) ?? tabs[0])];
+  const resolvedActiveHistory = activeHistory.length > 0 ? activeHistory : fallbackHistory;
+  const activeHistoryIndex = normalizePersistedNumber(
+    value.activeHistoryIndex,
+    0,
+    resolvedActiveHistory.length - 1,
+    resolvedActiveHistory.length - 1,
+  );
+  const activeHistoryEntry = resolvedActiveHistory[activeHistoryIndex];
+  const resolvedActiveTabId = tabsById.has(activeHistoryEntry.tabId) ? activeHistoryEntry.tabId : activeTabId;
 
   return {
     isOpen: value.isOpen === true,
     mode: isDocBrowserMode(value.mode) ? value.mode : 'docked',
     tabs,
-    activeTabId,
+    activeTabId: resolvedActiveTabId,
+    activeHistory: resolvedActiveHistory,
+    activeHistoryIndex,
   };
 }
 
@@ -122,6 +171,8 @@ export const useDocBrowserStore = create<DocBrowserStore>()(
           mode: state.snapshot.mode,
           tabs: state.snapshot.tabs.slice(-DOC_BROWSER_MAX_PERSISTED_TABS),
           activeTabId: state.snapshot.activeTabId,
+          activeHistory: state.snapshot.activeHistory,
+          activeHistoryIndex: state.snapshot.activeHistoryIndex,
         },
       }),
       merge: (persistedState, currentState) => {