minecraft-renderer 0.1.38 → 0.1.39

package/src/mesher/mesherWasmConversionCache.ts

@@ -0,0 +1,155 @@
+//@ts-nocheck
+// Worker-side cache for `convertChunkToWasm` outputs in column mode.
+//
+// In column-mode meshing, every dirty column triggers a 3x3 conversion
+// (target + up to 8 neighbors). During the initial-load wave each column ends
+// up being converted up to 9 times (once for itself, once per surrounding
+// column that lists it as a neighbor). This cache short-circuits the
+// redundant conversions.
+//
+// Correctness invariants:
+// - Cache value MUST NOT be mutated by consumers. The `ChunkConversionResult`
+//   typed arrays are used as `set()` SOURCES (and as wasm INPUTS) in the
+//   mesher tick, never as destinations, so the read-only contract holds.
+// - Identity-based key validation: a hit is served only when the stored
+//   chunk reference is `===` the live `world.getColumn(x,z)` reference, so a
+//   replaced column (via `world.addColumn`) can never accidentally serve
+//   stale data even if the explicit invalidation in the message handler is
+//   skipped (defense in depth).
+// - In-place mutation of an existing column object (e.g. via
+//   `world.setBlockStateId` from a `blockUpdate` message) preserves identity
+//   but changes content. The `blockUpdate` handler explicitly invalidates
+//   the affected `(chunkX, chunkZ)` to handle this.
+
+import type { ChunkConversionResult } from '../wasm-lib/convertChunk'
+
+// Hard cap on entries. A 12x12 visible area ≈ 144 columns; 64 keeps the hot
+// ~8x8 window resident. Tunable.
+export const CONVERSION_CACHE_LIMIT = 64
+
+// Active limit, mutable via `setConversionCacheLimit`. `0` disables caching
+// entirely (memory hotfix path for low-RAM environments such as iOS Safari).
+let activeLimit = CONVERSION_CACHE_LIMIT
+
+interface CacheEntry {
+  chunkRef: any
+  version: string
+  worldMinY: number
+  worldMaxY: number
+  result: ChunkConversionResult
+}
+
+const cache = new Map<string, CacheEntry>()
+let hits = 0
+let misses = 0
+
+const keyOf = (x: number, z: number) => `${x},${z}`
+
+const isDev = () => {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    return typeof process === 'undefined' || process.env?.NODE_ENV !== 'production'
+  } catch {
+    return true
+  }
+}
+
+export interface GetOrConvertResult {
+  result: ChunkConversionResult
+  hit: boolean
+}
+
+export function getOrConvertColumn(
+  x: number,
+  z: number,
+  chunkRef: any,
+  version: string,
+  worldMinY: number,
+  worldMaxY: number,
+  convert: () => ChunkConversionResult,
+  liveChunkRef?: any
+): GetOrConvertResult {
+  const k = keyOf(x, z)
+  if (activeLimit <= 0) {
+    // Cache disabled — bypass entirely. Drop any stale entry that may
+    // pre-date the disable call.
+    if (cache.size > 0) cache.delete(k)
+    misses++
+    return { result: convert(), hit: false }
+  }
+  const e = cache.get(k)
+  if (
+    e
+    && e.chunkRef === chunkRef
+    && e.version === version
+    && e.worldMinY === worldMinY
+    && e.worldMaxY === worldMaxY
+  ) {
+    // Defense-in-depth: if the live world ref no longer matches the stored
+    // ref, the explicit invalidation path was missed somewhere upstream.
+    if (liveChunkRef !== undefined && liveChunkRef !== e.chunkRef) {
+      if (isDev()) {
+        console.warn(`[WASM Mesher] conversion cache identity drift at ${k} — invalidation likely missed`)
+      }
+      cache.delete(k)
+    } else {
+      // LRU bump: re-insert to move to most-recent.
+      cache.delete(k)
+      cache.set(k, e)
+      hits++
+      return { result: e.result, hit: true }
+    }
+  }
+
+  const result = convert()
+  cache.delete(k)
+  cache.set(k, { chunkRef, version, worldMinY, worldMaxY, result })
+  while (cache.size > activeLimit) {
+    const oldest = cache.keys().next().value
+    if (oldest === undefined) break
+    cache.delete(oldest)
+  }
+  misses++
+  return { result, hit: false }
+}
+
+export function setConversionCacheLimit(n: number): void {
+  activeLimit = Math.max(0, n | 0)
+  if (activeLimit === 0) {
+    cache.clear()
+    return
+  }
+  while (cache.size > activeLimit) {
+    const oldest = cache.keys().next().value
+    if (oldest === undefined) break
+    cache.delete(oldest)
+  }
+}
+
+export function getConversionCacheLimit(): number {
+  return activeLimit
+}
+
+export function invalidateConversion(x: number, z: number): boolean {
+  return cache.delete(keyOf(x, z))
+}
+
+export function clearConversionCache(): void {
+  cache.clear()
+}
+
+export function getConversionCacheSize(): number {
+  return cache.size
+}
+
+export function consumeConversionCacheStats(): { hits: number, misses: number } {
+  const r = { hits, misses }
+  hits = 0
+  misses = 0
+  return r
+}
+
+// Test-only helper: peek without bumping LRU or mutating counters.
+export function _peekConversionCache(x: number, z: number): CacheEntry | undefined {
+  return cache.get(keyOf(x, z))
+}

package/src/mesher/mesherWasmRequestTracker.ts

@@ -0,0 +1,56 @@
+//@ts-nocheck
+// Tracks requested section keys and their pending dirty counts separately from
+// the section keys that a full-column WASM meshing call can generate.
+//
+// Why this exists:
+//  - The legacy per-section path usually generates exactly the requested key.
+//  - The column path can mesh a whole chunk column and produce data for more
+//    sections than the main thread requested. `WorldRendererCommon` throws on
+//    `sectionFinished` for keys it did not register, so the worker must filter
+//    outgoing `geometry`/`sectionFinished` events through this tracker.
+//  - Each `setSectionDirty(value=true)` is one logical request and must yield
+//    exactly one `sectionFinished` event, mirroring the existing per-key
+//    counter semantics of `dirtySections`.
+
+export class SectionRequestTracker {
+    private readonly counts = new Map<string, number>()
+
+    /** Register one pending request for `key` (called per dirty-section ingest). */
+    addRequest (key: string): void {
+        this.counts.set(key, (this.counts.get(key) ?? 0) + 1)
+    }
+
+    /** True if at least one request for `key` is still pending. */
+    hasPending (key: string): boolean {
+        return (this.counts.get(key) ?? 0) > 0
+    }
+
+    /** Pending request count for `key` (0 if none). */
+    pendingCount (key: string): number {
+        return this.counts.get(key) ?? 0
+    }
+
+    /**
+     * Consume one pending request for `key`. Returns true if a request was
+     * consumed, false if there was nothing pending. Callers in the column
+     * path must treat `false` as a contract violation (the main thread did
+     * not request this key).
+     */
+    consumeOne (key: string): boolean {
+        const c = this.counts.get(key) ?? 0
+        if (c <= 0) return false
+        if (c === 1) this.counts.delete(key)
+        else this.counts.set(key, c - 1)
+        return true
+    }
+
+    /** Clear all pending requests (used on worker reset). */
+    clear (): void {
+        this.counts.clear()
+    }
+
+    /** Number of distinct keys with pending requests. */
+    size (): number {
+        return this.counts.size
+    }
+}

package/src/mesher/models.ts

@@ -8,6 +8,7 @@ import { World, BlockModelPartsResolved, WorldBlock as Block, WorldBlock, worldC
 import { BlockElement, buildRotationMatrix, elemFaces, matmul3, matmulmat3, vecadd3, vecsub3 } from './modelsGeometryCommon'
 import { INVISIBLE_BLOCKS } from './worldConstants'
 import { MesherGeometryOutput, HighestBlockInfo } from './shared'
+import { collectBlockEntityMetadata } from './blockEntityMetadata'
 
 // Log function disabled by default for zero overhead in production hot loops
 const ENABLE_TS_LOGS = false
@@ -598,52 +599,7 @@ export function getSectionGeometry(sx: number, sy: number, sz: number, world: Wo
       for (cursor.x = sx; cursor.x < sx + 16; cursor.x++) {
         let block = world.getBlock(cursor, blockProvider, attr)!
         if (INVISIBLE_BLOCKS.has(block.name)) continue
-        if ((block.name.includes('_sign') || block.name === 'sign') && !world.config.disableBlockEntityTextures) {
-          const key = `${cursor.x},${cursor.y},${cursor.z}`
-          const props: any = block.getProperties()
-          const facingRotationMap = {
-            'north': 2,
-            'south': 0,
-            'west': 1,
-            'east': 3
-          }
-          const isWall = block.name.endsWith('wall_sign') || block.name.endsWith('wall_hanging_sign')
-          const isHanging = block.name.endsWith('hanging_sign')
-          attr.signs[key] = {
-            isWall,
-            isHanging,
-            rotation: isWall ? facingRotationMap[props.facing] : +props.rotation
-          }
-        } else if (block.name === 'player_head' || block.name === 'player_wall_head') {
-          const key = `${cursor.x},${cursor.y},${cursor.z}`
-          const props: any = block.getProperties()
-          const facingRotationMap = {
-            'north': 0,
-            'south': 2,
-            'west': 3,
-            'east': 1
-          }
-          const isWall = block.name === 'player_wall_head'
-          attr.heads[key] = {
-            isWall,
-            rotation: isWall ? facingRotationMap[props.facing] : +props.rotation
-          }
-        } else if (block.name.includes('_banner') && !world.config.disableBlockEntityTextures) {
-          const key = `${cursor.x},${cursor.y},${cursor.z}`
-          const props: any = block.getProperties()
-          const facingRotationMap = {
-            'north': 2,
-            'south': 0,
-            'west': 1,
-            'east': 3
-          }
-          const isWall = block.name.endsWith('_wall_banner')
-          attr.banners[key] = {
-            isWall,
-            blockName: block.name, // Pass block name for base color extraction
-            rotation: isWall ? facingRotationMap[props.facing] : (props.rotation === undefined ? 0 : +props.rotation)
-          }
-        }
+        collectBlockEntityMetadata(block, cursor.x, cursor.y, cursor.z, attr, { disableBlockEntityTextures: world.config.disableBlockEntityTextures })
         const biome = block.biome.name
 
         if (world.preflat) { // 10% perf

package/src/mesher/shared.ts

@@ -1,7 +1,6 @@
 //@ts-nocheck
 import { BlockType } from '../playground/shared'
 
-export const IS_FULL_WORLD_SECTION = false
 export const SECTION_HEIGHT = 16
 
 // only here for easier testing
@@ -18,7 +17,8 @@ export const defaultMesherConfig = {
   // textureSize: 1024, // for testing
   debugModelVariant: undefined as undefined | number[],
   clipWorldBelowY: undefined as undefined | number,
-  disableBlockEntityTextures: false
+  disableBlockEntityTextures: false,
+  disableConversionCache: false,
 }
 
 export type CustomBlockModels = {
@@ -65,7 +65,26 @@ export type MesherGeometryOutput = {
 
 export interface MesherMainEvents {
   geometry: { type: 'geometry'; key: string; geometry: MesherGeometryOutput; workerIndex: number };
-  sectionFinished: { type: 'sectionFinished'; key: string; workerIndex: number; processTime?: number };
+  sectionFinished: {
+    type: 'sectionFinished';
+    key: string;
+    workerIndex: number;
+    processTime?: number;
+    pre?: number;
+    wasm?: number;
+    post?: number;
+    // Pre-stage substages (added for column-mode perf instrumentation).
+    // All times in ms. `preNeighborConvert` is a SUM across neighbors;
+    // divide by `preNeighborCount` for per-neighbor average.
+    preTargetConvert?: number;
+    preNeighborConvert?: number;
+    preNeighborCount?: number;
+    preTypedArrayBuild?: number;
+    preOther?: number;
+    // Per-event counts for the column-mode conversion cache.
+    preCacheHits?: number;
+    preCacheMisses?: number;
+  };
   blockStateModelInfo: { type: 'blockStateModelInfo'; info: Record<string, BlockStateModelInfo> };
   heightmap: { type: 'heightmap'; key: string; heightmap: Int16Array };
 }

package/src/mesher/test/heightmapParity.test.ts

@@ -0,0 +1,231 @@
+//@ts-nocheck
+import { test, expect } from 'vitest'
+import Chunks from 'prismarine-chunk'
+import MinecraftData from 'minecraft-data'
+import { Vec3 } from 'vec3'
+import { World } from '../world'
+import { computeHeightmap } from '../computeHeightmap'
+import { INVISIBLE_BLOCKS } from '../worldConstants'
+import { extractColumnHeightmap, WasmGeometryOutput } from '../../wasm-lib/render-from-wasm'
+
+// ---------------------------------------------------------------------------
+// Heightmap parity test
+//
+// Verifies that the (future) Rust full-column heightmap (as exposed via the
+// `extractColumnHeightmap` adapter) yields the same 256-entry Int16Array as
+// the existing JS source-of-truth `computeHeightmap`, for representative
+// chunk fixtures.
+//
+// Strategy:
+//   1. Build a real `World` with known blocks.
+//   2. Run the real JS `computeHeightmap` to get the reference.
+//   3. Simulate Rust's full-column iteration in JS (mirroring
+//      `wasm-mesher/src/mesher.rs::generate_with_world`: scan all
+//      `(y, z, x)` over the full Y range, last write per `(x,z)` wins,
+//      skipping blocks whose state IDs are in the `invisible_blocks`
+//      set — equivalent to `INVISIBLE_BLOCKS` by name) and pack it into
+//      a `WasmGeometryOutput.heightmap` field shaped exactly like Rust
+//      returns it (`Vec<i16>` => plain `number[]`, length 256, indexed
+//      `z*16+x`, sentinel `-32768`).
+//   4. Run the simulated output through the SAME `extractColumnHeightmap`
+//      adapter that the runtime uses, and assert element-wise equality
+//      with the JS heightmap.
+//
+// If parity ever fails here, Rust heightmap usage in `mesherWasm.ts` MUST stay
+// disabled and `getHeightmap` MUST keep using the JS handler.
+// ---------------------------------------------------------------------------
+
+const VERSION = '1.16.5'
+
+type BlockSpec = { x: number, y: number, z: number, name: string }
+
+function buildWorld(blocks: BlockSpec[]): { world: World, invisibleStateIds: Set<number> } {
+  const mcData = MinecraftData(VERSION)
+  const Chunk = Chunks(VERSION) as any
+  const chunk = new Chunk(undefined as any)
+
+  for (const b of blocks) {
+    const id = mcData.blocksByName[b.name]?.defaultState
+    if (id == null) throw new Error(`Unknown block name in fixture: ${b.name}`)
+    chunk.setBlockStateId(new Vec3(b.x, b.y, b.z), id)
+  }
+
+  const world = new World(VERSION)
+  // computeHeightmap requires worldMinY / worldMaxY on world.config; the
+  // defaults (0..256) match the 1.16.5 chunk shape we're using here.
+  world.addColumn(0, 0, chunk.toJson())
+
+  // Build the invisible-state-ID set the way `convertChunkToWasm` does at
+  // runtime: every state ID of every block whose name is in
+  // INVISIBLE_BLOCKS. Used by the Rust simulation below.
+  const invisibleStateIds = new Set<number>()
+  for (const block of mcData.blocksArray) {
+    if (!INVISIBLE_BLOCKS.has(block.name)) continue
+    const min = block.minStateId ?? block.defaultState
+    const max = block.maxStateId ?? block.defaultState
+    for (let id = min; id <= max; id++) invisibleStateIds.add(id)
+  }
+  return { world, invisibleStateIds }
+}
+
+/**
+ * JS port of `Mesher::generate_with_world` heightmap pass — bottom-up
+ * iteration over the full column with last-write-wins per `(x,z)`.
+ * Returns a plain `number[]` matching the on-the-wire shape of Rust's
+ * `Vec<i16>` (length 256, indexed `z*16+x`, sentinel `-32768`).
+ */
+function simulateRustColumnHeightmap(
+  world: World,
+  invisibleStateIds: Set<number>,
+  worldMinY: number,
+  worldMaxY: number
+): number[] {
+  const heightmap = new Array<number>(256).fill(-32768)
+  const column = world.getColumn(0, 0)
+  if (!column) return heightmap
+
+  const pos = new Vec3(0, 0, 0)
+  for (let y = worldMinY; y < worldMaxY; y++) {
+    for (let z = 0; z < 16; z++) {
+      for (let x = 0; x < 16; x++) {
+        pos.x = x
+        pos.y = y
+        pos.z = z
+        const stateId = column.getBlockStateId(pos)
+        if (stateId === 0 || invisibleStateIds.has(stateId)) continue
+        heightmap[z * 16 + x] = y
+      }
+    }
+  }
+  return heightmap
+}
+
+function makeWasmOutputWithHeightmap(heightmap: number[]): WasmGeometryOutput {
+  return {
+    blocks: [],
+    block_count: 0,
+    block_iterations: 0,
+    heightmap,
+  }
+}
+
+function runParity(blocks: BlockSpec[]): { js: Int16Array, rust: Int16Array } {
+  const { world, invisibleStateIds } = buildWorld(blocks)
+  const js = computeHeightmap(world, 0, 0)
+
+  const rustShaped = simulateRustColumnHeightmap(
+    world,
+    invisibleStateIds,
+    world.config.worldMinY,
+    world.config.worldMaxY
+  )
+  const wasmOutput = makeWasmOutputWithHeightmap(rustShaped)
+  const rust = extractColumnHeightmap(wasmOutput)
+  expect(rust).not.toBeNull()
+  return { js, rust: rust! }
+}
+
+test('heightmap parity: flat stone layer at y=5', () => {
+  const blocks: BlockSpec[] = []
+  for (let z = 0; z < 16; z++) {
+    for (let x = 0; x < 16; x++) {
+      blocks.push({ x, y: 5, z, name: 'stone' })
+    }
+  }
+  const { js, rust } = runParity(blocks)
+  expect(rust.length).toBe(256)
+  expect(js.length).toBe(256)
+  expect(Array.from(rust)).toEqual(Array.from(js))
+  // Sanity: every column should report y=5.
+  for (let i = 0; i < 256; i++) expect(js[i]).toBe(5)
+})
+
+test('heightmap parity: varied heights, every column populated (Rust == JS)', () => {
+  // Fully-populated chunk (every (x,z) has at least one block) so we sidestep
+  // the documented empty-column gap captured in the next test.
+  const blocks: BlockSpec[] = []
+  for (let z = 0; z < 16; z++) {
+    for (let x = 0; x < 16; x++) {
+      // Default floor.
+      blocks.push({ x, y: 5, z, name: 'stone' })
+    }
+  }
+  // Layered overrides exercising mid/high/low surfaces and invisible-skipping.
+  blocks.push({ x: 0, y: 64, z: 0, name: 'stone' })
+  blocks.push({ x: 1, y: 70, z: 0, name: 'dirt' })
+  blocks.push({ x: 2, y: 80, z: 0, name: 'oak_log' }) // top wins over y=64 below
+  blocks.push({ x: 2, y: 64, z: 0, name: 'stone' })
+  blocks.push({ x: 5, y: 255, z: 5, name: 'stone' }) // high-Y edge (worldMaxY-1)
+  blocks.push({ x: 6, y: 0, z: 6, name: 'stone' })   // low-Y edge (worldMinY)
+  // Invisible block above a real surface must be skipped on both sides.
+  blocks.push({ x: 7, y: 10, z: 7, name: 'stone' })
+  blocks.push({ x: 7, y: 11, z: 7, name: 'barrier' })
+  blocks.push({ x: 8, y: 12, z: 8, name: 'stone' })
+  blocks.push({ x: 8, y: 13, z: 8, name: 'cave_air' })
+
+  const { js, rust } = runParity(blocks)
+  expect(Array.from(rust)).toEqual(Array.from(js))
+
+  // Spot-check absolute values so a future regression in either side
+  // doesn't silently align them on a wrong shared value.
+  expect(js[0 * 16 + 0]).toBe(64)
+  expect(js[0 * 16 + 1]).toBe(70)
+  expect(js[0 * 16 + 2]).toBe(80)
+  expect(js[5 * 16 + 5]).toBe(255)
+  expect(js[6 * 16 + 6]).toBe(5)  // y=0 stone is below the y=5 floor stone
+  expect(js[7 * 16 + 7]).toBe(10) // barrier above must be skipped
+  expect(js[8 * 16 + 8]).toBe(12) // cave_air above must be skipped
+})
+
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Empty-column parity (post-alignment).
+//
+// Historically `computeHeightmap` returned `0` (== worldMinY) for a fully-
+// empty column, because its loop reads at worldMinY, finds air (truthy block,
+// name in INVISIBLE_BLOCKS), exits the `while` because `blockPos.y > worldMinY`
+// becomes false, and fell through to `heightmap[index] = blockPos.y`
+// (== worldMinY). Rust's mesher writes `-32768` for any column with no
+// non-invisible block, so the two encodings disagreed and the WASM
+// `getHeightmap` runtime switch was blocked on that gap.
+//
+// `computeHeightmap` has since been aligned: it now writes
+// `EMPTY_COLUMN_HEIGHTMAP_SENTINEL` (-32768) for empty columns, matching
+// Rust. This test pins that alignment so a regression can never silently
+// re-introduce the divergence.
+// ---------------------------------------------------------------------------
+test('heightmap parity: empty columns produce the same sentinel (-32768) in JS and Rust', () => {
+  // No blocks at all — fully empty chunk.
+  const { js, rust } = runParity([])
+  for (let i = 0; i < 256; i++) {
+    expect(js[i]).toBe(-32768)
+    expect(rust[i]).toBe(-32768)
+  }
+  expect(Array.from(rust)).toEqual(Array.from(js))
+})
+
+test('extractColumnHeightmap: returns null for missing or wrong-length heightmap (forces JS fallback)', () => {
+  expect(extractColumnHeightmap({ heightmap: null })).toBeNull()
+  expect(extractColumnHeightmap({})).toBeNull()
+  expect(extractColumnHeightmap({ heightmap: [1, 2, 3] })).toBeNull()
+  expect(extractColumnHeightmap(undefined)).toBeNull()
+})
+
+test('extractColumnHeightmap: accepts both number[] and Int16Array shapes', () => {
+  const arr = new Array<number>(256).fill(-32768)
+  arr[0] = 42
+  const fromArr = extractColumnHeightmap({ heightmap: arr })!
+  expect(fromArr).toBeInstanceOf(Int16Array)
+  expect(fromArr[0]).toBe(42)
+  expect(fromArr[1]).toBe(-32768)
+
+  const typed = new Int16Array(256)
+  typed.fill(-32768)
+  typed[5] = 99
+  const fromTyped = extractColumnHeightmap({ heightmap: typed })!
+  expect(fromTyped).toBeInstanceOf(Int16Array)
+  expect(fromTyped[5]).toBe(99)
+  // Must be a copy, not aliased — runtime transfers the buffer to the
+  // main thread and would otherwise detach the cached one.
+  expect(fromTyped).not.toBe(typed)
+})

package/src/mesher/test/mesherWasmConversionCache.test.ts

@@ -0,0 +1,128 @@
+//@ts-nocheck
+import { describe, test, expect, beforeEach, vi } from 'vitest'
+import {
+  CONVERSION_CACHE_LIMIT,
+  _peekConversionCache,
+  clearConversionCache,
+  getOrConvertColumn,
+  invalidateConversion,
+} from '../mesherWasmConversionCache'
+import type { ChunkConversionResult } from '../../wasm-lib/convertChunk'
+
+const makeResult = (tag: number): ChunkConversionResult => ({
+  blockStates: new Uint16Array([tag]),
+  blockLight: new Uint8Array(0),
+  skyLight: new Uint8Array(0),
+  biomesArray: new Uint8Array(0),
+  invisibleBlocks: new Uint16Array(0),
+  transparentBlocks: new Uint16Array(0),
+  noAoBlocks: new Uint16Array(0),
+  cullIdenticalBlocks: new Uint16Array(0),
+  occludingBlocks: new Uint16Array(0),
+  blockCount: 0,
+})
+
+describe('mesherWasmConversionCache', () => {
+  beforeEach(() => {
+    clearConversionCache()
+  })
+
+  test('miss then hit on same chunk ref returns cached result', () => {
+    const ref = { id: 'chunk-a' }
+    let calls = 0
+    const convert = () => {
+      calls++
+      return makeResult(1)
+    }
+    const a = getOrConvertColumn(0, 0, ref, 'v', 0, 256, convert, ref)
+    expect(a.hit).toBe(false)
+    expect(calls).toBe(1)
+    const b = getOrConvertColumn(0, 0, ref, 'v', 0, 256, convert, ref)
+    expect(b.hit).toBe(true)
+    expect(calls).toBe(1)
+    expect(b.result).toBe(a.result)
+  })
+
+  test('miss when chunk reference changes (chunk message replacement)', () => {
+    const ref1 = { id: 'r1' }
+    const ref2 = { id: 'r2' }
+    const r1 = getOrConvertColumn(16, 32, ref1, 'v', 0, 256, () => makeResult(1), ref1)
+    const r2 = getOrConvertColumn(16, 32, ref2, 'v', 0, 256, () => makeResult(2), ref2)
+    expect(r1.hit).toBe(false)
+    expect(r2.hit).toBe(false)
+    expect(r2.result).not.toBe(r1.result)
+  })
+
+  test('explicit invalidation forces recompute', () => {
+    const ref = { id: 'r' }
+    const r1 = getOrConvertColumn(0, 0, ref, 'v', 0, 256, () => makeResult(1), ref)
+    expect(r1.hit).toBe(false)
+    expect(invalidateConversion(0, 0)).toBe(true)
+    const r2 = getOrConvertColumn(0, 0, ref, 'v', 0, 256, () => makeResult(2), ref)
+    expect(r2.hit).toBe(false)
+    expect(_peekConversionCache(0, 0)?.result).toBe(r2.result)
+  })
+
+  test('invalidating a non-existent key returns false', () => {
+    expect(invalidateConversion(999, 999)).toBe(false)
+  })
+
+  test('LRU evicts oldest beyond CONVERSION_CACHE_LIMIT', () => {
+    const refs: any[] = []
+    for (let i = 0; i < CONVERSION_CACHE_LIMIT + 5; i++) {
+      const ref = { id: i }
+      refs.push(ref)
+      getOrConvertColumn(i * 16, 0, ref, 'v', 0, 256, () => makeResult(i), ref)
+    }
+    // The first 5 entries should have been evicted.
+    for (let i = 0; i < 5; i++) {
+      expect(_peekConversionCache(i * 16, 0)).toBeUndefined()
+    }
+    // The most-recent entries remain.
+    for (let i = 5; i < CONVERSION_CACHE_LIMIT + 5; i++) {
+      expect(_peekConversionCache(i * 16, 0)).toBeDefined()
+    }
+  })
+
+  test('hit bumps LRU recency (touched entry survives eviction)', () => {
+    const ref0 = { id: 'keep' }
+    getOrConvertColumn(0, 0, ref0, 'v', 0, 256, () => makeResult(0), ref0)
+    // Fill the cache up to the limit.
+    for (let i = 1; i < CONVERSION_CACHE_LIMIT; i++) {
+      const ref = { id: i }
+      getOrConvertColumn(i * 16, 0, ref, 'v', 0, 256, () => makeResult(i), ref)
+    }
+    // Touch the oldest (0,0) -> it becomes most-recent.
+    const touched = getOrConvertColumn(0, 0, ref0, 'v', 0, 256, () => makeResult(99), ref0)
+    expect(touched.hit).toBe(true)
+    // Insert one more; the new oldest (16,0) should be evicted, not (0,0).
+    const refExtra = { id: 'extra' }
+    getOrConvertColumn(9999, 0, refExtra, 'v', 0, 256, () => makeResult(7), refExtra)
+    expect(_peekConversionCache(0, 0)).toBeDefined()
+    expect(_peekConversionCache(16, 0)).toBeUndefined()
+  })
+
+  test('miss when worldMinY/worldMaxY/version metadata changes', () => {
+    const ref = { id: 'r' }
+    const r1 = getOrConvertColumn(0, 0, ref, 'v1', 0, 256, () => makeResult(1), ref)
+    const r2 = getOrConvertColumn(0, 0, ref, 'v2', 0, 256, () => makeResult(2), ref)
+    const r3 = getOrConvertColumn(0, 0, ref, 'v2', -64, 256, () => makeResult(3), ref)
+    const r4 = getOrConvertColumn(0, 0, ref, 'v2', -64, 320, () => makeResult(4), ref)
+    expect(r1.hit).toBe(false)
+    expect(r2.hit).toBe(false)
+    expect(r3.hit).toBe(false)
+    expect(r4.hit).toBe(false)
+  })
+
+  test('identity drift between stored and live ref triggers warn + miss', () => {
+    const stored = { id: 'old' }
+    const live = { id: 'new' } // simulates a missed invalidation path
+    const r1 = getOrConvertColumn(0, 0, stored, 'v', 0, 256, () => makeResult(1), stored)
+    expect(r1.hit).toBe(false)
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const r2 = getOrConvertColumn(0, 0, stored, 'v', 0, 256, () => makeResult(2), live)
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(r2.hit).toBe(false)
+    warn.mockRestore()
+  })
+})

package/src/mesher/test/run/chunk.ts

@@ -10,8 +10,8 @@ export const getChunk = () => {
   const chunkDataBuffer = Buffer.from(chunkData.data)
 
   const chunk = new Chunk({ minY: 0, worldHeight: 256, x: 0, z: 0 }) as PCChunk
-  // chunk.load(chunkDataBuffer, bitMap, true, groundUp)
-  chunk.setBlockStateId(new Vec3(0, 1, 0), 1)
+  chunk.load(chunkDataBuffer, bitMap, true, groundUp)
+  // chunk.setBlockStateId(new Vec3(0, 1, 0), 1)
   // chunk.setBlockStateId(new Vec3(0, 0, 1), 1)
 
   return chunk