react-semaphor 0.1.545 → 0.1.546

package/dist/surfboard/index.js

@@ -1,5 +1,5 @@
-import { a, R as s, D as o } from "../chunks/report-preferences-dialog-DUtuUL_5.js";
-import { C as f, E as D } from "../chunks/table-settings-CLZocegs.js";
+import { a, R as s, D as o } from "../chunks/report-preferences-dialog-4QEZWe5U.js";
+import { C as f, E as D } from "../chunks/table-settings-CunhoDUi.js";
 export {
   f as CONTROL_CARD_DEFAULT_VALUE,
   a as DisplayFormatPreferencesFields,

package/dist/types/components/index.d.ts

@@ -35,6 +35,8 @@ export { VisualEditingControls } from './editor/editor-main/visual-editing-contr
 export { AdvancedModeToggle } from './editor/editor-main/advanced-mode-toggle.js';
 export { AssistantProvider } from './assistant/assistant-provider.js';
 export { AssistantPanel, AssistantToolbarButton } from './assistant/assistant-entry-points.js';
+export { ArrangeLayoutButton } from './surfboard/arrange-layout-button.js';
+export { ScreenSizePreviewButton } from './surfboard/screen-size-preview-button.js';
 export type { AssistantPanelSurface } from './assistant/assistant-entry-points.js';
 export { useAssistant } from './assistant/use-assistant.js';
 export * from '../lib/types/common-types.js';

package/dist/types/components/surfboard/arrange-layout-button.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Arrange in the dashboard toolbar (responsive layouts RL-D13): lays the
+ * selected grid sheet out by kind on every screen size, or tidies it in its
+ * current order, with Undo on the toast (RL-INV-7). Shown while editing a
+ * grid sheet. Reads only the dashboard store, so semaphor-app mounts it in
+ * its own toolbar as well as the package's.
+ */
+export declare function ArrangeLayoutButton(): import("react").JSX.Element | null;

package/dist/types/components/surfboard/screen-size-preview-button.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Preview screen sizes without editing (responsive layouts RL-D19): opens the
+ * sheet's floating size control, look-only, at the size the grid shows now.
+ * The host places it beside the Activity bell for people who can edit the dashboard. Reads
+ * only the dashboard store, so semaphor-app mounts it in its own toolbar too.
+ */
+export declare function ScreenSizePreviewButton(): import("react").JSX.Element | null;

package/dist/types/index.js

@@ -1,9 +1,9 @@
-import { C as s, E as r, V as l, i as o, c as i, g as n, f as d, b as m, e as u, d as E, a as c, u as p, s as C, h as T, j as D, q as A, o as I, m as _, n as F, p as S, k as b, l as L, r as f, t as N } from "../chunks/table-settings-CLZocegs.js";
-import { C as y, D as M, L as g, P as h, e as x, g as O, j as V, h as k, k as w, d as U, b as B, i as K, c as z, n as v, f as P } from "../chunks/validators-DMHTpf7a.js";
-import { D as q } from "../chunks/token-types-DBbZVQsm.js";
-import { B as Q, a as j, p as W, r as J } from "../chunks/bookmark-state-CXw7lZ50.js";
-import { r as H, a as Z } from "../chunks/pivot-result-identity-DJhXXcns.js";
-import { D as ee } from "../chunks/report-runtime-context-Dq8XyODK.js";
+import { C as s, E as r, V as l, i as o, c as i, g as n, f as d, b as m, e as u, d as E, a as c, u as p, s as C, h as T, j as D, q as A, o as I, m as _, n as F, p as S, k as b, l as L, r as f, t as N } from "../chunks/table-settings-CunhoDUi.js";
+import { C as y, D as M, L as g, P as h, e as x, g as O, j as V, h as k, k as w, d as U, b as B, i as K, c as z, n as v, f as P } from "../chunks/validators-C-aOQlTB.js";
+import { D as q } from "../chunks/token-types-BMqRmT-C.js";
+import { B as Q, a as j, p as W, r as J } from "../chunks/bookmark-state-C4vetoa0.js";
+import { r as H, a as Z } from "../chunks/pivot-result-identity-C-Q1j1Wb.js";
+import { D as ee } from "../chunks/report-runtime-context-hWiTCzFV.js";
 const e = [
   "concatenate",
   "conditional-category",

package/dist/types/lib/charts/table-chart-types.d.ts

@@ -0,0 +1,4 @@
+import { TChartType } from './types.js';
+/** The chart types that render as tables. No runtime imports: server-safe code reads these. */
+export declare const TABLE_CHART_TYPES: readonly ["table", "pivotTable", "aggregateTable", "matrixTable", "detailTable"];
+export declare function isTableChartType(chartType: TChartType | string | undefined | null): boolean;

package/dist/types/lib/charts/types.d.ts

@@ -7,6 +7,7 @@ import { SemaphorResultColumn } from '../../shared/analytics-protocol/index.js';
 import { PresentationExecutionSnapshot } from '../../shared/format-utils/index.js';
 import { CartesianTemporalPresentation } from '../formatters/cartesian-temporal-presentation.js';
 import { CartesianFieldRoles } from './cartesian-fields.js';
+import { TABLE_CHART_TYPES, isTableChartType } from './table-chart-types.js';
 export type ChartConfigParams = {
     card: TCard;
     data: any[];
@@ -49,8 +50,7 @@ export type BlurEffectProps = {
     blurColor?: string;
 };
 export type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'matrixTable' | 'detailTable' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
-export declare const TABLE_CHART_TYPES: readonly ["table", "pivotTable", "aggregateTable", "matrixTable", "detailTable"];
-export declare function isTableChartType(chartType: TChartType | string | undefined | null): boolean;
+export { TABLE_CHART_TYPES, isTableChartType };
 export declare function isChartJsVisualType(chartType: TChartType | string | undefined | null): boolean;
 export declare const REGULAR_TABLE_SETTINGS_CHART_TYPES: readonly ["table", "matrixTable", "pivotTable", "aggregateTable", "detailTable"];
 export declare function supportsRegularTableSettings(chartType: TChartType | string | undefined | null): boolean;

package/dist/types/lib/dashboard-inputs/dashboard-input-values.d.ts

@@ -80,3 +80,9 @@ export declare function removeDashboardInputSlotsById(values: DashboardInputValu
  * are the stored slots, read without building the model.
  */
 export declare function savedDefaultInputValues(dashboard: Pick<TDashboard, 'defaultInputValues' | 'defaultFilterValues'>): DashboardInputValues | undefined;
+/**
+ * Every value an input holds, saved or live, removed: its shared slot and its
+ * slot on every sheet, card and Document section. Shared by the store's
+ * input removal and the dashboard reducer's `filter.remove`.
+ */
+export declare function removeDashboardInputFromValues(values: DashboardInputValues | undefined, inputId: string): DashboardInputValues;

package/dist/types/lib/dashboard-inputs/filter-settings.d.ts

@@ -108,6 +108,8 @@ export declare function buildFilterInputFromField(params: {
     scope: DashboardInputScope;
     existingInputs: readonly DashboardInput[];
     createId?: () => string;
+    /** The filter's label (and variable name); default the field's label. */
+    label?: string;
 }): EmbeddedFilterDashboardInput;
 /**
  * A new filter input holding this definition (one filter model Phase 5):

package/dist/types/lib/dashboard-inputs/prepare-loaded-dashboard.d.ts

@@ -0,0 +1,15 @@
+import { TDashboard } from '../types/common-types.js';
+/**
+ * A saved dashboard as it enters a runtime (one filter model SPEC 5.1): the
+ * filter model's stored shape, every filter an embedded input, when the
+ * model reads it without issues; otherwise the template as received, read
+ * tolerantly (rejected inputs left out) and refused on save. Then the
+ * Include / Exclude repair. Loading never throws on model issues.
+ *
+ * The one entry for every runtime: the client load (`useDashboard`), the
+ * store's replace and load (`setDashboard`, `setDashboardWithFilterValues`)
+ * and the server's saved-dashboard reader, so they all hold the same shape.
+ * The same object when nothing changes. Alias-based text is bound to stable
+ * input ids before the upgrade (`upgradeToStoredDashboard`, ledger P5-11).
+ */
+export declare function prepareLoadedDashboard<TDashboardShape extends TDashboard>(dashboard: TDashboardShape): TDashboardShape;

package/dist/types/lib/matrix-table/matrix-editor.d.ts

@@ -0,0 +1,52 @@
+import { ContainerId, Field } from '../types/explorer-types.js';
+import { TCard } from '../types/common-types.js';
+import { FieldPlacement, FieldPlacementContext, FieldPlacementOutcome } from '../utils/field-placement.js';
+import { MatrixViewState, MatrixConfig, MatrixSpec } from '../../shared/analytics-protocol/index.js';
+import { MatrixAuthoringChange, MatrixAuthoringNotice } from '../../shared/dashboard-authoring/matrix-authoring.js';
+import { MatrixCardCatalog } from './matrix-card-adapter.js';
+/** Source-panel fields already carry catalog identity; do not infer it from names or SQL. */
+export declare function matrixEditorCatalogFromFields(card: Pick<TCard, 'dataSource'> & {
+    config?: {
+        matrix?: {
+            spec: Pick<MatrixSpec, 'source'>;
+        };
+    };
+}, fields: readonly Field[]): MatrixCardCatalog;
+export type MatrixEditorChange = {
+    card: TCard;
+    notices: readonly MatrixAuthoringNotice[];
+};
+export declare function changeMatrixEditor(card: TCard, config: MatrixConfig, change: MatrixAuthoringChange, catalog: MatrixCardCatalog): MatrixEditorChange;
+/**
+ * Copy the live session into the authored config: expansion on both axes
+ * becomes defaultView and effective sorts become the authored sorts. This is
+ * the one explicit path from exploration to persisted state.
+ */
+export declare function persistMatrixEditorView(card: TCard, config: MatrixConfig, view: MatrixViewState, catalog: MatrixCardCatalog): MatrixEditorChange;
+/** All editor surfaces replace the canonical config and its bindings atomically. */
+export declare function applyMatrixEditorResult(card: TCard, result: {
+    config: MatrixConfig;
+    bindings: readonly NonNullable<TCard['controlBindings']>[number][];
+    notices: readonly MatrixAuthoringNotice[];
+}): MatrixEditorChange;
+/**
+ * Field placement for Matrix cards: the field-list entity gate, then the one
+ * spec transaction. Side-effect-free; the new instance id is context input.
+ * Called through `evaluateFieldPlacement` by both the drop and its preview.
+ */
+export declare function evaluateMatrixPlacement(card: TCard, placement: FieldPlacement, context: FieldPlacementContext): FieldPlacementOutcome;
+/**
+ * One atomic mutation for source drops, cross-shelf moves and reordering.
+ * A field-list drop creates an instance and needs `newInstanceId`; the
+ * committing adapter mints it, so this function reads no random source.
+ */
+export declare function dropMatrixEditorField(card: TCard, catalog: MatrixCardCatalog, input: {
+    field: Field;
+    from: ContainerId;
+    to: ContainerId;
+    beforeId?: string;
+    newInstanceId?: string;
+}): MatrixEditorChange;
+export declare function removeMatrixEditorField(card: TCard, zone: ContainerId, id: string, catalog: MatrixCardCatalog): MatrixEditorChange;
+/** Scope storage stays with calculated-field transitions; this owns selected Matrix copies. */
+export declare function reconcileMatrixCalculatedField(card: TCard, fields: readonly Field[], previous: Field | undefined, updated?: Field): MatrixEditorChange;

package/dist/types/lib/query-context/dashboard-filter-mapping-resolution.d.ts

@@ -73,6 +73,75 @@ export declare function validateDashboardFilterTargetForCard(params: {
     sourceIndex: ReturnType<typeof buildDashboardCardSourceIndex>;
     target: DashboardFilterTarget;
 }): DashboardFilterTargetValidation;
+/**
+ * Where a filter input lands on a card: the one decision execution
+ * (`resolveDashboardFilterMappings`) and every description of reach (the
+ * dashboard outline, the change resolver's reach warnings and filter-effect
+ * check) make, in one order: the card's mapping entry (excluded, or a bound
+ * target the card must still address), then SQL Auto, then the automatic and
+ * inherited targets. A selected value only supplies the automatic target's
+ * data type when the input states none.
+ */
+export type DashboardFilterCardTarget = {
+    status: 'excluded';
+} | {
+    status: 'bound';
+    bindingId: string;
+    target: DashboardFilterTarget;
+    validation: Extract<DashboardFilterTargetValidation, {
+        status: 'valid';
+    }>;
+}
+/**
+ * A bound target the card can't run, no longer addresses, or whose type the
+ * filter's values can't take: the card blocks until it is mapped again.
+ */
+ | {
+    status: 'unsupportedTarget' | 'stale' | 'incompatible';
+    bindingId: string;
+} | {
+    status: 'sql';
+} | {
+    status: 'automatic';
+    target: DashboardFilterTarget;
+}
+/**
+ * The card's data takes the filter's field (the one applicability rule) but
+ * not through a source its query uses, such as a dataset it selects or
+ * joins: the value applies as it is, as it does for a filter with no card
+ * mappings.
+ */
+ | {
+    status: 'passthrough';
+} | {
+    status: 'ambiguous';
+} | {
+    status: 'notApplicable';
+};
+/** The filter's mapping marks the card "Don't apply" (the first step of `decideDashboardFilterCardTarget`). */
+export declare function isDashboardFilterCardExcluded(input: NormalizedFilterDashboardInput, cardId: string): boolean;
+export declare function decideDashboardFilterCardTarget(input: NormalizedFilterDashboardInput, card: TCard, sourceIndex?: ReturnType<typeof buildDashboardCardSourceIndex>, selectedValue?: TFilterValue): DashboardFilterCardTarget;
+/** How a filter applies to a card, whatever value it holds. */
+export type DashboardFilterCardReach = 
+/** The mapping marks the card "Don't apply". */
+'excluded'
+/** The mapping binds the filter to a field of the card. */
+ | 'bound'
+/** The card executes the filter's own field (or a proven binding's), so it applies with no mapping. */
+ | 'automatic'
+/** A SQL card takes the filter's value as is. */
+ | 'sql'
+/** More than one field of the card could take it: the card blocks until it is mapped. */
+ | 'ambiguous'
+/** The mapping binds a target the card can't run or no longer has: the card blocks until it is mapped again. */
+ | 'blocked' | 'notApplicable';
+/**
+ * Whether a filter in scope reaches a card, read without a value, from the
+ * decision execution makes (`decideDashboardFilterCardTarget`). The dashboard
+ * outline and the change resolver read it, so they report what the card runs
+ * (MCP dashboard editing SPEC 3.6, 5.4).
+ */
+export declare function describeDashboardFilterCardReach(input: NormalizedFilterDashboardInput, card: TCard): DashboardFilterCardReach;
 export declare function resolveDashboardFilterMappings({ card, inputs, resolvedInputs, activeFilterValues, shouldApplyDashboardFilters, }: {
     card: TCard;
     inputs: NormalizedFilterDashboardInput[];

package/dist/types/lib/stores/dashboard-store.d.ts

@@ -9,7 +9,8 @@ import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.j
 import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
 import { MissingPrintInputs } from '../print/print-inputs.js';
 import { default as ReactGridLayout } from 'react-grid-layout';
-import { DashboardFramePlacement } from '../../shared/dashboard-authoring/operations/apply-dashboard-operations.js';
+import { CustomizableBreakpoint, EditableBreakpoint, FramePlacement, GridEditBreakpoint, LayoutItem } from '../../shared/layouts/index.js';
+import { DashboardOperation, OperationContext } from '../../shared/dashboard-authoring/operations/apply-dashboard-operations.js';
 import { FilterGroup, Field } from '../types/explorer-types.js';
 import { DashboardControlsModelOptions } from '../controls/control-authoring-types.js';
 import { SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
@@ -26,15 +27,86 @@ import { CardViewStateMap, DrillStep } from '../dashboard-view-state/index.js';
 import { DashboardCardPaginationState } from '../dashboard-pagination/dashboard-card-pagination.js';
 export declare function mergeSemanticExecutionPayloadIntoTarget(target: SemanticExecutionPayload, incoming?: SemanticExecutionPayload): void;
 type AddFrameOptions = {
-    /** Default `end`; beside a frame is how a duplicate lands next to its original. */
-    placement?: DashboardFramePlacement;
+    /** By intent; absent: placed by kind (RL-D12). A duplicate passes `{ position: { beside: originalId } }`. */
+    placement?: FramePlacement;
     semanticExecutionPayload?: SemanticExecutionPayload;
 };
+/**
+ * A proposal the assistant applied in this edit session (analytics agent
+ * Plan 1, spec 8.1, D7-20): the document before and after it, for Undo.
+ */
+export type AppliedProposal = {
+    proposalId: string;
+    before: TDashboard;
+    beforePayload: SemanticExecutionPayload;
+    after: TDashboard;
+};
+export type ApplyProposalInput = {
+    proposalId: string;
+    operations: DashboardOperation[];
+    /** The context the proposal was resolved with: its pinned calendar. */
+    context: OperationContext;
+    /** The exact document the proposal was built from (D7-19). */
+    basedOn: TDashboard;
+    /** Metadata loaded for cards the loaded metadata doesn't cover. */
+    semanticExecutionPayload?: SemanticExecutionPayload;
+};
+export type ApplyProposalRefusal = {
+    ok: false;
+    reason: 'dashboard_changed' | 'not_editable' | 'refused' | 'previous_not_applied';
+    message: string;
+};
+export type ApplyProposalResult = {
+    ok: true;
+    after: TDashboard;
+} | ApplyProposalRefusal;
+export type UndoProposalResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'changed_since' | 'not_found' | 'not_editable';
+};
+/** Arrange from the toolbar (responsive layouts SPEC §6.4, RL-D13). */
+export type ArrangeSheetResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not_editable' | 'not_a_grid';
+};
+export type UndoArrangeResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'changed_since' | 'not_found';
+};
+/** The last toolbar Arrange: `after` is the store's own document, so Undo can tell whether anything changed since (RL-INV-7). */
+export type LastArrange = {
+    sheetId: string;
+    before: TDashboard;
+    after: TDashboard;
+};
+/** The words for a proposal the dashboard could not take, for the viewer. */
+export declare const PROPOSAL_REFUSALS: {
+    readonly dashboard_changed: "Not applied: the dashboard changed while I was answering.";
+    readonly not_editable: "Not applied: close the editor and ask again.";
+    readonly no_save: "Not applied: changes to this dashboard can't be saved here.";
+    /** A change built on one that wasn't applied here: nothing to build on (P7-46). */
+    readonly previous_not_applied: "Not applied: the change before it wasn't applied.";
+};
 export type DashboardStore = {
     isDownloadingPdf?: boolean;
     isSessionExpired: boolean;
     authToken?: AuthToken;
+    /** The breakpoint the sheet grid renders: from the container width in view mode, `layoutEditBreakpoint` while editing, `lg` in print (responsive layouts SPEC §6.3). semaphor-app's BreakpointIndicator reads it. */
     currentBreakpoint: Breakpoint;
+    /** The breakpoint the editor edits (RL-D11). Reset to `lg` on dashboard load and on leaving edit mode. */
+    layoutEditBreakpoint: EditableBreakpoint;
+    /**
+     * A screen size shown look-only, or Laptop or Small phone while editing
+     * (responsive layouts RL-D18, RL-D19). null: no preview. Never saved; cleared
+     * on load, on entering or leaving edit mode, and when an editable size is chosen.
+     */
+    layoutPreviewBreakpoint: Breakpoint | null;
     theme?: 'light' | 'dark' | 'system';
     themeStyle?: StyleProps;
     filteringCards?: TCard[];
@@ -70,6 +142,14 @@ export type DashboardStore = {
         dashboard: TDashboard;
         semanticExecutionPayload: SemanticExecutionPayload;
     } | null;
+    /**
+     * The assistant's proposals applied in this edit session, oldest first
+     * (analytics agent Plan 1, spec 8.1, D7-20). Leaving edit mode, and every
+     * replacement of the document but a proposal's own Undo, clears them.
+     */
+    appliedProposals: AppliedProposal[];
+    /** The last toolbar Arrange, for its Undo. Cleared by any dashboard load, leaving edit mode, or a successful undo (responsive layouts SPEC §6.4). */
+    lastArrange?: LastArrange;
     isVisualEditing: boolean;
     showDashboardJSON: boolean;
     showFilters: boolean;
@@ -273,7 +353,20 @@ type Actions = {
     clearDocumentInputRuntime: (sheetId?: string) => void;
     setSelectedSheetId: (sheetId: string | null) => void;
     setSheetLayout: (sheetId: string, layout: ReactGridLayout.Layout[]) => void;
-    setSheetLayouts: (sheetId: string, layouts: ReactGridLayout.Layouts) => void;
+    /** The grid's items at the edited breakpoint after a drag or resize stop, through the layout engine (`grid_edited`). */
+    editSheetLayout: (sheetId: string, breakpoint: GridEditBreakpoint, items: LayoutItem[]) => void;
+    /** Shows a screen size look-only, or ends the preview with null (RL-D19). */
+    setLayoutPreviewBreakpoint: (breakpoint: Breakpoint | null) => void;
+    /** The screen size the editor edits: Desktop, Tablet or Phone (RL-D11). */
+    setLayoutEditBreakpoint: (breakpoint: EditableBreakpoint) => void;
+    /** "Back to automatic" for a customized Tablet or Phone layout, through the layout engine (`reset_to_automatic`). */
+    resetSheetLayout: (sheetId: string, breakpoint: CustomizableBreakpoint) => void;
+    /** Arrange from the toolbar: the `layout.arrange` operation, with edit mode on and an undo record (RL-D13, RL-INV-7). */
+    arrangeSheet: (sheetId: string, options?: {
+        keepOrder?: boolean;
+    }) => ArrangeSheetResult;
+    /** Restores the dashboard from before the last toolbar Arrange while it is still what the Arrange left. */
+    undoArrange: () => UndoArrangeResult;
     setSelectedCardId: (sheetId: string, cardId: string | null) => void;
     setSelectedFrameId: (frameId: string) => void;
     clearSelectedFrameId: () => void;
@@ -281,7 +374,7 @@ type Actions = {
     setCardInfo: (cardId: string, info: string) => void;
     setCardSql: (sheetId: string, cardId: string, sql: string) => void;
     setCardPython: (cardId: string, pythonCode: string) => void;
-    setCardDescription: (sheetId: string, cardId: string, description: string, preferences?: TCard['preferences']) => void;
+    setCardDescription: (sheetId: string, cardId: string, description: string) => void;
     setCardKpiOptions: (sheetId: string, cardId: string, kpiOptions: Record<string, any>) => void;
     updateCardFilters: (cardId: string, filters: FilterGroup | undefined) => void;
     clearCardFilters: (cardId: string) => void;
@@ -301,7 +394,7 @@ type Actions = {
     clearAllInlineFilterValues: () => void;
     setInlineFilterValuesMap: (map: Record<string, TFilterValue[]>) => void;
     setCardInlineFilterDefaultValues: (sheetId: string, cardId: string, filterId: string, defaultValues: (string | number)[] | undefined) => void;
-    addFrame: (sheetId: string, frame: TFrame, positionOrOptions?: 'start' | 'end' | AddFrameOptions) => void;
+    addFrame: (sheetId: string, frame: TFrame, options?: AddFrameOptions) => void;
     updateFrame: (sheetId: string, frame: TFrame, options?: {
         semanticExecutionPayload?: SemanticExecutionPayload;
     }) => void;
@@ -315,6 +408,15 @@ type Actions = {
     removeFrame: (sheetId: string, frameId: string) => void;
     removeCard: (sheetId: string, card: TCard) => void;
     setIsDashboardEditing: (editing: boolean) => void;
+    /**
+     * Applies an assistant proposal to the dashboard on screen (spec 8.1,
+     * D7-18, D7-27): only while the dashboard is still `basedOn`, checked and
+     * written in one step, with edit mode on and an undo record. Callers go
+     * through `useApplyProposal`, which loads the metadata first.
+     */
+    applyProposal: (input: ApplyProposalInput) => ApplyProposalResult;
+    /** Undoes the newest applied proposal while the dashboard is still what it left (D7-20). */
+    undoProposal: (proposalId: string) => UndoProposalResult;
     setShowDashboardJSON: (show: boolean) => void;
     setIsVisualEditing: (editing: boolean) => void;
     setShowFilters: (show: boolean) => void;
@@ -435,6 +537,23 @@ export type ViewerRequestToken = {
  * editing turned on, else the dashboard as it is now. Both toolbars' "before
  * editing" capture reads this.
  */
+/**
+ * Whether a toolbar that owns the edit session (the package's or the app's)
+ * is mounted: each registers its unsaved-changes check while mounted. Where
+ * none is, there is no Save, so nothing changes the dashboard (D7-32).
+ */
+export declare function selectHasEditingToolbar(state: Pick<DashboardStore, 'checkUnsavedDashboardChanges'>): boolean;
+/**
+ * Where an applied proposal stands for its block (spec 8.1, D7-20):
+ * `undoable` while it is the newest and the dashboard is still what it left,
+ * `older` with a newer one after it while the dashboard is still what the
+ * newest left, `changed_since` for every record after the person's own edit
+ * (their change may have undone this one, P7-36), `none` when its record is
+ * gone.
+ */
+export type ProposalRecordState = 'undoable' | 'older' | 'changed_since' | 'none';
+export declare function selectProposalRecordState(state: Pick<DashboardStore, 'appliedProposals' | 'dashboard'>, proposalId: string): ProposalRecordState;
+export declare function selectProposalUndoable(state: Pick<DashboardStore, 'appliedProposals' | 'dashboard'>, proposalId: string): boolean;
 export declare function selectEditSessionStart(state: Pick<DashboardStore, 'editingStartedWith' | 'dashboard' | 'semanticExecutionPayload'>): {
     dashboard: TDashboard;
     semanticExecutionPayload: SemanticExecutionPayload;

package/dist/types/lib/types/common-types.d.ts

@@ -315,6 +315,8 @@ export type AuthToken = {
     refreshToken?: string;
 };
 export type Breakpoint = 'lg' | 'md' | 'sm' | 'xs' | 'xxs';
+/** The breakpoints a person may customize on purpose: Tablet and Phone (responsive layouts RL-D14). */
+export type CustomizableBreakpoint = Extract<Breakpoint, 'sm' | 'xs'>;
 type FilterOnClick = {
     expression?: string;
     columnIndex: number;
@@ -1521,6 +1523,12 @@ export type TSheet = {
     description?: string;
     layout?: ReactGridLayout.Layout[];
     layouts?: ReactGridLayout.Layouts;
+    /**
+     * The breakpoints edited on purpose (responsive layouts RL-D3); every other
+     * breakpoint but `lg` is derived from `lg` by the layout engine
+     * (`src/shared/layouts`). Absent on a sheet the engine has never written.
+     */
+    customizedBreakpoints?: CustomizableBreakpoint[];
     cards?: TCard[];
     frames?: TFrame[];
     calculatedFields?: Field[];

package/dist/types/lib/types/explorer-types.d.ts

@@ -212,6 +212,14 @@ export interface MetricField extends Field {
      * pre-aggregated metric input.
      */
     isPreAggregated?: boolean;
+    /**
+     * The governed compiler's aggregate provenance, saved with every card it
+     * compiles (semaphor-app `buildMetricField`): the semantic model's
+     * aggregate, the one applied, and where it came from.
+     */
+    semanticAggregate?: AggregateFunction;
+    effectiveAggregate?: AggregateFunction;
+    aggregateSource?: 'semantic_model' | 'caller_override' | 'default_sum';
     comparison?: MetricComparisonConfig;
     comparisonPolarity?: MetricComparisonPolarity;
     /** Governed runtime annotation. When present, authoring polarity is read-only. */
@@ -478,6 +486,8 @@ export interface FilterCondition {
      * it was saved.
      */
     latestValue?: true;
+    /** Set when the governed compiler added the latest-value condition by a snapshot dataset's policy (no stated window), not someone's choice: a read leaves it unstated and a recompile adds it again. */
+    latestValuePolicy?: 'snapshot';
 }
 export interface FilterGroup {
     id: string;

package/dist/types/lib/types/semantic-types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Joinability types: the response of GET /api/v1/domains/[domainId]/joinability,
+ * used by field draggability states in the query builder.
+ *
+ * The domain template contract (datasets, fields, metrics, relationships) has one
+ * owner, semaphor-app (`src/lib/semantic/template/contract.ts`); it is not copied
+ * here. If a react-semaphor consumer ever needs template types, move the contract
+ * into react-semaphor's shared contracts and have the app import it, rather than
+ * copy it (domain template 2.1, ledger P2-20).
+ */
+/**
+ * Joinability map for a semantic domain
+ *
+ * Maps each dataset to the datasets it can join with, including both direct (1-hop)
+ * and indirect (2-hop) joins. This is a lightweight topology representation used by
+ * the frontend for UX feedback (field draggability states).
+ *
+ * The backend generates this from the full relationship definitions and serves it
+ * via GET /api/v1/domains/[domainId]/joinability
+ */
+export interface JoinabilityMap {
+    [datasetName: string]: {
+        /**
+         * Datasets that can be joined directly (1-hop)
+         * Example: orders.canJoinTo = ['customers', 'products']
+         */
+        canJoinTo: string[];
+        /**
+         * Datasets that require multi-hop joins (2-hop)
+         * Key: target dataset name
+         * Value: array of intermediate datasets to traverse
+         *
+         * Example: orders.indirectJoins = { countries: ['stores'] }
+         * Means: orders → stores → countries
+         */
+        indirectJoins: {
+            [targetDataset: string]: string[];
+        };
+        /**
+         * Datasets related by an ACTIVE relationship that is not set to join
+         * automatically. The query engine will not auto-join these; the user
+         * has to enable automatic join on the relationship or configure the
+         * join on the chart. Drives the "Requires setup" field state.
+         * Optional: older servers omit it.
+         */
+        manualJoins?: string[];
+        /**
+         * Direct neighbours connected by MORE THAN ONE active auto-join
+         * relationship, with the count. The engine picks by join priority,
+         * so this is informational ("Multiple relationships; highest
+         * priority is used"), never blocking. Optional.
+         */
+        ambiguousJoins?: {
+            [targetDataset: string]: number;
+        };
+        /**
+         * Cardinality of the direct auto-join, from THIS dataset's side.
+         * `one_to_many` means one row here matches many rows there, so an
+         * aggregate over this dataset's values joined to that dataset may
+         * repeat. `unknown` when the relationship has no authored cardinality
+         * (the planner refuses repeat-sensitive measures across it).
+         * Informational; drives a warning, never a block. Optional.
+         */
+        cardinality?: {
+            [targetDataset: string]: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many' | 'unknown';
+        };
+    };
+}
+/**
+ * Response from the joinability map API
+ */
+export interface JoinabilityMapResponse {
+    /** Lightweight joinability map for field state calculation */
+    joinabilityMap: JoinabilityMap;
+    /** Minimal dataset information */
+    datasets: Array<{
+        name: string;
+        label: string;
+        type: string;
+        table?: string | null;
+        catalog?: string | null;
+        schema?: string | null;
+    }>;
+}

package/dist/types/lib/utils/build-saved-editor-card.d.ts

@@ -0,0 +1,20 @@
+import { TCard } from '../types/common-types.js';
+type BuildSavedEditorCardOptions = {
+    isDevMode: boolean;
+    cardSql?: string;
+    selectedSchemaName?: string;
+    selectedDatabaseName?: string;
+    selectedTableName?: string;
+    selectedConnectionId?: string;
+    remoteChartSettings?: unknown;
+    stripConfig: (config: TCard['config']) => TCard['config'];
+};
+/**
+ * The card the editor saves. The editor's picker selection (database,
+ * schema, table, data model) is not written onto the card: a card's source is
+ * its `dataSource`, so Done with no change leaves the card as it was
+ * (MCP dashboard editing ledger V-50, V-58). A stored card's older copies of
+ * the picker stay as they are, read by nothing at run time.
+ */
+export declare function buildSavedEditorCard(card: TCard, { isDevMode, cardSql, selectedSchemaName, selectedDatabaseName, selectedTableName, selectedConnectionId, remoteChartSettings, stripConfig, }: BuildSavedEditorCardOptions): TCard;
+export {};

package/dist/types/lib/utils/card-type-change.d.ts

@@ -8,6 +8,11 @@ export type CardTypeChangeOptions = {
     catalogLoading?: boolean;
     /** A plugin visual chosen as `custom`. */
     customVisual?: TCustomCardPreferences;
+    /**
+     * Mints the ids the conversion needs (Matrix field instances), in order.
+     * Default `crypto.randomUUID`; a replayed change passes its stored ids (DE-D54).
+     */
+    createId?: () => string;
 };
 export type CardTypeChange = {
     status: 'refused';
@@ -19,6 +24,8 @@ export type CardTypeChange = {
     card: TCard;
     /** Labels of authored parts the new type could not keep. */
     leftOut: readonly string[];
+    /** Chart-scoped preference keys the new type drops (DE-D43). */
+    droppedPreferences: readonly (keyof TCardPreferences)[];
     crossedMatrixBoundary: boolean;
     forcesSqlMode: boolean;
 };
@@ -28,3 +35,12 @@ export type CardTypeChange = {
  * the editor store applies the result.
  */
 export declare function changeCardType(card: TCard, type: TCard['type'], options?: CardTypeChangeOptions): CardTypeChange;
+/**
+ * A type change as a person makes it in the editor (MCP dashboard editing
+ * DE-D51, ledger P2-01): the chart picker is `changeCardType`; between table
+ * kinds the table editor's tabs are `switchTableType`. A detail table is
+ * reached only through the tabs, so a change into or out of one goes through
+ * a table, as the editor's two steps do. The dashboard reducer's `retype`
+ * calls this; the editor keeps calling each half from its own control.
+ */
+export declare function changeCardTypeAsEditor(card: TCard, type: TCard['type'], options?: CardTypeChangeOptions): CardTypeChange;