minecraft-renderer 0.1.84 → 0.1.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.84",
+  "version": "0.1.86",
   "description": "The most Modular Minecraft world renderer with Three.js WebGL backend",
   "type": "module",
   "main": "./dist/index.js",

package/src/lib/worldrendererCommon.ts

@@ -676,6 +676,13 @@ export abstract class WorldRendererCommon<WorkerSend = any, WorkerReceive = any>
       const heightmap = new Int16Array(data.heightmap)
       this.reactiveState.world.heightmaps[data.key] = heightmap
     }
+
+    if (data.type === 'neighborDataArrived') {
+      const sectionHeight = this.getSectionHeight()
+      for (let y = this.worldMinYRender; y < this.worldSizeParams.worldHeight; y += sectionHeight) {
+        this.setSectionDirty(new Vec3(data.x, y, data.z))
+      }
+    }
   }
 
   downloadMesherLog() {

package/src/mesher-shared/shared.ts

@@ -105,7 +105,12 @@ export interface MesherMainEvents {
     // Per-event counts for the column-mode conversion cache.
     preCacheHits?: number
     preCacheMisses?: number
+    chunkCount?: number
+    worldColumns3x3?: number
+    parsedCache3x3?: number
+    columnMeshPath?: string
   }
+  neighborDataArrived: { type: 'neighborDataArrived'; x: number; z: number; workerIndex: number }
   blockStateModelInfo: { type: 'blockStateModelInfo'; info: Record<string, BlockStateModelInfo> }
   heightmap: { type: 'heightmap'; key: string; heightmap: Int16Array }
   /** Reply to `{ type: 'mc-web-ping', t?, workerIndex? }` from the main thread (not batched in worker). */

package/src/three/modules/starfield.ts

@@ -9,7 +9,7 @@ const threeVersion = parseInt(THREE.REVISION.replaceAll(/\D+/g, ''), 10)
 class StarfieldMaterial extends THREE.ShaderMaterial {
   constructor() {
     super({
-      uniforms: { time: { value: 0 }, fade: { value: 1 } },
+      uniforms: { time: { value: 0 } },
       vertexShader: /* glsl */ `
         uniform float time;
         attribute float size;
@@ -23,13 +23,9 @@ class StarfieldMaterial extends THREE.ShaderMaterial {
         }`,
       fragmentShader: /* glsl */ `
         uniform sampler2D pointTexture;
-        uniform float fade;
         varying vec3 vColor;
         void main() {
-          // fade scales star brightness (0 = invisible). With additive blending this is
-          // the only way to dim stars — scene fog never reaches this shader. Driven by the
-          // rain state so stars disappear in rain like in vanilla.
-          gl_FragColor = vec4(vColor * fade, 1.0);
+          gl_FragColor = vec4(vColor, 1.0);
 
           #include <tonemapping_fragment>
           #include <${threeVersion >= 154 ? 'colorspace_fragment' : 'encodings_fragment'}>
@@ -43,8 +39,6 @@ export class StarfieldModule implements RendererModuleController {
   private timer = new THREE.Timer()
   private enabled = false
   private currentTime?: number
-  /** Current star brightness multiplier; lerps toward 0 while raining, 1 otherwise. */
-  private fade = 1
 
   constructor(private readonly worldRenderer: WorldRendererThree) {}
 
@@ -76,20 +70,13 @@ export class StarfieldModule implements RendererModuleController {
     return this.currentTime > nightTime && this.currentTime < morningStart
   }
 
-  render?: (deltaTime: number) => void = deltaTime => {
+  render?: (deltaTime: number) => void = () => {
     if (!this.points) return
     this.points.position.set(0, 0, 0)
 
     const material = this.points.material as StarfieldMaterial
     this.timer.update(performance.now())
     material.uniforms.time.value = this.timer.getElapsed() * 0.2
-
-    // Fade stars out while raining (vanilla scales star brightness by 1 - rainLevel).
-    // isRaining is a boolean here, so ease toward the target instead of snapping.
-    const target = this.worldRenderer.worldRendererConfig.isRaining ? 0 : 1
-    const t = Math.min(1, deltaTime * 2)
-    this.fade += (target - this.fade) * t
-    material.uniforms.fade.value = this.fade
   }
 
   /**

package/src/wasm-mesher/bridge/render-from-wasm.ts

@@ -559,13 +559,21 @@ export function renderWasmOutputToGeometry(
   const uvs: number[] = []
   const indices: number[] = []
 
-  const blendPositions: number[] = []
-  const blendNormals: number[] = []
-  const blendColors: number[] = []
-  const blendSkyLights: number[] = []
-  const blendBlockLights: number[] = []
-  const blendUvs: number[] = []
-  const blendIndices: number[] = []
+  const blockBlendPositions: number[] = []
+  const blockBlendNormals: number[] = []
+  const blockBlendColors: number[] = []
+  const blockBlendSkyLights: number[] = []
+  const blockBlendBlockLights: number[] = []
+  const blockBlendUvs: number[] = []
+  const blockBlendIndices: number[] = []
+
+  const liquidPositions: number[] = []
+  const liquidNormals: number[] = []
+  const liquidColors: number[] = []
+  const liquidSkyLights: number[] = []
+  const liquidBlockLights: number[] = []
+  const liquidUvs: number[] = []
+  const liquidIndices: number[] = []
 
   const liquidQueue: Array<{
     pos: Vec3
@@ -691,13 +699,13 @@ export function renderWasmOutputToGeometry(
     if (!models || models.length == 0) continue
 
     const routeToBlend = prismBlock.transparent && isSemiTransparentBlockName(cachedModel.blockName)
-    const tgtPos = routeToBlend ? blendPositions : positions
-    const tgtNorm = routeToBlend ? blendNormals : normals
-    const tgtCol = routeToBlend ? blendColors : colors
-    const tgtSky = routeToBlend ? blendSkyLights : skyLights
-    const tgtBlock = routeToBlend ? blendBlockLights : blockLights
-    const tgtUv = routeToBlend ? blendUvs : uvs
-    const tgtIdx = routeToBlend ? blendIndices : indices
+    const tgtPos = routeToBlend ? blockBlendPositions : positions
+    const tgtNorm = routeToBlend ? blockBlendNormals : normals
+    const tgtCol = routeToBlend ? blockBlendColors : colors
+    const tgtSky = routeToBlend ? blockBlendSkyLights : skyLights
+    const tgtBlock = routeToBlend ? blockBlendBlockLights : blockLights
+    const tgtUv = routeToBlend ? blockBlendUvs : uvs
+    const tgtIdx = routeToBlend ? blockBlendIndices : indices
 
     const faceNameToIndex: Record<string, number> = {
       up: 0,
@@ -947,17 +955,39 @@ export function renderWasmOutputToGeometry(
         q.biome,
         q.water,
         q.isRealWater,
-        blendPositions,
-        blendNormals,
-        blendColors,
-        blendSkyLights,
-        blendBlockLights,
-        blendUvs,
-        blendIndices
+        liquidPositions,
+        liquidNormals,
+        liquidColors,
+        liquidSkyLights,
+        liquidBlockLights,
+        liquidUvs,
+        liquidIndices
       )
     }
   }
 
+  let blendPositions: number[] = []
+  let blendNormals: number[] = []
+  let blendColors: number[] = []
+  let blendSkyLights: number[] = []
+  let blendBlockLights: number[] = []
+  let blendUvs: number[] = []
+  const blendIndices: number[] = []
+
+  if (liquidPositions.length > 0 || blockBlendPositions.length > 0) {
+    const liquidVertexCount = liquidPositions.length / 3
+    blendPositions = liquidPositions.concat(blockBlendPositions)
+    blendNormals = liquidNormals.concat(blockBlendNormals)
+    blendColors = liquidColors.concat(blockBlendColors)
+    blendSkyLights = liquidSkyLights.concat(blockBlendSkyLights)
+    blendBlockLights = liquidBlockLights.concat(blockBlendBlockLights)
+    blendUvs = liquidUvs.concat(blockBlendUvs)
+    blendIndices.push(...liquidIndices)
+    for (const idx of blockBlendIndices) {
+      blendIndices.push(idx + liquidVertexCount)
+    }
+  }
+
   const shaderCubes = buildShaderCubesFromWords(shaderWordBuffer)
 
   const result: ExportedSection = {

package/src/wasm-mesher/tests/blendEmissionOrder.test.ts

@@ -0,0 +1,123 @@
+//@ts-nocheck
+import { beforeAll, beforeEach, expect, test } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import Chunks from 'prismarine-chunk'
+import MinecraftData from 'minecraft-data'
+import { Vec3 } from 'vec3'
+import blocksAtlasesJson from 'mc-assets/dist/blocksAtlases.json'
+import blockStatesModels from 'mc-assets/dist/blockStatesModels.json'
+import { World } from '../../mesher-shared/world'
+import { setBlockStatesData } from '../../mesher-shared/models'
+import { resetFaceOcclusionCache } from '../../mesher-shared/faceOcclusion'
+import { convertChunkToWasm, getBlockMeta } from '../bridge/convertChunk'
+import { renderWasmOutputToGeometry } from '../bridge/render-from-wasm'
+
+const VERSION = '1.17.1'
+const SECTION_Y = 0
+const ICE_Y = 2
+const WATER_Y = 1
+const WORLD_MIN_Y = 0
+const WORLD_MAX_Y = 256
+const COLUMN_HEIGHT = WORLD_MAX_Y - WORLD_MIN_Y
+
+let wasmModule: typeof import('../runtime-build/wasm_mesher.js')
+
+beforeAll(async () => {
+  wasmModule = await import('../runtime-build/wasm_mesher.js')
+  const wasmDir = dirname(fileURLToPath(import.meta.url))
+  const wasmBytes = readFileSync(join(wasmDir, '../runtime-build/wasm_mesher_bg.wasm'))
+  wasmModule.initSync(wasmBytes)
+})
+
+beforeEach(() => {
+  resetFaceOcclusionCache()
+  const mcData = MinecraftData(VERSION)
+  setBlockStatesData(blockStatesModels, blocksAtlasesJson, false, true, VERSION, { blocks: mcData.blocksArray })
+  ;(globalThis as any).__wasmBlockModelCache = new Map()
+})
+
+function resolveStateId(name: string) {
+  const mcData = MinecraftData(VERSION)
+  const block = mcData.blocksByName[name]
+  if (!block) throw new Error(`Unknown block: ${name}`)
+  return block.defaultState
+}
+
+function buildIceOverWaterWorld(): World {
+  const Chunk = Chunks(VERSION) as any
+  const chunk = new Chunk(undefined as any)
+  const iceId = resolveStateId('ice')
+  const waterId = resolveStateId('water')
+
+  for (let z = 0; z < 16; z++) {
+    for (let x = 0; x < 16; x++) {
+      chunk.setBlockStateId(new Vec3(x, WATER_Y, z), waterId)
+      chunk.setBlockStateId(new Vec3(x, ICE_Y, z), iceId)
+      chunk.setBlockLight(new Vec3(x, ICE_Y, z), 15)
+      chunk.setSkyLight(new Vec3(x, ICE_Y, z), 15)
+      chunk.setBlockLight(new Vec3(x, WATER_Y, z), 15)
+      chunk.setSkyLight(new Vec3(x, WATER_Y, z), 15)
+    }
+  }
+
+  const world = new World(VERSION)
+  world.addColumn(0, 0, chunk.toJson())
+  return world
+}
+
+function findLiquidBeforeBlockIndexSplit(indices: number[]) {
+  for (let split = 1; split < indices.length; split++) {
+    const prefix = indices.slice(0, split)
+    const suffix = indices.slice(split)
+    const maxPrefix = Math.max(...prefix)
+    const minSuffix = Math.min(...suffix)
+    if (maxPrefix < minSuffix) {
+      return { split, liquidVertexCount: minSuffix }
+    }
+  }
+  return null
+}
+
+test('blend emission order: liquid quads precede ice block quads in the index buffer', () => {
+  const world = buildIceOverWaterWorld()
+  const meta = getBlockMeta(VERSION)
+  const column = world.getColumn(0, 0)!
+  const conversion = convertChunkToWasm(column, VERSION, 0, 0, WORLD_MIN_Y, WORLD_MAX_Y)
+  const wasmResult = wasmModule.generate_geometry(
+    0,
+    WORLD_MIN_Y,
+    0,
+    COLUMN_HEIGHT,
+    WORLD_MIN_Y,
+    WORLD_MAX_Y,
+    WORLD_MIN_Y,
+    conversion.blockStates,
+    conversion.blockLight,
+    conversion.skyLight,
+    conversion.biomesArray,
+    meta.invisibleBlocks,
+    meta.transparentBlocks,
+    meta.noAoBlocks,
+    meta.cullIdenticalBlocks,
+    meta.occludingBlocks,
+    true,
+    false,
+    15
+  )
+
+  const section = renderWasmOutputToGeometry(wasmResult, VERSION, `0,${SECTION_Y},0`, { x: 8, y: 8, z: 8 }, world, {
+    sectionHeight: 16,
+    shaderCubes: false
+  })
+
+  const blend = section.blendGeometry
+  expect(blend).toBeDefined()
+  expect(blend!.indices.length).toBeGreaterThan(0)
+
+  const split = findLiquidBeforeBlockIndexSplit(blend!.indices)
+  expect(split).not.toBeNull()
+  expect(split!.split).toBeGreaterThan(0)
+  expect(split!.liquidVertexCount).toBeGreaterThan(0)
+})

package/src/wasm-mesher/tests/crossColumnCulling.test.ts

@@ -0,0 +1,205 @@
+//@ts-nocheck
+import { beforeAll, beforeEach, describe, expect, test } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import Chunks from 'prismarine-chunk'
+import MinecraftData from 'minecraft-data'
+import { Vec3 } from 'vec3'
+import PrismarineBlockLoader from 'prismarine-block'
+import blocksAtlasesJson from 'mc-assets/dist/blocksAtlases.json'
+import blockStatesModels from 'mc-assets/dist/blockStatesModels.json'
+import { setBlockStatesData } from '../../mesher-shared/models'
+import { resetFaceOcclusionCache } from '../../mesher-shared/faceOcclusion'
+import { convertChunkToWasm, getBlockMeta } from '../bridge/convertChunk'
+import type { WasmGeometryOutput } from '../bridge/render-from-wasm'
+
+const VERSION = '1.17.1'
+const ICE_Y = 62
+const WATER_Y = 61
+const WORLD_MIN_Y = 0
+// Full overworld height (256) makes multi-column WASM meshing exceed CI's 5s
+// default timeout. Culling only needs the section band that contains ice/water.
+const WORLD_MAX_Y = 80
+const COLUMN_HEIGHT = WORLD_MAX_Y - WORLD_MIN_Y
+
+const EAST_FACE = 1 << 2
+const WEST_FACE = 1 << 3
+
+let wasmModule: typeof import('../runtime-build/wasm_mesher.js')
+
+beforeAll(async () => {
+  wasmModule = await import('../runtime-build/wasm_mesher.js')
+  const wasmDir = dirname(fileURLToPath(import.meta.url))
+  const wasmBytes = readFileSync(join(wasmDir, '../runtime-build/wasm_mesher_bg.wasm'))
+  wasmModule.initSync(wasmBytes)
+})
+
+beforeEach(() => {
+  resetFaceOcclusionCache()
+  const mcData = MinecraftData(VERSION)
+  setBlockStatesData(blockStatesModels, blocksAtlasesJson, false, true, VERSION, { blocks: mcData.blocksArray })
+  ;(globalThis as any).__wasmBlockModelCache = new Map()
+})
+
+function resolveStateId(name: string) {
+  const mcData = MinecraftData(VERSION)
+  const block = mcData.blocksByName[name]
+  if (!block) throw new Error(`Unknown block: ${name}`)
+  return block.defaultState
+}
+
+function buildIceOverWaterColumn() {
+  const Chunk = Chunks(VERSION) as any
+  const chunk = new Chunk(undefined as any)
+  const iceId = resolveStateId('ice')
+  const waterId = resolveStateId('water')
+
+  for (let z = 0; z < 16; z++) {
+    for (let x = 0; x < 16; x++) {
+      chunk.setBlockStateId(new Vec3(x, WATER_Y, z), waterId)
+      chunk.setBlockStateId(new Vec3(x, ICE_Y, z), iceId)
+      chunk.setBlockLight(new Vec3(x, ICE_Y, z), 15)
+      chunk.setSkyLight(new Vec3(x, ICE_Y, z), 15)
+    }
+  }
+  return chunk.toJson()
+}
+
+function meshColumns(columnOrigins: Array<{ x: number; z: number }>, targetX: number, targetZ: number, options?: { forceMulti?: boolean }): WasmGeometryOutput {
+  const meta = getBlockMeta(VERSION)
+  const conversions = columnOrigins.map(({ x, z }) => {
+    const chunkJson = buildIceOverWaterColumn()
+    return convertChunkToWasm(chunkJson, VERSION, x, z, WORLD_MIN_Y, WORLD_MAX_Y)
+  })
+
+  if (conversions.length === 1 && !options?.forceMulti) {
+    const c = conversions[0]
+    return wasmModule.generate_geometry(
+      targetX,
+      WORLD_MIN_Y,
+      targetZ,
+      COLUMN_HEIGHT,
+      WORLD_MIN_Y,
+      WORLD_MAX_Y,
+      WORLD_MIN_Y,
+      c.blockStates,
+      c.blockLight,
+      c.skyLight,
+      c.biomesArray,
+      meta.invisibleBlocks,
+      meta.transparentBlocks,
+      meta.noAoBlocks,
+      meta.cullIdenticalBlocks,
+      meta.occludingBlocks,
+      true,
+      false,
+      15
+    ) as WasmGeometryOutput
+  }
+
+  const perChunkLen = conversions[0].blockStates.length
+  const xs = new Int32Array(columnOrigins.length)
+  const zs = new Int32Array(columnOrigins.length)
+  const blockStatesAll = new Uint16Array(perChunkLen * columnOrigins.length)
+  const blockLightAll = new Uint8Array(perChunkLen * columnOrigins.length)
+  const skyLightAll = new Uint8Array(perChunkLen * columnOrigins.length)
+  const biomesAll = new Uint8Array(perChunkLen * columnOrigins.length)
+
+  for (let i = 0; i < columnOrigins.length; i++) {
+    const c = conversions[i]
+    xs[i] = columnOrigins[i].x
+    zs[i] = columnOrigins[i].z
+    blockStatesAll.set(c.blockStates, perChunkLen * i)
+    blockLightAll.set(c.blockLight, perChunkLen * i)
+    skyLightAll.set(c.skyLight, perChunkLen * i)
+    biomesAll.set(c.biomesArray, perChunkLen * i)
+  }
+
+  const first = conversions[0]
+  return (wasmModule as any).generate_geometry_multi(
+    targetX,
+    WORLD_MIN_Y,
+    targetZ,
+    COLUMN_HEIGHT,
+    WORLD_MIN_Y,
+    WORLD_MAX_Y,
+    WORLD_MIN_Y,
+    xs,
+    zs,
+    blockStatesAll,
+    blockLightAll,
+    skyLightAll,
+    biomesAll,
+    first.invisibleBlocks,
+    first.transparentBlocks,
+    first.noAoBlocks,
+    first.cullIdenticalBlocks,
+    first.occludingBlocks,
+    true,
+    false,
+    15
+  ) as WasmGeometryOutput
+}
+
+function countIceBorderFaces(output: WasmGeometryOutput, iceStateId: number, planeX: number, faceBit: number) {
+  let count = 0
+  for (const block of output.blocks) {
+    if (block.block_state_id !== iceStateId) continue
+    const [bx, by] = block.position
+    if (bx !== planeX || by !== ICE_Y) continue
+    if ((block.visible_faces & faceBit) !== 0) count++
+  }
+  return count
+}
+
+describe('cross-column ice culling', { timeout: 15_000 }, () => {
+  test('two adjacent columns produce zero border faces', () => {
+    const iceStateId = resolveStateId('ice')
+    const output = meshColumns(
+      [
+        { x: 0, z: 0 },
+        { x: 16, z: 0 }
+      ],
+      0,
+      0
+    )
+
+    expect(countIceBorderFaces(output, iceStateId, 15, EAST_FACE)).toBe(0)
+    expect(countIceBorderFaces(output, iceStateId, 16, WEST_FACE)).toBe(0)
+  })
+
+  test('negative coordinates', () => {
+    const iceStateId = resolveStateId('ice')
+    const ax = -504928
+    const bx = ax + 16
+    const z = 496768
+    const output = meshColumns(
+      [
+        { x: ax, z },
+        { x: bx, z }
+      ],
+      ax,
+      z
+    )
+
+    expect(countIceBorderFaces(output, iceStateId, ax + 15, EAST_FACE)).toBe(0)
+    expect(countIceBorderFaces(output, iceStateId, bx, WEST_FACE)).toBe(0)
+  })
+
+  test('healed mesh has fewer blocks at the shared boundary plane', () => {
+    const alone = meshColumns([{ x: 0, z: 0 }], 0, 0, { forceMulti: true })
+    const pair = meshColumns(
+      [
+        { x: 0, z: 0 },
+        { x: 16, z: 0 }
+      ],
+      0,
+      0
+    )
+    const aloneBoundaryBlocks = alone.blocks.filter(b => b.position[0] === 15 && b.position[1] === ICE_Y).length
+    const pairBoundaryBlocks = pair.blocks.filter(b => b.position[0] === 15 && b.position[1] === ICE_Y).length
+    expect(aloneBoundaryBlocks).toBeGreaterThanOrEqual(pairBoundaryBlocks)
+    expect(pair.blocks.filter(b => b.position[0] === 16 && b.position[1] === ICE_Y && (b.visible_faces & WEST_FACE) !== 0).length).toBe(0)
+  })
+})

package/src/wasm-mesher/tests/mesherWasmChunkBuffer.test.ts

@@ -0,0 +1,24 @@
+//@ts-nocheck
+import { describe, expect, test } from 'vitest'
+import { PendingChunkBuffer } from '../worker/mesherWasmChunkBuffer'
+
+describe('PendingChunkBuffer', () => {
+  test('buffers chunk messages until drained', () => {
+    const buffer = new PendingChunkBuffer()
+    buffer.enqueue({ x: 0, z: 0, chunk: { sections: [] } })
+    buffer.enqueue({ x: 16, z: 0, chunk: { sections: [] } })
+    expect(buffer.size).toBe(2)
+
+    const applied: number[] = []
+    buffer.drain(msg => applied.push(msg.x))
+    expect(applied).toEqual([0, 16])
+    expect(buffer.size).toBe(0)
+  })
+
+  test('clear drops pending messages', () => {
+    const buffer = new PendingChunkBuffer()
+    buffer.enqueue({ x: 0, z: 0, chunk: {} })
+    buffer.clear()
+    expect(buffer.size).toBe(0)
+  })
+})

package/src/wasm-mesher/tests/mesherWasmNeighborhood.test.ts

@@ -0,0 +1,91 @@
+//@ts-nocheck
+import { describe, expect, test } from 'vitest'
+import {
+  PendingNeighborHealTracker,
+  collectChunksForColumnUnion,
+  columnDataAvailable,
+  countParsedCache3x3,
+  countWorldColumns3x3
+} from '../worker/mesherWasmNeighborhood'
+
+describe('collectChunksForColumnUnion', () => {
+  test('includes cache-only side neighbors not yet in world.columns', () => {
+    const worldCols = new Map<string, any>([['0,0', { id: 'A' }]])
+    const packet = new Set(['16,0'])
+
+    const result = collectChunksForColumnUnion(0, 0, (x, z) => worldCols.get(`${x},${z}`) ?? null, { raw: packet, v17: new Set(), v16: new Set() })
+
+    expect(result).toHaveLength(2)
+    expect(result[0]).toEqual({ x: 0, z: 0, chunk: { id: 'A' } })
+    expect(result[1]).toEqual({ x: 16, z: 0, chunk: null })
+  })
+
+  test('returns full 3x3 when both pipelines are complete', () => {
+    const worldCols = new Map<string, any>()
+    const packet = new Set<string>()
+    for (const dx of [-16, 0, 16]) {
+      for (const dz of [-16, 0, 16]) {
+        worldCols.set(`${dx},${dz}`, {})
+        packet.add(`${dx},${dz}`)
+      }
+    }
+
+    const result = collectChunksForColumnUnion(0, 0, (x, z) => worldCols.get(`${x},${z}`) ?? null, {
+      raw: packet,
+      v17: new Set(),
+      v16: new Set()
+    })
+
+    expect(result).toHaveLength(9)
+  })
+})
+
+describe('column availability counters', () => {
+  test('detects pipeline A lag behind packet caches', () => {
+    const worldCols = new Map<string, any>([
+      ['0,0', {}],
+      ['16,0', {}],
+      ['-16,0', {}],
+      ['0,16', {}]
+    ])
+    const packet = new Set(['0,0', '16,0', '-16,0', '0,16', '0,-16', '16,16', '-16,16', '-16,-16', '16,-16'])
+    const caches = { raw: packet, v17: new Set(), v16: new Set() }
+
+    expect(countWorldColumns3x3(0, 0, (x, z) => worldCols.get(`${x},${z}`) ?? null)).toBe(4)
+    expect(countParsedCache3x3(0, 0, caches)).toBe(9)
+    expect(columnDataAvailable(0, -16, (x, z) => worldCols.get(`${x},${z}`) ?? null, caches)).toBe(true)
+    expect(columnDataAvailable(16, 16, (x, z) => worldCols.get(`${x},${z}`) ?? null, caches)).toBe(true)
+  })
+})
+
+describe('PendingNeighborHealTracker', () => {
+  test('queues and releases columns awaiting a missing neighbor', () => {
+    const tracker = new PendingNeighborHealTracker()
+    tracker.recordMissingSide(0, 0, 16, 0)
+    tracker.recordMissingSide(0, 16, 16, 0)
+
+    expect(tracker.takeColumnsAwaitingNeighbor(16, 0).sort((a, b) => a.z - b.z)).toEqual([
+      { x: 0, z: 0 },
+      { x: 0, z: 16 }
+    ])
+    expect(tracker.takeColumnsAwaitingNeighbor(16, 0)).toEqual([])
+  })
+
+  test('clears column references on unload', () => {
+    const tracker = new PendingNeighborHealTracker()
+    tracker.recordMissingSide(0, 0, 16, 0)
+    tracker.clearColumn(0, 0)
+    expect(tracker.takeColumnsAwaitingNeighbor(16, 0)).toEqual([])
+  })
+
+  test('union grows when packet cache arrives for a missing side neighbor (I1 heal)', () => {
+    const worldCols = new Map<string, any>([['0,0', {}]])
+    const v17 = new Set<string>()
+    const caches = { raw: new Set<string>(), v17, v16: new Set<string>() }
+    const getColumn = (x: number, z: number) => worldCols.get(`${x},${z}`) ?? null
+
+    expect(collectChunksForColumnUnion(0, 0, getColumn, caches)).toHaveLength(1)
+    v17.add('16,0')
+    expect(collectChunksForColumnUnion(0, 0, getColumn, caches)).toHaveLength(2)
+  })
+})