@loontail/minecraft-kit 0.5.0 → 0.6.1

package/dist/index.d.ts

@@ -1,15 +1,91 @@
-/** Pluggable in-memory cache for HTTP metadata responses. */
-interface MetadataCache {
-    get<T>(key: string): T | undefined;
-    set<T>(key: string, value: T, ttlMs?: number): void;
-    delete(key: string): void;
-    clear(): void;
-}
+/** Authentication modes accepted by the launch composer. */
+declare const AuthModes: {
+    /** Offline-mode play with a chosen username and synthetic UUID. */
+    readonly OFFLINE: "offline";
+    /** Pre-authenticated session — caller provides the access token and identity. */
+    readonly ONLINE: "online";
+};
+/** Auth mode literal. */
+type AuthMode = (typeof AuthModes)[keyof typeof AuthModes];
+/** Offline authentication. */
+type OfflineAuth = {
+    readonly mode: typeof AuthModes.OFFLINE;
+    readonly username: string;
+    /** Optional explicit UUID. When omitted, a deterministic UUID is derived from the username. */
+    readonly uuid?: string;
+};
+/** Online (token-based) authentication. */
+type OnlineAuth = {
+    readonly mode: typeof AuthModes.ONLINE;
+    readonly username: string;
+    readonly uuid: string;
+    readonly accessToken: string;
+    readonly userType?: string;
+    readonly clientId?: string;
+    readonly xuid?: string;
+};
+/** Auth shape consumed by `kit.launch.compose`. */
+type LaunchAuth = OfflineAuth | OnlineAuth;
+/**
+ * Device-code prompt presented to the user. The caller renders these to the user, who then
+ * visits {@link verificationUri} in a browser and enters {@link userCode}.
+ */
+type DeviceCodePrompt = {
+    /** Short alphanumeric code the user types on the verification page. */
+    readonly userCode: string;
+    /** URI the user opens to complete sign-in (typically `https://microsoft.com/link`). */
+    readonly verificationUri: string;
+    /** Human-readable instruction string suggested by Microsoft. */
+    readonly message: string;
+    /** Seconds before the device/user code pair becomes invalid. */
+    readonly expiresIn: number;
+    /** Recommended seconds between polling requests. */
+    readonly interval: number;
+};
+/** Opaque state returned by `start()` and consumed by `poll()`. */
+type DeviceCodeState = {
+    readonly deviceCode: string;
+    readonly userCode: string;
+    readonly verificationUri: string;
+    readonly message: string;
+    readonly expiresIn: number;
+    readonly interval: number;
+    readonly clientId: string;
+    /** Wall-clock ms timestamp after which polling should stop. */
+    readonly expiresAt: number;
+};
+/**
+ * Combined Microsoft + Minecraft session returned by `kit.auth.login` and `kit.auth.refresh`.
+ *
+ * The fields under {@link minecraft} are everything {@link OnlineAuth} needs. The fields under
+ * {@link microsoft} are needed only by the launcher to refresh the session later — persist them
+ * to durable storage (encrypted) alongside the user's profile.
+ */
+type MojangSession = {
+    readonly minecraft: {
+        /** Player display name. */
+        readonly username: string;
+        /** Player UUID, dashed (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`). */
+        readonly uuid: string;
+        /** Bearer token for `api.minecraftservices.com` and the game itself. */
+        readonly accessToken: string;
+        /** Wall-clock ms timestamp when {@link accessToken} expires. */
+        readonly expiresAt: number;
+        /** Xbox User ID (XUID) as a numeric string. */
+        readonly xuid: string;
+    };
+    readonly microsoft: {
+        /** Microsoft refresh token; used to obtain a fresh session without re-prompting. */
+        readonly refreshToken: string;
+        /** Azure AD application id used to mint the session. */
+        readonly clientId: string;
+    };
+};
 
 /** Subset of fetch headers the library actually uses. */
 type HttpHeaders = Readonly<Record<string, string>>;
 /** Response delivered by the {@link HttpClient} interface. */
-interface HttpResponse {
+type HttpResponse = {
     readonly status: number;
     readonly headers: HttpHeaders;
     readonly url: string;
@@ -18,24 +94,161 @@ interface HttpResponse {
     bytes(): Promise<Uint8Array>;
     /** Stream the body. The stream may be consumed at most once. */
     stream(): AsyncIterable<Uint8Array>;
-}
+};
+/** HTTP method supported by {@link HttpClient}. */
+type HttpMethod = "GET" | "POST";
+/** Body payload accepted on POST requests. */
+type HttpRequestBody = string | Uint8Array;
 /** Options for an HTTP request. */
-interface HttpRequestOptions {
+type HttpRequestOptions = {
     readonly headers?: HttpHeaders;
     readonly signal?: AbortSignal;
     readonly timeoutMs?: number;
     /** When true, do not consult the in-memory cache. */
     readonly noCache?: boolean;
-}
+    /** HTTP method. Defaults to `GET`. */
+    readonly method?: HttpMethod;
+    /** Request body. Ignored for GET. */
+    readonly body?: HttpRequestBody;
+    /**
+     * When `true`, the client returns the response even for non-2xx statuses
+     * instead of throwing. Useful for callers that must inspect the body of
+     * error responses (e.g. OAuth polling endpoints that return 400 with
+     * structured JSON like `{"error":"authorization_pending"}`).
+     */
+    readonly acceptNonOk?: boolean;
+};
 /**
  * Pluggable HTTP client. The default implementation uses Node's built-in fetch; consumers
  * can inject a fake (e.g. for tests) by passing an `httpClient` to the {@link MinecraftKit}
  * constructor.
  */
-interface HttpClient {
+type HttpClient = {
     request(url: string, options?: HttpRequestOptions): Promise<HttpResponse>;
+};
+
+/** Log levels accepted by the pluggable logger. */
+declare const LogLevels: {
+    readonly DEBUG: "debug";
+    readonly INFO: "info";
+    readonly WARN: "warn";
+    readonly ERROR: "error";
+};
+/** Log-level literal. */
+type LogLevel = (typeof LogLevels)[keyof typeof LogLevels];
+/** Pluggable logger. Default implementation is a silent logger; pass your own to surface logs. */
+type Logger = {
+    log(level: LogLevel, message: string, fields?: Readonly<Record<string, unknown>>): void;
+};
+
+/** Env var consulted when no explicit `clientId` is supplied. */
+declare const CLIENT_ID_ENV_VAR = "MINECRAFT_KIT_MSA_CLIENT_ID";
+
+/** Options accepted by {@link MojangAuthApi.login}. */
+type LoginOptions = {
+    /**
+     * Azure AD application id. When omitted, the value of
+     * `process.env.MINECRAFT_KIT_MSA_CLIENT_ID` is used. Throws `AUTH_MISSING_CLIENT_ID` if
+     * neither is set — the library cannot ship a default client id.
+     */
+    readonly clientId?: string;
+    /**
+     * Called once with the URL + user code the user must enter in a browser. The promise
+     * returned by `login` resolves only after the user finishes signing in (or rejects on
+     * abort / decline / timeout).
+     */
+    readonly onPrompt: (prompt: DeviceCodePrompt) => void | Promise<void>;
+    /** Called once per polling tick — useful for UI "still waiting" feedback. */
+    readonly onPoll?: (info: {
+        readonly nextDelayMs: number;
+        readonly expiresAt: number;
+    }) => void;
+    readonly signal?: AbortSignal;
+};
+/** Options accepted by {@link MojangAuthApi.refresh}. */
+type RefreshOptions = {
+    /** As in {@link LoginOptions.clientId}. */
+    readonly clientId?: string;
+    readonly signal?: AbortSignal;
+};
+/** Options accepted by {@link MojangAuthApi.deviceCode.start}. */
+type StartDeviceCodeOptions = {
+    readonly clientId?: string;
+    readonly signal?: AbortSignal;
+};
+/** Options accepted by {@link MojangAuthApi.deviceCode.poll}. */
+type PollDeviceCodeOptions = {
+    readonly signal?: AbortSignal;
+    readonly onTick?: (info: {
+        readonly nextDelayMs: number;
+        readonly expiresAt: number;
+    }) => void;
+};
+/**
+ * High-level Microsoft / Mojang auth surface attached to {@link import("../kit").MinecraftKit}
+ * as `kit.auth`. Implements the standard 5-step flow:
+ *
+ * 1. Microsoft OAuth2 device-code grant against the `consumers` tenant.
+ * 2. Xbox Live RPS exchange.
+ * 3. XSTS token bound to `rp://api.minecraftservices.com/`.
+ * 4. `login_with_xbox` to get a Minecraft bearer token.
+ * 5. `minecraft/profile` to resolve the player UUID + display name.
+ *
+ * Returns a {@link MojangSession} carrying everything launch composition needs plus the
+ * Microsoft refresh token. The library does NOT persist tokens — that's the launcher's job.
+ */
+declare class MojangAuthApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Run the full device-code flow end-to-end. The caller supplies an `onPrompt` callback to
+     * render the URL + code to the user; this method polls until they finish.
+     */
+    login(options: LoginOptions): Promise<MojangSession>;
+    /** Refresh a previously obtained session. The Microsoft refresh token may be rotated. */
+    refresh(refreshToken: string, options?: RefreshOptions): Promise<MojangSession>;
+    /**
+     * Lower-level device-code surface — exposed so callers can decouple "show prompt" from
+     * "block on poll" (e.g. a GUI that lets the user dismiss the modal). Most callers should
+     * use {@link login} instead.
+     */
+    readonly deviceCode: {
+        start: (options?: StartDeviceCodeOptions) => Promise<{
+            readonly prompt: DeviceCodePrompt;
+            readonly state: DeviceCodeState;
+        }>;
+        poll: (state: DeviceCodeState, options?: PollDeviceCodeOptions) => Promise<MojangSession>;
+    };
+    /** Steps 2 → 5: given a Microsoft access token, finish the flow. */
+    private completeMicrosoftToken;
+}
+/**
+ * Project a {@link MojangSession} into the {@link OnlineAuth} shape that `kit.launch.compose`
+ * accepts.
+ */
+declare const toOnlineAuth: (session: MojangSession) => OnlineAuth;
+
+/**
+ * Cooperative pause primitive. Consumers call {@link waitWhilePaused} at safe
+ * checkpoints. Independent from `AbortSignal` — abort wins at the next signal
+ * check.
+ */
+declare class PauseController {
+    #private;
+    get paused(): boolean;
+    pause(): void;
+    resume(): void;
+    waitWhilePaused(): Promise<void>;
 }
 
+/** Pluggable in-memory cache for HTTP metadata responses. */
+type MetadataCache = {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttlMs?: number): void;
+    delete(key: string): void;
+    clear(): void;
+};
+
 /**
  * Minecraft release channels matching the `type` field of Mojang version manifest entries.
  */
@@ -53,7 +266,7 @@ type MinecraftChannel = (typeof MinecraftChannels)[keyof typeof MinecraftChannel
  * Note: this is a summary entry, not the full per-version manifest. Use
  * {@link ResolvedMinecraft} for the resolved/parsed full manifest.
  */
-interface MinecraftVersionSummary {
+type MinecraftVersionSummary = {
     /** Version id (e.g. `"1.20.1"`). */
     readonly id: string;
     /** Release channel. */
@@ -68,9 +281,9 @@ interface MinecraftVersionSummary {
     readonly sha1: string;
     /** Compliance level: 0 = legacy, 1 = secure-chat / safety features. */
     readonly complianceLevel: number;
-}
+};
 /** Subset of the per-version manifest used by resolvers and consumers. */
-interface MinecraftVersionManifest {
+type MinecraftVersionManifest = {
     readonly id: string;
     readonly type: MinecraftChannel | string;
     readonly mainClass: string;
@@ -91,30 +304,30 @@ interface MinecraftVersionManifest {
     readonly time?: string;
     readonly minimumLauncherVersion?: number;
     readonly complianceLevel?: number;
-}
+};
 /** Reference to the asset-index JSON file. */
-interface AssetIndexReference {
+type AssetIndexReference = {
     readonly id: string;
     readonly sha1: string;
     readonly size: number;
     readonly totalSize: number;
     readonly url: string;
-}
+};
 /** Per-platform downloads block of the Minecraft per-version manifest. */
-interface MinecraftDownloads {
+type MinecraftDownloads = {
     readonly client: ArtifactDownload;
     readonly server?: ArtifactDownload;
     readonly client_mappings?: ArtifactDownload;
     readonly server_mappings?: ArtifactDownload;
-}
+};
 /** A single hash-verified download. */
-interface ArtifactDownload {
+type ArtifactDownload = {
     readonly sha1: string;
     readonly size: number;
     readonly url: string;
-}
+};
 /** Library entry. Combines vanilla, modern-natives, and legacy-classifier shapes. */
-interface MinecraftLibrary {
+type MinecraftLibrary = {
     readonly name: string;
     readonly downloads?: MinecraftLibraryDownloads;
     readonly natives?: Readonly<Record<string, string>>;
@@ -124,18 +337,18 @@ interface MinecraftLibrary {
     readonly rules?: readonly LibraryRule[];
     /** Some Fabric/Forge libraries carry only a Maven base URL plus a coordinate. */
     readonly url?: string;
-}
+};
 /** Library downloads block. */
-interface MinecraftLibraryDownloads {
+type MinecraftLibraryDownloads = {
     readonly artifact?: LibraryArtifact;
     readonly classifiers?: Readonly<Record<string, LibraryArtifact>>;
-}
+};
 /** An individual library artifact (jar/zip). */
 interface LibraryArtifact extends ArtifactDownload {
     readonly path: string;
 }
 /** Rule entry used by libraries and modern arguments. */
-interface LibraryRule {
+type LibraryRule = {
     readonly action: "allow" | "disallow";
     readonly os?: {
         readonly name?: string;
@@ -143,25 +356,25 @@ interface LibraryRule {
         readonly version?: string;
     };
     readonly features?: Readonly<Record<string, boolean>>;
-}
+};
 /** Modern (1.13+) arguments structure. */
-interface MinecraftArguments {
+type MinecraftArguments = {
     readonly game: readonly ArgumentEntry[];
     readonly jvm: readonly ArgumentEntry[];
-}
+};
 /** A single argument entry: bare string or rule-gated value. */
 type ArgumentEntry = string | {
     readonly rules: readonly LibraryRule[];
     readonly value: string | readonly string[];
 };
 /** Required Java runtime descriptor from the version manifest. */
-interface MinecraftJavaVersion {
+type MinecraftJavaVersion = {
     /** Mojang java-runtime component name (e.g. `java-runtime-gamma`). */
     readonly component: string;
     readonly majorVersion: number;
-}
+};
 /** Logging-config entry from the version manifest. */
-interface MinecraftLogging {
+type MinecraftLogging = {
     readonly client?: {
         readonly argument: string;
         readonly file: ArtifactDownload & {
@@ -169,49 +382,49 @@ interface MinecraftLogging {
         };
         readonly type: string;
     };
-}
+};
 /**
  * Fully resolved Minecraft version: summary + parsed manifest, ready to feed into
  * `kit.targets.create` or `kit.install.plan`.
  */
-interface ResolvedMinecraft {
+type ResolvedMinecraft = {
     /** Version id (e.g. `"1.20.1"`). */
     readonly version: string;
     readonly channel: MinecraftChannel;
     readonly manifest: MinecraftVersionManifest;
     readonly summary: MinecraftVersionSummary;
-}
+};
 /** Asset index document body. */
-interface AssetIndexDocument {
+type AssetIndexDocument = {
     readonly objects: Readonly<Record<string, AssetObject>>;
     readonly virtual?: boolean;
     readonly map_to_resources?: boolean;
-}
+};
 /** A single asset object hash + size. */
-interface AssetObject {
+type AssetObject = {
     readonly hash: string;
     readonly size: number;
-}
+};
 
 /** Summary entry from `/v2/versions/loader`. */
-interface FabricLoaderSummary {
+type FabricLoaderSummary = {
     readonly version: string;
     readonly stable: boolean;
     readonly maven: string;
     readonly build: number;
     readonly separator: string;
-}
+};
 /** Compatibility entry from `/v2/versions/loader/{minecraftVersion}`. */
-interface FabricCompatibilityEntry {
+type FabricCompatibilityEntry = {
     readonly loader: FabricLoaderSummary;
     readonly intermediary: {
         readonly version: string;
         readonly maven: string;
         readonly stable: boolean;
     };
-}
+};
 /** Fabric profile JSON returned by `/v2/versions/loader/{mc}/{loader}/profile/json`. */
-interface FabricProfile {
+type FabricProfile = {
     readonly id: string;
     readonly inheritsFrom: string;
     readonly type: string;
@@ -221,17 +434,17 @@ interface FabricProfile {
         readonly game?: readonly string[];
         readonly jvm?: readonly string[];
     };
-}
+};
 /** Resolved Fabric loader for a specific Minecraft version. */
-interface ResolvedFabricLoader {
+type ResolvedFabricLoader = {
     readonly type: typeof Loaders.FABRIC;
     readonly minecraftVersion: string;
     readonly loaderVersion: string;
     readonly profile: FabricProfile;
-}
+};
 
 /** A Forge build entry derived from the Maven metadata XML. */
-interface ForgeBuildSummary {
+type ForgeBuildSummary = {
     /** Full Maven version string e.g. `"1.20.1-47.2.0"`. */
     readonly fullVersion: string;
     /** Minecraft version e.g. `"1.20.1"`. */
@@ -242,9 +455,9 @@ interface ForgeBuildSummary {
     readonly isRecommended: boolean;
     /** True when this build is the latest one per `promotions_slim.json`. */
     readonly isLatest: boolean;
-}
+};
 /** Modern Forge `install_profile.json` (spec 1) shape — only fields we actually consume. */
-interface ForgeInstallProfile {
+type ForgeInstallProfile = {
     readonly spec: number;
     readonly profile: string;
     readonly version: string;
@@ -257,22 +470,22 @@ interface ForgeInstallProfile {
     readonly libraries: readonly MinecraftLibrary[];
     readonly processors: readonly ForgeProcessor[];
     readonly serverJarPath?: string;
-}
+};
 /** Side-keyed data value pair. */
-interface ForgeProfileData {
+type ForgeProfileData = {
     readonly client: string;
     readonly server: string;
-}
+};
 /** A single processor invocation. */
-interface ForgeProcessor {
+type ForgeProcessor = {
     readonly sides?: readonly ("client" | "server" | "extract")[];
     readonly jar: string;
     readonly classpath: readonly string[];
     readonly args: readonly string[];
     readonly outputs?: Readonly<Record<string, string>>;
-}
+};
 /** The version.json stored inside the Forge installer JAR. */
-interface ForgeVersionJson {
+type ForgeVersionJson = {
     readonly id: string;
     readonly inheritsFrom: string;
     readonly type: string;
@@ -282,27 +495,27 @@ interface ForgeVersionJson {
         readonly game?: readonly string[];
         readonly jvm?: readonly string[];
     };
-}
+};
 /** Resolved Forge loader. */
-interface ResolvedForgeLoader {
+type ResolvedForgeLoader = {
     readonly type: typeof Loaders.FORGE;
     readonly minecraftVersion: string;
     readonly forgeVersion: string;
     readonly fullVersion: string;
     readonly installerUrl: string;
-}
+};
 
 /**
  * Trivial loader used when no mod loader is in play. Carries the resolved Minecraft so the
  * launch composer has a uniform view across vanilla / Fabric / Forge.
  */
-interface ResolvedVanillaLoader {
+type ResolvedVanillaLoader = {
     readonly type: typeof Loaders.VANILLA;
     /** Minecraft version this loader is pinned to. */
     readonly minecraftVersion: string;
     /** The Minecraft manifest used for launch — same as the target's `minecraft.manifest`. */
     readonly minecraft: ResolvedMinecraft;
-}
+};
 
 /**
  * Discriminator literal identifying which mod loader is active for a target.
@@ -364,14 +577,14 @@ type Architecture = (typeof Architectures)[keyof typeof Architectures];
  * Identifies the host system for the launcher. All resolvers consume this object to
  * pick the right artifacts (libraries, natives, runtime).
  */
-interface RuntimeSystem {
+type RuntimeSystem = {
     /** OS identifier (mojang naming). */
     readonly os: OperatingSystem;
     /** CPU architecture (mojang naming). */
     readonly arch: Architecture;
     /** OS version string from `os.release()`. Used to evaluate library `os.version` regex rules. */
     readonly osVersion: string;
-}
+};
 
 /**
  * Mojang Java-runtime component identifiers. New components appear over time
@@ -407,7 +620,7 @@ type RuntimeIndex = Readonly<Record<string, RuntimeIndexPlatform>>;
 /** Per-platform component map inside the runtime index. */
 type RuntimeIndexPlatform = Readonly<Record<string, readonly RuntimeIndexEntry[]>>;
 /** A single available runtime release. */
-interface RuntimeIndexEntry {
+type RuntimeIndexEntry = {
     readonly availability: {
         readonly group: number;
         readonly progress: number;
@@ -421,15 +634,15 @@ interface RuntimeIndexEntry {
         readonly name: string;
         readonly released: string;
     };
-}
+};
 /** Inner per-component file manifest. */
-interface RuntimeFilesManifest {
+type RuntimeFilesManifest = {
     readonly files: Readonly<Record<string, RuntimeFileEntry>>;
-}
+};
 /** A single file in the runtime manifest. */
 type RuntimeFileEntry = RuntimeFileFile | RuntimeFileDirectory | RuntimeFileLink;
 /** A file entry: real bytes to download, may have lzma sidecar. */
-interface RuntimeFileFile {
+type RuntimeFileFile = {
     readonly type: "file";
     readonly executable: boolean;
     readonly downloads: {
@@ -444,18 +657,18 @@ interface RuntimeFileFile {
             readonly url: string;
         };
     };
-}
+};
 /** A directory placeholder. */
-interface RuntimeFileDirectory {
+type RuntimeFileDirectory = {
     readonly type: "directory";
-}
+};
 /** A relative symlink. */
-interface RuntimeFileLink {
+type RuntimeFileLink = {
     readonly type: "link";
     readonly target: string;
-}
+};
 /** Resolved runtime ready to install or launch with. */
-interface ResolvedRuntime {
+type ResolvedRuntime = {
     /** Mojang component name (e.g. `java-runtime-gamma`). */
     readonly component: string;
     /** Platform key inside the runtime index (e.g. `windows-x64`). */
@@ -474,7 +687,7 @@ interface ResolvedRuntime {
      * live at `<installRoot>/<component>/...`. When unset, defaults to `<target.directory>/runtime`.
      */
     readonly installRoot?: string;
-}
+};
 
 /**
  * Fully resolved target: a concrete Minecraft + loader + runtime + directory.
@@ -483,7 +696,7 @@ interface ResolvedRuntime {
  * it. `kit.targets.create` produces a Target from already-resolved components;
  * `kit.targets.resolve` resolves them in one go.
  */
-interface Target {
+type Target = {
     /** Stable identifier chosen by the consumer. Used for diagnostics, not persistence. */
     readonly id: string;
     /** Absolute or relative path to the per-target Minecraft directory. */
@@ -491,20 +704,20 @@ interface Target {
     readonly minecraft: ResolvedMinecraft;
     readonly loader: Loader;
     readonly runtime: ResolvedRuntime;
-}
+};
 /** Inputs accepted by `kit.targets.create`. */
-interface TargetCreateInput {
+type TargetCreateInput = {
     readonly id: string;
     readonly directory: string;
     readonly minecraft: ResolvedMinecraft;
     readonly loader: Loader;
     readonly runtime: ResolvedRuntime;
-}
+};
 /**
  * Discovered installation found by scanning a root directory. Contains only what was
  * actually read from disk — no assumptions about correctness, completeness, or repair state.
  */
-interface DiscoveredTarget {
+type DiscoveredTarget = {
     /** Subdirectory name under the scanned root. */
     readonly id: string;
     /** Absolute or normalized directory path. */
@@ -515,19 +728,19 @@ interface DiscoveredTarget {
     readonly loaders: readonly DiscoveredLoaderHint[];
     /** Detected Java executable, when one is present in the per-target `runtime/` folder. */
     readonly runtime?: DiscoveredRuntimeHint;
-}
+};
 /** Inferred loader hint (does not assert correctness). */
-interface DiscoveredLoaderHint {
+type DiscoveredLoaderHint = {
     readonly type: LoaderKind;
     readonly minecraftVersion?: string;
     readonly version?: string;
-}
+};
 /** Detected runtime files. */
-interface DiscoveredRuntimeHint {
+type DiscoveredRuntimeHint = {
     readonly component?: string;
     readonly javaPath?: string;
     readonly javaVersion?: string;
-}
+};
 
 /**
  * Coarse-grained install phases. Used in `install:phase-changed` events so consumers can
@@ -560,50 +773,84 @@ declare const InstallActionKinds: {
 };
 /** Discriminator for an install action. */
 type InstallActionKind = (typeof InstallActionKinds)[keyof typeof InstallActionKinds];
+/**
+ * Categorisation tag on every {@link DownloadAction}. Drives the install-phase mapping
+ * and lets consumers filter the plan to a subset (e.g. "runtime only").
+ */
+declare const DownloadCategories: {
+    readonly CLIENT_JAR: "client-jar";
+    readonly LIBRARY: "library";
+    readonly ASSET_INDEX: "asset-index";
+    readonly ASSET: "asset";
+    readonly LOGGING_CONFIG: "logging-config";
+    readonly FABRIC_LIBRARY: "fabric-library";
+    readonly FORGE_LIBRARY: "forge-library";
+    readonly RUNTIME_FILE: "runtime-file";
+    readonly FORGE_INSTALLER: "forge-installer";
+};
+/** Download category literal — drives `runInstall` phase boundaries. */
+type DownloadCategory = (typeof DownloadCategories)[keyof typeof DownloadCategories];
 /** A single download step. */
-interface DownloadAction {
+type DownloadAction = {
     readonly kind: typeof InstallActionKinds.DOWNLOAD_FILE;
     readonly url: string;
     readonly target: string;
     readonly expectedSha1?: string;
     readonly expectedSize?: number;
-    readonly category: "client-jar" | "library" | "asset-index" | "asset" | "logging-config" | "fabric-library" | "forge-library" | "runtime-file" | "forge-installer";
-}
+    readonly category: DownloadCategory;
+};
 /** A native extraction step. Source jar must already exist on disk. */
-interface ExtractNativeAction {
+type ExtractNativeAction = {
     readonly kind: typeof InstallActionKinds.EXTRACT_NATIVE;
     readonly source: string;
     readonly destination: string;
     readonly exclude: readonly string[];
-}
+};
 /**
  * A Forge processor invocation. `Main-Class` is intentionally NOT carried here — the
  * runner reads it from `classpath[0]`'s manifest at execution time, because the JAR is
  * not guaranteed to exist on disk during planning (newer Forge versions ship some
  * processor JARs as regular Maven libraries instead of bundling them in the installer).
  */
-interface RunForgeProcessorAction {
+type RunForgeProcessorAction = {
     readonly kind: typeof InstallActionKinds.RUN_FORGE_PROCESSOR;
     readonly index: number;
     /** First entry is the processor JAR; remaining entries are its declared classpath. */
     readonly classpath: readonly string[];
     readonly args: readonly string[];
     readonly outputs: Readonly<Record<string, string>>;
-}
+};
 /** Write a version JSON to disk (Fabric / Forge). */
-interface WriteVersionJsonAction {
+type WriteVersionJsonAction = {
     readonly kind: typeof InstallActionKinds.WRITE_VERSION_JSON;
     readonly path: string;
     readonly content: string;
-}
+};
 /** Write a logging config (log4j XML) to disk. */
-interface WriteLoggingConfigAction {
+type WriteLoggingConfigAction = {
     readonly kind: typeof InstallActionKinds.WRITE_LOGGING_CONFIG;
     readonly path: string;
     readonly content: string;
-}
+};
 /** Discriminated union of install actions. */
 type InstallAction = DownloadAction | ExtractNativeAction | RunForgeProcessorAction | WriteVersionJsonAction | WriteLoggingConfigAction;
+/**
+ * A "runtime-only" install plan target. Used by `planStandaloneRuntimeInstall` to plan a
+ * JRE-only install without a Minecraft version/loader pinned to the plan.
+ */
+type RuntimeOnlyInstallTarget = {
+    readonly id: string;
+    readonly directory: string;
+    readonly runtime: ResolvedRuntime;
+    readonly minecraft?: undefined;
+    readonly loader?: undefined;
+};
+/**
+ * Shape of `InstallPlan.target`. Either a fully-resolved {@link import("./target").Target} or a
+ * runtime-only stand-in. The install runner only reads `target.minecraft`/`target.loader` when
+ * the plan actually contains those steps, so runtime-only plans are safe.
+ */
+type InstallPlanTarget = Target | RuntimeOnlyInstallTarget;
 /**
  * Pre-computed install plan: a flat ordered list of actions plus computed totals.
  *
@@ -611,30 +858,30 @@ type InstallAction = DownloadAction | ExtractNativeAction | RunForgeProcessorAct
  * carries a reference to the resolved target so the runner does not need a second target
  * argument.
  */
-interface InstallPlan {
+type InstallPlan = {
     readonly targetId: string;
     readonly directory: string;
-    readonly target: Target;
+    readonly target: InstallPlanTarget;
     readonly actions: readonly InstallAction[];
     readonly totalBytes: number;
     readonly totalActions: number;
-}
+};
 /** Outcome summary returned by `install.run`. */
-interface InstallReport {
+type InstallReport = {
     readonly targetId: string;
     readonly bytesDownloaded: number;
     readonly actionsCompleted: number;
     readonly actionsSkipped: number;
     readonly durationMs: number;
-}
+};
 
 /** Inputs to {@link planRuntimeInstall}. */
-interface PlanRuntimeInstallInput {
+type PlanRuntimeInstallInput = {
     readonly target: Target;
     readonly http: HttpClient;
     readonly cache: MetadataCache;
     readonly signal?: AbortSignal;
-}
+};
 /**
  * Build an install plan that downloads ONLY the Java runtime declared by `target.runtime`.
  *
@@ -646,9 +893,9 @@ interface PlanRuntimeInstallInput {
  * install runner — directory placeholders and symlinks declared by the runtime manifest are
  * still materialized after downloads complete.
  */
-declare function planRuntimeInstall(input: PlanRuntimeInstallInput): Promise<InstallPlan>;
+declare const planRuntimeInstall: (input: PlanRuntimeInstallInput) => Promise<InstallPlan>;
 /** Inputs to {@link planStandaloneRuntimeInstall}. */
-interface PlanStandaloneRuntimeInstallInput {
+type PlanStandaloneRuntimeInstallInput = {
     readonly id: string;
     /** Where the runtime files live. Used as `directory` if `runtime.installRoot` is unset. */
     readonly directory: string;
@@ -656,210 +903,22 @@ interface PlanStandaloneRuntimeInstallInput {
     readonly http: HttpClient;
     readonly cache: MetadataCache;
     readonly signal?: AbortSignal;
-}
+};
 /**
  * Plan a runtime-only install **without a Minecraft target**. Useful for "Install Java/runtime"
  * flows where the user just wants a JRE on disk and never had a Minecraft version to choose
- * from. The returned plan is shaped exactly like a normal {@link InstallPlan} and runs through
- * the standard install runner — but its `target.minecraft` and `target.loader` fields are
- * intentional placeholders. The runner only reads `target.runtime` for runtime-only plans, so
- * the placeholders are never accessed at runtime.
+ * from. The returned plan is shaped exactly like a normal {@link InstallPlan} but uses a
+ * {@link RuntimeOnlyInstallTarget} that carries only the runtime + directory — the runner skips
+ * Minecraft/loader-specific stages because they have no actions in this plan.
  */
-declare function planStandaloneRuntimeInstall(input: PlanStandaloneRuntimeInstallInput): Promise<InstallPlan>;
+declare const planStandaloneRuntimeInstall: (input: PlanStandaloneRuntimeInstallInput) => Promise<InstallPlan>;
 
-/** Log levels accepted by the pluggable logger. */
-declare const LogLevels: {
-    readonly DEBUG: "debug";
-    readonly INFO: "info";
-    readonly WARN: "warn";
-    readonly ERROR: "error";
-};
-/** Log-level literal. */
-type LogLevel = (typeof LogLevels)[keyof typeof LogLevels];
-/** Pluggable logger. Default implementation is a silent logger; pass your own to surface logs. */
-interface Logger {
-    log(level: LogLevel, message: string, fields?: Readonly<Record<string, unknown>>): void;
-}
-
-/** Shared context passed to every resolver. */
-interface ResolverContext {
-    readonly http: HttpClient;
-    readonly cache: MetadataCache;
-    readonly logger: Logger;
-}
-
-/** Inputs to {@link FabricVersionsApi.list}. */
-interface FabricListInput {
-    readonly minecraftVersion?: string;
-    readonly signal?: AbortSignal;
-}
-/** Inputs to {@link FabricVersionsApi.resolve}. */
-interface FabricResolveInput {
-    readonly minecraftVersion: string;
-    readonly preference?: VersionPreferenceKind;
-    readonly loaderVersion?: string;
-    readonly signal?: AbortSignal;
-}
-/** Public Fabric versions API surface. */
-declare class FabricVersionsApi {
-    private readonly ctx;
-    constructor(ctx: ResolverContext);
-    /** List Fabric loader versions, optionally constrained to a Minecraft version. */
-    list(input?: FabricListInput): Promise<readonly FabricLoaderSummary[]>;
-    /** Resolve a Fabric loader version against a Minecraft version. */
-    resolve(input: FabricResolveInput): Promise<ResolvedFabricLoader>;
-}
-
-/** Inputs to {@link ForgeVersionsApi.list}. */
-interface ForgeListInput {
-    readonly minecraftVersion?: string;
-    readonly signal?: AbortSignal;
-}
-/** Inputs to {@link ForgeVersionsApi.resolve}. */
-interface ForgeResolveInput {
-    readonly minecraftVersion: string;
-    readonly preference?: VersionPreferenceKind;
-    readonly forgeVersion?: string;
-    readonly signal?: AbortSignal;
-}
-/** Public Forge versions API surface. */
-declare class ForgeVersionsApi {
-    private readonly ctx;
-    constructor(ctx: ResolverContext);
-    /** List Forge builds (across all Minecraft versions, or filtered to one). */
-    list(input?: ForgeListInput): Promise<readonly ForgeBuildSummary[]>;
-    /** Resolve a Forge build for a Minecraft version. */
-    resolve(input: ForgeResolveInput): Promise<ResolvedForgeLoader>;
-}
-
-/** Inputs to {@link MinecraftVersionsApi.list}. */
-interface MinecraftListInput {
-    readonly channel?: MinecraftChannel;
-    readonly signal?: AbortSignal;
-}
-/** Inputs to {@link MinecraftVersionsApi.latest}. */
-interface MinecraftLatestInput {
-    readonly channel?: MinecraftChannel;
-    readonly signal?: AbortSignal;
-}
-/** Inputs to {@link MinecraftVersionsApi.get} / `.resolve`. */
-interface MinecraftGetInput {
-    readonly version: string;
-    readonly signal?: AbortSignal;
-}
-/** Public Minecraft versions API surface. */
-declare class MinecraftVersionsApi {
-    private readonly ctx;
-    constructor(ctx: ResolverContext);
-    /** List all Minecraft versions, optionally filtered by channel. */
-    list(input?: MinecraftListInput): Promise<readonly MinecraftVersionSummary[]>;
-    /** Return the latest version on the given channel (defaults to RELEASE). */
-    latest(input?: MinecraftLatestInput): Promise<MinecraftVersionSummary>;
-    /** Return a single version summary or throw `MANIFEST_NOT_FOUND`. */
-    get(input: MinecraftGetInput): Promise<MinecraftVersionSummary>;
-    /** Fetch and parse the per-version manifest in addition to the summary. */
-    resolve(input: MinecraftGetInput): Promise<ResolvedMinecraft>;
-    private fetchManifestRoot;
-}
-
-/** Inputs to {@link RuntimeVersionsApi.list}. */
-interface RuntimeListInput {
-    readonly system: RuntimeSystem;
-    readonly minecraftVersion?: string;
-    readonly signal?: AbortSignal;
-}
-/** A summary entry for the list API. */
-interface RuntimeListEntry {
-    readonly component: string;
-    readonly platformKey: string;
-    readonly versionName: string;
-    readonly released: string;
-    readonly manifestUrl: string;
-}
-/** Inputs to {@link RuntimeVersionsApi.resolve}. */
-interface RuntimeResolveInput {
-    readonly system: RuntimeSystem;
-    readonly minecraftVersion?: string;
-    readonly component?: string;
-    readonly preference?: RuntimePreferenceKind;
-    readonly signal?: AbortSignal;
-}
-/** Public runtime versions API surface. */
-declare class RuntimeVersionsApi {
-    private readonly ctx;
-    constructor(ctx: ResolverContext);
-    /** List available runtime entries for the host platform. */
-    list(input: RuntimeListInput): Promise<readonly RuntimeListEntry[]>;
-    /** Resolve a single runtime for the host platform and Minecraft version. */
-    resolve(input: RuntimeResolveInput): Promise<ResolvedRuntime>;
-    private fetchIndex;
-}
-
-/** Inputs to {@link TargetsApi.resolve}. */
-interface TargetResolveInput {
-    readonly id: string;
-    readonly directory: string;
-    readonly minecraft: {
-        readonly version: string;
-    };
-    readonly loader: TargetLoaderInput;
-    readonly runtime?: {
-        readonly preference?: RuntimePreferenceKind;
-        /** Override the runtime component. Defaults to the Minecraft manifest's `javaVersion.component`. */
-        readonly component?: string;
-        /**
-         * Custom install root (absolute path) holding the component directories.
-         * When unset, runtime files live under `<directory>/runtime/`.
-         */
-        readonly installRoot?: string;
-    };
-    readonly system?: RuntimeSystem;
-    readonly signal?: AbortSignal;
-}
-/** Loader input variants. */
-type TargetLoaderInput = {
-    readonly type: typeof Loaders.VANILLA;
-} | {
-    readonly type: typeof Loaders.FABRIC;
-    readonly preference?: VersionPreferenceKind;
-    readonly version?: string;
-} | {
-    readonly type: typeof Loaders.FORGE;
-    readonly preference?: VersionPreferenceKind;
-    readonly version?: string;
-};
-/** Inputs to {@link TargetsApi.list}. */
-interface TargetListInput {
-    readonly rootDir: string;
-}
-/** Constructor inputs for {@link TargetsApi}. */
-interface TargetsApiContext {
-    readonly minecraft: MinecraftVersionsApi;
-    readonly fabric: FabricVersionsApi;
-    readonly forge: ForgeVersionsApi;
-    readonly runtime: RuntimeVersionsApi;
-    readonly system: RuntimeSystem;
-}
-/** Public Targets API surface. */
-declare class TargetsApi {
-    private readonly ctx;
-    constructor(ctx: TargetsApiContext);
-    /** The detected host system used by `resolve()` when no `system` is supplied. */
-    get system(): RuntimeSystem;
-    /** Build a {@link Target} from already-resolved components. */
-    create(input: TargetCreateInput): Target;
-    /** Sugar API: resolve every component then assemble a target. */
-    resolve(input: TargetResolveInput): Promise<Target>;
-    /** Scan a root directory for Minecraft installations. Returns only what is on disk. */
-    list(input: TargetListInput): Promise<readonly DiscoveredTarget[]>;
-}
-
-/** Aspect of an installation a verification result describes. */
-declare const VerificationKinds: {
-    readonly MINECRAFT: "minecraft";
-    readonly FABRIC: "fabric";
-    readonly FORGE: "forge";
-    readonly RUNTIME: "runtime";
+/** Aspect of an installation a verification result describes. */
+declare const VerificationKinds: {
+    readonly MINECRAFT: "minecraft";
+    readonly FABRIC: "fabric";
+    readonly FORGE: "forge";
+    readonly RUNTIME: "runtime";
 };
 /** Verification kind literal. */
 type VerificationKind = (typeof VerificationKinds)[keyof typeof VerificationKinds];
@@ -886,7 +945,7 @@ declare const VerifyFileCategories: {
 /** Verification file category literal. */
 type VerifyFileCategory = (typeof VerifyFileCategories)[keyof typeof VerifyFileCategories];
 /** A single verified file. */
-interface VerificationFileResult {
+type VerificationFileResult = {
     readonly path: string;
     readonly category: VerifyFileCategory;
     readonly status: VerifyFileStatus;
@@ -896,16 +955,16 @@ interface VerificationFileResult {
     readonly actualSize?: number;
     /** Optional URL where the file can be re-downloaded if it's broken. */
     readonly url?: string;
-}
+};
 /** Aggregate verification result returned by each `verify.<kind>.run` API. */
-interface VerificationResult {
+type VerificationResult = {
     readonly targetId: string;
     readonly kind: VerificationKind;
     readonly isValid: boolean;
     readonly issues: readonly VerificationFileResult[];
     readonly checkedFiles: number;
     readonly durationMs: number;
-}
+};
 
 /** Coarse-grained repair phases used for `repair:phase-changed` events. */
 declare const RepairPhases: {
@@ -924,33 +983,33 @@ type RepairPhase = (typeof RepairPhases)[keyof typeof RepairPhases];
  * A repair plan is, structurally, an install plan limited to actions needed to fix the
  * issues reported by a previous {@link VerificationResult}. The runner is the same.
  */
-interface RepairPlan {
+type RepairPlan = {
     readonly targetId: string;
     readonly directory: string;
     readonly target: Target;
     readonly actions: readonly InstallAction[];
     readonly totalBytes: number;
     readonly totalActions: number;
-}
+};
 /** Repair report — same shape as install report. */
-interface RepairReport {
+type RepairReport = {
     readonly targetId: string;
     readonly bytesDownloaded: number;
     readonly actionsCompleted: number;
     readonly durationMs: number;
-}
+};
 /**
  * Inputs accepted by every aspect-specific `planXxxRepair` (`planMinecraftRepair`,
  * `planFabricRepair`, `planForgeRepair`, `planRuntimeRepair`). The per-aspect input types
  * are aliases over this shape.
  */
-interface AspectRepairInput {
+type AspectRepairInput = {
     readonly target: Target;
     readonly from: VerificationResult | readonly VerificationResult[];
     readonly http: HttpClient;
     readonly cache: MetadataCache;
     readonly signal?: AbortSignal;
-}
+};
 
 /**
  * Stable string constants for the `type` discriminator of every {@link ProgressEvent}.
@@ -982,16 +1041,16 @@ declare const EventTypes: {
 /** Literal type of the `type` discriminator of a {@link ProgressEvent}. */
 type EventType = (typeof EventTypes)[keyof typeof EventTypes];
 /** Reference to a single file used in download events. */
-interface FileRef {
+type FileRef = {
     readonly url: string;
     readonly target: string;
     readonly category?: string;
-}
+};
 /** A single processor description used in Forge events. */
-interface ProcessorRef {
+type ProcessorRef = {
     readonly index: number;
     readonly mainClass: string;
-}
+};
 /**
  * Discriminated union of all runtime progress events. Pass an `onEvent` callback to
  * `install.run`, `update.run`, `verify.run`, `repair.run`, or `launch.run` to receive these.
@@ -1086,52 +1145,246 @@ type ProgressEvent = {
 /** Listener signature accepted by every long-running operation. */
 type ProgressListener = (event: ProgressEvent) => void;
 /** Common options accepted by long-running operations. */
-interface OperationOptions {
+type OperationOptions = {
     readonly signal?: AbortSignal;
     readonly onEvent?: ProgressListener;
+};
+
+/** Stream-of-text channel exposed by spawned processes. */
+type ProcessStream = {
+    on(event: "data", listener: (chunk: string) => void): void;
+};
+/** Live handle for a child process. */
+type SpawnedProcess = {
+    readonly pid: number;
+    readonly stdout: ProcessStream;
+    readonly stderr: ProcessStream;
+    /** Resolves when the process exits with its exit info. */
+    readonly exited: Promise<{
+        readonly code: number | null;
+        readonly signal: NodeJS.Signals | null;
+    }>;
+    /** Send a termination signal. Returns true on success. */
+    kill(signal?: NodeJS.Signals): boolean;
+};
+/** Options accepted by the spawner. */
+type SpawnOptions = {
+    readonly cwd: string;
+    readonly env?: Readonly<Record<string, string>>;
+};
+/**
+ * Pluggable process spawner. The default implementation uses `node:child_process`; tests
+ * inject a fake to avoid spawning real processes.
+ */
+type Spawner = {
+    spawn(command: string, args: readonly string[], options: SpawnOptions): SpawnedProcess;
+};
+
+type RepairAllInput = {
+    readonly target: Target;
+    readonly http: HttpClient;
+    readonly cache: MetadataCache;
+    readonly spawner: Spawner;
+    readonly signal?: AbortSignal;
+    readonly onEvent?: ProgressListener;
+};
+type RepairAllReport = {
+    readonly verifications: readonly VerificationResult[];
+    /** Present only for aspects that actually needed work. */
+    readonly repairs: ReadonlyMap<VerificationKind, RepairReport>;
+    readonly bytesDownloaded: number;
+    readonly durationMs: number;
+};
+/** Verify every applicable aspect and repair each broken one. */
+declare const repairAll: (input: RepairAllInput) => Promise<RepairAllReport>;
+
+/** Shared context passed to every resolver. */
+type ResolverContext = {
+    readonly http: HttpClient;
+    readonly cache: MetadataCache;
+    readonly logger: Logger;
+};
+
+/** Inputs to {@link FabricVersionsApi.list}. */
+type FabricListInput = {
+    readonly minecraftVersion?: string;
+    readonly signal?: AbortSignal;
+};
+/** Inputs to {@link FabricVersionsApi.resolve}. */
+type FabricResolveInput = {
+    readonly minecraftVersion: string;
+    readonly preference?: VersionPreferenceKind;
+    readonly loaderVersion?: string;
+    readonly signal?: AbortSignal;
+};
+/** Public Fabric versions API surface. */
+declare class FabricVersionsApi {
+    private readonly ctx;
+    constructor(ctx: ResolverContext);
+    /** List Fabric loader versions, optionally constrained to a Minecraft version. */
+    list(input?: FabricListInput): Promise<readonly FabricLoaderSummary[]>;
+    /** Resolve a Fabric loader version against a Minecraft version. */
+    resolve(input: FabricResolveInput): Promise<ResolvedFabricLoader>;
 }
 
-/** Authentication modes accepted by the launch composer. */
-declare const AuthModes: {
-    /** Offline-mode play with a chosen username and synthetic UUID. */
-    readonly OFFLINE: "offline";
-    /** Pre-authenticated session — caller provides the access token and identity. */
-    readonly ONLINE: "online";
+/** Inputs to {@link ForgeVersionsApi.list}. */
+type ForgeListInput = {
+    readonly minecraftVersion?: string;
+    readonly signal?: AbortSignal;
+};
+/** Inputs to {@link ForgeVersionsApi.resolve}. */
+type ForgeResolveInput = {
+    readonly minecraftVersion: string;
+    readonly preference?: VersionPreferenceKind;
+    readonly forgeVersion?: string;
+    readonly signal?: AbortSignal;
+};
+/** Public Forge versions API surface. */
+declare class ForgeVersionsApi {
+    private readonly ctx;
+    constructor(ctx: ResolverContext);
+    /** List Forge builds (across all Minecraft versions, or filtered to one). */
+    list(input?: ForgeListInput): Promise<readonly ForgeBuildSummary[]>;
+    /** Resolve a Forge build for a Minecraft version. */
+    resolve(input: ForgeResolveInput): Promise<ResolvedForgeLoader>;
+}
+
+/** Inputs to {@link MinecraftVersionsApi.list}. */
+type MinecraftListInput = {
+    readonly channel?: MinecraftChannel;
+    readonly signal?: AbortSignal;
+};
+/** Inputs to {@link MinecraftVersionsApi.latest}. */
+type MinecraftLatestInput = {
+    readonly channel?: MinecraftChannel;
+    readonly signal?: AbortSignal;
+};
+/** Inputs to {@link MinecraftVersionsApi.get} / `.resolve`. */
+type MinecraftGetInput = {
+    readonly version: string;
+    readonly signal?: AbortSignal;
+};
+/** Public Minecraft versions API surface. */
+declare class MinecraftVersionsApi {
+    private readonly ctx;
+    constructor(ctx: ResolverContext);
+    /** List all Minecraft versions, optionally filtered by channel. */
+    list(input?: MinecraftListInput): Promise<readonly MinecraftVersionSummary[]>;
+    /** Return the latest version on the given channel (defaults to RELEASE). */
+    latest(input?: MinecraftLatestInput): Promise<MinecraftVersionSummary>;
+    /** Return a single version summary or throw `MANIFEST_NOT_FOUND`. */
+    get(input: MinecraftGetInput): Promise<MinecraftVersionSummary>;
+    /** Fetch and parse the per-version manifest in addition to the summary. */
+    resolve(input: MinecraftGetInput): Promise<ResolvedMinecraft>;
+    private fetchManifestRoot;
+}
+
+/** Inputs to {@link RuntimeVersionsApi.list}. */
+type RuntimeListInput = {
+    readonly system: RuntimeSystem;
+    readonly minecraftVersion?: string;
+    readonly signal?: AbortSignal;
+};
+/** A summary entry for the list API. */
+type RuntimeListEntry = {
+    readonly component: string;
+    readonly platformKey: string;
+    readonly versionName: string;
+    readonly released: string;
+    readonly manifestUrl: string;
+};
+/** Inputs to {@link RuntimeVersionsApi.resolve}. */
+type RuntimeResolveInput = {
+    readonly system: RuntimeSystem;
+    readonly minecraftVersion?: string;
+    readonly component?: string;
+    readonly preference?: RuntimePreferenceKind;
+    readonly signal?: AbortSignal;
+};
+/** Public runtime versions API surface. */
+declare class RuntimeVersionsApi {
+    private readonly ctx;
+    constructor(ctx: ResolverContext);
+    /** List available runtime entries for the host platform. */
+    list(input: RuntimeListInput): Promise<readonly RuntimeListEntry[]>;
+    /** Resolve a single runtime for the host platform and Minecraft version. */
+    resolve(input: RuntimeResolveInput): Promise<ResolvedRuntime>;
+    private fetchIndex;
+}
+/** Parse the leading integer from a runtime versionName (`"21.0.8"` → 21). */
+declare const parseMajorVersion: (versionName: string) => number | undefined;
+
+/** Inputs to {@link TargetsApi.resolve}. */
+type TargetResolveInput = {
+    readonly id: string;
+    readonly directory: string;
+    readonly minecraft: {
+        readonly version: string;
+    };
+    readonly loader: TargetLoaderInput;
+    readonly runtime?: {
+        readonly preference?: RuntimePreferenceKind;
+        /** Override the runtime component. Defaults to the Minecraft manifest's `javaVersion.component`. */
+        readonly component?: string;
+        /**
+         * Custom install root (absolute path) holding the component directories.
+         * When unset, runtime files live under `<directory>/runtime/`.
+         */
+        readonly installRoot?: string;
+    };
+    readonly system?: RuntimeSystem;
+    readonly signal?: AbortSignal;
+};
+/** Loader input variants. */
+type TargetLoaderInput = {
+    readonly type: typeof Loaders.VANILLA;
+} | {
+    readonly type: typeof Loaders.FABRIC;
+    readonly preference?: VersionPreferenceKind;
+    readonly version?: string;
+} | {
+    readonly type: typeof Loaders.FORGE;
+    readonly preference?: VersionPreferenceKind;
+    readonly version?: string;
 };
-/** Auth mode literal. */
-type AuthMode = (typeof AuthModes)[keyof typeof AuthModes];
-/** Offline authentication. */
-interface OfflineAuth {
-    readonly mode: typeof AuthModes.OFFLINE;
-    readonly username: string;
-    /** Optional explicit UUID. When omitted, a deterministic UUID is derived from the username. */
-    readonly uuid?: string;
-}
-/** Online (token-based) authentication. */
-interface OnlineAuth {
-    readonly mode: typeof AuthModes.ONLINE;
-    readonly username: string;
-    readonly uuid: string;
-    readonly accessToken: string;
-    readonly userType?: string;
-    readonly clientId?: string;
-    readonly xuid?: string;
+/** Inputs to {@link TargetsApi.list}. */
+type TargetListInput = {
+    readonly rootDir: string;
+};
+/** Constructor inputs for {@link TargetsApi}. */
+type TargetsApiContext = {
+    readonly minecraft: MinecraftVersionsApi;
+    readonly fabric: FabricVersionsApi;
+    readonly forge: ForgeVersionsApi;
+    readonly runtime: RuntimeVersionsApi;
+    readonly system: RuntimeSystem;
+};
+/** Public Targets API surface. */
+declare class TargetsApi {
+    private readonly ctx;
+    constructor(ctx: TargetsApiContext);
+    /** The detected host system used by `resolve()` when no `system` is supplied. */
+    get system(): RuntimeSystem;
+    /** Build a {@link Target} from already-resolved components. */
+    create(input: TargetCreateInput): Target;
+    /** Sugar API: resolve every component then assemble a target. */
+    resolve(input: TargetResolveInput): Promise<Target>;
+    /** Scan a root directory for Minecraft installations. Returns only what is on disk. */
+    list(input: TargetListInput): Promise<readonly DiscoveredTarget[]>;
 }
-/** Auth shape consumed by `kit.launch.compose`. */
-type LaunchAuth = OfflineAuth | OnlineAuth;
 
 /** Optional memory configuration. */
-interface LaunchMemoryOptions {
+type LaunchMemoryOptions = {
     readonly minMb?: number;
     readonly maxMb?: number;
-}
+};
 /** Optional resolution / window configuration. */
-interface LaunchResolutionOptions {
+type LaunchResolutionOptions = {
     readonly width: number;
     readonly height: number;
-}
+};
 /** Inputs for `kit.launch.compose` (and the lower-level `composeLaunch` helper). */
-interface LaunchOptions {
+type LaunchOptions = {
     readonly auth: LaunchAuth;
     readonly memory?: LaunchMemoryOptions;
     readonly resolution?: LaunchResolutionOptions;
@@ -1146,9 +1399,9 @@ interface LaunchOptions {
     readonly extraGameArgs?: readonly string[];
     /** Set of feature flags evaluated by argument rules (e.g. `is_demo_user`). */
     readonly features?: Readonly<Record<string, boolean>>;
-}
+};
 /** Fully composed launch command, ready to be passed to `kit.launch.run`. */
-interface LaunchComposition {
+type LaunchComposition = {
     readonly targetId: string;
     readonly directory: string;
     readonly javaPath: string;
@@ -1162,87 +1415,57 @@ interface LaunchComposition {
     readonly workingDirectory: string;
     /** Environment variables to set on the spawned process. */
     readonly env?: Readonly<Record<string, string>>;
-}
+};
 /** Live handle for a running game process. */
-interface LaunchSession {
+type LaunchSession = {
     /** Operating-system process id. */
     readonly pid: number;
     /** Resolves with the exit code/signal when the process terminates. */
     readonly exited: Promise<LaunchExit>;
     /** Best-effort cancel — sends SIGTERM, then SIGKILL after the grace period. */
     abort(reason?: string): void;
-}
+};
 /** Outcome of a finished launch. */
-interface LaunchExit {
+type LaunchExit = {
     readonly code: number | null;
     readonly signal: NodeJS.Signals | null;
     readonly aborted: boolean;
-}
+};
 /** Options for `kit.launch.run` (and the lower-level `runLaunch` helper). */
-interface LaunchRunOptions {
+type LaunchRunOptions = {
     readonly signal?: AbortSignal;
     readonly onEvent?: (event: ProgressEvent) => void;
     /** Milliseconds to wait between SIGTERM and SIGKILL when aborting. */
     readonly killGracePeriodMs?: number;
-}
-
-/** Stream-of-text channel exposed by spawned processes. */
-interface ProcessStream {
-    on(event: "data", listener: (chunk: string) => void): void;
-}
-/** Live handle for a child process. */
-interface SpawnedProcess {
-    readonly pid: number;
-    readonly stdout: ProcessStream;
-    readonly stderr: ProcessStream;
-    /** Resolves when the process exits with its exit info. */
-    readonly exited: Promise<{
-        readonly code: number | null;
-        readonly signal: NodeJS.Signals | null;
-    }>;
-    /** Send a termination signal. Returns true on success. */
-    kill(signal?: NodeJS.Signals): boolean;
-}
-/** Options accepted by the spawner. */
-interface SpawnOptions {
-    readonly cwd: string;
-    readonly env?: Readonly<Record<string, string>>;
-}
-/**
- * Pluggable process spawner. The default implementation uses `node:child_process`; tests
- * inject a fake to avoid spawning real processes.
- */
-interface Spawner {
-    spawn(command: string, args: readonly string[], options: SpawnOptions): SpawnedProcess;
-}
+};
 
 /** Update plan — additive list of actions to bring an installation up to date. */
-interface UpdatePlan {
+type UpdatePlan = {
     readonly targetId: string;
     readonly directory: string;
-    readonly target: Target;
+    readonly target: InstallPlanTarget;
     readonly actions: readonly InstallAction[];
     readonly totalBytes: number;
     readonly totalActions: number;
-}
+};
 /** Update report. */
-interface UpdateReport {
+type UpdateReport = {
     readonly targetId: string;
     readonly bytesDownloaded: number;
     readonly actionsCompleted: number;
     /** Actions that found their target already correct on disk and were skipped. */
     readonly actionsSkipped: number;
     readonly durationMs: number;
-}
+};
 
 /** Constructor options for {@link MinecraftKit}. */
-interface MinecraftKitOptions {
+type MinecraftKitOptions = {
     readonly httpClient?: HttpClient;
     readonly cache?: MetadataCache;
     readonly logger?: Logger;
     readonly system?: RuntimeSystem;
     readonly spawner?: Spawner;
-}
+};
 /**
  * Single facade for the entire library.
  *
@@ -1264,11 +1487,11 @@ declare class MinecraftKit {
     readonly targets: TargetsApi;
     readonly install: {
         plan(target: Target, options?: OperationOptions): Promise<InstallPlan>;
-        run(plan: InstallPlan, options?: OperationOptions): Promise<InstallReport>;
+        run(plan: InstallPlan, options?: InstallRunOptions): Promise<InstallReport>;
         /** Install only the Java runtime declared by `target.runtime` (honours `installRoot`). */
         readonly runtime: {
             plan(target: Target, options?: OperationOptions): Promise<InstallPlan>;
-            run(plan: InstallPlan, options?: OperationOptions): Promise<InstallReport>;
+            run(plan: InstallPlan, options?: InstallRunOptions): Promise<InstallReport>;
             /**
              * Plan a runtime-only install without an existing Minecraft Target. The caller
              * supplies a {@link ResolvedRuntime} (typically from `kit.versions.runtime.resolve`)
@@ -1308,120 +1531,246 @@ declare class MinecraftKit {
         readonly forge: RepairAspect;
         /** Repair the Java runtime files. Honours `target.runtime.installRoot`. */
         readonly runtime: RepairAspect;
+        /** Verify every applicable aspect (Minecraft + Runtime + active loader) and repair each broken one. */
+        all(target: Target, options?: OperationOptions): Promise<RepairAllReport>;
     };
     readonly launch: {
         compose(target: Target, options: LaunchOptions): Promise<LaunchComposition>;
         run(composition: LaunchComposition, options?: LaunchRunOptions): LaunchSession;
     };
+    /**
+     * Microsoft / Mojang authentication. Implements the device-code flow against Microsoft
+     * Entra, exchanges the resulting tokens for an XSTS + Minecraft session, and returns
+     * everything needed to compose an `OnlineAuth` for `launch.compose`.
+     */
+    readonly auth: MojangAuthApi;
     /** Cache surface useful for advanced consumers (e.g. clearing between operations). */
     readonly cache: MetadataCache;
     constructor(options?: MinecraftKitOptions);
 }
+/** Options accepted by `install.run` (and `install.runtime.run`). */
+interface InstallRunOptions extends OperationOptions {
+    readonly pauseController?: PauseController;
+    readonly actionCategories?: ReadonlySet<DownloadAction["category"]>;
+}
 /** Options accepted by every `verify.<kind>.run`. */
-interface VerifyOperationOptions {
+type VerifyOperationOptions = {
     readonly signal?: AbortSignal;
     readonly onEvent?: ProgressListener;
-}
+};
 /** Options for any `repair.<aspect>.plan` call. Accepts one or many verification results. */
-interface RepairPlanOptions {
+type RepairPlanOptions = {
     readonly from: VerificationResult | readonly VerificationResult[];
     readonly signal?: AbortSignal;
-}
+};
 /** Shared shape of every aspect-specific repair surface (`repair.minecraft`, `.fabric`, …). */
-interface RepairAspect {
+type RepairAspect = {
     plan(target: Target, options: RepairPlanOptions): Promise<RepairPlan>;
     run(plan: RepairPlan, options?: OperationOptions): Promise<RepairReport>;
-}
+};
 
-/** Inputs to {@link createMemoryCache}. */
-interface MemoryCacheOptions {
-    readonly maxEntries?: number;
-    readonly ttlMs?: number;
-}
-/** In-memory metadata cache backed by `lru-cache`. */
-declare function createMemoryCache(options?: MemoryCacheOptions): MetadataCache;
+/**
+ * Stable error code registry. `MinecraftKitError` carries one of these as `code`; consumers
+ * can switch on it exhaustively via the derived {@link MinecraftKitErrorCode} union.
+ *
+ * Codes are stable across releases — adding new codes is non-breaking; removing or renaming
+ * a code is a breaking change.
+ */
+declare const MinecraftKitErrorCodes: {
+    readonly NETWORK_TIMEOUT: "NETWORK_TIMEOUT";
+    readonly NETWORK_HTTP_ERROR: "NETWORK_HTTP_ERROR";
+    readonly NETWORK_ABORTED: "NETWORK_ABORTED";
+    readonly INTEGRITY_HASH_MISMATCH: "INTEGRITY_HASH_MISMATCH";
+    readonly INTEGRITY_SIZE_MISMATCH: "INTEGRITY_SIZE_MISMATCH";
+    readonly MANIFEST_INVALID: "MANIFEST_INVALID";
+    readonly MANIFEST_NOT_FOUND: "MANIFEST_NOT_FOUND";
+    readonly METADATA_PARSE_ERROR: "METADATA_PARSE_ERROR";
+    readonly FILESYSTEM_PATH_TRAVERSAL: "FILESYSTEM_PATH_TRAVERSAL";
+    readonly FILESYSTEM_WRITE_ERROR: "FILESYSTEM_WRITE_ERROR";
+    readonly FILESYSTEM_READ_ERROR: "FILESYSTEM_READ_ERROR";
+    readonly ARCHIVE_INVALID: "ARCHIVE_INVALID";
+    readonly ARCHIVE_TOO_LARGE: "ARCHIVE_TOO_LARGE";
+    readonly ARCHIVE_ENTRY_REJECTED: "ARCHIVE_ENTRY_REJECTED";
+    readonly RUNTIME_NOT_FOUND: "RUNTIME_NOT_FOUND";
+    readonly RUNTIME_UNSUPPORTED_PLATFORM: "RUNTIME_UNSUPPORTED_PLATFORM";
+    readonly FORGE_PROCESSOR_FAILED: "FORGE_PROCESSOR_FAILED";
+    readonly FORGE_INSTALLER_INVALID: "FORGE_INSTALLER_INVALID";
+    readonly LAUNCH_JAVA_NOT_FOUND: "LAUNCH_JAVA_NOT_FOUND";
+    readonly LAUNCH_PROCESS_FAILED: "LAUNCH_PROCESS_FAILED";
+    readonly LAUNCH_ABORTED: "LAUNCH_ABORTED";
+    readonly VERIFICATION_FAILED: "VERIFICATION_FAILED";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly NOT_IMPLEMENTED: "NOT_IMPLEMENTED";
+    readonly UNSUPPORTED_VERSION: "UNSUPPORTED_VERSION";
+    readonly LZMA_DECODE_ERROR: "LZMA_DECODE_ERROR";
+    readonly AUTH_DEVICE_CODE_EXPIRED: "AUTH_DEVICE_CODE_EXPIRED";
+    readonly AUTH_DEVICE_CODE_DECLINED: "AUTH_DEVICE_CODE_DECLINED";
+    readonly AUTH_DEVICE_CODE_FAILED: "AUTH_DEVICE_CODE_FAILED";
+    readonly AUTH_REFRESH_FAILED: "AUTH_REFRESH_FAILED";
+    readonly AUTH_XBOX_FAILED: "AUTH_XBOX_FAILED";
+    readonly AUTH_XSTS_FAILED: "AUTH_XSTS_FAILED";
+    readonly AUTH_MINECRAFT_FAILED: "AUTH_MINECRAFT_FAILED";
+    readonly AUTH_NO_GAME_OWNERSHIP: "AUTH_NO_GAME_OWNERSHIP";
+    readonly AUTH_MISSING_CLIENT_ID: "AUTH_MISSING_CLIENT_ID";
+    readonly AUTH_CANCELLED: "AUTH_CANCELLED";
+};
+/** Union of all kit error codes. */
+type MinecraftKitErrorCode = (typeof MinecraftKitErrorCodes)[keyof typeof MinecraftKitErrorCodes];
+/** Structured context attached to errors. */
+type MinecraftKitErrorContext = {
+    readonly url?: string;
+    readonly filePath?: string;
+    readonly expectedHash?: string;
+    readonly actualHash?: string;
+    readonly expectedSize?: number;
+    readonly actualSize?: number;
+    readonly httpStatus?: number;
+    readonly exitCode?: number;
+    readonly platform?: string;
+    readonly version?: string;
+    readonly [key: string]: unknown;
+};
 
-/** Inputs allowing the host system to be derived from current Node values or overrides. */
-interface DetectSystemInput {
-    readonly platform?: NodeJS.Platform;
-    readonly arch?: NodeJS.Architecture;
-    readonly osVersion?: string;
+/**
+ * The single error class thrown by every public API in `@loontail/minecraft-kit`.
+ *
+ * Use {@link isMinecraftKitError} or {@link isErrorCode} for type-narrowing in `catch` blocks.
+ */
+declare class MinecraftKitError extends Error {
+    readonly name = "MinecraftKitError";
+    /** Stable discriminator. */
+    readonly code: MinecraftKitErrorCode;
+    /** Structured context; safe to serialize. */
+    readonly context: Readonly<MinecraftKitErrorContext>;
+    constructor(code: MinecraftKitErrorCode, message: string, options?: {
+        cause?: unknown;
+        context?: MinecraftKitErrorContext;
+    });
+    /** JSON-friendly representation. */
+    toJSON(): Record<string, unknown>;
 }
+/** True when `e` is an {@link MinecraftKitError}. */
+declare const isMinecraftKitError: (e: unknown) => e is MinecraftKitError;
+/** True when `e` is an {@link MinecraftKitError} carrying the given code. */
+declare const isErrorCode: <C extends MinecraftKitErrorCode>(e: unknown, code: C) => e is MinecraftKitError & {
+    code: C;
+};
+
 /**
- * Resolve the current host system identifiers.
+ * Exhaustiveness sentinel for discriminated unions. Drop into the `default` of a switch on
+ * `kind` / `type` / `status` so the compiler errors when a new variant is added but the
+ * switch is not updated.
  *
- * @throws {@link MinecraftKitError} with code `RUNTIME_UNSUPPORTED_PLATFORM` when the
- * platform/arch combination is not understood.
+ * ```ts
+ * switch (action.kind) {
+ *   case "download-file": return ...;
+ *   case "write-version-json": return ...;
+ *   default: return assertNever(action);
+ * }
+ * ```
  */
-declare function detectSystem(input?: DetectSystemInput): RuntimeSystem;
+declare const assertNever: (value: never) => never;
+
+/** UI-oriented coarse progress stages, identical across install and repair flows. */
+declare const InstallStages: {
+    readonly PREPARE: "prepare";
+    readonly RUNTIME: "runtime";
+    readonly MINECRAFT: "minecraft";
+    readonly LOADER: "loader";
+    readonly FINALIZE: "finalize";
+};
+type InstallStage = (typeof InstallStages)[keyof typeof InstallStages];
+type ProgressSnapshot = {
+    readonly stage: InstallStage;
+    readonly stagePercent: number;
+    readonly overallPercent: number;
+    readonly bytesDownloaded: number;
+    readonly totalBytes: number;
+    readonly currentFile?: string;
+};
+type ProgressTrackerOptions = {
+    /** Milliseconds between snapshot pushes. Defaults to 100ms. */
+    readonly throttleMs?: number;
+};
+type InstallProgressTracker = {
+    /** Pass directly as the `onEvent` callback to `install.run` / `repair.run`. */
+    readonly onEvent: ProgressListener;
+    snapshot(): ProgressSnapshot;
+    /** First push fires immediately with the initial snapshot. */
+    subscribe(listener: (snapshot: ProgressSnapshot) => void): () => void;
+    /** Force-emit a final 100% snapshot and stop the throttle timer. */
+    finish(): void;
+};
+/** Aggregate `ProgressEvent`s from one install/repair run into throttled UI snapshots. */
+declare const createInstallProgressTracker: (plan: Pick<InstallPlan, "actions">, options?: ProgressTrackerOptions) => InstallProgressTracker;
 
 /** Inputs to {@link verifyMinecraft}. */
-interface VerifyMinecraftInput {
+type VerifyMinecraftInput = {
     readonly target: Target;
     readonly http: HttpClient;
     readonly cache: MetadataCache;
     readonly signal?: AbortSignal;
     readonly onEvent?: ProgressListener;
-}
+};
 /**
  * Verify the vanilla Minecraft slice of an installation: the client jar, version JSON,
  * libraries (incl. native jars), assets (index + objects), logging config, and the
  * extracted natives directory.
  */
-declare function verifyMinecraft(input: VerifyMinecraftInput): Promise<VerificationResult>;
+declare const verifyMinecraft: (input: VerifyMinecraftInput) => Promise<VerificationResult>;
 
 /** Inputs to {@link verifyFabric}. */
-interface VerifyFabricInput {
+type VerifyFabricInput = {
     readonly target: Target;
     readonly http: HttpClient;
     readonly cache: MetadataCache;
     readonly signal?: AbortSignal;
     readonly onEvent?: ProgressListener;
-}
+};
 /** Verify the Fabric loader slice: profile JSON + every library it pulls in. */
-declare function verifyFabric(input: VerifyFabricInput): Promise<VerificationResult>;
+declare const verifyFabric: (input: VerifyFabricInput) => Promise<VerificationResult>;
 
 /** Inputs to {@link verifyForge}. */
-interface VerifyForgeInput {
+type VerifyForgeInput = {
     readonly target: Target;
     readonly http: HttpClient;
     readonly cache: MetadataCache;
     readonly signal?: AbortSignal;
     readonly onEvent?: ProgressListener;
-}
+};
 /**
  * Verify the Forge loader slice: the on-disk Forge version JSON and every library it
  * declares. Libraries can only be enumerated once the JSON is present *and parsable*; a
  * malformed JSON is surfaced as a CORRUPT issue so repair rewrites it before re-running.
  */
-declare function verifyForge(input: VerifyForgeInput): Promise<VerificationResult>;
+declare const verifyForge: (input: VerifyForgeInput) => Promise<VerificationResult>;
 
 /** Inputs to {@link verifyRuntime}. */
-interface VerifyRuntimeInput {
+type VerifyRuntimeInput = {
     readonly target: Target;
     readonly http: HttpClient;
     readonly cache: MetadataCache;
     readonly signal?: AbortSignal;
     readonly onEvent?: ProgressListener;
-}
+};
 /**
  * Verify the Java runtime files. Honours `target.runtime.installRoot` when set so a
  * shared/global runtime install is checked at its real location instead of the per-target
  * `runtime/` subfolder.
  */
-declare function verifyRuntime(input: VerifyRuntimeInput): Promise<VerificationResult>;
+declare const verifyRuntime: (input: VerifyRuntimeInput) => Promise<VerificationResult>;
 
 /** Inputs to {@link runRepair}. Shared across all aspect-specific repair flows. */
-interface RunRepairInput {
+type RunRepairInput = {
     readonly plan: RepairPlan;
     readonly http: HttpClient;
     readonly cache: MetadataCache;
     readonly spawner: Spawner;
     readonly signal?: AbortSignal;
     readonly onEvent?: ProgressListener;
-}
+};
 /** Execute any repair plan. Reuses the install runner. */
-declare function runRepair(input: RunRepairInput): Promise<RepairReport>;
+declare const runRepair: (input: RunRepairInput) => Promise<RepairReport>;
 
 /** Inputs to {@link planMinecraftRepair}. */
 type PlanMinecraftRepairInput = AspectRepairInput;
@@ -1429,12 +1778,12 @@ type PlanMinecraftRepairInput = AspectRepairInput;
  * Build a repair plan covering only the vanilla Minecraft slice: client jar, version JSON,
  * libraries (incl. native jars), assets, logging config, and native extractions.
  */
-declare function planMinecraftRepair(input: PlanMinecraftRepairInput): Promise<RepairPlan>;
+declare const planMinecraftRepair: (input: PlanMinecraftRepairInput) => Promise<RepairPlan>;
 
 /** Inputs to {@link planFabricRepair}. */
 type PlanFabricRepairInput = AspectRepairInput;
 /** Build a repair plan covering the Fabric loader slice: profile JSON + libraries. */
-declare function planFabricRepair(input: PlanFabricRepairInput): Promise<RepairPlan>;
+declare const planFabricRepair: (input: PlanFabricRepairInput) => Promise<RepairPlan>;
 
 /** Inputs to {@link planForgeRepair}. */
 type PlanForgeRepairInput = AspectRepairInput;
@@ -1444,7 +1793,7 @@ type PlanForgeRepairInput = AspectRepairInput;
  * version JSON was missing during verify (so libraries couldn't be enumerated), every
  * forge-library download is added defensively — `downloadFile` skips files already on disk.
  */
-declare function planForgeRepair(input: PlanForgeRepairInput): Promise<RepairPlan>;
+declare const planForgeRepair: (input: PlanForgeRepairInput) => Promise<RepairPlan>;
 
 /** Inputs to {@link planRuntimeRepair}. */
 type PlanRuntimeRepairInput = AspectRepairInput;
@@ -1453,64 +1802,44 @@ type PlanRuntimeRepairInput = AspectRepairInput;
  * honoured automatically because both `planInstall` and the verify side resolve runtime
  * paths through the same `targetPaths.runtimeRoot(..., installRoot)` helper.
  */
-declare function planRuntimeRepair(input: PlanRuntimeRepairInput): Promise<RepairPlan>;
+declare const planRuntimeRepair: (input: PlanRuntimeRepairInput) => Promise<RepairPlan>;
 
+/** Result of resolving the on-disk version JSON for a target. */
+type ResolvedLaunchVersion = {
+    /** Topmost version id (the one used as `${version_name}` and for the natives directory). */
+    readonly versionId: string;
+    /** Merged manifest with `inheritsFrom` chain folded together. */
+    readonly merged: MinecraftVersionManifest;
+    /** Inherits-from chain from top (`versionId`) down to the root vanilla version. */
+    readonly chain: readonly string[];
+};
+/** Read the installed version JSON appropriate for a target's loader and merge inheritsFrom. */
+declare const resolveLaunchVersion: (target: Target) => Promise<ResolvedLaunchVersion>;
 /**
- * Stable error code discriminator. Consumers can `switch (e.code)` exhaustively.
+ * Pick the version id whose `versions/<id>/<id>.jar` should land on the launch classpath.
+ * Walks the inherits-from chain from top to root and returns the first id whose jar exists
+ * on disk. Falls back to the root id when nothing is materialised yet.
  *
- * Codes are stable across releases — adding new codes is non-breaking; removing or renaming
- * a code is a breaking change.
+ * Why: Fabric's profile id is `fabric-loader-0.14.21-1.20.1`, but Fabric does not produce a
+ * matching `.jar`; the loader expects the **vanilla** client jar on the classpath and hooks
+ * it via `KnotClient`. Modern Forge similarly leaves `versions/<forge-id>/<forge-id>.jar`
+ * absent and routes the patched client jar through `libraries/`. Walking the chain picks
+ * the right id for both shapes without special-casing.
  */
-type MinecraftKitErrorCode = "NETWORK_TIMEOUT" | "NETWORK_HTTP_ERROR" | "NETWORK_ABORTED" | "INTEGRITY_HASH_MISMATCH" | "INTEGRITY_SIZE_MISMATCH" | "MANIFEST_INVALID" | "MANIFEST_NOT_FOUND" | "METADATA_PARSE_ERROR" | "FILESYSTEM_PATH_TRAVERSAL" | "FILESYSTEM_WRITE_ERROR" | "FILESYSTEM_READ_ERROR" | "ARCHIVE_INVALID" | "ARCHIVE_TOO_LARGE" | "ARCHIVE_ENTRY_REJECTED" | "RUNTIME_NOT_FOUND" | "RUNTIME_UNSUPPORTED_PLATFORM" | "FORGE_PROCESSOR_FAILED" | "FORGE_INSTALLER_INVALID" | "LAUNCH_JAVA_NOT_FOUND" | "LAUNCH_PROCESS_FAILED" | "LAUNCH_ABORTED" | "VERIFICATION_FAILED" | "INVALID_INPUT" | "NOT_IMPLEMENTED" | "UNSUPPORTED_VERSION" | "LZMA_DECODE_ERROR";
-/** Structured context attached to errors. */
-interface MinecraftKitErrorContext {
-    readonly url?: string;
-    readonly filePath?: string;
-    readonly expectedHash?: string;
-    readonly actualHash?: string;
-    readonly expectedSize?: number;
-    readonly actualSize?: number;
-    readonly httpStatus?: number;
-    readonly exitCode?: number;
-    readonly platform?: string;
-    readonly version?: string;
-    readonly [key: string]: unknown;
-}
+declare const pickClientJarVersionId: (directory: string, chain: readonly string[]) => Promise<string>;
 
-/**
- * The single error class thrown by every public API in `@loontail/minecraft-kit`.
- *
- * Use {@link isMinecraftKitError} or {@link isErrorCode} for type-narrowing in `catch` blocks.
- */
-declare class MinecraftKitError extends Error {
-    readonly name = "MinecraftKitError";
-    /** Stable discriminator. */
-    readonly code: MinecraftKitErrorCode;
-    /** Structured context; safe to serialize. */
-    readonly context: Readonly<MinecraftKitErrorContext>;
-    constructor(code: MinecraftKitErrorCode, message: string, options?: {
-        cause?: unknown;
-        context?: MinecraftKitErrorContext;
-    });
-    /** JSON-friendly representation. */
-    toJSON(): Record<string, unknown>;
+/** Default spawner backed by `node:child_process.spawn`. */
+declare class ChildProcessSpawner implements Spawner {
+    spawn(command: string, args: readonly string[], options: SpawnOptions): SpawnedProcess;
 }
-/** True when `e` is an {@link MinecraftKitError}. */
-declare function isMinecraftKitError(e: unknown): e is MinecraftKitError;
-/** True when `e` is an {@link MinecraftKitError} carrying the given code. */
-declare function isErrorCode<C extends MinecraftKitErrorCode>(e: unknown, code: C): e is MinecraftKitError & {
-    code: C;
-};
 
-/**
- * Derive a stable v3-style UUID for an offline player username.
- *
- * Mojang's offline-mode formula: `MD5("OfflinePlayer:" + name)` with the version/variant
- * bits patched to UUID v3.
- */
-declare function offlineUuidFor(username: string): string;
-/** Strip the dashes from a UUID. Used by `${auth_uuid}`. */
-declare function stripUuidDashes(uuid: string): string;
+/** Inputs to {@link createMemoryCache}. */
+type MemoryCacheOptions = {
+    readonly maxEntries?: number;
+    readonly ttlMs?: number;
+};
+/** In-memory metadata cache backed by `lru-cache`. */
+declare const createMemoryCache: (options?: MemoryCacheOptions) => MetadataCache;
 
 /**
  * Default {@link HttpClient} implementation backed by Node's built-in `fetch` (undici under
@@ -1520,15 +1849,68 @@ declare class FetchHttpClient implements HttpClient {
     request(url: string, options?: HttpRequestOptions): Promise<HttpResponse>;
 }
 
-/** Default spawner backed by `node:child_process.spawn`. */
-declare class ChildProcessSpawner implements Spawner {
-    spawn(command: string, args: readonly string[], options: SpawnOptions): SpawnedProcess;
-}
-
 /** Logger that drops every message. Default when no logger is supplied. */
 declare const silentLogger: Logger;
 /** Logger that mirrors messages to `console.<level>` with structured fields. */
 declare const consoleLogger: Logger;
+/**
+ * Wrap a {@link Logger} so every message is prefixed with `[scope]`. Mirrors the
+ * `scopedLogger(scope)` convention used by the launcher: each module reaches for one named
+ * logger at the top of the file (e.g. `const log = scopedLogger(input.logger, "http")`)
+ * instead of threading the scope through every callsite.
+ *
+ * The merged `fields` argument lets a scope attach default context (e.g. a request id) without
+ * the call site repeating it on every message.
+ */
+declare const scopedLogger: (base: Logger, scope: string, baseFields?: Readonly<Record<string, unknown>>) => Logger;
+
+/** Inputs allowing the host system to be derived from current Node values or overrides. */
+type DetectSystemInput = {
+    readonly platform?: NodeJS.Platform;
+    readonly arch?: NodeJS.Architecture;
+    readonly osVersion?: string;
+};
+/**
+ * Resolve the current host system identifiers.
+ *
+ * @throws {@link MinecraftKitError} with code `RUNTIME_UNSUPPORTED_PLATFORM` when the
+ * platform/arch combination is not understood.
+ */
+declare const detectSystem: (input?: DetectSystemInput) => RuntimeSystem;
+
+/**
+ * Derive a stable v3-style UUID for an offline player username.
+ *
+ * Mojang's offline-mode formula: `MD5("OfflinePlayer:" + name)` with the version/variant
+ * bits patched to UUID v3.
+ */
+declare const offlineUuidFor: (username: string) => string;
+/** Strip the dashes from a UUID. Used by `${auth_uuid}`. */
+declare const stripUuidDashes: (uuid: string) => string;
+
+/** Helpers for the per-target directory layout. */
+declare const targetPaths: {
+    readonly versionsDir: (root: string) => string;
+    readonly versionDir: (root: string, versionId: string) => string;
+    readonly versionJar: (root: string, versionId: string) => string;
+    readonly versionJson: (root: string, versionId: string) => string;
+    readonly librariesDir: (root: string) => string;
+    readonly libraryFile: (root: string, libraryPath: string) => string;
+    readonly assetIndex: (root: string, indexId: string) => string;
+    readonly assetObject: (root: string, hash: string) => string;
+    readonly assetVirtual: (root: string, virtualPath: string) => string;
+    readonly assetLegacy: (root: string, virtualPath: string) => string;
+    readonly assetResource: (root: string, virtualPath: string) => string;
+    readonly loggingConfig: (root: string, id: string) => string;
+    readonly nativesDir: (root: string, versionId: string) => string;
+    /**
+     * Path to a runtime component's root directory. Honours `installRoot` (custom global
+     * runtime location) when present; otherwise falls back to `<directory>/runtime/<component>`.
+     */
+    readonly runtimeRoot: (directory: string, component: string, installRoot?: string) => string;
+    readonly runtimeJavaExecutable: (directory: string, component: string, os: OperatingSystem, installRoot?: string) => string;
+    readonly forgeInstaller: (root: string, mavenVersion: string) => string;
+};
 
 /**
  * Endpoint builders for every external HTTP request the library makes. Code MUST go through
@@ -1711,4 +2093,4 @@ declare const RUNTIME_PLATFORM_KEYS: Readonly<Record<OperatingSystem, Readonly<R
  */
 declare const FALLBACK_COMPONENT: string;
 
-export { ASSETS_DIR, ASSETS_INDEXES_DIR, ASSETS_LEGACY_DIR, ASSETS_LOG_CONFIGS_DIR, ASSETS_OBJECTS_DIR, ASSETS_RESOURCES_DIR, ASSETS_VIRTUAL_DIR, ApiEndpoints, type ApiEndpointsShape, type Architecture, Architectures, type ArgumentEntry, type ArtifactDownload, type AspectRepairInput, type AssetIndexDocument, type AssetIndexReference, type AssetObject, type AuthMode, AuthModes, BASE_JVM_ARGS, CACHE_MAX_ENTRIES, CACHE_TTL_MS, ChildProcessSpawner, DEFAULT_KILL_GRACE_MS, DEFAULT_LAUNCHER_NAME, DEFAULT_LAUNCHER_VERSION, DEFAULT_LIBRARY_REPOSITORY, DEFAULT_MAX_MB, DEFAULT_MIN_MB, DOWNLOAD_CONCURRENCY, type DetectSystemInput, type DiscoveredLoaderHint, type DiscoveredRuntimeHint, type DiscoveredTarget, type DownloadAction, EXTRACTION_MAX_COMPRESSION_RATIO, EXTRACTION_MAX_ENTRY_COUNT, EXTRACTION_MAX_FILE_SIZE, EXTRACTION_MAX_TOTAL_SIZE, type EventType, EventTypes, type ExtractNativeAction, FABRIC_MAVEN_BASE, FALLBACK_COMPONENT, FORGE_INSTALLERS_DIR, FORGE_INSTALLER_MAX_SIZE, FORGE_MAVEN_BASE, type FabricCompatibilityEntry, type FabricListInput, type FabricLoaderSummary, type FabricProfile, type FabricResolveInput, FabricVersionsApi, FetchHttpClient, type FileRef, type ForgeBuildSummary, type ForgeInstallProfile, type ForgeListInput, type ForgeProcessor, type ForgeProfileData, type ForgeResolveInput, type ForgeVersionJson, ForgeVersionsApi, HTTP_RETRY_BACKOFF_BASE_MS, HTTP_RETRY_BACKOFF_CAP_MS, HTTP_RETRY_MAX, HTTP_TIMEOUT_MS, type HttpClient, type HttpHeaders, type HttpRequestOptions, type HttpResponse, type InstallAction, type InstallActionKind, InstallActionKinds, type InstallPhase, InstallPhases, type InstallPlan, type InstallReport, JAVA_EXECUTABLE, LAUNCH_PLACEHOLDERS, LEGACY_JVM_ARGS, LIBRARIES_DIR, type LaunchAuth, type LaunchComposition, type LaunchExit, type LaunchMemoryOptions, type LaunchOptions, type LaunchPlaceholder, type LaunchResolutionOptions, type LaunchRunOptions, type LaunchSession, type LibraryArtifact, type LibraryRule, type Loader, type LoaderKind, Loaders, type LogLevel, LogLevels, type Logger, MACOS_JVM_ARGS, MAC_RUNTIME_PREFIX, MAX_PROCESSOR_STDERR_LINES, type MemoryCacheOptions, type MetadataCache, type MinecraftArguments, type MinecraftChannel, MinecraftChannels, type MinecraftDownloads, type MinecraftGetInput, type MinecraftJavaVersion, MinecraftKit, MinecraftKitError, type MinecraftKitErrorCode, type MinecraftKitErrorContext, type MinecraftKitOptions, type MinecraftLatestInput, type MinecraftLibrary, type MinecraftLibraryDownloads, type MinecraftListInput, type MinecraftLogging, type MinecraftVersionManifest, type MinecraftVersionSummary, MinecraftVersionsApi, NATIVES_DIR_NAME, NODE_ARCH_TO_MOJANG_ARCH, NODE_PLATFORM_TO_MOJANG_OS, type OfflineAuth, type OnlineAuth, type OperatingSystem, OperatingSystems, type OperationOptions, PROGRESS_EVENT_INTERVAL_MS, type PlanFabricRepairInput, type PlanForgeRepairInput, type PlanMinecraftRepairInput, type PlanRuntimeInstallInput, type PlanRuntimeRepairInput, type PlanStandaloneRuntimeInstallInput, type ProcessStream, type ProcessorRef, type ProgressEvent, type ProgressListener, RUNTIMES_DIR, RUNTIME_PLATFORM_KEYS, type RepairAspect, type RepairPhase, RepairPhases, type RepairPlan, type RepairPlanOptions, type RepairReport, type ResolvedFabricLoader, type ResolvedForgeLoader, type ResolvedMinecraft, type ResolvedRuntime, type ResolvedVanillaLoader, type ResolverContext, type RunForgeProcessorAction, type RunRepairInput, type RuntimeComponent, RuntimeComponents, type RuntimeFileDirectory, type RuntimeFileEntry, type RuntimeFileFile, type RuntimeFileLink, type RuntimeFilesManifest, type RuntimeIndex, type RuntimeIndexEntry, type RuntimeIndexPlatform, type RuntimeListEntry, type RuntimeListInput, RuntimePreference, type RuntimePreferenceKind, type RuntimeResolveInput, type RuntimeSystem, RuntimeVersionsApi, SPAWNER_MAX_LINE_BYTES, type SpawnOptions, type SpawnedProcess, type Spawner, type Target, type TargetCreateInput, type TargetListInput, type TargetLoaderInput, type TargetResolveInput, TargetsApi, type TargetsApiContext, USER_AGENT, type UpdatePlan, type UpdateReport, VERSIONS_DIR, type VerificationFileResult, type VerificationKind, VerificationKinds, type VerificationResult, type VerifyFabricInput, VerifyFileCategories, type VerifyFileCategory, type VerifyFileStatus, VerifyFileStatuses, type VerifyForgeInput, type VerifyMinecraftInput, type VerifyOperationOptions, type VerifyRuntimeInput, VersionPreference, type VersionPreferenceKind, type WriteLoggingConfigAction, type WriteVersionJsonAction, consoleLogger, createMemoryCache, detectSystem, isErrorCode, isMinecraftKitError, offlineUuidFor, planFabricRepair, planForgeRepair, planMinecraftRepair, planRuntimeInstall, planRuntimeRepair, planStandaloneRuntimeInstall, runRepair, silentLogger, stripUuidDashes, verifyFabric, verifyForge, verifyMinecraft, verifyRuntime };
+export { ASSETS_DIR, ASSETS_INDEXES_DIR, ASSETS_LEGACY_DIR, ASSETS_LOG_CONFIGS_DIR, ASSETS_OBJECTS_DIR, ASSETS_RESOURCES_DIR, ASSETS_VIRTUAL_DIR, ApiEndpoints, type ApiEndpointsShape, type Architecture, Architectures, type ArgumentEntry, type ArtifactDownload, type AspectRepairInput, type AssetIndexDocument, type AssetIndexReference, type AssetObject, type AuthMode, AuthModes, BASE_JVM_ARGS, CACHE_MAX_ENTRIES, CACHE_TTL_MS, CLIENT_ID_ENV_VAR, ChildProcessSpawner, DEFAULT_KILL_GRACE_MS, DEFAULT_LAUNCHER_NAME, DEFAULT_LAUNCHER_VERSION, DEFAULT_LIBRARY_REPOSITORY, DEFAULT_MAX_MB, DEFAULT_MIN_MB, DOWNLOAD_CONCURRENCY, type DetectSystemInput, type DeviceCodePrompt, type DeviceCodeState, type DiscoveredLoaderHint, type DiscoveredRuntimeHint, type DiscoveredTarget, type DownloadAction, DownloadCategories, type DownloadCategory, EXTRACTION_MAX_COMPRESSION_RATIO, EXTRACTION_MAX_ENTRY_COUNT, EXTRACTION_MAX_FILE_SIZE, EXTRACTION_MAX_TOTAL_SIZE, type EventType, EventTypes, type ExtractNativeAction, FABRIC_MAVEN_BASE, FALLBACK_COMPONENT, FORGE_INSTALLERS_DIR, FORGE_INSTALLER_MAX_SIZE, FORGE_MAVEN_BASE, type FabricCompatibilityEntry, type FabricListInput, type FabricLoaderSummary, type FabricProfile, type FabricResolveInput, FabricVersionsApi, FetchHttpClient, type FileRef, type ForgeBuildSummary, type ForgeInstallProfile, type ForgeListInput, type ForgeProcessor, type ForgeProfileData, type ForgeResolveInput, type ForgeVersionJson, ForgeVersionsApi, HTTP_RETRY_BACKOFF_BASE_MS, HTTP_RETRY_BACKOFF_CAP_MS, HTTP_RETRY_MAX, HTTP_TIMEOUT_MS, type HttpClient, type HttpHeaders, type HttpMethod, type HttpRequestBody, type HttpRequestOptions, type HttpResponse, type InstallAction, type InstallActionKind, InstallActionKinds, type InstallPhase, InstallPhases, type InstallPlan, type InstallPlanTarget, type InstallProgressTracker, type InstallReport, type InstallRunOptions, type InstallStage, InstallStages, JAVA_EXECUTABLE, LAUNCH_PLACEHOLDERS, LEGACY_JVM_ARGS, LIBRARIES_DIR, type LaunchAuth, type LaunchComposition, type LaunchExit, type LaunchMemoryOptions, type LaunchOptions, type LaunchPlaceholder, type LaunchResolutionOptions, type LaunchRunOptions, type LaunchSession, type LibraryArtifact, type LibraryRule, type Loader, type LoaderKind, Loaders, type LogLevel, LogLevels, type Logger, type LoginOptions, MACOS_JVM_ARGS, MAC_RUNTIME_PREFIX, MAX_PROCESSOR_STDERR_LINES, type MemoryCacheOptions, type MetadataCache, type MinecraftArguments, type MinecraftChannel, MinecraftChannels, type MinecraftDownloads, type MinecraftGetInput, type MinecraftJavaVersion, MinecraftKit, MinecraftKitError, type MinecraftKitErrorCode, MinecraftKitErrorCodes, type MinecraftKitErrorContext, type MinecraftKitOptions, type MinecraftLatestInput, type MinecraftLibrary, type MinecraftLibraryDownloads, type MinecraftListInput, type MinecraftLogging, type MinecraftVersionManifest, type MinecraftVersionSummary, MinecraftVersionsApi, MojangAuthApi, type MojangSession, NATIVES_DIR_NAME, NODE_ARCH_TO_MOJANG_ARCH, NODE_PLATFORM_TO_MOJANG_OS, type OfflineAuth, type OnlineAuth, type OperatingSystem, OperatingSystems, type OperationOptions, PROGRESS_EVENT_INTERVAL_MS, PauseController, type PlanFabricRepairInput, type PlanForgeRepairInput, type PlanMinecraftRepairInput, type PlanRuntimeInstallInput, type PlanRuntimeRepairInput, type PlanStandaloneRuntimeInstallInput, type PollDeviceCodeOptions, type ProcessStream, type ProcessorRef, type ProgressEvent, type ProgressListener, type ProgressSnapshot, type ProgressTrackerOptions, RUNTIMES_DIR, RUNTIME_PLATFORM_KEYS, type RefreshOptions, type RepairAllInput, type RepairAllReport, type RepairAspect, type RepairPhase, RepairPhases, type RepairPlan, type RepairPlanOptions, type RepairReport, type ResolvedFabricLoader, type ResolvedForgeLoader, type ResolvedLaunchVersion, type ResolvedMinecraft, type ResolvedRuntime, type ResolvedVanillaLoader, type ResolverContext, type RunForgeProcessorAction, type RunRepairInput, type RuntimeComponent, RuntimeComponents, type RuntimeFileDirectory, type RuntimeFileEntry, type RuntimeFileFile, type RuntimeFileLink, type RuntimeFilesManifest, type RuntimeIndex, type RuntimeIndexEntry, type RuntimeIndexPlatform, type RuntimeListEntry, type RuntimeListInput, type RuntimeOnlyInstallTarget, RuntimePreference, type RuntimePreferenceKind, type RuntimeResolveInput, type RuntimeSystem, RuntimeVersionsApi, SPAWNER_MAX_LINE_BYTES, type SpawnOptions, type SpawnedProcess, type Spawner, type StartDeviceCodeOptions, type Target, type TargetCreateInput, type TargetListInput, type TargetLoaderInput, type TargetResolveInput, TargetsApi, type TargetsApiContext, USER_AGENT, type UpdatePlan, type UpdateReport, VERSIONS_DIR, type VerificationFileResult, type VerificationKind, VerificationKinds, type VerificationResult, type VerifyFabricInput, VerifyFileCategories, type VerifyFileCategory, type VerifyFileStatus, VerifyFileStatuses, type VerifyForgeInput, type VerifyMinecraftInput, type VerifyOperationOptions, type VerifyRuntimeInput, VersionPreference, type VersionPreferenceKind, type WriteLoggingConfigAction, type WriteVersionJsonAction, assertNever, consoleLogger, createInstallProgressTracker, createMemoryCache, detectSystem, isErrorCode, isMinecraftKitError, offlineUuidFor, parseMajorVersion, pickClientJarVersionId, planFabricRepair, planForgeRepair, planMinecraftRepair, planRuntimeInstall, planRuntimeRepair, planStandaloneRuntimeInstall, repairAll, resolveLaunchVersion, runRepair, scopedLogger, silentLogger, stripUuidDashes, targetPaths, toOnlineAuth, verifyFabric, verifyForge, verifyMinecraft, verifyRuntime };