@mastra/playground-ui 66.1.0-alpha.2 → 67.0.0

package/dist/src/domains/logs/components/logs-saved-views.d.ts

@@ -0,0 +1,4 @@
+import type { ObservabilitySavedViewsProps } from '../../observability/saved-views';
+export type LogsSavedViewsProps = Pick<ObservabilitySavedViewsProps, 'searchParams' | 'setSearchParams' | 'className'>;
+/** Saved views of the logs page, placed by the host next to `LogsToolbar`. Renders nothing without a `SavedViewsProvider`. */
+export declare function LogsSavedViews(props: LogsSavedViewsProps): import("react").JSX.Element;

package/dist/src/domains/logs/log-filters.d.ts

@@ -53,6 +53,14 @@ export declare const LOGS_ROOT_ENTITY_TYPE_PARAM = "rootEntityType";
 export declare const LOGS_DATE_PRESET_PARAM = "datePreset";
 export declare const LOGS_DATE_FROM_PARAM = "dateFrom";
 export declare const LOGS_DATE_TO_PARAM = "dateTo";
+/** The range the logs page shows when the URL names none. */
+export declare const DEFAULT_LOGS_DATE_PRESET: LogsDatePreset;
+/** Fields the logs list can be sorted by. */
+export declare const LOGS_SORT_FIELDS: readonly ['timestamp'];
+export declare const DEFAULT_LOGS_SORT: {
+    readonly key: 'timestamp';
+    readonly direction: 'desc';
+};
 export declare const LOGS_DATE_PRESET_VALUES: Set<LogsDatePreset>;
 /**
  * Generic filter URL params (filterX keys). Fields that carry multiple values

package/dist/src/domains/metrics/components/agent-runs-card.d.ts

@@ -1,7 +1,14 @@
 import type { TimeRange } from '../drilldown';
-/** Completed and failed agent runs per bucket; a column opens its agent traces. */
+/**
+ * Completed and failed agent runs per bucket, or the share that failed; the title switches between
+ * them. A column or point opens its agent traces.
+ */
 export type AgentRunsCardProps = {
-    /** Called with the time range of the clicked bar or point. */
+    /** Called with the time range of the clicked column (Agent runs). */
     onTimeRangeClick?: (range: TimeRange) => void;
+    /** Called with the time range of the clicked point (Failure rate), for its failed runs. */
+    onFailureTimeRangeClick?: (range: TimeRange) => void;
+    /** Called from the "View errors in logs" button (Failure rate). */
+    onViewErrors?: () => void;
 };
-export declare function AgentRunsCard({ onTimeRangeClick }: AgentRunsCardProps): import("react").JSX.Element;
+export declare function AgentRunsCard({ onTimeRangeClick, onFailureTimeRangeClick, onViewErrors }: AgentRunsCardProps): import("react").JSX.Element;

package/dist/src/domains/metrics/components/breakdown/breakdown-name.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+/**
+ * A row's mark and name. With `provider` set (a model row with a name), the name reads
+ * `openai › gpt-5-mini`; `title` is the name either way.
+ */
+export declare function BreakdownName({ mark, title, model, }: {
+    mark: ReactNode;
+    title: string;
+    model?: {
+        name: string;
+        provider: string | undefined;
+    };
+}): import("react").JSX.Element;

package/dist/src/domains/metrics/components/breakdown/breakdown-not-priced.d.ts

@@ -0,0 +1,2 @@
+/** A figure without a price: said so rather than shown as $0. */
+export declare function BreakdownNotPriced(): import("react").JSX.Element;

package/dist/src/domains/metrics/components/breakdown/breakdown-row-mark.d.ts

@@ -1,9 +1,22 @@
 import type { BreakdownRow, BreakdownTab } from '../../lib/breakdown';
-/**
- * What a row is, before its name: the entity's icon (agents, workflows, tools), the model's
- * provider logo (a generic model icon when the usage names no provider), or nothing.
- */
+import { AgentIcon, ToolsIcon, WorkflowIcon } from '../../../../ds/icons';
+/** The entities a row can be, each marked by its icon before the name. */
+declare const ENTITY_ICONS: {
+    readonly agent: typeof AgentIcon;
+    readonly workflow: typeof WorkflowIcon;
+    readonly tool: typeof ToolsIcon;
+};
+export type MarkedEntity = keyof typeof ENTITY_ICONS;
+export declare function BreakdownEntityMark({ entity }: {
+    entity: MarkedEntity;
+}): import("react").JSX.Element;
+/** The model's provider logo; a generic model icon when the usage names no provider. */
+export declare function BreakdownModelMark({ provider }: {
+    provider: string | undefined;
+}): import("react").JSX.Element;
+/** What a row is, before its name: the entity's icon (agents, workflows, tools), the model's provider, or nothing. */
 export declare function BreakdownRowMark({ tab, row }: {
     tab: BreakdownTab;
     row: BreakdownRow;
 }): import("react").JSX.Element | null;
+export {};

package/dist/src/domains/metrics/components/breakdown/breakdown-trend-text.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+/**
+ * A change, green when it's good news and red when it's bad; without one, a muted dash. The cell sits
+ * in the list's main column, so a flat change is muted too.
+ */
+export declare function BreakdownTrendText({ trend, children }: {
+    trend: 'good' | 'bad' | undefined;
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist/src/domains/metrics/components/card-action-buttons.d.ts

@@ -7,4 +7,13 @@ export declare function OpenInTracesButton({ onClick }: CardActionButtonProps):
 /** Icon button in a MetricsCard top bar that opens the Logs page scoped to
  *  errors for the card's current dimensions. */
 export declare function OpenErrorsInLogsButton({ onClick }: CardActionButtonProps): import("react").JSX.Element;
+/** Icon button in a MetricsCard top bar that opens the Logs page scoped to
+ *  the card's current dimensions, whatever their status. */
+export declare function OpenInLogsButton({ onClick }: CardActionButtonProps): import("react").JSX.Element;
+/** Icon button in a MetricsCard top bar that opens the Spans page scoped to
+ *  the card's current dimensions. */
+export declare function OpenInSpansButton({ onClick }: CardActionButtonProps): import("react").JSX.Element;
+/** Icon button in a MetricsCard top bar that opens the Threads page scoped to
+ *  the card's current dimensions. */
+export declare function OpenInThreadsButton({ onClick }: CardActionButtonProps): import("react").JSX.Element;
 export {};

package/dist/src/domains/metrics/components/chart-card.d.ts

@@ -1,44 +1,56 @@
 import type { ElementType, ReactNode } from 'react';
-import type { MetricsCardTitleMenuProps } from '../../../ds/components/MetricsCard';
+import type { MetricsCardTitleMenuProps, MetricsCardTotalPart } from '../../../ds/components/MetricsCard';
 import type { LinkComponentProps } from '../../../lib/framework';
 /** What `LinkComponent` gets: anchor props, with `href` always set. */
 type ChartCardLinkProps = LinkComponentProps & {
     href: string;
 };
-export type ChartCardProps = {
+export type ChartCardProps<V extends string = string> = {
     /**
-     * Card layout.
-     * - `default`: title and description, the summary top right, a 240px body.
-     * - `compact`: a one-line header (title, `total` on the right), and one card height, so cards
-     *   in a grid line up; the chart fills what the toolbar leaves. For small cards in a grid.
+     * Card layout. `default` and `compact` share one header: the title, and `total` on the right.
+     * - `default`: a 240px body.
+     * - `compact`: one card height, so cards in a grid line up; the chart fills what the toolbar
+     *   leaves. For small cards in a grid.
+     * - `hero`: one large chart that is the page's subject (an explorer): the title as a label over
+     *   a large `total`, with `change` beside it, and `actions` always shown. The body is as tall
+     *   as its content.
      */
-    variant?: 'default' | 'compact';
+    variant?: 'default' | 'compact' | 'hero';
     title: string;
     /**
      * Makes the title a link, marked by an expand icon, to a fuller view of the chart (e.g. the
-     * chart in an explorer). Ignored with `titleMenu`.
+     * chart in an explorer). Ignored with `titleMenu` and on `hero` cards.
      */
     href?: string;
     /** Renders `href` links, e.g. the app's router link; it gets anchor props. Default `a`. */
     LinkComponent?: ElementType<ChartCardLinkProps>;
-    /** Makes the title a dropdown of the card's views (e.g. by model, by provider). */
-    titleMenu?: Omit<MetricsCardTitleMenuProps<string>, 'title' | 'className'>;
-    /** Compact cards: the card's total, right of the title in the same type. */
-    total?: string;
-    /** Compact cards: a skeleton in place of `total`. */
+    /**
+     * Makes the title a dropdown of the card's views (e.g. "Agent latency", "Tool latency"), in
+     * place of tabs. `title` is the picked view's label. Ignored on `hero` cards.
+     */
+    titleMenu?: Omit<MetricsCardTitleMenuProps<V>, 'title' | 'className'>;
+    /**
+     * The card's headline number: right of the title, or the large value on `hero` cards. A card
+     * charting a few different things can pass one total each, marked with its series' color.
+     */
+    total?: string | readonly MetricsCardTotalPart[];
+    /** `hero` cards: the change against the previous period, e.g. "+71.4%". */
+    change?: string;
+    /** A skeleton in place of `total`. */
     isLoading?: boolean;
-    description?: string;
-    /** The headline number, top right: a `MetricsCard.Summary`. Its slot has a fixed width, so the title wraps the same loading or loaded. */
-    summary?: ReactNode;
-    /** Top-bar buttons revealed on hover, e.g. "View in Traces". */
+    /** Top-bar buttons, e.g. "View in traces": revealed on hover, except on `hero` cards. */
     actions?: ReactNode;
-    /** Tabs and legend above the body; they stay in every state. */
+    /**
+     * Legend and controls above the body; they stay in every state. Pass `false` or `null` while
+     * there's nothing to show yet, and the row keeps its height.
+     */
     toolbar?: ReactNode;
     /** Previous data stays on screen, dimmed, while a new range or filter loads. */
     isUpdating?: boolean;
     /**
-     * `fixed` (default): the body is one chart high in every state. `fit`: at least that high, and
-     * taller when the content needs it, for lists that grow with "Show more".
+     * `default` cards. `fixed` (default): a chart, at least 240px high in every state and filling
+     * the card when the card is taller (a grid row). `fit`: at least that high, and as tall as the
+     * content needs, for lists that grow with "Show more".
      */
     bodyHeight?: 'fixed' | 'fit';
     className?: string;
@@ -48,5 +60,5 @@ export type ChartCardProps = {
  * Pure layout for a metrics chart card. The body has a fixed height, so the loading,
  * error, empty and loaded states take the same room and nothing shifts around the card.
  */
-export declare function ChartCard({ variant, title, href, LinkComponent, titleMenu, total, isLoading, description, summary, actions, toolbar, isUpdating, bodyHeight, className, children, }: ChartCardProps): import("react").JSX.Element;
+export declare function ChartCard<V extends string = string>({ variant, title, href, LinkComponent, titleMenu, total, change, isLoading, actions, toolbar, isUpdating, bodyHeight, className, children, }: ChartCardProps<V>): import("react").JSX.Element;
 export {};

package/dist/src/domains/metrics/components/distinct-ids/distinct-ids-chart.d.ts

@@ -1,7 +1,6 @@
 import type { DrilldownScope } from '../../drilldown';
 import type { TraceAggregateScope } from '../../hooks/use-metrics-trace-aggregate';
 export declare const DISTINCT_IDS_TITLE = "Resources and threads";
-export declare const DISTINCT_IDS_DESCRIPTION = "Unique ids on traces; users and sessions only when set.";
 export type DistinctIdsChartProps = {
     scope: TraceAggregateScope;
     /** Called with the time range of the clicked bucket. */

package/dist/src/domains/metrics/components/failure-rate-card.d.ts

@@ -1,9 +1,12 @@
 import type { TimeRange } from '../drilldown';
+import type { ChartCardProps } from './chart-card';
 /** Share of agent runs that failed, per bucket; a point opens the failed runs' traces. */
-export type FailureRateCardProps = {
+export type FailureRateCardProps<V extends string = string> = {
     /** Called from the "View errors in Logs" button. */
     onViewErrors?: () => void;
     /** Called with the time range of the clicked bar or point. */
     onTimeRangeClick?: (range: TimeRange) => void;
+    /** Switches to a sibling view from the title (Agent runs uses it). */
+    titleMenu?: ChartCardProps<V>['titleMenu'];
 };
-export declare function FailureRateCard({ onViewErrors, onTimeRangeClick }: FailureRateCardProps): import("react").JSX.Element;
+export declare function FailureRateCard<V extends string = string>({ onViewErrors, onTimeRangeClick, titleMenu, }: FailureRateCardProps<V>): import("react").JSX.Element;

package/dist/src/domains/metrics/components/index.d.ts

@@ -1,13 +1,12 @@
 export { DateRangeSelector } from './date-range-selector';
 export { MetricsTimeRangeChip } from './metrics-time-range-chip';
-export { OpenErrorsInLogsButton, OpenInTracesButton } from './card-action-buttons';
+export { OpenErrorsInLogsButton, OpenInLogsButton, OpenInSpansButton, OpenInThreadsButton, OpenInTracesButton, } from './card-action-buttons';
 export { ChartArea, type ChartAreaProps } from './chart-area';
 export { ChartCard, type ChartCardProps } from './chart-card';
 export { ChartCardError } from './chart-card-error';
 export { AggregateLimiterProvider } from '../hooks/aggregate-limiter-provider';
 export { KpiCard, type KpiCardProps } from './kpi-card';
 export { MetricsGrid, type MetricsGridProps, type MetricsGridItemProps } from './metrics-grid/metrics-grid';
-export { MetricsKpis } from './metrics-kpis';
 export { TokenUsageCard, type TokenUsageCardProps } from './token-usage-card';
 export { AgentRunsCard, type AgentRunsCardProps } from './agent-runs-card';
 export { FailureRateCard, type FailureRateCardProps } from './failure-rate-card';

package/dist/src/domains/metrics/components/metrics-grid/metrics-grid.d.ts

@@ -17,6 +17,9 @@ export type MetricsGridItemProps = {
     span?: MetricsGridItemSpan;
     className?: string;
 };
-/** A grid cell. The grid owns the width, so each card's own `min-w-*` is neutralised. */
+/**
+ * A grid cell. The grid owns the width, so each card's own `min-w-*` is neutralised, and the card
+ * fills the cell's height, so cards in a row end together.
+ */
 declare function MetricsGridItem({ children, span, className }: MetricsGridItemProps): import("react").JSX.Element;
 export {};

package/dist/src/domains/metrics/components/trace-aggregate-card.d.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
 import type { TraceAggregateScope } from '../hooks/use-metrics-trace-aggregate';
 import type { ChartCardProps } from './chart-card';
-export type TraceAggregateCardProps = Pick<ChartCardProps, 'title' | 'description' | 'className'> & {
+export type TraceAggregateCardProps = Pick<ChartCardProps, 'title' | 'className'> & {
     /** The card groups or filters on the root span's type, which needs `traceQueryRootSpanFields`. */
     requiresRootSpanFields?: boolean;
     /** The loaded card, rendered once the server can answer it and the page filters apply to traces. */

package/dist/src/domains/observability/components/observability-header-slot.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The element at the end of the shared observability header row, next to the traces / spans / threads
+ * switch. Controls rendered deep in a page body (e.g. saved views) portal into it.
+ */
+export declare const ObservabilityHeaderSlotContext: import("react").Context<HTMLElement | undefined>;
+export declare const useObservabilityHeaderSlot: () => HTMLElement | undefined;

package/dist/src/domains/observability/components/observability-histogram.d.ts

@@ -10,7 +10,7 @@ export type ObservabilityHistogramProps = {
     isError?: boolean;
     /** Previous buckets stay on screen, dimmed, while a new selection loads. */
     isUpdating?: boolean;
-    /** Dragging across bars reports the first and last selected bar; turn it into a window with `zoomWindow`. */
+    /** Dragging across bars, or clicking one, reports the first and last selected bar; turn it into a window with `zoomWindow`. */
     onZoom?: (range: DragSelectionRange) => void;
 };
 /**

package/dist/src/domains/observability/hooks/use-observability-list-filters.d.ts

@@ -1,6 +1,7 @@
+import type { ObservabilityListSort } from '../observability-list-url-state';
 import type { TraceFilterGroup, TraceFilterToken } from '../../traces/trace-query-filters';
 import type { TraceDatePreset } from '../../traces/types';
-import type { DataListSort } from '../../../ds/components/DataList/data-list-sortable-top-cell';
+import type { SetURLSearchParamsLike } from '../../../lib/sort/use-url-sort';
 /**
  * Like the traces list with delta polling: a timer or a window focus would reload every loaded page
  * and reset the cursor chain, so an observability list only reloads to recover from a transient failure.
@@ -13,8 +14,21 @@ export declare const observabilityListQueryOptions: {
     }) => number | false;
     refetchOnWindowFocus: boolean;
 };
-/** The time range, filter and sort state of a spans or threads list. */
-export declare function useObservabilityListFilters(): {
+export type ObservabilityListUrlState = {
+    searchParams: URLSearchParams;
+    setSearchParams: SetURLSearchParamsLike;
+};
+/**
+ * The time range, filter and sort state of a spans or threads list, kept in the host's URL (same
+ * date, sort and group params as /traces) so it survives a reload and can be shared. Without `url`
+ * the state lives in memory. A sort on a field outside `sortFields` reads as start time, newest first.
+ * `defaultDatePreset` is the range shown when the URL names none (last 7 days unless the host differs);
+ * it is left out of the URL like any default.
+ */
+export declare function useObservabilityListFilters<F extends string = 'startedAt'>(url?: ObservabilityListUrlState, { sortFields, defaultDatePreset, }?: {
+    sortFields?: readonly F[];
+    defaultDatePreset?: TraceDatePreset;
+}): {
     datePreset: TraceDatePreset;
     dateFrom: Date | undefined;
     dateTo: Date | undefined;
@@ -26,11 +40,13 @@ export declare function useObservabilityListFilters(): {
     rolling: boolean;
     tokens: TraceFilterToken[];
     groups: TraceFilterGroup[];
-    sort: DataListSort;
-    setSort: import("react").Dispatch<import("react").SetStateAction<DataListSort>>;
+    sort: ObservabilityListSort<"startedAt" | F>;
+    setSort: (next: ObservabilityListSort<F | 'startedAt'>) => void;
     onDatePresetChange: (preset: TraceDatePreset) => void;
     onDateChange: (date: Date | undefined, end: 'from' | 'to') => void;
     onDateRangeChange: (from: Date | undefined, to: Date | undefined) => void;
+    onZoom: (from: Date, to: Date) => void;
+    onDateReset: (defaultPreset: TraceDatePreset) => void;
     onFiltersChange: (nextTokens: TraceFilterToken[], nextGroups: TraceFilterGroup[]) => void;
     contentFiltersApplied: boolean;
     filtersApplied: boolean;

package/dist/src/domains/observability/index.d.ts

@@ -15,3 +15,5 @@ export { OBSERVABILITY_LIST_HEAD_LIMIT, OBSERVABILITY_LIST_HEAD_MAX_ROWS, OBSERV
 export { OBSERVABILITY_VIEW_LABELS, observabilityViewCrumbLabel } from './observability-crumbs';
 export { readSpanSelection, readThreadSelection, spanTraceSearch, withSpanSelection, withThreadSelection, } from './observability-selection-params';
 export type { ObservabilityView } from '../traces/components/traces-spans-switch';
+export { ObservabilitySavedViews, SavedViewNameTakenError, SavedViewsProvider } from './saved-views';
+export type { ObservabilitySavedViewsProps, SavedViewColumnsControl, SavedViewRecord, SavedViewsProviderProps, SavedViewsSource, } from './saved-views';

package/dist/src/domains/observability/lib/zoom-memory.d.ts

@@ -0,0 +1,19 @@
+import type { TraceDatePreset } from '../../traces/types';
+export type DateRangeSelection = {
+    datePreset: TraceDatePreset;
+    dateFrom?: Date;
+    dateTo?: Date;
+};
+/** The range picked before a histogram zoom, and the zoomed range it can be restored from. */
+export type ZoomMemory = {
+    before: DateRangeSelection;
+    fromMs: number;
+    toMs: number;
+};
+/** Zooming from an earlier zoom keeps the range picked before the first one. */
+export declare function rememberZoom(memory: ZoomMemory | undefined, current: DateRangeSelection, from: Date, to: Date): ZoomMemory;
+/**
+ * The range to restore while `current` is still the remembered zoom. Once the user picks another
+ * range, the zoom no longer applies and this returns `undefined`.
+ */
+export declare const rangeBeforeZoom: (memory: ZoomMemory | undefined, current: DateRangeSelection) => DateRangeSelection | undefined;

package/dist/src/domains/observability/observability-list-url-state.d.ts

@@ -0,0 +1,39 @@
+import type { TraceFilterGroup, TraceFilterToken } from '../traces/trace-query-filters';
+import type { TraceDatePreset } from '../traces/types';
+/**
+ * URL state of the spans and threads lists. Dates, sort and groups use the same params as /traces;
+ * a flat token lives in `filter.<fieldId>` (plus `filter.<fieldId>.op` unless the operator is `is`),
+ * since span and thread fields are not in the trace page's fixed `filterX` param map.
+ */
+export declare const OBSERVABILITY_LIST_FILTER_PARAM_PREFIX = "filter.";
+export declare const OBSERVABILITY_LIST_SORT_FIELDS: readonly ['startedAt'];
+/** Spans can also be ordered by their streaming timings, where the store supports it. */
+export declare const SPAN_LIST_SORT_FIELDS: readonly ['startedAt', 'timeToFirstChunkMs', 'timeToFirstTokenMs'];
+export declare const OBSERVABILITY_LIST_DEFAULT_DATE_PRESET: TraceDatePreset;
+export type ObservabilityListSortDirection = 'asc' | 'desc';
+export declare const OBSERVABILITY_LIST_DEFAULT_SORT_DIRECTION: ObservabilityListSortDirection;
+export type ObservabilityListSort<F extends string = string> = {
+    field: F;
+    direction: ObservabilityListSortDirection;
+};
+export type ObservabilityListDates = {
+    datePreset: TraceDatePreset;
+    dateFrom?: Date;
+    dateTo?: Date;
+};
+export type ObservabilityListFilters = {
+    tokens: TraceFilterToken[];
+    groups: TraceFilterGroup[];
+};
+/** `defaultPreset` is the range the host shows when the URL names none. */
+export declare function readObservabilityListDates(params: URLSearchParams, defaultPreset?: TraceDatePreset): ObservabilityListDates;
+/** Mutates `params`. The host's default preset is left out of the URL; dates are only kept for `custom`. */
+export declare function writeObservabilityListDates(params: URLSearchParams, { datePreset, dateFrom, dateTo }: ObservabilityListDates, defaultPreset?: TraceDatePreset): void;
+/** Flat tokens in URL order, plus the advanced groups. */
+export declare function readObservabilityListFilters(params: URLSearchParams): ObservabilityListFilters;
+/** Mutates `params`: replaces every filter param with `tokens` (in order) and `groups`. */
+export declare function writeObservabilityListFilters(params: URLSearchParams, { tokens, groups }: ObservabilityListFilters): void;
+/** The URL's sort when its field is one of `fields`, else start time, newest first. */
+export declare function readObservabilityListSort<F extends string>(params: URLSearchParams, fields: readonly F[]): ObservabilityListSort<F | 'startedAt'>;
+/** Mutates `params`. */
+export declare function writeObservabilityListSort(params: URLSearchParams, { field, direction }: ObservabilityListSort): void;

package/dist/src/domains/observability/saved-view-state.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Conversion between a saved view (`SavedViewState` from `@mastra/core/storage`) and the URL state of
+ * the observability list pages. Applying a view writes the URL the user would get by setting the same
+ * filters, range, sort and options by hand, through each page's own URL writers.
+ *
+ * Columns are not URL state (traces and spans keep them in local storage), so they travel separately
+ * as `TraceColumnPreferences`.
+ */
+import type { SavedViewColumn, SavedViewPage, SavedViewState } from '@mastra/core/storage';
+import type { TraceColumnPreferences, TraceColumnScope } from '../traces/trace-list-columns';
+export declare const SAVED_VIEW_CUSTOM_COLUMN_PREFIX = "custom.";
+export declare const SAVED_VIEW_METADATA_COLUMN_PREFIX = "metadata.";
+/**
+ * A page's column preferences as saved-view columns: every standard column in catalog order with its
+ * visibility, then the custom columns (shown ones first, in their order) and the metadata columns.
+ */
+export declare function savedViewColumnsFromPreferences(scope: TraceColumnScope, preferences: TraceColumnPreferences): SavedViewColumn[];
+/** Saved-view columns as a page's column preferences. Columns the page no longer offers are dropped. */
+export declare function columnPreferencesFromSavedView(scope: TraceColumnScope, columns: readonly SavedViewColumn[]): TraceColumnPreferences;
+/**
+ * The saved view of `page` for its current URL. Pass the page's column preferences to save its
+ * columns too (traces, spans and threads only; the other pages have fixed columns).
+ */
+export declare function savedViewFromSearchParams(page: SavedViewPage, params: URLSearchParams, { columns }?: {
+    columns?: TraceColumnPreferences;
+}): SavedViewState;
+export type AppliedSavedView = {
+    /** `base` with the view's filters, range, sort and options in place of the page's own. */
+    params: URLSearchParams;
+    /** The column preferences to apply; set only when the view has columns and the page offers a column picker. */
+    columns?: TraceColumnPreferences;
+};
+export type ApplySavedViewOptions = {
+    /**
+     * The range the host shows when the URL names none, when it differs from the page's own default.
+     * Only this preset is left out of the URL; any other one, including the page's default, is written.
+     */
+    defaultDatePreset?: string;
+};
+/**
+ * Applies `view` on top of `base` (the page's current search params): every view param is replaced,
+ * other params (e.g. the open row) are kept and the list restarts at its first page. Parts of the view
+ * the page no longer supports (unknown filter field or operator, sort field, date preset, column,
+ * option) are dropped one by one; the page's default takes their place.
+ */
+export declare function applySavedView(view: SavedViewState, base: URLSearchParams, { defaultDatePreset }?: ApplySavedViewOptions): AppliedSavedView;

package/dist/src/domains/observability/saved-views/index.d.ts

@@ -0,0 +1,7 @@
+export { ObservabilitySavedViews } from './observability-saved-views';
+export type { ObservabilitySavedViewsProps } from './observability-saved-views';
+export { SavedViewsProvider } from './saved-views-provider';
+export type { SavedViewsProviderProps } from './saved-views-provider';
+export { SavedViewNameTakenError } from './saved-views-source';
+export type { SavedViewRecord, SavedViewsSource } from './saved-views-source';
+export type { SavedViewColumnsControl } from './use-hosted-saved-views';

package/dist/src/domains/observability/saved-views/observability-saved-views.d.ts

@@ -0,0 +1,22 @@
+import type { SavedViewPage } from '@mastra/core/storage';
+import type { SavedViewColumnsControl } from './use-hosted-saved-views';
+import type { SetURLSearchParamsLike } from '../../../lib/sort/use-url-sort';
+export type ObservabilitySavedViewsProps = {
+    page: SavedViewPage;
+    searchParams: URLSearchParams;
+    setSearchParams: SetURLSearchParamsLike;
+    /** The page's column picker (traces, spans, threads), so views save and restore columns. */
+    columns?: SavedViewColumnsControl;
+    /**
+     * The range the page shows when the URL names none, when the host's differs from the page's own
+     * (the same value passed to `useObservabilityListFilters`).
+     */
+    defaultDatePreset?: string;
+    className?: string;
+};
+/**
+ * The saved views of an observability page: a searchable view picker with save and reset actions.
+ * Inside the shared traces / spans / threads header it moves into that header's row. Renders nothing
+ * unless a `SavedViewsProvider` above it supplies where views are stored.
+ */
+export declare function ObservabilitySavedViews(props: ObservabilitySavedViewsProps): import("react").JSX.Element | null;

package/dist/src/domains/observability/saved-views/saved-views-provider.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import type { SavedViewRecord, SavedViewsSource } from './saved-views-source';
+export type SavedViewsProviderProps = {
+    source: SavedViewsSource;
+    /** Keeps the cached views of one scope (e.g. `['project', projectId]`) apart from another's. */
+    queryKeyScope?: readonly unknown[];
+    /**
+     * Whether a view can be renamed, deleted or overwritten here, e.g. `view => view.scope !== 'org'` where
+     * org-wide views are read-only. Read-only views can still be applied and duplicated. Defaults to all.
+     */
+    canEdit?: (view: SavedViewRecord) => boolean;
+    children: ReactNode;
+};
+/** Turns saved views on for the observability pages below it. Without it, the pages show none. */
+export declare function SavedViewsProvider({ source, queryKeyScope, canEdit, children }: SavedViewsProviderProps): import("react").JSX.Element;

package/dist/src/domains/observability/saved-views/saved-views-source.d.ts

@@ -0,0 +1,41 @@
+import type { SavedViewPage, SavedViewState } from '@mastra/core/storage';
+/** A saved view as the host stores it. */
+export type SavedViewRecord = {
+    id: string;
+    name: string;
+    state: SavedViewState;
+    updatedAt: string;
+    /** `org`: shared by every project of the organization. Omitted: saved where it is listed. */
+    scope?: 'org' | 'project';
+};
+/**
+ * Where saved views are stored. The host supplies it (e.g. backed by its API), so the observability
+ * pages show saved views only where the host supports them.
+ */
+export type SavedViewsSource = {
+    /** The views of one page, newest-updated first. */
+    list: (page: SavedViewPage) => Promise<SavedViewRecord[]>;
+    /** Rejects with `SavedViewNameTakenError` when the name is already used. */
+    create: (input: {
+        name: string;
+        state: SavedViewState;
+    }) => Promise<SavedViewRecord>;
+    /** Rejects with `SavedViewNameTakenError` when the new name is already used. */
+    update: (id: string, patch: {
+        name?: string;
+        state?: SavedViewState;
+    }) => Promise<SavedViewRecord>;
+    remove: (id: string) => Promise<void>;
+};
+/** Thrown by a `SavedViewsSource` when a view with the same name already exists (e.g. on an HTTP 409). */
+export declare class SavedViewNameTakenError extends Error {
+    constructor(message?: string);
+}
+export type SavedViewsContextValue = {
+    source: SavedViewsSource;
+    queryKeyScope: readonly unknown[];
+    canEdit?: (view: SavedViewRecord) => boolean;
+};
+export declare const SavedViewsContext: import("react").Context<SavedViewsContextValue | undefined>;
+export declare const useSavedViewsSource: () => SavedViewsContextValue | undefined;
+export declare const savedViewsQueryKey: (queryKeyScope: readonly unknown[], page: SavedViewPage) => unknown[];

package/dist/src/domains/observability/saved-views/use-hosted-saved-views.d.ts

@@ -0,0 +1,34 @@
+import type { SavedViewPage, SavedViewState } from '@mastra/core/storage';
+import type { SavedViewRecord, SavedViewsContextValue } from './saved-views-source';
+import type { TraceColumnPreferences } from '../../traces/trace-list-columns';
+import type { SavedViewsController } from '../../../ds/components/SavedViews/use-saved-views';
+import type { SetURLSearchParamsLike } from '../../../lib/sort/use-url-sort';
+/** Same limit as the saved view schema in `@mastra/core`, checked before a request is made. */
+export declare const SAVED_VIEW_STATE_MAX_BYTES: number;
+export declare const SAVED_VIEW_TOO_LARGE_MESSAGE = "This view is too large to save (16 KiB max). Remove some filters or columns.";
+/** A view's state, and for a stored view its record. */
+export type HostedSavedViewSettings = {
+    state: SavedViewState;
+    record?: SavedViewRecord;
+};
+export type SavedViewColumnsControl = {
+    preferences: TraceColumnPreferences;
+    setPreferences: (next: TraceColumnPreferences) => void;
+    /** Back to the page's default columns, when the page default is picked. */
+    resetColumns: () => void;
+};
+export type UseHostedSavedViewsArgs = SavedViewsContextValue & {
+    page: SavedViewPage;
+    searchParams: URLSearchParams;
+    setSearchParams: SetURLSearchParamsLike;
+    /** The page's column picker; omitted on pages with fixed columns. */
+    columns?: SavedViewColumnsControl;
+    /** The range the page shows when the URL names none, when the host's differs from the page's own. */
+    defaultDatePreset?: string;
+};
+/**
+ * Saved views of one observability page, stored by the host's `SavedViewsSource`. The page URL is
+ * the draft: picking a view writes its state to the URL (and its columns to the column picker), and
+ * the view shows unsaved changes while the URL differs from it.
+ */
+export declare function useHostedSavedViews({ page, source, queryKeyScope, searchParams, setSearchParams, columns, defaultDatePreset, canEdit, }: UseHostedSavedViewsArgs): SavedViewsController<HostedSavedViewSettings>;

package/dist/src/domains/spans/components/spans-explorer-body.d.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import type { SpanSelection } from './span-detail-panel';
+import type { ObservabilityListUrlState } from '../../observability/hooks/use-observability-list-filters';
 export type SpansExplorerPanelArgs = {
     selection: SpanSelection | undefined;
     /** Loaded spans, in list order, for the panel's previous/next buttons. */
@@ -13,6 +14,8 @@ export type SpansExplorerBodyProps = {
     onSelectionChange: (selection: SpanSelection | undefined) => void;
     /** Renders the open span's panel in the host's own side panel or drawer. */
     renderPanel: (args: SpansExplorerPanelArgs) => ReactNode;
+    /** The host's search params, so the time range, filters and sort survive a reload. Omitted: kept in memory. */
+    urlState?: ObservabilityListUrlState;
 };
 /** The spans page body: filter bar, span list and the host's span panel. Router-agnostic. */
-export declare function SpansExplorerBody({ selection, onSelectionChange, renderPanel }: SpansExplorerBodyProps): import("react").JSX.Element;
+export declare function SpansExplorerBody({ selection, onSelectionChange, renderPanel, urlState }: SpansExplorerBodyProps): import("react").JSX.Element;

package/dist/src/domains/spans/components/spans-filter-bar.d.ts

@@ -14,10 +14,12 @@ export type SpansFilterBarProps = {
     onDatePresetChange: (preset: TraceDatePreset) => void;
     onDateChange: (value: Date | undefined, type: 'from' | 'to') => void;
     onDateRangeChange: (from: Date | undefined, to: Date | undefined) => void;
+    /** Called by the time range chip's × with the default preset, e.g. to undo a histogram zoom first. */
+    onDateReset?: (defaultPreset: TraceDatePreset) => void;
     onFiltersChange: (tokens: TraceFilterToken[], groups: TraceFilterGroup[]) => void;
     /** Turns a failed value suggestions lookup into the message shown in the option list. */
     describeSuggestionsError?: (error: unknown) => string | undefined;
     disabled?: boolean;
 };
 /** The spans filter bar: a time range chip plus the fields `querySpans()` accepts. */
-export declare function SpansFilterBar({ datePreset, dateFrom, dateTo, minDate, timeRange, tokens, groups, onDatePresetChange, onDateChange, onDateRangeChange, onFiltersChange, describeSuggestionsError, disabled, }: SpansFilterBarProps): import("react").JSX.Element;
+export declare function SpansFilterBar({ datePreset, dateFrom, dateTo, minDate, timeRange, tokens, groups, onDatePresetChange, onDateChange, onDateRangeChange, onDateReset, onFiltersChange, describeSuggestionsError, disabled, }: SpansFilterBarProps): import("react").JSX.Element;

package/dist/src/domains/spans/hooks/use-spans-filter-bar.d.ts

@@ -10,7 +10,7 @@ export type UseSpansFilterBarFieldsOptions = {
 };
 /**
  * The fields the spans filter bar offers: the time range plus the fields `querySpans()` accepts.
- * Context fields are only included when the store declares `spanQueryContextFields`.
+ * Context, model and outcome fields and streaming timings are only included when the store declares them.
  */
 export declare function useSpansFilterBarFields({ timeRange }: UseSpansFilterBarFieldsOptions): FilterBarField[];
 export type UseSpansFilterBarOptions = {