azeroth-shell 0.0.0-stage → 0.1.0

package/src/engine/game/createHealthstone.ts

@@ -0,0 +1,45 @@
+// Create Healthstone OOC helpers (Warlock.cpp CreateHealthStoneWarlock). Kept out of game.ts to stay under
+// the filesize ratchet.
+import type { DataStore } from '../../data/dataStore.ts';
+import type { SpellEffect } from '../../data/schema.ts';
+import type { Character } from '../../domain/character/character.ts';
+import { countItem, type Inventory } from '../../domain/items/inventory.ts';
+import {
+  CREATE_HEALTHSTONE_SPELL_IDS,
+  improvedHealthstoneRankFromTalents,
+  type InterpretContext,
+} from '../spells/interpreter/index.ts';
+
+function isCreateHealthstone(spellId: number): boolean {
+  return (CREATE_HEALTHSTONE_SPELL_IDS as readonly number[]).includes(spellId);
+}
+
+/** Improved Healthstone talent rank for resolveCombatSpell (itypes column). */
+export function createHealthstoneInterpretCtx(
+  spellId: number,
+  char: Character,
+  ds: DataStore,
+): Pick<InterpretContext, 'improvedHealthstoneRank'> {
+  if (!isCreateHealthstone(spellId)) return {};
+  const rank = improvedHealthstoneRankFromTalents(
+    char.talents,
+    (id) => ds.talent(id),
+    (char.activeAuras ?? []).map((a) => a.spellId),
+  );
+  return rank > 0 ? { improvedHealthstoneRank: rank } : {};
+}
+
+// SPELL_FAILED_TOO_MANY_OF_ITEM when the selected stone is already in bags. Cite: Warlock.cpp
+// CreateHealthStoneWarlock::OnCheckCast.
+export function createHealthstoneBlockedReason(
+  spellId: number,
+  effects: readonly SpellEffect[],
+  inv: Inventory,
+): string | null {
+  if (!isCreateHealthstone(spellId)) return null;
+  const conj = effects.find((e) => e.kind === 'conjure');
+  if (conj && conj.kind === 'conjure' && conj.item > 0 && countItem(inv, conj.item) > 0) {
+    return 'You already have that item';
+  }
+  return null;
+}

package/src/engine/game/deathFlow.ts

@@ -0,0 +1,127 @@
+// Death-flow facade: ghost status / run-to-corpse / reclaim / spirit healer.
+// Pattern C: createDeathFlowModule(ctx) — no import of game.ts.
+
+import {
+  type DeathFlowMode,
+  moveGhostToCorpse,
+  reclaimCorpse as doReclaimCorpse,
+  spiritHealerResurrect as doSpiritHealerResurrect,
+  canReclaimCorpse,
+  isCorpseReclaimReady,
+} from '../../domain/run/death.ts';
+import {
+  maxHealth, maxPower, powerType, applyAura,
+} from '../../domain/character/character.ts';
+import { applyDurabilityLossFraction } from '../../domain/items/durability.ts';
+import { resurrectionSicknessOnRevive } from '../../domain/character/resurrectionSickness.ts';
+import type { Game } from './types.ts';
+import type { GameCtx } from './context.ts';
+
+export type DeathFlowModule = {
+  deathFlowMode: () => DeathFlowMode;
+  methods: Pick<
+    Game,
+    | 'deathFlowStatus'
+    | 'runToCorpse'
+    | 'reclaimCorpse'
+    | 'spiritHealerResurrect'
+  >;
+};
+
+export function createDeathFlowModule(ctx: GameCtx): DeathFlowModule {
+  const { ds, state, opts, log } = ctx;
+
+  const deathFlowMode = (): DeathFlowMode => {
+    const v = typeof opts.deathFlowMode === 'function' ? opts.deathFlowMode() : opts.deathFlowMode;
+    return v === 'full' ? 'full' : 'repair-only';
+  };
+
+  return {
+    deathFlowMode,
+    methods: {
+      deathFlowStatus(nowMs = Date.now()) {
+        const flow = state.deathFlow;
+        if (!flow || flow.deathState === 'ALIVE' || flow.deathState === 'JUST_ALIVED') return null;
+        const ghostTime = flow.corpse?.ghostTimeMs ?? 0;
+        const readyAt = ghostTime > 0 ? ghostTime + flow.reclaimDelayMs : Number.POSITIVE_INFINITY;
+        return {
+          deathState: flow.deathState,
+          canReclaim: canReclaimCorpse(flow, nowMs),
+          reclaimReady: isCorpseReclaimReady(flow, nowMs),
+          reclaimDelayMs: flow.reclaimDelayMs,
+          reclaimReadyInMs: Math.max(0, readyAt - nowMs),
+          corpseZoneId: flow.corpse?.zoneId ?? null,
+          graveyardId: flow.graveyard?.id ?? null,
+        };
+      },
+
+      runToCorpse() {
+        const flow = state.deathFlow;
+        if (!flow || flow.deathState !== 'GHOST') {
+          return { ok: false, reason: 'You are not a ghost' };
+        }
+        const next = moveGhostToCorpse(flow);
+        if (!next) return { ok: false, reason: 'No corpse to find' };
+        state.deathFlow = next;
+        // Zone-based stand-in: return to the zone where you died.
+        if (next.corpse && typeof next.corpse.zoneId === 'string') {
+          state.char = { ...state.char, zoneId: next.corpse.zoneId };
+        }
+        log('You find your corpse.');
+        return { ok: true };
+      },
+
+      reclaimCorpse(nowMs = Date.now()) {
+        const flow = state.deathFlow;
+        if (!flow) return { ok: false, reason: 'You are not dead' };
+        const res = doReclaimCorpse(flow, nowMs);
+        if (!res) {
+          if (!isCorpseReclaimReady(flow, nowMs)) {
+            return { ok: false, reason: 'You cannot reclaim your corpse yet' };
+          }
+          return { ok: false, reason: 'You are too far from your corpse' };
+        }
+        state.deathFlow = res.flow;
+        const maxHp = maxHealth(state.char, ds);
+        state.char.health = Math.max(1, Math.round(maxHp * res.restorePercent));
+        {
+          const pt = powerType(state.char);
+          state.char.power = (pt === 'mana' || pt === 'energy')
+            ? Math.round(maxPower(state.char, ds) * res.restorePercent)
+            : 0;
+        }
+        // No sickness on corpse reclaim (applySickness default false).
+        log('You reclaim your corpse and return to life.');
+        return { ok: true };
+      },
+
+      spiritHealerResurrect(nowMs = Date.now()) {
+        void nowMs;
+        const flow = state.deathFlow;
+        if (!flow) return { ok: false, reason: 'You are not dead' };
+        const res = doSpiritHealerResurrect(flow);
+        if (!res) return { ok: false, reason: 'Only a ghost can speak with the spirit healer' };
+        state.deathFlow = res.flow;
+        // DurabilityLossAll(0.25f) — NPCHandler.cpp SendSpiritResurrect
+        state.char = applyDurabilityLossFraction(state.char, ds.item, res.durabilityLossFraction);
+        const maxHp = maxHealth(state.char, ds);
+        state.char.health = Math.max(1, Math.round(maxHp * res.restorePercent));
+        {
+          const pt = powerType(state.char);
+          state.char.power = (pt === 'mana' || pt === 'energy')
+            ? Math.round(maxPower(state.char, ds) * res.restorePercent)
+            : 0;
+        }
+        // Resurrection sickness (spell 15007), level-scaled. Cite: Player.cpp ~4340.
+        const sick = resurrectionSicknessOnRevive(state.char.level, res.applySickness);
+        if (sick) {
+          state.char = applyAura(state.char, sick.spellId, sick.durationMs, Date.now(), ds);
+          log('The spirit healer returns you to life. You feel the weight of resurrection sickness.');
+        } else {
+          log('The spirit healer returns you to life.');
+        }
+        return { ok: true };
+      },
+    },
+  };
+}

package/src/engine/game/devGrant.ts

@@ -0,0 +1,117 @@
+// Guide-screen test grants, reached from the wiki detail pane (wikiView.ts onDevClick). They skip
+// the accept gates, the trainer and the cost the real paths enforce.
+
+import { countItem } from '../../domain/items/inventory.ts';
+import {
+  grantStarterRecipes as doGrantStarterRecipes,
+  learnRecipe as doLearnRecipe,
+} from '../../domain/professions/professions.ts';
+import { accept, getQuest, creatureCreditTargets } from '../../domain/quests/questlog.ts';
+import type { GameCtx } from './context.ts';
+import type { Game } from './types.ts';
+import { isPoisonsProfession, poisonsSkillCap } from '../../domain/professions/poisons.ts';
+
+export function createDevGrantModule(
+  ctx: GameCtx,
+  extras: { turnInQuest: Game['turnInQuest'] },
+): Pick<Game, 'devGrantItem' | 'devCompleteQuest' | 'devLearnProfession' | 'devLearnRecipe'> {
+  const { ds, state, log, refreshQuests, takeDrop } = ctx;
+
+  return {
+    devGrantItem(entry, qty = 1) {
+      const def = ds.item(entry);
+      if (!def) return { ok: false, reason: 'Unknown item' };
+      const want = Math.max(1, Math.min(1000, qty | 0));
+      // takeDrop is the loot path: bag space, the keyring family, unique and MaxCount all apply.
+      let added = 0;
+      for (let left = want; left > 0;) {
+        const step = Math.min(left, Math.max(1, def.stackable ?? 1));
+        const took = takeDrop(entry, step);
+        if (took <= 0) break;
+        added += took;
+        left -= took;
+      }
+      if (added <= 0) return { ok: false, reason: 'Bags full, or you already carry the most you can' };
+      log(`Added ${added}x ${def.name}.`);
+      refreshQuests();
+      return { ok: true, added };
+    },
+
+    devCompleteQuest(entry) {
+      const q = ds.quest(entry);
+      if (!q) return { ok: false, reason: 'Unknown quest' };
+      if (getQuest(state.questlog, entry)?.status === 'turnedIn') {
+        return { ok: false, reason: 'Already completed' };
+      }
+      // accept() straight from the domain, so level, class, chain and zone never block a test.
+      state.questlog = accept(state.questlog, q);
+      const st = getQuest(state.questlog, entry);
+      if (!st) return { ok: false, reason: 'Could not add it to the log' };
+      st.status = 'active';
+      for (const k of creatureCreditTargets(q)) st.kills[String(k.creatureEntry)] = k.count;
+      for (const o of q.objectTargets ?? []) st.objects[String(o.objectEntry)] = o.count;
+      st.spells = st.spells ?? {};
+      for (const s of q.spellCastTargets ?? []) st.spells[String(s.spell)] = s.count;
+      st.uses = st.uses ?? {};
+      for (const s of q.sourceItemTargets ?? []) st.uses[String(s.item)] = s.count;
+      st.explored = true;
+      st.talked = true;
+      // Item objectives are counted off the bags, never off the log, so they have to be real.
+      for (const t of [...(q.itemTargets ?? []), ...(q.sourceItemTargets ?? [])]) {
+        const have = countItem(state.inventory, t.item);
+        if (have < t.count) takeDrop(t.item, t.count - have);
+      }
+      refreshQuests();
+      const res = extras.turnInQuest(entry);
+      if (!res.ok) return { ok: false, reason: res.reason ?? 'Could not turn it in' };
+      return { ok: true, xp: res.xp, money: res.money };
+    },
+
+    devLearnProfession(skill, opts) {
+      const prof = ds.profession(skill);
+      if (!prof) return { ok: false, reason: 'Unknown profession' };
+      const cap = isPoisonsProfession(prof.id)
+        ? poisonsSkillCap(state.char.level)
+        : prof.ranks.reduce((n, r) => Math.max(n, r.cap), 1);
+      state.char = {
+        ...state.char,
+        skills: { ...state.char.skills, [prof.id]: { current: cap, max: cap } },
+      };
+      const starters = doGrantStarterRecipes(state.char, prof.id, ds.recipes());
+      state.char = starters.char;
+      let recipes = 0;
+      if (opts?.recipes) {
+        const known = new Set(state.char.knownRecipes);
+        for (const r of ds.recipes()) {
+          if (r.skill !== prof.id || known.has(r.id)) continue;
+          known.add(r.id);
+          recipes++;
+        }
+        const enchants = prof.id === 'enchanting'
+          ? [...new Set([...(state.char.knownEnchants ?? []), ...ds.enchants().map((e) => e.id)])]
+          : state.char.knownEnchants;
+        state.char = {
+          ...state.char,
+          knownRecipes: [...known],
+          ...(enchants !== undefined ? { knownEnchants: enchants } : {}),
+        };
+      }
+      log(`Learned ${prof.name} at ${cap}${recipes ? ` with ${recipes} recipes` : ''}.`);
+      return { ok: true, cap, recipes };
+    },
+
+    devLearnRecipe(recipeId) {
+      const recipe = ds.recipe(recipeId);
+      if (!recipe) return { ok: false, reason: 'Unknown recipe' };
+      if (!state.char.skills[recipe.skill]) {
+        return { ok: false, reason: `Learn ${recipe.skill} first` };
+      }
+      // fromItem skips the trainer's orange-skill gate and the cost, as a world-drop recipe does.
+      const res = doLearnRecipe(state.char, recipe, { fromItem: true });
+      if (!res.ok) return { ok: false, reason: res.reason ?? 'Cannot learn' };
+      state.char = res.char;
+      log(`Learned recipe: ${recipe.name}.`);
+      return { ok: true };
+    },
+  };
+}

package/src/engine/game/dynamicObject.ts

@@ -0,0 +1,365 @@
+// DynamicObject / ground-pool model for SPELL_EFFECT_PERSISTENT_AREA_AURA. Combat still pulses the
+// snapshot damage; this module owns membership and lifetime. Cite: SpellEffects.cpp EffectPersistentAA.
+
+import type { School, SpellDef, SpellEffect } from '../../data/schema.ts';
+import type { Side } from '../core/events.ts';
+import {
+  SPELL_EFFECT_ADD_FARSIGHT,
+  SPELL_EFFECT_PERSISTENT_AREA_AURA,
+} from '../spells/interpreter/opcodes.ts';
+
+/** Planar yards snapshot for a fixed DynamicObject origin (cast-time position). */
+export interface GroundPoolOrigin {
+  x: number;
+  y: number;
+  z?: number;
+}
+
+/** Session-owned lingering ground effect (DynamicObject area spell). */
+export interface GroundPool {
+  /** Session-local id (monotonic); not a world GUID. */
+  id: number;
+  spellId: number;
+  name: string;
+  source: Side;
+  school: School;
+  /** Snapshot damage range per pulse (post SP/talent at cast). */
+  min: number;
+  max: number;
+  // Yards from SpellRadius.dbc / effect.radius when known. combat.ts filters pulse targets by this when
+  // unit positions exist.
+  radius?: number;
+  // Fixed cast-time origin in yards: a ground target for Blizzard, the caster's feet for a PBAoE.
+  // Absent, combat falls back to the live caster position. Cite: SpellEffects.cpp EffectPersistentAA.
+  origin?: GroundPoolOrigin;
+  tickMs: number;
+  nextTickAt: number;
+  expiresAt: number;
+  /** SpellMgr IsBinarySpell snapshot for partial resist on pulses. */
+  binary?: boolean;
+  /** GuidSet m_affected — sides that currently hold this dynobj's aura. */
+  affected: Side[];
+  /** Creating effect index. Cite: DynamicObject.h m_effIndex. */
+  effIndex: number;
+  // True when a later effect slot is PAA or ADD_FARSIGHT. Delay only calls DelaySpellAuraHolder on those
+  // holders (avoids double-delay on multi-PAA). Cite: DynamicObject.cpp:174–188.
+  laterPersistentEffect: boolean;
+  // ONLY_ON_PLAYER on the pool's own spell: the dynamic object visits a pet, totem or guardian and
+  // applies nothing. Snapshot at cast, because the pulse loop has no spell lookup.
+  onlyOnPlayer?: boolean;
+}
+
+export interface CreateGroundPoolInput {
+  id: number;
+  spellId: number;
+  name: string;
+  source: Side;
+  school: School;
+  min: number;
+  max: number;
+  durationMs: number;
+  tickMs: number;
+  /** Session clock at cast finish. */
+  nowMs: number;
+  radius?: number;
+  /** Cast-time planar origin; see GroundPool.origin. */
+  origin?: GroundPoolOrigin;
+  binary?: boolean;
+  /** Creating effect index (default 0). */
+  effIndex?: number;
+  /** Precomputed Delay later-PAA/farsight flag. */
+  laterPersistentEffect?: boolean;
+  /** SPELL_ATTR_EX3_ONLY_ON_PLAYER — see GroundPool.onlyOnPlayer. */
+  onlyOnPlayer?: boolean;
+}
+
+/** Payload extracted from a spell that should become a ground pool. */
+export interface PersistentAreaPayload {
+  school: School;
+  min: number;
+  max: number;
+  durationMs: number;
+  tickMs: number;
+  radius?: number;
+  pointsPerComboPoint?: number;
+}
+
+// Create a ground pool. First pulse is after `tickMs` (matches unit DoT nextTickAt = t + tickMs), not on
+// the cast tick.
+export function createGroundPool(input: CreateGroundPoolInput): GroundPool {
+  const tickMs = Math.max(1, Math.trunc(input.tickMs));
+  const durationMs = Math.max(0, Math.trunc(input.durationMs));
+  const nowMs = Math.trunc(input.nowMs);
+  const origin =
+    input.origin != null
+    && Number.isFinite(input.origin.x)
+    && Number.isFinite(input.origin.y)
+      ? {
+        x: input.origin.x,
+        y: input.origin.y,
+        ...(input.origin.z != null && Number.isFinite(input.origin.z) ? { z: input.origin.z } : {}),
+      }
+      : undefined;
+  return {
+    id: input.id | 0,
+    spellId: input.spellId | 0,
+    name: input.name,
+    source: input.source,
+    school: input.school,
+    min: input.min,
+    max: input.max,
+    radius: input.radius != null && input.radius > 0 ? input.radius : undefined,
+    ...(origin ? { origin } : {}),
+    tickMs,
+    nextTickAt: nowMs + tickMs,
+    expiresAt: nowMs + durationMs,
+    binary: input.binary,
+    affected: [],
+    effIndex: input.effIndex != null ? input.effIndex | 0 : 0,
+    laterPersistentEffect: input.laterPersistentEffect === true,
+    ...(input.onlyOnPlayer === true ? { onlyOnPlayer: true } : {}),
+  };
+}
+
+export function isGroundPoolExpired(pool: GroundPool, nowMs: number): boolean {
+  return nowMs >= pool.expiresAt;
+}
+
+// Advance pool clock to `nowMs`. Returns how many pulse moments fired. Mutates `nextTickAt`. Pulses only
+// while nextTickAt < expiresAt + 1 (same fence as combat unit-DoT ticks).
+export function advanceGroundPool(pool: GroundPool, nowMs: number): number {
+  if (pool.tickMs <= 0) return 0;
+  let pulses = 0;
+  while (pool.nextTickAt <= nowMs && pool.nextTickAt < pool.expiresAt + 1) {
+    pulses++;
+    pool.nextTickAt += pool.tickMs;
+  }
+  return pulses;
+}
+
+// Find existing pool for (source, spellId) — recast refreshes rather than stacking multiple ground objects
+// of the same spell from one caster.
+function findGroundPool(
+  pools: readonly GroundPool[],
+  source: Side,
+  spellId: number,
+): GroundPool | undefined {
+  return pools.find((p) => p.source === source && p.spellId === spellId);
+}
+
+// Upsert: refresh an existing (source, spellId) pool or append a new one. A refresh keeps the earlier
+// next tick, or Rain of Fire spam resets it forever on a GCD shorter than the tick and deals nothing.
+export function upsertGroundPool(pools: GroundPool[], created: GroundPool): GroundPool {
+  const idx = pools.findIndex((p) => p.source === created.source && p.spellId === created.spellId);
+  if (idx >= 0) {
+    const prev = pools[idx]!;
+    if (prev.nextTickAt < created.nextTickAt) {
+      created.nextTickAt = prev.nextTickAt;
+    }
+    created.id = prev.id;
+    created.affected = prev.affected;
+    pools[idx] = created;
+    return pools[idx]!;
+  }
+  pools.push(created);
+  return created;
+}
+
+/** Remove expired pools; returns removed entries (for fade events). */
+export function expireGroundPools(pools: GroundPool[], nowMs: number): GroundPool[] {
+  const removed: GroundPool[] = [];
+  for (let i = pools.length - 1; i >= 0; i--) {
+    const p = pools[i]!;
+    if (isGroundPoolExpired(p, nowMs)) {
+      removed.push(p);
+      pools.splice(i, 1);
+    }
+  }
+  return removed;
+}
+
+// True when this effect is absorbed into a session ground pool, so the unit DoT is skipped: an explicit
+// persistent-area kind, or the equivalent baked shape of an aoe spell with a dot effect.
+export function isPersistentAreaEffect(spell: Pick<SpellDef, 'aoe' | 'effects'>, eff: SpellEffect): boolean {
+  if (eff.kind === 'persistent_area') return true;
+  if (eff.kind === 'dot' && spell.aoe === true) return true;
+  return false;
+}
+
+// Extract the first persistent-area payload from a spell, or null. Prefers the explicit kind and falls
+// back to the aoe-plus-dot bake shape; the radius is the effect's, else the spell's.
+export function persistentAreaFromSpell(
+  spell: Pick<SpellDef, 'aoe' | 'effects' | 'radiusYd'>,
+): PersistentAreaPayload | null {
+  const spellRadius =
+    spell.radiusYd != null && spell.radiusYd > 0 ? spell.radiusYd : undefined;
+  for (const e of spell.effects) {
+    if (e.kind === 'persistent_area') {
+      const r = e.radius != null && e.radius > 0 ? e.radius : spellRadius;
+      return {
+        school: e.school,
+        min: e.min,
+        max: e.max,
+        durationMs: e.durationMs,
+        tickMs: e.tickMs,
+        radius: r,
+        pointsPerComboPoint: e.pointsPerComboPoint,
+      };
+    }
+  }
+  if (spell.aoe === true) {
+    for (const e of spell.effects) {
+      if (e.kind === 'dot') {
+        return {
+          school: e.school,
+          min: e.min,
+          max: e.max,
+          durationMs: e.durationMs,
+          tickMs: e.tickMs,
+          radius: spellRadius,
+          pointsPerComboPoint: e.pointsPerComboPoint,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+/** Whether a caster side is on the enemy pack (for pulse target selection). */
+export function isEnemyCasterSide(side: Side): boolean {
+  if (side === 'enemy') return true;
+  return typeof side === 'string' && /^enemy_\d+$/.test(side);
+}
+
+// Later-slot PAA / ADD_FARSIGHT — the Delay() foundAura walk. Prefers raw EffectN opcodes; mapped kinds
+// when rawEffects is absent. Cite: DynamicObject.cpp:174–181; SpellEffectDefines.h 27 / 72.
+export function hasLaterPersistentAreaOrFarsight(
+  spell: Pick<SpellDef, 'effects' | 'rawEffects'>,
+  effIndex: number,
+): boolean {
+  const raw = spell.rawEffects;
+  if (raw && raw.length > 0) {
+    for (let i = (effIndex | 0) + 1; i < raw.length; i++) {
+      const code = raw[i]?.effect ?? 0;
+      if (code === SPELL_EFFECT_PERSISTENT_AREA_AURA || code === SPELL_EFFECT_ADD_FARSIGHT) {
+        return true;
+      }
+    }
+    return false;
+  }
+  for (const e of spell.effects) {
+    const slot = e.effectSlot ?? 0;
+    if (slot <= effIndex) continue;
+    if (e.kind === 'persistent_area' || e.kind === 'add_farsight') return true;
+  }
+  return false;
+}
+
+/** Cite: DynamicObject.h IsAffecting. */
+export function isGroundPoolAffecting(pool: GroundPool, side: Side): boolean {
+  return pool.affected.includes(side);
+}
+
+/** Cite: DynamicObject.h AddAffected. */
+export function addGroundPoolAffected(pool: GroundPool, side: Side): void {
+  if (!pool.affected.includes(side)) pool.affected.push(side);
+}
+
+/** Cite: DynamicObject.h RemoveAffected. */
+export function removeGroundPoolAffected(pool: GroundPool, side: Side): void {
+  const i = pool.affected.indexOf(side);
+  if (i >= 0) pool.affected.splice(i, 1);
+}
+
+// Script hook. C++ returns true when no AuraScript is bound. ScriptDev types.ts is not extended this batch
+// — default allow. Cite: DynamicObject.cpp:216–221 OnPersistentAreaAuraCheckTarget.
+function onPersistentAreaAuraCheckTarget(
+  _pool: GroundPool,
+  _target: Side,
+): boolean {
+  return true;
+}
+
+/** Cite: DynamicObject.h GetDuration — max(m_aliveTime - now, 0). */
+function groundPoolRemainingMs(pool: GroundPool, nowMs: number): number {
+  return Math.max(0, pool.expiresAt - nowMs);
+}
+
+// VisitHelper duration refresh: only extend when holder remaining < dynobj remaining. Cite:
+// GridNotifiersImpl.h VisitHelper holder->SetAuraDuration(i_dynobject.GetDuration()).
+export function shouldRefreshAffectedAuraDuration(
+  auraExpiresAt: number,
+  poolExpiresAt: number,
+): boolean {
+  return auraExpiresAt >= 0 && auraExpiresAt < poolExpiresAt;
+}
+
+export interface GroundPoolAffectedSync {
+  entered: Side[];
+  refreshed: Side[];
+  left: Side[];
+}
+
+// DynamicObject::Update membership against the current in-radius set, which is already filtered for
+// hostility, sight and liveness. This still runs the script hook. Cite: DynamicObject.cpp:138-142.
+export function syncGroundPoolAffected(
+  pool: GroundPool,
+  inRadius: readonly Side[],
+): GroundPoolAffectedSync {
+  const allowed: Side[] = [];
+  for (const side of inRadius) {
+    if (onPersistentAreaAuraCheckTarget(pool, side)) allowed.push(side);
+  }
+  const inSet = new Set(allowed);
+  const entered: Side[] = [];
+  const refreshed: Side[] = [];
+  const left: Side[] = [];
+  for (const side of pool.affected) {
+    if (!inSet.has(side)) left.push(side);
+  }
+  for (const side of allowed) {
+    if (isGroundPoolAffecting(pool, side)) refreshed.push(side);
+    else entered.push(side);
+  }
+  for (const side of left) removeGroundPoolAffected(pool, side);
+  for (const side of entered) addGroundPoolAffected(pool, side);
+  return { entered, refreshed, left };
+}
+
+// Channel pushback shortens the pool's alive time, and delays the holder only when a later persistent
+// aura still sits on it. A single-pool spell just gets shorter. Cite: DynamicObject.cpp:159-195.
+function delayGroundPool(
+  pool: GroundPool,
+  delayMs: number,
+  hasHolder: (side: Side) => boolean,
+): Side[] {
+  const delay = Math.trunc(delayMs);
+  if (delay <= 0) return [];
+  pool.expiresAt -= delay;
+  const delayAuras: Side[] = [];
+  const keep: Side[] = [];
+  for (const side of pool.affected) {
+    if (!hasHolder(side)) continue;
+    if (!pool.laterPersistentEffect) continue;
+    delayAuras.push(side);
+    keep.push(side);
+  }
+  pool.affected = keep;
+  return delayAuras;
+}
+
+/** DelayedChannel loop: every dynobj of this (caster, spellId). */
+export function delayGroundPoolsForSpell(
+  pools: readonly GroundPool[],
+  source: Side,
+  spellId: number,
+  delayMs: number,
+  hasHolder: (side: Side) => boolean,
+): { pool: GroundPool; delayAuras: Side[] }[] {
+  const out: { pool: GroundPool; delayAuras: Side[] }[] = [];
+  for (const pool of pools) {
+    if (pool.source !== source || pool.spellId !== spellId) continue;
+    out.push({ pool, delayAuras: delayGroundPool(pool, delayMs, hasHolder) });
+  }
+  return out;
+}