@vttforge/core 0.11.2 → 0.12.0

package/dist/index.d.mts

@@ -1,107 +1,4 @@
-//#region src/foundry-base.d.ts
-/**
- * How a base factory reports what it returns.
- *
- * These factories mix VTTForge behaviour into a Foundry class resolved at
- * runtime, so the result has two halves: what we add, and what Foundry brings.
- *
- * ## What the index signature cost
- *
- * The first version returned `any` for the whole thing. The second kept our
- * half typed and let Foundry's through `[member: string]: any`. Both were
- * measured against two real consumers, and the index signature turned out to
- * be the worse of the two failures rather than a middle ground:
- *
- * ```ts
- * const viewer = new PdfViewer();
- * viewer.goToPage(3);      // no such method — accepted
- * viewer.tpyoDeVerdade();  // not even a real name — accepted
- * ```
- *
- * A module shipped a release calling `url` and `goToPage` on a viewer that
- * had neither, and nothing reported it. An index signature makes every
- * property access legal, so a typo in the consumer's own subclass reads as
- * valid code.
- *
- * And it did not even buy the thing it looked like it bought:
- *
- * ```
- * error TS4113: This member cannot have an 'override' modifier because it is
- * not declared in the base class.
- * ```
- *
- * An index signature is not a declaration, so `override` on a Foundry member
- * was rejected anyway. It permitted what should have failed and forbade what
- * should have worked.
- *
- * ## What replaced it
- *
- * The Foundry members these factories actually stand on are written down
- * below. Removing the index signature and running both consumers produced
- * thirty-three errors naming eight distinct members — a set small enough to
- * declare, which is what settled the design. It is not the whole ApplicationV2
- * surface and does not claim to be; `@vttforge/types` is where that lands.
- *
- * Reaching a member that is not here is a cast, and a cast is a sentence you
- * write on purpose. That is the difference from an index signature, which
- * writes it for you on every line.
- */
-/**
- * The ApplicationV2 surface these bases rely on.
- *
- * Deliberately small. Every member here is one a real consumer used, not one
- * that exists in Foundry — the point is to describe what the factories stand
- * on, not to restate Foundry's API.
- */
-interface ApplicationV2Members {
-  /** The window's root element once rendered. `undefined` before that. */
-  readonly element: HTMLElement | undefined;
-  /** The window title, from `options.window.title`. */
-  readonly title: string;
-  /** Whether the window is currently rendered. */
-  readonly rendered: boolean;
-  /** Render the application. Resolves when the render completes. */
-  render(options?: unknown, _options?: unknown): Promise<unknown>;
-  /** Close the window. */
-  close(options?: unknown): Promise<unknown>;
-  /** Build the render context. */
-  _prepareContext(options: unknown): Promise<Record<string, unknown>>;
-  /** Runs after every render. */
-  _onRender(context: unknown, options: unknown): void;
-  /** Runs after the first render only. */
-  _onFirstRender(context: unknown, options: unknown): void;
-  /** The resolved options this instance was constructed with. */
-  readonly options: Record<string, unknown>;
-}
-/**
- * What a document sheet adds on top of an application.
- */
-interface DocumentSheetV2Members extends ApplicationV2Members {
-  /**
-   * The document this sheet is for.
-   *
-   * Typed loosely on purpose: which document, and what its `system` holds,
-   * is the consumer's to know. Narrow it with a getter on your subclass.
-   */
-  readonly document: unknown;
-  /** Whether the current user may edit this document. */
-  readonly isEditable: boolean;
-}
-/**
- * A class this SDK built on top of a Foundry one.
- *
- * `Added` is what the factory contributes; `Foundry` is the part of Foundry's
- * own surface the factory stands on. Anything outside both is a cast — see
- * the note at the top of this file for why that is the point.
- *
- * `Foundry` defaults to nothing rather than to the application surface. A
- * `TypeDataModel` is not an application, and defaulting the other way handed
- * data models a `render` and a `close` they do not have.
- */
-type VttforgeClass<Added, Statics = unknown, Foundry = unknown> = Statics & {
-  new (...args: any[]): Added & Foundry;
-};
-//#endregion
+import { ApplicationV2Members, DocumentSheetV2Members, VttforgeClass } from "@vttforge/types";
 //#region src/base-actor-sheet.d.ts
 /**
  * Declarative DragDrop entry consumed by `_onRender`. Mirrors the
@@ -122,7 +19,7 @@ interface DragDropConfig {
  * 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 —
+ * `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.
  *
@@ -141,7 +38,7 @@ interface SheetBaseStatics {
  * What the sheet factories add on top of Foundry's own sheet.
  *
  * Only the members a subclass actually reaches for. The rest of the Foundry
- * surface stays reachable and untyped until `@vttforge/types` describes it —
+ * surface stays reachable and untyped until `@vttforge/types` describes it;
  * see `DocumentSheetV2Members`.
  */
 interface SheetBaseMembers {
@@ -162,7 +59,7 @@ interface SheetBaseMembers {
    * Foundry's own drop entry points, implemented here to resolve the payload
    * and hand it to the `onDropX` hook above.
    *
-   * Declared because the base really does define them — an earlier version
+   * Declared because the base really does define them. An earlier version
    * left them off, and nothing said so while an index signature was making
    * every member name legal. Override `onDropItem` rather than this.
    */
@@ -247,7 +144,7 @@ interface BaseDocumentSheetMembers {
   /**
    * Put the rendered content in the window.
    *
-   * The whole-content swap. Override for a sheet that updates in place —
+   * The whole-content swap. Override for a sheet that updates in place:
    * a viewer that keeps its scroll position across a page turn, say.
    */
   _replaceHTML(result: HTMLElement, content: HTMLElement): void;
@@ -302,7 +199,7 @@ declare function BaseItemSheet(): SheetBaseCtor;
  * 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
+ * `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).
@@ -352,7 +249,7 @@ interface ArrayFieldOptions extends DataFieldOptions {
 }
 type SchemaFieldOptions = DataFieldOptions;
 /**
- * `SetField` takes the same options as `ArrayField` — it is a subclass whose
+ * `SetField` takes the same options as `ArrayField`. It is a subclass whose
  * only difference is what `initialize` hands back.
  */
 type SetFieldOptions = ArrayFieldOptions;
@@ -360,7 +257,7 @@ 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
+   * 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.
    */
@@ -376,7 +273,7 @@ type TypedSchemaFieldOptions = DataFieldOptions;
 //#region src/data/fields.d.ts
 declare const BRAND: unique symbol;
 /**
- * Anything that satisfies the `FieldInstance` shape — used as the inner-field
+ * 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.
  */
@@ -417,7 +314,7 @@ interface ArrayFieldInstance<Inner extends FieldInstance = FieldInstance, O exte
  * 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
+ * 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.
  */
@@ -432,7 +329,7 @@ interface SetFieldInstance<Inner extends FieldInstance = FieldInstance, O extend
  * 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.
+ * instance, or `null` when it is gone or lives in a compendium.
  *
  * The field is nullable by default, so both shapes admit `null`.
  */
@@ -445,7 +342,7 @@ interface ForeignDocumentFieldInstance<Doc extends DocumentClass = DocumentClass
  * 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
+ * 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 {
@@ -468,8 +365,8 @@ interface EmbeddedDocumentFieldInstance<Doc extends DataModelClass = DataModelCl
  * 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
+ * `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 {
@@ -507,7 +404,7 @@ 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
+ * 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.
  */
@@ -515,7 +412,7 @@ 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. */
+/** 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>;
@@ -531,7 +428,7 @@ interface SchemaFieldCtor {
 }
 /**
  * Typed bag returned by `fields()`. Each property is the corresponding
- * `foundry.data.fields.*` class — the runtime value is Foundry's own
+ * `foundry.data.fields.*` class. The runtime value is Foundry's own
  * constructor; the type is our overlay.
  */
 interface FieldsApi {
@@ -554,7 +451,7 @@ interface 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.
+ * tests; the global only exists inside the Foundry runtime.
  *
  * @throws `VttfError` with code `VTTF-0002` when `foundry.data.fields` is
  * missing.
@@ -565,8 +462,8 @@ declare function fields(): FieldsApi;
 /**
  * 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
+ * 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.
  *
@@ -601,13 +498,13 @@ interface Color {
 /**
  * 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.
+ * conditional-type surface, for IDE performance.
  */
 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 }`
+ * Presence of the key is the question, not its value: `{ initial: undefined }`
  * is not an initial.
  */
 type HasInitial<O> = O extends {
@@ -682,7 +579,7 @@ type ContainerDefaults = {
   nullable: false;
   populated: true;
 };
-/** Required but nullable — an id that points at nothing is `null`. */
+/** Required but nullable: an id that points at nothing is `null`. */
 type ReferenceDefaults = {
   required: true;
   nullable: true;
@@ -692,7 +589,7 @@ type ReferenceDefaults = {
  * 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
+ * `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.
  *
@@ -704,7 +601,7 @@ 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
+ * 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.
@@ -728,8 +625,8 @@ type ForeignDocumentValue<Doc extends DocumentClass, O> = Presence<O, O extends
  * 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
+ * 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]> & {
@@ -737,7 +634,7 @@ type TypedSchemaValue<T extends Record<string, Record<string, FieldInstance>>> =
 }>; }[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
+ * shapes we don't recognise; `@vttforge/types` 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;
@@ -777,7 +674,7 @@ interface TypeDataModelHooks {
 /**
  * What an instance looks like when the schema is known.
  *
- * The schema's fields ARE the instance properties — inside
+ * The schema's fields ARE the instance properties: inside
  * `prepareDerivedData()` you read `this.level`, not `this.system.level`, and
  * `actor.system` is this instance.
  *
@@ -791,7 +688,7 @@ interface TypeDataModelHooks {
 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:
+   * never present at runtime; it exists so the type has a name:
    *
    * ```ts
    * type CharacterSystem = CharacterData['$inferData'];
@@ -841,10 +738,10 @@ declare function BaseTypeDataModel<S extends Record<string, FieldInstance>>(defi
 //#endregion
 //#region src/errors/registry.d.ts
 /**
- * VTTF-NNNN error registry — append-only, stable across majors.
+ * 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`
+ * `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
@@ -859,7 +756,7 @@ interface VttfErrorEntry {
   readonly replacedBy?: VttfErrorCode;
 }
 /**
- * Look up a registered entry by code. Throws if the code is unknown — the
+ * 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;
@@ -870,10 +767,10 @@ declare function getErrorEntry(code: VttfErrorCode): VttfErrorEntry;
 declare function listErrorEntries(): readonly VttfErrorEntry[];
 declare function docsUrlFor(code: VttfErrorCode): string;
 /**
- * VttfError — every error VTTForge throws extends this.
+ * 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.
+ * - `name` is the PascalCase name from the registry; it 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.
@@ -893,7 +790,7 @@ interface ErrorManifest {
 }
 /**
  * Snapshot the current registry as a manifest object. Recomputed on every
- * call — cheap (the registry is a frozen literal). For the JSON projection
+ * call, cheap because the registry is a frozen literal. For the JSON projection
  * shipped with the package, see `dist/errors-manifest.json`.
  */
 declare function getErrorManifest(): ErrorManifest;
@@ -902,7 +799,7 @@ declare function getErrorManifest(): ErrorManifest;
 /**
  * Minimal type-only contracts for the Foundry v13+ globals VTTForge core touches.
  *
- * Intentionally narrow — full Foundry typing lives in `@vttforge/types` (v1.0)
+ * Intentionally narrow. The Foundry members the bases stand on are in `@vttforge/types`;
  * 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.
  *
@@ -975,7 +872,7 @@ interface FoundryConfig {
 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. */
+  /** 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>;
@@ -986,14 +883,14 @@ interface MigrationLogger {
   error(message: string): void;
 }
 interface MigrationRunnerOptions {
-  /** System id — used as the `game.settings` namespace. */
+  /** 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
+   * 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`.
    */
@@ -1030,7 +927,7 @@ interface MigrationRunner {
    * 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
+   * 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>>;
@@ -1068,8 +965,8 @@ declare function createMigrationRunner(options: MigrationRunnerOptions): Migrati
 /**
  * Text enricher registration.
  *
- * An enricher turns a pattern in any rich text field — chat, journals, item
- * descriptions — into markup. `@PDF[handbook|page=12]{Player's Handbook}`
+ * An enricher turns a pattern in any rich text field (chat, journals, item
+ * descriptions) into markup. `@PDF[handbook|page=12]{Player's Handbook}`
  * becomes a link that opens the book at that page.
  *
  * `CONFIG.TextEditor.enrichers` is a plain array, so registering by hand is one
@@ -1081,7 +978,7 @@ declare function createMigrationRunner(options: MigrationRunnerOptions): Migrati
  *   nothing to fire the callback from. The enricher still produces markup, so
  *   the text looks right and only the behaviour is missing.
  * - **A duplicate `id` silently loses.** The wrapper stores the id as an
- *   attribute and looks the enricher back up with `find` — first match wins.
+ *   attribute and looks the enricher back up with `find`; first match wins.
  *   Two packages using `link` means the first one's `onRender` runs against the
  *   second one's markup. Only reproducible with both installed.
  * - **A pattern without the `g` flag throws.** Enrichment runs the pattern
@@ -1105,13 +1002,13 @@ interface EnricherRegistration {
    */
   readonly id: string;
   /**
-   * The pattern to match. Must carry the `g` flag — enrichment runs it through
+   * The pattern to match. Must carry the `g` flag: enrichment runs it through
    * `matchAll`, which refuses a non-global regex.
    */
   readonly pattern: RegExp;
   /**
    * Build the replacement for one match. Return `null` to leave the text
-   * alone — the usual answer when the thing referenced does not exist or the
+   * alone, the usual answer when the thing referenced does not exist or the
    * reader is not allowed to see it.
    */
   readonly enricher: (match: RegExpMatchArray, options?: unknown) => Promise<HTMLElement | null> | HTMLElement | null;
@@ -1146,7 +1043,7 @@ declare function registerEnrichers(packageId: string, enrichers: readonly Enrich
  * same sheet registers as `mo` in one build and `vo` in the next. The saved
  * key then names a sheet that no longer exists, Foundry falls back to the
  * default, and the reader's chosen sheet is gone with nothing in the console.
- * It hits released upgrades, not just a dev loop — pick the sheet in 1.0, ship
+ * It hits released upgrades, not just a dev loop: pick the sheet in 1.0, ship
  * 1.1, and the choice is lost.
  *
  * So the caller names the sheet and VTTForge fixes the class name to that
@@ -1176,7 +1073,7 @@ interface SheetRegistration {
    * Document sub-types the sheet applies to. Omit to offer it for every type.
    *
    * A module registering a sheet for its own sub-type must pass the prefixed
-   * key — `moduleSubType(id, 'pdf')`, not `'pdf'`.
+   * key: `moduleSubType(id, 'pdf')`, not `'pdf'`.
    */
   readonly types?: readonly string[];
   /** Localization key for the name shown in the sheet picker. */
@@ -1198,7 +1095,7 @@ declare function registerSheets(packageId: string, sheets: readonly SheetRegistr
 //#endregion
 //#region src/register-module.d.ts
 interface ModuleRegistration {
-  /** Module id — must match the folder name and `module.json` `id`. */
+  /** 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.
@@ -1232,10 +1129,28 @@ interface ModuleRegistration {
    * with it. See `registerEnrichers`.
    */
   readonly enrichers?: readonly EnricherRegistration[];
-  /** Runs before any CONFIG mutation — the usual home for the module API. */
+  /** 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 on `i18nInit`, after Foundry loads the language files.
+   *
+   * This is where CONFIG labels get translated. `game.i18n` is not loaded
+   * during `init`, so `game.i18n.localize()` called there returns the key you
+   * passed it, and the untranslated key is what players see.
+   */
+  readonly onI18nInit?: () => void;
+  /**
+   * Runs on `setup`, after every package is loaded and before the canvas is
+   * drawn.
+   *
+   * For a module this is also the first point where the system it is extending
+   * has finished its own `init`, so it is the place to read what the system
+   * registered. A setting registered during `init` can only be read from here
+   * on. Keep world data out of it, that is `onReady`.
+   */
+  readonly onSetup?: () => void | Promise<void>;
   /**
    * Runs once on `ready`.
    *
@@ -1246,7 +1161,7 @@ interface ModuleRegistration {
 /**
  * The key Foundry files a module's document sub-type under.
  *
- * Use it wherever you name the type outside `registerModule` — registering the
+ * 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.
  *
@@ -1259,7 +1174,7 @@ 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
+ * 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.
  */
@@ -1267,7 +1182,7 @@ 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`. */
+  /** 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>>;
@@ -1277,12 +1192,12 @@ interface SystemRegistration {
   readonly actorDocumentClass?: unknown;
   /** Replacement for `CONFIG.Item.documentClass`. */
   readonly itemDocumentClass?: unknown;
-  /** Global initiative formula — assigned to `CONFIG.Combat.initiative`. */
+  /** 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).
+   * Replaces `CONFIG.statusEffects` (systems own this array; modules push).
    * If omitted, the existing array is kept untouched.
    */
   readonly statusEffects?: readonly unknown[];
@@ -1305,23 +1220,52 @@ interface SystemRegistration {
   readonly enrichers?: readonly EnricherRegistration[];
   /**
    * Optional pre-init hook for work that has to run before any of the CONFIG
-   * mutations (rare — usually used to assign `globalThis.<systemId>` API).
+   * 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.
+   * Optional `i18nInit` hook. Fires after Foundry loads the language files and
+   * before `setup`.
+   *
+   * This is where CONFIG labels get translated. `game.i18n` is not loaded
+   * during `init`, so `game.i18n.localize()` called there returns the key you
+   * passed it, and the untranslated key is what players see. Do it here
+   * instead, once, rather than localizing on every render.
+   *
+   * @example
+   * ```ts
+   * onI18nInit: () => {
+   *   for (const ability of Object.values(CONFIG.MY_SYSTEM.abilities)) {
+   *     ability.label = game.i18n.localize(ability.label);
+   *   }
+   * },
+   * ```
+   */
+  readonly onI18nInit?: () => void;
+  /**
+   * Optional `setup` hook. Fires after every package is loaded and before the
+   * canvas is drawn.
+   *
+   * The home for work that `init` is too early for and `ready` too late: a
+   * setting registered during `init` can only be read from here on, and
+   * compendium packs are available. Keep world data out of it, that is
+   * `onReady`.
+   */
+  readonly onSetup?: () => void | Promise<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.
+   * when the work is GM-only, and 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.
+ * 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
@@ -1342,26 +1286,26 @@ declare class SystemConfig {
 //#endregion
 //#region src/index.d.ts
 /**
- * @vttforge/core — runtime utilities for FoundryVTT v13+ systems and modules.
+ * @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
+ *   - 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.
+ * imports cleanly in Node/tests. The Foundry members the bases stand on are
+ * declared in `@vttforge/types` and re-exported here.
  */
 declare const VTTFORGE_CORE_VERSION: string;
 //#endregion
-export { type ActiveEffectConfig, type ApplicationV2Members, type ArrayFieldCtor, type ArrayFieldInstance, type ArrayFieldOptions, BaseActorSheet, BaseApplication, type BaseApplicationMembers, BaseDocumentSheet, type BaseDocumentSheetMembers, BaseItemSheet, BaseTypeDataModel, type BooleanFieldCtor, type BooleanFieldInstance, type BooleanFieldOptions, type ColorFieldCtor, type ColorFieldInstance, type ColorFieldOptions, type CombatConfig, type DataFieldOptions, type DataModelClass, type DocumentClass, type DocumentSheetKind, type DocumentSheetV2Members, type DragDropConfig, ERROR_MANIFEST_VERSION, type EmbeddedDataFieldCtor, type EmbeddedDataFieldInstance, type EmbeddedDataFieldOptions, type EmbeddedDocumentFieldCtor, type EmbeddedDocumentFieldInstance, type EmbeddedDocumentFieldOptions, type EnricherRegistration, 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 SheetBaseMembers, type SheetBaseStatics, type SheetDocumentKind, type SheetRegistration, 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, type VttforgeClass, createMigrationRunner, docsUrlFor, fields, getErrorEntry, getErrorManifest, listErrorEntries, moduleSubType, registerEnrichers, registerModule, registerSheets, registerSystem };
+export { type ActiveEffectConfig, type ActorConfig, type ApplicationV2Members, type ArrayFieldCtor, type ArrayFieldInstance, type ArrayFieldOptions, BaseActorSheet, BaseApplication, type BaseApplicationMembers, BaseDocumentSheet, type BaseDocumentSheetMembers, BaseItemSheet, BaseTypeDataModel, type BooleanFieldCtor, type BooleanFieldInstance, type BooleanFieldOptions, type ColorFieldCtor, type ColorFieldInstance, type ColorFieldOptions, type CombatConfig, type ConfigCollection, type DataFieldOptions, type DataModelClass, type DocumentClass, type DocumentSheetKind, type DocumentSheetV2Members, type DragDropConfig, ERROR_MANIFEST_VERSION, type EmbeddedDataFieldCtor, type EmbeddedDataFieldInstance, type EmbeddedDataFieldOptions, type EmbeddedDocumentFieldCtor, type EmbeddedDocumentFieldInstance, type EmbeddedDocumentFieldOptions, type EnricherRegistration, 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 ItemConfig, 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 SheetBaseMembers, type SheetBaseStatics, type SheetDocumentKind, type SheetRegistration, 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, type VttforgeClass, createMigrationRunner, docsUrlFor, fields, getErrorEntry, getErrorManifest, listErrorEntries, moduleSubType, registerEnrichers, registerModule, registerSheets, registerSystem };
 //# sourceMappingURL=index.d.mts.map