@buley/hexgrid-3d 1.0.0

package/src/wasm/HexGridWasmWrapper.ts

@@ -0,0 +1,753 @@
+/**
+ * TypeScript wrapper for hexgrid-wasm
+ * 
+ * Provides a seamless interface to the Rust/WASM module with
+ * automatic fallback to pure TypeScript implementations.
+ * 
+ * @module wasm/HexGridWasmWrapper
+ */
+
+// Types matching the Rust structs
+export interface WasmCellState {
+  owner: number
+  population: number
+  infectedBy: number
+  infection: number
+  resistance: number
+  flags: number
+}
+
+export interface WasmFluidSource {
+  x: number
+  y: number
+  radius: number
+  density: number
+  velocityX: number
+  velocityY: number
+  color?: [number, number, number]
+}
+
+// WASM module interface (generated by wasm-bindgen)
+interface HexGridWasmModule {
+  HexGridWasm: {
+    new (width: number, height: number): HexGridWasmInstance
+  }
+  FlowFieldWasm: {
+    new (width: number, height: number): FlowFieldWasmInstance
+  }
+}
+
+interface HexGridWasmInstance {
+  get_owner(index: number): number
+  set_owner(index: number, owner: number): void
+  set_population(index: number, population: number): void
+  get_neighbors(index: number): Int32Array
+  step_infection(infectionRate: number, infectionThreshold: number): Uint32Array
+  find_connected_regions(owner: number): Uint32Array
+  find_border_cells(owner: number): Uint32Array
+  find_path(start: number, end: number, ownerFilter: number): Uint32Array
+  get_territory_counts(): Uint32Array
+  compute_gini(): number
+  compute_entropy(): number
+  kmeans_cluster(k: number, iterations: number): Uint32Array
+  size(): number
+  width(): number
+  height(): number
+  clear(): void
+  free(): void
+}
+
+interface FlowFieldWasmInstance {
+  add_source(x: number, y: number, strength: number): void
+  add_vortex(x: number, y: number, strength: number): void
+  sample(x: number, y: number): Float32Array
+  compute_divergence(): Float32Array
+  compute_curl(): Float32Array
+  clear(): void
+  free(): void
+}
+
+/**
+ * Wrapper class that provides TypeScript interface to WASM
+ * with automatic fallback
+ */
+export class HexGridWasmWrapper {
+  private static module: HexGridWasmModule | null = null
+  private static loading: Promise<HexGridWasmModule | null> | null = null
+  private static loadFailed = false
+
+  private wasmInstance: HexGridWasmInstance | null = null
+  private fallbackData: {
+    width: number
+    height: number
+    owners: Uint8Array
+    populations: Float32Array
+    neighborCache: Int32Array[]
+  } | null = null
+
+  private constructor(
+    private readonly width: number,
+    private readonly height: number
+  ) {}
+
+  /**
+   * Load the WASM module
+   */
+  static async loadModule(): Promise<boolean> {
+    if (this.loadFailed) return false
+    if (this.module) return true
+
+    if (this.loading) {
+      const result = await this.loading
+      return result !== null
+    }
+
+    this.loading = (async () => {
+      try {
+        // Try to dynamically import the WASM module
+        const wasmModule = await import('../rust/pkg/hexgrid_wasm')
+        await wasmModule.default()
+        this.module = wasmModule as unknown as HexGridWasmModule
+        console.log('[HexGrid] WASM module loaded successfully')
+        return this.module
+      } catch (error) {
+        console.warn('[HexGrid] WASM module not available, using fallback:', error)
+        this.loadFailed = true
+        return null
+      }
+    })()
+
+    const result = await this.loading
+    return result !== null
+  }
+
+  /**
+   * Create a new HexGrid wrapper
+   */
+  static async create(width: number, height: number): Promise<HexGridWasmWrapper> {
+    const wrapper = new HexGridWasmWrapper(width, height)
+    
+    const hasWasm = await this.loadModule()
+    
+    if (hasWasm && this.module) {
+      wrapper.wasmInstance = new this.module.HexGridWasm(width, height)
+    } else {
+      // Initialize fallback data
+      const size = width * height
+      wrapper.fallbackData = {
+        width,
+        height,
+        owners: new Uint8Array(size),
+        populations: new Float32Array(size),
+        neighborCache: []
+      }
+      
+      // Precompute neighbors
+      for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+          const neighbors = new Int32Array(6).fill(-1)
+          const offset = y % 2 === 1 ? 1 : 0
+          
+          // Odd-r offset coordinates
+          const dirs = y % 2 === 1
+            ? [[1, 0], [0, -1], [-1, -1], [-1, 0], [-1, 1], [0, 1]]
+            : [[1, 0], [1, -1], [0, -1], [-1, 0], [0, 1], [1, 1]]
+          
+          for (let i = 0; i < 6; i++) {
+            const nx = x + dirs[i][0]
+            const ny = y + dirs[i][1]
+            if (nx >= 0 && nx < width && ny >= 0 && ny < height) {
+              neighbors[i] = ny * width + nx
+            }
+          }
+          
+          wrapper.fallbackData.neighborCache.push(neighbors)
+        }
+      }
+    }
+    
+    return wrapper
+  }
+
+  /**
+   * Check if WASM is being used
+   */
+  isUsingWasm(): boolean {
+    return this.wasmInstance !== null
+  }
+
+  /**
+   * Get cell owner
+   */
+  getOwner(index: number): number {
+    if (this.wasmInstance) {
+      return this.wasmInstance.get_owner(index)
+    }
+    return this.fallbackData?.owners[index] ?? 0
+  }
+
+  /**
+   * Set cell owner
+   */
+  setOwner(index: number, owner: number): void {
+    if (this.wasmInstance) {
+      this.wasmInstance.set_owner(index, owner)
+    } else if (this.fallbackData) {
+      this.fallbackData.owners[index] = owner
+    }
+  }
+
+  /**
+   * Set cell population
+   */
+  setPopulation(index: number, population: number): void {
+    if (this.wasmInstance) {
+      this.wasmInstance.set_population(index, population)
+    } else if (this.fallbackData) {
+      this.fallbackData.populations[index] = population
+    }
+  }
+
+  /**
+   * Get neighbors of a cell
+   */
+  getNeighbors(index: number): Int32Array {
+    if (this.wasmInstance) {
+      return this.wasmInstance.get_neighbors(index)
+    }
+    return this.fallbackData?.neighborCache[index] ?? new Int32Array(6).fill(-1)
+  }
+
+  /**
+   * Step the infection simulation
+   */
+  stepInfection(infectionRate: number = 0.1, infectionThreshold: number = 1.0): number[] {
+    if (this.wasmInstance) {
+      return Array.from(this.wasmInstance.step_infection(infectionRate, infectionThreshold))
+    }
+    
+    // Fallback implementation
+    const changed: number[] = []
+    const data = this.fallbackData!
+    const size = data.width * data.height
+    
+    // Simple infection spread (basic fallback)
+    const newOwners = new Uint8Array(data.owners)
+    
+    for (let i = 0; i < size; i++) {
+      if (data.owners[i] === 0) continue
+      
+      const neighbors = data.neighborCache[i]
+      for (const ni of neighbors) {
+        if (ni < 0) continue
+        
+        if (data.owners[ni] !== data.owners[i] && Math.random() < infectionRate) {
+          newOwners[ni] = data.owners[i]
+          changed.push(ni)
+        }
+      }
+    }
+    
+    data.owners = newOwners
+    return changed
+  }
+
+  /**
+   * Find connected regions for an owner
+   */
+  findConnectedRegions(owner: number): number[] {
+    if (this.wasmInstance) {
+      return Array.from(this.wasmInstance.find_connected_regions(owner))
+    }
+    
+    // Fallback: BFS implementation
+    const data = this.fallbackData!
+    const size = data.width * data.height
+    const regionIds = new Array(size).fill(0)
+    const visited = new Array(size).fill(false)
+    let currentRegion = 1
+    
+    for (let start = 0; start < size; start++) {
+      if (visited[start] || data.owners[start] !== owner) continue
+      
+      const queue = [start]
+      visited[start] = true
+      
+      while (queue.length > 0) {
+        const idx = queue.shift()!
+        regionIds[idx] = currentRegion
+        
+        for (const ni of data.neighborCache[idx]) {
+          if (ni < 0 || visited[ni] || data.owners[ni] !== owner) continue
+          visited[ni] = true
+          queue.push(ni)
+        }
+      }
+      
+      currentRegion++
+    }
+    
+    return regionIds
+  }
+
+  /**
+   * Find border cells for an owner
+   */
+  findBorderCells(owner: number): number[] {
+    if (this.wasmInstance) {
+      return Array.from(this.wasmInstance.find_border_cells(owner))
+    }
+    
+    const data = this.fallbackData!
+    const borders: number[] = []
+    
+    for (let i = 0; i < data.owners.length; i++) {
+      if (data.owners[i] !== owner) continue
+      
+      const isBorder = data.neighborCache[i].some(ni => {
+        if (ni < 0) return true
+        return data.owners[ni] !== owner
+      })
+      
+      if (isBorder) borders.push(i)
+    }
+    
+    return borders
+  }
+
+  /**
+   * Find path between two cells
+   */
+  findPath(start: number, end: number, ownerFilter: number = 0): number[] {
+    if (this.wasmInstance) {
+      return Array.from(this.wasmInstance.find_path(start, end, ownerFilter))
+    }
+    
+    // Fallback: A* implementation
+    const data = this.fallbackData!
+    const gScore = new Map<number, number>()
+    const fScore = new Map<number, number>()
+    const cameFrom = new Map<number, number>()
+    const openSet = new Set<number>([start])
+    
+    const heuristic = (a: number, b: number) => {
+      const ax = a % data.width
+      const ay = Math.floor(a / data.width)
+      const bx = b % data.width
+      const by = Math.floor(b / data.width)
+      return Math.abs(bx - ax) + Math.abs(by - ay)
+    }
+    
+    gScore.set(start, 0)
+    fScore.set(start, heuristic(start, end))
+    
+    while (openSet.size > 0) {
+      // Find node with lowest fScore
+      let current = -1
+      let lowestF = Infinity
+      for (const node of openSet) {
+        const f = fScore.get(node) ?? Infinity
+        if (f < lowestF) {
+          lowestF = f
+          current = node
+        }
+      }
+      
+      if (current === end) {
+        // Reconstruct path
+        const path: number[] = [current]
+        while (cameFrom.has(current)) {
+          current = cameFrom.get(current)!
+          path.unshift(current)
+        }
+        return path
+      }
+      
+      openSet.delete(current)
+      
+      for (const neighbor of data.neighborCache[current]) {
+        if (neighbor < 0) continue
+        if (ownerFilter !== 0 && data.owners[neighbor] !== ownerFilter) continue
+        
+        const tentativeG = (gScore.get(current) ?? Infinity) + 1
+        
+        if (tentativeG < (gScore.get(neighbor) ?? Infinity)) {
+          cameFrom.set(neighbor, current)
+          gScore.set(neighbor, tentativeG)
+          fScore.set(neighbor, tentativeG + heuristic(neighbor, end))
+          openSet.add(neighbor)
+        }
+      }
+    }
+    
+    return [] // No path found
+  }
+
+  /**
+   * Get territory counts
+   */
+  getTerritoryCounts(): Map<number, number> {
+    if (this.wasmInstance) {
+      const counts = this.wasmInstance.get_territory_counts()
+      const result = new Map<number, number>()
+      for (let i = 0; i < counts.length; i++) {
+        if (counts[i] > 0) {
+          result.set(i, counts[i])
+        }
+      }
+      return result
+    }
+    
+    const data = this.fallbackData!
+    const counts = new Map<number, number>()
+    for (const owner of data.owners) {
+      if (owner !== 0) {
+        counts.set(owner, (counts.get(owner) ?? 0) + 1)
+      }
+    }
+    return counts
+  }
+
+  /**
+   * Compute Gini coefficient
+   */
+  computeGini(): number {
+    if (this.wasmInstance) {
+      return this.wasmInstance.compute_gini()
+    }
+    
+    const populations = Array.from(this.fallbackData?.populations ?? [])
+      .filter(p => p > 0)
+      .sort((a, b) => a - b)
+    
+    if (populations.length === 0) return 0
+    
+    const n = populations.length
+    let sum = 0
+    
+    for (let i = 0; i < n; i++) {
+      sum += (2 * (i + 1) - n - 1) * populations[i]
+    }
+    
+    const mean = populations.reduce((a, b) => a + b, 0) / n
+    if (mean === 0) return 0
+    
+    return sum / (n * n * mean)
+  }
+
+  /**
+   * Compute Shannon entropy
+   */
+  computeEntropy(): number {
+    if (this.wasmInstance) {
+      return this.wasmInstance.compute_entropy()
+    }
+    
+    const counts = this.getTerritoryCounts()
+    const total = Array.from(counts.values()).reduce((a, b) => a + b, 0)
+    if (total === 0) return 0
+    
+    let entropy = 0
+    for (const count of counts.values()) {
+      if (count > 0) {
+        const p = count / total
+        entropy -= p * Math.log(p)
+      }
+    }
+    
+    return entropy
+  }
+
+  /**
+   * K-means clustering
+   */
+  kmeansCluster(k: number, iterations: number = 20): number[] {
+    if (this.wasmInstance) {
+      return Array.from(this.wasmInstance.kmeans_cluster(k, iterations))
+    }
+    
+    // Fallback implementation
+    const data = this.fallbackData!
+    const positions: Array<{ x: number; y: number; idx: number }> = []
+    
+    for (let i = 0; i < data.owners.length; i++) {
+      if (data.owners[i] !== 0) {
+        positions.push({
+          x: i % data.width,
+          y: Math.floor(i / data.width),
+          idx: i
+        })
+      }
+    }
+    
+    if (positions.length === 0 || k === 0) {
+      return new Array(data.owners.length).fill(0)
+    }
+    
+    // Initialize centroids randomly
+    const centroids: Array<{ x: number; y: number }> = []
+    const shuffled = [...positions].sort(() => Math.random() - 0.5)
+    for (let i = 0; i < Math.min(k, shuffled.length); i++) {
+      centroids.push({ x: shuffled[i].x, y: shuffled[i].y })
+    }
+    
+    const assignments = new Array(positions.length).fill(0)
+    
+    // Run iterations
+    for (let iter = 0; iter < iterations; iter++) {
+      // Assign points to nearest centroid
+      for (let i = 0; i < positions.length; i++) {
+        let minDist = Infinity
+        let bestCluster = 0
+        
+        for (let j = 0; j < centroids.length; j++) {
+          const dx = positions[i].x - centroids[j].x
+          const dy = positions[i].y - centroids[j].y
+          const dist = dx * dx + dy * dy
+          
+          if (dist < minDist) {
+            minDist = dist
+            bestCluster = j
+          }
+        }
+        
+        assignments[i] = bestCluster
+      }
+      
+      // Update centroids
+      const sums = centroids.map(() => ({ x: 0, y: 0, count: 0 }))
+      
+      for (let i = 0; i < positions.length; i++) {
+        const cluster = assignments[i]
+        sums[cluster].x += positions[i].x
+        sums[cluster].y += positions[i].y
+        sums[cluster].count++
+      }
+      
+      for (let j = 0; j < centroids.length; j++) {
+        if (sums[j].count > 0) {
+          centroids[j].x = sums[j].x / sums[j].count
+          centroids[j].y = sums[j].y / sums[j].count
+        }
+      }
+    }
+    
+    // Return cluster assignments for all cells
+    const result = new Array(data.owners.length).fill(0)
+    for (let i = 0; i < positions.length; i++) {
+      result[positions[i].idx] = assignments[i]
+    }
+    
+    return result
+  }
+
+  /**
+   * Get size
+   */
+  size(): number {
+    return this.wasmInstance?.size() ?? (this.width * this.height)
+  }
+
+  /**
+   * Clear all cells
+   */
+  clear(): void {
+    if (this.wasmInstance) {
+      this.wasmInstance.clear()
+    } else if (this.fallbackData) {
+      this.fallbackData.owners.fill(0)
+      this.fallbackData.populations.fill(0)
+    }
+  }
+
+  /**
+   * Dispose resources
+   */
+  dispose(): void {
+    if (this.wasmInstance) {
+      this.wasmInstance.free()
+      this.wasmInstance = null
+    }
+    this.fallbackData = null
+  }
+}
+
+/**
+ * Flow Field WASM Wrapper
+ */
+export class FlowFieldWasmWrapper {
+  private wasmInstance: FlowFieldWasmInstance | null = null
+  private fallbackData: {
+    width: number
+    height: number
+    velocityX: Float32Array
+    velocityY: Float32Array
+  } | null = null
+
+  private constructor(
+    private readonly width: number,
+    private readonly height: number
+  ) {}
+
+  static async create(width: number, height: number): Promise<FlowFieldWasmWrapper> {
+    const wrapper = new FlowFieldWasmWrapper(width, height)
+    
+    const hasWasm = await HexGridWasmWrapper.loadModule()
+    
+    if (hasWasm) {
+      try {
+        const module = await import('../rust/pkg/hexgrid_wasm')
+        wrapper.wasmInstance = new module.FlowFieldWasm(width, height)
+      } catch {
+        // Fall through to fallback
+      }
+    }
+    
+    if (!wrapper.wasmInstance) {
+      const size = width * height
+      wrapper.fallbackData = {
+        width,
+        height,
+        velocityX: new Float32Array(size),
+        velocityY: new Float32Array(size)
+      }
+    }
+    
+    return wrapper
+  }
+
+  isUsingWasm(): boolean {
+    return this.wasmInstance !== null
+  }
+
+  addSource(x: number, y: number, strength: number): void {
+    if (this.wasmInstance) {
+      this.wasmInstance.add_source(x, y, strength)
+      return
+    }
+    
+    const data = this.fallbackData!
+    for (let j = 0; j < data.height; j++) {
+      for (let i = 0; i < data.width; i++) {
+        const dx = i - x
+        const dy = j - y
+        const distSq = dx * dx + dy * dy + 0.0001
+        const dist = Math.sqrt(distSq)
+        
+        const idx = j * data.width + i
+        data.velocityX[idx] += strength * dx / (dist * distSq)
+        data.velocityY[idx] += strength * dy / (dist * distSq)
+      }
+    }
+  }
+
+  addVortex(x: number, y: number, strength: number): void {
+    if (this.wasmInstance) {
+      this.wasmInstance.add_vortex(x, y, strength)
+      return
+    }
+    
+    const data = this.fallbackData!
+    for (let j = 0; j < data.height; j++) {
+      for (let i = 0; i < data.width; i++) {
+        const dx = i - x
+        const dy = j - y
+        const distSq = dx * dx + dy * dy + 0.0001
+        
+        const idx = j * data.width + i
+        data.velocityX[idx] += -strength * dy / distSq
+        data.velocityY[idx] += strength * dx / distSq
+      }
+    }
+  }
+
+  sample(x: number, y: number): [number, number] {
+    if (this.wasmInstance) {
+      const result = this.wasmInstance.sample(x, y)
+      return [result[0], result[1]]
+    }
+    
+    const data = this.fallbackData!
+    const x0 = Math.min(Math.floor(x), data.width - 2)
+    const y0 = Math.min(Math.floor(y), data.height - 2)
+    const x1 = x0 + 1
+    const y1 = y0 + 1
+    
+    const tx = x - x0
+    const ty = y - y0
+    
+    const i00 = y0 * data.width + x0
+    const i10 = y0 * data.width + x1
+    const i01 = y1 * data.width + x0
+    const i11 = y1 * data.width + x1
+    
+    const vx = data.velocityX[i00] * (1 - tx) * (1 - ty)
+             + data.velocityX[i10] * tx * (1 - ty)
+             + data.velocityX[i01] * (1 - tx) * ty
+             + data.velocityX[i11] * tx * ty
+    
+    const vy = data.velocityY[i00] * (1 - tx) * (1 - ty)
+             + data.velocityY[i10] * tx * (1 - ty)
+             + data.velocityY[i01] * (1 - tx) * ty
+             + data.velocityY[i11] * tx * ty
+    
+    return [vx, vy]
+  }
+
+  computeDivergence(): Float32Array {
+    if (this.wasmInstance) {
+      return this.wasmInstance.compute_divergence()
+    }
+    
+    const data = this.fallbackData!
+    const div = new Float32Array(data.width * data.height)
+    
+    for (let j = 1; j < data.height - 1; j++) {
+      for (let i = 1; i < data.width - 1; i++) {
+        const idx = j * data.width + i
+        const dudx = (data.velocityX[idx + 1] - data.velocityX[idx - 1]) * 0.5
+        const dvdy = (data.velocityY[idx + data.width] - data.velocityY[idx - data.width]) * 0.5
+        div[idx] = dudx + dvdy
+      }
+    }
+    
+    return div
+  }
+
+  computeCurl(): Float32Array {
+    if (this.wasmInstance) {
+      return this.wasmInstance.compute_curl()
+    }
+    
+    const data = this.fallbackData!
+    const curl = new Float32Array(data.width * data.height)
+    
+    for (let j = 1; j < data.height - 1; j++) {
+      for (let i = 1; i < data.width - 1; i++) {
+        const idx = j * data.width + i
+        const dvdx = (data.velocityY[idx + 1] - data.velocityY[idx - 1]) * 0.5
+        const dudy = (data.velocityX[idx + data.width] - data.velocityX[idx - data.width]) * 0.5
+        curl[idx] = dvdx - dudy
+      }
+    }
+    
+    return curl
+  }
+
+  clear(): void {
+    if (this.wasmInstance) {
+      this.wasmInstance.clear()
+    } else if (this.fallbackData) {
+      this.fallbackData.velocityX.fill(0)
+      this.fallbackData.velocityY.fill(0)
+    }
+  }
+
+  dispose(): void {
+    if (this.wasmInstance) {
+      this.wasmInstance.free()
+      this.wasmInstance = null
+    }
+    this.fallbackData = null
+  }
+}