@elite-dangerous-almanac/core 0.1.0-beta.1

package/dist/ships/experimental-effects.d.ts

@@ -0,0 +1,62 @@
+import { ExperimentalEffect } from './engineering.js';
+import './slef.js';
+import './modules.js';
+import './engineering-options.js';
+import './slots.js';
+
+/**
+ * The **experimental-effect mechanics catalogue** — each engineering special effect's
+ * stat modifiers and qualitative behavior, keyed by the effect's Frontier `fdname` (as it
+ * appears in a journal `Loadout` event's `Engineering.ExperimentalEffect`).
+ *
+ * Its own module (and data file) so consumers who never engineer a build do not bundle
+ * it. Each effect is an {@link ExperimentalEffect} — its `modifiers` (pass to
+ * {@link computeModifiers} alongside a blueprint grade), optional fixed damage-type
+ * conversion, and optional qualitative description. Read it with
+ * {@link getExperimentalEffect}. Material shopping lists live separately in
+ * `ships/experimental-effect-costs`, so build calculations do not bundle them.
+ *
+ * Keys are Frontier `fdname`s — the exact strings a journal `Loadout` event carries in
+ * `Engineering.ExperimentalEffect` (e.g. `"special_fsd_heavy"`), not the in-game
+ * display names. Enumerate the available effects with `Object.keys(EXPERIMENTAL_EFFECTS)`.
+ *
+ * Data from EDSY (`eddb.js` `expeffect`) — coriolis-data does not carry the numeric
+ * experimental modifiers; see [`data/ships/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/ships/SOURCES.md).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Every experimental effect, keyed by Frontier `fdname` (e.g. `"special_fsd_heavy"`).
+ * Each carries its `modifiers` (stat contributions), optional damage conversion, and
+ * optional qualitative description.
+ *
+ * @example
+ * ```ts
+ * import { EXPERIMENTAL_EFFECTS } from '@elite-dangerous-almanac/core/ships/experimental-effects';
+ *
+ * EXPERIMENTAL_EFFECTS['special_fsd_heavy']?.modifiers;
+ * // -> [{ label: 'Integrity', ... }, { label: 'FSDOptimalMass', ... }]
+ * ```
+ */
+declare const EXPERIMENTAL_EFFECTS: Readonly<Record<string, ExperimentalEffect>>;
+/**
+ * Look up an experimental effect by its Frontier `fdname`, case-insensitively.
+ *
+ * @param fdname - The effect id, e.g. `"special_fsd_heavy"`.
+ * @returns The effect record — its display `name`, modifier contributions, optional
+ * `damageDistribution`, and optional qualitative description — or `null` if unknown.
+ * @throws {TypeError} If `fdname` is present and not a string. A nullish
+ * `fdname` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { getExperimentalEffect } from '@elite-dangerous-almanac/core/ships/experimental-effects';
+ *
+ * const effect = getExperimentalEffect('special_fsd_heavy');
+ * effect?.name;      // -> 'Mass Manager'
+ * effect?.modifiers; // -> [{ label: 'Integrity', ... }, ...]
+ * ```
+ */
+declare function getExperimentalEffect(fdname: string): ExperimentalEffect | null;
+
+export { EXPERIMENTAL_EFFECTS, getExperimentalEffect };

package/dist/ships/experimental-effects.js

@@ -0,0 +1 @@
+export{EXPERIMENTAL_EFFECTS,getExperimentalEffect}from"../chunk-PMJG7PHU.js";                                                                                       //# sourceMappingURL=experimental-effects.js.map

package/dist/ships/experimental-effects.js.map

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

package/dist/ships/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Ship and outfitting data for Elite Dangerous — Frontier's shipyard and outfitting
+ * registries.
+ *
+ * This entry point re-exports the ships feature area. Every symbol is also reachable
+ * from its own module, so bundlers can drop anything you do not use.
+ *
+ * **Working with a whole build? Start with {@link ShipLoadout}** — it reads a SLEF
+ * export ({@link ShipLoadout.fromSlef}) or a journal `Loadout` event straight out of a
+ * player journal ({@link ShipLoadout.fromLoadout}), writes either back out
+ * ({@link ShipLoadout.toSlefString}, {@link ShipLoadout.toLoadoutEvent}), lets you fit
+ * modules and apply engineering, and
+ * answers the questions apps actually ask ({@link ShipLoadout.maxJumpRange},
+ * {@link ShipLoadout.powerBudget}, {@link ShipLoadout.shieldMetrics}, `unladenMass`,
+ * `rebuy`) — and keeps what a capture said it *paid* apart from what the build is worth
+ * at retail ({@link ShipLoadout.sourcePurchase}, a {@link SourcePurchaseRecord}). It is
+ * the batteries-included facade and pulls in every catalogue;
+ * everything below is what it is built from, so drop to the pieces when you
+ * need one answer rather than a whole ship.
+ *
+ * The area has five layers:
+ *
+ * - **Ships** — {@link SHIPS} and the {@link getShipBySymbol} / {@link getShipByName}
+ *   lookups. One small catalogue; each {@link Ship} carries the
+ *   hull's identity, stats and slot layout together.
+ * - **Modules** — the {@link OutfittingModule} type and the lookups
+ *   ({@link getModuleBySymbol} & co.), which search all 1199 modules unless you hand
+ *   them a narrower set. Capability guards such as {@link hasFrameShiftDriveJumpStats}
+ *   and {@link hasWeaponDamageStats} narrow the sparse record before stat access. The
+ *   catalogues live on explicit subpaths split by Frontier's
+ *   four outfitting categories — {@link ships/modules-core!CORE_MODULES | CORE_MODULES},
+ *   {@link ships/modules-internal!INTERNAL_MODULES | INTERNAL_MODULES},
+ *   {@link ships/modules-hardpoint!HARDPOINT_MODULES | HARDPOINT_MODULES},
+ *   {@link ships/modules-utility!UTILITY_MODULES | UTILITY_MODULES} and
+ *   {@link ships/modules-all!ALL_MODULES | ALL_MODULES}; each record carries the
+ *   module's identity and its stats. They are reachable only by their own subpath, so
+ *   importing one never bundles the rest.
+ * - **Jump range & SLEF** — {@link singleJumpRange}, {@link fuelPerJump} and
+ *   {@link totalRange} are pure maths over {@link FrameShiftDriveParams} and cost
+ *   nothing but the function; {@link parseSlef} reads an Inara SLEF export — or a bare
+ *   journal `Loadout` event — on its own, and {@link toSlef} / {@link stringifySlef}
+ *   write one back out.
+ * - **Build metrics** — the rest of what an outfitting screen shows, each its own
+ *   data-free module: {@link powerBudget} (what the plant makes against what the build
+ *   draws, by priority group), {@link shieldMetrics} and {@link armourMetrics} (strength,
+ *   hit points and the resistances behind them, stacked by {@link stackShieldResistance}
+ *   / {@link stackArmourResistance}), {@link weaponMetrics} (DPS, sustained DPS,
+ *   capacitor draw and heat) and {@link ammunitionCapacity} (the magazine and the reserve
+ *   behind it, for anything that carries rounds).
+ * - **Engineering** — {@link computeModifiers} applies a {@link BLUEPRINTS} recipe and
+ *   an {@link EXPERIMENTAL_EFFECTS} entry; {@link ENGINEERING_OPTION_GROUPS} answers
+ *   what a module *can* be engineered with, and {@link PRE_ENGINEERED_MODULES} covers
+ *   the fixed-roll modules you cannot craft. {@link DECORATIVE_MODIFICATIONS} is the
+ *   odd one out and the one to reach for when an id resolves to no recipe: the game
+ *   writes a handful of festive transformations in the same field, and no engineer
+ *   applies one. Material shopping data stays on the explicit
+ *   {@link ships/blueprint-costs!BLUEPRINT_COSTS | blueprint-costs} and
+ *   {@link ships/experimental-effect-costs!EXPERIMENTAL_EFFECT_COSTS | experimental-effect-costs}
+ *   subpaths, so build calculations do not pull it in.
+ *
+ * The registries use two distinct Frontier identity spaces. `symbol` identifies an
+ * item — a hull, module, material, micro-resource or commodity — and is what item and
+ * journal `Item` lookups accept. Engineering catalogue entries instead use `fdname` to
+ * identify a recipe, effect or decorative modification. The journal normally writes
+ * that id in `Engineering.BlueprintName` or `Engineering.ExperimentalEffect`; the few
+ * colliding blueprint aliases are resolved for their module by
+ * {@link resolveBlueprintForModule}. Functions that look up an engineering entry
+ * therefore take an `fdname`, while functions that ask which engineering is available
+ * *for a module* take that module's `symbol`.
+ *
+ * Catalogue containers follow those jobs rather than one universal shape. The
+ * identity-bearing entity catalogues — {@link SHIPS} and the module catalogues — are
+ * readonly arrays because every value carries its own `symbol` and consumers commonly
+ * enumerate or filter them. {@link PRE_ENGINEERED_MODULES} is also an array, but it is
+ * an enumerable relation: each row joins a base module to engineering and acquisition
+ * data rather than identifying a new module with a symbol of its own.
+ *
+ * Engineering entities and groups are keyed catalogues: {@link BLUEPRINTS},
+ * {@link EXPERIMENTAL_EFFECTS}, {@link DECORATIVE_MODIFICATIONS} and
+ * {@link ENGINEERING_OPTION_GROUPS} carry the recipe, effect or group identity in the
+ * key rather than repeating it in each value. The separate
+ * {@link ships/blueprint-costs!BLUEPRINT_COSTS | BLUEPRINT_COSTS} and
+ * {@link ships/experimental-effect-costs!EXPERIMENTAL_EFFECT_COSTS | EXPERIMENTAL_EFFECT_COSTS}
+ * records map those ids to costs; {@link SLOT_RESTRICTION_LABELS} maps typed restriction
+ * codes to display labels. Use `Object.values()` or `Object.entries()` to enumerate any
+ * of these keyed structures.
+ *
+ * Five `fdname` maps have public case-insensitive, whitespace-trimming lookups for a
+ * caller- or journal-supplied id: {@link getBlueprint}, {@link getExperimentalEffect},
+ * {@link getDecorativeModification},
+ * {@link ships/blueprint-costs!getBlueprintCosts | getBlueprintCosts} and
+ * {@link ships/experimental-effect-costs!getExperimentalEffectCost | getExperimentalEffectCost}.
+ * Prefer those helpers to direct indexing for external text. Engineering group ids and
+ * slot restriction codes are typed keys, so index their maps directly.
+ *
+ * Note that a hull's derived figures split by cost: cheap stored values are properties
+ * ({@link ShipLoadout.unladenMass}), while anything that recomputes or takes options is
+ * a method ({@link ShipLoadout.maxJumpRange}).
+ *
+ * Identity primarily from EDCD FDevIDs (`shipyard.csv`, `outfitting.csv`), with
+ * supplemental module identities documented in the source record; stats and slot
+ * layouts from EDCD/coriolis-data and EDSY. See [`data/ships/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/ships/SOURCES.md).
+ *
+ * @example
+ * **The whole-build layer.** {@link ShipLoadout} reads a capture and answers the
+ * questions an outfitting screen asks. This is the one to start from, and the one that
+ * pulls in every catalogue.
+ *
+ * ```ts
+ * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ * import type { LoadoutEvent } from '@elite-dangerous-almanac/core/ships/slef';
+ *
+ * declare const event: LoadoutEvent;
+ *
+ * // Figures below are one build's — a Krait Phantom explorer.
+ * const build = ShipLoadout.fromLoadout(event);
+ * build.maxJumpRange(); // -> 60.5478  (ly)
+ * build.powerBudget().withinBudget; // -> true
+ * build.shieldMetrics()?.strength; // -> 743.12   (MJ)
+ * build.weaponMetrics().total.damagePerSecond; // -> 34
+ * ```
+ *
+ * @example
+ * **The lookup layer.** One small hull catalogue, and 1199 modules split by Frontier's
+ * four outfitting categories. Lookups ignore case and surrounding whitespace.
+ *
+ * ```ts
+ * import { getShipBySymbol } from '@elite-dangerous-almanac/core/ships/ships';
+ * import { getModuleBySymbol } from '@elite-dangerous-almanac/core/ships/modules';
+ * import { CORE_MODULES } from '@elite-dangerous-almanac/core/ships/modules-core';
+ *
+ * getShipBySymbol('empire_trader')?.name; // -> 'Imperial Clipper'
+ *
+ * // Pass a category to bound what you bundle; omit it to search all 1199.
+ * CORE_MODULES.length; // -> 521
+ * getModuleBySymbol('Int_Hyperdrive_Size6_Class5', CORE_MODULES)?.name;
+ * // -> 'Frame Shift Drive'
+ * ```
+ *
+ * The catalogues live on their own subpaths (`./modules-core`, `./modules-internal`,
+ * `./modules-hardpoint`, `./modules-utility`, `./modules-all`) precisely so importing
+ * one does not bundle the rest — `./modules-all` is 310.8 KiB.
+ *
+ * @example
+ * **The data-free layer.** Each calculation is its own module over plain constants, so
+ * it costs nothing but the function — no catalogue, no build.
+ *
+ * ```ts
+ * import { singleJumpRange } from '@elite-dangerous-almanac/core/ships/jump-range';
+ *
+ * singleJumpRange(1237.3, 6.8, {
+ *     optMass: 7528.04,
+ *     maxFuel: 6.8,
+ *     fuelMul: 0.011,
+ *     fuelPower: 2.5025,
+ *     jumpBoost: 10.5, // Guardian FSD Booster
+ * }); // -> 89.4147  (ly)
+ * ```
+ *
+ * `./power`, `./shields`, `./armour`, `./weapons`, `./ammunition` and `./resistances`
+ * are the same shape: pass the constants, get the number.
+ *
+ * @example
+ * **The slot layer.** Slot keys come from the game and are not derivable from position,
+ * so read them rather than composing them — and let {@link ShipLoadout.modulesForSlot}
+ * tell you what actually fits.
+ *
+ * ```ts
+ * import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+ *
+ * const build = ShipLoadout.empty('Anaconda');
+ *
+ * build.slots('optional').length; // -> 14
+ * build.slots()[0]?.key; // -> the key setModule takes
+ *
+ * // Only the modules this mount will accept, by size and restriction.
+ * build.modulesForSlot('FrameShiftDrive');
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { SHIPS, Ship, getShipByName, getShipBySymbol, getShipSlots } from './ships.js';
+export { DamageComponents, DamageDistribution, ModuleCategory, ModuleGuidance, ModuleMount, ModuleRating, OutfittingModule, OutfittingModuleIdentity, OutfittingModuleStats, ProjectileRangeBoundaries, getBulkheadsForShip, getModuleBySymbol, getModulesByName } from './modules.js';
+export { FrameShiftDriveJumpStats, MassCurveStats, PowerDistributorStats, PowerGenerationStats, ShieldRegenerationStats, WeaponDamageStats, hasFrameShiftDriveJumpStats, hasMassCurveStats, hasPowerDistributorStats, hasPowerGenerationStats, hasShieldRegenerationStats, hasWeaponDamageStats } from './module-capabilities.js';
+export { EngineeringModifier, LoadoutEvent, LoadoutModule, ModuleEngineering, Slef, SlefDiagnostic, SlefDiagnosticCode, SlefEntry, SlefHeader, SlefInspection, SlefStringifyOptions, getLoadoutModifier, inspectSlef, parseSlef, stringifySlef, toSlef } from './slef.js';
+export { FrameShiftDriveParams, fuelPerJump, singleJumpRange, totalRange } from './jump-range.js';
+export { A as ApplyBlueprintOptions, a as AvailableBlueprint, B as BuildWeaponMetrics, D as DefenceOptions, F as FittedModule, b as FittedWeaponMetrics, J as JumpOptions, c as JumpRangeSummary, L as LoadoutExportOptions, d as LoadoutSlot, S as ShipLoadout, e as SlefExportOptions } from '../ship-loadout-Ba63RDf-.js';
+export { CalculationIssue, CalculationResult, FuelCapacity, LoadoutCalculationModule, calculateCargoCapacity, calculateFuelCapacity, calculateUnladenMass } from './loadout-calculations.js';
+export { LoadoutIssue, LoadoutIssueCode, LoadoutValidation, LoadoutValidationInput, ValidationModule, validateLoadout } from './loadout-validation.js';
+export { SourceModuleValue, SourcePurchaseRecord, getSourceModuleValue, sourcePurchaseFromLoadout, sumSourceModuleValues } from './source-purchase.js';
+export { PowerBand, PowerBudget, PowerConsumer, powerBudget } from './power.js';
+export { DamageResistanceParams, DamageResistances, DamageType, DamageTypeValues, effectiveHitPoints, mapDamageTypes, stackArmourResistance, stackShieldResistance, systemsResistance } from './resistances.js';
+export { ShieldBoosterParams, ShieldGeneratorParams, ShieldInput, ShieldMetrics, shieldMassCurveMultiplier, shieldMetrics, shieldStrength } from './shields.js';
+export { ArmourInput, ArmourMetrics, BulkheadParams, HullReinforcementParams, ModuleReinforcementParams, armourMetrics } from './armour.js';
+export { DamageSplit, WeaponMetrics, WeaponStats, WeaponTotals, armourPiercingFactor, combinedRateOfFire, damageFalloff, damagePerSecond, energyPerSecond, heatPerSecond, splitDamage, sumWeaponMetrics, sustainedDamagePerSecond, sustainedFireFactor, weaponMetrics } from './weapons.js';
+export { AmmunitionCapacity, AmmunitionStats, ammunitionCapacity } from './ammunition.js';
+export { BuildSlot, BuildSlotBase, CoreBuildSlot, CoreSlotType, CoreSlots, HardpointBuildSlot, HardpointRestriction, HardpointSlotSpec, ModuleSlot, OptionalBuildSlot, OptionalRestriction, OptionalSlotSpec, ParsedSlot, SLOT_RESTRICTION_LABELS, ShipSlots, SimpleBuildSlot, SlotKind, SlotRestriction, enumerateSlots, parseSlotName } from './slots.js';
+export { Blueprint, BlueprintFeature, BlueprintGrade, BlueprintGrades, EngineeringMaterial, ExperimentalContribution, ExperimentalEffect, ModifierMethod, computeModifiers, rollsForGrade, sumMaterials } from './engineering.js';
+export { BLUEPRINTS, getBlueprint, getBlueprintGrade } from './blueprints.js';
+export { EXPERIMENTAL_EFFECTS, getExperimentalEffect } from './experimental-effects.js';
+export { ENGINEERING_OPTION_GROUPS, EngineeringGroupId, EngineeringOptionGroup, getBlueprintsForModule, getEngineeringGroup, getExperimentalsForBlueprint, getExperimentalsForModule } from './engineering-options.js';
+export { resolveBlueprintForModule } from './blueprint-journal.js';
+export { DECORATIVE_MODIFICATIONS, DecorativeModification, DecorativeModifier, getDecorativeModification, getDecorativeModificationsForModule, isDecorativeModification } from './decorative-modifications.js';
+export { PRE_ENGINEERED_MODULES, PreEngineeredAcquisition, PreEngineeredModifier, PreEngineeredVariant, getPreEngineeredByBlueprint, getPreEngineeredVariants, isPreEngineered } from './pre-engineered.js';
+export { getPreEngineeredModifiers, getPreEngineeredStats, identifyPreEngineeredVariant, unresolvedModifiers } from './pre-engineered-stats.js';

package/dist/ships/index.js

@@ -0,0 +1 @@
+export{ShipLoadout}from"../chunk-RD73TFGS.js";export{SHIPS,getShipByName,getShipBySymbol,getShipSlots}from"../chunk-462OKHXR.js";export{getLoadoutModifier,inspectSlef,parseSlef,stringifySlef,toSlef}from"../chunk-R4OD62HV.js";export{SLOT_RESTRICTION_LABELS,enumerateSlots,parseSlotName}from"../chunk-I7PIDRMU.js";export{getSourceModuleValue,sourcePurchaseFromLoadout,sumSourceModuleValues}from"../chunk-QTDBO7R2.js";export{powerBudget}from"../chunk-76XKY2Y2.js";export{getPreEngineeredModifiers,getPreEngineeredStats,identifyPreEngineeredVariant,unresolvedModifiers}from"../chunk-TLNHETGC.js";export{armourPiercingFactor,combinedRateOfFire,damageFalloff,damagePerSecond,energyPerSecond,heatPerSecond,splitDamage,sumWeaponMetrics,sustainedDamagePerSecond,sustainedFireFactor,weaponMetrics}from"../chunk-INNFH37U.js";export{getBulkheadsForShip,getModuleBySymbol,getModulesByName}from"../chunk-BRDQUJXV.js";export{PRE_ENGINEERED_MODULES,getPreEngineeredByBlueprint,getPreEngineeredVariants,isPreEngineered}from"../chunk-GJCB2Z72.js";export{shieldMassCurveMultiplier,shieldMetrics,shieldStrength}from"../chunk-2FHHMYDC.js";export{fuelPerJump,singleJumpRange,totalRange}from"../chunk-KG4EWDZZ.js";export{calculateCargoCapacity,calculateFuelCapacity,calculateUnladenMass}from"../chunk-PP2VSA6M.js";export{validateLoadout}from"../chunk-COE5ADYJ.js";export{hasFrameShiftDriveJumpStats,hasMassCurveStats,hasPowerDistributorStats,hasPowerGenerationStats,hasShieldRegenerationStats,hasWeaponDamageStats}from"../chunk-JTQVWIGL.js";                                                                                                                                                                              export{resolveBlueprintForModule}from"../chunk-L2ZZXEZM.js";export{BLUEPRINTS,getBlueprint,getBlueprintGrade}from"../chunk-Q5MR36RW.js";export{DECORATIVE_MODIFICATIONS,getDecorativeModification,getDecorativeModificationsForModule,isDecorativeModification}from"../chunk-6LUEKHO5.js";export{ENGINEERING_OPTION_GROUPS,getBlueprintsForModule,getEngineeringGroup,getExperimentalsForBlueprint,getExperimentalsForModule}from"../chunk-BNILZXJD.js";export{EXPERIMENTAL_EFFECTS,getExperimentalEffect}from"../chunk-PMJG7PHU.js";export{ammunitionCapacity}from"../chunk-AA3K5XUE.js";export{armourMetrics}from"../chunk-FGXWVFN6.js";export{effectiveHitPoints,mapDamageTypes,stackArmourResistance,stackShieldResistance,systemsResistance}from"../chunk-ZNCXENNB.js";export{computeModifiers,rollsForGrade,sumMaterials}from"../chunk-VZZ2XIRE.js";                                                                                       //# sourceMappingURL=index.js.map

package/dist/ships/index.js.map

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

package/dist/ships/jump-range.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Frame-shift-drive **jump-range and fuel** calculations — the data-free core of
+ * the ship-build maths.
+ *
+ * These are the pure functions; they take the drive's constants and the ship's
+ * mass and hand back light-years and tonnes. {@link ShipLoadout} (`./ship-loadout`)
+ * is the convenient front end that pulls the constants out of a SLEF build for you.
+ *
+ * The model is the community-standard one used by EDSY and Coriolis, itself derived
+ * from Frontier's "mass effect on hyperspace range" description
+ * (<https://forums.frontier.co.uk/threads/510879/>). The port is validated against
+ * EDSY: for the sample "Deep Black" build these functions reproduce EDSY's exported
+ * `MaxJumpRange` of 89.414678 LY.
+ *
+ * @remarks
+ * Reference implementation: EDSY. 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
+ */
+/**
+ * The frame shift drive constants a jump calculation needs — all post-engineering.
+ *
+ * @remarks
+ * `optMass` and `maxFuel` are what engineering changes (Long Range raises `optMass`;
+ * some effects change `maxFuel`); `fuelMul` and `fuelPower` are intrinsic to the
+ * drive and never modified. Read these off the drive's module record from
+ * `./modules-core` (and, for a Guardian FSD Booster's `jumpBoost`,
+ * `./modules-internal`), whose records carry their stats.
+ */
+interface FrameShiftDriveParams {
+    /** Optimised mass, in tonnes — finite and positive. */
+    readonly optMass: number;
+    /** Maximum fuel drawn for a single jump, in tonnes — finite and non-negative. */
+    readonly maxFuel: number;
+    /** The drive's finite, positive rating (linear) fuel constant. */
+    readonly fuelMul: number;
+    /** The drive's finite, positive size (power) fuel constant. */
+    readonly fuelPower: number;
+    /**
+     * Flat bonus added to every jump, in light-years, from a Guardian FSD Booster.
+     * Finite and non-negative. Defaults to `0` (no booster).
+     */
+    readonly jumpBoost?: number;
+}
+/**
+ * The range of a single jump, in light-years.
+ *
+ * @param mass - Total ship mass **excluding** the fuel being modelled, in tonnes
+ * (hull + modules + cargo — i.e. unladen mass plus cargo).
+ * @param fuel - Fuel in the tank for this jump, in tonnes. Only up to the drive's
+ * `maxFuel` is burned, but the full amount still adds to the mass being moved.
+ * @param fsd - The drive constants.
+ * @returns The jump distance in light-years, including any `jumpBoost`. `0` if the
+ * drive cannot jump (`maxFuel` or `fuel` = 0).
+ * @remarks
+ * Lighter ships and larger `optMass` jump farther; carrying more fuel than one jump
+ * needs only weighs you down, which is why {@link ShipLoadout.maxJumpRange} loads
+ * exactly one jump's worth.
+ * @throws {RangeError} If a quantity is negative or non-finite, or a required drive
+ * constant is not positive.
+ * @example
+ * ```ts
+ * import { singleJumpRange } from '@elite-dangerous-almanac/core/ships/jump-range';
+ *
+ * singleJumpRange(1237.3, 6.8, { optMass: 7528.04, maxFuel: 6.8, fuelMul: 0.011,
+ *   fuelPower: 2.5025, jumpBoost: 10.5 }); // -> 89.414678
+ * ```
+ */
+declare function singleJumpRange(mass: number, fuel: number, fsd: FrameShiftDriveParams): number;
+/**
+ * The fuel a single jump of a given distance costs, in tonnes.
+ *
+ * @param distance - The jump distance, in light-years. Distances beyond the
+ * {@link singleJumpRange} cost more than the tank holds — the result is capped at
+ * the drive's `maxFuel`.
+ * @param mass - Total ship mass excluding fuel, in tonnes (see
+ * {@link singleJumpRange}).
+ * @param fuel - Fuel in the tank, in tonnes — sets the mass moved and caps the burn.
+ * @param fsd - The drive constants.
+ * @returns Fuel used, in tonnes, in `[0, min(fuel, maxFuel)]`.
+ * @remarks
+ * This is EDSY's model: the cost scales as `(distance / maxRange)^fuelPower` of the
+ * tank's per-jump fuel, where `maxRange` is {@link singleJumpRange} for the same
+ * mass and fuel. It round-trips at the maximum jump —
+ * `fuelPerJump(singleJumpRange(m, f), m, f)` returns `min(f, maxFuel)` — and, with no
+ * Guardian FSD Booster, is the exact inverse of {@link singleJumpRange} at every
+ * distance. With a booster fitted, the booster's flat `jumpBoost` is treated
+ * proportionally (as EDSY does) rather than subtracted, so interior distances are a
+ * close approximation rather than the exact inverse. It matches the fuel figures
+ * EDSY reports.
+ * @throws {RangeError} If a quantity is negative or non-finite, or a required drive
+ * constant is not positive.
+ */
+declare function fuelPerJump(distance: number, mass: number, fuel: number, fsd: FrameShiftDriveParams): number;
+/**
+ * The total multi-jump range on a full tank, in light-years.
+ *
+ * @param mass - Total ship mass excluding fuel, in tonnes (unladen mass plus cargo).
+ * @param fuel - Fuel available to spend, in tonnes — normally the main tank's
+ * capacity.
+ * @param fsd - The drive constants.
+ * @returns The sum of successive jumps as the tank drains, in light-years.
+ * @remarks
+ * Each jump burns up to `maxFuel`; the sum runs until the tank is empty. `mass`
+ * (hull + modules + cargo) stays fixed, while the decreasing `remaining` fuel is
+ * included by {@link singleJumpRange}, so the ship becomes lighter after each jump.
+ * At most 100,000 jumps are evaluated; larger workloads throw instead of returning a
+ * silently truncated range.
+ * @throws {RangeError} If a quantity is negative or non-finite, a required drive
+ * constant is not positive, or the tank would require more than 100,000 jumps.
+ */
+declare function totalRange(mass: number, fuel: number, fsd: FrameShiftDriveParams): number;
+
+export { type FrameShiftDriveParams, fuelPerJump, singleJumpRange, totalRange };

package/dist/ships/jump-range.js

@@ -0,0 +1 @@
+export{fuelPerJump,singleJumpRange,totalRange}from"../chunk-KG4EWDZZ.js";//# sourceMappingURL=jump-range.js.map

package/dist/ships/jump-range.js.map

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

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

@@ -0,0 +1,109 @@
+/**
+ * Pure aggregate calculations for ship loadouts.
+ *
+ * @remarks
+ * These functions deliberately distinguish a genuine zero from an incomplete answer.
+ * They consume already-resolved module contributions, so they neither import the module
+ * catalogues nor know about {@link ShipLoadout}. The facade uses them after resolving
+ * engineering and consumers with their own catalogues can use them directly.
+ *
+ * @packageDocumentation
+ */
+/** A dependency that prevented a loadout calculation from producing a complete value. */
+interface CalculationIssue {
+    /** Field whose value is missing, using the public catalogue spelling. */
+    readonly field: 'hullMass' | 'mass' | 'cargoCapacity' | 'fuelCapacity' | 'reserveFuelCapacity';
+    /** Slot containing the incomplete module, when the dependency belongs to a module. */
+    readonly slot?: string;
+    /** Module symbol, when the dependency belongs to a module. */
+    readonly symbol?: string;
+    /** Human-readable diagnostic suitable for a log or validation panel. */
+    readonly message: string;
+}
+/**
+ * A calculation and the evidence for whether it is complete.
+ *
+ * @typeParam T - The calculated value.
+ */
+type CalculationResult<T> = {
+    /** The complete calculated value. */
+    readonly value: T;
+    /** Discriminator for a complete calculation. */
+    readonly complete: true;
+    /** Complete calculations have no missing inputs. */
+    readonly issues: readonly [];
+} | {
+    /** Incomplete calculations never expose a misleading partial value. */
+    readonly value: null;
+    /** Discriminator for an incomplete calculation. */
+    readonly complete: false;
+    /** One or more missing inputs. */
+    readonly issues: readonly [CalculationIssue, ...CalculationIssue[]];
+};
+/** One fitted module reduced to the contributions aggregate calculations need. */
+interface LoadoutCalculationModule {
+    /** Slot key in the build's own spelling. */
+    readonly slot: string;
+    /** Module symbol. */
+    readonly symbol: string;
+    /** Post-engineering mass in tonnes, or `null` when this fitted module's mass is unknown. */
+    readonly mass: number | null;
+    /** Cargo tonnes; `undefined` for a non-rack and `null` for an unclassified rack. */
+    readonly cargoCapacity?: number | null;
+    /** Fuel tonnes; `undefined` for a non-tank and `null` for an unclassified tank. */
+    readonly fuelCapacity?: number | null;
+}
+/** A ship's fuel-tank capacities, in tonnes. */
+interface FuelCapacity {
+    /** Main tank capacity — the fuel jumps and supercruise draw from. */
+    readonly main: number;
+    /** Reserve tank capacity — the small emergency reserve. */
+    readonly reserve: number;
+}
+/**
+ * Sum hull and fitted-module mass.
+ *
+ * @param hullMass - Empty-hull mass in tonnes, or `null` when unknown.
+ * @param modules - Resolved fitted-module contributions.
+ * @returns Mass in tonnes, or a result listing every missing dependency.
+ * @example
+ * ```ts
+ * import { calculateUnladenMass } from '@elite-dangerous-almanac/core/ships/loadout-calculations';
+ *
+ * const result = calculateUnladenMass(25, [{ slot: 'Radar', symbol: 'sensors', mass: 2 }]);
+ * if (result.complete) result.value; // -> 27 tonnes; narrowed to number
+ * ```
+ */
+declare function calculateUnladenMass(hullMass: number | null, modules: readonly LoadoutCalculationModule[]): CalculationResult<number>;
+/**
+ * Sum fitted cargo racks.
+ *
+ * @param modules - Resolved fitted-module contributions.
+ * @returns Cargo capacity in tonnes. A build with no rack is the complete value `0`.
+ * @example
+ * ```ts
+ * import { calculateCargoCapacity } from '@elite-dangerous-almanac/core/ships/loadout-calculations';
+ *
+ * calculateCargoCapacity([]).value; // -> 0, a complete result
+ * ```
+ */
+declare function calculateCargoCapacity(modules: readonly LoadoutCalculationModule[]): CalculationResult<number>;
+/**
+ * Sum fitted fuel tanks and the hull reserve.
+ *
+ * @param reserveFuelCapacity - Hull reserve in tonnes, or `null` when unknown.
+ * @param modules - Resolved fitted-module contributions.
+ * @returns Main and reserve capacity. No fitted tank is the complete main value `0`.
+ * @example
+ * ```ts
+ * import { calculateFuelCapacity } from '@elite-dangerous-almanac/core/ships/loadout-calculations';
+ *
+ * const result = calculateFuelCapacity(0.3, [
+ *   { slot: 'FuelTank', symbol: 'tank', mass: 2, fuelCapacity: 4 },
+ * ]);
+ * if (result.complete) result.value.main; // -> 4 tonnes
+ * ```
+ */
+declare function calculateFuelCapacity(reserveFuelCapacity: number | null, modules: readonly LoadoutCalculationModule[]): CalculationResult<FuelCapacity>;
+
+export { type CalculationIssue, type CalculationResult, type FuelCapacity, type LoadoutCalculationModule, calculateCargoCapacity, calculateFuelCapacity, calculateUnladenMass };

package/dist/ships/loadout-calculations.js

@@ -0,0 +1 @@
+export{calculateCargoCapacity,calculateFuelCapacity,calculateUnladenMass}from"../chunk-PP2VSA6M.js";                             //# sourceMappingURL=loadout-calculations.js.map

package/dist/ships/loadout-calculations.js.map

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

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

@@ -0,0 +1,80 @@
+import { BuildSlot } from './slots.js';
+
+/**
+ * Structural validation for fitted ship loadouts.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Stable machine-readable reason a loadout is invalid or incomplete.
+ *
+ * @remarks
+ * `duplicateSlot` only ever comes from calling {@link validateLoadout} directly on a
+ * module list you assembled yourself. A `ShipLoadout` cannot report it, because it
+ * refuses to hold two modules in one slot in the first place: `fromLoadout` throws a
+ * `TypeError` on a duplicate, and every edit is keyed by slot. Switch on it when you
+ * validate your own list; skip it when the input came from a build.
+ */
+type LoadoutIssueCode = 'unknownHull' | 'duplicateSlot' | 'unknownSlot' | 'missingRequiredSlot' | 'unknownModule' | 'incompatibleModule';
+/** One validation diagnostic. */
+interface LoadoutIssue {
+    /** Machine-readable reason. */
+    readonly code: LoadoutIssueCode;
+    /** Invalid input is an error; missing catalogue/build data makes the build incomplete. */
+    readonly severity: 'error' | 'incomplete';
+    /** Slot involved, in the build's own spelling when possible. */
+    readonly slot?: string;
+    /** Module symbol involved, when any. */
+    readonly symbol?: string;
+    /** Human-readable explanation. */
+    readonly message: string;
+}
+/** Summary returned by {@link validateLoadout}. */
+interface LoadoutValidation {
+    /** No structurally invalid slots, duplicate keys, or incompatible modules. */
+    readonly valid: boolean;
+    /** Valid, operational core slots filled, and every fitted module classified. */
+    readonly complete: boolean;
+    /** All validation diagnostics. */
+    readonly issues: readonly LoadoutIssue[];
+}
+/** One fitted module reduced to what structural validation needs. */
+interface ValidationModule {
+    /** Slot key in the input's own spelling. */
+    readonly slot: string;
+    /** Module symbol. */
+    readonly symbol: string;
+    /** Whether the caller's module catalogue resolved the symbol. */
+    readonly known: boolean;
+    /** Whether this entry must name one of the hull's outfitting slots. */
+    readonly requiresKnownSlot?: boolean;
+    /** Why the resolved module does not fit, or `null` when it fits. */
+    readonly fitError: string | null;
+}
+/** Input to {@link validateLoadout}. */
+interface LoadoutValidationInput {
+    /** Hull symbol. */
+    readonly shipSymbol: string;
+    /** Expanded hull layout, or `null` for an unknown hull. */
+    readonly slots: readonly BuildSlot[] | null;
+    /** Fitted modules. Duplicate keys must be retained here so they can be diagnosed. */
+    readonly modules: readonly ValidationModule[];
+}
+/**
+ * Validate a resolved fitted build without importing any catalogue.
+ *
+ * @param input - Hull layout and resolved module classifications.
+ * @returns Structural validity, operational completeness, and diagnostics.
+ * @example
+ * ```ts
+ * import { validateLoadout } from '@elite-dangerous-almanac/core/ships/loadout-validation';
+ *
+ * const result = validateLoadout({ shipSymbol: 'FutureShip', slots: null, modules: [] });
+ * result.valid;    // -> true: no impossible fit was claimed
+ * result.complete; // -> false: the hull layout is unknown
+ * ```
+ */
+declare function validateLoadout(input: LoadoutValidationInput): LoadoutValidation;
+
+export { type LoadoutIssue, type LoadoutIssueCode, type LoadoutValidation, type LoadoutValidationInput, type ValidationModule, validateLoadout };

package/dist/ships/loadout-validation.js

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

package/dist/ships/loadout-validation.js.map

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