refactor(bdd): consolidate uiAgent slot machinery per simplify review

One UiAgentSlot class now serves both the worker-scoped and per-World
agent lifetimes (shared in-flight promise, retry after failure with a
compare-before-clear guard, teardown that awaits in-flight creation), so
the two paths cannot drift. importPlatformPackage only translates
genuine resolution failures of the platform package itself into the
install hint — an installed-but-broken package rethrows untouched.
Single unknown-type guard in config validation, exhaustiveness tripwire
on UI_TARGET_TYPES, deprecated no-op fields (screenshotResizeScale,
testId) dropped from the new public types, harmony gains the yaml env's
appNameMapping, and the README scopes its yaml-parity claim honestly
and documents worker-scope retry and cache-id semantics.

Author: ScriptedAlchemy

packages/bdd/README.md

@@ -212,7 +212,7 @@ interface BddConfig {
 }
 ```
 
-`uiAgent` is a flat union discriminated on `type` — field names match the corresponding [yaml automation](https://midscenejs.com/automate-with-scripts-in-yaml) env blocks, so configs translate 1:1:
+`uiAgent` is a flat union discriminated on `type` — field names match the corresponding [yaml automation](https://midscenejs.com/automate-with-scripts-in-yaml) env vocabulary (each row below lists exactly what its target supports; the web target covers the launcher basics, not yaml's serve/bridge modes):
 
 | `type` | Fields | Notes |
 | --- | --- | --- |
@@ -226,7 +226,9 @@ interface BddConfig {
 Every target also accepts `scope?: 'scenario' | 'worker'`:
 
 - `'scenario'` (default) — a fresh agent per scenario: full isolation, one Midscene report per scenario. Cheap for browsers.
-- `'worker'` — one agent per cucumber worker, reused across scenarios and destroyed when the worker finishes. Use this for device targets where reconnecting per scenario is expensive. Note the report semantics differ: scenarios share one rolling Midscene report (the same path is attached to each scenario) instead of one report per scenario. Factory configs are always scenario-scoped.
+- `'worker'` — one agent per cucumber worker, reused across scenarios and destroyed when the worker finishes. Use this for device targets where reconnecting per scenario is expensive. Note the report semantics differ: scenarios share one rolling Midscene report (the same path is attached to each scenario) instead of one report per scenario. If creation fails, the slot clears and the next scenario retries. Factory configs are always scenario-scoped.
+
+`uiAgentOptions.cache: true` uses one shared cache id (`'default'`) for the whole suite — unlike the yaml runner, which derives a per-file cache id. Set `cache: { id: '...' }` if you want finer granularity.
 
 The android/ios/harmony/computer platform packages are **optional peer dependencies** — install the one your target needs, e.g.:
 

packages/bdd/src/agents/ui-agent.ts

@@ -11,6 +11,7 @@
  * defaults to true.
  */
 import path from 'node:path';
+import { getDebug } from '@midscene/shared/logger';
 import {
   type AndroidUiTarget,
   type ComputerUiTarget,
@@ -19,6 +20,7 @@ import {
   type IOSUiTarget,
   type InterfaceUiTarget,
   type ResolvedBddConfig,
+  UI_TARGET_TYPES,
   type UiAgent,
   type UiAgentOptions,
   type WebUiTarget,
@@ -87,28 +89,42 @@ export async function createUiAgent(
     default: {
       const unreachable: never = uiAgent;
       throw new Error(
-        `${ERROR_PREFIX} unhandled uiAgent.type ${JSON.stringify(unreachable)}`,
+        `${ERROR_PREFIX} unhandled uiAgent.type '${String(
+          (unreachable as { type?: unknown }).type,
+        )}' — valid types: ${UI_TARGET_TYPES.join(', ')}`,
       );
     }
   }
 }
 
 /**
  * Lazy platform import with a pointed error when the optional peer
- * dependency `@midscene/<targetType>` is not installed.
+ * dependency `@midscene/<targetType>` is not installed. Only genuine
+ * resolution failures OF THAT PACKAGE get the install hint — an installed
+ * package that fails to load (broken transitive dep, native build failure)
+ * rethrows untouched so the real error stays the headline.
  */
-async function importPlatformPackage<T>(
+export async function importPlatformPackage<T>(
   targetType: string,
   importer: () => Promise<T>,
 ): Promise<T> {
+  const packageName = `@midscene/${targetType}`;
   try {
     return await importer();
   } catch (error) {
-    const packageName = `@midscene/${targetType}`;
+    const code = (error as NodeJS.ErrnoException).code;
+    // The QUOTED name is what Node puts around the unresolvable specifier
+    // ("Cannot find package '@midscene/x' …"); a transitive dep's failure
+    // only mentions our package unquoted inside the "imported from" path.
+    const notFound =
+      (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') &&
+      error instanceof Error &&
+      error.message.includes(`'${packageName}'`);
+    if (!notFound) {
+      throw error;
+    }
     throw new Error(
-      `${ERROR_PREFIX} uiAgent type '${targetType}' requires the optional peer dependency '${packageName}' — install it (e.g. \`pnpm add -D ${packageName}\`). Original error: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
+      `${ERROR_PREFIX} uiAgent type '${targetType}' requires the optional peer dependency '${packageName}' — install it (e.g. \`pnpm add -D ${packageName}\`).`,
       { cause: error },
     );
   }
@@ -250,6 +266,9 @@ async function createInterfaceUiAgent(
     path.isAbsolute(target.module)
       ? path.resolve(baseDir, target.module)
       : target.module;
+  getDebug('bdd:ui-agent')(
+    `interface module '${target.module}' resolved to '${specifier}'`,
+  );
 
   let importedModule: Record<string, unknown>;
   try {
@@ -274,6 +293,9 @@ async function createInterfaceUiAgent(
     );
   }
 
+  // Lazy not because core is optional (it's a hard dep) but to keep the
+  // unit-test mock surface small and module load cheap for non-interface
+  // targets.
   const { createAgent } = await import('@midscene/core/agent');
   const device = new (
     DeviceClass as new (

packages/bdd/src/config.ts

@@ -21,13 +21,6 @@ function configError(message: string): Error {
 
 function validateUiTarget(target: Record<string, unknown>): void {
   const type = target.type as UiTarget['type'];
-  if (!UI_TARGET_TYPES.includes(type)) {
-    throw configError(
-      `uiAgent.type '${String(type)}' is unknown — valid types: ${UI_TARGET_TYPES.join(
-        ', ',
-      )} (or pass a factory function)`,
-    );
-  }
 
   if (
     target.scope !== undefined &&
@@ -57,9 +50,15 @@ function validateUiTarget(target: Record<string, unknown>): void {
     case 'computer':
       // Everything is optional: deviceId/launch/displayId default sensibly.
       break;
+    // One guard for unknown types: the `never` binding keeps the switch
+    // exhaustive at compile time, the throw handles unvalidated JS configs.
     default: {
       const unreachable: never = type;
-      throw configError(`unhandled uiAgent.type ${String(unreachable)}`);
+      throw configError(
+        `uiAgent.type '${String(unreachable)}' is unknown — valid types: ${UI_TARGET_TYPES.join(
+          ', ',
+        )} (or pass a factory function)`,
+      );
     }
   }
 }

packages/bdd/src/types.ts

@@ -86,7 +86,10 @@ export interface WebUiTarget extends UiTargetCommon {
 /** Field vocabulary mirrors the yaml `android:` env (deviceId, launch, ...). */
 export interface AndroidUiTarget
   extends UiTargetCommon,
-    Omit<AndroidDeviceOpt, 'customActions'> {
+    // customActions is callback-typed (not config material); the resize
+    // scale is deprecated-and-ignored in core — a new API has no reason to
+    // accept either.
+    Omit<AndroidDeviceOpt, 'customActions' | 'screenshotResizeScale'> {
   type: 'android';
   /** ADB device id; defaults to the first connected device. */
   deviceId?: string;
@@ -106,12 +109,14 @@ export interface IOSUiTarget
 /** Field vocabulary mirrors the yaml `harmony:` env (deviceId, launch, ...). */
 export interface HarmonyUiTarget
   extends UiTargetCommon,
-    Omit<HarmonyDeviceOpt, 'customActions'> {
+    Omit<HarmonyDeviceOpt, 'customActions' | 'screenshotResizeScale'> {
   type: 'harmony';
   /** HDC device id; defaults to the first connected device. */
   deviceId?: string;
   /** App package to launch after connecting (optional). */
   launch?: string;
+  /** App-name → bundle-name mapping for launch, as in the yaml env. */
+  appNameMapping?: Record<string, string>;
 }
 
 /** Field vocabulary mirrors the yaml `computer:` env. */
@@ -144,6 +149,16 @@ export const UI_TARGET_TYPES = [
   'interface',
 ] as const satisfies readonly UiTarget['type'][];
 
+// Completeness tripwire: `satisfies` above rejects typos but not omissions —
+// this fails to compile until a new union member is added to the array.
+type MissingTargetTypes = Exclude<
+  UiTarget['type'],
+  (typeof UI_TARGET_TYPES)[number]
+>;
+const _allTargetTypesListed: MissingTargetTypes extends never ? true : never =
+  true;
+void _allTargetTypesListed;
+
 /**
  * Declarative UI target — one flat object per platform, discriminated on
  * `type`. android/ios/harmony/computer need their optional peer package
@@ -160,9 +175,10 @@ export type UiTarget =
 /**
  * Agent construction options shared by every target type — mirrors the yaml
  * `agent:` block (generateReport, reportFileName, groupName, cache, ...).
- * `generateReport` defaults to true.
+ * `generateReport` defaults to true. (`testId` is a deprecated yaml alias a
+ * new API has no reason to accept.)
  */
-export type UiAgentOptions = MidsceneYamlScriptAgentOpt;
+export type UiAgentOptions = Omit<MidsceneYamlScriptAgentOpt, 'testId'>;
 
 export type UiAgentFactory = () => Promise<{
   agent: UiAgent;