react-semaphor 0.1.532 → 0.1.534

package/dist/types/lib/dashboard-viewer/viewer-state.d.ts

@@ -0,0 +1,212 @@
+import { DashboardInputValues, TDashboard } from '../types/common-types.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DefaultsCalendar } from '../utils/filter-default-value-utils.js';
+import { ViewerTableSettings } from '../../shared/dashboard-viewer/table-settings.js';
+import { Bookmark, BookmarkState } from '../../shared/dashboard-viewer/viewer-contract.js';
+/** The report runtime's calendar, as filter defaults read it. */
+export type ViewerCalendar = DefaultsCalendar;
+/** 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[];
+};
+/** Host app defaults, exactly as hydration receives them today (embed props). */
+export type HostDefaults = {
+    readonly filterValues?: readonly HostFilterValue[];
+    readonly controlValues?: Readonly<Record<string, unknown>>;
+    /** The host's sheet prop: the sheet the dashboard opens on when valid. */
+    readonly selectedSheetId?: string;
+};
+export type ViewerBaseline = {
+    readonly filterValues: readonly TFilterValue[];
+    /** Passed to `setDashboardWithFilterValues` as `runtimeOverrides`. */
+    readonly controlOverrides: Readonly<Record<string, unknown>> | undefined;
+    /** The host's sheet when valid, else the author's first sheet. */
+    readonly selectedSheetId: string | null;
+    /** The host's sheet prop as given; a refetch compares it, not the resolved sheet. */
+    readonly hostSelectedSheetId: string | null;
+    /** Every applicable input's baseline slot, materialized. Used by capture and compare. */
+    readonly materializedInputs: DashboardInputValues;
+};
+/** The viewer-owned part of the current view. */
+export type ViewerSnapshot = {
+    readonly selectedSheetId: string | null;
+    /** Every applicable input's current slot, materialized like the baseline, including click selection slots. */
+    readonly inputs: DashboardInputValues;
+    readonly tableSettings: Readonly<Record<string, ViewerTableSettings>>;
+};
+export type ViewerNotice = {
+    readonly kind: 'setting-no-longer-applies';
+    readonly target: 'input' | 'selection' | 'sheet' | 'card';
+    readonly id: string;
+    /** `invalid`: the saved part could not be read. */
+    readonly reason: 'removed' | 'incompatible' | 'not-eligible' | 'invalid';
+};
+export type RememberedSettingsWrite = {
+    readonly kind: 'set';
+    readonly cardId: string;
+    readonly settings: ViewerTableSettings;
+} | {
+    readonly kind: 'clear';
+    readonly cardId: string;
+} | {
+    readonly kind: 'clear-all';
+};
+/** The store values a view consists of. */
+export type ViewerValues = {
+    readonly filterValues: readonly TFilterValue[];
+    readonly controlOverrides: Readonly<Record<string, unknown>> | undefined;
+    /** Runtime input slots: a bookmark's slots only (overlay). Never completed as `cleared`. */
+    readonly dashboardInputValues: DashboardInputValues;
+    /** Card inline filter values when they differ from the cards' defaults. Absent: the defaults. */
+    readonly inlineFilterValuesMap?: Readonly<Record<string, readonly TFilterValue[]>>;
+    readonly selectedSheetId: string | null;
+    readonly tableSettings: Readonly<Record<string, ViewerTableSettings>>;
+};
+/**
+ * The result of a viewer event: the values to write now, plus the view it
+ * opened. Built by `applyViewerState`; `markViewerSaved` (a completed save)
+ * and `rebaseOnHostControls` (new host control defaults) adjust one.
+ */
+export type AppliedViewerState = ViewerValues & {
+    readonly appliedBookmarkId: string | null;
+    /** Remembered-settings writes this event implies (sent only with read-write access, never in print mode). */
+    readonly rememberedWrites: readonly RememberedSettingsWrite[];
+    /** The view right after opening; "changed" compares against it. */
+    readonly opened: ViewerSnapshot;
+    /** What Discard writes back: the values the view opened with. A refetch carries it forward. */
+    readonly restore: ViewerValues;
+    readonly notices: readonly ViewerNotice[];
+};
+/** The view at one moment, taken before an async save: what was submitted, and how to restore it. */
+export type ViewerCapture = {
+    readonly snapshot: ViewerSnapshot;
+    readonly values: ViewerValues;
+};
+/** The live store state a refetch preserves. */
+export type ViewerLiveState = {
+    /** The template the live state was built against. */
+    readonly previousDashboard: TDashboard;
+    /** The baseline of the previous hydration; a changed host prop wins over the live value. */
+    readonly previousBaseline: ViewerBaseline | null;
+    readonly filterValues: readonly TFilterValue[];
+    /**
+     * Live control values, flattened. `undefined` when the control contract
+     * changed: the baseline's control defaults apply again.
+     */
+    readonly controlValues: Readonly<Record<string, unknown>> | undefined;
+    /** Live runtime input slots (not materialized). */
+    readonly dashboardInputValues: DashboardInputValues;
+    /** Live card inline filter values. */
+    readonly inlineFilterValuesMap: Readonly<Record<string, readonly TFilterValue[] | undefined>>;
+    readonly selectedSheetId: string | null;
+    /** Live table settings (edits may still be queued; the server's are ignored). */
+    readonly tableSettings: Readonly<Record<string, ViewerTableSettings>>;
+    readonly applied: AppliedViewerState | null;
+};
+export type ViewerEvent = 
+/**
+ * First hydration, or the dashboard id or viewer identity changed.
+ * `captured`: the table settings are a capture (a PDF render), which keeps
+ * a sort on a table with customization off (PLAN B30).
+ */
+{
+    readonly kind: 'initial-load';
+    readonly defaultBookmark?: Bookmark;
+    readonly captured?: boolean;
+}
+/** Same dashboard, same viewer: keep compatible live state; never re-apply the default. */
+ | {
+    readonly kind: 'refetch';
+    readonly live: ViewerLiveState;
+} | {
+    readonly kind: 'open-bookmark';
+    readonly bookmark: Bookmark;
+} | {
+    readonly kind: 'open-default-view';
+} | {
+    readonly kind: 'reset-to-default-view';
+} | {
+    readonly kind: 'discard-changes';
+    readonly applied: AppliedViewerState;
+};
+/** What the dashboard shows with no bookmark: the author's defaults, then the host's (TECH-SPEC 6.1). */
+export declare function resolveViewerBaseline(input: {
+    readonly dashboard: TDashboard;
+    readonly host: HostDefaults;
+    readonly calendar?: ViewerCalendar;
+    /** False skips `materializedInputs` (left empty) when nothing captures or compares, as in a PDF render. */
+    readonly materializeInputs?: boolean;
+}): ViewerBaseline;
+/**
+ * For a click selection's input id: whether its slot still applies (the source
+ * visual exists and still filters other visuals when clicked). `undefined`
+ * for any other input.
+ */
+export declare function selectionApplies(dashboard: TDashboard, inputId: string): 'applies' | 'removed' | 'not-eligible' | undefined;
+/** Whether the dashboard still defines this input (for a selection: whether it still applies). */
+export declare function hasDashboardInput(dashboard: TDashboard, inputId: string): boolean;
+export type ApplyViewerStateInput = {
+    readonly dashboard: TDashboard;
+    readonly baseline: ViewerBaseline;
+    /** On `initial-load`: the server's settings (or the PDF prop). Otherwise: the store's live settings. */
+    readonly rememberedTableSettings: Readonly<Record<string, ViewerTableSettings>>;
+    readonly event: ViewerEvent;
+    /** The report calendar, for materializing the opened view. */
+    readonly calendar?: ViewerCalendar;
+};
+/** The only code that combines baseline, bookmark and remembered settings (section 6.2). Pure. */
+export declare function applyViewerState(input: ApplyViewerStateInput): AppliedViewerState;
+/**
+ * The host changed its control defaults mid-visit (TECH-SPEC 6.2). Only
+ * controls move: the baseline takes the host's new values; the controls
+ * become them, with the applied bookmark's own control values over them, as
+ * opening it would; the restore point and opened view follow, so the change
+ * is not the viewer's. Filters, inputs, sheet and columns stay as they are.
+ * Pure.
+ */
+export declare function rebaseOnHostControls(input: {
+    readonly dashboard: TDashboard;
+    readonly baseline: ViewerBaseline;
+    readonly hostControlValues: Readonly<Record<string, unknown>> | undefined;
+    readonly applied: AppliedViewerState | null;
+    readonly appliedBookmark: Bookmark | null;
+    readonly calendar?: ViewerCalendar;
+}): {
+    readonly baseline: ViewerBaseline;
+    readonly controlOverrides: Readonly<Record<string, unknown>> | undefined;
+    readonly applied: AppliedViewerState | null;
+};
+/**
+ * After a save or update completes: the bookmark is the applied one, and the
+ * view captured when the viewer clicked Save is its opened view and restore
+ * point. Edits made while it saved stay on screen and show as changes. Pure.
+ */
+export declare function markViewerSaved(previous: AppliedViewerState, bookmarkId: string, capture: ViewerCapture): AppliedViewerState;
+/** The bookmark state to save: the current snapshot minus the baseline (section 6.3). Pure. */
+export declare function captureViewerState(input: {
+    readonly dashboard: TDashboard;
+    readonly baseline: ViewerBaseline;
+    readonly current: ViewerSnapshot;
+}): BookmarkState;
+export type ViewerChange = {
+    readonly target: 'input';
+    readonly inputId: string;
+    readonly label: string;
+} | {
+    readonly target: 'sheet';
+} | {
+    readonly target: 'table';
+    readonly cardId: string;
+    readonly cardTitle: string;
+};
+/** Every input's label, by input id. */
+export declare function listInputLabels(dashboard: TDashboard): Map<string, string>;
+/** An input's label; a click selection is named by the visual it came from. */
+export declare function labelForInput(dashboard: TDashboard, labels: ReadonlyMap<string, string>, inputId: string): string;
+/** What changed since the view opened: the dot, its tooltip, and whether Update is offered. */
+export declare function compareViewerState(input: {
+    readonly dashboard: TDashboard;
+    readonly opened: ViewerSnapshot;
+    readonly current: ViewerSnapshot;
+}): readonly ViewerChange[];

package/dist/types/lib/dashboard-viewer/viewer-store-state.d.ts

@@ -0,0 +1,44 @@
+import { AppliedViewerState, ViewerBaseline, ViewerNotice } from './viewer-state.js';
+import { Bookmark, DashboardViewerPayload, ViewerAccessMode, ViewerAccessReason, ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
+/**
+ * One viewer's personal layer on the dashboard (dashboard bookmarks). Nothing
+ * here is ever written into the template, `card.config` or `tablePrefs`.
+ */
+export type DashboardViewerState = {
+    readonly access: ViewerAccessMode;
+    readonly accessReason?: ViewerAccessReason;
+    /** True when the `viewerTableSettings` prop is present (PDF render): no writes, no bookmark UI. */
+    readonly printMode: boolean;
+    /** Who TEAM means and whether the viewer can publish dashboard views; absent for session-only access. */
+    readonly sharing?: DashboardViewerPayload['sharing'];
+    readonly baseline: ViewerBaseline | null;
+    readonly applied: AppliedViewerState | null;
+    /** The bookmark the view was opened from; `null` = the default view. */
+    readonly appliedBookmark: Bookmark | null;
+    /** Live table settings per card. Never written into `card.config` or `tablePrefs`. */
+    readonly tableSettings: Readonly<Record<string, ViewerTableSettings>>;
+    readonly notices: readonly ViewerNotice[];
+};
+/** Session-only until the dashboard load says otherwise (TECH-SPEC 7). */
+export declare const INITIAL_DASHBOARD_VIEWER_STATE: DashboardViewerState;
+type ViewerGateState = {
+    readonly viewer: DashboardViewerState;
+    readonly isDashboardEditing: boolean;
+};
+/**
+ * Whether the bookmark UI shows: a viewer whose state loaded, outside print
+ * mode and dashboard editing. The one rule for the view control, the notice
+ * bar and the bookmark hook.
+ */
+export declare function selectIsViewerUiAvailable(state: ViewerGateState & {
+    readonly viewerStateClient: unknown;
+}): boolean;
+/**
+ * The table settings that shape dashboard queries and tables right now. While
+ * the dashboard is being edited, the author sees the authored table. The
+ * visual editor's preview is gated by its own caller (`useIsEditorPreview`,
+ * the card execution's input source).
+ */
+export declare function selectActiveViewerTableSettings(state: ViewerGateState): Readonly<Record<string, ViewerTableSettings>>;
+export declare function selectActiveViewerTableSettingsForCard(state: ViewerGateState, cardId: string): ViewerTableSettings | undefined;
+export {};

package/dist/types/lib/download-pdf.d.ts

@@ -1,3 +1,4 @@
+import { ViewerTableSettings } from '../shared/dashboard-viewer/index.js';
 import { TFilterValue } from '../components/surfboard/filter/types.js';
 import { AuthToken, ControlBinding, ControlDefinition, DashboardInputExecutionSnapshot, DocumentInputRuntimeValues } from './types/common-types.js';
 import { TChartType } from './charts/types.js';
@@ -7,6 +8,8 @@ import { PrintInputCapture } from './print/print-inputs.js';
 import { buildMatrixDeliveryPayload } from './matrix-table/matrix-delivery.js';
 export type MatrixPdfCapture = ReturnType<typeof buildMatrixDeliveryPayload>;
 export type DashboardParams = {
+    /** The viewer's table settings captured at the click (PLAN B20). */
+    viewerTableSettings?: Readonly<Record<string, ViewerTableSettings>>;
     authToken: AuthToken;
     theme: string;
     filterValues: TFilterValue[];
@@ -23,6 +26,8 @@ export type DashboardParams = {
     timezone?: string;
 };
 export type VisualPdfParams = {
+    /** The viewer's table settings captured at the click (PLAN B20). */
+    viewerTableSettings?: Readonly<Record<string, ViewerTableSettings>>;
     authToken: AuthToken;
     theme: string;
     filterValues: TFilterValue[];
@@ -41,6 +46,8 @@ export type VisualPdfParams = {
 };
 type VisualPrintRuntimeOverrides = {
     filterValues?: TFilterValue[];
+    /** Replaces the store's viewer table settings (`{}` where the authored table applies, such as the editor preview). */
+    viewerTableSettings?: Readonly<Record<string, ViewerTableSettings>>;
 };
 export type LayoutApplied = {
     requestedPageSize?: string;
@@ -84,7 +91,8 @@ export declare function downloadDocumentPdf(apiServiceUrl: string, authToken: Au
 }): Promise<void>;
 export declare function getVisualParamsForPrint(authToken: AuthToken | undefined, cardId: string, frameId: string, cardTitle: string, overrides?: VisualPrintRuntimeOverrides): VisualPdfParams;
 export declare function downloadVisualPdf(apiServiceUrl: string, authToken: AuthToken | undefined, cardId: string, frameId: string, cardTitle: string, cardChartType?: TChartType, password?: string, pageSize?: string, orientation?: string, filterLine?: string, filterValues?: TFilterValue[], expandedState?: Record<string, boolean>, matrix?: MatrixPdfCapture): Promise<void>;
-export declare function downloadVisualPdfWithResponse(apiServiceUrl: string, authToken: AuthToken | undefined, cardId: string, frameId: string, cardTitle: string, cardChartType?: TChartType, password?: string, pageSize?: string, orientation?: string, filterLine?: string, filterValues?: TFilterValue[], expandedState?: Record<string, boolean>, matrix?: MatrixPdfCapture): Promise<PdfDownloadResponse | undefined>;
+/** `captured`: the print parameters taken at the click (`getVisualParamsForPrint`), for a fallback after an await. */
+export declare function downloadVisualPdfWithResponse(apiServiceUrl: string, authToken: AuthToken | undefined, cardId: string, frameId: string, cardTitle: string, cardChartType?: TChartType, password?: string, pageSize?: string, orientation?: string, filterLine?: string, filterValues?: TFilterValue[], expandedState?: Record<string, boolean>, matrix?: MatrixPdfCapture, captured?: VisualPdfParams): Promise<PdfDownloadResponse | undefined>;
 type FastPathOptions = {
     password?: string;
     pageSize?: string;

package/dist/types/lib/exports/bounded-request.d.ts

@@ -0,0 +1,12 @@
+/**
+ * One export status, list or download-link request never waits longer than
+ * this (hotspot H-06: every wait that decides something is bounded). A
+ * timed-out request counts as failed, and its fetch is aborted.
+ */
+export declare const EXPORT_STATUS_TIMEOUT_MS = 15000;
+/**
+ * Rejects when `work` outlasts `EXPORT_STATUS_TIMEOUT_MS`, and aborts its
+ * request. `work` must pass `signal` to its fetch, or the timeout releases the
+ * caller while the request stays open (a static test checks every caller).
+ */
+export declare function boundedRequest<T>(work: (signal: AbortSignal) => Promise<T>): Promise<T>;

package/dist/types/lib/hooks/index.d.ts

@@ -5,10 +5,9 @@ import { useAddNewFrame } from './use-add-new-frame.js';
 import { useDebounce } from './use-debounce.js';
 import { useDebouncedEditorValue } from './use-debounced-editor-value.js';
 import { useClickOutside } from './use-click-outside.js';
-import { useDefaultSheetPreference } from './use-default-sheet-preference.js';
 import { useStableValue, rowsEqual } from './use-stable-value.js';
 import { useExportPolling } from './use-export-polling.js';
 import { useExportRecovery } from './use-export-recovery.js';
 import { useCalendarContext, useResolvedDateStyle, useResolvedDateTimeDateStyle, useResolvedDateTimeTimeStyle, useResolvedDefaultCurrency, useResolvedValueFormatLocale, useReportPreferenceSources, useResolvedValueFormatPreferences, useTimezone, useWeekStart } from './use-calendar-context.js';
 import { useValueFormatPreferences } from './use-value-format-preferences.js';
-export { useDashboard, useCard, useDataColumns, useAddNewFrame, useDebounce, useDebouncedEditorValue, useClickOutside, useDefaultSheetPreference, useStableValue, rowsEqual, useExportPolling, useExportRecovery, useCalendarContext, useResolvedDateStyle, useResolvedDateTimeDateStyle, useResolvedDateTimeTimeStyle, useResolvedDefaultCurrency, useResolvedValueFormatLocale, useReportPreferenceSources, useResolvedValueFormatPreferences, useTimezone, useWeekStart, useValueFormatPreferences, };
+export { useDashboard, useCard, useDataColumns, useAddNewFrame, useDebounce, useDebouncedEditorValue, useClickOutside, useStableValue, rowsEqual, useExportPolling, useExportRecovery, useCalendarContext, useResolvedDateStyle, useResolvedDateTimeDateStyle, useResolvedDateTimeTimeStyle, useResolvedDefaultCurrency, useResolvedValueFormatLocale, useReportPreferenceSources, useResolvedValueFormatPreferences, useTimezone, useWeekStart, useValueFormatPreferences, };

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

@@ -5,6 +5,7 @@ export declare function useDashboardQuery(): {
         assistantProfileId?: string;
         semanticExecutionPayload: import('../types/semantic-runtime-types.js').SemanticExecutionPayload;
         organizationAppearance?: import('../types/index.js').AppearanceSpec | null;
+        viewer?: import('../types/index.js').DashboardViewerPayload;
     } | null | undefined;
     isLoading: boolean;
     isFetching: boolean;
@@ -15,6 +16,7 @@ export declare function useDashboardQuery(): {
         assistantProfileId?: string;
         semanticExecutionPayload: import('../types/semantic-runtime-types.js').SemanticExecutionPayload;
         organizationAppearance?: import('../types/index.js').AppearanceSpec | null;
+        viewer?: import('../types/index.js').DashboardViewerPayload;
     } | null, Error>>;
     dashboardIdToFetch: string | null;
 };

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

@@ -1,6 +1,7 @@
 import { AuthToken, ControlBinding, ControlDefinition, CustomCard, DashboardLifecycleEvent, DashboardInputExecutionSnapshot, TDashboard, TEvent, TStyle } from '../types/common-types.js';
 import { PresentationExecutionSnapshot } from '../../shared/format-utils/index.js';
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
 type UseDashboardProps = {
     id?: string;
     version?: string;
@@ -19,6 +20,8 @@ type UseDashboardProps = {
     /** Untrusted per-sheet input capture of a Full dashboard PDF; see resolvePrintInputs. */
     printInputCapture?: unknown;
     presentationExecutionSnapshot?: PresentationExecutionSnapshot;
+    /** PDF render: the viewer's table settings captured at export time. Nothing is read or written. */
+    viewerTableSettings?: Readonly<Record<string, ViewerTableSettings>>;
     customStyle?: TStyle;
     currentTheme?: 'light' | 'dark' | 'system';
     onSave?: (dashboard: TDashboard) => void;
@@ -30,7 +33,7 @@ type UseDashboardProps = {
     type?: 'dashboard' | 'visual';
     cardId?: string;
 };
-export declare function useDashboard({ customStyle, currentTheme, onSave, onEvent, onDashboardLifecycleEvent, defaultFilterValues, defaultControlValues, controlContractOverrides, dashboardInputExecutionSnapshot, printInputCapture, presentationExecutionSnapshot, type, cardId, selectedSheetId, onFilterValuesChange, }: UseDashboardProps): {
+export declare function useDashboard({ customStyle, currentTheme, onSave, onEvent, onDashboardLifecycleEvent, defaultFilterValues, defaultControlValues, controlContractOverrides, dashboardInputExecutionSnapshot, printInputCapture, presentationExecutionSnapshot, viewerTableSettings, type, cardId, selectedSheetId, onFilterValuesChange, }: UseDashboardProps): {
     isFetching: boolean;
     isLoading: boolean;
     isError: boolean;
@@ -40,6 +43,7 @@ export declare function useDashboard({ customStyle, currentTheme, onSave, onEven
         assistantProfileId?: string;
         semanticExecutionPayload: import('../types/semantic-runtime-types.js').SemanticExecutionPayload;
         organizationAppearance?: import('../appearance/types.js').AppearanceSpec | null;
+        viewer?: import('../../shared/dashboard-viewer/index.js').DashboardViewerPayload;
     } | null, Error>>;
 };
 export {};

package/dist/types/lib/hooks/use-date-filter.d.ts

@@ -1,4 +1,4 @@
-import { TFilter, TFilterValue, RelativeDateFilter, DateComparisonOperation, FilterStorageOptions, TemporalPrecision } from '../../components/surfboard/filter/types.js';
+import { TFilter, TFilterValue, RelativeDateFilter, DateComparisonOperation, FilterStorageOptions, RelativeDateChangeOptions, TemporalPrecision } from '../../components/surfboard/filter/types.js';
 import { DateRange } from 'react-day-picker';
 type UseDateFilterOptions = FilterStorageOptions;
 type DateFilterChangeOptions = {
@@ -15,7 +15,7 @@ export declare function useDateFilterHook(filterId: string): {
     handleClear: () => void;
     handleChange: (date: DateRange | undefined, operation?: DateComparisonOperation, options?: DateFilterChangeOptions) => void;
     handleNullOperation: (operation: "is null" | "is not null") => void;
-    handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: DateFilterChangeOptions) => void;
+    handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: RelativeDateChangeOptions) => void;
     handleReset: () => void;
 };
 export declare function useDateFilter(filter: TFilter, options?: UseDateFilterOptions): {
@@ -30,7 +30,7 @@ export declare function useDateFilter(filter: TFilter, options?: UseDateFilterOp
     handleClear: () => void;
     handleChange: (date: DateRange | undefined, operation?: DateComparisonOperation, options?: DateFilterChangeOptions) => void;
     handleNullOperation: (operation: "is null" | "is not null") => void;
-    handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: DateFilterChangeOptions) => void;
+    handleRelativeChange: (date: DateRange | undefined, relativeMeta: RelativeDateFilter, options?: RelativeDateChangeOptions) => void;
     handleReset: () => void;
 };
 export {};

package/dist/types/lib/hooks/use-export-polling.d.ts

@@ -1,3 +1,10 @@
+import { EXPORT_STATUS_TIMEOUT_MS } from '../exports/bounded-request.js';
+/**
+ * The browser follows the server (MX-D9): it gives up on an export this long
+ * after the server's `deadlineAt`, by which the server has settled the export.
+ */
+export declare const EXPORT_POLL_GRACE_MS: number;
+export { EXPORT_STATUS_TIMEOUT_MS };
 /**
  * Hook that manages smart polling for export status updates.
  *
@@ -20,5 +27,6 @@ export declare const POLLING_INTERVALS: {
     LONG: number;
     MEDIUM_THRESHOLD: number;
     LONG_THRESHOLD: number;
-    MAX_POLLING_DURATION: number;
+    EXPORT_POLL_GRACE_MS: number;
+    FALLBACK_POLLING_DURATION: number;
 };

package/dist/types/lib/query-context/build-card-query-context.d.ts

@@ -8,6 +8,7 @@ import { CardViewState } from '../dashboard-view-state/index.js';
 import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
 import { DashboardCardFilterCompilationInput } from './compile-dashboard-card-filters.js';
 import { ResolvedCardDateFields } from './resolve-card-primary-date-field.js';
+import { ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
 export type BuildCardQueryContextParams = {
     card: TCard;
     dashboard: Pick<TDashboard, 'sheets'>;
@@ -25,6 +26,13 @@ export type BuildCardQueryContextParams = {
      * query the card at its top level while the viewer sees it drilled.
      */
     cardViewState: CardViewState | undefined;
+    /**
+     * This card's viewer table settings (dashboard bookmarks): a viewer's sort
+     * goes into the query through `effectiveTableConfig`. Required so that every
+     * caller decides; a caller that leaves it out would query with the author's
+     * sort while the viewer sees their own.
+     */
+    viewerTableSettings: ViewerTableSettings | undefined;
     filters: TFilter[] | undefined;
     filterValues: TFilterValue[] | undefined;
     selectedSheetId: string | null | undefined;
@@ -57,4 +65,4 @@ export type CompiledCardQueryContext = Omit<CardQueryContext, 'filterCompilation
     globalDateComparisonSelection?: GlobalDateComparisonSelection;
     dateComparisonInputs?: ResolvedDashboardDateComparisonInput[];
 };
-export declare function buildCardQueryContext({ card, dashboard, transientContexts, cardViewState, filters, filterValues, selectedSheetId, inlineFilterValuesMap, dashboardControls, dashboardControlValues, cardControlValuesMap, dashboardInputContext, includeAuthoredFilters, }: BuildCardQueryContextParams): CardQueryContext;
+export declare function buildCardQueryContext({ card, dashboard, transientContexts, cardViewState, viewerTableSettings, filters, filterValues, selectedSheetId, inlineFilterValuesMap, dashboardControls, dashboardControlValues, cardControlValuesMap, dashboardInputContext, includeAuthoredFilters, }: BuildCardQueryContextParams): CardQueryContext;

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

@@ -1,3 +1,9 @@
+import { ViewerBaseline, ViewerCapture, ViewerEvent } from '../dashboard-viewer/viewer-state.js';
+import { TableColumnEdit, TableView } from '../dashboard-viewer/table-view.js';
+import { TableColumnEditResult } from '../dashboard-viewer/table-view-edit.js';
+import { Bookmark } from '../../shared/dashboard-viewer/index.js';
+import { DashboardViewerState } from '../dashboard-viewer/viewer-store-state.js';
+import { ViewerStateClient } from '../dashboard-viewer/viewer-state-client.js';
 import { AuthToken, TBaseQuery, Breakpoint, ControlDefinition, CustomCard, StyleProps, TCard, TDashboard, TEvent, TFrame, TSheet, TStyle, AIScopeTable, CacheConfig, FilterLayoutSettings, DocumentDefinition, DashboardInput, DashboardInputSlot, DashboardInputValues, DashboardLifecycleEvent } from '../types/common-types.js';
 import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
 import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
@@ -101,6 +107,13 @@ export type DashboardStore = {
     cardViewState: CardViewStateMap;
     /** Session-only server pagination, attached to the query identity that owns each page. */
     dashboardCardPagination: Record<string, DashboardCardPaginationState>;
+    /**
+     * One viewer's personal layer (dashboard bookmarks): table settings, the
+     * applied bookmark, notices. Never written into the template.
+     */
+    viewer: DashboardViewerState;
+    /** Saves `viewer` for read-write access; one per mounted dashboard, owned by `useDashboard`. */
+    viewerStateClient: ViewerStateClient | null;
     /**
      * When the replayed input snapshot was generated, for a document's
      * "Generated at" text only. Queries never read it: a print render's
@@ -224,8 +237,16 @@ type Actions = {
         authToken?: AuthToken;
         /** Present (even as undefined) on every PDF-aware hydration; replaces the previous value. */
         missingPrintInputs?: MissingPrintInputs;
+        /** The viewer layer for this hydration, written in the same store update. */
+        viewer?: DashboardViewerState;
     }) => void;
-    hydrateRuntimeControlValues: (dashboard: TDashboard, runtimeOverrides?: Record<string, unknown>) => void;
+    /**
+     * The host's control defaults changed for the dashboard on screen: writes
+     * only the controls and, for a viewer, the baseline and restore point
+     * (`rebaseOnHostControls`). Never re-sets the dashboard, so an author's
+     * unsaved edits stay. Returns the new baseline, or `null` without one.
+     */
+    hydrateRuntimeControlValues: (dashboard: TDashboard, runtimeOverrides?: Record<string, unknown>) => ViewerBaseline | null;
     mergeSemanticExecutionPayload: (semanticExecutionPayload: SemanticExecutionPayload) => void;
     setDashboardTheme: (theme: 'light' | 'dark' | 'system') => void;
     setDashboardTitle: (title: string) => void;
@@ -366,6 +387,60 @@ type Actions = {
     openInsightRequest: (request: InsightRenderRequest) => void;
     closeInsightRequest: (sourceCardId: string) => void;
     closeAllInsightRequests: () => void;
+    /**
+     * A viewer's column edit: runs `computeTableColumnEdit`, updates
+     * `viewer.tableSettings[cardId]` and queues the save when access allows
+     * and the author left customization on (otherwise only a sort applies, for
+     * the visit). Never touches `card.config`, `tablePrefs` or the template.
+     */
+    editTableSettings: (cardId: string, view: TableView, edit: TableColumnEdit) => TableColumnEditResult['status'];
+    setViewerStateClient: (client: ViewerStateClient | null) => void;
+    /**
+     * Runs `applyViewerState` for a viewer event after load (open a bookmark,
+     * the default view, discard, reset), writes the result and queues its
+     * remembered-settings writes when access allows. Load and refetch go
+     * through `setDashboardWithFilterValues` instead.
+     */
+    applyViewerEvent: (event: Exclude<ViewerEvent, {
+        kind: 'initial-load';
+    } | {
+        kind: 'refetch';
+    }>) => void;
+    /**
+     * Fetches a bookmark and opens it, unless it went stale while loading: a
+     * newer open, any other viewer event (default view, reset, discard) or a
+     * different viewer or dashboard (another client) wins. Rejects only when
+     * the current request fails.
+     */
+    openBookmark: (bookmarkId: string) => Promise<'applied' | 'stale'>;
+    /** Captured before an async bookmark write; see `markBookmarkApplied`. */
+    beginViewerRequest: () => ViewerRequestToken;
+    /**
+     * After a save or update: this bookmark is now the applied one, and the view
+     * captured at the click is its opened view and restore point (`markViewerSaved`);
+     * edits made while it saved show as changes. Ignored when the token went
+     * stale: a newer open or save started, a viewer event, a new restore point
+     * (a hydration or new host control defaults) or another viewer since it
+     * was taken.
+     */
+    markBookmarkApplied: (bookmark: Bookmark, since: ViewerRequestToken, capture: ViewerCapture) => void;
+    /**
+     * A bookmark was deleted: if it is still the applied one, the view keeps its
+     * values and restore point but no longer names it. Checked against the store
+     * when the delete completes, so a bookmark opened meanwhile stays applied.
+     */
+    forgetBookmark: (bookmarkId: string) => void;
+    /** A rename of the applied bookmark: its name and revision move, its opened state stays. */
+    replaceAppliedBookmark: (bookmark: Bookmark) => void;
+    dismissViewerNotices: () => void;
+};
+/** Taken before an async viewer request; see `isViewerRequestCurrent`. */
+export type ViewerRequestToken = {
+    /** This request's place among viewer requests (opens and saves). */
+    readonly request: number;
+    readonly seq: number;
+    readonly restoreSeq: number;
+    readonly client: ViewerStateClient | null;
 };
 export declare const useDashboardStore: import('zustand').UseBoundStore<Omit<import('zustand').StoreApi<DashboardStore>, "setState"> & {
     setState(nextStateOrUpdater: DashboardStore | Partial<DashboardStore> | ((state: import('immer').WritableDraft<DashboardStore>) => void), shouldReplace?: false): void;

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

@@ -61,7 +61,6 @@ export type EditorStore = {
         queryData: any;
     };
     isDevMode: boolean;
-    isShowingVisual: boolean;
     showAIDialog: boolean;
     userInputForAI: string;
     triggerAIRun: boolean;
@@ -79,7 +78,6 @@ export type EditorStore = {
     queryResultColumns: string[];
     queryResultColumnKeyMap?: QueryColumnKeyMap;
     queryError?: string;
-    pythonStdOut?: string;
     selectedConnectionId?: string;
     selectedDatamodelId?: string;
     selectedDatabaseName?: string;
@@ -169,7 +167,6 @@ type Actions = TableActions & ExplorerActions & {
     setCardRefreshInterval: (refreshInterval: string) => void;
     setNumberFormat: (decimalPlaces: number, currency: string, locale: string, suffix: string) => void;
     setColorRanges: (colorRanges: ColorRange[]) => void;
-    setIsShowingVisual: (isShowingVisual: boolean) => void;
     setQueryResultColumns: (columns: string[], columnKeyMap?: QueryColumnKeyMap) => void;
     setRunSql: (runSql: boolean) => void;
     setCardPreferences: (preferences: TCardPreferences) => void;
@@ -189,7 +186,6 @@ type Actions = TableActions & ExplorerActions & {
     setCardType: (type: TChartType) => void;
     setCardSql: (sql: string | undefined) => void;
     setCardPython: (python: string | undefined) => void;
-    setPythonStdOut: (pythonStdOut: string) => void;
     setCardCustomCfg: (cfg: any) => void;
     setCardConfig: (config: CardConfig | undefined) => void;
     setShowFilters: (showFilters: boolean) => void;

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

@@ -17,6 +17,10 @@ export interface ActiveExport {
     fileSize?: number;
     error?: string;
     expiresAt: Date;
+    /** Matrix exports: the server's phase, for the bell's stage text (M9, M10, M12). */
+    phase?: 'preparing' | 'acquiring' | 'finalizing' | 'completed';
+    /** When the server stops the export; polling gives up a grace period later (MX-D9). */
+    deadlineAt?: Date;
 }
 type ExportStoreState = {
     /** Map of export ID to export data */
@@ -27,6 +31,13 @@ type ExportStoreActions = {
     addExport: (exportData: ActiveExport) => void;
     /** Update an existing export */
     updateExport: (id: string, updates: Partial<ActiveExport>) => void;
+    /**
+     * Applies a server answer (poll, refresh). An answer never moves an export
+     * that is final here back to in progress: a newer answer already settled it.
+     */
+    applyServerStatus: (id: string, updates: Partial<ActiveExport>) => void;
+    /** Adds a recovered export only if it is not tracked already (checked when adding). */
+    recoverExport: (exportData: ActiveExport) => void;
     /** Remove an export from the store */
     removeExport: (id: string) => void;
     /** Get all in-progress exports */

package/dist/types/lib/table-formatting/table-totals-settings.d.ts

@@ -19,5 +19,9 @@ export declare function buildFlatTableTotalsRowByColumnId({ card, effectiveCardC
     totalsByColumnId: FlatTableTotalsByColumnId | undefined;
 }): FlatTableTotalsByColumnId | undefined;
 export declare function applyFlatTableTotalsDefaults<TCardLike extends TCard>(card: TCardLike): TCardLike;
-export declare function buildFlatTableTotalsRequest(card: TCard, effectiveCardConfig?: CardConfig): TableTotalsRequest | undefined;
+/**
+ * `labelColumnKey` names the displayed column for the label (an export knows
+ * the viewer's order); otherwise it goes on the first dimension.
+ */
+export declare function buildFlatTableTotalsRequest(card: TCard, effectiveCardConfig?: CardConfig, labelColumnKey?: string): TableTotalsRequest | undefined;
 export declare function removeFlatTableTotalsRowFromCard<TCardLike extends TCard>(card: TCardLike): TCardLike;

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

@@ -79,6 +79,11 @@ export type GetDashboardResponse = {
     assistantProfileId?: string;
     semanticExecutionPayload: SemanticExecutionPayload;
     organizationAppearance?: import('../appearance/types.js').AppearanceSpec | null;
+    /**
+     * This viewer's saved state for the dashboard (dashboard bookmarks). Absent
+     * when the viewer can't be resolved; the dashboard then saves nothing.
+     */
+    viewer?: import('../../shared/dashboard-viewer/index.js').DashboardViewerPayload;
 };
 export type PluginType = 'custom' | 'standard';
 export type GetPluginsResponse = {
@@ -251,6 +256,11 @@ export type DashboardProps = {
     printInputCapture?: unknown;
     /** Server-resolved immutable presentation snapshot for internal print views. */
     presentationExecutionSnapshot?: PresentationExecutionSnapshot;
+    /**
+     * Internal print prop (rendered PDF): the viewer's table settings captured
+     * at export time. Replaces remembered settings; nothing is written.
+     */
+    viewerTableSettings?: Readonly<Record<string, import('../../shared/dashboard-viewer/index.js').ViewerTableSettings>>;
     /**
      * Render target for print entry points. Generic dashboard PDF exports also
      * use cardDisplay.mode="print"; document-specific print handling must only