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

package/src/foundry/common/data/_module.d.mts

@@ -7,3 +7,4 @@ export * as validators from "./validators.mjs";
 export * as validation from "./validation-failure.mjs";
 export * as fields from "./fields.mjs";
 export * from "./data.mjs";
+export { ActorDeltaField } from "../documents/token.mjs";

package/src/foundry/common/data/_types.d.mts

@@ -1,3 +1,6 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import type { fields } from "./_module.d.mts";
+
 // After seeing that none of these types add anything or are even exported a
 // very reasonable question may be: Why on earth does this file exist?
 //
@@ -8,11 +11,11 @@
 // TODO: Stubs
 export {};
 
-type DataFieldValidator = unknown;
+type DataFieldValidator = fields.DataField.Validator<fields.DataField.Any, unknown>;
 
-type DataFieldOptions = unknown;
+type DataFieldOptions = fields.DataField.Options.Any;
 
-type DataFieldContext = unknown;
+type DataFieldContext = fields.DataField.ConstructionContext;
 
 type FormGroupConfig = unknown;
 
@@ -24,24 +27,24 @@ type CodeMirrorLanguage = unknown;
 
 type CodeMirrorInputConfig = unknown;
 
-type LightAnimationData = unknown;
+type LightAnimationData = foundry.data.LightData.AnimationData;
 
-type NumberFieldOptions = unknown;
+type NumberFieldOptions = fields.NumberField.Options;
 
-type StringFieldOptions = unknown;
+type StringFieldOptions = fields.StringField.Options;
 
 type ChoiceInputConfig = unknown;
 
-type ArrayFieldOptions = unknown;
+type ArrayFieldOptions = fields.ArrayField.Options<unknown>;
 
-type DocumentUUIDFieldOptions = unknown;
+type DocumentUUIDFieldOptions = fields.DocumentUUIDField.Options;
 
-type FilePathFieldOptions = unknown;
+type FilePathFieldOptions = fields.FilePathField;
 
-type DocumentFlags = unknown;
+type DocumentFlags = Record<string, Record<string, unknown>>;
 
-type DocumentStats = unknown;
+type DocumentStats = fields.DocumentStatsField.Data;
 
-type JavaScriptFieldOptions = unknown;
+type JavaScriptFieldOptions = fields.JavaScriptField.Options;
 
-type ElementValidationFailure = unknown;
+type ElementValidationFailure = foundry.data.validation.DataModelValidationFailure.ElementValidationFailure;

package/src/foundry/common/data/data.d.mts

@@ -1,25 +1,32 @@
-import type { DatabaseBackend } from "../abstract/_module.d.mts";
 import type { DataModel } from "../abstract/data.d.mts";
-import type { fields } from "./_module.d.mts";
-import type * as documents from "../documents/_module.d.mts";
-import type { AnyMutableObject, EmptyObject, ToMethod, ValueOf } from "fvtt-types/utils";
-import type { FilePathField } from "./fields.d.mts";
+import type {
+  AnyMutableObject,
+  EmptyObject,
+  GetKey,
+  NullishCoalesce,
+  RemoveIndexSignatures,
+  ToMethod,
+  ValueOf,
+} from "#utils";
+import type { SchemaField } from "./fields.d.mts";
+
+import fields = foundry.data.fields;
+import documents = foundry.documents;
+import Document = foundry.abstract.Document;
 
 type DataSchema = foundry.data.fields.DataSchema;
 
-// TODO: Implement all of the necessary options
-
-declare global {
-  type LightAnimationData = fields.SchemaField.InnerInitializedType<LightData.LightAnimationDataSchema>;
-}
-
 declare namespace LightData {
-  type Parent = TokenDocument | AmbientLightDocument;
+  type Parent = TokenDocument.Implementation | AmbientLightDocument.Implementation;
+
+  interface AnimationData extends fields.SchemaField.InitializedData<LightAnimationDataSchema> {}
 
   interface LightAnimationDataSchema extends DataSchema {
     /**
      * The animation type which is applied
      * @defaultValue `null`
+     * @remarks While not enforced by the data model, this should be in `keyof CONFIG.Canvas.lightAnimations`
+     * (or `.darknessAnimations` as appropriate) or the animation will be ignored
      */
     type: fields.StringField<{ nullable: true; blank: false; initial: null }>;
 
@@ -62,12 +69,12 @@ declare namespace LightData {
     /**
      * @defaultValue `0`
      */
-    min: fields.NumberField<{ initial: 0 }>;
+    min: fields.AlphaField<{ initial: 0 }>;
 
     /**
      * @defaultValue `1`
      */
-    max: fields.NumberField<{ initial: 1 }>;
+    max: fields.AlphaField<{ initial: 1 }>;
   }
 
   interface Schema extends DataSchema {
@@ -109,6 +116,7 @@ declare namespace LightData {
     /**
      * The coloration technique applied in the shader
      * @defaultValue `1`
+     * @remarks This should match the `id` of the desired property of {@linkcode AdaptiveLightingShader.SHADER_TECHNIQUES}
      */
     coloration: fields.NumberField<{ required: true; integer: true; initial: 1 }>;
 
@@ -161,7 +169,7 @@ declare namespace LightData {
     darkness: fields.SchemaField<
       DarknessSchema,
       {
-        validate: (d: fields.SchemaField.InnerAssignmentType<DarknessSchema>) => boolean;
+        validate: (d: unknown) => boolean;
         validationError: "darkness.max may not be less than darkness.min";
       }
     >;
@@ -175,12 +183,15 @@ declare namespace LightData {
 declare class LightData extends DataModel<LightData.Schema, LightData.Parent> {
   static override defineSchema(): LightData.Schema;
 
-  /**
-   * @defaultValue `["LIGHT"]`
-   */
+  /** @defaultValue `["LIGHT"]` */
   static override LOCALIZATION_PREFIXES: string[];
 
-  static migrateData(source: AnyMutableObject): AnyMutableObject;
+  /**
+   * @remarks
+   * Migrations:
+   * - negative `luminosity`s to `1 - luminosity` and setting `negative` true
+   */
+  static override migrateData(source: AnyMutableObject): AnyMutableObject;
 }
 
 declare namespace ShapeData {
@@ -237,17 +248,26 @@ declare class ShapeData extends DataModel<ShapeData.Schema> {
 }
 
 declare namespace BaseShapeData {
-  interface Schema extends DataSchema {
+  interface Source extends fields.SchemaField.SourceData<Schema> {}
+  interface CreateData extends fields.SchemaField.CreateData<Schema> {}
+  interface InitializedData extends fields.SchemaField.InitializedData<Schema> {}
+  interface UpdateData extends fields.SchemaField.UpdateData<Schema> {}
+
+  interface Schema<ShapeType extends ShapeTypes = ShapeTypes> extends DataSchema {
     /**
      * The type of shape, a value in BaseShapeData.TYPES.
      * @defaultValue `this.TYPE`
+     * @remarks `this.TYPE` is `""` in `BaseShapeData`, and must be defined by subclasses
      */
     type: fields.StringField<{
       required: true;
       blank: false;
-      initial: string;
-      validate: (value: string) => boolean;
-      validationError: `must be equal to "${string}"`;
+      initial: ShapeType;
+      validate: (value: unknown) => value is ShapeType;
+      // TODO: The following `choices` does not exist in Foundry, it's a type hack to get this field to report as the only valid value it can have
+      // TODO: The validation function enough might be able to be made to sufficiently limit the value
+      choices: [ShapeType];
+      validationError: `must be equal to "${ShapeType}"`;
     }>;
 
     /**
@@ -257,6 +277,8 @@ declare namespace BaseShapeData {
     hole: fields.BooleanField;
   }
 
+  type ShapeTypes = keyof RemoveIndexSignatures<BaseShapeData.Types>;
+
   interface Types extends foundry.data.fields.TypedSchemaField.Types {
     rectangle: typeof RectangleShapeData;
     circle: typeof CircleShapeData;
@@ -268,7 +290,9 @@ declare namespace BaseShapeData {
 /**
  * A data model intended to be used as an inner EmbeddedDataField which defines a geometric shape.
  */
-declare abstract class BaseShapeData extends DataModel<BaseShapeData.Schema> {
+declare abstract class BaseShapeData<
+  ShapeSchema extends BaseShapeData.Schema = BaseShapeData.Schema,
+> extends DataModel<ShapeSchema> {
   /**
    * The possible shape types.
    */
@@ -285,7 +309,7 @@ declare abstract class BaseShapeData extends DataModel<BaseShapeData.Schema> {
 }
 
 declare namespace RectangleShapeData {
-  interface Schema extends BaseShapeData.Schema {
+  interface Schema extends BaseShapeData.Schema<"rectangle"> {
     /**
      * The top-left x-coordinate in pixels before rotation.
      * @defaultValue `undefined`
@@ -321,17 +345,14 @@ declare namespace RectangleShapeData {
 /**
  * The data model for a rectangular shape.
  */
-declare class RectangleShapeData extends BaseShapeData {
-  /**
-   * @defaultValue `"rectangle"`
-   */
-  static override TYPE: string;
+declare class RectangleShapeData extends BaseShapeData<RectangleShapeData.Schema> {
+  static override TYPE: "rectangle";
 
   static override defineSchema(): RectangleShapeData.Schema;
 }
 
 declare namespace CircleShapeData {
-  interface Schema extends BaseShapeData.Schema {
+  interface Schema extends BaseShapeData.Schema<"circle"> {
     /**
      * The x-coordinate of the center point in pixels.
      * @defaultValue `undefined`
@@ -355,17 +376,14 @@ declare namespace CircleShapeData {
 /**
  * The data model for a circle shape.
  */
-declare class CircleShapeData extends BaseShapeData {
-  /**
-   * @defaultValue `"circle"`
-   */
-  static override TYPE: string;
+declare class CircleShapeData extends BaseShapeData<CircleShapeData.Schema> {
+  static override TYPE: "circle";
 
   static override defineSchema(): CircleShapeData.Schema;
 }
 
 declare namespace EllipseShapeData {
-  interface Schema extends BaseShapeData.Schema {
+  interface Schema extends BaseShapeData.Schema<"ellipse"> {
     /**
      * The x-coordinate of the center point in pixels.
      * @defaultValue `undefined`
@@ -401,17 +419,14 @@ declare namespace EllipseShapeData {
 /**
  * The data model for an ellipse shape.
  */
-declare class EllipseShapeData extends BaseShapeData {
-  /**
-   * @defaultValue `"ellipse"`
-   */
-  static override TYPE: string;
+declare class EllipseShapeData extends BaseShapeData<EllipseShapeData.Schema> {
+  static override TYPE: "ellipse";
 
   static override defineSchema(): EllipseShapeData.Schema;
 }
 
 declare namespace PolygonShapeData {
-  interface Schema extends BaseShapeData.Schema {
+  interface Schema extends BaseShapeData.Schema<"polygon"> {
     /**
      * The points of the polygon ([x0, y0, x1, y1, ...]).
      * The polygon must not be self-intersecting.
@@ -427,97 +442,175 @@ declare namespace PolygonShapeData {
 /**
  * The data model for a polygon shape.
  */
-declare class PolygonShapeData extends BaseShapeData {
-  /**
-   * @defaultValue `"polygon"`
-   */
-  static override TYPE: string;
+declare class PolygonShapeData extends BaseShapeData<PolygonShapeData.Schema> {
+  static override TYPE: "polygon";
 
   static override defineSchema(): PolygonShapeData.Schema;
 }
 
 declare namespace TextureData {
+  /** The parameter defaults for `srcOptions` in the {@link TextureData} constructor */
   interface DefaultOptions {
     categories: ["IMAGE", "VIDEO"];
-    // initial: {};
+    initial: EmptyObject;
     wildcard: false;
     label: "";
   }
 
-  interface Schema<SrcOptions extends FilePathField.Options> extends DataSchema {
+  /**
+   * The `initial` property of the `srcOptions` parameter of the {@linkcode TextureData} constructor
+   * is not the `initial` for any one field, but instead is an object that gets parcelled out by key to the
+   * fields of the schema
+   *
+   * @internal
+   */
+  type _SrcOptionsInitial<T> = {
+    [K in keyof T]: fields.DataField.Options.InitialType<T[K]>;
+  };
+
+  /** @remarks The keys picked directly are passed on to the `src: FilePathField` field, but `initial` is an object of initial values for potentially every field in the schema */
+  interface SrcOptions extends Pick<fields.FilePathField.Options, "categories" | "wildcard" | "label"> {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    initial: _SrcOptionsInitial<fields.SchemaField.AssignmentData<Schema<DefaultOptions>>>;
+  }
+
+  interface Schema<Options extends SrcOptions = DefaultOptions> extends DataSchema {
     /**
      * The URL of the texture source.
      * @defaultValue `initial.src ?? null`
-     */
-    src: fields.FilePathField<SrcOptions>;
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
+     */
+    src: fields.FilePathField<{
+      categories: NullishCoalesce<Options["categories"], DefaultOptions["categories"]>;
+      initial: NullishCoalesce<GetKey<Options["initial"], "src", null>, null>;
+      wildcard: NullishCoalesce<Options["wildcard"], DefaultOptions["wildcard"]>;
+      label: NullishCoalesce<Options["label"], DefaultOptions["label"]>;
+    }>;
 
     /**
      * The X coordinate of the texture anchor.
      * @defaultValue `initial.anchorX ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    anchorX: fields.NumberField<{ nullable: false; initial: number }>;
+    anchorX: fields.NumberField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "anchorX", 0>, 0>;
+    }>;
 
     /**
      * The Y coordinate of the texture anchor.
      * @defaultValue `initial.anchorY ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    anchorY: fields.NumberField<{ nullable: false; initial: number }>;
+    anchorY: fields.NumberField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "anchorY", 0>, 0>;
+    }>;
 
     /**
      * The X offset of the texture with (0,0) in the top left.
      * @defaultValue `initial.offsetX ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    offsetX: fields.NumberField<{ nullable: false; integer: true; initial: number }>;
+    offsetX: fields.NumberField<{
+      nullable: false;
+      integer: true;
+      initial: NullishCoalesce<GetKey<Options["initial"], "offsetX", 0>, 0>;
+    }>;
 
     /**
      * The Y offset of the texture with (0,0) in the top left.
      * @defaultValue `initial.offsetY ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    offsetY: fields.NumberField<{ nullable: false; integer: true; initial: number }>;
+    offsetY: fields.NumberField<{
+      nullable: false;
+      integer: true;
+      initial: NullishCoalesce<GetKey<Options["initial"], "offsetY", 0>, 0>;
+    }>;
 
     /**
      * @defaultValue `initial.fit ?? "fill"`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    fit: fields.StringField<{ initial: string; choices: typeof CONST.TEXTURE_DATA_FIT_MODES }>;
+    fit: fields.StringField<
+      {
+        initial: NullishCoalesce<GetKey<Options["initial"], "fit", "fill">, "fill">;
+        choices: typeof CONST.TEXTURE_DATA_FIT_MODES;
+      },
+      ValueOf<typeof CONST.TEXTURE_DATA_FIT_MODES> | null | undefined,
+      ValueOf<typeof CONST.TEXTURE_DATA_FIT_MODES>,
+      ValueOf<typeof CONST.TEXTURE_DATA_FIT_MODES>
+    >;
 
     /**
      * The scale of the texture in the X dimension.
      * @defaultValue `initial.scaleX ?? 1`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    scaleX: fields.NumberField<{ nullable: false; initial: number }>;
+    scaleX: fields.NumberField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "scaleX", 1>, 1>;
+    }>;
 
     /**
      * The scale of the texture in the Y dimension.
      * @defaultValue `initial.scaleY ?? 1`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    scaleY: fields.NumberField<{ nullable: false; initial: number }>;
+    scaleY: fields.NumberField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "scaleY", 1>, 1>;
+    }>;
 
     /**
      * An angle of rotation by which this texture is rotated around its center.
      * @defaultValue `initial.rotation ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    rotation: fields.AngleField<{ initial: number }>;
+    rotation: fields.AngleField<{
+      initial: NullishCoalesce<GetKey<Options["initial"], "rotation", 0>, 0>;
+    }>;
 
     /**
      * The tint applied to the texture.
      * @defaultValue `initial.tint ?? "#ffffff"`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    tint: fields.ColorField<{ nullable: false; initial: string }>;
+    tint: fields.ColorField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "tint", "#ffffff">, "#ffffff">;
+    }>;
 
     /**
      * Only pixels with an alpha value at or above this value are consider solid
      * w.r.t. to occlusion testing and light/weather blocking.
      * @defaultValue `initial.alphaThreshold ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@linkcode TextureData} constructor
      */
-    alphaThreshold: fields.AlphaField<{ nullable: false; initial: number }>;
+    alphaThreshold: fields.AlphaField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "alphaThreshold", 0>, 0>;
+    }>;
   }
 }
 
 /**
- * A {@link fields.SchemaField} subclass used to represent texture data.
+ * A {@linkcode fields.SchemaField} subclass used to represent texture data.
  */
 declare class TextureData<
-  SrcOptions extends FilePathField.Options = TextureData.DefaultOptions,
+  SrcOptions extends TextureData.SrcOptions = TextureData.DefaultOptions,
   SchemaOptions extends fields.SchemaField.Options<TextureData.Schema<SrcOptions>> = EmptyObject,
 > extends fields.SchemaField<TextureData.Schema<SrcOptions>, SchemaOptions> {
   /**
@@ -530,7 +623,11 @@ declare class TextureData<
 declare namespace PrototypeToken {
   type Parent = documents.BaseActor;
 
-  // Not otherwise used
+  /**
+   * The fields foundry omits from the BaseToken schema. Not used, left as reference
+   *
+   * @internal
+   */
   type ExcludedProperties =
     | "_id"
     | "actorId"
@@ -543,29 +640,54 @@ declare namespace PrototypeToken {
     | "locked"
     | "_regions";
 
-  interface Schema extends foundry.documents.BaseToken.SharedProtoSchema {
-    name: fields.StringField<{ required: true; blank: true; textSearch: boolean }>;
+  /**
+   * @remarks This has `PrototypeToken.#applyDefaultTokenSettings` run on it before actually being returned, so `initial`
+   * values may not be exactly accurate as typed
+   * @privateRemarks Since the {@link TokenDocument.Schema | `TokenDocument` schema} also extends `SharedProtoSchema`,
+   * overrides & extensions specific to {@linkcode PrototypeToken} must go here
+   */
+  interface Schema extends TokenDocument.SharedProtoSchema {
+    /**
+     * The name used to describe the Token
+     * @defaultValue `""`
+     * @privateRemarks Only change from parent schema is `textSearch: false`
+     */
+    name: fields.StringField<{ required: true; blank: true; textSearch: false }>;
 
     /**
      * Does the prototype token use a random wildcard image?
      * @defaultValue `false`
+     * @privateRemarks New field, not in parent schema
      */
     randomImg: fields.BooleanField;
   }
 
-  type ConstructorData = fields.SchemaField.InnerAssignmentType<Schema>;
+  /**
+   * @deprecated Replace with {@linkcode PrototypeToken.CreateData}.
+   */
+  type ConstructorData = CreateData;
+
+  interface CreateData extends fields.SchemaField.CreateData<Schema> {}
+
+  interface UpdateData extends fields.SchemaField.UpdateData<Schema> {}
+
+  interface Source extends fields.SchemaField.SourceData<Schema> {}
+
+  export import Flags = TokenDocument.Flags;
 }
 
 /**
  * Extend the base TokenData to define a PrototypeToken which exists within a parent Actor.
  */
-declare class PrototypeToken extends DataModel<PrototypeToken.Schema, any> {
-  constructor(data?: PrototypeToken.ConstructorData, options?: DataModel.DataValidationOptions<PrototypeToken.Parent>);
+declare class PrototypeToken extends DataModel<PrototypeToken.Schema, PrototypeToken.Parent> {
+  // options: not null (destructured when passed to super)
+  constructor(data?: PrototypeToken.Source | null, options?: DataModel.ConstructionContext<PrototypeToken.Parent>);
 
-  declare parent: PrototypeToken.Parent;
-
-  /** @defaultValue `{}` */
-  apps: Record<string, Application.Any>;
+  /**
+   * @defaultValue `{}`
+   * @remarks Created via `defineProperty` in constructor
+   */
+  apps: Record<string, foundry.appv1.api.Application.Any | foundry.applications.api.ApplicationV2.Any>;
 
   static override defineSchema(): PrototypeToken.Schema;
 
@@ -579,10 +701,11 @@ declare class PrototypeToken extends DataModel<PrototypeToken.Schema, any> {
    */
   get actor(): this["parent"];
 
-  override toObject(source: true): this["_source"] & { actorId: string | undefined };
-  override toObject(source?: boolean): ReturnType<this["schema"]["toObject"]>;
+  override toObject(
+    source?: boolean | null,
+  ): SchemaField.SourceData<PrototypeToken.Schema> & { actorId: string | undefined };
 
-  static get database(): DatabaseBackend;
+  static get database(): CONFIG["DatabaseBackend"];
 
   /**
    * Apply configured default token settings to the schema.
@@ -591,45 +714,63 @@ declare class PrototypeToken extends DataModel<PrototypeToken.Schema, any> {
   static #applyDefaultTokenSettings(schema: DataSchema): void;
 
   /**
-   * @see foundry.abstract.Document#update
+   * @see {@link foundry.abstract.Document.update | `foundry.abstract.Document#update`}
+   * @remarks Despite the above `@see`, forwards to {@link Actor.update | `this.actor.update`} after wrapping `data`
+   * in `{prototypeToken: data}`
    */
-  update(data: unknown, options: unknown): unknown;
+  update(
+    data: PrototypeToken.UpdateData | undefined,
+    operation?: Actor.Database.UpdateOperation,
+  ): Promise<Actor.Implementation | undefined>;
 
   /**
-   * @see foundry.abstract.Document#getFlag
+   * @see {@link foundry.abstract.Document.getFlag | `foundry.abstract.Document#getFlag`}
    */
-  getFlag(args: unknown): unknown;
+  getFlag<Scope extends TokenDocument.Flags.Scope, Key extends TokenDocument.Flags.Key<Scope>>(
+    scope: Scope,
+    key: Key,
+  ): Document.GetFlag<TokenDocument.Name, Scope, Key>;
 
   /**
-   * @see foundry.abstract.Document#setFlag
+   * @see {@link foundry.abstract.Document.setFlag | `foundry.abstract.Document#setFlag`}
    */
-  setFlag(args: unknown): unknown;
+  setFlag<
+    Scope extends TokenDocument.Flags.Scope,
+    Key extends TokenDocument.Flags.Key<Scope>,
+    Value extends Document.GetFlag<TokenDocument.Name, Scope, Key>,
+  >(scope: Scope, key: Key, value: Value): Promise<this>;
 
   /**
-   * @see foundry.abstract.Document#unsetFlag
+   * @see {@link foundry.abstract.Document.unsetFlag | `foundry.abstract.Document#unsetFlag`}
    */
-  unsetFlag(args: unknown): Promise<unknown>;
+  unsetFlag<Scope extends TokenDocument.Flags.Scope, Key extends TokenDocument.Flags.Key<Scope>>(
+    scope: Scope,
+    key: Key,
+  ): Promise<this>;
 
   /**
-   * @see foundry.abstract.Document#testUserPermission
+   * @see {@link Document.testUserPermission | `Document#testUserPermission`}
+   * @remarks Forwards to {@link Actor.testUserPermission | `this.actor.testUserPermission`}. Core's `Actor` implementation
+   * doesn't override this method, so without further extension, that's equivalent to `Document#testUserPermission`
    */
+  // options: not null (destructured)
   testUserPermission(
-    user: User,
-    permission: unknown,
-    { exact }: { exact: boolean },
-  ): ReturnType<this["actor"]["testUserPermission"]>;
+    user: User.Implementation,
+    permission: Document.ActionPermission,
+    options?: Document.TestUserPermissionOptions,
+  ): boolean;
 
   /**
-   * @see foundry.abstract.Document#isOwner
+   * @see {@link foundry.abstract.Document.isOwner | `foundry.abstract.Document#isOwner`}
    */
   get isOwner(): boolean;
 
   /**
-   * @see TokenDocument#getBarAttribute
+   * @see {@link TokenDocument.getBarAttribute | `TokenDocument#getBarAttribute`}
    *
    * @remarks This is monkey patched in from `token.js`, put here due to issues with the merge process
    */
-  getBarAttribute: ToMethod<TokenDocument["getBarAttribute"]>;
+  getBarAttribute: ToMethod<TokenDocument.Implementation["getBarAttribute"]>;
 }
 
 declare namespace TombstoneData {
@@ -646,7 +787,7 @@ declare namespace TombstoneData {
      */
     _tombstone: fields.BooleanField<{
       initial: true;
-      validate: (v: boolean) => boolean;
+      validate: (v: unknown) => boolean;
       validationError: "must be true";
     }>;
   }