@equinor/fusion-framework-module-context 8.0.3 → 9.0.0

package/src/mock/ContextMockConfigurator.ts

@@ -0,0 +1,244 @@
+import { EMPTY, from, lastValueFrom, of, throwError } from 'rxjs';
+
+import type { ModuleInitializerArgs } from '@equinor/fusion-framework-module';
+import type { NavigationModule } from '@equinor/fusion-framework-module-navigation';
+import type { ServicesModule } from '@equinor/fusion-framework-module-services';
+
+import { ContextModuleConfigurator } from '../ContextModuleConfigurator';
+import type { ContextModuleConfig } from '../ContextModuleConfig';
+import type { IContextModuleConfigurator } from '../ContextModuleConfigurator.interface';
+import type { ContextItem } from '../types';
+
+/**
+ * Resolves a context item by id, or `undefined` if none matches.
+ *
+ * @remarks
+ * The escape hatch for {@link ContextMockConfigurator.setResolver} — anything
+ * the friendly seeding methods did not anticipate can be expressed here instead.
+ */
+export type ContextResolverFn = (id: string) => ContextItem | undefined;
+
+/**
+ * A {@link ContextModuleConfigurator} backed by in-memory context items instead
+ * of a real context API, for seeding context in tests.
+ *
+ * @remarks
+ * Two layers cover different needs, both running through the real
+ * `ContextProvider` logic underneath — only the data source is substituted,
+ * never `validateContext`, `resolveContext`, or parent-context propagation:
+ *
+ * - **Friendly layer** — {@link setCurrentContext}, {@link setContexts},
+ *   {@link addContext}, {@link setRelatedContexts} — a small, context-domain
+ *   vocabulary for the common case: seed a known item, get it back.
+ * - **Escape hatch** — {@link setResolver} — a raw id-lookup function for a
+ *   custom id-based resolution strategy or a shape the friendly layer did not
+ *   cover. Only replaces id-based lookup (used by `setCurrentContextById` and
+ *   the initial context); it does not affect related-context resolution by
+ *   item, which always goes through {@link setRelatedContexts} instead.
+ *
+ * Seeding the initial context (via {@link setCurrentContext}) overrides
+ * `resolveInitialContext` directly with the seeded item, so a test never needs
+ * to construct a fake navigation module or parent framework instance to make an
+ * app start up with a known context selected. Resolving a context id from a URL
+ * path on startup is not covered — that needs a fake router, which is separate,
+ * not-yet-built work.
+ *
+ * Seeded ids are never generated for you — every item is looked up and
+ * returned exactly by the id it was seeded with, so a test never sees a
+ * different id than the one it wrote. Use `createContextItemFactory` or
+ * `createContextItems` for fixtures needing ids of their own, rather than a
+ * random generator that would change on every run.
+ *
+ * Related-context resolution defaults to the same seeded pool, filtered to
+ * whichever type(s) the query asked for — related context is the same
+ * context, just a different type, exactly as `ContextProvider.resolveContext`
+ * uses it to resolve an item of an unexpected type into one of the configured
+ * type. Seed items of both types and resolution works with no extra wiring;
+ * {@link setRelatedContexts} overrides that default for one specific item.
+ *
+ * @example Seed and select a known context item
+ * ```ts
+ * enableContextMock(configurator, (mock) => {
+ *   mock.setCurrentContext({ id: 'my-ctx', type: { id: 'ProjectMaster' }, value: {} });
+ * });
+ * ```
+ *
+ * @example Resolve a child-typed item into its parent type
+ * ```ts
+ * enableContextMock(configurator, (mock) => {
+ *   // no explicit wiring needed — relatedContexts filters this same pool by type
+ *   mock.setContexts([project, facility]);
+ * });
+ * ```
+ *
+ * @example Override related contexts for one specific item
+ * ```ts
+ * enableContextMock(configurator, (mock) => {
+ *   mock.addContext(project);
+ *   mock.setRelatedContexts(project.id, [facilityA, facilityB]);
+ * });
+ * ```
+ *
+ * @example Escape hatch for a custom resolution need
+ * ```ts
+ * enableContextMock(configurator, (mock) => {
+ *   mock.setResolver((id) => (id === 'special' ? specialContextItem : undefined));
+ * });
+ * ```
+ */
+export class ContextMockConfigurator extends ContextModuleConfigurator {
+  #contexts = new Map<string, ContextItem>();
+  #related = new Map<string, ContextItem[]>();
+  #resolver?: ContextResolverFn;
+  #pendingCurrentId?: string;
+
+  /**
+   * Registers the in-memory client up front, so `createConfig` never falls
+   * back to building one from a real `ServicesModule` — a mock needs neither
+   * an API provider nor a network to answer `get`/`query`/`related`.
+   */
+  constructor() {
+    super();
+    this.addConfigBuilder((builder) => {
+      builder.setContextClient({
+        get: (args) => {
+          const item = this.#resolve(args.id);
+          // a caller asking for an unseeded id gets a clear error, not a silent miss
+          return item
+            ? of(item)
+            : throwError(
+                () =>
+                  new Error(
+                    `ContextMockConfigurator: no context item resolves for id "${args.id}" — seed it with setCurrentContext/setContexts/addContext, or provide setResolver.`,
+                  ),
+              );
+        },
+        query: () => of([...this.#contexts.values()]),
+        related: (args) => {
+          const override = this.#related.get(args.item.id);
+          // an explicit override for this exact item always wins
+          if (override) return of(override);
+          const types = args.filter?.type;
+          // otherwise: related context is the same seeded pool, filtered to the requested type(s)
+          return of(
+            [...this.#contexts.values()].filter(
+              (item) => item.id !== args.item.id && (!types || types.includes(item.type.id)),
+            ),
+          );
+        },
+      });
+    });
+  }
+
+  /**
+   * Seeds a context item and selects it as the context the app resolves on startup.
+   *
+   * @param item - The context item to seed and select.
+   * @returns This configurator, for chaining.
+   */
+  public setCurrentContext(item: ContextItem): this {
+    this.#contexts.set(item.id, item);
+    this.#pendingCurrentId = item.id;
+    return this;
+  }
+
+  /**
+   * Seeds multiple context items, making each resolvable by id.
+   *
+   * @remarks
+   * Does not select any of them as current — pair with {@link setCurrentContext}
+   * for that.
+   *
+   * @param items - The context items to seed.
+   * @returns This configurator, for chaining.
+   */
+  public setContexts(items: ContextItem[]): this {
+    // seed every item so each is individually resolvable by id
+    for (const item of items) this.#contexts.set(item.id, item);
+    return this;
+  }
+
+  /**
+   * Seeds a single context item, making it resolvable by id.
+   *
+   * @param item - The context item to seed.
+   * @returns This configurator, for chaining.
+   */
+  public addContext(item: ContextItem): this {
+    this.#contexts.set(item.id, item);
+    return this;
+  }
+
+  /**
+   * Overrides related-context resolution for one specific source item.
+   *
+   * @remarks
+   * Without this, `relatedContexts` filters the seeded pool by the requested
+   * type(s) — this is only needed when a test wants a specific item to resolve
+   * something other than that default (e.g. no related items at all).
+   *
+   * @param itemId - The id of the item relations are being overridden for.
+   * @param items - The context items to return from `relatedContexts` for that item.
+   * @returns This configurator, for chaining.
+   */
+  public setRelatedContexts(itemId: string, items: ContextItem[]): this {
+    this.#related.set(itemId, items);
+    return this;
+  }
+
+  /**
+   * Escape hatch: overrides id-based context resolution directly.
+   *
+   * @remarks
+   * For a custom id-lookup strategy or a shape the friendly seeding methods
+   * above did not cover — reaching for this means they were already tried
+   * and did not fit. Only replaces lookup by id (used by
+   * `setCurrentContextById` and the seeded initial context) — related-context
+   * resolution by item always goes through {@link setRelatedContexts} instead,
+   * regardless of this setting.
+   *
+   * @param fn - Resolves a context item by id, or returns `undefined` if none matches.
+   * @returns This configurator, for chaining.
+   */
+  public setResolver(fn: ContextResolverFn): this {
+    this.#resolver = fn;
+    return this;
+  }
+
+  /**
+   * Resolves an id through the escape hatch if one is set, otherwise the seeded map.
+   *
+   * @param id - The context id to resolve.
+   * @returns The matching context item, or `undefined`.
+   */
+  #resolve(id: string): ContextItem | undefined {
+    // the escape hatch, when set, replaces the seeded map entirely
+    return this.#resolver ? this.#resolver(id) : this.#contexts.get(id);
+  }
+
+  /**
+   * Defaults `resolveInitialContext` from the seeded/resolved state, once the
+   * real config has been assembled.
+   *
+   * @param config - The context module config assembled by the base configurator.
+   * @param init - Module initializer arguments.
+   * @returns The context module configuration, backed by seeded/resolved data.
+   */
+  protected override async _processConfig(
+    config: Partial<ContextModuleConfig>,
+    init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule, NavigationModule]>,
+  ): Promise<ContextModuleConfig> {
+    // the base default is a plain Observable (`of(...)`), not a thenable — unwrap it explicitly
+    const resolved = await lastValueFrom(from(super._processConfig(config, init)));
+    const id = this.#pendingCurrentId;
+
+    // The base default resolves from the URL path or a parent framework, and
+    // throws when neither is present — the common case for an isolated mock.
+    // Resolve the seeded item when one was selected, otherwise resolve none.
+    resolved.resolveInitialContext = id ? () => of(this.#resolve(id)) : () => EMPTY;
+
+    return resolved;
+  }
+}
+
+export default ContextMockConfigurator;

package/src/mock/fixtures/create-context-item-factory.ts

@@ -0,0 +1,62 @@
+import { Faker, en } from '@faker-js/faker';
+
+import type { ContextItem } from '../../types';
+import { stringToSeed } from './string-to-seed';
+
+/**
+ * Creates one {@link ContextItem} fixture per call, for a single factory instance.
+ *
+ * @param overrides - Fields to override on the generated item. Supplying `id`
+ * skips the sequential generator for that one item.
+ * @returns A fully-formed {@link ContextItem}.
+ */
+export type MockContextItemFactory = (overrides?: Partial<ContextItem>) => ContextItem;
+
+/**
+ * Builds a {@link MockContextItemFactory} producing deterministic, sequential
+ * ids of the form `<prefix>-<n>`, with a realistic `title` filled in by
+ * {@link https://fakerjs.dev/ | faker} (`@faker-js/faker`, a peer dependency —
+ * only required if this factory is imported).
+ *
+ * @remarks
+ * Ids are scoped to the returned factory, not shared globally, so two tests
+ * creating their own factory each start counting from `1` — a random id (e.g.
+ * `crypto.randomUUID()`) would change on every run and break any assertion
+ * that seeds one item and expects to see that same id again. The faker seed
+ * is derived from that same id, so the generated `title` is just as
+ * deterministic. For fixtures spanning several context types (e.g. a
+ * parent/child type hierarchy), use `createContextItems` instead — it
+ * assigns ids per type and wires the type hierarchy for you.
+ *
+ * @param prefix - The id prefix. Defaults to `'ctx'`.
+ * @returns A function creating one {@link ContextItem} fixture per call.
+ *
+ * @example
+ * ```ts
+ * const createContextItem = createContextItemFactory();
+ *
+ * const project = createContextItem(); // id: 'ctx-1', title: a deterministic faker company name
+ * const facility = createContextItem({ title: 'Facility A' }); // id: 'ctx-2', title overridden
+ *
+ * mock.setContexts([project, facility]);
+ * ```
+ */
+export const createContextItemFactory = (prefix = 'ctx'): MockContextItemFactory => {
+  const created: ContextItem[] = [];
+  return (overrides: Partial<ContextItem> = {}): ContextItem => {
+    // overrides.id, when supplied, always wins over the sequential generator
+    const id = overrides.id ?? `${prefix}-${created.length + 1}`;
+    const faker = new Faker({ seed: stringToSeed(id), locale: en });
+    const item: ContextItem = {
+      type: { id: 'Mock' },
+      value: {},
+      title: faker.company.name(),
+      ...overrides,
+      id,
+    };
+    created.push(item);
+    return item;
+  };
+};
+
+export default createContextItemFactory;

package/src/mock/fixtures/create-context-items.ts

@@ -0,0 +1,80 @@
+import { Faker, en } from '@faker-js/faker';
+
+import type { ContextItem } from '../../types';
+import { stringToSeed } from './string-to-seed';
+
+/** Overridable {@link ContextItem} fields. `id` and `type` are always assigned by the type seed itself. */
+export type ContextItemOverrides = Partial<Omit<ContextItem, 'id' | 'type'>>;
+
+/**
+ * Describes one context type to generate fixtures for.
+ *
+ * @param type - The context type id (e.g. `'ProjectMaster'`, `'Contract'`).
+ * @param count - Number of items to generate for this type. Defaults to `1`.
+ * @param parentTypeIds - Parent type ids, when this type is a child in the
+ * type hierarchy — sets `type.isChildType`/`type.parentTypeIds` on every
+ * generated item of this type.
+ * @param item - Per-item overrides, called with the item's 1-based index
+ * within this type.
+ */
+export interface ContextTypeSeed {
+  type: string;
+  count?: number;
+  parentTypeIds?: string[];
+  item?: (index: number) => ContextItemOverrides;
+}
+
+/**
+ * Generates a batch of {@link ContextItem} fixtures across one or more
+ * context types, with deterministic ids, a realistic `title` from
+ * {@link https://fakerjs.dev/ | faker} (`@faker-js/faker`, a peer dependency —
+ * only required if this factory is imported), and a consistent type hierarchy.
+ *
+ * @remarks
+ * Ids are `<type>-<n>` (lowercased type, 1-based per type), so results are
+ * stable across runs and readable in test failures. `title` is filled in from
+ * a faker instance seeded by that same id, so it's just as deterministic.
+ * Feeding the result to `ContextMockConfigurator.setContexts` is enough to
+ * make related-context resolution work across types — the mock's
+ * `relatedContexts` filters this same seeded pool by type, so a child-typed
+ * item resolves into a parent of its `parentTypeIds` without any per-item
+ * wiring. That default is a simplification: the real context API resolves
+ * relations per specific instance (a `Contract` belongs to one particular
+ * `ProjectMaster`, not every `ProjectMaster` in the system) — seed only one
+ * instance per type when that distinction doesn't matter to the test, or use
+ * `ContextMockConfigurator.setRelatedContexts` to pin a specific item's
+ * relations when it does.
+ *
+ * @param types - The context types, and how many items to generate for each.
+ * @returns The generated context items, in the order the type seeds were given.
+ *
+ * @example Seed a project type and a child contract type
+ * ```ts
+ * const [project] = createContextItems([{ type: 'ProjectMaster' }]);
+ * const [contract] = createContextItems([
+ *   { type: 'Contract', parentTypeIds: ['ProjectMaster'] },
+ * ]);
+ *
+ * enableContextMock(configurator, (mock) => {
+ *   mock.setContexts([project, contract]);
+ *   // relatedContexts({ item: contract, filter: { type: ['ProjectMaster'] } }) now resolves `project`
+ * });
+ * ```
+ */
+export const createContextItems = (types: ContextTypeSeed[]): ContextItem[] =>
+  types.flatMap(({ type, count = 1, parentTypeIds, item }) =>
+    Array.from({ length: count }, (_, i): ContextItem => {
+      const index = i + 1;
+      const id = `${type.toLowerCase()}-${index}`;
+      const faker = new Faker({ seed: stringToSeed(id), locale: en });
+      return {
+        value: {},
+        title: faker.company.name(),
+        ...item?.(index),
+        id,
+        type: parentTypeIds ? { id: type, isChildType: true, parentTypeIds } : { id: type },
+      };
+    }),
+  );
+
+export default createContextItems;

package/src/mock/fixtures/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Fixture generators for {@link ContextMockConfigurator} test data.
+ *
+ * @remarks
+ * A separate entry point from `@equinor/fusion-framework-module-context/mock`
+ * because these factories use {@link https://fakerjs.dev/ | faker}
+ * (`@faker-js/faker`) for realistic values — an optional peer dependency, only
+ * required if this entry point is imported. `enableContextMock` and
+ * `ContextMockConfigurator` on the main `/mock` entry point never require it.
+ *
+ * @example
+ * ```typescript
+ * import { createContextItems } from '@equinor/fusion-framework-module-context/mock/fixtures';
+ *
+ * const [project] = createContextItems([{ type: 'ProjectMaster' }]);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export {
+  createContextItemFactory,
+  type MockContextItemFactory,
+} from './create-context-item-factory';
+export {
+  createContextItems,
+  type ContextTypeSeed,
+  type ContextItemOverrides,
+} from './create-context-items';

package/src/mock/fixtures/string-to-seed.ts

@@ -0,0 +1,18 @@
+/**
+ * Derives a numeric seed from a string, for a deterministic {@link https://fakerjs.dev/ | faker} instance.
+ *
+ * @remarks
+ * A pure-JS hash (no `node:crypto`) so fixtures stay usable in browser-like test
+ * environments, not just Node. Same id in, same seed out, every run.
+ *
+ * @param value - The string to derive a seed from (typically a generated item id).
+ * @returns A 32-bit unsigned integer seed.
+ */
+export const stringToSeed = (value: string): number =>
+  // FNV-1a-style hash: fold each char in, keep the running hash unsigned 32-bit
+  [...value].reduce(
+    (hash, char) => Math.imul(hash ^ char.charCodeAt(0), 16777619) >>> 0,
+    2166136261,
+  );
+
+export default stringToSeed;

package/src/mock/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Mock context module for tests: real provider, real configurator, in-memory data.
+ *
+ * @remarks
+ * Substituting the data source is the smallest change that removes the context
+ * API, HTTP mocking, and service-discovery mocking from a test. Everything
+ * above it — validation, resolution, parent-context propagation, initial-context
+ * selection — is the production code path.
+ *
+ * This is one of two ways to mock context data in tests: a small, static,
+ * in-memory pool (this module — no HTTP layer involved at all). The other is
+ * mocking the context API's HTTP responses directly (e.g. with MSW), which
+ * exercises the real `ContextModuleConfigurator`/services/HTTP pipeline —
+ * reach for that instead when the test needs to cover that pipeline itself.
+ * For fixture generators with realistic fake data, see
+ * `@equinor/fusion-framework-module-context/mock/fixtures`.
+ *
+ * @example
+ * ```typescript
+ * import { enableContextMock } from '@equinor/fusion-framework-module-context/mock';
+ *
+ * enableContextMock(configurator, (mock) => {
+ *   mock.setCurrentContext({ id: 'my-ctx', type: { id: 'ProjectMaster' }, value: {} });
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export {
+  ContextMockConfigurator,
+  type ContextResolverFn,
+} from './ContextMockConfigurator';
+export { enableContextMock, contextMockModule, type ContextMockConfigFn } from './module';

package/src/mock/module.ts

@@ -0,0 +1,54 @@
+import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
+
+import { module, type ContextModule } from '../module';
+
+import { ContextMockConfigurator } from './ContextMockConfigurator';
+
+/**
+ * The context module with an in-memory mock configurator instead of a real
+ * context API.
+ *
+ * @remarks
+ * Only `configure` differs from the real module. `initialize` is the production
+ * one, untouched, so a test exercises the real `ContextProvider` startup path,
+ * `validateContext`/`resolveContext`, and parent-context propagation — a
+ * rehearsal of the module, not a stand-in for it.
+ */
+export const contextMockModule: ContextModule = {
+  ...module,
+  configure: () => new ContextMockConfigurator(),
+};
+
+/**
+ * Configuration callback for {@link enableContextMock}.
+ */
+export type ContextMockConfigFn = (mock: ContextMockConfigurator) => void | Promise<void>;
+
+/**
+ * Enables the context module against in-memory seeded data, so a test needs no
+ * context API, no HTTP mock, and no service-discovery mock.
+ *
+ * @remarks
+ * Registered last, this replaces whichever context module the configurator
+ * already carries, so it works on a `FrameworkConfigurator` that pre-registers
+ * the real one.
+ *
+ * @param configurator - The modules configurator to register on.
+ * @param configure - Optional callback to seed context items or override resolution.
+ *
+ * @example
+ * ```ts
+ * enableContextMock(configurator, (mock) => {
+ *   mock.setCurrentContext({ id: 'my-ctx', type: { id: 'ProjectMaster' }, value: {} });
+ * });
+ * ```
+ */
+export const enableContextMock = (
+  // biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
+  configurator: IModulesConfigurator<any, any>,
+  configure?: ContextMockConfigFn,
+): void => {
+  configurator.addConfig({ module: contextMockModule, configure } as {
+    module: ContextModule;
+  });
+};

package/src/module.ts

@@ -5,8 +5,16 @@ import type { Module, ModulesInstance } from '@equinor/fusion-framework-module';
 import type { EventModule } from '@equinor/fusion-framework-module-event';
 import type { ServicesModule } from '@equinor/fusion-framework-module-services';
 import type { NavigationModule } from '@equinor/fusion-framework-module-navigation';
-
-import { type IContextModuleConfigurator, ContextModuleConfigurator } from './configurator';
+import {
+  TelemetryLevel,
+  TelemetryScope,
+  type TelemetryModule,
+} from '@equinor/fusion-framework-module-telemetry';
+
+import {
+  type IContextModuleConfigurator,
+  ContextModuleConfigurator,
+} from './ContextModuleConfigurator';
 import { type IContextProvider, ContextProvider } from './ContextProvider';
 import type { ContextItem } from './types';
 
@@ -31,7 +39,7 @@ export const moduleKey: ContextModuleKey = 'context';
  * @typeParam ContextModuleKey - The unique key identifying the context module.
  * @typeParam IContextProvider - The provider interface for context-related services.
  * @typeParam IContextModuleConfigurator - The configurator interface for customizing the context module.
- * @typeParam [ServicesModule, EventModule, NavigationModule] - The tuple of dependent modules required by the context module.
+ * @typeParam [ServicesModule, EventModule, NavigationModule, TelemetryModule] - The tuple of dependent modules required by the context module.
  *
  * @see Module
  */
@@ -39,7 +47,7 @@ export type ContextModule = Module<
   ContextModuleKey,
   IContextProvider,
   IContextModuleConfigurator,
-  [ServicesModule, EventModule, NavigationModule]
+  [ServicesModule, EventModule, NavigationModule, TelemetryModule]
 >;
 
 /**
@@ -68,16 +76,21 @@ export const module: ContextModule = {
   configure: () => new ContextModuleConfigurator(),
   initialize: async function (args) {
     // create config from configurator
-    const config = await (args.config as ContextModuleConfigurator).createConfig(args);
+    const config = await (args.config as ContextModuleConfigurator).createConfigAsync(args);
 
     // get event module if available
     const event = args.hasModule('event') ? await args.requireInstance('event') : undefined;
 
+    // get telemetry module if available, for tracking context resolution outcomes
+    const telemetry = args.hasModule('telemetry')
+      ? await args.requireInstance('telemetry')
+      : undefined;
+
     // get parent context provider if available
     const parentProvider = (args.ref as ModulesInstance<[ContextModule]>)?.context;
 
-    // create context provider
-    const provider = new ContextProvider({ config, event, parentContext: parentProvider });
+    // create context provider; parent context is wired up later via connectParentContext, not the deprecated ctor arg
+    const provider = new ContextProvider({ config, event });
 
     // create subscription for disposing the provider
     const subscription = new Subscription(() => provider.dispose());
@@ -106,27 +119,42 @@ export const module: ContextModule = {
           resolveInitialContext$
             .pipe(
               catchError((err) => {
-                console.warn(
-                  'ContextModule.postInitialize',
-                  'failed to resolve initial context',
-                  err,
-                );
+                const exception = err instanceof Error ? err : new Error(String(err));
+                // report through telemetry when available, otherwise fall back to console.warn below
+                if (telemetry) {
+                  telemetry.trackException({
+                    name: 'Context::postInitialize.resolveInitialContext',
+                    exception,
+                    level: TelemetryLevel.Warning,
+                    scope: ['context', TelemetryScope.Framework],
+                  });
+                } else {
+                  // no telemetry module registered - fall back to a visible warning so a
+                  // genuine resolution failure isn't silently swallowed
+                  console.warn('Context::postInitialize.resolveInitialContext', exception);
+                }
                 // failed to resolve initial context, complete immediately
                 return EMPTY;
               }),
             )
             .subscribe({
               next: (item) => {
-                console.debug(
-                  'ContextModule.postInitialize',
-                  `initial context was resolved to [${item ? item.id : 'none'}]`,
-                  item,
-                );
+                telemetry?.trackEvent({
+                  name: 'Context::postInitialize.initialContextResolved',
+                  level: TelemetryLevel.Debug,
+                  scope: ['context', TelemetryScope.Framework],
+                  properties: { contextId: item ? item.id : 'none' },
+                });
               },
               complete: () => {
                 // connect parent context if available when stream completes
                 if (config.connectParentContext !== false && parentProvider) {
                   provider.connectParentContext(parentProvider);
+                  telemetry?.trackEvent({
+                    name: 'Context::postInitialize.parentContextConnected',
+                    level: TelemetryLevel.Debug,
+                    scope: ['context', TelemetryScope.Framework],
+                  });
                 }
                 subscriber.complete();
               },

package/src/{get-context-selector.ts → selectors/get-context-selector.ts}

@@ -1,7 +1,7 @@
 import type { GetContextResponse } from '@equinor/fusion-framework-module-services/context/get';
 
-import { parseContextItem } from './parse-context-item';
-import type { ContextItem } from './types';
+import { parseContextItem } from '../utils/parse-context-item';
+import type { ContextItem } from '../types';
 
 /**
  * Parse the response from the GetContext API into a context item.
@@ -12,7 +12,3 @@ export const getContextSelector = async (response: Response): Promise<ContextIte
   const result = (await response.json()) as GetContextResponse<'v1'>;
   return parseContextItem(result);
 };
-
-// Deliberately re-exported from here to preserve the package's existing selectors entry point
-export { queryContextSelector } from './query-context-selector';
-export { relatedContextSelector } from './related-context-selector';

package/src/selectors/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Response selectors that parse raw context API responses into {@link ContextItem}s.
+ *
+ * - {@link getContextSelector} — parses a single-item GetContext response.
+ * - {@link queryContextSelector} — parses a multi-item QueryContext response.
+ * - {@link relatedContextSelector} — parses a multi-item RelatedContext response.
+ *
+ * @packageDocumentation
+ */
+export { getContextSelector } from './get-context-selector';
+export { queryContextSelector } from './query-context-selector';
+export { relatedContextSelector } from './related-context-selector';