@shipload/sdk 1.0.0-next.7 → 1.0.0-next.70

package/src/planner/planner.test.ts

@@ -0,0 +1,459 @@
+import {UInt8, UInt16, UInt32, UInt64} from '@wharfkit/antelope'
+import {expect, test, describe} from 'bun:test'
+import {ServerContract} from '../contracts'
+import {encodeStats} from '../derivation/crafting'
+import {ITEM_GATHERER_T1} from '../data/item-ids'
+import {
+    planParallelTransfer,
+    planSingleGather,
+    type GatherPlanEntity,
+    gatherEnergyCost,
+    splitCost,
+    maxQtyForCharge,
+    buildGatherPlan,
+} from './index'
+
+type ModuleEntry = ServerContract.Types.module_entry
+type Lane = ServerContract.Types.lane
+
+function makeModuleEntry(itemId: number, stats: bigint): ModuleEntry {
+    return {
+        type: UInt8.from(0),
+        installed: {
+            item_id: UInt16.from(itemId),
+            stats: UInt64.from(stats),
+        },
+    } as unknown as ModuleEntry
+}
+
+function gathererLane(
+    slotIndex: number,
+    yieldVal: number,
+    drain: number,
+    depth: number
+): ServerContract.Types.gatherer_lane {
+    return ServerContract.Types.gatherer_lane.from({
+        slot_index: UInt8.from(slotIndex),
+        yield: UInt16.from(yieldVal),
+        drain: UInt32.from(drain),
+        depth: UInt16.from(depth),
+        output_pct: UInt16.from(100),
+    })
+}
+
+function loaderLane(
+    slotIndex: number,
+    mass: number,
+    thrust: number
+): ServerContract.Types.loader_lane {
+    return ServerContract.Types.loader_lane.from({
+        slot_index: UInt8.from(slotIndex),
+        mass: UInt32.from(mass),
+        thrust: UInt16.from(thrust),
+        output_pct: UInt16.from(100),
+    })
+}
+
+function energyStats(capacity: number, recharge: number): ServerContract.Types.energy_stats {
+    return ServerContract.Types.energy_stats.from({
+        capacity: UInt32.from(capacity),
+        recharge: UInt32.from(recharge),
+    })
+}
+
+interface EntityOverrides {
+    gatherer_lanes?: ServerContract.Types.gatherer_lane[]
+    loader_lanes?: ServerContract.Types.loader_lane[]
+    generator?: ServerContract.Types.energy_stats
+    energy?: number
+    lanes?: ServerContract.Types.lane[]
+}
+
+function entity(overrides: EntityOverrides = {}): GatherPlanEntity {
+    return {
+        gatherer_lanes: overrides.gatherer_lanes ?? [],
+        loader_lanes: overrides.loader_lanes ?? [],
+        generator: overrides.generator,
+        energy: overrides.energy !== undefined ? UInt32.from(overrides.energy) : undefined,
+        lanes: overrides.lanes ?? [],
+        coordinates: ServerContract.Types.coordinates.from({x: 0, y: 0}),
+        cargo: [],
+        cargomass: UInt32.from(0),
+    }
+}
+
+const NOW = new Date('2026-06-21T00:00:00.000Z')
+
+describe('planParallelTransfer', () => {
+    test('two loader lanes: quantities proportional to thrust, sums to target', () => {
+        const THRUST1 = 100
+        const THRUST2 = 200
+        const QUANTITY = 90
+
+        const e = entity({
+            loader_lanes: [loaderLane(0, 500, THRUST1), loaderLane(1, 500, THRUST2)],
+        })
+
+        const plan = planParallelTransfer(e, {quantity: QUANTITY})
+
+        expect(plan).toHaveLength(2)
+        expect(plan.reduce((s, p) => s + p.quantity, 0)).toBe(QUANTITY)
+
+        const q1 = plan.find((p) => p.slot === 0)!.quantity
+        const q2 = plan.find((p) => p.slot === 1)!.quantity
+        expect(q2 / q1).toBeCloseTo(THRUST2 / THRUST1, 0)
+    })
+
+    test('no loader lanes: returns empty plan', () => {
+        const plan = planParallelTransfer(entity({loader_lanes: []}), {quantity: 10})
+        expect(plan).toHaveLength(0)
+    })
+
+    test('thrust=0 loader lane (no-loader/mobility case): returns empty plan', () => {
+        const plan = planParallelTransfer(entity({loader_lanes: [loaderLane(0, 500, 0)]}), {
+            quantity: 10,
+        })
+        expect(plan).toHaveLength(0)
+    })
+
+    test("'max' target: each loader lane gets >= 1 unit", () => {
+        const e = entity({
+            loader_lanes: [loaderLane(0, 500, 100), loaderLane(1, 500, 200)],
+        })
+        const plan = planParallelTransfer(e, 'max')
+        expect(plan.length).toBeGreaterThan(0)
+        for (const entry of plan) {
+            expect(entry.quantity).toBeGreaterThanOrEqual(1)
+        }
+    })
+})
+
+describe('cost helpers', () => {
+    const STRATUM = 100
+    const ITEM_MASS = 10
+    const RICHNESS = 500
+
+    test('gatherEnergyCost is 0 for non-positive quantity and positive otherwise', () => {
+        const lane = gathererLane(0, 700, 1_250_000, 5000)
+        expect(gatherEnergyCost(lane, 0, STRATUM, ITEM_MASS, RICHNESS)).toBe(0)
+        expect(gatherEnergyCost(lane, 100, STRATUM, ITEM_MASS, RICHNESS)).toBeGreaterThan(0)
+    })
+
+    test('splitCost across two lanes is monotonic non-decreasing in quantity', () => {
+        const reaching = [
+            gathererLane(0, 700, 1_250_000, 5000),
+            gathererLane(1, 700, 1_250_000, 5000),
+        ]
+        const c100 = splitCost(reaching, 100, STRATUM, ITEM_MASS, RICHNESS)
+        const c200 = splitCost(reaching, 200, STRATUM, ITEM_MASS, RICHNESS)
+        expect(c200).toBeGreaterThanOrEqual(c100)
+    })
+
+    test('maxQtyForCharge returns hi when the whole batch fits the charge', () => {
+        const reaching = [gathererLane(0, 700, 1_250_000, 5000)]
+        // capacity huge → the full 500 fits
+        expect(maxQtyForCharge(reaching, 500, 1_000_000, STRATUM, ITEM_MASS, RICHNESS)).toBe(500)
+    })
+
+    test('maxQtyForCharge finds the boundary: result fits, result+1 does not', () => {
+        const reaching = [gathererLane(0, 700, 1_250_000, 5000)]
+        const capacity = 40_000
+        const q = maxQtyForCharge(reaching, 100_000, capacity, STRATUM, ITEM_MASS, RICHNESS)
+        expect(splitCost(reaching, q, STRATUM, ITEM_MASS, RICHNESS)).toBeLessThanOrEqual(capacity)
+        expect(splitCost(reaching, q + 1, STRATUM, ITEM_MASS, RICHNESS)).toBeGreaterThan(capacity)
+    })
+})
+
+describe('buildGatherPlan', () => {
+    const STRATUM = 100
+    const OPTS = {
+        richness: 500,
+        itemMass: 10,
+        holdRoom: 1_000_000,
+        reserveRemaining: 1_000_000,
+        now: NOW,
+    }
+
+    test('single cycle when the target fits one charge and energy is full', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1_250_000, 5000)],
+            generator: energyStats(1_200_000, 2000),
+            energy: 1_200_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 100}, OPTS)
+        expect(plan.cycleCount).toBe(1)
+        expect(plan.totalOre).toBe(100)
+        expect(plan.cycles[0].rechargeBefore).toBe(false)
+        expect(plan.cycles[0].limpets).toHaveLength(1)
+        expect(plan.cycles[0].limpets[0].quantity).toBe(100)
+        expect(plan.cap).toBe('requested')
+    })
+
+    test('two limpets split one charge proportional to yield, finish within 1s of each other', () => {
+        const e = entity({
+            gatherer_lanes: [
+                gathererLane(0, 200, 500_000, 5000),
+                gathererLane(1, 400, 500_000, 5000),
+            ],
+            generator: energyStats(60_000_000, 2000),
+            energy: 60_000_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 60}, OPTS)
+        expect(plan.cycleCount).toBe(1)
+        const [a, b] = plan.cycles[0].limpets
+        expect(a.quantity + b.quantity).toBe(60)
+        expect(b.quantity).toBeGreaterThan(a.quantity) // higher yield gets more
+        expect(Math.abs(a.durationSeconds - b.durationSeconds)).toBeLessThanOrEqual(2)
+    })
+
+    test('multi-cycle: fills beyond one charge; totalOre equals fill target; each cycle fits the charge', () => {
+        const CAP = 40_000
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1_250_000, 5000)],
+            generator: energyStats(CAP, 2),
+            energy: CAP,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 500}, OPTS)
+        expect(plan.cycleCount).toBeGreaterThan(1)
+        expect(plan.totalOre).toBe(500)
+        // every cycle's summed gather cost fits one full charge
+        for (const c of plan.cycles) {
+            const cost = splitCost(
+                e.gatherer_lanes,
+                c.batchOre,
+                STRATUM,
+                OPTS.itemMass,
+                OPTS.richness
+            )
+            expect(cost).toBeLessThanOrEqual(CAP)
+        }
+        // cycles after the first recharge to full
+        expect(plan.cycles.slice(1).every((c) => c.rechargeBefore)).toBe(true)
+        // limpet quantities across all cycles sum to the target
+        const gathered = plan.cycles.flatMap((c) => c.limpets).reduce((s, l) => s + l.quantity, 0)
+        expect(gathered).toBe(500)
+    })
+
+    test('cap reasons: hold binds, reserve binds, requested binds', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1_250_000, 5000)],
+            generator: energyStats(60_000_000, 2000),
+            energy: 60_000_000,
+        })
+        expect(
+            buildGatherPlan(e, STRATUM, 'max', {...OPTS, holdRoom: 300, reserveRemaining: 9999}).cap
+        ).toBe('hold')
+        expect(
+            buildGatherPlan(e, STRATUM, 'max', {...OPTS, holdRoom: 9999, reserveRemaining: 200}).cap
+        ).toBe('reserve')
+        expect(buildGatherPlan(e, STRATUM, {quantity: 50}, OPTS).cap).toBe('requested')
+    })
+
+    test('total ETA sums per-cycle recharge + gather seconds', () => {
+        const CAP = 40_000
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1_250_000, 5000)],
+            generator: energyStats(CAP, 2),
+            energy: CAP,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 500}, OPTS)
+        const expected = plan.cycles.reduce((s, c) => s + c.rechargeSeconds + c.gatherSeconds, 0)
+        expect(plan.totalSeconds).toBe(expected)
+    })
+
+    test('excludes limpets that cannot reach the stratum and warns', () => {
+        const e = entity({
+            gatherer_lanes: [
+                gathererLane(0, 700, 1_250_000, 5000), // reaches 100
+                gathererLane(1, 700, 1_250_000, 50), // does not reach 100
+            ],
+            generator: energyStats(60_000_000, 2000),
+            energy: 60_000_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 100}, OPTS)
+        expect(plan.cycles[0].limpets).toHaveLength(1)
+        expect(plan.cycles[0].limpets[0].slot).toBe(0)
+        expect(plan.warnings.some((w) => w.includes("can't reach"))).toBe(true)
+    })
+
+    test('reports structured limpet reach counts (all reaching)', () => {
+        const e = entity({
+            gatherer_lanes: [
+                gathererLane(0, 700, 1_250_000, 5000),
+                gathererLane(1, 700, 1_250_000, 5000),
+            ],
+            generator: energyStats(60_000_000, 2000),
+            energy: 60_000_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 50}, OPTS)
+        expect(plan.totalLimpets).toBe(2)
+        expect(plan.reachingCount).toBe(2)
+    })
+
+    test('reachingCount excludes limpets that cannot reach the stratum', () => {
+        const e = entity({
+            gatherer_lanes: [
+                gathererLane(0, 700, 1_250_000, 5000), // reaches 100
+                gathererLane(1, 700, 1_250_000, 50), // does not reach 100
+            ],
+            generator: energyStats(60_000_000, 2000),
+            energy: 60_000_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 50}, OPTS)
+        expect(plan.totalLimpets).toBe(2)
+        expect(plan.reachingCount).toBe(1)
+    })
+
+    test('single-limpet ship still fills across cycles', () => {
+        const CAP = 40_000
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1_250_000, 5000)],
+            generator: energyStats(CAP, 2),
+            energy: CAP,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 300}, OPTS)
+        expect(plan.cycles.every((c) => c.limpets.length === 1)).toBe(true)
+        expect(plan.totalOre).toBe(300)
+    })
+
+    test('throws when no gatherer reaches the stratum', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1_250_000, 50)],
+            generator: energyStats(1_200_000, 2000),
+            energy: 1_200_000,
+        })
+        expect(() => buildGatherPlan(e, STRATUM, 'max', OPTS)).toThrow('no gatherer reaches')
+    })
+
+    test('zero fill target yields an empty plan (no cycles)', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1_250_000, 5000)],
+            generator: energyStats(1_200_000, 2000),
+            energy: 1_200_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, 'max', {...OPTS, holdRoom: 0})
+        expect(plan.cycleCount).toBe(0)
+        expect(plan.totalOre).toBe(0)
+        expect(plan.cap).toBe('hold')
+    })
+
+    test('first cycle skips recharge when current energy already covers the small batch', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1_250_000, 5000)],
+            generator: energyStats(60_000_000, 2000),
+            energy: 60_000_000, // full
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 50}, OPTS)
+        expect(plan.cycles[0].rechargeBefore).toBe(false)
+        expect(plan.cycles[0].rechargeSeconds).toBe(0)
+    })
+})
+
+describe('planSingleGather', () => {
+    const STRATUM = 100
+    const ITEM_MASS = 1000
+    const RICHNESS = 500
+    const deepStats = encodeStats([100, 900, 100]) // tol=900 => depth=5000 for tier1
+
+    test('mirrors the bot hand-assembly: laneKey, quantity, energyCost match selectGatherLane + maxQtyForCharge + splitCost', () => {
+        const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, deepStats)]
+        const lane = gathererLane(0, 700, 1_250_000, 5000)
+
+        const result = planSingleGather({
+            modules,
+            entityItemId: ITEM_GATHERER_T1,
+            lanes: [],
+            gathererLanes: [lane],
+            stratum: STRATUM,
+            desiredQuantity: 100,
+            itemMass: ITEM_MASS,
+            richness: RICHNESS,
+            generatorCapacity: 1_000_000,
+            currentEnergy: 1_000_000,
+        })
+
+        const expectedLaneKey = 1
+        const expectedQuantity = maxQtyForCharge(
+            [lane],
+            100,
+            1_000_000,
+            STRATUM,
+            ITEM_MASS,
+            RICHNESS
+        )
+        const expectedCost = splitCost([lane], expectedQuantity, STRATUM, ITEM_MASS, RICHNESS)
+
+        expect(result.laneKey).toBe(expectedLaneKey)
+        expect(result.quantity).toBe(expectedQuantity)
+        expect(result.energyCost).toBe(expectedCost)
+        expect(result.needsRecharge).toBe(false)
+    })
+
+    test('needsRecharge is true when current energy is below the priced cost', () => {
+        const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, deepStats)]
+        const lane = gathererLane(0, 700, 1_250_000, 5000)
+
+        const result = planSingleGather({
+            modules,
+            entityItemId: ITEM_GATHERER_T1,
+            lanes: [],
+            gathererLanes: [lane],
+            stratum: STRATUM,
+            desiredQuantity: 100,
+            itemMass: ITEM_MASS,
+            richness: RICHNESS,
+            generatorCapacity: 1_000_000,
+            currentEnergy: 0,
+        })
+
+        expect(result.energyCost).toBeGreaterThan(0)
+        expect(result.needsRecharge).toBe(true)
+    })
+
+    test('caps quantity to what fits one full charge, same boundary as maxQtyForCharge', () => {
+        const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, deepStats)]
+        const lane = gathererLane(0, 700, 1_250_000, 5000)
+        const capacity = 40_000
+
+        const result = planSingleGather({
+            modules,
+            entityItemId: ITEM_GATHERER_T1,
+            lanes: [],
+            gathererLanes: [lane],
+            stratum: STRATUM,
+            desiredQuantity: 100_000,
+            itemMass: ITEM_MASS,
+            richness: RICHNESS,
+            generatorCapacity: capacity,
+            currentEnergy: capacity,
+        })
+
+        expect(
+            splitCost([lane], result.quantity, STRATUM, ITEM_MASS, RICHNESS)
+        ).toBeLessThanOrEqual(capacity)
+        expect(
+            splitCost([lane], result.quantity + 1, STRATUM, ITEM_MASS, RICHNESS)
+        ).toBeGreaterThan(capacity)
+    })
+
+    test('throws when no gatherer lane reaches the stratum, same as selectGatherLane', () => {
+        const shallowStats = encodeStats([100, 10, 100]) // depth=550 for tier1
+        const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, shallowStats)]
+        const lane = gathererLane(0, 700, 1_250_000, 550)
+
+        expect(() =>
+            planSingleGather({
+                modules,
+                entityItemId: ITEM_GATHERER_T1,
+                lanes: [] as Lane[],
+                gathererLanes: [lane],
+                stratum: 5000,
+                desiredQuantity: 100,
+                itemMass: ITEM_MASS,
+                richness: RICHNESS,
+                generatorCapacity: 1_000_000,
+                currentEnergy: 1_000_000,
+            })
+        ).toThrow('no gatherer reaches this stratum')
+    })
+})

package/src/receipts.ts

@@ -0,0 +1,22 @@
+import {Serializer} from '@wharfkit/antelope'
+import {ServerContract} from './contracts'
+
+export type BookingReceipt = ServerContract.Types.booking_receipt
+
+export function decodeBookingReceipt(data: unknown): BookingReceipt {
+    if (data === null || data === undefined) {
+        throw new Error('decodeBookingReceipt: no return value')
+    }
+    if (data instanceof Uint8Array || typeof data === 'string') {
+        return Serializer.decode({data, type: ServerContract.Types.booking_receipt})
+    }
+    return ServerContract.Types.booking_receipt.from(data as ServerContract.Types.booking_receipt)
+}
+
+export function bookingReceiptLandsAtMs(receipt: BookingReceipt): number {
+    return receipt.lands_at.toMilliseconds()
+}
+
+export function bookingReceiptRuntimeSeconds(receipt: BookingReceipt): number {
+    return Number(receipt.runtime)
+}

package/src/resolution/describe-module.ts

@@ -20,6 +20,7 @@ export interface ModuleDescription {
 export interface RenderDescriptionOptions {
     translate?: (id: string, fallback: string) => string
     formatNumber?: (n: number) => string
+    formatParam?: (paramName: string, value: number, descId: string) => string | undefined
 }
 
 interface TemplateSpec {
@@ -27,6 +28,7 @@ interface TemplateSpec {
     template: string
     params: readonly [string, string][]
     highlightKeys: readonly string[]
+    derive?: Record<string, (get: (label: string) => number) => number>
 }
 
 const TEMPLATES: Record<string, TemplateSpec> = {
@@ -53,43 +55,48 @@ const TEMPLATES: Record<string, TemplateSpec> = {
     gatherer: {
         id: 'module.gatherer.description',
         template:
-            'mines resources at {yield} speed to a max depth of {depth} with {speed} gather speed while draining {drain} energy per second',
+            'mines resources at {yield} yield to a max depth of {depth} while draining {drain} energy per minute',
         params: [
             ['yield', 'Yield'],
-            ['drain', 'Drain'],
             ['depth', 'Depth'],
-            ['speed', 'Speed'],
         ],
-        highlightKeys: ['yield', 'depth', 'speed', 'drain'],
+        highlightKeys: ['yield', 'depth', 'drain'],
+        derive: {
+            drain: (get) => Math.round((get('Drain') / 10000) * 60 * 10) / 10,
+        },
     },
-    loader: {
-        id: 'module.loader.description',
-        template:
-            '{quantity} loader that generates {thrust} thrust with a weight of {mass} per unit',
+    loading: {
+        id: 'module.loading.description',
+        template: 'generates {thrust} thrust with a weight of {mass} per unit',
         params: [
-            ['quantity', 'Quantity'],
             ['thrust', 'Thrust'],
             ['mass', 'Mass'],
         ],
-        highlightKeys: ['quantity', 'thrust', 'mass'],
+        highlightKeys: ['thrust', 'mass'],
     },
-    crafter: {
-        id: 'module.crafter.description',
-        template: 'manufactures items at {speed} speed while draining {drain} energy per second',
-        params: [
-            ['speed', 'Speed'],
-            ['drain', 'Drain'],
-        ],
+    crafting: {
+        id: 'module.crafting.description',
+        template: 'manufactures items at {speed} speed while draining {drain} energy per minute',
+        params: [['speed', 'Speed']],
         highlightKeys: ['speed', 'drain'],
+        derive: {
+            drain: (get) => Math.round(((get('Drain') * get('Speed')) / 150000) * 60 * 10) / 10,
+        },
     },
     storage: {
         id: 'module.storage.description',
-        template: 'boosts cargo capacity by {bonus}%',
-        params: [['bonus', 'Capacity Bonus']],
-        highlightKeys: ['bonus'],
+        template: 'adds {capacity} cargo capacity',
+        params: [['capacity', 'Cargo Capacity']],
+        highlightKeys: ['capacity'],
+    },
+    energy: {
+        id: 'module.energy-capacity.description',
+        template: 'adds {capacity} energy capacity',
+        params: [['capacity', 'Energy Capacity']],
+        highlightKeys: ['capacity'],
     },
-    hauler: {
-        id: 'module.hauler.description',
+    hauling: {
+        id: 'module.hauling.description',
         template:
             'locks onto up to {capacity} targets at {efficiency} efficiency while draining {drain} energy per distance travelled per target',
         params: [
@@ -111,6 +118,12 @@ export function describeModule(input: CapabilityInput): ModuleDescription | null
         const attr = input.attributes.find((a) => a.label === attrLabel)
         if (attr) params[paramName] = attr.value
     }
+    if (spec.derive) {
+        const get = (label: string) => input.attributes.find((a) => a.label === label)?.value ?? 0
+        for (const [paramName, fn] of Object.entries(spec.derive)) {
+            params[paramName] = fn(get)
+        }
+    }
     return {
         id: spec.id,
         template: spec.template,
@@ -127,8 +140,10 @@ export function describeModuleForItem(resolved: ResolvedItem): ModuleDescription
 }
 
 export function describeModuleForSlot(slot: ResolvedModuleSlot): ModuleDescription | null {
-    if (!slot.installed || !slot.name || !slot.attributes) return null
-    return describeModule({capability: slot.name, attributes: slot.attributes})
+    if (!slot.installed || !slot.attributes) return null
+    const capability = slot.capability ?? slot.name
+    if (!capability) return null
+    return describeModule({capability, attributes: slot.attributes})
 }
 
 export function renderDescription(
@@ -153,7 +168,10 @@ export function renderDescription(
         if (raw === undefined) {
             spans.push({text: `{${paramName}}`})
         } else {
-            const formatted = typeof raw === 'number' ? formatNumber(raw) : raw
+            const formatted =
+                typeof raw === 'number'
+                    ? (options?.formatParam?.(paramName, raw, desc.id) ?? formatNumber(raw))
+                    : raw
             const highlight = (desc.highlightKeys as readonly string[]).includes(paramName)
             spans.push(highlight ? {text: formatted, highlight: true} : {text: formatted})
         }

package/src/resolution/display-name.ts

@@ -1,28 +1,56 @@
 import type {ResolvedItem} from './resolve-item'
 import type {ResourceCategory} from '../types'
-import {CATEGORY_LABELS, TIER_ADJECTIVES} from '../types'
+import {
+    CATEGORY_LABELS,
+    RESOURCE_TIER_ADJECTIVES,
+    COMPONENT_TIER_PREFIXES,
+    MODULE_TIER_PREFIXES,
+} from '../types'
 import {formatMass as defaultFormatMass} from '../format'
 
-export interface DisplayNameInput {
-    itemType: 'resource' | 'component' | 'module' | 'entity' | string
+interface DisplayNameInputCommon {
     tier: number
     category?: ResourceCategory
     name: string
 }
 
-export function displayName(resolved: DisplayNameInput): string {
-    if (resolved.itemType === 'resource') {
-        const adj = TIER_ADJECTIVES[resolved.tier] ?? 'Unknown'
-        const cat = resolved.category ? CATEGORY_LABELS[resolved.category] : 'Resource'
-        return `${adj} ${cat}`
-    }
-    return resolved.name
+export type DisplayNameInput =
+    | (DisplayNameInputCommon & {itemType: 'resource' | 'component' | 'module' | 'entity' | string})
+    | (DisplayNameInputCommon & {type: string})
+
+function itemTypeOf(item: DisplayNameInput): string {
+    return 'itemType' in item ? item.itemType : item.type
+}
+
+function tierPrefix(item: DisplayNameInput): string | null {
+    const t = itemTypeOf(item)
+    if (t === 'resource') return RESOURCE_TIER_ADJECTIVES[item.tier] ?? null
+    if (t === 'component') return COMPONENT_TIER_PREFIXES[item.tier] ?? null
+    if (t === 'module') return MODULE_TIER_PREFIXES[item.tier] ?? null
+    return null
+}
+
+function rootName(item: DisplayNameInput): string {
+    if (itemTypeOf(item) !== 'resource') return item.name
+    return item.category ? CATEGORY_LABELS[item.category] : 'Resource'
+}
+
+// Tier-free display name: includes the resource tier adjective / component-module
+// prefix, but no "(T#)" suffix. Use this when the tier is shown separately.
+export function baseName(item: DisplayNameInput): string {
+    const prefix = tierPrefix(item)
+    const root = rootName(item)
+    return prefix ? `${prefix} ${root}` : root
+}
+
+export function displayName(item: DisplayNameInput): string {
+    return `${baseName(item)} (T${item.tier})`
 }
 
 export interface DescribeOptions {
     translate?: (key: string) => string
     formatNumber?: (n: number) => string
-    formatMass?: (kg: number) => string
+    formatMass?: (mass: number) => string
 }
 
 export function describeItem(resolved: ResolvedItem, opts?: DescribeOptions): string {