@elite-dangerous-almanac/core 0.1.0-beta.9 → 0.1.2

package/dist/ships/ship-loadout.d.ts

@@ -1,21 +1,1795 @@
-import './slef.js';
-import './jump-range.js';
-import './slots.js';
-import './modules.js';
-import './power.js';
-import './heat.js';
-import './shields.js';
-import './armour.js';
-import './weapons.js';
-import './ammunition.js';
-import './weapons-capacitor.js';
-import './distributor.js';
-import './mobility.js';
-import './shield-recovery.js';
-import './pre-engineered.js';
-export { A as ApplyBlueprintOptions, a as AvailableBlueprint, B as BuildWeaponMetrics, D as DefenceOptions, b as DistributorOptions, c as FittedWeaponMetrics, I as ImmovableReason, J as JumpOptions, d as JumpRangeSummary, L as LoadoutEditError, e as LoadoutEditErrorCode, f as LoadoutExportOptions, g as LoadoutSlot, M as MobilityOptions, R as RetailCredits, S as ShipLoadout, h as SlefExportOptions, W as WeaponsOptions } from '../ship-loadout-BsfKbvKe.js';
-import './source-purchase.js';
-import './loadout-calculations.js';
-import './loadout-validation.js';
+import { ModuleEngineering, LoadoutModule, LoadoutEvent, SlefHeader, Slef } from './slef.js';
+import { TotalRangeDetails, FrameShiftDriveParams } from './jump-range.js';
+import { BuildSlot, SlotKind } from './slots.js';
+import { OutfittingModule, ProjectileRangeBoundaries } from './modules.js';
+import { PowerBudget } from './power.js';
+import { HeatMetrics } from './heat.js';
+import { ShieldMetrics } from './shields.js';
+import { ArmourMetrics } from './armour.js';
+import { WeaponMetrics, WeaponTotals } from './weapons.js';
+import { AmmunitionCapacity } from './ammunition.js';
+import { WeaponsCapacitorMetrics } from './weapons-capacitor.js';
+import { DistributorMetrics } from './distributor.js';
+import { MobilityMetrics } from './mobility.js';
+import { ShieldRecovery, CellBankSummary } from './shield-recovery.js';
+import { PreEngineeredVariant } from './pre-engineered.js';
+import { SourcePurchaseRecord } from './source-purchase.js';
+import { CalculationResult, FuelCapacity } from './loadout-calculations.js';
+import { ModuleFitConstraint, LoadoutIssueParams, LoadoutValidation } from './loadout-validation.js';
 import './engineering-options.js';
 import './resistances.js';
+
+/**
+ * Immutable fitted-module snapshots returned by {@link ShipLoadout}.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A point-in-time, deeply frozen view of the module fitted in one slot.
+ *
+ * The view is detached from its {@link ShipLoadout}: later edits do not change it, and
+ * mutating it throws. Fetch a new view with {@link ShipLoadout.fittedModuleAt} after a
+ * state-changing edit. All mutations live on `ShipLoadout`, keyed by {@link slot}; this
+ * avoids the stale-handle lifecycle that a live proxy would otherwise need.
+ *
+ * @example
+ * ```ts
+ * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ *
+ * declare const build: ShipLoadout;
+ *
+ * const before = build.fittedModuleAt('FrameShiftDrive')!;
+ * build.applyBlueprint(before.slot, 'FSD_LongRange', { grade: 5 });
+ * const after = build.fittedModuleAt(before.slot)!;
+ * before.engineering; // unchanged
+ * after.engineering;  // the applied blueprint
+ * ```
+ */
+interface FittedModule {
+    /** Slot key in the build's own spelling. */
+    readonly slot: string;
+    /** Frontier module symbol, e.g. `"Int_Hyperdrive_Size6_Class5"`. */
+    readonly symbol: string;
+    /** Whether the module was powered on, or `undefined` when unspecified. */
+    readonly on: boolean | undefined;
+    /** Zero-based power-priority group, or `undefined` when unspecified. */
+    readonly priority: number | undefined;
+    /** Module health in `[0, 1]`, or `undefined` when unspecified. */
+    readonly health: number | undefined;
+    /** Captured purchase value in credits, or `undefined` when unspecified. */
+    readonly value: number | undefined;
+    /** Applied engineering state; otherwise `undefined`. */
+    readonly engineering: ModuleEngineering | undefined;
+    /** Detached, journal-shaped fitted record. */
+    readonly raw: LoadoutModule;
+    /**
+     * Snapshotted fitted-article stats before its journal modifier block is folded, or
+     * `null` when unresolved.
+     *
+     * A stock or ordinarily engineered module exposes its base catalogue record. A fixed
+     * pre-engineered variant exposes its resolved article record here as well as through
+     * {@link effectiveStats}, so stats omitted by a journal capture still describe the
+     * article. Clearing or replacing that fixed engineering restores the stock record
+     * before applying the next recipe.
+     */
+    readonly stats: OutfittingModule | null;
+    /**
+     * Post-engineering module stats, or `null` when unresolved. For weapons, journal
+     * damage per second is resolved back to per-round damage and falloff is capped at
+     * maximum range. Exact damage components follow the engineered total and disappear
+     * when a damage conversion replaces them with a fractional distribution.
+     * A module engineered through {@link ShipLoadout.applyBlueprint} also retains
+     * recipe-only burst values that its journal-shaped modifier block does not serialize.
+     * A festive variant fitted through {@link ShipLoadout.setPreEngineeredVariant} uses
+     * its fixed modifier block.
+     */
+    readonly effectiveStats: OutfittingModule | null;
+    /** Fully rearmed ammunition capacity, or `null` for modules without ammunition. */
+    readonly ammunition: AmmunitionCapacity | null;
+    /** Identified fixed pre-engineered variant, or `null` when not uniquely identified. */
+    readonly preEngineeredVariant: PreEngineeredVariant | null;
+}
+
+/**
+ * Immutable slot snapshots returned by {@link ShipLoadout}.
+ *
+ * @packageDocumentation
+ */
+
+/** Stable reason a hull mount cannot be emptied through {@link ShipLoadout.removeModule}. */
+type ImmovableReason = 'cargoHatch' | 'moduleLimit' | 'requiredSlot';
+/**
+ * A point-in-time, deeply frozen view of one hull mount.
+ *
+ * The view is detached from its {@link ShipLoadout}; after an edit that changes the
+ * build, call {@link ShipLoadout.slots} again for the current view. Mutations and candidate
+ * filtering stay on `ShipLoadout` and take the slot `key`, leaving this value serializable
+ * and free of lifecycle rules.
+ *
+ * @example
+ * Walking a build's mounts. Slot keys come from the game and are not derivable from
+ * position, so read the slot's `key` rather than composing one.
+ *
+ * ```ts
+ * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ * import type { LoadoutEvent } from '@elite-dangerous-almanac/core/ships/slef';
+ *
+ * declare const event: LoadoutEvent;
+ *
+ * // Figures below are one build's — a Federal Corvette.
+ * const build = ShipLoadout.fromLoadout(event);
+ *
+ * build.slots().length; // -> 38   every mount on the hull
+ * build.slots('hardpoint').length; // -> 7
+ *
+ * const first = build.slots('hardpoint')[0];
+ * first?.key; // -> 'HugeHardpoint1'      what ShipLoadout.setModule takes
+ * first?.name; // -> 'Huge Hardpoint 1'   what a UI shows
+ * first?.size; // -> 4
+ * first?.module?.symbol; // -> 'hpt_beamlaser_gimbal_huge'; undefined when the mount is empty
+ * ```
+ *
+ * @example
+ * The view is a snapshot, not a handle — re-read it after an edit.
+ *
+ * ```ts
+ * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ * import { HARDPOINT_MODULES } from '@elite-dangerous-almanac/core/ships/modules-hardpoint';
+ * import { getModuleBySymbol } from '@elite-dangerous-almanac/core/ships/modules';
+ *
+ * const build = ShipLoadout.empty('Sidewinder');
+ * const before = build.slots('hardpoint')[0];
+ * before?.key; // -> 'SmallHardpoint1'
+ * before?.module; // -> null
+ *
+ * const pulse = getModuleBySymbol('Hpt_PulseLaser_Fixed_Small', HARDPOINT_MODULES);
+ * if (pulse) build.setModule('SmallHardpoint1', pulse);
+ *
+ * before?.module; // -> still null — `before` describes the build as it was
+ * build.slots('hardpoint')[0]?.module?.symbol; // -> 'Hpt_PulseLaser_Fixed_Small'
+ * ```
+ */
+type LoadoutSlot = BuildSlot & {
+    /** Human-readable label, e.g. `"Frame Shift Drive"`. */
+    readonly name: string;
+    /** Frozen fitted-module snapshot, or `null` when this mount is empty. */
+    readonly module: FittedModule | null;
+    /** Whether {@link ShipLoadout.removeModule} may empty this mount. */
+    readonly removable: boolean;
+    /**
+     * Machine-readable reason the mount cannot currently be emptied: `cargoHatch` for
+     * the built-in hatch, `requiredSlot` for a core or armour mount, or `moduleLimit`
+     * when removing a fitted allowance-increasing module would leave too many limited
+     * modules. Absent when {@link removable} is true.
+     */
+    readonly immovableReason?: ImmovableReason;
+};
+
+/**
+ * {@link ShipLoadout} — a mutable fitted-ship model that both **answers questions**
+ * about a build and **edits** it.
+ *
+ * Load one from a SLEF export (or a journal `Loadout` event) to read back the ship's
+ * identity, mass and fuel and ask for jump range and per-jump fuel; or start an
+ * {@link ShipLoadout.default | default} or {@link ShipLoadout.empty | empty} hull,
+ * enumerate its {@link ShipLoadout.slots | slots}, and
+ * {@link ShipLoadout.setModule | fit} and {@link ShipLoadout.removeModule | remove}
+ * modules. It composes the data-free pieces of this folder — the SLEF parser
+ * (`./slef`), the jump-range maths (`./jump-range`), the slot model (`./slots`), and
+ * the module and ship catalogues (each record carrying its own stats).
+ *
+ * Instances are **mutable**: `setModule`/`removeModule` change the build in place and
+ * return `this` for chaining. Values a SLEF export already computed (its
+ * `UnladenMass`, `FuelCapacity`, …) are trusted verbatim; for a build assembled from
+ * scratch those figures are computed from the fitted modules and the hull's stats.
+ * Editing an imported build adjusts the supplied aggregate figures by the changed
+ * module's contribution; when that contribution is unknown, the affected figure is
+ * discarded and recomputed rather than allowed to go stale.
+ * `setModule` snapshots the complete record it receives, including resolved
+ * pre-engineered or caller-supplied stats, so every later metric uses the article that
+ * was actually fitted rather than resolving its symbol back to a stock module.
+ * Slot and fitted-module queries return deeply frozen point-in-time values; edits are
+ * made only through this facade, then observed by querying again.
+ *
+ * **Slot keys are matched case-insensitively.** Frontier writes `FrameShiftDrive` and
+ * `LargeMiningHardpoint1`, but a SLEF producer may lower-case every key as the
+ * specification's own example does — Inara writes `frameshiftdrive` and
+ * `largemininghardpoint1` — and both spellings name the same mount, whether you are
+ * reading it or fitting into it. What a build already carries is never rewritten to
+ * match, so re-exporting an import returns the producer's own spelling untouched.
+ *
+ * @remarks
+ * This is the batteries-included ship facade: resolving arbitrary journal module
+ * ids and engineering recipes requires the complete ship/module, blueprint, and
+ * experimental-effect catalogues. Import `./slef`, `./jump-range`, or an individual
+ * module catalogue instead when you only need one data-free operation or one
+ * outfitting category.
+ *
+ * @example
+ * ```ts
+ * declare const slefJsonString: string;
+ *
+ * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ *
+ * // Read a build:
+ * const build = ShipLoadout.fromSlef(slefJsonString);
+ * build.maxJumpRange();  // -> 89.41  (best single jump, one jump's fuel, no cargo)
+ *
+ * // Assemble one:
+ * import { getModuleBySymbol } from '@elite-dangerous-almanac/core/ships/modules';
+ * import { CORE_MODULES } from '@elite-dangerous-almanac/core/ships/modules-core';
+ * const conda = ShipLoadout.empty('Anaconda');
+ * conda.setModule('FrameShiftDrive', getModuleBySymbol('Int_Hyperdrive_Size6_Class5', CORE_MODULES)!);
+ * conda.slots('optional'); // every optional mount, occupied or empty, with size
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Stable machine-readable reason a {@link ShipLoadout} edit was refused. `immutableSlot`
+ * identifies a mount that cannot be changed at all; `requiredSlot` identifies a core or
+ * armour mount that must remain occupied. A required mount can be replaced but not
+ * emptied.
+ * The remaining codes identify an incompatible fit, a duplicate one-per-ship family,
+ * or a module count beyond the build's current allowance.
+ */
+type LoadoutEditErrorCode = 'immutableSlot' | 'requiredSlot' | 'incompatibleModule' | 'duplicateExclusiveModule' | 'moduleLimitExceeded';
+/**
+ * An editor request that the current hull or build constraints cannot accept.
+ *
+ * @remarks
+ * This remains a `TypeError`, so existing `instanceof TypeError` handling continues to
+ * work. Localized editors should switch on {@link code}, then use {@link constraint}
+ * and {@link params} instead of parsing the English fallback in `message`.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   LoadoutEditError,
+ *   ShipLoadout,
+ * } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ * import { getModuleBySymbol } from '@elite-dangerous-almanac/core/ships/modules';
+ * import { CORE_MODULES } from '@elite-dangerous-almanac/core/ships/modules-core';
+ *
+ * const build = ShipLoadout.empty('SideWinder');
+ * const drive = getModuleBySymbol('Int_Hyperdrive_Size8_Class5', CORE_MODULES)!;
+ * try {
+ *   build.setModule('FrameShiftDrive', drive);
+ * } catch (error) {
+ *   if (error instanceof LoadoutEditError) error.constraint; // -> 'oversized'
+ * }
+ * ```
+ */
+declare class LoadoutEditError extends TypeError {
+    /** Stable category for the refused edit. */
+    readonly code: LoadoutEditErrorCode;
+    /** More specific fitting rule for an `incompatibleModule` failure. */
+    readonly constraint?: ModuleFitConstraint;
+    /** Language-neutral values used by the English fallback message. */
+    readonly params: LoadoutIssueParams;
+    /**
+     * Construct a structured loadout-edit error.
+     *
+     * @param message - English fallback suitable for logs.
+     * @param code - Stable category for the refused edit.
+     * @param params - Language-neutral values used to render the failure.
+     * @param constraint - Specific fitting rule, when `code` is `incompatibleModule`.
+     */
+    constructor(message: string, code: LoadoutEditErrorCode, params: LoadoutIssueParams, constraint?: ModuleFitConstraint);
+}
+/** Result of {@link ShipLoadout.repairFixedMount}, discriminated by `status`. */
+type FixedMountRepairResult = {
+    /** The hull default was installed. */
+    readonly status: 'repaired';
+    /** Slot key in the build's own spelling. */
+    readonly slot: string;
+    /** Installed module symbol. */
+    readonly symbol: string;
+} | {
+    /** The fixed mount already held a valid module. */
+    readonly status: 'unchanged';
+    /** Slot key in the build's own spelling. */
+    readonly slot: string;
+    /** Current module symbol. */
+    readonly symbol: string;
+} | {
+    /** No resolvable hull default exists for the fixed mount. */
+    readonly status: 'defaultUnavailable';
+    /** Slot key in the build's own spelling when one exists, otherwise the request. */
+    readonly slot: string;
+    /** Default module symbol, when the loadout names one but its stats are unavailable. */
+    readonly symbol?: string;
+} | {
+    /** The requested mount is not fixed. */
+    readonly status: 'refused';
+    /** Slot key in the build's own spelling when one exists, otherwise the request. */
+    readonly slot: string;
+    /** Stable refusal reason. */
+    readonly reason: 'notFixedMount';
+};
+/** Optional mass overrides for a single calculation. */
+interface JumpOptions {
+    /** Finite non-negative fuel load, in tonnes. Defaults to the full main tank. */
+    readonly fuel?: number;
+    /** Finite non-negative cargo load, in tonnes. Defaults to `0` (unladen). */
+    readonly cargo?: number;
+}
+/** Options for {@link ShipLoadout.applyBlueprint}. */
+interface ApplyBlueprintOptions {
+    /** The blueprint grade, `1`–`5`. */
+    readonly grade: number;
+    /**
+     * The engineering system's shared quality roll, `0`–`1`. Defaults to `1`
+     * (best roll). A legacy-engineered module's independently advanced attributes cannot be
+     * reconstructed from its single reported quality; import its stated modifiers instead.
+     */
+    readonly quality?: number;
+    /** The experimental (special) effect's Frontier `fdname`, if any. */
+    readonly experimental?: string;
+}
+/** Stable reason {@link ShipLoadout.setExperimentalEffect} cannot perform an edit. */
+type ExperimentalEffectMutationCode = 'emptySlot' | 'unknownModule' | 'notEngineered' | 'unknownExperimentalEffect' | 'unsupportedExperimentalEffect' | 'finalArticle' | 'unsupportedEngineering' | 'unidentifiedPreEngineeredVariant' | 'unresolvedModifiers';
+/** Successful effect-only engineering edit. */
+interface ExperimentalEffectUpdated {
+    /** Discriminator for an edit that changed the fitted module. */
+    readonly kind: 'updated';
+    /** Effect id before the edit, or `null` when none was present. */
+    readonly previousExperimental: string | null;
+    /** Effect id after the edit, or `null` when it was removed. */
+    readonly experimental: string | null;
+}
+/** Effect-only edit that requested the fitted module's current effect. */
+interface ExperimentalEffectUnchanged {
+    /** Discriminator for a no-op edit. */
+    readonly kind: 'unchanged';
+    /** Current effect id, or `null` when none is present. */
+    readonly experimental: string | null;
+}
+/** Effect-only edit that cannot be performed losslessly. */
+interface ExperimentalEffectUnsupported {
+    /** Discriminator for a refused edit. */
+    readonly kind: 'unsupported';
+    /** Stable machine-readable reason for the refusal. */
+    readonly code: ExperimentalEffectMutationCode;
+    /** Language-neutral values describing the fitted article and requested edit. */
+    readonly params: LoadoutIssueParams;
+}
+/** Result of {@link ShipLoadout.setExperimentalEffect}. */
+type ExperimentalEffectMutationResult = ExperimentalEffectUpdated | ExperimentalEffectUnchanged | ExperimentalEffectUnsupported;
+/** Stable reason {@link ShipLoadout.completeEngineeringGrade} cannot normalize a grade. */
+type EngineeringNormalizationCode = 'emptySlot' | 'unknownModule' | 'notEngineered' | 'invalidQuality' | 'unknownExperimentalEffect' | 'unsupportedExperimentalEffect' | 'finalArticle' | 'unsupportedEngineering' | 'unidentifiedPreEngineeredVariant' | 'unresolvedModifiers';
+/** Engineering state that already needs no normalization. */
+interface EngineeringNormalizationUnchanged {
+    /** Discriminator for a no-op normalization. */
+    readonly kind: 'unchanged';
+}
+/** Engineering state recomputed at completed quality. */
+interface EngineeringNormalized {
+    /** Discriminator for a successful normalization. */
+    readonly kind: 'normalized';
+    /** Quality reported by the fitted module before normalization, in `[0, 1)`. */
+    readonly previousQuality: number;
+    /** Completed engineering quality. Always `1`. */
+    readonly quality: 1;
+}
+/** Engineering state that cannot be normalized losslessly. */
+interface EngineeringNormalizationUnsupported {
+    /** Discriminator for a refused normalization. */
+    readonly kind: 'unsupported';
+    /** Stable machine-readable reason for the refusal. */
+    readonly code: EngineeringNormalizationCode;
+    /** Language-neutral values describing the fitted engineering identity. */
+    readonly params: LoadoutIssueParams;
+}
+/** Result of {@link ShipLoadout.completeEngineeringGrade}. */
+type EngineeringNormalizationResult = EngineeringNormalizationUnchanged | EngineeringNormalized | EngineeringNormalizationUnsupported;
+/** Options for the defence figures a build reports. */
+interface DefenceOptions {
+    /**
+     * Pips to the systems capacitor, `0`–`4`, folded into the shield resistances.
+     * Defaults to `0` for {@link ShipLoadout.shieldMetrics} and `4` for
+     * {@link ShipLoadout.shieldRecovery}.
+     */
+    readonly systemsPips?: number;
+}
+/** Optional load and ENG allocation for {@link ShipLoadout.mobilityMetrics}. */
+interface MobilityOptions extends JumpOptions {
+    /** Pips assigned to the engines capacitor, `0`–`4`. Defaults to `4`. */
+    readonly enginesPips?: number;
+}
+/** A standard fuel-and-cargo condition shared by jump and mobility views. */
+type StandardLoad = 'maximum' | 'unladen' | 'laden';
+/** Fuel and cargo carried for a {@link StandardLoad}, both in tonnes. */
+interface StandardLoadInputs {
+    /** Main-tank fuel carried, in tonnes. */
+    readonly fuel: number;
+    /** Cargo carried, in tonnes. */
+    readonly cargo: number;
+}
+/** Optional WEP allocation for {@link ShipLoadout.weaponsCapacitorMetrics}. */
+interface WeaponsOptions {
+    /** Pips assigned to the weapons capacitor, `0`–`4`. Defaults to `4`. */
+    readonly weaponsPips?: number;
+}
+/** Optional SYS, ENG and WEP allocations for {@link ShipLoadout.distributorMetrics}. */
+interface DistributorOptions {
+    /** Pips assigned to the systems capacitor, `0`–`4`. Defaults to `4`. */
+    readonly systemsPips?: number;
+    /** Pips assigned to the engines capacitor, `0`–`4`. Defaults to `4`. */
+    readonly enginesPips?: number;
+    /** Pips assigned to the weapons capacitor, `0`–`4`. Defaults to `4`. */
+    readonly weaponsPips?: number;
+}
+/**
+ * Retail catalogue credits for an assembled build.
+ *
+ * @see {@link ShipLoadout.mercCoinCost} for Mercenary purchase prices.
+ */
+interface RetailCredits {
+    /** Bare hull list price in credits. */
+    readonly hull: number;
+    /** Sum of every priced fitted module, in credits. A lower bound when `unpriced` is non-empty. */
+    readonly modules: number;
+    /** Five percent of the priced hull and modules, truncated to credits. */
+    readonly rebuy: number;
+    /** Fitted modules that could not be priced from the catalogue. */
+    readonly unpriced: readonly {
+        readonly slot: string;
+        readonly symbol: string;
+    }[];
+}
+/** One fitted weapon and what it does, as {@link ShipLoadout.weaponMetrics} reports it. */
+interface FittedWeaponMetrics {
+    /** The hardpoint's slot key, e.g. `"LargeHardpoint1"`. */
+    readonly slot: string;
+    /** The weapon's internal symbol. */
+    readonly symbol: string;
+    /** The weapon's display name, e.g. `"Multi-Cannon"`. */
+    readonly name: string;
+    /** Whether the weapon is switched on — a disabled weapon is excluded from the totals. */
+    readonly enabled: boolean;
+    /** What this weapon does per second, post-engineering. */
+    readonly metrics: WeaponMetrics;
+    /**
+     * How many rounds it holds when fully rearmed, post-engineering — `null` for a laser,
+     * which carries none. A capacity, not a rearm state: see {@link FittedModule.ammunition}.
+     */
+    readonly ammunition: AmmunitionCapacity | null;
+    /** Maximum effective range in metres, absent when the fitted weapon does not state one. */
+    readonly maximumRange?: number;
+    /** Damage-falloff start in metres, absent when the fitted weapon does not state one. */
+    readonly falloffRange?: number;
+    /**
+     * Exact projectile boundary metadata, absent when unavailable. These are not
+     * effective distances and remain separate from {@link maximumRange} and
+     * {@link falloffRange}.
+     */
+    readonly projectileRange?: ProjectileRangeBoundaries;
+    /** Armour-piercing rating, absent when unavailable. */
+    readonly armourPiercing?: number;
+}
+/** A build's firepower: every fitted weapon, and the totals across the enabled ones. */
+interface BuildWeaponMetrics {
+    /**
+     * Every fitted weapon in hull slot order. Weapons in unknown or unmapped slots
+     * follow the known slots in their original source order.
+     */
+    readonly weapons: readonly FittedWeaponMetrics[];
+    /** The additive totals across the **enabled** weapons. */
+    readonly total: WeaponTotals;
+}
+/**
+ * A build's jump ranges at the loads that matter. The three single-jump values and
+ * each total result's `range` are in light-years.
+ */
+interface JumpRangeSummary {
+    /**
+     * Best single jump: no cargo, and only one jump's fuel aboard — the figure the game
+     * and EDSY label "maximum jump range".
+     */
+    readonly max: number;
+    /** Single jump on a full tank with an empty hold. */
+    readonly unladen: number;
+    /** Single jump on a full tank with a full hold. */
+    readonly laden: number;
+    /** Summed range and jump count on one jump's fuel, empty hold. */
+    readonly totalMax: TotalRangeDetails;
+    /** Summed range and jump count on one full tank, empty hold. */
+    readonly totalUnladen: TotalRangeDetails;
+    /** Summed range and jump count on one full tank, full hold. */
+    readonly totalLaden: TotalRangeDetails;
+}
+/** A blueprint candidate for a module symbol, with its grades and availability route. */
+interface AvailableBlueprint {
+    /** The blueprint's Frontier `fdname`, e.g. `"FSD_LongRange"`. */
+    readonly fdname: string;
+    /** The grades the blueprint offers, ascending (e.g. `[1, 2, 3, 4, 5]`). */
+    readonly grades: readonly number[];
+    /**
+     * Why the recipe is listed: `'ordinary'` for the stock module's engineering menu,
+     * or `'mercenary'` for a bespoke recipe attached to a Mercenary purchase.
+     *
+     * @remarks
+     * A Mercenary article shares its module symbol with the stock article. Its bespoke
+     * blueprint is nevertheless available only through that purchase, so a fitted module
+     * carrying the blueprint identifies the article even after a later grade upgrade.
+     * `'mercenary'` means the recipe requires that purchase route.
+     */
+    readonly route: 'ordinary' | 'mercenary';
+}
+/** How to shape a build on the way out — see {@link ShipLoadout.toLoadoutEvent}. */
+interface LoadoutExportOptions {
+    /**
+     * Module order. `'fitted'` — the default — keeps the order the build carries: an
+     * import's own `Modules[]` order, or the order modules were fitted. `'slots'`
+     * re-orders into outfitting-panel order; a module in a slot the hull's layout does
+     * not describe keeps its relative position at the end rather than being dropped.
+     */
+    readonly moduleOrder?: 'fitted' | 'slots';
+    /**
+     * Write `On: true` / `Priority: 0` on modules that carry neither — as a journal
+     * always does and a build assembled here never does. Off by default, following
+     * SLEF's "require what is necessary, do not force the rest".
+     */
+    readonly explicitPower?: boolean;
+    /**
+     * Which credits to quote. `'retail'` — the default — prices the build from the
+     * catalogue: the bare hull's `hullCost`, every fitted module's list price, and a
+     * `Rebuy` of 5% of the two.
+     *
+     * `'source'` quotes the build's {@link ShipLoadout.sourcePurchase | source purchase
+     * record} instead — `HullValue`, `ModulesValue`, `Rebuy` and the per-module `Value`
+     * figures exactly as the capture stated them, and nothing where it stated nothing.
+     * An unedited capture therefore re-exports its own credits unchanged.
+     *
+     * Each captured figure is pinned to what it was paid for, so an edit narrows the
+     * export rather than staling it. A slot whose module has been swapped is left
+     * unpriced, because the figure was paid for the article that *was* fitted; and
+     * `ModulesValue` and `Rebuy` are dropped once any priced module has been swapped or
+     * removed, since they then cover an article no longer aboard. Removing a module the
+     * capture listed but never priced is the one case this cannot detect: only the
+     * capture ever knew which unpriced modules its total counted. The built-in cargo hatch
+     * is never purchasable, so normalising an unpriced or zero-priced captured hatch does
+     * not invalidate the totals. A non-zero captured hatch value is treated like any
+     * other priced replaced article.
+     *
+     * `HullValue` always stands: a captured hull figure names no slot, so no edit
+     * narrows it. Note that on a game capture it counts the hull *with* its stock
+     * fittings, and removing one of those leaves it overstating what is aboard.
+     *
+     * A build with no source record — one assembled here, or a capture that quoted no
+     * credits — exports no credit figure at all rather than falling back to retail.
+     */
+    readonly credits?: 'retail' | 'source';
+}
+/** As {@link LoadoutExportOptions}, plus the SLEF envelope — see {@link ShipLoadout.toSlef}. */
+interface SlefExportOptions extends LoadoutExportOptions {
+    /**
+     * The envelope header identifying the exporting application.
+     *
+     * SLEF attribution belongs to the application producing the export, not to this
+     * calculation library, so callers must provide it.
+     */
+    readonly header: SlefHeader;
+    /** Spaces per indent for {@link ShipLoadout.toSlefString}. `0` (the default) is compact. */
+    readonly indent?: number;
+}
+/**
+ * A fitted ship — read a SLEF export, or assemble a hull from scratch.
+ *
+ * @remarks
+ * Jump calculations resolve the frame shift drive's constants from the drive's module
+ * record, applying any engineering the build carries (a Long Range blueprint's
+ * `FSDOptimalMass`, for instance). For a SLEF build, mass comes from the export's
+ * `UnladenMass`; for an assembled build it is the hull mass plus every fitted module's
+ * mass (armour defaults to the zero-mass lightweight alloy).
+ *
+ * @example
+ * Read a build a player already flies, and ask it what an outfitting screen shows.
+ * Every figure below is one build's — a Krait Phantom explorer. Figures the capture
+ * already stated — `unladenMass` here — are trusted verbatim; the rest are computed
+ * from the fit.
+ *
+ * ```ts
+ * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ * import type { LoadoutEvent } from '@elite-dangerous-almanac/core/ships/slef';
+ *
+ * // A `Loadout` line lifted from a player journal, parsed.
+ * declare const event: LoadoutEvent;
+ *
+ * const build = ShipLoadout.fromLoadout(event);
+ *
+ * build.shipSymbol; // -> 'krait_light'
+ * build.shipName; // -> 'Jenny Longuet'
+ * build.unladenMass; // -> 388.830017   (tonnes)
+ *
+ * build.maxJumpRange(); // -> 60.5478   (ly, best single jump)
+ * build.powerBudget().withinBudget; // -> true
+ * build.shieldMetrics()?.strength; // -> 743.12  (MJ)
+ * build.armourMetrics().hitPoints; // -> 307.8
+ * ```
+ *
+ * @example
+ * Assemble a hull instead. `empty` starts from the shipyard layout, `slots` enumerates
+ * the mounts, and `setModule` fits one — chainable, because the build is mutable.
+ *
+ * ```ts
+ * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ * import { getModuleBySymbol } from '@elite-dangerous-almanac/core/ships/modules';
+ * import { CORE_MODULES } from '@elite-dangerous-almanac/core/ships/modules-core';
+ *
+ * const conda = ShipLoadout.empty('Anaconda');
+ * conda.slots().length; // -> 39   (every mount, occupied or not)
+ * conda.slots('optional').length; // -> 14
+ * conda.validation.complete; // -> false  (nothing fitted yet)
+ *
+ * const fsd = getModuleBySymbol('Int_Hyperdrive_Size6_Class5', CORE_MODULES);
+ * if (fsd) conda.setModule('FrameShiftDrive', fsd);
+ * ```
+ *
+ * @example
+ * Write a build back out. Retail credits are what the catalogue prices the fit at; pass
+ * `credits: 'source'` to export the figures a capture stated it paid instead — see
+ * {@link ShipLoadout.sourcePurchase}.
+ *
+ * ```ts
+ * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ *
+ * declare const build: ShipLoadout;
+ *
+ * build.toLoadoutEvent(); // retail: hull cost plus every module's list price
+ * build.toLoadoutEvent({ credits: 'source' }); // the capture's own figures
+ * build.toSlefString({ header: { appName: 'MyApp', appVersion: '1.0.0' } });
+ * ```
+ */
+declare class ShipLoadout {
+    #private;
+    private constructor();
+    /**
+     * Build from a SLEF export.
+     *
+     * @param input - The SLEF JSON string, or an already-parsed SLEF object (see
+     * {@link parseSlef} for accepted shapes).
+     * @param index - Which entry to take when the export holds several builds.
+     * Defaults to the first.
+     * @returns The loadout for that entry.
+     * @throws {SyntaxError} If `input` is a string that is not valid JSON.
+     * @throws {TypeError} If the export holds no usable loadout, `index` is out of range,
+     * or the selected entry names a hull absent from the catalogue.
+     */
+    static fromSlef(input: unknown, index?: number): ShipLoadout;
+    /**
+     * Build from a bare journal `Loadout` event (the `data` half of a SLEF entry).
+     *
+     * @param event - A `Loadout` event object.
+     * @returns The loadout.
+     * @remarks
+     * Capture/instance state (`timestamp`, `ShipID`, `HullHealth`, `Hot`) and engineering
+     * provenance (`Engineer`, `EngineerID`, `BlueprintID`) are deliberately excluded
+     * from the durable build. See {@link LoadoutEvent} and {@link ModuleEngineering}.
+     * A reward module is identified when its reported stat signature uniquely matches a
+     * catalogue variant. That reward's complete fixed stat block is then used as the fitted
+     * record, including values the capture omits; a separately applied experimental effect
+     * is included when matching and remains authoritative in the captured modifiers. A
+     * Mercenary module is instead identified by the bespoke blueprint available only to its
+     * purchase, including after a later grade upgrade. Its unpublished purchase modifiers
+     * are not inferred; the capture's current engineering remains authoritative. A fixed
+     * catalogue article can also be identified by its complete
+     * symbol/blueprint/grade/experimental identity when a SLEF capture omits the
+     * `Modifiers` key entirely. A present modifier array must pass the stat-signature
+     * match instead, so an older exported stock roll sharing that identity remains stock.
+     * A third-party export could also omit the array from an ordinary historical AX roll;
+     * that record is indistinguishable from the fixed reward, so the catalogue identity
+     * wins. Other under-specified or ambiguous evidence stays unidentified.
+     * An ordinary weapon recipe on a Guardian weapon identifies a final pre-engineered
+     * article; the import preserves that identity, uses the catalogue's complete hand-set
+     * stat block when the exact article is known, exposes no engineering options for it,
+     * and refuses attempts to engineer it further. Explicit journal modifiers remain
+     * authoritative over that stat block.
+     *
+     * The event's credit figures are kept twice over: as the live `hullValue` /
+     * `modulesValue` / `rebuy`, which an edit may invalidate, and as the immutable
+     * {@link sourcePurchase} record, which no edit touches.
+     *
+     * Modules are imported as one complete snapshot: their array order does not affect
+     * per-ship count allowances, and any aggregate violation is reported by
+     * {@link validation}. Use this factory rather than replaying a complete loadout
+     * through the incremental {@link setModule} editor.
+     * A known hull's non-removable cargo hatch is restored from its default loadout when
+     * the capture omits it or supplies an unresolved item for that mount. Because that
+     * hatch has zero mass, capacity and price, restoration preserves the build's live
+     * aggregate mass, capacity and credit figures. Source-credit export retains its
+     * totals only when the captured hatch was unpriced or valued at zero.
+     *
+     * @throws {TypeError} If the event is not shaped like one. What is checked is the
+     * structure a build is assembled from, and the types of the fields naming things in
+     * it: `event` must be an object with an array of module objects in `Modules`; each
+     * module needs a string `Slot` and `Item`, and no two may claim the same slot; a
+     * module's `Engineering` must be an object, and that block's `Modifiers` an array of
+     * objects each carrying a string `Label`, whenever their key is there **at all**;
+     * `event.Ship` must name a known hull; the block's `BlueprintName` and its
+     * `ExperimentalEffect` must be strings **when they carry a value**. Every remaining
+     * field — every number, every
+     * flag, a modifier's value beside its label — is trusted, so use
+     * {@link ShipLoadout.fromSlef} (or {@link parseSlef}) for input you did not produce,
+     * which reports all of them.
+     *
+     * A modifier's `Label` is required rather than checked-when-present because it is
+     * the only thing saying which stat moved: {@link fittedModuleAt} and the
+     * pre-engineered identification both read it unconditionally, so an entry without
+     * one would import cleanly and then break the build it produced.
+     *
+     * `Ship`, `Engineering` and `Modifiers` are fields where `null` is not an omission:
+     * `Ship` is required, while a relay writing `null` for an optional block or list it
+     * does not have would otherwise be read as one. A partial `Engineering` block is
+     * accepted because a capture may state modifiers without naming the recipe.
+     */
+    static fromLoadout(event: LoadoutEvent): ShipLoadout;
+    /**
+     * Start a new build for a hull with no editable modules fitted.
+     *
+     * @param shipSymbol - The hull's internal symbol, e.g. `"Anaconda"`
+     * (case-insensitive).
+     * @returns An otherwise empty loadout whose {@link slots} come from the hull's
+     * declared layout. The hull's immutable default cargo hatch is fitted because it
+     * is part of the ship rather than an outfitting choice.
+     * @throws {TypeError} If `shipSymbol` is not a string, or no hull with that symbol
+     * has a known slot layout.
+     * @example
+     * ```ts
+     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * ShipLoadout.empty('Sidewinder').slots('hardpoint').length; // -> 2
+     * ```
+     */
+    static empty(shipSymbol: string): ShipLoadout;
+    /**
+     * Start a new build with the modules supplied on a stock ship.
+     *
+     * @param shipSymbol - The hull's internal symbol, e.g. `"SideWinder"`
+     * (case-insensitive).
+     * @returns A complete, ready-to-edit stock loadout. The build is independent of the
+     * frozen shared catalogue: edits affect this instance only.
+     * @throws {TypeError} If `shipSymbol` is not a string, or no default loadout exists
+     * for that hull.
+     * @remarks
+     * This batteries-included factory resolves calculations through the complete module
+     * catalogue already used by `ShipLoadout`. If only the stock slot/module identities
+     * are needed, `getDefaultLoadout` from `./default-loadouts` avoids that cost.
+     * @example
+     * ```ts
+     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * const stock = ShipLoadout.default('SideWinder');
+     * stock.validation.complete; // -> true
+     * stock.fittedModuleAt('FrameShiftDrive')?.symbol;
+     * // -> 'Int_Hyperdrive_Size2_Class1'
+     * ```
+     */
+    static default(shipSymbol: string): ShipLoadout;
+    /** The hull's internal id, e.g. `"explorer_nx"`. */
+    get shipSymbol(): string;
+    /** The player-given ship name, or `null` if the build has none. */
+    get shipName(): string | null;
+    /** The player-given ID plate, or `null` if the build has none. */
+    get shipIdent(): string | null;
+    /**
+     * Hull + modules mass with an empty tank and no cargo, in tonnes, or `null` if it
+     * cannot be determined (no `UnladenMass` in the export and a fitted module has no
+     * known mass).
+     *
+     * @remarks
+     * A SLEF export's `UnladenMass` is trusted verbatim. Otherwise the mass is the
+     * hull's `hullMass` plus every fitted module's mass (post-engineering), with armour
+     * at the zero-mass lightweight default.
+     */
+    get unladenMass(): number | null;
+    /**
+     * Unladen mass with diagnostics for every missing input.
+     *
+     * @returns A complete imported or computed mass, otherwise `null` plus the module
+     * fields that prevented the calculation.
+     */
+    get unladenMassResult(): CalculationResult<number>;
+    /**
+     * Fuel-tank capacities, in tonnes, or `null` when a tank's capacity is unknown. A
+     * SLEF export's `FuelCapacity` is used when present;
+     * otherwise the main capacity is the sum of the fitted fuel tanks and the reserve
+     * comes from the hull's stats.
+     */
+    get fuelCapacity(): FuelCapacity | null;
+    /** Fuel capacity with diagnostics instead of unknown tanks collapsing to zero. */
+    get fuelCapacityResult(): CalculationResult<FuelCapacity>;
+    /**
+     * Cargo capacity, in tonnes, or `null` when a fitted optional module cannot be
+     * classified. A SLEF export's `CargoCapacity` is used when present; otherwise it is
+     * the sum of the fitted cargo racks.
+     */
+    get cargoCapacity(): number | null;
+    /** Cargo capacity with diagnostics instead of unknown racks collapsing to zero. */
+    get cargoCapacityResult(): CalculationResult<number>;
+    /**
+     * Hull cost in credits represented by the build, or `null` if unknown.
+     *
+     * @remarks
+     * This is the live figure, kept coherent with edits: an import's own `HullValue`
+     * until something invalidates it. For the capture's figure as captured — which no
+     * edit changes — read {@link sourcePurchase}.
+     */
+    get hullValue(): number | null;
+    /**
+     * Fitted-modules cost in credits represented by the build, or `null` if
+     * unknown — including after an edit discarded an import's figure, since no catalogue
+     * records what a replaced module was bought for. {@link sourcePurchase} keeps the
+     * captured figure regardless.
+     */
+    get modulesValue(): number | null;
+    /**
+     * Insurance rebuy cost in credits represented by the build, or `null` if
+     * unknown. Discarded by an edit for the same reason as {@link modulesValue}, and
+     * likewise preserved by {@link sourcePurchase}.
+     */
+    get rebuy(): number | null;
+    /**
+     * What the capture this build came from said was **paid** for it — a read-only
+     * {@link SourcePurchaseRecord}, or `null` for a build assembled here or imported
+     * from a capture that quoted no credits at all.
+     *
+     * @remarks
+     * The record is provenance about the source, so it is fixed at import and **survives
+     * every edit**: fit, remove or engineer whatever you like and it still reports the
+     * figures the capture carried, for the modules the capture carried them for. That is
+     * what {@link hullValue}, {@link modulesValue} and {@link rebuy} cannot do — they
+     * describe the build in hand, so an edit that invalidates one drops it.
+     *
+     * The two answer different questions and neither substitutes for the other. A
+     * captured price belongs to one commander's purchase history, discounts included;
+     * the library's own figures are catalogue retail. Export picks between them
+     * explicitly, and quotes retail unless asked otherwise — see
+     * {@link LoadoutExportOptions.credits}.
+     *
+     * @example
+     * ```ts
+     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     * import { getSourceModuleValue } from '@elite-dangerous-almanac/core/ships/source-purchase';
+     *
+     * declare const slefJson: string;
+     *
+     * const build = ShipLoadout.fromSlef(slefJson);
+     * const paid = build.sourcePurchase!;
+     * paid.hullValue; // -> 189326510, as captured
+     * getSourceModuleValue(paid, 'powerplant')?.value; // -> what that plant cost its owner
+     *
+     * build.removeModule('Slot05_Size4');
+     * build.modulesValue;                 // -> null   unavailable after the edit
+     * paid.modulesValue;                  // -> 192625195, the captured figure
+     * ```
+     */
+    get sourcePurchase(): SourcePurchaseRecord | null;
+    /**
+     * Structural validity and operational completeness of this build.
+     *
+     * @remarks
+     * Optional, hardpoint and utility mounts may be empty. Armour and all seven core
+     * mounts must be filled for `complete` to be true. An unknown module is incomplete;
+     * a module in a nonexistent or incompatible slot is invalid. Exclusive
+     * families and per-ship module-count allowances must also be satisfied.
+     */
+    get validation(): LoadoutValidation;
+    /**
+     * Frozen point-in-time views of the hull's mounts in outfitting-panel order.
+     *
+     * @param kind - Optionally keep only one mount kind. Omit it for every mount.
+     * @returns Detached, frozen slot views. Repeated reads for the same `kind` reuse the
+     * same snapshots until a state-changing edit.
+     * @example
+     * ```ts
+     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * const emptyHardpoints = ShipLoadout.empty('Sidewinder').slots('hardpoint');
+     * emptyHardpoints.every((slot) => slot.module === null); // true
+     * ```
+     */
+    slots(kind?: SlotKind): readonly LoadoutSlot[];
+    /**
+     * A deeply frozen, point-in-time view of the module in a slot.
+     *
+     * @param slotKey - Slot key, matched case-insensitively.
+     * @returns A detached, frozen view, or `null` when the slot is empty or unknown.
+     * @throws {TypeError} If `slotKey` is not a string.
+     */
+    fittedModuleAt(slotKey: string): FittedModule | null;
+    /**
+     * Every fitted module as a deeply frozen point-in-time view.
+     *
+     * @returns Detached module snapshots in the order the build carries them. The array
+     * and every nested record are frozen; query again after an edit for current state.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * build.fittedModules().map((module) => `${module.slot}: ${module.symbol}`);
+     * ```
+     */
+    fittedModules(): readonly FittedModule[];
+    /**
+     * Return the computable blueprint candidates for a fitted module symbol.
+     *
+     * @param slotKey - Slot key, matched case-insensitively.
+     * @returns Frozen blueprint descriptors: the ordinary engineering menu first, then
+     * bespoke Mercenary upgrade recipes. An `'ordinary'` candidate is available to the
+     * stock module; a `'mercenary'` candidate is purchase-specific. Applying that bespoke
+     * blueprint identifies the matching Mercenary article even though its bare module
+     * symbol does not.
+     * Returns an empty array when the slot is empty, unresolved or final, or the module
+     * symbol has neither route.
+     * @throws {TypeError} If `slotKey` is not a string.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * build.availableBlueprints('FrameShiftDrive').map(({ fdname }) => fdname);
+     * ```
+     */
+    availableBlueprints(slotKey: string): readonly AvailableBlueprint[];
+    /**
+     * Return the computable experimental effects offered to a fitted module.
+     *
+     * @param slotKey - Slot key, matched case-insensitively.
+     * @returns Frozen Frontier effect ids in engineering-menu order, or an empty array
+     * when the slot is empty, unresolved, final, or has no experimental menu.
+     * @throws {TypeError} If `slotKey` is not a string.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * build.availableExperimentalEffects('FrameShiftDrive');
+     * // -> ['special_fsd_heavy', ...]
+     * ```
+     */
+    availableExperimentalEffects(slotKey: string): readonly string[];
+    /**
+     * The modules that fit a given slot — its size, kind and any restriction all
+     * satisfied, with candidates that would worsen a one-per-ship or module-count limit
+     * omitted.
+     *
+     * @param slotKey - The slot key to fit, matched case-insensitively (journal spelling).
+     * @returns The fitting modules, in complete-catalogue order.
+     * @throws {RangeError} If the hull has no slot with that key.
+     * @throws {TypeError} If `slotKey` is not a string.
+     * @example
+     * ```ts
+     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * ShipLoadout.empty('Anaconda').modulesForSlot('FrameShiftDrive');
+     * ```
+     */
+    modulesForSlot(slotKey: string): OutfittingModule[];
+    /**
+     * Restore a missing, unresolved or invalid fixed mount from this hull's stock loadout.
+     *
+     * @remarks
+     * This is the narrow repair path for mounts that {@link setModule} deliberately does
+     * not expose as ordinary edits, including the built-in cargo hatch. Live aggregates
+     * are updated by the same rules as every package-owned refit. The immutable
+     * {@link sourcePurchase} record is unchanged; source-credit export leaves a replaced
+     * slot unpriced, while its aggregate totals remain valid for an unpriced or
+     * zero-priced cargo hatch. Resolved valid core and armour alternatives are left
+     * unchanged.
+     *
+     * @param slotKey - Fixed slot key, matched case-insensitively.
+     * @returns A frozen {@link FixedMountRepairResult}. Refusals leave the build unchanged.
+     * @throws {TypeError} If `slotKey` is not a string.
+     * @throws {RangeError} If a known hull has no slot with that key.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const imported: ShipLoadout;
+     * const result = imported.repairFixedMount('CargoHatch');
+     * if (result.status === 'repaired') console.log(result.symbol.toLowerCase());
+     * ```
+     */
+    repairFixedMount(slotKey: string): FixedMountRepairResult;
+    /**
+     * Fit a module into a slot, replacing whatever is there.
+     *
+     * @remarks
+     * This is an incremental editor: every call must avoid worsening the current
+     * build's module-count excess. Fit an allowance-increasing module before the weapons
+     * it permits. To consume a complete order-independent snapshot, use
+     * {@link ShipLoadout.fromLoadout}.
+     *
+     * @param slotKey - The slot key to fit into, matched case-insensitively (journal
+     * spelling). An occupied slot keeps the key the build already spells it with, so
+     * fitting into an import never renames one of its mounts.
+     * @param module - The module to fit (resolve it from a catalogue first, e.g. with
+     * {@link getModuleBySymbol}). The complete record is snapshotted, so a result from
+     * `getPreEngineeredStats` or a caller-supplied catalogue keeps its resolved stats.
+     * @returns `this`, for chaining.
+     * @throws {RangeError} If the hull has no slot with that key.
+     * @throws {TypeError} If `slotKey` is not a string; `module` is null/undefined (e.g. a
+     * `getModuleBySymbol` miss) or is not an outfitting module at all.
+     * @throws {LoadoutEditError} If the module does not fit the slot (wrong kind, too
+     * large, or a restriction the module does not satisfy), conflicts with a one-per-ship
+     * family already fitted elsewhere, or worsens a per-ship module-count excess.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * import { getModuleBySymbol } from '@elite-dangerous-almanac/core/ships/modules';
+     * import { CORE_MODULES } from '@elite-dangerous-almanac/core/ships/modules-core';
+     * const fsd = getModuleBySymbol('Int_Hyperdrive_Size6_Class5', CORE_MODULES)!;
+     * const tank = getModuleBySymbol('Int_FuelTank_Size6_Class3', CORE_MODULES)!;
+     * build.setModule('FrameShiftDrive', fsd).setModule('Slot01_Size7', tank);
+     * ```
+     */
+    setModule(slotKey: string, module: OutfittingModule): this;
+    /**
+     * Empty a slot.
+     *
+     * @param slotKey - The slot key to clear, matched case-insensitively (journal
+     * spelling).
+     * @returns `this`, for chaining. Clearing an already-empty removable slot is a no-op.
+     * @throws {TypeError} If `slotKey` is not a string.
+     * @throws {LoadoutEditError} If the slot is the built-in cargo hatch; is a required
+     * core or armour mount; or removing the module would worsen a per-ship module-count
+     * excess. Required mounts may be replaced with {@link setModule} but cannot be
+     * emptied.
+     */
+    removeModule(slotKey: string): this;
+    /**
+     * Engineer the module in a slot — apply a blueprint (with a grade and quality) and
+     * an optional experimental effect, computing the resulting stat modifiers.
+     *
+     * The modifiers are stored with journal-equivalent labels and numeric values on the
+     * fitted module, so the build's jump-range and mass calculations pick them up
+     * automatically. The optional journal display-direction hint `LessIsGood` is omitted.
+     * The block keeps the `BlueprintName` you passed, so it reads back the way the build
+     * declared it. Values use Frontier's float32 arithmetic, and weapon recipe internals
+     * such as `BurstInterval` are exposed as the derived `RateOfFire` and
+     * `DamagePerSecond` labels a journal writes. Module-specific aliases likewise use the
+     * journal spelling (`MaximumRange` for a module's maximum range and `Range` for a
+     * scanner range).
+     * Recipe-only values remain available through {@link FittedModule.effectiveStats} and
+     * build calculations even though a journal does not serialize their labels; this is
+     * what keeps burst and reload-cycle calculations faithful after applying a recipe.
+     *
+     * **Which recipe an id names can depend on the module.** The game writes
+     * `Sensor_LongRange` and `Sensor_WideAngle` for both a sensor suite's modification and a
+     * utility scanner's, and the two roll different stats in opposite directions — Long
+     * Range costs the suite mass and the scanner power draw. So the id is resolved against
+     * the module's menu before anything is computed, and a wake scanner engineered
+     * `Sensor_LongRange` gets the scanner's numbers, which `BLUEPRINTS` keys
+     * `Scanner_LongRange`. Reading a stored block back the same way means resolving it the
+     * same way: `resolveBlueprintForModule` in `ships/blueprint-journal` is that lookup.
+     *
+     * @param slotKey - The slot whose module to engineer, matched case-insensitively
+     * (journal spelling).
+     * @param fdname - The blueprint recipe's Frontier `fdname`, e.g. `"FSD_LongRange"`.
+     * @param options - {@link ApplyBlueprintOptions}: `grade` (1–5), optional `quality`
+     * (0–1, default 1), and optional `experimental` effect `fdname`. A nullish
+     * `experimental` means no effect, the same as leaving it out. Each is read once,
+     * before anything is checked, so an accessor cannot answer the check and the use
+     * differently.
+     * @returns `this`, for chaining.
+     * @throws {RangeError} If the slot is empty, or the blueprint/grade/experimental is
+     * unknown, or `quality` is outside `[0, 1]`.
+     * @throws {TypeError} If `slotKey` or `fdname` is not a string, `options` is not an
+     * object, or `options.experimental` carries a value that is not a string — a nullish
+     * one is no effect, not a wrong type; the fitted module has no stats to engineer; or the id names a
+     * fixed event-reward identity, which names no craftable recipe; or the module is not offered the blueprint — by
+     * its engineering menu, by the journal spelling of an entry on that menu, by the
+     * generic spelling of a recipe that menu lists under a family's name, or by being a
+     * Mercenary article sold at grade 1 with that bespoke recipe; the fitted article is
+     * final and accepts no further engineering;
+     * or the module is not offered the experimental effect, which its
+     * menu alone decides; or the catalogue does not carry every base stat the recipe
+     * modifies. Incomplete engineering is rejected rather than stored as a partial journal
+     * modifier block.
+     * @example
+     * ```ts
+     * import { getModuleBySymbol } from '@elite-dangerous-almanac/core/ships/modules';
+     * import { CORE_MODULES } from '@elite-dangerous-almanac/core/ships/modules-core';
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * const fsd = getModuleBySymbol('Int_Hyperdrive_Size6_Class5', CORE_MODULES)!;
+     *
+     * build.setModule('FrameShiftDrive', fsd)
+     *      .applyBlueprint('FrameShiftDrive', 'FSD_LongRange', {
+     *          grade: 5,
+     *          experimental: 'special_fsd_heavy',
+     *      });
+     * build.maxJumpRange(); // uses the engineered optimal mass
+     * ```
+     */
+    applyBlueprint(slotKey: string, fdname: string, options: ApplyBlueprintOptions): this;
+    /**
+     * Add, replace or remove only the fitted module's experimental effect.
+     *
+     * Ordinary and Mercenary engineering is recomputed at its current blueprint, grade
+     * and quality. A fixed reward instead retains its hand-authored modifiers and
+     * purchase identity while the requested effect is composed with them. Refused edits
+     * leave the build unchanged and return stable structured data.
+     *
+     * @param slotKey - The engineered slot, matched case-insensitively.
+     * @param experimental - Experimental-effect `fdname`, or `null` to remove the effect.
+     * @returns A frozen result identifying an update, no-op or lossless refusal.
+     * @throws {TypeError} If `slotKey` or a non-null `experimental` is not a string.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * build.setExperimentalEffect('FrameShiftDrive', 'special_fsd_heavy');
+     * build.setExperimentalEffect('FrameShiftDrive', null);
+     * ```
+     */
+    setExperimentalEffect(slotKey: string, experimental: string | null): ExperimentalEffectMutationResult;
+    /**
+     * Recompute the fitted module's current engineering identity at quality `1`.
+     *
+     * Imported modifier values remain authoritative until this method is called. An
+     * ordinary or Mercenary recipe is rerolled through the package calculator; a fixed
+     * reward rebuilds its hand-authored modifiers and optional effect without losing its
+     * purchase identity. A refusal never changes the loadout.
+     *
+     * @param slotKey - The engineered slot, matched case-insensitively.
+     * @returns A frozen result identifying a normalized, unchanged or unsupported state.
+     * @throws {TypeError} If `slotKey` is not a string.
+     * @example
+     * ```ts
+     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * const partial = ShipLoadout.default('SideWinder').applyBlueprint(
+     *     'FrameShiftDrive',
+     *     'FSD_LongRange',
+     *     { grade: 5, quality: 0.42 },
+     * );
+     * const imported = ShipLoadout.fromLoadout(partial.toLoadoutEvent());
+     * imported.completeEngineeringGrade('FrameShiftDrive').kind; // -> 'normalized'
+     * imported.fittedModuleAt('FrameShiftDrive')?.engineering?.Quality; // -> 1
+     * ```
+     */
+    completeEngineeringGrade(slotKey: string): EngineeringNormalizationResult;
+    /**
+     * Fit a pre-engineered variant into a slot, replacing whatever is there.
+     *
+     * The variant's fixed stats and journal engineering block are resolved together.
+     * Articles carry `Level`, `Quality: 1`, any baked experimental effect and their fixed
+     * modifiers. Because the variant names its base module, a decorative identity cannot
+     * be applied to an unrelated damage-bearing module.
+     * A Mercenary variant whose fixed modifier block has not been published retains the
+     * stock catalogue stats and omits `Modifiers` rather than claiming it changes none.
+     *
+     * @param slotKey - The slot key to fit into, matched case-insensitively.
+     * @param variant - The pre-engineered catalogue variant to fit.
+     * @returns `this`, for chaining.
+     * @throws {TypeError} If `variant` is not a pre-engineered variant or one of its
+     * authored modifier labels cannot be resolved for its base module.
+     * @throws {RangeError} If no catalogue row matches the supplied module, blueprint,
+     * grade, experimental effect and acquisition route.
+     * @throws {LoadoutEditError} If the variant's base module does not fit the slot or
+     * violates a fitted-module limit.
+     * @example
+     * ```ts
+     * import { getPreEngineeredVariants } from '@elite-dangerous-almanac/core/ships/pre-engineered';
+     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * const festive = getPreEngineeredVariants('Hpt_FlakMortar_Turret_Medium')
+     *     .find((variant) => variant.blueprint === 'Decorative_Red')!;
+     * const build = ShipLoadout.empty('Krait_MkII')
+     *     .setPreEngineeredVariant('MediumHardpoint1', festive);
+     * build.fittedModuleAt('MediumHardpoint1')?.effectiveStats?.damage; // -> 0.34
+     * ```
+     */
+    setPreEngineeredVariant(slotKey: string, variant: PreEngineeredVariant): this;
+    /**
+     * Strip engineering from a slot's module,
+     * restoring its base stats.
+     *
+     * @param slotKey - The slot to de-engineer, matched case-insensitively (journal
+     * spelling).
+     * @returns `this`, for chaining. A no-op if the slot is empty or unmodified.
+     * @throws {TypeError} If `slotKey` is not a string, or the fitted article is final
+     * pre-engineered and its baked engineering cannot be removed.
+     * @remarks
+     * Clearing a Mercenary article removes its purchase-exclusive blueprint identity.
+     * Its {@link FittedModule.preEngineeredVariant} then reads `null`.
+     */
+    clearEngineering(slotKey: string): this;
+    /**
+     * Switch a fitted module on or off.
+     *
+     * @param slotKey - The slot's journal key, e.g. `"PowerPlant"`, matched
+     * case-insensitively.
+     * @param on - `true` to power it, `false` to switch it off.
+     * @returns `this`, for chaining.
+     * @throws {RangeError} If the slot is empty.
+     * @throws {TypeError} If `slotKey` is not a string.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * build.setModuleEnabled('TinyHardpoint6', false); // an unpowered heat sink
+     * ```
+     */
+    setModuleEnabled(slotKey: string, on: boolean): this;
+    /**
+     * Set a fitted module's power-priority group.
+     *
+     * @param slotKey - The slot's journal key, matched case-insensitively.
+     * @param priority - The journal's **zero-based** group, `0`–`4`. Note that the
+     * outfitting panel — and {@link powerBudget}'s `bands[].priority` — number the same
+     * five groups `1`–`5`.
+     * @returns `this`, for chaining.
+     * @throws {RangeError} If the slot is empty, or `priority` is not an integer in `[0, 4]`.
+     * @throws {TypeError} If `slotKey` is not a string.
+     */
+    setModulePriority(slotKey: string, priority: number): this;
+    /**
+     * This build as a journal `Loadout` event — the `data` half of a SLEF entry.
+     *
+     * @param options - Module ordering and how sparse to be about power state.
+     * @returns A fresh event. Every top-level figure is **recomputed** from the hull and
+     * the fitted modules rather than echoed from whatever an import supplied — the one
+     * exception being the credits, when `credits: 'source'` asks for the capture's own.
+     * Any figure that cannot be worked out is **left out** rather than emitted as a stale
+     * or zero value — SLEF requires nothing beyond `Ship` and `Modules`.
+     *
+     * Credits are quoted at **retail** by default: the bare hull's `hullCost` plus every
+     * fitted module's catalogue list price, with `Rebuy` 5% of the two. A source's own
+     * `HullValue` / `ModulesValue` / `Value` figures are deliberately not quoted here,
+     * because they record one commander's purchase history — the Deep Black's modules
+     * are all 12.25% off list — and purchase discounts are not a property of the build.
+     * They are not lost either: pass `credits: 'source'` to export the
+     * {@link sourcePurchase} record instead, as provenance rather than as a price.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * const event = build.toLoadoutEvent();
+     * event.MaxJumpRange; // recomputed, not the exporter's claim
+     * event.HullValue;    // the catalogue's list price
+     *
+     * build.toLoadoutEvent({ credits: 'source' }).HullValue; // what the capture paid
+     * ```
+     */
+    toLoadoutEvent(options?: LoadoutExportOptions): LoadoutEvent;
+    /**
+     * This build as a one-entry SLEF export.
+     *
+     * @param options - Ordering, power state, and the envelope header.
+     * @returns The export. Several builds travel together as
+     * `toSlef([a.toLoadoutEvent(), b.toLoadoutEvent()])` using the function of the same
+     * name from `./slef`.
+     */
+    toSlef(options: SlefExportOptions): Slef;
+    /**
+     * This build as SLEF JSON — ready to write to a file or put on the clipboard.
+     *
+     * @param options - As {@link toSlef}, plus `indent` (compact by default).
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * build.toSlefString({ header: { appName: 'MyApp', appVersion: '1.0.0' } });
+     * ```
+     */
+    toSlefString(options: SlefExportOptions): string;
+    /**
+     * The resolved frame-shift-drive constants for this build — post-engineering,
+     * with any Guardian FSD Booster folded into `jumpBoost`.
+     *
+     * @throws {TypeError} If the build has no frame shift drive, or its required jump
+     * constants are missing from the stats catalogue.
+     */
+    get frameShiftDrive(): FrameShiftDriveParams;
+    /**
+     * The fitted frame shift drive's dimensionless mass factor at a chosen load.
+     *
+     * @param options - {@link JumpOptions}. `fuel` defaults to a full main tank and
+     * `cargo` to `0`.
+     * @returns `optMass / loadedMass`: `1` at the drive's optimised mass, below `1`
+     * above it and above `1` below it.
+     * @remarks
+     * This is the mass term used by the jump equation, not the three-point performance
+     * curve used by thrusters and shield generators. Main-tank fuel contributes to the
+     * loaded mass; the Guardian FSD Booster's additive range does not contribute to the
+     * factor.
+     * @throws {TypeError} If the build has no usable frame shift drive or its mass
+     * cannot be determined; also if fuel capacity is unknown and `options.fuel` is
+     * omitted.
+     * @throws {RangeError} If fuel or cargo is not finite and non-negative, or loaded
+     * mass is zero.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * build.frameShiftDriveMassFactor({ fuel: 8, cargo: 32 }); // dimensionless
+     * ```
+     */
+    frameShiftDriveMassFactor(options?: JumpOptions): number;
+    /**
+     * Best single-jump range, in light-years — no cargo, and exactly one jump's fuel
+     * aboard (the lightest the ship jumps). This is the figure the game and EDSY label
+     * "maximum jump range".
+     *
+     * @remarks
+     * Returns `0` when no fuel is available — an assembled build with no fuel tank
+     * fitted has an empty main tank, so there is nothing to jump on.
+     * @returns The best single jump, in light-years.
+     * @throws {TypeError} If the build has no usable frame shift drive, or its mass or
+     * fuel capacity cannot be determined.
+     */
+    maxJumpRange(): number;
+    /**
+     * The range of a single jump for a chosen fuel and cargo load, in light-years.
+     *
+     * @param options - {@link JumpOptions}. `fuel` defaults to a full main tank,
+     * `cargo` to `0`.
+     * @returns The jump's range, in light-years.
+     * @throws {TypeError} If the build has no usable frame shift drive or its mass
+     * cannot be determined; also if fuel capacity is unknown and `options.fuel` is
+     * omitted.
+     * @throws {RangeError} If fuel or cargo is not finite and non-negative.
+     */
+    jumpRange(options?: JumpOptions): number;
+    /**
+     * Single-jump range on a full tank with a full cargo hold, in light-years.
+     *
+     * @returns The jump's range, in light-years.
+     * @throws {TypeError} If the build has no usable frame shift drive, or its mass,
+     * fuel capacity or cargo capacity cannot be determined.
+     */
+    ladenJumpRange(): number;
+    /**
+     * The fuel a single jump of a given distance costs, in tonnes.
+     *
+     * @param distance - The jump distance, in light-years.
+     * @param options - {@link JumpOptions}. `fuel` defaults to a full main tank,
+     * `cargo` to `0`.
+     * @returns Fuel used, in tonnes (capped at the drive's max fuel per jump).
+     * @throws {TypeError} If the build has no usable frame shift drive or its mass
+     * cannot be determined; also if fuel capacity is unknown and `options.fuel` is
+     * omitted.
+     * @throws {RangeError} If fuel or cargo is not finite and non-negative.
+     */
+    fuelPerJump(distance: number, options?: JumpOptions): number;
+    /**
+     * Total range and jump count for a chosen fuel and cargo load.
+     *
+     * @param options - {@link JumpOptions}. `fuel` defaults to a full main tank,
+     * `cargo` to `0`.
+     * @returns Summed range in light-years and the jumps made before the tank is empty.
+     * @throws {TypeError} If the build has no usable frame shift drive, or its mass or
+     * fuel capacity cannot be determined; fuel capacity is not required when
+     * `options.fuel` is supplied.
+     * @throws {RangeError} If fuel or cargo is not finite and non-negative, or the
+     * fuel load would require more than 100,000 jumps.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * build.totalRange().jumps; // jumps available from one full main tank
+     * build.totalRange({ fuel: 8, cargo: 32 }).range; // range for that partial load
+     * ```
+     */
+    totalRange(options?: JumpOptions): TotalRangeDetails;
+    /**
+     * Resolve one of the package's standard load conditions for jump and mobility views.
+     *
+     * @param load - `'maximum'` for one jump's fuel and no cargo, `'unladen'` for a
+     * full main tank and no cargo, or `'laden'` for a full main tank and full hold.
+     * @returns Fuel and cargo in tonnes, or structured diagnostics for unavailable
+     * capacities. `'maximum'` also reports every mass or frame-shift-drive fact needed
+     * to use that load in a jump calculation. A complete maximum result can therefore
+     * be passed safely to {@link jumpRange}; it validates the whole fitted drive,
+     * including an active jump booster, even though only the drive's maximum fuel
+     * determines the returned load.
+     * @throws {RangeError} If `load` is not a recognised standard load.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * const load = build.standardLoadResult('maximum');
+     * if (load.complete) build.mobilityMetrics({ ...load.value, enginesPips: 2 });
+     * ```
+     */
+    standardLoadResult(load: StandardLoad): CalculationResult<StandardLoadInputs>;
+    /**
+     * Every jump figure at once — best, unladen, laden, and each load's total.
+     *
+     * @returns The {@link JumpRangeSummary}. Single-jump figures and each total's
+     * `range` are in light-years. For a partial load, call {@link jumpRange} for one
+     * jump or {@link totalRange} for every jump with the `fuel` and `cargo` you
+     * actually have.
+     * @throws {TypeError} If the build has no usable frame shift drive, or its mass,
+     * fuel capacity or cargo capacity cannot be determined.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * const jumps = build.jumpRangeSummary();
+     * jumps.max;    // -> 89.41  (one jump's fuel, empty hold)
+     * jumps.laden;  // -> the range with the hold full
+     * jumps.totalMax.jumps; // the best jump expressed as a total
+     * // Half a tank and 32 t aboard, once the tank is known:
+     * const fuel = build.fuelCapacityResult;
+     * if (fuel.complete) build.jumpRange({ fuel: fuel.value.main / 2, cargo: 32 });
+     * ```
+     */
+    jumpRangeSummary(): JumpRangeSummary;
+    /**
+     * The build's power budget: what the plant makes, what the modules draw with
+     * hardpoints retracted and deployed, and which priority groups stay lit.
+     *
+     * Draws are post-engineering, modules switched off in the journal are skipped, and
+     * weapons (plus the utility fittings that are not always powered) count only
+     * towards the deployed total.
+     *
+     * @returns The {@link PowerBudget}. With no power plant fitted, `available` is `0`
+     * and nothing is powered. An unresolved plant also reports `available: 0`; it is
+     * identified as `powerCapacity` by the mobility, shield and recovery result methods,
+     * not {@link PowerBudget.unknownDraws}. When the entire plant record is unresolved,
+     * {@link validation} also reports `unknownModule`. A fitted module whose draw the
+     * catalogue cannot supply is
+     * named in {@link PowerBudget.unknownDraws} rather than counted as drawing nothing,
+     * which makes every total a lower bound while that list is non-empty. `consumers`
+     * includes modules with positive or unknown draw; passive and zero-draw fittings are
+     * absent.
+     * @throws {RangeError} If a known power capacity or module draw is negative or not
+     * finite.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * const power = build.powerBudget();
+     * power.available;                  // -> 20.4 MW generated
+     * power.deployed;                   // -> 19.02 MW drawn, hardpoints out
+     * power.withinBudget;               // -> true
+     * power.bands[4]?.poweredDeployed;  // -> is priority group 5 still lit?
+     * ```
+     */
+    powerBudget(): PowerBudget;
+    /**
+     * The build's heat: what it idles at, what it runs at flying and jumping, and
+     * whether firing everything cooks it.
+     *
+     * Every figure is post-engineering. The heat a build makes follows what the plant
+     * actually feeds, so a module switched off — or one in a priority group the plant
+     * cannot keep lit — contributes nothing.
+     *
+     * @returns The {@link HeatMetrics}, or `null` when the build has no powered power
+     * plant. A build carrying a module the catalogues cannot resolve is answered rather
+     * than refused. {@link HeatMetrics.unknownDraws} names unknown power contributions;
+     * {@link HeatMetrics.unknownWeaponHeat} names unresolved hardpoints omitted from the
+     * firing scenarios. Read those entries before showing the figures, because a
+     * non-empty diagnostic makes the affected results projections over the rest of the
+     * build rather than complete answers.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * const heat = build.heatMetrics();
+     * heat?.idle.gauge;                      // -> 0.23, i.e. the gauge reads 23%
+     * heat?.firingSustained.overheats;       // -> false: the guns run cool enough to hold
+     * heat?.firingDrained.secondsToOverheat; // -> how long an alpha strike has on an empty WEP
+     * ```
+     */
+    heatMetrics(): HeatMetrics | null;
+    /**
+     * The build's speed, boost and rotation rates at a chosen load and ENG allocation.
+     *
+     * @remarks
+     * Main-tank fuel contributes to the flight model's loaded mass. Reserve-tank fuel
+     * does not: although the statistics panel includes it in the displayed current
+     * mass, ten observed builds reproduce their angular rates only when the reserve is
+     * excluded from the thruster mass curve.
+     *
+     * @param options - Fuel defaults to a full main tank, cargo to `0`, and ENG pips to `4`.
+     * @returns Loaded {@link MobilityMetrics}, or `null` when no fully described
+     * thrusters are powered with hardpoints retracted. Use
+     * {@link mobilityMetricsResult} to distinguish the unavailable conditions.
+     * @throws {TypeError} If mass or an omitted main-tank fuel load cannot be determined.
+     * @throws {RangeError} If fuel or cargo is not finite and non-negative, or
+     * `enginesPips` is outside `[0, 4]`.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * build.mobilityMetrics({ cargo: 32, fuel: 8, enginesPips: 2 })?.speed; // -> m/s
+     * ```
+     */
+    mobilityMetrics(options?: MobilityOptions): MobilityMetrics | null;
+    /**
+     * The build's mobility with a diagnostic when its thrusters or retracted power
+     * supply is unavailable.
+     *
+     * @param options - Fuel defaults to a full main tank, cargo to `0`, and ENG pips to `4`.
+     * @returns A complete {@link MobilityMetrics} value, otherwise `null` plus the input
+     * or fitted-module state that prevented the calculation.
+     * @throws {TypeError} If mass or an omitted main-tank fuel load cannot be determined.
+     * @throws {RangeError} If fuel or cargo is not finite and non-negative, or
+     * `enginesPips` is outside `[0, 4]`.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * const result = build.mobilityMetricsResult({ enginesPips: 2 });
+     * if (result.complete) result.value.speed; // metres per second
+     * else result.issues[0].reason;            // unavailable-state discriminator
+     * ```
+     */
+    mobilityMetricsResult(options?: MobilityOptions): CalculationResult<MobilityMetrics>;
+    /**
+     * The build's shields: strength in megajoules, where it comes from, and the
+     * effective resistances.
+     *
+     * Shield strength scales with the **hull's** mass, not the build's, so fitting
+     * more modules never weakens it. Boosters, Guardian shield reinforcement and any
+     * engineering are all folded in; switched-off or shed boosters and reinforcement
+     * are ignored, while a switched-off or shed generator makes the metric unavailable.
+     *
+     * @param options - {@link DefenceOptions}. `systemsPips` (0–4) folds the SYS
+     * capacitor's own resistance into the reported figures; it defaults to `0`, which
+     * is what an outfitting screen shows.
+     * @returns The {@link ShieldMetrics}, or `null` when the build has no shield
+     * generator powered with hardpoints retracted. Use
+     * {@link shieldMetricsResult} to distinguish the unavailable conditions.
+     * @throws {RangeError} If `systemsPips` is outside `[0, 4]` or not finite.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * const shields = build.shieldMetrics();
+     * shields?.strength;              // -> MJ
+     * shields?.resistances.thermal;   // -> negative on a stock generator
+     * build.shieldMetrics({ systemsPips: 4 })?.resistances.thermal; // -> with 4 pips to SYS
+     * ```
+     */
+    shieldMetrics(options?: DefenceOptions): ShieldMetrics | null;
+    /**
+     * The build's shields with a diagnostic when its hull, generator or retracted
+     * power supply is unavailable.
+     *
+     * @param options - {@link DefenceOptions}. `systemsPips` defaults to `0`.
+     * @returns A complete {@link ShieldMetrics} value, otherwise `null` plus the input
+     * or fitted-module state that prevented the calculation.
+     * @throws {RangeError} If `systemsPips` is outside `[0, 4]` or not finite.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * const result = build.shieldMetricsResult();
+     * if (result.complete) result.value.strength; // megajoules
+     * else result.issues[0].reason;               // unavailable-state discriminator
+     * ```
+     */
+    shieldMetricsResult(options?: DefenceOptions): CalculationResult<ShieldMetrics>;
+    /**
+     * Time for this build's shield to rise after collapse and then regenerate to full.
+     *
+     * @param options - SYS pips in `[0, 4]`, defaulting to `4`.
+     * @returns Recovery rates and seconds, or `null` when no shield generator is powered
+     * with hardpoints retracted. Use
+     * {@link shieldRecoveryResult} to distinguish the unavailable conditions.
+     * A missing distributor or insufficient zero-pip recharge produces `Infinity`.
+     * @throws {RangeError} If `systemsPips` is outside `[0, 4]` or not finite.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * build.shieldRecovery({ systemsPips: 4 })?.recoveryTime; // -> seconds from collapse to 50%
+     * ```
+     */
+    shieldRecovery(options?: DefenceOptions): ShieldRecovery | null;
+    /**
+     * The build's shield recovery with a diagnostic when its hull, generator or
+     * retracted power supply is unavailable.
+     *
+     * @param options - SYS pips in `[0, 4]`, defaulting to `4`.
+     * @returns A complete {@link ShieldRecovery} value, otherwise `null` plus the input
+     * or fitted-module state that prevented the calculation.
+     * @throws {RangeError} If `systemsPips` is outside `[0, 4]` or not finite.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * const result = build.shieldRecoveryResult();
+     * if (result.complete) result.value.recoveryTime; // seconds
+     * else result.issues[0].reason; // unavailable-state discriminator
+     * ```
+     */
+    shieldRecoveryResult(options?: DefenceOptions): CalculationResult<ShieldRecovery>;
+    /**
+     * Every fitted shield cell bank and the usable rearmed reinforcement pool.
+     *
+     * Every fitted bank remains in `banks`, where `powered` says whether it is switched
+     * on and its priority group is fed with hardpoints deployed. The totals include
+     * only those powered banks. A bank whose draw is unresolved is assumed powered,
+     * consistently with {@link powerBudget}; inspect that result's `unknownDraws` when
+     * the distinction matters. A build with no powered power plant — including one
+     * created by {@link empty} before a plant is fitted — reports every bank as
+     * unpowered and returns zero totals.
+     *
+     * @returns A frozen {@link CellBankSummary}; no banks is an empty list and zero totals.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * build.cellBanks().totalRestorable; // -> MJ across every powered fitted cell
+     * ```
+     */
+    cellBanks(): CellBankSummary;
+    /**
+     * Price this build from current catalogue list prices without creating a journal event.
+     *
+     * @returns Hull, module and five-percent rebuy credits. `modules` and `rebuy` remain
+     * lower bounds when {@link RetailCredits.unpriced} is non-empty; built-in hull fittings are free.
+     * @example
+     * ```ts
+     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * ShipLoadout.default('Anaconda').retailCredits().hull; // -> 142456440
+     * ```
+     * @see {@link mercCoinCost} for Mercenary purchase prices.
+     */
+    retailCredits(): RetailCredits;
+    /**
+     * Total the Merc Coin prices of the Mercenary articles fitted to this build.
+     *
+     * @returns The total in Merc Coin, or `0` when no fitted article is a Mercenary
+     * purchase. Credit prices and rebuy remain available from {@link retailCredits}.
+     * @remarks
+     * The total counts both articles fitted through {@link setPreEngineeredVariant} and
+     * purchases implied by applying their Mercenary-only blueprint through
+     * {@link applyBlueprint}. The blueprint identifies the purchase at grade 1 and after
+     * later upgrades; the current grade does not change the original shop price.
+     * @example
+     * ```ts
+     * import { getPreEngineeredVariants } from '@elite-dangerous-almanac/core/ships/pre-engineered';
+     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * const variant = getPreEngineeredVariants('Hpt_Railgun_Fixed_Medium')
+     *     .find((candidate) => candidate.acquisition === 'mercenary')!;
+     * const build = ShipLoadout.default('Python')
+     *     .setPreEngineeredVariant('MediumHardpoint1', variant);
+     * build.mercCoinCost(); // -> 950
+     * ```
+     */
+    mercCoinCost(): number;
+    /**
+     * The build's armour: hull hit points, the bulkhead and reinforcement each
+     * contribute, and the effective resistances.
+     *
+     * @returns The {@link ArmourMetrics}. A build with no armour module fitted is
+     * reported on the stock lightweight alloy the hull
+     * leaves the shipyard with, which is what the game does.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * const hull = build.armourMetrics();
+     * hull.hitPoints;                  // -> total hull points
+     * hull.resistances.explosive;      // -> lightweight alloy is explosively weak
+     * hull.effectiveHitPoints.thermal; // -> thermal damage the hull can soak
+     * ```
+     */
+    armourMetrics(): ArmourMetrics;
+    /**
+     * The build's firepower: DPS, sustained DPS, weapons-capacitor draw, heat and power
+     * draw for every fitted weapon, plus the totals.
+     *
+     * Every figure is post-engineering. A weapon switched off in the journal is still
+     * listed — with its own metrics — but left out of the totals.
+     *
+     * @returns The {@link BuildWeaponMetrics}.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     *
+     * const guns = build.weaponMetrics();
+     * guns.total.damagePerSecond;          // -> burst DPS across the hardpoints
+     * guns.total.sustainedDamagePerSecond; // -> with reloads folded in
+     * guns.total.energyPerSecond;          // -> MW asked of the WEP capacitor
+     * guns.total.powerDraw;                // -> MW asked of the power plant when deployed
+     * guns.weapons[0]?.metrics.damageByType.thermal;
+     * guns.weapons[0]?.maximumRange;        // post-engineering metres, when known
+     * guns.weapons[0]?.armourPiercing;      // post-engineering rating, when known
+     * guns.weapons[0]?.ammunition?.total;  // -> rounds aboard when fully rearmed
+     * ```
+     */
+    weaponMetrics(): BuildWeaponMetrics;
+    /**
+     * WEP-capacitor recharge and endurance while every powered weapon fires.
+     *
+     * @param options - WEP pips in `[0, 4]`, defaulting to `4`.
+     * @returns Actual recharge, sustained draw, net drain and seconds from full to
+     * empty. The deployed power budget is applied to the distributor and weapons, so a
+     * module the plant sheds contributes nothing. A module with an unresolved power
+     * draw is assumed powered, consistently with {@link powerBudget}; inspect its
+     * `unknownDraws` when that distinction matters. With no powered distributor,
+     * capacity and recharge are zero. A load that draws no more than recharge reports
+     * `Infinity` for `timeToDrain`.
+     * @throws {RangeError} If `weaponsPips` is outside `[0, 4]` or not finite.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * build.weaponsCapacitorMetrics({ weaponsPips: 2 }).timeToDrain; // seconds
+     * ```
+     */
+    weaponsCapacitorMetrics(options?: WeaponsOptions): WeaponsCapacitorMetrics;
+    /**
+     * All three power-distributor capacitors at selected pip allocations.
+     *
+     * @param options - SYS, ENG and WEP pips in `[0, 4]`, each defaulting
+     * independently to `4`. The allocations need not sum to six, which permits
+     * independent comparisons of the three maxima.
+     * @returns Capacity, rated four-pip recharge and actual pip-scaled recharge for
+     * SYS, ENG and WEP, or `null` when no distributor is fitted, it is switched off,
+     * its six capacitor stats cannot be resolved, or the retracted power budget sheds
+     * it. The retracted state represents the distributor itself; firing endurance in
+     * {@link weaponsCapacitorMetrics} separately applies the deployed state. A module
+     * with unresolved power draw is assumed powered, consistently with
+     * {@link powerBudget}; inspect its `unknownDraws` when that distinction matters.
+     * @throws {RangeError} If any pip allocation is outside `[0, 4]` or not finite.
+     * @example
+     * ```ts
+     * import type { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+     *
+     * declare const build: ShipLoadout;
+     * const distributor = build.distributorMetrics({
+     *   systemsPips: 2,
+     *   enginesPips: 2,
+     *   weaponsPips: 2,
+     * });
+     * distributor?.engines.rechargeRate; // MJ/s
+     * ```
+     */
+    distributorMetrics(options?: DistributorOptions): DistributorMetrics | null;
+}
+
+export { type ApplyBlueprintOptions, type AvailableBlueprint, type BuildWeaponMetrics, type DefenceOptions, type DistributorOptions, type EngineeringNormalizationCode, type EngineeringNormalizationResult, type EngineeringNormalizationUnchanged, type EngineeringNormalizationUnsupported, type EngineeringNormalized, type ExperimentalEffectMutationCode, type ExperimentalEffectMutationResult, type ExperimentalEffectUnchanged, type ExperimentalEffectUnsupported, type ExperimentalEffectUpdated, type FittedModule, type FittedWeaponMetrics, type FixedMountRepairResult, type ImmovableReason, type JumpOptions, type JumpRangeSummary, LoadoutEditError, type LoadoutEditErrorCode, type LoadoutExportOptions, type LoadoutSlot, type MobilityOptions, type RetailCredits, ShipLoadout, type SlefExportOptions, type StandardLoad, type StandardLoadInputs, type WeaponsOptions };