@fate-app/mod-types 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Stanislav Sonder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @fate-app/mod-types
+
+Shared TypeScript types and runtime helpers for [Assistant for Fate](https://github.com/Stanislavsonder/fate)
+mods — the single source of truth for the mod manifest/bundle shape, consumed
+by both the app and community mod authors.
+
+Exports `defineFateMod`, `getModData`/`setModData`, `validateBundleShape`, and
+the vendored `registry.schema.json` used to validate a mod's `manifest.json`.
+
+Full author-facing documentation lives in the app repo's
+[`docs/MOD_API.md`](https://github.com/Stanislavsonder/fate/blob/main/docs/MOD_API.md).
+Submitting a mod to the public registry: see
+[`fate-core-mods`](https://github.com/Stanislavsonder/fate-core-mods)'s
+`SUBMITTING.md`.
+
+## Version discipline
+
+This package's version tracks `SDK_VERSION` (the `FateSDK` ABI, defined in
+the app's `src/mods/sdk.ts`) — same major.minor, patch is free. A mod's
+`manifest.json` `sdk` field is a semver range checked against the app's
+`SDK_VERSION` at load time; this package (and `@fate-app/mod-build`) is how
+you compile against a given ABI version. Don't pin a version here that
+doesn't correspond to a real `SDK_VERSION` the app has shipped.

package/dist/bundle.d.ts

@@ -0,0 +1,30 @@
+import type { Character, FatePatch } from './character';
+import type { FateContext, FateConstants, FateTemplates } from './context';
+import type { FateModuleComponent } from './manifest';
+import type { DiceConstructor, DiceMaterial } from './dice';
+/** The executable half of a mod — the default export of bundle.mjs */
+export interface FateModBundle {
+    components?: FateModuleComponent[];
+    constants?: Partial<FateConstants>;
+    templates?: Partial<FateTemplates>;
+    shared?: Record<string, unknown>;
+    onInstall?(context: FateContext, character: Character): Promise<void> | void;
+    onUninstall?(context: FateContext, character: Character): Promise<void> | void;
+    onReconfigure?(context: FateContext, character: Character): Promise<void> | void;
+    patches?: FatePatch[];
+    /** Capability sections. */
+    dice?: FateModDice;
+    theme?: FateModTheme;
+}
+export interface FateModDice {
+    shapes?: DiceConstructor[];
+    materials?: DiceMaterial[];
+}
+export interface FateModTheme {
+    css: string;
+}
+export type FateModCapability = 'sheetComponents' | 'dice' | 'theme' | 'translations';
+/** Identity helper that gives mod authors typing + future validation hook */
+export declare function defineFateMod<_TData = unknown>(bundle: FateModBundle): FateModBundle;
+export declare function getModData<T>(character: Character, key: string): T | undefined;
+export declare function setModData<T>(character: Character, key: string, value: T): void;

package/dist/bundle.js

@@ -0,0 +1,11 @@
+/** Identity helper that gives mod authors typing + future validation hook */
+export function defineFateMod(bundle) {
+    return bundle;
+}
+export function getModData(character, key) {
+    return character[key];
+}
+export function setModData(character, key, value) {
+    ;
+    character[key] = value;
+}

package/dist/character.d.ts

@@ -0,0 +1,35 @@
+import type { FateContext } from './context';
+export type CharacterModule = {
+    version: string;
+    config?: Record<string, unknown>;
+};
+export type CharacterModules = {
+    [id: string]: CharacterModule;
+};
+export interface Character {
+    _modules: CharacterModules;
+    _version?: string;
+    id: number;
+    name: string;
+    /**
+     * Core field, not owned by any module — a character always has one
+     * (defaults to `''`, rendered as a placeholder image) so the character
+     * list card never depends on whether sonder@core-identity is installed.
+     * Existing characters are backfilled by src/patches/v2.0.0.ts.
+     */
+    avatar: string;
+    /**
+     * Mod-owned data. Built-ins currently attach typed fields here via
+     * `declare module '@fate-app/mod-types'` augmentation (see each module's
+     * src/types.ts); external mods (Phase 2+), which compile separately and
+     * cannot augment this package, read/write their slice through
+     * getModData/setModData instead.
+     */
+    [modKey: string]: unknown;
+}
+export interface FatePatch {
+    version: string;
+    note?: string;
+    incompatible?: boolean;
+    action: (context: FateContext, character: Character) => Promise<void>;
+}

package/dist/character.js

@@ -0,0 +1 @@
+export {};

package/dist/context.d.ts

@@ -0,0 +1,19 @@
+import type { Character } from './character';
+import type { FateModuleComponent, FateModuleManifest } from './manifest';
+export interface FateTemplates {
+    character: Character;
+    [modKey: string]: unknown;
+}
+export interface FateConstants {
+    [modKey: string]: unknown;
+}
+export interface FateShared {
+    [modKey: string]: unknown;
+}
+export interface FateContext {
+    modules: Record<string, FateModuleManifest>;
+    constants: FateConstants;
+    components: FateModuleComponent[];
+    templates: FateTemplates;
+    shared: FateShared;
+}

package/dist/context.js

@@ -0,0 +1 @@
+export {};

package/dist/dice.d.ts

@@ -0,0 +1,64 @@
+import type * as CANNON from 'cannon-es';
+import type * as THREE from 'three';
+/**
+ * Structural mirror of the app's own dice-collision event shape. Deliberately
+ * not the legacy `cannon` package's `ICollisionEvent` (an app-local quirk
+ * predating this package, kept only where the app already used it) —
+ * cannon-es's own `Body` type is all a dice author actually needs.
+ */
+export interface DiceCollisionEvent {
+    type: string;
+    body: CANNON.Body;
+    target: CANNON.Body;
+    contact: CANNON.ContactEquation;
+}
+export type DiceResult = {
+    value: number;
+    values: number[];
+    text: string;
+    color: 'success' | 'danger' | 'medium';
+};
+/**
+ * A dice material — a real (tiny) runtime class, not just a type: it has no
+ * three/cannon-es logic of its own beyond holding references, so bundling it
+ * into every dice mod costs nothing. Only the heavy libraries (three,
+ * cannon-es themselves) go through FateSDK.dice — see docs/MOD_API.md.
+ */
+export declare class DiceMaterial {
+    readonly name: string;
+    readonly faceMaterial: THREE.MeshStandardMaterial;
+    readonly symbolMaterial: THREE.MeshStandardMaterial;
+    readonly previewColor: string;
+    constructor(name: string, faceMaterial: THREE.MeshStandardMaterial, symbolMaterial: THREE.MeshStandardMaterial, previewColor: string);
+}
+/**
+ * The abstract base class every custom dice shape extends. A real runtime
+ * export (not a type-only declaration) for the same reason as DiceMaterial —
+ * its own constructor logic never touches three/cannon-es directly (that's
+ * the subclass's job in createMesh/createBody), so it's safe and cheap to
+ * bundle per-mod rather than routing through FateSDK.
+ */
+export declare abstract class Dice {
+    material: DiceMaterial;
+    size: number;
+    quality: number;
+    mass: number;
+    world: CANNON.World;
+    onCollide: (event: DiceCollisionEvent) => void;
+    static name: string;
+    static icon: string;
+    mesh: THREE.Mesh | THREE.Group;
+    body: CANNON.Body;
+    protected constructor(material: DiceMaterial, size: number, quality: number, mass: number, world: CANNON.World, onCollide: (event: DiceCollisionEvent) => void);
+    abstract clone(): Dice;
+    abstract getResult(): number;
+    abstract formatResult(result: number | number[]): DiceResult;
+    abstract changeMaterial(material: DiceMaterial): void;
+    protected abstract createMesh(): THREE.Mesh | THREE.Group;
+    protected abstract createBody(world: CANNON.World, onCollide: (event: DiceCollisionEvent) => void): CANNON.Body;
+}
+export type DiceConstructor = {
+    new (material: DiceMaterial, size: number, quality: number, mass: number, world: CANNON.World, onCollide: (event: DiceCollisionEvent) => void): Dice;
+    icon: string;
+    name: string;
+};

package/dist/dice.js

@@ -0,0 +1,47 @@
+/**
+ * A dice material — a real (tiny) runtime class, not just a type: it has no
+ * three/cannon-es logic of its own beyond holding references, so bundling it
+ * into every dice mod costs nothing. Only the heavy libraries (three,
+ * cannon-es themselves) go through FateSDK.dice — see docs/MOD_API.md.
+ */
+export class DiceMaterial {
+    name;
+    faceMaterial;
+    symbolMaterial;
+    previewColor;
+    constructor(name, faceMaterial, symbolMaterial, previewColor) {
+        this.name = name;
+        this.faceMaterial = faceMaterial;
+        this.symbolMaterial = symbolMaterial;
+        this.previewColor = previewColor;
+    }
+}
+/**
+ * The abstract base class every custom dice shape extends. A real runtime
+ * export (not a type-only declaration) for the same reason as DiceMaterial —
+ * its own constructor logic never touches three/cannon-es directly (that's
+ * the subclass's job in createMesh/createBody), so it's safe and cheap to
+ * bundle per-mod rather than routing through FateSDK.
+ */
+export class Dice {
+    material;
+    size;
+    quality;
+    mass;
+    world;
+    onCollide;
+    static name;
+    static icon;
+    mesh;
+    body;
+    constructor(material, size, quality, mass, world, onCollide) {
+        this.material = material;
+        this.size = size;
+        this.quality = quality;
+        this.mass = mass;
+        this.world = world;
+        this.onCollide = onCollide;
+        this.mesh = this.createMesh();
+        this.body = this.createBody(this.world, this.onCollide);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './character.ts';
+export * from './context.ts';
+export * from './manifest.ts';
+export * from './bundle.ts';
+export * from './resolution.ts';
+export * from './validateBundleShape.ts';
+export * from './dice.ts';

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./character.js";
+export * from "./context.js";
+export * from "./manifest.js";
+export * from "./bundle.js";
+export * from "./resolution.js";
+export * from "./validateBundleShape.js";
+export * from "./dice.js";

package/dist/manifest.d.ts

@@ -0,0 +1,103 @@
+import type { Component } from 'vue';
+import type { Character, FatePatch } from './character';
+import type { FateConstants, FateContext, FateShared, FateTemplates } from './context';
+import type { FateModCapability, FateModDice, FateModTheme } from './bundle';
+export interface FateModuleComponent {
+    id: string;
+    component: Component;
+    order: number;
+}
+export interface FateModuleManifest {
+    id: string;
+    name: string;
+    version: string;
+    author: {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    description: {
+        short: string;
+        full?: string;
+    };
+    languages: string[];
+    tags: string[];
+    dependencies?: Record<string, string>;
+    incompatibleWith?: string[];
+    appVersion?: string;
+    loadPriority: number;
+    components?: FateModuleComponent[];
+    constants?: Partial<FateConstants>;
+    templates?: Partial<FateTemplates>;
+    shared?: Partial<FateShared>;
+    onInstall(context: FateContext, character: Character): Promise<void> | void;
+    onUninstall(context: FateContext, character: Character): Promise<void> | void;
+    onReconfigure(context: FateContext, character: Character): Promise<void> | void;
+    patches?: FatePatch[];
+    config?: FateModuleConfig;
+    /** Host mod-API (ABI) semver range this manifest was built against */
+    sdk?: string;
+    /** Entry file relative to the mod's published directory, e.g. "bundle.mjs" */
+    entry?: string;
+    capabilities?: FateModCapability[];
+    /** For 'translations'-capability mods: what the pack translates — "app" and/or other mod ids.
+     * Declarative only for now (schema stub); the runtime merge is not implemented yet. */
+    translationTargets?: string[];
+    /** Present when capabilities includes 'dice' — spread onto the manifest by assembleMod() from the bundle */
+    dice?: FateModDice;
+    /** Present when capabilities includes 'theme' — spread onto the manifest by assembleMod() from the bundle */
+    theme?: FateModTheme;
+    extra?: {
+        [key: string]: unknown;
+    };
+}
+export interface FateModuleConfig {
+    groups: FateModuleConfigGroup[];
+    options: FateModuleConfigOption[];
+}
+export type FateModuleConfigGroup = {
+    id: string;
+    name: string;
+    description: string;
+};
+export type FateModuleConfigField = {
+    id: string;
+    name: string;
+    tooltip?: string;
+    type: 'string' | 'number' | 'select' | 'custom-list' | 'boolean' | 'range';
+    multiple?: boolean;
+    default: unknown;
+    limits?: {
+        min?: number;
+        max?: number;
+        step?: number;
+    };
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    itemTemplate?: {
+        fields: FateModuleConfigField[];
+    };
+};
+export type FateModuleConfigOption = {
+    id: string;
+    groupId?: string;
+    name: string;
+    tooltip?: string;
+    type: 'number' | 'string' | 'boolean' | 'select' | 'range' | 'custom-list';
+    multiple?: boolean;
+    default: unknown;
+    limits?: {
+        min?: number;
+        max?: number;
+        step?: number;
+    };
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    itemTemplate?: {
+        fields: FateModuleConfigField[];
+    };
+};

package/dist/manifest.js

@@ -0,0 +1 @@
+export {};

package/dist/resolution.d.ts

@@ -0,0 +1,38 @@
+import type { CharacterModules } from './character';
+import type { FateModuleManifest } from './manifest';
+export type ModulesUpdateInstruction = {
+    install: CharacterModules;
+    reconfigure: CharacterModules;
+    uninstall: CharacterModules;
+};
+export type ModuleResolutionIssue = {
+    type: 'missing-dependency' | 'version-mismatch' | 'app-version-mismatch' | 'incompatible-modules' | 'dependency-cycle' | 'mod-not-installed';
+    moduleId: string;
+    moduleName: string;
+    details: {
+        dependencyId?: string;
+        requiredVersion?: string;
+        actualVersion?: string;
+        dependencyName?: string;
+        appVersion?: string;
+        requiredAppVersion?: string;
+        incompatibleWith?: Array<{
+            id: string;
+            name: string;
+        }>;
+        cycleModules?: Array<{
+            id: string;
+            name: string;
+        }>;
+    };
+    suggestedActions: Array<{
+        type: 'enable' | 'disable' | 'update' | 'choose-one' | 'install';
+        description: string;
+        targetModules: string[];
+    }>;
+};
+export type ModuleResolutionResult = {
+    resolvedModules: FateModuleManifest[];
+    issues: ModuleResolutionIssue[];
+    disabledModules: FateModuleManifest[];
+};

package/dist/resolution.js

@@ -0,0 +1 @@
+export {};

package/dist/validateBundleShape.d.ts

@@ -0,0 +1,10 @@
+import type { FateModBundle, FateModCapability } from './bundle';
+/**
+ * Cheap structural checks run on a freshly `import()`ed external bundle before
+ * anything (assembleMod, translations, the character sheet) trusts its shape.
+ * Throws a descriptive error on the first violation found — the app's loader
+ * catches it and quarantines the mod rather than letting a malformed bundle
+ * crash the app; the registry's CI smoke-load check runs the exact same
+ * function so the two never drift.
+ */
+export declare function validateBundleShape(bundle: unknown, capabilities: FateModCapability[] | undefined): asserts bundle is FateModBundle;

package/dist/validateBundleShape.js

@@ -0,0 +1,86 @@
+const LIFECYCLE_FNS = ['onInstall', 'onUninstall', 'onReconfigure'];
+// A legitimate skin overrides a handful of CSS custom properties/selectors —
+// sonder@theme-pink's real CSS is well under 1KB. This is generous headroom,
+// not a real ceiling on styling ambition: it exists only to bound the worst
+// case (a bloated or malicious stylesheet), since raw CSS can't execute
+// script and the existing whole-bundle size limit (manifestChecks.ts)
+// already covers the general case indirectly.
+const THEME_CSS_MAX_BYTES = 100 * 1024;
+/**
+ * Cheap structural checks run on a freshly `import()`ed external bundle before
+ * anything (assembleMod, translations, the character sheet) trusts its shape.
+ * Throws a descriptive error on the first violation found — the app's loader
+ * catches it and quarantines the mod rather than letting a malformed bundle
+ * crash the app; the registry's CI smoke-load check runs the exact same
+ * function so the two never drift.
+ */
+export function validateBundleShape(bundle, capabilities) {
+    if (!bundle || typeof bundle !== 'object') {
+        throw new Error('bundle default export must be an object');
+    }
+    const b = bundle;
+    if (capabilities?.includes('sheetComponents') && b.components !== undefined) {
+        if (!Array.isArray(b.components)) {
+            throw new Error('bundle.components must be an array');
+        }
+        b.components.forEach((component, index) => {
+            const c = component;
+            if (!c || typeof c !== 'object' || typeof c.id !== 'string' || typeof c.order !== 'number' || !c.component) {
+                throw new Error(`bundle.components[${index}] must be { id: string, component, order: number }`);
+            }
+        });
+    }
+    for (const fn of LIFECYCLE_FNS) {
+        if (b[fn] !== undefined && typeof b[fn] !== 'function') {
+            throw new Error(`bundle.${fn} must be a function`);
+        }
+    }
+    if (b.patches !== undefined) {
+        if (!Array.isArray(b.patches)) {
+            throw new Error('bundle.patches must be an array');
+        }
+        b.patches.forEach((patch, index) => {
+            const p = patch;
+            if (!p || typeof p !== 'object' || typeof p.version !== 'string' || typeof p.action !== 'function') {
+                throw new Error(`bundle.patches[${index}] must be { version: string, action: function }`);
+            }
+        });
+    }
+    if (capabilities?.includes('theme') && b.theme !== undefined) {
+        const theme = b.theme;
+        if (!theme || typeof theme.css !== 'string') {
+            throw new Error('bundle.theme.css must be a string');
+        }
+        if (theme.css.length > THEME_CSS_MAX_BYTES) {
+            throw new Error(`bundle.theme.css is ${(theme.css.length / 1024).toFixed(0)}KB, over the ${THEME_CSS_MAX_BYTES / 1024}KB limit for a theme mod`);
+        }
+    }
+    if (capabilities?.includes('dice') && b.dice !== undefined) {
+        const dice = b.dice;
+        if (!dice || typeof dice !== 'object') {
+            throw new Error('bundle.dice must be an object');
+        }
+        if (dice.shapes !== undefined) {
+            if (!Array.isArray(dice.shapes)) {
+                throw new Error('bundle.dice.shapes must be an array');
+            }
+            dice.shapes.forEach((shape, index) => {
+                const s = shape;
+                if (typeof shape !== 'function' || typeof s?.name !== 'string' || typeof s?.icon !== 'string') {
+                    throw new Error(`bundle.dice.shapes[${index}] must be a class with static name/icon strings`);
+                }
+            });
+        }
+        if (dice.materials !== undefined) {
+            if (!Array.isArray(dice.materials)) {
+                throw new Error('bundle.dice.materials must be an array');
+            }
+            dice.materials.forEach((material, index) => {
+                const m = material;
+                if (!m || typeof m !== 'object' || typeof m.name !== 'string' || typeof m.previewColor !== 'string' || !m.faceMaterial || !m.symbolMaterial) {
+                    throw new Error(`bundle.dice.materials[${index}] must be { name: string, faceMaterial, symbolMaterial, previewColor: string }`);
+                }
+            });
+        }
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@fate-app/mod-types",
+  "version": "2.0.0",
+  "description": "Shared TypeScript types and runtime helpers for Assistant for Fate mods — the single source of truth for the mod manifest/bundle shape, consumed by both the app and community mod authors.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Stanislavsonder/fate.git",
+    "directory": "packages/mod-types"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./registry.schema.json": "./registry.schema.json"
+  },
+  "files": [
+    "dist",
+    "registry.schema.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "cannon-es": "^0.20.0",
+    "three": "^0.185.0"
+  },
+  "peerDependencies": {
+    "cannon-es": "^0.20.0",
+    "three": "^0.185.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "cannon-es": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}

package/registry.schema.json

@@ -0,0 +1,97 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://stanislavsonder.github.io/fate-core-mods/registry.schema.json",
+	"title": "FATE: Core mod manifest.json",
+	"description": "Static, non-executable metadata for a mod submitted to fate-core-mods. Anything executable belongs in bundle.mjs, never here.",
+	"type": "object",
+	"required": ["id", "version", "name", "author", "description", "languages", "tags", "loadPriority", "sdk", "entry", "capabilities"],
+	"additionalProperties": false,
+	"properties": {
+		"id": {
+			"type": "string",
+			"pattern": "^[a-z0-9-]+@[a-z0-9-]+$",
+			"description": "\"author@name\", globally unique, lowercase kebab-case on both sides of the @."
+		},
+		"version": {
+			"type": "string",
+			"pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$",
+			"description": "Semver."
+		},
+		"name": {
+			"type": "string",
+			"minLength": 1,
+			"description": "\"t.name\" i18n key (resolved via signRecord) or a plain string."
+		},
+		"author": {
+			"type": "object",
+			"required": ["name", "github"],
+			"additionalProperties": false,
+			"properties": {
+				"name": { "type": "string", "minLength": 1 },
+				"email": { "type": "string", "format": "email" },
+				"url": { "type": "string", "format": "uri" },
+				"github": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "description": "GitHub handle — CI binds this to the PR author." }
+			}
+		},
+		"description": {
+			"type": "object",
+			"required": ["short"],
+			"additionalProperties": false,
+			"properties": {
+				"short": { "type": "string", "minLength": 1, "maxLength": 160 },
+				"full": { "type": "string" }
+			}
+		},
+		"languages": {
+			"type": "array",
+			"items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+			"minItems": 1,
+			"description": "Must match the files present under translations/."
+		},
+		"tags": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"dependencies": {
+			"type": "object",
+			"additionalProperties": { "type": "string" },
+			"description": "{ [modId]: semverRange }"
+		},
+		"incompatibleWith": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"appVersion": {
+			"type": "string",
+			"description": "Semver range gating the app version."
+		},
+		"loadPriority": {
+			"type": "number"
+		},
+		"sdk": {
+			"type": "string",
+			"description": "Semver range gating FateSDK.version (the ABI)."
+		},
+		"entry": {
+			"type": "string",
+			"const": "bundle.mjs"
+		},
+		"capabilities": {
+			"type": "array",
+			"minItems": 1,
+			"items": { "type": "string", "enum": ["sheetComponents", "dice", "theme", "translations"] },
+			"description": "\"sheetComponents\", \"dice\", and \"theme\" are fully supported for external mods (SDK >= 1.1.0). \"translations\" is declared-only for now: the manifest fields exist, but the app does not yet merge translation packs at runtime."
+		},
+		"translationTargets": {
+			"type": "array",
+			"items": { "type": "string", "pattern": "^(app|[a-z0-9-]+@[a-z0-9-]+)$" },
+			"minItems": 1,
+			"description": "For \"translations\"-capability mods: what this pack translates — \"app\" (the app's own UI strings) and/or other mod ids. Declarative only until the runtime merge ships; entry/bundle.mjs is still required for now."
+		},
+		"config": {
+			"type": "object",
+			"additionalProperties": true,
+			"description": "{ groups: [], options: [] } — declarative settings schema, structurally validated by the host app, not by this schema."
+		}
+	}
+}