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

package/dist/astro/procedural-system.d.ts

@@ -0,0 +1,228 @@
+import { SystemNameParts } from './system-name.js';
+import { G as GalacticPosition } from '../galactic-position-shLkm4Qg.js';
+import { SystemAddressInput } from './system-address-input.js';
+
+/**
+ * {@link ProceduralSystem} — an immutable handle on a procedurally named Elite
+ * Dangerous system.
+ *
+ * This is a thin value object over the pure functions in this folder. Construct
+ * one from a name or a system address; read its canonical name, naming region, mass
+ * code, position and addresses back. Consumers who only need one calculation
+ * can import the underlying function directly and skip the class entirely — the
+ * algorithms do not live here, only the glue that composes them (including the
+ * hand-authored-sector override, which needs the sector, region-origin and
+ * HA-sphere lookups together).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * An Elite Dangerous star system, identified by its procedural name and/or
+ * system address. Hand-named systems such as Sol are deliberately outside this type.
+ *
+ * Instances are immutable. The normal system address is validated and computed by the
+ * factory, so reading a successfully constructed system never throws; the modulated
+ * form is `null` when its narrower sequence field cannot represent the system.
+ *
+ * @remarks
+ * **Failure model** — factory failures are deliberately
+ * split by cause:
+ * - {@link ProceduralSystem.fromName} returns `null` for a string that is not a
+ *   well-formed system name (a parsing outcome, not an error).
+ * - {@link ProceduralSystem.fromSystemAddress} / {@link ProceduralSystem.fromModSystemAddress}
+ *   throw `RangeError` for an `id64` outside the unsigned 64-bit range or one
+ *   whose sector-grid slot has no assigned procedural name.
+ * - {@link ProceduralSystem.fromModSystemAddress} also throws `RangeError` when the
+ *   modulated layout's sequence cannot fit the normal layout. Every constructed
+ *   instance guarantees a normal {@link ProceduralSystem.systemAddress}.
+ * - {@link ProceduralSystem.fromName} throws `RangeError` immediately when a
+ *   syntactically valid name cannot be encoded (unknown naming region, or an address
+ *   field out of range).
+ * - {@link ProceduralSystem.fromName} throws `TypeError` when `name` is not a string at
+ *   all, a missing one included — that is a caller bug, not a name the scheme does not
+ *   cover, so it is not reported as `null`.
+ *
+ * For the galactic codex region of a system, pass its address to the standalone
+ * `findCodexRegionForBoxel` (from `./codex-region-lookup`) — kept off this facade so
+ * `ProceduralSystem` does not bundle the region grid.
+ *
+ * @example
+ * ```ts
+ * import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';
+ *
+ * declare const id64: bigint;
+ * declare const x: number;
+ * declare const y: number;
+ * declare const z: number;
+ *
+ * // Name -> id64
+ * const sys = ProceduralSystem.fromName('Synuefe EN-H d11-96');
+ * if (sys) sys.systemAddress; // bigint
+ *
+ * // id64 -> name (pass coords so hand-authored regions render correctly)
+ * ProceduralSystem.fromSystemAddress(id64, { x, y, z }).name;
+ * ```
+ */
+declare class ProceduralSystem {
+    #private;
+    /** Whether the name uses a hand-authored region instead of a procedural sector. */
+    readonly usesHandAuthoredRegion: boolean;
+    /**
+     * Whether the system's **region** sits behind a permit lock (Col 70, Bleia,
+     * the Cone Sector, …).
+     *
+     * @remarks
+     * This is a region-level flag only. Individually permit-locked systems — Sol,
+     * Shinrarta Dezhra, Achenar and 51 others — are not procedurally named, so they
+     * never reach a `ProceduralSystem`; check those with `permitLockForSystemName` from
+     * `./permit-locks`, which covers both kinds of lock from a name alone.
+     */
+    readonly requiresRegionPermit: boolean;
+    private constructor();
+    /**
+     * Build a system from a procedural name.
+     *
+     * Procedural and catalogued hand-authored region names are re-cased canonically.
+     * Unknown naming regions and out-of-range address fields are rejected here rather
+     * than creating an object whose address getter fails later.
+     *
+     * @param name - A system name in any casing, e.g. `blae eock kc-c d0`.
+     * @returns The system, or `null` when `name` is not a **procedurally named**
+     * system. Hand-named systems (`Sol`, `Maia`, `Shinrarta Dezhra`) have no
+     * algorithmic address and so yield `null` too — that is a "not covered by the
+     * scheme" answer, not "your string was malformed".
+     * @throws {TypeError} If `name` is not a string. A missing or wrong-typed argument
+     * is a caller bug, not a name the scheme does not cover, so it is not reported as
+     * `null`.
+     * @throws {RangeError} If a syntactically valid name has no known naming-region
+     * origin, or a name field cannot fit the normal system-address layout.
+     * @example
+     * ```ts
+     * import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';
+     *
+     * ProceduralSystem.fromName('blae eock kc-c d0')?.name; // -> 'Blae Eock KC-C d0'
+     * ProceduralSystem.fromName('Sol');                     // -> null (hand-named system)
+     * ```
+     */
+    static fromName(name: string): ProceduralSystem | null;
+    /**
+     * Build a system from its 64-bit system address.
+     *
+     * When `position` is supplied and the system sits inside a hand-authored
+     * region, the name is overridden with the hand-authored one (as the game
+     * displays it). Without `position`, the procedural name is used.
+     *
+     * @remarks
+     * **Pass `position` if you can.** An `id64` alone encodes only the boxel, not the
+     * exact position, so it cannot tell whether the system falls inside a
+     * hand-authored region (Pleiades, Coalsack, …). Without `position`, such a system
+     * silently renders under its *procedural* name instead of the name the game
+     * shows. Coordinates come from an external source you already have the `id64`
+     * from — the player journal, EDSM or Spansh — in light-years with Sol at origin.
+     *
+     * @param id64 - The system address, as a `bigint`, a normally parsed journal
+     *   `number` (`event.SystemAddress`), or a decimal `string` (see
+     *   {@link SystemAddressInput}).
+     * @param position - Galactic position (light-years, Sol at origin). Optional, but
+     *   required for correct hand-authored-region names.
+     * @returns The system at that address.
+     * @throws {TypeError} If the address is not a usable representation — a
+     * non-integer, or a `number` beyond `2^53 - 1` that has already been rounded.
+     * @throws {RangeError} If the address is outside 64 bits or its grid slot has no
+     * assigned procedural name.
+     * @example
+     * ```ts
+     * import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';
+     *
+     * ProceduralSystem.fromSystemAddress(3309179996515n).name;
+     * // -> 'Synuefe EN-H d11-96'
+     * ```
+     */
+    static fromSystemAddress(id64: SystemAddressInput, position?: GalacticPosition): ProceduralSystem;
+    /**
+     * Build a system from its 64-bit modulated system address.
+     *
+     * @param id64 - The modulated system address, as a `bigint`, a safe-integer
+     *   `number`, or a decimal `string` (see {@link SystemAddressInput}). Modulated
+     *   addresses routinely exceed `2^53`; those values must be supplied as a
+     *   `bigint` or string because a JS `number` has already lost precision.
+     * @param position - Galactic position (light-years, Sol at origin). Optional,
+     *   but required for correct hand-authored-region names.
+     * @returns The system at that address.
+     * @throws {TypeError} If the address is not a usable representation.
+     * @throws {RangeError} If the address is outside 64 bits or its grid slot has no
+     * assigned procedural name, or if its sequence cannot fit the normal address
+     * layout that every `ProceduralSystem` exposes.
+     * @example
+     * ```ts
+     * import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';
+     *
+     * declare const modulatedAddress: bigint;
+     *
+     * const normal = ProceduralSystem.fromModSystemAddress(modulatedAddress);
+     * normal.systemAddress; // normal-layout id64
+     * ```
+     */
+    static fromModSystemAddress(id64: SystemAddressInput, position?: GalacticPosition): ProceduralSystem;
+    /** The canonical system name, e.g. `Synuefe EN-H d11-96`. */
+    get name(): string;
+    /**
+     * The region (sector) name — a procedural sector (`Synuefe`) or, when the
+     * system is inside a hand-authored region, that region's name
+     * (`Pleiades Sector`). See {@link ProceduralSystem.usesHandAuthoredRegion} to tell which.
+     */
+    get namingRegionName(): string;
+    /** The mass-code letter `a`–`h`. */
+    get massCode(): string;
+    /** The system's sequence number (`N2`). */
+    get sequence(): number;
+    /**
+     * Galactic position (light-years, Sol at origin), if known.
+     *
+     * @remarks
+     * Only ever the position **you supplied** to
+     * {@link ProceduralSystem.fromSystemAddress} or
+     * {@link ProceduralSystem.fromModSystemAddress} — a name or an `id64` does not carry
+     * an exact position, so this is `null` for a system built from either alone. For an
+     * approximate position from an address, use `findCodexRegionForBoxel(id64)` from
+     * `./codex-region-lookup`, which returns the boxel corner in light-years.
+     * @returns A copy of the position, or `null` when none is known (`null`, not
+     * `undefined` — every "absent" result in this library is `null`).
+     */
+    get position(): GalacticPosition | null;
+    /**
+     * A shallow copy of the parsed name parts.
+     *
+     * @remarks
+     * Letters and mass code are **zero-based numeric indices**, not characters — the
+     * form the address encoder consumes (see {@link SystemNameParts}). Use
+     * {@link ProceduralSystem.name} / {@link ProceduralSystem.massCode} for the display strings.
+     *
+     * @example
+     * ```ts
+     * import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';
+     *
+     * ProceduralSystem.fromName('Synuefe EN-H d11-96')!.parts;
+     * // { regionName: 'Synuefe', l1: 4, l2: 13, l3: 7, massCode: 3, n1: 11, n2: 96 }
+     * ```
+     */
+    get parts(): SystemNameParts;
+    /**
+     * The validated 64-bit system address.
+     *
+     * @remarks
+     * Construction validates the naming region and every normal-address field, so this
+     * getter has no deferred failure mode.
+     */
+    get systemAddress(): bigint;
+    /**
+     * The 64-bit modulated system address, computed from the region origin, or `null`
+     * when the system sequence cannot fit the modulated layout.
+     *
+     * A `null` result is explicit and has no deferred failure mode.
+     */
+    get modSystemAddress(): bigint | null;
+}
+
+export { ProceduralSystem, SystemAddressInput };

package/dist/astro/procedural-system.js

@@ -0,0 +1 @@
+export{ProceduralSystem}from"../chunk-VXVUEF5U.js";                                                                                                                                                                                                                                                                                                                               //# sourceMappingURL=procedural-system.js.map

package/dist/astro/procedural-system.js.map

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

package/dist/astro/sector-name.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Procedural (boxel) sector naming for the Elite Dangerous galaxy.
+ *
+ * Most of the galaxy is not hand-named. Instead the game derives a sector's name
+ * algorithmically from its integer position on the 128×128×128 grid of 1280 ly
+ * sector cubes. Two schemes exist, chosen per sector by a hash of its position:
+ *
+ * - **Class 1 (C1)** — a single run-together word, e.g. `Synuefe`, `Pyroifoo`.
+ *   Built as `prefix + infix(+ infix) + suffix`.
+ * - **Class 2 (C2)** — two words, e.g. `Blae Eock`, `Hypheasms Ni`.
+ *   Built as `prefix₁suffix₁ prefix₂suffix₂`.
+ *
+ * This module implements the forward map ({@link sectorNameFromGridPosition}) and its
+ * inverse ({@link sectorGridPositionFromName}) as pure functions. The fragment tables
+ * and the run-length/offset lookups derived from them are computed once as module
+ * constants; nothing here mutates observable state between calls.
+ *
+ * Ported and restructured from the EDTS reference algorithm (`edtslib/pgdata.py`), via
+ * the canonn-signals TypeScript port. Credit and licence terms, including the BSD
+ * 3-Clause text EDTS requires be reproduced, are in [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Integer position of a sector on the galaxy's sector grid.
+ *
+ * Each axis indexes a 1280 ly cube. `x` and `z` span the full 7-bit range
+ * (0–127); `y` only reaches 0–63 for real systems (the system-address format has
+ * a 6-bit y field), but the naming algorithm itself treats all three as 7-bit.
+ *
+ * @example
+ * ```ts
+ * import type { SectorGridPosition } from '@elite-dangerous-almanac/core/astro/sector-name';
+ *
+ * const sector: SectorGridPosition = { sectorX: 39, sectorY: 31, sectorZ: 18 };
+ * ```
+ */
+interface SectorGridPosition {
+    /** Sector index along the galactic X axis (0–127). */
+    readonly sectorX: number;
+    /** Sector index along the galactic Y axis (0–63 for addressable systems). */
+    readonly sectorY: number;
+    /** Sector index along the galactic Z axis (0–127). */
+    readonly sectorZ: number;
+}
+/**
+ * The procedural sector name for a grid position.
+ *
+ * @param position - Integer sector position on the galaxy grid. Each axis must be
+ *   an integer in 0–127 (the 7-bit sector grid); the packed offset would
+ *   otherwise bleed one axis into the next and produce a wrong or empty name.
+ * @returns The canonically-cased sector name (e.g. `Synuefe`, `Blae Eock`).
+ * @throws {RangeError} If any axis is not an integer in 0–127, or if the grid
+ * slot is outside the procedural generator's assigned name range.
+ * @example
+ * ```ts
+ * import { sectorNameFromGridPosition } from '@elite-dangerous-almanac/core/astro/sector-name';
+ *
+ * sectorNameFromGridPosition({ sectorX: 39, sectorY: 30, sectorZ: 20 }); // -> a procedural name
+ * ```
+ */
+declare function sectorNameFromGridPosition(position: SectorGridPosition): string;
+/**
+ * The grid position a procedural sector name maps to, or `null` if the name is
+ * not a valid procedural sector name.
+ *
+ * Every assigned name produced by {@link sectorNameFromGridPosition} round-trips through
+ * this function. A valid fragment sequence that is not the canonical name emitted for
+ * its coordinates is rejected.
+ *
+ * @param name - A procedural sector name in any casing (e.g. `blae eock`).
+ * @returns The sector grid position, or `null` when the name is not procedural —
+ * including a nullish `name`, which the name parsers tolerate on this path too.
+ * @throws {TypeError} If `name` is present and not a string.
+ */
+declare function sectorGridPositionFromName(name: string): SectorGridPosition | null;
+/**
+ * Re-derive a sector name's canonical casing by round-tripping it through the
+ * grid, e.g. `blae eock` → `Blae Eock`. Returns `null` for non-procedural names.
+ *
+ * @param name - A procedural sector name in any casing. A nullish one answers `null`,
+ * matching {@link sectorGridPositionFromName}.
+ * @throws {TypeError} If `name` is present and not a string.
+ */
+declare function canonicalizeSectorName(name: string): string | null;
+
+export { type SectorGridPosition, canonicalizeSectorName, sectorGridPositionFromName, sectorNameFromGridPosition };

package/dist/astro/sector-name.js

@@ -0,0 +1 @@
+export{canonicalizeSectorName,sectorGridPositionFromName,sectorNameFromGridPosition}from"../chunk-J2PNZQY4.js";                                                          //# sourceMappingURL=sector-name.js.map

package/dist/astro/sector-name.js.map

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

package/dist/astro/system-address-input.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Accepting a system address (`id64`) from wherever the caller got it.
+ *
+ * The library works in `bigint` internally, because address fields reach bit 55
+ * and JS number bitwise operators truncate to 32 bits. Callers, however, rarely
+ * hold a `bigint`: `JSON.parse` of a journal event yields a `number`, persisted
+ * JSON and query strings yield a decimal `string`. Every public entry point that
+ * takes an address therefore accepts {@link SystemAddressInput} and funnels it
+ * through {@link toSystemAddress}.
+ *
+ * This module depends only on the shared argument-guard helper, so importing it (or any
+ * of the address entry points that use it) costs nothing but conversion and bounded
+ * error reporting. That helper carries no catalogue and no data of its own.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A system address as a caller is likely to hold it.
+ *
+ * - `bigint` — the canonical form, and what this library returns.
+ * - `number` — a normally parsed journal event (`event.SystemAddress`). Accepted
+ *   only when it is a non-negative safe integer, since a rounded address would
+ *   silently identify the wrong system.
+ * - `string` — a decimal address from persisted JSON, a URL or a database column.
+ */
+type SystemAddressInput = bigint | number | string;
+/**
+ * Convert a supported address representation to a `bigint`, without accepting a
+ * value that may already have lost precision.
+ *
+ * @param address - A `bigint`, a non-negative safe-integer `number` (a normally
+ * parsed journal address), or a decimal digit `string`.
+ * @returns The address as a `bigint`, or `null` when the input cannot be *converted*
+ * to one: a non-integer or unsafe `number` (beyond `2^53 - 1`, where the value has
+ * already been rounded), a negative `number`, or a string that is not all decimal
+ * digits. A `bigint` always passes through unchanged — whether it fits the 64-bit
+ * address layout is the decoder's `RangeError` to raise, not a conversion failure.
+ * @example
+ * ```ts
+ * import { tryToSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address-input';
+ *
+ * tryToSystemAddress(10477373803);   // -> 10477373803n
+ * tryToSystemAddress('10477373803'); // -> 10477373803n
+ * tryToSystemAddress(1.5);           // -> null
+ * ```
+ */
+declare function tryToSystemAddress(address: SystemAddressInput): bigint | null;
+/**
+ * Convert a supported address representation to a `bigint`, or throw.
+ *
+ * Use this at the edge of your own code when you want the failure to be loud;
+ * the library's address entry points call it for you, so
+ * `decodeSystemAddress(event.SystemAddress)` and
+ * `ProceduralSystem.fromSystemAddress(event.SystemAddress)` accept a journal number
+ * directly.
+ *
+ * @param address - A `bigint`, a non-negative safe-integer `number` (a normally
+ * parsed journal address), or a decimal digit `string`.
+ * @returns The address as a `bigint`.
+ * @throws {TypeError} If the value cannot be converted: a non-integer, a negative
+ * `number`, a `number` beyond `2^53 - 1` (already rounded, so the identity is lost),
+ * or a non-numeric string. The message names the offending value. A `bigint` outside
+ * the 64-bit range is *not* a conversion failure — the decoder rejects it with a
+ * `RangeError`.
+ * @example
+ * ```ts
+ * import { toSystemAddress } from '@elite-dangerous-almanac/core/astro/system-address-input';
+ * declare const event: { SystemAddress: number }; // an `FSDJump` line, parsed
+ *
+ * toSystemAddress(event.SystemAddress); // journal number -> bigint
+ * toSystemAddress('3309179996515');     // -> 3309179996515n
+ * ```
+ */
+declare function toSystemAddress(address: SystemAddressInput): bigint;
+
+export { type SystemAddressInput, toSystemAddress, tryToSystemAddress };

package/dist/astro/system-address-input.js

@@ -0,0 +1 @@
+export{toSystemAddress,tryToSystemAddress}from"../chunk-IH4NXKVW.js";                             //# sourceMappingURL=system-address-input.js.map

package/dist/astro/system-address-input.js.map

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

package/dist/astro/system-address.d.ts

@@ -0,0 +1,4 @@
+import './system-name.js';
+export { A as AbsoluteBoxel, D as DecodedAddress, S as SECTOR_INTERNAL_SIZE, a as absoluteBoxelToBoxelCode, b as boxelCodeToAbsoluteBoxel, c as boxelInternalSize, d as decodeModSystemAddress, e as decodeSystemAddress, f as encodeModSystemAddress, g as encodeSystemAddress } from '../system-address-DYsN1qOT.js';
+import './sector-name.js';
+export { SystemAddressInput } from './system-address-input.js';

package/dist/astro/system-address.js

@@ -0,0 +1 @@
+export{SECTOR_INTERNAL_SIZE,absoluteBoxelToBoxelCode,boxelCodeToAbsoluteBoxel,boxelInternalSize,decodeModSystemAddress,decodeSystemAddress,encodeModSystemAddress,encodeSystemAddress}from"../chunk-BTPV5CIF.js";                                                          //# sourceMappingURL=system-address.js.map

package/dist/astro/system-address.js.map

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

package/dist/astro/system-name.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Parsing and formatting of Elite Dangerous procedural system names.
+ *
+ * A procedural system name has the shape `Region LL-L m[N1-]N2`, e.g.
+ * `Synuefe EN-H d11-96` or `Blae Eock KC-C d0`. Its parts are:
+ *
+ * - **Region** — the sector name (procedural, e.g. `Synuefe`, or hand-authored,
+ *   e.g. `Pleiades Sector`).
+ * - **L1 L2 L3** — three letters (`EN-H`) giving the boxel's position within the
+ *   sector, together with **N1**.
+ * - **Mass code** — the size class `a`–`h`.
+ * - **N1 / N2** — the boxel's high index and the system's sequence number. When
+ *   N1 is zero the game omits it (and its hyphen), so `…d0`, not `…d0-0`.
+ *
+ * This module only handles the *textual* form. The bit-packed `id64`
+ * (system address) lives in `./system-address`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The parsed parts of a procedural system name. Letters and mass code are stored
+ * as zero-based indices, not characters, so they can feed the address encoder
+ * directly.
+ */
+interface SystemNameParts {
+    /** The region (sector) name, as written — casing is fixed up on canonicalize. */
+    readonly regionName: string;
+    /** First boxel letter, 0–25 (`A`–`Z`). */
+    readonly l1: number;
+    /** Second boxel letter, 0–25. */
+    readonly l2: number;
+    /** Third boxel letter, 0–25. */
+    readonly l3: number;
+    /** Mass code as a 0–7 size class (`a`–`h`). */
+    readonly massCode: number;
+    /** High boxel index (the `N1` before the hyphen); 0 when the name omits it. */
+    readonly n1: number;
+    /** System sequence number (`N2`). */
+    readonly n2: number;
+}
+/**
+ * Pack a boxel's `(l1, l2, l3, n1)` letter code into the single base-26 index the
+ * address format uses (the **boxel code**).
+ *
+ * @param l1 - First letter as a zero-based index, `0`–`25` (`A`–`Z`).
+ * @param l2 - Second letter as a zero-based index, `0`–`25`.
+ * @param l3 - Third letter as a zero-based index, `0`–`25`.
+ * @param n1 - The boxel number that follows the letters (`d11-96` → `11`), a
+ *   non-negative integer small enough that the packed code stays exact.
+ * @returns The packed base-26 boxel code.
+ * @throws {RangeError} If any letter is not an integer in 0–25, or `n1` is not an
+ * integer between 0 and the largest value that still packs exactly. Such a field packs
+ * as a different boxel than the one asked for rather than failing.
+ * @example
+ * ```ts
+ * import { lettersToBoxelCode } from '@elite-dangerous-almanac/core/astro/system-name';
+ *
+ * lettersToBoxelCode(4, 13, 7, 11); // the 'EN-H …11' boxel of a d-class sector
+ * ```
+ */
+declare function lettersToBoxelCode(l1: number, l2: number, l3: number, n1: number): number;
+/**
+ * A boxel's letter code unpacked — the `EN-H …11` half of a procedural name.
+ *
+ * @remarks
+ * The same four fields {@link SystemNameParts} carries, without the region name, mass
+ * code and sequence that complete a name.
+ *
+ * @example
+ * ```ts
+ * import { boxelCodeToLetters } from '@elite-dangerous-almanac/core/astro/system-name';
+ * import type { BoxelLetters } from '@elite-dangerous-almanac/core/astro/system-name';
+ *
+ * const code: BoxelLetters = boxelCodeToLetters(198_410);
+ * // -> { l1: 4, l2: 13, l3: 7, n1: 11 }, the 'EN-H …11' boxel
+ * ```
+ */
+interface BoxelLetters {
+    /** First letter as a zero-based index, `0`–`25`. */
+    readonly l1: number;
+    /** Second letter as a zero-based index, `0`–`25`. */
+    readonly l2: number;
+    /** Third letter as a zero-based index, `0`–`25`. */
+    readonly l3: number;
+    /** The boxel number that follows the letters (`d11-96` → `11`). */
+    readonly n1: number;
+}
+/**
+ * Unpack a base-26 boxel code into its `(l1, l2, l3, n1)` letter code — the inverse
+ * of {@link lettersToBoxelCode}.
+ *
+ * @param boxelCode - The packed base-26 boxel code, as `decodeSystemAddress` returns.
+ *   Must be a non-negative integer {@link lettersToBoxelCode} could have packed.
+ * @returns The three letter indices (`0`–`25` each) and the boxel number `n1`.
+ * @throws {RangeError} If `boxelCode` is not an integer between 0 and the largest
+ * exactly packable code — no such code can be packed, and a negative one would yield
+ * letters outside `0`–`25`.
+ * @example
+ * ```ts
+ * import { boxelCodeToLetters, lettersToBoxelCode } from '@elite-dangerous-almanac/core/astro/system-name';
+ *
+ * boxelCodeToLetters(lettersToBoxelCode(4, 13, 7, 11)); // -> { l1: 4, l2: 13, l3: 7, n1: 11 }
+ * ```
+ */
+declare function boxelCodeToLetters(boxelCode: number): BoxelLetters;
+/**
+ * Parse a procedural system name into its parts.
+ *
+ * The region name may itself contain digits (`Col 285 Sector`), so parsing walks
+ * the suffix backwards from the end. Returns `null` for anything that is not a
+ * well-formed procedural system name.
+ *
+ * @remarks
+ * Parsing does **not** canonicalize casing: `regionName` is captured verbatim from
+ * the input (`parseSystemName('synuefe …').regionName === 'synuefe'`). The letters
+ * and mass code become numeric indices, so re-formatting them is always canonical,
+ * but the region is not — use {@link canonicalizeSystemName} (or build a
+ * {@link ProceduralSystem} via `ProceduralSystem.fromName`) if you need the region re-cased too.
+ *
+ * @param name - A system name in any casing, e.g. `blae eock kc-c d0`.
+ * @returns The parsed parts, or `null` if the name is malformed. A nullish `name`
+ * answers `null` too: this parser tolerates an absent name, deliberately, so a caller
+ * can hand it a field that may not be there. `ProceduralSystem.fromName` is the stricter
+ * factory over the same grammar — it throws `TypeError` for anything but a string.
+ * @throws {TypeError} If `name` is present and not a string. Tolerating an absent name is
+ * not tolerating any value at all: a number where a name belongs is a caller bug, and it
+ * is named rather than left to fail on a method it does not have.
+ */
+declare function parseSystemName(name: string): SystemNameParts | null;
+/**
+ * Format parts back into a system name. N1 (and its hyphen) is omitted when zero,
+ * matching the in-game rendering.
+ *
+ * @remarks
+ * Letters and mass code are rendered from their numeric indices, so they always
+ * come out canonically cased. The `regionName`, however, is emitted **as stored** —
+ * `formatSystemName` does not re-case it. Round-tripping a lower-cased name through
+ * {@link parseSystemName} → `formatSystemName` therefore keeps the region's original
+ * casing (`synuefe EN-H d11-96`); for a fully canonical name use
+ * {@link canonicalizeSystemName} or `ProceduralSystem.fromName(...).name`.
+ *
+ * @param parts - The system-name parts to render.
+ * @returns The system name, e.g. `Synuefe EN-H d11-96`.
+ */
+declare function formatSystemName(parts: SystemNameParts): string;
+/**
+ * Fix the casing of a system name. Procedural regions are round-tripped through
+ * the grid; catalogued hand-authored regions are looked up case-insensitively.
+ * Unknown region strings are left untouched so syntactic parsing remains separate
+ * from address encodability.
+ *
+ * @param name - A system name in any casing.
+ * @returns The canonically-cased name, or `null` if it is not a system name — including
+ * a nullish `name`, which {@link parseSystemName} tolerates on this path too.
+ * @throws {TypeError} If `name` is present and not a string.
+ */
+declare function canonicalizeSystemName(name: string): string | null;
+/** Options for {@link isProceduralSystemName}. */
+interface IsProceduralSystemNameOptions {
+    /**
+     * When `true`, also require the region to parse as a procedural sector, so
+     * hand-authored region names (e.g. `Pleiades Sector HR-W d1-79`) are rejected.
+     * Defaults to `false`.
+     */
+    readonly strict?: boolean;
+}
+/**
+ * Whether a string is a well-formed procedural system name.
+ *
+ * @param name - The candidate name.
+ * @param options - See {@link IsProceduralSystemNameOptions}.
+ * @returns `true` when the name parses as a procedural system name. A hand-named
+ * system (`Sol`, `Maia`) is `false`: it is a real system, just not a procedural name. A
+ * nullish `name` is `false` as well, matching {@link parseSystemName}'s tolerance.
+ * @throws {TypeError} If `name` is present and not a string.
+ * @example
+ * ```ts
+ * import { isProceduralSystemName } from '@elite-dangerous-almanac/core/astro/system-name';
+ *
+ * isProceduralSystemName('Blae Eock KC-C d0');                    // -> true
+ * isProceduralSystemName('Pleiades Sector HR-W d1-79');           // -> true
+ * isProceduralSystemName('Pleiades Sector HR-W d1-79', { strict: true }); // -> false
+ * ```
+ */
+declare function isProceduralSystemName(name: string, options?: IsProceduralSystemNameOptions): boolean;
+
+export { type BoxelLetters, type IsProceduralSystemNameOptions, type SystemNameParts, boxelCodeToLetters, canonicalizeSystemName, formatSystemName, isProceduralSystemName, lettersToBoxelCode, parseSystemName };

package/dist/astro/system-name.js

@@ -0,0 +1 @@
+export{boxelCodeToLetters,canonicalizeSystemName,formatSystemName,isProceduralSystemName,lettersToBoxelCode,parseSystemName}from"../chunk-JWJ7RSZC.js";                                                                                                                                                                                                           //# sourceMappingURL=system-name.js.map

package/dist/astro/system-name.js.map

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

package/dist/chunk-2FHHMYDC.js

@@ -0,0 +1 @@
+import{systemsResistance,mapDamageTypes,effectiveHitPoints,stackShieldResistance}from"./chunk-ZNCXENNB.js";function shieldMassCurveMultiplier(hullMass,generator){const{minMass:minMass,optMass:optMass,maxMass:maxMass,minMultiplier:minMultiplier,optMultiplier:optMultiplier,maxMultiplier:maxMultiplier}=generator;if(minMass===void 0||optMass===void 0||maxMass===void 0||minMultiplier===void 0||optMultiplier===void 0||maxMultiplier===void 0){return 0}if(hullMass>maxMass)return 0;const span=maxMass-minMass;if(span<=0||maxMultiplier===minMultiplier)return optMultiplier;const normalised=Math.max(0,Math.min(1,(maxMass-hullMass)/span));const optNormalised=Math.min(1,(maxMass-optMass)/span);const exponent=Math.log((optMultiplier-minMultiplier)/(maxMultiplier-minMultiplier))/Math.log(optNormalised);if(!Number.isFinite(exponent))return optMultiplier;return minMultiplier+Math.pow(normalised,exponent)*(maxMultiplier-minMultiplier)}function shieldStrength(hullMass,baseShieldStrength,generator,boostMultiplier=1){return baseShieldStrength*shieldMassCurveMultiplier(hullMass,generator)*boostMultiplier}var boosterResistances=(boosters,type)=>boosters.map(booster=>booster[`${type}Resistance`]??0);function shieldMetrics(input){const boosters=input.boosters??[];const reinforcement=input.reinforcement??0;const pips=input.systemsPips??0;const sysResistance=systemsResistance(pips);const generator=input.generator??null;if(!generator){const none=mapDamageTypes(()=>0);return{strength:0,generator:0,boosters:0,reinforcement:0,massCurveMultiplier:0,boostMultiplier:1,resistances:none,effectiveHitPoints:effectiveHitPoints(0,none),systemsResistance:sysResistance}}const massCurveMultiplier=shieldMassCurveMultiplier(input.hullMass,generator);const boostMultiplier=1+boosters.reduce((sum,booster)=>sum+(booster.shieldBoost??0),0);const generatorStrength=input.baseShieldStrength*massCurveMultiplier;const boostersStrength=generatorStrength*(boostMultiplier-1);const strength=generatorStrength+boostersStrength+reinforcement;const withPips=resistance=>1-(1-resistance)*(1-sysResistance);const resistances=mapDamageTypes(type=>withPips(stackShieldResistance(generator[`${type}Resistance`]??0,boosterResistances(boosters,type))));return{strength:strength,generator:generatorStrength,boosters:boostersStrength,reinforcement:reinforcement,massCurveMultiplier:massCurveMultiplier,boostMultiplier:boostMultiplier,resistances:resistances,effectiveHitPoints:effectiveHitPoints(strength,resistances),systemsResistance:sysResistance}}export{shieldMassCurveMultiplier,shieldMetrics,shieldStrength};//# sourceMappingURL=chunk-2FHHMYDC.js.map

package/dist/chunk-2FHHMYDC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ships/shields.ts"],"names":["systemsResistance","mapDamageTypes","effectiveHitPoints","stackShieldResistance","shieldMassCurveMultiplier","hullMass","generator","minMass","optMass","maxMass","minMultiplier","optMultiplier","maxMultiplier","span","normalised","Math","max","min","optNormalised","exponent","log","Number","isFinite","pow","shieldStrength","baseShieldStrength","boostMultiplier","boosterResistances","boosters","type","map","booster","shieldMetrics","input","reinforcement","pips","systemsPips","sysResistance","none","strength","massCurveMultiplier","resistances","reduce","sum","shieldBoost","generatorStrength","boostersStrength","withPips","resistance"],"mappings":"O,oGA0LO,SAASI,0BACZC,SACAC,WAEA,MAAMC,QAAEA,QAAAC,QAASA,QAAAC,QAASA,QAAAC,cAASA,cAAAC,cAAeA,cAAAC,cAAeA,eAAkBN,UACnF,GACIC,eAAY,GACZC,eAAY,GACZC,eAAY,GACZC,qBAAkB,GAClBC,qBAAkB,GAClBC,qBAAkB,EACpB,CAGE,OAAO,CACX,CAEA,GAAIP,SAAWI,QAAS,OAAO,EAC/B,MAAMI,KAAOJ,QAAUF,QACvB,GAAIM,MAAQ,GAAKD,gBAAkBF,cAAe,OAAOC,cACzD,MAAMG,WAAaC,KAAKC,IAAI,EAAGD,KAAKE,IAAI,GAAIR,QAAUJ,UAAYQ,OAClE,MAAMK,cAAgBH,KAAKE,IAAI,GAAIR,QAAUD,SAAWK,MACxD,MAAMM,SACFJ,KAAKK,KAAKT,cAAgBD,gBAAkBE,cAAgBF,gBAC5DK,KAAKK,IAAIF,eACb,IAAKG,OAAOC,SAASH,UAAW,OAAOR,cACvC,OAAOD,cAAgBK,KAAKQ,IAAIT,WAAYK,WAAaP,cAAgBF,cAC7E,CAYO,SAASc,eACZnB,SACAoB,mBACAnB,UACAoB,gBAAkB,GAElB,OAAOD,mBAAqBrB,0BAA0BC,SAAUC,WAAaoB,eACjF,CAGA,IAAMC,mBAAqB,CAACC,SAA0CC,OAClED,SAASE,IAAKC,SAAYA,QAAQ,GAAGF,mBAAqB,GAmCvD,SAASG,cAAcC,OAC1B,MAAML,SAAWK,MAAML,UAAY,GACnC,MAAMM,cAAgBD,MAAMC,eAAiB,EAC7C,MAAMC,KAAOF,MAAMG,aAAe,EAClC,MAAMC,cAAgBrC,kBAAkBmC,MACxC,MAAM7B,UAAY2B,MAAM3B,WAAa,KAErC,IAAKA,UAAW,CACZ,MAAMgC,KAAOrC,eAAe,IAAM,GAClC,MAAO,CACHsC,SAAU,EACVjC,UAAW,EACXsB,SAAU,EACVM,cAAe,EACfM,oBAAqB,EACrBd,gBAAiB,EACjBe,YAAaH,KACbpC,mBAAoBA,mBAAmB,EAAGoC,MAC1CtC,kBAAmBqC,cAE3B,CAEA,MAAMG,oBAAsBpC,0BAA0B6B,MAAM5B,SAAUC,WACtE,MAAMoB,gBACF,EAAIE,SAASc,OAAO,CAACC,IAAKZ,UAAYY,KAAOZ,QAAQa,aAAe,GAAI,GAC5E,MAAMC,kBAAoBZ,MAAMR,mBAAqBe,oBACrD,MAAMM,iBAAmBD,mBAAqBnB,gBAAkB,GAChE,MAAMa,SAAWM,kBAAoBC,iBAAmBZ,cAGxD,MAAMa,SAAYC,YAA+B,GAAK,EAAIA,aAAe,EAAIX,eAC7E,MAAMI,YAAiCxC,eAAgB4B,MACnDkB,SACI5C,sBACIG,UAAU,GAAGuB,mBAAqB,EAClCF,mBAAmBC,SAAUC,SAKzC,MAAO,CACHU,kBACAjC,UAAWuC,kBACXjB,SAAUkB,iBACVZ,4BACAM,wCACAd,gCACAe,wBACAvC,mBAAoBA,mBAAmBqC,SAAUE,aACjDzC,kBAAmBqC,cAE3B,QAAAjC,0BAAA4B,cAAAR"}