azeroth-shell 0.0.0-stage → 0.1.1

package/src/world/rareRoll.ts

@@ -0,0 +1,335 @@
+/**
+ * Once-per-instance dungeon pool roll (rare-elite + equal-chance substitutes).
+ *
+ * Cite: PoolManager.cpp RollOne / SpawnObject / Initialize;
+ * MapPersistentStateMgr.cpp InitPools ~198-207 — run once per persistent state, no
+ * respawn re-roll in v1. Chances come only from baked `pools.json` members.
+ *
+ * Multi-location rares (Bannok ×2, Forresten ×4, …) are authored as several boss
+ * encounters sharing a display name. Pool roll picks spawn guids; the route must
+ * keep at most one of those candidates so the map does not walk every spawn point.
+ */
+
+import type { Rng } from '../engine/core/rng.ts';
+import {
+  populateFromBakedPool,
+  type BakedPoolRow,
+} from '../domain/world/pools.ts';
+import type { DungeonSpawn } from '../data/dungeonSpawns.ts';
+import type { EncounterDef } from '../data/schema/encounter.ts';
+
+/** Sub-seed salt for instance pool rolls (ASCII "pool"). */
+export const DUNGEON_POOL_ROLL_SALT = 0x706f6f6c;
+
+export type DungeonPoolRoll = {
+  /** Pool template ids rolled for this map (stable ascending). */
+  poolIds: readonly number[];
+  /** Guids that won populatePool for those pools. */
+  spawnedGuids: readonly number[];
+  /** Union of every member guid in those pools (winners + losers). */
+  memberGuids: readonly number[];
+};
+
+/** Map spawn rows used for pool membership / multi-slot rebinding. */
+export type PoolMapSpawn = {
+  guid: number;
+  entry: number;
+  /** CSE candidates on the spawn (SM grave rares). */
+  poolCandidates?: readonly number[];
+  x?: number;
+  y?: number;
+};
+
+/** Pools with at least one member guid on this floor (or authored encounter list). */
+export function poolsForMapGuids(
+  pools: readonly BakedPoolRow[],
+  mapGuids: ReadonlySet<number>,
+): BakedPoolRow[] {
+  const out: BakedPoolRow[] = [];
+  for (const p of pools) {
+    if (p.members.some((m) => mapGuids.has(m.guid))) out.push(p);
+  }
+  out.sort((a, b) => a.id - b.id);
+  return out;
+}
+
+// Roll every map-relevant pool once. Deterministic given `rng`. Cite: MapPersistentState::InitPools — once
+// per persistent state.
+export function rollDungeonPools(
+  pools: readonly BakedPoolRow[],
+  mapGuids: ReadonlySet<number>,
+  rng: Rng,
+): DungeonPoolRoll {
+  const relevant = poolsForMapGuids(pools, mapGuids);
+  const poolIds: number[] = [];
+  const spawned: number[] = [];
+  const members: number[] = [];
+  for (const row of relevant) {
+    poolIds.push(row.id);
+    for (const m of row.members) members.push(m.guid);
+    // Fresh pool each call — no prior spawns (v1 no respawn re-roll).
+    spawned.push(...populateFromBakedPool(row, { spawned: [] }, rng));
+  }
+  return {
+    poolIds,
+    spawnedGuids: [...new Set(spawned)],
+    memberGuids: [...new Set(members)],
+  };
+}
+
+/** Rebuild a roll from persisted winners (re-mount). Member set re-derived from bake. */
+export function poolRollFromPersisted(
+  pools: readonly BakedPoolRow[],
+  mapGuids: ReadonlySet<number>,
+  spawnedGuids: readonly number[],
+): DungeonPoolRoll {
+  const relevant = poolsForMapGuids(pools, mapGuids);
+  const poolIds: number[] = [];
+  const members: number[] = [];
+  for (const row of relevant) {
+    poolIds.push(row.id);
+    for (const m of row.members) members.push(m.guid);
+  }
+  return {
+    poolIds,
+    spawnedGuids: [...spawnedGuids],
+    memberGuids: [...new Set(members)],
+  };
+}
+
+/** True unless `guid` is a rolled-pool member that lost. */
+export function spawnAllowedByPoolRoll(
+  guid: number,
+  roll: DungeonPoolRoll | null | undefined,
+): boolean {
+  if (!roll || roll.memberGuids.length === 0) return true;
+  // Hot path: sets once when filtering many spawns — callers prefer filterSpawnsByPoolRoll.
+  const members = new Set(roll.memberGuids);
+  if (!members.has(guid)) return true;
+  return new Set(roll.spawnedGuids).has(guid);
+}
+
+/** Drop pool losers from dungeon floor spawns; keep non-members and winners. */
+export function filterSpawnsByPoolRoll(
+  spawns: readonly DungeonSpawn[],
+  roll: DungeonPoolRoll | null | undefined,
+): DungeonSpawn[] {
+  if (!roll || roll.memberGuids.length === 0) return spawns.slice();
+  const members = new Set(roll.memberGuids);
+  const spawned = new Set(roll.spawnedGuids);
+  return spawns.filter((s) => !members.has(s.guid) || spawned.has(s.guid));
+}
+
+/** Pool member guids that can materialize this encounter's creature entry. */
+function poolGuidsForEncounter(
+  enc: { spawnGuids?: readonly number[]; creatureEntry: number },
+  members: ReadonlySet<number>,
+  mapSpawns: readonly PoolMapSpawn[],
+): Set<number> {
+  const poolGuids = new Set<number>();
+  const authored = enc.spawnGuids ?? [];
+  // Authored slots are the encounter's presence set (SM CSE graves ×6, each with a
+  // unique name). Do not union every map spawn that shares poolCandidates — any
+  // winner would then mark every grave up (KI-970; pool 46001 max_limit=1).
+  if (authored.length > 0) {
+    for (const g of authored) {
+      if (members.has(g)) poolGuids.add(g);
+    }
+    if (poolGuids.size > 0) return poolGuids;
+  }
+  for (const s of mapSpawns) {
+    if (!members.has(s.guid)) continue;
+    if (s.entry === enc.creatureEntry) poolGuids.add(s.guid);
+    // CSE rare graves (SM): base entry differs; candidates include this rare.
+    if (s.poolCandidates?.includes(enc.creatureEntry)) poolGuids.add(s.guid);
+  }
+  return poolGuids;
+}
+
+/**
+ * Pool-gated encounter presence. Not gated when no map/pool member shares the
+ * encounter's entry (or authored spawnGuids / CSE poolCandidates). Multi-slot
+ * same-entry rares count any winning same-entry guid for *presence*; route
+ * dedupe (stripAbsentPoolEncountersFromRoute) keeps a single candidate pin.
+ */
+export function isEncounterUpAfterPoolRoll(
+  enc: { spawnGuids?: readonly number[]; creatureEntry: number },
+  roll: DungeonPoolRoll | null | undefined,
+  mapSpawns: readonly PoolMapSpawn[],
+): boolean {
+  if (!roll || roll.memberGuids.length === 0) return true;
+  const members = new Set(roll.memberGuids);
+  const spawned = new Set(roll.spawnedGuids);
+  const poolGuids = poolGuidsForEncounter(enc, members, mapSpawns);
+  if (poolGuids.size === 0) return true;
+  for (const g of poolGuids) if (spawned.has(g)) return true;
+  return false;
+}
+
+// Point the encounter at the winning pool guid(s) for its entry (multi-slot rares). No-op when the
+// encounter is not pool-gated or lost the roll.
+export function rebindSpawnGuidsAfterPoolRoll(
+  enc: EncounterDef,
+  roll: DungeonPoolRoll | null | undefined,
+  mapSpawns: readonly PoolMapSpawn[],
+): EncounterDef {
+  if (!roll || roll.memberGuids.length === 0) return enc;
+  const members = new Set(roll.memberGuids);
+  const spawned = new Set(roll.spawnedGuids);
+  const winners = new Set<number>();
+  // Same authored-slot rule as poolGuidsForEncounter (KI-970 CSE graves).
+  const authored = enc.spawnGuids ?? [];
+  if (authored.length > 0) {
+    for (const g of authored) {
+      if (members.has(g) && spawned.has(g)) winners.add(g);
+    }
+  }
+  if (!winners.size) {
+    for (const s of mapSpawns) {
+      if (!members.has(s.guid) || !spawned.has(s.guid)) continue;
+      if (s.entry === enc.creatureEntry || s.poolCandidates?.includes(enc.creatureEntry)) {
+        winners.add(s.guid);
+      }
+    }
+  }
+  if (!winners.size) return enc;
+  const sorted = [...winners].sort((a, b) => a - b);
+  const prev = enc.spawnGuids ?? [];
+  if (prev.length === sorted.length && prev.every((g, i) => g === sorted[i])) return enc;
+  return { ...enc, spawnGuids: sorted };
+}
+
+/**
+ * Boss-kind encounters that share a display name are multi-location rare candidates
+ * (Bannok ×2, Forresten ×4). Trash reusing a name is a different pack each time —
+ * only `kind === 'boss'` groups are multi-slot rares.
+ */
+export function multiSlotBossGroups(
+  encounters: readonly EncounterDef[],
+): Map<string, EncounterDef[]> {
+  const byName = new Map<string, EncounterDef[]>();
+  for (const e of encounters) {
+    if (e.kind !== 'boss') continue;
+    const list = byName.get(e.name);
+    if (list) list.push(e);
+    else byName.set(e.name, [e]);
+  }
+  for (const [name, list] of [...byName]) {
+    if (list.length < 2) byName.delete(name);
+  }
+  return byName;
+}
+
+/**
+ * Pick the single route representative for a multi-location rare group.
+ * Prefers an encounter whose spawnGuids include a pool winner; else nearest
+ * origin to the winning spawn; else first id in route order (`orderedIds`).
+ */
+export function selectMultiSlotRareRepresentative(
+  group: readonly EncounterDef[],
+  orderedIds: readonly string[],
+  roll: DungeonPoolRoll | null | undefined,
+  mapSpawns: readonly PoolMapSpawn[],
+): EncounterDef {
+  if (group.length === 1) return group[0]!;
+  const orderRank = new Map(orderedIds.map((id, i) => [id, i]));
+  const byRoute = (a: EncounterDef, b: EncounterDef): number =>
+    (orderRank.get(a.id) ?? 1e9) - (orderRank.get(b.id) ?? 1e9)
+    || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+  if (!roll || roll.memberGuids.length === 0) {
+    return [...group].sort(byRoute)[0]!;
+  }
+
+  const members = new Set(roll.memberGuids);
+  const spawned = new Set(roll.spawnedGuids);
+  const entry = group[0]!.creatureEntry;
+  const winners: PoolMapSpawn[] = [];
+  for (const s of mapSpawns) {
+    if (!members.has(s.guid) || !spawned.has(s.guid)) continue;
+    if (s.entry === entry || s.poolCandidates?.includes(entry)) winners.push(s);
+  }
+  for (const enc of group) {
+    for (const g of enc.spawnGuids ?? []) {
+      if (members.has(g) && spawned.has(g) && !winners.some((w) => w.guid === g)) {
+        const hit = mapSpawns.find((s) => s.guid === g);
+        winners.push(hit ?? { guid: g, entry });
+      }
+    }
+  }
+  winners.sort((a, b) => a.guid - b.guid);
+
+  if (winners.length) {
+    const winGuids = new Set(winners.map((w) => w.guid));
+    const bound = group.filter((e) => e.spawnGuids?.some((g) => winGuids.has(g)));
+    if (bound.length) return [...bound].sort(byRoute)[0]!;
+
+    const win = winners[0]!;
+    if (win.x != null && win.y != null && group.some((e) => e.origin)) {
+      return [...group].sort((a, b) => {
+        const da = a.origin
+          ? Math.hypot(a.origin.x - win.x!, a.origin.y - win.y!)
+          : Number.POSITIVE_INFINITY;
+        const db = b.origin
+          ? Math.hypot(b.origin.x - win.x!, b.origin.y - win.y!)
+          : Number.POSITIVE_INFINITY;
+        if (da !== db) return da - db;
+        return byRoute(a, b);
+      })[0]!;
+    }
+  }
+
+  return [...group].sort(byRoute)[0]!;
+}
+
+// Among boss multi-slot groups, keep exactly one id per display name. Losers stay in the def; they only
+// leave the route.
+export function dedupeMultiSlotBossRoute(
+  encounterIds: readonly string[],
+  encounters: readonly EncounterDef[],
+  roll: DungeonPoolRoll | null | undefined,
+  mapSpawns: readonly PoolMapSpawn[],
+): string[] {
+  const byId = new Map(encounters.map((e) => [e.id, e]));
+  const groups = multiSlotBossGroups(encounters);
+  if (groups.size === 0) return encounterIds.slice();
+
+  const keepOne = new Map<string, string>(); // name → chosen id
+  for (const [name, group] of groups) {
+    const onRoute = group.filter((e) => encounterIds.includes(e.id));
+    if (onRoute.length < 2) continue;
+    const pick = selectMultiSlotRareRepresentative(onRoute, encounterIds, roll, mapSpawns);
+    keepOne.set(name, pick.id);
+  }
+  if (keepOne.size === 0) return encounterIds.slice();
+
+  return encounterIds.filter((id) => {
+    const enc = byId.get(id);
+    if (!enc || enc.kind !== 'boss') return true;
+    const chosen = keepOne.get(enc.name);
+    if (chosen == null) return true;
+    return id === chosen;
+  });
+}
+
+// Drop pool-absent encounters from the run route, then collapse multi-location rare candidates (same boss
+// name) to a single pin. Defs keep every candidate.
+export function stripAbsentPoolEncountersFromRoute(
+  encounterIds: readonly string[],
+  encounters: readonly EncounterDef[],
+  roll: DungeonPoolRoll | null | undefined,
+  mapSpawns: readonly PoolMapSpawn[],
+): string[] {
+  const byId = new Map(encounters.map((e) => [e.id, e]));
+  let kept: string[];
+  if (!roll || roll.memberGuids.length === 0) {
+    kept = encounterIds.slice();
+  } else {
+    kept = encounterIds.filter((id) => {
+      const enc = byId.get(id);
+      if (!enc) return true;
+      return isEncounterUpAfterPoolRoll(enc, roll, mapSpawns);
+    });
+  }
+  return dedupeMultiSlotBossRoute(kept, encounters, roll, mapSpawns);
+}

package/src/world/routeAuthoring.ts

@@ -0,0 +1,132 @@
+// Geometry for hand-authored dungeon routes: where a new click belongs in the step list, and
+// which step the party is walking toward. Shared by both editors and the autopilot. Pure.
+
+export type RoutePoint = { x: number; y: number; z?: number | null };
+
+/** 3-D when both points carry z, plan-view otherwise (a click on a plate has no z yet). */
+export function routeDist(a: RoutePoint, b: RoutePoint): number {
+  const dz = a.z != null && b.z != null && Number.isFinite(a.z) && Number.isFinite(b.z)
+    ? a.z - b.z
+    : 0;
+  return Math.hypot(a.x - b.x, a.y - b.y, dz);
+}
+
+/** Plan-view distance: what is drawn on the plate, whatever the storeys say. */
+export function routeDist2(a: RoutePoint, b: RoutePoint): number {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+
+/** One owner, in domain/nav/storey.ts, which also says why the floor gate is a different 10. */
+import { REACH_STOREY_DZ_YD } from '../domain/nav/storey.ts';
+export { REACH_STOREY_DZ_YD };
+
+/** Same floor when both points carry z. Missing z stays compatible (legacy 2-D nodes). */
+export function routeSameStorey(a: RoutePoint, b: RoutePoint): boolean {
+  const az = a.z;
+  const bz = b.z;
+  if (az == null || bz == null || !Number.isFinite(az) || !Number.isFinite(bz)) return true;
+  return Math.abs(az - bz) <= REACH_STOREY_DZ_YD;
+}
+
+// On the pin in plan view AND on its storey. Same-xy one floor up is not arrival — a click on any plate of
+// a stacked map used to count the step done.
+export function routeArrived(party: RoutePoint, dest: RoutePoint, xyYd: number): boolean {
+  if (routeDist2(party, dest) > xyYd) return false;
+  return routeSameStorey(party, dest);
+}
+
+// Z the walk must finish on. A stacked column is walkable at dest.xy on THIS floor; stamping the path's
+// landing z completed the click a storey below the pin. Truncated (aggro-cut) walks keep the cut's z.
+export function walkArriveZ(
+  destZ: number | undefined,
+  lastPtZ: number | undefined,
+  truncated: boolean,
+): number | undefined {
+  const dest = destZ != null && Number.isFinite(destZ) ? destZ : undefined;
+  const last = lastPtZ != null && Number.isFinite(lastPtZ) ? lastPtZ : undefined;
+  if (truncated) return last ?? dest;
+  return dest ?? last;
+}
+
+/**
+ * Closest point on segment a→b. `d` is plan-view; `dz` is the height gap to it (0 when either
+ * side has no z). 3-D distance is `hypot(d, dz)`. Kept separate because the two questions here
+ * want different metrics: what the operator clicked is 2-D, where the party stands is 3-D.
+ *
+ * z interpolates only when BOTH ends have one. Inheriting one end's z put a leg 28 yd away
+ * while its own start node read 21 yd, so routeForwardIndex aimed backwards for ever.
+ */
+export function segmentNearest(
+  a: RoutePoint,
+  b: RoutePoint,
+  p: RoutePoint,
+): { t: number; d: number; dz: number } {
+  const vx = b.x - a.x;
+  const vy = b.y - a.y;
+  const len2 = vx * vx + vy * vy;
+  const gap = (z: number | null | undefined): number =>
+    z != null && Number.isFinite(z) && p.z != null && Number.isFinite(p.z)
+      ? Math.abs(z - p.z)
+      : 0;
+  if (len2 < 1e-6) return { t: 0, d: routeDist2(a, p), dz: gap(a.z ?? b.z) };
+  let t = ((p.x - a.x) * vx + (p.y - a.y) * vy) / len2;
+  t = t < 0 ? 0 : t > 1 ? 1 : t;
+  const bothZ = a.z != null && b.z != null && Number.isFinite(a.z) && Number.isFinite(b.z);
+  return {
+    t,
+    d: Math.hypot(a.x + vx * t - p.x, a.y + vy * t - p.y),
+    dz: gap(bothZ ? a.z! + (b.z! - a.z!) * t : null),
+  };
+}
+
+/**
+ * Where to splice a new step: into the DRAWN LEG NEAREST THE CLICK, or at an end when the click
+ * is out past one. Nearest-leg, not cheapest-insertion — on a route that folds back through the
+ * same corridor, cheapest-insertion answered "step 16" for a click beside leg 1-2
+ * (probe-path-editor-authoring). Returns `nodes.length` for append.
+ */
+export function routeInsertIndex(nodes: readonly RoutePoint[], p: RoutePoint): number {
+  const n = nodes.length;
+  if (n === 0) return 0;
+  if (n === 1) return 1;
+  /** Legs this close in plan view are "the same place on the picture"; z then decides. */
+  const TIE_YD = 6;
+  const legs: { i: number; d: number; dz: number }[] = [];
+  for (let i = 1; i < n; i++) {
+    const { d, dz } = segmentNearest(nodes[i - 1]!, nodes[i]!, p);
+    legs.push({ i, d, dz });
+  }
+  let best = legs[0]!;
+  for (const l of legs) if (l.d < best.d) best = l;
+  for (const l of legs) {
+    if (l.d <= best.d + TIE_YD && l.dz < best.dz - TIE_YD) best = l;
+  }
+  // Out past an end (nearer the terminal step than any leg) → extend rather than splice.
+  const dFirst = routeDist2(nodes[0]!, p);
+  const dLast = routeDist2(nodes[n - 1]!, p);
+  if (dLast <= best.d && dLast <= dFirst) return n;
+  if (dFirst <= best.d) return 0;
+  return best.i;
+}
+
+// The step the party is walking toward: far end of its nearest leg. Projection, not nearest node (halfway
+// down a leg the nearest node is behind you). Past the end → `nodes.length`.
+export function routeForwardIndex(nodes: readonly RoutePoint[], p: RoutePoint): number {
+  const n = nodes.length;
+  if (n === 0) return 0;
+  if (n === 1) return 0;
+  let bestIdx = 1;
+  let bestD = Infinity;
+  for (let i = 1; i < n; i++) {
+    const { t, d, dz } = segmentNearest(nodes[i - 1]!, nodes[i]!, p);
+    const d3 = Math.hypot(d, dz); // the party's z is real: a leg one floor up is not near
+    if (d3 < bestD) {
+      bestD = d3;
+      // t≈1 means the party is standing on the leg's end node — lead to the one after it.
+      bestIdx = t >= 0.999 ? i + 1 : i;
+    }
+  }
+  // Before the route starts: closer to step 1 itself than to any leg → aim at step 1.
+  if (routeDist(nodes[0]!, p) < bestD) return 0;
+  return bestIdx;
+}

package/src/world/routeEdit.ts

@@ -0,0 +1,209 @@
+// Shared route-editor session: parse, undo snapshots, insert/delete, plan seed.
+// Both the live run bar and the standalone path editor call this. One click, one undo.
+
+import type { InstanceDef } from '../data/schema.ts';
+import { dungeonGameObjectsForMap } from '../data/dungeonGameObjects.ts';
+import {
+  flagsSetByEncounter,
+  hasFlag,
+  isCleared,
+  type InstanceRun,
+} from './instances.ts';
+import { worldPosForEncounter } from './dungeonRouteGeometry.ts';
+import { routeInsertIndex } from './routeAuthoring.ts';
+import { objectiveItinerary } from './dungeonObjectives.ts';
+import { setAuthoredRouteAnchors } from './dungeonRouteOrder.ts';
+import authoredRoutesJson from '../data/tables/dungeonAuthoredRoutes.json' with { type: 'json' };
+
+export type RouteEditNode = {
+  kind: 'walk' | 'use';
+  x: number;
+  y: number;
+  z?: number;
+  goEntry?: number;
+  name?: string;
+};
+
+export const ROUTE_EDIT_UNDO_CAP = 40;
+
+export function parseRouteEditNodes(raw: unknown): RouteEditNode[] {
+  if (!Array.isArray(raw)) return [];
+  return (raw as RouteEditNode[]).filter(
+    (n) => n && (n.kind === 'walk' || n.kind === 'use')
+      && Number.isFinite(n.x) && Number.isFinite(n.y),
+  );
+}
+
+export function cloneRouteEditNodes(nodes: readonly RouteEditNode[]): RouteEditNode[] {
+  return nodes.map((n) => ({ ...n }));
+}
+
+export function pushRouteEditUndo(stack: RouteEditNode[][], nodes: readonly RouteEditNode[]): void {
+  stack.push(cloneRouteEditNodes(nodes));
+  if (stack.length > ROUTE_EDIT_UNDO_CAP) stack.shift();
+}
+
+/** Splice `n` into the nearest drawn leg, or append when `forceAppend`. Returns the index. */
+export function insertRouteEditNode(
+  nodes: RouteEditNode[],
+  n: RouteEditNode,
+  forceAppend = false,
+): number {
+  const at = forceAppend ? nodes.length : routeInsertIndex(nodes, n);
+  nodes.splice(at, 0, n);
+  return at;
+}
+
+export function deleteRouteEditNode(nodes: RouteEditNode[], idx: number): boolean {
+  if (!Number.isFinite(idx) || idx < 0 || idx >= nodes.length) return false;
+  nodes.splice(idx, 1);
+  return true;
+}
+
+/**
+ * Remaining bosses, flag packs, unmet object gates — InstanceDef spine order.
+ * Geometric NN (live pack tour) is not the itinerary: it put BRD's vault doors
+ * after Roccor because the vault is 235 yd away and Gerstahn is 345 yd back.
+ */
+export function seedRouteFromPlan(def: InstanceDef, run: InstanceRun): RouteEditNode[] {
+  const gos = dungeonGameObjectsForMap(def.mapId);
+  const seenGate = new Set<number>();
+  const out: RouteEditNode[] = [];
+  for (const enc of def.encounters) {
+    if (isCleared(run, enc.id)) continue;
+    // Quest-started side content (Gor'shak) is not on the default itinerary.
+    if (enc.startQuestId) continue;
+    for (const ev of enc.events ?? []) {
+      if (ev.kind !== 'objectGate') continue;
+      if (ev.setsFlag && hasFlag(run, ev.setsFlag)) continue;
+      const entries = [ev.goEntry, ...(ev.goEntries ?? [])]
+        .filter((e): e is number => typeof e === 'number' && e > 0);
+      for (const goEntry of entries) {
+        if (seenGate.has(goEntry)) continue;
+        seenGate.add(goEntry);
+        const go = gos.find((g) => g.entry === goEntry);
+        if (!go) continue;
+        const un: RouteEditNode = { kind: 'use', goEntry, name: go.name, x: go.x, y: go.y };
+        if (Number.isFinite(go.z)) un.z = go.z;
+        out.push(un);
+      }
+    }
+    if (enc.kind !== 'boss' && flagsSetByEncounter(enc).length === 0) continue;
+    const w = worldPosForEncounter(def, run, enc.id);
+    if (!w) continue;
+    const n: RouteEditNode = { kind: 'walk', x: w.x, y: w.y, name: enc.name || enc.id };
+    if (w.z != null && Number.isFinite(w.z)) n.z = w.z;
+    out.push(n);
+  }
+  return out;
+}
+
+/**
+ * Route to ONE picked objective — the atlas pin the operator set before walking in.
+ *
+ * `seedRouteFromPlan` above is the whole dungeon in def order. This is the run the
+ * operator asked for: `objectiveItinerary` resolves the target's prerequisite graph
+ * (Baron Rivendare wants three ziggurats, nine abominations, Ramstein and the Black
+ * Guard gauntlet; Emberseer wants his seven rune rooms) and each stop still gets its
+ * unmet object gates as a ⚙ use-step in front of it. Ends ON the target — nothing
+ * behind it is on the itinerary.
+ *
+ * Empty when the target resolves to nothing walkable; callers fall back to the plan.
+ */
+export function objectiveRouteFor(
+  def: InstanceDef,
+  run: InstanceRun,
+  targetEncounterId: string,
+): RouteEditNode[] {
+  const gos = dungeonGameObjectsForMap(def.mapId);
+  const seenGate = new Set<number>();
+  const out: RouteEditNode[] = [];
+  for (const enc of objectiveItinerary(def, run, targetEncounterId)) {
+    if (isCleared(run, enc.id)) continue;
+    for (const ev of enc.events ?? []) {
+      if (ev.kind !== 'objectGate') continue;
+      if (ev.setsFlag && hasFlag(run, ev.setsFlag)) continue;
+      const entries = [ev.goEntry, ...(ev.goEntries ?? [])]
+        .filter((e): e is number => typeof e === 'number' && e > 0);
+      for (const goEntry of entries) {
+        if (seenGate.has(goEntry)) continue;
+        seenGate.add(goEntry);
+        const go = gos.find((g) => g.entry === goEntry);
+        if (!go) continue;
+        const un: RouteEditNode = { kind: 'use', goEntry, name: go.name, x: go.x, y: go.y };
+        if (Number.isFinite(go.z)) un.z = go.z;
+        out.push(un);
+      }
+    }
+    const w = worldPosForEncounter(def, run, enc.id);
+    if (!w) continue;
+    const n: RouteEditNode = { kind: 'walk', x: w.x, y: w.y, name: enc.name || enc.id };
+    if (w.z != null && Number.isFinite(w.z)) n.z = w.z;
+    out.push(n);
+  }
+  return out;
+}
+
+/** In-session Seed writes land here so Reset does not wait on a JSON HMR. */
+const authoredOverride: Record<string, RouteEditNode[]> = {};
+
+export function rememberAuthoredRoute(instanceId: string, nodes: readonly RouteEditNode[]): void {
+  authoredOverride[instanceId] = serializeRouteEditNodes(nodes);
+  // The itinerary is also the route ORDER (dungeonRouteOrder anchors), not just the drawn line.
+  setAuthoredRouteAnchors(
+    instanceId,
+    nodes.filter((n) => n.kind !== 'use' && n.name).map((n) => n.name!),
+  );
+}
+
+/** Shipped default for this instance, or [] if none has been Seeded yet. */
+export function authoredRouteFor(instanceId: string): RouteEditNode[] {
+  const over = authoredOverride[instanceId];
+  if (over?.length) return cloneRouteEditNodes(over);
+  const raw = (authoredRoutesJson as { routes?: Record<string, unknown> }).routes?.[instanceId];
+  return parseRouteEditNodes(raw ?? []);
+}
+
+// The route to walk. A picked atlas objective wins over both the shipped route and the whole-dungeon plan —
+// that pick IS the run the operator planned.
+export function defaultRouteFor(
+  def: InstanceDef,
+  run: InstanceRun,
+  targetEncounterId?: string | null,
+): RouteEditNode[] {
+  if (targetEncounterId) {
+    const toTarget = objectiveRouteFor(def, run, targetEncounterId);
+    if (toTarget.length) return toTarget;
+  }
+  const shipped = authoredRouteFor(def.id);
+  return shipped.length ? shipped : seedRouteFromPlan(def, run);
+}
+
+export function serializeRouteEditNodes(nodes: readonly RouteEditNode[]): RouteEditNode[] {
+  return nodes.map((n) => {
+    const o: RouteEditNode = { kind: n.kind, x: n.x, y: n.y };
+    if (n.z != null && Number.isFinite(n.z)) o.z = n.z;
+    if (n.goEntry != null && Number.isFinite(n.goEntry)) o.goEntry = n.goEntry;
+    if (n.name) o.name = n.name;
+    return o;
+  });
+}
+
+// Hand-edited routes survive. Unmarked storage takes the shipped default, else the plan
+// (probe-path-editor-authoring: a stale 45-step seed without the flag is disposable).
+export function resolveRouteLoad(
+  stored: readonly RouteEditNode[],
+  handEdited: boolean,
+  def: InstanceDef,
+  run: InstanceRun,
+  targetEncounterId?: string | null,
+): { nodes: RouteEditNode[]; seeded: boolean } {
+  // An atlas pick outranks a hand-edited route: the operator just said, on the pre-run
+  // screen, where this run goes. A stale stored path is not that answer.
+  if (targetEncounterId) {
+    const toTarget = objectiveRouteFor(def, run, targetEncounterId);
+    if (toTarget.length) return { nodes: toTarget, seeded: true };
+  }
+  if (handEdited) return { nodes: cloneRouteEditNodes(stored), seeded: false };
+  return { nodes: defaultRouteFor(def, run), seeded: true };
+}