@bsuite/page-builder 0.7.0 → 0.9.0

package/dist/CanvasCard.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+export interface CanvasCardProps {
+    /** Stable widget key used by PageGridLayout for layout persistence. Required. */
+    cardKey: string;
+    /** Default grid width in columns (12-col grid). Defaults to 12. */
+    w?: 2 | 3 | 4 | 6 | 8 | 12;
+    /** Minimum width in columns when the user resizes. Defaults to 4. */
+    minW?: 2 | 3 | 4 | 6 | 8 | 12;
+    /** Default grid height in 32px row units (seed before first measurement). Defaults to 6. */
+    h?: number;
+    /** Minimum height in row units when the user resizes. Defaults to 2. */
+    minH?: number;
+    /**
+     * When true, this card's height tracks its measured content height instead
+     * of a fixed manual size. `h` is only the seed row count used before the
+     * first ResizeObserver measurement lands. Threaded through to the underlying
+     * {@link GridLayoutItem.autoHeight} by `DraggableCardPage`.
+     *
+     * Defaults to TRUE. Cards grow to fit their content so forms and sections
+     * never render clipped.
+     *
+     * `autoHeight={false}` is RESERVED FOR VIRTUALIZED / WINDOWED LISTS ONLY
+     * (operator card-surfaces doctrine, 2026-07-23): a card whose body renders a
+     * windowed list that owns its own internal scroll and must NOT balloon to
+     * the full row count. An ordinary data table must NOT opt out — the doctrine
+     * is expand-by-default so every row is visible without an internal
+     * scrollbar. A blanket opt-out across ~120 crm7 pages was the 192px clip bug
+     * and was swept. Do not reintroduce it on a plain card or table.
+     */
+    autoHeight?: boolean;
+    /** Card body — typically a single card or page-header element. */
+    children: ReactNode;
+}
+/**
+ * CanvasCard — marker component consumed by `DraggableCardPage`.
+ *
+ * It renders `null` by design: `DraggableCardPage` reads its props off the JSX
+ * tree rather than rendering it, so accidental flat usage outside a
+ * `DraggableCardPage` is harmless rather than broken.
+ *
+ * Kept in its own module so a consumer can import the marker without pulling
+ * in `DraggableCardPage`'s transitive dependency on `react-grid-layout`. The
+ * `displayName` check inside `DraggableCardPage` compares against the literal
+ * string `'CanvasCard'`, so it keeps working across module boundaries, bundler
+ * chunk splits and duplicated package instances — an `instanceof`/identity
+ * check would not.
+ */
+export declare function CanvasCard(_props: CanvasCardProps): null;
+export declare namespace CanvasCard {
+    var displayName: string;
+}
+//# sourceMappingURL=CanvasCard.d.ts.map

package/dist/CanvasCard.d.ts.map

@@ -0,0 +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,mEAAmE;IACnE,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"}

package/dist/CanvasCard.js

@@ -0,0 +1,18 @@
+/**
+ * CanvasCard — marker component consumed by `DraggableCardPage`.
+ *
+ * It renders `null` by design: `DraggableCardPage` reads its props off the JSX
+ * tree rather than rendering it, so accidental flat usage outside a
+ * `DraggableCardPage` is harmless rather than broken.
+ *
+ * Kept in its own module so a consumer can import the marker without pulling
+ * in `DraggableCardPage`'s transitive dependency on `react-grid-layout`. The
+ * `displayName` check inside `DraggableCardPage` compares against the literal
+ * string `'CanvasCard'`, so it keeps working across module boundaries, bundler
+ * chunk splits and duplicated package instances — an `instanceof`/identity
+ * check would not.
+ */
+export function CanvasCard(_props) {
+    return null;
+}
+CanvasCard.displayName = 'CanvasCard';

package/dist/DraggableCardPage.d.ts

@@ -0,0 +1,118 @@
+/**
+ * DraggableCardPage — declarative wrapper around `PageGridLayout` that gives
+ * each child card its own draggable, independently-resizable widget slot.
+ *
+ * Why this exists
+ * ---------------
+ * The default way to reach `PageGridLayout` is
+ * `widgets={{ content: <Card/><Card/>… }}`, which packs an entire page into
+ * ONE widget. The canvas editor then drags the whole page as a single block
+ * instead of letting the user rearrange individual cards, and the page's
+ * height is capped at that one grid item's pixel height, so long forms render
+ * truncated. That is the operator's most-repeated complaint about this estate
+ * ("cards move as one block"), and it is a property of how the page calls the
+ * grid, not of the grid itself.
+ *
+ * Why it lives HERE rather than in an app
+ * ---------------------------------------
+ * It previously existed as three hand-copied forms (crm7, braden, throughput)
+ * and was ABSENT from two apps (BSU, conduit). The absence had a cost beyond
+ * duplication: BSU's exclusion ledger recorded that its dynamic card lists
+ * "cannot be split into static widget keys without a dynamic-widget
+ * registration mechanism", which is FALSE — `buildCanvasCardLayout` derives
+ * the widget dict from the children at render time, so a `.map()` over a
+ * runtime-variable list already produces N independent grid items. crm7 ships
+ * exactly that against a Postgres-backed 0..N array. The objection was an
+ * artifact of the primitive not being present, not a real constraint.
+ * Tracked as crm7#412 / bsuite#1995.
+ *
+ * Usage
+ * -----
+ *   <DraggableCardPage pageKey="/people/:id" layoutVersion={3}>
+ *     <CanvasCard cardKey="header" h={4}>
+ *       <PageHeader heading="Person" />
+ *     </CanvasCard>
+ *     <CanvasCard cardKey="personalInfo" h={12}>
+ *       <Card>…</Card>
+ *     </CanvasCard>
+ *     {isTraining && (
+ *       <CanvasCard cardKey="trainingContract" h={16}>
+ *         <Card>…</Card>
+ *       </CanvasCard>
+ *     )}
+ *   </DraggableCardPage>
+ *
+ * Heights are 32px row units. Falsy children are skipped, so conditional cards
+ * collapse cleanly without leaving empty slots. Fragments are flattened.
+ *
+ * What this component deliberately does NOT do
+ * --------------------------------------------
+ * - **Permissions.** Gating is an app concern with an app-specific permission
+ *   vocabulary. Wrap this component in the app's own gate.
+ * - **`compactType`.** It is NOT accepted, on purpose. `usePageGridLayout`
+ *   selects `verticalCompactor` unconditionally for BOTH view and edit mode,
+ *   and that is load-bearing: the previous edit-mode config
+ *   (`preventCollision: true` with `compactType: null`) made react-grid-layout
+ *   full-revert any gesture landing on an occupied cell, and `onDragStop` only
+ *   emits when the layout changed — so a reverted gesture emitted nothing and
+ *   NOTHING COULD EVER SAVE (bsuite#1588). Accepting a `compactType` prop here
+ *   would re-open that hole. crm7's local wrapper passed `compactType ?? null`
+ *   through a cast to a component that does not read it; the prop was dead,
+ *   and dead is the correct state for it.
+ */
+import { type ComponentType, type ReactNode } from 'react';
+import { CanvasCard, type CanvasCardProps } from './CanvasCard.js';
+import type { PageGridLayoutProps } from './types.js';
+export { CanvasCard };
+export type { CanvasCardProps };
+export type DraggableCardPageProps = Omit<PageGridLayoutProps, 'widgets' | 'defaultLayouts'> & {
+    /**
+     * App-wide layout epoch, added to this page's `layoutVersion` before it
+     * reaches `PageGridLayout`. Defaults to 0.
+     *
+     * This is the lever for "a DraggableCardPage-level default changed for EVERY
+     * page in this app" — bump it once instead of hand-bumping `layoutVersion`
+     * at hundreds of call sites, which is guaranteed to miss some. Per-page
+     * `layoutVersion` bumps keep working on top of it.
+     *
+     * It is deliberately a PROP rather than a package constant, because each app
+     * has its own history of saved layouts: crm7 is at 101 (E5a autoHeight flip,
+     * then the 2026-07-23 card-surfaces sweep), braden and throughput at 100
+     * (the D-74 sweep), and a fresh adopter starts at 0. Baking a single number
+     * into the package would silently reset or fail to reset saved layouts
+     * depending on which app imported it.
+     *
+     * Distinct from the package-level `PACKAGE_LAYOUT_EPOCH`, which is a
+     * one-time reset applied by `usePageGridLayout` to every consumer at once
+     * when a package behaviour change poisons stored layouts suite-wide.
+     */
+    layoutEpoch?: number;
+    /**
+     * The grid component to render. Defaults to this package's `PageGridLayout`.
+     *
+     * Apps that wrap `PageGridLayout` in a local adapter (to inject permissions,
+     * a preference adapter, tenant scoping or entity-widget factories) pass that
+     * adapter here, so they get the shared card algorithm without giving up
+     * their adapter. An app with no adapter passes nothing.
+     */
+    gridComponent?: ComponentType<PageGridLayoutProps>;
+    /**
+     * Called with the display names of children that occupied no grid slot and
+     * were discarded. Defaults to a development-only `console.error`.
+     *
+     * A dropped child is a defect, not a style note: if it was a dialog, its
+     * trigger appears to do nothing — the button renders, the handler runs, and
+     * the element it toggles was never mounted.
+     */
+    onDroppedChildren?: (dropped: string[], pageKey: string) => void;
+    /**
+     * CanvasCard children. Falsy entries are ignored. Fragments are flattened so
+     * a conditional multi-card branch still registers each CanvasCard.
+     */
+    children: ReactNode;
+};
+export declare function DraggableCardPage({ layoutEpoch, gridComponent, onDroppedChildren, children, ...pageProps }: DraggableCardPageProps): import("react").JSX.Element;
+export declare namespace DraggableCardPage {
+    var displayName: string;
+}
+//# sourceMappingURL=DraggableCardPage.d.ts.map

package/dist/DraggableCardPage.d.ts.map

@@ -0,0 +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;;;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"}

package/dist/DraggableCardPage.js

@@ -0,0 +1,110 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * DraggableCardPage — declarative wrapper around `PageGridLayout` that gives
+ * each child card its own draggable, independently-resizable widget slot.
+ *
+ * Why this exists
+ * ---------------
+ * The default way to reach `PageGridLayout` is
+ * `widgets={{ content: <Card/><Card/>… }}`, which packs an entire page into
+ * ONE widget. The canvas editor then drags the whole page as a single block
+ * instead of letting the user rearrange individual cards, and the page's
+ * height is capped at that one grid item's pixel height, so long forms render
+ * truncated. That is the operator's most-repeated complaint about this estate
+ * ("cards move as one block"), and it is a property of how the page calls the
+ * grid, not of the grid itself.
+ *
+ * Why it lives HERE rather than in an app
+ * ---------------------------------------
+ * It previously existed as three hand-copied forms (crm7, braden, throughput)
+ * and was ABSENT from two apps (BSU, conduit). The absence had a cost beyond
+ * duplication: BSU's exclusion ledger recorded that its dynamic card lists
+ * "cannot be split into static widget keys without a dynamic-widget
+ * registration mechanism", which is FALSE — `buildCanvasCardLayout` derives
+ * the widget dict from the children at render time, so a `.map()` over a
+ * runtime-variable list already produces N independent grid items. crm7 ships
+ * exactly that against a Postgres-backed 0..N array. The objection was an
+ * artifact of the primitive not being present, not a real constraint.
+ * Tracked as crm7#412 / bsuite#1995.
+ *
+ * Usage
+ * -----
+ *   <DraggableCardPage pageKey="/people/:id" layoutVersion={3}>
+ *     <CanvasCard cardKey="header" h={4}>
+ *       <PageHeader heading="Person" />
+ *     </CanvasCard>
+ *     <CanvasCard cardKey="personalInfo" h={12}>
+ *       <Card>…</Card>
+ *     </CanvasCard>
+ *     {isTraining && (
+ *       <CanvasCard cardKey="trainingContract" h={16}>
+ *         <Card>…</Card>
+ *       </CanvasCard>
+ *     )}
+ *   </DraggableCardPage>
+ *
+ * Heights are 32px row units. Falsy children are skipped, so conditional cards
+ * collapse cleanly without leaving empty slots. Fragments are flattened.
+ *
+ * What this component deliberately does NOT do
+ * --------------------------------------------
+ * - **Permissions.** Gating is an app concern with an app-specific permission
+ *   vocabulary. Wrap this component in the app's own gate.
+ * - **`compactType`.** It is NOT accepted, on purpose. `usePageGridLayout`
+ *   selects `verticalCompactor` unconditionally for BOTH view and edit mode,
+ *   and that is load-bearing: the previous edit-mode config
+ *   (`preventCollision: true` with `compactType: null`) made react-grid-layout
+ *   full-revert any gesture landing on an occupied cell, and `onDragStop` only
+ *   emits when the layout changed — so a reverted gesture emitted nothing and
+ *   NOTHING COULD EVER SAVE (bsuite#1588). Accepting a `compactType` prop here
+ *   would re-open that hole. crm7's local wrapper passed `compactType ?? null`
+ *   through a cast to a component that does not read it; the prop was dead,
+ *   and dead is the correct state for it.
+ */
+import { useMemo } from 'react';
+import { PageGridLayout as DefaultPageGridLayout } from './PageGridLayout.js';
+import { buildCanvasCardLayout } from './canvasCardLayout.js';
+import { CanvasCard } from './CanvasCard.js';
+// Re-exported so a consumer can import both from one module, matching the
+// long-standing crm7 import shape used by ~284 call sites.
+export { CanvasCard };
+/**
+ * `process.env.NODE_ENV` rather than `import.meta.env`: every bundler in the
+ * estate (Vite, Next, Rollup) statically replaces it, and the `typeof` guard
+ * keeps the expression safe in a raw browser ESM context where `process` does
+ * not exist. This package must not assume a Vite consumer.
+ */
+function isDevelopment() {
+    return (typeof process !== 'undefined' &&
+        process.env?.NODE_ENV !== 'production');
+}
+function defaultOnDroppedChildren(dropped, pageKey) {
+    if (!isDevelopment())
+        return;
+    // console.error, not warn: React uses error for "you have written something
+    // that will not work", and this is that.
+    //
+    // Deliberately NOT a thrown error. Hundreds of pages use this component and
+    // a throw would turn a missing dialog into a blank page for a shape that has
+    // been shipping for months — trading a partial page for no page at all is
+    // not an improvement for the user in front of it.
+    console.error(`[DraggableCardPage] ${dropped.length} child(ren) of "${pageKey}" were DISCARDED and will not render: ${dropped.join(', ')}. ` +
+        `Only <CanvasCard> children (optionally inside a Fragment) occupy a grid slot — everything else is dropped. ` +
+        `If this is a dialog or a modal, its trigger will appear to do nothing: the button renders, the handler runs, and the element it toggles was never mounted. ` +
+        `Wrap it in <CanvasCard cardKey="…"> or move it outside <DraggableCardPage>.`);
+}
+export function DraggableCardPage({ layoutEpoch = 0, gridComponent, onDroppedChildren, children, ...pageProps }) {
+    const { widgets, layouts, dropped } = useMemo(() => buildCanvasCardLayout(children), [children]);
+    if (dropped.length > 0) {
+        (onDroppedChildren ?? defaultOnDroppedChildren)(dropped, pageProps.pageKey);
+    }
+    // Ensure a sensible default 12-column grid when the consumer does not
+    // override. Without this, PageGridLayout's fallback collapses to cols=1 at
+    // every breakpoint and the page renders as a single vertical column with no
+    // horizontal canvas area — the user-reported "drag cards into these white
+    // 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 }));
+}
+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, 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, 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":"AACA,OAAO,KAA6E,MAAM,OAAO,CAAC;AAGlG,OAAO,kCAAkC,CAAC;AAC1C,OAAO,gCAAgC,CAAC;AAMxC,OAAO,KAAK,EAAe,mBAAmB,EAA4B,MAAM,YAAY,CAAC;AAmR7F,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,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,+BAA6E,EAC7E,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,EAAE,mBAAmB,qBAowBrB"}
+{"version":3,"file":"PageGridLayout.d.ts","sourceRoot":"","sources":["../src/PageGridLayout.tsx"],"names":[],"mappings":"AACA,OAAO,KAQN,MAAM,OAAO,CAAC;AAGf,OAAO,kCAAkC,CAAC;AAC1C,OAAO,gCAAgC,CAAC;AAMxC,OAAO,KAAK,EAAe,mBAAmB,EAA4B,MAAM,YAAY,CAAC;AA8U7F,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,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,+BAA6E,EAC7E,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,EAAE,mBAAmB,qBA6xBrB"}

package/dist/PageGridLayout.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ArrowDown, ArrowUp, ChevronDown, ChevronUp, Eye, EyeOff, Layers, LayoutGrid, Lock, Plus, RotateCcw, Save, Settings2, Unlock } from 'lucide-react';
-import React, { startTransition, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { startTransition, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Responsive } from 'react-grid-layout';
 import { gridBounds, minMaxSize, minSize } from 'react-grid-layout/core';
 import 'react-grid-layout/css/styles.css';
@@ -97,6 +97,71 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
     const measureRef = useRef(null);
     const lastReportedRowsRef = useRef(null);
     const measureRafRef = useRef(null);
+    /**
+     * Latest measured content height, updated on EVERY ResizeObserver entry.
+     *
+     * D-76 root cause ("cards render half cut off on page open"). The previous
+     * implementation captured `contentPx` in the rAF closure and then bailed
+     * out of any further entry that arrived before that frame ran:
+     *
+     *     if (measureRafRef.current !== null) return;   // <- measurement lost
+     *
+     * That is first-writer-wins inside a frame, and the first writer is
+     * routinely the WRONG one: a card mounts empty or skeletonised, the
+     * observer fires at (say) 90px and schedules the frame, the query resolves
+     * and the observer fires again at 760px — and that second entry returned
+     * early, discarding the real height. The frame then converged the card to
+     * ~3 rows. Because `computeAutoHeightRows` is a pure function of the height
+     * it is given, nothing re-triggered: the card stayed at the empty-state
+     * height with its content clipped by the `overflow-hidden` autoHeight
+     * wrapper until something else happened to resize it.
+     *
+     * Storing the height in a ref and READING IT INSIDE the frame makes it
+     * last-writer-wins, which is the only correct policy for "how tall is this
+     * content right now".
+     */
+    const latestContentPxRef = useRef(null);
+    const reportRows = useCallback((contentPx) => {
+        if (!onAutoHeightChange)
+            return;
+        const rows = computeAutoHeightRows({
+            contentPx,
+            cardChromePx: DEFAULT_CARD_CHROME_PX,
+            rowHeightPx: DEFAULT_ROW_HEIGHT,
+            marginYPx: DEFAULT_MARGIN[1],
+        });
+        if (rows === lastReportedRowsRef.current)
+            return;
+        lastReportedRowsRef.current = rows;
+        onAutoHeightChange(id, rows);
+    }, [id, onAutoHeightChange]);
+    /**
+     * First measurement BEFORE paint (second half of D-76).
+     *
+     * A ResizeObserver's initial observation is delivered asynchronously, and
+     * the rAF hop below adds another frame. Until it lands the card renders at
+     * its seed `h` — 6 rows / 192px for a `DraggableCardPage` card — with
+     * `overflow-hidden`, so the first painted frame of a taller card is
+     * literally cut in half. That is what the operator sees "on page open",
+     * every open, on every surface with content taller than its seed.
+     *
+     * Measuring in a layout effect and reporting synchronously puts the correct
+     * row count into state within the same commit, so the browser never paints
+     * the clipped frame. React batches these updates across all GridItems
+     * mounting together, and `applyAutoHeightRows` is a functional update, so N
+     * cards settling at once cost one re-render and cannot clobber each other.
+     */
+    useLayoutEffect(() => {
+        if (!autoHeight || !onAutoHeightChange)
+            return;
+        const el = measureRef.current;
+        if (!el)
+            return;
+        const contentPx = el.getBoundingClientRect().height;
+        latestContentPxRef.current = contentPx;
+        if (contentPx > 0)
+            reportRows(contentPx);
+    }, [autoHeight, onAutoHeightChange, reportRows]);
     useEffect(() => {
         if (!autoHeight || !onAutoHeightChange)
             return;
@@ -107,7 +172,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
             const entry = entries[0];
             if (!entry)
                 return;
-            const contentPx = entry.contentRect.height;
+            latestContentPxRef.current = entry.contentRect.height;
             if (measureRafRef.current !== null)
                 return;
             const schedule = typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'function'
@@ -115,16 +180,10 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
                 : (cb) => setTimeout(cb, 0);
             measureRafRef.current = schedule(() => {
                 measureRafRef.current = null;
-                const rows = computeAutoHeightRows({
-                    contentPx,
-                    cardChromePx: DEFAULT_CARD_CHROME_PX,
-                    rowHeightPx: DEFAULT_ROW_HEIGHT,
-                    marginYPx: DEFAULT_MARGIN[1],
-                });
-                if (rows !== lastReportedRowsRef.current) {
-                    lastReportedRowsRef.current = rows;
-                    onAutoHeightChange(id, rows);
-                }
+                const contentPx = latestContentPxRef.current;
+                if (contentPx === null)
+                    return;
+                reportRows(contentPx);
             });
         });
         ro.observe(el);
@@ -137,7 +196,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
             }
             measureRafRef.current = null;
         };
-    }, [autoHeight, id, onAutoHeightChange]);
+    }, [autoHeight, onAutoHeightChange, reportRows]);
     // DnD root-cause fix (2026-05-07): react-draggable@4 (used internally by
     // react-grid-layout@2) checks the drag handle via
     // `matchesSelectorAndParentsTo(target, handle, baseNode)` — it walks UP
@@ -163,8 +222,8 @@ 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, 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, handleCompact, handleReset, addWidget, moveWidget, setWidgetLocked, applyAutoHeightRows, autoHeightRows, resetConfirmOpen, setResetConfirmOpen, containerRef, containerWidth, } = usePageGridLayout({
+isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, defaultAutoHeight, 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({
         pageKey,
         defaultLayouts,
         defaultCols,
@@ -172,6 +231,7 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, addEntityW
         canEditPage,
         editorEventNames,
         preferenceAdapter,
+        defaultAutoHeight,
     });
     // Auto-height dispatcher (blueprint amendment A1, hardened per quality
     // review 2026-07-14). `GridItem`'s ResizeObserver calls this per-widget
@@ -309,9 +369,28 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, addEntityW
                 // Until the first measurement lands, `autoHeightRows` has no entry and
                 // the item's seed `h` renders as-is.
                 .map((item) => {
-                if (!item.autoHeight)
-                    return item;
-                // HEAL a persisted `isResizable: false`.
+                // HEAL a persisted `isResizable: false` on ANY item, not just an
+                // autoHeight one (D-75: "individual cards can no longer be resized").
+                //
+                // The 0.6.0 heal was scoped to `item.autoHeight`, which left the
+                // whole non-autoHeight population — every card that opted out, and
+                // every layout persisted before `autoHeight` existed as a concept —
+                // permanently unresizable with no way back: the flag is re-persisted
+                // on each load, so clearing it by hand does not survive a refresh.
+                //
+                // The one legitimate source of a per-item `isResizable: false` is the
+                // Layers "lock" control, which writes it together with `static: true`
+                // and `isDraggable: false`. Requiring that full signature separates a
+                // deliberate lock (kept) from the 0.5.2 leak (dropped), so the heal
+                // can be widened without silently unlocking anything a user locked.
+                const lockedDeliberately = item.static === true || item.isDraggable === false;
+                const needsResizeHeal = item.isResizable === false && !lockedDeliberately;
+                if (!item.autoHeight) {
+                    if (!needsResizeHeal)
+                        return item;
+                    const { isResizable: _dropped, ...unlocked } = item;
+                    return unlocked;
+                }
                 //
                 // 0.5.2 set this at the render layer, and it leaked out through
                 // `onLayoutChange` into the SAVED layout. Removing the override in
@@ -565,7 +644,11 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, addEntityW
                                         }) })] })), layerItems.length > 0 && (_jsxs("div", { className: "basis-full rounded-md border border-border bg-background/80 p-2", children: [_jsxs("div", { className: "mb-2 flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-muted-foreground", children: [_jsx(Layers, { className: "h-3.5 w-3.5" }), "Layers"] }), _jsx("div", { className: "flex flex-col gap-1", children: layerItems.map((layer) => (_jsxs("div", { className: "flex items-center gap-1 rounded border border-border bg-card px-2 py-1", children: [_jsx("input", { type: "text", value: layer.label, onChange: (event) => handleLayerRename(layer.id, event.target.value), className: "min-w-0 flex-1 bg-transparent text-xs text-foreground outline-none", "aria-label": `Rename ${layer.label}` }), _jsx("button", { type: "button", onClick: () => moveWidget(layer.id, 'up'), disabled: !layer.canMoveUp, "aria-label": `Move ${layer.label} up`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40", children: _jsx(ArrowUp, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => moveWidget(layer.id, 'down'), disabled: !layer.canMoveDown, "aria-label": `Move ${layer.label} down`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40", children: _jsx(ArrowDown, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => setWidgetLocked(layer.id, !layer.locked), "aria-label": `${layer.locked ? 'Unlock' : 'Lock'} ${layer.label}`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", children: layer.locked ? _jsx(Lock, { className: "h-3.5 w-3.5" }) : _jsx(Unlock, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => hideLayer(layer.id), "aria-label": `Hide ${layer.label}`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", children: _jsx(EyeOff, { className: "h-3.5 w-3.5" }) })] }, layer.id))) })] })), _jsxs("button", { type: "button", onClick: handleCompact, className: cn('ml-auto inline-flex items-center rounded-md border border-border px-2 py-1 text-sm transition-colors', 'text-muted-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(Layers, { className: "h-4 w-4 mr-1" }), "Compact Layout"] }), _jsxs("button", { type: "button", onClick: () => setResetConfirmOpen(true), className: cn('inline-flex items-center rounded-md border border-border px-2 py-1 text-sm transition-colors', 'text-muted-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(RotateCcw, { className: "h-4 w-4 mr-1" }), "Reset to Default"] })] })] })), resetConfirmOpen && (_jsx("div", { className: "fixed inset-0 z-50 flex items-center justify-center bg-overlay/50 p-4", role: "dialog", "aria-modal": "true", "aria-labelledby": "page-grid-reset-title", "aria-describedby": "page-grid-reset-description", children: _jsxs("div", { className: "max-w-md rounded-lg bg-card p-5 shadow-lg border border-border", children: [_jsx("h2", { id: "page-grid-reset-title", className: "text-lg font-semibold", children: "Reset page layout?" }), _jsx("p", { id: "page-grid-reset-description", className: "mt-2 text-sm text-muted-foreground", children: "This will discard your current layout and restore all widgets to their default positions." }), _jsxs("div", { className: "mt-4 flex justify-end gap-2", children: [_jsx("button", { type: "button", ref: resetCancelButtonRef, onClick: () => setResetConfirmOpen(false), className: cn('inline-flex items-center rounded-md border border-border px-3 py-2 text-sm transition-colors', 'bg-card text-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: "Cancel" }), _jsx("button", { type: "button", ref: resetConfirmButtonRef, onClick: () => {
                                         handleReset();
                                         setResetConfirmOpen(false);
-                                    }, className: cn('inline-flex items-center rounded-md px-3 py-2 text-sm font-medium transition-colors', 'bg-destructive text-destructive-foreground shadow hover:bg-destructive/90', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-destructive/40 focus-visible:ring-offset-1'), children: "Reset to Default" })] })] }) })), _jsx("div", { ref: containerRef, className: cn('relative z-0 overflow-visible', isEditing && 'min-h-[200px] bg-muted/30'), "data-page-grid-editing": isEditing || undefined, children: _jsx("div", { className: "relative z-0", style: { opacity: containerWidth > 0 ? 1 : 0 }, "aria-busy": containerWidth <= 0, children: _jsx(Responsive, { width: Math.max(containerWidth, 1), className: "layout page-grid-canvas", layouts: activeLayouts, breakpoints: { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }, rowHeight: DEFAULT_ROW_HEIGHT, onLayoutChange: onLayoutChange, dragConfig: {
+                                    }, className: cn('inline-flex items-center rounded-md px-3 py-2 text-sm font-medium transition-colors', 'bg-destructive text-destructive-foreground shadow hover:bg-destructive/90', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-destructive/40 focus-visible:ring-offset-1'), children: "Reset to Default" })] })] }) })), _jsx("div", { ref: containerRef, className: cn('relative z-0 overflow-visible', isEditing && 'min-h-[200px] bg-muted/30'), "data-page-grid-editing": isEditing || undefined, children: _jsx("div", { className: "relative z-0", style: { opacity: containerWidth > 0 ? 1 : 0 }, "aria-busy": containerWidth <= 0, children: _jsx(Responsive, { width: Math.max(containerWidth, 1), className: "layout page-grid-canvas", layouts: activeLayouts, breakpoints: { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }, rowHeight: DEFAULT_ROW_HEIGHT, onLayoutChange: onLayoutChange, 
+                        // Tells the hook which breakpoint a gesture belongs to, so the edit
+                        // is folded back onto `lg` instead of into a derived breakpoint
+                        // that is regenerated (and therefore discarded) on the next render.
+                        onBreakpointChange: handleBreakpointChange, dragConfig: {
                             enabled: isEditing,
                             handle: '.drag-handle',
                             bounded: false,

package/dist/buildResponsiveLayouts.d.ts

@@ -1,15 +1,72 @@
 import type { GridLayouts } from './types.js';
 export declare const RESPONSIVE_BREAKPOINTS: readonly ["lg", "md", "sm", "xs", "xxs"];
 export type ResponsiveBreakpoint = (typeof RESPONSIVE_BREAKPOINTS)[number];
+/**
+ * Breakpoints whose layout MIRRORS `lg` verbatim.
+ *
+ * D-75 root cause (operator directive 2026-08-13: "columns available to move
+ * cards into do not respect the columns slider").
+ * ---------------------------------------------------------------------------
+ * react-grid-layout picks its breakpoint from the **container** width, not the
+ * viewport — `<Responsive width={containerWidth}>` in `PageGridLayout`. Inside
+ * an app shell with a sidebar and page padding, a 1280px laptop presents a
+ * container around 950px and a 1440px desktop around 1100px. Both land BELOW
+ * the `md: 996` / `lg: 1200` thresholds, so the great majority of real desktop
+ * sessions render at `sm` or `md`, not `lg`.
+ *
+ * `sm` used to be derived by `stackToSingleColumn`, which sets `w: cols` on
+ * every item — one card per row at full width, whatever the column count. So
+ * on an ordinary laptop the columns slider changed `activeCols` while every
+ * card stayed stretched across all of them: the control provably did nothing,
+ * and the SE resize handle could not widen a card that was already at the grid
+ * bound nor narrow one whose `minW` had been clamped up to `cols`.
+ *
+ * `md` and `sm` therefore mirror `lg`: at a container width of 768px and above
+ * there is room for the arrangement the user chose, and honouring their choice
+ * is the whole point of the control. Genuine phone widths (`xs` < 768px
+ * container, `xxs` < 480px) still stack, which is what that code was for.
+ */
+export declare const MIRRORED_BREAKPOINTS: readonly ["md", "sm"];
+/**
+ * Breakpoints derived as a single full-width stack — narrow enough that a
+ * multi-column arrangement cannot be read.
+ */
+export declare const STACKED_BREAKPOINTS: readonly ["xs", "xxs"];
+/**
+ * Every breakpoint this module DERIVES from `lg`.
+ *
+ * A derived breakpoint is a render-time projection, never a stored fact. It
+ * must not reach the preference adapter: react-grid-layout echoes ALL
+ * breakpoints back through `onLayoutChange` on every gesture, so persisting
+ * them verbatim froze the derivation — a layout derived once at 12 columns was
+ * then "consumer-supplied" forever and stopped tracking `lg`. See
+ * `canonicaliseLayoutForPersist` in `usePageGridLayout.ts`.
+ */
+export declare const DERIVED_BREAKPOINTS: readonly ResponsiveBreakpoint[];
+export declare function isDerivedBreakpoint(breakpoint: string): boolean;
+/**
+ * True when a gesture at `breakpoint` can be written straight back onto `lg`.
+ *
+ * `lg`, `md` and `sm` all render the same array against the same column count,
+ * so an edit made at any of them is expressible in `lg` with no loss. `xs` and
+ * `xxs` render a full-width stack, where an edit carries only a vertical order
+ * and would flatten a multi-column desktop arrangement if applied to `lg`.
+ */
+export declare function isCanonicalisableBreakpoint(breakpoint: string): boolean;
 export interface BuildResponsiveLayoutsOptions {
     cols?: number;
 }
 /**
  * Ensure a GridLayouts object has entries for all responsive breakpoints
- * (lg, md, sm, xs, xxs). Missing smaller breakpoints (sm/xs/xxs) are derived
- * from `lg` as a single-column vertical stack so that consumer-supplied
- * lg-only layouts no longer squash on phone viewports. Missing `md` is
- * mirrored from `lg`. Consumer-supplied breakpoints are preserved verbatim.
+ * (lg, md, sm, xs, xxs).
+ *
+ * - `md` and `sm` mirror `lg` so the user's chosen column arrangement survives
+ *   every desktop and tablet container width (see {@link MIRRORED_BREAKPOINTS}).
+ * - `xs` and `xxs` are derived as a single-column stack so a phone viewport
+ *   never squashes cards into unreadable slivers.
+ * - Consumer-supplied breakpoints are preserved verbatim. Supplying one opts
+ *   that breakpoint OUT of tracking `lg`, including out of the columns slider —
+ *   prefer not to.
  */
 export declare function buildResponsiveLayouts(layouts: GridLayouts, { cols }?: BuildResponsiveLayoutsOptions): GridLayouts;
 //# sourceMappingURL=buildResponsiveLayouts.d.ts.map

package/dist/buildResponsiveLayouts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildResponsiveLayouts.d.ts","sourceRoot":"","sources":["../src/buildResponsiveLayouts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,eAAO,MAAM,sBAAsB,0CAA2C,CAAC;AAC/E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,MAAM,WAAW,6BAA6B;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkBD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,EACpB,EAAE,IAAS,EAAE,GAAE,6BAAkC,GAChD,WAAW,CAyBb"}
+{"version":3,"file":"buildResponsiveLayouts.d.ts","sourceRoot":"","sources":["../src/buildResponsiveLayouts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,eAAO,MAAM,sBAAsB,0CAA2C,CAAC;AAC/E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,uBAAwB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,mBAAmB,wBAAyB,CAAC;AAE1D;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,oBAAoB,EAG9D,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0BD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,EACpB,EAAE,IAAS,EAAE,GAAE,6BAAkC,GAChD,WAAW,CAyBb"}