@mintplayer/ng-spark 22.32.0 → 22.34.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mintplayer/ng-spark",
   "private": false,
-  "version": "22.32.0",
+  "version": "22.34.0",
   "description": "Angular component library for MintPlayer.Spark CRUD applications",
   "repository": {
     "type": "git",
@@ -120,6 +120,10 @@
       "types": "./types/mintplayer-ng-spark-contributions.d.ts",
       "default": "./fesm2022/mintplayer-ng-spark-contributions.mjs"
     },
+    "./dashboards": {
+      "types": "./types/mintplayer-ng-spark-dashboards.d.ts",
+      "default": "./fesm2022/mintplayer-ng-spark-dashboards.mjs"
+    },
     "./grid": {
       "types": "./types/mintplayer-ng-spark-grid.d.ts",
       "default": "./fesm2022/mintplayer-ng-spark-grid.mjs"
@@ -160,6 +164,18 @@
       "types": "./types/mintplayer-ng-spark-moderation.d.ts",
       "default": "./fesm2022/mintplayer-ng-spark-moderation.mjs"
     },
+    "./notifications": {
+      "types": "./types/mintplayer-ng-spark-notifications.d.ts",
+      "default": "./fesm2022/mintplayer-ng-spark-notifications.mjs"
+    },
+    "./organizations": {
+      "types": "./types/mintplayer-ng-spark-organizations.d.ts",
+      "default": "./fesm2022/mintplayer-ng-spark-organizations.mjs"
+    },
+    "./organizations/accept": {
+      "types": "./types/mintplayer-ng-spark-organizations-accept.d.ts",
+      "default": "./fesm2022/mintplayer-ng-spark-organizations-accept.mjs"
+    },
     "./panels": {
       "types": "./types/mintplayer-ng-spark-panels.d.ts",
       "default": "./fesm2022/mintplayer-ng-spark-panels.mjs"
@@ -204,10 +220,22 @@
       "types": "./types/mintplayer-ng-spark-routes.d.ts",
       "default": "./fesm2022/mintplayer-ng-spark-routes.mjs"
     },
+    "./score-renderers": {
+      "types": "./types/mintplayer-ng-spark-score-renderers.d.ts",
+      "default": "./fesm2022/mintplayer-ng-spark-score-renderers.mjs"
+    },
     "./services": {
       "types": "./types/mintplayer-ng-spark-services.d.ts",
       "default": "./fesm2022/mintplayer-ng-spark-services.mjs"
     },
+    "./share": {
+      "types": "./types/mintplayer-ng-spark-share.d.ts",
+      "default": "./fesm2022/mintplayer-ng-spark-share.mjs"
+    },
+    "./share/page": {
+      "types": "./types/mintplayer-ng-spark-share-page.d.ts",
+      "default": "./fesm2022/mintplayer-ng-spark-share-page.mjs"
+    },
     "./shell": {
       "types": "./types/mintplayer-ng-spark-shell.d.ts",
       "default": "./fesm2022/mintplayer-ng-spark-shell.mjs"

package/types/mintplayer-ng-spark-dashboards.d.ts

@@ -0,0 +1,226 @@
+import { SparkAttributeColumnRenderer, SparkAttributeDetailRenderer, SparkAttributeRendererRegistration } from "@mintplayer/ng-spark/renderers";
+import * as i0 from "@angular/core";
+import { Provider, Type } from "@angular/core";
+import { Color } from "@mintplayer/ng-bootstrap";
+import { SparkLanguageService } from "@mintplayer/ng-spark/services";
+import { EntityAttributeDefinition, PersistentObject, TranslatedString } from "@mintplayer/ng-spark/models";
+import { SparkDetailContext } from "@mintplayer/ng-spark/panels";
+/** How a dashboard value is written: a plain number, bytes (binary units), a percentage, a date, or as is. */
+export type SparkDashboardFormat = 'number' | 'bytes' | 'percent' | 'date' | 'datetime' | 'text';
+/** A finite number from a wire value (a number or a numeric string), else null. */
+export declare function toSparkNumber(value: unknown): number | null;
+/** 1536 → "1.5 KB": binary units, one decimal from KB up; "—" for no value. */
+export declare function formatSparkBytes(bytes: number | null | undefined, locale?: string): string;
+/**
+ * A value as a dashboard writes it: "—" for none; numbers by `format` (`decimals` places for `number`/`percent`,
+ * default 0); dates in the viewer's locale; anything else as text.
+ */
+export declare function formatSparkDashboardValue(value: unknown, format: SparkDashboardFormat | undefined, locale?: string, decimals?: number): string;
+/** The colour a threshold gives a value: `danger` at or past `danger`, `warning` at or past `warning`, else none. */
+export declare function sparkThresholdColor(value: number | null, thresholds: {
+  warning?: number;
+  danger?: number;
+  direction?: 'above' | 'below';
+}): 'warning' | 'danger' | null;
+/** `rendererOptions` of the `spark-stat` renderer. Every member is optional. */
+export interface SparkStatOptions {
+  /** How the value is written. Default `'number'`. */
+  format?: SparkDashboardFormat;
+  /** Decimals for `number` (default 0) and `percent` (default 1). */
+  decimals?: number;
+  /** Text after the value, e.g. `' sites'`. Default none. */
+  suffix?: string;
+  /** The value turns amber at or past this. */
+  warning?: number;
+  /** The value turns red at or past this. */
+  danger?: number;
+  /** `'above'` (default): high is bad, as for disk use. `'below'`: low is bad, as for free space. */
+  direction?: 'above' | 'below';
+}
+/**
+ * The `spark-stat` renderer: one figure, large on a detail page (a dashboard tile) and plain in a grid cell,
+ * coloured amber or red once it passes the model's `warning` / `danger` threshold. No value draws a muted dash.
+ */
+export declare class SparkStatComponent implements SparkAttributeColumnRenderer, SparkAttributeDetailRenderer {
+  private readonly locale;
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  private readonly settings;
+  protected readonly text: import("@angular/core").Signal<string>;
+  protected readonly color: import("@angular/core").Signal<"warning" | "danger" | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkStatComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkStatComponent, "spark-stat", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** `rendererOptions` of the `spark-meter` renderer. Every member is optional. */
+export interface SparkMeterOptions {
+  /** The ceiling when the value is a plain number (a value `{ value, max }` brings its own). Default 100. */
+  max?: number;
+  /** How the value and the ceiling are written. Default `'number'`. */
+  format?: SparkDashboardFormat;
+  /** Amber from this share of the ceiling, in percent. Default 75. */
+  warning?: number;
+  /** Red from this share of the ceiling, in percent. Default 90. */
+  danger?: number;
+  /** The meter's accessible name. Default `'Usage'`. */
+  label?: string;
+}
+interface MeterView {
+  value: number;
+  max: number;
+  /** The share of the ceiling, in percent (0–100), one decimal. */
+  share: number;
+  color: Color;
+  text: string;
+}
+/**
+ * The `spark-meter` renderer: how much of something is used, as a bar coloured by its share (green, amber from 75 %,
+ * red from 90 % by default) with "used of total (share)" next to it. The value is a number against the `max` option, or
+ * `{ value, max }` from the server (the dashboards package's `DashboardValues.Meter`), e.g. disk bytes used of the total.
+ * No value, or no ceiling, draws a muted dash.
+ */
+export declare class SparkMeterComponent implements SparkAttributeColumnRenderer, SparkAttributeDetailRenderer {
+  private readonly locale;
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  private readonly settings;
+  protected readonly label: import("@angular/core").Signal<string>;
+  protected readonly view: import("@angular/core").Signal<MeterView | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkMeterComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkMeterComponent, "spark-meter", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** One column of a `spark-dashboard-table`. */
+export interface SparkDashboardTableColumn {
+  /** The row field. For a value that is a dictionary, its rows are `{ key, value }`. */
+  key: string;
+  /** A translation key for the header (`translations.json`), shown as is when it has no translation. Default `key`. */
+  label?: string;
+  /** How the cells are written. Numbers and bytes are right-aligned. Default: as is. */
+  format?: SparkDashboardFormat | 'boolean';
+  /** Translate each cell as `{translate}{value}` (e.g. `'seoUi.runStatus.'`), falling back to the value. */
+  translate?: string;
+}
+/** `rendererOptions` of the `spark-dashboard-table` renderer. */
+export interface SparkDashboardTableOptions {
+  /** The columns, in order. Default: the first row's fields. */
+  columns?: SparkDashboardTableColumn[];
+  /** A translation key shown when there are no rows. Default `'dashboards.empty'`. */
+  empty?: string;
+}
+interface TableCell {
+  text: string;
+  check: boolean;
+}
+/**
+ * The `spark-dashboard-table` renderer (detail pages): a dashboard value that is a list of rows, such as the
+ * RavenDB statistics' collections (D12: tables are JSON attributes). A dictionary (`{ "Completed": 3 }`) reads as
+ * rows `{ key, value }`.
+ */
+export declare class SparkDashboardTableComponent implements SparkAttributeDetailRenderer {
+  private readonly locale;
+  protected readonly lang: SparkLanguageService;
+  readonly value: import("@angular/core").InputSignal<any>;
+  readonly options: import("@angular/core").InputSignal<Record<string, any> | undefined>;
+  protected readonly settings: import("@angular/core").Signal<SparkDashboardTableOptions>;
+  protected readonly rows: import("@angular/core").Signal<Record<string, unknown>[]>;
+  protected readonly columns: import("@angular/core").Signal<SparkDashboardTableColumn[]>;
+  protected readonly cells: import("@angular/core").Signal<TableCell[][]>;
+  protected header(column: SparkDashboardTableColumn): string;
+  protected isNumeric(column: SparkDashboardTableColumn | undefined): boolean;
+  private cell;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkDashboardTableComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkDashboardTableComponent, "spark-dashboard-table", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/** The rows of a table value: a list of objects as is, a dictionary as `{ key, value }` rows, anything else none. */
+export declare function toSparkTableRows(value: unknown): Record<string, unknown>[];
+/** The `metadata` key a dashboard carries (the dashboards package's `SparkDashboardActions.MetadataKey`). */
+export declare const SPARK_DASHBOARD_METADATA_KEY = "dashboard";
+/** Whether `item` is a dashboard: the server marks one with `metadata.dashboard`. */
+export declare function isSparkDashboard(item: PersistentObject | null | undefined): boolean;
+interface DashboardTile {
+  attribute: EntityAttributeDefinition;
+  /** Columns spanned: 1, 2, or the whole row. */
+  span: 1 | 2 | 'row';
+  component: Type<any> | null;
+  inputs: Record<string, any>;
+  /** The value as text, for an attribute without a detail renderer. */
+  text: string;
+}
+interface DashboardSection {
+  id: string;
+  name: string | null;
+  label?: TranslatedString;
+  tiles: DashboardTile[];
+}
+/**
+ * The dashboard tile layout (D12): replaces a dashboard's attribute cards on the routed detail page
+ * (`SPARK_DETAIL_LAYOUTS`, registered by `provideSparkDashboards()`). Each group of the model is a section, each
+ * attribute a tile: its label above its detail renderer (`spark-stat`, `spark-meter`, `spark-trend`,
+ * `spark-dashboard-table`, …) or its plain value. `columnSpan` 2 takes two columns, 3 and more (and a table without one) the
+ * whole row. An attribute the caller may not read is not on the object and has no tile. The page follows the object
+ * over `/spark/live` like any live type, so the tiles change in place.
+ */
+export declare class SparkDashboardComponent {
+  private readonly locale;
+  private readonly renderers;
+  readonly context: import("@angular/core").InputSignal<SparkDetailContext>;
+  protected readonly sections: import("@angular/core").Signal<DashboardSection[]>;
+  /** When the server read the values, in the viewer's locale. */
+  protected readonly generatedAt: import("@angular/core").Signal<string | null>;
+  private tile;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkDashboardComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<SparkDashboardComponent, "spark-dashboard", never, {
+    "context": {
+      "alias": "context";
+      "required": true;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * The dashboard renderers under their model names. Renderers are one list, so add these to the app's own in its
+ * single `provideSparkAttributeRenderers` (or `provideSparkScoreRenderers`, which `spark-trend` comes from) call:
+ *
+ * @example
+ * provideSparkScoreRenderers([...appRenderers, ...sparkDashboardRenderers]),
+ * provideSparkDashboards(),
+ */
+export declare const sparkDashboardRenderers: readonly SparkAttributeRendererRegistration[];
+/**
+ * Draws every dashboard (an object the server marks with `metadata.dashboard`, the dashboards package's live virtual
+ * types) with the tile layout instead of the attribute cards, on the routed detail page. The renderers are registered
+ * separately: see {@link sparkDashboardRenderers}.
+ */
+export declare function provideSparkDashboards(): Provider[];

package/types/mintplayer-ng-spark-grid.d.ts

@@ -219,23 +219,22 @@ export declare function sparkActionClass(definition: CustomActionDefinition, siz
  * The one Spark grid: a `<bs-datatable>` rendering a query or a sub-query.
  *
  * This replaces two components that were the same grid written twice — and, counting
- * `spark-query-list`'s streaming and paged branches, the `<bs-datatable>` element itself written
- * three times. The duplication had already produced four user-visible bugs, each fixed on one
- * side and not the other: `[indeterminate]` on null booleans, permission state surviving a failed
+ * `spark-query-list`'s former streaming and paged branches, the `<bs-datatable>` element itself
+ * written three times. The duplication had already produced four user-visible bugs, each fixed on
+ * one side and not the other: `[indeterminate]` on null booleans, permission state surviving a failed
  * reload, a swallowed fetch failure, and virtual-scroll sizing. `SparkGridRenderers` was
  * extracted to stop that and could only take the stateless helpers with it; this takes the rest.
  *
- * ## What it deliberately does NOT own: streaming
+ * ## Where the rows come from
  *
- * `spark-grid-renderers.ts` records why — a websocket dependency graph must not reach the bundle
- * of every PO detail page, none of which stream. So rows can come from **either** side:
- *
- *  - unbound `data` — the grid fetches for itself, paging and sorting server-side;
+ *  - unbound `data` — the grid fetches for itself, paging and sorting server-side: over HTTP, or over
+ *    `/spark/live` when the grid is live (see {@link live});
  *  - bound `data` — the grid renders what it is given and never fetches.
  *
- * `spark-query-list` keeps the socket and feeds its snapshot in. This is the line `bs-datatable`
- * itself draws: `[data]` and `[fetch]` are mutually exclusive, and binding both makes `[fetch]`
- * win silently.
+ * This is the line `bs-datatable` itself draws: `[data]` and `[fetch]` are mutually exclusive, and
+ * binding both makes `[fetch]` win silently. Live rides on `[fetch]`, so server-side paging, sort,
+ * search and filters work the same live or not; every embedded grid, sub-query and card follows a live
+ * query, not only the query page.
  *
  * ## Reading its state
  *
@@ -246,6 +245,7 @@ export declare function sparkActionClass(definition: CustomActionDefinition, siz
  */
 export declare class SparkQueryGridComponent {
   private readonly sparkService;
+  private readonly liveService;
   private readonly gridRenderers;
   private readonly queryRefresh;
   private readonly injector;
@@ -282,11 +282,31 @@ export declare class SparkQueryGridComponent {
   /**
    * Rows supplied from outside. When bound, the grid renders these and runs no fetch.
    *
-   * This is how streaming stays out of this component (see the class comment). `null` — the
-   * default — means "fetch for yourself"; an empty array means "you have been given no rows",
-   * which is a different statement and renders an empty grid rather than triggering a load.
+   * `null` — the default — means "fetch for yourself"; an empty array means "you have been given no
+   * rows", which is a different statement and renders an empty grid rather than triggering a load.
+   * Bound rows are never live.
    */
   data: import("@angular/core").InputSignal<QueryResultItem[] | null>;
+  /**
+   * Whether this grid follows its query over `/spark/live` (X4): `undefined` — the default — follows the
+   * query's own `live` flag; `true`/`false` overrides it (`[live]="false"` on a dashboard tile).
+   *
+   * Live, the grid's current request (page, sort, search, column filters, parent, deleted modes — exactly
+   * the `/execute` body) is ONE server subscription, sent again as an `update` on every page, sort, search
+   * or filter change, and every pushed page is rendered as it arrives: rows that change, appear or leave.
+   * A subscription `error` clears the rows and shows the message; it is not retried (see {@link isLive}).
+   * A virtual-scrolling query is never live: its blocks are separate pages fetched as the user scrolls, and
+   * one subscription follows one page.
+   */
+  live: import("@angular/core").InputSignal<boolean | undefined>;
+  /**
+   * The live subscription ended with an error for the query loaded now. Reset by a new load; a live grid
+   * does not resubscribe by itself after an error (the answer would not change).
+   */
+  private readonly liveFailed;
+  /** Whether rows arrive over `/spark/live` right now: the query page shows its LIVE badge from this. */
+  readonly isLive: import("@angular/core").Signal<boolean>;
+  private liveWanted;
   /**
    * Server-side search term, passed through to the query.
    *
@@ -539,10 +559,9 @@ export declare class SparkQueryGridComponent {
   deleteRows(rows: QueryResultItem[], definition?: CustomActionDefinition): Promise<void>;
   isVirtualScrolling: import("@angular/core").Signal<boolean>;
   /**
-   * Columns as sent with the most recent fetched page.
+   * Columns as sent with the most recent fetched (or pushed) page.
    *
-   * A host binding `data` (streaming) supplies its own via the `columns` input instead — the
-   * snapshot carries them once, exactly as a paged result does.
+   * A host binding `data` supplies its own via the `columns` input instead.
    */
   private readonly fetchedColumns;
   /**
@@ -557,15 +576,7 @@ export declare class SparkQueryGridComponent {
    * each string names comes from `bsDatatableColumnLabel` in the template. See `sparkDatatableLabels`.
    */
   datatableLabels: import("@angular/core").Signal<import("@mintplayer/ng-spark/services").SparkDatatableLabels>;
-  /**
-   * True when rows do not come from this component's own fetch.
-   *
-   * Either because the host bound `data`, or because the query streams — a streaming query's rows
-   * arrive over a socket and `/execute` is not a way to get them. The grid recognises the second
-   * case itself rather than waiting to be told, because it resolves the query before the host can
-   * see it: left to `data` alone, every streaming grid would fire one pointless fetch on mount,
-   * before the host had anything to bind.
-   */
+  /** True when rows do not come from this component's own fetch: the host bound `data`. */
   hasExternalData: import("@angular/core").Signal<boolean>;
   /**
    * Whether an action can run right now: its selection rule is satisfied, and the client method it
@@ -578,6 +589,22 @@ export declare class SparkQueryGridComponent {
    */
   actionUnavailableReason(action: CustomActionDefinition): string | null;
   constructor();
+  /** The live subscription of the query loaded now, while the grid is live. */
+  private liveSession;
+  private disposeLive;
+  /**
+   * A pushed page: re-fetch through the datatable, which lands in the live fetch and is served from
+   * memory. Through `reload()` rather than a new `[fetch]` identity, so page, sort and scroll stay.
+   */
+  private onLivePush;
+  /**
+   * A live subscription error (defect 4): clear the rows — a stale page must never stay up looking current
+   * — and say why. Not retried: `unavailable` (unknown, forbidden, not live, missing parent — one answer),
+   * `invalid`, `limit` and `failed` would answer the same again, and a socket-level failure (4429, a
+   * repeated 4401) is the socket's to surface. No HTTP fallback either: `unavailable` is the same answer
+   * `/execute` gives as a 404, and an app stream's rows exist only on the socket.
+   */
+  private onLiveError;
   /**
    * Re-run the query, keeping the current page, sort and scroll position.
    *
@@ -689,7 +716,26 @@ export declare class SparkQueryGridComponent {
    * rendered correctly as a page. Both grids are this one now, so there is one answer.
    */
   private resolveEntityType;
+  /** The datatable's `[fetch]`: over `/spark/live` when the grid is live (see {@link live}), else HTTP. */
   private makeFetch;
+  /**
+   * The `/execute` body for one datatable request — the same for HTTP and live. Read at call time, so
+   * what forces a refetch is the fetch identity `reload()` creates, not the value captured when the
+   * closure was built.
+   */
+  private requestFor;
+  /**
+   * One page as the datatable takes it, recording what the chrome reads off a result: count, columns,
+   * the result's withheld actions, the ids on screen.
+   */
+  private toPage;
+  /**
+   * Live: the request goes to this grid's {@link LiveGridSession} — subscribed on the first fetch, sent as
+   * an `update` when it changes, answered from the latest push when it does not. After an error every fetch
+   * is an empty page and the error stays shown.
+   */
+  private makeLiveFetch;
+  private makeHttpFetch;
   private loadLookupReferenceOptions;
   /**
    * The underlying value a custom renderer receives, which is not the printable one.
@@ -730,6 +776,11 @@ export declare class SparkQueryGridComponent {
       "required": false;
       "isSignal": true;
     };
+    "live": {
+      "alias": "live";
+      "required": false;
+      "isSignal": true;
+    };
     "search": {
       "alias": "search";
       "required": false;

package/types/mintplayer-ng-spark-models.d.ts

@@ -341,6 +341,12 @@ export interface EntityType {
    */
   canRead?: boolean;
   alias?: string;
+  /**
+   * Whether an object of this type is followed over `/spark/live` (X4): `spark-po-detail` replaces the
+   * shown object when it changes and shows the unavailable state when it is deleted, and `spark-po-edit`
+   * adopts a newer version (or offers a merge when the form is dirty). Opt-in per type.
+   */
+  live?: boolean;
   /**
    * Breadcrumb template: literal text plus `{AttributeName}` placeholders. A scalar placeholder
    * renders its value; a reference placeholder renders the referenced entity's breadcrumb.
@@ -409,8 +415,12 @@ export interface SparkQuery {
   indexName?: string;
   /** Optional entity type name (e.g., "Person"). When set, used for entity type resolution. */
   entityType?: string;
-  /** When true, this query uses WebSocket streaming with snapshot + patch updates. */
-  isStreamingQuery?: boolean;
+  /**
+   * Whether grids showing this query follow it over `/spark/live` (X4): the page re-renders when a row in
+   * it changes, appears or disappears, with server-side paging, sort, search and filters intact. Opt-in
+   * per query; a grid's `[live]` input overrides it. See `docs/guide-live-updates.md`.
+   */
+  live?: boolean;
   /**
    * Whether the grid offers row selection (#460, D17). Absent is `'auto'`: derived from the offered
    * actions. A sub-query entry on the parent's type may override it.
@@ -734,30 +744,153 @@ export interface EntityPermissions {
   canRevertContribution?: boolean;
 }
 /**
- * The opening message of a stream: the column metadata plus the rows so far.
+ * The live-updates protocol (`/spark/live`, X4), as `docs/guide-live-updates.md` "The protocol" fixes it.
  *
- * Columns arrive once, here. A stream is one result whose rows arrive over time, so its shape is
- * fixed when it opens — patches carry values only.
+ * One WebSocket per browser tab carries every subscription; one JSON object per text frame. Subscriptions
+ * are reads only: mutations stay on HTTP.
  */
-export interface StreamingSnapshotMessage {
-  type: 'snapshot';
-  columns: QueryColumn[];
-  data: QueryResultItem[];
-}
-export interface StreamingPatchItem {
+/** A subscription to one persistent object: exactly the body of `POST /spark/po/load`. */
+export interface LivePoRequest {
+  objectTypeId: string;
   id: string;
-  /** Changed cell values, keyed by column name. Never metadata — the snapshot fixed that. */
-  values: Record<string, any>;
+  deleted?: SparkDeletedFilter | null;
+}
+/** A sort column as `/spark/queries/execute` takes it. */
+export interface LiveSortColumn {
+  property: string;
+  direction: 'asc' | 'desc';
+}
+/**
+ * A subscription to one page of a query: exactly the body of `POST /spark/queries/execute`
+ * (`retryResults` is ignored by the server — a push cannot prompt).
+ */
+export interface LiveQueryRequest {
+  queryId: string;
+  skip?: number | null;
+  take?: number | null;
+  sortColumns?: LiveSortColumn[] | null;
+  search?: string | null;
+  columns?: QueryColumnFilter[] | null;
+  parentId?: string | null;
+  parentType?: string | null;
+  deleted?: SparkDeletedFilter | null;
+  parentDeleted?: SparkDeletedFilter | null;
+}
+export interface LiveSubscribePoOp {
+  op: 'subscribe';
+  sub: string;
+  po: LivePoRequest;
+}
+export interface LiveSubscribeQueryOp {
+  op: 'subscribe';
+  sub: string;
+  query: LiveQueryRequest;
+}
+/** The same query subscription with a new page, sort, search or filters; the server keeps the sub. */
+export interface LiveUpdateOp {
+  op: 'update';
+  sub: string;
+  query: LiveQueryRequest;
+}
+export interface LiveUnsubscribeOp {
+  op: 'unsubscribe';
+  sub: string;
 }
-export interface StreamingPatchMessage {
+export type LiveClientOp = LiveSubscribePoOp | LiveSubscribeQueryOp | LiveUpdateOp | LiveUnsubscribeOp;
+/** `error` codes. Every one ends its subscription; the socket stays open. */
+export type LiveErrorCode = 'unavailable' | 'invalid' | 'limit' | 'failed';
+/** The changes to a held persistent object: top-level fields (`null` = removed) and whole attributes, by `name`. */
+export interface LivePoPatch {
+  set?: Record<string, unknown>;
+  attributes?: PersistentObjectAttribute[];
+}
+/**
+ * The changes to a held query page. Apply: index the held rows by `id`; drop `remove`; replace or add each
+ * `upsert`; the rows are `order` mapped through the index when present, otherwise the held order minus the
+ * removed rows; then assign `set` (`totalItems`, `skip`, `take`, `disabledActions`, `typeHints`, …).
+ */
+export interface LiveQueryPatch {
+  upsert?: QueryResultItem[];
+  remove?: string[];
+  order?: string[];
+  set?: Record<string, unknown>;
+}
+/** The first state of an object, or one whose set or order of attributes changed. Replace. */
+export interface LivePoFrame {
+  type: 'po';
+  sub: string;
+  po: PersistentObject;
+}
+export interface LivePoPatchFrame {
+  type: 'poPatch';
+  sub: string;
+  patch: LivePoPatch;
+}
+/** Deleted or no longer readable (one answer). The subscription has ended. */
+export interface LiveGoneFrame {
+  type: 'gone';
+  sub: string;
+}
+/** The first page, a page whose columns changed, or a change a patch would not make smaller. Replace. */
+export interface LiveResultFrame {
+  type: 'result';
+  sub: string;
+  result: QueryResult;
+}
+export interface LivePatchFrame {
   type: 'patch';
-  updated: StreamingPatchItem[];
+  sub: string;
+  patch: LiveQueryPatch;
 }
-export interface StreamingErrorMessage {
+/** The subscription has ended. Without `sub` it answers an unparseable frame. */
+export interface LiveErrorFrame {
   type: 'error';
+  sub?: string;
+  code: LiveErrorCode;
   message: string;
 }
-export type StreamingMessage = StreamingSnapshotMessage | StreamingPatchMessage | StreamingErrorMessage;
+/** Heartbeat. Nothing to answer. */
+export interface LivePingFrame {
+  type: 'ping';
+}
+export type LiveServerFrame = LivePoFrame | LivePoPatchFrame | LiveGoneFrame | LiveResultFrame | LivePatchFrame | LiveErrorFrame | LivePingFrame;
+/** Close codes with a meaning of their own; any other code is reconnected with backoff. */
+export declare const LIVE_CLOSE_REAUTHENTICATE = 4401;
+export declare const LIVE_CLOSE_TOO_MANY_SOCKETS = 4429;
+export declare const LIVE_CLOSE_MESSAGE_TOO_LARGE = 1009;
+/**
+ * Why a watcher's subscription ended, beyond the server's own {@link LiveErrorCode}s — the socket-level
+ * failures the client surfaces instead of retrying:
+ * - `tooManySockets`: closed with 4429; not reconnected until a new watcher asks.
+ * - `unauthenticated`: closed with 4401 again within seconds of reconnecting for a 4401.
+ * - `messageTooLarge`: closed with 1009, a client bug; not retried blindly.
+ */
+export type LiveFailureCode = LiveErrorCode | 'tooManySockets' | 'unauthenticated' | 'messageTooLarge';
+export interface LiveErrorEvent {
+  type: 'error';
+  code: LiveFailureCode;
+  message: string;
+}
+/** `po`: the object with every patch applied. `gone` and `error` end the stream (it completes after them). */
+export type LivePoEvent = {
+  type: 'po';
+  po: PersistentObject;
+} | {
+  type: 'gone';
+} | LiveErrorEvent;
+/** `result`: the page with every patch applied. `error` ends the stream (it completes after it). */
+export type LiveQueryEvent = {
+  type: 'result';
+  result: QueryResult;
+} | LiveErrorEvent;
+/**
+ * Applies a `patch` frame to a held page, exactly as the protocol says. A new id in `upsert` that `order`
+ * does not place (the server always sends `order` when membership changes, so this is defensive) is
+ * appended rather than dropped.
+ */
+export declare function applyLiveQueryPatch(held: QueryResult, patch: LiveQueryPatch): QueryResult;
+/** Applies a `poPatch` frame to a held object: `set` assigned, changed attributes replaced by `name`. */
+export declare function applyLivePoPatch(held: PersistentObject, patch: LivePoPatch): PersistentObject;
 /**
  * Conversions between the wire format for a timestamp and what an `<input type="datetime-local">`
  * or `<input type="date">` will accept.