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

package/README.md

@@ -0,0 +1,148 @@
+# @elite-dangerous-almanac/core
+
+Tree-shakeable Elite Dangerous static data and calculations for TypeScript and
+JavaScript applications.
+
+## Install
+
+```bash
+npm install @elite-dangerous-almanac/core
+```
+
+The package is ESM-only, supports Node.js 22+ and targets modern browser bundlers.
+It is marked side-effect free.
+
+The package includes game and community data under source-specific terms. Review
+[LICENSE](./LICENSE) and [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) before
+redistribution or commercial use.
+
+## Imports
+
+Use a feature barrel when a bundler will tree-shake it:
+
+```ts
+import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro';
+```
+
+There is no package-wide root entry; choose one of the four feature areas or a leaf.
+
+Use leaf subpaths to avoid evaluating unrelated data modules in native ESM:
+
+```ts
+import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';
+import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+```
+
+The heavyweight module registries, planetary/combined nebula catalogues and codex-region
+coordinate lookup are only exported from their leaf subpaths, not the feature barrels.
+
+The package has four feature areas:
+
+- `astro`: procedural names, id64 addresses, regions, nebulae and permit locks;
+- `ships`: ships, modules, SLEF loadouts, engineering and build metrics;
+- `materials`: ship engineering materials and Odyssey micro resources;
+- `commodities`: standard and rare market goods.
+
+## Examples
+
+```ts
+import { ProceduralSystem } from '@elite-dangerous-almanac/core/astro/procedural-system';
+
+const system = ProceduralSystem.fromName('Synuefe EN-H d11-96');
+system?.systemAddress; // -> 3309179996515n
+ProceduralSystem.fromSystemAddress(3309179996515n).name;
+// -> "Synuefe EN-H d11-96"
+```
+
+Address inputs accept `bigint`, safe integer `number` values and decimal strings.
+Addresses are returned as `bigint`.
+
+```ts
+import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';
+
+declare const slefJsonString: string;
+
+const build = ShipLoadout.fromSlef(slefJsonString);
+build.maxJumpRange();
+build.powerBudget();
+build.shieldMetrics();
+build.armourMetrics();
+build.weaponMetrics();
+
+build.toSlefString({
+    header: { appName: 'MyApp', appVersion: '1.0.0' },
+});
+```
+
+`ShipLoadout` imports every ship and module catalogue so it can resolve any build.
+When only one calculation is required, use the data-free leaf modules under
+`ships/jump-range`, `ships/power`, `ships/shields`, `ships/armour`, `ships/weapons`,
+`ships/ammunition` or `ships/resistances`.
+
+`build.validation` reports validity and operational completeness. Potentially incomplete
+aggregates are nullable and have a diagnostic counterpart (`cargoCapacityResult`,
+`fuelCapacityResult`, `unladenMassResult`). `parseSlef` is strict; `inspectSlef` is the
+tolerant importer for mixed files and returns indexed diagnostics instead of silently
+dropping entries.
+
+```ts
+import { getShipBySymbol } from '@elite-dangerous-almanac/core/ships/ships';
+import { getMaterialByName } from '@elite-dangerous-almanac/core/materials/materials';
+import { getCommodityByName } from '@elite-dangerous-almanac/core/commodities/commodities';
+
+getShipBySymbol('empire_trader')?.name; // -> "Imperial Clipper"
+getMaterialByName('iron')?.grade;
+getCommodityByName('lavian brandy')?.rare; // -> true
+```
+
+Registry lookups ignore case and surrounding whitespace. Material, commodity and
+module lookups search their complete registry by default and accept an optional
+catalogue to narrow the results. Nebula queries require an explicit catalogue so the
+large combined dataset is never an implicit dependency.
+
+`symbol` is Frontier's item id for a hull, module, material, micro-resource or
+commodity. Engineering uses a separate identity space: `fdname` identifies a
+blueprint recipe, experimental effect or decorative modification. The journal
+normally writes that id in its `Engineering` block, but a few blueprint aliases
+collide across module families; `resolveBlueprintForModule` resolves those journal
+spellings. Functions that ask what engineering a module accepts therefore take the
+module's `symbol`; functions that look up a recipe, effect or modification take its
+`fdname`.
+
+## Important behavior
+
+- Exported catalogues are deeply frozen.
+- Slot keys come from the game and are not reliably derivable from position. Enumerate
+  them with `ShipLoadout.slots()` or `enumerateSlots`.
+- Resistances are fractions, not percentages.
+- Build credits are quoted at catalogue retail. What a capture says it paid is kept
+  apart, unedited, as `ShipLoadout.sourcePurchase`, and is exported only when asked for
+  by name with `{ credits: 'source' }`.
+- Absent catalogue fields are omitted rather than represented by zero. Catalogue
+  provenance records unresolved data gaps.
+- Lookups return `null`; malformed inputs throw `TypeError`; unsupported ranges throw
+  `RangeError`.
+- `parseSlef`, `inspectSlef` and `ShipLoadout.fromSlef` throw `SyntaxError` when handed a
+  string that is not valid JSON. Past that, a payload number outside its documented
+  journal range counts as malformed rather than out of range: `parseSlef` and
+  `ShipLoadout.fromSlef` throw `TypeError`, not `RangeError`, and `inspectSlef` reports it
+  as a diagnostic.
+
+The [repository README](https://github.com/DarkSession/Elite-Dangerous-Almanac#readme)
+contains the project guide. The generated
+[GitHub Wiki](https://github.com/DarkSession/Elite-Dangerous-Almanac/wiki) contains the
+complete API reference.
+
+## Data and credits
+
+The package's [provenance record](./PROVENANCE/SNAPSHOTS.md) includes every domain's
+canonical `SOURCES.md` verbatim, recording each catalogue's source, acquisition date,
+immutable revision or checksum, derivation and manual corrections. It travels with the
+installed version, so its pinned data currency can be checked offline. Unknown values
+are omitted rather than guessed.
+
+Third-party credits and licence terms ship with the package in
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+
+The project's code and documentation are MIT-licensed. Bundled game and third-party
+data remains under its source-specific terms and is not relicensed under MIT.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,202 @@
+# Attributions and third-party notices
+
+Elite Dangerous Almanac incorporates community-researched algorithms and factual
+galaxy data. The project's own implementation is MIT-licensed; upstream material
+remains subject to its own terms, several of which are **non-commercial**. Read
+this file and `LICENSE` before redistributing the data or using it commercially.
+
+**This is the one place a source is described.** Each source is described in one of the
+sections below — its author, its link and its licence position — and where an entry names
+a source another section covers, it does so as a cross-reference rather than a second
+description. Nothing else in the repository repeats that: a data file's comment header
+names the source and points here, and each
+`data/<domain>/SOURCES.md` records what was taken from it — the acquisition date, the
+pinned revision, the derivation and every manual correction — referring to it by name
+alone. Test fixtures carry their own provenance in their file header.
+
+This file is shipped to npm consumers inside the package as `THIRD_PARTY_NOTICES.md`,
+a verbatim copy produced at build time — edit this file, never the copy.
+
+## Algorithms
+
+- **Procedural sector and system naming** — reverse-engineered by the Elite Dangerous
+  community and ported from the EDTS reference implementation (`edtslib/pgdata.py`,
+  `edtslib/pgnames.py`) by **Andy Martin** (Esvandiary),
+  <https://bitbucket.org/Esvandiary/edts>, **BSD 3-Clause, © 2016 Andy Martin** —
+  reproduced in full at the end of this file, as its terms require. The TypeScript port
+  passed through canonn-signals (credited under Data below) before being restructured
+  here. (EDTS lives on Bitbucket, not GitHub.)
+- **[EDCD/Coriolis](https://github.com/EDCD/coriolis)** — the Coriolis _application_, by
+  the **Coriolis contributors**, whose code is **MIT**-licensed. (Its data repository is a
+  separate credit, under Data below.) The **build-metric algorithms** are ported as fact
+  (our own implementation) from it: the power budget and its priority groups, shield
+  strength and its mass curve, armour hit points, resistance stacking with its diminishing
+  returns, and weapon DPS / capacitor draw / heat. It credits the original Frontier-forum
+  research the formulas come from.
+- **The jump-range and fuel algorithm**, the **engineered ammunition rounding** rule and
+  the **build metrics above** are cross-checked against, or ported as fact from, EDSY
+  (credited under Data below). The jump-range model derives from Frontier's "mass effect on
+  hyperspace range" description; Coriolis carries the same maths for the metrics, and a clip
+  round-up that omits EDSY's burst step, where EDSY is followed.
+- **Galactic codex region lookup** — resolving a region from galactic coordinates or from a
+  boxel, ported as fact (our own implementation) from `RegionMap.js` in
+  EliteDangerousRegionMap, whose region tables are credited under Data below.
+- **SLEF parsing and writing** — both follow the
+  [Inara Ship Loadout Export Format specification](https://inara.cz/elite/inara-impexp-slef/)
+  published by **Inara** (Artie).
+
+## Data
+
+- **[EDCD FDevIDs](https://github.com/EDCD/FDevIDs)** — the community-maintained registry
+  of Frontier's internal ids and names. Supplies the identities of materials and micro
+  resources, ships and outfitting modules, and standard and rare market commodities.
+  FDevIDs states no explicit licence; consult the repository terms before redistributing
+  the raw identifiers.
+- **[EDCD/coriolis-data](https://github.com/EDCD/coriolis-data)** — ship and module
+  stats, per-hull slot layouts, engineering blueprint modifiers and their material
+  recipes. coriolis-data releases only its _code_ under **MIT**; the JSON stat values are
+  **Elite Dangerous game data, property of Frontier Developments plc** — see the Frontier
+  notice below.
+- **[EDSY](https://github.com/taleden/EDSY)** by **taleden**, **CC BY-NC 4.0** —
+  `eddb.js` and `edsy.js`. Supplies the values coriolis-data leaves blank or carries
+  wrongly (module mass, integrity, power draw, boot time, the base stats engineering
+  recipes scale), the experimental-effect modifiers and their recipes, the module-group
+  engineering menus, the journal slot names, and the attribute-to-journal-Label mapping.
+  The values are Elite Dangerous game data — see the Frontier notice below.
+- **[Inara](https://inara.cz/)** — the blueprint and outfitting registries behind the
+  Operations pre-engineered blueprints and shop rows, the ship pages used to corroborate
+  hull layouts, and the component pages that grade the Thargoid caustic / Titan materials
+  absent from FDevIDs.
+- **[EliteDangerousRegionMap](https://github.com/klightspeed/EliteDangerousRegionMap)** by
+  **Ben Peddell** ([klightspeed](https://github.com/klightspeed)), **MIT** — the 42
+  galactic codex regions, their ids and their lookup geometry. Original region-boundary
+  research on the
+  [Frontier forums](https://forums.frontier.co.uk/threads/determining-the-region-of-a-system.537845/).
+- **[canonn-science/canonn-signals](https://github.com/canonn-science/canonn-signals)** by
+  the **Canonn Research Group**, **MIT**, © 2023 — the route by which two of the sources
+  below were obtained, and the TypeScript port the procedural-naming algorithm passed
+  through.
+- **EDAstro nebulae coordinates** published by **CMDR Orvidius**
+  ([EDAstro](https://edastro.com/mapcharts/)) — nebula names, catalogued systems,
+  coordinates, classes and region ids, obtained via canonn-signals. EDAstro states no
+  explicit licence for the dataset; consult the site's terms before redistributing it.
+- **"Elite Dangerous Permit Database"** — the community-maintained spreadsheet behind the
+  permit-locked systems and regions, obtained via canonn-signals. Permit status is
+  published in no game file or API, so the list is hand-maintained and best-effort.
+- **[EDSM](https://www.edsm.net)** and **[Spansh](https://spansh.co.uk)**, maintained by
+  their respective community contributors — factual system names, coordinates and
+  addresses, used for the hand-authored region spheres, the named-region origins and the
+  permit-locked systems' `id64` values. Consult each service's published terms for use of
+  its API or data.
+- **[Odyssey Materials Helper](https://github.com/jixxed/ed-odyssey-materials-helper)** by
+  **Jixxed**, **MIT** — a CAPI response in its test resources corroborates the six
+  bundle-granted Vessel Hangar variants. The response itself is factual Elite Dangerous
+  game output; only the module identities, bundle flags and grant tokens are used.
+- **[msarilar/EDEngineer](https://github.com/msarilar/EDEngineer)**, **MIT** for its code
+  — its `blueprints.json` corroborates which weapons the Overcharged recipe gives a clip
+  penalty to. The values are game data.
+- **[Elite Dangerous Wiki](https://elite-dangerous.fandom.com/)** (Fandom,
+  **CC BY-SA 3.0**) — how the Corrosion Resistant Cargo Racks are obtained, which is why
+  two of them carry no list price.
+- **Frontier Developments plc** — the game itself, the ship models represented by the
+  shared vector illustrations, and its published statements:
+  the [media-usage rules](https://forums.frontier.co.uk/threads/elite-dangerous-media-usage-rules.510879/)
+  quoted below, the Operations and Lynx
+  [update notes](https://forums.frontier.co.uk/threads/648012/), and the
+  [Rhea Disaster Community Goal](https://forums.frontier.co.uk/threads/deliver-critical-aid-for-the-rhea-disaster.626528/)
+  with its [announcement](https://x.com/EliteDangerous/status/1812792503776489745).
+  Values read directly from the running game are Frontier's too — see the notice below.
+- **A [community description](https://www.reddit.com/r/EliteDangerous/comments/1uk2zhp/plasma_laser_theorycrafting_following_new/)
+  by u/Techno3020** — linked only as corroboration that the Operations Plasma conversion's
+  Plasma share is absolute damage. The post states no redistribution licence; none of its
+  text or media is redistributed.
+
+## Test fixtures
+
+The fixtures in `fixtures/` are not bundled into any published package. Each one carries
+its own provenance in its file header; the projects that published the captures they came
+from are credited here:
+
+- **[adam-drewery/EliteAssist](https://github.com/adam-drewery/EliteAssist)**, **WTFPL** —
+  a Frontier journal `Loadout` event in its example data.
+- **[UFO-Studios/EDDP](https://github.com/UFO-Studios/EDDP)** — a captured journal log the
+  project ships as example data. That repository's own code is under the **UFO Licence
+  1.0**, which permits use with credit but not redistribution of the project; the licence
+  covers UFO Studios' project, not the Frontier journal line quoted from its example data,
+  which travels under Frontier's media-usage terms like every other capture. Credit to UFO
+  Studios & AW2C Systems Ltd for capturing and publishing the log. No code from that
+  project is used.
+- **[Coriolis](https://coriolis.io/)** (`s.orbis.zone`) and **[EDSY](https://edsy.org/)**
+  — the two share-link formats the 181-build community corpus was decoded from, using each
+  tool's own published serialisation and id tables (credited above). No code from either
+  is vendored here.
+- **[Inara](https://inara.cz/)** — SLEF exports produced by its loadout tool.
+
+Every capture is Elite Dangerous game output and remains the property of Frontier
+Developments plc — see the notice below.
+
+## Elite Dangerous game data and imagery (Frontier media-usage notice)
+
+The ship and module stat values and the ship illustrations are the property of
+**Frontier Developments plc** and are used under Frontier's
+[media-usage rules](https://forums.frontier.co.uk/threads/elite-dangerous-media-usage-rules.510879/):
+
+> Elite Dangerous Almanac was created using assets and imagery from Elite
+> Dangerous, with the permission of Frontier Developments plc, for non-commercial
+> purposes. It is not endorsed by nor reflects the views or opinions of Frontier
+> Developments and no employee of Frontier Developments was involved in the making
+> of it.
+
+Projects that redistribute this data should include the same notice.
+
+## Where the provenance lives
+
+This file credits. What was taken from each source, when, from which revision, how it was
+derived and every manual correction are recorded with the data itself, in
+[`data/astro/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/astro/SOURCES.md),
+[`data/materials/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/materials/SOURCES.md),
+[`data/ships/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/ships/SOURCES.md)
+and
+[`data/commodities/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/commodities/SOURCES.md),
+with the rules those files follow in
+[`data/SNAPSHOTS.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/SNAPSHOTS.md).
+Those files live in the repository only — this file is also published inside the npm
+package, where they are not present, so the links are absolute.
+
+If you add or change data, port an algorithm, or add a dependency that warrants credit,
+add it here and record the provenance where the data lives.
+
+---
+
+## EDTS license (procedural naming)
+
+The procedural sector- and system-naming algorithm and its region tables derive
+from EDTS by Andy Martin (<https://bitbucket.org/Esvandiary/edts>), whose full
+license is reproduced here as required by its terms:
+
+```
+Copyright (c) 2016, Andy Martin
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the EDTS Project nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE EDTS PROJECT OR ANDY MARTIN BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```

package/dist/astro/codex-region-lookup.d.ts

@@ -0,0 +1,169 @@
+import { CodexRegion, GalacticPlanePosition } from './codex-region.js';
+import { SystemAddressInput } from './system-address-input.js';
+
+/**
+ * Resolve a coordinate or system address to its Elite Dangerous **galactic codex
+ * region**.
+ *
+ * The region a system belongs to is fixed by its position on a flat ≈49.35 ly
+ * (`4096 / 83` ly) grid over the galactic plane. Each region's cells are stored as
+ * run-length geometry in [`data/astro/galactic-region-cells.jsonc`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/astro/galactic-region-cells.jsonc) (kept separate
+ * from the lightweight metadata so metadata-only consumers never bundle it); this
+ * module rebuilds a per-row lookup index from them. The per-region metadata objects
+ * live in `./codex-region`.
+ *
+ * Two lookups are provided, matching the two things the game calls "the region":
+ * - {@link findCodexRegionAt} — the region at a set of coordinates (what the codex
+ *   records a discovery against, and what is shown when jumping *into* a system).
+ * - {@link findCodexRegionForBoxel} — the region of a system's boxel `0/0/0` corner
+ *   (what the journal and the codex main page display for the system).
+ *
+ * These can differ near a region border; see the upstream discussion linked in the
+ * data file's attribution.
+ *
+ * Algorithm ported from klightspeed's EliteDangerousRegionMap (`RegionMap.js`),
+ * See [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md) for credit and licence terms.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Galactic X of the galaxy's origin corner, in light-years.
+ *
+ * @example
+ * ```ts
+ * import { CODEX_REGION_MAP_X0 } from '@elite-dangerous-almanac/core/astro/codex-region-lookup';
+ *
+ * CODEX_REGION_MAP_X0; // -> -49985
+ * ```
+ */
+declare const CODEX_REGION_MAP_X0: number;
+/**
+ * Galactic Y of the galaxy's origin corner, in light-years.
+ *
+ * @example
+ * ```ts
+ * import { CODEX_REGION_MAP_Y0 } from '@elite-dangerous-almanac/core/astro/codex-region-lookup';
+ *
+ * CODEX_REGION_MAP_Y0; // -> -40985
+ * ```
+ */
+declare const CODEX_REGION_MAP_Y0: number;
+/**
+ * Galactic Z of the galaxy's origin corner, in light-years.
+ *
+ * @example
+ * ```ts
+ * import { CODEX_REGION_MAP_Z0 } from '@elite-dangerous-almanac/core/astro/codex-region-lookup';
+ *
+ * CODEX_REGION_MAP_Z0; // -> -24105
+ * ```
+ */
+declare const CODEX_REGION_MAP_Z0: number;
+/**
+ * Edge length of one region-grid cell, in light-years (`4096 / 83` ≈ 49.3494).
+ *
+ * @example
+ * ```ts
+ * import { CODEX_REGION_MAP_LY_PER_CELL } from '@elite-dangerous-almanac/core/astro/codex-region-lookup';
+ *
+ * CODEX_REGION_MAP_LY_PER_CELL; // -> approximately 49.3494
+ * ```
+ */
+declare const CODEX_REGION_MAP_LY_PER_CELL: number;
+/**
+ * A point to resolve a region at: a {@link GalacticPlanePosition}, or a full
+ * {@link astro!GalacticPosition | GalacticPosition} — from the journal, EDSM, Spansh or
+ * `ProceduralSystem.position`
+ * — passed straight through, whether it comes from a variable or is written out inline.
+ *
+ * @example
+ * ```ts
+ * import { findCodexRegionAt } from '@elite-dangerous-almanac/core/astro/codex-region-lookup';
+ *
+ * findCodexRegionAt({ x: 0, z: 0 });        // the plane position the map is indexed by
+ * findCodexRegionAt({ x: 0, y: 0, z: 0 });  // a full position, `y` and all
+ * ```
+ */
+interface CodexRegionPoint extends GalacticPlanePosition {
+    /**
+     * Galactic Y, in light-years. Accepted and ignored: the region map is a flat X/Z
+     * projection, so a region has no vertical extent to test against.
+     */
+    readonly y?: number;
+}
+/**
+ * A system's boxel `0/0/0` corner (galactic coordinates, in light-years) and the
+ * region it falls in.
+ *
+ * @example
+ * ```ts
+ * import { findCodexRegionForBoxel } from '@elite-dangerous-almanac/core/astro/codex-region-lookup';
+ * import type { BoxelCodexRegionLookup } from '@elite-dangerous-almanac/core/astro/codex-region-lookup';
+ *
+ * const result: BoxelCodexRegionLookup = findCodexRegionForBoxel(3309179996515n);
+ * ```
+ */
+interface BoxelCodexRegionLookup {
+    /** Galactic X of the boxel corner, in light-years. */
+    readonly x: number;
+    /** Galactic Y of the boxel corner, in light-years. */
+    readonly y: number;
+    /** Galactic Z of the boxel corner, in light-years. */
+    readonly z: number;
+    /** The region at the boxel corner, or `null` if it lies outside the mapped grid. */
+    readonly region: CodexRegion | null;
+}
+/**
+ * Find the galactic region at a point on the galactic plane.
+ *
+ * This is the region the game records a codex discovery against, and the region
+ * name shown when jumping *into* a system.
+ *
+ * @param point - Galactic position, in light-years. Only `x` and `z` are read — the
+ * vertical `y` is accepted but ignored, because the region map is a flat X/Z projection.
+ * @returns The {@link CodexRegion} containing the point, or `null` if the point
+ * lies outside the mapped region grid.
+ * @example
+ * ```ts
+ * import { findCodexRegionAt } from '@elite-dangerous-almanac/core/astro/codex-region-lookup';
+ *
+ * findCodexRegionAt({ x: 0, z: 0 })?.name;      // -> 'Inner Orion Spur' (near Sol)
+ * findCodexRegionAt({ x: 0, z: 25900 })?.name;  // -> 'Galactic Centre'
+ *
+ * // A full position works as it comes — no need to strip the `y` first:
+ * findCodexRegionAt({ x: 0, y: 0, z: 0 })?.name; // -> 'Inner Orion Spur'
+ * ```
+ */
+declare function findCodexRegionAt(point: CodexRegionPoint): CodexRegion | null;
+/**
+ * Find the galactic region of a system's boxel, from its system address (`id64`).
+ *
+ * This is the region written to the player journal and shown on the codex main
+ * page for the system. It is resolved from the `0/0/0` corner of the system's
+ * boxel, which can differ from {@link findCodexRegionAt} of the system's exact
+ * coordinates near a region border.
+ *
+ * @param id64 - The 64-bit system address, as a `bigint`, a normally parsed journal
+ * `number`, or a decimal `string` (see {@link SystemAddressInput}).
+ * @returns The boxel corner coordinates — **galactic light-years, Sol at origin** —
+ * and the region there. Those coordinates are also the closest this library gets to
+ * a position for an `id64` alone: the corner of the system's boxel, so they are
+ * accurate to one boxel edge ({@link boxelEdgeLy} of the size class: 10 ly for mass
+ * code `a`, 1280 ly for `h`).
+ * @throws {TypeError} If `id64` is not a usable address representation.
+ * @throws {RangeError} If the address is outside 64 bits.
+ * @example
+ * ```ts
+ * import { findCodexRegionForBoxel } from '@elite-dangerous-almanac/core/astro/codex-region-lookup';
+ *
+ * findCodexRegionForBoxel(5306097239922n).region?.name; // -> the codex region
+ *
+ * // Approximate position from an id64 alone (boxel corner, in light-years):
+ * const { x, y, z } = findCodexRegionForBoxel(3309179996515n);
+ * ({ x, y, z }); // -> { x: 735, y: -185, z: -105 }
+ * ```
+ */
+declare function findCodexRegionForBoxel(id64: SystemAddressInput): BoxelCodexRegionLookup;
+
+export { type BoxelCodexRegionLookup, CODEX_REGION_MAP_LY_PER_CELL, CODEX_REGION_MAP_X0, CODEX_REGION_MAP_Y0, CODEX_REGION_MAP_Z0, type CodexRegionPoint, SystemAddressInput, findCodexRegionAt, findCodexRegionForBoxel };