@phis/ui 0.1.0 → 0.2.1

package/plugins/runtime-modules/builder/region-hydration.js

@@ -180,26 +180,6 @@ pageKey, regionKeys = BUILDER_REGION_KEYS) {
     }
     return drafts;
 }
-export function buildPhiDeveloperBuilderDraftHydrationSet({ area, pageKey, areaPreset, page, shellRegionKeys = PHI_BUILDER_SHELL_REGION_KEYS, pageRegionKeys = PHI_BUILDER_PAGE_REGION_KEYS, }) {
-    const drafts = {};
-    if (shellRegionKeys.length > 0 && areaPreset) {
-        Object.assign(drafts, buildPhiDeveloperBuilderRegionDraftsFromTree(areaPreset, area, pageKey, shellRegionKeys));
-    }
-    else {
-        for (const regionKey of shellRegionKeys) {
-            drafts[getPhiBuilderRegionDraftKey(area, regionKey, pageKey)] = buildRegionDraft(regionKey, {}, null);
-        }
-    }
-    if (pageRegionKeys.length > 0 && page) {
-        Object.assign(drafts, buildPhiDeveloperBuilderRegionDraftsFromTree(page, area, pageKey, pageRegionKeys));
-    }
-    else {
-        for (const regionKey of pageRegionKeys) {
-            drafts[getPhiBuilderRegionDraftKey(area, regionKey, pageKey)] = buildRegionDraft(regionKey, {}, null);
-        }
-    }
-    return drafts;
-}
 export function serializePhiDeveloperBuilderRegionConfig(_regionKey, draft) {
     const base = {
         ...toJsonRecord(draft.regionConfig),

package/plugins/runtime-modules/builder/render-root-node-preview.server.d.ts

@@ -12,8 +12,6 @@ export type PhiBuilderRootNodeServerPreviewProps = {
     runtime: PhiBlockRuntime;
     regionType?: number;
     regionKey?: string;
-    fallbackBlockSize?: string | null;
-    fallbackMinBlockSize?: string | null;
     registry: PhiCmsRuntimeRenderRegistry;
     regionConfig?: Record<string, unknown> | null;
     regionBackgroundConfig?: PhiCmsBackgroundWidgetConfig | null;
@@ -39,4 +37,4 @@ export declare function buildPhiBuilderServerPreviewRegions({ snapshot, runtime,
     runtime: PhiBlockRuntime;
     registry: PhiCmsRuntimeRenderRegistry;
 }): Partial<Record<PhiBuilderServerPreviewRegionKey, ReactNode>>;
-export declare function PhiBuilderRootNodeServerPreview({ rootNode, runtime, regionType, fallbackBlockSize, fallbackMinBlockSize, registry, regionConfig, regionBackgroundConfig, extraPreviewNodes, }: PhiBuilderRootNodeServerPreviewProps): Promise<ReactNode>;
+export declare function PhiBuilderRootNodeServerPreview({ rootNode, runtime, regionType, registry, regionConfig, regionBackgroundConfig, extraPreviewNodes, }: PhiBuilderRootNodeServerPreviewProps): Promise<ReactNode>;

package/plugins/runtime-modules/builder/render-root-node-preview.server.js

@@ -5,39 +5,12 @@ import { PhiSlotChildFrame } from "../../../plugins/runtime/phi-slot-child-frame
 import { resolvePhiCmsRegionType } from "../../../helpers/cms-region-keys";
 import {} from "./preview-transport";
 import { getPhiBuilderRegionDraftKey } from "./region-keys";
-import {} from "./root-node-normalization";
-import { resolvePhiRootNodeCssSize } from "./root-node-css-size";
+import { readPhiBuilderRootNodeDraftFields, } from "./root-node-normalization";
+import { resolvePhiRenderableBlockGeometry } from "../../../types/renderable-block-geometry";
+import { resolvePhiRootScaffoldProperties } from "./builder-geometry";
 import { buildPhiBuilderRootNodeRenderableTree } from "./root-node-renderable-tree";
 import { normalizePhiPaddingWidgetConfig } from "../../../types/cms-config";
 import { resolvePhiPaddingStyle } from "../../../components/layouts/phi-layout-contract";
-function resolveCssLength(value) {
-    if (typeof value === "number" && Number.isFinite(value)) {
-        return `${value}px`;
-    }
-    if (typeof value === "string") {
-        const trimmed = value.trim();
-        return trimmed.length > 0 ? trimmed : null;
-    }
-    return null;
-}
-function resolvePreviewFallbackBlockSize(regionKey, draft) {
-    if (!regionKey) {
-        return null;
-    }
-    const shouldUseFallbackHeight = regionKey === "header_bottom" ||
-        regionKey === "hero" ||
-        regionKey === "sider_right";
-    if (!shouldUseFallbackHeight) {
-        return null;
-    }
-    return resolveCssLength(draft?.minSize?.height) ?? resolveCssLength(draft?.size?.height) ?? "84px";
-}
-function resolvePreviewFallbackMinBlockSize(regionKey, draft) {
-    if (regionKey !== "content") {
-        return null;
-    }
-    return resolveCssLength(draft?.minSize?.height) ?? resolveCssLength(draft?.size?.height) ?? "84px";
-}
 function buildPreviewTree(rootNode, regionType, regionConfig, regionBackgroundConfig) {
     return buildPhiBuilderRootNodeRenderableTree({
         rootNode,
@@ -86,16 +59,7 @@ function resolveRootNodeFromPreviewDraft(draft) {
         id: draft.rootNodeId ?? null,
         typeKey: draft.rootNodeTypeKey,
         kind: resolvePreviewRootNodeKind(draft.rootNodeKind ?? null),
-        title: draft.rootNodeTitle ?? null,
-        rootNodeConfig: draft.rootNodeConfig ?? null,
-        rootNodeGeometry: draft.rootNodeGeometry ?? null,
-        rootNodeAnchor: draft.rootNodeAnchor ?? null,
-        rootNodePadding: draft.rootNodePadding ?? null,
-        rootNodeBackground: draft.rootNodeBackground ?? null,
-        rootNodeBorder: draft.rootNodeBorder ?? null,
-        rootNodeShadow: draft.rootNodeShadow ?? null,
-        childLayouts: draft.rootNodeChildLayouts ?? [],
-        childWidgets: draft.rootNodeChildWidgets ?? [],
+        ...readPhiBuilderRootNodeDraftFields(draft),
     };
 }
 function buildPreviewSnapshotNodes(snapshot) {
@@ -147,7 +111,7 @@ export function PhiBuilderRegionServerPreview({ snapshot, draft, regionKey, runt
     if (!rootNode) {
         return null;
     }
-    return (_jsx(PhiBuilderRootNodeServerPreview, { rootNode: rootNode, runtime: runtime, regionKey: regionKey, fallbackBlockSize: resolvePreviewFallbackBlockSize(regionKey, previewDraft), fallbackMinBlockSize: resolvePreviewFallbackMinBlockSize(regionKey, previewDraft), regionType: resolvePhiCmsRegionType(regionKey), registry: registry, regionConfig: previewRegionConfig, regionBackgroundConfig: regionBackgroundConfig, extraPreviewNodes: extraPreviewNodes }));
+    return (_jsx(PhiBuilderRootNodeServerPreview, { rootNode: rootNode, runtime: runtime, regionKey: regionKey, regionType: resolvePhiCmsRegionType(regionKey), registry: registry, regionConfig: previewRegionConfig, regionBackgroundConfig: regionBackgroundConfig, extraPreviewNodes: extraPreviewNodes }));
 }
 export function buildPhiBuilderServerPreviewRegions({ snapshot, runtime, registry, }) {
     if (!snapshot) {
@@ -170,8 +134,9 @@ export function buildPhiBuilderServerPreviewRegions({ snapshot, runtime, registr
         _jsx(PhiBuilderRegionServerPreview, { snapshot: snapshot, regionKey: regionKey, runtime: runtime, registry: registry }, regionKey),
     ]));
 }
-export async function PhiBuilderRootNodeServerPreview({ rootNode, runtime, regionType = PhiCmsRegionType.Content, fallbackBlockSize = null, fallbackMinBlockSize = null, registry, regionConfig = null, regionBackgroundConfig = null, extraPreviewNodes, }) {
+export async function PhiBuilderRootNodeServerPreview({ rootNode, runtime, regionType = PhiCmsRegionType.Content, registry, regionConfig = null, regionBackgroundConfig = null, extraPreviewNodes, }) {
     const rootSlotChildKind = rootNode.kind === "widget" ? "widget" : "layout";
+    const rootGeometry = resolvePhiRenderableBlockGeometry(rootNode.rootNodeGeometry);
     const tree = buildPreviewTree(rootNode, regionType, regionConfig, regionBackgroundConfig);
     if (!tree) {
         return null;
@@ -185,20 +150,7 @@ export async function PhiBuilderRootNodeServerPreview({ rootNode, runtime, regio
                 : undefined, className: "phi-cms-region-shell phi-cms-region-shell--fill", style: {
             width: "100%",
             height: "100%",
-        }, children: _jsx("div", { className: "phi-cms-region-shell__content", style: regionPaddingStyle, children: _jsx(PhiSlotChildFrame, { className: "phi-builder-root-scaffold__slot", kind: rootSlotChildKind, blockId: rootNode.id ?? null, explicitInlineSize: rootNode.rootNodeGeometry?.size?.width != null, explicitBlockSize: rootNode.rootNodeGeometry?.size?.height != null, style: {
-                    "--phi-root-scaffold-width": resolvePhiRootNodeCssSize(rootNode.rootNodeGeometry?.size?.width, "100%"),
-                    "--phi-root-scaffold-height": resolvePhiRootNodeCssSize(rootNode.rootNodeGeometry?.size?.height, fallbackBlockSize ?? "auto"),
-                    "--phi-root-scaffold-min-width": resolvePhiRootNodeCssSize(rootNode.rootNodeGeometry?.minSize?.width, "0"),
-                    "--phi-root-scaffold-min-height": resolvePhiRootNodeCssSize(rootNode.rootNodeGeometry?.minSize?.height, fallbackMinBlockSize ?? "0"),
-                    "--phi-root-scaffold-max-width": resolvePhiRootNodeCssSize(rootNode.rootNodeGeometry?.maxSize?.width, "none"),
-                    "--phi-root-scaffold-max-height": resolvePhiRootNodeCssSize(rootNode.rootNodeGeometry?.maxSize?.height, "none"),
-                    "--phi-root-scaffold-flex": rootNode.rootNodeGeometry?.size?.width != null || rootNode.rootNodeGeometry?.size?.height != null ? "0 0 auto" : "1 1 auto",
-                    "--phi-root-scaffold-explicit-width": resolvePhiRootNodeCssSize(rootNode.rootNodeGeometry?.size?.width, "auto"),
-                    "--phi-root-scaffold-explicit-height": resolvePhiRootNodeCssSize(rootNode.rootNodeGeometry?.size?.height, "auto"),
-                    minWidth: 0,
-                    minHeight: 0,
-                    flex: "1 1 auto",
-                }, children: _jsx(PhiCmsLayoutRenderer, { tree: {
+        }, children: _jsx("div", { className: "phi-cms-region-shell__content", style: regionPaddingStyle, children: _jsx(PhiSlotChildFrame, { className: "phi-builder-root-scaffold__slot", kind: rootSlotChildKind, blockId: rootNode.id ?? null, explicitInlineSize: rootGeometry.explicitInline, explicitBlockSize: rootGeometry.explicitBlock, style: resolvePhiRootScaffoldProperties(rootGeometry), children: _jsx(PhiCmsLayoutRenderer, { tree: {
                         ...previewTree,
                         regions: previewTree.regions.map((region) => ({
                             ...region,

package/plugins/runtime-modules/builder/render-root-node-scaffold.d.ts

@@ -4,6 +4,7 @@ import { type PhiCmsInstanceId } from "../../../types/cms-instance-id";
 import { type PhiStructureDragData, type PhiStructureDropTargetData } from "./structure-dnd";
 import { type PhiAnchorWidgetPlacement } from "../../../components/controls/phi-anchor-control-contract";
 import type { PhiEffectsWidgetLabels } from "../../../components/widgets/label-types/effects";
+import type { PhiAuthoringToolsLabels } from "../../../components/widgets/label-types/authoring-tools";
 import type { PhiCmsWidgetAuthoringCanvas } from "../../../types";
 import type { PhiBuilderRootNodeDraft } from "./root-node-normalization";
 import type { PhiRuntimeControllerMaterializationOwner } from "../../../components/runtime/runtime-controller-materialization";
@@ -36,9 +37,8 @@ export declare function renderPhiRootNodeScaffold(rootNode: PhiBuilderRootNodeDr
     nodeKey?: string | null;
     nodeKind?: "layout" | "widget" | null;
 }) => void, onUpdateWidgetNodeConfig?: (node: PhiCmsContentWidgetNode, configPatch: Record<string, unknown>) => void, onUpdateLayoutNodeConfig?: (node: PhiCmsLayoutRenderNode, configPatch: Record<string, unknown>) => void, options?: {
-    fallbackBlockSize?: string | null;
-    fallbackMinBlockSize?: string | null;
     effectsLabels?: PhiEffectsWidgetLabels;
+    authoringToolsLabels?: PhiAuthoringToolsLabels;
     demandControllerContext?: PhiBuilderDemandControllerContextInput;
     authoringCanvas?: PhiCmsWidgetAuthoringCanvas;
     inheritedViewportFlags?: number | null;

package/plugins/runtime-modules/builder/render-root-node-scaffold.js

@@ -7,19 +7,22 @@ import { PhiEditScaffoldDrawer } from "./edit-scaffold-drawer";
 import { comparePhiCmsInstanceIds } from "../../../types/cms-instance-id";
 import { normalizePhiPaddingWidgetConfig } from "../../../types/cms-config";
 import { resolvePhiBackgroundWidgetStyle, } from "../../../components/widgets/config/background";
-import { resolvePhiBorderWidgetStyle } from "../../../helpers/border-widget-style";
+import { resolvePhiSourcedBorderStyle } from "../../../helpers/border-widget-style";
+import { readPhiCmsBorderSource, resolvePhiCmsBorderSource, } from "../../../types/cms-border-source";
 import { resolvePhiAnchorPlacement } from "../../../components/layouts/phi-layout-contract";
 import { PhiSlotChildFrame } from "../../../plugins/runtime/phi-slot-child-frame";
 import { PhiLayoutDeleteButtonOverlay, PhiLayoutDragButtonOverlay, PhiLayoutPlusButtonOverlay, } from "./clients/layout-scaffold-overlays";
 import { PhiPlusButtonWidget, } from "./clients/layout-scaffold-buttons";
 import { usePhiStructureDroppable, } from "./structure-dnd";
-import { PhiInlineTextEditor } from "./clients/inline-text-editor";
+import { PhiInlineTextEditor } from "../../../components/controls/phi-inline-text-editor";
 import { PhiButtonControl } from "../../../components/controls/phi-button-control";
 import { usePhiAuthoringLayoutDefinition, usePhiRuntimeModuleAuthoringRegistration, } from "../../../plugins/runtime-modules/client-authoring-module";
 import { usePhiRuntimeModuleState } from "../../../components/runtime/runtime-module-context";
 import { PhiCmsRenderDiagnostic } from "../../../components/cms/phi-cms-render-diagnostic";
 import { PhiCmsRenderErrorBoundary } from "../../../components/cms/phi-cms-render-error-boundary";
 import { isPhiAnchorWidgetPlacement } from "../../../components/controls/phi-anchor-control-contract";
+import { PhiAuthoringToolsLabelsProvider } from "../../../components/widgets/client/shared/phi-authoring-tools-labels";
+import { PhiBuilderPageReferencesProvider } from "./page-references-provider";
 import { readPhiShadow } from "../../../types/layout-style";
 import { combinePhiBoxShadows, resolvePhiShadow } from "../../../helpers/layout-style";
 import { PHI_VIEWER_ACCESS_ANYONE, intersectPhiInheritedViewportFlags, } from "../../../types/access";
@@ -28,12 +31,13 @@ import { PHI_RENDERABLE_BLOCK_DEFAULT_TRANSITION } from "../../../helpers/render
 import { PhiWidgetEffectsToolButton } from "./clients/widget-effects-editor";
 import { PHI_WIDGET_SCAFFOLD_POPUP_CLASS_NAME, PhiWidgetScaffoldPopupProvider, } from "../../../components/widgets/client/shared/phi-widget-scaffold-popup";
 import { buildPhiBuilderRootNodeRenderConfig, normalizePhiBuilderRootNodeDraft, } from "./root-node-normalization";
-import { resolvePhiRootNodeCssSize } from "./root-node-css-size";
+import { resolvePhiRenderableBlockGeometry } from "../../../types/renderable-block-geometry";
+import { resolvePhiRootScaffoldProperties } from "./builder-geometry";
 import { PhiWidgetPreviewFallback } from "../../../components/widgets/built-in/widget-preview";
 import { splitPhiCmsLayoutNamespacedTypeKey } from "../../../constants/cms-layout-types";
 import { PhiBuilderDemandControllerRegistration } from "./demand-controller-registration";
 import { buildPhiBuilderRootNodeRenderableTree } from "./root-node-renderable-tree";
-import { usePhiDeveloperBuilderStateValue } from "./developer-workspace-store";
+import { readPhiDeveloperBuilderEffectsPreview, usePhiDeveloperBuilderStateValue, } from "./developer-workspace-store";
 function resolvePhiAuthoringLayoutType(type) {
     const { pluginKey, typeKey } = splitPhiCmsLayoutNamespacedTypeKey(type);
     return `${pluginKey}/${typeKey}`;
@@ -267,13 +271,25 @@ function findPhiWidgetAuthoringTextTarget(container, clientX, clientY) {
             clientY <= rect.bottom);
     }) ?? null;
 }
-function PhiWidgetEffectsPreviewFrame({ kind, slotSizePolicy, blockId, regionKey, config, title, editorInteraction = "inert", onSelect, dropTarget, tools, style, children, }) {
+function PhiWidgetEffectsPreviewFrame({ kind, slotSizePolicy, blockId, regionKey, config: committedConfig, title, scaffoldLabel, editorInteraction = "inert", onSelect, dropTarget, tools, style, children, }) {
     const { token } = antdTheme.useToken();
     const selected = usePhiDeveloperBuilderStateValue("public", (state) => blockId != null &&
         regionKey != null &&
         state.selectedRootRegionKey === regionKey &&
         state.nodeKind === "widget" &&
         state.nodeId === blockId);
+    /*
+     * What the node is drawn with: the draft, or -- while its Effects editor stands open on this node --
+     * what that editor shows at this moment.
+     *
+     * A transparency is chosen by looking at it, so the number has to be on the page while the handle is
+     * still under the finger; the draft learns it when Save is pressed. Overlaying the whole `effects`
+     * rather than one property keeps this the editor's picture and not a second opinion about it.
+     */
+    const effectsPreview = usePhiDeveloperBuilderStateValue("public", (state) => readPhiDeveloperBuilderEffectsPreview(state, "widget", blockId ?? null));
+    const config = effectsPreview
+        ? { ...committedConfig, effects: effectsPreview }
+        : committedConfig;
     const [previewRunId, setPreviewRunId] = useState(0);
     const [isPreviewing, setIsPreviewing] = useState(false);
     const [isAuthoringActive, setIsAuthoringActive] = useState(false);
@@ -450,8 +466,23 @@ function PhiWidgetEffectsPreviewFrame({ kind, slotSizePolicy, blockId, regionKey
         "--phi-builder-widget-scaffold-label-border": token.colorWarningBorder,
         "--phi-builder-widget-scaffold-label-color": token.colorWarningText,
     };
+    /*
+     * While the Widget is being written in, the scaffold steps back.
+     *
+     * The band, the toolbar, the drag handle, the delete and inspector buttons and the effects preview are
+     * all chrome for a Widget one is looking at, and they sit on top of the surface one is typing into --
+     * the preview button stood dead centre of the text editor, the toolbar over its first line. None of it
+     * has anything to add while a text is being written, and what it does instead is cover the text and
+     * offer a drag handle for a node the pointer is inside of.
+     *
+     * The tools are not rendered; the band and the outline are the stylesheet's, drawn from hovering and
+     * from the attributes below, so they are switched off there -- and the band deliberately by `content`
+     * rather than by withholding its text, because an absent attribute still leaves `attr()` an empty
+     * string to draw a bordered chip from.
+     */
+    const scaffoldChrome = isAuthoringActive ? null : tools;
     if (!hasRenderableBlockPreviewEffects(config)) {
-        return (_jsx(PhiWidgetScaffoldPopupProvider, { onOpenChange: setIsToolbarPopupOpen, children: _jsx(PhiSlotChildFrame, { kind: kind, slotSizePolicy: slotSizePolicy, blockId: blockId, config: config, disableEffects: true, runtimeSignalEmissionsEnabled: false, className: "phi-builder-widget-scaffold", style: widgetScaffoldStyle, builderWidgetTitle: title, builderWidgetSelected: selected, builderWidgetPopupOpen: isToolbarPopupOpen, onPointerLeave: isAuthoringActive && !isToolbarPopupOpen ? finishAuthoringOnPointerLeave : undefined, chrome: tools, children: renderEditorLayers() }) }));
+        return (_jsx(PhiWidgetScaffoldPopupProvider, { onOpenChange: setIsToolbarPopupOpen, children: _jsx(PhiSlotChildFrame, { kind: kind, slotSizePolicy: slotSizePolicy, blockId: blockId, config: config, disableEffects: true, runtimeSignalEmissionsEnabled: false, className: "phi-builder-widget-scaffold", style: widgetScaffoldStyle, builderWidgetTitle: scaffoldLabel?.trim() || title, builderWidgetSelected: selected, builderWidgetPopupOpen: isToolbarPopupOpen, onPointerLeave: isAuthoringActive && !isToolbarPopupOpen ? finishAuthoringOnPointerLeave : undefined, chrome: scaffoldChrome, children: renderEditorLayers() }) }));
     }
     const previewConfig = {
         ...config,
@@ -460,7 +491,7 @@ function PhiWidgetEffectsPreviewFrame({ kind, slotSizePolicy, blockId, regionKey
             transitionTrigger: "on_mount",
         },
     };
-    return (_jsx(PhiWidgetScaffoldPopupProvider, { onOpenChange: setIsToolbarPopupOpen, children: _jsx(PhiSlotChildFrame, { kind: kind, slotSizePolicy: slotSizePolicy, blockId: blockId, config: previewConfig, disableEffects: !isPreviewing, runtimeSignalEmissionsEnabled: false, className: "phi-builder-widget-scaffold", style: widgetScaffoldStyle, builderWidgetTitle: title, builderWidgetSelected: selected, builderWidgetPopupOpen: isToolbarPopupOpen, onPointerLeave: isAuthoringActive && !isToolbarPopupOpen ? finishAuthoringOnPointerLeave : undefined, chrome: (_jsxs(_Fragment, { children: [tools, !isPreviewing ? (_jsx(PhiEffectsPreviewButton, { config: config, blockKind: "widget", onRun: () => {
+    return (_jsx(PhiWidgetScaffoldPopupProvider, { onOpenChange: setIsToolbarPopupOpen, children: _jsx(PhiSlotChildFrame, { kind: kind, slotSizePolicy: slotSizePolicy, blockId: blockId, config: previewConfig, disableEffects: !isPreviewing, runtimeSignalEmissionsEnabled: false, className: "phi-builder-widget-scaffold", style: widgetScaffoldStyle, builderWidgetTitle: scaffoldLabel?.trim() || title, builderWidgetSelected: selected, builderWidgetPopupOpen: isToolbarPopupOpen, onPointerLeave: isAuthoringActive && !isToolbarPopupOpen ? finishAuthoringOnPointerLeave : undefined, chrome: scaffoldChrome === null ? null : (_jsxs(_Fragment, { children: [scaffoldChrome, !isPreviewing ? (_jsx(PhiEffectsPreviewButton, { config: config, blockKind: "widget", onRun: () => {
                             setIsPreviewing(false);
                             window.requestAnimationFrame(() => {
                                 setPreviewRunId((current) => current + 1);
@@ -468,7 +499,12 @@ function PhiWidgetEffectsPreviewFrame({ kind, slotSizePolicy, blockId, regionKey
                             });
                         } })) : null] })), children: renderEditorLayers() }, `effects-preview-${previewRunId}`) }));
 }
-function PhiLayoutEffectsPreviewFrame({ kind, slotSizePolicy, blockId, config, explicitInlineSize, explicitBlockSize, children, }) {
+function PhiLayoutEffectsPreviewFrame({ kind, slotSizePolicy, blockId, config: committedConfig, explicitInlineSize, explicitBlockSize, children, }) {
+    // The same live picture the Widget frame draws, for the Layout whose own toolbar opened the editor.
+    const effectsPreview = usePhiDeveloperBuilderStateValue("public", (state) => readPhiDeveloperBuilderEffectsPreview(state, "layout", blockId ?? null));
+    const config = effectsPreview
+        ? { ...committedConfig, effects: effectsPreview }
+        : committedConfig;
     const [previewRunId, setPreviewRunId] = useState(0);
     const [isPreviewing, setIsPreviewing] = useState(false);
     const previewDurationMs = resolveEffectsPreviewDurationMs(config);
@@ -504,7 +540,26 @@ function PhiAuthoringLayoutEffectsPreviewFrame({ type, ...props }) {
 function readObjectConfig(value) {
     return typeof value === "object" && value != null ? value : null;
 }
-function formatLayoutScaffoldLabel(typeKey, _kind, definitionTitle) {
+/**
+ * The band under a scaffold: what this node is called, and then what it is.
+ *
+ * Both belong there. The type is how somebody recognizes a Block they did not place, and the name a
+ * Preset gave it -- "dev home hero" -- is what tells two Markdown Widgets on one Page apart. On a
+ * Widget the name used to take the type's place, so on every Page built from a Preset the canvas
+ * stopped saying what anything was; a Layout said only its type and never its name.
+ *
+ * A node inserted through the picker is handed the type's own title as its name
+ * (`buildInsertedWidgetNode`), and "Markdown: Markdown" says nothing twice. So a name that is the type
+ * is not a name here. `typeName` is what that comparison is against, which for a Layout is the type
+ * without the trailing kind -- the picker writes "Vertical Flex", the band reads "Vertical Flex layout".
+ */
+function formatPhiScaffoldLabel(name, typeLabel, typeName = typeLabel) {
+    const resolvedName = name?.trim();
+    return !resolvedName || resolvedName === typeName.trim()
+        ? typeLabel
+        : `${resolvedName}: ${typeLabel}`;
+}
+function formatLayoutScaffoldLabel(typeKey, _kind, definitionTitle, name) {
     const typeTitle = splitPhiCmsLayoutNamespacedTypeKey(typeKey)
         .typeKey
         ?.split("-")
@@ -512,7 +567,8 @@ function formatLayoutScaffoldLabel(typeKey, _kind, definitionTitle) {
         .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
         .join(" ") ?? "Layout";
     const kindLabel = "layout";
-    return `${definitionTitle?.trim() || typeTitle} ${kindLabel}`;
+    const typeName = definitionTitle?.trim() || typeTitle;
+    return formatPhiScaffoldLabel(name, `${typeName} ${kindLabel}`, typeName);
 }
 function resolveLayoutNodeRootProps(node) {
     return {
@@ -533,15 +589,21 @@ function resolveLayoutNodeRootProps(node) {
         childWidgets: node.childWidgets,
     };
 }
-function resolveRootNodeChromeStyle({ background, border, shadow, style, }) {
-    if (background == null && border == null && shadow == null) {
+function resolveRootNodeChromeStyle({ background, borderSource, border, shadow, style, }) {
+    /*
+     * The Canvas draws the same chrome the page will, so it has to ask the same question: where does the
+     * outline come from. `theme` draws a line where nothing is stored, which is why the shortcut below
+     * can no longer take "nothing stored" for "nothing to draw".
+     */
+    const resolvedBorderSource = resolvePhiCmsBorderSource(borderSource, border);
+    if (background == null && border == null && shadow == null && resolvedBorderSource !== "theme") {
         return style;
     }
     const backgroundStyle = background == null ? {} : resolvePhiBackgroundWidgetStyle(background);
     return {
         ...style,
         ...backgroundStyle,
-        ...(border == null ? {} : resolvePhiBorderWidgetStyle(border)),
+        ...resolvePhiSourcedBorderStyle(resolvedBorderSource, border),
         boxShadow: combinePhiBoxShadows(backgroundStyle.boxShadow, resolvePhiShadow(shadow)),
     };
 }
@@ -650,7 +712,9 @@ function resolvePhiRootNodeRenderedBody(rootNode, renderMode, plugin, definition
         const widgetViewportFlags = intersectPhiInheritedViewportFlags(resolvedViewportFlags, widget.config.viewportFlags);
         return (_jsx(PhiAuthoringWidgetLoader, { widget: widget, config: { ...renderableBlockConfig, renderMode: "editor" }, slotSizePolicy: widgetDefinitionsByType.get(widget.widgetType)?.slotSizePolicy, demandControllerContext: demandControllerContext, children: (plugin, definition) => {
                 const resolvedConfig = plugin.parseConfig(widget.config ?? {});
-                const widgetTitle = widget.label ?? plugin.title ?? widget.widgetType;
+                const widgetTypeTitle = plugin.title ?? widget.widgetType;
+                const widgetTitle = widget.label ?? widgetTypeTitle;
+                const widgetScaffoldLabel = formatPhiScaffoldLabel(widget.label, widgetTypeTitle);
                 const parsedWidgetConfig = (resolvedConfig ?? {});
                 const editorConfig = {
                     ...renderableBlockConfig,
@@ -682,7 +746,7 @@ function resolvePhiRootNodeRenderedBody(rootNode, renderMode, plugin, definition
                         authoring,
                     })
                     : null;
-                const renderedScaffoldTools = (_jsxs(_Fragment, { children: [widgetViewportFlags === 0 ? _jsx(PhiViewportIntersectionDiagnostic, {}) : null, renderedEditorTools, onOpenWiringWidgetNode ? (_jsx(PhiSignalWiringToolButton, { onOpen: () => onOpenWiringWidgetNode({ ...widget }) })) : null, _jsx(PhiWidgetEffectsToolButton, { effects: renderableBlockConfig.effects, labels: effectsLabels, onChange: (effects) => onUpdateWidgetNodeConfig?.(widget, { effects }) })] }));
+                const renderedScaffoldTools = (_jsxs(_Fragment, { children: [widgetViewportFlags === 0 ? _jsx(PhiViewportIntersectionDiagnostic, {}) : null, renderedEditorTools, onOpenWiringWidgetNode ? (_jsx(PhiSignalWiringToolButton, { onOpen: () => onOpenWiringWidgetNode({ ...widget }) })) : null, _jsx(PhiWidgetEffectsToolButton, { effects: renderableBlockConfig.effects, target: { kind: "widget", blockId: widget.id }, labels: effectsLabels, onChange: (effects) => onUpdateWidgetNodeConfig?.(widget, { effects }) })] }));
                 const renderedNode = isValidElement(renderedWidget)
                     ? cloneElement(renderedWidget, {
                         "data-phi-widget-node": widget.widgetType,
@@ -693,9 +757,9 @@ function resolvePhiRootNodeRenderedBody(rootNode, renderMode, plugin, definition
                         typeof onOpenInspectorWidgetNode === "function" ||
                         typeof onUpdateWidgetNodeConfig === "function");
                 if (!shouldWrapWidgetNode) {
-                    return (_jsx(PhiWidgetEffectsPreviewFrame, { kind: "widget", slotSizePolicy: plugin.slotSizePolicy, blockId: widget.id, regionKey: regionKey, config: editorConfig, title: widgetTitle, editorInteraction: plugin.editorInteraction, children: renderedNode }, `widget-${widget.id}`));
+                    return (_jsx(PhiWidgetEffectsPreviewFrame, { kind: "widget", slotSizePolicy: plugin.slotSizePolicy, blockId: widget.id, regionKey: regionKey, config: editorConfig, title: widgetTitle, scaffoldLabel: widgetScaffoldLabel, editorInteraction: plugin.editorInteraction, children: renderedNode }, `widget-${widget.id}`));
                 }
-                return (_jsx(PhiWidgetEffectsPreviewFrame, { kind: "widget", slotSizePolicy: plugin.slotSizePolicy, blockId: widget.id, regionKey: regionKey, config: editorConfig, title: widgetTitle, editorInteraction: plugin.editorInteraction, onSelect: onOpenInspectorWidgetNode
+                return (_jsx(PhiWidgetEffectsPreviewFrame, { kind: "widget", slotSizePolicy: plugin.slotSizePolicy, blockId: widget.id, regionKey: regionKey, config: editorConfig, title: widgetTitle, scaffoldLabel: widgetScaffoldLabel, editorInteraction: plugin.editorInteraction, onSelect: onOpenInspectorWidgetNode
                         ? () => onOpenInspectorWidgetNode({ ...widget })
                         : undefined, dropTarget: resolveWidgetDropTarget?.(widget) ?? null, tools: onDeleteWidgetNode ? (_jsxs(_Fragment, { children: [resolveWidgetDragData ? (_jsx(PhiLayoutDragButtonOverlay, { ariaLabel: `Move ${widgetTitle}`, nodeKind: "widget", dragData: resolveWidgetDragData(widget) })) : null, _jsx(PhiLayoutDeleteButtonOverlay, { onOpenInspector: onOpenInspectorWidgetNode
                                     ? () => onOpenInspectorWidgetNode({ ...widget })
@@ -705,19 +769,36 @@ function resolvePhiRootNodeRenderedBody(rootNode, renderMode, plugin, definition
                     }, children: renderedNode }, `widget-${widget.id}`));
             } }, `widget-${widget.id}`));
     };
-    const renderSequentialSlotChildren = () => {
-        return [...syntheticRootNode.childLayouts, ...syntheticRootNode.childWidgets]
-            .sort((left, right) => left.sortOrder - right.sortOrder || comparePhiCmsInstanceIds(left.id, right.id))
-            .reduce((slots, entry) => {
-            const rendered = "contentId" in entry
-                ? renderWidgetNode(entry)
-                : renderChildLayoutNode
-                    ? renderChildLayoutNode(entry)
-                    : renderPhiRootNodePreview(resolveLayoutNodeRootProps(entry));
-            slots[entry.slotIndex] = rendered;
-            return slots;
-        }, []);
-    };
+    /**
+     * The node's children, both kinds, in the order they were added.
+     *
+     * One collection with two shapes over it, the way the Site renderer already does it
+     * (`buildRenderedChildEntries` in components/cms/phi-cms-layout-renderer.tsx). It was two
+     * independent walks here, and they drifted: the flat one listed the Widgets only, so a Layout
+     * dropped into the one kind that renders flat -- Content -- was written to the draft and never
+     * drawn. Collecting once is what keeps the two answers about the same children the same.
+     *
+     * A Layout is drawn by the scaffold's own child renderer where there is one, and falls back to a
+     * plain preview where there is not; that is what tells this apart from the Site renderer, which
+     * always has the full runtime to hand.
+     */
+    const buildRenderedChildEntries = () => [...syntheticRootNode.childLayouts, ...syntheticRootNode.childWidgets]
+        .sort((left, right) => left.sortOrder - right.sortOrder || comparePhiCmsInstanceIds(left.id, right.id))
+        .map((entry) => ({
+        slotIndex: entry.slotIndex,
+        rendered: "contentId" in entry
+            ? renderWidgetNode(entry)
+            : renderChildLayoutNode
+                ? renderChildLayoutNode(entry)
+                : renderPhiRootNodePreview(resolveLayoutNodeRootProps(entry)),
+    }));
+    /** Flat, for a Layout with one content area rather than numbered slots. */
+    const renderChildren = () => buildRenderedChildEntries().map((entry) => entry.rendered);
+    /** Placed by slot, for a Layout whose slots are positions it draws into. */
+    const renderSequentialSlotChildren = () => buildRenderedChildEntries().reduce((slots, entry) => {
+        slots[entry.slotIndex] = entry.rendered;
+        return slots;
+    }, []);
     const rootRenderMode = renderMode === "preview" ? "preview" : renderMode === "editor" ? "editor" : "live";
     const renderRootNode = resolvePhiAuthoringLayoutRenderer(plugin, definition, rootRenderMode);
     const parseRootConfig = resolvePhiAuthoringLayoutConfigParser(plugin);
@@ -734,12 +815,11 @@ function resolvePhiRootNodeRenderedBody(rootNode, renderMode, plugin, definition
     try {
         return renderRootNode({
             node: syntheticRootNode,
-            layoutKind: plugin.layoutKind,
             runtime: {},
             tree: previewTree,
             config: (parseRootConfig?.(buildPhiBuilderRootNodeRenderConfig(normalizedRootNode, rootRenderMode)) ??
                 plugin.parseConfig(buildPhiBuilderRootNodeRenderConfig(normalizedRootNode, rootRenderMode))),
-            renderChildren: () => syntheticRootNode.childWidgets.map((widget) => renderWidgetNode(widget)),
+            renderChildren,
             renderSequentialSlotChildren,
         });
     }
@@ -760,6 +840,7 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
     }
     const regionKey = rootNode.regionKey;
     const normalizedRootNode = normalizePhiBuilderRootNodeDraft(rootNode);
+    const rootGeometry = resolvePhiRenderableBlockGeometry(normalizedRootNode.rootNodeGeometry);
     if (normalizedRootNode.id == null) {
         return null;
     }
@@ -793,7 +874,7 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
         childLayouts: normalizedRootNode.childLayouts ?? [],
         childWidgets: normalizedRootNode.childWidgets ?? [],
     };
-    const wrapRootScaffoldChild = (child) => (_jsx(PhiLayoutEffectsPreviewFrame, { kind: "layout", blockId: normalizedRootNode.id ?? null, config: rootNodeRenderableConfig, explicitInlineSize: normalizedRootNode.rootNodeGeometry?.size?.width != null, explicitBlockSize: normalizedRootNode.rootNodeGeometry?.size?.height != null, children: child }));
+    const wrapRootScaffoldChild = (child) => (_jsx(PhiLayoutEffectsPreviewFrame, { kind: "layout", blockId: normalizedRootNode.id ?? null, config: rootNodeRenderableConfig, explicitInlineSize: rootGeometry.explicitInline, explicitBlockSize: rootGeometry.explicitBlock, children: child }));
     const renderRootScaffoldToolbar = () => {
         if (typeof onDeleteRootNode !== "function") {
             return null;
@@ -807,7 +888,7 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
                                     nodeKey: normalizedRootNode.typeKey,
                                     nodeKind,
                                     openWiring: true,
-                                }) })) : null, _jsx(PhiWidgetEffectsToolButton, { effects: rootNodeEffects, labels: options?.effectsLabels, onChange: (effects) => onUpdateLayoutNodeConfig(syntheticRootNodeForUpdates, { effects }) })] })) : null, onOpenInspector: onOpenInspector
+                                }) })) : null, _jsx(PhiWidgetEffectsToolButton, { effects: rootNodeEffects, target: { kind: "layout", blockId: normalizedRootNode.id ?? null }, labels: options?.effectsLabels, onChange: (effects) => onUpdateLayoutNodeConfig(syntheticRootNodeForUpdates, { effects }) })] })) : null, onOpenInspector: onOpenInspector
                         ? () => onOpenInspector({
                             nodeId: normalizedRootNode.id ?? null,
                             nodeKey: normalizedRootNode.typeKey,
@@ -819,16 +900,8 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
                         nodeKind: normalizedRootNode.kind,
                     }) })] }));
     };
-    const renderRootDrawer = (child, definitionTitle) => (_jsx(PhiEditScaffoldDrawer, { className: "phi-builder-root-scaffold", kind: "layout", nodeId: normalizedRootNode.id, regionKey: regionKey, title: rootTitle, scaffoldLabel: formatLayoutScaffoldLabel(normalizedRootNode.typeKey, normalizedRootNode.kind, definitionTitle), packageName: rootPackageName, style: {
-            "--phi-root-scaffold-width": resolvePhiRootNodeCssSize(normalizedRootNode.rootNodeGeometry?.size?.width, "100%"),
-            "--phi-root-scaffold-height": resolvePhiRootNodeCssSize(normalizedRootNode.rootNodeGeometry?.size?.height, options?.fallbackBlockSize ?? "auto"),
-            "--phi-root-scaffold-min-width": resolvePhiRootNodeCssSize(normalizedRootNode.rootNodeGeometry?.minSize?.width, "0"),
-            "--phi-root-scaffold-min-height": resolvePhiRootNodeCssSize(normalizedRootNode.rootNodeGeometry?.minSize?.height, options?.fallbackMinBlockSize ?? "0"),
-            "--phi-root-scaffold-max-width": resolvePhiRootNodeCssSize(normalizedRootNode.rootNodeGeometry?.maxSize?.width, "none"),
-            "--phi-root-scaffold-max-height": resolvePhiRootNodeCssSize(normalizedRootNode.rootNodeGeometry?.maxSize?.height, "none"),
-            "--phi-root-scaffold-flex": normalizedRootNode.rootNodeGeometry?.size?.width != null || normalizedRootNode.rootNodeGeometry?.size?.height != null ? "0 0 auto" : "1 1 auto",
-            "--phi-root-scaffold-explicit-width": resolvePhiRootNodeCssSize(normalizedRootNode.rootNodeGeometry?.size?.width, "auto"),
-            "--phi-root-scaffold-explicit-height": resolvePhiRootNodeCssSize(normalizedRootNode.rootNodeGeometry?.size?.height, "auto"),
+    const renderRootDrawer = (child, definitionTitle) => (_jsx(PhiEditScaffoldDrawer, { className: "phi-builder-root-scaffold", kind: "layout", nodeId: normalizedRootNode.id, regionKey: regionKey, title: rootTitle, scaffoldLabel: formatLayoutScaffoldLabel(normalizedRootNode.typeKey, normalizedRootNode.kind, definitionTitle, normalizedRootNode.title), packageName: rootPackageName, style: {
+            ...resolvePhiRootScaffoldProperties(rootGeometry),
         }, onClick: onOpenInspector
             ? () => onOpenInspector({
                 nodeId: normalizedRootNode.id ?? null,
@@ -839,7 +912,8 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
     const renderChildLayoutNode = (node) => {
         const nodeKind = "layout";
         const rootProps = resolveLayoutNodeRootProps(node);
-        return (_jsx(PhiAuthoringLayoutEffectsPreviewFrame, { type: node.widgetType, kind: nodeKind, blockId: node.id, config: node.config, explicitInlineSize: rootProps.rootNodeGeometry?.size?.width != null, explicitBlockSize: rootProps.rootNodeGeometry?.size?.height != null, children: renderPhiRootNodeScaffold({ ...rootProps, regionKey }, (options) => onOpenInsert?.({
+        const rootPropsGeometry = resolvePhiRenderableBlockGeometry(rootProps.rootNodeGeometry);
+        return (_jsx(PhiAuthoringLayoutEffectsPreviewFrame, { type: node.widgetType, kind: nodeKind, blockId: node.id, config: node.config, explicitInlineSize: rootPropsGeometry.explicitInline, explicitBlockSize: rootPropsGeometry.explicitBlock, children: renderPhiRootNodeScaffold({ ...rootProps, regionKey }, (options) => onOpenInsert?.({
                 ...options,
                 slotIndex: options?.slotIndex ?? 0,
                 targetNodeId: node.id,
@@ -854,6 +928,18 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
                 nodeKind: options?.nodeKind ?? nodeKind,
             }), onUpdateWidgetNodeConfig, onUpdateLayoutNodeConfig, {
                 effectsLabels: options?.effectsLabels,
+                /*
+                 * The canvas and the tool captions travel down with the recursion.
+                 *
+                 * A nested Layout is drawn by this same function, and what it is not handed it cannot hand
+                 * on. Without the canvas every Widget below it is rendered with `authoring: null`, so its
+                 * editor comes up read-only, the scaffold's click finds no text target in it and authoring
+                 * cannot be entered at all -- a Widget one Layout deeper was editable through the Inspector
+                 * only. Without the captions the nested scaffold's own provider resets the Builder's tools
+                 * to their default English.
+                 */
+                authoringToolsLabels: options?.authoringToolsLabels,
+                authoringCanvas: options?.authoringCanvas,
                 demandControllerContext,
                 inheritedViewportFlags: resolvedViewportFlags,
                 draggable: true,
@@ -863,7 +949,7 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
                 renderInsertPicker: options?.renderInsertPicker,
             }) }));
     };
-    return (_jsx(PhiAuthoringLayoutLoader, { type: normalizedRootNode.typeKey, kind: "layout", blockId: normalizedRootNode.id ?? -1, children: (plugin, definition, widgetDefinitionsByType) => {
+    const scaffold = (_jsx(PhiAuthoringLayoutLoader, { type: normalizedRootNode.typeKey, kind: "layout", blockId: normalizedRootNode.id ?? -1, children: (plugin, definition, widgetDefinitionsByType) => {
             const rendered = resolvePhiRootNodeRenderedBody(normalizedRootNode, "editor", plugin, definition, widgetDefinitionsByType, regionKey, renderChildLayoutNode, onDeleteRootNode
                 ? (widget) => onDeleteRootNode({
                     nodeId: widget.id,
@@ -911,6 +997,7 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
                 paddingLeft: normalizedRootNode.rootNodePadding?.paddingLeft ?? undefined,
                 style: resolveRootNodeChromeStyle({
                     background: normalizedRootNode.rootNodeBackground,
+                    borderSource: readPhiCmsBorderSource(normalizedRootNode.rootNodeConfig?.borderSource),
                     border: normalizedRootNode.rootNodeBorder,
                     shadow: normalizedRootNode.rootNodeShadow,
                     style: rendered.props.style,
@@ -919,10 +1006,12 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
                 rootNodeBorder: normalizedRootNode.rootNodeBorder ?? null,
             }), definition.title);
         } }));
+    return (_jsx(PhiAuthoringToolsLabelsProvider, { labels: options?.authoringToolsLabels, children: _jsx(PhiBuilderPageReferencesProvider, { children: scaffold }) }));
 }
 export function renderPhiRootNodePreview(rootNode) {
     const normalizedRootNode = normalizePhiBuilderRootNodeDraft(rootNode);
-    return (_jsx(PhiSlotChildFrame, { className: "phi-builder-root-scaffold__slot", kind: resolveRootNodeSlotChildKind(normalizedRootNode.kind), blockId: normalizedRootNode.id ?? null, explicitInlineSize: normalizedRootNode.rootNodeGeometry?.size?.width != null, explicitBlockSize: normalizedRootNode.rootNodeGeometry?.size?.height != null, config: normalizedRootNode.rootNodeConfig, children: _jsx(PhiAuthoringLayoutLoader, { type: normalizedRootNode.typeKey, kind: "layout", blockId: normalizedRootNode.id ?? null, children: (plugin, definition, widgetDefinitionsByType) => {
+    const rootGeometry = resolvePhiRenderableBlockGeometry(normalizedRootNode.rootNodeGeometry);
+    return (_jsx(PhiSlotChildFrame, { className: "phi-builder-root-scaffold__slot", kind: resolveRootNodeSlotChildKind(normalizedRootNode.kind), blockId: normalizedRootNode.id ?? null, explicitInlineSize: rootGeometry.explicitInline, explicitBlockSize: rootGeometry.explicitBlock, config: normalizedRootNode.rootNodeConfig, children: _jsx(PhiAuthoringLayoutLoader, { type: normalizedRootNode.typeKey, kind: "layout", blockId: normalizedRootNode.id ?? null, children: (plugin, definition, widgetDefinitionsByType) => {
                 const rendered = resolvePhiRootNodeRenderedBody(normalizedRootNode, "preview", plugin, definition, widgetDefinitionsByType, null);
                 if (rendered == null) {
                     return null;
@@ -939,6 +1028,7 @@ export function renderPhiRootNodePreview(rootNode) {
                         paddingLeft: normalizedRootNode.rootNodePadding?.paddingLeft ?? undefined,
                         style: resolveRootNodeChromeStyle({
                             background: normalizedRootNode.rootNodeBackground,
+                            borderSource: readPhiCmsBorderSource(normalizedRootNode.rootNodeConfig?.borderSource),
                             border: normalizedRootNode.rootNodeBorder,
                             shadow: normalizedRootNode.rootNodeShadow,
                             style: rendered.props.style,

package/plugins/runtime-modules/builder/root-node-normalization.d.ts

@@ -5,7 +5,7 @@ import type { PhiCmsGeometryWidgetConfig } from "../../../components/widgets/con
 import { type PhiAnchorWidgetPlacement } from "../../../components/controls/phi-anchor-control-contract";
 import type { PhiRenderableBlockRenderMode } from "../../../types";
 import type { PhiCmsInstanceId } from "../../../types/cms-instance-id";
-import type { PhiBuilderRootNodeKind } from "./preview-transport";
+import type { PhiBuilderPreviewRegionDraft, PhiBuilderRootNodeKind } from "./preview-transport";
 import { type PhiShadow } from "../../../types/layout-style";
 export type PhiBuilderRootNodeDraft = {
     id?: PhiCmsInstanceId | null;
@@ -23,6 +23,11 @@ export type PhiBuilderRootNodeDraft = {
     childLayouts?: PhiCmsLayoutRenderNode[];
     childWidgets?: PhiCmsContentWidgetNode[];
 };
+/**
+ * What a region draft says about its root node, as a root node draft reads it: every field but the ones
+ * that name the node (`id`, `typeKey`, `kind`, `packageName`), which each caller answers for itself.
+ */
+export declare function readPhiBuilderRootNodeDraftFields(draft: Pick<PhiBuilderPreviewRegionDraft, "rootNodeTitle" | "rootNodeConfig" | "rootNodeGeometry" | "rootNodeAnchor" | "rootNodePadding" | "rootNodeBackground" | "rootNodeBorder" | "rootNodeShadow" | "rootNodeChildLayouts" | "rootNodeChildWidgets">): Omit<PhiBuilderRootNodeDraft, "id" | "typeKey" | "kind" | "packageName">;
 export type PhiBuilderRootNodeDefaults = {
     rootNodePadding: PhiCmsPaddingWidgetConfig | null;
     rootNodeBackground: PhiCmsBackgroundWidgetConfig | null;