@elite-dangerous-almanac/core 0.1.8 → 0.2.0

package/dist/ships/mobility.d.ts

@@ -1,7 +1,10 @@
 /**
- * Data-free speed and handling calculations for a loaded ship. Speed and angular-rate
- * endpoints interpolate linearly by the ENG-PIP fraction before thruster mass curves
- * are applied.
+ * Data-free speed and handling calculations for a loaded ship, at **full ENG** — the
+ * hull's four-pip endpoints with the fitted thruster mass curves applied.
+ *
+ * The ENG capacitor is a separate story with its own entry point,
+ * `./mobility-capacitor`, which interpolates the hull's zero-pip endpoints towards the
+ * four-pip ones before the same curves are applied.
  *
  * Ported from EDCD/Coriolis and cross-checked against EDSY's mass-curve calculation;
  * see [`ATTRIBUTIONS.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md).
@@ -61,10 +64,15 @@ interface MobilityInput {
     readonly mass: number;
     /** The fitted thrusters' post-engineering curve, or no curve when none are fitted. */
     readonly thrusters?: ThrusterParams | null;
-    /** Finite pips assigned to ENG, in `[0, 4]`. Defaults to `4`. */
-    readonly enginesPips?: number;
 }
-/** Speed and rotation rates for one loaded ship. */
+/**
+ * Speed and rotation rates for one loaded ship.
+ *
+ * @remarks
+ * Frozen — nested records and lists included — so a result can be held, cached and
+ * shared without a defensive copy. Derive a changed figure with a spread rather than
+ * by assigning into one.
+ */
 interface MobilityMetrics {
     /**
      * The loaded mass these figures were calculated at, in tonnes — the
@@ -78,15 +86,15 @@ interface MobilityMetrics {
      * move the ship at all — {@link massCurveMultiplier} is `0` there.
      */
     readonly loadedMass: number;
-    /** Top speed at this mass and ENG allocation, in metres per second. */
+    /** Top speed at this mass and **four** ENG pips, in metres per second. */
     readonly speed: number;
-    /** Boost speed at this mass, in metres per second. */
+    /** Boost speed at this mass, in metres per second. Boost ignores the ENG allocation. */
     readonly boost: number;
-    /** Pitch rate at this mass and ENG allocation, in degrees per second. */
+    /** Pitch rate at this mass and **four** ENG pips, in degrees per second. */
     readonly pitch: number;
-    /** Roll rate at this mass and ENG allocation, in degrees per second. */
+    /** Roll rate at this mass and **four** ENG pips, in degrees per second. */
     readonly roll: number;
-    /** Yaw rate at this mass and ENG allocation, in degrees per second. */
+    /** Yaw rate at this mass and **four** ENG pips, in degrees per second. */
     readonly yaw: number;
     /** The thruster mass curve's performance multiplier at this loaded mass. */
     readonly massCurveMultiplier: number;
@@ -114,15 +122,19 @@ interface MobilityMetrics {
  */
 declare function thrusterMassCurveMultiplier(mass: number, thrusters: ThrusterCurveParams): number;
 /**
- * Calculate a loaded ship's top speed, boost speed and rotation rates.
+ * Calculate a loaded ship's top speed, boost speed and rotation rates at **full ENG**.
  *
  * @remarks
- * Speed, pitch, roll and yaw interpolate linearly from their installed zero-ENG-PIP
- * endpoints to their four-PIP endpoints. The fitted thruster's speed and rotation
- * mass-curve multipliers are then applied to those interpolated hull values. Boost is
- * independent of ENG allocation and uses the speed curve at the loaded mass.
+ * Speed, pitch, roll and yaw are the hull's four-ENG-PIP endpoints with the fitted
+ * thruster's speed and rotation mass-curve multipliers applied. Boost is independent of
+ * the ENG allocation and uses the speed curve at the loaded mass, so it is the same
+ * figure whatever the pips.
+ *
+ * A **lower** allocation is {@link mobilityCapacitorMetrics}: it interpolates each figure
+ * from the hull's zero-pip endpoint (`minimumSpeed`, `minPitch`, `minRoll`, `minYaw`)
+ * towards the endpoint used here, and applies the same curves.
  *
- * @param input - Hull figures, loaded mass, fitted thrusters and ENG pips.
+ * @param input - Hull figures, loaded mass and fitted thrusters.
  * @returns The build's {@link MobilityMetrics}, or `null` without thrusters. A mass above
  * the thrusters' maximum returns zero performance rather than a fabricated curve value.
  * @throws {RangeError} If an input is not finite or is outside its documented range,

package/dist/ships/mobility.js

@@ -1 +1 @@
-export{mobilityMetrics,thrusterMassCurveMultiplier}from"../chunk-CX7B67OI.js";//# sourceMappingURL=mobility.js.map
+export{mobilityMetrics,thrusterMassCurveMultiplier}from"../chunk-Y6KJJMIM.js";                                                          //# sourceMappingURL=mobility.js.map

package/dist/ships/power.d.ts

@@ -10,8 +10,8 @@
  * whose running total would go over, along with everything below it.
  *
  * This module is data-free: hand {@link powerBudget} the plant's capacity and a
- * {@link PowerConsumer} per fitted module. {@link ShipLoadout.powerBudget} (in
- * `./ship-loadout`) builds that list from a build for you, post-engineering.
+ * {@link PowerConsumer} per fitted module. {@link BuildMetrics.powerBudget} (in
+ * `./build-metrics`) builds that list from a build for you, post-engineering.
  *
  * @remarks
  * Reference implementation: EDCD/Coriolis, `src/app/shipyard/Ship.js`
@@ -93,7 +93,14 @@ interface PowerBand {
     /** Whether this group stays powered with hardpoints deployed. */
     readonly poweredDeployed: boolean;
 }
-/** What a build's power plant makes and what the build asks of it. */
+/**
+ * What a build's power plant makes and what the build asks of it.
+ *
+ * @remarks
+ * Frozen — nested records and lists included — so a result can be held, cached and
+ * shared without a defensive copy. Derive a changed figure with a spread rather than
+ * by assigning into one.
+ */
 interface PowerBudget {
     /** Power the plant generates, in megawatts, post-engineering. */
     readonly available: number;
@@ -117,7 +124,7 @@ interface PowerBudget {
     readonly bands: readonly PowerBand[];
     /**
      * Every supplied consumer in source order, including switched-off entries. Enabled
-     * entries reconcile with the band and aggregate totals. {@link ShipLoadout.powerBudget}
+     * entries reconcile with the band and aggregate totals. {@link BuildMetrics.powerBudget}
      * supplies only modules with a positive draw; passive and zero-draw fittings are absent.
      */
     readonly consumers: readonly PowerConsumerResult[];
@@ -130,7 +137,7 @@ interface PowerBudget {
  * fitted — every group then reads as unpowered). Must be finite and non-negative.
  * @param consumers - Power consumers to include. Modules with `enabled: false` are
  * skipped from totals; the rest fall into their {@link PowerConsumer.priority | priority}
- * group. {@link ShipLoadout.powerBudget} omits passive and zero-draw fittings.
+ * group. {@link BuildMetrics.powerBudget} omits passive and zero-draw fittings.
  * @returns The {@link PowerBudget}.
  * @throws {RangeError} If `available` or any consumer's `draw` is not a finite
  * non-negative number.

package/dist/ships/power.js

@@ -1 +1 @@
-export{powerBudget}from"../chunk-RLUS76LZ.js";//# sourceMappingURL=power.js.map
+export{powerBudget}from"../chunk-D6YEHR5S.js";//# sourceMappingURL=power.js.map

package/dist/ships/pre-engineered-stats.d.ts

@@ -15,8 +15,8 @@ import './slots.js';
  * arrives, not as the stock module leaves the shipyard. That is what
  * {@link getPreEngineeredStats} returns.
  *
- * This module imports every module record to resolve stats. Its resolver is 343.9 KiB
- * minified in a consumer bundle; the complete runtime API is 376.2 KiB (41.6 KiB
+ * This module imports every module record to resolve stats. Its resolver is 362.5 KiB
+ * minified in a consumer bundle; the complete runtime API is 396.3 KiB (43.1 KiB
  * gzipped). Consumers that only list variants can import `./pre-engineered.js` without
  * these module catalogues.
  * A journal or SLEF module can instead be classified with
@@ -52,7 +52,7 @@ import './slots.js';
  * import { getPreEngineeredModifiers } from '@elite-dangerous-almanac/core/ships/pre-engineered-stats';
  *
  * const railgun = getPreEngineeredVariants('Hpt_Railgun_Fixed_Medium')
- *     .find((variant) => variant.blueprint === 'Weapon_HighCapacity');
+ *     .find((variant) => variant.blueprintSymbol === 'Weapon_HighCapacity');
  * if (railgun) getPreEngineeredModifiers(railgun);
  * // -> [{ Label: 'Mass', Value: 2.85, OriginalValue: 1.5 }, ...]
  * ```
@@ -76,7 +76,7 @@ declare function getPreEngineeredModifiers(variant: PreEngineeredVariant): Engin
  * import { getPreEngineeredJournalModifiers } from '@elite-dangerous-almanac/core/ships/pre-engineered-stats';
  *
  * const red = getPreEngineeredVariants('Hpt_FlakMortar_Turret_Medium')
- *     .find((variant) => variant.blueprint === 'Decorative_Red')!;
+ *     .find((variant) => variant.blueprintSymbol === 'Decorative_Red')!;
  * getPreEngineeredJournalModifiers(red);
  * // -> [{ Label: 'DamagePerSecond', Value: 0.17, OriginalValue: 17 }, { Label: 'Damage', Value: 0.34, OriginalValue: 34 }]
  * ```
@@ -165,13 +165,15 @@ declare function unresolvedModifiers(variant: PreEngineeredVariant): string[];
  * Exact damage components scale with an engineered `damage` value so their proportions
  * and the anti-xeno overlay remain coherent with the resolved scalar.
  *
- * A variant with no stat block (every `mercenary` row) resolves to the base record
- * unchanged, which is the honest answer — the pre-engineering those arrive with is not
- * published anywhere, so the catalogue does not guess at it.
+ * A variant with no stat block (every `mercenary` row) resolves to a copy of the base
+ * record with nothing changed, which is the honest answer — the pre-engineering those
+ * arrive with is not published anywhere, so the catalogue does not guess at it.
  *
  * @param variant - A pre-engineered variant.
  * @returns The resolved module record, or `null` when the variant's symbol is not in the
- * module catalogues.
+ * module catalogues. It is always a record of your own — never the shared catalogue
+ * singleton — so you may adjust it before fitting it; its nested values are still the
+ * catalogue's frozen ones, so replace them rather than write into them.
  *
  * @example
  * ```ts

package/dist/ships/pre-engineered-stats.js

@@ -1 +1 @@
-export{getPreEngineeredJournalModifiers,getPreEngineeredModifiers,getPreEngineeredStats,identifyPreEngineeredVariant,unresolvedModifiers}from"../chunk-6BO5JJNI.js";                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             //# sourceMappingURL=pre-engineered-stats.js.map
+export{getPreEngineeredJournalModifiers,getPreEngineeredModifiers,getPreEngineeredStats,identifyPreEngineeredVariant,unresolvedModifiers}from"../chunk-GZYPQIO2.js";                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             //# sourceMappingURL=pre-engineered-stats.js.map

package/dist/ships/pre-engineered.d.ts

@@ -97,15 +97,15 @@ interface PreEngineeredVariant {
      * against it prices ordinary engineering rather than the reward. Read `modifiers`
      * for what the article actually carries.
      */
-    readonly blueprint: string;
+    readonly blueprintSymbol: string;
     /** The engineering grade already applied (1–5). */
     readonly grade: number;
     /**
-     * The experimental effect's Frontier `fdname`, e.g.
+     * The experimental effect's Frontier symbol, e.g.
      * `"special_feedback_cascade_cooled"`. Joins to `EXPERIMENTAL_EFFECTS`. Absent when
      * the variant carries none.
      */
-    readonly experimental?: string;
+    readonly experimentalEffectSymbol?: string;
     /** Where the variant comes from. */
     readonly acquisition: PreEngineeredAcquisition;
     /**
@@ -152,7 +152,7 @@ interface PreEngineeredVariant {
  * PRE_ENGINEERED_MODULES.length; // -> 76
  * PRE_ENGINEERED_MODULES[0];
  * // -> { symbol: 'Hpt_Mining_AbrBlstr_Fixed_Small', name: 'Abrasion Blaster',
- * //      blueprint: 'AbrasionBlaster_FarReaching', grade: 1,
+ * //      blueprintSymbol: 'AbrasionBlaster_FarReaching', grade: 1,
  * //      acquisition: 'mercenary', mercCoinCost: 400 }
  * ```
  */
@@ -173,7 +173,7 @@ declare const PRE_ENGINEERED_MODULES: readonly PreEngineeredVariant[];
  * ```ts
  * import { getPreEngineeredVariants } from '@elite-dangerous-almanac/core/ships/pre-engineered';
  *
- * getPreEngineeredVariants('Hpt_BasicMissileRack_Fixed_Medium').map((v) => v.blueprint);
+ * getPreEngineeredVariants('Hpt_BasicMissileRack_Fixed_Medium').map((v) => v.blueprintSymbol);
  * // -> ['SeekerMissileRack_Drag',
  * //     'SeekerMissileRack_LightWeightThermal',
  * //     'SeekerMissileRackMedium_Lockdown',
@@ -186,7 +186,7 @@ declare function getPreEngineeredVariants(symbol: string): readonly PreEngineere
 /**
  * Whether a module has at least one known pre-engineered form.
  *
- * @param symbol - A module symbol.
+ * @param symbol - A module symbol. Leading/trailing whitespace and case are ignored.
  * @returns `true` when {@link getPreEngineeredVariants} would return anything.
  *
  * @throws {TypeError} If `symbol` is present and not a string. A nullish

package/dist/ships/pre-engineered.js

@@ -1 +1 @@
-export{PRE_ENGINEERED_MODULES,getPreEngineeredVariants,isPreEngineered}from"../chunk-2VPVZELZ.js";                                                                                       //# sourceMappingURL=pre-engineered.js.map
+export{PRE_ENGINEERED_MODULES,getPreEngineeredVariants,isPreEngineered}from"../chunk-PL75RTA2.js";                                                                                       //# sourceMappingURL=pre-engineered.js.map

package/dist/ships/resistances.d.ts

@@ -18,8 +18,8 @@
  *   multiplier (capped at `0.7`), the range `[0, max]` is squeezed into `[0.35, max]`.
  *   If the squeeze would *raise* the multiplier above `0.7`, the plain product stands.
  *
- * This module is data-free — pass fractions in, get fractions out. {@link ShipLoadout}
- * (`./ship-loadout`), `./shields` and `./armour` gather the numbers for you.
+ * This module is data-free — pass fractions in, get fractions out. {@link BuildMetrics}
+ * (`./build-metrics`), `./shields` and `./armour` gather the numbers for you.
  *
  * @remarks
  * Reference implementation: EDCD/Coriolis,

package/dist/ships/resistances.js

@@ -1 +1 @@
-export{effectiveHitPoints,mapDamageTypes,stackArmourResistance,stackShieldResistance,systemsResistance}from"../chunk-ZNCXENNB.js";//# sourceMappingURL=resistances.js.map
+export{effectiveHitPoints,mapDamageTypes,stackArmourResistance,stackShieldResistance,systemsResistance}from"../chunk-JGOAQLYW.js";                             //# sourceMappingURL=resistances.js.map

package/dist/ships/shield-capacitor.d.ts

@@ -0,0 +1,133 @@
+import { DamageResistances, DamageTypeValues } from './resistances.js';
+
+/**
+ * **The SYS capacitor** — what pips to SYS buy a raised shield, and what the shield is
+ * worth once they are folded in.
+ *
+ * SYS does two things at once. It **resists**: the allocation adds a flat resistance to
+ * every damage type, which multiplies with the shield's own stack rather than adding to
+ * it, so incoming damage is scaled by `(1 − shieldResistance) × (1 − sysResistance)`. And
+ * it **recharges**: the capacitor's energy is what the generator spends putting the
+ * shield back up, on the same non-linear pip curve the other two capacitors follow,
+ * `ratedRecharge × (pips / 4) ^ 1.1`.
+ *
+ * ```text
+ * sysResistance         = 0.6 × (pips / 4) ^ 0.85
+ * effectiveResistance   = 1 − (1 − shieldResistance) × (1 − sysResistance)
+ * effectiveHitPoints    = strength / (1 − effectiveResistance)
+ * ```
+ *
+ * The bare shield those effective figures are built from is {@link shieldMetrics}, which
+ * is pip-free. What the recharge reported here *buys* — seconds from collapse back to a
+ * raised shield — is {@link shieldRecovery}, which takes the same allocation and the
+ * generator's regeneration rates.
+ *
+ * This module is data-free. {@link BuildMetrics.shieldCapacitorMetrics} (in
+ * `./build-metrics`) resolves the powered generator, boosters and distributor for you.
+ *
+ * @remarks
+ * Reference implementation: EDCD/Coriolis, `src/app/shipyard/Calculations.js`
+ * (`sysResistance`, `calcShieldStrength`), commit
+ * `68c042ca6e3db62372cbbb2077cf972345511712`. The algorithm is ported as fact, not code;
+ * credit and licence terms are in
+ * [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md).
+ *
+ * @packageDocumentation
+ */
+
+/** Everything {@link shieldCapacitorMetrics} needs about one raised shield. */
+interface ShieldCapacitorInput {
+    /**
+     * The shield's total strength, in megajoules — finite and non-negative.
+     * {@link ShieldMetrics.strength}.
+     */
+    readonly strength: number;
+    /**
+     * The shield's own stacked resistances, pip-free — every one a finite fraction.
+     * {@link ShieldMetrics.resistances}.
+     */
+    readonly resistances: DamageResistances;
+    /** SYS-capacitor capacity, in megajoules — finite and non-negative. */
+    readonly systemsCapacity: number;
+    /** Four-SYS-pip recharge rate, in megajoules per second — finite and non-negative. */
+    readonly systemsRecharge: number;
+    /** Pips assigned to SYS, in `[0, 4]`. Fractional pips are accepted; defaults to `4`. */
+    readonly systemsPips?: number;
+}
+/**
+ * What one SYS allocation is worth to a raised shield.
+ *
+ * @remarks
+ * Frozen — nested records and lists included — so a result can be held, cached and
+ * shared without a defensive copy. Derive a changed figure with a spread rather than
+ * by assigning into one.
+ */
+interface ShieldCapacitorMetrics {
+    /** Pips assigned to SYS for this result, in `[0, 4]`. */
+    readonly systemsPips: number;
+    /** SYS-capacitor capacity, in megajoules. */
+    readonly capacity: number;
+    /** Actual recharge rate at {@link systemsPips}, in megajoules per second. */
+    readonly rechargeRate: number;
+    /**
+     * The resistance the pips contribute on their own, as a fraction: `0` at no pips
+     * rising to `0.6` at four. Unrounded, like every resistance here.
+     */
+    readonly systemsResistance: number;
+    /**
+     * The shield's resistances with the pips folded in — the figures the game's own
+     * panel shows while the allocation stands.
+     *
+     * @remarks
+     * Fractions rather than percentages, and **unrounded**. The pips multiply with the
+     * shield's stack rather than adding to it, so these are
+     * `1 − (1 − shieldResistance) × (1 − systemsResistance)` and not a sum.
+     */
+    readonly effectiveResistances: DamageResistances;
+    /**
+     * Effective hit points against each damage type, in megajoules, behind
+     * {@link ShieldCapacitorMetrics.effectiveResistances} — the raw damage of that type
+     * the shield soaks at this allocation. `Infinity` where a resistance reaches 100%.
+     */
+    readonly effectiveHitPoints: DamageTypeValues;
+}
+/**
+ * Calculate what a SYS-pip allocation gives a raised shield.
+ *
+ * @param input - The bare shield's strength and stacked resistances, the distributor's
+ * SYS capacity and rated four-pip recharge, and the allocation to model.
+ * @returns The {@link ShieldCapacitorMetrics}. At **no** pips `systemsResistance` and
+ * `rechargeRate` are `0` and the effective figures equal the bare ones that went in.
+ * @throws {RangeError} If `systemsPips` is outside `[0, 4]`, if a strength, capacity or
+ * recharge is negative or non-finite, or if a resistance is not a finite number. The
+ * pips are checked first, so a bad allocation is reported before the shield.
+ * @throws {TypeError} If `resistances` is not an object carrying the four damage types.
+ * @example
+ * ```ts
+ * import { shieldMetrics } from '@elite-dangerous-almanac/core/ships/shields';
+ * import { shieldCapacitorMetrics } from '@elite-dangerous-almanac/core/ships/shield-capacitor';
+ *
+ * // The bare shield, then what four pips to SYS make of it.
+ * const shields = shieldMetrics({
+ *   hullMass: 400,
+ *   baseShieldStrength: 350,
+ *   generator: {
+ *     minMass: 270, optMass: 540, maxMass: 1350,
+ *     minMultiplier: 0.7, optMultiplier: 1.2, maxMultiplier: 1.7,
+ *     kineticResistance: 0.4,
+ *   },
+ * });
+ * const sys = shieldCapacitorMetrics({
+ *   ...shields,
+ *   systemsCapacity: 41,
+ *   systemsRecharge: 3.9,
+ *   systemsPips: 4,
+ * });
+ * Number(sys.systemsResistance.toFixed(2));            // -> 0.6
+ * Number(sys.effectiveResistances.kinetic.toFixed(2)); // -> 0.76
+ * sys.effectiveHitPoints.kinetic > shields.effectiveHitPoints.kinetic; // -> true
+ * ```
+ */
+declare function shieldCapacitorMetrics(input: ShieldCapacitorInput): ShieldCapacitorMetrics;
+
+export { type ShieldCapacitorInput, type ShieldCapacitorMetrics, shieldCapacitorMetrics };

package/dist/ships/shield-capacitor.js

@@ -0,0 +1 @@
+export{shieldCapacitorMetrics}from"../chunk-6L56LWTT.js";                                                                                       //# sourceMappingURL=shield-capacitor.js.map

package/dist/ships/shield-capacitor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"O"}

package/dist/ships/shield-recovery.d.ts

@@ -24,7 +24,14 @@ interface ShieldRecoveryInput {
     /** Finite pips assigned to SYS, in `[0, 4]`. Defaults to `4`. */
     readonly systemsPips?: number;
 }
-/** Time and rates for a shield to return after collapsing. */
+/**
+ * Time and rates for a shield to return after collapsing.
+ *
+ * @remarks
+ * Frozen — nested records and lists included — so a result can be held, cached and
+ * shared without a defensive copy. Derive a changed figure with a spread rather than
+ * by assigning into one.
+ */
 interface ShieldRecovery {
     /** Megajoules per second regenerated while the shield is raised. */
     readonly regenRate: number;
@@ -73,7 +80,14 @@ interface CellBankMetrics {
     /** Whether the fitted bank is switched on and receiving power. */
     readonly powered: boolean;
 }
-/** Every fitted shield cell bank and the combined pool available from powered banks. */
+/**
+ * Every fitted shield cell bank and the combined pool available from powered banks.
+ *
+ * @remarks
+ * Frozen — nested records and lists included — so a result can be held, cached and
+ * shared without a defensive copy. Derive a changed figure with a spread rather than
+ * by assigning into one.
+ */
 interface CellBankSummary {
     /** Fitted banks in slot order. */
     readonly banks: readonly CellBankMetrics[];

package/dist/ships/shield-recovery.js

@@ -1 +1 @@
-export{cellBankSummary,shieldRecovery}from"../chunk-VZZUNSDF.js";                             //# sourceMappingURL=shield-recovery.js.map
+export{cellBankSummary,shieldRecovery}from"../chunk-4KJ7CR74.js";                             //# sourceMappingURL=shield-recovery.js.map

package/dist/ships/shields.d.ts

@@ -1,4 +1,4 @@
-import { DamageResistanceParams, DamageResistances, DamageTypeValues } from './resistances.js';
+import { DamageResistances, DamageTypeValues, DamageResistanceParams } from './resistances.js';
 
 /**
  * **Shields** — strength in megajoules and the resistances that decide what that
@@ -16,9 +16,10 @@ import { DamageResistanceParams, DamageResistances, DamageTypeValues } from './r
  * ```
  *
  * Resistances stack separately, with their own diminishing returns — see
- * `./resistances`.
+ * `./resistances`. Everything here is **pip-free**: the SYS capacitor's own resistance,
+ * and the effective figures it buys, live in `./shield-capacitor`.
  *
- * This module is data-free. {@link ShipLoadout.shieldMetrics} (in `./ship-loadout`)
+ * This module is data-free. {@link BuildMetrics.shieldMetrics} (in `./build-metrics`)
  * pulls the generator, boosters and reinforcement packages out of a build,
  * post-engineering, and calls {@link shieldMetrics} for you.
  *
@@ -56,6 +57,13 @@ import { DamageResistanceParams, DamageResistances, DamageTypeValues } from './r
  * moves. Every field is optional because the type accepts those records; a generator
  * **missing** any of the six curve fields cannot be placed on the curve at all, and
  * raises no shield ({@link shieldMassCurveMultiplier} returns `0`).
+ *
+ * A generator that carries all six is held to the curve's shape: every value finite and
+ * non-negative, masses strictly ordered `minMass < optMass < maxMass` (or all equal, for
+ * a constant curve), multipliers strictly ordered
+ * `minMultiplier < optMultiplier < maxMultiplier` (or all equal), and equal multipliers
+ * wherever the masses are all equal. Anything else is a `RangeError` rather than a
+ * plausible-looking number.
  */
 interface ShieldGeneratorParams extends DamageResistanceParams {
     /** Hull mass at which the generator performs at `maxMultiplier`, in tonnes. */
@@ -101,15 +109,15 @@ interface ShieldInput {
      * {@link ShieldMetrics.reinforcement} is `0`.
      */
     readonly reinforcement?: number;
-    /**
-     * Pips to the systems capacitor, `0`–`4`, folded into the reported resistances when
-     * a generator is fitted; with none, they are reported only as
-     * {@link ShieldMetrics.systemsResistance}.
-     * Defaults to `0` — the bare shield, as an outfitting screen shows it.
-     */
-    readonly systemsPips?: number;
 }
-/** A build's shield strength, where it comes from, and what it resists. */
+/**
+ * A build's shield strength, where it comes from, and what it resists.
+ *
+ * @remarks
+ * Frozen — nested records and lists included — so a result can be held, cached and
+ * shared without a defensive copy. Derive a changed figure with a spread rather than
+ * by assigning into one.
+ */
 interface ShieldMetrics {
     /** Total shield strength, in megajoules. `0` when no generator is fitted. */
     readonly strength: number;
@@ -131,9 +139,17 @@ interface ShieldMetrics {
      */
     readonly boostMultiplier: number;
     /**
-     * Effective resistances, generator and boosters stacked with diminishing returns,
-     * and the SYS pips folded in. `0` for every damage type when no generator is fitted;
-     * the pips are then reported only in {@link ShieldMetrics.systemsResistance}.
+     * Effective resistances, generator and boosters stacked with diminishing returns.
+     * The SYS pips are **not** in these — they belong to the capacitor, and
+     * {@link shieldCapacitorMetrics} folds them in. `0` for every damage type when no
+     * generator is fitted.
+     *
+     * @remarks
+     * Fractions rather than percentages, and **unrounded**: the stacking is
+     * floating-point arithmetic, so a nominal −20% reads as `-0.19999999999999996`
+     * rather than `-0.2`. Round where the figure is displayed, not before it is
+     * composed further — {@link ShieldMetrics.effectiveHitPoints} is derived from
+     * exactly these values.
      */
     readonly resistances: DamageResistances;
     /**
@@ -142,24 +158,35 @@ interface ShieldMetrics {
      * `Infinity` where a resistance reaches 100%.
      */
     readonly effectiveHitPoints: DamageTypeValues;
-    /** The extra resistance the SYS pips contribute, as a fraction. */
-    readonly systemsResistance: number;
 }
 /**
  * A shield generator's strength multiplier at a given hull mass.
  *
- * @param hullMass - The **hull's** mass, in tonnes (not the loaded ship's).
- * @param generator - The generator's mass/multiplier curve, post-engineering.
+ * @param hullMass - The **hull's** mass, in tonnes (not the loaded ship's). Finite and
+ * non-negative.
+ * @param generator - The generator's mass/multiplier curve, post-engineering. Either all
+ * six curve fields, or a record the catalogue left incomplete — see the `0` cases below.
  * @returns The multiplier to apply to the hull's base shield strength: `minMultiplier`
  * for a hull sitting exactly on `maxMass`, no more than `maxMultiplier` for a
  * featherweight one, and **`0` past `maxMass`** — a generator cannot raise a shield
  * around a hull heavier than it is rated for. Also `0` for a generator whose record is
  * missing part of its curve.
+ * @throws {RangeError} If `hullMass` is not a finite number of zero or more, or if the
+ * generator carries all six curve fields and they are not a physical curve: every one
+ * has to be finite and non-negative, the masses strictly ordered
+ * `minMass < optMass < maxMass` (or all equal, for a constant curve), the multipliers
+ * strictly ordered `minMultiplier < optMultiplier < maxMultiplier` (or all equal), and an
+ * all-equal mass curve must have equal multipliers. A curve that is merely *absent* still
+ * answers `0`: a catalogue record missing any of the six fields is incomplete data, not a
+ * non-physical curve, and this is the only mass-curve outcome that is not a number or a
+ * throw.
  * @remarks
  * The curve is a power law fitted through the generator's three declared points:
  * normalize the mass into `[0, 1]` between `maxMass` and `minMass`, raise it to the
  * exponent that makes the curve pass through `(optMass, optMultiplier)`, then
- * interpolate between `minMultiplier` and `maxMultiplier`.
+ * interpolate between `minMultiplier` and `maxMultiplier`. It is the same curve
+ * `thrusterMassCurveMultiplier` reads a thruster's performance off, and the two agree on
+ * every input they both accept.
  * @example
  * ```ts
  * import { shieldMassCurveMultiplier } from '@elite-dangerous-almanac/core/ships/shields';
@@ -170,6 +197,24 @@ interface ShieldMetrics {
  *   minMultiplier: 0.7, optMultiplier: 1.2, maxMultiplier: 1.7,
  * }); // -> 1.434…
  * ```
+ * @example
+ * ```ts
+ * import { shieldMassCurveMultiplier } from '@elite-dangerous-almanac/core/ships/shields';
+ *
+ * // A generator whose optimal mass sits on its maximum is not a curve at all
+ * try {
+ *   shieldMassCurveMultiplier(400, {
+ *     minMass: 270, optMass: 1350, maxMass: 1350,
+ *     minMultiplier: 0.7, optMultiplier: 1.2, maxMultiplier: 1.7,
+ *   });
+ * } catch (error) {
+ *   (error as Error).message;
+ *   // -> 'shieldMassCurveMultiplier: generator: masses must be strictly ordered minMass < optMass < maxMass, or all equal'
+ * }
+ *
+ * // A record the catalogue left incomplete is data that is missing, not data that is wrong
+ * shieldMassCurveMultiplier(400, { optMass: 540, optMultiplier: 1.2 }); // -> 0
+ * ```
  */
 declare function shieldMassCurveMultiplier(hullMass: number, generator: ShieldGeneratorParams): number;
 /**
@@ -180,24 +225,37 @@ declare function shieldMassCurveMultiplier(hullMass: number, generator: ShieldGe
  * @param generator - The fitted generator, post-engineering.
  * @param boostMultiplier - The boosters' combined multiplier — `1 + Σ shieldBoost`.
  * Defaults to `1` (no boosters).
- * @returns The shield's megajoules, before any Guardian reinforcement addition.
+ * @returns The shield's megajoules, before any Guardian reinforcement addition. `0` for a
+ * hull past the generator's `maxMass`, and `0` for a generator whose record is missing
+ * part of its curve — see {@link shieldMassCurveMultiplier}.
+ * @throws {RangeError} If `hullMass` is not a finite number of zero or more, or the
+ * generator carries a complete but non-physical curve — the contract
+ * {@link shieldMassCurveMultiplier} documents, reported as `shieldStrength`.
  */
 declare function shieldStrength(hullMass: number, baseShieldStrength: number, generator: ShieldGeneratorParams, boostMultiplier?: number): number;
 /**
- * Everything an outfitting screen shows about a build's shields: strength, where it
- * comes from, and the effective resistances.
+ * A build's bare shields: strength, where it comes from, and the resistances the
+ * generator and boosters stack up between them.
+ *
+ * These are the **pip-free** figures, the ones an outfitting screen shows. The SYS
+ * capacitor is a separate story with its own entry point,
+ * {@link shieldCapacitorMetrics}, which takes what this returns and folds a pip
+ * allocation into it.
  *
  * @param input - The hull's mass and base shield strength, the fitted generator, and
- * any powered boosters, Guardian reinforcement and SYS pips.
+ * any powered boosters and Guardian reinforcement.
  * @returns The {@link ShieldMetrics}. With no generator fitted there is no shield for
  * a resistance to apply to: every strength figure is `0` — any `reinforcement` passed is
  * dropped, since a Guardian package has no shield to reinforce — and `resistances` and
- * `effectiveHitPoints` are `0` for every damage type, so a hull with no shields gets no
- * benefit from the SYS pips. The pips are still reported on their own, as
- * `systemsResistance`. `massCurveMultiplier` is `0` and `boostMultiplier` is `1`,
+ * `effectiveHitPoints` are `0` for every damage type.
+ * `massCurveMultiplier` is `0` and `boostMultiplier` is `1`,
  * whatever boosters are fitted, since there is no generator strength to multiply.
- * @throws {RangeError} If `systemsPips` is not a finite number in `[0, 4]`. The pips are
- * checked before the generator, so this applies with no generator fitted too.
+ * @throws {RangeError} With a generator fitted, if `hullMass` is not a finite number of
+ * zero or more, or the generator
+ * carries a complete but non-physical curve — the contract
+ * {@link shieldMassCurveMultiplier} documents, reported as `shieldMetrics`. A generator
+ * whose record is simply *missing* part of its curve is not a failure: `hullMass` is
+ * never read, and `massCurveMultiplier` and every strength figure are `0`.
  * @example
  * ```ts
  * import { shieldMetrics } from '@elite-dangerous-almanac/core/ships/shields';

package/dist/ships/shields.js

@@ -1 +1 @@
-export{shieldMassCurveMultiplier,shieldMetrics,shieldStrength}from"../chunk-2FHHMYDC.js";                             //# sourceMappingURL=shields.js.map
+export{shieldMassCurveMultiplier,shieldMetrics,shieldStrength}from"../chunk-QTAMQ6ME.js";                                                                                       //# sourceMappingURL=shields.js.map