@mintplayer/ng-spark 22.23.0 → 22.25.0

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

@@ -1,202 +1,251 @@
-import * as i0 from '@angular/core';
-import { RetryActionPayload, RetryActionResult, TranslatedString, StreamingMessage, QueryColumnFilter, EntityType, EntityPermissions, SparkQuery, QueryResult, DistinctValuesResult, ProgramUnitsConfiguration, PersistentObject, CustomActionDefinition, LookupReferenceListItem, LookupReference, LookupReferenceValue } from '@mintplayer/ng-spark/models';
-import { Observable } from 'rxjs';
-import { SortColumn } from '@mintplayer/pagination';
-import { SafeHtml } from '@angular/platform-browser';
-import { HttpInterceptorFn, HttpFeature, HttpFeatureKind } from '@angular/common/http';
-
-declare class RetryActionService {
-    private resolveRetry;
-    payload: i0.WritableSignal<RetryActionPayload | null>;
-    show(payload: RetryActionPayload): Promise<RetryActionResult>;
-    respond(result: RetryActionResult): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<RetryActionService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<RetryActionService>;
+import { CustomActionDefinition, DistinctValuesResult, EntityPermissions, EntityType, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, ProgramUnitsConfiguration, QueryColumnFilter, QueryResult, RetryActionPayload, RetryActionResult, SparkDeletedFilter, SparkQuery, StreamingMessage, TranslatedString } from "@mintplayer/ng-spark/models";
+import * as i0 from "@angular/core";
+import { Observable } from "rxjs";
+import { SortColumn } from "@mintplayer/pagination";
+import { SafeHtml } from "@angular/platform-browser";
+import { HttpFeature, HttpFeatureKind, HttpInterceptorFn } from "@angular/common/http";
+export declare class RetryActionService {
+  private resolveRetry;
+  payload: import("@angular/core").WritableSignal<RetryActionPayload | null>;
+  show(payload: RetryActionPayload): Promise<RetryActionResult>;
+  respond(result: RetryActionResult): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<RetryActionService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
-
-declare class SparkLanguageService {
-    private readonly http;
-    private readonly config;
-    private readonly baseUrl;
-    private readonly currentLang;
-    private readonly translationsMap;
-    readonly language: i0.Signal<string>;
-    readonly languages: i0.WritableSignal<Record<string, TranslatedString>>;
-    constructor();
-    private loadCulture;
-    private loadTranslations;
-    setLanguage(lang: string): void;
-    resolve(ts: TranslatedString | undefined): string;
-    t(key: string): string;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SparkLanguageService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<SparkLanguageService>;
+export declare class SparkLanguageService {
+  private readonly http;
+  private readonly config;
+  private readonly baseUrl;
+  private readonly currentLang;
+  private readonly translationsMap;
+  readonly language: import("@angular/core").Signal<string>;
+  readonly languages: import("@angular/core").WritableSignal<Record<string, TranslatedString>>;
+  constructor();
+  private loadCulture;
+  private loadTranslations;
+  setLanguage(lang: string): void;
+  resolve(ts: TranslatedString | undefined): string;
+  t(key: string): string;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkLanguageService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
-
-declare class SparkStreamingService {
-    private readonly config;
-    private readonly baseUrl;
-    private readonly ngZone;
-    connectToStreamingQuery(queryId: string): Observable<StreamingMessage>;
-    private buildWebSocketUrl;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SparkStreamingService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<SparkStreamingService>;
+export declare class SparkStreamingService {
+  private readonly config;
+  private readonly baseUrl;
+  private readonly ngZone;
+  connectToStreamingQuery(queryId: string): Observable<StreamingMessage>;
+  private buildWebSocketUrl;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkStreamingService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
-
 /**
  * Context for {@link SparkService.newObject}. Everything is optional: a standalone New sends an
  * empty body, and an AsDetail row on a parent that has never been saved sends no `parentId` —
  * which is the honest answer, not a gap. The server hands the hook a null parent rather than
  * trusting the client's copy of one.
  */
-interface NewObjectOptions {
-    /** Name of the parent's AsDetail attribute the row is for; absent for a standalone New. */
-    asDetailAttribute?: string;
-    /** The parent's entity type — required whenever `asDetailAttribute` is set. */
-    parentType?: string;
-    /** The parent's id, absent while the parent is itself unsaved. */
-    parentId?: string;
-    /** Free-form arguments, e.g. which variant a New menu chose. */
-    parameters?: Record<string, string>;
+export interface NewObjectOptions {
+  /** Name of the parent's AsDetail attribute the row is for; absent for a standalone New. */
+  asDetailAttribute?: string;
+  /** The parent's entity type — required whenever `asDetailAttribute` is set. */
+  parentType?: string;
+  /** The parent's id, absent while the parent is itself unsaved. */
+  parentId?: string;
+  /** Free-form arguments, e.g. which variant a New menu chose. */
+  parameters?: Record<string, string>;
+  /**
+   * The sub-query New was started from (#460, D19), with `parentType` and `parentId` and no
+   * `asDetailAttribute`. The server loads the parent, checks the parent's type declares this
+   * sub-query, and runs `OnNewAsync` with it — whose base fills the reference to the parent.
+   */
+  queryId?: string;
+}
+/** Where a bulk delete was started from; see {@link SparkService.deleteMany}. */
+export interface DeleteManyOptions {
+  /** The query the rows were selected in, for the server's `OnDisableActionsAsync`. */
+  queryId?: string;
+  /** The sub-query's container, when deleting from a sub-query. */
+  parentId?: string;
+  parentType?: string;
 }
 /** Context for {@link SparkService.deleteRow}. Every field is required — see `DeleteRow.cs`. */
-interface DeleteRowOptions {
-    asDetailAttribute: string;
-    parentType: string;
-    parentId: string;
-    /** The row's `__sparkRowKey`, as it arrived from the server. */
-    rowKey: string;
-    parameters?: Record<string, string>;
+export interface DeleteRowOptions {
+  asDetailAttribute: string;
+  parentType: string;
+  parentId: string;
+  /** The row's `__sparkRowKey`, as it arrived from the server. */
+  rowKey: string;
+  parameters?: Record<string, string>;
 }
-declare class SparkService {
-    #private;
-    private readonly config;
-    private readonly baseUrl;
-    private readonly http;
-    private readonly retryActionService;
-    /**
-     * How many prompts one request will answer before giving up. Matches the .NET client's
-     * `SparkClient.MaxRetryDepth`, and for the same reason: this is a termination bound, not a
-     * capacity one. Far above any real conversation (Fleet's longest is two) and far below anything
-     * that could hide a spin.
-     */
-    private static readonly MAX_RETRY_DEPTH;
-    private readonly dispatcher;
-    getEntityTypes(): Promise<EntityType[]>;
-    getEntityType(id: string): Promise<EntityType>;
-    getEntityTypeByClrType(clrType: string): Promise<EntityType | undefined>;
-    getPermissions(entityTypeId: string): Promise<EntityPermissions>;
-    getQueries(): Promise<SparkQuery[]>;
-    getQuery(id: string): Promise<SparkQuery>;
-    /**
-     * Resolves a query by name, fetching the catalogue at most once per service instance.
-     *
-     * Without the cache this costs a full `GET /spark/queries` per call, and a form with several
-     * reference attributes resolves them in parallel — so opening one page fetched the whole query
-     * catalogue N times over. The catalogue is per-caller and effectively static for a page's
-     * lifetime; the service is scoped to the app, so a permission change lands on the next load.
-     */
-    getQueryByName(name: string): Promise<SparkQuery | undefined>;
-    executeQuery(queryId: string, options?: ExecuteQueryOptions): Promise<QueryResult>;
-    /**
-     * The distinct values behind one column's filter panel (#431).
-     *
-     * `columns` carries the OTHER columns' current filters, so the values returned are the ones still
-     * reachable — offering a value that empties the grid the moment it is picked is worse than
-     * omitting it.
-     *
-     * An empty result means either "nothing matches" or "you may not enumerate this column". The two
-     * are deliberately indistinguishable, so there is nothing for a caller to branch on.
-     */
-    getDistinctValues(queryId: string, column: string, options?: {
-        search?: string;
-        columns?: QueryColumnFilter[];
-        parentId?: string;
-        parentType?: string;
-    }): Promise<DistinctValuesResult>;
-    /**
-     * Runs a query identified by name.
-     *
-     * It used to forward only the parent, dropping skip/take/search — so every reference picker and
-     * AsDetail reference column silently saw the server's default of 50 candidates, with no indication
-     * that the list was cut. A picker that omits the option you are looking for, and says nothing, is
-     * worse than one that fails.
-     */
-    executeQueryByName(queryName: string, options?: ExecuteQueryOptions): Promise<QueryResult>;
-    getProgramUnits(): Promise<ProgramUnitsConfiguration>;
-    get(type: string, id: string): Promise<PersistentObject>;
-    create(type: string, data: Partial<PersistentObject>): Promise<PersistentObject>;
-    update(type: string, id: string, data: Partial<PersistentObject>): Promise<PersistentObject>;
-    /**
-     * Asks the server to reshape an in-progress object after `triggeredBy`'s value changed.
-     *
-     * Writes nothing, but goes through the envelope like every other mutating call: a refresh may
-     * legitimately emit notifications, and may open the retry-action prompt.
-     *
-     * `triggeredBy` is the attribute's name. For a trigger inside an AsDetail row it is the same
-     * path form the inline validation errors use — `Jobs[2].ProfessionId`.
-     */
-    refresh(type: string, data: Partial<PersistentObject>, triggeredBy: string): Promise<PersistentObject>;
-    /**
-     * Asks the server to construct a new object of `type`, so `OnNewAsync` can default it.
-     *
-     * Writes nothing — the object comes back unsaved, and for an AsDetail row the parent still owns
-     * the save. Only called for a row type whose `serverSideRowLifecycle` is on; every other type
-     * keeps building its blank row locally, which is why switching the flag off costs no request.
-     *
-     * ⚠️ The row comes back **keyed**: the server constructs the CLR instance, so the row-key field
-     * initializer runs and `po.id` carries the key. Flattening it with `nestedPoToDict` therefore
-     * populates `__sparkRowKey`, and the row is matchable on save from the moment it is added — the
-     * whole reason this round-trip is worth a request.
-     */
-    newObject(type: string, options?: NewObjectOptions): Promise<PersistentObject>;
-    /**
-     * Asks whether a stored row may leave its parent's AsDetail collection.
-     *
-     * Deletes nothing: a resolved promise means the caller may splice the row out of the collection
-     * it is editing, and the removal is persisted with the parent. A hook that refuses rejects with a
-     * 400 whose `error.error.result.errors` carries the readable reason, exactly like a save.
-     *
-     * A POST — as everything is now. It used to be worth explaining: the framework's real delete route
-     * was a catch-all that would have swallowed a sibling DELETE. The catch-all is gone with the rest
-     * of the route variables.
-     */
-    deleteRow(type: string, options: DeleteRowOptions): Promise<void>;
-    delete(type: string, id: string): Promise<void>;
-    getCustomActions(objectTypeId: string): Promise<CustomActionDefinition[]>;
-    /**
-     * @param parent The object of THIS type the action is operating on — the detail-page invocation.
-     * @param selectedItemIds Row ids from a query. Ids, never row objects: a row is a projection.
-     * @param queryParent When invoked from a sub-query, the object whose detail page it was rendered
-     *   on — a DIFFERENT type (the cars listed on a company's page are Cars, the page is a Company).
-     *   Sent as id + type, exactly as the query endpoint names it, and resolved server-side under its
-     *   own type with its own Read gate.
-     * @param queryId The query the selection came from, so the server can re-run it narrowed to those
-     *   ids and hand the action the rows the grid actually had -- index-computed columns included.
-     */
-    executeCustomAction(objectTypeId: string, actionName: string, parent?: PersistentObject, selectedItemIds?: string[], queryParent?: {
-        id: string;
-        type: string;
-    }, queryId?: string): Promise<void>;
-    getLookupReferences(): Promise<LookupReferenceListItem[]>;
-    getLookupReference(name: string): Promise<LookupReference>;
-    addLookupReferenceValue(name: string, value: LookupReferenceValue): Promise<LookupReferenceValue>;
-    updateLookupReferenceValue(name: string, key: string, value: LookupReferenceValue): Promise<LookupReferenceValue>;
-    deleteLookupReferenceValue(name: string, key: string): Promise<void>;
-    private postWithEnvelope;
+export declare class SparkService {
+  #private;
+  private readonly config;
+  private readonly baseUrl;
+  private readonly http;
+  private readonly retryActionService;
+  /**
+   * How many prompts one request will answer before giving up. Matches the .NET client's
+   * `SparkClient.MaxRetryDepth`, and for the same reason: this is a termination bound, not a
+   * capacity one. Far above any real conversation (Fleet's longest is two) and far below anything
+   * that could hide a spin.
+   */
+  private static readonly MAX_RETRY_DEPTH;
+  private readonly dispatcher;
+  getEntityTypes(): Promise<EntityType[]>;
+  getEntityType(id: string): Promise<EntityType>;
+  getEntityTypeByClrType(clrType: string): Promise<EntityType | undefined>;
+  getPermissions(entityTypeId: string): Promise<EntityPermissions>;
+  getQueries(): Promise<SparkQuery[]>;
+  getQuery(id: string): Promise<SparkQuery>;
+  /**
+   * Resolves a query by name, fetching the catalogue at most once per service instance.
+   *
+   * Without the cache this costs a full `GET /spark/queries` per call, and a form with several
+   * reference attributes resolves them in parallel — so opening one page fetched the whole query
+   * catalogue N times over. The catalogue is per-caller and effectively static for a page's
+   * lifetime; the service is scoped to the app, so a permission change lands on the next load.
+   */
+  getQueryByName(name: string): Promise<SparkQuery | undefined>;
+  executeQuery(queryId: string, options?: ExecuteQueryOptions): Promise<QueryResult>;
+  /**
+   * The distinct values behind one column's filter panel (#431).
+   *
+   * `columns` carries the OTHER columns' current filters, so the values returned are the ones still
+   * reachable — offering a value that empties the grid the moment it is picked is worse than
+   * omitting it.
+   *
+   * An empty result means either "nothing matches" or "you may not enumerate this column". The two
+   * are deliberately indistinguishable, so there is nothing for a caller to branch on.
+   */
+  getDistinctValues(queryId: string, column: string, options?: {
+    /** Narrows the listed values themselves (the panel's own box). */
+    search?: string;
     /**
-     * A read: posts the request, and returns the response **as-is** rather than unwrapping an
-     * envelope.
-     *
-     * The read endpoints moved from GET to POST so their hooks could prompt, but their success
-     * responses are still bare — a `PersistentObject`, a `QueryResult`. Only the 449 is enveloped,
-     * because a retry has nowhere else to live. So this shares the retry loop with the mutating calls
-     * and nothing else.
+     * The grid's search term, what `executeQuery` sends as `search` (#460 M15): the values come only
+     * from the rows it matches, so a searched grid's panel lists what the grid shows.
      */
-    private sendRead;
-    private sendWithEnvelope;
-    private handleEnvelopeRetryError;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SparkService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<SparkService>;
+    querySearch?: string;
+    columns?: QueryColumnFilter[];
+    parentId?: string;
+    parentType?: string;
+    /** The same soft-deletion mode as the grid the panel belongs to (#460). */
+    deleted?: SparkDeletedFilter;
+    /** The same parent mode as the grid the panel belongs to (#460). */
+    parentDeleted?: SparkDeletedFilter;
+  }): Promise<DistinctValuesResult>;
+  /**
+   * Runs a query identified by name.
+   *
+   * It used to forward only the parent, dropping skip/take/search — so every reference picker and
+   * AsDetail reference column silently saw the server's default of 50 candidates, with no indication
+   * that the list was cut. A picker that omits the option you are looking for, and says nothing, is
+   * worse than one that fails.
+   */
+  executeQueryByName(queryName: string, options?: ExecuteQueryOptions): Promise<QueryResult>;
+  getProgramUnits(): Promise<ProgramUnitsConfiguration>;
+  /**
+   * Loads one object. `options.deleted` (#460) lets a `ViewDeleted` holder open a soft-deleted row
+   * from the recycle bin (`'include'` or `'only'`); without the right the server ignores it and a
+   * deleted row stays a 404. Omitted = exclude.
+   */
+  get(type: string, id: string, options?: {
+    deleted?: SparkDeletedFilter;
+  }): Promise<PersistentObject>;
+  create(type: string, data: Partial<PersistentObject>): Promise<PersistentObject>;
+  update(type: string, id: string, data: Partial<PersistentObject>): Promise<PersistentObject>;
+  /**
+   * Asks the server to reshape an in-progress object after `triggeredBy`'s value changed.
+   *
+   * Writes nothing, but goes through the envelope like every other mutating call: a refresh may
+   * legitimately emit notifications, and may open the retry-action prompt.
+   *
+   * `triggeredBy` is the attribute's name. For a trigger inside an AsDetail row it is the same
+   * path form the inline validation errors use — `Jobs[2].ProfessionId`.
+   */
+  refresh(type: string, data: Partial<PersistentObject>, triggeredBy: string): Promise<PersistentObject>;
+  /**
+   * Asks the server to construct a new object of `type`, so `OnNewAsync` can default it.
+   *
+   * Writes nothing — the object comes back unsaved, and for an AsDetail row the parent still owns
+   * the save. Called by the create page for every New (#460, D19: with `parentId`/`parentType`/
+   * `queryId` when started from a sub-query, whose base hook fills the parent reference), and for an
+   * AsDetail row only when its type's `serverSideRowLifecycle` is on; every other row type keeps
+   * building its blank row locally, which is why switching the flag off costs no request.
+   *
+   * ⚠️ The row comes back **keyed**: the server constructs the CLR instance, so the row-key field
+   * initializer runs and `po.id` carries the key. Flattening it with `nestedPoToDict` therefore
+   * populates `__sparkRowKey`, and the row is matchable on save from the moment it is added — the
+   * whole reason this round-trip is worth a request.
+   */
+  newObject(type: string, options?: NewObjectOptions): Promise<PersistentObject>;
+  /**
+   * Asks whether a stored row may leave its parent's AsDetail collection.
+   *
+   * Deletes nothing: a resolved promise means the caller may splice the row out of the collection
+   * it is editing, and the removal is persisted with the parent. A hook that refuses rejects with a
+   * 400 whose `error.error.result.errors` carries the readable reason, exactly like a save.
+   *
+   * A POST — as everything is now. It used to be worth explaining: the framework's real delete route
+   * was a catch-all that would have swallowed a sibling DELETE. The catch-all is gone with the rest
+   * of the route variables.
+   */
+  deleteRow(type: string, options: DeleteRowOptions): Promise<void>;
+  delete(type: string, id: string): Promise<void>;
+  /**
+   * Deletes several rows of one type in one request — the default Delete action on a selection
+   * (`POST /spark/po/delete-many`, #460 D18). All or nothing: a 404 means some row is missing or not
+   * yours to delete, a 403 that the server's `OnDisableActionsAsync` withholds Delete on the query or
+   * on one of the rows, a 400 that the selection breaks the rule or the 200-row cap.
+   */
+  deleteMany(type: string, ids: string[], options?: DeleteManyOptions): Promise<void>;
+  getCustomActions(objectTypeId: string): Promise<CustomActionDefinition[]>;
+  /**
+   * @param parent The object of THIS type the action is operating on — the detail-page invocation.
+   * @param selectedItemIds Row ids from a query. Ids, never row objects: a row is a projection.
+   * @param queryParent When invoked from a sub-query, the object whose detail page it was rendered
+   *   on — a DIFFERENT type (the cars listed on a company's page are Cars, the page is a Company).
+   *   Sent as id + type, exactly as the query endpoint names it, and resolved server-side under its
+   *   own type with its own Read gate.
+   * @param queryId The query the selection came from, so the server can re-run it narrowed to those
+   *   ids and hand the action the rows the grid actually had -- index-computed columns included.
+   * @returns What the action handed to `CustomActionArgs.SetResult` (#460, T5) -- the envelope's
+   *   `result` -- or `undefined` when it set nothing. The value is the action author's to shape: it
+   *   bypasses the server's redaction. A 403 means the action is disabled for this object, query or
+   *   selection (the server's `OnDisableActionsAsync` said so), distinct from a 404 for a row the
+   *   caller cannot see.
+   */
+  executeCustomAction<T = unknown>(objectTypeId: string, actionName: string, parent?: PersistentObject, selectedItemIds?: string[], queryParent?: {
+    id: string;
+    type: string;
+  }, queryId?: string): Promise<T | undefined>;
+  getLookupReferences(): Promise<LookupReferenceListItem[]>;
+  getLookupReference(name: string): Promise<LookupReference>;
+  addLookupReferenceValue(name: string, value: LookupReferenceValue): Promise<LookupReferenceValue>;
+  updateLookupReferenceValue(name: string, key: string, value: LookupReferenceValue): Promise<LookupReferenceValue>;
+  deleteLookupReferenceValue(name: string, key: string): Promise<void>;
+  /**
+   * Posts to an add-on package's endpoint under the Spark base URL (`/spark` + `path`) and unwraps
+   * the `ClientOperationEnvelope` exactly like the built-in mutations: operations are dispatched and
+   * a 449 retry opens the retry modal. For the ng-spark add-on entry points (`soft-delete`,
+   * `history`, `moderation`) whose server packages answer through core's envelope helpers
+   * (`SparkAddOnEndpoints`, #460).
+   */
+  postEnvelope<T>(path: string, body: Record<string, unknown>): Promise<T>;
+  private postWithEnvelope;
+  /**
+   * A read: posts the request, and returns the response **as-is** rather than unwrapping an
+   * envelope.
+   *
+   * The read endpoints moved from GET to POST so their hooks could prompt, but their success
+   * responses are still bare — a `PersistentObject`, a `QueryResult`. Only the 449 is enveloped,
+   * because a retry has nowhere else to live. So this shares the retry loop with the mutating calls
+   * and nothing else.
+   */
+  private sendRead;
+  private sendWithEnvelope;
+  private handleEnvelopeRetryError;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
 /**
  * The options every query execution takes.
@@ -205,17 +254,28 @@ declare class SparkService {
  * options as separate inline literals a field added to one silently failed to forward from the
  * other — which is how skip/take/search were once dropped for every reference picker.
  */
-interface ExecuteQueryOptions {
-    sortColumns?: SortColumn[];
-    parentId?: string;
-    parentType?: string;
-    skip?: number;
-    take?: number;
-    search?: string;
-    /** Per-column value filters (#431). Columns AND together; values within a column OR. */
-    columns?: QueryColumnFilter[];
+export interface ExecuteQueryOptions {
+  sortColumns?: SortColumn[];
+  parentId?: string;
+  parentType?: string;
+  skip?: number;
+  take?: number;
+  search?: string;
+  /** Per-column value filters (#431). Columns AND together; values within a column OR. */
+  columns?: QueryColumnFilter[];
+  /**
+   * Soft-deletion mode (#460): `exclude` (default), `include`, `only`. Sent only when set; the server
+   * honours a widening only for callers holding `ViewDeleted` on the type.
+   */
+  deleted?: SparkDeletedFilter;
+  /**
+   * The mode the PARENT (`parentId`/`parentType`) is resolved under (#460) — `include` for a sub-query
+   * on a deleted object's page, opened from the recycle bin. Independent of `deleted`, which stays the
+   * rows' filter. Honoured only for callers holding `ViewDeleted` on the parent's type; anyone else
+   * gets the same 404 a missing parent gives.
+   */
+  parentDeleted?: SparkDeletedFilter;
 }
-
 /**
  * R2-M12: SVG icon registry. The registry no longer accepts a raw string —
  * apps must pre-sanitize via `DomSanitizer.bypassSecurityTrustHtml` (or
@@ -228,29 +288,28 @@ interface ExecuteQueryOptions {
  * The built-in icons baked into the package are still bypass-trusted internally
  * because they're known-safe at build time.
  */
-declare class SparkIconRegistry {
-    private sanitizer;
-    private icons;
-    constructor();
-    /**
-     * Registers a pre-sanitized SVG icon. Callers MUST validate or explicitly
-     * trust the SVG before passing — for example:
-     *
-     * ```ts
-     * const safe = sanitizer.bypassSecurityTrustHtml(svgFromBuildTimeConstant);
-     * registry.register('app-logo', safe);
-     * ```
-     *
-     * For server-supplied SVG, prefer a strict allow-list parser (no `<script>`,
-     * no `on*` attributes, no `href="javascript:..."`) before trusting.
-     */
-    register(name: string, svg: SafeHtml): void;
-    get(name: string): SafeHtml | undefined;
-    has(name: string): boolean;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SparkIconRegistry, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<SparkIconRegistry>;
+export declare class SparkIconRegistry {
+  private sanitizer;
+  private icons;
+  constructor();
+  /**
+   * Registers a pre-sanitized SVG icon. Callers MUST validate or explicitly
+   * trust the SVG before passing — for example:
+   *
+   * ```ts
+   * const safe = sanitizer.bypassSecurityTrustHtml(svgFromBuildTimeConstant);
+   * registry.register('app-logo', safe);
+   * ```
+   *
+   * For server-supplied SVG, prefer a strict allow-list parser (no `<script>`,
+   * no `on*` attributes, no `href="javascript:..."`) before trusting.
+   */
+  register(name: string, svg: SafeHtml): void;
+  get(name: string): SafeHtml | undefined;
+  has(name: string): boolean;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkIconRegistry, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
-
 /**
  * A query's custom actions, reachable **without the grid that usually renders them**.
  *
@@ -274,44 +333,58 @@ declare class SparkIconRegistry {
  * It also does not cache. Actions depend on the caller, and a memo keyed by type id would survive
  * a sign-out.
  */
-declare class SparkQueryActionsService {
-    private readonly sparkService;
-    /**
-     * The custom actions of the query named by id or alias, already filtered to those that belong on
-     * a query surface.
-     *
-     * Returns an empty list — rather than throwing — when the query resolves to no entity type,
-     * because a caller rendering a toolbar wants "no buttons", not a broken page.
-     */
-    actionsFor(queryIdOrAlias: string): Promise<CustomActionDefinition[]>;
-    /**
-     * Runs one of those actions. `selectedItemIds` are row ids, exactly as the grid posts them —
-     * the server re-materializes each one through the same load path a detail page uses, so an id
-     * from anywhere is treated as caller input rather than as a verified row.
-     */
-    execute(queryIdOrAlias: string, actionName: string, options?: {
-        parent?: PersistentObject;
-        selectedItemIds?: string[];
-        /** For a sub-query: the object whose detail page it was rendered on. See SparkService. */
-        queryParent?: {
-            id: string;
-            type: string;
-        };
-    }): Promise<void>;
-    /**
-     * The query and the entity type its rows are mapped against — the two-step resolution both
-     * methods need, kept in one place so they cannot disagree about which type an action runs on.
-     */
-    private contextFor;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SparkQueryActionsService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<SparkQueryActionsService>;
+export declare class SparkQueryActionsService {
+  private readonly sparkService;
+  /**
+   * The custom actions of the query named by id or alias, already filtered to those that belong on
+   * a query surface.
+   *
+   * Returns an empty list — rather than throwing — when the query resolves to no entity type,
+   * because a caller rendering a toolbar wants "no buttons", not a broken page.
+   */
+  actionsFor(queryIdOrAlias: string): Promise<CustomActionDefinition[]>;
+  /**
+   * Runs one of those actions. `selectedItemIds` are row ids, exactly as the grid posts them —
+   * the server re-materializes each one through the same load path a detail page uses, so an id
+   * from anywhere is treated as caller input rather than as a verified row.
+   */
+  execute(queryIdOrAlias: string, actionName: string, options?: {
+    parent?: PersistentObject;
+    selectedItemIds?: string[];
+    /** For a sub-query: the object whose detail page it was rendered on. See SparkService. */
+    queryParent?: {
+      id: string;
+      type: string;
+    };
+  }): Promise<void>;
+  /**
+   * The query and the entity type its rows are mapped against — the two-step resolution both
+   * methods need, kept in one place so they cannot disagree about which type an action runs on.
+   */
+  private contextFor;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkQueryActionsService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
-
 /**
  * The header carrying the viewer's IANA timezone id, e.g. `Europe/Brussels`.
  * Must stay in lockstep with `RequestTimeZoneResolver.HeaderName` on the server.
  */
-declare const SPARK_TIMEZONE_HEADER = "X-Spark-Timezone";
+export declare const SPARK_TIMEZONE_HEADER = "X-Spark-Timezone";
+/**
+ * The default name of the cookie carrying the same id, for requests the browser makes without any
+ * script running first (a server-side render, a link opened from a mail). Must stay in lockstep
+ * with `SparkTimeZoneOptions.DefaultCookieName` (`Spark:TimeZone:CookieName`) on the server.
+ */
+export declare const SPARK_TIMEZONE_COOKIE = "spark-timezone";
+/** Options for {@link withSparkTimezone}. */
+export interface SparkTimezoneOptions {
+  /**
+   * The cookie to write the viewer's zone into; `false` writes none (the header is still sent).
+   * Defaults to {@link SPARK_TIMEZONE_COOKIE}. Use the same name as the server's
+   * `Spark:TimeZone:CookieName`.
+   */
+  cookieName?: string | false;
+}
 /**
  * Returns the browser's IANA zone id, or `null` when the environment cannot name one.
  *
@@ -319,23 +392,66 @@ declare const SPARK_TIMEZONE_HEADER = "X-Spark-Timezone";
  * so a server asked to render "next Tuesday at 09:00" from an offset captured today gets it wrong
  * across a DST boundary. A zone id carries the rules, not one sample of them.
  */
-declare function resolveBrowserTimeZone(): string | null;
+export declare function resolveBrowserTimeZone(): string | null;
 /**
- * Attaches {@link SPARK_TIMEZONE_HEADER} to same-origin requests.
+ * Builds the interceptor for {@link withSparkTimezone}. Exported for apps that compose their own
+ * `withInterceptors([...])`.
  *
  * **This does not participate in reading or writing timestamps.** A `DateTimeOffset` means an
- * instant, and the browser converts in both directions on those paths. The header exists for work
- * the server starts on its own — a scheduled export, a notification email — where there is no
- * browser in the loop to do the converting but the output still has to read as local time.
+ * instant, and the browser converts in both directions on those paths. The header and cookie exist
+ * for work the server does on its own — a scheduled export, a notification email, a server-side
+ * render — where there is no browser in the loop to do the converting but the output still has to
+ * read as local time.
+ *
+ * ⚠️ **Nothing happens on the server platform.** During a server-side render `Intl` names the Node
+ * process's zone (UTC in a container), and a header carrying it would win over the viewer's cookie
+ * on the server (spike S-TZ3, #460).
  */
-declare const sparkTimezoneInterceptor: HttpInterceptorFn;
+export declare function createSparkTimezoneInterceptor(options?: SparkTimezoneOptions): HttpInterceptorFn;
 /**
- * `provideHttpClient(...withSparkTimezone())` — registers {@link sparkTimezoneInterceptor}.
+ * Attaches {@link SPARK_TIMEZONE_HEADER} to same-origin requests and keeps the
+ * {@link SPARK_TIMEZONE_COOKIE} cookie current — with the default options. See
+ * {@link createSparkTimezoneInterceptor}.
+ */
+export declare const sparkTimezoneInterceptor: HttpInterceptorFn;
+/**
+ * `provideHttpClient(...withSparkTimezone())` — registers the timezone interceptor.
  *
  * Spreadable alongside `withSparkAuth()`:
  * `provideHttpClient(...withSparkAuth(), ...withSparkTimezone())`.
+ *
+ * The cookie is written on the first request the browser app makes, so the very first server-side
+ * render of a first visit has no cookie and renders in UTC.
+ */
+export declare function withSparkTimezone(options?: SparkTimezoneOptions): HttpFeature<HttpFeatureKind>[];
+/** The `history.state` key a list row link stores the list's own URL under. */
+export declare const SPARK_RETURN_URL_STATE_KEY = "sparkReturnUrl";
+/**
+ * Where a detail page goes back to after its row stops existing — a Delete, or a Purge from the
+ * recycle bin (#460).
+ *
+ * Neither "the start page" nor "the previous history entry" is the right answer: the first loses the
+ * user's place, the second may be the deleted row's edit page, or another site. The right answer is
+ * the list the row was opened from, so a list's row link records that list's URL in the navigation
+ * state ({@link stateForRowLink}); a detail page reached otherwise (a bookmark, a reference link)
+ * falls back to the row type's own list — its program-unit query, else any query over the type.
  */
-declare function withSparkTimezone(): HttpFeature<HttpFeatureKind>[];
-
-export { RetryActionService, SPARK_TIMEZONE_HEADER, SparkIconRegistry, SparkLanguageService, SparkQueryActionsService, SparkService, SparkStreamingService, resolveBrowserTimeZone, sparkTimezoneInterceptor, withSparkTimezone };
-export type { DeleteRowOptions, ExecuteQueryOptions, NewObjectOptions };
+export declare class SparkReturnNavigationService {
+  private readonly router;
+  private readonly spark;
+  /** Navigation state for a row link: the current URL (the list, with its `?deleted=` mode). */
+  stateForRowLink(): Record<string, string>;
+  /** The list URL the current detail page was opened from, when a row link recorded one. */
+  recordedReturnUrl(): string | null;
+  /**
+   * Navigates to the list the row came from, else to the type's list (`?deleted=only` kept when
+   * `deletedView`), else to the start page. `replaceUrl`: the gone row's page is not worth a Back.
+   */
+  returnToList(entityTypeName: string | null | undefined, options?: {
+    deletedView?: boolean;
+  }): Promise<void>;
+  /** `['/query', alias]` of the type's list: a menu (program-unit) query first, else any query. */
+  listRouteFor(entityTypeName: string): Promise<unknown[] | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<SparkReturnNavigationService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}