@elite-dangerous-almanac/core 0.1.8 → 0.2.0

package/dist/i18n/experimental-effect-descriptions.d.ts

@@ -2,11 +2,12 @@
 /**
  * Look up an experimental effect's display description.
  *
- * @param fdname - Frontier's experimental-effect id.
+ * @param experimentalEffectSymbol - Frontier's experimental-effect id. Matching ignores case and
+ * surrounding whitespace.
  * @param locale - A BCP 47 locale. The current source supplies canonical English only.
  * @returns The localized description, or `null` when the effect is unknown, has no
  * source description, or the requested locale is unavailable.
- * @throws {TypeError} If a present `fdname` or `locale` is not a string.
+ * @throws {TypeError} If a present `experimentalEffectSymbol` or `locale` is not a string.
  * @example
  * ```ts
  * import { getExperimentalEffectDescription } from '@elite-dangerous-almanac/core/i18n/experimental-effect-descriptions';
@@ -15,6 +16,6 @@
  * getExperimentalEffectDescription('special_auto_loader', 'fr'); // -> null
  * ```
  */
-declare function getExperimentalEffectDescription(fdname: string, locale: string): string | null;
+declare function getExperimentalEffectDescription(experimentalEffectSymbol: string, locale: string): string | null;
 
 export { getExperimentalEffectDescription };

package/dist/i18n/experimental-effect-descriptions.js

@@ -1 +1 @@
-export{getExperimentalEffectDescription}from"../chunk-4S6WB7QR.js";                                                                                       //# sourceMappingURL=experimental-effect-descriptions.js.map
+export{getExperimentalEffectDescription}from"../chunk-FF2X4K5P.js";                                                                                       //# sourceMappingURL=experimental-effect-descriptions.js.map

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

@@ -2,7 +2,7 @@
 /**
  * Look up an engineering experimental effect's source-backed display name for a locale.
  *
- * @param fdname - Frontier's experimental-effect id, such as
+ * @param experimentalEffectSymbol - Frontier's experimental-effect id, such as
  * `"special_concordant_sequence"`. Matching ignores case and surrounding whitespace.
  * @param locale - A BCP 47 language or regional tag, such as `"de"`, `"de-DE"` or
  * `"en-GB"`. Matching is case-insensitive; underscores are accepted in place of
@@ -14,8 +14,9 @@
  * @remarks
  * This function bundles names only, not modifier mechanics or material costs. Missing
  * translations never silently fall back to English.
- * @throws {TypeError} If `fdname` is present and not a string, or `locale` is not a
- * string. A nullish `fdname` is a lookup miss and returns `null`.
+ * @throws {TypeError} If `experimentalEffectSymbol` is present and not a string, or
+ * `locale` is not a string. A nullish `experimentalEffectSymbol` is a lookup miss and
+ * returns `null`.
  * @example
  * ```ts
  * import { getExperimentalEffectName } from '@elite-dangerous-almanac/core/i18n/experimental-effects';
@@ -25,6 +26,6 @@
  * getExperimentalEffectName('special_concordant_sequence', 'ja-JP'); // -> null
  * ```
  */
-declare function getExperimentalEffectName(fdname: string, locale: string): string | null;
+declare function getExperimentalEffectName(experimentalEffectSymbol: string, locale: string): string | null;
 
 export { getExperimentalEffectName };

package/dist/i18n/experimental-effects.js

@@ -1 +1 @@
-export{getExperimentalEffectName}from"../chunk-CJWFY6OX.js";                                                                                       //# sourceMappingURL=experimental-effects.js.map
+export{getExperimentalEffectName}from"../chunk-DSMLYA2M.js";                                                                                       //# sourceMappingURL=experimental-effects.js.map

package/dist/i18n/index.d.ts

@@ -18,20 +18,8 @@ import '../ships/engineering-options.js';
 import '../ships/module-families.js';
 import '../ships/ship-loadout.js';
 import '../ships/slef.js';
-import '../ships/jump-range.js';
-import '../ships/engineering.js';
-import '../ships/power.js';
-import '../ships/heat.js';
-import '../ships/shields.js';
-import '../ships/resistances.js';
-import '../ships/armour.js';
-import '../ships/weapons.js';
-import '../ships/ammunition.js';
-import '../ships/weapons-capacitor.js';
-import '../ships/distributor.js';
-import '../ships/mobility.js';
-import '../ships/shield-recovery.js';
 import '../ships/pre-engineered.js';
+import '../ships/ammunition.js';
 import '../ships/source-purchase.js';
 
 /**

package/dist/i18n/index.js

@@ -1 +1 @@
-export{getMicroResourceName}from"../chunk-GRSNX36B.js";export{getOutfittingFamilyName}from"../chunk-SD6GNFDX.js";export{getModuleName}from"../chunk-LZYHBFJC.js";export{getPreEngineeredVariantName}from"../chunk-J42ZXLBL.js";export{getShipManufacturer,getShipName}from"../chunk-KJFUNIIY.js";export{getLoadoutSlotName,getSlotRestrictionLabel}from"../chunk-ZRG35JSH.js";                                                          export{getBlueprintName}from"../chunk-Z6XMXMVI.js";export{getCalculationIssueMessage,getLoadoutEditErrorMessage,getLoadoutIssueMessage,getSlefDiagnosticMessage}from"../chunk-6G6TYW2D.js";export{getEngineeringGroupName}from"../chunk-EKQCVCMK.js";export{getExperimentalEffectDescription}from"../chunk-4S6WB7QR.js";export{getExperimentalEffectName}from"../chunk-CJWFY6OX.js";export{getMaterialName}from"../chunk-TW7LUBHD.js";                                                                                                                    //# sourceMappingURL=index.js.map
+export{getMicroResourceName}from"../chunk-GRSNX36B.js";export{getOutfittingFamilyName}from"../chunk-SD6GNFDX.js";export{getModuleName}from"../chunk-LZYHBFJC.js";export{getPreEngineeredVariantName}from"../chunk-T62GO4AA.js";export{getShipManufacturer,getShipName}from"../chunk-KJFUNIIY.js";export{getLoadoutSlotName,getSlotRestrictionLabel}from"../chunk-ZRG35JSH.js";                                                          export{getBlueprintName}from"../chunk-DBDCOHI4.js";export{getCalculationIssueMessage,getLoadoutEditErrorMessage,getLoadoutIssueMessage,getSlefDiagnosticMessage}from"../chunk-6G6TYW2D.js";export{getEngineeringGroupName}from"../chunk-5ZVYRX6Z.js";export{getExperimentalEffectDescription}from"../chunk-FF2X4K5P.js";export{getExperimentalEffectName}from"../chunk-DSMLYA2M.js";export{getMaterialName}from"../chunk-TW7LUBHD.js";                                                                                                                    //# sourceMappingURL=index.js.map

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

@@ -6,10 +6,10 @@ import { PreEngineeredAcquisition } from '../ships/pre-engineered.js';
 interface PreEngineeredVariantIdentity {
     /** Base outfitting-module symbol. */
     readonly symbol: string;
-    /** Frontier blueprint or fixed-reward id. */
-    readonly blueprint: string;
-    /** Frontier experimental-effect id, or `null`/omitted when none is fitted. */
-    readonly experimental?: string | null;
+    /** Frontier blueprint or fixed-reward symbol. */
+    readonly blueprintSymbol: string;
+    /** Frontier experimental-effect symbol, or `null`/omitted when none is fitted. */
+    readonly experimentalEffectSymbol?: string | null;
     /** Route through which the variant is obtained. */
     readonly acquisition: PreEngineeredAcquisition;
 }
@@ -22,14 +22,15 @@ interface PreEngineeredVariantIdentity {
  * @returns The explicit localized name, or `null` for an unknown variant or unavailable
  * translation. Decorative reward names currently have English values only.
  * @throws {TypeError} If `variant` is not an object, a required identity field or a
- * non-null `experimental` value is not a string, or `locale` is not a string.
+ * non-null `experimentalEffectSymbol` value is not a string, or `locale` is not a
+ * string.
  * @example
  * ```ts
  * import { getPreEngineeredVariantName } from '@elite-dangerous-almanac/core/i18n/pre-engineered';
  *
  * getPreEngineeredVariantName({
  *   symbol: 'Hpt_FlakMortar_Turret_Medium',
- *   blueprint: 'Decorative_Red',
+ *   blueprintSymbol: 'Decorative_Red',
  *   acquisition: 'eventReward',
  * }, 'en'); // -> 'Festive Red Remote Release Flak Launcher'
  * ```

package/dist/i18n/pre-engineered.js

@@ -1 +1 @@
-export{getPreEngineeredVariantName}from"../chunk-J42ZXLBL.js";                                                                                       //# sourceMappingURL=pre-engineered.js.map
+export{getPreEngineeredVariantName}from"../chunk-T62GO4AA.js";                                                                                       //# sourceMappingURL=pre-engineered.js.map

package/dist/materials/index.d.ts

@@ -22,14 +22,26 @@
  * getMicroResourceBySymbol('graphene')?.name;     // -> 'Graphene'
  * ```
  *
- * Every lookup also takes an optional trailing argument to **narrow** the search to
- * a subset — one category's catalogue, or an array you have filtered yourself:
+ * The by-key lookups also take an optional trailing argument to **narrow** the search
+ * to a subset — one category's catalogue, or an array you have filtered yourself. It
+ * must be one of the exported catalogues *by reference*; `ALL_MATERIALS` (or omitting
+ * it) is the one that answers from an index rather than a scan:
  *
  * ```ts
- * import { materialsByGrade } from '@elite-dangerous-almanac/core/materials';
+ * import { getMaterialByName } from '@elite-dangerous-almanac/core/materials';
  * import { RAW_MATERIALS } from '@elite-dangerous-almanac/core/materials/materials-raw';
  *
- * materialsByGrade(MaterialGrade.Rare, RAW_MATERIALS).length; // -> 7, one per raw line
+ * getMaterialByName('imperial shielding', RAW_MATERIALS); // -> null; it is manufactured
+ * ```
+ *
+ * A lookup that returns an array takes no catalogue — narrow its result, or the subset
+ * you already imported, with `.filter()`:
+ *
+ * ```ts
+ * import { MaterialGrade } from '@elite-dangerous-almanac/core/materials';
+ * import { RAW_MATERIALS } from '@elite-dangerous-almanac/core/materials/materials-raw';
+ *
+ * RAW_MATERIALS.filter((m) => m.grade === MaterialGrade.Rare).length; // -> 7, one per raw line
  * ```
  *
  * @packageDocumentation

package/dist/materials/index.js

@@ -1 +1 @@
-export{getMicroResourceByName,getMicroResourceBySymbol,microResourcesInCategory}from"../chunk-MKGJPVPS.js";export{MaterialGrade,MaterialLine,getMaterialByElementSymbol,getMaterialByName,getMaterialBySymbol,materialsByGrade,materialsInCategory,materialsInLine}from"../chunk-IOJXLDJN.js";export{ALL_MICRO_RESOURCES}from"../chunk-GVNTKCVF.js";export{ITEM_MICRO_RESOURCES}from"../chunk-WHWFKHV3.js";export{COMPONENT_MICRO_RESOURCES}from"../chunk-HTB52N6S.js";export{CONSUMABLE_MICRO_RESOURCES}from"../chunk-K7L7SMIR.js";export{DATA_MICRO_RESOURCES}from"../chunk-GVLDFJEY.js";                             export{ALL_MATERIALS}from"../chunk-V4C6FIE2.js";export{ENCODED_MATERIALS}from"../chunk-Q5XOGATC.js";export{MANUFACTURED_MATERIALS}from"../chunk-HKXXFIRI.js";export{RAW_MATERIALS}from"../chunk-SQS7672E.js";                                                                                                                    //# sourceMappingURL=index.js.map
+export{getMicroResourceByName,getMicroResourceBySymbol,microResourcesInCategory}from"../chunk-MRTTQYT5.js";export{MaterialGrade,MaterialLine,getMaterialByElementSymbol,getMaterialByName,getMaterialBySymbol,materialsByGrade,materialsInCategory,materialsInLine}from"../chunk-OYR5HUQZ.js";export{ALL_MICRO_RESOURCES}from"../chunk-GVNTKCVF.js";export{ITEM_MICRO_RESOURCES}from"../chunk-WHWFKHV3.js";export{COMPONENT_MICRO_RESOURCES}from"../chunk-HTB52N6S.js";export{CONSUMABLE_MICRO_RESOURCES}from"../chunk-K7L7SMIR.js";export{DATA_MICRO_RESOURCES}from"../chunk-GVLDFJEY.js";                             export{ALL_MATERIALS}from"../chunk-V4C6FIE2.js";export{ENCODED_MATERIALS}from"../chunk-Q5XOGATC.js";export{MANUFACTURED_MATERIALS}from"../chunk-HKXXFIRI.js";export{RAW_MATERIALS}from"../chunk-SQS7672E.js";                                                                                                                    //# sourceMappingURL=index.js.map

package/dist/materials/materials.d.ts

@@ -16,8 +16,9 @@
  * getMaterialByName('iron')?.grade; // -> MaterialGrade.VeryCommon (1)
  * ```
  *
- * Each lookup takes an optional second argument to **narrow** the search to a
- * subset — one category's catalogue, or any array you have filtered yourself:
+ * The three **by-key** lookups take an optional second argument to **narrow** the
+ * search to a subset — one category's catalogue, or any array you have filtered
+ * yourself:
  *
  * | Module | Export | Entries |
  * | --- | --- | --- |
@@ -27,9 +28,19 @@
  * | `./materials-all` | `ALL_MATERIALS` | 146 (the default) |
  *
  * It narrows *results*, not bundle size: importing a lookup pulls all three
- * catalogues, since that is what it falls back to — 16.9 KiB minified for all 146.
+ * catalogues, since that is what it falls back to — 17.2 KiB minified for all 146.
  * {@link materialsInCategory} reaches the same subsets from a plain string.
  *
+ * **Only `ALL_MATERIALS` itself is indexed.** A by-key lookup answers from an O(1)
+ * index when the catalogue you pass *is* `ALL_MATERIALS` — the same object, not a copy
+ * — and scans linearly otherwise, including for `[...ALL_MATERIALS]`, which holds the
+ * same 146 records. Omitting the argument always takes the indexed path, so pass one
+ * only when you mean to exclude the rest.
+ *
+ * The filtering lookups ({@link materialsByGrade}, {@link materialsInLine},
+ * {@link materialsInCategory}) take no catalogue: each returns an array, so narrowing
+ * one is `.filter()` on the result or on the subset you already imported.
+ *
  * Data originates from EDCD FDevIDs, with Thargoid materials absent from that
  * pinned source supplied by INARA; see [`data/materials/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/materials/SOURCES.md).
  *
@@ -168,10 +179,14 @@ interface Material {
  * Here, `symbol` is Frontier's internal item id for the material.
  *
  * @param symbol - The internal symbol, e.g. `"GridResistors"`, or the lower-cased
- * form the player journal reports (`"gridresistors"`).
+ * form the player journal reports (`"gridresistors"`). Leading/trailing whitespace
+ * and case are ignored.
  * @param materials - Optional subset to search instead of all 146 materials —
  * `RAW_MATERIALS`, `MANUFACTURED_MATERIALS`, `ENCODED_MATERIALS`, or any array you
- * have filtered yourself. Omit it unless you specifically want to exclude the rest.
+ * have filtered yourself. Omit it unless you specifically want to exclude the rest:
+ * the indexed O(1) path is taken only when the argument is omitted or is
+ * `ALL_MATERIALS` **by reference**, and every other array — a copy of that same
+ * catalogue included — is scanned.
  * @returns The matching {@link Material}, or `null` if no material has that symbol.
  * @throws {TypeError} If `symbol` is present and not a string. A nullish
  * `symbol` is a miss, answered the way an unrecognised one is.
@@ -187,6 +202,7 @@ declare function getMaterialBySymbol(symbol: string, materials?: readonly Materi
  * Look up a material by its display name (case-insensitive).
  *
  * @param name - The display name as the catalogue spells it, e.g. `"Grid Resistors"`.
+ * Leading/trailing whitespace and case are ignored.
  * @param materials - Optional subset to search (see {@link getMaterialBySymbol}).
  * @returns The matching {@link Material}, or `null` if no material has that name.
  * @throws {TypeError} If `name` is present and not a string. A nullish
@@ -202,7 +218,8 @@ declare function getMaterialByName(name: string, materials?: readonly Material[]
 /**
  * Look up a raw material by its chemical element symbol (case-insensitive).
  *
- * @param elementSymbol - The element symbol, e.g. `"Fe"` or `"fe"`.
+ * @param elementSymbol - The element symbol, e.g. `"Fe"` or `"fe"`. Leading/trailing
+ * whitespace and case are ignored.
  * @param materials - Optional subset to search (see {@link getMaterialBySymbol}).
  * @returns The matching {@link Material}, or `null`. Only raw materials carry an
  * element symbol, so a manufactured or encoded subset never matches.
@@ -217,29 +234,30 @@ declare function getMaterialByName(name: string, materials?: readonly Material[]
  */
 declare function getMaterialByElementSymbol(elementSymbol: string, materials?: readonly Material[]): Material | null;
 /**
- * Every material of a given grade, in catalogue order.
+ * Every material of a given grade, across all three categories, in catalogue order.
  *
- * @param grade - The grade to match, 1–5 (or a {@link MaterialGrade} member).
- * @param materials - Optional subset to search (see {@link getMaterialBySymbol}).
- * @returns A new array of matches (possibly empty). The input is not modified.
+ * @param grade - The grade to match, 1–5 (or a {@link MaterialGrade} member). A grade
+ * no material carries matches nothing, the way an unrecognised symbol does.
+ * @returns A new array of matches (possibly empty).
+ * @throws {TypeError} If `grade` is present and not a number. A nullish `grade` is a
+ * miss, answered the way an unrecognised one is.
  * @example
  * ```ts
  * import { MaterialGrade, materialsByGrade } from '@elite-dangerous-almanac/core/materials/materials';
  * import { RAW_MATERIALS } from '@elite-dangerous-almanac/core/materials/materials-raw';
  *
- * materialsByGrade(MaterialGrade.VeryRare).length;                 // -> across every category
- * materialsByGrade(MaterialGrade.Rare, RAW_MATERIALS).length;      // -> 7, one per raw line
+ * materialsByGrade(MaterialGrade.VeryRare).length;                        // -> across every category
+ * RAW_MATERIALS.filter((m) => m.grade === MaterialGrade.Rare).length;     // -> 7, one per raw line
  * ```
  */
-declare function materialsByGrade(grade: MaterialGrade, materials?: readonly Material[]): Material[];
+declare function materialsByGrade(grade: MaterialGrade): Material[];
 /**
  * Every material in a given line, in catalogue order.
  *
  * @param line - The line to match, e.g. `MaterialLine.Chemical`. A plain string of
  * the line's value works too: leading/trailing whitespace and case are ignored, like
  * every other lookup here.
- * @param materials - Optional subset to search (see {@link getMaterialBySymbol}).
- * @returns A new array of matches (possibly empty). The input is not modified.
+ * @returns A new array of matches (possibly empty).
  * @throws {TypeError} If `line` is present and not a string. A nullish
  * `line` is a miss, answered the way an unrecognised one is.
  * @example
@@ -249,7 +267,7 @@ declare function materialsByGrade(grade: MaterialGrade, materials?: readonly Mat
  * materialsInLine(MaterialLine.Chemical).map((m) => m.grade); // -> [1, 2, 3, 4, 5]
  * ```
  */
-declare function materialsInLine(line: string, materials?: readonly Material[]): Material[];
+declare function materialsInLine(line: string): Material[];
 /**
  * Every material in a given category, in catalogue order.
  *
@@ -260,8 +278,7 @@ declare function materialsInLine(line: string, materials?: readonly Material[]):
  *
  * @param category - The category to match: `'raw'`, `'manufactured'` or `'encoded'`.
  * Leading/trailing whitespace and case are ignored, like every other lookup here.
- * @param materials - Optional subset to search (see {@link getMaterialBySymbol}).
- * @returns A new array of matches (possibly empty). The input is not modified.
+ * @returns A new array of matches (possibly empty).
  * @throws {TypeError} If `category` is present and not a string. A nullish
  * `category` is a miss, answered the way an unrecognised one is.
  * @example
@@ -272,6 +289,6 @@ declare function materialsInLine(line: string, materials?: readonly Material[]):
  * materialsInCategory('Encoded').length;      // -> 47; case is ignored
  * ```
  */
-declare function materialsInCategory(category: string, materials?: readonly Material[]): Material[];
+declare function materialsInCategory(category: string): Material[];
 
 export { type Material, type MaterialCategory, MaterialGrade, MaterialLine, getMaterialByElementSymbol, getMaterialByName, getMaterialBySymbol, materialsByGrade, materialsInCategory, materialsInLine };

package/dist/materials/materials.js

@@ -1 +1 @@
-export{MaterialGrade,MaterialLine,getMaterialByElementSymbol,getMaterialByName,getMaterialBySymbol,materialsByGrade,materialsInCategory,materialsInLine}from"../chunk-IOJXLDJN.js";                                                                                                                                                                                                           //# sourceMappingURL=materials.js.map
+export{MaterialGrade,MaterialLine,getMaterialByElementSymbol,getMaterialByName,getMaterialBySymbol,materialsByGrade,materialsInCategory,materialsInLine}from"../chunk-OYR5HUQZ.js";                                                                                                                                                                                                           //# sourceMappingURL=materials.js.map

package/dist/materials/micro-resources.d.ts

@@ -15,8 +15,8 @@
  * getMicroResourceBySymbol('graphene')?.category; // -> 'component'
  * ```
  *
- * Each lookup takes an optional second argument to **narrow** the search to a
- * subset — one category's catalogue, or any array you have filtered yourself:
+ * The two **by-key** lookups take an optional second argument to **narrow** the search
+ * to a subset — one category's catalogue, or any array you have filtered yourself:
  *
  * | Module | Export | Entries |
  * | --- | --- | --- |
@@ -27,9 +27,18 @@
  * | `./micro-resources-all` | `ALL_MICRO_RESOURCES` | 226 (the default) |
  *
  * It narrows *results*, not bundle size: importing a lookup pulls all four
- * catalogues, since that is what it falls back to — 13.0 KiB minified for all 226.
+ * catalogues, since that is what it falls back to — 13.4 KiB minified for all 226.
  * {@link microResourcesInCategory} reaches the same subsets from a plain string.
  *
+ * **Only `ALL_MICRO_RESOURCES` itself is indexed.** A by-key lookup answers from an
+ * O(1) index when the catalogue you pass *is* `ALL_MICRO_RESOURCES` — the same object,
+ * not a copy — and scans linearly otherwise, including for `[...ALL_MICRO_RESOURCES]`,
+ * which holds the same 226 records. Omitting the argument always takes the indexed
+ * path, so pass one only when you mean to exclude the rest.
+ *
+ * {@link microResourcesInCategory} takes no catalogue: it returns an array, so
+ * narrowing it is `.filter()` on the result or on the subset you already imported.
+ *
  * Data originates from EDCD FDevIDs (`microresources.csv`), in-game verification and
  * Inara; see [`data/materials/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/materials/SOURCES.md).
  *
@@ -83,7 +92,10 @@ interface MicroResource {
  * @param microResources - Optional subset to search instead of all 226 micro
  * resources — `COMPONENT_MICRO_RESOURCES`, `CONSUMABLE_MICRO_RESOURCES`,
  * `DATA_MICRO_RESOURCES`, `ITEM_MICRO_RESOURCES`, or any array you have filtered
- * yourself. Omit it unless you specifically want to exclude the rest.
+ * yourself. Omit it unless you specifically want to exclude the rest: the indexed O(1)
+ * path is taken only when the argument is omitted or is `ALL_MICRO_RESOURCES` **by
+ * reference**, and every other array — a copy of that same catalogue included — is
+ * scanned.
  * @returns The matching {@link MicroResource}, or `null` if no micro resource has
  * that symbol.
  * @throws {TypeError} If `symbol` is present and not a string. A nullish
@@ -119,8 +131,7 @@ declare function getMicroResourceByName(name: string, microResources?: readonly
  *
  * @param category - The category to match, e.g. `'component'`. Leading/trailing
  * whitespace and case are ignored, like every other lookup here.
- * @param microResources - Optional subset to search (see {@link getMicroResourceBySymbol}).
- * @returns A new array of matches (possibly empty). The input is not modified.
+ * @returns A new array of matches (possibly empty).
  * @throws {TypeError} If `category` is present and not a string. A nullish
  * `category` is a miss, answered the way an unrecognised one is.
  * @example
@@ -131,6 +142,6 @@ declare function getMicroResourceByName(name: string, microResources?: readonly
  * microResourcesInCategory('Consumable').length; // -> 6; case is ignored
  * ```
  */
-declare function microResourcesInCategory(category: string, microResources?: readonly MicroResource[]): MicroResource[];
+declare function microResourcesInCategory(category: string): MicroResource[];
 
 export { type MicroResource, type MicroResourceCategory, getMicroResourceByName, getMicroResourceBySymbol, microResourcesInCategory };

package/dist/materials/micro-resources.js

@@ -1 +1 @@
-export{getMicroResourceByName,getMicroResourceBySymbol,microResourcesInCategory}from"../chunk-MKGJPVPS.js";                                                                                                                                                                                                                                                                     //# sourceMappingURL=micro-resources.js.map
+export{getMicroResourceByName,getMicroResourceBySymbol,microResourcesInCategory}from"../chunk-MRTTQYT5.js";                                                                                                                                                                                                                                                                     //# sourceMappingURL=micro-resources.js.map

package/dist/ships/armour.d.ts

@@ -14,7 +14,7 @@ import { DamageResistanceParams, DamageResistances, DamageTypeValues } from './r
  * stack onto with diminishing returns — see `./resistances`. Module reinforcement
  * packages protect the *modules* rather than the hull, and are reported separately.
  *
- * This module is data-free. {@link ShipLoadout.armourMetrics} (in `./ship-loadout`)
+ * This module is data-free. {@link BuildMetrics.armourMetrics} (in `./build-metrics`)
  * gathers a build's bulkhead and reinforcement packages, post-engineering, and calls
  * {@link armourMetrics} for you.
  *
@@ -77,7 +77,7 @@ interface ArmourInput {
      * @remarks
      * Absent means **no** bulkhead: no armour bonus and no resistances, so the hull
      * reports its bare `baseArmour`. No ship in the game flies like that;
-     * `ShipLoadout.armourMetrics()` substitutes the hull's stock lightweight alloy
+     * `BuildMetrics.armourMetrics()` substitutes the hull's stock lightweight alloy
      * instead, and you should pass the hull's own armour record here to do the same.
      */
     readonly bulkhead?: BulkheadParams | null;
@@ -86,7 +86,14 @@ interface ArmourInput {
     /** Each fitted, powered module reinforcement package. Defaults to none. */
     readonly moduleReinforcements?: readonly ModuleReinforcementParams[];
 }
-/** A build's armour: hit points, where they come from, and what the hull resists. */
+/**
+ * A build's armour: hit points, where they come from, and what the hull resists.
+ *
+ * @remarks
+ * Frozen — nested records and lists included — so a result can be held, cached and
+ * shared without a defensive copy. Derive a changed figure with a spread rather than
+ * by assigning into one.
+ */
 interface ArmourMetrics {
     /** Total hull hit points. */
     readonly hitPoints: number;
@@ -94,7 +101,16 @@ interface ArmourMetrics {
     readonly bulkheads: number;
     /** What the hull reinforcement packages add. */
     readonly reinforcement: number;
-    /** Effective resistances, bulkhead and reinforcement stacked with diminishing returns. */
+    /**
+     * Effective resistances, bulkhead and reinforcement stacked with diminishing returns.
+     *
+     * @remarks
+     * Fractions rather than percentages, and **unrounded**: the stacking is
+     * floating-point arithmetic, so a nominal −20% reads as `-0.19999999999999996`
+     * rather than `-0.2`. Round where the figure is displayed, not before it is
+     * composed further — {@link ArmourMetrics.effectiveHitPoints} is derived from
+     * exactly these values.
+     */
     readonly resistances: DamageResistances;
     /**
      * Effective hit points against each damage type — `hitPoints / (1 − resistance)`,

package/dist/ships/armour.js

@@ -1 +1 @@
-export{armourMetrics}from"../chunk-FGXWVFN6.js";                             //# sourceMappingURL=armour.js.map
+export{armourMetrics}from"../chunk-FYVPZBXN.js";                                                          //# sourceMappingURL=armour.js.map

package/dist/ships/blueprint-costs.d.ts

@@ -39,7 +39,7 @@ import './slots.js';
  */
 type BlueprintGradeCosts = Readonly<Record<string, readonly EngineeringMaterial[]>>;
 /**
- * Every craftable blueprint's per-roll material recipes, keyed by Frontier `fdname` and then grade.
+ * Every craftable blueprint's per-roll material recipes, keyed by Frontier symbol and then grade.
  *
  * @remarks
  * Its ids and grade sets are the craftable subset of `BLUEPRINTS` from
@@ -59,7 +59,7 @@ declare const BLUEPRINT_COSTS: Readonly<Record<string, BlueprintGradeCosts>>;
 /**
  * Look up all per-grade material recipes for one blueprint.
  *
- * @param fdname - The blueprint id, e.g. `"FSD_LongRange"`, matched
+ * @param blueprintSymbol - The blueprint id, e.g. `"FSD_LongRange"`, matched
  * case-insensitively after trimming surrounding whitespace.
  * @remarks
  * The material half only, straight from the catalogue. The Merc Coin some recipes charge
@@ -68,8 +68,8 @@ declare const BLUEPRINT_COSTS: Readonly<Record<string, BlueprintGradeCosts>>;
  *
  * @returns The frozen grade-to-material-list record, or `null` if no ordinary craft
  * cost is catalogued (including a known fixed reward identity).
- * @throws {TypeError} If `fdname` is present and not a string. A nullish
- * `fdname` is a miss, answered the way an unrecognised one is.
+ * @throws {TypeError} If `blueprintSymbol` is present and not a string. A nullish
+ * `blueprintSymbol` is a miss, answered the way an unrecognised one is.
  * @example
  * ```ts
  * import { getBlueprintCosts } from '@elite-dangerous-almanac/core/ships/blueprint-costs';
@@ -78,7 +78,7 @@ declare const BLUEPRINT_COSTS: Readonly<Record<string, BlueprintGradeCosts>>;
  * // -> [{ symbol: 'Arsenic', name: 'Arsenic', count: 1 }, ...]
  * ```
  */
-declare function getBlueprintCosts(fdname: string): BlueprintGradeCosts | null;
+declare function getBlueprintCosts(blueprintSymbol: string): BlueprintGradeCosts | null;
 /**
  * What one engineering step costs — the materials it consumes and the Merc Coin billed
  * beside them.
@@ -109,15 +109,15 @@ interface BlueprintCost {
 /**
  * Look up what **one roll** at one blueprint grade costs.
  *
- * @param fdname - The blueprint id, e.g. `"FSD_LongRange"`, matched
+ * @param blueprintSymbol - The blueprint id, e.g. `"FSD_LongRange"`, matched
  * case-insensitively after trimming surrounding whitespace.
  * @param grade - The grade, `1`–`5`.
  * @returns The materials one roll consumes and the Merc Coin it bills, or `null` if no
  * ordinary craft cost is catalogued for the blueprint and grade. `materials` is the
  * frozen catalogue list; `mercCoins` is `0` unless the recipe charges a currency.
  * @throws {RangeError} If `grade` is not an integer from 1 through 5.
- * @throws {TypeError} If `fdname` is present and not a string. A nullish
- * `fdname` is a miss, answered the way an unrecognised one is.
+ * @throws {TypeError} If `blueprintSymbol` is present and not a string. A nullish
+ * `blueprintSymbol` is a miss, answered the way an unrecognised one is.
  * @example
  * ```ts
  * import { getBlueprintGradeCost } from '@elite-dangerous-almanac/core/ships/blueprint-costs';
@@ -128,12 +128,15 @@ interface BlueprintCost {
  * getBlueprintGradeCost('RailGun_LongShot', 5)?.mercCoins; // -> 50
  * ```
  */
-declare function getBlueprintGradeCost(fdname: string, grade: number): BlueprintCost | null;
+declare function getBlueprintGradeCost(blueprintSymbol: string, grade: number): BlueprintCost | null;
 /**
  * Compute the **total** cost of engineering a module up to a grade — every grade the
- * module still has to climb, each rolled the number of times it takes to complete
- * ({@link rollsForGrade}: grade `g` needs `g` rolls), summed into one shopping list and
- * one Merc Coin total.
+ * module still has to climb, each rolled the number of times it takes to complete,
+ * summed into one shopping list and one Merc Coin total.
+ *
+ * **Grade `N` takes `N` rolls** to fill its progress bar (grade 1 → 1 roll, grade 2 → 2
+ * rolls, … grade 5 → 5 rolls), and each roll costs that grade's recipe once, so the
+ * climb is weighted rather than a plain sum — for the materials and the Merc Coin alike.
  *
  * By default it prices the whole climb from unengineered; pass `currentGrade` to price
  * only what remains. Each grade `g` in `currentGrade + 1 … grade` contributes
@@ -153,7 +156,7 @@ declare function getBlueprintGradeCost(fdname: string, grade: number): Blueprint
  * same at every grade. Either spelling therefore prices correctly without a fitted
  * module; cross-catalogue tests pin that invariant.
  *
- * @param fdname - The blueprint id, e.g. `"FSD_LongRange"`, matched
+ * @param blueprintSymbol - The blueprint id, e.g. `"FSD_LongRange"`, matched
  * case-insensitively after trimming surrounding whitespace.
  * @param grade - The target grade, `1`–`5`.
  * @param currentGrade - The completed grade, `0`–`5`; defaults to `0` for an
@@ -166,8 +169,8 @@ declare function getBlueprintGradeCost(fdname: string, grade: number): Blueprint
  * charges no currency, so `null` remains the one answer meaning "not catalogued".
  * @throws {RangeError} If `grade` is not an integer from 1 through 5, or `currentGrade`
  * is not an integer from 0 through 5.
- * @throws {TypeError} If `fdname` is present and not a string. A nullish
- * `fdname` is a miss, answered the way an unrecognised one is.
+ * @throws {TypeError} If `blueprintSymbol` is present and not a string. A nullish
+ * `blueprintSymbol` is a miss, answered the way an unrecognised one is.
  * @example
  * ```ts
  * import { getBlueprintCost } from '@elite-dangerous-almanac/core/ships/blueprint-costs';
@@ -181,7 +184,7 @@ declare function getBlueprintGradeCost(fdname: string, grade: number): Blueprint
  * getBlueprintCost('FuelScoop_Efficiency', 5)?.mercCoins; // -> 350
  * ```
  */
-declare function getBlueprintCost(fdname: string, grade: number, currentGrade?: number): BlueprintCost | null;
+declare function getBlueprintCost(blueprintSymbol: string, grade: number, currentGrade?: number): BlueprintCost | null;
 /**
  * Merc Coin charged for **one roll** of a blueprint, keyed by grade (`"1"`–`"5"`).
  *
@@ -195,7 +198,7 @@ declare function getBlueprintCost(fdname: string, grade: number, currentGrade?:
 type BlueprintMercCoinCosts = Readonly<Record<string, number>>;
 /**
  * The Merc Coin charged per roll by every blueprint that charges any, keyed by Frontier
- * `fdname` and then grade.
+ * symbol and then grade.
  *
  * @remarks
  * The raw catalogue behind {@link BlueprintCost.mercCoins}; reach for

package/dist/ships/blueprint-costs.js

@@ -1 +1 @@
-export{BLUEPRINT_COSTS,BLUEPRINT_MERC_COIN_COSTS,getBlueprintCost,getBlueprintCosts,getBlueprintGradeCost}from"../chunk-TEOJCBSG.js";                                                                                                                    //# sourceMappingURL=blueprint-costs.js.map
+export{BLUEPRINT_COSTS,BLUEPRINT_MERC_COIN_COSTS,getBlueprintCost,getBlueprintCosts,getBlueprintGradeCost}from"../chunk-MTJ4MS7W.js";                                                                                                                    //# sourceMappingURL=blueprint-costs.js.map

package/dist/ships/blueprint-journal.d.ts

@@ -39,17 +39,18 @@
  * unaffected — both spellings of a pair bill the same at every grade, so
  * `getBlueprintCost` needs no module.
  *
- * @param symbol - A module symbol, e.g. `"Hpt_CloudScanner_Size0_Class5"`.
- * @param fdname - A blueprint catalogue or journal id, matched case-insensitively and
- * trimmed. Colliding journal spellings are resolved against `symbol`.
+ * @param moduleSymbol - A module symbol, e.g. `"Hpt_CloudScanner_Size0_Class5"`.
+ * @param blueprintSymbol - A blueprint catalogue or journal id, matched case-insensitively and
+ * trimmed. Colliding journal spellings are resolved against `moduleSymbol`.
  * @returns The id to join to `BLUEPRINTS`, in that catalogue's spelling when a journal
- * name resolved, and otherwise `fdname` exactly as it was passed — byte for byte, so a
+ * name resolved, and otherwise `blueprintSymbol` exactly as it was passed — byte for byte, so a
  * caller who never meets the collision never sees their own spelling rewritten.
  *
- * @throws {TypeError} If `fdname` is not a string, including when it is missing — this
+ * @throws {TypeError} If `blueprintSymbol` is not a string, including when it is missing — this
  * returns an id rather than reporting whether one is known, so there is no miss for a
- * nullish one to be. A nullish `symbol` *is* a miss: an unknown module offers no menu,
- * and `fdname` comes back unchanged.
+ * nullish one to be. A nullish `moduleSymbol` *is* a miss: an unknown module offers no
+ * menu,
+ * and `blueprintSymbol` comes back unchanged.
  * @example
  * ```ts
  * import { resolveBlueprintForModule } from '@elite-dangerous-almanac/core/ships/blueprint-journal';
@@ -69,6 +70,6 @@
  * // -> 'Weapon_Overcharged'
  * ```
  */
-declare function resolveBlueprintForModule(symbol: string, fdname: string): string;
+declare function resolveBlueprintForModule(moduleSymbol: string, blueprintSymbol: string): string;
 
 export { resolveBlueprintForModule };

package/dist/ships/blueprint-journal.js

@@ -1 +1 @@
-export{resolveBlueprintForModule}from"../chunk-2TW4ZBI3.js";                                                                                                                    //# sourceMappingURL=blueprint-journal.js.map
+export{resolveBlueprintForModule}from"../chunk-OLKNYGGT.js";                                                                                                                    //# sourceMappingURL=blueprint-journal.js.map