@vttforge/core 0.0.0 → 0.7.0

package/dist/index.d.mts

@@ -0,0 +1,1049 @@
+//#region src/base-actor-sheet.d.ts
+/**
+ * BaseActorSheet — `ActorSheetV2 + HandlebarsApplicationMixin` baseline with the
+ * boilerplate every shipping system copy-pastes hoisted into the SDK.
+ *
+ * What this adds beyond stock Foundry v13:
+ *
+ * - **`static DRAG_DROP`** — declare drag sources / drop targets as data, get
+ *   `foundry.applications.ux.DragDrop` instances wired in `_onRender` with
+ *   `isEditable`-gated permissions and a sensible default `_onDragStart` that
+ *   serialises `data-item-id` elements as `{ type: "Item", uuid }`.
+ * - **`_prepareContext` auto-fills `context.tabs[group]`** for every group
+ *   declared in ApplicationV2's `static TABS`, so subclass `_prepareContext`
+ *   implementations stop having to call `_prepareTabs(group)` by hand.
+ * - **Typed drop dispatch** — override `onDropItem(item, event)` /
+ *   `onDropActor(actor, event)` / `onDropFolder(folder, event)` /
+ *   `onDropActiveEffect(effect, event)` and skip the `fromUuid()` ceremony.
+ *   Returning `undefined` falls through to Foundry's default `_onDropX`
+ *   behaviour; return any other value to take ownership.
+ *
+ * Intentional non-additions:
+ *
+ * - `editImage` action — already shipped by `DocumentSheetV2` (inherited by
+ *   `ActorSheetV2`). Templates wire `<img data-edit="img">` and Foundry's
+ *   built-in action handles the `FilePicker` flow.
+ * - `_getTabs()` — ApplicationV2 already owns the tab state machine; we only
+ *   eliminate the `_prepareTabs` call in `_prepareContext`.
+ *
+ * Resolved lazily so subclasses can be declared at module load without
+ * Foundry globals existing yet (test boot, ESM hoist).
+ */
+/**
+ * Declarative DragDrop entry consumed by `_onRender`. Mirrors the
+ * `foundry.applications.ux.DragDrop` constructor config. Permissions and
+ * callbacks fall back to sensible defaults that honour `this.isEditable` and
+ * the default `_onDragStart` / `_onDrop`.
+ */
+interface DragDropConfig {
+  readonly dragSelector?: string;
+  readonly dropSelector?: string;
+  readonly permissions?: {
+    readonly dragstart?: () => boolean;
+    readonly drop?: () => boolean;
+  };
+  readonly callbacks?: Record<string, (...args: any[]) => unknown>;
+}
+/**
+ * The statics a VTTForge sheet base carries.
+ *
+ * The factory used to return a bare constructor, so a subclass writing
+ * `super.DEFAULT_OPTIONS` — the pattern the docs show and every sheet needs —
+ * failed to compile. TypeScript cannot see a static through an untyped
+ * constructor. The example system never caught it because it is JavaScript.
+ *
+ * `DEFAULT_OPTIONS` is deliberately loose: a subclass merges its own shape
+ * into it, and pinning ours would reject the merge.
+ */
+interface SheetBaseStatics {
+  readonly DEFAULT_OPTIONS: Record<string, any>;
+  readonly DRAG_DROP: ReadonlyArray<DragDropConfig>;
+}
+/**
+ * What the factory hands back: something you can `extend`, whose statics the
+ * compiler can see.
+ */
+interface SheetBaseCtor extends SheetBaseStatics {
+  new (...args: any[]): any;
+}
+/**
+ * Marker class that consumer CSS uses for scoping. Always present on every
+ * VTTForge-derived sheet so rules like `.vttforge .actor-sheet { ... }` work.
+ */
+declare const VTTFORGE_SHEET_CLASS = "vttforge";
+/**
+ * Build the `BaseActorSheet` for the current Foundry runtime. See module
+ * header for the boilerplate this base eliminates.
+ *
+ * @example
+ * ```ts
+ * class CharacterSheet extends BaseActorSheet() {
+ *   static DEFAULT_OPTIONS = foundry.utils.mergeObject(
+ *     super.DEFAULT_OPTIONS,
+ *     { classes: ['my-system'], position: { width: 720 } },
+ *   );
+ *   static PARTS = { ... };
+ *   static TABS = {
+ *     primary: {
+ *       tabs: [
+ *         { id: 'features', group: 'primary', label: 'Features' },
+ *         { id: 'inventory', group: 'primary', label: 'Inventory' },
+ *       ],
+ *       initial: 'features',
+ *     },
+ *   };
+ *   static DRAG_DROP = [{ dragSelector: '.item[draggable=true]', dropSelector: null }];
+ *   async onDropItem(item, event) {
+ *     if (item.type !== 'weapon') return false;
+ *     // …fall through to super by returning undefined.
+ *   }
+ * }
+ * ```
+ */
+declare function BaseActorSheet(): SheetBaseCtor;
+//#endregion
+//#region src/base-item-sheet.d.ts
+/**
+ * Build the `BaseItemSheet` for the current Foundry runtime.
+ *
+ * @example
+ * ```ts
+ * class WeaponSheet extends BaseItemSheet() {
+ *   static DEFAULT_OPTIONS = foundry.utils.mergeObject(
+ *     super.DEFAULT_OPTIONS,
+ *     { classes: ['my-system'], position: { width: 540 } },
+ *   );
+ *   static PARTS = { ... };
+ *   static TABS = {
+ *     primary: {
+ *       tabs: [
+ *         { id: 'description', group: 'primary', label: 'Description' },
+ *         { id: 'details', group: 'primary', label: 'Details' },
+ *       ],
+ *       initial: 'description',
+ *     },
+ *   };
+ * }
+ * ```
+ */
+declare function BaseItemSheet(): SheetBaseCtor;
+//#endregion
+//#region src/data/field-options.d.ts
+/**
+ * Option interfaces for the Foundry v13 data fields covered by `@vttforge/core`'s
+ * v0.1 `InferSchema<T>` surface.
+ *
+ * Mirrors the shape documented at https://foundryvtt.com/api/v13/ for each
+ * `foundry.data.fields.*` class. Properties are structural — they exist purely
+ * so the conditional types in `./infer-schema.ts` can extract semantics like
+ * `nullable: true` without us pulling in `fvtt-types` (deferred to
+ * `@vttforge/types` v1.0).
+ */
+/**
+ * Properties shared by every Foundry data field option object.
+ *
+ * Mirrors the base `DataFieldOptions` interface documented at
+ * https://foundryvtt.com/api/v13/classes/foundry.data.fields.DataField.html.
+ */
+interface DataFieldOptions {
+  readonly required?: boolean;
+  readonly nullable?: boolean;
+  readonly initial?: unknown;
+  readonly readonly?: boolean;
+  readonly gmOnly?: boolean;
+  readonly label?: string;
+  readonly hint?: string;
+  readonly validationError?: string;
+  readonly validate?: (value: unknown) => boolean | undefined;
+}
+interface NumberFieldOptions extends DataFieldOptions {
+  readonly integer?: boolean;
+  readonly positive?: boolean;
+  readonly min?: number;
+  readonly max?: number;
+  readonly step?: number;
+  readonly choices?: readonly number[] | Record<string, number>;
+}
+interface StringFieldOptions extends DataFieldOptions {
+  readonly blank?: boolean;
+  readonly trim?: boolean;
+  readonly textSearch?: boolean;
+  readonly choices?: readonly string[] | Record<string, string>;
+}
+type BooleanFieldOptions = DataFieldOptions;
+type HTMLFieldOptions = StringFieldOptions;
+type ColorFieldOptions = StringFieldOptions;
+interface FilePathFieldOptions extends StringFieldOptions {
+  readonly categories?: ReadonlyArray<'IMAGE' | 'VIDEO' | 'AUDIO' | 'TEXT' | 'FONT' | 'GRAPHICS'>;
+  readonly base64?: boolean;
+  readonly wildcard?: boolean;
+}
+interface ArrayFieldOptions extends DataFieldOptions {
+  readonly min?: number;
+  readonly max?: number;
+}
+type SchemaFieldOptions = DataFieldOptions;
+/**
+ * `SetField` takes the same options as `ArrayField` — it is a subclass whose
+ * only difference is what `initialize` hands back.
+ */
+type SetFieldOptions = ArrayFieldOptions;
+interface ForeignDocumentFieldOptions extends DataFieldOptions {
+  /**
+   * Keep the stored id instead of resolving the document.
+   *
+   * With this off, the field initializes to a getter — reading the property
+   * gives you a function, and calling it looks the document up. That is why
+   * the two cases infer to different types.
+   */
+  readonly idOnly?: boolean;
+}
+/** `EmbeddedDataField` builds a SchemaField from the model's own schema. */
+type EmbeddedDataFieldOptions = SchemaFieldOptions;
+/** `EmbeddedDocumentField` is the same, but nullable out of the box. */
+type EmbeddedDocumentFieldOptions = SchemaFieldOptions;
+/** `TypedSchemaField` is required by default and takes no options of its own. */
+type TypedSchemaFieldOptions = DataFieldOptions;
+//#endregion
+//#region src/data/fields.d.ts
+declare const BRAND: unique symbol;
+/**
+ * Anything that satisfies the `FieldInstance` shape — used as the inner-field
+ * constraint on `ArrayField` and as the value type of `SchemaField`'s child
+ * map. Keeps the conditional types in `./infer-schema.ts` straightforward.
+ */
+interface FieldInstance {
+  readonly [BRAND]: string;
+  readonly options: unknown;
+}
+interface NumberFieldInstance<O extends NumberFieldOptions = NumberFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'number';
+  readonly options: O;
+}
+interface StringFieldInstance<O extends StringFieldOptions = StringFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'string';
+  readonly options: O;
+}
+interface BooleanFieldInstance<O extends BooleanFieldOptions = BooleanFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'boolean';
+  readonly options: O;
+}
+interface HTMLFieldInstance<O extends HTMLFieldOptions = HTMLFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'html';
+  readonly options: O;
+}
+interface ColorFieldInstance<O extends ColorFieldOptions = ColorFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'color';
+  readonly options: O;
+}
+interface FilePathFieldInstance<O extends FilePathFieldOptions = FilePathFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'filePath';
+  readonly options: O;
+}
+interface ArrayFieldInstance<Inner extends FieldInstance = FieldInstance, O extends ArrayFieldOptions = ArrayFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'array';
+  readonly element: Inner;
+  readonly options: O;
+}
+/**
+ * A `SetField` holds a `Set`, not an array.
+ *
+ * It extends `ArrayField` and validates the same way, but `initialize`
+ * wraps the result in `new Set(...)` — so a schema that declares one and
+ * types it as an array gets `.push` and index access from the compiler on a
+ * value that has neither.
+ */
+interface SetFieldInstance<Inner extends FieldInstance = FieldInstance, O extends SetFieldOptions = SetFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'set';
+  readonly element: Inner;
+  readonly options: O;
+}
+/**
+ * A reference to another document, stored as its id.
+ *
+ * What you read back depends on `idOnly`. With it, the id string. Without
+ * it, the document itself: the field resolves to a getter, so reading the
+ * property looks the document up in its collection and hands back the
+ * instance — or `null` when it is gone or lives in a compendium.
+ *
+ * The field is nullable by default, so both shapes admit `null`.
+ */
+interface ForeignDocumentFieldInstance<Doc extends DocumentClass = DocumentClass, O extends ForeignDocumentFieldOptions = ForeignDocumentFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'foreignDocument';
+  readonly model: Doc;
+  readonly options: O;
+}
+/**
+ * A nested data model.
+ *
+ * It is a `SchemaField` built from the model class's own `defineSchema()`, so
+ * the value is an instance of that model — not a plain object. Reading it
+ * gives you the model's derived data and methods too.
+ */
+interface EmbeddedDataFieldInstance<Model extends DataModelClass = DataModelClass, O extends EmbeddedDataFieldOptions = EmbeddedDataFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'embeddedData';
+  readonly model: Model;
+  readonly options: O;
+}
+/**
+ * A single embedded document, stored inline.
+ *
+ * Like `EmbeddedDataField` but for a Document class, and nullable by default:
+ * the field's own defaults turn `nullable` on, so an absent one reads `null`.
+ */
+interface EmbeddedDocumentFieldInstance<Doc extends DataModelClass = DataModelClass, O extends EmbeddedDocumentFieldOptions = EmbeddedDocumentFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'embeddedDocument';
+  readonly model: Doc;
+  readonly options: O;
+}
+/**
+ * One of several shapes, told apart by a `type` property.
+ *
+ * Each entry becomes its own SchemaField. When an entry does not declare a
+ * `type` field, the field adds one — a required string whose value must equal
+ * that entry's key — which is what makes the result a discriminated union you
+ * can narrow on.
+ */
+interface TypedSchemaFieldInstance<T extends Record<string, Record<string, FieldInstance>> = Record<string, Record<string, FieldInstance>>, O extends TypedSchemaFieldOptions = TypedSchemaFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'typedSchema';
+  readonly types: T;
+  readonly options: O;
+}
+interface SchemaFieldInstance<S extends Record<string, FieldInstance> = Record<string, FieldInstance>, O extends SchemaFieldOptions = SchemaFieldOptions> extends FieldInstance {
+  readonly [BRAND]: 'schema';
+  readonly fields: S;
+  readonly options: O;
+}
+interface NumberFieldCtor {
+  new <O extends NumberFieldOptions = NumberFieldOptions>(options?: O): NumberFieldInstance<O>;
+}
+interface StringFieldCtor {
+  new <O extends StringFieldOptions = StringFieldOptions>(options?: O): StringFieldInstance<O>;
+}
+interface BooleanFieldCtor {
+  new <O extends BooleanFieldOptions = BooleanFieldOptions>(options?: O): BooleanFieldInstance<O>;
+}
+interface HTMLFieldCtor {
+  new <O extends HTMLFieldOptions = HTMLFieldOptions>(options?: O): HTMLFieldInstance<O>;
+}
+interface ColorFieldCtor {
+  new <O extends ColorFieldOptions = ColorFieldOptions>(options?: O): ColorFieldInstance<O>;
+}
+interface FilePathFieldCtor {
+  new <O extends FilePathFieldOptions = FilePathFieldOptions>(options?: O): FilePathFieldInstance<O>;
+}
+interface ArrayFieldCtor {
+  new <Inner extends FieldInstance, O extends ArrayFieldOptions = ArrayFieldOptions>(element: Inner, options?: O): ArrayFieldInstance<Inner, O>;
+}
+interface SetFieldCtor {
+  new <Inner extends FieldInstance, O extends SetFieldOptions = SetFieldOptions>(element: Inner, options?: O): SetFieldInstance<Inner, O>;
+}
+/**
+ * Any document class — what `ForeignDocumentField` takes as its first
+ * argument. Declared structurally so the inference surface stays free of a
+ * dependency on a Foundry type package.
+ */
+type DocumentClass = abstract new (...args: never[]) => object;
+interface ForeignDocumentFieldCtor {
+  new <Doc extends DocumentClass, O extends ForeignDocumentFieldOptions = ForeignDocumentFieldOptions>(model: Doc, options?: O): ForeignDocumentFieldInstance<Doc, O>;
+}
+/** Any DataModel subclass — what the embedded fields take as their type. */
+type DataModelClass = abstract new (...args: never[]) => object;
+interface EmbeddedDataFieldCtor {
+  new <Model extends DataModelClass, O extends EmbeddedDataFieldOptions = EmbeddedDataFieldOptions>(model: Model, options?: O): EmbeddedDataFieldInstance<Model, O>;
+}
+interface EmbeddedDocumentFieldCtor {
+  new <Doc extends DataModelClass, O extends EmbeddedDocumentFieldOptions = EmbeddedDocumentFieldOptions>(model: Doc, options?: O): EmbeddedDocumentFieldInstance<Doc, O>;
+}
+interface TypedSchemaFieldCtor {
+  new <T extends Record<string, Record<string, FieldInstance>>, O extends TypedSchemaFieldOptions = TypedSchemaFieldOptions>(types: T, options?: O): TypedSchemaFieldInstance<T, O>;
+}
+interface SchemaFieldCtor {
+  new <S extends Record<string, FieldInstance>, O extends SchemaFieldOptions = SchemaFieldOptions>(fields: S, options?: O): SchemaFieldInstance<S, O>;
+}
+/**
+ * Typed bag returned by `fields()`. Each property is the corresponding
+ * `foundry.data.fields.*` class — the runtime value is Foundry's own
+ * constructor; the type is our overlay.
+ */
+interface FieldsApi {
+  readonly NumberField: NumberFieldCtor;
+  readonly StringField: StringFieldCtor;
+  readonly BooleanField: BooleanFieldCtor;
+  readonly HTMLField: HTMLFieldCtor;
+  readonly ColorField: ColorFieldCtor;
+  readonly FilePathField: FilePathFieldCtor;
+  readonly ArrayField: ArrayFieldCtor;
+  readonly SetField: SetFieldCtor;
+  readonly ForeignDocumentField: ForeignDocumentFieldCtor;
+  readonly SchemaField: SchemaFieldCtor;
+  readonly EmbeddedDataField: EmbeddedDataFieldCtor;
+  readonly EmbeddedDocumentField: EmbeddedDocumentFieldCtor;
+  readonly TypedSchemaField: TypedSchemaFieldCtor;
+}
+/**
+ * Resolve `globalThis.foundry.data.fields` and return it typed as `FieldsApi`.
+ *
+ * Call this inside `defineSchema()` (or any code that runs after Foundry's
+ * `init` hook). Calling at module scope will throw when imported from Node
+ * tests — the global only exists inside the Foundry runtime.
+ *
+ * @throws `VttfError` with code `VTTF-0002` when `foundry.data.fields` is
+ * missing.
+ */
+declare function fields(): FieldsApi;
+//#endregion
+//#region src/data/color.d.ts
+/**
+ * The shape a `ColorField` hands back.
+ *
+ * Foundry initializes the field into one of its own `Color` instances — a
+ * boxed 24-bit integer with derived accessors — rather than the CSS string it
+ * stores. Described structurally here rather than imported, because the
+ * inference surface deliberately does not depend on the Foundry type package.
+ *
+ * Members mirror the documented public accessors. `toString(radix)` is
+ * included because a colour is routinely interpolated straight into markup.
+ */
+interface Color {
+  /** False when the underlying value is not a valid colour. */
+  readonly valid: boolean;
+  /** CSS hexadecimal string, e.g. `#ff0000`. */
+  readonly css: string;
+  /** Normalized `[r, g, b]`, each 0–1. */
+  readonly rgb: [number, number, number];
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+  /** The largest of the three channels. */
+  readonly maximum: number;
+  /** The smallest of the three channels. */
+  readonly minimum: number;
+  /** Byte order flipped, for APIs that want BGR. */
+  readonly littleEndian: number;
+  readonly hsv: [number, number, number];
+  readonly hsl: [number, number, number];
+  /** The colour in linear space, for shader work. */
+  readonly linear: Color;
+  toString: (radix?: number) => string;
+  valueOf: () => number;
+}
+//#endregion
+//#region src/data/infer-schema.d.ts
+/**
+ * Flatten an intersection / mapped type into a plain object literal so IDE
+ * hovers stay readable (Matt Pocock's `Prettify`). Use on every public
+ * conditional-type surface — PRD §7 TS-hygiene rule.
+ */
+type Prettify<T> = { [K in keyof T]: T[K]; } & {};
+/**
+ * Whether a field's options gave an explicit `initial`.
+ *
+ * Presence of the key is the question, not its value — `{ initial: undefined }`
+ * is not an initial.
+ */
+type HasInitial<O> = O extends {
+  initial: unknown;
+} ? true : false;
+/**
+ * What a field class decides on its own behalf, for the options a schema
+ * leaves out.
+ *
+ * Every field type sets its own defaults, and they disagree. A number field
+ * is optional and nullable out of the box; a boolean field is required and
+ * starts at `false`. Reading a schema without knowing which defaults apply
+ * gets the shape wrong for exactly the fields people write most.
+ */
+interface FieldDefaults {
+  /** Whether the field is required when the schema does not say. */
+  required: boolean;
+  /** Whether the field admits `null` when the schema does not say. */
+  nullable: boolean;
+  /** Whether the field supplies a value when the schema gives no `initial`. */
+  populated: boolean;
+}
+/** Read an option the schema may have set, falling back to the field's default. */
+type Resolve<O, Key extends string, Fallback extends boolean> = O extends Record<Key, true> ? true : O extends Record<Key, false> ? false : Fallback;
+/**
+ * Widen a field's base type by what it can actually hold.
+ *
+ * Two independent widenings:
+ *
+ * - nullable admits `null`.
+ * - not required, with nothing to fall back on, admits `undefined`: cleaning
+ *   asks the field for an initial value and keeps whatever it gets, which is
+ *   `undefined` when there is no initial to give.
+ *
+ * A required field never widens to `undefined`. It would fail validation
+ * before the document existed, so there is no state to type.
+ */
+type Presence<O, T, D extends FieldDefaults> = T | (Resolve<O, 'nullable', D['nullable']> extends true ? null : never) | (Resolve<O, 'required', D['required']> extends true ? never : HasInitial<O> extends true ? never : D['populated'] extends true ? never : undefined);
+/** Optional, nullable, nothing to fall back on. */
+type NumberDefaults = {
+  required: false;
+  nullable: true;
+  populated: false;
+};
+/** Optional and non-nullable, so an unset one is simply absent. */
+type StringDefaults = {
+  required: false;
+  nullable: false;
+  populated: false;
+};
+/** Required, and starts at `false`. */
+type BooleanDefaults = {
+  required: true;
+  nullable: false;
+  populated: true;
+};
+/** Required and blank-friendly, so an unset one is the empty string. */
+type HTMLDefaults = {
+  required: true;
+  nullable: false;
+  populated: true;
+};
+/** Optional and nullable, but starts at `null` rather than absent. */
+type NullStartDefaults = {
+  required: false;
+  nullable: true;
+  populated: true;
+};
+/** Required, and builds its own empty value. */
+type ContainerDefaults = {
+  required: true;
+  nullable: false;
+  populated: true;
+};
+/** Required but nullable — an id that points at nothing is `null`. */
+type ReferenceDefaults = {
+  required: true;
+  nullable: true;
+  populated: false;
+};
+/**
+ * What a `ColorField` holds once the model is initialized.
+ *
+ * Not a string. The field casts its stored value to a CSS string, but
+ * `initialize` hands back a `Color` instance — so `system.tint` is an object
+ * with `.css`, `.rgb`, `.hex` and friends, and typing it as `string` makes
+ * every property access on it a lie the compiler accepts.
+ *
+ * It starts at `null`, so reading `.css` off a fresh document crashes unless
+ * the schema gives it an initial. That is what this type refuses.
+ */
+type ColorFieldValue<O> = Presence<O, Color, NullStartDefaults>;
+/**
+ * What a `ForeignDocumentField` holds once the model is initialized.
+ *
+ * With `idOnly`, the stored id string. Without it the field resolves to a
+ * getter, and the data model installs it as one — so reading the property
+ * gives the document instance, not the function that fetched it. It yields
+ * `null` when the id points at nothing, or when the parent lives in a
+ * compendium.
+ *
+ * Two caveats this does not encode, both narrow enough to document rather
+ * than type:
+ *
+ * - On the server the field keeps the id string in both cases, because there
+ *   are no collections to resolve against. System code runs on both sides,
+ *   but typing that union would put a string check in front of every read of
+ *   a document reference.
+ * - Under `readonly: true` the data model takes the read-only branch before
+ *   the getter branch, so the property keeps the resolver function itself.
+ *   The field turns that flag off by default and no schema has reason to
+ *   turn it back on.
+ */
+type ForeignDocumentValue<Doc extends DocumentClass, O> = Presence<O, O extends {
+  idOnly: true;
+} ? string : InstanceType<Doc>, ReferenceDefaults>;
+/**
+ * What a `TypedSchemaField` holds: one shape per entry, each carrying the
+ * key it was filed under as its `type`.
+ *
+ * The field supplies that `type` when an entry does not declare one — a
+ * required string validated to equal the key — so narrowing on `type` picks
+ * exactly one branch.
+ */
+type TypedSchemaValue<T extends Record<string, Record<string, FieldInstance>>> = { [K in keyof T]: Prettify<InferSchema<T[K]> & {
+  type: K;
+}>; }[keyof T];
+/**
+ * Map a single field instance to its runtime TypeScript type. `never` for
+ * shapes we don't recognise — the v1.0 `@vttforge/types` package will widen
+ * this matrix to the remaining Foundry fields.
+ */
+type InferField<F> = F extends NumberFieldInstance<infer O> ? Presence<O, number, NumberDefaults> : F extends StringFieldInstance<infer O> ? Presence<O, string, StringDefaults> : F extends BooleanFieldInstance<infer O> ? Presence<O, boolean, BooleanDefaults> : F extends HTMLFieldInstance<infer O> ? Presence<O, string, HTMLDefaults> : F extends ColorFieldInstance<infer O> ? ColorFieldValue<O> : F extends FilePathFieldInstance<infer O> ? Presence<O, string, NullStartDefaults> : F extends ForeignDocumentFieldInstance<infer Doc, infer O> ? ForeignDocumentValue<Doc, O> : F extends ArrayFieldInstance<infer Inner, infer O> ? Presence<O, InferField<Inner>[], ContainerDefaults> : F extends SetFieldInstance<infer Inner, infer O> ? Presence<O, Set<InferField<Inner>>, ContainerDefaults> : F extends SchemaFieldInstance<infer S, infer O> ? Presence<O, InferSchema<S>, ContainerDefaults> : F extends EmbeddedDocumentFieldInstance<infer Doc, infer O> ? Presence<O, InstanceType<Doc>, ReferenceDefaults> : F extends EmbeddedDataFieldInstance<infer Model, infer O> ? Presence<O, InstanceType<Model>, ContainerDefaults> : F extends TypedSchemaFieldInstance<infer T, infer O> ? Presence<O, TypedSchemaValue<T>, ContainerDefaults> : never;
+/**
+ * Map a `defineSchema()` return value to the corresponding `system` shape.
+ *
+ * @example
+ * ```ts
+ * class CharacterData extends BaseTypeDataModel() {
+ *   static defineSchema() {
+ *     const f = fields();
+ *     return {
+ *       level: new f.NumberField({ required: true, initial: 1 }),
+ *       biography: new f.HTMLField(),
+ *     };
+ *   }
+ * }
+ * type CharacterSystem = InferSchema<ReturnType<typeof CharacterData.defineSchema>>;
+ * // → { level: number; biography: string }
+ * ```
+ */
+type InferSchema<S extends Record<string, FieldInstance>> = Prettify<{ [K in keyof S]: InferField<S[K]>; }>;
+//#endregion
+//#region src/base-type-data-model.d.ts
+type AnyConstructor = new (...args: any[]) => any;
+/**
+ * Resolve the runtime base class, then build a mixin that adds VTTForge defaults.
+ *
+ * Why a function: subclasses are declared once at module load, but Foundry
+ * globals may not exist yet (test boot, ESM hoist). Calling `BaseTypeDataModel()`
+ * lazy-resolves the global at the moment of subclassing.
+ */
+/** The two hooks this base fills in, so a subclass can omit either. */
+interface TypeDataModelHooks {
+  prepareBaseData(): void;
+  prepareDerivedData(): void;
+}
+/**
+ * What an instance looks like when the schema is known.
+ *
+ * The schema's fields ARE the instance properties — inside
+ * `prepareDerivedData()` you read `this.level`, not `this.system.level`, and
+ * `actor.system` is this instance.
+ *
+ * Derived values are not in the schema, so they are not here either. Declare
+ * them on the subclass:
+ *
+ * ```ts
+ * declare armorClass: number;
+ * ```
+ */
+type TypedTypeDataModel<S extends Record<string, FieldInstance>> = InferSchema<S> & TypeDataModelHooks & {
+  /**
+   * Phantom property carrying the schema's inferred shape. Never assigned,
+   * never present at runtime — it exists so the type has a name:
+   *
+   * ```ts
+   * type CharacterSystem = CharacterData['$inferData'];
+   * ```
+   */
+  readonly $inferData: InferSchema<S>;
+};
+interface TypedTypeDataModelCtor<S extends Record<string, FieldInstance>> {
+  new (...args: any[]): TypedTypeDataModel<S>;
+  defineSchema(): S;
+  migrateData(data: Record<string, unknown>): Record<string, unknown>;
+}
+/**
+ * Build a base class with no knowledge of the schema.
+ *
+ * `this` inside the hooks is untyped. Pass your schema function instead to
+ * get the fields typed.
+ */
+declare function BaseTypeDataModel(): AnyConstructor;
+/**
+ * Build a base class that knows its schema.
+ *
+ * Hand it the function that returns your fields and it implements
+ * `static defineSchema()` for you, so the schema is written once:
+ *
+ * ```ts
+ * const defineCharacterSchema = () => {
+ *   const f = fields();
+ *   return { level: new f.NumberField({ required: true, nullable: false, initial: 1 }) };
+ * };
+ *
+ * class CharacterData extends BaseTypeDataModel(defineCharacterSchema) {
+ *   declare armorClass: number;
+ *   prepareDerivedData() {
+ *     this.armorClass = 10 + this.level; // this.level is number
+ *   }
+ * }
+ * ```
+ *
+ * It has to be a function, not an object: `fields()` reads a Foundry global
+ * that does not exist when the module is first evaluated.
+ *
+ * A subclass may still declare its own `static defineSchema()`; that one wins,
+ * the same as any other static.
+ */
+declare function BaseTypeDataModel<S extends Record<string, FieldInstance>>(defineSchema: () => S): TypedTypeDataModelCtor<S>;
+//#endregion
+//#region src/errors/registry.d.ts
+/**
+ * VTTF-NNNN error registry — append-only, stable across majors.
+ *
+ * Every error VTTForge throws has a numeric code (`VTTF-NNNN`) and a PascalCase
+ * `name` for stack-trace readability. Codes are URLs — `https://vttforge.dev/errors/VTTF-0001`
+ * eventually links to a docs page generated from this registry.
+ *
+ * Never renumber an entry. To deprecate, mark with `deprecated: true` and add a
+ * `replacedBy` pointer. Adding a new code: pick the next unused integer.
+ */
+type VttfErrorCode = `VTTF-${string}`;
+interface VttfErrorEntry {
+  readonly code: VttfErrorCode;
+  readonly name: string;
+  readonly summary: string;
+  readonly deprecated?: boolean;
+  readonly replacedBy?: VttfErrorCode;
+}
+/**
+ * Look up a registered entry by code. Throws if the code is unknown — the
+ * registry is the source of truth, so missing codes mean a typo.
+ */
+declare function getErrorEntry(code: VttfErrorCode): VttfErrorEntry;
+/**
+ * Return every entry currently in the registry. Used by codegen to emit the
+ * runtime constants and the JSON manifest that powers the docs pages.
+ */
+declare function listErrorEntries(): readonly VttfErrorEntry[];
+declare function docsUrlFor(code: VttfErrorCode): string;
+/**
+ * VttfError — every error VTTForge throws extends this.
+ *
+ * - `code` is the registry key (string-narrowed).
+ * - `name` is the PascalCase name from the registry — shows up in stack traces.
+ * - `docsUrl` points at the docs page.
+ * - `cause` uses the native ES2022 mechanism. Multiple causes => pass an
+ *   `AggregateError` as the cause.
+ */
+declare class VttfError extends Error {
+  readonly code: VttfErrorCode;
+  readonly docsUrl: string;
+  constructor(code: VttfErrorCode, message?: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/errors/manifest.d.ts
+declare const ERROR_MANIFEST_VERSION: 1;
+interface ErrorManifest {
+  readonly version: typeof ERROR_MANIFEST_VERSION;
+  readonly package: '@vttforge/core';
+  readonly entries: ReadonlyArray<VttfErrorEntry>;
+}
+/**
+ * Snapshot the current registry as a manifest object. Recomputed on every
+ * call — cheap (the registry is a frozen literal). For the JSON projection
+ * shipped with the package, see `dist/errors-manifest.json`.
+ */
+declare function getErrorManifest(): ErrorManifest;
+//#endregion
+//#region src/foundry-globals.d.ts
+/**
+ * Minimal type-only contracts for the Foundry v13+ globals VTTForge core touches.
+ *
+ * Intentionally narrow — full Foundry typing lives in `@vttforge/types` (v1.0)
+ * built on top of `fvtt-types`. We mirror just the surface we use so the core
+ * package compiles without pulling in fvtt-types' git-SHA dependency.
+ *
+ * Every consumer is expected to run inside the Foundry runtime; we read these
+ * via `globalThis` and never bundle Foundry itself.
+ */
+type HookCallback<Args extends readonly unknown[] = readonly unknown[]> = (...args: Args) => unknown | Promise<unknown>;
+interface HooksApi {
+  once<Args extends readonly unknown[]>(event: string, fn: HookCallback<Args>): number;
+  on<Args extends readonly unknown[]>(event: string, fn: HookCallback<Args>): number;
+  off(event: string, idOrFn: number | HookCallback): boolean;
+  call(event: string, ...args: readonly unknown[]): boolean;
+  callAll(event: string, ...args: readonly unknown[]): boolean;
+}
+type SettingScope = 'world' | 'client';
+interface SettingConfig<T = unknown> {
+  readonly name?: string;
+  readonly hint?: string;
+  readonly scope: SettingScope;
+  readonly config?: boolean;
+  readonly type: unknown;
+  readonly default: T;
+  readonly choices?: Readonly<Record<string, string>>;
+  readonly range?: {
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number;
+  };
+  readonly onChange?: (value: T) => void;
+}
+interface GameSettingsApi {
+  register<T>(namespace: string, key: string, config: SettingConfig<T>): void;
+  get<T = unknown>(namespace: string, key: string): T;
+  set<T>(namespace: string, key: string, value: T): Promise<T>;
+}
+interface GameApi {
+  readonly settings: GameSettingsApi;
+  readonly user?: {
+    readonly isGM: boolean;
+  };
+}
+type ConfigCollection<T = unknown> = Record<string, T>;
+interface ActorConfig {
+  documentClass?: unknown;
+  dataModels: ConfigCollection;
+}
+interface ItemConfig {
+  documentClass?: unknown;
+  dataModels: ConfigCollection;
+}
+interface CombatConfig {
+  initiative?: {
+    formula: string;
+    decimals?: number;
+  };
+}
+interface ActiveEffectConfig {
+  legacyTransferral?: boolean;
+}
+interface FoundryConfig {
+  Actor: ActorConfig;
+  Item: ItemConfig;
+  Combat: CombatConfig;
+  ActiveEffect: ActiveEffectConfig;
+  statusEffects?: unknown[];
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/migrations/types.d.ts
+interface Migration {
+  /** Semver version this migration brings the world to. */
+  readonly version: string;
+  /** Optional human-readable description — logged when the migration runs and shown in error messages. */
+  readonly description?: string;
+  /** The migration body. May be sync or async. Should be idempotent (safe to re-run after partial failure). */
+  readonly fn: () => void | Promise<void>;
+}
+interface MigrationLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+interface MigrationRunnerOptions {
+  /** System id — used as the `game.settings` namespace. */
+  readonly systemId: string;
+  /** Migrations in ascending version order. Empty array is allowed (`run()` is a no-op then). */
+  readonly migrations: ReadonlyArray<Migration>;
+  /** Settings key under `systemId`. Defaults to `'schemaVersion'`. */
+  readonly settingKey?: string;
+  /**
+   * Compatibility floor — worlds with a stored schemaVersion strictly older than this
+   * throw `VttfError VTTF-0005` instead of running migrations. Mirrors the
+   * `flags.<systemId>.compatibleMigrationVersion` declaration in `system.json`.
+   */
+  readonly compatibleVersion?: string;
+  /**
+   * Override the semver comparator. Defaults to `foundry.utils.isNewerVersion`
+   * resolved at call time. Test-only injection.
+   */
+  readonly isNewerVersion?: (next: string, current: string) => boolean;
+  /**
+   * Override `game.settings`. Defaults to `globalThis.game.settings` resolved
+   * at call time. Test-only injection.
+   */
+  readonly settings?: GameSettingsApi;
+  /**
+   * Override the logger. Defaults to a `console` + `ui.notifications` adapter.
+   * Test-only injection.
+   */
+  readonly logger?: MigrationLogger;
+}
+interface MigrationRunner {
+  /** The target version (last migration's `version`, or `'0.0.0'` if the list is empty). */
+  readonly targetVersion: string;
+  /**
+   * Register the `schemaVersion` setting. Call once from your `init` hook so
+   * Foundry knows about it before any world load. Re-calls are idempotent (the
+   * underlying `game.settings.register` enforces that).
+   */
+  register(): void;
+  /**
+   * Run every migration whose version is newer than the stored
+   * `schemaVersion`, in order. Returns the list of versions actually executed
+   * (empty when the world is already up to date). Throws `VttfError VTTF-0004`
+   * wrapping the original error if any migration throws; throws
+   * `VttfError VTTF-0005` if the stored version is older than `compatibleVersion`.
+   *
+   * Call from your `ready` hook, gated by `game.user.isGM` — this method does
+   * NOT enforce GM-only itself so consumers can compose differently if needed.
+   */
+  run(): Promise<ReadonlyArray<string>>;
+}
+//#endregion
+//#region src/migrations/runner.d.ts
+/**
+ * Build a migration runner for a system. See module header for the failure
+ * semantics; see `Migration` JSDoc for the per-entry shape.
+ *
+ * @example
+ * ```ts
+ * const migrations = createMigrationRunner({
+ *   systemId: 'my-system',
+ *   migrations: [
+ *     { version: '1.0.0', description: 'Rename bio → biography', fn: migrateV1 },
+ *     { version: '2.0.0', description: 'Add hp.temp', fn: migrateV2 },
+ *   ],
+ *   compatibleVersion: '0.9.0',
+ * });
+ *
+ * registerSystem({
+ *   id: 'my-system',
+ *   onAfterInit: () => migrations.register(),
+ *   onReady: async () => {
+ *     if (!game.user.isGM) return;
+ *     await migrations.run();
+ *   },
+ * });
+ * ```
+ */
+declare function createMigrationRunner(options: MigrationRunnerOptions): MigrationRunner;
+//#endregion
+//#region src/register-module.d.ts
+/**
+ * registerModule — the module counterpart to `registerSystem`.
+ *
+ * A module is a guest in someone else's world, and Foundry enforces that. The
+ * two differences that matter:
+ *
+ * - **Sub-type keys are namespaced.** A system registers `character`; a module
+ *   registering the same thing must register `<module-id>.character`, and the
+ *   manifest must declare it under `documentTypes`. Forget the prefix and the
+ *   type silently never appears. This function adds it for you.
+ * - **A module never owns the globals.** Document classes, the initiative
+ *   formula and the status-effect array belong to the system. So there is no
+ *   option here to replace them — `statusEffects` only appends, which is what
+ *   a module is allowed to do.
+ */
+interface ModuleRegistration {
+  /** Module id — must match the folder name and `module.json` `id`. */
+  readonly id: string;
+  /**
+   * Actor sub-types this module contributes, keyed by the bare type name.
+   * Registered under `<id>.<type>`, so declare them the same way in
+   * `documentTypes.Actor` in your manifest.
+   */
+  readonly actorDataModels?: Readonly<Record<string, unknown>>;
+  /** Item sub-types, same rule as `actorDataModels`. */
+  readonly itemDataModels?: Readonly<Record<string, unknown>>;
+  /**
+   * Status effects to append to `CONFIG.statusEffects`.
+   *
+   * Appended, never assigned: the array belongs to the system, and replacing
+   * it would delete conditions the world depends on.
+   */
+  readonly statusEffects?: readonly unknown[];
+  /** Runs before any CONFIG mutation — the usual home for the module API. */
+  readonly onBeforeInit?: () => void;
+  /** Runs after the mutations above, inside the same `init` hook. */
+  readonly onAfterInit?: () => void;
+  /**
+   * Runs once on `ready`.
+   *
+   * **Not GM-gated.** Guard inside your callback when the work is GM-only.
+   */
+  readonly onReady?: () => void | Promise<void>;
+}
+/**
+ * The key Foundry files a module's document sub-type under.
+ *
+ * Use it wherever you name the type outside `registerModule` — registering the
+ * sheet, checking `actor.type`, writing `documentTypes` in the manifest. The
+ * prefix is easy to get wrong by hand and fails silently when you do.
+ *
+ * @example
+ * ```ts
+ * moduleSubType('pdf-character-sheet', 'pdf'); // 'pdf-character-sheet.pdf'
+ * ```
+ */
+declare function moduleSubType(moduleId: string, type: string): string;
+/**
+ * Register a Foundry module with VTTForge.
+ *
+ * Calling twice with the same `id` throws VTTF-0001 — almost always a
+ * hot-reload artefact or a duplicate import. The CONFIG mutations are deferred
+ * until Foundry's `init` hook fires.
+ */
+declare function registerModule(config: ModuleRegistration): ModuleRegistration;
+//#endregion
+//#region src/register-system.d.ts
+interface SystemRegistration {
+  /** System id — must match the folder name and `system.json` `id`. */
+  readonly id: string;
+  /** Map of `documentTypes.Actor` key → TypeDataModel class. */
+  readonly actorDataModels?: Readonly<Record<string, unknown>>;
+  /** Map of `documentTypes.Item` key → TypeDataModel class. */
+  readonly itemDataModels?: Readonly<Record<string, unknown>>;
+  /** Replacement for `CONFIG.Actor.documentClass`. */
+  readonly actorDocumentClass?: unknown;
+  /** Replacement for `CONFIG.Item.documentClass`. */
+  readonly itemDocumentClass?: unknown;
+  /** Global initiative formula — assigned to `CONFIG.Combat.initiative`. */
+  readonly combat?: CombatConfig;
+  /** Disables legacy Active Effect transferral. Defaults to true. */
+  readonly activeEffect?: ActiveEffectConfig;
+  /**
+   * Replaces `CONFIG.statusEffects` (systems own this array — modules push).
+   * If omitted, the existing array is kept untouched.
+   */
+  readonly statusEffects?: readonly unknown[];
+  /**
+   * Optional pre-init hook for work that has to run before any of the CONFIG
+   * mutations (rare — usually used to assign `globalThis.<systemId>` API).
+   */
+  readonly onBeforeInit?: () => void;
+  /** Optional post-init hook for work that depends on the mutations above. */
+  readonly onAfterInit?: () => void;
+  /**
+   * Optional `ready` hook — fires once after Foundry has finished bootstrap.
+   * The natural home for migration runners (`createMigrationRunner().run()`).
+   *
+   * **Not GM-gated.** Guard inside your callback (`if (!game.user.isGM) return;`)
+   * when the work is GM-only — migrations always are.
+   */
+  readonly onReady?: () => void | Promise<void>;
+}
+/**
+ * Register a Foundry system with VTTForge. Idempotency: the same `id` calling
+ * twice throws VTTF-0001 — almost always a hot-reload or duplicate import bug.
+ *
+ * Returns the registration object so consumers can inspect what was applied
+ * (useful in tests). The actual CONFIG mutations are deferred until Foundry's
+ * `init` hook fires.
+ */
+declare function registerSystem(config: SystemRegistration): SystemRegistration;
+//#endregion
+//#region src/system-config.d.ts
+declare class SystemConfig {
+  #private;
+  readonly systemId: string;
+  constructor(systemId: string);
+  register<T>(key: string, config: SettingConfig<T>): void;
+  get<T>(key: string): T;
+  set<T>(key: string, value: T): Promise<T>;
+  isRegistered(key: string): boolean;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * @vttforge/core — runtime utilities for FoundryVTT v13+ systems and modules.
+ *
+ * v0.1 surface:
+ *
+ *   - registerSystem()             — one-call init, replaces Hooks.once("init")
+ *   - registerModule()             — the same for modules, with namespaced sub-types
+ *   - SystemConfig                 — typed wrapper around game.settings
+ *   - BaseTypeDataModel()          — TypeDataModel with safe migrateData default
+ *   - BaseActorSheet()             — ActorSheetV2 + HandlebarsApplicationMixin
+ *   - BaseItemSheet()              — ItemSheetV2 + HandlebarsApplicationMixin
+ *   - fields()                     — typed bag of foundry.data.fields constructors
+ *   - InferSchema<T>               — derive `system` shape from defineSchema()
+ *   - createMigrationRunner()      — declarative schema migrations (register + run)
+ *   - VttfError + error registry   — VTTF-NNNN codes with docs URLs
+ *
+ * Foundry classes are resolved from `globalThis.foundry` lazily so the package
+ * imports cleanly in Node/tests; concrete Foundry typing arrives with
+ * `@vttforge/types` in v1.0.
+ */
+declare const VTTFORGE_CORE_VERSION = "0.2.0";
+//#endregion
+export { type ActiveEffectConfig, type ArrayFieldCtor, type ArrayFieldInstance, type ArrayFieldOptions, BaseActorSheet, BaseItemSheet, BaseTypeDataModel, type BooleanFieldCtor, type BooleanFieldInstance, type BooleanFieldOptions, type ColorFieldCtor, type ColorFieldInstance, type ColorFieldOptions, type CombatConfig, type DataFieldOptions, type DataModelClass, type DocumentClass, type DragDropConfig, ERROR_MANIFEST_VERSION, type EmbeddedDataFieldCtor, type EmbeddedDataFieldInstance, type EmbeddedDataFieldOptions, type EmbeddedDocumentFieldCtor, type EmbeddedDocumentFieldInstance, type EmbeddedDocumentFieldOptions, type ErrorManifest, type FieldInstance, type FieldsApi, type FilePathFieldCtor, type FilePathFieldInstance, type FilePathFieldOptions, type ForeignDocumentFieldCtor, type ForeignDocumentFieldInstance, type ForeignDocumentFieldOptions, type FoundryConfig, type GameApi, type GameSettingsApi, type HTMLFieldCtor, type HTMLFieldInstance, type HTMLFieldOptions, type HookCallback, type HooksApi, type InferField, type InferSchema, type Migration, type MigrationLogger, type MigrationRunner, type MigrationRunnerOptions, type ModuleRegistration, type NumberFieldCtor, type NumberFieldInstance, type NumberFieldOptions, type Prettify, type SchemaFieldCtor, type SchemaFieldInstance, type SchemaFieldOptions, type SetFieldCtor, type SetFieldInstance, type SetFieldOptions, type SettingConfig, type SettingScope, type SheetBaseCtor, type SheetBaseStatics, type StringFieldCtor, type StringFieldInstance, type StringFieldOptions, SystemConfig, type SystemRegistration, type TypeDataModelHooks, type TypedSchemaFieldCtor, type TypedSchemaFieldInstance, type TypedSchemaFieldOptions, type TypedTypeDataModel, type TypedTypeDataModelCtor, VTTFORGE_CORE_VERSION, VTTFORGE_SHEET_CLASS, VttfError, type VttfErrorCode, type VttfErrorEntry, createMigrationRunner, docsUrlFor, fields, getErrorEntry, getErrorManifest, listErrorEntries, moduleSubType, registerModule, registerSystem };
+//# sourceMappingURL=index.d.mts.map