@thinkwise/testwise 0.2.67 → 0.2.103

package/helpers/FlightTracker.ts

@@ -1,22 +1,54 @@
 import { EventEmitter } from 'node:events';
 import { testwiseConfig } from '../services/ConfigBuilder.js';
 
-const timeout = testwiseConfig().get<number>('featureSettings.InflightRequests.waitTimeout') ?? 5000;
+/**
+ * Tracks in-flight XHR requests made by the Thinkwise application and blocks
+ * test execution until the network has been idle for a short stability window.
+ *
+ * **Why this exists:** The Thinkwise Platform performs fire-and-forget XHR calls
+ * for things like navigation, saves, and data loads. Raw Playwright `waitFor*`
+ * helpers don't know about these — tests that proceed too early will act on
+ * stale data or a half-rendered screen. `FlightTracker` listens to every
+ * request/response cycle and exposes `waitToContinue()` which returns only
+ * once all tracked requests have finished AND the page has been quiet for at
+ * least `stabilityTime` milliseconds.
+ *
+ * **How to use it in tests:** You don't — it is wired up automatically inside
+ * `SubjectNavigator.navigateTo()`, `ClickOverride`, and `FillOverride`. You
+ * only need to know it exists if you are writing a new page-extension or
+ * override that performs navigation.
+ *
+ * @example
+ * // Inside a page-override or page-extension:
+ * const tracker = new FlightTracker();
+ * page.on('request',  req  => tracker.handleRequestStarted(req.url(), req.resourceType()));
+ * page.on('response', res  => tracker.handleRequestFinished(res.request().url()));
+ * await myAction();
+ * await tracker.waitToContinue();
+ */
+const minTimeout = 30000;
+const timeout = Math.max(testwiseConfig().get<number>('featureSettings.InflightRequests.waitTimeout') ?? 0, minTimeout);
+
 const stabilityTime = 150;
 
 export class FlightTracker {
   public requestsInFlight: number = 0;
-  private activeRequests = new Set<string>();
+  private activeRequests = new Map<string, number>();
   public eventEmitter: EventEmitter = new EventEmitter();
 
   /**
-   * Filters out non-functional "noise" requests that shouldn't block test execution.
+   * Returns true for XHR requests that should block test execution.
+   * Filters out non-XHR traffic and known noise endpoints.
    */
-  public isEssentialRequest(url: string): boolean {
+  public isEssentialRequest(url: string, resourceType: string): boolean {
+    if (resourceType !== 'xhr') return false;
+
     const noisePatterns = [
-      '.download_icon',
-      '.download_list_bar_grp_icon',
-      '.download_form_next_grp_icon',
+      '/detect_change(',
+      '/set_gui_start_use_log_session',
+      'download_icon',
+      'download_list_bar_grp_icon',
+      'download_form_next_grp_icon',
       '/badge()',
       'universal_background_picture',
       'i_ui_theme'
@@ -25,17 +57,44 @@ export class FlightTracker {
     return !noisePatterns.some((pattern) => url.includes(pattern));
   }
 
-  public handleRequestStarted = (url: string) => {
-    if (this.isEssentialRequest(url)) {
-      this.activeRequests.add(url);
-      this.requestsInFlight = this.activeRequests.size;
+  public handleRequestStarted = (url: string, resourceType: string) => {
+    if (this.isEssentialRequest(url, resourceType)) {
+      const wasIdle = this.activeRequests.size === 0;
+      this.activeRequests.set(url, (this.activeRequests.get(url) ?? 0) + 1);
+      this.requestsInFlight++;
+      if (wasIdle) this.eventEmitter.emit('active');
+    }
+  };
+
+  public reset = (): void => {
+    this.activeRequests.clear();
+    this.requestsInFlight = 0;
+  };
+
+  public handleRequestFailed = (url: string) => {
+    const count = this.activeRequests.get(url);
+    if (count !== undefined) {
+      if (count <= 1) {
+        this.activeRequests.delete(url);
+      } else {
+        this.activeRequests.set(url, count - 1);
+      }
+      this.requestsInFlight = Math.max(0, this.requestsInFlight - 1);
+      if (this.requestsInFlight === 0) {
+        this.eventEmitter.emit('idle');
+      }
     }
   };
 
   public handleRequestFinished = (url: string) => {
-    if (this.isEssentialRequest(url)) {
-      this.activeRequests.delete(url);
-      this.requestsInFlight = this.activeRequests.size;
+    const count = this.activeRequests.get(url);
+    if (count !== undefined) {
+      if (count <= 1) {
+        this.activeRequests.delete(url);
+      } else {
+        this.activeRequests.set(url, count - 1);
+      }
+      this.requestsInFlight = Math.max(0, this.requestsInFlight - 1);
       if (this.requestsInFlight === 0) {
         this.eventEmitter.emit('idle');
       }
@@ -64,14 +123,14 @@ export class FlightTracker {
       this.eventEmitter.on('idle', checkIdle);
     });
 
-    const timeoutPromise = new Promise<void>((_, reject) => {
+    const timeoutPromise = new Promise<void>((resolve) => {
       timeoutId = setTimeout(() => {
-        const pending = Array.from(this.activeRequests).join('\n -> ');
-        reject(
-          new Error(
-            `Timeout waiting for ${this.requestsInFlight} requests to complete (${timeout}ms).\nPending Essential Requests:\n -> ${pending}`
-          )
+        const pending = Array.from(this.activeRequests.keys()).join('\n -> ');
+        console.warn(
+          `FlightTracker: timed out after ${timeout}ms waiting for ${this.requestsInFlight} request(s) to complete.\nPending Essential Requests:\n -> ${pending}\nContinuing test execution.`
         );
+        this.reset();
+        resolve();
       }, timeout);
     });
 
@@ -83,4 +142,34 @@ export class FlightTracker {
       this.eventEmitter.removeAllListeners('idle');
     }
   };
+
+  /**
+   * For use after hash-based SPA navigation. Waits for the SPA to begin firing
+   * XHR requests (within `spaStartupTimeout`), then waits for all of them to
+   * settle. If no requests appear within the startup window the page is
+   * considered already loaded.
+   */
+  public waitForNavigationToSettle = async (spaStartupTimeout = 3000): Promise<void> => {
+    if (this.requestsInFlight > 0) {
+      return this.waitToContinue();
+    }
+
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        this.eventEmitter.off('active', onActive);
+        resolve();
+      }, spaStartupTimeout);
+
+      const onActive = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+
+      this.eventEmitter.once('active', onActive);
+    });
+
+    if (this.requestsInFlight > 0) {
+      await this.waitToContinue();
+    }
+  };
 }

package/helpers/GlobalWaitEventHandler.ts

@@ -2,6 +2,19 @@ import { EventEmitter } from 'node:events';
 import type { Page, Response } from '@playwright/test';
 import { testwiseConfig } from '../services/ConfigBuilder.js';
 
+/**
+ * Waits for a specific response URL pattern before allowing test execution
+ * to continue. Used when you need to block until a known async API response
+ * has arrived, as opposed to waiting for XHR idle (which `FlightTracker` does).
+ *
+ * Attached to the page as `page.waitEventHandler` by the `WaitEventHandler`
+ * page extension. Call `page.waitEventHandler.waitForUrl(pattern)` to block
+ * until a response matching that URL has been received.
+ *
+ * @example
+ * // Wait for a specific background endpoint before asserting:
+ * await page.waitEventHandler.waitForUrl('/api/employees/load');
+ */
 export class GlobalWaitEventHandler {
   private _canContinue: boolean = true;
   private _eventEmitter: EventEmitter = new EventEmitter();

package/helpers/LoginHelper.ts

@@ -9,10 +9,22 @@ import { pollUntil } from './Poll.js';
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 const configFixture = JSON.parse(fs.readFileSync(path.resolve(dirname, '../../config.json'), 'utf-8'));
 
+/**
+ * Handles authentication against the Thinkwise Indicium API and the
+ * web application login screen.
+ *
+ * Exposed on the page fixture via `LoginFeatures` as `page.logIn()`,
+ * `page.logInWithCredentials()`, `page.logInWithOptions()`, and `page.logOut()`.
+ * You do not instantiate `LoginHelper` directly in tests.
+ *
+ * Credentials are read from `Testwise.json` (`environmentSettings.username`
+ * and `environmentSettings.password`) by default, and can be overridden
+ * per-call via `logInWithCredentials()` or `logInWithOptions()`.
+ */
 export class LoginHelper {
   private _page: Page;
-  protected serviceUrl = String(testwiseConfig().get('environmentSettings.serviceUrl'));
-  protected metaEndpoint = String(testwiseConfig().get('environmentSettings.metaEndpoint'));
+  protected serviceUrl = String(testwiseConfig().get('environmentSettings.serviceUrl')).replace(/\/+$/, '');
+  protected metaEndpoint = String(testwiseConfig().get('environmentSettings.metaEndpoint')).replace(/\/+$/, '');
 
   constructor(page: Page) {
     if (!this.serviceUrl || this.serviceUrl === 'undefined') throw new Error('Service URL not found');
@@ -56,20 +68,23 @@ export class LoginHelper {
   }
 
   /**
-   * Navigate to the home page and wait for the menu to load
+   * Navigate to the home page and wait for the menu to load.
    */
   private async navigateHomeAndWaitForMenuToLoad() {
-    const baseUrl = testwiseConfig().get<string>('environmentSettings.baseUrl');
+    const baseUrl = testwiseConfig().get<string>('environmentSettings.baseUrl')?.replace(/\/+$/, '');
+    const minimumTimeout = 60000;
+
     if (!baseUrl) {
       throw new Error('Base URL is not defined in the configuration.');
     }
-    await this._page.goto(baseUrl);
 
-    await this._page.route('**/i_ui_menu?**', (route) => {
-      route.continue();
-    });
+    let timeout = Number(testwiseConfig().get<string | number>('featureSettings.other.loginTimeout') ?? minimumTimeout);
 
-    const timeout = Number(testwiseConfig().get<string | number>('featureSettings.other.loginTimeout') ?? 30_000);
+    if (Number.isNaN(timeout) || timeout < minimumTimeout) {
+      timeout = minimumTimeout;
+    }
+
+    await this._page.goto(baseUrl);
 
     await pollUntil(async () => this._page.url().includes('#application='), {
       timeout,
@@ -93,8 +108,8 @@ export class LoginHelper {
     }
 
     if (serviceUrl && metaEndpoint) {
-      this.serviceUrl = serviceUrl;
-      this.metaEndpoint = metaEndpoint;
+      this.serviceUrl = serviceUrl.replace(/\/+$/, '');
+      this.metaEndpoint = metaEndpoint.replace(/\/+$/, '');
     }
 
     const response = await this._page.request.post(`${this.serviceUrl}/account/api/login`, {
@@ -171,6 +186,10 @@ export class LoginHelper {
     });
   }
 
+  /**
+   * Logs out the current session by POSTing to the logout endpoint (accepts 204 or 401
+   * as valid responses), then clears all browser cookies.
+   */
   public async logOut() {
     const response = await this._page.request.post(`${this.serviceUrl}/account/api/logout`);
 
@@ -188,6 +207,14 @@ export class UserPreferences {
   public readonly guiApplAlias = String(testwiseConfig().get<string>('environmentSettings.guiApplAlias'));
   public readonly url: string;
 
+  /**
+   * Initialises the `UserPreferences` service, resolving the service URL, meta endpoint,
+   * and GUI application alias from config (overridable via optional parameters) and
+   * constructing the full Indicium endpoint URL.
+   * @param requestContext - The Playwright `Page` used to make API requests.
+   * @param serviceUrl - Optional override for the service URL from config.
+   * @param metaEndpoint - Optional override for the meta endpoint from config.
+   */
   constructor(requestContext: Page, serviceUrl?: string, metaEndpoint?: string) {
     this._page = requestContext;
 
@@ -198,9 +225,14 @@ export class UserPreferences {
     if (!metaEndpoint) throw new Error('Meta endpoint not found or is empty');
     if (!this.guiApplAlias) throw new Error('GUI application alias not found or is empty');
 
-    this.url = `${serviceUrl}/${metaEndpoint}/${this.guiApplAlias}`;
+    this.url = `${serviceUrl.replace(/\/+$/, '')}/${metaEndpoint.replace(/\/+$/, '')}/${this.guiApplAlias}`;
   }
 
+  /**
+   * Activates a specific user preference configuration for the current session by POSTing
+   * to the `set_up_configuration` endpoint with the given configuration ID.
+   * @param upConfigurationId - The ID of the user preference configuration to activate.
+   */
   public async run(upConfigurationId: number) {
     const fullUrl = `${this.url}/set_up_configuration`;
 
@@ -211,6 +243,11 @@ export class UserPreferences {
     await this._page.request.post(fullUrl, { headers: { 'Content-Type': 'application/json; charset=utf-8' }, data });
   }
 
+  /**
+   * Disables all active user preferences for the current session by POSTing to the
+   * `disable_up` endpoint.
+   * @returns The raw Playwright `APIResponse`.
+   */
   public async disable(): Promise<APIResponse> {
     const fullUrl = `${this.url}/disable_up`;
 

package/helpers/PathResolver.ts

@@ -1,7 +1,29 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+/**
+ * Locates the root directory of the **consumer project** (the project that has
+ * `@thinkwise/testwise` installed as a dependency) at runtime.
+ *
+ * **Why this exists:** Testwise runs from inside `node_modules` but needs to
+ * read and write files that belong to the consuming project (e.g.
+ * `registeredSubjects.json`, `Testwise.json`). Simply using `process.cwd()`
+ * is unreliable when scripts are invoked from sub-directories. This class
+ * walks up the directory tree looking for the first `package.json` whose
+ * `name` is NOT `@thinkwise/testwise`, which is guaranteed to be the consumer
+ * project root.
+ *
+ * **How to use it:** Inject it into any pipeline helper that needs to write
+ * to the consumer project. `PipelinePaths` already does this — you rarely
+ * need to instantiate `PathResolver` directly.
+ */
 export class PathResolver {
+  /**
+   * Walks up the directory tree from `process.cwd()` to find the nearest `package.json`
+   * whose `name` is not `@thinkwise/testwise`, returning that directory as the consumer
+   * project root. Falls back to `process.cwd()` if no such package is found.
+   * @returns Absolute path to the consumer project's root directory.
+   */
   public getConsumerRootDirectory(): string {
     let directory = process.cwd();
     let lastDir = '';

package/helpers/Poll.ts

@@ -1,5 +1,17 @@
-import type { PollOptions } from '../types/PollTypes.ts';
+import type { PollOptions } from '../types/PollTypes.js';
 
+/**
+ * Repeatedly calls `fn` at a configurable interval until the optional `predicate` returns
+ * truthy or the `timeout` is exceeded, at which point it throws.
+ * `onTick` is called with the last value and elapsed time after each failing attempt.
+ * @param fn - The async or sync function to poll.
+ * @param opts.timeout - Maximum wait time in milliseconds (default `10 000`).
+ * @param opts.interval - Polling interval in milliseconds (default `200`).
+ * @param opts.predicate - Returns `true` when the result is acceptable (default: truthy check).
+ * @param opts.onTick - Called after each failing attempt with the last value and elapsed ms.
+ * @returns The first value for which `predicate` returns `true`.
+ * @throws If `timeout` is exceeded before `predicate` returns `true`.
+ */
 export async function pollUntil<T>(fn: () => Promise<T> | T, opts: PollOptions<T> = {}): Promise<T> {
   const timeout = opts.timeout ?? 10_000;
   const interval = opts.interval ?? 200;

package/helpers/RegexHelper.ts

@@ -1,10 +1,22 @@
-// Escapes characters with special meaning in regexes.
+/**
+ * Escapes all characters with special meaning in regular expressions so that `input`
+ * can be safely embedded inside a `RegExp` constructor without unintended pattern matching.
+ * @param input - The raw string to escape.
+ * @returns The escaped string.
+ */
 export function escapeRegex(input: string): string {
   return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-// Exact match, case-insensitive, Unicode-safe.
-// By default trims the input; set trim=false for truly literal.
+/**
+ * Builds a case-insensitive, Unicode-safe `RegExp` that exactly matches `input`.
+ * Optionally trims leading/trailing whitespace and collapses internal whitespace runs
+ * to a single space to match typical UI text normalization.
+ * @param input - The text to match exactly.
+ * @param opts.trim - Trim leading/trailing whitespace before matching (default `true`).
+ * @param opts.collapseWhitespace - Collapse runs of whitespace to a single space (default `false`).
+ * @returns A case-insensitive `RegExp` anchored with `^` and `$`.
+ */
 export function exactTextRegex(input: string, opts?: { trim?: boolean; collapseWhitespace?: boolean }) {
   const { trim = true, collapseWhitespace = false } = opts ?? {};
   let s = trim ? input.trim() : input;

package/helpers/SubjectNavigator.ts

@@ -0,0 +1,57 @@
+import type { Page } from '@playwright/test';
+import { FlightTracker } from './FlightTracker.js';
+
+/**
+ * Navigates the browser to a Thinkwise subject deep-link URL and waits for
+ * the application to fully settle before returning control to the test.
+ *
+ * **Why this exists:** Calling `page.goto()` directly does not account for
+ * the asynchronous XHR requests that the Thinkwise app fires after a navigation
+ * event. Tests that act immediately after a bare `goto` frequently encounter
+ * loading spinners, empty grids, or incomplete form data. `SubjectNavigator`
+ * wraps navigation in a `FlightTracker` session so the test only continues
+ * once the network is truly idle.
+ *
+ * **How to use it:** You typically don't call this directly — it is used
+ * internally by the generated subject class `goTo()` methods. If you need
+ * to navigate imperatively in a test, prefer `page.subject.MySubjectClass.goTo()`.
+ *
+ * @example
+ * // Inside a generated subject class:
+ * const navigator = new SubjectNavigator(page);
+ * await navigator.navigateTo('subjects/Employee/Editable1/Main');
+ */
+export class SubjectNavigator {
+  private readonly _page: Page;
+
+  constructor(page: Page) {
+    this._page = page;
+  }
+
+  public async navigateTo(url: string): Promise<void> {
+    const flightTracker = new FlightTracker();
+
+    const onRequest = (request: import('@playwright/test').Request) => {
+      flightTracker.handleRequestStarted(request.url(), request.resourceType());
+    };
+    const onResponse = (response: import('@playwright/test').Response) => {
+      flightTracker.handleRequestFinished(response.request().url());
+    };
+    const onRequestFailed = (request: import('@playwright/test').Request) => {
+      flightTracker.handleRequestFailed(request.url());
+    };
+
+    this._page.on('request', onRequest);
+    this._page.on('response', onResponse);
+    this._page.on('requestfailed', onRequestFailed);
+
+    try {
+      await this._page.goToDeepLink(url);
+      await flightTracker.waitForNavigationToSettle();
+    } finally {
+      this._page.off('request', onRequest);
+      this._page.off('response', onResponse);
+      this._page.off('requestfailed', onRequestFailed);
+    }
+  }
+}

package/helpers/UserSimulationHelper.ts

@@ -2,6 +2,20 @@ import type { Page } from '@playwright/test';
 import { testwiseConfig } from '../services/ConfigBuilder.js';
 import { pollUntil } from './Poll.js';
 
+/**
+ * Simulates switching the active user identity in the Thinkwise application
+ * at runtime, without logging out and back in. Useful for testing
+ * role-based access control (RBAC) and user-specific workflows.
+ *
+ * Exposed on the page fixture via `UserSimulation` as `page.simulateUser()`,
+ * `page.getSimulatedUser()`, and `page.stopSimulation()`. You do not
+ * instantiate `UserSimulationHelper` directly in tests.
+ *
+ * @example
+ * await page.simulateUser('john.doe@example.com');
+ * // ... assert behaviour for this user ...
+ * await page.stopSimulation();
+ */
 export class UserSimulationHelper {
   private _page: Page;
   private _serviceUrl: string;

package/helpers/index.ts

@@ -1,3 +1,4 @@
 export * from './LoginHelper.js';
 export * from './PathResolver.js';
 export * from './RegexHelper.js';
+export * from './SubjectNavigator.js';

package/index.ts

@@ -17,6 +17,7 @@ export * from './components/index.js';
 export * from './controls/index.js';
 export * from './enums/index.js';
 export * from './helpers/index.js';
+export * from './mcp/index.js';
 export * from './page-extensions/index.js';
 export * from './page-overrides/index.js';
 export * from './services/index.js';

package/interfaces/IComponentObjects.ts

@@ -1,6 +1,18 @@
 import type { Locator } from '@playwright/test';
 
+/**
+ * Base contract that every `*Objects` class in `components/` and `controls/`
+ * must implement.
+ *
+ * **Why this exists:** Each component is split into two files — a `<Name>.ts`
+ * (public API with interaction methods) and a `<Name>Objects.ts` (raw locator
+ * accessors). `IComponentObjects` enforces that every `Objects` class exposes
+ * the two locators that all Thinkwise screens share: the scoped `context`
+ * locator and the page-level `mainHeader` locator used for presence checks.
+ */
 export interface IComponentObjects {
+  /** The scoped Playwright `Locator` that roots all locator lookups for this component instance. */
   context: Locator;
+  /** Locator for `main header` — used as a presence anchor to confirm the screen has rendered. */
   mainHeader: Locator;
 }

package/interfaces/IComponentSchemaMeta.ts

@@ -0,0 +1,17 @@
+import type { SubjectComponents } from '../types/Components.js';
+
+/** Metadata for a single property within a generated component schema. */
+export interface IComponentPropertyMeta {
+  colId: string;
+  elementType: string;
+}
+
+/**
+ * The full meta file that SchemaGenerator writes alongside each `.json`
+ * schema file, and that SubjectComponentGenerator reads back to drive code
+ * generation.
+ */
+export interface IComponentSchemaMeta {
+  componentType: SubjectComponents;
+  properties: Record<string, IComponentPropertyMeta>;
+}

package/interfaces/IProperty.ts

@@ -1,4 +1,17 @@
+/**
+ * Describes a single field or column on a Thinkwise screen, as returned by
+ * the Indicium API and stored in `seed-data/subjects.json`.
+ *
+ * The `control_type` drives which Testwise control helper gets generated for
+ * the property (e.g. `"field"` → `InputFieldControl`, `"lookup"` → `LookupDropdown`).
+ */
 export interface IProperty {
+  /** The field or column identifier as defined in the Thinkwise model (e.g. `"employee_id"`). */
   col: string;
+  /**
+   * The Thinkwise UI control type for this property.
+   * Drives the control class suffix appended in generated subject components.
+   * Common values: `"field"`, `"lookup"`, `"dropdown"`, `"checkbox"`, `"date_picker"`, `"combo_box"`.
+   */
   control_type: string;
 }

package/interfaces/IRegisteredSubjects.ts

@@ -1,5 +1,17 @@
+/**
+ * Describes a subject that has been registered in the consumer project's
+ * `registeredSubjects.json` file.
+ *
+ * The `SubjectRegistration` pipeline step reads generated subject classes and
+ * writes an entry here for each one. The `SubjectRegistry` page-extension
+ * reads this file at test startup to make all subjects available on
+ * `page.subject.<ClassName>`.
+ */
 export interface IRegisteredSubjects {
+  /** Thinkwise subject identifier (e.g. `"Employee"`). */
   subject: string;
+  /** Optional variant discriminator when the same subject has multiple variants (e.g. `"Editable1"`). */
   variant?: string;
+  /** Screen type context — `"Main"`, `"Popup"`, `"Zoom"`, or `"Detail"`. */
   screen_type: string;
 }

package/interfaces/ISeedSubjectDraft.ts

@@ -0,0 +1,17 @@
+import type { IProperty } from './IProperty.js';
+
+/**
+ * Represents a subject as it is built from the Indicium API before properties
+ * are fully populated. `properties` is optional here because it is assigned
+ * after the initial object is constructed during the build phase.
+ *
+ * Once written to `subjects.json` and read back via `DataRetriever`, the data
+ * is typed as the narrower `ISubject` (which requires `properties`).
+ */
+export interface ISeedSubjectDraft {
+  subject: string;
+  variant: string;
+  screentype_context: string;
+  screentype_id: string;
+  properties?: IProperty[];
+}

package/interfaces/ISubject.ts

@@ -1,9 +1,22 @@
 import type { IProperty } from './IProperty.js';
 
+/**
+ * Represents a single Thinkwise subject as stored in `seed-data/subjects.json`
+ * after the `ModelDataBuilder` pipeline step fetches it from the Indicium API.
+ *
+ * Each subject maps to one screen variant in the Thinkwise application. The
+ * `SubjectClassModelBuilder` reads these records and turns them into generated
+ * TypeScript subject classes under `test-artifacts/subjects/`.
+ */
 export interface ISubject {
+  /** Internal Thinkwise subject identifier (e.g. `"Employee"`). */
   subject: string;
+  /** Subject variant, used to distinguish multiple configurations of the same subject (e.g. `"Editable1"`). */
   variant: string;
+  /** Human-readable screen context: `"Main"`, `"Popup"`, `"Zoom"`, or `"Detail"`. */
   screentype_context: string;
+  /** Thinkwise screen type identifier used to look up the correct screen schema file. */
   screentype_id: string;
+  /** All field/column properties available on this screen. */
   properties: IProperty[];
 }

package/interfaces/ISubjectDetail.ts

@@ -0,0 +1,12 @@
+/** Screen context variants produced by the artifact-builder pipeline. */
+export type ScreenContext = 'Main' | 'Popup' | 'Zoom' | 'Detail';
+
+/**
+ * Describes a single generated subject class that the SubjectRegistration
+ * step registers in the SubjectRegistry.
+ */
+export interface ISubjectDetail {
+  subject: string;
+  variant?: string;
+  screen: ScreenContext;
+}