minecraft-inventory 0.1.24 → 0.1.26

package/README.md

@@ -9,7 +9,7 @@ A flexible, scalable React library for rendering Minecraft inventory GUIs. Desig
 - `<img>`-rendered item textures with automatic `items/` → `blocks/` fallback (via PrismarineJS asset mirror by default)
 - Tooltips that follow the cursor, matching the original Minecraft style
 - Full keyboard support: number keys (1-9) to swap hotbar, Q to drop, double-click to collect, scroll wheel to pick/place
-- Mobile support: tap to open a context menu (take all / half / custom amount / drop)
+- Mobile support: tap-to-focus inventory interactions plus long-press slot actions (pick half / custom amount / drop one / drop all)
 - Optional JEI (item browser) panel on the left or right
 - Bot connector layer — plugs into a mineflayer bot or any custom server connection
 - Demo connector with action logging for local development
@@ -414,13 +414,13 @@ const myConnector: InventoryConnector = {
 
 ## Mobile Support
 
-On touch devices, tapping a slot with no held item opens a context menu instead of immediately picking up the item. The menu appears to the side in landscape or below in portrait.
+On touch devices, tapping a slot uses the mobile focus/swap flow. Long-pressing a populated slot with no held item opens a context menu. The menu appears to the side in landscape or below in portrait.
 
 Context menu options:
-- **Take All** — picks up the entire stack
-- **Take Half** — picks up half
-- **Take Amount…** — `window.prompt` to enter a custom quantity
-- **Drop** — drops the stack from the slot
+- **Pick Half** — picks up half and highlights the selected slot
+- **Pick Amount…** — `window.prompt` to enter a custom quantity, remembering the last value entered
+- **Drop One** — drops a single item from the slot (same as `Q`)
+- **Drop All** — drops the full stack from the slot (same as `Ctrl+Q`)
 - **Cancel**
 
 When you have a held item, tapping a slot places/transfers it (same as left-click on desktop).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-inventory",
-  "version": "0.1.24",
+  "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.24
+            INV 0.1.26
           </a>
         )}
 

package/src/components/Slot/Slot.tsx

@@ -54,6 +54,8 @@ export function Slot({
     setPKeyActive,
     focusedSlot,
     setFocusedSlot,
+    mobilePickAmount,
+    setMobilePickAmount,
     dragEndedRef,
     noPlaceholders,
   } = useInventoryContext()
@@ -331,6 +333,7 @@ export function Slot({
 
       if (heldItem) {
         // When holding an item, place it (standard behavior, no focus needed)
+        if (focusedSlot !== null) setFocusedSlot(null)
         sendAction({ type: 'click', slotIndex: index, button: 'left', mode: 'normal' })
         return
       }
@@ -351,28 +354,25 @@ export function Slot({
     [isMobile, disabled, heldItem, sendAction, index, pKeyActive, setPKeyActive, focusedSlot, setFocusedSlot, onClickOverride, cancelLongPress, mobileMenuOpen],
   )
 
-  const handleMobilePickAll = useCallback(() => {
-    setMobileMenuOpen(false)
-    setShowTooltip(false)
-    sendAction({ type: 'click', slotIndex: index, button: 'left', mode: 'normal' })
-  }, [sendAction, index])
-
   const handleMobilePickHalf = useCallback(() => {
     setMobileMenuOpen(false)
     setShowTooltip(false)
+    setFocusedSlot(index)
     sendAction({ type: 'click', slotIndex: index, button: 'right', mode: 'normal' })
-  }, [sendAction, index])
+  }, [sendAction, index, setFocusedSlot])
 
   const handleMobilePickCustom = useCallback(() => {
     if (!item) return
-    const input = window.prompt(`Pick amount (max ${item.count}):`, String(item.count))
+    const input = window.prompt(`Pick amount (max ${item.count}):`, String(mobilePickAmount))
     const amount = parseInt(input ?? '', 10)
     if (isNaN(amount) || amount <= 0) return
+    setMobilePickAmount(amount)
     setMobileMenuOpen(false)
     setShowTooltip(false)
+    setFocusedSlot(index)
     const take = Math.min(amount, item.count)
     if (take >= item.count) {
-      // Take all: just left-click
+      // Pick all: just left-click
       sendAction({ type: 'click', slotIndex: index, button: 'left', mode: 'normal' })
     } else {
       // Pick up all, then put back (count - take) items one-by-one via right-click
@@ -381,13 +381,21 @@ export function Slot({
         sendAction({ type: 'click', slotIndex: index, button: 'right', mode: 'normal' })
       }
     }
-  }, [item, sendAction, index])
+  }, [item, mobilePickAmount, sendAction, index, setFocusedSlot, setMobilePickAmount])
+
+  const handleMobileDropOne = useCallback(() => {
+    setMobileMenuOpen(false)
+    setShowTooltip(false)
+    setFocusedSlot(null)
+    sendAction({ type: 'drop', slotIndex: index, all: false })
+  }, [sendAction, index, setFocusedSlot])
 
-  const handleMobileDrop = useCallback(() => {
+  const handleMobileDropAll = useCallback(() => {
     setMobileMenuOpen(false)
     setShowTooltip(false)
+    setFocusedSlot(null)
     sendAction({ type: 'drop', slotIndex: index, all: true })
-  }, [sendAction, index])
+  }, [sendAction, index, setFocusedSlot])
 
   const closeMobileMenu = useCallback(() => {
     setMobileMenuOpen(false)
@@ -532,10 +540,10 @@ export function Slot({
             item={item}
             x={mobileTouchPos.x}
             y={mobileTouchPos.y}
-            onPickAll={handleMobilePickAll}
             onPickHalf={handleMobilePickHalf}
             onPickCustom={handleMobilePickCustom}
-            onDrop={handleMobileDrop}
+            onDropOne={handleMobileDropOne}
+            onDropAll={handleMobileDropAll}
             onClose={closeMobileMenu}
           />
         </>
@@ -548,14 +556,14 @@ interface MobileSlotMenuProps {
   item: ItemStack
   x: number
   y: number
-  onPickAll(): void
   onPickHalf(): void
   onPickCustom(): void
-  onDrop(): void
+  onDropOne(): void
+  onDropAll(): void
   onClose(): void
 }
 
-function MobileSlotMenu({ item, x, y, onPickAll, onPickHalf, onPickCustom, onDrop, onClose }: MobileSlotMenuProps) {
+function MobileSlotMenu({ item, x, y, onPickHalf, onPickCustom, onDropOne, onDropAll, onClose }: MobileSlotMenuProps) {
   const { scale } = useScale()
   const menuRef = useRef<HTMLDivElement>(null)
   const [pos, setPos] = useState({ left: x, top: y })
@@ -600,10 +608,10 @@ function MobileSlotMenu({ item, x, y, onPickAll, onPickHalf, onPickCustom, onDro
       <div className={styles.mobileMenuTitle}>
         {item.displayName ?? item.name ?? `Item #${item.type}`} ×{item.count}
       </div>
-      <button className={styles.mobileBtn} {...touchBtn(onPickAll)}>Take All ({item.count})</button>
-      <button className={styles.mobileBtn} {...touchBtn(onPickHalf)}>Take Half ({Math.ceil(item.count / 2)})</button>
-      <button className={styles.mobileBtn} {...touchBtn(onPickCustom)}>Take Amount…</button>
-      <button className={[styles.mobileBtn, styles.mobileBtnDanger].join(' ')} {...touchBtn(onDrop)}>Drop</button>
+      <button className={styles.mobileBtn} {...touchBtn(onPickHalf)}>Pick Half ({Math.ceil(item.count / 2)})</button>
+      <button className={styles.mobileBtn} {...touchBtn(onPickCustom)}>Pick Amount…</button>
+      <button className={[styles.mobileBtn, styles.mobileBtnDanger].join(' ')} {...touchBtn(onDropOne)}>Drop One</button>
+      <button className={[styles.mobileBtn, styles.mobileBtnDanger].join(' ')} {...touchBtn(onDropAll)}>Drop All</button>
       <button className={styles.mobileBtn} {...touchBtn(onClose)}>Cancel</button>
     </div>
   )

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
@@ -44,6 +53,9 @@ export interface InventoryContextValue {
   /** Pending first digit for P-key slot number entry */
   pKeyDigit: string
   setPKeyDigit: (d: string) => void
+  /** Last amount entered in the mobile pick-amount prompt */
+  mobilePickAmount: number
+  setMobilePickAmount: (amount: number) => void
   /** Ref set to true when a drag just ended; cleared on next mouseDown.
    *  Used by Slot to suppress spurious click events that fire after endDrag. */
   dragEndedRef: React.MutableRefObject<boolean>
@@ -90,6 +102,7 @@ export function InventoryProvider({ connector, children, noDragSpread = false, n
   const [pKeyActive, setPKeyActive] = useState(false)
   const [focusedSlot, setFocusedSlot] = useState<number | null>(null)
   const [pKeyDigit, setPKeyDigit] = useState('')
+  const [mobilePickAmount, setMobilePickAmount] = useState(1)
 
   const connectorRef = useRef(connector)
   connectorRef.current = connector
@@ -105,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
@@ -115,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)
       }
     })
@@ -136,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)
     },
     [],
@@ -210,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
@@ -320,24 +398,13 @@ export function InventoryProvider({ connector, children, noDragSpread = false, n
     setFocusedSlot,
     pKeyDigit,
     setPKeyDigit,
+    mobilePickAmount,
+    setMobilePickAmount,
     dragEndedRef,
     resolveEnchantmentName,
   }
 
   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'