// Only seed entity prayer points when both values are finite
const hasExplicitPrayerPoints =
  isFiniteNumber(prayerPoints) && isFiniteNumber(maxPrayerPoints);

if (hasExplicitPrayerPoints) {
  setPlayerStats((prev) => {
    const merged = mergePlayerStats(prev, {
      prayerPoints: {
        current: prayerPoints,
        max: maxPrayerPoints,
      },
    });
    return arePlayerStatsEqual(prev, merged) ? prev : merged;
  });
}

// Re-hydrate when local player becomes available
const handlePlayerSpawned = (event: unknown) => {
  const spawnedPlayerId = /* extract from event */;
  const localPlayerId = world.entities?.player?.id ?? world.getPlayer?.()?.id ?? playerId;
  
  if (spawnedPlayerId && localPlayerId && spawnedPlayerId !== localPlayerId) {
    return; // Not our player
  }
  
  requestInitial(); // Re-run hydration
};

world.on(EventType.PLAYER_SPAWNED, handlePlayerSpawned, undefined);

/**
 * Handler for PLAYER_JOINED events.
 * Re-emits the authoritative prayer snapshot for the new session after join.
 */
private readonly onPlayerJoined = async (event: unknown): Promise<void> => {
  if (!this.world.isServer) return;

  const payload = event as Partial<PlayerJoinedPayload>;
  if (!payload.playerId || typeof payload.playerId !== \"string\") {
    Logger.systemError(\"PrayerSystem\", \"Invalid PLAYER_JOINED payload\", 
      new Error(`Invalid payload: ${JSON.stringify(event)}`));
    return;
  }

  const state = await this.ensurePlayerPrayerInitialized(payload.playerId);
  if (!state) return;

  this.emitPrayerStateSync(payload.playerId, state);
};

// Desktop
export const PANEL_PADDING = 4;           // Outer panel wrapper
export const PANEL_GRID_GAP = 4;          // Gap between icons/slots
export const PANEL_GRID_PADDING = 4;      // Inner grid inset
export const PANEL_ICON_SIZE = 36;        // Icon/slot size

// Mobile
export const PANEL_MOBILE_PADDING = 3;
export const PANEL_MOBILE_ICON_SIZE = 48; // Touch target size
export const PANEL_MOBILE_GRID_GAP = 4;

// Border radius
export const PANEL_SLOT_RADIUS = 4;       // Square aesthetic

<CursorTooltip
  visible={!!hoveredItem}
  position={{ x: mouseX, y: mouseY }}
  estimatedSize={{ width: 200, height: 100 }}
  cursorOffset={4}
  style={{ minWidth: 180 }}
>
  {/* Tooltip content */}
</CursorTooltip>

┌─────────────────────────────────────┐
│  [Icon]  [Icon]  [Icon]  [Icon]     │  ← Circular badges
│  ╱▔▔▔╲  ╱▔▔▔╲  ╱▔▔▔╲  ╱▔▔▔╲       │
│ │ ⚔️  │ │ ⚡  │ │ 🛡️  │ │ ⚖️  │      │  ← Shield shapes
│ │ACCU │ │AGGR │ │DEFE │ │CTRL │      │  ← Style names
│ │+ATK │ │+STR │ │+DEF │ │+ALL │      │  ← XP bonuses
│  ╲___╱  ╲___╱  ╲___╱  ╲___╱        │
└─────────────────────────────────────┘

// Combat style change - instant UI feedback
const changeStyle = (next: string) => {
  // Optimistic: update UI instantly (OSRS has zero visible delay)
  combatStyleCache.set(playerId, next);
  setStyle(next);
  
  // Send to server — server confirms via attackStyleChanged packet
  actions.actionMethods.changeAttackStyle(playerId, next);
};

// Auto-retaliate toggle - instant UI feedback
const toggleAutoRetaliate = () => {
  const newValue = !autoRetaliate;
  
  // Optimistic: update UI instantly
  autoRetaliateCache.set(playerId, newValue);
  setAutoRetaliate(newValue);
  
  // Send to server — server confirms via autoRetaliateChanged packet
  actions.actionMethods.setAutoRetaliate(playerId, newValue);
};

┌─────────────────────────────────┐
│ [Head]        [Portrait]   [Cape]│
│ [Body]        [Portrait]  [Amulet]│
│ [Legs]        [Portrait]   [Ring]│
│ [Boots]       [Portrait] [Gloves]│
│ [Ammo] [Weapon] [Portrait] [Shield]│
└─────────────────────────────────┘

// Create dedicated viewport for portrait
const viewport = await createAvatarPreviewViewport({
  container,
  canvas,
  cameraPosition: new THREE.Vector3(0, 1.32, 2.95),
  adjustCameraDepth: false,
});

// Load player avatar
const loadedAvatar = await world.loader.load('avatar', avatarUrl);
const avatarNode = loadedAvatar.toNodes({ scene: viewport.scene, loader: world.loader }).get('avatar');

// Attach equipment visuals
await loadPreviewEquipmentVisuals({
  world,
  equipment,
  vrm,
  avatarRoot: avatarScene,
  visuals: previewVisualsRef.current,
});

// Start animation loop
viewport.start((delta) => {
  avatarNode.instance?.update(delta);
  // Smooth rotation/zoom interpolation
  currentRotationRef.current += (targetRotationRef.current - currentRotationRef.current) * delta * 15;
  currentZoomRef.current += (targetZoomRef.current - currentZoomRef.current) * delta * 15;
  framePortraitAvatar(avatarScene, viewport.camera, currentZoomRef.current);
});

// Old: Only render active tab (unmounts others)
if (typeof activeTab.content === \"string\") {
  const panelContent = renderPanel(activeTab.content, undefined, windowId);
  return <div>{panelContent}</div>;
}

// New: Render all tabs, toggle visibility
return (
  <div style={{ position: 'relative', flex: 1 }}>
    {tabs.map((tab, idx) => {
      const isActive = idx === activeTabIndex;
      const panelContent = typeof tab.content === \"string\"
        ? renderPanel(tab.content, undefined, windowId)
        : tab.content;
      
      return (
        <div
          key={tab.id || idx}
          style={{
            display: isActive ? 'flex' : 'none',
            position: 'absolute',
            inset: 0,
            flexDirection: 'column',
          }}
        >
          {panelContent}
        </div>
      );
    })}
  </div>
);

{
  id: \"prayer\",
  label: \"Prayer\",
  icon: \"✨\",
  content: \"prayer\",
  closeable: true,
},
{
  id: \"spells\",
  label: \"Spells\",
  icon: \"🪄\",
  content: \"spells\",
  closeable: true,
},

if (data.component === \"equipment\" && isObject(data.data)) {
  const equipmentPayload = data.data as {
    playerId?: string;
    equipment?: RawEquipmentData;
  };
  
  if (!equipmentPayload.equipment) return;
  
  // Only update if this equipment belongs to the local player
  if (playerId && equipmentPayload.playerId && equipmentPayload.playerId !== playerId) {
    return; // Ignore other players' equipment
  }
  
  const nextEquipment = processRawEquipment(equipmentPayload.equipment);
  setEquipment((prev) => areEquipmentItemsEqual(prev, nextEquipment) ? prev : nextEquipment);
}

// Re-emit as UI update event with playerId for filtering
this.world.emit(EventType.UI_UPDATE, {
  component: \"equipment\",
  data: {
    playerId: data.playerId, // Include for client-side filtering
    equipment: data.equipment,
  },
});

// Deduplication map: key → timestamp
private readonly _recentDamageKeys = new Map<string, number>();

onCombatDamageDealt = (data: {
  attackerId: string;
  targetId: string;
  damage: number;
  targetType: \"player\" | \"mob\";
  position: { x: number; y: number; z: number };
  tick?: number;
}) => {
  // Include server tick in dedup key to distinguish same-damage rapid hits on different ticks
  // Use | separator (not -) to avoid collisions if IDs contain hyphens
  const tick = data.tick ?? Math.floor(performance.now() / 125); // Fallback during rolling deploy
  const dedupKey = `${data.attackerId}|${data.targetId}|${data.damage}|${tick}`;
  
  if (this._recentDamageKeys.has(dedupKey)) {
    return; // Already processed this damage event
  }
  
  // Periodic sweep: clear stale entries (>500ms old) when map exceeds threshold
  const now = performance.now();
  if (this._recentDamageKeys.size > 150) {
    // Soft threshold at 150 (close to hard cap of 200)
    for (const [key, ts] of this._recentDamageKeys) {
      if (now - ts > 500) this._recentDamageKeys.delete(key);
    }
    
    // Hard cap: trim to 100 if sweep didn't clear enough
    if (this._recentDamageKeys.size > 200) {
      const excess = this._recentDamageKeys.size - 100;
      let dropped = 0;
      for (const key of this._recentDamageKeys.keys()) {
        this._recentDamageKeys.delete(key);
        if (++dropped >= excess) break;
      }
    }
  }
  
  this._recentDamageKeys.set(dedupKey, now);
  
  // Forward to local event system
  this.world.emit(EventType.COMBAT_DAMAGE_DEALT, data);
};

this.broadcast.sendToNearby(
  \"combatDamageDealt\",
  {
    attackerId: data.attackerId,
    targetId: data.targetId,
    damage: data.damage,
    targetType: data.targetType,
    position: { x: pos.x, y: pos.y, z: pos.z },
    tick: currentTick, // Include server tick for dedup
  },
  pos.x,
  pos.z,
);

// 1. Update local cache + state (optimistic)
cache.set(playerId, newValue);
setState(newValue);

// 2. Send to server
actions.actionMethods.changeX(playerId, newValue);

// 3. Server confirms via event (overwrites optimistic value)
world.on(EventType.X_CHANGED, (data) => {
  cache.set(data.playerId, data.newValue);
  setState(data.newValue);
});

/**
 * OSRS-accurate: When weapon changes, validate current style is still available.
 * If not, auto-switch to the first valid style for the new weapon type.
 */
private handleWeaponChange(playerId: string): void {
  const playerState = this.playerAttackStyles.get(playerId);
  if (!playerState) return;

  const weaponType = this.getPlayerWeaponType(playerId);
  const currentStyle = playerState.selectedStyle as CombatStyleExtended;

  if (!isStyleValidForWeapon(weaponType, currentStyle)) {
    const newStyle = getDefaultStyleForWeapon(weaponType);
    this.handleStyleChange({ playerId, newStyle });
  }
}

// Subscribe to equipment changes (server-only)
if (this.world.isServer) {
  this.subscribe(EventType.PLAYER_EQUIPMENT_CHANGED, (data) => {
    const eqData = data as { playerId: string; slot: string; itemId: string | null };
    if (eqData.slot === \"weapon\") {
      this.handleWeaponChange(eqData.playerId);
    }
  });
}

// In handleStyleChange
let playerState = this.playerAttackStyles.get(playerId);
if (!playerState) {
  // Auto-initialize if player exists but wasn't registered yet (event ordering)
  if (this.isKnownPlayer(playerId)) {
    const weaponType = this.getPlayerWeaponType(playerId);
    const defaultStyle = getDefaultStyleForWeapon(weaponType);
    this.logger.debug(
      `Auto-initializing attack style for ${playerId} (event ordering race), default: ${defaultStyle}`
    );
    this.initializePlayerAttackStyle(playerId, defaultStyle);
    playerState = this.playerAttackStyles.get(playerId);
  }
  if (!playerState) {
    this.logger.warn(`Attack style change rejected: no state for player ${playerId}`);
    return;
  }
}

// In onPlayerRegister - skip if state already exists
if (!this.playerAttackStyles.has(data.playerId)) {
  this.initializePlayerAttackStyle(data.playerId, savedAttackStyle);
}
if (!this.playerAutoRetaliate.has(data.playerId)) {
  this.initializePlayerAutoRetaliate(data.playerId, savedAutoRetaliate);
}

// Optimistic removal: remove the logs from the client inventory cache
// so the UI updates immediately (same pattern as eat/drop/bury in
// InventoryActionDispatcher). The server's authoritative inventoryUpdated
// packet will replace this cache within ~100-200ms.
this.applyOptimisticRemoval(playerId, logsSlot, 1);

/**
 * Optimistically remove an item from the inventory cache and emit an
 * immediate UI update. Automatically snapshots before mutation for
 * rollback if the server doesn't confirm within 5 seconds.
 */
applyOptimisticRemoval(playerId: string, slot: number, quantity: number): void {
  const cached = this.lastInventoryByPlayerId[playerId];
  if (!cached) return;

  const itemIndex = cached.items.findIndex((i) => i.slot === slot);
  if (itemIndex === -1) return;

  // Snapshot before mutation for rollback on timeout
  const snapshot = this.snapshotInventory(playerId);
  if (snapshot) this.inventoryTracker.add(snapshot);
  this.ensureInventoryPruner();

  const item = cached.items[itemIndex];
  if (item.quantity <= quantity) {
    cached.items.splice(itemIndex, 1);
  } else {
    item.quantity -= quantity;
  }

  this.world.emit(EventType.INVENTORY_UPDATED, { ...cached });
}

/** Start periodic stale-action pruning (once per second) */
private ensureInventoryPruner(): void {
  if (this.inventoryPrunerInterval) return;
  
  this.inventoryPrunerInterval = setInterval(() => {
    const rollbacks = this.inventoryTracker.pruneStale();
    for (const snapshot of rollbacks) {
      // Restore the pre-action cache so the UI corrects itself
      this.lastInventoryByPlayerId[snapshot.playerId] = snapshot;
      this.world.emit(EventType.INVENTORY_UPDATED, { ...snapshot });
      console.warn(\"[ClientNetwork] Optimistic inventory action timed out, rolling back\");
    }
  }, 1000);
}

// Clear tracker when server confirms
onInventoryUpdated = (data: { ... }) => {
  // Server sent authoritative inventory — discard all pending rollbacks
  this.inventoryTracker.clear();
  // ... rest of handler
};

// After emitting TARGETING_SELECT
world.emit(EventType.TARGETING_SELECT, {
  sourceType: \"inventory_item\",
  sourceSlot: targetingState.sourceSlot,
  targetType: \"inventory_item\",
  targetSlot: slotIndex,
});

// Clear targeting immediately — action is committed
setTargetingState(initialTargetingState);

// Old: Hover disabled during targeting
hovered: !isEmpty && !isTargetingActive,

// New: Hover always enabled for filled slots
hovered: !isEmpty,

// Old (404 error)
const result = await modelCache.loadModel(
  \"asset://models/firemaking-fire/firemaking-fire.glb\",
  this.world
);

// New (correct)
const result = await modelCache.loadModel(
  \"asset://models/misc/firemaking-fire/firemaking-fire.glb\",
  this.world
);

class ClientNetwork {
  // Deep-clone inventory cache for rollback
  snapshotInventory(playerId: string): InventorySnapshot | null;
  
  // Optimistically remove item with automatic snapshot + rollback
  applyOptimisticRemoval(playerId: string, slot: number, quantity: number): void;
  
  // Restore inventory from snapshot (used by rollback)
  restoreInventorySnapshot(snapshot: InventorySnapshot): void;
}

export interface InventorySnapshot {
  playerId: string;
  items: Array<{ slot: number; itemId: string; quantity: number }>;
  coins: number;
  maxSlots: number;
}

// FIX: Route combat rotation through TileInterpolator when it controls this entity.
const tileControlled = this.data?.tileInterpolatorControlled === true;

if (tileControlled) {
  const network = this.world.network as {
    tileInterpolator?: {
      setCombatRotation?: (
        entityId: string,
        quaternion: number[] | THREE.Quaternion,
        entityPosition?: { x: number; y: number; z: number }
      ) => boolean;
    };
  };
  network?.tileInterpolator?.setCombatRotation?.(this.data.id, _combatQuat);
} else if (this.base) {
  // Fallback: TileInterpolator hasn't touched this entity yet
  this.base.quaternion.copy(_combatQuat);
}

class ClientNetwork {
  /**
   * Deep-clone the current inventory cache for a player for rollback purposes.
   * Returns null if no cache exists yet.
   */
  snapshotInventory(playerId: string): InventorySnapshot | null;

  /**
   * Optimistically remove an item from the inventory cache and emit an
   * immediate UI update. Automatically snapshots before mutation for
   * rollback if the server doesn't confirm within 5 seconds.
   */
  applyOptimisticRemoval(playerId: string, slot: number, quantity: number): void;
}

export interface InventorySnapshot {
  playerId: string;
  items: Array<{ slot: number; itemId: string; quantity: number }>;
  coins: number;
  maxSlots: number;
}

export {
  attachEquipmentVisualToVRM,
  extractEquipmentAttachmentData,
  removeEquipmentVisual,
  resolveEquipmentVisualData,
  resolveEquipmentVisualUrls,
} from \"./systems/client/EquipmentVisualHelpers\";

export type {
  EquipmentAttachmentData,
  EquipmentVisualModelData,
  EquipmentVisualStore,
  EquipmentVisualUrlResolution,
} from \"./systems/client/EquipmentVisualHelpers\";

import {
  resolveEquipmentVisualData,
  resolveEquipmentVisualUrls,
  attachEquipmentVisualToVRM,
  type EquipmentVisualStore,
} from \"@hyperscape/shared\";

// Resolve item metadata
const itemData = resolveEquipmentVisualData({ itemId: \"bronze_helmet\" });

// Resolve URLs (primary + fallback)
const urls = resolveEquipmentVisualUrls({
  assetsUrl: \"https://assets.hyperscape.club\",
  itemId: \"bronze_helmet\",
  slot: \"helmet\",
  itemData,
});

// Load and attach to VRM
const gltf = await loader.loadAsync(urls.primaryUrl);
const modelRoot = gltf.scene.clone(true);
attachEquipmentVisualToVRM({
  slot: \"helmet\",
  modelRoot,
  visuals: equipmentStore,
  vrm,
  avatarRoot,
});

// Old
interface PlayerAttackStyleState {
  playerId: string;
  selectedStyle: string;
  lastStyleChange: number;           // REMOVED
  combatStyleHistory: Array<{        // REMOVED
    style: string;
    timestamp: number;
    combatSession: string;
  }>;
}

// New
interface PlayerAttackStyleState {
  playerId: string;
  selectedStyle: string;
}

import {
  PANEL_PADDING,
  PANEL_GRID_GAP,
  PANEL_ICON_SIZE,
  PANEL_MOBILE_PADDING,
  PANEL_MOBILE_ICON_SIZE,
  PANEL_SLOT_RADIUS,
} from \"@/constants/panelLayout\";

// Desktop grid
<div style={{
  padding: PANEL_PADDING,
  gap: PANEL_GRID_GAP,
  gridTemplateColumns: `repeat(auto-fill, ${PANEL_ICON_SIZE}px)`,
}}>
  {/* Icons */}
</div>

// Mobile grid
<div style={{
  padding: PANEL_MOBILE_PADDING,
  gap: PANEL_MOBILE_GRID_GAP,
  gridTemplateColumns: `repeat(auto-fill, ${PANEL_MOBILE_ICON_SIZE}px)`,
}}>
  {/* Icons */}
</div>

// Old (manual portal + positioning)
const { left, top } = calculateCursorTooltipPosition(mousePos, tooltipSize);
return createPortal(
  <div ref={tooltipRef} style={{ position: 'fixed', left, top, zIndex: 100000 }}>
    {/* Content */}
  </div>,
  document.body
);

// New (CursorTooltip component)
return (
  <CursorTooltip
    visible={!!hoveredItem}
    position={mousePos}
    estimatedSize={{ width: 200, height: 100 }}
  >
    {/* Content */}
  </CursorTooltip>
);

// Old (unsafe - direct cache access)
const network = world.network as { lastInventoryByPlayerId?: Record<string, any> };
const cached = network.lastInventoryByPlayerId?.[playerId];
cached.items.splice(itemIndex, 1);
world.emit(EventType.INVENTORY_UPDATED, cached);

// New (safe - public API with rollback)
const network = world.network as ClientNetwork;
network.applyOptimisticRemoval(playerId, slot, quantity);

// Removed methods (no longer available)
canPlayerChangeStyle(playerId)      // Always returned true
getRemainingStyleCooldown(playerId) // Always returned 0
getPlayerStyleHistory(playerId)     // Always returned []

// Use direct state access instead
const playerState = playerAttackStyles.get(playerId);
const currentStyle = playerState?.selectedStyle;

## March 26, 2026 - UI & Systems Update

### 🎨 UI Panel Redesign
- Combat panel with heraldic shield banners
- Equipment panel with live 3D paperdoll portrait
- Unified panel layout constants across all panels
- New CursorTooltip component for consistent tooltips
- Tab persistence (no unmounting on switch)
- SpellsPanel added to default layout

### 🙏 Prayer System
- Fixed prayer state hydration on login/reconnect
- Prayer cache preserved during bootstrap
- PLAYER_SPAWNED re-hydration support
- PrayerSystem re-emits state on PLAYER_JOINED

### ⚔️ Combat Improvements
- Optimistic UI updates for attack style and auto-retaliate
- Attack style cooldown system removed (was 0ms)
- Auto-style switching on weapon change
- Combat rotation race condition fixed

### 🎒 Inventory Enhancements
- Firemaking optimistic inventory removal
- Targeting mode improvements
- Optimistic inventory logic consolidated into ClientNetwork
- Fire model asset path corrected

### 🐛 Bug Fixes
- Equipment panel cross-player data leak fixed
- Combat damage deduplication for region boundaries
- Targeting state clears immediately after selection
- Item rename: bronze_sword → bronze_shortsword