@gravitee/gamma-lib-observability 1.40.0 → 2.0.0-feat-obs-41-http-dashboard-persistence.74f3ce8

package/QUERYING.md

@@ -229,11 +229,23 @@ series to keep a single left axis (backward compatible).
 Filters merge in this order, later layers win on a field conflict:
 
 ```
-context (dashboard scope) → view (active dashboard filters) → widget (widget.filters) → series/item (series[].filters / items[].filters)
+dashboard definition (re-valuable default) → reader URL filters → dashboard definition (locked) → widget (widget.filters) → series/item (series[].filters / items[].filters)
 ```
 
-- The merged top-level filters are sent as the request `filters[]`; series/item filters are sent as
-  per-metric `filters[]`.
+**The host's context scope sits above all of it as a ceiling, not as a layer.** A module mounted with
+`scopeApiTypes` (or explicit `contextFilters`) always carries that scope, and any condition on a
+scoped field is intersected with it: a later layer can narrow inside the scope, never step outside
+it. An intersection that comes out empty falls back to the host's own values rather than to no
+condition at all, because a value-less condition is dropped before the request and would leave the
+query unscoped. Only ceilings whose operator is `eq` or `in` are enforced this way. See
+`clampToScope` in `src/filters/scope-ceiling.ts`.
+
+Within a dashboard, a definition filter is locked or re-valuable (`editable`); see
+`resolveDashboardFilters` for how a reader's URL filters are reconciled with it.
+
+- The merged top-level filters are sent as the request `filters[]`. Item filters (`items[].filters`)
+  are sent as per-metric `filters[]`; series filters are merged into the top-level `filters[]` of
+  that series' own request, since each series is one request.
 - Operators are mapped to the v2 wire format: `eq → EQ`, `in → IN`, `gte → GTE`, `lte → LTE`.
   `eq`/`gte`/`lte` take a single value; `in` takes an array. Unsupported operators throw with a clear
   error rather than silently dropping the filter.

package/dist/dashboards/DashboardFilterChip.d.ts

@@ -0,0 +1,32 @@
+import { FilterCondition } from '../types/domain';
+export interface DashboardFilterChipProps {
+    readonly condition: FilterCondition;
+    /** Re-valuable slots show a chevron affordance; locked ones show a padlock. */
+    readonly revaluable: boolean;
+    /**
+     * The reader has moved this slot off the author's value. Marked, because a
+     * shared link otherwise looks identical whether it carries the author's
+     * intent or somebody else's session.
+     */
+    readonly changedByReader?: boolean;
+    /** Forwarded to {@link FilterChip}: whether the chip reacts to clicks at all. */
+    readonly editable?: boolean;
+    readonly active?: boolean;
+    readonly onEdit?: () => void;
+    /**
+     * Offers the X on hover and the Delete/Backspace shortcut, the gesture this
+     * app already uses for every other filter chip. The author's editor passes
+     * it; the reader's dashboard must not, since removing a dashboard filter is
+     * not theirs to do.
+     */
+    readonly onRemove?: () => void;
+}
+/**
+ * Adapter that maps a dashboard-definition filter onto the generic
+ * {@link FilterChip}: an outline pill with a leading padlock (locked) or a
+ * trailing chevron (re-valuable), and `: Any` for an empty slot. This is the
+ * single place that owns the "dashboard chip" look. It composes FilterChip,
+ * it does not reimplement it.
+ */
+export declare const DashboardFilterChip: import('react').ForwardRefExoticComponent<DashboardFilterChipProps & import('react').RefAttributes<HTMLSpanElement>>;
+//# sourceMappingURL=DashboardFilterChip.d.ts.map

package/dist/dashboards/DashboardFilterChip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DashboardFilterChip.d.ts","sourceRoot":"","sources":["../../src/dashboards/DashboardFilterChip.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CAChC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,sHA4B9B,CAAC"}

package/dist/dashboards/DashboardFilterChipPopover.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { FilterCondition } from '../types/domain';
+export interface DashboardFilterChipPopoverProps {
+    readonly condition: FilterCondition;
+    readonly revaluable: boolean;
+    readonly changedByReader?: boolean;
+    /** When set, the chip also offers the X and the Delete shortcut. */
+    readonly onRemove?: () => void;
+    /** Renders the popover body; `close` dismisses it after apply/cancel. */
+    readonly renderForm: (close: () => void) => ReactNode;
+}
+/**
+ * A dashboard filter chip that opens a popover on click. It renders the shared
+ * {@link DashboardFilterChip} and anchors the popover to it via a virtual ref,
+ * the same pattern as `FilterBar`, so the edit / re-value form renders exactly
+ * like every other filter popover.
+ */
+export declare function DashboardFilterChipPopover({ condition, revaluable, changedByReader, onRemove, renderForm, }: DashboardFilterChipPopoverProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=DashboardFilterChipPopover.d.ts.map

package/dist/dashboards/DashboardFilterChipPopover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DashboardFilterChipPopover.d.ts","sourceRoot":"","sources":["../../src/dashboards/DashboardFilterChipPopover.tsx"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,SAAS,CAAC;CACvD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,SAAS,EACT,UAAU,EACV,eAAe,EACf,QAAQ,EACR,UAAU,GACX,EAAE,+BAA+B,2CAwBjC"}

package/dist/dashboards/DashboardFilterChips.d.ts

@@ -0,0 +1,29 @@
+import { FilterProvider } from '../filters/filter-provider';
+import { FilterCondition } from '../types/domain';
+export interface DashboardFilterChipsProps {
+    /** Locked dashboard filters: read-only, always applied. */
+    readonly lockedFilters: readonly FilterCondition[];
+    /** Re-valuable dashboard filters: the reader may change the value only. */
+    readonly revaluableFilters: readonly FilterCondition[];
+    /**
+     * The author's value for each re-valuable filter, aligned index by index.
+     * What a chip is compared against to know the reader has moved it.
+     */
+    readonly revaluableDefaults?: readonly FilterCondition[];
+    /** Providers used to load values in the re-value popover. */
+    readonly providers: readonly FilterProvider[];
+    /** Active API types passed to async value loaders. */
+    readonly activeApiTypes?: readonly string[];
+    /** Called when the reader re-values a slot (field fixed; empty value = "*"). */
+    readonly onRevalue: (field: string, next: FilterCondition) => void;
+    /** Drops the reader's value so the author's takes over again. */
+    readonly onResetRevalue?: (field: string) => void;
+}
+/**
+ * Dashboard-definition filter chips shown in view mode, rendered with the shared
+ * {@link FilterChip}. Locked filters render read-only with a padlock; re-valuable
+ * filters are clickable slots whose value the reader can change (field and
+ * operator are stated rather than offered). An empty value renders `label: Any`.
+ */
+export declare function DashboardFilterChips({ lockedFilters, revaluableFilters, revaluableDefaults, providers, activeApiTypes, onRevalue, onResetRevalue, }: DashboardFilterChipsProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=DashboardFilterChips.d.ts.map

package/dist/dashboards/DashboardFilterChips.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DashboardFilterChips.d.ts","sourceRoot":"","sources":["../../src/dashboards/DashboardFilterChips.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAKvD,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,SAAS,eAAe,EAAE,CAAC;IACnD,2EAA2E;IAC3E,QAAQ,CAAC,iBAAiB,EAAE,SAAS,eAAe,EAAE,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACzD,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IACnE,iEAAiE;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AASD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,SAAS,EACT,cAAc,GACf,EAAE,yBAAyB,kDAmD3B"}

package/dist/dashboards/DashboardFilterValueForm.d.ts

@@ -0,0 +1,32 @@
+import { FilterProvider } from '../filters/filter-provider';
+import { FilterCondition } from '../types/domain';
+export interface DashboardFilterValueFormProps {
+    /** The definition slot: its field and operator are the author's and stay. */
+    readonly condition: FilterCondition;
+    readonly provider?: FilterProvider;
+    readonly activeApiTypes?: readonly string[];
+    /**
+     * Puts the author's value back. Set only when the reader has moved away from
+     * it, so the control appears exactly when it has something to undo.
+     */
+    readonly onReset?: () => void;
+    readonly onApply: (next: FilterCondition) => void;
+    readonly onCancel: () => void;
+}
+/**
+ * What a reader gets when they open a re-valuable dashboard filter: one
+ * question, "which value?".
+ *
+ * Deliberately not the author's form with two thirds of it switched off. That
+ * shape showed a reader a field picker and an operator select they could never
+ * use, which communicates only that something is being withheld, and it made
+ * the guarantee a matter of disabled attributes: a greyed combobox is still
+ * focusable, and a wrapper that swallows input is a lie rather than a lock.
+ * Here the field and the operator are not controls at all, so there is nothing
+ * to grey, nothing to skip in the tab order, and no way to reach them.
+ *
+ * The value editor itself is shared with the author's form, so the half the two
+ * roles do have in common cannot drift.
+ */
+export declare function DashboardFilterValueForm({ condition, provider, activeApiTypes, onReset, onApply, onCancel, }: DashboardFilterValueFormProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=DashboardFilterValueForm.d.ts.map

package/dist/dashboards/DashboardFilterValueForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DashboardFilterValueForm.d.ts","sourceRoot":"","sources":["../../src/dashboards/DashboardFilterValueForm.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,4BAA4B,CAAC;AAIpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,6BAA6B;IAC5C,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,SAAS,EACT,QAAQ,EACR,cAAc,EACd,OAAO,EACP,OAAO,EACP,QAAQ,GACT,EAAE,6BAA6B,2CAiF/B"}

package/dist/dashboards/dashboard-filters.d.ts

@@ -0,0 +1,79 @@
+import { FilterCondition } from '../types/domain';
+/**
+ * How a filter with no value renders: every value passes, no query constraint.
+ * It is a slot the author leaves open so a reader finds the field ready to fill
+ * instead of having to build the chip themselves.
+ *
+ * A word rather than an asterisk. In a form, `*` is the established mark for a
+ * required field, so it read as the opposite of what this means.
+ */
+export declare const ALL_VALUES_LABEL = "Any";
+/**
+ * A dashboard-definition filter is **locked** unless it explicitly opts into
+ * "allow value change" (`editable: true`). Defaulting a missing flag to locked
+ * is the safe direction: a scoping filter that silently became reader-editable
+ * would widen a scope its author fixed, while the reverse only costs a reader
+ * one control.
+ *
+ * A filter with no value is never locked, whatever the flag says. There is no
+ * value to fix, so locking one would produce a chip that constrains nothing and
+ * can never be filled: a dead slot. The rule lives here rather than only in the
+ * editor because a definition can also arrive from the JSON tab, a template or
+ * the backend, and none of those pass through the editor's toggle. Letting the
+ * reader value it cannot widen anything either, since the empty filter was
+ * imposing no constraint to begin with.
+ */
+export declare function isLocked(filter: FilterCondition): boolean;
+export declare function isRevaluable(filter: FilterCondition): boolean;
+/**
+ * The flag to store for what the author expressed in the editor, kept next to
+ * {@link isLocked} so the two cannot drift apart on the empty-value rule.
+ */
+export declare function deriveEditable(allowValueChange: boolean, hasValue: boolean): boolean;
+export interface ResolvedDashboardFilters {
+    /**
+     * Every field the dashboard governs, locked or re-valuable. Barrier 1: the
+     * page removes these from the reader's filter picker. Returned here rather
+     * than recomputed by the caller so all three barriers derive from one split.
+     */
+    readonly governedFields: ReadonlySet<string>;
+    /** Locked filters: rendered read-only, always applied. */
+    readonly lockedChips: FilterCondition[];
+    /** Re-valuable filters, showing the reader's value if set, else the author's. */
+    readonly revaluableChips: FilterCondition[];
+    /**
+     * The author's own value for each re-valuable filter, aligned index by index
+     * with `revaluableChips`.
+     *
+     * Both halves already existed here; only the resolved one was published. A
+     * reader who changes a slot had no way to see they had diverged, and no way
+     * back: on a shared link the two are indistinguishable.
+     */
+    readonly revaluableDefaults: FilterCondition[];
+    /** The reader's raw re-values (their URL filters on re-valuable fields), for preservation. */
+    readonly userRevalues: FilterCondition[];
+    /** The reader's own free filters (fields the dashboard does not govern). */
+    readonly userOwnFilters: FilterCondition[];
+    /** Filters actually applied to widgets (empty-value placeholders dropped at wire time). */
+    readonly effectiveFilters: FilterCondition[];
+}
+/**
+ * Splits a dashboard's definition filters and the reader's URL filters into the
+ * chips to render and the effective filters to query.
+ *
+ * Locked filters are **non-circumventable** from the client. Three barriers,
+ * kept independent on purpose so no single one carries the guarantee alone:
+ *
+ * 1. the page removes every dashboard-governed field from the filter picker, so
+ *    a competing chip cannot be built through the UI at all;
+ * 2. a URL filter on a locked field is discarded here. It lands in neither
+ *    `userRevalues` nor `userOwnFilters`, so a hand-written query string is
+ *    read and dropped rather than trusted;
+ * 3. the merge dedupes by field and takes the locked definitions last, so even
+ *    a condition that reached this point some other way loses.
+ *
+ * A reader can only ever change the *value* of a re-valuable field. The flag
+ * itself is never encoded into the URL, so it cannot be granted by tampering.
+ */
+export declare function resolveDashboardFilters(dashboardFilters: readonly FilterCondition[], urlFilters: readonly FilterCondition[]): ResolvedDashboardFilters;
+//# sourceMappingURL=dashboard-filters.d.ts.map

package/dist/dashboards/dashboard-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-filters.d.ts","sourceRoot":"","sources":["../../src/dashboards/dashboard-filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,iBAAiB,CAAC;AAGvE;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAEzD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAE7D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,gBAAgB,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAEpF;AA4BD,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7C,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,eAAe,EAAE,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,eAAe,EAAE,eAAe,EAAE,CAAC;IAC5C;;;;;;;OAOG;IACH,QAAQ,CAAC,kBAAkB,EAAE,eAAe,EAAE,CAAC;IAC/C,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,EAAE,eAAe,EAAE,CAAC;IACzC,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,eAAe,EAAE,CAAC;IAC3C,2FAA2F;IAC3F,QAAQ,CAAC,gBAAgB,EAAE,eAAe,EAAE,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,SAAS,eAAe,EAAE,EAC5C,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,wBAAwB,CAiE1B"}

package/dist/dashboards/editor/DashboardEditorPage.d.ts

@@ -11,5 +11,13 @@
  * belongs. The range still refreshes on demand, by re-picking it in the time
  * range control.
  */
-export declare function DashboardEditorPage(): import("react/jsx-runtime").JSX.Element;
+export interface DashboardEditorPageProps {
+    /**
+     * Context field carrying the host's module scope (e.g. `API_TYPE`), forwarded
+     * to the dashboard-filters editor so an author is only offered the fields and
+     * values their own module covers.
+     */
+    readonly scopeFilterField?: string;
+}
+export declare function DashboardEditorPage({ scopeFilterField }: DashboardEditorPageProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=DashboardEditorPage.d.ts.map

package/dist/dashboards/editor/DashboardEditorPage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DashboardEditorPage.d.ts","sourceRoot":"","sources":["../../../src/dashboards/editor/DashboardEditorPage.tsx"],"names":[],"mappings":"AA+DA;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,4CAQlC"}
+{"version":3,"file":"DashboardEditorPage.d.ts","sourceRoot":"","sources":["../../../src/dashboards/editor/DashboardEditorPage.tsx"],"names":[],"mappings":"AAkEA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,wBAAgB,mBAAmB,CAAC,EAAE,gBAAgB,EAAE,EAAE,wBAAwB,2CAYjF"}

package/dist/dashboards/editor/DashboardFiltersEditor.d.ts

@@ -0,0 +1,26 @@
+import { FilterCondition } from '../../types/domain';
+export interface DashboardFiltersEditorProps {
+    readonly filters: readonly FilterCondition[];
+    /**
+     * Context field carrying the host's module scope (e.g. `API_TYPE`). It
+     * narrows what the author may *add*: which fields the picker offers and which
+     * values their loaders return. Without it an author scoped to LLM and MCP is
+     * shown every API the tenant owns and can build a filter pointing outside
+     * their own module.
+     *
+     * It deliberately does not narrow the filters already on the dashboard. Those
+     * stay editable and keep their catalog name whatever the scope says, so a
+     * definition written before the scope changed, or written by hand, never
+     * becomes a chip its author can only look at.
+     */
+    readonly scopeFilterField?: string;
+    readonly onChange: (filters: FilterCondition[]) => void;
+}
+/**
+ * Inline editor for a dashboard's definition filters. The author manipulates the
+ * exact chips the reader will see (WYSIWYG): each chip opens a popover to edit
+ * its value/operator and toggle "Allow value change" (locked vs re-valuable);
+ * "Add dashboard filter" appends one. An empty value renders `: Any`.
+ */
+export declare function DashboardFiltersEditor({ filters, scopeFilterField, onChange }: DashboardFiltersEditorProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=DashboardFiltersEditor.d.ts.map

package/dist/dashboards/editor/DashboardFiltersEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DashboardFiltersEditor.d.ts","sourceRoot":"","sources":["../../../src/dashboards/editor/DashboardFiltersEditor.tsx"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAa1D,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,IAAI,CAAC;CACzD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAAE,2BAA2B,2CAiD1G"}

package/dist/dashboards/editor/dashboard-editor-state.d.ts

@@ -31,6 +31,9 @@ export type DashboardDraftAction = {
 } | {
     type: 'setTimeRange';
     timeRange: TimeRange;
+} | {
+    type: 'setFilters';
+    filters: FilterCondition[];
 } | {
     type: 'upsertWidget';
     widget: Widget;

package/dist/dashboards/editor/dashboard-editor-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard-editor-state.d.ts","sourceRoot":"","sources":["../../../src/dashboards/editor/dashboard-editor-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGlH;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAAC;AAEjE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,mBAAmB,CAE1E;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAEhE;AAMD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,oBAAoB,GAAG,mBAAmB,CA8DnH;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAK5C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAE/D;AAED,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,YAAY,CAAC;AAClD,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAepC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAErE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAmDpG;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAIvD;AAED,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,IAAiB,GAAG,SAAS,CAUtE"}
+{"version":3,"file":"dashboard-editor-state.d.ts","sourceRoot":"","sources":["../../../src/dashboards/editor/dashboard-editor-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGlH;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAAC;AAEjE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,mBAAmB,CAE1E;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAEhE;AAMD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,oBAAoB,GAAG,mBAAmB,CAgEnH;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAK5C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAE/D;AAED,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,YAAY,CAAC;AAClD,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAepC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAErE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAmDpG;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAIvD;AAED,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,IAAiB,GAAG,SAAS,CAUtE"}

package/dist/dashboards/editor/locked-filter-conflicts.d.ts

@@ -0,0 +1,29 @@
+import { FilterCondition, Widget } from '../../types/domain';
+export interface LockedFilterConflict {
+    readonly widgetId: string;
+    /** Falls back to the id: a widget can be saved before it is named. */
+    readonly widgetTitle: string;
+    readonly field: string;
+    readonly label: string;
+    readonly dashboardValue: string[];
+    readonly dashboardValueLabels?: string[];
+    readonly widgetValue: string[];
+    readonly widgetValueLabels?: string[];
+}
+/**
+ * Widgets whose own filters override a locked dashboard filter.
+ *
+ * Widget filters are merged last, so on a shared field the widget's value is
+ * the one queried, whatever the padlock on the dashboard chip says. Within the
+ * host's module scope, which still clamps it either way. That is
+ * deliberate (see `ObservabilityDashboardPage`), which is exactly why the
+ * author has to be told: nothing downstream will. Most of these are written
+ * without anyone typing them, by `withAutoScope` stamping the `API_TYPE` a
+ * metric requires, so the contradiction can appear from picking a metric.
+ *
+ * A widget carrying the *same* value is not a conflict. It is what the AIM
+ * templates do today, pinning every widget to the API type the dashboard is
+ * about, and flagging it would cry wolf on the common case.
+ */
+export declare function findLockedFilterConflicts(dashboardFilters: readonly FilterCondition[], widgets: readonly Widget[]): LockedFilterConflict[];
+//# sourceMappingURL=locked-filter-conflicts.d.ts.map

package/dist/dashboards/editor/locked-filter-conflicts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locked-filter-conflicts.d.ts","sourceRoot":"","sources":["../../../src/dashboards/editor/locked-filter-conflicts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGlE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CACvC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,gBAAgB,EAAE,SAAS,eAAe,EAAE,EAC5C,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,oBAAoB,EAAE,CAsBxB"}

package/dist/dashboards/merge-filters.d.ts

@@ -1,8 +1,17 @@
 import { FilterCondition } from '../types/domain';
 /**
- * Union-merges multiple filter sources.
- * Later sources take precedence when the same field is targeted.
- * Canonical order: context → view → widget (widget wins on conflict).
+ * Union-merges multiple filter sources. Later sources take precedence when the
+ * same field is targeted, and the result keeps the first insertion position of
+ * each field.
+ *
+ * This is the mechanism, not the policy: it does not know which source is which
+ * and has no canonical order of its own. The host's scope is applied on top by
+ * `clampToScope`, which is what actually decides precedence and is the only
+ * place that describes the full chain.
+ *
+ * Note it keys on `field` alone, so two conditions on the same field with
+ * different operators can never coexist across sources: `latency gte 100` and
+ * `latency lte 500` collapse to one.
  */
 export declare function mergeFilters(...sources: (readonly FilterCondition[] | undefined)[]): FilterCondition[];
 //# sourceMappingURL=merge-filters.d.ts.map

package/dist/dashboards/merge-filters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge-filters.d.ts","sourceRoot":"","sources":["../../src/dashboards/merge-filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,OAAO,EAAE,CAAC,SAAS,eAAe,EAAE,GAAG,SAAS,CAAC,EAAE,GAAG,eAAe,EAAE,CAWtG"}
+{"version":3,"file":"merge-filters.d.ts","sourceRoot":"","sources":["../../src/dashboards/merge-filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,GAAG,OAAO,EAAE,CAAC,SAAS,eAAe,EAAE,GAAG,SAAS,CAAC,EAAE,GAAG,eAAe,EAAE,CAWtG"}

package/dist/dashboards/renderers/CartesianWidgetRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CartesianWidgetRenderer.d.ts","sourceRoot":"","sources":["../../../src/dashboards/renderers/CartesianWidgetRenderer.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,oBAAoB,CAAC;AAO5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAGvE,wBAAgB,uBAAuB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,mBAAmB,CAAC,eAAe,CAAC,2CA4F3G"}
+{"version":3,"file":"CartesianWidgetRenderer.d.ts","sourceRoot":"","sources":["../../../src/dashboards/renderers/CartesianWidgetRenderer.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,oBAAoB,CAAC;AAO5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAGvE,wBAAgB,uBAAuB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,mBAAmB,CAAC,eAAe,CAAC,2CAkG3G"}

package/dist/dashboards/use-merged-widget-filters.d.ts

@@ -1,11 +1,16 @@
 import { FilterCondition } from '../types/domain';
 /**
  * Resolves the effective filters for a widget renderer.
- * Merge order: context → view → widget (widget wins on field conflict).
  *
- * All widget renderers must use this hook so the merge contract is
- * explicit and consistent, regardless of whether the downstream query
- * hook also merges context filters internally.
+ * View filters then widget filters, the widget winning on a shared field, all
+ * of it then clamped by the host's context scope. The clamp is what changed:
+ * a widget filter used to replace a context filter outright, which let a widget
+ * render another module's data. It can now narrow inside the host's scope but
+ * not step outside it. See `clampToScope`.
+ *
+ * All widget renderers must use this hook so the contract is explicit and
+ * consistent, regardless of whether the downstream query hook also applies the
+ * scope itself.
  */
 export declare function useMergedWidgetFilters(widgetFilters?: readonly FilterCondition[], viewFilters?: readonly FilterCondition[]): FilterCondition[];
 //# sourceMappingURL=use-merged-widget-filters.d.ts.map

package/dist/dashboards/use-merged-widget-filters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-merged-widget-filters.d.ts","sourceRoot":"","sources":["../../src/dashboards/use-merged-widget-filters.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,EAC1C,WAAW,CAAC,EAAE,SAAS,eAAe,EAAE,GACvC,eAAe,EAAE,CAGnB"}
+{"version":3,"file":"use-merged-widget-filters.d.ts","sourceRoot":"","sources":["../../src/dashboards/use-merged-widget-filters.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,EAC1C,WAAW,CAAC,EAAE,SAAS,eAAe,EAAE,GACvC,eAAe,EAAE,CAGnB"}

package/dist/data-sources/dashboard-errors.d.ts

@@ -0,0 +1,42 @@
+import { Dashboard } from '../types/domain';
+/**
+ * Failure returned by a server-backed dashboard persistence.
+ *
+ * The subclasses exist because the screens already tell these outcomes apart:
+ * a refused read degrades to the read-only template experience, a missing
+ * dashboard shows its own state, and a stale save asks the author what to do.
+ * Distinguishing them on a status code parsed from the message would put that
+ * decision in every caller instead of here.
+ */
+export declare class DashboardPersistenceError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** The caller lacks the `ENVIRONMENT_DASHBOARD` ACL for this verb. */
+export declare class DashboardForbiddenError extends DashboardPersistenceError {
+    constructor(message: string);
+}
+/**
+ * No dashboard with this id exists in the current environment.
+ *
+ * The API answers 404 rather than 403 for an id belonging to another
+ * environment, so this also covers a dashboard the caller may not reach.
+ */
+export declare class DashboardNotFoundError extends DashboardPersistenceError {
+    readonly dashboardId: string;
+    constructor(dashboardId: string, message: string);
+}
+/**
+ * The dashboard was saved by someone else since it was read, so the update was
+ * refused and nothing on the server changed.
+ *
+ * Carries the server's current dashboard because the API returns it in the 412
+ * body: the author can be shown what they were about to overwrite, and can
+ * choose to reload, save a copy, or overwrite, without a second request.
+ */
+export declare class DashboardConflictError extends DashboardPersistenceError {
+    readonly currentVersion: number | undefined;
+    readonly currentDashboard: Dashboard;
+    constructor(message: string, currentDashboard: Dashboard, currentVersion?: number);
+}
+//# sourceMappingURL=dashboard-errors.d.ts.map

package/dist/data-sources/dashboard-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-errors.d.ts","sourceRoot":"","sources":["../../src/data-sources/dashboard-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK5C;AAED,sEAAsE;AACtE,qBAAa,uBAAwB,SAAQ,yBAAyB;gBACxD,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,yBAAyB;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAKjD;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,yBAAyB;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,cAAc,CAAC,EAAE,MAAM;CAMlF"}

package/dist/data-sources/dashboard-wire.d.ts

@@ -0,0 +1,85 @@
+import { Dashboard, FilterCondition, TimeRange, Widget } from '../types/domain';
+/**
+ * Wire shapes of the Gamma dashboards API and the mapping to the lib's domain
+ * model, in one module so the two directions cannot drift apart.
+ *
+ * The API is the authority on these shapes (`DashboardDto`, `DashboardFilterDto`,
+ * `DashboardTimeRangeDto`, `SaveDashboardRequestDto`). Every optional/nullable
+ * field below is declared that way because the server declares it that way, not
+ * defensively: the response types are what a `null` in the JSON actually looks
+ * like, and the mapping is the single place that decides what it becomes.
+ */
+/**
+ * One dashboard-definition filter as the API returns it. `operator` is
+ * UPPERCASE and `value` is always an array, even for single-value operators.
+ */
+export interface WireDashboardFilter {
+    name: string;
+    label?: string | null;
+    operator: string;
+    value?: string[] | null;
+    editable?: boolean | null;
+}
+/**
+ * `type` is lowercase on the wire — it was chosen to match this lib's
+ * discriminated union, so no translation is needed beyond the null handling.
+ */
+export interface WireTimeRange {
+    type: string;
+    period?: string | null;
+    from?: number | null;
+    to?: number | null;
+}
+export interface WireDashboard {
+    id: string;
+    title: string;
+    description?: string | null;
+    filters?: WireDashboardFilter[] | null;
+    timeRange?: WireTimeRange | null;
+    widgets?: unknown;
+    /** Revision counter, also handed out as the response `ETag`. Starts at 1. */
+    version?: number | null;
+    createdAt?: number | null;
+    updatedAt?: number | null;
+}
+/**
+ * Body of `POST` and `PUT`. Server-owned fields (`version`, `createdAt`,
+ * `updatedAt`, `createdBy`) are absent by design — the API ignores them, and
+ * the revision a `PUT` is based on travels in `If-Match`, not in the body.
+ */
+export interface WireSaveDashboardRequest {
+    /** Client-supplied, and read on `POST` only: `PUT` takes the id from the path. */
+    id?: string;
+    title: string;
+    description?: string;
+    filters: WireDashboardFilter[];
+    timeRange: WireTimeRange;
+    widgets: readonly Widget[];
+}
+export interface WirePagination {
+    totalCount: number;
+    page: number;
+    perPage: number;
+    pageCount: number;
+    pageItemsCount: number;
+}
+export interface WireDashboardsPage {
+    data?: WireDashboard[] | null;
+    pagination?: WirePagination | null;
+}
+/** Body of the `412` refusing a stale save. Extends the standard error shape. */
+export interface WireDashboardConflict {
+    message?: string;
+    http_status?: number;
+    currentVersion?: number | null;
+    dashboard?: WireDashboard | null;
+}
+export declare function toWireFilter(filter: FilterCondition): WireDashboardFilter;
+export declare function fromWireFilter(wire: WireDashboardFilter): FilterCondition;
+export declare function toWireTimeRange(timeRange: TimeRange): WireTimeRange;
+export declare function fromWireTimeRange(wire: WireTimeRange | null | undefined): TimeRange;
+export declare function fromWireDashboard(wire: WireDashboard): Dashboard;
+export declare function toWireSaveRequest(dashboard: Dashboard, options: {
+    readonly includeId: boolean;
+}): WireSaveDashboardRequest;
+//# sourceMappingURL=dashboard-wire.d.ts.map

package/dist/data-sources/dashboard-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-wire.d.ts","sourceRoot":"","sources":["../../src/data-sources/dashboard-wire.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAkC,SAAS,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAErH;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,mBAAmB,EAAE,GAAG,IAAI,CAAC;IACvC,SAAS,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,kFAAkF;IAClF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IAC9B,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CACpC;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CAClC;AAwBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,mBAAmB,CAYzE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CASzE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,aAAa,CAInE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAcnF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CAiBhE;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GACvC,wBAAwB,CAS1B"}

package/dist/data-sources/http-dashboard-persistence.d.ts

@@ -0,0 +1,62 @@
+import { HttpOptions } from '../providers/http-provider';
+import { Dashboard } from '../types/domain';
+import { DashboardPersistence } from './dashboard-persistence';
+export interface HttpDashboardPersistenceOptions extends HttpOptions {
+    /**
+     * Path appended to `baseUrl` for the dashboards collection.
+     * @default '/observability/dashboards'
+     */
+    readonly dashboardsPath?: string;
+}
+export interface UpdateDashboardOptions {
+    /**
+     * Applies the write over whatever revision is current (`If-Match: *`) instead
+     * of the revision this adapter last saw.
+     *
+     * This is the second step of the conflict flow, not a convenience: an author
+     * who was refused a save and chose "overwrite" applies their edit in one
+     * request, where re-reading and re-submitting could lose the same race again.
+     * It cannot be reached by accident — only by asking for it here. The
+     * dashboard must still exist, so an overwrite never resurrects a deleted one.
+     */
+    readonly force?: boolean;
+}
+/**
+ * A {@link DashboardPersistence} that can also be asked for a deliberate
+ * overwrite. The extra argument is optional, so this is the port plus a
+ * capability rather than a different shape: anything typed against the port
+ * keeps working, and callers holding this type can offer the overwrite.
+ */
+export interface HttpDashboardPersistence extends DashboardPersistence {
+    updateDashboard(dashboard: Dashboard, signal?: AbortSignal, options?: UpdateDashboardOptions): Promise<Dashboard>;
+}
+/**
+ * {@link DashboardPersistence} backed by the Gamma dashboards API
+ * (`{baseUrl}/observability/dashboards`).
+ *
+ * <h3>Revisions</h3>
+ * The API guards concurrent edits with `ETag` / `If-Match`, and its revision
+ * counter has no home in the lib's `Dashboard` — deliberately, so the port stays
+ * the same contract whatever backs it. This adapter therefore remembers, per
+ * dashboard id, the validator naming the revision the caller is working from,
+ * and quotes it back on the next save. `If-Match` is always sent, so the API's
+ * 428 is unreachable from here.
+ *
+ * A **write** always adopts the revision it just produced: after a save, that is
+ * what the caller holds. A **read** only fills a blank — it never moves a
+ * revision already remembered. The two differ because a read is not proof the
+ * caller took the content: an editor holds a draft seeded from an earlier read
+ * while TanStack Query refetches behind it, and adopting that refetch's revision
+ * would let the draft be saved with a validator naming a revision it was never
+ * based on — silently overwriting the edit that produced it, which is the one
+ * outcome the whole mechanism exists to prevent. The cost of the other direction
+ * is a save refused as a conflict while the author was in fact already looking
+ * at the current revision: they are shown it and can overwrite in one request.
+ * Visible and recoverable, where the reverse is neither.
+ *
+ * The `ETag` header is preferred and the body's `version` is the fallback: a
+ * cross-origin deployment that does not expose `ETag` still yields a usable
+ * validator instead of silently degrading every save to an overwrite.
+ */
+export declare function createHttpDashboardPersistence(baseUrl: string, options?: HttpDashboardPersistenceOptions): HttpDashboardPersistence;
+//# sourceMappingURL=http-dashboard-persistence.d.ts.map

package/dist/data-sources/http-dashboard-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-dashboard-persistence.d.ts","sourceRoot":"","sources":["../../src/data-sources/http-dashboard-persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAOjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAkBpE,MAAM,WAAW,+BAAgC,SAAQ,WAAW;IAClE;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAyB,SAAQ,oBAAoB;IACpE,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACnH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,+BAA+B,GACxC,wBAAwB,CAgN1B"}