@bsuite/page-builder 2.6.1 → 2.7.1-next.0

package/README.md

@@ -48,3 +48,19 @@ Behaviour and guarantees:
 
 When adding `autoHeight` to an existing page's layout, bump that page's
 `layoutVersion` so stale persisted layouts (without the flag) are reset.
+
+## Edit-mode chrome (2.7.1-next.0+)
+
+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
+card heading. AutoHeight measures it with the content so the grid grows;
+leaving edit mode removes it and restores the content-only measurement.
+Do not restyle this in a consumer — it is the shared contract.
+
+The label carries `min-w-0 truncate` and a `title` with the full name. That is
+load-bearing on a narrow card, not decoration: without it the label's automatic
+minimum size is its min-content, and a long unbroken widget name pushes the
+`ml-auto` hide button outside the card box. Measured both ways in
+`scripts/editor-chrome-geometry.mjs`, which reproduces the defect with the two
+classes removed at run time.

package/dist/DraggableCardPage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DraggableCardPage.d.ts","sourceRoot":"","sources":["../src/DraggableCardPage.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGpE,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAItD,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,mBAAmB,EACnB,SAAS,GAAG,gBAAgB,CAC7B,GAAG;IACF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACnD;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAgCF,wBAAgB,iBAAiB,CAAC,EAChC,WAAe,EACf,aAAa,EACb,iBAAiB,EACjB,QAAQ,EACR,GAAG,SAAS,EACb,EAAE,sBAAsB,+BA2BxB;yBAjCe,iBAAiB"}
+{"version":3,"file":"DraggableCardPage.d.ts","sourceRoot":"","sources":["../src/DraggableCardPage.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGpE,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAmB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAIvE,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,mBAAmB,EACnB,SAAS,GAAG,gBAAgB,CAC7B,GAAG;IACF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACnD;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAgCF,wBAAgB,iBAAiB,CAAC,EAChC,WAAe,EACf,aAAa,EACb,iBAAiB,EACjB,QAAQ,EACR,GAAG,SAAS,EACb,EAAE,sBAAsB,+BAyDxB;yBA/De,iBAAiB"}

package/dist/DraggableCardPage.js

@@ -105,6 +105,36 @@ export function DraggableCardPage({ layoutEpoch = 0, gridComponent, onDroppedChi
     // spaces" surface had no white spaces because the grid was 1 column wide.
     const defaultCols = pageProps.defaultCols ?? 12;
     const Grid = gridComponent ?? DefaultPageGridLayout;
-    return (_jsx(Grid, { ...pageProps, layoutVersion: (pageProps.layoutVersion ?? 1) + layoutEpoch, defaultCols: defaultCols, widgets: widgets, defaultLayouts: layouts }));
+    /*
+     * `layoutMigrations` keys live in the same version space as `layoutVersion`,
+     * so they cross the epoch boundary with it. A page writes the number it
+     * bumped — `layoutVersion={2}` with `{ 2: … }` — and never has to know this
+     * app's epoch, or the package's.
+     *
+     * Getting this wrong fails SILENTLY and in the worst direction: an unshifted
+     * key simply never matches the step being migrated, the version gate finds
+     * nothing registered, and it falls back to the wholesale discard the
+     * migration existed to prevent. Pinned by
+     * `DraggableCardPage.layoutMigrations.test.tsx`.
+     *
+     * Memoised because the shifted map is an effect dependency inside
+     * `usePageGridLayout`; a fresh object per render would re-run an effect that
+     * writes state.
+     */
+    const layoutMigrations = useMemo(() => {
+        const declared = pageProps.layoutMigrations;
+        if (!declared || layoutEpoch === 0)
+            return declared;
+        const shifted = {};
+        for (const [version, migration] of Object.entries(declared)) {
+            shifted[Number(version) + layoutEpoch] = migration;
+        }
+        return shifted;
+    }, [pageProps.layoutMigrations, layoutEpoch]);
+    return (_jsx(Grid, { ...pageProps, layoutVersion: (pageProps.layoutVersion ?? 1) + layoutEpoch, 
+        // AFTER the spread, deliberately — `pageProps` still carries the
+        // consumer's unshifted map, and letting the spread lay it back over this
+        // would look wired and silently discard instead of migrate.
+        layoutMigrations: layoutMigrations, defaultCols: defaultCols, widgets: widgets, defaultLayouts: layouts }));
 }
 DraggableCardPage.displayName = 'DraggableCardPage';

package/dist/PageGridLayout.d.ts

@@ -2,5 +2,5 @@ import React from 'react';
 import 'react-grid-layout/css/styles.css';
 import 'react-resizable/css/styles.css';
 import type { PageGridLayoutProps } from './types.js';
-export declare function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVersion, canEditPage, editorEventNames, preferenceAdapter, widgets, widgetMeta, className, isResizable, resizeHandles, tenantId, defaultAutoHeight, itemChrome, addEntityWidgetEventNames, createEntityWidget, onRegisterEntityWidget, relationshipCatalog, addRelationshipWidgetEventNames, createRelationshipWidget, onRegisterRelationshipWidget, onRelationshipWidgetRejected, }: PageGridLayoutProps): React.JSX.Element;
+export declare function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVersion, canEditPage, editorEventNames, preferenceAdapter, widgets, widgetMeta, className, isResizable, resizeHandles, tenantId, defaultAutoHeight, layoutMigrations, itemChrome, addEntityWidgetEventNames, createEntityWidget, onRegisterEntityWidget, relationshipCatalog, addRelationshipWidgetEventNames, createRelationshipWidget, onRegisterRelationshipWidget, onRelationshipWidgetRejected, }: PageGridLayoutProps): React.JSX.Element;
 //# sourceMappingURL=PageGridLayout.d.ts.map

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;AAmmB7F,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,EAKjB,UAAkB,EAClB,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,+BAA6E,EAC7E,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,EAAE,mBAAmB,qBAs+BrB"}
+{"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;AA2pB7F,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,qBAu+BrB"}

package/dist/PageGridLayout.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 React, { startTransition, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
@@ -109,6 +109,31 @@ const RGLResizeHandle = React.forwardRef(function RGLResizeHandle({ axis = 'se',
  * the silent case audible in development and leaves production untouched, which
  * is the same trade @bsuite/theme 1.3.0 made for its missing-provider warning.
  */
+/**
+ * Edit-mode label + hide. These used to be `absolute top-2 left-2` /
+ * `top-2 right-2` overlays on the card (PageGridLayout GridItem, historically
+ * around the 407/415 marks). That painted the widget name and the hide control
+ * on top of the card heading — measured on the Candidates card at 1440.
+ *
+ * An earlier draft of this comment also claimed 390. Withdrawn: the instrument
+ * that produced that number never asserted its own `innerWidth`, and the cell
+ * labelled "390" reported 1560. What 390 actually looks like is now measured
+ * and recorded in `editor-chrome-geometry-390.json` — and it is a different
+ * fact: below a 480px container `buildResponsiveLayouts` stacks every card to
+ * full width, so 390 has no narrow card at all.
+ *
+ * In-flow, measured: the strip is a flex-none row. AutoHeight includes it in
+ * the unconstrained measure wrapper so the grid grows rather than overlapping.
+ * Fixed-height cards keep it *above* the overflow-auto body so hide cannot
+ * 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) => {
+                    event.stopPropagation();
+                    onHide(id);
+                }, title: `Hide ${label}`, "aria-label": `Hide ${label}`, children: _jsx(EyeOff, { className: "h-3 w-3", "aria-hidden": "true" }) })] }));
+}
 let warnedAboutCollapsedContent = false;
 function warnOnceAboutCollapsedContent(el) {
     if (warnedAboutCollapsedContent)
@@ -230,7 +255,9 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
             reportRows(contentPx);
         else
             warnOnceAboutCollapsedContent(el);
-    }, [autoHeight, onAutoHeightChange, reportRows]);
+        // Re-measure when edit chrome mounts/unmounts so the strip is in the
+        // row count in edit mode and gone again on lossless return.
+    }, [autoHeight, onAutoHeightChange, reportRows, isEditing]);
     useEffect(() => {
         if (!autoHeight || !onAutoHeightChange)
             return;
@@ -280,10 +307,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
     // (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);
-    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" })), isEditing && (_jsx("div", { className: "absolute top-2 left-2 z-30 flex items-center gap-1 pointer-events-none", children: _jsx("span", { className: "text-[10px] px-1.5 py-0.5 rounded-md opacity-80 font-medium bg-muted text-muted-foreground", children: label }) })), isEditing && (_jsx("button", { className: "absolute top-2 right-2 z-30 h-6 w-6 rounded-full flex items-center justify-center bg-destructive/80 hover:bg-destructive text-destructive-foreground shadow transition-colors", "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" }) })), _jsx("div", { "data-slot": "grid-item-surface", "data-chrome": chrome ? 'on' : 'off', "data-grid-slot-key": id, className: chrome
+    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, className: chrome
                             ? // ONE radius token, read by the grid item AND available to any
                                 // app card that opts into the same surface. Two surfaces
                                 // reading the SAME var is what makes their corners align, and
@@ -346,7 +370,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
                             ...(cardStyleVars && '--card-padding' in cardStyleVars
                                 ? { padding: cardStyleVars['--card-padding'] }
                                 : null),
-                        }, children: _jsx("div", { className: cn('min-h-0', autoHeight ? 'flex-none overflow-visible' : 'flex-1 overflow-auto'), children: autoHeight ? (_jsx("div", { ref: measureRef, className: "flow-root", children: scopedContent })) : (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 })) : 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] }));
 }));
 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
@@ -354,7 +378,7 @@ export function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVer
 // adapters then defaulted it back to true. With v2's handle gap fixed,
 // the safe default is true so any consumer who forgets to set it still
 // gets a usable canvas. Opt out per-page with isResizable={false}.
-isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, defaultAutoHeight, 
+isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, defaultAutoHeight, layoutMigrations, 
 // CHROME OFF BY DEFAULT — the inversion. See `GridItemProps.chrome`.
 // An app that is not ready to migrate its own card surfaces passes
 // `itemChrome` to get the pre-2.0.0 behaviour back for every slot, and
@@ -369,6 +393,7 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
         editorEventNames,
         preferenceAdapter,
         defaultAutoHeight,
+        layoutMigrations,
     });
     // Auto-height dispatcher (blueprint amendment A1, hardened per quality
     // review 2026-07-14). `GridItem`'s ResizeObserver calls this per-widget

package/dist/index.d.ts

@@ -7,8 +7,10 @@ export type { DraggableCardPageProps } from './DraggableCardPage.js';
 export { buildCanvasCardLayout, DEFAULT_CANVAS_CARD_WIDTH, flattenCanvasCards, isCanvasCardElement, describeNode, clampColumns, CANVAS_GRID_COLUMNS, } from './canvasCardLayout.js';
 export type { CanvasCardLayoutResult } from './canvasCardLayout.js';
 export type { WidgetConfig, PageEditorLauncherProps } from './PageEditorLauncher.js';
-export { usePageGridLayout, DEFAULT_EDITOR_EVENT_NAMES, PAGE_GRID_EDITING_EVENT, } from './usePageGridLayout.js';
+export { usePageGridLayout, migrateSavedLayout, DEFAULT_EDITOR_EVENT_NAMES, PACKAGE_LAYOUT_EPOCH, PAGE_GRID_EDITING_EVENT, } from './usePageGridLayout.js';
 export type { PageGridEditingEventDetail } from './usePageGridLayout.js';
+export { adoptUnchangedDefaults } from './layoutMigrations.js';
+export type { PreviousItemDefault } from './layoutMigrations.js';
 export { rescaleLayout } from './rescaleLayout.js';
 export { computeAutoHeightRows } from './autoHeight.js';
 export type { ComputeAutoHeightRowsOptions } from './autoHeight.js';
@@ -20,7 +22,7 @@ export { useLocalPreference, defaultPreferenceAdapter } from './preferences.js';
 export { RelationshipField } from './RelationshipField.js';
 export type { RelationshipFieldProps } from './RelationshipField.js';
 export { isRelationshipWritable } from './relationshipCatalog.js';
-export type { EntityWidgetDetail, EntityWidgetFactoryOptions, GridLayoutItem, GridLayouts, PageGridLayoutProps, PageGridPreferenceAdapter, PageGridPreferenceFactory, RelationshipCatalog, RelationshipCatalogEntry, RelationshipFieldOption, RelationshipWidgetDetail, RelationshipWidgetFactoryOptions, UsePageGridLayoutOptions, UsePageGridLayoutResult, WidgetMeta, } from './types.js';
+export type { EntityWidgetDetail, EntityWidgetFactoryOptions, GridLayoutItem, GridLayouts, PageGridLayoutProps, PageGridPreferenceAdapter, PageGridPreferenceFactory, RelationshipCatalog, RelationshipCatalogEntry, RelationshipFieldOption, RelationshipWidgetDetail, RelationshipWidgetFactoryOptions, LayoutMigration, UsePageGridLayoutOptions, UsePageGridLayoutResult, WidgetMeta, } from './types.js';
 export { BORDER_TONES, BORDER_STYLES, DEFAULT_CARD_STYLE, RADIUS_RANGE, BORDER_WIDTH_RANGE, PADDING_RANGE, normaliseCardStyle, isDefaultCardStyle, toCssVars as cardStyleToCssVars, describeCardStyle, } from './cardStyle.js';
 export type { CardStyle, BorderTone, BorderStyle, Elevation } from './cardStyle.js';
 export { ElementScopeProvider, useElementScope, elementRef, describeElement, parseElementRef, } from './elementScope.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,MAAM,qBAAqB,CAAC;AACrD,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,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,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,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":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,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"}

package/dist/index.js

@@ -3,7 +3,8 @@ export { PageEditorLauncher } from './PageEditorLauncher.js';
 export { CanvasCard } from './CanvasCard.js';
 export { DraggableCardPage } from './DraggableCardPage.js';
 export { buildCanvasCardLayout, DEFAULT_CANVAS_CARD_WIDTH, flattenCanvasCards, isCanvasCardElement, describeNode, clampColumns, CANVAS_GRID_COLUMNS, } from './canvasCardLayout.js';
-export { usePageGridLayout, DEFAULT_EDITOR_EVENT_NAMES, PAGE_GRID_EDITING_EVENT, } from './usePageGridLayout.js';
+export { usePageGridLayout, migrateSavedLayout, DEFAULT_EDITOR_EVENT_NAMES, PACKAGE_LAYOUT_EPOCH, PAGE_GRID_EDITING_EVENT, } from './usePageGridLayout.js';
+export { adoptUnchangedDefaults } from './layoutMigrations.js';
 export { rescaleLayout } from './rescaleLayout.js';
 export { computeAutoHeightRows } from './autoHeight.js';
 export { WYSIWYG_REQUIRED_PRIMITIVES, WYSIWYG_SURFACE_CONTRACTS, assertWysiwygPrimitiveCoverage, getWysiwygSurfaceContract, } from './wysiwygContract.js';

package/dist/layoutMigrations.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Migrations for a `layoutVersion` bump — the alternative to throwing the
+ * user's arrangement away.
+ *
+ * `usePageGridLayout` had exactly one response to a version bump: overwrite
+ * the stored layout with `defaultLayouts`. That is right for the reason
+ * crm7's dashboard epoch 8 was raised — a saved layout referencing widgets
+ * that no longer exist cannot be repaired — and wrong for the reason a
+ * version usually gets bumped, which is that a DEFAULT changed. crm7#2490
+ * bumped four routes purely to change default card widths; measured on one
+ * account, that discarded 14 stored layouts.
+ *
+ * The doctrine is already in `usePageGridLayout.ts`, in the derived-breakpoint
+ * heal: "`lg` … is preserved untouched, so nobody loses the arrangement they
+ * made." A migration is how a version bump keeps that promise.
+ */
+import type { LayoutMigration } from './types.js';
+/**
+ * The subset of an item's OLD default a migration compares against.
+ *
+ * `w` is required, because the whole test is "does the stored value still equal
+ * what the page used to author?". `minW` and `position` are optional: state
+ * them only where the bump actually moved them, because stating a value is what
+ * makes it a candidate for replacement.
+ *
+ * `position` is `{x, y}` and not two loose fields ON PURPOSE. Half a match is
+ * not a match: an item whose `x` still equals the old default but whose `y` does
+ * not was moved, and adopting only `x` would invent a third position that
+ * neither the user nor the page ever chose. Making the pair a single object
+ * means a caller cannot record half of it by accident.
+ */
+export interface PreviousItemDefault {
+    w: number;
+    minW?: number;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * A migration for a bump that changed DEFAULTS — widths, positions, or both.
+ *
+ * One rule, applied per item: **adopt what the user never chose, keep what they
+ * did.** A stored value still equal to the old default was never a decision; it
+ * is inherited furniture.
+ *
+ *   saved position === the OLD default position
+ *       -> the user never placed this card. Adopt the new default `x` and `y`
+ *          (atomically — never one without the other), and go on to consider
+ *          its width.
+ *   saved position !== the OLD default position
+ *       -> the user placed this card. It is IMMUNE: position and width are both
+ *          left alone. A card someone put somewhere by hand must not silently
+ *          change size underneath them either, and reflowing around a
+ *          hand-placed card is how a deliberate arrangement stops making sense.
+ *
+ *   saved w === the OLD default w  ->  adopt the new default width
+ *   saved w !== the OLD default w  ->  the user sized it; keep it
+ *
+ * and the same comparison for `minW`. Height, `autoHeight`, `chrome`,
+ * `hUserSet` and everything else are never touched.
+ *
+ * An entry that records no `position` is a WIDTH-ONLY migration: nothing moves.
+ * That is the pre-existing behaviour and is kept so a migration written before
+ * the position rule existed cannot start relocating cards.
+ *
+ * Why position is in scope at all, since it did not start that way: treating
+ * width as inherited while treating position as sacred splits one rule into two,
+ * and produces a layout nobody authored. Measured on `/clients` — the four stat
+ * cards asked for `w={3}` and stored 4 (the default `minW` clamps `w` up), so
+ * three filled the row and the fourth wrapped. Adopting only widths narrowed
+ * them to 3 but left them at x 0/4/8 with the fourth still wrapped: neither the
+ * arrangement the user had nor the 0/3/6/9 the page now authors. Pinned in
+ * `layoutVersionMigration.test.tsx`.
+ *
+ * @param previousDefaults keyed by layout item id (`i` / `cardKey`). An item
+ *   with no entry is passed through untouched, so a bump only has to name the
+ *   items whose defaults actually moved.
+ */
+export declare function adoptUnchangedDefaults(previousDefaults: Readonly<Record<string, PreviousItemDefault>>): LayoutMigration;
+//# sourceMappingURL=layoutMigrations.d.ts.map

package/dist/layoutMigrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layoutMigrations.d.ts","sourceRoot":"","sources":["../src/layoutMigrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAA+B,eAAe,EAAE,MAAM,YAAY,CAAC;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,GAC9D,eAAe,CA2CjB"}

package/dist/layoutMigrations.js

@@ -0,0 +1,102 @@
+/**
+ * Migrations for a `layoutVersion` bump — the alternative to throwing the
+ * user's arrangement away.
+ *
+ * `usePageGridLayout` had exactly one response to a version bump: overwrite
+ * the stored layout with `defaultLayouts`. That is right for the reason
+ * crm7's dashboard epoch 8 was raised — a saved layout referencing widgets
+ * that no longer exist cannot be repaired — and wrong for the reason a
+ * version usually gets bumped, which is that a DEFAULT changed. crm7#2490
+ * bumped four routes purely to change default card widths; measured on one
+ * account, that discarded 14 stored layouts.
+ *
+ * The doctrine is already in `usePageGridLayout.ts`, in the derived-breakpoint
+ * heal: "`lg` … is preserved untouched, so nobody loses the arrangement they
+ * made." A migration is how a version bump keeps that promise.
+ */
+/**
+ * A migration for a bump that changed DEFAULTS — widths, positions, or both.
+ *
+ * One rule, applied per item: **adopt what the user never chose, keep what they
+ * did.** A stored value still equal to the old default was never a decision; it
+ * is inherited furniture.
+ *
+ *   saved position === the OLD default position
+ *       -> the user never placed this card. Adopt the new default `x` and `y`
+ *          (atomically — never one without the other), and go on to consider
+ *          its width.
+ *   saved position !== the OLD default position
+ *       -> the user placed this card. It is IMMUNE: position and width are both
+ *          left alone. A card someone put somewhere by hand must not silently
+ *          change size underneath them either, and reflowing around a
+ *          hand-placed card is how a deliberate arrangement stops making sense.
+ *
+ *   saved w === the OLD default w  ->  adopt the new default width
+ *   saved w !== the OLD default w  ->  the user sized it; keep it
+ *
+ * and the same comparison for `minW`. Height, `autoHeight`, `chrome`,
+ * `hUserSet` and everything else are never touched.
+ *
+ * An entry that records no `position` is a WIDTH-ONLY migration: nothing moves.
+ * That is the pre-existing behaviour and is kept so a migration written before
+ * the position rule existed cannot start relocating cards.
+ *
+ * Why position is in scope at all, since it did not start that way: treating
+ * width as inherited while treating position as sacred splits one rule into two,
+ * and produces a layout nobody authored. Measured on `/clients` — the four stat
+ * cards asked for `w={3}` and stored 4 (the default `minW` clamps `w` up), so
+ * three filled the row and the fourth wrapped. Adopting only widths narrowed
+ * them to 3 but left them at x 0/4/8 with the fourth still wrapped: neither the
+ * arrangement the user had nor the 0/3/6/9 the page now authors. Pinned in
+ * `layoutVersionMigration.test.tsx`.
+ *
+ * @param previousDefaults keyed by layout item id (`i` / `cardKey`). An item
+ *   with no entry is passed through untouched, so a bump only has to name the
+ *   items whose defaults actually moved.
+ */
+export function adoptUnchangedDefaults(previousDefaults) {
+    return (saved, defaults) => {
+        const migrated = { lg: [] };
+        for (const breakpoint of Object.keys(saved)) {
+            const defaultItems = defaults[breakpoint] ??
+                defaults.lg ??
+                [];
+            const defaultByKey = new Map(defaultItems.map((item) => [item.i, item]));
+            migrated[breakpoint] = (saved[breakpoint] ?? []).map((item) => {
+                const previous = previousDefaults[item.i];
+                const current = defaultByKey.get(item.i);
+                // No recorded old default, or the item is gone from the new defaults:
+                // there is nothing to compare against, so nothing is a candidate.
+                if (!previous || !current)
+                    return item;
+                // Position is decided FIRST, because a moved item is immune to the
+                // width rule as well — returning the item itself, not a copy, so the
+                // immunity is visible in the object identity too.
+                const placed = previous.position !== undefined &&
+                    (item.x !== previous.position.x || item.y !== previous.position.y);
+                if (placed)
+                    return item;
+                // A fresh object every time — the caller's array is state that other
+                // renders still hold, and mutating it in place would edit the "before"
+                // out from under anyone comparing the two.
+                const next = { ...item };
+                if (previous.position !== undefined) {
+                    next.x = current.x;
+                    next.y = current.y;
+                }
+                if (item.w === previous.w)
+                    next.w = current.w;
+                if (previous.minW !== undefined && item.minW === previous.minW) {
+                    if (current.minW === undefined)
+                        delete next.minW;
+                    else
+                        next.minW = current.minW;
+                }
+                return next;
+            });
+        }
+        if (!migrated.lg)
+            migrated.lg = saved.lg ?? [];
+        return migrated;
+    };
+}

package/dist/types.d.ts

@@ -53,6 +53,17 @@ export interface GridLayouts {
     lg: GridLayoutItem[];
     [key: string]: GridLayoutItem[];
 }
+/**
+ * Transforms a saved layout from the version immediately below a bump to the
+ * version at it. Pure: it is handed the stored layout and the NEW authored
+ * defaults, and returns the layout to store.
+ *
+ * Registered per target version in {@link UsePageGridLayoutOptions.layoutMigrations}.
+ * A step with no registered migration falls back to the wholesale discard,
+ * which is the correct answer when a bump's reason is that saved layouts
+ * reference widgets that no longer exist.
+ */
+export type LayoutMigration = (saved: GridLayouts, defaults: GridLayouts) => GridLayouts;
 export interface PageGridPreferenceAdapter<T> {
     value: T;
     setValue: (value: T | ((previous: T) => T)) => void;
@@ -75,6 +86,40 @@ export interface UsePageGridLayoutOptions {
      * can always opt out with an explicit `autoHeight: false`.
      */
     defaultAutoHeight?: boolean;
+    /**
+     * Migrations that TRANSFORM a stored layout across a `layoutVersion` bump
+     * instead of destroying it, keyed by the version each one produces.
+     *
+     * Without this, every bump has exactly one outcome: the stored layout is
+     * overwritten with `defaultLayouts` and every card position the user ever
+     * dragged on that page is gone, for every user. That is the right answer
+     * when the bump's reason is that saved layouts reference widgets which no
+     * longer exist (crm7's dashboard epoch 8), and the wrong one for the reason
+     * a version usually moves — a DEFAULT changed. crm7#2490 bumped four routes
+     * purely to change default card widths and, measured on one account, cost 14
+     * stored layouts.
+     *
+     * Keys are in the SAME version space as `layoutVersion` on the component you
+     * pass them to — `layoutVersion={2}` pairs with `{ 2: … }`. Any app-level
+     * epoch (`DraggableCardPage`'s `layoutEpoch`) and the package-level
+     * `PACKAGE_LAYOUT_EPOCH` are applied to these keys exactly as they are
+     * applied to `layoutVersion`, so a page author never writes an epoch down.
+     *
+     * Every step from the stored version up to the current one must have a
+     * registered migration; they are applied in ascending order. If ANY step in
+     * that span has none, the whole span falls back to the wholesale discard —
+     * a missing migration means "nobody has said this transition is safe", and
+     * guessing is how a layout gets silently corrupted rather than reset. A
+     * `PACKAGE_LAYOUT_EPOCH` bump therefore discards by construction, which is
+     * what that lever is for.
+     *
+     * Use a module-level constant, not an object literal in the render body:
+     * this is an effect dependency.
+     *
+     * @see adoptUnchangedDefaults for the common case — a bump that only moved
+     *   default widths and/or default positions.
+     */
+    layoutMigrations?: Readonly<Record<number, LayoutMigration>>;
 }
 export interface WidgetMeta {
     label: string;

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,4 @@
-import type { UsePageGridLayoutOptions, UsePageGridLayoutResult } from './types.js';
+import type { GridLayouts, LayoutMigration, UsePageGridLayoutOptions, UsePageGridLayoutResult } from './types.js';
 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"];
 /**
  * Event name broadcast on `window` whenever any PageGridLayout transitions
@@ -38,9 +38,38 @@ export declare const PAGE_GRID_EDITING_EVENT = "bsuite-page-grid-editing";
  * floor.
  */
 export declare const PACKAGE_LAYOUT_EPOCH = 2000;
+/**
+ * Walk a stored layout from the version it was written at up to the version
+ * the page now declares, applying one registered migration per step.
+ *
+ * Returns the migrated layout, or `null` meaning "this span cannot be
+ * migrated — discard". Discarding is not a failure mode here; it is the
+ * pre-existing behaviour, kept deliberately as the fallback. crm7's dashboard
+ * epoch 8 was raised because saved layouts referenced widgets that no longer
+ * existed, and no transformation can repair that. A step nobody registered a
+ * migration for means nobody has said the transition is safe, and inventing
+ * one silently corrupts a layout instead of resetting it.
+ *
+ * Consequences that fall out of this rule, all of them wanted:
+ *   - A first visit (`from` 0) has no registered step and no stored layout to
+ *     preserve, so it discards onto the defaults exactly as before.
+ *   - A `PACKAGE_LAYOUT_EPOCH` bump moves the target by a thousand, so the span
+ *     cannot be covered and every consumer resets — which is what that lever
+ *     exists to do.
+ *
+ * Exported for direct unit testing: this is the decision, and it should be
+ * assertable without a React tree around it.
+ */
+export declare function migrateSavedLayout({ saved, defaults, from, to, migrations, }: {
+    saved: GridLayouts | undefined;
+    defaults: GridLayouts;
+    from: number;
+    to: number;
+    migrations: ReadonlyMap<number, LayoutMigration> | null;
+}): GridLayouts | null;
 export interface PageGridEditingEventDetail {
     pageKey: string;
     editing: boolean;
 }
-export declare function usePageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVersion, canEditPage, editorEventNames, preferenceAdapter, defaultAutoHeight, }: UsePageGridLayoutOptions): UsePageGridLayoutResult;
+export declare function usePageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVersion, canEditPage, editorEventNames, preferenceAdapter, defaultAutoHeight, layoutMigrations, }: UsePageGridLayoutOptions): UsePageGridLayoutResult;
 //# sourceMappingURL=usePageGridLayout.d.ts.map

package/dist/usePageGridLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePageGridLayout.d.ts","sourceRoot":"","sources":["../src/usePageGridLayout.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAGV,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,0BAA0B,2IAM7B,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAiBzC,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,GAClB,EAAE,wBAAwB,GAAG,uBAAuB,CAsuBpD"}
+{"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;;;;;;;;GAQG;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,CA8yBpD"}

package/dist/usePageGridLayout.js

@@ -62,7 +62,65 @@ export const PACKAGE_LAYOUT_EPOCH = 2000;
  * opts out with an explicit `autoHeight: false`.
  */
 const DEFAULT_ITEM_AUTO_HEIGHT = true;
-export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, layoutVersion = 1, canEditPage = true, editorEventNames = DEFAULT_EDITOR_EVENT_NAMES, preferenceAdapter = defaultPreferenceAdapter, defaultAutoHeight, }) {
+/**
+ * Walk a stored layout from the version it was written at up to the version
+ * the page now declares, applying one registered migration per step.
+ *
+ * Returns the migrated layout, or `null` meaning "this span cannot be
+ * migrated — discard". Discarding is not a failure mode here; it is the
+ * pre-existing behaviour, kept deliberately as the fallback. crm7's dashboard
+ * epoch 8 was raised because saved layouts referenced widgets that no longer
+ * existed, and no transformation can repair that. A step nobody registered a
+ * migration for means nobody has said the transition is safe, and inventing
+ * one silently corrupts a layout instead of resetting it.
+ *
+ * Consequences that fall out of this rule, all of them wanted:
+ *   - A first visit (`from` 0) has no registered step and no stored layout to
+ *     preserve, so it discards onto the defaults exactly as before.
+ *   - A `PACKAGE_LAYOUT_EPOCH` bump moves the target by a thousand, so the span
+ *     cannot be covered and every consumer resets — which is what that lever
+ *     exists to do.
+ *
+ * Exported for direct unit testing: this is the decision, and it should be
+ * assertable without a React tree around it.
+ */
+export function migrateSavedLayout({ saved, defaults, from, to, migrations, }) {
+    if (!migrations || migrations.size === 0)
+        return null;
+    if (from >= to)
+        return null;
+    // Nothing stored (or an empty object) is not an arrangement worth carrying
+    // across — and `rawLayouts` already treats an empty stored layout as "use
+    // the defaults", so migrating it would be a no-op wearing a cost.
+    if (!saved || Object.keys(saved).length === 0)
+        return null;
+    // O(1) refusal before the loop: a span wider than the number of registered
+    // migrations must contain a step with none.
+    //
+    // This is a COST guard, not a correctness one — the loop below reaches the
+    // same `null` without it, because it bails at the first version with no
+    // migration. What it saves is AT MOST `migrations.size + 1` registry lookups,
+    // reached only when the registry happens to be contiguous from `from + 1`;
+    // measured, size 1 -> 2, size 5 -> 6, size 500 -> 501. For crm7#2490's shape
+    // — one migration keyed 2103, a first visit from 0 — it is ONE lookup, since
+    // the very first miss ends the walk.
+    //
+    // An earlier version of this comment claimed a first visit would "spin two
+    // thousand times". That was false: the work is bounded by the REGISTRY, never
+    // by the span. The guard is still worth keeping, and it is worth keeping for
+    // the size it actually has.
+    if (to - from > migrations.size)
+        return null;
+    let working = saved;
+    for (let version = from + 1; version <= to; version += 1) {
+        const migration = migrations.get(version);
+        if (!migration)
+            return null;
+        working = migration(working, defaults);
+    }
+    return working;
+}
+export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, layoutVersion = 1, canEditPage = true, editorEventNames = DEFAULT_EDITOR_EVENT_NAMES, preferenceAdapter = defaultPreferenceAdapter, defaultAutoHeight, layoutMigrations, }) {
     const effectiveLayoutVersion = layoutVersion + PACKAGE_LAYOUT_EPOCH;
     const containerRef = useRef(null);
     const [containerWidth, setContainerWidth] = useState(0);
@@ -105,21 +163,91 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
     const { value: savedLayoutCols, setValue: setLayoutCols } = preferenceAdapter(`page:${pageKey}_grid_cols`, defaultCols);
     const { value: savedBaseCols, setValue: setBaseCols } = preferenceAdapter(`page:${pageKey}_grid_base_cols`, defaultCols);
     const prefsLoaded = layoutLoaded && versionLoaded;
+    /*
+     * Migration keys arrive in the CONSUMER's version space — `layoutVersion={2}`
+     * pairs with `{ 2: … }` — and are shifted onto the stored (effective) space
+     * by exactly the same epoch that shifts `layoutVersion`. That symmetry is the
+     * point: a page author writes the number they bumped, and never has to know
+     * `PACKAGE_LAYOUT_EPOCH` exists. `DraggableCardPage` applies its own
+     * `layoutEpoch` to both in the same way, one level up.
+     */
+    const effectiveMigrations = useMemo(() => {
+        if (!layoutMigrations)
+            return null;
+        const byEffectiveVersion = new Map();
+        for (const [version, migration] of Object.entries(layoutMigrations)) {
+            byEffectiveVersion.set(Number(version) + PACKAGE_LAYOUT_EPOCH, migration);
+        }
+        return byEffectiveVersion;
+    }, [layoutMigrations]);
+    /*
+     * The stored layout, mirrored for the version gate below — which must READ it
+     * without DEPENDING on it.
+     *
+     * Depending on it would re-run the gate on every drag that saves a layout,
+     * and worse, would re-run it in the window between the gate writing the
+     * migrated layout and the new version landing: an adapter that surfaces those
+     * two writes in separate renders would then apply the same migration twice.
+     * `adoptUnchangedDefaults` happens to be idempotent; a migration in general is
+     * not, and a contract that only holds for the migrations that exist today is
+     * not a contract.
+     *
+     * `useLayoutEffect`, not a render-phase assignment and not `useEffect`: all
+     * layout effects for a commit run before any passive effect, so on mount this
+     * is populated before the gate's `useEffect` reads it. Declared here, above
+     * the gate, so that ordering is visible rather than inferred.
+     */
+    const savedLayoutForVersionGateRef = useRef(savedLayout);
+    useLayoutEffect(() => {
+        savedLayoutForVersionGateRef.current = savedLayout;
+    }, [savedLayout]);
     useEffect(() => {
         if (!prefsLoaded)
             return;
-        if ((savedLayoutVersion ?? 0) < effectiveLayoutVersion) {
-            startTransition(() => {
-                setSavedLayout(defaultLayouts);
+        const storedVersion = savedLayoutVersion ?? 0;
+        if (storedVersion >= effectiveLayoutVersion)
+            return;
+        /*
+         * MIGRATE, DO NOT DISCARD.
+         *
+         * This used to have one branch: overwrite the stored layout with
+         * `defaultLayouts`. So ANY `layoutVersion` bump threw away every card
+         * position the user had ever dragged on that page, for every user — and
+         * the commonest reason to bump a version is that a DEFAULT WIDTH changed,
+         * which is a transformation, not a reason to lose an arrangement.
+         * crm7#2490 bumped four routes purely to change default widths; measured on
+         * one account (braden@braden.com.au), that was 14 layouts.
+         *
+         * The doctrine is forty lines below, in the derived-breakpoint heal: "`lg`
+         * … is preserved untouched, so nobody loses the arrangement they made."
+         * `migrateSavedLayout` returning null keeps the discard for the case that
+         * genuinely needs it.
+         */
+        const migrated = migrateSavedLayout({
+            saved: savedLayoutForVersionGateRef.current,
+            defaults: defaultLayouts,
+            from: storedVersion,
+            to: effectiveLayoutVersion,
+            migrations: effectiveMigrations,
+        });
+        startTransition(() => {
+            setSavedLayout(migrated ?? defaultLayouts);
+            // Column choice is part of the arrangement, not part of the layout array:
+            // a migration preserves what the user set up, so it must not reset these
+            // either. A discard still does — the layout it is restoring is authored
+            // at `defaultCols`, and leaving a stale `baseCols` behind would rescale
+            // the fresh defaults against a column count nothing authored them at.
+            if (migrated === null) {
                 setLayoutCols(defaultCols);
                 setBaseCols(defaultCols);
-                setSavedLayoutVersion(effectiveLayoutVersion);
-            });
-        }
+            }
+            setSavedLayoutVersion(effectiveLayoutVersion);
+        });
     }, [
         defaultCols,
         defaultLayouts,
         effectiveLayoutVersion,
+        effectiveMigrations,
         prefsLoaded,
         savedLayoutVersion,
         setBaseCols,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/page-builder",
-  "version": "2.6.1",
+  "version": "2.7.1-next.0",
   "description": "Shared BSuite responsive page-builder grid and layout persistence primitives",
   "type": "module",
   "license": "UNLICENSED",
@@ -33,6 +33,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:geometry": "node scripts/editor-chrome-geometry.mjs",
     "prepublishOnly": "pnpm build"
   },
   "peerDependencies": {

package/dist/cardSurfaces.stories.d.ts

@@ -1,68 +0,0 @@
-import type { ReactNode } from 'react';
-/**
- * The card-surface defect classes, made VISIBLE and DIFFABLE.
- *
- * `@bsuite/page-builder` 1.0.4, 1.0.5 and 1.0.6 each shipped GREEN AND BROKEN.
- * Types, lint, unit tests and CI cannot see a 28px card sitting inside a 24px
- * frame; only a rendered surface can. These stories exist so the chrome
- * inversion has something to be checked against that is not a number.
- *
- * Read them in pairs: the story named "…(the defect)" is what shipped up to
- * 1.0.7, and the one beside it is what 2.0.0 renders.
- */
-/**
- * Plain CSF, no `Meta`/`StoryObj` type imports.
- *
- * `@storybook/react-vite` is a devDependency of `@bsuite/ui`, which owns the
- * Storybook config; this package does not depend on Storybook and must not
- * start to, or `pnpm typecheck` here fails on a type-only import for a tool
- * that is not installed. CSF is a plain-object format — the indexer reads the
- * default export and the named exports, and the types are optional sugar.
- */
-type Story = {
-    name?: string;
-    render: () => ReactNode;
-};
-declare const _default: {
-    title: string;
-    parameters: {
-        layout: string;
-    };
-};
-export default _default;
-/**
- * THE DEFECT, exactly as it shipped. A card inside the grid item's card:
- * two radii, two 1px borders, two backgrounds. 316+ files render this.
- */
-export declare const NestedCardDoubleFrame: Story;
-/** The same content on 2.0.0 defaults: ONE border, ONE radius. */
-export declare const NestedCardSingleFrame: Story;
-/** Bare content with chrome OFF — the regression the inversion could cause. */
-export declare const BareContentNoChrome: Story;
-/** The same bare content opting IN per item. This is the migration for the 10%. */
-export declare const BareContentOptsIn: Story;
-/**
- * Every card width side by side. `w` defaulted to 12, so 1,068 of 1,729 usages
- * rendered like the last row here — one card per row, the rest of the screen
- * empty. That is the "cards don't use the available space" report.
- */
-export declare const WidthLadder: Story;
-/**
- * Card headings. `text-gradient-accent` is on 183 of 235 crm7 h1 page titles
- * and 0 of 310 crm7 h2/h3 CARD headings — the element the operator keeps
- * asking about. The pairing matters: the solid `text-(--role-text-heading)`
- * sits UNDER the gradient as the fallback layer.
- *
- * `width: fit-content` inside the utility is load-bearing. Anything that
- * overrides width makes a short heading sample only the first ~15% of the
- * gradient and render flat — indistinguishable from having no gradient at all,
- * which is why "is the class present" is not a check.
- */
-export declare const CardHeadingGradient: Story;
-export declare const CardStyleDefault: Story;
-export declare const CardStyleThickBorder: Story;
-export declare const CardStyleDashedAccent: Story;
-export declare const CardStyleSquare: Story;
-export declare const CardStyleBorderless: Story;
-export declare const CardStyleElevationLadder: Story;
-//# sourceMappingURL=cardSurfaces.stories.d.ts.map

package/dist/cardSurfaces.stories.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cardSurfaces.stories.d.ts","sourceRoot":"","sources":["../src/cardSurfaces.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC;;;;;;;;;;GAUG;AACH;;;;;;;;GAQG;AACH,KAAK,KAAK,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,SAAS,CAAA;CAAE,CAAA;;;;;;;AAEvD,wBAGC;AA0BD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAYnC,CAAA;AAED,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,EAAE,KAWnC,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,EAAE,KAWjC,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,EAAE,KAW/B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,KAyBzB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,KAoBjC,CAAA;AA2CD,eAAO,MAAM,gBAAgB,EAAE,KAK9B,CAAA;AAED,eAAO,MAAM,oBAAoB,EAAE,KAGlC,CAAA;AAED,eAAO,MAAM,qBAAqB,EAAE,KAQnC,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,KAG7B,CAAA;AAED,eAAO,MAAM,mBAAmB,EAAE,KAQjC,CAAA;AAED,eAAO,MAAM,wBAAwB,EAAE,KAatC,CAAA"}

package/dist/cardSurfaces.stories.js

@@ -1,126 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { PageGridLayout } from './PageGridLayout.js';
-import { DEFAULT_CARD_STYLE, describeCardStyle, toCssVars } from './cardStyle.js';
-export default {
-    title: 'Page Builder/Card surfaces',
-    parameters: { layout: 'fullscreen' },
-};
-/** What an app renders inside a slot: its own card. Border, radius, background. */
-function AppCard({ title, children }) {
-    return (_jsxs("div", { className: "h-full rounded-[var(--radius-card,1.5rem)] border border-border bg-card p-6 shadow-sm", children: [_jsx("h3", { className: "mb-2 text-lg font-semibold text-(--role-text-heading)", children: title }), _jsx("div", { className: "text-sm text-muted-foreground", children: children })] }));
-}
-/** Bare content: no surface of its own. This is the 10% that NEEDS the chrome. */
-function BareContent({ title }) {
-    return (_jsxs("div", { className: "p-6", children: [_jsx("h3", { className: "mb-2 text-lg font-semibold text-(--role-text-heading)", children: title }), _jsx("p", { className: "text-sm text-muted-foreground", children: "No surface of its own \u2014 this slot is the one that should opt IN to chrome." })] }));
-}
-const oneSlot = { lg: [{ i: 'a', x: 0, y: 0, w: 6, h: 6 }] };
-/**
- * THE DEFECT, exactly as it shipped. A card inside the grid item's card:
- * two radii, two 1px borders, two backgrounds. 316+ files render this.
- */
-export const NestedCardDoubleFrame = {
-    name: 'Nested card — DOUBLE FRAME (the defect)',
-    render: () => (_jsx("div", { className: "p-8", children: _jsx(PageGridLayout, { pageKey: "sb/nested-defect", defaultLayouts: oneSlot, itemChrome: true, widgets: { a: _jsx(AppCard, { title: "Quick Actions", children: "Grid item chrome ON + app card." }) } }) })),
-};
-/** The same content on 2.0.0 defaults: ONE border, ONE radius. */
-export const NestedCardSingleFrame = {
-    name: 'Nested card — ONE frame (2.0.0 default)',
-    render: () => (_jsx("div", { className: "p-8", children: _jsx(PageGridLayout, { pageKey: "sb/nested-fixed", defaultLayouts: oneSlot, widgets: { a: _jsx(AppCard, { title: "Quick Actions", children: "Grid item chrome OFF; the app card is the only surface." }) } }) })),
-};
-/** Bare content with chrome OFF — the regression the inversion could cause. */
-export const BareContentNoChrome = {
-    name: 'Bare content, chrome OFF — the regression to watch for',
-    render: () => (_jsx("div", { className: "p-8", children: _jsx(PageGridLayout, { pageKey: "sb/bare-off", defaultLayouts: oneSlot, widgets: { a: _jsx(BareContent, { title: "Pipeline Overview" }) } }) })),
-};
-/** The same bare content opting IN per item. This is the migration for the 10%. */
-export const BareContentOptsIn = {
-    name: 'Bare content, per-item chrome ON — the migration',
-    render: () => (_jsx("div", { className: "p-8", children: _jsx(PageGridLayout, { pageKey: "sb/bare-on", defaultLayouts: { lg: [{ i: 'a', x: 0, y: 0, w: 6, h: 6, chrome: true }] }, widgets: { a: _jsx(BareContent, { title: "Pipeline Overview" }) } }) })),
-};
-/**
- * Every card width side by side. `w` defaulted to 12, so 1,068 of 1,729 usages
- * rendered like the last row here — one card per row, the rest of the screen
- * empty. That is the "cards don't use the available space" report.
- */
-export const WidthLadder = {
-    name: 'Width ladder — w = 2 / 3 / 4 / 6 / 12',
-    render: () => (_jsx("div", { className: "p-8", children: _jsx(PageGridLayout, { pageKey: "sb/widths", defaultLayouts: {
-                lg: [
-                    { i: 'w2', x: 0, y: 0, w: 2, h: 4 },
-                    { i: 'w3', x: 2, y: 0, w: 3, h: 4 },
-                    { i: 'w4', x: 5, y: 0, w: 4, h: 4 },
-                    { i: 'w6', x: 0, y: 4, w: 6, h: 4 },
-                    { i: 'w12', x: 0, y: 8, w: 12, h: 4 },
-                ],
-            }, widgets: {
-                w2: _jsx(AppCard, { title: "w=2" }),
-                w3: _jsx(AppCard, { title: "w=3" }),
-                w4: _jsx(AppCard, { title: "w=4" }),
-                w6: _jsx(AppCard, { title: "w=6 \u2014 the new default" }),
-                w12: _jsx(AppCard, { title: "w=12 \u2014 the old default, one card per row" }),
-            } }) })),
-};
-/**
- * Card headings. `text-gradient-accent` is on 183 of 235 crm7 h1 page titles
- * and 0 of 310 crm7 h2/h3 CARD headings — the element the operator keeps
- * asking about. The pairing matters: the solid `text-(--role-text-heading)`
- * sits UNDER the gradient as the fallback layer.
- *
- * `width: fit-content` inside the utility is load-bearing. Anything that
- * overrides width makes a short heading sample only the first ~15% of the
- * gradient and render flat — indistinguishable from having no gradient at all,
- * which is why "is the class present" is not a check.
- */
-export const CardHeadingGradient = {
-    name: 'Card headings — with and without the gradient',
-    render: () => (_jsxs("div", { className: "grid gap-8 p-8 md:grid-cols-2", children: [_jsxs("div", { className: "rounded-[var(--radius-card,1.5rem)] border border-border bg-card p-6", children: [_jsx("h3", { className: "mb-2 text-lg font-semibold text-(--role-text-heading)", children: "Quick Actions \u2014 flat (today, 0 of 310)" }), _jsx("p", { className: "text-sm text-muted-foreground", children: "No gradient." })] }), _jsxs("div", { className: "rounded-[var(--radius-card,1.5rem)] border border-border bg-card p-6", children: [_jsx("h3", { className: "text-gradient-accent mb-2 text-lg font-semibold text-(--role-text-heading)", children: "Quick Actions \u2014 gradient (G2 target)" }), _jsx("p", { className: "text-sm text-muted-foreground", children: "`text-gradient-accent` over the solid heading token." })] })] })),
-};
-/* ------------------------------------------------------------------ *
- * OPERATOR-EDITABLE CARD APPEARANCE
- *
- * The border, corners, shadow and padding are set by the operator in the
- * canvas editor and persisted per page (see cardStyle.ts). These stories are
- * the reference for what each setting actually paints, so a change to the
- * chrome can be diffed against a picture rather than argued about.
- *
- * `toCssVars` returns ONLY the properties that differ from the default, so
- * `Default` below emits no custom properties at all — it is the control, and
- * it must look exactly like `BareContentOptsIn`. If those two ever diverge,
- * the "costs nothing until you touch it" guarantee has been broken.
- * ------------------------------------------------------------------ */
-/** Renders one slot with chrome on, under a given operator card style. */
-function StyledSurface({ style, note }) {
-    const resolved = { ...DEFAULT_CARD_STYLE, ...style };
-    const vars = toCssVars(resolved);
-    return (_jsxs("div", { className: "p-8", style: {
-            ...vars,
-            // The editor applies elevation and padding as real declarations,
-            // because each has to beat a class. Mirrored here so the story shows
-            // what the page shows.
-            ...('--card-shadow' in vars ? { ['--story-shadow']: vars['--card-shadow'] } : null),
-        }, children: [_jsx("p", { className: "mb-3 text-sm text-muted-foreground", children: note }), _jsx("p", { className: "mb-3 text-sm font-medium text-foreground", children: describeCardStyle(resolved) }), _jsx(PageGridLayout, { pageKey: `card-style-${note.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}`, defaultLayouts: oneSlot, itemChrome: true, widgets: { a: _jsx(BareContent, { title: "Operator-styled card" }) } })] }));
-}
-export const CardStyleDefault = {
-    name: 'Card style — default (emits no CSS)',
-    render: () => (_jsx(StyledSurface, { style: {}, note: "The control. No custom properties are emitted at all." })),
-};
-export const CardStyleThickBorder = {
-    name: 'Card style — 4px border',
-    render: () => _jsx(StyledSurface, { style: { borderWidth: 4 }, note: "Border width is a slider, 0-8px." }),
-};
-export const CardStyleDashedAccent = {
-    name: 'Card style — dashed accent border',
-    render: () => (_jsx(StyledSurface, { style: { borderWidth: 2, borderStyle: 'dashed', borderTone: 'accent' }, note: "Colour comes from a THEME TOKEN, never a literal, so white-labelling still applies." })),
-};
-export const CardStyleSquare = {
-    name: 'Card style — square corners',
-    render: () => _jsx(StyledSurface, { style: { radius: 0 }, note: "Corner radius is a slider, 0-48px." }),
-};
-export const CardStyleBorderless = {
-    name: 'Card style — no border',
-    render: () => (_jsx(StyledSurface, { style: { borderStyle: 'none' }, note: "A borderless card still keeps its background and radius." })),
-};
-export const CardStyleElevationLadder = {
-    name: 'Card style — elevation 0 to 4',
-    render: () => (_jsx("div", { className: "space-y-2", children: [0, 1, 2, 3, 4].map((level) => (_jsx(StyledSurface, { style: { elevation: level }, note: `--shadow-elev-${level}, from @bsuite/theme.` }, level))) })),
-};