@elytracms/studio 0.0.43 → 0.0.45

package/dist/components/cms/use-publish-controller.d.ts

@@ -0,0 +1,49 @@
+import type { CmsDocument, CollectionDef, DocumentRef } from '@elytracms/core/cms-core';
+import type { CollectionViewSource } from '@elytracms/studio/lib/collection-view/collection-view-source';
+export type PublishState = 'idle' | 'pending' | 'success';
+/**
+ * EC-268 / 0.0.39 — the split Publish button's shared gate, computed once so the
+ * primary "Publish" and the "Publish & close" item can never diverge. A pure
+ * decision (directly testable): the Published perspective is read-only (switch to
+ * Draft to publish), schema errors block (with a count-aware hint), and an
+ * in-flight publish disables re-entry.
+ */
+export declare function publishGate(input: {
+    hasErrors: boolean;
+    viewReadOnly: boolean;
+    publishState: PublishState;
+    errorCount: number;
+}): {
+    disabled: boolean;
+    title: string | undefined;
+};
+export interface PublishController {
+    publishState: PublishState;
+    /** Is the confirm-through dialog (unpublished hard refs) open? */
+    publishConfirm: boolean;
+    /** Publish (opening the confirm-through dialog first if there are unpublished refs). */
+    handlePublish: () => void;
+    /** Publish and, on success, return to the rail's list (0.0.39 "Publish & close"). */
+    handlePublishAndClose: () => void;
+    /** Confirm-through: publish despite the unpublished hard references. */
+    confirmPublish: () => void;
+    /** Dismiss the confirm-through dialog (also clears a pending "& close" intent). */
+    cancelPublishConfirm: () => void;
+}
+/**
+ * EC-268 / EC-300 / 0.0.39 — the publish controller. Owns the publish indicator
+ * state, the EC-300 confirm-through guard (unpublished hard references would render
+ * empty on the live site, so publishing confirms rather than blocks), and the
+ * 0.0.39 "Publish & close" navigation (remembered across the confirm dialog via a
+ * ref, so a successful publish returns to the rail-owned list).
+ */
+export declare function usePublishController(input: {
+    source: CollectionViewSource;
+    docRef: DocumentRef;
+    collection: CollectionDef;
+    projectId: string;
+    draft: CmsDocument;
+    setDraft: (doc: CmsDocument) => void;
+    dirty: boolean;
+    hasUnpublishedRefs: boolean;
+}): PublishController;

package/dist/components/cms/use-publish-controller.js

@@ -0,0 +1,102 @@
+import { useCallback, useRef, useState } from 'react';
+import { STUDIO_PROJECT_ROUTE, studioPath, useNavigate } from '@elytracms/studio/router';
+import { clearHiddenValues } from '@elytracms/core/cms-core';
+import { toast } from '@elytracms/studio/ui';
+import { translate } from '@elytracms/studio/lib/i18n';
+/**
+ * EC-268 / 0.0.39 — the split Publish button's shared gate, computed once so the
+ * primary "Publish" and the "Publish & close" item can never diverge. A pure
+ * decision (directly testable): the Published perspective is read-only (switch to
+ * Draft to publish), schema errors block (with a count-aware hint), and an
+ * in-flight publish disables re-entry.
+ */
+export function publishGate(input) {
+    const disabled = input.hasErrors || input.viewReadOnly || input.publishState === 'pending';
+    const title = input.viewReadOnly
+        ? translate('cms.editor.switchToDraftToPublish')
+        : input.hasErrors
+            ? translate(input.errorCount === 1
+                ? 'cms.editor.fixIssuesToPublish.one'
+                : 'cms.editor.fixIssuesToPublish.other', { count: input.errorCount })
+            : undefined;
+    return { disabled, title };
+}
+/**
+ * EC-268 / EC-300 / 0.0.39 — the publish controller. Owns the publish indicator
+ * state, the EC-300 confirm-through guard (unpublished hard references would render
+ * empty on the live site, so publishing confirms rather than blocks), and the
+ * 0.0.39 "Publish & close" navigation (remembered across the confirm dialog via a
+ * ref, so a successful publish returns to the rail-owned list).
+ */
+export function usePublishController(input) {
+    const { source, docRef, collection, projectId, draft, setDraft, dirty, hasUnpublishedRefs } = input;
+    const navigate = useNavigate();
+    const [publishState, setPublishState] = useState('idle');
+    const [publishConfirm, setPublishConfirm] = useState(false);
+    // The split-button "Publish & close" intent — remembered across the confirm-through
+    // dialog so a successful publish returns to the list. Cleared on cancel or failure.
+    const closeAfterPublishRef = useRef(false);
+    const doPublish = useCallback(async () => {
+        // EC-273: clean conditionally-hidden values from the draft AT PUBLISH TIME —
+        // into the draft AND the snapshot, so both go clean together. Also captures the
+        // latest edit if Publish fires inside the autosave debounce window; the serial
+        // persister runs the upsert before the publish so the snapshot is this draft.
+        const cleaned = clearHiddenValues(collection, draft);
+        if (cleaned !== draft)
+            setDraft(cleaned);
+        if (cleaned !== draft || dirty)
+            source.save(cleaned);
+        setPublishState('pending');
+        try {
+            await source.publishing?.publish(docRef);
+            setPublishState('success');
+            setTimeout(() => setPublishState('idle'), 1800);
+            // "Publish & close": return to the list once the publish landed (never on a
+            // failure). Rail-owned `listPath`, falling back to the project index (AD-19).
+            if (closeAfterPublishRef.current) {
+                closeAfterPublishRef.current = false;
+                void navigate({
+                    to: STUDIO_PROJECT_ROUTE,
+                    params: { projectId, _splat: source.listPath ?? studioPath.index() },
+                });
+            }
+        }
+        catch (error) {
+            closeAfterPublishRef.current = false;
+            setPublishState('idle');
+            toast.error(error instanceof Error
+                ? translate('cms.editor.publishFailedReason', { error: error.message })
+                : translate('cms.editor.publishFailed'));
+        }
+    }, [collection, draft, setDraft, dirty, source, docRef, navigate, projectId]);
+    // Gate publish on the confirm-through dialog when there are unpublished hard
+    // references; schema errors already disable the button, so they never reach here.
+    const handlePublish = useCallback(() => {
+        if (hasUnpublishedRefs) {
+            setPublishConfirm(true);
+            return;
+        }
+        void doPublish();
+    }, [hasUnpublishedRefs, doPublish]);
+    const handlePublishAndClose = useCallback(() => {
+        closeAfterPublishRef.current = true;
+        handlePublish();
+    }, [handlePublish]);
+    const confirmPublish = useCallback(() => {
+        setPublishConfirm(false);
+        void doPublish();
+    }, [doPublish]);
+    const cancelPublishConfirm = useCallback(() => {
+        setPublishConfirm(false);
+        closeAfterPublishRef.current = false;
+    }, []);
+    return {
+        publishState,
+        publishConfirm,
+        handlePublish,
+        handlePublishAndClose,
+        confirmPublish,
+        cancelPublishConfirm,
+    };
+}
+//# sourceMappingURL=use-publish-controller.js.map

package/dist/components/cms/use-publish-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-publish-controller.js","sourceRoot":"","sources":["../../../src/components/cms/use-publish-controller.ts"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useRef, useState } from 'react'\nimport { STUDIO_PROJECT_ROUTE, studioPath, useNavigate } from '@elytracms/studio/router'\nimport { clearHiddenValues } from '@elytracms/core/cms-core'\nimport type { CmsDocument, CollectionDef, DocumentRef } from '@elytracms/core/cms-core'\nimport type { CollectionViewSource } from '@elytracms/studio/lib/collection-view/collection-view-source'\nimport { toast } from '@elytracms/studio/ui'\nimport { translate } from '@elytracms/studio/lib/i18n'\n\nexport type PublishState = 'idle' | 'pending' | 'success'\n\n/**\n * EC-268 / 0.0.39 — the split Publish button's shared gate, computed once so the\n * primary \"Publish\" and the \"Publish & close\" item can never diverge. A pure\n * decision (directly testable): the Published perspective is read-only (switch to\n * Draft to publish), schema errors block (with a count-aware hint), and an\n * in-flight publish disables re-entry.\n */\nexport function publishGate(input: {\n  hasErrors: boolean\n  viewReadOnly: boolean\n  publishState: PublishState\n  errorCount: number\n}): { disabled: boolean; title: string | undefined } {\n  const disabled = input.hasErrors || input.viewReadOnly || input.publishState === 'pending'\n  const title = input.viewReadOnly\n    ? translate('cms.editor.switchToDraftToPublish')\n    : input.hasErrors\n      ? translate(\n          input.errorCount === 1\n            ? 'cms.editor.fixIssuesToPublish.one'\n            : 'cms.editor.fixIssuesToPublish.other',\n          { count: input.errorCount },\n        )\n      : undefined\n  return { disabled, title }\n}\n\nexport interface PublishController {\n  publishState: PublishState\n  /** Is the confirm-through dialog (unpublished hard refs) open? */\n  publishConfirm: boolean\n  /** Publish (opening the confirm-through dialog first if there are unpublished refs). */\n  handlePublish: () => void\n  /** Publish and, on success, return to the rail's list (0.0.39 \"Publish & close\"). */\n  handlePublishAndClose: () => void\n  /** Confirm-through: publish despite the unpublished hard references. */\n  confirmPublish: () => void\n  /** Dismiss the confirm-through dialog (also clears a pending \"& close\" intent). */\n  cancelPublishConfirm: () => void\n}\n\n/**\n * EC-268 / EC-300 / 0.0.39 — the publish controller. Owns the publish indicator\n * state, the EC-300 confirm-through guard (unpublished hard references would render\n * empty on the live site, so publishing confirms rather than blocks), and the\n * 0.0.39 \"Publish & close\" navigation (remembered across the confirm dialog via a\n * ref, so a successful publish returns to the rail-owned list).\n */\nexport function usePublishController(input: {\n  source: CollectionViewSource\n  docRef: DocumentRef\n  collection: CollectionDef\n  projectId: string\n  draft: CmsDocument\n  setDraft: (doc: CmsDocument) => void\n  dirty: boolean\n  hasUnpublishedRefs: boolean\n}): PublishController {\n  const { source, docRef, collection, projectId, draft, setDraft, dirty, hasUnpublishedRefs } = input\n  const navigate = useNavigate()\n  const [publishState, setPublishState] = useState<PublishState>('idle')\n  const [publishConfirm, setPublishConfirm] = useState(false)\n  // The split-button \"Publish & close\" intent — remembered across the confirm-through\n  // dialog so a successful publish returns to the list. Cleared on cancel or failure.\n  const closeAfterPublishRef = useRef(false)\n\n  const doPublish = useCallback(async () => {\n    // EC-273: clean conditionally-hidden values from the draft AT PUBLISH TIME —\n    // into the draft AND the snapshot, so both go clean together. Also captures the\n    // latest edit if Publish fires inside the autosave debounce window; the serial\n    // persister runs the upsert before the publish so the snapshot is this draft.\n    const cleaned = clearHiddenValues(collection, draft)\n    if (cleaned !== draft) setDraft(cleaned)\n    if (cleaned !== draft || dirty) source.save(cleaned)\n    setPublishState('pending')\n    try {\n      await source.publishing?.publish(docRef)\n      setPublishState('success')\n      setTimeout(() => setPublishState('idle'), 1800)\n      // \"Publish & close\": return to the list once the publish landed (never on a\n      // failure). Rail-owned `listPath`, falling back to the project index (AD-19).\n      if (closeAfterPublishRef.current) {\n        closeAfterPublishRef.current = false\n        void navigate({\n          to: STUDIO_PROJECT_ROUTE,\n          params: { projectId, _splat: source.listPath ?? studioPath.index() },\n        })\n      }\n    } catch (error) {\n      closeAfterPublishRef.current = false\n      setPublishState('idle')\n      toast.error(\n        error instanceof Error\n          ? translate('cms.editor.publishFailedReason', { error: error.message })\n          : translate('cms.editor.publishFailed'),\n      )\n    }\n  }, [collection, draft, setDraft, dirty, source, docRef, navigate, projectId])\n\n  // Gate publish on the confirm-through dialog when there are unpublished hard\n  // references; schema errors already disable the button, so they never reach here.\n  const handlePublish = useCallback(() => {\n    if (hasUnpublishedRefs) {\n      setPublishConfirm(true)\n      return\n    }\n    void doPublish()\n  }, [hasUnpublishedRefs, doPublish])\n\n  const handlePublishAndClose = useCallback(() => {\n    closeAfterPublishRef.current = true\n    handlePublish()\n  }, [handlePublish])\n\n  const confirmPublish = useCallback(() => {\n    setPublishConfirm(false)\n    void doPublish()\n  }, [doPublish])\n\n  const cancelPublishConfirm = useCallback(() => {\n    setPublishConfirm(false)\n    closeAfterPublishRef.current = false\n  }, [])\n\n  return {\n    publishState,\n    publishConfirm,\n    handlePublish,\n    handlePublishAndClose,\n    confirmPublish,\n    cancelPublishConfirm,\n  }\n}\n"]}

package/dist/components/cms/use-published-perspective.d.ts

@@ -0,0 +1,67 @@
+import type { QueryKey } from '@tanstack/react-query';
+import type { CmsDocument, DocumentRef } from '@elytracms/core/cms-core';
+import type { CollectionViewSource } from '@elytracms/studio/lib/collection-view/collection-view-source';
+import type { DocumentVersionsView } from './cms-store';
+import type { PublishedSnapshotState } from './versions-model';
+export type Perspective = 'draft' | 'published';
+/**
+ * EC-226 — which document the fieldset renders, given the active perspective and
+ * the pinned published snapshot's load state. A pure decision so "never present
+ * the draft AS published" is single-sourced and directly testable:
+ *
+ * - Draft perspective → the live draft, editable.
+ * - Published perspective, snapshot READY → the pinned snapshot, read-only.
+ * - Published perspective, snapshot NOT ready → still the draft as the fallback
+ *   render target, but flagged `publishedPending` so the shell shows a placeholder
+ *   instead (the draft must never be shown labelled as the published content).
+ */
+export declare function resolveViewDoc(input: {
+    perspective: Perspective;
+    publishedSnapshot: PublishedSnapshotState;
+    draft: CmsDocument;
+}): {
+    viewReadOnly: boolean;
+    viewDoc: CmsDocument;
+    publishedPending: boolean;
+};
+export interface PublishedPerspective {
+    perspective: Perspective;
+    setPerspective: (perspective: Perspective) => void;
+    /** Is the document published (a version pointer is set)? */
+    published: boolean;
+    /** A publishing AND versioned rail — gates the version-history query + Discard. */
+    canDiscard: boolean;
+    /** The recorded version history (null while loading / disabled). */
+    versionsView: DocumentVersionsView | null;
+    /** The shared version-history cache key ({@link documentVersionsKey}). */
+    versionKey: QueryKey;
+    /** The pinned published version number, or undefined while loading / none pinned. */
+    publishedVersionNumber: number | undefined;
+    /** The pinned published version's snapshot, or undefined while loading / none. */
+    publishedSnapshotDoc: CmsDocument | undefined;
+    /** The loaded state of the pinned published snapshot. */
+    publishedSnapshot: PublishedSnapshotState;
+    /** Is the editor viewing the read-only Published snapshot? */
+    viewReadOnly: boolean;
+    /** The document the fieldset renders (draft or the pinned snapshot). */
+    viewDoc: CmsDocument;
+    /** Is the Published snapshot still loading (show a placeholder, not the draft)? */
+    publishedPending: boolean;
+}
+/**
+ * EC-226 / EC-316 / EC-325 — the Draft/Published VIEW perspective plus the pinned
+ * published snapshot, both derived from the ONE shared version-history query
+ * (AD-17: the single operations-backed cache, `use-document-versions.ts` — no raw
+ * `source.versioning.load` call). The Discard-draft gating and the Published
+ * perspective read exactly the same `versions`/`publishedVersion` shape, so a
+ * second bespoke fetch on perspective switch would just re-read this. Gated the
+ * same way Discard always was — a publishing + versioned rail AND a published
+ * document — which is also exactly when the Published perspective is reachable.
+ */
+export declare function usePublishedPerspective(input: {
+    ref: DocumentRef;
+    source: CollectionViewSource;
+    canPublish: boolean;
+    canVersions: boolean;
+    draft: CmsDocument;
+}): PublishedPerspective;

package/dist/components/cms/use-published-perspective.js

@@ -0,0 +1,67 @@
+import { useEffect, useState } from 'react';
+import { useDocumentVersionsQuery } from './use-document-versions';
+import { derivePublishedSnapshot, publishedVersionSnapshot } from './versions-model';
+/**
+ * EC-226 — which document the fieldset renders, given the active perspective and
+ * the pinned published snapshot's load state. A pure decision so "never present
+ * the draft AS published" is single-sourced and directly testable:
+ *
+ * - Draft perspective → the live draft, editable.
+ * - Published perspective, snapshot READY → the pinned snapshot, read-only.
+ * - Published perspective, snapshot NOT ready → still the draft as the fallback
+ *   render target, but flagged `publishedPending` so the shell shows a placeholder
+ *   instead (the draft must never be shown labelled as the published content).
+ */
+export function resolveViewDoc(input) {
+    const viewReadOnly = input.perspective === 'published';
+    const ready = input.publishedSnapshot.status === 'ready';
+    return {
+        viewReadOnly,
+        viewDoc: viewReadOnly && input.publishedSnapshot.status === 'ready' ? input.publishedSnapshot.doc : input.draft,
+        publishedPending: viewReadOnly && !ready,
+    };
+}
+/**
+ * EC-226 / EC-316 / EC-325 — the Draft/Published VIEW perspective plus the pinned
+ * published snapshot, both derived from the ONE shared version-history query
+ * (AD-17: the single operations-backed cache, `use-document-versions.ts` — no raw
+ * `source.versioning.load` call). The Discard-draft gating and the Published
+ * perspective read exactly the same `versions`/`publishedVersion` shape, so a
+ * second bespoke fetch on perspective switch would just re-read this. Gated the
+ * same way Discard always was — a publishing + versioned rail AND a published
+ * document — which is also exactly when the Published perspective is reachable.
+ */
+export function usePublishedPerspective(input) {
+    const { ref, source, canPublish, canVersions, draft } = input;
+    const published = source.publishing?.isPublished(ref) ?? false;
+    const [perspective, setPerspective] = useState('draft');
+    // Snap back to Draft if the document is unpublished while viewing Published.
+    useEffect(() => {
+        if (!published)
+            setPerspective('draft');
+    }, [published]);
+    const canDiscard = canPublish && canVersions;
+    const { versionsQuery, versionKey } = useDocumentVersionsQuery(ref, {
+        enabled: canDiscard && published,
+    });
+    const versionsView = versionsQuery.data ?? null;
+    const publishedVersionNumber = versionsView?.publishedVersion;
+    const publishedSnapshotDoc = publishedVersionSnapshot(versionsView);
+    const publishedSnapshot = derivePublishedSnapshot(versionsView);
+    const { viewReadOnly, viewDoc, publishedPending } = resolveViewDoc({ perspective, publishedSnapshot, draft });
+    return {
+        perspective,
+        setPerspective,
+        published,
+        canDiscard,
+        versionsView,
+        versionKey,
+        publishedVersionNumber,
+        publishedSnapshotDoc,
+        publishedSnapshot,
+        viewReadOnly,
+        viewDoc,
+        publishedPending,
+    };
+}
+//# sourceMappingURL=use-published-perspective.js.map

package/dist/components/cms/use-published-perspective.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-published-perspective.js","sourceRoot":"","sources":["../../../src/components/cms/use-published-perspective.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAK3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AAClE,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAKpF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,KAI9B;IACC,MAAM,YAAY,GAAG,KAAK,CAAC,WAAW,KAAK,WAAW,CAAA;IACtD,MAAM,KAAK,GAAG,KAAK,CAAC,iBAAiB,CAAC,MAAM,KAAK,OAAO,CAAA;IACxD,OAAO;QACL,YAAY;QACZ,OAAO,EAAE,YAAY,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK;QAC/G,gBAAgB,EAAE,YAAY,IAAI,CAAC,KAAK;KACzC,CAAA;AACH,CAAC;AA2BD;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAMvC;IACC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,KAAK,CAAA;IAC7D,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,GAAG,CAAC,IAAI,KAAK,CAAA;IAC9D,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAc,OAAO,CAAC,CAAA;IACpE,6EAA6E;IAC7E,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,SAAS;YAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IACzC,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAA;IAEf,MAAM,UAAU,GAAG,UAAU,IAAI,WAAW,CAAA;IAC5C,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,wBAAwB,CAAC,GAAG,EAAE;QAClE,OAAO,EAAE,UAAU,IAAI,SAAS;KACjC,CAAC,CAAA;IACF,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,IAAI,IAAI,CAAA;IAC/C,MAAM,sBAAsB,GAAG,YAAY,EAAE,gBAAgB,CAAA;IAC7D,MAAM,oBAAoB,GAAG,wBAAwB,CAAC,YAAY,CAAC,CAAA;IACnE,MAAM,iBAAiB,GAAG,uBAAuB,CAAC,YAAY,CAAC,CAAA;IAC/D,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,gBAAgB,EAAE,GAAG,cAAc,CAAC,EAAE,WAAW,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAA;IAE7G,OAAO;QACL,WAAW;QACX,cAAc;QACd,SAAS;QACT,UAAU;QACV,YAAY;QACZ,UAAU;QACV,sBAAsB;QACtB,oBAAoB;QACpB,iBAAiB;QACjB,YAAY;QACZ,OAAO;QACP,gBAAgB;KACjB,CAAA;AACH,CAAC","sourcesContent":["import { useEffect, useState } from 'react'\nimport type { QueryKey } from '@tanstack/react-query'\nimport type { CmsDocument, DocumentRef } from '@elytracms/core/cms-core'\nimport type { CollectionViewSource } from '@elytracms/studio/lib/collection-view/collection-view-source'\nimport type { DocumentVersionsView } from './cms-store'\nimport { useDocumentVersionsQuery } from './use-document-versions'\nimport { derivePublishedSnapshot, publishedVersionSnapshot } from './versions-model'\nimport type { PublishedSnapshotState } from './versions-model'\n\nexport type Perspective = 'draft' | 'published'\n\n/**\n * EC-226 — which document the fieldset renders, given the active perspective and\n * the pinned published snapshot's load state. A pure decision so \"never present\n * the draft AS published\" is single-sourced and directly testable:\n *\n * - Draft perspective → the live draft, editable.\n * - Published perspective, snapshot READY → the pinned snapshot, read-only.\n * - Published perspective, snapshot NOT ready → still the draft as the fallback\n *   render target, but flagged `publishedPending` so the shell shows a placeholder\n *   instead (the draft must never be shown labelled as the published content).\n */\nexport function resolveViewDoc(input: {\n  perspective: Perspective\n  publishedSnapshot: PublishedSnapshotState\n  draft: CmsDocument\n}): { viewReadOnly: boolean; viewDoc: CmsDocument; publishedPending: boolean } {\n  const viewReadOnly = input.perspective === 'published'\n  const ready = input.publishedSnapshot.status === 'ready'\n  return {\n    viewReadOnly,\n    viewDoc: viewReadOnly && input.publishedSnapshot.status === 'ready' ? input.publishedSnapshot.doc : input.draft,\n    publishedPending: viewReadOnly && !ready,\n  }\n}\n\nexport interface PublishedPerspective {\n  perspective: Perspective\n  setPerspective: (perspective: Perspective) => void\n  /** Is the document published (a version pointer is set)? */\n  published: boolean\n  /** A publishing AND versioned rail — gates the version-history query + Discard. */\n  canDiscard: boolean\n  /** The recorded version history (null while loading / disabled). */\n  versionsView: DocumentVersionsView | null\n  /** The shared version-history cache key ({@link documentVersionsKey}). */\n  versionKey: QueryKey\n  /** The pinned published version number, or undefined while loading / none pinned. */\n  publishedVersionNumber: number | undefined\n  /** The pinned published version's snapshot, or undefined while loading / none. */\n  publishedSnapshotDoc: CmsDocument | undefined\n  /** The loaded state of the pinned published snapshot. */\n  publishedSnapshot: PublishedSnapshotState\n  /** Is the editor viewing the read-only Published snapshot? */\n  viewReadOnly: boolean\n  /** The document the fieldset renders (draft or the pinned snapshot). */\n  viewDoc: CmsDocument\n  /** Is the Published snapshot still loading (show a placeholder, not the draft)? */\n  publishedPending: boolean\n}\n\n/**\n * EC-226 / EC-316 / EC-325 — the Draft/Published VIEW perspective plus the pinned\n * published snapshot, both derived from the ONE shared version-history query\n * (AD-17: the single operations-backed cache, `use-document-versions.ts` — no raw\n * `source.versioning.load` call). The Discard-draft gating and the Published\n * perspective read exactly the same `versions`/`publishedVersion` shape, so a\n * second bespoke fetch on perspective switch would just re-read this. Gated the\n * same way Discard always was — a publishing + versioned rail AND a published\n * document — which is also exactly when the Published perspective is reachable.\n */\nexport function usePublishedPerspective(input: {\n  ref: DocumentRef\n  source: CollectionViewSource\n  canPublish: boolean\n  canVersions: boolean\n  draft: CmsDocument\n}): PublishedPerspective {\n  const { ref, source, canPublish, canVersions, draft } = input\n  const published = source.publishing?.isPublished(ref) ?? false\n  const [perspective, setPerspective] = useState<Perspective>('draft')\n  // Snap back to Draft if the document is unpublished while viewing Published.\n  useEffect(() => {\n    if (!published) setPerspective('draft')\n  }, [published])\n\n  const canDiscard = canPublish && canVersions\n  const { versionsQuery, versionKey } = useDocumentVersionsQuery(ref, {\n    enabled: canDiscard && published,\n  })\n  const versionsView = versionsQuery.data ?? null\n  const publishedVersionNumber = versionsView?.publishedVersion\n  const publishedSnapshotDoc = publishedVersionSnapshot(versionsView)\n  const publishedSnapshot = derivePublishedSnapshot(versionsView)\n  const { viewReadOnly, viewDoc, publishedPending } = resolveViewDoc({ perspective, publishedSnapshot, draft })\n\n  return {\n    perspective,\n    setPerspective,\n    published,\n    canDiscard,\n    versionsView,\n    versionKey,\n    publishedVersionNumber,\n    publishedSnapshotDoc,\n    publishedSnapshot,\n    viewReadOnly,\n    viewDoc,\n    publishedPending,\n  }\n}\n"]}

package/dist/components/cms/use-restore-version.d.ts

@@ -0,0 +1,57 @@
+import type { QueryKey } from '@tanstack/react-query';
+import type { CmsDocument, DocumentRef, RestoreScope } from '@elytracms/core/cms-core';
+import type { CollectionViewSource } from '@elytracms/studio/lib/collection-view/collection-view-source';
+/**
+ * EC-325 — the version-restore sequence, single-sourced. The Versions pane's
+ * per-version restore, the Compare view's scoped/whole restore, and the header's
+ * "Discard changes" (a whole-document restore of the pinned published version)
+ * all ran their OWN copy of the identical four steps:
+ *
+ *   1. flush a dirty in-memory buffer FIRST (`flushDirtyDraft`) — `documents.restore`
+ *      snapshots whatever is currently PERSISTED as its pre-restore version, so an
+ *      edit still in the autosave debounce window must reach the server before the
+ *      restore reads it, or it is silently unrecoverable (the undo-guarantee gap
+ *      the Discard path used to have);
+ *   2. `versioning.restore(ref, version, scope?)` — scope absent ⇒ whole document
+ *      (`documents.restore` reads `scope ?? { kind: 'all' }`, so an omitted scope
+ *      and `{ kind: 'all' }` are the same restore);
+ *   3. adopt the restored draft into the open editor (`replaceDraft`);
+ *   4. invalidate the shared version-history cache key so the history re-reads.
+ *
+ * The pure {@link performRestore} pins that ordering (unit-tested with spies); the
+ * {@link useRestoreVersion} hook wraps it with the per-call-site busy flag and the
+ * operations cache. The differing signatures reconcile to `(version, scope?)`:
+ * whole-document callers pass no scope, the Compare view passes its `RestoreScope`,
+ * and Discard passes the pinned published version with `{ kind: 'all' }`.
+ */
+export declare function performRestore(input: {
+    dirty: boolean;
+    save: () => void;
+    restore: (version: number, scope?: RestoreScope) => Promise<CmsDocument | null>;
+    replaceDraft: (doc: CmsDocument) => void;
+    invalidate: () => Promise<void>;
+    version: number;
+    scope?: RestoreScope;
+}): Promise<void>;
+/** Dependencies the restore sequence reads from its call site's editor state. */
+export interface RestoreVersionDeps {
+    source: CollectionViewSource;
+    docRef: DocumentRef;
+    /** The shared version-history cache key ({@link documentVersionsKey}). */
+    versionKey: QueryKey;
+    /** Is the in-memory draft dirty (an unsaved buffer to flush first)? */
+    dirty: boolean;
+    /** Persist the current draft buffer. */
+    save: () => void;
+    /** Adopt the restored snapshot as the open editor's draft. */
+    replaceDraft: (doc: CmsDocument) => void;
+}
+/**
+ * The shared restore action + its in-flight flag. `restore(version, scope?)`
+ * runs the {@link performRestore} sequence; `busy` gates the calling surface's
+ * restore/discard controls while it round-trips.
+ */
+export declare function useRestoreVersion(deps: RestoreVersionDeps): {
+    restore: (version: number, scope?: RestoreScope) => Promise<void>;
+    busy: boolean;
+};

package/dist/components/cms/use-restore-version.js

@@ -0,0 +1,66 @@
+import { useCallback, useState } from 'react';
+import { useOperationCache } from '@elytracms/studio/lib/query';
+import { flushDirtyDraft } from './discard-draft';
+/**
+ * EC-325 — the version-restore sequence, single-sourced. The Versions pane's
+ * per-version restore, the Compare view's scoped/whole restore, and the header's
+ * "Discard changes" (a whole-document restore of the pinned published version)
+ * all ran their OWN copy of the identical four steps:
+ *
+ *   1. flush a dirty in-memory buffer FIRST (`flushDirtyDraft`) — `documents.restore`
+ *      snapshots whatever is currently PERSISTED as its pre-restore version, so an
+ *      edit still in the autosave debounce window must reach the server before the
+ *      restore reads it, or it is silently unrecoverable (the undo-guarantee gap
+ *      the Discard path used to have);
+ *   2. `versioning.restore(ref, version, scope?)` — scope absent ⇒ whole document
+ *      (`documents.restore` reads `scope ?? { kind: 'all' }`, so an omitted scope
+ *      and `{ kind: 'all' }` are the same restore);
+ *   3. adopt the restored draft into the open editor (`replaceDraft`);
+ *   4. invalidate the shared version-history cache key so the history re-reads.
+ *
+ * The pure {@link performRestore} pins that ordering (unit-tested with spies); the
+ * {@link useRestoreVersion} hook wraps it with the per-call-site busy flag and the
+ * operations cache. The differing signatures reconcile to `(version, scope?)`:
+ * whole-document callers pass no scope, the Compare view passes its `RestoreScope`,
+ * and Discard passes the pinned published version with `{ kind: 'all' }`.
+ */
+export async function performRestore(input) {
+    // Step 1 — flush before the restore reads the persisted document.
+    flushDirtyDraft({ dirty: input.dirty, save: input.save });
+    // Step 2 — the restore itself (scope absent ⇒ whole document).
+    const restored = await input.restore(input.version, input.scope);
+    // Step 3 — the open editor adopts the restored snapshot as its new draft.
+    if (restored)
+        input.replaceDraft(restored);
+    // Step 4 — re-read the recorded history (the new pre-restore version appears).
+    await input.invalidate();
+}
+/**
+ * The shared restore action + its in-flight flag. `restore(version, scope?)`
+ * runs the {@link performRestore} sequence; `busy` gates the calling surface's
+ * restore/discard controls while it round-trips.
+ */
+export function useRestoreVersion(deps) {
+    const { source, docRef, versionKey, dirty, save, replaceDraft } = deps;
+    const cache = useOperationCache();
+    const [busy, setBusy] = useState(false);
+    const restore = useCallback(async (version, scope) => {
+        setBusy(true);
+        try {
+            await performRestore({
+                dirty,
+                save,
+                restore: async (v, s) => (await source.versioning?.restore(docRef, v, s)) ?? null,
+                replaceDraft,
+                invalidate: () => cache.invalidate(versionKey),
+                version,
+                scope,
+            });
+        }
+        finally {
+            setBusy(false);
+        }
+    }, [source, docRef, versionKey, dirty, save, replaceDraft, cache]);
+    return { restore, busy };
+}
+//# sourceMappingURL=use-restore-version.js.map

package/dist/components/cms/use-restore-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-restore-version.js","sourceRoot":"","sources":["../../../src/components/cms/use-restore-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAG7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAQpC;IACC,kEAAkE;IAClE,eAAe,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;IACzD,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IAChE,0EAA0E;IAC1E,IAAI,QAAQ;QAAE,KAAK,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAA;IAC1C,+EAA+E;IAC/E,MAAM,KAAK,CAAC,UAAU,EAAE,CAAA;AAC1B,CAAC;AAgBD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAwB;IAIxD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI,CAAA;IACtE,MAAM,KAAK,GAAG,iBAAiB,EAAE,CAAA;IACjC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IACvC,MAAM,OAAO,GAAG,WAAW,CACzB,KAAK,EAAE,OAAe,EAAE,KAAoB,EAAE,EAAE;QAC9C,OAAO,CAAC,IAAI,CAAC,CAAA;QACb,IAAI,CAAC;YACH,MAAM,cAAc,CAAC;gBACnB,KAAK;gBACL,IAAI;gBACJ,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI;gBACjF,YAAY;gBACZ,UAAU,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC;gBAC9C,OAAO;gBACP,KAAK;aACN,CAAC,CAAA;QACJ,CAAC;gBAAS,CAAC;YACT,OAAO,CAAC,KAAK,CAAC,CAAA;QAChB,CAAC;IACH,CAAC,EACD,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,CAC/D,CAAA;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAC1B,CAAC","sourcesContent":["import { useCallback, useState } from 'react'\nimport type { QueryKey } from '@tanstack/react-query'\nimport type { CmsDocument, DocumentRef, RestoreScope } from '@elytracms/core/cms-core'\nimport { useOperationCache } from '@elytracms/studio/lib/query'\nimport type { CollectionViewSource } from '@elytracms/studio/lib/collection-view/collection-view-source'\nimport { flushDirtyDraft } from './discard-draft'\n\n/**\n * EC-325 — the version-restore sequence, single-sourced. The Versions pane's\n * per-version restore, the Compare view's scoped/whole restore, and the header's\n * \"Discard changes\" (a whole-document restore of the pinned published version)\n * all ran their OWN copy of the identical four steps:\n *\n *   1. flush a dirty in-memory buffer FIRST (`flushDirtyDraft`) — `documents.restore`\n *      snapshots whatever is currently PERSISTED as its pre-restore version, so an\n *      edit still in the autosave debounce window must reach the server before the\n *      restore reads it, or it is silently unrecoverable (the undo-guarantee gap\n *      the Discard path used to have);\n *   2. `versioning.restore(ref, version, scope?)` — scope absent ⇒ whole document\n *      (`documents.restore` reads `scope ?? { kind: 'all' }`, so an omitted scope\n *      and `{ kind: 'all' }` are the same restore);\n *   3. adopt the restored draft into the open editor (`replaceDraft`);\n *   4. invalidate the shared version-history cache key so the history re-reads.\n *\n * The pure {@link performRestore} pins that ordering (unit-tested with spies); the\n * {@link useRestoreVersion} hook wraps it with the per-call-site busy flag and the\n * operations cache. The differing signatures reconcile to `(version, scope?)`:\n * whole-document callers pass no scope, the Compare view passes its `RestoreScope`,\n * and Discard passes the pinned published version with `{ kind: 'all' }`.\n */\nexport async function performRestore(input: {\n  dirty: boolean\n  save: () => void\n  restore: (version: number, scope?: RestoreScope) => Promise<CmsDocument | null>\n  replaceDraft: (doc: CmsDocument) => void\n  invalidate: () => Promise<void>\n  version: number\n  scope?: RestoreScope\n}): Promise<void> {\n  // Step 1 — flush before the restore reads the persisted document.\n  flushDirtyDraft({ dirty: input.dirty, save: input.save })\n  // Step 2 — the restore itself (scope absent ⇒ whole document).\n  const restored = await input.restore(input.version, input.scope)\n  // Step 3 — the open editor adopts the restored snapshot as its new draft.\n  if (restored) input.replaceDraft(restored)\n  // Step 4 — re-read the recorded history (the new pre-restore version appears).\n  await input.invalidate()\n}\n\n/** Dependencies the restore sequence reads from its call site's editor state. */\nexport interface RestoreVersionDeps {\n  source: CollectionViewSource\n  docRef: DocumentRef\n  /** The shared version-history cache key ({@link documentVersionsKey}). */\n  versionKey: QueryKey\n  /** Is the in-memory draft dirty (an unsaved buffer to flush first)? */\n  dirty: boolean\n  /** Persist the current draft buffer. */\n  save: () => void\n  /** Adopt the restored snapshot as the open editor's draft. */\n  replaceDraft: (doc: CmsDocument) => void\n}\n\n/**\n * The shared restore action + its in-flight flag. `restore(version, scope?)`\n * runs the {@link performRestore} sequence; `busy` gates the calling surface's\n * restore/discard controls while it round-trips.\n */\nexport function useRestoreVersion(deps: RestoreVersionDeps): {\n  restore: (version: number, scope?: RestoreScope) => Promise<void>\n  busy: boolean\n} {\n  const { source, docRef, versionKey, dirty, save, replaceDraft } = deps\n  const cache = useOperationCache()\n  const [busy, setBusy] = useState(false)\n  const restore = useCallback(\n    async (version: number, scope?: RestoreScope) => {\n      setBusy(true)\n      try {\n        await performRestore({\n          dirty,\n          save,\n          restore: async (v, s) => (await source.versioning?.restore(docRef, v, s)) ?? null,\n          replaceDraft,\n          invalidate: () => cache.invalidate(versionKey),\n          version,\n          scope,\n        })\n      } finally {\n        setBusy(false)\n      }\n    },\n    [source, docRef, versionKey, dirty, save, replaceDraft, cache],\n  )\n  return { restore, busy }\n}\n"]}

package/dist/components/cms/use-save-mode.d.ts

@@ -0,0 +1,35 @@
+import type { CmsDocument } from '@elytracms/core/cms-core';
+import type { CollectionViewSource } from '@elytracms/studio/lib/collection-view/collection-view-source';
+/**
+ * EC-225 / EC-240 — the two persistence disciplines the detail editor supports,
+ * as one pure decision so the autosave scheduler and the unmount flush can never
+ * diverge on WHEN a dirty draft is persisted silently:
+ *
+ * - A **publishing** rail AUTOSAVES: the draft persists 1s after the last edit and
+ *   publish is the deliberate commit — so a dirty draft is flushed both on the
+ *   debounce timer and on unmount (navigating away inside the debounce window).
+ * - A **non-publishing** rail (users, EC-240) SAVES EXPLICITLY: edits stay in the
+ *   draft until the Save button, and an `UnsavedChangesGuard` protects navigation —
+ *   so it NEVER persists silently (returns false here).
+ */
+export declare function shouldPersistDraft(input: {
+    explicitSave: boolean;
+    dirty: boolean;
+}): boolean;
+/**
+ * EC-225 autosave · EC-240 explicit save. Owns the debounced autosave timer and
+ * the unmount flush for a publishing rail; a non-publishing rail persists only via
+ * its Save button (the caller's `UnsavedChangesGuard` covers navigation). Refs let
+ * the unmount flush read the latest values without re-subscribing.
+ *
+ * Returns `explicitSave` — the caller renders the Save button + guard (explicit)
+ * or the autosave status text (autosave) from it.
+ */
+export declare function useSaveMode(input: {
+    canPublish: boolean;
+    dirty: boolean;
+    draft: CmsDocument;
+    source: CollectionViewSource;
+}): {
+    explicitSave: boolean;
+};

package/dist/components/cms/use-save-mode.js

@@ -0,0 +1,54 @@
+import { useEffect, useRef } from 'react';
+/**
+ * EC-225 / EC-240 — the two persistence disciplines the detail editor supports,
+ * as one pure decision so the autosave scheduler and the unmount flush can never
+ * diverge on WHEN a dirty draft is persisted silently:
+ *
+ * - A **publishing** rail AUTOSAVES: the draft persists 1s after the last edit and
+ *   publish is the deliberate commit — so a dirty draft is flushed both on the
+ *   debounce timer and on unmount (navigating away inside the debounce window).
+ * - A **non-publishing** rail (users, EC-240) SAVES EXPLICITLY: edits stay in the
+ *   draft until the Save button, and an `UnsavedChangesGuard` protects navigation —
+ *   so it NEVER persists silently (returns false here).
+ */
+export function shouldPersistDraft(input) {
+    return !input.explicitSave && input.dirty;
+}
+/**
+ * EC-225 autosave · EC-240 explicit save. Owns the debounced autosave timer and
+ * the unmount flush for a publishing rail; a non-publishing rail persists only via
+ * its Save button (the caller's `UnsavedChangesGuard` covers navigation). Refs let
+ * the unmount flush read the latest values without re-subscribing.
+ *
+ * Returns `explicitSave` — the caller renders the Save button + guard (explicit)
+ * or the autosave status text (autosave) from it.
+ */
+export function useSaveMode(input) {
+    const { canPublish, dirty, draft, source } = input;
+    const explicitSave = !canPublish;
+    const draftRef = useRef(draft);
+    draftRef.current = draft;
+    const dirtyRef = useRef(dirty);
+    dirtyRef.current = dirty;
+    const sourceRef = useRef(source);
+    sourceRef.current = source;
+    const explicitSaveRef = useRef(explicitSave);
+    explicitSaveRef.current = explicitSave;
+    useEffect(() => {
+        if (explicitSave)
+            return; // explicit rails persist only via the Save button
+        if (!dirty)
+            return;
+        const timer = window.setTimeout(() => sourceRef.current.save(draftRef.current), 1000);
+        return () => window.clearTimeout(timer);
+    }, [dirty, draft, explicitSave]);
+    // Flush a still-pending AUTOSAVE edit on unmount (navigating away inside the
+    // debounce window) so nothing is lost. Explicit rails never flush silently —
+    // their `UnsavedChangesGuard` catches the navigation instead. Unmount-only.
+    useEffect(() => () => {
+        if (shouldPersistDraft({ explicitSave: explicitSaveRef.current, dirty: dirtyRef.current }))
+            sourceRef.current.save(draftRef.current);
+    }, []);
+    return { explicitSave };
+}
+//# sourceMappingURL=use-save-mode.js.map

package/dist/components/cms/use-save-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-save-mode.js","sourceRoot":"","sources":["../../../src/components/cms/use-save-mode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AAIzC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAgD;IACjF,OAAO,CAAC,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,KAAK,CAAA;AAC3C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAK3B;IACC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAK,CAAA;IAClD,MAAM,YAAY,GAAG,CAAC,UAAU,CAAA;IAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC9B,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAA;IACxB,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC9B,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAA;IACxB,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;IAChC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAA;IAC1B,MAAM,eAAe,GAAG,MAAM,CAAC,YAAY,CAAC,CAAA;IAC5C,eAAe,CAAC,OAAO,GAAG,YAAY,CAAA;IAEtC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,YAAY;YAAE,OAAM,CAAC,kDAAkD;QAC3E,IAAI,CAAC,KAAK;YAAE,OAAM;QAClB,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAA;QACrF,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;IACzC,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAA;IAEhC,6EAA6E;IAC7E,6EAA6E;IAC7E,4EAA4E;IAC5E,SAAS,CACP,GAAG,EAAE,CAAC,GAAG,EAAE;QACT,IAAI,kBAAkB,CAAC,EAAE,YAAY,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;YACxF,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC5C,CAAC,EACD,EAAE,CACH,CAAA;IAED,OAAO,EAAE,YAAY,EAAE,CAAA;AACzB,CAAC","sourcesContent":["import { useEffect, useRef } from 'react'\nimport type { CmsDocument } from '@elytracms/core/cms-core'\nimport type { CollectionViewSource } from '@elytracms/studio/lib/collection-view/collection-view-source'\n\n/**\n * EC-225 / EC-240 — the two persistence disciplines the detail editor supports,\n * as one pure decision so the autosave scheduler and the unmount flush can never\n * diverge on WHEN a dirty draft is persisted silently:\n *\n * - A **publishing** rail AUTOSAVES: the draft persists 1s after the last edit and\n *   publish is the deliberate commit — so a dirty draft is flushed both on the\n *   debounce timer and on unmount (navigating away inside the debounce window).\n * - A **non-publishing** rail (users, EC-240) SAVES EXPLICITLY: edits stay in the\n *   draft until the Save button, and an `UnsavedChangesGuard` protects navigation —\n *   so it NEVER persists silently (returns false here).\n */\nexport function shouldPersistDraft(input: { explicitSave: boolean; dirty: boolean }): boolean {\n  return !input.explicitSave && input.dirty\n}\n\n/**\n * EC-225 autosave · EC-240 explicit save. Owns the debounced autosave timer and\n * the unmount flush for a publishing rail; a non-publishing rail persists only via\n * its Save button (the caller's `UnsavedChangesGuard` covers navigation). Refs let\n * the unmount flush read the latest values without re-subscribing.\n *\n * Returns `explicitSave` — the caller renders the Save button + guard (explicit)\n * or the autosave status text (autosave) from it.\n */\nexport function useSaveMode(input: {\n  canPublish: boolean\n  dirty: boolean\n  draft: CmsDocument\n  source: CollectionViewSource\n}): { explicitSave: boolean } {\n  const { canPublish, dirty, draft, source } = input\n  const explicitSave = !canPublish\n  const draftRef = useRef(draft)\n  draftRef.current = draft\n  const dirtyRef = useRef(dirty)\n  dirtyRef.current = dirty\n  const sourceRef = useRef(source)\n  sourceRef.current = source\n  const explicitSaveRef = useRef(explicitSave)\n  explicitSaveRef.current = explicitSave\n\n  useEffect(() => {\n    if (explicitSave) return // explicit rails persist only via the Save button\n    if (!dirty) return\n    const timer = window.setTimeout(() => sourceRef.current.save(draftRef.current), 1000)\n    return () => window.clearTimeout(timer)\n  }, [dirty, draft, explicitSave])\n\n  // Flush a still-pending AUTOSAVE edit on unmount (navigating away inside the\n  // debounce window) so nothing is lost. Explicit rails never flush silently —\n  // their `UnsavedChangesGuard` catches the navigation instead. Unmount-only.\n  useEffect(\n    () => () => {\n      if (shouldPersistDraft({ explicitSave: explicitSaveRef.current, dirty: dirtyRef.current }))\n        sourceRef.current.save(draftRef.current)\n    },\n    [],\n  )\n\n  return { explicitSave }\n}\n"]}

package/dist/components/cms/version-compare.js

@@ -4,7 +4,6 @@ import { ArrowRight, ChevronDown, ChevronLeft, ChevronRight, Image as ImageIcon,
 import { diffDocuments } from '@elytracms/core/content';
 import { assetSubfieldsOf, isAssetNode, readAssetId, readDocumentRef } from '@elytracms/core/cms-core';
 import { Badge, Button, Code, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, Row, Spacer, Stack, Text, } from '@elytracms/studio/ui';
-import { useOperationCache } from '@elytracms/studio/lib/query';
 import { translate } from '@elytracms/studio/lib/i18n';
 import { localeChipLabel } from '@elytracms/studio/lib/locale';
 import { cn } from '@elytracms/studio/lib/utils';
@@ -15,6 +14,7 @@ import { toRefArray } from './cell';
 import { DIFF_TRUNCATE_THRESHOLD, mergeWordDiff, richTextToText, truncateText, truncateTokens, wordDiff, } from './version-compare-text';
 import { useDocumentEditor } from './document-editor-context';
 import { useDocumentVersionsQuery } from './use-document-versions';
+import { useRestoreVersion } from './use-restore-version';
 import { formatVersionTimestamp } from './versions-model';
 /**
  * EC-298 — the version compare view. Renders as the sticky **Compare** content tab
@@ -35,8 +35,16 @@ export function VersionCompare() {
     const source = useCollectionView();
     const { collection, docRef, draft, dirty, viewReadOnly, save, replaceDraft, compare, setCompareBase, setCompareTarget, } = useDocumentEditor();
     const { versionsQuery, versionKey } = useDocumentVersionsQuery(docRef);
-    const cache = useOperationCache();
-    const [busy, setBusy] = useState(false);
+    // EC-325 — the shared restore sequence (flush → restore → replaceDraft →
+    // invalidate). `busy` gates the restore controls below while it round-trips.
+    const { restore: restoreVersion, busy } = useRestoreVersion({
+        source,
+        docRef,
+        versionKey,
+        dirty,
+        save,
+        replaceDraft,
+    });
     // EC-317 — the unified/side-by-side toggle is a transient, personal-local view
     // preference (same class as the theme/rail prefs): read once at mount, written
     // back on every change, never round-tripped through the project graph.
@@ -97,19 +105,8 @@ export function VersionCompare() {
     const restore = useCallback(async (scope) => {
         if (!compare)
             return;
-        setBusy(true);
-        try {
-            if (dirty)
-                save();
-            const restored = await source.versioning?.restore(docRef, compare.base, scope);
-            if (restored)
-                replaceDraft(restored);
-            await cache.invalidate(versionKey);
-        }
-        finally {
-            setBusy(false);
-        }
-    }, [compare, dirty, save, source, docRef, replaceDraft, cache, versionKey]);
+        await restoreVersion(compare.base, scope);
+    }, [compare, restoreVersion]);
     if (!compare)
         return null;
     if (view === null)