suaveplan/openspec/changes/enterprise-gaming-r3f-inventory/proposal.md

OpenSpec Change: enterprise-gaming-r3f-inventory

• Change ID: enterprise-gaming-r3f-inventory
• Package: @suaveplan/r3f-inventory
• Category: gaming/gameplay
• Target path: gaming/gameplay/r3f-inventory
• Status: PROPOSED
• Date: 2026-04-24

---

Summary

Deliver @suaveplan/r3f-inventory on the genesis branch from scratch at enterprise quality. The package provides a 3D grid-based inventory rendered inside a React Three Fiber scene or as an HTML overlay: InventoryGrid with configurable cell size and slot count, ItemMesh showing a 3D model preview of each item, EquipmentSlots with body-region anchors, LootTable drop-chance visualization, and useInventory() backed by a framework-agnostic InventoryManager. Drag-and-drop reordering, stack splitting, and equipment slot restriction rules are enforced by the manager. Genesis adds 100% coverage and Storybook stories.

---

Available workspace deps

@suaveplan/error, @suaveplan/types, @suaveplan/events, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

interface InventoryItem {
  id: string
  name: string
  stackSize: number
  maxStack: number
  equipSlot?: EquipmentSlot
  modelUrl?: string
  iconUrl?: string
}

type EquipmentSlot = 'head' | 'chest' | 'legs' | 'feet' | 'mainHand' | 'offHand' | 'ring' | 'neck'

function createInventoryManager(options: InventoryOptions): InventoryManager

function InventoryGrid(props: InventoryGridProps): JSX.Element
function EquipmentSlots(props: EquipmentSlotsProps): JSX.Element
function ItemMesh(props: ItemMeshProps): JSX.Element
function LootTableDisplay(props: LootTableDisplayProps): JSX.Element

function useInventory(): InventoryState & { manager: InventoryManager }

---

File layout

gaming/gameplay/r3f-inventory/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    state/inventory-manager.ts + md + test
    hooks/use-inventory.ts + md + test
    components/
      InventoryGrid/ (tsx + md + test + stories + index)
      EquipmentSlots/ (tsx + md + test + stories + index)
      ItemMesh/ (tsx + md + test + stories + index)
      LootTableDisplay/ (tsx + md + test + stories + index)
  tests/integration.test.ts