@aephia/atlas-kit 0.6.0-next.17 → 0.6.0-next.171

package/dist/world/planet-claim-stake-plots.d.ts

@@ -0,0 +1,139 @@
+import { type Address, type EntityRef, type SageContext } from '../client/index.js';
+import type { ClaimStakeTier as C4ClaimStakeTier, GameClaimStakeDefinitionData } from '../internal/c4/claim-stake-definitions.js';
+import type { WorldFixedValue, WorldStarbaseLevel } from '../internal/c4/world.js';
+import type { PlanetSnapshot, StarSystemSnapshot } from './index.js';
+/** Claim Stake tier label, the column axis of Planet plot tables.
+ *
+ * @example
+ * ```ts
+ * const tier: ClaimStakeTier = 'two';
+ * ```
+ */
+export type ClaimStakeTier = C4ClaimStakeTier;
+/** Returns the zero-based column index of a Claim Stake tier.
+ *
+ * Planet plot, base rent and base placement-fee tables are indexed
+ * `[starbaseLevelIndex][claimStakeTierIndex]`: seven Starbase level rows and
+ * five tier columns.
+ *
+ * @example
+ * ```ts
+ * declare const planet: PlanetSnapshot;
+ * const level1TierTwo = planet.details.claimStakePlots[1]![claimStakeTierIndex('two')];
+ * ```
+ */
+export declare function claimStakeTierIndex(tier: ClaimStakeTier): number;
+/** One Claim Stake structure recorded on a Planet plot.
+ *
+ * `active` is true while the stored deactivation time is zero. A deactivated
+ * structure still occupies its plot until the program removes it from the
+ * Planet.
+ *
+ * @example
+ * ```ts
+ * declare const structure: PlanetClaimStakePlotStructure;
+ * console.log(structure.address, structure.active);
+ * ```
+ */
+export interface PlanetClaimStakePlotStructure {
+    readonly address: Address;
+    readonly deactivationTimeUnixSeconds: bigint;
+    readonly active: boolean;
+}
+/** One plot row of a Planet: the Claim Stakes placed at one Starbase level.
+ *
+ * The program records placed stakes per Starbase level row, not per Claim
+ * Stake definition. `occupied` counts every stake in the row, of every tier
+ * and including deactivated stakes that still hold their plot. `chronology` is
+ * the stored placement order the program uses to index the row's stakes.
+ *
+ * @example
+ * ```ts
+ * declare const row: PlanetClaimStakePlotRow;
+ * console.log(row.level, row.occupied);
+ * ```
+ */
+export interface PlanetClaimStakePlotRow {
+    readonly level: WorldStarbaseLevel;
+    readonly levelIndex: number;
+    readonly occupied: number;
+    readonly structures: readonly PlanetClaimStakePlotStructure[];
+    readonly chronology: readonly Address[];
+}
+/** One Claim Stake definition of a tier and whether the Planet suits it.
+ *
+ * `requiredTagsProvided` is true when the Planet provides every tag the
+ * definition requires. It is not a complete eligibility verdict: permissions,
+ * rent, faction rules and concurrent placements remain chain-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const entry: PlanetClaimStakePlotDefinition;
+ * console.log(entry.definition.name, entry.requiredTagsProvided);
+ * ```
+ */
+export interface PlanetClaimStakePlotDefinition {
+    readonly definition: GameClaimStakeDefinitionData;
+    readonly requiredTagsProvided: boolean;
+}
+/** Plot limits and availability for one Claim Stake tier on a Planet.
+ *
+ * `plotLimitByLevel`, `baseRentRateByLevel` and `basePlacementFeeByLevel`
+ * list the stored cell of every plot row in {@link starbaseLevelIndex} order.
+ * A row's limit caps the stakes of all tiers in that row: placing a stake of
+ * this tier needs a row whose `occupied` count is below this tier's limit.
+ * The program uses the first such row from `level-0` up to the System's
+ * Starbase level; `placementLevel` names it. `available` sums the free plots
+ * of this tier over those rows. Both are absent when the System has no
+ * Starbase. Tiers share rows, so availability across tiers does not add up.
+ * Definition multipliers and the exact rent and fee settlement remain
+ * program-authoritative.
+ *
+ * @example
+ * ```ts
+ * declare const tier: PlanetClaimStakePlotTier;
+ * console.log(tier.tier, tier.available, tier.placementLevel);
+ * ```
+ */
+export interface PlanetClaimStakePlotTier {
+    readonly tier: ClaimStakeTier;
+    readonly tierIndex: number;
+    readonly plotLimitByLevel: readonly number[];
+    readonly baseRentRateByLevel: readonly WorldFixedValue[];
+    readonly basePlacementFeeByLevel: readonly WorldFixedValue[];
+    readonly available?: number;
+    readonly placementLevel?: WorldStarbaseLevel;
+    readonly definitions: readonly PlanetClaimStakePlotDefinition[];
+}
+/** Immutable Claim Stake plot availability of one Planet.
+ *
+ * `rows` always holds the seven plot rows in Starbase level order, and `tiers`
+ * the five Claim Stake tiers in order. `starbaseLevel` and
+ * `starbaseLevelIndex` come from the Planet's StarSystem and are absent when
+ * that System has no Starbase. Read metadata reports the older of the Planet
+ * and StarSystem observations.
+ *
+ * @example
+ * ```ts
+ * declare const plots: PlanetClaimStakePlotsSnapshot;
+ * const open = plots.tiers.filter((tier) => (tier.available ?? 0) > 0);
+ * console.log(plots.name, open.map((tier) => tier.tier));
+ * ```
+ */
+export interface PlanetClaimStakePlotsSnapshot {
+    readonly kind: 'planetClaimStakePlots';
+    readonly address: Address;
+    readonly bodyId: number;
+    readonly name: string;
+    readonly game: Address;
+    readonly system: EntityRef<'starSystem'>;
+    readonly starbaseLevel?: WorldStarbaseLevel;
+    readonly starbaseLevelIndex?: number;
+    readonly providedTags: readonly number[];
+    readonly rows: readonly PlanetClaimStakePlotRow[];
+    readonly tiers: readonly PlanetClaimStakePlotTier[];
+    toJSON(): unknown;
+}
+/** Builds the plot availability snapshot for a loaded Planet and its System. */
+export declare function createPlanetClaimStakePlotsSnapshot(context: SageContext, planet: PlanetSnapshot, system: StarSystemSnapshot): Promise<PlanetClaimStakePlotsSnapshot>;
+//# sourceMappingURL=planet-claim-stake-plots.d.ts.map

package/dist/world/planet-claim-stake-plots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planet-claim-stake-plots.d.ts","sourceRoot":"","sources":["../../src/world/planet-claim-stake-plots.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,OAAO,EACZ,KAAK,SAAS,EAEd,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,cAAc,IAAI,gBAAgB,EAClC,4BAA4B,EAC7B,MAAM,2CAA2C,CAAC;AACnD,OAAO,KAAK,EAEV,eAAe,EACf,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAYjC,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAU9C;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,CAAC;CACzC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,UAAU,EAAE,4BAA4B,CAAC;IAClD,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,eAAe,EAAE,CAAC;IACzD,QAAQ,CAAC,uBAAuB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,8BAA8B,EAAE,CAAC;CACjE;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IAC5C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACpD,MAAM,IAAI,OAAO,CAAC;CACnB;AAkCD,gFAAgF;AAChF,wBAAsB,mCAAmC,CACvD,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,6BAA6B,CAAC,CA+FxC"}

package/dist/world/planet-claim-stake-plots.js

@@ -0,0 +1,117 @@
+import { AccountDecodeError, entityRef, } from '../client/index.js';
+import { attachJsonSerialization } from '../internal/json.js';
+import { attachReadMeta, readMeta } from '../internal/read-meta.js';
+import { freezeResolvedSnapshot } from '../internal/resolved-snapshot.js';
+import { CLAIM_STAKE_PLOT_ROWS, claimStakeFreePlotsByRow, claimStakePlacementRow, claimStakePlotRowOccupancy, } from '../internal/c4/claim-stake-plots.js';
+import { listClaimStakeDefinitions } from '../registry/index.js';
+import { starbaseLevelIndex } from './starbase-status.js';
+const CLAIM_STAKE_TIERS = Object.freeze([
+    'one',
+    'two',
+    'three',
+    'four',
+    'five',
+]);
+/** Returns the zero-based column index of a Claim Stake tier.
+ *
+ * Planet plot, base rent and base placement-fee tables are indexed
+ * `[starbaseLevelIndex][claimStakeTierIndex]`: seven Starbase level rows and
+ * five tier columns.
+ *
+ * @example
+ * ```ts
+ * declare const planet: PlanetSnapshot;
+ * const level1TierTwo = planet.details.claimStakePlots[1]![claimStakeTierIndex('two')];
+ * ```
+ */
+export function claimStakeTierIndex(tier) {
+    return CLAIM_STAKE_TIERS.indexOf(tier);
+}
+const PLOT_ROW_LEVELS = Object.freeze([
+    'level-0',
+    'level-1',
+    'level-2',
+    'level-3',
+    'level-4',
+    'level-5',
+    'css',
+]);
+function structuresOf(group) {
+    return (group?.structures ?? []).map((structure) => ({
+        active: structure.deactivationTimeUnixSeconds === 0n,
+        address: structure.address,
+        deactivationTimeUnixSeconds: structure.deactivationTimeUnixSeconds,
+    }));
+}
+function olderMetadata(planet, system) {
+    return {
+        commitment: planet.commitment,
+        slot: planet.slot < system.slot ? planet.slot : system.slot,
+        source: planet.source,
+        strategy: 'direct',
+    };
+}
+/** Builds the plot availability snapshot for a loaded Planet and its System. */
+export async function createPlanetClaimStakePlotsSnapshot(context, planet, system) {
+    const details = planet.details;
+    const outsideRow = details.claimedPlots.find(({ key }) => !Number.isInteger(key) || key < 0 || key >= CLAIM_STAKE_PLOT_ROWS);
+    if (outsideRow !== undefined) {
+        throw new AccountDecodeError('celestialBody', planet.address, new RangeError('A Claim Stake plot group is outside the Starbase level rows.'), `Planet ${planet.address} records Claim Stakes in plot row ${String(outsideRow.key)}, but plot rows are the ${String(CLAIM_STAKE_PLOT_ROWS)} Starbase levels. Refresh the Planet and verify the pinned binding version before retrying.`);
+    }
+    const definitions = await listClaimStakeDefinitions(context);
+    const starbase = system.starbase;
+    const levelIndex = starbase === undefined ? undefined : starbaseLevelIndex(starbase.level);
+    const rows = PLOT_ROW_LEVELS.map((level, index) => {
+        const group = details.claimedPlots.find(({ key }) => key === index);
+        return {
+            chronology: [...(group?.chronoAddresses ?? [])],
+            level,
+            levelIndex: index,
+            occupied: claimStakePlotRowOccupancy(details.claimedPlots, index),
+            structures: structuresOf(group),
+        };
+    });
+    const tiers = CLAIM_STAKE_TIERS.map((tier, tierIndex) => {
+        // The pinned Planet codec fixes seven level rows and five tier columns.
+        const column = (grid) => grid.map((row) => row[tierIndex]);
+        const entries = definitions
+            .filter((definition) => definition.tier === tier)
+            .map((definition) => ({
+            definition,
+            requiredTagsProvided: definition.requiredTagIds.every((tag) => details.providedTags.includes(tag)),
+        }));
+        const common = {
+            basePlacementFeeByLevel: column(details.baseClaimStakePlacementFee).map((value) => ({ ...value })),
+            baseRentRateByLevel: column(details.baseClaimStakeRentRate).map((value) => ({ ...value })),
+            definitions: entries,
+            plotLimitByLevel: column(details.claimStakePlots),
+            tier,
+            tierIndex,
+        };
+        if (levelIndex === undefined)
+            return common;
+        const placementRow = claimStakePlacementRow(details.claimStakePlots, details.claimedPlots, tierIndex, levelIndex);
+        return {
+            ...common,
+            available: claimStakeFreePlotsByRow(details.claimStakePlots, details.claimedPlots, tierIndex, levelIndex).reduce((total, free) => total + free, 0),
+            ...(placementRow === undefined
+                ? {}
+                : { placementLevel: PLOT_ROW_LEVELS[placementRow] }),
+        };
+    });
+    return freezeResolvedSnapshot(attachReadMeta(attachJsonSerialization({
+        address: planet.address,
+        bodyId: planet.id,
+        game: planet.game,
+        kind: 'planetClaimStakePlots',
+        name: planet.name,
+        providedTags: [...details.providedTags],
+        rows,
+        ...(starbase === undefined || levelIndex === undefined
+            ? {}
+            : { starbaseLevel: starbase.level, starbaseLevelIndex: levelIndex }),
+        system: entityRef('starSystem', system.address),
+        tiers,
+    }), olderMetadata(readMeta(planet), readMeta(system))));
+}
+//# sourceMappingURL=planet-claim-stake-plots.js.map

package/dist/world/planet-claim-stake-plots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planet-claim-stake-plots.js","sourceRoot":"","sources":["../../src/world/planet-claim-stake-plots.ts"],"names":[],"mappings":"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"}

package/dist/world/starbase-status.d.ts

@@ -0,0 +1,217 @@
+import { type Address, type EntityRef, type SageContext } from '../client/index.js';
+import type { WorldFaction, WorldStarbaseData, WorldStarbaseLevel, WorldStarbaseLevelInfoData } from '../internal/c4/world.js';
+import { type CargoDefinitionSummary } from '../registry/index.js';
+import type { StarSystemSnapshot } from './index.js';
+/** Returns the zero-based ordinal of a Starbase level label.
+ *
+ * Levels `level-0` through `level-5` map to 0 through 5 and the Central Space
+ * Station (`css`) ranks above them as 6. This is the row index used by Planet
+ * Claim Stake plot tables and Starbase Crafting Hab plot tables, and the order
+ * used to compare a Starbase level with a service enable level.
+ *
+ * @example
+ * ```ts
+ * const unlocked = starbaseLevelIndex('level-3') >= starbaseLevelIndex('level-2');
+ * ```
+ */
+export declare function starbaseLevelIndex(level: WorldStarbaseLevel): number;
+/** One material a shared Starbase needs before it can reach its next level.
+ *
+ * `needed`, `deposited` and `remaining` are raw cargo units. `complete` is true
+ * once `deposited` has reached `needed`. `crew` and `durationSeconds` describe
+ * one contribution of this material: a Starbase Player installs it through its
+ * own `StarbaseUpgradeProcess`, which the `starbases` entry reads separately.
+ *
+ * @example
+ * ```ts
+ * declare const material: StarbaseUpgradeMaterial;
+ * console.log(material.cargoId, material.remaining);
+ * ```
+ */
+export interface StarbaseUpgradeMaterial {
+    readonly cargoId: number;
+    readonly needed: bigint;
+    readonly deposited: bigint;
+    readonly remaining: bigint;
+    readonly complete: boolean;
+    readonly crew: number;
+    readonly durationSeconds: number;
+}
+/** Shared progress of a Starbase toward its next level.
+ *
+ * `complete` is true when every listed material is fully deposited. The pinned
+ * contract states that the Starbase should then change level and reset the
+ * deposits; the program applies that change, the SDK only reports the stored
+ * state.
+ *
+ * @example
+ * ```ts
+ * declare const upgrade: StarbaseUpgradeProgress;
+ * console.log(upgrade.toLevel, upgrade.complete);
+ * ```
+ */
+export interface StarbaseUpgradeProgress {
+    readonly toLevel: WorldStarbaseLevel;
+    readonly complete: boolean;
+    readonly materials: readonly StarbaseUpgradeMaterial[];
+}
+/** Whether one Starbase service is enabled at the current level.
+ *
+ * @example
+ * ```ts
+ * declare const service: StarbaseServiceAvailability;
+ * if (service.available) console.log('enabled since', service.enabledFromLevel);
+ * ```
+ */
+export interface StarbaseServiceAvailability {
+    readonly enabledFromLevel: WorldStarbaseLevel;
+    readonly available: boolean;
+}
+/** Hull and shield points of a shared Starbase, with its level maximums.
+ *
+ * `pendingHullPoints` is the repair reservoir: hull points already paid for
+ * that regenerate into `hullPoints` over time. Hull plus pending never exceeds
+ * the maximum.
+ *
+ * @example
+ * ```ts
+ * declare const points: StarbasePoints;
+ * console.log(points.hullPoints / points.maxHullPoints);
+ * ```
+ */
+export interface StarbasePoints {
+    readonly hullPoints: number;
+    readonly pendingHullPoints: number;
+    readonly maxHullPoints: number;
+    readonly shieldPoints: number;
+    readonly maxShieldPoints: number;
+}
+/** Derived status of the shared Starbase nested in one StarSystem.
+ *
+ * `current` pairs the stored hull and shield points with the maximums the
+ * current level configures. The program writes these points only when combat
+ * or a repair touches the Starbase and regenerates them on read in between, so
+ * stored values can lag far behind: use {@link projectStarbasePoints} for the
+ * points at a given moment. `timing` values are raw Unix seconds, as on the
+ * Fleet combat status. `upgrade` is absent once the Starbase has reached its
+ * maximum level.
+ *
+ * @example
+ * ```ts
+ * declare const status: StarbaseStatus;
+ * console.log(status.level, status.current.hullPoints, status.current.maxHullPoints);
+ * ```
+ */
+export interface StarbaseStatus {
+    readonly kind: 'starbaseStatus';
+    readonly owner: WorldFaction;
+    readonly level: WorldStarbaseLevel;
+    /** Ordinal from {@link starbaseLevelIndex}; the Central Space Station is 6. */
+    readonly levelIndex: number;
+    readonly maxLevel: WorldStarbaseLevel;
+    readonly atMaxLevel: boolean;
+    /** Configured values for the current level, copied from the level table. */
+    readonly levelInfo: WorldStarbaseLevelInfoData;
+    /** Stored points, as last written; see {@link projectStarbasePoints}. */
+    readonly current: StarbasePoints;
+    readonly timing: {
+        /** When shield points may resume regenerating after reaching zero. */
+        readonly shieldBreakDelayEndsAtUnixSeconds: bigint;
+        readonly lastCombatUpdateAtUnixSeconds: bigint;
+        /** When the Starbase was last built or destroyed. */
+        readonly builtOrDestroyedAtUnixSeconds: bigint;
+    };
+    readonly services: {
+        readonly localMarket: StarbaseServiceAvailability;
+        readonly repair: StarbaseServiceAvailability;
+    };
+    readonly upgrade?: StarbaseUpgradeProgress;
+    toJSON(): unknown;
+}
+/** One upgrade material with its registry-resolved cargo definition.
+ *
+ * @example
+ * ```ts
+ * declare const material: ResolvedStarbaseUpgradeMaterial;
+ * console.log(material.cargo.name, material.remaining);
+ * ```
+ */
+export interface ResolvedStarbaseUpgradeMaterial extends StarbaseUpgradeMaterial {
+    readonly cargo: CargoDefinitionSummary;
+}
+/** Upgrade progress whose materials carry resolved cargo definitions.
+ *
+ * @example
+ * ```ts
+ * declare const upgrade: ResolvedStarbaseUpgradeProgress;
+ * console.log(upgrade.materials.map((material) => material.cargo.name));
+ * ```
+ */
+export interface ResolvedStarbaseUpgradeProgress extends Omit<StarbaseUpgradeProgress, 'materials'> {
+    readonly materials: readonly ResolvedStarbaseUpgradeMaterial[];
+}
+/** Immutable shared Starbase status read for one StarSystem.
+ *
+ * `address` is the StarSystem address: the nested Starbase has no account of
+ * its own. Read metadata comes from the StarSystem observation.
+ *
+ * @example
+ * ```ts
+ * declare const status: StarbaseStatusSnapshot;
+ * console.log(status.systemName, status.upgrade?.materials[0]?.cargo.name);
+ * ```
+ */
+export interface StarbaseStatusSnapshot extends Omit<StarbaseStatus, 'upgrade'> {
+    readonly address: Address;
+    readonly system: EntityRef<'starSystem'>;
+    readonly systemName: string;
+    readonly upgrade?: ResolvedStarbaseUpgradeProgress;
+}
+/** Derives the status of a shared Starbase from already-loaded StarSystem data.
+ *
+ * This is pure and network-free: it needs neither the context nor the Game
+ * definitions registry, so galaxy-map readers can call it on every System they
+ * already hold. The result is a new deeply frozen value; the input is left
+ * untouched. Materials carry numeric cargo ids; use `getStarbaseStatus` when
+ * you want them resolved to cargo definitions.
+ *
+ * @example
+ * ```ts
+ * declare const system: StarSystemSnapshot;
+ * if (system.starbase !== undefined) {
+ *   const status = deriveStarbaseStatus(system.starbase);
+ *   console.log(status.level, status.upgrade?.toLevel);
+ * }
+ * ```
+ */
+export declare function deriveStarbaseStatus(starbase: WorldStarbaseData): StarbaseStatus;
+/** Builds the resolved status snapshot for a loaded StarSystem's Starbase. */
+export declare function createStarbaseStatusSnapshot(context: SageContext, system: StarSystemSnapshot, starbase: WorldStarbaseData): Promise<StarbaseStatusSnapshot>;
+/** Projects a shared Starbase's hull and shield points to one moment.
+ *
+ * Between combat and repairs the program regenerates both on read, from the
+ * stored points and the last combat update:
+ *
+ * - Hull: pending repair points flow into the hull at the level's
+ *   `repairRate` per second, never past the maximum. A full hull holds no
+ *   pending points.
+ * - Shield: once the shield break delay has ended, the shield recharges at
+ *   the level's `shieldRechargeRate` per second from the later of the last
+ *   combat update and the end of the delay, never past the maximum.
+ *
+ * Results are the whole points the program would store if it settled at
+ * `atUnixSeconds`; combat itself uses the unrounded values, less than one point
+ * higher. This is pure and network-free, so a map can project every Starbase
+ * it already holds on each frame. A moment at or before the last combat
+ * update adds no regeneration.
+ *
+ * @example
+ * ```ts
+ * declare const status: StarbaseStatus;
+ * const now = BigInt(Math.floor(Date.now() / 1000));
+ * const points = projectStarbasePoints(status, now);
+ * console.log(points.hullPoints, points.shieldPoints);
+ * ```
+ */
+export declare function projectStarbasePoints(status: Pick<StarbaseStatus, 'current' | 'levelInfo' | 'timing'>, atUnixSeconds: bigint): StarbasePoints;
+//# sourceMappingURL=starbase-status.d.ts.map

package/dist/world/starbase-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starbase-status.d.ts","sourceRoot":"","sources":["../../src/world/starbase-status.ts"],"names":[],"mappings":"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"}