@loontail/minecraft-kit 0.6.0 → 0.6.1

package/dist/index.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import process2 from 'process';
 import os from 'os';
 import { LRUCache } from 'lru-cache';
 import path from 'path';
@@ -12,6 +13,317 @@ import { AsyncResource } from 'async_hooks';
 import { Buffer as Buffer$1 } from 'buffer';
 import { spawn } from 'child_process';
 
+// src/types/errors.ts
+var MinecraftKitErrorCodes = {
+  NETWORK_TIMEOUT: "NETWORK_TIMEOUT",
+  NETWORK_HTTP_ERROR: "NETWORK_HTTP_ERROR",
+  NETWORK_ABORTED: "NETWORK_ABORTED",
+  INTEGRITY_HASH_MISMATCH: "INTEGRITY_HASH_MISMATCH",
+  INTEGRITY_SIZE_MISMATCH: "INTEGRITY_SIZE_MISMATCH",
+  MANIFEST_INVALID: "MANIFEST_INVALID",
+  MANIFEST_NOT_FOUND: "MANIFEST_NOT_FOUND",
+  METADATA_PARSE_ERROR: "METADATA_PARSE_ERROR",
+  FILESYSTEM_PATH_TRAVERSAL: "FILESYSTEM_PATH_TRAVERSAL",
+  FILESYSTEM_WRITE_ERROR: "FILESYSTEM_WRITE_ERROR",
+  FILESYSTEM_READ_ERROR: "FILESYSTEM_READ_ERROR",
+  ARCHIVE_INVALID: "ARCHIVE_INVALID",
+  ARCHIVE_TOO_LARGE: "ARCHIVE_TOO_LARGE",
+  ARCHIVE_ENTRY_REJECTED: "ARCHIVE_ENTRY_REJECTED",
+  RUNTIME_NOT_FOUND: "RUNTIME_NOT_FOUND",
+  RUNTIME_UNSUPPORTED_PLATFORM: "RUNTIME_UNSUPPORTED_PLATFORM",
+  FORGE_PROCESSOR_FAILED: "FORGE_PROCESSOR_FAILED",
+  FORGE_INSTALLER_INVALID: "FORGE_INSTALLER_INVALID",
+  LAUNCH_JAVA_NOT_FOUND: "LAUNCH_JAVA_NOT_FOUND",
+  LAUNCH_PROCESS_FAILED: "LAUNCH_PROCESS_FAILED",
+  LAUNCH_ABORTED: "LAUNCH_ABORTED",
+  VERIFICATION_FAILED: "VERIFICATION_FAILED",
+  INVALID_INPUT: "INVALID_INPUT",
+  NOT_IMPLEMENTED: "NOT_IMPLEMENTED",
+  UNSUPPORTED_VERSION: "UNSUPPORTED_VERSION",
+  LZMA_DECODE_ERROR: "LZMA_DECODE_ERROR",
+  AUTH_DEVICE_CODE_EXPIRED: "AUTH_DEVICE_CODE_EXPIRED",
+  AUTH_DEVICE_CODE_DECLINED: "AUTH_DEVICE_CODE_DECLINED",
+  AUTH_DEVICE_CODE_FAILED: "AUTH_DEVICE_CODE_FAILED",
+  AUTH_REFRESH_FAILED: "AUTH_REFRESH_FAILED",
+  AUTH_XBOX_FAILED: "AUTH_XBOX_FAILED",
+  AUTH_XSTS_FAILED: "AUTH_XSTS_FAILED",
+  AUTH_MINECRAFT_FAILED: "AUTH_MINECRAFT_FAILED",
+  AUTH_NO_GAME_OWNERSHIP: "AUTH_NO_GAME_OWNERSHIP",
+  AUTH_MISSING_CLIENT_ID: "AUTH_MISSING_CLIENT_ID",
+  AUTH_CANCELLED: "AUTH_CANCELLED"
+};
+
+// src/core/errors.ts
+var MinecraftKitError = class extends Error {
+  name = "MinecraftKitError";
+  /** Stable discriminator. */
+  code;
+  /** Structured context; safe to serialize. */
+  context;
+  constructor(code, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.code = code;
+    this.context = Object.freeze({ ...options.context ?? {} });
+  }
+  /** JSON-friendly representation. */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      context: this.context,
+      cause: this.cause instanceof Error ? { name: this.cause.name, message: this.cause.message } : this.cause
+    };
+  }
+};
+var isMinecraftKitError = (e) => {
+  return e instanceof MinecraftKitError;
+};
+var isErrorCode = (e, code) => {
+  return isMinecraftKitError(e) && e.code === code;
+};
+
+// src/types/auth.ts
+var AuthModes = {
+  /** Offline-mode play with a chosen username and synthetic UUID. */
+  OFFLINE: "offline",
+  /** Pre-authenticated session — caller provides the access token and identity. */
+  ONLINE: "online"
+};
+
+// src/auth/microsoft.ts
+var TENANT = "consumers";
+var DEVICE_CODE_URL = `https://login.microsoftonline.com/${TENANT}/oauth2/v2.0/devicecode`;
+var TOKEN_URL = `https://login.microsoftonline.com/${TENANT}/oauth2/v2.0/token`;
+var SCOPE = "XboxLive.signin offline_access";
+var startDeviceCode = async (input) => {
+  const body = new URLSearchParams({ client_id: input.clientId, scope: SCOPE });
+  const response = await input.http.request(DEVICE_CODE_URL, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body: body.toString(),
+    // We need to read the body of 400/401 responses to surface Microsoft's actual
+    // `error_description` rather than reporting "HTTP 400" — the most common cause is
+    // an app registration that doesn't allow personal MSA accounts or hasn't enabled
+    // public client flows.
+    acceptNonOk: true,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  if (response.status < 200 || response.status >= 300) {
+    const err = await response.json().catch(() => ({}));
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_DEVICE_CODE_FAILED,
+      explainDeviceCodeError(err, input.clientId),
+      {
+        context: {
+          httpStatus: response.status,
+          microsoftError: err.error,
+          clientId: input.clientId
+        }
+      }
+    );
+  }
+  const data = await response.json();
+  const now = Date.now();
+  const state = {
+    deviceCode: data.device_code,
+    userCode: data.user_code,
+    verificationUri: data.verification_uri,
+    message: data.message,
+    expiresIn: data.expires_in,
+    interval: data.interval,
+    clientId: input.clientId,
+    expiresAt: now + data.expires_in * 1e3
+  };
+  const prompt = {
+    userCode: data.user_code,
+    verificationUri: data.verification_uri,
+    message: data.message,
+    expiresIn: data.expires_in,
+    interval: data.interval
+  };
+  return { prompt, state };
+};
+var pollDeviceCode = async (input) => {
+  let intervalSec = input.state.interval;
+  while (true) {
+    if (input.signal?.aborted) {
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.AUTH_CANCELLED,
+        "Device-code polling aborted.",
+        {
+          context: { reason: input.signal.reason }
+        }
+      );
+    }
+    if (Date.now() >= input.state.expiresAt) {
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.AUTH_DEVICE_CODE_EXPIRED,
+        "Device code expired before the user signed in."
+      );
+    }
+    const delayMs = intervalSec * 1e3;
+    input.onTick?.({ nextDelayMs: delayMs, expiresAt: input.state.expiresAt });
+    await wait(delayMs, input.signal);
+    const body = new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      client_id: input.state.clientId,
+      device_code: input.state.deviceCode
+    });
+    const response = await input.http.request(TOKEN_URL, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: body.toString(),
+      acceptNonOk: true
+    });
+    if (response.status >= 200 && response.status < 300) {
+      const ok = await response.json();
+      if (!ok.refresh_token) {
+        throw new MinecraftKitError(
+          MinecraftKitErrorCodes.AUTH_DEVICE_CODE_FAILED,
+          "Microsoft did not return a refresh token. Make sure `offline_access` is in the requested scopes."
+        );
+      }
+      return {
+        accessToken: ok.access_token,
+        refreshToken: ok.refresh_token,
+        expiresIn: ok.expires_in
+      };
+    }
+    const err = await response.json().catch(() => ({}));
+    switch (err.error) {
+      case "authorization_pending":
+        continue;
+      case "slow_down":
+        intervalSec += 5;
+        continue;
+      case "authorization_declined":
+        throw new MinecraftKitError(
+          MinecraftKitErrorCodes.AUTH_DEVICE_CODE_DECLINED,
+          "The user declined the sign-in request."
+        );
+      case "expired_token":
+        throw new MinecraftKitError(
+          MinecraftKitErrorCodes.AUTH_DEVICE_CODE_EXPIRED,
+          "Device code expired before the user signed in."
+        );
+      default:
+        throw new MinecraftKitError(
+          MinecraftKitErrorCodes.AUTH_DEVICE_CODE_FAILED,
+          `Microsoft device-code exchange failed: ${err.error ?? "unknown_error"}${err.error_description ? ` \u2014 ${err.error_description}` : ""}`,
+          { context: { httpStatus: response.status, microsoftError: err.error } }
+        );
+    }
+  }
+};
+var refreshMicrosoftToken = async (input) => {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    client_id: input.clientId,
+    refresh_token: input.refreshToken,
+    scope: SCOPE
+  });
+  const response = await input.http.request(TOKEN_URL, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body: body.toString(),
+    acceptNonOk: true,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  if (response.status < 200 || response.status >= 300) {
+    const err = await response.json().catch(() => ({}));
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_REFRESH_FAILED,
+      `Microsoft refused to refresh the token: ${err.error ?? "unknown_error"}${err.error_description ? ` \u2014 ${err.error_description}` : ""}`,
+      { context: { httpStatus: response.status, microsoftError: err.error } }
+    );
+  }
+  const ok = await response.json();
+  return {
+    accessToken: ok.access_token,
+    refreshToken: ok.refresh_token ?? input.refreshToken,
+    expiresIn: ok.expires_in
+  };
+};
+var explainDeviceCodeError = (err, clientId) => {
+  const desc = err.error_description ?? "";
+  const ms = desc ? ` \u2014 ${desc}` : "";
+  if (/AADSTS700016/i.test(desc) || /not found in the directory/i.test(desc)) {
+    return `Microsoft cannot see app ${clientId} from the consumers tenant. Fix: Azure portal \u2192 your app \u2192 Authentication \u2192 "Supported account types" \u2192 choose "Personal Microsoft accounts only" or "Multitenant + personal accounts" \u2192 Save. Wait ~30s for propagation.${ms}`;
+  }
+  if (/AADSTS7000218/i.test(desc) || /must either be a confidential client/i.test(desc)) {
+    return `Microsoft rejected the client_id (${clientId}): "Allow public client flows" is OFF. Fix: Azure portal \u2192 your app \u2192 Authentication \u2192 bottom of the page \u2192 toggle "Allow public client flows" to Yes \u2192 Save.${ms}`;
+  }
+  if (/AADSTS50059/i.test(desc) || /tenant identifier/i.test(desc)) {
+    return `Microsoft Entra cannot route the request \u2014 the app's "Supported account types" excludes consumers. Fix: Azure portal \u2192 Authentication \u2192 set Supported account types to include personal MSA \u2192 Save.${ms}`;
+  }
+  switch (err.error) {
+    case "unauthorized_client":
+      return `Microsoft rejected the client_id (${clientId}). Likely cause: "Supported account types" excludes personal Microsoft accounts, OR "Allow public client flows" is disabled. Fix both in Azure portal \u2192 your app \u2192 Authentication.${ms}`;
+    case "invalid_client":
+      return `Microsoft does not recognise client_id ${clientId}. Make sure you pasted the Application (client) ID \u2014 not the Object ID or Tenant ID \u2014 and that the app exists.${ms}`;
+    case "invalid_request":
+      return `Microsoft rejected the device-code request as malformed.${ms}`;
+    case "invalid_scope":
+      return `Microsoft refused the requested scope (XboxLive.signin offline_access). Make sure the app is configured for Microsoft account sign-in.${ms}`;
+    default:
+      return `Microsoft device-code request failed: ${err.error ?? "unknown_error"}${ms}`;
+  }
+};
+var wait = (ms, signal) => {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(
+        new MinecraftKitError(
+          MinecraftKitErrorCodes.AUTH_CANCELLED,
+          "Device-code polling aborted.",
+          {
+            context: { reason: signal.reason }
+          }
+        )
+      );
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(
+        new MinecraftKitError(
+          MinecraftKitErrorCodes.AUTH_CANCELLED,
+          "Device-code polling aborted.",
+          {
+            context: { reason: signal?.reason }
+          }
+        )
+      );
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+};
+
+// src/core/json.ts
+var parseJsonStrict = (text, options) => {
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    throw new MinecraftKitError(options.code, options.message, {
+      cause,
+      ...options.context !== void 0 ? { context: options.context } : {}
+    });
+  }
+};
+var parseJsonOrUndefined = (text) => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+};
+
 // src/types/logger.ts
 var LogLevels = {
   DEBUG: "debug",
@@ -35,12 +347,361 @@ var consoleLogger = {
     }
   }
 };
-function pickConsole(level) {
+var scopedLogger = (base, scope, baseFields) => {
+  if (base === silentLogger) return silentLogger;
+  return {
+    log(level, message, fields) {
+      const merged = baseFields !== void 0 || fields !== void 0 ? { ...baseFields, ...fields } : void 0;
+      if (merged !== void 0) {
+        base.log(level, `[${scope}] ${message}`, merged);
+      } else {
+        base.log(level, `[${scope}] ${message}`);
+      }
+    }
+  };
+};
+var pickConsole = (level) => {
   if (level === LogLevels.ERROR) return console.error.bind(console);
   if (level === LogLevels.WARN) return console.warn.bind(console);
   if (level === LogLevels.INFO) return console.info.bind(console);
   return console.debug.bind(console);
-}
+};
+
+// src/auth/debug.ts
+var DEBUG_ENV_VAR = "MINECRAFT_KIT_AUTH_DEBUG";
+var authDebug = (message) => {
+  if (process2.env[DEBUG_ENV_VAR]) {
+    process2.stderr.write(`[auth] ${message}
+`);
+  }
+};
+
+// src/auth/minecraft.ts
+var MC_LOGIN_URL = "https://api.minecraftservices.com/authentication/login_with_xbox";
+var MC_PROFILE_URL = "https://api.minecraftservices.com/minecraft/profile";
+var loginWithXbox = async (input) => {
+  const body = JSON.stringify({
+    identityToken: `XBL3.0 x=${input.userHash};${input.xstsToken}`
+  });
+  authDebug(
+    `login_with_xbox POST \u2014 userHashLen=${input.userHash.length}, xstsTokenLen=${input.xstsToken.length}`
+  );
+  const response = await input.http.request(MC_LOGIN_URL, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json",
+      // Mojang sometimes rejects unknown user-agents on the auth endpoints. Override the
+      // library default with a UA that matches what real Minecraft launchers send, so we
+      // don't trip an "anomalous client" filter.
+      "user-agent": "Minecraft Launcher/2.0 (minecraft-kit)"
+    },
+    body,
+    acceptNonOk: true,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  if (response.status < 200 || response.status >= 300) {
+    const rawBody = await response.text().catch(() => "");
+    const detail = rawBody.slice(0, 400);
+    authDebug(`login_with_xbox failed status=${response.status} body=${detail}`);
+    if (response.status === 403) {
+      if (/invalid app registration/i.test(detail)) {
+        throw new MinecraftKitError(
+          MinecraftKitErrorCodes.AUTH_MINECRAFT_FAILED,
+          `Mojang has not approved this Azure AD application id for the Minecraft API. The OAuth + Xbox/XSTS exchange all succeeded, but api.minecraftservices.com only accepts client_ids that are on its allow-list. Apply at https://aka.ms/mce-reviewappid (Application ID, contact email, purpose) \u2014 approval typically takes a few days. Raw response: ${detail}`,
+          { context: { httpStatus: 403, body: detail, reason: "invalid_app_registration" } }
+        );
+      }
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.AUTH_NO_GAME_OWNERSHIP,
+        `Mojang refused login_with_xbox (HTTP 403). The Xbox/Microsoft exchange succeeded, but api.minecraftservices.com declined to issue a Minecraft token. Most common causes: (1) you signed in to the browser with a DIFFERENT Microsoft account than the one owning Java Edition \u2014 re-check the email on https://www.minecraft.net/profile and make sure it matches what you typed at the device-code page; (2) this account never used Xbox services before \u2014 open https://www.xbox.com once with this account, then retry; (3) transient Mojang 5xx/403, just retry in 60s. Raw response: ${detail || "<empty>"}`,
+        { context: { httpStatus: 403, body: detail } }
+      );
+    }
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_MINECRAFT_FAILED,
+      `Minecraft sign-in failed with HTTP ${response.status}. Response: ${detail || "<empty>"}`,
+      { context: { httpStatus: response.status, body: detail } }
+    );
+  }
+  const parsed = await response.json();
+  if (!parsed.access_token) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_MINECRAFT_FAILED,
+      "Minecraft sign-in returned no access token."
+    );
+  }
+  return { accessToken: parsed.access_token, expiresIn: parsed.expires_in };
+};
+var fetchMinecraftProfile = async (input) => {
+  const response = await input.http.request(MC_PROFILE_URL, {
+    headers: {
+      authorization: `Bearer ${input.accessToken}`,
+      accept: "application/json",
+      "user-agent": "Minecraft Launcher/2.0 (minecraft-kit)"
+    },
+    acceptNonOk: true,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  if (response.status === 404) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_NO_GAME_OWNERSHIP,
+      "This Microsoft account does not own Minecraft: Java Edition.",
+      { context: { httpStatus: 404 } }
+    );
+  }
+  if (response.status < 200 || response.status >= 300) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_MINECRAFT_FAILED,
+      `Failed to load Minecraft profile (HTTP ${response.status}).`,
+      { context: { httpStatus: response.status } }
+    );
+  }
+  const parsed = await response.json();
+  if (parsed.errorMessage || !parsed.id || !parsed.name) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_MINECRAFT_FAILED,
+      parsed.errorMessage ?? "Minecraft profile response was malformed."
+    );
+  }
+  return { uuid: dashUuid(parsed.id), username: parsed.name };
+};
+var extractXuid = (accessToken) => {
+  const parts = accessToken.split(".");
+  const payload = parts[1];
+  if (typeof payload !== "string") return "";
+  const json = Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString(
+    "utf8"
+  );
+  const parsed = parseJsonOrUndefined(json);
+  return typeof parsed?.xuid === "string" ? parsed.xuid : "";
+};
+var dashUuid = (raw) => {
+  if (raw.includes("-")) return raw;
+  if (raw.length !== 32) return raw;
+  return `${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(
+    16,
+    20
+  )}-${raw.slice(20)}`;
+};
+
+// src/auth/xbox.ts
+var XBL_URL = "https://user.auth.xboxlive.com/user/authenticate";
+var XSTS_URL = "https://xsts.auth.xboxlive.com/xsts/authorize";
+var authenticateXbl = async (input) => {
+  const body = JSON.stringify({
+    Properties: {
+      AuthMethod: "RPS",
+      SiteName: "user.auth.xboxlive.com",
+      RpsTicket: `d=${input.accessToken}`
+    },
+    RelyingParty: "http://auth.xboxlive.com",
+    TokenType: "JWT"
+  });
+  let response;
+  try {
+    response = await input.http.request(XBL_URL, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body,
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+  } catch (cause) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_XBOX_FAILED,
+      "Xbox Live authentication failed.",
+      {
+        cause
+      }
+    );
+  }
+  const parsed = await response.json();
+  const userHash = parsed.DisplayClaims?.xui?.[0]?.uhs;
+  if (!parsed.Token || !userHash) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_XBOX_FAILED,
+      "Xbox Live authentication returned an incomplete response."
+    );
+  }
+  input.logger?.log("debug", `XBL ok \u2014 tokenLen=${parsed.Token.length}, userHash=${userHash}`);
+  return { token: parsed.Token, userHash };
+};
+var authenticateXsts = async (input) => {
+  const body = JSON.stringify({
+    Properties: { SandboxId: "RETAIL", UserTokens: [input.xblToken] },
+    RelyingParty: "rp://api.minecraftservices.com/",
+    TokenType: "JWT"
+  });
+  const response = await input.http.request(XSTS_URL, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body,
+    acceptNonOk: true,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  if (response.status === 401) {
+    const err = await response.json().catch(() => ({}));
+    throw new MinecraftKitError(MinecraftKitErrorCodes.AUTH_XSTS_FAILED, explainXErr(err.XErr), {
+      context: { xerr: err.XErr ?? null, message: err.Message ?? null }
+    });
+  }
+  if (response.status < 200 || response.status >= 300) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_XSTS_FAILED,
+      `XSTS authorization failed with HTTP ${response.status}.`,
+      { context: { httpStatus: response.status } }
+    );
+  }
+  const parsed = await response.json();
+  const userHash = parsed.DisplayClaims?.xui?.[0]?.uhs;
+  if (!parsed.Token || !userHash) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.AUTH_XSTS_FAILED,
+      "XSTS authorization returned an incomplete response."
+    );
+  }
+  input.logger?.log("debug", `XSTS ok \u2014 tokenLen=${parsed.Token.length}, userHash=${userHash}`);
+  return { token: parsed.Token, userHash };
+};
+var explainXErr = (xerr) => {
+  switch (xerr) {
+    case 2148916227:
+      return "This account has been banned from Xbox.";
+    case 2148916233:
+      return "This Microsoft account has no Xbox profile yet \u2014 sign in once at https://minecraft.net to create one.";
+    case 2148916235:
+      return "Xbox Live is not available in this account's country/region.";
+    case 2148916236:
+    case 2148916237:
+      return "This account needs an adult to verify it. Sign in on Xbox to complete the prompt.";
+    case 2148916238:
+      return "This is a child account. Add it to a Microsoft family group with an adult to continue.";
+    default:
+      return xerr ? `XSTS authorization failed (XErr ${xerr}).` : "XSTS authorization failed.";
+  }
+};
+
+// src/auth/index.ts
+var CLIENT_ID_ENV_VAR = "MINECRAFT_KIT_MSA_CLIENT_ID";
+var MojangAuthApi = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * 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.
+   */
+  async login(options) {
+    const clientId = resolveClientId(options.clientId);
+    const { prompt, state } = await startDeviceCode({
+      http: this.http,
+      clientId,
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    await options.onPrompt(prompt);
+    const msToken = await pollDeviceCode({
+      http: this.http,
+      state,
+      ...options.signal !== void 0 ? { signal: options.signal } : {},
+      ...options.onPoll !== void 0 ? { onTick: options.onPoll } : {}
+    });
+    return this.completeMicrosoftToken(msToken, clientId, options.signal);
+  }
+  /** Refresh a previously obtained session. The Microsoft refresh token may be rotated. */
+  async refresh(refreshToken, options = {}) {
+    const clientId = resolveClientId(options.clientId);
+    const msToken = await refreshMicrosoftToken({
+      http: this.http,
+      refreshToken,
+      clientId,
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    return this.completeMicrosoftToken(msToken, clientId, options.signal);
+  }
+  /**
+   * 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.
+   */
+  deviceCode = {
+    start: (options = {}) => {
+      const clientId = resolveClientId(options.clientId);
+      return startDeviceCode({
+        http: this.http,
+        clientId,
+        ...options.signal !== void 0 ? { signal: options.signal } : {}
+      });
+    },
+    poll: async (state, options = {}) => {
+      const msToken = await pollDeviceCode({
+        http: this.http,
+        state,
+        ...options.signal !== void 0 ? { signal: options.signal } : {},
+        ...options.onTick !== void 0 ? { onTick: options.onTick } : {}
+      });
+      return this.completeMicrosoftToken(msToken, state.clientId, options.signal);
+    }
+  };
+  /** Steps 2 → 5: given a Microsoft access token, finish the flow. */
+  async completeMicrosoftToken(msToken, clientId, signal) {
+    const signalOpt = signal !== void 0 ? { signal } : {};
+    const xbl = await authenticateXbl({
+      http: this.http,
+      accessToken: msToken.accessToken,
+      ...signalOpt
+    });
+    const xsts = await authenticateXsts({
+      http: this.http,
+      xblToken: xbl.token,
+      ...signalOpt
+    });
+    const mc = await loginWithXbox({
+      http: this.http,
+      xstsToken: xsts.token,
+      userHash: xsts.userHash,
+      ...signalOpt
+    });
+    const profile = await fetchMinecraftProfile({
+      http: this.http,
+      accessToken: mc.accessToken,
+      ...signalOpt
+    });
+    return {
+      minecraft: {
+        username: profile.username,
+        uuid: profile.uuid,
+        accessToken: mc.accessToken,
+        expiresAt: Date.now() + mc.expiresIn * 1e3,
+        xuid: extractXuid(mc.accessToken)
+      },
+      microsoft: {
+        refreshToken: msToken.refreshToken,
+        clientId
+      }
+    };
+  }
+};
+var toOnlineAuth = (session) => {
+  return {
+    mode: AuthModes.ONLINE,
+    username: session.minecraft.username,
+    uuid: session.minecraft.uuid,
+    accessToken: session.minecraft.accessToken,
+    userType: "msa",
+    clientId: session.microsoft.clientId,
+    xuid: session.minecraft.xuid
+  };
+};
+var resolveClientId = (explicit) => {
+  if (typeof explicit === "string" && explicit.trim().length > 0) return explicit.trim();
+  const fromEnv = process.env[CLIENT_ID_ENV_VAR];
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) return fromEnv.trim();
+  throw new MinecraftKitError(
+    MinecraftKitErrorCodes.AUTH_MISSING_CLIENT_ID,
+    `No Azure AD client id supplied. Pass \`clientId\` explicitly or set ${CLIENT_ID_ENV_VAR}. Register an Azure AD application in the 'Personal Microsoft accounts' audience with XboxLive.signin + offline_access scopes to obtain one.`
+  );
+};
 
 // src/constants/platform.ts
 var NODE_PLATFORM_TO_MOJANG_OS = {
@@ -59,39 +720,8 @@ var RUNTIME_PLATFORM_KEYS = {
   linux: { x64: "linux", x86: "linux-i386", arm64: "linux" }
 };
 
-// src/core/errors.ts
-var MinecraftKitError = class extends Error {
-  name = "MinecraftKitError";
-  /** Stable discriminator. */
-  code;
-  /** Structured context; safe to serialize. */
-  context;
-  constructor(code, message, options = {}) {
-    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
-    Object.setPrototypeOf(this, new.target.prototype);
-    this.code = code;
-    this.context = Object.freeze({ ...options.context ?? {} });
-  }
-  /** JSON-friendly representation. */
-  toJSON() {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      context: this.context,
-      cause: this.cause instanceof Error ? { name: this.cause.name, message: this.cause.message } : this.cause
-    };
-  }
-};
-function isMinecraftKitError(e) {
-  return e instanceof MinecraftKitError;
-}
-function isErrorCode(e, code) {
-  return isMinecraftKitError(e) && e.code === code;
-}
-
 // src/core/system.ts
-function detectSystem(input = {}) {
+var detectSystem = (input = {}) => {
   const platform = input.platform ?? process.platform;
   const arch = input.arch ?? process.arch;
   const osVersion = input.osVersion ?? os.release();
@@ -99,13 +729,13 @@ function detectSystem(input = {}) {
   const mojangArch = NODE_ARCH_TO_MOJANG_ARCH[arch];
   if (mojangOs === void 0 || mojangArch === void 0) {
     throw new MinecraftKitError(
-      "RUNTIME_UNSUPPORTED_PLATFORM",
+      MinecraftKitErrorCodes.RUNTIME_UNSUPPORTED_PLATFORM,
       `Unsupported platform/arch combination: ${platform}/${arch}`,
       { context: { platform, arch: String(arch) } }
     );
   }
   return { os: mojangOs, arch: mojangArch, osVersion };
-}
+};
 
 // src/constants/defaults.ts
 var HTTP_TIMEOUT_MS = 3e4;
@@ -126,7 +756,7 @@ var MAX_PROCESSOR_STDERR_LINES = 20;
 var SPAWNER_MAX_LINE_BYTES = 64 * 1024;
 
 // src/http/cache.ts
-function createMemoryCache(options = {}) {
+var createMemoryCache = (options = {}) => {
   const cache = new LRUCache({
     max: options.maxEntries ?? CACHE_MAX_ENTRIES,
     ttl: options.ttlMs ?? CACHE_TTL_MS
@@ -151,7 +781,7 @@ function createMemoryCache(options = {}) {
       cache.clear();
     }
   };
-}
+};
 
 // src/http/client.ts
 var TIMEOUT_REASON = /* @__PURE__ */ Symbol("http-timeout");
@@ -169,39 +799,60 @@ var FetchHttpClient = class {
     }
     const timer = setTimeout(() => controller.abort(TIMEOUT_REASON), timeoutMs);
     let response;
+    const method = options.method ?? "GET";
     try {
-      response = await fetch(url, {
-        method: "GET",
+      const init = {
+        method,
         headers: { "user-agent": USER_AGENT, ...options.headers ?? {} },
         signal: controller.signal,
         redirect: "follow"
-      });
+      };
+      if (method !== "GET" && options.body !== void 0) {
+        init.body = options.body;
+      }
+      response = await fetch(url, init);
     } catch (cause) {
       clearTimeout(timer);
       options.signal?.removeEventListener("abort", onParentAbort);
       if (controller.signal.reason === TIMEOUT_REASON) {
-        throw new MinecraftKitError("NETWORK_TIMEOUT", `Request timed out: ${url}`, {
-          cause,
-          context: { url, timeoutMs }
-        });
+        throw new MinecraftKitError(
+          MinecraftKitErrorCodes.NETWORK_TIMEOUT,
+          `Request timed out: ${url}`,
+          {
+            cause,
+            context: { url, timeoutMs }
+          }
+        );
       }
       if (options.signal?.aborted) {
-        throw new MinecraftKitError("NETWORK_ABORTED", `Request aborted: ${url}`, {
+        throw new MinecraftKitError(
+          MinecraftKitErrorCodes.NETWORK_ABORTED,
+          `Request aborted: ${url}`,
+          {
+            cause,
+            context: { url }
+          }
+        );
+      }
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.NETWORK_HTTP_ERROR,
+        `Network request failed: ${url}`,
+        {
           cause,
           context: { url }
-        });
-      }
-      throw new MinecraftKitError("NETWORK_HTTP_ERROR", `Network request failed: ${url}`, {
-        cause,
-        context: { url }
-      });
+        }
+      );
     }
     clearTimeout(timer);
     options.signal?.removeEventListener("abort", onParentAbort);
-    if (!response.ok) {
-      throw new MinecraftKitError("NETWORK_HTTP_ERROR", `HTTP ${response.status} for ${url}`, {
-        context: { url, httpStatus: response.status }
-      });
+    if (!response.ok && options.acceptNonOk !== true) {
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.NETWORK_HTTP_ERROR,
+        `HTTP ${response.status} for ${url}`,
+        {
+          context: { url, httpStatus: response.status }
+        }
+      );
     }
     return new FetchHttpResponse(response, url);
   }
@@ -325,6 +976,17 @@ var InstallActionKinds = {
   WRITE_VERSION_JSON: "write-version-json",
   WRITE_LOGGING_CONFIG: "write-logging-config"
 };
+var DownloadCategories = {
+  CLIENT_JAR: "client-jar",
+  LIBRARY: "library",
+  ASSET_INDEX: "asset-index",
+  ASSET: "asset",
+  LOGGING_CONFIG: "logging-config",
+  FABRIC_LIBRARY: "fabric-library",
+  FORGE_LIBRARY: "forge-library",
+  RUNTIME_FILE: "runtime-file",
+  FORGE_INSTALLER: "forge-installer"
+};
 
 // src/types/loader.ts
 var Loaders = {
@@ -378,7 +1040,7 @@ var ApiEndpoints = {
 };
 
 // src/http/metadata.ts
-async function fetchJson(http, cache, input) {
+var fetchJson = async (http, cache, input) => {
   const key = input.cacheKey ?? `json:${input.url}`;
   const cached = cache.get(key);
   if (cached !== void 0) {
@@ -390,8 +1052,8 @@ async function fetchJson(http, cache, input) {
   const value = await response.json();
   cache.set(key, value, input.ttlMs ?? CACHE_TTL_MS);
   return value;
-}
-async function fetchText(http, cache, input) {
+};
+var fetchText = async (http, cache, input) => {
   const key = input.cacheKey ?? `text:${input.url}`;
   const cached = cache.get(key);
   if (cached !== void 0) {
@@ -403,10 +1065,10 @@ async function fetchText(http, cache, input) {
   const text = await response.text();
   cache.set(key, text, input.ttlMs ?? CACHE_TTL_MS);
   return text;
-}
+};
 
 // src/install/assets.ts
-async function planAssetDownloads(input) {
+var planAssetDownloads = async (input) => {
   const indexUrl = input.assetIndex.url;
   const indexPath = targetPaths.assetIndex(input.directory, input.assetIndex.id);
   const indexDocument = await fetchJson(input.http, input.cache, {
@@ -421,7 +1083,7 @@ async function planAssetDownloads(input) {
       target: indexPath,
       expectedSha1: input.assetIndex.sha1,
       expectedSize: input.assetIndex.size,
-      category: "asset-index"
+      category: DownloadCategories.ASSET_INDEX
     }
   ];
   const seen = /* @__PURE__ */ new Set();
@@ -434,11 +1096,11 @@ async function planAssetDownloads(input) {
       target: targetPaths.assetObject(input.directory, entry.hash),
       expectedSha1: entry.hash,
       expectedSize: entry.size,
-      category: "asset"
+      category: DownloadCategories.ASSET
     });
   }
   return { actions, indexDocument };
-}
+};
 
 // src/constants/maven.ts
 var DEFAULT_LIBRARY_REPOSITORY = "https://libraries.minecraft.net/";
@@ -446,21 +1108,25 @@ var FABRIC_MAVEN_BASE = "https://maven.fabricmc.net/";
 var FORGE_MAVEN_BASE = "https://maven.minecraftforge.net/";
 
 // src/core/maven.ts
-function parseMavenCoordinate(input) {
+var parseMavenCoordinate = (input) => {
   const trimmed = input.startsWith("[") && input.endsWith("]") ? input.slice(1, -1) : input;
   const atIndex = trimmed.indexOf("@");
   const extension = atIndex === -1 ? "jar" : trimmed.slice(atIndex + 1);
   const body = atIndex === -1 ? trimmed : trimmed.slice(0, atIndex);
   const parts = body.split(":");
   if (parts.length < 3 || parts.length > 4) {
-    throw new MinecraftKitError("INVALID_INPUT", `Invalid Maven coordinate: ${input}`, {
-      context: { input }
-    });
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.INVALID_INPUT,
+      `Invalid Maven coordinate: ${input}`,
+      {
+        context: { input }
+      }
+    );
   }
   const [group, artifact, version, classifier] = parts;
   if (!group || !artifact || !version) {
     throw new MinecraftKitError(
-      "INVALID_INPUT",
+      MinecraftKitErrorCodes.INVALID_INPUT,
       `Invalid Maven coordinate (missing component): ${input}`,
       { context: { input } }
     );
@@ -469,19 +1135,19 @@ function parseMavenCoordinate(input) {
     return { group, artifact, version, extension };
   }
   return { group, artifact, version, classifier, extension };
-}
-function mavenRelativePath(coord) {
+};
+var mavenRelativePath = (coord) => {
   const groupPath = coord.group.replaceAll(".", "/");
   const classifierSegment = coord.classifier === void 0 ? "" : `-${coord.classifier}`;
   const filename = `${coord.artifact}-${coord.version}${classifierSegment}.${coord.extension}`;
   return `${groupPath}/${coord.artifact}/${coord.version}/${filename}`;
-}
-function mavenRelativePathFor(input) {
+};
+var mavenRelativePathFor = (input) => {
   return mavenRelativePath(parseMavenCoordinate(input));
-}
+};
 
 // src/core/rules.ts
-function evaluateRules(rules, context) {
+var evaluateRules = (rules, context) => {
   if (!rules || rules.length === 0) {
     return true;
   }
@@ -492,8 +1158,8 @@ function evaluateRules(rules, context) {
     }
   }
   return allowed;
-}
-function matchesRule(rule, context) {
+};
+var matchesRule = (rule, context) => {
   if (rule.os !== void 0) {
     if (rule.os.name !== void 0 && rule.os.name !== context.system.os) {
       return false;
@@ -521,21 +1187,21 @@ function matchesRule(rule, context) {
     }
   }
   return true;
-}
-function normalizeArch(arch) {
+};
+var normalizeArch = (arch) => {
   return arch === "ia32" ? "x86" : arch;
-}
-function resolveArchPlaceholder(template, archDigit2) {
+};
+var resolveArchPlaceholder = (template, archDigit2) => {
   return template.replaceAll("${arch}", archDigit2);
-}
-function archDigit(arch) {
+};
+var archDigit = (arch) => {
   if (arch === "x86") return "32";
   if (arch === "x64") return "64";
   return "64";
-}
+};
 
 // src/install/libraries.ts
-function planLibraryDownloads(input) {
+var planLibraryDownloads = (input) => {
   const downloads = [];
   const nativeExtractions = [];
   const classpathFiles = [];
@@ -589,8 +1255,8 @@ function planLibraryDownloads(input) {
     }
   }
   return { downloads, nativeExtractions, classpathFiles };
-}
-function pickPrimaryArtifact(library) {
+};
+var pickPrimaryArtifact = (library) => {
   if (library.downloads?.artifact) {
     return artifactFromDownload(library.downloads.artifact);
   }
@@ -601,8 +1267,8 @@ function pickPrimaryArtifact(library) {
     return mavenArtifactFromCoord(library.name, DEFAULT_LIBRARY_REPOSITORY);
   }
   return null;
-}
-function pickNative(library, system) {
+};
+var pickNative = (library, system) => {
   if (!library.natives) return null;
   const classifierTemplate = library.natives[system.os];
   if (!classifierTemplate) return null;
@@ -617,22 +1283,26 @@ function pickNative(library, system) {
     return mavenArtifactFromCoord(withClassifier, library.url ?? DEFAULT_LIBRARY_REPOSITORY);
   }
   return null;
-}
-function artifactFromDownload(artifact) {
+};
+var artifactFromDownload = (artifact) => {
   return {
     relativePath: artifact.path,
     url: artifact.url,
     sha1: artifact.sha1,
     size: artifact.size
   };
-}
-function mavenArtifactFromCoord(coord, baseUrl) {
+};
+var mavenArtifactFromCoord = (coord, baseUrl) => {
   const relativePath = mavenRelativePathFor(coord);
   const normalizedBase = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
   if (!relativePath) {
-    throw new MinecraftKitError("MANIFEST_INVALID", `Invalid library coordinate: ${coord}`, {
-      context: { input: coord }
-    });
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.MANIFEST_INVALID,
+      `Invalid library coordinate: ${coord}`,
+      {
+        context: { input: coord }
+      }
+    );
   }
   return {
     relativePath,
@@ -640,10 +1310,10 @@ function mavenArtifactFromCoord(coord, baseUrl) {
     sha1: void 0,
     size: void 0
   };
-}
+};
 
 // src/install/fabric-install.ts
-function planFabricInstall(input) {
+var planFabricInstall = (input) => {
   const versionId = input.loader.profile.id;
   const versionJsonPath = targetPaths.versionJson(input.directory, versionId);
   const versionJson = {
@@ -657,7 +1327,7 @@ function planFabricInstall(input) {
     directory: input.directory,
     system: input.system,
     versionId: input.minecraft.version,
-    category: "fabric-library"
+    category: DownloadCategories.FABRIC_LIBRARY
   });
   return {
     versionJson,
@@ -665,7 +1335,7 @@ function planFabricInstall(input) {
     classpathFiles: plan.classpathFiles,
     versionId
   };
-}
+};
 
 // src/constants/limits.ts
 var EXTRACTION_MAX_FILE_SIZE = 256 * 1024 * 1024;
@@ -673,42 +1343,42 @@ var EXTRACTION_MAX_TOTAL_SIZE = 2 * 1024 * 1024 * 1024;
 var EXTRACTION_MAX_COMPRESSION_RATIO = 200;
 var EXTRACTION_MAX_ENTRY_COUNT = 1e5;
 var FORGE_INSTALLER_MAX_SIZE = 256 * 1024 * 1024;
-async function ensureDir(directory) {
+var ensureDir = async (directory) => {
   try {
     await fs.mkdir(directory, { recursive: true });
   } catch (cause) {
     throw new MinecraftKitError(
-      "FILESYSTEM_WRITE_ERROR",
+      MinecraftKitErrorCodes.FILESYSTEM_WRITE_ERROR,
       `Failed to create directory: ${directory}`,
       { cause, context: { filePath: directory } }
     );
   }
-}
-async function fileExists(filePath) {
+};
+var fileExists = async (filePath) => {
   try {
     const stat = await fs.stat(filePath);
     return stat.isFile();
   } catch {
     return false;
   }
-}
-async function dirExists(filePath) {
+};
+var dirExists = async (filePath) => {
   try {
     const stat = await fs.stat(filePath);
     return stat.isDirectory();
   } catch {
     return false;
   }
-}
-async function fileSize(filePath) {
+};
+var fileSize = async (filePath) => {
   try {
     const stat = await fs.stat(filePath);
     return stat.size;
   } catch {
     return -1;
   }
-}
-async function atomicWrite(target, data) {
+};
+var atomicWrite = async (target, data) => {
   await ensureDir(path.dirname(target));
   const tmp = `${target}.${crypto2.randomBytes(4).toString("hex")}.tmp`;
   try {
@@ -723,31 +1393,39 @@ async function atomicWrite(target, data) {
       await fs.unlink(tmp);
     } catch {
     }
-    throw new MinecraftKitError("FILESYSTEM_WRITE_ERROR", `Failed to write file: ${target}`, {
-      cause,
-      context: { filePath: target }
-    });
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.FILESYSTEM_WRITE_ERROR,
+      `Failed to write file: ${target}`,
+      {
+        cause,
+        context: { filePath: target }
+      }
+    );
   }
-}
-async function readText(filePath) {
+};
+var readText = async (filePath) => {
   try {
     return await fs.readFile(filePath, "utf8");
   } catch (cause) {
-    throw new MinecraftKitError("FILESYSTEM_READ_ERROR", `Failed to read file: ${filePath}`, {
-      cause,
-      context: { filePath }
-    });
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.FILESYSTEM_READ_ERROR,
+      `Failed to read file: ${filePath}`,
+      {
+        cause,
+        context: { filePath }
+      }
+    );
   }
-}
-async function listChildDirectories(directory) {
+};
+var listChildDirectories = async (directory) => {
   try {
     const entries = await fs.readdir(directory, { withFileTypes: true });
     return entries.filter((e) => e.isDirectory()).map((e) => e.name);
   } catch {
     return [];
   }
-}
-async function chmodExecutable(filePath) {
+};
+var chmodExecutable = async (filePath) => {
   if (process.platform === "win32") {
     return;
   }
@@ -755,35 +1433,43 @@ async function chmodExecutable(filePath) {
     await fs.chmod(filePath, 493);
   } catch {
   }
-}
-function assertWithinRoot(root, child) {
+};
+var assertWithinRoot = (root, child) => {
   const normalizedRoot = path.resolve(root);
   const normalizedChild = path.resolve(root, child);
   const sep = path.sep;
   if (normalizedChild !== normalizedRoot && !normalizedChild.startsWith(normalizedRoot + sep)) {
-    throw new MinecraftKitError("FILESYSTEM_PATH_TRAVERSAL", `Path escapes root: ${child}`, {
-      context: { filePath: child, rootDirectory: root }
-    });
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.FILESYSTEM_PATH_TRAVERSAL,
+      `Path escapes root: ${child}`,
+      {
+        context: { filePath: child, rootDirectory: root }
+      }
+    );
   }
-}
+};
 
 // src/core/archive.ts
-function openZip(filePath) {
+var openZip = (filePath) => {
   return new Promise((resolve, reject) => {
     yauzl.open(filePath, { lazyEntries: true, autoClose: false }, (err, zipFile) => {
       if (err || !zipFile) {
         reject(
-          new MinecraftKitError("ARCHIVE_INVALID", `Failed to open archive: ${filePath}`, {
-            cause: err,
-            context: { filePath }
-          })
+          new MinecraftKitError(
+            MinecraftKitErrorCodes.ARCHIVE_INVALID,
+            `Failed to open archive: ${filePath}`,
+            {
+              cause: err,
+              context: { filePath }
+            }
+          )
         );
         return;
       }
       resolve(new ZipReader(zipFile, filePath));
     });
   });
-}
+};
 var ZipReader = class {
   constructor(file, filePath) {
     this.file = file;
@@ -801,7 +1487,7 @@ var ZipReader = class {
       count++;
       if (count > EXTRACTION_MAX_ENTRY_COUNT) {
         throw new MinecraftKitError(
-          "ARCHIVE_TOO_LARGE",
+          MinecraftKitErrorCodes.ARCHIVE_TOO_LARGE,
           `Archive contains too many entries: ${this.filePath}`,
           { context: { filePath: this.filePath } }
         );
@@ -833,10 +1519,14 @@ var ZipReader = class {
       const onError = (err) => {
         cleanup();
         reject(
-          new MinecraftKitError("ARCHIVE_INVALID", "Failed to read archive entry", {
-            cause: err,
-            context: { filePath: this.filePath }
-          })
+          new MinecraftKitError(
+            MinecraftKitErrorCodes.ARCHIVE_INVALID,
+            "Failed to read archive entry",
+            {
+              cause: err,
+              context: { filePath: this.filePath }
+            }
+          )
         );
       };
       const cleanup = () => {
@@ -861,14 +1551,14 @@ var ZipReader = class {
       readBuffer: async () => {
         if (entry.uncompressedSize > EXTRACTION_MAX_FILE_SIZE) {
           throw new MinecraftKitError(
-            "ARCHIVE_TOO_LARGE",
+            MinecraftKitErrorCodes.ARCHIVE_TOO_LARGE,
             `Archive entry exceeds size cap: ${name}`,
             { context: { filePath: this.filePath, entryName: name, size: entry.uncompressedSize } }
           );
         }
         if (entry.compressedSize > 0 && entry.uncompressedSize / entry.compressedSize > EXTRACTION_MAX_COMPRESSION_RATIO) {
           throw new MinecraftKitError(
-            "ARCHIVE_TOO_LARGE",
+            MinecraftKitErrorCodes.ARCHIVE_TOO_LARGE,
             `Archive entry exceeds compression-ratio cap: ${name}`,
             { context: { filePath: this.filePath, entryName: name } }
           );
@@ -884,13 +1574,13 @@ var ZipReader = class {
     };
   }
 };
-function openStream(file, entry, archivePath) {
+var openStream = (file, entry, archivePath) => {
   return new Promise((resolve, reject) => {
     file.openReadStream(entry, (err, stream) => {
       if (err || !stream) {
         reject(
           new MinecraftKitError(
-            "ARCHIVE_INVALID",
+            MinecraftKitErrorCodes.ARCHIVE_INVALID,
             `Failed to open archive entry: ${entry.fileName}`,
             { cause: err, context: { filePath: archivePath, entryName: entry.fileName } }
           )
@@ -900,8 +1590,8 @@ function openStream(file, entry, archivePath) {
       resolve(stream);
     });
   });
-}
-async function extractAllToDir(zipPath, targetDir, options = {}) {
+};
+var extractAllToDir = async (zipPath, targetDir, options = {}) => {
   const exclude = options.excludePrefixes ?? ["META-INF/"];
   let fileCount = 0;
   let totalSize = 0;
@@ -917,14 +1607,14 @@ async function extractAllToDir(zipPath, targetDir, options = {}) {
       totalSize += entry.uncompressedSize;
       if (totalSize > EXTRACTION_MAX_TOTAL_SIZE) {
         throw new MinecraftKitError(
-          "ARCHIVE_TOO_LARGE",
+          MinecraftKitErrorCodes.ARCHIVE_TOO_LARGE,
           `Archive total size cap exceeded: ${zipPath}`,
           { context: { filePath: zipPath } }
         );
       }
       if (entry.uncompressedSize > EXTRACTION_MAX_FILE_SIZE) {
         throw new MinecraftKitError(
-          "ARCHIVE_TOO_LARGE",
+          MinecraftKitErrorCodes.ARCHIVE_TOO_LARGE,
           `Archive entry exceeds size cap: ${entry.name}`,
           { context: { filePath: zipPath, entryName: entry.name } }
         );
@@ -941,9 +1631,9 @@ async function extractAllToDir(zipPath, targetDir, options = {}) {
     reader.close();
   }
   return { fileCount };
-}
+};
 var RESERVED_NAME = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\..*)?$/i;
-function assertSafeEntryName(name) {
+var assertSafeEntryName = (name) => {
   if (!name) {
     throw rejectEntry(name, "empty entry name");
   }
@@ -965,15 +1655,15 @@ function assertSafeEntryName(name) {
       throw rejectEntry(name, "trailing dot or whitespace");
     }
   }
-}
-function rejectEntry(name, reason) {
+};
+var rejectEntry = (name, reason) => {
   return new MinecraftKitError(
-    "ARCHIVE_ENTRY_REJECTED",
+    MinecraftKitErrorCodes.ARCHIVE_ENTRY_REJECTED,
     `Archive entry rejected (${reason}): ${name}`,
     { context: { entryName: name, reason } }
   );
-}
-async function readEntryBuffer(zipPath, entryName) {
+};
+var readEntryBuffer = async (zipPath, entryName) => {
   const reader = await openZip(zipPath);
   try {
     const entry = await reader.findEntry(entryName);
@@ -982,19 +1672,23 @@ async function readEntryBuffer(zipPath, entryName) {
   } finally {
     reader.close();
   }
-}
-async function extractSingleEntry(zipPath, entryName, destination) {
+};
+var extractSingleEntry = async (zipPath, entryName, destination) => {
   const buffer = await readEntryBuffer(zipPath, entryName);
   if (!buffer) {
-    throw new MinecraftKitError("ARCHIVE_INVALID", `Archive entry not found: ${entryName}`, {
-      context: { filePath: zipPath, entryName }
-    });
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.ARCHIVE_INVALID,
+      `Archive entry not found: ${entryName}`,
+      {
+        context: { filePath: zipPath, entryName }
+      }
+    );
   }
   await atomicWrite(destination, buffer);
-}
+};
 var MANIFEST_LINE_CONTINUATION = /\r?\n[ \t]/g;
 var MANIFEST_MAIN_CLASS = /^Main-Class:\s*(.+)$/i;
-async function readJarMainClass(zipPath) {
+var readJarMainClass = async (zipPath) => {
   const buf = await readEntryBuffer(zipPath, "META-INF/MANIFEST.MF");
   if (!buf) return void 0;
   const text = buf.toString("utf8").replaceAll(MANIFEST_LINE_CONTINUATION, "");
@@ -1003,10 +1697,10 @@ async function readJarMainClass(zipPath) {
     if (match?.[1]) return match[1].trim();
   }
   return void 0;
-}
+};
 
 // src/core/collections.ts
-function dedupeBy(values, key) {
+var dedupeBy = (values, key) => {
   const seen = /* @__PURE__ */ new Set();
   const result = [];
   for (const value of values) {
@@ -1016,13 +1710,25 @@ function dedupeBy(values, key) {
     result.push(value);
   }
   return result;
-}
-function dedupe(values) {
+};
+var dedupe = (values) => {
   return dedupeBy(values, (v) => v);
-}
+};
+
+// src/core/abort.ts
+var assertNotAborted = (signal, message) => {
+  if (signal?.aborted) {
+    throw new MinecraftKitError(MinecraftKitErrorCodes.LAUNCH_ABORTED, message);
+  }
+};
+var checkpoint = async (sources, message = "Operation aborted by signal") => {
+  assertNotAborted(sources.signal, message);
+  await sources.pauseController?.waitWhilePaused();
+  assertNotAborted(sources.signal, message);
+};
 
 // src/core/retry.ts
-function abortableSleep(ms, signal) {
+var abortableSleep = (ms, signal) => {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
       reject(toAbortError(signal));
@@ -1038,13 +1744,13 @@ function abortableSleep(ms, signal) {
     };
     signal?.addEventListener("abort", onAbort, { once: true });
   });
-}
-function toAbortError(signal) {
-  return new MinecraftKitError("NETWORK_ABORTED", "Operation aborted", {
+};
+var toAbortError = (signal) => {
+  return new MinecraftKitError(MinecraftKitErrorCodes.NETWORK_ABORTED, "Operation aborted", {
     context: { reason: signal?.reason }
   });
-}
-async function withRetry(op, isRetryable, options = {}) {
+};
+var withRetry = async (op, isRetryable, options = {}) => {
   const max = options.maxAttempts ?? HTTP_RETRY_MAX;
   const base = options.baseMs ?? HTTP_RETRY_BACKOFF_BASE_MS;
   const cap = options.capMs ?? HTTP_RETRY_BACKOFF_CAP_MS;
@@ -1069,8 +1775,8 @@ async function withRetry(op, isRetryable, options = {}) {
     }
   }
   throw lastError ?? new Error("withRetry exhausted attempts");
-}
-function isHttpRetryable(error) {
+};
+var isHttpRetryable = (error) => {
   if (!isMinecraftKitError(error)) {
     return false;
   }
@@ -1083,15 +1789,45 @@ function isHttpRetryable(error) {
     return status === 0;
   }
   return false;
-}
+};
+
+// src/types/events.ts
+var EventTypes = {
+  INSTALL_PHASE_CHANGED: "install:phase-changed",
+  DOWNLOAD_STARTED: "download:started",
+  DOWNLOAD_PROGRESS: "download:progress",
+  DOWNLOAD_SKIPPED: "download:skipped",
+  DOWNLOAD_COMPLETED: "download:completed",
+  DOWNLOAD_FAILED: "download:failed",
+  INTEGRITY_VERIFIED: "integrity:verified",
+  INTEGRITY_MISMATCH: "integrity:mismatch",
+  ARCHIVE_EXTRACTED: "archive:extracted",
+  FORGE_PROCESSOR_STARTED: "forge:processor-started",
+  FORGE_PROCESSOR_COMPLETED: "forge:processor-completed",
+  FORGE_PROCESSOR_OUTPUT_VERIFIED: "forge:processor-output-verified",
+  VERIFY_FILE_CHECKED: "verify:file-checked",
+  VERIFY_COMPLETED: "verify:completed",
+  REPAIR_PHASE_CHANGED: "repair:phase-changed",
+  LAUNCH_STARTING: "launch:starting",
+  LAUNCH_STARTED: "launch:started",
+  LAUNCH_STDOUT: "launch:stdout",
+  LAUNCH_STDERR: "launch:stderr",
+  LAUNCH_EXITED: "launch:exited",
+  LAUNCH_ABORTED: "launch:aborted"
+};
 
 // src/http/download.ts
-async function downloadFile(http, input) {
-  const fileRef = { url: input.url, target: input.target, category: input.category };
+var downloadFile = async (http, input) => {
+  assertSafeDownloadUrl(input.url, input.hostAllowList);
+  const fileRef = {
+    url: input.url,
+    target: input.target,
+    ...input.category !== void 0 ? { category: input.category } : {}
+  };
   if (input.expectedSha1 !== void 0) {
     const existing = await checkExistingFile(input.target, input.expectedSha1, input.expectedSize);
     if (existing.matches) {
-      input.onEvent?.({ type: "download:skipped", file: fileRef });
+      input.onEvent?.({ type: EventTypes.DOWNLOAD_SKIPPED, file: fileRef });
       return { bytesDownloaded: 0, sha1: existing.sha1, skipped: true };
     }
   }
@@ -1100,29 +1836,32 @@ async function downloadFile(http, input) {
   return withRetry(
     async () => {
       input.onEvent?.({
-        type: "download:started",
+        type: EventTypes.DOWNLOAD_STARTED,
         file: fileRef,
         expectedSize: input.expectedSize ?? 0
       });
       const startedAt = Date.now();
       let bytesDownloaded = 0;
       const hash = crypto2.createHash("sha1");
-      const response = await http.request(input.url, { signal: input.signal });
+      const response = await http.request(input.url, {
+        ...input.signal !== void 0 ? { signal: input.signal } : {}
+      });
       const contentLength = Number(response.headers["content-length"] ?? "0");
       const total = input.expectedSize ?? (Number.isFinite(contentLength) ? contentLength : 0);
       const sourceIterable = response.stream();
       const counting = (async function* () {
         for await (const chunk of sourceIterable) {
-          if (input.pauseController?.paused) {
-            await input.pauseController.waitWhilePaused();
-          }
-          if (input.signal?.aborted) {
-            throw new MinecraftKitError("LAUNCH_ABORTED", "Download aborted by signal");
-          }
+          await checkpoint(
+            {
+              ...input.signal !== void 0 ? { signal: input.signal } : {},
+              ...input.pauseController !== void 0 ? { pauseController: input.pauseController } : {}
+            },
+            "Download aborted by signal"
+          );
           bytesDownloaded += chunk.byteLength;
           hash.update(chunk);
           input.onEvent?.({
-            type: "download:progress",
+            type: EventTypes.DOWNLOAD_PROGRESS,
             file: fileRef,
             bytesDownloaded,
             totalBytes: total
@@ -1135,7 +1874,7 @@ async function downloadFile(http, input) {
       } catch (cause) {
         await safeUnlink(tmp);
         throw new MinecraftKitError(
-          "FILESYSTEM_WRITE_ERROR",
+          MinecraftKitErrorCodes.FILESYSTEM_WRITE_ERROR,
           `Failed to write download: ${input.target}`,
           { cause, context: { filePath: input.target, url: input.url } }
         );
@@ -1143,50 +1882,58 @@ async function downloadFile(http, input) {
       const computedSha1 = hash.digest("hex");
       if (input.expectedSize !== void 0 && bytesDownloaded !== input.expectedSize) {
         await safeUnlink(tmp);
-        throw new MinecraftKitError("INTEGRITY_SIZE_MISMATCH", `Size mismatch for ${input.url}`, {
-          context: {
-            url: input.url,
-            expectedSize: input.expectedSize,
-            actualSize: bytesDownloaded
+        throw new MinecraftKitError(
+          MinecraftKitErrorCodes.INTEGRITY_SIZE_MISMATCH,
+          `Size mismatch for ${input.url}`,
+          {
+            context: {
+              url: input.url,
+              expectedSize: input.expectedSize,
+              actualSize: bytesDownloaded
+            }
           }
-        });
+        );
       }
       if (input.expectedSha1 !== void 0 && computedSha1 !== input.expectedSha1) {
         await safeUnlink(tmp);
         input.onEvent?.({
-          type: "integrity:mismatch",
+          type: EventTypes.INTEGRITY_MISMATCH,
           file: fileRef,
           algorithm: "sha1",
           expected: input.expectedSha1,
           actual: computedSha1
         });
-        throw new MinecraftKitError("INTEGRITY_HASH_MISMATCH", `SHA-1 mismatch for ${input.url}`, {
-          context: {
-            url: input.url,
-            expectedHash: input.expectedSha1,
-            actualHash: computedSha1
+        throw new MinecraftKitError(
+          MinecraftKitErrorCodes.INTEGRITY_HASH_MISMATCH,
+          `SHA-1 mismatch for ${input.url}`,
+          {
+            context: {
+              url: input.url,
+              expectedHash: input.expectedSha1,
+              actualHash: computedSha1
+            }
           }
-        });
+        );
       }
       try {
         await fs.rename(tmp, input.target);
       } catch (cause) {
         await safeUnlink(tmp);
         throw new MinecraftKitError(
-          "FILESYSTEM_WRITE_ERROR",
+          MinecraftKitErrorCodes.FILESYSTEM_WRITE_ERROR,
           `Failed to finalize download: ${input.target}`,
           { cause, context: { filePath: input.target } }
         );
       }
       input.onEvent?.({
-        type: "download:completed",
+        type: EventTypes.DOWNLOAD_COMPLETED,
         file: fileRef,
         durationMs: Date.now() - startedAt,
         bytes: bytesDownloaded
       });
       if (input.expectedSha1 !== void 0) {
         input.onEvent?.({
-          type: "integrity:verified",
+          type: EventTypes.INTEGRITY_VERIFIED,
           file: fileRef,
           algorithm: "sha1",
           hash: computedSha1
@@ -1199,7 +1946,7 @@ async function downloadFile(http, input) {
       ...input.signal !== void 0 ? { signal: input.signal } : {},
       onAttemptFailed: (error, attempt) => {
         input.onEvent?.({
-          type: "download:failed",
+          type: EventTypes.DOWNLOAD_FAILED,
           file: fileRef,
           error: error instanceof Error ? error : new Error(String(error)),
           willRetry: isHttpRetryable(error) && attempt < HTTP_RETRY_MAX - 1
@@ -1207,8 +1954,8 @@ async function downloadFile(http, input) {
       }
     }
   );
-}
-async function checkExistingFile(target, expectedSha1, expectedSize) {
+};
+var checkExistingFile = async (target, expectedSha1, expectedSize) => {
   let stat;
   try {
     stat = await fs.stat(target);
@@ -1224,21 +1971,60 @@ async function checkExistingFile(target, expectedSha1, expectedSize) {
   const buf = await fs.readFile(target);
   const sha1 = crypto2.createHash("sha1").update(buf).digest("hex");
   return { matches: sha1 === expectedSha1, sha1 };
-}
-async function safeUnlink(filePath) {
+};
+var safeUnlink = async (filePath) => {
   try {
     await fs.unlink(filePath);
   } catch {
   }
-}
+};
+var assertSafeDownloadUrl = (url, allowList) => {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.INVALID_INPUT,
+      `Download URL is not parseable: ${url}`,
+      {
+        context: { url }
+      }
+    );
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.INVALID_INPUT,
+      `Download URL must use http(s); refusing scheme ${parsed.protocol}`,
+      { context: { url, scheme: parsed.protocol } }
+    );
+  }
+  if (allowList !== void 0 && !matchesHostAllowList(parsed.hostname, allowList)) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.INVALID_INPUT,
+      `Download URL host is not in the allow-list: ${parsed.hostname}`,
+      { context: { url, host: parsed.hostname } }
+    );
+  }
+};
+var matchesHostAllowList = (hostname, allowList) => {
+  const host = hostname.toLowerCase();
+  return allowList.some((entry) => matchesHostEntry(host, entry.toLowerCase()));
+};
+var matchesHostEntry = (host, entry) => {
+  if (entry.startsWith("*.")) {
+    const suffix = entry.slice(1);
+    return host === entry.slice(2) || host.endsWith(suffix);
+  }
+  return host === entry;
+};
 
 // src/install/forge-install.ts
-async function planForgeInstall(input) {
+var planForgeInstall = async (input) => {
   const installerPath = targetPaths.forgeInstaller(input.directory, input.loader.fullVersion);
   await downloadFile(input.http, {
     url: input.loader.installerUrl,
     target: installerPath,
-    category: "forge-installer",
+    category: DownloadCategories.FORGE_INSTALLER,
     ...input.signal !== void 0 ? { signal: input.signal } : {},
     ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
   });
@@ -1246,7 +2032,7 @@ async function planForgeInstall(input) {
     kind: InstallActionKinds.DOWNLOAD_FILE,
     url: input.loader.installerUrl,
     target: installerPath,
-    category: "forge-installer"
+    category: DownloadCategories.FORGE_INSTALLER
   };
   const profile = await readJsonEntry(installerPath, "install_profile.json");
   const versionRelative = profile.json.startsWith("/") ? profile.json.slice(1) : profile.json;
@@ -1262,14 +2048,14 @@ async function planForgeInstall(input) {
     directory: input.directory,
     system: input.system,
     versionId: input.minecraft.version,
-    category: "forge-library"
+    category: DownloadCategories.FORGE_LIBRARY
   });
   const versionLibraries = planLibraryDownloads({
     libraries: version.libraries,
     directory: input.directory,
     system: input.system,
     versionId: version.id,
-    category: "forge-library"
+    category: DownloadCategories.FORGE_LIBRARY
   });
   const dedupedDownloads = dedupeBy(
     [...installerLibraries.downloads, ...versionLibraries.downloads],
@@ -1304,27 +2090,23 @@ async function planForgeInstall(input) {
     profile,
     version
   };
-}
-async function readJsonEntry(zipPath, entryName) {
+};
+var readJsonEntry = async (zipPath, entryName) => {
   const buffer = await readEntryBuffer(zipPath, entryName);
   if (!buffer) {
     throw new MinecraftKitError(
-      "FORGE_INSTALLER_INVALID",
+      MinecraftKitErrorCodes.FORGE_INSTALLER_INVALID,
       `Forge installer is missing required entry: ${entryName}`,
       { context: { filePath: zipPath, entryName } }
     );
   }
-  try {
-    return JSON.parse(buffer.toString("utf8"));
-  } catch (cause) {
-    throw new MinecraftKitError(
-      "FORGE_INSTALLER_INVALID",
-      `Forge installer entry is not valid JSON: ${entryName}`,
-      { cause, context: { filePath: zipPath, entryName } }
-    );
-  }
-}
-async function extractInstallerMavenEntries(installerPath, directory) {
+  return parseJsonStrict(buffer.toString("utf8"), {
+    code: MinecraftKitErrorCodes.FORGE_INSTALLER_INVALID,
+    message: `Forge installer entry is not valid JSON: ${entryName}`,
+    context: { filePath: zipPath, entryName }
+  });
+};
+var extractInstallerMavenEntries = async (installerPath, directory) => {
   const reader = await openZip(installerPath);
   try {
     for await (const entry of reader.entries()) {
@@ -1337,16 +2119,16 @@ async function extractInstallerMavenEntries(installerPath, directory) {
   } finally {
     reader.close();
   }
-}
-async function resolveProfileData(input) {
+};
+var resolveProfileData = async (input) => {
   const tokens = {};
   for (const [key, sided] of Object.entries(input.profile.data)) {
     const raw = sided.client;
     tokens[key] = await resolveDataValue(raw, input.installerPath, input.directory);
   }
   return { tokens };
-}
-async function resolveDataValue(raw, installerPath, directory) {
+};
+var resolveDataValue = async (raw, installerPath, directory) => {
   if (raw.startsWith("[") && raw.endsWith("]")) {
     const coord = raw.slice(1, -1);
     const relativePath = mavenRelativePathFor(coord);
@@ -1365,8 +2147,8 @@ async function resolveDataValue(raw, installerPath, directory) {
     return { value: destination, isPath: true };
   }
   return { value: raw, isPath: false };
-}
-async function buildProcessorActions(input) {
+};
+var buildProcessorActions = async (input) => {
   const builtIns = {
     SIDE: { value: "client", isPath: false },
     MINECRAFT_JAR: {
@@ -1399,12 +2181,12 @@ async function buildProcessorActions(input) {
     index++;
   }
   return actions;
-}
-function processorAppliesToClient(processor) {
+};
+var processorAppliesToClient = (processor) => {
   if (!processor.sides || processor.sides.length === 0) return true;
   return processor.sides.includes("client");
-}
-function buildProcessorAction(input) {
+};
+var buildProcessorAction = (input) => {
   const jarPath = path.join(
     targetPaths.librariesDir(input.directory),
     mavenRelativePathFor(input.processor.jar)
@@ -1431,26 +2213,30 @@ function buildProcessorAction(input) {
     args,
     outputs
   };
-}
-function substituteToken(raw, tokens) {
+};
+var substituteToken = (raw, tokens) => {
   if (raw.startsWith("[") && raw.endsWith("]")) {
     return path.join(...mavenRelativePathFor(raw.slice(1, -1)).split("/"));
   }
   return raw.replaceAll(/\{([A-Z0-9_]+)\}/g, (match, key) => {
     const token = tokens[key];
     if (token === void 0) {
-      throw new MinecraftKitError("FORGE_INSTALLER_INVALID", `Unknown processor token: ${match}`, {
-        context: { token: key }
-      });
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.FORGE_INSTALLER_INVALID,
+        `Unknown processor token: ${match}`,
+        {
+          context: { token: key }
+        }
+      );
     }
     return token.value;
   });
-}
-function stripLiteralPrefix(value) {
+};
+var stripLiteralPrefix = (value) => {
   const stripped = value.startsWith("'") ? value.slice(1) : value;
   return stripped.endsWith("'") ? stripped.slice(0, -1) : stripped;
-}
-async function planRuntimeDownloads(input) {
+};
+var planRuntimeDownloads = async (input) => {
   const manifest = await fetchJson(input.http, input.cache, {
     url: input.runtime.manifestUrl,
     cacheKey: `runtime-manifest:${input.runtime.component}:${input.runtime.platformKey}:${input.runtime.manifestSha1}`,
@@ -1471,14 +2257,14 @@ async function planRuntimeDownloads(input) {
       target,
       expectedSha1: entry.downloads.raw.sha1,
       expectedSize: entry.downloads.raw.size,
-      category: "runtime-file"
+      category: DownloadCategories.RUNTIME_FILE
     });
   }
   return { actions, manifest };
-}
+};
 
 // src/install/planner.ts
-async function planInstall(input) {
+var planInstall = async (input) => {
   const { target } = input;
   const actions = [];
   actions.push({
@@ -1487,7 +2273,7 @@ async function planInstall(input) {
     target: targetPaths.versionJar(target.directory, target.minecraft.version),
     expectedSha1: target.minecraft.manifest.downloads.client.sha1,
     expectedSize: target.minecraft.manifest.downloads.client.size,
-    category: "client-jar"
+    category: DownloadCategories.CLIENT_JAR
   });
   actions.push({
     kind: InstallActionKinds.WRITE_VERSION_JSON,
@@ -1500,7 +2286,7 @@ async function planInstall(input) {
     directory: target.directory,
     system: target.runtime.system,
     versionId: target.minecraft.version,
-    category: "library"
+    category: DownloadCategories.LIBRARY
   });
   actions.push(...vanillaLibraries.downloads);
   actions.push(...vanillaLibraries.nativeExtractions);
@@ -1520,7 +2306,7 @@ async function planInstall(input) {
       target: targetPaths.loggingConfig(target.directory, logging.file.id),
       expectedSha1: logging.file.sha1,
       expectedSize: logging.file.size,
-      category: "logging-config"
+      category: DownloadCategories.LOGGING_CONFIG
     });
   }
   const runtimePlan = await planRuntimeDownloads({
@@ -1570,7 +2356,7 @@ async function planInstall(input) {
     totalActions: actions.length,
     totalBytes
   };
-}
+};
 
 // node_modules/yocto-queue/index.js
 var Node = class {
@@ -1673,22 +2459,126 @@ function pLimit(concurrency) {
   const generator = (function_, ...arguments_) => new Promise((resolve) => {
     enqueue(function_, resolve, arguments_);
   });
-  Object.defineProperties(generator, {
-    activeCount: {
-      get: () => activeCount
-    },
-    pendingCount: {
-      get: () => queue.size
-    },
-    clearQueue: {
-      value() {
-        queue.clear();
-      }
+  Object.defineProperties(generator, {
+    activeCount: {
+      get: () => activeCount
+    },
+    pendingCount: {
+      get: () => queue.size
+    },
+    clearQueue: {
+      value() {
+        queue.clear();
+      }
+    }
+  });
+  return generator;
+}
+var sha1OfFile = async (filePath) => {
+  const hash = crypto2.createHash("sha1");
+  const stream = createReadStream(filePath);
+  try {
+    await new Promise((resolve, reject) => {
+      stream.on("data", (chunk) => hash.update(chunk));
+      stream.on("end", resolve);
+      stream.on("error", reject);
+    });
+  } finally {
+    if (!stream.destroyed) stream.destroy();
+  }
+  return hash.digest("hex");
+};
+
+// src/install/processor.ts
+var runProcessor = async (input) => {
+  const startedAt = Date.now();
+  const mainClass = await resolveProcessorMainClass(input.action);
+  emit(input, { type: EventTypes.FORGE_PROCESSOR_STARTED, index: input.action.index, mainClass });
+  const exit = await spawnProcessor(input, mainClass);
+  if (exit.code !== 0) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.FORGE_PROCESSOR_FAILED,
+      `Forge processor exited with code ${exit.code ?? "(signal)"}: ${mainClass}`,
+      {
+        context: {
+          mainClass,
+          stderr: exit.stderr,
+          ...exit.code !== null ? { exitCode: exit.code } : {}
+        }
+      }
+    );
+  }
+  input.onEvent?.({
+    type: EventTypes.FORGE_PROCESSOR_COMPLETED,
+    processor: { index: input.action.index, mainClass },
+    exitCode: exit.code ?? 0,
+    durationMs: Date.now() - startedAt
+  });
+  await verifyProcessorOutputs(input, mainClass);
+};
+var resolveProcessorMainClass = async (action) => {
+  const processorJar = action.classpath[0];
+  if (processorJar === void 0) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.FORGE_INSTALLER_INVALID,
+      "Forge processor has an empty classpath",
+      { context: { processorIndex: action.index } }
+    );
+  }
+  const mainClass = await readJarMainClass(processorJar);
+  if (!mainClass) {
+    throw new MinecraftKitError(
+      MinecraftKitErrorCodes.FORGE_INSTALLER_INVALID,
+      `Forge processor jar has no Main-Class: ${processorJar}`,
+      { context: { filePath: processorJar } }
+    );
+  }
+  return mainClass;
+};
+var spawnProcessor = async (input, mainClass) => {
+  const classpathSeparator = process.platform === "win32" ? ";" : ":";
+  const args = [
+    "-cp",
+    input.action.classpath.join(classpathSeparator),
+    mainClass,
+    ...input.action.args
+  ];
+  const stderrTail = [];
+  const child = input.spawner.spawn(input.javaPath, args, { cwd: process.cwd() });
+  child.stdout.on("data", () => {
+  });
+  child.stderr.on("data", (line) => {
+    if (stderrTail.length >= MAX_PROCESSOR_STDERR_LINES) stderrTail.shift();
+    stderrTail.push(line);
+  });
+  const exit = await child.exited;
+  return { code: exit.code, stderr: stderrTail.join("\n") };
+};
+var verifyProcessorOutputs = async (input, mainClass) => {
+  for (const [outputPath, expectedSha1] of Object.entries(input.action.outputs)) {
+    const sha1 = await sha1OfFile(outputPath);
+    if (sha1 !== expectedSha1) {
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.FORGE_PROCESSOR_FAILED,
+        `Processor output hash mismatch: ${outputPath}`,
+        { context: { filePath: outputPath, expectedHash: expectedSha1, actualHash: sha1 } }
+      );
     }
+    input.onEvent?.({
+      type: EventTypes.FORGE_PROCESSOR_OUTPUT_VERIFIED,
+      processor: { index: input.action.index, mainClass },
+      path: outputPath
+    });
+  }
+};
+var emit = (input, event) => {
+  input.onEvent?.({
+    type: event.type,
+    processor: { index: event.index, mainClass: event.mainClass },
+    total: input.total
   });
-  return generator;
-}
-async function materializeRuntimeExtras(input) {
+};
+var materializeRuntimeExtras = async (input) => {
   const root = targetPaths.runtimeRoot(
     input.directory,
     input.runtime.component,
@@ -1707,20 +2597,20 @@ async function materializeRuntimeExtras(input) {
       });
     }
   }
-}
-async function unlinkIfPresent(target) {
+};
+var unlinkIfPresent = async (target) => {
   try {
     await fs.unlink(target);
   } catch (cause) {
     if (isNotFound(cause)) return;
     throw new MinecraftKitError(
-      "FILESYSTEM_WRITE_ERROR",
+      MinecraftKitErrorCodes.FILESYSTEM_WRITE_ERROR,
       `Failed to remove stale runtime entry: ${target}`,
       { cause, context: { filePath: target } }
     );
   }
-}
-async function createLinkOrCopy(root, relativePath, linkTarget, destination) {
+};
+var createLinkOrCopy = async (root, relativePath, linkTarget, destination) => {
   try {
     await fs.symlink(linkTarget, destination);
     return;
@@ -1730,7 +2620,7 @@ async function createLinkOrCopy(root, relativePath, linkTarget, destination) {
       await fs.copyFile(absoluteSource, destination);
     } catch (copyError) {
       throw new MinecraftKitError(
-        "FILESYSTEM_WRITE_ERROR",
+        MinecraftKitErrorCodes.FILESYSTEM_WRITE_ERROR,
         `Failed to materialize runtime entry: ${destination}`,
         {
           cause: copyError,
@@ -1743,283 +2633,209 @@ async function createLinkOrCopy(root, relativePath, linkTarget, destination) {
       );
     }
   }
-}
-function isNotFound(error) {
+};
+var isNotFound = (error) => {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
-}
-function errorMessage(error) {
+};
+var errorMessage = (error) => {
   return error instanceof Error ? error.message : String(error);
-}
+};
 
 // src/install/runner.ts
 var DOWNLOAD_GROUPS = [
-  { categories: ["runtime-file"], phase: InstallPhases.INSTALLING_RUNTIME },
-  { categories: ["client-jar"], phase: InstallPhases.DOWNLOADING_CLIENT_JAR },
-  { categories: ["library"], phase: InstallPhases.DOWNLOADING_LIBRARIES },
-  { categories: ["asset-index"], phase: InstallPhases.DOWNLOADING_ASSET_INDEX },
-  { categories: ["asset"], phase: InstallPhases.DOWNLOADING_ASSETS },
-  { categories: ["logging-config"], phase: InstallPhases.WRITING_FILES },
-  { categories: ["fabric-library"], phase: InstallPhases.INSTALLING_FABRIC },
-  { categories: ["forge-installer", "forge-library"], phase: InstallPhases.INSTALLING_FORGE }
+  { categories: [DownloadCategories.RUNTIME_FILE], phase: InstallPhases.INSTALLING_RUNTIME },
+  { categories: [DownloadCategories.CLIENT_JAR], phase: InstallPhases.DOWNLOADING_CLIENT_JAR },
+  { categories: [DownloadCategories.LIBRARY], phase: InstallPhases.DOWNLOADING_LIBRARIES },
+  { categories: [DownloadCategories.ASSET_INDEX], phase: InstallPhases.DOWNLOADING_ASSET_INDEX },
+  { categories: [DownloadCategories.ASSET], phase: InstallPhases.DOWNLOADING_ASSETS },
+  { categories: [DownloadCategories.LOGGING_CONFIG], phase: InstallPhases.WRITING_FILES },
+  { categories: [DownloadCategories.FABRIC_LIBRARY], phase: InstallPhases.INSTALLING_FABRIC },
+  {
+    categories: [DownloadCategories.FORGE_INSTALLER, DownloadCategories.FORGE_LIBRARY],
+    phase: InstallPhases.INSTALLING_FORGE
+  }
 ];
-async function runInstall(input) {
+var runInstall = async (input) => {
   const startedAt = Date.now();
-  let bytesDownloaded = 0;
-  let actionsCompleted = 0;
-  let actionsSkipped = 0;
-  const onEvent = input.onEvent;
+  const counters = { bytesDownloaded: 0, actionsCompleted: 0, actionsSkipped: 0 };
+  const ctx = createContext(input, counters);
+  ctx.enterPhase(InstallPhases.PLANNING);
+  const plannedActions = partitionActions(input);
+  await runDownloadsStage(ctx, plannedActions.downloads);
+  await runWritesStage(ctx, plannedActions.writes);
+  await runNativesStage(ctx, plannedActions.natives);
+  await runRuntimeStage(ctx);
+  await runProcessorsStage(ctx, plannedActions.processors);
+  ctx.enterPhase(InstallPhases.COMPLETED);
+  return {
+    targetId: input.plan.targetId,
+    bytesDownloaded: counters.bytesDownloaded,
+    actionsCompleted: counters.actionsCompleted,
+    actionsSkipped: counters.actionsSkipped,
+    durationMs: Date.now() - startedAt
+  };
+};
+var createContext = (input, counters) => {
   let currentPhase = null;
   const enterPhase = (phase) => {
     if (phase === currentPhase) return;
-    onEvent?.({ type: "install:phase-changed", phase, previous: currentPhase });
+    input.onEvent?.({ type: EventTypes.INSTALL_PHASE_CHANGED, phase, previous: currentPhase });
     currentPhase = phase;
   };
-  const checkpoint = async () => {
-    if (input.signal?.aborted) {
-      throw new MinecraftKitError("LAUNCH_ABORTED", "Install aborted by signal");
-    }
-    await input.pauseController?.waitWhilePaused();
-    if (input.signal?.aborted) {
-      throw new MinecraftKitError("LAUNCH_ABORTED", "Install aborted by signal");
-    }
+  const checkpoint2 = () => checkpoint(
+    {
+      ...input.signal !== void 0 ? { signal: input.signal } : {},
+      ...input.pauseController !== void 0 ? { pauseController: input.pauseController } : {}
+    },
+    "Install aborted by signal"
+  );
+  return {
+    input,
+    counters,
+    checkpoint: checkpoint2,
+    enterPhase,
+    limit: pLimit(input.concurrency ?? DOWNLOAD_CONCURRENCY)
+  };
+};
+var partitionActions = (input) => {
+  const filter = input.actionCategories;
+  return {
+    downloads: input.plan.actions.filter(isDownload).filter((a) => filter ? filter.has(a.category) : true),
+    natives: input.plan.actions.filter(isNative),
+    writes: input.plan.actions.filter(isWrite),
+    processors: input.plan.actions.filter(isProcessor)
   };
-  const categoryFilter = input.actionCategories;
-  const downloads = input.plan.actions.filter(isDownload).filter((a) => categoryFilter ? categoryFilter.has(a.category) : true);
-  const natives = input.plan.actions.filter(isNative);
-  const writeActions = input.plan.actions.filter(isWrite);
-  const processors = input.plan.actions.filter(isProcessor);
-  enterPhase(InstallPhases.PLANNING);
-  const limit = pLimit(input.concurrency ?? DOWNLOAD_CONCURRENCY);
+};
+var runDownloadsStage = async (ctx, downloads) => {
+  if (downloads.length === 0) return;
   for (const group of DOWNLOAD_GROUPS) {
     const groupActions = downloads.filter((action) => group.categories.includes(action.category));
     if (groupActions.length === 0) continue;
-    await checkpoint();
-    enterPhase(group.phase);
-    await Promise.all(
-      groupActions.map(
-        (action) => limit(async () => {
-          await checkpoint();
-          const result = await downloadFile(input.http, {
-            url: action.url,
-            target: action.target,
-            ...action.expectedSha1 !== void 0 ? { expectedSha1: action.expectedSha1 } : {},
-            ...action.expectedSize !== void 0 ? { expectedSize: action.expectedSize } : {},
-            ...action.category !== void 0 ? { category: action.category } : {},
-            ...input.signal !== void 0 ? { signal: input.signal } : {},
-            ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {},
-            ...input.pauseController !== void 0 ? { pauseController: input.pauseController } : {}
-          });
-          bytesDownloaded += result.bytesDownloaded;
-          if (result.skipped) actionsSkipped++;
-          actionsCompleted++;
-        })
-      )
-    );
+    await ctx.checkpoint();
+    ctx.enterPhase(group.phase);
+    await runDownloadGroup(ctx, groupActions);
   }
   const ungrouped = downloads.filter(
     (action) => !DOWNLOAD_GROUPS.some((g) => g.categories.includes(action.category))
   );
   if (ungrouped.length > 0) {
-    await checkpoint();
-    enterPhase(InstallPhases.DOWNLOADING_LIBRARIES);
-    await Promise.all(
-      ungrouped.map(
-        (action) => limit(async () => {
-          await checkpoint();
-          const result = await downloadFile(input.http, {
-            url: action.url,
-            target: action.target,
-            ...action.expectedSha1 !== void 0 ? { expectedSha1: action.expectedSha1 } : {},
-            ...action.expectedSize !== void 0 ? { expectedSize: action.expectedSize } : {},
-            ...action.category !== void 0 ? { category: action.category } : {},
-            ...input.signal !== void 0 ? { signal: input.signal } : {},
-            ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {},
-            ...input.pauseController !== void 0 ? { pauseController: input.pauseController } : {}
-          });
-          bytesDownloaded += result.bytesDownloaded;
-          if (result.skipped) actionsSkipped++;
-          actionsCompleted++;
-        })
-      )
-    );
-  }
-  if (writeActions.length > 0) {
-    await checkpoint();
-    enterPhase(InstallPhases.WRITING_FILES);
-    for (const action of writeActions) {
-      await checkpoint();
-      await atomicWrite(action.path, action.content);
-      actionsCompleted++;
-    }
+    await ctx.checkpoint();
+    ctx.enterPhase(InstallPhases.DOWNLOADING_LIBRARIES);
+    await runDownloadGroup(ctx, ungrouped);
   }
-  if (natives.length > 0) {
-    await checkpoint();
-    enterPhase(InstallPhases.EXTRACTING_NATIVES);
-    for (const action of natives) {
-      await checkpoint();
-      const { fileCount } = await extractAllToDir(action.source, action.destination, {
-        excludePrefixes: action.exclude
-      });
-      input.onEvent?.({
-        type: "archive:extracted",
-        archive: action.source,
-        target: action.destination,
-        fileCount
-      });
-      actionsCompleted++;
-    }
+};
+var runDownloadGroup = async (ctx, groupActions) => {
+  await Promise.all(
+    groupActions.map(
+      (action) => ctx.limit(async () => {
+        await ctx.checkpoint();
+        const result = await downloadFile(ctx.input.http, {
+          url: action.url,
+          target: action.target,
+          ...action.expectedSha1 !== void 0 ? { expectedSha1: action.expectedSha1 } : {},
+          ...action.expectedSize !== void 0 ? { expectedSize: action.expectedSize } : {},
+          ...action.category !== void 0 ? { category: action.category } : {},
+          ...ctx.input.signal !== void 0 ? { signal: ctx.input.signal } : {},
+          ...ctx.input.onEvent !== void 0 ? { onEvent: ctx.input.onEvent } : {},
+          ...ctx.input.pauseController !== void 0 ? { pauseController: ctx.input.pauseController } : {}
+        });
+        ctx.counters.bytesDownloaded += result.bytesDownloaded;
+        if (result.skipped) ctx.counters.actionsSkipped++;
+        ctx.counters.actionsCompleted++;
+      })
+    )
+  );
+};
+var runWritesStage = async (ctx, writes) => {
+  if (writes.length === 0) return;
+  await ctx.checkpoint();
+  ctx.enterPhase(InstallPhases.WRITING_FILES);
+  for (const action of writes) {
+    await ctx.checkpoint();
+    await atomicWrite(action.path, action.content);
+    ctx.counters.actionsCompleted++;
   }
-  if (input.plan.target.runtime !== void 0) {
-    await checkpoint();
-    enterPhase(InstallPhases.INSTALLING_RUNTIME);
-    const runtimePlan = await planRuntimeDownloads({
-      runtime: input.plan.target.runtime,
-      directory: input.plan.directory,
-      http: input.http,
-      cache: input.cache,
-      ...input.signal !== void 0 ? { signal: input.signal } : {}
+};
+var runNativesStage = async (ctx, natives) => {
+  if (natives.length === 0) return;
+  await ctx.checkpoint();
+  ctx.enterPhase(InstallPhases.EXTRACTING_NATIVES);
+  for (const action of natives) {
+    await ctx.checkpoint();
+    const { fileCount } = await extractAllToDir(action.source, action.destination, {
+      excludePrefixes: action.exclude
     });
-    await materializeRuntimeExtras({
-      runtime: input.plan.target.runtime,
-      directory: input.plan.directory,
-      manifest: runtimePlan.manifest
+    ctx.input.onEvent?.({
+      type: EventTypes.ARCHIVE_EXTRACTED,
+      archive: action.source,
+      target: action.destination,
+      fileCount
     });
+    ctx.counters.actionsCompleted++;
   }
-  if (processors.length > 0) {
-    await checkpoint();
-    enterPhase(InstallPhases.RUNNING_FORGE_PROCESSORS);
-    if (input.plan.target.loader.type !== Loaders.FORGE) {
-      throw new MinecraftKitError(
-        "FORGE_PROCESSOR_FAILED",
-        "Forge processors planned for a non-Forge target"
-      );
-    }
-    const javaPath = targetPaths.runtimeJavaExecutable(
-      input.plan.directory,
-      input.plan.target.runtime.component,
-      input.plan.target.runtime.system.os,
-      input.plan.target.runtime.installRoot
-    );
-    for (const action of processors) {
-      await checkpoint();
-      await runProcessor({
-        action,
-        javaPath,
-        spawner: input.spawner,
-        ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {},
-        total: processors.length
-      });
-      actionsCompleted++;
-    }
-  }
-  enterPhase(InstallPhases.COMPLETED);
-  return {
-    targetId: input.plan.targetId,
-    bytesDownloaded,
-    actionsCompleted,
-    actionsSkipped,
-    durationMs: Date.now() - startedAt
-  };
-}
-function isDownload(action) {
-  return action.kind === InstallActionKinds.DOWNLOAD_FILE;
-}
-function isNative(action) {
-  return action.kind === InstallActionKinds.EXTRACT_NATIVE;
-}
-function isProcessor(action) {
-  return action.kind === InstallActionKinds.RUN_FORGE_PROCESSOR;
-}
-function isWrite(action) {
-  return action.kind === InstallActionKinds.WRITE_VERSION_JSON || action.kind === InstallActionKinds.WRITE_LOGGING_CONFIG;
-}
-async function runProcessor(input) {
-  const startedAt = Date.now();
-  const processorJar = input.action.classpath[0];
-  if (processorJar === void 0) {
-    throw new MinecraftKitError(
-      "FORGE_INSTALLER_INVALID",
-      "Forge processor has an empty classpath",
-      { context: { processorIndex: input.action.index } }
-    );
-  }
-  const mainClass = await readJarMainClass(processorJar);
-  if (!mainClass) {
-    throw new MinecraftKitError(
-      "FORGE_INSTALLER_INVALID",
-      `Forge processor jar has no Main-Class: ${processorJar}`,
-      { context: { filePath: processorJar } }
-    );
-  }
-  const classpathSeparator = process.platform === "win32" ? ";" : ":";
-  const args = [
-    "-cp",
-    input.action.classpath.join(classpathSeparator),
-    mainClass,
-    ...input.action.args
-  ];
-  input.onEvent?.({
-    type: "forge:processor-started",
-    processor: { index: input.action.index, mainClass },
-    total: input.total
-  });
-  const stderrTail = [];
-  const child = input.spawner.spawn(input.javaPath, args, { cwd: process.cwd() });
-  child.stdout.on("data", () => {
+};
+var runRuntimeStage = async (ctx) => {
+  const runtime = ctx.input.plan.target.runtime;
+  if (runtime === void 0) return;
+  await ctx.checkpoint();
+  ctx.enterPhase(InstallPhases.INSTALLING_RUNTIME);
+  const runtimePlan = await planRuntimeDownloads({
+    runtime,
+    directory: ctx.input.plan.directory,
+    http: ctx.input.http,
+    cache: ctx.input.cache,
+    ...ctx.input.signal !== void 0 ? { signal: ctx.input.signal } : {}
   });
-  child.stderr.on("data", (line) => {
-    if (stderrTail.length >= MAX_PROCESSOR_STDERR_LINES) stderrTail.shift();
-    stderrTail.push(line);
+  await materializeRuntimeExtras({
+    runtime,
+    directory: ctx.input.plan.directory,
+    manifest: runtimePlan.manifest
   });
-  const exit = await child.exited;
-  if (exit.code !== 0) {
+};
+var runProcessorsStage = async (ctx, processors) => {
+  if (processors.length === 0) return;
+  await ctx.checkpoint();
+  ctx.enterPhase(InstallPhases.RUNNING_FORGE_PROCESSORS);
+  const target = ctx.input.plan.target;
+  if (target.loader?.type !== Loaders.FORGE) {
     throw new MinecraftKitError(
-      "FORGE_PROCESSOR_FAILED",
-      `Forge processor exited with code ${exit.code ?? "(signal)"}: ${mainClass}`,
-      {
-        context: {
-          exitCode: exit.code ?? void 0,
-          mainClass,
-          stderr: stderrTail.join("\n")
-        }
-      }
+      MinecraftKitErrorCodes.FORGE_PROCESSOR_FAILED,
+      "Forge processors planned for a non-Forge target"
     );
   }
-  input.onEvent?.({
-    type: "forge:processor-completed",
-    processor: { index: input.action.index, mainClass },
-    exitCode: exit.code ?? 0,
-    durationMs: Date.now() - startedAt
-  });
-  for (const [outputPath, expectedSha1] of Object.entries(input.action.outputs)) {
-    const sha1 = await sha1OfFileStreaming(outputPath);
-    if (sha1 !== expectedSha1) {
-      throw new MinecraftKitError(
-        "FORGE_PROCESSOR_FAILED",
-        `Processor output hash mismatch: ${outputPath}`,
-        { context: { filePath: outputPath, expectedHash: expectedSha1, actualHash: sha1 } }
-      );
-    }
-    input.onEvent?.({
-      type: "forge:processor-output-verified",
-      processor: { index: input.action.index, mainClass },
-      path: outputPath
+  const javaPath = targetPaths.runtimeJavaExecutable(
+    ctx.input.plan.directory,
+    target.runtime.component,
+    target.runtime.system.os,
+    target.runtime.installRoot
+  );
+  for (const action of processors) {
+    await ctx.checkpoint();
+    await runProcessor({
+      action,
+      javaPath,
+      spawner: ctx.input.spawner,
+      ...ctx.input.onEvent !== void 0 ? { onEvent: ctx.input.onEvent } : {},
+      total: processors.length
     });
+    ctx.counters.actionsCompleted++;
   }
-}
-async function sha1OfFileStreaming(filePath) {
-  const hash = crypto2.createHash("sha1");
-  await new Promise((resolve, reject) => {
-    const stream = createReadStream(filePath);
-    stream.on("data", (chunk) => hash.update(chunk));
-    stream.on("end", () => resolve());
-    stream.on("error", reject);
-  });
-  return hash.digest("hex");
-}
+};
+var isDownload = (action) => {
+  return action.kind === InstallActionKinds.DOWNLOAD_FILE;
+};
+var isNative = (action) => {
+  return action.kind === InstallActionKinds.EXTRACT_NATIVE;
+};
+var isProcessor = (action) => {
+  return action.kind === InstallActionKinds.RUN_FORGE_PROCESSOR;
+};
+var isWrite = (action) => {
+  return action.kind === InstallActionKinds.WRITE_VERSION_JSON || action.kind === InstallActionKinds.WRITE_LOGGING_CONFIG;
+};
 
 // src/install/runtime-install.ts
-async function planRuntimeInstall(input) {
+var planRuntimeInstall = async (input) => {
   const runtimePlan = await planRuntimeDownloads({
     runtime: input.target.runtime,
     directory: input.target.directory,
@@ -2040,8 +2856,8 @@ async function planRuntimeInstall(input) {
     totalActions: actions.length,
     totalBytes
   };
-}
-async function planStandaloneRuntimeInstall(input) {
+};
+var planStandaloneRuntimeInstall = async (input) => {
   const runtimePlan = await planRuntimeDownloads({
     runtime: input.runtime,
     directory: input.directory,
@@ -2057,9 +2873,7 @@ async function planStandaloneRuntimeInstall(input) {
   const target = {
     id: input.id,
     directory: input.directory,
-    runtime: input.runtime,
-    minecraft: void 0,
-    loader: void 0
+    runtime: input.runtime
   };
   return {
     targetId: input.id,
@@ -2069,7 +2883,7 @@ async function planStandaloneRuntimeInstall(input) {
     totalActions: actions.length,
     totalBytes
   };
-}
+};
 
 // src/constants/launch.ts
 var BASE_JVM_ARGS = [
@@ -2090,7 +2904,7 @@ var LEGACY_JVM_ARGS = [
 var MACOS_JVM_ARGS = ["-Xdock:name=Minecraft"];
 
 // src/launch/arguments.ts
-function flattenArguments(entries, context) {
+var flattenArguments = (entries, context) => {
   const result = [];
   for (const entry of entries) {
     if (typeof entry === "string") {
@@ -2105,16 +2919,16 @@ function flattenArguments(entries, context) {
     }
   }
   return result;
-}
-function splitLegacyArguments(raw) {
+};
+var splitLegacyArguments = (raw) => {
   return raw.trim().length === 0 ? [] : raw.trim().split(/\s+/);
-}
-function pickArguments(args, context) {
+};
+var pickArguments = (args, context) => {
   return {
     game: flattenArguments(args?.game ?? [], context),
     jvm: flattenArguments(args?.jvm ?? [], context)
   };
-}
+};
 
 // src/launch/jvm-compat.ts
 var FLAG_MIN_JAVA = [
@@ -2123,7 +2937,7 @@ var FLAG_MIN_JAVA = [
   { prefix: "-XX:+UseCompactObjectHeaders", minJava: 24 },
   { prefix: "-XX:+UseZGC", minJava: 15 }
 ];
-function filterArgsForJava(input) {
+var filterArgsForJava = (input) => {
   if (!Number.isFinite(input.javaMajor) || input.javaMajor <= 0) return input.args;
   const out = [];
   for (const arg of input.args) {
@@ -2141,26 +2955,30 @@ function filterArgsForJava(input) {
     out.push(arg);
   }
   return out;
-}
+};
 
 // src/launch/placeholders.ts
-function substituteArg(raw, values) {
+var substituteArg = (raw, values) => {
   return raw.replaceAll(/\$\{([a-zA-Z0-9_]+)\}/g, (match, key) => {
     const value = values[key];
     if (value === void 0) {
-      throw new MinecraftKitError("INVALID_INPUT", `Unknown launch placeholder: ${match}`, {
-        context: { placeholder: key }
-      });
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.INVALID_INPUT,
+        `Unknown launch placeholder: ${match}`,
+        {
+          context: { placeholder: key }
+        }
+      );
     }
     return value;
   });
-}
-function substituteArgs(args, values) {
+};
+var substituteArgs = (args, values) => {
   return args.map((arg) => substituteArg(arg, values));
-}
+};
 
 // src/launch/args-composition.ts
-function composeArgs(input) {
+var composeArgs = (input) => {
   const minMb = input.options.memory?.minMb ?? DEFAULT_MIN_MB;
   const maxMb = input.options.memory?.maxMb ?? DEFAULT_MAX_MB;
   const memoryArgs = [`-Xms${minMb}M`, `-Xmx${maxMb}M`];
@@ -2210,8 +3028,8 @@ function composeArgs(input) {
     );
   }
   return { jvmArgs: [...jvmArgs, ...extraJvm], gameArgs };
-}
-function buildClasspath(input) {
+};
+var buildClasspath = (input) => {
   const seen = /* @__PURE__ */ new Set();
   const entries = [];
   for (const library of input.merged.libraries) {
@@ -2227,41 +3045,33 @@ function buildClasspath(input) {
   const versionJar = targetPaths.versionJar(input.directory, input.versionId);
   if (!seen.has(versionJar)) entries.push(versionJar);
   return entries;
-}
-function relativeFor(library) {
+};
+var relativeFor = (library) => {
   if (library.downloads?.artifact?.path) return library.downloads.artifact.path;
   if (library.name) {
     const coord = parseMavenCoordinate(library.name);
     return mavenRelativePath(coord);
   }
   return null;
-}
-function offlineUuidFor(username) {
+};
+var offlineUuidFor = (username) => {
   const md5 = crypto2.createHash("md5");
   md5.update(`OfflinePlayer:${username}`, "utf8");
   const bytes = md5.digest();
   bytes[6] = (bytes[6] ?? 0) & 15 | 48;
   bytes[8] = (bytes[8] ?? 0) & 63 | 128;
   return formatUuid(bytes);
-}
-function formatUuid(bytes) {
+};
+var formatUuid = (bytes) => {
   const hex = bytes.toString("hex");
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-}
-function stripUuidDashes(uuid) {
+};
+var stripUuidDashes = (uuid) => {
   return uuid.replaceAll("-", "");
-}
-
-// src/types/auth.ts
-var AuthModes = {
-  /** Offline-mode play with a chosen username and synthetic UUID. */
-  OFFLINE: "offline",
-  /** Pre-authenticated session — caller provides the access token and identity. */
-  ONLINE: "online"
 };
 
 // src/launch/placeholder-values.ts
-function buildPlaceholderValues(input) {
+var buildPlaceholderValues = (input) => {
   const cpSeparator = process.platform === "win32" ? ";" : ":";
   const directory = input.target.directory;
   const username = input.auth.username;
@@ -2294,11 +3104,20 @@ function buildPlaceholderValues(input) {
     resolution_width: input.options.resolution?.width.toString() ?? "",
     resolution_height: input.options.resolution?.height.toString() ?? ""
   };
-}
+};
 
 // src/core/manifest-merge.ts
-function mergeManifest(parent, child) {
-  const merged = {
+var mergeManifest = (parent, child) => {
+  const args = mergeArguments(parent.arguments, child.arguments);
+  const minecraftArguments = child.minecraftArguments ?? parent.minecraftArguments;
+  const javaVersion = child.javaVersion ?? parent.javaVersion;
+  const logging = child.logging ?? parent.logging;
+  const inheritsFrom = child.inheritsFrom ?? parent.inheritsFrom;
+  const releaseTime = child.releaseTime ?? parent.releaseTime;
+  const time = child.time ?? parent.time;
+  const minimumLauncherVersion = child.minimumLauncherVersion ?? parent.minimumLauncherVersion;
+  const complianceLevel = child.complianceLevel ?? parent.complianceLevel;
+  return {
     id: child.id || parent.id,
     type: child.type ?? parent.type,
     mainClass: child.mainClass ?? parent.mainClass,
@@ -2306,19 +3125,18 @@ function mergeManifest(parent, child) {
     assets: child.assets ?? parent.assets,
     downloads: { ...parent.downloads, ...child.downloads },
     libraries: mergeLibraries(parent.libraries, child.libraries),
-    arguments: mergeArguments(parent.arguments, child.arguments),
-    minecraftArguments: child.minecraftArguments ?? parent.minecraftArguments,
-    javaVersion: child.javaVersion ?? parent.javaVersion,
-    logging: child.logging ?? parent.logging,
-    inheritsFrom: child.inheritsFrom ?? parent.inheritsFrom,
-    releaseTime: child.releaseTime ?? parent.releaseTime,
-    time: child.time ?? parent.time,
-    minimumLauncherVersion: child.minimumLauncherVersion ?? parent.minimumLauncherVersion,
-    complianceLevel: child.complianceLevel ?? parent.complianceLevel
+    ...args !== void 0 ? { arguments: args } : {},
+    ...minecraftArguments !== void 0 ? { minecraftArguments } : {},
+    ...javaVersion !== void 0 ? { javaVersion } : {},
+    ...logging !== void 0 ? { logging } : {},
+    ...inheritsFrom !== void 0 ? { inheritsFrom } : {},
+    ...releaseTime !== void 0 ? { releaseTime } : {},
+    ...time !== void 0 ? { time } : {},
+    ...minimumLauncherVersion !== void 0 ? { minimumLauncherVersion } : {},
+    ...complianceLevel !== void 0 ? { complianceLevel } : {}
   };
-  return merged;
-}
-function libraryDedupeKey(library) {
+};
+var libraryDedupeKey = (library) => {
   if (!library.name) return null;
   try {
     const coord = parseMavenCoordinate(library.name);
@@ -2327,8 +3145,8 @@ function libraryDedupeKey(library) {
   } catch {
     return null;
   }
-}
-function mergeLibraries(parent, child) {
+};
+var mergeLibraries = (parent, child) => {
   const byKey = /* @__PURE__ */ new Map();
   const unkeyed = [];
   for (const lib of [...parent, ...child]) {
@@ -2340,8 +3158,8 @@ function mergeLibraries(parent, child) {
     byKey.set(key, lib);
   }
   return [...byKey.values(), ...unkeyed];
-}
-function mergeArguments(parent, child) {
+};
+var mergeArguments = (parent, child) => {
   if (!parent && !child) return void 0;
   const parentGame = parent?.game ?? [];
   const parentJvm = parent?.jvm ?? [];
@@ -2351,10 +3169,10 @@ function mergeArguments(parent, child) {
     game: [...parentGame, ...childGame],
     jvm: [...parentJvm, ...childJvm]
   };
-}
+};
 
 // src/launch/version-resolution.ts
-async function resolveLaunchVersion(target) {
+var resolveLaunchVersion = async (target) => {
   if (target.loader.type === Loaders.VANILLA) {
     return {
       versionId: target.minecraft.version,
@@ -2365,8 +3183,8 @@ async function resolveLaunchVersion(target) {
   const versionId = await pickInstalledVersionId(target);
   const merged = await loadAndMerge(target.directory, versionId, target.minecraft.manifest);
   return { versionId, merged, chain: [versionId, target.minecraft.version] };
-}
-async function pickClientJarVersionId(directory, chain) {
+};
+var pickClientJarVersionId = async (directory, chain) => {
   for (const id of chain) {
     const jar = targetPaths.versionJar(directory, id);
     if (await fileExists(jar)) return id;
@@ -2374,13 +3192,13 @@ async function pickClientJarVersionId(directory, chain) {
   const fallback = chain.at(-1);
   if (fallback === void 0) {
     throw new MinecraftKitError(
-      "MANIFEST_NOT_FOUND",
+      MinecraftKitErrorCodes.MANIFEST_NOT_FOUND,
       "Cannot resolve a client jar version id from an empty inheritsFrom chain"
     );
   }
   return fallback;
-}
-async function pickInstalledVersionId(target) {
+};
+var pickInstalledVersionId = async (target) => {
   if (target.loader.type === Loaders.FABRIC) {
     const candidate = target.loader.profile.id;
     const versionJsonPath = targetPaths.versionJson(target.directory, candidate);
@@ -2392,46 +3210,38 @@ async function pickInstalledVersionId(target) {
       const versionJsonPath = targetPaths.versionJson(target.directory, id);
       if (!await fileExists(versionJsonPath)) continue;
       const text = await readText(versionJsonPath);
-      try {
-        const parsed = JSON.parse(text);
-        if (parsed.inheritsFrom === target.minecraft.version && (id.includes("forge") || (parsed.id ?? "").includes("forge"))) {
-          return id;
-        }
-      } catch {
+      const parsed = parseJsonOrUndefined(text);
+      if (parsed?.inheritsFrom === target.minecraft.version && (id.includes("forge") || (parsed.id ?? "").includes("forge"))) {
+        return id;
       }
     }
   }
   throw new MinecraftKitError(
-    "MANIFEST_NOT_FOUND",
+    MinecraftKitErrorCodes.MANIFEST_NOT_FOUND,
     `Could not find an installed version JSON for target ${target.id}`,
     { context: { targetId: target.id, loaderType: target.loader.type } }
   );
-}
-async function loadAndMerge(directory, versionId, parentManifest) {
+};
+var loadAndMerge = async (directory, versionId, parentManifest) => {
   const versionJsonPath = targetPaths.versionJson(directory, versionId);
   const text = await readText(versionJsonPath);
-  let child;
-  try {
-    child = JSON.parse(text);
-  } catch (cause) {
-    throw new MinecraftKitError(
-      "MANIFEST_INVALID",
-      `Version JSON is not valid JSON: ${versionJsonPath}`,
-      { cause, context: { filePath: versionJsonPath } }
-    );
-  }
+  const child = parseJsonStrict(text, {
+    code: MinecraftKitErrorCodes.MANIFEST_INVALID,
+    message: `Version JSON is not valid JSON: ${versionJsonPath}`,
+    context: { filePath: versionJsonPath }
+  });
   if (child.inheritsFrom !== void 0 && child.inheritsFrom !== parentManifest.id) {
     return mergeManifest(parentManifest, child);
   }
   return mergeManifest(parentManifest, child);
-}
+};
 
 // src/launch/compose.ts
-async function composeLaunch(input) {
+var composeLaunch = async (input) => {
   const { target, options } = input;
   if (!options.auth.username || options.auth.username.length === 0) {
     throw new MinecraftKitError(
-      "INVALID_INPUT",
+      MinecraftKitErrorCodes.INVALID_INPUT,
       `Auth username must be non-empty (target ${target.id})`,
       { context: { targetId: target.id } }
     );
@@ -2478,22 +3288,22 @@ async function composeLaunch(input) {
     auth: options.auth,
     workingDirectory: target.directory
   };
-}
-function buildFeatures(options) {
+};
+var buildFeatures = (options) => {
   const features = { ...options.features ?? {} };
   if (options.resolution !== void 0) {
     features.has_custom_resolution = true;
   }
   return features;
-}
+};
 
 // src/launch/runner.ts
-function runLaunch(input) {
+var runLaunch = (input) => {
   const composition = input.composition;
   const options = input.options ?? {};
   const args = [...composition.jvmArgs, composition.mainClass, ...composition.gameArgs];
   options.onEvent?.({
-    type: "launch:starting",
+    type: EventTypes.LAUNCH_STARTING,
     command: composition.javaPath,
     args,
     cwd: composition.workingDirectory
@@ -2502,19 +3312,19 @@ function runLaunch(input) {
     cwd: composition.workingDirectory,
     ...composition.env !== void 0 ? { env: composition.env } : {}
   });
-  options.onEvent?.({ type: "launch:started", pid: child.pid });
+  options.onEvent?.({ type: EventTypes.LAUNCH_STARTED, pid: child.pid });
   child.stdout.on("data", (line) => {
-    options.onEvent?.({ type: "launch:stdout", line });
+    options.onEvent?.({ type: EventTypes.LAUNCH_STDOUT, line });
   });
   child.stderr.on("data", (line) => {
-    options.onEvent?.({ type: "launch:stderr", line });
+    options.onEvent?.({ type: EventTypes.LAUNCH_STDERR, line });
   });
   const grace = options.killGracePeriodMs ?? DEFAULT_KILL_GRACE_MS;
   let aborted = false;
   const doAbort = (reason) => {
     if (aborted) return;
     aborted = true;
-    options.onEvent?.({ type: "launch:aborted", reason });
+    options.onEvent?.({ type: EventTypes.LAUNCH_ABORTED, reason });
     child.kill("SIGTERM");
     setTimeout(() => child.kill("SIGKILL"), grace).unref();
   };
@@ -2529,10 +3339,10 @@ function runLaunch(input) {
   }
   const exited = (async () => {
     const { code, signal } = await child.exited;
-    options.onEvent?.({ type: "launch:exited", code, signal });
+    options.onEvent?.({ type: EventTypes.LAUNCH_EXITED, code, signal });
     if (!aborted && code !== 0 && code !== null) {
       throw new MinecraftKitError(
-        "LAUNCH_PROCESS_FAILED",
+        MinecraftKitErrorCodes.LAUNCH_PROCESS_FAILED,
         `Minecraft process exited with code ${code}`,
         { context: { exitCode: code } }
       );
@@ -2546,13 +3356,13 @@ function runLaunch(input) {
       doAbort(reason ?? "user");
     }
   };
-}
-function reasonFrom(value) {
+};
+var reasonFrom = (value) => {
   if (value === void 0) return "aborted";
   if (typeof value === "string") return value;
   if (value instanceof Error) return value.message;
   return String(value);
-}
+};
 var ChildProcessSpawner = class {
   spawn(command, args, options) {
     const child = spawn(command, [...args], {
@@ -2576,14 +3386,14 @@ var ChildProcessSpawner = class {
     };
   }
 };
-function streamFromBuffer(stream) {
+var streamFromBuffer = (stream) => {
   if (!stream) {
     return { on() {
     } };
   }
   let buffer = "";
   const listeners = /* @__PURE__ */ new Set();
-  const emit = (line) => {
+  const emit2 = (line) => {
     for (const listener of listeners) listener(line);
   };
   stream.on("data", (chunk) => {
@@ -2593,35 +3403,36 @@ function streamFromBuffer(stream) {
     while (index !== -1) {
       const line = buffer.slice(0, index).replace(/\r$/, "");
       buffer = buffer.slice(index + 1);
-      emitBounded(emit, line);
+      emitBounded(emit2, line);
       index = buffer.indexOf("\n");
     }
     while (buffer.length > SPAWNER_MAX_LINE_BYTES) {
-      emit(buffer.slice(0, SPAWNER_MAX_LINE_BYTES));
+      emit2(buffer.slice(0, SPAWNER_MAX_LINE_BYTES));
       buffer = buffer.slice(SPAWNER_MAX_LINE_BYTES);
     }
   });
   stream.on("end", () => {
     if (buffer.length > 0) {
-      emitBounded(emit, buffer);
+      emitBounded(emit2, buffer);
       buffer = "";
     }
+    listeners.clear();
   });
   return {
     on(_event, listener) {
       listeners.add(listener);
     }
   };
-}
-function emitBounded(emit, line) {
+};
+var emitBounded = (emit2, line) => {
   if (line.length <= SPAWNER_MAX_LINE_BYTES) {
-    emit(line);
+    emit2(line);
     return;
   }
   for (let i = 0; i < line.length; i += SPAWNER_MAX_LINE_BYTES) {
-    emit(line.slice(i, i + SPAWNER_MAX_LINE_BYTES));
+    emit2(line.slice(i, i + SPAWNER_MAX_LINE_BYTES));
   }
-}
+};
 
 // src/types/verify.ts
 var VerificationKinds = {
@@ -2646,24 +3457,14 @@ var VerifyFileCategories = {
   RUNTIME_FILE: "runtime-file",
   LOGGING_CONFIG: "logging-config"
 };
-async function sha1OfFile(filePath) {
-  const hash = crypto2.createHash("sha1");
-  await new Promise((resolve, reject) => {
-    const stream = createReadStream(filePath);
-    stream.on("data", (chunk) => hash.update(chunk));
-    stream.on("end", resolve);
-    stream.on("error", reject);
-  });
-  return hash.digest("hex");
-}
 
 // src/verify/helpers.ts
-async function runVerification(input, check) {
+var runVerification = async (input, check) => {
   const startedAt = Date.now();
   const results = [];
   const record = (result) => {
     results.push(result);
-    input.onEvent?.({ type: "verify:file-checked", file: result });
+    input.onEvent?.({ type: EventTypes.VERIFY_FILE_CHECKED, file: result });
   };
   await check(record);
   return {
@@ -2674,8 +3475,8 @@ async function runVerification(input, check) {
     checkedFiles: results.length,
     durationMs: Date.now() - startedAt
   };
-}
-async function verifyHashedFile(input) {
+};
+var verifyHashedFile = async (input) => {
   if (!await fileExists(input.path)) {
     return {
       path: input.path,
@@ -2722,8 +3523,8 @@ async function verifyHashedFile(input) {
     ...input.expectedSize !== void 0 ? { expectedSize: input.expectedSize } : {},
     ...input.url !== void 0 ? { url: input.url } : {}
   };
-}
-async function verifyExistence(input) {
+};
+var verifyExistence = async (input) => {
   if (await fileExists(input.path)) {
     return {
       path: input.path,
@@ -2738,8 +3539,8 @@ async function verifyExistence(input) {
     status: VerifyFileStatuses.MISSING,
     ...input.url !== void 0 ? { url: input.url } : {}
   };
-}
-async function findForgeVersionJsonPath(directory, minecraftVersion) {
+};
+var findForgeVersionJsonPath = async (directory, minecraftVersion) => {
   const versionsDir = targetPaths.versionsDir(directory);
   const dirs = await listChildDirectories(versionsDir);
   for (const id of dirs) {
@@ -2752,21 +3553,17 @@ async function findForgeVersionJsonPath(directory, minecraftVersion) {
     if (parsed === minecraftVersion) return jsonPath;
   }
   return null;
-}
-async function tryParseInheritsFrom(jsonPath) {
-  try {
-    const parsed = JSON.parse(await readText(jsonPath));
-    return parsed.inheritsFrom;
-  } catch {
-    return void 0;
-  }
-}
+};
+var tryParseInheritsFrom = async (jsonPath) => {
+  const parsed = parseJsonOrUndefined(await readText(jsonPath));
+  return parsed?.inheritsFrom;
+};
 
 // src/verify/fabric.ts
-async function verifyFabric(input) {
+var verifyFabric = async (input) => {
   if (input.target.loader.type !== Loaders.FABRIC) {
     throw new MinecraftKitError(
-      "INVALID_INPUT",
+      MinecraftKitErrorCodes.INVALID_INPUT,
       `verify.fabric requires a Fabric target (got ${input.target.loader.type})`
     );
   }
@@ -2789,14 +3586,14 @@ async function verifyFabric(input) {
         directory: input.target.directory,
         system: input.target.runtime.system,
         versionId: input.target.minecraft.version,
-        category: "fabric-library"
+        category: DownloadCategories.FABRIC_LIBRARY
       });
       for (const action of fabricLibraries.downloads) {
         record(
           await verifyHashedFile({
             path: action.target,
-            expectedSha1: action.expectedSha1,
-            expectedSize: action.expectedSize,
+            ...action.expectedSha1 !== void 0 ? { expectedSha1: action.expectedSha1 } : {},
+            ...action.expectedSize !== void 0 ? { expectedSize: action.expectedSize } : {},
             ...action.url ? { url: action.url } : {},
             category: VerifyFileCategories.LOADER_LIBRARY
           })
@@ -2804,13 +3601,13 @@ async function verifyFabric(input) {
       }
     }
   );
-}
+};
 
 // src/verify/forge.ts
-async function verifyForge(input) {
+var verifyForge = async (input) => {
   if (input.target.loader.type !== Loaders.FORGE) {
     throw new MinecraftKitError(
-      "INVALID_INPUT",
+      MinecraftKitErrorCodes.INVALID_INPUT,
       `verify.forge requires a Forge target (got ${input.target.loader.type})`
     );
   }
@@ -2833,10 +3630,8 @@ async function verifyForge(input) {
         })
       );
       if (!await fileExists(forgeVersionJsonPath)) return;
-      let parsed;
-      try {
-        parsed = JSON.parse(await readText(forgeVersionJsonPath));
-      } catch {
+      const parsed = parseJsonOrUndefined(await readText(forgeVersionJsonPath));
+      if (parsed === void 0) {
         record({
           path: forgeVersionJsonPath,
           category: VerifyFileCategories.LOADER_LIBRARY,
@@ -2849,14 +3644,14 @@ async function verifyForge(input) {
         directory: input.target.directory,
         system: input.target.runtime.system,
         versionId: input.target.minecraft.version,
-        category: "forge-library"
+        category: DownloadCategories.FORGE_LIBRARY
       });
       for (const action of forgeLibraries.downloads) {
         record(
           await verifyHashedFile({
             path: action.target,
-            expectedSha1: action.expectedSha1,
-            expectedSize: action.expectedSize,
+            ...action.expectedSha1 !== void 0 ? { expectedSha1: action.expectedSha1 } : {},
+            ...action.expectedSize !== void 0 ? { expectedSize: action.expectedSize } : {},
             ...action.url ? { url: action.url } : {},
             category: VerifyFileCategories.LOADER_LIBRARY
           })
@@ -2864,10 +3659,10 @@ async function verifyForge(input) {
       }
     }
   );
-}
+};
 
 // src/verify/minecraft.ts
-async function verifyMinecraft(input) {
+var verifyMinecraft = async (input) => {
   return runVerification(
     {
       targetId: input.target.id,
@@ -2908,14 +3703,14 @@ async function verifyMinecraft(input) {
         directory,
         system: runtime.system,
         versionId: minecraft.version,
-        category: "library"
+        category: DownloadCategories.LIBRARY
       });
       for (const action of libraryPlan.downloads) {
         record(
           await verifyHashedFile({
             path: action.target,
-            expectedSha1: action.expectedSha1,
-            expectedSize: action.expectedSize,
+            ...action.expectedSha1 !== void 0 ? { expectedSha1: action.expectedSha1 } : {},
+            ...action.expectedSize !== void 0 ? { expectedSize: action.expectedSize } : {},
             url: action.url,
             category: VerifyFileCategories.LIBRARY
           })
@@ -2962,8 +3757,8 @@ async function verifyMinecraft(input) {
       }
     }
   );
-}
-async function verifyRuntime(input) {
+};
+var verifyRuntime = async (input) => {
   return runVerification(
     {
       targetId: input.target.id,
@@ -3005,13 +3800,13 @@ async function verifyRuntime(input) {
       }
     }
   );
-}
+};
 
 // src/repair/helpers.ts
-function asResultArray(from) {
+var asResultArray = (from) => {
   return Array.isArray(from) ? from : [from];
-}
-function buildIssueIndex(from) {
+};
+var buildIssueIndex = (from) => {
   const map = /* @__PURE__ */ new Map();
   for (const v of asResultArray(from)) {
     for (const issue of v.issues) {
@@ -3032,16 +3827,16 @@ function buildIssueIndex(from) {
     },
     categoriesAt: (path13) => map.get(path13) ?? /* @__PURE__ */ new Set()
   };
-}
-function sumDownloadBytes(actions) {
+};
+var sumDownloadBytes = (actions) => {
   return actions.reduce((sum, action) => {
     if (action.kind === InstallActionKinds.DOWNLOAD_FILE) {
       return sum + (action.expectedSize ?? 0);
     }
     return sum;
   }, 0);
-}
-function buildRepairPlan(target, actions) {
+};
+var buildRepairPlan = (target, actions) => {
   return {
     targetId: target.id,
     directory: target.directory,
@@ -3050,8 +3845,8 @@ function buildRepairPlan(target, actions) {
     totalActions: actions.length,
     totalBytes: sumDownloadBytes(actions)
   };
-}
-async function planAspectRepair(input, aspectFilter, postprocess) {
+};
+var planAspectRepair = async (input, aspectFilter, postprocess) => {
   const installPlan = await planInstall({
     target: input.target,
     http: input.http,
@@ -3067,8 +3862,8 @@ async function planAspectRepair(input, aspectFilter, postprocess) {
   });
   postprocess?.({ actions, installPlan, issues });
   return buildRepairPlan(input.target, actions);
-}
-function selectRepairActions(input) {
+};
+var selectRepairActions = (input) => {
   const matching = [];
   for (const action of input.installPlan.actions) {
     if (!input.aspectFilter(action)) continue;
@@ -3089,13 +3884,13 @@ function selectRepairActions(input) {
     }
   }
   return matching;
-}
+};
 
 // src/repair/fabric.ts
-async function planFabricRepair(input) {
+var planFabricRepair = async (input) => {
   if (input.target.loader.type !== Loaders.FABRIC) {
     throw new MinecraftKitError(
-      "INVALID_INPUT",
+      MinecraftKitErrorCodes.INVALID_INPUT,
       `repair.fabric requires a Fabric target (got ${input.target.loader.type})`
     );
   }
@@ -3105,24 +3900,24 @@ async function planFabricRepair(input) {
   );
   return planAspectRepair(input, (action) => {
     if (action.kind === InstallActionKinds.DOWNLOAD_FILE) {
-      return action.category === "fabric-library";
+      return action.category === DownloadCategories.FABRIC_LIBRARY;
     }
     if (action.kind === InstallActionKinds.WRITE_VERSION_JSON) {
       return action.path === fabricJsonPath;
     }
     return false;
   });
-}
+};
 
 // src/repair/forge.ts
 var FORGE_DOWNLOAD_CATEGORIES = /* @__PURE__ */ new Set([
-  "forge-library",
-  "forge-installer"
+  DownloadCategories.FORGE_LIBRARY,
+  DownloadCategories.FORGE_INSTALLER
 ]);
-async function planForgeRepair(input) {
+var planForgeRepair = async (input) => {
   if (input.target.loader.type !== Loaders.FORGE) {
     throw new MinecraftKitError(
-      "INVALID_INPUT",
+      MinecraftKitErrorCodes.INVALID_INPUT,
       `repair.forge requires a Forge target (got ${input.target.loader.type})`
     );
   }
@@ -3147,7 +3942,7 @@ async function planForgeRepair(input) {
         actions.filter((a) => a.kind === InstallActionKinds.DOWNLOAD_FILE).map((a) => a.target)
       );
       for (const action of installPlan.actions) {
-        if (action.kind === InstallActionKinds.DOWNLOAD_FILE && action.category === "forge-library" && !alreadyIncluded.has(action.target)) {
+        if (action.kind === InstallActionKinds.DOWNLOAD_FILE && action.category === DownloadCategories.FORGE_LIBRARY && !alreadyIncluded.has(action.target)) {
           actions.push(action);
         } else if (action.kind === InstallActionKinds.RUN_FORGE_PROCESSOR) {
           actions.push(action);
@@ -3155,17 +3950,17 @@ async function planForgeRepair(input) {
       }
     }
   );
-}
+};
 
 // src/repair/minecraft.ts
 var MINECRAFT_DOWNLOAD_CATEGORIES = /* @__PURE__ */ new Set([
-  "client-jar",
-  "library",
-  "asset-index",
-  "asset",
-  "logging-config"
+  DownloadCategories.CLIENT_JAR,
+  DownloadCategories.LIBRARY,
+  DownloadCategories.ASSET_INDEX,
+  DownloadCategories.ASSET,
+  DownloadCategories.LOGGING_CONFIG
 ]);
-async function planMinecraftRepair(input) {
+var planMinecraftRepair = async (input) => {
   const vanillaJsonPath = targetPaths.versionJson(
     input.target.directory,
     input.target.minecraft.version
@@ -3182,10 +3977,10 @@ async function planMinecraftRepair(input) {
     }
     return false;
   });
-}
+};
 
 // src/repair/runner.ts
-async function runRepair(input) {
+var runRepair = async (input) => {
   const report = await runInstall({
     plan: {
       ...input.plan,
@@ -3204,18 +3999,18 @@ async function runRepair(input) {
     actionsCompleted: report.actionsCompleted,
     durationMs: report.durationMs
   };
-}
+};
 
 // src/repair/runtime.ts
-async function planRuntimeRepair(input) {
+var planRuntimeRepair = async (input) => {
   return planAspectRepair(
     input,
-    (action) => action.kind === InstallActionKinds.DOWNLOAD_FILE && action.category === "runtime-file"
+    (action) => action.kind === InstallActionKinds.DOWNLOAD_FILE && action.category === DownloadCategories.RUNTIME_FILE
   );
-}
+};
 
 // src/repair/all.ts
-async function repairAll(input) {
+var repairAll = async (input) => {
   const startedAt = Date.now();
   const ctx = {
     target: input.target,
@@ -3258,7 +4053,7 @@ async function repairAll(input) {
     bytesDownloaded,
     durationMs: Date.now() - startedAt
   };
-}
+};
 var PLANNERS = {
   minecraft: planMinecraftRepair,
   runtime: planRuntimeRepair,
@@ -3297,14 +4092,27 @@ var TargetsApi = class {
   /** Build a {@link Target} from already-resolved components. */
   create(input) {
     if (!input.id) {
-      throw new MinecraftKitError("INVALID_INPUT", "Target id must be non-empty");
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.INVALID_INPUT,
+        "Target id must be non-empty"
+      );
     }
     if (!input.directory) {
-      throw new MinecraftKitError("INVALID_INPUT", "Target directory must be non-empty");
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.INVALID_INPUT,
+        "Target directory must be non-empty"
+      );
+    }
+    if (!path.isAbsolute(input.directory)) {
+      throw new MinecraftKitError(
+        MinecraftKitErrorCodes.INVALID_INPUT,
+        `Target directory must be an absolute path, got: ${input.directory}`,
+        { context: { directory: input.directory } }
+      );
     }
     if (input.loader.minecraftVersion !== input.minecraft.version) {
       throw new MinecraftKitError(
-        "INVALID_INPUT",
+        MinecraftKitErrorCodes.INVALID_INPUT,
         `Loader Minecraft version (${input.loader.minecraftVersion}) does not match resolved Minecraft (${input.minecraft.version})`,
         {
           context: {
@@ -3381,7 +4189,7 @@ var TargetsApi = class {
     return results;
   }
 };
-async function discoverInstallation(id, directory) {
+var discoverInstallation = async (id, directory) => {
   const versionsDir = path.join(directory, VERSIONS_DIR);
   const librariesDir = path.join(directory, LIBRARIES_DIR);
   const assetsDir = path.join(directory, ASSETS_DIR);
@@ -3403,8 +4211,8 @@ async function discoverInstallation(id, directory) {
   }
   const runtime = await discoverRuntime(directory);
   return { id, directory, minecraftVersions, loaders, ...runtime ? { runtime } : {} };
-}
-async function discoverRuntime(directory) {
+};
+var discoverRuntime = async (directory) => {
   const runtimeDir = path.join(directory, RUNTIMES_DIR);
   if (!await dirExists(runtimeDir)) return void 0;
   let components;
@@ -3415,14 +4223,14 @@ async function discoverRuntime(directory) {
   }
   for (const component of components) {
     const root = path.join(runtimeDir, component);
-    const javaPath = process.platform === "win32" ? path.join(root, "bin", "javaw.exe") : process.platform === "darwin" ? path.join(root, "jre.bundle", "Contents", "Home", "bin", "java") : path.join(root, "bin", "java");
+    const javaPath = javaExecutablePath(root);
     if (await fileExists(javaPath)) {
       return { component, javaPath };
     }
   }
   return void 0;
-}
-function inferLoaderFromVersionId(versionId) {
+};
+var inferLoaderFromVersionId = (versionId) => {
   const fabricMatch = /^fabric-loader-([^-]+)-(.+)$/.exec(versionId);
   if (fabricMatch?.[1] && fabricMatch[2]) {
     return { type: Loaders.FABRIC, version: fabricMatch[1], minecraftVersion: fabricMatch[2] };
@@ -3432,18 +4240,25 @@ function inferLoaderFromVersionId(versionId) {
     return { type: Loaders.FORGE, minecraftVersion: forgeMatch[1], version: forgeMatch[2] };
   }
   return null;
-}
+};
+var javaExecutablePath = (runtimeRoot) => {
+  if (process.platform === "win32") return path.join(runtimeRoot, "bin", "javaw.exe");
+  if (process.platform === "darwin") {
+    return path.join(runtimeRoot, "jre.bundle", "Contents", "Home", "bin", "java");
+  }
+  return path.join(runtimeRoot, "bin", "java");
+};
 
 // src/update/runner.ts
-async function planUpdate(input) {
+var planUpdate = async (input) => {
   return planInstall({
     target: input.target,
     http: input.http,
     cache: input.cache,
     ...input.signal !== void 0 ? { signal: input.signal } : {}
   });
-}
-async function runUpdate(input) {
+};
+var runUpdate = async (input) => {
   const report = await runInstall({
     plan: input.plan,
     http: input.http,
@@ -3459,7 +4274,7 @@ async function runUpdate(input) {
     actionsSkipped: report.actionsSkipped,
     durationMs: report.durationMs
   };
-}
+};
 
 // src/versions/fabric.ts
 var FabricVersionsApi = class {
@@ -3495,7 +4310,7 @@ var FabricVersionsApi = class {
     });
     if (loaders.length === 0) {
       throw new MinecraftKitError(
-        "MANIFEST_NOT_FOUND",
+        MinecraftKitErrorCodes.MANIFEST_NOT_FOUND,
         `No Fabric loader available for Minecraft ${input.minecraftVersion}`,
         { context: { version: input.minecraftVersion } }
       );
@@ -3503,9 +4318,11 @@ var FabricVersionsApi = class {
     const chosen = pickFabricLoader(loaders, input);
     if (!chosen) {
       throw new MinecraftKitError(
-        "MANIFEST_NOT_FOUND",
+        MinecraftKitErrorCodes.MANIFEST_NOT_FOUND,
         `Fabric loader version not found: ${input.loaderVersion ?? "(none matched)"}`,
-        { context: { version: input.loaderVersion } }
+        {
+          context: input.loaderVersion !== void 0 ? { version: input.loaderVersion } : {}
+        }
       );
     }
     const profile = await fetchJson(this.ctx.http, this.ctx.cache, {
@@ -3521,7 +4338,7 @@ var FabricVersionsApi = class {
     };
   }
 };
-function pickFabricLoader(loaders, input) {
+var pickFabricLoader = (loaders, input) => {
   if (input.loaderVersion !== void 0) {
     return loaders.find((l) => l.version === input.loaderVersion);
   }
@@ -3531,17 +4348,17 @@ function pickFabricLoader(loaders, input) {
     if (stable) return stable;
   }
   return loaders[0];
-}
+};
 
 // src/core/xml.ts
-function parseMavenMetadataVersions(xml) {
+var parseMavenMetadataVersions = (xml) => {
   const versions = [];
   const regex = /<version>\s*([^<]+?)\s*<\/version>/g;
   for (const match of xml.matchAll(regex)) {
     if (match[1]) versions.push(match[1]);
   }
   return versions;
-}
+};
 
 // src/versions/forge.ts
 var ForgeVersionsApi = class {
@@ -3574,7 +4391,7 @@ var ForgeVersionsApi = class {
     });
     if (builds.length === 0) {
       throw new MinecraftKitError(
-        "MANIFEST_NOT_FOUND",
+        MinecraftKitErrorCodes.MANIFEST_NOT_FOUND,
         `No Forge build available for Minecraft ${input.minecraftVersion}`,
         { context: { version: input.minecraftVersion } }
       );
@@ -3582,9 +4399,11 @@ var ForgeVersionsApi = class {
     const chosen = pickForge(builds, input);
     if (!chosen) {
       throw new MinecraftKitError(
-        "MANIFEST_NOT_FOUND",
+        MinecraftKitErrorCodes.MANIFEST_NOT_FOUND,
         `Forge build not found for ${input.minecraftVersion}: ${input.forgeVersion ?? "(none matched)"}`,
-        { context: { version: input.forgeVersion } }
+        {
+          context: input.forgeVersion !== void 0 ? { version: input.forgeVersion } : {}
+        }
       );
     }
     return {
@@ -3596,7 +4415,7 @@ var ForgeVersionsApi = class {
     };
   }
 };
-function buildSummary(fullVersion, promotions) {
+var buildSummary = (fullVersion, promotions) => {
   const dashIndex = fullVersion.indexOf("-");
   if (dashIndex <= 0 || dashIndex === fullVersion.length - 1) return null;
   const minecraftVersion = fullVersion.slice(0, dashIndex);
@@ -3611,8 +4430,8 @@ function buildSummary(fullVersion, promotions) {
     isRecommended: recommended === forgeVersion,
     isLatest: latest === forgeVersion
   };
-}
-function pickForge(builds, input) {
+};
+var pickForge = (builds, input) => {
   if (input.forgeVersion !== void 0) {
     return builds.find(
       (b) => b.forgeVersion === input.forgeVersion || b.fullVersion === input.forgeVersion
@@ -3626,7 +4445,30 @@ function pickForge(builds, input) {
   const latest = builds.find((b) => b.isLatest);
   if (latest) return latest;
   return builds[builds.length - 1];
-}
+};
+
+// src/core/guards.ts
+var isPlainObject = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var isNonEmptyString = (value) => {
+  return typeof value === "string" && value.length > 0;
+};
+var isArtifactDownload = (value) => {
+  if (!isPlainObject(value)) return false;
+  return typeof value.sha1 === "string" && typeof value.size === "number" && isNonEmptyString(value.url);
+};
+var isMinecraftVersionManifestShape = (value) => {
+  if (!isPlainObject(value)) return false;
+  if (!isNonEmptyString(value.id)) return false;
+  if (!isNonEmptyString(value.mainClass)) return false;
+  if (!isPlainObject(value.assetIndex)) return false;
+  if (!isNonEmptyString(value.assetIndex.id) || typeof value.assetIndex.sha1 !== "string" || typeof value.assetIndex.size !== "number" || !isNonEmptyString(value.assetIndex.url)) {
+    return false;
+  }
+  if (!isPlainObject(value.downloads)) return false;
+  return isArtifactDownload(value.downloads.client);
+};
 
 // src/versions/minecraft.ts
 var MinecraftVersionsApi = class {
@@ -3647,7 +4489,7 @@ var MinecraftVersionsApi = class {
     const summary = root.versions.find((v) => v.id === targetId);
     if (!summary) {
       throw new MinecraftKitError(
-        "MANIFEST_NOT_FOUND",
+        MinecraftKitErrorCodes.MANIFEST_NOT_FOUND,
         `Latest version ${targetId} not found in manifest`
       );
     }
@@ -3659,7 +4501,7 @@ var MinecraftVersionsApi = class {
     const summary = root.versions.find((v) => v.id === input.version);
     if (!summary) {
       throw new MinecraftKitError(
-        "MANIFEST_NOT_FOUND",
+        MinecraftKitErrorCodes.MANIFEST_NOT_FOUND,
         `Minecraft version not found: ${input.version}`,
         { context: { version: input.version } }
       );
@@ -3669,18 +4511,19 @@ var MinecraftVersionsApi = class {
   /** Fetch and parse the per-version manifest in addition to the summary. */
   async resolve(input) {
     const summary = await this.get(input);
-    const manifest = await fetchJson(this.ctx.http, this.ctx.cache, {
+    const raw = await fetchJson(this.ctx.http, this.ctx.cache, {
       url: summary.url,
       cacheKey: `minecraft-manifest:${summary.id}:${summary.sha1}`,
       ...input.signal !== void 0 ? { signal: input.signal } : {}
     });
-    if (!manifest.id || !manifest.mainClass) {
+    if (!isMinecraftVersionManifestShape(raw)) {
       throw new MinecraftKitError(
-        "MANIFEST_INVALID",
-        `Per-version manifest is missing required fields: ${summary.id}`,
+        MinecraftKitErrorCodes.MANIFEST_INVALID,
+        `Per-version manifest does not match the expected shape: ${summary.id}`,
         { context: { version: summary.id, url: summary.url } }
       );
     }
+    const manifest = raw;
     return {
       version: summary.id,
       channel: summary.type,
@@ -3733,7 +4576,7 @@ var RuntimeVersionsApi = class {
     const platform = index[platformKey];
     if (!platform) {
       throw new MinecraftKitError(
-        "RUNTIME_UNSUPPORTED_PLATFORM",
+        MinecraftKitErrorCodes.RUNTIME_UNSUPPORTED_PLATFORM,
         `No runtimes published for platform: ${platformKey}`,
         { context: { platform: platformKey } }
       );
@@ -3750,7 +4593,7 @@ var RuntimeVersionsApi = class {
         }
       }
       throw new MinecraftKitError(
-        "RUNTIME_NOT_FOUND",
+        MinecraftKitErrorCodes.RUNTIME_NOT_FOUND,
         `Runtime component ${component} not available on ${platformKey}`,
         { context: { platform: platformKey, version: component } }
       );
@@ -3758,7 +4601,7 @@ var RuntimeVersionsApi = class {
     const entry = candidates[0];
     if (!entry) {
       throw new MinecraftKitError(
-        "RUNTIME_NOT_FOUND",
+        MinecraftKitErrorCodes.RUNTIME_NOT_FOUND,
         `Runtime component ${component} list is empty for ${platformKey}`,
         { context: { platform: platformKey, version: component } }
       );
@@ -3773,11 +4616,11 @@ var RuntimeVersionsApi = class {
     });
   }
 };
-function pickPlatformKey(system) {
+var pickPlatformKey = (system) => {
   const archMap = RUNTIME_PLATFORM_KEYS[system.os];
   return archMap[system.arch];
-}
-function pickLatestAcrossComponents(entries) {
+};
+var pickLatestAcrossComponents = (entries) => {
   let bestComponent = null;
   let bestEntry = null;
   for (const [component, list] of entries) {
@@ -3790,8 +4633,8 @@ function pickLatestAcrossComponents(entries) {
   }
   if (!bestComponent || !bestEntry) return null;
   return { component: bestComponent, entry: bestEntry };
-}
-function toResolved(component, platformKey, entry, system) {
+};
+var toResolved = (component, platformKey, entry, system) => {
   const majorVersion = parseMajorVersion(entry.version.name);
   return {
     component,
@@ -3802,13 +4645,13 @@ function toResolved(component, platformKey, entry, system) {
     manifestUrl: entry.manifest.url,
     manifestSha1: entry.manifest.sha1
   };
-}
-function parseMajorVersion(versionName) {
+};
+var parseMajorVersion = (versionName) => {
   const match = /^(\d+)/.exec(versionName);
   if (!match || !match[1]) return void 0;
   const parsed = Number.parseInt(match[1], 10);
   return Number.isFinite(parsed) ? parsed : void 0;
-}
+};
 
 // src/kit.ts
 var MinecraftKit = class {
@@ -3819,6 +4662,12 @@ var MinecraftKit = class {
   verify;
   repair;
   launch;
+  /**
+   * 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`.
+   */
+  auth;
   /** Cache surface useful for advanced consumers (e.g. clearing between operations). */
   cache;
   constructor(options = {}) {
@@ -3834,6 +4683,7 @@ var MinecraftKit = class {
     const runtime = new RuntimeVersionsApi(ctx);
     this.versions = { minecraft, fabric, forge, runtime };
     this.targets = new TargetsApi({ minecraft, fabric, forge, runtime, system });
+    this.auth = new MojangAuthApi(http);
     this.cache = cache;
     const carry = (opts) => ({
       ...opts?.signal !== void 0 ? { signal: opts.signal } : {},
@@ -3914,26 +4764,9 @@ var MinecraftKit = class {
   }
 };
 
-// src/core/pause-controller.ts
-var PauseController = class {
-  #paused = false;
-  #waiters = [];
-  get paused() {
-    return this.#paused;
-  }
-  pause() {
-    this.#paused = true;
-  }
-  resume() {
-    this.#paused = false;
-    const list = this.#waiters;
-    this.#waiters = [];
-    for (const resolve of list) resolve();
-  }
-  waitWhilePaused() {
-    if (!this.#paused) return Promise.resolve();
-    return new Promise((resolve) => this.#waiters.push(resolve));
-  }
+// src/core/assert-never.ts
+var assertNever = (value) => {
+  throw new Error(`Unhandled variant: ${JSON.stringify(value)}`);
 };
 
 // src/install/progress-tracker.ts
@@ -3945,15 +4778,15 @@ var InstallStages = {
   FINALIZE: "finalize"
 };
 var STAGE_FOR_CATEGORY = {
-  "runtime-file": InstallStages.RUNTIME,
-  "client-jar": InstallStages.MINECRAFT,
-  library: InstallStages.MINECRAFT,
-  "asset-index": InstallStages.MINECRAFT,
-  asset: InstallStages.MINECRAFT,
-  "logging-config": InstallStages.MINECRAFT,
-  "fabric-library": InstallStages.LOADER,
-  "forge-library": InstallStages.LOADER,
-  "forge-installer": InstallStages.LOADER
+  [DownloadCategories.RUNTIME_FILE]: InstallStages.RUNTIME,
+  [DownloadCategories.CLIENT_JAR]: InstallStages.MINECRAFT,
+  [DownloadCategories.LIBRARY]: InstallStages.MINECRAFT,
+  [DownloadCategories.ASSET_INDEX]: InstallStages.MINECRAFT,
+  [DownloadCategories.ASSET]: InstallStages.MINECRAFT,
+  [DownloadCategories.LOGGING_CONFIG]: InstallStages.MINECRAFT,
+  [DownloadCategories.FABRIC_LIBRARY]: InstallStages.LOADER,
+  [DownloadCategories.FORGE_LIBRARY]: InstallStages.LOADER,
+  [DownloadCategories.FORGE_INSTALLER]: InstallStages.LOADER
 };
 var STAGE_FOR_PHASE = {
   [InstallPhases.PLANNING]: InstallStages.PREPARE,
@@ -3977,7 +4810,7 @@ var ALL_STAGES = [
   InstallStages.LOADER,
   InstallStages.FINALIZE
 ];
-function createInstallProgressTracker(plan, options = {}) {
+var createInstallProgressTracker = (plan, options = {}) => {
   const throttleMs = options.throttleMs ?? 100;
   const stageOfTarget = /* @__PURE__ */ new Map();
   const expectedSizeOf = /* @__PURE__ */ new Map();
@@ -4061,7 +4894,7 @@ function createInstallProgressTracker(plan, options = {}) {
   };
   const onEvent = (event) => {
     switch (event.type) {
-      case "install:phase-changed": {
+      case EventTypes.INSTALL_PHASE_CHANGED: {
         const next = STAGE_FOR_PHASE[event.phase];
         if (next && next !== currentStage) {
           currentStage = next;
@@ -4070,14 +4903,14 @@ function createInstallProgressTracker(plan, options = {}) {
         }
         return;
       }
-      case "download:started": {
+      case EventTypes.DOWNLOAD_STARTED: {
         const stage = stageOfTarget.get(event.file.target) ?? currentStage;
         inFlightByTarget.set(event.file.target, { stage, bytes: 0 });
         currentFile = event.file.target;
         schedulePush();
         return;
       }
-      case "download:progress": {
+      case EventTypes.DOWNLOAD_PROGRESS: {
         const entry = inFlightByTarget.get(event.file.target);
         if (entry) {
           const delta = event.bytesDownloaded - entry.bytes;
@@ -4091,7 +4924,7 @@ function createInstallProgressTracker(plan, options = {}) {
         schedulePush();
         return;
       }
-      case "download:skipped": {
+      case EventTypes.DOWNLOAD_SKIPPED: {
         const stage = stageOfTarget.get(event.file.target);
         if (stage) {
           const size = expectedSizeOf.get(event.file.target) ?? 0;
@@ -4101,7 +4934,7 @@ function createInstallProgressTracker(plan, options = {}) {
         }
         return;
       }
-      case "download:completed": {
+      case EventTypes.DOWNLOAD_COMPLETED: {
         const entry = inFlightByTarget.get(event.file.target);
         if (entry) {
           const finalBytes = event.bytes ?? entry.bytes;
@@ -4148,36 +4981,60 @@ function createInstallProgressTracker(plan, options = {}) {
       for (const listener of listeners) listener(snap);
     }
   };
-}
-function clamp(value) {
+};
+var clamp = (value) => {
   if (value <= 0) return 0;
   if (value >= 100) return 100;
   return value;
-}
+};
 
-// src/types/events.ts
-var EventTypes = {
-  INSTALL_PHASE_CHANGED: "install:phase-changed",
-  DOWNLOAD_STARTED: "download:started",
-  DOWNLOAD_PROGRESS: "download:progress",
-  DOWNLOAD_SKIPPED: "download:skipped",
-  DOWNLOAD_COMPLETED: "download:completed",
-  DOWNLOAD_FAILED: "download:failed",
-  INTEGRITY_VERIFIED: "integrity:verified",
-  INTEGRITY_MISMATCH: "integrity:mismatch",
-  ARCHIVE_EXTRACTED: "archive:extracted",
-  FORGE_PROCESSOR_STARTED: "forge:processor-started",
-  FORGE_PROCESSOR_COMPLETED: "forge:processor-completed",
-  FORGE_PROCESSOR_OUTPUT_VERIFIED: "forge:processor-output-verified",
-  VERIFY_FILE_CHECKED: "verify:file-checked",
-  VERIFY_COMPLETED: "verify:completed",
-  REPAIR_PHASE_CHANGED: "repair:phase-changed",
-  LAUNCH_STARTING: "launch:starting",
-  LAUNCH_STARTED: "launch:started",
-  LAUNCH_STDOUT: "launch:stdout",
-  LAUNCH_STDERR: "launch:stderr",
-  LAUNCH_EXITED: "launch:exited",
-  LAUNCH_ABORTED: "launch:aborted"
+// src/core/pause-controller.ts
+var PauseController = class {
+  #paused = false;
+  #waiters = [];
+  get paused() {
+    return this.#paused;
+  }
+  pause() {
+    this.#paused = true;
+  }
+  resume() {
+    this.#paused = false;
+    const list = this.#waiters;
+    this.#waiters = [];
+    for (const resolve of list) resolve();
+  }
+  waitWhilePaused() {
+    if (!this.#paused) return Promise.resolve();
+    return new Promise((resolve) => this.#waiters.push(resolve));
+  }
+};
+
+// src/constants/placeholders.ts
+var LAUNCH_PLACEHOLDERS = {
+  "${auth_player_name}": "Player display name.",
+  "${version_name}": "Resolved Minecraft version id.",
+  "${game_directory}": "Per-target directory.",
+  "${assets_root}": "Assets root (`<directory>/assets`).",
+  "${assets_index_name}": "Asset index id from the manifest.",
+  "${auth_uuid}": "Player UUID (no dashes).",
+  "${auth_access_token}": "Yggdrasil/MSA access token.",
+  "${auth_session}": "Legacy session token (`token:<token>:<uuid>`).",
+  "${clientid}": "MSA client id.",
+  "${auth_xuid}": "Xbox user id.",
+  "${user_type}": "`msa` | `mojang` | `legacy`.",
+  "${user_properties}": "User properties JSON (often `{}`).",
+  "${version_type}": "Channel string, e.g. `release`.",
+  "${game_assets}": "Legacy virtual assets directory.",
+  "${resolution_width}": "Window width (feature-gated).",
+  "${resolution_height}": "Window height (feature-gated).",
+  "${natives_directory}": "Extracted natives directory.",
+  "${classpath}": "Joined classpath of libraries + version jar.",
+  "${classpath_separator}": "OS-specific classpath separator (`:` / `;`).",
+  "${library_directory}": "Per-target libraries directory.",
+  "${launcher_name}": "Launcher brand string.",
+  "${launcher_version}": "Launcher version string.",
+  "${path}": "Path to the log4j config file (logging.client.argument only)."
 };
 
 // src/types/minecraft.ts
@@ -4212,33 +5069,6 @@ var Architectures = {
   ARM64: "arm64"
 };
 
-// src/constants/placeholders.ts
-var LAUNCH_PLACEHOLDERS = {
-  "${auth_player_name}": "Player display name.",
-  "${version_name}": "Resolved Minecraft version id.",
-  "${game_directory}": "Per-target directory.",
-  "${assets_root}": "Assets root (`<directory>/assets`).",
-  "${assets_index_name}": "Asset index id from the manifest.",
-  "${auth_uuid}": "Player UUID (no dashes).",
-  "${auth_access_token}": "Yggdrasil/MSA access token.",
-  "${auth_session}": "Legacy session token (`token:<token>:<uuid>`).",
-  "${clientid}": "MSA client id.",
-  "${auth_xuid}": "Xbox user id.",
-  "${user_type}": "`msa` | `mojang` | `legacy`.",
-  "${user_properties}": "User properties JSON (often `{}`).",
-  "${version_type}": "Channel string, e.g. `release`.",
-  "${game_assets}": "Legacy virtual assets directory.",
-  "${resolution_width}": "Window width (feature-gated).",
-  "${resolution_height}": "Window height (feature-gated).",
-  "${natives_directory}": "Extracted natives directory.",
-  "${classpath}": "Joined classpath of libraries + version jar.",
-  "${classpath_separator}": "OS-specific classpath separator (`:` / `;`).",
-  "${library_directory}": "Per-target libraries directory.",
-  "${launcher_name}": "Launcher brand string.",
-  "${launcher_version}": "Launcher version string.",
-  "${path}": "Path to the log4j config file (logging.client.argument only)."
-};
-
-export { ASSETS_DIR, ASSETS_INDEXES_DIR, ASSETS_LEGACY_DIR, ASSETS_LOG_CONFIGS_DIR, ASSETS_OBJECTS_DIR, ASSETS_RESOURCES_DIR, ASSETS_VIRTUAL_DIR, ApiEndpoints, Architectures, 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, EXTRACTION_MAX_COMPRESSION_RATIO, EXTRACTION_MAX_ENTRY_COUNT, EXTRACTION_MAX_FILE_SIZE, EXTRACTION_MAX_TOTAL_SIZE, EventTypes, FABRIC_MAVEN_BASE, FALLBACK_COMPONENT, FORGE_INSTALLERS_DIR, FORGE_INSTALLER_MAX_SIZE, FORGE_MAVEN_BASE, FabricVersionsApi, FetchHttpClient, ForgeVersionsApi, HTTP_RETRY_BACKOFF_BASE_MS, HTTP_RETRY_BACKOFF_CAP_MS, HTTP_RETRY_MAX, HTTP_TIMEOUT_MS, InstallActionKinds, InstallPhases, InstallStages, JAVA_EXECUTABLE, LAUNCH_PLACEHOLDERS, LEGACY_JVM_ARGS, LIBRARIES_DIR, Loaders, LogLevels, MACOS_JVM_ARGS, MAC_RUNTIME_PREFIX, MAX_PROCESSOR_STDERR_LINES, MinecraftChannels, MinecraftKit, MinecraftKitError, MinecraftVersionsApi, NATIVES_DIR_NAME, NODE_ARCH_TO_MOJANG_ARCH, NODE_PLATFORM_TO_MOJANG_OS, OperatingSystems, PROGRESS_EVENT_INTERVAL_MS, PauseController, RUNTIMES_DIR, RUNTIME_PLATFORM_KEYS, RepairPhases, RuntimeComponents, RuntimePreference, RuntimeVersionsApi, SPAWNER_MAX_LINE_BYTES, TargetsApi, USER_AGENT, VERSIONS_DIR, VerificationKinds, VerifyFileCategories, VerifyFileStatuses, VersionPreference, 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 };
+export { ASSETS_DIR, ASSETS_INDEXES_DIR, ASSETS_LEGACY_DIR, ASSETS_LOG_CONFIGS_DIR, ASSETS_OBJECTS_DIR, ASSETS_RESOURCES_DIR, ASSETS_VIRTUAL_DIR, ApiEndpoints, Architectures, 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, DownloadCategories, EXTRACTION_MAX_COMPRESSION_RATIO, EXTRACTION_MAX_ENTRY_COUNT, EXTRACTION_MAX_FILE_SIZE, EXTRACTION_MAX_TOTAL_SIZE, EventTypes, FABRIC_MAVEN_BASE, FALLBACK_COMPONENT, FORGE_INSTALLERS_DIR, FORGE_INSTALLER_MAX_SIZE, FORGE_MAVEN_BASE, FabricVersionsApi, FetchHttpClient, ForgeVersionsApi, HTTP_RETRY_BACKOFF_BASE_MS, HTTP_RETRY_BACKOFF_CAP_MS, HTTP_RETRY_MAX, HTTP_TIMEOUT_MS, InstallActionKinds, InstallPhases, InstallStages, JAVA_EXECUTABLE, LAUNCH_PLACEHOLDERS, LEGACY_JVM_ARGS, LIBRARIES_DIR, Loaders, LogLevels, MACOS_JVM_ARGS, MAC_RUNTIME_PREFIX, MAX_PROCESSOR_STDERR_LINES, MinecraftChannels, MinecraftKit, MinecraftKitError, MinecraftKitErrorCodes, MinecraftVersionsApi, MojangAuthApi, NATIVES_DIR_NAME, NODE_ARCH_TO_MOJANG_ARCH, NODE_PLATFORM_TO_MOJANG_OS, OperatingSystems, PROGRESS_EVENT_INTERVAL_MS, PauseController, RUNTIMES_DIR, RUNTIME_PLATFORM_KEYS, RepairPhases, RuntimeComponents, RuntimePreference, RuntimeVersionsApi, SPAWNER_MAX_LINE_BYTES, TargetsApi, USER_AGENT, VERSIONS_DIR, VerificationKinds, VerifyFileCategories, VerifyFileStatuses, VersionPreference, 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 };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map