@decaf-ts/ui-decorators 0.18.0 → 0.19.0

package/lib/esm/user-requests/UserRequestHandler.js

@@ -0,0 +1,185 @@
+/**
+ * @module ui-decorators/user-requests/UserRequestHandler
+ * @summary Service-based base class for user request handlers.
+ * @description No Angular or DOM imports — safe for pure-Node (backend) bundles.
+ *
+ * Handlers extend `Service`, receive a rendering-engine facade as a
+ * `protected readonly` property and implement `handle`, either returning the
+ * resolved value or throwing (a `CancelledError` when the user cancels
+ * mid-request). Lookup and dispatch are static: `@userRequest(reference)`
+ * records the class as metadata and `UserRequestHandler.getHandler(reference)`
+ * / `UserRequestHandler.handle(request, renderingEngine)` resolve and run it,
+ * so no process-wide registry instance is needed.
+ */
+import { Service, } from "@decaf-ts/core";
+import { Metadata } from "@decaf-ts/decoration";
+import { InternalError } from "@decaf-ts/db-decorators";
+import { USER_REQUEST_KEY } from "./constants.js";
+import { CancelledError } from "./errors.js";
+/**
+ * @description Abstract base class for user request handlers.
+ *
+ * Handler methods follow the core `Service` golden rules: `handle` (and the
+ * lifecycle helpers `getInput`/`cancel`) accept rest contextual args
+ * (`...args: ContextualArgs<C>`) and obtain their `{ log, ctx, ctxArgs }` via
+ * `this.logCtx([request, ...args], this.handle, true)` — entry and resolution
+ * via `log.info`, transitions via `log.verbose`, payload details via
+ * `log.debug` and failures/cancellations via `log.error`. A `CancelledError`
+ * is thrown when the user cancels mid-request. `handle` is the one async
+ * method handlers override, returning the resolved value or throwing.
+ * @summary Service-based base class implementing the user request lifecycle.
+ * @template T The resolved payload type the handler returns.
+ * @template C The decaf context the service runs under.
+ */
+export class UserRequestHandler extends Service {
+    /**
+     * @description Creates a handler bound to the given rendering-engine facade.
+     * The facade is the only external dependency: no context/resolver
+     * indirection.
+     * @param {RenderingFacade} renderingEngine The rendering-engine surface the
+     * handler drives (modal, toast, spinner and router).
+     */
+    constructor(renderingEngine) {
+        super();
+        this.renderingEngine = renderingEngine;
+        this.cancelled = false;
+    }
+    /**
+     * @description Resolves the handler class registered for the given request
+     * reference via `Metadata`. Handlers are recorded by the `@userRequest`
+     * decorator under `USER_REQUEST_KEY`.
+     * @param {string} reference The request id/type the handler is registered
+     * for.
+     * @return {.Constructor<UserRequestHandler> | undefined}
+     * The registered handler constructor, or `undefined` when unknown.
+     */
+    static getHandler(reference) {
+        return Metadata.get(USER_REQUEST_KEY, reference);
+    }
+    /**
+     * @description Reads the `@userRequest` metadata recorded on a handler class
+     * via `Metadata`.
+     * @param {object} target The handler class to inspect.
+     * @return {UserRequestHandlerMetadata | undefined} The recorded metadata
+     * `{ reference }`, or `undefined` when the class is not decorated.
+     */
+    static getMetadata(target) {
+        return Metadata.get(target, USER_REQUEST_KEY);
+    }
+    static async handle(request, renderingEngine) {
+        const id = request.type || request.id;
+        const Handler = UserRequestHandler.getHandler(id);
+        if (!Handler)
+            throw new InternalError(`No user request handler registered for "${id}"`);
+        const instance = new Handler(renderingEngine);
+        const ctx = await instance.context("user-request", {});
+        return instance.handle(request, ctx);
+    }
+    async getInput(request, ...args) {
+        const { log } = await this.logCtx([request, ...args], this.getInput, true);
+        const component = { props: { request } };
+        log.info(`Requesting input for user request "${request.type || request.id}"`);
+        const modal = await this.renderingEngine.getModal(component);
+        this.currentModal = modal;
+        if (this.cancelled) {
+            this.currentModal = undefined;
+            await modal.cancel();
+            log.error(`User request "${request.type || request.id}" was cancelled`);
+            throw new CancelledError(`User request "${request.type || request.id}" was cancelled`);
+        }
+        return this.awaitDismissal(request, modal);
+    }
+    awaitDismissal(request, modal) {
+        return new Promise((resolve, reject) => {
+            this.submitted = resolve;
+            this.dismissed = reject;
+            const confirm = modal.confirm.bind(modal);
+            const cancel = modal.cancel.bind(modal);
+            modal.confirm = async (event) => {
+                try {
+                    await confirm(event);
+                    this.currentModal = undefined;
+                    const data = (event?.data ?? event);
+                    resolve(data);
+                }
+                catch (error) {
+                    // A facade confirms with an error payload (e.g. a `ValidationError`
+                    // from an invalid form submission) by throwing it out of `confirm`;
+                    // reject the pending request with that decaf error instead of
+                    // leaving it hanging.
+                    this.currentModal = undefined;
+                    reject(error);
+                }
+            };
+            modal.cancel = async () => {
+                await cancel();
+                this.currentModal = undefined;
+                reject(new CancelledError(`User request "${request.type || request.id}" was cancelled`));
+            };
+        });
+    }
+    async cancel(...args) {
+        const { log } = await this.logCtx(args, this.cancel, true);
+        log.info("Cancelling active user request");
+        this.cancelled = true;
+        const modal = this.currentModal;
+        this.currentModal = undefined;
+        if (this.dismissed) {
+            log.verbose("Rejecting pending user request with CancelledError");
+            this.dismissed(new CancelledError("User request was cancelled"));
+            this.dismissed = undefined;
+            this.submitted = undefined;
+        }
+        if (modal) {
+            log.debug("Dismissing the active user request modal");
+            await modal.cancel();
+        }
+        log.error("User request cancelled");
+    }
+    logCtx(args, operation, allowCreate = false, overrides) {
+        const base = super.logCtx(args, operation, allowCreate, overrides);
+        if (base instanceof Promise) {
+            return (async () => this.wrapLogContext(await base))();
+        }
+        return this.wrapLogContext(base);
+    }
+    /**
+     * @description Decorates the base contextual surface with the rendering
+     * engine methods exposed as `modal`/`toast`/`spinner`/`router` bound getters.
+     * @return {UserRequestLogContext<C, ARGS>} The decorated contextual surface.
+     * @template C The decaf context the service runs under.
+     * @template ARGS The contextual argument tuple passed to the call.
+     */
+    wrapLogContext(base) {
+        const engine = this.renderingEngine;
+        const result = {
+            log: base.log,
+            ctx: base.ctx,
+            ctxArgs: base.ctxArgs,
+        };
+        Object.defineProperties(result, {
+            modal: {
+                get: () => engine.getModal.bind(engine),
+                enumerable: true,
+                configurable: true,
+            },
+            toast: {
+                get: () => engine.getToast.bind(engine),
+                enumerable: true,
+                configurable: true,
+            },
+            spinner: {
+                get: () => engine.getSpinner.bind(engine),
+                enumerable: true,
+                configurable: true,
+            },
+            router: {
+                get: () => engine.router.bind(engine),
+                enumerable: true,
+                configurable: true,
+            },
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=UserRequestHandler.js.map

package/lib/esm/user-requests/UserRequestHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserRequestHandler.js","sourceRoot":"","sources":["../../../src/user-requests/UserRequestHandler.ts"],"names":[],"mappings":"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"}

package/lib/esm/user-requests/constants.js

@@ -0,0 +1,18 @@
+/**
+ * @module ui-decorators/user-requests/constants
+ * @summary Metadata keys for the User Request Resolution Engine.
+ */
+/**
+ * @description Metadata key under which user request handlers are registered
+ * and resolved.
+ * @summary The `@userRequest(reference)` decorator stores both the handler
+ * reference and the decorating metadata under this key, and
+ * `UserRequestHandler.getHandler` / `UserRequestHandler.getMetadata` read it
+ * back. The key is scoped to the User Request Resolution Engine to avoid
+ * colliding with other reflection metadata.
+ * @const USER_REQUEST_KEY
+ * @type {string}
+ * @readonly
+ */
+export const USER_REQUEST_KEY = "user-requests.handler";
+//# sourceMappingURL=constants.js.map

package/lib/esm/user-requests/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/user-requests/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC"}

package/lib/esm/user-requests/decorators.js

@@ -0,0 +1,37 @@
+/**
+ * @module ui-decorators/user-requests/decorators
+ * @summary `@userRequest(reference)` class decorator.
+ * @description No Angular or DOM imports — safe for pure-Node (backend)
+ * bundles. Registration is metadata-based: the decorator records the handler
+ * class under `USER_REQUEST_KEY` and the static `UserRequestHandler` methods
+ * resolve and dispatch it, so no process-wide registry is involved.
+ */
+import { Decoration, metadata, Metadata, } from "@decaf-ts/decoration";
+import { USER_REQUEST_KEY } from "./constants.js";
+/**
+ * @description Registers a handler class for the given request id/type.
+ *
+ * Mirrors `core/src/migrations/decorators.ts`:
+ * `Decoration.for(KEY).define({ decorator, args }).apply()` plus
+ * `Metadata.set(USER_REQUEST_KEY, reference, original)` so the class is
+ * retrievable by id via metadata — `UserRequestHandler.getHandler(reference)`
+ * reads it back and `UserRequestHandler.handle(request, renderingEngine)`
+ * dispatches it — and a class-level `metadata(...)` payload for
+ * introspection (`UserRequestHandler.getMetadata(target)`).
+ * @param {string} reference The request id/type the handler is registered for.
+ * @return {ClassDecorator} The class decorator to apply.
+ */
+export function userRequest(reference) {
+    function innerUserRequest(ref) {
+        return function userRequestDecorator(target) {
+            const constructor = target;
+            const meta = { reference: ref };
+            Metadata.set(USER_REQUEST_KEY, ref, constructor);
+            return metadata(USER_REQUEST_KEY, meta)(constructor);
+        };
+    }
+    return Decoration.for(USER_REQUEST_KEY)
+        .define({ decorator: innerUserRequest, args: [reference] })
+        .apply();
+}
+//# sourceMappingURL=decorators.js.map

package/lib/esm/user-requests/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../src/user-requests/decorators.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,UAAU,EACV,QAAQ,EACR,QAAQ,GACT,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,uBAAoB;AAG/C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,SAAS,gBAAgB,CAAC,GAAW;QACnC,OAAO,SAAS,oBAAoB,CAAC,MAAc;YACjD,MAAM,WAAW,GAAG,MAAqB,CAAC;YAC1C,MAAM,IAAI,GAA+B,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;YAC5D,QAAQ,CAAC,GAAG,CAAC,gBAAgB,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;YACjD,OAAO,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC,WAAW,CAAC,CAAC;QACvD,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC,GAAG,CAAC,gBAAgB,CAAC;SACpC,MAAM,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC;SAC1D,KAAK,EAAoB,CAAC;AAC/B,CAAC"}

package/lib/esm/user-requests/errors.js

@@ -0,0 +1,21 @@
+/**
+ * @module ui-decorators/user-requests/errors
+ * @summary Decaf error hierarchy for the User Request Resolution Engine.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+/**
+ * @description Error thrown when the user cancels a user request mid-resolution.
+ * Follows the decaf error hierarchy: never a raw `Error`. Compatible with the
+ * validation error signaling used by `@devcerts/decaf` UI facades.
+ * @summary Error thrown when a user request is cancelled.
+ */
+export class CancelledError extends InternalError {
+    /**
+     * @param {string | Error | unknown} msg The cancellation message.
+     * @return {CancelledError} A new `CancelledError`.
+     */
+    constructor(msg = "User request cancelled") {
+        super(msg, CancelledError.name, 400);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/lib/esm/user-requests/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/user-requests/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,aAAa;IAC/C;;;OAGG;IACH,YAAY,MAAgC,wBAAwB;QAClE,KAAK,CAAC,GAAG,EAAE,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;CACF"}

package/lib/esm/user-requests/index.js

@@ -0,0 +1,16 @@
+/**
+ * @module ui-decorators/user-requests
+ * @summary Backend binding surface for the User Request Resolution Engine.
+ * @description Framework-agnostic core of the engine: no Angular or DOM
+ * imports, safe for pure-Node (backend) bundles. Handlers are registered via
+ * `@userRequest(reference)` (metadata) and resolved/dispatched through the
+ * static `UserRequestHandler` methods; example handlers and rendering-engine
+ * mocks live only in the test tree, never under `src`. Frontend bindings live
+ * in `for-angular`.
+ */
+export * from "./constants.js";
+export * from "./errors.js";
+export * from "./types.js";
+export * from "./UserRequestHandler.js";
+export * from "./decorators.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/user-requests/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/user-requests/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,+BAA4B;AAC5B,4BAAyB;AACzB,2BAAwB;AACxB,wCAAqC;AACrC,gCAA6B"}

package/lib/esm/user-requests/types.js

@@ -0,0 +1,8 @@
+/**
+ * @module ui-decorators/user-requests/types
+ * @summary Framework-agnostic contracts for the User Request Resolution Engine.
+ * @description No Angular or DOM imports are allowed here so the `user-requests`
+ * entry point stays consumable from pure-Node (backend) bundles.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/esm/user-requests/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/user-requests/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/lib/types/graph/constants.d.cts

@@ -37,6 +37,11 @@ export type GraphNodeMetadata = {
      * (the one-vs-all toggle). See {@link GraphPortGroupMetadata}.
      */
     portGroups?: GraphPortGroupMetadata[];
+    /**
+     * Node I/O inspection hints (DECAF-48 §4.6) — viewer mode and which ports
+     * map to the inputs/outputs panes. Frontend-safe metadata only.
+     */
+    inspection?: GraphNodeIoMetadata;
 };
 export type GraphWorkflowNodeMetadata = {
     id: string;
@@ -45,7 +50,68 @@ export type GraphWorkflowNodeMetadata = {
     description?: string;
     node?: unknown;
     metadata?: Record<string, unknown>;
+    /**
+     * Node I/O inspection hints for this workflow instance (DECAF-48 §4.6).
+     * Frontend-safe metadata only.
+     */
+    inspection?: GraphNodeIoMetadata;
+};
+/**
+ * A view-mode choice for the reusable I/O viewer (DECAF-48 §4.6 / Req-9).
+ * One shared component renders both the inputs and outputs panes.
+ */
+export type GraphNodeIoViewMode = "json" | "table" | "raw";
+/**
+ * Node I/O inspection metadata (DECAF-48 §4.6) — hints the workflow canvas
+ * uses to open the inline split view for an already-ran node. Framework
+ * neutral, frontend-safe, no engine/runtime dependency (DECAF-24 §4).
+ */
+export type GraphNodeIoMetadata = {
+    /** Default view mode for the reusable viewer. Defaults to "json". */
+    view?: GraphNodeIoViewMode;
+    /** Port property names shown in the right-side inputs pane. */
+    inputPorts?: string[];
+    /** Port property names shown in the left-side outputs pane. */
+    outputPorts?: string[];
+    /** Whether the node exposes editable config (opens the edit modal instead). */
+    editable?: boolean;
+    /** Free-form extension points. */
+    metadata?: Record<string, unknown>;
 };
+/**
+ * Visual treatment for a node/edge execution state (DECAF-48 §4.4). Maps a
+ * {@link GraphVisualState} value to the faded glow / fade-after-fail overlay
+ * colours used by the canvas renderer.
+ */
+export type GraphVisualStyle = {
+    /** Visual state string as defined by the shared `GraphVisualState` values (e.g. `"running"`, `"blocked"`). */
+    state: string;
+    /** Glow/border colour for the live run-feedback overlay. */
+    glow?: string;
+    /** Level of fade for unexecuted/disabled rendering (0..1). */
+    opacity?: number;
+    /** Optional fill colour when the node is in this state. */
+    color?: string;
+};
+/**
+ * The default visual-state → overlay mapping contract (DECAF-48 §4.4):
+ * running=faded green, blocked=yellow, errored=red; succeeded keeps the
+ * node's own accent; unexecuted-after-failure fades/disabled. This is the
+ * shared, framework-neutral source of truth that supersedes the DECAF-32
+ * §21.9 running colour for the live run-feedback overlay (§4.5).
+ */
+export declare const GRAPH_VISUAL_STATE_STYLES: {
+    [state: string]: Omit<GraphVisualStyle, "state">;
+};
+/**
+ * Resolves the visual style overlay for a node/edge execution state, falling
+ * back to a neutral default when the state is unknown or unregistered.
+ *
+ * @param state - The visual state string (as defined by the shared
+ * `GraphVisualState` values, e.g. `"running"`, `"blocked"`).
+ * @returns The style overlay for the given state.
+ */
+export declare function graphVisualStyleOf(state: string): Omit<GraphVisualStyle, "state">;
 export type GraphWorkflowRelationMetadata = {
     source: string | unknown;
     sourcePort?: string;

package/lib/types/graph/constants.d.mts

@@ -37,6 +37,11 @@ export type GraphNodeMetadata = {
      * (the one-vs-all toggle). See {@link GraphPortGroupMetadata}.
      */
     portGroups?: GraphPortGroupMetadata[];
+    /**
+     * Node I/O inspection hints (DECAF-48 §4.6) — viewer mode and which ports
+     * map to the inputs/outputs panes. Frontend-safe metadata only.
+     */
+    inspection?: GraphNodeIoMetadata;
 };
 export type GraphWorkflowNodeMetadata = {
     id: string;
@@ -45,7 +50,68 @@ export type GraphWorkflowNodeMetadata = {
     description?: string;
     node?: unknown;
     metadata?: Record<string, unknown>;
+    /**
+     * Node I/O inspection hints for this workflow instance (DECAF-48 §4.6).
+     * Frontend-safe metadata only.
+     */
+    inspection?: GraphNodeIoMetadata;
+};
+/**
+ * A view-mode choice for the reusable I/O viewer (DECAF-48 §4.6 / Req-9).
+ * One shared component renders both the inputs and outputs panes.
+ */
+export type GraphNodeIoViewMode = "json" | "table" | "raw";
+/**
+ * Node I/O inspection metadata (DECAF-48 §4.6) — hints the workflow canvas
+ * uses to open the inline split view for an already-ran node. Framework
+ * neutral, frontend-safe, no engine/runtime dependency (DECAF-24 §4).
+ */
+export type GraphNodeIoMetadata = {
+    /** Default view mode for the reusable viewer. Defaults to "json". */
+    view?: GraphNodeIoViewMode;
+    /** Port property names shown in the right-side inputs pane. */
+    inputPorts?: string[];
+    /** Port property names shown in the left-side outputs pane. */
+    outputPorts?: string[];
+    /** Whether the node exposes editable config (opens the edit modal instead). */
+    editable?: boolean;
+    /** Free-form extension points. */
+    metadata?: Record<string, unknown>;
 };
+/**
+ * Visual treatment for a node/edge execution state (DECAF-48 §4.4). Maps a
+ * {@link GraphVisualState} value to the faded glow / fade-after-fail overlay
+ * colours used by the canvas renderer.
+ */
+export type GraphVisualStyle = {
+    /** Visual state string as defined by the shared `GraphVisualState` values (e.g. `"running"`, `"blocked"`). */
+    state: string;
+    /** Glow/border colour for the live run-feedback overlay. */
+    glow?: string;
+    /** Level of fade for unexecuted/disabled rendering (0..1). */
+    opacity?: number;
+    /** Optional fill colour when the node is in this state. */
+    color?: string;
+};
+/**
+ * The default visual-state → overlay mapping contract (DECAF-48 §4.4):
+ * running=faded green, blocked=yellow, errored=red; succeeded keeps the
+ * node's own accent; unexecuted-after-failure fades/disabled. This is the
+ * shared, framework-neutral source of truth that supersedes the DECAF-32
+ * §21.9 running colour for the live run-feedback overlay (§4.5).
+ */
+export declare const GRAPH_VISUAL_STATE_STYLES: {
+    [state: string]: Omit<GraphVisualStyle, "state">;
+};
+/**
+ * Resolves the visual style overlay for a node/edge execution state, falling
+ * back to a neutral default when the state is unknown or unregistered.
+ *
+ * @param state - The visual state string (as defined by the shared
+ * `GraphVisualState` values, e.g. `"running"`, `"blocked"`).
+ * @returns The style overlay for the given state.
+ */
+export declare function graphVisualStyleOf(state: string): Omit<GraphVisualStyle, "state">;
 export type GraphWorkflowRelationMetadata = {
     source: string | unknown;
     sourcePort?: string;

package/lib/types/index.d.cts

@@ -15,19 +15,19 @@ export * from "./ui/index.d.cts";
  * @const VERSION
  * @memberOf module:ui-decorators
  */
-export declare const VERSION = "0.17.11";
+export declare const VERSION = "0.18.0";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export declare const COMMIT = "bcc23e4";
+export declare const COMMIT = "23dcb33";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export declare const FULL_VERSION = "0.17.11-bcc23e4";
+export declare const FULL_VERSION = "0.18.0-23dcb33";
 export declare const PACKAGE_NAME = "@decaf-ts/ui-decorators";

package/lib/types/index.d.mts

@@ -15,19 +15,19 @@ export * from "./ui/index.d.mts";
  * @const VERSION
  * @memberOf module:ui-decorators
  */
-export declare const VERSION = "0.17.11";
+export declare const VERSION = "0.18.0";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export declare const COMMIT = "bcc23e4";
+export declare const COMMIT = "23dcb33";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export declare const FULL_VERSION = "0.17.11-bcc23e4";
+export declare const FULL_VERSION = "0.18.0-23dcb33";
 export declare const PACKAGE_NAME = "@decaf-ts/ui-decorators";

package/lib/types/user-requests/UserRequestHandler.d.cts

@@ -0,0 +1,117 @@
+/**
+ * @module ui-decorators/user-requests/UserRequestHandler
+ * @summary Service-based base class for user request handlers.
+ * @description No Angular or DOM imports — safe for pure-Node (backend) bundles.
+ *
+ * Handlers extend `Service`, receive a rendering-engine facade as a
+ * `protected readonly` property and implement `handle`, either returning the
+ * resolved value or throwing (a `CancelledError` when the user cancels
+ * mid-request). Lookup and dispatch are static: `@userRequest(reference)`
+ * records the class as metadata and `UserRequestHandler.getHandler(reference)`
+ * / `UserRequestHandler.handle(request, renderingEngine)` resolve and run it,
+ * so no process-wide registry instance is needed.
+ */
+import { Context, ContextFlags, ContextualArgs, FlagsOf, LoggerOf, MaybeContextualArg, MethodOrOperation, Service } from "@decaf-ts/core";
+import { Constructor } from "@decaf-ts/decoration";
+import type { RenderingFacade, UserRequest, UserRequestHandlerMetadata } from "./types.d.cts";
+/**
+ * @description Result of `UserRequestHandler.logCtx(...)`. Extends the
+ * standard `{ log, ctx, ctxArgs }` surface with the exact `RenderingEngine`
+ * methods a handler needs (`modal`/`toast`/`spinner`/`router`) wrapping the
+ * rendering engine handed to the handler constructor. The keys mirror the
+ * underlying engine methods without a `get` prefix, and no duplicated
+ * `UserRequest*` rendering types are introduced.
+ * @summary Contextual surface returned by `UserRequestHandler.logCtx(*, *, true)`.
+ * @template C The decaf context the handler service runs under.
+ * @template ARGS The contextual argument tuple passed to the call.
+ */
+export interface UserRequestLogContext<C extends Context<ContextFlags<any>> = Context<ContextFlags<any>>, ARGS extends any[] = any[]> {
+    log: LoggerOf<C>;
+    ctx: C;
+    ctxArgs: ContextualArgs<C, ARGS>;
+    readonly modal: RenderingFacade["getModal"];
+    readonly toast: RenderingFacade["getToast"];
+    readonly spinner: RenderingFacade["getSpinner"];
+    readonly router: RenderingFacade["router"];
+}
+/**
+ * @description Abstract base class for user request handlers.
+ *
+ * Handler methods follow the core `Service` golden rules: `handle` (and the
+ * lifecycle helpers `getInput`/`cancel`) accept rest contextual args
+ * (`...args: ContextualArgs<C>`) and obtain their `{ log, ctx, ctxArgs }` via
+ * `this.logCtx([request, ...args], this.handle, true)` — entry and resolution
+ * via `log.info`, transitions via `log.verbose`, payload details via
+ * `log.debug` and failures/cancellations via `log.error`. A `CancelledError`
+ * is thrown when the user cancels mid-request. `handle` is the one async
+ * method handlers override, returning the resolved value or throwing.
+ * @summary Service-based base class implementing the user request lifecycle.
+ * @template T The resolved payload type the handler returns.
+ * @template C The decaf context the service runs under.
+ */
+export declare abstract class UserRequestHandler<T = unknown, C extends Context<ContextFlags<any>> = Context<ContextFlags<any>>> extends Service<C> {
+    protected readonly renderingEngine: RenderingFacade;
+    private currentModal?;
+    private cancelled;
+    private submitted?;
+    private dismissed?;
+    /**
+     * @description Creates a handler bound to the given rendering-engine facade.
+     * The facade is the only external dependency: no context/resolver
+     * indirection.
+     * @param {RenderingFacade} renderingEngine The rendering-engine surface the
+     * handler drives (modal, toast, spinner and router).
+     */
+    protected constructor(renderingEngine: RenderingFacade);
+    /**
+     * @description Resolves the handler class registered for the given request
+     * reference via `Metadata`. Handlers are recorded by the `@userRequest`
+     * decorator under `USER_REQUEST_KEY`.
+     * @param {string} reference The request id/type the handler is registered
+     * for.
+     * @return {.Constructor<UserRequestHandler> | undefined}
+     * The registered handler constructor, or `undefined` when unknown.
+     */
+    static getHandler(reference: string): Constructor<UserRequestHandler> | undefined;
+    /**
+     * @description Reads the `@userRequest` metadata recorded on a handler class
+     * via `Metadata`.
+     * @param {object} target The handler class to inspect.
+     * @return {UserRequestHandlerMetadata | undefined} The recorded metadata
+     * `{ reference }`, or `undefined` when the class is not decorated.
+     */
+    static getMetadata(target: object): UserRequestHandlerMetadata | undefined;
+    static handle<T = unknown>(request: UserRequest<T>, renderingEngine: RenderingFacade): Promise<T>;
+    protected getInput(request: UserRequest<T>, ...args: ContextualArgs<C>): Promise<T>;
+    private awaitDismissal;
+    cancel(...args: ContextualArgs<C> | []): Promise<void>;
+    abstract handle(request: UserRequest<T>, ...args: ContextualArgs<C>): Promise<T>;
+    /**
+     * @description Logging + rendering-engine methods for a call. Mirrors the
+     * `Service` `logCtx` contract and exposes `modal`/`toast`/`spinner`/`router`
+     * getters wrapping the rendering engine.
+     * @param {MaybeContextualArg<C, ARGS>} args Contextual args (context at the
+     * end, or pre-args plus context).
+     * @param {METHOD} operation The operation the context is created for.
+     * @param {boolean} allowCreate Whether a context is created when none is
+     * provided.
+     * @param {Partial<FlagsOf<CONTEXT>>} overrides Optional flag overrides.
+     * @return {UserRequestLogContext<C, ARGS> | Promise<UserRequestLogContext<C, ARGS>>}
+     * The contextual surface (or a promise of it when `allowCreate` is true).
+     * @template C The decaf context the service runs under.
+     * @template ARGS The contextual argument tuple passed to the call.
+     * @template CONTEXT The context type to promote to when creating one.
+     * @template METHOD The operation the context is created for.
+     */
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<C, ARGS>, operation: METHOD): UserRequestLogContext<C, ARGS>;
+    protected logCtx<CONTEXT extends Context<any> = C, ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<CONTEXT, ARGS>, operation: METHOD, allowCreate: false, overrides?: Partial<FlagsOf<CONTEXT>>): UserRequestLogContext<C, ARGS>;
+    protected logCtx<CONTEXT extends Context<any> = C, ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<CONTEXT, ARGS>, operation: METHOD, allowCreate: true, overrides?: Partial<FlagsOf<CONTEXT>>): Promise<UserRequestLogContext<C, ARGS>>;
+    /**
+     * @description Decorates the base contextual surface with the rendering
+     * engine methods exposed as `modal`/`toast`/`spinner`/`router` bound getters.
+     * @return {UserRequestLogContext<C, ARGS>} The decorated contextual surface.
+     * @template C The decaf context the service runs under.
+     * @template ARGS The contextual argument tuple passed to the call.
+     */
+    private wrapLogContext;
+}