@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

package/README.md

@@ -15,29 +15,31 @@ TypeScript type definitions for [Foundry Virtual Tabletop](https://foundryvtt.co
 
 We aim to support the latest release of each Foundry VTT version (0.7, 0.8, 9, etc.), starting with 0.7.
 
-At the moment, versions 0.7, 0.8, and 9 are fully supported with partial support for versions 10 and 11. Work on support for version 12 is currently underway. See the [open foundry V12 issues](https://github.com/League-of-Foundry-Developers/foundry-vtt-types/issues?q=is%3Aopen+is%3Aissue+label%3A%22foundry+V12%22).
+At the moment, versions 0.7, 0.8, and 9 are fully supported with partial support for versions 10, 11, and 12. Work on support for version 13 is currently underway.
 
-## V12 Installation
+## AI
 
-Currently v12 is still in beta. There are known bugs, issues in the ergonomics, and major unfinished work in the current implementation. To get a direct line of communication about the current status of development as well as to help us understand what areas need to be prioritized first, join the [League of Extraordinary FoundryVTT Developers Discord](https://discord.gg/73HTMuK7dT) or file an issue.
+AI cannot be provided the source of Foundry VTT Types. This is because Foundry VTT Types contains documentation from Foundry and AI is _**not**_ allowed to be used on the source of Foundry due to its [End User License Agreement (EULA)](https://foundryvtt.com/article/license/). Staff members have confirmed there is no exception for AI.
 
-The recommended way to install for v12 is this command:
+## V13 Installation
+
+Currently v13 is still in beta. There are known bugs, issues in the ergonomics, and unfinished work in the current implementation. To get a direct line of communication about the current status of development as well as to help us understand what areas need to be prioritized first, join the [League of Extraordinary FoundryVTT Developers Discord](https://discord.gg/73HTMuK7dT) or file an issue.
+
+The recommended way to install for v13 is this command:
 
 ```sh
 npm add -D fvtt-types@github:League-of-Foundry-Developers/foundry-vtt-types#main
 ```
 
-Alternatively, if you're using yarn you'll need to use the command `yarn add --dev fvtt-types@github:League-of-Foundry-Developers/foundry-vtt-types#main`.
+The command for other package managers is similar, for example with yarn you'll need to use the command `yarn add --dev fvtt-types@github:League-of-Foundry-Developers/foundry-vtt-types#main`.
 
-This will add the current commit on `main` as a dependency. Both npm and yarn's lockfile will store the commit you initially installed this command and so updates to your dependency will not happen automatically or even after a fresh install. To update you will need to be rerun the prior command periodically to update as improvements are added frequently.
-
-If you've been using the types for a few months now, the best branch would be `maintenance` instead. `main` will have a number of backwards incompatible breaking changes going forward.
+This will add the current commit on `main` as a dependency. Every popular package manager has a lockfile which will store the commit you initially installed this command and so updates to your dependency will not happen automatically or even after a fresh install. To update you will need to be rerun the prior command periodically to update as improvements are added frequently.
 
 ## Installation
 
 You can install historical versions of foundry-vtt-types from the [npm registry](https://npmjs.org/).
 
-In order to install the latest stable version (v9), run
+In order to install the latest stable version, run
 
 ```sh
 npm add --save-dev fvtt-types@npm:@league-of-foundry-developers/foundry-vtt-types
@@ -86,16 +88,19 @@ Add foundry-vtt-types to your types section in your `tsconfig.json`:
 {
   "compilerOptions": {
     "types": ["fvtt-types"],
-    "module": "esnext",
+    "target": "esnext",
     "moduleResolution": "bundler",
     "strict": true
   }
 }
 ```
 
-This will make the type definitions available globally in your project.
+Compiler Option Notes:
 
-We recommend using `"strict": true` because it enables a whole host of useful options. However if you want to check that your config supports foundry-vtt-types, the most important settings under `strict` would be `strictNullChecks` and `strictFunctionTypes` are the most important.
+- `types` is set to make fvtt-types globally available in your project. Without it global variables like `game` and `CONFIG` won't appear.
+- `"target": "esnext"` is recommended because Foundry lives on the bleeding edge of JavaScript features. If you want to downlevel your code setting `"lib": ["esnext", "dom"]` and `target` is reasonable but TypeScript's downlevelling is not the most advanced and so it's probably a good idea to leave this to other tools. It's a bad idea to lower the `lib` version as Foundry will frequently use new JavaScript features. Nevertheless the minimum out of the box usable lib is `es2022` as before that types like `WeakRef` won't exist.
+- Using `"strict": true` is _highly_ recommended because it enables a whole host of useful options. However if you want to check that your config supports foundry-vtt-types, the most important settings under `strict` would be `strictNullChecks` and `strictFunctionTypes`.
+- Changing the `moduleResolution` is generally not recommended. Only new `moduleResolution` strategies have support for certain imports like `"fvtt-types/utils"`. For example the Node `moduleResolutions` above `node16` may work but have additional Node-only constraints not relevant to the browser.
 
 You can find some information about how to actually work with the type definitions in the
 [Wiki](https://github.com/League-of-Foundry-Developers/foundry-vtt-types/wiki). A good starting point is
@@ -121,34 +126,6 @@ Please read [CONTRIBUTING.md](CONTRIBUTING.md) for more details on how to contri
 If you have any specific questions, feel free to contact us in the
 [League of Extraordinary Foundry Developers Discord](https://discord.gg/52DNPzqm2Z).
 
-## Type-Checking, Linting, Testing
-
-When contributing, make sure that the type checks pass, the linter is green and the tests are green. We _do_ have
-checks in the CI but running this locally also helps you while developing and saves you time as you don't have to wait
-for the CI.
-
-You can run type checking and linting with the following command:
-
-```shell
-npm run lint
-```
-
-You can run the tests with
-
-```shell
-npm run test
-```
-
-## Creating a release
-
-To create a release, you have to create a new release commit, tag it and create a GitHub release from that. The CI will
-handle the rest.
-
-```shell
-npm version <release-type>
-git push --follow-tags
-```
-
 ## License
 
 This project is licensed under the MIT license. You can find a copy at [LICENSE](LICENSE).

package/package.json

@@ -1,10 +1,10 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "13.340.0",
+  "version": "13.345.1-beta.20250704.94554",
   "description": "TypeScript type definitions for Foundry VTT",
   "type": "module",
-  "types": "./index.d.mts",
+  "types": "./src/index.d.mts",
   "exports": {
     ".": {
       "types": "./src/index.d.mts"
@@ -25,17 +25,34 @@
       "types": "./src/foundry/public/scripts/workers/image-compressor.d.mts"
     }
   },
+  "imports": {
+    "#client/*": {
+      "import": "./src/foundry/client/*"
+    },
+    "#common/*": {
+      "import": "./src/foundry/common/*"
+    },
+    "#utils": {
+      "import": "./src/utils/index.d.mts"
+    },
+    "#configuration": {
+      "import": "./src/configuration/index.d.mts"
+    }
+  },
   "scripts": {
-    "lint": "npm-run-all -c typecheck lint/eslint lint/prettier",
-    "lint/eslint": "eslint --cache .",
-    "lint/prettier": "prettier -c .",
-    "lint:fix": "npm-run-all -c typecheck lint:fix/eslint lint:fix/prettier",
-    "lint:fix/eslint": "eslint --cache --fix .",
-    "lint:fix/prettier": "prettier -l -w .",
+    "format": "prettier -l -w .",
+    "lint": "npm-run-all -c typecheck eslint prettier",
+    "eslint": "eslint --cache .",
+    "prettier": "prettier -c .",
+    "lint:fix": "npm-run-all -c typecheck eslint:fix prettier:fix",
+    "eslint:fix": "eslint --cache --fix .",
+    "prettier:fix": "prettier -l -w .",
     "eslint:report": "eslint --cache --output-file eslint_report.json --format json .",
     "test": "vitest --typecheck",
-    "typecheck": "tsc -b tsconfig.main.json",
-    "prepare": "is-ci || husky"
+    "typecheck": "tsc",
+    "prepare": "is-ci || husky",
+    "betterer": "betterer",
+    "betterer:update": "betterer --update"
   },
   "repository": {
     "type": "git",
@@ -80,87 +97,86 @@
   ],
   "dependencies": {
     "@codemirror/lang-html": "^6.4.9",
-    "@codemirror/lang-javascript": "^6.2.2",
+    "@codemirror/lang-javascript": "^6.2.3",
     "@codemirror/lang-json": "^6.0.1",
-    "@codemirror/lang-markdown": "^6.3.1",
-    "@pixi/basis": "^7.4.2",
-    "@pixi/graphics-smooth": "^1.1.0",
-    "@pixi/particle-emitter": "^5.0.8",
-    "@types/earcut": "^3.0.0",
-    "@types/jquery": "~3.5.22",
+    "@codemirror/lang-markdown": "^6.3.2",
+    "@pixi/basis": "github:foundry-vtt-types/pixi-basis#main",
+    "@pixi/graphics-smooth": "^1.1.1",
+    "@pixi/particle-emitter": "github:foundry-vtt-types/pixi-particle-emitter#main",
+    "@types/jquery": "^3.5.32",
     "@types/showdown": "~2.0.6",
     "@types/simple-peer": "~9.11.1",
     "@types/youtube": "~0.0.48",
-    "earcut": "^3.0.1",
     "codemirror": "^6.0.1",
     "handlebars": "^4.7.8",
     "handlebars-intl": "^1.1.2",
     "jquery": "^3.7.1",
-    "mime-types": "^2.1.35",
+    "mime-types": "^3.0.1",
     "peggy": "^4.2.0",
-    "pixi.js": "^7.4.2",
+    "pixi.js": "github:foundry-vtt-types/pixi.js#main",
+    "pixi-basis-ktx2": "^0.0.22",
     "prosemirror-collab": "^1.3.1",
-    "prosemirror-commands": "^1.6.2",
+    "prosemirror-commands": "^1.7.0",
     "prosemirror-dropcursor": "^1.8.1",
     "prosemirror-gapcursor": "^1.3.2",
     "prosemirror-history": "^1.4.1",
-    "prosemirror-inputrules": "^1.4.0",
+    "prosemirror-inputrules": "^1.5.0",
     "prosemirror-keymap": "^1.2.2",
-    "prosemirror-model": "^1.23.0",
-    "prosemirror-schema-list": "^1.4.1",
+    "prosemirror-model": "^1.25.0",
+    "prosemirror-schema-list": "^1.5.1",
     "prosemirror-state": "^1.4.3",
-    "prosemirror-tables": "^1.6.1",
-    "prosemirror-transform": "^1.10.2",
-    "prosemirror-view": "^1.36.0",
-    "sanitize-html": "^2.13.1",
+    "prosemirror-tables": "^1.6.4",
+    "prosemirror-transform": "^1.10.3",
+    "prosemirror-view": "^1.38.1",
+    "sanitize-html": "^2.15.0",
     "showdown": "^2.1.0",
     "simple-peer": "^9.11.1",
     "socket.io": "^4.8.1",
     "socket.io-client": "^4.8.1",
     "spark-md5": "^3.0.2",
-    "tinymce": "^7.5.1"
+    "tinymce": "^6.8.5"
   },
   "devDependencies": {
     "@actions/core": "^1.11.1",
     "@actions/github": "^6.0.0",
+    "@betterer/betterer": "^6.0.0-alpha.1",
+    "@betterer/cli": "^6.0.0-alpha.1",
     "@eslint/compat": "^1.2.6",
     "@eslint/js": "^9.19.0",
-    "@ts-morph/common": "^0.26.1",
     "@types/debug": "^4.1.12",
     "@types/fvtt-types": "file:.",
-    "@typescript-eslint/eslint-plugin": "^8.23.0",
-    "@typescript-eslint/parser": "^8.23.0",
-    "@typescript-eslint/utils": "^8.23.0",
+    "@typescript-eslint/eslint-plugin": "^8.31.0",
+    "@typescript-eslint/parser": "^8.31.0",
+    "@typescript-eslint/scope-manager": "^8.31.0",
+    "@typescript-eslint/utils": "^8.31.0",
+    "@typescript/native-preview": "^7.0.0-dev.20250620.1",
     "eslint": "^9.19.0",
     "eslint-config-prettier": "^10.0.1",
-    "eslint-import-resolver-typescript": "^3.7.0",
+    "eslint-import-resolver-typescript": "^4.3.2",
     "eslint-plugin-import-x": "^4.6.1",
+    "eslint-plugin-jsdoc": "^51.0.1",
     "eslint-plugin-tsdoc": "^0.4.0",
-    "globals": "^15.14.0",
+    "globals": "^16.0.0",
     "husky": "^9.1.4",
     "is-ci": "^4.1.0",
-    "lint-staged": "^15.3.0",
-    "npm-run-all": "^4.1.5",
+    "lint-staged": "^16.0.0",
+    "npm-run-all2": "^8.0.1",
     "pathe": "^2.0.2",
     "prettier": "^3.0.3",
-    "type-fest": "^4.34.0",
-    "typescript": "~5.7",
-    "typescript-eslint": "^8.23.0",
-    "vitest": "^3.0.5"
+    "type-fest": "^4.41.0",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.31.0",
+    "vitest": "^4.0.0-beta.1"
   },
   "peerDependencies": {
     "typescript": "^5.4"
   },
-  "overrides": {
-    "@types/css-font-loading-module": "^0.0.14",
-    "@pixi/utils": {
-      "@types/earcut": "3.0.0"
-    }
-  },
   "files": [
     "index.d.mts",
     "index-lenient.d.mts",
-    "src"
+    "src",
+    "tsconfig.base.json",
+    "tsconfig.json"
   ],
   "publishConfig": {
     "access": "public"

package/src/configuration/configuration.d.mts

@@ -1,9 +1,12 @@
-import type { DeepPartial, MaybeEmpty } from "fvtt-types/utils";
+import type { DeepPartial, InterfaceToObject, MaybeEmpty } from "#utils";
 import type { fields } from "../foundry/common/data/_module.d.mts";
 import type Document from "../foundry/common/abstract/document.d.mts";
 
+import AVSettings = foundry.av.AVSettings;
+import Game = foundry.Game;
+
 /**
- * Some global variables (such as {@link game}) are only initialized after certain events have happened during the
+ * Some global variables (such as {@linkcode game}) are only initialized after certain events have happened during the
  * initialization of Foundry VTT. For that reason, the correct types for these variables include the types for the
  * uninitialized state.
  *
@@ -24,7 +27,7 @@ import type Document from "../foundry/common/abstract/document.d.mts";
  *
  * @example
  * ```typescript
- * declare global {
+ * declare module "fvtt-types/configuration" {
  *   interface AssumeHookRan {
  *     setup: never; // the type doesn't matter
  *   }
@@ -48,14 +51,14 @@ export interface AssumeHookRan {}
  * // myActor.ts
  * class MyActor extends Actor {}
  *
- * // entryPoint.ts
+ * // index.ts
  * import { MyActor } from "./myActor"
  *
- * hooks.once("init", () => {
+ * Hooks.once("init", () => {
  *   CONFIG.Actor.documentClass = typeof MyActor;
  * });
  *
- * declare global {
+ * declare module "fvtt-types/configuration" {
  *   interface DocumentClassConfig {
  *     Actor: typeof MyActor
  *   }
@@ -77,14 +80,14 @@ export interface DocumentClassConfig {}
  * // myToken.ts
  * class MyToken extends Token {}
  *
- * // entryPoint.ts
+ * // index.ts
  * import { MyToken } from "./myToken"
  *
  * Hooks.once("init", () => {
  *   CONFIG.Token.objectClass = MyToken;
  * });
  *
- * declare global {
+ * declare module "fvtt-types/configuration" {
  *   interface PlaceableObjectClassConfig {
  *     Token: typeof MyToken;
  *   }
@@ -95,9 +98,9 @@ export interface DocumentClassConfig {}
 export interface PlaceableObjectClassConfig {}
 
 /**
- * This interface together with {@link SourceConfig} is used to configure the
+ * This interface together with {@linkcode SourceConfig} is used to configure the
  * types of the `data`  and `data._source` properties of the
- * {@link foundry.documents.BaseActor} and {@link foundry.documents.BaseItem}
+ * {@linkcode foundry.documents.BaseActor} and {@linkcode foundry.documents.BaseItem}
  * classes. System authors should use declaration merging to provide the types
  * that match their `template.json` file. It is also very important for these
  * types to stay in sync with the `template.json` file, otherwise unexpected
@@ -145,7 +148,7 @@ export interface PlaceableObjectClassConfig {}
  * type MyItemDataSource = ArmorDataSource | WeaponDataSource;
  * type MyItemDataProperties = ArmorDataProperties | WeaponDataProperties;
  *
- * declare global {
+ * declare module "fvtt-types/configuration" {
  *   interface DataConfig {
  *     Item: MyItemDataProperties;
  *   }
@@ -161,11 +164,11 @@ export interface PlaceableObjectClassConfig {}
  *   damage: 5
  * });
  *
- * if(item.data.type === "weapon") {
+ * if (item.data.type === "weapon") {
  *   const damage: number = item.data.data.damage;
  * }
  *
- * if(item.data._source.type === "armor") {
+ * if (item.data._source.type === "armor") {
  *   const armorValue = item.data._source.data.armorValue;
  * }
  * ```
@@ -187,7 +190,7 @@ export interface GetDataConfig {}
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface DataModelConfig {}
 
-/** @see {@link DataConfig} */
+/** @see {@linkcode DataConfig} */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface SourceConfig {}
 
@@ -199,8 +202,8 @@ export interface WebRTCConfig {}
 
 /**
  * Injects extra data for modules from `game.modules.get("module-id")`.
- * @see {@link RequiredModules} for removing the `undefined` type for required modules.
- *  @example
+ * @see {@linkcode RequiredModules} for removing the `undefined` type for required modules.
+ * @example
  * ```typescript
  * interface ModuleConfig {
  *   "module-id": {
@@ -216,7 +219,7 @@ export interface ModuleConfig {}
 /**
  * Removes `undefined` for modules listed as keys here from the return type of `game.modules.get`.
  * Useful if a module is a required dependency.
- * @see {@link ModuleConfig} for adding useful properties to the returned modules, like APIs.
+ * @see {@linkcode ModuleConfig} for adding useful properties to the returned modules, like APIs.
  * @example
  * ```typescript
  * interface RequiredModules {
@@ -233,7 +236,10 @@ export interface SettingConfig {
   "core.chatBubbles": fields.BooleanField<{ initial: true }>;
   "core.chatBubblesPan": fields.BooleanField<{ initial: true }>;
   "core.combatTrackerConfig": MaybeEmpty<{ resource: string; skipDefeated: boolean }>;
-  "core.compendiumConfiguration": Partial<Record<string, CompendiumCollection.Configuration>>;
+  "core.compendiumConfiguration": Partial<
+    Record<string, foundry.documents.collections.CompendiumCollection.Configuration>
+  >;
+  "core.gridTemplates": fields.BooleanField<{ initial: false }>;
   "core.coneTemplateType": "round" | "flat";
   "core.colorSchema": fields.StringField<{
     required: true;
@@ -255,14 +261,16 @@ export interface SettingConfig {
   }>;
   "core.defaultDrawingConfig": MaybeEmpty<foundry.documents.BaseDrawing["_source"]>;
   "core.defaultToken": DeepPartial<foundry.documents.BaseToken>;
-  "core.diceConfiguration": Record<CONFIG.Dice.DTermDiceStrings, string>;
+  "core.diceConfiguration": {
+    [K in CONFIG.Dice.DTermDiceStrings]?: string | undefined;
+  };
   "core.disableResolutionScaling": boolean;
   "core.fontSize": number;
   "core.fpsMeter": boolean;
   "core.globalAmbientVolume": number;
   "core.globalInterfaceVolume": number;
   "core.globalPlaylistVolume": number;
-  "core.keybindings": Record<string, ClientKeybindings.KeybindingActionBinding[]>;
+  "core.keybindings": Record<string, foundry.helpers.interaction.ClientKeybindings.KeybindingActionBinding[]>;
   "core.language": fields.StringField<{
     required: true;
     blank: false;
@@ -282,26 +290,36 @@ export interface SettingConfig {
     nullable: true;
     initial: null;
     choices: {
-      [_ in typeof CONST.CANVAS_PERFORMANCE_MODES.LOW]: "SETTINGS.PerformanceModeLow";
-    } & {
-      [_ in typeof CONST.CANVAS_PERFORMANCE_MODES.MED]: "SETTINGS.PerformanceModeMed";
-    } & {
-      [_ in typeof CONST.CANVAS_PERFORMANCE_MODES.HIGH]: "SETTINGS.PerformanceModeHigh";
-    } & {
-      [_ in typeof CONST.CANVAS_PERFORMANCE_MODES.MAX]: "SETTINGS.PerformanceModeMax";
+      // Note: these keys correspond to values of `CANVAS_PERFORMANCE_MODES`. They are not used
+      // directly because the values are branded.
+      0: "SETTINGS.PerformanceModeLow";
+      1: "SETTINGS.PerformanceModeMed";
+      2: "SETTINGS.PerformanceModeHigh";
+      3: "SETTINGS.PerformanceModeMax";
     };
   }>;
   "core.permissions": Game.Permissions;
   "core.pixelRatioResolutionScaling": fields.BooleanField<{ initial: true }>;
   "core.playlist.playingLocation": "top" | "bottom";
-  "core.rollMode": fields.StringField<{
-    required: true;
-    blank: false;
-    initial: typeof CONST.DICE_ROLL_MODES.PUBLIC;
-    choices: typeof CONFIG.Dice.rollModes;
-  }>;
-  "core.rtcClientSettings": typeof AVSettings.DEFAULT_CLIENT_SETTINGS;
-  "core.rtcWorldSettings": typeof AVSettings.DEFAULT_WORLD_SETTINGS;
+
+  /**
+   * @remarks `choices` is a type with the index signature of {@linkcode CONFIG.Dice.rollModes} removed.
+   * If you want to use a custom `rollMode`, you must register it in `CONFIG`.
+   */
+  "core.rollMode": fields.StringField<
+    {
+      required: true;
+      blank: false;
+      initial: typeof CONST.DICE_ROLL_MODES.PUBLIC;
+      choices: InterfaceToObject<typeof CONFIG.Dice.rollModes>;
+    },
+    // Note(LukeAbby): This override is necessary because the `initial` wasn't removing `null`.
+    (string & keyof typeof CONFIG.Dice.rollModes) | null | undefined,
+    string & keyof typeof CONFIG.Dice.rollModes,
+    string & keyof typeof CONFIG.Dice.rollModes
+  >;
+  "core.rtcClientSettings": typeof AVSettings.schemaFields.client;
+  "core.rtcWorldSettings": typeof AVSettings.schemaFields.world;
   "core.scrollingStatusText": fields.BooleanField<{ initial: true }>;
   "core.sheetClasses": {
     [Key in Document.Type as Document.SubTypesOf<Key> extends string ? Key : never]?: Record<
@@ -313,3 +331,20 @@ export interface SettingConfig {
   "core.tokenDragPreview": boolean;
   "core.visionAnimation": boolean;
 }
+
+/**
+ * Allows you to control the name of your system. Useful for typing things like `game.system.id`
+ * @example
+ * ```typescript
+ * declare module "fvtt-types/configuration" {
+ *   interface SystemNameConfig {
+ *     name: "lancer";
+ *   }
+ * }
+ *
+ * const systemName = game.system.id;
+ * //    ^? "lancer"
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface SystemNameConfig {}