@bsuite/page-builder 2.7.1-next.5 → 2.7.1-next.7

package/README.md

@@ -71,6 +71,15 @@ stays flat. Consumers must read all three variables; chrome-owning grid items
 already do. Default painted grid cards now use neutral elevation 2, with
 interaction feedback, matching the D2C card recovery.
 
+From `2.7.1-next.6`, app Cards import `useCardPadding` and
+`CardPaddingBoundary` from `@bsuite/page-builder/card-padding`. Read the
+inset before rendering the Card, apply a defined value to its painted surface,
+and wrap its children with a boundary without a padding prop. Inner Cards then
+keep their spacing; a nested grid establishes its own independent inset.
+The grid supplies no child inset when it paints chrome itself. This replaces
+consumer CSS `@scope` rules, which do not cover the supported Safari/Firefox
+baseline. The subpath keeps a standalone Card import separate from grid code.
+
 While the canvas editor is open, each grid item renders an in-flow strip
 (`[data-slot="grid-item-editor-chrome"]`) above the card content: the widget
 name and a Hide control. The strip is **not** absolutely positioned over the

package/dist/PageGridLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PageGridLayout.d.ts","sourceRoot":"","sources":["../src/PageGridLayout.tsx"],"names":[],"mappings":"AAEA,OAAO,KAQN,MAAM,OAAO,CAAC;AAGf,OAAO,kCAAkC,CAAC;AAC1C,OAAO,gCAAgC,CAAC;AAsBxC,OAAO,KAAK,EAAe,mBAAmB,EAA4B,MAAM,YAAY,CAAC;AAE7F,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAC5D,MAAM,WAAW,uBAAuB;IAAG,OAAO,EAAE,MAAM,CAAA;CAAE;AAiqB5D,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,EACP,UAAU,EACV,SAAS,EAMT,WAAkB,EAClB,aAAsC,EACtC,QAAQ,EACR,iBAAiB,EACjB,gBAAgB,EAKhB,UAAkB,EAClB,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,+BAA6E,EAC7E,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,EAAE,mBAAmB,qBAkhCrB"}
+{"version":3,"file":"PageGridLayout.d.ts","sourceRoot":"","sources":["../src/PageGridLayout.tsx"],"names":[],"mappings":"AAGA,OAAO,KAQN,MAAM,OAAO,CAAC;AAGf,OAAO,kCAAkC,CAAC;AAC1C,OAAO,gCAAgC,CAAC;AAsBxC,OAAO,KAAK,EAAe,mBAAmB,EAA4B,MAAM,YAAY,CAAC;AAE7F,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAC5D,MAAM,WAAW,uBAAuB;IAAG,OAAO,EAAE,MAAM,CAAA;CAAE;AAmrB5D,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,EACP,UAAU,EACV,SAAS,EAMT,WAAkB,EAClB,aAAsC,EACtC,QAAQ,EACR,iBAAiB,EACjB,gBAAgB,EAKhB,UAAkB,EAClB,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,+BAA6E,EAC7E,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,EAAE,mBAAmB,qBAoqCrB"}

package/dist/PageGridLayout.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { ElementScopeProvider } from './elementScope.js';
-import { ArrowDown, ArrowUp, ChevronDown, ChevronUp, Eye, EyeOff, Layers, LayoutGrid, Lock, Plus, RotateCcw, Save, Settings2, Unlock } from 'lucide-react';
+import { CardPaddingBoundary } from './cardPadding.js';
+import { ArrowDown, ArrowUp, ChevronDown, ChevronUp, Eye, EyeOff, Layers, LayoutGrid, Lock, Plus, RefreshCw, RotateCcw, Save, Settings2, Unlock, X } from 'lucide-react';
 import React, { startTransition, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Responsive } from 'react-grid-layout';
 import { gridBounds, minMaxSize, minSize } from 'react-grid-layout/core';
@@ -10,7 +11,7 @@ import { computeAutoHeightRows } from './autoHeight.js';
 import { BORDER_STYLES, BORDER_TONES, BORDER_WIDTH_RANGE, DEFAULT_CARD_STYLE, PADDING_RANGE, RADIUS_RANGE, describeCardStyle, isDefaultCardStyle, normaliseCardStyle, toCssVars, } from './cardStyle.js';
 import { defaultPreferenceAdapter } from './preferences.js';
 import { isRelationshipWritable } from './relationshipCatalog.js';
-import { usePageGridLayout } from './usePageGridLayout.js';
+import { combinePreferenceStatuses, preferenceStatusOf, usePageGridLayout } from './usePageGridLayout.js';
 import { cn } from './utils.js';
 /** Ask one mounted canvas to acknowledge its preferences before closing. */
 export const PAGE_GRID_SAVE_EVENT = 'bsuite-page-grid-save';
@@ -130,8 +131,8 @@ const RGLResizeHandle = React.forwardRef(function RGLResizeHandle({ axis = 'se',
  * scroll away. Drag still starts from the strip (outer `.drag-handle`); hide
  * is a `button` + `data-no-drag` so the existing cancel selector ignores it.
  */
-function GridItemEditorChrome({ id, label, onHide, }) {
-    return (_jsxs("div", { "data-slot": "grid-item-editor-chrome", className: "flex min-w-0 flex-none items-center gap-1 px-2 py-1 bg-muted text-muted-foreground", children: [_jsx("span", { className: "min-w-0 truncate text-[10px] px-1.5 py-0.5 rounded-md font-medium", title: label, children: label }), _jsx("button", { type: "button", className: "ml-auto h-6 w-6 shrink-0 rounded-full flex items-center justify-center bg-destructive hover:bg-destructive text-destructive-foreground shadow transition-colors", "data-no-drag": true, onPointerDown: (event) => event.stopPropagation(), onClick: (event) => {
+function GridItemEditorChrome({ id, label, onHide, hideDisabled = false, }) {
+    return (_jsxs("div", { "data-slot": "grid-item-editor-chrome", className: "flex min-w-0 flex-none items-center gap-1 px-2 py-1 bg-muted text-muted-foreground", children: [_jsx("span", { className: "min-w-0 truncate text-[10px] px-1.5 py-0.5 rounded-md font-medium", title: label, children: label }), _jsx("button", { type: "button", className: "ml-auto h-6 w-6 shrink-0 rounded-full flex items-center justify-center bg-destructive hover:bg-destructive text-destructive-foreground shadow transition-colors disabled:opacity-50 disabled:pointer-events-none", disabled: hideDisabled, "data-no-drag": true, onPointerDown: (event) => event.stopPropagation(), onClick: (event) => {
                     event.stopPropagation();
                     onHide(id);
                 }, title: `Hide ${label}`, "aria-label": `Hide ${label}`, children: _jsx(EyeOff, { className: "h-3 w-3", "aria-hidden": "true" }) })] }));
@@ -168,7 +169,7 @@ function warnOnceAboutCollapsedContent(el) {
         + '(an aspect ratio, a px/rem height, or min-height), or pass autoHeight={false} on '
         + 'this card so it renders into the constrained scrollable wrapper instead.');
 }
-const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, isEditing, label, pageKey, onHide, autoHeight, onAutoHeightChange, chrome = false, cardStyleVars, children: injectedChildren, className: injectedClassName, style: injectedStyle, ...rest }, ref) {
+const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, isEditing, label, pageKey, onHide, editingPaused = false, autoHeight, onAutoHeightChange, chrome = false, cardStyleVars, children: injectedChildren, className: injectedClassName, style: injectedStyle, ...rest }, ref) {
     // Auto-height measurement (blueprint amendment A1). `measureRef` wraps
     // `content` with NO height constraint of its own — its parent has
     // `overflow-hidden` + `flex-1 min-h-0` (clips *painting* to the current
@@ -187,7 +188,10 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
      * of card overflow across 70 sites. An extra element here would have been a
      * real risk; a provider is not one.
      */
-    const scopedContent = (_jsx(ElementScopeProvider, { scope: { pageKey, cardKey: id, cardLabel: label, isEditing }, children: content }));
+    const cardPadding = !chrome && cardStyleVars && '--card-padding' in cardStyleVars
+        && typeof cardStyleVars['--card-padding'] === 'string'
+        ? cardStyleVars['--card-padding'] : undefined;
+    const scopedContent = (_jsx(ElementScopeProvider, { scope: { pageKey, cardKey: id, cardLabel: label, isEditing }, children: _jsx(CardPaddingBoundary, { padding: cardPadding, children: content }) }));
     const measureRef = useRef(null);
     const surfaceRef = useRef(null);
     const lastReportedRowsRef = useRef(null);
@@ -317,7 +321,9 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
     // the GridItem has it as an ancestor → drag fires. Interactive elements
     // (buttons, inputs, textarea, select, links, [data-no-drag]) are still
     // protected via the `cancel` selector below in the <Responsive> render.
-    const outerClass = cn('relative group overflow-visible', isEditing && 'drag-handle cursor-move', injectedClassName);
+    const outerClass = cn('relative group overflow-visible', isEditing && 'drag-handle', 
+    // Paused editing (bsuite#3277) cannot move a card, so it must not promise to.
+    isEditing && !editingPaused && 'cursor-move', injectedClassName);
     return (_jsxs("div", { ref: ref, className: outerClass, style: injectedStyle, ...rest, children: [_jsxs("div", { className: "h-full w-full relative", children: [isEditing && (_jsx("div", { className: "absolute inset-0 z-10 pointer-events-none rounded-3xl border-2 border-transparent group-hover:border-primary/50 transition-colors bg-primary/5" })), _jsx("div", { "data-slot": "grid-item-surface", "data-chrome": chrome ? 'on' : 'off', "data-grid-slot-key": id, ref: surfaceRef, "data-card-padding": !chrome && cardStyleVars && '--card-padding' in cardStyleVars ? '' : undefined, className: chrome
                             ? // ONE radius token, read by the grid item AND available to any
                                 // app card that opts into the same surface. Two surfaces
@@ -376,7 +382,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
                             ...(chrome && cardStyleVars && '--card-padding' in cardStyleVars
                                 ? { padding: cardStyleVars['--card-padding'] }
                                 : null),
-                        }, children: autoHeight ? (_jsx("div", { "data-slot": "grid-item-body", className: "min-h-0 flex-none overflow-visible", children: _jsxs("div", { ref: measureRef, className: "flow-root", children: [isEditing ? (_jsx(GridItemEditorChrome, { id: id, label: label, onHide: onHide })) : null, scopedContent] }) })) : (_jsxs(_Fragment, { children: [isEditing ? (_jsx(GridItemEditorChrome, { id: id, label: label, onHide: onHide })) : null, _jsx("div", { "data-slot": "grid-item-body", className: "min-h-0 flex-1 overflow-auto", children: scopedContent })] })) })] }), injectedChildren] }));
+                        }, children: autoHeight ? (_jsx("div", { "data-slot": "grid-item-body", className: "min-h-0 flex-none overflow-visible", children: _jsxs("div", { ref: measureRef, className: "flow-root", children: [isEditing ? (_jsx(GridItemEditorChrome, { id: id, label: label, onHide: onHide, hideDisabled: editingPaused })) : null, scopedContent] }) })) : (_jsxs(_Fragment, { children: [isEditing ? (_jsx(GridItemEditorChrome, { id: id, label: label, onHide: onHide, hideDisabled: editingPaused })) : null, _jsx("div", { "data-slot": "grid-item-body", className: "min-h-0 flex-1 overflow-auto", children: scopedContent })] })) })] }), injectedChildren] }));
 }));
 export function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVersion, canEditPage, editorEventNames, preferenceAdapter, widgets, widgetMeta, className, 
 // Resize default flipped 2026-05-12: rgl v2 dropped auto-handle rendering
@@ -390,7 +396,7 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, defaultAut
 // `itemChrome` to get the pre-2.0.0 behaviour back for every slot, and
 // migrates page by page with the per-item `chrome` flag.
 itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_NAMES, createEntityWidget, onRegisterEntityWidget, relationshipCatalog, addRelationshipWidgetEventNames = DEFAULT_ADD_RELATIONSHIP_WIDGET_EVENT_NAMES, createRelationshipWidget, onRegisterRelationshipWidget, onRelationshipWidgetRejected, }) {
-    const { currentLayouts, layoutCols, isEditing, setIsEditing, flushPreferences, activeCols, activeCompactor, onLayoutChange, handleColumnChange, handleBreakpointChange, handleCompact, handleReset, addWidget, moveWidget, setWidgetLocked, applyAutoHeightRows, autoHeightRows, resetConfirmOpen, setResetConfirmOpen, containerRef, containerWidth, } = usePageGridLayout({
+    const { currentLayouts, layoutCols, isEditing, setIsEditing, flushPreferences, preferencesStatus, canRetryPreferences, retryPreferences, activeCols, activeCompactor, onLayoutChange, handleColumnChange, handleBreakpointChange, handleCompact, handleReset, addWidget, moveWidget, setWidgetLocked, applyAutoHeightRows, autoHeightRows, resetConfirmOpen, setResetConfirmOpen, containerRef, containerWidth, } = usePageGridLayout({
         pageKey,
         defaultLayouts,
         defaultCols,
@@ -465,7 +471,6 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
             autoHeightFrameRef.current = scheduleFrame(flushAutoHeightUpdates);
         }
     }, [flushAutoHeightUpdates, scheduleFrame]);
-    const resizeEnabled = isEditing && isResizable;
     const resizeConstraints = useMemo(() => [
         // `gridBounds` caps width at the active column count, so we don't need
         // a global maxSize(...). Width and height are unbounded by default;
@@ -477,8 +482,10 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
     ], []);
     const [extraWidgetConfigs, setExtraWidgetConfigs] = useState({});
     const [extraRelationshipWidgetConfigs, setExtraRelationshipWidgetConfigs] = useState({});
-    const { value: layerNames, setValue: setLayerNames, flush: flushLayerNames } = (preferenceAdapter ?? defaultPreferenceAdapter)(`page:${pageKey}_grid_layer_names`, {});
-    const { value: hiddenLayerIds, setValue: setHiddenLayerIds, flush: flushHiddenLayers } = (preferenceAdapter ?? defaultPreferenceAdapter)(`page:${pageKey}_grid_hidden_layers`, {});
+    const layerNamesPreference = (preferenceAdapter ?? defaultPreferenceAdapter)(`page:${pageKey}_grid_layer_names`, {});
+    const { value: layerNames, setValue: setLayerNames, flush: flushLayerNames } = layerNamesPreference;
+    const hiddenLayersPreference = (preferenceAdapter ?? defaultPreferenceAdapter)(`page:${pageKey}_grid_hidden_layers`, {});
+    const { value: hiddenLayerIds, setValue: setHiddenLayerIds, flush: flushHiddenLayers } = hiddenLayersPreference;
     /*
      * Card appearance, per page, persisted beside the layout.
      *
@@ -486,13 +493,92 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
      * survives a reload, follows the operator across devices wherever the app
      * backs the adapter with the database, and needs no new storage concept.
      */
-    const { value: storedCardStyle, setValue: setStoredCardStyle, flush: flushCardStyle } = (preferenceAdapter ?? defaultPreferenceAdapter)(`page:${pageKey}_card_style`, DEFAULT_CARD_STYLE);
+    const cardStylePreference = (preferenceAdapter ?? defaultPreferenceAdapter)(`page:${pageKey}_card_style`, DEFAULT_CARD_STYLE);
+    const { value: storedCardStyle, setValue: setStoredCardStyle, flush: flushCardStyle } = cardStylePreference;
+    /*
+     * THE EDIT GATE (bsuite#3277).
+     *
+     * The hook refuses every write while any of ITS keys is loading or failed.
+     * This canvas reads and writes three more keys the hook never sees — layer
+     * names, hidden layers and card appearance — so the same rule is applied to
+     * them here, and the two are combined into the one state the editor shows.
+     *
+     * While it is not `'loaded'` the editor stays open but PAUSED: the banner says
+     * why, a failed read offers Retry, every control in the banner body is
+     * disabled by a single `<fieldset disabled>` (so a control added later cannot
+     * forget the gate), drag/resize/hide are off, and every write path in this
+     * component is refused underneath the disabled controls as well.
+     *
+     * Retry is in place. It calls `retry` on each FAILED key's adapter — the
+     * hook's four through `retryPreferences`, this component's three directly —
+     * and nothing else: no remount, no key change, no reset. The editor, its
+     * expanded/collapsed state and everything already loaded stay exactly as they
+     * are; the pause lifts on the render in which the last failed key loads.
+     */
+    const layerNamesStatus = preferenceStatusOf(layerNamesPreference);
+    const hiddenLayersStatus = preferenceStatusOf(hiddenLayersPreference);
+    const cardStyleStatus = preferenceStatusOf(cardStylePreference);
+    const editingPreferencesStatus = combinePreferenceStatuses([
+        preferencesStatus,
+        layerNamesStatus,
+        hiddenLayersStatus,
+        cardStyleStatus,
+    ]);
+    const editingPaused = editingPreferencesStatus !== 'loaded';
+    const resizeEnabled = isEditing && isResizable && !editingPaused;
+    const { retry: retryLayerNames } = layerNamesPreference;
+    const { retry: retryHiddenLayers } = hiddenLayersPreference;
+    const { retry: retryCardStyle } = cardStylePreference;
+    const canRetryEditingPreferences = canRetryPreferences ||
+        (layerNamesStatus === 'failed' && typeof retryLayerNames === 'function') ||
+        (hiddenLayersStatus === 'failed' && typeof retryHiddenLayers === 'function') ||
+        (cardStyleStatus === 'failed' && typeof retryCardStyle === 'function');
+    // Keyed by page so a retry on one page never says "still" about another.
+    const [retriedPage, setRetriedPage] = useState(null);
+    const retriedAndStillFailed = retriedPage === pageKey && editingPreferencesStatus === 'failed';
+    const retryEditingPreferences = useCallback(() => {
+        setRetriedPage(pageKey);
+        retryPreferences();
+        if (layerNamesStatus === 'failed')
+            retryLayerNames?.();
+        if (hiddenLayersStatus === 'failed')
+            retryHiddenLayers?.();
+        if (cardStyleStatus === 'failed')
+            retryCardStyle?.();
+    }, [
+        cardStyleStatus,
+        hiddenLayersStatus,
+        layerNamesStatus,
+        pageKey,
+        retryCardStyle,
+        retryHiddenLayers,
+        retryLayerNames,
+        retryPreferences,
+    ]);
     const cardStyle = useMemo(() => normaliseCardStyle(storedCardStyle), [storedCardStyle]);
     const cardStyleVars = useMemo(() => toCssVars(cardStyle), [cardStyle]);
-    const updateCardStyle = useCallback((patch) => setStoredCardStyle((previous) => ({ ...normaliseCardStyle(previous), ...patch })), [setStoredCardStyle]);
+    const updateCardStyle = useCallback((patch) => {
+        if (editingPaused)
+            return;
+        setStoredCardStyle((previous) => ({ ...normaliseCardStyle(previous), ...patch }));
+    }, [editingPaused, setStoredCardStyle]);
+    const resetCardStyle = useCallback(() => {
+        if (editingPaused)
+            return;
+        setStoredCardStyle({ ...DEFAULT_CARD_STYLE });
+    }, [editingPaused, setStoredCardStyle]);
     const saveAndExit = useCallback(async () => {
         if (canEditPage === false || !isEditing || savingAttempt.current !== null)
             return;
+        if (editingPaused) {
+            // Every write is refused while paused, so the paused keys hold nothing to
+            // save. Flushing them would only let an adapter that refuses to flush a
+            // failed key hold the user in an editor they cannot use. (A write made
+            // before the pause — the page switched mid-session — is already with its
+            // adapter and keeps saving there; exiting does not cancel it.)
+            startTransition(() => setIsEditing(false));
+            return;
+        }
         const attempt = ++saveAttempt.current;
         savingAttempt.current = attempt;
         setSaveState({ pageKey, status: 'saving' });
@@ -511,7 +597,7 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
             if (savingAttempt.current === attempt)
                 savingAttempt.current = null;
         }
-    }, [canEditPage, isEditing, pageKey, flushPreferences, flushLayerNames, flushHiddenLayers, flushCardStyle, setIsEditing]);
+    }, [canEditPage, isEditing, editingPaused, pageKey, flushPreferences, flushLayerNames, flushHiddenLayers, flushCardStyle, setIsEditing]);
     useEffect(() => {
         const onSaveRequest = (event) => {
             const detail = event.detail;
@@ -666,10 +752,17 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
         }
         return filtered;
     }, [autoHeightRows, currentLayouts, hiddenLayerIds, renderableWidgetKeys]);
+    // Every write below is refused while editing is paused (bsuite#3277) — the
+    // controls that reach them are disabled too, but a disabled control is a
+    // presentation; the refusal is the guarantee.
     const hideLayer = (layerId) => {
+        if (editingPaused)
+            return;
         setHiddenLayerIds((previous) => ({ ...previous, [layerId]: true }));
     };
     const showLayer = (layerId, defaultSize) => {
+        if (editingPaused)
+            return;
         setHiddenLayerIds((previous) => {
             if (!previous[layerId])
                 return previous;
@@ -688,6 +781,12 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
             const detail = event.detail;
             if (!detail?.entityType)
                 return;
+            if (editingPaused) {
+                // Nothing is registered or added while paused; the user lands in the
+                // editor, where the reason and Retry are shown.
+                startTransition(() => setIsEditing(true));
+                return;
+            }
             const widgetId = `entity:${detail.entityType}`;
             const alreadyInLayout = activeLayouts.lg?.some((item) => item.i === widgetId);
             if (alreadyInLayout) {
@@ -715,6 +814,7 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
         addEntityWidgetEventNames,
         addWidget,
         createEntityWidget,
+        editingPaused,
         onRegisterEntityWidget,
         setIsEditing,
     ]);
@@ -733,6 +833,10 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
             const detail = event.detail;
             if (!detail?.hostEntityType || !detail.fkColumn || !detail.targetEntityType)
                 return;
+            if (editingPaused) {
+                startTransition(() => setIsEditing(true));
+                return;
+            }
             if (!isRelationshipWritable(relationshipCatalog, detail)) {
                 onRelationshipWidgetRejected?.(detail);
                 return;
@@ -764,6 +868,7 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
         addRelationshipWidgetEventNames,
         addWidget,
         createRelationshipWidget,
+        editingPaused,
         onRegisterRelationshipWidget,
         onRelationshipWidgetRejected,
         relationshipCatalog,
@@ -782,6 +887,8 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
         };
     }), [activeLayouts.lg, layerNames, widgetMeta]);
     const handleLayerRename = (layerId, value) => {
+        if (editingPaused)
+            return;
         const trimmed = value.trim();
         setLayerNames((previous) => {
             if (trimmed.length === 0) {
@@ -878,13 +985,18 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
                 // partially visible — mitigates Issue 2 (banner consuming
                 // vertical space). `bg-card/95` + `backdrop-blur` keeps text
                 // legible while showing form context behind the banner.
-                'bg-card/95 supports-[backdrop-filter]:bg-card/80 backdrop-blur border-primary'), role: "region", "aria-label": "Canvas editor controls", "aria-busy": isSaving, children: [_jsxs("div", { className: "flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3", children: [_jsxs("div", { className: "flex items-center gap-3", children: [_jsx("div", { className: cn('rounded-full flex items-center justify-center bg-primary/10', controlsCollapsed ? 'h-8 w-8' : 'h-10 w-10 animate-pulse'), children: _jsx(Settings2, { className: cn('text-primary', controlsCollapsed ? 'h-4 w-4' : 'h-5 w-5') }) }), _jsxs("div", { children: [_jsx("h3", { className: cn('font-semibold text-foreground', controlsCollapsed ? 'text-sm' : 'text-lg'), children: "Canvas Editor Active" }), !controlsCollapsed && (_jsx("span", { className: "text-sm text-muted-foreground", children: "Drag anywhere on a card to move it. Resize with the bottom-right handle." }))] })] }), _jsxs("div", { className: "flex items-center gap-2 shrink-0", children: [_jsxs("button", { type: "button", className: "inline-flex items-center gap-1 rounded-md border border-border-interactive px-2 py-2 text-sm text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", "aria-expanded": !controlsCollapsed, "aria-controls": "page-grid-editor-controls-body", "aria-label": controlsCollapsed ? 'Expand controls: columns, cards and layers' : 'Collapse controls', onClick: () => setControlsCollapsed((previous) => !previous), children: [controlsCollapsed ? _jsx(ChevronDown, { className: "h-4 w-4" }) : _jsx(ChevronUp, { className: "h-4 w-4" }), _jsx("span", { className: "sr-only sm:not-sr-only", children: controlsCollapsed ? 'Columns, cards & layers' : 'Collapse' })] }), _jsxs("button", { type: "button", className: "inline-flex items-center rounded-md px-3 py-2 text-sm font-medium bg-primary text-primary-foreground shadow transition-colors hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", disabled: isSaving, onClick: () => { void saveAndExit(); }, children: [_jsx(Save, { className: "h-4 w-4 mr-2" }), isSaving ? 'Saving…' : 'Save & Exit'] })] })] }), saveFailed && (_jsx("p", { role: "alert", className: "mt-2 text-sm text-destructive", children: "Changes could not be saved. Your changes are still here. Try Save & Exit again." })), _jsxs("div", { id: "page-grid-editor-controls-body", hidden: controlsCollapsed, className: "flex flex-wrap items-center gap-x-4 gap-y-2 pt-2 border-t border-border max-h-[60vh] overflow-y-auto", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(LayoutGrid, { className: "h-4 w-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "text-sm shrink-0 text-muted-foreground", children: "Columns:" }), _jsx("input", { type: "range", min: 1, max: 24, value: layoutCols, onChange: (event) => handleColumnChange(Number(event.target.value)), className: "w-24 cursor-pointer accent-primary", "aria-label": "Column count" }), _jsx("span", { className: "text-sm font-mono w-5 text-center tabular-nums", children: layoutCols })] }), _jsx("div", { className: "flex items-center gap-1", role: "group", "aria-label": "Column presets", children: [1, 2, 3, 4, 6, 12].map((columnCount) => (_jsx("button", { type: "button", onClick: () => handleColumnChange(columnCount), "data-active": layoutCols === columnCount || undefined, "aria-pressed": layoutCols === columnCount, className: cn('px-2 py-0.5 rounded text-xs font-medium transition-colors border', 'bg-muted text-muted-foreground border-border-interactive', 'hover:bg-muted/80 hover:text-foreground', 'data-[active]:bg-primary data-[active]:text-primary-foreground data-[active]:border-primary', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: columnCount }, columnCount))) }), _jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-2 w-full pt-2 border-t border-border", role: "group", "aria-label": "Card appearance", children: [_jsx("span", { className: "text-sm shrink-0 font-medium text-foreground", children: "Card:" }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "text-sm text-muted-foreground", children: "Corners" }), _jsx("input", { type: "range", min: RADIUS_RANGE.min, max: RADIUS_RANGE.max, value: cardStyle.radius, onChange: (event) => updateCardStyle({ radius: Number(event.target.value) }), className: "w-20 cursor-pointer accent-primary", "aria-label": "Card corner radius in pixels" }), _jsx("span", { className: "text-sm font-mono w-8 text-right tabular-nums", children: cardStyle.radius })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "text-sm text-muted-foreground", children: "Border" }), _jsx("input", { type: "range", min: BORDER_WIDTH_RANGE.min, max: BORDER_WIDTH_RANGE.max, value: cardStyle.borderWidth, onChange: (event) => updateCardStyle({ borderWidth: Number(event.target.value) }), className: "w-16 cursor-pointer accent-primary", "aria-label": "Card border width in pixels" }), _jsx("span", { className: "text-sm font-mono w-6 text-right tabular-nums", children: cardStyle.borderWidth })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "sr-only", children: "Border colour" }), _jsx("select", { value: cardStyle.borderTone, onChange: (event) => updateCardStyle({ borderTone: event.target.value }), className: "rounded-md border border-border-interactive bg-background px-2 py-1 text-sm text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", "aria-label": "Card border colour", children: BORDER_TONES.map((tone) => (_jsx("option", { value: tone, children: tone === 'border' ? 'default colour' : tone }, tone))) })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "sr-only", children: "Border style" }), _jsx("select", { value: cardStyle.borderStyle, onChange: (event) => updateCardStyle({ borderStyle: event.target.value }), className: "rounded-md border border-border-interactive bg-background px-2 py-1 text-sm text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", "aria-label": "Card border style", children: BORDER_STYLES.map((style) => (_jsx("option", { value: style, children: style }, style))) })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "sr-only", children: "Card shadow" }), _jsxs("select", { value: cardStyle.elevation === null ? 'default' : String(cardStyle.elevation), onChange: (event) => updateCardStyle({
-                                                    elevation: event.target.value === 'default' ? null : Number(event.target.value),
-                                                }), className: "rounded-md border border-border-interactive bg-background px-2 py-1 text-sm text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", "aria-label": "Card shadow depth", children: [_jsx("option", { value: "default", children: "default shadow" }), [0, 1, 2, 3, 4].map((level) => (_jsx("option", { value: level, children: level === 0 ? 'no shadow' : `shadow ${level}` }, level)))] })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "text-sm text-muted-foreground", children: "Padding" }), _jsx("input", { type: "range", min: PADDING_RANGE.min, max: PADDING_RANGE.max, value: cardStyle.padding ?? 0, onChange: (event) => updateCardStyle({ padding: Number(event.target.value) }), className: "w-16 cursor-pointer accent-primary", "aria-label": "Card inner padding in pixels" }), _jsx("span", { className: "text-sm font-mono w-8 text-right tabular-nums", children: cardStyle.padding === null ? '\u2014' : cardStyle.padding })] }), _jsxs("button", { type: "button", onClick: () => setStoredCardStyle({ ...DEFAULT_CARD_STYLE }), disabled: isDefaultCardStyle(cardStyle), className: "inline-flex items-center gap-1 rounded-md border border-border-interactive px-2 py-1 text-sm text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-50 disabled:pointer-events-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", children: [_jsx(RotateCcw, { className: "h-3.5 w-3.5" }), "Reset cards"] }), _jsx("output", { className: "text-sm text-muted-foreground", "aria-live": "polite", children: describeCardStyle(cardStyle) })] }), hiddenWidgetKeys.length > 0 && (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Eye, { className: "h-4 w-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "text-sm shrink-0 text-muted-foreground", children: "Add widget:" }), _jsx("div", { className: "flex flex-wrap gap-1", children: hiddenWidgetKeys.map((key) => {
-                                            const meta = widgetMeta?.[key];
-                                            const Icon = meta?.icon;
-                                            return (_jsxs("button", { type: "button", onClick: () => showLayer(key, meta?.defaultSize), className: cn('flex items-center gap-1 px-2 py-0.5 rounded text-xs font-medium border transition-colors', 'bg-muted text-muted-foreground border-border-interactive', 'hover:bg-muted/80 hover:text-foreground hover:border-primary/60', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(Plus, { className: "h-3 w-3" }), Icon && _jsx(Icon, { className: "h-3 w-3" }), layerNames[key] || meta?.label || key] }, key));
-                                        }) })] })), layerItems.length > 0 && (_jsxs("div", { className: "basis-full rounded-md border border-border bg-background/80 p-2", children: [_jsxs("div", { className: "mb-2 flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-muted-foreground", children: [_jsx(Layers, { className: "h-3.5 w-3.5" }), "Layers"] }), _jsx("div", { className: "flex flex-col gap-1", children: layerItems.map((layer) => (_jsxs("div", { className: "flex items-center gap-1 rounded border border-border bg-card px-2 py-1", children: [_jsx("input", { type: "text", value: layer.label, onChange: (event) => handleLayerRename(layer.id, event.target.value), className: "min-w-0 flex-1 bg-transparent text-xs text-foreground outline-none", "aria-label": `Rename ${layer.label}` }), _jsx("button", { type: "button", onClick: () => moveWidget(layer.id, 'up'), disabled: !layer.canMoveUp, "aria-label": `Move ${layer.label} up`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40", children: _jsx(ArrowUp, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => moveWidget(layer.id, 'down'), disabled: !layer.canMoveDown, "aria-label": `Move ${layer.label} down`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40", children: _jsx(ArrowDown, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => setWidgetLocked(layer.id, !layer.locked), "aria-label": `${layer.locked ? 'Unlock' : 'Lock'} ${layer.label}`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", children: layer.locked ? _jsx(Lock, { className: "h-3.5 w-3.5" }) : _jsx(Unlock, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => hideLayer(layer.id), "aria-label": `Hide ${layer.label}`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", children: _jsx(EyeOff, { className: "h-3.5 w-3.5" }) })] }, layer.id))) })] })), _jsxs("button", { type: "button", onClick: handleCompact, className: cn('ml-auto inline-flex items-center rounded-md border border-border-interactive px-2 py-1 text-sm transition-colors', 'text-muted-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(Layers, { className: "h-4 w-4 mr-1" }), "Compact Layout"] }), _jsxs("button", { type: "button", onClick: () => setResetConfirmOpen(true), className: cn('inline-flex items-center rounded-md border border-border-interactive px-2 py-1 text-sm transition-colors', 'text-muted-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(RotateCcw, { className: "h-4 w-4 mr-1" }), "Reset to Default"] })] })] })), resetConfirmOpen && (_jsx("div", { className: "fixed inset-0 z-50 flex items-center justify-center bg-overlay/50 p-4", role: "dialog", "aria-modal": "true", "aria-labelledby": "page-grid-reset-title", "aria-describedby": "page-grid-reset-description", children: _jsxs("div", { className: "max-w-md rounded-lg bg-card p-5 shadow-lg border border-border", children: [_jsx("h2", { id: "page-grid-reset-title", className: "text-lg font-semibold", children: "Reset page layout?" }), _jsx("p", { id: "page-grid-reset-description", className: "mt-2 text-sm text-muted-foreground", children: "This will discard your current layout and restore all widgets to their default positions." }), _jsxs("div", { className: "mt-4 flex justify-end gap-2", children: [_jsx("button", { type: "button", ref: resetCancelButtonRef, onClick: () => setResetConfirmOpen(false), className: cn('inline-flex items-center rounded-md border border-border-interactive px-3 py-2 text-sm transition-colors', 'bg-card text-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: "Cancel" }), _jsx("button", { type: "button", ref: resetConfirmButtonRef, onClick: () => {
+                'bg-card/95 supports-[backdrop-filter]:bg-card/80 backdrop-blur border-primary'), role: "region", "aria-label": "Canvas editor controls", "aria-busy": isSaving, children: [_jsxs("div", { className: "flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3", children: [_jsxs("div", { className: "flex items-center gap-3", children: [_jsx("div", { className: cn('rounded-full flex items-center justify-center bg-primary/10', controlsCollapsed ? 'h-8 w-8' : 'h-10 w-10 animate-pulse'), children: _jsx(Settings2, { className: cn('text-primary', controlsCollapsed ? 'h-4 w-4' : 'h-5 w-5') }) }), _jsxs("div", { children: [_jsx("h3", { className: cn('font-semibold text-foreground', controlsCollapsed ? 'text-sm' : 'text-lg'), children: "Canvas Editor Active" }), !controlsCollapsed && !editingPaused && (_jsx("span", { className: "text-sm text-muted-foreground", children: "Drag anywhere on a card to move it. Resize with the bottom-right handle." }))] })] }), _jsxs("div", { className: "flex items-center gap-2 shrink-0", children: [_jsxs("button", { type: "button", className: "inline-flex items-center gap-1 rounded-md border border-border-interactive px-2 py-2 text-sm text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", "aria-expanded": !controlsCollapsed, "aria-controls": "page-grid-editor-controls-body", "aria-label": controlsCollapsed ? 'Expand controls: columns, cards and layers' : 'Collapse controls', onClick: () => setControlsCollapsed((previous) => !previous), children: [controlsCollapsed ? _jsx(ChevronDown, { className: "h-4 w-4" }) : _jsx(ChevronUp, { className: "h-4 w-4" }), _jsx("span", { className: "sr-only sm:not-sr-only", children: controlsCollapsed ? 'Columns, cards & layers' : 'Collapse' })] }), _jsxs("button", { type: "button", className: "inline-flex items-center rounded-md px-3 py-2 text-sm font-medium bg-primary text-primary-foreground shadow transition-colors hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", disabled: isSaving, onClick: () => { void saveAndExit(); }, children: [editingPaused ? _jsx(X, { className: "h-4 w-4 mr-2" }) : _jsx(Save, { className: "h-4 w-4 mr-2" }), isSaving ? 'Saving…' : editingPaused ? 'Exit' : 'Save & Exit'] })] })] }), editingPaused && (_jsxs("div", { role: editingPreferencesStatus === 'failed' ? 'alert' : 'status', "data-page-grid-editing-paused": editingPreferencesStatus, className: cn('flex flex-wrap items-center gap-2 text-sm', editingPreferencesStatus === 'failed' ? 'text-destructive' : 'text-muted-foreground'), children: [_jsx("p", { children: editingPreferencesStatus === 'failed'
+                                    ? `Editing is paused: your saved settings for this page ${retriedAndStillFailed ? 'still couldn\'t' : 'couldn\'t'} be loaded. Nothing can be changed until they load, so nothing you saved is overwritten.${canRetryEditingPreferences ? '' : ' Reload the page to try again.'}`
+                                    : 'Loading your saved settings for this page… Editing starts as soon as they arrive.' }), editingPreferencesStatus === 'failed' && canRetryEditingPreferences && (_jsxs("button", { type: "button", onClick: retryEditingPreferences, className: "inline-flex items-center gap-1 rounded-md border border-border-interactive px-2 py-1 text-sm text-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", children: [_jsx(RefreshCw, { className: "h-3.5 w-3.5", "aria-hidden": "true" }), "Retry"] }))] })), saveFailed && (_jsx("p", { role: "alert", className: "mt-2 text-sm text-destructive", children: "Changes could not be saved. Your changes are still here. Try Save & Exit again." })), _jsx("div", { id: "page-grid-editor-controls-body", hidden: controlsCollapsed, 
+                        // Dimmed while paused so the disabled state reads at a glance; inline
+                        // rather than a utility so no consumer's CSS build can drop it.
+                        style: editingPaused ? { opacity: 0.6 } : undefined, className: "flex flex-wrap items-center gap-x-4 gap-y-2 pt-2 border-t border-border max-h-[60vh] overflow-y-auto", children: _jsxs("fieldset", { disabled: editingPaused, style: { display: 'contents' }, children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(LayoutGrid, { className: "h-4 w-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "text-sm shrink-0 text-muted-foreground", children: "Columns:" }), _jsx("input", { type: "range", min: 1, max: 24, value: layoutCols, onChange: (event) => handleColumnChange(Number(event.target.value)), className: "w-24 cursor-pointer accent-primary", "aria-label": "Column count" }), _jsx("span", { className: "text-sm font-mono w-5 text-center tabular-nums", children: layoutCols })] }), _jsx("div", { className: "flex items-center gap-1", role: "group", "aria-label": "Column presets", children: [1, 2, 3, 4, 6, 12].map((columnCount) => (_jsx("button", { type: "button", onClick: () => handleColumnChange(columnCount), "data-active": layoutCols === columnCount || undefined, "aria-pressed": layoutCols === columnCount, className: cn('px-2 py-0.5 rounded text-xs font-medium transition-colors border', 'bg-muted text-muted-foreground border-border-interactive', 'hover:bg-muted/80 hover:text-foreground', 'data-[active]:bg-primary data-[active]:text-primary-foreground data-[active]:border-primary', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: columnCount }, columnCount))) }), _jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-2 w-full pt-2 border-t border-border", role: "group", "aria-label": "Card appearance", children: [_jsx("span", { className: "text-sm shrink-0 font-medium text-foreground", children: "Card:" }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "text-sm text-muted-foreground", children: "Corners" }), _jsx("input", { type: "range", min: RADIUS_RANGE.min, max: RADIUS_RANGE.max, value: cardStyle.radius, onChange: (event) => updateCardStyle({ radius: Number(event.target.value) }), className: "w-20 cursor-pointer accent-primary", "aria-label": "Card corner radius in pixels" }), _jsx("span", { className: "text-sm font-mono w-8 text-right tabular-nums", children: cardStyle.radius })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "text-sm text-muted-foreground", children: "Border" }), _jsx("input", { type: "range", min: BORDER_WIDTH_RANGE.min, max: BORDER_WIDTH_RANGE.max, value: cardStyle.borderWidth, onChange: (event) => updateCardStyle({ borderWidth: Number(event.target.value) }), className: "w-16 cursor-pointer accent-primary", "aria-label": "Card border width in pixels" }), _jsx("span", { className: "text-sm font-mono w-6 text-right tabular-nums", children: cardStyle.borderWidth })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "sr-only", children: "Border colour" }), _jsx("select", { value: cardStyle.borderTone, onChange: (event) => updateCardStyle({ borderTone: event.target.value }), className: "rounded-md border border-border-interactive bg-background px-2 py-1 text-sm text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", "aria-label": "Card border colour", children: BORDER_TONES.map((tone) => (_jsx("option", { value: tone, children: tone === 'border' ? 'default colour' : tone }, tone))) })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "sr-only", children: "Border style" }), _jsx("select", { value: cardStyle.borderStyle, onChange: (event) => updateCardStyle({ borderStyle: event.target.value }), className: "rounded-md border border-border-interactive bg-background px-2 py-1 text-sm text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", "aria-label": "Card border style", children: BORDER_STYLES.map((style) => (_jsx("option", { value: style, children: style }, style))) })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "sr-only", children: "Card shadow" }), _jsxs("select", { value: cardStyle.elevation === null ? 'default' : String(cardStyle.elevation), onChange: (event) => updateCardStyle({
+                                                        elevation: event.target.value === 'default' ? null : Number(event.target.value),
+                                                    }), className: "rounded-md border border-border-interactive bg-background px-2 py-1 text-sm text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", "aria-label": "Card shadow depth", children: [_jsx("option", { value: "default", children: "default shadow" }), [0, 1, 2, 3, 4].map((level) => (_jsx("option", { value: level, children: level === 0 ? 'no shadow' : `shadow ${level}` }, level)))] })] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "text-sm text-muted-foreground", children: "Padding" }), _jsx("input", { type: "range", min: PADDING_RANGE.min, max: PADDING_RANGE.max, value: cardStyle.padding ?? 0, onChange: (event) => updateCardStyle({ padding: Number(event.target.value) }), className: "w-16 cursor-pointer accent-primary", "aria-label": "Card inner padding in pixels" }), _jsx("span", { className: "text-sm font-mono w-8 text-right tabular-nums", children: cardStyle.padding === null ? '\u2014' : cardStyle.padding })] }), _jsxs("button", { type: "button", onClick: resetCardStyle, disabled: isDefaultCardStyle(cardStyle), className: "inline-flex items-center gap-1 rounded-md border border-border-interactive px-2 py-1 text-sm text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-50 disabled:pointer-events-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", children: [_jsx(RotateCcw, { className: "h-3.5 w-3.5" }), "Reset cards"] }), _jsx("output", { className: "text-sm text-muted-foreground", "aria-live": "polite", children: describeCardStyle(cardStyle) })] }), hiddenWidgetKeys.length > 0 && (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Eye, { className: "h-4 w-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "text-sm shrink-0 text-muted-foreground", children: "Add widget:" }), _jsx("div", { className: "flex flex-wrap gap-1", children: hiddenWidgetKeys.map((key) => {
+                                                const meta = widgetMeta?.[key];
+                                                const Icon = meta?.icon;
+                                                return (_jsxs("button", { type: "button", onClick: () => showLayer(key, meta?.defaultSize), className: cn('flex items-center gap-1 px-2 py-0.5 rounded text-xs font-medium border transition-colors', 'bg-muted text-muted-foreground border-border-interactive', 'hover:bg-muted/80 hover:text-foreground hover:border-primary/60', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(Plus, { className: "h-3 w-3" }), Icon && _jsx(Icon, { className: "h-3 w-3" }), layerNames[key] || meta?.label || key] }, key));
+                                            }) })] })), layerItems.length > 0 && (_jsxs("div", { className: "basis-full rounded-md border border-border bg-background/80 p-2", children: [_jsxs("div", { className: "mb-2 flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-muted-foreground", children: [_jsx(Layers, { className: "h-3.5 w-3.5" }), "Layers"] }), _jsx("div", { className: "flex flex-col gap-1", children: layerItems.map((layer) => (_jsxs("div", { className: "flex items-center gap-1 rounded border border-border bg-card px-2 py-1", children: [_jsx("input", { type: "text", value: layer.label, onChange: (event) => handleLayerRename(layer.id, event.target.value), className: "min-w-0 flex-1 bg-transparent text-xs text-foreground outline-none", "aria-label": `Rename ${layer.label}` }), _jsx("button", { type: "button", onClick: () => moveWidget(layer.id, 'up'), disabled: !layer.canMoveUp, "aria-label": `Move ${layer.label} up`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40", children: _jsx(ArrowUp, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => moveWidget(layer.id, 'down'), disabled: !layer.canMoveDown, "aria-label": `Move ${layer.label} down`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40", children: _jsx(ArrowDown, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => setWidgetLocked(layer.id, !layer.locked), "aria-label": `${layer.locked ? 'Unlock' : 'Lock'} ${layer.label}`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", children: layer.locked ? _jsx(Lock, { className: "h-3.5 w-3.5" }) : _jsx(Unlock, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => hideLayer(layer.id), "aria-label": `Hide ${layer.label}`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", children: _jsx(EyeOff, { className: "h-3.5 w-3.5" }) })] }, layer.id))) })] })), _jsxs("button", { type: "button", onClick: handleCompact, className: cn('ml-auto inline-flex items-center rounded-md border border-border-interactive px-2 py-1 text-sm transition-colors', 'text-muted-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(Layers, { className: "h-4 w-4 mr-1" }), "Compact Layout"] }), _jsxs("button", { type: "button", onClick: () => setResetConfirmOpen(true), className: cn('inline-flex items-center rounded-md border border-border-interactive px-2 py-1 text-sm transition-colors', 'text-muted-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(RotateCcw, { className: "h-4 w-4 mr-1" }), "Reset to Default"] })] }) })] })), resetConfirmOpen && (_jsx("div", { className: "fixed inset-0 z-50 flex items-center justify-center bg-overlay/50 p-4", role: "dialog", "aria-modal": "true", "aria-labelledby": "page-grid-reset-title", "aria-describedby": "page-grid-reset-description", children: _jsxs("div", { className: "max-w-md rounded-lg bg-card p-5 shadow-lg border border-border", children: [_jsx("h2", { id: "page-grid-reset-title", className: "text-lg font-semibold", children: "Reset page layout?" }), _jsx("p", { id: "page-grid-reset-description", className: "mt-2 text-sm text-muted-foreground", children: "This will discard your current layout and restore all widgets to their default positions." }), _jsxs("div", { className: "mt-4 flex justify-end gap-2", children: [_jsx("button", { type: "button", ref: resetCancelButtonRef, onClick: () => setResetConfirmOpen(false), className: cn('inline-flex items-center rounded-md border border-border-interactive px-3 py-2 text-sm transition-colors', 'bg-card text-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: "Cancel" }), _jsx("button", { type: "button", ref: resetConfirmButtonRef, onClick: () => {
                                         handleReset();
                                         setResetConfirmOpen(false);
                                     }, className: cn('inline-flex items-center rounded-md px-3 py-2 text-sm font-medium transition-colors', 'bg-destructive text-destructive-foreground shadow hover:bg-destructive/90', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-destructive/40 focus-visible:ring-offset-1'), children: "Reset to Default" })] })] }) })), _jsx("div", { ref: containerRef, className: cn('relative z-0 overflow-visible', isEditing && 'min-h-[200px] bg-muted/30'), "data-page-grid-editing": isEditing || undefined, children: _jsx("div", { className: "relative z-0", style: { opacity: containerWidth > 0 ? 1 : 0 }, "aria-busy": containerWidth <= 0, children: _jsx(Responsive, { width: Math.max(containerWidth, 1), className: "layout page-grid-canvas", layouts: activeLayouts, breakpoints: { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }, rowHeight: DEFAULT_ROW_HEIGHT, onLayoutChange: (layout, layouts) => {
@@ -896,7 +1008,7 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
                         // is folded back onto `lg` instead of into a derived breakpoint
                         // that is regenerated (and therefore discarded) on the next render.
                         onBreakpointChange: handleBreakpointChange, dragConfig: {
-                            enabled: isEditing,
+                            enabled: isEditing && !editingPaused,
                             handle: '.drag-handle',
                             bounded: false,
                             cancel: '.react-resizable-handle, button, input, textarea, select, [contenteditable="true"], [data-no-drag], a[href], [role="button"], [role="combobox"], [role="menuitem"], [role="tab"], [role="checkbox"], [role="switch"], [role="slider"], [role="textbox"]',
@@ -914,6 +1026,6 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
                             const content = allWidgets[layoutItem.i];
                             if (content === undefined || content === null)
                                 return null;
-                            return (_jsx(GridItem, { id: layoutItem.i, content: content, isEditing: isEditing, label: layerNames[layoutItem.i] || widgetMeta?.[layoutItem.i]?.label || layoutItem.i, pageKey: pageKey, onHide: hideLayer, autoHeight: layoutItem.autoHeight, onAutoHeightChange: handleAutoHeightChange, chrome: layoutItem.chrome ?? itemChrome, cardStyleVars: cardStyleVars }, layoutItem.i));
+                            return (_jsx(GridItem, { id: layoutItem.i, content: content, isEditing: isEditing, label: layerNames[layoutItem.i] || widgetMeta?.[layoutItem.i]?.label || layoutItem.i, pageKey: pageKey, onHide: hideLayer, editingPaused: editingPaused, autoHeight: layoutItem.autoHeight, onAutoHeightChange: handleAutoHeightChange, chrome: layoutItem.chrome ?? itemChrome, cardStyleVars: cardStyleVars }, layoutItem.i));
                         }) }) }) })] }));
 }

package/dist/cardPadding.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+/**
+ * A grid offers its inset to the first app Card. That Card places a boundary
+ * around its children so inner panels keep their own spacing. A nested grid
+ * supplies a new value, including undefined when its inset is not overridden.
+ * No DOM wrapper or browser-specific CSS scoping is needed.
+ */
+export declare function CardPaddingBoundary({ padding, children }: {
+    padding?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useCardPadding(): string | undefined;
+//# sourceMappingURL=cardPadding.d.ts.map

package/dist/cardPadding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardPadding.d.ts","sourceRoot":"","sources":["../src/cardPadding.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAEnG;AAED,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD"}

package/dist/cardPadding.js

@@ -0,0 +1,16 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+const CardPaddingContext = createContext(undefined);
+/**
+ * A grid offers its inset to the first app Card. That Card places a boundary
+ * around its children so inner panels keep their own spacing. A nested grid
+ * supplies a new value, including undefined when its inset is not overridden.
+ * No DOM wrapper or browser-specific CSS scoping is needed.
+ */
+export function CardPaddingBoundary({ padding, children }) {
+    return _jsx(CardPaddingContext.Provider, { value: padding, children: children });
+}
+export function useCardPadding() {
+    return useContext(CardPaddingContext);
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { PageGridLayout, PAGE_GRID_SAVE_EVENT } from './PageGridLayout.js';
+export { CardPaddingBoundary, useCardPadding } from './cardPadding.js';
 export type { PageGridSaveEventDetail } from './PageGridLayout.js';
 export { PageEditorLauncher } from './PageEditorLauncher.js';
 export { CanvasCard } from './CanvasCard.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,YAAY,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAwB7C,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACrF,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC1B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,gCAAgC,EAChC,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,IAAI,kBAAkB,EAC/B,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQpF,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,eAAe,EACf,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export { PageGridLayout, PAGE_GRID_SAVE_EVENT } from './PageGridLayout.js';
+export { CardPaddingBoundary, useCardPadding } from './cardPadding.js';
 export { PageEditorLauncher } from './PageEditorLauncher.js';
 export { CanvasCard } from './CanvasCard.js';
 export { DraggableCardPage } from './DraggableCardPage.js';

package/dist/types.d.ts

@@ -64,10 +64,52 @@ export interface GridLayouts {
  * reference widgets that no longer exist.
  */
 export type LayoutMigration = (saved: GridLayouts, defaults: GridLayouts) => GridLayouts;
+/**
+ * Where the READ of one preference key stands (bsuite#3277).
+ *
+ * - `'loading'` — the stored value has not arrived yet. `value` is a local
+ *   mirror or the fallback.
+ * - `'loaded'`  — `value` is what is stored for this key, or nothing is stored
+ *   and `value` is the fallback. Only this state authorises a write.
+ * - `'failed'`  — the read errored. `value` is a local mirror or the fallback
+ *   and says NOTHING about what is stored.
+ *
+ * A failed read is not an empty read. On a device with no local copy, crm7 and
+ * business-suite-unified reported a failed `_grid_version` read as "loaded,
+ * version 0"; the version gate then took its discard branch and wrote the
+ * defaults over the user's saved layout — 200 of 200 pages in the measurement.
+ */
+export type PageGridPreferenceStatus = 'loading' | 'loaded' | 'failed';
 export interface PageGridPreferenceAdapter<T> {
     value: T;
     setValue: (value: T | ((previous: T) => T)) => void;
+    /**
+     * The two-state read signal every adapter has always reported. An adapter
+     * that implements `status` must keep this equal to `status === 'loaded'` —
+     * never true after a failed read.
+     *
+     * An adapter that does NOT implement `status` keeps exactly the meaning this
+     * had before: `true` is `'loaded'`, `false` is `'loading'`.
+     */
     loaded: boolean;
+    /**
+     * The three-state read signal. When present it is AUTHORITATIVE over
+     * `loaded`: `usePageGridLayout` treats a key as readable only when `status`
+     * is `'loaded'` AND `loaded` is true, so an adapter that adds `status` beside
+     * an older "the read settled" `loaded` still cannot authorise a write after a
+     * failure.
+     *
+     * Once a key has loaded, a later background re-read that fails must NOT move
+     * it back to `'failed'` — the value it holds is still the stored one.
+     */
+    status?: PageGridPreferenceStatus;
+    /**
+     * Re-read THIS key after a failed read, in place: no remount, no reset of any
+     * other key, and no write. The adapter moves the key to `'loading'` and then
+     * to `'loaded'` or back to `'failed'`. Omit it only if the adapter genuinely
+     * cannot read again without a reload.
+     */
+    retry?: () => void;
     /** Wait for pending writes and reject if the latest change was not saved.
      * A subsequent explicit call may retry a failed write without losing the draft.
      * Synchronous adapters may omit this; remote adapters should implement it. */
@@ -258,6 +300,22 @@ export interface UsePageGridLayoutResult {
     isEditing: boolean;
     setIsEditing: React.Dispatch<React.SetStateAction<boolean>>;
     flushPreferences: () => Promise<void>;
+    /**
+     * The read state of every preference key this hook reads OR writes
+     * (`_grid_version`, `_grid_layouts`, `_grid_cols`, `_grid_base_cols`),
+     * combined: `'failed'` if any failed, else `'loading'` if any is still
+     * loading, else `'loaded'`. Until it is `'loaded'` the hook runs no version
+     * gate, no migration, no discard and no write of any kind (bsuite#3277).
+     */
+    preferencesStatus: PageGridPreferenceStatus;
+    /** True when at least one failed key's adapter offers `retry`. */
+    canRetryPreferences: boolean;
+    /**
+     * Re-read ONLY the keys whose read failed, via each adapter's own `retry`.
+     * Nothing remounts: editing state, the draft and every loaded key are kept,
+     * and the gate simply runs once every key has loaded.
+     */
+    retryPreferences: () => void;
     activeCols: Record<string, number>;
     activeCompactor: Compactor;
     onLayoutChange: (_layout: unknown, layouts: unknown, wasGesture?: boolean) => void;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/usePageGridLayout.d.ts

@@ -1,4 +1,23 @@
-import type { GridLayouts, LayoutMigration, UsePageGridLayoutOptions, UsePageGridLayoutResult } from './types.js';
+import type { GridLayouts, LayoutMigration, PageGridPreferenceAdapter, PageGridPreferenceStatus, UsePageGridLayoutOptions, UsePageGridLayoutResult } from './types.js';
+/**
+ * One key's read state, resolved from what its adapter reports (bsuite#3277).
+ *
+ * `status` is authoritative when present, and a key counts as readable only if
+ * `status` is `'loaded'` AND `loaded` is true. The conjunction is the point: the
+ * first adapter a consumer ships will add `status` beside its old "the read
+ * settled" `loaded`, and that `loaded` is true after an error. Anything that is
+ * not positively loaded — including a `status` value this version does not know —
+ * resolves to not-loaded, so an unrecognised state fails closed.
+ *
+ * An adapter without `status` keeps the meaning `loaded` always had.
+ */
+export declare function preferenceStatusOf(adapter: Pick<PageGridPreferenceAdapter<unknown>, 'loaded' | 'status'>): PageGridPreferenceStatus;
+/**
+ * Several keys' read states as one: a failure outranks a key still loading,
+ * because the failure is what the user can act on (Retry) and a still-loading
+ * key must not hide it.
+ */
+export declare function combinePreferenceStatuses(statuses: readonly PageGridPreferenceStatus[]): PageGridPreferenceStatus;
 export declare const DEFAULT_EDITOR_EVENT_NAMES: readonly ["bsuite-open-page-editor", "bsu-open-page-editor", "crm7-open-page-editor", "conduit-open-page-editor", "r80-open-page-editor"];
 /**
  * Broadcast after a PageGridLayout commits an editing-state change. Header

package/dist/usePageGridLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePageGridLayout.d.ts","sourceRoot":"","sources":["../src/usePageGridLayout.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAEV,WAAW,EACX,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,0BAA0B,2IAM7B,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAiBzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,EAAE,EACF,UAAU,GACX,EAAE;IACD,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/B,QAAQ,EAAE,WAAW,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,IAAI,CAAC;CACzD,GAAG,WAAW,GAAG,IAAI,CA+BrB;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,cAAc,EACd,WAAgB,EAChB,aAAiB,EACjB,WAAkB,EAClB,gBAA6C,EAC7C,iBAA4C,EAC5C,iBAAiB,EACjB,gBAAgB,GACjB,EAAE,wBAAwB,GAAG,uBAAuB,CA4yBpD"}
+{"version":3,"file":"usePageGridLayout.d.ts","sourceRoot":"","sources":["../src/usePageGridLayout.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAEV,WAAW,EACX,eAAe,EACf,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC,GACrE,wBAAwB,CAI1B;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,GAC5C,wBAAwB,CAI1B;AAED,eAAO,MAAM,0BAA0B,2IAM7B,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAiBzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,EAAE,EACF,UAAU,GACX,EAAE;IACD,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/B,QAAQ,EAAE,WAAW,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,IAAI,CAAC;CACzD,GAAG,WAAW,GAAG,IAAI,CA+BrB;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,cAAc,EACd,WAAgB,EAChB,aAAiB,EACjB,WAAkB,EAClB,gBAA6C,EAC7C,iBAA4C,EAC5C,iBAAiB,EACjB,gBAAgB,GACjB,EAAE,wBAAwB,GAAG,uBAAuB,CAg3BpD"}

package/dist/usePageGridLayout.js

@@ -3,6 +3,37 @@ import { verticalCompactor } from 'react-grid-layout';
 import { buildResponsiveLayouts, isCanonicalisableBreakpoint, isDerivedBreakpoint, } from './buildResponsiveLayouts.js';
 import { defaultPreferenceAdapter } from './preferences.js';
 import { rescaleLayout } from './rescaleLayout.js';
+/**
+ * One key's read state, resolved from what its adapter reports (bsuite#3277).
+ *
+ * `status` is authoritative when present, and a key counts as readable only if
+ * `status` is `'loaded'` AND `loaded` is true. The conjunction is the point: the
+ * first adapter a consumer ships will add `status` beside its old "the read
+ * settled" `loaded`, and that `loaded` is true after an error. Anything that is
+ * not positively loaded — including a `status` value this version does not know —
+ * resolves to not-loaded, so an unrecognised state fails closed.
+ *
+ * An adapter without `status` keeps the meaning `loaded` always had.
+ */
+export function preferenceStatusOf(adapter) {
+    if (adapter.status === 'failed')
+        return 'failed';
+    if (adapter.status === undefined)
+        return adapter.loaded ? 'loaded' : 'loading';
+    return adapter.status === 'loaded' && adapter.loaded ? 'loaded' : 'loading';
+}
+/**
+ * Several keys' read states as one: a failure outranks a key still loading,
+ * because the failure is what the user can act on (Retry) and a still-loading
+ * key must not hide it.
+ */
+export function combinePreferenceStatuses(statuses) {
+    if (statuses.includes('failed'))
+        return 'failed';
+    if (statuses.includes('loading'))
+        return 'loading';
+    return 'loaded';
+}
 export const DEFAULT_EDITOR_EVENT_NAMES = [
     'bsuite-open-page-editor',
     'bsu-open-page-editor',
@@ -152,14 +183,70 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         window.addEventListener('resize', onResize);
         return () => window.removeEventListener('resize', onResize);
     }, []);
-    const { value: savedLayoutVersion, setValue: setSavedLayoutVersion, loaded: versionLoaded, flush: flushVersion } = preferenceAdapter(`page:${pageKey}_grid_version`, 0);
-    const { value: savedLayout, setValue: setSavedLayout, loaded: layoutLoaded, flush: flushLayout } = preferenceAdapter(`page:${pageKey}_grid_layouts`, defaultLayouts);
-    const { value: savedLayoutCols, setValue: setLayoutCols, flush: flushCols } = preferenceAdapter(`page:${pageKey}_grid_cols`, defaultCols);
-    const { value: savedBaseCols, setValue: setBaseCols, flush: flushBaseCols } = preferenceAdapter(`page:${pageKey}_grid_base_cols`, defaultCols);
+    const versionPreference = preferenceAdapter(`page:${pageKey}_grid_version`, 0);
+    const layoutPreference = preferenceAdapter(`page:${pageKey}_grid_layouts`, defaultLayouts);
+    const colsPreference = preferenceAdapter(`page:${pageKey}_grid_cols`, defaultCols);
+    const baseColsPreference = preferenceAdapter(`page:${pageKey}_grid_base_cols`, defaultCols);
+    const { value: savedLayoutVersion, setValue: setSavedLayoutVersion, flush: flushVersion, retry: retryVersion } = versionPreference;
+    const { value: savedLayout, setValue: setSavedLayout, flush: flushLayout, retry: retryLayout } = layoutPreference;
+    const { value: savedLayoutCols, setValue: setLayoutCols, flush: flushCols, retry: retryCols } = colsPreference;
+    const { value: savedBaseCols, setValue: setBaseCols, flush: flushBaseCols, retry: retryBaseCols } = baseColsPreference;
     const flushPreferences = useCallback(async () => {
         await Promise.all([flushVersion?.(), flushLayout?.(), flushCols?.(), flushBaseCols?.()]);
     }, [flushVersion, flushLayout, flushCols, flushBaseCols]);
-    const prefsLoaded = layoutLoaded && versionLoaded;
+    /*
+     * NOTHING IS WRITTEN UNTIL EVERY KEY THIS HOOK TOUCHES HAS BEEN READ (bsuite#3277).
+     *
+     * The gate below used to wait for `_grid_layouts` and `_grid_version` only, and
+     * trusted `loaded` to mean "the stored value is here". crm7 and
+     * business-suite-unified set `loaded` on a read ERROR too, so on a device with
+     * no local copy a failed `_grid_version` read looked like "loaded, version 0" —
+     * the gate took its discard branch and wrote the page defaults over the user's
+     * saved layout. Measured with the real 2.7.0 hook: 200 of 200 pages.
+     *
+     * The rule now covers every key the hook READS or WRITES — `_grid_cols` and
+     * `_grid_base_cols` included, because a discard writes them — and every write
+     * the hook can make, not only the gate's: a gesture, compact, reset, add, move,
+     * lock, remove and a column change are all refused while any key is loading or
+     * failed. `PageGridLayout` shows the reason and a Retry while that holds.
+     */
+    const versionStatus = preferenceStatusOf(versionPreference);
+    const layoutStatus = preferenceStatusOf(layoutPreference);
+    const colsStatus = preferenceStatusOf(colsPreference);
+    const baseColsStatus = preferenceStatusOf(baseColsPreference);
+    const preferencesStatus = combinePreferenceStatuses([versionStatus, layoutStatus, colsStatus, baseColsStatus]);
+    const preferencesWritable = preferencesStatus === 'loaded';
+    /*
+     * Retry is PER KEY and IN PLACE. Each adapter's own `retry` re-runs that one
+     * key's read — crm7 re-runs its fetch effect, business-suite-unified refetches
+     * that key's query, conduit re-reads that key's local copy. This hook, its
+     * editing state and every key that already loaded stay mounted; the gate above
+     * simply runs once the last failed key lands. A key that loaded is never
+     * re-read, so a retry cannot disturb a value that is already right.
+     */
+    const canRetryPreferences = (versionStatus === 'failed' && typeof retryVersion === 'function') ||
+        (layoutStatus === 'failed' && typeof retryLayout === 'function') ||
+        (colsStatus === 'failed' && typeof retryCols === 'function') ||
+        (baseColsStatus === 'failed' && typeof retryBaseCols === 'function');
+    const retryPreferences = useCallback(() => {
+        if (versionStatus === 'failed')
+            retryVersion?.();
+        if (layoutStatus === 'failed')
+            retryLayout?.();
+        if (colsStatus === 'failed')
+            retryCols?.();
+        if (baseColsStatus === 'failed')
+            retryBaseCols?.();
+    }, [
+        baseColsStatus,
+        colsStatus,
+        layoutStatus,
+        retryBaseCols,
+        retryCols,
+        retryLayout,
+        retryVersion,
+        versionStatus,
+    ]);
     /*
      * Migration keys arrive in the CONSUMER's version space — `layoutVersion={2}`
      * pairs with `{ 2: … }` — and are shifted onto the stored (effective) space
@@ -199,7 +286,8 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         savedLayoutForVersionGateRef.current = savedLayout;
     }, [savedLayout]);
     useEffect(() => {
-        if (!prefsLoaded)
+        // Every key read AND written must be loaded without failure — see above.
+        if (!preferencesWritable)
             return;
         const storedVersion = savedLayoutVersion ?? 0;
         if (storedVersion >= effectiveLayoutVersion)
@@ -245,7 +333,7 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         defaultLayouts,
         effectiveLayoutVersion,
         effectiveMigrations,
-        prefsLoaded,
+        preferencesWritable,
         savedLayoutVersion,
         setBaseCols,
         setLayoutCols,
@@ -590,12 +678,15 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
      * to agree, so it is the one moment `baseCols` may move.
      */
     const commitLayout = useCallback((layouts) => {
+        // bsuite#3277: no write while any key is loading or failed.
+        if (!preferencesWritable)
+            return;
         const canonical = canonicaliseLayoutForPersist(layouts);
         if (!canonical)
             return;
         setSavedLayout(stripAutoHeightRows(canonical));
         setBaseCols(layoutCols);
-    }, [canonicaliseLayoutForPersist, layoutCols, setBaseCols, setSavedLayout, stripAutoHeightRows]);
+    }, [canonicaliseLayoutForPersist, layoutCols, preferencesWritable, setBaseCols, setSavedLayout, stripAutoHeightRows]);
     const onLayoutChange = useCallback((_layout, layouts, wasGesture = true) => {
         if (!isEditing)
             return;
@@ -681,8 +772,11 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
      * undo. Storage moves only when the user actually edits — see `commitLayout`.
      */
     const handleColumnChange = useCallback((newCols) => {
+        // bsuite#3277: no write while any key is loading or failed.
+        if (!preferencesWritable)
+            return;
         setLayoutCols(newCols);
-    }, [setLayoutCols]);
+    }, [preferencesWritable, setLayoutCols]);
     /**
      * Build the object handed to the preference adapter from a new `lg` array.
      *
@@ -702,9 +796,12 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
     }, [currentLayouts]);
     /** Persist a bare `lg` item list from a mutator, re-basing the same way. */
     const commitItems = useCallback((items) => {
+        // bsuite#3277: no write while any key is loading or failed.
+        if (!preferencesWritable)
+            return;
         setSavedLayout(layoutsWithLg(items));
         setBaseCols(layoutCols);
-    }, [layoutCols, layoutsWithLg, setBaseCols, setSavedLayout]);
+    }, [layoutCols, layoutsWithLg, preferencesWritable, setBaseCols, setSavedLayout]);
     const handleCompact = useCallback(() => {
         if (!currentLayouts.lg)
             return;
@@ -724,12 +821,15 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         startTransition(() => commitItems(result));
     }, [currentLayouts, commitItems]);
     const handleReset = useCallback(() => {
+        // bsuite#3277: no write while any key is loading or failed.
+        if (!preferencesWritable)
+            return;
         startTransition(() => {
             setSavedLayout(defaultLayouts);
             setLayoutCols(defaultCols);
             setBaseCols(defaultCols);
         });
-    }, [defaultCols, defaultLayouts, setBaseCols, setLayoutCols, setSavedLayout]);
+    }, [defaultCols, defaultLayouts, preferencesWritable, setBaseCols, setLayoutCols, setSavedLayout]);
     const addWidget = useCallback((widgetKey, initialSize) => {
         const maxY = (currentLayouts.lg ?? []).reduce((max, item) => Math.max(max, item.y + item.h), 0);
         const newItem = {
@@ -742,7 +842,12 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             minH: initialSize?.minH,
         };
         startTransition(() => commitItems([...(currentLayouts.lg ?? []), newItem]));
-    }, [currentLayouts, layoutCols, layoutsWithLg, setSavedLayout]);
+    }, 
+    // `commitItems` is the write funnel and carries the read-state refusal
+    // (bsuite#3277). Omit it and the mutator keeps the funnel from the render it
+    // was created in: paused editing never un-pauses for this control after a
+    // Retry, because retrying a key that changes no layout re-creates nothing.
+    [commitItems, currentLayouts, layoutCols]);
     const moveWidget = useCallback((widgetKey, direction) => {
         const items = [...(currentLayouts.lg ?? [])];
         const index = items.findIndex((item) => item.i === widgetKey);
@@ -759,7 +864,7 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             ...withoutMoved.slice(targetIndex),
         ];
         startTransition(() => commitItems(nextItems));
-    }, [currentLayouts, layoutsWithLg, setSavedLayout]);
+    }, [commitItems, currentLayouts]);
     const setWidgetLocked = useCallback((widgetKey, locked) => {
         const nextItems = (currentLayouts.lg ?? []).map((item) => {
             if (item.i !== widgetKey)
@@ -772,11 +877,11 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             };
         });
         startTransition(() => commitItems(nextItems));
-    }, [currentLayouts, layoutsWithLg, setSavedLayout]);
+    }, [commitItems, currentLayouts]);
     const removeWidget = useCallback((widgetKey) => {
         const nextItems = (currentLayouts.lg ?? []).filter((item) => item.i !== widgetKey);
         startTransition(() => commitItems(nextItems));
-    }, [currentLayouts, layoutsWithLg, setSavedLayout]);
+    }, [commitItems, currentLayouts]);
     /**
      * Measured auto-height overrides (widgetKey -> rows). DERIVED, in-memory-
      * only state (quality-review design ruling, 2026-07-14):
@@ -850,6 +955,9 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         isEditing,
         setIsEditing,
         flushPreferences,
+        preferencesStatus,
+        canRetryPreferences,
+        retryPreferences,
         activeCols,
         activeCompactor,
         onLayoutChange,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/page-builder",
-  "version": "2.7.1-next.5",
+  "version": "2.7.1-next.7",
   "description": "Shared BSuite responsive page-builder grid and layout persistence primitives",
   "type": "module",
   "license": "UNLICENSED",
@@ -24,6 +24,10 @@
       "types": "./dist/index.d.ts"
     },
     "./styles.css": "./src/styles/react-grid-layout-overrides.css",
+    "./card-padding": {
+      "import": "./dist/cardPadding.js",
+      "types": "./dist/cardPadding.d.ts"
+    },
     "./scanner": {
       "import": "./dist/scanner/index.js",
       "types": "./dist/scanner/index.d.ts"