@bsuite/page-builder 1.1.0 → 2.1.0-next.0

package/dist/CanvasCard.d.ts

@@ -35,6 +35,34 @@ export interface CanvasCardProps {
      * and was swept. Do not reintroduce it on a plain card or table.
      */
     autoHeight?: boolean;
+    /**
+     * Whether the GRID ITEM paints a card around this slot — border, radius,
+     * background, shadow. Threaded through to {@link GridLayoutItem.chrome} by
+     * `buildCanvasCardLayout`, and per-item always beats the page-level
+     * `itemChrome` prop in either direction.
+     *
+     * Leave it undefined and the app's `itemChrome` decides. Say `chrome={false}`
+     * on a slot whose content is NOT a card — a marketing section, a page
+     * heading, a chart that supplies its own surface — in an app that has set
+     * `itemChrome` true; say `chrome` on a BARE slot in an app that has not.
+     *
+     * WHY IT EXISTS AT ALL (2.1.0). 2.0.0 inverted the grid-item chrome default
+     * and offered `GridLayoutItem.chrome` as the per-slot escape hatch. That
+     * hatch was real for the handful of pages that hand-author a layout array,
+     * and UNREACHABLE for the ~1,700 CanvasCard usages that are how BSuite pages
+     * are actually written: `CanvasCardProps` did not declare the prop and
+     * `buildCanvasCardLayout` destructured a fixed set of fields, so a `chrome`
+     * written on a CanvasCard was dropped before it could reach a layout item.
+     * crm7's 2.0.0 adoption shipped a comment promising the opt-out and zero
+     * call sites able to use it. Declaring it here is what makes the promise
+     * true.
+     *
+     * Unlike `autoHeight`, this is not a hint the grid may override: a slot that
+     * says false is never framed. It also survives a drag — see the `chrome`
+     * restore in `stripAutoHeightRows`, which exists because react-grid-layout
+     * does not round-trip custom item props.
+     */
+    chrome?: boolean;
     /** Card body — typically a single card or page-header element. */
     children: ReactNode;
 }

package/dist/CanvasCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CanvasCard.d.ts","sourceRoot":"","sources":["../src/CanvasCard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;IAC3B,qEAAqE;IACrE,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;IAC9B,4FAA4F;IAC5F,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAExD;yBAFe,UAAU"}
+{"version":3,"file":"CanvasCard.d.ts","sourceRoot":"","sources":["../src/CanvasCard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;IAC3B,qEAAqE;IACrE,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;IAC9B,4FAA4F;IAC5F,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAExD;yBAFe,UAAU"}

package/dist/DraggableCardPage.d.ts

@@ -109,7 +109,7 @@ export type DraggableCardPageProps = Omit<PageGridLayoutProps, 'widgets' | 'defa
      * Width, in grid columns, for cards that do not set `w` themselves.
      *
      * Defaults to `DEFAULT_CANVAS_CARD_WIDTH` (6 — half the grid, two cards per
-     * row) as of 1.1.0. Pass 12 to restore the pre-1.1.0 full-width stack while
+     * row) as of 2.0.0. Pass 12 to restore the pre-2.0.0 full-width stack while
      * an app migrates its pages.
      */
     defaultCardWidth?: number;

package/dist/PageGridLayout.js

@@ -236,7 +236,7 @@ export function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVer
 isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, defaultAutoHeight, 
 // 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-1.1.0 behaviour back for every slot, and
+// `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, activeCols, activeCompactor, onLayoutChange, handleColumnChange, handleBreakpointChange, handleCompact, handleReset, addWidget, moveWidget, setWidgetLocked, applyAutoHeightRows, autoHeightRows, resetConfirmOpen, setResetConfirmOpen, containerRef, containerWidth, } = usePageGridLayout({

package/dist/canvasCardLayout.d.ts

@@ -15,7 +15,7 @@ export declare const CANVAS_GRID_COLUMNS = 12;
 /**
  * The width a `CanvasCard` gets when its author does not say.
  *
- * SIX, i.e. half the grid — changed from twelve in 1.1.0. Twelve on a
+ * SIX, i.e. half the grid — changed from twelve in 2.0.0. Twelve on a
  * twelve-column grid means every card that omits `w` renders full width and
  * the page becomes a single vertical stack. Measured across the estate on
  * 2026-08-25: **1,068 of 1,729 CanvasCard usages omit `w`** (BSU and conduit

package/dist/canvasCardLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvasCardLayout.d.ts","sourceRoot":"","sources":["../src/canvasCardLayout.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,GACd,IAAI,IAAI,YAAY,CAAC,eAAe,CAAC,CAKvC;AAQD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAQpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG;IACpD,KAAK,EAAE,YAAY,CAAC,eAAe,CAAC,EAAE,CAAC;IACvC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAqBA;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAI,EAAE,GAAG,SAAsB,UAE7E;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,yEAAyE;IACzE,OAAO,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,EACnB,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACtC,sBAAsB,CA2CxB"}
+{"version":3,"file":"canvasCardLayout.d.ts","sourceRoot":"","sources":["../src/canvasCardLayout.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,GACd,IAAI,IAAI,YAAY,CAAC,eAAe,CAAC,CAKvC;AAQD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAQpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG;IACpD,KAAK,EAAE,YAAY,CAAC,eAAe,CAAC,EAAE,CAAC;IACvC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAqBA;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAI,EAAE,GAAG,SAAsB,UAE7E;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,yEAAyE;IACzE,OAAO,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,EACnB,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACtC,sBAAsB,CAsDxB"}

package/dist/canvasCardLayout.js

@@ -14,7 +14,7 @@ export const CANVAS_GRID_COLUMNS = 12;
 /**
  * The width a `CanvasCard` gets when its author does not say.
  *
- * SIX, i.e. half the grid — changed from twelve in 1.1.0. Twelve on a
+ * SIX, i.e. half the grid — changed from twelve in 2.0.0. Twelve on a
  * twelve-column grid means every card that omits `w` renders full width and
  * the page becomes a single vertical stack. Measured across the estate on
  * 2026-08-25: **1,068 of 1,729 CanvasCard usages omit `w`** (BSU and conduit
@@ -115,7 +115,7 @@ export function buildCanvasCardLayout(children, options = {}) {
     for (const child of cards) {
         // autoHeight defaults to TRUE — cards track measured content height unless
         // a card explicitly opts out for a virtualized list. See CanvasCardProps.
-        const { cardKey, h = 6, minH = 2, minW = 4, autoHeight = true, children: body, } = child.props;
+        const { cardKey, h = 6, minH = 2, minW = 4, autoHeight = true, chrome, children: body, } = child.props;
         const normalizedMinW = clampColumns(minW);
         const width = clampColumns(child.props.w ?? defaultWidth, normalizedMinW);
         if (x + width > CANVAS_GRID_COLUMNS) {
@@ -133,6 +133,16 @@ export function buildCanvasCardLayout(children, options = {}) {
             minW: normalizedMinW,
             minH,
             ...(autoHeight ? { autoHeight: true } : {}),
+            // `chrome` is THREE-VALUED and only two of those values are the card's
+            // own: true and false both have to reach the layout item, and undefined
+            // has to stay absent so `layoutItem.chrome ?? itemChrome` can fall
+            // through to the app default. Writing `chrome: chrome` unconditionally
+            // would put an explicit `undefined` on every item, which is still absent
+            // to `??` but is NOT absent to a structural comparison — and
+            // `stripAutoHeightRows` compares items across a gesture. Spreading only
+            // when the author said something keeps the item shape identical to what
+            // 2.0.0 produced for the 1,729 cards that say nothing.
+            ...(chrome === undefined ? {} : { chrome }),
         });
         x += width;
         rowHeight = Math.max(rowHeight, h);

package/dist/cardSurfaces.stories.d.ts

@@ -8,7 +8,7 @@ import type { ReactNode } from 'react';
  * 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 1.1.0 renders.
+ * 1.0.7, and the one beside it is what 2.0.0 renders.
  */
 /**
  * Plain CSF, no `Meta`/`StoryObj` type imports.
@@ -35,7 +35,7 @@ export default _default;
  * two radii, two 1px borders, two backgrounds. 316+ files render this.
  */
 export declare const NestedCardDoubleFrame: Story;
-/** The same content on 1.1.0 defaults: ONE border, ONE radius. */
+/** 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;

package/dist/cardSurfaces.stories.js

@@ -21,9 +21,9 @@ 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 1.1.0 defaults: ONE border, ONE radius. */
+/** The same content on 2.0.0 defaults: ONE border, ONE radius. */
 export const NestedCardSingleFrame = {
-    name: 'Nested card — ONE frame (1.1.0 default)',
+    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. */

package/dist/scanner/cardHeadingScanner.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Which headings are CARD headings, and do they carry the gradient?
+ *
+ * WHY THIS EXISTS. The estate's heading gradient was implemented as a
+ * PAGE-TITLE convention and shipped: 183 of 232 crm7 `<h1>` page titles carry
+ * `.text-gradient-accent`. Card headings were never in scope, and the numbers
+ * say so plainly — 0 of 304 crm7 `<h2>`/`<h3>`, 15 of 734 estate-wide. The work
+ * was done, declared complete, and covered a DIFFERENT ELEMENT than the one the
+ * operator keeps pointing at. On the very dashboard he screenshotted,
+ * "Dashboard" (h1) has the gradient and "Quick Actions", "Communication Center"
+ * and "Pipeline Overview" (h2/h3) do not.
+ *
+ * SO WHY NOT JUST GREP `<h2`? Because `<h2>` is not the same thing as "card
+ * heading", and a sweep that treats them as equal gradients dialog titles,
+ * empty-state titles, section labels and table captions along with the cards.
+ * The operator asked for card headings. A detector that cannot tell a card
+ * heading from any other heading would deliver 734 changes to satisfy a request
+ * about roughly 600 of them, and the excess is what gets noticed.
+ *
+ * A heading is a CARD heading here when an enclosing element paints card chrome
+ * — a card component, or a border+radius+background surface — which is the same
+ * definition `cardSurfaceScanner` already uses for nested chrome. One definition
+ * of "card", two scanners.
+ *
+ * FAIL CLOSED. A file whose JSX tags do not balance is UNKNOWN, not clean: a
+ * tag stack that has lost its place cannot say what encloses what, and
+ * "checked nothing" must not share an exit code with "found nothing" (D-92).
+ *
+ * Node-only: filesystem access, exported from `@bsuite/page-builder/scanner`.
+ */
+export interface CardHeadingFinding {
+    file: string;
+    /** `h2` or `h3`. */
+    tag: string;
+    /** 1-based line of the heading's opening tag. */
+    line: number;
+    /** The chrome element that makes this a card heading. */
+    enclosingSurface: string;
+    /** Does it already carry a gradient class? */
+    hasGradient: boolean;
+    /**
+     * Classes that fight `width: fit-content`.
+     *
+     * `.text-gradient-accent` sets `width: fit-content`, and that is load-bearing
+     * — `background-clip: text` paints across the ELEMENT BOX, so a block-level
+     * heading spanning its container samples only the first slice of the gradient
+     * and renders flat, which is indistinguishable from having no gradient at
+     * all. But a heading that is `truncate`, `flex-1`, `w-full` or `line-clamp-*`
+     * DEPENDS on filling its box, and shrink-wrapping it changes the layout.
+     * Those headings need a decision, not a codemod.
+     */
+    widthDependentClasses: string[];
+}
+export interface CardHeadingScanResult {
+    findings: CardHeadingFinding[];
+    filesScanned: number;
+    scanRootsResolved: string[];
+    /** Files whose JSX could not be walked. UNKNOWN is not clean. */
+    unknownFiles: string[];
+    summary: string;
+}
+export interface CardHeadingScannerConfig {
+    projectRoot: string;
+    scanRoots: string[];
+    /** Component names that count as card chrome. */
+    cardTags: string[];
+    /** Extra chrome components, as in `cardSurfaceScanner`. */
+    nestedChromeTags?: string[];
+    /** Heading tags to consider. Defaults to h2 and h3 — h1 is the page title. */
+    headingTags?: string[];
+    /** Classes that already paint a heading gradient. */
+    gradientClasses?: string[];
+    extensions?: string[];
+}
+interface JsxTag {
+    kind: 'open' | 'close' | 'self';
+    tag: string;
+    attrs: string;
+    index: number;
+}
+/**
+ * Tokenise JSX tags with their kind and offset.
+ *
+ * `openingTags` in the sibling module is deliberately kind-blind — it only has
+ * to find chrome inside a known block. Ancestry needs a stack, and a stack
+ * needs to know which tags close.
+ */
+export declare function jsxTags(source: string): JsxTag[];
+export declare function scanCardHeadings(config: CardHeadingScannerConfig): CardHeadingScanResult;
+export {};
+//# sourceMappingURL=cardHeadingScanner.d.ts.map

package/dist/scanner/cardHeadingScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardHeadingScanner.d.ts","sourceRoot":"","sources":["../../src/scanner/cardHeadingScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;OAUG;IACH,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,iEAAiE;IACjE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAkDD,UAAU,MAAM;IACd,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAqDhD;AAsCD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,wBAAwB,GAAG,qBAAqB,CA+FxF"}

package/dist/scanner/cardHeadingScanner.js

@@ -0,0 +1,278 @@
+/**
+ * Which headings are CARD headings, and do they carry the gradient?
+ *
+ * WHY THIS EXISTS. The estate's heading gradient was implemented as a
+ * PAGE-TITLE convention and shipped: 183 of 232 crm7 `<h1>` page titles carry
+ * `.text-gradient-accent`. Card headings were never in scope, and the numbers
+ * say so plainly — 0 of 304 crm7 `<h2>`/`<h3>`, 15 of 734 estate-wide. The work
+ * was done, declared complete, and covered a DIFFERENT ELEMENT than the one the
+ * operator keeps pointing at. On the very dashboard he screenshotted,
+ * "Dashboard" (h1) has the gradient and "Quick Actions", "Communication Center"
+ * and "Pipeline Overview" (h2/h3) do not.
+ *
+ * SO WHY NOT JUST GREP `<h2`? Because `<h2>` is not the same thing as "card
+ * heading", and a sweep that treats them as equal gradients dialog titles,
+ * empty-state titles, section labels and table captions along with the cards.
+ * The operator asked for card headings. A detector that cannot tell a card
+ * heading from any other heading would deliver 734 changes to satisfy a request
+ * about roughly 600 of them, and the excess is what gets noticed.
+ *
+ * A heading is a CARD heading here when an enclosing element paints card chrome
+ * — a card component, or a border+radius+background surface — which is the same
+ * definition `cardSurfaceScanner` already uses for nested chrome. One definition
+ * of "card", two scanners.
+ *
+ * FAIL CLOSED. A file whose JSX tags do not balance is UNKNOWN, not clean: a
+ * tag stack that has lost its place cannot say what encloses what, and
+ * "checked nothing" must not share an exit code with "found nothing" (D-92).
+ *
+ * Node-only: filesystem access, exported from `@bsuite/page-builder/scanner`.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { stripComments, elementDeclaresCardChrome } from './cardSurfaceScanner.js';
+const DEFAULT_HEADINGS = ['h2', 'h3'];
+const DEFAULT_GRADIENT_CLASSES = ['text-gradient-accent', 'gradient-text'];
+/**
+ * Classes whose effect DEPENDS on the heading filling its box.
+ *
+ * `.text-gradient-accent` sets `width: fit-content`, and that is load-bearing —
+ * `background-clip: text` paints across the ELEMENT BOX, so a block-level
+ * heading spanning its container samples only the first slice of the gradient
+ * and renders flat, indistinguishable from having no gradient at all. Shrinking
+ * the box is therefore not optional; it is the effect.
+ *
+ * But shrinking the box is VISIBLE wherever the box itself is visible or
+ * positioned. Three families, and the first was the only one measured on the
+ * first pass:
+ *
+ *   1. SIZE — `truncate`, `flex-1`, `w-full`, `line-clamp-*`. Fit-content never
+ *      truncates and never fills.
+ *   2. POSITION — `text-center`, `mx-auto`. A centred heading stops centring the
+ *      moment its box hugs the glyphs, because there is nothing left to centre
+ *      the text inside.
+ *   3. PAINT — the heading's OWN `border-*` or `bg-*`. A rule or a tinted strip
+ *      that used to span the card suddenly ends at the last letter. This is the
+ *      most visible of the three and the easiest to miss in a diff.
+ *
+ * A first, loose measurement over a three-line window put family 1 at 2 and
+ * implied the sweep was nearly free. Reading the heading's OWN attributes puts
+ * the full hazard set an order of magnitude higher. The loose number was the
+ * kind that makes a codemod look safe.
+ */
+const WIDTH_DEPENDENT = [
+    'truncate',
+    'flex-1',
+    'w-full',
+    'grow',
+    'flex-grow',
+    'text-center',
+    'mx-auto',
+];
+const WIDTH_DEPENDENT_PREFIXES = ['line-clamp-', 'basis-', 'w-', 'min-w-', 'max-w-'];
+/** The heading paints its own box — a border or a background of its own. */
+const OWN_PAINT = /(?:^|\s)(?:border(?:-[a-z0-9[\]().\-/]+)?|bg-[a-z0-9[\]().\-/]+)(?=$|\s)/;
+/** Void HTML elements never carry a closing tag. */
+const VOID_TAGS = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+/**
+ * Tokenise JSX tags with their kind and offset.
+ *
+ * `openingTags` in the sibling module is deliberately kind-blind — it only has
+ * to find chrome inside a known block. Ancestry needs a stack, and a stack
+ * needs to know which tags close.
+ */
+export function jsxTags(source) {
+    const out = [];
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] !== '<')
+            continue;
+        const close = /^<\/([A-Za-z][A-Za-z0-9._-]*)\s*>/.exec(source.slice(i, i + 80));
+        if (close) {
+            out.push({ kind: 'close', tag: close[1], attrs: '', index: i });
+            i += close[0].length - 1;
+            continue;
+        }
+        const open = /^<([A-Za-z][A-Za-z0-9._-]*)/.exec(source.slice(i, i + 64));
+        if (!open)
+            continue;
+        // KNOWN LIMITATION, measured rather than papered over. A TypeScript type
+        // argument presents as a tag to any matcher this cheap:
+        // `row.getValue<string>('code')` pushes `<string>`, and every ancestry
+        // answer after it in that file is fiction. The file is therefore reported
+        // UNKNOWN by the stack check below — 23 files across six apps, 0.8% of the
+        // tree, named individually rather than absorbed.
+        //
+        // A GUARD WAS TRIED AND REVERTED, and the measurement is why. Skipping a
+        // tag whose `<` is preceded by an identifier character catches the generics
+        // — and also catches JSX that follows TEXT (`Total<span>`), which is
+        // ordinary markup. Skipping an OPENING tag while its CLOSING tag is still
+        // counted unbalances the stack outright, so UNKNOWN went from 23 to 106.
+        // An over-eager filter feeding a stack is strictly worse than no filter,
+        // and a real parser is the fix if 23 ever stops being acceptable.
+        let j = i + open[0].length;
+        let depth = 0;
+        let quote = null;
+        let closed = false;
+        for (; j < source.length; j++) {
+            const c = source[j];
+            if (quote) {
+                if (c === quote && source[j - 1] !== '\\')
+                    quote = null;
+                continue;
+            }
+            if (c === '"' || c === "'" || c === '`') {
+                quote = c;
+                continue;
+            }
+            if (c === '{')
+                depth++;
+            else if (c === '}')
+                depth--;
+            else if (c === '>' && depth === 0) {
+                closed = true;
+                break;
+            }
+        }
+        if (!closed)
+            continue;
+        const attrs = source.slice(i + open[0].length, j);
+        const selfClosing = /\/\s*$/.test(attrs) || VOID_TAGS.has(open[1]);
+        out.push({
+            kind: selfClosing ? 'self' : 'open',
+            tag: open[1],
+            attrs: attrs.replace(/\/\s*$/, ''),
+            index: i,
+        });
+        i = j;
+    }
+    return out;
+}
+function classText(attrs) {
+    const m = /class(?:Name)?\s*=\s*(?:"([^"]*)"|'([^']*)'|\{([\s\S]*)\})/.exec(attrs);
+    if (!m)
+        return '';
+    if (m[1] !== undefined)
+        return m[1];
+    if (m[2] !== undefined)
+        return m[2];
+    const lit = /(?:"([^"]*)"|'([^']*)'|`([^`]*)`)/g;
+    const parts = [];
+    let l;
+    while ((l = lit.exec(m[3] ?? '')) !== null)
+        parts.push(l[1] ?? l[2] ?? l[3] ?? '');
+    return parts.join(' ');
+}
+function widthDependent(classes) {
+    const tokens = classes.split(/\s+/).filter(Boolean);
+    const hits = tokens.filter((t) => WIDTH_DEPENDENT.includes(t) ||
+        WIDTH_DEPENDENT_PREFIXES.some((p) => t.startsWith(p)));
+    // A heading that paints its own box: shrinking the box moves the paint.
+    for (const t of tokens)
+        if (OWN_PAINT.test(` ${t} `) && !hits.includes(t))
+            hits.push(t);
+    return hits;
+}
+function walk(dir, extensions, acc) {
+    for (const entry of readdirSync(dir)) {
+        if (entry === 'node_modules' || entry === 'dist' || entry === '.git')
+            continue;
+        const full = join(dir, entry);
+        const st = statSync(full);
+        if (st.isDirectory())
+            walk(full, extensions, acc);
+        else if (extensions.some((e) => entry.endsWith(e)) && !/\.(test|spec)\./.test(entry))
+            acc.push(full);
+    }
+}
+export function scanCardHeadings(config) {
+    const extensions = config.extensions ?? ['.tsx'];
+    const headings = new Set(config.headingTags ?? DEFAULT_HEADINGS);
+    const gradientClasses = config.gradientClasses ?? DEFAULT_GRADIENT_CLASSES;
+    const chromeTags = new Set([...config.cardTags, ...(config.nestedChromeTags ?? [])]);
+    const findings = [];
+    const unknownFiles = [];
+    const files = [];
+    const scanRootsResolved = [];
+    // D-92: assert the inputs before reporting a verdict.
+    for (const root of config.scanRoots) {
+        const abs = join(config.projectRoot, root);
+        if (!existsSync(abs))
+            throw new Error(`[cardHeadingScanner] scan root "${root}" does not exist at ${abs}. ` +
+                `A scanner that silently skips a missing root reports a false pass.`);
+        const before = files.length;
+        walk(abs, extensions, files);
+        if (files.length === before)
+            throw new Error(`[cardHeadingScanner] scan root "${root}" matched ZERO files. ` +
+                `Refusing to report a verdict from an empty scan.`);
+        scanRootsResolved.push(root);
+    }
+    for (const file of files) {
+        const rel = relative(config.projectRoot, file);
+        let src;
+        try {
+            src = stripComments(readFileSync(file, 'utf8'));
+        }
+        catch {
+            unknownFiles.push(rel);
+            continue;
+        }
+        if (!/<h[1-6][\s/>]/.test(src))
+            continue;
+        const tags = jsxTags(src);
+        const stack = [];
+        let lostPlace = false;
+        for (const t of tags) {
+            if (t.kind === 'self')
+                continue;
+            if (t.kind === 'close') {
+                // A close with nothing to close, or closing something else, means the
+                // stack no longer describes the tree. Ancestry answers become fiction
+                // from here, so stop and report UNKNOWN rather than guess.
+                const top = stack[stack.length - 1];
+                if (!top || top.tag !== t.tag) {
+                    lostPlace = true;
+                    break;
+                }
+                stack.pop();
+                continue;
+            }
+            if (headings.has(t.tag)) {
+                const surface = stack
+                    .slice()
+                    .reverse()
+                    .map((a) => elementDeclaresCardChrome(a, chromeTags))
+                    .find((hit) => Boolean(hit));
+                if (surface) {
+                    const classes = classText(t.attrs);
+                    findings.push({
+                        file: rel,
+                        tag: t.tag,
+                        line: src.slice(0, t.index).split('\n').length,
+                        enclosingSurface: surface,
+                        hasGradient: gradientClasses.some((g) => new RegExp(`(?:^|\\s)${g}(?:$|\\s)`).test(classes)),
+                        widthDependentClasses: widthDependent(classes),
+                    });
+                }
+            }
+            stack.push({ tag: t.tag, attrs: t.attrs });
+        }
+        if (lostPlace) {
+            unknownFiles.push(rel);
+            // Drop this file's findings — an ancestry answer from a broken stack is
+            // worse than no answer, because it looks like a measurement.
+            for (let i = findings.length - 1; i >= 0; i--)
+                if (findings[i].file === rel)
+                    findings.splice(i, 1);
+        }
+    }
+    const missing = findings.filter((f) => !f.hasGradient);
+    const risky = missing.filter((f) => f.widthDependentClasses.length > 0);
+    const summary = `scanned ${files.length} files across ${scanRootsResolved.length} root(s) [${scanRootsResolved.join(', ')}]; ` +
+        `${findings.length} card heading(s), ${findings.length - missing.length} already gradient, ` +
+        `${missing.length} without — of which ${risky.length} carry a width-dependent class and need a ` +
+        `decision rather than a codemod; ${unknownFiles.length} UNKNOWN file(s) — an UNKNOWN is not a clean file.`;
+    return { findings, filesScanned: files.length, scanRootsResolved, unknownFiles, summary };
+}

package/dist/scanner/cardSurfaceScanner.d.ts

@@ -125,7 +125,7 @@ export interface CardSurfaceScannerConfig {
      * no way to turn it off. On those versions a nested card is ALWAYS a double
      * frame, so every nesting slot is a finding.
      *
-     * FALSE from 1.1.0, where chrome is opt-in. A nested card then becomes the
+     * FALSE from 2.0.0, where chrome is opt-in. A nested card then becomes the
      * CORRECT shape — it is the only surface — and the defect narrows to a slot
      * that opts back INTO chrome (`itemChrome`, or `chrome` on the item or the
      * CanvasCard) AND still nests a card.

package/dist/scanner/index.d.ts

@@ -1,3 +1,5 @@
 export { scanCardSurfaces, stripComments, openingTags, elementDeclaresCardChrome, findNestedChrome, parseConfidence, slotOptsIntoChrome, } from './cardSurfaceScanner.js';
 export type { CardSurfaceScannerConfig, CardSurfaceScanResult, CardSurfaceFinding, CardSurfaceIdiom, } from './cardSurfaceScanner.js';
+export { scanCardHeadings, jsxTags } from './cardHeadingScanner.js';
+export type { CardHeadingScannerConfig, CardHeadingScanResult, CardHeadingFinding, } from './cardHeadingScanner.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/scanner/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scanner/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scanner/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACpE,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC"}

package/dist/scanner/index.js

@@ -1 +1,2 @@
 export { scanCardSurfaces, stripComments, openingTags, elementDeclaresCardChrome, findNestedChrome, parseConfidence, slotOptsIntoChrome, } from './cardSurfaceScanner.js';
+export { scanCardHeadings, jsxTags } from './cardHeadingScanner.js';

package/dist/types.d.ts

@@ -161,9 +161,9 @@ export interface PageGridLayoutProps extends UsePageGridLayoutOptions {
     /**
      * Paint every grid item as a card unless the item says otherwise.
      *
-     * DEFAULT FALSE. This is the app-level migration lever for the 1.1.0 chrome
+     * DEFAULT FALSE. This is the app-level migration lever for the 2.0.0 chrome
      * inversion: an app that has not yet migrated its bare slots passes
-     * `itemChrome` and gets the pre-1.1.0 look back exactly, then flips slot by
+     * `itemChrome` and gets the pre-2.0.0 look back exactly, then flips slot by
      * slot with `GridLayoutItem.chrome`. Per-item always wins.
      */
     itemChrome?: boolean;

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,CA2sBpD"}
+{"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"}

package/dist/usePageGridLayout.js

@@ -330,8 +330,32 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             const baseByKey = new Map(baseItems.map((item) => [item.i, item]));
             result[bp] = (layouts[bp] ?? []).map((item) => {
                 const baseItem = baseByKey.get(item.i);
+                /**
+                 * Carry `chrome` back onto EVERY item, autoHeight or not.
+                 *
+                 * react-grid-layout hands `onLayoutChange` its own item objects, which
+                 * carry only the fields it models (`i/x/y/w/h/minW/minH/…`). Every
+                 * custom field is gone. The pre-existing `autoHeight`/`hUserSet`
+                 * restore below is the same mechanism — it just lived inside the
+                 * `autoHeight` branch, so it only ever protected autoHeight items.
+                 *
+                 * `chrome` cannot live in that branch. It is meaningful on items that
+                 * are NOT autoHeight, and losing it is not a cosmetic regression that
+                 * heals on reload: `rawLayouts` prefers a saved item over the authored
+                 * default for every key it already has, so the first drag on a page
+                 * writes a chrome-less layout to user_preferences and the slot falls
+                 * back to the app's `itemChrome` permanently, for that user only. A
+                 * marketing page deliberately set frameless would silently re-frame
+                 * itself the first time someone nudged a card, and nothing would ever
+                 * put it back.
+                 *
+                 * Three-valued on purpose: `undefined` must stay ABSENT so
+                 * `layoutItem.chrome ?? itemChrome` still falls through to the app
+                 * default. Only an explicit true/false is restored.
+                 */
+                const withChrome = (next) => baseItem?.chrome === undefined ? next : { ...next, chrome: baseItem.chrome };
                 if (!baseItem?.autoHeight)
-                    return item;
+                    return withChrome(item);
                 const measuredRows = measured[item.i];
                 // MUST mirror `activeLayouts` in PageGridLayout.tsx exactly, including
                 // its `hUserSet` test. This predicts what the grid was RENDERED with;
@@ -350,25 +374,25 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
                     // for the same reason `autoHeight` is: react-grid-layout does not
                     // round-trip custom item props, so anything not restored here is
                     // silently dropped on the next commit.
-                    return {
+                    return withChrome({
                         ...item,
                         autoHeight: true,
                         h: baseItem.h,
                         minH: baseItem.minH,
                         ...(baseItem.hUserSet ? { hUserSet: true } : {}),
-                    };
+                    });
                 }
                 // A deliberate resize (bigger or smaller than the base) — keep it,
                 // still floored by the measured content height. This is the only
                 // moment in the system where a height is known to be a CHOICE rather
                 // than an authored seed, so it is where that fact gets recorded.
-                return {
+                return withChrome({
                     ...item,
                     autoHeight: true,
                     hUserSet: true,
                     h: measuredRows === undefined ? item.h : Math.max(item.h, measuredRows),
                     minH: measuredRows ?? baseItem.minH,
-                };
+                });
             });
         }
         return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/page-builder",
-  "version": "1.1.0",
+  "version": "2.1.0-next.0",
   "description": "Shared BSuite responsive page-builder grid and layout persistence primitives",
   "type": "module",
   "license": "UNLICENSED",