minecraft-inventory 0.1.5 → 0.1.6

package/README.md

@@ -262,16 +262,16 @@ pnpm add mc-assets   # optional peer dependency
 
 ```tsx
 import { TextureProvider, InventoryOverlay } from 'minecraft-inventory'
-import { localTexturesConfig } from './generated/localTextures'
+import { localBundledTexturesConfig } from './bundledTexturesConfig'
 
 // GUI container backgrounds (chest, furnace, etc.) load from bundled mc-assets;
 // item/block textures still use the default remote URLs unless you override them.
-<TextureProvider config={localTexturesConfig}>
+<TextureProvider config={localBundledTexturesConfig}>
   <InventoryOverlay type="chest" ... />
 </TextureProvider>
 ```
 
-The generated file imports every `backgroundTexture` from your registry, resolves each to `node_modules/mc-assets/dist/other-textures/<version>/...` (or `latest/` if that version is missing), and exports `allContainerPaths` (inventory name → short path) plus `localTexturesConfig.getGuiTextureUrl(path)` for use with `<TextureProvider config={...}>`. Re-run `pnpm gen:textures` after changing [inventory types](#adding-new-inventory-types).
+The generated file (`src/generated/localTextures.ts`) exports `bundledTextureMap`, `allTexturePaths`, and `allContainerPaths`. Use `createBundledTexturesConfig({ remoteFallback: true, bundledTextureMap? })` to get a config with `getGuiTextureUrl`, `setOverride(path, image)`, `clearOverrides()`, `setRemoteFallback(enabled)`, and `resetRenderedSlots()`. Pass short paths to `setOverride` (e.g. `gui/sprites/container/anvil/text_field_disabled.png`) — the version prefix exists only for the texture import generator. Call `resetRenderedSlots()` after multiple `setOverride` calls to invalidate cached textures so slots re-request them. `localBundledTexturesConfig` is the default instance. Re-run `pnpm gen:textures` after changing [inventory types](#adding-new-inventory-types).
 
 ---
 
@@ -546,9 +546,18 @@ interface ItemStack {
   lore?: string[]
   durability?: number        // Current durability value
   maxDurability?: number     // Max durability (renders bar when < max)
+  textureKey?: string        // Override texture path for getItemTextureUrl
+  texture?: string | HTMLImageElement  // Direct texture (bypasses URL lookup)
+  blockTexture?: BlockTextureRender   // Isometric block icon from face slices
+  debugKey?: string
 }
 ```
 
+**Texture overrides (mineflayer `itemMapper`):**
+- `texture: string` — URL or data URL, fetched and cached.
+- `texture: HTMLImageElement` — Preloaded image, used directly.
+- `blockTexture: { source, top, left, right }` — Composite an isometric block icon from three face slices. Each face has `slice: [x, y, w, h]` in source texture pixels. Uses a pool of aux canvases (not recreated per slot).
+
 ---
 
 ## Project Structure
@@ -613,6 +622,10 @@ Each Minecraft window type has a fixed slot layout defined by the server protoco
 - [`prismarine-windows`](https://github.com/PrismarineJS/prismarine-windows) for JS slot maps
 - Minecraft source: `net/minecraft/world/inventory/` for the canonical layout
 
+### Memory leak note (Tooltip / MessageFormattedString)
+
+If opening tooltips increases memory without returning to baseline, see [docs/MEMORY_LEAK_ANALYSIS.md](docs/MEMORY_LEAK_ANALYSIS.md). The likely cause is `filter:blur(2px)` on obfuscated (§k) text creating retained compositor layers.
+
 ### Connector protocol
 
 When implementing a custom connector, actions have these shapes:

package/package.json

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

package/src/bundledTexturesConfig.ts

@@ -0,0 +1,126 @@
+/**
+ * Centralized config for bundled GUI textures. Uses maps from generated localTextures.
+ * Supports overrides via short paths (e.g. "gui/sprites/container/anvil/text_field_disabled.png"),
+ * remote fallback toggle, and cache invalidation after overrides.
+ *
+ * Version prefix (e.g. "1.21.11/textures/") in bundled keys exists only for the texture
+ * import generator — setOverride accepts short paths without it.
+ */
+
+import {
+  bundledTextureMap,
+  allTexturePaths,
+  allContainerPaths,
+} from './generated/localTextures'
+import type { TextureConfig } from './context/TextureContext'
+import { clearTextureCache } from './cache/textureCache'
+
+const MC_ASSETS_REMOTE =
+  'https://raw.githubusercontent.com/zardoy/mc-assets/refs/heads/gh-pages'
+
+/** Normalize path to short form: "gui/..." (strip version prefix if present). */
+function toShortPath(path: string): string {
+  const m = path.match(/^\d[\d.]+\/textures\/(.+)$/)
+  return m ? m[1] : path
+}
+
+/** Default version for building mc-assets URLs when path is short. */
+const DEFAULT_VERSION = '1.21.11'
+
+export interface BundledTexturesConfigOptions {
+  /** When true (default), unknown paths fall back to remote mc-assets URL. */
+  remoteFallback?: boolean
+  /** Override the bundled texture map (e.g. for custom builds). */
+  bundledTextureMap?: Record<string, string | undefined>
+}
+
+export interface BundledTexturesConfig extends Pick<TextureConfig, 'getGuiTextureUrl'> {
+  /**
+   * Override a texture. Pass short path (e.g. "gui/sprites/container/anvil/text_field_disabled.png")
+   * and image URL. Version prefix is only for the import generator — not needed here.
+   */
+  setOverride(path: string, image: string): void
+  /** Remove all texture overrides. */
+  clearOverrides(): void
+  /** Enable or disable remote fallback for unknown paths. */
+  setRemoteFallback(enabled: boolean): void
+  /**
+   * Invalidate cached textures so slots re-request them. Call after multiple setOverride
+   * calls when you want UI to immediately reflect new overrides.
+   */
+  resetRenderedSlots(): void
+}
+
+/**
+ * Build a reverse map: shortPath -> bundled URL.
+ */
+function buildShortPathToBundled(
+  bundled: Record<string, string | undefined>,
+): Map<string, string> {
+  const map = new Map<string, string>()
+  for (const [key, url] of Object.entries(bundled)) {
+    if (!url) continue
+    const short = toShortPath(key)
+    if (!map.has(short)) map.set(short, url)
+  }
+  return map
+}
+
+/**
+ * Create a bundled textures config with overrides and optional remote fallback.
+ * Pass the returned config to <TextureProvider config={...}>.
+ */
+export function createBundledTexturesConfig(
+  options?: BundledTexturesConfigOptions,
+): BundledTexturesConfig {
+  let remoteFallbackEnabled = options?.remoteFallback ?? true
+  const overrides = new Map<string, string>()
+  const bundled = options?.bundledTextureMap ?? bundledTextureMap
+  const shortToBundled = buildShortPathToBundled(bundled)
+
+  function getGuiTextureUrl(path: string): string {
+    const shortPath = toShortPath(path)
+
+    const override = overrides.get(shortPath)
+    if (override) return override
+
+    const bundledUrl = bundled[path] ?? shortToBundled.get(shortPath)
+    if (bundledUrl) return bundledUrl
+
+    if (
+      remoteFallbackEnabled &&
+      path.endsWith('.png') &&
+      path.includes('/textures/')
+    ) {
+      return `${MC_ASSETS_REMOTE}/${path}`
+    }
+
+    if (remoteFallbackEnabled && shortPath.endsWith('.png')) {
+      const versioned = `${DEFAULT_VERSION}/textures/${shortPath}`
+      return `${MC_ASSETS_REMOTE}/${versioned}`
+    }
+
+    return path
+  }
+
+  return {
+    getGuiTextureUrl,
+    setOverride(path: string, image: string) {
+      overrides.set(toShortPath(path), image)
+    },
+    clearOverrides() {
+      overrides.clear()
+    },
+    setRemoteFallback(enabled: boolean) {
+      remoteFallbackEnabled = enabled
+    },
+    resetRenderedSlots() {
+      clearTextureCache()
+    },
+  }
+}
+
+/** Default config instance for <TextureProvider config={localBundledTexturesConfig}>. */
+export const localBundledTexturesConfig = createBundledTexturesConfig()
+
+export { allTexturePaths, allContainerPaths }

package/src/cache/blockRenderer.ts

@@ -0,0 +1,103 @@
+/**
+ * Pool of offscreen canvases for block-face compositing.
+ * Reuses a fixed set of canvases instead of creating new ones per render.
+ */
+
+const POOL_SIZE = 8
+const OUTPUT_SIZE = 32
+
+const pool: HTMLCanvasElement[] = []
+const inUse = new Set<HTMLCanvasElement>()
+
+function getCanvas(): HTMLCanvasElement {
+  const free = pool.find((c) => !inUse.has(c))
+  if (free) {
+    inUse.add(free)
+    return free
+  }
+  if (pool.length < POOL_SIZE) {
+    const c = document.createElement('canvas')
+    c.width = OUTPUT_SIZE
+    c.height = OUTPUT_SIZE
+    pool.push(c)
+    inUse.add(c)
+    return c
+  }
+  const c = pool[pool.length - 1]
+  inUse.add(c)
+  return c
+}
+
+function releaseCanvas(c: HTMLCanvasElement): void {
+  inUse.delete(c)
+}
+
+/** Slice rect [x, y, width, height] */
+type Slice = [number, number, number, number]
+
+/**
+ * Composite top/left/right block faces into an isometric-style icon.
+ * Uses a pool of canvases; not recreated each time.
+ */
+export function renderBlockIcon(
+  source: HTMLImageElement | string,
+  top: Slice,
+  left: Slice,
+  right: Slice,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const isUrl = typeof source === 'string'
+    const img = isUrl ? new Image() : (source as HTMLImageElement)
+
+    const draw = (image: HTMLImageElement) => {
+      let canvas: HTMLCanvasElement | null = null
+      try {
+        canvas = getCanvas()
+        const ctx = canvas.getContext('2d')
+        if (!ctx) throw new Error('No 2d context')
+
+        ctx.imageSmoothingEnabled = false
+        ctx.clearRect(0, 0, OUTPUT_SIZE, OUTPUT_SIZE)
+
+        const s = OUTPUT_SIZE / 16
+        const [tx, ty, tw, th] = top
+        const [lx, ly, lw, lh] = left
+        const [rx, ry, rw, rh] = right
+
+        // Isometric layout: top face tilted, left and right as sides
+        ctx.save()
+        ctx.translate(8 * s, 2 * s)
+        ctx.rotate(-Math.PI / 4)
+        ctx.drawImage(image, tx, ty, tw, th, -4 * s, -4 * s, 8 * s, 8 * s)
+        ctx.restore()
+
+        ctx.drawImage(image, lx, ly, lw, lh, 0, 12 * s, 10 * s, 10 * s)
+        ctx.drawImage(image, rx, ry, rw, rh, 12 * s, 12 * s, 10 * s, 10 * s)
+
+        const dataUrl = canvas.toDataURL('image/png')
+        resolve(dataUrl)
+      } catch (e) {
+        reject(e)
+      } finally {
+        if (canvas) releaseCanvas(canvas)
+      }
+    }
+
+    if (isUrl) {
+      img.onload = () => draw(img)
+      img.onerror = () =>
+        reject(new Error('Failed to load block texture'))
+      img.crossOrigin = 'anonymous'
+      img.src = source
+    } else if (
+      (img).complete &&
+      (img).naturalWidth > 0
+    ) {
+      draw(img)
+    } else {
+      img.onload = () => draw(img)
+      img.onerror = () =>
+        reject(new Error('Block texture image failed'))
+    }
+  })
+}

package/src/cache/textureCache.ts

@@ -45,6 +45,16 @@ export function isTextureFailed(url: string): boolean {
   return failedUrls.has(url)
 }
 
+/**
+ * Clear all cached texture data URLs and failed state.
+ * Call after setOverride in bundledTexturesConfig so slots re-request textures.
+ */
+export function clearTextureCache(): void {
+  dataUrlCache.clear()
+  failedUrls.clear()
+  inflight.clear()
+}
+
 /**
  * Hook that resolves a URL to a cached base64 data URL.
  * Returns:

package/src/components/InventoryOverlay/InventoryOverlay.tsx

@@ -288,7 +288,7 @@ export function InventoryOverlay({
               lineHeight: 1,
             }}
           >
-            INV 0.0.0
+            INV 0.1.6
           </a>
         )}
 

package/src/components/InventoryWindow/InventoryBackground.tsx

@@ -37,7 +37,7 @@ export function InventoryBackground({
   const { scale } = useScale()
 
   const bgUrl = textures.getGuiTextureUrl(definition.backgroundTexture)
-  const isStitched = definition.containerRows != null && definition.containerRows < 6
+  const isStitched = definition.containerRows != null && definition.containerRows <= 6
 
   const w = definition.backgroundWidth * scale
   const h = definition.backgroundHeight * scale

package/src/components/ItemCanvas/ItemCanvas.tsx

@@ -3,6 +3,7 @@ import type { ItemStack } from '../../types'
 import { useTextures } from '../../context/TextureContext'
 import { useScale } from '../../context/ScaleContext'
 import { useDataUrl, isTextureFailed } from '../../cache/textureCache'
+import { renderBlockIcon } from '../../cache/blockRenderer'
 
 interface ItemCanvasProps {
   item: ItemStack
@@ -22,28 +23,68 @@ function getDurabilityColor(current: number, max: number): string {
   return '#ff5555'
 }
 
-/** Renders a single item: texture as <img>, count as <span>, durability as CSS bars. */
-export const ItemCanvas = memo(function ItemCanvas({
-  item,
-  size,
-  noCount = false,
-  noDurability = false,
-  className,
-  style,
-}: ItemCanvasProps) {
+/** Resolve item texture source: direct override, block render, or URL lookup. */
+function useItemTextureSrc(item: ItemStack): {
+  src: string | null
+  failed: boolean
+  loading: boolean
+} {
   const textures = useTextures()
-  const { contentSize, pixelSize } = useScale()
-  const renderSize = size ?? contentSize
 
-  const primaryUrl = textures.getItemTextureUrl(item)
-  // Skip the block-texture fallback when a textureKey override is already in use
-  const fallbackUrl = !item.textureKey && item.name ? textures.getBlockTextureUrl(item) : null
+  // Block texture: always run effect for blockTexture case
+  const blockConfig = item.blockTexture ?? null
+  const [blockDataUrl, setBlockDataUrl] = useState<string | null>(null)
+  const [blockFailed, setBlockFailed] = useState(false)
+
+  useEffect(() => {
+    if (!blockConfig) return
+    let cancelled = false
+    renderBlockIcon(
+      blockConfig.source,
+      blockConfig.top.slice,
+      blockConfig.left.slice,
+      blockConfig.right.slice,
+    )
+      .then((url) => {
+        if (!cancelled) setBlockDataUrl(url)
+      })
+      .catch(() => {
+        if (!cancelled) setBlockFailed(true)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [
+    blockConfig?.source,
+    blockConfig ? String(blockConfig.top.slice) : '',
+    blockConfig ? String(blockConfig.left.slice) : '',
+    blockConfig ? String(blockConfig.right.slice) : '',
+  ])
+
+  // Reset block state when switching away from blockTexture
+  useEffect(() => {
+    if (!blockConfig) {
+      setBlockDataUrl(null)
+      setBlockFailed(false)
+    }
+  }, [blockConfig])
+
+  // Direct texture (string) - use cache
+  const directUrl =
+    typeof item.texture === 'string' ? item.texture : null
+  const directDataUrl = useDataUrl(directUrl)
 
-  // Load primary URL as cached data URL
-  const primaryDataUrl = useDataUrl(primaryUrl)
+  // Default URL lookup
+  const primaryUrl = blockConfig ? '' : (typeof item.texture === 'string' ? '' : textures.getItemTextureUrl(item))
+  const fallbackUrl =
+    !blockConfig &&
+    !item.textureKey &&
+    item.name
+      ? textures.getBlockTextureUrl(item)
+      : null
+  const primaryDataUrl = useDataUrl(primaryUrl || null)
   const primaryFailed = primaryDataUrl === null || isTextureFailed(primaryUrl)
 
-  // Load fallback only once primary is known to have failed
   const [loadFallback, setLoadFallback] = useState(false)
   useEffect(() => {
     if (primaryFailed && fallbackUrl) setLoadFallback(true)
@@ -51,11 +92,56 @@ export const ItemCanvas = memo(function ItemCanvas({
   }, [primaryFailed, fallbackUrl])
   const fallbackDataUrl = useDataUrl(loadFallback ? fallbackUrl : null)
 
+  // Resolve final src by priority
+  if (typeof item.texture === 'string') {
+    return {
+      src: directDataUrl ?? null,
+      failed: directDataUrl === null || isTextureFailed(item.texture),
+      loading: directDataUrl === undefined,
+    }
+  }
+  if (item.texture instanceof HTMLImageElement) {
+    const img = item.texture
+    return {
+      src: img.complete && img.naturalWidth > 0 ? img.src : null,
+      failed: false,
+      loading: !img.complete,
+    }
+  }
+  if (blockConfig) {
+    return {
+      src: blockDataUrl,
+      failed: blockFailed,
+      loading: !blockDataUrl && !blockFailed,
+    }
+  }
+
   const src = loadFallback ? fallbackDataUrl : primaryDataUrl
   const failed = loadFallback
     ? (fallbackDataUrl === null || isTextureFailed(fallbackUrl ?? ''))
     : primaryFailed && !fallbackUrl
 
+  return {
+    src: src ?? null,
+    failed,
+    loading: src === undefined,
+  }
+}
+
+/** Renders a single item: texture as <img>, count as <span>, durability as CSS bars. */
+export const ItemCanvas = memo(function ItemCanvas({
+  item,
+  size,
+  noCount = false,
+  noDurability = false,
+  className,
+  style,
+}: ItemCanvasProps) {
+  const { contentSize, pixelSize } = useScale()
+  const renderSize = size ?? contentSize
+
+  const { src, failed, loading } = useItemTextureSrc(item)
+
   const hasDurability =
     !noDurability &&
     item.durability !== undefined &&

package/src/components/JEI/JEI.module.css

@@ -1,6 +1,8 @@
 .jei {
   font-family: 'Minecraft', monospace;
   image-rendering: pixelated;
+  height: 100%;
+  border-radius: 1px;
 }
 
 .searchInput::placeholder {

package/src/components/JEI/JEI.tsx

@@ -96,6 +96,7 @@ export function JEI({
 
     const ro = new ResizeObserver((entries) => {
       for (const entry of entries) {
+        // console.log('got size', entry.target.className, entry.contentRect.width, entry.contentRect.height)
         if (entry.target === (root as unknown as Element)) {
           sizes.rootW = entry.contentRect.width
         } else if (entry.target === (grid as unknown as Element)) {
@@ -240,8 +241,6 @@ export function JEI({
         className="mc-inv-jei-header"
         style={{
           padding: `${padding}px`,
-          background: '#c6c6c6',
-          // border: `${scale}px solid #555555`,
           flexShrink: 0,
         }}
       >
@@ -284,7 +283,7 @@ export function JEI({
           >
             ◀
           </button>
-          <span className="mc-inv-jei-page-counter" style={{ flex: 1, textAlign: 'center', color: '#404040' }}>
+          <span className="mc-inv-jei-page-counter" style={{ flex: 1, textAlign: 'center', color: '#ffffff' }}>
             {page + 1} / {Math.max(1, totalPages)}
           </span>
           <button

package/src/components/Text/MessageFormattedString.tsx

@@ -16,6 +16,7 @@ const CODE_COLORS: Record<string, string> = {
 function parseSectionCodes(text: string): MessageFormatPart[] {
   const parts: MessageFormatPart[] = []
   const regex = /§([0-9a-fk-orA-FK-OR])|([^§]+)/g
+  regex.lastIndex = 0
   let color: string | undefined
   let bold = false, italic = false, underlined = false
   let strikethrough = false, obfuscated = false

package/src/components/Tooltip/Tooltip.tsx

@@ -85,8 +85,7 @@ export function Tooltip({ item, visible }: TooltipProps) {
         fontSize: fs,
         padding: pad,
         gap: gap2,
-        minWidth: Math.round(80 * scale),
-        maxWidth: Math.round(220 * scale),
+        width: 'max-content',
         // Start invisible; applyPosition sets visibility after measuring dimensions
         visibility: 'hidden',
         pointerEvents: 'none',

package/src/connector/mineflayer.ts

@@ -10,19 +10,31 @@ export interface MineflayerConnectorOptions {
   /**
    * Custom item mapper called for every slot conversion from raw mineflayer data to
    * {@link ItemStack}. Receives the raw slot data and the default-mapped stack.
-   * Return a modified stack to override fields (e.g. `name`, `textureKey`, `displayName`),
-   * or return the second argument unchanged to use the default mapping.
+   * Return a modified stack to override fields (e.g. `name`, `textureKey`, `displayName`,
+   * `texture`, `blockTexture`), or return the second argument unchanged to use the default mapping.
    *
    * @example
    * ```ts
    * createMineflayerConnector(bot, {
    *   itemMapper: (raw, mapped) => ({
    *     ...mapped,
-   *     // Override texture for specific numeric type IDs:
    *     textureKey: raw.type === 438 ? 'item/potion_water' : mapped.textureKey,
    *   }),
    * })
    * ```
+   *
+   * @example Block texture with isometric face slices
+   * ```ts
+   * itemMapper: (raw, mapped) => ({
+   *   ...mapped,
+   *   blockTexture: {
+   *     source: blockAtlasUrl,
+   *     top: { slice: [0, 0, 16, 16] },
+   *     left: { slice: [16, 0, 16, 16] },
+   *     right: { slice: [32, 0, 16, 16] },
+   *   },
+   * })
+   * ```
    */
   itemMapper?: (raw: RawSlot, mapped: ItemStack) => ItemStack
 }

package/src/generated/localTextures.ts

@@ -28,6 +28,72 @@ import _gui_widgets from 'mc-assets/dist/other-textures/1.15/gui/widgets.png'
 import _gui_sprites_container_anvil_text_field from 'mc-assets/dist/other-textures/latest/gui/sprites/container/anvil/text_field.png'
 import _gui_sprites_container_anvil_text_field_disabled from 'mc-assets/dist/other-textures/latest/gui/sprites/container/anvil/text_field_disabled.png'
 
+/**
+ * Versioned texture path → bundled asset URL (or undefined for remote fallback).
+ * Keys are full mc-assets paths e.g. "1.21.11/textures/gui/container/inventory.png"
+ */
+export const bundledTextureMap: Record<string, string | undefined> = {
+  '1.21.11/textures/gui/container/inventory.png': _gui_container_inventory,
+  '1.21.11/textures/gui/container/shulker_box.png': _gui_container_shulker_box,
+  '1.21.11/textures/gui/container/generic_54.png': _gui_container_generic_54,
+  '1.21.11/textures/gui/container/crafting_table.png': _gui_container_crafting_table,
+  '1.21.11/textures/gui/container/furnace.png': _gui_container_furnace,
+  '1.21.11/textures/gui/container/blast_furnace.png': _gui_container_blast_furnace,
+  '1.21.11/textures/gui/container/smoker.png': _gui_container_smoker,
+  '1.21.11/textures/gui/container/brewing_stand.png': _gui_container_brewing_stand,
+  '1.21.11/textures/gui/container/anvil.png': _gui_container_anvil,
+  '1.21.11/textures/gui/container/grindstone.png': _gui_container_grindstone,
+  '1.21.11/textures/gui/container/enchanting_table.png': _gui_container_enchanting_table,
+  '1.21.11/textures/gui/container/smithing.png': _gui_container_smithing,
+  '1.16.4/textures/gui/container/smithing.png': _gui_container_smithing_2,
+  '1.21.11/textures/gui/container/hopper.png': _gui_container_hopper,
+  '1.21.11/textures/gui/container/dispenser.png': _gui_container_dispenser,
+  '1.21.11/textures/gui/container/beacon.png': _gui_container_beacon,
+  '1.21.11/textures/gui/container/horse.png': _gui_container_horse,
+  '1.14/textures/gui/container/villager2.png': _gui_container_villager2,
+  '1.21.11/textures/gui/container/cartography_table.png': _gui_container_cartography_table,
+  '1.21.11/textures/gui/container/loom.png': _gui_container_loom,
+  '1.21.11/textures/gui/container/stonecutter.png': _gui_container_stonecutter,
+  '1.21.11/textures/gui/container/crafter.png': _gui_container_crafter,
+  '1.21.11/textures/gui/container/creative_inventory/tab_items.png': _gui_container_creative_inventory_tab_items,
+  '1.15/textures/gui/widgets.png': _gui_widgets,
+  '1.21.11/textures/gui/sprites/container/anvil/text_field.png': _gui_sprites_container_anvil_text_field,
+  '1.21.11/textures/gui/sprites/container/anvil/text_field_disabled.png': _gui_sprites_container_anvil_text_field_disabled,
+}
+
+
+/**
+ * All texture paths without version prefix (e.g. "gui/container/inventory.png").
+ * Same set as bundledTextureMap keys with version stripped.
+ */
+export const allTexturePaths: readonly string[] = [
+  'gui/container/inventory.png',
+  'gui/container/shulker_box.png',
+  'gui/container/generic_54.png',
+  'gui/container/crafting_table.png',
+  'gui/container/furnace.png',
+  'gui/container/blast_furnace.png',
+  'gui/container/smoker.png',
+  'gui/container/brewing_stand.png',
+  'gui/container/anvil.png',
+  'gui/container/grindstone.png',
+  'gui/container/enchanting_table.png',
+  'gui/container/smithing.png',
+  'gui/container/hopper.png',
+  'gui/container/dispenser.png',
+  'gui/container/beacon.png',
+  'gui/container/horse.png',
+  'gui/container/villager2.png',
+  'gui/container/cartography_table.png',
+  'gui/container/loom.png',
+  'gui/container/stonecutter.png',
+  'gui/container/crafter.png',
+  'gui/container/creative_inventory/tab_items.png',
+  'gui/widgets.png',
+  'gui/sprites/container/anvil/text_field.png',
+  'gui/sprites/container/anvil/text_field_disabled.png',
+]
+
 /**
  * Maps each inventory type name to its texture path (version prefix stripped).
  */
@@ -68,54 +134,3 @@ export const allContainerPaths: Record<string, string> = {
   creative: 'gui/container/creative_inventory/tab_items.png',
   hotbar: 'gui/widgets.png',
 }
-
-// Internal: versioned texture key → bundled asset URL (or undefined → remote fallback)
-const _map: Record<string, string | undefined> = {
-  '1.21.11/textures/gui/container/inventory.png': _gui_container_inventory,
-  '1.21.11/textures/gui/container/shulker_box.png': _gui_container_shulker_box,
-  '1.21.11/textures/gui/container/generic_54.png': _gui_container_generic_54,
-  '1.21.11/textures/gui/container/crafting_table.png': _gui_container_crafting_table,
-  '1.21.11/textures/gui/container/furnace.png': _gui_container_furnace,
-  '1.21.11/textures/gui/container/blast_furnace.png': _gui_container_blast_furnace,
-  '1.21.11/textures/gui/container/smoker.png': _gui_container_smoker,
-  '1.21.11/textures/gui/container/brewing_stand.png': _gui_container_brewing_stand,
-  '1.21.11/textures/gui/container/anvil.png': _gui_container_anvil,
-  '1.21.11/textures/gui/container/grindstone.png': _gui_container_grindstone,
-  '1.21.11/textures/gui/container/enchanting_table.png': _gui_container_enchanting_table,
-  '1.21.11/textures/gui/container/smithing.png': _gui_container_smithing,
-  '1.16.4/textures/gui/container/smithing.png': _gui_container_smithing_2,
-  '1.21.11/textures/gui/container/hopper.png': _gui_container_hopper,
-  '1.21.11/textures/gui/container/dispenser.png': _gui_container_dispenser,
-  '1.21.11/textures/gui/container/beacon.png': _gui_container_beacon,
-  '1.21.11/textures/gui/container/horse.png': _gui_container_horse,
-  '1.14/textures/gui/container/villager2.png': _gui_container_villager2,
-  '1.21.11/textures/gui/container/cartography_table.png': _gui_container_cartography_table,
-  '1.21.11/textures/gui/container/loom.png': _gui_container_loom,
-  '1.21.11/textures/gui/container/stonecutter.png': _gui_container_stonecutter,
-  '1.21.11/textures/gui/container/crafter.png': _gui_container_crafter,
-  '1.21.11/textures/gui/container/creative_inventory/tab_items.png': _gui_container_creative_inventory_tab_items,
-  '1.15/textures/gui/widgets.png': _gui_widgets,
-  '1.21.11/textures/gui/sprites/container/anvil/text_field.png': _gui_sprites_container_anvil_text_field,
-  '1.21.11/textures/gui/sprites/container/anvil/text_field_disabled.png': _gui_sprites_container_anvil_text_field_disabled,
-}
-
-/**
- * Partial TextureConfig that resolves inventory GUI textures from locally bundled
- * mc-assets assets instead of remote GitHub URLs.
- *
- * Pass to `<TextureProvider config={localTexturesConfig}>` to use offline/bundled assets.
- *
- * Unknown paths (not bundled) fall back to the mc-assets remote URL automatically.
- */
-const _MC_ASSETS_REMOTE = "https://raw.githubusercontent.com/zardoy/mc-assets/refs/heads/gh-pages"
-export const localTexturesConfig = {
-  getGuiTextureUrl(path: string): string {
-    const local = _map[path] as string | undefined
-    if (local) return local
-    // Fall back to remote mc-assets URL for paths not in the bundle
-    if (path.endsWith('.png') && path.includes('/textures/')) {
-      return `${_MC_ASSETS_REMOTE}/${path}`
-    }
-    return path
-  },
-}

package/src/index.tsx

@@ -67,4 +67,22 @@ export type {
   RecipeGuide,
   RecipeNavFrame,
   EntityDisplayArea,
+  TextureSlice,
+  BlockFaceSlice,
+  BlockTextureRender,
 } from './types'
+
+// Bundled textures config
+export {
+  createBundledTexturesConfig,
+  localBundledTexturesConfig,
+  allTexturePaths,
+  allContainerPaths,
+} from './bundledTexturesConfig'
+export type {
+  BundledTexturesConfig,
+  BundledTexturesConfigOptions,
+} from './bundledTexturesConfig'
+
+// Texture cache (for resetRenderedSlots / manual invalidation)
+export { clearTextureCache } from './cache/textureCache'

package/src/registry/inventories.ts

@@ -140,7 +140,7 @@ export const inventoryDefinitions = makeInventoryDefinitions({
     containerRows: 1,
     slots: [
       ...gridSlots(9, 1, 8, 18, 'container'),
-      ...playerInv(48), // 1*18 + 30
+      ...playerInv(50), // 1*18 + 30 + 2px offset below
     ],
   },
 
@@ -153,7 +153,7 @@ export const inventoryDefinitions = makeInventoryDefinitions({
     containerRows: 2,
     slots: [
       ...gridSlots(9, 2, 8, 18, 'container'),
-      ...playerInv(66), // 2*18 + 30
+      ...playerInv(68), // 2*18 + 30 + 2px offset below
     ],
   },
 
@@ -164,10 +164,10 @@ export const inventoryDefinitions = makeInventoryDefinitions({
     backgroundWidth: 176,
     backgroundHeight: 168, // 3*18 + 114
     containerRows: 3,
-    playerInventoryOffset: { x: 8, y: 84 },
+    playerInventoryOffset: { x: 8, y: 82 },
     slots: [
       ...gridSlots(9, 3, 8, 18, 'container'),
-      ...playerInv(84), // 3*18 + 30
+      ...playerInv(86), // 3*18 + 30 + 2px offset below
     ],
   },
 
@@ -180,7 +180,7 @@ export const inventoryDefinitions = makeInventoryDefinitions({
     containerRows: 4,
     slots: [
       ...gridSlots(9, 4, 8, 18, 'container'),
-      ...playerInv(102), // 4*18 + 30
+      ...playerInv(104), // 4*18 + 30 + 2px offset below
     ],
   },
 
@@ -193,7 +193,7 @@ export const inventoryDefinitions = makeInventoryDefinitions({
     containerRows: 5,
     slots: [
       ...gridSlots(9, 5, 8, 18, 'container'),
-      ...playerInv(120), // 5*18 + 30
+      ...playerInv(122), // 5*18 + 30 + 2px offset below
     ],
   },
 
@@ -204,6 +204,7 @@ export const inventoryDefinitions = makeInventoryDefinitions({
     backgroundWidth: 176,
     backgroundHeight: 222, // full 6-row texture, no stitching needed (N*18+114 = 222)
     playerInventoryOffset: { x: 8, y: 140 },
+    containerRows: 6,
     slots: [
       ...gridSlots(9, 6, 8, 18, 'container'),
       ...playerInv(140), // matches large_chest
@@ -216,7 +217,8 @@ export const inventoryDefinitions = makeInventoryDefinitions({
     backgroundTexture: '1.21.11/textures/gui/container/generic_54.png',
     backgroundWidth: 176,
     backgroundHeight: 222,
-    playerInventoryOffset: { x: 8, y: 140 },
+    containerRows: 6,
+    playerInventoryOffset: { x: 8, y: 138 },
     slots: [
       ...gridSlots(9, 6, 8, 18, 'container'),
       ...playerInv(140),

package/src/types.ts

@@ -1,3 +1,24 @@
+/** Slice rect [x, y, width, height] in source texture pixels. */
+export type TextureSlice = [x:number, y:number, width:number, height:number]
+
+/** Block face slice for isometric block rendering. */
+export interface BlockFaceSlice {
+  slice: TextureSlice
+}
+
+/**
+ * Block-style render config. When set, ItemCanvas uses an aux canvas to composite
+ * top/left/right faces into an isometric icon instead of a single texture.
+ * Useful for blocks in mineflayer connector where block texture atlas faces differ.
+ */
+export interface BlockTextureRender {
+  /** Source texture URL or preloaded HTMLImageElement. */
+  source: string | HTMLImageElement
+  top: BlockFaceSlice
+  left: BlockFaceSlice
+  right: BlockFaceSlice
+}
+
 export interface ItemStack {
   type: number
   count: number
@@ -19,6 +40,17 @@ export interface ItemStack {
    * Example: `"item/dye_black"` or `"entity/spider/spider"`
    */
   textureKey?: string
+  /**
+   * Direct texture override. When set, bypasses getItemTextureUrl.
+   * - `string`: URL (data URL or http) used as img src.
+   * - `HTMLImageElement`: preloaded image, drawn directly.
+   */
+  texture?: string | HTMLImageElement
+  /**
+   * Block-style isometric render. When set, ItemCanvas uses a canvas pool to composite
+   * top/left/right face slices into the icon. Use in mineflayer itemMapper for blocks.
+   */
+  blockTexture?: BlockTextureRender
   /**
    * Arbitrary debug identifier exposed as a `data-debug` attribute on the slot element.
    * The mineflayer connector sets this to `"<type>:<metadata>"` by default, making it easy