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

package/src/WidgetModuleConfigurator.ts

@@ -3,34 +3,62 @@ import type { ConfigBuilderCallbackArgs } from '@equinor/fusion-framework-module
 import { createDefaultClient } from './utils';
 import type { IClient } from './types';
 
-// Define the configuration type for the WidgetModule
+/**
+ * Resolved configuration produced by {@link WidgetModuleConfigurator}.
+ *
+ * Contains the {@link IClient} used to fetch widget manifests and configs
+ * from the backend API.
+ */
 export type WidgetModuleConfig = {
+  /** HTTP client abstraction for widget API calls. */
   client: IClient;
 };
 
-// Define a callback type for configuring the WidgetModule
+/**
+ * Callback signature accepted by {@link enableWidgetModule} for customizing
+ * the widget module configuration.
+ *
+ * @param builder - The {@link WidgetModuleConfigurator} instance to configure.
+ */
 export type WidgetModuleConfigBuilderCallback = (
   builder: WidgetModuleConfigurator,
 ) => void | Promise<void>;
 
-// Class responsible for configuring the WidgetModule
+/**
+ * Configuration builder for the widget module.
+ *
+ * Extends `BaseConfigBuilder` to produce a {@link WidgetModuleConfig}. If no
+ * custom client is provided via {@link setClient}, a default HTTP client is
+ * created from the `apps` service-discovery endpoint.
+ *
+ * @example
+ * ```typescript
+ * enableWidgetModule(configurator, (builder) => {
+ *   builder.setClient(async () => myCustomClient);
+ * });
+ * ```
+ */
 export class WidgetModuleConfigurator extends BaseConfigBuilder<WidgetModuleConfig> {
-  // Default expiration time for configurations (1 minute)
+  /** Default cache expiration time in milliseconds (1 minute). */
   defaultExpireTime = 1 * 60 * 1000;
 
   /**
-   * Set the client for the WidgetModule configuration.
-   * @param cb - Callback function to configure the client.
+   * Registers a custom {@link IClient} factory for the widget module.
+   *
+   * @param cb - Callback that receives config-builder args and returns an
+   *   `IClient` instance (or a `Promise` thereof).
    */
   public setClient(cb: ConfigBuilderCallback<IClient>) {
     this._set('client', cb);
   }
 
   /**
-   * Create an HTTP client based on the provided parameters.
-   * @param clientId - Identifier for the client.
-   * @param init - Configuration builder callback arguments.
-   * @returns An instance of the HTTP client.
+   * Creates an HTTP client by resolving the `apps` client from the HTTP module
+   * or falling back to service discovery.
+   *
+   * @param clientId - Registered HTTP client identifier (typically `'apps'`).
+   * @param init - Framework config-builder callback args providing module instances.
+   * @returns An `IHttpClient` instance for widget API calls.
    */
   private async _createHttpClient(clientId: string, init: ConfigBuilderCallbackArgs) {
     const http = await init.requireInstance('http');
@@ -45,23 +73,22 @@ export class WidgetModuleConfigurator extends BaseConfigBuilder<WidgetModuleConf
   }
 
   /**
-   * Process the WidgetModule configuration and create an HTTP client if needed.
-   * @param config - Partial configuration for the WidgetModule.
-   * @param _init - Configuration builder callback arguments.
-   * @returns The processed WidgetModule configuration.
+   * Finalizes the configuration by creating the default HTTP client when no
+   * custom client has been set.
+   *
+   * @param config - Partial configuration accumulated by builder callbacks.
+   * @param _init - Framework config-builder callback args.
+   * @returns The fully resolved {@link WidgetModuleConfig}.
    */
   protected async _processConfig(
     config: Partial<WidgetModuleConfig>,
     _init: ConfigBuilderCallbackArgs,
   ) {
-    // Create an HTTP client using the specified client ID and initialization parameters
     const httpClient = await this._createHttpClient('apps', _init);
 
-    // If the configuration does not have a client, use the default client
     if (!config.client) {
       config.client = createDefaultClient(httpClient);
     }
-    // Return the processed configuration as a WidgetModuleConfig object
     return config as WidgetModuleConfig;
   }
 }

package/src/WidgetModuleProvider.ts

@@ -12,15 +12,45 @@ import type { WidgetModuleConfig } from './WidgetModuleConfigurator';
 import { WidgetManifestLoadError, WidgetConfigLoadError } from './errors';
 import { Widget } from './Widget';
 
+/**
+ * Public interface for the widget module provider.
+ *
+ * Consumers depend on this interface rather than the concrete
+ * {@link WidgetModuleProvider} class, enabling testability and
+ * alternative implementations.
+ */
 export interface IWidgetModuleProvider {
+  /**
+   * Creates a {@link Widget} instance for the given widget key.
+   *
+   * @param widgetKey - Unique identifier (name) of the widget.
+   * @param args - Optional version or tag selector.
+   * @returns A new `Widget` ready for initialization.
+   */
   getWidget(
     widgetKey: GetWidgetParameters['widgetKey'],
     args?: GetWidgetParameters['args'],
   ): Widget;
+
+  /**
+   * Fetches the manifest for a widget as an observable stream.
+   *
+   * @param widgetKey - Unique identifier (name) of the widget.
+   * @param args - Optional version or tag selector.
+   * @returns Observable that emits the {@link WidgetManifest}.
+   */
   getWidgetManifest(
     widgetKey: GetWidgetParameters['widgetKey'],
     args?: GetWidgetParameters['args'],
   ): Observable<WidgetManifest>;
+
+  /**
+   * Fetches the configuration for a widget as an observable stream.
+   *
+   * @param widgetKey - Unique identifier (name) of the widget.
+   * @param args - Optional version or tag selector.
+   * @returns Observable that emits the {@link WidgetConfig}.
+   */
   getWidgetConfig(
     widgetKey: GetWidgetParameters['widgetKey'],
     args?: GetWidgetParameters['args'],
@@ -28,7 +58,17 @@ export interface IWidgetModuleProvider {
 }
 
 /**
- * The `WidgetModuleProvider` class implements the `IWidgetModuleProvider` interface and serves as a provider for managing widgets.
+ * Concrete provider that manages widget instances and performs API queries
+ * for widget manifests and configurations.
+ *
+ * Created automatically during module initialization; see {@link module} and
+ * {@link enableWidgetModule}.
+ *
+ * @example
+ * ```typescript
+ * const widget = provider.getWidget('my-widget');
+ * widget.initialize().subscribe(result => { ... });
+ * ```
  */
 export class WidgetModuleProvider implements IWidgetModuleProvider {
   // Private fields
@@ -37,8 +77,11 @@ export class WidgetModuleProvider implements IWidgetModuleProvider {
   #event?: ModuleType<EventModule>;
 
   /**
-   * Constructs a new `WidgetModuleProvider` instance.
-   * @param args - An object containing configuration and optional event module for the widget provider.
+   * Creates a new `WidgetModuleProvider`.
+   *
+   * @param args - Provider dependencies.
+   * @param args.config - Resolved {@link WidgetModuleConfig} with HTTP client.
+   * @param args.event - Optional event module for dispatching lifecycle events.
    */
   constructor(args: { config: WidgetModuleConfig; event?: ModuleType<EventModule> }) {
     const { config, event } = args;
@@ -47,9 +90,13 @@ export class WidgetModuleProvider implements IWidgetModuleProvider {
   }
 
   /**
-   * Retrieves a widget instance based on the provided name and optional parameters.
-   * @param name - The name of the widget.
-   * @param widgetParams - Optional parameters for the widget.
+   * Creates a new {@link Widget} instance for the given name.
+   *
+   * The returned widget has not been initialized yet — call
+   * {@link Widget.initialize} to start the lifecycle.
+   *
+   * @param name - Unique widget name (used as lookup key).
+   * @param widgetPrams - Optional version or tag selector.
    * @returns A new `Widget` instance.
    */
   public getWidget(name: string, widgetPrams?: GetWidgetParameters['args']): Widget {
@@ -60,10 +107,12 @@ export class WidgetModuleProvider implements IWidgetModuleProvider {
   }
 
   /**
-   * Retrieves the manifest of a widget as an observable stream.
-   * @param name - The name of the widget.
-   * @param widgetParams - Optional parameters for the widget.
-   * @returns An observable stream of the widget manifest.
+   * Fetches the manifest for a widget via the configured HTTP client.
+   *
+   * @param name - Unique widget name.
+   * @param widgetPrams - Optional version or tag selector.
+   * @returns Observable that emits the {@link WidgetManifest} and completes.
+   * @throws {WidgetManifestLoadError} When the manifest request fails.
    */
   public getWidgetManifest(
     name: string,
@@ -73,10 +122,12 @@ export class WidgetModuleProvider implements IWidgetModuleProvider {
   }
 
   /**
-   * Retrieves the config of a widget as an observable stream.
-   * @param name - The name of the widget.
-   * @param widgetParams - Optional parameters for the widget.
-   * @returns An observable stream of the widget config.
+   * Fetches the configuration for a widget via the configured HTTP client.
+   *
+   * @param name - Unique widget name.
+   * @param widgetPrams - Optional version or tag selector.
+   * @returns Observable that emits the {@link WidgetConfig} and completes.
+   * @throws {WidgetConfigLoadError} When the config request fails.
    */
   public getWidgetConfig(
     name: string,
@@ -85,6 +136,14 @@ export class WidgetModuleProvider implements IWidgetModuleProvider {
     return this._getWidgetConfig(name, widgetPrams);
   }
 
+  /**
+   * Internal: queries widget config from the API and maps HTTP errors to
+   * typed {@link WidgetConfigLoadError} instances.
+   *
+   * @param widgetKey - Widget identifier.
+   * @param args - Optional version or tag selector.
+   * @returns Observable emitting the {@link WidgetConfig}.
+   */
   protected _getWidgetConfig(
     widgetKey: GetWidgetParameters['widgetKey'],
     args?: GetWidgetParameters['args'],
@@ -116,11 +175,12 @@ export class WidgetModuleProvider implements IWidgetModuleProvider {
   }
 
   /**
-   * Fetches the configuration for a widget using a query.
-   * @param widgetKey - The key identifying the widget.
-   * @param args - Optional arguments for the widget.
-   * @returns An observable stream of the widget manifest.
-   * @protected
+   * Internal: queries widget manifest from the API and maps HTTP errors to
+   * typed {@link WidgetManifestLoadError} instances.
+   *
+   * @param widgetKey - Widget identifier.
+   * @param args - Optional version or tag selector.
+   * @returns Observable emitting the {@link WidgetManifest}.
    */
   protected _getWidget(
     widgetKey: GetWidgetParameters['widgetKey'],
@@ -154,7 +214,9 @@ export class WidgetModuleProvider implements IWidgetModuleProvider {
   }
 
   /**
-   * Disposes of the widget provider by unsubscribing from any active subscriptions.
+   * Disposes all internal query subscriptions.
+   *
+   * After disposal the provider should not be reused.
    */
   public dispose() {
     this.#subscription.unsubscribe();

package/src/enable-widget-module.ts

@@ -4,8 +4,22 @@ import { module } from './module';
 import type { WidgetModuleConfigBuilderCallback } from './WidgetModuleConfigurator';
 
 /**
- * Method for enabling the widget module
- * @param configurator - configuration object
+ * Registers the widget module on a Fusion Framework configurator.
+ *
+ * Call this during framework setup to enable widget loading, manifest
+ * resolution, and script import capabilities.
+ *
+ * @param configurator - The framework modules configurator to register the
+ *   widget module on.
+ * @param builder - Optional callback to customize the
+ *   {@link WidgetModuleConfigurator} (e.g., set a custom HTTP client).
+ *
+ * @example
+ * ```typescript
+ * import { enableWidgetModule } from '@equinor/fusion-framework-module-widget';
+ *
+ * enableWidgetModule(configurator);
+ * ```
  */
 export const enableWidgetModule = (
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/errors.ts

@@ -1,6 +1,29 @@
+/**
+ * Discriminator for categorizing widget HTTP errors.
+ *
+ * - `'not_found'` — HTTP 404
+ * - `'unauthorized'` — HTTP 401
+ * - `'unknown'` — any other error
+ */
 type WidgetErrorType = 'not_found' | 'unauthorized' | 'unknown';
 
+/**
+ * Error thrown when a widget manifest cannot be loaded from the backend API.
+ *
+ * Use the static {@link fromHttpResponse} factory to create instances from
+ * HTTP responses with appropriate type mapping.
+ */
 export class WidgetManifestLoadError extends Error {
+  /**
+   * Creates a `WidgetManifestLoadError` from an HTTP `Response`.
+   *
+   * Maps HTTP 401 to `'unauthorized'`, 404 to `'not_found'`, and all other
+   * status codes to `'unknown'`.
+   *
+   * @param response - The failing HTTP response.
+   * @param options - Standard `ErrorOptions` (e.g., `cause`).
+   * @returns A typed `WidgetManifestLoadError`.
+   */
   static fromHttpResponse(response: Response, options?: ErrorOptions) {
     switch (response.status) {
       case 401:
@@ -18,6 +41,11 @@ export class WidgetManifestLoadError extends Error {
       options,
     );
   }
+  /**
+   * @param type - Error category discriminator.
+   * @param message - Human-readable error description.
+   * @param options - Standard `ErrorOptions` (e.g., `cause`).
+   */
   constructor(
     public readonly type: WidgetErrorType,
     message?: string,
@@ -28,7 +56,23 @@ export class WidgetManifestLoadError extends Error {
   }
 }
 
+/**
+ * Error thrown when a widget configuration cannot be loaded from the backend API.
+ *
+ * Use the static {@link fromHttpResponse} factory to create instances from
+ * HTTP responses with appropriate type mapping.
+ */
 export class WidgetConfigLoadError extends Error {
+  /**
+   * Creates a `WidgetConfigLoadError` from an HTTP `Response`.
+   *
+   * Maps HTTP 401 to `'unauthorized'`, 404 to `'not_found'`, and all other
+   * status codes to `'unknown'`.
+   *
+   * @param response - The failing HTTP response.
+   * @param options - Standard `ErrorOptions` (e.g., `cause`).
+   * @returns A typed `WidgetConfigLoadError`.
+   */
   static fromHttpResponse(response: Response, options?: ErrorOptions) {
     switch (response.status) {
       case 401:
@@ -46,6 +90,11 @@ export class WidgetConfigLoadError extends Error {
       options,
     );
   }
+  /**
+   * @param type - Error category discriminator.
+   * @param message - Human-readable error description.
+   * @param options - Standard `ErrorOptions` (e.g., `cause`).
+   */
   constructor(
     public readonly type: WidgetErrorType,
     message?: string,
@@ -56,7 +105,15 @@ export class WidgetConfigLoadError extends Error {
   }
 }
 
+/**
+ * Error thrown when a widget script module cannot be dynamically imported.
+ */
 export class WidgetScriptModuleError extends Error {
+  /**
+   * @param type - Error category discriminator.
+   * @param message - Human-readable error description.
+   * @param options - Standard `ErrorOptions` (e.g., `cause`).
+   */
   constructor(
     public readonly type: WidgetErrorType,
     message?: string,

package/src/events.ts

@@ -9,18 +9,31 @@ import type {
   WidgetScriptModule,
 } from './types';
 
-/** base event type for applications */
+/**
+ * Base event-init shape for all widget lifecycle events.
+ *
+ * Extends `FrameworkEventInit` with a mandatory `name` field identifying
+ * the widget, and sets the event `source` to the originating {@link Widget}
+ * instance.
+ *
+ * @template TDetail - Additional detail properties merged with `{ name: string }`.
+ */
 export type WidgetEventInit<TDetail extends Record<string, unknown> | unknown = unknown> =
-  FrameworkEventInit<
-    /** additional event details and key of target event */
-    TDetail & { name: string },
-    /** source of the event */
-    Widget
-  >;
+  FrameworkEventInit<TDetail & { name: string }, Widget>;
 
+/**
+ * Concrete framework-event type for widget lifecycle events.
+ *
+ * @template TDetail - Additional detail properties.
+ */
 export type WidgetEvent<TDetail extends Record<string, unknown> | unknown = unknown> =
   FrameworkEvent<WidgetEventInit<TDetail>>;
 
+/**
+ * Framework-event type for widget lifecycle failure events.
+ *
+ * Carries an `error` property in the event detail for error inspection.
+ */
 export type WidgetEventFailure = FrameworkEvent<
   WidgetEventInit<{
     error: WidgetConfig;
@@ -29,47 +42,53 @@ export type WidgetEventFailure = FrameworkEvent<
 
 declare module '@equinor/fusion-framework-module-event' {
   interface FrameworkEventMap {
-    /** fired when the application has initiated its modules */
+    /** Fired when a widget has finished initializing its framework modules. */
     onWidgetModulesLoaded: WidgetEvent<{
-      /** initiated modules for application */
+      /** The initialized module instances. */
       modules: WidgetModulesInstance;
     }>;
 
+    /** Fired when a widget manifest fetch starts. */
     onWidgetManifestLoad: WidgetEvent;
-    /** fired when the application has loaded corresponding manifest */
+    /** Fired when a widget manifest has been successfully loaded. */
     onWidgetManifestLoaded: WidgetEvent<{
       manifest: WidgetManifest;
     }>;
+    /** Fired when a widget manifest fetch fails. */
     onWidgetManifestFailure: WidgetEventFailure;
 
+    /** Fired when a widget config fetch starts. */
     onWidgetConfigLoad: WidgetEvent;
-    /** fired when the application has loaded corresponding config */
+    /** Fired when a widget config has been successfully loaded. */
     onWidgetConfigLoaded: WidgetEvent<{
       config: WidgetConfig;
     }>;
+    /** Fired when a widget config fetch fails. */
     onWidgetConfigFailure: WidgetEventFailure;
 
-    /** fired when the application has loaded corresponding javascript module */
+    /** Fired when a widget script import starts. */
     onAWidgetScriptLoad: WidgetEvent;
+    /** Fired when a widget script has been successfully imported. */
     onWidgetScriptLoaded: WidgetEvent<{
       script: WidgetScriptModule;
     }>;
+    /** Fired when a widget script import fails. */
     onWidgetScriptFailure: WidgetEventFailure;
 
-    /** fired before application loads manifest, config and script */
+    /** Fired before the widget begins loading manifest, config, and script. */
     onWidgetInitialize: WidgetEvent;
 
     /**
-     * fired after application has loaded manifest, config and script
+     * Fired after the widget has loaded manifest, config, and script.
      *
-     * __note:__ not fired until all loaders has settled (last emit)
+     * Not emitted until all loaders have settled (last emission).
      */
     onWidgetInitialized: WidgetEvent;
 
-    /** fired when application fails to load either manifest, config and script */
+    /** Fired when the widget fails to load manifest, config, or script. */
     onWidgetInitializeFailure: WidgetEventFailure;
 
-    /** fired when the application is disposed (unmounts) */
+    /** Fired when the widget is disposed (unmounted from the DOM). */
     onWidgetDispose: FrameworkEvent<WidgetEventInit>;
   }
 }

package/src/index.ts

@@ -1,4 +1,14 @@
-export { WidgetModuleConfigurator, WidgetModuleConfig } from './WidgetModuleConfigurator';
+/**
+ * Fusion Framework Widget Module
+ *
+ * Provides runtime loading, configuration, and lifecycle management for
+ * remote widget micro-frontends. Widgets are dynamically fetched, imported,
+ * and mounted into a host application.
+ *
+ * @packageDocumentation
+ */
+
+export { WidgetModuleConfigurator, type WidgetModuleConfig } from './WidgetModuleConfigurator';
 
 export { WidgetModuleProvider } from './WidgetModuleProvider';
 
@@ -8,4 +18,4 @@ export * from './types';
 
 export { enableWidgetModule } from './enable-widget-module';
 
-export { default, WidgetModule, module, moduleKey } from './module';
+export { default, type WidgetModule, module, moduleKey } from './module';

package/src/module.ts

@@ -4,8 +4,14 @@ import type { ModuleDeps } from './types';
 import { WidgetModuleConfigurator } from './WidgetModuleConfigurator';
 import { type IWidgetModuleProvider, WidgetModuleProvider } from './WidgetModuleProvider';
 
+/** Module registration key used in the Fusion Framework module map. */
 export const moduleKey = 'widget';
 
+/**
+ * Module type definition binding the `'widget'` key to the
+ * {@link IWidgetModuleProvider} instance, {@link WidgetModuleConfigurator}
+ * configuration builder, and required {@link ModuleDeps}.
+ */
 export type WidgetModule = Module<
   typeof moduleKey,
   IWidgetModuleProvider,
@@ -13,6 +19,17 @@ export type WidgetModule = Module<
   ModuleDeps
 >;
 
+/**
+ * Widget module descriptor.
+ *
+ * Defines how the widget module is configured, initialized, and disposed
+ * within the Fusion Framework module system.
+ *
+ * - `configure` — creates a fresh {@link WidgetModuleConfigurator}
+ * - `initialize` — resolves the config, optionally acquires the event module,
+ *   and returns a {@link WidgetModuleProvider}
+ * - `dispose` — cleans up provider subscriptions
+ */
 export const module: WidgetModule = {
   name: moduleKey,
   configure() {
@@ -31,6 +48,10 @@ export const module: WidgetModule = {
 
 export default module;
 
+/**
+ * Augments the global Fusion Framework `Modules` interface so that
+ * `modules.widget` is typed as {@link WidgetModule}.
+ */
 declare module '@equinor/fusion-framework-module' {
   interface Modules {
     [moduleKey]: WidgetModule;

package/src/state/actions.ts

@@ -12,8 +12,17 @@ import type {
   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.
+ */
 const createActions = () => ({
-  /** Manifest loading */
+  /** Sets the manifest in state (optionally merging with existing). */
   setManifest: createAction('set_manifest', (manifest: WidgetManifest, update?: boolean) => ({
     payload: manifest,
     meta: {
@@ -21,6 +30,7 @@ const createActions = () => ({
       update,
     },
   })),
+  /** Async action triplet for fetching the widget manifest from the API. */
   fetchManifest: createAsyncAction(
     'fetch_manifest',
     (payload: { key: string; args?: GetWidgetParameters['args'] }, update?: boolean) => ({
@@ -30,8 +40,9 @@ const createActions = () => ({
     (manifest: WidgetManifest) => ({ payload: manifest }),
     (error: unknown) => ({ payload: error }),
   ),
-  /** Config loading */
+  /** Sets the widget config in state. */
   setConfig: createAction('set_config', (config: WidgetConfig) => ({ payload: config })),
+  /** Async action triplet for fetching the widget config from the API. */
   fetchConfig: createAsyncAction(
     'fetch_config',
     (payload: { key: string; args?: GetWidgetParameters['args'] }, update?: boolean) => ({
@@ -41,18 +52,21 @@ const createActions = () => ({
     (config: WidgetConfig) => ({ payload: config }),
     (error: unknown) => ({ payload: error }),
   ),
+  /** Sets the dynamically imported widget script module in state. */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   setModule: createAction('set_module', (module: any) => ({ payload: module })),
+  /** Async action triplet for dynamically importing the widget script. */
   importWidget: createAsyncAction(
     'import_widget',
     (entrypoint: string) => ({ payload: entrypoint }),
     (module: WidgetScriptModule) => ({ payload: module }),
     (error: unknown) => ({ payload: error }),
   ),
-  // widget Instance
+  /** Sets the resolved widget framework-module instances in state. */
   setInstance: createAction('set_instance', (instance: WidgetModulesInstance) => ({
     payload: instance,
   })),
+  /** Async action triplet for the overall widget initialization lifecycle. */
   initialize: createAsyncAction(
     'initialize_widget',
     () => ({ payload: null }),
@@ -61,10 +75,14 @@ const createActions = () => ({
   ),
 });
 
+/** Singleton action creators used by the widget state machine. */
 export const actions = createActions();
 
+/** 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>;

package/src/state/create-reducer.ts

@@ -12,6 +12,16 @@ enableMapSet();
 import { type Actions, actions } from './actions';
 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 const createReducer = (value: WidgetStateInitial) =>
   makeReducer<WidgetState, Actions>({ ...value, status: new Set() } as WidgetState, (builder) =>
     builder

package/src/state/create-state.ts

@@ -8,6 +8,18 @@ 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 const createState = (
   value: WidgetStateInitial,
   provider: WidgetModuleProvider,