clearcote 0.47.0 → 0.49.0

package/dist/pacing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pacing.js","sourceRoot":"","sources":["../src/pacing.ts"],"names":[],"mappings":"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"}

package/dist/widevine.d.ts

@@ -1,12 +1,40 @@
+/** 1/true/yes/on forces Widevine on, 0/false/no/off off; an explicit `widevine` option wins over it. */
+export declare const WIDEVINE_ENV = "CLEARCOTE_WIDEVINE";
+/** How long a DEFAULT (not requested) launch waits for a first download, in seconds (clamped to 1-600). */
+export declare const TIMEOUT_ENV = "CLEARCOTE_WIDEVINE_TIMEOUT_SECONDS";
+export declare const DEFAULT_TIMEOUT_SECONDS = 15;
+export declare const MIN_TIMEOUT_SECONDS = 1;
+export declare const MAX_TIMEOUT_SECONDS = 600;
+/** Ask Google for a newer CDM at most once a day. */
+export declare const CHECK_INTERVAL_MS: number;
+/** A failed first download is not retried for 10 minutes in this process. */
+export declare const RETRY_AFTER_MS = 600000;
+/** How long a background refresh waits for Google's update check (it may hold a finishing process that long). */
+export declare const REFRESH_CHECK_TIMEOUT_MS = 10000;
+/** In the cache root: its mtime is the last update check (a failed one counts). */
+export declare const STAMP_FILE = ".last-check";
+/** What a CDM version looks like; anything else never becomes a path. */
+export declare const VERSION_RE: RegExp;
+/** How long a requested install waits for another process installing the CDM. */
+export declare const LOCK_WAIT_MS = 300000;
+export declare const WARN_CODE = "widevine-default";
+/** What one launch does about Widevine: requested, the licensed default, or nothing. */
+export type WidevineMode = "explicit" | "default" | "off";
 /** Chrome's component-updater app id for the Widevine CDM + Google's Omaha JSON endpoint. */
 export declare const WIDEVINE_APP_ID = "oimompecagnajdejgnnjijobebaeigek";
 export declare const OMAHA_URL = "https://update.googleapis.com/service/update2/json";
 export declare const HINT_FILE = "latest-component-updated-widevine-cdm";
 export interface WidevineOptions {
-    /** Destination root (default ~/.clearcote/WidevineCdm). */
+    /** Destination root (default CLEARCOTE_WIDEVINE_DIR, else ~/.clearcote/WidevineCdm). */
     dest?: string;
     /** Suppress progress logging. */
     quiet?: boolean;
+    /** Abort the update check and the download (the default launch path bounds its wait with it). */
+    signal?: AbortSignal;
+    /** Abort only the update check (a background refresh bounds it). */
+    checkSignal?: AbortSignal;
+    /** How long to wait for another process installing the CDM (default 5 minutes). */
+    lockTimeoutMs?: number;
 }
 /** Minimal Omaha v3.1 update check for the current-OS x64 Widevine CDM (version 0.0.0.0 -> latest). */
 export declare function omahaRequestBody(): unknown;
@@ -14,15 +42,60 @@ export declare function omahaRequestBody(): unknown;
 export declare function parseUpdate(resp: any): [string, string, string];
 /** A CRX3 file is 'Cr24' + u32 version + u32 headerLen + header + zip. Return the zip bytes. */
 export declare function crx3ToZip(buf: Buffer): Buffer;
+/** The newest complete CDM in the cache (`root`, default the cache root), or undefined. No network. */
+export declare function cachedCdm(root?: string): string | undefined;
 /**
- * Download + verify the current-OS x64 Widevine CDM into `dest` (default ~/.clearcote/WidevineCdm/
- * <version>). Returns the versioned CDM directory (manifest.json + _platform_specific/<subdir>/
- * <filename>). Re-fetch is skipped if already present.
+ * Download + verify the current-OS x64 Widevine CDM into `dest` (default CLEARCOTE_WIDEVINE_DIR, else
+ * ~/.clearcote/WidevineCdm) as <version>/. Returns the versioned CDM directory (manifest.json +
+ * _platform_specific/<subdir>/<filename>).
+ *
+ * Always asks Google's update server for the latest version; the download is skipped when that version is
+ * already installed. Installs take the install lock and land with a rename. A version that does not look
+ * like one is refused.
  */
 export declare function fetchWidevine(opts?: WidevineOptions): Promise<string>;
+/**
+ * The CDM directory a launch should use, network only when needed: the cached CDM when Google was asked
+ * within the last day (no network), otherwise {@link fetchWidevine}. When that fails (offline, a firewall,
+ * Google refusing the request) the CDM already on disk still works and is used, and the failed check is
+ * recorded (the stamp is touched), so no launch asks again for a day. Rejects only when there is no CDM.
+ */
+export declare function resolveCdm(opts?: WidevineOptions): Promise<string>;
+/**
+ * `"explicit"`, `"default"` or `"off"` for a launch. `option` (the `widevine` launch option) wins: true ->
+ * explicit, false -> off. Unset follows CLEARCOTE_WIDEVINE (1/true/yes/on -> explicit, 0/false/no/off ->
+ * off). Otherwise a licensed launch (a licence key resolved, which selects the PRO build) gets the default
+ * and a free launch stays off. Same rules in the Python and .NET SDKs.
+ */
+export declare function widevineMode(option: boolean | undefined | null, licensed: boolean, env?: NodeJS.ProcessEnv): WidevineMode;
+/** How long a default launch waits for a first download: CLEARCOTE_WIDEVINE_TIMEOUT_SECONDS clamped to 1-600, else 15
+ * (an unparsable or non-positive value too). */
+export declare function timeoutSeconds(env?: NodeJS.ProcessEnv): number;
+/** Tests: forget the in-flight fetch, the refresh and the last failure (and stop what is running). */
+export declare function resetWidevineDefaultState(): void;
+/** Tests: the background refresh in flight, if any. */
+export declare function widevineRefreshInFlight(): Promise<void> | undefined;
+/** Tests: pretend the last failure was this long ago. */
+export declare function ageLastWidevineFailure(byMs: number): void;
+/**
+ * The CDM for a launch that did not ask for Widevine (the licensed default), or undefined.
+ *
+ * A CDM in the cache is used AT ONCE, with no network on the launch path; when its last update check is over a
+ * day old, a background refresh asks Google for a newer one (used from the next launch on). Only with nothing
+ * cached does the launch wait for a download, at most `timeoutMs` (default {@link timeoutSeconds}). FAIL-SOFT:
+ * never rejects. When there is no CDM to use (the download failed or did not finish in time) it warns once per
+ * process (unless quiet) and answers undefined, so the launch goes on without DRM; a download still running at
+ * the deadline is cancelled (it cannot keep the process alive), and a failed one is not retried for
+ * RETRY_AFTER_MS in this process. The fetches here are quiet: the default path prints nothing else.
+ */
+export declare function defaultCdm(opts?: {
+    quiet?: boolean;
+    timeoutMs?: number;
+}): Promise<string | undefined>;
 /**
  * Make a persistent profile load the fetched CDM: copy it under <userDataDir>/WidevineCdm/<version>/
- * and write the component hint file the engine reads. Fetches the CDM first if needed.
+ * and write the component hint file the engine reads. Fetches the CDM first if needed
+ * ({@link resolveCdm}: the cached one when it is current).
  */
 export declare function seedWidevine(userDataDir: string, opts?: WidevineOptions): Promise<string>;
 /**
@@ -51,4 +124,16 @@ export declare function widevineArgs(ignoreDefaultArgs: string[] | boolean | und
 export declare function widevineCdmArgs(exe: string | undefined, opts?: {
     quiet?: boolean;
 }): Promise<string[]>;
+/**
+ * The Widevine switch for one launch, by {@link widevineMode}. explicit: {@link widevineCdmArgs} (the
+ * behaviour `widevine: true` always had). default: the same switch, only on an engine that implements it
+ * (r32+; an older engine keeps the old default, off), with the CDM from {@link defaultCdm} (bounded,
+ * fail-soft, warns once). off: nothing. A `--widevine-cdm-path` the caller put in `args` is theirs:
+ * nothing is added then. Works for every launch path: such an engine loads the CDM without a profile,
+ * incognito included.
+ */
+export declare function widevineLaunchArgs(exe: string | undefined, option: boolean | undefined | null, licensed: boolean, userArgs: readonly string[] | undefined, opts?: {
+    quiet?: boolean;
+    timeoutMs?: number;
+}): Promise<string[]>;
 //# sourceMappingURL=widevine.d.ts.map

package/dist/widevine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widevine.d.ts","sourceRoot":"","sources":["../src/widevine.ts"],"names":[],"mappings":"AAoBA,6FAA6F;AAC7F,eAAO,MAAM,eAAe,qCAAqC,CAAC;AAClE,eAAO,MAAM,SAAS,uDAAuD,CAAC;AAC9E,eAAO,MAAM,SAAS,0CAA0C,CAAC;AAwBjE,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAUD,uGAAuG;AACvG,wBAAgB,gBAAgB,IAAI,OAAO,CAiB1C;AAgBD,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAe/D;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM7C;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgC/E;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBnG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,iBAAiB,EAAE,MAAM,EAAE,GAAG,OAAO,GAAG,SAAS,EACjD,QAAQ,EAAE,MAAM,EAAE,GACjB;IAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,OAAO,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAevE;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOhH"}
+{"version":3,"file":"widevine.d.ts","sourceRoot":"","sources":["../src/widevine.ts"],"names":[],"mappings":"AAwCA,wGAAwG;AACxG,eAAO,MAAM,YAAY,uBAAuB,CAAC;AACjD,2GAA2G;AAC3G,eAAO,MAAM,WAAW,uCAAuC,CAAC;AAChE,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,QAAgB,CAAC;AAC/C,6EAA6E;AAC7E,eAAO,MAAM,cAAc,SAAU,CAAC;AACtC,iHAAiH;AACjH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,mFAAmF;AACnF,eAAO,MAAM,UAAU,gBAAgB,CAAC;AACxC,yEAAyE;AACzE,eAAO,MAAM,UAAU,QAA4B,CAAC;AACpD,iFAAiF;AACjF,eAAO,MAAM,YAAY,SAAU,CAAC;AACpC,eAAO,MAAM,SAAS,qBAAqB,CAAC;AAI5C,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,KAAK,CAAC;AAE1D,6FAA6F;AAC7F,eAAO,MAAM,eAAe,qCAAqC,CAAC;AAClE,eAAO,MAAM,SAAS,uDAAuD,CAAC;AAC9E,eAAO,MAAM,SAAS,0CAA0C,CAAC;AAwBjE,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iGAAiG;IACjG,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oEAAoE;IACpE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAUD,uGAAuG;AACvG,wBAAgB,gBAAgB,IAAI,OAAO,CAiB1C;AA8BD,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAe/D;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM7C;AA2BD,uGAAuG;AACvG,wBAAgB,SAAS,CAAC,IAAI,GAAE,MAAoB,GAAG,MAAM,GAAG,SAAS,CAYxE;AAkGD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAe/E;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAa5E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAMtI;AAED;gDACgD;AAChD,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAK3E;AAQD,sGAAsG;AACtG,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAEnE;AAED,yDAAyD;AACzD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzD;AA+BD;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAqChH;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBnG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,iBAAiB,EAAE,MAAM,EAAE,GAAG,OAAO,GAAG,SAAS,EACjD,QAAQ,EAAE,MAAM,EAAE,GACjB;IAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,OAAO,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAevE;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOhH;AAMD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACvH,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACjD,OAAO,CAAC,MAAM,EAAE,CAAC,CAOnB"}

package/dist/widevine.js

@@ -1,21 +1,63 @@
-// Opt-in Widevine CDM fetch + persistent-profile seeding (Windows + Linux).
+// Widevine CDM fetch + persistent-profile seeding (Windows + Linux).
 //
 // clearcote is a 100%-open-source build: it ships the EME/Widevine *plumbing* (enable_widevine=true)
-// but NOT Google's proprietary CDM binary (that blob can't live in a FOSS package). This module lets
-// a user *opt in* to fetching the CDM from Google's component server at runtime — exactly how a real
-// Chrome receives it via the component updater — so requestMediaKeySystemAccess('com.widevine.alpha')
-// resolves (DRM plays, and the EME surface matches a real Chrome instead of a no-Widevine tell).
+// but NOT Google's proprietary CDM binary (that blob can't live in a FOSS package). This module fetches
+// the CDM from Google's component server at runtime — exactly how a real Chrome receives it via the
+// component updater — so requestMediaKeySystemAccess('com.widevine.alpha') resolves (DRM plays, and the
+// EME surface matches a real Chrome instead of a no-Widevine tell).
 //
 //   import { fetchWidevine, launchPersistentContext } from "clearcote";
 //   await fetchWidevine();                                  // download + verify into ~/.clearcote
 //   const ctx = await launchPersistentContext("profile", { widevine: true });  // seeds + enables it
-import { createHash } from "node:crypto";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
-import { rm } from "node:fs/promises";
+//
+// WHEN IT IS ON (since 0.48.0). A licensed launch (a licence key resolved: the launch that selects the
+// PRO build, which claims the Google Chrome brand) on an engine with --widevine-cdm-path (r32+) loads the
+// CDM by default; a free launch keeps it opt-in. `widevine: false` or CLEARCOTE_WIDEVINE=0 turns it off,
+// `widevine: true` or CLEARCOTE_WIDEVINE=1 on for any launch; an explicit option wins over the
+// environment (see widevineMode). The default is FAIL-SOFT and never waits on the network when a CDM is
+// cached: a cached CDM is used at once (a stale one is refreshed in the background). Only the very first
+// launch, with nothing cached, waits for the download, at most CLEARCOTE_WIDEVINE_TIMEOUT_SECONDS (default
+// 15, clamped to 1-600); when that fails the launch goes on without Widevine and says so once per process.
+// The default path prints nothing else. A launch that ASKED for Widevine keeps its old behaviour (a note,
+// unless quiet, and no DRM).
+//
+// The CDM is cached (CLEARCOTE_WIDEVINE_DIR, else ~/.clearcote/WidevineCdm); Google is asked for a newer
+// one at most once a day, and a failed check counts as one (the cached CDM keeps working). Installs take
+// the SDK's install lock in the cache directory and land with download.ts's rename (retried on Windows
+// while a scanner holds the fresh tree), so concurrent first launches never see a half-extracted CDM. The
+// version Google names must look like one before it is used as a directory name. Same rules, names and
+// warning as the Python and .NET SDKs.
+import { createHash, randomBytes } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { performance } from "node:perf_hooks";
 import extract from "extract-zip";
+import { acquireInstallLock, renameDir } from "./download.js";
 import { engineSupportsSwitch } from "./launchopts.js";
+import { warnOnce } from "./warnings.js";
+/** 1/true/yes/on forces Widevine on, 0/false/no/off off; an explicit `widevine` option wins over it. */
+export const WIDEVINE_ENV = "CLEARCOTE_WIDEVINE";
+/** How long a DEFAULT (not requested) launch waits for a first download, in seconds (clamped to 1-600). */
+export const TIMEOUT_ENV = "CLEARCOTE_WIDEVINE_TIMEOUT_SECONDS";
+export const DEFAULT_TIMEOUT_SECONDS = 15;
+export const MIN_TIMEOUT_SECONDS = 1;
+export const MAX_TIMEOUT_SECONDS = 600;
+/** Ask Google for a newer CDM at most once a day. */
+export const CHECK_INTERVAL_MS = 24 * 3600_000;
+/** A failed first download is not retried for 10 minutes in this process. */
+export const RETRY_AFTER_MS = 600_000;
+/** How long a background refresh waits for Google's update check (it may hold a finishing process that long). */
+export const REFRESH_CHECK_TIMEOUT_MS = 10_000;
+/** In the cache root: its mtime is the last update check (a failed one counts). */
+export const STAMP_FILE = ".last-check";
+/** What a CDM version looks like; anything else never becomes a path. */
+export const VERSION_RE = /^[0-9]+(\.[0-9]+){1,3}$/;
+/** How long a requested install waits for another process installing the CDM. */
+export const LOCK_WAIT_MS = 300_000;
+export const WARN_CODE = "widevine-default";
+const TRUTHY = ["1", "true", "yes", "on"];
+const FALSY = ["0", "false", "no", "off"];
 /** Chrome's component-updater app id for the Widevine CDM + Google's Omaha JSON endpoint. */
 export const WIDEVINE_APP_ID = "oimompecagnajdejgnnjijobebaeigek";
 export const OMAHA_URL = "https://update.googleapis.com/service/update2/json";
@@ -59,13 +101,28 @@ export function omahaRequestBody() {
         },
     };
 }
-async function postJson(url, body) {
+/** `AbortSignal.timeout(ms)`, also aborted with `signal` (AbortSignal.any is Node 20.3+). */
+function withTimeout(ms, signal) {
+    const timeout = AbortSignal.timeout(ms);
+    if (!signal)
+        return timeout;
+    const both = new AbortController();
+    const stop = (s) => () => both.abort(s.reason);
+    if (signal.aborted)
+        both.abort(signal.reason);
+    else {
+        signal.addEventListener("abort", stop(signal), { once: true });
+        timeout.addEventListener("abort", stop(timeout), { once: true });
+    }
+    return both.signal;
+}
+async function postJson(url, body, signal) {
     const res = await fetch(url, {
         method: "POST",
         headers: { "Content-Type": "application/json", "User-Agent": UA },
         body: JSON.stringify(body),
         redirect: "follow",
-        signal: AbortSignal.timeout(60_000),
+        signal: withTimeout(60_000, signal),
     });
     if (!res.ok)
         throw new Error(`Widevine update check HTTP ${res.status}`);
@@ -105,54 +162,326 @@ export function crx3ToZip(buf) {
         throw new Error("malformed CRX3 (header overruns buffer)");
     return buf.subarray(12 + headerLen);
 }
+function cdmBinary(verDir) {
+    const { subdir, filename } = cdmPlatform();
+    return path.join(verDir, "_platform_specific", subdir, filename);
+}
+/** A complete CDM directory: its manifest and this OS's CDM binary are both there. */
+function validCdm(verDir) {
+    return !!verDir && existsSync(cdmBinary(verDir)) && existsSync(path.join(verDir, "manifest.json"));
+}
+function versionKey(name) {
+    // "current" (no version in the update response) sorts below any real version
+    return /^\d+(\.\d+)*$/.test(name) ? [1, ...name.split(".").map(Number)] : [0];
+}
+function compareVersions(a, b) {
+    const ka = versionKey(a);
+    const kb = versionKey(b);
+    for (let i = 0; i < Math.max(ka.length, kb.length); i++) {
+        const d = (ka[i] ?? -1) - (kb[i] ?? -1);
+        if (d)
+            return d;
+    }
+    return 0;
+}
+/** The newest complete CDM in the cache (`root`, default the cache root), or undefined. No network. */
+export function cachedCdm(root = cacheRoot()) {
+    let names;
+    try {
+        names = readdirSync(root).filter((n) => !n.startsWith("."));
+    }
+    catch {
+        return undefined;
+    }
+    for (const name of names.sort(compareVersions).reverse()) {
+        const dir = path.join(root, name);
+        if (validCdm(dir))
+            return dir;
+    }
+    return undefined;
+}
+/** Whether Google was asked for a newer CDM less than CHECK_INTERVAL_MS ago. */
+function stampFresh(root) {
+    try {
+        const age = Date.now() - statSync(path.join(root, STAMP_FILE)).mtimeMs;
+        return age > -3600_000 && age < CHECK_INTERVAL_MS; // a stamp from the future (clock moved back) is not fresh
+    }
+    catch {
+        return false;
+    }
+}
+function touchStamp(root) {
+    try {
+        writeFileSync(path.join(root, STAMP_FILE), String(Math.floor(Date.now() / 1000)));
+    }
+    catch {
+        /* the next launch asks again */
+    }
+}
+/** Remove a tree, never throwing (a Windows scanner can hold a file in it for a moment; the next install sweeps it). */
+function removeQuietly(p) {
+    try {
+        rmSync(p, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+    }
+    catch {
+        /* swept by the next install */
+    }
+}
+/** Remove what an interrupted install left in the cache root (only under the install lock). */
+function sweepLeftovers(root) {
+    let names = [];
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return;
+    }
+    for (const n of names)
+        if (n.startsWith(".tmp-") || n.startsWith(".trash-"))
+            removeQuietly(path.join(root, n));
+}
+/**
+ * `root`/<version>, once `version` looks like a CDM version (`4.10.2830.0`). The version comes from Google's
+ * update response: anything else (`../victim`, an absolute path) is refused before it can name, or delete, a
+ * directory. No version at all means `current`.
+ */
+function versionDir(root, version) {
+    if (!version)
+        return path.join(root, "current");
+    if (!VERSION_RE.test(String(version))) {
+        throw new Error(`Widevine update response named an unexpected version ${JSON.stringify(String(version).slice(0, 80))} — refusing to use it`);
+    }
+    return path.join(root, version);
+}
 /**
- * Download + verify the current-OS x64 Widevine CDM into `dest` (default ~/.clearcote/WidevineCdm/
- * <version>). Returns the versioned CDM directory (manifest.json + _platform_specific/<subdir>/
- * <filename>). Re-fetch is skipped if already present.
+ * Download, verify and install one CDM version into `root`/<version>. Holds the SDK's install lock
+ * (`root`/.install-lock, the protocol in download.ts) so concurrent first launches take turns, extracts
+ * into `root`/.tmp-<id> and renames the finished tree into place: a reader never sees a half-extracted CDM.
+ * The renames are download.ts's, which retry while a Windows scanner holds a file in the fresh tree.
+ */
+async function install(root, url, sha256, version, opts) {
+    const verDir = versionDir(root, version);
+    mkdirSync(root, { recursive: true });
+    const lock = await acquireInstallLock(root, { timeoutMs: opts.lockTimeoutMs ?? LOCK_WAIT_MS, quiet: true });
+    try {
+        if (validCdm(verDir))
+            return verDir; // another process installed it while we waited
+        sweepLeftovers(root);
+        log(opts.quiet, `fetching CDM ${version || "(latest)"}`);
+        const res = await fetch(url, { headers: { "User-Agent": UA }, redirect: "follow", signal: withTimeout(120_000, opts.signal) });
+        if (!res.ok)
+            throw new Error(`Widevine CDM download HTTP ${res.status}`);
+        const blob = Buffer.from(await res.arrayBuffer());
+        if (createHash("sha256").update(blob).digest("hex") !== sha256.toLowerCase()) {
+            throw new Error("Widevine CDM sha256 mismatch — refusing to install");
+        }
+        const tmp = path.join(root, `.tmp-${randomBytes(8).toString("hex")}`);
+        try {
+            mkdirSync(tmp);
+            const zipPath = path.join(tmp, ".cdm.zip");
+            writeFileSync(zipPath, crx3ToZip(blob));
+            await extract(zipPath, { dir: tmp });
+            rmSync(zipPath, { force: true });
+            // some CRX layouts nest the platform dir differently; surface a clear error
+            if (!validCdm(tmp))
+                throw new Error(`extracted CDM but ${cdmPlatform().filename} not at ${cdmBinary(verDir)}`);
+            if (existsSync(verDir)) { // an incomplete tree (an older SDK extracted in place): move it aside
+                const trash = path.join(root, `.trash-${randomBytes(8).toString("hex")}`);
+                renameDir(verDir, trash);
+                removeQuietly(trash);
+            }
+            renameDir(tmp, verDir);
+        }
+        finally {
+            removeQuietly(tmp);
+        }
+    }
+    finally {
+        await lock.release();
+    }
+    log(opts.quiet, `installed: ${verDir}`);
+    return verDir;
+}
+/**
+ * Download + verify the current-OS x64 Widevine CDM into `dest` (default CLEARCOTE_WIDEVINE_DIR, else
+ * ~/.clearcote/WidevineCdm) as <version>/. Returns the versioned CDM directory (manifest.json +
+ * _platform_specific/<subdir>/<filename>).
+ *
+ * Always asks Google's update server for the latest version; the download is skipped when that version is
+ * already installed. Installs take the install lock and land with a rename. A version that does not look
+ * like one is refused.
  */
 export async function fetchWidevine(opts = {}) {
-    const [url, sha256, version] = parseUpdate(await postJson(OMAHA_URL, omahaRequestBody()));
+    const [url, sha256, version] = parseUpdate(await postJson(OMAHA_URL, omahaRequestBody(), opts.checkSignal ?? opts.signal));
     const root = opts.dest || cacheRoot();
-    const verDir = path.join(root, version || "current");
-    const { subdir, filename } = cdmPlatform();
-    const dll = path.join(verDir, "_platform_specific", subdir, filename);
-    if (existsSync(dll) && existsSync(path.join(verDir, "manifest.json"))) {
+    const verDir = versionDir(root, version);
+    if (validCdm(verDir)) {
+        touchStamp(root);
         log(opts.quiet, `already present: ${verDir}`);
         return verDir;
     }
-    log(opts.quiet, `fetching CDM ${version || "(latest)"}`);
-    const res = await fetch(url, { headers: { "User-Agent": UA }, redirect: "follow", signal: AbortSignal.timeout(120_000) });
-    if (!res.ok)
-        throw new Error(`Widevine CDM download HTTP ${res.status}`);
-    const blob = Buffer.from(await res.arrayBuffer());
-    // The CDM is a NATIVE DLL loaded into the browser process — never install it unverified. A
-    // missing hash in the update response is a hard failure, not a skip.
+    // The CDM is a NATIVE library loaded into the browser process — never install it unverified. A
+    // missing hash in the update response is a hard failure, not a skip (checked before downloading).
     if (!sha256)
         throw new Error("Widevine update response had no sha256 — refusing to install an unverified CDM");
-    if (createHash("sha256").update(blob).digest("hex") !== sha256.toLowerCase()) {
-        throw new Error("Widevine CDM sha256 mismatch — refusing to install");
+    const dir = await install(root, url, sha256, version, opts);
+    touchStamp(root);
+    return dir;
+}
+/**
+ * The CDM directory a launch should use, network only when needed: the cached CDM when Google was asked
+ * within the last day (no network), otherwise {@link fetchWidevine}. When that fails (offline, a firewall,
+ * Google refusing the request) the CDM already on disk still works and is used, and the failed check is
+ * recorded (the stamp is touched), so no launch asks again for a day. Rejects only when there is no CDM.
+ */
+export async function resolveCdm(opts = {}) {
+    const root = opts.dest || cacheRoot();
+    const cached = cachedCdm(root);
+    if (cached && stampFresh(root))
+        return cached;
+    try {
+        return await fetchWidevine({ ...opts, dest: root });
+    }
+    catch (e) {
+        if (cached) {
+            touchStamp(root);
+            return cached;
+        }
+        throw e;
+    }
+}
+/**
+ * `"explicit"`, `"default"` or `"off"` for a launch. `option` (the `widevine` launch option) wins: true ->
+ * explicit, false -> off. Unset follows CLEARCOTE_WIDEVINE (1/true/yes/on -> explicit, 0/false/no/off ->
+ * off). Otherwise a licensed launch (a licence key resolved, which selects the PRO build) gets the default
+ * and a free launch stays off. Same rules in the Python and .NET SDKs.
+ */
+export function widevineMode(option, licensed, env = process.env) {
+    if (option !== undefined && option !== null)
+        return option ? "explicit" : "off";
+    const value = String(env[WIDEVINE_ENV] ?? "").trim().toLowerCase();
+    if (TRUTHY.includes(value))
+        return "explicit";
+    if (FALSY.includes(value))
+        return "off";
+    return licensed ? "default" : "off";
+}
+/** How long a default launch waits for a first download: CLEARCOTE_WIDEVINE_TIMEOUT_SECONDS clamped to 1-600, else 15
+ * (an unparsable or non-positive value too). */
+export function timeoutSeconds(env = process.env) {
+    const raw = String(env[TIMEOUT_ENV] ?? "").trim();
+    const value = raw === "" ? NaN : Number(raw);
+    if (!(value > 0))
+        return DEFAULT_TIMEOUT_SECONDS; // also NaN
+    return Math.min(Math.max(value, MIN_TIMEOUT_SECONDS), MAX_TIMEOUT_SECONDS);
+}
+// The default path's process state: the first download in flight (one at a time), the background refresh of
+// a stale cached CDM (one at a time), and when a first download last failed (a monotonic clock).
+let defaultJob;
+let refreshJob;
+let defaultFailedAt;
+/** Tests: forget the in-flight fetch, the refresh and the last failure (and stop what is running). */
+export function resetWidevineDefaultState() {
+    defaultJob?.controller.abort();
+    refreshJob?.controller.abort();
+    defaultJob = undefined;
+    refreshJob = undefined;
+    defaultFailedAt = undefined;
+}
+/** Tests: the background refresh in flight, if any. */
+export function widevineRefreshInFlight() {
+    return refreshJob?.promise;
+}
+/** Tests: pretend the last failure was this long ago. */
+export function ageLastWidevineFailure(byMs) {
+    if (defaultFailedAt !== undefined)
+        defaultFailedAt -= byMs;
+}
+function shortReason(e) {
+    const err = e;
+    const text = String(err?.message ?? e ?? "").trim().split("\n")[0].slice(0, 160);
+    const name = err?.name ?? "Error";
+    return text ? `${name}: ${text}` : name;
+}
+function warnDefault(reason, quiet) {
+    warnOnce(WARN_CODE, `Widevine is on by default for licensed launches, but the CDM could not be loaded (${reason}); ` +
+        "launching without it. Set CLEARCOTE_WIDEVINE=0 (or pass widevine: false) to stop trying.", quiet);
+}
+/** Ask Google whether a newer CDM exists, with nobody waiting: one at a time, quiet. The update check is bounded
+ * (REFRESH_CHECK_TIMEOUT_MS), so a blackholed network holds a finishing process that long at most, once a day:
+ * {@link resolveCdm} records a failed check. */
+function refreshInBackground() {
+    if (refreshJob)
+        return;
+    const controller = new AbortController();
+    const job = {
+        controller,
+        promise: resolveCdm({ quiet: true, signal: controller.signal, checkSignal: withTimeout(REFRESH_CHECK_TIMEOUT_MS, controller.signal) })
+            .then(() => undefined, () => undefined)
+            .finally(() => { if (refreshJob === job)
+            refreshJob = undefined; }),
+    };
+    refreshJob = job;
+}
+/**
+ * The CDM for a launch that did not ask for Widevine (the licensed default), or undefined.
+ *
+ * A CDM in the cache is used AT ONCE, with no network on the launch path; when its last update check is over a
+ * day old, a background refresh asks Google for a newer one (used from the next launch on). Only with nothing
+ * cached does the launch wait for a download, at most `timeoutMs` (default {@link timeoutSeconds}). FAIL-SOFT:
+ * never rejects. When there is no CDM to use (the download failed or did not finish in time) it warns once per
+ * process (unless quiet) and answers undefined, so the launch goes on without DRM; a download still running at
+ * the deadline is cancelled (it cannot keep the process alive), and a failed one is not retried for
+ * RETRY_AFTER_MS in this process. The fetches here are quiet: the default path prints nothing else.
+ */
+export async function defaultCdm(opts = {}) {
+    const root = cacheRoot();
+    const cached = cachedCdm(root);
+    if (cached) {
+        if (!stampFresh(root))
+            refreshInBackground();
+        return cached;
     }
-    mkdirSync(verDir, { recursive: true });
-    const tmp = mkdtempSync(path.join(os.tmpdir(), "cc-wv-"));
-    const zipPath = path.join(tmp, "cdm.zip");
+    if (defaultFailedAt !== undefined && performance.now() - defaultFailedAt < RETRY_AFTER_MS)
+        return undefined;
+    const waitMs = opts.timeoutMs ?? timeoutSeconds() * 1000;
+    if (!defaultJob || defaultJob.done) {
+        const controller = new AbortController();
+        const started = { controller, done: false, promise: Promise.resolve({ err: undefined }) };
+        started.promise = resolveCdm({ quiet: true, signal: controller.signal, lockTimeoutMs: waitMs })
+            .then((ok) => ({ ok }), (err) => ({ err }))
+            .finally(() => { started.done = true; });
+        defaultJob = started;
+    }
+    const job = defaultJob;
+    let timer;
+    const deadline = new Promise((resolve) => { timer = setTimeout(() => resolve("timeout"), waitMs); });
     try {
-        writeFileSync(zipPath, crx3ToZip(blob));
-        await extract(zipPath, { dir: verDir });
+        const r = await Promise.race([job.promise, deadline]);
+        if (r === "timeout") {
+            defaultFailedAt = performance.now();
+            job.controller.abort(); // never keep the process alive for a launch that went on without it
+            warnDefault(`not ready within ${waitMs / 1000} s`, opts.quiet);
+            return undefined;
+        }
+        if ("err" in r) {
+            defaultFailedAt = performance.now();
+            warnDefault(shortReason(r.err), opts.quiet);
+            return undefined;
+        }
+        return r.ok;
     }
     finally {
-        await rm(tmp, { recursive: true, force: true });
+        clearTimeout(timer);
     }
-    if (!existsSync(dll))
-        throw new Error(`extracted CDM but ${filename} not at ${dll}`);
-    log(opts.quiet, `installed: ${verDir}`);
-    return verDir;
 }
 /**
  * Make a persistent profile load the fetched CDM: copy it under <userDataDir>/WidevineCdm/<version>/
- * and write the component hint file the engine reads. Fetches the CDM first if needed.
+ * and write the component hint file the engine reads. Fetches the CDM first if needed
+ * ({@link resolveCdm}: the cached one when it is current).
  */
 export async function seedWidevine(userDataDir, opts = {}) {
-    const src = await fetchWidevine(opts);
+    const src = await resolveCdm(opts);
     const version = path.basename(src);
     const wvRoot = path.join(userDataDir, "WidevineCdm");
     const target = path.join(wvRoot, version);
@@ -209,10 +538,32 @@ export async function widevineCdmArgs(exe, opts = {}) {
     try {
         if (!engineSupportsSwitch(exe, "widevine-cdm-path"))
             return [];
-        return [`--widevine-cdm-path=${await fetchWidevine({ quiet: opts.quiet })}`];
+        return [`--widevine-cdm-path=${await resolveCdm({ quiet: opts.quiet })}`];
     }
     catch {
         return [];
     }
 }
+function callerSetCdmPath(userArgs) {
+    return (userArgs ?? []).some((a) => String(a).split("=", 1)[0] === "--widevine-cdm-path");
+}
+/**
+ * The Widevine switch for one launch, by {@link widevineMode}. explicit: {@link widevineCdmArgs} (the
+ * behaviour `widevine: true` always had). default: the same switch, only on an engine that implements it
+ * (r32+; an older engine keeps the old default, off), with the CDM from {@link defaultCdm} (bounded,
+ * fail-soft, warns once). off: nothing. A `--widevine-cdm-path` the caller put in `args` is theirs:
+ * nothing is added then. Works for every launch path: such an engine loads the CDM without a profile,
+ * incognito included.
+ */
+export async function widevineLaunchArgs(exe, option, licensed, userArgs, opts = {}) {
+    const mode = widevineMode(option, licensed);
+    if (mode === "off" || callerSetCdmPath(userArgs))
+        return [];
+    if (mode === "explicit")
+        return widevineCdmArgs(exe, { quiet: opts.quiet });
+    if (!engineSupportsSwitch(exe, "widevine-cdm-path"))
+        return [];
+    const cdm = await defaultCdm(opts);
+    return cdm ? [`--widevine-cdm-path=${cdm}`] : [];
+}
 //# sourceMappingURL=widevine.js.map