@byline/host-tanstack-start 4.17.0 → 4.19.0

package/dist/server-fns/collections/restore-version.js

@@ -3,6 +3,7 @@ import { getAdminRequestContext } from "@byline/client/server";
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from "@byline/core";
 import { restoreDocumentVersion } from "@byline/core/services";
 import { ensureCollection } from "../../integrations/api-utils.js";
+import { toCommittedDocumentHookFailureResponse } from "./save-outcome.js";
 const restore_version_restoreDocumentVersion = createServerFn({
     method: 'POST'
 }).validator((input)=>input).handler(async ({ data: input })=>{
@@ -27,15 +28,21 @@ const restore_version_restoreDocumentVersion = createServerFn({
         slugifier: serverConfig.slugifier,
         requestContext: await getAdminRequestContext()
     };
-    const result = await restoreDocumentVersion(ctx, {
-        documentId: id,
-        sourceVersionId: versionId
-    });
-    return {
-        status: 'ok',
-        documentId: result.documentId,
-        documentVersionId: result.documentVersionId,
-        sourceVersionId: result.sourceVersionId
-    };
+    try {
+        const result = await restoreDocumentVersion(ctx, {
+            documentId: id,
+            sourceVersionId: versionId
+        });
+        return {
+            status: 'ok',
+            documentId: result.documentId,
+            documentVersionId: result.documentVersionId,
+            sourceVersionId: result.sourceVersionId
+        };
+    } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error);
+        if (null != committedFailure) return committedFailure;
+        throw error;
+    }
 });
 export { restore_version_restoreDocumentVersion as restoreDocumentVersion };

package/dist/server-fns/collections/save-outcome.d.ts

@@ -0,0 +1,23 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { type DocumentHookCommittedPhase, type DocumentHookSideEffectCode } from '@byline/core/services';
+export interface CollectionDocumentCommittedHookFailureResponse {
+    status: 'committed-hook-failed';
+    documentId: string;
+    documentVersionId: string;
+    sideEffectFailure: {
+        phase: DocumentHookCommittedPhase;
+        code: DocumentHookSideEffectCode;
+    };
+}
+/**
+ * Convert only validated core committed-hook errors into safe wire data. Raw
+ * hook errors, messages, stack traces, and storage paths remain server-side.
+ */
+export declare function toCommittedDocumentHookFailureResponse(error: unknown): CollectionDocumentCommittedHookFailureResponse | null;
+export declare function hasCommittedDocumentHookFailure(result: unknown): result is CollectionDocumentCommittedHookFailureResponse;

package/dist/server-fns/collections/save-outcome.js

@@ -0,0 +1,18 @@
+import { getDocumentHookCommittedDetails } from "@byline/core/services";
+function toCommittedDocumentHookFailureResponse(error) {
+    const details = getDocumentHookCommittedDetails(error);
+    if (null == details) return null;
+    return {
+        status: 'committed-hook-failed',
+        documentId: details.documentId,
+        documentVersionId: details.documentVersionId,
+        sideEffectFailure: {
+            phase: details.phase,
+            code: details.sideEffectCode
+        }
+    };
+}
+function hasCommittedDocumentHookFailure(result) {
+    return 'object' == typeof result && null != result && 'status' in result && 'committed-hook-failed' === result.status;
+}
+export { hasCommittedDocumentHookFailure, toCommittedDocumentHookFailureResponse };

package/dist/server-fns/collections/update.d.ts

@@ -18,8 +18,10 @@ export declare const updateCollectionDocumentWithPatches: import("@tanstack/reac
     patches: DocumentPatch[];
     versionId?: string;
     locale?: string;
-}, Promise<{
+}, Promise<import("./save-outcome.js").CollectionDocumentCommittedHookFailureResponse | {
     status: 'ok';
+    documentId: string;
+    documentVersionId: string;
 }>>;
 export declare const updateCollectionDocumentSystemFields: import("@tanstack/react-start").RequiredFetcher<undefined, (input: {
     collection: string;

package/dist/server-fns/collections/update.js

@@ -3,6 +3,7 @@ import { getAdminRequestContext } from "@byline/client/server";
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from "@byline/core";
 import { updateDocumentSystemFields, updateDocumentWithPatches } from "@byline/core/services";
 import { ensureCollection } from "../../integrations/api-utils.js";
+import { toCommittedDocumentHookFailureResponse } from "./save-outcome.js";
 const updateCollectionDocumentWithPatches = createServerFn({
     method: 'POST'
 }).validator((input)=>input).handler(async ({ data: input })=>{
@@ -27,14 +28,23 @@ const updateCollectionDocumentWithPatches = createServerFn({
         slugifier: serverConfig.slugifier,
         requestContext: await getAdminRequestContext()
     };
-    await updateDocumentWithPatches(ctx, {
-        documentId: id,
-        patches,
-        documentVersionId: versionId,
-        locale: locale ?? serverConfig.i18n.content.defaultLocale
-    });
+    let result;
+    try {
+        result = await updateDocumentWithPatches(ctx, {
+            documentId: id,
+            patches,
+            documentVersionId: versionId,
+            locale: locale ?? serverConfig.i18n.content.defaultLocale
+        });
+    } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error);
+        if (null != committedFailure) return committedFailure;
+        throw error;
+    }
     return {
-        status: 'ok'
+        status: 'ok',
+        documentId: result.documentId,
+        documentVersionId: result.documentVersionId
     };
 });
 const updateCollectionDocumentSystemFields = createServerFn({

package/dist/server-fns/singletons/copy-to-locale.js

@@ -1,11 +1,20 @@
 import { createServerFn } from "@tanstack/react-start";
 import { getAdminBylineClient } from "@byline/client/server";
+import { toCommittedDocumentHookFailureResponse } from "../collections/save-outcome.js";
 import { serialise } from "../serialise.js";
 const copySingletonToLocale = createServerFn({
     method: 'POST'
-}).validator((input)=>input).handler(async ({ data })=>serialise(await getAdminBylineClient().singleton(data.singleton).copyToLocale({
-        sourceLocale: data.sourceLocale,
-        targetLocale: data.targetLocale,
-        overwrite: data.overwrite
-    })));
+}).validator((input)=>input).handler(async ({ data })=>{
+    try {
+        return serialise(await getAdminBylineClient().singleton(data.singleton).copyToLocale({
+            sourceLocale: data.sourceLocale,
+            targetLocale: data.targetLocale,
+            overwrite: data.overwrite
+        }));
+    } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error);
+        if (null != committedFailure) return committedFailure;
+        throw error;
+    }
+});
 export { copySingletonToLocale };

package/dist/server-fns/singletons/restore-version.js

@@ -1,7 +1,16 @@
 import { createServerFn } from "@tanstack/react-start";
 import { getAdminBylineClient } from "@byline/client/server";
+import { toCommittedDocumentHookFailureResponse } from "../collections/save-outcome.js";
 import { serialise } from "../serialise.js";
 const restoreSingletonVersion = createServerFn({
     method: 'POST'
-}).validator((input)=>input).handler(async ({ data })=>serialise(await getAdminBylineClient().singleton(data.singleton).restoreVersion(data.versionId)));
+}).validator((input)=>input).handler(async ({ data })=>{
+    try {
+        return serialise(await getAdminBylineClient().singleton(data.singleton).restoreVersion(data.versionId));
+    } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error);
+        if (null != committedFailure) return committedFailure;
+        throw error;
+    }
+});
 export { restoreSingletonVersion };

package/dist/server-fns/singletons/update.js

@@ -1,14 +1,21 @@
 import { createServerFn } from "@tanstack/react-start";
 import { getAdminBylineClient } from "@byline/client/server";
+import { toCommittedDocumentHookFailureResponse } from "../collections/save-outcome.js";
 import { serialise } from "../serialise.js";
 const updateSingleton = createServerFn({
     method: 'POST'
 }).validator((input)=>input).handler(async ({ data })=>{
     const { singleton, data: fields, locale, expectedVersionId } = data;
-    const result = await getAdminBylineClient().singleton(singleton).update(fields, {
-        locale,
-        expectedVersionId
-    });
-    return serialise(result);
+    try {
+        const result = await getAdminBylineClient().singleton(singleton).update(fields, {
+            locale,
+            expectedVersionId
+        });
+        return serialise(result);
+    } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error);
+        if (null != committedFailure) return committedFailure;
+        throw error;
+    }
 });
 export { updateSingleton };

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "4.17.0",
+  "version": "4.19.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -125,15 +125,15 @@
     "react-json-view-lite": "^2.5.0",
     "react-swipeable": "^7.0.2",
     "zod": "^4.4.3",
-    "@byline/analytics": "4.17.0",
-    "@byline/ai": "4.17.0",
-    "@byline/auth": "4.17.0",
-    "@byline/analytics-agent": "4.17.0",
-    "@byline/i18n": "4.17.0",
-    "@byline/admin": "4.17.0",
-    "@byline/core": "4.17.0",
-    "@byline/ui": "4.17.0",
-    "@byline/client": "4.17.0"
+    "@byline/admin": "4.19.0",
+    "@byline/analytics": "4.19.0",
+    "@byline/analytics-agent": "4.19.0",
+    "@byline/ai": "4.19.0",
+    "@byline/core": "4.19.0",
+    "@byline/client": "4.19.0",
+    "@byline/auth": "4.19.0",
+    "@byline/i18n": "4.19.0",
+    "@byline/ui": "4.19.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.167.0",

package/src/admin-shell/chrome/router-pager.tsx

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+import { useCallback } from 'react'
 import { useRouterState } from '@tanstack/react-router'
 
 import type { PaginationProps } from '@byline/ui/react'
@@ -18,6 +19,7 @@ import {
 } from '@byline/ui/react'
 
 import { Link } from './loose-router.js'
+import { scrollWindowToTop } from './scroll-to-top.js'
 
 interface RouterPageProps extends PaginationProps {
   smoothScrollToTop?: boolean
@@ -27,6 +29,13 @@ interface RouterPageProps extends PaginationProps {
  * A convenience pager wrapped around uikit's Pagination with `asChild`
  * targets that delegate to TanStack Router's `<Link>`. `asChild` merges
  * the existing button styles into the rendered Link.
+ *
+ * `smoothScrollToTop` is for a pager sitting *below* a long list: turning a
+ * page there should carry the reader back to the top rather than leaving them
+ * at the foot of a fresh page. It suppresses the router's own instant
+ * `resetScroll` and animates instead — so the component owes an actual
+ * scroll, which was the missing half: the flag disabled the reset and put
+ * nothing in its place, so a bottom pager did not scroll at all.
  */
 export function RouterPager({
   className,
@@ -36,6 +45,14 @@ export function RouterPager({
 }: RouterPageProps): React.JSX.Element {
   const location = useRouterState({ select: (s) => s.location })
 
+  // Fires alongside navigation rather than after it: the scroll and the new
+  // page load run together, so the list is in place by the time the reader
+  // arrives at the top.
+  const handleScrollToTop = useCallback(() => {
+    if (smoothScrollToTop !== true) return
+    scrollWindowToTop()
+  }, [smoothScrollToTop])
+
   return (
     <Pagination variant="dashboard" {...rest}>
       <Pagination.Root className={className} ariaLabel={ariaLabel}>
@@ -51,6 +68,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />
@@ -76,6 +94,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />
@@ -103,6 +122,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />
@@ -130,6 +150,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />
@@ -156,6 +177,7 @@ export function RouterPager({
                   ) : (
                     <Link
                       resetScroll={smoothScrollToTop !== true}
+                      onClick={handleScrollToTop}
                       to={location.pathname as never}
                       search={params}
                     />

package/src/admin-shell/chrome/scroll-to-top.test.ts

@@ -0,0 +1,56 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { scrollWindowToTop } from './scroll-to-top.js'
+
+function mockReducedMotion(matches: boolean) {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn((query: string) => ({ matches, media: query })) as unknown as typeof window.matchMedia
+  )
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe('scrollWindowToTop', () => {
+  it('scrolls to the top of the page', () => {
+    const scrollTo = vi.fn()
+    vi.stubGlobal('scrollTo', scrollTo)
+    mockReducedMotion(false)
+
+    scrollWindowToTop()
+
+    expect(scrollTo).toHaveBeenCalledWith({ top: 0, behavior: 'smooth' })
+  })
+
+  it('skips the animation when the reader asks for reduced motion', () => {
+    const scrollTo = vi.fn()
+    vi.stubGlobal('scrollTo', scrollTo)
+    mockReducedMotion(true)
+
+    scrollWindowToTop()
+
+    // Still goes to the top — only the travel is dropped.
+    expect(scrollTo).toHaveBeenCalledWith({ top: 0, behavior: 'auto' })
+  })
+
+  /** Older browsers and some test environments have no `matchMedia`. */
+  it('still scrolls when matchMedia is unavailable', () => {
+    const scrollTo = vi.fn()
+    vi.stubGlobal('scrollTo', scrollTo)
+    vi.stubGlobal('matchMedia', undefined)
+
+    expect(() => scrollWindowToTop()).not.toThrow()
+    expect(scrollTo).toHaveBeenCalledWith({ top: 0, behavior: 'smooth' })
+  })
+})

package/src/admin-shell/chrome/scroll-to-top.ts

@@ -0,0 +1,28 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Return the reader to the top of the page.
+ *
+ * Separate from `RouterPager` so the behaviour can be asserted without
+ * mounting a router. `smoothScrollToTop` suppresses TanStack's instant
+ * `resetScroll` in favour of an animated one, which makes a missing
+ * implementation silent — the page simply does not move. That is what
+ * happened to every pager carrying the flag.
+ *
+ * Honours `prefers-reduced-motion`: those readers still arrive at the top,
+ * without the travel.
+ */
+export function scrollWindowToTop(): void {
+  if (typeof window === 'undefined') return
+
+  // `matchMedia` is absent in some test and server-ish environments; treating
+  // that as "no preference expressed" keeps the scroll working either way.
+  const prefersReducedMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+  window.scrollTo({ top: 0, behavior: prefersReducedMotion === true ? 'auto' : 'smooth' })
+}

package/src/admin-shell/collections/create.tsx

@@ -15,7 +15,10 @@ import { Container, Section, useToastManager } from '@byline/ui/react'
 
 import { getAdminRoutePath } from '../../routes/admin-path.js'
 import { decodeListReturnState } from '../../routes/list-return-state.js'
-import { createCollectionDocument } from '../../server-fns/collections/index.js'
+import {
+  createCollectionDocument,
+  hasCommittedDocumentHookFailure,
+} from '../../server-fns/collections/index.js'
 import { useNavigate } from '../chrome/loose-router.js'
 import { useTanStackNavigationGuard } from './tanstack-navigation-guard.js'
 
@@ -65,6 +68,14 @@ export const CreateView = ({
           ...(systemAvailableLocales ? { availableLocales: systemAvailableLocales } : {}),
         },
       })
+      const hookFailed = hasCommittedDocumentHookFailure(result)
+      if (hookFailed) {
+        toastManager.add({
+          title: t('collections.save.hookFailedToast'),
+          description: t('collections.save.hookFailedDescription'),
+          data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+        })
+      }
       // Create → edit: land the editor on the new document, where the rest
       // of the work (content, status, relations) happens. `from` threads
       // forward so closing the brand-new document also returns to the
@@ -75,13 +86,21 @@ export const CreateView = ({
         navigate({
           to: getAdminRoutePath('collections', '$collection', '$id'),
           params: { collection: path, id: result.documentId } as never,
-          search: { action: 'created', from },
+          search: { ...(hookFailed ? {} : { action: 'created' as const }), from },
+          // Persistence has succeeded, but FormRenderer cannot commit its
+          // clean baseline until this handler returns. Do not let that brief
+          // dirty-state overlap block the intentional create → edit redirect.
+          ignoreBlocker: true,
         })
       } else {
         navigate({
           to: getAdminRoutePath('collections', '$collection'),
           params: { collection: path },
-          search: { ...decodeListReturnState(from), action: 'created' },
+          search: {
+            ...decodeListReturnState(from),
+            ...(hookFailed ? {} : { action: 'created' as const }),
+          },
+          ignoreBlocker: true,
         })
       }
     } catch (err) {

package/src/admin-shell/collections/edit.tsx

@@ -29,6 +29,7 @@ import {
   deleteDocument,
   deleteDocumentLocale,
   duplicateCollectionDocument,
+  hasCommittedDocumentHookFailure,
   hasDeleteSideEffectFailures,
   scheduleCollectionDocumentPublish,
   unpublishDocument,
@@ -43,7 +44,7 @@ import type { SerializedDocumentPublishSchedule } from '../../server-fns/collect
 import type { ContentLocaleOption } from './view-menu.js'
 
 type EditState = {
-  status: 'success' | 'failed' | 'busy' | 'idle'
+  status: 'success' | 'warning' | 'failed' | 'busy' | 'idle'
   message: string
 }
 
@@ -110,6 +111,16 @@ export const EditView = ({
     })
   }
 
+  const notifyCommittedHookFailure = () => {
+    const description = t('collections.save.hookFailedDescription')
+    toastManager.add({
+      title: t('collections.save.hookFailedToast'),
+      description,
+      data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+    })
+    setEditState({ status: 'warning', message: description })
+  }
+
   const handleLocaleChange = (newLocale: string) => {
     navigate({
       to: getAdminRoutePath('collections', '$collection', '$id'),
@@ -306,6 +317,15 @@ export const EditView = ({
       const result = await duplicateCollectionDocument({
         data: { collection: path, id: String(initialData.id) },
       })
+      if (hasCommittedDocumentHookFailure(result)) {
+        notifyCommittedHookFailure()
+        navigate({
+          to: getAdminRoutePath('collections', '$collection', '$id'),
+          params: { collection: path, id: result.documentId },
+          search: (prev: Record<string, unknown>) => ({ ...prev }),
+        })
+        return
+      }
       const description = result.pathRetried
         ? t('collections.edit.duplicatedAutoPathDescription', { path: result.newPath })
         : t('collections.edit.duplicatedPathDescription', { path: result.newPath })
@@ -367,6 +387,16 @@ export const EditView = ({
           overwrite,
         },
       })
+      if (hasCommittedDocumentHookFailure(result)) {
+        notifyCommittedHookFailure()
+        notifyScheduleSuspended()
+        navigate({
+          to: getAdminRoutePath('collections', '$collection', '$id'),
+          params: { collection: path, id: String(initialData.id) },
+          search: (prev: Record<string, unknown>) => ({ ...prev, locale: targetLocale }),
+        })
+        return
+      }
       const sourceLabel =
         contentLocales.find((l) => l.code === result.sourceLocale)?.label ?? result.sourceLocale
       const targetLabel =
@@ -435,6 +465,16 @@ export const EditView = ({
           locale: targetLocale,
         },
       })
+      if (hasCommittedDocumentHookFailure(result)) {
+        notifyCommittedHookFailure()
+        notifyScheduleSuspended()
+        navigate({
+          to: getAdminRoutePath('collections', '$collection', '$id'),
+          params: { collection: path, id: String(initialData.id) },
+          search: (prev: Record<string, unknown>) => ({ ...prev, locale: defaultContentLocale }),
+        })
+        return
+      }
       const targetLabel =
         contentLocales.find((l) => l.code === result.locale)?.label ?? result.locale
       const description = t('collections.edit.deletedLocaleDescription', {
@@ -498,7 +538,10 @@ export const EditView = ({
           close: true,
         },
       })
-      setEditState({ status: 'success', message: description })
+      setEditState({
+        status: hasSideEffectFailures ? 'warning' : 'success',
+        message: description,
+      })
       // Navigate back to the collection list after deletion. The return
       // target has now been consumed — clear the stored fallback so a later
       // visit doesn't resurrect a stale list position.
@@ -550,6 +593,7 @@ export const EditView = ({
     systemAvailableLocales?: string[]
   }) => {
     try {
+      let hookFailed = false
       // Document-grain system fields write first via their own non-versioned
       // path — so a path conflict surfaces before we mint a content version,
       // and these immediate writes never reset workflow status. See
@@ -571,7 +615,7 @@ export const EditView = ({
       // fields changed, so a path/advertising edit never creates an empty
       // content version.
       if (contentDirty) {
-        await updateCollectionDocumentWithPatches({
+        const result = await updateCollectionDocumentWithPatches({
           data: {
             collection: path,
             id: String(initialData.id),
@@ -580,33 +624,42 @@ export const EditView = ({
             locale,
           },
         })
+        hookFailed = hasCommittedDocumentHookFailure(result)
       }
 
       if (contentDirty && scheduledPublication?.state === 'armed') {
         notifyScheduleSuspended()
       }
 
-      const description = t('collections.edit.updatedDescription', { label: singularLower })
+      const description = hookFailed
+        ? t('collections.save.hookFailedDescription')
+        : t('collections.edit.updatedDescription', { label: singularLower })
       toastManager.add({
-        title: t('collections.edit.updateTitle', { label: singular }),
+        title: hookFailed
+          ? t('collections.save.hookFailedToast')
+          : t('collections.edit.updateTitle', { label: singular }),
         description,
         data: {
-          intent: 'success',
-          iconType: 'success',
+          intent: hookFailed ? 'warning' : 'success',
+          iconType: hookFailed ? 'warning' : 'success',
           icon: true,
           close: true,
         },
       })
 
-      setEditState({ status: 'success', message: description })
+      setEditState({ status: hookFailed ? 'warning' : 'success', message: description })
 
       // Re-navigate to the same route so the loader re-fetches the document.
-      // The new version will have a fresh version ID, draft status, and
-      // updated publishedVersion metadata.
+      // The new version will have a fresh version ID, the collection's default
+      // workflow status, and updated publishedVersion metadata.
       navigate({
         to: getAdminRoutePath('collections', '$collection', '$id'),
         params: { collection: path, id: String(initialData.id) },
         search: (prev: Record<string, unknown>) => ({ ...prev }),
+        // Every write above has succeeded. FormRenderer clears its dirty
+        // baseline after this handler returns, so bypass the guard during the
+        // intentional post-save refresh rather than racing that state update.
+        ignoreBlocker: true,
       })
     } catch (err) {
       console.error('Network error:', err)

package/src/admin-shell/collections/restore-version-modal.tsx

@@ -19,9 +19,10 @@
 import { useState } from 'react'
 
 import { useTranslation } from '@byline/i18n/react'
-import { Alert, Button, LoaderEllipsis, Modal } from '@byline/ui/react'
+import { Alert, Button, LoaderEllipsis, Modal, useToastManager } from '@byline/ui/react'
 import cx from 'clsx'
 
+import { hasCommittedDocumentHookFailure } from '../../server-fns/collections/save-outcome.js'
 import styles from './restore-version-modal.module.css'
 
 interface RestoreVersionModalProps {
@@ -42,6 +43,7 @@ export function RestoreVersionModal({
   onRestoreComplete,
 }: RestoreVersionModalProps) {
   const { t } = useTranslation('byline-admin')
+  const toastManager = useToastManager()
   const [error, setError] = useState<string | null>(null)
   const [pending, setPending] = useState(false)
 
@@ -50,7 +52,14 @@ export function RestoreVersionModal({
     setPending(true)
     setError(null)
     try {
-      await restoreVersion()
+      const result = await restoreVersion()
+      if (hasCommittedDocumentHookFailure(result)) {
+        toastManager.add({
+          title: t('collections.save.hookFailedToast'),
+          description: t('collections.save.hookFailedDescription'),
+          data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+        })
+      }
       onClose()
       await onRestoreComplete()
     } catch (err) {