@socketsecurity/lib 5.25.1 → 5.26.1

package/dist/releases/github-downloads.js

@@ -0,0 +1,155 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var github_downloads_exports = {};
+__export(github_downloads_exports, {
+  downloadGitHubRelease: () => downloadGitHubRelease,
+  downloadReleaseAsset: () => downloadReleaseAsset
+});
+module.exports = __toCommonJS(github_downloads_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_fs = require("../fs");
+var import_http_request = require("../http-request");
+var import_logger = require("../logger");
+var import_primordials = require("../primordials");
+var import_spawn = require("../spawn");
+var import_github_api = require("./github-api");
+const logger = (0, import_logger.getDefaultLogger)();
+let _fs;
+let _path;
+// @__NO_SIDE_EFFECTS__
+function getFs() {
+  if (_fs === void 0) {
+    _fs = require("node:fs");
+  }
+  return _fs;
+}
+// @__NO_SIDE_EFFECTS__
+function getPath() {
+  if (_path === void 0) {
+    _path = require("node:path");
+  }
+  return _path;
+}
+async function downloadGitHubRelease(config) {
+  const {
+    assetName,
+    binaryName,
+    cwd = import_node_process.default.cwd(),
+    downloadDir = "build/downloaded",
+    owner,
+    platformArch,
+    quiet = false,
+    removeMacOSQuarantine = true,
+    repo,
+    tag: explicitTag,
+    toolName,
+    toolPrefix
+  } = config;
+  let tag;
+  if (explicitTag) {
+    tag = explicitTag;
+  } else if (toolPrefix) {
+    const latestTag = await (0, import_github_api.getLatestRelease)(toolPrefix, { owner, repo });
+    if (!latestTag) {
+      throw new import_primordials.ErrorCtor(`No ${toolPrefix} release found in ${owner}/${repo}`);
+    }
+    tag = latestTag;
+  } else {
+    throw new import_primordials.ErrorCtor("Either toolPrefix or tag must be provided");
+  }
+  const path = /* @__PURE__ */ getPath();
+  const resolvedDownloadDir = path.isAbsolute(downloadDir) ? downloadDir : path.join(cwd, downloadDir);
+  const binaryDir = resolvedDownloadDir;
+  const binaryPath = path.join(binaryDir, binaryName);
+  const versionPath = path.join(binaryDir, ".version");
+  const fs = /* @__PURE__ */ getFs();
+  if (fs.existsSync(versionPath) && fs.existsSync(binaryPath)) {
+    const cachedVersion = (await fs.promises.readFile(versionPath, "utf8")).trim();
+    if (cachedVersion === tag && fs.existsSync(binaryPath)) {
+      if (!quiet) {
+        logger.info(`Using cached ${toolName} (${platformArch}): ${binaryPath}`);
+      }
+      return binaryPath;
+    }
+  }
+  if (!quiet) {
+    logger.info(`Downloading ${toolName} for ${platformArch}...`);
+  }
+  await downloadReleaseAsset(
+    tag,
+    assetName,
+    binaryPath,
+    { owner, repo },
+    { quiet }
+  );
+  const isWindows = (0, import_primordials.StringPrototypeEndsWith)(binaryName, ".exe");
+  if (!isWindows) {
+    fs.chmodSync(binaryPath, 493);
+    if (removeMacOSQuarantine && import_node_process.default.platform === "darwin" && (0, import_primordials.StringPrototypeStartsWith)(platformArch, "darwin")) {
+      try {
+        await (0, import_spawn.spawn)("xattr", ["-d", "com.apple.quarantine", binaryPath], {
+          stdio: "ignore"
+        });
+      } catch {
+      }
+    }
+  }
+  await fs.promises.writeFile(versionPath, tag, "utf8");
+  if (!quiet) {
+    logger.info(`Downloaded ${toolName} to ${binaryPath}`);
+  }
+  return binaryPath;
+}
+async function downloadReleaseAsset(tag, assetPattern, outputPath, repoConfig, options = {}) {
+  const { owner, repo } = repoConfig;
+  const { quiet = false } = options;
+  const downloadUrl = await (0, import_github_api.getReleaseAssetUrl)(tag, assetPattern, {
+    owner,
+    repo
+  });
+  if (!downloadUrl) {
+    const patternDesc = typeof assetPattern === "string" ? assetPattern : "matching pattern";
+    throw new import_primordials.ErrorCtor(`Asset ${patternDesc} not found in release ${tag}`);
+  }
+  const path = /* @__PURE__ */ getPath();
+  await (0, import_fs.safeMkdir)(path.dirname(outputPath));
+  await (0, import_http_request.httpDownload)(downloadUrl, outputPath, {
+    logger: quiet ? void 0 : logger,
+    progressInterval: 10,
+    retries: 2,
+    retryDelay: 5e3
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  downloadGitHubRelease,
+  downloadReleaseAsset
+});

package/dist/releases/github-types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Public types for GitHub release download utilities.
+ */
+/**
+ * Pattern for matching release assets.
+ * Can be either:
+ * - A string with glob pattern syntax
+ * - A prefix/suffix pair for explicit matching (backward compatible)
+ * - A RegExp for complex patterns
+ *
+ * String patterns support full glob syntax via picomatch.
+ * Examples:
+ * - Simple wildcard: yoga-sync-*.mjs matches yoga-sync-abc123.mjs
+ * - Complex: models-*.tar.gz matches models-2024-01-15.tar.gz
+ * - Prefix wildcard: *-models.tar.gz matches foo-models.tar.gz
+ * - Suffix wildcard: yoga-* matches yoga-layout
+ * - Brace expansion: {yoga,models}-*.{mjs,js} matches yoga-abc.mjs or models-xyz.js
+ *
+ * For backward compatibility, prefix/suffix objects are still supported but glob patterns are recommended.
+ */
+export type AssetPattern = string | {
+    prefix: string;
+    suffix: string;
+} | RegExp;
+/**
+ * Configuration for downloading a GitHub release.
+ */
+export interface DownloadGitHubReleaseConfig {
+    /** Asset name on GitHub. */
+    assetName: string;
+    /** Binary filename (e.g., 'node', 'binject'). */
+    binaryName: string;
+    /** Working directory (defaults to process.cwd()). */
+    cwd?: string;
+    /** Download destination directory. @default 'build/downloaded' */
+    downloadDir?: string;
+    /** GitHub repository owner/organization. */
+    owner: string;
+    /** Platform-arch identifier (e.g., 'linux-x64-musl'). */
+    platformArch: string;
+    /** Suppress log messages. @default false */
+    quiet?: boolean;
+    /** Remove macOS quarantine attribute after download. @default true */
+    removeMacOSQuarantine?: boolean;
+    /** GitHub repository name. */
+    repo: string;
+    /** Specific release tag to download. */
+    tag?: string;
+    /** Tool name for directory structure. */
+    toolName: string;
+    /** Tool prefix for finding latest release. */
+    toolPrefix?: string;
+}
+/**
+ * Configuration for repository access.
+ */
+export interface RepoConfig {
+    /**
+     * GitHub repository owner/organization.
+     */
+    owner: string;
+    /**
+     * GitHub repository name.
+     */
+    repo: string;
+}

package/dist/{effects/types.js → releases/github-types.js}

@@ -14,5 +14,5 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var types_exports = {};
-module.exports = __toCommonJS(types_exports);
+var github_types_exports = {};
+module.exports = __toCommonJS(github_types_exports);

package/dist/releases/socket-btm.d.ts

@@ -2,7 +2,7 @@
  * @fileoverview Socket-btm release download utilities.
  */
 import { type Arch, type Libc, type Platform } from '../constants/platform';
-import { type AssetPattern } from './github';
+import type { AssetPattern } from './github-types';
 export type { Arch, Libc, Platform };
 /**
  * Socket-btm GitHub repository configuration.

package/dist/releases/socket-btm.js

@@ -29,7 +29,9 @@ __export(socket_btm_exports, {
 });
 module.exports = __toCommonJS(socket_btm_exports);
 var import_platform = require("../constants/platform");
-var import_github = require("./github");
+var import_github_api = require("./github-api");
+var import_github_downloads = require("./github-downloads");
+var import_primordials = require("../primordials");
 const SOCKET_BTM_REPO = {
   owner: "SocketDev",
   repo: "socket-btm"
@@ -93,27 +95,25 @@ async function downloadSocketBtmRelease(tool, options) {
       resolvedAsset = asset;
     } else {
       if (tag) {
-        throw new Error(
+        throw new import_primordials.ErrorCtor(
           "Cannot use asset pattern with explicit tag. Either provide exact asset name or omit tag."
         );
       }
-      resolvedTag = await (0, import_github.getLatestRelease)(toolPrefix, SOCKET_BTM_REPO, {
-        assetPattern: asset,
-        quiet
+      resolvedTag = await (0, import_github_api.getLatestRelease)(toolPrefix, SOCKET_BTM_REPO, {
+        assetPattern: asset
       }) ?? void 0;
       if (!resolvedTag) {
-        throw new Error(`No ${tool} release with matching asset pattern found`);
+        throw new import_primordials.ErrorCtor(
+          `No ${tool} release with matching asset pattern found`
+        );
       }
-      const assetUrl = await (0, import_github.getReleaseAssetUrl)(
+      const assetUrl = await (0, import_github_api.getReleaseAssetUrl)(
         resolvedTag,
         asset,
-        SOCKET_BTM_REPO,
-        {
-          quiet
-        }
+        SOCKET_BTM_REPO
       );
       if (!assetUrl) {
-        throw new Error(`No matching asset found in release ${resolvedTag}`);
+        throw new import_primordials.ErrorCtor(`No matching asset found in release ${resolvedTag}`);
       }
       resolvedAsset = assetUrl.split("/").pop() || asset.toString();
     }
@@ -169,12 +169,12 @@ async function downloadSocketBtmRelease(tool, options) {
       removeMacOSQuarantine
     };
   }
-  return await (0, import_github.downloadGitHubRelease)(downloadConfig);
+  return await (0, import_github_downloads.downloadGitHubRelease)(downloadConfig);
 }
 function getBinaryAssetName(binaryBaseName, platform, arch, libc) {
   const mappedArch = ARCH_MAP[arch];
   if (!mappedArch) {
-    throw new Error(`Unsupported architecture: ${arch}`);
+    throw new import_primordials.ErrorCtor(`Unsupported architecture: ${arch}`);
   }
   const muslSuffix = platform === "linux" && libc === "musl" ? "-musl" : "";
   const ext = platform === "win32" ? ".exe" : "";
@@ -187,7 +187,7 @@ function getBinaryAssetName(binaryBaseName, platform, arch, libc) {
   if (platform === "win32") {
     return `${binaryBaseName}-win32-${mappedArch}${ext}`;
   }
-  throw new Error(`Unsupported platform: ${platform}`);
+  throw new import_primordials.ErrorCtor(`Unsupported platform: ${platform}`);
 }
 function getBinaryName(binaryBaseName, platform) {
   return platform === "win32" ? `${binaryBaseName}.exe` : binaryBaseName;
@@ -195,11 +195,11 @@ function getBinaryName(binaryBaseName, platform) {
 function getPlatformArch(platform, arch, libc) {
   const mappedPlatform = PLATFORM_MAP[platform];
   if (!mappedPlatform) {
-    throw new Error(`Unsupported platform: ${platform}`);
+    throw new import_primordials.ErrorCtor(`Unsupported platform: ${platform}`);
   }
   const mappedArch = ARCH_MAP[arch];
   if (!mappedArch) {
-    throw new Error(`Unsupported architecture: ${arch}`);
+    throw new import_primordials.ErrorCtor(`Unsupported architecture: ${arch}`);
   }
   const muslSuffix = platform === "linux" && libc === "musl" ? "-musl" : "";
   return `${mappedPlatform}-${mappedArch}${muslSuffix}`;

package/dist/schema/parse.js

@@ -24,13 +24,14 @@ __export(parse_exports, {
 });
 module.exports = __toCommonJS(parse_exports);
 var import_validate = require("./validate");
+var import_primordials = require("../primordials");
 function parseSchema(schema, data) {
   const result = (0, import_validate.validateSchema)(schema, data);
   if (result.ok) {
     return result.value;
   }
   const summary = result.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join(", ");
-  throw new Error(`Validation failed: ${summary}`);
+  throw new import_primordials.ErrorCtor(`Validation failed: ${summary}`);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/schema/validate.js

@@ -23,11 +23,12 @@ __export(validate_exports, {
   validateSchema: () => validateSchema
 });
 module.exports = __toCommonJS(validate_exports);
+var import_primordials = require("../primordials");
 function isTypeBoxSchema(schema) {
   if (schema === null || typeof schema !== "object") {
     return false;
   }
-  for (const sym of Object.getOwnPropertySymbols(schema)) {
+  for (const sym of (0, import_primordials.ObjectGetOwnPropertySymbols)(schema)) {
     if (sym.description === "TypeBox.Kind") {
       return typeof schema[sym] === "string";
     }
@@ -41,7 +42,7 @@ function normalizeTypeBoxErrors(errors) {
     out.push({
       path: segs.map((s) => {
         const n = Number(s);
-        return Number.isInteger(n) && String(n) === s ? n : s;
+        return (0, import_primordials.NumberIsInteger)(n) && String(n) === s ? n : s;
       }),
       message: err.message
     });
@@ -53,13 +54,13 @@ function normalizeZodError(err) {
     return [{ path: [], message: String(err) }];
   }
   const issues = err.issues;
-  if (!Array.isArray(issues)) {
+  if (!(0, import_primordials.ArrayIsArray)(issues)) {
     return [{ path: [], message: "Unknown validation error" }];
   }
   return issues.map((issue) => {
     const i = issue;
     return {
-      path: Array.isArray(i.path) ? i.path : [],
+      path: (0, import_primordials.ArrayIsArray)(i.path) ? i.path : [],
       message: typeof i.message === "string" ? i.message : "Invalid value"
     };
   });
@@ -88,7 +89,7 @@ function validateSchema(schema, data) {
       errors: normalizeZodError(result.error)
     };
   }
-  throw new TypeError(
+  throw new import_primordials.TypeErrorCtor(
     "validateSchema: unsupported schema kind. Expected a Zod schema or an object with a safeParse method."
   );
 }

package/dist/shadow.js

@@ -44,7 +44,8 @@ function shouldSkipShadow(binPath, options) {
     return true;
   }
   const userAgent = import_node_process.default.env["npm_config_user_agent"];
-  if (userAgent?.includes("exec") || userAgent?.includes("npx") || userAgent?.includes("dlx")) {
+  if (userAgent?.includes("exec") || userAgent?.includes("npx") || // # socket-hook: allow npx
+  userAgent?.includes("dlx")) {
     return true;
   }
   const normalizedCwd = (0, import_normalize.normalizePath)(cwd);

package/dist/signal-exit.js

@@ -133,7 +133,7 @@ function processReallyExit(code) {
     globalProcess,
     [exitCode]
   );
-  throw new Error("processReallyExit should never return");
+  throw new import_primordials.ErrorCtor("processReallyExit should never return");
 }
 // @__NO_SIDE_EFFECTS__
 function load() {
@@ -168,7 +168,7 @@ function onExit(cb, options) {
     };
   }
   if (typeof cb !== "function") {
-    throw new TypeError("a callback must be provided for exit handler");
+    throw new import_primordials.TypeErrorCtor("a callback must be provided for exit handler");
   }
   if (loaded === false) {
     /* @__PURE__ */ load();

package/dist/spawn.js

@@ -46,10 +46,11 @@ var import_objects = require("./objects");
 var import_normalize = require("./paths/normalize");
 var import_spinner = require("./spinner");
 var import_strings = require("./strings");
+var import_primordials = require("./primordials");
 const abortSignal = (0, import_process.getAbortSignal)();
 const spinner = (0, import_spinner.getDefaultSpinner)();
-const stackCache = /* @__PURE__ */ new WeakMap();
-const spawnBinPathCache = /* @__PURE__ */ new Map();
+const stackCache = new import_primordials.WeakMapCtor();
+const spawnBinPathCache = new import_primordials.MapCtor();
 const windowsScriptExtRegExp = /\.(?:cmd|bat|ps1)$/i;
 let _npmCliPromiseSpawn;
 let _path;
@@ -133,7 +134,7 @@ ${firstLine.slice(0, 197)}...`;
   }
   const isSynthetic = err.message === "command failed";
   if (isSynthetic) {
-    Object.defineProperty(err, "message", {
+    (0, import_primordials.ObjectDefineProperty)(err, "message", {
       __proto__: null,
       value: enhancedMessage,
       writable: true,
@@ -142,14 +143,14 @@ ${firstLine.slice(0, 197)}...`;
     });
     return err;
   }
-  const enhancedError = new Error(enhancedMessage, {
+  const enhancedError = new import_primordials.ErrorCtor(enhancedMessage, {
     cause: err
   });
-  const descriptors = Object.getOwnPropertyDescriptors(err);
-  Reflect.deleteProperty(descriptors, "message");
-  Reflect.deleteProperty(descriptors, "stack");
-  Object.defineProperties(enhancedError, descriptors);
-  Object.defineProperty(enhancedError, "stack", {
+  const descriptors = (0, import_primordials.ObjectGetOwnPropertyDescriptors)(err);
+  (0, import_primordials.ReflectDeleteProperty)(descriptors, "message");
+  (0, import_primordials.ReflectDeleteProperty)(descriptors, "stack");
+  (0, import_primordials.ObjectDefineProperties)(enhancedError, descriptors);
+  (0, import_primordials.ObjectDefineProperty)(enhancedError, "stack", {
     __proto__: null,
     configurable: true,
     enumerable: false,
@@ -214,7 +215,7 @@ function spawn(cmd, args, options, extra) {
     }
   }
   const WIN32 = import_node_process.default.platform === "win32";
-  if (WIN32 && shell && windowsScriptExtRegExp.test(actualCmd)) {
+  if (WIN32 && shell && (0, import_primordials.RegExpPrototypeTest)(windowsScriptExtRegExp, actualCmd)) {
     if (!(0, import_normalize.isPath)(actualCmd)) {
       actualCmd = (/* @__PURE__ */ getPath()).basename(actualCmd, (/* @__PURE__ */ getPath()).extname(actualCmd));
     }
@@ -253,35 +254,44 @@ function spawn(cmd, args, options, extra) {
   const oldSpawnPromise = spawnPromise;
   let newSpawnPromise;
   if (shouldStripAnsi && stdioString) {
-    newSpawnPromise = spawnPromise.then((result) => {
-      const strippedResult = /* @__PURE__ */ stripAnsiFromSpawnResult(result);
-      if ("code" in strippedResult) {
-        ;
-        strippedResult.exitCode = strippedResult.code;
+    newSpawnPromise = (async () => {
+      try {
+        const result = await spawnPromise;
+        const strippedResult = /* @__PURE__ */ stripAnsiFromSpawnResult(result);
+        if ("code" in strippedResult) {
+          ;
+          strippedResult.exitCode = strippedResult.code;
+        }
+        return strippedResult;
+      } catch (error) {
+        const strippedError = /* @__PURE__ */ stripAnsiFromSpawnResult(error);
+        throw /* @__PURE__ */ enhanceSpawnError(strippedError);
       }
-      return strippedResult;
-    }).catch((error) => {
-      const strippedError = /* @__PURE__ */ stripAnsiFromSpawnResult(error);
-      const enhancedError = /* @__PURE__ */ enhanceSpawnError(strippedError);
-      throw enhancedError;
-    });
+    })();
   } else {
-    newSpawnPromise = spawnPromise.then((result) => {
-      if (result !== null && typeof result === "object" && "code" in result) {
-        const res = result;
-        res.exitCode = res.code;
-        return res;
+    newSpawnPromise = (async () => {
+      try {
+        const result = await spawnPromise;
+        if (result !== null && typeof result === "object" && "code" in result) {
+          const res = result;
+          res.exitCode = res.code;
+          return res;
+        }
+        return result;
+      } catch (error) {
+        throw /* @__PURE__ */ enhanceSpawnError(error);
       }
-      return result;
-    }).catch((error) => {
-      const enhancedError = /* @__PURE__ */ enhanceSpawnError(error);
-      throw enhancedError;
-    });
+    })();
   }
   if (shouldRestartSpinner) {
-    newSpawnPromise = newSpawnPromise.finally(() => {
-      spinnerInstance.start();
-    });
+    const prevPromise = newSpawnPromise;
+    newSpawnPromise = (async () => {
+      try {
+        return await prevPromise;
+      } finally {
+        spinnerInstance.start();
+      }
+    })();
   }
   ;
   newSpawnPromise.process = oldSpawnPromise.process;
@@ -301,7 +311,7 @@ function spawnSync(cmd, args, options) {
   }
   const shell = (0, import_objects.getOwn)(options, "shell");
   const WIN32 = import_node_process.default.platform === "win32";
-  if (WIN32 && shell && windowsScriptExtRegExp.test(actualCmd)) {
+  if (WIN32 && shell && (0, import_primordials.RegExpPrototypeTest)(windowsScriptExtRegExp, actualCmd)) {
     if (!(0, import_normalize.isPath)(actualCmd)) {
       actualCmd = (/* @__PURE__ */ getPath()).basename(actualCmd, (/* @__PURE__ */ getPath()).extname(actualCmd));
     }

package/dist/spinner.d.ts

@@ -4,7 +4,7 @@
  */
 import type { Writable } from 'node:stream';
 import type { ColorInherit, ColorRgb, ColorValue } from './colors';
-import type { ShimmerColorGradient, ShimmerConfig, ShimmerDirection, ShimmerState } from './effects/text-shimmer';
+import type { Palette, ShimmerConfig, ShimmerDirection } from './effects/shimmer';
 /**
  * Symbol types for status messages.
  * Maps to log symbols: fail (✗), info (ℹ), skip (↻), success (✓), warn (⚠).
@@ -23,12 +23,19 @@ export type ProgressInfo = {
     unit?: string | undefined;
 };
 /**
- * Internal shimmer state with color configuration.
- * Extends `ShimmerState` with additional color property that can be inherited from spinner.
+ * Internal shimmer runtime state. Holds the user-facing config plus a
+ * monotonic frame counter; the spinner advances `frame` on each animation
+ * tick and feeds the current frame to the shimmer engine.
  */
-export type ShimmerInfo = ShimmerState & {
-    /** Color for shimmer effect - can inherit from spinner, use explicit color, or gradient */
-    color: ColorInherit | ColorValue | ShimmerColorGradient;
+export type ShimmerInfo = {
+    /** User-facing color reference (inherit, explicit value, or palette). */
+    color: ColorInherit | ColorValue | Palette;
+    /** Current direction (driven by config, snapshotted here for getters). */
+    direction: ShimmerDirection;
+    /** Steps per frame. */
+    speed: number;
+    /** Monotonic frame counter — advanced on each animation tick. */
+    frame: number;
 };
 /**
  * Spinner instance for displaying animated loading indicators.