@bsuite/page-builder 0.8.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/canvasCardLayout.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The CanvasCard → grid-layout algorithm, extracted from the component so it
+ * can be unit-tested and reused without rendering anything.
+ *
+ * This is the half of `DraggableCardPage` that was copied verbatim into three
+ * apps (crm7, braden, throughput) and was absent from two more (BSU, conduit).
+ * It has no app dependencies, no permission model and no adapter — those are
+ * the parts that legitimately differ per app and stay there.
+ */
+import { type ReactElement, type ReactNode } from 'react';
+import type { CanvasCardProps } from './CanvasCard.js';
+import type { GridLayouts } from './types.js';
+/** The 12-column grid every BSuite page canvas is laid out against. */
+export declare const CANVAS_GRID_COLUMNS = 12;
+export declare function isCanvasCardElement(node: ReactNode): node is ReactElement<CanvasCardProps>;
+/**
+ * Best-effort display name for a node that is about to be discarded.
+ * "Something was dropped" is not actionable across hundreds of pages; the
+ * component's own name is what makes it findable.
+ */
+export declare function describeNode(node: ReactNode): string;
+/**
+ * Depth-first flatten: CanvasCards kept, Fragments expanded, everything else
+ * dropped — and RECORDED rather than vanishing.
+ *
+ * The dropping itself is correct and deliberate: this maps children onto grid
+ * slots, and a node with no `cardKey` has no slot to occupy. What was wrong is
+ * that it happened in total silence, so a page could render with a confirm
+ * dialog missing and look completely fine — the button appears, the click
+ * handler runs, state flips, and the element it toggles was never mounted.
+ *
+ * Fragments must be expanded explicitly because `Children.forEach` is shallow:
+ * it sees one Fragment node, not the CanvasCards inside it. A Fragment-wrapped
+ * conditional branch used to drop every nested card silently (the crm7 burn-7
+ * CI class, `leave/[id]`).
+ */
+export declare function flattenCanvasCards(nodes: ReactNode): {
+    cards: ReactElement<CanvasCardProps>[];
+    dropped: string[];
+};
+export declare function clampColumns(value: number, min?: number, max?: number): number;
+export interface CanvasCardLayoutResult {
+    /** Widget dict keyed by `cardKey`, ready for `PageGridLayout.widgets`. */
+    widgets: Record<string, ReactNode>;
+    /** `lg` breakpoint layout, ready for `PageGridLayout.defaultLayouts`. */
+    layouts: GridLayouts;
+    /** Display names of children that occupied no grid slot and were discarded. */
+    dropped: string[];
+}
+/**
+ * Build the `widgets` dict and `defaultLayouts.lg` array from CanvasCard
+ * children.
+ *
+ * Cards flow left-to-right and wrap to a new row when the next card would
+ * overflow the 12-column grid. Because the dict is built FROM THE CHILDREN AT
+ * RENDER TIME, a `.map()` producing N cards is fully supported and needs no
+ * registration mechanism — each mapped card becomes its own independent grid
+ * item. (This is the fact that disproves the "dynamic card lists cannot be
+ * split into static widget keys" objection recorded in several app ledgers.)
+ */
+export declare function buildCanvasCardLayout(children: ReactNode): CanvasCardLayoutResult;
+//# sourceMappingURL=canvasCardLayout.d.ts.map

package/dist/canvasCardLayout.d.ts.map

@@ -0,0 +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,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,GAClB,sBAAsB,CA0CxB"}

package/dist/canvasCardLayout.js

@@ -0,0 +1,120 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The CanvasCard → grid-layout algorithm, extracted from the component so it
+ * can be unit-tested and reused without rendering anything.
+ *
+ * This is the half of `DraggableCardPage` that was copied verbatim into three
+ * apps (crm7, braden, throughput) and was absent from two more (BSU, conduit).
+ * It has no app dependencies, no permission model and no adapter — those are
+ * the parts that legitimately differ per app and stay there.
+ */
+import { Children, Fragment, isValidElement, } from 'react';
+/** The 12-column grid every BSuite page canvas is laid out against. */
+export const CANVAS_GRID_COLUMNS = 12;
+export function isCanvasCardElement(node) {
+    return (isValidElement(node) &&
+        node.type.displayName === 'CanvasCard');
+}
+function isFragmentElement(node) {
+    return isValidElement(node) && node.type === Fragment;
+}
+/**
+ * Best-effort display name for a node that is about to be discarded.
+ * "Something was dropped" is not actionable across hundreds of pages; the
+ * component's own name is what makes it findable.
+ */
+export function describeNode(node) {
+    if (!isValidElement(node))
+        return typeof node === 'string'
+            ? `text ${JSON.stringify(node)}`
+            : String(node);
+    const t = node.type;
+    if (typeof t === 'string')
+        return `<${t}>`;
+    return `<${t?.displayName ?? t?.name ?? 'Unknown'}>`;
+}
+/**
+ * Depth-first flatten: CanvasCards kept, Fragments expanded, everything else
+ * dropped — and RECORDED rather than vanishing.
+ *
+ * The dropping itself is correct and deliberate: this maps children onto grid
+ * slots, and a node with no `cardKey` has no slot to occupy. What was wrong is
+ * that it happened in total silence, so a page could render with a confirm
+ * dialog missing and look completely fine — the button appears, the click
+ * handler runs, state flips, and the element it toggles was never mounted.
+ *
+ * Fragments must be expanded explicitly because `Children.forEach` is shallow:
+ * it sees one Fragment node, not the CanvasCards inside it. A Fragment-wrapped
+ * conditional branch used to drop every nested card silently (the crm7 burn-7
+ * CI class, `leave/[id]`).
+ */
+export function flattenCanvasCards(nodes) {
+    const cards = [];
+    const dropped = [];
+    Children.forEach(nodes, (child) => {
+        // Falsy entries are the documented conditional shape — `{cond && <CanvasCard/>}`
+        // collapses to `false`, which is intentional and must stay silent.
+        if (child == null || child === false || child === true || child === '')
+            return;
+        if (isCanvasCardElement(child)) {
+            cards.push(child);
+            return;
+        }
+        if (isFragmentElement(child)) {
+            const inner = flattenCanvasCards(child.props.children);
+            cards.push(...inner.cards);
+            dropped.push(...inner.dropped);
+            return;
+        }
+        dropped.push(describeNode(child));
+    });
+    return { cards, dropped };
+}
+export function clampColumns(value, min = 1, max = CANVAS_GRID_COLUMNS) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Build the `widgets` dict and `defaultLayouts.lg` array from CanvasCard
+ * children.
+ *
+ * Cards flow left-to-right and wrap to a new row when the next card would
+ * overflow the 12-column grid. Because the dict is built FROM THE CHILDREN AT
+ * RENDER TIME, a `.map()` producing N cards is fully supported and needs no
+ * registration mechanism — each mapped card becomes its own independent grid
+ * item. (This is the fact that disproves the "dynamic card lists cannot be
+ * split into static widget keys" objection recorded in several app ledgers.)
+ */
+export function buildCanvasCardLayout(children) {
+    const widgets = {};
+    const lg = [];
+    let x = 0;
+    let y = 0;
+    let rowHeight = 0;
+    const { cards, dropped } = flattenCanvasCards(children);
+    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 normalizedMinW = clampColumns(minW);
+        const width = clampColumns(child.props.w ?? CANVAS_GRID_COLUMNS, normalizedMinW);
+        if (x + width > CANVAS_GRID_COLUMNS) {
+            y += rowHeight;
+            x = 0;
+            rowHeight = 0;
+        }
+        widgets[cardKey] = (_jsx("div", { className: "relative h-full group/canvas-card", children: body }));
+        lg.push({
+            i: cardKey,
+            x,
+            y,
+            w: width,
+            h,
+            minW: normalizedMinW,
+            minH,
+            ...(autoHeight ? { autoHeight: true } : {}),
+        });
+        x += width;
+        rowHeight = Math.max(rowHeight, h);
+    }
+    return { widgets, layouts: { lg }, dropped };
+}

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 export { PageGridLayout } from './PageGridLayout.js';
 export { PageEditorLauncher } from './PageEditorLauncher.js';
+export { CanvasCard } from './CanvasCard.js';
+export type { CanvasCardProps } from './CanvasCard.js';
+export { DraggableCardPage } from './DraggableCardPage.js';
+export type { DraggableCardPageProps } from './DraggableCardPage.js';
+export { buildCanvasCardLayout, 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 type { PageGridEditingEventDetail } from './usePageGridLayout.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,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"}
+{"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;AAC7C,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,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"}

package/dist/index.js

@@ -1,5 +1,8 @@
 export { PageGridLayout } from './PageGridLayout.js';
 export { PageEditorLauncher } from './PageEditorLauncher.js';
+export { CanvasCard } from './CanvasCard.js';
+export { DraggableCardPage } from './DraggableCardPage.js';
+export { buildCanvasCardLayout, flattenCanvasCards, isCanvasCardElement, describeNode, clampColumns, CANVAS_GRID_COLUMNS, } from './canvasCardLayout.js';
 export { usePageGridLayout, DEFAULT_EDITOR_EVENT_NAMES, PAGE_GRID_EDITING_EVENT, } from './usePageGridLayout.js';
 export { rescaleLayout } from './rescaleLayout.js';
 export { computeAutoHeightRows } from './autoHeight.js';

package/dist/scanner/cardSurfaceScanner.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The card-surface contract scanner — ONE implementation, shipped from the
+ * package, replacing five divergent hand-rolled copies.
+ *
+ * Why this exists
+ * ---------------
+ * crm7 wrote a card-unglue contract test. BSU, conduit, throughput and braden
+ * each PORTED it, and each silently dropped checks during the port. The
+ * divergence was not cosmetic:
+ *
+ *   - `findUngriddedMultiCard` — the check crm7's own comment calls "the actual
+ *     root cause of the operator's platform-wide complaint" — was ABSENT from
+ *     BSU, throughput and braden, and present only in a narrowed form in
+ *     conduit. In throughput and braden it was absent structurally: their glue
+ *     scan is gated on the file containing `CanvasCard` at all, so a page with
+ *     two cards and no grid primitive is invisible by construction.
+ *   - conduit's header documents THREE card idioms and its regexes detect TWO.
+ *     The third (`rounded-lg border p-4` section panels) has no detector, which
+ *     is how five known-glued conduit pages pass as an empty ledger.
+ *   - BSU's scan only walks files containing the literal string
+ *     `PageGridLayout`, so every BSU page that never adopted the grid is
+ *     structurally invisible to BSU's own gate.
+ *
+ * A gate that cannot tell "checked nothing" from "found nothing" is not a gate
+ * (D-92). This module therefore ASSERTS ITS INPUTS: it fails closed if a scan
+ * root is missing or matches zero files, and it reports how it reached its
+ * verdict rather than only the verdict.
+ *
+ * What stays per-app
+ * ------------------
+ * Scan roots, card vocabulary, class-based surface patterns, and the exclusion
+ * ledgers. Those are operational truth about a specific app. Everything else —
+ * the detection logic — lives here so it can only be fixed once.
+ *
+ * Node-only: this module touches the filesystem and is exported from
+ * `@bsuite/page-builder/scanner`, NOT from the package root, so it never
+ * reaches a browser bundle.
+ */
+export type CardSurfaceIdiom = 
+/** 2+ card-like components packed inside ONE grid slot. */
+'glued-widget'
+/** 2+ card-like components on a page that never reaches a grid primitive. */
+ | 'ungridded-multi-card'
+/** A retired single-widget primitive still present or still imported. */
+ | 'retired-primitive'
+/** autoHeight opt-out on a card that is not a virtualized list. */
+ | 'autoheight-optout'
+/** autoHeight={false} with a seed height so small the card must clip. */
+ | 'clipped-card';
+export interface CardSurfaceFinding {
+    file: string;
+    idiom: CardSurfaceIdiom;
+    detail: string;
+    /** Number of card-like components involved, where meaningful. */
+    cardCount?: number;
+}
+export interface CardSurfaceScannerConfig {
+    /** Absolute path to the repo root. */
+    projectRoot: string;
+    /**
+     * Directories to walk, repo-relative. Every one MUST exist and MUST contain
+     * at least one scannable file, or the scan fails closed.
+     */
+    scanRoots: string[];
+    /**
+     * Component names that count as a card. Apps differ materially here: crm7
+     * uses `Card`/`StatCard`/`SummaryCard`, BSU adds `ServiceCard`, conduit uses
+     * `SummaryCard`/`CounterCard`.
+     */
+    cardTags: string[];
+    /**
+     * Class-based card surfaces — a card that is a styled `div`, not a
+     * component. This is the idiom conduit documented and never implemented, and
+     * the one BSU's `glass-card` tiles use. Supply e.g.
+     * `[/glass-card/, /rounded-lg border p-4/]`.
+     */
+    classSurfaces?: RegExp[];
+    /** Identifiers that prove a file reached the grid. */
+    gridPrimitives?: string[];
+    /** Repo-relative path of a retired single-widget primitive that must not exist. */
+    retiredPrimitivePaths?: string[];
+    /** file -> reason. A glued widget listed here is allowed. */
+    gluedExclusions?: Record<string, string>;
+    /** file -> reason. An ungridded multi-card page listed here is allowed. */
+    ungriddedExclusions?: Record<string, string>;
+    /**
+     * Directories deliberately NOT scanned, each with a reason. Declaring a
+     * blind spot is required; having an undeclared one is the defect.
+     */
+    blindSpots?: Record<string, string>;
+    /**
+     * If a file matches this, an `autoHeight={false}` in it is permitted — the
+     * opt-out is reserved for genuinely virtualized/windowed lists.
+     */
+    autoHeightEscapeHatch?: RegExp;
+    /** File extensions to scan. Defaults to .tsx. */
+    extensions?: string[];
+}
+export interface CardSurfaceScanResult {
+    findings: CardSurfaceFinding[];
+    /** Files actually read. If this is 0 the scan proved nothing. */
+    filesScanned: number;
+    scanRootsResolved: string[];
+    /** Exclusion-ledger keys that no longer match any finding — stale entries. */
+    staleExclusions: string[];
+    /** Human-readable account of how the verdict was reached. */
+    summary: string;
+}
+/**
+ * Strip block comments, line comments and JSX comments before matching.
+ *
+ * Three of the five hand-rolled copies matched against raw file content, which
+ * produced two opposite errors at once: a commented-out `<Card/><Card/>`
+ * example false-POSITIVES as glue, and a file that merely MENTIONS
+ * `CanvasCard` in a TODO comment false-NEGATIVES as "already gridded" and is
+ * skipped entirely. Stripping first fixes both.
+ */
+export declare function stripComments(source: string): string;
+export declare function scanCardSurfaces(config: CardSurfaceScannerConfig): CardSurfaceScanResult;
+//# sourceMappingURL=cardSurfaceScanner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cardSurfaceScanner.d.ts","sourceRoot":"","sources":["../../src/scanner/cardSurfaceScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,MAAM,MAAM,gBAAgB;AAC1B,2DAA2D;AACzD,cAAc;AAChB,6EAA6E;GAC3E,sBAAsB;AACxB,yEAAyE;GACvE,mBAAmB;AACrB,mEAAmE;GACjE,mBAAmB;AACrB,yEAAyE;GACvE,cAAc,CAAC;AAEnB,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,8EAA8E;IAC9E,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;CACjB;AASD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKpD;AAwHD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,wBAAwB,GAC/B,qBAAqB,CAwIvB"}

package/dist/scanner/cardSurfaceScanner.js

@@ -0,0 +1,289 @@
+/**
+ * The card-surface contract scanner — ONE implementation, shipped from the
+ * package, replacing five divergent hand-rolled copies.
+ *
+ * Why this exists
+ * ---------------
+ * crm7 wrote a card-unglue contract test. BSU, conduit, throughput and braden
+ * each PORTED it, and each silently dropped checks during the port. The
+ * divergence was not cosmetic:
+ *
+ *   - `findUngriddedMultiCard` — the check crm7's own comment calls "the actual
+ *     root cause of the operator's platform-wide complaint" — was ABSENT from
+ *     BSU, throughput and braden, and present only in a narrowed form in
+ *     conduit. In throughput and braden it was absent structurally: their glue
+ *     scan is gated on the file containing `CanvasCard` at all, so a page with
+ *     two cards and no grid primitive is invisible by construction.
+ *   - conduit's header documents THREE card idioms and its regexes detect TWO.
+ *     The third (`rounded-lg border p-4` section panels) has no detector, which
+ *     is how five known-glued conduit pages pass as an empty ledger.
+ *   - BSU's scan only walks files containing the literal string
+ *     `PageGridLayout`, so every BSU page that never adopted the grid is
+ *     structurally invisible to BSU's own gate.
+ *
+ * A gate that cannot tell "checked nothing" from "found nothing" is not a gate
+ * (D-92). This module therefore ASSERTS ITS INPUTS: it fails closed if a scan
+ * root is missing or matches zero files, and it reports how it reached its
+ * verdict rather than only the verdict.
+ *
+ * What stays per-app
+ * ------------------
+ * Scan roots, card vocabulary, class-based surface patterns, and the exclusion
+ * ledgers. Those are operational truth about a specific app. Everything else —
+ * the detection logic — lives here so it can only be fixed once.
+ *
+ * Node-only: this module touches the filesystem and is exported from
+ * `@bsuite/page-builder/scanner`, NOT from the package root, so it never
+ * reaches a browser bundle.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+const DEFAULT_GRID_PRIMITIVES = [
+    'CanvasCard',
+    'DraggableCardPage',
+    'PageGridLayout',
+    'usePageGridLayout',
+];
+/**
+ * Strip block comments, line comments and JSX comments before matching.
+ *
+ * Three of the five hand-rolled copies matched against raw file content, which
+ * produced two opposite errors at once: a commented-out `<Card/><Card/>`
+ * example false-POSITIVES as glue, and a file that merely MENTIONS
+ * `CanvasCard` in a TODO comment false-NEGATIVES as "already gridded" and is
+ * skipped entirely. Stripping first fixes both.
+ */
+export function stripComments(source) {
+    return source
+        .replace(/\{\s*\/\*[\s\S]*?\*\/\s*\}/g, '') // {/* JSX comment */}
+        .replace(/\/\*[\s\S]*?\*\//g, '') // /* block */
+        .replace(/(^|[^:])\/\/[^\n]*/g, '$1'); // // line, but not http://
+}
+function tagPattern(tags) {
+    // `[\s/>]` not `[\s>]`: `<Card/>` with no space before the slash was missed
+    // by three of the five copies. The trailing alternation keeps `<Card>` and
+    // `<Card ...>` matching too.
+    return new RegExp(`<(${tags.join('|')})[\\s/>]`, 'g');
+}
+function countCardTags(source, config) {
+    let count = (source.match(tagPattern(config.cardTags)) ?? []).length;
+    for (const re of config.classSurfaces ?? []) {
+        const global = new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g');
+        count += (source.match(global) ?? []).length;
+    }
+    return count;
+}
+/**
+ * Does this source render cards from a `.map()`?
+ *
+ * The non-greedy `[\s\S]*?` form is deliberate. Three copies used
+ * `\.map\s*\([^)]*\)\s*=>` which requires a PARENTHESISED parameter, so
+ * `items.map(item => <Card/>)` — a bare param with an expression body — was
+ * missed. That gap is currently dormant across the estate but it is a landmine,
+ * not a theoretical concern.
+ */
+function hasMappedCards(source, config) {
+    const tags = config.cardTags.join('|');
+    if (new RegExp(`\\.map\\s*\\([\\s\\S]*?=>\\s*\\(?\\s*<(${tags})[\\s/>]`).test(source) ||
+        new RegExp(`\\.map\\s*\\([\\s\\S]*?\\{[\\s\\S]*?return\\s*\\(?\\s*<(${tags})[\\s/>]`).test(source))
+        return true;
+    // A mapped CLASS surface is still a mapped card.
+    //
+    // This was missed on the first pass: the tag alternation above is built from
+    // `cardTags` only, so `.map(api => <div className="glass-card">…)` produced N
+    // cards inside one grid slot and read as clean. BSU's `Government.tsx#apis`
+    // is exactly that shape, and only its hand-maintained ledger knew — which is
+    // the failure mode this whole module exists to end. `countCardTags` already
+    // counts class surfaces; the mapped check has to as well or the two disagree.
+    for (const re of config.classSurfaces ?? []) {
+        const src = re.source;
+        if (new RegExp(`\\.map\\s*\\([\\s\\S]*?=>\\s*\\(?\\s*<[^>]*?${src}`).test(source) ||
+            new RegExp(`\\.map\\s*\\([\\s\\S]*?\\{[\\s\\S]*?return\\s*\\(?\\s*<[^>]*?${src}`).test(source))
+            return true;
+    }
+    return false;
+}
+/** Extract the body of every `<CanvasCard …> … </CanvasCard>` block. */
+function extractCanvasCardBlocks(source) {
+    const blocks = [];
+    const re = /<CanvasCard[\s>][\s\S]*?<\/CanvasCard>/g;
+    let m;
+    while ((m = re.exec(source)) !== null)
+        blocks.push(m[0]);
+    return blocks;
+}
+/**
+ * Extract each value of an inline `widgets={{ key: <jsx/> }}` object literal.
+ * Brace-balanced rather than regex-terminated, because a widget body contains
+ * arbitrary nested JSX and braces.
+ */
+function extractWidgetEntries(source) {
+    const out = [];
+    const start = /widgets=\{\{/g;
+    let m;
+    while ((m = start.exec(source)) !== null) {
+        let depth = 2;
+        let i = m.index + m[0].length;
+        const objStart = i;
+        while (i < source.length && depth > 0) {
+            if (source[i] === '{')
+                depth++;
+            else if (source[i] === '}')
+                depth--;
+            i++;
+        }
+        const obj = source.slice(objStart, i - 2);
+        // Split top-level `key:` entries at depth 0.
+        let d = 0;
+        let keyStart = 0;
+        let currentKey = null;
+        let bodyStart = 0;
+        for (let j = 0; j < obj.length; j++) {
+            const c = obj[j];
+            if (c === '{' || c === '(' || c === '[')
+                d++;
+            else if (c === '}' || c === ')' || c === ']')
+                d--;
+            else if (c === ':' && d === 0 && currentKey === null) {
+                currentKey = obj.slice(keyStart, j).trim().replace(/['"]/g, '');
+                bodyStart = j + 1;
+            }
+            else if (c === ',' && d === 0 && currentKey !== null) {
+                out.push({ key: currentKey, body: obj.slice(bodyStart, j) });
+                currentKey = null;
+                keyStart = j + 1;
+            }
+        }
+        if (currentKey !== null)
+            out.push({ key: currentKey, body: obj.slice(bodyStart) });
+    }
+    return out;
+}
+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 scanCardSurfaces(config) {
+    const extensions = config.extensions ?? ['.tsx'];
+    const gridPrimitives = config.gridPrimitives ?? DEFAULT_GRID_PRIMITIVES;
+    const findings = [];
+    const files = [];
+    const scanRootsResolved = [];
+    // D-92: assert the inputs were present BEFORE reporting any verdict. A
+    // missing scan root must fail loudly, not produce a confident zero.
+    for (const root of config.scanRoots) {
+        const abs = join(config.projectRoot, root);
+        if (!existsSync(abs))
+            throw new Error(`[cardSurfaceScanner] scan root "${root}" does not exist at ${abs}. ` +
+                `A scanner that silently skips a missing root reports a false pass, which is worse than a failure.`);
+        const before = files.length;
+        walk(abs, extensions, files);
+        if (files.length === before)
+            throw new Error(`[cardSurfaceScanner] scan root "${root}" matched ZERO files with extensions ${extensions.join(', ')}. ` +
+                `Refusing to report a verdict from an empty scan.`);
+        scanRootsResolved.push(root);
+    }
+    // Retired single-widget primitives must not exist and must not be imported.
+    for (const retired of config.retiredPrimitivePaths ?? []) {
+        const abs = join(config.projectRoot, retired);
+        if (existsSync(abs))
+            findings.push({
+                file: retired,
+                idiom: 'retired-primitive',
+                detail: `${retired} still exists. It builds ONE grid item for the whole page, so every card on it ` +
+                    `moves as a single block — the exact defect this contract exists to prevent.`,
+            });
+        const base = retired.split(sep).pop()?.replace(/\.tsx?$/, '');
+        if (base) {
+            for (const file of files) {
+                const src = stripComments(readFileSync(file, 'utf8'));
+                if (new RegExp(`\\b${base}\\b`).test(src) && !file.endsWith(retired))
+                    findings.push({
+                        file: relative(config.projectRoot, file),
+                        idiom: 'retired-primitive',
+                        detail: `imports or references the retired primitive ${base}`,
+                    });
+            }
+        }
+    }
+    for (const file of files) {
+        const rel = relative(config.projectRoot, file);
+        const raw = readFileSync(file, 'utf8');
+        const src = stripComments(raw);
+        // --- glued widget: 2+ cards inside ONE grid slot -----------------------
+        const slots = [
+            ...extractCanvasCardBlocks(src).map((b, i) => ({ label: `CanvasCard#${i + 1}`, body: b })),
+            ...extractWidgetEntries(src).map((e) => ({ label: `widgets.${e.key}`, body: e.body })),
+        ];
+        for (const slot of slots) {
+            const n = countCardTags(slot.body, config);
+            const mapped = hasMappedCards(slot.body, config);
+            if (n > 1 || mapped) {
+                if (config.gluedExclusions?.[rel])
+                    continue;
+                findings.push({
+                    file: rel,
+                    idiom: 'glued-widget',
+                    cardCount: n,
+                    detail: `${slot.label} packs ${mapped ? 'a .map() of cards' : `${n} card-like components`} into one grid slot. ` +
+                        `Dragging any one of them moves them all.`,
+                });
+            }
+        }
+        // --- ungridded multi-card: the check three of five ports DROPPED -------
+        // Gate on the COMMENT-STRIPPED source so a TODO mentioning CanvasCard does
+        // not mask a page that never actually reaches the grid.
+        const usesGrid = gridPrimitives.some((p) => new RegExp(`\\b${p}\\b`).test(src));
+        if (!usesGrid) {
+            const n = countCardTags(src, config);
+            if (n > 1 && !config.ungriddedExclusions?.[rel]) {
+                findings.push({
+                    file: rel,
+                    idiom: 'ungridded-multi-card',
+                    cardCount: n,
+                    detail: `renders ${n} card-like surfaces and never reaches a grid primitive, so none of them is draggable at all. ` +
+                        `This is the idiom crm7's scanner calls "the actual root cause of the operator's platform-wide complaint".`,
+                });
+            }
+        }
+        // --- autoHeight opt-out + clip invariant -------------------------------
+        const optOut = /autoHeight\s*[:=]\s*\{?\s*false/g;
+        if (optOut.test(src) && !(config.autoHeightEscapeHatch?.test(src) ?? false)) {
+            findings.push({
+                file: rel,
+                idiom: 'autoheight-optout',
+                detail: `opts out of autoHeight. That is reserved for genuinely virtualized/windowed lists that own their own scroll; ` +
+                    `an ordinary table must expand so every row is visible.`,
+            });
+        }
+        // A card that opts out AND seeds h<=2 (64px) cannot show its content.
+        if (/autoHeight\s*[:=]\s*\{?\s*false/.test(src) && /\bh=\{?[12]\}?/.test(src)) {
+            findings.push({
+                file: rel,
+                idiom: 'clipped-card',
+                detail: `autoHeight={false} with h<=2 (<=64px) — the card is guaranteed to clip its content.`,
+            });
+        }
+    }
+    // Stale ledger entries: a claim that is no longer true is a claim that will
+    // be trusted next time. An exclusions ledger is a claim, not a fact.
+    const hit = new Set(findings.map((f) => `${f.idiom}:${f.file}`));
+    const staleExclusions = [
+        ...Object.keys(config.gluedExclusions ?? {}).filter((f) => !hit.has(`glued-widget:${f}`) && !hit.has(`autoheight-optout:${f}`)),
+        ...Object.keys(config.ungriddedExclusions ?? {}).filter((f) => !hit.has(`ungridded-multi-card:${f}`)),
+    ];
+    const summary = `scanned ${files.length} files across ${scanRootsResolved.length} root(s) [${scanRootsResolved.join(', ')}] ` +
+        `with cardTags [${config.cardTags.join(', ')}]` +
+        `${config.classSurfaces?.length ? ` + ${config.classSurfaces.length} class surface pattern(s)` : ''}; ` +
+        `${findings.length} finding(s); ${Object.keys(config.blindSpots ?? {}).length} declared blind spot(s); ` +
+        `${staleExclusions.length} stale exclusion(s).`;
+    return { findings, filesScanned: files.length, scanRootsResolved, staleExclusions, summary };
+}

package/dist/scanner/index.d.ts

@@ -0,0 +1,3 @@
+export { scanCardSurfaces, stripComments } from './cardSurfaceScanner.js';
+export type { CardSurfaceScannerConfig, CardSurfaceScanResult, CardSurfaceFinding, CardSurfaceIdiom, } from './cardSurfaceScanner.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scanner/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC1E,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC"}

package/dist/scanner/index.js

@@ -0,0 +1 @@
+export { scanCardSurfaces, stripComments } from './cardSurfaceScanner.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/page-builder",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Shared BSuite responsive page-builder grid and layout persistence primitives",
   "type": "module",
   "license": "UNLICENSED",
@@ -23,7 +23,11 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./styles.css": "./src/styles/react-grid-layout-overrides.css"
+    "./styles.css": "./src/styles/react-grid-layout-overrides.css",
+    "./scanner": {
+      "import": "./dist/scanner/index.js",
+      "types": "./dist/scanner/index.d.ts"
+    }
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -70,6 +74,7 @@
     "react-resizable": "^4.0.1",
     "typescript": "~6.0.3",
     "vite": "^8.0.16",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.8",
+    "@types/node": "^25.9.2"
   }
 }