@vttforge/core 0.0.0 → 0.7.0

package/dist/index.mjs

@@ -0,0 +1,911 @@
+//#region src/errors/registry.ts
+const DOCS_BASE_URL = "https://vttforge.dev/errors";
+const REGISTRY = Object.freeze({
+	"VTTF-0001": Object.freeze({
+		code: "VTTF-0001",
+		name: "SystemAlreadyRegistered",
+		summary: "registerSystem() was called more than once for the same system id. This is almost always a hot-reload artefact or a duplicate import."
+	}),
+	"VTTF-0002": Object.freeze({
+		code: "VTTF-0002",
+		name: "MissingFoundryGlobals",
+		summary: "VTTForge code ran in an environment without Foundry globals (game, Hooks, CONFIG). Initialise inside the Foundry runtime, not in a Node test without mocks."
+	}),
+	"VTTF-0003": Object.freeze({
+		code: "VTTF-0003",
+		name: "UnknownSetting",
+		summary: "SystemConfig.get() / set() was called with a key that was never passed to SystemConfig.register(). Register the setting in your init hook before reading it."
+	}),
+	"VTTF-0004": Object.freeze({
+		code: "VTTF-0004",
+		name: "MigrationFailed",
+		summary: "A migration function passed to createMigrationRunner() threw. The original error is available on .cause. The schemaVersion setting is not advanced past the failed migration so retrying on the next world load picks up where the failure left off."
+	}),
+	"VTTF-0005": Object.freeze({
+		code: "VTTF-0005",
+		name: "WorldTooOldForMigration",
+		summary: "createMigrationRunner() was called on a world whose stored schemaVersion is older than the configured compatibleVersion floor. Upgrade the world to a supported intermediate version before continuing — running migrations across the gap would corrupt data."
+	})
+});
+/**
+* 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.
+*/
+function getErrorEntry(code) {
+	const entry = REGISTRY[code];
+	if (entry === void 0) throw new Error(`Unknown VTTForge error code: ${code}. Add it to the registry.`);
+	return entry;
+}
+/**
+* Return every entry currently in the registry. Used by codegen to emit the
+* runtime constants and the JSON manifest that powers the docs pages.
+*/
+function listErrorEntries() {
+	return Object.values(REGISTRY);
+}
+function docsUrlFor(code) {
+	return `${DOCS_BASE_URL}/${code}`;
+}
+/**
+* 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.
+*/
+var VttfError = class extends Error {
+	code;
+	docsUrl;
+	constructor(code, message, options) {
+		const entry = getErrorEntry(code);
+		const finalMessage = `[${code}] ${message ?? entry.summary}`;
+		super(finalMessage, options);
+		this.code = code;
+		this.name = entry.name;
+		this.docsUrl = docsUrlFor(code);
+	}
+};
+//#endregion
+//#region src/base-actor-sheet.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).
+*/
+function resolveBases$1() {
+	const foundry = globalThis.foundry;
+	const Base = foundry?.applications?.sheets?.ActorSheetV2;
+	const mixin = foundry?.applications?.api?.HandlebarsApplicationMixin;
+	if (typeof Base !== "function" || typeof mixin !== "function") throw new VttfError("VTTF-0002", "foundry.applications.sheets.ActorSheetV2 and/or foundry.applications.api.HandlebarsApplicationMixin are not available. Define your BaseActorSheet subclasses inside the Foundry runtime (or stub the global in tests).");
+	return {
+		Base,
+		mixin
+	};
+}
+function resolveDragDrop$1() {
+	const ctor = globalThis.foundry?.applications?.ux?.DragDrop;
+	return typeof ctor === "function" ? ctor : void 0;
+}
+async function resolveFromUuid(uuid) {
+	const fn = globalThis.fromUuid;
+	if (typeof fn !== "function") return null;
+	return fn(uuid);
+}
+/**
+* Marker class that consumer CSS uses for scoping. Always present on every
+* VTTForge-derived sheet so rules like `.vttforge .actor-sheet { ... }` work.
+*/
+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.
+*   }
+* }
+* ```
+*/
+function BaseActorSheet() {
+	const { Base, mixin } = resolveBases$1();
+	const Mixed = mixin(Base);
+	class VttforgeBaseActorSheet extends Mixed {
+		static DEFAULT_OPTIONS = {
+			classes: [VTTFORGE_SHEET_CLASS],
+			window: { resizable: true },
+			position: {
+				width: 600,
+				height: 700
+			},
+			tag: "form",
+			form: {
+				submitOnChange: true,
+				closeOnSubmit: false
+			},
+			actions: { vttforgeTab: VttforgeBaseActorSheet._onTab }
+		};
+		/**
+		* Declarative DragDrop entries. Each becomes a
+		* `foundry.applications.ux.DragDrop` instance bound in `_onRender`.
+		* Subclasses override by re-declaring `static DRAG_DROP = [...]`.
+		*/
+		static DRAG_DROP = [];
+		/**
+		* Augment ApplicationV2's context with `tabs[group]` for sheets that
+		* declare **multiple** `static TABS` groups. ApplicationV2 already
+		* auto-populates `context.tabs` (keyed by tab id) for single-group
+		* sheets — overriding that flat shape would force every consumer to
+		* either unwrap or write `context.tabs.<group>.<tabId>` in templates.
+		* Multi-group sheets get nested `context.tabs.<group>.<tabId>` because
+		* ApplicationV2 returns `{}` for them by default.
+		*/
+		async _prepareContext(options) {
+			const superPrepare = Mixed.prototype._prepareContext;
+			const context = typeof superPrepare === "function" ? await superPrepare.call(this, options) : {};
+			const tabsConfig = this.constructor.TABS;
+			if (tabsConfig && typeof tabsConfig === "object") {
+				const groups = Object.keys(tabsConfig);
+				if (groups.length > 1) {
+					const prepareTabs = this._prepareTabs;
+					const tabs = {};
+					for (const group of groups) tabs[group] = typeof prepareTabs === "function" ? prepareTabs.call(this, group) : {};
+					context.tabs = tabs;
+				}
+			}
+			return context;
+		}
+		/**
+		* Default `tab` action handler. ApplicationV2 doesn't ship one, so every
+		* sheet that uses `<button data-action="tab" data-tab=… data-group=…>`
+		* has to wire its own. We toggle the `.active` class on the matching
+		* nav element (`[data-action="tab"][data-tab=…][data-group=…]`) and
+		* on `section.tab[data-tab=…][data-group=…]`, then update
+		* `sheet.tabGroups[group]` so subsequent re-renders pick the right
+		* initial tab.
+		*
+		* ApplicationV2's action dispatcher binds `this` to the sheet instance
+		* at call time even though the handler is declared `static`.
+		*/
+		static _onTab(_event, target) {
+			const sheet = this;
+			const group = target.dataset?.group;
+			const tab = target.dataset?.tab;
+			if (!group || !tab) return;
+			sheet.tabGroups[group] = tab;
+			const root = sheet.element;
+			if (!root) return;
+			for (const link of root.querySelectorAll(`[data-action="vttforgeTab"][data-group="${group}"]`)) link.classList.toggle("active", link.dataset.tab === tab);
+			for (const section of root.querySelectorAll(`section.tab[data-group="${group}"]`)) section.classList.toggle("active", section.dataset.tab === tab);
+		}
+		/**
+		* Wire each `static DRAG_DROP` entry into a real `DragDrop` instance.
+		* Permissions default to `this.isEditable`; callbacks default to
+		* `_onDragStart` / `_onDrop`. Subclasses extending `_onRender` MUST call
+		* `super._onRender(context, options)` to keep DragDrop wired.
+		*/
+		_onRender(context, options) {
+			const superRender = Mixed.prototype._onRender;
+			if (typeof superRender === "function") superRender.call(this, context, options);
+			const configs = this.constructor.DRAG_DROP;
+			if (!configs?.length) return;
+			const DragDrop = resolveDragDrop$1();
+			if (!DragDrop) return;
+			const element = this.element;
+			if (!element) return;
+			const onDragStart = this._onDragStart;
+			const onDrop = this._onDrop;
+			for (const cfg of configs) new DragDrop({
+				dragSelector: cfg.dragSelector,
+				dropSelector: cfg.dropSelector,
+				permissions: {
+					dragstart: cfg.permissions?.dragstart ?? (() => this.#isEditable()),
+					drop: cfg.permissions?.drop ?? (() => this.#isEditable())
+				},
+				callbacks: {
+					...typeof onDragStart === "function" ? { dragstart: onDragStart.bind(this) } : {},
+					...typeof onDrop === "function" ? { drop: onDrop.bind(this) } : {},
+					...cfg.callbacks ?? {}
+				}
+			}).bind(element);
+		}
+		/**
+		* Default drag handler — serialises the item identified by
+		* `data-item-id` on the drag source element. Override for richer payloads
+		* (Actor drags, custom UUIDs).
+		*/
+		_onDragStart(event) {
+			const itemId = event.currentTarget?.dataset?.itemId;
+			if (!itemId || !event.dataTransfer) return;
+			const item = (this.document?.items)?.get(itemId);
+			if (!item) return;
+			event.dataTransfer.setData("application/json", JSON.stringify({
+				type: "Item",
+				uuid: item.uuid
+			}));
+		}
+		/**
+		* Typed drop sugar. Subclasses override this instead of `_onDropItem`
+		* to skip the `fromUuid()` ceremony. Return `undefined` to fall through
+		* to Foundry's default `_onDropItem`; return anything else to take
+		* ownership of the drop.
+		*/
+		async onDropItem(_item, _event) {}
+		async onDropActor(_actor, _event) {}
+		async onDropFolder(_folder, _event) {}
+		async onDropActiveEffect(_effect, _event) {}
+		async _onDropItem(event, data) {
+			return this.#dispatchDrop("_onDropItem", "onDropItem", event, data);
+		}
+		async _onDropActor(event, data) {
+			return this.#dispatchDrop("_onDropActor", "onDropActor", event, data);
+		}
+		async _onDropFolder(event, data) {
+			return this.#dispatchDrop("_onDropFolder", "onDropFolder", event, data);
+		}
+		async _onDropActiveEffect(event, data) {
+			return this.#dispatchDrop("_onDropActiveEffect", "onDropActiveEffect", event, data);
+		}
+		async #dispatchDrop(superKey, sugarKey, event, data) {
+			const uuid = data?.uuid;
+			if (uuid) {
+				const doc = await resolveFromUuid(uuid);
+				if (doc) {
+					const result = await this[sugarKey](doc, event);
+					if (result !== void 0) return result;
+				}
+			}
+			const superFn = Mixed.prototype[superKey];
+			if (typeof superFn === "function") return superFn.call(this, event, data);
+		}
+		#isEditable() {
+			return Boolean(this.isEditable);
+		}
+	}
+	return VttforgeBaseActorSheet;
+}
+//#endregion
+//#region src/base-item-sheet.ts
+function resolveBases() {
+	const foundry = globalThis.foundry;
+	const Base = foundry?.applications?.sheets?.ItemSheetV2;
+	const mixin = foundry?.applications?.api?.HandlebarsApplicationMixin;
+	if (typeof Base !== "function" || typeof mixin !== "function") throw new VttfError("VTTF-0002", "foundry.applications.sheets.ItemSheetV2 and/or foundry.applications.api.HandlebarsApplicationMixin are not available. Define your BaseItemSheet subclasses inside the Foundry runtime (or stub the global in tests).");
+	return {
+		Base,
+		mixin
+	};
+}
+function resolveDragDrop() {
+	const ctor = globalThis.foundry?.applications?.ux?.DragDrop;
+	return typeof ctor === "function" ? ctor : void 0;
+}
+/**
+* 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',
+*     },
+*   };
+* }
+* ```
+*/
+function BaseItemSheet() {
+	const { Base, mixin } = resolveBases();
+	const Mixed = mixin(Base);
+	class VttforgeBaseItemSheet extends Mixed {
+		static DEFAULT_OPTIONS = {
+			classes: [VTTFORGE_SHEET_CLASS],
+			window: { resizable: true },
+			position: {
+				width: 520,
+				height: 480
+			},
+			tag: "form",
+			form: {
+				submitOnChange: true,
+				closeOnSubmit: false
+			},
+			actions: { vttforgeTab: VttforgeBaseItemSheet._onTab }
+		};
+		static DRAG_DROP = [];
+		/**
+		* Multi-group sheets get nested `context.tabs.<group>.<tabId>` because
+		* ApplicationV2 returns `{}` for them by default; single-group sheets
+		* use ApplicationV2's flat `context.tabs.<tabId>` shape untouched. See
+		* BaseActorSheet for the long version.
+		*/
+		async _prepareContext(options) {
+			const superPrepare = Mixed.prototype._prepareContext;
+			const context = typeof superPrepare === "function" ? await superPrepare.call(this, options) : {};
+			const tabsConfig = this.constructor.TABS;
+			if (tabsConfig && typeof tabsConfig === "object") {
+				const groups = Object.keys(tabsConfig);
+				if (groups.length > 1) {
+					const prepareTabs = this._prepareTabs;
+					const tabs = {};
+					for (const group of groups) tabs[group] = typeof prepareTabs === "function" ? prepareTabs.call(this, group) : {};
+					context.tabs = tabs;
+				}
+			}
+			return context;
+		}
+		static _onTab(_event, target) {
+			const sheet = this;
+			const group = target.dataset?.group;
+			const tab = target.dataset?.tab;
+			if (!group || !tab) return;
+			sheet.tabGroups[group] = tab;
+			const root = sheet.element;
+			if (!root) return;
+			for (const link of root.querySelectorAll(`[data-action="vttforgeTab"][data-group="${group}"]`)) link.classList.toggle("active", link.dataset.tab === tab);
+			for (const section of root.querySelectorAll(`section.tab[data-group="${group}"]`)) section.classList.toggle("active", section.dataset.tab === tab);
+		}
+		_onRender(context, options) {
+			const superRender = Mixed.prototype._onRender;
+			if (typeof superRender === "function") superRender.call(this, context, options);
+			const configs = this.constructor.DRAG_DROP;
+			if (!configs?.length) return;
+			const DragDrop = resolveDragDrop();
+			if (!DragDrop) return;
+			const element = this.element;
+			if (!element) return;
+			const onDragStart = this._onDragStart;
+			const onDrop = this._onDrop;
+			for (const cfg of configs) new DragDrop({
+				dragSelector: cfg.dragSelector,
+				dropSelector: cfg.dropSelector,
+				permissions: {
+					dragstart: cfg.permissions?.dragstart ?? (() => this.#isEditable()),
+					drop: cfg.permissions?.drop ?? (() => this.#isEditable())
+				},
+				callbacks: {
+					...typeof onDragStart === "function" ? { dragstart: onDragStart.bind(this) } : {},
+					...typeof onDrop === "function" ? { drop: onDrop.bind(this) } : {},
+					...cfg.callbacks ?? {}
+				}
+			}).bind(element);
+		}
+		#isEditable() {
+			return Boolean(this.isEditable);
+		}
+	}
+	return VttforgeBaseItemSheet;
+}
+//#endregion
+//#region src/base-type-data-model.ts
+function resolveTypeDataModelClass() {
+	const cls = globalThis.foundry?.abstract?.TypeDataModel;
+	if (typeof cls !== "function") throw new VttfError("VTTF-0002", "foundry.abstract.TypeDataModel is not available. Define your BaseTypeDataModel subclasses inside the Foundry runtime (or stub the global in tests).");
+	return cls;
+}
+function BaseTypeDataModel(defineSchema) {
+	const Base = resolveTypeDataModelClass();
+	class VttforgeBaseTypeDataModel extends Base {
+		/**
+		* Default no-op so subclasses can omit it when they have no value-level
+		* migrations. Always end with `super.migrateData(data)` if you override.
+		*/
+		static migrateData(data) {
+			const superMigrateData = Base.migrateData;
+			if (typeof superMigrateData === "function") return superMigrateData.call(VttforgeBaseTypeDataModel, data);
+			return data;
+		}
+		/**
+		* No-op stub. Override per type to initialize fields whose values Active
+		* Effects need to consume — base max HP, base AC, etc. Foundry calls this
+		* BEFORE applying Active Effects, so anything you set here is the input
+		* that AE changes (`ADD`, `MULTIPLY`, `OVERRIDE`, …) operate on.
+		*
+		* Use `prepareDerivedData()` instead for values that depend on the
+		* AE-mutated state (modifiers, percentages, totals).
+		*
+		* Never write to the database here — purely in-memory.
+		*/
+		prepareBaseData() {}
+		/**
+		* No-op stub. Override per type to compute derived values from the
+		* AE-mutated state (modifiers, percentages, totals). Runs AFTER Active
+		* Effects apply; use `prepareBaseData()` for values that AEs need to read.
+		*
+		* Never write to the database here — purely in-memory.
+		*/
+		prepareDerivedData() {}
+	}
+	if (defineSchema !== void 0) Object.defineProperty(VttforgeBaseTypeDataModel, "defineSchema", {
+		value: defineSchema,
+		writable: true,
+		configurable: true
+	});
+	return VttforgeBaseTypeDataModel;
+}
+//#endregion
+//#region src/data/fields.ts
+/**
+* `fields()` — typed bag of Foundry v13 data-field constructors.
+*
+* Foundry idiom inside `defineSchema()` is `const f = foundry.data.fields`. We
+* mirror that, but routed through a factory so the import succeeds in Node
+* (tests, IDE typecheck) where the global is absent. The factory resolves
+* `globalThis.foundry.data.fields` lazily — same pattern as
+* `BaseTypeDataModel()` (see `base-type-data-model.ts:25`) and
+* `BaseActorSheet()` (see `base-actor-sheet.ts:40`).
+*
+* v0.1 covers eight fields (PRD §7): NumberField, StringField, BooleanField,
+* HTMLField, ArrayField, SchemaField, ColorField, FilePathField. The instance
+* interfaces carry a phantom `[BRAND]` tag and an `options` capture so the
+* conditional types in `./infer-schema.ts` can extract the runtime semantics
+* (e.g. `nullable: true`).
+*
+* `EmbeddedDataField`, `EmbeddedDocumentField`, `TypedSchemaField`, and the
+* full required×initial nullability matrix ship with `@vttforge/types` v1.0.
+*/
+/**
+* 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.
+*/
+function fields() {
+	const f = globalThis.foundry?.data?.fields;
+	if (f === void 0 || f === null) throw new VttfError("VTTF-0002", "foundry.data.fields is not available. Call fields() inside the Foundry runtime (or stub the global in tests).");
+	return f;
+}
+//#endregion
+//#region src/errors/manifest.ts
+/**
+* Typed runtime view over the VTTF-NNNN registry.
+*
+* Same data as `listErrorEntries()` — the manifest wraps it in a versioned
+* envelope so external tooling (the v0.3 docs site, IDE extensions, lint
+* rules) has a stable shape to consume. The matching JSON projection is
+* emitted to `dist/errors-manifest.json` at build time by
+* `packages/core/scripts/codegen-errors.mjs`.
+*/
+const ERROR_MANIFEST_VERSION = 1;
+/**
+* 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`.
+*/
+function getErrorManifest() {
+	return {
+		version: 1,
+		package: "@vttforge/core",
+		entries: listErrorEntries()
+	};
+}
+//#endregion
+//#region src/migrations/runner.ts
+/**
+* `createMigrationRunner` — declarative schema migrations for Foundry systems.
+*
+* Replaces the copy-pasted "schemaVersion setting + Hooks.once('ready') +
+* isNewerVersion compare + sequential await" pattern that every system
+* eventually grows on its own. The runner owns no hooks — call
+* `register()` from your `init` hook and `run()` from your `ready` hook
+* (gated by `game.user.isGM`).
+*
+* Versions are semver strings, compared with `foundry.utils.isNewerVersion`.
+* The data lives in a per-system world setting and lines up cleanly with
+* `system.json`'s `flags.<systemId>.needsMigrationVersion` /
+* `compatibleMigrationVersion`.
+*
+* Failures advance `schemaVersion` only past migrations that *completed* — a
+* mid-sequence throw leaves the world at the last successful version so the
+* retry on the next world load picks up exactly where it failed.
+*/
+const DEFAULT_SETTING_KEY = "schemaVersion";
+const INITIAL_VERSION = "0.0.0";
+function resolveIsNewerVersion() {
+	const fn = globalThis.foundry?.utils?.isNewerVersion;
+	if (typeof fn === "function") return fn;
+	return naiveIsNewerVersion;
+}
+function naiveIsNewerVersion(next, current) {
+	const parse = (v) => v.split(".").map((part) => {
+		const n = Number.parseInt(part, 10);
+		return Number.isNaN(n) ? 0 : n;
+	});
+	const a = parse(next);
+	const b = parse(current);
+	const len = Math.max(a.length, b.length);
+	for (let i = 0; i < len; i++) {
+		const ai = a[i] ?? 0;
+		const bi = b[i] ?? 0;
+		if (ai > bi) return true;
+		if (ai < bi) return false;
+	}
+	return false;
+}
+function resolveSettings() {
+	const settings = globalThis.game?.settings;
+	if (settings === void 0 || typeof settings.register !== "function" || typeof settings.get !== "function" || typeof settings.set !== "function") throw new VttfError("VTTF-0002", "globalThis.game.settings is not available — call createMigrationRunner().register() inside the Foundry runtime (or pass an explicit settings adapter in MigrationRunnerOptions).");
+	return settings;
+}
+function resolveLogger() {
+	const notifications = globalThis.ui?.notifications;
+	return {
+		info(message) {
+			console.info(message);
+			notifications?.info?.(message);
+		},
+		warn(message) {
+			console.warn(message);
+			notifications?.warn?.(message);
+		},
+		error(message) {
+			console.error(message);
+			notifications?.error?.(message);
+		}
+	};
+}
+function lastVersion(migrations) {
+	return migrations.at(-1)?.version ?? INITIAL_VERSION;
+}
+function assertAscending(migrations, isNewer) {
+	for (let i = 1; i < migrations.length; i++) {
+		const prevMig = migrations[i - 1];
+		const nextMig = migrations[i];
+		if (prevMig === void 0 || nextMig === void 0) continue;
+		if (!isNewer(nextMig.version, prevMig.version)) throw new VttfError("VTTF-0004", `Migration list out of order: ${nextMig.version} must be newer than ${prevMig.version}.`);
+	}
+}
+/**
+* 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();
+*   },
+* });
+* ```
+*/
+function createMigrationRunner(options) {
+	const settingKey = options.settingKey ?? DEFAULT_SETTING_KEY;
+	const target = lastVersion(options.migrations);
+	const settingsOverride = options.settings;
+	const loggerOverride = options.logger;
+	const isNewerOverride = options.isNewerVersion;
+	return {
+		targetVersion: target,
+		register() {
+			(settingsOverride ?? resolveSettings()).register(options.systemId, settingKey, {
+				name: "Schema Version",
+				hint: "Internal schema version for VTTForge data migration tracking. Do not edit by hand.",
+				scope: "world",
+				config: false,
+				type: String,
+				default: INITIAL_VERSION
+			});
+		},
+		async run() {
+			if (options.migrations.length === 0) return [];
+			const settings = settingsOverride ?? resolveSettings();
+			const logger = loggerOverride ?? resolveLogger();
+			const isNewer = isNewerOverride ?? resolveIsNewerVersion();
+			assertAscending(options.migrations, isNewer);
+			const current = settings.get(options.systemId, settingKey) ?? INITIAL_VERSION;
+			if (options.compatibleVersion !== void 0) {
+				if (isNewer(options.compatibleVersion, current)) throw new VttfError("VTTF-0005", `World schemaVersion ${current} is older than ${options.systemId}'s compatibleVersion ${options.compatibleVersion}. Upgrade through an intermediate release first.`);
+			}
+			const pending = options.migrations.filter((m) => isNewer(m.version, current));
+			if (pending.length === 0) return [];
+			const ran = [];
+			let lastApplied = current;
+			logger.warn(`${options.systemId} | Running ${pending.length} pending migration(s) from ${current} to ${target}.`);
+			for (const migration of pending) {
+				const label = migration.description ? `${migration.version} — ${migration.description}` : migration.version;
+				logger.info(`${options.systemId} | Migrating to ${label}`);
+				try {
+					await migration.fn();
+				} catch (cause) {
+					if (isNewer(lastApplied, current)) await settings.set(options.systemId, settingKey, lastApplied);
+					throw new VttfError("VTTF-0004", `Migration to ${label} failed for system "${options.systemId}". schemaVersion left at ${lastApplied}.`, { cause });
+				}
+				await settings.set(options.systemId, settingKey, migration.version);
+				lastApplied = migration.version;
+				ran.push(migration.version);
+			}
+			logger.info(`${options.systemId} | Migration complete. schemaVersion = ${target}.`);
+			return ran;
+		}
+	};
+}
+//#endregion
+//#region src/register-module.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.
+*/
+const registered$1 = /* @__PURE__ */ new Set();
+/**
+* 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'
+* ```
+*/
+function moduleSubType(moduleId, type) {
+	return `${moduleId}.${type}`;
+}
+function vttfError$1(code, message) {
+	return new VttfError(code, message);
+}
+function readHooks$1() {
+	const hooks = globalThis.Hooks;
+	if (hooks === void 0 || typeof hooks.once !== "function") throw vttfError$1("VTTF-0002", "globalThis.Hooks is not available — call registerModule() inside a Foundry runtime or stub Hooks in tests");
+	return hooks;
+}
+function readConfig$1() {
+	const config = globalThis.CONFIG;
+	if (config === void 0) throw vttfError$1("VTTF-0002", "globalThis.CONFIG is not available — call registerModule() inside a Foundry runtime or stub CONFIG in tests");
+	return config;
+}
+function assignSubTypes(target, moduleId, models) {
+	for (const [type, model] of Object.entries(models)) target[moduleSubType(moduleId, type)] = model;
+}
+/**
+* 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.
+*/
+function registerModule(config) {
+	if (registered$1.has(config.id)) throw vttfError$1("VTTF-0001", `Module "${config.id}" was already registered`);
+	registered$1.add(config.id);
+	const hooks = readHooks$1();
+	hooks.once("init", () => {
+		applyInit$1(config);
+	});
+	if (config.onReady !== void 0) hooks.once("ready", () => {
+		config.onReady?.();
+	});
+	return config;
+}
+function applyInit$1(config) {
+	config.onBeforeInit?.();
+	const CONFIG = readConfig$1();
+	if (config.actorDataModels !== void 0) assignSubTypes(CONFIG.Actor.dataModels, config.id, config.actorDataModels);
+	if (config.itemDataModels !== void 0) assignSubTypes(CONFIG.Item.dataModels, config.id, config.itemDataModels);
+	if (config.statusEffects !== void 0 && config.statusEffects.length > 0) {
+		CONFIG.statusEffects ??= [];
+		CONFIG.statusEffects.push(...config.statusEffects);
+	}
+	config.onAfterInit?.();
+}
+//#endregion
+//#region src/register-system.ts
+/**
+* registerSystem — one call that replaces the boilerplate `Hooks.once("init", ...)`
+* block in every Foundry system.
+*
+* Conforms to the canonical Foundry init lifecycle:
+*
+*   init       → CONFIG mutations (dataModels, documentClass, statusEffects)
+*   i18nInit   → translate CONFIG labels
+*   setup      → enrichers, packs
+*   ready      → migrations (GM-only — consumer guards inside onReady)
+*
+* v0.1 scope: `init` + `ready`. `setup` / `i18nInit` callbacks remain v0.1.1.
+*
+* Per PRD §11 open question #1, we wrap the hook ourselves ("explicit hook for
+* now"); callers don't need to write `Hooks.once("init", ...)` themselves.
+*/
+const registered = /* @__PURE__ */ new Set();
+function readHooks() {
+	const hooks = globalThis.Hooks;
+	if (hooks === void 0 || typeof hooks.once !== "function") throw vttfError("VTTF-0002", "globalThis.Hooks is not available — call registerSystem() inside a Foundry runtime or stub Hooks in tests");
+	return hooks;
+}
+function readConfig() {
+	const config = globalThis.CONFIG;
+	if (config === void 0) throw vttfError("VTTF-0002", "globalThis.CONFIG is not available — call registerSystem() inside a Foundry runtime or stub CONFIG in tests");
+	return config;
+}
+function vttfError(code, message) {
+	return new VttfError(code, message);
+}
+/**
+* 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.
+*/
+function registerSystem(config) {
+	if (registered.has(config.id)) throw vttfError("VTTF-0001", `System "${config.id}" was already registered`);
+	registered.add(config.id);
+	const hooks = readHooks();
+	hooks.once("init", () => {
+		applyInit(config);
+	});
+	if (config.onReady !== void 0) hooks.once("ready", () => {
+		config.onReady?.();
+	});
+	return config;
+}
+function applyInit(config) {
+	config.onBeforeInit?.();
+	const CONFIG = readConfig();
+	if (config.actorDataModels !== void 0) Object.assign(CONFIG.Actor.dataModels, config.actorDataModels);
+	if (config.itemDataModels !== void 0) Object.assign(CONFIG.Item.dataModels, config.itemDataModels);
+	if (config.actorDocumentClass !== void 0) CONFIG.Actor.documentClass = config.actorDocumentClass;
+	if (config.itemDocumentClass !== void 0) CONFIG.Item.documentClass = config.itemDocumentClass;
+	if (config.combat?.initiative !== void 0) CONFIG.Combat.initiative = config.combat.initiative;
+	const legacyTransferral = config.activeEffect?.legacyTransferral ?? false;
+	CONFIG.ActiveEffect.legacyTransferral = legacyTransferral;
+	if (config.statusEffects !== void 0) CONFIG.statusEffects = [...config.statusEffects];
+	config.onAfterInit?.();
+}
+//#endregion
+//#region src/system-config.ts
+/**
+* SystemConfig — typed wrapper around `game.settings.register/get/set`.
+*
+* Eliminates the boilerplate of repeating the system id in every call:
+*
+*   // before
+*   game.settings.register("ordemparanormal", "homebrewRules", { ... });
+*   game.settings.get("ordemparanormal", "homebrewRules");
+*
+*   // after
+*   const cfg = new SystemConfig("ordemparanormal");
+*   cfg.register("homebrewRules", { ... });
+*   cfg.get<boolean>("homebrewRules");
+*
+* Also keeps a local manifest of registered keys so attempts to read an
+* unregistered key fail with VTTF-0003 instead of returning undefined.
+*
+* Registration must happen during the `init` hook; reads can happen any
+* time after.
+*/
+function readGame() {
+	const candidate = globalThis.game;
+	if (candidate === void 0 || candidate.settings === void 0) throw new VttfError("VTTF-0002", "game.settings is not available — call SystemConfig methods inside or after the Foundry \"init\" hook");
+	return candidate;
+}
+var SystemConfig = class {
+	systemId;
+	#registered = /* @__PURE__ */ new Set();
+	constructor(systemId) {
+		this.systemId = systemId;
+	}
+	register(key, config) {
+		readGame().settings.register(this.systemId, key, config);
+		this.#registered.add(key);
+	}
+	get(key) {
+		if (!this.#registered.has(key)) throw new VttfError("VTTF-0003", `SystemConfig.get("${key}") was called before register("${key}")`);
+		return readGame().settings.get(this.systemId, key);
+	}
+	async set(key, value) {
+		if (!this.#registered.has(key)) throw new VttfError("VTTF-0003", `SystemConfig.set("${key}") was called before register("${key}")`);
+		return readGame().settings.set(this.systemId, key, value);
+	}
+	isRegistered(key) {
+		return this.#registered.has(key);
+	}
+};
+//#endregion
+//#region src/index.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.
+*/
+const VTTFORGE_CORE_VERSION = "0.2.0";
+//#endregion
+export { BaseActorSheet, BaseItemSheet, BaseTypeDataModel, ERROR_MANIFEST_VERSION, SystemConfig, VTTFORGE_CORE_VERSION, VTTFORGE_SHEET_CLASS, VttfError, createMigrationRunner, docsUrlFor, fields, getErrorEntry, getErrorManifest, listErrorEntries, moduleSubType, registerModule, registerSystem };
+
+//# sourceMappingURL=index.mjs.map