@elite-dangerous-almanac/core 0.1.7 → 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,20 +64,37 @@ 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 {
-    /** Top speed at this mass and ENG allocation, in metres per second. */
+    /**
+     * The loaded mass these figures were calculated at, in tonnes — the
+     * {@link MobilityInput.mass} that went in.
+     *
+     * @remarks
+     * Reported so a build-level caller, which never states the mass itself, can read
+     * what the curve was evaluated at. Against the fitted curve's `optMass` and
+     * `maxMass` it is the build's position on that curve: at or below `optMass` the
+     * thrusters are at or above their rated performance, and past `maxMass` they do not
+     * move the ship at all — {@link massCurveMultiplier} is `0` there.
+     */
+    readonly loadedMass: number;
+    /** 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;
@@ -102,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-24INI4U7.js";//# sourceMappingURL=mobility.js.map
+export{mobilityMetrics,thrusterMassCurveMultiplier}from"../chunk-Y6KJJMIM.js";                                                          //# sourceMappingURL=mobility.js.map

package/dist/ships/modules-all.js

@@ -1 +1 @@
-export{ALL_MODULES}from"../chunk-VDVFJXX5.js";                                                                                                                                                                              //# sourceMappingURL=modules-all.js.map
+export{ALL_MODULES}from"../chunk-QY3L5BKN.js";                                                                                                                                                                              //# sourceMappingURL=modules-all.js.map

package/dist/ships/modules-core.js

@@ -1 +1 @@
-export{CORE_MODULES}from"../chunk-UHSNB5SV.js";                                                          //# sourceMappingURL=modules-core.js.map
+export{CORE_MODULES}from"../chunk-EVJ32UF3.js";                                                          //# sourceMappingURL=modules-core.js.map

package/dist/ships/modules.d.ts

@@ -44,7 +44,7 @@ import { ModuleSlot, SlotRestriction } from './slots.js';
  *
  * @remarks
  * **This is the one default that costs real bundle weight.** A lookup imported from
- * here pulls all four catalogues — 336.5 KiB minified (33.3 KiB gzipped) — since
+ * here pulls all four catalogues — 337.4 KiB minified (33.3 KiB gzipped) — since
  * that is what it falls back to, and passing an explicit catalogue does not undo it.
  * A build that must carry only one category should import that catalogue and search
  * it directly:
@@ -499,6 +499,32 @@ interface OutfittingModuleStats {
      * drive of the same size.
      */
     readonly fsdHeatRate?: number;
+    /**
+     * Frame shift drive: `true` on a Supercruise Overcharge drive, the line the
+     * outfitting screen labels SCO.
+     *
+     * @remarks
+     * A sparse capability flag on the 36 Overcharge drives and absent everywhere else,
+     * including on the 36 ordinary drives of the same sizes and ratings. Read it rather
+     * than matching `Int_Hyperdrive_Overcharge` on the symbol: the capability is the
+     * record's to state, and a pre-engineered or fitted article carries the flag
+     * through while its symbol is not always the one you looked up.
+     *
+     * The two lines share every jump constant this library models, so the flag changes
+     * no calculation here; it is what an outfitting list filters and labels on. The
+     * overcharged supercruise behaviour itself — the boosted acceleration and the extra
+     * fuel it burns — is in-flight behaviour the game publishes no figures for, and the
+     * library models none of it.
+     *
+     * @example
+     * ```ts
+     * import { getModuleBySymbol } from '@elite-dangerous-almanac/core/ships/modules';
+     *
+     * getModuleBySymbol('Int_Hyperdrive_Overcharge_Size5_Class5')?.supercruiseOvercharge; // -> true
+     * getModuleBySymbol('Int_Hyperdrive_Size5_Class5')?.supercruiseOvercharge; // -> undefined
+     * ```
+     */
+    readonly supercruiseOvercharge?: boolean;
     /** Guardian FSD Booster: flat jump-range bonus, in light-years. */
     readonly jumpBoost?: number;
     /** Power plant: power generated, in megawatts. */

package/dist/ships/modules.js

@@ -1 +1 @@
-export{getBulkheadsForShip,getModuleBySymbol,getModulesByName}from"../chunk-LLHGSBPI.js";                                                                                                                                                                                                                                                                     //# sourceMappingURL=modules.js.map
+export{getBulkheadsForShip,getModuleBySymbol,getModulesByName}from"../chunk-PA5EITW5.js";                                                                                                                                                                                                                                                                     //# sourceMappingURL=modules.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-ZZT2PQZ5.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