@shipload/item-renderer 1.0.0-next.2 → 1.0.0-next.21

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@shipload/item-renderer",
-    "version": "1.0.0-next.2",
+    "version": "1.0.0-next.21",
     "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.21",
         "@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,7 +27,7 @@ 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'

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/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

@@ -59,13 +59,15 @@ export function statBar({
         const displayFraction = inverted ? 1 - clamped / 1023 : clamped / 1023
         const filled = Math.floor(width * displayFraction)
 
+        // 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',
         })
 

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}
 }

package/src/templates/_shared.ts

@@ -1,7 +1,11 @@
+import type {ResolvedItem} from '@shipload/sdk'
+import {baseName, formatMassScaled} from '@shipload/sdk'
+import {text} from '../primitives/text.ts'
+import {divider} from '../primitives/divider.ts'
 import {tokens} from '../tokens/index.ts'
 
-export function formatMass(n: number): string {
-    return n.toLocaleString('en-US')
+export function formatMass(kg: number): string {
+    return formatMassScaled(kg)
 }
 
 export function tierBorder(tier: number): string {
@@ -12,3 +16,110 @@ export function shortCode(itemId: number): string {
     const str = itemId.toString(10)
     return str.slice(-2).padStart(2, '0')
 }
+
+export function capabilityColor(name: string): string {
+    const key = name.toLowerCase().replace(/\s+/g, '') as keyof typeof tokens.colors.capability
+    return tokens.colors.capability[key] ?? tokens.colors.accent.component
+}
+
+export const META_ROW_H = 22
+export const HEADER_H = 48
+export const ICON_Y = 4
+export const BADGE_Y = 6
+export const META_BLOCK_GAP = 16
+
+export const STAT_ROW_H = 26
+export const CAP_HEADER_H = 22
+export const CAP_ROW_H = 18
+export const BODY_TAIL = 8
+
+// Gap from the meta block to the first stat row. Resources/components have no
+// body sub-header, and statBar draws its label 6px above its y, so this is
+// META_BLOCK_GAP plus the offset that puts the first stat label level with
+// where module/entity body sections begin — keeping the meta→body gap uniform.
+export const STAT_BLOCK_GAP = META_BLOCK_GAP + 22
+
+// Uniform gap between a card's last body element and the bottom frame edge.
+// Cards size their height to (last element bottom) + BOTTOM_PAD so trailing
+// space is consistent across resource / component / module / entity types.
+export const BOTTOM_PAD = 22
+
+export function titleParts(x: number, y: number, name: string, tier: number): string {
+    return text({
+        x,
+        y,
+        value: name,
+        size: tokens.typography.sizes.title,
+        weight: 700,
+        family: tokens.typography.display,
+        spans: [
+            {
+                value: `T${tier}`,
+                dx: 6,
+                size: tokens.typography.sizes.subtitle,
+                weight: 700,
+                color: tokens.colors.text.secondary,
+            },
+        ],
+    })
+}
+
+export function titleText(x: number, y: number, resolved: ResolvedItem): string {
+    // Prominent base name; tier rendered as a smaller, muted inline suffix.
+    return titleParts(x, y, baseName(resolved), resolved.tier)
+}
+
+export interface MetaRowProps {
+    x: number
+    y: number
+    width: number
+    label: string
+    value: string
+    showDivider?: boolean
+}
+
+export function metaRow({x, y, width, label, value, showDivider = true}: MetaRowProps): string {
+    const labelText = text({
+        x,
+        y: y + 12,
+        value: label,
+        size: tokens.typography.sizes.body,
+        color: tokens.colors.text.secondary,
+    })
+    const valueText = text({
+        x: x + width,
+        y: y + 12,
+        value,
+        size: tokens.typography.sizes.body,
+        weight: 700,
+        anchor: 'end',
+    })
+    const sep = showDivider
+        ? divider({
+              x,
+              y: y + META_ROW_H - 4,
+              width,
+              color: tokens.colors.surface.panelBorderBright,
+          })
+        : ''
+    return labelText + valueText + sep
+}
+
+export function metaRowBlock(
+    x: number,
+    yStart: number,
+    width: number,
+    rows: {label: string; value: string}[]
+): {svg: string; height: number} {
+    let svg = ''
+    rows.forEach((row, i) => {
+        svg += metaRow({
+            x,
+            y: yStart + i * META_ROW_H,
+            width,
+            ...row,
+            showDivider: i < rows.length - 1,
+        })
+    })
+    return {svg, height: rows.length * META_ROW_H}
+}

package/src/templates/component.ts

@@ -1,17 +1,28 @@
-import type {ResolvedItem, ResourceCategory} from '@shipload/sdk'
-import {formatTier, getRecipe, getStatDefinitions, categoryColors} from '@shipload/sdk'
+import type {ResolvedItem} from '@shipload/sdk'
+import {getRecipe, getStatDefinitions, resolveItemCategory, formatLocation} from '@shipload/sdk'
 import type {CargoItem} from '../payload/codec.ts'
 import {panel} from '../primitives/panel.ts'
 import {iconHex} from '../primitives/icon-hex.ts'
-import {text} from '../primitives/text.ts'
-import {divider} from '../primitives/divider.ts'
 import {statBar} from '../primitives/stat-bar.ts'
 import {quantityBadge} from '../primitives/quantity-badge.ts'
 import {tokens} from '../tokens/index.ts'
-import {shortCode, formatMass, tierBorder} from './_shared.ts'
+import {
+    shortCode,
+    formatMass,
+    tierBorder,
+    metaRowBlock,
+    titleText,
+    BADGE_Y,
+    HEADER_H,
+    ICON_Y,
+    STAT_BLOCK_GAP,
+    STAT_ROW_H,
+    BOTTOM_PAD,
+} from './_shared.ts'
 
 export interface RenderComponentOpts {
     mode?: 'values' | 'ranges'
+    location?: {x: number; y: number}
 }
 
 type StatRow = {
@@ -32,13 +43,15 @@ export function renderComponent(
     const pad = tokens.spacing.panelPadding
     const innerW = w - pad * 2
 
+    const identity = tokens.colors.accent.component
+
     let rows: StatRow[]
     if (mode === 'values') {
         rows = (resolved.stats ?? []).map((s) => ({
             label: s.label,
             abbreviation: s.abbreviation,
             value: s.value,
-            color: s.color,
+            color: identity,
             inverted: s.inverted,
         }))
     } else {
@@ -47,8 +60,9 @@ export function renderComponent(
             const src = slot.sources[0]
             if (!src) return []
             const input = recipe!.inputs[src.inputIndex]
-            if (!input || !('category' in input)) return []
-            const category = input.category as ResourceCategory
+            if (!input) return []
+            const category = resolveItemCategory(input.itemId)
+            if (!category) return []
             const def = getStatDefinitions(category)[src.statIndex]
             if (!def) return []
             return [
@@ -56,78 +70,44 @@ export function renderComponent(
                     label: def.label,
                     abbreviation: def.abbreviation,
                     value: null,
-                    color: categoryColors[category],
+                    color: identity,
                     inverted: def.inverted,
                 },
             ]
         })
     }
 
-    const headerH = 48
-    const metaRowH = 28
-    const statsH = rows.length * 26 + 8
-    const height = headerH + metaRowH + 14 + statsH + pad
+    const quantity = Number(BigInt(item.quantity.toString()))
+    const metaRows = [
+        {label: 'Mass', value: formatMass(resolved.mass * Math.max(quantity, 1))},
+        ...(opts?.location ? [{label: 'Location', value: formatLocation(opts.location)}] : []),
+    ]
+
+    const metaYStart = pad + HEADER_H
+    const {svg: metaSvg, height: metaH} = metaRowBlock(pad, metaYStart, innerW, metaRows)
+    const statsYStart = metaYStart + metaH + STAT_BLOCK_GAP
+    const statsBottom =
+        statsYStart + Math.max(0, rows.length - 1) * STAT_ROW_H + tokens.spacing.statBarHeight
+    const height = statsBottom + BOTTOM_PAD
 
     const chrome = panel({width: w, height, borderColor: tierBorder(resolved.tier)})
 
-    const quantity = Number(BigInt(item.quantity.toString()))
-    const badge = quantityBadge({x: w - pad, y: pad, quantity})
+    const badge = quantityBadge({x: w - pad, y: pad + BADGE_Y, quantity, tone: identity})
 
     const icon = iconHex({
         x: pad,
-        y: pad + 4,
-        color: tokens.colors.accent.component,
+        y: pad + ICON_Y,
+        color: identity,
         code: shortCode(resolved.itemId),
     })
 
-    const name = text({
-        x: pad + 34,
-        y: pad + 22,
-        value: resolved.name,
-        size: tokens.typography.sizes.title,
-        weight: 700,
-        family: tokens.typography.display,
-    })
-
-    const subtitleText = text({
-        x: pad,
-        y: pad + headerH + 4,
-        value: 'Type',
-        size: tokens.typography.sizes.body,
-        color: tokens.colors.text.secondary,
-    })
-    const subtitleValue = text({
-        x: w - pad,
-        y: pad + headerH + 4,
-        value: `COMPONENT · ${formatTier(resolved.tier)}`,
-        size: tokens.typography.sizes.body,
-        weight: 600,
-        anchor: 'end',
-    })
-    const massLabel = text({
-        x: pad,
-        y: pad + headerH + metaRowH - 8,
-        value: 'Mass',
-        size: tokens.typography.sizes.body,
-        color: tokens.colors.text.secondary,
-    })
-    const massValue = text({
-        x: w - pad,
-        y: pad + headerH + metaRowH - 8,
-        value: formatMass(resolved.mass),
-        size: tokens.typography.sizes.body,
-        weight: 600,
-        anchor: 'end',
-    })
-
-    const sepY = pad + headerH + metaRowH + 6
-    const sep = divider({x: pad, y: sepY, width: innerW})
+    const name = titleText(pad + 34, pad + 22, resolved)
 
     const statsSvg = rows
         .map((row, i) =>
             statBar({
                 x: pad,
-                y: sepY + 18 + i * 26,
+                y: statsYStart + i * STAT_ROW_H,
                 width: innerW,
                 label: row.label,
                 abbreviation: row.abbreviation,
@@ -138,7 +118,7 @@ export function renderComponent(
         )
         .join('')
 
-    const inner = `${chrome}${icon}${name}${badge}${subtitleText}${subtitleValue}${massLabel}${massValue}${sep}${statsSvg}`
+    const inner = `${chrome}${icon}${name}${badge}${metaSvg}${statsSvg}`
 
     return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${height}" viewBox="0 0 ${w} ${height}">${inner}</svg>`
 }

package/src/templates/index.ts

@@ -8,6 +8,7 @@ import {renderModule} from './module.ts'
 
 export interface RenderByTypeOpts {
     mode?: 'values' | 'ranges'
+    location?: {x: number; y: number}
 }
 
 export function renderByType(
@@ -19,7 +20,7 @@ export function renderByType(
         case 'resource':
             return renderResource(item, resolved, opts)
         case 'entity':
-            return renderPackedEntity(item, resolved)
+            return renderPackedEntity(item, resolved, opts)
         case 'component':
             return renderComponent(item, resolved, opts)
         case 'module':