@equinor/fusion-framework-module-widget 14.0.2-next.0 → 15.0.1

package/dist/types/state/actions.d.ts

@@ -1,11 +1,21 @@
 import { type ActionInstanceMap, type ActionTypes } from '@equinor/fusion-observable';
 import type { GetWidgetParameters, WidgetConfig, WidgetManifest, WidgetModulesInstance, WidgetScriptModule } from '../types';
+/**
+ * Factory that creates all widget state-machine actions.
+ *
+ * Each action (or async action triplet) drives a specific step in the
+ * widget lifecycle: manifest loading, config loading, script import,
+ * and initialization.
+ *
+ * @returns Action creators for the widget state machine.
+ */
 declare const createActions: () => {
-    /** Manifest loading */
+    /** Sets the manifest in state (optionally merging with existing). */
     setManifest: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[manifest: WidgetManifest, update?: boolean | undefined], WidgetManifest, "set_manifest", never, {
         created: number;
         update: boolean | undefined;
     }>;
+    /** Async action triplet for fetching the widget manifest from the API. */
     fetchManifest: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[payload: {
         key: string;
         args?: GetWidgetParameters["args"];
@@ -18,8 +28,9 @@ declare const createActions: () => {
         success: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[manifest: WidgetManifest], WidgetManifest, "fetch_manifest::success", never, never>;
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "fetch_manifest::failure", never, never>;
     };
-    /** Config loading */
+    /** Sets the widget config in state. */
     setConfig: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[config: WidgetConfig], WidgetConfig, "set_config", never, never>;
+    /** Async action triplet for fetching the widget config from the API. */
     fetchConfig: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[payload: {
         key: string;
         args?: GetWidgetParameters["args"];
@@ -32,23 +43,29 @@ declare const createActions: () => {
         success: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[config: WidgetConfig], WidgetConfig, "fetch_config::success", never, never>;
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "fetch_config::failure", never, never>;
     };
+    /** Sets the dynamically imported widget script module in state. */
     setModule: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[module: any], any, "set_module", never, never>;
+    /** Async action triplet for dynamically importing the widget script. */
     importWidget: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[entrypoint: string], string, "import_widget::request", never, never> & {
         success: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[module: WidgetScriptModule], WidgetScriptModule, "import_widget::success", never, never>;
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "import_widget::failure", never, never>;
     };
+    /** Sets the resolved widget framework-module instances in state. */
     setInstance: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[instance: WidgetModulesInstance], WidgetModulesInstance, "set_instance", never, never>;
+    /** Async action triplet for the overall widget initialization lifecycle. */
     initialize: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[], null, "initialize_widget::request", never, never> & {
         success: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[], null, "initialize_widget::success", never, never>;
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "initialize_widget::failure", never, never>;
     };
 };
+/** Singleton action creators used by the widget state machine. */
 export declare const actions: {
-    /** Manifest loading */
+    /** Sets the manifest in state (optionally merging with existing). */
     setManifest: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[manifest: WidgetManifest, update?: boolean | undefined], WidgetManifest, "set_manifest", never, {
         created: number;
         update: boolean | undefined;
     }>;
+    /** Async action triplet for fetching the widget manifest from the API. */
     fetchManifest: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[payload: {
         key: string;
         args?: GetWidgetParameters["args"];
@@ -61,8 +78,9 @@ export declare const actions: {
         success: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[manifest: WidgetManifest], WidgetManifest, "fetch_manifest::success", never, never>;
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "fetch_manifest::failure", never, never>;
     };
-    /** Config loading */
+    /** Sets the widget config in state. */
     setConfig: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[config: WidgetConfig], WidgetConfig, "set_config", never, never>;
+    /** Async action triplet for fetching the widget config from the API. */
     fetchConfig: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[payload: {
         key: string;
         args?: GetWidgetParameters["args"];
@@ -75,18 +93,25 @@ export declare const actions: {
         success: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[config: WidgetConfig], WidgetConfig, "fetch_config::success", never, never>;
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "fetch_config::failure", never, never>;
     };
+    /** Sets the dynamically imported widget script module in state. */
     setModule: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[module: any], any, "set_module", never, never>;
+    /** Async action triplet for dynamically importing the widget script. */
     importWidget: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[entrypoint: string], string, "import_widget::request", never, never> & {
         success: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[module: WidgetScriptModule], WidgetScriptModule, "import_widget::success", never, never>;
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "import_widget::failure", never, never>;
     };
+    /** Sets the resolved widget framework-module instances in state. */
     setInstance: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[instance: WidgetModulesInstance], WidgetModulesInstance, "set_instance", never, never>;
+    /** Async action triplet for the overall widget initialization lifecycle. */
     initialize: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[], null, "initialize_widget::request", never, never> & {
         success: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[], null, "initialize_widget::success", never, never>;
         failure: import("@equinor/fusion-observable").ActionCreatorWithPreparedPayload<[error: unknown], unknown, "initialize_widget::failure", never, never>;
     };
 };
+/** Map of action-creator names to their instance types. */
 export type ActionBuilder = ReturnType<typeof createActions>;
+/** Map of action types produced by the action builders. */
 export type ActionMap = ActionInstanceMap<ActionBuilder>;
+/** Union of all action types dispatched in the widget state machine. */
 export type Actions = ActionTypes<typeof actions>;
 export {};

package/dist/types/state/create-reducer.d.ts

@@ -1,4 +1,14 @@
 import type { WidgetStateInitial, WidgetState } from '../types';
+/**
+ * Creates an Immer-powered reducer for the widget state machine.
+ *
+ * Handles direct state setters (`setManifest`, `setConfig`, `setModule`,
+ * `setInstance`) and tracks in-flight async operations via the `status` set.
+ *
+ * @param value - Initial widget state (without `status`, which is added
+ *   automatically as an empty `Set`).
+ * @returns A reducer function compatible with `FlowSubject`.
+ */
 export declare const createReducer: (value: WidgetStateInitial) => import("@equinor/fusion-observable").ReducerWithInitialState<WidgetState, import("@equinor/fusion-observable").PayloadAction<import("..").WidgetManifest, "set_manifest", {
     created: number;
     update: boolean | undefined;

package/dist/types/state/create-state.d.ts

@@ -2,4 +2,16 @@ import { FlowSubject } from '@equinor/fusion-observable';
 import type { Actions } from './actions';
 import type { WidgetState, WidgetStateInitial } from '../types';
 import type WidgetModuleProvider from '../WidgetModuleProvider';
+/**
+ * Creates and wires the RxJS-based `FlowSubject` state machine for a single
+ * widget.
+ *
+ * Attaches the manifest-fetch, script-import, and config-fetch flows to the
+ * subject so that dispatched actions trigger the corresponding side effects.
+ *
+ * @param value - Initial widget state (name and optional pre-loaded data).
+ * @param provider - The {@link WidgetModuleProvider} used by flows to query
+ *   the backend API.
+ * @returns A `FlowSubject` managing {@link WidgetState} via {@link Actions}.
+ */
 export declare const createState: (value: WidgetStateInitial, provider: WidgetModuleProvider) => FlowSubject<WidgetState, Actions>;

package/dist/types/state/flows.d.ts

@@ -2,6 +2,28 @@ import type { Flow } from '@equinor/fusion-observable';
 import type { Actions } from './actions';
 import type { WidgetState } from '../types';
 import type WidgetModuleProvider from '../WidgetModuleProvider';
+/**
+ * RxJS flow that reacts to `fetchManifest` actions by querying the
+ * {@link WidgetModuleProvider} for the manifest, emitting intermediate
+ * `setManifest` actions, and completing with a success or failure action.
+ *
+ * @param provider - The widget module provider used for API queries.
+ * @returns A `Flow` function for the widget state machine.
+ */
 export declare const handleFetchManifest: (provider: WidgetModuleProvider) => Flow<Actions, WidgetState>;
+/**
+ * RxJS flow that reacts to `fetchConfig` actions by querying the
+ * {@link WidgetModuleProvider} for the widget config, emitting intermediate
+ * `setConfig` actions, and completing with a success or failure action.
+ *
+ * @param provider - The widget module provider used for API queries.
+ * @returns A `Flow` function for the widget state machine.
+ */
 export declare const handleFetchConfig: (provider: WidgetModuleProvider) => Flow<Actions, WidgetState>;
+/**
+ * RxJS flow that reacts to `importWidget` actions by dynamically importing
+ * the widget’s JavaScript entry point URL and emitting success or failure.
+ *
+ * @returns A `Flow` function for the widget state machine.
+ */
 export declare const handleImportWidget: () => Flow<Actions, WidgetState>;

package/dist/types/types.d.ts

@@ -5,80 +5,121 @@ import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-se
 import type { QueryCtorOptions } from '@equinor/fusion-query';
 type Fusion = any;
 /**
- * WidgetEnv type represents the environment configuration for a widget.
+ * Environment descriptor passed to widget render functions.
+ *
+ * @template TProps - Custom props type forwarded to the widget.
  */
 export type WidgetEnv<TProps = unknown> = {
+    /** Base URL path the widget should use for routing (if applicable). */
     basename?: string;
+    /** The resolved widget manifest. */
     manifest?: WidgetManifest;
+    /** Arbitrary props forwarded from the host application. */
     props?: TProps;
 };
 /**
- * IClient interface represents a client with properties and methods for widget-related operations.
+ * HTTP client abstraction used by the widget module to fetch manifests
+ * and configurations from the backend API.
  */
 export type IClient = {
+    /** API version string appended as a query parameter to widget endpoints. */
     apiVersion: string;
+    /** Base URL used to construct full import URLs for widget scripts. */
     baseImportUrl: string;
+    /** Query constructor options for fetching a {@link WidgetManifest}. */
     getWidgetManifest: QueryCtorOptions<WidgetManifest, GetWidgetParameters>;
+    /** Query constructor options for fetching a {@link WidgetConfig}. */
     getWidgetConfig: QueryCtorOptions<WidgetConfig, GetWidgetParameters>;
 };
 /**
- * ModuleDeps type represents a tuple of dependencies required for a module.
+ * Peer-dependency module tuple required by the widget module.
+ *
+ * Includes {@link HttpModule}, {@link ServiceDiscoveryModule}, and
+ * {@link EventModule} (the latter two are optional at runtime).
  */
 export type ModuleDeps = [HttpModule, ServiceDiscoveryModule, EventModule];
 /**
- * GetWidgetParameters type represents parameters for retrieving widget information.
+ * Parameters for fetching a widget manifest or configuration.
  */
 export type GetWidgetParameters = {
+    /** Unique key (name) identifying the widget. */
     widgetKey: string;
+    /** Optional version or tag selector for the widget. */
     args?: {
         type: 'version' | 'tag';
         value: string;
     };
 };
 /**
- * WidgetEndpointBuilder type represents a function for building widget endpoints based on GetWidgetParameters.
+ * Function that builds a widget API endpoint URL from {@link GetWidgetParameters}.
  */
 export type WidgetEndpointBuilder = (args: GetWidgetParameters) => string;
 /**
- * WidgetManifest type represents the manifest information of a widget.
+ * Metadata manifest describing a widget’s identity, version, and entry point.
+ *
+ * Fetched from the backend API during widget initialization.
  */
 export type WidgetManifest = {
+    /** Unique backend identifier for the widget. */
     id: string;
+    /** Human-readable widget name (also used as lookup key). */
     name: string;
+    /** Semantic version of the widget. */
     version: string;
+    /** Brief description of the widget’s purpose. */
     description: string;
+    /** Optional list of maintainer identifiers. */
     maintainers?: string[];
+    /** Relative path to the JavaScript entry point (e.g., `index.js`). */
     entryPoint: string;
+    /** Base path for widget assets (combined with `entryPoint` to build the import URL). */
     assetPath: string;
 };
 /**
- * Endpoint type represents an endpoint with properties like name, uri, and optional scopes.
+ * Describes a named endpoint with a URI and optional OAuth scopes.
  */
 export type Endpoint = {
+    /** Endpoint name. */
     name: string;
+    /** Endpoint URI. */
     uri: string;
+    /** Optional OAuth scopes required for the endpoint. */
     scopes?: string[];
 };
 /**
- * WidgetConfig type represents the configuration for a widget, including environment and endpoints.
+ * Runtime configuration for a widget, including environment variables and
+ * backend endpoint mappings.
+ *
+ * @template TEnvironment - Custom environment shape.
  */
 export type WidgetConfig<TEnvironment = unknown> = {
+    /** Widget-specific environment variables. */
     environment: TEnvironment;
+    /** Map of endpoint names to URIs or structured {@link Endpoint} objects. */
     endpoints: Record<string, string | Endpoint>;
 };
 /**
- * WidgetModules type represents a combination of modules related to events and service discovery.
+ * Combined module set available inside a widget, merging custom modules with
+ * the standard {@link EventModule} and {@link ServiceDiscoveryModule}.
+ *
+ * @template TModules - Additional modules to combine.
  */
 export type WidgetModules<TModules extends Array<AnyModule> | unknown = unknown> = CombinedModules<TModules, [
     EventModule,
     ServiceDiscoveryModule
 ]>;
 /**
- * WidgetProps type represents widget properties as a record of PropertyKey to unknown.
+ * Generic property bag passed from the host application to a widget render
+ * function.
  */
 export type WidgetProps = Record<PropertyKey, unknown>;
 /**
- * WidgetRenderArgs type represents arguments for rendering a widget, including fusion, environment, and optional properties.
+ * Arguments passed to a widget’s render functions (`renderWidget`, `render`,
+ * `renderIcon`, and the default export).
+ *
+ * @template TFusion - Fusion instance type.
+ * @template TEnv - Environment descriptor type.
+ * @template TProps - Custom props type.
  */
 export type WidgetRenderArgs<TFusion extends Fusion = Fusion, TEnv = WidgetEnv, TProps extends WidgetProps = WidgetProps> = {
     fusion: TFusion;
@@ -86,31 +127,57 @@ export type WidgetRenderArgs<TFusion extends Fusion = Fusion, TEnv = WidgetEnv,
     props?: TProps;
 };
 /**
- * WidgetScriptModule type represents a script module for a widget with functions for rendering, rendering icons, etc.
+ * Describes the interface a widget script module must export.
+ *
+ * A dynamically imported widget entry point is expected to expose render
+ * functions that mount the widget into a given DOM element and return a
+ * cleanup function.
+ *
+ * @template TProps - Custom props type.
  */
 export type WidgetScriptModule<TProps extends WidgetProps = WidgetProps> = {
+    /** Default render function (fallback entry point). */
     default: (el: HTMLElement, args: WidgetRenderArgs, props?: TProps) => VoidFunction;
+    /** Primary render function for the widget body. */
     renderWidget: (el: HTMLElement, args: WidgetRenderArgs, props?: TProps) => VoidFunction;
+    /** Render function for the widget’s icon representation. */
     renderIcon: (el: HTMLElement, args: WidgetRenderArgs, props?: TProps) => VoidFunction;
+    /** Generic render function. */
     render: (el: HTMLElement, args: WidgetRenderArgs, props?: TProps) => VoidFunction;
 };
 /**
- * WidgetModulesInstance type represents an instance of widget modules.
+ * Resolved module instances available inside a running widget.
+ *
+ * @template TModules - Additional custom modules.
  */
 export type WidgetModulesInstance<TModules extends Array<AnyModule> | unknown = unknown> = ModulesInstance<WidgetModules<TModules>>;
 /**
- * WidgetState type represents the state of a widget, including properties like name, status, config, manifest, modules, and instance.
+ * Internal state managed by a {@link Widget}’s `FlowSubject` state machine.
+ *
+ * Tracks manifest, config, imported script, framework module instances, and
+ * a set of in-flight status markers.
+ *
+ * @template TModules - Custom module types.
  */
 export type WidgetState<TModules = any> = {
+    /** Widget name (lookup key). */
     name: string;
+    /** Set of in-flight action base types (e.g., `'fetch_manifest'`). */
     status: Set<string>;
+    /** Resolved widget configuration (when loaded). */
     config?: WidgetConfig;
+    /** Resolved widget manifest (when loaded). */
     manifest?: WidgetManifest;
+    /** Imported widget script module (when loaded). */
     modules?: WidgetScriptModule;
+    /** Framework module instances created for the widget. */
     instance?: WidgetModulesInstance<TModules>;
 };
 /**
- * WidgetStateInitial type represents an initial state of a widget, omitting the status property.
+ * Initial widget state shape passed to the `Widget` constructor.
+ *
+ * Same as {@link WidgetState} but without the `status` set, which is
+ * initialized internally by the reducer.
  */
 export type WidgetStateInitial = Omit<WidgetState, 'status'>;
 export {};

package/dist/types/utils.d.ts

@@ -1,5 +1,34 @@
 import type { IClient, WidgetEndpointBuilder } from './types';
 import type { IHttpClient } from '@equinor/fusion-framework-module-http';
+/**
+ * Creates a {@link WidgetEndpointBuilder} that produces manifest endpoint URLs.
+ *
+ * Routes versioned or tagged lookups to `/widgets/{key}/versions/{value}` and
+ * unversioned lookups to `/widgets/{key}`.
+ *
+ * @param apiVersion - API version string appended as a query parameter.
+ * @returns A function that maps {@link GetWidgetParameters} to a URL path.
+ */
 export declare const defaultManifestEndpointBuilder: (apiVersion: string) => WidgetEndpointBuilder;
+/**
+ * Creates a {@link WidgetEndpointBuilder} that produces config endpoint URLs.
+ *
+ * Routes versioned or tagged lookups to `/widgets/{key}/versions/{value}/config`
+ * and unversioned lookups to `/widgets/{key}/config`.
+ *
+ * @param apiVersion - API version string appended as a query parameter.
+ * @returns A function that maps {@link GetWidgetParameters} to a URL path.
+ */
 export declare const defaultConfigEndpointBuilder: (apiVersion: string) => WidgetEndpointBuilder;
+/**
+ * Creates the default {@link IClient} that uses the given HTTP client to
+ * fetch widget manifests and configurations.
+ *
+ * Uses `api-version=1.0-preview` and the default manifest/config endpoint
+ * builders.
+ *
+ * @param httpClient - An `IHttpClient` instance (typically resolved from the
+ *   `apps` service-discovery key).
+ * @returns A fully configured `IClient`.
+ */
 export declare const createDefaultClient: (httpClient: IHttpClient) => IClient;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "14.0.2-next.0";
+export declare const version = "15.0.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-widget",
-  "version": "14.0.2-next.0",
+  "version": "15.0.1",
   "description": "",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -38,22 +38,22 @@
   "dependencies": {
     "immer": "^11.0.0",
     "rxjs": "^7.8.1",
-    "@equinor/fusion-observable": "8.5.9-next.0",
-    "@equinor/fusion-query": "6.0.5-next.0"
+    "@equinor/fusion-observable": "9.0.1",
+    "@equinor/fusion-query": "7.0.1"
   },
   "devDependencies": {
-    "typescript": "^5.8.2",
-    "@equinor/fusion-framework-module-http": "^7.0.9-next.0",
-    "@equinor/fusion-framework-module": "^5.0.7-next.0",
-    "@equinor/fusion-framework-module-service-discovery": "^9.1.2-next.0",
-    "@equinor/fusion-query": "^6.0.5-next.0",
-    "@equinor/fusion-framework-module-event": "^5.0.2-next.0"
+    "typescript": "^5.9.3",
+    "@equinor/fusion-framework-module-event": "^6.0.0",
+    "@equinor/fusion-framework-module-http": "^8.0.0",
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-framework-module-service-discovery": "^10.0.0",
+    "@equinor/fusion-query": "^7.0.1"
   },
   "peerDependencies": {
-    "@equinor/fusion-framework-module": "5.0.7-next.0",
-    "@equinor/fusion-framework-module-http": "7.0.9-next.0",
-    "@equinor/fusion-framework-module-event": "5.0.2-next.0",
-    "@equinor/fusion-framework-module-service-discovery": "9.1.2-next.0"
+    "@equinor/fusion-framework-module": "6.0.0",
+    "@equinor/fusion-framework-module-event": "6.0.0",
+    "@equinor/fusion-framework-module-http": "8.0.0",
+    "@equinor/fusion-framework-module-service-discovery": "10.0.0"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-module-event": {

package/src/Widget.ts

@@ -18,24 +18,56 @@ import type { WidgetModuleConfig } from './WidgetModuleConfigurator';
 
 import './events';
 
-// Class representing a fusion widget
+/**
+ * Manages the full lifecycle of a single Fusion widget.
+ *
+ * A `Widget` encapsulates fetching its manifest, dynamically importing its
+ * script entry point, loading configuration, and emitting lifecycle events.
+ * Internally it uses an RxJS-based `FlowSubject` state machine driven by
+ * actions and flows defined in the `state/` directory.
+ *
+ * Create instances via {@link WidgetModuleProvider.getWidget} rather than
+ * constructing directly.
+ *
+ * @example
+ * ```typescript
+ * const widget = provider.getWidget('my-widget');
+ * widget.initialize().subscribe(({ manifest, script }) => {
+ *   script.renderWidget(el, { fusion, env: { manifest } });
+ * });
+ * ```
+ */
 export class Widget {
   #state: FlowSubject<WidgetState, Actions>;
+
+  /** Human-readable widget name used as the lookup key for manifest and config. */
   name: string;
+
+  /** Module-level HTTP client configuration used to resolve asset URLs. */
   config?: WidgetModuleConfig;
+
+  /** Optional version or tag parameters forwarded to manifest/config endpoints. */
   widgetPrams?: GetWidgetParameters['args'];
 
   #subscription = new Subscription();
 
-  // Getter for accessing the current state of the widget
+  /** Current snapshot of the widget's internal state (manifest, config, modules, status). */
   get state(): WidgetState {
     return this.#state.value;
   }
 
   /**
-   * Constructs a new Widget instance.
-   * @param value - Initial state of the widget.
-   * @param args - Configuration and event parameters for the widget.
+   * Constructs a new `Widget` instance.
+   *
+   * Prefer using {@link WidgetModuleProvider.getWidget} instead of calling
+   * this constructor directly.
+   *
+   * @param value - Initial widget state (at minimum, the widget `name`).
+   * @param args - Dependencies required by the widget.
+   * @param args.provider - The owning {@link WidgetModuleProvider}.
+   * @param args.config - Optional module-level HTTP client configuration.
+   * @param args.event - Optional event module for dispatching lifecycle events.
+   * @param args.widgetPrams - Optional version/tag selector for the widget.
    */
   constructor(
     value: WidgetStateInitial,
@@ -121,9 +153,15 @@ export class Widget {
   }
 
   /**
-   * Retrieves the manifest of the widget as an observable stream.
-   * @param force_refresh - Flag to force refresh the manifest.
-   * @returns An observable stream of the widget manifest.
+   * Retrieves the widget manifest as an observable stream.
+   *
+   * If the manifest is already cached in state it is emitted immediately.
+   * When `force_refresh` is `true`, a new fetch is dispatched regardless of
+   * cache status.
+   *
+   * @param force_refresh - When `true`, re-fetches the manifest even if cached.
+   * @returns Observable that emits the {@link WidgetManifest} and completes.
+   * @throws {Error} When the manifest fetch fails (wraps the underlying cause).
    */
   public getManifest(force_refresh = false): Observable<WidgetManifest> {
     return new Observable((subscriber) => {
@@ -159,9 +197,14 @@ export class Widget {
   }
 
   /**
-   * Retrieves the configuration of the widget as an observable stream.
-   * @param force_refresh - Flag to force refresh the configuration.
-   * @returns An observable stream of the widget configuration.
+   * Retrieves the widget configuration as an observable stream.
+   *
+   * Returns the cached config immediately when available. Set `force_refresh`
+   * to `true` to force a new fetch from the backend API.
+   *
+   * @param force_refresh - When `true`, re-fetches the config even if cached.
+   * @returns Observable that emits the {@link WidgetConfig} and completes.
+   * @throws {Error} When the config fetch fails (wraps the underlying cause).
    */
   public getConfig(force_refresh = false): Observable<WidgetConfig> {
     return new Observable((subscriber) => {
@@ -198,25 +241,35 @@ export class Widget {
   }
 
   /**
-   * Loads the configuration for the widget.
-   * @param update - Flag to force an update of the configuration.
+   * Dispatches a config fetch action into the state machine.
+   *
+   * @param update - When `true`, merges the fetched config with existing state
+   *   instead of replacing it.
    */
   public loadConfig(update?: boolean) {
     this.#state.next(actions.fetchConfig({ key: this.name, ...this.widgetPrams }, update));
   }
 
   /**
-   * Loads the manifest for the widget.
-   * @param update - Flag to force an update of the manifest.
+   * Dispatches a manifest fetch action into the state machine.
+   *
+   * @param update - When `true`, merges the fetched manifest with existing
+   *   state instead of replacing it.
    */
   public loadManifest(update?: boolean) {
     this.#state.next(actions.fetchManifest({ key: this.name, ...this.widgetPrams }, update));
   }
 
   /**
-   * Retrieves the widget module as an observable stream.
-   * @param force_refresh - Flag to force refresh the widget module.
-   * @returns An observable stream of the widget module.
+   * Retrieves the widget's script module as an observable stream.
+   *
+   * Resolves the manifest first, builds the full import URL from the asset
+   * path and entry point, then dynamically imports the script. The imported
+   * module is cached in state for subsequent calls.
+   *
+   * @param force_refresh - When `true`, re-imports the script even if cached.
+   * @returns Observable that emits the {@link WidgetScriptModule} and completes.
+   * @throws {Error} When the script import fails (wraps the underlying cause).
    */
   public getWidgetModule(force_refresh = false): Observable<WidgetScriptModule> {
     return new Observable((subscriber) => {
@@ -261,8 +314,12 @@ export class Widget {
     });
   }
   /**
-   * Initializes the widget and returns an observable stream with the combined results.
-   * @returns An observable stream with the manifest, script, and configuration.
+   * Initializes the widget by loading the manifest, importing the script, and
+   * preparing configuration. Emits a combined result when all resources are ready.
+   *
+   * @returns Observable that emits `{ manifest, script, config }` and completes
+   *   once all resources have been resolved.
+   * @throws {Error} When any initialization step fails.
    */
   public initialize(): Observable<{
     manifest: WidgetManifest;
@@ -299,25 +356,35 @@ export class Widget {
     });
   }
   /**
-   * Retrieves the widget module asynchronously as a Promise.
-   * @param allow_cache - Flag to allow caching of the widget module.
-   * @returns A Promise containing the widget module.
+   * Retrieves the widget script module as a `Promise`.
+   *
+   * When `allow_cache` is `true` (default), resolves with the first emitted
+   * value (which may be cached). When `false`, waits for the last emission
+   * after a forced refresh.
+   *
+   * @param allow_cache - When `true`, uses `firstValueFrom`; when `false`,
+   *   uses `lastValueFrom` after forcing a re-import.
+   * @returns Promise that resolves with the {@link WidgetScriptModule}.
    */
   public getWidgetModuleAsync(allow_cache = true): Promise<WidgetScriptModule> {
     const operator = allow_cache ? firstValueFrom : lastValueFrom;
     return operator(this.getWidgetModule(!allow_cache));
   }
   /**
-   * Updates the manifest of the widget.
-   * @param manifest - The new manifest for the widget.
-   * @param replace - Flag to replace the existing manifest.
+   * Replaces or merges the widget manifest in state.
+   *
+   * @param manifest - The new or partial manifest to set.
+   * @param replace - When `false` (default), the new manifest is merged with
+   *   the existing one. Pass explicit `false` to merge, or omit to merge.
    */
   public updateManifest(manifest: WidgetManifest, replace?: false) {
     this.#state.next(actions.setManifest(manifest, !replace));
   }
 
   /**
-   * Disposes of the widget by unsubscribing from any active subscriptions.
+   * Disposes of the widget by unsubscribing from all internal subscriptions.
+   *
+   * After disposal the widget instance should not be reused.
    */
   public dispose() {
     this.#subscription.unsubscribe();