mlform 0.1.2 → 0.1.4

package/dist/types/src/engine/errors.d.ts

@@ -0,0 +1,28 @@
+import { MLFormError } from '../../shared';
+import { FormValidationResult } from './types';
+export declare class EngineError extends MLFormError {
+    constructor(message: string);
+}
+export declare class RegistryError extends EngineError {
+    constructor(message: string);
+}
+export declare class ValidationError extends EngineError {
+    readonly result: FormValidationResult;
+    constructor(result: FormValidationResult);
+}
+export declare class SubmitError extends EngineError {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+export declare class ReportPayloadError extends SubmitError {
+    readonly reportId: string;
+    constructor(reportId: string, message: string, cause: unknown);
+}
+export declare class SubmissionAbortedError extends SubmitError {
+    readonly code: "ABORTED";
+    constructor(message?: string, cause?: unknown);
+}
+export declare const createAbortError: (reason?: string) => SubmissionAbortedError;
+export declare const isAbortLikeError: (error: unknown) => boolean;
+export { TransportError, transportErrorCodes } from '../../transport';
+export type { TransportErrorCode } from '../../transport';

package/dist/types/src/engine/explanations/controller.d.ts

@@ -0,0 +1,13 @@
+import { EngineStore } from '../state';
+import { ExplanationController, ExplanationDefinition, FormHooks, NormalizedExplanationConfig } from '../types';
+type CreateExplanationControllerOptions = {
+    config: NormalizedExplanationConfig;
+    definition: ExplanationDefinition;
+    store: EngineStore;
+    hooks: FormHooks | undefined;
+};
+export type InternalExplanationController = ExplanationController & {
+    reset(): void;
+};
+export declare const createExplanationController: ({ config, definition, store, hooks, }: CreateExplanationControllerOptions) => InternalExplanationController;
+export {};

package/dist/types/src/engine/explanations/index.d.ts

@@ -0,0 +1 @@
+export * from './controller';

package/dist/types/src/engine/fields/controller.d.ts

@@ -0,0 +1,30 @@
+import { EngineStore, InternalFieldState } from '../state';
+import { FieldController, FieldDefinition, FieldValidationResult, FormStatus, InactiveFieldPolicy, NormalizedFieldConfig } from '../types';
+type CreateFieldControllerOptions = {
+    config: NormalizedFieldConfig;
+    definition: FieldDefinition;
+    store: EngineStore;
+    getValues: () => Record<string, unknown>;
+    getSubmitCount: () => number;
+    getFormStatus: () => FormStatus;
+    onValueChange?: (fieldId: string, values: Record<string, unknown>) => void;
+};
+export type RefreshOptions = {
+    values?: Record<string, unknown>;
+    preserveValidationErrors?: boolean;
+    preserveExternalErrors?: boolean;
+    resetInactiveToInitial?: boolean;
+    inactiveFieldPolicy?: InactiveFieldPolicy;
+};
+export type InternalFieldController = FieldController & {
+    serialize(): unknown;
+    refresh(options?: RefreshOptions): InternalFieldState;
+    applyValue(value: unknown, values: Record<string, unknown>): void;
+    prepareValue(value: unknown, values: Record<string, unknown>): InternalFieldState;
+    commitState(state: InternalFieldState): void;
+    setExternalErrors(errors: string[]): void;
+    coerceValue(value: unknown): unknown;
+    validate(validationVersion?: number): Promise<FieldValidationResult>;
+};
+export declare const createFieldController: ({ config, definition, store, getValues, getSubmitCount, getFormStatus, onValueChange, }: CreateFieldControllerOptions) => InternalFieldController;
+export {};

package/dist/types/src/engine/fields/index.d.ts

@@ -0,0 +1 @@
+export * from './controller';

package/dist/types/src/engine/form.d.ts

@@ -0,0 +1,2 @@
+import { CreateFormConfig, FormController } from './types';
+export declare const createForm: (config: CreateFormConfig) => FormController;

package/dist/types/src/engine/index.d.ts

@@ -0,0 +1,11 @@
+export { createBuiltinRegistry } from './builtins';
+export { booleanFieldDefinition, categoryFieldDefinition, classifierReportDefinition, dateFieldDefinition, longTextFieldDefinition, multiChoiceFieldDefinition, numberFieldDefinition, ratingFieldDefinition, regressorReportDefinition, seriesFieldDefinition, singleChoiceFieldDefinition, textFieldDefinition, } from './builtins';
+export { createExplanationController } from './explanations';
+export { executeExplanations, executeFormPipeline } from './submission';
+export { EngineError, ReportPayloadError, RegistryError, SubmissionAbortedError, SubmitError, TransportError, transportErrorCodes, ValidationError, } from './errors';
+export type { TransportErrorCode } from './errors';
+export { createForm } from './form';
+export { createRegistry, defineExplanationDefinition, defineExplanationKind, defineFieldKind, defineFieldDefinition, defineReportKind, defineReportDefinition, EngineRegistry, } from './registry';
+export { defaultEquality, shallowArrayEquality, shallowEquality, shallowObjectEquality, } from './equality';
+export { identity, isPromiseLike } from './utils';
+export type { AfterExplanationContext, AllConditions, AfterSubmitContext, AfterValidateContext, AnyConditions, BaseExplanationConfig, BaseFieldConfig, BaseReportConfig, DeclarativeExplanationKind, DeclarativeFieldKind, DeclarativeReportKind, BeforeSubmitContext, BeforeValidateContext, ExplanationFetchContext, ExplanationFetchFactory, CreateFormConfig, DeclarativeFieldCondition, ExplanationConfig, ExplanationController, ExplanationDefinition, ExplanationDescriptor, ExplanationDescriptorContext, ExplanationErrorContext, ExplanationExecutionContext, ExplanationExecutionResult, ExplanationFetchRequest, ExplanationFetchTransport, ExplanationRenderSpec, ExplanationRenderSpecContext, ExplanationStateSnapshot, ExplanationStatus, FieldRenderHints, FieldRenderSpec, FieldRenderSpecContext, FieldValidationFnContext, FieldValueAdapter, FieldWidget, FieldConfig, FieldComparisonCondition, FieldCondition, FieldConditionContext, FieldController, FieldDefinition, FieldDescriptor, FieldStateSnapshot, FieldStatus, FieldValueCondition, FieldValidationContext, FieldValidationResult, FormController, FormHooks, FormSchema, FormState, FormStatusCondition, FormStatus, FormValidator, FormValidationContext, FormValidationIssue, FormValidationResult, InactiveFieldPolicy, MaybePromise, NormalizedExplanationConfig, NormalizedFieldConfig, NormalizedReportConfig, Registry, ReportConfig, ReportController, ReportDefinition, ReportDescriptor, ReportRenderSpec, ReportRenderSpecContext, ReportResolveContext, ReportStateSnapshot, ReportStatus, PresentationNode, PresentationSummary, PipelineArtifactAdapter, PipelineArtifactContext, PipelineResult, ExecuteFormPipelineOptions, SelectorSubscriptionOptions, SubmitCountCondition, SubmitErrorContext, SubmitOptions, SubmitRequest, SubmitRequestTransportContext, SubmitResult, Transport, TransportAuthKind, TransportBackpressureMode, TransportCapabilities, TransportConsistency, TransportDeliveryMode, TransportPolicyContext, TransportSession, TransportSessionEvent, TransportSessionMessage, TransportStreamEvent, TransportResponse, NotCondition, } from './types';

package/dist/types/src/engine/paths.d.ts

@@ -0,0 +1,2 @@
+export declare const normalizeValuePath: (path: string | string[] | undefined, fallback: string) => string[];
+export declare const setPathValue: (target: Record<string, unknown>, path: readonly string[], value: unknown) => void;

package/dist/types/src/engine/registry/index.d.ts

@@ -0,0 +1,26 @@
+import { defineExplanationKind } from '../declarative/explanation';
+import { defineFieldKind } from '../declarative/field';
+import { defineReportKind } from '../declarative/report';
+import { ExplanationConfig, ExplanationDefinition, FieldConfig, FieldDefinition, Registry, ReportConfig, ReportDefinition } from '../types';
+export declare class EngineRegistry implements Registry {
+    private readonly fieldDefinitions;
+    private readonly reportDefinitions;
+    private readonly explanationDefinitions;
+    registerField<TConfig extends FieldConfig, TValue>(definition: FieldDefinition<TConfig, TValue>): Registry;
+    unregisterField(kind: string): Registry;
+    registerReport<TConfig extends ReportConfig>(definition: ReportDefinition<TConfig>): Registry;
+    unregisterReport(kind: string): Registry;
+    registerExplanation<TConfig extends ExplanationConfig>(definition: ExplanationDefinition<TConfig>): Registry;
+    unregisterExplanation(kind: string): Registry;
+    getField<TConfig extends FieldConfig = FieldConfig, TValue = unknown>(kind: string): FieldDefinition<TConfig, TValue> | undefined;
+    getReport<TConfig extends ReportConfig = ReportConfig>(kind: string): ReportDefinition<TConfig> | undefined;
+    getExplanation<TConfig extends ExplanationConfig = ExplanationConfig>(kind: string): ExplanationDefinition<TConfig> | undefined;
+    listFields(): FieldDefinition<FieldConfig, unknown>[];
+    listReports(): ReportDefinition<ReportConfig>[];
+    listExplanations(): ExplanationDefinition<ExplanationConfig>[];
+}
+export declare const createRegistry: () => Registry;
+export declare const defineFieldDefinition: <TConfig extends FieldConfig, TValue>(definition: FieldDefinition<TConfig, TValue>) => FieldDefinition<TConfig, TValue>;
+export declare const defineReportDefinition: <TConfig extends ReportConfig>(definition: ReportDefinition<TConfig>) => ReportDefinition<TConfig>;
+export declare const defineExplanationDefinition: <TConfig extends ExplanationConfig>(definition: ExplanationDefinition<TConfig>) => ExplanationDefinition<TConfig>;
+export { defineExplanationKind, defineFieldKind, defineReportKind };

package/dist/types/src/engine/reports/controller.d.ts

@@ -0,0 +1,19 @@
+import { EngineStore } from '../state';
+import { NormalizedReportConfig, PartialReportUpdatePolicy, ReportController, ReportDefinition, ReportStateSnapshot, SubmitResult } from '../types';
+type CreateReportControllerOptions = {
+    config: NormalizedReportConfig;
+    definition: ReportDefinition;
+    store: EngineStore;
+};
+export declare const cloneReportStateSnapshot: (definition: ReportDefinition, config: NormalizedReportConfig, state: ReportStateSnapshot) => ReportStateSnapshot;
+export type InternalReportController = ReportController & {
+    cloneState(state: ReportStateSnapshot): ReportStateSnapshot;
+    prepareState(result: SubmitResult): Promise<ReportStateSnapshot>;
+    commitState(state: ReportStateSnapshot): void;
+    update(result: SubmitResult): Promise<void>;
+    markLoading(): void;
+    reset(): void;
+    readonly partialUpdatePolicy: PartialReportUpdatePolicy;
+};
+export declare const createReportController: ({ config, definition, store, }: CreateReportControllerOptions) => InternalReportController;
+export {};

package/dist/types/src/engine/reports/index.d.ts

@@ -0,0 +1 @@
+export * from './controller';

package/dist/types/src/engine/schema/index.d.ts

@@ -0,0 +1,7 @@
+import { FormSchema, NormalizedExplanationConfig, NormalizedFieldConfig, NormalizedReportConfig, Registry } from '../types';
+export interface NormalizedFormSchema {
+    fields: NormalizedFieldConfig[];
+    reports: NormalizedReportConfig[];
+    explanations: NormalizedExplanationConfig[];
+}
+export declare const normalizeSchema: (schema: FormSchema, registry: Registry) => NormalizedFormSchema;

package/dist/types/src/engine/state/engine.d.ts

@@ -0,0 +1,60 @@
+import { ExplanationStateSnapshot, FieldStateSnapshot, FormStatus, ReportStateSnapshot, SubmissionProgressState, SubmitResult } from '../types';
+import { Store } from './store';
+export interface InternalFieldState extends FieldStateSnapshot {
+    syncErrors: string[];
+    validationErrors: string[];
+    externalErrors: string[];
+    validationVersion: number;
+}
+export interface EngineState {
+    status: FormStatus;
+    submitCount: number;
+    lastResult: SubmitResult | null;
+    formErrors: string[];
+    fieldStates: Record<string, InternalFieldState>;
+    reportStates: Record<string, ReportStateSnapshot>;
+    explanationStates: Record<string, ExplanationStateSnapshot>;
+    submissionProgress: SubmissionProgressState | null;
+    lifecycleVersion: number;
+    activeValidationVersion: number;
+    activeSubmissionVersion: number | null;
+}
+export type EngineStore = Store<EngineState>;
+export type EngineTransition = {
+    type: "bump-lifecycle";
+} | {
+    type: "rest";
+    status: "idle" | "editing";
+} | {
+    type: "editing";
+    clearFormErrors?: boolean;
+    bumpLifecycle?: boolean;
+} | {
+    type: "start-validation";
+    validationVersion: number;
+} | {
+    type: "validation-error";
+    message: string;
+} | {
+    type: "start-submission";
+    submissionVersion: number;
+} | {
+    type: "submission-stream-update";
+    progress: SubmissionProgressState;
+} | {
+    type: "submission-success";
+    result: SubmitResult;
+} | {
+    type: "submission-aborted";
+    message: string;
+} | {
+    type: "submission-error";
+    message: string;
+} | {
+    type: "clear-active-submission";
+    submissionVersion: number;
+} | {
+    type: "reset";
+};
+export declare const createInitialEngineState: () => EngineState;
+export declare const transitionEngineState: (current: EngineState, transition: EngineTransition) => EngineState;

package/dist/types/src/engine/state/index.d.ts

@@ -0,0 +1,3 @@
+export * from './engine';
+export * from './snapshots';
+export * from './store';

package/dist/types/src/engine/state/snapshots.d.ts

@@ -0,0 +1,5 @@
+import { FieldStateSnapshot, FormState } from '../types';
+import { EngineState, InternalFieldState } from './engine';
+export declare const toFieldStateSnapshot: (state: InternalFieldState) => FieldStateSnapshot;
+export declare const toFieldStateSnapshots: (fieldStates: Record<string, InternalFieldState>) => Record<string, FieldStateSnapshot>;
+export declare const toFormState: (state: EngineState) => FormState;

package/dist/types/src/engine/state/store.d.ts

@@ -0,0 +1,13 @@
+export interface Store<T> {
+    getState(): T;
+    setState(nextState: T): void;
+    update(updater: (current: T) => T): void;
+    batch(callback: () => void): void;
+    subscribe(listener: (state: T) => void): () => void;
+}
+type StoreOptions<T> = {
+    listenerErrorPolicy?: "ignore" | "throw-aggregate";
+    onListenerError?: (error: unknown, state: T) => void;
+};
+export declare const createStore: <T>(initialState: T, options?: StoreOptions<T>) => Store<T>;
+export {};

package/dist/types/src/engine/submission/abort.d.ts

@@ -0,0 +1,15 @@
+import { SubmitOptions } from '../types';
+export type SubmissionAbortManager = {
+    ensureIdle(): void;
+    begin(): number;
+    getCurrentRequestId(): number | null;
+    getAbortReason(requestId: number): string;
+    isAborted(requestId: number): boolean;
+    setActiveController(requestId: number, controller: AbortController | null): void;
+    createSignal(options?: SubmitOptions): AbortSignal;
+    attachExternalSignal(options: SubmitOptions | undefined, requestId: number): void;
+    abort(reason?: string): void;
+    clear(requestId: number): void;
+    reset(): void;
+};
+export declare const createSubmissionAbortManager: () => SubmissionAbortManager;

package/dist/types/src/engine/submission/explanations.d.ts

@@ -0,0 +1,2 @@
+import { ExplanationExecutionContext, ExplanationExecutionResult } from '../types';
+export declare const executeExplanations: ({ explanations, request, }: ExplanationExecutionContext) => Promise<ExplanationExecutionResult>;

package/dist/types/src/engine/submission/index.d.ts

@@ -0,0 +1,5 @@
+export * from './explanations';
+export * from './pipeline';
+export * from './request';
+export * from './reports';
+export * from './submitter';

package/dist/types/src/engine/submission/lifecycle.d.ts

@@ -0,0 +1,16 @@
+import { EngineStore } from '../state';
+import { SubmitResult } from '../types';
+type SubmissionTransitionOptions = {
+    store: EngineStore;
+    resetReports: () => void;
+    resetExplanations: () => void;
+    syncAfterSubmissionTransition: () => void;
+};
+export declare const createSubmissionLifecycle: ({ store, resetReports, resetExplanations, syncAfterSubmissionTransition, }: SubmissionTransitionOptions) => {
+    start(submissionVersion: number): void;
+    succeed(result: SubmitResult): void;
+    abort(message: string): void;
+    fail(message: string): void;
+    clear(submissionVersion: number): void;
+};
+export {};

package/dist/types/src/engine/submission/pipeline.d.ts

@@ -0,0 +1,2 @@
+import { ExecuteFormPipelineOptions, PipelineResult } from '../types';
+export declare const executeFormPipeline: <TArtifacts extends Record<string, unknown> = Record<string, never>>({ form, submit, artifactAdapter, explanationMode, }: ExecuteFormPipelineOptions<TArtifacts>) => Promise<PipelineResult<TArtifacts>>;

package/dist/types/src/engine/submission/reports.d.ts

@@ -0,0 +1,12 @@
+import { NormalizedReportConfig, PartialReportUpdatePolicy, ReportStateSnapshot, SubmitResult } from '../types';
+export type SubmissionReport = {
+    readonly id: string;
+    readonly config: NormalizedReportConfig;
+    readonly partialUpdatePolicy: PartialReportUpdatePolicy;
+    cloneState(state: ReportStateSnapshot): ReportStateSnapshot;
+    prepareState(result: SubmitResult): Promise<ReportStateSnapshot>;
+    commitState(state: ReportStateSnapshot): void;
+};
+export declare const prepareReportStates: (reports: readonly SubmissionReport[], baseResult: SubmitResult) => Promise<Map<string, ReportStateSnapshot>>;
+export declare const commitReportStates: (reports: readonly SubmissionReport[], nextReportStates: Map<string, ReportStateSnapshot>) => void;
+export declare const toSubmissionReportStates: (reports: readonly SubmissionReport[], nextReportStates: Map<string, ReportStateSnapshot>) => Record<string, ReportStateSnapshot>;

package/dist/types/src/engine/submission/request.d.ts

@@ -0,0 +1,23 @@
+import { NormalizedFieldConfig, TransportResponse } from '../types';
+type SubmissionField = {
+    readonly id: string;
+    readonly config: NormalizedFieldConfig;
+    readonly state: {
+        value: unknown;
+        visible: boolean;
+        disabled: boolean;
+    };
+    serialize(): unknown;
+};
+export type SubmissionValueRecords = {
+    values: Record<string, unknown>;
+    fieldValues: Record<string, unknown>;
+    serializedValues: Record<string, unknown>;
+    serializedFieldValues: Record<string, unknown>;
+};
+export declare const estimatePayloadBytes: (value: unknown) => number | undefined;
+export declare const cloneSubmissionValueRecords: (records: SubmissionValueRecords) => SubmissionValueRecords;
+export declare const shouldIncludeFieldInSubmission: (field: SubmissionField, resolveInactiveFieldPolicy: (field: SubmissionField) => "include" | "omit" | "reset-on-hide") => boolean;
+export declare const buildSubmissionValueRecords: (fields: readonly SubmissionField[], resolveInactiveFieldPolicy: (field: SubmissionField) => "include" | "omit" | "reset-on-hide") => SubmissionValueRecords;
+export declare const normalizeTransportResponse: (response: unknown) => TransportResponse;
+export {};

package/dist/types/src/engine/submission/result.d.ts

@@ -0,0 +1,4 @@
+import { SubmitResult } from '../types';
+import { SubmissionReport } from './reports';
+export declare const createSubmissionResult: (reports: readonly SubmissionReport[], baseResult: Omit<SubmitResult, "reportStates">, nextReportStates: Map<string, SubmitResult["reportStates"][string]>) => SubmitResult;
+export declare const cloneSubmissionResult: (reports: readonly SubmissionReport[], result: SubmitResult) => SubmitResult;

package/dist/types/src/engine/submission/submitter.d.ts

@@ -0,0 +1,40 @@
+import { NormalizedFormSchema } from '../schema';
+import { EngineStore } from '../state';
+import { FormHooks, FormValidationResult, InactiveFieldPolicy, SubmitOptions, SubmitResult, Transport } from '../types';
+import { buildSubmissionValueRecords } from './request';
+import { SubmissionReport } from './reports';
+type SubmissionField = Parameters<typeof buildSubmissionValueRecords>[0][number];
+type SyncDerivedFieldStateOptions = {
+    values?: Record<string, unknown>;
+    preserveValidationErrors?: boolean;
+    preserveExternalErrors?: boolean;
+    resetInactiveToInitial?: boolean;
+    inactiveFieldPolicy?: InactiveFieldPolicy;
+};
+type CreateFormSubmitterOptions = {
+    store: EngineStore;
+    transport: Transport;
+    hooks?: FormHooks;
+    hookFailurePolicy?: {
+        afterSubmit?: "fail-submit" | "preserve-success";
+    };
+    normalizedSchema: NormalizedFormSchema;
+    fields: readonly SubmissionField[];
+    reports: readonly SubmissionReport[];
+    validate: () => Promise<FormValidationResult>;
+    getSubmitCount: () => number;
+    markReportsLoading: () => void;
+    resetReports: () => void;
+    resetExplanations: () => void;
+    syncDerivedFieldState: (options?: SyncDerivedFieldStateOptions) => void;
+    shouldResetInactiveFields: () => boolean;
+    resolveInactiveFieldPolicy: (field: SubmissionField) => InactiveFieldPolicy;
+    inactiveFieldPolicy?: InactiveFieldPolicy;
+};
+export type FormSubmitter = {
+    submit(options?: SubmitOptions): Promise<SubmitResult>;
+    abort(reason?: string): void;
+    reset(): void;
+};
+export declare const createFormSubmitter: ({ store, transport, hooks, hookFailurePolicy, normalizedSchema, fields, reports, validate, getSubmitCount, markReportsLoading, resetReports, resetExplanations, syncDerivedFieldState, shouldResetInactiveFields, resolveInactiveFieldPolicy, inactiveFieldPolicy, }: CreateFormSubmitterOptions) => FormSubmitter;
+export {};

package/dist/types/src/engine/types/explanation.d.ts

@@ -0,0 +1,109 @@
+import { ZodType } from 'zod';
+import { PresentationContent, PresentationSummary } from '../declarative/presentation';
+export type ExplanationStatus = "idle" | "loading" | "done" | "error";
+export interface BaseExplanationConfig {
+    id?: string;
+    kind: string;
+    label?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+export type ExplanationConfig = BaseExplanationConfig;
+export type NormalizedExplanationConfig<TConfig extends ExplanationConfig = ExplanationConfig> = TConfig & {
+    id: string;
+};
+export interface ExplanationStateSnapshot {
+    status: ExplanationStatus;
+    result: unknown;
+    error: string | null;
+}
+export interface ExplanationDescriptor {
+    component: string;
+    props: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+}
+export interface ExplanationDescriptorContext {
+    explanationId: string;
+    state: ExplanationStateSnapshot;
+}
+export interface ExplanationFetchContext<TConfig extends ExplanationConfig = ExplanationConfig> {
+    config: NormalizedExplanationConfig<TConfig>;
+    explanationId: string;
+}
+/**
+ * Minimal transport interface used to fetch explanation data from an external
+ * service. Defined in engine types so ExplanationController can reference it
+ * without a circular dependency on the primitives layer.
+ */
+export interface ExplanationFetchRequest {
+    explanationId: string;
+    backend?: string;
+    values: Record<string, unknown>;
+    fieldValues: Record<string, unknown>;
+    serializedValues: Record<string, unknown>;
+    serializedFieldValues: Record<string, unknown>;
+    reports: Record<string, unknown>;
+    meta: Record<string, unknown>;
+    raw: unknown;
+    signal?: AbortSignal;
+}
+export interface ExplanationFetchTransport {
+    submit: (request: ExplanationFetchRequest) => Promise<unknown>;
+}
+export type ExplanationFetchFactory<TConfig extends ExplanationConfig = ExplanationConfig> = (context: ExplanationFetchContext<TConfig>) => ExplanationFetchTransport;
+export interface ExplanationRenderSpecContext<TConfig extends ExplanationConfig = ExplanationConfig, TResult = unknown> {
+    config: NormalizedExplanationConfig<TConfig>;
+    explanationId: string;
+    state: ExplanationStateSnapshot;
+    result: TResult;
+}
+export interface ExplanationRenderSpec<TConfig extends ExplanationConfig = ExplanationConfig, TResult = unknown> {
+    summary?: (context: ExplanationRenderSpecContext<TConfig, TResult>) => PresentationSummary | undefined;
+    content: (context: ExplanationRenderSpecContext<TConfig, TResult>) => PresentationContent;
+}
+export interface DeclarativeExplanationKind<TConfig extends ExplanationConfig = ExplanationConfig, TResult = unknown> {
+    kind: string;
+    schema: ZodType<TConfig>;
+    fetch: ExplanationFetchFactory<TConfig>;
+    render: ExplanationRenderSpec<TConfig, TResult>;
+}
+/**
+ * Plugin definition for an explanation kind. Each explanation plugin must
+ * provide a Zod schema for its config, a transport factory, and a describe
+ * function that returns a descriptor for primitive rendering.
+ */
+export interface ExplanationDefinition<TConfig extends ExplanationConfig = ExplanationConfig> {
+    kind: string;
+    schema: ZodType<TConfig>;
+    /**
+     * Factory that returns the transport used to fetch this explanation's data.
+     * Called with the normalized explanation config when a fetch is triggered.
+     */
+    transport: (config: TConfig) => ExplanationFetchTransport;
+    describe: (config: TConfig, context: ExplanationDescriptorContext) => ExplanationDescriptor | null;
+}
+/**
+ * Runtime controller for a single explanation instance. Tracks fetch
+ * lifecycle state and exposes a subscribe API consistent with
+ * FieldController / ReportController.
+ */
+export interface ExplanationController {
+    readonly id: string;
+    readonly kind: string;
+    readonly config: NormalizedExplanationConfig;
+    readonly state: ExplanationStateSnapshot;
+    readonly descriptor: ExplanationDescriptor | null;
+    /**
+     * Trigger an explanation fetch using the definition's transport. The
+     * request must contain the full submit result context; the controller
+     * appends an AbortSignal internally and combines it with any caller-provided
+     * signal.
+     * Idempotent when status is not "idle" — call reset() first to refetch.
+     */
+    fetch(request: ExplanationFetchRequest): Promise<void>;
+    /** Abort any in-flight fetch and reset state to "idle". */
+    abort(): void;
+    /** Reset state to "idle" without aborting (use before re-submission). */
+    reset(): void;
+    subscribe(listener: (state: ExplanationStateSnapshot) => void): () => void;
+}