@shipload/item-renderer 0.1.0

package/test/fixtures/cargo-items.ts

@@ -0,0 +1,122 @@
+import { ServerContract } from '@shipload/sdk'
+
+export const ITEM_IRON = 26
+export const ITEM_HELIUM = 2
+export const ITEM_ENGINE_T1 = 10100
+export const ITEM_GENERATOR_T1 = 10101
+export const ITEM_GATHERER_T1 = 10102
+export const ITEM_LOADER_T1 = 10103
+export const ITEM_MANUFACTURING_T1 = 10104
+export const ITEM_STORAGE_T1 = 10105
+export const ITEM_HAULER_T1 = 10106
+export const ITEM_SHIP_T1_PACKED = 10201
+
+export const MODULE_ENGINE = 1
+export const MODULE_GENERATOR = 2
+
+export function cargoIron(stats = '0x123456789ABCDEF', quantity = 1) {
+  return ServerContract.Types.cargo_item.from({
+    item_id: ITEM_IRON,
+    quantity,
+    stats,
+    modules: [],
+  })
+}
+
+export function cargoShipT1Packed(opts?: {
+  stats?: string
+  engineStats?: string
+  generatorStats?: string
+  onlyEngine?: boolean
+}) {
+  const o = opts ?? {}
+  const modules: unknown[] = []
+  modules.push({
+    type: MODULE_ENGINE,
+    installed: { item_id: ITEM_ENGINE_T1, stats: o.engineStats ?? '0x2A4F6B8C' },
+  })
+  if (!o.onlyEngine) {
+    modules.push({
+      type: MODULE_GENERATOR,
+      installed: { item_id: ITEM_GENERATOR_T1, stats: o.generatorStats ?? '0x1B2D4F' },
+    })
+  }
+  return ServerContract.Types.cargo_item.from({
+    item_id: ITEM_SHIP_T1_PACKED,
+    quantity: 1,
+    stats: o.stats ?? '0',
+    modules,
+  })
+}
+
+export const ITEM_HULL_PLATES = 10001
+
+export const FIXTURES = {
+  iron: cargoIron('0x123456789ABCDEF'),
+  ironStackOf50: cargoIron('0x123456789ABCDEF', 50),
+  ironZeroStats: cargoIron('0'),
+  helium: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_HELIUM,
+    quantity: 1,
+    stats: '0xDEADBEEF1234',
+    modules: [],
+  }),
+  hullPlates: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_HULL_PLATES,
+    quantity: 1,
+    stats: '0x7FFF',
+    modules: [],
+  }),
+  engineT1: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_ENGINE_T1,
+    quantity: 1,
+    stats: '358800',
+    modules: [],
+  }),
+  generatorT1: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_GENERATOR_T1,
+    quantity: 1,
+    stats: '683908',
+    modules: [],
+  }),
+  gathererT1: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_GATHERER_T1,
+    quantity: 1,
+    stats: '138255128433040',
+    modules: [],
+  }),
+  loaderT1: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_LOADER_T1,
+    quantity: 1,
+    stats: '512750',
+    modules: [],
+  }),
+  crafterT1: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_MANUFACTURING_T1,
+    quantity: 1,
+    stats: '512600',
+    modules: [],
+  }),
+  storageT1: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_STORAGE_T1,
+    quantity: 1,
+    stats: '537605632700',
+    modules: [],
+  }),
+  haulerT1: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_HAULER_T1,
+    quantity: 1,
+    stats: '0x3E8',
+    modules: [],
+  }),
+  shipT1NoModules: ServerContract.Types.cargo_item.from({
+    item_id: ITEM_SHIP_T1_PACKED,
+    quantity: 1,
+    stats: '0',
+    modules: [],
+  }),
+  shipT1TwoModules: cargoShipT1Packed(),
+  shipT1OnlyEngine: cargoShipT1Packed({ onlyEngine: true }),
+} as const
+
+export type FixtureName = keyof typeof FIXTURES

package/test/fonts.test.ts

@@ -0,0 +1,28 @@
+import { expect, test } from 'bun:test'
+import { embedFontsInSvg } from '../src/fonts/index.ts'
+import { loadFontData } from '../src/fonts/load-bun.ts'
+
+test('loadFontData returns all four faces with non-zero bytes', async () => {
+  const data = await loadFontData()
+  expect(Object.keys(data).sort()).toEqual([
+    'inter-400',
+    'inter-600',
+    'jetbrains-500',
+    'orbitron-700',
+  ])
+  for (const [key, bytes] of Object.entries(data)) {
+    expect(bytes.byteLength, `${key} bytes`).toBeGreaterThan(2000)
+    expect(bytes.byteLength, `${key} bytes`).toBeLessThan(120_000)
+  }
+})
+
+test('embedFontsInSvg inlines @font-face blocks', async () => {
+  const data = await loadFontData()
+  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"></svg>'
+  const out = embedFontsInSvg(svg, data)
+  expect(out).toContain('@font-face')
+  expect(out).toContain('font-family: "Orbitron"')
+  expect(out).toContain('font-family: "Inter"')
+  expect(out).toContain('font-family: "JetBrains Mono"')
+  expect(out).toContain('data:font/woff2;base64,')
+})

package/test/links-meta.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from 'bun:test'
+import { resolveItem } from '@shipload/sdk'
+import { linkToItemImage, linkToItemPage } from '../src/links.ts'
+import { itemPageMeta } from '../src/meta.ts'
+import { FIXTURES } from './fixtures/cargo-items.ts'
+
+test('linkToItemPage defaults to shiploadgame.com', () => {
+  const url = linkToItemPage(FIXTURES.iron)
+  expect(url).toMatch(/^https:\/\/shiploadgame\.com\/guide\/item\/[A-Za-z0-9_-]+$/)
+})
+
+test('linkToItemPage accepts a custom base URL', () => {
+  const url = linkToItemPage(FIXTURES.iron, 'http://localhost:5173')
+  expect(url.startsWith('http://localhost:5173/guide/item/')).toBe(true)
+})
+
+test('linkToItemImage builds a PNG URL', () => {
+  const url = linkToItemImage(FIXTURES.iron, 'png')
+  expect(url).toMatch(/^https:\/\/img\.shiploadgame\.com\/item\/[A-Za-z0-9_-]+\.png$/)
+})
+
+test('linkToItemImage builds an SVG URL', () => {
+  const url = linkToItemImage(FIXTURES.iron, 'svg')
+  expect(url).toMatch(/\.svg$/)
+})
+
+test('itemPageMeta produces title, description, and ogImage', () => {
+  const item = FIXTURES.iron
+  const resolved = resolveItem(item.item_id, item.stats, item.modules)
+  const meta = itemPageMeta(item, resolved)
+  expect(meta.title).toContain('Iron')
+  expect(meta.description.length).toBeGreaterThan(0)
+  expect(meta.ogImage).toMatch(/^https:\/\/img\.shiploadgame\.com\/item\/[A-Za-z0-9_-]+\.png$/)
+})

package/test/pixel.test.ts

@@ -0,0 +1,66 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { expect, test } from 'bun:test'
+import { Resvg } from '@resvg/resvg-js'
+import pixelmatch from 'pixelmatch'
+import { PNG } from 'pngjs'
+import { resolveItem } from '@shipload/sdk'
+import { renderItem } from '../src/render.ts'
+import { embedFontsInSvg } from '../src/fonts/index.ts'
+import { loadFontData } from '../src/fonts/load-bun.ts'
+import { FIXTURES } from './fixtures/cargo-items.ts'
+
+const SNAP_DIR = resolve(import.meta.dir, '__image_snapshots__')
+const UPDATE = process.env.UPDATE_IMAGE_SNAPSHOTS === '1'
+
+await mkdir(SNAP_DIR, { recursive: true })
+const fontData = await loadFontData()
+
+async function renderPng(svg: string): Promise<Buffer> {
+  const resvg = new Resvg(svg, {
+    font: { loadSystemFonts: false, fontBuffers: Object.values(fontData).map((b) => Buffer.from(b)) },
+  })
+  return resvg.render().asPng()
+}
+
+const CASES = [
+  { name: 'resource-iron', fixture: FIXTURES.iron },
+  { name: 'packed-entity-ship-t1-two-modules', fixture: FIXTURES.shipT1TwoModules },
+  { name: 'packed-entity-ship-t1-only-engine', fixture: FIXTURES.shipT1OnlyEngine },
+  { name: 'component-hull-plates', fixture: FIXTURES.hullPlates },
+  { name: 'module-engine-t1', fixture: FIXTURES.engineT1 },
+  { name: 'module-storage-t1', fixture: FIXTURES.storageT1 },
+] as const
+
+for (const c of CASES) {
+  test(`pixel golden — ${c.name}`, async () => {
+    const resolved = resolveItem(c.fixture.item_id, c.fixture.stats, c.fixture.modules)
+    const svg = embedFontsInSvg(renderItem(c.fixture, resolved), fontData)
+    const png = await renderPng(svg)
+    const goldPath = resolve(SNAP_DIR, `${c.name}.png`)
+
+    if (UPDATE || !existsSync(goldPath)) {
+      await writeFile(goldPath, png)
+      return
+    }
+
+    const actual = PNG.sync.read(png)
+    const expected = PNG.sync.read(await readFile(goldPath))
+    expect(actual.width).toBe(expected.width)
+    expect(actual.height).toBe(expected.height)
+    const diff = new PNG({ width: actual.width, height: actual.height })
+    const diffCount = pixelmatch(
+      actual.data,
+      expected.data,
+      diff.data,
+      actual.width,
+      actual.height,
+      { threshold: 0.1 },
+    )
+    if (diffCount > 10) {
+      await writeFile(resolve(SNAP_DIR, `${c.name}.diff.png`), PNG.sync.write(diff))
+    }
+    expect(diffCount).toBeLessThanOrEqual(10)
+  })
+}

package/test/primitives-category-icon.test.ts

@@ -0,0 +1,79 @@
+import { test, expect } from 'bun:test'
+import { categoryIconSvg, categoryIconPath } from '../src/primitives/category-icon.ts'
+
+test('categoryIconSvg returns self-contained <svg> for each shape', () => {
+  for (const shape of ['hex', 'diamond', 'star', 'circle', 'square'] as const) {
+    const svg = categoryIconSvg(shape)
+    expect(svg.startsWith('<svg ')).toBe(true)
+    expect(svg.endsWith('</svg>')).toBe(true)
+    expect(svg).toContain('viewBox=')
+  }
+})
+
+test('categoryIconSvg respects size option', () => {
+  const svg = categoryIconSvg('hex', { size: 24 })
+  expect(svg).toContain('width="24"')
+  expect(svg).toContain('height="24"')
+  expect(svg).toContain('viewBox="0 0 24 24"')
+})
+
+test('categoryIconSvg respects color option', () => {
+  const svg = categoryIconSvg('hex', { color: '#ff0000' })
+  expect(svg).toContain('#ff0000')
+})
+
+test('categoryIconPath returns inline element at given coordinates without svg wrapper', () => {
+  const path = categoryIconPath({ shape: 'diamond', cx: 50, cy: 50, size: 20, color: '#00ff00' })
+  expect(path.startsWith('<svg')).toBe(false)
+  expect(path).toMatch(/^<(polygon|rect|circle)\b/)
+  expect(path).toContain('#00ff00')
+})
+
+test('hex shape produces a 6-point polygon', () => {
+  const path = categoryIconPath({ shape: 'hex', cx: 50, cy: 50, size: 40, color: '#fff' })
+  expect(path).toContain('<polygon')
+  const match = path.match(/points="([^"]+)"/)
+  expect(match).not.toBeNull()
+  const pointCount = match![1].trim().split(/\s+/).length
+  expect(pointCount).toBe(6)
+})
+
+test('star shape produces a 10-vertex polygon', () => {
+  const path = categoryIconPath({ shape: 'star', cx: 50, cy: 50, size: 40, color: '#fff' })
+  const match = path.match(/points="([^"]+)"/)
+  expect(match).not.toBeNull()
+  const pointCount = match![1].trim().split(/\s+/).length
+  expect(pointCount).toBe(10)
+})
+
+test('circle shape produces a <circle> element', () => {
+  const path = categoryIconPath({ shape: 'circle', cx: 50, cy: 50, size: 40, color: '#abc' })
+  expect(path).toMatch(/^<circle\b/)
+  expect(path).toContain('cx="50"')
+  expect(path).toContain('cy="50"')
+  expect(path).toContain('r="20"')
+})
+
+test('square shape produces a <rect> element', () => {
+  const path = categoryIconPath({ shape: 'square', cx: 50, cy: 50, size: 40, color: '#abc' })
+  expect(path).toMatch(/^<rect\b/)
+  expect(path).toContain('width="40"')
+  expect(path).toContain('height="40"')
+  expect(path).toContain('x="30"')
+  expect(path).toContain('y="30"')
+})
+
+test('strokeWidth renders outline mode: fill=none, stroke=color', () => {
+  for (const shape of ['hex', 'diamond', 'star', 'circle', 'square'] as const) {
+    const path = categoryIconPath({ shape, cx: 50, cy: 50, size: 40, color: '#ff0000', strokeWidth: 2 })
+    expect(path).toContain('fill="none"')
+    expect(path).toContain('stroke="#ff0000"')
+    expect(path).toContain('stroke-width="2"')
+  }
+})
+
+test('fill mode (no strokeWidth) does not produce stroke attributes', () => {
+  const path = categoryIconPath({ shape: 'hex', cx: 50, cy: 50, size: 40, color: '#ff0000' })
+  expect(path).toContain('fill="#ff0000"')
+  expect(path).not.toContain('stroke=')
+})

package/test/primitives-compact-row.test.ts

@@ -0,0 +1,44 @@
+import { test, expect } from 'bun:test'
+import { compactRow } from '../src/primitives/compact-row.ts'
+
+test('compactRow emits left-anchored label and right-anchored value', () => {
+  const svg = compactRow({
+    x: 14,
+    y: 80,
+    width: 252,
+    label: 'Thrust',
+    value: '700',
+  })
+  expect(svg).toContain('<text')
+  expect(svg).toContain('Thrust')
+  expect(svg).toContain('700')
+  expect(svg).toContain('x="14"')
+  expect(svg).toContain('x="266"')
+  expect(svg).toContain('text-anchor="end"')
+})
+
+test('compactRow applies supplied label and value colors', () => {
+  const svg = compactRow({
+    x: 14,
+    y: 80,
+    width: 252,
+    label: 'Drain',
+    value: '50',
+    labelColor: '#aabbcc',
+    valueColor: '#ddeeff',
+  })
+  expect(svg).toContain('fill="#aabbcc"')
+  expect(svg).toContain('fill="#ddeeff"')
+})
+
+test('compactRow escapes HTML entities in label and value', () => {
+  const svg = compactRow({
+    x: 14,
+    y: 80,
+    width: 252,
+    label: 'A & B',
+    value: '<5',
+  })
+  expect(svg).toContain('A &amp; B')
+  expect(svg).toContain('&lt;5')
+})

package/test/primitives-domain.test.ts

@@ -0,0 +1,72 @@
+import { expect, test } from 'bun:test'
+import { iconHex } from '../src/primitives/icon-hex.ts'
+import { statBar } from '../src/primitives/stat-bar.ts'
+import { moduleSlot } from '../src/primitives/module-slot.ts'
+import { quantityBadge } from '../src/primitives/quantity-badge.ts'
+
+test('iconHex draws a hexagon with the category color and 2-char code', () => {
+  const svg = iconHex({ x: 14, y: 14, color: '#58d08c', code: 'FE' })
+  expect(svg).toContain('<polygon')
+  expect(svg).toContain('stroke="#58d08c"')
+  expect(svg).toContain('>FE<')
+})
+
+test('statBar emits a labeled bar with value ∈ [0, 1023]', () => {
+  const svg = statBar({
+    x: 14,
+    y: 100,
+    width: 252,
+    label: 'Strength',
+    abbreviation: 'STR',
+    value: 342,
+    color: '#58d08c',
+  })
+  expect(svg).toContain('STR')
+  expect(svg).toContain('Strength')
+  expect(svg).toContain('342')
+  // Fill width proportional to value/1023:
+  // expected filled width ≈ 252 * 342 / 1023 ≈ 84.2
+  expect(svg).toContain('width="84"')
+})
+
+test('statBar inverts the visual fill when inverted is true', () => {
+  const hi = statBar({
+    x: 0, y: 0, width: 100, label: 'X', abbreviation: 'X',
+    value: 900, color: '#fff',
+  })
+  const lo = statBar({
+    x: 0, y: 0, width: 100, label: 'X', abbreviation: 'X',
+    value: 900, color: '#fff', inverted: true,
+  })
+  expect(hi).not.toBe(lo)
+})
+
+test('moduleSlot renders an empty state with "Empty module" label', () => {
+  const svg = moduleSlot({ x: 14, y: 200, width: 252, installed: false })
+  expect(svg).toContain('Empty module')
+})
+
+test('moduleSlot renders an installed state with capability description', () => {
+  const svg = moduleSlot({
+    x: 14,
+    y: 200,
+    width: 252,
+    installed: true,
+    capability: 'Engine',
+    description: 'generates 757 thrust for travel while draining 41 energy per distance travelled',
+    accentColor: '#58d08c',
+  })
+  expect(svg).toContain('Engine')
+  expect(svg).toContain('757')
+  expect(svg).toContain('thrust')
+})
+
+test('quantityBadge is empty string when quantity <= 1', () => {
+  expect(quantityBadge({ x: 0, y: 0, quantity: 1 })).toBe('')
+  expect(quantityBadge({ x: 0, y: 0, quantity: 0 })).toBe('')
+})
+
+test('quantityBadge renders ×N chip when quantity > 1', () => {
+  const svg = quantityBadge({ x: 250, y: 8, quantity: 50 })
+  expect(svg).toContain('×50')
+})

package/test/primitives-layout.test.ts

@@ -0,0 +1,56 @@
+import { expect, test } from 'bun:test'
+import { panel } from '../src/primitives/panel.ts'
+import { text } from '../src/primitives/text.ts'
+import { divider } from '../src/primitives/divider.ts'
+import { wrapText } from '../src/primitives/wrap.ts'
+
+test('panel renders a rect inset by 0.5px so the 1px stroke stays inside the viewBox', () => {
+  const svg = panel({ width: 280, height: 120 })
+  expect(svg).toContain('<rect')
+  expect(svg).toContain('x="0.5"')
+  expect(svg).toContain('y="0.5"')
+  expect(svg).toContain('width="279"')
+  expect(svg).toContain('height="119"')
+  expect(svg).toContain('rx="10"')
+})
+
+test('panel accepts an optional tier border color', () => {
+  const svg = panel({ width: 280, height: 120, borderColor: '#6cb9ff' })
+  expect(svg).toContain('stroke="#6cb9ff"')
+})
+
+test('text emits a <text> element with escaped content', () => {
+  const svg = text({ x: 10, y: 20, value: `Ship "T1"`, size: 14, weight: 600 })
+  expect(svg).toContain('<text')
+  expect(svg).toContain('x="10"')
+  expect(svg).toContain('y="20"')
+  expect(svg).toContain('Ship &quot;T1&quot;')
+  expect(svg).toContain('font-size="14"')
+  expect(svg).toContain('font-weight="600"')
+})
+
+test('divider is a horizontal line at y', () => {
+  const svg = divider({ x: 14, y: 40, width: 252 })
+  expect(svg).toContain('<line')
+  expect(svg).toContain('x1="14"')
+  expect(svg).toContain('x2="266"')
+  expect(svg).toContain('y1="40"')
+  expect(svg).toContain('y2="40"')
+})
+
+test('wrapText splits a string into lines that fit within a char budget', () => {
+  const lines = wrapText({
+    value: 'generates 757 thrust for travel while draining 41 energy per distance travelled',
+    charsPerLine: 40,
+  })
+  for (const line of lines) expect(line.length).toBeLessThanOrEqual(40)
+  // No word is broken mid-word:
+  expect(lines.join(' ')).toBe(
+    'generates 757 thrust for travel while draining 41 energy per distance travelled',
+  )
+})
+
+test('wrapText preserves a single unbreakable long token', () => {
+  const lines = wrapText({ value: 'supercalifragilisticexpialidocious', charsPerLine: 10 })
+  expect(lines).toEqual(['supercalifragilisticexpialidocious'])
+})

package/test/primitives-module-slot.test.ts

@@ -0,0 +1,88 @@
+import { test, expect } from 'bun:test'
+import { moduleSlot } from '../src/primitives/module-slot.ts'
+import type { TextSpan } from '@shipload/sdk'
+
+test('string description flows inline with the bold capability label', () => {
+  const svg = moduleSlot({
+    x: 14,
+    y: 40,
+    width: 252,
+    installed: true,
+    capability: 'Engine',
+    description: 'generates 700 thrust for travel',
+    accentColor: '#2fd6d1',
+  })
+  expect(svg).toContain('<polygon')
+  expect(svg).toContain('Engine: ')
+  expect(svg).toContain('font-weight="600"')
+  expect(svg).toContain('generates 700 thrust for')
+})
+
+test('TextSpan[] description renders each span; highlighted spans get accent color', () => {
+  const spans: TextSpan[] = [
+    { text: 'generates ' },
+    { text: '700', highlight: true },
+    { text: ' thrust for travel while draining ' },
+    { text: '45', highlight: true },
+    { text: ' energy per distance travelled' },
+  ]
+  const svg = moduleSlot({
+    x: 14,
+    y: 40,
+    width: 252,
+    installed: true,
+    capability: 'Engine',
+    description: spans,
+    accentColor: '#2fd6d1',
+  })
+  expect(svg).toContain('Engine:')
+  expect(svg).toContain('>generates <')
+  expect(svg).toContain('>700<')
+  expect(svg).toContain('>45<')
+  expect(svg).toMatch(/fill="#[0-9A-Fa-f]{6}"[^>]*>700</)
+})
+
+test('TextSpan[] description wraps across lines preserving highlight boundaries', () => {
+  const spans: TextSpan[] = [
+    { text: 'mines resources at ' },
+    { text: '880', highlight: true },
+    { text: ' speed to a max depth of ' },
+    { text: '248', highlight: true },
+    { text: ' with ' },
+    { text: '100', highlight: true },
+    { text: ' gather speed while draining ' },
+    { text: '1,250', highlight: true },
+    { text: ' energy per second' },
+  ]
+  const svg = moduleSlot({
+    x: 14,
+    y: 40,
+    width: 252,
+    installed: true,
+    capability: 'Gatherer',
+    description: spans,
+    accentColor: '#f59e0b',
+  })
+  expect(svg).toContain('880')
+  expect(svg).toContain('248')
+  expect(svg).toContain('100')
+  expect(svg).toContain('1,250')
+})
+
+test('Empty description array renders headline only', () => {
+  const svg = moduleSlot({
+    x: 14,
+    y: 40,
+    width: 252,
+    installed: true,
+    capability: 'Engine',
+    description: [],
+    accentColor: '#2fd6d1',
+  })
+  expect(svg).toContain('Engine:')
+})
+
+test('Empty slot renders unchanged', () => {
+  const svg = moduleSlot({ x: 14, y: 40, width: 252, installed: false })
+  expect(svg).toContain('Empty module')
+})

package/test/render.test.ts

@@ -0,0 +1,40 @@
+import { expect, test } from 'bun:test'
+import { resolveItem } from '@shipload/sdk'
+import { renderItem, renderFromPayload } from '../src/render.ts'
+import { RenderError } from '../src/errors.ts'
+import { encodePayload } from '../src/payload/codec.ts'
+import { FIXTURES } from './fixtures/cargo-items.ts'
+
+test('renderItem dispatches to resource template for resources', () => {
+  const item = FIXTURES.iron
+  const resolved = resolveItem(item.item_id, item.stats, item.modules)
+  const svg = renderItem(item, resolved)
+  expect(svg).toContain('Iron')
+})
+
+test('renderItem dispatches to packed entity template for entities', () => {
+  const item = FIXTURES.shipT1TwoModules
+  const resolved = resolveItem(item.item_id, item.stats, item.modules)
+  const svg = renderItem(item, resolved)
+  expect(svg).toContain('HULL')
+})
+
+test('renderItem dispatches to module template for modules', () => {
+  const item = FIXTURES.engineT1
+  const resolved = resolveItem(item.item_id, item.stats, item.modules)
+  const svg = renderItem(item, resolved)
+  expect(svg).toContain('MODULE')
+})
+
+test('renderItem throws RenderError for unknown types', () => {
+  const item = FIXTURES.iron
+  const fake = { ...resolveItem(item.item_id, item.stats, item.modules), itemType: 'unknown' as never }
+  expect(() => renderItem(item, fake)).toThrow(RenderError)
+})
+
+test('renderFromPayload round-trips a payload into SVG', async () => {
+  const payload = encodePayload(FIXTURES.iron)
+  const { svg, item } = await renderFromPayload(payload)
+  expect(svg).toContain('Iron')
+  expect(item.itemType).toBe('resource')
+})

package/test/sanity.test.ts

@@ -0,0 +1,6 @@
+import { expect, test } from 'bun:test'
+import { VERSION } from '../src/index.ts'
+
+test('VERSION is a semver string', () => {
+  expect(VERSION).toMatch(/^\d+\.\d+\.\d+$/)
+})

package/test/sdk-link.test.ts

@@ -0,0 +1,19 @@
+import { expect, test } from 'bun:test'
+import { resolveItem, ServerContract, type ResolvedItem } from '@shipload/sdk'
+
+test('sdkv2 is linked and exposes resolveItem + ResolvedItem type', () => {
+  const resolved: ResolvedItem = resolveItem(26 /* Iron */, undefined, undefined)
+  expect(resolved.itemId).toBe(26)
+  expect(resolved.name).toBe('Iron')
+  expect(resolved.itemType).toBe('resource')
+})
+
+test('ServerContract.Types.cargo_item can be constructed', () => {
+  const ci = ServerContract.Types.cargo_item.from({
+    item_id: 26,
+    quantity: 1,
+    stats: '0',
+    modules: [],
+  })
+  expect(ci.item_id.equals(26)).toBe(true)
+})