@shipload/item-renderer 1.0.0-next.3 → 1.0.0-next.30

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@shipload/item-renderer",
-    "version": "1.0.0-next.3",
+    "version": "1.0.0-next.30",
     "description": "Deterministic SVG rendering for Shipload items",
     "homepage": "https://github.com/shipload/toolkit/tree/master/packages/item-renderer",
     "repository": {
@@ -45,7 +45,7 @@
         "fonts:copy": "bun run scripts/copy-fonts.ts"
     },
     "dependencies": {
-        "@shipload/sdk": "workspace:^",
+        "@shipload/sdk": "^1.0.0-next.30",
         "@wharfkit/antelope": "1.2.0"
     },
     "devDependencies": {

package/src/index.ts

@@ -5,8 +5,18 @@ export const VERSION = '0.1.0'
 export {InvalidPayloadError, UnknownItemError, RenderError} from './errors.ts'
 
 // Payload
-export {encodePayload, decodePayload} from './payload/codec.ts'
-export type {CargoItem, CargoItemLike} from './payload/codec.ts'
+export {
+    encodeCargoItem,
+    decodeCargoItem,
+    encodeNftPayload,
+    decodeNftPayload,
+} from './payload/codec.ts'
+export type {
+    CargoItem,
+    CargoItemLike,
+    NftItemPayload,
+    NftItemPayloadLike,
+} from './payload/codec.ts'
 
 // Rendering
 export {renderItem, renderFromPayload, type RenderOptions} from './render.ts'
@@ -17,17 +27,22 @@ export {linkToItemPage, linkToItemImage, linkToItemSocial} from './links.ts'
 export {itemPageMeta, svgDimensions} from './meta.ts'
 export type {ItemPageMeta, ItemPageMetaOptions} from './meta.ts'
 
-// Tokens (consumed by testmap tailwind.config)
+// Tokens (consumed by webapp tailwind.config)
 export {tokens} from './tokens/index.ts'
 export type {Tokens} from './tokens/index.ts'
 export type {CategoryColorKey, TierColorKey} from './tokens/colors.ts'
 
-// Category icon primitive
-export {categoryIconSvg, categoryIconPath} from './primitives/category-icon.ts'
-export type {CategoryIconPathOpts, CategoryIconSvgOpts} from './primitives/category-icon.ts'
+// Resource icon primitive
+export {
+    resourceIcon,
+    resourceIconBody,
+    resourceIconCategories,
+    resourceIconSvg,
+} from './primitives/resource-icon.ts'
+export type {ResourceIconInlineOpts, ResourceIconSvgOpts} from './primitives/resource-icon.ts'
 
 // Item cell templates
-export {renderItemCell, itemCellGroup} from './templates/item-cell.ts'
+export {renderItemCell, itemCellGroup, abbreviateQuantity} from './templates/item-cell.ts'
 export type {ItemCellProps, ItemCellGroupProps} from './templates/item-cell.ts'
 
 // Social card template (1200x630 OG image)
@@ -51,4 +66,3 @@ export {
     type ResolvedModuleSlot,
     type ResolvedAttributeGroup,
 } from '@shipload/sdk'
-export type {CategoryIconShape} from '@shipload/sdk'

package/src/links.ts

@@ -1,24 +1,27 @@
 import type {CargoItem} from './payload/codec.ts'
-import {encodePayload} from './payload/codec.ts'
+import {encodeCargoItem, encodeNftPayload} from './payload/codec.ts'
 
 const DEFAULT_WEBSITE_BASE = 'https://shiploadgame.com'
 const DEFAULT_IMAGE_BASE = 'https://item.shiploadgame.com'
 
 export function linkToItemPage(item: CargoItem, baseUrl = DEFAULT_WEBSITE_BASE): string {
-    const payload = encodePayload(item)
+    const payload = encodeCargoItem(item)
     return `${baseUrl}/guide/item/${payload}`
 }
 
 export function linkToItemImage(
     item: CargoItem,
     ext: 'png' | 'svg',
-    baseUrl = DEFAULT_IMAGE_BASE
+    opts?: {location?: {x: number | bigint; y: number | bigint}; baseUrl?: string}
 ): string {
-    const payload = encodePayload(item)
-    return `${baseUrl}/item/${payload}.${ext}`
+    const payload = encodeNftPayload({item, location: opts?.location ?? null})
+    return `${opts?.baseUrl ?? DEFAULT_IMAGE_BASE}/item/${payload}.${ext}`
 }
 
-export function linkToItemSocial(item: CargoItem, baseUrl = DEFAULT_IMAGE_BASE): string {
-    const payload = encodePayload(item)
-    return `${baseUrl}/social/${payload}.png`
+export function linkToItemSocial(
+    item: CargoItem,
+    opts?: {location?: {x: number | bigint; y: number | bigint}; baseUrl?: string}
+): string {
+    const payload = encodeNftPayload({item, location: opts?.location ?? null})
+    return `${opts?.baseUrl ?? DEFAULT_IMAGE_BASE}/social/${payload}.png`
 }

package/src/meta.ts

@@ -32,7 +32,7 @@ export function itemPageMeta(
     return {
         title: `${displayName(resolved)} · Shipload Guide`,
         description: describeItem(resolved),
-        ogImage: linkToItemSocial(item, opts?.imageBaseUrl),
+        ogImage: linkToItemSocial(item, {baseUrl: opts?.imageBaseUrl}),
         ogImageWidth: SOCIAL_CARD_WIDTH,
         ogImageHeight: SOCIAL_CARD_HEIGHT,
     }

package/src/payload/codec.ts

@@ -6,13 +6,16 @@ import {base64UrlToBytes, bytesToBase64Url} from './base64url.ts'
 export type CargoItem = InstanceType<typeof ServerContract.Types.cargo_item>
 export type CargoItemLike = Parameters<typeof ServerContract.Types.cargo_item.from>[0]
 
-export function encodePayload(input: CargoItemLike): string {
+export type NftItemPayload = InstanceType<typeof ServerContract.Types.nft_item_payload>
+export type NftItemPayloadLike = Parameters<typeof ServerContract.Types.nft_item_payload.from>[0]
+
+export function encodeCargoItem(input: CargoItemLike): string {
     const item = ServerContract.Types.cargo_item.from(input)
     const bytes = Serializer.encode({object: item}).array
     return bytesToBase64Url(bytes)
 }
 
-export function decodePayload(input: string): CargoItem {
+export function decodeCargoItem(input: string): CargoItem {
     if (input.length === 0) throw new InvalidPayloadError('empty payload')
     const bytes = base64UrlToBytes(input)
     try {
@@ -24,3 +27,22 @@ export function decodePayload(input: string): CargoItem {
         throw new InvalidPayloadError(`cargo_item decode failed: ${(e as Error).message}`)
     }
 }
+
+export function encodeNftPayload(input: NftItemPayloadLike): string {
+    const payload = ServerContract.Types.nft_item_payload.from(input)
+    const bytes = Serializer.encode({object: payload}).array
+    return bytesToBase64Url(bytes)
+}
+
+export function decodeNftPayload(input: string): NftItemPayload {
+    if (input.length === 0) throw new InvalidPayloadError('empty payload')
+    const bytes = base64UrlToBytes(input)
+    try {
+        return Serializer.decode({
+            data: bytes,
+            type: ServerContract.Types.nft_item_payload,
+        }) as NftItemPayload
+    } catch (e) {
+        throw new InvalidPayloadError(`nft_item_payload decode failed: ${(e as Error).message}`)
+    }
+}

package/src/primitives/module-slot.ts

@@ -71,7 +71,7 @@ export function moduleSlot(props: ModuleSlotProps): string {
         )
     }
 
-    const accent = props.accentColor ?? tokens.colors.text.accent
+    const accent = props.accentColor ?? tokens.colors.accent.component
     const label = `${props.capability ?? 'Module'}: `
 
     const desc = props.description
@@ -89,7 +89,7 @@ export function moduleSlot(props: ModuleSlotProps): string {
                 value: label.trimEnd(),
                 size: tokens.typography.sizes.body,
                 weight: 600,
-                color: tokens.colors.text.primary,
+                color: accent,
             })
         )
     }
@@ -99,9 +99,9 @@ export function moduleSlot(props: ModuleSlotProps): string {
     const combined = label + descPlain
     const lines = wrapText({value: combined, charsPerLine: 36})
 
-    const highlightColor = tokens.colors.text.accent
+    const highlightColor = tokens.colors.text.primary
     const bodyColor = tokens.colors.text.secondary
-    const labelColor = tokens.colors.text.primary
+    const labelColor = accent
     const size = tokens.typography.sizes.body
     const fontFamily = escapeXml(tokens.typography.sans)
     const labelEnd = label.length

package/src/primitives/quantity-badge.ts

@@ -6,11 +6,19 @@ export interface QuantityBadgeProps {
     x: number
     y: number
     quantity: number
+    label?: string
+    tone: string
 }
 
-export function quantityBadge({x, y, quantity}: QuantityBadgeProps): string {
-    if (quantity <= 1) return ''
-    const label = `×${quantity}`
+export function quantityBadge({
+    x,
+    y,
+    quantity,
+    label: labelOverride,
+    tone,
+}: QuantityBadgeProps): string {
+    if (quantity <= 0) return ''
+    const label = labelOverride ?? `×${quantity}`
     const w = label.length * 7 + 12
     const h = tokens.spacing.quantityBadgeHeight
     return (
@@ -21,7 +29,9 @@ export function quantityBadge({x, y, quantity}: QuantityBadgeProps): string {
             height: h,
             rx: h / 2,
             ry: h / 2,
-            fill: tokens.colors.text.accent,
+            fill: tokens.colors.surface.panel,
+            stroke: tone,
+            'stroke-width': 1.5,
         }) +
         text({
             x: x - w / 2,
@@ -30,7 +40,7 @@ export function quantityBadge({x, y, quantity}: QuantityBadgeProps): string {
             size: tokens.typography.sizes.label,
             weight: 700,
             family: tokens.typography.mono,
-            color: tokens.colors.surface.background,
+            color: tokens.colors.text.primary,
             anchor: 'middle',
         })
     )

package/src/primitives/resource-icon.ts

@@ -0,0 +1,242 @@
+import {CATEGORY_LABELS, categoryColors, type ResourceCategory} from '@shipload/sdk'
+import {el, escapeXml} from './svg.ts'
+
+export const resourceIconCategories = [
+    'ore',
+    'crystal',
+    'gas',
+    'regolith',
+    'biomass',
+] as const satisfies readonly ResourceCategory[]
+
+export interface ResourceIconSvgOpts {
+    size?: number
+    title?: string
+    className?: string
+}
+
+export interface ResourceIconInlineOpts {
+    x: number
+    y: number
+    size: number
+}
+
+const OUTLINE = '#06142f'
+const HILITE = '#f7fbff'
+const OUTER_STROKE = 4
+const DETAIL_STROKE = 2.5
+
+function oreIcon(): string {
+    return [
+        el('path', {
+            d: 'M13 24 L25 11 L43 13 L55 27 L48 49 L27 56 L12 42 Z',
+            fill: categoryColors.ore,
+            stroke: OUTLINE,
+            'stroke-width': OUTER_STROKE,
+            'stroke-linejoin': 'round',
+        }),
+        el('path', {d: 'M25 11 L31 30 L13 24 Z', fill: '#e39a5e'}),
+        el('path', {d: 'M31 30 L43 13 L55 27 L41 32 Z', fill: '#b85b35'}),
+        el('path', {d: 'M31 30 L41 32 L48 49 L27 56 Z', fill: '#8f432e'}),
+        el('path', {
+            d: 'M31 30 L25 11 M31 30 L13 24 M31 30 L41 32 M41 32 L48 49 M31 30 L27 56',
+            fill: 'none',
+            stroke: OUTLINE,
+            'stroke-width': 1.5,
+            'stroke-linecap': 'round',
+            'stroke-linejoin': 'round',
+            opacity: 0.28,
+        }),
+        el('path', {
+            d: 'M21 23 L27 18 M42 20 L48 27',
+            fill: 'none',
+            stroke: '#ffd29c',
+            'stroke-width': DETAIL_STROKE,
+            'stroke-linecap': 'round',
+            opacity: 0.72,
+        }),
+    ].join('')
+}
+
+function crystalIcon(): string {
+    return [
+        el('path', {
+            d: 'M32 6 L49 24 L39 58 L23 58 L14 25 Z',
+            fill: categoryColors.crystal,
+            stroke: OUTLINE,
+            'stroke-width': OUTER_STROKE,
+            'stroke-linejoin': 'round',
+        }),
+        el('path', {d: 'M32 6 L32 58 L14 25 Z', fill: '#1fb9e4'}),
+        el('path', {d: 'M32 6 L49 24 L32 58 Z', fill: '#8df0ff'}),
+        el('path', {d: 'M23 58 L32 32 L39 58 Z', fill: '#2f87d7', opacity: 0.72}),
+        el('path', {
+            d: 'M32 6 L32 58 M14 25 L32 32 L49 24 M23 58 L32 32 L39 58',
+            fill: 'none',
+            stroke: OUTLINE,
+            'stroke-width': 1.5,
+            'stroke-linecap': 'round',
+            'stroke-linejoin': 'round',
+            opacity: 0.25,
+        }),
+        el('path', {
+            d: 'M25 20 L31 13 M38 19 L43 25',
+            fill: 'none',
+            stroke: HILITE,
+            'stroke-width': DETAIL_STROKE,
+            'stroke-linecap': 'round',
+            opacity: 0.78,
+        }),
+    ].join('')
+}
+
+function gasIcon(): string {
+    return [
+        el('circle', {
+            cx: 32,
+            cy: 32,
+            r: 23,
+            fill: categoryColors.gas,
+            stroke: OUTLINE,
+            'stroke-width': OUTER_STROKE,
+        }),
+        el('path', {
+            d: 'M17 33 C21 20 38 18 44 27 C51 38 37 51 25 43',
+            fill: 'none',
+            stroke: '#7a48d9',
+            'stroke-width': 7.5,
+            'stroke-linecap': 'round',
+        }),
+        el('path', {
+            d: 'M21 33 C25 25 36 25 39 31 C43 38 35 44 28 39',
+            fill: 'none',
+            stroke: '#f0d7ff',
+            'stroke-width': 5,
+            'stroke-linecap': 'round',
+        }),
+        el('circle', {
+            cx: 44,
+            cy: 18,
+            r: 5,
+            fill: '#f0d7ff',
+            stroke: OUTLINE,
+            'stroke-width': DETAIL_STROKE,
+        }),
+        el('circle', {
+            cx: 19,
+            cy: 47,
+            r: 4,
+            fill: '#f0d7ff',
+            stroke: OUTLINE,
+            'stroke-width': DETAIL_STROKE,
+        }),
+    ].join('')
+}
+
+function regolithIcon(): string {
+    return [
+        el('path', {
+            d: 'M16 14 H45 L54 25 V46 L43 55 H17 L9 43 V24 Z',
+            fill: categoryColors.regolith,
+            stroke: OUTLINE,
+            'stroke-width': OUTER_STROKE,
+            'stroke-linejoin': 'round',
+        }),
+        el('path', {d: 'M16 14 H45 L54 25 L34 28 Z', fill: '#dec59a'}),
+        el('path', {d: 'M9 43 L34 28 L43 55 H17 Z', fill: '#9e7c55', opacity: 0.78}),
+        el('path', {
+            d: 'M16 14 L34 28 L54 25 M34 28 L43 55 M34 28 L9 43',
+            fill: 'none',
+            stroke: OUTLINE,
+            'stroke-width': 1.5,
+            'stroke-linecap': 'round',
+            'stroke-linejoin': 'round',
+            opacity: 0.25,
+        }),
+        el('circle', {cx: 25, cy: 28, r: 4, fill: '#806248', stroke: OUTLINE, 'stroke-width': 1.5}),
+        el('circle', {cx: 42, cy: 40, r: 5, fill: '#8b6a4d', stroke: OUTLINE, 'stroke-width': 1.5}),
+        el('circle', {
+            cx: 22,
+            cy: 44,
+            r: 3,
+            fill: '#e7d0a9',
+            stroke: OUTLINE,
+            'stroke-width': 1.25,
+        }),
+        el('path', {
+            d: 'M35 18 L45 23',
+            fill: 'none',
+            stroke: '#f0dbb7',
+            'stroke-width': DETAIL_STROKE,
+            'stroke-linecap': 'round',
+            opacity: 0.72,
+        }),
+    ].join('')
+}
+
+function biomassIcon(): string {
+    return [
+        el('path', {
+            d: 'M32 7 C37 14 42 17 50 16 C50 24 54 29 57 35 C51 39 48 44 47 52 C39 50 36 55 31 59 C27 52 21 50 13 53 C14 45 10 40 7 34 C13 29 14 23 12 16 C21 18 26 14 32 7 Z',
+            fill: categoryColors.biomass,
+            stroke: OUTLINE,
+            'stroke-width': OUTER_STROKE,
+            'stroke-linejoin': 'round',
+        }),
+        el('circle', {cx: 32, cy: 32, r: 13, fill: '#73ad49', stroke: OUTLINE, 'stroke-width': 2}),
+        el('circle', {cx: 27, cy: 28, r: 5, fill: '#a8db6f', stroke: OUTLINE, 'stroke-width': 1.5}),
+        el('circle', {cx: 38, cy: 34, r: 5, fill: '#2f6f35', stroke: OUTLINE, 'stroke-width': 1.5}),
+        el('circle', {cx: 30, cy: 41, r: 4, fill: '#89c85a', stroke: OUTLINE, 'stroke-width': 1.5}),
+        el('circle', {
+            cx: 40,
+            cy: 24,
+            r: 3,
+            fill: '#c9ef8a',
+            stroke: OUTLINE,
+            'stroke-width': 1.25,
+        }),
+    ].join('')
+}
+
+const iconBodies: Record<ResourceCategory, string> = {
+    ore: oreIcon(),
+    crystal: crystalIcon(),
+    gas: gasIcon(),
+    regolith: regolithIcon(),
+    biomass: biomassIcon(),
+}
+
+export function resourceIconBody(category: ResourceCategory): string {
+    return iconBodies[category]
+}
+
+export function resourceIcon(category: ResourceCategory, opts: ResourceIconInlineOpts): string {
+    const scale = opts.size / 64
+    return el(
+        'g',
+        {transform: `translate(${opts.x} ${opts.y}) scale(${scale})`, 'data-resource': category},
+        resourceIconBody(category)
+    )
+}
+
+export function resourceIconSvg(
+    category: ResourceCategory,
+    opts: ResourceIconSvgOpts = {}
+): string {
+    const size = opts.size ?? 64
+    const title = opts.title ?? `${CATEGORY_LABELS[category]} resource icon`
+    const children = `<title>${escapeXml(title)}</title>${resourceIconBody(category)}`
+    return el(
+        'svg',
+        {
+            xmlns: 'http://www.w3.org/2000/svg',
+            width: size,
+            height: size,
+            viewBox: '0 0 64 64',
+            role: 'img',
+            class: opts.className,
+            'aria-label': title,
+        },
+        children
+    )
+}

package/src/primitives/span-paragraph.ts

@@ -43,7 +43,7 @@ export function spanParagraph(props: SpanParagraphProps): {svg: string; lineCoun
     const chars = props.charsPerLine ?? 36
     const lh = props.lineHeight ?? 14
     const bodyColor = props.bodyColor ?? tokens.colors.text.secondary
-    const highlightColor = props.highlightColor ?? tokens.colors.text.accent
+    const highlightColor = props.highlightColor ?? tokens.colors.text.primary
     const size = props.fontSize ?? tokens.typography.sizes.body
 
     const plain = props.spans.map((s) => s.text).join('')

package/src/primitives/stat-bar.ts

@@ -1,6 +1,7 @@
 import {el} from './svg.ts'
 import {text} from './text.ts'
 import {tokens} from '../tokens/index.ts'
+import {statStars, STAR_BLOCK_WIDTH} from './stat-stars.ts'
 
 export interface StatBarProps {
     x: number
@@ -11,6 +12,7 @@ export interface StatBarProps {
     value: number | null // 0..1023, or null for ranges mode (no value text, no fill)
     color: string
     inverted?: boolean
+    stars?: number // 0..3 per-stat rating; only drawn in values mode
 }
 
 export function statBar({
@@ -22,6 +24,7 @@ export function statBar({
     value,
     color,
     inverted,
+    stars,
 }: StatBarProps): string {
     const h = tokens.spacing.statBarHeight
 
@@ -59,16 +62,29 @@ export function statBar({
         const displayFraction = inverted ? 1 - clamped / 1023 : clamped / 1023
         const filled = Math.floor(width * displayFraction)
 
+        const VALUE_COL_W = 34 // room for up to 4 mono digits at size 14, anchored end
+
+        // value text = primary; identity color = bar + code + chrome
         labelOut += text({
             x: x + width,
             y: y - 6,
             value: String(clamped),
             size: tokens.typography.sizes.statValue,
             weight: 700,
-            color,
+            family: tokens.typography.mono,
+            color: tokens.colors.text.primary,
             anchor: 'end',
         })
 
+        // stars sit immediately left of the reserved value column
+        if (stars !== undefined) {
+            labelOut += statStars({
+                x: x + width - VALUE_COL_W - STAR_BLOCK_WIDTH,
+                y: y - 6,
+                n: stars,
+            })
+        }
+
         const bar = el('rect', {
             x,
             y,

package/src/primitives/stat-stars.ts

@@ -0,0 +1,36 @@
+import {el} from './svg.ts'
+
+// 24×24 path, identical to the webapp ItemStatRow star.
+const STAR_PATH =
+    'M12 2.2l2.95 5.98 6.6.96-4.77 4.65 1.13 6.57L12 17.23 6.09 20.36l1.13-6.57L2.45 9.14l6.6-.96z'
+
+export const STAR_SIZE = 9
+export const STAR_GAP = 1
+export const MAX_STARS = 3
+export const STAR_BLOCK_WIDTH = MAX_STARS * STAR_SIZE + (MAX_STARS - 1) * STAR_GAP
+
+const ON_COLOR = '#ffce5c'
+const EMPTY_COLOR = 'rgba(255,255,255,0.16)'
+const SCALE = STAR_SIZE / 24
+
+export interface StatStarsProps {
+    x: number // left edge of the star block
+    y: number // vertical center the stars should sit on (text baseline)
+    n: number
+}
+
+// Draws MAX_STARS glyphs left-to-right starting at x; the first `n` are filled.
+export function statStars({x, y, n}: StatStarsProps): string {
+    const filled = Math.max(0, Math.min(MAX_STARS, Math.floor(n)))
+    const top = y - STAR_SIZE + 1 // center the glyph on the text baseline
+    let out = ''
+    for (let i = 0; i < MAX_STARS; i++) {
+        const gx = x + i * (STAR_SIZE + STAR_GAP)
+        out += el('path', {
+            d: STAR_PATH,
+            transform: `translate(${gx} ${top}) scale(${SCALE})`,
+            fill: i < filled ? ON_COLOR : EMPTY_COLOR,
+        })
+    }
+    return out
+}

package/src/primitives/text.ts

@@ -1,6 +1,14 @@
 import {el} from './svg.ts'
 import {tokens} from '../tokens/index.ts'
 
+export interface TextSpan {
+    value: string
+    size?: number
+    weight?: 400 | 600 | 700 | 500
+    color?: string
+    dx?: number
+}
+
 export interface TextProps {
     x: number
     y: number
@@ -12,9 +20,14 @@ export interface TextProps {
     anchor?: 'start' | 'middle' | 'end'
     letterSpacing?: number
     dominantBaseline?: 'auto' | 'middle' | 'central' | 'hanging' | 'text-top' | 'text-bottom'
+    // Optional trailing tspans that flow inline after value (no manual width math).
+    spans?: TextSpan[]
 }
 
 export function text(props: TextProps): string {
+    const body = props.spans?.length
+        ? escapeValue(props.value) + props.spans.map(renderSpan).join('')
+        : escapeValue(props.value)
     return el(
         'text',
         {
@@ -28,7 +41,20 @@ export function text(props: TextProps): string {
             'letter-spacing': props.letterSpacing,
             'dominant-baseline': props.dominantBaseline,
         },
-        escapeValue(props.value)
+        body
+    )
+}
+
+function renderSpan(span: TextSpan): string {
+    return el(
+        'tspan',
+        {
+            dx: span.dx,
+            'font-size': span.size,
+            'font-weight': span.weight,
+            fill: span.color,
+        },
+        escapeValue(span.value)
     )
 }
 

package/src/render.ts

@@ -1,29 +1,34 @@
 import {resolveItem, type ResolvedItem} from '@shipload/sdk'
 import type {CargoItem} from './payload/codec.ts'
-import {decodePayload} from './payload/codec.ts'
+import {decodeNftPayload} from './payload/codec.ts'
 import {renderByType} from './templates/index.ts'
 import {UnknownItemError} from './errors.ts'
 
 export interface RenderOptions {
     width?: number
     theme?: 'dark' | 'light'
+    location?: {x: number; y: number}
 }
 
-export function renderItem(item: CargoItem, resolved: ResolvedItem, _opts?: RenderOptions): string {
-    return renderByType(item, resolved)
+export function renderItem(item: CargoItem, resolved: ResolvedItem, opts?: RenderOptions): string {
+    return renderByType(item, resolved, {location: opts?.location})
 }
 
 export async function renderFromPayload(
     payload: string,
     opts?: RenderOptions
 ): Promise<{svg: string; item: ResolvedItem}> {
-    const cargoItem = decodePayload(payload)
+    const decoded = decodeNftPayload(payload)
+    const cargo = decoded.item
     let resolved: ResolvedItem
     try {
-        resolved = resolveItem(cargoItem.item_id, cargoItem.stats, cargoItem.modules)
+        resolved = resolveItem(cargo.item_id, cargo.stats, cargo.modules)
     } catch {
-        throw new UnknownItemError(Number(BigInt(cargoItem.item_id.toString())))
+        throw new UnknownItemError(Number(BigInt(cargo.item_id.toString())))
     }
-    const svg = renderItem(cargoItem, resolved, opts)
+    const location = decoded.location
+        ? {x: Number(decoded.location.x), y: Number(decoded.location.y)}
+        : opts?.location
+    const svg = renderItem(cargo, resolved, {...opts, location})
     return {svg, item: resolved}
 }