@nextclaw/ui 0.20.2 → 0.20.3

package/src/features/cron/hooks/__tests__/use-cron-job-actions.test.tsx

@@ -0,0 +1,95 @@
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { CronJobView } from "@/shared/lib/api";
+import { setLanguage } from "@/shared/lib/i18n";
+import { useCronJobActions } from "@/features/cron/hooks/use-cron-job-actions";
+
+const mocks = vi.hoisted(() => ({
+  confirm: vi.fn(),
+  deleteJob: vi.fn(),
+  runJob: vi.fn(),
+  toggleJob: vi.fn(),
+}));
+
+vi.mock("@/features/cron/hooks/use-cron-jobs", () => ({
+  useDeleteCronJob: () => ({ mutateAsync: mocks.deleteJob }),
+  useRunCronJob: () => ({ mutateAsync: mocks.runJob }),
+  useToggleCronJob: () => ({ mutateAsync: mocks.toggleJob }),
+}));
+
+vi.mock("@/shared/hooks/use-confirm-dialog", () => ({
+  useConfirmDialog: () => ({
+    confirm: mocks.confirm,
+    ConfirmDialog: () => null,
+  }),
+}));
+
+function createJob(overrides: Partial<CronJobView> = {}): CronJobView {
+  return {
+    id: "paint-daily",
+    name: "每日绘画",
+    enabled: true,
+    schedule: { kind: "cron", expr: "0 9 * * *", tz: "Asia/Shanghai" },
+    payload: {
+      kind: "agent_turn",
+      message: "生成一张今日绘画。",
+      agentId: "main",
+      sessionId: "session:paint",
+    },
+    state: {
+      nextRunAt: "2026-08-27T01:00:00.000Z",
+      lastRunAt: null,
+      lastStatus: null,
+      lastError: null,
+    },
+    createdAt: "2026-08-26T01:00:00.000Z",
+    updatedAt: "2026-08-26T01:00:00.000Z",
+    deleteAfterRun: false,
+    ...overrides,
+  };
+}
+
+describe("useCronJobActions", () => {
+  beforeEach(() => {
+    setLanguage("zh");
+    vi.clearAllMocks();
+    mocks.confirm.mockResolvedValue(true);
+    mocks.deleteJob.mockResolvedValue({ deleted: true });
+    mocks.runJob.mockResolvedValue({ job: createJob(), executed: true });
+    mocks.toggleJob.mockResolvedValue({ job: createJob() });
+  });
+
+  it("requires confirmation and forces a paused task to run without enabling it", async () => {
+    const { result } = renderHook(() => useCronJobActions());
+    const job = createJob({ enabled: false });
+
+    await act(async () => {
+      await result.current.runJob(job);
+    });
+
+    expect(mocks.confirm).toHaveBeenCalledWith({
+      title: "任务已暂停，仍要立即执行?",
+      description: "每日绘画 (paint-daily)",
+      confirmLabel: "立即执行",
+    });
+    expect(mocks.runJob).toHaveBeenCalledWith({ id: "paint-daily", force: true });
+    expect(mocks.toggleJob).not.toHaveBeenCalled();
+  });
+
+  it("uses a destructive confirmation before deleting", async () => {
+    const { result } = renderHook(() => useCronJobActions());
+
+    await act(async () => {
+      await result.current.deleteJob(createJob());
+    });
+
+    expect(mocks.confirm).toHaveBeenCalledWith({
+      title: "确认删除定时任务?",
+      description: "每日绘画 (paint-daily)",
+      confirmLabel: "删除",
+      variant: "destructive",
+    });
+    expect(mocks.deleteJob).toHaveBeenCalledWith({ id: "paint-daily" });
+  });
+});

package/src/features/cron/hooks/use-cron-job-actions.ts

@@ -0,0 +1,109 @@
+import { useState } from "react";
+
+import type { CronJobView } from "@/shared/lib/api";
+import { useConfirmDialog } from "@/shared/hooks/use-confirm-dialog";
+import { t } from "@/shared/lib/i18n";
+import {
+  useDeleteCronJob,
+  useRunCronJob,
+  useToggleCronJob,
+} from "./use-cron-jobs";
+
+type AfterSuccess = () => void;
+
+function describeJob(job: CronJobView): string {
+  return job.name ? `${job.name} (${job.id})` : job.id;
+}
+
+export function useCronJobActions() {
+  const deleteCronJob = useDeleteCronJob();
+  const runCronJob = useRunCronJob();
+  const toggleCronJob = useToggleCronJob();
+  const { confirm, ConfirmDialog } = useConfirmDialog();
+  const [pendingJobIds, setPendingJobIds] = useState<ReadonlySet<string>>(
+    new Set(),
+  );
+
+  const execute = async (
+    job: CronJobView,
+    action: () => Promise<unknown>,
+    afterSuccess?: AfterSuccess,
+  ): Promise<boolean> => {
+    setPendingJobIds((ids) => new Set(ids).add(job.id));
+    try {
+      await action();
+      afterSuccess?.();
+      return true;
+    } catch {
+      return false;
+    } finally {
+      setPendingJobIds((ids) => {
+        const nextIds = new Set(ids);
+        nextIds.delete(job.id);
+        return nextIds;
+      });
+    }
+  };
+
+  const deleteJob = async (
+    job: CronJobView,
+    afterSuccess?: AfterSuccess,
+  ): Promise<boolean> => {
+    const confirmed = await confirm({
+      title: `${t("cronDeleteConfirm")}?`,
+      description: describeJob(job),
+      confirmLabel: t("delete"),
+      variant: "destructive",
+    });
+    if (!confirmed) {
+      return false;
+    }
+    return await execute(
+      job,
+      () => deleteCronJob.mutateAsync({ id: job.id }),
+      afterSuccess,
+    );
+  };
+
+  const runJob = async (
+    job: CronJobView,
+    afterSuccess?: AfterSuccess,
+  ): Promise<boolean> => {
+    const force = !job.enabled;
+    if (force) {
+      const confirmed = await confirm({
+        title: `${t("cronRunForceConfirm")}?`,
+        description: describeJob(job),
+        confirmLabel: t("cronRunNow"),
+      });
+      if (!confirmed) {
+        return false;
+      }
+    }
+    return await execute(
+      job,
+      () => runCronJob.mutateAsync({ id: job.id, force }),
+      afterSuccess,
+    );
+  };
+
+  const toggleJob = async (
+    job: CronJobView,
+    enabled: boolean,
+    afterSuccess?: AfterSuccess,
+  ): Promise<boolean> => {
+    return await execute(
+      job,
+      () => toggleCronJob.mutateAsync({ id: job.id, enabled }),
+      afterSuccess,
+    );
+  };
+
+  return {
+    ConfirmDialog,
+    deleteJob,
+    isPending: (job: CronJobView) => pendingJobIds.has(job.id),
+    runJob,
+    toggleJob,
+  };
+}

package/src/features/cron/index.ts

@@ -1,4 +1,6 @@
 export { CronConfig } from "./components/cron-config";
+export { CronJobDetailDialog } from "./components/cron-job-detail-dialog";
+export { useCronJobActions } from "./hooks/use-cron-job-actions";
 export {
   useCronJobs,
   useDeleteCronJob,

package/src/features/inbox/pages/inbox-page.tsx

@@ -12,6 +12,7 @@ import { Button } from "@/shared/components/ui/button";
 import { useConfirmDialog } from "@/shared/hooks/use-confirm-dialog";
 import { formatDateShort, formatDateTime, t } from "@/shared/lib/i18n";
 import { cn } from "@/shared/lib/utils";
+import { useScrollRestoration } from "@/shared/hooks/use-scroll-restoration";
 
 type InboxFilter = "unread" | "all" | "archived";
 
@@ -64,6 +65,10 @@ function InboxListPane({
   filter: InboxFilter;
   onFilterChange: (filter: InboxFilter) => void;
 }) {
+  const scrollRestoration = useScrollRestoration<HTMLDivElement>({
+    restorationKey: "inbox:list",
+  });
+  const { onScroll, scrollRef } = scrollRestoration;
   const filterItems: Array<{ id: InboxFilter; label: string; count: number }> = [
     {
       id: "unread",
@@ -100,7 +105,11 @@ function InboxListPane({
           </button>
         ))}
       </div>
-      <div className="custom-scrollbar min-h-0 flex-1 overflow-y-auto p-2">
+      <div
+        ref={scrollRef}
+        onScroll={onScroll}
+        className="custom-scrollbar min-h-0 flex-1 overflow-y-auto p-2"
+      >
         {filteredDeliveries.length > 0 ? (
           <ul className="space-y-0.5">
             {filteredDeliveries.map((delivery) => (
@@ -166,6 +175,10 @@ function InboxDetailPane({
   onDelete: () => void;
   onReadToggle: () => void;
 }) {
+  const scrollRestoration = useScrollRestoration<HTMLDivElement>({
+    restorationKey: delivery ? `inbox:delivery:${delivery.id}` : null,
+  });
+  const { onScroll, scrollRef } = scrollRestoration;
   if (!delivery) {
     return <main className="flex min-h-0 flex-col"><InboxEmptyState selection /></main>;
   }
@@ -204,7 +217,10 @@ function InboxDetailPane({
         isHtml
           ? "p-3 sm:p-4"
           : "custom-scrollbar overflow-y-auto px-5 py-5 sm:px-6 sm:py-6",
-      )}>
+      )}
+      ref={scrollRef}
+      onScroll={onScroll}
+      >
         <div className={cn("mx-auto max-w-5xl", isHtml && "h-full")}>
           <InboxDeliveryContent
             className={isHtml ? "h-full" : undefined}

package/src/features/marketplace/components/marketplace-page.tsx

@@ -30,6 +30,7 @@ import { PageLayout } from "@/app/components/layout/page-layout";
 import { useEffect, useMemo, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
 import { useInfiniteScrollLoader } from "@/shared/hooks/use-infinite-scroll-loader";
+import { useScrollRestoration } from "@/shared/hooks/use-scroll-restoration";
 import { Tabs, TabsList, TabsTrigger } from "@/shared/components/ui/tabs";
 
 const PAGE_SIZE = 20;
@@ -95,6 +96,11 @@ export function MarketplacePage({
     onLoadMore: () => itemsQuery.fetchNextPage(),
     watchValue: `${typeFilter}:${scope}:${query}:${sceneParam ?? ""}:${sort}:${itemsQuery.data?.loadedItems ?? 0}:${itemsQuery.data?.loadedPages ?? 0}`,
   });
+  const scrollRestoration = useScrollRestoration({
+    restorationKey: `marketplace:${forcedType ?? "all"}`,
+    scrollRef: listContainerRef,
+  });
+  const { onScroll: onScrollPositionSave } = scrollRestoration;
 
   useEffect(() => {
     const container = listContainerRef.current;
@@ -177,6 +183,7 @@ export function MarketplacePage({
       <section className="flex min-h-0 flex-1 flex-col">
         <div
           ref={listContainerRef}
+          onScroll={onScrollPositionSave}
           className="min-h-0 flex-1 overflow-y-auto custom-scrollbar pr-1"
           aria-busy={listModel.showListSkeleton || itemsQuery.isFetchingNextPage}
         >

package/src/features/panel-apps/pages/panel-app-main-page.tsx

@@ -12,6 +12,7 @@ import {
 } from "@/features/panel-apps/utils/panel-app-iframe.utils";
 import { openApps } from "@/features/panel-apps/utils/panel-app-doc-browser.utils";
 import { useDocBrowser } from "@/shared/components/doc-browser";
+import { usePanelAppScrollRestoration } from "@/shared/hooks/use-panel-app-scroll-restoration";
 import { t } from "@/shared/lib/i18n";
 
 export function PanelAppMainPage() {
@@ -25,6 +26,12 @@ export function PanelAppMainPage() {
     [appId, panelApps.data?.entries],
   );
   const runtime = usePanelAppMainRuntime(entry);
+  const restoreScroll = usePanelAppScrollRestoration({
+    currentUrl: entry?.contentPath ?? null,
+    iframeRef,
+    isEnabled: Boolean(entry),
+    restorationKey: entry ? `panel-app:main:${entry.appId}` : null,
+  });
 
   useEffect(() => {
     const handleMessage = (event: MessageEvent) => {
@@ -88,6 +95,7 @@ export function PanelAppMainPage() {
         title={entry.title}
         sandbox={PANEL_APP_IFRAME_SANDBOX}
         className="block h-full w-full border-0 bg-background"
+        onLoad={restoreScroll}
         onPointerOver={(event) => focusPanelAppIframe(event.currentTarget)}
       />
     </div>

package/src/platforms/desktop/components/desktop-app-shell.tsx

@@ -14,6 +14,7 @@ import type { DocBrowserTabMenuGroupsResolver } from "@/shared/components/doc-br
 import { cn } from "@/shared/lib/utils";
 import { useViewportLayoutStore } from "@/app/stores/viewport-layout.store";
 import { SIDEBAR_RAIL_WIDTH_PX } from "@/app/components/layout/sidebar-rail.styles";
+import { useScrollRestoration } from "@/shared/hooks/use-scroll-restoration";
 
 const DocBrowser = lazy(async () => ({
   default: (await import("@/shared/components/doc-browser/doc-browser"))
@@ -55,6 +56,10 @@ export function DesktopAppShell({
     : isMainRoute
       ? "280px"
       : "240px";
+  const settingsScroll = useScrollRestoration<HTMLElement>({
+    restorationKey: isMainRoute ? null : `settings-page:${pathname}`,
+  });
+  const { onScroll: onSettingsScroll, scrollRef: settingsScrollRef } = settingsScroll;
 
   return (
     <div
@@ -82,7 +87,11 @@ export function DesktopAppShell({
             {isMainRoute ? (
               <div className="flex-1 h-full overflow-hidden">{children}</div>
             ) : (
-              <main className="flex-1 overflow-auto p-8 pb-16 custom-scrollbar">
+              <main
+                ref={settingsScrollRef}
+                onScroll={onSettingsScroll}
+                className="flex-1 overflow-auto p-8 pb-16 custom-scrollbar"
+              >
                 <div className="mx-auto h-full max-w-6xl animate-fade-in">
                   {children}
                 </div>

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

@@ -215,7 +215,6 @@ export function DocBrowser({
     currentTab,
     iframeRef,
     isEnabled: supportsScrollRestoration,
-    tabs,
   });
   const { handleUrlSubmit, setUrlInput, urlInput } = useDocBrowserAddressBar({
     activeTabId,

package/src/shared/components/doc-browser/hooks/use-doc-browser-scroll-restoration.ts

@@ -1,126 +1,22 @@
-import { useCallback, useEffect, useRef, type RefObject } from 'react';
-import { PANEL_APP_SCROLL_RESTORATION_CONTRACT } from '@nextclaw/shared';
+import type { RefObject } from 'react';
 import type { DocBrowserTab } from '@/shared/components/doc-browser/doc-browser-context';
-
-type ScrollTarget =
-  | { kind: 'document' }
-  | { kind: 'element'; path: Array<{ index: number; tagName: string }> };
-
-type ScrollPosition = {
-  currentUrl: string;
-  target: ScrollTarget;
-  x: number;
-  y: number;
-};
+import { usePanelAppScrollRestoration } from '@/shared/hooks/use-panel-app-scroll-restoration';
 
 type UseDocBrowserScrollRestorationParams = {
   currentTab?: DocBrowserTab;
-  iframeRef: RefObject<HTMLIFrameElement | null>;
+  iframeRef: RefObject<HTMLIFrameElement>;
   isEnabled: boolean;
-  tabs: DocBrowserTab[];
 };
 
-function isScrollTarget(value: unknown): value is ScrollTarget {
-  if (!value || typeof value !== 'object') {
-    return false;
-  }
-  const candidate = value as Partial<ScrollTarget>;
-  if (candidate.kind === 'document') {
-    return true;
-  }
-  return candidate.kind === 'element'
-    && Array.isArray(candidate.path)
-    && candidate.path.length > 0
-    && candidate.path.length <= 30
-    && candidate.path.every((segment) => (
-      typeof segment?.index === 'number'
-      && Number.isInteger(segment.index)
-      && segment.index >= 0
-      && segment.index <= 1000
-      && typeof segment.tagName === 'string'
-      && segment.tagName.length > 0
-      && segment.tagName.length <= 32
-    ));
-}
-
-function isScrollMessage(value: unknown): value is {
-  target: ScrollTarget;
-  type: string;
-  version: number;
-  x: number;
-  y: number;
-} {
-  if (!value || typeof value !== 'object') {
-    return false;
-  }
-  const candidate = value as Partial<{
-    target: unknown;
-    type: string;
-    version: number;
-    x: number;
-    y: number;
-  }>;
-  return candidate.type === PANEL_APP_SCROLL_RESTORATION_CONTRACT.scrollMessageType
-    && candidate.version === PANEL_APP_SCROLL_RESTORATION_CONTRACT.version
-    && isScrollTarget(candidate.target)
-    && typeof candidate.x === 'number'
-    && Number.isFinite(candidate.x)
-    && candidate.x >= 0
-    && typeof candidate.y === 'number'
-    && Number.isFinite(candidate.y)
-    && candidate.y >= 0;
-}
-
 export function useDocBrowserScrollRestoration({
   currentTab,
   iframeRef,
   isEnabled,
-  tabs,
 }: UseDocBrowserScrollRestorationParams) {
-  const positionsRef = useRef(new Map<string, ScrollPosition>());
-
-  useEffect(() => {
-    const activeTabIds = new Set(tabs.map((tab) => tab.id));
-    for (const tabId of positionsRef.current.keys()) {
-      if (!activeTabIds.has(tabId)) {
-        positionsRef.current.delete(tabId);
-      }
-    }
-  }, [tabs]);
-
-  useEffect(() => {
-    if (!currentTab || !isEnabled) {
-      return;
-    }
-    const onMessage = (event: MessageEvent) => {
-      if (event.source !== iframeRef.current?.contentWindow || !isScrollMessage(event.data)) {
-        return;
-      }
-      positionsRef.current.set(currentTab.id, {
-        currentUrl: currentTab.currentUrl,
-        target: event.data.target,
-        x: event.data.x,
-        y: event.data.y,
-      });
-    };
-    window.addEventListener('message', onMessage);
-    return () => window.removeEventListener('message', onMessage);
-  }, [currentTab, iframeRef, isEnabled]);
-
-  return useCallback(() => {
-    if (!currentTab || !isEnabled) {
-      return;
-    }
-    const position = positionsRef.current.get(currentTab.id);
-    if (!position || position.currentUrl !== currentTab.currentUrl) {
-      return;
-    }
-    iframeRef.current?.contentWindow?.postMessage({
-      type: PANEL_APP_SCROLL_RESTORATION_CONTRACT.restoreScrollMessageType,
-      version: PANEL_APP_SCROLL_RESTORATION_CONTRACT.version,
-      target: position.target,
-      x: position.x,
-      y: position.y,
-    }, '*');
-  }, [currentTab, iframeRef, isEnabled]);
+  return usePanelAppScrollRestoration({
+    currentUrl: currentTab?.currentUrl ?? null,
+    iframeRef,
+    isEnabled,
+    restorationKey: currentTab ? `panel-app:doc-browser:${currentTab.id}` : null,
+  });
 }

package/src/shared/hooks/use-panel-app-scroll-restoration.test.tsx

@@ -0,0 +1,66 @@
+import { fireEvent, render } from "@testing-library/react";
+import { useRef } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { PANEL_APP_SCROLL_RESTORATION_CONTRACT } from "@nextclaw/shared";
+import { usePanelAppScrollRestoration } from "@/shared/hooks/use-panel-app-scroll-restoration";
+import { scrollRestorationManager } from "@/shared/lib/navigation-history";
+
+function PanelAppFrame({ currentUrl = "/app", restorationKey = "panel-app:test" }: {
+  currentUrl?: string;
+  restorationKey?: string;
+}) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const restoreScroll = usePanelAppScrollRestoration({
+    currentUrl,
+    iframeRef,
+    isEnabled: true,
+    restorationKey,
+  });
+  return <iframe ref={iframeRef} data-testid="panel-app-frame" onLoad={restoreScroll} />;
+}
+
+describe("usePanelAppScrollRestoration", () => {
+  beforeEach(() => scrollRestorationManager.clear());
+
+  it("records only scroll messages from its iframe and restores them after load", () => {
+    const { getByTestId } = render(<PanelAppFrame />);
+    const iframe = getByTestId("panel-app-frame") as HTMLIFrameElement;
+    const postMessage = vi.spyOn(iframe.contentWindow!, "postMessage");
+    const target = { kind: "document" } as const;
+
+    window.dispatchEvent(new MessageEvent("message", {
+      data: {
+        type: PANEL_APP_SCROLL_RESTORATION_CONTRACT.scrollMessageType,
+        version: PANEL_APP_SCROLL_RESTORATION_CONTRACT.version,
+        target,
+        x: 8,
+        y: 64,
+      },
+      source: iframe.contentWindow,
+    }));
+    fireEvent.load(iframe);
+
+    expect(postMessage).toHaveBeenCalledWith({
+      type: PANEL_APP_SCROLL_RESTORATION_CONTRACT.restoreScrollMessageType,
+      version: PANEL_APP_SCROLL_RESTORATION_CONTRACT.version,
+      target,
+      x: 8,
+      y: 64,
+    }, "*");
+  });
+
+  it("does not restore a position from another resource URL", () => {
+    scrollRestorationManager.save("panel-app:test", {
+      x: 0,
+      y: 64,
+      payload: { currentUrl: "/old-app", target: { kind: "document" } },
+    });
+    const { getByTestId } = render(<PanelAppFrame currentUrl="/new-app" />);
+    const iframe = getByTestId("panel-app-frame") as HTMLIFrameElement;
+    const postMessage = vi.spyOn(iframe.contentWindow!, "postMessage");
+
+    fireEvent.load(iframe);
+
+    expect(postMessage).not.toHaveBeenCalled();
+  });
+});

package/src/shared/hooks/use-panel-app-scroll-restoration.ts

@@ -0,0 +1,107 @@
+import { useCallback, useEffect, type RefObject } from "react";
+import { PANEL_APP_SCROLL_RESTORATION_CONTRACT } from "@nextclaw/shared";
+import { scrollRestorationManager } from "@/shared/lib/navigation-history";
+
+type ScrollTarget =
+  | { kind: "document" }
+  | { kind: "element"; path: Array<{ index: number; tagName: string }> };
+
+type PanelAppScrollSnapshot = {
+  currentUrl: string;
+  target: ScrollTarget;
+};
+
+type UsePanelAppScrollRestorationParams = {
+  currentUrl: string | null;
+  iframeRef: RefObject<HTMLIFrameElement>;
+  isEnabled: boolean;
+  restorationKey: string | null;
+};
+
+function isScrollTarget(value: unknown): value is ScrollTarget {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<ScrollTarget>;
+  if (candidate.kind === "document") return true;
+  return candidate.kind === "element"
+    && Array.isArray(candidate.path)
+    && candidate.path.length > 0
+    && candidate.path.length <= 30
+    && candidate.path.every((segment) => (
+      typeof segment?.index === "number"
+      && Number.isInteger(segment.index)
+      && segment.index >= 0
+      && segment.index <= 1000
+      && typeof segment.tagName === "string"
+      && segment.tagName.length > 0
+      && segment.tagName.length <= 32
+    ));
+}
+
+function isPanelAppScrollSnapshot(value: unknown): value is PanelAppScrollSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<PanelAppScrollSnapshot>;
+  return typeof candidate.currentUrl === "string" && isScrollTarget(candidate.target);
+}
+
+function isScrollMessage(value: unknown): value is {
+  target: ScrollTarget;
+  x: number;
+  y: number;
+} {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<{
+    target: unknown;
+    type: string;
+    version: number;
+    x: number;
+    y: number;
+  }>;
+  return candidate.type === PANEL_APP_SCROLL_RESTORATION_CONTRACT.scrollMessageType
+    && candidate.version === PANEL_APP_SCROLL_RESTORATION_CONTRACT.version
+    && isScrollTarget(candidate.target)
+    && typeof candidate.x === "number"
+    && Number.isFinite(candidate.x)
+    && candidate.x >= 0
+    && typeof candidate.y === "number"
+    && Number.isFinite(candidate.y)
+    && candidate.y >= 0;
+}
+
+/** Bridges the Panel App iframe scroll protocol to the shared navigation history. */
+export function usePanelAppScrollRestoration({
+  currentUrl,
+  iframeRef,
+  isEnabled,
+  restorationKey,
+}: UsePanelAppScrollRestorationParams) {
+  useEffect(() => {
+    if (!currentUrl || !isEnabled || !restorationKey) return;
+    const onMessage = (event: MessageEvent) => {
+      if (event.source !== iframeRef.current?.contentWindow || !isScrollMessage(event.data)) {
+        return;
+      }
+      scrollRestorationManager.save(restorationKey, {
+        x: event.data.x,
+        y: event.data.y,
+        payload: { currentUrl, target: event.data.target } satisfies PanelAppScrollSnapshot,
+      });
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [currentUrl, iframeRef, isEnabled, restorationKey]);
+
+  return useCallback(() => {
+    if (!currentUrl || !isEnabled || !restorationKey) return;
+    const position = scrollRestorationManager.read(restorationKey);
+    if (!position || !isPanelAppScrollSnapshot(position.payload) || position.payload.currentUrl !== currentUrl) {
+      return;
+    }
+    iframeRef.current?.contentWindow?.postMessage({
+      type: PANEL_APP_SCROLL_RESTORATION_CONTRACT.restoreScrollMessageType,
+      version: PANEL_APP_SCROLL_RESTORATION_CONTRACT.version,
+      target: position.payload.target,
+      x: position.x,
+      y: position.y,
+    }, "*");
+  }, [currentUrl, iframeRef, isEnabled, restorationKey]);
+}