react-semaphor 0.1.545 → 0.1.547

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

@@ -1,5 +1,5 @@
 import { SelectionField, SelectionInputValue } from '../../shared/analytics-protocol/selection-contract.js';
-import { DashboardFilterTarget } from '../../shared/dashboard-authoring/index.js';
+import { DashboardFilterFieldTarget } from '../../shared/dashboard-authoring/index.js';
 import { ScopedDashboardInputTarget } from '../../shared/dashboard-authoring/dashboard-input-scope.js';
 import { NormalizedFilterDashboardInput, SelectionDashboardInput, TCard } from '../types/common-types.js';
 import { FilterCondition } from '../types/explorer-types.js';
@@ -19,7 +19,7 @@ export type SelectionBlockReason = 'ambiguousAutomaticTarget' | 'staleBinding' |
 export type SelectionConditionDisposition = {
     status: 'apply';
     clickedFieldKey: string;
-    target: DashboardFilterTarget;
+    target: DashboardFilterFieldTarget;
     provenance: 'automatic' | 'bound' | 'borrowedFromFilter';
     /** Set when provenance is 'borrowedFromFilter'. */
     borrowedFromInputId?: string;
@@ -57,7 +57,7 @@ export declare function findBorrowedSelectionBinding(params: {
     filterInputs: NormalizedFilterDashboardInput[];
 }): {
     inputId: string;
-    target: DashboardFilterTarget;
+    target: DashboardFilterFieldTarget;
 } | undefined;
 /**
  * Decides what one source card's selection does on one target card. A viewer's

package/dist/types/lib/hooks/use-dashboard-card.d.ts

@@ -21,6 +21,7 @@ export declare function useCard(cardId: string): {
     resolvedPrimaryDateField: import('../types/semantic-runtime-types.js').ResolvedPrimaryDateField | undefined;
     effectiveCardConfig: import('../types/index.js').CardConfig | undefined;
     isCurrentQueryResult: boolean;
+    filterReach: import('../../shared/analytics-protocol/index.js').SemaphorFilterReachEntry[];
 };
 export declare function useDashboardCard(card: TCard): {
     isPending: boolean;
@@ -42,4 +43,5 @@ export declare function useDashboardCard(card: TCard): {
     resolvedPrimaryDateField: import('../types/semantic-runtime-types.js').ResolvedPrimaryDateField | undefined;
     effectiveCardConfig: import('../types/index.js').CardConfig | undefined;
     isCurrentQueryResult: boolean;
+    filterReach: import('../../shared/analytics-protocol/index.js').SemaphorFilterReachEntry[];
 };

package/dist/types/lib/matrix-table/matrix-delivery-policy.d.ts

@@ -31,4 +31,4 @@ export declare function matrixDeliveryOptions(allowDownload?: boolean, content?:
     formats: ("csv" | "xlsx" | "pdf" | "png")[];
 };
 /** Matrix delivery requires an effective capture, never resident cells. */
-export declare function resolveMatrixExportEngine(card: TCard | null | undefined, hasContext: boolean): "window" | "unavailable" | "ordinary";
+export declare function resolveMatrixExportEngine(card: TCard | null | undefined, hasContext: boolean): "unavailable" | "window" | "ordinary";

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/matrix-table/matrix-runtime-types.d.ts

@@ -1,4 +1,4 @@
-import { MatrixAxis, MatrixAxisPage, MatrixCellBlock, MatrixCoordinate, MatrixFailure, MatrixPageRequest, MatrixPath, MatrixPresentation, MatrixSpec, MatrixViewState, MatrixWindow, MatrixIndexedWindowOutcome, MatrixWindowRequest, OperationTemporalState, SemaphorScalarValue } from '../../shared/analytics-protocol/index.js';
+import { MatrixAxis, MatrixAxisPage, MatrixCellBlock, MatrixCoordinate, MatrixFailure, MatrixPageRequest, MatrixPath, MatrixPresentation, MatrixSpec, MatrixViewState, MatrixWindow, MatrixIndexedWindowOutcome, MatrixWindowRequest, OperationTemporalState, SemaphorScalarValue, SemaphorFilterReachEntry } from '../../shared/analytics-protocol/index.js';
 export type MatrixRuntimeError = {
     failure: MatrixFailure;
     retryKey: string | null;
@@ -124,6 +124,12 @@ export type MatrixDataset = {
      * or seeded dataset continues on the same instant.
      */
     temporalState?: OperationTemporalState;
+    /**
+     * The per-filter report its latest window returned (relationship filter
+     * reach RF-D13): a restored dataset shows rows without running a window, so
+     * its filter info reads the report saved with them (ledger R-03).
+     */
+    filterReach?: readonly SemaphorFilterReachEntry[];
 };
 /** What a mounted runtime exposes to History. */
 export type MatrixLiveView = {
@@ -208,6 +214,8 @@ export type MatrixWindowExecutor = (input: {
 /** A window outcome and the operation state the server ran it on. */
 export type MatrixWindowExecution = MatrixIndexedWindowOutcome & {
     temporalState?: OperationTemporalState;
+    /** The per-filter report for this window, as `/api/v1/query` returns it for other cards. */
+    filterReach?: SemaphorFilterReachEntry[];
 };
 export type MatrixRuntimeInput = {
     spec: MatrixSpec;

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

@@ -1,5 +1,5 @@
+import { SemaphorFilterReachEntry, MatrixAxis, MatrixCoordinate, MatrixPath, MatrixSort, MatrixViewState } from '../../shared/analytics-protocol/index.js';
 import { QueryClient } from '@tanstack/react-query';
-import { MatrixAxis, MatrixCoordinate, MatrixPath, MatrixSort, MatrixViewState } from '../../shared/analytics-protocol/index.js';
 import { MatrixCellAddress, MatrixCellState, MatrixDatasetRetention, MatrixRuntimeInput, MatrixRuntimeSnapshot, MatrixViewport, MatrixVisibleCoverage, MatrixWindowExecutor } from './matrix-runtime-types.js';
 /** Owns acquisition, errors, generation fencing and retention for exactly one card. */
 export declare class MatrixRuntimeController {
@@ -26,6 +26,8 @@ export declare class MatrixRuntimeController {
      * every page and expansion sends it, so they all run on one instant.
      */
     private temporalState?;
+    /** The latest window's per-filter report (relationship filter reach RF-D13). */
+    private filterReach;
     private error?;
     private notice?;
     private blockingFailures;
@@ -73,6 +75,8 @@ export declare class MatrixRuntimeController {
      * Value, null and empty cells are complete; unloaded and loading cells, axis
      * pages still loading, and queued or active work are not.
      */
+    /** Which filters the latest window's source applied, and why not, as the server reported it. */
+    readFilterReach: () => SemaphorFilterReachEntry[];
     readVisibleCoverage: () => MatrixVisibleCoverage;
     /** Used by explicit refresh/retry integrations; latest-issued response wins. */
     refetchCell: (coordinate: MatrixCoordinate) => void;

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

@@ -1,6 +1,7 @@
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
 import { NormalizedFilterDashboardInput, ResolvedDashboardInput, TCard } from '../types/common-types.js';
-import { DashboardFilterLogicalValueField, DashboardFilterTarget, DashboardFilterTargetField, DashboardFilterTargetSource, buildDashboardCardSourceIndex } from '../../shared/dashboard-authoring/index.js';
+import { DashboardFilterLogicalValueField, DashboardFilterFieldTarget, DashboardFilterTargetField, DashboardFilterTargetSource, buildDashboardCardSourceIndex } from '../../shared/dashboard-authoring/index.js';
+import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../../shared/analytics-protocol/index.js';
 import { Field } from '../types/explorer-types.js';
 export type DashboardFilterMappingSkipReason = 'outsideScope' | 'noSelection' | 'explicitlyExcluded' | 'notApplicable';
 export type DashboardFilterMappingBlockReason = 'ambiguousAutomaticTarget' | 'staleBinding' | 'invalidSelection' | 'incompatibleValueType' | 'unsupportedTarget';
@@ -35,7 +36,7 @@ export type DashboardFilterMappingResolution = {
  * use, so the server resolves both to the same table alias. Pass the card's
  * grounded executable source when validation returned one.
  */
-export declare function explorerFieldFromMappingTarget(target: DashboardFilterTarget, source?: DashboardFilterTargetField['source']): Field;
+export declare function explorerFieldFromMappingTarget(target: DashboardFilterFieldTarget, source?: DashboardFilterTargetField['source']): Field;
 /** Date and datetime are interchangeable; every other type must match exactly. */
 export declare function dashboardFilterDataTypesAreCompatible(sourceType: string, targetType: DashboardFilterTargetField['dataType']): boolean;
 /**
@@ -47,13 +48,7 @@ export declare function automaticTargetCandidates(params: {
     valueField: DashboardFilterLogicalValueField;
     valueSources: DashboardFilterTargetSource[];
     sourceIndex: ReturnType<typeof buildDashboardCardSourceIndex>;
-}): DashboardFilterTarget[];
-/**
- * The source-qualified fields whose values a toolbar filter holds. A filter
- * with an option source has exactly one; an ordinary filter has one per
- * source it is proven to address.
- */
-export declare function dashboardFilterInputValueFields(input: NormalizedFilterDashboardInput): DashboardFilterTargetField[];
+}): DashboardFilterFieldTarget[];
 export type DashboardFilterTargetValidation = {
     status: 'valid';
     /** The card's own copy of the source the target addresses. */
@@ -71,8 +66,152 @@ export type DashboardFilterTargetValidation = {
  */
 export declare function validateDashboardFilterTargetForCard(params: {
     sourceIndex: ReturnType<typeof buildDashboardCardSourceIndex>;
-    target: DashboardFilterTarget;
+    target: DashboardFilterFieldTarget;
 }): 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: DashboardFilterFieldTarget;
+    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: DashboardFilterFieldTarget;
+}
+/**
+ * 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';
+}
+/**
+ * The value's dataset is one the card's query doesn't use, in the card's
+ * semantic domain: the value is sent as it is and the server decides,
+ * through the domain's relationships, whether and how it reaches the card
+ * (relationship filter reach row 7r). The browser loads no relationships.
+ * With `route`, the author chose the relationships (a mapping `relationship`
+ * target, RF-D10): the value carries their ids and the server resolves
+ * exactly them or blocks the card.
+ */
+ | {
+    status: 'relationship';
+    route?: {
+        bindingId: string;
+        relationshipIds: string[];
+    };
+} | {
+    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'
+/**
+ * The server decides when the card runs, through the domain's
+ * relationships: it may apply the value or skip it with a reason. A reader
+ * never counts it as reached.
+ */
+ | 'relationship'
+/** A server-side resolver confirmed the route the card will apply (RF-D15). */
+ | 'relationshipApplied' | 'notApplicable';
+/** How a filter reaches a card, with the route or the reason a resolver gave (RF-D15). */
+export type DashboardFilterCardReachDetail = {
+    reach: DashboardFilterCardReach;
+    /** With 'relationshipApplied'. */
+    route?: SemaphorRelationshipRoute;
+    /** With 'notApplicable' from a resolver. */
+    reason?: SemaphorSkippedConstraintReason;
+    /** With reason 'relationship_ambiguous'. */
+    candidates?: SemaphorRelationshipRoute[];
+    /** With 'blocked' from a resolver. */
+    message?: string;
+    /**
+     * With 'automatic' from a resolver: a card the target decision sends to the
+     * server to place applies the value on data its query already uses, so no
+     * route is needed (ledger R-05).
+     */
+    kept?: true;
+};
+/**
+ * Supplied by semaphor-app to server-side readers (RF-D15). Synchronous: the
+ * app preloads each card's domain. In the browser readers have none and
+ * report `relationship` unresolved.
+ */
+export type DashboardRelationshipReachResolver = (query: {
+    card: TCard;
+    value: TFilterValue;
+}) => {
+    status: 'applied';
+    route: SemaphorRelationshipRoute;
+}
+/** The card's query already uses the value's dataset: it applies as any filter. */
+ | {
+    status: 'kept';
+} | {
+    status: 'skipped';
+    reason: SemaphorSkippedConstraintReason;
+    candidates?: SemaphorRelationshipRoute[];
+} | {
+    status: 'blocked';
+    message: string;
+};
+/**
+ * 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;
+/**
+ * `describeDashboardFilterCardReach` with the route or reason. With a
+ * resolver (server-side readers, RF-D15) a `relationship` card is resolved
+ * the way the card query resolves it: applied with its route, not applicable
+ * with the reason, or blocked. The value is the filter's own field, as the
+ * card would send it; no policy step depends on the operator.
+ */
+export declare function describeDashboardFilterCardReachDetail(input: NormalizedFilterDashboardInput, card: TCard, options?: {
+    relationshipReach?: DashboardRelationshipReachResolver;
+}): DashboardFilterCardReachDetail;
 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,92 @@ 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;
+    /**
+     * Whether the screen-size bar is open (responsive layouts RL-D21). Closed by
+     * default: the editor edits Desktop and the bar appears only when someone
+     * opens it. Closed on load and on entering or leaving edit mode.
+     */
+    screenSizesOpen: boolean;
     theme?: 'light' | 'dark' | 'system';
     themeStyle?: StyleProps;
     filteringCards?: TCard[];
@@ -70,6 +148,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 +359,26 @@ 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;
+    /**
+     * Opens or closes the screen-size bar (RL-D21). Opening in view mode starts a
+     * look-only preview at the size shown now; closing ends any preview and
+     * returns the editor to Desktop.
+     */
+    setScreenSizesOpen: (open: boolean) => 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 +386,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 +406,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 +420,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 +549,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;