@elite-dangerous-almanac/core 0.1.8 → 0.2.1

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

@@ -1,25 +1,13 @@
 import { ModuleEngineering, LoadoutModule, LoadoutEvent, SlefHeader, Slef } from './slef.js';
-import { TotalRangeDetails, FrameShiftDriveParams } from './jump-range.js';
 import { BuildSlot, SlotKind } from './slots.js';
-import { EngineeringMaterial } from './engineering.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 { ThrusterParams, MobilityMetrics } from './mobility.js';
-import { ShieldRecovery, CellBankSummary } from './shield-recovery.js';
+import { OutfittingModule } from './modules.js';
 import { PreEngineeredVariant } from './pre-engineered.js';
+import { AmmunitionCapacity } from './ammunition.js';
 import { SourcePurchaseRecord } from './source-purchase.js';
-import { FuelCapacity, CalculationResult } from './loadout-calculations.js';
+import { FuelCapacity } from './loadout-calculations.js';
 import { ModuleFitConstraint, LoadoutIssueParams, LoadoutValidation } from './loadout-validation.js';
 import './engineering-options.js';
 import './module-families.js';
-import './resistances.js';
 
 /**
  * Immutable fitted-module snapshots returned by {@link ShipLoadout}.
@@ -172,10 +160,13 @@ type LoadoutSlot = BuildSlot & {
  * A change made while normalizing a journal or SLEF loadout against the catalogues.
  *
  * @remarks
- * `ShipLoadout.fromLoadout` states the rule these outcomes report: a removable mount is
+ * `ShipLoadout.fromLoadout` states the rules these outcomes report: a removable mount is
  * `emptied` of an article the catalogue cannot resolve, and a fixed mount is `defaulted`
  * to the hull's stock article whenever the source left none it can hold — with a `null`
- * `sourceSymbol` when the source named nothing there at all.
+ * `sourceSymbol` when the source named nothing there at all. A module whose source stated
+ * a recipe and no `Modifiers` reports `unresolvedEngineering` when neither a craftable
+ * recipe nor a catalogued article answers to what it named, because that module alone
+ * keeps the figures of an unengineered one.
  *
  * @example
  * ```ts
@@ -206,11 +197,24 @@ type LoadoutImportOutcome = {
     readonly sourceSymbol: string | null;
     /** Stock module identity installed in the mount. */
     readonly replacementSymbol: string;
+} | {
+    /**
+     * The source stated engineering with no `Modifiers`, and what it named could
+     * not be rolled — an unknown or unoffered blueprint or experimental effect, a
+     * grade or quality outside the recipe, or a base stat the catalogues do not
+     * carry — so this module's figures are the unengineered ones.
+     */
+    readonly action: 'unresolvedEngineering';
+    /** Exact slot spelling used by the imported build. */
+    readonly slot: string;
+    /** Module identity the recipe was stated for. */
+    readonly sourceSymbol: string;
+    /** Recipe the source named, in its own spelling. */
+    readonly blueprintSymbol: string;
 };
 
 /**
- * {@link ShipLoadout} — a mutable fitted-ship model that both **answers questions**
- * about a build and **edits** it.
+ * {@link ShipLoadout} — a mutable fitted-ship model that **holds and edits** a build.
  *
  * Load one from a SLEF export or a journal `Loadout` event, or start from a
  * {@link ShipLoadout.default | default} or {@link ShipLoadout.empty | empty} hull, then
@@ -218,9 +222,15 @@ type LoadoutImportOutcome = {
  * build in place and return `this`; everything a query returns is a deeply frozen
  * snapshot, so query again after an edit rather than re-reading an earlier value.
  *
- * **Slot keys are matched case-insensitively.** Frontier writes `FrameShiftDrive`, a
- * SLEF producer may write `frameshiftdrive`, and both name the same mount. A build's own
- * spelling is never rewritten, so re-exporting an import returns it untouched.
+ * **What a build *calculates* lives next door.** Jump range, mass, cost, power, heat,
+ * mobility, shields, armour and firepower are on
+ * {@link ships!BuildMetrics | BuildMetrics}, over the same build:
+ * `BuildMetrics.of(build).maxJumpRange()`.
+ *
+ * **Slot keys are matched case-insensitively, with surrounding whitespace ignored.**
+ * Frontier writes `FrameShiftDrive`, a SLEF producer may write `frameshiftdrive`, and
+ * both name the same mount. A build's own spelling is never rewritten, so re-exporting
+ * an import returns it untouched.
  *
  * @remarks
  * This is the batteries-included ship facade: it carries the complete ship, module,
@@ -231,11 +241,12 @@ type LoadoutImportOutcome = {
  * ```ts
  * declare const slefJsonString: string;
  *
+ * import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
  * 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)
+ * BuildMetrics.of(build).maxJumpRange(); // -> 89.41  (best single jump, one jump's fuel, no cargo)
  *
  * // Assemble one:
  * import { getModuleBySymbol } from '@elite-dangerous-almanac/core/ships/modules';
@@ -330,13 +341,6 @@ type FixedMountRepairResult = {
     /** 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`. */
@@ -347,8 +351,8 @@ interface ApplyBlueprintOptions {
      * 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;
+    /** The experimental (special) effect's Frontier symbol, if any. */
+    readonly experimentalEffectSymbol?: string;
 }
 /** Stable reason {@link ShipLoadout.setExperimentalEffect} cannot perform an edit. */
 type ExperimentalEffectMutationCode = 'emptySlot' | 'notEngineered' | 'unknownExperimentalEffect' | 'unsupportedExperimentalEffect' | 'finalArticle' | 'unsupportedEngineering' | 'unidentifiedPreEngineeredVariant' | 'unresolvedModifiers';
@@ -356,17 +360,17 @@ type ExperimentalEffectMutationCode = 'emptySlot' | 'notEngineered' | 'unknownEx
 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 symbol before the edit, or `null` when none was present. */
+    readonly previousExperimentalEffectSymbol: string | null;
+    /** Effect symbol after the edit, or `null` when it was removed. */
+    readonly experimentalEffectSymbol: 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;
+    /** Current effect symbol, or `null` when none is present. */
+    readonly experimentalEffectSymbol: string | null;
 }
 /** Effect-only edit that cannot be performed losslessly. */
 interface ExperimentalEffectUnsupported {
@@ -391,8 +395,9 @@ interface EngineeringNormalized {
     /** Discriminator for a successful normalization. */
     readonly kind: 'normalized';
     /**
-     * Quality reported by the fitted module before normalization, in `[0, 1]`. It reads
-     * `1` where a completed roll stated no modifiers and this call spelled them out.
+     * Quality reported by the fitted module before normalization, in `[0, 1]`. A block
+     * that stated no modifiers still reports the quality it stated, so this reads `1` for
+     * a completed roll whose figures this call was the first to spell out.
      */
     readonly previousQuality: number;
     /** Completed engineering quality. Always `1`. */
@@ -409,223 +414,10 @@ interface EngineeringNormalizationUnsupported {
 }
 /** 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';
-/** What a {@link StandardLoad} carries, and what the ship weighs carrying it. */
-interface StandardLoadInputs {
-    /** Main-tank fuel carried, in tonnes. */
-    readonly fuel: number;
-    /** Cargo carried, in tonnes. */
-    readonly cargo: number;
-    /**
-     * What the ship weighs at this load, in tonnes: {@link ShipLoadout.unladenMass}
-     * plus `fuel` plus `cargo`.
-     *
-     * @remarks
-     * This is the mass the jump and mobility calculations run on, so it is the figure
-     * to show beside them rather than one reassembled by the caller. The reserve tank
-     * is **not** in it: the game's statistics panel counts the reserve in the current
-     * mass it displays, and neither calculation here does — see
-     * {@link ShipLoadout.mobilityMetrics}. Add {@link FuelCapacity.reserve} to match the
-     * panel.
-     *
-     * The extra `fuel` and `cargo` are the load a screen labels; the mass is what they
-     * add up to, and passing the whole value back into {@link ShipLoadout.jumpRange} or
-     * {@link ShipLoadout.mobilityMetrics} is unaffected by its presence.
-     */
-    readonly mass: 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, as {@link ShipLoadout.buildCost} prices it.
- */
-interface BuildCredits {
-    /**
-     * Priced hull and modules together, in credits.
-     *
-     * A Mercenary article is bought with Merc Coin and has no credit price at all, but it
-     * is counted here at the catalogue list price of the stock module it is built on, and
-     * again in {@link BuildCost.mercCoins} at what it actually cost. Subtract the stock
-     * module's price to quote credits a shop would really ask.
-     */
-    readonly total: number;
-    /** 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 `total`, truncated to credits: what insurance bills to rebuild the
-     * fit at catalogue prices. For what a capture said its own rebuy was, read
-     * {@link ShipLoadout.rebuy}.
-     */
-    readonly rebuy: number;
-    /** Fitted modules that could not be priced from the catalogue. */
-    readonly unpriced: readonly {
-        readonly slot: string;
-        readonly symbol: string;
-    }[];
-}
-/**
- * What an assembled build costs to own, in all three currencies the game charges for it.
- *
- * Every figure prices the **current fit** from the catalogues rather than reporting what a
- * capture said was paid; for the latter read {@link ShipLoadout.sourcePurchase}.
- */
-interface BuildCost {
-    /** Shop credits for the hull and its fitted modules. */
-    readonly credits: BuildCredits;
-    /**
-     * Merc Coin billed by the build: every Mercenary article's shop price plus every
-     * blueprint's currency cost, including ordinary engineering-menu recipes that charge it.
-     * A Mercenary article's blueprint is charged only above the grade it was sold at.
-     */
-    readonly mercCoins: number;
-    /**
-     * What the build's blueprints and experimental effects consume, one entry per distinct
-     * material, counts summed across modules.
-     *
-     * Pre-engineered articles arrive engineered, so only what a player still has to roll on
-     * top of one is charged. A fixed reward carries no craft recipe at all and contributes
-     * nothing, and so does a modification whose recipe the catalogues do not price — a
-     * capture may name a blueprint or effect no registry lists, and an unpriceable
-     * modification is silently absent rather than reported the way
-     * {@link BuildCredits.unpriced} reports an unpriceable module.
-     */
-    readonly materials: readonly EngineeringMaterial[];
-}
-/**
- * What an assembled build weighs, broken down the way {@link ShipLoadout.buildMass}
- * weighs it. Every figure is in tonnes.
- *
- * @remarks
- * The mass counterpart of {@link BuildCredits}, and the same split: what the bare hull
- * contributes, what the fit adds, and the total. `fuel` and `cargo` are the chosen load
- * on top of that, so `total` is the mass the jump and mobility calculations run on.
- */
-interface BuildMass {
-    /** Bare hull mass — the {@link ships!Ship.hullMass | hullMass} of the hull being flown. */
-    readonly hull: number;
-    /**
-     * Every fitted module's post-engineering mass, summed.
-     *
-     * @remarks
-     * Lightweight blueprints are already folded in, and the cargo hatch weighs nothing.
-     * A fitted record with no mass at all contributes `0` rather than making the total
-     * unavailable — mass is the one figure no article can be missing (see
-     * {@link ShipLoadout.unladenMass}), which is why there is no `unpriced` counterpart
-     * to {@link BuildCredits.unpriced} here.
-     */
-    readonly modules: number;
-    /**
-     * The ship with an empty tank and no cargo — {@link ShipLoadout.unladenMass}.
-     *
-     * @remarks
-     * `hull` and `modules` are always computed from the hull record and the current
-     * fit, while this is the build's own unladen mass, which for an unedited import is
-     * the figure the **capture** stated. The two agree on anything assembled here; where
-     * a capture disagrees with the catalogues, this is the one the jump and mobility
-     * calculations use and the decomposition is what the catalogues say it is made of.
-     */
-    readonly unladen: number;
-    /** Main-tank fuel counted, in tonnes. Defaults to a full main tank. */
-    readonly fuel: number;
-    /** Cargo counted, in tonnes. Defaults to an empty hold. */
-    readonly cargo: number;
-    /** `unladen + fuel + cargo`: what the ship weighs at the chosen load. */
-    readonly total: number;
-}
-/** 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 blueprint's Frontier symbol, e.g. `"FSD_LongRange"`. */
+    readonly blueprintSymbol: string;
     /** The grades the blueprint offers, ascending (e.g. `[1, 2, 3, 4, 5]`). */
     readonly grades: readonly number[];
     /**
@@ -688,6 +480,46 @@ interface SlefExportOptions extends LoadoutExportOptions {
 /**
  * A fitted ship — read a SLEF export, or assemble a hull from scratch.
  *
+ * ## Member index
+ *
+ * - **Construct** — {@link fromSlef}, {@link fromLoadout}, {@link empty},
+ *   {@link default}. The constructor is private; every build starts at one of these four.
+ * - **Inspect** — {@link shipSymbol}, {@link shipName}, {@link shipIdent},
+ *   {@link unladenMass}, {@link cargoCapacity}, {@link fuelCapacity}, {@link hullValue},
+ *   {@link modulesValue}, {@link rebuy}, {@link sourcePurchase}, {@link importOutcomes},
+ *   {@link slots}, {@link fittedModuleAt}, {@link fittedModules},
+ *   {@link modulesForSlot}, {@link availableBlueprints},
+ *   {@link availableExperimentalEffects}, {@link validation | validation()}.
+ * - **Edit** — {@link setModule}, {@link removeModule}, {@link repairFixedMount},
+ *   {@link applyBlueprint}, {@link setExperimentalEffect},
+ *   {@link completeEngineeringGrade}, {@link setPreEngineeredVariant},
+ *   {@link clearEngineering}, {@link setModuleEnabled}, {@link setModulePriority}. Each
+ *   returns `this` unless it reports a result of its own.
+ * - **Analyse** — not here. Jump range, mass, cost, power, heat, mobility, shields,
+ *   armour and firepower live on
+ *   {@link ships!BuildMetrics | BuildMetrics}, which reads this build:
+ *   `BuildMetrics.of(build).maxJumpRange()`. The split lets an outfitting editor import
+ *   the editors without the calculations, and a viewer the calculations without the
+ *   editors.
+ * - **Export** — {@link toLoadoutEvent}, {@link toSlef}, {@link toSlefString}.
+ *
+ * ## Properties against methods
+ *
+ * **A property is a fact this build already carries; a method does something.** Every
+ * getter above is an identity, an aggregate figure, or what a capture stated — it
+ * computes nothing, takes no options, and never throws. Everything that does work is a
+ * call: reading the catalogues, enumerating mounts, editing the fit, exporting it, and
+ * every figure on {@link ships!BuildMetrics | BuildMetrics}.
+ *
+ * The rule makes the split predictable, not harmless. Two of those calls take no
+ * argument and read like facts — {@link validation | validation()}, which revalidates
+ * the whole fit, and {@link fittedModules | fittedModules()}, which allocates and
+ * deeply freezes a fresh snapshot on every call — so they are methods by the rule above
+ * even though a reader may reach for them as properties. **A forgotten `()` still hands
+ * you the function rather than the value**, and in plain JavaScript nothing complains:
+ * `build.fittedModules` is a function reference, `build.fittedModules()` is the list.
+ * TypeScript catches it; a `.js` consumer will not.
+ *
  * @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
@@ -695,6 +527,7 @@ interface SlefExportOptions extends LoadoutExportOptions {
  * describe survives import; the rest are computed from the fit.
  *
  * ```ts
+ * import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
  * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
  * import type { LoadoutEvent } from '@elite-dangerous-almanac/core/ships/slef';
  *
@@ -707,10 +540,11 @@ interface SlefExportOptions extends LoadoutExportOptions {
  * 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
+ * const metrics = BuildMetrics.of(build);
+ * metrics.maxJumpRange(); // -> 60.5478   (ly, best single jump)
+ * metrics.powerBudget().withinBudget; // -> true
+ * metrics.shieldMetrics()?.strength; // -> 743.12  (MJ)
+ * metrics.armourMetrics().hitPoints; // -> 307.8
  * ```
  */
 declare class ShipLoadout {
@@ -725,7 +559,8 @@ declare class ShipLoadout {
      * Defaults to the first.
      * @returns The loadout for that entry.
      * @remarks Module normalization follows {@link ShipLoadout.fromLoadout}; inspect
-     * {@link importOutcomes} for modules that were emptied or defaulted.
+     * {@link importOutcomes} for modules that were emptied or defaulted, and for stated
+     * engineering it could not resolve.
      * @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.
@@ -744,6 +579,20 @@ declare class ShipLoadout {
      * and the catalogue's stat block then supplies the values the capture omits; the
      * capture's own modifiers stay authoritative over it.
      *
+     * **A recipe stated without `Modifiers` is rolled.** A journal writes the modifier
+     * block beside the recipe, but SLEF permits stating the recipe alone and Inara does,
+     * so such a block is materialised here at the grade and quality it states — otherwise
+     * the module would report that it is engineered while publishing the figures of one
+     * that is not. Where the module's own engineering menu offers the recipe, the block
+     * is read as an ordinary roll of it, even if a fixed article of that module carries
+     * the same blueprint at the same grade; use {@link setPreEngineeredVariant} to say
+     * the article was meant instead. A Mercenary article is read as its own article at
+     * the grade it was bought at, and as that purchase climbed by its bespoke recipe
+     * above it. Where the menu does not offer the recipe, no ordinary roll
+     * could have written the block, so a single catalogued article answering to it is
+     * fitted. Where neither answers, the module keeps unengineered figures and
+     * {@link importOutcomes} reports the slot as `unresolvedEngineering`.
+     *
      * Modules are imported as one complete snapshot, so their order does not affect
      * per-ship count allowances. An entry stands as the event stated it when the mount
      * can hold the article the catalogue resolves, when its slot is a known cosmetic or
@@ -755,7 +604,7 @@ declare class ShipLoadout {
      * unresolved symbol, a resolved one the mount refuses, and no entry at all are
      * corrected alike, each keeping the source's `On`, `Priority` and `Health`. A
      * removable mount may stand empty, so an article *it* refuses stays where the event
-     * put it and is reported by {@link validation} instead.
+     * put it and is reported by {@link validation | validation()} instead.
      *
      * Normalization makes the captured aggregates untrustworthy, so they are dropped:
      * {@link unladenMass}, {@link cargoCapacity} and {@link fuelCapacity} are recomputed
@@ -818,7 +667,7 @@ declare class ShipLoadout {
      * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
      *
      * const stock = ShipLoadout.default('SideWinder');
-     * stock.validation.complete; // -> true
+     * stock.validation().complete; // -> true
      * stock.fittedModuleAt('FrameShiftDrive')?.symbol;
      * // -> 'Int_Hyperdrive_Size2_Class1'
      * ```
@@ -864,14 +713,14 @@ declare class ShipLoadout {
      * unknown — including after an edit or import normalization discarded an import's
      * figure, since no catalogue records what a replaced module was bought for. Unlike
      * mass and capacity it is not recomputed from what remains; {@link sourcePurchase}
-     * keeps the captured figure and {@link buildCost} prices the current fit.
+     * keeps the captured figure and {@link ships!BuildMetrics.buildCost | BuildMetrics.buildCost} prices the current fit.
      */
     get modulesValue(): number | null;
     /**
      * Insurance rebuy cost in credits represented by the build, or `null` if
      * unknown. Discarded by an edit or by import normalization for the same reason as
      * {@link modulesValue}, and likewise kept by {@link sourcePurchase};
-     * {@link buildCost} rebuys the current fit at catalogue prices instead.
+     * {@link ships!BuildMetrics.buildCost | BuildMetrics.buildCost} rebuys the current fit at catalogue prices instead.
      */
     get rebuy(): number | null;
     /**
@@ -909,18 +758,23 @@ declare class ShipLoadout {
      */
     get sourcePurchase(): SourcePurchaseRecord | null;
     /**
-     * Changes made while importing this build, in source order, followed by the fixed
-     * mounts stocked from the hull defaults because the source named none, in the
-     * defaults' own order.
+     * What the import made of this build: the changes it applied, in source order,
+     * followed by the fixed mounts stocked from the hull defaults because the source
+     * named none, in the defaults' own order, followed by the modules whose stated
+     * engineering it could not resolve.
      *
      * @returns A deeply frozen list. It is empty for builds created with
      * {@link ShipLoadout.empty} or {@link ShipLoadout.default}, and for imports that
-     * needed no normalization.
+     * needed no normalization and left no engineering unresolved.
      * @remarks
      * Each entry names the exact slot, and the source identity where the source gave one.
      * `emptied` means an unknown module was removed from a removable mount; `defaulted`
      * names the stock article fitted to armour, a core internal or the cargo hatch, with
      * a `null` `sourceSymbol` when the source named nothing there at all.
+     * `unresolvedEngineering` is the one entry that reports a *non*-change: the source
+     * stated a recipe and no `Modifiers`, nothing the catalogues carry answers to it, and
+     * that module alone keeps the figures of an unengineered one (see
+     * {@link ShipLoadout.fromLoadout}).
      */
     get importOutcomes(): readonly LoadoutImportOutcome[];
     /**
@@ -928,13 +782,33 @@ declare class ShipLoadout {
      *
      * @remarks
      * `valid` asks whether the fit is legal: a module in a nonexistent or incompatible
-     * slot, a duplicated exclusive family, or a module count past the build's allowance
-     * makes it `false`. `complete` asks that *and* whether armour and the seven core
-     * mounts are filled — every build fills those, so on a build the two answers agree.
-     * Neither question reports import normalization, so read {@link importOutcomes}
-     * beside them.
-     */
-    get validation(): LoadoutValidation;
+     * slot, a duplicated exclusive family, a module count past the build's allowance, or
+     * a ship heavier than its own thrusters can move makes it `false`. `complete` asks
+     * that *and* whether armour and the seven core mounts are filled — every build fills
+     * those, so on a build the two answers agree. Neither question reports import
+     * normalization, so read {@link importOutcomes} beside them.
+     *
+     * The thruster rule weighs the fitted thrusters' post-engineering `maxMass` against
+     * what the ship comes to at each load it can reach without being re-fitted:
+     * {@link unladenMass} alone, then with a full {@link fuelCapacity | main tank}, then
+     * with a full {@link cargoCapacity | hold} as well. The lightest of those that is
+     * already too heavy is what gets reported. A ship that cannot move on a full tank is
+     * an error — it never leaves the pad, where the tank always is one — while a ship
+     * that only fails with the hold full is a warning, and leaves the build valid and
+     * complete: how much cargo to take is the pilot's call. Either way
+     * {@link ships!BuildMetrics.mobilityMetrics | BuildMetrics.mobilityMetrics} reports
+     * a speed of zero at the load in question.
+     *
+     * A capture may state a mass nobody can weigh — a negative `UnladenMass`, or an
+     * engineering modifier that drives a rating below zero. Neither is refused here:
+     * this method reports a build rather than rejecting one, so an unweighable figure is
+     * left out and the rule it feeds simply does not run. The figure itself is still
+     * reported, as a thrown one, by whichever {@link ships!BuildMetrics | BuildMetrics}
+     * calculation reads it.
+     *
+     * @returns The validation report, recomputed from the current fit on every call.
+     */
+    validation(): LoadoutValidation;
     /**
      * Frozen point-in-time views of the hull's mounts in outfitting-panel order.
      *
@@ -991,7 +865,7 @@ declare class ShipLoadout {
      *
      * declare const build: ShipLoadout;
      *
-     * build.availableBlueprints('FrameShiftDrive').map(({ fdname }) => fdname);
+     * build.availableBlueprints('FrameShiftDrive').map(({ blueprintSymbol }) => blueprintSymbol);
      * ```
      */
     availableBlueprints(slotKey: string): readonly AvailableBlueprint[];
@@ -1018,6 +892,13 @@ declare class ShipLoadout {
      * satisfied, with candidates that would worsen a one-per-ship or module-count limit
      * omitted.
      *
+     * @remarks
+     * This is the outfitting *offer*, so the fifteen {@link ships!OutfittingModule.grantOnly | grantOnly}
+     * articles are never in it: each is a second identity for a module the game already
+     * sells — `Int_Engine_Size2_Class1_free` is the 2E Thrusters — and listing both puts
+     * the same article on the screen twice, once with no price. A build that already
+     * carries one keeps it; only the choices are filtered.
+     *
      * @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.
@@ -1131,17 +1012,17 @@ declare class ShipLoadout {
      *
      * @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 blueprintSymbol - The blueprint recipe's Frontier symbol, e.g. `"FSD_LongRange"`.
      * @param options - {@link ApplyBlueprintOptions}: `grade` (1–5), optional `quality`
-     * (0–1, default 1), and optional `experimental` effect `fdname`. A nullish
+     * (0–1, default 1), and optional `experimental` effect symbol. 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
+     * @throws {TypeError} If `slotKey` or `blueprintSymbol` is not a string, `options` is not an
+     * object, or `options.experimentalEffectSymbol` carries a value that is not a string — a nullish
      * one is no effect, not a wrong type. Also if the fitted module has no stats to
      * engineer, is final and accepts no further engineering, is not offered the blueprint
      * by its own menu, is not offered the experimental effect by it, or the id names a
@@ -1151,6 +1032,7 @@ declare class ShipLoadout {
      * stored as a partial journal modifier block.
      * @example
      * ```ts
+     * import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
      * 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';
@@ -1162,12 +1044,12 @@ declare class ShipLoadout {
      * build.setModule('FrameShiftDrive', fsd)
      *      .applyBlueprint('FrameShiftDrive', 'FSD_LongRange', {
      *          grade: 5,
-     *          experimental: 'special_fsd_heavy',
+     *          experimentalEffectSymbol: 'special_fsd_heavy',
      *      });
-     * build.maxJumpRange(); // uses the engineered optimal mass
+     * BuildMetrics.of(build).maxJumpRange(); // uses the engineered optimal mass
      * ```
      */
-    applyBlueprint(slotKey: string, fdname: string, options: ApplyBlueprintOptions): this;
+    applyBlueprint(slotKey: string, blueprintSymbol: string, options: ApplyBlueprintOptions): this;
     /**
      * Add, replace or remove only the fitted module's experimental effect.
      *
@@ -1177,7 +1059,7 @@ declare class ShipLoadout {
      * 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.
+     * @param experimental - Experimental-effect symbol, 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
@@ -1200,9 +1082,13 @@ declare class ShipLoadout {
      * purchase identity. A refusal never changes the loadout.
      *
      * A block that names a blueprint and grade but states no `Modifiers` at all is rolled
-     * here too, even at quality `1` — SLEF permits that identity-only shape and Inara
-     * writes it, so a capture of a completed roll would otherwise stay stock. A stated
-     * modifier array, empty or partial, is left alone at quality `1`.
+     * here too, even at quality `1`, so a completed roll cannot stay stock. On an imported
+     * build such a block is one {@link ShipLoadout.fromLoadout} did not roll: a catalogued
+     * article it fitted instead, whose fixed modifiers this spells out unless the article
+     * is final; a Mercenary article at the grade it was bought at, whose block no registry
+     * publishes and which this refuses; or a recipe nothing answered to, which this
+     * refuses for the reason the import could not roll it. A stated modifier array, empty
+     * or partial, is left alone at quality `1`.
      *
      * @param slotKey - The engineered slot, matched case-insensitively.
      * @returns A frozen result identifying a normalized, unchanged or unsupported state.
@@ -1247,7 +1133,7 @@ declare class ShipLoadout {
      * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
      *
      * const festive = getPreEngineeredVariants('Hpt_FlakMortar_Turret_Medium')
-     *     .find((variant) => variant.blueprint === 'Decorative_Red')!;
+     *     .find((variant) => variant.blueprintSymbol === 'Decorative_Red')!;
      * const build = ShipLoadout.empty('Krait_MkII')
      *     .setPreEngineeredVariant('MediumHardpoint1', festive);
      * build.fittedModuleAt('MediumHardpoint1')?.effectiveStats?.damage; // -> 0.34
@@ -1292,7 +1178,7 @@ declare class ShipLoadout {
      *
      * @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
+     * outfitting panel — and {@link ships!BuildMetrics.powerBudget | BuildMetrics.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]`.
@@ -1353,531 +1239,6 @@ declare class ShipLoadout {
      * ```
      */
     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 fitted drive's record is missing any of its required
-     * jump constants.
-     */
-    get frameShiftDrive(): FrameShiftDriveParams;
-    /**
-     * The fitted thrusters' post-engineering mass curve, or `null` when the build has
-     * none — the thruster counterpart of {@link frameShiftDrive}.
-     *
-     * @remarks
-     * A {@link ships!ThrusterParams | ThrusterParams} carries the three masses the
-     * curve is defined over and the multiplier at each, plus the separate `speedCurve`
-     * and `rotationCurve` an enhanced-performance thruster refines them with. Pass it
-     * straight to
-     * {@link ships!thrusterMassCurveMultiplier | thrusterMassCurveMultiplier} for the
-     * multiplier at a mass of your own, or read `optMass` and `maxMass` against
-     * {@link ships!MobilityMetrics.loadedMass | loadedMass} for where this build sits
-     * on the curve.
-     *
-     * This is the fitted article's curve, so a switched-off or shed thruster still has
-     * one; {@link mobilityMetricsResult} is what judges whether the build can use it.
-     * It answers `null` rather than throwing — unlike `frameShiftDrive`, which the jump
-     * equation cannot do without — when no thrusters are fitted or the fitted record
-     * carries no complete curve.
-     *
-     * @example
-     * ```ts
-     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
-     *
-     * const build = ShipLoadout.default('Anaconda');
-     * build.thrusters?.optMass; // -> 1440, tonnes
-     * build.thrusters?.maxMass; // -> 2160, past which the ship does not move at all
-     * ```
-     */
-    get thrusters(): ThrusterParams | null;
-    /**
-     * 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.
-     * @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".
-     *
-     * @returns The best single jump, in light-years, or `0` for a capture that states a
-     * main tank of `0`.
-     * @throws {TypeError} If the build has no usable frame shift drive.
-     */
-    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.
-     * @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.
-     */
-    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.
-     * @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.
-     * @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 The fuel and cargo carried, and the {@link StandardLoadInputs.mass} the
-     * ship weighs carrying them, all in tonnes. Only `'maximum'` can come back
-     * incomplete: it validates the whole fitted drive, jump booster included, so a
-     * complete one can be passed straight to {@link jumpRange}.
-     * @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 });
-     * ```
-     * @example
-     * ```ts
-     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
-     *
-     * const build = ShipLoadout.default('Anaconda');
-     * build.standardLoadResult('laden').value?.mass; // -> 1210, tonnes with a full tank and hold
-     * ```
-     */
-    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.
-     * @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:
-     * build.jumpRange({ fuel: build.fuelCapacity.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}. `consumers` includes modules with positive
-     * draw; passive and zero-draw fittings are absent.
-     * @throws {RangeError} If a 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.
-     * @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 {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 {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.
-     * 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, so a build whose plant is switched off or outdrawn reports
-     * every bank unpowered and 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 the whole build from the catalogues: shop credits, Merc Coin and the
-     * engineering materials its modifications consume.
-     *
-     * No modification is charged twice. A Mercenary article arrives at the grade it was sold at,
-     * so only the climb above that grade bills materials and further Merc Coin, and an
-     * experimental effect the article came with is free while one added on top is not. A
-     * fixed reward article — festive, Guardian, community-goal — identifies a recipe it
-     * was never rolled from, so it contributes no materials at all.
-     *
-     * @returns A frozen {@link BuildCost}. `credits.modules`, `credits.total` and
-     * `credits.rebuy` are lower bounds while {@link BuildCredits.unpriced} is non-empty;
-     * built-in hull fittings are free rather than unpriced.
-     * @remarks
-     * This is the one place `ShipLoadout` reads the material and Merc Coin cost
-     * catalogues, which is why the facade carries them; import
-     * {@link ships/blueprint-costs!getBlueprintCost | getBlueprintCost} and
-     * {@link ships/experimental-effect-costs!getExperimentalEffectCost | getExperimentalEffectCost}
-     * directly to price one recipe without a build.
-     * @example
-     * ```ts
-     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
-     *
-     * const build = ShipLoadout.default('Anaconda');
-     * build.buildCost().credits.hull; // -> 142456440
-     * build.applyBlueprint('FrameShiftDrive', 'FSD_LongRange', { grade: 5 });
-     * build.buildCost().materials.find((material) => material.symbol === 'Arsenic')?.count; // -> 5
-     * ```
-     * @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.buildCost().mercCoins; // -> 950
-     * ```
-     */
-    buildCost(): BuildCost;
-    /**
-     * Weigh the whole build: the hull, the fitted modules, and the load on top of them.
-     *
-     * @remarks
-     * The mass companion to {@link buildCost}, answering the same question in tonnes
-     * that that one answers in credits. Every module's mass is post-engineering, so a
-     * Lightweight roll is already in `modules`.
-     *
-     * The reserve tank is **not** counted. The main tank is the fuel the drive and the
-     * flight model see, and it is what {@link jumpRange} and {@link mobilityMetrics}
-     * weigh; the game's statistics panel additionally counts the reserve in the current
-     * mass it displays, so add {@link fuelCapacity}`.reserve` to reproduce that reading.
-     *
-     * @param options - {@link JumpOptions}. `fuel` defaults to a full main tank and
-     * `cargo` to `0`, matching {@link jumpRange} and {@link mobilityMetrics}. Pass
-     * {@link standardLoadResult} to weigh one of the standard loads.
-     * @returns A frozen {@link BuildMass}, every figure in tonnes.
-     * @throws {RangeError} If fuel or cargo is not finite and non-negative.
-     * @example
-     * ```ts
-     * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
-     *
-     * const build = ShipLoadout.default('Anaconda');
-     * const mass = build.buildMass();
-     * mass.hull; // -> 400
-     * mass.modules; // -> 664
-     * mass.total; // -> 1096, a full main tank and an empty hold
-     * build.buildMass({ cargo: build.cargoCapacity }).total; // -> 1210
-     * ```
-     */
-    buildMass(options?: JumpOptions): BuildMass;
-    /**
-     * The build's armour: hull hit points, the bulkhead and reinforcement each
-     * contribute, and the effective resistances.
-     *
-     * @returns The {@link ArmourMetrics}, read off the fitted bulkhead.
-     * @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. 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 the distributor is switched off, its six
-     * capacitor stats cannot be resolved, or the retracted power budget sheds it. That
-     * retracted state represents the distributor itself; firing endurance in
-     * {@link weaponsCapacitorMetrics} separately applies the deployed state.
-     * @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 BuildCost, type BuildCredits, type BuildMass, 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 LoadoutImportOutcome, type LoadoutSlot, type MobilityOptions, ShipLoadout, type SlefExportOptions, type StandardLoad, type StandardLoadInputs, type WeaponsOptions };
+export { type ApplyBlueprintOptions, type AvailableBlueprint, type EngineeringNormalizationCode, type EngineeringNormalizationResult, type EngineeringNormalizationUnchanged, type EngineeringNormalizationUnsupported, type EngineeringNormalized, type ExperimentalEffectMutationCode, type ExperimentalEffectMutationResult, type ExperimentalEffectUnchanged, type ExperimentalEffectUnsupported, type ExperimentalEffectUpdated, type FittedModule, type FixedMountRepairResult, type ImmovableReason, LoadoutEditError, type LoadoutEditErrorCode, type LoadoutExportOptions, type LoadoutImportOutcome, type LoadoutSlot, ShipLoadout, type SlefExportOptions };