@league-of-foundry-developers/foundry-vtt-types 13.346.0-beta.20250717053920 → 13.346.0-beta.20250717163058

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "13.346.0-beta.20250717053920",
+  "version": "13.346.0-beta.20250717163058",
   "description": "TypeScript type definitions for Foundry VTT",
   "type": "module",
   "types": "./src/index.d.mts",

package/src/foundry/client/applications/ui/scene-controls.d.mts

@@ -12,15 +12,93 @@ declare module "#configuration" {
 
 /**
  * The Scene Controls UI element.
- * @remarks TODO: Stub
  */
 declare class SceneControls<
   RenderContext extends SceneControls.RenderContext = SceneControls.RenderContext,
   Configuration extends SceneControls.Configuration = SceneControls.Configuration,
   RenderOptions extends SceneControls.RenderOptions = SceneControls.RenderOptions,
 > extends HandlebarsApplicationMixin(ApplicationV2)<RenderContext, Configuration, RenderOptions> {
-  // Fake override.
   static override DEFAULT_OPTIONS: SceneControls.DefaultOptions;
+
+  static PARTS: Record<string, HandlebarsApplicationMixin.HandlebarsTemplatePart>;
+
+  static override readonly emittedEvents: string[];
+
+  /**
+   * Prepared data of available controls.
+   */
+  get controls(): Record<string, SceneControls.Control>;
+
+  /**
+   * The currently active control layer.
+   */
+  get control(): SceneControls.Control | null;
+
+  /**
+   * The tools which are available within the current control layer.
+   */
+  get tools(): Record<string, SceneControls.Tool>;
+
+  /**
+   * The currently active tool in the control palette.
+   */
+  get tool(): SceneControls.Tool;
+
+  /**
+   * Activate a new control layer or tool.
+   * This method is advantageous to use because it minimizes the amount of re-rendering necessary.
+   */
+  activate(options?: SceneControls.ActivateOptions): Promise<void>;
+
+  protected override _configureRenderOptions(options: DeepPartial<RenderOptions>): void;
+  protected override _preRender(
+    context: DeepPartial<RenderContext>,
+    options: DeepPartial<RenderOptions>,
+  ): Promise<void>;
+  protected override _prepareContext(
+    options: DeepPartial<RenderOptions> & { isFirstRender: boolean },
+  ): Promise<RenderContext>;
+  protected override _onRender(context: DeepPartial<RenderContext>, options: DeepPartial<RenderOptions>): Promise<void>;
+
+  /**
+   * Update the class of the notes layer icon to reflect whether there are visible notes or not.
+   * @internal
+   */
+  _updateNotesIcon(): void;
+
+  override setPosition(position?: DeepPartial<ApplicationV2.Position>): ApplicationV2.Position | void;
+
+  /**
+   * Reusable toolclip items.
+   */
+  static COMMON_TOOLCLIP_ITEMS: Record<string, SceneControls.ToolclipItem>;
+
+  /**
+   * A helper function used to prepare an array of toolclip items.
+   */
+  static buildToolclipItems(
+    items: Array<SceneControls.ToolclipConfigurationItem | string | null>,
+  ): SceneControls.ToolclipConfigurationItem[];
+
+  /**
+   * @deprecated "{@linkcode SceneControls#activeControl} is deprecated in favor of {@linkcode SceneControls#control#name}" (since v13, until v15)
+   * @ignore
+   */
+  get activeControl(): void;
+
+  /**
+   * @deprecated "{@linkcode SceneControls#activeTool} is deprecated in favor of {@linkcode SceneControls#tool#name}" (since v13, until v15)
+   * @ignore
+   */
+  get activeTool(): void;
+
+  /**
+   * @deprecated "{@linkcode SceneControls#initialize} is deprecated in favor of {@linkcode SceneControls#render} with `{controls, tool}` passed as render options." (since v13, until v15)
+   * @ignore
+   */
+  initialize({ layer, tool }: { layer?: string | undefined; tool?: string | undefined }): Promise<void>;
+
+  #sceneControls: true;
 }
 
 declare namespace SceneControls {
@@ -105,6 +183,11 @@ declare namespace SceneControls {
     reference: string;
   }
 
+  interface ToolclipItem {
+    heading: string;
+    reference: string;
+  }
+
   interface Configuration<SceneControls extends SceneControls.Any = SceneControls.Any>
     extends ApplicationV2.Configuration<SceneControls> {}
 
@@ -115,7 +198,26 @@ declare namespace SceneControls {
   > &
     object;
 
-  interface RenderOptions extends ApplicationV2.RenderOptions {}
+  interface RenderOptions extends ApplicationV2.RenderOptions, HandlebarsApplicationMixin.RenderOptions {
+    /** An event which prompted a re-render */
+    event: Event;
+
+    /** Re-prepare the possible list of controls */
+    reset: boolean;
+
+    /** The control set to activate. If undefined, the current control set remains active */
+    control: string;
+
+    /** A specific tool to activate. If undefined the current tool or default tool for the control set becomes active */
+    tool: string;
+
+    /** Changes to apply to toggles within the control set */
+    toggles: Record<string, boolean>;
+  }
+
+  type EmittedEvents = [...ApplicationV2.EmittedEvents, "activate"];
+
+  interface ActivateOptions extends Pick<SceneControls.RenderOptions, "event" | "control" | "tool" | "toggles"> {}
 }
 
 declare abstract class AnySceneControls extends SceneControls<

package/src/foundry/client/applications/ui/scene-navigation.d.mts

@@ -12,13 +12,61 @@ declare module "#configuration" {
 
 /**
  * The Scene Navigation UI element.
- * @remarks TODO: Stub
  */
 declare class SceneNavigation<
   RenderContext extends SceneNavigation.RenderContext = SceneNavigation.RenderContext,
   Configuration extends SceneNavigation.Configuration = SceneNavigation.Configuration,
   RenderOptions extends SceneNavigation.RenderOptions = SceneNavigation.RenderOptions,
-> extends HandlebarsApplicationMixin(ApplicationV2)<RenderContext, Configuration, RenderOptions> {}
+> extends HandlebarsApplicationMixin(ApplicationV2)<RenderContext, Configuration, RenderOptions> {
+  static override DEFAULT_OPTIONS: SceneNavigation.DefaultOptions;
+  static override PARTS: Record<string, HandlebarsApplicationMixin.HandlebarsTemplatePart>;
+
+  /**
+   * Whether the scene navigation is currently expanded.
+   */
+  get expanded(): boolean;
+
+  protected override _prepareContext(
+    options: DeepPartial<RenderOptions> & { isFirstRender: boolean },
+  ): Promise<RenderContext>;
+
+  protected override _onFirstRender(
+    context: DeepPartial<RenderContext>,
+    options: DeepPartial<RenderOptions>,
+  ): Promise<void>;
+
+  protected override _onRender(context: DeepPartial<RenderContext>, options: DeepPartial<RenderOptions>): Promise<void>;
+
+  /**
+   * Get the set of ContextMenu options which should be applied for Scenes in the menu.
+   */
+  protected _getContextMenuOptions(): foundry.applications.ux.ContextMenu.Entry<HTMLElement>[];
+
+  /**
+   * Expand Scene Navigation, displaying inactive Scenes.
+   */
+  expand(): void;
+
+  /**
+   * Collapse Scene Navigation, hiding inactive Scenes.
+   */
+  collapse(): Promise<void>;
+
+  /**
+   * Toggle the expanded state of scene navigation.
+   * @param expanded - Force the expanded state to the provided value, otherwise toggle the state.
+   */
+  toggleExpanded(expanded?: boolean): void;
+
+  /**
+   * @deprecated "SceneNavigation.displayProgressBar is deprecated in favor of {@linkcode Notifications#notify} using the \{progress: true\} option" (since v13, until v15)
+   * @ignore
+   */
+  static displayProgressBar({ label, pct }?: SceneNavigation.DisplayProgressBarOptions): void;
+
+  static #SceneNavigationStatic: true;
+  #SceneNavigation: true;
+}
 
 declare namespace SceneNavigation {
   interface Any extends AnySceneNavigation {}
@@ -40,6 +88,11 @@ declare namespace SceneNavigation {
     canExpand: number;
   }
 
+  interface DisplayProgressBarOptions {
+    label?: string | undefined;
+    pct?: number | undefined;
+  }
+
   interface Configuration<SceneNavigation extends SceneNavigation.Any = SceneNavigation.Any>
     extends HandlebarsApplicationMixin.Configuration,
       ApplicationV2.Configuration<SceneNavigation> {}

package/src/foundry/client/canvas/groups/interface.d.mts

@@ -40,7 +40,7 @@ declare class InterfaceCanvasGroup<
    * @param origin  - An origin point where the text should first emerge
    * @param content - The text content to display
    * @param options - Options which customize the text animation
-   * @returns - The created PreciseText object which is scrolling
+   * @returns The created PreciseText object which is scrolling
    * @remarks Only returns `null` if the core `scrollingStatusText` setting is falsey
    */
   createScrollingText(

package/src/foundry/client/canvas/layers/base/interaction-layer.d.mts

@@ -38,7 +38,7 @@ declare class InteractionLayer extends CanvasLayer {
   /**
    * Activate the InteractionLayer, deactivating other layers and marking this layer's children as interactive.
    * @param options - Options which configure layer activation
-   * @returns - The layer instance, now activated
+   * @returns The layer instance, now activated
    */
   activate(options?: InteractionLayer.ActivateOptions): this;
 
@@ -49,7 +49,7 @@ declare class InteractionLayer extends CanvasLayer {
 
   /**
    * Deactivate the InteractionLayer, removing interactivity from its children.
-   * @returns - The layer instance, now inactive
+   * @returns The layer instance, now inactive
    */
   deactivate(): this;
 

package/src/foundry/client/canvas/rendering/shaders/samplers/base-sampler.d.mts

@@ -167,7 +167,7 @@ declare class BaseSamplerShader extends AbstractBaseShader {
 
   /**
    * Create a batch plugin for this sampler class.
-   * @returns - The batch plugin class linked to this sampler class.
+   * @returns The batch plugin class linked to this sampler class.
    */
   static createPlugin<ThisType extends BaseSamplerShader.AnyConstructor>(
     this: ThisType,

package/src/foundry/client/documents/actor-delta.d.mts

@@ -2,7 +2,7 @@ import type { DataSchema } from "#common/data/fields.d.mts";
 import type { BaseActorDelta } from "#common/documents/_module.d.mts";
 import type Document from "#common/abstract/document.d.mts";
 import type { ConfiguredActorDelta } from "fvtt-types/configuration";
-import type { Identity, InexactPartial, Merge, NullishProps, RequiredProps } from "#utils";
+import type { Identity, InexactPartial, Merge, NullishProps } from "#utils";
 import type DataModel from "#common/abstract/data.d.mts";
 
 import fields = foundry.data.fields;
@@ -14,9 +14,9 @@ declare namespace ActorDelta {
   type Name = "ActorDelta";
 
   /**
-   * @privateRemarks This is off-template, as `ActorDelta` requires a valid parent to validate.
+   * The context used to create a `ActorDelta`.
    */
-  interface ConstructionContext extends RequiredProps<Document.ConstructionContext<Parent>, "parent"> {}
+  interface ConstructionContext extends Document.ConstructionContext<Parent> {}
 
   /**
    * The documents embedded within `ActorDelta`.
@@ -131,8 +131,10 @@ declare namespace ActorDelta {
   /**
    * 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.
+   *
+   * `ActorDelta` requires a parent so `null` is not an option here.
    */
-  type Parent = TokenDocument.Implementation | null;
+  type Parent = TokenDocument.Implementation;
 
   /**
    * A document's direct descendants are documents that are contained directly within its schema.

package/src/foundry/client/documents/collections/compendium-collection.d.mts

@@ -12,13 +12,13 @@ import type ApplicationV2 from "#client/applications/api/application.mjs";
  * @see {@link Game.packs | `Game#packs`}
  */
 declare class CompendiumCollection<
-  Type extends foundry.documents.collections.CompendiumCollection.DocumentName,
+  Type extends CompendiumCollection.DocumentName,
 > extends foundry.documents.abstract.DirectoryCollectionMixin(foundry.documents.abstract.DocumentCollection)<Type> {
   /** @param metadata - The compendium metadata, an object provided by game.data */
-  constructor(metadata: foundry.documents.collections.CompendiumCollection.ConstructorMetadata<Type>);
+  constructor(metadata: CompendiumCollection.ConstructorMetadata<Type>);
 
   /** The compendium metadata which defines the compendium content and location */
-  metadata: foundry.documents.collections.CompendiumCollection.Metadata;
+  metadata: CompendiumCollection.Metadata;
 
   /** A subsidiary collection which contains the more minimal index of the pack */
   index: IndexTypeForMetadata<Type>;
@@ -83,7 +83,7 @@ declare class CompendiumCollection<
   // Note(LukeAbby): The override for `_getVisibleTreeContents` become unreasonably long and don't add any changes and so has been omitted.
 
   /** Access the compendium configuration data for this pack */
-  get config(): foundry.documents.collections.CompendiumCollection.Configuration | EmptyObject;
+  get config(): CompendiumCollection.Configuration | EmptyObject;
 
   get documentName(): Type;
 
@@ -127,7 +127,7 @@ declare class CompendiumCollection<
    * Load the Compendium index and cache it as the keys and values of the Collection.
    * @param options - Options which customize how the index is created
    */
-  getIndex(options?: foundry.documents.collections.CompendiumCollection.GetIndexOptions<Type>): Promise<this["index"]>;
+  getIndex(options?: CompendiumCollection.GetIndexOptions<Type>): Promise<this["index"]>;
 
   /**
    * Get a single Document from this Compendium by ID.
@@ -158,9 +158,7 @@ declare class CompendiumCollection<
    * await pack.getDocuments({ type__in: ["weapon", "armor"] });
    * ```
    */
-  getDocuments(
-    query?: foundry.documents.collections.CompendiumCollection.Query<Type>,
-  ): Promise<Document.ImplementationFor<Type>[]>;
+  getDocuments(query?: CompendiumCollection.Query<Type>): Promise<Document.ImplementationFor<Type>[]>;
 
   /**
    * Get the ownership level that a User has for this Compendium pack.
@@ -180,7 +178,7 @@ declare class CompendiumCollection<
   testUserPermission(
     user: User.Implementation,
     permission: string | number,
-    options?: foundry.documents.collections.CompendiumCollection.TestUserPermissionOptions,
+    options?: CompendiumCollection.TestUserPermissionOptions,
   ): boolean;
 
   /**
@@ -200,29 +198,21 @@ declare class CompendiumCollection<
    * @param folder  - The existing Folder you wish to import
    * @param options - Additional options which modify how the data is imported.
    */
-  importFolder(
-    folder: Folder.Implementation,
-    options?: foundry.documents.collections.CompendiumCollection.ImportFolderOptions,
-  ): Promise<void>;
+  importFolder(folder: Folder.Implementation, options?: CompendiumCollection.ImportFolderOptions): Promise<void>;
 
   /**
    * Import an array of Folders into this Compendium Collection.
    * @param folders - The existing Folders you wish to import
    * @param options - Additional options which modify how the data is imported.
    */
-  importFolders(
-    folders: Folder.Implementation[],
-    options?: foundry.documents.collections.CompendiumCollection.ImportFoldersOptions,
-  ): Promise<void>;
+  importFolders(folders: Folder.Implementation[], options?: CompendiumCollection.ImportFoldersOptions): Promise<void>;
 
   /**
    * Fully import the contents of a Compendium pack into a World folder.
    * @param options - Options which modify the import operation. Additional options are forwarded to {@link WorldCollection.fromCompendium | `WorldCollection#fromCompendium`} and {@linkcode Document.createDocuments} (default: `{}`)
    * @returns The imported Documents, now existing within the World
    */
-  importAll(
-    options?: foundry.documents.collections.CompendiumCollection.ImportAllOptions<Type>,
-  ): Promise<Document.StoredForName<Type>[]>;
+  importAll(options?: CompendiumCollection.ImportAllOptions<Type>): Promise<Document.StoredForName<Type>[]>;
 
   /**
    * Provide a dialog form that prompts the user to import the full contents of a Compendium pack into the World.
@@ -261,9 +251,9 @@ declare class CompendiumCollection<
    * @param options - Additional options which modify the Compendium creation request
    *                  (default: `{}`)
    */
-  static createCompendium<T extends foundry.documents.collections.CompendiumCollection.DocumentName>(
+  static createCompendium<T extends CompendiumCollection.DocumentName>(
     this: abstract new (...args: never) => CompendiumCollection<NoInfer<T>>,
-    metadata: foundry.documents.collections.CompendiumCollection.CreateCompendiumMetadata<T>,
+    metadata: CompendiumCollection.CreateCompendiumMetadata<T>,
     options?: unknown,
   ): Promise<CompendiumCollection<T>>;
 
@@ -294,9 +284,7 @@ declare class CompendiumCollection<
    * Duplicate a compendium pack to the current World.
    * @param label - A new Compendium label
    */
-  duplicateCompendium({
-    label,
-  }?: foundry.documents.collections.CompendiumCollection.DuplicateCompendiumOptions): Promise<this>;
+  duplicateCompendium({ label }?: CompendiumCollection.DuplicateCompendiumOptions): Promise<this>;
 
   /**
    * Migrate a compendium pack.
@@ -333,19 +321,21 @@ declare namespace CompendiumCollection {
   }
 
   // The type that's passed to `new CompendiumCollection(...)`
-  type ConstructorMetadata<Type extends foundry.documents.collections.CompendiumCollection.DocumentName> =
-    Metadata<Type> & {
-      index: IndexTypeForMetadata<Type>;
-      folders: Folder.Implementation[];
-    };
+  type ConstructorMetadata<Type extends CompendiumCollection.DocumentName> = Metadata<Type> & {
+    index: IndexTypeForMetadata<Type>;
+    folders: Folder.Implementation[];
+  };
 
   // The type that appears in `compendium.metadata` after initialization.
-  interface Metadata<
-    Type extends
-      foundry.documents.collections.CompendiumCollection.DocumentName = foundry.documents.collections.CompendiumCollection.DocumentName,
-  > {
+  interface Metadata<Type extends CompendiumCollection.DocumentName = CompendiumCollection.DocumentName> {
     type: Type;
     label: string;
+
+    /**
+     * @remarks `undefined` is replaced with the default `CONFIG[this.metadata.type]?.compendiumBanner`
+     * but `null` passes through unchanged.
+     */
+    banner?: string | null | undefined;
     name: string;
 
     flags: Record<string, never>; // created by the server, but always empty and no way to change it in a way that is s
@@ -431,7 +421,7 @@ declare namespace CompendiumCollection {
     importParents?: boolean | undefined;
   }
 
-  type ImportAllOptions<Type extends foundry.documents.collections.CompendiumCollection.DocumentName> = SimpleMerge<
+  type ImportAllOptions<Type extends CompendiumCollection.DocumentName> = SimpleMerge<
     UnionToIntersection<Document.Database.CreateOperationForName<Type>>,
     foundry.documents.abstract.WorldCollection.FromCompendiumOptions
   > & {
@@ -462,9 +452,7 @@ declare namespace CompendiumCollection {
 
   // Note(LukeAbby): One neat possibility for this type would be making something like `type: "foo"`,
   // `type__ne: "foo"`, and `type__in: ["foo", "bar"]` all narrow `system`.
-  type Query<Type extends foundry.documents.collections.CompendiumCollection.DocumentName> = _Queryify<
-    Document.SourceForName<Type>
-  >;
+  type Query<Type extends CompendiumCollection.DocumentName> = _Queryify<Document.SourceForName<Type>>;
 
   /** @internal */
   type _Queryify<T> = T extends object ? _QueryifyObject<T> : T;
@@ -487,7 +475,8 @@ declare namespace CompendiumCollection {
 
 type IsComparable<T> = T extends boolean | string | number | bigint | symbol | null | undefined ? true : false;
 
-type IndexTypeForMetadata<Type extends foundry.documents.collections.CompendiumCollection.DocumentName> =
-  foundry.utils.Collection<foundry.documents.collections.CompendiumCollection.IndexEntry<Type>>;
+type IndexTypeForMetadata<Type extends CompendiumCollection.DocumentName> = foundry.utils.Collection<
+  CompendiumCollection.IndexEntry<Type>
+>;
 
 export default CompendiumCollection;

package/src/foundry/client/documents/combatant.d.mts

@@ -1,5 +1,5 @@
 import type { ConfiguredCombatant } from "fvtt-types/configuration";
-import type { Identity, InexactPartial, Merge, RequiredProps } from "#utils";
+import type { Identity, InexactPartial, Merge } from "#utils";
 import type { documents } from "#client/client.d.mts";
 import type Document from "#common/abstract/document.d.mts";
 import type { DataSchema } from "#common/data/fields.d.mts";
@@ -15,9 +15,8 @@ declare namespace Combatant {
 
   /**
    * The context used to create a `Combatant`.
-   * @privateRemarks This is off-template, as `Combatant` requires a valid parent to validate.
    */
-  interface ConstructionContext extends RequiredProps<Document.ConstructionContext<Parent>, "parent"> {}
+  interface ConstructionContext extends Document.ConstructionContext<Parent> {}
 
   /**
    * The documents embedded within `Combatant`.
@@ -130,8 +129,10 @@ declare namespace Combatant {
   /**
    * 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.
+   *
+   * `Combatant` requires a parent so `null` is not an option here.
    */
-  type Parent = Combat.Implementation | null;
+  type Parent = Combat.Implementation;
 
   /**
    * A document's descendants are any child documents, grandchild documents, etc.

package/src/foundry/client/hooks.d.mts

@@ -456,8 +456,11 @@ export interface AllHooks extends DynamicHooks {
 
   /**
    * A hook event that fires when a custom active effect is applied.
-   * @param actor  - The actor the active effect is being applied to
-   * @param change - The change data being applied
+   * @param actor   - The actor the active effect is being applied to
+   * @param change  - The change data being applied
+   * @param current - The current value being modified
+   * @param delta   - The parsed value of the change object
+   * @param changes - An object which accumulates changes to be applied
    * @remarks This is called by {@linkcode Hooks.call}.
    * @see {@link ActiveEffect._applyCustom | `ActiveEffect#_applyCustom`}
    */
@@ -803,8 +806,11 @@ export interface AllHooks extends DynamicHooks {
       /** The new round of combat */
       round: number;
 
-      /** The new turn number */
-      turn: number;
+      /**
+       * The new turn number
+       * @remarks `combatRound`, unlike `combatTurn` and `combatStart`, can have a `null` turn.
+       */
+      turn: number | null;
     },
     updateOptions: {
       /** The amount of time in seconds that time is being advanced */
@@ -974,6 +980,17 @@ export interface AllHooks extends DynamicHooks {
     app: foundry.applications.ui.Players,
     contextOptions: ContextMenu.Entry<HTMLElement>[],
   ) => boolean | void;
+
+  /**
+   * A hook event that fires when the context menu for a SceneNavigation entry is constructed.
+   * @param app            - The Application instance that the context menu is constructed in
+   * @param contextOptions - The context menu entries
+   * @remarks This is called by {@linkcode Hooks.callAll}.
+   */
+  getSceneContextOptions: (
+    app: foundry.applications.ui.SceneNavigation,
+    contextOptions: ContextMenu.Entry<HTMLElement>[],
+  ) => void;
 }
 
 declare global {

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

@@ -5,7 +5,29 @@ import type Document from "./document.d.mts";
 // This means that actual functions must use helper types to properly omit properties or explicit undefined
 // Also, the _result property is intentionally left out as it is never present on the client
 
-export interface DatabaseGetOperation<Parent extends Document.Any | null = Document.Any | null> {
+// @ts-expect-error This pattern is inherently an error.
+interface _DynamicBase<T extends object> extends T {}
+
+interface _Parent<Parent extends Document.Any | null>
+  extends _DynamicBase<
+    Parent extends null
+      ? {
+          /**
+           * A parent Document within which Documents are embedded
+           * @defaultValue `null`
+           */
+          parent?: Parent | null | undefined;
+        }
+      : {
+          /**
+           * A parent Document within which Documents are embedded
+           */
+          parent: Parent;
+        }
+  > {}
+
+export interface DatabaseGetOperation<Parent extends Document.Any | null = Document.Any | null>
+  extends _Parent<Parent> {
   /**
    * A query object which identifies the set of Documents retrieved
    */
@@ -31,11 +53,6 @@ export interface DatabaseGetOperation<Parent extends Document.Any | null = Docum
    */
   pack?: string | null | undefined;
 
-  /**
-   * A parent Document within which Documents are embedded
-   */
-  parent?: Parent | null | undefined;
-
   /**
    * A parent Document UUID provided when the parent instance is unavailable
    */
@@ -46,7 +63,7 @@ export interface DatabaseCreateOperation<
   CreateData extends object | null | undefined = object | null | undefined,
   Parent extends Document.Any | null = Document.Any | null,
   Temporary extends boolean | undefined = boolean | undefined,
-> {
+> extends _Parent<Parent> {
   /**
    * Whether the database operation is broadcast to other connected clients
    */
@@ -91,11 +108,6 @@ export interface DatabaseCreateOperation<
    */
   renderSheet: boolean;
 
-  /**
-   * A parent Document within which Documents are embedded
-   */
-  parent?: Parent | undefined;
-
   /**
    * A compendium collection ID which contains the Documents
    */
@@ -133,7 +145,7 @@ export interface DatabaseCreateOperation<
 export interface DatabaseUpdateOperation<
   UpdateData extends object | null | undefined = object | null | undefined,
   Parent extends Document.Any | null = Document.Any | null,
-> {
+> extends _Parent<Parent> {
   /**
    * Whether the database operation is broadcast to other connected clients
    */
@@ -176,11 +188,6 @@ export interface DatabaseUpdateOperation<
    */
   noHook?: boolean | null;
 
-  /**
-   * A parent Document within which Documents are embedded
-   */
-  parent?: Parent | null;
-
   /**
    * A compendium collection ID which contains the Documents
    */
@@ -192,7 +199,8 @@ export interface DatabaseUpdateOperation<
   parentUuid?: string | null;
 }
 
-export interface DatabaseDeleteOperation<Parent extends Document.Any | null = Document.Any | null> {
+export interface DatabaseDeleteOperation<Parent extends Document.Any | null = Document.Any | null>
+  extends _Parent<Parent> {
   /**
    * Whether the database operation is broadcast to other connected clients
    */
@@ -226,11 +234,6 @@ export interface DatabaseDeleteOperation<Parent extends Document.Any | null = Do
    */
   render: boolean;
 
-  /**
-   * A parent Document within which Documents are embedded
-   */
-  parent?: Parent | null;
-
   /**
    * A compendium collection ID which contains the Documents
    */

package/src/foundry/common/abstract/document.d.mts

@@ -1573,33 +1573,51 @@ declare namespace Document {
   }
 
   /** @internal */
-  type _ConstructionContext<Parent extends Document.Any | null> = NullishProps<{
-    /**
-     * The parent Document of this one, if this one is embedded
-     * @defaultValue `null`
-     */
-    parent: Parent;
+  interface _ParentContext<Parent extends Document.Any | null>
+    extends _DynamicBase<
+      Parent extends null
+        ? {
+            /**
+             * The parent Document of this one, if this one is embedded
+             * @defaultValue `null`
+             */
+            parent?: Parent | undefined;
+          }
+        : {
+            /**
+             * The parent Document of this one, if this one is embedded
+             */
+            parent: Parent;
+          }
+    > {}
 
-    /**
-     * The compendium collection ID which contains this Document, if any
-     * @defaultValue `null`
-     */
-    pack: string;
+  // @ts-expect-error This pattern is inherently an error.
+  interface _DynamicBase<T extends object> extends T {}
 
-    /**
-     * Whether to validate initial data strictly?
-     * @defaultValue `true`
-     */
-    strict: boolean;
+  /** @internal */
+  interface _ConstructionContext<Parent extends Document.Any | null>
+    extends _ParentContext<Parent>,
+      NullishProps<{
+        /**
+         * The compendium collection ID which contains this Document, if any
+         * @defaultValue `null`
+         */
+        pack: string;
 
-    /**
-     * An immutable reverse-reference to the name of the collection that this Document exists in on its parent, if any.
-     * @privateRemarks Omitted from the typedef, inferred from usage in {@link Document._configure | `Document#_configure`}
-     * (and included in the construction context rather than `ConfigureOptions` due to being passed to construction in
-     * {@link foundry.abstract.EmbeddedCollection.createDocument | `EmbeddedCollection#createDocument`})
-     */
-    parentCollection: string;
-  }>;
+        /**
+         * Whether to validate initial data strictly?
+         * @defaultValue `true`
+         */
+        strict: boolean;
+
+        /**
+         * An immutable reverse-reference to the name of the collection that this Document exists in on its parent, if any.
+         * @privateRemarks Omitted from the typedef, inferred from usage in {@link Document._configure | `Document#_configure`}
+         * (and included in the construction context rather than `ConfigureOptions` due to being passed to construction in
+         * {@link foundry.abstract.EmbeddedCollection.createDocument | `EmbeddedCollection#createDocument`})
+         */
+        parentCollection: string;
+      }> {}
 
   /**
    * Foundry does not include the properties from the DataModel construction context in `DocumentConstructionContext`,

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

@@ -422,7 +422,7 @@ declare abstract class DataField<
    * @param delta  - The change delta.
    * @param model  - The model instance.
    * @param change - The original change data.
-   * @returns - The updated value.
+   * @returns The updated value.
    *
    * @remarks Returns `value + delta`. `model` and `change` are unused in `DataField`
    */
@@ -473,7 +473,7 @@ declare abstract class DataField<
    * @param delta - The change delta.
    * @param model - The model instance.
    * @param change - The original change data.
-   * @returns - The updated value.
+   * @returns The updated value.
    *
    * @remarks No-op in `DataField`, returns `undefined` unless overridden
    */
@@ -507,7 +507,7 @@ declare abstract class DataField<
    * @param delta - The change delta.
    * @param model - The model instance.
    * @param change - The original change data.
-   * @returns - The updated value.
+   * @returns The updated value.
    * @remarks Only returns a value if the target value of the change actually changed
    */
   protected _applyChangeCustom(