@decaf-ts/ui-decorators 0.17.11 → 0.19.0

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.10";
+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 = "382e32c";
+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.10-382e32c";
+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.10";
+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 = "382e32c";
+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.10-382e32c";
+export declare const FULL_VERSION = "0.18.0-23dcb33";
 export declare const PACKAGE_NAME = "@decaf-ts/ui-decorators";

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

@@ -78,6 +78,9 @@ export declare const UIKeys: {
     TYPE: string;
     SUB_TYPE: string;
     HIDDEN: string;
+    HIDE_FOR: string;
+    SHOW_FOR: string;
+    RENDER_IF: string;
     FORMAT: string;
     ORDER: string;
     PAGE: string;

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

@@ -78,6 +78,9 @@ export declare const UIKeys: {
     TYPE: string;
     SUB_TYPE: string;
     HIDDEN: string;
+    HIDE_FOR: string;
+    SHOW_FOR: string;
+    RENDER_IF: string;
     FORMAT: string;
     ORDER: string;
     PAGE: string;

package/lib/types/ui/decorators.d.cts

@@ -36,6 +36,21 @@ import { CrudOperationKeys, UIEventHandler, UIEventName, UIFunctionLike, UILayou
  *   RenderingEngine->>UI: Render or hide based on current operation
  */
 export declare function hideOn(...operations: CrudOperationKeys[]): (object: any, propertyKey?: any) => any;
+/**
+ * @description Decorator that hides a property for specific namespaces.
+ * @summary Controls property visibility based on namespace membership.
+ */
+export declare function hideFor(...namespaces: string[]): (object: any, propertyKey?: any) => any;
+/**
+ * @description Decorator that shows a property only for specific namespaces.
+ * @summary Namespace-aware counterpart to `hideFor`.
+ */
+export declare function showFor(...namespaces: string[]): (object: any, propertyKey?: any) => any;
+/**
+ * @description Decorator that renders a property only when the namespace matches.
+ * @summary Convenience alias for namespace-scoped visibility control.
+ */
+export declare function renderIf(...namespaces: string[]): (object: any, propertyKey?: any) => any;
 /**
  * @description Decorator that sets the order of a UI element
  * @summary Specifies the rendering order for UI components

package/lib/types/ui/decorators.d.mts

@@ -36,6 +36,21 @@ import { CrudOperationKeys, UIEventHandler, UIEventName, UIFunctionLike, UILayou
  *   RenderingEngine->>UI: Render or hide based on current operation
  */
 export declare function hideOn(...operations: CrudOperationKeys[]): (object: any, propertyKey?: any) => any;
+/**
+ * @description Decorator that hides a property for specific namespaces.
+ * @summary Controls property visibility based on namespace membership.
+ */
+export declare function hideFor(...namespaces: string[]): (object: any, propertyKey?: any) => any;
+/**
+ * @description Decorator that shows a property only for specific namespaces.
+ * @summary Namespace-aware counterpart to `hideFor`.
+ */
+export declare function showFor(...namespaces: string[]): (object: any, propertyKey?: any) => any;
+/**
+ * @description Decorator that renders a property only when the namespace matches.
+ * @summary Convenience alias for namespace-scoped visibility control.
+ */
+export declare function renderIf(...namespaces: string[]): (object: any, propertyKey?: any) => any;
 /**
  * @description Decorator that sets the order of a UI element
  * @summary Specifies the rendering order for UI components

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;
+}

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

@@ -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.mts";
+/**
+ * @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;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * @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 declare const USER_REQUEST_KEY = "user-requests.handler";

package/lib/types/user-requests/constants.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @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 declare const USER_REQUEST_KEY = "user-requests.handler";

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

@@ -0,0 +1,22 @@
+/**
+ * @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.
+ */
+/**
+ * @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 declare function userRequest(reference: string): ClassDecorator;

package/lib/types/user-requests/decorators.d.mts

@@ -0,0 +1,22 @@
+/**
+ * @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.
+ */
+/**
+ * @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 declare function userRequest(reference: string): ClassDecorator;

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

@@ -0,0 +1,18 @@
+/**
+ * @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 declare class CancelledError extends InternalError {
+    /**
+     * @param {string | Error | unknown} msg The cancellation message.
+     * @return {CancelledError} A new `CancelledError`.
+     */
+    constructor(msg?: string | Error | unknown);
+}

package/lib/types/user-requests/errors.d.mts

@@ -0,0 +1,18 @@
+/**
+ * @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 declare class CancelledError extends InternalError {
+    /**
+     * @param {string | Error | unknown} msg The cancellation message.
+     * @return {CancelledError} A new `CancelledError`.
+     */
+    constructor(msg?: string | Error | unknown);
+}

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

@@ -0,0 +1,15 @@
+/**
+ * @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.d.cts";
+export * from "./errors.d.cts";
+export * from "./types.d.cts";
+export * from "./UserRequestHandler.d.cts";
+export * from "./decorators.d.cts";