@loontail/minecraft-kit 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1,3 +1,16 @@
+/**
+ * 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. */
 interface MetadataCache {
     get<T>(key: string): T | undefined;
@@ -667,193 +680,6 @@ interface PlanStandaloneRuntimeInstallInput {
  */
 declare function 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";
@@ -1091,6 +917,243 @@ interface OperationOptions {
     readonly onEvent?: ProgressListener;
 }
 
+/** 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;
+}
+
+interface RepairAllInput {
+    readonly target: Target;
+    readonly http: HttpClient;
+    readonly cache: MetadataCache;
+    readonly spawner: Spawner;
+    readonly signal?: AbortSignal;
+    readonly onEvent?: ProgressListener;
+}
+interface 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 function repairAll(input: RepairAllInput): Promise<RepairAllReport>;
+
+/** 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;
+}
+/** Parse the leading integer from a runtime versionName (`"21.0.8"` → 21). */
+declare function parseMajorVersion(versionName: string): number | undefined;
+
+/** 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[]>;
+}
+
 /** Authentication modes accepted by the launch composer. */
 declare const AuthModes: {
     /** Offline-mode play with a chosen username and synthetic UUID. */
@@ -1186,36 +1249,6 @@ interface LaunchRunOptions {
     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 {
     readonly targetId: string;
@@ -1264,11 +1297,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,6 +1341,8 @@ 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>;
@@ -1317,6 +1352,11 @@ declare class MinecraftKit {
     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 {
     readonly signal?: AbortSignal;
@@ -1333,6 +1373,54 @@ interface RepairAspect {
     run(plan: RepairPlan, options?: OperationOptions): Promise<RepairReport>;
 }
 
+/** Result of resolving the on-disk version JSON for a target. */
+interface 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 function resolveLaunchVersion(target: Target): Promise<ResolvedLaunchVersion>;
+/**
+ * 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.
+ *
+ * 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.
+ */
+declare function pickClientJarVersionId(directory: string, chain: readonly string[]): Promise<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;
+};
+
 /** Inputs to {@link createMemoryCache}. */
 interface MemoryCacheOptions {
     readonly maxEntries?: number;
@@ -1455,6 +1543,39 @@ type PlanRuntimeRepairInput = AspectRepairInput;
  */
 declare function planRuntimeRepair(input: PlanRuntimeRepairInput): Promise<RepairPlan>;
 
+/** 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];
+interface ProgressSnapshot {
+    readonly stage: InstallStage;
+    readonly stagePercent: number;
+    readonly overallPercent: number;
+    readonly bytesDownloaded: number;
+    readonly totalBytes: number;
+    readonly currentFile?: string;
+}
+interface ProgressTrackerOptions {
+    /** Milliseconds between snapshot pushes. Defaults to 100ms. */
+    readonly throttleMs?: number;
+}
+interface 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 function createInstallProgressTracker(plan: Pick<InstallPlan, "actions">, options?: ProgressTrackerOptions): InstallProgressTracker;
+
 /**
  * Stable error code discriminator. Consumers can `switch (e.code)` exhaustively.
  *
@@ -1711,4 +1832,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, 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 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, 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, PauseController, type PlanFabricRepairInput, type PlanForgeRepairInput, type PlanMinecraftRepairInput, type PlanRuntimeInstallInput, type PlanRuntimeRepairInput, type PlanStandaloneRuntimeInstallInput, type ProcessStream, type ProcessorRef, type ProgressEvent, type ProgressListener, type ProgressSnapshot, type ProgressTrackerOptions, RUNTIMES_DIR, RUNTIME_PLATFORM_KEYS, 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, 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, createInstallProgressTracker, createMemoryCache, detectSystem, isErrorCode, isMinecraftKitError, offlineUuidFor, parseMajorVersion, pickClientJarVersionId, planFabricRepair, planForgeRepair, planMinecraftRepair, planRuntimeInstall, planRuntimeRepair, planStandaloneRuntimeInstall, repairAll, resolveLaunchVersion, runRepair, silentLogger, stripUuidDashes, targetPaths, verifyFabric, verifyForge, verifyMinecraft, verifyRuntime };