@elytracms/studio 0.0.43 → 0.0.44

package/dist/components/cms/detail-editor.js

@@ -1,17 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Link, STUDIO_PROJECT_ROUTE, studioPath, useNavigate } from '@elytracms/studio/router';
 import { Check, ChevronDown, CircleAlert, CircleCheck, Eye, EyeOff, GitCompareArrows, History, Loader2, Lock, MoreHorizontal, RotateCcw, Save, Tag, Trash2, X, } from 'lucide-react';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { FIELD_WIDTH_SPANS, SIDEBAR_FIELD_GROUP, clearHiddenValues, documentKey, groupOrder, groupSectionOf, hasAliases, hiddenGroupNames, isBlocksField, isFieldHidden, isFieldLocalized, isSingleton, resolveDocumentForLocale, resolveDocumentTitle, resolveField, sidebarFields, tabDescriptorOf, tabOrder, titleFieldOf, staticFieldHidden, urlForDocument, } from '@elytracms/core/cms-core';
+import { useCallback, useMemo, useState } from 'react';
+import { FIELD_WIDTH_SPANS, SIDEBAR_FIELD_GROUP, documentKey, groupOrder, groupSectionOf, hasAliases, hiddenGroupNames, isBlocksField, isFieldHidden, isFieldLocalized, isSingleton, resolveDocumentForLocale, resolveDocumentTitle, resolveField, sidebarFields, tabDescriptorOf, tabOrder, titleFieldOf, staticFieldHidden, } from '@elytracms/core/cms-core';
 import { blockRootsOf } from '@elytracms/core/project-graph';
 import { Badge, Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, CollapsibleSection, Field, Heading, Row, Spacer, Stack, Text, toast, } from '@elytracms/studio/ui';
 import { getStudioRegistry } from '@elytracms/studio/lib/registry';
 import { collectEmbedRefs, resolveReuseCapability } from '../builder/reuse';
 import { cn } from '@elytracms/studio/lib/utils';
-import { useOperationCache } from '@elytracms/studio/lib/query';
 import { localizedLabel, translate } from '@elytracms/studio/lib/i18n';
-import { LocaleSwitcher, activeLocaleValues, displayedFieldFallback, fieldConnection, fillFieldFromBase, resetFieldToBase, setFieldValue, setStudioLocale, } from '@elytracms/studio/lib/locale';
-import { parseDocumentFieldPath } from '@elytracms/studio/lib/references';
+import { LocaleSwitcher, activeLocaleValues, displayedFieldFallback, fieldConnection, fillFieldFromBase, resetFieldToBase, setFieldValue, } from '@elytracms/studio/lib/locale';
 import { FallbackChip } from './cell';
 import { FieldConnectionControl } from './field-connection';
 import { FieldControl } from './field-control';
@@ -32,9 +30,6 @@ import { VersionsPane } from './versions-pane';
 // EC-322: the lazy-wrapped compare view — its diff UI code-splits off the detail-view
 // critical path and loads only when the Compare tab opens.
 import { VersionCompare } from './version-compare-lazy';
-import { useDocumentVersionsQuery } from './use-document-versions';
-import { discardDraftStatus, flushDirtyDraft } from './discard-draft';
-import { derivePublishedSnapshot, publishedVersionSnapshot } from './versions-model';
 import { IssuesPane } from './issues-pane';
 import { DetailsPane } from './details-pane';
 import { DocumentUrlPath } from './document-url-path';
@@ -43,8 +38,18 @@ import { DocumentUrlPath } from './document-url-path';
 import { EmbedInspectorProvider } from './rich-text/embed-inspector-context';
 import { EmbedInspector } from './rich-text/embed-inspector';
 import { useSetBreadcrumb } from '../breadcrumb-context';
-import { resolveDeploymentFrontendUrl, resolveDeploymentRoutes } from '@elytracms/studio/lib/workspace';
-import { usePublishedDocuments } from '@elytracms/studio/lib/cms/published-documents';
+import { resolveDeploymentRoutes } from '@elytracms/studio/lib/workspace';
+// EC-325 — the controller hooks EditorBody orchestrates (each independently
+// unit-tested at its pure core); the shell threads shared draft/ref/replaceDraft
+// state across their boundaries.
+import { usePublishedPerspective } from './use-published-perspective';
+import { useSaveMode } from './use-save-mode';
+import { useDiscardController } from './use-discard-controller';
+import { usePublishController, publishGate } from './use-publish-controller';
+import { useFieldFocus } from './use-field-focus';
+import { useCompareSelection } from './use-compare-selection';
+import { useLiveUrl } from './use-live-url';
+import { useEmbedInspectorHost } from './use-embed-inspector-host';
 export function DetailEditor({ projectId, collectionId, documentId, focusPath, }) {
     // AD-19: the edit shell is a portable surface over a CollectionViewSource, just
     // like the list. `DetailEditor` is the CMS entry point — it builds the CMS source
@@ -115,89 +120,24 @@ function EditorBody({ projectId, collection, doc, focusPath, }) {
     // Stable so the document-editor context value (EC-224) doesn't churn each render.
     const ref = useMemo(() => ({ collection: collection.id, id: doc.id }), [collection.id, doc.id]);
     const confirmTargets = useMemo(() => [{ collection: collection.id, id: doc.id }], [collection.id, doc.id]);
-    // EC-226: the draft/published VIEW perspective. Draft = the editable working
-    // draft; Published = the pinned published snapshot, rendered read-only. Only
-    // meaningful when the document is published.
-    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]);
-    // EC-316/EC-325 — "Discard changes" gating AND the Published-perspective
-    // snapshot share ONE query (AD-17: the one operations-backed cache,
-    // `use-document-versions.ts` — no raw `source.versioning.load` call
-    // anywhere in this component). Both need exactly the same
-    // `versions`/`publishedVersion` shape, so a second bespoke fetch on
-    // perspective switch would just re-read what this already has. Gated the
-    // same way the Discard-draft menu item always was: a publishing + versioned
-    // rail AND a published document (never a wasted fetch on e.g. the users
-    // rail or a never-published draft) — in every real `CollectionViewSource`
-    // `capabilities.publish`/`capabilities.versions` are set identically, so
-    // this is also exactly when the Published perspective is reachable.
-    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);
-    // The Published-perspective snapshot (EC-226), derived from the query
-    // above — no second fetch, and `derivePublishedSnapshot` guards a
-    // disabled/not-yet-resolved query by reading as 'loading' (never a false
-    // 'missing').
-    const publishedSnapshot = derivePublishedSnapshot(versionsView);
-    // The whole fieldset is read-only when viewing Published. The form/canvas
-    // render the pinned snapshot ONLY once it has loaded — never the draft, which
-    // must not be presented as published; until then the body shows a placeholder.
-    const viewReadOnly = perspective === 'published';
-    const viewDoc = viewReadOnly && publishedSnapshot.status === 'ready' ? publishedSnapshot.doc : draft;
-    const publishedPending = viewReadOnly && publishedSnapshot.status !== 'ready';
-    const discardCache = useOperationCache();
-    const [discardConfirm, setDiscardConfirm] = useState(false);
-    const [discardBusy, setDiscardBusy] = useState(false);
-    // One pure decision (tested in discard-draft.test.ts): hidden / disabled-
-    // with-reason / ready. Its semantic equality is the SAME comparator the
-    // Versions pane's publish gate uses, so the two never contradict (EC-298).
-    const discardStatus = discardDraftStatus({
-        canDiscard,
-        published,
-        viewReadOnly,
-        publishedSnapshot: publishedSnapshotDoc,
-        collection,
-        draft,
-    });
-    const discardDisabledReason = discardStatus === 'view-read-only'
-        ? translate('cms.editor.switchToDraftToDiscard')
-        : discardStatus === 'up-to-date'
-            ? translate('cms.editor.discardDraftUpToDateHint')
-            : discardStatus === 'loading'
-                ? translate('common.loading')
-                : undefined;
-    // Reuses the EC-298 restore machinery (the same op the Compare view's
-    // "Restore version" button calls) — never a parallel write path: reverting
-    // the draft IS restoring the published version's snapshot, whole-document.
-    async function handleDiscardDraft() {
-        if (publishedVersionNumber === undefined)
-            return;
-        setDiscardBusy(true);
-        try {
-            // EC-325: flush a dirty in-memory buffer FIRST, mirroring the Versions
-            // pane's/Compare view's own restores — `documents.restore` snapshots
-            // whatever is currently PERSISTED, so an edit still sitting in the
-            // autosave debounce window would otherwise be silently unrecoverable.
-            flushDirtyDraft({ dirty, save });
-            const restored = await source.versioning?.restore(ref, publishedVersionNumber, { kind: 'all' });
-            if (restored)
-                replaceDraft(restored);
-            await discardCache.invalidate(versionKey);
-        }
-        finally {
-            setDiscardBusy(false);
-            setDiscardConfirm(false);
-        }
+    // EC-224 — the working draft's two out-of-band mutators, shared across the
+    // controller hooks below and the document-editor context. `save` persists the
+    // current buffer; `replaceDraft` adopts a restored snapshot and bumps the nonce
+    // to REMOUNT the uncontrolled canvas from it (else the next edit clobbers the
+    // restore — the canvas builds its graph once at mount and lifts edits OUT).
+    function save() {
+        source.save(draft);
+    }
+    function replaceDraft(next) {
+        setDraft(next);
+        setRestoreNonce((n) => n + 1);
     }
+    // EC-226 / EC-316 / EC-325 — the Draft/Published VIEW perspective AND the pinned
+    // published snapshot, both derived from the ONE shared version-history query
+    // (AD-17: the single operations-backed cache — no raw `source.versioning.load`
+    // in this component). `canDiscard`/`versionKey`/`publishedVersionNumber`/
+    // `publishedSnapshotDoc` feed the Discard controller below off that same query.
+    const { perspective, setPerspective, published, canDiscard, versionKey, publishedVersionNumber, publishedSnapshotDoc, publishedSnapshot, viewReadOnly, viewDoc, publishedPending, } = usePublishedPerspective({ ref, source, canPublish, canVersions, draft });
     const dirty = useMemo(() => JSON.stringify(draft) !== JSON.stringify(doc), [draft, doc]);
     const schemaIssues = useMemo(() => source.validate(draft), [source, draft]);
     // EC-300/AD-16: composition embeds (hard references) whose target isn't published
@@ -210,38 +150,29 @@ function EditorBody({ projectId, collection, doc, focusPath, }) {
     const errorCount = schemaIssues.filter((i) => i.severity === 'error').length;
     const hasErrors = errorCount > 0;
     const hasUnpublishedRefs = referenceIssues.length > 0;
-    // --- Save mode (EC-225 autosave · EC-240 explicit) -------------------------
-    // A publishing rail AUTOSAVES: the draft persists 1s after the last edit and
-    // publish is the deliberate commit. A non-publishing rail (users, EC-240) has no
-    // publish step, so silent apply is the wrong default for authority data — it
-    // SAVES EXPLICITLY instead: edits stay in the draft until the Save button, and a
-    // navigation guard protects unsaved changes. (Role stays in `members`, applied
-    // on Save and enforced immediately — never behind a publish pointer.)
-    // Refs let the unmount flush read the latest values without re-subscribing.
-    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 (!explicitSaveRef.current && dirtyRef.current)
-            sourceRef.current.save(draftRef.current);
-    }, []);
+    // EC-225 autosave · EC-240 explicit save — the persistence discipline for this
+    // rail (a publishing rail autosaves + flushes on unmount; a non-publishing rail
+    // saves explicitly and relies on the `UnsavedChangesGuard` below for navigation).
+    const { explicitSave } = useSaveMode({ canPublish, dirty, draft, source });
+    // EC-316 / EC-325 — the "Discard changes" controller: the pure enablement
+    // decision plus the shared restore sequence (flush → restore the pinned published
+    // version whole → replaceDraft → invalidate). Destructured to the names the header
+    // menu + confirm dialog already use.
+    const { status: discardStatus, disabledReason: discardDisabledReason, confirmOpen: discardConfirm, setConfirmOpen: setDiscardConfirm, busy: discardBusy, discard: handleDiscardDraft, } = useDiscardController({
+        canDiscard,
+        published,
+        viewReadOnly,
+        publishedSnapshotDoc,
+        publishedVersionNumber,
+        versionKey,
+        collection,
+        draft,
+        source,
+        docRef: ref,
+        replaceDraft,
+        dirty,
+        save,
+    });
     const errorsByField = useMemo(() => {
         const map = new Map();
         for (const issue of issues) {
@@ -282,40 +213,28 @@ function EditorBody({ projectId, collection, doc, focusPath, }) {
     // not a field-row — it takes over its tab with the full page-builder canvas.
     // Convention: such a field lives on its own dedicated fieldset tab.
     const canvasField = tabFields.find(isBlocksField);
-    const [highlightedField, setHighlightedField] = useState(null);
-    // EC-285: the form-path inspector's active pane, controlled so a jump to a
-    // `sidebar`-group field can open the Details pane (where it renders). Undefined
-    // = uncontrolled (the sidebar defaults to its first pane).
-    const [inspectorPaneId, setInspectorPaneId] = useState();
-    // 0.0.41: the selected rich-text component embed, if any — a `componentEmbed` node
-    // selection swaps the inspector sidebar for the embed's prop form. Fed by the
-    // rich-text field through the EmbedInspector context; `clearActiveEmbed` keys on the
-    // node id so a fast A→B reselect can't let A's deselect wipe B (selection race).
-    const [activeEmbed, setActiveEmbed] = useState(null);
-    const embedInspectorApi = useMemo(() => ({
-        setActiveEmbed: (payload) => setActiveEmbed(payload),
-        clearActiveEmbed: (nodeId) => setActiveEmbed((prev) => (prev?.nodeId === nodeId ? null : prev)),
-    }), []);
-    // EC-298: the open version comparison. The Compare tab is STICKY — opening it
-    // sets the selection and focuses the tab; tabbing to the real fields keeps it
-    // open (the selection persists) so an editor can flip between diff and fields;
-    // only its ✕ closes it. `activeTab === COMPARE_TAB` is when the diff is visible.
-    const [compare, setCompare] = useState(null);
-    const startCompare = useCallback((base) => {
-        setCompare({ base, target: 'draft' });
-        setActiveTab(COMPARE_TAB);
-        setInspectorPaneId('versions');
-    }, []);
-    const setCompareBase = useCallback((base) => {
-        setCompare((c) => (c ? { ...c, base } : { base, target: 'draft' }));
-    }, []);
-    const setCompareTarget = useCallback((target) => {
-        setCompare((c) => (c ? { ...c, target } : c));
-    }, []);
-    const exitCompare = useCallback(() => {
-        setCompare(null);
-        setActiveTab((prev) => (prev === COMPARE_TAB ? tabs[0] : prev));
-    }, [tabs]);
+    // EC-172 / EC-283 — the field-focus/highlight controller (jump-to-field from the
+    // reference deep-link `focusPath` and the Issues pane). Owns the highlight + the
+    // controlled inspector-pane state and the scroll/clear timers.
+    const { highlightedField, inspectorPaneId, setInspectorPaneId, focusField } = useFieldFocus({
+        collection,
+        source,
+        focusPath,
+        setActiveTab,
+    });
+    // 0.0.41 — the selection-driven embed-inspector host: a rich-text `componentEmbed`
+    // selection swaps the inspector sidebar for the embed's prop form (the `api` is fed
+    // to the rich-text field through the EmbedInspector context).
+    const { activeEmbed, embedInspectorApi } = useEmbedInspectorHost();
+    // EC-298 — the sticky version-compare selection. Opening it focuses the Compare tab
+    // + the Versions pane; tabbing to the real fields keeps it open (only its ✕ closes
+    // it). `activeTab === COMPARE_TAB` is when the diff is visible.
+    const { compare, startCompare, setCompareBase, setCompareTarget, exitCompare } = useCompareSelection({
+        tabs,
+        compareTab: COMPARE_TAB,
+        setActiveTab,
+        setInspectorPaneId,
+    });
     // A content tab (schema tab or References). Selecting one leaves the Compare
     // view VISIBLE-wise but keeps the comparison open (sticky) — the diff is one
     // click away on its still-present tab chip.
@@ -333,49 +252,6 @@ function EditorBody({ projectId, collection, doc, focusPath, }) {
         const titleCase = tab !== REFERENCES_TAB && declaredLabel === undefined;
         return (_jsx("button", { type: "button", "aria-pressed": active, onClick: () => setActiveTab(tab), className: cn('rounded-md px-2.5 py-1 text-xs font-medium transition-colors', titleCase && 'capitalize', active ? 'bg-accent text-accent-foreground' : 'text-muted-foreground hover:bg-muted'), children: display }, tab));
     };
-    // Focus a field by name: switch to its tab (and locale, when given), scroll the
-    // control into view, and ring-highlight it. Shared by the reference deep-link
-    // (`focusPath`, EC-172) and the Issues pane's jump-to-field (EC-283).
-    const focusTimersRef = useRef([]);
-    const focusField = useCallback((fieldName, localeHint) => {
-        const field = collection.fields.find((f) => f.name === fieldName);
-        if (!field)
-            return;
-        // EC-285: a `sidebar`-group field renders in the Details inspector pane, not
-        // a content tab — open that pane instead of switching tabs.
-        if (field.form?.group === SIDEBAR_FIELD_GROUP) {
-            setInspectorPaneId('details');
-        }
-        else {
-            const fieldTabs = tabOrder(collection.form);
-            setActiveTab(field.form?.tab ?? fieldTabs[0] ?? 'main');
-        }
-        if (localeHint !== undefined && source.localeConfig.locales.includes(localeHint)) {
-            setStudioLocale(localeHint);
-        }
-        setHighlightedField(field.name);
-        // Clear any timers from a prior jump so back-to-back jumps don't fight.
-        focusTimersRef.current.forEach((t) => window.clearTimeout(t));
-        const scrollTimer = window.setTimeout(() => {
-            // Some controls (relation/asset pickers) don't render the input id —
-            // the field label (`htmlFor`) is always present.
-            const control = document.getElementById(`f-${field.name}`) ??
-                document.querySelector(`label[for="${CSS.escape(`f-${field.name}`)}"]`);
-            control?.scrollIntoView({ block: 'center', behavior: 'smooth' });
-        }, 60);
-        const clearTimer = window.setTimeout(() => setHighlightedField(null), 3200);
-        focusTimersRef.current = [scrollTimer, clearTimer];
-    }, [collection, source.localeConfig]);
-    useEffect(() => () => focusTimersRef.current.forEach((t) => window.clearTimeout(t)), []);
-    // Reference deep links (EC-172): `?field=<index path>` pinpoints the exact field.
-    useEffect(() => {
-        if (!focusPath)
-            return;
-        const parsed = parseDocumentFieldPath(focusPath);
-        if (!parsed)
-            return;
-        focusField(parsed.field, parsed.locale);
-    }, [focusPath, focusField]);
     function getValue(field) {
         // EC-226: read from the active VIEW (the draft, or the pinned published
         // snapshot when viewing Published) — never directly from `draft`.
@@ -437,20 +313,6 @@ function EditorBody({ projectId, collection, doc, focusPath, }) {
             : null;
         return (_jsx(Field, { className: cn('rounded-md transition-shadow', highlightedField === field.name && 'bg-primary/5 p-2 ring-2 ring-primary/70'), label: _jsxs(Row, { gap: "2", children: [_jsx("span", { children: fieldLabel(field) }), field.validation?.required ? _jsx("span", { className: "text-destructive", children: "*" }) : null, localized ? _jsx(Badge, { variant: "outline", children: locale }) : null, fieldLevelReadOnly ? (_jsxs(Badge, { variant: "outline", children: [_jsx(Lock, { className: "size-3" }), " ", translate('cms.editor.readOnlyBadge')] })) : null, _jsx(Spacer, {}), connection && !fieldReadOnly ? (_jsx(FieldConnectionControl, { connection: connection, fieldName: field.name, locale: locale, onFillFromBase: () => setDraft((d) => fillFieldFromBase(collection, d, field.name, locale, source.localeConfig)), onResetToBase: () => setDraft((d) => resetFieldToBase(collection, d, field.name, locale)) })) : null] }), htmlFor: `f-${field.name}`, hint: localizedLabel(field.form?.description) || undefined, error: fieldReadOnly ? undefined : errorsByField.get(field.name), children: _jsx(FieldControl, { id: `f-${field.name}`, field: field, value: getValue(field), onChange: (v) => setValue(field, v), readOnly: fieldReadOnly }) }, field.name));
     }
-    function save() {
-        source.save(draft);
-    }
-    // EC-224: a version restore swaps the working draft for an older snapshot; the
-    // open editor adopts it so the form/canvas re-render from the restored content
-    // (the operation already persisted it, so it lands clean/non-dirty).
-    function replaceDraft(next) {
-        setDraft(next);
-        // The canvas editor is uncontrolled after mount (it builds its graph once and
-        // lifts edits OUT). A restore replaces the draft from outside, so bump the
-        // nonce to REMOUNT the canvas from the restored value — otherwise it keeps the
-        // pre-restore tree and the next edit would clobber the restore.
-        setRestoreNonce((n) => n + 1);
-    }
     // The frame-owned `Versions` pane (EC-224) — appended after any view-supplied
     // pane (the canvas's `Properties`). One instance feeds both the form view's
     // sidebar and the canvas view's sidebar.
@@ -511,75 +373,20 @@ function EditorBody({ projectId, collection, doc, focusPath, }) {
         ...(canVersions ? [versionsPane] : []),
         issuesPane,
     ];
-    // EC-268: the Publish button is its own indicator — pending while the publish
-    // round-trips, a brief success, and an error toast if it rejects at transport.
-    const [publishState, setPublishState] = useState('idle');
-    // EC-300/AD-16: confirm-through guard when the page embeds unpublished reusables.
-    const [publishConfirm, setPublishConfirm] = useState(false);
-    // 0.0.39: the split-button "Publish & close" intent — remembered across the
-    // confirm-through dialog so a successful publish returns to the list, matching the
-    // retired EC-316 "Save & close". Cleared on cancel or a publish failure (no navigate).
-    const closeAfterPublishRef = useRef(false);
-    // Gate publish on the confirm-through dialog when there are unpublished hard
-    // references (they'd render empty on the live site); schema errors already
-    // disable the button, so they never reach here.
-    function handlePublish() {
-        if (hasUnpublishedRefs) {
-            setPublishConfirm(true);
-            return;
-        }
-        void doPublish();
-    }
-    // 0.0.39: publish, then return to the rail's list (rail-owned `listPath`, AD-19),
-    // the same navigation the removed "Save & close" did. Shares handlePublish's exact
-    // gating + confirm-through; the close happens only after the publish resolves.
-    function handlePublishAndClose() {
-        closeAfterPublishRef.current = true;
-        handlePublish();
-    }
-    async function doPublish() {
-        // EC-273: clean conditionally-hidden values from the draft AT PUBLISH TIME.
-        // While editing, the draft keeps them so an accidental hide (e.g. flipping a
-        // link's type) is recoverable; publishing is the intentional moment we commit
-        // the cleanup — into the draft AND the snapshot, so both go clean together (the
-        // reference index updates off the saved draft, so a now-unlinked page becomes
-        // deletable once the change is published). Also captures the latest edit in case
-        // Publish is clicked inside the autosave debounce window; the serial persister
-        // runs the upsert before the publish so the snapshot is exactly this draft (EC-225).
-        const cleaned = clearHiddenValues(collection, draft);
-        if (cleaned !== draft)
-            setDraft(cleaned);
-        if (cleaned !== draft || dirty)
-            source.save(cleaned);
-        // Publish snapshots the draft as a version and pins it (EC-224). The live
-        // row stays a continuous draft — published-ness is the version pointer
-        // (`source.publishing.isPublished`). Pre-gated by `disabled={hasErrors}`; the optimistic
-        // flip reconciles against the backend (EC-225), so a logical rejection the
-        // gate doesn't cover (schema divergence) self-corrects the badge. A hard
-        // failure (transport) rejects the flush — surface it loudly (EC-268).
-        setPublishState('pending');
-        try {
-            await source.publishing?.publish(ref);
-            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'));
-        }
-    }
+    // EC-268 / EC-300 / 0.0.39 — the publish controller: the publish indicator state,
+    // the EC-300 confirm-through guard (unpublished hard refs would render empty on
+    // the live site), and the "Publish & close" navigation. Handlers are named to
+    // match the header split button + the confirm-through dialog below.
+    const { publishState, publishConfirm, handlePublish, handlePublishAndClose, confirmPublish, cancelPublishConfirm, } = usePublishController({
+        source,
+        docRef: ref,
+        collection,
+        projectId,
+        draft,
+        setDraft,
+        dirty,
+        hasUnpublishedRefs,
+    });
     function handleConfirmedAction() {
         if (confirmAction === 'unpublish') {
             setConfirmAction(null);
@@ -628,41 +435,13 @@ function EditorBody({ projectId, collection, doc, focusPath, }) {
         ];
     }, [singleton, collection, draft, locale, source.localeConfig, source.listPath, doc.id, projectId]);
     useSetBreadcrumb(breadcrumbItems);
-    // EC-205/EC-216: the LIVE URL derives strictly from PUBLISHED data — the
-    // document's pinned published snapshot and its published ancestors — never the
-    // draft (an unpublished slug/parent edit must not leak into the live URL). The
-    // pool is exactly what the live site serves, so a published doc resolves to the
-    // URL visitors actually get; `undefined` until the doc is published (and the
-    // pool has loaded). The collection being routable gates the disabled hint below.
-    const publishedDocs = usePublishedDocuments(source.projectId, collection.id);
-    const liveUrl = useMemo(() => {
-        const published = publishedDocs.byId.get(doc.id);
-        if (!published)
-            return undefined;
-        return urlForDocument({
-            routes: resolveDeploymentRoutes(),
-            frontendUrl: resolveDeploymentFrontendUrl(),
-            localeConfig: source.localeConfig,
-        }, collection, published, { siblings: [...publishedDocs.byId.values()], locale });
-    }, [publishedDocs, collection, doc.id, locale, source.localeConfig]);
-    // 0.0.42 (round 3): the composed URL row lives in the header under the title; its
-    // LEAF segment carries the open-live affordance, mirroring the retired "View live"
-    // button's gating EXACTLY. `href` present (published + frontendUrl) → the leaf opens
-    // the live page in a new tab; absent → a muted, non-interactive icon with the same
-    // reason tooltip (loading / publish-first / set-frontendUrl). The draft-derived path
-    // itself still updates as you type — only the OPEN-live action is published-gated, so
-    // the draft/live distinction is preserved.
-    const headerLive = routableCollection
-        ? liveUrl?.href
-            ? { href: liveUrl.href, title: translate('cms.editor.openLiveUrl', { path: liveUrl.path }) }
-            : {
-                title: publishedDocs.status === 'loading'
-                    ? translate('cms.editor.loadingLiveUrl')
-                    : !published
-                        ? translate('cms.editor.publishToViewLive')
-                        : translate('cms.editor.setFrontendUrlHint'),
-            }
-        : undefined;
+    // EC-205/EC-216 — the header composed-URL row's live-link descriptor. Derives
+    // strictly from PUBLISHED data (the pinned snapshot + published ancestors), never
+    // the draft, so an unpublished slug/parent edit can't leak into the live URL; the
+    // draft-derived path itself (rendered by `DocumentUrlPath`) still updates as you
+    // type — only the OPEN-live action is published-gated. `undefined` when the
+    // collection is non-routable.
+    const { headerLive } = useLiveUrl({ source, collection, doc, locale, published, routableCollection });
     // EC-240: hide the tab bar when there is nothing to navigate — a single content
     // tab with no References/Compare (the users rail). When framework tabs ARE
     // present we KEEP the content tab(s) so there is always a way back to the form;
@@ -672,14 +451,15 @@ function EditorBody({ projectId, collection, doc, focusPath, }) {
     const hasFrameworkTabs = showReferences || compare !== null;
     const showContentTabs = tabs.length > 1 || hasFrameworkTabs;
     const showLensRow = showContentTabs || canLocales || canPublish;
-    // 0.0.39 split Publish button — the shared gating/label, computed once so the
-    // primary "Publish" and the "Publish & close" item can never diverge.
-    const publishDisabled = hasErrors || viewReadOnly || publishState === 'pending';
-    const publishTitle = viewReadOnly
-        ? translate('cms.editor.switchToDraftToPublish')
-        : hasErrors
-            ? translate(errorCount === 1 ? 'cms.editor.fixIssuesToPublish.one' : 'cms.editor.fixIssuesToPublish.other', { count: errorCount })
-            : undefined;
+    // 0.0.39 split Publish button — the shared gate (disabled + title), computed once
+    // (pure `publishGate`) so the primary "Publish" and the "Publish & close" item can
+    // never diverge.
+    const { disabled: publishDisabled, title: publishTitle } = publishGate({
+        hasErrors,
+        viewReadOnly,
+        publishState,
+        errorCount,
+    });
     const publishButtonLabel = publishState === 'pending' ? (_jsxs(_Fragment, { children: [_jsx(Loader2, { className: "animate-spin" }), " ", translate('cms.editor.publishing')] })) : publishState === 'success' ? (_jsxs(_Fragment, { children: [_jsx(CircleCheck, {}), " ", translate('cms.editor.publishedState')] })) : (_jsxs(_Fragment, { children: [_jsx(Eye, {}), " ", translate('cms.editor.publish')] }));
     // Offer "Publish & close" only when there IS a list to return to — the same gate
     // the removed EC-316 "Save & close" used (never a singleton or a list-less rail).
@@ -738,18 +518,10 @@ function EditorBody({ projectId, collection, doc, focusPath, }) {
                             if (!open)
                                 setConfirmAction(null);
                         }, onConfirm: handleConfirmedAction })) : null, _jsx(Dialog, { open: discardConfirm, onOpenChange: (open) => { if (!open)
-                            setDiscardConfirm(false); }, children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: translate('cms.editor.discardDraftTitle') }), _jsx(DialogDescription, { children: translate('cms.editor.discardDraftDescription') })] }), _jsxs(DialogFooter, { className: "mt-4", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => setDiscardConfirm(false), disabled: discardBusy, children: translate('common.cancel') }), _jsx(Button, { variant: "destructive", size: "sm", "data-testid": "discard-draft-confirm", disabled: discardBusy, onClick: () => void handleDiscardDraft(), children: discardBusy ? (_jsxs(_Fragment, { children: [_jsx(Loader2, { className: "animate-spin" }), " ", translate('cms.editor.discardingDraft')] })) : (_jsxs(_Fragment, { children: [_jsx(RotateCcw, {}), " ", translate('cms.editor.discardDraftConfirm')] })) })] })] }) }), _jsx(Dialog, { open: publishConfirm, onOpenChange: (open) => { if (!open) {
-                            setPublishConfirm(false);
-                            closeAfterPublishRef.current = false;
-                        } }, children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: translate('cms.editor.publishUnpublishedRefsTitle') }), _jsx(DialogDescription, { children: translate('cms.editor.publishUnpublishedRefsDescription') })] }), _jsxs(Stack, { gap: "1", children: [referenceIssues.map((issue, i) => (_jsxs(Text, { size: "xs", tone: "muted", children: ["\u2022 ", issue.message] }, `${issue.meta?.id ?? i}`))), schemaIssues.length > 0 ? (_jsx(Text, { size: "xs", tone: "muted", className: "mt-1", children: translate(schemaIssues.length === 1
+                            setDiscardConfirm(false); }, children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: translate('cms.editor.discardDraftTitle') }), _jsx(DialogDescription, { children: translate('cms.editor.discardDraftDescription') })] }), _jsxs(DialogFooter, { className: "mt-4", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => setDiscardConfirm(false), disabled: discardBusy, children: translate('common.cancel') }), _jsx(Button, { variant: "destructive", size: "sm", "data-testid": "discard-draft-confirm", disabled: discardBusy, onClick: () => void handleDiscardDraft(), children: discardBusy ? (_jsxs(_Fragment, { children: [_jsx(Loader2, { className: "animate-spin" }), " ", translate('cms.editor.discardingDraft')] })) : (_jsxs(_Fragment, { children: [_jsx(RotateCcw, {}), " ", translate('cms.editor.discardDraftConfirm')] })) })] })] }) }), _jsx(Dialog, { open: publishConfirm, onOpenChange: (open) => { if (!open)
+                            cancelPublishConfirm(); }, children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: translate('cms.editor.publishUnpublishedRefsTitle') }), _jsx(DialogDescription, { children: translate('cms.editor.publishUnpublishedRefsDescription') })] }), _jsxs(Stack, { gap: "1", children: [referenceIssues.map((issue, i) => (_jsxs(Text, { size: "xs", tone: "muted", children: ["\u2022 ", issue.message] }, `${issue.meta?.id ?? i}`))), schemaIssues.length > 0 ? (_jsx(Text, { size: "xs", tone: "muted", className: "mt-1", children: translate(schemaIssues.length === 1
                                                 ? 'cms.editor.publishAlsoHasIssues.one'
-                                                : 'cms.editor.publishAlsoHasIssues.other', { count: schemaIssues.length }) })) : null] }), _jsxs(DialogFooter, { className: "mt-4", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => {
-                                                setPublishConfirm(false);
-                                                closeAfterPublishRef.current = false;
-                                            }, children: translate('common.cancel') }), _jsx(Button, { size: "sm", "data-testid": "publish-anyway", onClick: () => {
-                                                setPublishConfirm(false);
-                                                void doPublish();
-                                            }, children: translate('cms.editor.publishAnyway') })] })] }) })] }) }) }));
+                                                : 'cms.editor.publishAlsoHasIssues.other', { count: schemaIssues.length }) })) : null] }), _jsxs(DialogFooter, { className: "mt-4", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: cancelPublishConfirm, children: translate('common.cancel') }), _jsx(Button, { size: "sm", "data-testid": "publish-anyway", onClick: confirmPublish, children: translate('cms.editor.publishAnyway') })] })] }) })] }) }) }));
 }
 /**
  * EC-300/AD-16 — errors for composition embeds (hard references) whose target isn't