@equinor/fusion-framework-module-app 7.4.2-next.0 → 8.0.0

package/dist/types/types.d.ts

@@ -5,9 +5,19 @@ import type { MsalModule } from '@equinor/fusion-framework-module-msal';
 import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
 import type { AppConfig } from './AppConfig';
 import type IApp from './app';
+/**
+ * Re-export of {@link ConfigEnvironment} from AppConfig.
+ */
 export type ConfigEnvironment = Record<string, unknown>;
 export type { AppConfig } from './AppConfig';
 type Fusion = any;
+/**
+ * Environment bindings passed to an application at render time,
+ * including its manifest, configuration, base path, and custom props.
+ *
+ * @template TEnv - Shape of the environment configuration record.
+ * @template TProps - Shape of custom properties passed to the app.
+ */
 export type AppEnv<TEnv extends ConfigEnvironment = ConfigEnvironment, TProps = unknown> = {
     basename?: string;
     manifest?: AppManifest;
@@ -15,19 +25,48 @@ export type AppEnv<TEnv extends ConfigEnvironment = ConfigEnvironment, TProps =
     props?: TProps;
 };
 /**
- * Reference to an app, used to fetch app manifest from app service
+ * Reference to an application, used to fetch the app manifest from the app service.
+ * The `tag` defaults to `'latest'` when omitted.
  */
 export type AppReference = {
     appKey: string;
     tag?: string;
 };
+/**
+ * Required module dependencies for the app module.
+ *
+ * The app module depends on HTTP (for API calls), service discovery
+ * (for resolving the apps service URL), and events (for lifecycle notifications).
+ */
 export type ModuleDeps = [HttpModule, ServiceDiscoveryModule, EventModule];
+/**
+ * Per-user application settings, stored as an arbitrary key-value record.
+ * Read via `getAppSettings` and written via `updateAppSettings` on the provider.
+ */
 export interface AppSettings {
     [key: string]: unknown;
 }
+/**
+ * Discriminant union of supported application types.
+ *
+ * - `'standalone'` – A full standalone application.
+ * - `'template'` / `'template-app'` – Template-based apps.
+ * - `'landing-page'` – Portal landing pages.
+ * - `'report'` / `'launcher'` – Legacy types (will be removed).
+ */
 export type AppType = 'standalone' | 'report' | 'launcher' | 'template' | 'template-app' | 'landing-page';
+/**
+ * The currently active application, or `null` when cleared, or `undefined`
+ * when no application has been set yet.
+ *
+ * @template TModules - Additional framework modules the app depends on.
+ * @template TEnv - Shape of the environment configuration record.
+ */
 export type CurrentApp<TModules extends Array<AnyModule> = [], TEnv extends ConfigEnvironment = ConfigEnvironment> = IApp<TEnv, TModules> | null | undefined;
 type Nullable<T> = T | null | undefined;
+/**
+ * Represents a person associated with an application (admin or owner).
+ */
 type AppPerson = {
     id: string;
     azureUniqueId: string;
@@ -38,7 +77,9 @@ type AppPerson = {
     accountClassification?: Nullable<string>;
     isExpired?: Nullable<boolean>;
 };
+/** An application administrator. */
 export type AppAdmin = AppPerson;
+/** An application owner. */
 export type AppOwner = AppPerson;
 /**
  * Schema entry format for route documentation in app manifests.
@@ -52,6 +93,10 @@ export type RouteSchemaEntry = [
         search?: Record<string, string>;
     }
 ];
+/**
+ * Build metadata returned by the app service for a specific application version.
+ * Contains the script entry point, asset path, tags, and optional CI metadata.
+ */
 export type AppBuildManifest = {
     version: string;
     entryPoint: string;
@@ -67,6 +112,10 @@ export type AppBuildManifest = {
     allowedExtensions?: Nullable<string[]>;
     uploadedBy?: Nullable<AppOwner>;
 };
+/**
+ * Full manifest describing a registered Fusion application, including
+ * display metadata, category, admins/owners, build info, and optional route schemas.
+ */
 export interface AppManifest {
     /** @deprecated will be removed, use appKey */
     key?: string;
@@ -99,25 +148,51 @@ export interface AppManifest {
     routes?: Nullable<RouteSchemaEntry[]>;
 }
 /**
- * @template TEnvironment - name of hosted environment
- * @template TModule - ES module type (import return type)
+ * A loaded application bundle containing its manifest, config, and imported script module.
+ *
+ * @template TEnvironment - Shape of the environment config record.
+ * @template TModule - Type of the dynamically imported ES module.
  */
 export type AppBundle<TEnvironment extends ConfigEnvironment = ConfigEnvironment, TModule = unknown> = {
     manifest: AppManifest;
     config: AppConfig<TEnvironment>;
     module: TModule;
 };
+/**
+ * Combined module type merging the app's own modules with base framework modules
+ * (Event, HTTP, MSAL).
+ *
+ * @template TModules - Additional modules contributed by the application.
+ */
 export type AppModules<TModules extends Array<AnyModule> | unknown = unknown> = CombinedModules<TModules, [
     EventModule,
     HttpModule,
     MsalModule
 ]>;
+/**
+ * Arguments passed to an application's `renderApp` or default export function
+ * when mounting the application into a DOM element.
+ *
+ * @template TFusion - Type of the Fusion framework instance.
+ * @template TEnv - Type of the environment bindings.
+ */
 export type ComponentRenderArgs<TFusion extends Fusion = Fusion, TEnv = AppEnv> = {
     fusion: TFusion;
     env: TEnv;
 };
+/**
+ * Shape of the ES module exported by an application's script bundle.
+ *
+ * Must expose either a `default` export or a `renderApp` function (or both)
+ * that mounts the application into a host DOM element.
+ */
 export type AppScriptModule = {
     default: (el: HTMLElement, args: ComponentRenderArgs) => VoidFunction;
     renderApp: (el: HTMLElement, args: ComponentRenderArgs) => VoidFunction;
 };
+/**
+ * Instantiated module collection for a running application.
+ *
+ * @template TModules - Additional modules contributed by the application.
+ */
 export type AppModulesInstance<TModules extends Array<AnyModule> | unknown = unknown> = ModulesInstance<AppModules<TModules>>;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.4.2-next.0";
+export declare const version = "8.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-app",
-  "version": "7.4.2-next.0",
+  "version": "8.0.0",
   "description": "",
   "main": "dist/esm/index.js",
   "exports": {
@@ -60,17 +60,17 @@
     "immer": "^11.0.0",
     "rxjs": "^7.8.1",
     "uuid": "^13.0.0",
-    "zod": "^4.1.8",
-    "@equinor/fusion-observable": "^8.5.9-next.0",
-    "@equinor/fusion-query": "^6.0.5-next.0"
+    "zod": "^4.3.6",
+    "@equinor/fusion-observable": "^9.0.0",
+    "@equinor/fusion-query": "^7.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.8.2",
-    "@equinor/fusion-framework-module": "^5.0.7-next.0",
-    "@equinor/fusion-framework-module-event": "^5.0.2-next.0",
-    "@equinor/fusion-framework-module-http": "^7.0.9-next.0",
-    "@equinor/fusion-framework-module-msal": "^7.3.2-next.0",
-    "@equinor/fusion-framework-module-service-discovery": "^9.1.2-next.0"
+    "typescript": "^5.9.3",
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-framework-module-http": "^8.0.0",
+    "@equinor/fusion-framework-module-event": "^6.0.0",
+    "@equinor/fusion-framework-module-service-discovery": "^10.0.0",
+    "@equinor/fusion-framework-module-msal": "^8.0.0"
   },
   "scripts": {
     "build": "tsc -b"

package/src/AppClient.ts

@@ -22,24 +22,48 @@ import type {
 import { AppBuildError, AppConfigError, AppManifestError, AppSettingsError } from './errors';
 import { AppConfigSelector } from './AppClient.Selectors';
 
+/**
+ * Contract for an app service client that fetches application manifests,
+ * build metadata, configurations, and per-user settings from the Fusion apps API.
+ *
+ * All methods return `ObservableInput` so consumers can use either `Observable`
+ * or `Promise`-based consumption patterns.
+ */
 export interface IAppClient extends Disposable {
   /**
-   * Fetch app manifest by appKey and tag
+   * Fetches the manifest for a single application.
+   *
+   * @param args - Object containing the `appKey` and an optional version `tag`.
+   * @returns An observable that emits the resolved {@link AppManifest}.
+   * @throws {AppManifestError} When the manifest cannot be loaded (404, 401, 410, or unknown).
    */
   getAppManifest: (args: { appKey: string; tag?: string }) => ObservableInput<AppManifest>;
 
   /**
-   * Fetch app build manifest by appKey and tag
+   * Fetches the build metadata (entry point, version, asset path) for an application.
+   *
+   * @param args - Object containing the `appKey` and an optional version `tag`.
+   * @returns An observable that emits the resolved {@link AppBuildManifest}.
+   * @throws {AppBuildError} When the build metadata cannot be loaded.
    */
   getAppBuild: (args: { appKey: string; tag?: string }) => ObservableInput<AppBuildManifest>;
 
   /**
-   * Fetch all app manifests
+   * Fetches manifests for all registered applications.
+   *
+   * @param args - Optional filter; set `filterByCurrentUser` to `true` to return
+   *   only apps the authenticated user has access to.
+   * @returns An observable that emits an array of {@link AppManifest} objects.
    */
   getAppManifests: (args?: { filterByCurrentUser?: boolean }) => ObservableInput<AppManifest[]>;
 
   /**
-   * Fetch app config by appKey and tag
+   * Fetches the runtime configuration (environment variables and endpoints) for an application.
+   *
+   * @template TType - Shape of the `environment` record in the returned config.
+   * @param args - Object containing the `appKey` and an optional version `tag`.
+   * @returns An observable that emits the resolved {@link AppConfig}.
+   * @throws {AppConfigError} When the configuration cannot be loaded.
    */
   getAppConfig: <TType extends ConfigEnvironment = ConfigEnvironment>(args: {
     appKey: string;
@@ -47,14 +71,20 @@ export interface IAppClient extends Disposable {
   }) => ObservableInput<AppConfig<TType>>;
 
   /**
-   * Fetch app settings by appKey
+   * Fetches per-user settings for an application.
+   *
+   * @param args - Object containing the `appKey`.
+   * @returns An observable that emits the {@link AppSettings} record.
+   * @throws {AppSettingsError} When settings cannot be loaded.
    */
   getAppSettings: (args: { appKey: string }) => ObservableInput<AppSettings>;
 
   /**
-   * Set app settings by appKey
-   * @param args - Object with appKey and settings
-   * @returns ObservableInput<AppSettings>
+   * Persists updated per-user settings for an application via PUT.
+   *
+   * @param args - Object containing the `appKey` and the `settings` payload to save.
+   * @returns An observable that emits the persisted {@link AppSettings}.
+   * @throws {AppSettingsError} When the update request fails.
    */
   updateAppSettings: (args: {
     appKey: string;
@@ -63,7 +93,8 @@ export interface IAppClient extends Disposable {
 }
 
 /**
- * Transforms an ApiApplicationSchema object into an AppManifest object.
+ * Transforms a raw API application response into an {@link AppManifest},
+ * adding backwards-compatible `key` and `name` getters.
  *
  * @returns An object conforming to the AppManifest interface.
  */
@@ -85,8 +116,20 @@ const ApplicationSchema = ApiApplicationSchema.transform((x): AppManifest => {
 });
 
 /**
- * The `AppClient` class implements the `IAppClient` interface and provides methods to query
- * application manifests and configurations from a backend service.
+ * Default implementation of {@link IAppClient} that communicates with the
+ * Fusion app service API over HTTP.
+ *
+ * Uses {@link Query} internally for request deduplication and caching
+ * (1-minute expiry by default). Responses are validated against Zod schemas
+ * ({@link ApiApplicationSchema}, {@link ApiApplicationBuildSchema}) and
+ * HTTP errors are mapped to typed error classes.
+ *
+ * @example
+ * ```ts
+ * const httpClient = await http.createClient('apps');
+ * const appClient = new AppClient(httpClient);
+ * appClient.getAppManifest({ appKey: 'my-app' }).subscribe(console.log);
+ * ```
  */
 export class AppClient implements IAppClient {
   #manifest: Query<AppManifest, { appKey: string }>;

package/src/AppConfig.ts

@@ -1,4 +1,10 @@
-// todo: move to utils
+/**
+ * Recursively freezes an object and all of its nested properties.
+ *
+ * @template T - Object type being frozen.
+ * @param obj - The object to deep-freeze.
+ * @returns The same object, deeply frozen.
+ */
 const deepFreeze = <T extends Record<string, unknown>>(obj: T): T => {
   for (const property of Object.keys(obj)) {
     if (
@@ -12,8 +18,16 @@ const deepFreeze = <T extends Record<string, unknown>>(obj: T): T => {
   return Object.freeze(obj);
 };
 
+/**
+ * Arbitrary key-value record representing environment-specific variables
+ * injected into an application's runtime configuration.
+ */
 export type ConfigEnvironment = Record<string, unknown>;
 
+/**
+ * A named endpoint from the application configuration, containing a URL
+ * and the OAuth scopes required to call it.
+ */
 export type ConfigEndPoint = {
   url: string;
   scopes: string[];

package/src/AppConfigurator.ts

@@ -10,21 +10,53 @@ import { moduleKey } from './module';
 
 import AppClient, { type IAppClient } from './AppClient';
 
+/**
+ * Resolved configuration for the app module.
+ *
+ * Produced by {@link AppConfigurator} during module initialization and consumed
+ * by {@link AppModuleProvider} at runtime.
+ */
 export interface AppModuleConfig {
+  /** HTTP client used to communicate with the Fusion app service API. */
   client: IAppClient;
-  // uri which to fetch the assets from aka the bundle of the application
+  /** Base URI for fetching application script bundles (e.g., `'/apps-proxy'`). */
   assetUri?: string;
 }
 
+/**
+ * Public interface for configuring the app module before initialization.
+ *
+ * Consumers use this interface (via the callback in {@link enableAppModule}) to
+ * override the default HTTP client or asset URI.
+ */
 export interface IAppConfigurator {
+  /**
+   * Sets the app service client used to fetch manifests, configs, and settings.
+   *
+   * @param client_or_cb - A promise resolving to an {@link IAppClient}, or a callback
+   *   that receives module initializer args and returns one.
+   */
   setClient: (
     client_or_cb:
       | Promise<AppModuleConfig['client']>
       | ConfigBuilderCallback<AppModuleConfig['client']>,
   ) => void;
+
+  /**
+   * Sets the base URI used to proxy-load application script bundles.
+   *
+   * @param base_or_cb - A static URI string or a callback returning one.
+   */
   setAssetUri: (base_or_cb: string | ConfigBuilderCallback<string>) => void;
 }
 
+/**
+ * Configuration builder for the app module.
+ *
+ * Extends {@link BaseConfigBuilder} to assemble an {@link AppModuleConfig} during
+ * framework initialization. If no explicit client is set, a default one is created
+ * via service discovery. The default `assetUri` is `'/apps-proxy'`.
+ */
 export class AppConfigurator
   extends BaseConfigBuilder<AppModuleConfig>
   implements IAppConfigurator

package/src/AppModuleProvider.ts

@@ -28,7 +28,27 @@ import type { IAppClient } from './AppClient';
 import { SemanticVersion } from '@equinor/fusion-framework-module';
 import { version } from './version';
 
+/**
+ * Runtime provider for the app module.
+ *
+ * Exposes methods for fetching application manifests, configurations, and user
+ * settings, and for setting or clearing the current active application. When an
+ * {@link EventModule} is available, lifecycle events are dispatched as the
+ * current app changes.
+ *
+ * @remarks
+ * Only one application can be active (`current`) at a time. Setting a new current
+ * app automatically disposes the previous one. Subscribe to {@link current$} for
+ * reactive updates.
+ */
 export class AppModuleProvider {
+  /**
+   * Shallow-compares two app manifests by JSON serialization.
+   *
+   * @param a - First manifest to compare.
+   * @param b - Second manifest to compare.
+   * @returns `true` if the serialized manifests are identical.
+   */
   static compareAppManifest<T extends AppManifest>(a?: T, b?: T): boolean {
     return JSON.stringify(a) === JSON.stringify(b);
   }
@@ -51,16 +71,22 @@ export class AppModuleProvider {
   }
 
   /**
-   * fetch an application by key
-   * @param appKey - application key
-   * @remarks
-   * - null when current app is cleared
-   * - undefined if application never set
+   * The current active application instance.
+   *
+   * - `undefined` – no application has been set yet.
+   * - `null` – the current application was explicitly cleared.
+   * - `App` – an active application instance.
    */
   get current(): CurrentApp | null | undefined {
     return this.#current$.value;
   }
 
+  /**
+   * Observable that emits when the current application changes.
+   *
+   * Emits are deduplicated by `appKey`; re-setting the same app does not trigger
+   * a new emission.
+   */
   get current$(): Observable<CurrentApp | null> {
     return this.#current$.pipe(
       distinctUntilChanged((prev, next) => {
@@ -72,6 +98,12 @@ export class AppModuleProvider {
     );
   }
 
+  /**
+   * Creates the app module provider.
+   *
+   * @param args - Object containing the resolved {@link AppModuleConfig} and an
+   *   optional {@link EventModule} instance for dispatching lifecycle events.
+   */
   constructor(args: { config: AppModuleConfig; event?: ModuleType<EventModule> }) {
     const { event, config } = args;
 
@@ -108,14 +140,23 @@ export class AppModuleProvider {
   }
 
   /**
-   * fetch an application by key
-   * @param appKey - application key
-   * @param tag - application tag (optional)
+   * Fetches the manifest for a single application by key.
+   *
+   * @param appKey - Unique application identifier.
+   * @param tag - Optional version tag (defaults to latest).
+   * @returns An observable that emits the resolved {@link AppManifest}.
    */
   public getAppManifest(appKey: string, tag?: string): Observable<AppManifest> {
     return from(this.#appClient.getAppManifest({ appKey, tag }));
   }
 
+  /**
+   * Fetches manifests for all registered applications.
+   *
+   * @param filter - Optional filter; set `filterByCurrentUser` to `true` to scope
+   *   results to apps accessible by the authenticated user.
+   * @returns An observable that emits an array of {@link AppManifest} objects.
+   */
   public getAppManifests(filter?: { filterByCurrentUser: boolean }): Observable<AppManifest[]> {
     return from(this.#appClient.getAppManifests(filter));
   }
@@ -129,8 +170,12 @@ export class AppModuleProvider {
   }
 
   /**
-   * fetch configuration for an application
-   * @param appKey - application key
+   * Fetches the runtime configuration for an application.
+   *
+   * @template TType - Shape of the `environment` record in the returned config.
+   * @param appKey - Unique application identifier.
+   * @param tag - Optional version tag.
+   * @returns An observable that emits the resolved {@link AppConfig}.
    */
   public getAppConfig<TType extends ConfigEnvironment = ConfigEnvironment>(
     appKey: string,
@@ -140,25 +185,33 @@ export class AppModuleProvider {
   }
 
   /**
-   * fetch user settings for an application
-   * @param appKey - application key
+   * Fetches per-user settings for an application.
+   *
+   * @param appKey - Unique application identifier.
+   * @returns An observable that emits the {@link AppSettings} record.
    */
   public getAppSettings(appKey: string): Observable<AppSettings> {
     return from(this.#appClient.getAppSettings({ appKey }));
   }
 
   /**
-   * Put user settings for an application
-   * @param appKey - application key
-   * @param settings - The settings to add save
+   * Persists updated per-user settings for an application.
+   *
+   * @param appKey - Unique application identifier.
+   * @param settings - The settings record to save.
+   * @returns An observable that emits the persisted {@link AppSettings}.
    */
   public updateAppSettings(appKey: string, settings: AppSettings): Observable<AppSettings> {
     return from(this.#appClient.updateAppSettings({ appKey, settings }));
   }
 
   /**
-   * set the current application, will internally resolve manifest
-   * @param appKey - application key
+   * Sets the current active application.
+   *
+   * Accepts an app key string, an {@link IApp} instance, or an {@link AppReference}
+   * with both `appKey` and `tag`. Setting a new app disposes the previous one.
+   *
+   * @param appKeyOrApp - Application key, app reference, or an existing `IApp` instance.
    */
   public setCurrentApp(appKeyOrApp: string | IApp | AppReference): void {
     if (typeof appKeyOrApp === 'string') {
@@ -179,10 +232,17 @@ export class AppModuleProvider {
     this.#current$.next(appKeyOrApp as CurrentApp);
   }
 
+  /**
+   * Clears the current application, disposing its resources and emitting `null`
+   * on {@link current$}.
+   */
   public clearCurrentApp(): void {
     this.#current$.next(null);
   }
 
+  /**
+   * Base URI used for proxying application script imports.
+   */
   public get assetUri(): string {
     return this.#appBaseUri;
   }
@@ -196,6 +256,9 @@ export class AppModuleProvider {
     return new App(value, { provider: this, event: this.#event });
   }
 
+  /**
+   * Tears down the provider, unsubscribing from all internal observables.
+   */
   public dispose() {
     this.#subscription.unsubscribe();
   }

package/src/app/App.ts

@@ -29,15 +29,25 @@ import isEqual from 'fast-deep-equal';
 
 import './events';
 
-// TODO - move globally
+/**
+ * RxJS operator that filters out `null` and `undefined` emissions.
+ *
+ * @template T - The non-nullable value type.
+ * @returns An operator that only passes through non-nullable values.
+ */
 export function filterEmpty<T>(): OperatorFunction<T | null | undefined, T> {
   return filter((value): value is T => value !== undefined && value !== null);
 }
 
 /**
- * Represents an application in the framework.
- * @template TEnv The type of the environment.
- * @template TModules The type of the app modules.
+ * Public interface for a single loaded Fusion application.
+ *
+ * Provides reactive observables and imperative methods for accessing the
+ * application's manifest, configuration, per-user settings, script module,
+ * and initialized module instance.
+ *
+ * @template TEnv - Shape of the environment configuration record.
+ * @template TModules - Additional framework modules the app depends on.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface IApp<
@@ -246,14 +256,29 @@ export interface IApp<
   getAppModuleAsync(allow_cache?: boolean): Promise<AppScriptModule>;
 }
 
+/** Default empty settings object used when no settings have been fetched. */
 const fallbackSettings: AppSettings = {};
 
+/**
+ * Result emitted by {@link IApp.initialize}, containing the resolved manifest,
+ * imported script module, and runtime configuration.
+ */
 export type AppInitializeResult = {
   manifest: AppManifest;
   script: AppScriptModule;
   config: AppConfig;
 };
 
+/**
+ * Concrete implementation of {@link IApp}.
+ *
+ * Manages an internal reactive state machine ({@link FlowSubject}) that orchestrates
+ * manifest fetching, config loading, settings management, and script import. Dispatches
+ * lifecycle events through the {@link EventModule} when available.
+ *
+ * @template TEnv - Shape of the environment configuration record.
+ * @template TModules - Additional framework modules the app depends on.
+ */
 // TODO make streams distinct until changed from state
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export class App<

package/src/app/actions.ts

@@ -12,6 +12,18 @@ import type {
   AppSettings,
 } from '../types';
 
+/**
+ * Factory function that creates all action creators used by the {@link App}
+ * state machine.
+ *
+ * Actions are grouped by domain:
+ * - **Manifest** – `setManifest`, `fetchManifest` (async)
+ * - **Config** – `setConfig`, `fetchConfig` (async)
+ * - **Settings** – `setSettings`, `fetchSettings` (async), `updateSettings` (async)
+ * - **Script module** – `setModule`, `importApp` (async)
+ * - **Instance** – `setInstance`
+ * - **Lifecycle** – `initialize` (async)
+ */
 const createActions = () => ({
   /** Manifest loading */
   setManifest: createAction('set_manifest', (manifest: AppManifest, update?: boolean) => ({
@@ -87,10 +99,14 @@ const createActions = () => ({
   ),
 });
 
+/** Singleton action creator map used by the app state machine. */
 export const actions = createActions();
 
+/** Record mapping action names to their creator functions. */
 export type ActionBuilder = ReturnType<typeof createActions>;
 
+/** Map of action names to their instantiated action shapes. */
 export type ActionMap = ActionInstanceMap<ActionBuilder>;
 
+/** Union of all action types dispatched by the app state machine. */
 export type Actions = ActionTypes<typeof actions>;

package/src/app/create-reducer.ts

@@ -13,6 +13,15 @@ import { type Actions, actions } from './actions';
 
 import type { AppBundleState, AppBundleStateInitial } from './types';
 
+/**
+ * Creates the Immer-powered reducer for the {@link App} state machine.
+ *
+ * Handles synchronous state updates (set manifest, config, settings, module, instance)
+ * and tracks in-progress async operations via a `status` set.
+ *
+ * @param value - Initial state values (appKey, tag, and any pre-loaded data).
+ * @returns A reducer function compatible with {@link FlowSubject}.
+ */
 export const createReducer = (value: AppBundleStateInitial) =>
   makeReducer<AppBundleState, Actions>(
     { ...value, status: new Set() } as AppBundleState,