@mintplayer/ng-spark 0.3.0 → 22.0.0

package/types/mintplayer-ng-spark-client-operations.d.ts

@@ -0,0 +1,170 @@
+import { PersistentObject } from '@mintplayer/ng-spark/models';
+import * as i0 from '@angular/core';
+import { InjectionToken, EnvironmentProviders } from '@angular/core';
+
+declare enum NotificationKind {
+    Info = 0,
+    Success = 1,
+    Warning = 2,
+    Error = 3
+}
+interface NavigateOperation {
+    type: 'navigate';
+    objectTypeId?: string;
+    id?: string;
+    routeName?: string;
+}
+interface NotifyOperation {
+    type: 'notify';
+    message: string;
+    kind: NotificationKind;
+    durationMs?: number;
+}
+interface RefreshAttributeOperation {
+    type: 'refreshAttribute';
+    objectTypeId: string;
+    id: string;
+    attributeName: string;
+    value?: unknown;
+}
+interface RefreshQueryOperation {
+    type: 'refreshQuery';
+    queryId: string;
+}
+type DisableTarget = {
+    kind: 'persistentObject';
+    objectTypeId: string;
+    id: string;
+} | {
+    kind: 'query';
+    queryId: string;
+} | {
+    kind: 'currentResponse';
+} | {
+    kind: 'session';
+};
+interface DisableActionOperation {
+    type: 'disableAction';
+    actionName: string;
+    target: DisableTarget;
+}
+interface RetryOperation {
+    type: 'retry';
+    step: number;
+    title: string;
+    options: string[];
+    defaultOption?: string | null;
+    persistentObject?: PersistentObject | null;
+    message?: string | null;
+}
+/**
+ * Discriminated union of known operation types, plus an open shape for unknown
+ * future operations. Handlers should narrow via the `type` discriminator before
+ * accessing fields specific to their operation type.
+ */
+type ClientOperation = NavigateOperation | NotifyOperation | RefreshAttributeOperation | RefreshQueryOperation | DisableActionOperation | RetryOperation | {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * Wire envelope returned by every action endpoint. `result` carries the primary
+ * payload (the PersistentObject for a Create, the QueryResult for an Execute,
+ * etc.); `operations` carries the side-effects the frontend dispatches.
+ */
+interface ClientOperationEnvelope<T = unknown> {
+    result: T | null;
+    operations: ClientOperation[];
+}
+
+/**
+ * Routes received operations to registered handlers. Unknown operation types
+ * (no matching registration) are silently dropped — this is the forward-compat
+ * contract that lets new operation types ship server-side without coordinated
+ * client updates.
+ *
+ * Last-registered-wins on duplicate `type` values, matching standard
+ * Angular multi-provider override semantics.
+ *
+ * R2-H19 — security contract for handler authors:
+ *   The dispatcher treats handler resolution as allow-list-by-type (unknown
+ *   types drop). It does NOT validate the *content* of each operation. Handlers
+ *   that act on URL-shaped fields (navigate, redirect, openWindow) MUST run
+ *   the value through `sanitizeReturnUrl` from `@mintplayer/ng-spark-auth/models`
+ *   (or an equivalent same-origin check) before acting on it. Otherwise a
+ *   single attribute-echo XSS or a single mid-channel byte flip on a non-TLS
+ *   path lets the server drive client navigation to an attacker host. The
+ *   built-in `notify` handler renders via Angular interpolation (escaped) so
+ *   it's safe to pass through, but anything more powerful must validate.
+ */
+declare class SparkClientOperationDispatcher {
+    private readonly handlerMap;
+    constructor();
+    dispatch(operations: readonly ClientOperation[] | null | undefined): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SparkClientOperationDispatcher, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SparkClientOperationDispatcher>;
+}
+
+/**
+ * A handler for a specific operation type. Receives the operation and
+ * executes the side-effect (e.g. show a toast, navigate, refresh a query).
+ * Handlers should `as`-narrow the operation to the type they registered for.
+ */
+type ClientOperationHandler = (operation: ClientOperation) => void;
+/**
+ * One entry in the multi-provider registration. Apps can register custom
+ * handlers alongside the built-in ones to extend the operation set with
+ * app-specific operation types.
+ */
+interface ClientOperationHandlerRegistration {
+    type: string;
+    handler: ClientOperationHandler;
+}
+/**
+ * Multi-provider token. `provideSparkClientOperations()` registers the
+ * built-in handlers; apps can add their own with additional `multi: true`
+ * providers using this token.
+ */
+declare const SPARK_CLIENT_OPERATION_HANDLERS: InjectionToken<readonly ClientOperationHandlerRegistration[]>;
+
+interface SparkToast {
+    id: string;
+    message: string;
+    kind: NotificationKind;
+    durationMs: number;
+}
+/**
+ * Holds the active toasts as a signal. The `<spark-toast-container>` component
+ * renders them; the built-in `notify` operation handler pushes new toasts here.
+ *
+ * Auto-dismissal: each toast schedules its own removal after `durationMs`. Pass
+ * `0` to make a toast sticky (manual dismissal only).
+ */
+declare class SparkNotificationService {
+    private readonly _toasts;
+    readonly toasts: i0.Signal<readonly SparkToast[]>;
+    show(message: string, kind?: NotificationKind, durationMs?: number): void;
+    dismiss(id: string): void;
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SparkNotificationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SparkNotificationService>;
+}
+
+declare class SparkToastContainerComponent {
+    protected readonly notifications: SparkNotificationService;
+    protected readonly Kind: typeof NotificationKind;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SparkToastContainerComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SparkToastContainerComponent, "spark-toast-container", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Registers the built-in client-operation handlers. Currently registers `notify`;
+ * additional types (`navigate`, `refreshQuery`, `refreshAttribute`, `disableAction`)
+ * land in subsequent commits. Apps add this once in their bootstrap providers.
+ *
+ * To register custom operation types alongside the built-ins, add additional
+ * `multi: true` providers using <see cref="SPARK_CLIENT_OPERATION_HANDLERS" />.
+ */
+declare function provideSparkClientOperations(): EnvironmentProviders;
+
+export { NotificationKind, SPARK_CLIENT_OPERATION_HANDLERS, SparkClientOperationDispatcher, SparkNotificationService, SparkToastContainerComponent, provideSparkClientOperations };
+export type { ClientOperation, ClientOperationEnvelope, ClientOperationHandler, ClientOperationHandlerRegistration, DisableActionOperation, DisableTarget, NavigateOperation, NotifyOperation, RefreshAttributeOperation, RefreshQueryOperation, RetryOperation, SparkToast };

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

@@ -4,7 +4,7 @@ import * as _angular_core from '@angular/core';
 declare class SparkIconComponent {
     private registry;
     name: _angular_core.InputSignal<string>;
-    iconHtml: _angular_core.Signal<_angular_platform_browser.SafeHtml>;
+    iconHtml: _angular_core.Signal<_angular_platform_browser.SafeHtml | undefined>;
     cssFallbackClass: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkIconComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkIconComponent, "spark-icon", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;

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

@@ -35,6 +35,14 @@ declare enum ShowedOn {
  */
 declare function hasShowedOnFlag(value: ShowedOn | string | undefined, flag: ShowedOn): boolean;
 
+interface PersistentObject {
+    id: string;
+    name: string;
+    objectTypeId: string;
+    breadcrumb?: string;
+    attributes: PersistentObjectAttribute[];
+}
+
 interface PersistentObjectAttribute {
     id: string;
     name: string;
@@ -61,14 +69,23 @@ interface PersistentObjectAttribute {
     renderer?: string;
     /** Options passed to the renderer component */
     rendererOptions?: Record<string, any>;
-}
-
-interface PersistentObject {
-    id: string;
-    name: string;
-    objectTypeId: string;
-    breadcrumb?: string;
-    attributes: PersistentObjectAttribute[];
+    /**
+     * When `dataType === 'AsDetail'` and `isArray === false`: the single nested
+     * PersistentObject carrying the detail entity's values. `null` when the field is unset.
+     * Mirrors the server's PersistentObjectAttributeAsDetail.Object.
+     */
+    object?: PersistentObject | null;
+    /**
+     * When `dataType === 'AsDetail'` and `isArray === true`: the nested PO collection, one
+     * per array element. Mirrors PersistentObjectAttributeAsDetail.Objects.
+     */
+    objects?: PersistentObject[] | null;
+    /**
+     * CLR type name of the detail entity for AsDetail attributes (e.g. `HR.Entities.Address`).
+     * Emitted by the server so the frontend can look up the matching EntityType metadata
+     * without re-resolving through `asDetailType` on the schema definition.
+     */
+    asDetailType?: string;
 }
 
 interface EntityAttributeDefinition {
@@ -271,5 +288,32 @@ interface StreamingErrorMessage {
 }
 type StreamingMessage = StreamingSnapshotMessage | StreamingPatchMessage | StreamingErrorMessage;
 
-export { ELookupDisplayType, ShowedOn, currentLanguage, hasShowedOnFlag, resolveTranslation };
-export type { AttributeGroup, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryResult, RetryActionPayload, RetryActionResult, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };
+/**
+ * Resolves an `EntityType` by its CLR type name (e.g. `"HR.Entities.Address"`).
+ * Callers typically close over `sparkService.getEntityTypes()`'s cached list.
+ */
+type EntityTypeResolver = (clrTypeName: string) => EntityType | undefined;
+/**
+ * Flattens a nested `PersistentObject` into the plain `Record<string, any>` shape the
+ * form state uses throughout ng-spark. Primitive / reference attributes contribute their
+ * `value`; nested AsDetail attributes recurse — single becomes an inner dict, array
+ * becomes an array of inner dicts. Returns `{}` for `null` / `undefined` input.
+ *
+ * This is the ONE place that reads the server's new AsDetail wire shape and collapses it
+ * back to the flat dict the form components already handle.
+ */
+declare function nestedPoToDict(po: PersistentObject | null | undefined): Record<string, any>;
+/**
+ * Builds a nested `PersistentObject` from a flat dict against the schema in
+ * <paramref name="entityType"/>. Used when the form is about to save — AsDetail attributes
+ * are no longer sent as flat dicts in `attribute.value`; the server now requires
+ * `attribute.object` / `attribute.objects` with fully scaffolded nested POs.
+ *
+ * `resolve` walks through AsDetail types registered elsewhere (usually the full
+ * `getEntityTypes()` list, keyed by CLR type name). Nested AsDetail inside AsDetail is
+ * handled recursively.
+ */
+declare function dictToNestedPo(dict: Record<string, any> | null | undefined, entityType: EntityType, resolve: EntityTypeResolver): PersistentObject;
+
+export { ELookupDisplayType, ShowedOn, currentLanguage, dictToNestedPo, hasShowedOnFlag, nestedPoToDict, resolveTranslation };
+export type { AttributeGroup, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryResult, RetryActionPayload, RetryActionResult, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };

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

@@ -134,6 +134,14 @@ declare class IconNamePipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<IconNamePipe, "iconName", true>;
 }
 
+/**
+ * Resolves an attribute to a list of flat row dicts for the detail-page table.
+ * AsDetail array attributes carry their data as nested PersistentObjects in
+ * <c>attr.objects</c>, not <c>attr.value</c> — the server stopped putting flat
+ * dicts in <c>value</c> when AsDetail moved to its dedicated wire shape. Without
+ * this branch, the detail page rendered AsDetail arrays as empty tables even
+ * when the edit page (which reads <c>attr.objects</c> directly) showed rows.
+ */
 declare class ArrayValuePipe implements PipeTransform {
     transform(attrName: string, item: PersistentObject | null): Record<string, any>[];
     static ɵfac: i0.ɵɵFactoryDeclaration<ArrayValuePipe, never>;

package/types/mintplayer-ng-spark-po-create.d.ts

@@ -10,11 +10,12 @@ declare class SparkPoCreateComponent {
     saved: _angular_core.OutputEmitterRef<PersistentObject>;
     cancelled: _angular_core.OutputEmitterRef<void>;
     colors: typeof Color;
-    entityType: _angular_core.WritableSignal<EntityType>;
+    entityType: _angular_core.WritableSignal<EntityType | null>;
     type: _angular_core.WritableSignal<string>;
     formData: _angular_core.WritableSignal<Record<string, any>>;
     validationErrors: _angular_core.WritableSignal<ValidationError[]>;
     isSaving: _angular_core.WritableSignal<boolean>;
+    private allEntityTypes;
     generalErrors: _angular_core.Signal<ValidationError[]>;
     constructor();
     private onParamsChange;

package/types/mintplayer-ng-spark-po-detail.d.ts

@@ -1,23 +1,22 @@
 import * as _angular_core from '@angular/core';
 import { TemplateRef, Type } from '@angular/core';
 import { Color } from '@mintplayer/ng-bootstrap';
+import { SparkLanguageService } from '@mintplayer/ng-spark/services';
 import { PersistentObject, EntityType, CustomActionDefinition, LookupReference, EntityAttributeDefinition, AttributeTab, AttributeGroup, SparkQuery } from '@mintplayer/ng-spark/models';
-import { DatatableSettings } from '@mintplayer/ng-bootstrap/datatable';
-import { VirtualDatatableDataSource } from '@mintplayer/ng-bootstrap/virtual-datatable';
-import { PaginationResponse } from '@mintplayer/pagination';
+import { DatatableSettings, BsDatatableFetch } from '@mintplayer/ng-bootstrap/datatable';
 
 declare class SparkPoDetailComponent {
     private readonly route;
     private readonly router;
     private readonly sparkService;
-    private readonly lang;
+    protected readonly lang: SparkLanguageService;
     private readonly rendererRegistry;
     showCustomActions: _angular_core.InputSignal<boolean>;
-    extraActionsTemplate: _angular_core.InputSignal<TemplateRef<void>>;
+    extraActionsTemplate: _angular_core.InputSignal<TemplateRef<void> | null>;
     extraContentTemplate: _angular_core.InputSignal<TemplateRef<{
         $implicit: PersistentObject;
         entityType: EntityType;
-    }>>;
+    }> | null>;
     edited: _angular_core.OutputEmitterRef<void>;
     deleted: _angular_core.OutputEmitterRef<void>;
     customActionExecuted: _angular_core.OutputEmitterRef<{
@@ -25,10 +24,10 @@ declare class SparkPoDetailComponent {
         item: PersistentObject;
     }>;
     colors: typeof Color;
-    errorMessage: _angular_core.WritableSignal<string>;
-    entityType: _angular_core.WritableSignal<EntityType>;
+    errorMessage: _angular_core.WritableSignal<string | null>;
+    entityType: _angular_core.WritableSignal<EntityType | null>;
     allEntityTypes: _angular_core.WritableSignal<EntityType[]>;
-    item: _angular_core.WritableSignal<PersistentObject>;
+    item: _angular_core.WritableSignal<PersistentObject | null>;
     lookupReferenceOptions: _angular_core.WritableSignal<Record<string, LookupReference>>;
     asDetailTypes: _angular_core.WritableSignal<Record<string, EntityType>>;
     asDetailReferenceOptions: _angular_core.WritableSignal<Record<string, Record<string, PersistentObject[]>>>;
@@ -63,21 +62,20 @@ declare class SparkSubQueryComponent {
     queryId: _angular_core.InputSignal<string>;
     parentId: _angular_core.InputSignal<string>;
     parentType: _angular_core.InputSignal<string>;
-    query: _angular_core.WritableSignal<SparkQuery>;
-    entityType: _angular_core.WritableSignal<EntityType>;
+    query: _angular_core.WritableSignal<SparkQuery | null>;
+    entityType: _angular_core.WritableSignal<EntityType | null>;
     allEntityTypes: _angular_core.WritableSignal<EntityType[]>;
-    paginationData: _angular_core.WritableSignal<PaginationResponse<PersistentObject>>;
+    resultCount: _angular_core.WritableSignal<number | null>;
     lookupReferenceOptions: _angular_core.WritableSignal<Record<string, LookupReference>>;
     loading: _angular_core.WritableSignal<boolean>;
     canRead: _angular_core.WritableSignal<boolean>;
     settings: _angular_core.WritableSignal<DatatableSettings>;
-    virtualDataSource: _angular_core.WritableSignal<VirtualDatatableDataSource<PersistentObject>>;
-    virtualSettings: _angular_core.WritableSignal<DatatableSettings>;
+    fetchFn: _angular_core.WritableSignal<BsDatatableFetch<PersistentObject> | null>;
+    isVirtualScrolling: _angular_core.Signal<boolean>;
     visibleAttributes: _angular_core.Signal<EntityAttributeDefinition[]>;
     constructor();
     private loadData;
-    private loadPage;
-    onSettingsChange(): void;
+    private makeFetch;
     private loadLookupReferenceOptions;
     getColumnRendererComponent(attr: EntityAttributeDefinition): Type<any> | null;
     getColumnRendererInputs(item: PersistentObject, attr: EntityAttributeDefinition): Record<string, any>;

package/types/mintplayer-ng-spark-po-edit.d.ts

@@ -10,17 +10,19 @@ declare class SparkPoEditComponent {
     saved: _angular_core.OutputEmitterRef<PersistentObject>;
     cancelled: _angular_core.OutputEmitterRef<void>;
     colors: typeof Color;
-    entityType: _angular_core.WritableSignal<EntityType>;
-    item: _angular_core.WritableSignal<PersistentObject>;
+    entityType: _angular_core.WritableSignal<EntityType | null>;
+    item: _angular_core.WritableSignal<PersistentObject | null>;
     type: string;
     id: string;
     formData: _angular_core.WritableSignal<Record<string, any>>;
     validationErrors: _angular_core.WritableSignal<ValidationError[]>;
     isSaving: _angular_core.WritableSignal<boolean>;
+    private allEntityTypes;
     generalErrors: _angular_core.Signal<ValidationError[]>;
     constructor();
     private onParamsChange;
     initFormData(): void;
+    private resolveEntityType;
     getEditableAttributes(): _mintplayer_ng_spark_models.EntityAttributeDefinition[];
     onSave(): Promise<void>;
     onCancel(): void;

package/types/mintplayer-ng-spark-po-form.d.ts

@@ -9,33 +9,33 @@ declare class SparkPoFormComponent {
     private readonly sparkService;
     private readonly translations;
     private readonly rendererRegistry;
-    entityType: _angular_core.InputSignal<EntityType>;
+    entityType: _angular_core.InputSignal<EntityType | null>;
     formData: _angular_core.ModelSignal<Record<string, any>>;
     validationErrors: _angular_core.InputSignal<ValidationError[]>;
     showButtons: _angular_core.InputSignal<boolean>;
     isSaving: _angular_core.InputSignal<boolean>;
-    parentId: _angular_core.InputSignal<string>;
-    parentType: _angular_core.InputSignal<string>;
+    parentId: _angular_core.InputSignal<string | undefined>;
+    parentType: _angular_core.InputSignal<string | undefined>;
     save: _angular_core.OutputEmitterRef<void>;
     cancel: _angular_core.OutputEmitterRef<void>;
     colors: typeof Color;
     referenceOptions: _angular_core.WritableSignal<Record<string, PersistentObject[]>>;
     asDetailTypes: _angular_core.WritableSignal<Record<string, EntityType>>;
     lookupReferenceOptions: _angular_core.WritableSignal<Record<string, LookupReference>>;
-    editingAsDetailAttr: _angular_core.WritableSignal<EntityAttributeDefinition>;
+    editingAsDetailAttr: _angular_core.WritableSignal<EntityAttributeDefinition | null>;
     asDetailFormData: _angular_core.WritableSignal<Record<string, any>>;
     showAsDetailModal: _angular_core.WritableSignal<boolean>;
-    editingArrayIndex: _angular_core.WritableSignal<number>;
+    editingArrayIndex: _angular_core.WritableSignal<number | null>;
     asDetailPermissions: _angular_core.WritableSignal<Record<string, EntityPermissions>>;
     asDetailReferenceOptions: _angular_core.WritableSignal<Record<string, Record<string, PersistentObject[]>>>;
-    editingReferenceAttr: _angular_core.WritableSignal<EntityAttributeDefinition>;
+    editingReferenceAttr: _angular_core.WritableSignal<EntityAttributeDefinition | null>;
     showReferenceModal: _angular_core.WritableSignal<boolean>;
     referenceModalItems: _angular_core.WritableSignal<PersistentObject[]>;
-    referenceModalEntityType: _angular_core.WritableSignal<EntityType>;
-    referenceModalPagination: _angular_core.WritableSignal<PaginationResponse<PersistentObject>>;
+    referenceModalEntityType: _angular_core.WritableSignal<EntityType | null>;
+    referenceModalPagination: _angular_core.WritableSignal<PaginationResponse<PersistentObject> | undefined>;
     referenceModalSettings: _angular_core.WritableSignal<DatatableSettings>;
     referenceSearchTerm: string;
-    editingLookupAttr: _angular_core.WritableSignal<EntityAttributeDefinition>;
+    editingLookupAttr: _angular_core.WritableSignal<EntityAttributeDefinition | null>;
     showLookupModal: _angular_core.WritableSignal<boolean>;
     lookupModalItems: _angular_core.WritableSignal<LookupReferenceValue[]>;
     lookupSearchTerm: _angular_core.WritableSignal<string>;
@@ -47,6 +47,7 @@ declare class SparkPoFormComponent {
     groupsForTab(tab: AttributeTab): AttributeGroup[];
     attrsForGroup(group: AttributeGroup): EntityAttributeDefinition[];
     referenceVisibleAttributes: _angular_core.Signal<EntityAttributeDefinition[]>;
+    referenceModalRows: _angular_core.Signal<PersistentObject[]>;
     filteredLookupItems: _angular_core.Signal<LookupReferenceValue[]>;
     constructor();
     private toRecord;

package/types/mintplayer-ng-spark-query-list.d.ts

@@ -1,46 +1,56 @@
 import * as _angular_core from '@angular/core';
 import { TemplateRef, Type } from '@angular/core';
 import { Color } from '@mintplayer/ng-bootstrap';
-import { DatatableSettings } from '@mintplayer/ng-bootstrap/datatable';
-import { VirtualDatatableDataSource } from '@mintplayer/ng-bootstrap/virtual-datatable';
-import { PaginationResponse } from '@mintplayer/pagination';
-import { PersistentObject, SparkQuery, EntityType, LookupReference, EntityAttributeDefinition } from '@mintplayer/ng-spark/models';
+import { BsDatatableFetch, DatatableSettings } from '@mintplayer/ng-bootstrap/datatable';
+import { SparkLanguageService } from '@mintplayer/ng-spark/services';
+import { PersistentObject, CustomActionDefinition, SparkQuery, EntityType, LookupReference, EntityAttributeDefinition } from '@mintplayer/ng-spark/models';
 
 declare class SparkQueryListComponent {
     private readonly route;
     private readonly router;
     private readonly sparkService;
     private readonly streamingService;
+    protected readonly lang: SparkLanguageService;
     private readonly rendererRegistry;
     private readonly destroyRef;
-    extraActionsTemplate: _angular_core.InputSignal<TemplateRef<void>>;
+    extraActionsTemplate: _angular_core.InputSignal<TemplateRef<void> | null>;
+    showCustomActions: _angular_core.InputSignal<boolean>;
     rowClicked: _angular_core.OutputEmitterRef<PersistentObject>;
     createClicked: _angular_core.OutputEmitterRef<void>;
+    customActionExecuted: _angular_core.OutputEmitterRef<{
+        action: CustomActionDefinition;
+    }>;
     colors: typeof Color;
-    errorMessage: _angular_core.WritableSignal<string>;
-    query: _angular_core.WritableSignal<SparkQuery>;
-    entityType: _angular_core.WritableSignal<EntityType>;
+    errorMessage: _angular_core.WritableSignal<string | null>;
+    query: _angular_core.WritableSignal<SparkQuery | null>;
+    entityType: _angular_core.WritableSignal<EntityType | null>;
     allEntityTypes: _angular_core.WritableSignal<EntityType[]>;
     lookupReferenceOptions: _angular_core.WritableSignal<Record<string, LookupReference>>;
-    paginationData: _angular_core.WritableSignal<PaginationResponse<PersistentObject>>;
+    resultCount: _angular_core.WritableSignal<number | null>;
     searchTerm: string;
     canRead: _angular_core.WritableSignal<boolean>;
     canCreate: _angular_core.WritableSignal<boolean>;
+    customActions: _angular_core.WritableSignal<CustomActionDefinition[]>;
     isStreaming: _angular_core.WritableSignal<boolean>;
     private streamingSub;
     private allItems;
-    private filteredItems;
+    streamItems: _angular_core.WritableSignal<PersistentObject[]>;
+    fetchFn: _angular_core.WritableSignal<BsDatatableFetch<PersistentObject> | null>;
     settings: _angular_core.WritableSignal<DatatableSettings>;
-    virtualDataSource: _angular_core.WritableSignal<VirtualDatatableDataSource<PersistentObject>>;
-    virtualSettings: _angular_core.WritableSignal<DatatableSettings>;
     constructor();
     private onParamsChange;
+    onCustomAction(action: CustomActionDefinition): Promise<void>;
     private resolveEntityTypeForQuery;
     private extractSourceName;
     private singularize;
-    private initVirtualDataSource;
-    loadItems(): Promise<void>;
-    onSettingsChange(): void;
+    /**
+     * Builds the server-side fetch callback the datatable invokes per page/sort.
+     * Reads `searchTerm` live, so a settings change (or a new fetchFn identity)
+     * refetches with the current search term.
+     */
+    private makeFetch;
+    /** Force a refetch (e.g. after a custom action) without changing page/sort. */
+    private refresh;
     onSearchChange(): void;
     clearSearch(): void;
     isVirtualScrolling: _angular_core.Signal<boolean>;
@@ -54,7 +64,7 @@ declare class SparkQueryListComponent {
     private handleStreamingMessage;
     private applyFilter;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkQueryListComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkQueryListComponent, "spark-query-list", never, { "extraActionsTemplate": { "alias": "extraActionsTemplate"; "required": false; "isSignal": true; }; }, { "rowClicked": "rowClicked"; "createClicked": "createClicked"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkQueryListComponent, "spark-query-list", never, { "extraActionsTemplate": { "alias": "extraActionsTemplate"; "required": false; "isSignal": true; }; "showCustomActions": { "alias": "showCustomActions"; "required": false; "isSignal": true; }; }, { "rowClicked": "rowClicked"; "createClicked": "createClicked"; "customActionExecuted": "customActionExecuted"; }, never, never, true, never>;
 }
 
 export { SparkQueryListComponent };

package/types/mintplayer-ng-spark-retry-action-modal.d.ts

@@ -1,14 +1,43 @@
-import * as i0 from '@angular/core';
+import * as _angular_core from '@angular/core';
 import { Color } from '@mintplayer/ng-bootstrap';
 import { RetryActionService } from '@mintplayer/ng-spark/services';
+import { EntityType } from '@mintplayer/ng-spark/models';
 
+/**
+ * Renders a retry-action popup. Before PRD §3 this component rendered title / message /
+ * option buttons only and silently forwarded the incoming <c>persistentObject</c> back to
+ * the server on submit — meaning any <c>Retry.Action(..., persistentObject)</c> flow had
+ * no UI to actually edit the PO. This component now embeds the shared PO form so every
+ * scalar / Reference / AsDetail attribute on the scaffolded Virtual PO is a real form
+ * field, and the values the user fills in flow back to the server via
+ * <c>RetryResult.PersistentObject</c>.
+ */
 declare class SparkRetryActionModalComponent {
     protected readonly retryActionService: RetryActionService;
+    private readonly sparkService;
     colors: typeof Color;
-    isOpen: i0.Signal<boolean>;
+    isOpen: _angular_core.Signal<boolean>;
+    /**
+     * EntityType definition for the incoming PO — fetched lazily via SparkService so the
+     * form knows which attributes are editable, their labels, rules, renderers, etc.
+     * `null` when the payload has no persistentObject or its objectTypeId doesn't match
+     * any registered entity type (renders the modal as a simple option picker).
+     */
+    entityType: _angular_core.WritableSignal<EntityType | null>;
+    formData: _angular_core.WritableSignal<Record<string, any>>;
+    private allEntityTypes;
+    constructor();
+    private seedForm;
     onOption(option: string): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SparkRetryActionModalComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<SparkRetryActionModalComponent, "spark-retry-action-modal", never, {}, {}, never, never, true, never>;
+    /**
+     * Builds the PO the server sees under <c>Retry.Result.PersistentObject</c>. If the
+     * form resolved an EntityType, rebuild from the schema + formData (identical to the
+     * po-edit save path — AsDetail recursion included). Otherwise forward the incoming
+     * PO unmodified so pre-§3 flows without editable attributes keep working.
+     */
+    private populatedPersistentObject;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkRetryActionModalComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkRetryActionModalComponent, "spark-retry-action-modal", never, {}, {}, never, never, true, never>;
 }
 
 export { SparkRetryActionModalComponent };

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

@@ -6,7 +6,7 @@ import { SafeHtml } from '@angular/platform-browser';
 
 declare class RetryActionService {
     private resolveRetry;
-    payload: i0.WritableSignal<RetryActionPayload>;
+    payload: i0.WritableSignal<RetryActionPayload | null>;
     show(payload: RetryActionPayload): Promise<RetryActionResult>;
     respond(result: RetryActionResult): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<RetryActionService, never>;
@@ -46,6 +46,7 @@ declare class SparkService {
     private readonly baseUrl;
     private readonly http;
     private readonly retryActionService;
+    private readonly dispatcher;
     getEntityTypes(): Promise<EntityType[]>;
     getEntityType(id: string): Promise<EntityType>;
     getEntityTypeByClrType(clrType: string): Promise<EntityType | undefined>;
@@ -78,19 +79,44 @@ declare class SparkService {
     addLookupReferenceValue(name: string, value: LookupReferenceValue): Promise<LookupReferenceValue>;
     updateLookupReferenceValue(name: string, key: string, value: LookupReferenceValue): Promise<LookupReferenceValue>;
     deleteLookupReferenceValue(name: string, key: string): Promise<void>;
-    private postWithRetry;
-    private putWithRetry;
-    private deleteWithRetry;
-    private handleRetryError;
+    private postWithEnvelope;
+    private putWithEnvelope;
+    private deleteWithEnvelope;
+    private sendWithEnvelope;
+    private handleEnvelopeRetryError;
     static ɵfac: i0.ɵɵFactoryDeclaration<SparkService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<SparkService>;
 }
 
+/**
+ * R2-M12: SVG icon registry. The registry no longer accepts a raw string —
+ * apps must pre-sanitize via `DomSanitizer.bypassSecurityTrustHtml` (or
+ * `parseSvg` to validate) before calling `register`. Treating the parameter
+ * as `SafeHtml` puts the explicit bypass decision in the caller's hands so a
+ * developer wiring server-supplied SVG (per-tenant branding fetched from a
+ * JSON endpoint) doesn't accidentally trust a `<svg><script>...</script>`
+ * payload.
+ *
+ * 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();
-    register(name: string, svg: string): void;
+    /**
+     * 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>;