@league-of-foundry-developers/foundry-vtt-types 12.331.3-beta → 12.331.5

package/src/foundry/client/data/documents/token.d.mts

@@ -1,68 +1,994 @@
-import type { DeepPartial, InexactPartial } from "../../../../types/utils.d.mts";
+import type DataModel from "#common/abstract/data.mjs";
+import type { AnyArray, AnyObject, InexactPartial, InterfaceToObject, Merge, NullishProps } from "#utils";
+import type { documents } from "../../../client-esm/client.d.mts";
 import type Document from "../../../common/abstract/document.d.mts";
-import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
-import type { SchemaField } from "../../../common/data/fields.d.mts";
+import type { DataSchema, SchemaField } from "../../../common/data/fields.d.mts";
+import type { fields, LightData, TextureData } from "../../../common/data/module.d.mts";
+import type { ActorDeltaField } from "../../../common/documents/token.d.mts";
 import type BaseToken from "../../../common/documents/token.d.mts";
 
 declare global {
   namespace TokenDocument {
-    type Metadata = Document.MetadataFor<TokenDocument>;
+    /**
+     * The document's name.
+     */
+    type Name = "Token";
+
+    /**
+     * The arguments to construct the document.
+     */
+    type ConstructorArgs = Document.ConstructorParameters<CreateData, Parent>;
+
+    /**
+     * The documents embedded within `TokenDocument`.
+     */
+    type Hierarchy = Readonly<Document.HierarchyOf<Schema>>;
+
+    /**
+     * The implementation of the `TokenDocument` document instance configured through `CONFIG.Token.documentClass` in Foundry and
+     * {@link DocumentClassConfig | `DocumentClassConfig`} or {@link ConfiguredTokenDocument | `fvtt-types/configuration/ConfiguredTokenDocument`} in fvtt-types.
+     */
+    type Implementation = Document.ImplementationFor<Name>;
+
+    /**
+     * The implementation of the `TokenDocument` document configured through `CONFIG.Token.documentClass` in Foundry and
+     * {@link DocumentClassConfig | `DocumentClassConfig`} in fvtt-types.
+     */
+    type ImplementationClass = Document.ImplementationClassFor<Name>;
+
+    /**
+     * A document's metadata is special information about the document ranging anywhere from its name,
+     * whether it's indexed, or to the permissions a user has over it.
+     */
+    interface Metadata
+      extends Merge<
+        Document.Metadata.Default,
+        Readonly<{
+          name: "Token";
+          collection: "tokens";
+          label: string;
+          labelPlural: string;
+          isEmbedded: true;
+          embedded: TokenDocument.Metadata.Embedded;
+          permissions: TokenDocument.Metadata.Permissions;
+          schemaVersion: string;
+        }>
+      > {}
+
+    namespace Metadata {
+      /**
+       * The embedded metadata
+       */
+      interface Embedded {
+        ActorDelta: "delta";
+      }
+
+      /**
+       * The permissions for whether a certain user can create, update, or delete this document.
+       */
+      interface Permissions {
+        create: "TOKEN_CREATE";
+        update(
+          user: User.Internal.Implementation,
+          doc: TokenDocument.Implementation,
+          data: BaseToken.UpdateData,
+        ): boolean;
+        delete: "TOKEN_DELETE";
+      }
+    }
+
+    /**
+     * A document's parent is something that can contain it.
+     * For example an `Item` can be contained by an `Actor` which makes `Actor` one of its possible parents.
+     */
+    type Parent = Scene.Implementation | null;
+
+    /**
+     * A document's direct descendants are documents that are contained directly within its schema.
+     * This is a union of all such instances, or never if the document doesn't have any descendants.
+     */
+    type DirectDescendant = ActorDelta.Stored;
+
+    /**
+     * A document's direct descendants are documents that are contained directly within its schema.
+     * This is a union of all such classes, or never if the document doesn't have any descendants.
+     */
+    type DirectDescendantClass = ActorDelta.ImplementationClass;
+
+    /**
+     * A document's descendants are any documents that are contained within, either within its schema
+     * or its descendant's schemas.
+     * This is a union of all such instances, or never if the document doesn't have any descendants.
+     */
+    type Descendant = DirectDescendant | ActorDelta.Descendant;
+
+    /**
+     * A document's descendants are any child documents, grandchild documents, etc.
+     * This is a union of all classes, or never if the document doesn't have any descendants.
+     */
+    type DescendantClass = DirectDescendantClass | ActorDelta.DescendantClass;
+
+    /**
+     * Types of `CompendiumCollection` this document might be contained in.
+     * Note that `this.pack` will always return a string; this is the type for `game.packs.get(this.pack)`
+     */
+    type Pack = CompendiumCollection.ForDocument<"Token">;
+
+    /**
+     * An embedded document is a document contained in another.
+     * For example an `Item` can be contained by an `Actor` which means `Item` can be embedded in `Actor`.
+     *
+     * If this is `never` it is because there are no embeddable documents (or there's a bug!).
+     */
+    type Embedded = Document.ImplementationFor<Embedded.Name>;
+
+    namespace Embedded {
+      /**
+       * An embedded document is a document contained in another.
+       * For example an `Item` can be contained by an `Actor` which means `Item` can be embedded in `Actor`.
+       *
+       * If this is `never` it is because there are no embeddable documents (or there's a bug!).
+       */
+      type Name = keyof Metadata.Embedded;
+
+      /**
+       * Gets the collection name for an embedded document.
+       */
+      type CollectionNameOf<CollectionName extends Embedded.CollectionName> = Document.Embedded.CollectionNameFor<
+        Metadata.Embedded,
+        CollectionName
+      >;
+
+      /**
+       * Gets the collection document for an embedded document.
+       */
+      // TODO(LukeAbby): There's a circularity. Should be `Document.Embedded.CollectionDocumentFor<Metadata.Embedded, CollectionName>`
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      type DocumentFor<CollectionName extends Embedded.CollectionName> = Document.Any;
+
+      /**
+       * Gets the collection for an embedded document.
+       */
+      type CollectionFor<CollectionName extends Embedded.CollectionName> = Document.Embedded.CollectionFor<
+        // TODO(LukeAbby): This should be `TokenDocument.Implementation` but this causes a circularity.
+        Document.Any,
+        Metadata.Embedded,
+        CollectionName
+      >;
+
+      /**
+       * A valid name to refer to a collection embedded in this document. For example an `Actor`
+       * has the key `"items"` which contains `Item` instance which would make both `"Item" | "Items"`
+       * valid keys (amongst others).
+       */
+      type CollectionName = Document.Embedded.CollectionName<Metadata.Embedded>;
+    }
+
+    /**
+     * The name of the world or embedded collection this document can find itself in.
+     * For example an `Item` is always going to be inside a collection with a key of `items`.
+     * This is a fixed string per document type and is primarily useful for {@link ClientDocumentMixin | `Descendant Document Events`}.
+     */
+    type ParentCollectionName = Metadata["collection"];
+
+    /**
+     * The world collection that contains this document type. Will be `never` if none exists.
+     */
+    type CollectionClass = never;
+
+    /**
+     * The world collection that contains this document type. Will be `never` if none exists.
+     */
+    type Collection = never;
+
+    /**
+     * An instance of `TokenDocument` that comes from the database but failed validation meaning that
+     * its `system` and `_source` could theoretically be anything.
+     */
+    interface Invalid extends Document.Invalid<TokenDocument.Implementation> {}
+
+    /**
+     * An instance of `TokenDocument` that comes from the database.
+     */
+    interface Stored extends Document.Stored<TokenDocument.Implementation> {}
+
+    /**
+     * The data put in {@link TokenDocument._source | `TokenDocument#_source`}. This data is what was
+     * persisted to the database and therefore it must be valid JSON.
+     *
+     * For example a {@link fields.SetField | `SetField`} is persisted to the database as an array
+     * but initialized as a {@link Set | `Set`}.
+     */
+    interface Source extends fields.SchemaField.SourceData<Schema> {}
+
+    /**
+     * @deprecated {@link TokenDocument.Source | `TokenDocument.Source`}
+     */
+    type PersistedData = Source;
+
+    /**
+     * The data necessary to create a document. Used in places like {@link TokenDocument.create | `TokenDocument.create`}
+     * and {@link TokenDocument | `new TokenDocument(...)`}.
+     *
+     * For example a {@link fields.SetField | `SetField`} can accept any {@link Iterable | `Iterable`}
+     * with the right values. This means you can pass a `Set` instance, an array of values,
+     * a generator, or any other iterable.
+     */
+    interface CreateData extends fields.SchemaField.CreateData<Schema> {}
+
+    /**
+     * The data after a {@link foundry.abstract.Document | `Document`} has been initialized, for example
+     * {@link TokenDocument.name | `TokenDocument#name`}.
+     *
+     * This is data transformed from {@link TokenDocument.Source | `TokenDocument.Source`} and turned into more
+     * convenient runtime data structures. For example a {@link fields.SetField | `SetField`} is
+     * persisted to the database as an array of values but at runtime it is a `Set` instance.
+     */
+    interface InitializedData extends fields.SchemaField.InitializedData<Schema> {}
+
+    /**
+     * The data used to update a document, for example {@link TokenDocument.update | `TokenDocument#update`}.
+     * It is a distinct type from {@link TokenDocument.CreateData | `DeepPartial<TokenDocument.CreateData>`} because
+     * it has different rules for `null` and `undefined`.
+     */
+    interface UpdateData extends fields.SchemaField.UpdateData<Schema> {}
 
-    type ConfiguredClass = Document.ConfiguredClassForName<"Token">;
-    type ConfiguredInstance = Document.ConfiguredInstanceForName<"Token">;
+    /**
+     * Schema definition shared by {@link foundry.data.PrototypeToken | `PrototypeToken`}.
+     * Foundry technically implements this through deletion, but it's easier for us to do by extension as there are field
+     * option overrides (e.g `textSearch` on `name`) that cause type issues otherwise.
+     */
+    interface SharedProtoSchema extends DataSchema {
+      // `name` omitted here because, while it is not in the list of omitted fields for `PrototypeToken`, it's `textSearch: true` in the base schema, but overridden to `false` in `PrototypeToken`
 
-    type ObjectClass = Document.ConfiguredObjectClassForName<"Token">;
-    type ObjectInstance = Document.ConfiguredObjectInstanceForName<"Token">;
+      /**
+       * The display mode of the Token nameplate, from CONST.TOKEN_DISPLAY_MODES
+       * @defaultValue `CONST.TOKEN_DISPLAY_MODES.NONE`
+       */
+      displayName: fields.NumberField<
+        {
+          required: true;
+          initial: typeof CONST.TOKEN_DISPLAY_MODES.NONE;
+          choices: CONST.TOKEN_DISPLAY_MODES[];
+          validationError: "must be a value in CONST.TOKEN_DISPLAY_MODES";
+        },
+        // FIXME: Without these overrides, the branded type from `choices` is not respected, and the field types as `number`
+        CONST.TOKEN_DISPLAY_MODES | null | undefined,
+        CONST.TOKEN_DISPLAY_MODES,
+        CONST.TOKEN_DISPLAY_MODES
+      >;
 
-    /* eslint-disable @typescript-eslint/no-empty-object-type */
-    interface DatabaseOperations
-      extends DocumentDatabaseOperations<
-        TokenDocument,
-        {},
+      /**
+       * Does this Token uniquely represent a singular Actor, or is it one of many?
+       * @defaultValue `false`
+       */
+      actorLink: fields.BooleanField;
+
+      appendNumber: fields.BooleanField;
+
+      prependAdjective: fields.BooleanField;
+
+      /**
+       * The width of the Token in grid units
+       * @defaultValue `1`
+       */
+      width: fields.NumberField<{ nullable: false; positive: true; initial: 1; step: 0.5; label: "Width" }>;
+
+      /**
+       * The height of the Token in grid units
+       * @defaultValue `1`
+       */
+      height: fields.NumberField<{ nullable: false; positive: true; initial: 1; step: 0.5; label: "Height" }>;
+
+      /**
+       * The token's texture on the canvas.
+       */
+      texture: TextureData<{
+        initial: {
+          src: () => typeof BaseToken.DEFAULT_ICON;
+          anchorX: 0.5;
+          anchorY: 0.5;
+          fit: "contain";
+          alphaThreshold: 0.75;
+        };
+        wildcard: true;
+      }>;
+
+      /**
+       * @defaultValue `CONST.TOKEN_HEXAGONAL_SHAPES.ELLIPSE_1`
+       */
+      hexagonalShape: fields.NumberField<
         {
-          previousActorId: string | null;
-          animate: boolean;
-          _priorRegions: Record<string, string[]>;
-          _priorPosition: Record<string, { x: number; y: number; elevation: number }>;
-          teleport: boolean;
-          forced: boolean;
+          initial: typeof CONST.TOKEN_HEXAGONAL_SHAPES.ELLIPSE_1;
+          choices: CONST.TOKEN_HEXAGONAL_SHAPES[];
         },
-        {}
-      > {}
-    /* eslint-enable @typescript-eslint/no-empty-object-type */
+        // FIXME: Without these overrides, the branded type from `choices` is not respected, and the field types as `number`
+        CONST.TOKEN_HEXAGONAL_SHAPES | null | undefined,
+        CONST.TOKEN_HEXAGONAL_SHAPES,
+        CONST.TOKEN_HEXAGONAL_SHAPES
+      >;
+
+      /**
+       * Prevent the Token image from visually rotating?
+       * @defaultValue `false`
+       */
+      lockRotation: fields.BooleanField;
+
+      /**
+       * The rotation of the Token in degrees, from 0 to 360. A value of 0 represents a southward-facing Token.
+       * @defaultValue `0`
+       */
+      rotation: fields.AngleField;
+
+      /**
+       * The opacity of the token image
+       * @defaultValue `1`
+       */
+      alpha: fields.AlphaField;
+
+      /**
+       * A displayed Token disposition from CONST.TOKEN_DISPOSITIONS
+       * @defaultValue `CONST.TOKEN_DISPOSITIONS.HOSTILE` (`-1`)
+       */
+      disposition: fields.NumberField<
+        {
+          required: true;
+          choices: CONST.TOKEN_DISPOSITIONS[];
+          initial: typeof CONST.TOKEN_DISPOSITIONS.HOSTILE;
+          validationError: "must be a value in CONST.TOKEN_DISPOSITIONS";
+        },
+        // FIXME: Without these overrides, the branded type from `choices` is not respected, and the field types as `number`
+        CONST.TOKEN_DISPOSITIONS | null | undefined,
+        CONST.TOKEN_DISPOSITIONS,
+        CONST.TOKEN_DISPOSITIONS
+      >;
+
+      /**
+       * The display mode of Token resource bars, from CONST.TOKEN_DISPLAY_MODES
+       * @defaultValue `CONST.TOKEN_DISPLAY_MODES.NONE`
+       */
+      displayBars: fields.NumberField<
+        {
+          required: true;
+          choices: CONST.TOKEN_DISPLAY_MODES[];
+          initial: typeof CONST.TOKEN_DISPLAY_MODES.NONE;
+          validationError: "must be a value in CONST.TOKEN_DISPLAY_MODES";
+        },
+        // FIXME: Without these overrides, the branded type from `choices` is not respected, and the field types as `number`
+        CONST.TOKEN_DISPLAY_MODES | null | undefined,
+        CONST.TOKEN_DISPLAY_MODES,
+        CONST.TOKEN_DISPLAY_MODES
+      >;
+
+      /**
+       * The configuration of the Token's primary resource bar
+       * @defaultValue see property
+       */
+      bar1: fields.SchemaField<{
+        /**
+         * The attribute path within the Token's Actor data which should be displayed
+         * @defaultValue `game?.system.primaryTokenAttribute || null`
+         */
+        attribute: fields.StringField<{
+          required: true;
+          nullable: true;
+          blank: false;
+          initial: () => string | null;
+        }>;
+      }>;
+
+      /**
+       * The configuration of the Token's secondary resource bar
+       * @defaultValue see property
+       */
+      bar2: fields.SchemaField<{
+        /**
+         * The attribute path within the Token's Actor data which should be displayed
+         * @defaultValue `game?.system.secondaryTokenAttribute || null`
+         */
+        attribute: fields.StringField<{
+          required: true;
+          nullable: true;
+          blank: false;
+          initial: () => string | null;
+        }>;
+      }>;
+
+      /**
+       * Configuration of the light source that this Token emits
+       * @defaultValue see {@link LightData | `LightData`}
+       */
+      light: fields.EmbeddedDataField<typeof LightData>;
+
+      /**
+       * Configuration of sight and vision properties for the Token
+       * @defaultValue see properties
+       * @privateRemarks Foundry has this split out into its own `@typedef TokenSightData`, but it's never
+       * referenced outside `@typedef TokenData`, so no need for a separate interface
+       */
+      sight: fields.SchemaField<{
+        /**
+         * Should vision computation and rendering be active for this Token?
+         * @defaultValue `true`, when the token's sight range is greater than 0
+         */
+        enabled: fields.BooleanField<{ initial: (data: unknown) => boolean }>;
+
+        /**
+         * How far in distance units the Token can see without the aid of a light source
+         * @defaultValue `0`
+         */
+        range: fields.NumberField<{ required: true; nullable: true; min: 0; step: 0.01; initial: 0 }>;
+
+        /**
+         * An angle at which the Token can see relative to their direction of facing
+         * @defaultValue `360`
+         */
+        angle: fields.AngleField<{ initial: 360; normalize: false }>;
+
+        /**
+         * The vision mode which is used to render the appearance of the visible area
+         * @defaultValue `"basic"`
+         */
+        visionMode: fields.StringField<{
+          required: true;
+          blank: false;
+          initial: "basic";
+          label: "TOKEN.VisionMode";
+          hint: "TOKEN.VisionModeHint";
+        }>;
+
+        /**
+         * A special color which applies a hue to the visible area
+         * @defaultValue `null`
+         */
+        color: fields.ColorField<{ label: "TOKEN.VisionColor" }>;
+
+        /**
+         * A degree of attenuation which gradually fades the edges of the visible area
+         * @defaultValue `0.1`
+         */
+        attenuation: fields.AlphaField<{
+          initial: 0.1;
+          label: "TOKEN.VisionAttenuation";
+          hint: "TOKEN.VisionAttenuationHint";
+        }>;
+
+        /**
+         * An advanced customization for the perceived brightness of the visible area
+         * @defaultValue `0`
+         */
+        brightness: fields.NumberField<{
+          required: true;
+          nullable: false;
+          initial: 0;
+          min: -1;
+          max: 1;
+          label: "TOKEN.VisionBrightness";
+          hint: "TOKEN.VisionBrightnessHint";
+        }>;
+
+        /**
+         * An advanced customization of color saturation within the visible area
+         * @defaultValue `0`
+         */
+        saturation: fields.NumberField<{
+          required: true;
+          nullable: false;
+          initial: 0;
+          min: -1;
+          max: 1;
+          label: "TOKEN.VisionSaturation";
+          hint: "TOKEN.VisionSaturationHint";
+        }>;
+
+        /**
+         * An advanced customization for contrast within the visible area
+         * @defaultValue `0`
+         */
+        contrast: fields.NumberField<{
+          required: true;
+          nullable: false;
+          initial: 0;
+          min: -1;
+          max: 1;
+          label: "TOKEN.VisionContrast";
+          hint: "TOKEN.VisionContrastHint";
+        }>;
+      }>;
+
+      /**
+       * An array of detection modes which are available to this Token
+       * @defaultValue `[]`
+       * @remarks The validation function is a `BaseToken.#validateDetectionModes` reference, which throws if there's a duplicate mode ID
+       */
+      detectionModes: fields.ArrayField<
+        fields.SchemaField<{
+          /**
+           * The id of the detection mode, a key from CONFIG.Canvas.detectionModes
+           * @defaultValue `""`
+           */
+          id: fields.StringField;
+
+          /**
+           * Whether or not this detection mode is presently enabled
+           * @defaultValue `true`
+           */
+          enabled: fields.BooleanField<{ initial: true }>;
+
+          /**
+           * The maximum range in distance units at which this mode can detect targets
+           * @defaultValue `null`
+           */
+          range: fields.NumberField<{ required: true; min: 0; step: 0.01 }>;
+        }>,
+        {
+          validate: () => void;
+        }
+      >;
+
+      /**
+       * @defaultValue see properties
+       */
+      occludable: fields.SchemaField<{
+        /**
+         * @defaultValue `0`
+         */
+        radius: fields.NumberField<{ nullable: false; min: 0; step: 0.01; initial: 0 }>;
+      }>;
+
+      /**
+       * @defaultValue see properties
+       */
+      ring: fields.SchemaField<{
+        /**
+         * @defaultValue `false`
+         */
+        enabled: fields.BooleanField;
+
+        /**
+         * @defaultValue see properties
+         */
+        colors: fields.SchemaField<{
+          /**
+           * @defaultValue `null`
+           */
+          ring: fields.ColorField;
+
+          /**
+           * @defaultValue `null`
+           */
+          background: fields.ColorField;
+        }>;
+
+        /**
+         * @defaultValue `1`
+         */
+        effects: fields.NumberField<{ initial: 1; min: 0; max: 0x7fffff; integer: true }>;
+
+        /**
+         * @defaultValue see properties
+         */
+        subject: fields.SchemaField<{
+          /**
+           * @defaultValue `1`
+           */
+          scale: fields.NumberField<{ initial: 1; min: 0.5 }>;
+
+          /**
+           * @defaultValue `null`
+           */
+          texture: fields.FilePathField<{ categories: ["IMAGE"] }>;
+        }>;
+      }>;
+
+      /**
+       * @remarks Foundry marked `@internal`
+       */
+      _regions: fields.ArrayField<fields.ForeignDocumentField<typeof documents.BaseRegion, { idOnly: true }>>;
+
+      /**
+       * An object of optional key/value flags
+       * @defaultValue `{}`
+       */
+      flags: fields.ObjectField.FlagsField<Name, InterfaceToObject<CoreFlags>>;
+    }
+
+    /**
+     * The schema for {@link TokenDocument | `TokenDocument`}. This is the source of truth for how an TokenDocument document
+     * must be structured.
+     *
+     * Foundry uses this schema to validate the structure of the {@link TokenDocument | `TokenDocument`}. For example
+     * a {@link fields.StringField | `StringField`} will enforce that the value is a string. More
+     * complex fields like {@link fields.SetField | `SetField`} goes through various conversions
+     * starting as an array in the database, initialized as a set, and allows updates with any
+     * iterable.
+     */
+    interface Schema extends SharedProtoSchema {
+      /**
+       * The Token _id which uniquely identifies it within its parent Scene
+       * @defaultValue `null`
+       */
+      _id: fields.DocumentIdField;
+
+      /**
+       * The name used to describe the Token
+       * @defaultValue `""`
+       */
+      name: fields.StringField<{ required: true; blank: true; textSearch: true }>;
+
+      /**
+       * The _id of an Actor document which this Token represents
+       * @defaultValue `null`
+       */
+      actorId: fields.ForeignDocumentField<typeof documents.BaseActor, { idOnly: true }>;
+
+      /**
+       * The ActorDelta embedded document which stores the differences between this
+       * token and the base actor it represents.
+       */
+      delta: ActorDeltaField<typeof documents.BaseActor>;
+
+      /**
+       * The x-coordinate of the top-left corner of the Token
+       * @defaultValue `0`
+       */
+      x: fields.NumberField<{ required: true; integer: true; nullable: false; initial: 0; label: "XCoord" }>;
+
+      /**
+       * The y-coordinate of the top-left corner of the Token
+       * @defaultValue `0`
+       */
+      y: fields.NumberField<{ required: true; integer: true; nullable: false; initial: 0; label: "YCoord" }>;
+
+      /**
+       * The vertical elevation of the Token, in distance units
+       * @defaultValue `0`
+       */
+      elevation: fields.NumberField<{ required: true; nullable: false; initial: 0 }>;
+
+      /**
+       * Is the Token currently locked? A locked token cannot be moved or rotated via
+       * standard keyboard or mouse interaction.
+       * @defaultValue `false`
+       */
+      locked: fields.BooleanField;
+
+      /**
+       * The z-index of this token relative to other siblings
+       * @defaultValue `0`
+       */
+      sort: fields.NumberField<{ required: true; integer: true; nullable: false; initial: 0 }>;
+
+      /**
+       * Is the Token currently hidden from player view?
+       * @defaultValue `false`
+       */
+      hidden: fields.BooleanField;
+    }
+
+    namespace Database {
+      /** Options passed along in Get operations for TokenDocuments */
+      interface Get extends foundry.abstract.types.DatabaseGetOperation<TokenDocument.Parent> {}
+
+      /** Options passed along in Create operations for TokenDocuments */
+      interface Create<Temporary extends boolean | undefined = boolean | undefined>
+        extends foundry.abstract.types.DatabaseCreateOperation<
+          TokenDocument.CreateData,
+          TokenDocument.Parent,
+          Temporary
+        > {}
+
+      /** Options passed along in Delete operations for TokenDocuments */
+      interface Delete extends foundry.abstract.types.DatabaseDeleteOperation<TokenDocument.Parent> {}
+
+      /** Options passed along in Update operations for TokenDocuments */
+      interface Update
+        extends foundry.abstract.types.DatabaseUpdateOperation<TokenDocument.UpdateData, TokenDocument.Parent> {
+        previousActorId?: string | null;
+        animate?: boolean;
+        _priorRegions?: Record<string, string[]>;
+        _priorPosition?: Record<string, { x: number; y: number; elevation: number }>;
+        teleport?: boolean;
+        forced?: boolean;
+        // TODO: Type this accurately when going over the Token placeable
+        animation: AnyObject;
+      }
+
+      /** Operation for {@link TokenDocument.createDocuments | `TokenDocument.createDocuments`} */
+      interface CreateDocumentsOperation<Temporary extends boolean | undefined>
+        extends Document.Database.CreateOperation<TokenDocument.Database.Create<Temporary>> {}
+
+      /** Operation for {@link TokenDocument.updateDocuments | `TokenDocument.updateDocuments`} */
+      interface UpdateDocumentsOperation
+        extends Document.Database.UpdateDocumentsOperation<TokenDocument.Database.Update> {}
+
+      /** Operation for {@link TokenDocument.deleteDocuments | `TokenDocument.deleteDocuments`} */
+      interface DeleteDocumentsOperation
+        extends Document.Database.DeleteDocumentsOperation<TokenDocument.Database.Delete> {}
+
+      /** Operation for {@link TokenDocument.create | `TokenDocument.create`} */
+      interface CreateOperation<Temporary extends boolean | undefined>
+        extends Document.Database.CreateOperation<TokenDocument.Database.Create<Temporary>> {}
+
+      /** Operation for {@link TokenDocument.update | `TokenDocument#update`} */
+      interface UpdateOperation extends Document.Database.UpdateOperation<Update> {}
+
+      interface DeleteOperation extends Document.Database.DeleteOperation<Delete> {}
+
+      /** Options for {@link TokenDocument.get | `TokenDocument.get`} */
+      interface GetOptions extends Document.Database.GetOptions {}
+
+      /** Options for {@link TokenDocument._preCreate | `TokenDocument#_preCreate`} */
+      interface PreCreateOptions extends Document.Database.PreCreateOptions<Create> {}
+
+      /** Options for {@link TokenDocument._onCreate | `TokenDocument#_onCreate`} */
+      interface OnCreateOptions extends Document.Database.CreateOptions<Create> {}
+
+      /** Operation for {@link TokenDocument._preCreateOperation | `TokenDocument._preCreateOperation`} */
+      interface PreCreateOperation extends Document.Database.PreCreateOperationStatic<TokenDocument.Database.Create> {}
+
+      /** Operation for {@link TokenDocument._onCreateOperation | `TokenDocument#_onCreateOperation`} */
+      interface OnCreateOperation extends TokenDocument.Database.Create {}
+
+      /** Options for {@link TokenDocument._preUpdate | `TokenDocument#_preUpdate`} */
+      interface PreUpdateOptions extends Document.Database.PreUpdateOptions<Update> {}
+
+      /** Options for {@link TokenDocument._onUpdate | `TokenDocument#_onUpdate`} */
+      interface OnUpdateOptions extends Document.Database.UpdateOptions<Update> {}
+
+      /** Operation for {@link TokenDocument._preUpdateOperation | `TokenDocument._preUpdateOperation`} */
+      interface PreUpdateOperation extends TokenDocument.Database.Update {}
+
+      /** Operation for {@link TokenDocument._onUpdateOperation | `TokenDocument._preUpdateOperation`} */
+      interface OnUpdateOperation extends TokenDocument.Database.Update {}
+
+      /** Options for {@link TokenDocument._preDelete | `TokenDocument#_preDelete`} */
+      interface PreDeleteOptions extends Document.Database.PreDeleteOperationInstance<Delete> {}
+
+      /** Options for {@link TokenDocument._onDelete | `TokenDocument#_onDelete`} */
+      interface OnDeleteOptions extends Document.Database.DeleteOptions<Delete> {}
+
+      /** Options for {@link TokenDocument._preDeleteOperation | `TokenDocument#_preDeleteOperation`} */
+      interface PreDeleteOperation extends TokenDocument.Database.Delete {}
+
+      /** Options for {@link TokenDocument._onDeleteOperation | `TokenDocument#_onDeleteOperation`} */
+      interface OnDeleteOperation extends TokenDocument.Database.Delete {}
+
+      /** Context for {@link TokenDocument._onDeleteOperation | `TokenDocument._onDeleteOperation`} */
+      interface OnDeleteDocumentsContext extends Document.ModificationContext<TokenDocument.Parent> {}
+
+      /** Context for {@link TokenDocument._onCreateDocuments | `TokenDocument._onCreateDocuments`} */
+      interface OnCreateDocumentsContext extends Document.ModificationContext<TokenDocument.Parent> {}
+
+      /** Context for {@link TokenDocument._onUpdateDocuments | `TokenDocument._onUpdateDocuments`} */
+      interface OnUpdateDocumentsContext extends Document.ModificationContext<TokenDocument.Parent> {}
+
+      /**
+       * Options for {@link TokenDocument._preCreateDescendantDocuments | `TokenDocument#_preCreateDescendantDocuments`}
+       * and {@link TokenDocument._onCreateDescendantDocuments | `TokenDocument#_onCreateDescendantDocuments`}
+       */
+      interface CreateOptions extends Document.Database.CreateOptions<TokenDocument.Database.Create> {}
+
+      /**
+       * Options for {@link TokenDocument._preUpdateDescendantDocuments | `TokenDocument#_preUpdateDescendantDocuments`}
+       * and {@link TokenDocument._onUpdateDescendantDocuments | `TokenDocument#_onUpdateDescendantDocuments`}
+       */
+      interface UpdateOptions extends Document.Database.UpdateOptions<TokenDocument.Database.Update> {}
+
+      /**
+       * Options for {@link TokenDocument._preDeleteDescendantDocuments | `TokenDocument#_preDeleteDescendantDocuments`}
+       * and {@link TokenDocument._onDeleteDescendantDocuments | `TokenDocument#_onDeleteDescendantDocuments`}
+       */
+      interface DeleteOptions extends Document.Database.DeleteOptions<TokenDocument.Database.Delete> {}
+    }
+
+    /**
+     * The flags that are available for this document in the form `{ [scope: string]: { [key: string]: unknown } }`.
+     */
+    interface Flags extends Document.ConfiguredFlagsForName<Name> {}
+
+    namespace Flags {
+      /**
+       * The valid scopes for the flags on this document e.g. `"core"` or `"dnd5e"`.
+       */
+      type Scope = Document.FlagKeyOf<Flags>;
+
+      /**
+       * The valid keys for a certain scope for example if the scope is "core" then a valid key may be `"sheetLock"` or `"viewMode"`.
+       */
+      type Key<Scope extends Flags.Scope> = Document.FlagKeyOf<Document.FlagGetKey<Flags, Scope>>;
+
+      /**
+       * Gets the type of a particular flag given a `Scope` and a `Key`.
+       */
+      type Get<Scope extends Flags.Scope, Key extends Flags.Key<Scope>> = Document.GetFlag<Name, Scope, Key>;
+    }
+
+    interface CoreFlags {
+      core?: {
+        /** @remarks If provided, will be used for any light animations emanating from this token */
+        animationSeed?: number;
+
+        /** @remarks If true, and texture.src is a video, it will jump to a random timestamp every time the token is drawn */
+        randomizeVideo?: boolean;
+      };
+    }
+
+    type PreCreateDescendantDocumentsArgs =
+      | Document.PreCreateDescendantDocumentsArgs<
+          TokenDocument.Stored,
+          TokenDocument.DirectDescendant,
+          TokenDocument.Metadata.Embedded
+        >
+      | ActorDelta.PreCreateDescendantDocumentsArgs;
+
+    type OnCreateDescendantDocumentsArgs =
+      | Document.OnCreateDescendantDocumentsArgs<
+          TokenDocument.Stored,
+          TokenDocument.DirectDescendant,
+          TokenDocument.Metadata.Embedded
+        >
+      | ActorDelta.OnCreateDescendantDocumentsArgs;
+
+    type PreUpdateDescendantDocumentsArgs =
+      | Document.PreUpdateDescendantDocumentsArgs<
+          TokenDocument.Stored,
+          TokenDocument.DirectDescendant,
+          TokenDocument.Metadata.Embedded
+        >
+      | ActorDelta.PreUpdateDescendantDocumentsArgs;
+
+    type OnUpdateDescendantDocumentsArgs =
+      | Document.OnUpdateDescendantDocumentsArgs<
+          TokenDocument.Stored,
+          TokenDocument.DirectDescendant,
+          TokenDocument.Metadata.Embedded
+        >
+      | ActorDelta.OnUpdateDescendantDocumentsArgs;
 
-    // Helpful aliases
-    type ConstructorData = BaseToken.ConstructorData;
-    type UpdateData = BaseToken.UpdateData;
-    type Schema = BaseToken.Schema;
-    type Source = BaseToken.Source;
+    type PreDeleteDescendantDocumentsArgs =
+      | Document.PreDeleteDescendantDocumentsArgs<
+          TokenDocument.Stored,
+          TokenDocument.DirectDescendant,
+          TokenDocument.Metadata.Embedded
+        >
+      | ActorDelta.PreDeleteDescendantDocumentsArgs;
+
+    type OnDeleteDescendantDocumentsArgs =
+      | Document.OnDeleteDescendantDocumentsArgs<
+          TokenDocument.Stored,
+          TokenDocument.DirectDescendant,
+          TokenDocument.Metadata.Embedded
+        >
+      | ActorDelta.OnDeleteDescendantDocumentsArgs;
+
+    // The getBarAttribute monkeypatch is simply inside the data model definition at `src/foundry/common/data/data.d.mts`
+
+    interface PseudoActorCollection extends foundry.utils.Collection<Actor.Implementation> {
+      documentClass: Actor.ImplementationClass;
+    }
+
+    /** @internal */
+    type _GetBarAttributeOptions = NullishProps<{
+      /**
+       * An alternative attribute path to get instead of the default one
+       * @defaultValue `this[barName]?.attribute`
+       * @remarks If the above default returns falsey, the {@link TokenDocument.getBarAttribute | `TokenDocument#getBarAttribute`}
+       * call returns `null`
+       */
+      alternative: string;
+    }>;
+
+    interface GetBarAttributeOptions extends _GetBarAttributeOptions {}
+
+    type GetBarAttributeReturn = SingleAttributeBar | ObjectAttributeBar | null;
+
+    /** @internal */
+    type _CreateCombatantsOptions = NullishProps<{
+      /**
+       * A specific Combat instance which should be modified. If undefined,
+       * the current active combat will be modified if one exists. Otherwise, a new
+       * Combat encounter will be created if the requesting user is a Gamemaster.
+       * @defaultValue `game.combats.viewed`
+       */
+      combat: Combat.Implementation;
+    }>;
+
+    interface CreateCombatantsOptions extends _CreateCombatantsOptions {}
+
+    interface DeleteCombatantsOptions extends _CreateCombatantsOptions {}
+
+    type TrackedAttributesSubject =
+      | DataModel.Any
+      | DataModel.AnyConstructor
+      | SchemaField.Any
+      | Actor.SubType
+      | AnyObject
+      | AnyArray;
+
+    interface TrackedAttributesDescription {
+      /** A list of property path arrays to attributes with both a value and a max property. */
+      bar: string[][];
+      /** A list of property path arrays to attributes that have only a value property. */
+      value: string[][];
+    }
+
+    interface TrackedAttributesChoice {
+      group: string;
+      value: string;
+      label: string;
+    }
+
+    interface ToggleCombatantOptions extends InexactPartial<TokenDocument.CreateCombatantsOptions> {
+      /**
+       * Require this token to be an active Combatant or to be removed.
+       * Otherwise, the current combat state of the Token is toggled.
+       */
+      active: boolean;
+    }
+
+    type GetEmbeddedCollectionName = Embedded.CollectionName | "Actor" | "Item" | "ActiveEffect";
+
+    // TODO(LukeAbby): Simplified for now to prevent circularities. The correct implementation would
+    // be this:
+    // | (Name extends "Actor" ? globalThis.Collection<Actor.Implementation> : never)
+    // | (Name extends "Item" ? globalThis.Collection<Item.Implementation> : never)
+    // | (Name extends "ActiveEffect" ? globalThis.Collection<ActiveEffect.Implementation> : never)
+    // | (Name extends Embedded.CollectionName ? Embedded.CollectionFor<Name> : never);
+    type GetEmbeddedCollectionResult<_Name extends GetEmbeddedCollectionName> = Collection.Any;
+
+    /**
+     * @deprecated {@link TokenDocument.Database | `TokenDocument.DatabaseOperation`}
+     */
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    interface DatabaseOperations extends Document.Database.Operations<TokenDocument.Implementation> {}
+
+    /**
+     * @deprecated {@link TokenDocument.CreateData | `TokenDocument.CreateData`}
+     */
+    interface ConstructorData extends TokenDocument.CreateData {}
+
+    /**
+     * @deprecated {@link TokenDocument.implementation | `TokenDocument.ImplementationClass`}
+     */
+    type ConfiguredClass = ImplementationClass;
+
+    /**
+     * @deprecated {@link TokenDocument.Implementation | `TokenDocument.Implementation`}
+     */
+    type ConfiguredInstance = Implementation;
   }
 
   /**
    * The client-side Token document which extends the common BaseToken model.
    *
-   * @see {@link Scene}               The Scene document type which contains Token embedded documents
-   * @see {@link TokenConfig}      The Token configuration application
+   * @see {@link Scene | `Scene`}               The Scene document type which contains Token embedded documents
+   * @see {@link TokenConfig | `TokenConfig`}      The Token configuration application
    */
   class TokenDocument extends CanvasDocumentMixin(foundry.documents.BaseToken) {
-    static override metadata: TokenDocument.Metadata;
+    /**
+     * @param data    - Initial data from which to construct the `TokenDocument`
+     * @param context - Construction context options
+     */
+    constructor(...args: TokenDocument.ConstructorArgs);
 
     /**
      * A singleton collection which holds a reference to the synthetic token actor by its base actor's ID.
+     * @remarks Initialized by an IIFE that makes a base-model {@linkcode Collection} and adds a `documentClass` property to it
      */
-    actors(): Collection<Actor.ConfiguredInstance>;
+    actors: TokenDocument.PseudoActorCollection;
 
     /**
      * A lazily evaluated reference to the Actor this Token modifies.
      * If actorLink is true, then the document is the primary Actor document.
      * Otherwise the Actor document is a synthetic (ephemeral) document constructed using the Token's ActorDelta.
      */
-    get actor(): Actor.ConfiguredInstance | null;
+    get actor(): Actor.Implementation | null;
 
     /**
      * A reference to the base, World-level Actor this token represents.
      */
-    get baseActor(): Actor | undefined;
+    get baseActor(): Actor.Implementation | undefined;
 
     /**
      * An indicator for whether or not the current User has full control over this Token document.
@@ -83,7 +1009,7 @@ declare global {
     /**
      * Return a reference to a Combatant that represents this Token, if one is present in the current encounter.
      */
-    get combatant(): Combatant.ConfiguredInstance | null;
+    get combatant(): Combatant.Implementation | null;
 
     /**
      * An indicator for whether or not this Token is currently involved in the active combat encounter.
@@ -92,12 +1018,11 @@ declare global {
 
     /**
      * The Regions this Token is currently in.
-     * @privateRemarks TODO: Change Set<any> to Set<RegionDocuments> when RegionDocuments are implemented
      */
-    regions: Set<any> | null;
+    regions: Set<RegionDocument.Implementation> | null;
 
-    // TODO: Same as `DataModel._initialize`
-    protected override _initialize(options?: any): void;
+    // options: not null (parameter default only)
+    protected override _initialize(options?: Document.InitializeOptions): void;
 
     override prepareBaseData(): void;
 
@@ -121,15 +1046,11 @@ declare global {
      * @param barName     - The named bar to retrieve the attribute for
      * @returns The attribute displayed on the Token bar, if any
      */
+    // options: not null (destructured)
     getBarAttribute(
       barName: string,
-      options?: InexactPartial<{
-        /**
-         * An alternative attribute path to get instead of the default one
-         */
-        alternative: string;
-      }>,
-    ): SingleAttributeBar | ObjectAttributeBar | null;
+      options?: TokenDocument.GetBarAttributeOptions,
+    ): TokenDocument.GetBarAttributeReturn;
 
     /**
      * Test whether a Token has a specific status effect.
@@ -140,63 +1061,59 @@ declare global {
 
     /**
      * Add or remove this Token from a Combat encounter.
-     * @param options - Additional options passed to TokenDocument.createCombatants or
-     *                  TokenDocument.deleteCombatants
-     *                  Default: `{}`
-     *  @returns Is this Token now an active Combatant?
-     */
-    toggleCombatant({
-      active,
-      ...options
-    }?: InexactPartial<
-      CreateCombatantOptions & {
-        /**
-         * Require this token to be an active Combatant or to be removed.
-         * Otherwise, the current combat state of the Token is toggled.
-         */
-        active: boolean;
-      }
-    >): Promise<boolean>;
+     * @param options - Additional options passed to TokenDocument.createCombatants or TokenDocument.deleteCombatants (default: `{}`)
+     * @returns Is this Token now an active Combatant?
+     */
+    // options: not null (destructured)
+    toggleCombatant(options?: TokenDocument.ToggleCombatantOptions): Promise<boolean>;
 
     /**
      * Create or remove Combatants for an array of provided Token objects.
      * @param tokens  - The tokens which should be added to the Combat
-     * @param options - Options which modify the toggle operation
-     *                  Default: `{}`
+     * @param options - Options which modify the toggle operation (default: `{}`)
      * @returns An array of created Combatant documents
      */
-    static createCombatants(tokens: TokenDocument[], options?: CreateCombatantOptions): Promise<Combatant[]>;
+    // options: not null (destructured)
+    static createCombatants(
+      tokens: TokenDocument.Implementation[],
+      options?: TokenDocument.CreateCombatantsOptions,
+    ): Promise<Combatant.Implementation[]>;
 
     /**
      * Remove Combatants for the array of provided Tokens.
      * @param tokens  - The tokens which should removed from the Combat
-     * @param options - Options which modify the operation
-     *                  Default: `{}`
+     * @param options - Options which modify the operation (default: `{}`)
      * @returns An array of deleted Combatant documents
      */
-    static deleteCombatants(tokens: TokenDocument[], options?: CreateCombatantOptions): Promise<Combatant[]>;
+    // options: not null (destructured)
+    static deleteCombatants(
+      tokens: TokenDocument.Implementation[],
+      options?: TokenDocument.DeleteCombatantsOptions,
+    ): Promise<Combatant.Implementation[]>;
 
     /**
      * Convenience method to change a token vision mode.
      * @param visionMode - The vision mode to apply to this token.
-     * @param defaults   - If the vision mode should be updated with its defaults.
-     *                     Default = `true`
+     * @param defaults   - If the vision mode should be updated with its defaults. (default: `true`)
      */
     updateVisionMode(
-      visionMode: typeof CONFIG.Canvas.visionModes,
-      defaults?: boolean,
-    ): Promise<ReturnType<this["update"]>>;
-
-    override getEmbeddedCollection<DocType extends Document.Type>(
-      embeddedName: DocType,
-    ): Collection<Document.ConfiguredInstanceForName<DocType>>;
+      visionMode: VisionMode.ConfiguredModes,
+      defaults?: boolean | null,
+    ): Promise<TokenDocument.Implementation | undefined>;
 
     /**
-     * @privateRemarks _onCreate, _preUpdate, _onUpdate, _onDelete, preCreateOperation, _preUpdateOperation, _onCreateOperation,
-     * _onUpdateOperation, _onDeleteOperation, _preCreateDescendantDocuments, _preUpdateDescendantDocuments, _preDeleteDescendantDocuments,
-     * _onUpdateDescendantDocuments, and _onDeleteDescendantDocuments are all overridden but with no signature changes.
-     * For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
+     * @remarks Foundry specifically overrides this method such that unlinked `TokenDocument` instances
+     * handles 3 extra cases:
+     * - Passing `"Actor"` returns `this.actors`.
+     * - Passing `"Item"` returns `this.actor.items`.
+     * - Passing `"ActiveEffect"` returns `this.actor.effects`.
      */
+    override getEmbeddedCollection<EmbeddedName extends TokenDocument.GetEmbeddedCollectionName>(
+      embeddedName: EmbeddedName,
+    ): TokenDocument.GetEmbeddedCollectionResult<EmbeddedName>;
+
+    // _onCreate, _preUpdate, _onUpdate, _onDelete, preCreateOperation, _preUpdateOperation, _onCreateOperation,
+    // _onUpdateOperation, _onDeleteOperation are all overridden but with no signature changes from their definition in BaseToken.
 
     /**
      * Is to Token document updated such that the Regions the Token is contained in may change?
@@ -204,18 +1121,122 @@ declare global {
      * @param changes - The changes.
      * @returns Could this Token update change Region containment?
      */
+    protected _couldRegionsChange(changes: TokenDocument.UpdateData): boolean;
+
+    /**
+     * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
+     * this method must be overridden like so:
+     * ```typescript
+     * class SwadeActorDelta extends ActorDelta {
+     *   protected override _preCreateDescendantDocuments(...args: ActorDelta.PreCreateDescendantDocumentsArgs) {
+     *     super._preCreateDescendantDocuments(...args);
+     *
+     *     const [parent, collection, data, options, userId] = args;
+     *     if (collection === "items") {
+     *         options; // Will be narrowed.
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    protected override _preCreateDescendantDocuments(...args: ActorDelta.PreCreateDescendantDocumentsArgs): void;
+
+    /**
+     * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
+     * this method must be overridden like so:
+     * ```typescript
+     * class GurpsActorDelta extends ActorDelta {
+     *   protected override _onCreateDescendantDocuments(...args: ActorDelta.OnCreateDescendantDocumentsArgs) {
+     *     super._onCreateDescendantDocuments(...args);
+     *
+     *     const [parent, collection, documents, data, options, userId] = args;
+     *     if (collection === "items") {
+     *         options; // Will be narrowed.
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    protected override _onCreateDescendantDocuments(...args: ActorDelta.OnCreateDescendantDocumentsArgs): void;
 
-    protected _couldRegionsChange(
-      changes: SchemaField.InnerAssignmentType<foundry.documents.BaseToken.Schema>,
-    ): boolean;
+    /**
+     * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
+     * this method must be overridden like so:
+     * ```typescript
+     * class LancerActorDelta extends ActorDelta {
+     *   protected override _preUpdateDescendantDocuments(...args: ActorDelta.OnUpdateDescendantDocuments) {
+     *     super._preUpdateDescendantDocuments(...args);
+     *
+     *     const [parent, collection, changes, options, userId] = args;
+     *     if (collection === "tokens") {
+     *         options; // Will be narrowed.
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    protected override _preUpdateDescendantDocuments(...args: ActorDelta.PreUpdateDescendantDocumentsArgs): void;
+
+    /**
+     * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
+     * this method must be overridden like so:
+     * ```typescript
+     * class Ptr2eTokenDocument extends TokenDocument {
+     *   protected override _onUpdateDescendantDocuments(...args: TokenDocument.OnUpdateDescendantDocumentsArgs) {
+     *     super._onUpdateDescendantDocuments(...args);
+     *
+     *     const [parent, collection, documents, changes, options, userId] = args;
+     *     if (collection === "items") {
+     *         options; // Will be narrowed.
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    protected override _onUpdateDescendantDocuments(...args: TokenDocument.OnUpdateDescendantDocumentsArgs): void;
+
+    /**
+     * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
+     * this method must be overridden like so:
+     * ```typescript
+     * class KultTokenDocument extends TokenDocument {
+     *   protected override _preDeleteDescendantDocuments(...args: TokenDocument.PreDeleteDescendantDocumentsArgs) {
+     *     super._preDeleteDescendantDocuments(...args);
+     *
+     *     const [parent, collection, ids, options, userId] = args;
+     *     if (collection === "items") {
+     *         options; // Will be narrowed.
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    protected override _preDeleteDescendantDocuments(...args: TokenDocument.PreDeleteDescendantDocumentsArgs): void;
+
+    /**
+     * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
+     * this method must be overridden like so:
+     * ```typescript
+     * class BladesTokenDocument extends TokenDocument {
+     *   protected override _onDeleteDescendantDocuments(...args: TokenDocument.OnUpdateDescendantDocuments) {
+     *     super._onDeleteDescendantDocuments(...args);
+     *
+     *     const [parent, collection, documents, ids, options, userId] = args;
+     *     if (collection === "tokens") {
+     *         options; // Will be narrowed.
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    protected override _onDeleteDescendantDocuments(...args: TokenDocument.OnDeleteDescendantDocumentsArgs): void;
 
     /**
      * When the base Actor for a TokenDocument changes, we may need to update its Actor instance
+     * @remarks After updating the synthetic actor, forwards to {@link TokenDocument._onRelatedUpdate | `TokenDocument#_onRelatedUpdate`}
      */
-    protected _onUpdateBaseActor(
-      update?: DeepPartial<Actor.ConfiguredInstance["_source"]>,
-      options?: Document.OnUpdateOptions<"Actor">,
-    ): void;
+    // update, options: not null (parameter defaults only)
+    protected _onUpdateBaseActor(update?: Actor.UpdateData, options?: Actor.Database.OnUpdateOperation): void;
 
     /**
      * Whenever the token's actor delta changes, or the base actor changes, perform associated refreshes.
@@ -223,68 +1244,81 @@ declare global {
      * @param options - The options provided to the update.
      */
     protected _onRelatedUpdate(
-      update?: DeepPartial<Actor.ConfiguredInstance["_source"]>,
-      /** @privateRemarks foundry calls this field operation
+      update?: Actor.UpdateData | ActorDelta.UpdateData,
+      /**
+       * @privateRemarks foundry calls this field operation
        * but it's being passed options (and then ignores them)
        */
-      operation?: Document.OnUpdateOptions<"Actor">,
+      operation?: Actor.Database.OnUpdateOperation,
     ): void;
 
     /**
      * Get an Array of attribute choices which could be tracked for Actors in the Combat Tracker
+     * @param data  - The object to explore for attributes, or an Actor type.
      * @param _path - (default: `[]`)
      */
     // TODO: There's some very complex handling for non-datamodel Actor system implementations if we want
+    // _path: not null (parameter default only)
     static getTrackedAttributes(
-      data?: Actor.ConfiguredInstance["system"],
+      data?: TokenDocument.TrackedAttributesSubject | null,
       _path?: string[],
-    ): TrackedAttributesDescription;
+    ): TokenDocument.TrackedAttributesDescription;
 
     /**
      * Retrieve an Array of attribute choices from a plain object.
      * @param schema - The schema to explore for attributes.
      */
-    protected static _getTrackedAttributesFromObject(data: object, _path?: string[]): TrackedAttributesDescription;
+    // _path: not null (parameter default only)
+    protected static _getTrackedAttributesFromObject(
+      data: AnyObject | AnyArray,
+      _path?: string[],
+    ): TokenDocument.TrackedAttributesDescription;
 
     /**
      * Retrieve an Array of attribute choices from a SchemaField.
      * @param schema - The schema to explore for attributes.
      */
     protected static _getTrackedAttributesFromSchema(
-      schema: foundry.data.fields.SchemaField.Any,
+      schema: SchemaField.Any,
       _path?: string[],
-    ): TrackedAttributesDescription;
+    ): TokenDocument.TrackedAttributesDescription;
 
     /**
      * Retrieve any configured attributes for a given Actor type.
      * @param type - The Actor type.
+     * @remarks If `type` is invalid, or doesn't have an entry in {@linkcode CONFIG.Actor.trackableAttributes}, returns the merged
+     * tracked attributes of all types. If no types have any configured, returns `void`
      */
-    static _getConfiguredTrackedAttributes(type: string): TrackedAttributesDescription | void;
+    static _getConfiguredTrackedAttributes(
+      type?: Actor.SubType | null,
+    ): TokenDocument.TrackedAttributesDescription | void;
 
     /**
      * Inspect the Actor data model and identify the set of attributes which could be used for a Token Bar
-     * @param attributes - The tracked attributes which can be chosen from
+     * @param attributes - The tracked attributes which can be chosen from (default: `this.getTrackedAttributes()`)
      * @returns A nested object of attribute choices to display
      */
-    static getTrackedAttributeChoices(attributes?: TrackedAttributesDescription): Record<string, string[]>;
+    static getTrackedAttributeChoices(
+      attributes?: TokenDocument.TrackedAttributesDescription | null,
+    ): TokenDocument.TrackedAttributesChoice[];
 
     /**
-     * @deprecated since v11
+     * @deprecated since v11, no specified end
      * @remarks `"TokenDocument#getActor has been deprecated. Please use the`
      * `TokenDocument#actor getter to retrieve the Actor instance that the TokenDocument represents, or use`
      * `TokenDocument#delta#apply to generate a new synthetic Actor instance."`
      */
-    getActor(): Actor.ConfiguredInstance;
+    getActor(): Actor.Implementation;
 
     /**
-     * @deprecated since v11
+     * @deprecated since v11, until v13
+     * @remarks "You are accessing `TokenDocument#actorData` which is deprecated. Source data may be retrieved via
+     * {@link TokenDocument.delta | `TokenDocument#delta`} but all modifications/access should be done via the
+     * synthetic Actor at {@link TokenDocument.actor | `TokenDocument#actor`} if possible."
      */
-    get actorData(): this["delta"]["_source"];
+    get actorData(): ActorDelta.Source;
 
-    /**
-     * @deprecated since v11
-     */
-    set actorData(actorData: this["delta"]["_source"]);
+    set actorData(actorData: ActorDelta.CreateData);
 
     /**
      * A helper function to toggle a status effect which includes an Active Effect template
@@ -293,31 +1327,61 @@ declare global {
      *                     (default: `{}`)
      * @returns Whether the Active Effect is now on or off
      * @deprecated since v12
-     * @remarks `TokenDocument#toggleActiveEffect is deprecated in favor of Actor#toggleStatusEffect"`
+     * @remarks "`TokenDocument#toggleActiveEffect` is deprecated in favor of {@link Actor.toggleStatusEffect | `Actor#toggleStatusEffect`}"
+     */
+    // options: not null (destructured)
+    toggleActiveEffect(effectData: CONFIG.StatusEffect, options?: Actor.ToggleStatusEffectOptions): Promise<boolean>;
+
+    /*
+     * After this point these are not really overridden methods.
+     * They are here because Foundry's documents are complex and have lots of edge cases.
+     * There are DRY ways of representing this but this ends up being harder to understand
+     * for end users extending these functions, especially for static methods. There are also a
+     * number of methods that don't make sense to call directly on `Document` like `createDocuments`,
+     * as there is no data that can safely construct every possible document. Finally keeping definitions
+     * separate like this helps against circularities.
      */
-    toggleActiveEffect(
-      effectData: CONFIG.StatusEffect,
-      options?: InexactPartial<ToggleActiveEffectOptions> | undefined,
-    ): Promise<boolean>;
-  }
 
-  // The getBarAttribute monkeypatch is simply inside the data model definition at `src\foundry\common\data\data.d.mts`
+    // ClientDocument overrides
 
-  interface TrackedAttributesDescription {
-    /** A list of property path arrays to attributes with both a value and a max property. */
-    bar: string[][];
-    /** A list of property path arrays to attributes that have only a value property. */
-    value: string[][];
-  }
+    // context: not null (destructured)
+    static override defaultName(
+      context?: Document.DefaultNameContext<"Token", NonNullable<TokenDocument.Parent>>,
+    ): string;
 
-  interface CreateCombatantOptions {
-    /**
-     * A specific Combat instance which should be modified. If undefined,
-     * the current active combat will be modified if one exists. Otherwise, a new
-     * Combat encounter will be created if the requesting user is a Gamemaster.
-     */
-    combat?: Combat | undefined;
+    /** @remarks `context.parent` is required as creation requires one */
+    static override createDialog(
+      data: Document.CreateDialogData<TokenDocument.CreateData> | undefined,
+      context: Document.CreateDialogContext<"Token", NonNullable<TokenDocument.Parent>>,
+    ): Promise<TokenDocument.Stored | null | undefined>;
+
+    // options: not null (parameter default only)
+    static override fromDropData(
+      data: Document.DropData<TokenDocument.Implementation>,
+      options?: AnyObject,
+    ): Promise<TokenDocument.Implementation | undefined>;
+
+    static override fromImport(
+      source: TokenDocument.Source,
+      context?: Document.FromImportContext<TokenDocument.Parent> | null,
+    ): Promise<TokenDocument.Implementation>;
+
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
+
+    // TODO: The deprecated Embedded Document Operations
+
+    #TokenDocument: true;
   }
+
+  /**
+   * @deprecated {@link TokenDocument.TrackedAttributesDescription | `TokenDocument.TrackedAttributesDescription`}
+   */
+  type TrackedAttributesDescription = TokenDocument.TrackedAttributesDescription;
+
+  /**
+   * @deprecated {@link TokenDocument.CreateCombatantsOptions | `TokenDocument.CreateCombatantOptions`}
+   */
+  type CreateCombatantOptions = TokenDocument.CreateCombatantsOptions;
 }
 
 interface SingleAttributeBar {
@@ -334,19 +1398,3 @@ interface ObjectAttributeBar {
   max: number;
   editable: boolean;
 }
-
-interface ToggleActiveEffectOptions {
-  /**
-   * Should the Active Effect icon be displayed as an overlay on the token?
-   * @defaultValue `false`
-   */
-  overlay: boolean;
-
-  /** Force a certain active state for the effect. */
-  active: boolean;
-}
-
-/**
- * @deprecated See {@link CONFIG.StatusEffect}
- */
-export type StatusEffect = CONFIG.StatusEffect;