react-semaphor 0.1.544 → 0.1.546

package/dist/types/shared/dashboard-authoring/filter-model/filter-values.d.ts

@@ -0,0 +1,58 @@
+import { TFilter, TFilterValue } from '../../../components/surfboard/filter/types.js';
+import { DashboardInputValues, NormalizedFilterDashboardInput, TDashboard } from '../../../lib/types/common-types.js';
+import { CalendarContext } from '../../report-runtime-context/index.js';
+import { DashboardInputRuntimeTarget } from '../../../lib/dashboard-inputs/dashboard-input-values.js';
+import { DashboardInputRuntimeValues } from '../../../lib/dashboard-inputs/resolve-dashboard-input-context.js';
+/**
+ * M5, the filter value adapters (one filter model SPEC 4.7): they move values
+ * between the old filter value list, keyed by `filterId`, and input slots.
+ * They decide no precedence.
+ */
+/** A host filter default: a full filter value, or the short `{ filterId, values }` embed form. */
+export type HostFilterValue = TFilterValue | {
+    readonly filterId: string;
+    readonly values: string[] | number[];
+};
+/**
+ * A host value as a filter value of this definition (today's hydration rule).
+ * The short embed form names no operation: it takes the filter's own, so the
+ * slot passes the input's validation (ledger P4a-03).
+ */
+export declare function hostFilterValueFor(filter: TFilter, hostValue: HostFilterValue, calendar: CalendarContext | null | undefined): TFilterValue;
+/**
+ * Host overlay in: each value goes to the input owning its `filterId`, as a
+ * runtime slot over saved defaults. A `shared` input gets one slot; a
+ * `perSheet` input gets one on every tab the input is on (a host default is
+ * dashboard-wide, as today). A value whose `filterId` owns no input, or
+ * whose input holds one value per card or section, is dropped and listed.
+ * The values that own no input are also returned as they were listed: the
+ * caller decides whether they are ad-hoc values (SPEC 5.8, 5.9).
+ */
+export declare function hostFilterValuesToSlots(dashboard: TDashboard, values: readonly HostFilterValue[] | undefined, options: {
+    calendar: CalendarContext | null | undefined;
+}): {
+    slots: DashboardInputValues;
+    adHocFilterValues: TFilterValue[];
+    droppedFilterIds: string[];
+};
+/**
+ * List out, tab-wide: each filter shown on this tab with its effective value
+ * (the inputs the tab-presence rule places on it, in model order, each
+ * through the hydration owner), followed by the tab's ad-hoc values. Inputs
+ * with no value, or cleared, are left out. Used by `onFilterValuesChange`,
+ * captures and every reader that reports a tab's filters.
+ */
+export declare function readFilterValueList(params: {
+    dashboard: TDashboard;
+    runtimeValues: Pick<DashboardInputRuntimeValues, 'dashboardInputValues'>;
+    adHocFilterValues: readonly TFilterValue[] | undefined;
+    sheetId: string | null | undefined;
+    sheetKind: 'dashboard' | 'document';
+    calendar: CalendarContext | null;
+}): TFilterValue[];
+/**
+ * Every runtime target a filter input holds a value at: one for a `shared`
+ * input, each tab it is on for `perSheet`, each card it reaches for
+ * `perCard`, each section it reaches for `perDocumentSection`.
+ */
+export declare function listFilterInputValueTargets(dashboard: TDashboard, input: NormalizedFilterDashboardInput): DashboardInputRuntimeTarget[];

package/dist/types/shared/dashboard-authoring/filter-model/index.d.ts

@@ -0,0 +1,7 @@
+export * from './read-dashboard-filter-model.js';
+export * from './toolbar-filter-reach.js';
+export { foldPrototypeDocumentInputs } from './prototype-document-inputs.js';
+export * from './filter-values.js';
+export * from './filter-definitions.js';
+export * from './ad-hoc-filter-values.js';
+export { upgradeToStoredDashboard } from './stored-dashboard.js';

package/dist/types/shared/dashboard-authoring/filter-model/prototype-document-inputs.d.ts

@@ -0,0 +1,15 @@
+import { DashboardInput, DocumentInputDefinition, TDashboard } from '../../../lib/types/common-types.js';
+/**
+ * The prototype Document input fold (one filter model SPEC 4.3 step 3), moved
+ * unchanged from `document-input-prototype-normalizer.ts`: inputs stored in
+ * `sheet.document.inputs` (the earliest Document shape) become Dashboard
+ * Inputs scoped to their tab, with variable names and control ids aligned as
+ * before. Returns the input dashboard when nothing changes.
+ */
+export declare function foldPrototypeDocumentInputs(dashboard: TDashboard): TDashboard;
+/** The ids of the prototype Document inputs the fold would add (not already stored). */
+export declare function listUnfoldedPrototypeDocumentInputs(dashboard: Pick<TDashboard, 'inputs' | 'sheets'>): Array<{
+    sheetId: string;
+    input: DocumentInputDefinition;
+}>;
+export declare function prototypeDocumentInputToDashboardInput(input: DocumentInputDefinition, sheetId: string): DashboardInput;

package/dist/types/shared/dashboard-authoring/filter-model/read-dashboard-filter-model.d.ts

@@ -0,0 +1,78 @@
+import { TFilter } from '../../../components/surfboard/filter/types.js';
+import { DashboardInputScope, DashboardInputValues, EmbeddedFilterDashboardInput, NormalizedFilterDashboardInput, TDashboard } from '../../../lib/types/common-types.js';
+import { DashboardFilterMappingContractIssue } from '../dashboard-filter-mapping-contract.js';
+import { DashboardCardLocation } from '../document-section-cards.js';
+/**
+ * The filter model (one filter model M1): every stored filter shape read as a
+ * filter input. One entry point, `readDashboardFilterModel`, used by the
+ * client runtime and by the server alike. Pure, never throws, memoized per
+ * dashboard object.
+ */
+/** A filter, by its filter id or by an input id (a legacy `compat-filter:` id included). */
+export type FilterRef = {
+    filterId: string;
+} | {
+    inputId: string;
+};
+export type FilterInputOrigin = 'embeddedInput' | 'referencedInput' | 'prototypeDocumentInput' | 'toolbarFilter';
+export type FilterInputEntry = {
+    /** What the runtime consumes; see the runtime view in SPEC 4.3. */
+    input: NormalizedFilterDashboardInput;
+    origin: FilterInputOrigin;
+};
+/** The shared card location plus its tab kind. */
+export type ReachedCard = DashboardCardLocation & {
+    sheetKind: 'dashboard' | 'document';
+};
+export type FilterModelIssueCode = 'contract' | 'duplicate_filter_owner' | 'compat_id_conflict' | 'duplicate_global_date';
+export type FilterModelIssue = {
+    code: FilterModelIssueCode;
+    /** A customer-safe sentence, in the style of the template validator's messages. */
+    message: string;
+    /** JSON path in the template that was read. */
+    path: string;
+    inputId?: string;
+    filterId?: string;
+    contractIssue?: DashboardFilterMappingContractIssue;
+};
+export type DashboardFilterModel = {
+    /** Accepted filter inputs: stored inputs in stored order, then prototype Document inputs, then toolbar filters. */
+    readonly inputs: readonly FilterInputEntry[];
+    readonly issues: readonly FilterModelIssue[];
+    /** Ids of stored inputs left out because of an issue. */
+    readonly rejectedInputIds: ReadonlySet<string>;
+    readonly globalDateInput: FilterInputEntry | undefined;
+    /** True when `toStoredDashboard()` would change anything. */
+    readonly needsUpgrade: boolean;
+    /** The saved defaults the runtime reads: stored `defaultInputValues` with owned `defaultFilterValues` entries moved in. */
+    readonly defaultInputValues: DashboardInputValues;
+    /**
+     * The variable name today's lift gives every toolbar filter, owned ones
+     * included, in filter order. Inputs named after toolbar filters (dashboard
+     * control compatibility inputs) are named against these, so their aliases
+     * stay what they are today (OF-INV-3).
+     */
+    readonly toolbarFilterVariableNames: readonly string[];
+    /** The owning entry. `{ inputId: 'compat-filter:x' }` resolves to the entry holding filter x, whatever its id. */
+    findFilterInput(ref: FilterRef): FilterInputEntry | undefined;
+    /** Card locations in dashboard order the input reaches (`options.scope` instead of its own when given). */
+    reachedCards(ref: FilterRef, options?: {
+        scope?: DashboardInputScope;
+    }): readonly ReachedCard[];
+    /** The template with every filter as an embedded input. The same object when `needsUpgrade` is false. Throws `FilterModelError` when `issues` is not empty. */
+    toStoredDashboard(): TDashboard;
+};
+export declare class FilterModelError extends Error {
+    readonly issues: readonly FilterModelIssue[];
+    constructor(issues: readonly FilterModelIssue[]);
+}
+/** One message for a persistence error: each issue's `message`, joined by "\n". */
+export declare function formatFilterModelIssues(issues: readonly FilterModelIssue[]): string;
+export declare function readDashboardFilterModel(dashboard: TDashboard): DashboardFilterModel;
+/**
+ * The input fields a toolbar filter's own fields give it (step 4), for a
+ * writer that creates or updates its input before Phase 5. The variable name
+ * is not among them: it depends on the dashboard's other inputs (use the
+ * model's entry).
+ */
+export declare function toolbarFilterInputFields(dashboard: Pick<TDashboard, 'sheets'>, filter: TFilter): Pick<EmbeddedFilterDashboardInput, 'label' | 'scope' | 'presentation' | 'exports'>;

package/dist/types/shared/dashboard-authoring/filter-model/stored-dashboard.d.ts

@@ -0,0 +1,18 @@
+import { TDashboard } from '../../../lib/types/common-types.js';
+/**
+ * A template in the stored shape (one filter model SPEC 5.1, 5.4): every
+ * filter an embedded input. The one upgrade, for the load
+ * (`prepareLoadedDashboard`) and every template write (the app's
+ * `prepareDashboardDocument`).
+ *
+ * The old shape's toolbar list also reserved names that compatibility
+ * aliases (dashboard controls, card controls, card inline filters) were
+ * allocated around; without it those aliases can change (`region3` becomes
+ * `region2`). So alias-based text is first bound to stable input ids against
+ * the template as read, then the model writes the stored shape (OF-INV-3,
+ * ledger P5-11).
+ *
+ * The same object when nothing needs upgrading. Throws `FilterModelError`
+ * when the model reports issues, as `toStoredDashboard()` does.
+ */
+export declare function upgradeToStoredDashboard(dashboard: TDashboard): TDashboard;

package/dist/types/shared/dashboard-authoring/filter-model/toolbar-filter-reach.d.ts

@@ -0,0 +1,23 @@
+import { TFilter } from '../../../components/surfboard/filter/types.js';
+import { DashboardInputScope, TDashboard } from '../../../lib/types/common-types.js';
+/**
+ * The reach conversion from a toolbar filter's own reach fields to a
+ * `DashboardInputScope` (one filter model SPEC 4.2), owned by the filter
+ * model. Since Phase 5 only the upgrade reads it: a stored filter has no
+ * reach fields, so nothing converts a scope back.
+ */
+/** The `TFilter` fields that store reach on the old shape. */
+export declare const TOOLBAR_FILTER_REACH_FIELDS: readonly ["sheetId", "applyToSheetIds", "excludeSheetIds", "applyToCardIds", "excludeCardIds"];
+export type ToolbarFilterReachField = (typeof TOOLBAR_FILTER_REACH_FIELDS)[number];
+/** Today's `doesFilterApplyToSheet`: does the toolbar filter reach this tab? */
+export declare function doesToolbarFilterReachTab(filter: TFilter, sheetId: string): boolean;
+/** Whether a toolbar filter stores any reach field. */
+export declare function hasToolbarFilterReachField(filter: TFilter): boolean;
+/** The filter without its reach fields (S-3). The same object when it has none. */
+export declare function withoutToolbarFilterReachFields(filter: TFilter): TFilter;
+/**
+ * Toolbar filter reach to scope (SPEC 4.2): the first matching row wins; for
+ * arrays "set" means `!== undefined`, for `sheetId` truthy; every id kept names
+ * an existing tab or card. Tab reach is the regular tabs the filter reaches.
+ */
+export declare function toolbarFilterScope(filter: TFilter, dashboard: Pick<TDashboard, 'sheets'>): DashboardInputScope;

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

@@ -2,9 +2,7 @@ export * from './contracts.js';
 export * from './comparison-document-migration.js';
 export * from './source-matching.js';
 export * from './validators.js';
-export * from './layout-compiler.js';
 export * from './artifact-compiler.js';
-export * from './change-compiler.js';
 export * from './protocol-adapter.js';
 export * from './temporal-result-owner.js';
 export * from './temporal-bucket-authoring.js';
@@ -16,6 +14,8 @@ export * from './dashboard-filter-automatic-target.js';
 export * from './dashboard-filter-sql-subscription.js';
 export * from './dashboard-filter-sql-target.js';
 export * from './dashboard-filter-mapping-contract.js';
+export * from './dashboard-input-scope.js';
+export * from './filter-model/index.js';
 export * from './dashboard-filter-value-compatibility.js';
 export * from './card-reference-remapping.js';
 export * from './apply-group-by-override.js';
@@ -37,3 +37,21 @@ export { matrixCatalogSources, matrixExecutionSources } from './matrix-control-s
 export * from './dashboard-option-dependencies.js';
 export * from './new-card.js';
 export * from './operations/apply-dashboard-operations.js';
+export * from './changes/card-types.js';
+export * from './changes/diagnostics.js';
+export * from './changes/card-query-part.js';
+export * from './changes/read-card-query.js';
+export * from './changes/dashboard-change.js';
+export * from './changes/resolve-dashboard-changes.js';
+export * from './outline/outline-filters.js';
+export * from './outline/outline-dashboard.js';
+export * from './column-catalog.js';
+export { prepareLoadedDashboard } from '../../lib/dashboard-inputs/prepare-loaded-dashboard.js';
+export { buildFilterInputFromField, buildFilterInputFromDefinition, applyFilterSettingsChange } from '../../lib/dashboard-inputs/filter-settings.js';
+export type { FilterSettingsChange, FilterValueEffect } from '../../lib/dashboard-inputs/filter-settings.js';
+export { describeDashboardFilterCardReach, type DashboardFilterCardReach } from '../../lib/query-context/dashboard-filter-mapping-resolution.js';
+export { changeCardType, sharedCardPreferences, type CardTypeChange, type CardTypeChangeOptions, } from '../../lib/utils/card-type-change.js';
+export { buildSavedEditorCard } from '../../lib/utils/build-saved-editor-card.js';
+export { getCardDefinition, type AuthoredCardFields } from '../../lib/utils/card-definition.js';
+export { changeMatrixEditor, dropMatrixEditorField, matrixEditorCatalogFromFields, } from '../../lib/matrix-table/matrix-editor.js';
+export * from './filter-applicability.js';

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;