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

package/src/foundry/client/pixi/placeables/token.d.mts

@@ -1,341 +1,172 @@
-import type { RequiredProps } from "../../../../types/utils.d.mts";
+import type {
+  Coalesce,
+  DeepPartial,
+  FixedInstanceType,
+  HandleEmptyObject,
+  InexactPartial,
+  IntentionalPartial,
+  NullishProps,
+  RequiredProps,
+} from "fvtt-types/utils";
 import type { ConfiguredObjectClassOrDefault } from "../../config.d.mts";
+import BaseToken = foundry.documents.BaseToken;
+import sources = foundry.canvas.sources;
 
 declare global {
-  namespace Token {
-    type ConfiguredClass = ConfiguredObjectClassOrDefault<typeof Token>;
-    type ConfiguredInstance = InstanceType<ConfiguredClass>;
-
-    interface RenderFlags extends PlaceableObject.RenderFlags {
-      redrawEffects: boolean;
-
-      refreshSize: boolean;
-
-      refreshPosition: boolean;
-
-      refreshElevation: boolean;
-
-      refreshVisibility: boolean;
-
-      refreshEffects: boolean;
-
-      refreshMesh: boolean;
-
-      refreshShader: boolean;
-
-      refreshBars: boolean;
-
-      refreshNameplate: boolean;
-
-      refreshBorder: boolean;
-
-      refreshTarget: boolean;
-    }
-
-    interface ReticuleOptions {
-      /**
-       * The amount of margin between the targeting arrows and the token's bounding box, expressed as a fraction of an arrow's size.
-       * @defaultValue `0`
-       */
-      margin?: number;
-
-      /**
-       * The alpha value of the arrows.
-       * @defaultValue `1`
-       */
-      alpha?: number;
-
-      /**
-       * The size of the arrows as a proportion of grid size.
-       * @defaultValue `0.15`
-       */
-      size?: number;
-
-      /**
-       * The color of the arrows.
-       * @defaultValue `0xFF6400`
-       */
-      color?: number;
-
-      /** The arrows' border style configuration. */
-      border?: {
-        /**
-         * The border color.
-         * @defaultValue `0`
-         */
-        color?: number;
-
-        /**
-         * The border width.
-         * @defaultValue `2`
-         */
-        width?: number;
-      };
-    }
-
-    type SourceType = "move" | "sight" | "light" | "sound";
-
-    interface Bar {
-      attribute: string;
-    }
-
-    interface Velocity {
-      dx: number;
-      sx: number;
-      dy: number;
-      sy: number;
-    }
-
-    /** The UI frame container which depicts Token metadata and status, displayed in the ControlsLayer. */
-    // TODO: Fix globalThis.ObjectHUD #2962
-    interface ObjectHUD {
-      /** Token health bars */
-      bars?: PIXI.Container;
-
-      /** Token nameplate */
-      nameplate?: PreciseText;
-
-      /** Token elevation tooltip */
-      tooltip?: PreciseText;
-
-      /** Token status effects */
-      effects?: PIXI.Container;
-
-      /** Token target marker */
-      target?: PIXI.Graphics;
-    }
-
-    type InitializedObjectHUD = RequiredProps<ObjectHUD, "bars" | "nameplate" | "tooltip" | "effects" | "target">;
-
-    interface UpdateLightSourceOptions {
-      /**
-       * Defer updating perception to manually update it later.
-       * @defaultValue `false`
-       */
-      defer?: boolean | undefined;
-
-      /**
-       * Indicate that this light source has been deleted.
-       * @defaultValue `false`
-       */
-      deleted?: boolean | undefined;
-    }
-
-    interface UpdateVisionSourceOptions {
-      /**
-       * Defer updating perception to manually update it later.
-       * @defaultValue `false`
-       */
-      defer?: boolean | undefined;
-
-      /**
-       * Indicate that this vision source has been deleted.
-       * @defaultValue `false`
-       */
-      deleted?: boolean | undefined;
-    }
-
-    type UpdateSourceOptions = UpdateLightSourceOptions & UpdateVisionSourceOptions;
-
-    interface PlayOptions {
-      /**
-       * Should the video loop?
-       * @defaultValue `true`
-       */
-      loop?: boolean | undefined;
-
-      /**
-       * A specific timestamp between 0 and the video duration to begin playback
-       * @defaultValue `0`
-       */
-      offset?: number | undefined;
-
-      /**
-       * Desired volume level of the video's audio channel (if any)
-       * @defaultValue `0`
-       */
-      volume?: number | undefined;
-    }
-
-    interface DrawOverlayOptions {
-      src?: string | undefined;
-      tint?: number | undefined;
-    }
-
-    interface PositionOptions {
-      /**
-       * Animate the movement path
-       * @defaultValue `true`
-       */
-      animate?: boolean;
-
-      /**
-       * Automatically re-center the view if token movement goes off-screen
-       * @defaultValue `true`
-       */
-      recenter?: boolean | undefined;
-    }
-
-    interface EffectToggleOptions {
-      /**
-       * Force a certain active state for the effect
-       * @defaultValue `false`
-       */
-      active?: boolean | undefined;
-
-      /**
-       * Whether to set the effect as the overlay effect?
-       * @defaultValue `false`
-       */
-      overlay?: boolean | undefined;
-    }
-
-    interface SetTargetContext {
-      /**
-       * Assign the token as a target for a specific User
-       * @defaultValue `null`
-       */
-      user?: User.ConfiguredInstance | null | undefined;
-
-      /**
-       * Release other active targets for the same player?
-       * @defaultValue `true`
-       */
-      releaseOthers?: boolean | undefined;
-
-      /**
-       * Is this target being set as part of a group selection workflow?
-       * @defaultValue `Is this target being set as part of a group selection workflow?`
-       */
-      groupSelection?: boolean | undefined;
-    }
-
-    interface ControlOptions extends PlaceableObject.ControlOptions {
-      /** @defaultValue `false` */
-      pan?: boolean;
-    }
-  }
-
   /**
    * A Token is an implementation of PlaceableObject which represents an Actor within a viewed Scene on the game canvas.
-   * @see TokenDocument
-   * @see TokenLayer
+   * @see {@link TokenDocument | `TokenDocument`}
+   * @see {@link TokenLayer | `TokenLayer`}
    */
-  class Token extends PlaceableObject<TokenDocument.ConfiguredInstance> {
+  class Token extends PlaceableObject<TokenDocument.Implementation> {
     static override embeddedName: "Token";
 
-    static override RENDER_FLAGS: {
-      /** @defaultValue `{ propagate: ["refresh"] }` */
-      redraw: RenderFlag<Partial<Token.RenderFlags>>;
-
-      /** @defaultValue `{}` */
-      redrawEffects: RenderFlag<Partial<Token.RenderFlags>>;
-
-      /** @defaultValue `{ propagate: ["refreshState", "refreshSize", "refreshPosition", "refreshElevation", "refreshBars", "refreshNameplate", "refreshBorder", "refreshShader"], alias: true }` */
-      refresh: RenderFlag<Partial<Token.RenderFlags>>;
+    static override RENDER_FLAGS: Token.RENDER_FLAGS;
 
-      /** @defaultValue `{ propagate: ["refreshVisibility", "refreshBorder"] }` */
-      refreshState: RenderFlag<Partial<Token.RenderFlags>>;
+    // Note: This isn't a "real" override but `renderFlags` is set corresponding to the
+    // `RENDER_FLAGS` and so it has to be adjusted here.
+    renderFlags: RenderFlags<Token.RENDER_FLAGS>;
 
-      /** @defaultValue `{ propagate: ["refreshMesh", "refreshBorder", "refreshBars", "refreshPosition", "refreshTarget", "refreshEffects"] }` */
-      refreshSize: RenderFlag<Partial<Token.RenderFlags>>;
+    // fake override; super has to type as if this could be a ControlIcon, but Tokens don't use one
+    override controlIcon: null;
 
-      /** @defaultValue `{ propagate: ["refreshMesh", "refreshVisibility"] }` */
-      refreshPosition: RenderFlag<Partial<Token.RenderFlags>>;
-
-      /** @defaultValue `{ propagate: ["refreshMesh"] }` */
-      refreshElevation: RenderFlag<Partial<Token.RenderFlags>>;
-
-      /** @defaultValue `{}` */
-      refreshVisibility: RenderFlag<Partial<Token.RenderFlags>>;
+    /**
+     * The shape of this token.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to {@link Token._refreshShape | `Token#_refreshShape`} being called.     *
+     * @privateRemarks Foundry types this as possibly being `PIXI.Circle` but {@link Token.getShape | `Token#getShape`} only returns `Rectangle` or `Polygon` in v12
+     */
+    shape: PIXI.Rectangle | PIXI.Polygon | undefined;
 
-      /** @defaultValue `{}` */
-      refreshEffects: RenderFlag<Partial<Token.RenderFlags>>;
+    /**
+     * Defines the filter to use for detection.
+     * @defaultValue `null`
+     * @remarks Only set to other-than-`null` externally, in {@link CanvasVisibility.testVisibility | `CanvasVisibility#testVisibility`}
+     *
+     * Set `null` unconditionally when {@link Token.isVisible | `Token#isVisible`} is accessed
+     */
+    detectionFilter: PIXI.Filter | null;
 
-      /** @defaultValue `{}` */
-      refreshMesh: RenderFlag<Partial<Token.RenderFlags>>;
+    /**
+     * A Graphics instance which renders the border frame for this Token inside the GridLayer.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
+     * */
+    border: PIXI.Graphics | undefined;
 
-      /** @defaultValue `{}` */
-      refreshShader: RenderFlag<Partial<Token.RenderFlags>>;
+    /**
+     * The attribute bars of this Token.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
+     */
+    bars: Token.Bars | undefined;
 
-      /** @defaultValue `{}` */
-      refreshBars: RenderFlag<Partial<Token.RenderFlags>>;
+    /**
+     * The tooltip text of this Token, which contains its elevation.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
+     */
+    tooltip: PreciseText | undefined;
 
-      /** @defaultValue `{}` */
-      refreshNameplate: RenderFlag<Partial<Token.RenderFlags>>;
+    /**
+     * The target marker, which indicates that this Token is targeted by this User or others.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
+     */
+    target: PIXI.Graphics | undefined;
 
-      /** @defaultValue `{}` */
-      refreshBorder: RenderFlag<Partial<Token.RenderFlags>>;
+    /**
+     * The nameplate of this Token, which displays its name.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
+     */
+    nameplate: PreciseText | undefined;
 
-      /** @defaultValue `{}` */
-      refreshTarget: RenderFlag<Partial<Token.RenderFlags>>;
-    };
+    /**
+     * Track the set of User documents which are currently targeting this Token
+     */
+    targeted: Set<User.Stored>;
 
     /**
-     * Defines the filter to use for detection.
+     * A reference to the SpriteMesh which displays this Token in the PrimaryCanvasGroup.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
      */
-    detectionFilter?: PIXI.Filter | null;
+    mesh: PrimarySpriteMesh | undefined;
 
     /**
-     * A Graphics instance which renders the border frame for this Token inside the GridLayer.
+     * Renders the mesh of this Token with ERASE blending in the Token.
      * @defaultValue `undefined`
-     * */
-    border?: PIXI.Graphics;
+     * @remarks Only `undefined` prior to first draw
+     * @privateRemarks Foundry types as `PIXI.DisplayObject`, but its only ever set to `PIXI.Container` in v12
+     */
+    voidMesh: PIXI.Container | undefined;
 
     /**
-     * Track the set of User documents which are currently targeting this Token
+     * Renders the mesh of with the detection filter.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
+     * @privateRemarks Foundry types as `PIXI.DisplayObject`, but its only ever set to `PIXI.Container` in v12
      */
-    targeted: Set<User>;
+    detectionFilterMesh: PIXI.Container | undefined;
 
     /**
-     * A reference to the SpriteMesh which displays this Token in the PrimaryCanvasGroup.
+     * The texture of this Token, which is used by its mesh.
+     * @defaultValue `undefined`
+     * @remarks `undefined` prior to first draw or after {@link Token._destroy | `Token#_destroy`} is called
      */
-    mesh: PrimarySpriteMesh;
+    texture: PIXI.Texture | undefined;
 
     /**
      * A reference to the VisionSource object which defines this vision source area of effect
+     * @defaultValue `undefined`
+     * @remarks `undefined` prior to first draw or after {@link Token._destroy | `Token#_destroy`} is called, or
+     * {@link Token.initializeVisionSource | `Token#initializeVisionSource`} is called with `{deleted: true}`
      */
-    vision: foundry.canvas.sources.PointVisionSource.Any;
+    vision: sources.PointVisionSource.ConfiguredInstance | undefined;
 
     /**
      * A reference to the LightSource object which defines this light source area of effect
+     * @defaultValue `undefined`
+     * @remarks `undefined` prior to first draw or after {@link Token._destroy | `Token#_destroy`} is called, or
+     * {@link Token.initializeLightSource | `Token#initializeLightSource`} is called with `{deleted: true}`
+     *
+     * Whether this is a LightSource or a DarknessSource depends on `this.document.light.negative`
      */
-    light: foundry.canvas.sources.PointLightSource;
+    light: sources.PointLightSource.ConfiguredInstance | sources.PointDarknessSource.ConfiguredInstance | undefined;
 
     /**
-     * A reference to an animation that is currently in progress for this Token, if any
-     * @internal
+     * The current animations of this Token.
      */
-    protected _animation: Promise<number> | null;
+    get animationContexts(): Map<string, Token.AnimationContext>;
 
     /**
-     * A convenient reference to the Actor object associated with the Token embedded document.
+     * A TokenRing instance which is used if this Token applies a dynamic ring.
+     * This property is null if the Token does not use a dynamic ring.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw. Set `null` if `token.document.ring.enabled` is `false`.
      */
-    get actor(): this["document"]["actor"];
+    get ring(): foundry.canvas.tokens.TokenRing.ConfiguredInstance | null | undefined;
 
     /**
-     * A convenient reference for whether the current User has full control over the Token document.
+     * A convenience boolean to test whether the Token is using a dynamic ring.
      */
-    get owner(): boolean;
-
-    get isOwner(): boolean;
+    get hasDynamicRing(): boolean;
 
     /**
-     * A boolean flag for whether the current game User has observer permission for the Token
+     * A convenient reference to the Actor object associated with the Token embedded document.
      */
-    get observer(): boolean;
+    get actor(): TokenDocument.Implementation["actor"];
 
     /**
-     * Is the HUD display active for this token?
+     * A boolean flag for whether the current game User has observer permission for the Token
      */
-    get hasActiveHUD(): boolean;
+    get observer(): boolean;
 
     /**
      * Convenience access to the token's nameplate string
-     * @remarks
-     * This is actually a getter that returns data.name
      */
-    readonly name: string;
+    get name(): string;
 
     override get bounds(): PIXI.Rectangle;
 
@@ -352,17 +183,21 @@ declare global {
     /**
      * The Token's current central position
      */
-    get center(): Canvas.Point;
+    get center(): PIXI.Point;
 
     /**
      * The Token's central position, adjusted in each direction by one or zero pixels to offset it relative to walls.
      */
-    getMovementAdjustedPoint(point: Canvas.Point, offset?: { offsetX: number; offsetY: number }): Canvas.Point;
+    // offsets: not null (destructured)
+    getMovementAdjustedPoint(point: Canvas.Point, offsets?: Token.GetMovementAdjustedPointOffsets): Canvas.Point;
 
     /**
      * The HTML source element for the primary Tile texture
+     * @privateRemarks Foundry types this as `HTMLImageElement | HTMLVideoElement`, but this just
+     * returns `this.texture?.baseTexture.resource.source`, which could be any of `PIXI.ImageSource`,
+     * and returns `ImageBitmap`, not `HTMLImageElement`, for static images.
      */
-    get sourceElement(): HTMLImageElement | HTMLVideoElement | undefined;
+    get sourceElement(): PIXI.ImageSource | undefined;
 
     override get sourceId(): string;
 
@@ -379,7 +214,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.Stored;
 
     /**
      * An indicator for whether the Token is currently targeted by the active game User
@@ -389,7 +224,7 @@ declare global {
     /**
      * Return a reference to the detection modes array.
      */
-    get detectionModes(): Array<DetectionMode>;
+    get detectionModes(): TokenDocument.Implementation["detectionModes"];
 
     /**
      * Determine whether the Token is visible to the calling user's perspective.
@@ -398,12 +233,16 @@ declare global {
      * Controlled tokens are always visible.
      * All Tokens are visible to a GM user if no Token is controlled.
      *
-     * @see {@link CanvasVisibility#testVisibility}
+     * @see {@link CanvasVisibility.testVisibility | `CanvasVisibility#testVisibility`}
      */
     get isVisible(): boolean;
 
     /**
      * The animation name used for Token movement
+     * @defaultValue
+     * ```js
+     * `${this.objectId}.animate`
+     * ```
      */
     get animationName(): string;
 
@@ -413,7 +252,19 @@ declare global {
     get hasSight(): boolean;
 
     /**
-     * Test whether the Token emits light (or darkness) at any radius
+     * Does this Token actively emit light given its properties and the current darkness level of the Scene?
+     */
+    protected _isLightSource(): boolean;
+
+    /**
+     * Does this Ambient Light actively emit darkness given
+     * its properties and the current darkness level of the Scene?
+     */
+    get emitsDarkness(): boolean;
+
+    /**
+     * Does this Ambient Light actively emit light given
+     * its properties and the current darkness level of the Scene?
      */
     get emitsLight(): boolean;
 
@@ -432,6 +283,16 @@ declare global {
      */
     get brightRadius(): number;
 
+    /**
+     * The maximum radius in pixels of the light field
+     */
+    get radius(): number;
+
+    /**
+     * The range of this token's light perception in pixels.
+     */
+    get lightPerceptionRange(): number;
+
     /**
      * Translate the token's vision range in units into a radius in pixels.
      */
@@ -442,37 +303,44 @@ declare global {
      */
     get optimalSightRange(): number;
 
-    // TODO(LukeAbby): This override appears to fail because it creates a circular dependency that tsc can't resolve for some reason. Bug report?
-    // `Token` is a `PlaceableObject` if it properly extends `PlaceableObject` however `clone` is a proper override of `PlaceableObject.clone` only if its return value extends `PlaceableObject`.
-    // This creates a loop of checking `Token` against `PlaceableObject`.
-    // override clone(): Token;
-
     /**
-     * Update the light and vision source objects associated with this Token
+     * Update the light and vision source objects associated with this Token.
      * @param options - Options which configure how perception sources are updated
      */
-    updateSource(options?: Token.UpdateSourceOptions): void;
+    // options: not null (destructured)
+    initializeSources(options?: Token.InitializeSourcesOptions): void;
 
     /**
      * Update an emitted light source associated with this Token.
-     * @param options - (default `{}`)
      */
-    updateLightSource(options?: Token.UpdateLightSourceOptions): void;
+    // options: not null (destructured)
+    initializeLightSource(options?: Token.InitializeSourcesOptions): void;
 
     /**
-     * Update an Token vision source associated for this token.
-     * @param options - Options which affect how the vision source is updated
-     *                  (default: `{}`)
+     * Get the light source data.
      */
-    updateVisionSource(options?: Token.UpdateVisionSourceOptions): void;
+    protected _getLightSourceData(): Token.LightSourceData;
 
     /**
-     * Test whether this Token is a viable vision source for the current User
-     * @internal
+     * Update the VisionSource instance associated with this Token.
      */
-    protected _isVisionSource(): boolean;
+    // options: not null (destructured)
+    initializeVisionSource(options?: Token.InitializeSourcesOptions): void;
 
-    override render(renderer: PIXI.Renderer): void;
+    /**
+     * Returns a record of blinding state.
+     */
+    protected _getVisionBlindedStates(): Token.BlindedStates;
+
+    /**
+     * Get the vision source data.
+     */
+    protected _getVisionSourceData(): Token.VisionSourceData;
+
+    /**
+     * Test whether this Token is a viable vision source for the current User.
+     */
+    protected _isVisionSource(): boolean;
 
     /**
      * Render the bound mesh detection filter.
@@ -482,17 +350,58 @@ declare global {
 
     override clear(): void;
 
-    protected override _destroy(options?: PIXI.IDestroyOptions | boolean): void;
+    protected override _destroy(options: PIXI.IDestroyOptions | boolean | undefined): void;
 
-    protected override _draw(options?: Record<string, unknown>): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<Token.DrawOptions> | undefined): Promise<void>;
 
     protected override _applyRenderFlags(flags: Token.RenderFlags): void;
 
+    /**
+     * Refresh the token ring visuals if necessary.
+     */
+    protected _refreshRingVisuals(): void;
+
     /**
      * Refresh the visibility.
      */
     protected _refreshVisibility(): void;
 
+    /**
+     * Refresh aspects of the user interaction state.
+     * For example the border, nameplate, or bars may be shown on Hover or on Control.
+     */
+    protected _refreshState(): void;
+
+    /**
+     * Refresh the size.
+     */
+    protected _refreshSize(): void;
+
+    /**
+     * Refresh the shape.
+     */
+    protected _refreshShape(): void;
+
+    /**
+     * Refresh the rotation.
+     */
+    protected _refreshRotation(): void;
+
+    /**
+     * Refresh the position.
+     */
+    protected _refreshPosition(): void;
+
+    /**
+     * Refresh the elevation
+     */
+    protected _refreshElevation(): void;
+
+    /**
+     * Refresh the tooltip.
+     */
+    protected _refreshTooltip(): void;
+
     /**
      * Refresh the text content, position, and visibility of the Token nameplate.
      */
@@ -509,34 +418,32 @@ declare global {
     protected _refreshShader(): void;
 
     /**
-     * Draw the Token border, taking into consideration the grid type and border color
-     * @internal
+     * Refresh the border.
      */
     protected _refreshBorder(): void;
 
     /**
      * Get the hex color that should be used to render the Token border
      * @returns The hex color used to depict the border color
-     * @internal
+     * @throws If this Token's Document somehow has an invalid `disposition`
+     * @remarks Border colors set via `CONFIG.Canvas.dispositionColors`
      */
-    protected _getBorderColor(options?: {
-      /**
-       * Return a border color for this hover state, otherwise use the token's current state.
-       */
-      hover?: boolean;
-    }): number | null;
+    protected _getBorderColor(): number;
 
     /**
      * Refresh the target indicators for the Token.
      * Draw both target arrows for the primary User and indicator pips for other Users targeting the same Token.
      * @param reticule - Additional parameters to configure how the targeting reticule is drawn.
+     * @remarks Forwards `reticule` to {@link Token._drawTarget | `Token#_drawTarget`}
      */
+    // reticule: not null (destructured in _drawTarget)
     protected _refreshTarget(reticule?: Token.ReticuleOptions): void;
 
     /**
      * Draw the targeting arrows around this token.
      * @param reticule - Additional parameters to configure how the targeting reticule is drawn.
      */
+    // reticule: not null (destructured)
     protected _drawTarget(reticule?: Token.ReticuleOptions): void;
 
     /**
@@ -550,8 +457,15 @@ declare global {
      * @param number - The Bar number
      * @param bar    - The Bar container
      * @param data   - Resource data for this bar
+     * @remarks Called in {@link Token.drawBars | `Token#drawBars`} only after checking `data` for truthiness.
+     *
+     * Unconditionally returns `true`
      */
-    protected _drawBar(number: number, bar: PIXI.Graphics, data: ReturnType<TokenDocument["getBarAttribute"]>): void;
+    protected _drawBar(
+      number: number,
+      bar: PIXI.Graphics,
+      data: NonNullable<TokenDocument.GetBarAttributeReturn>,
+    ): boolean;
 
     /**
      * Return the text which should be displayed in a token's tooltip field
@@ -566,17 +480,27 @@ declare global {
     /**
      * Draw the active effects and overlay effect icons which are present upon the Token
      */
-    drawEffects(): Promise<void>;
+    drawEffects(): Promise<this>;
+
+    /**
+     * Draw the effect icons for ActiveEffect documents which apply to the Token's Actor.
+     * Called by {@link Token.drawEffects | `Token#drawEffects`}.
+     */
+    protected _drawEffects(): Promise<void>;
 
     /**
      * Draw a status effect icon
+     * @param src  - Path to a texture
+     * @param tint - A tint to apply to the returned sprite (default: `0xFFFFFF`)
+     * @remarks Returns early if `src` is falsey, but otherwise calls {@link loadTexture | `loadTexture`} with `{ fallback: "icons/svg/hazard.svg" }` and returns that
      */
-    protected _drawEffect(src: string, tint: number | null): Promise<PIXI.Sprite | undefined>;
+    protected _drawEffect(src: string, tint?: number | null): Promise<PIXI.Sprite | undefined>;
 
     /**
      * Draw the overlay effect icon
+     * @remarks Forwards both arguments to {@link Token._drawEffect | `Token#_drawEffect`}, and returns its output.
      */
-    protected _drawOverlay(src: string, tint: number | null): Promise<PIXI.Sprite>;
+    protected _drawOverlay(src: string, tint?: number | null): Promise<PIXI.Sprite | undefined>;
 
     /**
      * Refresh the display of status effects, adjusting their position for the token width and height.
@@ -588,128 +512,167 @@ declare global {
      * @param mode - The mode from CONST.TOKEN_DISPLAY_MODES
      * @returns Is the attribute viewable?
      */
-    protected _canViewMode(mode: foundry.CONST.TOKEN_DISPLAY_MODES): boolean;
+    protected _canViewMode(mode: CONST.TOKEN_DISPLAY_MODES): boolean;
 
     /**
-     * Animate changes to the appearance of the Token.
-     * Animations are performed over differences between the TokenDocument and the current Token and TokenMesh appearance.
-     * @param updateData - A record of the differential data which changed, for reference only
-     * @param options    - Options which configure the animation behavior
-     * @returns A promise which resolves once the animation is complete
+     * Override ring colors for this particular Token instance.
+     * @remarks The return gets `mergeObject`ed over {@link TokenDocument.ring | `TokenDocument#ring#colors`}
+     * in {@link foundry.canvas.tokens.TokenRing.configureVisuals | `TokenRing#configureVisuals`} and
+     * {@link foundry.canvas.tokens.TokenRing.flashColor | `TokenRing#flashColor`}. Foundry's implementation returns `{}`
      */
-    animate(
-      updateData: unknown,
-      options: {
-        /** An optional function called each animation frame */
-        ontick: (dt: number, data: CanvasAnimationData) => number;
+    getRingColors(): Token.RingColors;
 
-        /**
-         * A desired token movement speed in grid spaces per second
-         * @defaultValue `6`
-         */
-        movementSpeed: number;
+    /**
+     * Apply additional ring effects for this particular Token instance.
+     * Effects are returned as an array of integers in {@link foundry.canvas.tokens.TokenRing.effects}.
+     * @remarks Additional effects to add over and above those in `CONFIG.Token.ring.effects`. Foundry's implementation returns `[]`
+     */
+    getRingEffects(): foundry.canvas.tokens.TokenRing.EFFECTS[];
 
-        /**
-         * The animation starting attributes if different from those cached.
-         *
-         * @deprecated since v12, will be removed in v14
-         */
-        a0: unknown;
-      },
-    ): Promise<void>;
+    /**
+     * Get the animation data for the current state of the document.
+     * @returns The target animation data object
+     */
+    protected _getAnimationData(): Token.AnimationData;
 
     /**
-     * Terminate animation of this particular Token.
+     * Animate from the old to the new state of this Token.
+     * @param to      - The animation data to animate to
+     * @param options - The options that configure the animation behavior. Passed to {@link Token._getAnimationDuration | `Token#_getAnimationDuration`}.
      */
-    stopAnimation(): void;
+    // options: not null (destructured)
+    animate(to: Token.PartialAnimationData, options?: Token.AnimateOptions): Promise<void>;
 
     /**
-     * Check for collision when attempting a move to a new position
-     * @param destination - The central destination point of the attempted movement
-     * @param options     - Additional options forwarded to WallsLayer#checkCollision
-     * @returns The result of the WallsLayer#checkCollision test
+     * Get the duration of the animation.
+     * @param from    - The animation data to animate from
+     * @param to      - The animation data to animate to
+     * @param options - The options that configure the animation behavior
+     * @returns The duration of the animation in milliseconds
      */
-    checkCollision(
-      destination: Canvas.Point,
-      options: {
-        origin: Canvas.Point;
+    // options: not null (destructured)
+    protected _getAnimationDuration(
+      from: Token.AnimationDataForDuration,
+      to: Token.PartialAnimationData,
+      options?: Token.GetAnimationDurationOptions,
+    ): number;
 
-        /** @defaultValue `"move"` */
-        type: Exclude<Token.SourceType, "Sound">;
+    /**
+     * Called each animation frame.
+     * @param changed - The animation data that changed
+     * @param context - The animation context
+     */
+    protected _onAnimationUpdate(changed: Token.PartialAnimationData, context: Token.AnimationContext): void;
 
-        /** @defaultValue `"any"` */
-        mode: PointSourcePolygon.CollisionModes;
-      },
-    ): boolean;
     /**
-     * Get the center-point coordinate for a given grid position
-     * @param x - The grid x-coordinate that represents the top-left of the Token
-     * @param y - The grid y-coordinate that represents the top-left of the Token
-     * @returns The coordinate pair which represents the Token's center at position (x, y)
+     * Terminate animation of this particular Token.
      */
-    getCenter(
-      x: number,
-      y: number,
-    ): {
-      x: number;
-      y: number;
-    };
+    // options: not null (destructured)
+    stopAnimation(options?: Token.StopAnimationOptions): void;
 
     /**
-     * Set the token's position by comparing its center position vs the nearest grid vertex
-     * Return a Promise that resolves to the Token once the animation for the movement has been completed
-     * @param x       - The x-coordinate of the token center
-     * @param y       - The y-coordinate of the token center
-     * @param options - Additional options which configure the token movement
-     *                  (defaultValue: `{}`)
-     * @returns The Token after animation has completed
+     * Prepare the animation data changes: performs special handling required for animating rotation.
+     * @param from    - The animation data to animate from
+     * @param changes - The animation data changes
+     * @param context - The animation context
+     * @param options - The options that configure the animation behavior
+     * @returns The animation attributes
      */
-    setPosition(x: number, y: number, options?: Token.PositionOptions): Promise<this>;
+    // options: not null (property access)
+    protected _prepareAnimation(
+      from: Token.AnimationDataForRotation,
+      changes: Token.PartialAnimationData,
+      context: Token.AnimationContext,
+      options?: Token.PrepareAnimationOptions,
+    ): CanvasAnimation.Attribute[];
 
     /**
-     * Update the Token velocity auto-regressively, shifting increasing weight towards more recent movement
-     * Employ a magic constant chosen to minimize (effectively zero) the likelihood of trigonometric edge cases
-     * @param ray - The proposed movement ray
-     * @returns An updated velocity with directional memory
-     * @internal
+     * Check for collision when attempting a move to a new position
+     * @param destination - The central destination point of the attempted movement
+     * @param options     - Additional options forwarded to {@link WallsLayer.checkCollision | `WallsLayer#checkCollision`}
+     * @returns The result of the `WallsLayer#checkCollision` test
      */
-    protected _updateVelocity(ray: Ray): Token.Velocity;
+    // options: not null (destructured)
+    checkCollision<Mode extends PointSourcePolygon.CollisionModes | undefined = undefined>(
+      destination: Canvas.Point,
+      options?: Token.CheckCollisionOptions<Mode>,
+    ): PointSourcePolygon.TestCollision<Coalesce<Mode, "any">>;
 
     /**
-     * Set this Token as an active target for the current game User
-     * @param targeted - Is the Token now targeted?
-     *                   (default: `true`)
-     * @param context  - Additional context options
-     *                   (default `{}`)
+     * Get the width and height of the Token in pixels.
+     * @returns The size in pixels
+     */
+    getSize(): Token.Size;
+
+    /**
+     * Get the shape of this Token.
+     * @privateRemarks Foundry types this as possibly returning a `PIXI.Circle`, but it never does in practice in v12.
+     * Not reported as this has changed in v13.
      */
-    setTarget(targeted?: boolean, context?: Token.SetTargetContext): void;
+    getShape(): PIXI.Rectangle | PIXI.Polygon;
 
     /**
-     * Add or remove the currently controlled Tokens from the active combat encounter
-     * @param combat - A specific combat encounter to which this Token should be added
-     * @returns The Token which initiated the toggle
+     * Get the center point for a given position or the current position.
+     * @param position - The position to be used instead of the current position (default: `this.document`)
+     * @returns The center point
      */
-    toggleCombat(combat?: Combat.ConfiguredInstance): Promise<this>;
+    getCenterPoint(position?: Canvas.Point | null): Canvas.Point;
+
+    override getSnappedPosition(position?: Canvas.Point | null): Canvas.Point;
 
     /**
-     * Toggle an active effect by its texture path.
-     * Copy the existing Array in order to ensure the update method detects the data as changed.
+     * Test whether the Token is inside the Region.
+     * This function determines the state of {@link TokenDocument.regions | `TokenDocument#regions`} and {@link RegionDocument.tokens | `RegionDocument#tokens`}.
      *
-     * @param effect  - The texture file-path of the effect icon to toggle on the Token.
-     * @param options - Additional optional arguments which configure how the effect is handled.
-     *                  (defaultValue: `{}`)
-     * @returns Was the texture applied (true) or removed (false)
+     * Implementations of this function are restricted in the following ways:
+     *   - If the bounds (given by {@link Token.getSize | `Token#getSize`}) of the Token do not intersect the Region, then the Token is not
+     *     contained within the Region.
+     *   - If the Token is inside the Region a particular elevation, then the Token is inside the Region at any elevation
+     *     within the elevation range of the Region.
+     *
+     * If this function is overridden, then {@link Token.segmentizeRegionMovement | `Token#segmentizeRegionMovement`} must be overridden too.
+     * @param region   - The region.
+     * @param position - The (x, y) and/or elevation to use instead of the current values.
+     * @returns Is the Token inside the Region?
+     * @remarks `position` can be `{x, y}`, `{elevation}`, both, or neither. If either part is omitted, uses the document's value(s)
      */
-    toggleEffect(
-      effect: string | Parameters<TokenDocument["toggleActiveEffect"]>[0],
-      options?: Token.EffectToggleOptions,
-    ): Promise<boolean>;
+    testInsideRegion(region: Region.Object, position?: Token.TestablePosition | null): boolean;
 
     /**
-     * Toggle the visibility state of any Tokens in the currently selected set
-     * @returns A Promise which resolves to the updated Token documents
+     * Split the Token movement through the waypoints into its segments.
+     *
+     * Implementations of this function are restricted in the following ways:
+     *   - The segments must go through the waypoints.
+     *   - The *from* position matches the *to* position of the succeeding segment.
+     *   - The Token must be contained (w.r.t. {@link Token.testInsideRegion | `Token#testInsideRegion`}) within the Region
+     *     at the *from* and *to* of MOVE segments.
+     *   - The Token must be contained (w.r.t. {@link Token.testInsideRegion | `Token#testInsideRegion`}) within the Region
+     *     at the *to* position of ENTER segments.
+     *   - The Token must be contained (w.r.t. {@link Token.testInsideRegion | `Token#testInsideRegion`}) within the Region
+     *     at the *from* position of EXIT segments.
+     *   - The Token must not be contained (w.r.t. {@link Token.testInsideRegion | `Token#testInsideRegion`}) within the Region
+     *     at the *from* position of ENTER segments.
+     *   - The Token must not be contained (w.r.t. {@link Token.testInsideRegion | `Token#testInsideRegion`}) within the Region
+     *     at the *to* position of EXIT segments.
+     * @param region    - The region.
+     * @param waypoints - The waypoints of movement.
+     * @param options   - Additional options
+     * @returns The movement split into its segments.
+     */
+    // options: not null (destructured)
+    segmentizeRegionMovement(
+      region: Region.Object,
+      waypoints: Region.MovementWaypoint[],
+      options?: Region.SegmentizeMovementOptions,
+    ): Region.MovementSegment[];
+
+    /**
+     * Set this Token as an active target for the current game User
+     * @param targeted - Is the Token now targeted? (default: `true`)
+     * @param context  - Additional context options
      */
-    toggleVisibility(): Promise<TokenDocument.ConfiguredInstance[]>;
+    // targeted: not null (!== check with a boolean), context: not null (destructured)
+    setTarget(targeted?: boolean, context?: Token.TargetContext): void;
 
     /**
      * The external radius of the token in pixels.
@@ -725,97 +688,601 @@ declare global {
      */
     getLightRadius(units: number): number;
 
-    protected override _getShiftedPosition(dx: number, dy: number): { x: number; y: number };
+    protected override _getShiftedPosition(dx: number, dy: number): Canvas.Point;
+
+    // options: not null (destructured)
+    protected override _updateRotation(options?: PlaceableObject.UpdateRotationOptions): number;
+
+    // _onCreate, _onUpdate, and _onDelete are 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.
 
     /**
-     * @privateRemarks _onDelete and _onUpdate are 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.
+     * Handle changes to Token behavior when a significant status effect is applied
+     * @param statusId - The status effect ID being applied, from `CONFIG.specialStatusEffects`
+     * @param active   - Is the special status effect now active?
+     * @remarks Foundry marked `@internal`
      */
+    protected _onApplyStatusEffect(statusId: string, active: boolean): void;
 
     /**
-     * Handle changes to Token behavior when a significant status effect is applied
-     * @param statusId - The status effect ID being applied, from CONFIG.specialStatusEffects
+     * Add/Modify a filter effect on this token.
+     * @param statusId - The status effect ID being applied, from `CONFIG.specialStatusEffects`
      * @param active   - Is the special status effect now active?
-     * @internal
+     * @remarks Foundry marked `@internal`
+     */
+    protected _configureFilterEffect(statusId: string, active: boolean): void;
+
+    /**
+     * Update the filter effects depending on special status effects
+     * TODO: replace this method by something more convenient.
+     * @remarks Foundry marked `@internal`. The TODO is theirs.
+     */
+    protected _updateSpecialStatusFilterEffects(): void;
+
+    /**
+     * Remove all filter effects on this placeable.
+     * @remarks Foundry marked `@internal`
      */
-    _onApplyStatusEffect(statusId: string, active: boolean): void;
+    protected _removeAllFilterEffects(): void;
+
+    protected override _onControl(options: Token.ControlOptions): void;
 
-    protected override _onControl(options?: Token.ControlOptions): void;
+    protected override _onRelease(options: HandleEmptyObject<Token.ReleaseOptions>): void;
 
-    protected override _onRelease(
-      options: PlaceableObject.ReleaseOptions,
-    ): Promise<TokenDocument.ConfiguredInstance> | undefined;
+    protected override _overlapsSelection(rectangle: PIXI.Rectangle): boolean;
 
-    protected override _canControl(user?: User.ConfiguredInstance, event?: PIXI.FederatedEvent): boolean;
+    protected override _canControl(user: User.Implementation, event: PIXI.FederatedEvent): boolean;
 
-    protected override _canHUD(user: User.ConfiguredInstance, event?: PIXI.FederatedEvent): boolean;
+    protected override _canHUD(user: User.Implementation, event: PIXI.FederatedEvent): boolean;
 
-    protected override _canConfigure(user?: User.ConfiguredInstance, event?: PIXI.FederatedEvent): true;
+    protected override _canConfigure(user: User.Implementation, event: PIXI.FederatedEvent): true;
 
-    protected override _canHover(user?: User.ConfiguredInstance, event?: PIXI.FederatedEvent): true;
+    protected override _canHover(user: User.Implementation, event: PIXI.FederatedEvent): true;
 
-    protected override _canView(user?: User.ConfiguredInstance, event?: PIXI.FederatedEvent): boolean;
+    protected override _canView(user: User.Implementation, event: PIXI.FederatedEvent): boolean;
 
-    protected override _canDrag(user: User.ConfiguredInstance, event: PIXI.FederatedEvent): boolean;
+    protected override _canDrag(user: User.Implementation, event: PIXI.FederatedEvent): boolean;
 
-    protected override _onHoverIn(event: PIXI.FederatedEvent, options?: { hoverOutOthers?: boolean }): void;
+    // options: not null (destructured)
+    protected override _onHoverIn(event: PIXI.FederatedEvent, options?: PlaceableObject.HoverInOptions): void;
 
-    protected override _onHoverOut(event: PIXI.FederatedEvent): false | void;
+    protected override _onHoverOut(event: PIXI.FederatedEvent): void;
 
     protected override _onClickLeft(event: PIXI.FederatedEvent): void;
 
+    protected override _propagateLeftClick(event: PIXI.FederatedEvent): boolean;
+
     protected override _onClickLeft2(event?: PIXI.FederatedEvent): void;
 
     protected override _onClickRight2(event: PIXI.FederatedEvent): void;
 
-    protected override _onDragLeftDrop(event: PIXI.FederatedEvent): Promise<any>;
+    protected override _onDragLeftStart(event: PIXI.FederatedEvent): void;
+
+    protected override _prepareDragLeftDropUpdates(event: PIXI.FederatedEvent): Token.DragLeftDropUpdate[];
 
     protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
 
     protected override _onDragEnd(): void;
 
     /**
-     * @remarks Not used
+     * @deprecated since v11, will be removed in v13
+     * @remarks "`Token#updatePosition` has been deprecated without replacement as it is no longer required."
      */
-    controlIcon: null;
+    updatePosition(): void;
 
     /**
-     * @deprecated since v10, will be removed in v12
-     * @remarks `"Token#hasLimitedVisionAngle has been renamed to Token#hasLimitedSourceAngle"`
+     * @deprecated since v11, will be removed in v13
+     * @remarks "`Token#refreshHUD` is deprecated in favor of {@link RenderFlags.set | `token.renderFlags.set()`}"
      */
-    get hasLimitedVisionAngle(): boolean;
+    // options: not null (destructured)
+    refreshHUD(options?: Token.RefreshHUDOptions): void;
 
     /**
-     * @deprecated since v10, will be removed in v12
-     * @remarks `"Token#getSightOrigin has been deprecated in favor of Token#getMovementAdjustedPoint"`
+     * Update the light and vision source objects associated with this Token
+     * @param options - Options which configure how perception sources are updated
+     * @deprecated since v12, until v14
+     * @remarks "`Token#updateSource` has been deprecated in favor of {@link Token.initializeSources | `Token#initializeSources`}"
      */
-    getSightOrigin(): {
-      x: number;
-      y: number;
-    };
+    // options: not null (destructured)
+    updateSource(options?: Token.InitializeSourcesOptions): void;
 
     /**
-     * @deprecated since v10, will be removed in v12
-     * @remarks `"Token#icon has been renamed to Token#mesh."`
+     * Get the center-point coordinate for a given grid position
+     * @param x - The grid x-coordinate that represents the top-left of the Token
+     * @param y - The grid y-coordinate that represents the top-left of the Token
+     * @returns The coordinate pair which represents the Token's center at position (x, y)
+     * @deprecated since v12, until v14
+     * @remarks "`Token#getCenter(x, y)` has been deprecated in favor of {@link Token.getCenterPoint | `Token#getCenterPoint(Point)`}."
      */
-    get icon(): this["mesh"];
+    getCenter(x: number, y: number): Canvas.Point;
 
     /**
-     * @deprecated since v11, will be removed in v13
-     * @remarks `"Token#updatePosition has been deprecated without replacement as it is no longer required."`
+     * A convenient reference for whether the current User has full control over the Token document.
+     * @deprecated since v12, until v14
+     * @remarks "`Token#owner` has been deprecated. Use {@link Token.isOwner | `Token#isOwner`} instead."
      */
-    updatePosition(): void;
+    get owner(): boolean;
 
     /**
-     * @deprecated since v11, will be removed in v13
-     * @remarks "Token#refreshHUD is deprecated in favor of token.renderFlags.set()"
+     * @deprecated since v12, until v14
+     * @remarks "`Token#toggleCombat` is deprecated in favor of {@link TokenDocument.toggleCombatant | `TokenDocument#toggleCombatant`},
+     * {@link TokenDocument.createCombatants | `TokenDocument.implementation.createCombatants`}, and
+     * {@link TokenDocument.deleteCombatants | `TokenDocument.implementation.deleteCombatants`}"
+     *
+     * The `combat` parameter is unused. Creates Combatants for every Token controlled, plus the Token this was called on if it wasn't already controlled
+     */
+    toggleCombat(combat?: Combat.Implementation): Promise<Combatant.Stored[]>;
+
+    /**
+     * @deprecated since v12, until v14
+     * @remarks "`Token#toggleEffect` is deprecated in favor of {@link Actor.toggleStatusEffect | `Actor#toggleStatusEffect`}"
+     */
+    // options: not null (destructured)
+    toggleEffect(
+      effect: CONFIG.StatusEffect,
+      options?: Actor.ToggleStatusEffectOptions,
+    ): Promise<ActiveEffect.Stored | boolean | undefined>;
+
+    /**
+     * @deprecated since v12, until v14
+     * @remarks "`Token#toggleVisibility` is deprecated without replacement in favor of updating the {@link TokenDocument.hidden | `hidden` field of the `TokenDocument`} directly."
+     */
+    toggleVisibility(): Promise<TokenDocument.Stored[]>;
+
+    /**
+     * @deprecated since v12 Stable 4, until v14
+     * @remarks "`Token#_recoverFromPreview` is deprecated without replacement in favor of recovering from preview directly into {@link TokenConfig._resetPreview | `TokenConfig#_resetPreview`}."
      */
-    refreshHUD(options?: Token.ObjectHUD): void;
+    protected _recoverFromPreview(): void;
   }
 
   /**
    * A "secret" global to help debug attributes of the currently controlled Token.
    * This is only for debugging, and may be removed in the future, so it's not safe to use.
    */
-  let _token: Token.ConfiguredInstance | null;
+  let _token: Token.Object | null;
+
+  namespace Token {
+    // eslint-disable-next-line no-restricted-syntax
+    interface ObjectClass extends ConfiguredObjectClassOrDefault<typeof Token> {}
+    interface Object extends FixedInstanceType<ObjectClass> {}
+
+    /**
+     * @deprecated {@link Token.ObjectClass | `Token.ObjectClass`}
+     */
+    type ConfiguredClass = ObjectClass;
+
+    /**
+     * @deprecated {@link Token.Object | `Token.Object`}
+     */
+    type ConfiguredInstance = Object;
+
+    /**
+     * This type will permanently exist but is marked deprecated. The reason it exists is because
+     * the confusion between `Token` (the `PlaceableObject` that appears on the canvas) and
+     * `TokenDocument` (the `Document` that represents the data for a `Token`) is so common that
+     * it is useful to have a type to forward to `TokenDocument`.
+     *
+     * @deprecated {@link TokenDocument.Implementation | `TokenDocument.Implementation`}
+     */
+    type Implementation = TokenDocument.Implementation;
+
+    /**
+     * This type will permanently exist but is marked deprecated. The reason it exists is because
+     * the confusion between `Token` (the `PlaceableObject` that appears on the canvas) and
+     * `TokenDocument` (the `Document` that represents the data for a `Token`) is so common that
+     * it is useful to have a type to forward to `TokenDocument`.
+     *
+     * @deprecated {@link TokenDocument.ImplementationClass | `TokenDocument.ImplementationClass`}
+     */
+    type ImplementationClass = TokenDocument.ImplementationClass;
+
+    type Schema = BaseToken.Schema;
+    type Parent = BaseToken.Parent;
+
+    type Metadata = BaseToken.Metadata;
+
+    export import SchemaField = BaseToken.SchemaField;
+    export import ConstructorData = BaseToken.ConstructorData;
+    export import UpdateData = BaseToken.UpdateData;
+    export import Properties = BaseToken.Properties;
+    export import Source = BaseToken.Source;
+
+    interface RENDER_FLAGS {
+      /** @defaultValue `{ propagate: ["refresh"] }` */
+      redraw: RenderFlag<this, "redraw">;
+
+      /** @defaultValue `{}` */
+      redrawEffects: RenderFlag<this, "redrawEffects">;
+
+      /** @defaultValue `{ propagate: ["refreshState", "refreshTransform", "refreshMesh", "refreshNameplate", "refreshElevation", "refreshRingVisuals"], alias: true }` */
+      refresh: RenderFlag<this, "refresh">;
+
+      /** @defaultValue `{ propagate: ["refreshVisibility", "refreshTarget"] }` */
+      refreshState: RenderFlag<this, "refreshState">;
+
+      /** @defaultValue `{}` */
+      refreshVisibility: RenderFlag<this, "refreshVisibility">;
+
+      /** @defaultValue `{ propagate: ["refreshPosition", "refreshRotation", "refreshSize"], alias: true }` */
+      refreshTransform: RenderFlag<this, "refreshTransform">;
+
+      /** @defaultValue `{}` */
+      refreshPosition: RenderFlag<this, "refreshPosition">;
+
+      /** @defaultValue `{}` */
+      refreshRotation: RenderFlag<this, "refreshRotation">;
+
+      /** @defaultValue `{ propagate: ["refreshPosition", "refreshShape", "refreshBars", "refreshEffects", "refreshNameplate", "refreshTarget", "refreshTooltip"] }` */
+      refreshSize: RenderFlag<this, "refreshSize">;
+
+      /** @defaultValue `{ propagate: ["refreshTooltip"] }` */
+      refreshElevation: RenderFlag<this, "refreshElevation">;
+
+      /** @defaultValue `{}` */
+      refreshMesh: RenderFlag<this, "refreshMesh">;
+
+      /** @defaultValue `{}` */
+      refreshShader: RenderFlag<this, "refreshShader">;
+
+      /** @defaultValue `{ propagate: ["refreshVisibility", "refreshPosition", "refreshBorder", "refreshEffects"] }` */
+      refreshShape: RenderFlag<this, "refreshShape">;
+
+      /** @defaultValue `{}` */
+      refreshBorder: RenderFlag<this, "refreshBorder">;
+
+      /** @defaultValue `{}` */
+      refreshBars: RenderFlag<this, "refreshBars">;
+
+      /** @defaultValue `{}` */
+      refreshEffects: RenderFlag<this, "refreshEffects">;
+
+      /** @defaultValue `{}` */
+      refreshNameplate: RenderFlag<this, "refreshNameplate">;
+
+      /** @defaultValue `{}` */
+      refreshTarget: RenderFlag<this, "refreshTarget">;
+
+      /** @defaultValue `{}` */
+      refreshTooltip: RenderFlag<this, "refreshTooltip">;
+
+      /** @defaultValue `{}` */
+      refreshRingVisuals: RenderFlag<this, "refreshRingVisuals">;
+    }
+
+    interface RenderFlags extends RenderFlagsMixin.ToBooleanFlags<RENDER_FLAGS> {}
+
+    interface Bars extends PIXI.Container {
+      bar1: PIXI.Graphics;
+      bar2: PIXI.Graphics;
+    }
+
+    /** @internal */
+    type _GetMovementAdjustedPointOffsets = NullishProps<{
+      /** @defaultValue `this.#priorMovement.ox` */
+      offsetX: number;
+
+      /** @defaultValue `this.#priorMovement.oy` */
+      offsetY: number;
+    }>;
+
+    interface GetMovementAdjustedPointOffsets extends _GetMovementAdjustedPointOffsets {}
+
+    interface DrawOptions extends PlaceableObject.DrawOptions {}
+
+    interface RefreshOptions extends PlaceableObject.RefreshOptions {}
+
+    /** @internal */
+    type _ControlOptions = NullishProps<{
+      /** @defaultValue `false` */
+      pan: boolean;
+    }>;
+
+    interface ControlOptions extends _ControlOptions, PlaceableObject.ControlOptions {}
+
+    interface ReleaseOptions extends PlaceableObject.ReleaseOptions {}
+
+    /**
+     * @remarks {@link Token._getLightSourceData | `Token#_getLightSourceData`} calls `mergeObject` on the return of
+     * {@link foundry.data.LightData.toObject | `LightData#toObject(false)`} and the enumerated properties below and
+     * returns the result. This gets passed to {@link foundry.canvas.sources.PointLightSource.initialize | `Token#light#initialize()`},
+     * so this is a `RequiredProps<IntentionalPartial<>>` rather than a `Pick<>`
+     */
+    type LightSourceData = foundry.data.fields.SchemaField.InitializedData<foundry.data.LightData.Schema> &
+      RequiredProps<
+        IntentionalPartial<foundry.canvas.sources.PointLightSource.SourceData>,
+        "x" | "y" | "elevation" | "rotation" | "dim" | "bright" | "externalRadius" | "seed" | "preview" | "disabled"
+      >;
+
+    /**
+     * @remarks The return of {@link Token._getVisionSourceData | `Token#_getVisionSourceData`}, which gets passed
+     * to {@link foundry.canvas.sources.PointVisionSource.initialize | `Token#vision#initialize()`}, so this is a
+     * `RequiredProps<IntentionalPartial<>>` rather than a `Pick<>`
+     */
+    type VisionSourceData = RequiredProps<
+      IntentionalPartial<foundry.canvas.sources.PointVisionSource.SourceData>,
+      | "x"
+      | "y"
+      | "elevation"
+      | "rotation"
+      | "lightRadius"
+      | "externalRadius"
+      | "angle"
+      | "contrast"
+      | "saturation"
+      | "brightness"
+      | "attenuation"
+      | "visionMode"
+      | "color"
+      | "preview"
+      | "disabled"
+    >;
+
+    // TODO: (LukeAbby) possible candidate for `-=` key handling
+    interface BlindedStates extends Record<string, boolean> {
+      blind: boolean;
+      burrow: boolean;
+    }
+
+    /** @internal */
+    type _ReticuleOptions = NullishProps<{
+      /**
+       * The amount of margin between the targeting arrows and the token's bounding box, expressed as a fraction of an arrow's size.
+       * @defaultValue `0`
+       * @remarks This gets assigned to with `*=` before use, so `null` casting to the default of `0` is fine
+       */
+      margin: number;
+
+      /**
+       * The color of the arrows.
+       * @defaultValue `this._getBorderColor()` {@link Token._getBorderColor | `Token#_getBorderColor`}
+       */
+      color: number;
+    }> &
+      InexactPartial<{
+        /**
+         * The alpha value of the arrows.
+         * @defaultValue `1`
+         * @remarks Can't be `null` as it only has a parameter default
+         */
+        alpha: number;
+
+        /**
+         * The size of the arrows as a proportion of grid size.
+         * @defaultValue `0.15`
+         * @remarks Can't be `null` as it only has a parameter default
+         */
+        size: number;
+
+        /**
+         * The arrows' border style configuration.
+         * @defaultValue see properties
+         * @remarks Can't be `null` as it's destructured in signature
+         */
+        border: InexactPartial<{
+          /**
+           * The border color.
+           * @defaultValue `0`
+           * @remarks Can't be `null` as it only has a parameter default
+           */
+          color: number;
+
+          /**
+           * The border width.
+           * @defaultValue `2`
+           * @remarks Can't be `null` as it only has a parameter default
+           */
+          width: number;
+        }>;
+      }>;
+    interface ReticuleOptions extends _ReticuleOptions {}
+
+    /**
+     * The return type of {@link Token.getRingColors | `Token#getRingColors`}. Core's implementation returns `{}`.
+     * Values returned by subclasses should not be nullish, as they are `mergeObject`'d into the default color values
+     * from {@link TokenRing.ConfiguredClass | `TokenRing.ConfiguredClass`}
+     */
+    interface RingColors {
+      ring?: Color;
+      background?: Color;
+    }
+
+    /** @internal */
+    type _AnimationData = Pick<TokenDocument.Implementation, "x" | "y" | "width" | "height" | "rotation" | "alpha"> & {
+      /** The texture data. */
+      texture: Pick<
+        TokenDocument.Implementation["texture"],
+        "src" | "anchorX" | "anchorY" | "scaleX" | "scaleY" | "tint"
+      >;
+    } & {
+      /** The ring data. */
+      ring: {
+        /** The ring subject data */
+        subject: Pick<TokenDocument.Implementation["ring"]["subject"], "texture" | "scale">;
+      };
+    };
+
+    /**
+     * Token animation data.
+     * @privateRemarks Implementing this interface like this does lose the specific (simplified, really)
+     * property descriptions of the `TokenAnimationData` typedef, but it gains the ones from the document
+     * schema, and since the values returned by {@link Token._getAnimationData | `Token#_getAnimationData`}
+     * are pulled directly from the document, this is also the most accurate typing.
+     */
+    interface AnimationData extends _AnimationData {}
+
+    type PartialAnimationData = DeepPartial<AnimationData>;
+
+    interface AnimationDataForDuration extends RequiredProps<PartialAnimationData, "x" | "y" | "rotation"> {}
+
+    interface AnimationDataForRotation extends RequiredProps<PartialAnimationData, "rotation"> {}
+
+    /** @internal */
+    type _GetAnimationDurationOptions = InexactPartial<{
+      /**
+       * A desired token movement speed in grid spaces per second
+       * @defaultValue `6`
+       * @remarks Can't be `null` as it only has a parameter default
+       */
+      movementSpeed: number;
+    }>;
+
+    interface GetAnimationDurationOptions extends _GetAnimationDurationOptions {}
+
+    /** @internal */
+    type _PrepareAnimationOptions = NullishProps<{
+      /**
+       * The desired texture transition type
+       * @defaultValue `TextureTransitionFilter.TYPES.FADE` (`"fade"`)
+       */
+      transition: TextureTransitionFilter.TYPES;
+    }>;
+
+    interface PrepareAnimationOptions extends _PrepareAnimationOptions {}
+
+    /** @internal */
+    type _AnimateOptions = Pick<CanvasAnimation.AnimateOptions, "duration" | "easing" | "name" | "ontick">;
+
+    interface AnimateOptions extends _AnimateOptions, GetAnimationDurationOptions, PrepareAnimationOptions {}
+
+    /** @internal */
+    type _StopAnimationOptions = NullishProps<{
+      /**
+       * Reset the TokenDocument?
+       * @defaultValue `false`
+       */
+      reset: boolean;
+    }>;
+
+    interface StopAnimationOptions extends _StopAnimationOptions {}
+
+    /** @internal */
+    type _CheckCollisionOptions<Mode extends PointSourcePolygon.CollisionModes | undefined = undefined> =
+      InexactPartial<{
+        /**
+         * The collision mode to test: "any", "all", or "closest"
+         * @defaultValue `"any"`
+         * @remarks Can't be `null` as it only has a parameter default
+         */
+        mode: Mode;
+
+        /**
+         * The collision type
+         * @defaultValue `"move"`
+         * @remarks Can't be `null` as it only has a parameter default
+         *
+         * `"sound"` is a valid source type but explicitly throws if passed, so omitted here
+         */
+        type: "move" | "sight" | "light";
+      }> &
+        NullishProps<{
+          /**
+           * The origin to be used instead of the current origin
+           */
+          origin: Canvas.Point;
+        }>;
+
+    interface CheckCollisionOptions<Mode extends PointSourcePolygon.CollisionModes | undefined = undefined>
+      extends _CheckCollisionOptions<Mode> {}
+
+    /** Return type of {@link Token.getSize | `Token#getSize`} */
+    interface Size {
+      width: number;
+      height: number;
+    }
+
+    /**
+     * @privateRemarks Foundry types this as `Point | (Point & {elevation: number}) | {elevation: number}`,
+     * but this is misleading, as if an object is passed for the 2nd param of {@link Token.testInsideRegion | `Token#testInsideRegion`}
+     * then it must contain `{x, y}` data, only if the value is nullish does the document's data get used.
+     * Passing just `{elevation: number}` would result in `{x: undefined, y: undefined}`, causing
+     * `PIXI.Rectangle#contains()` to always return false.
+     *
+     * Not reported, as `testInsideRegion` is deprecated and thus untyped in v13.
+     */
+    type TestablePosition = Canvas.Point & { elevation?: number };
+
+    type _InitializeSourcesOptions = NullishProps<{
+      /**
+       * Indicate that this source has been deleted.
+       * @defaultValue `false`
+       */
+      deleted: boolean;
+    }>;
+
+    interface InitializeSourcesOptions extends _InitializeSourcesOptions {}
+
+    /** @internal */
+    type _TargetContext = NullishProps<{
+      /**
+       * Assign the token as a target for a specific User
+       * @defaultValue `game.user`
+       * @remarks `null` is the parameter default, but it's `||=`d with `game.user`
+       */
+      user: User.Implementation;
+
+      /**
+       * Release other active targets for the same player?
+       * @defaultValue `true`
+       */
+      releaseOthers: boolean;
+
+      /**
+       * Is this target being set as part of a group selection workflow?
+       * @defaultValue `false`
+       */
+      groupSelection: boolean;
+    }>;
+
+    interface TargetContext extends _TargetContext {}
+
+    interface AnimationContext {
+      /** The name of the animation */
+      name: PropertyKey;
+
+      /**
+       * The final animation state
+       * @remarks This gets `mergeObject`ed with the return of {@link Token._getAnimationData | `Token#_getAnimationData`}
+       */
+      to: PartialAnimationData;
+
+      /** The duration of the animation */
+      duration: number;
+
+      /** The current time of the animation */
+      time: number;
+
+      /** Asynchronous functions that are executed before the animation starts */
+      preAnimate: ((context: Token.AnimationContext) => Promise<void>)[];
+
+      /** Synchronous functions that are executed after the animation ended */
+      postAnimate: ((context: Token.AnimationContext) => void)[];
+
+      /** Synchronous functions that are executed each frame after `ontick` and before {@link Token._onAnimationUpdate | `Token#_onAnimationUpdate`} */
+      onAnimate: ((context: Token.AnimationContext) => void)[];
+
+      /**
+       * The promise of the animation, which resolves to true if the animation
+       * completed, to false if it was terminated, and rejects if an error occurred.
+       * Undefined in the first frame (at time 0) of the animation.
+       */
+      promise?: Promise<boolean> | undefined;
+    }
+
+    interface DragLeftDropUpdate {
+      _id: string;
+      x: number;
+      y: number;
+    }
+
+    /** @internal */
+    type _RefreshHUDOptions = NullishProps<{
+      bars: boolean;
+      border: boolean;
+      elevation: boolean;
+      nameplate: boolean;
+      effects: boolean;
+    }>;
+    interface RefreshHUDOptions extends _RefreshHUDOptions {}
+  }
 }