@phis/ui 0.1.0 → 0.2.1

package/plugins/runtime-modules/builder/draft-command-controller.js

@@ -1,22 +1,20 @@
 "use client";
 import { useState } from "react";
-import { useRouter } from "next/navigation";
-import { App } from "antd";
-import { PhiCmsRegionType } from "../../../constants/phi-cms";
+import { usePhiConfirmDialog } from "../../../components/controls/phi-confirm-dialog";
 import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../types/signals";
 import { usePhiSignalDispatcher } from "../../../components/runtime/runtime-signal-bus";
 import { usePhiApplicationFeedback } from "../../../components/runtime/use-phi-application-feedback";
 import { createPhiBuilderControllerAddress } from "./controller/address";
-import { createPhiDefaultAreaRuntimeModuleIds } from "./runtime-module-defaults";
+import { createPhiDefaultAreaRuntimeModuleIds } from "../area-module-defaults";
 import { getPhiBuilderDefaultRegionDraft } from "./region-defaults";
 import { getPhiBuilderRegionDraftKey, PHI_BUILDER_PAGE_REGION_KEYS, } from "./region-keys";
 import { resolvePhiBuilderCmsStoragePath } from "../../../helpers/cms-paths";
 import { resolvePhiBuilderActivePageCatalog, resolvePhiBuilderActivePageKey, resolvePhiBuilderPagePresetSource, } from "../../../helpers/cms-page-catalog";
-import { buildPhiBuilderLiveHref, clearPhiDeveloperBuilderDraftAllocation, createPhiDeveloperBuilderInitialPageDrafts, deleteCmsDraft, discardPhiDeveloperBuilderModulesDraft, getPhiDeveloperBuilderModulesDraftAllocation, savePhiDeveloperBuilderModulesDraft, publishPhiDeveloperBuilderModulesDraft, previewPhiDeveloperBuilderDraft, publishPhiDeveloperBuilderDraft, savePhiDeveloperBuilderDraft, } from "./persistence";
+import { deleteCmsDraft } from "../../../helpers/cms-draft-delete";
+import { buildPhiBuilderLiveHref, clearPhiDeveloperBuilderDraftAllocation, createPhiDeveloperBuilderInitialPageDrafts, discardPhiDeveloperBuilderModulesDraft, getPhiDeveloperBuilderModulesDraftAllocation, savePhiDeveloperBuilderModulesDraft, publishPhiDeveloperBuilderModulesDraft, previewPhiDeveloperBuilderDraft, publishPhiDeveloperBuilderDraft, savePhiDeveloperBuilderDraft, } from "./persistence";
 import { clearPhiBuilderNavigationDraft, getPhiBuilderNavigationDraftSnapshot, updatePhiBuilderNavigationDraft, restorePhiBuilderNavigationDraft, setPhiBuilderNavigationDraft, } from "./navigation-store";
 import { deletePhiBuilderNavigationDraft, loadPhiBuilderNavigationDraft, loadPhiBuilderNavigationScope, publishPhiBuilderNavigationDraft, savePhiBuilderNavigationDraft, } from "./navigation-persistence";
-import { builderWorkspaceStore, splitWorkspacePatch, getPhiDeveloperRegionDraftsSnapshot, mergePhiDeveloperDeletedPageDrafts, mergePhiDeveloperRegionDrafts, restorePhiDeveloperBuilderAreaMeta, restorePhiDeveloperRegionDrafts, setPhiDeveloperBuilderAreaRootRoute, } from "./developer-workspace-store";
-import { getBuilderRegionKey } from "./region-controller";
+import { builderWorkspaceStore, splitWorkspacePatch, getPhiDeveloperRegionDraftsSnapshot, mergePhiDeveloperDeletedPageDrafts, mergePhiDeveloperRegionDrafts, restorePhiDeveloperBuilderAreaMeta, restorePhiDeveloperRegionDrafts, setPhiDeveloperBuilderAreaRootRoute, setPhiDeveloperRegionDraftsWithHistory, } from "./developer-workspace-store";
 import { findPhiBuilderNavigationSurface } from "../../../helpers/cms-navigation-catalog";
 import { createPhiBuilderHistoryContext, phiBuilderHistory, } from "./history";
 import { usePhiBuilderModuleMetas } from "./plugin-meta-store";
@@ -24,9 +22,14 @@ import { clearPhiBuilderModuleAreasDirty } from "./runtime-module-selection";
 import { phiWorkspaceCatalogStore } from "../../../components/workspace/catalog-store";
 import { applyPhiBuilderNavigationFolderTargets, refreshPhiBuilderNavigationFolderAddresses, } from "./navigation-folder-address";
 import { createPhiBuilderNavigationPathContext } from "./navigation-path-context";
-export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultArea, effectiveArea, effectiveNavKey, effectivePageKey, pathname, shellPresetDraftsByArea, state, }) {
-    const { modal } = App.useApp();
-    const router = useRouter();
+export function usePhiBuilderDraftCommandController({ defaultArea, effectiveArea, effectiveNavKey, effectivePageKey, pathname, reportSaved, shellPresetDraftsByArea, state, }) {
+    /*
+     * Every one of these is a command from a toolbar somewhere else, so there is nothing on screen to
+     * hang a Popconfirm on. Drawn as a Dialog by this Controller rather than asked of Ant Design's
+     * `App`, whose provider would otherwise sit in every page's first load for the sake of questions
+     * only the Builder asks.
+     */
+    const { confirm, confirmDialog } = usePhiConfirmDialog();
     const { showMessage } = usePhiApplicationFeedback();
     const dispatchSignal = usePhiSignalDispatcher();
     const builderModuleMetas = usePhiBuilderModuleMetas(effectiveArea);
@@ -51,7 +54,7 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
         return withCurrentFolderAddresses(scope.navigation);
     }
     /*
-     * A save may have carried folder targets into other Navigations of the Area (TODOS.md, "Folder
+     * A save may have carried folder targets into other Navigations of the Area (phis-server REFERENCES.md, "Folder
      * addresses"). Their Drafts on the server moved; one open here takes the same targets and the new base
      * revision, one that is not is loaded, and neither records history -- Undo stays per Navigation.
      */
@@ -82,36 +85,13 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
         });
     }
     /*
-     * A folder address is resolved when the Draft is saved or published (TODOS.md, "Folder addresses"): a
+     * A folder address is resolved when the Draft is saved or published (phis-server REFERENCES.md, "Folder addresses"): a
      * Page moved in /pages since the last Navigation edit has moved the folder its container stands for.
      */
     function withCurrentFolderAddresses(navigation) {
         const items = refreshPhiBuilderNavigationFolderAddresses(navigation.items, createPhiBuilderNavigationPathContext(state).resolveLinkPath);
         return items === navigation.items ? navigation : { ...navigation, items };
     }
-    function emitDraftStatus(status, revisionId) {
-        dispatchSignal({
-            scope: "area",
-            channel: "draftStatus",
-            action: "change",
-            value: {
-                status,
-                revisionId,
-                ...(commandWorkspace === "navigation"
-                    ? { navKey: effectiveNavKey }
-                    : {
-                        area: effectiveArea,
-                        pageKey: effectivePageKey,
-                    }),
-                regionKey: getBuilderRegionKey(PhiCmsRegionType.HeaderMain),
-            },
-            valueType: "json",
-            valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.revisionsDraftStatus,
-            sender: createPhiBuilderControllerAddress(),
-            receiver: "broadcast",
-            timestamp: Date.now(),
-        });
-    }
     /**
      * The Areas a site-wide Modules command has to reach: every Area with unsaved selection edits,
      * plus every Area already holding an open Module draft allocation -- a draft saved earlier in the
@@ -176,7 +156,7 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
                 });
                 lastRevisionId = modulesResult.revisionId;
             }
-            emitDraftStatus("draft", lastRevisionId);
+            reportSaved("draft", lastRevisionId);
             showMessage({
                 level: "success",
                 content: areas.length === 1
@@ -198,7 +178,7 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
                     pageKey: effectivePageKey,
                 },
             });
-        emitDraftStatus("draft", result.revisionId);
+        reportSaved("draft", result.revisionId);
         if (!("savedScopes" in result)) {
             const navigationDraft = await resolveCurrentNavigationDraft();
             setPhiBuilderNavigationDraft(effectiveNavKey, {
@@ -228,7 +208,7 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
                 });
             }
             clearPhiBuilderModuleAreasDirty(defaultArea);
-            emitDraftStatus("published", null);
+            reportSaved("published", null);
             showMessage({
                 level: "success",
                 content: areas.length === 1
@@ -252,7 +232,7 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
                 },
             });
         }
-        emitDraftStatus("published", null);
+        reportSaved("published", null);
         showMessage({ level: "success", content: "Published CMS draft." });
     }
     async function runPreviewCommand(workspaceKind) {
@@ -291,120 +271,45 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
             buildPhiBuilderLiveHref(previewScope.area, previewScope.pageKey, currentPageTree, workspaceKind);
         window.open(href, "_blank", "noopener,noreferrer");
     }
-    function confirmResetShell() {
-        const presetDrafts = shellPresetDraftsByArea[effectiveArea] ?? null;
-        if (!presetDrafts) {
-            showMessage({ level: "warning", content: "No shell preset found for the current area." });
-            return;
-        }
-        modal.confirm({
-            title: "Discard shell draft?",
-            content: "This discards the unpublished shell draft for this Area. What is published stays live.",
-            okText: "Discard draft",
-            okButtonProps: { danger: true },
-            cancelText: "Cancel",
-            centered: true,
-            onOk: async () => {
-                setActiveDraftAction("reset");
-                try {
-                    await deleteCmsDraft("/api/site/cms/area", {
-                        area: effectiveArea,
-                        ownerModuleId: state.areaPresetSourcesByArea[effectiveArea]?.ownerModuleId,
-                        presetKey: state.areaPresetSourcesByArea[effectiveArea]?.presetKey,
-                    });
-                    clearPhiDeveloperBuilderDraftAllocation({
-                        area: effectiveArea,
-                        pageKey: effectivePageKey,
-                        workspaceKind: "structure",
-                    });
-                    mergePhiDeveloperRegionDrafts(presetDrafts);
-                    phiBuilderHistory.clear(createPhiBuilderHistoryContext({
-                        workspace: "structure",
-                        area: effectiveArea,
-                    }));
-                    /*
-                     * What the Shell said about itself went with the draft, and only the server knows what is
-                     * left.
-                     *
-                     * The Region tree above can be put back from the preset this client already holds; the root
-                     * route and the SEO answers cannot -- what stands after the override is deleted is whatever
-                     * was published, and that is a value nobody here has. So the session's answers are dropped
-                     * and the workspace is asked for again: `/pages` reads the stored root route to decide which
-                     * Pages it may open, and leaving the deleted draft's answer in place would have it offering
-                     * a `/` that no longer exists.
-                     */
-                    setPhiDeveloperBuilderAreaRootRoute(effectiveArea, undefined);
-                    restorePhiDeveloperBuilderAreaMeta(effectiveArea, undefined);
-                    router.refresh();
-                    showMessage({ level: "success", content: "Reset shell draft." });
-                }
-                catch (error) {
-                    showMessage({ level: "error", content: error instanceof Error ? error.message : "Shell reset failed." });
-                    throw error;
-                }
-                finally {
-                    setActiveDraftAction(null);
-                }
-            },
-        });
-    }
     /**
-     * Gives the Area back to the Module preset by removing the Site's own shell entirely.
+     * Puts the Module's shell back into the draft, as an edit rather than as an erasure.
+     *
+     * It used to delete the draft on the server and clear the history behind it, which made "start over"
+     * the one gesture in this workspace that could not be taken back -- and it promised the wrong thing
+     * twice over: the dialog said what is published stays live while the editor came back showing the
+     * preset, two different answers that only agreed while nobody had published.
+     *
+     * Nothing is deleted now. The preset's Regions are written into the draft as one recorded step, so
+     * undo returns what was there, the previous draft stays in the revision history, and what is live
+     * stays live until somebody publishes. That also makes this the only way back to where a Module
+     * started: revisions know the states this Site has been in, and if it was customised before it was
+     * first published, the Module's own starting point was never one of them.
      *
-     * The reset above discards a draft and leaves what is published standing, which is right when an edit
-     * went wrong and wrong when the shell itself should no longer exist: an Area published once kept its
-     * snapshot forever, and every later preset improvement stopped at it, invisibly, because the Area
-     * still rendered. This is the way back, and it is a separate command because it also takes the live
-     * chrome with it.
+     * The Area's root route and its SEO answers are deliberately untouched. They say where the Area lives
+     * and how it describes itself, which is not what its shell looks like; the old command dropped them
+     * only because it had deleted the draft that held them.
      */
-    function confirmRestoreShellPreset() {
+    function confirmResetShell() {
         const presetDrafts = shellPresetDraftsByArea[effectiveArea] ?? null;
-        const sourcePreset = state.areaPresetSourcesByArea[effectiveArea] ?? null;
-        if (!presetDrafts || !sourcePreset) {
+        if (!presetDrafts) {
             showMessage({ level: "warning", content: "No shell preset found for the current area." });
             return;
         }
-        modal.confirm({
-            title: "Restore the Module preset?",
-            content: "This deletes this Area's own shell, drafts and published alike, and puts the Module preset back. " +
-                "It cannot be undone.",
-            okText: "Delete shell and restore",
-            okButtonProps: { danger: true },
-            cancelText: "Cancel",
-            centered: true,
-            onOk: async () => {
-                setActiveDraftAction("restorePreset");
-                try {
-                    await deleteCmsDraft("/api/site/cms/area/override", {
-                        area: effectiveArea,
-                        ownerModuleId: sourcePreset.ownerModuleId,
-                        presetKey: sourcePreset.presetKey,
-                    });
-                    clearPhiDeveloperBuilderDraftAllocation({
-                        area: effectiveArea,
-                        pageKey: effectivePageKey,
-                        workspaceKind: "structure",
-                    });
-                    mergePhiDeveloperRegionDrafts(presetDrafts);
-                    phiBuilderHistory.clear(createPhiBuilderHistoryContext({
+        confirm({
+            title: "Start from the Module's shell?",
+            content: "This puts the Module's shell into the draft, replacing what the editor is showing. " +
+                "Nothing is deleted -- undo takes it back, and what is published stays live until you publish.",
+            confirmLabel: "Start from the preset",
+            cancelLabel: "Cancel",
+            onConfirm: () => {
+                setPhiDeveloperRegionDraftsWithHistory(presetDrafts, {
+                    historyContext: createPhiBuilderHistoryContext({
                         workspace: "structure",
                         area: effectiveArea,
-                    }));
-                    // What the deleted shell said about itself -- its root route, its SEO answers -- went with it,
-                    // and what stands now is the preset's own. Only the server knows that, so the session drops
-                    // its copies and asks again, exactly as the draft reset does.
-                    setPhiDeveloperBuilderAreaRootRoute(effectiveArea, undefined);
-                    restorePhiDeveloperBuilderAreaMeta(effectiveArea, undefined);
-                    router.refresh();
-                    showMessage({ level: "success", content: "Restored the Module preset." });
-                }
-                catch (error) {
-                    showMessage({ level: "error", content: error instanceof Error ? error.message : "Preset restore failed." });
-                    throw error;
-                }
-                finally {
-                    setActiveDraftAction(null);
-                }
+                    }),
+                    historyLabel: "Start from the Module's shell",
+                });
+                showMessage({ level: "success", content: "The Module's shell is in the draft." });
             },
         });
     }
@@ -426,14 +331,13 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
             showMessage({ level: "info", content: "No module selection changes to reset." });
             return;
         }
-        modal.confirm({
+        confirm({
             title: "Delete Module drafts?",
             content: "This removes the open DB Module drafts and restores the shared default selection for every touched area.",
-            okText: "Delete and reset",
-            okButtonProps: { danger: true },
-            cancelText: "Cancel",
-            centered: true,
-            onOk: async () => {
+            confirmLabel: "Delete and reset",
+            danger: true,
+            cancelLabel: "Cancel",
+            onConfirm: async () => {
                 setActiveDraftAction("reset");
                 try {
                     for (const area of areas) {
@@ -454,6 +358,7 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
                         workspace: "modules",
                         area: defaultArea,
                     }));
+                    reportSaved("published", null);
                     showMessage({ level: "success", content: "Reset Module drafts." });
                 }
                 catch (error) {
@@ -473,16 +378,15 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
             return draft ? [[draftKey, draft]] : [];
         }));
         const hasPreset = Object.keys(presetDrafts).length > 0;
-        modal.confirm({
+        confirm({
             title: hasPreset ? "Delete page override?" : "Delete page?",
             content: hasPreset
                 ? "This removes the current DB page override and restores the shared preset."
                 : "This prepares a delete draft. The live page returns 404 after the draft is published.",
-            okText: hasPreset ? "Delete and reset" : "Create delete draft",
-            okButtonProps: { danger: true },
-            cancelText: "Cancel",
-            centered: true,
-            onOk: async () => {
+            confirmLabel: hasPreset ? "Delete and reset" : "Create delete draft",
+            danger: true,
+            cancelLabel: "Cancel",
+            onConfirm: async () => {
                 setActiveDraftAction("reset");
                 try {
                     if (!hasPreset) {
@@ -517,12 +421,12 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
                                 pageKey: effectivePageKey,
                             },
                         });
-                        emitDraftStatus("draft", result.revisionId);
                         phiBuilderHistory.clear(createPhiBuilderHistoryContext({
                             workspace: "pages",
                             area: effectiveArea,
                             pageKey: effectivePageKey,
                         }));
+                        reportSaved("draft", result.revisionId);
                         showMessage({ level: "success", content: "Saved page delete draft." });
                         return;
                     }
@@ -561,6 +465,7 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
                         area: effectiveArea,
                         pageKey: effectivePageKey,
                     }));
+                    reportSaved("published", null);
                     showMessage({ level: "success", content: "Reset page draft." });
                 }
                 catch (error) {
@@ -574,14 +479,13 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
         });
     }
     function confirmResetNavigation() {
-        modal.confirm({
+        confirm({
             title: "Delete navigation draft?",
             content: "This removes the current navigation draft and restores the published navigation tree.",
-            okText: "Delete and reset",
-            okButtonProps: { danger: true },
-            cancelText: "Cancel",
-            centered: true,
-            onOk: async () => {
+            confirmLabel: "Delete and reset",
+            danger: true,
+            cancelLabel: "Cancel",
+            onConfirm: async () => {
                 setActiveDraftAction("reset");
                 try {
                     await deletePhiBuilderNavigationDraft(effectiveNavKey);
@@ -591,6 +495,7 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
                         area: effectiveArea,
                         navKey: effectiveNavKey,
                     }));
+                    reportSaved("published", null);
                     dispatchSignal({
                         scope: "area",
                         channel: "navigation",
@@ -645,13 +550,6 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
             runResetCommand(workspaceKind);
             return;
         }
-        if (command === "restorePreset") {
-            // Only the shell workspace owns an Area preset to restore; elsewhere the command is not offered.
-            if (workspaceKind === "structure") {
-                confirmRestoreShellPreset();
-            }
-            return;
-        }
         const historyContext = createPhiBuilderHistoryContext({
             workspace: workspaceKind,
             area: effectiveArea,
@@ -729,5 +627,5 @@ export function usePhiBuilderDraftCommandController({ commandWorkspace, defaultA
             setActiveDraftAction(null);
         });
     }
-    return { confirmResetPage, confirmResetModules, runBuilderCommand };
+    return { confirmResetPage, confirmResetModules, runBuilderCommand, confirmDialog };
 }

package/plugins/runtime-modules/builder/draft-status-controller.d.ts

@@ -0,0 +1,23 @@
+import type { PhiDeveloperBuilderArea, PhiDeveloperBuilderCommandWorkspace, PhiDeveloperBuilderWorkspaceState } from "./developer-workspace-types";
+/**
+ * The draft state of the workspace on screen, stated for the Core Draft Status Widget.
+ *
+ * What is stored is read here once per workspace target -- the Area shell, its Module selection, a
+ * Page, a Navigation -- and kept as the saved state; a save or a publish replaces it through
+ * `reportSaved`. `unsaved` is the history having moved since: the head of the workspace's undo history
+ * is remembered with every saved state, and any record, undo or redo that leaves a different head
+ * standing means what is on screen is in no stored revision. Undoing back to the saved head is saved
+ * again.
+ *
+ * Every change is broadcast; a Widget that mounts asks on `draftStatus`/`activate` and is answered
+ * alone.
+ */
+export declare function usePhiBuilderDraftStatusController({ commandWorkspace, effectiveArea, effectiveNavKey, effectivePageKey, state, }: {
+    commandWorkspace: PhiDeveloperBuilderCommandWorkspace;
+    effectiveArea: PhiDeveloperBuilderArea;
+    effectiveNavKey: string;
+    effectivePageKey: string;
+    state: PhiDeveloperBuilderWorkspaceState;
+}): {
+    reportSaved: (status: "draft" | "published", revisionId: number | null) => void;
+};

package/plugins/runtime-modules/builder/draft-status-controller.js

@@ -0,0 +1,173 @@
+"use client";
+import { useCallback, useEffect, useState } from "react";
+import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../types/signals";
+import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../components/runtime/runtime-signal-bus";
+import { resolvePhiBuilderCmsStoragePath } from "../../../helpers/cms-paths";
+import { resolvePhiBuilderActivePageCatalog } from "../../../helpers/cms-page-catalog";
+import { createPhiBuilderControllerAddress } from "./controller/address";
+import { createPhiBuilderHistoryContext, phiBuilderHistory } from "./history";
+/** A history scope nothing records into, for the screens that report no draft. */
+const PHI_BUILDER_NO_DRAFT_HISTORY_CONTEXT = "draft-status:none";
+function resolveTarget(workspace, area, pageKey, navKey, state) {
+    if (workspace === "navigation") {
+        return {
+            url: `/api/site/cms/navigation/draft?key=${encodeURIComponent(navKey)}`,
+            subject: navKey,
+            historyContext: createPhiBuilderHistoryContext({ workspace, area, navKey }),
+        };
+    }
+    if (workspace === "pages") {
+        if (!state.catalogHydrated || !state.pageCatalogHydratedByArea[area] || !pageKey) {
+            return null;
+        }
+        const pages = resolvePhiBuilderActivePageCatalog(area, state.modulePresetPagesByArea, state.customPages, state.persistedPageCatalogByArea);
+        const storagePath = resolvePhiBuilderCmsStoragePath(area, pageKey, pages);
+        return {
+            url: `/api/site/cms/page/draft?${new URLSearchParams({ area, path: storagePath }).toString()}`,
+            subject: area === "public" ? storagePath : `${area}${storagePath}`,
+            historyContext: createPhiBuilderHistoryContext({ workspace, area, pageKey }),
+        };
+    }
+    if (workspace === "structure" || workspace === "modules") {
+        if (!state.catalogHydrated) {
+            return null;
+        }
+        const sourcePreset = state.areaPresetSourcesByArea[area] ?? null;
+        if (!sourcePreset) {
+            throw new Error(`Builder target Area "${area}" has no source preset identity.`);
+        }
+        const query = new URLSearchParams({
+            area,
+            ownerModuleId: sourcePreset.ownerModuleId,
+            presetKey: sourcePreset.presetKey,
+        }).toString();
+        /*
+         * The Module selection has its own Draft on the same Area revision, so it reports its own status:
+         * asking the structure endpoint here would show the shell's Draft on a page that cannot save one.
+         */
+        return {
+            url: workspace === "modules"
+                ? `/api/site/cms/area/modules/draft?${query}`
+                : `/api/site/cms/area/draft?${query}`,
+            subject: area === "public" ? "/" : `${area}/`,
+            historyContext: createPhiBuilderHistoryContext({ workspace, area }),
+        };
+    }
+    return null;
+}
+/**
+ * The draft state of the workspace on screen, stated for the Core Draft Status Widget.
+ *
+ * What is stored is read here once per workspace target -- the Area shell, its Module selection, a
+ * Page, a Navigation -- and kept as the saved state; a save or a publish replaces it through
+ * `reportSaved`. `unsaved` is the history having moved since: the head of the workspace's undo history
+ * is remembered with every saved state, and any record, undo or redo that leaves a different head
+ * standing means what is on screen is in no stored revision. Undoing back to the saved head is saved
+ * again.
+ *
+ * Every change is broadcast; a Widget that mounts asks on `draftStatus`/`activate` and is answered
+ * alone.
+ */
+export function usePhiBuilderDraftStatusController({ commandWorkspace, effectiveArea, effectiveNavKey, effectivePageKey, state, }) {
+    const dispatchSignal = usePhiSignalDispatcher();
+    const target = resolveTarget(commandWorkspace, effectiveArea, effectivePageKey, effectiveNavKey, state);
+    const targetUrl = target?.url ?? null;
+    const subject = target?.subject ?? null;
+    const historyContext = target?.historyContext ?? null;
+    const [stored, setStored] = useState(null);
+    const historyHead = phiBuilderHistory.useHead(historyContext ?? PHI_BUILDER_NO_DRAFT_HISTORY_CONTEXT);
+    useEffect(() => {
+        if (targetUrl === null) {
+            return;
+        }
+        let cancelled = false;
+        const settle = (next) => {
+            if (cancelled) {
+                return;
+            }
+            setStored({
+                requestKey: targetUrl,
+                ...next,
+                savedHead: historyContext === null ? null : phiBuilderHistory.getHead(historyContext),
+            });
+        };
+        void fetch(targetUrl, { method: "GET", cache: "no-store" })
+            .then(async (response) => {
+            if (response.status === 404) {
+                settle({ status: "published", revisionId: null, error: null });
+                return;
+            }
+            const body = (await response.json().catch(() => null));
+            if (!response.ok) {
+                settle({ status: "error", revisionId: null, error: body?.error ?? null });
+                return;
+            }
+            const revisionId = Number.isInteger(body?.revisionId) ? body?.revisionId : null;
+            settle({ status: revisionId != null ? "draft" : "published", revisionId, error: null });
+        })
+            .catch((error) => {
+            settle({
+                status: "error",
+                revisionId: null,
+                error: error instanceof Error ? error.message : null,
+            });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [historyContext, targetUrl]);
+    const current = stored === null || stored.requestKey !== targetUrl || subject === null
+        ? null
+        : stored.status === "error"
+            ? { status: "error", revisionId: null, subject, error: stored.error }
+            : historyHead !== stored.savedHead
+                ? { status: "unsaved", revisionId: stored.revisionId, subject }
+                : { status: stored.status, revisionId: stored.revisionId, subject };
+    const emitTo = useCallback((receiver, value, correlationId) => {
+        dispatchSignal({
+            scope: "area",
+            channel: "draftStatus",
+            action: "change",
+            value,
+            valueType: "json",
+            valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.revisionsDraftStatus,
+            sender: createPhiBuilderControllerAddress(),
+            receiver,
+            correlationId,
+            timestamp: Date.now(),
+        });
+    }, [dispatchSignal]);
+    const serialized = current === null ? null : JSON.stringify(current);
+    useEffect(() => {
+        if (serialized !== null) {
+            emitTo("broadcast", JSON.parse(serialized));
+        }
+    }, [emitTo, serialized]);
+    usePhiSignalListener((signal) => {
+        if (signal.scope !== "area" ||
+            signal.channel !== "draftStatus" ||
+            signal.action !== "activate" ||
+            signal.receiver !== createPhiBuilderControllerAddress() ||
+            signal.sender == null) {
+            return;
+        }
+        // Not read yet: the broadcast that follows the read reaches the Widget that asked as well.
+        if (current !== null) {
+            emitTo(signal.sender, current, signal.correlationId);
+        }
+    }, undefined, createPhiBuilderControllerAddress());
+    /** A save or publish of the workspace on screen: the state it stored, and history as it stands. */
+    function reportSaved(status, revisionId) {
+        if (targetUrl === null) {
+            return;
+        }
+        setStored({
+            requestKey: targetUrl,
+            status,
+            revisionId,
+            error: null,
+            savedHead: historyContext === null ? null : phiBuilderHistory.getHead(historyContext),
+        });
+    }
+    return { reportSaved };
+}

package/plugins/runtime-modules/builder/effects-form-values.d.ts

@@ -15,6 +15,15 @@ export type PhiBuilderEffectsFormValuesBySection = {
     };
 };
 export declare function splitPhiBuilderEffectsFormValues(effects: PhiRenderableBlockEffects | null | undefined): PhiBuilderEffectsFormValuesBySection;
+/**
+ * The Transparency the Appearance section shows, as the opacity a block is drawn with.
+ *
+ * One reading for both the commit and the live picture in the canvas: the form asks how much of the
+ * block is taken away, the style says how much is left, and a second place doing that arithmetic is a
+ * second place for the two to disagree. Three decimals, because a percent step is a thousandth and
+ * anything beyond it is the binary fraction showing through.
+ */
+export declare function readPhiBuilderEffectsOpacity(appearance: unknown): number;
 export declare function mergePhiBuilderEffectsFormValues(input: {
     appearance: unknown;
     transitions: unknown;

package/plugins/runtime-modules/builder/effects-form-values.js

@@ -33,17 +33,27 @@ function withoutRowKeys(value) {
         return [row];
     });
 }
+/**
+ * The Transparency the Appearance section shows, as the opacity a block is drawn with.
+ *
+ * One reading for both the commit and the live picture in the canvas: the form asks how much of the
+ * block is taken away, the style says how much is left, and a second place doing that arithmetic is a
+ * second place for the two to disagree. Three decimals, because a percent step is a thousandth and
+ * anything beyond it is the binary fraction showing through.
+ */
+export function readPhiBuilderEffectsOpacity(appearance) {
+    const transparency = readRecord(appearance).transparency;
+    const clamped = typeof transparency === "number" ? Math.min(100, Math.max(0, transparency)) : 0;
+    return Number((1 - clamped / 100).toFixed(3));
+}
 export function mergePhiBuilderEffectsFormValues(input) {
     const appearance = readRecord(input.appearance);
     const transitions = readRecord(input.transitions);
     const viewport = readRecord(input.viewport);
-    const transparency = typeof appearance.transparency === "number"
-        ? Math.min(100, Math.max(0, appearance.transparency))
-        : 0;
     const viewportEffects = withoutRowKeys(viewport.viewportEffects)
         .map((effect) => effect.unit === "unitless" ? { ...effect, unit: "" } : effect);
     return {
-        opacity: Number((1 - transparency / 100).toFixed(3)),
+        opacity: readPhiBuilderEffectsOpacity(appearance),
         transitionTrigger: typeof transitions.transitionTrigger === "string"
             ? transitions.transitionTrigger
             : "on_mount",