@solidxai/core 0.1.15 → 0.1.16-beta.1

package/src/services/authentication.service.ts

@@ -40,6 +40,7 @@ import { User } from "../entities/user.entity";
 import { EventDetails, EventType } from "../interfaces";
 import { ActiveUserData } from "../interfaces/active-user-data.interface";
 import { ActiveSessionStorageService } from "./active-session-storage.service";
+import { AccessTokenDenylistService } from "./access-token-denylist.service";
 import { HashingService } from "./hashing.service";
 import {
   InvalidatedRefreshTokenError,
@@ -77,6 +78,7 @@ export class AuthenticationService {
     private readonly hashingService: HashingService,
     private readonly jwtService: JwtService,
     private readonly activeSessionStorage: ActiveSessionStorageService,
+    private readonly accessTokenDenylist: AccessTokenDenylistService,
     private readonly refreshTokenIdsStorage: RefreshTokenIdsStorageService,
     private readonly httpService: HttpService,
     // private readonly mailService: SMTPEMailService,
@@ -2356,15 +2358,34 @@ export class AuthenticationService {
       }
 
       const userId = payload.sub;
+
       if (allDevices) {
+        // Deliberately not gated on session ownership: "log out everywhere"
+        // treats any verifiable refresh token as sufficient authority, which is
+        // what invalidateAll already accepts.
         await this.refreshTokenIdsStorage.invalidateAll(userId);
-      } else {
+        await this.accessTokenDenylist.revokeAllForUser(userId);
+      } else if (await this.ownsLiveSession(userId, payload, refreshToken)) {
         // Scoped to the bucket this token belongs to, so signing out on one
         // device leaves the others alive. A token with no deviceKey names the
         // single slot, which is the same key as before.
         await this.refreshTokenIdsStorage.invalidate(userId, payload.deviceKey);
+        await this.accessTokenDenylist.revokeSession(
+          userId,
+          await this.resolveRevocationKey(userId, payload),
+        );
+        await this.activeSessionStorage.clearActiveSession(userId);
+      } else {
+        // The token names a session that is already gone - superseded by a
+        // newer login into the same bucket. Acting on it would destroy the
+        // session that replaced it. Nothing to do, but log it: the failure is
+        // otherwise invisible, and a cluster of these means clients are losing
+        // token state and their logouts are no-ops.
+        this.logger.warn(
+          `logout: refresh token does not match the live session for user ${userId}; nothing invalidated`,
+        );
       }
-      await this.activeSessionStorage.clearActiveSession(userId);
+
       const user = await this.userRepository.findOne({
         where: {
           id: userId,
@@ -2387,6 +2408,101 @@ export class AuthenticationService {
     }
   }
 
+  /**
+   * Whether this refresh token belongs to the session that currently occupies
+   * its bucket.
+   *
+   * A per-device bucket holds exactly one session - deviceKey is a fresh
+   * randomUUID per login - so a token carrying one is that session by
+   * construction and needs no further proof. Only the bare `user-<id>` bucket
+   * is shared across logins (preventConcurrentLogins on, or a pre-migration
+   * token), and that is the sole case where a stale token can name a session
+   * that has since been replaced. Without this, a laptop whose session was
+   * superseded by a phone login would, on logging out, destroy the phone's
+   * session instead of its own.
+   *
+   * Matches current OR previous, and deliberately does not consult
+   * isWithinGraceWindow: that window governs whether a rotated-out token may
+   * still be exchanged, whereas the question here is only which session the
+   * token belongs to - which stays true however long ago it rotated.
+   *
+   * Missing state means it owns nothing. Safe, because the refresh state and
+   * active-session entry share one cache: if the state is gone the session
+   * entry is too, so the actions being skipped were no-ops anyway.
+   */
+  private async ownsLiveSession(
+    userId: number,
+    payload: { deviceKey?: string },
+    refreshToken: string,
+  ): Promise<boolean> {
+    if (payload.deviceKey) {
+      return true;
+    }
+
+    const state =
+      await this.refreshTokenIdsStorage.getCurrentRefreshTokenState(userId);
+    return (
+      state?.currentRefreshToken === refreshToken ||
+      (!!state?.previousRefreshToken &&
+        state.previousRefreshToken === refreshToken)
+    );
+  }
+
+  /**
+   * The key a session's access tokens are denylisted under. Mirrors how the
+   * access token itself is stamped: deviceKey while concurrent logins are
+   * allowed, sessionId while they are not - and in the latter case only one
+   * session exists, so the recorded active session IS this session's id.
+   *
+   * Must be read before clearActiveSession, which deletes the value it reads.
+   */
+  private async resolveRevocationKey(
+    userId: number,
+    payload: { deviceKey?: string },
+  ): Promise<string | undefined> {
+    return (
+      payload.deviceKey ??
+      (await this.activeSessionStorage.getActiveSession(userId))
+    );
+  }
+
+  /**
+   * Public seam for consuming projects that need a logout of their own shape -
+   * for instance revoking the access token while deliberately leaving the
+   * refresh token valid.
+   *
+   * Verifies the refresh token (signature/audience/issuer enforced, expiry
+   * tolerated), confirms it owns the live session, and returns the key its
+   * access tokens are denylisted under.
+   *
+   *   null                    - unverifiable: forged, malformed, or an access
+   *                             token presented here
+   *   revocationKey undefined - verified, but nothing safe to revoke: either a
+   *                             superseded session, or no session key could be
+   *                             resolved. userId is still returned so the caller
+   *                             can log the event or call revokeAllForUser.
+   *
+   * logout() uses this same method, so the seam cannot silently rot.
+   */
+  async resolveSessionRevocationKey(
+    refreshToken: string,
+  ): Promise<{ userId: number; revocationKey?: string } | null> {
+    const payload = await this.verifyRefreshTokenForLogout(refreshToken);
+    if (!payload?.sub) {
+      return null;
+    }
+
+    const userId = payload.sub;
+    if (!(await this.ownsLiveSession(userId, payload, refreshToken))) {
+      return { userId };
+    }
+
+    return {
+      userId,
+      revocationKey: await this.resolveRevocationKey(userId, payload),
+    };
+  }
+
   private async verifyRefreshTokenForLogout(
     refreshToken: string,
   ): Promise<{ sub: number; deviceKey?: string } | null> {

package/src/services/import-transaction.service.ts

@@ -607,12 +607,28 @@ export class ImportTransactionService extends CRUDService<ImportTransaction> {
   //FIXME Currently below method fails if any field in the record is not valid or if the record is not valid. It does not collect the errors for all fields in a record
   private async insertRecord(record: Record<string, any>, mapping: ImportMapping[], modelMetadataWithFields: ModelMetadata, modelService: CRUDService<any>): Promise<any> {
     // Convert the imported record to a DTO
-    const dto = await this.convertImportedRecordToDto(record, mapping, modelMetadataWithFields);
+    const dto = await this.convertImportedRecordToDto(record, mapping, modelMetadataWithFields, modelService);
     // Use the model service to create the record in the database
     const createdRecord = await modelService.create(dto, [], {}); //FIXME: Need to handle this part alongwith the refactoring of the CRUDService for permissions
     return createdRecord; // Return the created record
   }
 
+  // Import files do not contain hidden internal fields. Add the entity's
+  // defaults before CRUD validation so those fields do not fail as missing.
+  private applyImportDefaults(dto: Record<string, any>, modelService: CRUDService<any>): void {
+    for (const column of modelService.repo.metadata.columns) {
+      if (dto[column.propertyName] !== undefined || column.default === undefined) {
+        continue;
+      }
+
+      // Leave SQL expression defaults (such as CURRENT_TIMESTAMP) for the
+      // database instead of putting the expression text into the DTO.
+      if (typeof column.default !== 'function') {
+        dto[column.propertyName] = column.default;
+      }
+    }
+  }
+
   private getModelService(modelSingularName: string): CRUDService<any> {
     // Get the model service for the model metadata name
     const modelServiceWrapper = this.introspectService.getProvider(`${classify(modelSingularName)}Service`);
@@ -623,7 +639,7 @@ export class ImportTransactionService extends CRUDService<ImportTransaction> {
     return modelService;
   }
 
-  private async convertImportedRecordToDto(record: Record<string, any>, mapping: ImportMapping[], modelMetadataWithFields: ModelMetadata) {
+  private async convertImportedRecordToDto(record: Record<string, any>, mapping: ImportMapping[], modelMetadataWithFields: ModelMetadata, modelService: CRUDService<any>) {
     // Create a new record object
     const dtoRecord: Record<string, any> = {};
 
@@ -644,43 +660,10 @@ export class ImportTransactionService extends CRUDService<ImportTransaction> {
       }
     }
 
-    // Some fields are hidden from the import file because users should not
-    // have to enter internal values such as passwordSchemeVersion. The
-    // backend still checks those fields as required, so fill in their default
-    // values here before validation. This lets users import normal details
-    // without exposing or requiring internal fields in the template.
-    for (const field of modelMetadataWithFields.fields) {
-      if (
-        field.required &&
-        field.defaultValue !== null &&
-        field.defaultValue !== undefined &&
-        !(field.name in dtoRecord)
-      ) {
-        dtoRecord[field.name] = this.parseImportDefaultValue(field);
-      }
-    }
-
+    this.applyImportDefaults(dtoRecord, modelService);
     return dtoRecord;
   }
 
-  // Defaults come from metadata as text. Convert them to the type expected by
-  // validation, so values like "1" and "true" are handled as a number and a
-  // boolean instead of being treated as plain text.
-  private parseImportDefaultValue(field: FieldMetadata): any {
-    const defaultValue = field.defaultValue;
-
-    switch (field.type) {
-      case SolidFieldType.boolean:
-        return ['true', '1', 'yes'].includes(String(defaultValue).toLowerCase());
-      case SolidFieldType.int:
-      case SolidFieldType.bigint:
-      case SolidFieldType.decimal:
-        return Number(defaultValue);
-      default:
-        return defaultValue;
-    }
-  }
-
   private async populateDtoForACell(dtoRecord: Record<string, any>, fieldMetadata: FieldMetadata, record: Record<string, any>, key: string): Promise<Record<string, any>> {
     const fieldType = fieldMetadata.type;
     // const userKeyFieldName = userKeyField?.name || 'id'; // Default to 'id' if not found

package/src/services/module-metadata.service.ts

@@ -142,8 +142,8 @@ export class ModuleMetadataService {
         throw new BadRequestException('Dangerous file types are not allowed for the menu icon.');
       }
       const fileStoragePath = this.getFullFilePathForDisk(this.getFileName(files[0]));
-      this.fileService.copy(files[0].path, fileStoragePath);
-      this.fileService.delete(files[0].path);
+      await this.fileService.copy(files[0].path, fileStoragePath);
+      await this.fileService.delete(files[0].path);
       createDto.menuIconUrl = fileStoragePath;
     }
     const moduleMetadata = this.moduleMetadataRepo.create(createDto);
@@ -250,8 +250,8 @@ export class ModuleMetadataService {
       }
 
       const fileStoragePath = this.getFullFilePathForDisk(this.getFileName(files[0]));
-      this.fileService.copy(files[0].path, fileStoragePath);
-      this.fileService.delete(files[0].path);
+      await this.fileService.copy(files[0].path, fileStoragePath);
+      await this.fileService.delete(files[0].path);
       module.menuIconUrl = fileStoragePath;
     }
     return manager.save(ModuleMetadata, module);

package/src/services/settings/default-settings-provider.service.ts

@@ -1263,6 +1263,18 @@ const getSolidCoreSettings = (isProd: boolean) =>
       sortOrder: 200,
       controlType: "boolean",
     },
+    {
+      moduleName: "solid-core",
+      key: "invalidateAccessTokenOnLogout",
+      value: false,
+      level: SettingLevel.SystemAdminEditable,
+      label: "Invalidate Access Token On Logout",
+      group: "authentication-settings",
+      sortOrder: 205,
+      controlType: "boolean",
+      helpText:
+        "Rejects a session's access token on the next request after logout, instead of letting it live out its remaining lifetime. Adds a cache lookup to every authenticated request, and needs Redis configured to take effect across multiple replicas.",
+    },
     {
       moduleName: "solid-core",
       key: "mpinEnabled",

package/src/services/workflow-secret.service.ts

@@ -1,7 +1,7 @@
-import { BadRequestException, Injectable, Logger } from '@nestjs/common';
+import { BadRequestException, Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { InjectEntityManager } from '@nestjs/typeorm';
 import { ModuleRef } from "@nestjs/core";
-import { EntityManager } from 'typeorm';
+import { EntityManager, In } from 'typeorm';
 import { CRUDService } from 'src/services/crud.service';
 import { WorkflowSecret } from '../entities/workflow-secret.entity';
 import { WorkflowSecretRepository } from '../repository/workflow-secret.repository';
@@ -88,6 +88,65 @@ export class WorkflowSecretService extends CRUDService<WorkflowSecret> {
     return context;
   }
 
+  /**
+   * Resolves one secret to its decrypted, type-coerced value.
+   *
+   * `key` is the literal key column value — "smtp.password" is one row, not a path.
+   * Callers must resolve at point of use and must not cache the result.
+   */
+  async resolve(key: string): Promise<any> {
+    const resolved = await this.resolveMany([key]);
+    return resolved[key];
+  }
+
+  /**
+   * Resolves whatever of `keys` exists and is active, in a single query, omitting the
+   * rest. Returns a flat map keyed by the literal keys requested.
+   *
+   * For callers that can report a missing key better than this service can — the test
+   * runner lets an unresolved key surface at the step that references it, which names
+   * the token and locates the failure. Prefer resolveMany elsewhere.
+   *
+   * Still fail-closed on infrastructure: an absent APP_ENCRYPTION_KEY or a failed
+   * decrypt throws rather than yielding a partial map.
+   */
+  async resolveAvailable(keys: string[]): Promise<Record<string, any>> {
+    const uniqueKeys = Array.from(new Set((keys ?? []).filter(Boolean)));
+    if (uniqueKeys.length === 0) {
+      return {};
+    }
+
+    const secrets = await this.repo.find({
+      where: { key: In(uniqueKeys), status: "active" } as any,
+    });
+
+    return secrets.reduce((resolved, secret) => {
+      resolved[secret.key] = this.decryptAndCoerce(secret);
+      return resolved;
+    }, {} as Record<string, any>);
+  }
+
+  /**
+   * Resolves several secrets in a single query, returning a flat map keyed by the
+   * literal keys requested.
+   *
+   * Fail-closed: throws for a key that is missing, inactive or undecryptable rather
+   * than omitting it from the result. A credential that silently resolves to undefined
+   * becomes an empty password on an outbound request.
+   */
+  async resolveMany(keys: string[]): Promise<Record<string, any>> {
+    const resolved = await this.resolveAvailable(keys);
+
+    const missing = Array.from(new Set((keys ?? []).filter(Boolean))).filter(
+      (key) => !(key in resolved),
+    );
+    if (missing.length > 0) {
+      throw new NotFoundException(`No active secret found for: ${missing.join(', ')}`);
+    }
+
+    return resolved;
+  }
+
   private prepareSecretForSave(dto: any, requireValue: boolean): any {
     const preparedDto = { ...dto };
     const rawValue = preparedDto.value;

package/src/solid-core.module.ts

@@ -100,6 +100,7 @@ import { OTPAuthenticationController } from "./controllers/otp-authentication.co
 import { ServiceController } from "./controllers/service.controller";
 import { SmsTemplateController } from "./controllers/sms-template.controller";
 import { TestQueueController } from "./controllers/test-queue.controller";
+import { TestRunController } from "./controllers/test-run.controller";
 import { EmailAttachment } from "./entities/email-attachment.entity";
 import { EmailTemplate } from "./entities/email-template.entity";
 import { MenuItemMetadata } from "./entities/menu-item-metadata.entity";
@@ -117,6 +118,8 @@ import { ApiEmailQueuePublisher } from "./jobs/rabbitmq/api-email-publisher.serv
 import { ApiEmailQueueSubscriber } from "./jobs/rabbitmq/api-email-subscriber.service";
 import { TestQueuePublisherDatabase } from "./jobs/database/test-queue-publisher-database.service";
 import { TestQueueSubscriberDatabase } from "./jobs/database/test-queue-subscriber-database.service";
+import { TestRunQueuePublisherDatabase } from "./jobs/database/test-run-queue-publisher-database.service";
+import { TestRunQueueSubscriberDatabase } from "./jobs/database/test-run-queue-subscriber-database.service";
 import { TestQueuePublisherRedis } from "./jobs/redis/test-queue-publisher-redis.service";
 import { TestQueueSubscriberRedis } from "./jobs/redis/test-queue-subscriber-redis.service";
 import { Msg91WhatsappQueuePublisher } from "./jobs/rabbitmq/msg91-whatsapp-publisher.service";
@@ -167,6 +170,7 @@ import { GoogleOauthStrategy } from "./passport-strategies/google-oauth.strategy
 import { ApiKeyService } from "./services/api-key.service";
 import { MpinService } from "./services/mpin.service";
 import { ActiveSessionStorageService } from "./services/active-session-storage.service";
+import { AccessTokenDenylistService } from "./services/access-token-denylist.service";
 import { AuthenticationService } from "./services/authentication.service";
 import { MetadataValidationService } from "./services/metadata-validation.service";
 import { BcryptService } from "./services/bcrypt.service";
@@ -626,6 +630,7 @@ import { SwitchNode } from './services/workflow/nodes/switch.node';
     SmsTemplateController,
     TestController,
     TestQueueController,
+    TestRunController,
     UserActivityHistoryController,
     UserController,
     UserViewMetadataController,
@@ -778,6 +783,7 @@ import { SwitchNode } from './services/workflow/nodes/switch.node';
     ApiKeyService,
     MpinService,
     ActiveSessionStorageService,
+    AccessTokenDenylistService,
     AuthenticationService,
     GoogleAuthenticationController,
     RefreshTokenIdsStorageService,
@@ -802,6 +808,8 @@ import { SwitchNode } from './services/workflow/nodes/switch.node';
 
     TestQueuePublisherDatabase,
     TestQueueSubscriberDatabase,
+    TestRunQueuePublisherDatabase,
+    TestRunQueueSubscriberDatabase,
     TestQueuePublisherRedis,
     TestQueueSubscriberRedis,
     ApiEmailQueuePublisherRedis,
@@ -996,6 +1004,9 @@ import { SwitchNode } from './services/workflow/nodes/switch.node';
     SolidXSendSmsNode,
   ],
   exports: [
+    // Exported for DI, not merely re-exported from index.ts: a consuming
+    // project composing its own logout has to be able to inject this.
+    AccessTokenDenylistService,
     AuthenticationService,
     ChatterMessageDetailsRepository,
     ChatterMessageDetailsService,

package/src/testing/README.md

@@ -8,6 +8,21 @@
 - `reporter/`: reporting interfaces + console reporter
 - `runner/`: lifecycle helpers + metadata runner
 
+## Browser Setup
+UI scenarios need a Chromium build. The npm `playwright` package ships no install script, so
+the binary is fetched separately.
+
+- **By default it is lazy.** The first test run that selects a UI scenario downloads Chromium
+  (~150MB) before the run starts, then reuses it. Runs filtered to API-only scenarios never
+  download anything, and neither do projects that have no UI scenarios.
+- **To fetch it at install time instead**, set `COMMON_UI_TEST_BROWSERS_EAGER_INSTALL=true`
+  either in the API project's `.env` or as a real environment variable. Useful for CI images.
+  A failed download never fails the install. Note that `npm install --ignore-scripts` skips
+  this entirely, in which case the lazy path still applies.
+- **In Docker**, browsers land in `~/.cache/ms-playwright` (Linux). A multi-stage build that
+  installs as `root` but runs as another user must set `PLAYWRIGHT_BROWSERS_PATH` to a shared
+  location, or the runtime user will not find the binary.
+
 ## Metadata Shape
 `TestingMetadata` lives under `testing` in module metadata JSON files.
 
@@ -252,11 +267,14 @@ Options in `with`:
 - `timeoutMs` (optional, overrides the run-wide UI navigation timeout)
 
 ### **Op: `ui.expectUrl`**
-Description: Asserts the current page URL.
+Description: Waits for the page URL to match, then asserts it. Backed by `page.waitForURL`, so an
+assertion placed straight after a navigating click does not race the navigation. Returns
+immediately when the URL already matches.
 
 Options in `with`:
 - `equals` (optional)
 - `contains` (optional)
+- `timeoutMs` (optional, overrides the run-wide UI navigation timeout)
 
 ### **Op: `ui.fill`**
 Description: Fills an input or editable element.
@@ -289,6 +307,19 @@ Options in `with`:
 - `key` (required)
 - `timeoutMs` (optional, overrides the run-wide UI timeout)
 
+### **Op: `ui.uploadFile`**
+Description: Sets one or more files on a file input.
+
+Options in `with`:
+- `selector` (required, the `<input type="file">`)
+- `filePath` (required, a path or an array of paths)
+- `timeoutMs` (optional, overrides the run-wide UI timeout)
+
+Notes:
+- Paths are resolved against the run's working directory, so a relative path is relative to where
+  `solid test run` was invoked.
+- Pass an array to populate a `multiple` input; a single string is the common case.
+
 ### **Op: `ui.waitForManual`**
 Description: Pauses a headed Playwright run so a human can interact with the live browser, then resumes when Enter is pressed in the terminal.
 
@@ -327,6 +358,18 @@ Options in `with`:
 - `selector` (required)
 - `timeoutMs` (optional, overrides the run-wide UI timeout)
 
+### **Op: `ui.expectHidden`**
+Description: Waits for an element to be hidden — i.e. detached or no longer visible.
+
+Options in `with`:
+- `selector` (required)
+- `timeoutMs` (optional, overrides the run-wide UI timeout)
+
+Notes:
+- The counterpart to `ui.expectVisible`: use it to wait for a modal, spinner, toast or overlay to
+  **go away** before the next step acts. Prefer it over `util.sleep` for that — it returns the moment
+  the element disappears instead of always spending the full duration.
+
 ### **Op: `ui.expectText`**
 Description: Asserts the text content of an element.
 

package/src/testing/adapters/ui/browser-provisioner.ts

@@ -0,0 +1,115 @@
+import { ChildProcess, spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * The npm `playwright` package ships no install script, so `npm install` places the
+ * JS module but never downloads the browser binary. These helpers fetch it on demand.
+ */
+
+let inFlight: Promise<void> | null = null;
+let activeInstall: ChildProcess | null = null;
+
+/**
+ * Resolves Playwright's own CLI entry point.
+ *
+ * `require.resolve('playwright/cli.js')` fails with ERR_PACKAGE_PATH_NOT_EXPORTED because
+ * `cli.js` is absent from Playwright's `exports` map, so we resolve `package.json` (which
+ * is exported) and walk to its sibling.
+ */
+export function resolvePlaywrightCli(): string | null {
+  try {
+    const packageJsonPath = require.resolve("playwright/package.json");
+    const cliPath = path.join(path.dirname(packageJsonPath), "cli.js");
+    return fs.existsSync(cliPath) ? cliPath : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Asking Playwright for the executable path keeps us in step with PLAYWRIGHT_BROWSERS_PATH
+ * and its per-version cache layout instead of second-guessing either.
+ */
+export async function isChromiumInstalled(): Promise<boolean> {
+  try {
+    const { chromium } = await import("playwright");
+    return fs.existsSync(chromium.executablePath());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Downloads Chromium unless it is already present. Only Chromium is fetched: it is the
+ * sole browser PlaywrightAdapter launches.
+ *
+ * Concurrent callers share one download. This matters once a server warms the browser up
+ * at boot while a test run may start before that finishes.
+ */
+export function ensureChromiumInstalled(): Promise<void> {
+  if (!inFlight) {
+    // Clearing on settle rather than caching the result lets a failed download be retried
+    // by the next caller instead of poisoning the whole process lifetime.
+    inFlight = installChromium().finally(() => {
+      inFlight = null;
+      activeInstall = null;
+    });
+  }
+  return inFlight;
+}
+
+/**
+ * Stops a download that is still running, so shutting down mid-install does not orphan the
+ * child process against a half-written browser cache.
+ */
+export function cancelChromiumInstall(): void {
+  activeInstall?.kill("SIGTERM");
+}
+
+async function installChromium(): Promise<void> {
+  if (await isChromiumInstalled()) return;
+
+  const cliPath = resolvePlaywrightCli();
+  if (!cliPath) {
+    throw new Error(
+      "Chromium is required for UI scenarios but the playwright package could not be resolved. " +
+        "Install it in the API project with: npm install playwright",
+    );
+  }
+
+  console.log(
+    "Chromium is required for UI scenarios and is not installed yet. Downloading it now (~150MB, one time)...",
+  );
+
+  await new Promise<void>((resolve, reject) => {
+    // Async spawn, never spawnSync: this also runs inside a live server during module init,
+    // where a synchronous child would block the event loop for the whole download.
+    const child = spawn(process.execPath, [cliPath, "install", "chromium"], {
+      stdio: "inherit",
+    });
+    activeInstall = child;
+
+    child.on("error", (error) =>
+      reject(
+        new Error(
+          `Failed to download Chromium: ${error.message}. ` +
+            "Install it manually with: npx playwright install chromium",
+        ),
+      ),
+    );
+
+    child.on("close", (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(
+        new Error(
+          `Chromium download ${signal ? `was stopped by ${signal}` : `exited with code ${code}`}. ` +
+            "Install it manually with: npx playwright install chromium",
+        ),
+      );
+    });
+  });
+}