@elite-dangerous-almanac/core 0.1.8 → 0.2.1

package/dist/ships/loadout-validation.js

@@ -1 +1 @@
-export{validateLoadout}from"../chunk-B4ZSTOM4.js";                                                          //# sourceMappingURL=loadout-validation.js.map
+export{validateLoadout}from"../chunk-OJC6AUL7.js";                                                          //# sourceMappingURL=loadout-validation.js.map

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

@@ -0,0 +1,90 @@
+import { MobilityInput, ThrusterParams } from './mobility.js';
+
+/**
+ * **The ENG capacitor** — speed and handling at a chosen ENG-pip allocation.
+ *
+ * A hull publishes two endpoints for each of speed, pitch, roll and yaw: the figure at
+ * **no** ENG pips (`minimumSpeed`, `minPitch`, `minRoll`, `minYaw`) and the figure at
+ * **four** (`maximumSpeed`, `pitch`, `roll`, `yaw`). The allocation interpolates
+ * linearly between them, and the fitted thruster's mass curves are applied to the
+ * result:
+ *
+ * ```text
+ * speed = (minimumSpeed + (maximumSpeed − minimumSpeed) × pips / 4) × speedCurve(mass)
+ * ```
+ *
+ * Boost does **not** move with the pips, so it is not reported here — it is on
+ * {@link MobilityMetrics.boost}, along with the loaded mass and the two curve
+ * multipliers these figures share.
+ *
+ * This module is data-free. {@link BuildMetrics.mobilityCapacitorMetrics} (in
+ * `./build-metrics`) reads the hull, the loaded mass and the powered thrusters out of a
+ * build and calls {@link mobilityCapacitorMetrics} for you.
+ *
+ * @remarks
+ * Reference implementations: EDCD/Coriolis and EDSY; the algorithm is ported as fact,
+ * not code, and credit and licence terms are in
+ * [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md).
+ *
+ * @packageDocumentation
+ */
+
+/** Everything {@link mobilityCapacitorMetrics} needs about one loaded ship. */
+interface MobilityCapacitorInput extends MobilityInput {
+    /** Finite pips assigned to ENG, in `[0, 4]`. Fractional pips are accepted; defaults to `4`. */
+    readonly enginesPips?: number;
+}
+/**
+ * Speed and rotation rates at one ENG-pip allocation.
+ *
+ * @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 MobilityCapacitorMetrics {
+    /** Pips assigned to ENG for this result, in `[0, 4]`. */
+    readonly enginesPips: number;
+    /** Top speed at this mass and allocation, in metres per second. */
+    readonly speed: number;
+    /** Pitch rate at this mass and allocation, in degrees per second. */
+    readonly pitch: number;
+    /** Roll rate at this mass and allocation, in degrees per second. */
+    readonly roll: number;
+    /** Yaw rate at this mass and allocation, in degrees per second. */
+    readonly yaw: number;
+}
+/**
+ * Calculate a loaded ship's speed and rotation rates at one ENG-pip allocation.
+ *
+ * @param input - The same hull figures, loaded mass and fitted thrusters
+ * {@link mobilityMetrics} takes, plus the allocation to model.
+ * @returns The {@link MobilityCapacitorMetrics}, or `null` without thrusters. A mass
+ * above the thrusters' maximum returns zero performance rather than a fabricated curve
+ * value. At four pips every figure equals its {@link MobilityMetrics} counterpart.
+ * @throws {RangeError} If `enginesPips` is outside `[0, 4]`, an input is not finite or
+ * is outside its documented range, or a thruster curve does not follow the ordering
+ * {@link ThrusterCurveParams} documents. The pips are checked before the hull figures,
+ * so a bad allocation is reported first.
+ * @example
+ * ```ts
+ * import { mobilityCapacitorMetrics } from '@elite-dangerous-almanac/core/ships/mobility-capacitor';
+ *
+ * mobilityCapacitorMetrics({
+ *   minimumSpeed: 100, maximumSpeed: 220, boost: 320,
+ *   minPitch: 34, pitch: 42, minRoll: 110, roll: 110, minYaw: 16, yaw: 16,
+ *   mass: 48,
+ *   thrusters: {
+ *     minMass: 24, optMass: 48, maxMass: 72,
+ *     minMultiplier: 0.83, optMultiplier: 1, maxMultiplier: 1.03,
+ *   },
+ *   enginesPips: 2,
+ * })?.speed; // -> 160
+ * ```
+ */
+declare function mobilityCapacitorMetrics(input: MobilityCapacitorInput & {
+    readonly thrusters: ThrusterParams;
+}): MobilityCapacitorMetrics;
+declare function mobilityCapacitorMetrics(input: MobilityCapacitorInput): MobilityCapacitorMetrics | null;
+
+export { type MobilityCapacitorInput, type MobilityCapacitorMetrics, mobilityCapacitorMetrics };

package/dist/ships/mobility-capacitor.js

@@ -0,0 +1 @@
+export{mobilityCapacitorMetrics}from"../chunk-VEEBJFJ7.js";                                                                                       //# sourceMappingURL=mobility-capacitor.js.map

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

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

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-A4QKXXZD.js";                                                                                       //# sourceMappingURL=mobility.js.map

package/dist/ships/modules-all.js

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

package/dist/ships/modules-core.js

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

package/dist/ships/modules-internal.js

@@ -1 +1 @@
-export{INTERNAL_MODULES}from"../chunk-4ZGUSHTP.js";                                                          //# sourceMappingURL=modules-internal.js.map
+export{INTERNAL_MODULES}from"../chunk-4CBMQULR.js";                                                          //# sourceMappingURL=modules-internal.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 — 337.4 KiB minified (33.3 KiB gzipped) — since
+ * here pulls all four catalogues — 337.6 KiB minified (33.4 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:
@@ -333,6 +333,26 @@ interface OutfittingModuleIdentity {
      * `"ELITE_HORIZONS_V_PLANETARY_LANDINGS"`. Present only on gated modules.
      */
     readonly entitlement?: string;
+    /**
+     * `true` on an article that arrives granted — with a hull or with a bundle — and
+     * that no outfitting screen sells. Absent on every module a station offers.
+     *
+     * @remarks
+     * The fifteen are the nine starter `*_free` fittings and the six bundle-granted
+     * Vessel Hangars. Each is a second identity for an article the game already sells:
+     * `Int_Engine_Size2_Class1_free` is the 2E Thrusters again, which is why
+     * {@link ShipLoadout.modulesForSlot} leaves them out — a picker that offered both
+     * would list "2E Thrusters" twice, once unpriced.
+     *
+     * They are still real fitted articles, so they stay in the catalogues and every
+     * lookup resolves one: a build imported from a journal can carry one, and
+     * {@link getModuleBySymbol} answers for it like any other symbol. Absent is not
+     * `false` — nothing carries `grantOnly: false`.
+     *
+     * Do not read it as a price: {@link OutfittingModule.cost} is missing on these but
+     * also on articles that are sold and simply unpriced by every registry.
+     */
+    readonly grantOnly?: true;
     /**
      * The hull symbol(s) a module is restricted to, when it is ship-specific — e.g.
      * `["Explorer_NX"]` for the Python Mk II's MkII Gravity Optimised thrusters.

package/dist/ships/modules.js

@@ -1 +1 @@
-export{getBulkheadsForShip,getModuleBySymbol,getModulesByName}from"../chunk-PA5EITW5.js";                                                                                                                                                                                                                                                                     //# sourceMappingURL=modules.js.map
+export{getBulkheadsForShip,getModuleBySymbol,getModulesByName}from"../chunk-HUYYGTRM.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-GGQMIQPC.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.7 KiB
+ * minified in a consumer bundle; the complete runtime API is 396.5 KiB (43.2 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 }]
  * ```
@@ -100,11 +100,16 @@ declare function getPreEngineeredJournalModifiers(variant: PreEngineeredVariant)
  *
  * A locked fixed article is also identified by its unique
  * symbol/blueprint/grade/experimental tuple when a SLEF capture omits the `Modifiers` key
- * entirely. A present empty or partial array does not use this shortcut: older library
- * exports can carry an ordinary roll with the same tuple, and its values must not be
- * replaced by reward stats. A third-party export can omit the array from such a roll;
- * that record is indistinguishable from the fixed article, so the catalogue identity
- * wins.
+ * entirely: being final, no ordinary roll could have written that tuple. A present empty
+ * or partial array does not use this shortcut: older library exports can carry an ordinary
+ * roll with the same tuple, and its values must not be replaced by reward stats. A third-
+ * party export can omit the array from such a roll; that record is indistinguishable from
+ * the fixed article, so the catalogue identity wins.
+ *
+ * An unlocked article that shares a blueprint with no craftable recipe of its base module
+ * is identified the same way, but by `ShipLoadout.fromLoadout` rather than here — that
+ * reading needs each module's engineering menu, a catalogue this module deliberately does
+ * not carry into a consumer's bundle.
  *
  * Frontier journals and captures may omit a derived modifier, so one predicted value may
  * be absent. Every stated predicted value must agree within journal float noise, and all
@@ -165,13 +170,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-JET673E5.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-F44QX47A.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-XQJERZUS.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-JMAXSXXQ.js";                                                          //# sourceMappingURL=shield-recovery.js.map