minecraft-inventory 0.1.25 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-inventory",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "type": "module",
   "license": "MIT",
   "release": {

package/src/components/InventoryOverlay/InventoryOverlay.tsx

@@ -310,7 +310,7 @@ export function InventoryOverlay({
               lineHeight: 1,
             }}
           >
-            INV 0.1.25
+            INV 0.1.26
           </a>
         )}
 

package/src/connector/mineflayer.ts

@@ -1,6 +1,15 @@
 import type { InventoryAction, InventoryWindowState, PlayerState, SlotState, ItemStack } from '../types'
 import type { InventoryConnector, ConnectorListener, ConnectorEvent, MineflayerBot } from './types'
 import { getInventoryType } from '../registry'
+import {
+  createInventoryDebugSession,
+  getActionSlotIndexes,
+  sanitizeDebugValue,
+  summarizeAction,
+  summarizeItem,
+  summarizeSlots,
+  summarizeWindowState,
+} from '../debug/inventoryDebug'
 
 type RawSlot = { type: number; count: number; metadata?: number; nbt?: unknown }
 
@@ -170,6 +179,24 @@ export function createMineflayerConnector(bot: MineflayerBot, options?: Mineflay
   // stale server responses overwriting our predicted stateId mid-sequence.
   let isDraggingRaw = false
 
+  const debugSession = createInventoryDebugSession(
+    hotbarOnly ? 'mineflayer-connector:hotbar' : 'mineflayer-connector',
+    () => {
+      const state = buildWindowState()
+      return {
+        windowState: state,
+        playerState: buildPlayerState(),
+        heldItem: state?.heldItem ?? null,
+      }
+    },
+  )
+  debugSession.log({
+    event: 'connector.mount',
+    data: {
+      hotbarOnly,
+    },
+  })
+
   // Resolve the Item class (prismarine-item) for converting notch-format items.
   // We extract it lazily from the first non-null slot item's constructor.
   let ItemClass: { fromNotch(notch: unknown): unknown } | null = null
@@ -318,6 +345,58 @@ export function createMineflayerConnector(bot: MineflayerBot, options?: Mineflay
     }
   }
 
+  function logActionEvent(
+    event: string,
+    action: InventoryAction,
+    data?: Record<string, unknown>,
+  ) {
+    const state = buildWindowState()
+    const slotIndexes = getActionSlotIndexes(action)
+    debugSession.log({
+      event,
+      windowId: state?.windowId,
+      windowType: state?.type,
+      action: summarizeAction(action),
+      stateId: dragStateId,
+      slots: state ? summarizeSlots(state.slots, slotIndexes) : undefined,
+      heldItem: summarizeItem(state?.heldItem),
+      data: data ? sanitizeDebugValue(data) : summarizeWindowState(state, slotIndexes),
+    })
+  }
+
+  function logPacketWrite(packet: string, params: unknown) {
+    const state = buildWindowState()
+    const paramsObject = params && typeof params === 'object' ? params as Record<string, unknown> : {}
+    debugSession.log({
+      event: 'connector.packetWrite',
+      windowId: typeof paramsObject.windowId === 'number' ? paramsObject.windowId : state?.windowId,
+      windowType: state?.type,
+      stateId: typeof paramsObject.stateId === 'number' ? paramsObject.stateId : dragStateId,
+      data: {
+        packet,
+        params: sanitizeDebugValue(params),
+      },
+    })
+  }
+
+  function logHelperIntent(action: InventoryAction, helper: string, params: Record<string, unknown>) {
+    const state = buildWindowState()
+    const slotIndexes = getActionSlotIndexes(action)
+    debugSession.log({
+      event: 'connector.helperIntent',
+      windowId: state?.windowId,
+      windowType: state?.type,
+      action: summarizeAction(action),
+      stateId: dragStateId,
+      slots: state ? summarizeSlots(state.slots, slotIndexes) : undefined,
+      heldItem: summarizeItem(state?.heldItem),
+      data: {
+        helper,
+        params: sanitizeDebugValue(params),
+      },
+    })
+  }
+
   /** Compute anvil cost client-side if callback is provided and window is anvil. */
   function tryComputeAnvilCost() {
     if (!computeAnvilCost || !currentWindowType) return
@@ -516,26 +595,40 @@ export function createMineflayerConnector(bot: MineflayerBot, options?: Mineflay
     openPlayerInventory,
 
     sendAction: async (action: InventoryAction) => {
+      logActionEvent('connector.action.start', action)
       try {
         // Hotbar "open inventory" button — delegates to openPlayerInventory()
         if (action.type === 'open-inventory') {
           await openPlayerInventory()
+          logActionEvent('connector.action.success', action)
           return
         }
   
         const win = bot.currentWindow
   
         if (action.type === 'trade' && win) {
+          let handled = false
           if (ext.trade && isVillagerWindow(win)) {
+            logHelperIntent(action, 'bot.trade', { tradeIndex: action.tradeIndex, count: 1 })
             await ext.trade(win, action.tradeIndex, 1)
+            handled = true
           } else if (isVillagerWindow(win)) {
+            logHelperIntent(action, 'window.trade', { tradeIndex: action.tradeIndex, count: 1 })
             await win.trade(action.tradeIndex, 1)
+            handled = true
+          }
+          if (handled) {
+            logActionEvent('connector.action.success', action)
+          } else {
+            logActionEvent('connector.action.skipped', action, { reason: 'missing_trade_handler' })
           }
           return
         }
   
         if (action.type === 'enchant' && win && isEnchantmentTableWindow(win)) {
+          logHelperIntent(action, 'window.enchant', { enchantIndex: action.enchantIndex })
           await win.enchant(action.enchantIndex)
+          logActionEvent('connector.action.success', action)
           return
         }
   
@@ -544,23 +637,44 @@ export function createMineflayerConnector(bot: MineflayerBot, options?: Mineflay
           // because it tries to transfer items from player inventory into anvil,
           // which fails when the user already placed items via the UI.
           if (ext.supportFeature?.('useMCItemName')) {
-            if (!ext._client.registerChannel) return
+            if (!ext._client.registerChannel) {
+              logActionEvent('connector.action.skipped', action, { reason: 'missing_registerChannel' })
+              return
+            }
             ext._client.registerChannel('MC|ItemName', 'string')
+            logPacketWrite('MC|ItemName', action.text)
             ext._client.writeChannel?.('MC|ItemName', action.text)
           } else {
-            ext._client.write('name_item', { name: action.text })
+            const packet = { name: action.text }
+            logPacketWrite('name_item', packet)
+            ext._client.write('name_item', packet)
           }
+          logActionEvent('connector.action.success', action)
           return
         }
   
         if (action.type === 'beacon' && win && isBeaconWindow(win)) {
+          let handled = false
           if (typeof win.setBeaconEffects === 'function') {
+            logHelperIntent(action, 'window.setBeaconEffects', {
+              primaryEffect: action.primaryEffect,
+              secondaryEffect: action.secondaryEffect,
+            })
             await win.setBeaconEffects(action.primaryEffect, action.secondaryEffect)
+            handled = true
           } else if (ext._client) {
-            ext._client.write('beacon_effect', {
+            const packet = {
               primaryEffect: action.primaryEffect,
               secondaryEffect: action.secondaryEffect,
-            })
+            }
+            logPacketWrite('beacon_effect', packet)
+            ext._client.write('beacon_effect', packet)
+            handled = true
+          }
+          if (handled) {
+            logActionEvent('connector.action.success', action)
+          } else {
+            logActionEvent('connector.action.skipped', action, { reason: 'missing_beacon_handler' })
           }
           return
         }
@@ -568,10 +682,13 @@ export function createMineflayerConnector(bot: MineflayerBot, options?: Mineflay
         if (action.type === 'click' && action.mode === 'double') {
           // bot.clickWindow() throws for mode=6 (prismarine-windows doubleClick is unimplemented).
           // Send raw window_click packet directly, same approach as drag (mode=5).
-          if (!ext._client) return
+          if (!ext._client) {
+            logActionEvent('connector.action.skipped', action, { reason: 'missing_client' })
+            return
+          }
           const windowId = bot.currentWindow ? bot.currentWindow.id : 0
 
-          ext._client.write('window_click', {
+          const packet = {
             windowId,
             stateId: dragStateId,
             slot: action.slotIndex,
@@ -579,19 +696,31 @@ export function createMineflayerConnector(bot: MineflayerBot, options?: Mineflay
             mode: 6,
             changedSlots: [],
             cursorItem: { present: false } as any,
-          })
+          }
+          logPacketWrite('window_click', packet)
+          ext._client.write('window_click', packet)
           dragStateId++
+          logActionEvent('connector.action.success', action)
           return
         }
   
         if (action.type === 'click') {
           const [mouseButton, mode] = modeFromAction(action)
+          logHelperIntent(action, 'bot.clickWindow', {
+            slot: action.slotIndex,
+            mouseButton,
+            mode,
+          })
           await bot.clickWindow(action.slotIndex, mouseButton, mode)
           onSetSlot()
+          logActionEvent('connector.action.success', action)
         } else if (action.type === 'drag') {
           // bot.clickWindow() throws for mode=5 (prismarine-windows dragClick is unimplemented).
           // Send raw window_click packets directly via _client.write.
-          if (!ext._client) return
+          if (!ext._client) {
+            logActionEvent('connector.action.skipped', action, { reason: 'missing_client' })
+            return
+          }
           const isRight = action.button === 'right'
           const startButton = isRight ? 4 : 0
           const slotButton = isRight ? 5 : 1
@@ -600,43 +729,68 @@ export function createMineflayerConnector(bot: MineflayerBot, options?: Mineflay
           const cursorItem = { present: false } as any
   
           isDraggingRaw = true
-          const writeClick = (slot: number, mouseButton: number) => {
-            ext._client!.write('window_click', {
-              windowId,
-              stateId: dragStateId,
-              slot,
-              mouseButton,
-              mode: 5,
-              changedSlots: [],
-              cursorItem,
-            })
-            dragStateId++
-          }
-  
-          writeClick(-999, startButton)
-          for (const slot of action.slots) {
-            writeClick(slot, slotButton)
+          try {
+            const writeClick = (slot: number, mouseButton: number) => {
+              const packet = {
+                windowId,
+                stateId: dragStateId,
+                slot,
+                mouseButton,
+                mode: 5,
+                changedSlots: [],
+                cursorItem,
+              }
+              logPacketWrite('window_click', packet)
+              ext._client!.write('window_click', packet)
+              dragStateId++
+            }
+    
+            writeClick(-999, startButton)
+            for (const slot of action.slots) {
+              writeClick(slot, slotButton)
+            }
+            writeClick(-999, endButton)
+          } finally {
+            isDraggingRaw = false
           }
-          writeClick(-999, endButton)
-          isDraggingRaw = false
+          logActionEvent('connector.action.success', action)
         } else if (action.type === 'drop') {
+          logHelperIntent(action, 'bot.clickWindow', {
+            slot: action.slotIndex,
+            mouseButton: action.all ? 1 : 0,
+            mode: 4,
+          })
           await bot.clickWindow(action.slotIndex, action.all ? 1 : 0, 4)
           onSetSlot()
+          logActionEvent('connector.action.success', action)
         } else if (action.type === 'close') {
           if (win) {
+            logHelperIntent(action, 'bot.closeWindow', { windowId: win.id })
             bot.closeWindow(win)
           } else {
             // Player inventory (synthetic) — send close_window so server drops cursor items
             if (ext._client) {
-              ext._client.write('close_window', { windowId: 0 })
+              const packet = { windowId: 0 }
+              logPacketWrite('close_window', packet)
+              ext._client.write('close_window', packet)
             }
             ;(bot.inventory as any).selectedItem = null
           }
+          logActionEvent('connector.action.success', action)
         } else if (action.type === 'hotbar-swap') {
+          logHelperIntent(action, 'bot.clickWindow', {
+            slot: action.slotIndex,
+            mouseButton: action.hotbarSlot,
+            mode: 2,
+          })
           await bot.clickWindow(action.slotIndex, action.hotbarSlot, 2)
           onSetSlot()
+          logActionEvent('connector.action.success', action)
+        } else {
+          logActionEvent('connector.action.ignored', action, { reason: 'no_matching_handler' })
         }
       } catch (err) {
+        logActionEvent('connector.action.failure', action, { error: err instanceof Error ? err.message : String(err) })
         const detail = 'slotIndex' in action ? ` slot=${(action as any).slotIndex}` : ''
         console.error(`[minecraft-inventory] sendAction "${action.type}"${detail} failed:`, err)
       }
@@ -674,7 +828,9 @@ export function createMineflayerConnector(bot: MineflayerBot, options?: Mineflay
         if (bot.currentWindow) {
           ;(bot.currentWindow as any).off('updateSlot', scheduleSlotUpdate)
         }
+        debugSession.log({ event: 'connector.unmount' })
+        debugSession.dispose()
       }
     },
   }
-}
+}

package/src/context/InventoryContext.tsx

@@ -2,6 +2,15 @@ import React, { createContext, useContext, useEffect, useRef, useState, useCallb
 import type { InventoryWindowState, PlayerState, ItemStack, SlotState } from '../types'
 import type { InventoryConnector } from '../connector/types'
 import { isItemEqual, getMaxStackSize } from '../utils/isItemEqual'
+import {
+  createInventoryDebugSession,
+  getActionSlotIndexes,
+  summarizeAction,
+  summarizeItem,
+  summarizeSlots,
+  summarizeWindowState,
+  type InventoryDebugSession,
+} from '../debug/inventoryDebug'
 
 export interface DragPreviewEntry {
   count: number
@@ -109,8 +118,30 @@ export function InventoryProvider({ connector, children, noDragSpread = false, n
   // Set to true when endDrag fires; cleared on the next mouseDown in Slot.
   // Prevents spurious mouseUp events from sending unwanted clicks after a drag.
   const dragEndedRef = useRef(false)
-  /** Latest full context value; updated every render for global debug (`globalThis.__mcInv.state`). */
+  /** Latest full context value; used by the DevTools debug API (`globalThis.__mcInv.state`). */
   const valueRef = useRef<InventoryContextValue | null>(null)
+  const debugSessionRef = useRef<InventoryDebugSession | null>(null)
+
+  useEffect(() => {
+    const session = createInventoryDebugSession('inventory-provider', () => {
+      const value = valueRef.current
+      if (!value) return null
+      return {
+        windowState: value.windowState,
+        playerState: value.playerState,
+        heldItem: value.heldItem,
+        isDragging: value.isDragging,
+        dragSlots: [...value.dragSlots],
+      }
+    })
+    debugSessionRef.current = session
+    session.log({ event: 'provider.mount' })
+    return () => {
+      session.log({ event: 'provider.unmount' })
+      session.dispose()
+      if (debugSessionRef.current === session) debugSessionRef.current = null
+    }
+  }, [])
 
   useEffect(() => {
     if (!connector) return
@@ -119,16 +150,35 @@ export function InventoryProvider({ connector, children, noDragSpread = false, n
 
     return connector.subscribe((event) => {
       if (event.type === 'windowOpen' || event.type === 'windowUpdate') {
+        debugSessionRef.current?.log({
+          event: `connector.${event.type}`,
+          windowId: event.state.windowId,
+          windowType: event.state.type,
+          slots: summarizeSlots(event.state.slots),
+          heldItem: summarizeItem(event.state.heldItem),
+        })
         setWindowState({ ...event.state })
         setHeldItemState(event.state.heldItem)
       } else if (event.type === 'windowClose') {
+        debugSessionRef.current?.log({ event: 'connector.windowClose' })
         setWindowState(null)
         setHeldItemState(null)
         setIsDragging(false)
         setDragSlots([])
       } else if (event.type === 'playerUpdate') {
+        debugSessionRef.current?.log({
+          event: 'connector.playerUpdate',
+          slots: summarizeSlots(event.state.inventory),
+          data: {
+            activeHotbarSlot: event.state.activeHotbarSlot,
+          },
+        })
         setPlayerState(event.state)
       } else if (event.type === 'heldItemChange') {
+        debugSessionRef.current?.log({
+          event: 'connector.heldItemChange',
+          heldItem: summarizeItem(event.item),
+        })
         setHeldItemState(event.item)
       }
     })
@@ -140,6 +190,19 @@ export function InventoryProvider({ connector, children, noDragSpread = false, n
 
   const sendAction = useCallback<InventoryConnector['sendAction']>(
     (action) => {
+      const slotIndexes = getActionSlotIndexes(action)
+      const state = valueRef.current?.windowState ?? connectorRef.current?.getWindowState() ?? null
+      debugSessionRef.current?.log({
+        event: 'ui.action',
+        windowId: state?.windowId,
+        windowType: state?.type,
+        action: summarizeAction(action),
+        slots: state ? summarizeSlots(state.slots, slotIndexes) : undefined,
+        heldItem: summarizeItem(valueRef.current?.heldItem ?? state?.heldItem),
+        data: {
+          before: summarizeWindowState(state, slotIndexes),
+        },
+      })
       return connectorRef.current?.sendAction(action)
     },
     [],
@@ -214,6 +277,17 @@ export function InventoryProvider({ connector, children, noDragSpread = false, n
 
       // Only send drag action if multiple slots were involved (single slot = normal click)
       if (slots.length > 1 && button && held) {
+        debugSessionRef.current?.log({
+          event: 'ui.drag.optimisticUpdate',
+          windowId: ws?.windowId,
+          windowType: ws?.type,
+          action: summarizeAction({ type: 'drag', slots, button }),
+          slots: ws ? summarizeSlots(ws.slots, slots) : undefined,
+          heldItem: summarizeItem(held),
+          data: {
+            before: summarizeWindowState(ws, slots),
+          },
+        })
         connectorRef.current?.sendAction({ type: 'drag', slots, button })
 
         // Optimistic client-side update: apply item distribution immediately
@@ -332,18 +406,5 @@ export function InventoryProvider({ connector, children, noDragSpread = false, n
 
   valueRef.current = value
 
-  // Full inventory UI state on global for DevTools: globalThis.__mcInv.state (e.g. windowState, playerState, heldItem, drag state).
-  useEffect(() => {
-    const g = globalThis as any
-    g.__mcInv = {
-      get state() {
-        return valueRef.current
-      },
-    }
-    return () => {
-      delete g.__mcInv
-    }
-  }, [])
-
   return <InventoryContext.Provider value={value}>{children}</InventoryContext.Provider>
 }

package/src/debug/README.md

@@ -0,0 +1,69 @@
+# Inventory Debug API
+
+Глобальный объект `__mcInv` доступен в DevTools сразу после монтирования `InventoryProvider`.
+
+## Быстрый старт
+
+```js
+// Текущее состояние инвентаря
+__mcInv.state
+
+// Все сессии (провайдер + коннектор)
+__mcInv.getStates()
+
+// Лог событий
+__mcInv.getLogs()
+
+// Последние N событий
+__mcInv.getLogs().slice(-20)
+
+// Экспорт для сравнения / передачи
+copy(JSON.stringify(__mcInv.exportLogs(), null, 2))
+
+// Очистить буфер
+__mcInv.clearLogs()
+```
+
+## События
+
+| Событие | Источник | Когда |
+|---|---|---|
+| `connector.mount` | mineflayer-connector | Коннектор создан |
+| `connector.unmount` | mineflayer-connector | Коннектор уничтожен |
+| `provider.mount` | inventory-provider | Провайдер смонтирован |
+| `provider.unmount` | inventory-provider | Провайдер размонтирован |
+| `connector.windowOpen` | inventory-provider | Открыто новое окно |
+| `connector.windowUpdate` | inventory-provider | Слоты обновились от сервера |
+| `connector.windowClose` | inventory-provider | Окно закрыто |
+| `connector.playerUpdate` | inventory-provider | Обновился инвентарь игрока |
+| `connector.heldItemChange` | inventory-provider | Изменился предмет в руке |
+| `ui.action` | inventory-provider | Пользователь инициировал действие |
+| `ui.drag.optimisticUpdate` | inventory-provider | Drag завершён, применён оптимистичный апдейт |
+| `connector.action.start` | mineflayer-connector | Начало отправки пакета |
+| `connector.action.success` | mineflayer-connector | Пакет успешно отправлен |
+| `connector.action.failure` | mineflayer-connector | Ошибка при отправке |
+| `connector.action.skipped` | mineflayer-connector | Действие пропущено (нет нужного хендлера) |
+| `connector.action.ignored` | mineflayer-connector | Неизвестный тип действия |
+| `connector.helperIntent` | mineflayer-connector | Вызов mineflayer-хелпера (bot.clickWindow и др.) |
+| `connector.packetWrite` | mineflayer-connector | Прямая запись пакета через `_client.write` |
+
+## Фильтрация логов
+
+```js
+// Только ошибки
+__mcInv.getLogs().filter(e => e.event === 'connector.action.failure')
+
+// Только действия пользователя
+__mcInv.getLogs().filter(e => e.event.startsWith('ui.'))
+
+// Конкретное окно
+__mcInv.getLogs().filter(e => e.windowType === 'enchanting_table')
+
+// Пакеты конкретного типа
+__mcInv.getLogs().filter(e => e.event === 'connector.packetWrite' && e.data?.packet === 'window_click')
+```
+
+## Ограничения
+
+- Буфер хранит последние **1000** записей. При активном геймплее старые события вытесняются — используйте `exportLogs()` своевременно.
+- `__mcInv.state` всегда показывает состояние последней созданной сессии (обычно `inventory-provider`). Для состояния коннектора используйте `getStates()`.

package/src/debug/inventoryDebug.ts

@@ -0,0 +1,240 @@
+import type { InventoryAction, InventoryWindowState, ItemStack, PlayerState, SlotState } from '../types'
+
+type JsonPrimitive = string | number | boolean | null
+type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
+
+export interface InventoryDebugLogEntry {
+  id: number
+  time: number
+  source: string
+  event: string
+  sessionId?: string
+  windowId?: number
+  windowType?: string
+  action?: JsonValue
+  stateId?: number
+  slots?: JsonValue
+  heldItem?: JsonValue
+  data?: JsonValue
+  error?: JsonValue
+}
+
+export interface InventoryDebugState {
+  windowState: InventoryWindowState | null
+  playerState: PlayerState | null
+  heldItem: ItemStack | null
+  isDragging?: boolean
+  dragSlots?: number[]
+}
+
+export interface InventoryDebugApi {
+  readonly state: InventoryDebugState | null
+  getStates(): Array<{ sessionId: string; source: string; state: InventoryDebugState | null }>
+  getLogs(): InventoryDebugLogEntry[]
+  clearLogs(): void
+  exportLogs(): {
+    exportedAt: string
+    logs: InventoryDebugLogEntry[]
+    states: JsonValue
+  }
+}
+
+interface ProviderRegistration {
+  sessionId: string
+  source: string
+  getState: () => InventoryDebugState | null
+}
+
+export interface InventoryDebugSession {
+  sessionId: string
+  source: string
+  log(entry: Omit<InventoryDebugLogEntry, 'id' | 'time' | 'source' | 'sessionId'>): void
+  dispose(): void
+}
+
+const MAX_LOGS = 1000
+const MAX_OBJECT_DEPTH = 4
+const MAX_ARRAY_ITEMS = 80
+
+let nextLogId = 1
+let nextSessionId = 1
+const logs: InventoryDebugLogEntry[] = []
+const providers = new Map<string, ProviderRegistration>()
+let activeSessionId: string | null = null
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function sanitize(value: unknown, depth = 0, seen = new WeakSet<object>()): JsonValue {
+  if (value == null) return null
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value
+  if (typeof value === 'bigint') return String(value)
+  if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'undefined') return null
+  if (depth >= MAX_OBJECT_DEPTH) return '[truncated]'
+
+  if (Array.isArray(value)) {
+    return value.slice(0, MAX_ARRAY_ITEMS).map((item) => sanitize(item, depth + 1, seen))
+  }
+
+  if (value instanceof Uint8Array) {
+    return `[Uint8Array:${value.byteLength}]`
+  }
+
+  if (!isObject(value)) return String(value)
+  if (seen.has(value)) return '[circular]'
+  seen.add(value)
+
+  const output: Record<string, JsonValue> = {}
+  for (const [key, entryValue] of Object.entries(value)) {
+    if (key === 'nbt') {
+      output.hasNbt = entryValue != null
+      continue
+    }
+    output[key] = sanitize(entryValue, depth + 1, seen)
+  }
+  return output
+}
+
+export function summarizeItem(item: ItemStack | null | undefined): JsonValue {
+  if (!item) return null
+  const summary: Record<string, JsonValue> = {
+    type: item.type,
+    count: item.count,
+  }
+  if (item.metadata !== undefined) summary.metadata = item.metadata
+  if (item.name) summary.name = item.name
+  if (item.displayName) summary.displayName = item.displayName
+  if (item.debugKey) summary.debugKey = item.debugKey
+  if (item.nbt) summary.hasNbt = true
+  if (item.enchantments?.length) summary.enchantments = sanitize(item.enchantments)
+  return summary
+}
+
+export function summarizeSlots(slots: SlotState[] | undefined, slotIndexes?: number[]): JsonValue {
+  if (!slots) return []
+  const filter = slotIndexes ? new Set(slotIndexes) : null
+  const selected = filter ? slots.filter((slot) => filter.has(slot.index)) : slots.filter((slot) => slot.item)
+  return selected.map((slot) => ({
+    index: slot.index,
+    item: summarizeItem(slot.item),
+  }))
+}
+
+export function summarizeAction(action: InventoryAction): JsonValue {
+  return sanitize(action)
+}
+
+export function sanitizeDebugValue(value: unknown): JsonValue {
+  return sanitize(value)
+}
+
+export function summarizeWindowState(state: InventoryWindowState | null | undefined, slotIndexes?: number[]): JsonValue {
+  if (!state) return null
+  return {
+    windowId: state.windowId,
+    type: state.type,
+    title: state.title ?? null,
+    heldItem: summarizeItem(state.heldItem),
+    properties: sanitize(state.properties ?? null),
+    slots: summarizeSlots(state.slots, slotIndexes),
+  }
+}
+
+export function getActionSlotIndexes(action: InventoryAction): number[] | undefined {
+  if (action.type === 'click' || action.type === 'drop' || action.type === 'hotbar-swap') return [action.slotIndex]
+  if (action.type === 'drag') return [...action.slots]
+  return undefined
+}
+
+function getActiveState(): InventoryDebugState | null {
+  if (activeSessionId && providers.has(activeSessionId)) {
+    return providers.get(activeSessionId)!.getState()
+  }
+  const last = [...providers.values()].at(-1)
+  return last?.getState() ?? null
+}
+
+function getStates(): Array<{ sessionId: string; source: string; state: InventoryDebugState | null }> {
+  return [...providers.values()].map((provider) => ({
+    sessionId: provider.sessionId,
+    source: provider.source,
+    state: provider.getState(),
+  }))
+}
+
+function installGlobalApi() {
+  const g = globalThis as typeof globalThis & { __mcInv?: InventoryDebugApi }
+  if (g.__mcInv?.getLogs === getLogs) return
+
+  const api: InventoryDebugApi = {
+    get state() {
+      return getActiveState()
+    },
+    getStates,
+    getLogs,
+    clearLogs,
+    exportLogs,
+  }
+  g.__mcInv = api
+}
+
+function getLogs(): InventoryDebugLogEntry[] {
+  return logs.map((entry) => ({ ...entry }))
+}
+
+function clearLogs() {
+  logs.length = 0
+}
+
+function exportLogs() {
+  return {
+    exportedAt: new Date().toISOString(),
+    logs: getLogs(),
+    states: sanitize(getStates()),
+  }
+}
+
+export function logInventoryDebug(entry: Omit<InventoryDebugLogEntry, 'id' | 'time'>): void {
+  const fullEntry: InventoryDebugLogEntry = {
+    ...entry,
+    id: nextLogId++,
+    time: Date.now(),
+  }
+  logs.push(fullEntry)
+  if (logs.length > MAX_LOGS) logs.splice(0, logs.length - MAX_LOGS)
+  installGlobalApi()
+}
+
+export function createInventoryDebugSession(
+  source: string,
+  getState: () => InventoryDebugState | null,
+): InventoryDebugSession {
+  installGlobalApi()
+  const sessionId = `${source}-${nextSessionId++}`
+  providers.set(sessionId, { sessionId, source, getState })
+  activeSessionId = sessionId
+
+  return {
+    sessionId,
+    source,
+    log(entry) {
+      logInventoryDebug({
+        ...entry,
+        source,
+        sessionId,
+      })
+    },
+    dispose() {
+      providers.delete(sessionId)
+      if (activeSessionId === sessionId) {
+        activeSessionId = [...providers.keys()].at(-1) ?? null
+      }
+    },
+  }
+}
+
+export function getInventoryDebugApi(): InventoryDebugApi {
+  installGlobalApi()
+  return (globalThis as typeof globalThis & { __mcInv: InventoryDebugApi }).__mcInv
+}

package/src/index.tsx

@@ -36,6 +36,23 @@ export { useKeyboardShortcuts } from './hooks/useKeyboardShortcuts'
 
 // Utilities
 export { isItemEqual, getMaxStackSize } from './utils/isItemEqual'
+export {
+  getInventoryDebugApi,
+  logInventoryDebug,
+  createInventoryDebugSession,
+  summarizeAction,
+  summarizeItem,
+  summarizeSlots,
+  summarizeWindowState,
+  getActionSlotIndexes,
+  sanitizeDebugValue,
+} from './debug/inventoryDebug'
+export type {
+  InventoryDebugApi,
+  InventoryDebugLogEntry,
+  InventoryDebugSession,
+  InventoryDebugState,
+} from './debug/inventoryDebug'
 
 // Connector
 export { createMineflayerConnector } from './connector/mineflayer'