react-semaphor 0.1.545 → 0.1.546

package/dist/types/shared/dashboard-authoring/operations/apply-dashboard-operations.d.ts

@@ -1,40 +1,13 @@
-import { TDashboard, TFrame } from '../../../lib/types/common-types.js';
+import { TDashboard } from '../../../lib/types/common-types.js';
+import { DashboardOperation, DashboardOperationResult, OperationContext } from './operation-types.js';
+export type { CardUpdate, CreatedEntity, DashboardOperation, DashboardOperationResult, DashboardRuntimeEffect, FrameCommit, FramePlacement, OperationContext, OperationDescription, OperationFailureCode, } from './operation-types.js';
 /**
  * Edits to a dashboard as operations on one pure reducer (analytics agent
- * Plan 1, AG-D14, Phase 7a). Every writer of these edits calls it: the
- * store's actions in the browser, and later an API or MCP edit on the
- * server. Callers that differ pass their differences in (placement, ids);
- * none keeps its own copy of the edit.
+ * Plan 1 AG-D14; MCP dashboard editing SPEC 3.3, 3.8). The one writer of the
+ * saved document for these edits: the editor stores, the change resolver's
+ * dry run and the server's apply all call it. It writes only the document; it
+ * returns what it created, one plain sentence per change, and the runtime
+ * effects a live editor applies to its own state (DE-D49). It never mints ids
+ * and never reads the clock (S-INV-1).
  */
-/** Where a new frame goes on its sheet: first, last, or right after a frame and beside it. */
-export type DashboardFramePlacement = 'start' | 'end' | {
-    beside: string;
-};
-export type DashboardOperation = {
-    op: 'frame.add';
-    sheetId: string;
-    /** The frame with its cards, ids included. */
-    frame: TFrame;
-    /** Default `end`. */
-    placement?: DashboardFramePlacement;
-};
-export type DashboardOperationFailureCode = 'sheet_not_found'
-/** A document sheet places cards through its document, not its grid. */
- | 'sheet_not_a_grid' | 'frame_id_taken';
-export type DashboardOperationResult = {
-    ok: true;
-    dashboard: TDashboard;
-} | {
-    ok: false;
-    failedAt: {
-        index: number;
-        op: DashboardOperation['op'];
-        code: DashboardOperationFailureCode;
-        message: string;
-    };
-};
-/**
- * Applies the operations in order, all or nothing. Never changes its input:
- * the result shares every sheet it did not touch.
- */
-export declare function applyDashboardOperations(dashboard: TDashboard, operations: DashboardOperation[]): DashboardOperationResult;
+export declare function applyDashboardOperations(dashboard: TDashboard, operations: readonly DashboardOperation[], context: OperationContext): DashboardOperationResult;

package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts

@@ -0,0 +1,189 @@
+import { EmbeddedFilterDashboardInput, TDashboard, TFrame } from '../../../lib/types/common-types.js';
+import { FilterSettingsChange, FilterValueEffect } from '../../../lib/dashboard-inputs/filter-settings.js';
+import { DashboardFilterBoundCardApplication } from '../dashboard-filter-mapping-types.js';
+import { Field } from '../../../lib/types/explorer-types.js';
+import { TChartType } from '../../../lib/charts/types.js';
+import { CalendarContext } from '../../report-runtime-context/index.js';
+import { CardQueryPart, StatedLabel } from '../changes/card-query-part.js';
+import { FramePlacement } from '../../layouts/index.js';
+/**
+ * The resolved operations the dashboard reducer applies (MCP dashboard
+ * editing SPEC 3.3, 3.8). Every id an operation creates is in it; the reducer
+ * never generates ids and never reads the clock (S-INV-1).
+ */
+/** Where a new frame goes on its sheet, by intent (responsive layouts SPEC §2.4). Absent: placed by kind. */
+export type { FramePlacement };
+export type CardUpdate = 
+/** Inline title and description edits; `description: null` removes it. */
+{
+    kind: 'rename';
+    title?: string;
+    description?: string | null;
+}
+/**
+ * A type transition: the editor's `changeCardType`, then the layout resize.
+ * `catalog` is the loaded column catalog a Matrix crossing needs; `newIds`
+ * every id the conversion mints, in the order it asks for them (DE-D54).
+ */
+ | {
+    kind: 'retype';
+    type: TChartType;
+    catalog?: readonly Field[];
+    newIds: string[];
+}
+/** A new computed part for the card's current type; presentation is carried (SPEC 3.4). */
+ | {
+    kind: 'requery';
+    query: CardQueryPart;
+}
+/** Labels a change states on columns it doesn't rebuild, set in place by the label owner; nothing is recompiled (DE-D61). */
+ | {
+    kind: 'relabel';
+    labels: StatedLabel[];
+};
+/** Everything the editor's "Done", Save & Apply and Apply Local commit persists, as one operation (DE-D13). */
+export type FrameCommit = {
+    sheetId: string;
+    /** The edited frame as the editor built it. Apply Local passes `visualId: undefined`. */
+    frame: TFrame;
+    /** Other frames on the sheet rewritten during the edit (calculated-field renames), applied with it. */
+    rewrittenFrames?: TFrame[];
+    /** Sheet calculated fields from the edited frame, persisted on the sheet. */
+    sheetCalculatedFields?: Field[];
+    /** Dashboard calculated fields rewritten during the edit. */
+    dashboardCalculatedFields?: Field[];
+    /** True when committed from the visual editor: resize the frame's layouts if its type changed. */
+    resizeLayouts: boolean;
+};
+export type DashboardOperation = ({
+    op: 'card.add';
+    sheetId: string;
+    /** The frame with its cards, ids included. */
+    frame: TFrame;
+    /** By intent; absent: placed by kind (responsive layouts SPEC §4.2). */
+    placement?: FramePlacement;
+} | {
+    op: 'card.update';
+    cardId: string;
+    update: CardUpdate;
+} | {
+    op: 'card.remove';
+    cardId: string;
+}
+/** Arrange a grid sheet by kind (responsive layouts RL-D7, SPEC §4.4); `keepOrder` keeps the reading order. */
+ | {
+    op: 'layout.arrange';
+    sheetId: string;
+    keepOrder?: boolean;
+}
+/** The editor's whole-frame commit; never produced by the resolver. */
+ | {
+    op: 'frame.commit';
+    commit: FrameCommit;
+}
+/** A new filter input, ids included; its defaults are in its definition, as the editor adds one. */
+ | {
+    op: 'filter.add';
+    input: EmbeddedFilterDashboardInput;
+}
+/** Settings through the editor's core (`applyFilterSettingsChange`); `filterId` is the input id. */
+ | {
+    op: 'filter.update';
+    filterId: string;
+    settings: FilterSettingsChange;
+} | {
+    op: 'filter.remove';
+    filterId: string;
+}
+/** The card's bound entry in the filter's mapping, built as the mapping editor builds one. */
+ | {
+    op: 'filter.bind';
+    filterId: string;
+    cardId: string;
+    binding: DashboardFilterBoundCardApplication;
+} | {
+    op: 'filter.exclude';
+    filterId: string;
+    cardId: string;
+}) & {
+    /** Set by the resolver: the public change this operation came from. Descriptions group by it. */
+    changeIndex?: number;
+};
+export type OperationContext = {
+    /** The report calendar; filter defaults resolve in it. A proposal's has a fixed anchor (DE-D59). */
+    calendar: CalendarContext | null;
+};
+export type CreatedEntity = {
+    kind: 'card' | 'filter';
+    id: string;
+    title: string;
+    changeIndex?: number;
+};
+export type OperationDescription = {
+    /** Operations with the same changeIndex share one description. */
+    changeIndex?: number;
+    /** Indexes into the operations list. */
+    operations: number[];
+    sentence: string;
+};
+/** What a live editor must do to its own state after an operation. The server ignores them (DE-D49). */
+export type DashboardRuntimeEffect = 
+/** card.remove, and frame.commit dropping tabs: drop live state keyed by these cards. */
+{
+    kind: 'cards_removed';
+    cardIds: string[];
+}
+/** frame.commit: re-sync inline filter runtime values from the frame before and after. */
+ | {
+    kind: 'frame_committed';
+    sheetId: string;
+    before: TFrame;
+    after: TFrame;
+}
+/**
+ * filter.update: `applyFilterSettingsChange`'s value effects, unchanged. One
+ * per update, even with none: the store still re-resolves forced selections,
+ * as `saveFilterSettings` always has (ledger P3-02).
+ */
+ | {
+    kind: 'filter_value';
+    effects: FilterValueEffect[];
+}
+/** filter.remove: drop the input's live values. */
+ | {
+    kind: 'input_removed';
+    inputId: string;
+};
+export type OperationFailureCode = 'sheet_not_found'
+/** A document sheet places cards through its document, not its grid. */
+ | 'sheet_not_a_grid' | 'frame_id_taken' | 'frame_not_found' | 'card_not_found' | 'filter_not_found' | 'filter_id_taken'
+/** The filter settings or mapping fail the input contract; `details.issues` has the core's issues. */
+ | 'filter_invalid'
+/** A requery part compiled for another type than the card's. */
+ | 'query_type_mismatch'
+/** A requery part that doesn't make a valid card (a Matrix definition the Matrix contract refuses). */
+ | 'query_invalid'
+/** A requery would change a part of the card its change doesn't state (DE-D61). */
+ | 'query_not_kept'
+/** A conversion asked for more ids than the operation carries. */
+ | 'ids_exhausted'
+/** A retype across the Matrix boundary without a catalog. */
+ | 'catalog_loading';
+export type DashboardOperationResult = {
+    ok: true;
+    dashboard: TDashboard;
+    created: CreatedEntity[];
+    /** One plain sentence per public change (or per operation without a changeIndex). */
+    descriptions: OperationDescription[];
+    runtimeEffects: DashboardRuntimeEffect[];
+} | {
+    ok: false;
+    failedAt: {
+        index: number;
+        op: DashboardOperation['op'];
+        code: OperationFailureCode;
+        message: string;
+        fix?: string;
+        details?: Record<string, unknown>;
+    };
+};

package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts

@@ -0,0 +1,94 @@
+import { TDashboard } from '../../../lib/types/common-types.js';
+import { FrameWidth } from '../../layouts/index.js';
+import { NotEditableReason, OutlineCardSource } from '../changes/read-card-query.js';
+import { CardQuery, MatrixColumns } from '../changes/dashboard-change.js';
+import { OutlineFilter } from './outline-filters.js';
+import { CalendarContext } from '../../report-runtime-context/index.js';
+/**
+ * A dashboard in the change vocabulary (MCP dashboard editing SPEC 3.6,
+ * DE-D29, DE-D34): every sheet, every card the shared traversal lists
+ * (Document-section cards included, read only), every filter, and what the
+ * viewer may do. A pure function of the hydrated dashboard and the viewer
+ * (S-INV-8): no clock, no catalog, no network.
+ */
+export type OutlineViewer = {
+    dashboardId: string;
+    /** `Dashboard.updatedAt`, ISO 8601; the staleness token, never called "version" (DE-D37). */
+    updatedAt: string;
+    access: {
+        canEdit: boolean;
+        canCopy: boolean;
+    };
+    sql: boolean;
+    sheetIds?: string[];
+    cardIds?: string[];
+    /** Above this many cards (after narrowing), queries are left out. Default 50 (DE-D34). */
+    maxQueryCards?: number;
+    /** The report calendar filter defaults are read in; without one, a fixed calendar at `updatedAt` (S-INV-8). */
+    calendar?: CalendarContext;
+};
+export type OutlineCard = {
+    cardId: string;
+    title: string;
+    /** The public type name (DE-D43). */
+    type: string;
+    source: OutlineCardSource;
+    /** Shows a library visual; changing it makes it local (DE-D50). */
+    linkedVisualId?: string;
+    editable: true;
+    /** Absent only when the outline is truncated. */
+    query?: CardQuery;
+    matrix?: MatrixColumns;
+} | {
+    cardId: string;
+    title: string;
+    type: string;
+    source?: OutlineCardSource;
+    linkedVisualId?: string;
+    editable: false;
+    notEditable: {
+        reason: NotEditableReason;
+        message: string;
+        detail?: string;
+    };
+};
+export type OutlineSheet = {
+    sheetId: string;
+    title: string;
+    /** Cards can be added only to "dashboard" sheets. */
+    kind: 'dashboard' | 'document';
+    /** On a Document sheet, its sections' cards (never editable). */
+    cards: OutlineCard[];
+    /**
+     * Grid sheets only: the desktop layout as rows, top to bottom, from the
+     * layout engine (responsive layouts RL-D10). Always the whole sheet, even
+     * when `cardIds` narrows the cards. Absent on Document sheets.
+     */
+    layout?: OutlineLayoutRow[];
+};
+/** One row of a sheet's desktop layout. A tile is a frame: its cards, active first, and its width by intent. Never coordinates (RL-INV-5). */
+export type OutlineLayoutRow = {
+    tiles: Array<{
+        cardIds: string[];
+        width: FrameWidth;
+    }>;
+};
+export type DashboardOutline = {
+    dashboardId: string;
+    title: string;
+    updatedAt: string;
+    access: {
+        canEdit: boolean;
+        canCopy: boolean;
+    };
+    /** Every dataset a card or filter uses. */
+    datasets: Array<{
+        domainId: string;
+        datasetName: string;
+    }>;
+    sheets: OutlineSheet[];
+    filters: OutlineFilter[];
+    /** Queries left out because the dashboard has more than `maxQueryCards` cards (DE-D34). */
+    truncated?: true;
+};
+export declare function outlineDashboard(dashboard: TDashboard, viewer: OutlineViewer): DashboardOutline;

package/dist/types/shared/dashboard-authoring/outline/outline-filters.d.ts

@@ -0,0 +1,78 @@
+import { TDashboard } from '../../../lib/types/common-types.js';
+import { FilterInputEntry } from '../filter-model/index.js';
+import { CalendarContext } from '../../report-runtime-context/index.js';
+import { FilterValue, TimeWindow } from '../changes/dashboard-change.js';
+/**
+ * Every dashboard filter in the change vocabulary (MCP dashboard editing
+ * DE-D58, SPEC 3.6). A field filter on one semantic dataset shown on every
+ * grid sheet or a list of sheets is editable; any other filter is a
+ * read-only summary with its reach and a reason, never left out and never
+ * given invented coordinates. Reach is read the way each card runs the
+ * filter (`describeDashboardFilterCardReach`).
+ */
+export type FilterNotEditableReason = 'global_date' | 'not_semantic' | 'scope_not_expressible';
+export type OutlineFilter = {
+    filterId: string;
+    label: string;
+    editable: true;
+    domainId: string;
+    datasetName: string;
+    field: string;
+    selection: 'single' | 'multiple';
+    /** The values it loads with, read through the default owner (a saved default first, else the definition). */
+    defaultValues?: FilterValue[];
+    /** The window it loads with, only when the loaded default keeps one (a day picker clamps a wider window to a day). */
+    defaultPeriod?: TimeWindow;
+    /** For a date filter, the picker a viewer gets: one day, one month, or a range. */
+    datePicker?: 'day' | 'month' | 'range';
+    /** "all": every grid sheet. */
+    sheetIds: string[] | 'all';
+    /** With "all": the sheets it leaves out ("every sheet except"); a sheet added later is reached. */
+    exceptSheetIds?: string[];
+    /** With "all": it also shows on Document sheets (their sections' cards). */
+    includesDocumentSheets?: true;
+    /** Card ids the filter applies to. */
+    reaches: string[];
+    /** Card ids excluded explicitly. */
+    excluded: string[];
+    /** In scope, not matched. */
+    notReached: Array<{
+        cardId: string;
+        title: string;
+        datasetName?: string;
+    }>;
+    /** In scope, and blocked when the filter has a value: a binding the card can't run, or two fields it could take. */
+    blocked?: Array<{
+        cardId: string;
+        title: string;
+        reason: 'blocked' | 'ambiguous';
+    }>;
+} | {
+    filterId: string;
+    label: string;
+    editable: false;
+    kind: 'global_date' | 'field' | 'other';
+    notEditable: {
+        reason: FilterNotEditableReason;
+        message: string;
+    };
+    reaches: string[];
+    excluded: string[];
+    blocked?: Array<{
+        cardId: string;
+        title: string;
+        reason: 'blocked' | 'ambiguous';
+    }>;
+};
+/**
+ * The calendar a summary reads defaults in: the report's, else a fixed one at
+ * the dashboard's own time, so a summary stays a pure function of its inputs.
+ * Only whether a default keeps its window is reported, never the dates it
+ * resolves to.
+ */
+export declare function outlineCalendar(calendar: CalendarContext | undefined, updatedAt: string | undefined): CalendarContext;
+export declare function summarizeFilter(dashboard: TDashboard, entry: FilterInputEntry, calendar?: CalendarContext): OutlineFilter;
+/** Every filter on the dashboard, in the filter model's order. */
+export declare function outlineFilters(dashboard: TDashboard, calendar?: CalendarContext): OutlineFilter[];
+/** One filter by its input id, or undefined. */
+export declare function outlineFilter(dashboard: TDashboard, filterId: string, calendar?: CalendarContext): OutlineFilter | undefined;

package/dist/types/shared/dashboard-authoring/validators.d.ts

@@ -1,3 +1,2 @@
-import { DashboardAuthoringValidationResult, DashboardChangePlan, DashboardPlan } from './contracts.js';
+import { DashboardAuthoringValidationResult, DashboardPlan } from './contracts.js';
 export declare function validateDashboardPlan(plan: DashboardPlan): DashboardAuthoringValidationResult;
-export declare function validateDashboardChangePlan(plan: DashboardChangePlan): DashboardAuthoringValidationResult;

package/dist/types/shared/layouts/engine/grid.d.ts

@@ -0,0 +1,25 @@
+import { Breakpoint, CustomizableBreakpoint } from '../../../lib/types/common-types.js';
+/**
+ * The dashboard grid's breakpoints and columns: the only place these values
+ * exist (responsive layouts SPEC §2.1, RL-INV-1).
+ */
+export type { CustomizableBreakpoint };
+/** Breakpoints the editor can edit: Desktop, Tablet, Phone (RL-D11, RL-D14). */
+export type EditableBreakpoint = 'lg' | CustomizableBreakpoint;
+/** Breakpoints a grid edit can arrive at: the editable ones, and `md`, an edit of Desktop at laptop width (RL-D17). */
+export type GridEditBreakpoint = EditableBreakpoint | 'md';
+export declare const DASHBOARD_GRID: {
+    /** Widest first. */
+    readonly breakpoints: readonly Breakpoint[];
+    readonly columns: Readonly<Record<Breakpoint, number>>;
+    /** react-grid-layout's default breakpoint widths, now stated. */
+    readonly minContainerWidthPx: Readonly<Record<Breakpoint, number>>;
+    readonly editable: readonly EditableBreakpoint[];
+    readonly customizable: readonly CustomizableBreakpoint[];
+    /** The preview canvas widths: Laptop, Tablet, Phone, Small phone (Desktop is at least `minContainerWidthPx.lg`; RL-D19). */
+    readonly previewWidthPx: Readonly<Record<Exclude<Breakpoint, "lg">, number>>;
+};
+export declare const LG_COLUMNS: number;
+export declare function isCustomizableBreakpoint(value: unknown): value is CustomizableBreakpoint;
+export declare function isEditableBreakpoint(value: unknown): value is EditableBreakpoint;
+export declare function isGridEditBreakpoint(value: unknown): value is GridEditBreakpoint;

package/dist/types/shared/layouts/engine/index.d.ts

@@ -0,0 +1,4 @@
+export { DASHBOARD_GRID } from './grid.js';
+export type { CustomizableBreakpoint, EditableBreakpoint, GridEditBreakpoint } from './grid.js';
+export type { FramePlacement, FramePosition, FrameWidth, LayoutItem, LayoutKind, SheetLayoutChange, SheetLayoutFailure, SheetLayoutInput, SheetLayoutResult, SheetLayoutRow, SheetLayouts, SheetLayoutTile, SheetLayoutView, } from './types.js';
+export { applySheetLayoutChange, assertSheetLayouts, readSheetLayout } from './sheet-layout.js';

package/dist/types/shared/layouts/engine/sheet-layout.d.ts

@@ -0,0 +1,7 @@
+import { SheetLayoutChange, SheetLayoutInput, SheetLayoutResult, SheetLayouts, SheetLayoutView } from './types.js';
+/** Every layout read (SPEC §3.2): complete, valid layouts; customized breakpoints, stored or inferred; `lg` as rows. Never fails. */
+export declare function readSheetLayout(sheet: SheetLayoutInput): SheetLayoutView;
+/** Every layout write (SPEC §3.1). `sheet` is the sheet before the change. */
+export declare function applySheetLayoutChange(sheet: SheetLayoutInput, change: SheetLayoutChange): SheetLayoutResult;
+/** Throws when layouts break invariants 1 to 4 (complete, in bounds, no overlaps, packed). For tests and development builds. */
+export declare function assertSheetLayouts(layouts: SheetLayouts, frameIds: readonly string[]): void;

package/dist/types/shared/layouts/engine/types.d.ts

@@ -0,0 +1,125 @@
+import { Breakpoint, TFrame, TSheet } from '../../../lib/types/common-types.js';
+import { CustomizableBreakpoint, GridEditBreakpoint } from './grid.js';
+/** One frame's tile on one breakpoint. The keys the dirty check persists (`PERSISTED_LAYOUT_KEYS`). */
+export type LayoutItem = {
+    /** The frame id. */
+    i: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    minW?: number;
+    minH?: number;
+    maxW?: number;
+    maxH?: number;
+    static?: boolean;
+    isResizable?: boolean;
+    isDraggable?: boolean;
+};
+/** Complete layouts: every breakpoint present. What the engine returns. */
+export type SheetLayouts = Record<Breakpoint, LayoutItem[]>;
+/** What the engine reads from a sheet. */
+export type SheetLayoutInput = Pick<TSheet, 'id' | 'frames' | 'layouts' | 'layout' | 'customizedBreakpoints'>;
+/** How a frame is sized and grouped (SPEC §2.4). */
+export type LayoutKind = 'kpi' | 'chart' | 'table' | 'text';
+/** A width by intent, as a share of the 48 `lg` columns: full 48, half 24, third 16, quarter 12. */
+export type FrameWidth = 'full' | 'half' | 'third' | 'quarter';
+/** Where a new frame goes on `lg`. Ids are frame ids. */
+export type FramePosition = 'top' | 'end' | {
+    after: string;
+} | {
+    beside: string;
+};
+/** How a caller states a new frame's place. Absent: placed by kind (SPEC §4.2). */
+export type FramePlacement = {
+    position?: FramePosition;
+    width?: FrameWidth;
+};
+export type SheetLayoutChange = 
+/** A new frame, not in `sheet.frames` yet. Without `placement`: by kind. */
+{
+    kind: 'frame_added';
+    frame: TFrame;
+    placement?: FramePlacement;
+}
+/** A frame in `sheet.frames` that leaves the sheet. */
+ | {
+    kind: 'frame_removed';
+    frameId: string;
+}
+/** A frame's content changed: the frame after the change, same id, in `sheet.frames`. */
+ | {
+    kind: 'frame_updated';
+    frame: TFrame;
+    resizeForNewKind: boolean;
+}
+/** The grid's items after a drag or resize stop at the breakpoint being edited. */
+ | {
+    kind: 'grid_edited';
+    breakpoint: GridEditBreakpoint;
+    items: readonly LayoutItem[];
+}
+/** "Back to automatic" for one customized breakpoint. */
+ | {
+    kind: 'reset_to_automatic';
+    breakpoint: CustomizableBreakpoint;
+}
+/** Arrange the sheet. */
+ | {
+    kind: 'arrange';
+    keepOrder?: boolean;
+};
+export type SheetLayoutFailure = {
+    code: 'frame_not_on_sheet';
+    frameId: string;
+    message: string;
+} | {
+    code: 'frame_already_on_sheet';
+    frameId: string;
+    message: string;
+} | {
+    code: 'position_target_not_found';
+    frameId: string;
+    message: string;
+} | {
+    code: 'breakpoint_not_editable';
+    breakpoint: string;
+    message: string;
+};
+export type SheetLayoutResult = {
+    ok: true;
+    /** The sheet's frames in their new order; the input array itself when untouched. */
+    frames: TFrame[];
+    layouts: SheetLayouts;
+    customizedBreakpoints: CustomizableBreakpoint[];
+    /** False when `frames`, `layouts` and `customizedBreakpoints` equal what `readSheetLayout(sheet)` gives. */
+    changed: boolean;
+    /**
+     * False when `layouts` and `customizedBreakpoints` equal the view's. Callers write them only when
+     * true, so a change with no layout effect (a frame update keeping its kind) leaves stored layouts
+     * untouched: a no-op editor Done stays clean (V-50).
+     */
+    layoutsChanged: boolean;
+} | {
+    ok: false;
+    failure: SheetLayoutFailure;
+};
+/** `width`: the `FrameWidth` whose column count is nearest the item's `lg` `w`; a tie goes to the wider. */
+export type SheetLayoutTile = {
+    frameId: string;
+    kind: LayoutKind;
+    width: FrameWidth;
+};
+export type SheetLayoutRow = {
+    tiles: SheetLayoutTile[];
+};
+export type SheetLayoutView = {
+    /** Complete and valid on every breakpoint; what the grid renders. */
+    layouts: SheetLayouts;
+    /** Stored `customizedBreakpoints`, or inferred when absent (SPEC §4.6). */
+    customizedBreakpoints: CustomizableBreakpoint[];
+    /** The `lg` layout as rows, top to bottom, tiles left to right. */
+    rows: SheetLayoutRow[];
+    /** True when `layouts` differs from what is stored. */
+    repaired: boolean;
+};

package/dist/types/shared/layouts/index.d.ts

@@ -1,2 +1 @@
-export * from './create-frame-layouts.js';
-export * from './frame-layouts.js';
+export * from './engine/index.js';

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.545",
+  "version": "0.1.546",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -123,7 +123,7 @@
     "build": "node scripts/build.mjs",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:regressions": "node scripts/lint-regressions.mjs",
-    "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs && node scripts/card-query-assembly-imports.mjs && node scripts/assistant-chat-imports.mjs && node scripts/filter-model-reads.mjs",
+    "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs && node scripts/card-query-assembly-imports.mjs && node scripts/assistant-chat-imports.mjs && node scripts/filter-model-reads.mjs && node scripts/layout-engine.mjs",
     "preview": "vite preview",
     "test": "vitest run",
     "test:changed": "vitest run --changed",